@plexus-ms/cli 0.5.0 → 0.7.0

package/dist/plx.js

@@ -7754,7 +7754,7 @@ function realIo(prompt) {
     stdout: process.stdout,
     stderr: process.stderr,
     prompt: prompt && isInteractive() ? prompt : void 0,
-    exec: (command, args, options = {}) => new Promise((resolve9, reject) => {
+    exec: (command, args, options = {}) => new Promise((resolve10, reject) => {
       const child = spawn(command, args, {
         cwd: options.cwd,
         env: options.env,
@@ -7777,7 +7777,7 @@ function realIo(prompt) {
       child.on("error", reject);
       child.on("close", (code) => {
         if (code === 0)
-          resolve9(stdout);
+          resolve10(stdout);
         else
           reject(new ExecError(render(command, args), code, stderr));
       });
@@ -7808,8 +7808,6 @@ function describe(step) {
   switch (step.kind) {
     case "run":
       return `$ ${step.cwd ? `(cd ${step.cwd} && ` : ""}${render(step.command, step.args)}${step.cwd ? ")" : ""}`;
-    case "ssh":
-      return `$ ${render("ssh", [step.host, "bash", "-s"])} <<'EOF'`;
     case "write":
       return `> ${step.path} (${Buffer.byteLength(step.content)} bytes)`;
   }
@@ -7818,9 +7816,6 @@ function body(step) {
   switch (step.kind) {
     case "run":
       return step.input;
-    case "ssh":
-      return `${step.script.trimEnd()}
-EOF`;
     case "write":
       return step.content;
   }
@@ -8110,8 +8105,6 @@ var Context = class {
     switch (step.kind) {
       case "run":
         return this.io.exec(step.command, step.args, { cwd: step.cwd, input: step.input, inherit });
-      case "ssh":
-        return this.io.exec("ssh", [step.host, "bash", "-s"], { input: step.script, inherit });
       case "write":
         await this.io.writeFile(step.path, step.content);
         return void 0;
@@ -8133,6 +8126,8 @@ function indent(text) {
 var import_yaml3 = __toESM(require_dist(), 1);
 var ANSWERS_FILE = ".copier-answers.yml";
 var TEMPLATE_FILES = ["copier.yml", "copier.yaml"];
+var COPIER_VERSION = "9.19.1";
+var copierVia = (args) => ["exec", `copier@${COPIER_VERSION}`, "--", "copier", ...args];
 function parseAnswers(text) {
   const data = (0, import_yaml3.parse)(text);
   if (data === null || typeof data !== "object" || Array.isArray(data))
@@ -8145,8 +8140,9 @@ function parseAnswers(text) {
   };
 }
 
-// ../lib/dist/deployTargets.js
-var import_yaml4 = __toESM(require_dist(), 1);
+// ../lib/dist/deploy.js
+import { randomBytes } from "node:crypto";
+import { tmpdir } from "node:os";
 import { join as join5 } from "node:path";
 
 // ../lib/dist/train.js
@@ -8289,7 +8285,174 @@ pass the version explicitly (--train ${train.last}) to finish the half-tagged tr
 var UsageError = class extends Error {
 };
 
+// ../lib/dist/deploy.js
+var PLACEHOLDER = /\$\{PLEXUS_DEPLOYMENT_IMAGE(:[^}]*)?\}/g;
+var INCOMING = ".incoming";
+function renderCompose(text, image, path3) {
+  const has = PLACEHOLDER.test(text);
+  PLACEHOLDER.lastIndex = 0;
+  if (image) {
+    if (!has)
+      throw new UsageError(`${path3} does not reference \${PLEXUS_DEPLOYMENT_IMAGE}; an image ref was given but nothing would use it (\xA7 3 PLX-App)`);
+    return text.replace(PLACEHOLDER, image);
+  }
+  if (has)
+    throw new UsageError(`${path3} references \${PLEXUS_DEPLOYMENT_IMAGE} but no image ref was given`);
+  return text;
+}
+var q = (word) => `'${word.replaceAll("'", "'\\''")}'`;
+var Remote = class {
+  socket = join5(tmpdir(), `plx-deploy-${randomBytes(4).toString("hex")}.sock`);
+  ctx;
+  host;
+  constructor(ctx, host) {
+    this.ctx = ctx;
+    this.host = host;
+  }
+  args(command) {
+    return [
+      "-o",
+      "ControlMaster=auto",
+      "-o",
+      `ControlPath=${this.socket}`,
+      "-o",
+      "ControlPersist=60",
+      "-o",
+      "StrictHostKeyChecking=accept-new",
+      this.host,
+      "--",
+      command
+    ];
+  }
+  /** An effect on the host: narrated, performed unless --dry-run. */
+  exec(command, input) {
+    return this.ctx.apply([run("ssh", this.args(command), input === void 0 ? {} : { input })]);
+  }
+  /**
+   * A read from the host: its output, or undefined under --dry-run, where no
+   * host is reached. A read that is a step of the procedure (`show`) is
+   * printed by the dry run like an effect, so the operator copies it too.
+   */
+  async read(command, show = false) {
+    if (this.ctx.dryRun) {
+      this.ctx.say(`${show ? "[dry-run] $" : "?"} ssh ${this.host} -- ${q(command)}`, show ? 0 : 1);
+      return void 0;
+    }
+    return (await this.ctx.read("ssh", this.args(command))).trimEnd();
+  }
+  /** A check on the host: whether the command succeeds, or undefined under --dry-run. */
+  async test(command, show = false) {
+    try {
+      return await this.read(command, show) === void 0 ? void 0 : true;
+    } catch (error) {
+      if (error instanceof ExecError)
+        return false;
+      throw error;
+    }
+  }
+  /** Close the shared connection; nothing to close when no call was made. */
+  close() {
+    return this.ctx.apply([run("ssh", ["-o", `ControlPath=${this.socket}`, "-O", "exit", this.host])]);
+  }
+};
+async function deploy(ctx, options) {
+  const { host, tenant, app } = options;
+  const dir = options.dir ?? ".";
+  const image = options.image || void 0;
+  const appDir = options.appDir || `/opt/stacks/${tenant}/${app}`;
+  const source = options.source || `apps/${app}`;
+  const retries = options.retries ?? 30;
+  let compose;
+  let text = "";
+  for (const candidate of [`${source}/docker/compose.yaml`, `${source}/compose.yaml`]) {
+    try {
+      text = await ctx.readFile(join5(dir, candidate));
+      compose = candidate;
+      break;
+    } catch {
+    }
+  }
+  if (compose === void 0)
+    throw new UsageError(`no compose.yaml under ${source}; run from the app's source repo (\xA7 2 PLX-App)`);
+  const rendered = renderCompose(text, image, compose);
+  ctx.say(`\u2192 deploying ${image ?? "<image pinned in compose.yaml>"}`);
+  ctx.say(`  host:    ${host}`);
+  ctx.say(`  dir:     ${appDir}`);
+  ctx.say(`  compose: ${compose}`);
+  ctx.say(`  health:  ${options.healthUrl || "<resolved on host>"}`);
+  const remote = new Remote(ctx, host);
+  const D = q(appDir);
+  const dc = `cd ${D} && docker compose`;
+  const dci = `${dc} --project-directory . -f ${INCOMING}/compose.yaml`;
+  const liveImage = `${dc} ps -q web 2>/dev/null | head -1 | xargs -r docker inspect --format '{{.Config.Image}}' 2>/dev/null || true`;
+  const result = { host, appDir, compose, image, healthy: false, rolledBack: false };
+  let staged = false;
+  try {
+    await remote.exec(`rm -rf ${D}/${INCOMING} && mkdir -p ${D}/${INCOMING} && cat > ${D}/${INCOMING}/compose.yaml`, rendered);
+    staged = true;
+    result.previous = await remote.read(liveImage) || void 0;
+    ctx.say(`  previous: ${result.previous ?? (ctx.dryRun ? "<read on host>" : "<none>")}`);
+    await remote.exec(`${dci} pull`);
+    const migrate = await remote.test(`${dci} --profile migrate config --services 2>/dev/null | grep -qx migrate`);
+    if (migrate === void 0)
+      ctx.say("  (if compose.yaml declares a migrate service:)");
+    if (migrate !== false)
+      await remote.exec(`${dci} run --rm migrate </dev/null`);
+    const hadPrev = await remote.test(`test -f ${D}/compose.yaml`);
+    if (hadPrev !== false)
+      await remote.exec(`cd ${D} && cp -p compose.yaml ${INCOMING}/compose.yaml.prev`);
+    await remote.exec(`cd ${D} && mv ${INCOMING}/compose.yaml compose.yaml`);
+    await remote.exec(`${dc} up -d`);
+    const url = options.healthUrl || await resolveHealthUrl(remote, D, dc, ctx);
+    const poll = `cd ${D} && for _ in $(seq 1 ${retries}); do curl -fsS --max-time 5 -o /dev/null ${q(url)} && exit 0; sleep 2; done; exit 1`;
+    const started = Date.now();
+    const healthy = await remote.test(poll, true);
+    if (healthy !== false) {
+      result.live = await remote.read(liveImage) || image;
+      result.healthy = true;
+      if (ctx.dryRun)
+        ctx.say("  (on failure: restore the previous compose.yaml, up -d, poll again)");
+      else
+        ctx.done(`${result.live ?? "the app"} is live and healthy`);
+      return result;
+    }
+    ctx.say(`\u2717 healthcheck failed after ${Math.round((Date.now() - started) / 1e3)}s; last lines from the app:`);
+    const logs = await remote.read(`${dc} logs --no-color --tail 50 web 2>&1 || true`);
+    if (logs)
+      ctx.say(logs.replace(/^/gm, "    "));
+    const differs = hadPrev && await remote.test(`cd ${D} && ! cmp -s compose.yaml ${INCOMING}/compose.yaml.prev`);
+    if (!differs) {
+      ctx.done("nothing to roll back to (first deploy, or the same run shape re-deployed); manual intervention needed", false);
+      return result;
+    }
+    await remote.exec(`cd ${D} && cp -p ${INCOMING}/compose.yaml.prev compose.yaml`);
+    ctx.say(`\u21A9 rolling back to ${result.previous ?? "the previous compose.yaml"}`);
+    await remote.exec(`${dc} up -d`);
+    result.rolledBack = true;
+    if (await remote.test(poll)) {
+      result.live = result.previous;
+      ctx.done(`rolled back to ${result.previous ?? "the previous compose.yaml"}`);
+    } else {
+      ctx.done("rollback also unhealthy; manual intervention needed", false);
+    }
+    return result;
+  } finally {
+    if (staged)
+      await remote.exec(`rm -rf ${D}/${INCOMING}`).catch(() => void 0);
+    await remote.close().catch(() => void 0);
+  }
+}
+async function resolveHealthUrl(remote, D, dc, ctx) {
+  const port = await remote.read(`sed -n 's/^PLEXUS_LOOPBACK_PORT=//p' ${D}/.env 2>/dev/null | tail -1`);
+  const path3 = await remote.read(`${dc} ps -q web 2>/dev/null | head -1 | xargs -r docker inspect --format '{{ index .Config.Labels "plexus.healthz" }}' 2>/dev/null || true`);
+  const url = ctx.dryRun ? "http://127.0.0.1:${PLEXUS_LOOPBACK_PORT:-3000}${plexus.healthz:-/healthz}" : `http://127.0.0.1:${port || "3000"}${path3 || "/healthz"}`;
+  ctx.say(`  health:   ${url}`);
+  return url;
+}
+
 // ../lib/dist/deployTargets.js
+var import_yaml4 = __toESM(require_dist(), 1);
+import { join as join6 } from "node:path";
 var VARS_DIRS = ["group_vars", "host_vars"];
 function parseInventoryFile(path3, text) {
   const data = (0, import_yaml4.parse)(text);
@@ -8318,7 +8481,7 @@ async function readDeployTargets(ctx, inventory) {
   const files = [];
   let found = false;
   for (const sub of VARS_DIRS) {
-    const dir = join5(inventory, sub);
+    const dir = join6(inventory, sub);
     const entries = await ctx.readDir(dir).catch(() => void 0);
     if (entries === void 0)
       continue;
@@ -8326,7 +8489,7 @@ async function readDeployTargets(ctx, inventory) {
     for (const e of entries) {
       if (e.directory || !/\.ya?ml$/.test(e.name))
         continue;
-      const path3 = join5(dir, e.name);
+      const path3 = join6(dir, e.name);
       files.push(parseInventoryFile(path3, await ctx.readFile(path3)));
     }
   }
@@ -8356,7 +8519,7 @@ function isNotable(dir) {
 }
 
 // ../lib/dist/overview.js
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 var PRUNED = /* @__PURE__ */ new Set([
   "node_modules",
   ".hg",
@@ -8404,7 +8567,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, join6(path3, sub), sub, options);
+    const child = await walk(ctx, join7(path3, sub), sub, options);
     if (isNotable(child) || child.children.length > 0)
       dir.children.push(child);
   }
@@ -8412,7 +8575,7 @@ async function walk(ctx, path3, name, options) {
 }
 async function facet(ctx, dir, file, read) {
   try {
-    read(await ctx.readFile(join6(dir.path, file)));
+    read(await ctx.readFile(join7(dir.path, file)));
   } catch (error) {
     dir.problems ??= [];
     dir.problems.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
@@ -8451,12 +8614,12 @@ async function templateFacet(ctx, cwd) {
 }
 
 // ../lib/dist/propagate.js
-import { join as join7, relative as relative3 } from "node:path";
+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";
 async function propagate(ctx, workspace, train) {
   const summary = { train, preview: ctx.dryRun, clean: [], conflicted: [], failed: [], skipped: [] };
-  const upstream = join7(workspace, UPSTREAM);
+  const upstream = join8(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));
@@ -8473,7 +8636,7 @@ async function propagate(ctx, workspace, train) {
   const cloneOf = async (consumer) => {
     let clone = clones.get(consumer.path);
     if (!clone) {
-      clone = join7(scratch ?? "", consumer.rel);
+      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);
@@ -8500,7 +8663,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, join7(upstream, preset), summary, cloneOf, previewCommit);
+        await updateSite(ctx, consumer, site, join8(upstream, preset), summary, cloneOf, previewCommit);
     }
     await refreshLockfiles(ctx, active, summary, clones);
     await bumpConsumerRefs(ctx, consumers, train);
@@ -8517,17 +8680,15 @@ 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 = 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}`)));
+      target = join8(repo, relative3(consumer.path, site.path));
+      const answers = await ctx.readFile(join8(site.path, 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 ctx.stage(run("copier", ["update", "--skip-answered", "--trust", "--defaults", "--skip-tasks", "--vcs-ref", "main"], {
-        cwd: target
-      }));
+      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"] : []];
-      await ctx.apply([run("copier", args, { cwd: target, interactive: true })]);
+      await ctx.apply([run("mise", copierVia(args), { cwd: target, interactive: true })]);
     }
   } catch (error) {
     ctx.say(`  \u2717 FAILED \u2014 copier update exited nonzero${detail(error)}`);
@@ -8538,7 +8699,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(join7(repo, f)).catch(() => "");
+    const text = await ctx.readFile(join8(repo, f)).catch(() => "");
     if (hasConflictMarkers(text))
       conflict = true;
   }
@@ -8556,17 +8717,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(join7(target, MARKER_FILE)).catch(() => void 0);
+  const marker = await ctx.readFile(join8(target, MARKER_FILE)).catch(() => void 0);
   if (marker === void 0)
     return;
-  const { commit } = parseAnswers(await ctx.readFile(join7(target, ANSWERS_FILE)));
+  const { commit } = parseAnswers(await ctx.readFile(join8(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(join7(target, MARKER_FILE), synced);
+  const step = write(join8(target, MARKER_FILE), synced);
   if (ctx.dryRun)
     await ctx.stage(step);
   else
@@ -8575,7 +8736,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(join7(c.path, "pnpm-workspace.yaml")).catch(() => void 0) === void 0)
+    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)
@@ -8595,7 +8756,7 @@ async function refreshLockfiles(ctx, consumers, summary, clones) {
 }
 async function bumpConsumerRefs(ctx, consumers, train) {
   for (const c of consumers) {
-    const dir = join7(c.path, ".github", "workflows");
+    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)
@@ -8605,14 +8766,14 @@ async function bumpConsumerRefs(ctx, consumers, train) {
       continue;
     }
     for (const f of files) {
-      const text = await ctx.readFile(join7(dir, f));
+      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(join7(dir, f), bumped)]);
+      await ctx.apply([write(join8(dir, f), bumped)]);
     }
   }
 }
@@ -8623,7 +8784,7 @@ var detail = (error) => {
 };
 
 // ../lib/dist/requirements.js
-import { join as join8 } from "node:path";
+import { join as join9 } 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);
@@ -8716,7 +8877,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(join8(compendium, dir));
+    const entries = await ctx.readDir(join9(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}`);
   }
@@ -8724,11 +8885,11 @@ async function modulePages(ctx, compendium) {
 }
 async function checkCompendium(ctx, compendium) {
   const defects = [];
-  defects.push(...scanPage(await ctx.readFile(join8(compendium, MAP_PAGE)), MAP_PAGE, "map").defects);
+  defects.push(...scanPage(await ctx.readFile(join9(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(join8(compendium, page)), page, "module");
+    const scan = scanPage(await ctx.readFile(join9(compendium, page)), page, "module");
     defects.push(...scan.defects);
     scans.set(page, scan);
   }
@@ -8774,11 +8935,25 @@ async function checkCompendium(ctx, compendium) {
   };
 }
 
+// ../lib/dist/self.js
+var SELF_PACKAGE = "@plexus-ms/cli";
+async function preflightSelf(ctx, running) {
+  const latest = (await ctx.read("npm", ["view", SELF_PACKAGE, "version"]).catch(() => "")).trim();
+  if (!latest) {
+    ctx.say(`\u26A0 could not ask the registry for the newest ${SELF_PACKAGE}; going on with plx ${running}`);
+    return;
+  }
+  if (compareTrains(running, latest) < 0)
+    throw new Error(`plx ${running} is behind ${latest}, the newest release; update it first: mise cache clear && mise up npm:${SELF_PACKAGE}`);
+}
+
 // ../lib/dist/ship.js
-import { join as join9 } from "node:path";
+import { join as join10 } from "node:path";
 async function ship(ctx, options) {
-  const upstream = join9(options.workspace, UPSTREAM);
+  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 preflightRelease(ctx, train);
@@ -8828,7 +9003,7 @@ async function planBookkeeping(ctx, train, next, today2) {
     return r;
   };
   const edit = async (r, rel, what, transform) => {
-    const path3 = join9(r.path, rel);
+    const path3 = join10(r.path, rel);
     const text = await ctx.readFile(path3).catch(() => void 0);
     if (text === void 0)
       return;
@@ -8849,7 +9024,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(join9(comp.path, page));
+    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(() => "") : "";
@@ -9812,13 +9987,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 resolve9;
+  let resolve10;
   let reject;
   const promise = new Promise((res, rej) => {
-    resolve9 = res;
+    resolve10 = res;
     reject = rej;
   });
-  return { promise, resolve: resolve9, reject };
+  return { promise, resolve: resolve10, reject };
 }
 
 // ../../node_modules/.pnpm/@inquirer+core@12.0.5_@types+node@26.6.5/node_modules/@inquirer/core/dist/lib/create-prompt.js
@@ -10197,7 +10372,7 @@ function createPrompt(view) {
     });
     output.mute();
     const screen = new ScreenManager(rl);
-    const { promise, resolve: resolve9, reject } = withResolver();
+    const { promise, resolve: resolve10, reject } = withResolver();
     return withHooks(rl, (cycle) => {
       const clearEffects = AsyncResource3.bind(() => effectScheduler.clearAll());
       const settlePrompt = (settle) => {
@@ -10208,7 +10383,7 @@ function createPrompt(view) {
           reject(error);
         }
       };
-      const resolvePrompt = (value) => settlePrompt(() => resolve9(value));
+      const resolvePrompt = (value) => settlePrompt(() => resolve10(value));
       const rejectPrompt = (error) => settlePrompt(() => reject(error));
       const promptPromise = Object.assign(promise.finally(() => {
         cleanups.forEach((cleanup) => cleanup());
@@ -13753,19 +13928,49 @@ function renderChangeset(c) {
   return [`\u2713 ${c.path}`, ...releases.map(([name, bump]) => `  ${name}: ${bump}`)].join("\n");
 }
 
-// src/commands/deploy-targets.ts
+// src/commands/deploy.ts
 import { resolve as resolve3 } from "node:path";
 function register3(program2) {
+  program2.command("deploy").description(
+    "render the app\u2019s compose file with the image pinned, stage it on the host, pull, migrate, swap, up, poll readiness, roll back on failure"
+  ).argument("<host>", "ssh target, deploy@host").argument("<tenant>", "tenant slug, the first segment of the app dir on the host").argument("<app>", "the app, apps/<app> in the checkout").option("--image <ref>", "the image ref to pin; absent for a third-party app whose compose.yaml pins its own").option(
+    "--health-url <url>",
+    "readiness URL polled on the host (default: /healthz, or the plexus.healthz label, on the loopback port)"
+  ).option("--retries <n>", "poll attempts, two seconds apart", "30").option("--app-dir <path>", "the app dir on the host (default: /opt/stacks/<tenant>/<app>)").option("--source <path>", "the app\u2019s dir in the checkout (default: apps/<app>)").option("-C, --dir <dir>", "the checkout to read", ".").action(async (host, tenant, app, opts, command) => {
+    const ctx = contextOf2(command);
+    const result = await deploy(ctx, {
+      host,
+      tenant,
+      app,
+      image: opts.image,
+      healthUrl: opts.healthUrl,
+      retries: Number(opts.retries),
+      appDir: opts.appDir,
+      source: opts.source,
+      dir: resolve3(opts.dir)
+    });
+    ctx.result(result, renderDeploy);
+    if (!result.healthy) process.exitCode = 1;
+  });
+}
+function renderDeploy(d) {
+  if (d.healthy) return d.live ?? "";
+  return d.rolledBack ? `rolled back to ${d.live ?? "the previous compose.yaml"}` : "not healthy";
+}
+
+// src/commands/deploy-targets.ts
+import { resolve as resolve4 } from "node:path";
+function register4(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));
+    const targets = await readDeployTargets(ctx, resolve4(inventory));
     ctx.result(targets, (t) => JSON.stringify(t));
   });
 }
 
 // src/commands/doctor.ts
 import { existsSync } from "node:fs";
-import { join as join10, resolve as resolve4 } from "node:path";
+import { join as join11, resolve as resolve5 } from "node:path";
 
 // src/style.ts
 function style(enabled) {
@@ -13776,15 +13981,15 @@ var colorByDefault = () => process.stdout.isTTY === true && !process.env.NO_COLO
 
 // src/commands/doctor.ts
 var WORKSPACE_COMPENDIUM = "plexus-ms/compendium";
-function register4(program2) {
+function register5(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 = resolve4(dir);
-    const compendium = resolve4(opts.compendium ?? join10(root, WORKSPACE_COMPENDIUM));
-    if (!existsSync(join10(compendium, "contracts")))
+    const root = resolve5(dir);
+    const compendium = resolve5(opts.compendium ?? join11(root, WORKSPACE_COMPENDIUM));
+    if (!existsSync(join11(compendium, "contracts")))
       throw new Error(
         `no compendium at ${compendium}; pass --compendium <path to a checkout of plexus-ms/compendium>`
       );
@@ -13812,11 +14017,11 @@ function renderReport(report, s, showCurrent) {
 }
 
 // src/commands/overview.ts
-import { resolve as resolve5 } from "node:path";
-function register5(program2) {
+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) => {
     const ctx = contextOf2(command);
-    const tree = await overview(ctx, resolve5(dir));
+    const tree = await overview(ctx, resolve6(dir));
     const s = style(opts.color ?? colorByDefault());
     ctx.result(tree, (t) => renderTree(t, s, ctx.verbose >= 1));
   });
@@ -13859,14 +14064,14 @@ function annotate(dir, s, modules) {
 }
 
 // src/commands/propagate.ts
-import { resolve as resolve7 } from "node:path";
+import { resolve as resolve8 } from "node:path";
 
 // src/commands/ship.ts
-import { resolve as resolve6 } from "node:path";
-function register6(program2) {
+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) => {
     const ctx = contextOf2(command);
-    const result = await ship(ctx, { workspace: resolve6(dir), train: opts.train });
+    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}`));
     if (!isClean(result)) process.exitCode = 1;
   });
@@ -13889,23 +14094,23 @@ function renderSummary(s, realCommand) {
 }
 
 // src/commands/propagate.ts
-function register7(program2) {
+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) => {
     const ctx = contextOf2(command);
-    const result = await ship(ctx, { workspace: resolve7(dir), train: opts.train, propagateOnly: true });
+    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}`));
     if (!isClean(result)) process.exitCode = 1;
   });
 }
 
 // src/commands/requirements.ts
-import { join as join11, resolve as resolve8 } from "node:path";
-function register8(program2) {
+import { join as join12, resolve as resolve9 } from "node:path";
+function register9(program2) {
   program2.command("requirements").description("lint the standard's map and module pages, or extract one module's requirement lines").argument("[dir]", "a checkout of the compendium", ".").option("--extract <page>", "print a module page's requirement lines instead of linting (path relative to dir)").action(async (dir, opts, command) => {
     const ctx = contextOf2(command);
-    const compendium = resolve8(dir);
+    const compendium = resolve9(dir);
     if (opts.extract) {
-      ctx.result(extractRequirements(await ctx.readFile(join11(compendium, opts.extract))));
+      ctx.result(extractRequirements(await ctx.readFile(join12(compendium, opts.extract))));
       return;
     }
     const check = await checkCompendium(ctx, compendium);
@@ -13920,13 +14125,14 @@ function renderCheck(c) {
 
 // src/commands/index.ts
 var commands = [
-  register5,
-  register4,
   register6,
+  register5,
   register7,
   register8,
+  register9,
   register2,
   register,
+  register4,
   register3
 ];
 
@@ -13937,7 +14143,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 register9 of commands) register9(program2);
+  for (const register10 of commands) register10(program2);
   return program2;
 }
 function contextOf2(command) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plexus-ms/cli",
-  "version": "0.5.0",
+  "version": "0.7.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.5.0",
+    "@plexus-ms/lib": "0.7.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {