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

package/dist/core/{config.js → envelope/config.js}

@@ -1,8 +1,9 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { dirname, join, parse as parsePath, resolve } from "node:path";
-import { resolveInside } from "./path-safety.js";
-import { serviceIdProblem } from "./ids.js";
+import { resolveInside } from "../kernel/path-safety.js";
+import { docsDirOf } from "../kernel/ids/dirs.js";
+import { parseServiceId } from "../kernel/ids/service.js";
 /** Local config, committed at the root of a service repo (or the docs repo itself). */
 export const CONFIG_FILENAME = "loam.json";
 /**
@@ -103,15 +104,26 @@ export function parseConfig(raw, configDir) {
     // Same discipline as docsDir: a malformed fact refuses the whole config
     // rather than being silently defaulted over — `5` or `""` here is a typo,
     // and defaulting would send generated files somewhere nobody chose.
+    // `parseServiceId` rather than a bare check: the same call both refuses the
+    // malformed value and produces the branded one below, so there is no window
+    // in which a checked name is still typed as an unchecked string. It takes a
+    // `string`, hence the shape guard first — the id grammar's own message is
+    // about spelling, and `5` is not a spelling.
+    let service;
     if (record.service !== undefined) {
-        const problem = serviceIdProblem(record.service, '"service"');
-        if (problem !== null)
-            throw new ConfigError("service", `${file}: ${problem}`);
+        if (typeof record.service !== "string") {
+            throw new ConfigError("service", `${file}: "service" must be a string.`);
+        }
+        const parsed = parseServiceId(record.service, '"service"');
+        if (!parsed.ok)
+            throw new ConfigError("service", `${file}: ${parsed.problem}`);
+        service = parsed.id;
     }
     if (record.gherkinDir !== undefined
         && (typeof record.gherkinDir !== "string" || record.gherkinDir === "")) {
         throw new ConfigError("gherkinDir", `${file}: "gherkinDir" must be a non-empty string when present.`);
     }
+    const contracts = readContracts(record.contracts, file);
     // Shape only. Which ids are legal is the registry's question, and asking it
     // here would make a config written by a newer binary — one that knows a tool
     // this one does not — unloadable for every command, not just for `init`.
@@ -120,6 +132,21 @@ export function parseConfig(raw, configDir) {
             || record.agentTools.some((t) => typeof t !== "string" || t === ""))) {
         throw new ConfigError("agentTools", `${file}: "agentTools" must be an array of non-empty strings when present.`);
     }
+    if (record.agentFiles !== undefined) {
+        if (record.agentFiles === null || typeof record.agentFiles !== "object" || Array.isArray(record.agentFiles)) {
+            throw new ConfigError("agentFiles", `${file}: "agentFiles" must be a path-to-digest mapping when present.`);
+        }
+        const entries = Object.entries(record.agentFiles);
+        if (entries.some(([path, digest]) => path === "" || typeof digest !== "string" || !/^[a-f0-9]{64}$/.test(digest))) {
+            throw new ConfigError("agentFiles", `${file}: "agentFiles" must map non-empty paths to lowercase sha256 digests.`);
+        }
+    }
+    if (record.agentProfile !== undefined
+        && record.agentProfile !== "full"
+        && record.agentProfile !== "service"
+        && record.agentProfile !== "docs") {
+        throw new ConfigError("agentProfile", `${file}: "agentProfile" must be one of: full, service, docs.`);
+    }
     if (typeof record.gherkinDir === "string") {
         // Validate the owned output directory, not merely its spelling. This also
         // catches an otherwise-contained path whose existing parent is a symlink
@@ -133,11 +160,19 @@ export function parseConfig(raw, configDir) {
     }
     return {
         // Resolved here, against the file's own directory, so the doc comment on
-        // `docsDir` is true no matter where a caller later resolves the path from.
-        docsDir: resolve(configDir, record.docsDir),
-        ...(record.service === undefined ? {} : { service: record.service }),
+        // `docsDir` is true no matter where a caller later resolves the path from —
+        // which is exactly the provenance `docsDirOf` demands.
+        docsDir: docsDirOf(resolve(configDir, record.docsDir)),
+        ...(service === undefined ? {} : { service }),
         ...(record.gherkinDir === undefined ? {} : { gherkinDir: record.gherkinDir }),
+        ...(contracts === undefined ? {} : { contracts }),
         ...(record.agentTools === undefined ? {} : { agentTools: record.agentTools }),
+        ...(record.agentFiles === undefined
+            ? {}
+            : { agentFiles: record.agentFiles }),
+        ...(record.agentProfile === undefined
+            ? {}
+            : { agentProfile: record.agentProfile }),
         root: resolve(configDir),
         docsDirAsWritten: record.docsDir,
     };
@@ -145,7 +180,7 @@ export function parseConfig(raw, configDir) {
 export async function loadConfig(cwd = process.cwd()) {
     const p = findConfigPath(cwd);
     if (p === null)
-        return null;
+        return { kind: "absent" };
     try {
         // The read belongs INSIDE the try: `existsSync` only says the name is
         // taken, not that it names a file this process can read. A loam.json that
@@ -153,17 +188,11 @@ export async function loadConfig(cwd = process.cwd()) {
         // deleted between the search and the read (ENOENT) all fail here rather
         // than in `parseConfig` — and read outside, each of them escaped every
         // command as an `internal` crash carrying a bare errno. Caught here they
-        // join the same "exists but cannot be believed" arm the parse failures
-        // already take, so `reportNoConfig` re-checks the path and answers the
-        // designed `config-invalid` (or `no-config` if the file really has gone).
-        return parseConfig(await readFile(p, "utf8"), dirname(p));
+        // join the same "exists but cannot be believed" arm the parse failures take.
+        return { kind: "loaded", config: parseConfig(await readFile(p, "utf8"), dirname(p)) };
     }
     catch (err) {
-        // An unreadable config must not crash the CLI with a stack trace: report it and
-        // treat it as absent — commands fail with their normal hint, and `loam init`
-        // (which spreads the old config) can rewrite a corrupt file instead of dying on it.
-        console.error(`Invalid ${CONFIG_FILENAME}: ${err instanceof Error ? err.message : String(err)}`);
-        return null;
+        return { kind: "invalid", path: p, problem: err instanceof Error ? err.message : String(err) };
     }
 }
 /**
@@ -177,4 +206,36 @@ export async function saveConfig(config, cwd = process.cwd()) {
     await writeFile(p, JSON.stringify(stored, null, 2) + "\n", "utf8");
     return p;
 }
+/**
+ * The optional `contracts` block, validated to shape only.
+ *
+ * SHAPE ONLY, exactly as `agentTools` is, and for a sharper version of the same
+ * reason: containment is not checked here because a build output legitimately
+ * sits outside the repo root's own subtree in some layouts, and the reader that
+ * resolves it is where an escaping path must be refused — with the service in
+ * hand, so the refusal can name it. A config that throws takes down every
+ * command, including the ones with nothing to do with contracts.
+ */
+function readContracts(value, file) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new ConfigError("contracts", `${file}: "contracts" must be a mapping with an optional "openapi" path.`);
+    }
+    const record = value;
+    // Only `openapi` today. The event axis gets a key when it gets a check —
+    // a config key nothing reads is worse than a missing one, because a fleet
+    // sets it and believes something is being graded.
+    const out = {};
+    for (const key of ["openapi"]) {
+        const spelled = record[key];
+        if (spelled === undefined)
+            continue;
+        if (typeof spelled !== "string" || spelled === "") {
+            throw new ConfigError("contracts", `${file}: "contracts.${key}" must be a non-empty string when present.`);
+        }
+        out[key] = spelled;
+    }
+    return out.openapi === undefined ? undefined : out;
+}
 //# sourceMappingURL=config.js.map

package/dist/core/envelope/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/core/envelope/config.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile, writeFile } from \"node:fs/promises\";\nimport { existsSync } from \"node:fs\";\nimport { dirname, join, parse as parsePath, resolve } from \"node:path\";\nimport { resolveInside } from \"../kernel/path-safety.js\";\nimport { docsDirOf, type DocsDir } from \"../kernel/ids/dirs.js\";\nimport { parseServiceId, type ServiceId } from \"../kernel/ids/service.js\";\n\n/** Local config, committed at the root of a service repo (or the docs repo itself). */\nexport const CONFIG_FILENAME = \"loam.json\";\n\nexport interface LoamConfig {\n  /**\n   * Path to the single shared docs repo (the source of truth). A LOADED config\n   * carries it resolved — `parseConfig` resolves the file's spelling against\n   * the config file's own directory, which is what earns the brand. The\n   * spelling itself is `docsDirAsWritten`, and the shape `saveConfig` persists\n   * (`StoredConfig`) keeps it a plain `string`: the stored form is deliberately\n   * unresolved (see `storedDocsDir` in commands/init/options.ts), and branding\n   * it would state a resolution that never happened.\n   */\n  docsDir: DocsDir;\n  /**\n   * Canonical id of the service in the current repo, if this is a service repo.\n   *\n   * Branded because `parseConfig` below is the one place that checks it, so\n   * every command reading `config.service` is reading a name that has already\n   * passed the grammar — which is why the config arm of\n   * `opts.service ?? config.service` needs no second parse.\n   */\n  service?: ServiceId;\n  /**\n   * Where Gherkin lives in this service repo, relative to the repo root\n   * (default \"features\" — the cucumber convention). `loam gherkin` writes only\n   * inside `<gherkinDir>/loam/`; the rest of the directory stays the team's.\n   * Left unresolved on purpose: commands resolve it against the repo they run\n   * in, which is where the config file lives.\n   */\n  gherkinDir?: string;\n  /**\n   * Where this repo's BUILD writes its contract documents, relative to the\n   * repo root — the springdoc/FastAPI/NestJS output, not a second copy anybody\n   * maintains.\n   *\n   * loam reads these and compares a digest; it never writes them, never copies\n   * them into the docs repo, and never derives meaning from them. That is what\n   * keeps the field on the right side of the no-extractor line: it parses a\n   * standard document somebody else generated, at a path a human named, in\n   * exactly the way `verify --results` already ingests a cucumber report.\n   *\n   * The committed `services/<id>/openapi.yaml` stays the contract, and the copy\n   * stays a human `cp` reviewed in a pull request. Automating the copy would\n   * make the docs-repo document a cache of the build; leaving it manual and\n   * merely REPORTING the divergence keeps it a document somebody agreed to.\n   */\n  contracts?: { openapi?: string };\n  /**\n   * The agent tools `loam init` has written command and skill files for in this\n   * repo, by AGENT_TOOLS id.\n   *\n   * Recorded because the two ways a generated file can be absent look identical\n   * on disk: the binary grew a command nobody has re-run `init` for, or nobody\n   * ever selected that tool here. Only this list tells them apart, and `loam\n   * doctor` needs the difference to know which absence is worth reporting.\n   *\n   * ACCUMULATED, never replaced — a later `init --tools cursor` does not\n   * un-write the claude files an earlier run left on disk, so the record of\n   * what this repo holds has to keep them too.\n   *\n   * Optional, and unvalidated against the registry on purpose: a config written\n   * by an older binary has no list at all, and one written by a NEWER binary\n   * may name a tool this one has never heard of. Neither may refuse to load.\n   */\n  agentTools?: string[];\n  /**\n   * Digests of generated agent files loam may safely refresh. Keys are\n   * repo-relative portable paths; a file whose bytes differ from its recorded\n   * digest is human-owned and is never overwritten.\n   */\n  agentFiles?: Record<string, string>;\n  /** Which workflow subset `loam init` manages; absent means the compatible full set. */\n  agentProfile?: \"full\" | \"service\" | \"docs\";\n  /**\n   * The directory the config was actually FOUND in — the repo root, which is\n   * not necessarily the cwd now that discovery walks upward. Everything a\n   * command resolves against \"this repo\" (gherkinDir, relative `sources:`)\n   * belongs here, not against process.cwd(): running `loam gherkin` from\n   * `src/deep/` must write the same files as running it from the root.\n   *\n   * Derived, never stored: `saveConfig` strips it, so it can never be spelled\n   * in loam.json and drift from where the file really is.\n   */\n  root?: string;\n  /**\n   * `docsDir` exactly as the file spells it, before resolution. Kept because\n   * \"relative\" and \"absolute\" are not recoverable from the resolved path, and\n   * the difference is the whole point: an absolute docsDir in a COMMITTED\n   * config is a path that only exists on the machine that ran `loam init`.\n   *\n   * Derived, never stored — same contract as `root`.\n   */\n  docsDirAsWritten?: string;\n}\n\n/**\n * A loam.json that exists but cannot be believed. Carries the field at fault\n * (null when the whole document is), because \"which field\" is the difference\n * between a fix and a guess — and because both `loadConfig` and `loam doctor`\n * report the same sentence from it.\n */\nexport class ConfigError extends Error {\n  constructor(\n    readonly field: string | null,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"ConfigError\";\n  }\n}\n\n/**\n * The directories a config search may look in: `start`, then each ancestor, up\n * to AND INCLUDING the git root — or the filesystem root when there is no git\n * repo above.\n *\n * The git root is the stop because it is the boundary the user already thinks\n * in: a loam.json outside it belongs to some other checkout (or, worse, to a\n * home directory), and silently adopting it would point a service repo's\n * commands at a docs repo nobody in this repo ever chose.\n */\nfunction searchDirs(start: string): string[] {\n  const out: string[] = [];\n  let current = resolve(start);\n  const root = parsePath(current).root;\n  for (;;) {\n    out.push(current);\n    // `.git` is a directory in a normal clone and a FILE in a worktree or\n    // submodule — existsSync answers both without caring which.\n    if (existsSync(join(current, \".git\"))) return out;\n    const parent = dirname(current);\n    if (parent === current || current === root) return out;\n    current = parent;\n  }\n}\n\n/** Where a config written HERE goes — never a discovered one. `init` and `saveConfig` use this. */\nexport function localConfigPath(cwd: string = process.cwd()): string {\n  return resolve(cwd, CONFIG_FILENAME);\n}\n\n/**\n * The nearest loam.json at or above `cwd`, or null. Exported because `init` has\n * to be able to ask a different question from \"is there one here\": a config in\n * an ancestor already governs this directory, and a second one written below it\n * would quietly shadow the first for every command run from the subtree.\n */\nexport function findConfigPath(cwd: string = process.cwd()): string | null {\n  for (const dir of searchDirs(cwd)) {\n    const candidate = join(dir, CONFIG_FILENAME);\n    if (existsSync(candidate)) return candidate;\n  }\n  return null;\n}\n\n/**\n * The config that governs `cwd`: the discovered one, or — when there is none —\n * where it would have to be written. The fallback keeps this total, which is\n * what lets a caller distinguish \"absent\" from \"present but unloadable\" with a\n * single existsSync (see `reportNoConfig`).\n */\nexport function configPath(cwd: string = process.cwd()): string {\n  return findConfigPath(cwd) ?? localConfigPath(cwd);\n}\n\n/**\n * THE config validator. One implementation, because two of them are two\n * opinions: `loam doctor` used to carry its own copy, and a config doctor\n * called healthy could still be one every other command refused to load.\n *\n * `configDir` is the directory the file lives in — every relative path in the\n * document is resolved against it, so the doc comments above stay true no\n * matter where the caller happens to be standing.\n */\nexport function parseConfig(raw: string, configDir: string): LoamConfig {\n  const file = join(configDir, CONFIG_FILENAME);\n  let value: unknown;\n  try {\n    value = JSON.parse(raw);\n  } catch (err) {\n    throw new ConfigError(null, `${file} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);\n  }\n  // Checked before any field access: `JSON.parse(\"null\")` and `JSON.parse(\"5\")`\n  // are valid JSON, and reaching for `.docsDir` on them is how a config typo\n  // used to surface as a raw Node TypeError instead of a named field.\n  if (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n    throw new ConfigError(null, `${file} must contain a JSON object.`);\n  }\n  const record = value as Record<string, unknown>;\n\n  if (typeof record.docsDir !== \"string\" || record.docsDir === \"\") {\n    throw new ConfigError(\"docsDir\", `${file}: \"docsDir\" must be a non-empty string.`);\n  }\n  // Same discipline as docsDir: a malformed fact refuses the whole config\n  // rather than being silently defaulted over — `5` or `\"\"` here is a typo,\n  // and defaulting would send generated files somewhere nobody chose.\n  // `parseServiceId` rather than a bare check: the same call both refuses the\n  // malformed value and produces the branded one below, so there is no window\n  // in which a checked name is still typed as an unchecked string. It takes a\n  // `string`, hence the shape guard first — the id grammar's own message is\n  // about spelling, and `5` is not a spelling.\n  let service: ServiceId | undefined;\n  if (record.service !== undefined) {\n    if (typeof record.service !== \"string\") {\n      throw new ConfigError(\"service\", `${file}: \"service\" must be a string.`);\n    }\n    const parsed = parseServiceId(record.service, '\"service\"');\n    if (!parsed.ok) throw new ConfigError(\"service\", `${file}: ${parsed.problem}`);\n    service = parsed.id;\n  }\n  if (record.gherkinDir !== undefined\n    && (typeof record.gherkinDir !== \"string\" || record.gherkinDir === \"\")) {\n    throw new ConfigError(\"gherkinDir\", `${file}: \"gherkinDir\" must be a non-empty string when present.`);\n  }\n  const contracts = readContracts(record.contracts, file);\n  // Shape only. Which ids are legal is the registry's question, and asking it\n  // here would make a config written by a newer binary — one that knows a tool\n  // this one does not — unloadable for every command, not just for `init`.\n  if (record.agentTools !== undefined\n    && (!Array.isArray(record.agentTools)\n      || record.agentTools.some((t) => typeof t !== \"string\" || t === \"\"))) {\n    throw new ConfigError(\n      \"agentTools\",\n      `${file}: \"agentTools\" must be an array of non-empty strings when present.`,\n    );\n  }\n  if (record.agentFiles !== undefined) {\n    if (record.agentFiles === null || typeof record.agentFiles !== \"object\" || Array.isArray(record.agentFiles)) {\n      throw new ConfigError(\"agentFiles\", `${file}: \"agentFiles\" must be a path-to-digest mapping when present.`);\n    }\n    const entries = Object.entries(record.agentFiles as Record<string, unknown>);\n    if (entries.some(([path, digest]) => path === \"\" || typeof digest !== \"string\" || !/^[a-f0-9]{64}$/.test(digest))) {\n      throw new ConfigError(\n        \"agentFiles\",\n        `${file}: \"agentFiles\" must map non-empty paths to lowercase sha256 digests.`,\n      );\n    }\n  }\n  if (record.agentProfile !== undefined\n    && record.agentProfile !== \"full\"\n    && record.agentProfile !== \"service\"\n    && record.agentProfile !== \"docs\") {\n    throw new ConfigError(\n      \"agentProfile\",\n      `${file}: \"agentProfile\" must be one of: full, service, docs.`,\n    );\n  }\n  if (typeof record.gherkinDir === \"string\") {\n    // Validate the owned output directory, not merely its spelling. This also\n    // catches an otherwise-contained path whose existing parent is a symlink\n    // out of the service repo.\n    try {\n      resolveInside(configDir, join(record.gherkinDir, \"loam\"), `\"gherkinDir\"`);\n    } catch (err) {\n      throw new ConfigError(\"gherkinDir\", `${file}: ${err instanceof Error ? err.message : String(err)}`);\n    }\n  }\n\n  return {\n    // Resolved here, against the file's own directory, so the doc comment on\n    // `docsDir` is true no matter where a caller later resolves the path from —\n    // which is exactly the provenance `docsDirOf` demands.\n    docsDir: docsDirOf(resolve(configDir, record.docsDir)),\n    ...(service === undefined ? {} : { service }),\n    ...(record.gherkinDir === undefined ? {} : { gherkinDir: record.gherkinDir as string }),\n    ...(contracts === undefined ? {} : { contracts }),\n    ...(record.agentTools === undefined ? {} : { agentTools: record.agentTools as string[] }),\n    ...(record.agentFiles === undefined\n      ? {}\n      : { agentFiles: record.agentFiles as Record<string, string> }),\n    ...(record.agentProfile === undefined\n      ? {}\n      : { agentProfile: record.agentProfile as \"full\" | \"service\" | \"docs\" }),\n    root: resolve(configDir),\n    docsDirAsWritten: record.docsDir,\n  };\n}\n\n/**\n * Every way asking for the config can come out, as data. It used to be\n * `LoamConfig | null` with a `console.error` on the invalid arm — core's one\n * print outside the envelope adapter, and a null that collapsed \"no config\"\n * and \"a config nobody can read\" into one answer `reportNoConfig` then had to\n * re-derive from the filesystem (a TOCTOU: the file could change between the\n * load and the re-check). The union says which case it is, carries the parse\n * problem for the command layer to render, and prints nothing.\n */\nexport type ConfigLoad =\n  | { kind: \"loaded\"; config: LoamConfig }\n  | { kind: \"absent\" }\n  | { kind: \"invalid\"; path: string; problem: string };\n\nexport async function loadConfig(cwd: string = process.cwd()): Promise<ConfigLoad> {\n  const p = findConfigPath(cwd);\n  if (p === null) return { kind: \"absent\" };\n  try {\n    // The read belongs INSIDE the try: `existsSync` only says the name is\n    // taken, not that it names a file this process can read. A loam.json that\n    // is a directory (EISDIR), one whose permissions refuse us (EACCES), or one\n    // deleted between the search and the read (ENOENT) all fail here rather\n    // than in `parseConfig` — and read outside, each of them escaped every\n    // command as an `internal` crash carrying a bare errno. Caught here they\n    // join the same \"exists but cannot be believed\" arm the parse failures take.\n    return { kind: \"loaded\", config: parseConfig(await readFile(p, \"utf8\"), dirname(p)) };\n  } catch (err) {\n    return { kind: \"invalid\", path: p, problem: err instanceof Error ? err.message : String(err) };\n  }\n}\n\n/**\n * What `saveConfig` persists: `LoamConfig` with `docsDir` back to a plain\n * `string`, because the stored form is the SPELLING (deliberately relative —\n * `storedDocsDir`), not the resolved `DocsDir` a loaded config carries. The\n * two derived fields ride along as optional so a caller may spread a loaded\n * config forward — `saveConfig` strips them on the way out either way.\n */\nexport type StoredConfig = Omit<LoamConfig, \"docsDir\"> & { docsDir: string };\n\n/**\n * Write the config for the repo rooted at `cwd`. The derived fields are dropped\n * on the way out: they are facts about where the file was found and how it was\n * spelled, and a stored copy could only ever disagree with the file itself.\n */\nexport async function saveConfig(config: StoredConfig, cwd: string = process.cwd()): Promise<string> {\n  const p = localConfigPath(cwd);\n  const { root: _root, docsDirAsWritten: _asWritten, ...stored } = config;\n  await writeFile(p, JSON.stringify(stored, null, 2) + \"\\n\", \"utf8\");\n  return p;\n}\n\n/**\n * The optional `contracts` block, validated to shape only.\n *\n * SHAPE ONLY, exactly as `agentTools` is, and for a sharper version of the same\n * reason: containment is not checked here because a build output legitimately\n * sits outside the repo root's own subtree in some layouts, and the reader that\n * resolves it is where an escaping path must be refused — with the service in\n * hand, so the refusal can name it. A config that throws takes down every\n * command, including the ones with nothing to do with contracts.\n */\nfunction readContracts(value: unknown, file: string): { openapi?: string } | undefined {\n  if (value === undefined) return undefined;\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new ConfigError(\"contracts\", `${file}: \"contracts\" must be a mapping with an optional \"openapi\" path.`);\n  }\n  const record = value as Record<string, unknown>;\n  // Only `openapi` today. The event axis gets a key when it gets a check —\n  // a config key nothing reads is worse than a missing one, because a fleet\n  // sets it and believes something is being graded.\n  const out: { openapi?: string } = {};\n  for (const key of [\"openapi\"] as const) {\n    const spelled = record[key];\n    if (spelled === undefined) continue;\n    if (typeof spelled !== \"string\" || spelled === \"\") {\n      throw new ConfigError(\"contracts\", `${file}: \"contracts.${key}\" must be a non-empty string when present.`);\n    }\n    out[key] = spelled;\n  }\n  return out.openapi === undefined ? undefined : out;\n}\n"]}

package/dist/core/envelope/json.js

@@ -0,0 +1,175 @@
+/**
+ * The `--json` envelope — loam's machine contract.
+ *
+ * Every JSON response carries `ok`. Success spreads the payload alongside it;
+ * failure carries a stable `error.code` a caller can branch on without parsing
+ * prose. Errors go to stdout too: a consumer reads one stream and always gets
+ * valid JSON, whether the command succeeded or not. The exit code still tells
+ * the shell what happened.
+ *
+ * Three keys identify the envelope before its payload is read, and they answer
+ * three different questions: `contractVersion` is the SHAPE's version,
+ * `version` is the BINARY's, and `command` (on every success payload) says
+ * which verb produced it. The first two are stamped by the emitters below so
+ * no command can forget them; the third is the payload's own first key,
+ * because only the command knows its name.
+ *
+ * Key casing: camelCase, with one deliberate exception — a key that mirrors a
+ * frontmatter field verbatim keeps that field's snake_case spelling
+ * (`last_verified`, `sources_digest` in vouch's payload), so the envelope and
+ * the document it describes spell the same fact the same way. snake_case only
+ * where a key mirrors a frontmatter field verbatim; camelCase everywhere else.
+ */
+import { relative } from "node:path";
+import { LOAM_VERSION } from "./version.js";
+/**
+ * Version of the top-level JSON envelope, independent of the CLI/package
+ * version. Additive payload fields do not require a bump; incompatible changes
+ * to `ok`, `error`, or their semantics do.
+ */
+export const JSON_CONTRACT_VERSION = "1.0";
+/**
+ * `version` is stamped HERE rather than by each command for the reason the
+ * `command` discriminator was not, and had to be retrofitted one call site at a
+ * time: a key every envelope owes is a key no command can be trusted to
+ * remember. Two lines in the two emitters give it to every command and every
+ * refusal at once, and a command added tomorrow cannot ship without it.
+ *
+ * Why a consumer needs it at all: `docs.binary-behind` exists to say that a
+ * green run from an old binary is worth less than it looks, and a caller
+ * holding only a `--json` payload could not tell which loam produced it — so it
+ * could not apply that caution, and could not see a mixed-version fleet in the
+ * contract. It sits beside `contractVersion`, never inside it: the envelope
+ * SHAPE and the binary that filled it version independently, and collapsing
+ * them would make every release look like a contract break.
+ */
+export function emitJson(payload) {
+    console.log(JSON.stringify({ contractVersion: JSON_CONTRACT_VERSION, version: LOAM_VERSION, ok: true, ...payload }, null, 2));
+}
+/** Paths in the contract are repo-relative, with forward slashes: diffable across machines. */
+export function repoPath(docsDir, abs) {
+    return relative(docsDir, abs).split(/[\\/]/).join("/");
+}
+/**
+ * Emit a failure envelope and set the exit code. Returns false, to `return`
+ * from a caller.
+ *
+ * `version` is on this path too, and deliberately: a refusal is the envelope a
+ * consumer is most likely to be holding at the moment it needs to know which
+ * binary answered — "this loam does not have that flag / that code" is a
+ * question about the build, and an unversioned refusal makes it unanswerable.
+ *
+ * There is no `command` here, and adding one is not a small change. The error
+ * emitter has no command in scope: `fail()` is called from deep inside core-ish
+ * helpers that never learn which verb the user typed, so threading it means
+ * either module-level mutable state — a hazard this codebase names outright,
+ * because a value cached at import time leaks across the forked test processes
+ * and across invocations in a long-running host — or one more argument threaded
+ * through `fail()`, `reportNoConfig()` and every deep helper that refuses, each
+ * of which would then carry a value it has no other use for. A consumer that
+ * needs to know which command refused already knows: it made the call.
+ */
+export function emitJsonError(code, message, details = {}) {
+    console.log(JSON.stringify({ contractVersion: JSON_CONTRACT_VERSION, version: LOAM_VERSION, ok: false, error: { code, message }, ...details }, null, 2));
+    process.exitCode = 1;
+    return false;
+}
+/**
+ * The refusals that print no `loam explain` pointer, each with the reason it is
+ * here. ONE named set rather than a condition per call site: "is this refusal
+ * worth looking up?" is a single question, and answering it in seven places is
+ * how two of them come to disagree.
+ *
+ * - `vouch-declined` — loam asked whether to stamp, and a person said no.
+ *   Nothing failed and there is nothing to fix, so a pointer would invite
+ *   somebody to go read the meaning of their own answer.
+ *
+ * `internal` was weighed and deliberately LEFT OUT. It is the one code with no
+ * stable meaning, which reads like a reason to stay silent — but its
+ * explanation carries the only instruction available to a person staring at an
+ * unexpected throw (a repeatable `internal` is a loam defect worth reporting),
+ * and that is worth more than the silence the old behaviour gave them.
+ *
+ * Exported so test/explain.test.ts can pin the membership: an entry added here
+ * silently removes a pointer nobody would notice was gone.
+ */
+export const NO_EXPLAIN_POINTER = new Set(["vouch-declined"]);
+/**
+ * The one-line pointer from a refusal to the command that explains it.
+ *
+ * Measured over eight wrong invocations a person makes in their first hour —
+ * no loam.json, an unknown service, an unknown feature, an unbound `gherkin`,
+ * a malformed feature id — every single one printed prose and no code, and
+ * only `loam validate` mentioned `loam explain` at all. `explain` is the best
+ * usability asset loam has and the message that most needs it could not reach
+ * it: to look a refusal up you first had to re-run the whole command with
+ * `--json` and read `error.code` out of the envelope, which is precisely the
+ * knowledge a first-hour user does not have. The code is printed as well as
+ * the invocation because the two are different needs: the bare code is what
+ * goes into a bug report, a grep or a CI branch, and the invocation is what
+ * answers it here.
+ *
+ * STDERR, never stdout, and that is the load-bearing half: a refusal's
+ * diagnostic must not pollute a piped payload. `loam show svc > out.json`
+ * already keeps its message off stdout, and a pointer that broke that rule
+ * would corrupt exactly the pipelines text mode was careful never to touch.
+ * (Findings do the opposite — their codes go to stdout with the report, in
+ * document order, for validate/report.ts's own reason. Same fact, two streams,
+ * because a finding is the answer and a refusal is the absence of one.)
+ *
+ * Nothing runs here under `--json`: the envelope already carries `error.code`
+ * as data, and a machine reader has no use for being told a second command
+ * exists — the same doctrine `EXPLAIN_FOOTER` follows in
+ * commands/policy/format.ts.
+ *
+ * No ANSI escape, though the line is meant to READ as dim. Nothing in this
+ * codebase emits escape sequences, the output is graded by tests that compare
+ * strings, and a colour that survives into a redirected file or a CI log is
+ * noise nobody asked for. The typography does the dimming: the code, a spaced
+ * middot, the command — an aside, not a sentence.
+ */
+export function sayExplain(code) {
+    if (NO_EXPLAIN_POINTER.has(code))
+        return;
+    console.error(`${code}  ·  loam explain ${code}`);
+}
+/**
+ * Report a failure in whichever mode the caller is in. Text mode goes to
+ * stderr as it always has — now with the code and its lookup on a second line;
+ * JSON mode goes into the envelope, whose stdout bytes are unchanged.
+ */
+export function fail(json, code, message) {
+    if (json) {
+        emitJsonError(code, message);
+        return;
+    }
+    console.error(message);
+    sayExplain(code);
+    process.exitCode = 1;
+}
+/** The message every command prints when there is no loam.json. */
+const NO_CONFIG_MESSAGE = "No loam.json found. Run `loam init --docs <dir>` first.";
+/**
+ * The message the service-scoped commands print when neither `--service` nor
+ * loam.json names one. Four commands ask the same question and owe the same two
+ * answers, and a fifth would have been written by hand. `loam delta` keeps its
+ * own longer sentence on purpose — it can say which feature was being read.
+ */
+export const NO_SERVICE_MESSAGE = "No service. Pass --service <id> or set it in loam.json.";
+/**
+ * Report "no config" in whichever mode the caller is in — distinguishing a
+ * config that is absent from one that exists but would not load, because the
+ * two point at opposite fixes: a missing config wants `loam init`, a corrupt
+ * one wants repair, and `init` would silently rewrite the corrupt file. The
+ * distinction arrives as DATA on the load outcome rather than being re-derived
+ * from the filesystem here — the file could change between the load and a
+ * re-check, and the parse problem itself is worth showing.
+ */
+export function reportNoConfig(json, load) {
+    if (load.kind === "invalid") {
+        fail(json, "config-invalid", `Invalid loam.json: ${load.problem}. Fix it (or delete it and re-run \`loam init\`).`);
+        return;
+    }
+    fail(json, "no-config", NO_CONFIG_MESSAGE);
+}
+//# sourceMappingURL=json.js.map

package/dist/core/envelope/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../../src/core/envelope/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AA0H3C;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAgC;IACvD,OAAO,CAAC,GAAG,CACT,IAAI,CAAC,SAAS,CAAC,EAAE,eAAe,EAAE,qBAAqB,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CACjH,CAAC;AACJ,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,GAAW;IACnD,OAAO,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAe,EACf,OAAe,EACf,OAAO,GAA4B,EAAE;IAErC,OAAO,CAAC,GAAG,CACT,IAAI,CAAC,SAAS,CACZ,EAAE,eAAe,EAAE,qBAAqB,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,EAClH,IAAI,EACJ,CAAC,CACF,CACF,CAAC;IACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACrB,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA2B,IAAI,GAAG,CAAY,CAAC,gBAAgB,CAAC,CAAC,CAAC;AAEjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,UAAU,CAAC,IAAe;IACxC,IAAI,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO;IACzC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,qBAAqB,IAAI,EAAE,CAAC,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,IAAa,EAAE,IAAe,EAAE,OAAe;IAClE,IAAI,IAAI,EAAE,CAAC;QACT,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC7B,OAAO;IACT,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACvB,UAAU,CAAC,IAAI,CAAC,CAAC;IACjB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;AAED,mEAAmE;AACnE,MAAM,iBAAiB,GAAG,yDAAyD,CAAC;AAEpF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,yDAAyD,CAAC;AAE5F;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAAa,EAAE,IAA6E;IACzH,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,CACF,IAAI,EACJ,gBAAgB,EAChB,sBAAsB,IAAI,CAAC,OAAO,mDAAmD,CACtF,CAAC;QACF,OAAO;IACT,CAAC;IACD,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAC;AAC7C,CAAC","sourcesContent":["/**\n * The `--json` envelope — loam's machine contract.\n *\n * Every JSON response carries `ok`. Success spreads the payload alongside it;\n * failure carries a stable `error.code` a caller can branch on without parsing\n * prose. Errors go to stdout too: a consumer reads one stream and always gets\n * valid JSON, whether the command succeeded or not. The exit code still tells\n * the shell what happened.\n *\n * Three keys identify the envelope before its payload is read, and they answer\n * three different questions: `contractVersion` is the SHAPE's version,\n * `version` is the BINARY's, and `command` (on every success payload) says\n * which verb produced it. The first two are stamped by the emitters below so\n * no command can forget them; the third is the payload's own first key,\n * because only the command knows its name.\n *\n * Key casing: camelCase, with one deliberate exception — a key that mirrors a\n * frontmatter field verbatim keeps that field's snake_case spelling\n * (`last_verified`, `sources_digest` in vouch's payload), so the envelope and\n * the document it describes spell the same fact the same way. snake_case only\n * where a key mirrors a frontmatter field verbatim; camelCase everywhere else.\n */\nimport { relative } from \"node:path\";\nimport { LOAM_VERSION } from \"./version.js\";\n\n/**\n * Version of the top-level JSON envelope, independent of the CLI/package\n * version. Additive payload fields do not require a bump; incompatible changes\n * to `ok`, `error`, or their semantics do.\n */\nexport const JSON_CONTRACT_VERSION = \"1.0\";\n\n/**\n * Stable failure codes. Prose may change; these may not.\n *\n * The `sources-*` pair mirrors the `sources.*` finding codes on purpose: the\n * same breach is recognisable whether it arrives as a refusal from `vouch` or\n * as a finding from `validate`.\n *\n * The `feature-active` / `snapshot-*` group is `unarchive` refusing to guess:\n * each names a different reason the undo is not one, and a caller has to tell\n * them apart to know whether re-running could ever work. Its commit failures\n * split the same way archive's do: `restore-failed` means nothing was restored\n * or everything was rolled back — the living docs are unchanged and re-running\n * can work; `rollback-incomplete` (shared with archive, same meaning) means\n * some files could not be put back, and the message lists them.\n *\n * The `answers-*` group is `loam verify --record` refusing an answer set that\n * does not answer the current checklist. They are separated for the same reason:\n * an unreadable file is a bug in whatever wrote it, a mismatch means the feature\n * moved and the claims have to be answered again, and an unevidenced\n * confirmation is the one an agent can fix on the spot.\n *\n * The archive group is `loam archive` refusing or failing, and each code is a\n * different answer to \"what do I fix, and can I trust the repo?\": `not-coherent`\n * is the gate — issues in the FEATURE, carried in `issues[]`. Most yield to\n * `--approve`; the ones that do not name an illegal service id — a\n * `specs/<svc>/` directory name (`delta.service-id-invalid`) or a\n * `metadata { service }` binding (`c4.service-binding-invalid`) — because the\n * name IS the path the merge would write, and the fix is a rename, never a\n * flag. A consumer branches on data, not prose: coherence issues carry the\n * additive `overridable` key resolved per issue, and a refusal `--approve`\n * cannot move says \"--approve does not override this\" in `error.message`;\n * `living-outside-requirements` is the refusal whose fault is not the\n * feature's — the LIVING spec holds requirements outside `## Requirements`,\n * and the merge would duplicate them, so the fix is in the living docs, and\n * `--approve` does not move it either; `archive-exists` is a\n * destination collision under `features/archive/`; `merge-failed` is a merge\n * that could not be computed or was rolled back — either way the living docs\n * are unchanged; `rollback-incomplete` is the one that demands a human: the\n * merge failed AND some files could not be restored.\n *\n * `config-invalid` is distinct from `no-config` because the fixes point in\n * opposite directions: a missing config wants `loam init`, a corrupt one wants\n * repair — and an agent that ran `init` on a corrupt file would silently\n * rewrite it.\n *\n * `internal` is the one code with no stable meaning: an unexpected throw. It\n * exists so a `--json` consumer still receives an envelope instead of a stack\n * trace on stdout's sibling stream.\n */\nexport type ErrorCode =\n  | \"no-config\"\n  | \"config-invalid\"\n  | \"unknown-target\"\n  | \"invalid-option\"\n  | \"already-exists\"\n  | \"sources-absent\"\n  | \"sources-path-missing\"\n  | \"not-coherent\"\n  | \"living-outside-requirements\"\n  | \"archive-exists\"\n  | \"merge-failed\"\n  | \"rollback-incomplete\"\n  | \"feature-active\"\n  | \"snapshot-missing\"\n  | \"snapshot-stale\"\n  /** A snapshot pre-image whose bytes no longer match the digest archive recorded for them: `unarchive` will not restore text nobody wrote. */\n  | \"snapshot-corrupt\"\n  /** A `loam archive`/`unarchive` was killed mid-commit: the living docs are half-written, and this run refuses rather than writing over the evidence. */\n  | \"commit-interrupted\"\n  | \"restore-failed\"\n  | \"answers-unreadable\"\n  | \"answers-mismatch\"\n  | \"answers-unevidenced\"\n  | \"service-mismatch\"\n  | \"unknown-service\"\n  | \"repository-unavailable\"\n  /** `loam verify --record` without `--service` over a federated (schema 2) record: it would erase other repositories' attestations. */\n  | \"record-federated\"\n  /** A `verification.yaml` that exists but cannot be read as a record — never overwritten, never reported as absent. */\n  | \"record-unreadable\"\n  /** `loam verify --record` found the record changed between its locked read and the swap — an editor or a lock-ignoring writer landed first. Nothing was written; re-running merges over the record as it now stands. */\n  | \"record-raced\"\n  /** `loam gherkin <FEAT>` refusing to overwrite a `.feature` file owned by another feature still in flight. */\n  | \"gherkin-conflict\"\n  /** `loam vouch` found the spec changed under it between reading and stamping — another vouch or an edit landed first, and nothing was written. */\n  | \"vouch-raced\"\n  /** `loam vouch` with nothing on the other end of stdin and no `--yes`: the stamp is a person's claim, and nobody was asked. */\n  | \"vouch-unattended\"\n  /** `loam vouch` could not learn who is vouching — git names no `user.email` here, so the stamp would record a claim with nobody behind it. */\n  | \"vouch-unattributable\"\n  /** `loam vouch` was asked to confirm and the answer was no. Nothing was stamped; this is a successful refusal, not a failure. */\n  | \"vouch-declined\"\n  /** `docsDir` in loam.json points at nothing: the docs repo was never cloned, or the path is wrong. A read command refuses rather than reporting an empty fleet. */\n  | \"docs-missing\"\n  /** `docsDir` is a directory but has no `services/`: it is some other directory, most often the service repo itself after a typo. */\n  | \"services-missing\"\n  /** Another loam writer holds the docs repo's advisory lock: nothing was read or written, and re-running once it finishes works. `verify --record` waits out a short holder before giving this answer. */\n  | \"docs-busy\"\n  /** `loam subsystem rm` refusing a subsystem that still holds members — services or child subsystems, named in the message. A destructive command never picks targets the caller did not name: move them out (or remove the children) first, then re-run. */\n  | \"subsystem-not-empty\"\n  /** `loam subsystem move`/`rename` refusing because git reports uncommitted or untracked paths under a directory being moved — the ONLY move-specific refusal: the rename would sweep them into a move nobody reviewed. Commit them, `git stash -u` (plain `stash` leaves untracked files behind), or remove them, then re-run. When git cannot answer at all the move proceeds — refusal needs positive evidence. */\n  | \"move-uncommitted\"\n  /** A subsystem move/rename failed and was rolled back cleanly: every rename undone, the generated views file restored, the docs unchanged — re-running can work. Distinct from `merge-failed` because no merge was computed; a failure that could NOT be fully undone is `rollback-incomplete`, exactly as for archive. */\n  | \"move-failed\"\n  /** `loam open` found no service checkout bound to this docs repo under any scanned root — the workspace would hold only the docs repo. Re-running can succeed once a bound checkout exists beside it, or with `--root` pointing where the checkouts live. */\n  | \"no-members\"\n  /** Two discovered repositories' committed loam.json files declare the same `service` for this docs repo — two checkouts of one service, or a copied config. loam will not guess which checkout speaks for the service; narrow the scan with `--root` or fix the stray binding, then re-run. */\n  | \"binding-duplicate\"\n  /** `loam list --owners` could not use the user-named CODEOWNERS file: the path cannot be read, or a line in it cannot be parsed as `pattern owner…` (the message names the line). Fail-closed like `answers-unreadable` for the other user-named file — a half-read ownership file must never file a service under the wrong team. Re-running succeeds once the path or the line is fixed. */\n  | \"owners-unreadable\"\n  /** `loam seed`'s fleet file is missing, unreadable, not YAML, the wrong shape, carries an illegal id or name, or no longer names every existing `services/<id>/` (that arm carries the additive `missingServices` payload key). The message names the file and, where one exists, the line; editing the file and re-running succeeds. */\n  | \"seed-file-invalid\"\n  /** fleet.yaml declares one name twice — as two services, or as both a service and an external/subsystem. Service ids, subsystem names and externals share one flat namespace (a call endpoint must name exactly one thing); the message names both declaration lines. Rename one and re-run. */\n  | \"seed-duplicate-service\"\n  /** A service's `subsystem:` in fleet.yaml names nothing `subsystems:` declares; the message carries a did-you-mean hint over the names the file really declares. Fix the spelling (or add the subsystem) and re-run. */\n  | \"seed-unknown-subsystem\"\n  /** architecture/landscape.likec4 carries hand edits (the line-1 stamp's digest no longer matches) or was authored some other way (no stamp, and not the scaffold's untouched stub). Seed never overwrites human work and nothing was written; re-running cannot succeed until the file is deleted or the edits are folded into fleet.yaml. */\n  | \"seed-landscape-edited\"\n  | \"internal\";\n\n/**\n * `version` is stamped HERE rather than by each command for the reason the\n * `command` discriminator was not, and had to be retrofitted one call site at a\n * time: a key every envelope owes is a key no command can be trusted to\n * remember. Two lines in the two emitters give it to every command and every\n * refusal at once, and a command added tomorrow cannot ship without it.\n *\n * Why a consumer needs it at all: `docs.binary-behind` exists to say that a\n * green run from an old binary is worth less than it looks, and a caller\n * holding only a `--json` payload could not tell which loam produced it — so it\n * could not apply that caution, and could not see a mixed-version fleet in the\n * contract. It sits beside `contractVersion`, never inside it: the envelope\n * SHAPE and the binary that filled it version independently, and collapsing\n * them would make every release look like a contract break.\n */\nexport function emitJson(payload: Record<string, unknown>): void {\n  console.log(\n    JSON.stringify({ contractVersion: JSON_CONTRACT_VERSION, version: LOAM_VERSION, ok: true, ...payload }, null, 2),\n  );\n}\n\n/** Paths in the contract are repo-relative, with forward slashes: diffable across machines. */\nexport function repoPath(docsDir: string, abs: string): string {\n  return relative(docsDir, abs).split(/[\\\\/]/).join(\"/\");\n}\n\n/**\n * Emit a failure envelope and set the exit code. Returns false, to `return`\n * from a caller.\n *\n * `version` is on this path too, and deliberately: a refusal is the envelope a\n * consumer is most likely to be holding at the moment it needs to know which\n * binary answered — \"this loam does not have that flag / that code\" is a\n * question about the build, and an unversioned refusal makes it unanswerable.\n *\n * There is no `command` here, and adding one is not a small change. The error\n * emitter has no command in scope: `fail()` is called from deep inside core-ish\n * helpers that never learn which verb the user typed, so threading it means\n * either module-level mutable state — a hazard this codebase names outright,\n * because a value cached at import time leaks across the forked test processes\n * and across invocations in a long-running host — or one more argument threaded\n * through `fail()`, `reportNoConfig()` and every deep helper that refuses, each\n * of which would then carry a value it has no other use for. A consumer that\n * needs to know which command refused already knows: it made the call.\n */\nexport function emitJsonError(\n  code: ErrorCode,\n  message: string,\n  details: Record<string, unknown> = {},\n): false {\n  console.log(\n    JSON.stringify(\n      { contractVersion: JSON_CONTRACT_VERSION, version: LOAM_VERSION, ok: false, error: { code, message }, ...details },\n      null,\n      2,\n    ),\n  );\n  process.exitCode = 1;\n  return false;\n}\n\n/**\n * The refusals that print no `loam explain` pointer, each with the reason it is\n * here. ONE named set rather than a condition per call site: \"is this refusal\n * worth looking up?\" is a single question, and answering it in seven places is\n * how two of them come to disagree.\n *\n * - `vouch-declined` — loam asked whether to stamp, and a person said no.\n *   Nothing failed and there is nothing to fix, so a pointer would invite\n *   somebody to go read the meaning of their own answer.\n *\n * `internal` was weighed and deliberately LEFT OUT. It is the one code with no\n * stable meaning, which reads like a reason to stay silent — but its\n * explanation carries the only instruction available to a person staring at an\n * unexpected throw (a repeatable `internal` is a loam defect worth reporting),\n * and that is worth more than the silence the old behaviour gave them.\n *\n * Exported so test/explain.test.ts can pin the membership: an entry added here\n * silently removes a pointer nobody would notice was gone.\n */\nexport const NO_EXPLAIN_POINTER: ReadonlySet<ErrorCode> = new Set<ErrorCode>([\"vouch-declined\"]);\n\n/**\n * The one-line pointer from a refusal to the command that explains it.\n *\n * Measured over eight wrong invocations a person makes in their first hour —\n * no loam.json, an unknown service, an unknown feature, an unbound `gherkin`,\n * a malformed feature id — every single one printed prose and no code, and\n * only `loam validate` mentioned `loam explain` at all. `explain` is the best\n * usability asset loam has and the message that most needs it could not reach\n * it: to look a refusal up you first had to re-run the whole command with\n * `--json` and read `error.code` out of the envelope, which is precisely the\n * knowledge a first-hour user does not have. The code is printed as well as\n * the invocation because the two are different needs: the bare code is what\n * goes into a bug report, a grep or a CI branch, and the invocation is what\n * answers it here.\n *\n * STDERR, never stdout, and that is the load-bearing half: a refusal's\n * diagnostic must not pollute a piped payload. `loam show svc > out.json`\n * already keeps its message off stdout, and a pointer that broke that rule\n * would corrupt exactly the pipelines text mode was careful never to touch.\n * (Findings do the opposite — their codes go to stdout with the report, in\n * document order, for validate/report.ts's own reason. Same fact, two streams,\n * because a finding is the answer and a refusal is the absence of one.)\n *\n * Nothing runs here under `--json`: the envelope already carries `error.code`\n * as data, and a machine reader has no use for being told a second command\n * exists — the same doctrine `EXPLAIN_FOOTER` follows in\n * commands/policy/format.ts.\n *\n * No ANSI escape, though the line is meant to READ as dim. Nothing in this\n * codebase emits escape sequences, the output is graded by tests that compare\n * strings, and a colour that survives into a redirected file or a CI log is\n * noise nobody asked for. The typography does the dimming: the code, a spaced\n * middot, the command — an aside, not a sentence.\n */\nexport function sayExplain(code: ErrorCode): void {\n  if (NO_EXPLAIN_POINTER.has(code)) return;\n  console.error(`${code}  ·  loam explain ${code}`);\n}\n\n/**\n * Report a failure in whichever mode the caller is in. Text mode goes to\n * stderr as it always has — now with the code and its lookup on a second line;\n * JSON mode goes into the envelope, whose stdout bytes are unchanged.\n */\nexport function fail(json: boolean, code: ErrorCode, message: string): void {\n  if (json) {\n    emitJsonError(code, message);\n    return;\n  }\n  console.error(message);\n  sayExplain(code);\n  process.exitCode = 1;\n}\n\n/** The message every command prints when there is no loam.json. */\nconst NO_CONFIG_MESSAGE = \"No loam.json found. Run `loam init --docs <dir>` first.\";\n\n/**\n * The message the service-scoped commands print when neither `--service` nor\n * loam.json names one. Four commands ask the same question and owe the same two\n * answers, and a fifth would have been written by hand. `loam delta` keeps its\n * own longer sentence on purpose — it can say which feature was being read.\n */\nexport const NO_SERVICE_MESSAGE = \"No service. Pass --service <id> or set it in loam.json.\";\n\n/**\n * Report \"no config\" in whichever mode the caller is in — distinguishing a\n * config that is absent from one that exists but would not load, because the\n * two point at opposite fixes: a missing config wants `loam init`, a corrupt\n * one wants repair, and `init` would silently rewrite the corrupt file. The\n * distinction arrives as DATA on the load outcome rather than being re-derived\n * from the filesystem here — the file could change between the load and a\n * re-check, and the parse problem itself is worth showing.\n */\nexport function reportNoConfig(json: boolean, load: { kind: \"absent\" } | { kind: \"invalid\"; path: string; problem: string }): void {\n  if (load.kind === \"invalid\") {\n    fail(\n      json,\n      \"config-invalid\",\n      `Invalid loam.json: ${load.problem}. Fix it (or delete it and re-run \\`loam init\\`).`,\n    );\n    return;\n  }\n  fail(json, \"no-config\", NO_CONFIG_MESSAGE);\n}\n"]}

package/dist/core/{version.js → envelope/version.js}

@@ -1,7 +1,7 @@
 /**
  * One version string, owned by package.json — read once, imported everywhere a
- * version is spoken. `../../package.json` resolves from src/core/ in dev and
- * from dist/core/ in the published layout alike.
+ * version is spoken. `../../../package.json` resolves from src/core/envelope/ in
+ * dev and from dist/core/envelope/ in the published layout alike.
  */
 import { createRequire } from "node:module";
 /**
@@ -20,5 +20,5 @@ function readVersion(pkg) {
     }
     return version;
 }
-export const LOAM_VERSION = readVersion(createRequire(import.meta.url)("../../package.json"));
+export const LOAM_VERSION = readVersion(createRequire(import.meta.url)("../../../package.json"));
 //# sourceMappingURL=version.js.map

package/dist/core/envelope/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../src/core/envelope/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;GAQG;AACH,SAAS,WAAW,CAAC,GAAY;IAC/B,MAAM,OAAO,GAAG,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,SAAS,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACtG,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,gGAAgG,CACjG,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC","sourcesContent":["/**\n * One version string, owned by package.json — read once, imported everywhere a\n * version is spoken. `../../../package.json` resolves from src/core/envelope/ in\n * dev and from dist/core/envelope/ in the published layout alike.\n */\nimport { createRequire } from \"node:module\";\n\n/**\n * The read is checked rather than asserted because the failure it would let\n * through is silent, permanent, and invisible on the machine that caused it: an\n * absent or empty `version` stamps `vundefined` into every file loam generates,\n * `agentsStampVersion` then cannot parse that stamp back, and every repository\n * built by that build reports its agent files stale forever with nothing to\n * point at. A build that cannot say what it is has nothing useful to do, so it\n * says so once, loudly, while its own module is being evaluated.\n */\nfunction readVersion(pkg: unknown): string {\n  const version = pkg !== null && typeof pkg === \"object\" && \"version\" in pkg ? pkg.version : undefined;\n  if (typeof version !== \"string\" || version === \"\") {\n    throw new Error(\n      \"readVersion: package.json declares no non-empty 'version', so this build cannot say what it is\",\n    );\n  }\n  return version;\n}\n\nexport const LOAM_VERSION = readVersion(createRequire(import.meta.url)(\"../../../package.json\"));\n"]}