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

package/dist/commands/gherkin/reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../../../src/commands/gherkin/reconcile.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The plan against what is already on disk: which files are orphans, which are\n * written, replaced, kept, or owned by another feature.\n *\n * A module of its own because it is the only part of `loam gherkin` that\n * DELETES, and the reasoning that makes deletion safe is all here: a candidate\n * is an orphan only when its containing directory really resolves inside the\n * owned root, and a root that does not resolve proves nothing about what lives\n * beneath it, so nothing is collected. Leaving an orphan behind is\n * self-repairing — `loam validate` grades it and the next run removes it — and a\n * deletion taken on an unproven path is not.\n *\n * The in-flight exemption is here for the same reason: files are named by\n * requirement slug in both modes, so a MODIFIED requirement's living emission\n * always collides with the active feature's file, and replacing it reverted the\n * delta's wording mid-flight with its digest stamps destroyed.\n */\nimport { existsSync, realpathSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { dirname, join, relative } from \"node:path\";\nimport { type PlannedFeature } from \"../../core/gherkin/emit.js\";\nimport { parseStampedFeature, type StampedFeature } from \"../../core/gherkin/read.js\";\nimport { featureFilesUnder } from \"../../core/gherkin/stale.js\";\nimport { isPathInside, resolveInside, UnsafePathError } from \"../../core/kernel/path-safety.js\";\n\n/**\n * The run's scope as ONE value, not a mode with an id lying beside it that only\n * one of the modes ever fills in: the emission tag, the orphan filter, the\n * overwrite rule and the conflict refusal all want the feature id exactly when\n * the run is a feature run. A union states that; two variables could only be\n * asserted to agree.\n */\nexport type Scope = { mode: \"living\" } | { mode: \"feature\"; featureId: string };\n\nexport type Emission = PlannedFeature & { path: string };\n\n/**\n * The row's shape follows its action instead of carrying every field any action\n * might want: only a kept or a conflicting row has read the file that is\n * already there, and only a conflicting one has owners. Held as one flat row\n * with optional fields, every reader had to assert what the writer three lines\n * up already knew.\n */\nexport type ActionRow =\n  | (Emission & { action: \"written\" })\n  // A replaced row carries the exact bytes it was graded against, so the\n  // commit can prove the file did not move between the grading and the swap —\n  // planning and committing must compare the same read, or a mismatch is\n  // buried instead of refused.\n  | (Emission & { action: \"replaced\"; raw: Buffer })\n  | (Emission & { action: \"kept\"; kept: StampedFeature })\n  | (Emission & { action: \"conflict\"; kept: StampedFeature; owners: string[] });\n\nexport type Action = ActionRow[\"action\"];\n\n/** Where the suite lives: the owned root, inside the service repository. */\nexport interface EmissionRoot {\n  root: string;\n  repoDir: string;\n}\n\nexport interface Reconciliation {\n  /** Each orphan with the bytes its grading read — the commit compares them before deleting. */\n  orphans: { path: string; raw: Buffer }[];\n  actions: ActionRow[];\n  /** Non-empty only in feature mode; one entry refuses the whole emission. */\n  conflicts: Extract<ActionRow, { action: \"conflict\" }>[];\n}\n\nexport async function reconcile(\n  plan: PlannedFeature[],\n  where: EmissionRoot,\n  scope: Scope,\n  activeIds: ReadonlySet<string>,\n): Promise<Reconciliation> {\n  const { root, repoDir } = where;\n  // Living mode owns the whole suite — any .feature not in the plan goes —\n  // EXCEPT files tagged with a feature still in flight: those answer to\n  // their feature's delta until it archives, and `loam gherkin <FEAT>` is\n  // their regeneration.\n  const planned = new Set(plan.map((f) => f.fileName));\n  // \"Inside loam/\" has to hold after the links are resolved, not merely in\n  // the spelling of the path. `featureFilesUnder` FOLLOWS symlinks and\n  // recurses with the LINK's path, so a planted `<gherkinDir>/loam/sub ->\n  // /outside` hands back candidates that read as ours while `unlink`\n  // resolves them and destroys files that were never in this repo. Planned\n  // names are flat, so nothing nested is ever spared by `planned.has(...)`,\n  // and deletion is the one irreversible thing this command does: a\n  // candidate is an orphan only when its CONTAINING directory really\n  // resolves inside the owned root. The write path below refuses the same\n  // attack for the same reason.\n  //\n  // The candidate FILE is deliberately NOT resolved. A symlinked .feature\n  // sitting directly in loam/ is loam's to remove — unlinking it takes the\n  // link and leaves its target alone — so only the directory chain has to\n  // be ours.\n  const realOrNull = (p: string): string | null => {\n    try {\n      return realpathSync(p);\n    } catch {\n      return null;\n    }\n  };\n  // A root that does not resolve — absent, dangling, or vanished mid-run —\n  // proves nothing about what lives beneath it, so nothing is collected.\n  // Leaving an orphan behind is self-repairing (`loam validate` grades it\n  // `gherkin.orphaned` and the next run removes it); a deletion taken on an\n  // unproven path is not.\n  const rootReal = realOrNull(root);\n  const orphans: { path: string; raw: Buffer }[] = [];\n  if (rootReal !== null) {\n    for (const abs of await featureFilesUnder(root)) {\n      if (planned.has(relative(root, abs).split(/[\\\\/]/).join(\"/\"))) continue;\n      const holder = realOrNull(dirname(abs));\n      if (holder === null || !isPathInside(rootReal, holder)) continue;\n      const raw = await readFile(abs);\n      const stamped = parseStampedFeature(raw.toString(\"utf8\"));\n      if (scope.mode === \"feature\") {\n        if (stamped !== null && stamped.tags.includes(scope.featureId)) orphans.push({ path: abs, raw });\n      } else {\n        if (stamped !== null && stamped.tags.some((t) => activeIds.has(t))) continue;\n        orphans.push({ path: abs, raw });\n      }\n    }\n  }\n\n  // The in-flight exemption guards the OVERWRITE path too, not only the\n  // orphan scan above: files are named by requirement slug in both modes,\n  // so a MODIFIED requirement's living emission always collides with the\n  // active feature's file — and replacing it reverted the delta's wording\n  // mid-flight, feature tag and new digest stamps destroyed, invisibly\n  // (the reverted file grades current against the living spec). A planned\n  // path whose existing content is stamped and tagged with a feature still\n  // in flight is KEPT and reported as such; it answers to its feature's\n  // delta until the feature archives, and then living regeneration\n  // replaces it normally.\n  //\n  // FEATURE mode has the same collision and cannot solve it by keeping:\n  // two features in flight against one requirement slug want the same\n  // file, and whichever runs second used to `replace` — silently reverting\n  // the other feature's wording, feature tag and digest stamps, so its\n  // `verify --results` could never confirm a scenario again. Nothing loam\n  // can write is right here (the file holds ONE feature's delta), so the\n  // run refuses and names the owner: the two features have to be sequenced,\n  // or the requirement renamed.\n  const actions: ActionRow[] = [];\n  for (const f of plan) {\n    let path: string;\n    try {\n      // Check the final file as well as the owned root: a pre-planted\n      // `<slug>.feature` symlink must not turn writeFile into an overwrite\n      // outside the repository.\n      path = resolveInside(\n        repoDir,\n        relative(repoDir, join(root, f.fileName)),\n        `gherkin file '${f.fileName}'`,\n      );\n    } catch (err) {\n      if (!(err instanceof UnsafePathError)) throw err;\n      throw err;\n    }\n    if (!existsSync(path)) {\n      actions.push({ ...f, path, action: \"written\" });\n      continue;\n    }\n    const raw = await readFile(path);\n    const existing = parseStampedFeature(raw.toString(\"utf8\"));\n    if (scope.mode === \"living\") {\n      if (existing !== null && existing.tags.some((t) => activeIds.has(t))) {\n        actions.push({ ...f, path, action: \"kept\", kept: existing });\n        continue;\n      }\n    } else if (existing !== null) {\n      // An unstamped file is nobody's delta — it owns nothing, so it is\n      // replaced like any other, which is what the empty owner list used\n      // to say the long way round.\n      const owners = existing.tags.filter((t) => t !== scope.featureId && activeIds.has(t));\n      if (owners.length > 0) {\n        actions.push({ ...f, path, action: \"conflict\", kept: existing, owners });\n        continue;\n      }\n    }\n    actions.push({ ...f, path, action: \"replaced\", raw });\n  }\n\n  // All or nothing: one conflicting file refuses the whole emission, so a\n  // half-written suite can never be the state an agent has to reason about.\n  // Only a feature run can conflict — living mode keeps the in-flight file\n  // rather than refusing — and standing inside that scope is also how the\n  // message names the feature without asserting there is one.\n  const conflicts = scope.mode === \"feature\"\n    ? actions.filter((a): a is Extract<ActionRow, { action: \"conflict\" }> => a.action === \"conflict\")\n    : [];\n\n  return { orphans, actions, conflicts };\n}\n"]}

package/dist/commands/gherkin/render.js

@@ -0,0 +1,77 @@
+/**
+ * The emission as a person reads it.
+ *
+ * A module of its own for `adopt/render.ts`'s reason: `--json` already carries
+ * every field below, so this decides only how they read — and the two
+ * per-scenario warnings are why that is worth separating. Both name something
+ * in a scenario body that did NOT survive into the emission, while the file
+ * that came out is valid Gherkin and the summary line counts it like any other.
+ * They are the only place those losses are visible at all, so they must not
+ * share a module with the write path that can grow past them.
+ */
+import { relative } from "node:path";
+import {} from "./reconcile.js";
+/**
+ * `conflict` never reaches the renderer — the run refuses before it — but the
+ * map is total so a future action cannot silently print `undefined`.
+ */
+const VERB = {
+    written: "write  ",
+    replaced: "replace",
+    kept: "keep   ",
+    conflict: "CONFLICT",
+};
+/** Every per-scenario loss, in one shape: what was written, and what became of it. */
+const LOSSES = [
+    {
+        of: (a) => (a.action === "kept" ? [] : a.stepless),
+        why: "has NO recognizable steps — cucumber runs it vacuously green and `verify --results` can never " +
+            "confirm it; reword its body as `- **Given/When/Then**` bullets",
+    },
+    {
+        of: (a) => (a.action === "kept" ? [] : a.malformedExamples),
+        why: "has a table loam could not read as Examples — every row must have the header's column count, " +
+            "and a header needs at least one row under it. It stayed in the description, so this scenario " +
+            "runs ONCE, not once per case",
+    },
+    {
+        of: (a) => (a.action === "kept" ? [] : a.strandedBlocks),
+        why: "wrote a fenced block or an indented table where no step precedes it, or a table loam could " +
+            "not read — it stayed in the description, so the step definition receives NO payload and no " +
+            "data table; put the block under the step it belongs to and give every row equal columns",
+    },
+];
+export function render(actions, ctx) {
+    const { service, root, dryRun, featureId } = ctx;
+    const head = featureId === null ? `${service} (living suite)` : `${featureId} · ${service}`;
+    console.log(`gherkin ${head} → ${root}/${dryRun ? "  (dry run)" : ""}\n`);
+    if (actions.length === 0) {
+        console.log(featureId === null
+            ? `  the living specs hold no requirements for ${service} — nothing to emit.`
+            : `  ${featureId} has no ADDED or MODIFIED requirements for ${service} — nothing to emit.`);
+    }
+    for (const a of actions) {
+        if (a.action === "kept") {
+            const owners = a.kept.tags.filter((t) => ctx.activeIds.has(t));
+            console.log(`  keep     ${a.fileName}  —  ${a.requirement.name}  (in flight: @${owners.join(" @")} — \`loam gherkin ${owners[0]}\` regenerates it)`);
+            continue;
+        }
+        const n = a.digests.length;
+        const arch = a.axis.key === "archSpec" ? ", arch" : "";
+        console.log(`  ${VERB[a.action]}  ${a.fileName}  —  ${a.requirement.name}  (${n} scenario${n === 1 ? "" : "s"}${arch})`);
+        for (const loss of LOSSES) {
+            for (const name of loss.of(a))
+                console.log(`      ⚠ scenario '${name}' ${loss.why}`);
+        }
+    }
+    for (const o of ctx.orphans) {
+        console.log(`  delete   ${relative(ctx.absRoot, o).split(/[\\/]/).join("/")}  —  no longer in this scope`);
+    }
+    const wrote = `${ctx.writes} file(s)`;
+    const keptNote = actions.length > ctx.writes ? `, ${actions.length - ctx.writes} kept in flight` : "";
+    const dropped = ctx.orphans.length > 0 ? `, ${ctx.orphans.length} deletion(s)` : "";
+    console.log(dryRun
+        ? `\n  ${wrote}${keptNote}${dropped} — dry run, nothing was written.`
+        : `\n  ${wrote} written${keptNote}${dropped}. Write step definitions OUTSIDE ${root}/ — regeneration rewrites it.`);
+}
+//# sourceMappingURL=render.js.map

package/dist/commands/gherkin/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../src/commands/gherkin/render.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The emission as a person reads it.\n *\n * A module of its own for `adopt/render.ts`'s reason: `--json` already carries\n * every field below, so this decides only how they read — and the two\n * per-scenario warnings are why that is worth separating. Both name something\n * in a scenario body that did NOT survive into the emission, while the file\n * that came out is valid Gherkin and the summary line counts it like any other.\n * They are the only place those losses are visible at all, so they must not\n * share a module with the write path that can grow past them.\n */\nimport { relative } from \"node:path\";\nimport { type Action, type ActionRow } from \"./reconcile.js\";\n\n/** What the text view needs that the plan does not carry. */\nexport interface RenderContext {\n  service: string;\n  /** Repo-relative `<gherkinDir>/loam/`. */\n  root: string;\n  /** Absolute suite root — orphan paths are printed relative to it. */\n  absRoot: string;\n  featureId: string | null;\n  dryRun: boolean;\n  /** Feature ids still in flight, for naming who owns a kept file. */\n  activeIds: Set<string>;\n  writes: number;\n  orphans: string[];\n}\n\n/**\n * `conflict` never reaches the renderer — the run refuses before it — but the\n * map is total so a future action cannot silently print `undefined`.\n */\nconst VERB: Record<Action, string> = {\n  written: \"write  \",\n  replaced: \"replace\",\n  kept: \"keep   \",\n  conflict: \"CONFLICT\",\n};\n\n/** Every per-scenario loss, in one shape: what was written, and what became of it. */\nconst LOSSES = [\n  {\n    of: (a: ActionRow): string[] => (a.action === \"kept\" ? [] : a.stepless),\n    why:\n      \"has NO recognizable steps — cucumber runs it vacuously green and `verify --results` can never \" +\n      \"confirm it; reword its body as `- **Given/When/Then**` bullets\",\n  },\n  {\n    of: (a: ActionRow): string[] => (a.action === \"kept\" ? [] : a.malformedExamples),\n    why:\n      \"has a table loam could not read as Examples — every row must have the header's column count, \" +\n      \"and a header needs at least one row under it. It stayed in the description, so this scenario \" +\n      \"runs ONCE, not once per case\",\n  },\n  {\n    of: (a: ActionRow): string[] => (a.action === \"kept\" ? [] : a.strandedBlocks),\n    why:\n      \"wrote a fenced block or an indented table where no step precedes it, or a table loam could \" +\n      \"not read — it stayed in the description, so the step definition receives NO payload and no \" +\n      \"data table; put the block under the step it belongs to and give every row equal columns\",\n  },\n];\n\nexport function render(actions: ActionRow[], ctx: RenderContext): void {\n  const { service, root, dryRun, featureId } = ctx;\n  const head = featureId === null ? `${service} (living suite)` : `${featureId} · ${service}`;\n  console.log(`gherkin ${head} → ${root}/${dryRun ? \"  (dry run)\" : \"\"}\\n`);\n  if (actions.length === 0) {\n    console.log(\n      featureId === null\n        ? `  the living specs hold no requirements for ${service} — nothing to emit.`\n        : `  ${featureId} has no ADDED or MODIFIED requirements for ${service} — nothing to emit.`,\n    );\n  }\n  for (const a of actions) {\n    if (a.action === \"kept\") {\n      const owners = a.kept.tags.filter((t) => ctx.activeIds.has(t));\n      console.log(\n        `  keep     ${a.fileName}  —  ${a.requirement.name}  (in flight: @${owners.join(\" @\")} — \\`loam gherkin ${owners[0]}\\` regenerates it)`,\n      );\n      continue;\n    }\n    const n = a.digests.length;\n    const arch = a.axis.key === \"archSpec\" ? \", arch\" : \"\";\n    console.log(\n      `  ${VERB[a.action]}  ${a.fileName}  —  ${a.requirement.name}  (${n} scenario${n === 1 ? \"\" : \"s\"}${arch})`,\n    );\n    for (const loss of LOSSES) {\n      for (const name of loss.of(a)) console.log(`      ⚠ scenario '${name}' ${loss.why}`);\n    }\n  }\n  for (const o of ctx.orphans) {\n    console.log(`  delete   ${relative(ctx.absRoot, o).split(/[\\\\/]/).join(\"/\")}  —  no longer in this scope`);\n  }\n  const wrote = `${ctx.writes} file(s)`;\n  const keptNote = actions.length > ctx.writes ? `, ${actions.length - ctx.writes} kept in flight` : \"\";\n  const dropped = ctx.orphans.length > 0 ? `, ${ctx.orphans.length} deletion(s)` : \"\";\n  console.log(\n    dryRun\n      ? `\\n  ${wrote}${keptNote}${dropped} — dry run, nothing was written.`\n      : `\\n  ${wrote} written${keptNote}${dropped}. Write step definitions OUTSIDE ${root}/ — regeneration rewrites it.`,\n  );\n}\n"]}

package/dist/commands/init/example.js

@@ -0,0 +1,204 @@
+/**
+ * `loam init --example <dir>`: copy the example fleet OUT OF the installed
+ * binary, so somebody evaluating loam can watch it work before modelling a
+ * single boundary of their own.
+ *
+ * The defect this exists to kill was measured, not imagined. `npm i -g
+ * @ybotok/loam` used to deliver no example at all — `files[]` shipped `dist`
+ * and eight Markdown pages, `examples/` was excluded, no verb in `--help` was
+ * demo/example/tour/sample, and all three `--dry-run` flags need a docs repo
+ * that already exists. So the first honest question an evaluating team asks —
+ * "show me a working one" — was answered with "model your own boundaries
+ * first, then come back". `examples` joining `files[]` is the other half of
+ * this change; this is the half that hands the tree to the user.
+ *
+ * A flag on `init` rather than a command of its own, and the flag/command line
+ * is exactly the contradiction matrix below: `--example` shares init's SUBJECT
+ * (this directory is about to become a loam workspace) and shares nothing else
+ * with it — no repository is bound, no agent files are scaffolded, no
+ * `docsDir` is recorded. A second verb would have re-litigated all of that.
+ */
+import { existsSync, statSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { emitJson, fail } from "../../core/envelope/json.js";
+import { inOrder } from "../../core/kernel/concurrency.js";
+import { stageWrites } from "../../core/staging/commit.js";
+import { commitStaged } from "../../core/staging/txn/transaction.js";
+import { planWrite } from "../../core/staging/writes.js";
+/**
+ * The packaged example fleet, found relative to THIS module rather than to
+ * `process.cwd()` or to any config: the tree is part of the artifact, and the
+ * whole point of the flag is that it works in a directory that has nothing in
+ * it yet.
+ *
+ * `../../../` is the package root from both layouts, which is why the path is
+ * written once instead of probed: this module is `src/commands/init/` in the
+ * repository and `dist/commands/init/` in the tarball, three levels below the
+ * root either way. `scripts/package-smoke.mjs` proves the tarball half by
+ * running the shipped binary, and `examples` is in `REVIEWED_PACKAGE_FILES`
+ * (scripts/package-docs.mjs) so the tree cannot leave the package without the
+ * release preflight blocking.
+ */
+const EXAMPLE_TREE = resolve(fileURLToPath(new URL("../../../examples/docs/", import.meta.url)));
+/**
+ * The three commands the copy exists to make runnable, each with what it
+ * demonstrates. `cd` is prefixed to the first one at print time — it is the
+ * one line that is about the caller's shell rather than about loam.
+ *
+ * Spelled as `command:` string literals deliberately: that is the shape
+ * test/agent-commands-runnable.test.ts scrapes out of `src/**` (its
+ * `nextCommands`, the one `loam status`'s next[] steps use), so all three are
+ * parsed against the real commander program at gate time. loam ships
+ * instructions; an instruction that does not parse is a defect, and these are
+ * the first three an evaluating user ever types. The sibling table in
+ * first-hour.ts is reached by IMPORT instead, because its rows are tuples that
+ * no scrape can see — two mechanisms, one obligation.
+ */
+const TOUR = [
+    { command: "loam status", why: "what to do next, derived from the files" },
+    { command: "loam validate --all", why: "the gate CI runs: 0 errors, 10 deliberate warnings" },
+    { command: "loam show FEAT-101", why: "one in-flight feature, end to end" },
+];
+/**
+ * Copy the packaged example fleet to `req.dir`, or refuse.
+ *
+ * Nothing here consults `loam.json`, and that is the point of the
+ * short-circuit its caller performs: `--example` writes a FRESH tree, it does
+ * not join a system, so init's governing-config guard — which refuses when a
+ * `loam.json` in an ancestor already governs this directory — is a rule about
+ * a question this flag never asks.
+ */
+export async function initExample(req) {
+    const { json } = req;
+    // The contradiction matrix, and naming it is what keeps `--example` a FLAG
+    // rather than a second command hiding inside `init`. Each of these four asks
+    // for a write that `--example` does not make: `--docs` and `--create` name a
+    // docs repo to point at or scaffold, `--service` binds this repository to a
+    // service, `--tools` selects agent files to generate. `--example` binds no
+    // repository and scaffolds no agent files, so none of them is a modifier of
+    // it — each is a different command spelled on the same line, and arbitrating
+    // between them would be inventing which one the caller meant.
+    //
+    // `--force`, `--no-commands` and `--no-skills` are deliberately NOT here:
+    // each only SUPPRESSES something (a refusal, a set of generated files) that
+    // this path already does not do, so none of them contradicts anything.
+    if (req.conflicts.length > 0) {
+        fail(json, "invalid-option", `--example contradicts ${req.conflicts.join(" and ")}: --example copies the packaged example ` +
+            "fleet into a fresh directory — it binds no repository, records no docsDir and generates no " +
+            "agent files. Copy the example first, then run loam init in the repository you are onboarding.");
+        return;
+    }
+    const target = resolve(process.cwd(), req.dir);
+    const occupant = await occupancy(target);
+    if (occupant !== null) {
+        fail(json, "already-exists", `${target} ${occupant}. --example writes a whole tree and never merges into one that is ` +
+            "already there. Name a directory that does not exist yet, or an empty one.");
+        return;
+    }
+    const writes = await planCopy(target);
+    const staged = await stageWrites(writes);
+    // The journaled transaction every other loam writer uses, and not `cp`,
+    // because the failure mode is the same one it exists for: a copy killed
+    // half way leaves a directory that LOOKS like a docs repo and validates as a
+    // broken one, and the reader has no way to tell that from an example that
+    // was always wrong. The journal's root is the target, so a killed run leaves
+    // `.loam-commit` beside the half-tree naming every file — and every write is
+    // an exclusive create (nothing here exists yet), so two `--example` runs
+    // racing for one directory serialise into the same `already-exists` the
+    // occupancy check above gives, exactly as `loam new` does for a feature id.
+    //
+    // No docs lock is taken, and that is the one place this departs from
+    // new/seed: the lock serialises writers against a SHARED docs repo, and the
+    // target here is a directory this run is creating. There is no predecessor
+    // commit to recover in a tree that does not exist yet.
+    const committed = await commitStaged({ root: target, command: "init", rerun: `loam init --example ${req.dir}`, target: "example" }, staged, "copied");
+    if (!committed.ok) {
+        if (committed.raced) {
+            fail(json, "already-exists", `${target} was created by another writer while this copy was being staged — nothing was ` +
+                "written. Name a directory that does not exist yet, or an empty one.");
+            return;
+        }
+        fail(json, committed.code, committed.message);
+        return;
+    }
+    report(req, target, writes);
+}
+/**
+ * Why `target` cannot be written into, as the clause a refusal reads with — or
+ * null when it is free.
+ *
+ * A path that exists and is not a directory is refused by the same code as a
+ * non-empty directory on purpose: the caller's question is "may I have this
+ * name?", and the answer is no for the same reason either way.
+ */
+async function occupancy(target) {
+    if (!existsSync(target))
+        return null;
+    if (!statSync(target).isDirectory())
+        return "already exists and is not a directory";
+    return (await readdir(target)).length > 0 ? "already exists and is not empty" : null;
+}
+/** Every file of the packaged tree, planned as an exclusive create under `target`. */
+async function planCopy(target) {
+    const paths = await treePaths(EXAMPLE_TREE);
+    // BYTES, never text: `readFile` without an encoding, straight into the
+    // planned write. A round trip through a string would substitute U+FFFD for
+    // every byte loam does not understand (core/staging/writes.ts records the
+    // defect), and the contract this command is tested against is that the copy
+    // is byte-identical to the tree that shipped.
+    return inOrder(paths, async (rel) => planWrite(join(target, ...rel.split("/")), await readFile(join(EXAMPLE_TREE, ...rel.split("/")))));
+}
+/**
+ * Every FILE under `root`, relative with forward slashes, in a stable order.
+ *
+ * Sorted per directory so the write order — and therefore the transaction
+ * journal — is the same on every host, whatever order the filesystem
+ * enumerates in. Directories are not carried: the example tree has no empty
+ * one, and `stageWrites` makes each file's parent on the way in.
+ */
+async function treePaths(root) {
+    const out = [];
+    const walk = async (dir, prefix) => {
+        const entries = (await readdir(dir, { withFileTypes: true })).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+        // Sequential, and the ordering IS the reason: `out` is one shared
+        // accumulator and its order is the journal's order.
+        for (const entry of entries) {
+            const rel = `${prefix}${entry.name}`;
+            if (entry.isDirectory())
+                await walk(join(dir, entry.name), `${rel}/`);
+            else
+                out.push(rel);
+        }
+    };
+    await walk(root, "");
+    return out;
+}
+/** The two views of a finished copy. Neither reads the tree again. */
+function report(req, target, writes) {
+    const created = writes.map((w) => w.path);
+    if (req.json) {
+        emitJson({ command: "init", example: { source: EXAMPLE_TREE, dir: target }, created });
+        return;
+    }
+    console.log("Example fleet copied.");
+    console.log(`  from:  ${EXAMPLE_TREE}`);
+    console.log(`  to:    ${target}`);
+    console.log(`  files: ${created.length} — five services, four features, and its own loam.json`);
+    console.log("         the tree governs itself, so every command below resolves to this fleet");
+    // The first line carries the `cd` because the tree governs itself: these
+    // commands answer about THIS fleet only when they are run from inside it.
+    // The width is computed over the printed lines, `cd` included, so the
+    // comment column is straight.
+    const prefix = `cd ${req.dir} && `;
+    const lines = TOUR.map((step, i) => ({
+        text: i === 0 ? `${prefix}${step.command}` : step.command,
+        why: step.why,
+    }));
+    const width = Math.max(...lines.map((line) => line.text.length));
+    console.log("  next — run it:");
+    for (const line of lines)
+        console.log(`    ${line.text.padEnd(width)}   # ${line.why}`);
+}
+//# sourceMappingURL=example.js.map

package/dist/commands/init/example.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"example.js","sourceRoot":"","sources":["../../../src/commands/init/example.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam init --example <dir>`: copy the example fleet OUT OF the installed\n * binary, so somebody evaluating loam can watch it work before modelling a\n * single boundary of their own.\n *\n * The defect this exists to kill was measured, not imagined. `npm i -g\n * @ybotok/loam` used to deliver no example at all — `files[]` shipped `dist`\n * and eight Markdown pages, `examples/` was excluded, no verb in `--help` was\n * demo/example/tour/sample, and all three `--dry-run` flags need a docs repo\n * that already exists. So the first honest question an evaluating team asks —\n * \"show me a working one\" — was answered with \"model your own boundaries\n * first, then come back\". `examples` joining `files[]` is the other half of\n * this change; this is the half that hands the tree to the user.\n *\n * A flag on `init` rather than a command of its own, and the flag/command line\n * is exactly the contradiction matrix below: `--example` shares init's SUBJECT\n * (this directory is about to become a loam workspace) and shares nothing else\n * with it — no repository is bound, no agent files are scaffolded, no\n * `docsDir` is recorded. A second verb would have re-litigated all of that.\n */\nimport { existsSync, statSync } from \"node:fs\";\nimport { readdir, readFile } from \"node:fs/promises\";\nimport { join, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { emitJson, fail } from \"../../core/envelope/json.js\";\nimport { inOrder } from \"../../core/kernel/concurrency.js\";\nimport { stageWrites } from \"../../core/staging/commit.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { planWrite, type PlannedWrite } from \"../../core/staging/writes.js\";\n\n/**\n * The packaged example fleet, found relative to THIS module rather than to\n * `process.cwd()` or to any config: the tree is part of the artifact, and the\n * whole point of the flag is that it works in a directory that has nothing in\n * it yet.\n *\n * `../../../` is the package root from both layouts, which is why the path is\n * written once instead of probed: this module is `src/commands/init/` in the\n * repository and `dist/commands/init/` in the tarball, three levels below the\n * root either way. `scripts/package-smoke.mjs` proves the tarball half by\n * running the shipped binary, and `examples` is in `REVIEWED_PACKAGE_FILES`\n * (scripts/package-docs.mjs) so the tree cannot leave the package without the\n * release preflight blocking.\n */\nconst EXAMPLE_TREE = resolve(fileURLToPath(new URL(\"../../../examples/docs/\", import.meta.url)));\n\n/**\n * The three commands the copy exists to make runnable, each with what it\n * demonstrates. `cd` is prefixed to the first one at print time — it is the\n * one line that is about the caller's shell rather than about loam.\n *\n * Spelled as `command:` string literals deliberately: that is the shape\n * test/agent-commands-runnable.test.ts scrapes out of `src/**` (its\n * `nextCommands`, the one `loam status`'s next[] steps use), so all three are\n * parsed against the real commander program at gate time. loam ships\n * instructions; an instruction that does not parse is a defect, and these are\n * the first three an evaluating user ever types. The sibling table in\n * first-hour.ts is reached by IMPORT instead, because its rows are tuples that\n * no scrape can see — two mechanisms, one obligation.\n */\nconst TOUR = [\n  { command: \"loam status\", why: \"what to do next, derived from the files\" },\n  { command: \"loam validate --all\", why: \"the gate CI runs: 0 errors, 10 deliberate warnings\" },\n  { command: \"loam show FEAT-101\", why: \"one in-flight feature, end to end\" },\n];\n\nexport interface ExampleRequest {\n  /** `--example <dir>` exactly as typed: what `cd` is spelled with in the epilogue. */\n  dir: string;\n  /**\n   * Which of `--docs`, `--service`, `--create`, `--tools` were actually\n   * passed. Computed by the caller because only it can tell a typed `--docs`\n   * from commander's default.\n   */\n  conflicts: string[];\n  json: boolean;\n}\n\n/**\n * Copy the packaged example fleet to `req.dir`, or refuse.\n *\n * Nothing here consults `loam.json`, and that is the point of the\n * short-circuit its caller performs: `--example` writes a FRESH tree, it does\n * not join a system, so init's governing-config guard — which refuses when a\n * `loam.json` in an ancestor already governs this directory — is a rule about\n * a question this flag never asks.\n */\nexport async function initExample(req: ExampleRequest): Promise<void> {\n  const { json } = req;\n\n  // The contradiction matrix, and naming it is what keeps `--example` a FLAG\n  // rather than a second command hiding inside `init`. Each of these four asks\n  // for a write that `--example` does not make: `--docs` and `--create` name a\n  // docs repo to point at or scaffold, `--service` binds this repository to a\n  // service, `--tools` selects agent files to generate. `--example` binds no\n  // repository and scaffolds no agent files, so none of them is a modifier of\n  // it — each is a different command spelled on the same line, and arbitrating\n  // between them would be inventing which one the caller meant.\n  //\n  // `--force`, `--no-commands` and `--no-skills` are deliberately NOT here:\n  // each only SUPPRESSES something (a refusal, a set of generated files) that\n  // this path already does not do, so none of them contradicts anything.\n  if (req.conflicts.length > 0) {\n    fail(\n      json,\n      \"invalid-option\",\n      `--example contradicts ${req.conflicts.join(\" and \")}: --example copies the packaged example ` +\n        \"fleet into a fresh directory — it binds no repository, records no docsDir and generates no \" +\n        \"agent files. Copy the example first, then run loam init in the repository you are onboarding.\",\n    );\n    return;\n  }\n\n  const target = resolve(process.cwd(), req.dir);\n  const occupant = await occupancy(target);\n  if (occupant !== null) {\n    fail(\n      json,\n      \"already-exists\",\n      `${target} ${occupant}. --example writes a whole tree and never merges into one that is ` +\n        \"already there. Name a directory that does not exist yet, or an empty one.\",\n    );\n    return;\n  }\n\n  const writes = await planCopy(target);\n  const staged = await stageWrites(writes);\n  // The journaled transaction every other loam writer uses, and not `cp`,\n  // because the failure mode is the same one it exists for: a copy killed\n  // half way leaves a directory that LOOKS like a docs repo and validates as a\n  // broken one, and the reader has no way to tell that from an example that\n  // was always wrong. The journal's root is the target, so a killed run leaves\n  // `.loam-commit` beside the half-tree naming every file — and every write is\n  // an exclusive create (nothing here exists yet), so two `--example` runs\n  // racing for one directory serialise into the same `already-exists` the\n  // occupancy check above gives, exactly as `loam new` does for a feature id.\n  //\n  // No docs lock is taken, and that is the one place this departs from\n  // new/seed: the lock serialises writers against a SHARED docs repo, and the\n  // target here is a directory this run is creating. There is no predecessor\n  // commit to recover in a tree that does not exist yet.\n  const committed = await commitStaged(\n    { root: target, command: \"init\", rerun: `loam init --example ${req.dir}`, target: \"example\" },\n    staged,\n    \"copied\",\n  );\n  if (!committed.ok) {\n    if (committed.raced) {\n      fail(\n        json,\n        \"already-exists\",\n        `${target} was created by another writer while this copy was being staged — nothing was ` +\n          \"written. Name a directory that does not exist yet, or an empty one.\",\n      );\n      return;\n    }\n    fail(json, committed.code, committed.message);\n    return;\n  }\n\n  report(req, target, writes);\n}\n\n/**\n * Why `target` cannot be written into, as the clause a refusal reads with — or\n * null when it is free.\n *\n * A path that exists and is not a directory is refused by the same code as a\n * non-empty directory on purpose: the caller's question is \"may I have this\n * name?\", and the answer is no for the same reason either way.\n */\nasync function occupancy(target: string): Promise<string | null> {\n  if (!existsSync(target)) return null;\n  if (!statSync(target).isDirectory()) return \"already exists and is not a directory\";\n  return (await readdir(target)).length > 0 ? \"already exists and is not empty\" : null;\n}\n\n/** Every file of the packaged tree, planned as an exclusive create under `target`. */\nasync function planCopy(target: string): Promise<PlannedWrite[]> {\n  const paths = await treePaths(EXAMPLE_TREE);\n  // BYTES, never text: `readFile` without an encoding, straight into the\n  // planned write. A round trip through a string would substitute U+FFFD for\n  // every byte loam does not understand (core/staging/writes.ts records the\n  // defect), and the contract this command is tested against is that the copy\n  // is byte-identical to the tree that shipped.\n  return inOrder(paths, async (rel) =>\n    planWrite(join(target, ...rel.split(\"/\")), await readFile(join(EXAMPLE_TREE, ...rel.split(\"/\")))),\n  );\n}\n\n/**\n * Every FILE under `root`, relative with forward slashes, in a stable order.\n *\n * Sorted per directory so the write order — and therefore the transaction\n * journal — is the same on every host, whatever order the filesystem\n * enumerates in. Directories are not carried: the example tree has no empty\n * one, and `stageWrites` makes each file's parent on the way in.\n */\nasync function treePaths(root: string): Promise<string[]> {\n  const out: string[] = [];\n  const walk = async (dir: string, prefix: string): Promise<void> => {\n    const entries = (await readdir(dir, { withFileTypes: true })).sort((a, b) =>\n      a.name < b.name ? -1 : a.name > b.name ? 1 : 0,\n    );\n    // Sequential, and the ordering IS the reason: `out` is one shared\n    // accumulator and its order is the journal's order.\n    for (const entry of entries) {\n      const rel = `${prefix}${entry.name}`;\n      if (entry.isDirectory()) await walk(join(dir, entry.name), `${rel}/`);\n      else out.push(rel);\n    }\n  };\n  await walk(root, \"\");\n  return out;\n}\n\n/** The two views of a finished copy. Neither reads the tree again. */\nfunction report(req: ExampleRequest, target: string, writes: PlannedWrite[]): void {\n  const created = writes.map((w) => w.path);\n  if (req.json) {\n    emitJson({ command: \"init\", example: { source: EXAMPLE_TREE, dir: target }, created });\n    return;\n  }\n\n  console.log(\"Example fleet copied.\");\n  console.log(`  from:  ${EXAMPLE_TREE}`);\n  console.log(`  to:    ${target}`);\n  console.log(`  files: ${created.length} — five services, four features, and its own loam.json`);\n  console.log(\"         the tree governs itself, so every command below resolves to this fleet\");\n\n  // The first line carries the `cd` because the tree governs itself: these\n  // commands answer about THIS fleet only when they are run from inside it.\n  // The width is computed over the printed lines, `cd` included, so the\n  // comment column is straight.\n  const prefix = `cd ${req.dir} && `;\n  const lines = TOUR.map((step, i) => ({\n    text: i === 0 ? `${prefix}${step.command}` : step.command,\n    why: step.why,\n  }));\n  const width = Math.max(...lines.map((line) => line.text.length));\n  console.log(\"  next — run it:\");\n  for (const line of lines) console.log(`    ${line.text.padEnd(width)}   # ${line.why}`);\n}\n"]}

package/dist/commands/init/first-hour.js

@@ -0,0 +1,28 @@
+/**
+ * The four commands of the single-repo trial's first hour, each with the
+ * reason it is there. `init` prints them as its epilogue when one run both
+ * creates the docs repo and leaves a service bound (init.ts holds that guard
+ * and the why).
+ *
+ * A module of its own for two reasons. The seam: init.ts is the wiring — the
+ * flag guards and the scaffold sequence — while this table is what the trial
+ * user is told, and the table alone pushed init.ts past the 300-line limit.
+ * The export: test/agent-commands-runnable.test.ts feeds these commands
+ * through the real commander program by IMPORT, because the printed lines are
+ * plain text inside template literals — no markdown backticks, no
+ * single-quoted `loam` forms — so that suite's literal scrape cannot see
+ * them, and they are the first instruction a single-repo trial user receives:
+ * the exact class its header records shipping broken once as `loam adopt
+ * <id>`. README.md's Quick start reprints the same four lines, and
+ * test/cli.test.ts pins that copy to this table.
+ */
+export function firstHour(service) {
+    return [
+        [`loam adopt --service ${service} --json`,
+            "the brief: an agent reads the code, writes the baseline as draft"],
+        [`loam validate --service ${service}`, "grade the result in this repo"],
+        [`loam vouch --service ${service}`, "you, not the agent: draft -> verified"],
+        ["loam status", "what to do next, derived from the files"],
+    ];
+}
+//# sourceMappingURL=first-hour.js.map

package/dist/commands/init/first-hour.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"first-hour.js","sourceRoot":"","sources":["../../../src/commands/init/first-hour.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO;QACL,CAAC,wBAAwB,OAAO,SAAS;YACvC,kEAAkE,CAAC;QACrE,CAAC,2BAA2B,OAAO,EAAE,EAAE,+BAA+B,CAAC;QACvE,CAAC,wBAAwB,OAAO,EAAE,EAAE,uCAAuC,CAAC;QAC5E,CAAC,aAAa,EAAE,yCAAyC,CAAC;KAC3D,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The four commands of the single-repo trial's first hour, each with the\n * reason it is there. `init` prints them as its epilogue when one run both\n * creates the docs repo and leaves a service bound (init.ts holds that guard\n * and the why).\n *\n * A module of its own for two reasons. The seam: init.ts is the wiring — the\n * flag guards and the scaffold sequence — while this table is what the trial\n * user is told, and the table alone pushed init.ts past the 300-line limit.\n * The export: test/agent-commands-runnable.test.ts feeds these commands\n * through the real commander program by IMPORT, because the printed lines are\n * plain text inside template literals — no markdown backticks, no\n * single-quoted `loam` forms — so that suite's literal scrape cannot see\n * them, and they are the first instruction a single-repo trial user receives:\n * the exact class its header records shipping broken once as `loam adopt\n * <id>`. README.md's Quick start reprints the same four lines, and\n * test/cli.test.ts pins that copy to this table.\n */\nexport function firstHour(service: string): Array<[command: string, why: string]> {\n  return [\n    [`loam adopt --service ${service} --json`,\n      \"the brief: an agent reads the code, writes the baseline as draft\"],\n    [`loam validate --service ${service}`, \"grade the result in this repo\"],\n    [`loam vouch --service ${service}`, \"you, not the agent: draft -> verified\"],\n    [\"loam status\", \"what to do next, derived from the files\"],\n  ];\n}\n"]}