@plexus-ms/cli 0.8.1 → 0.10.0

package/dist/plx.js

@@ -7567,9 +7567,10 @@ function frontmatterField(text, key) {
 
 // ../lib/dist/bookkeeping.js
 var bumpGalaxyVersion = (text, train) => text.replace(/^(version: )\d+\.\d+\.\d+/m, `$1${train}`);
+var COLLECTION_SOURCE = "plexus-ms/primitives.git";
 function bumpCollectionPin(text, train) {
   const lines = text.split("\n");
-  const start = lines.findIndex((l) => l.includes("plexus-ms/platform.git"));
+  const start = lines.findIndex((l) => l.includes(COLLECTION_SOURCE));
   if (start === -1)
     return text;
   for (let i = start; i < lines.length; i++) {
@@ -7581,8 +7582,13 @@ function bumpCollectionPin(text, train) {
   }
   return lines.join("\n");
 }
-var WORKFLOW_REF = "plexus-ms/ci-cd/.github/workflows/";
-var bumpWorkflowRefs = (text, train) => text.replace(/(plexus-ms\/ci-cd\/\.github\/workflows\/[A-Za-z0-9._-]+)@v?[0-9.]+/g, `$1@${train}`);
+var WORKFLOW_REF = "plexus-ms/primitives/.github/workflows/";
+var bumpWorkflowRefs = (text, train) => text.replace(/(plexus-ms\/primitives\/\.github\/workflows\/[A-Za-z0-9._-]+)@v?[0-9.]+/g, `$1@${train}`);
+var bumpManifestVersion = (text, train) => text.replace(/^(\s*"version":\s*")[^"]*(")/m, `$1${train}$2`);
+var PLX_PIN = "npm:@plexus-ms/cli";
+var bumpPlxPin = (text, train) => text.replace(/("npm:@plexus-ms\/cli"\s*=\s*(?:\{\s*version\s*=\s*)?")[^"]*(")/g, `$1${train}$2`);
+var CONFIG_PIN = "@plexus-ms/config";
+var bumpConfigPin = (text, train) => text.replace(/("@plexus-ms\/config":\s*")(?!workspace:|catalog:)[^"]*(")/g, `$1${train}$2`);
 var stampStandard = (text, train, today2) => setFrontmatterField(setFrontmatterField(text, "version", train), "timestamp", today2);
 var stampChanged = (text, train) => setFrontmatterField(text, "changed", train, { after: "binds" });
 var hasConflictMarkers = (text) => /^<<<<<<< /m.test(text);
@@ -7968,13 +7974,13 @@ async function expand(ctx, root, glob) {
 
 // ../lib/dist/consumers.js
 import { relative } from "node:path";
-function expectedBranch(declaration) {
+function expectedBranch(declaration, answers = {}) {
   if (!declaration)
     return void 0;
   if (declaration.modules.includes("PLX-Platform"))
     return "main";
   if (declaration.modules.includes("PLX-Repo"))
-    return "develop";
+    return answers.publishes_packages === true ? "main" : "develop";
   return void 0;
 }
 var presetSource = (preset) => `gh:plexus-ms/${preset}`;
@@ -7993,11 +7999,12 @@ async function findConsumers(ctx, root, presets) {
       else {
         let consumer = consumers.get(here.path);
         if (!consumer) {
+          const expected = expectedBranch(here.declaration, here.copier?.answers);
           consumer = {
             path: here.path,
             rel: relative(root.path, here.path) || ".",
-            branch: here.git?.branch ?? "?",
-            expected: expectedBranch(here.declaration),
+            branch: expected ?? here.git?.branch ?? "main",
+            expected,
             sites: []
           };
           consumers.set(here.path, consumer);
@@ -8012,13 +8019,11 @@ async function findConsumers(ctx, root, presets) {
   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";
+    const origin = (await ctx.read("git", ["remote", "get-url", "origin"], { cwd: c.path }).catch(() => "")).trim();
+    if (origin === "")
+      c.skipped = "no origin remote";
+    else
+      c.origin = origin;
   }
   return [...consumers.values()];
 }
@@ -8222,14 +8227,20 @@ function compareTrains(a, b) {
 }
 
 // ../lib/dist/train.js
+var PRIMITIVES = "primitives";
 var TRAIN_REPOS = [
-  "platform",
-  "ci-cd",
+  PRIMITIVES,
   "preset-repo-web",
   "preset-app-nextjs",
   "preset-repo-platform",
   "compendium"
 ];
+var PHASES = [[PRIMITIVES], TRAIN_REPOS.filter((r) => r !== PRIMITIVES)];
+var TRAIN_PACKAGES = [
+  { name: "@plexus-ms/cli", dir: "packages/cli" },
+  { name: "@plexus-ms/lib", dir: "packages/lib" },
+  { name: "@plexus-ms/config", dir: "packages/config" }
+];
 var UPSTREAM = "plexus-ms";
 var isTrainVersion = (v) => /^\d+\.\d+\.\d+$/.test(v);
 function nextMinor(version2) {
@@ -8240,7 +8251,7 @@ 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 repos2 = [];
   const all = /* @__PURE__ */ new Set();
   for (const name of TRAIN_REPOS) {
     const path3 = join4(upstream, name);
@@ -8260,11 +8271,12 @@ async function readTrain(ctx, upstream) {
     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 });
+    repos2.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]) };
+  const latest = repos2.map((r) => r.latest);
+  return { repos: repos2, last: latestTag([...all]), skew: latest.some((l) => l !== latest[0]) };
 }
+var phasesOf = (train) => PHASES.map((names) => train.repos.filter((r) => names.includes(r.name)));
 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();
@@ -8277,6 +8289,13 @@ async function preflightRelease(ctx, train) {
       throw new Error(`${name} is ${behind} commit(s) behind origin/main \u2014 pull first, or the tag lands on a stale commit`);
   }
 }
+async function preflightForge(ctx) {
+  try {
+    await ctx.read("gh", ["auth", "status"]);
+  } catch {
+    throw new Error("gh is not logged in (gh auth status failed) \u2014 run gh auth login first");
+  }
+}
 function resolveVersion(train, explicit, propagateOnly) {
   if (explicit !== void 0 && !isTrainVersion(explicit))
     throw new UsageError(`'${explicit}' is not plain semver (X.Y.Z, no v)`);
@@ -8557,8 +8576,41 @@ var PRUNED = /* @__PURE__ */ new Set([
   ".terraform",
   ".gradle"
 ]);
-function overview(ctx, root, options = {}) {
-  return walk(ctx, root, root.replace(/\/+$/, "").split("/").pop() || root, { git: true, ...options });
+var FETCHES = 8;
+async function overview(ctx, root, options = {}) {
+  const opts = { git: true, fetch: false, ...options };
+  const tree = await walk(ctx, root, root.replace(/\/+$/, "").split("/").pop() || root, opts);
+  if (opts.git && opts.fetch)
+    await syncAll(ctx, repos(tree));
+  return tree;
+}
+function repos(dir) {
+  return [...dir.git ? [dir] : [], ...dir.children.flatMap(repos)];
+}
+async function syncAll(ctx, dirs) {
+  const queue = [...dirs];
+  const worker = async () => {
+    for (let dir = queue.shift(); dir; dir = queue.shift())
+      await sync(ctx, dir);
+  };
+  await Promise.all(Array.from({ length: Math.min(FETCHES, queue.length) }, worker));
+}
+async function sync(ctx, dir) {
+  const facet2 = dir.git;
+  if (!facet2)
+    return;
+  try {
+    await ctx.read("git", ["fetch", "--all", "--quiet"], { cwd: dir.path });
+  } catch (error) {
+    dir.problems ??= [];
+    dir.problems.push(`git fetch: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const counts = await git(ctx, dir.path, ["rev-list", "--left-right", "--count", "HEAD...@{upstream}"]);
+  const [ahead, behind] = (counts ?? "").split(/\s+/).map(Number);
+  if (ahead === void 0 || behind === void 0 || Number.isNaN(ahead) || Number.isNaN(behind))
+    return;
+  facet2.ahead = ahead;
+  facet2.behind = behind;
 }
 async function walk(ctx, path3, name, options) {
   const entries = await ctx.readDir(path3);
@@ -8630,9 +8682,18 @@ async function templateFacet(ctx, cwd) {
 // ../lib/dist/propagate.js
 import { join as join8, relative as relative3 } from "node:path";
 var isClean = (s) => s.conflicted.length === 0 && s.failed.length === 0 && s.skipped.length === 0;
-var PREVIEW_BASE = "ship-base";
+var BASE_TAG = "ship-base";
+var trainBranch = (train) => `train/${train}`;
 async function propagate(ctx, workspace, train) {
-  const summary = { train, preview: ctx.dryRun, clean: [], conflicted: [], failed: [], skipped: [] };
+  const summary = {
+    train,
+    preview: ctx.dryRun,
+    clean: [],
+    conflicted: [],
+    failed: [],
+    skipped: [],
+    pulls: []
+  };
   const upstream = join8(workspace, UPSTREAM);
   const tree = await overview(ctx, workspace);
   const upstreamDir = tree.children.find((c) => c.path === upstream);
@@ -8644,64 +8705,63 @@ async function propagate(ctx, workspace, train) {
     ctx.say(`\u26A0 ${c.rel}: ${c.skipped} \u2014 skipped (fix it, then re-run propagate)`);
     summary.skipped.push({ path: c.rel, reason: c.skipped });
   }
-  const active = consumers.filter((c) => !c.skipped);
-  const scratch = ctx.dryRun ? (await ctx.stage(run("mktemp", ["-d"])))?.trim() : void 0;
-  const clones = /* @__PURE__ */ new Map();
-  const cloneOf = async (consumer) => {
-    let clone = clones.get(consumer.path);
-    if (!clone) {
-      clone = join8(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);
-    }
-    return clone;
-  };
-  const previewCommit = (clone, message) => ctx.stage(run("git", ["add", "-A"], { cwd: clone })).then(() => ctx.stage(run("git", [
-    "-c",
-    "commit.gpgsign=false",
-    "-c",
-    "user.name=plx",
-    "-c",
-    "user.email=plx@localhost",
-    "commit",
-    "--quiet",
-    "--no-verify",
-    "--allow-empty",
-    "-m",
-    message
-  ], { cwd: clone })));
+  for (const preset of presets)
+    if (!consumers.some((c) => c.sites.some((s) => s.preset === preset)))
+      ctx.say(`\u2022 no consumers of ${presetSource(preset)} found under ${workspace}`);
+  const scratch = (await ctx.stage(run("mktemp", ["-d"])))?.trim() ?? "";
   try {
-    for (const preset of presets) {
-      const sites = active.flatMap((c) => c.sites.filter((s) => s.preset === preset).map((s) => [c, s]));
-      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, join8(upstream, preset), summary, cloneOf, previewCommit);
-    }
-    await refreshLockfiles(ctx, active, summary, clones);
-    await bumpConsumerRefs(ctx, consumers, train);
+    for (const consumer of consumers) {
+      if (consumer.skipped || !consumer.origin)
+        continue;
+      const clone = join8(scratch, consumer.rel);
+      ctx.say(`\u2192 ${consumer.rel}: clone ${consumer.origin} at ${consumer.branch}`);
+      try {
+        await ctx.stage(run("git", ["clone", "--quiet", "--branch", consumer.branch, consumer.origin, clone]));
+        await ctx.stage(run("git", ["tag", BASE_TAG], { cwd: clone }));
+      } catch (error) {
+        ctx.say(`  \u2717 FAILED \u2014 clone${detail(error)}`);
+        summary.failed.push(consumer.rel);
+        continue;
+      }
+      for (const site of consumer.sites)
+        await updateSite(ctx, consumer, site, clone, upstream, summary);
+      await refreshLockfile(ctx, consumer, clone, summary);
+      await bumpConsumerRefs(ctx, consumer, clone, train);
+      await openPull(ctx, consumer, clone, train, summary);
+    }
   } finally {
     if (scratch)
       await ctx.stage(run("rm", ["-rf", scratch]));
   }
   return summary;
 }
-async function updateSite(ctx, consumer, site, localPreset, summary, cloneOf, previewCommit) {
-  let repo = consumer.path;
-  let target = site.path;
+var previewCommit = (ctx, clone, message) => ctx.stage(run("git", ["add", "-A"], { cwd: clone })).then(() => ctx.stage(run("git", [
+  "-c",
+  "commit.gpgsign=false",
+  "-c",
+  "user.name=plx",
+  "-c",
+  "user.email=plx@localhost",
+  "commit",
+  "--quiet",
+  "--no-verify",
+  "--allow-empty",
+  "-m",
+  message
+], { cwd: clone })));
+async function updateSite(ctx, consumer, site, clone, upstream, summary) {
+  const target = join8(clone, relative3(consumer.path, site.path));
+  const localPreset = join8(upstream, site.preset);
   try {
     if (ctx.dryRun) {
       ctx.say(`\u2192 ${site.rel}: copier update (preview from ${localPreset}@main)`);
-      repo = await cloneOf(consumer);
-      target = join8(repo, relative3(consumer.path, site.path));
-      const answers = await ctx.readFile(join8(site.path, ANSWERS_FILE));
+      const answers = await ctx.readFile(join8(target, ANSWERS_FILE));
       await ctx.stage(write(join8(target, ANSWERS_FILE), answers.replace(/^_src_path: .*$/m, `_src_path: ${localPreset}`)));
-      await previewCommit(repo, `plx preview: ${site.rel} reads ${localPreset} from the local checkout`);
+      await previewCommit(ctx, clone, `plx preview: ${site.rel} reads ${localPreset} from the local checkout`);
       await ctx.stage(run("mise", copierVia(["update", "--skip-answered", "--trust", "--defaults", "--skip-tasks", "--vcs-ref", "main"]), { cwd: target }));
     } else {
       ctx.say(`\u2192 ${site.rel}: copier update`);
-      const args = ["update", "--skip-answered", "--trust", ...ctx.yes ? ["--defaults"] : []];
+      const args = ["update", "--skip-answered", "--trust", "--skip-tasks", ...ctx.yes ? ["--defaults"] : []];
       await ctx.apply([run("mise", copierVia(args), { cwd: target, interactive: true })]);
     }
   } catch (error) {
@@ -8709,17 +8769,17 @@ async function updateSite(ctx, consumer, site, localPreset, summary, cloneOf, pr
     summary.failed.push(site.rel);
     return;
   }
-  const status = await ctx.read("git", ["status", "--porcelain"], { cwd: repo });
+  const status = await ctx.read("git", ["status", "--porcelain", "--", "."], { cwd: target });
   let conflict = hasUnmergedEntries(status);
-  const changed = (await ctx.read("git", ["diff", "--name-only"], { cwd: repo })).split("\n").filter(Boolean);
+  const changed = (await ctx.read("git", ["diff", "--name-only", "--relative", "--", "."], { cwd: target })).split("\n").filter(Boolean);
   for (const f of changed) {
-    const text = await ctx.readFile(join8(repo, f)).catch(() => "");
+    const text = await ctx.readFile(join8(target, f)).catch(() => "");
     if (hasConflictMarkers(text))
       conflict = true;
   }
   await syncSiteMarker(ctx, site, target);
   if (conflict) {
-    ctx.say("  \u2717 CONFLICTS \u2014 resolve the <<<<<<< markers, then git add:");
+    ctx.say("  \u2717 CONFLICTS \u2014 committed with their <<<<<<< markers, to resolve in the pull request:");
     summary.conflicted.push(site.rel);
   } else {
     ctx.say("  \u2713 merged clean:");
@@ -8728,7 +8788,7 @@ async function updateSite(ctx, consumer, site, localPreset, summary, cloneOf, pr
   for (const line of status.split("\n").filter(Boolean))
     ctx.say(`    ${line}`);
   if (ctx.dryRun)
-    await previewCommit(repo, `plx preview: ${site.rel} updated`);
+    await previewCommit(ctx, clone, `plx preview: ${site.rel} updated`);
 }
 async function syncSiteMarker(ctx, site, target) {
   const marker = await ctx.readFile(join8(target, MARKER_FILE)).catch(() => void 0);
@@ -8741,55 +8801,129 @@ async function syncSiteMarker(ctx, site, target) {
   if (synced === marker)
     return;
   ctx.say(`  marker: plexus \u2192 ${commit} in ${site.rel}/${MARKER_FILE}`);
-  const step = write(join8(target, MARKER_FILE), synced);
-  if (ctx.dryRun)
-    await ctx.stage(step);
-  else
-    await ctx.apply([step]);
+  await ctx.stage(write(join8(target, MARKER_FILE), synced));
 }
-async function refreshLockfiles(ctx, consumers, summary, clones) {
+async function refreshLockfile(ctx, consumer, clone, summary) {
+  if (await ctx.readFile(join8(clone, "pnpm-workspace.yaml")).catch(() => void 0) === void 0)
+    return;
   const manifests = ["*package.json", "pnpm-workspace.yaml"];
-  for (const c of consumers) {
-    if (await ctx.readFile(join8(c.path, "pnpm-workspace.yaml")).catch(() => void 0) === void 0)
-      continue;
-    const repo = ctx.dryRun ? clones.get(c.path) : c.path;
-    if (!repo)
-      continue;
-    const range = ctx.dryRun ? [PREVIEW_BASE] : [];
-    const unchanged = await ctx.read("git", ["diff", "--quiet", ...range, "--", ...manifests], { cwd: repo }).then(() => true).catch(() => false);
-    if (unchanged)
-      continue;
-    ctx.say(`\u2192 ${c.rel}: pnpm install (manifests changed)`);
-    try {
-      await ctx.apply([run("mise", ["exec", "--", "pnpm", "install", "--reporter=silent"], { cwd: c.path })]);
-    } catch (error) {
-      ctx.say(`  \u2717 pnpm install failed${detail(error)}`);
-      summary.failed.push(`${c.rel}/pnpm-lock.yaml`);
-    }
+  const unchanged = await ctx.read("git", ["diff", "--quiet", BASE_TAG, "--", ...manifests], { cwd: clone }).then(() => true).catch(() => false);
+  if (unchanged)
+    return;
+  ctx.say(`\u2192 ${consumer.rel}: pnpm install (manifests changed)`);
+  try {
+    await ctx.apply([run("mise", ["exec", "--", "pnpm", "install", "--reporter=silent"], { cwd: clone })]);
+  } catch (error) {
+    ctx.say(`  \u2717 pnpm install failed${detail(error)}`);
+    summary.failed.push(`${consumer.rel}/pnpm-lock.yaml`);
   }
 }
-async function bumpConsumerRefs(ctx, consumers, train) {
-  for (const c of consumers) {
-    const dir = join8(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)
+async function bumpConsumerRefs(ctx, consumer, clone, train) {
+  const dir = join8(clone, ".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();
+  for (const f of files) {
+    const text = await ctx.readFile(join8(dir, f));
+    if (!text.includes(WORKFLOW_REF))
       continue;
-    if (c.skipped) {
-      ctx.say(`\u26A0 ${c.rel}: workflow refs not bumped (skipped above)`);
+    const bumped = bumpWorkflowRefs(text, train);
+    if (bumped === text)
       continue;
-    }
-    for (const f of files) {
-      const text = await ctx.readFile(join8(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(join8(dir, f), bumped)]);
-    }
+    ctx.say(`\u2192 ${consumer.rel}: ${f} workflow refs \u2192 @${train}`);
+    await ctx.stage(write(join8(dir, f), bumped));
+  }
+}
+async function openPull(ctx, consumer, clone, train, summary) {
+  const branch = trainBranch(train);
+  if (ctx.dryRun) {
+    ctx.say(`  (preview) ${consumer.rel}: would commit, push ${branch} and open a pull request against ${consumer.branch}`);
+    return;
+  }
+  if ((await ctx.read("git", ["status", "--porcelain"], { cwd: clone })).trim() === "") {
+    ctx.say(`\u2022 ${consumer.rel}: nothing changed \u2014 no pull request`);
+    return;
   }
+  const head = `${consumer.origin} ${branch}`;
+  try {
+    await ctx.apply([
+      run("git", ["add", "-A"], { cwd: clone }),
+      run("git", ["commit", "--quiet", "--no-verify", "-m", `chore: train ${train}`], { cwd: clone })
+    ]);
+    await ctx.read("git", ["fetch", "--quiet", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`], {
+      cwd: clone
+    }).catch(() => "");
+    await ctx.apply([
+      run("git", ["push", "--quiet", "--force-with-lease", "origin", `HEAD:refs/heads/${branch}`], { cwd: clone })
+    ]);
+  } catch (error) {
+    ctx.say(`  \u2717 FAILED \u2014 push to ${head}${detail(error)}`);
+    summary.failed.push(consumer.rel);
+    return;
+  }
+  const existing = (await ctx.read("gh", [
+    "pr",
+    "list",
+    "--head",
+    branch,
+    "--base",
+    consumer.branch,
+    "--state",
+    "open",
+    "--json",
+    "url",
+    "--jq",
+    ".[0].url"
+  ], { cwd: clone }).catch(() => "")).trim();
+  if (existing) {
+    ctx.say(`\u2022 ${consumer.rel}: pull request updated: ${existing}`);
+    summary.pulls.push(existing);
+    return;
+  }
+  const sites = consumer.sites.map((s) => s.rel);
+  const conflicted = sites.filter((s) => summary.conflicted.includes(s));
+  const body2 = [
+    `Train ${train} (\xA7 1.5 PLX): \`copier update\` at ${sites.join(", ")}, the marker, the lockfile where manifests moved, and the workflow refs.`,
+    conflicted.length > 0 ? `Conflicts to resolve, committed with their markers: ${conflicted.join(", ")}.` : "Merged clean at every site.",
+    "Opened by `plx ship`."
+  ].join("\n\n");
+  try {
+    await ctx.apply([
+      run("gh", [
+        "pr",
+        "create",
+        "--base",
+        consumer.branch,
+        "--head",
+        branch,
+        "--title",
+        `chore: train ${train}`,
+        "--body",
+        body2
+      ], { cwd: clone })
+    ]);
+  } catch (error) {
+    ctx.say(`  \u2717 FAILED \u2014 pull request${detail(error)}`);
+    summary.failed.push(consumer.rel);
+    return;
+  }
+  const url = (await ctx.read("gh", [
+    "pr",
+    "list",
+    "--head",
+    branch,
+    "--base",
+    consumer.branch,
+    "--state",
+    "open",
+    "--json",
+    "url",
+    "--jq",
+    ".[0].url"
+  ], {
+    cwd: clone
+  }).catch(() => "")).trim();
+  ctx.say(`\u2022 ${consumer.rel}: pull request opened${url ? `: ${url}` : ""}`);
+  summary.pulls.push(url || `${consumer.rel} ${branch}`);
 }
 var detail = (error) => {
   const message = error instanceof Error ? error.message : String(error);
@@ -8963,59 +9097,118 @@ async function preflightSelf(ctx, running) {
 
 // ../lib/dist/ship.js
 import { join as join10 } from "node:path";
+var DEFAULT_WAIT = { interval: 15e3, timeout: 20 * 6e4 };
 async function ship(ctx, options) {
   const upstream = join10(options.workspace, UPSTREAM);
   const propagateOnly = options.propagateOnly ?? false;
   if (options.plx)
     await preflightSelf(ctx, options.plx);
   const train = await readTrain(ctx, upstream);
-  if (!propagateOnly)
+  await preflightForge(ctx);
+  if (!propagateOnly) {
     await preflightRelease(ctx, train);
+    await preflightImmutable(ctx, train);
+  }
   const next = resolveVersion(train, options.train, propagateOnly);
   if (!propagateOnly)
-    await release(ctx, train, next, options.today ?? today());
+    await release(ctx, train, next, options.today ?? today(), { ...DEFAULT_WAIT, ...options.wait });
   const summary = await propagate(ctx, options.workspace, next);
   return { ...summary, released: !propagateOnly };
 }
-async function release(ctx, train, next, today2) {
+async function preflightImmutable(ctx, train) {
+  for (const repo of train.repos) {
+    const newest = (await ctx.read("gh", ["api", "repos/{owner}/{repo}/releases?per_page=1", "--jq", ".[0].immutable"], { cwd: repo.path }).catch(() => "")).trim();
+    if (newest === "false")
+      throw new Error(mutableRelease(`${repo.name}: its newest GitHub release is not immutable`));
+  }
+}
+var mutableRelease = (what) => `${what} \u2014 enable immutable releases on the plexus-ms organisation (Settings \u2192 General \u2192 Releases); existing releases stay as they are (never delete one: a deleted immutable release burns its number)`;
+async function release(ctx, train, next, today2, wait) {
   ctx.say(`\u2192 train ${train.last ?? "none"} \u2192 ${next}`);
   for (const repo of train.repos) {
     if (repo.pending.length === 0)
       ctx.say(`  ${repo.name}: no changes since ${repo.latest} \u2014 tag only`);
     else {
       ctx.say(`  ${repo.name} (since ${repo.latest ?? "the beginning"}):`);
-      for (const line of repo.pending)
+      for (const line of repo.pending.slice(0, PENDING_SHOWN))
         ctx.say(`    ${line}`);
+      if (repo.pending.length > PENDING_SHOWN)
+        ctx.say(`    \u2026 and ${repo.pending.length - PENDING_SHOWN} more`);
     }
   }
-  if (!await ctx.confirm(`tag all ${train.repos.length} repos as ${next} and push?`))
+  if (!await ctx.confirm(`tag all ${train.repos.length} repos as ${next}, release them and push?`))
     throw new Error("aborted");
+  const [one = [], two = []] = phasesOf(train);
   try {
-    const plan = await planBookkeeping(ctx, train, next, today2);
-    await ctx.apply(plan);
-    for (const repo of train.repos) {
-      const tagged = await ctx.read("git", ["rev-parse", "-q", "--verify", `refs/tags/${next}`], { cwd: repo.path }).then(() => true).catch(() => false);
-      if (tagged)
-        ctx.say(`\u2022 ${repo.name}: already tagged ${next}`);
-      else
-        await ctx.apply([run("git", ["tag", "-a", next, "-m", `train ${next}`], { cwd: repo.path })]);
-      await ctx.apply([run("git", ["push", "origin", "main", next], { cwd: repo.path })]);
-    }
+    await releasePhase(ctx, train, one, next, today2);
+    await awaitPublished(ctx, next, wait);
+    await releasePhase(ctx, train, two, next, today2);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(`${message}
-\u2717 ship stopped during the release; re-run with --train ${next} to finish it (tagged repos are skipped)`);
+\u2717 ship stopped during the release; re-run with --train ${next} to finish it (tagged repos and existing releases are skipped; if the registry already has ${next}, update plx first: it is the same code, built from the commit phase one tagged)`);
   }
 }
-async function planBookkeeping(ctx, train, next, today2) {
+var PENDING_SHOWN = 20;
+async function releasePhase(ctx, train, repos2, next, today2) {
+  ctx.say(`\u2192 phase: ${repos2.map((r) => r.name).join(", ")}`);
+  await ctx.apply(await planBookkeeping(ctx, train, repos2, next, today2));
+  for (const repo of repos2)
+    await tagAndRelease(ctx, repo, next);
+}
+async function tagAndRelease(ctx, repo, next) {
+  const tagged = await ctx.read("git", ["rev-parse", "-q", "--verify", `refs/tags/${next}`], { cwd: repo.path }).then(() => true).catch(() => false);
+  if (tagged)
+    ctx.say(`\u2022 ${repo.name}: already tagged ${next}`);
+  else
+    await ctx.apply([run("git", ["tag", "-a", next, "-m", `train ${next}`], { cwd: repo.path })]);
+  await ctx.apply([run("git", ["push", "origin", "main", next], { cwd: repo.path })]);
+  const released = await ctx.read("gh", ["release", "view", next], { cwd: repo.path }).then(() => true).catch(() => false);
+  if (released) {
+    ctx.say(`\u2022 ${repo.name}: release ${next} exists`);
+    return;
+  }
+  await ctx.apply([
+    run("gh", ["release", "create", next, "--verify-tag", "--generate-notes", "--title", next], { cwd: repo.path })
+  ]);
+  if (ctx.dryRun)
+    return;
+  const immutable = (await ctx.read("gh", ["api", `repos/{owner}/{repo}/releases/tags/${next}`, "--jq", ".immutable"], {
+    cwd: repo.path
+  })).trim();
+  if (immutable !== "true")
+    throw new Error(mutableRelease(`${repo.name}: release ${next} was created mutable, and its tag can still move`));
+}
+async function awaitPublished(ctx, next, wait) {
+  const names = TRAIN_PACKAGES.map((p) => p.name);
+  const list2 = names.map((n) => `${n}@${next}`).join(", ");
+  if (ctx.dryRun) {
+    ctx.say(`\u23F3 [dry-run] would wait for ${list2} on npm (${PRIMITIVES}' release workflow publishes them)`);
+    return;
+  }
+  ctx.say(`\u23F3 waiting for ${list2} on npm (${PRIMITIVES}' release workflow publishes them)`);
+  const started = Date.now();
+  let missing = [...names];
+  for (; ; ) {
+    const still = [];
+    for (const name of missing) {
+      const seen = (await ctx.read("npm", ["view", `${name}@${next}`, "version"]).catch(() => "")).trim();
+      if (seen !== next)
+        still.push(name);
+    }
+    missing = still;
+    if (missing.length === 0)
+      break;
+    if (Date.now() - started >= wait.timeout)
+      throw new Error(`${missing.join(", ")} not on npm at ${next} after ${Math.round(wait.timeout / 6e4)} min \u2014 check the release workflow (gh run list -R plexus-ms/${PRIMITIVES})`);
+    await new Promise((resolve10) => setTimeout(resolve10, wait.interval));
+  }
+  ctx.say(`  \u2713 ${list2} on npm`);
+}
+async function planBookkeeping(ctx, train, repos2, next, today2) {
   const plan = [];
   const touched = /* @__PURE__ */ new Set();
-  const repo = (name) => {
-    const r = train.repos.find((r2) => r2.name === name);
-    if (!r)
-      throw new Error(`${name} is not a train repo`);
-    return r;
-  };
+  const repo = (name) => repos2.find((r) => r.name === name);
   const edit = async (r, rel, what, transform) => {
     const path3 = join10(r.path, rel);
     const text = await ctx.readFile(path3).catch(() => void 0);
@@ -9028,23 +9221,36 @@ async function planBookkeeping(ctx, train, next, today2) {
     plan.push(write(path3, edited));
     touched.add(r);
   };
-  await edit(repo("platform"), "ansible/galaxy.yml", `version \u2192 ${next}`, (t) => bumpGalaxyVersion(t, next));
-  await edit(repo("preset-repo-platform"), "template/requirements.yml", `plexus.platform pin \u2192 ${next}`, (t) => bumpCollectionPin(t, next));
-  for (const r of train.repos) {
-    const files = await ctx.read("git", ["grep", "-l", WORKFLOW_REF, "--", "*.yml", "*.yaml", "*.jinja"], { cwd: r.path }).catch(() => "");
-    for (const f of files.split("\n").filter(Boolean))
-      await edit(r, f, `ci-cd refs \u2192 @${next}`, (t) => bumpWorkflowRefs(t, next));
+  const grep = async (r, needle, pathspecs) => (await ctx.read("git", ["grep", "-l", needle, "--", ...pathspecs], { cwd: r.path }).catch(() => "")).split("\n").filter(Boolean);
+  const primitives = repo(PRIMITIVES);
+  if (primitives) {
+    await edit(primitives, "ansible/galaxy.yml", `version \u2192 ${next}`, (t) => bumpGalaxyVersion(t, next));
+    for (const p of TRAIN_PACKAGES)
+      await edit(primitives, `${p.dir}/package.json`, `${p.name} \u2192 ${next}`, (t) => bumpManifestVersion(t, next));
+  }
+  const platformPreset = repo("preset-repo-platform");
+  if (platformPreset)
+    await edit(platformPreset, "template/requirements.yml", `plexus.platform pin \u2192 ${next}`, (t) => bumpCollectionPin(t, next));
+  for (const r of repos2) {
+    for (const f of await grep(r, WORKFLOW_REF, ["*.yml", "*.yaml", "*.jinja"]))
+      await edit(r, f, `workflow refs \u2192 @${next}`, (t) => bumpWorkflowRefs(t, next));
+    for (const f of await grep(r, PLX_PIN, ["*.toml", "*.toml.jinja"]))
+      await edit(r, f, `plx pin \u2192 ${next}`, (t) => bumpPlxPin(t, next));
+    for (const f of await grep(r, `"${CONFIG_PIN}"`, ["*package.json", "*package.json.jinja"]))
+      await edit(r, f, `${CONFIG_PIN} pin \u2192 ${next}`, (t) => bumpConfigPin(t, next));
   }
   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(join10(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(() => "") : "";
-    if (extractRequirements(text).join("\n") === extractRequirements(previous).join("\n"))
-      continue;
-    await edit(comp, page, `requirements changed since ${comp.latest ?? "the beginning"} \u2192 changed: ${next}`, (t) => stampChanged(t, next));
+  if (comp) {
+    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(join10(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(() => "") : "";
+      if (extractRequirements(text).join("\n") === extractRequirements(previous).join("\n"))
+        continue;
+      await edit(comp, page, `requirements changed since ${comp.latest ?? "the beginning"} \u2192 changed: ${next}`, (t) => stampChanged(t, next));
+    }
   }
   for (const r of train.repos) {
     if (!touched.has(r))
@@ -14035,9 +14241,9 @@ function renderReport(report, s, showCurrent) {
 // src/commands/overview.ts
 import { resolve as resolve6 } from "node:path";
 function register6(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) => {
+  program2.command("overview").description("map the git repos, copier templates and projects, and Plexus units under a directory").argument("[dir]", "directory to map", ".").option("-s, --sync", "fetch every repo first, to show branches behind (or ahead of) their upstream").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, resolve6(dir));
+    const tree = await overview(ctx, resolve6(dir), { fetch: opts.sync ?? false });
     const s = style(opts.color ?? colorByDefault());
     ctx.result(tree, (t) => renderTree(t, s, ctx.verbose >= 1));
   });
@@ -14061,9 +14267,10 @@ function renderTree(root, s, modules) {
 function annotate(dir, s, modules) {
   const tags = [];
   if (dir.git) {
-    const { branch, dirty, tag, remote } = dir.git;
+    const { branch, dirty, tag, remote, ahead, behind } = dir.git;
+    const drift = `${behind ? ` \u2193${behind}` : ""}${ahead ? ` \u2191${ahead}` : ""}`;
     const rest = `${tag ? ` ${tag}` : ""}${remote ? ` \u2192 ${remote}` : ""}]`;
-    tags.push(`${s.ok(`[${branch}`)}${dirty ? s.warn("*") : ""}${s.ok(rest)}`);
+    tags.push(`${s.ok(`[${branch}`)}${dirty ? s.warn("*") : ""}${drift ? s.warn(drift) : ""}${s.ok(rest)}`);
   }
   if (dir.template) tags.push(s.note(`[template ${dir.template.tag ?? "untagged"}]`));
   if (dir.copier) {
@@ -14085,7 +14292,9 @@ import { resolve as resolve8 } from "node:path";
 // src/commands/ship.ts
 import { resolve as resolve7 } from "node:path";
 function register7(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) => {
+  program2.command("ship").description(
+    "release the train: tag and release every train repo identically, then open a pull request per 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: resolve7(dir), train: opts.train, plx: version });
     ctx.result(result, (r) => renderSummary(r, `plx -y ship --train ${r.train} ${dir}`));
@@ -14098,12 +14307,13 @@ function renderSummary(s, realCommand) {
   for (const p of s.conflicted) lines.push(`  \u2717 conflicts:  ${p}`);
   for (const p of s.failed) lines.push(`  \u2717 failed:     ${p}`);
   for (const { path: path3, reason } of s.skipped) lines.push(`  \u26A0 skipped:    ${path3} (${reason})`);
+  for (const url of s.pulls) lines.push(`  \u2192 pull:       ${url}`);
   const clean = isClean(s);
   if (s.preview) {
     lines.push("  (preview only \u2014 nothing was changed)");
     if (clean) lines.push(`\u2713 dry run clean \u2014 run it for real: ${realCommand}`);
   } else if (clean) {
-    lines.push("\u2713 done \u2014 review consumer diffs, commit (web repos on develop, platform repos on main), push");
+    lines.push("\u2713 done \u2014 review and merge the pull requests");
   }
   if (!clean) lines.push("\u2717 needs attention \u2014 see above; fix the consumer, then re-run propagate");
   return lines.join("\n");
@@ -14111,7 +14321,7 @@ function renderSummary(s, realCommand) {
 
 // src/commands/propagate.ts
 function register8(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) => {
+  program2.command("propagate").description("copier-update every consumer of the presets to the current train, as one pull request per consumer").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: resolve8(dir), train: opts.train, propagateOnly: true, plx: version });
     ctx.result(result, (r) => renderSummary(r, `plx -y propagate --train ${r.train} ${dir}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plexus-ms/cli",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "plx, the Plexus command-line tool: a single-script adapter over @plexus-ms/lib",
   "license": "GPL-3.0-or-later",
   "type": "module",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.7.4",
-    "@plexus-ms/lib": "0.8.1",
+    "@plexus-ms/lib": "0.10.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {