@plexus-ms/cli 0.3.0 → 0.5.0

package/dist/plx.js

@@ -7268,7 +7268,7 @@ var require_public_api = __commonJS({
       }
       return doc;
     }
-    function parse3(src, reviver, options) {
+    function parse5(src, reviver, options) {
       let _reviver = void 0;
       if (typeof reviver === "function") {
         _reviver = reviver;
@@ -7309,7 +7309,7 @@ var require_public_api = __commonJS({
         return value.toString(options);
       return new Document.Document(value, _replacer, options).toString(options);
     }
-    exports.parse = parse3;
+    exports.parse = parse5;
     exports.parseAllDocuments = parseAllDocuments;
     exports.parseDocument = parseDocument;
     exports.stringify = stringify;
@@ -7655,63 +7655,84 @@ async function readCatalog(ctx, compendium) {
   return catalog;
 }
 
-// ../lib/dist/consumers.js
-import { relative } from "node:path";
-function expectedBranch(declaration) {
-  if (!declaration)
-    return void 0;
-  if (declaration.modules.includes("PLX-Platform"))
-    return "main";
-  if (declaration.modules.includes("PLX-Repo"))
-    return "develop";
-  return void 0;
+// ../lib/dist/changedApps.js
+import { join as join2 } from "node:path";
+var BOOKKEEPING = /(^|\/)(PLEXUS\.md|\.copier-answers\.yml)$/;
+var GLOBALS = /^(pnpm-lock\.yaml|pnpm-workspace\.yaml|package\.json|turbo\.json|mise\.toml|\.npmrc|\.node-version)$/;
+var NO_REF = /^0*$/;
+async function selectChangedApps(input) {
+  const all = [...input.all].sort();
+  if (input.changed === void 0)
+    return { apps: all, reason: "no base ref: every app counts as changed" };
+  const changed = input.changed.filter((f) => !BOOKKEEPING.test(f));
+  const under = (app) => changed.some((f) => f.startsWith(`apps/${app}/`));
+  if (!input.workspace)
+    return { apps: all.filter(under), reason: "files under the apps changed" };
+  if (changed.length === 0)
+    return { apps: [], reason: "nothing but bookkeeping changed" };
+  if (changed.some((f) => GLOBALS.test(f)))
+    return { apps: all, reason: "a workspace-global input changed: every app counts as changed" };
+  const outside = changed.some((f) => !f.startsWith("apps/"));
+  const listed = new Set(await input.dependents?.() ?? []);
+  return {
+    apps: all.filter((app) => listed.has(app) && (outside || under(app))),
+    reason: "sources or their dependencies changed"
+  };
 }
-var presetSource = (preset) => `gh:plexus-ms/${preset}`;
-async function findConsumers(ctx, root, presets) {
-  const sources = new Map(presets.map((p) => [presetSource(p), p]));
-  const consumers = /* @__PURE__ */ new Map();
-  const orphans = [];
-  const visit = (dir, repo, inTemplate) => {
-    const here = dir.git ? dir : repo;
-    const template = inTemplate || Boolean(dir.template);
-    const preset = dir.copier?.src ? sources.get(dir.copier.src) : void 0;
-    if (preset && !template) {
-      const site = { path: dir.path, rel: relative(root.path, dir.path) || ".", preset };
-      if (!here)
-        orphans.push(site);
-      else {
-        let consumer = consumers.get(here.path);
-        if (!consumer) {
-          consumer = {
-            path: here.path,
-            rel: relative(root.path, here.path) || ".",
-            branch: here.git?.branch ?? "?",
-            expected: expectedBranch(here.declaration),
-            sites: []
-          };
-          consumers.set(here.path, consumer);
-        }
-        consumer.sites.push(site);
-      }
-    }
-    for (const child of dir.children)
-      visit(child, here, template);
+async function readChangedApps(ctx, dir, from, to = "HEAD") {
+  const git2 = (args) => ctx.read("git", args, { cwd: dir });
+  const workspace = await exists(ctx, join2(dir, "pnpm-workspace.yaml"));
+  const all = await deployableApps(ctx, dir, workspace);
+  let changed;
+  if (from !== "" && !NO_REF.test(from) && await isCommit(git2, from))
+    changed = (await git2(["diff", "--name-only", from, to])).split("\n").filter(Boolean);
+  const dependents = async () => {
+    const out = await ctx.read("pnpm", ["--filter", `...[${from}...${to}]`, "ls", "--depth", "-1", "--parseable"], {
+      cwd: dir
+    });
+    return out.split("\n").map((line) => /(?:^|\/)apps\/([^/]+)$/.exec(line.trim())?.[1]).filter((app) => app !== void 0);
   };
-  visit(root, void 0, false);
-  for (const site of orphans)
-    ctx.say(`\u26A0 ${site.rel}: not inside a git repo \u2014 skipped`);
-  for (const c of consumers.values()) {
-    if (c.expected && c.branch !== c.expected) {
-      c.skipped = `on '${c.branch}', expected '${c.expected}'`;
+  const result = await selectChangedApps({ workspace, all, changed, dependents });
+  ctx.say(`\u2192 ${result.reason}`, 1);
+  return result;
+}
+async function isCommit(git2, ref) {
+  try {
+    await git2(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function deployableApps(ctx, dir, workspace) {
+  const entries = await ctx.readDir(join2(dir, "apps")).catch(() => []);
+  const apps = [];
+  for (const e of entries) {
+    if (!e.directory)
       continue;
+    const marks = workspace ? ["package.json"] : ["docker/compose.yaml", "compose.yaml"];
+    for (const mark of marks) {
+      if (await exists(ctx, join2(dir, "apps", e.name, mark))) {
+        apps.push(e.name);
+        break;
+      }
     }
-    const tracked = (await ctx.read("git", ["status", "--porcelain", "--untracked-files=no"], { cwd: c.path })).trim();
-    if (tracked !== "")
-      c.skipped = "has uncommitted changes";
   }
-  return [...consumers.values()];
+  return apps.sort();
+}
+async function exists(ctx, path3) {
+  try {
+    await ctx.readFile(path3);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
+// ../lib/dist/changeset.js
+var import_yaml2 = __toESM(require_dist(), 1);
+import { join as join3 } from "node:path";
+
 // ../lib/dist/io.js
 import { spawn } from "node:child_process";
 import { readdir, readFile, writeFile } from "node:fs/promises";
@@ -7733,13 +7754,13 @@ function realIo(prompt) {
     stdout: process.stdout,
     stderr: process.stderr,
     prompt: prompt && isInteractive() ? prompt : void 0,
-    exec: (command, args, options = {}) => new Promise((resolve6, reject) => {
+    exec: (command, args, options = {}) => new Promise((resolve9, reject) => {
       const child = spawn(command, args, {
         cwd: options.cwd,
         env: options.env,
         stdio: [
           options.input !== void 0 ? "pipe" : options.inherit ? "inherit" : "ignore",
-          options.inherit ? "inherit" : "pipe",
+          options.inherit ? process.stderr.fd : "pipe",
           "pipe"
         ]
       });
@@ -7756,7 +7777,7 @@ function realIo(prompt) {
       child.on("error", reject);
       child.on("close", (code) => {
         if (code === 0)
-          resolve6(stdout);
+          resolve9(stdout);
         else
           reject(new ExecError(render(command, args), code, stderr));
       });
@@ -7805,6 +7826,194 @@ EOF`;
   }
 }
 
+// ../lib/dist/changeset.js
+var CHANGESET_DIR = ".changeset";
+var FIELDS = ["dependencies", "optionalDependencies", "peerDependencies"];
+function changesetPath(branch) {
+  const slug = branch.replace(/^(renovate|dependabot)\//, "").replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").toLowerCase();
+  return `${CHANGESET_DIR}/bot-${slug || "branch"}.md`;
+}
+function planChangeset(input) {
+  const path3 = changesetPath(input.branch);
+  const changes = [];
+  const releases = {};
+  for (const diff of input.packages) {
+    const { before, after } = diff;
+    if (!before || !after?.name || after.private || input.ignore.includes(after.name))
+      continue;
+    for (const field of FIELDS) {
+      const names = /* @__PURE__ */ new Set([...Object.keys(before[field] ?? {}), ...Object.keys(after[field] ?? {})]);
+      for (const dependency of [...names].sort()) {
+        const from = resolveRange(before[field]?.[dependency], dependency, input.catalogsBefore);
+        const to = resolveRange(after[field]?.[dependency], dependency, input.catalogsAfter);
+        if (from === to)
+          continue;
+        changes.push({ package: after.name, dependency, field, from, to });
+        const bump = field === "peerDependencies" ? "major" : "patch";
+        if (releases[after.name] !== "major")
+          releases[after.name] = bump;
+      }
+    }
+  }
+  const root = input.root;
+  if (changes.length === 0) {
+    const remove = run("rm", ["-f", path3], root ? { cwd: root } : {});
+    return { path: path3, releases, changes, plan: input.exists ? [remove] : [] };
+  }
+  const header = Object.entries(releases).sort(([a], [b]) => a.localeCompare(b)).map(([name, bump]) => `'${name}': ${bump}`);
+  const lines = [...new Set(changes.map(describeChange))].sort((a, b) => a.localeCompare(b));
+  const content = `---
+${header.join("\n")}
+---
+
+${lines.join("\n")}
+`;
+  return { path: path3, releases, changes, content, plan: [write(root ? join3(root, path3) : path3, content)] };
+}
+function describeChange(c) {
+  const peer = c.field === "peerDependencies" ? " (peer)" : "";
+  if (c.from === void 0)
+    return `Add \`${c.dependency}\`${peer} at ${c.to}`;
+  if (c.to === void 0)
+    return `Remove \`${c.dependency}\`${peer}`;
+  return `Update \`${c.dependency}\`${peer} from ${c.from} to ${c.to}`;
+}
+function resolveRange(value, dependency, catalogs) {
+  if (value === void 0)
+    return void 0;
+  if (value === "catalog:" || value === "catalog:default")
+    return catalogs.default[dependency] ?? value;
+  if (value.startsWith("catalog:"))
+    return catalogs.named[value.slice("catalog:".length)]?.[dependency] ?? value;
+  return value;
+}
+function parseCatalogs(text) {
+  const data = text === void 0 ? void 0 : (0, import_yaml2.parse)(text);
+  const ws = data !== null && typeof data === "object" ? data : {};
+  const map = (v) => v !== null && typeof v === "object" ? Object.fromEntries(Object.entries(v).map(([k, r]) => [k, String(r)])) : {};
+  const named = ws.catalogs !== null && typeof ws.catalogs === "object" ? ws.catalogs : {};
+  return {
+    default: map(ws.catalog),
+    named: Object.fromEntries(Object.entries(named).map(([name, entries]) => [name, map(entries)]))
+  };
+}
+function workspaceGlobs(text) {
+  const data = text === void 0 ? void 0 : (0, import_yaml2.parse)(text);
+  const globs = data !== null && typeof data === "object" ? data.packages : void 0;
+  return Array.isArray(globs) ? globs.map(String).filter((g) => !g.startsWith("!")) : [];
+}
+async function readChangeset(ctx, dir, base, branch) {
+  const git2 = (args) => ctx.read("git", args, { cwd: dir });
+  const head = branch ?? (await git2(["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+  const mergeBase = (await git2(["merge-base", base, "HEAD"])).trim();
+  const show = async (path4) => {
+    try {
+      return await git2(["show", `${mergeBase}:${path4}`]);
+    } catch (error) {
+      if (error instanceof ExecError)
+        return void 0;
+      throw error;
+    }
+  };
+  const current = async (path4) => {
+    try {
+      return await ctx.readFile(join3(dir, path4));
+    } catch {
+      return void 0;
+    }
+  };
+  const workspaceAfter = await current("pnpm-workspace.yaml");
+  const packages = [];
+  for (const glob of workspaceGlobs(workspaceAfter)) {
+    for (const pkgDir of await expand(ctx, dir, glob)) {
+      const path4 = `${pkgDir}/package.json`;
+      const [before, after] = await Promise.all([show(path4), current(path4)]);
+      packages.push({ path: path4, before: manifest(before), after: manifest(after) });
+    }
+  }
+  const config = await current(`${CHANGESET_DIR}/config.json`);
+  const ignore = config ? JSON.parse(config).ignore ?? [] : [];
+  const entries = await ctx.readDir(join3(dir, CHANGESET_DIR)).catch(() => []);
+  const path3 = changesetPath(head);
+  return planChangeset({
+    branch: head,
+    packages,
+    catalogsBefore: parseCatalogs(await show("pnpm-workspace.yaml")),
+    catalogsAfter: parseCatalogs(workspaceAfter),
+    ignore,
+    exists: entries.some((e) => !e.directory && `${CHANGESET_DIR}/${e.name}` === path3),
+    root: dir
+  });
+}
+function manifest(text) {
+  return text === void 0 ? void 0 : JSON.parse(text);
+}
+async function expand(ctx, root, glob) {
+  const star = glob.indexOf("*");
+  if (star < 0)
+    return [glob.replace(/\/$/, "")];
+  const parent = glob.slice(0, star).replace(/\/$/, "");
+  const entries = await ctx.readDir(join3(root, parent)).catch(() => []);
+  return entries.filter((e) => e.directory && !e.name.startsWith(".")).map((e) => parent ? `${parent}/${e.name}` : e.name).sort();
+}
+
+// ../lib/dist/consumers.js
+import { relative } from "node:path";
+function expectedBranch(declaration) {
+  if (!declaration)
+    return void 0;
+  if (declaration.modules.includes("PLX-Platform"))
+    return "main";
+  if (declaration.modules.includes("PLX-Repo"))
+    return "develop";
+  return void 0;
+}
+var presetSource = (preset) => `gh:plexus-ms/${preset}`;
+async function findConsumers(ctx, root, presets) {
+  const sources = new Map(presets.map((p) => [presetSource(p), p]));
+  const consumers = /* @__PURE__ */ new Map();
+  const orphans = [];
+  const visit = (dir, repo, inTemplate) => {
+    const here = dir.git ? dir : repo;
+    const template = inTemplate || Boolean(dir.template);
+    const preset = dir.copier?.src ? sources.get(dir.copier.src) : void 0;
+    if (preset && !template) {
+      const site = { path: dir.path, rel: relative(root.path, dir.path) || ".", preset };
+      if (!here)
+        orphans.push(site);
+      else {
+        let consumer = consumers.get(here.path);
+        if (!consumer) {
+          consumer = {
+            path: here.path,
+            rel: relative(root.path, here.path) || ".",
+            branch: here.git?.branch ?? "?",
+            expected: expectedBranch(here.declaration),
+            sites: []
+          };
+          consumers.set(here.path, consumer);
+        }
+        consumer.sites.push(site);
+      }
+    }
+    for (const child of dir.children)
+      visit(child, here, template);
+  };
+  visit(root, void 0, false);
+  for (const site of orphans)
+    ctx.say(`\u26A0 ${site.rel}: not inside a git repo \u2014 skipped`);
+  for (const c of consumers.values()) {
+    if (c.expected && c.branch !== c.expected) {
+      c.skipped = `on '${c.branch}', expected '${c.expected}'`;
+      continue;
+    }
+    const tracked = (await ctx.read("git", ["status", "--porcelain", "--untracked-files=no"], { cwd: c.path })).trim();
+    if (tracked !== "")
+      c.skipped = "has uncommitted changes";
+  }
+  return [...consumers.values()];
+}
+
 // ../lib/dist/context.js
 var Context = class {
   dryRun;
@@ -7840,6 +8049,8 @@ var Context = class {
    */
   result(data, human = renderHuman) {
     const text = this.json ? JSON.stringify(data, null, 2) : human(data);
+    if (text === "")
+      return;
     this.io.stdout.write(text.endsWith("\n") ? text : `${text}
 `);
   }
@@ -7919,11 +8130,11 @@ function indent(text) {
 }
 
 // ../lib/dist/copier.js
-var import_yaml2 = __toESM(require_dist(), 1);
+var import_yaml3 = __toESM(require_dist(), 1);
 var ANSWERS_FILE = ".copier-answers.yml";
 var TEMPLATE_FILES = ["copier.yml", "copier.yaml"];
 function parseAnswers(text) {
-  const data = (0, import_yaml2.parse)(text);
+  const data = (0, import_yaml3.parse)(text);
   if (data === null || typeof data !== "object" || Array.isArray(data))
     throw new Error("answers file is not a mapping");
   const { _commit, _src_path, ...answers } = data;
@@ -7934,6 +8145,13 @@ function parseAnswers(text) {
   };
 }
 
+// ../lib/dist/deployTargets.js
+var import_yaml4 = __toESM(require_dist(), 1);
+import { join as join5 } from "node:path";
+
+// ../lib/dist/train.js
+import { join as join4 } from "node:path";
+
 // ../lib/dist/doctor.js
 import { relative as relative2 } from "node:path";
 function diagnose(root, catalog) {
@@ -7993,6 +8211,130 @@ function compareTrains(a, b) {
   return 0;
 }
 
+// ../lib/dist/train.js
+var TRAIN_REPOS = [
+  "platform",
+  "ci-cd",
+  "preset-repo-web",
+  "preset-app-nextjs",
+  "preset-repo-platform",
+  "compendium"
+];
+var UPSTREAM = "plexus-ms";
+var isTrainVersion = (v) => /^\d+\.\d+\.\d+$/.test(v);
+function nextMinor(version2) {
+  const [major = "0", minor = "0"] = version2.split(".");
+  return `${major}.${Number(minor) + 1}.0`;
+}
+function latestTag(tags) {
+  return tags.filter((t) => /^v?\d/.test(t)).sort((a, b) => compareTrains(a.replace(/^v/, ""), b.replace(/^v/, ""))).at(-1);
+}
+async function readTrain(ctx, upstream) {
+  const repos = [];
+  const all = /* @__PURE__ */ new Set();
+  for (const name of TRAIN_REPOS) {
+    const path3 = join4(upstream, name);
+    try {
+      await ctx.read("git", ["rev-parse", "--git-dir"], { cwd: path3 });
+    } catch {
+      throw new Error(`${path3} is not a git repo`);
+    }
+    try {
+      await ctx.read("git", ["fetch", "origin", "--tags", "--quiet"], { cwd: path3 });
+    } catch {
+      throw new Error(`${name}: fetch from origin failed`);
+    }
+    const tags = (await ctx.read("git", ["tag", "--list", "v*", "[0-9]*"], { cwd: path3 })).split("\n").filter(Boolean);
+    for (const t of tags)
+      all.add(t.replace(/^v/, ""));
+    const tag = latestTag(tags);
+    const range = tag ? `${tag}..HEAD` : "HEAD";
+    const pending = (await ctx.read("git", ["log", "--oneline", range], { cwd: path3 })).split("\n").filter(Boolean);
+    repos.push({ name, path: path3, tag, latest: tag?.replace(/^v/, ""), pending });
+  }
+  const latest = repos.map((r) => r.latest);
+  return { repos, last: latestTag([...all]), skew: latest.some((l) => l !== latest[0]) };
+}
+async function preflightRelease(ctx, train) {
+  for (const { name, path: path3 } of train.repos) {
+    const branch = (await ctx.read("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: path3 })).trim();
+    if (branch !== "main")
+      throw new Error(`${name} is on '${branch}', trains cut from main`);
+    if ((await ctx.read("git", ["status", "--porcelain"], { cwd: path3 })).trim() !== "")
+      throw new Error(`${name} has uncommitted changes \u2014 commit first`);
+    const behind = (await ctx.read("git", ["rev-list", "--count", "main..origin/main"], { cwd: path3 })).trim();
+    if (behind !== "0")
+      throw new Error(`${name} is ${behind} commit(s) behind origin/main \u2014 pull first, or the tag lands on a stale commit`);
+  }
+}
+function resolveVersion(train, explicit, propagateOnly) {
+  if (explicit !== void 0 && !isTrainVersion(explicit))
+    throw new UsageError(`'${explicit}' is not plain semver (X.Y.Z, no v)`);
+  if (propagateOnly) {
+    const v = explicit ?? train.last;
+    if (!v)
+      throw new Error("no train version found to propagate");
+    return v;
+  }
+  if (explicit)
+    return explicit;
+  if (train.skew) {
+    const report = train.repos.map((r) => `  ${r.name}: ${r.latest ?? "none"}`).join("\n");
+    throw new Error(`the train repos' latest tags disagree:
+${report}
+pass the version explicitly (--train ${train.last}) to finish the half-tagged train, or a higher one to start a new one`);
+  }
+  return train.last ? nextMinor(train.last) : "0.1.0";
+}
+var UsageError = class extends Error {
+};
+
+// ../lib/dist/deployTargets.js
+var VARS_DIRS = ["group_vars", "host_vars"];
+function parseInventoryFile(path3, text) {
+  const data = (0, import_yaml4.parse)(text);
+  const vars = data !== null && typeof data === "object" ? data : {};
+  const target = typeof vars.plexus_deploy_target === "string" ? vars.plexus_deploy_target : void 0;
+  const records = Array.isArray(vars.plexus_apps) ? vars.plexus_apps : [];
+  const apps = records.map((r) => r !== null && typeof r === "object" ? r.name : void 0).filter((n) => typeof n === "string");
+  return { path: path3, target, apps };
+}
+function selectDeployTargets(files) {
+  const targets = {};
+  const declaredIn = {};
+  for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+    if (file.target === void 0)
+      continue;
+    for (const app of file.apps) {
+      if (app in targets)
+        throw new Error(`app "${app}" is declared with a deploy target in both ${declaredIn[app]} and ${file.path}`);
+      targets[app] = file.target;
+      declaredIn[app] = file.path;
+    }
+  }
+  return Object.fromEntries(Object.entries(targets).sort(([a], [b]) => a.localeCompare(b)));
+}
+async function readDeployTargets(ctx, inventory) {
+  const files = [];
+  let found = false;
+  for (const sub of VARS_DIRS) {
+    const dir = join5(inventory, sub);
+    const entries = await ctx.readDir(dir).catch(() => void 0);
+    if (entries === void 0)
+      continue;
+    found = true;
+    for (const e of entries) {
+      if (e.directory || !/\.ya?ml$/.test(e.name))
+        continue;
+      const path3 = join5(dir, e.name);
+      files.push(parseInventoryFile(path3, await ctx.readFile(path3)));
+    }
+  }
+  if (!found && await ctx.readDir(inventory).catch(() => void 0) === void 0)
+    throw new UsageError(`no inventory directory at ${inventory}`);
+  return selectDeployTargets(files);
+}
+
 // ../lib/dist/model.js
 function kindOf(declaration) {
   const has = (code) => declaration.modules.includes(code);
@@ -8014,7 +8356,7 @@ function isNotable(dir) {
 }
 
 // ../lib/dist/overview.js
-import { join as join2 } from "node:path";
+import { join as join6 } from "node:path";
 var PRUNED = /* @__PURE__ */ new Set([
   "node_modules",
   ".hg",
@@ -8062,7 +8404,7 @@ async function walk(ctx, path3, name, options) {
   }
   const subdirs = entries.filter((e) => e.directory && e.name !== ".git" && !PRUNED.has(e.name)).map((e) => e.name).sort();
   for (const sub of subdirs) {
-    const child = await walk(ctx, join2(path3, sub), sub, options);
+    const child = await walk(ctx, join6(path3, sub), sub, options);
     if (isNotable(child) || child.children.length > 0)
       dir.children.push(child);
   }
@@ -8070,7 +8412,7 @@ async function walk(ctx, path3, name, options) {
 }
 async function facet(ctx, dir, file, read) {
   try {
-    read(await ctx.readFile(join2(dir.path, file)));
+    read(await ctx.readFile(join6(dir.path, file)));
   } catch (error) {
     dir.problems ??= [];
     dir.problems.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
@@ -8109,93 +8451,12 @@ async function templateFacet(ctx, cwd) {
 }
 
 // ../lib/dist/propagate.js
-import { join as join4, relative as relative3 } from "node:path";
-
-// ../lib/dist/train.js
-import { join as join3 } from "node:path";
-var TRAIN_REPOS = [
-  "platform",
-  "ci-cd",
-  "preset-repo-web",
-  "preset-app-nextjs",
-  "preset-repo-platform",
-  "compendium"
-];
-var UPSTREAM = "plexus-ms";
-var isTrainVersion = (v) => /^\d+\.\d+\.\d+$/.test(v);
-function nextMinor(version2) {
-  const [major = "0", minor = "0"] = version2.split(".");
-  return `${major}.${Number(minor) + 1}.0`;
-}
-function latestTag(tags) {
-  return tags.filter((t) => /^v?\d/.test(t)).sort((a, b) => compareTrains(a.replace(/^v/, ""), b.replace(/^v/, ""))).at(-1);
-}
-async function readTrain(ctx, upstream) {
-  const repos = [];
-  const all = /* @__PURE__ */ new Set();
-  for (const name of TRAIN_REPOS) {
-    const path3 = join3(upstream, name);
-    try {
-      await ctx.read("git", ["rev-parse", "--git-dir"], { cwd: path3 });
-    } catch {
-      throw new Error(`${path3} is not a git repo`);
-    }
-    try {
-      await ctx.read("git", ["fetch", "origin", "--tags", "--quiet"], { cwd: path3 });
-    } catch {
-      throw new Error(`${name}: fetch from origin failed`);
-    }
-    const tags = (await ctx.read("git", ["tag", "--list", "v*", "[0-9]*"], { cwd: path3 })).split("\n").filter(Boolean);
-    for (const t of tags)
-      all.add(t.replace(/^v/, ""));
-    const tag = latestTag(tags);
-    const range = tag ? `${tag}..HEAD` : "HEAD";
-    const pending = (await ctx.read("git", ["log", "--oneline", range], { cwd: path3 })).split("\n").filter(Boolean);
-    repos.push({ name, path: path3, tag, latest: tag?.replace(/^v/, ""), pending });
-  }
-  const latest = repos.map((r) => r.latest);
-  return { repos, last: latestTag([...all]), skew: latest.some((l) => l !== latest[0]) };
-}
-async function preflightRelease(ctx, train) {
-  for (const { name, path: path3 } of train.repos) {
-    const branch = (await ctx.read("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: path3 })).trim();
-    if (branch !== "main")
-      throw new Error(`${name} is on '${branch}', trains cut from main`);
-    if ((await ctx.read("git", ["status", "--porcelain"], { cwd: path3 })).trim() !== "")
-      throw new Error(`${name} has uncommitted changes \u2014 commit first`);
-    const behind = (await ctx.read("git", ["rev-list", "--count", "main..origin/main"], { cwd: path3 })).trim();
-    if (behind !== "0")
-      throw new Error(`${name} is ${behind} commit(s) behind origin/main \u2014 pull first, or the tag lands on a stale commit`);
-  }
-}
-function resolveVersion(train, explicit, propagateOnly) {
-  if (explicit !== void 0 && !isTrainVersion(explicit))
-    throw new UsageError(`'${explicit}' is not plain semver (X.Y.Z, no v)`);
-  if (propagateOnly) {
-    const v = explicit ?? train.last;
-    if (!v)
-      throw new Error("no train version found to propagate");
-    return v;
-  }
-  if (explicit)
-    return explicit;
-  if (train.skew) {
-    const report = train.repos.map((r) => `  ${r.name}: ${r.latest ?? "none"}`).join("\n");
-    throw new Error(`the train repos' latest tags disagree:
-${report}
-pass the version explicitly (--train ${train.last}) to finish the half-tagged train, or a higher one to start a new one`);
-  }
-  return train.last ? nextMinor(train.last) : "0.1.0";
-}
-var UsageError = class extends Error {
-};
-
-// ../lib/dist/propagate.js
+import { join as join7, relative as relative3 } from "node:path";
 var isClean = (s) => s.conflicted.length === 0 && s.failed.length === 0 && s.skipped.length === 0;
 var PREVIEW_BASE = "ship-base";
 async function propagate(ctx, workspace, train) {
   const summary = { train, preview: ctx.dryRun, clean: [], conflicted: [], failed: [], skipped: [] };
-  const upstream = join4(workspace, UPSTREAM);
+  const upstream = join7(workspace, UPSTREAM);
   const tree = await overview(ctx, workspace);
   const upstreamDir = tree.children.find((c) => c.path === upstream);
   const presets = TRAIN_REPOS.filter((r) => upstreamDir?.children.some((c) => c.name === r && c.template));
@@ -8212,7 +8473,7 @@ async function propagate(ctx, workspace, train) {
   const cloneOf = async (consumer) => {
     let clone = clones.get(consumer.path);
     if (!clone) {
-      clone = join4(scratch ?? "", consumer.rel);
+      clone = join7(scratch ?? "", consumer.rel);
       await ctx.stage(run("git", ["clone", "--quiet", consumer.path, clone]));
       await ctx.stage(run("git", ["tag", PREVIEW_BASE], { cwd: clone }));
       clones.set(consumer.path, clone);
@@ -8239,7 +8500,7 @@ async function propagate(ctx, workspace, train) {
       if (sites.length === 0)
         ctx.say(`\u2022 no consumers of ${presetSource(preset)} found under ${workspace}`);
       for (const [consumer, site] of sites)
-        await updateSite(ctx, consumer, site, join4(upstream, preset), summary, cloneOf, previewCommit);
+        await updateSite(ctx, consumer, site, join7(upstream, preset), summary, cloneOf, previewCommit);
     }
     await refreshLockfiles(ctx, active, summary, clones);
     await bumpConsumerRefs(ctx, consumers, train);
@@ -8256,9 +8517,9 @@ async function updateSite(ctx, consumer, site, localPreset, summary, cloneOf, pr
     if (ctx.dryRun) {
       ctx.say(`\u2192 ${site.rel}: copier update (preview from ${localPreset}@main)`);
       repo = await cloneOf(consumer);
-      target = join4(repo, relative3(consumer.path, site.path));
-      const answers = await ctx.readFile(join4(site.path, ANSWERS_FILE));
-      await ctx.stage(write(join4(target, ANSWERS_FILE), answers.replace(/^_src_path: .*$/m, `_src_path: ${localPreset}`)));
+      target = join7(repo, relative3(consumer.path, site.path));
+      const answers = await ctx.readFile(join7(site.path, ANSWERS_FILE));
+      await ctx.stage(write(join7(target, ANSWERS_FILE), answers.replace(/^_src_path: .*$/m, `_src_path: ${localPreset}`)));
       await previewCommit(repo, `plx preview: ${site.rel} reads ${localPreset} from the local checkout`);
       await ctx.stage(run("copier", ["update", "--skip-answered", "--trust", "--defaults", "--skip-tasks", "--vcs-ref", "main"], {
         cwd: target
@@ -8277,7 +8538,7 @@ async function updateSite(ctx, consumer, site, localPreset, summary, cloneOf, pr
   let conflict = hasUnmergedEntries(status);
   const changed = (await ctx.read("git", ["diff", "--name-only"], { cwd: repo })).split("\n").filter(Boolean);
   for (const f of changed) {
-    const text = await ctx.readFile(join4(repo, f)).catch(() => "");
+    const text = await ctx.readFile(join7(repo, f)).catch(() => "");
     if (hasConflictMarkers(text))
       conflict = true;
   }
@@ -8295,17 +8556,17 @@ async function updateSite(ctx, consumer, site, localPreset, summary, cloneOf, pr
     await previewCommit(repo, `plx preview: ${site.rel} updated`);
 }
 async function syncSiteMarker(ctx, site, target) {
-  const marker = await ctx.readFile(join4(target, MARKER_FILE)).catch(() => void 0);
+  const marker = await ctx.readFile(join7(target, MARKER_FILE)).catch(() => void 0);
   if (marker === void 0)
     return;
-  const { commit } = parseAnswers(await ctx.readFile(join4(target, ANSWERS_FILE)));
+  const { commit } = parseAnswers(await ctx.readFile(join7(target, ANSWERS_FILE)));
   if (!commit)
     return;
   const synced = syncMarker(marker, commit);
   if (synced === marker)
     return;
   ctx.say(`  marker: plexus \u2192 ${commit} in ${site.rel}/${MARKER_FILE}`);
-  const step = write(join4(target, MARKER_FILE), synced);
+  const step = write(join7(target, MARKER_FILE), synced);
   if (ctx.dryRun)
     await ctx.stage(step);
   else
@@ -8314,7 +8575,7 @@ async function syncSiteMarker(ctx, site, target) {
 async function refreshLockfiles(ctx, consumers, summary, clones) {
   const manifests = ["*package.json", "pnpm-workspace.yaml"];
   for (const c of consumers) {
-    if (await ctx.readFile(join4(c.path, "pnpm-workspace.yaml")).catch(() => void 0) === void 0)
+    if (await ctx.readFile(join7(c.path, "pnpm-workspace.yaml")).catch(() => void 0) === void 0)
       continue;
     const repo = ctx.dryRun ? clones.get(c.path) : c.path;
     if (!repo)
@@ -8334,7 +8595,7 @@ async function refreshLockfiles(ctx, consumers, summary, clones) {
 }
 async function bumpConsumerRefs(ctx, consumers, train) {
   for (const c of consumers) {
-    const dir = join4(c.path, ".github", "workflows");
+    const dir = join7(c.path, ".github", "workflows");
     const entries = await ctx.readDir(dir).catch(() => []);
     const files = entries.filter((e) => !e.directory && /\.ya?ml$/.test(e.name)).map((e) => e.name).sort();
     if (files.length === 0)
@@ -8344,14 +8605,14 @@ async function bumpConsumerRefs(ctx, consumers, train) {
       continue;
     }
     for (const f of files) {
-      const text = await ctx.readFile(join4(dir, f));
+      const text = await ctx.readFile(join7(dir, f));
       if (!text.includes(WORKFLOW_REF))
         continue;
       const bumped = bumpWorkflowRefs(text, train);
       if (bumped === text)
         continue;
       ctx.say(`\u2192 ${c.rel}: ${f} ci-cd refs \u2192 @${train}`);
-      await ctx.apply([write(join4(dir, f), bumped)]);
+      await ctx.apply([write(join7(dir, f), bumped)]);
     }
   }
 }
@@ -8362,7 +8623,7 @@ var detail = (error) => {
 };
 
 // ../lib/dist/requirements.js
-import { join as join5 } from "node:path";
+import { join as join8 } from "node:path";
 var KEYWORD = /MUST|SHOULD|MAY/;
 var hasKeyword = (line) => KEYWORD.test(line.replace(/MUSTs|SHOULDs|MAYs/g, ""));
 var list = (value) => value.replace(/^\s*\[/, "").replace(/\].*$/, "").split(",").map((s) => s.trim()).filter(Boolean);
@@ -8455,7 +8716,7 @@ var MAP_PAGE = "essentials/standard.md";
 async function modulePages(ctx, compendium) {
   const pages = [];
   for (const dir of Object.keys(CATALOG_DIRS)) {
-    const entries = await ctx.readDir(join5(compendium, dir));
+    const entries = await ctx.readDir(join8(compendium, dir));
     for (const e of entries.filter((e2) => !e2.directory && e2.name.endsWith(".md") && e2.name !== "index.md").sort())
       pages.push(`${dir}/${e.name}`);
   }
@@ -8463,11 +8724,11 @@ async function modulePages(ctx, compendium) {
 }
 async function checkCompendium(ctx, compendium) {
   const defects = [];
-  defects.push(...scanPage(await ctx.readFile(join5(compendium, MAP_PAGE)), MAP_PAGE, "map").defects);
+  defects.push(...scanPage(await ctx.readFile(join8(compendium, MAP_PAGE)), MAP_PAGE, "map").defects);
   const pages = await modulePages(ctx, compendium);
   const scans = /* @__PURE__ */ new Map();
   for (const page of pages) {
-    const scan = scanPage(await ctx.readFile(join5(compendium, page)), page, "module");
+    const scan = scanPage(await ctx.readFile(join8(compendium, page)), page, "module");
     defects.push(...scan.defects);
     scans.set(page, scan);
   }
@@ -8514,9 +8775,9 @@ async function checkCompendium(ctx, compendium) {
 }
 
 // ../lib/dist/ship.js
-import { join as join6 } from "node:path";
+import { join as join9 } from "node:path";
 async function ship(ctx, options) {
-  const upstream = join6(options.workspace, UPSTREAM);
+  const upstream = join9(options.workspace, UPSTREAM);
   const propagateOnly = options.propagateOnly ?? false;
   const train = await readTrain(ctx, upstream);
   if (!propagateOnly)
@@ -8567,7 +8828,7 @@ async function planBookkeeping(ctx, train, next, today2) {
     return r;
   };
   const edit = async (r, rel, what, transform) => {
-    const path3 = join6(r.path, rel);
+    const path3 = join9(r.path, rel);
     const text = await ctx.readFile(path3).catch(() => void 0);
     if (text === void 0)
       return;
@@ -8588,7 +8849,7 @@ async function planBookkeeping(ctx, train, next, today2) {
   const comp = repo("compendium");
   await edit(comp, MAP_PAGE, `version \u2192 ${next}, timestamp \u2192 ${today2}`, (t) => stampStandard(t, next, today2));
   for (const page of await modulePages(ctx, comp.path)) {
-    const text = await ctx.readFile(join6(comp.path, page));
+    const text = await ctx.readFile(join9(comp.path, page));
     if (frontmatterField(text, "maturity") !== "standard")
       continue;
     const previous = comp.tag ? await ctx.read("git", ["show", `${comp.tag}:${page}`], { cwd: comp.path }).catch(() => "") : "";
@@ -9551,13 +9812,13 @@ import { AsyncResource as AsyncResource3 } from "node:async_hooks";
 
 // ../../node_modules/.pnpm/@inquirer+type@4.2.0_@types+node@26.6.5/node_modules/@inquirer/type/dist/utils.js
 function withResolver() {
-  let resolve6;
+  let resolve9;
   let reject;
   const promise = new Promise((res, rej) => {
-    resolve6 = res;
+    resolve9 = res;
     reject = rej;
   });
-  return { promise, resolve: resolve6, reject };
+  return { promise, resolve: resolve9, reject };
 }
 
 // ../../node_modules/.pnpm/@inquirer+core@12.0.5_@types+node@26.6.5/node_modules/@inquirer/core/dist/lib/create-prompt.js
@@ -9936,7 +10197,7 @@ function createPrompt(view) {
     });
     output.mute();
     const screen = new ScreenManager(rl);
-    const { promise, resolve: resolve6, reject } = withResolver();
+    const { promise, resolve: resolve9, reject } = withResolver();
     return withHooks(rl, (cycle) => {
       const clearEffects = AsyncResource3.bind(() => effectScheduler.clearAll());
       const settlePrompt = (settle) => {
@@ -9947,7 +10208,7 @@ function createPrompt(view) {
           reject(error);
         }
       };
-      const resolvePrompt = (value) => settlePrompt(() => resolve6(value));
+      const resolvePrompt = (value) => settlePrompt(() => resolve9(value));
       const rejectPrompt = (error) => settlePrompt(() => reject(error));
       const promptPromise = Object.assign(promise.finally(() => {
         cleanups.forEach((cleanup) => cleanup());
@@ -13466,9 +13727,45 @@ function useColor() {
 // ../../node_modules/.pnpm/commander@15.0.0/node_modules/commander/index.js
 var program = new Command();
 
+// src/commands/changed-apps.ts
+import { resolve } from "node:path";
+function register(program2) {
+  program2.command("changed-apps").description("list the apps whose sources changed between two refs, dependents of a changed package included").argument("<from>", "the base ref; empty, all zeros or unknown lists every app").argument("[to]", "the ref compared against", "HEAD").option("-C, --dir <dir>", "the checkout to read", ".").action(async (from, to, opts, command) => {
+    const ctx = contextOf2(command);
+    const result = await readChangedApps(ctx, resolve(opts.dir), from, to);
+    ctx.result(result.apps);
+  });
+}
+
+// src/commands/changeset.ts
+import { resolve as resolve2 } from "node:path";
+function register2(program2) {
+  program2.command("changeset").description("write the changeset a dependency bump owes: a patch per package whose runtime dependencies moved").argument("[dir]", "a checkout of the package repo, on the bump branch", ".").option("--base <ref>", "the trunk the branch is diffed against, at the merge base", "origin/main").option("--branch <name>", "the branch name that names the file (default: the checked-out branch)").action(async (dir, opts, command) => {
+    const ctx = contextOf2(command);
+    const changeset = await readChangeset(ctx, resolve2(dir), opts.base, opts.branch);
+    await ctx.apply(changeset.plan);
+    ctx.result(changeset, renderChangeset);
+  });
+}
+function renderChangeset(c) {
+  const releases = Object.entries(c.releases);
+  if (releases.length === 0) return `\u2713 nothing owed; no ${c.path}`;
+  return [`\u2713 ${c.path}`, ...releases.map(([name, bump]) => `  ${name}: ${bump}`)].join("\n");
+}
+
+// src/commands/deploy-targets.ts
+import { resolve as resolve3 } from "node:path";
+function register3(program2) {
+  program2.command("deploy-targets").description("map each app of a platform repo to the deploy target of the inventory file that declares it").argument("[inventory]", "the inventory directory", "inventory").action(async (inventory, _opts, command) => {
+    const ctx = contextOf2(command);
+    const targets = await readDeployTargets(ctx, resolve3(inventory));
+    ctx.result(targets, (t) => JSON.stringify(t));
+  });
+}
+
 // src/commands/doctor.ts
 import { existsSync } from "node:fs";
-import { join as join7, resolve } from "node:path";
+import { join as join10, resolve as resolve4 } from "node:path";
 
 // src/style.ts
 function style(enabled) {
@@ -13479,15 +13776,15 @@ var colorByDefault = () => process.stdout.isTTY === true && !process.env.NO_COLO
 
 // src/commands/doctor.ts
 var WORKSPACE_COMPENDIUM = "plexus-ms/compendium";
-function register(program2) {
+function register4(program2) {
   program2.command("doctor").description("check every PLEXUS.md under a directory for modules that changed since and dependencies not declared").argument("[dir]", "directory to check", ".").option(
     "--compendium <path>",
     `compendium checkout to read the modules from (default: <dir>/${WORKSPACE_COMPENDIUM})`
   ).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 = resolve(dir);
-    const compendium = resolve(opts.compendium ?? join7(root, WORKSPACE_COMPENDIUM));
-    if (!existsSync(join7(compendium, "contracts")))
+    const root = resolve4(dir);
+    const compendium = resolve4(opts.compendium ?? join10(root, WORKSPACE_COMPENDIUM));
+    if (!existsSync(join10(compendium, "contracts")))
       throw new Error(
         `no compendium at ${compendium}; pass --compendium <path to a checkout of plexus-ms/compendium>`
       );
@@ -13515,11 +13812,11 @@ function renderReport(report, s, showCurrent) {
 }
 
 // src/commands/overview.ts
-import { resolve as resolve2 } from "node:path";
-function register2(program2) {
+import { resolve as resolve5 } from "node:path";
+function register5(program2) {
   program2.command("overview").description("map the git repos, copier templates and projects, and Plexus units under a directory").argument("[dir]", "directory to map", ".").option("--color", "colour the tree even when piped").option("--no-color", "never colour the tree").action(async (dir, opts, command) => {
     const ctx = contextOf2(command);
-    const tree = await overview(ctx, resolve2(dir));
+    const tree = await overview(ctx, resolve5(dir));
     const s = style(opts.color ?? colorByDefault());
     ctx.result(tree, (t) => renderTree(t, s, ctx.verbose >= 1));
   });
@@ -13562,14 +13859,14 @@ function annotate(dir, s, modules) {
 }
 
 // src/commands/propagate.ts
-import { resolve as resolve4 } from "node:path";
+import { resolve as resolve7 } from "node:path";
 
 // src/commands/ship.ts
-import { resolve as resolve3 } from "node:path";
-function register3(program2) {
+import { resolve as resolve6 } from "node:path";
+function register6(program2) {
   program2.command("ship").description("release the train: tag every train repo identically, then copier-update every consumer").argument("[dir]", "the workspace: plexus-ms/ and the consumers sit under it", ".").option("--train <version>", "the train version, plain semver (default: minor+1 over the latest train)").action(async (dir, opts, command) => {
     const ctx = contextOf2(command);
-    const result = await ship(ctx, { workspace: resolve3(dir), train: opts.train });
+    const result = await ship(ctx, { workspace: resolve6(dir), train: opts.train });
     ctx.result(result, (r) => renderSummary(r, `plx -y ship --train ${r.train} ${dir}`));
     if (!isClean(result)) process.exitCode = 1;
   });
@@ -13592,23 +13889,23 @@ function renderSummary(s, realCommand) {
 }
 
 // src/commands/propagate.ts
-function register4(program2) {
+function register7(program2) {
   program2.command("propagate").description("copier-update every consumer of the presets to the current train, and pin their ci-cd workflow refs").argument("[dir]", "the workspace: plexus-ms/ and the consumers sit under it", ".").option("--train <version>", "the train to propagate (default: the current one)").action(async (dir, opts, command) => {
     const ctx = contextOf2(command);
-    const result = await ship(ctx, { workspace: resolve4(dir), train: opts.train, propagateOnly: true });
+    const result = await ship(ctx, { workspace: resolve7(dir), train: opts.train, propagateOnly: true });
     ctx.result(result, (r) => renderSummary(r, `plx -y propagate --train ${r.train} ${dir}`));
     if (!isClean(result)) process.exitCode = 1;
   });
 }
 
 // src/commands/requirements.ts
-import { join as join8, resolve as resolve5 } from "node:path";
-function register5(program2) {
+import { join as join11, resolve as resolve8 } from "node:path";
+function register8(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 = resolve5(dir);
+    const compendium = resolve8(dir);
     if (opts.extract) {
-      ctx.result(extractRequirements(await ctx.readFile(join8(compendium, opts.extract))));
+      ctx.result(extractRequirements(await ctx.readFile(join11(compendium, opts.extract))));
       return;
     }
     const check = await checkCompendium(ctx, compendium);
@@ -13622,7 +13919,16 @@ function renderCheck(c) {
 }
 
 // src/commands/index.ts
-var commands = [register2, register, register3, register4, register5];
+var commands = [
+  register5,
+  register4,
+  register6,
+  register7,
+  register8,
+  register2,
+  register,
+  register3
+];
 
 // src/program.ts
 var { version, description } = createRequire(import.meta.url)("../package.json");
@@ -13631,7 +13937,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 register6 of commands) register6(program2);
+  for (const register9 of commands) register9(program2);
   return program2;
 }
 function contextOf2(command) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plexus-ms/cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "plx, the Plexus command-line tool: a single-script adapter over @plexus-ms/lib",
   "license": "GPL-3.0-or-later",
   "type": "module",
@@ -20,15 +20,17 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=24.22.1"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.7.4",
+    "@plexus-ms/lib": "0.5.0",
+    "commander": "^15.0.0"
   },
   "devDependencies": {
-    "@inquirer/prompts": "^8.0.0",
     "@types/node": "^26.6.5",
-    "commander": "^15.0.0",
     "esbuild": "^0.28.2",
-    "typescript": "^6.0.3",
-    "@plexus-ms/lib": "0.3.0"
+    "typescript": "^6.0.3"
   },
   "scripts": {
     "build": "node build.js",