@plexus-ms/cli 0.3.0 → 0.4.0

package/dist/plx.js

@@ -7268,7 +7268,7 @@ var require_public_api = __commonJS({
       }
       return doc;
     }
-    function parse3(src, reviver, options) {
+    function parse4(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 = parse4;
     exports.parseAllDocuments = parseAllDocuments;
     exports.parseDocument = parseDocument;
     exports.stringify = stringify;
@@ -7655,62 +7655,9 @@ 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;
-}
-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/changeset.js
+var import_yaml2 = __toESM(require_dist(), 1);
+import { join as join2 } from "node:path";
 
 // ../lib/dist/io.js
 import { spawn } from "node:child_process";
@@ -7733,13 +7680,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((resolve7, 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 +7703,7 @@ function realIo(prompt) {
       child.on("error", reject);
       child.on("close", (code) => {
         if (code === 0)
-          resolve6(stdout);
+          resolve7(stdout);
         else
           reject(new ExecError(render(command, args), code, stderr));
       });
@@ -7805,6 +7752,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 ? join2(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(join2(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(join2(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(join2(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;
@@ -7919,11 +8054,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;
@@ -8014,7 +8149,7 @@ function isNotable(dir) {
 }
 
 // ../lib/dist/overview.js
-import { join as join2 } from "node:path";
+import { join as join3 } from "node:path";
 var PRUNED = /* @__PURE__ */ new Set([
   "node_modules",
   ".hg",
@@ -8062,7 +8197,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, join3(path3, sub), sub, options);
     if (isNotable(child) || child.children.length > 0)
       dir.children.push(child);
   }
@@ -8070,7 +8205,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(join3(dir.path, file)));
   } catch (error) {
     dir.problems ??= [];
     dir.problems.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
@@ -8109,10 +8244,10 @@ async function templateFacet(ctx, cwd) {
 }
 
 // ../lib/dist/propagate.js
-import { join as join4, relative as relative3 } from "node:path";
+import { join as join5, relative as relative3 } from "node:path";
 
 // ../lib/dist/train.js
-import { join as join3 } from "node:path";
+import { join as join4 } from "node:path";
 var TRAIN_REPOS = [
   "platform",
   "ci-cd",
@@ -8134,7 +8269,7 @@ async function readTrain(ctx, upstream) {
   const repos = [];
   const all = /* @__PURE__ */ new Set();
   for (const name of TRAIN_REPOS) {
-    const path3 = join3(upstream, name);
+    const path3 = join4(upstream, name);
     try {
       await ctx.read("git", ["rev-parse", "--git-dir"], { cwd: path3 });
     } catch {
@@ -8195,7 +8330,7 @@ var isClean = (s) => s.conflicted.length === 0 && s.failed.length === 0 && s.ski
 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 = join5(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 +8347,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 = join5(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 +8374,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, join5(upstream, preset), summary, cloneOf, previewCommit);
     }
     await refreshLockfiles(ctx, active, summary, clones);
     await bumpConsumerRefs(ctx, consumers, train);
@@ -8256,9 +8391,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 = 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}`)));
       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 +8412,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(join5(repo, f)).catch(() => "");
     if (hasConflictMarkers(text))
       conflict = true;
   }
@@ -8295,17 +8430,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(join5(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(join5(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(join5(target, MARKER_FILE), synced);
   if (ctx.dryRun)
     await ctx.stage(step);
   else
@@ -8314,7 +8449,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(join5(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 +8469,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 = join5(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 +8479,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(join5(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(join5(dir, f), bumped)]);
     }
   }
 }
@@ -8362,7 +8497,7 @@ var detail = (error) => {
 };
 
 // ../lib/dist/requirements.js
-import { join as join5 } from "node:path";
+import { join as join6 } 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 +8590,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(join6(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 +8598,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(join6(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(join6(compendium, page)), page, "module");
     defects.push(...scan.defects);
     scans.set(page, scan);
   }
@@ -8514,9 +8649,9 @@ async function checkCompendium(ctx, compendium) {
 }
 
 // ../lib/dist/ship.js
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 async function ship(ctx, options) {
-  const upstream = join6(options.workspace, UPSTREAM);
+  const upstream = join7(options.workspace, UPSTREAM);
   const propagateOnly = options.propagateOnly ?? false;
   const train = await readTrain(ctx, upstream);
   if (!propagateOnly)
@@ -8567,7 +8702,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 = join7(r.path, rel);
     const text = await ctx.readFile(path3).catch(() => void 0);
     if (text === void 0)
       return;
@@ -8588,7 +8723,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(join7(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 +9686,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 resolve7;
   let reject;
   const promise = new Promise((res, rej) => {
-    resolve6 = res;
+    resolve7 = res;
     reject = rej;
   });
-  return { promise, resolve: resolve6, reject };
+  return { promise, resolve: resolve7, 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 +10071,7 @@ function createPrompt(view) {
     });
     output.mute();
     const screen = new ScreenManager(rl);
-    const { promise, resolve: resolve6, reject } = withResolver();
+    const { promise, resolve: resolve7, reject } = withResolver();
     return withHooks(rl, (cycle) => {
       const clearEffects = AsyncResource3.bind(() => effectScheduler.clearAll());
       const settlePrompt = (settle) => {
@@ -9947,7 +10082,7 @@ function createPrompt(view) {
           reject(error);
         }
       };
-      const resolvePrompt = (value) => settlePrompt(() => resolve6(value));
+      const resolvePrompt = (value) => settlePrompt(() => resolve7(value));
       const rejectPrompt = (error) => settlePrompt(() => reject(error));
       const promptPromise = Object.assign(promise.finally(() => {
         cleanups.forEach((cleanup) => cleanup());
@@ -13466,9 +13601,25 @@ function useColor() {
 // ../../node_modules/.pnpm/commander@15.0.0/node_modules/commander/index.js
 var program = new Command();
 
+// src/commands/changeset.ts
+import { resolve } from "node:path";
+function register(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);
+    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/doctor.ts
 import { existsSync } from "node:fs";
-import { join as join7, resolve } from "node:path";
+import { join as join8, resolve as resolve2 } from "node:path";
 
 // src/style.ts
 function style(enabled) {
@@ -13479,15 +13630,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 register2(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 = resolve2(dir);
+    const compendium = resolve2(opts.compendium ?? join8(root, WORKSPACE_COMPENDIUM));
+    if (!existsSync(join8(compendium, "contracts")))
       throw new Error(
         `no compendium at ${compendium}; pass --compendium <path to a checkout of plexus-ms/compendium>`
       );
@@ -13515,11 +13666,11 @@ function renderReport(report, s, showCurrent) {
 }
 
 // src/commands/overview.ts
-import { resolve as resolve2 } from "node:path";
-function register2(program2) {
+import { resolve as resolve3 } from "node:path";
+function register3(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, resolve3(dir));
     const s = style(opts.color ?? colorByDefault());
     ctx.result(tree, (t) => renderTree(t, s, ctx.verbose >= 1));
   });
@@ -13562,14 +13713,14 @@ function annotate(dir, s, modules) {
 }
 
 // src/commands/propagate.ts
-import { resolve as resolve4 } from "node:path";
+import { resolve as resolve5 } from "node:path";
 
 // src/commands/ship.ts
-import { resolve as resolve3 } from "node:path";
-function register3(program2) {
+import { resolve as resolve4 } from "node:path";
+function register4(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: resolve4(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 +13743,23 @@ function renderSummary(s, realCommand) {
 }
 
 // src/commands/propagate.ts
-function register4(program2) {
+function register5(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: resolve5(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 join9, resolve as resolve6 } from "node:path";
+function register6(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 = resolve6(dir);
     if (opts.extract) {
-      ctx.result(extractRequirements(await ctx.readFile(join8(compendium, opts.extract))));
+      ctx.result(extractRequirements(await ctx.readFile(join9(compendium, opts.extract))));
       return;
     }
     const check = await checkCompendium(ctx, compendium);
@@ -13622,7 +13773,7 @@ function renderCheck(c) {
 }
 
 // src/commands/index.ts
-var commands = [register2, register, register3, register4, register5];
+var commands = [register3, register2, register4, register5, register6, register];
 
 // src/program.ts
 var { version, description } = createRequire(import.meta.url)("../package.json");
@@ -13631,7 +13782,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 register7 of commands) register7(program2);
   return program2;
 }
 function contextOf2(command) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plexus-ms/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "plx, the Plexus command-line tool: a single-script adapter over @plexus-ms/lib",
   "license": "GPL-3.0-or-later",
   "type": "module",
@@ -22,13 +22,15 @@
   "engines": {
     "node": ">=24"
   },
+  "dependencies": {
+    "@inquirer/prompts": "^8.7.4",
+    "@plexus-ms/lib": "0.4.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",