@inixiative/config 0.5.201 → 0.5.202

package/README.md

@@ -71,7 +71,7 @@ TypeScript 6.0 notes, discovered by this repo's fixture suite:
 bunx @inixiative/config check [dir] [--preset=base|node|react]
 bunx @inixiative/config sync  [dir] [--preset=...] [--force] [--no-install]
 bunx @inixiative/config scan  [root] [--lane=primitives|agentic]
-bunx @inixiative/config train [root] [--lane=primitives|agentic] [--push] [--dry-run]
+bunx @inixiative/config train [root] [--lane=primitives|agentic] [--push] [--dry-run] [--adopt-check-timeout=<seconds>]
 bunx @inixiative/config ports [project]
 bunx @inixiative/config terms [dir] [--write-baseline]
 ```
@@ -110,10 +110,10 @@ Lanes stand alone. A lane with a package missing a checkout, or claimed by ambig
 Blessing is two-phase, so a dependent that needs work never deadlocks a release:
 
 1. **Candidate.** A published version is recorded under `candidates`, and the config release that ends the train carries it, so `check` in any repo's CI accepts it from then on.
-2. **Adopt.** A repo (lane checkout or consumer) whose check fails against the candidates it was moved onto doesn't stop the train. Its checkout is put back as it was, and the train opens `train/adopt-<pkg>-<version>` in a worktree (the repo's own `worktree:create <base> <branch>` when it declares one, so a template-based repo gets its slot's databases, released with its `worktree:destroy`; otherwise a temporary linked worktree; either way with the repo's ignored `.env*` files copied in where missing): the same bump and re-lock, then the repo's `train:adopt` script if its package.json declares one (Foundry's re-records cassettes with `bun run test:live`), all committed, and re-locked onto the new config release so its CI judges it against the candidates. `--push` pushes the branch; the train opens no PR. A lane checkout that adopts publishes nothing this run. A consumer that passes against candidates commits on its default branch, like any other passing repo. If the adoption's commit is refused (its hooks typecheck), the branch is deleted and the summary says to adopt by hand.
-3. **Promote.** At the end of each run a candidate is blessed (moved into its lane's section) unless something holds it: its lane stopped; a repo has an adoption branch for it that is not yet on its default branch (opened this run, unmerged, or committed but never pushed); or a repo that declares it was not walked to an outcome this run (another lane's checkout, a skipped or failed one, a consumer without a checkout). A later train finds a waiting adoption branch and opens nothing new; once it merges, the repo is on the candidate and the train promotes it. A candidate every dependent already accepts is blessed in the run that published it. An adoption branch abandoned without merging holds its candidates until it is deleted; the next train that moves that repo deletes it.
+2. **Adopt.** A repo (lane checkout or consumer) whose check fails against the candidates it was moved onto doesn't stop the train. Its checkout is put back as it was, and the train opens `train/adopt-<pkg>-<version>` in a worktree (the repo's own `worktree:create <base> <branch>` when it declares one, so a template-based repo gets its slot's databases, released with its `worktree:destroy`; otherwise a temporary linked worktree; either way with the repo's ignored `.env*` files copied in where missing): the same bump and re-lock, then the repo's `train:adopt` script if its package.json declares one (Foundry's re-records cassettes with `bun run test:live`), and a commit. The train stages its own writes (the package.json files and `bun.lock`) before `train:adopt` runs and captures what the script wrote as it exits. That output joins the commit only if the script passed and the repo's `check` then passes with it in place, within `--adopt-check-timeout` seconds (default 1800; a timeout is a failure). That check runs against the config release the train started from, before the branch is re-locked onto the new one. Anything the check itself writes is never committed. Otherwise the adoption is **incomplete**: the commit is the re-lock alone (`chore: adopt <label> (incomplete)`, with a `Train-Adopt: incomplete (<reason>)` trailer), and the script's output, edits to owned files included, is saved on `<branch>-output`, one commit on top of it, which `--push` pushes beside the branch. Later trains read the trailer, keep reporting the branch as incomplete, and print what to run to finish it: `bun run train:adopt && bun run check` on the branch, then a commit with the trailer `Train-Adopt: complete`. A repo that declares no `train:adopt` gets the re-lock alone. `--dry-run` never fails a check, so for each repo moving onto candidates it prints how an adoption would be decided. The branch is then re-locked onto the new config release so its CI judges it against the candidates. `--push` pushes the branch; the train opens no PR. A lane checkout that adopts publishes nothing this run. A consumer that passes against candidates commits on its default branch, like any other passing repo. If the adoption's commit is refused (its hooks typecheck), the branch is deleted and the summary says to adopt by hand.
+3. **Promote.** At the end of each run a candidate is blessed (moved into its lane's section) unless something holds it: its lane stopped; a repo has an adoption branch for it that is not yet on its default branch (opened this run, incomplete, unmerged, or committed but never pushed); or a repo that declares it was not walked to an outcome this run (another lane's checkout, a skipped or failed one, a consumer without a checkout). A later train finds a waiting adoption branch and opens nothing new; once it merges, the repo is on the candidate and the train promotes it. A candidate every dependent already accepts is blessed in the run that published it. An adoption branch abandoned without merging holds its candidates until it is deleted; the next train that moves that repo deletes it.
 
-The summary lists what was blessed, every candidate with what holds it, every hold with its reason, and each pending adoption branch.
+The summary lists what was blessed, every candidate with what holds it (an incomplete adoption is marked so), every hold with its reason, and each pending adoption branch.
 
 **Holds.** A hold keeps a package's breaking line out of the blessed set while its dependents can't take it yet (signet 0.12 waiting on Kingdom's grants cutover), without stopping the package's own releases or anyone else's:
 

package/dist/cli.js

@@ -1008,12 +1008,13 @@ var OPTIONS = {
   check: { preset },
   sync: { preset, force: flag, "no-install": flag },
   scan: { lane },
-  train: { lane, push: flag, "dry-run": flag },
+  train: { lane, push: flag, "dry-run": flag, "adopt-check-timeout": { type: "string" } },
   ports: {},
   terms: { "write-baseline": flag }
 };
 var UsageError = class extends Error {
 };
+var DEFAULT_ADOPT_CHECK_TIMEOUT = 30 * 60;
 var isCommand = (value) => COMMANDS.includes(value);
 var parseCommandLine = (argv) => {
   const command2 = argv[0];
@@ -1050,6 +1051,11 @@ var parseCommandLine = (argv) => {
   if (typeof laneValue === "string" && !isLane(laneValue)) {
     throw new UsageError(`unknown lane: ${laneValue}`);
   }
+  const timeoutValue = values["adopt-check-timeout"];
+  const adoptCheckTimeout2 = typeof timeoutValue === "string" ? Number(timeoutValue) : DEFAULT_ADOPT_CHECK_TIMEOUT;
+  if (!Number.isInteger(adoptCheckTimeout2) || adoptCheckTimeout2 <= 0) {
+    throw new UsageError(`--adopt-check-timeout takes whole seconds, got ${timeoutValue}`);
+  }
   return {
     command: command2,
     positionals: positionals2,
@@ -1059,6 +1065,7 @@ var parseCommandLine = (argv) => {
     noInstall: values["no-install"] === true,
     push: values.push === true,
     dryRun: values["dry-run"] === true,
+    adoptCheckTimeout: adoptCheckTimeout2,
     writeBaseline: values["write-baseline"] === true
   };
 };
@@ -1349,7 +1356,7 @@ try {
   );
   process.exit(2);
 }
-var { command, positionals, preset: presetFlag, dryRun } = commandLine;
+var { command, positionals, preset: presetFlag, dryRun, adoptCheckTimeout } = commandLine;
 var dir = resolve2(positionals[0] ?? ".");
 if (command === "ports") {
   const project = positionals[0];
@@ -1664,18 +1671,52 @@ if (command === "train") {
     if (git(cwd, "rev-parse", "--verify", "--quiet", ref).status !== 0) return null;
     return Number(git(cwd, "rev-list", "--count", `HEAD..${ref}`).stdout.trim());
   };
+  const outputBranch = (branch) => `${branch}-output`;
+  const incompleteReason = (cwd, ref) => {
+    const newest = git(
+      cwd,
+      "log",
+      "--format=%(trailers:key=Train-Adopt,valueonly,separator=%x2C)",
+      `HEAD..${ref}`
+    ).stdout.split("\n").map((value) => value.trim()).find(Boolean);
+    if (!newest?.startsWith("incomplete")) return null;
+    return /\((.*)\)/.exec(newest)?.[1] ?? "no reason recorded";
+  };
   const pendingAdoption = (checkout, moving) => {
     if (moving.length === 0) return false;
     const branch = adoptionBranch(moving);
     const remote = ahead(checkout.dir, `refs/remotes/origin/${branch}`);
     const local = ahead(checkout.dir, `refs/heads/${branch}`);
     if (!remote && !local) return false;
+    walked.add(checkout.dir);
+    const reason = incompleteReason(
+      checkout.dir,
+      remote ? `refs/remotes/origin/${branch}` : `refs/heads/${branch}`
+    );
+    if (reason) {
+      const output = outputBranch(branch);
+      const saved = [`refs/heads/${output}`, `refs/remotes/origin/${output}`].some(
+        (ref) => git(checkout.dir, "rev-parse", "--verify", "--quiet", ref).status === 0
+      );
+      console.log(`\u23F3 adopting ${moving.join(", ")} on ${branch} \u2014 incomplete (${reason})`);
+      console.log(
+        `  finish it: on ${branch}, run \`bun run train:adopt && bun run check\`, commit what it wrote with \`git commit --trailer 'Train-Adopt: complete'\`, and push${saved ? `; the last train's output is on ${output}` : ""}`
+      );
+      waiting.push({
+        name: checkout.name,
+        dir: checkout.dir,
+        moving,
+        state: "incomplete",
+        branch,
+        reason
+      });
+      return true;
+    }
     const state = remote ? "unmerged" : "unpushed";
     console.log(
       `\u23F3 adopting ${moving.join(", ")} on ${branch} \u2014 ${state === "unmerged" ? "waiting for it to merge" : "never pushed: push it"}`
     );
     waiting.push({ name: checkout.name, dir: checkout.dir, moving, state, branch });
-    walked.add(checkout.dir);
     return true;
   };
   const worktree = (checkout, branch) => {
@@ -1716,29 +1757,93 @@ if (command === "train") {
     git(checkout.dir, "branch", "-D", branch);
   };
   const defaultBranch = (cwd) => offDefaultBranch(cwd)?.main ?? currentBranch(cwd);
+  const captureOutput = (cwd) => {
+    const changed = [
+      ...git(cwd, "diff", "--name-only", "-z").stdout.split("\0"),
+      ...git(cwd, "ls-files", "--others", "--exclude-standard", "-z").stdout.split("\0")
+    ].filter(Boolean);
+    if (changed.length === 0) return null;
+    const scratch = mkdtempSync(join3(tmpdir(), "inixiative-train-"));
+    try {
+      const env = { ...process.env, GIT_INDEX_FILE: join3(scratch, "index") };
+      const step = (...args) => {
+        const result = spawnSync3("git", args, { cwd, env, encoding: "utf8" });
+        if (result.status !== 0) {
+          throw new Abort(`git ${args[0]} failed capturing train:adopt's output`);
+        }
+        return result.stdout.trim();
+      };
+      step("read-tree", git(cwd, "write-tree").stdout.trim());
+      step("add", "-A", "--", ...changed);
+      return step("write-tree");
+    } finally {
+      rmSync3(scratch, { recursive: true, force: true });
+    }
+  };
+  const adoptionPlan = (script, output) => script ? `re-lock, run train:adopt, then the check \u2014 complete if both pass, else incomplete with the re-lock only and train:adopt's output saved on ${output}` : "re-lock and commit";
+  const previewAdoption = (checkout, moving) => {
+    if (!dryRun || moving.length === 0) return;
+    const branch = adoptionBranch(moving);
+    console.log(
+      `  [dry-run] would, if its check fails against the candidates, open ${branch} in ${checkout.name}: ${adoptionPlan(checkout.pkg.scripts?.["train:adopt"], outputBranch(branch))}`
+    );
+  };
   const adopt = (checkout, moving) => {
     const branch = adoptionBranch(moving);
+    const output = outputBranch(branch);
     const label = moving.map((name) => `${name}@${manifest.candidates?.[name]}`).join(", ");
     const script = checkout.pkg.scripts?.["train:adopt"];
     try {
-      effect(
-        `open ${branch} in ${checkout.name}: re-lock onto ${label}${script ? ", run train:adopt" : ""}, commit`,
-        void 0,
+      const outcome = effect(
+        `open ${branch} in ${checkout.name}: ${adoptionPlan(script, output)}`,
+        { reason: null, saved: false },
         () => {
           const branchCheckout = worktree(checkout, branch);
+          let reason = null;
+          let saved = false;
           try {
-            bumpRanges(branchCheckout);
+            const { inspection } = bumpRanges(branchCheckout);
             relockAndCheck(branchCheckout, false);
-            if (script && spawnSync3("bun", ["run", "train:adopt"], {
-              cwd: branchCheckout.dir,
-              stdio: "inherit"
-            }).status !== 0) {
-              console.log(
-                `\u26A0 train:adopt failed in ${checkout.name} \u2014 the branch needs work before it merges`
-              );
+            const owned = [...inspection.packagePaths, "bun.lock"].filter(
+              (path) => existsSync3(join3(branchCheckout.dir, path))
+            );
+            if (git(branchCheckout.dir, "add", "--", ...owned).status !== 0) {
+              throw new Abort(`git add failed on ${branch} in ${checkout.name}`);
+            }
+            let produced = null;
+            if (script) {
+              const adopted = spawnSync3("bun", ["run", "train:adopt"], {
+                cwd: branchCheckout.dir,
+                stdio: "inherit"
+              }).status === 0;
+              produced = captureOutput(branchCheckout.dir);
+              const leftOut = `its output is left out; ${branch} carries the re-lock only and needs work before it merges`;
+              if (!adopted) {
+                reason = "train:adopt failed";
+                console.log(`\u26A0 train:adopt failed in ${checkout.name} \u2014 ${leftOut}`);
+              } else {
+                const check = spawnSync3("bun", ["run", "check"], {
+                  cwd: branchCheckout.dir,
+                  stdio: "inherit",
+                  timeout: adoptCheckTimeout * 1e3,
+                  killSignal: "SIGKILL"
+                });
+                if (check.status !== 0) {
+                  reason = "check failed after train:adopt";
+                  console.log(
+                    check.error || check.signal ? `\u26A0 check timed out after ${adoptCheckTimeout}s in ${checkout.name} after train:adopt \u2014 ${leftOut}` : `\u26A0 check still fails in ${checkout.name} after train:adopt \u2014 ${leftOut}`
+                  );
+                }
+              }
+              if (!reason && produced) git(branchCheckout.dir, "read-tree", produced);
             }
-            git(branchCheckout.dir, "add", "-A");
-            const commit = spawnSync3("git", ["commit", "-m", `chore: adopt ${label}`], {
+            const message = reason ? [
+              "-m",
+              `chore: adopt ${label} (incomplete)`,
+              "-m",
+              `Train-Adopt: incomplete (${reason})`
+            ] : ["-m", `chore: adopt ${label}`];
+            const commit = spawnSync3("git", ["commit", ...message], {
               cwd: branchCheckout.dir,
               stdio: "inherit"
             });
@@ -1747,15 +1852,44 @@ if (command === "train") {
                 `commit failed on ${branch} in ${checkout.name} (its hooks reject the adoption)`
               );
             }
+            if (reason && produced) {
+              const saving = spawnSync3(
+                "git",
+                [
+                  "commit-tree",
+                  produced,
+                  "-p",
+                  "HEAD",
+                  "-m",
+                  `train:adopt output for ${branch} (${reason}), not adopted`
+                ],
+                { cwd: branchCheckout.dir, encoding: "utf8" }
+              );
+              saved = saving.status === 0 && git(branchCheckout.dir, "branch", "-f", output, saving.stdout.trim()).status === 0;
+              console.log(
+                saved ? `  its output is saved on ${output} (git -C ${checkout.dir} diff ${branch} ${output})` : `\u2717 could not save train:adopt's output on ${output} in ${checkout.name}`
+              );
+            }
+            git(branchCheckout.dir, "reset", "--quiet", "--hard", "HEAD");
+            git(branchCheckout.dir, "clean", "--quiet", "-fd");
           } catch (error) {
             dropBranch(checkout, branch);
+            git(checkout.dir, "branch", "-D", output);
             throw error;
           }
           followers.push({ checkout: branchCheckout, onBranch: true });
+          return { reason, saved };
         }
       );
-      adoptionBranches.push({ dir: checkout.dir, branch });
-      waiting.push({ name: checkout.name, dir: checkout.dir, moving, state: "opened", branch });
+      adoptionBranches.push({ dir: checkout.dir, branch, ...outcome.saved ? { output } : {} });
+      waiting.push({
+        name: checkout.name,
+        dir: checkout.dir,
+        moving,
+        state: outcome.reason ? "incomplete" : "opened",
+        branch,
+        ...outcome.reason ? { reason: outcome.reason } : {}
+      });
     } catch (error) {
       if (!(error instanceof Abort)) throw error;
       failed.push(checkout.name);
@@ -1856,6 +1990,7 @@ if (command === "train") {
         if (pendingAdoption(checkout, moving)) continue;
         const { inspection, bumped, staleLock } = bumpRanges(checkout);
         const relocked = bumped || staleLock || releases.some((release) => release.ahead);
+        if (relocked) previewAdoption(checkout, moving);
         try {
           if (relocked) relockAndCheck(checkout);
           if (commitOwned(checkout, inspection.packagePaths, relocked)) committed.add(checkout.dir);
@@ -1934,6 +2069,7 @@ if (command === "train") {
       console.log("\u2713 already on the blessed set");
       continue;
     }
+    previewAdoption(checkout, moving);
     try {
       relockAndCheck(checkout);
       const message = moving.length > 0 ? `chore: adopt ${moving.map((name) => `${name}@${manifest.candidates?.[name]}`).join(", ")}` : void 0;
@@ -1996,6 +2132,7 @@ if (command === "train") {
   }
   const why = {
     opened: "opened this run",
+    incomplete: "incomplete",
     unmerged: "waiting for its branch to merge",
     unpushed: "committed but never pushed",
     failed: "the train could not commit it \u2014 adopt by hand",
@@ -2007,7 +2144,9 @@ blessed: ${promoted.length === 0 ? "nothing" : promoted.join(", ")}`);
   if (candidates.length > 0) {
     console.log("candidates (check accepts them; not yet blessed):");
     for (const [name, version] of candidates) {
-      const on = waiting.filter((entry) => entry.moving.includes(name)).map((entry) => `${entry.name} (${entry.branch ?? why[entry.state]})`);
+      const on = waiting.filter((entry) => entry.moving.includes(name)).map(
+        (entry) => `${entry.name} (${entry.branch ?? why[entry.state]}${entry.state === "incomplete" ? ", incomplete" : ""})`
+      );
       console.log(`  ${name}@${version}${on.length === 0 ? "" : ` \u2014 waiting on ${on.join(", ")}`}`);
     }
   }
@@ -2016,7 +2155,7 @@ blessed: ${promoted.length === 0 ? "nothing" : promoted.join(", ")}`);
     console.log("pending (merge each adoption branch, then run the train again to bless):");
     for (const entry of waiting) {
       console.log(
-        `  ${entry.name}: ${entry.branch ? `${entry.branch} \u2014 ` : ""}${why[entry.state]}`
+        `  ${entry.name}: ${entry.branch ? `${entry.branch} \u2014 ` : ""}${entry.state === "incomplete" ? `incomplete (${entry.reason}) \u2014 finish it on the branch` : why[entry.state]}`
       );
     }
   }
@@ -2104,7 +2243,11 @@ blessed: ${promoted.length === 0 ? "nothing" : promoted.join(", ")}`);
     }
   }
   const moved = [.../* @__PURE__ */ new Set([...committed, ...adoptionBranches.map((entry) => entry.dir)])];
-  const keep = new Set(adoptionBranches.map((entry) => `${entry.dir}\0${entry.branch}`));
+  const keep = new Set(
+    adoptionBranches.flatMap(
+      (entry) => [entry.branch, entry.output].flatMap((branch) => branch ? [`${entry.dir}\0${branch}`] : [])
+    )
+  );
   const superseded = (repoDir) => {
     const refs = (prefix) => git(repoDir, "for-each-ref", "--format=%(refname:short)", prefix).stdout.split("\n").map((ref) => ref.trim().replace(/^origin\//, "")).filter((branch) => branch.startsWith("train/") && !keep.has(`${repoDir}\0${branch}`));
     return { local: refs("refs/heads/train/"), remote: refs("refs/remotes/origin/train/") };
@@ -2124,12 +2267,14 @@ dry run complete \u2014 a real train would commit in ${committed.size} repo(s) a
         process.exit(1);
       }
     }
-    for (const { dir: repoDir, branch } of adoptionBranches) {
-      const push = spawnSync3("git", ["push", "-u", "origin", branch], {
-        cwd: repoDir,
-        stdio: "inherit"
-      });
-      if (push.status !== 0) console.error(`\u2717 could not push ${branch} in ${repoDir}`);
+    for (const { dir: repoDir, branch, output } of adoptionBranches) {
+      for (const ref of output ? [branch, output] : [branch]) {
+        const push = spawnSync3("git", ["push", "-u", "origin", ref], {
+          cwd: repoDir,
+          stdio: "inherit"
+        });
+        if (push.status !== 0) console.error(`\u2717 could not push ${ref} in ${repoDir}`);
+      }
     }
     for (const repoDir of moved) {
       git(repoDir, "fetch", "--quiet", "--prune", "origin");
@@ -2150,8 +2295,9 @@ dry run complete \u2014 a real train would commit in ${committed.size} repo(s) a
   } else if (committed.size > 0 || adoptionBranches.length > 0) {
     console.log("train does not push without --push \u2014 review its commits, then push:");
     for (const repoDir of committed) console.log(`  git -C ${repoDir} push`);
-    for (const { dir: repoDir, branch } of adoptionBranches) {
+    for (const { dir: repoDir, branch, output } of adoptionBranches) {
       console.log(`  git -C ${repoDir} push -u origin ${branch}`);
+      if (output) console.log(`  git -C ${repoDir} push -u origin ${output}`);
     }
     for (const repoDir of moved) {
       const { local, remote } = superseded(repoDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/config",
-  "version": "0.5.201",
+  "version": "0.5.202",
   "description": "Shared toolchain and theme for the inixiative packages: tsconfig/biome/tsup presets, theme CSS, a version manifest (BOM), and a sync/check/train CLI",
   "type": "module",
   "license": "MIT",

package/versions.json

@@ -13,7 +13,7 @@
     "@types/bun"
   ],
   "ecosystem": {
-    "@inixiative/config": "0.5.201",
+    "@inixiative/config": "0.5.202",
     "@inixiative/json-rules": "3.16.0",
     "@inixiative/permissions": "0.21.1",
     "@inixiative/transitions": "0.7.2",
@@ -52,6 +52,7 @@
   },
   "candidates": {
     "@inixiative/atlas": "0.5.0",
-    "@inixiative/json-rules": "3.21.0"
+    "@inixiative/json-rules": "3.21.0",
+    "@inixiative/signet": "0.13.0"
   }
 }