@ingadhoc/docs-platform

Adhoc 문서 플랫폼: 하나의 검색 엔진, 하나의 MCP 코어, 하나의 액세스 게이트, 하나의 유출 가드, 콘텐츠 저장소(oba-docs, odumbo-docs, adhoc-docs)가 핀으로 고정하여 소비합니다.

이 전에는 네 조각이 세 저장소에 포크되어 있었습니다: 같은 파일이 세 가지 방언으로, 각 수정은 수동으로 전파되거나 — 전파되지 않았습니다. 측정은 docs/unificacion/에 있습니다: lib/mcp/indice.mjs는 세 복사본 사이에 41개의 차이가 있었고, 17개는 한 저장소에는 있고 다른 두 저장소에는 없는 수정이었습니다. 가장 비용이 큰 경우: 유출 가드는 두 저장소에서 바이트 단위로 동일했고 세 번째에는 존재하지 않았습니다.

• ADR 0006 of knowledge-management — 콘텐츠 본문당 하나의 저장소, 그리고 플랫폼은 별도 패키지로: 콘텐츠와 엔진은 수명 주기와 소유자가 다릅니다.

• ADR 0007 of knowledge-management — 게이트와 유출 가드는 플랫폼의 것이지 각 사이트의 것이 아닙니다: 각 저장소가 다시 구현하는 보호는 어떤 저장소에는 없는 보호입니다.

• spec arquitectura-plataforma-docs의 A 단계: 이 패키지, 두 개의 버전 관리된 계약과 핀의 지연을 보이게 하는 drift-check.

소비 방법

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

정확한 핀, 항상 태그로. ^ 없음, main 없음, 브랜치 없음: 핀은 플랫폼의 수정이 동시에 세 사이트를 깨뜨리는 것을 막고, 한 줄의 롤백을 가능하게 합니다. 범위는 의도적으로 docs-drift-check를 실패시킵니다 — 핀하지 않는 핀은 핀이 아닙니다.

--ignore-scripts 권장. 이 패키지에는 install 스크립트가 없으며 앞으로도 없을 것입니다; 이 플래그는 전체 트리를 위한 것입니다. 왜냐하면 이것은 공개 사이트의 buildCommand에서 실행되기 때문입니다. 패키지에 단 하나의 의존성(minisearch, 검색 엔진이 필요로 하는)과 devDependencies 0개가 있는 것도 같은 이유입니다: 빌드에서 최소 표면.

소비자가 이미 가지고 있고 이 패키지가 선언하지 않는 것: mcp-handler와 zod, lib/mcp/mcp-handler.mjs가 import합니다. 이들은 의도적으로 저장소의 의존성입니다: 저장소가 어떤 MCP 프레임워크 버전으로 배포할지 결정하고, 패키지는 강제하지 않습니다. 세 저장소 모두 오늘 그것들을 가지고 있습니다.

npm i 후, 소비 저장소에는 세 줄의 접착제가 남습니다:

// 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로 종료될 때 배포를 중단시키는 것입니다. ;로 바꾸지 마세요.

내보내는 것

두 계약

둘 다 schemaVersion을 가지며, 두 리더는 발신자가 읽을 수 있는 버전보다 더 새로운 버전을 선언하거나 — 선언하지 않으면 던집니다. 조용히 저하시키는 것은 없습니다: 잘못 응답하는 잘못된 인덱스는 응답하지 않는 것보다 나쁩니다.

1. config ↔ 플랫폼: docs.config.json, 스키마는 schema/docs.config.schema.json에 게시되고 검증기는 lib/config.mjs에 있습니다 (자체, 의존성 없음: ajv는 공개 사이트 빌드에 들어가지 않습니다). 각 필드의 설계와 측정된 증거는 docs/unificacion/diseno-eje.md에 있습니다; 현재 세 config의 번역은 mapeo-configs.md에 있습니다.

2. 인덱스 ↔ 엔진: 각 저장소의 tools/build.mjs가 생성하고 lib/mcp/indice.mjs가 읽습니다. docs/unificacion/contrato-indice.md에 명시되어 있습니다.

축, 표로

코퍼스는 하나의 축을 객체로 선언합니다: { tipo, default?, valores[] }.

leer()의 규칙은 하나이며 축 유형별 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을 줍니다. capability가 없는 사례는 명시적으로 건너뜁니다; 저하된 상태로 실행되지 않습니다.

jjs를 위한 — 열린 결정

이 어셈블리가 스스로 해결하지 못하는 것. 처음 세 개는 diseno-eje.md §7에서 나왔고 계약을 위태롭게 합니다; 나머지는 네 가지 분석에서 나왔고 통일 후에도 여전히 살아 있습니다.

1. 코퍼스당 하나의 축: 한계를 수용하나요?

schemaVersion: 1은 config당 하나의 축을 허용하며, 오늘은 세 저장소에 충분합니다. 코퍼스가 동시에 project × version을 필요로 하는 날, 스키마는 그것을 표현하지 못하고 출력은 ejes: [...](복수)를 가진 schemaVersion: 2입니다. 설계 권장: 한계를 명시적으로 수용하고 실제 필요가 증거와 함께 다시 열게 하십시오 (B 단계의 bump 알람과 같은 기준). major를 위태롭게 하므로 당신의 결정입니다.

2. metadata.types: 코퍼스별 어휘인가 Adhoc 고유인가?

오늘은 adhoc-docs만 types를 가지며, 그 6개 값은 knowledge-management의 표준과 매우 비슷합니다 (concepto, referencia, procedimiento, troubleshooting, guia, indice). 어휘가 Adhoc의 것이라면 각 저장소의 config에 들어가지 않습니다: 패키지에 들어가고, config는 그것을 요구하는지 여부만 말합니다. 이것은 스키마가 아닌 콘텐츠 거버넌스 결정입니다; 판결이 내려질 때까지 스키마는 그것을 코퍼스별 목록으로 남겨둡니다 (두 출력 모두와 호환).

3. adhoc-docs의 유출 가드 옵트아웃: 서명하시나요?

스키마는 deploy.guardDeFuga를 선언하도록 강제하므로 조용한 생략은 더 이상 불가능합니다. 두 가지 출력이 남아 있고, 둘 다 방어 가능합니다: {"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이 존재하지 않음"으로 시작부터 실패합니다. 엄격한 방법은 그 두 가지를 생성하는 것입니다.

4. 청중 목록은 여전히 중복되어 있고, drift-check는 아직 그것을 비교하지 않습니다

docs.config.json → audiences와 middleware.js → AUDIENCIAS는 일치해야 하며, 중복을 피할 방법이 없습니다: 엣지는 파일시스템에서 읽지 않습니다. 이것은 포크가 시작된 조용한 드리프트의 정확한 유형입니다. 그것들을 비교하는 CI 사례가 빠져 있습니다 (오늘의 docs-drift-check는 핀을 측정하지 그 일관성을 측정하지 않습니다).

5. 태그를 달기 전에 저장소에서 확인해야 할 세 가지

• 각 Vercel 프로젝트의 세 환경(Production, Preview, Development)에 DOCS_AUDIENCE 패키지를 채택하는 merge 전에. fail-closed로 인해 변수가 없는 프로젝트는 503을 반환합니다. 안전한 방향이지만 공짜는 아닙니다.

• 현재 buildCommand의 --esperada: 이제 가드는 Vercel에서 실행되는 것을 거부합니다. 오늘 어떤 buildCommand가 그것을 전달하면 그 배포는 실패하기 시작합니다. 스냅샷에서 확인할 수 없었습니다.

• MCP의 GET은 503을 반환합니다 배포가 서빙 가능한 청중을 선언하지 않으면. 소비자에게 관찰 가능한 변화입니다: 배포가 잘못 구성되면 Claude Code의 사전 점검은 안내판 대신 503을 받습니다.

6. 이 패키지가 닫을 수 없는 측정된 부채

• 전처리기의 fail-closed는 출력한 후에 실패한다. 잘못 작성된 지시문(::: 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"를 말한다 Etapa A의 테스트 관례로, 세 저장소 중 어느 것도 vitest를 사용하지 않는다. 실제 관례 —그리고 이 패키지의 관례—는 네이티브 node:test이다. 누군가 이를 충족시키기 위해 vitest를 설치하기 전에 그 줄을 수정하는 것이 좋다.