@plexus-ms/cli 0.101.0 → 0.102.0

package/dist/plx.js

@@ -7761,7 +7761,7 @@ function realIo(prompt) {
     stdout: process.stdout,
     stderr: process.stderr,
     prompt: prompt && isInteractive() ? prompt : void 0,
-    exec: (command, args, options = {}) => new Promise((resolve10, reject) => {
+    exec: (command, args, options = {}) => new Promise((resolve11, reject) => {
       const child = spawn(command, args, {
         cwd: options.cwd,
         env: options.env,
@@ -7784,7 +7784,7 @@ function realIo(prompt) {
       child.on("error", reject);
       child.on("close", (code) => {
         if (code === 0)
-          resolve10(stdout);
+          resolve11(stdout);
         else
           reject(new ExecError(render(command, args), code, stderr));
       });
@@ -8683,22 +8683,22 @@ async function templateFacet(ctx, cwd) {
 // ../lib/dist/propagate.js
 import { join as join8, relative as relative3 } from "node:path";
 var isClean = (s) => s.conflicted.length === 0 && s.failed.length === 0 && s.skipped.length === 0;
-var BASE_TAG = "ship-base";
-var trainBranch = (train) => `train/${train}`;
-var copierIn = (clone, args) => [
+var emptySummary = (train, preview) => ({
+  train,
+  preview,
+  clean: [],
+  conflicted: [],
+  failed: [],
+  skipped: [],
+  pulls: []
+});
+var trainBranch = (train) => `plexus/${train}`;
+var copierIn = (dir, args) => [
   "env",
-  [`MISE_IGNORED_CONFIG_PATHS=${clone}`, "mise", ...copierVia(args)]
+  [`MISE_IGNORED_CONFIG_PATHS=${dir}`, "mise", ...copierVia(args)]
 ];
 async function propagate(ctx, workspace, train) {
-  const summary = {
-    train,
-    preview: ctx.dryRun,
-    clean: [],
-    conflicted: [],
-    failed: [],
-    skipped: [],
-    pulls: []
-  };
+  const summary = emptySummary(train, ctx.dryRun);
   const upstream = join8(workspace, UPSTREAM);
   const tree = await overview(ctx, workspace);
   const upstreamDir = tree.children.find((c) => c.path === upstream);
@@ -8713,6 +8713,7 @@ async function propagate(ctx, workspace, train) {
   for (const preset of presets)
     if (!consumers.some((c) => c.sites.some((s) => s.preset === preset)))
       ctx.say(`\u2022 no consumers of ${presetSource(preset)} found under ${workspace}`);
+  const take = { train, opener: "`plx ship`", ...ctx.dryRun ? { previewFrom: upstream } : {} };
   const scratch = (await ctx.stage(run("mktemp", ["-d"])))?.trim() ?? "";
   try {
     for (const consumer of consumers) {
@@ -8722,17 +8723,12 @@ async function propagate(ctx, workspace, train) {
       ctx.say(`\u2192 ${consumer.rel}: clone ${consumer.origin} at ${consumer.branch}`);
       try {
         await ctx.stage(run("git", ["clone", "--quiet", "--branch", consumer.branch, consumer.origin, clone]));
-        await ctx.stage(run("git", ["tag", BASE_TAG], { cwd: clone }));
       } catch (error) {
         ctx.say(`  \u2717 FAILED \u2014 clone${detail(error)}`);
         summary.failed.push(consumer.rel);
         continue;
       }
-      for (const site of consumer.sites)
-        await updateSite(ctx, consumer, site, clone, upstream, summary);
-      await refreshLockfile(ctx, consumer, clone, summary);
-      await bumpConsumerRefs(ctx, consumer, clone, train);
-      await openPull(ctx, consumer, clone, train, summary);
+      await takeTrain(ctx, consumer, clone, take, summary);
     }
   } finally {
     if (scratch)
@@ -8740,7 +8736,15 @@ async function propagate(ctx, workspace, train) {
   }
   return summary;
 }
-var previewCommit = (ctx, clone, message) => ctx.stage(run("git", ["add", "-A"], { cwd: clone })).then(() => ctx.stage(run("git", [
+async function takeTrain(ctx, consumer, dir, take, summary) {
+  const base = (await ctx.read("git", ["rev-parse", "HEAD"], { cwd: dir })).trim();
+  for (const site of consumer.sites)
+    await updateSite(ctx, consumer, site, dir, take, summary);
+  await refreshLockfile(ctx, consumer, dir, base, summary);
+  await bumpConsumerRefs(ctx, consumer, dir, take.train);
+  await openPull(ctx, consumer, dir, take, summary);
+}
+var previewCommit = (ctx, dir, message) => ctx.stage(run("git", ["add", "-A"], { cwd: dir })).then(() => ctx.stage(run("git", [
   "-c",
   "commit.gpgsign=false",
   "-c",
@@ -8753,31 +8757,32 @@ var previewCommit = (ctx, clone, message) => ctx.stage(run("git", ["add", "-A"],
   "--allow-empty",
   "-m",
   message
-], { cwd: clone })));
-async function updateSite(ctx, consumer, site, clone, upstream, summary) {
-  const target = join8(clone, relative3(consumer.path, site.path));
-  const localPreset = join8(upstream, site.preset);
+], { cwd: dir })));
+async function updateSite(ctx, consumer, site, dir, take, summary) {
+  const target = join8(dir, relative3(consumer.path, site.path));
   try {
-    if (ctx.dryRun) {
+    if (take.previewFrom) {
+      const localPreset = join8(take.previewFrom, site.preset);
       ctx.say(`\u2192 ${site.rel}: copier update (preview from ${localPreset}@main)`);
       const answers = await ctx.readFile(join8(target, ANSWERS_FILE));
       await ctx.stage(write(join8(target, ANSWERS_FILE), answers.replace(/^_src_path: .*$/m, `_src_path: ${localPreset}`)));
-      await previewCommit(ctx, clone, `plx preview: ${site.rel} reads ${localPreset} from the local checkout`);
-      await ctx.stage(run(...copierIn(clone, [
+      await previewCommit(ctx, dir, `plx preview: ${site.rel} reads ${localPreset} from the local checkout`);
+      await ctx.stage(run(...copierIn(dir, ["update", "--skip-answered", "--trust", "--defaults", "--skip-tasks", "--vcs-ref", "main"]), { cwd: target }));
+    } else {
+      ctx.say(`\u2192 ${site.rel}: copier update${take.ref ? ` to ${take.ref}` : ""}`);
+      const args = [
         "update",
         "--skip-answered",
         "--trust",
-        "--defaults",
         "--skip-tasks",
-        "--vcs-ref",
-        "main"
-      ]), {
-        cwd: target
-      }));
-    } else {
-      ctx.say(`\u2192 ${site.rel}: copier update`);
-      const args = ["update", "--skip-answered", "--trust", "--skip-tasks", ...ctx.yes ? ["--defaults"] : []];
-      await ctx.apply([run(...copierIn(clone, args), { cwd: target, interactive: true })]);
+        ...take.ref ? ["--vcs-ref", take.ref] : [],
+        ...ctx.yes || ctx.dryRun ? ["--defaults"] : []
+      ];
+      const step = run(...copierIn(dir, args), { cwd: target, interactive: !ctx.dryRun });
+      if (ctx.dryRun)
+        await ctx.stage(step);
+      else
+        await ctx.apply([step]);
     }
   } catch (error) {
     ctx.say(`  \u2717 FAILED \u2014 copier update exited nonzero${detail(error)}`);
@@ -8802,10 +8807,10 @@ async function updateSite(ctx, consumer, site, clone, upstream, summary) {
   }
   for (const line of status.split("\n").filter(Boolean))
     ctx.say(`    ${line}`);
-  if (ctx.dryRun)
-    await previewCommit(ctx, clone, `plx preview: ${site.rel} updated`);
+  if (take.previewFrom)
+    await previewCommit(ctx, dir, `plx preview: ${site.rel} updated`);
   else
-    await ctx.stage(run("git", ["add", "-A"], { cwd: clone }));
+    await ctx.stage(run("git", ["add", "-A"], { cwd: dir }));
 }
 async function syncSiteMarker(ctx, site, target) {
   const marker = await ctx.readFile(join8(target, MARKER_FILE)).catch(() => void 0);
@@ -8820,77 +8825,71 @@ async function syncSiteMarker(ctx, site, target) {
   ctx.say(`  marker: plexus \u2192 ${commit} in ${site.rel}/${MARKER_FILE}`);
   await ctx.stage(write(join8(target, MARKER_FILE), synced));
 }
-async function refreshLockfile(ctx, consumer, clone, summary) {
-  if (await ctx.readFile(join8(clone, "pnpm-workspace.yaml")).catch(() => void 0) === void 0)
+async function refreshLockfile(ctx, consumer, dir, base, summary) {
+  if (await ctx.readFile(join8(dir, "pnpm-workspace.yaml")).catch(() => void 0) === void 0)
     return;
   const manifests = ["*package.json", "pnpm-workspace.yaml"];
-  const unchanged = await ctx.read("git", ["diff", "--quiet", BASE_TAG, "--", ...manifests], { cwd: clone }).then(() => true).catch(() => false);
+  const unchanged = await ctx.read("git", ["diff", "--quiet", base, "--", ...manifests], { cwd: dir }).then(() => true).catch(() => false);
   if (unchanged)
     return;
   ctx.say(`\u2192 ${consumer.rel}: pnpm install (manifests changed)`);
   try {
-    await ctx.apply([run("mise", ["exec", "--", "pnpm", "install", "--reporter=silent"], { cwd: clone })]);
+    await ctx.apply([run("mise", ["exec", "--", "pnpm", "install", "--reporter=silent"], { cwd: dir })]);
   } catch (error) {
     ctx.say(`  \u2717 pnpm install failed${detail(error)}`);
     summary.failed.push(`${consumer.rel}/pnpm-lock.yaml`);
   }
 }
-async function bumpConsumerRefs(ctx, consumer, clone, train) {
-  const dir = join8(clone, ".github", "workflows");
-  const entries = await ctx.readDir(dir).catch(() => []);
+async function bumpConsumerRefs(ctx, consumer, dir, train) {
+  const workflows = join8(dir, ".github", "workflows");
+  const entries = await ctx.readDir(workflows).catch(() => []);
   const files = entries.filter((e) => !e.directory && /\.ya?ml$/.test(e.name)).map((e) => e.name).sort();
   for (const f of files) {
-    const text = await ctx.readFile(join8(dir, f));
+    const text = await ctx.readFile(join8(workflows, f));
     if (!text.includes(WORKFLOW_REF))
       continue;
     const bumped = bumpWorkflowRefs(text, train);
     if (bumped === text)
       continue;
     ctx.say(`\u2192 ${consumer.rel}: ${f} workflow refs \u2192 @${train}`);
-    await ctx.stage(write(join8(dir, f), bumped));
+    await ctx.stage(write(join8(workflows, f), bumped));
   }
 }
-async function openPull(ctx, consumer, clone, train, summary) {
+async function openPullUrl(ctx, consumer, dir, train) {
+  const args = ["pr", "list", "--head", trainBranch(train), "--base", consumer.branch, "--state", "open"];
+  return (await ctx.read("gh", [...args, "--json", "url", "--jq", ".[0].url"], { cwd: dir }).catch(() => "")).trim();
+}
+async function openPull(ctx, consumer, dir, take, summary) {
+  const { train } = take;
   const branch = trainBranch(train);
   if (ctx.dryRun) {
     ctx.say(`  (preview) ${consumer.rel}: would commit, push ${branch} and open a pull request against ${consumer.branch}`);
     return;
   }
-  if ((await ctx.read("git", ["status", "--porcelain"], { cwd: clone })).trim() === "") {
+  if ((await ctx.read("git", ["status", "--porcelain"], { cwd: dir })).trim() === "") {
     ctx.say(`\u2022 ${consumer.rel}: nothing changed \u2014 no pull request`);
     return;
   }
-  const head = `${consumer.origin} ${branch}`;
+  const head = `${consumer.origin ?? "origin"} ${branch}`;
   try {
     await ctx.apply([
-      run("git", ["add", "-A"], { cwd: clone }),
-      run("git", ["commit", "--quiet", "--no-verify", "-m", `chore: train ${train}`], { cwd: clone })
+      run("git", ["add", "-A"], { cwd: dir }),
+      run("git", ["commit", "--quiet", "--no-verify", "-m", `chore: train ${train}`], { cwd: dir })
     ]);
     await ctx.read("git", ["fetch", "--quiet", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`], {
-      cwd: clone
+      cwd: dir
     }).catch(() => "");
     await ctx.apply([
-      run("git", ["push", "--quiet", "--force-with-lease", "origin", `HEAD:refs/heads/${branch}`], { cwd: clone })
+      run("git", ["push", "--quiet", "--no-verify", "--force-with-lease", "origin", `HEAD:refs/heads/${branch}`], {
+        cwd: dir
+      })
     ]);
   } catch (error) {
     ctx.say(`  \u2717 FAILED \u2014 push to ${head}${detail(error)}`);
     summary.failed.push(consumer.rel);
     return;
   }
-  const existing = (await ctx.read("gh", [
-    "pr",
-    "list",
-    "--head",
-    branch,
-    "--base",
-    consumer.branch,
-    "--state",
-    "open",
-    "--json",
-    "url",
-    "--jq",
-    ".[0].url"
-  ], { cwd: clone }).catch(() => "")).trim();
+  const existing = await openPullUrl(ctx, consumer, dir, train);
   if (existing) {
     ctx.say(`\u2022 ${consumer.rel}: pull request updated: ${existing}`);
     summary.pulls.push(existing);
@@ -8901,7 +8900,7 @@ async function openPull(ctx, consumer, clone, train, summary) {
   const body2 = [
     `Train ${train} (\xA7 1.5 PLX): \`copier update\` at ${sites.join(", ")}, the marker, the lockfile where manifests moved, and the workflow refs.`,
     conflicted.length > 0 ? `Conflicts to resolve, committed with their markers: ${conflicted.join(", ")}.` : "Merged clean at every site.",
-    "Opened by `plx ship`."
+    `Opened by ${take.opener}.`
   ].join("\n\n");
   try {
     await ctx.apply([
@@ -8916,29 +8915,14 @@ async function openPull(ctx, consumer, clone, train, summary) {
         `chore: train ${train}`,
         "--body",
         body2
-      ], { cwd: clone })
+      ], { cwd: dir })
     ]);
   } catch (error) {
     ctx.say(`  \u2717 FAILED \u2014 pull request${detail(error)}`);
     summary.failed.push(consumer.rel);
     return;
   }
-  const url = (await ctx.read("gh", [
-    "pr",
-    "list",
-    "--head",
-    branch,
-    "--base",
-    consumer.branch,
-    "--state",
-    "open",
-    "--json",
-    "url",
-    "--jq",
-    ".[0].url"
-  ], {
-    cwd: clone
-  }).catch(() => "")).trim();
+  const url = await openPullUrl(ctx, consumer, dir, train);
   ctx.say(`\u2022 ${consumer.rel}: pull request opened${url ? `: ${url}` : ""}`);
   summary.pulls.push(url || `${consumer.rel} ${branch}`);
 }
@@ -9218,7 +9202,7 @@ async function awaitPublished(ctx, next, wait) {
       break;
     if (Date.now() - started >= wait.timeout)
       throw new Error(`${missing.join(", ")} not on npm at ${next} after ${Math.round(wait.timeout / 6e4)} min \u2014 check the release workflow (gh run list -R plexus-ms/${PRIMITIVES})`);
-    await new Promise((resolve10) => setTimeout(resolve10, wait.interval));
+    await new Promise((resolve11) => setTimeout(resolve11, wait.interval));
   }
   ctx.say(`  \u2713 ${list2} on npm`);
 }
@@ -9280,6 +9264,76 @@ async function planBookkeeping(ctx, train, repos2, next, today2) {
   return plan;
 }
 
+// ../lib/dist/update.js
+import { basename, join as join11 } from "node:path";
+var PRESETS = TRAIN_REPOS.filter((r) => r.startsWith("preset-"));
+async function update(ctx, options) {
+  const { repo } = options;
+  const name = basename(repo);
+  if (options.train !== void 0 && !isTrainVersion(options.train))
+    throw new UsageError(`'${options.train}' is not plain semver (X.Y.Z, no v)`);
+  const tree = await overview(ctx, repo);
+  const consumer = (await findConsumers(ctx, tree, PRESETS)).find((c) => c.path === tree.path);
+  if (!consumer)
+    throw new Error(`${repo} is not a repo generated from the presets: no ${ANSWERS_FILE} at its root naming one of ${PRESETS.map(presetSource).join(", ")}`);
+  if (consumer.skipped)
+    throw new Error(`${name}: ${consumer.skipped}`);
+  consumer.rel = name;
+  for (const s of consumer.sites)
+    s.rel = s.rel === "." ? name : join11(name, s.rel);
+  const root = consumer.sites.find((s) => s.path === consumer.path);
+  if (!root)
+    throw new Error(`${name}: its root is not a site of a repo preset`);
+  await preflightForge(ctx);
+  const train = options.train ?? await newestTrain(ctx, root.preset);
+  const summary = emptySummary(train, ctx.dryRun);
+  const recorded = await Promise.all(consumer.sites.map(async (s) => parseAnswers(await ctx.readFile(join11(s.path, ANSWERS_FILE))).commit));
+  if (recorded.every((c) => c === train)) {
+    ctx.say(`\u2022 ${name}: already at ${train}`);
+    return summary;
+  }
+  const past = recorded.find((c) => c && isTrainVersion(c) && compareTrains(c, train) > 0);
+  if (past)
+    throw new Error(`${name} is at ${past}, past ${train}; a repo is never taken back to an older train`);
+  const branch = trainBranch(train);
+  const onOrigin = await ctx.read("git", ["ls-remote", "--exit-code", "--heads", "origin", `refs/heads/${branch}`], { cwd: repo }).then(() => true).catch(() => false);
+  if (onOrigin) {
+    const url = await openPullUrl(ctx, consumer, repo, train);
+    ctx.say(`\u2022 ${name}: ${branch} is already on origin${url ? ` (${url})` : ""} \u2014 nothing to do; delete the branch to pull the train again`);
+    if (url)
+      summary.pulls.push(url);
+    return summary;
+  }
+  const scratch = (await ctx.stage(run("mktemp", ["-d"])))?.trim() ?? "";
+  const dir = join11(scratch, name);
+  try {
+    ctx.say(`\u2192 ${name}: worktree of origin/${consumer.branch}`);
+    try {
+      await ctx.stage(run("git", ["fetch", "--quiet", "origin", consumer.branch], { cwd: repo }));
+      await ctx.stage(run("git", ["worktree", "add", "--quiet", "--detach", dir, `origin/${consumer.branch}`], { cwd: repo }));
+    } catch (error) {
+      ctx.say(`  \u2717 FAILED \u2014 worktree of origin/${consumer.branch}${detail(error)}`);
+      summary.failed.push(name);
+      return summary;
+    }
+    await takeTrain(ctx, consumer, dir, { train, ref: train, opener: "`plx update`" }, summary);
+  } finally {
+    await ctx.stage(run("git", ["worktree", "remove", "--force", dir], { cwd: repo })).catch(() => void 0);
+    if (scratch)
+      await ctx.stage(run("rm", ["-rf", scratch]));
+  }
+  return summary;
+}
+async function newestTrain(ctx, preset) {
+  const source = presetSource(preset).replace(/^gh:/, "");
+  const tag = (await ctx.read("gh", ["api", `repos/${source}/releases/latest`, "--jq", ".tag_name"]).catch(() => "")).trim();
+  if (!tag)
+    throw new Error(`no release of ${source} found \u2014 pass the train explicitly (--train <version>)`);
+  if (!isTrainVersion(tag))
+    throw new Error(`the newest release of ${source} is '${tag}', not a train`);
+  return tag;
+}
+
 // src/program.ts
 import { createRequire } from "node:module";
 
@@ -10226,13 +10280,13 @@ import { AsyncResource as AsyncResource3 } from "node:async_hooks";
 
 // ../../node_modules/.pnpm/@inquirer+type@4.2.1_@types+node@26.6.5/node_modules/@inquirer/type/dist/utils.js
 function withResolver() {
-  let resolve10;
+  let resolve11;
   let reject;
   const promise = new Promise((res, rej) => {
-    resolve10 = res;
+    resolve11 = res;
     reject = rej;
   });
-  return { promise, resolve: resolve10, reject };
+  return { promise, resolve: resolve11, reject };
 }
 
 // ../../node_modules/.pnpm/@inquirer+core@12.0.6_@types+node@26.6.5/node_modules/@inquirer/core/dist/lib/create-prompt.js
@@ -10611,7 +10665,7 @@ function createPrompt(view) {
     });
     output.mute();
     const screen = new ScreenManager(rl);
-    const { promise, resolve: resolve10, reject } = withResolver();
+    const { promise, resolve: resolve11, reject } = withResolver();
     return withHooks(rl, (cycle) => {
       const clearEffects = AsyncResource3.bind(() => effectScheduler.clearAll());
       const settlePrompt = (settle) => {
@@ -10622,7 +10676,7 @@ function createPrompt(view) {
           reject(error);
         }
       };
-      const resolvePrompt = (value) => settlePrompt(() => resolve10(value));
+      const resolvePrompt = (value) => settlePrompt(() => resolve11(value));
       const rejectPrompt = (error) => settlePrompt(() => reject(error));
       const promptPromise = Object.assign(promise.finally(() => {
         cleanups.forEach((cleanup) => cleanup());
@@ -14211,7 +14265,7 @@ function register4(program2) {
 
 // src/commands/doctor.ts
 import { existsSync } from "node:fs";
-import { join as join11, resolve as resolve5 } from "node:path";
+import { join as join12, resolve as resolve5 } from "node:path";
 
 // src/style.ts
 function style(enabled) {
@@ -14229,8 +14283,8 @@ function register5(program2) {
   ).option("--color", "colour the report even when piped").option("--no-color", "never colour the report").action(async (dir, opts, command) => {
     const ctx = contextOf2(command);
     const root = resolve5(dir);
-    const compendium = resolve5(opts.compendium ?? join11(root, WORKSPACE_COMPENDIUM));
-    if (!existsSync(join11(compendium, "contracts")))
+    const compendium = resolve5(opts.compendium ?? join12(root, WORKSPACE_COMPENDIUM));
+    if (!existsSync(join12(compendium, "contracts")))
       throw new Error(
         `no compendium at ${compendium}; pass --compendium <path to a checkout of plexus-ms/compendium>`
       );
@@ -14320,7 +14374,7 @@ function register7(program2) {
     if (!isClean(result)) process.exitCode = 1;
   });
 }
-function renderSummary(s, realCommand) {
+function renderSummary(s, realCommand, verb = "propagate") {
   const lines = ["\u2500\u2500 summary \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"];
   for (const p of s.clean) lines.push(`  \u2713 clean:      ${p}`);
   for (const p of s.conflicted) lines.push(`  \u2717 conflicts:  ${p}`);
@@ -14334,7 +14388,7 @@ function renderSummary(s, realCommand) {
   } else if (clean) {
     lines.push("\u2713 done \u2014 review and merge the pull requests");
   }
-  if (!clean) lines.push("\u2717 needs attention \u2014 see above; fix the consumer, then re-run propagate");
+  if (!clean) lines.push(`\u2717 needs attention \u2014 see above; fix the consumer, then re-run ${verb}`);
   return lines.join("\n");
 }
 
@@ -14349,13 +14403,13 @@ function register8(program2) {
 }
 
 // src/commands/requirements.ts
-import { join as join12, resolve as resolve9 } from "node:path";
+import { join as join13, resolve as resolve9 } from "node:path";
 function register9(program2) {
   program2.command("requirements").description("lint the standard's map and module pages, or extract one module's requirement lines").argument("[dir]", "a checkout of the compendium", ".").option("--extract <page>", "print a module page's requirement lines instead of linting (path relative to dir)").action(async (dir, opts, command) => {
     const ctx = contextOf2(command);
     const compendium = resolve9(dir);
     if (opts.extract) {
-      ctx.result(extractRequirements(await ctx.readFile(join12(compendium, opts.extract))));
+      ctx.result(extractRequirements(await ctx.readFile(join13(compendium, opts.extract))));
       return;
     }
     const check = await checkCompendium(ctx, compendium);
@@ -14368,12 +14422,26 @@ function renderCheck(c) {
   return `\u2713 the map, ${c.contracts} contracts and ${c.approaches} approaches are well-formed`;
 }
 
+// src/commands/update.ts
+import { resolve as resolve10 } from "node:path";
+function register10(program2) {
+  program2.command("update").description(
+    "bring this repo up to a train, as a pull request on plexus/<version>: copier update at every site, the marker, the lockfile, the workflow refs"
+  ).argument("[dir]", "a repo generated from the presets", ".").option("--train <version>", "the train to take (default: the preset's newest release)").action(async (dir, opts, command) => {
+    const ctx = contextOf2(command);
+    const result = await update(ctx, { repo: resolve10(dir), train: opts.train });
+    ctx.result(result, (r) => renderSummary(r, `plx -y update --train ${r.train} ${dir}`, "update"));
+    if (!isClean(result)) process.exitCode = 1;
+  });
+}
+
 // src/commands/index.ts
 var commands = [
   register6,
   register5,
   register7,
   register8,
+  register10,
   register9,
   register2,
   register,
@@ -14388,7 +14456,7 @@ function buildProgram() {
   program2.addOption(new Option("-n, --dry-run", "print every effect this run would have, perform none").env("PLX_DRY_RUN")).addOption(
     new Option("-v, --verbose", "say more: once for reads and inputs, twice for command output").argParser((_value, previous) => previous + 1).default(0)
   ).addOption(new Option("-q, --quiet", "say nothing but results and errors").env("PLX_QUIET")).addOption(new Option("-y, --yes", "answer every confirmation with yes (needed off a terminal)").env("PLX_YES")).addOption(new Option("--json", "print results as JSON").env("PLX_JSON"));
-  for (const register10 of commands) register10(program2);
+  for (const register11 of commands) register11(program2);
   return program2;
 }
 function contextOf2(command) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plexus-ms/cli",
-  "version": "0.101.0",
+  "version": "0.102.0",
   "description": "plx, the Plexus command-line tool: a single-script adapter over @plexus-ms/lib",
   "license": "GPL-3.0-or-later",
   "type": "module",
@@ -23,8 +23,8 @@
     "node": ">=24.22.1"
   },
   "dependencies": {
-    "@inquirer/prompts": "^8.7.4",
-    "@plexus-ms/lib": "0.101.0",
+    "@inquirer/prompts": "^8.7.5",
+    "@plexus-ms/lib": "0.102.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {