@agent-teams/docs-protocol 0.3.1 → 0.4.0

package/dist/community/bootstrap/portable-bootstrap-assets.js

@@ -0,0 +1,183 @@
+const MAXIMUM_BOOTSTRAP_FILES = 32;
+const SKILL_PATH = ".agents/skills/docs-authoring/SKILL.md";
+export const PORTABLE_BOOTSTRAP_BEGIN_MARKER = "<!-- agent-teams:portable-docs:start -->";
+export const PORTABLE_BOOTSTRAP_END_MARKER = "<!-- agent-teams:portable-docs:end -->";
+function yamlScalar(value) {
+    return JSON.stringify(value);
+}
+function docsConfig() {
+    return `schemaVersion: 3
+protocol: {id: agent-teams.docs-protocol, version: 1}
+foundationProfile:
+  path: .docs-protocol/document-authoring.yaml
+  schemaVersion: 3
+  metadataSidecarPolicy: foundation-profile-v3-strict-merge
+agentWorkflow:
+  skillPath: ${SKILL_PATH}
+  adoption: portable-v1
+semanticValidatorIds: []
+`;
+}
+function artifactType(input) {
+    const reachability = input.type === "adr"
+        ? "{kind: manual-fixed-index, indexPath: docs/decisions/README.md}"
+        : "{kind: not-required, reason: Deterministic catalog and context projection provide reachability without duplicating manual indexes.}";
+    const heading = input.type === "adr" ? "id-colon-title" : "title";
+    return `    - type: ${input.type}
+      initialStatus: proposed
+      identity: ${input.identity}
+      placement: {kind: collection, directory: ${input.directory}, filename: ${input.type === "adr" ? "numeric-id-slug" : "slug"}}
+      template: {kind: fenced-markdown-body, path: .docs-protocol/templates/${input.template}.md}
+      heading: {kind: ${heading}}
+      reachability: ${reachability}
+      ownerSetId: documentation
+`;
+}
+function documentAuthoringProfile(projectId, ownerId) {
+    return `schemaVersion: 3
+projectId: ${yamlScalar(projectId)}
+catalog:
+  metadataSchemaPath: .docs-protocol/metadata.schema.json
+  ownerCatalog: {path: .docs-protocol/owners.yaml, contract: foundation.owner-map/v1}
+  collections:
+    - {kind: markdown-tree, root: docs}
+  excludedPrefixes: [.docs-protocol]
+authoring:
+  mode: create-only
+  ownerSets:
+    schemaVersion: 1
+    sets:
+      documentation: [${yamlScalar(ownerId)}]
+  artifactTypes:
+${artifactType({ type: "adr", directory: "docs/decisions", template: "adr", identity: "{kind: explicit, format: adr-four-digits}" })}${artifactType({ type: "tutorial", directory: "docs/tutorials", template: "tutorial", identity: "{kind: explicit, format: qualified, grammar: {prefixSegments: [docs, tutorial], minSuffixSegments: 1, maxSuffixSegments: 16}}" })}${artifactType({ type: "how-to", directory: "docs/how-to", template: "how-to", identity: "{kind: explicit, format: qualified, grammar: {prefixSegments: [docs, how-to], minSuffixSegments: 1, maxSuffixSegments: 16}}" })}${artifactType({ type: "reference", directory: "docs/reference", template: "reference", identity: "{kind: explicit, format: qualified, grammar: {prefixSegments: [docs, reference], minSuffixSegments: 1, maxSuffixSegments: 16}}" })}${artifactType({ type: "explanation", directory: "docs/explanation", template: "explanation", identity: "{kind: explicit, format: qualified, grammar: {prefixSegments: [docs, explanation], minSuffixSegments: 1, maxSuffixSegments: 16}}" })}`;
+}
+function metadataSchema(ownerId) {
+    const commonStatuses = ["proposed", "active", "deprecated", "superseded"];
+    const nonAdrTypes = ["tutorial", "how-to", "reference", "explanation", "index"];
+    return `${JSON.stringify({
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        type: "object",
+        additionalProperties: false,
+        required: ["id", "type", "status", "owner", "summary"],
+        properties: {
+            id: { type: "string", minLength: 1, maxLength: 214 },
+            type: { enum: ["adr", "tutorial", "how-to", "reference", "explanation", "index"] },
+            status: { type: "string" },
+            owner: { const: ownerId },
+            summary: { type: "string", minLength: 1, maxLength: 500 },
+            related: { type: "array", uniqueItems: true, items: { type: "string" } },
+            blocked_by: { type: "array", uniqueItems: true, items: { type: "string" } },
+            code_anchors: { type: "array", uniqueItems: true, items: { type: "object" } }
+        },
+        oneOf: [{
+                type: "object",
+                required: ["type", "status"],
+                properties: {
+                    type: { const: "adr" },
+                    status: { enum: [...commonStatuses, "accepted"] }
+                }
+            }, {
+                type: "object",
+                required: ["type", "status"],
+                properties: {
+                    type: { enum: nonAdrTypes },
+                    status: { enum: commonStatuses }
+                }
+            }]
+    }, undefined, 2)}\n`;
+}
+function template(type, title, sections) {
+    return `\`\`\`\`markdown
+---
+id: REPLACE_ME
+type: ${type}
+status: proposed
+owner: REPLACE_ME
+summary: REPLACE_ME
+---
+
+# ${title}
+
+${sections.map((section) => `## ${section}\n\nREPLACE_ME`).join("\n\n")}
+\`\`\`\`
+`;
+}
+function indexReadme(input) {
+    return `---
+id: ${input.id}
+type: index
+status: active
+owner: ${yamlScalar(input.ownerId)}
+summary: ${input.description}
+---
+
+# ${input.title}
+
+${input.description}
+
+This index describes the category. The deterministic documentation catalog is the source for document discovery, so this file does not duplicate a hand-maintained document list.
+`;
+}
+function skill() {
+    return `---
+name: docs-authoring
+description: Create and maintain repository documentation using the portable Docs Protocol layout.
+---
+
+# Documentation authoring
+
+Protocol declaration: agent-teams.docs-protocol/v1.
+
+Read \`docs.config.yaml\` and the local authority files before changing documentation.
+Choose the Diataxis category matching the reader's need, or use an ADR for a durable decision.
+
+1. Discover existing material with \`docs-protocol find --consumer . --profile docs.config.yaml --text QUERY\`.
+2. Preview creation with \`docs-protocol new --consumer . --profile docs.config.yaml --type TYPE --id ID --title "TITLE" --owner OWNER_ID --summary "SUMMARY" --dry-run\`.
+3. Apply the reviewed intent with \`docs-protocol new --consumer . --profile docs.config.yaml --type TYPE --id ID --title "TITLE" --owner OWNER_ID --summary "SUMMARY" --apply\`.
+4. If the result is \`manual-required\`, add its exact \`markdownLink\` to its exact \`indexPath\` before verification.
+5. Refresh bounded agent context with \`docs-protocol context --consumer . --profile docs.config.yaml\`.
+6. Verify authorities and documents with \`docs-protocol check --consumer . --profile docs.config.yaml\`.
+
+Start from the matching template in \`.docs-protocol/templates\` and replace every placeholder.
+Keep metadata valid against \`.docs-protocol/metadata.schema.json\` and select a declared owner.
+Create files only and never overwrite an existing document for a new-document request.
+Do not assume a package manager, hosting provider, or repository forge.
+`;
+}
+export function portableBootstrapManagedBlock(eol) {
+    return [
+        PORTABLE_BOOTSTRAP_BEGIN_MARKER,
+        `Use [${SKILL_PATH}](${SKILL_PATH}) for documentation.`,
+        PORTABLE_BOOTSTRAP_END_MARKER
+    ].join(eol);
+}
+export function portableBootstrapDesiredFiles(projectId, ownerId) {
+    const textFiles = [
+        ["docs.config.yaml", docsConfig()],
+        [".docs-protocol/document-authoring.yaml", documentAuthoringProfile(projectId, ownerId)],
+        [".docs-protocol/metadata.schema.json", metadataSchema(ownerId)],
+        [".docs-protocol/owners.yaml", `version: 1\nowners:\n  ${yamlScalar(ownerId)}:\n    kind: documentation\n`],
+        [".docs-protocol/templates/adr.md", template("adr", "ADR-NNNN: Decision title", ["Context", "Decision", "Consequences"])],
+        [".docs-protocol/templates/tutorial.md", template("tutorial", "Tutorial title", ["Goal", "Prerequisites", "Steps", "Next steps"])],
+        [".docs-protocol/templates/how-to.md", template("how-to", "How to achieve a goal", ["Before you begin", "Procedure", "Verification"])],
+        [".docs-protocol/templates/reference.md", template("reference", "Reference title", ["Overview", "Contract", "Examples"])],
+        [".docs-protocol/templates/explanation.md", template("explanation", "Explanation title", ["Context", "Concept", "Trade-offs"])],
+        ["docs/README.md", indexReadme({ id: "docs.index", ownerId, title: "Documentation", description: "Use tutorials to learn, how-to guides to complete tasks, reference for exact facts, explanations for understanding, and decision records for architectural choices." })],
+        ["docs/decisions/README.md", indexReadme({ id: "docs.decisions.index", ownerId, title: "Architecture decisions", description: "MADR-compatible decision records capture durable architectural choices, their context, and their consequences." })],
+        ["docs/tutorials/README.md", indexReadme({ id: "docs.tutorials.index", ownerId, title: "Tutorials", description: "Tutorials are learning-oriented lessons that guide a reader to a successful first result." })],
+        ["docs/how-to/README.md", indexReadme({ id: "docs.how-to.index", ownerId, title: "How-to guides", description: "How-to guides are goal-oriented procedures for readers who already understand the basics." })],
+        ["docs/reference/README.md", indexReadme({ id: "docs.reference.index", ownerId, title: "Reference", description: "Reference documentation is precise, complete, and organized for lookup." })],
+        ["docs/explanation/README.md", indexReadme({ id: "docs.explanation.index", ownerId, title: "Explanation", description: "Explanations build understanding by describing concepts, context, and trade-offs." })],
+        [SKILL_PATH, skill()]
+    ];
+    const files = textFiles.map(([path, source]) => Object.freeze({
+        path,
+        ownership: "create-only",
+        bytes: Buffer.from(source, "utf8")
+    }));
+    if (files.length + 1 > MAXIMUM_BOOTSTRAP_FILES) {
+        throw new TypeError(`Portable bootstrap exceeds ${MAXIMUM_BOOTSTRAP_FILES} files.`);
+    }
+    return Object.freeze(files);
+}
+//# sourceMappingURL=portable-bootstrap-assets.js.map

package/dist/community/bootstrap/portable-bootstrap-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-bootstrap-assets.js","sourceRoot":"","sources":["../../../src/community/bootstrap/portable-bootstrap-assets.ts"],"names":[],"mappings":"AAAA,MAAM,uBAAuB,GAAG,EAAE,CAAC;AACnC,MAAM,UAAU,GAAG,wCAAwC,CAAC;AAE5D,MAAM,CAAC,MAAM,+BAA+B,GAAG,0CAA0C,CAAC;AAC1F,MAAM,CAAC,MAAM,6BAA6B,GAAG,wCAAwC,CAAC;AAQtF,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,UAAU;IACjB,OAAO;;;;;;;eAOM,UAAU;;;CAGxB,CAAC;AACF,CAAC;AAED,SAAS,YAAY,CAAC,KAKrB;IACC,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK;QACvC,CAAC,CAAC,iEAAiE;QACnE,CAAC,CAAC,qIAAqI,CAAC;IAC1I,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC;IAClE,OAAO,eAAe,KAAK,CAAC,IAAI;;kBAEhB,KAAK,CAAC,QAAQ;iDACiB,KAAK,CAAC,SAAS,eAAe,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM;8EAClD,KAAK,CAAC,QAAQ;wBACpE,OAAO;sBACT,YAAY;;CAEjC,CAAC;AACF,CAAC;AAED,SAAS,wBAAwB,CAAC,SAAiB,EAAE,OAAe;IAClE,OAAO;aACI,UAAU,CAAC,SAAS,CAAC;;;;;;;;;;;;wBAYV,UAAU,CAAC,OAAO,CAAC;;EAEzC,YAAY,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,2CAA2C,EAAE,CAAC,GAAG,YAAY,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,+HAA+H,EAAE,CAAC,GAAG,YAAY,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,6HAA6H,EAAE,CAAC,GAAG,YAAY,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,gBAAgB,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,gIAAgI,EAAE,CAAC,GAAG,YAAY,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,kBAAkB,EAAE,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,kIAAkI,EAAE,CAAC,EAAE,CAAC;AACxhC,CAAC;AAED,SAAS,cAAc,CAAC,OAAe;IACrC,MAAM,cAAc,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC;IAC1E,MAAM,WAAW,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;IAChF,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;QACvB,OAAO,EAAE,8CAA8C;QACvD,IAAI,EAAE,QAAQ;QACd,oBAAoB,EAAE,KAAK;QAC3B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAC;QACtD,UAAU,EAAE;YACV,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE;YACpD,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE;YAClF,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC1B,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE;YACzB,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE;YACzD,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;YACxE,UAAU,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;YAC3E,YAAY,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;SAC9E;QACD,KAAK,EAAE,CAAC;gBACN,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;gBAC5B,UAAU,EAAE;oBACV,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;oBACtB,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,GAAG,cAAc,EAAE,UAAU,CAAC,EAAE;iBAClD;aACF,EAAE;gBACD,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;gBAC5B,UAAU,EAAE;oBACV,IAAI,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE;oBAC3B,MAAM,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE;iBACjC;aACF,CAAC;KACH,EAAE,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC;AACvB,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY,EAAE,KAAa,EAAE,QAA2B;IACxE,OAAO;;;QAGD,IAAI;;;;;;IAMR,KAAK;;EAEP,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;;CAEtE,CAAC;AACF,CAAC;AAED,SAAS,WAAW,CAAC,KAKpB;IACC,OAAO;MACH,KAAK,CAAC,EAAE;;;SAGL,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC;WACvB,KAAK,CAAC,WAAW;;;IAGxB,KAAK,CAAC,KAAK;;EAEb,KAAK,CAAC,WAAW;;;CAGlB,CAAC;AACF,CAAC;AAED,SAAS,KAAK;IACZ,OAAO;;;;;;;;;;;;;;;;;;;;;;;CAuBR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,6BAA6B,CAAC,GAAW;IACvD,OAAO;QACL,+BAA+B;QAC/B,QAAQ,UAAU,KAAK,UAAU,sBAAsB;QACvD,6BAA6B;KAC9B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,SAAiB,EACjB,OAAe;IAEf,MAAM,SAAS,GAAgC;QAC7C,CAAC,kBAAkB,EAAE,UAAU,EAAE,CAAC;QAClC,CAAC,wCAAwC,EAAE,wBAAwB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACxF,CAAC,qCAAqC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;QAChE,CAAC,4BAA4B,EAAE,0BAA0B,UAAU,CAAC,OAAO,CAAC,8BAA8B,CAAC;QAC3G,CAAC,iCAAiC,EAAE,QAAQ,CAAC,KAAK,EAAE,0BAA0B,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;QACzH,CAAC,sCAAsC,EAAE,QAAQ,CAAC,UAAU,EAAE,gBAAgB,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;QAClI,CAAC,oCAAoC,EAAE,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,EAAE,CAAC,kBAAkB,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC;QACtI,CAAC,uCAAuC,EAAE,QAAQ,CAAC,WAAW,EAAE,iBAAiB,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;QACzH,CAAC,yCAAyC,EAAE,QAAQ,CAAC,aAAa,EAAE,mBAAmB,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;QAC/H,CAAC,gBAAgB,EAAE,WAAW,CAAC,EAAE,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,qKAAqK,EAAE,CAAC,CAAC;QAC1Q,CAAC,0BAA0B,EAAE,WAAW,CAAC,EAAE,EAAE,EAAE,sBAAsB,EAAE,OAAO,EAAE,KAAK,EAAE,wBAAwB,EAAE,WAAW,EAAE,gHAAgH,EAAE,CAAC,CAAC;QAClP,CAAC,0BAA0B,EAAE,WAAW,CAAC,EAAE,EAAE,EAAE,sBAAsB,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,2FAA2F,EAAE,CAAC,CAAC;QAChN,CAAC,uBAAuB,EAAE,WAAW,CAAC,EAAE,EAAE,EAAE,mBAAmB,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,2FAA2F,EAAE,CAAC,CAAC;QAC9M,CAAC,0BAA0B,EAAE,WAAW,CAAC,EAAE,EAAE,EAAE,sBAAsB,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,yEAAyE,EAAE,CAAC,CAAC;QAC9L,CAAC,4BAA4B,EAAE,WAAW,CAAC,EAAE,EAAE,EAAE,wBAAwB,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,mFAAmF,EAAE,CAAC,CAAC;QAC9M,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC;KACtB,CAAC;IACF,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;QAC5D,IAAI;QACJ,SAAS,EAAE,aAAsB;QACjC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;KACnC,CAAC,CAAC,CAAC;IACJ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,GAAG,uBAAuB,EAAE,CAAC;QAC/C,MAAM,IAAI,SAAS,CAAC,8BAA8B,uBAAuB,SAAS,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC"}

package/dist/community/bootstrap/portable-bootstrap.d.ts

@@ -0,0 +1,48 @@
+import { type KnownFileTransactionPlanV1, type KnownFileTransactionReceiptV1 } from "@agent-teams/engineering-foundation/mutation";
+type PortableBootstrapMode = "dry-run" | "apply";
+type PortableBootstrapWriteState = "blocked" | "create" | "current" | "replace";
+interface PortableBootstrapInput {
+    readonly consumerRoot: string;
+    readonly mode: PortableBootstrapMode;
+    readonly ownerId: string;
+    readonly projectId: string;
+}
+interface ApplyPortableBootstrapInput extends PortableBootstrapInput {
+    readonly expectedPlanDigest: `sha256:${string}`;
+    readonly mode: "apply";
+}
+interface PortableBootstrapFilePlan {
+    readonly ownership: "create-only" | "managed-block";
+    readonly path: string;
+    readonly writeState: PortableBootstrapWriteState;
+}
+interface PortableBootstrapIssue {
+    readonly code: "PORTABLE_BOOTSTRAP_AGENTS_TOO_LARGE" | "PORTABLE_BOOTSTRAP_CONFLICT" | "PORTABLE_BOOTSTRAP_INVALID_AGENTS_MARKERS";
+    readonly message: string;
+    readonly path: string;
+}
+export interface PortableBootstrapPlan {
+    readonly schemaVersion: 1;
+    readonly protocol: "agent-teams.docs-protocol.portable-bootstrap/v1";
+    readonly mode: PortableBootstrapMode;
+    readonly outcome: "blocked" | "change-required" | "current";
+    readonly planDigest: `sha256:${string}`;
+    readonly files: readonly PortableBootstrapFilePlan[];
+    readonly issues: readonly PortableBootstrapIssue[];
+    readonly transactionPlan?: KnownFileTransactionPlanV1;
+}
+interface PortableBootstrapExecution {
+    readonly outcome: "applied" | "current";
+    readonly plan: PortableBootstrapPlan;
+    readonly receipt: KnownFileTransactionReceiptV1;
+}
+export declare function compilePortableBootstrap(input: PortableBootstrapInput): Promise<PortableBootstrapPlan>;
+export declare function applyPortableBootstrap(input: ApplyPortableBootstrapInput): Promise<PortableBootstrapExecution>;
+export declare function inspectPortableBootstrap(input: {
+    readonly consumerRoot: string;
+}): Promise<import("@agent-teams/engineering-foundation/mutation").KnownFileTransactionBarrierInspection>;
+export declare function recoverPortableBootstrap(input: {
+    readonly consumerRoot: string;
+}): Promise<KnownFileTransactionReceiptV1>;
+export {};
+//# sourceMappingURL=portable-bootstrap.d.ts.map

package/dist/community/bootstrap/portable-bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-bootstrap.d.ts","sourceRoot":"","sources":["../../../src/community/bootstrap/portable-bootstrap.ts"],"names":[],"mappings":"AAKA,OAAO,EAML,KAAK,0BAA0B,EAC/B,KAAK,6BAA6B,EACnC,MAAM,8CAA8C,CAAC;AAetD,KAAK,qBAAqB,GAAG,SAAS,GAAG,OAAO,CAAC;AACjD,KAAK,2BAA2B,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhF,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,UAAU,2BAA4B,SAAQ,sBAAsB;IAClE,QAAQ,CAAC,kBAAkB,EAAE,UAAU,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,UAAU,yBAAyB;IACjC,QAAQ,CAAC,SAAS,EAAE,aAAa,GAAG,eAAe,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,2BAA2B,CAAC;CAClD;AAED,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,IAAI,EACT,qCAAqC,GACrC,6BAA6B,GAC7B,2CAA2C,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,iDAAiD,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,iBAAiB,GAAG,SAAS,CAAC;IAC5D,QAAQ,CAAC,UAAU,EAAE,UAAU,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,yBAAyB,EAAE,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACnD,QAAQ,CAAC,eAAe,CAAC,EAAE,0BAA0B,CAAC;CACvD;AAED,UAAU,0BAA0B;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,6BAA6B,CAAC;CACjD;AAwVD,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA8C5G;AAED,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAqBpH;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,yGAEtF;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,0CAEtF"}

package/dist/community/bootstrap/portable-bootstrap.js

@@ -0,0 +1,387 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { applyKnownFileTransaction, compileKnownFileTransactionPlan, inspectKnownFileTransactionBarrier, recoverKnownFileTransaction } from "@agent-teams/engineering-foundation/mutation";
+import { DOCS_ADOPTION_MAX_ROUTING_BYTES } from "../../domain/model.js";
+import { PORTABLE_BOOTSTRAP_BEGIN_MARKER, PORTABLE_BOOTSTRAP_END_MARKER, portableBootstrapDesiredFiles, portableBootstrapManagedBlock } from "./portable-bootstrap-assets.js";
+const MAXIMUM_OBSERVED_FILE_BYTES = 8 * 1024 * 1024;
+const MAXIMUM_ROOT_LENGTH = 4096, MAXIMUM_PROJECT_ID_LENGTH = 160, MAXIMUM_OWNER_ID_LENGTH = 214;
+const PROJECT_ID = /^[a-z0-9][a-z0-9._/-]*$/u;
+const OWNER_ID = /^[A-Za-z0-9@][A-Za-z0-9@._/-]*$/u;
+function assertCanonicalId(value, name, pattern, maximumLength) {
+    if (typeof value !== "string" || value.length === 0 || value.length > maximumLength ||
+        value.normalize("NFC") !== value || !pattern.test(value) || value.startsWith("/") ||
+        value.endsWith("/") || value.includes("//") || value.split("/").some((part) => part === "." || part === "..")) {
+        throw new TypeError(`${name} must be one bounded canonical identifier.`);
+    }
+}
+function assertInput(input) {
+    if (Object.getPrototypeOf(input) !== Object.prototype) {
+        throw new TypeError("Portable bootstrap input must be a plain object.");
+    }
+    if (typeof input.consumerRoot !== "string" || input.consumerRoot.length === 0 ||
+        input.consumerRoot.length > MAXIMUM_ROOT_LENGTH || input.consumerRoot.includes("\u0000")) {
+        throw new TypeError("consumerRoot must be one bounded filesystem path.");
+    }
+    if (input.mode !== "dry-run" && input.mode !== "apply") {
+        throw new TypeError("mode must be dry-run or apply.");
+    }
+    assertCanonicalId(input.projectId, "projectId", PROJECT_ID, MAXIMUM_PROJECT_ID_LENGTH);
+    assertCanonicalId(input.ownerId, "ownerId", OWNER_ID, MAXIMUM_OWNER_ID_LENGTH);
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function sameObservation(left, right) {
+    return sameIdentity(left, right) &&
+        left.birthtimeNs === right.birthtimeNs &&
+        left.ctimeNs === right.ctimeNs &&
+        left.mtimeNs === right.mtimeNs &&
+        left.nlink === right.nlink &&
+        left.size === right.size;
+}
+async function readAtMost(handle) {
+    const chunks = [];
+    let total = 0;
+    while (total <= MAXIMUM_OBSERVED_FILE_BYTES) {
+        const remaining = MAXIMUM_OBSERVED_FILE_BYTES + 1 - total;
+        const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, remaining));
+        const { bytesRead } = await handle.read(chunk, 0, chunk.byteLength, null);
+        if (bytesRead === 0) {
+            return Buffer.concat(chunks, total);
+        }
+        chunks.push(chunk.subarray(0, bytesRead));
+        total += bytesRead;
+    }
+    return undefined;
+}
+async function readObservedHandle(handle, path) {
+    const opened = await handle.stat({ bigint: true });
+    if (!opened.isFile()) {
+        throw new TypeError(`Portable bootstrap target must be a real regular file: ${path}.`);
+    }
+    if (opened.nlink !== 1n) {
+        throw new TypeError(`Portable bootstrap target must not have multiple hard links: ${path}.`);
+    }
+    if (opened.size > BigInt(MAXIMUM_OBSERVED_FILE_BYTES)) {
+        throw new TypeError(`Portable bootstrap target exceeds the bounded read limit: ${path}.`);
+    }
+    const bytes = await readAtMost(handle);
+    if (bytes === undefined) {
+        throw new TypeError(`Portable bootstrap target exceeds the bounded read limit: ${path}.`);
+    }
+    const after = await handle.stat({ bigint: true });
+    const physical = await realpath(path).catch(() => null);
+    const pathState = physical === path
+        ? await lstat(path, { bigint: true }).catch(() => null)
+        : null;
+    if (!after.isFile() || after.nlink !== 1n || !sameObservation(opened, after) ||
+        after.size !== BigInt(bytes.byteLength) || pathState === null ||
+        pathState.isSymbolicLink() || !pathState.isFile() || pathState.nlink !== 1n ||
+        !sameObservation(after, pathState)) {
+        throw new TypeError(`Portable bootstrap target changed during read: ${path}.`);
+    }
+    return { bytes, mode: Number(after.mode & 511n) };
+}
+async function canonicalConsumerRoot(consumerRoot) {
+    const requested = resolve(consumerRoot);
+    const physical = await realpath(requested);
+    const [requestedMetadata, physicalMetadata] = await Promise.all([
+        lstat(requested, { bigint: true }),
+        lstat(physical, { bigint: true })
+    ]);
+    if (requestedMetadata.isSymbolicLink() || !requestedMetadata.isDirectory() ||
+        physicalMetadata.isSymbolicLink() || !physicalMetadata.isDirectory() ||
+        !sameIdentity(requestedMetadata, physicalMetadata)) {
+        throw new TypeError("Portable bootstrap consumerRoot must be one real directory, not a symlink.");
+    }
+    return physical;
+}
+async function containedTarget(root, repositoryPath) {
+    const segments = repositoryPath.split("/");
+    let current = root;
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        const identity = segment.normalize("NFC").toLowerCase();
+        const entries = await readdir(current);
+        const matches = entries.filter((entry) => entry.normalize("NFC").toLowerCase() === identity);
+        if (matches.some((entry) => entry !== segment)) {
+            throw new TypeError(`Portable bootstrap target has a case or Unicode path alias: ${repositoryPath}.`);
+        }
+        if (!matches.includes(segment)) {
+            return undefined;
+        }
+        const next = join(current, segment);
+        if (index === segments.length - 1) {
+            return next;
+        }
+        const metadata = await lstat(next);
+        if (metadata.isSymbolicLink() || !metadata.isDirectory() || await realpath(next) !== next) {
+            throw new TypeError(`Portable bootstrap target has an unsafe repository ancestor: ${repositoryPath}.`);
+        }
+        current = next;
+    }
+    return undefined;
+}
+async function observe(root, repositoryPath) {
+    const path = await containedTarget(root, repositoryPath);
+    if (path === undefined) {
+        return undefined;
+    }
+    const noFollow = process.platform === "win32" ? 0 : constants.O_NOFOLLOW;
+    const nonBlocking = process.platform === "win32" ? 0 : constants.O_NONBLOCK;
+    const handle = await open(path, constants.O_RDONLY | noFollow | nonBlocking).catch((error) => {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        if (error.code === "ELOOP") {
+            throw new TypeError(`Portable bootstrap target must be a real regular file: ${path}.`);
+        }
+        throw error;
+    });
+    if (handle === null) {
+        return undefined;
+    }
+    try {
+        return await readObservedHandle(handle, path);
+    }
+    finally {
+        await handle.close();
+    }
+}
+function count(source, needle) {
+    return source.split(needle).length - 1;
+}
+function portablePlanDigest(input) {
+    const body = JSON.stringify({
+        protocol: "agent-teams.docs-protocol.portable-bootstrap/v1",
+        projectId: input.projectId,
+        ownerId: input.ownerId,
+        files: input.desired.map(({ bytes, ownership, path }) => ({
+            path,
+            ownership,
+            digest: createHash("sha256").update(bytes).digest("hex")
+        })),
+        agentsManagedBlockDigest: createHash("sha256").update(portableBootstrapManagedBlock("\n")).digest("hex"),
+        observedPlanDigest: input.transactionPlan?.planDigest ?? null,
+        observations: input.files.map(({ ownership, path, writeState }) => ({ ownership, path, writeState })),
+        issues: input.issues
+    });
+    return `sha256:${createHash("sha256").update(body).digest("hex")}`;
+}
+function planCreateOnlyFile(file, current) {
+    if (current === undefined) {
+        return {
+            file: { path: file.path, ownership: file.ownership, writeState: "create" },
+            operation: {
+                path: file.path,
+                precondition: { state: "absent" },
+                postimage: { bytes: file.bytes }
+            }
+        };
+    }
+    if (current.bytes.equals(file.bytes)) {
+        return {
+            file: { path: file.path, ownership: file.ownership, writeState: "current" },
+            operation: {
+                path: file.path,
+                precondition: { state: "known-file", acceptedPreimages: [{ bytes: current.bytes, mode: current.mode }] },
+                postimage: { bytes: current.bytes, mode: current.mode }
+            }
+        };
+    }
+    return {
+        file: { path: file.path, ownership: file.ownership, writeState: "blocked" },
+        issue: {
+            code: "PORTABLE_BOOTSTRAP_CONFLICT",
+            path: file.path,
+            message: "A create-only bootstrap target already exists with different bytes."
+        }
+    };
+}
+function agentsSizeIssue(bytes) {
+    return bytes.byteLength > DOCS_ADOPTION_MAX_ROUTING_BYTES ? {
+        code: "PORTABLE_BOOTSTRAP_AGENTS_TOO_LARGE",
+        path: "AGENTS.md",
+        message: `Managed AGENTS.md postimage exceeds the ${DOCS_ADOPTION_MAX_ROUTING_BYTES} byte adoption limit.`
+    } : undefined;
+}
+function hasExactManagedBlock(input) {
+    const begin = input.source.indexOf(PORTABLE_BOOTSTRAP_BEGIN_MARKER);
+    const end = input.source.indexOf(PORTABLE_BOOTSTRAP_END_MARKER);
+    return input.beginCount === 1 && input.endCount === 1 && input.source.includes(input.block) &&
+        begin < end && (begin === 0 || input.source.slice(0, begin).endsWith(input.eol)) &&
+        (end + PORTABLE_BOOTSTRAP_END_MARKER.length === input.source.length ||
+            input.source.slice(end + PORTABLE_BOOTSTRAP_END_MARKER.length).startsWith(input.eol));
+}
+function planAgentsFile(agents) {
+    if (agents === undefined) {
+        const bytes = Buffer.from(`${portableBootstrapManagedBlock("\n")}\n`, "utf8");
+        return {
+            file: { path: "AGENTS.md", ownership: "managed-block", writeState: "create" },
+            operation: {
+                path: "AGENTS.md",
+                precondition: { state: "absent" },
+                postimage: { bytes }
+            }
+        };
+    }
+    const currentSizeIssue = agentsSizeIssue(agents.bytes);
+    if (currentSizeIssue !== undefined) {
+        return {
+            file: { path: "AGENTS.md", ownership: "managed-block", writeState: "blocked" },
+            issue: currentSizeIssue
+        };
+    }
+    let source;
+    try {
+        source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(agents.bytes);
+    }
+    catch {
+        return {
+            file: { path: "AGENTS.md", ownership: "managed-block", writeState: "blocked" },
+            issue: {
+                code: "PORTABLE_BOOTSTRAP_INVALID_AGENTS_MARKERS",
+                path: "AGENTS.md",
+                message: "AGENTS.md must be strict UTF-8 text without BOM or NUL bytes."
+            }
+        };
+    }
+    if (source.startsWith("\uFEFF") || source.includes("\u0000")) {
+        return {
+            file: { path: "AGENTS.md", ownership: "managed-block", writeState: "blocked" },
+            issue: {
+                code: "PORTABLE_BOOTSTRAP_INVALID_AGENTS_MARKERS",
+                path: "AGENTS.md",
+                message: "AGENTS.md must be strict UTF-8 text without BOM or NUL bytes."
+            }
+        };
+    }
+    const beginCount = count(source, PORTABLE_BOOTSTRAP_BEGIN_MARKER);
+    const endCount = count(source, PORTABLE_BOOTSTRAP_END_MARKER);
+    const eol = source.includes("\r\n") && !source.replaceAll("\r\n", "").includes("\n")
+        ? "\r\n"
+        : "\n";
+    const block = portableBootstrapManagedBlock(eol);
+    if (beginCount === 0 && endCount === 0) {
+        const separator = source.length === 0 ? "" : source.endsWith(`${eol}${eol}`) ? "" :
+            source.endsWith(eol) ? eol : `${eol}${eol}`;
+        const postimage = Buffer.concat([agents.bytes, Buffer.from(`${separator}${block}${eol}`, "utf8")]);
+        const postimageSizeIssue = agentsSizeIssue(postimage);
+        if (postimageSizeIssue !== undefined) {
+            return {
+                file: { path: "AGENTS.md", ownership: "managed-block", writeState: "blocked" },
+                issue: postimageSizeIssue
+            };
+        }
+        return {
+            file: { path: "AGENTS.md", ownership: "managed-block", writeState: "replace" },
+            operation: {
+                path: "AGENTS.md",
+                precondition: { state: "known-file", acceptedPreimages: [{ bytes: agents.bytes, mode: agents.mode }] },
+                postimage: { bytes: postimage, mode: agents.mode }
+            }
+        };
+    }
+    const exactBlock = hasExactManagedBlock({ beginCount, block, endCount, eol, source });
+    if (exactBlock) {
+        return {
+            file: { path: "AGENTS.md", ownership: "managed-block", writeState: "current" },
+            operation: {
+                path: "AGENTS.md",
+                precondition: { state: "known-file", acceptedPreimages: [{ bytes: agents.bytes, mode: agents.mode }] },
+                postimage: { bytes: agents.bytes, mode: agents.mode }
+            }
+        };
+    }
+    return {
+        file: { path: "AGENTS.md", ownership: "managed-block", writeState: "blocked" },
+        issue: {
+            code: "PORTABLE_BOOTSTRAP_INVALID_AGENTS_MARKERS",
+            path: "AGENTS.md",
+            message: "AGENTS.md contains duplicate, incomplete, or modified portable documentation markers."
+        }
+    };
+}
+export async function compilePortableBootstrap(input) {
+    assertInput(input);
+    const root = await canonicalConsumerRoot(input.consumerRoot);
+    const desired = portableBootstrapDesiredFiles(input.projectId, input.ownerId);
+    const operations = [];
+    const files = [];
+    const issues = [];
+    for (const file of desired) {
+        const planned = planCreateOnlyFile(file, await observe(root, file.path));
+        files.push(planned.file);
+        if (planned.operation !== undefined) {
+            operations.push(planned.operation);
+        }
+        if (planned.issue !== undefined) {
+            issues.push(planned.issue);
+        }
+    }
+    const agents = planAgentsFile(await observe(root, "AGENTS.md"));
+    files.push(agents.file);
+    if (agents.operation !== undefined) {
+        operations.push(agents.operation);
+    }
+    if (agents.issue !== undefined) {
+        issues.push(agents.issue);
+    }
+    files.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+    issues.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+    const transactionPlan = issues.length === 0
+        ? compileKnownFileTransactionPlan({ operations })
+        : undefined;
+    const mutationRequired = files.some(({ writeState }) => writeState === "create" || writeState === "replace");
+    const outcome = issues.length > 0 ? "blocked" : mutationRequired ? "change-required" : "current";
+    const frozenFiles = Object.freeze(files.map((file) => Object.freeze(file)));
+    const frozenIssues = Object.freeze(issues.map((issue) => Object.freeze(issue)));
+    return Object.freeze({
+        schemaVersion: 1,
+        protocol: "agent-teams.docs-protocol.portable-bootstrap/v1",
+        mode: input.mode,
+        outcome,
+        planDigest: portablePlanDigest({
+            desired,
+            transactionPlan,
+            projectId: input.projectId,
+            ownerId: input.ownerId,
+            files: frozenFiles,
+            issues: frozenIssues
+        }),
+        files: frozenFiles,
+        issues: frozenIssues,
+        ...(transactionPlan === undefined ? {} : { transactionPlan })
+    });
+}
+export async function applyPortableBootstrap(input) {
+    if (typeof input.expectedPlanDigest !== "string" ||
+        !/^sha256:[0-9a-f]{64}$/u.test(input.expectedPlanDigest)) {
+        throw new TypeError("expectedPlanDigest must be the exact digest returned by dry-run.");
+    }
+    const compiled = await compilePortableBootstrap(input);
+    if (compiled.outcome === "blocked" || compiled.transactionPlan === undefined) {
+        throw new Error("Portable bootstrap is blocked by conflicting repository files.");
+    }
+    if (input.expectedPlanDigest !== compiled.planDigest) {
+        throw new Error(`Portable bootstrap Plan is stale: expected ${input.expectedPlanDigest}, observed ${compiled.planDigest}.`);
+    }
+    const receipt = await applyKnownFileTransaction({
+        consumerRoot: input.consumerRoot,
+        plan: compiled.transactionPlan
+    });
+    return Object.freeze({
+        outcome: receipt.outcome === "applied" ? "applied" : "current",
+        plan: compiled,
+        receipt
+    });
+}
+export async function inspectPortableBootstrap(input) {
+    return inspectKnownFileTransactionBarrier(input);
+}
+export async function recoverPortableBootstrap(input) {
+    return recoverKnownFileTransaction(input);
+}
+//# sourceMappingURL=portable-bootstrap.js.map