@agentskit/doc-bridge 1.4.0 → 1.4.3

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.4.3
+
+### Patch Changes
+
+- Keep the release audit green by pinning the available `nanoid` fix and documenting
+  the upstream `extract-zip` advisory exception until its patched npm release exists.
+
+## 1.4.2
+
+### Patch Changes
+
+- df61b17: Accept managed ecosystem products without a public repository by supporting `repo: null` and declaration-backed claims in the canonical ecosystem contract.
+
+## 1.4.1
+
+### Patch Changes
+
+- ef543f6: Publish the portable handoff skill through an Agent Plugins v1 manifest for GitHub Copilot.
+- 8b07f46: Package the portable handoff skill and credential-free MCP server as a Claude Code plugin.
+
 ## 1.4.0
 
 ### Minor Changes

package/README.md

@@ -116,7 +116,7 @@ Using Cline? Follow the deterministic [`llms-install.md`](llms-install.md) setup
 |---------|------------|--------------------|
 | **CLI** | Inspect ownership, search docs, run gates, ask local questions | `ak-docs query`, `search`, `ask`, `doctor`, `gate` |
 | **MCP server** | Let Cursor, Claude Code, Codex-style agents resolve handoffs before editing | `ak-docs mcp`, `handoff.resolve` |
-| **GitHub Action / CI** | Fail stale indexes and broken human-doc links on PRs | `AgentsKit-io/doc-bridge@v1.3.0` |
+| **GitHub Action / CI** | Fail stale indexes and broken human-doc links on PRs | `AgentsKit-io/doc-bridge@v1.4.0` |
 | **Documentation conformance** | Check the stable ecosystem standard with auditable evidence | `ak-docs conformance run documentation-standard-v1 --text` |
 | **Doc adapters** | Link human docs to agent docs | `fumadocs`, `docusaurus`, `vitepress`, `starlight`, `nextra`, `plain-markdown` |
 | **Monorepo routing** | Discover workspaces and checks | `pnpm-monorepo`, `nx` |
@@ -129,6 +129,14 @@ See [docs/getting-started.md](docs/getting-started.md), [docs/mcp.md](docs/mcp.m
 
 This repository also contains a Cursor plugin that pairs the read-only Doc Bridge MCP server with a handoff skill. It resolves `startHere`, `readBeforeEditing`, `editRoots`, and `checks` before Cursor edits a routed repository. The plugin does not request credentials or write project files through MCP.
 
+### GitHub Copilot plugin
+
+The root Agent Plugins manifest exposes the same portable handoff skill and read-only MCP server to GitHub Copilot CLI. Copilot discovers `skills/` and `.mcp.json` from the standard plugin layout, so the integration stays source-owned instead of copying prompts into another repository.
+
+```bash
+copilot plugin install AgentsKit-io/doc-bridge
+```
+
 ### Portable Agent Skill
 
 [`skills/doc-bridge-handoff`](skills/doc-bridge-handoff) packages the same fail-closed routing contract in the open Agent Skills layout for OpenClaw-compatible clients, Hermes Agent, Pi, Cursor, and other runtimes that can execute a local skill script. The skill prefers the read-only MCP tool and falls back to a pinned, zero-credential CLI resolver. It never edits files, runs returned checks, or grants authority outside `editRoots`.
@@ -246,7 +254,7 @@ permissions:
 
 steps:
   - uses: actions/checkout@v4
-  - uses: AgentsKit-io/doc-bridge@v1.3.0
+  - uses: AgentsKit-io/doc-bridge@v1.4.0
     with:
       config-path: doc-bridge.config.json
 ```
@@ -332,7 +340,7 @@ ak-docs memory promote --pr              # opens draft PR via gh
 
 ## Status
 
-**v1.3.0 stable** — deterministic Documentation Standard v1 conformance, VitePress, Starlight, Nextra, and Nx discovery, verified release provenance, Marketplace Action, doctor + CI + skill, and full Tier A/B/C.
+**v1.4.0 stable** — portable, fail-closed handoffs for Cursor, Pi, Hermes, and ClawHub-compatible clients; deterministic Documentation Standard v1 conformance; verified release provenance; Marketplace Action; doctor + CI + skill; and full Tier A/B/C.
 
 ```bash
 pnpm install && pnpm build && pnpm test

package/action.yml

@@ -20,7 +20,7 @@ inputs:
   package-version:
     description: Exact @agentskit/doc-bridge npm version (kept in sync with this Action release)
     required: false
-    default: '1.4.0'
+    default: '1.4.3'
 
 runs:
   using: composite

package/dist/cli/program.js

@@ -356,7 +356,9 @@ var IndexConfigSchema = z.object({
   llmsTxt: z.object({
     enabled: z.boolean().optional(),
     outFile: z.string().min(1).max(512).optional(),
-    preamble: z.string().max(4e3).optional()
+    preamble: z.string().max(4e3).optional(),
+    urlPrefix: z.string().url().optional(),
+    pathPrefix: z.string().min(1).max(512).optional()
   }).strict().optional(),
   capabilities: z.object({
     enabled: z.boolean().optional(),
@@ -692,7 +694,7 @@ var ProductSchema = z2.object({
   role: NonEmptyStringSchema,
   promise: NonEmptyStringSchema,
   maturity: z2.enum(["planning", "alpha", "beta", "stable", "deprecated"]),
-  repo: RepoSchema,
+  repo: RepoSchema.nullable(),
   accent: z2.string().regex(/^#[0-9A-Fa-f]{6}$/),
   surfaces: SurfaceSchema,
   navigation: z2.object({
@@ -707,7 +709,7 @@ var LegacyPropertySchema = z2.object({
   barLabel: NonEmptyStringSchema,
   domain: NonEmptyStringSchema,
   url: HttpsUrlSchema,
-  repo: RepoSchema,
+  repo: RepoSchema.nullable(),
   tagline: NonEmptyStringSchema,
   kind: NonEmptyStringSchema,
   accent: z2.string().regex(/^#[0-9A-Fa-f]{6}$/),
@@ -744,7 +746,8 @@ var ClaimProductSchema = z2.object({
   productId: SlugSchema,
   source: z2.discriminatedUnion("type", [
     z2.object({ type: z2.literal("endpoint"), url: HttpsUrlSchema }).passthrough(),
-    z2.object({ type: z2.literal("repository"), repo: RepoSchema }).passthrough()
+    z2.object({ type: z2.literal("repository"), repo: RepoSchema }).passthrough(),
+    z2.object({ type: z2.literal("declaration"), summary: NonEmptyStringSchema }).passthrough()
   ]),
   verification: z2.enum(["verified", "declared"]),
   claims: z2.array(ClaimSchema)
@@ -821,8 +824,10 @@ var parseCanonicalEcosystemContract = (manifestInput, claimsInput) => {
     if (!claimProduct) throw new Error(`Claims are missing product ${productId}.`);
     if (claimProduct.source.type === "endpoint") {
       if (claimProduct.source.url !== product.surfaces.stats) throw new Error(`Claims source for ${productId} must match stats.`);
-    } else if (claimProduct.source.repo !== product.repo) {
+    } else if (claimProduct.source.type === "repository" && claimProduct.source.repo !== product.repo) {
       throw new Error(`Claims source for ${productId} must match repo.`);
+    } else if (claimProduct.source.type === "declaration" && product.repo !== null) {
+      throw new Error(`Declaration source for ${productId} requires a null repo.`);
     }
     if (claimProduct.verification === "declared" && claimProduct.claims.length > 0) {
       throw new Error(`Declared product ${productId} cannot publish claims.`);
@@ -924,6 +929,9 @@ var defaultChecksForTarget = (root, opts) => {
   return opts.strict ? ["npm test", "npm run lint"] : ["npm test"];
 };
 
+// src/index-builder/scan-corpus.ts
+import { minimatch } from "minimatch";
+
 // src/lib/bounded-text.ts
 import { readFileSync as readFileSync3, statSync } from "fs";
 var MAX_DOCUMENT_BYTES = 4 * 1024 * 1024;
@@ -1084,10 +1092,20 @@ var walkFiles = (root, opts) => {
 };
 
 // src/index-builder/scan-corpus.ts
+var configuredPathMatches = (relPath, include, exclude) => {
+  const normalize = (pattern) => toPosix(pattern).replace(/^\.\//, "");
+  const included = include?.filter(Boolean).map(normalize) ?? [];
+  const excluded = exclude?.filter(Boolean).map(normalize) ?? [];
+  if (excluded.some((pattern) => minimatch(relPath, pattern, { dot: true }))) return false;
+  return included.length === 0 || included.some((pattern) => minimatch(relPath, pattern, { dot: true }));
+};
 var scanAgentCorpus = (root, config) => {
   const agentRoot = containedProjectPath(root, config.corpus.agent.root);
   if (!agentRoot) throw new Error("Agent corpus root escapes the project root.");
-  const files = walkFiles(agentRoot, { extensions: [".md", ".mdx"] });
+  const files = walkFiles(agentRoot, { extensions: [".md", ".mdx"] }).filter((abs) => {
+    const relToCorpus = toPosix(abs.replace(`${toPosix(agentRoot)}/`, ""));
+    return configuredPathMatches(relToCorpus, config.corpus.agent.include, config.corpus.agent.exclude);
+  });
   const corpusRelRoot = toPosix(config.corpus.agent.root);
   const budget = { used: 0 };
   return files.map((abs) => {
@@ -1350,7 +1368,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "1.4.0";
+var PACKAGE_VERSION = "1.4.3";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -1401,6 +1419,18 @@ var sha256NormalizedV1 = (payload) => {
 };
 
 // src/index-builder/llms-txt.ts
+var routePath = (path, pathPrefix) => {
+  const normalizedPath = path.replaceAll("\\", "/").replace(/\.(?:md|mdx)$/, "");
+  const normalizedPrefix = pathPrefix?.replaceAll("\\", "/").replace(/\/$/, "");
+  const relativePath2 = normalizedPrefix && normalizedPath.startsWith(`${normalizedPrefix}/`) ? normalizedPath.slice(normalizedPrefix.length + 1) : normalizedPath;
+  return relativePath2.replace(/^\/+/, "");
+};
+var knowledgeUrl = (path, options = {}) => {
+  const relativePath2 = routePath(path, options.pathPrefix);
+  if (!options.urlPrefix) return path;
+  const base = options.urlPrefix.endsWith("/") ? options.urlPrefix : `${options.urlPrefix}/`;
+  return new URL(relativePath2, base).toString();
+};
 var renderLlmsTxt = (config, knowledge, projectName2) => {
   const preamble = config.index?.llmsTxt?.preamble ?? `# ${projectName2}
 
@@ -1408,7 +1438,8 @@ var renderLlmsTxt = (config, knowledge, projectName2) => {
 `;
   const lines = knowledge.slice(0, 500).map((entry) => {
     const desc = entry.description ? `: ${entry.description}` : "";
-    return `- [${entry.title}](${entry.path})${desc}`;
+    const url = knowledgeUrl(entry.path, config.index?.llmsTxt);
+    return `- [${entry.title}](${url})${desc}`;
   });
   return `${preamble.trim()}
 
@@ -1640,11 +1671,23 @@ var nextraAdapter = {
 };
 
 // src/index-builder/human-adapters/plain-markdown.ts
+import { minimatch as minimatch2 } from "minimatch";
+var stringPatterns = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.length > 0) : [];
+var matchesConfiguredPath = (relPath, options) => {
+  const normalize = (pattern) => pattern.replaceAll("\\", "/").replace(/^\.\//, "");
+  const include = stringPatterns(options?.include).map(normalize);
+  const exclude = stringPatterns(options?.exclude).map(normalize);
+  if (exclude.some((pattern) => minimatch2(relPath, pattern, { dot: true }))) return false;
+  return include.length === 0 || include.some((pattern) => minimatch2(relPath, pattern, { dot: true }));
+};
 var plainMarkdownAdapter = {
   plugin: "plain-markdown",
   scan: ({ root, config }) => {
     const humanRoot = optionString(config.options, ["contentDir", "root", "docsDir"]) ?? "docs";
-    return scanMarkdownDocs(root, humanRoot, { urlPrefix: config.options?.urlPrefix });
+    return scanMarkdownDocs(root, humanRoot, {
+      urlPrefix: config.options?.urlPrefix,
+      includeRelPath: (relPath) => matchesConfiguredPath(relPath, config.options)
+    });
   }
 };
 
@@ -1673,7 +1716,7 @@ var starlightAdapter = {
 };
 
 // src/index-builder/human-adapters/vitepress.ts
-import { minimatch } from "minimatch";
+import { minimatch as minimatch3 } from "minimatch";
 var isVitePressPage = (relPath) => !relPath.split("/").some((part) => part === ".vitepress" || part.startsWith("."));
 var srcExcludePatterns = (value) => {
   if (value === void 0) return [];
@@ -1687,7 +1730,7 @@ var srcExcludePatterns = (value) => {
     return pattern;
   });
 };
-var isExcluded = (relPath, patterns) => patterns.some((pattern) => minimatch(relPath, pattern, { dot: true }));
+var isExcluded = (relPath, patterns) => patterns.some((pattern) => minimatch3(relPath, pattern, { dot: true }));
 var vitepressSlug = (relPath, cleanUrls) => {
   const slug2 = routeSlug(relPath);
   if (cleanUrls || /(?:^|\/)index\.mdx?$/.test(relPath)) return slug2;