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

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,72 @@
+/**
+ * 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"],
+    ];
+}
+/**
+ * The first hour of a docs repo created with NO service bound — WORKFLOW.md's
+ * Day zero steps 2–4, and the same rungs `loam status` answers on an empty
+ * fleet (`next.author-landscape`, `next.bind-service`, `next.adopt-first`).
+ *
+ * This run used to print nothing after the scaffold list: the single-repo
+ * table above needs a service id to name, and the guard that withheld it read
+ * "nothing is bound" as "nothing to say". But this is the Day zero composition
+ * itself — the person who just created the fleet's shared repo — and its next
+ * steps are as fixed as the trial's: state the map, bind each service's own
+ * repo, adopt. The ids are placeholders because nothing here knows them yet,
+ * which is also why the runnable-commands suite substitutes them like every
+ * other `<id>` it parses. Exported for that suite, by import, for the reason
+ * the header gives.
+ *
+ * The bind line names `--agent-profile service` because it is run in a
+ * SERVICE checkout of a fleet whose features are authored and archived here,
+ * in this docs repo: the profile defaults to `full`, and `full` puts
+ * `loam-feature` and `loam-ship` into every service repo — the outcome
+ * README's "Pass the profile explicitly" warns against. Agents type the
+ * command loam prints, not the README.
+ */
+export function docsRepoFirstHour() {
+    return [
+        ["loam seed --from fleet.yaml", "the fleet map from a fleet.yaml you write, or draw it by hand"],
+        ["loam init --docs <docs-repo> --service <id> --agent-profile service",
+            "in each service's own repo: bind it, commit loam.json"],
+        ["loam adopt --service <id> --json", "there: the brief, an agent writes the baseline as draft"],
+        ["loam status", "what to do next, derived from the files"],
+    ];
+}
+/**
+ * The epilogue's printed lines — the heading and one aligned `command   # why`
+ * row per step — for whichever first hour this run earned. Rendering only:
+ * init.ts decides WHETHER (never on a join), this decides which table and how
+ * it reads, so the two variants cannot drift into two layouts.
+ */
+export function firstHourLines(service) {
+    const [heading, steps] = service === undefined
+        ? ["next — the docs repo's first hour:", docsRepoFirstHour()]
+        : ["next — the first hour:", firstHour(service)];
+    const width = Math.max(...steps.map(([command]) => command.length));
+    return [`  ${heading}`, ...steps.map(([command, why]) => `    ${command.padEnd(width)}   # ${why}`)];
+}
+//# 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;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,CAAC,6BAA6B,EAAE,+DAA+D,CAAC;QAChG,CAAC,qEAAqE;YACpE,uDAAuD,CAAC;QAC1D,CAAC,kCAAkC,EAAE,yDAAyD,CAAC;QAC/F,CAAC,aAAa,EAAE,yCAAyC,CAAC;KAC3D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAA2B;IACxD,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,OAAO,KAAK,SAAS;QAC5C,CAAC,CAAC,CAAC,oCAAoC,EAAE,iBAAiB,EAAE,CAAC;QAC7D,CAAC,CAAC,CAAC,wBAAwB,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IACnD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACpE,OAAO,CAAC,KAAK,OAAO,EAAE,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,EAAE,CAAC,CAAC,CAAC;AACvG,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\n/**\n * The first hour of a docs repo created with NO service bound — WORKFLOW.md's\n * Day zero steps 2–4, and the same rungs `loam status` answers on an empty\n * fleet (`next.author-landscape`, `next.bind-service`, `next.adopt-first`).\n *\n * This run used to print nothing after the scaffold list: the single-repo\n * table above needs a service id to name, and the guard that withheld it read\n * \"nothing is bound\" as \"nothing to say\". But this is the Day zero composition\n * itself — the person who just created the fleet's shared repo — and its next\n * steps are as fixed as the trial's: state the map, bind each service's own\n * repo, adopt. The ids are placeholders because nothing here knows them yet,\n * which is also why the runnable-commands suite substitutes them like every\n * other `<id>` it parses. Exported for that suite, by import, for the reason\n * the header gives.\n *\n * The bind line names `--agent-profile service` because it is run in a\n * SERVICE checkout of a fleet whose features are authored and archived here,\n * in this docs repo: the profile defaults to `full`, and `full` puts\n * `loam-feature` and `loam-ship` into every service repo — the outcome\n * README's \"Pass the profile explicitly\" warns against. Agents type the\n * command loam prints, not the README.\n */\nexport function docsRepoFirstHour(): Array<[command: string, why: string]> {\n  return [\n    [\"loam seed --from fleet.yaml\", \"the fleet map from a fleet.yaml you write, or draw it by hand\"],\n    [\"loam init --docs <docs-repo> --service <id> --agent-profile service\",\n      \"in each service's own repo: bind it, commit loam.json\"],\n    [\"loam adopt --service <id> --json\", \"there: the brief, an agent writes the baseline as draft\"],\n    [\"loam status\", \"what to do next, derived from the files\"],\n  ];\n}\n\n/**\n * The epilogue's printed lines — the heading and one aligned `command   # why`\n * row per step — for whichever first hour this run earned. Rendering only:\n * init.ts decides WHETHER (never on a join), this decides which table and how\n * it reads, so the two variants cannot drift into two layouts.\n */\nexport function firstHourLines(service: string | undefined): string[] {\n  const [heading, steps] = service === undefined\n    ? [\"next — the docs repo's first hour:\", docsRepoFirstHour()]\n    : [\"next — the first hour:\", firstHour(service)];\n  const width = Math.max(...steps.map(([command]) => command.length));\n  return [`  ${heading}`, ...steps.map(([command, why]) => `    ${command.padEnd(width)}   # ${why}`)];\n}\n"]}

package/dist/commands/{init.js → init/init.js}

@@ -1,64 +1,18 @@
 import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
-import { CONFIG_FILENAME, findConfigPath, loadConfig, localConfigPath, saveConfig, } from "../core/config.js";
-import { emitJson, fail } from "../core/json.js";
-import { plannedDocsFiles, scaffoldDocs } from "../core/docs.js";
-import { agentsPath, docsRepoState, listServices } from "../core/repo.js";
-import { InvalidIdError, assertServiceId } from "../core/ids.js";
-import { AGENT_TOOLS, detectAgentTools, plannedCommandFiles, scaffoldAgentCommands, } from "../core/agent.js";
-/**
- * Resolve --tools to registry ids, or null after reporting the refusal. The
- * default (the cwd scan) lives at the call site, not in commander, so an
- * explicit `--tools` is distinguishable from none — which is what lets both the
- * autodetection fallback and the `--no-*` contradiction be decided instead of
- * silently arbitrated.
- */
-function resolveTools(raw, json) {
-    const supported = Object.keys(AGENT_TOOLS);
-    if (raw === "all")
-        return supported;
-    const ids = [...new Set(raw.split(",").map((t) => t.trim()).filter((t) => t !== ""))];
-    const unknown = ids.filter((t) => !(t in AGENT_TOOLS));
-    if (ids.length === 0 || unknown.length > 0) {
-        fail(json, "invalid-option", (ids.length === 0
-            ? "--tools names no tool."
-            : `--tools does not recognize: ${unknown.join(", ")}.`) +
-            ` Supported: ${supported.join(", ")} — or "all".`);
-        return null;
-    }
-    return ids;
-}
-/**
- * `--docs` exactly as the caller wrote it, with separators normalised.
- *
- * Stored verbatim on purpose. `init` used to resolve it and write the absolute
- * result, which meant a committed loam.json named a directory that existed on
- * one laptop: every teammate who cloned the service repo got a docsDir under
- * someone else's home directory, and `loam list` reported an empty fleet
- * instead of saying so. `loadConfig` resolves relative paths against the config
- * file's own directory, so `../docs` keeps meaning "next to this repo" wherever
- * the pair is checked out. An absolute `--docs` is still stored absolute — that
- * is the caller's explicit choice, and `loam doctor` warns about it.
- *
- * Backslashes become forward slashes so a config written on Windows resolves on
- * POSIX; a trailing separator is dropped so the stored spelling is stable.
- */
-function storedDocsDir(raw) {
-    const slashed = raw.split("\\").join("/");
-    if (slashed.length <= 1)
-        return slashed;
-    const trimmed = slashed.replace(/\/+$/, "");
-    return trimmed === "" ? "/" : trimmed;
-}
-/**
- * Does this directory already hold a docs repo? `services/` plus `AGENTS.md` —
- * the two things every docs repo has and no service repo does. The pair is the
- * whole point: a single marker would make `init --docs ../srv` (a typo for
- * `../docs`) look like a join and adopt the service repo as the fleet.
- */
-function isDocsRepo(dir) {
-    return docsRepoState(dir).kind === "ok" && existsSync(agentsPath(dir));
-}
+import { CONFIG_FILENAME, findConfigPath, loadConfig, localConfigPath, saveConfig, } from "../../core/envelope/config.js";
+import { docsDirOf } from "../../core/kernel/ids/dirs.js";
+import { emitJson, fail } from "../../core/envelope/json.js";
+import { plannedDocsFiles, scaffoldDocs } from "../../core/docs.js";
+import { docsRepoState } from "../../core/repo/state.js";
+import { listServices } from "../../core/repo/repo.js";
+import { InvalidIdError, assertServiceId } from "../../core/kernel/ids/service.js";
+import { detectAgentTools, plannedCommandFiles, syncAgentCommands, updatedAgentFileManifest, } from "../../core/agent/scaffold.js";
+import { AGENT_TOOLS } from "../../core/agent/tools/registry.js";
+import { initExample } from "./example.js";
+import { firstHourLines } from "./first-hour.js";
+import { MCP_CONFIG_FILENAME, mcpConfigPath, mcpServerSnippet, writeMcpConfig } from "./mcp.js";
+import { isDocsRepo, resolveAgentProfile, resolveTools, storedDocsDir } from "./options.js";
 export function registerInit(program) {
     program
         .command("init")
@@ -69,12 +23,42 @@ export function registerInit(program) {
         .option("--force", `write ${CONFIG_FILENAME} here even though one governs a parent directory`)
         .option("--tools <ids>", "agent tools to generate for, overriding the scan of this directory: " +
         `comma-separated (${Object.keys(AGENT_TOOLS).join(", ")}) or "all"`)
+        .option("--agent-profile <profile>", "workflow set: full | service | docs")
+        .option("--example <dir>", "copy the packaged example fleet to <dir> and stop: no repository is bound, nothing is scaffolded")
         .option("--no-commands", "skip the slash commands for this repo entirely")
         .option("--no-skills", "skip the agent skills for this repo entirely")
+        .option("--mcp", `also write ${MCP_CONFIG_FILENAME} here, so an MCP host launches \`loam mcp\` for this repo`)
+        .option("--mcp-author", `write ${MCP_CONFIG_FILENAME} with the opt-in authoring profile`)
         .option("--json", "emit the machine contract instead of the human view")
         .action(async (opts, command) => {
         const json = opts.json === true;
         const cwd = process.cwd();
+        // FIRST, before every guard below including the governing-config one:
+        // `--example` writes a fresh tree, it does not join a system. A
+        // loam.json in an ancestor governs the directories a repository is bound
+        // INTO, and this flag binds nothing — refusing here would be the tool
+        // declining to show itself working because of a config that has no
+        // bearing on the copy. Before the --service id check too, so a run
+        // combining the two answers the contradiction rather than grading an id
+        // it is about to refuse to use.
+        if (opts.example !== undefined) {
+            await initExample({
+                dir: opts.example,
+                conflicts: [
+                    // `--docs` carries a default, so only its SOURCE can say whether
+                    // anybody typed it — the same question the docsDir precedence
+                    // below asks, for the same reason.
+                    ...(command.getOptionValueSource("docs") !== "default" ? ["--docs"] : []),
+                    ...(opts.service !== undefined ? ["--service"] : []),
+                    ...(opts.create === true ? ["--create"] : []),
+                    ...(opts.tools !== undefined ? ["--tools"] : []),
+                    ...(opts.agentProfile !== undefined ? ["--agent-profile"] : []),
+                    ...(opts.mcpAuthor === true ? ["--mcp-author"] : []),
+                ],
+                json,
+            });
+            return;
+        }
         // The id becomes services/<id>/ in the shared repo, so it is validated
         // before anything is written — by the same rule adopt, vouch and gherkin
         // use, never by a guard invented here.
@@ -103,7 +87,12 @@ export function registerInit(program) {
         // Only THIS directory's config is spread forward. Under --force there is
         // a config in an ancestor too, and inheriting its `service` would bind
         // this repo to a service somebody else's repo declared.
-        const existing = existsSync(localConfigPath(cwd)) ? await loadConfig(cwd) : null;
+        // `kind: "invalid"` reads as null on purpose: init REPAIRS a corrupt
+        // loam.json by rewriting it, so a config nobody can read is treated
+        // exactly like no config at all. The old stderr line about it was
+        // core's side effect, promised nowhere.
+        const load = existsSync(localConfigPath(cwd)) ? await loadConfig(cwd) : null;
+        const existing = load?.kind === "loaded" ? load.config : null;
         // A re-run must not move a committed pointer. `--docs` has a default
         // (`.loam-docs`), so an init invoked for any OTHER reason — `--service`,
         // a new `--tools`, the fix `doctor.agent-files-missing` prints — used to
@@ -118,7 +107,11 @@ export function registerInit(program) {
         const docsTyped = command.getOptionValueSource("docs") !== "default";
         const docsSource = docsTyped ? "flag" : committedDocs === undefined ? "default" : "config";
         const docsOption = !docsTyped && committedDocs !== undefined ? committedDocs : opts.docs;
-        const docsDir = resolve(cwd, docsOption);
+        // Branded at the resolution, because the guards below are what validate
+        // it — the brand's provenance is "an explicit --docs a command
+        // validated", and this command is the one that does. The STORED spelling
+        // (`storedDocsDir` below) deliberately stays a plain string.
+        const docsDir = docsDirOf(resolve(cwd, docsOption));
         // The one predictable failure: --docs naming a file. Refused here so the
         // caller gets a clean envelope/message instead of mkdir's ENOTDIR throw.
         if (existsSync(docsDir) && !statSync(docsDir).isDirectory()) {
@@ -165,33 +158,72 @@ export function registerInit(program) {
         const tools = opts.tools === undefined ? scanned : resolveTools(opts.tools, json);
         if (tools === null)
             return;
-        // `skipped` is the other half of the never-overwrite contract: the
-        // scaffolds return only what they created, so what they left alone is
-        // probed here, before they run — in the order they would create it, so
-        // created + skipped is the same list on every repo. Both halves come from
-        // the scaffolds' own planned-file lists, so the probe cannot drift from
-        // what is actually written.
-        const agentFiles = delivery.length > 0 ? plannedCommandFiles(cwd, tools, delivery) : [];
-        const candidates = [...plannedDocsFiles(docsDir), ...agentFiles.map((f) => f.path)];
-        const skipped = candidates.filter((p) => existsSync(p));
+        const profile = resolveAgentProfile(opts.agentProfile, existing?.agentProfile, json);
+        if (profile === null)
+            return;
+        // Probe the pre-existing paths in planned order. Managed files refreshed
+        // below are removed from `skipped`; custom and already-current files stay.
+        const plannedAgentFiles = delivery.length > 0 ? plannedCommandFiles(cwd, tools, delivery, profile) : [];
+        // `.mcp.json` joins the same list rather than being reported on the side:
+        // it is a scaffolded path like any other, so it must appear in `created`
+        // or in `skipped` by the one rule that governs both. Last, because it is
+        // written last.
+        const candidates = [
+            ...plannedDocsFiles(docsDir),
+            ...plannedAgentFiles.map((f) => f.path),
+            ...(opts.mcp === true || opts.mcpAuthor === true ? [mcpConfigPath(cwd)] : []),
+        ];
+        let skipped = candidates.filter((p) => existsSync(p));
         // Joining touches the docs repo not at all: it is somebody's committed
         // repository, and "point at it" must never mean "write to it".
         const created = joining && opts.create !== true ? [] : (await scaffoldDocs(docsDir)).created;
         const generatedFor = delivery.length > 0 ? tools : [];
+        let refreshed = [];
+        let managedFiles = {};
         if (delivery.length > 0) {
-            created.push(...(await scaffoldAgentCommands(cwd, tools, delivery)));
+            const synced = await syncAgentCommands({
+                cwd,
+                toolIds: tools,
+                delivery,
+                profile,
+                known: existing?.agentFiles,
+            });
+            created.push(...synced.created);
+            refreshed = synced.refreshed;
+            managedFiles = synced.managed;
+            skipped = skipped.filter((path) => !refreshed.includes(path));
+        }
+        // The third delivery, and the only machine-readable one. It refuses out
+        // loud rather than being written best-effort: a `.mcp.json` half-landed
+        // is a host that starts a broken server, and the caller asked for it by
+        // name. Before saveConfig, so a run that cannot write this file has not
+        // yet moved the committed pointer either.
+        let mcpWritten = false;
+        if (opts.mcp === true || opts.mcpAuthor === true) {
+            const write = await writeMcpConfig(cwd, opts.mcpAuthor === true);
+            if (write.kind === "failed") {
+                fail(json, write.code, write.message);
+                return;
+            }
+            mcpWritten = write.kind === "created";
+            if (mcpWritten)
+                created.push(mcpConfigPath(cwd));
         }
         const stored = storedDocsDir(docsOption);
         // Union, not replacement: this run's files join the ones earlier runs left
         // on disk, and `agentTools` is a record of what the repo HOLDS. A run that
         // generated nothing adds nothing and erases nothing.
         const recordedTools = [...new Set([...(existing?.agentTools ?? []), ...generatedFor])];
+        const agentFileManifest = updatedAgentFileManifest(cwd, plannedAgentFiles, existing?.agentFiles, managedFiles);
         const config = {
             ...existing,
             docsDir: stored,
             ...(opts.service ? { service: opts.service } : {}),
             ...(recordedTools.length > 0 ? { agentTools: recordedTools } : {}),
+            agentProfile: profile,
         };
+        if (Object.keys(agentFileManifest).length > 0)
+            config.agentFiles = agentFileManifest;
         const configFile = await saveConfig(config, cwd);
         const serviceCount = (await listServices(docsDir)).length;
         if (json) {
@@ -204,6 +236,7 @@ export function registerInit(program) {
             // changing: an agent comparing the two learns whether its selection
             // matches the repo.
             emitJson({
+                command: "init",
                 docsDir,
                 docsDirStored: stored,
                 // Where the pointer came from: `flag` (a --docs somebody typed),
@@ -213,8 +246,10 @@ export function registerInit(program) {
                 docsRepo: joining ? "existing" : "created",
                 services: serviceCount,
                 created,
+                refreshed,
                 skipped,
                 tools: generatedFor,
+                agentProfile: profile,
                 detected,
             });
             return;
@@ -240,11 +275,47 @@ export function registerInit(program) {
             console.log(`  commands:  ${tools.join(", ")}`);
         if (opts.skills)
             console.log(`  skills:    ${tools.join(", ")}`);
+        console.log(`  profile:   ${profile}`);
         if (created.length > 0) {
             console.log("  scaffolded:");
             for (const c of created)
                 console.log(`    + ${c}`);
         }
+        if (refreshed.length > 0) {
+            console.log("  refreshed (unchanged since loam last wrote them):");
+            for (const path of refreshed)
+                console.log(`    ↻ ${path}`);
+        }
+        // The one skipped path that earns more than its line in `skipped`: loam
+        // will not merge into a `.mcp.json` a human owns, and the caller asked
+        // for this delivery by name — so they are handed the exact key to paste
+        // into their own `mcpServers` object. Nothing was read out of their file
+        // to produce it; the snippet is the same bytes a fresh write would have
+        // used, which is also why it names the launch form this install shape
+        // actually needs.
+        if ((opts.mcp === true || opts.mcpAuthor === true) && !mcpWritten) {
+            console.log(`  mcp:       ${MCP_CONFIG_FILENAME} is already here — left exactly as it is.`);
+            console.log(`             paste this into its "mcpServers" object:`);
+            for (const line of mcpServerSnippet(cwd, opts.mcpAuthor === true))
+                console.log(`               ${line}`);
+        }
+        // Printed ONLY when this run created the docs repo. With a service bound
+        // (the binding may predate the run — the config spread above carries an
+        // existing loam.json's `service` forward) it is the single-repo trial's
+        // hour. `loam status` is NOT mute here — its first-hour ladder
+        // (core/status/fleet/next.ts) already answers `next.adopt-bound` in
+        // exactly this state — but status has to be run to say so, and no status
+        // rung ever names `loam vouch`, the one step of this loop that is a
+        // person's; init's output is already on screen, so it prints the whole
+        // hour once. With none bound it is the docs repo's own hour (map, bind,
+        // adopt — first-hour.ts says why that used to be silence). A join stays
+        // silent on purpose: a joined fleet has other repositories already
+        // through this loop, and `loam status` in its docs repo is the working
+        // guide there. The --json path returned above, so the envelope is
+        // byte-identical to before this block existed: neither variant has a key.
+        if (!joining)
+            for (const line of firstHourLines(config.service))
+                console.log(line);
     });
 }
 //# sourceMappingURL=init.js.map