@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 — ゲートと漏洩ガードは各サイトではなくプラットフォームのもの: 各リポジトリが再実装する保護は、一部のリポジトリが持たない保護です。

• spec 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 で実行されるためです。同じ理由で、パッケージには 単一の依存関係（検索エンジンが必要とする 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';
export const { handler, default: fetchHandler } = crearMcp({
  config,
  indice,
  crearIssue: crearFeedback(config.feedback),
});

// middleware.js — en la RAÍZ del repo (Vercel lo exige ahí)
import { next } from '@vercel/functions';
import { decidir } from '@ingadhoc/docs-platform/gate';
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で終了したときにデプロイを中止するものです。; に変更しないでください。

エクスポート内容

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 をインストールする前に、 その行を修正する価値があります。