@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/core/links/parse.js

@@ -0,0 +1,265 @@
+/**
+ * Every markdown link a document writes, as data.
+ *
+ * A link between documents in a docs repo is a JOIN, not decoration — a
+ * requirement that names a domain term points at that term's definition, and an
+ * ADR that supersedes another says which. `SCHEMA.md` and the generated
+ * `AGENTS.md` have stated the convention (standard markdown links, relative
+ * path targets) since the fleet-ADR work; this module is what finally reads
+ * one, so `./findings.ts` can answer the only question the convention was
+ * chosen for: does the target exist.
+ *
+ * WHY A PARSER RATHER THAN A REGEX AT THE CALL SITE. Two classes of false
+ * positive make the naive `\[.*\]\(.*\)` unusable on the documents loam owns,
+ * and both occur in loam's OWN generated prose. A fenced block is where a
+ * document SHOWS the convention — the `AGENTS.md` section that teaches the link
+ * format contains a link nobody wrote to be followed — and an inline code span
+ * is where prose quotes a path. Both must read as text. The fence rule is the
+ * one `core/document/parse.ts` already applies to headings, and it is imported
+ * rather than restated for the reason that module gives about its own sampler:
+ * two readers disagreeing about what a fence encloses prescribe a document no
+ * author can satisfy.
+ */
+import { relative, resolve, sep } from "node:path";
+import { fenceTracker } from "../kernel/fences.js";
+/**
+ * Inline links and images: `[text](target)`, `![alt](target)`,
+ * `[text](<target with spaces>)`, `[text](target "title")`.
+ *
+ * The target alternation takes `<...>` first so an angle-bracketed path
+ * containing spaces stays one token; the bare form stops at whitespace or `)`,
+ * which gives up on the balanced-parens spelling markdown also allows
+ * (`[x](a(1).md)`). That is a deliberate under-read: it costs a link nobody
+ * writes, where over-reading would swallow the rest of a sentence and report a
+ * target no author would recognise.
+ */
+const INLINE_RE = /!?\[([^\]]*)\]\(\s*(<[^>\n]*>|[^\s)]*)(?:\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\s*\)/gd;
+/**
+ * A reference DEFINITION — `[label]: target "title"` on its own line. Included
+ * because the target is the same join written in a different place: a document
+ * that collects its links at the bottom is following the convention, and a
+ * reader that only saw inline links would grade it as having none.
+ */
+const DEFINITION_RE = /^ {0,3}\[([^\]]+)\]:\s*(<[^>\n]*>|\S+)/d;
+/**
+ * Code spans, blanked before matching. `\`[a](b)\`` is prose ABOUT a link and
+ * resolving it would convict a document for explaining the convention. Blanked
+ * to spaces rather than removed so every column after it — and therefore any
+ * real link later on the same line — keeps its position.
+ */
+const CODE_SPAN_RE = /(`+)(?:[^`]|(?!\1)`)*\1/g;
+/**
+ * Every link in `md`, in document order.
+ *
+ * The whole document is scanned, frontmatter included: a YAML `see: [x](y.md)`
+ * is not a link loam wrote a field for, and the alternative — teaching this
+ * module where frontmatter ends — would make it read the one part of a document
+ * loam's own doctrine says is structured. A link that resolves is a link that
+ * resolves wherever it is written.
+ */
+export function documentLinks(md) {
+    const fenced = fenceTracker();
+    const out = [];
+    md.split(/\r?\n/).forEach((rawLine, i) => {
+        if (fenced(rawLine))
+            return;
+        const line = rawLine.replace(CODE_SPAN_RE, (m) => " ".repeat(m.length));
+        const definition = DEFINITION_RE.exec(line);
+        if (definition) {
+            push(out, definition[2], definition[1], i + 1);
+            return;
+        }
+        INLINE_RE.lastIndex = 0;
+        for (let m = INLINE_RE.exec(line); m !== null; m = INLINE_RE.exec(line)) {
+            push(out, m[2], m[1], i + 1);
+        }
+    });
+    return out;
+}
+/**
+ * Record one link, unless its target is not a path this repository can answer
+ * for. Four exclusions, each of them a question with no filesystem answer
+ * rather than a link loam declines to grade:
+ *
+ * - an EMPTY target (`[text]()`) addresses nothing;
+ * - a SCHEME (`https:`, `mailto:`, and a Windows `C:` drive with it) addresses
+ *   something outside this repository;
+ * - a ROOT-relative or protocol-relative target (`/x`, `//host/x`) is resolved
+ *   by whatever renders the document — a site root, not the file's directory —
+ *   so loam does not know what it points at;
+ * - a PURE fragment (`#section`) addresses this same document, and grading it
+ *   means resolving heading anchors, which is a different question from "does
+ *   this file exist".
+ *
+ * The last two are DEFENSIVE rather than decisive, and a mutation run says so:
+ * removing either leaves every test green, because a pure fragment leaves an
+ * empty path and a site-root target resolves outside the docs repo, where
+ * `./findings.ts` declines to answer anyway. They are kept because the reason
+ * differs from that boundary's — loam is not silent about these because they
+ * are elsewhere, it is silent because it does not know where they are — and a
+ * later reader deleting them as dead would be removing an intention, not a
+ * branch.
+ */
+function push(out, target, text, line) {
+    const raw = target.startsWith("<") && target.endsWith(">") ? target.slice(1, -1) : target;
+    if (raw === "" || raw.startsWith("#") || raw.startsWith("/"))
+        return;
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(raw))
+        return;
+    const path = decodePath(raw.split("#")[0]);
+    if (path === "")
+        return;
+    out.push({ raw, path, text, line });
+}
+/**
+ * Percent-decode a link target, or keep it verbatim when it does not decode.
+ *
+ * `[Order line](order%20line.md)` is how every editor writes a path holding a
+ * space, so a resolver that skipped this step would report the one spelling
+ * authors do not type by hand. `decodeURIComponent` throws on a lone `%` — a
+ * literal percent in a filename is legal and rarer than the escape — and the
+ * honest answer there is the string as written, which then resolves or does not
+ * on its own terms.
+ */
+function decodePath(raw) {
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+/**
+ * Re-express every relative link in `md` from a new base directory — the merge's
+ * half of the link convention.
+ *
+ * THE DEFECT THIS CLOSES is structural and predates the glossary. A feature's
+ * `specs/<svc>/spec.md` sits four directories below the docs root; the living
+ * `services/<svc>/spec.md` it merges into sits two. `loam archive` copies a
+ * requirement's text verbatim, so `[Order](../../../../glossary/order.md)` —
+ * correct where it was written, and clickable in the pull request that reviewed
+ * it — lands in the living document pointing two directories above the
+ * repository. The same is true of a delta requirement citing an ADR, which has
+ * been possible since before this module existed.
+ *
+ * REWRITING IS THE ONLY ANSWER THAT KEEPS BOTH PROPERTIES. The alternative
+ * considered was to have authors write the link relative to where the text will
+ * END UP, leaving loam to touch nothing — but that link does not resolve in the
+ * delta, and "it renders as a link in pull-request review, which is where these
+ * documents are actually read" is the convention's own first argument. So the
+ * author writes what is true where they write it, and the merge makes it true
+ * where it lands. The target is unchanged: only the route to it is.
+ *
+ * It is a positional rewrite, never a re-render: the matched target's own span
+ * is replaced and every other byte of the line — the link text, the title, the
+ * prose around it — is left exactly as written.
+ *
+ * WHEN THE TARGET MOVES TOO, `retarget` says where to. The same archive that
+ * moves a requirement two directories up moves the rest of the feature as
+ * well: a term the feature defines is copied into `glossary/`, and the feature
+ * directory itself — its ADRs, its intent — goes to `features/archive/<FEAT>/`.
+ * A link into the feature re-expressed against the target's OLD place was
+ * therefore re-expressed correctly and still rotted on the commit that made it.
+ * And a document that does not move at all can still need rewriting, when the
+ * directory it links into does (`subsystem move`) — which is why `from === to`
+ * is no longer a reason to stop when a `retarget` is given.
+ *
+ * A LINK WHOSE TEXT STILL REACHES ITS TARGET FROM THE NEW PLACE KEEPS ITS
+ * SPELLING: a sibling that moves with its document, or a target nothing moved
+ * under a document that stays, comes out of the rewrite exactly as the author
+ * wrote it rather than normalised into `./` form by a commit that had no
+ * reason to touch it.
+ */
+export function rebaseLinks(md, move) {
+    const from = resolve(move.from);
+    const to = resolve(move.to);
+    if (from === to && move.retarget === undefined)
+        return md;
+    const route = { from, to, retarget: move.retarget ?? ((target) => target) };
+    const fenced = fenceTracker();
+    // `split` with a capturing group keeps the separators, so a document's own
+    // mixture of CRLF and LF survives a rewrite that touches neither.
+    const parts = md.split(/(\r?\n)/);
+    for (let i = 0; i < parts.length; i += 2) {
+        const rawLine = parts[i];
+        if (fenced(rawLine))
+            continue;
+        parts[i] = rebaseLine(rawLine, route);
+    }
+    return parts.join("");
+}
+/** One line's links re-expressed, right to left so earlier spans keep their offsets. */
+function rebaseLine(rawLine, route) {
+    const blanked = rawLine.replace(CODE_SPAN_RE, (m) => " ".repeat(m.length));
+    const spans = [];
+    const collect = (m) => {
+        const at = m.indices?.[2];
+        if (at === undefined)
+            return;
+        const rebased = rebaseTarget(m[2], route);
+        if (rebased !== null)
+            spans.push([at[0], at[1], rebased]);
+    };
+    const definition = DEFINITION_RE.exec(blanked);
+    if (definition)
+        collect(definition);
+    else {
+        INLINE_RE.lastIndex = 0;
+        for (let m = INLINE_RE.exec(blanked); m !== null; m = INLINE_RE.exec(blanked))
+            collect(m);
+    }
+    let out = rawLine;
+    for (const [start, end, replacement] of spans.reverse()) {
+        out = out.slice(0, start) + replacement + out.slice(end);
+    }
+    return out;
+}
+/**
+ * One target, re-expressed from `to` instead of `from` — and pointed at wherever
+ * `retarget` says the file itself will be — or null when there is nothing to
+ * re-express.
+ *
+ * The exclusions are `push`'s exactly — an absolute URL, a site-root path and a
+ * bare fragment mean the same thing from every directory — and the ANGLE-BRACKET
+ * and PERCENT-ESCAPE forms are preserved rather than normalised: a rewrite that
+ * silently changed `<a b.md>` into `a%20b.md` would be editing the author's
+ * spelling under cover of moving their file. A route that comes out unchanged
+ * is null for the same reason (`rebaseLinks` says when that happens).
+ */
+function rebaseTarget(target, route) {
+    const angled = target.startsWith("<") && target.endsWith(">");
+    const raw = angled ? target.slice(1, -1) : target;
+    if (raw === "" || raw.startsWith("#") || raw.startsWith("/"))
+        return null;
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(raw))
+        return null;
+    const hash = raw.indexOf("#");
+    const pathPart = hash === -1 ? raw : raw.slice(0, hash);
+    const fragment = hash === -1 ? "" : raw.slice(hash);
+    if (pathPart === "")
+        return null;
+    const encoded = pathPart.includes("%");
+    const was = resolve(route.from, decodePath(pathPart));
+    const will = resolve(route.retarget(was));
+    // The author's TEXT, read from the new place, still reaching the target —
+    // not two computed routes compared. A link that climbs above a moved
+    // directory and comes back down through its old name
+    // (`../../../services/payment-service/spec.md` from inside that service)
+    // normalises to the same route either side of the move, and comparing
+    // routes kept a spelling that names a directory the move just removed.
+    if (resolve(route.to, decodePath(pathPart)) === will)
+        return null;
+    let rebased = relative(route.to, will).split(sep).join("/");
+    // `relative` returns a bare name for a sibling, which markdown reads as a
+    // path relative to the file anyway — but `./` is what an author writes and
+    // what keeps the link distinguishable from a reference label.
+    if (rebased !== "" && !rebased.startsWith("."))
+        rebased = `./${rebased}`;
+    if (rebased === "")
+        return null;
+    if (!angled && (encoded || rebased.includes(" ")))
+        rebased = rebased.split(" ").join("%20");
+    const rewritten = rebased + fragment;
+    return angled ? `<${rewritten}>` : rewritten;
+}
+//# sourceMappingURL=parse.js.map

package/dist/core/links/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../../src/core/links/parse.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Every markdown link a document writes, as data.\n *\n * A link between documents in a docs repo is a JOIN, not decoration — a\n * requirement that names a domain term points at that term's definition, and an\n * ADR that supersedes another says which. `SCHEMA.md` and the generated\n * `AGENTS.md` have stated the convention (standard markdown links, relative\n * path targets) since the fleet-ADR work; this module is what finally reads\n * one, so `./findings.ts` can answer the only question the convention was\n * chosen for: does the target exist.\n *\n * WHY A PARSER RATHER THAN A REGEX AT THE CALL SITE. Two classes of false\n * positive make the naive `\\[.*\\]\\(.*\\)` unusable on the documents loam owns,\n * and both occur in loam's OWN generated prose. A fenced block is where a\n * document SHOWS the convention — the `AGENTS.md` section that teaches the link\n * format contains a link nobody wrote to be followed — and an inline code span\n * is where prose quotes a path. Both must read as text. The fence rule is the\n * one `core/document/parse.ts` already applies to headings, and it is imported\n * rather than restated for the reason that module gives about its own sampler:\n * two readers disagreeing about what a fence encloses prescribe a document no\n * author can satisfy.\n */\nimport { relative, resolve, sep } from \"node:path\";\nimport { fenceTracker } from \"../kernel/fences.js\";\n\n/** One link written in a markdown document. */\nexport interface DocumentLink {\n  /** The target exactly as written, angle brackets stripped, fragment included. */\n  raw: string;\n  /**\n   * The FILE half — `raw` with any `#fragment` removed and percent-escapes\n   * decoded. This is what resolves against the filesystem; `raw` is what the\n   * finding quotes back, because that is the string the author has to find.\n   */\n  path: string;\n  /** The link text, or the reference label for a definition. Quoted in the finding. */\n  text: string;\n  /** 1-based line the link was written on. */\n  line: number;\n}\n\n/**\n * Inline links and images: `[text](target)`, `![alt](target)`,\n * `[text](<target with spaces>)`, `[text](target \"title\")`.\n *\n * The target alternation takes `<...>` first so an angle-bracketed path\n * containing spaces stays one token; the bare form stops at whitespace or `)`,\n * which gives up on the balanced-parens spelling markdown also allows\n * (`[x](a(1).md)`). That is a deliberate under-read: it costs a link nobody\n * writes, where over-reading would swallow the rest of a sentence and report a\n * target no author would recognise.\n */\nconst INLINE_RE = /!?\\[([^\\]]*)\\]\\(\\s*(<[^>\\n]*>|[^\\s)]*)(?:\\s+(?:\"[^\"]*\"|'[^']*'|\\([^)]*\\)))?\\s*\\)/gd;\n\n/**\n * A reference DEFINITION — `[label]: target \"title\"` on its own line. Included\n * because the target is the same join written in a different place: a document\n * that collects its links at the bottom is following the convention, and a\n * reader that only saw inline links would grade it as having none.\n */\nconst DEFINITION_RE = /^ {0,3}\\[([^\\]]+)\\]:\\s*(<[^>\\n]*>|\\S+)/d;\n\n/**\n * Code spans, blanked before matching. `\\`[a](b)\\`` is prose ABOUT a link and\n * resolving it would convict a document for explaining the convention. Blanked\n * to spaces rather than removed so every column after it — and therefore any\n * real link later on the same line — keeps its position.\n */\nconst CODE_SPAN_RE = /(`+)(?:[^`]|(?!\\1)`)*\\1/g;\n\n/**\n * Every link in `md`, in document order.\n *\n * The whole document is scanned, frontmatter included: a YAML `see: [x](y.md)`\n * is not a link loam wrote a field for, and the alternative — teaching this\n * module where frontmatter ends — would make it read the one part of a document\n * loam's own doctrine says is structured. A link that resolves is a link that\n * resolves wherever it is written.\n */\nexport function documentLinks(md: string): DocumentLink[] {\n  const fenced = fenceTracker();\n  const out: DocumentLink[] = [];\n  md.split(/\\r?\\n/).forEach((rawLine, i) => {\n    if (fenced(rawLine)) return;\n    const line = rawLine.replace(CODE_SPAN_RE, (m) => \" \".repeat(m.length));\n    const definition = DEFINITION_RE.exec(line);\n    if (definition) {\n      push(out, definition[2]!, definition[1]!, i + 1);\n      return;\n    }\n    INLINE_RE.lastIndex = 0;\n    for (let m = INLINE_RE.exec(line); m !== null; m = INLINE_RE.exec(line)) {\n      push(out, m[2]!, m[1]!, i + 1);\n    }\n  });\n  return out;\n}\n\n/**\n * Record one link, unless its target is not a path this repository can answer\n * for. Four exclusions, each of them a question with no filesystem answer\n * rather than a link loam declines to grade:\n *\n * - an EMPTY target (`[text]()`) addresses nothing;\n * - a SCHEME (`https:`, `mailto:`, and a Windows `C:` drive with it) addresses\n *   something outside this repository;\n * - a ROOT-relative or protocol-relative target (`/x`, `//host/x`) is resolved\n *   by whatever renders the document — a site root, not the file's directory —\n *   so loam does not know what it points at;\n * - a PURE fragment (`#section`) addresses this same document, and grading it\n *   means resolving heading anchors, which is a different question from \"does\n *   this file exist\".\n *\n * The last two are DEFENSIVE rather than decisive, and a mutation run says so:\n * removing either leaves every test green, because a pure fragment leaves an\n * empty path and a site-root target resolves outside the docs repo, where\n * `./findings.ts` declines to answer anyway. They are kept because the reason\n * differs from that boundary's — loam is not silent about these because they\n * are elsewhere, it is silent because it does not know where they are — and a\n * later reader deleting them as dead would be removing an intention, not a\n * branch.\n */\nfunction push(out: DocumentLink[], target: string, text: string, line: number): void {\n  const raw = target.startsWith(\"<\") && target.endsWith(\">\") ? target.slice(1, -1) : target;\n  if (raw === \"\" || raw.startsWith(\"#\") || raw.startsWith(\"/\")) return;\n  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(raw)) return;\n  const path = decodePath(raw.split(\"#\")[0]!);\n  if (path === \"\") return;\n  out.push({ raw, path, text, line });\n}\n\n/**\n * Percent-decode a link target, or keep it verbatim when it does not decode.\n *\n * `[Order line](order%20line.md)` is how every editor writes a path holding a\n * space, so a resolver that skipped this step would report the one spelling\n * authors do not type by hand. `decodeURIComponent` throws on a lone `%` — a\n * literal percent in a filename is legal and rarer than the escape — and the\n * honest answer there is the string as written, which then resolves or does not\n * on its own terms.\n */\nfunction decodePath(raw: string): string {\n  try {\n    return decodeURIComponent(raw);\n  } catch {\n    return raw;\n  }\n}\n\n/**\n * Re-express every relative link in `md` from a new base directory — the merge's\n * half of the link convention.\n *\n * THE DEFECT THIS CLOSES is structural and predates the glossary. A feature's\n * `specs/<svc>/spec.md` sits four directories below the docs root; the living\n * `services/<svc>/spec.md` it merges into sits two. `loam archive` copies a\n * requirement's text verbatim, so `[Order](../../../../glossary/order.md)` —\n * correct where it was written, and clickable in the pull request that reviewed\n * it — lands in the living document pointing two directories above the\n * repository. The same is true of a delta requirement citing an ADR, which has\n * been possible since before this module existed.\n *\n * REWRITING IS THE ONLY ANSWER THAT KEEPS BOTH PROPERTIES. The alternative\n * considered was to have authors write the link relative to where the text will\n * END UP, leaving loam to touch nothing — but that link does not resolve in the\n * delta, and \"it renders as a link in pull-request review, which is where these\n * documents are actually read\" is the convention's own first argument. So the\n * author writes what is true where they write it, and the merge makes it true\n * where it lands. The target is unchanged: only the route to it is.\n *\n * It is a positional rewrite, never a re-render: the matched target's own span\n * is replaced and every other byte of the line — the link text, the title, the\n * prose around it — is left exactly as written.\n *\n * WHEN THE TARGET MOVES TOO, `retarget` says where to. The same archive that\n * moves a requirement two directories up moves the rest of the feature as\n * well: a term the feature defines is copied into `glossary/`, and the feature\n * directory itself — its ADRs, its intent — goes to `features/archive/<FEAT>/`.\n * A link into the feature re-expressed against the target's OLD place was\n * therefore re-expressed correctly and still rotted on the commit that made it.\n * And a document that does not move at all can still need rewriting, when the\n * directory it links into does (`subsystem move`) — which is why `from === to`\n * is no longer a reason to stop when a `retarget` is given.\n *\n * A LINK WHOSE TEXT STILL REACHES ITS TARGET FROM THE NEW PLACE KEEPS ITS\n * SPELLING: a sibling that moves with its document, or a target nothing moved\n * under a document that stays, comes out of the rewrite exactly as the author\n * wrote it rather than normalised into `./` form by a commit that had no\n * reason to touch it.\n */\nexport function rebaseLinks(md: string, move: LinkMove): string {\n  const from = resolve(move.from);\n  const to = resolve(move.to);\n  if (from === to && move.retarget === undefined) return md;\n  const route: Route = { from, to, retarget: move.retarget ?? ((target) => target) };\n  const fenced = fenceTracker();\n  // `split` with a capturing group keeps the separators, so a document's own\n  // mixture of CRLF and LF survives a rewrite that touches neither.\n  const parts = md.split(/(\\r?\\n)/);\n  for (let i = 0; i < parts.length; i += 2) {\n    const rawLine = parts[i]!;\n    if (fenced(rawLine)) continue;\n    parts[i] = rebaseLine(rawLine, route);\n  }\n  return parts.join(\"\");\n}\n\n/** Where a document's text is moving, and where each file it links to will be. */\nexport interface LinkMove {\n  /** The directory the text was written in. */\n  from: string;\n  /** The directory the text will be read from. */\n  to: string;\n  /**\n   * Where a link's target will be once the same change lands: an absolute path\n   * in, an absolute path out, the input itself for a target that stays put.\n   * Omitted, every target stays put — the requirement merge's original case.\n   */\n  retarget?: (target: string) => string;\n}\n\n/** `LinkMove` with both directories resolved and the retarget defaulted — what each line is rewritten against. */\ninterface Route {\n  from: string;\n  to: string;\n  retarget: (target: string) => string;\n}\n\n/** One line's links re-expressed, right to left so earlier spans keep their offsets. */\nfunction rebaseLine(rawLine: string, route: Route): string {\n  const blanked = rawLine.replace(CODE_SPAN_RE, (m) => \" \".repeat(m.length));\n  const spans: Array<[number, number, string]> = [];\n  const collect = (m: RegExpExecArray): void => {\n    const at = m.indices?.[2];\n    if (at === undefined) return;\n    const rebased = rebaseTarget(m[2]!, route);\n    if (rebased !== null) spans.push([at[0], at[1], rebased]);\n  };\n  const definition = DEFINITION_RE.exec(blanked);\n  if (definition) collect(definition);\n  else {\n    INLINE_RE.lastIndex = 0;\n    for (let m = INLINE_RE.exec(blanked); m !== null; m = INLINE_RE.exec(blanked)) collect(m);\n  }\n  let out = rawLine;\n  for (const [start, end, replacement] of spans.reverse()) {\n    out = out.slice(0, start) + replacement + out.slice(end);\n  }\n  return out;\n}\n\n/**\n * One target, re-expressed from `to` instead of `from` — and pointed at wherever\n * `retarget` says the file itself will be — or null when there is nothing to\n * re-express.\n *\n * The exclusions are `push`'s exactly — an absolute URL, a site-root path and a\n * bare fragment mean the same thing from every directory — and the ANGLE-BRACKET\n * and PERCENT-ESCAPE forms are preserved rather than normalised: a rewrite that\n * silently changed `<a b.md>` into `a%20b.md` would be editing the author's\n * spelling under cover of moving their file. A route that comes out unchanged\n * is null for the same reason (`rebaseLinks` says when that happens).\n */\nfunction rebaseTarget(target: string, route: Route): string | null {\n  const angled = target.startsWith(\"<\") && target.endsWith(\">\");\n  const raw = angled ? target.slice(1, -1) : target;\n  if (raw === \"\" || raw.startsWith(\"#\") || raw.startsWith(\"/\")) return null;\n  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(raw)) return null;\n  const hash = raw.indexOf(\"#\");\n  const pathPart = hash === -1 ? raw : raw.slice(0, hash);\n  const fragment = hash === -1 ? \"\" : raw.slice(hash);\n  if (pathPart === \"\") return null;\n  const encoded = pathPart.includes(\"%\");\n  const was = resolve(route.from, decodePath(pathPart));\n  const will = resolve(route.retarget(was));\n  // The author's TEXT, read from the new place, still reaching the target —\n  // not two computed routes compared. A link that climbs above a moved\n  // directory and comes back down through its old name\n  // (`../../../services/payment-service/spec.md` from inside that service)\n  // normalises to the same route either side of the move, and comparing\n  // routes kept a spelling that names a directory the move just removed.\n  if (resolve(route.to, decodePath(pathPart)) === will) return null;\n  let rebased = relative(route.to, will).split(sep).join(\"/\");\n  // `relative` returns a bare name for a sibling, which markdown reads as a\n  // path relative to the file anyway — but `./` is what an author writes and\n  // what keeps the link distinguishable from a reference label.\n  if (rebased !== \"\" && !rebased.startsWith(\".\")) rebased = `./${rebased}`;\n  if (rebased === \"\") return null;\n  if (!angled && (encoded || rebased.includes(\" \"))) rebased = rebased.split(\" \").join(\"%20\");\n  const rewritten = rebased + fragment;\n  return angled ? `<${rewritten}>` : rewritten;\n}\n"]}

package/dist/core/mcp/argv.js

@@ -0,0 +1,212 @@
+/**
+ * The MCP inputSchema for one tool: a closed object, so a typo'd argument
+ * refuses instead of vanishing, with the required set and the positional order
+ * `toArgv` enforces declared beside it.
+ */
+export function toInputSchema(tool) {
+    const properties = {};
+    for (const positional of tool.positionals) {
+        properties[positional.property] = positional.variadic
+            ? { type: "array", items: { type: "string" }, description: positional.description }
+            : { type: "string", description: positional.description };
+    }
+    for (const flag of tool.flags) {
+        properties[flag.property] =
+            flag.kind === "boolean"
+                ? { type: "boolean", description: flag.description }
+                : flag.kind === "strings"
+                    ? { type: "array", items: { type: "string" }, description: flag.description }
+                    : { type: "string", description: flag.description };
+    }
+    const required = [
+        ...tool.positionals.filter((p) => p.required).map((p) => p.property),
+        ...tool.flags.filter((f) => f.required === true).map((f) => f.property),
+    ];
+    return {
+        type: "object",
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+        ...orderRule(tool),
+        additionalProperties: false,
+    };
+}
+/**
+ * The rule `positionalTokens` enforces, declared: a positional after an
+ * optional one needs it, because positionals reach argv by position and the
+ * later value would otherwise be read in the earlier one's slot. Without it a
+ * client that validated `{name: "smoke"}` for `loam_list` against the schema
+ * it was given passed, and was then refused `-32602` by the server.
+ *
+ * Read off the declaration order rather than spelled per tool, so a tool that
+ * gains a positional after an optional one is declared the day it is refused.
+ * Each later positional needs every earlier OPTIONAL one; an earlier required
+ * one is in `required` already.
+ *
+ * Two keywords, because presence means two things. A scalar that is present
+ * always yields a token, so presence is the whole condition and
+ * `dependentRequired` says exactly that. A variadic yields tokens only when it
+ * has members: an empty one moves nothing into anybody's slot, and
+ * `positionalTokens` serves it — `{args: []}` with no `workflow` is the
+ * workflow list. `dependentRequired` there would forbid a call the server
+ * answers, the same disagreement turned the other way, so the variadic's rule
+ * sits under `dependentSchemas`: once it is present, either the earlier ones
+ * are too or it is empty. `anyOf` rather than `if`/`then`, which says the same
+ * but puts a `then` key on an object, and a thenable literal is one `await`
+ * away from being called.
+ */
+function orderRule(tool) {
+    const dependentRequired = {};
+    const dependentSchemas = {};
+    const earlier = [];
+    for (const positional of tool.positionals) {
+        if (earlier.length > 0 && positional.variadic) {
+            dependentSchemas[positional.property] = {
+                anyOf: [{ required: [...earlier] }, { properties: { [positional.property]: { maxItems: 0 } } }],
+            };
+        }
+        else if (earlier.length > 0) {
+            dependentRequired[positional.property] = [...earlier];
+        }
+        if (!positional.required)
+            earlier.push(positional.property);
+    }
+    return {
+        ...(Object.keys(dependentRequired).length > 0 ? { dependentRequired } : {}),
+        ...(Object.keys(dependentSchemas).length > 0 ? { dependentSchemas } : {}),
+    };
+}
+/**
+ * A string value that argv would read as a flag is refused before any command
+ * sees it: {"target": "--type"} must not become a parsed option. Commander
+ * cannot make this distinction after the fact — by then the token IS a flag —
+ * so the boundary is here, on every string that crosses, array members
+ * included. No shell is ever involved, so this is the only smuggling path.
+ */
+function smuggled(property, value) {
+    return value.startsWith("-")
+        ? `argument '${property}' value '${value}' begins with '-' — a value argv would read as a flag is refused`
+        : null;
+}
+/** One string value checked for type and smuggling. */
+function checkedString(property, value) {
+    if (typeof value !== "string")
+        return { ok: false, problem: `argument '${property}' must be a string` };
+    const bad = smuggled(property, value);
+    return bad === null ? { ok: true, tokens: [value] } : { ok: false, problem: bad };
+}
+/** An array value checked member by member — rebuilt, not cast, so the claim is earned. */
+function checkedStrings(property, value) {
+    if (!Array.isArray(value))
+        return { ok: false, problem: `argument '${property}' must be an array of strings` };
+    const tokens = [];
+    for (const entry of value) {
+        const checked = checkedString(property, entry);
+        if (!checked.ok)
+            return checked;
+        tokens.push(...checked.tokens);
+    }
+    return { ok: true, tokens };
+}
+/**
+ * The positionals, in declaration order — and refused when one would land in
+ * another's slot.
+ *
+ * A positional reaches argv by POSITION, so an optional one left out leaves no
+ * gap: whatever follows it moves up into its place. `loam_list` with `{name:
+ * "services"}` built `list services` and answered ok:true with the services
+ * listing, a wrong answer with nothing in it saying so; `loam_instructions`
+ * with `{args: [...]}` and no `workflow` read the first arg as the workflow.
+ * Refused here instead, as the invalid-params problem a missing REQUIRED
+ * positional already is, naming the slot the caller left empty. A later
+ * positional that yields no token — an empty variadic — moves nothing up, so
+ * it passes. `orderRule` above declares the same rule in the advertised
+ * schema; the two change together.
+ */
+function positionalTokens(tool, args) {
+    const tokens = [];
+    let absent;
+    for (const positional of tool.positionals) {
+        const value = args[positional.property];
+        if (value === undefined) {
+            if (positional.required)
+                return { ok: false, problem: `required argument '${positional.property}' is missing` };
+            absent ??= positional.property;
+            continue;
+        }
+        const checked = positional.variadic
+            ? checkedStrings(positional.property, value)
+            : checkedString(positional.property, value);
+        if (!checked.ok)
+            return checked;
+        if (absent !== undefined && checked.tokens.length > 0) {
+            return {
+                ok: false,
+                problem: `argument '${positional.property}' requires '${absent}' — positionals are read in order, ` +
+                    `so without '${absent}' this value would be read as '${absent}'`,
+            };
+        }
+        tokens.push(...checked.tokens);
+    }
+    return { ok: true, tokens };
+}
+function flagTokens(tool, args) {
+    const tokens = [];
+    for (const flag of tool.flags) {
+        const value = args[flag.property];
+        if (value === undefined) {
+            // The same refusal absent required positionals get: the client learns
+            // "-32602 missing argument", not an invalid-option envelope after the
+            // command already refused.
+            if (flag.required === true)
+                return { ok: false, problem: `required argument '${flag.property}' is missing` };
+            continue;
+        }
+        if (flag.kind === "boolean") {
+            if (typeof value !== "boolean")
+                return { ok: false, problem: `argument '${flag.property}' must be a boolean` };
+            if (value)
+                tokens.push(flag.flag);
+            continue;
+        }
+        const checked = flag.kind === "strings"
+            ? checkedStrings(flag.property, value)
+            : checkedString(flag.property, value);
+        if (!checked.ok)
+            return checked;
+        // A repeatable flag repeats per value; a single-valued one appears once.
+        for (const token of checked.tokens)
+            tokens.push(flag.flag, token);
+    }
+    return { ok: true, tokens };
+}
+/**
+ * The argv for one tool call — or the invalid-params problem that stops it.
+ * `--json` is always appended: the envelope is the tool-result contract, and
+ * a client cannot opt out of it into the human rendering. Unknown argument
+ * names refuse rather than vanish — the schema says additionalProperties
+ * false, and a server that enforced that only in the schema would silently
+ * drop the typo'd argument of any client that skipped validation.
+ */
+export function toArgv(tool, args) {
+    const known = new Set([
+        ...tool.positionals.map((p) => p.property),
+        ...tool.flags.map((f) => f.property),
+    ]);
+    for (const property of Object.keys(args)) {
+        if (!known.has(property)) {
+            const allowed = known.size === 0 ? "no arguments" : [...known].join(", ");
+            return { ok: false, problem: `unknown argument '${property}' for ${tool.name} — expected ${allowed}` };
+        }
+    }
+    const positionals = positionalTokens(tool, args);
+    if (!positionals.ok)
+        return { ok: false, problem: positionals.problem };
+    const flags = flagTokens(tool, args);
+    if (!flags.ok)
+        return { ok: false, problem: flags.problem };
+    return {
+        ok: true,
+        argv: [tool.command, ...positionals.tokens, ...flags.tokens, ...(tool.fixed ?? []), "--json"],
+    };
+}
+//# sourceMappingURL=argv.js.map

package/dist/core/mcp/argv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argv.js","sourceRoot":"","sources":["../../../src/core/mcp/argv.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How one MCP tool call's JSON arguments become an argv the CLI already\n * trusts — the boundary where an argument value could otherwise smuggle a\n * flag. The tool TABLE (what the tools are) lives in `./tools.ts`; this\n * module owns the crossing, and the inputSchema that declares it: the schema\n * a client validates against and the argv builder that refuses what it\n * forbids are one contract written twice, so they sit in one module.\n */\nimport type { McpTool } from \"./tools.js\";\n\n/**\n * The MCP inputSchema for one tool: a closed object, so a typo'd argument\n * refuses instead of vanishing, with the required set and the positional order\n * `toArgv` enforces declared beside it.\n */\nexport function toInputSchema(tool: McpTool): Record<string, unknown> {\n  const properties: Record<string, unknown> = {};\n  for (const positional of tool.positionals) {\n    properties[positional.property] = positional.variadic\n      ? { type: \"array\", items: { type: \"string\" }, description: positional.description }\n      : { type: \"string\", description: positional.description };\n  }\n  for (const flag of tool.flags) {\n    properties[flag.property] =\n      flag.kind === \"boolean\"\n        ? { type: \"boolean\", description: flag.description }\n        : flag.kind === \"strings\"\n          ? { type: \"array\", items: { type: \"string\" }, description: flag.description }\n          : { type: \"string\", description: flag.description };\n  }\n  const required = [\n    ...tool.positionals.filter((p) => p.required).map((p) => p.property),\n    ...tool.flags.filter((f) => f.required === true).map((f) => f.property),\n  ];\n  return {\n    type: \"object\",\n    properties,\n    ...(required.length > 0 ? { required } : {}),\n    ...orderRule(tool),\n    additionalProperties: false,\n  };\n}\n\n/**\n * The rule `positionalTokens` enforces, declared: a positional after an\n * optional one needs it, because positionals reach argv by position and the\n * later value would otherwise be read in the earlier one's slot. Without it a\n * client that validated `{name: \"smoke\"}` for `loam_list` against the schema\n * it was given passed, and was then refused `-32602` by the server.\n *\n * Read off the declaration order rather than spelled per tool, so a tool that\n * gains a positional after an optional one is declared the day it is refused.\n * Each later positional needs every earlier OPTIONAL one; an earlier required\n * one is in `required` already.\n *\n * Two keywords, because presence means two things. A scalar that is present\n * always yields a token, so presence is the whole condition and\n * `dependentRequired` says exactly that. A variadic yields tokens only when it\n * has members: an empty one moves nothing into anybody's slot, and\n * `positionalTokens` serves it — `{args: []}` with no `workflow` is the\n * workflow list. `dependentRequired` there would forbid a call the server\n * answers, the same disagreement turned the other way, so the variadic's rule\n * sits under `dependentSchemas`: once it is present, either the earlier ones\n * are too or it is empty. `anyOf` rather than `if`/`then`, which says the same\n * but puts a `then` key on an object, and a thenable literal is one `await`\n * away from being called.\n */\nfunction orderRule(tool: McpTool): Record<string, unknown> {\n  const dependentRequired: Record<string, string[]> = {};\n  const dependentSchemas: Record<string, unknown> = {};\n  const earlier: string[] = [];\n  for (const positional of tool.positionals) {\n    if (earlier.length > 0 && positional.variadic) {\n      dependentSchemas[positional.property] = {\n        anyOf: [{ required: [...earlier] }, { properties: { [positional.property]: { maxItems: 0 } } }],\n      };\n    } else if (earlier.length > 0) {\n      dependentRequired[positional.property] = [...earlier];\n    }\n    if (!positional.required) earlier.push(positional.property);\n  }\n  return {\n    ...(Object.keys(dependentRequired).length > 0 ? { dependentRequired } : {}),\n    ...(Object.keys(dependentSchemas).length > 0 ? { dependentSchemas } : {}),\n  };\n}\n\n/** One checked step of argv construction: the tokens it yields, or the invalid-params problem. */\ntype Checked =\n  | { readonly ok: true; readonly tokens: readonly string[] }\n  | { readonly ok: false; readonly problem: string };\n\nexport type ArgvOutcome =\n  | { readonly ok: true; readonly argv: readonly string[] }\n  | { readonly ok: false; readonly problem: string };\n\n/**\n * A string value that argv would read as a flag is refused before any command\n * sees it: {\"target\": \"--type\"} must not become a parsed option. Commander\n * cannot make this distinction after the fact — by then the token IS a flag —\n * so the boundary is here, on every string that crosses, array members\n * included. No shell is ever involved, so this is the only smuggling path.\n */\nfunction smuggled(property: string, value: string): string | null {\n  return value.startsWith(\"-\")\n    ? `argument '${property}' value '${value}' begins with '-' — a value argv would read as a flag is refused`\n    : null;\n}\n\n/** One string value checked for type and smuggling. */\nfunction checkedString(property: string, value: unknown): Checked {\n  if (typeof value !== \"string\") return { ok: false, problem: `argument '${property}' must be a string` };\n  const bad = smuggled(property, value);\n  return bad === null ? { ok: true, tokens: [value] } : { ok: false, problem: bad };\n}\n\n/** An array value checked member by member — rebuilt, not cast, so the claim is earned. */\nfunction checkedStrings(property: string, value: unknown): Checked {\n  if (!Array.isArray(value)) return { ok: false, problem: `argument '${property}' must be an array of strings` };\n  const tokens: string[] = [];\n  for (const entry of value) {\n    const checked = checkedString(property, entry);\n    if (!checked.ok) return checked;\n    tokens.push(...checked.tokens);\n  }\n  return { ok: true, tokens };\n}\n\n/**\n * The positionals, in declaration order — and refused when one would land in\n * another's slot.\n *\n * A positional reaches argv by POSITION, so an optional one left out leaves no\n * gap: whatever follows it moves up into its place. `loam_list` with `{name:\n * \"services\"}` built `list services` and answered ok:true with the services\n * listing, a wrong answer with nothing in it saying so; `loam_instructions`\n * with `{args: [...]}` and no `workflow` read the first arg as the workflow.\n * Refused here instead, as the invalid-params problem a missing REQUIRED\n * positional already is, naming the slot the caller left empty. A later\n * positional that yields no token — an empty variadic — moves nothing up, so\n * it passes. `orderRule` above declares the same rule in the advertised\n * schema; the two change together.\n */\nfunction positionalTokens(tool: McpTool, args: Record<string, unknown>): Checked {\n  const tokens: string[] = [];\n  let absent: string | undefined;\n  for (const positional of tool.positionals) {\n    const value = args[positional.property];\n    if (value === undefined) {\n      if (positional.required) return { ok: false, problem: `required argument '${positional.property}' is missing` };\n      absent ??= positional.property;\n      continue;\n    }\n    const checked = positional.variadic\n      ? checkedStrings(positional.property, value)\n      : checkedString(positional.property, value);\n    if (!checked.ok) return checked;\n    if (absent !== undefined && checked.tokens.length > 0) {\n      return {\n        ok: false,\n        problem:\n          `argument '${positional.property}' requires '${absent}' — positionals are read in order, ` +\n          `so without '${absent}' this value would be read as '${absent}'`,\n      };\n    }\n    tokens.push(...checked.tokens);\n  }\n  return { ok: true, tokens };\n}\n\nfunction flagTokens(tool: McpTool, args: Record<string, unknown>): Checked {\n  const tokens: string[] = [];\n  for (const flag of tool.flags) {\n    const value = args[flag.property];\n    if (value === undefined) {\n      // The same refusal absent required positionals get: the client learns\n      // \"-32602 missing argument\", not an invalid-option envelope after the\n      // command already refused.\n      if (flag.required === true) return { ok: false, problem: `required argument '${flag.property}' is missing` };\n      continue;\n    }\n    if (flag.kind === \"boolean\") {\n      if (typeof value !== \"boolean\") return { ok: false, problem: `argument '${flag.property}' must be a boolean` };\n      if (value) tokens.push(flag.flag);\n      continue;\n    }\n    const checked = flag.kind === \"strings\"\n      ? checkedStrings(flag.property, value)\n      : checkedString(flag.property, value);\n    if (!checked.ok) return checked;\n    // A repeatable flag repeats per value; a single-valued one appears once.\n    for (const token of checked.tokens) tokens.push(flag.flag, token);\n  }\n  return { ok: true, tokens };\n}\n\n/**\n * The argv for one tool call — or the invalid-params problem that stops it.\n * `--json` is always appended: the envelope is the tool-result contract, and\n * a client cannot opt out of it into the human rendering. Unknown argument\n * names refuse rather than vanish — the schema says additionalProperties\n * false, and a server that enforced that only in the schema would silently\n * drop the typo'd argument of any client that skipped validation.\n */\nexport function toArgv(tool: McpTool, args: Record<string, unknown>): ArgvOutcome {\n  const known = new Set([\n    ...tool.positionals.map((p) => p.property),\n    ...tool.flags.map((f) => f.property),\n  ]);\n  for (const property of Object.keys(args)) {\n    if (!known.has(property)) {\n      const allowed = known.size === 0 ? \"no arguments\" : [...known].join(\", \");\n      return { ok: false, problem: `unknown argument '${property}' for ${tool.name} — expected ${allowed}` };\n    }\n  }\n  const positionals = positionalTokens(tool, args);\n  if (!positionals.ok) return { ok: false, problem: positionals.problem };\n  const flags = flagTokens(tool, args);\n  if (!flags.ok) return { ok: false, problem: flags.problem };\n  return {\n    ok: true,\n    argv: [tool.command, ...positionals.tokens, ...flags.tokens, ...(tool.fixed ?? []), \"--json\"],\n  };\n}\n"]}

package/dist/core/mcp/author-tools.js

@@ -0,0 +1,73 @@
+const WRITE_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+};
+const SAFE_WRITE_ANNOTATIONS = {
+    ...WRITE_ANNOTATIONS,
+    idempotentHint: true,
+};
+export const MCP_AUTHOR_TOOLS = [
+    {
+        name: "loam_new",
+        command: "new",
+        description: "Scaffold a feature in the docs repo. Opt-in writer; refuses an existing feature. " +
+            "CLI equivalent: loam new <featureId> [--title <text>] [--touches <id>...] [--new-service <id>...] [--capability <id>...] [--modifies <Req-ID>...] --json",
+        positionals: [
+            { property: "featureId", required: true, variadic: false, description: "new feature id, e.g. FEAT-101" },
+        ],
+        flags: [
+            { property: "title", flag: "--title", kind: "string", description: "human title and directory slug" },
+            { property: "touches", flag: "--touches", kind: "strings", description: "existing services changed; repeatable" },
+            { property: "newServices", flag: "--new-service", kind: "strings", description: "services introduced; repeatable" },
+            { property: "capabilities", flag: "--capability", kind: "strings", description: "business capabilities changed; repeatable" },
+            { property: "modifies", flag: "--modifies", kind: "strings", description: "living Requirement-IDs of touched services this feature rewrites, scaffolded as pinned MODIFIED blocks; repeatable" },
+        ],
+        annotations: WRITE_ANNOTATIONS,
+    },
+    {
+        name: "loam_rebase",
+        command: "rebase",
+        description: "Pin a feature delta to the living baselines after the agent has reconciled them. Opt-in journaled writer. " +
+            "CLI equivalent: loam rebase [featureId] [--service <id>] --json",
+        // Optional because the REGISTERED argument is — `loam rebase` relaxed it
+        // for `--living`, which names no feature — and the schema mirrors the
+        // command it wraps rather than the subset this tool exposes. `--living` is
+        // not offered here, so an omitted id reaches the CLI's own refusal, which
+        // names the flag that makes the omission legal.
+        positionals: [
+            { property: "featureId", required: false, variadic: false, description: "feature id whose baselines were reviewed" },
+        ],
+        flags: [
+            { property: "service", flag: "--service", kind: "string", description: "restrict to one touched service" },
+        ],
+        annotations: SAFE_WRITE_ANNOTATIONS,
+    },
+    {
+        name: "loam_gherkin",
+        command: "gherkin",
+        description: "Generate loam-owned Gherkin files in the bound service repository. Opt-in journaled writer; refuses ownership conflicts. " +
+            "CLI equivalent: loam gherkin [featureId] [--service <id>] --json",
+        positionals: [
+            { property: "featureId", required: false, variadic: false, description: "feature id; omit for the living suite" },
+        ],
+        flags: [
+            { property: "service", flag: "--service", kind: "string", description: "service to emit for" },
+        ],
+        annotations: SAFE_WRITE_ANNOTATIONS,
+    },
+    {
+        name: "loam_archive_plan",
+        command: "archive",
+        description: "Compute the complete archive plan without writing. The server enforces --dry-run. " +
+            "CLI equivalent: loam archive <featureId> --dry-run --json",
+        positionals: [
+            { property: "featureId", required: true, variadic: false, description: "feature id to review" },
+        ],
+        flags: [],
+        fixed: ["--dry-run"],
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+];
+//# sourceMappingURL=author-tools.js.map

package/dist/core/mcp/author-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"author-tools.js","sourceRoot":"","sources":["../../../src/core/mcp/author-tools.ts"],"names":[],"mappings":"AAGA,MAAM,iBAAiB,GAAG;IACxB,YAAY,EAAE,KAAK;IACnB,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,KAAK;IACrB,aAAa,EAAE,KAAK;CACZ,CAAC;AAEX,MAAM,sBAAsB,GAAG;IAC7B,GAAG,iBAAiB;IACpB,cAAc,EAAE,IAAI;CACZ,CAAC;AAEX,MAAM,CAAC,MAAM,gBAAgB,GAAuB;IAClD;QACE,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,KAAK;QACd,WAAW,EACT,mFAAmF;YACnF,0JAA0J;QAC5J,WAAW,EAAE;YACX,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,+BAA+B,EAAE;SACzG;QACD,KAAK,EAAE;YACL,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gCAAgC,EAAE;YACrG,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,uCAAuC,EAAE;YACjH,EAAE,QAAQ,EAAE,aAAa,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,iCAAiC,EAAE;YACnH,EAAE,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,2CAA2C,EAAE;YAC7H,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,oHAAoH,EAAE;SACjM;QACD,WAAW,EAAE,iBAAiB;KAC/B;IACD;QACE,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,QAAQ;QACjB,WAAW,EACT,4GAA4G;YAC5G,iEAAiE;QACnE,yEAAyE;QACzE,sEAAsE;QACtE,2EAA2E;QAC3E,0EAA0E;QAC1E,gDAAgD;QAChD,WAAW,EAAE;YACX,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,0CAA0C,EAAE;SACrH;QACD,KAAK,EAAE;YACL,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iCAAiC,EAAE;SAC3G;QACD,WAAW,EAAE,sBAAsB;KACpC;IACD;QACE,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,SAAS;QAClB,WAAW,EACT,2HAA2H;YAC3H,kEAAkE;QACpE,WAAW,EAAE;YACX,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,uCAAuC,EAAE;SAClH;QACD,KAAK,EAAE;YACL,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qBAAqB,EAAE;SAC/F;QACD,WAAW,EAAE,sBAAsB;KACpC;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,SAAS;QAClB,WAAW,EACT,oFAAoF;YACpF,2DAA2D;QAC7D,WAAW,EAAE;YACX,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,sBAAsB,EAAE;SAChG;QACD,KAAK,EAAE,EAAE;QACT,KAAK,EAAE,CAAC,WAAW,CAAC;QACpB,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;KAC1D;CACF,CAAC","sourcesContent":["/** Opt-in MCP writers. Vouch and a committing archive are never exposed. */\nimport type { McpTool } from \"./tools.js\";\n\nconst WRITE_ANNOTATIONS = {\n  readOnlyHint: false,\n  destructiveHint: false,\n  idempotentHint: false,\n  openWorldHint: false,\n} as const;\n\nconst SAFE_WRITE_ANNOTATIONS = {\n  ...WRITE_ANNOTATIONS,\n  idempotentHint: true,\n} as const;\n\nexport const MCP_AUTHOR_TOOLS: readonly McpTool[] = [\n  {\n    name: \"loam_new\",\n    command: \"new\",\n    description:\n      \"Scaffold a feature in the docs repo. Opt-in writer; refuses an existing feature. \" +\n      \"CLI equivalent: loam new <featureId> [--title <text>] [--touches <id>...] [--new-service <id>...] [--capability <id>...] [--modifies <Req-ID>...] --json\",\n    positionals: [\n      { property: \"featureId\", required: true, variadic: false, description: \"new feature id, e.g. FEAT-101\" },\n    ],\n    flags: [\n      { property: \"title\", flag: \"--title\", kind: \"string\", description: \"human title and directory slug\" },\n      { property: \"touches\", flag: \"--touches\", kind: \"strings\", description: \"existing services changed; repeatable\" },\n      { property: \"newServices\", flag: \"--new-service\", kind: \"strings\", description: \"services introduced; repeatable\" },\n      { property: \"capabilities\", flag: \"--capability\", kind: \"strings\", description: \"business capabilities changed; repeatable\" },\n      { property: \"modifies\", flag: \"--modifies\", kind: \"strings\", description: \"living Requirement-IDs of touched services this feature rewrites, scaffolded as pinned MODIFIED blocks; repeatable\" },\n    ],\n    annotations: WRITE_ANNOTATIONS,\n  },\n  {\n    name: \"loam_rebase\",\n    command: \"rebase\",\n    description:\n      \"Pin a feature delta to the living baselines after the agent has reconciled them. Opt-in journaled writer. \" +\n      \"CLI equivalent: loam rebase [featureId] [--service <id>] --json\",\n    // Optional because the REGISTERED argument is — `loam rebase` relaxed it\n    // for `--living`, which names no feature — and the schema mirrors the\n    // command it wraps rather than the subset this tool exposes. `--living` is\n    // not offered here, so an omitted id reaches the CLI's own refusal, which\n    // names the flag that makes the omission legal.\n    positionals: [\n      { property: \"featureId\", required: false, variadic: false, description: \"feature id whose baselines were reviewed\" },\n    ],\n    flags: [\n      { property: \"service\", flag: \"--service\", kind: \"string\", description: \"restrict to one touched service\" },\n    ],\n    annotations: SAFE_WRITE_ANNOTATIONS,\n  },\n  {\n    name: \"loam_gherkin\",\n    command: \"gherkin\",\n    description:\n      \"Generate loam-owned Gherkin files in the bound service repository. Opt-in journaled writer; refuses ownership conflicts. \" +\n      \"CLI equivalent: loam gherkin [featureId] [--service <id>] --json\",\n    positionals: [\n      { property: \"featureId\", required: false, variadic: false, description: \"feature id; omit for the living suite\" },\n    ],\n    flags: [\n      { property: \"service\", flag: \"--service\", kind: \"string\", description: \"service to emit for\" },\n    ],\n    annotations: SAFE_WRITE_ANNOTATIONS,\n  },\n  {\n    name: \"loam_archive_plan\",\n    command: \"archive\",\n    description:\n      \"Compute the complete archive plan without writing. The server enforces --dry-run. \" +\n      \"CLI equivalent: loam archive <featureId> --dry-run --json\",\n    positionals: [\n      { property: \"featureId\", required: true, variadic: false, description: \"feature id to review\" },\n    ],\n    flags: [],\n    fixed: [\"--dry-run\"],\n    annotations: { readOnlyHint: true, openWorldHint: false },\n  },\n];\n"]}