@tangle-network/agent-docs 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# agent-docs
+
+A deterministic **repo surface + dependency map** for any TypeScript package, with an optional **DeepWiki** narrative augment for public repos.
+
+It answers "what does this package actually export, and how do its parts depend on each other?" — from source, so it can't drift — and gates that answer in CI. For public repos it can also pull DeepWiki's AI-generated architecture wiki alongside, clearly separated so the non-deterministic prose never contaminates the part CI trusts.
+
+## Why
+
+Hand-maintained "modules" tables and architecture docs lie the moment code moves. The mature fix (Microsoft's api-extractor "api-report", docs-as-tests) is to generate the surface from source and fail CI when the committed copy is stale. agent-docs is that pattern, shaped for **multi-entry packages** (a `exports` menu with many subpaths) and **agent readability** — it emits the real dependency graph between subpaths, not just a symbol list, and a machine-readable JSON alongside the markdown.
+
+## Two layers
+
+| Layer | Source | Deterministic? | Gated by `--check`? |
+|---|---|---|---|
+| **Code map + API** (`CODEMAP.md`, `api/*.md`, `codemap.json`) | The TypeScript compiler walking real exports + the import graph | Yes | **Yes** |
+| **Agent-readable surface** (`llms.txt`, `llms-full.txt`) | Same extraction, emitted in the [llms.txt](https://llmstxt.org) format | Yes | **Yes** |
+| **Architecture wiki** (`WIKI.md`) | DeepWiki's MCP (`read_wiki_structure` / `ask_question`) | No (LLM prose) | **Never** |
+
+The `llms.txt` files are the differentiator: an agent-readable index (consumable by GitMCP, Context7, Cursor, Claude) that is **type-derived**, so it can't rot — `--check` fails when it diverges from the real exports. Every `llms.txt` generator in the wild is hand-written or crawl-inferred and drifts silently; this one is gated. (It is not a search/SEO artifact — Google doesn't consume llms.txt — its value is coding agents pulling it.)
+
+The split is deliberate: an LLM must never write the artifact CI depends on. The deterministic files are the contract; `WIKI.md` is a reading aid.
+
+## Usage
+
+```bash
+# regenerate the deterministic map (docs/CODEMAP.md + docs/api/*.md + docs/codemap.json)
+npx @tangle-network/agent-docs
+
+# CI gate — exit 1 if the committed map is stale
+npx @tangle-network/agent-docs --check
+
+# also write docs/WIKI.md from DeepWiki (public GitHub repos only)
+npx @tangle-network/agent-docs --deepwiki
+
+# options
+npx @tangle-network/agent-docs --repo path/to/repo --out docs
+```
+
+Wire the gate into CI (it needs only the `typescript` the repo already has):
+
+```yaml
+- run: npx @tangle-network/agent-docs --check
+```
+
+## Entry-point detection
+
+Auto-detected, in priority order — no config needed for the common cases:
+
+1. `agent-docs.config.{mjs,json}` — explicit `entries` override
+2. `tsup.config.ts` `entry` map
+3. `package.json` `exports` (reverse-mapped from `dist` → `src`)
+4. `src/index.ts`
+
+```js
+// agent-docs.config.mjs (only if auto-detection misses)
+export default {
+  entries: ['src/index.ts', 'src/server/index.ts'],
+  out: 'docs',
+  deepwiki: true, // augment when the repo is public
+}
+```
+
+## Public vs private repos
+
+- **Private repos:** the deterministic core runs fully offline — no network, no LLM, no external service. This is the whole tool for a private repo.
+- **Public repos:** add `--deepwiki` to pull the free, no-auth DeepWiki wiki + Q&A for the repo. If the repo isn't indexed yet, the augment is skipped and the deterministic map is unaffected. (Index a public repo once at `deepwiki.com/<owner>/<repo>`.)
+
+## Requirements
+
+Node ≥ 20, and `typescript` resolvable from the target repo (it's a peer dependency — every TS repo has it). agent-docs carries no runtime dependencies of its own.
+
+## License
+
+MIT

package/dist/chunk-EKQKRTAN.js

@@ -0,0 +1,571 @@
+// src/index.ts
+import { existsSync as existsSync4, mkdirSync, readdirSync as readdirSync2, readFileSync as readFileSync4, rmSync, writeFileSync } from "fs";
+import { basename, dirname as dirname3, join as join5, resolve as resolve2 } from "path";
+
+// src/config.ts
+import { execFileSync } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { pathToFileURL } from "url";
+async function loadConfig(repoRoot) {
+  for (const name of ["agent-docs.config.mjs", "agent-docs.config.js"]) {
+    const p = join(repoRoot, name);
+    if (existsSync(p)) {
+      const mod = await import(pathToFileURL(p).href);
+      return mod.default ?? mod.config ?? {};
+    }
+  }
+  const jsonPath = join(repoRoot, "agent-docs.config.json");
+  if (existsSync(jsonPath)) return JSON.parse(readFileSync(jsonPath, "utf8"));
+  return {};
+}
+function parseRemoteUrl(url) {
+  if (!url) return null;
+  const ssh = url.match(/git@([^:]+):([^/]+)\/(.+?)(?:\.git)?$/);
+  const https = url.match(/https?:\/\/(?:[^@/]+@)?([^/]+)\/([^/]+)\/(.+?)(?:\.git)?$/);
+  const parsed = ssh ?? https;
+  if (!parsed) return null;
+  const [, host, owner, repo] = parsed;
+  return { host, owner, repo, slug: `${owner}/${repo}` };
+}
+function detectRepoSlug(repoRoot) {
+  let url;
+  try {
+    url = execFileSync("git", ["-C", repoRoot, "remote", "get-url", "origin"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    const cfg = join(repoRoot, ".git", "config");
+    if (!existsSync(cfg)) return null;
+    const m = readFileSync(cfg, "utf8").match(/\[remote "origin"\][^[]*?url\s*=\s*(.+)/);
+    if (!m) return null;
+    url = m[1].trim();
+  }
+  return parseRemoteUrl(url);
+}
+
+// src/deepwiki.ts
+var ENDPOINT = "https://mcp.deepwiki.com/mcp";
+var PROTOCOL = "2025-06-18";
+function parseBody(contentType, text) {
+  if (contentType.includes("text/event-stream")) {
+    const out = [];
+    for (const line of text.split(/\r?\n/)) {
+      const m = line.match(/^data:\s*(.*)$/);
+      if (!m) continue;
+      try {
+        out.push(JSON.parse(m[1]));
+      } catch {
+      }
+    }
+    return out;
+  }
+  try {
+    return [JSON.parse(text)];
+  } catch {
+    return [];
+  }
+}
+async function post(body, sessionId, signal) {
+  const headers = {
+    "content-type": "application/json",
+    accept: "application/json, text/event-stream"
+  };
+  if (sessionId) headers["mcp-session-id"] = sessionId;
+  const res = await fetch(ENDPOINT, { method: "POST", headers, body: JSON.stringify(body), signal });
+  const text = await res.text();
+  return { res, messages: parseBody(res.headers.get("content-type") ?? "", text) };
+}
+function resultOf(messages, id) {
+  const msg = messages.find((m) => m && m.id === id);
+  if (!msg || msg.error) return null;
+  return msg.result ?? null;
+}
+function toolText(result) {
+  if (!result) return "";
+  const content = Array.isArray(result.content) ? result.content : [];
+  return content.map((c) => c && typeof c.text === "string" ? c.text : "").filter(Boolean).join("\n").trim();
+}
+async function fetchDeepwiki(slug, { ask = [], timeoutMs = 25e3 } = {}) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const init = await post(
+      {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          protocolVersion: PROTOCOL,
+          capabilities: {},
+          clientInfo: { name: "agent-docs", version: "0.1.0" }
+        }
+      },
+      void 0,
+      ac.signal
+    );
+    const sessionId = init.res.headers.get("mcp-session-id") ?? void 0;
+    if (!resultOf(init.messages, 1)) return null;
+    await post({ jsonrpc: "2.0", method: "notifications/initialized" }, sessionId, ac.signal).catch(() => {
+    });
+    const call = async (id2, name, args) => {
+      const { messages } = await post(
+        { jsonrpc: "2.0", id: id2, method: "tools/call", params: { name, arguments: args } },
+        sessionId,
+        ac.signal
+      );
+      return toolText(resultOf(messages, id2));
+    };
+    const structure = await call(2, "read_wiki_structure", { repoName: slug });
+    if (!structure || /not\s+found|to index it/i.test(structure)) return null;
+    const answers = [];
+    let id = 3;
+    for (const q of ask) {
+      const a = await call(id++, "ask_question", { repoName: slug, question: q });
+      if (a) answers.push({ q, a });
+    }
+    return { structure, answers };
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/entries.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { dirname, join as join2, relative } from "path";
+function resolveEntries(repoRoot, config, ts) {
+  const srcRoot = join2(repoRoot, config.srcDir ?? "src");
+  const rels = (config.entries && config.entries.length ? config.entries : null) ?? fromTsup(repoRoot, ts) ?? fromPackageExports(repoRoot) ?? fromDefault(repoRoot);
+  if (!rels || rels.length === 0) {
+    throw new Error(
+      'agent-docs: no entry points detected. Add a agent-docs.config.json with { "entries": ["src/index.ts", ...] }.'
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const entries = [];
+  for (const rel of rels) {
+    const abs = join2(repoRoot, rel);
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    if (!existsSync2(abs)) continue;
+    entries.push(toEntry(repoRoot, abs, srcRoot, rel));
+  }
+  return entries.sort((a, b) => a.exportPath.localeCompare(b.exportPath));
+}
+function toEntry(repoRoot, abs, srcRoot, rel) {
+  const underSrc = abs === srcRoot || abs.startsWith(srcRoot + "/");
+  const key = (underSrc ? relative(srcRoot, abs) : relative(repoRoot, abs)).replace(/\.[tj]sx?$/, "");
+  const id = key === "index" ? "." : key.replace(/\/index$/, "");
+  const exportPath = id === "." ? "." : `./${id}`;
+  const apiName = (id === "." ? "index" : id).replace(/\//g, "-");
+  const topDir = key.split("/")[0];
+  return { id, exportPath, file: abs, apiName, topDir, srcDir: dirname(abs), rel: rel.replace(/\\/g, "/") };
+}
+function fromTsup(repoRoot, ts) {
+  if (!ts) return null;
+  const configPath = ["tsup.config.ts", "tsup.config.js", "tsup.config.mjs"].map((n) => join2(repoRoot, n)).find((p) => existsSync2(p));
+  if (!configPath) return null;
+  const sf = ts.createSourceFile(configPath, readFileSync2(configPath, "utf8"), ts.ScriptTarget.Latest, true);
+  let init;
+  const visit = (node) => {
+    if (ts.isPropertyAssignment(node) && (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) && node.name.text === "entry" && !init) {
+      init = node.initializer;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  if (!init) return null;
+  const files = [];
+  if (ts.isObjectLiteralExpression(init)) {
+    for (const prop of init.properties) {
+      if (ts.isPropertyAssignment(prop) && ts.isStringLiteral(prop.initializer)) files.push(prop.initializer.text);
+    }
+  } else if (ts.isArrayLiteralExpression(init)) {
+    for (const el of init.elements) if (ts.isStringLiteral(el)) files.push(el.text);
+  }
+  return files.length ? files : null;
+}
+function fromPackageExports(repoRoot) {
+  const pkgPath = join2(repoRoot, "package.json");
+  if (!existsSync2(pkgPath)) return null;
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync2(pkgPath, "utf8"));
+  } catch {
+    return null;
+  }
+  const exp = pkg.exports;
+  if (!exp || typeof exp !== "object") return null;
+  const files = [];
+  for (const [sub, val] of Object.entries(exp)) {
+    if (sub.includes("*") || sub.endsWith("package.json") || /\.(css|json)$/.test(sub)) continue;
+    const target = typeof val === "string" ? val : val && typeof val === "object" ? val.types ?? val.import ?? val.default ?? val.require : void 0;
+    if (typeof target !== "string") continue;
+    const src = distToSrc(target);
+    if (src && existsSync2(join2(repoRoot, src))) files.push(src);
+  }
+  return files.length ? files : null;
+}
+function distToSrc(target) {
+  let s = target.replace(/^\.\//, "");
+  s = s.replace(/^dist\//, "src/");
+  s = s.replace(/\.d\.ts$/, ".ts").replace(/\.d\.mts$/, ".ts").replace(/\.m?js$/, ".ts");
+  return s;
+}
+function fromDefault(repoRoot) {
+  for (const rel of ["src/index.ts", "src/index.tsx", "index.ts", "src/index.mts"]) {
+    if (existsSync2(join2(repoRoot, rel))) return [rel];
+  }
+  return null;
+}
+
+// src/extract.ts
+import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync3 } from "fs";
+import { dirname as dirname2, join as join3, relative as relative2, resolve } from "path";
+function createProgram(ts, repoRoot, entries, tsconfigName = "tsconfig.json") {
+  const tsconfigPath = join3(repoRoot, tsconfigName);
+  let options = { allowJs: true };
+  if (existsSync3(tsconfigPath)) {
+    const cfg = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+    const parsed = ts.parseJsonConfigFileContent(cfg.config ?? {}, ts.sys, repoRoot);
+    options = parsed.options;
+  }
+  options = { ...options, noEmit: true, skipLibCheck: true, allowJs: true };
+  return ts.createProgram(
+    entries.map((e) => e.file),
+    options
+  );
+}
+var truncate = (s, n) => s.length > n ? `${s.slice(0, n - 1).trimEnd()}\u2026` : s;
+function firstSentence(text) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  if (!flat) return "";
+  const m = flat.match(/^(.*?[.!?])(\s|$)/);
+  return truncate(m ? m[1] : flat, 200);
+}
+function describe(ts, checker, exported) {
+  let sym = exported;
+  if (sym.flags & ts.SymbolFlags.Alias) {
+    try {
+      sym = checker.getAliasedSymbol(sym);
+    } catch {
+      sym = exported;
+    }
+  }
+  const name = exported.getName();
+  const decl = sym.valueDeclaration ?? sym.declarations?.[0];
+  const f = sym.flags;
+  let kind;
+  let signature;
+  if (f & ts.SymbolFlags.Class) {
+    kind = "class";
+    signature = `class ${name}`;
+  } else if (f & ts.SymbolFlags.Interface) {
+    kind = "interface";
+    signature = `interface ${name}`;
+  } else if (f & ts.SymbolFlags.TypeAlias) {
+    kind = "type";
+    signature = `type ${name}`;
+  } else if (f & ts.SymbolFlags.Enum || f & ts.SymbolFlags.EnumMember) {
+    kind = "enum";
+    signature = `enum ${name}`;
+  } else if (f & (ts.SymbolFlags.Module | ts.SymbolFlags.ValueModule | ts.SymbolFlags.NamespaceModule)) {
+    kind = "namespace";
+    signature = `namespace ${name}`;
+  } else if (decl) {
+    const type = checker.getTypeOfSymbolAtLocation(sym, decl);
+    const callable = type.getCallSignatures().length > 0;
+    kind = f & ts.SymbolFlags.Function || callable ? "function" : "const";
+    signature = truncate(checker.typeToString(type).replace(/\s+/g, " "), 120);
+  } else {
+    kind = "value";
+    signature = name;
+  }
+  let doc = ts.displayPartsToString(exported.getDocumentationComment(checker)).trim();
+  if (!doc && sym !== exported) doc = ts.displayPartsToString(sym.getDocumentationComment(checker)).trim();
+  return { name, kind, signature, doc: firstSentence(doc) };
+}
+function exportsOf(ts, program, checker, entry) {
+  const sf = program.getSourceFile(entry.file);
+  if (!sf) return { error: `no source file for ${entry.rel}` };
+  const moduleSym = checker.getSymbolAtLocation(sf);
+  if (!moduleSym) return { error: `no module symbol for ${entry.rel} (empty or non-module?)` };
+  const exports = checker.getExportsOfModule(moduleSym).filter((s) => !s.getName().startsWith("__")).map((s) => describe(ts, checker, s)).sort((a, b) => a.name.localeCompare(b.name));
+  return { exports };
+}
+var walk = (dir) => existsSync3(dir) ? readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+  const p = join3(dir, e.name);
+  if (e.isDirectory()) return walk(p);
+  return /\.(ts|tsx|mts|cts)$/.test(e.name) ? [p] : [];
+}) : [];
+function siblingDeps(entry, srcRoot, topDirs) {
+  const deps = /* @__PURE__ */ new Set();
+  for (const file of walk(entry.srcDir)) {
+    const text = readFileSync3(file, "utf8");
+    for (const m of text.matchAll(/(?:from|import)\s*\(?\s*['"](\.[^'"]*)['"]/g)) {
+      const abs = resolve(dirname2(file), m[1]);
+      if (!abs.startsWith(srcRoot + "/")) continue;
+      const seg = relative2(srcRoot, abs).split("/")[0];
+      if (seg && seg !== entry.topDir && topDirs.has(seg)) deps.add(seg);
+    }
+  }
+  return [...deps].sort();
+}
+function extractRows(ts, repoRoot, entries, config = {}) {
+  const srcRoot = join3(repoRoot, config.srcDir ?? "src");
+  const topDirs = new Set(entries.map((e) => e.topDir));
+  const program = createProgram(ts, repoRoot, entries, config.tsconfig);
+  const checker = program.getTypeChecker();
+  return entries.map((entry) => {
+    const { exports = [], error } = exportsOf(ts, program, checker, entry);
+    return { entry, exports, error, deps: siblingDeps(entry, srcRoot, topDirs) };
+  });
+}
+
+// src/render.ts
+var HEADER = "<!-- GENERATED by agent-docs \u2014 DO NOT EDIT BY HAND. Regenerate with `agent-docs`. -->";
+function buildFiles(rows, meta) {
+  const out = meta.out ?? "docs";
+  const files = /* @__PURE__ */ new Map();
+  files.set(`${out}/CODEMAP.md`, renderCodemap(rows, meta));
+  files.set(`${out}/codemap.json`, renderJson(rows, meta));
+  files.set(`${out}/llms.txt`, renderLlmsTxt(rows, meta));
+  files.set(`${out}/llms-full.txt`, renderLlmsFull(rows, meta));
+  for (const row of rows) files.set(`${out}/api/${row.entry.apiName}.md`, renderApiPage(row));
+  return files;
+}
+function purpose(meta) {
+  return meta.description ?? `Deterministic export surface for ${meta.title}.`;
+}
+function renderLlmsTxt(rows, meta) {
+  const lines = [`# ${meta.title}`, "", `> ${purpose(meta)}`, ""];
+  lines.push(
+    `_Generated by agent-docs from ${meta.sourceLabel}; ${rows.length} entr${rows.length === 1 ? "y" : "ies"}. Regenerate with \`agent-docs\`; full inlined surface in [llms-full.txt](llms-full.txt)._`,
+    "",
+    "## Modules",
+    ""
+  );
+  for (const { entry, exports, error } of rows) {
+    const count = error ? "introspection failed" : `${exports.length} export${exports.length === 1 ? "" : "s"}`;
+    const names = error || !exports.length ? "" : ` \u2014 ${exports.slice(0, 8).map((e) => e.name).join(", ")}${exports.length > 8 ? ", \u2026" : ""}`;
+    lines.push(`- [\`${entry.exportPath}\`](api/${entry.apiName}.md): ${count}${names}`);
+  }
+  return `${lines.join("\n").trimEnd()}
+`;
+}
+function renderLlmsFull(rows, meta) {
+  const lines = [`# ${meta.title} \u2014 full API surface`, "", `> ${purpose(meta)}`, ""];
+  lines.push(
+    `_Generated by agent-docs from ${meta.sourceLabel}; ${rows.length} entries, every export with its signature. Regenerate with \`agent-docs\`._`
+  );
+  for (const { entry, exports, error, deps } of rows) {
+    lines.push("", `## \`${entry.exportPath}\``, "");
+    lines.push(`Source: \`${entry.rel}\`${deps.length ? ` \xB7 depends on ${deps.map((d) => `\`${d}\``).join(", ")}` : ""}`, "");
+    if (error) {
+      lines.push(`> Could not introspect: ${error}`);
+      continue;
+    }
+    if (!exports.length) {
+      lines.push("_No public exports._");
+      continue;
+    }
+    for (const e of exports) {
+      lines.push(`### \`${e.name}\``, "", `\`${e.kind}\`${e.doc ? ` \u2014 ${e.doc}` : ""}`, "", "```ts", e.signature, "```", "");
+    }
+  }
+  return `${lines.join("\n").trimEnd()}
+`;
+}
+function renderWiki(meta) {
+  if (!meta.deepwiki) return null;
+  const out = meta.out ?? "docs";
+  const lines = [
+    HEADER.replace(
+      "DO NOT EDIT BY HAND. Regenerate with `agent-docs`.",
+      "AI-GENERATED via DeepWiki \u2014 non-authoritative, regenerated with `agent-docs --deepwiki`."
+    ),
+    "",
+    `# ${meta.title} \u2014 architecture (DeepWiki)`,
+    "",
+    `> AI-generated by [DeepWiki](https://deepwiki.com/${meta.slug}); a reading aid, **not** a contract. The source of truth is [\`CODEMAP.md\`](./CODEMAP.md), extracted from source.`,
+    ""
+  ];
+  if (meta.deepwiki.structure) lines.push("## Wiki pages", "", "```", meta.deepwiki.structure.trim(), "```", "");
+  for (const { q, a } of meta.deepwiki.answers ?? []) lines.push(`## ${q}`, "", a.trim(), "");
+  return { path: `${out}/WIKI.md`, content: `${lines.join("\n").trimEnd()}
+` };
+}
+function renderCodemap(rows, meta) {
+  const title = meta.title ?? "code map";
+  const lines = [HEADER, "", `# ${title} code map`, ""];
+  lines.push(`_${rows.length} entr${rows.length === 1 ? "y" : "ies"} \u2014 ${meta.sourceLabel}. Regenerate with \`agent-docs\`._`, "");
+  lines.push("| Entry | Exports | Depends on |", "|---|---|---|");
+  for (const { entry, exports, error, deps } of rows) {
+    const link = `[\`${entry.exportPath}\`](api/${entry.apiName}.md)`;
+    const count = error ? "\u2014" : String(exports.length);
+    const dep = deps.length ? deps.map((d) => `\`${d}\``).join(", ") : "\u2014";
+    lines.push(`| ${link} | ${count} | ${dep} |`);
+  }
+  lines.push("", "---", "");
+  for (const { entry, exports, error, deps } of rows) {
+    lines.push(`## \`${entry.exportPath}\``, "");
+    lines.push(`Source: \`${entry.rel}\` \xB7 ${error ? "introspection failed" : `${exports.length} exports`}`, "");
+    if (deps.length) lines.push(`Depends on: ${deps.map((d) => `\`${d}\``).join(", ")}`, "");
+    if (error) lines.push(`> Could not introspect: ${error}`, "");
+    else if (exports.length) lines.push(exports.map((e) => `\`${e.name}\``).join(", "), "", `[Full API \u2192](api/${entry.apiName}.md)`, "");
+    else lines.push("_No public exports._", "");
+  }
+  return `${lines.join("\n").trimEnd()}
+`;
+}
+function renderApiPage({ entry, exports, error }) {
+  const lines = [HEADER, "", `# \`${entry.exportPath}\``, "", `Source: \`${entry.rel}\``, ""];
+  if (error) return `${[...lines, `> Could not introspect this entry: ${error}`].join("\n").trimEnd()}
+`;
+  lines.push(`${exports.length} export${exports.length === 1 ? "" : "s"}.`, "");
+  for (const e of exports) {
+    lines.push(`### \`${e.name}\``, "");
+    lines.push(`\`${e.kind}\`${e.doc ? ` \u2014 ${e.doc}` : ""}`, "");
+    lines.push("```ts", e.signature, "```", "");
+  }
+  return `${lines.join("\n").trimEnd()}
+`;
+}
+function renderJson(rows, meta) {
+  const payload = {
+    generator: "agent-docs",
+    title: meta.title,
+    source: meta.sourceLabel,
+    slug: meta.slug ?? null,
+    entries: rows.map(({ entry, exports, error, deps }) => ({
+      id: entry.exportPath,
+      source: entry.rel,
+      dependsOn: deps,
+      error: error ?? null,
+      exports: exports.map((e) => ({ name: e.name, kind: e.kind, signature: e.signature, doc: e.doc || null }))
+    }))
+  };
+  return `${JSON.stringify(payload, null, 2)}
+`;
+}
+
+// src/ts.ts
+import { createRequire } from "module";
+import { join as join4 } from "path";
+import { pathToFileURL as pathToFileURL2 } from "url";
+async function loadTs(repoRoot) {
+  const candidates = [];
+  try {
+    candidates.push(createRequire(join4(repoRoot, "package.json")).resolve("typescript"));
+  } catch {
+  }
+  try {
+    candidates.push(createRequire(import.meta.url).resolve("typescript"));
+  } catch {
+  }
+  for (const path of candidates) {
+    try {
+      const mod = await import(pathToFileURL2(path).href);
+      return mod.default ?? mod;
+    } catch {
+    }
+  }
+  throw new Error(
+    "could not load 'typescript'. Run agent-docs inside a repo that has typescript installed (it's a peer dependency)."
+  );
+}
+
+// src/index.ts
+var DEFAULT_ASK = [
+  "What is the high-level architecture and what are the main components?",
+  "How do the main components fit together in a typical request or data flow?"
+];
+function readPackageDescription(root) {
+  const pkg = join5(root, "package.json");
+  if (!existsSync4(pkg)) return void 0;
+  try {
+    const d = JSON.parse(readFileSync4(pkg, "utf8")).description;
+    return typeof d === "string" && d ? d : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function describeSource(root, config) {
+  if (config.entries?.length) return "entries from agent-docs.config";
+  if (["tsup.config.ts", "tsup.config.js", "tsup.config.mjs"].some((n) => existsSync4(join5(root, n)))) return "tsup.config `entry`";
+  const pkg = join5(root, "package.json");
+  if (existsSync4(pkg)) {
+    try {
+      if (JSON.parse(readFileSync4(pkg, "utf8")).exports) return "package.json `exports`";
+    } catch {
+    }
+  }
+  return "src/index";
+}
+async function analyze(repoRoot, opts = {}) {
+  const root = resolve2(repoRoot);
+  const config = await loadConfig(root);
+  const ts = await loadTs(root);
+  const entries = resolveEntries(root, config, ts);
+  const rows = extractRows(ts, root, entries, config);
+  const slug = detectRepoSlug(root);
+  const meta = {
+    out: opts.out ?? config.out ?? "docs",
+    title: config.title ?? slug?.repo ?? basename(root),
+    description: readPackageDescription(root),
+    sourceLabel: describeSource(root, config),
+    slug: slug?.slug
+  };
+  const wantWiki = opts.deepwiki ?? config.deepwiki ?? false;
+  let deepwikiTried = false;
+  if (wantWiki && slug && /(^|\.)github\.com$/i.test(slug.host)) {
+    deepwikiTried = true;
+    const dw = await fetchDeepwiki(slug.slug, { ask: opts.ask ?? config.ask ?? DEFAULT_ASK });
+    if (dw) meta.deepwiki = dw;
+  }
+  return { root, rows, meta, slug, wantWiki, deepwikiTried, files: buildFiles(rows, meta), wiki: renderWiki(meta) };
+}
+async function write(repoRoot, opts = {}) {
+  const r = await analyze(repoRoot, opts);
+  const apiDir = join5(r.root, r.meta.out, "api");
+  if (existsSync4(apiDir)) rmSync(apiDir, { recursive: true, force: true });
+  const written = [];
+  for (const [rel, content] of r.files) {
+    const abs = join5(r.root, rel);
+    mkdirSync(dirname3(abs), { recursive: true });
+    writeFileSync(abs, content);
+    written.push(rel);
+  }
+  if (r.wiki) {
+    const abs = join5(r.root, r.wiki.path);
+    mkdirSync(dirname3(abs), { recursive: true });
+    writeFileSync(abs, r.wiki.content);
+    written.push(r.wiki.path);
+  }
+  return { ...r, written };
+}
+async function check(repoRoot, opts = {}) {
+  const r = await analyze(repoRoot, { ...opts, deepwiki: false });
+  const stale = [];
+  const missing = [];
+  for (const [rel, content] of r.files) {
+    const abs = join5(r.root, rel);
+    if (!existsSync4(abs)) missing.push(rel);
+    else if (readFileSync4(abs, "utf8") !== content) stale.push(rel);
+  }
+  const apiDir = join5(r.root, r.meta.out, "api");
+  const orphan = existsSync4(apiDir) ? readdirSync2(apiDir).filter((f) => f.endsWith(".md")).map((f) => `${r.meta.out}/api/${f}`).filter((rel) => !r.files.has(rel)) : [];
+  return { ok: stale.length + missing.length + orphan.length === 0, stale, missing, orphan, meta: r.meta };
+}
+
+export {
+  parseRemoteUrl,
+  detectRepoSlug,
+  fetchDeepwiki,
+  analyze,
+  write,
+  check
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import {
+  check,
+  write
+} from "./chunk-EKQKRTAN.js";
+
+// src/cli.ts
+var HELP = `agent-docs \u2014 deterministic repo surface + dependency map for any TypeScript package.
+
+Usage:
+  agent-docs [gen]            Regenerate docs/CODEMAP.md + docs/api/*.md + docs/codemap.json
+  agent-docs --check         Exit 1 if the committed deterministic docs are stale (CI gate)
+  agent-docs --deepwiki      Also write docs/WIKI.md from DeepWiki (public GitHub repos only)
+
+Options:
+  --repo <path>              Repo root (default: cwd)
+  --out <dir>                Output dir (default: docs, or agent-docs.config \`out\`)
+  -h, --help
+
+Entry points are auto-detected: agent-docs.config > tsup.config \`entry\` > package.json \`exports\` > src/index.
+The deterministic files are what --check gates on; the DeepWiki WIKI.md is a non-authoritative reading aid and is never gated.`;
+function parseArgs(argv) {
+  const args2 = { repo: process.cwd(), check: false, deepwiki: false, help: false };
+  const rest = argv.slice(2);
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--check" || a === "check") args2.check = true;
+    else if (a === "--deepwiki") args2.deepwiki = true;
+    else if (a === "--repo") args2.repo = rest[++i];
+    else if (a === "--out") args2.out = rest[++i];
+    else if (a === "-h" || a === "--help") args2.help = true;
+    else if (a === "gen") {
+    } else if (a.startsWith("-")) {
+      console.error(`agent-docs: unknown option ${a}`);
+      process.exit(2);
+    }
+  }
+  return args2;
+}
+var args = parseArgs(process.argv);
+if (args.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+try {
+  if (args.check) {
+    const r2 = await check(args.repo, { out: args.out });
+    if (r2.ok) {
+      console.log("agent-docs: docs are fresh");
+      process.exit(0);
+    }
+    console.error("agent-docs: docs are STALE \u2014 run `agent-docs` and commit the result.");
+    for (const f of r2.missing) console.error(`  missing:  ${f}`);
+    for (const f of r2.stale) console.error(`  changed:  ${f}`);
+    for (const f of r2.orphan) console.error(`  orphaned: ${f}`);
+    process.exit(1);
+  }
+  const r = await write(args.repo, { out: args.out, deepwiki: args.deepwiki });
+  const det = r.written.filter((f) => !f.endsWith("WIKI.md")).length;
+  console.log(`agent-docs: wrote ${det} files under ${r.meta.out}/ (${r.rows.length} entries)`);
+  if (args.deepwiki) {
+    if (r.wiki) console.log(`agent-docs: + ${r.wiki.path} (DeepWiki: ${r.slug?.slug})`);
+    else if (r.deepwikiTried)
+      console.log(`agent-docs: DeepWiki skipped \u2014 ${r.slug?.slug ?? "repo"} not indexed or unreachable (deterministic map unaffected)`);
+    else console.log("agent-docs: DeepWiki needs a public github.com remote; skipped");
+  }
+} catch (err) {
+  console.error(`agent-docs: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(2);
+}

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import * as typescript from 'typescript';
+
+/** The TypeScript compiler module, loaded from the target repo at runtime. */
+type TS = typeof typescript;
+interface Entry {
+    /** Public subpath id: `.` for the root, else e.g. `chat-routes`. */
+    id: string;
+    /** Export path as written in `exports`: `.` or `./chat-routes`. */
+    exportPath: string;
+    /** Absolute path to the entry source file. */
+    file: string;
+    /** Flattened name for the API page file: `index` or `chat-routes`. */
+    apiName: string;
+    /** First path segment under the source root — the sibling-graph key. */
+    topDir: string;
+    /** Directory containing the entry (scanned for the import graph). */
+    srcDir: string;
+    /** Repo-relative source path, for display. */
+    rel: string;
+}
+type ExportKind = 'class' | 'interface' | 'type' | 'enum' | 'namespace' | 'function' | 'const' | 'value';
+interface ExportInfo {
+    name: string;
+    kind: ExportKind;
+    signature: string;
+    doc: string;
+}
+interface Row {
+    entry: Entry;
+    exports: ExportInfo[];
+    error?: string;
+    deps: string[];
+}
+interface CartographConfig {
+    entries?: string[];
+    srcDir?: string;
+    tsconfig?: string;
+    out?: string;
+    title?: string;
+    deepwiki?: boolean;
+    ask?: string[];
+}
+interface RepoSlug {
+    host: string;
+    owner: string;
+    repo: string;
+    slug: string;
+}
+interface DeepwikiResult {
+    structure: string;
+    answers: Array<{
+        q: string;
+        a: string;
+    }>;
+}
+interface Meta {
+    out: string;
+    title: string;
+    /** One-line purpose (from package.json `description`), for the llms.txt blockquote. */
+    description?: string;
+    sourceLabel: string;
+    slug?: string;
+    deepwiki?: DeepwikiResult;
+}
+interface AnalyzeOptions {
+    out?: string;
+    deepwiki?: boolean;
+    ask?: string[];
+}
+interface AnalyzeResult {
+    root: string;
+    rows: Row[];
+    meta: Meta;
+    slug: RepoSlug | null;
+    wantWiki: boolean;
+    deepwikiTried: boolean;
+    files: Map<string, string>;
+    wiki: {
+        path: string;
+        content: string;
+    } | null;
+}
+interface CheckResult {
+    ok: boolean;
+    stale: string[];
+    missing: string[];
+    orphan: string[];
+    meta: Meta;
+}
+
+/** Pure parse of a git remote URL → `{ host, owner, repo, slug }` or null. */
+declare function parseRemoteUrl(url: string | null | undefined): RepoSlug | null;
+/**
+ * `{ host, owner, repo, slug }` from the git `origin` remote, or null. Uses
+ * `git` (worktree-safe) and falls back to parsing `.git/config`. Only GitHub
+ * remotes carry a DeepWiki-usable slug; the caller decides what to do with it.
+ */
+declare function detectRepoSlug(repoRoot: string): RepoSlug | null;
+
+/**
+ * Fetch DeepWiki context for `slug` (`owner/repo`). Returns
+ * `{ structure, answers: [{q, a}] }` or null. `ask` is a list of questions to
+ * put to `ask_question`.
+ */
+declare function fetchDeepwiki(slug: string, { ask, timeoutMs }?: {
+    ask?: string[];
+    timeoutMs?: number;
+}): Promise<DeepwikiResult | null>;
+
+/** Extract the surface + graph (+ optional DeepWiki) and build the output files. */
+declare function analyze(repoRoot: string, opts?: AnalyzeOptions): Promise<AnalyzeResult>;
+/** Regenerate all files to disk. Cleans stale `api/*.md` first. */
+declare function write(repoRoot: string, opts?: AnalyzeOptions): Promise<AnalyzeResult & {
+    written: string[];
+}>;
+/**
+ * Compare the freshly-extracted DETERMINISTIC files against what's committed.
+ * Forces DeepWiki off — the gate only ever inspects the deterministic surface,
+ * so a `WIKI.md` (non-deterministic) never trips it.
+ */
+declare function check(repoRoot: string, opts?: AnalyzeOptions): Promise<CheckResult>;
+
+export { type AnalyzeOptions, type AnalyzeResult, type CartographConfig, type CheckResult, type DeepwikiResult, type Entry, type ExportInfo, type ExportKind, type Meta, type RepoSlug, type Row, type TS, analyze, check, detectRepoSlug, fetchDeepwiki, parseRemoteUrl, write };

package/dist/index.js

@@ -0,0 +1,16 @@
+import {
+  analyze,
+  check,
+  detectRepoSlug,
+  fetchDeepwiki,
+  parseRemoteUrl,
+  write
+} from "./chunk-EKQKRTAN.js";
+export {
+  analyze,
+  check,
+  detectRepoSlug,
+  fetchDeepwiki,
+  parseRemoteUrl,
+  write
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@tangle-network/agent-docs",
+  "version": "0.1.0",
+  "description": "Deterministic repo surface + dependency map for any TypeScript package, with an optional DeepWiki narrative augment for public repos.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "agent-docs": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "tsup && node --test 'tests/*.test.mjs'",
+    "prepublishOnly": "tsup"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": { "optional": false }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tangle-network/agent-docs.git"
+  }
+}