@plexus-ms/cli 0.4.0 → 0.5.0

package/dist/plx.js

@@ -7268,7 +7268,7 @@ var require_public_api = __commonJS({
       }
       return doc;
     }
-    function parse4(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 = parse4;
+    exports.parse = parse5;
     exports.parseAllDocuments = parseAllDocuments;
     exports.parseDocument = parseDocument;
     exports.stringify = stringify;
@@ -7655,9 +7655,83 @@ async function readCatalog(ctx, compendium) {
   return catalog;
 }
 
+// ../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"
+  };
+}
+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);
+  };
+  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;
+      }
+    }
+  }
+  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 join2 } from "node:path";
+import { join as join3 } from "node:path";
 
 // ../lib/dist/io.js
 import { spawn } from "node:child_process";
@@ -7680,7 +7754,7 @@ function realIo(prompt) {
     stdout: process.stdout,
     stderr: process.stderr,
     prompt: prompt && isInteractive() ? prompt : void 0,
-    exec: (command, args, options = {}) => new Promise((resolve7, reject) => {
+    exec: (command, args, options = {}) => new Promise((resolve9, reject) => {
       const child = spawn(command, args, {
         cwd: options.cwd,
         env: options.env,
@@ -7703,7 +7777,7 @@ function realIo(prompt) {
       child.on("error", reject);
       child.on("close", (code) => {
         if (code === 0)
-          resolve7(stdout);
+          resolve9(stdout);
         else
           reject(new ExecError(render(command, args), code, stderr));
       });
@@ -7794,7 +7868,7 @@ ${header.join("\n")}
 
 ${lines.join("\n")}
 `;
-  return { path: path3, releases, changes, content, plan: [write(root ? join2(root, path3) : path3, content)] };
+  return { path: path3, releases, changes, content, plan: [write(root ? join3(root, path3) : path3, content)] };
 }
 function describeChange(c) {
   const peer = c.field === "peerDependencies" ? " (peer)" : "";
@@ -7843,7 +7917,7 @@ async function readChangeset(ctx, dir, base, branch) {
   };
   const current = async (path4) => {
     try {
-      return await ctx.readFile(join2(dir, path4));
+      return await ctx.readFile(join3(dir, path4));
     } catch {
       return void 0;
     }
@@ -7859,7 +7933,7 @@ async function readChangeset(ctx, dir, base, branch) {
   }
   const config = await current(`${CHANGESET_DIR}/config.json`);
   const ignore = config ? JSON.parse(config).ignore ?? [] : [];
-  const entries = await ctx.readDir(join2(dir, CHANGESET_DIR)).catch(() => []);
+  const entries = await ctx.readDir(join3(dir, CHANGESET_DIR)).catch(() => []);
   const path3 = changesetPath(head);
   return planChangeset({
     branch: head,
@@ -7879,7 +7953,7 @@ async function expand(ctx, root, glob) {
   if (star < 0)
     return [glob.replace(/\/$/, "")];
   const parent = glob.slice(0, star).replace(/\/$/, "");
-  const entries = await ctx.readDir(join2(root, parent)).catch(() => []);
+  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();
 }
 
@@ -7975,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}
 `);
   }
@@ -8069,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) {
@@ -8128,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);
@@ -8149,7 +8356,7 @@ function isNotable(dir) {
 }
 
 // ../lib/dist/overview.js
-import { join as join3 } from "node:path";
+import { join as join6 } from "node:path";
 var PRUNED = /* @__PURE__ */ new Set([
   "node_modules",
   ".hg",
@@ -8197,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, join3(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);
   }
@@ -8205,7 +8412,7 @@ async function walk(ctx, path3, name, options) {
 }
 async function facet(ctx, dir, file, read) {
   try {
-    read(await ctx.readFile(join3(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)}`);
@@ -8244,93 +8451,12 @@ async function templateFacet(ctx, cwd) {
 }
 
 // ../lib/dist/propagate.js
-import { join as join5, relative as relative3 } from "node:path";
-
-// ../lib/dist/train.js
-import { join as join4 } 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 = 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/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 = join5(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));
@@ -8347,7 +8473,7 @@ async function propagate(ctx, workspace, train) {
   const cloneOf = async (consumer) => {
     let clone = clones.get(consumer.path);
     if (!clone) {
-      clone = join5(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);
@@ -8374,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, join5(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);
@@ -8391,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 = join5(repo, relative3(consumer.path, site.path));
-      const answers = await ctx.readFile(join5(site.path, ANSWERS_FILE));
-      await ctx.stage(write(join5(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
@@ -8412,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(join5(repo, f)).catch(() => "");
+    const text = await ctx.readFile(join7(repo, f)).catch(() => "");
     if (hasConflictMarkers(text))
       conflict = true;
   }
@@ -8430,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(join5(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(join5(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(join5(target, MARKER_FILE), synced);
+  const step = write(join7(target, MARKER_FILE), synced);
   if (ctx.dryRun)
     await ctx.stage(step);
   else
@@ -8449,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(join5(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)
@@ -8469,7 +8595,7 @@ async function refreshLockfiles(ctx, consumers, summary, clones) {
 }
 async function bumpConsumerRefs(ctx, consumers, train) {
   for (const c of consumers) {
-    const dir = join5(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)
@@ -8479,14 +8605,14 @@ async function bumpConsumerRefs(ctx, consumers, train) {
       continue;
     }
     for (const f of files) {
-      const text = await ctx.readFile(join5(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(join5(dir, f), bumped)]);
+      await ctx.apply([write(join7(dir, f), bumped)]);
     }
   }
 }
@@ -8497,7 +8623,7 @@ var detail = (error) => {
 };
 
 // ../lib/dist/requirements.js
-import { join as join6 } 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);
@@ -8590,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(join6(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}`);
   }
@@ -8598,11 +8724,11 @@ async function modulePages(ctx, compendium) {
 }
 async function checkCompendium(ctx, compendium) {
   const defects = [];
-  defects.push(...scanPage(await ctx.readFile(join6(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(join6(compendium, page)), page, "module");
+    const scan = scanPage(await ctx.readFile(join8(compendium, page)), page, "module");
     defects.push(...scan.defects);
     scans.set(page, scan);
   }
@@ -8649,9 +8775,9 @@ async function checkCompendium(ctx, compendium) {
 }
 
 // ../lib/dist/ship.js
-import { join as join7 } from "node:path";
+import { join as join9 } from "node:path";
 async function ship(ctx, options) {
-  const upstream = join7(options.workspace, UPSTREAM);
+  const upstream = join9(options.workspace, UPSTREAM);
   const propagateOnly = options.propagateOnly ?? false;
   const train = await readTrain(ctx, upstream);
   if (!propagateOnly)
@@ -8702,7 +8828,7 @@ async function planBookkeeping(ctx, train, next, today2) {
     return r;
   };
   const edit = async (r, rel, what, transform) => {
-    const path3 = join7(r.path, rel);
+    const path3 = join9(r.path, rel);
     const text = await ctx.readFile(path3).catch(() => void 0);
     if (text === void 0)
       return;
@@ -8723,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(join7(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(() => "") : "";
@@ -9686,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 resolve7;
+  let resolve9;
   let reject;
   const promise = new Promise((res, rej) => {
-    resolve7 = res;
+    resolve9 = res;
     reject = rej;
   });
-  return { promise, resolve: resolve7, 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
@@ -10071,7 +10197,7 @@ function createPrompt(view) {
     });
     output.mute();
     const screen = new ScreenManager(rl);
-    const { promise, resolve: resolve7, reject } = withResolver();
+    const { promise, resolve: resolve9, reject } = withResolver();
     return withHooks(rl, (cycle) => {
       const clearEffects = AsyncResource3.bind(() => effectScheduler.clearAll());
       const settlePrompt = (settle) => {
@@ -10082,7 +10208,7 @@ function createPrompt(view) {
           reject(error);
         }
       };
-      const resolvePrompt = (value) => settlePrompt(() => resolve7(value));
+      const resolvePrompt = (value) => settlePrompt(() => resolve9(value));
       const rejectPrompt = (error) => settlePrompt(() => reject(error));
       const promptPromise = Object.assign(promise.finally(() => {
         cleanups.forEach((cleanup) => cleanup());
@@ -13601,12 +13727,22 @@ function useColor() {
 // ../../node_modules/.pnpm/commander@15.0.0/node_modules/commander/index.js
 var program = new Command();
 
-// src/commands/changeset.ts
+// 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, resolve(dir), opts.base, opts.branch);
+    const changeset = await readChangeset(ctx, resolve2(dir), opts.base, opts.branch);
     await ctx.apply(changeset.plan);
     ctx.result(changeset, renderChangeset);
   });
@@ -13617,9 +13753,19 @@ function renderChangeset(c) {
   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 join8, resolve as resolve2 } from "node:path";
+import { join as join10, resolve as resolve4 } from "node:path";
 
 // src/style.ts
 function style(enabled) {
@@ -13630,15 +13776,15 @@ var colorByDefault = () => process.stdout.isTTY === true && !process.env.NO_COLO
 
 // src/commands/doctor.ts
 var WORKSPACE_COMPENDIUM = "plexus-ms/compendium";
-function register2(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 = resolve2(dir);
-    const compendium = resolve2(opts.compendium ?? join8(root, WORKSPACE_COMPENDIUM));
-    if (!existsSync(join8(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>`
       );
@@ -13666,11 +13812,11 @@ function renderReport(report, s, showCurrent) {
 }
 
 // src/commands/overview.ts
-import { resolve as resolve3 } from "node:path";
-function register3(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, resolve3(dir));
+    const tree = await overview(ctx, resolve5(dir));
     const s = style(opts.color ?? colorByDefault());
     ctx.result(tree, (t) => renderTree(t, s, ctx.verbose >= 1));
   });
@@ -13713,14 +13859,14 @@ function annotate(dir, s, modules) {
 }
 
 // src/commands/propagate.ts
-import { resolve as resolve5 } from "node:path";
+import { resolve as resolve7 } from "node:path";
 
 // src/commands/ship.ts
-import { resolve as resolve4 } from "node:path";
-function register4(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: resolve4(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;
   });
@@ -13743,23 +13889,23 @@ function renderSummary(s, realCommand) {
 }
 
 // src/commands/propagate.ts
-function register5(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: resolve5(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 join9, resolve as resolve6 } from "node:path";
-function register6(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 = resolve6(dir);
+    const compendium = resolve8(dir);
     if (opts.extract) {
-      ctx.result(extractRequirements(await ctx.readFile(join9(compendium, opts.extract))));
+      ctx.result(extractRequirements(await ctx.readFile(join11(compendium, opts.extract))));
       return;
     }
     const check = await checkCompendium(ctx, compendium);
@@ -13773,7 +13919,16 @@ function renderCheck(c) {
 }
 
 // src/commands/index.ts
-var commands = [register3, register2, register4, register5, register6, register];
+var commands = [
+  register5,
+  register4,
+  register6,
+  register7,
+  register8,
+  register2,
+  register,
+  register3
+];
 
 // src/program.ts
 var { version, description } = createRequire(import.meta.url)("../package.json");
@@ -13782,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 register7 of commands) register7(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.4.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,11 +20,11 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=24.22.1"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.7.4",
-    "@plexus-ms/lib": "0.4.0",
+    "@plexus-ms/lib": "0.5.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {