agent-doc-system 0.0.0-stage → 1.0.0

package/core/scaffold.mjs

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+// CREATE-mode scaffolding.
+//
+// Generates a descriptor skeleton from what the repository can actually prove.
+// The generation rules are deliberately conservative:
+//   - a component descriptor is written only for a discovered unit with a name
+//     the unit itself supplies (package name, module path, or directory name);
+//   - a description is a template sentence naming the artifact evidence, never
+//     an invented product claim;
+//   - a placement that cannot be inferred is left out, and the compiler will
+//     report it as a question rather than the scaffolder guessing.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { AgentDocError, CODES } from "./codes.mjs";
+import { Repo } from "./fsx.mjs";
+import { classifyContractFile } from "./contracts.mjs";
+
+const TEMPLATES_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "templates");
+
+function yamlStr(s) {
+  return '"' + String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"') + '"';
+}
+
+function kebab(s) {
+  return String(s)
+    .replace(/^@/, "")
+    .replace(/[_\s]+/g, "-")
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[^A-Za-z0-9-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase()
+    .slice(0, 63) || "component";
+}
+
+function sentence(s) {
+  const t = String(s).replace(/\s+/g, " ").trim();
+  if (!t) return "TODO: describe this in one present-tense sentence.";
+  return /[.!?]$/.test(t) ? t : t + ".";
+}
+
+export function installTemplates(repo, cfg, { write, root, force = false, eligible = null } = {}) {
+  const written = [];
+  const skipped = [];
+  const targetRoot = root || (repo ? repo.root : process.cwd());
+  const r = repo || new Repo(targetRoot, { noGit: false });
+
+  const put = (rel, content) => {
+    const abs = path.join(targetRoot, rel);
+    if (fs.existsSync(abs) && !force) { skipped.push(rel); return; }
+    if (!write) { written.push(rel + " (dry run)"); return; }
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content.endsWith("\n") ? content : content + "\n");
+    written.push(rel);
+  };
+
+  // ── configuration ───────────────────────────────────────────────────────
+  const config = buildConfig(scanLayout(r));
+  put("agentdoc/agentdoc.config.yaml", config);
+  put("agentdoc/journeys.yaml", "schemaVersion: agentdoc.dev/journeys/v1\njourneys: []\n");
+  for (const f of ["domains.yaml", "systems.yaml", "apis.yaml", "resources.yaml"]) {
+    put("agentdoc/" + f, "");
+  }
+  put("agentdoc/observations/README.md", OBSERVATIONS_README);
+
+  // ── documentation hierarchy ──────────────────────────────────────────────
+  for (const f of ["PRODUCT.md", "ARCHITECTURE.md", "CONSTRAINTS.md"]) {
+    const tpl = fs.readFileSync(path.join(TEMPLATES_DIR, f), "utf8");
+    put("docs/" + f, tpl);
+  }
+  put("docs/adr/README.md", fs.readFileSync(path.join(TEMPLATES_DIR, "ADR.md"), "utf8"));
+  put(".github/workflows/agentdoc.yml", fs.readFileSync(path.join(TEMPLATES_DIR, "ci.yml"), "utf8"));
+
+  // ── per-unit component descriptors ──────────────────────────────────────
+  if (cfg) {
+    // When the caller ran the compiler's discovery first, write for the units
+    // the compiler itself counts as eligible — adapter-discovered roots
+    // (go.work members, pnpm workspace packages, supplementalRoots) may have
+    // no marker file the layout scan would find on its own.
+    const units = discoverUnitNames(r, cfg, eligible);
+    for (const u of units) {
+      put(u.root + "/" + cfg.discovery.componentDescriptorName, componentDescriptor(u));
+    }
+  }
+  return { written, skipped, note: write ? "files written" : "dry run: pass --write to apply" };
+}
+
+// Layout inference for CREATE mode: which directories look like unit roots.
+// Uses only file-presence heuristics that any repository can answer.
+function scanLayout(repo) {
+  const candidates = new Map();
+  const note = (root, kind) => {
+    if (!candidates.has(root)) candidates.set(root, { root, kinds: new Set(), evidence: [] });
+    candidates.get(root).kinds.add(kind);
+    candidates.get(root).evidence.push(kind);
+  };
+  const skip = new Set(["node_modules", ".git", "dist", "build", "vendor", "target", "agentdoc", "docs", "scripts", ".github", "test", "tests", "examples", "example"]);
+  const walk = (dir, depth) => {
+    if (depth > 3) return;
+    let entries;
+    try { entries = fs.readdirSync(path.join(repo.root, dir), { withFileTypes: true }); } catch { return; }
+    for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      if (e.isSymbolicLink() || skip.has(e.name)) continue;
+      const rel = dir ? dir + "/" + e.name : e.name;
+      if (e.isDirectory()) {
+        if (e.name.startsWith(".")) continue;
+        walk(rel, depth + 1);
+        continue;
+      }
+      // Parent directory of the manifest. Parenthesised deliberately: without
+      // the brackets, `-"/" + e.name` binds first and slice(0, NaN) silently
+      // yields the empty string, which then crashes the layout analysis.
+      const parent = () => rel.slice(0, -("/" + e.name).length);
+      if (e.name === "package.json") note(parent(), "node");
+      if (e.name === "go.mod") note(parent(), "go");
+      if (e.name === "Dockerfile") note(parent(), "docker");
+      if (/^wrangler\.(toml|json|jsonc)$/.test(e.name)) note(parent(), "platform");
+      if (e.name === "go.mod") note(rel.slice(0, -"/go.mod".length), "go");
+    }
+  };
+  walk("", 0);
+  return [...candidates.values()].sort((a, b) => (a.root < b.root ? -1 : 1));
+}
+
+function discoverUnitNames(repo, cfg, eligible = null) {
+  const out = [];
+  const nameFor = (root) => {
+    const pkg = root + "/package.json";
+    if (repo.exists(pkg)) {
+      try {
+        const j = repo.readJson(pkg);
+        if (typeof j.name === "string" && j.name) return kebab(j.name);
+      } catch { /* fall through */ }
+    }
+    const gomod = root + "/go.mod";
+    if (repo.exists(gomod)) {
+      const m = /^module\s+(\S+)/m.exec(repo.readText(gomod));
+      if (m) return kebab(m[1].split("/").pop());
+    }
+    return kebab(path.basename(root));
+  };
+  const seen = new Set();
+  const seenRoots = new Set();
+  // Union, not replacement: compiler-eligible units (adapter roots,
+  // supplementalRoots) cover what markers cannot see, while the layout scan
+  // still covers marker-bearing dirs that no adapter claims.
+  const units = [
+    ...(eligible || []).map((u) => ({
+      root: u.root,
+      kinds: (u.markers || []).map((m) => m.adapter).sort(),
+      deployable: Boolean(u.deployable),
+      importable: Boolean(u.importable),
+    })),
+    ...scanLayout(repo).map((u) => ({ root: u.root, kinds: [...u.kinds].sort(), deployable: false, importable: false })),
+  ];
+  for (const u of units) {
+    if (u.root === "." || !u.root || seenRoots.has(u.root)) continue;
+    seenRoots.add(u.root);
+    const name = nameFor(u.root);
+    if (seen.has(name)) continue;
+    seen.add(name);
+    out.push({ ...u, name });
+  }
+  void cfg;
+  return out;
+}
+
+function componentDescriptor(u) {
+  const deployable = u.deployable || u.kinds.some((k) => k === "docker" || k === "platform");
+  const importable = u.importable || u.kinds.some((k) => k === "node" || k === "go");
+  // "library" and "service" both have to be corroborated by artifact evidence
+  // (AGENTDOC_ARTIFACT_TYPE); a unit the compiler only knows from configuration
+  // shows neither, so claiming a concrete type would manufacture an error.
+  const type = deployable ? "service" : importable ? "library" : "other";
+  return [
+    "apiVersion: agentdoc.dev/v1",
+    "kind: Component",
+    "metadata:",
+    "  name: " + u.name,
+    "  description: " + yamlStr(sentence("TODO: " + u.name + " (" + (u.kinds.length ? u.kinds.join("/") : "configured") + " at " + u.root + ") — state its single current responsibility")),
+    "spec:",
+    "  type: " + type,
+    "  # Choose exactly one of the three lines below. Uncomment one.",
+    "  # system: <system-name>",
+    "  # domain: <domain-name>",
+    "  # placementRationale: " + yamlStr(sentence("TODO: explain why this component belongs to no system or domain")),
+    "",
+  ].join("\n");
+}
+
+// Which adapter a discovered manifest marker implies. Project-agnostic: this
+// maps a technology to its extractor, never a folder name to a component.
+const ADAPTER_FOR_MARKER = {
+  node: "node",
+  go: "go",
+  docker: "dockerfile",
+  platform: "wrangler",
+};
+
+function buildConfig(layout) {
+  const roots = layout.map((l) => l.root);
+  const groups = new Map();
+  for (const r of roots) {
+    const head = r.split("/")[0];
+    if (!groups.has(head)) groups.set(head, []);
+    groups.get(head).push(r);
+  }
+  // A manifest at the repository root yields an empty head; emitting
+  // "/agentdoc.yaml" would be an absolute glob, which the loader rejects.
+  const componentGlobs = [...groups.entries()]
+    .filter(([head]) => head.length > 0)
+    .sort((a, b) => (a[0] < b[0] ? -1 : 1))
+    .map(([head, list]) => (list.length === 1 && list[0] === head ? head + "/agentdoc.yaml" : head + "/**/agentdoc.yaml"));
+  if (!componentGlobs.length) componentGlobs.push("*/**/agentdoc.yaml");
+
+  const adapters = new Set(["generic"]);
+  for (const l of layout) {
+    for (const k of l.kinds) {
+      if (ADAPTER_FOR_MARKER[k]) adapters.add(ADAPTER_FOR_MARKER[k]);
+    }
+  }
+  adapters.add("database");
+  adapters.add("openapi");
+  adapters.add("events");
+  adapters.add("github-actions");
+
+  // Candidate contract roots, filtered to those that actually exist. These are
+  // only suggestions: the engine has no opinion about a folder name.
+  const contractRoots = ["contracts", "api", "specs", "proto", "openapi", "schemas"].filter((r) => groups.has(r) || r === "");
+  return [
+    "# agentdoc configuration — the only project-specific file in the system.",
+    "# Everything the engine does is derived from this plus the repository.",
+    "apiVersion: agentdoc.dev/config/v1",
+    "# namespace prefixes every entity ref (component:<namespace>/<name>).",
+    "# 'default' is a placeholder — pick the name this repository calls itself.",
+    "namespace: default",
+    "",
+    "discovery:",
+    "  componentDescriptorName: agentdoc.yaml",
+    "  componentDescriptors:",
+    // Globs are quoted: an unquoted leading "*" is an alias in strict YAML,
+    // and a configuration the compiler cannot parse is worse than none.
+    ...componentGlobs.map((g) => "    - " + yamlStr(g)),
+    "  centralDescriptors:",
+    "    - agentdoc/domains.yaml",
+    "    - agentdoc/systems.yaml",
+    "    - agentdoc/apis.yaml",
+    "    - agentdoc/resources.yaml",
+    "  journeyDefinitions: agentdoc/journeys.yaml",
+    ...(contractRoots.filter((r) => groups.has(r)).length
+      ? ["  contractRoots:", ...contractRoots.filter((r) => groups.has(r)).map((r) => "    - " + r)]
+      : ["  # contractRoots: []  # uncomment once you have a canonical contract directory"]),
+    "  # eventPatternPrefixes:",
+    "  #   - acme.",
+    "",
+    "adapters:",
+    ...[...adapters].sort().map((a) => "  - " + a),
+    "",
+    "authority:",
+    "  # No default global precedence exists. Every fact kind that can disagree",
+    "  # across evidence classes needs an explicit rule, or it stays unresolved.",
+    "  #",
+    "  # The three rules below are COMMENTED OUT ON PURPOSE. An authority rule is a",
+    "  # governance decision about which class of evidence wins, and a scaffolder is",
+    "  # not entitled to make it for you. Uncomment the ones you can justify, and",
+    "  # write the rationale in your own words:",
+    "  #",
+    "  # rules:",
+    "  #   - id: deployed-schedule-is-runtime-truth",
+    "  #     keyPattern: ' schedule\\\\.(cron|enabled|target)$'",
+    "  #     elect: [OBSERVED_RUNTIME]",
+    '  #     rationale: "Why this class is authoritative for this key."',
+    '  #     reviewWhen: "What has to change for this rule to be re-examined."',
+    "  rules: []",
+    "",
+    "reviewedOverrides: []",
+    "warningAcceptances: []",
+    "",
+    "output:",
+    "  graph: .agentdoc/graph.json",
+    "  observations: agentdoc/observations",
+    "",
+    "docs:",
+    "  product: docs/PRODUCT.md",
+    "  architecture: docs/ARCHITECTURE.md",
+    "  constraints: docs/CONSTRAINTS.md",
+    "  adrDir: docs/adr",
+    "",
+  ].join("\n");
+}
+
+const OBSERVATIONS_README = `# Runtime observations
+
+An ObservationSet records what an authoritative external system actually said,
+at a known time, with a durable reference to the raw evidence.
+
+## Rules
+
+1. Never put a secret, token or credentialed URL in an observation, an evidence
+   bundle, or anywhere else in this directory. Run \`agentdoc validate\`; it
+   fails on secret-shaped input.
+2. Every fact needs a \`subject\` (an entity ref that exists) and a \`key\`
+   (see "Fact keys" in the AgentDoc specification,
+   docs/SPEC.md of https://github.com/lbframe/agent-doc-system). Two
+   observation sets must not use the same key on the same subject.
+3. \`evidenceBundle\` must be a committed, repository-relative file. A temp
+   path, a console URL with a session token, or a screenshot filename is not
+   evidence.
+4. \`maxAgeDays\` is a promise. When the observation is older than that, every
+   gate fails closed and says so. Re-observe, or restate the fact as authored
+   intent if the divergence is intended.
+
+## Shape
+
+See the \`observation.yaml\` template shipped with the agentdoc CLI
+(templates/observation.yaml in the installed package).
+`;
+
+export function templatePaths() {
+  return { dir: TEMPLATES_DIR };
+}

package/core/secrets.mjs

@@ -0,0 +1,92 @@
+// Secret material must never reach the compiled graph, a report, a log line,
+// or a prompt. Two layers:
+//
+//  1. Source scanning — every authored/observed document is scanned before it
+//     can influence any output.
+//  2. Output scanning — the serialized graph, every report and every query
+//     payload is scanned again, because derivations and extractor heuristics can
+//     synthesize a secret-shaped string that no source scan would have caught.
+import { AgentDocError, CODES } from "./codes.mjs";
+
+const PATTERNS = [
+  { re: /-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----/, why: "private key material" },
+  { re: /\bAKIA[0-9A-Z]{16}\b/, why: "AWS-style access key id" },
+  { re: /\bASIA[0-9A-Z]{16}\b/, why: "AWS-style temporary access key id" },
+  { re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/, why: "GitHub token" },
+  { re: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/, why: "GitHub fine-grained token" },
+  { re: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/, why: "Slack token" },
+  { re: /\bsk-[A-Za-z0-9]{20,}\b/, why: "provider secret key" },
+  { re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/, why: "JWT-shaped token" },
+  { re: /\b[a-z][a-z0-9+.-]*:\/\/[^\s/@]+:[^\s/@]+@/, why: "URL with embedded credentials" },
+  {
+    re: /\b(?:secret|password|passwd|passphrase|token|api[_-]?key|private[_-]?key|client[_-]?secret|auth[_-]?token)\b\s*[:=]\s*["']?[^\s"',;]{8,}/i,
+    why: "credential assignment",
+  },
+  { re: /\bBearer\s+[A-Za-z0-9._~+/-]{20,}=*/, why: "bearer token" },
+  { re: /\b(?:curl|wget)\b[^\n]*\s-[a-z]*u\s+\S+:\S+/i, why: "inline credentials on a command line" },
+  { re: /\bAuthorization\s*[:=]\s*["']?[^\s"']{8,}/i, why: "authorization header value" },
+  { re: /\baws_secret_access_key\b\s+\S{16,}/i, why: "AWS secret access key" },
+  { re: /\b(?:api[_-]?key|apikey|access[_-]?token|auth[_-]?token)\b\s+["']?[A-Za-z0-9_\-]{16,}/i, why: "credential passed as an argument" },
+];
+
+function scanString(value, where) {
+  // Values this system already redacted are not secrets. Removing the marker
+  // before matching stops the output scanner from refusing to emit its own
+  // redaction, which would make a redacted command unusable.
+  const v = String(value).replace(/\[REDACTED[^\]]*\]/g, "");
+  for (const { re, why } of PATTERNS) {
+    if (re.test(v)) {
+      throw new AgentDocError(CODES.SECRET, "secret-like value (" + why + ") at " + where + ": agentdoc sources and outputs must never contain credentials", {});
+    }
+  }
+}
+
+// Recursive scan of an in-memory document.
+export function scanForSecrets(node, path, pointer = "") {
+  if (node == null) return;
+  if (typeof node === "string") return scanString(node, pointer || "/");
+  if (typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    node.forEach((item, i) => scanForSecrets(item, path, pointer + "/" + i));
+    return;
+  }
+  for (const [k, v] of Object.entries(node)) {
+    scanForSecrets(v, path, pointer + "/" + k.replace(/~/g, "~0").replace(/\//g, "~1"));
+  }
+}
+
+// Scan serialized text (a graph, a report, a query payload). Throws on the
+// first hit; the caller decides whether that is fatal.
+export function assertNoSecretsInText(text, what) {
+  const scrubbed = String(text).replace(/\[REDACTED[^\]]*\]/g, "");
+  for (const { re, why } of PATTERNS) {
+    const m = re.exec(scrubbed);
+    if (m) {
+      throw new AgentDocError(
+        CODES.SECRET,
+        "refusing to emit " + what + ": secret-like value (" + why + ") near offset " + m.index
+      );
+    }
+  }
+}
+
+// Verification commands are a routing index, not a credential transport. Keep
+// the runnable shape; strip any inline assignment or DSN password.
+const SECRET_NAME = /(?:SECRET|TOKEN|PASSWORD|PASSWD|PASSPHRASE|API_?KEY|PRIVATE_?KEY|CREDENTIAL|ACCESS_?KEY)/i;
+
+export function redactCommand(command) {
+  return String(command)
+    // Assignment form. The name is matched structurally and then tested, rather
+    // than by a single backtracking pattern: "API_KEY" must be recognised as
+    // an API key, which a greedy name group would swallow whole.
+    .replace(/\b([A-Za-z_][A-Za-z0-9_]*)=([^\s;"'`]+)/g, (m, name, value) =>
+      SECRET_NAME.test(name) ? name + "=[REDACTED]" : m)
+    .replace(/\b((?:postgres|postgresql|mysql|mongodb(?:\+srv)?|redis|amqp|https?):\/\/)[^:@/\s]+:[^@/\s]+@/gi,
+      "$1[REDACTED]@")
+    .replace(/\b(Bearer\s+)[A-Za-z0-9._~+/-]{12,}=*/g, "$1[REDACTED]")
+    // `curl -u user:pass` and `<credential-name> <value>` as separate arguments.
+    .replace(/(\s-[a-zA-Z]*u\s+)(\S+):(\S+)/g, "$1$2:[REDACTED]")
+    .replace(/\b(aws_secret_access_key|aws_access_key_id)(\s+)([A-Za-z0-9/+=]{12,})/gi, "$1$2[REDACTED]")
+    .replace(/\b(Authorization)(\s*[:=]\s*)(\S{8,})/gi, "$1$2[REDACTED]")
+    .replace(/\b(api[_-]?key|apikey|access[_-]?token|auth[_-]?token)(\s+)(["']?)([A-Za-z0-9_-]{16,})/gi, "$1$2$3[REDACTED]");
+}

package/core/sourcescan.mjs

@@ -0,0 +1,88 @@
+// Source scanning primitives shared by adapters.
+//
+// The extraction of quoted module specifiers is language-neutral: a bare
+// identifier in quotes that is not a relative path is a candidate dependency
+// reference in practically every language. Deciding whether that reference
+// resolves to a sibling unit is the adapter's job, because only the adapter
+// knows the namespace convention.
+import path from "node:path";
+import fs from "node:fs";
+
+const SPECIFIER_RE = /["'`]([A-Za-z@][A-Za-z0-9@._/+-]*(?:\.[A-Za-z0-9@._/+-]+)*(?:\/[A-Za-z0-9@._+*-]+)*)["'`]/g;
+
+export function importSpecifiers(text) {
+  const out = new Set();
+  for (const m of text.matchAll(SPECIFIER_RE)) {
+    const s = m[1];
+    if (s.startsWith(".") || s.startsWith("/")) continue;
+    if (s.length < 2) continue;
+    out.add(s);
+  }
+  return out;
+}
+
+export function sourceFiles(repo, root, { test = false, extensions } = {}) {
+  const TEST_PATH = /(^|\/)(tests?|__tests__|spec)\//;
+  const TEST_FILE = /\.(test|spec)\./;
+  const DEFAULT_EXT = /\.(ts|tsx|js|jsx|mts|cts|mjs|cjs|go|py|rb|java|kt|rs|ex|exs|cs|php|swift|scala|sh)$/;
+  const re = extensions || DEFAULT_EXT;
+  const out = [];
+  for (const f of repo.walk(root)) {
+    if (!re.test(f)) continue;
+    const isTest = TEST_PATH.test(f) || TEST_FILE.test(f) || /_test\.[a-z]+$/.test(f);
+    if (isTest !== test) continue;
+    out.push(f);
+  }
+  return out;
+}
+
+// Directory candidates that hold schema migrations or an ORM schema. Used to
+// find "this component owns a database" evidence without assuming a framework.
+export const MIGRATION_DIR_CANDIDATES = [
+  "migrations", "db/migrations", "database/migrations", "internal/db/migrations",
+  "internal/migrations", "src/db/migrations", "alembic/versions", "liquibase",
+];
+
+// Any directory named "migrations" inside a unit, at bounded depth. Framework
+// and language conventions move; the name of a migration directory has been
+// stable for far longer than its location.
+export function findMigrationDirs(repo, root, maxDepth = 5) {
+  const out = [];
+  // Absolute paths throughout: `root` is repository-relative, and resolving it
+  // against the process working directory would make the result depend on
+  // where the compiler was invoked from.
+  const base = repo.abs(root);
+  const walk = (dirAbs, depth) => {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dirAbs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      if (!e.isDirectory() || e.isSymbolicLink()) continue;
+      if (["node_modules", ".git", "vendor", "target", "dist", "build", ".next", "__pycache__"].includes(e.name)) continue;
+      const abs = path.join(dirAbs, e.name);
+      if (e.name === "migrations" || e.name === "migration") {
+        out.push(path.relative(repo.root, abs).split(path.sep).join("/"));
+        continue;
+      }
+      walk(abs, depth + 1);
+    }
+  };
+  walk(base, 0);
+  return out.sort();
+}
+
+export function firstExistingFile(repo, root, names) {
+  for (const n of names) {
+    if (repo.exists(root + "/" + n)) return root + "/" + n;
+  }
+  return null;
+}
+
+export function relativeTo(root, p) {
+  const r = path.posix.relative(root, p);
+  return r === "" ? "." : r;
+}

package/core/toml.mjs

@@ -0,0 +1,163 @@
+// Minimal TOML reader for platform deployment manifests.
+//
+// Only what a deployment manifest needs: tables, arrays of tables, key/value
+// pairs, strings, integers, booleans, inline arrays and inline tables. Anything
+// richer is rejected rather than guessed at, because a mis-parsed manifest
+// would produce confident nonsense about deployed state.
+import { AgentDocError, CODES } from "./codes.mjs";
+
+export function parse(src, path = "") {
+  const root = {};
+  let cur = root;
+  const lines = String(src).split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = stripComment(lines[i]).trim();
+    if (!line) continue;
+    const table = /^\[\[?([^\]]+)\]\]?$/.exec(line);
+    if (table) {
+      const isArray = line.startsWith("[[");
+      const keys = splitKeyPath(table[1]);
+      cur = root;
+      for (let k = 0; k < keys.length; k++) {
+        const key = keys[k];
+        const last = k === keys.length - 1;
+        if (last && isArray) {
+          if (!Array.isArray(cur[key])) cur[key] = [];
+          const obj = {};
+          cur[key].push(obj);
+          cur = obj;
+        } else {
+          if (cur[key] === undefined) cur[key] = {};
+          cur = cur[key];
+        }
+      }
+      continue;
+    }
+    const eq = findEquals(line);
+    if (eq < 0) {
+      throw new AgentDocError(CODES.YAML_PARSE, "unparseable TOML line " + (i + 1) + (path ? " in " + path : ""), { path, line: i + 1 });
+    }
+    const key = unquoteKey(line.slice(0, eq).trim());
+    let valueText = line.slice(eq + 1).trim();
+    // Multi-line arrays.
+    while (unbalanced(valueText) && i + 1 < lines.length) {
+      i++;
+      valueText += " " + stripComment(lines[i]).trim();
+    }
+    const keys = splitKeyPath(key);
+    let target = cur;
+    for (let k = 0; k < keys.length - 1; k++) {
+      if (target[keys[k]] === undefined) target[keys[k]] = {};
+      target = target[keys[k]];
+    }
+    target[keys[keys.length - 1]] = value(valueText, path, i + 1);
+  }
+  return root;
+}
+
+function unbalanced(s) {
+  let b = 0;
+  let q = null;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (q) { if (c === "\\") { i++; continue; } if (c === q) q = null; continue; }
+    if (c === '"' || c === "'") { q = c; continue; }
+    if (c === "[" || c === "{") b++;
+    if (c === "]" || c === "}") b--;
+  }
+  return b > 0;
+}
+
+function stripComment(s) {
+  let q = null;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (q) { if (c === "\\" && q === '"') { i++; continue; } if (c === q) q = null; continue; }
+    if (c === '"' || c === "'") { q = c; continue; }
+    if (c === "#") return s.slice(0, i);
+  }
+  return s;
+}
+
+function findEquals(line) {
+  let q = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (q) { if (c === "\\" && q === '"') { i++; continue; } if (c === q) q = null; continue; }
+    if (c === '"' || c === "'") { q = c; continue; }
+    if (c === "=") return i;
+  }
+  return -1;
+}
+
+function splitKeyPath(s) {
+  return s.split(".").map((k) => unquoteKey(k.trim()));
+}
+
+function unquoteKey(k) {
+  if ((k.startsWith('"') && k.endsWith('"')) || (k.startsWith("'") && k.endsWith("'"))) return k.slice(1, -1);
+  return k;
+}
+
+function value(t, path, line) {
+  if (t === "true") return true;
+  if (t === "false") return false;
+  if (/^".*"$/.test(t)) return JSON.parse(t.replace(/\\'/g, "'"));
+  if (/^'.*'$/.test(t)) return t.slice(1, -1);
+  if (/^-?\d+$/.test(t)) return Number(t);
+  if (/^-?\d+\.\d+$/.test(t)) return Number(t);
+  if (t.startsWith("[")) return parseArray(t, path, line);
+  if (t.startsWith("{")) return parseInlineTable(t, path, line);
+  if (t === "") return "";
+  return t;
+}
+
+function parseArray(t, path, line) {
+  const inner = t.slice(1, -1).trim();
+  if (!inner) return [];
+  const out = [];
+  let buf = "";
+  let q = null;
+  let depth = 0;
+  for (let i = 0; i < inner.length; i++) {
+    const c = inner[i];
+    if (q) { buf += c; if (c === "\\") { buf += inner[++i] || ""; continue; } if (c === q) q = null; continue; }
+    if (c === '"' || c === "'") { q = c; buf += c; continue; }
+    if (c === "[" || c === "{") { depth++; buf += c; continue; }
+    if (c === "]" || c === "}") { depth--; buf += c; continue; }
+    if (c === "," && depth === 0) { out.push(value(buf.trim(), path, line)); buf = ""; continue; }
+    buf += c;
+  }
+  if (buf.trim()) out.push(value(buf.trim(), path, line));
+  return out;
+}
+
+function parseInlineTable(t, path, line) {
+  const inner = t.slice(1, -1).trim();
+  const out = {};
+  if (!inner) return out;
+  for (const part of splitTop(inner)) {
+    const eq = findEquals(part);
+    if (eq < 0) continue;
+    out[unquoteKey(part.slice(0, eq).trim())] = value(part.slice(eq + 1).trim(), path, line);
+  }
+  return out;
+}
+
+function splitTop(s) {
+  const out = [];
+  let buf = "";
+  let q = null;
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (q) { buf += c; if (c === "\\") { buf += s[++i] || ""; continue; } if (c === q) q = null; continue; }
+    if (c === '"' || c === "'") { q = c; buf += c; continue; }
+    if (c === "[" || c === "{") { depth++; buf += c; continue; }
+    if (c === "]" || c === "}") { depth--; buf += c; continue; }
+    if (c === "," && depth === 0) { out.push(buf.trim()); buf = ""; continue; }
+    buf += c;
+  }
+  if (buf.trim()) out.push(buf.trim());
+  return out;
+}