@ingadhoc/docs-platform

Adhoc のドキュメントプラットフォーム: 1つの検索エンジン、1つの MCP コア、1つのアクセスゲート、1つの漏洩ガード。これらは コンテンツリポジトリ (oba-docs、odumbo-docs、adhoc-docs) によって ピン留めされて消費されます。

これ以前は、4つの部品が3つのリポジトリにフォークされていました: 同じファイルが 3つの方言を持ち、各修正は手動で伝播されるか、あるいは伝播されませんでした。 測定は docs/unificacion/ にあります: lib/mcp/indice.mjs は3つのコピー間で 41の差分があり、17はあるリポジトリが持っていて他の2つが持っていない修正でした。 最もコストがかかったケース: 漏洩ガードは2つのリポジトリでバイト単位で同一であり、 3つ目には存在しませんでした。

• knowledge-management の ADR 0006 — コンテンツ本文ごとに1つのリポジトリ、そして プラットフォームは別のパッケージとして: コンテンツとエンジンは異なるライフサイクルと 異なる所有者を持ちます。

• knowledge-management の ADR 0007 — ゲートと漏洩ガードはプラットフォームのものであり、 各サイトのものではありません: 各リポジトリが再実装する保護は、 一部のリポジトリが持っていない保護です。

• arquitectura-plataforma-docs 仕様のステージ A: このパッケージは、2つのバージョン管理された コントラクトと、ピンの遅延を可視化するドリフトチェックを備えています。

消費方法

npm i --ignore-scripts github:ingadhoc/doc-platform#v0.1.0

正確なピン、常にタグで。 ^ も main もブランチもなし: ピンは、 プラットフォームの修正が同時に3つのサイトを壊すのを防ぎ、1行でのロールバックを可能にします。 範囲を指定すると、docs-drift-check が意図的に失敗します — ピン留めしないピンはピンではありません。

--ignore-scripts 推奨。 このパッケージにはインストールスクリプトはなく、 今後も追加される予定はありません。このフラグはツリー全体のためのもので、 これは公開サイトの buildCommand で実行されるためです。同じ理由で、 このパッケージには依存関係が1つだけ (minisearch、検索エンジンが必要とするもの) あり、 devDependencies はゼロです: ビルドでの表面積を最小限にします。

コンシューマーがすでに持っていて、このパッケージが宣言しないもの: mcp-handler と zod。これらは lib/mcp/mcp-handler.mjs がインポートします。これらはリポジトリの依存関係であり、 意図的です: リポジトリがどのバージョンの MCP フレームワークでデプロイするかを決定し、 パッケージはそれを強制しません。3つのリポジトリは現在これらを持っています。

npm i の後、コンシューマーリポジトリには3行の接着コードが残ります:

// api/mcp.mjs
import { crearMcp } from '@ingadhoc/docs-platform/mcp-handler';
import { crearFeedback } from '@ingadhoc/docs-platform/feedback';
import * as indice from '@ingadhoc/docs-platform/indice';
import { config } from '../docs.mcp.config.mjs';
const { handler } = crearMcp({
  config,
  indice,
  crearIssue: crearFeedback(config.feedback),
});
export default handler; // sin default export Vercel no encuentra el handler

// middleware.js — en la RAÍZ del repo (Vercel lo exige ahí)
import { next } from '@vercel/functions';
// Por RUTA RELATIVA, no por especificador de paquete: el bundler del edge
// rechaza `@ingadhoc/docs-platform/gate` cuando el repo consumidor no es
// `"type": "module"` (Docusaurus lo impide) — "unsupported modules".
// Y ojo con renombrar a middleware.mjs: el deploy queda VERDE y SIN
// middleware (la ausencia silenciosa del gate). Hallazgo del piloto
// odumbo-docs, deployment 3mXWLwPHPgcwasEji49pGEg7Lyuv.
import { decidir } from './node_modules/@ingadhoc/docs-platform/lib/mcp/gate.mjs';
const AUDIENCIAS = ['publico', 'interno']; // adhoc-docs: ['interno']
export default function middleware(request) {
  return decidir(request, process.env, { audiencias: AUDIENCIAS }) ?? next();
}

// package.json del consumidor — el guard, dentro del buildCommand
"build:publico": "node tools/build.mjs --audience=publico && npm --prefix site run build && npx docs-guard-fuga --salida=dist/publico"

&& は装飾ではありません: ガードが1で終了したときにデプロイを中止するものです。 ; に変更しないでください。

Related MCP server: docrag

エクスポート内容

2つのコントラクト

両方とも schemaVersion を持ち、両方のリーダーは、発行者が自分たちが読めるバージョンより 新しいバージョンを宣言した場合、または宣言しなかった場合に例外をスローします。 静かに劣化することはありません: 間違って応答するインデックスは、応答しないインデックスより悪いです。

1. config ↔ プラットフォーム: docs.config.json。スキーマは schema/docs.config.schema.json で公開され、 バリデーターは lib/config.mjs (独自、依存関係なし: ajv は公開サイトのビルドには入りません)。 各フィールドの設計と測定された証拠は docs/unificacion/diseno-eje.md にあり、 現在の3つの config の翻訳は mapeo-configs.md にあります。

2. インデックス ↔ エンジン: 各リポジトリの tools/build.mjs が生成し、 lib/mcp/indice.mjs が読み取ります。これは docs/unificacion/contrato-indice.md で仕様化されています。

軸、表で

コーパスは1つの軸をオブジェクトとして宣言します: { tipo, default?, valores[] }。

leer() のルールは1つであり、軸のタイプごとの if はありません: config が誰を選ぶかを 宣言した場合にのみ選択します。動作を変えるのは eje.default の存在であり、タイプではありません — そして、軸 project のコーパスに default を設定してそれをテストするテストがあります。

テストの実行

npm install && npm test        # 227 casos

bloques はコンテンツリポジトリを必要とし (インシデントのフィクスチャに対して実際の tools/build.mjs を実行します)、存在しない場合は理由付きでスキップされます:

DOCS_REPO=~/repositorios/oba-docs node --test tests/bloques.test.mjs

mcp.test.mjs の HTTP ハンドラーの部分 (16ケース) も、チェックアウトに mcp-handler/zod が ない場合は理由付きでスキップされます。これらはコンシューマーの依存関係であり、このパッケージの ものではありません。両方がインストールされている場合、mcp は57になります。 ケーパビリティのないケースは明示的にスキップされます; 劣化して実行されることはありません。

jjs 向け — 未解決の決定

このアセンブリが単独では解決しないこと。最初の3つは diseno-eje.md §7 のもので、 コントラクトに関わります; 残りは4つの分析から出てきて、統合後も存続しています。

1. コーパスごとに1つの軸: 上限を受け入れますか?

schemaVersion: 1 は config ごとに1つの軸を許可し、現在は3つのリポジトリで十分です。 コーパスが project × version を同時に必要とする日には、スキーマはそれを表現できず、 出力は ejes: [...] (複数形) を持つ schemaVersion: 2 になります。 設計の推奨: 上限を明示的に受け入れ、実際のニーズが証拠を持ってそれを再開させる (ステージ B のバンプアラームと同じ基準)。これはメジャーに関わるため、あなたの判断です。

2. metadata.types: コーパスごとの語彙か、Adhoc 全体の語彙か?

現在、types を持っているのは adhoc-docs だけで、その6つの値は knowledge-management の 標準 (concepto、referencia、procedimiento、troubleshooting、guia、indice) に 非常に似ています。語彙が Adhoc のものであれば、各リポジトリの config には入らず、 パッケージに入り、config はそれを要求するかどうかのみを指定します。これはスキーマの決定ではなく、 コンテンツガバナンスの決定です; 裁定が下されるまで、スキーマはそれをコーパスごとのリストとして 残します (両方の出力と互換性があります)。

3. adhoc-docs の漏洩ガードのオプトアウト: 署名しますか?

スキーマは deploy.guardDeFuga の宣言を必須にしているため、黙って省略することは もはや不可能です。2つの出力が残り、どちらも擁護可能です: {"activo": false, "motivo": "…"} (そのリポジトリには公開ビルドがありません: そのゲートは 無条件であり、ガードは公開ビルドへの漏洩を防ぎます)、またはガードをベルトとして そのまま入れる。現在 mapeo-configs.md にある motivo は文字通り "PENDIENTE DE FIRMA (jjs)" と書かれています。

そして、ファイルをコピーしても解決しない技術的な部分があります (analisis-04-seguridad.md の DUDA 1): adhoc-docs には :::interno ブロックがなく、オーディエンス付きの site/generated.json を生成せず、deploy.proyectos マップもありません。 ガードをそのまま有効にすると、ビルドは "site/generated.json が存在しない" で最初から失敗します。 厳密な方法は、それらの2つを生成することです。

4. オーディエンスのリストはまだ重複しており、ドリフトチェックはまだそれを比較していません

docs.config.json → audiences と middleware.js → AUDIENCIAS は一致する必要があり、 重複を避ける方法はありません: エッジはファイルシステムから読み取りません。 これは、フォークが始まったまさにその種の静かなドリフトです。 それらを比較する CI ケースが欠けています (現在の docs-drift-check はピンを測定しており、 その一貫性は測定していません)。

5. タグを打つ前にリポジトリで確認すべき3つのこと

• Vercel の各プロジェクトの3つの環境 (Production、Preview、Development) の DOCS_AUDIENCE パッケージを採用するマージの前に。フェイルクローズドでは、変数のないプロジェクトは 503を返します。これは安全な方向ですが、無料ではありません。

• 現在の buildCommand の --esperada: 現在、ガードは Vercel で実行されることを 拒否します。今日それを渡す buildCommand がある場合、そのデプロイは失敗し始めます。 スナップショットからは検証できませんでした。

• MCP の GET は、デプロイメントが提供可能なオーディエンスを宣言していない場合、503を返します。 これはコンシューマーにとって観察可能な変更です: Claude Code のプリフライトは、 デプロイメントが誤って設定されている場合、バナーではなく503を受け取ります。

6. このパッケージが閉じることができない測定された負債

• プリプロセッサのフェイルクローズは出力してから失敗する。 誤ったディレクティブ（::: interno）があると、build.mjs は内部の行を含む site/docs/** を書き出し、その後 に終了コード1で終了する。現在は漏れないのは、buildCommand が && で連結しているからだ。保護は演算子側にあり、プログラム側にはない。これは tests/bloques.test.mjs で todo として宣言されており、build.mjs の統合で修正される予定だが、この段階では入っていない。

• tests/bloques.test.mjs は <repo>/site/ に書き込む。oba と odumbo ではビルド出力がハードコードされているためだ。スイートを実行した後は、npm run gen で再生成する必要がある。

• ガードの字句的アプローチの限界: 5文字未満の数字や文字列には決してプローブが付かない（キー 4821、頭字語など）。画像はスキャンされず、applyBlocks 内の漏れはプローブを生成しない。これはガードのヘッダーに記載されている。ここで繰り返すのは、カバレッジと混同される可能性がある部分だからだ。

• serverInfo.version はハンドラー内で '1.0.0' にハードコードされたまま。これはピン留めされたパッケージの package.json から取得すべきで、そうすれば MCP クライアントはどのバージョンのプラットフォームと通信したかを報告できる。変更されていないのは、動作を発明することになるからだ。

• ワイルドカードは軸の tipo のプロパティであり、コーパスのプロパティではない。 軸が project のコーパスは、横断的なドキュメント（eje: null）を持つことができない。これはどのフィルターからも見えない。将来必要になった場合、厳密な出力は、ワイルドカードがオフの間はインデックスの契約がそれを禁止し、矛盾がランタイムではなくビルドで失敗するようにすることだ。

• 仕様は「vitest」と書かれているが、これはステージAのテスト規約であり、3つのリポジトリのどれも vitest を使用していない。実際の規約（このパッケージの規約も）はネイティブの node:test だ。誰かがそれを満たすために vitest をインストールする前に、その行を修正する価値がある。