alexandr 0.2.2 → 0.3.1

package/src/app/update.js

@@ -0,0 +1,163 @@
+// `alexandr app update` — move the linked workspace onto the newest release.
+//
+// The terminal door to `POST /_kernel/store/update` (app-system-stage-3.md
+// WP-N), which re-reads the feed, refuses anything that is not strictly newer,
+// then stages and switches. One request, one answer: `{ ok, version, previous }`.
+//
+// ⚠ THIS VERB DOES NOT PUBLISH AND DOES NOT BUILD. It moves a box between
+// releases that already exist — which is why the box gates it on
+// `os.apps.manage` (install/uninstall/switch) rather than `os.apps.create` (new
+// code arriving from a laptop, the `deploy` gate).
+//
+// ⚠ A 409 HERE IS AN ANSWER, NOT A FAILURE. "notes is already at 1.2.0" is the
+// truthful reply to "update notes", and a CLI that exited non-zero on it would
+// make `alexandr app update` unusable in any script that runs it more than once.
+// Only a refusal that leaves the box somewhere it should not be is an error.
+//
+// This module also holds the two helpers the three release verbs share
+// (`postKernelJson`, `resolveAppId`) — `rollback` and `entitle` import them from
+// here rather than each transcribing the same eight lines, and deliberately NOT
+// from `reach.js`, which is the "how do I talk to the box" module and has no
+// business knowing what an app id is.
+
+import { resolve } from "node:path";
+import { bold, cyan, dim, fail, log, ok, step, warn } from "../util.js";
+import { EXIT } from "../exit.js";
+import { appIdOf } from "./deploy.js";
+import { APP_ID_RE, headersFor, reachWorkspace } from "./reach.js";
+
+export const UPDATE_HELP = `${bold("alexandr app update")} — move the linked workspace onto the newest release
+
+${bold("USAGE")}
+  alexandr app update [--app <id>] [--dir <path>]
+
+${bold("OPTIONS")}
+  --app <id>    The app to update, when it isn't the one in this folder
+  --dir <path>  The app folder, when it isn't the current one
+
+${dim("Re-reads the catalog and switches the workspace onto the newest release. Refuses anything that isn't strictly newer — that is `alexandr app rollback`'s job. Needs the os.apps.manage permission in that workspace.")}`;
+
+export async function appUpdate(flags, project) {
+  // ⚠ `--help` before anything that can exit — see the note in publish.js.
+  if (flags.help || flags.h) return void log(UPDATE_HELP);
+  const dir = project ?? projectFor(flags);
+  const chosen = resolveAppId(flags, dir);
+  if (chosen.error) fail(chosen.error, EXIT.USAGE);
+  const id = chosen.id;
+
+  const { url, authorization } = await reachWorkspace(dir);
+  step(`Updating ${bold(id)} in ${cyan(url)}…`);
+  const res = await postKernelJson(`${url}/_kernel/store/update`, { id }, headersFor(authorization, true));
+
+  if (!res.ok) {
+    if (res.status === 403) {
+      fail(
+        `The workspace refused it (403) — changing which version an app runs needs the 'os.apps.manage' permission in that workspace. ${res.error ?? ""}`.trim(),
+        EXIT.GENERAL,
+      );
+    }
+    if (res.status === 409) {
+      // The door's own sentence, verbatim: it already names the installed version
+      // and what the catalog offers, which is more than this side knows.
+      const conflict = updateConflict(res.error, id);
+      return void (conflict.kind === "ok" ? ok(conflict.message) : warn(conflict.message));
+    }
+    // A build that failed AFTER the switch has already put the previous release
+    // back by the time this answers — say so, or the developer goes looking for a
+    // half-updated box that does not exist.
+    if (res.rolledBack) warn(`${id} is back on its previous release.`);
+    fail(`Couldn't update ${id}: ${res.error}`, EXIT.GENERAL);
+  }
+
+  const { version, previous } = res.data ?? {};
+  ok(`${bold(id)} is on ${bold(version ?? "its newest release")}${previous ? dim(` (was ${previous})`) : ""}`);
+}
+
+/**
+ * A 409 from the update door, classified.
+ *
+ * "already at X" is the happy answer to a re-run and reads as a tick; anything
+ * else the door refuses with (a catalog that does not name a version for this
+ * app) is a real gap the developer should see as a warning. Neither is an exit
+ * code — see the header.
+ */
+export function updateConflict(error, id) {
+  const message = typeof error === "string" && error.trim() ? error.trim() : `${id} has nothing newer to move to.`;
+  return { kind: /already at/i.test(message) ? "ok" : "warn", message };
+}
+
+/**
+ * The folder these verbs act in: `--dir`, else the cwd.
+ *
+ * ⚠ NOT `appDirOf` — and the difference is the point. `update`, `rollback` and
+ * `entitle` can name their app with `--app`, so a folder with no manifest.json
+ * is a perfectly legitimate place to run them from (what they need is the
+ * project's `.alexandr/link.json`, not its manifest). `appDirOf` would refuse
+ * that folder, and refuse it with the wrong reason.
+ */
+export function projectFor(flags, cwd = process.cwd()) {
+  return typeof flags.dir === "string" && flags.dir.trim() ? resolve(cwd, flags.dir) : resolve(cwd);
+}
+
+/**
+ * Which app: `--app` when given, else the one this folder declares.
+ *
+ * Pure — it answers `{ id }` or `{ error }` rather than exiting, so the choice
+ * is testable without a process. `--app` is validated against the same grammar
+ * the kernel mints ids with, so a typo is refused here with the rule spelled
+ * out instead of arriving as a 404 from the box.
+ */
+export function resolveAppId(flags, project) {
+  const named = typeof flags.app === "string" ? flags.app.trim() : "";
+  if (named) {
+    if (!APP_ID_RE.test(named)) {
+      return { error: `'${named}' is not an app id — lowercase letters, digits and dashes.` };
+    }
+    return { id: named };
+  }
+  const declared = appIdOf(project);
+  if (!declared) {
+    return {
+      error: `No manifest.json in ${project} to read an app id from — name the app with \`--app <id>\`, or run this inside its folder.`,
+    };
+  }
+  return { id: declared };
+}
+
+/**
+ * POST json to a kernel door → `{ ok, status, data, error, rolledBack }`.
+ *
+ * The kernel's store routes answer with a BODY on failure too (`{ error }`, and
+ * `rolledBack` when an update undid itself), so the status alone is never the
+ * whole answer — a helper that threw away the body would lose the only sentence
+ * worth printing. Shaped like `postMultipart` in deploy.js for the same reason.
+ */
+export async function postKernelJson(url, body, headers = {}) {
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...headers },
+      body: JSON.stringify(body),
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      return {
+        ok: false,
+        status: res.status,
+        error: typeof data?.error === "string" && data.error ? data.error : `HTTP ${res.status}`,
+        rolledBack: data?.rolledBack === true,
+      };
+    }
+    return { ok: true, status: res.status, data };
+  } catch (e) {
+    return { ok: false, status: 0, error: `couldn't reach ${safeOrigin(url)}: ${e?.message ?? e}` };
+  }
+}
+
+function safeOrigin(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return url;
+  }
+}

package/src/cli.js

@@ -10,6 +10,7 @@ import * as cmd from "./commands.js";
 import { resolveInstance, isMaterialized, kernelPort } from "./instance.js";
 import { kernelUrl, version as kVersion } from "./probe.js";
 import { COMMANDS, completion } from "./completion.js";
+import { app } from "./app/index.js";
 import { EXIT } from "./exit.js";
 
 const pkg = JSON.parse(
@@ -51,17 +52,23 @@ async function version(flags) {
 }
 
 const TABLE = {
+  app,
   up: cmd.up, down: cmd.down, destroy: cmd.destroy, status: cmd.status,
   ls: cmd.ls, logs: cmd.logs, config: cmd.config, init: cmd.init,
   update: cmd.update, connect: cmd.connect, link: cmd.link, login: cmd.login, backup: cmd.backup,
   restore: cmd.restore, completion, doctor: cmd.doctor, version,
+  // The sidecar's entrypoint (`alexandr updater serve`) — the same package, in a container.
+  updater: cmd.updater,
 };
 
 export async function run(argv = process.argv.slice(2)) {
   const flags = parseArgs(argv);
   const sub = flags._.shift();
 
-  if (!sub || flags.help || flags.h) {
+  // ⚠ `--help` is handled HERE for every verb except `app`, whose subcommands
+  // each have their own help (`alexandr app deploy --help`). Swallowing it at
+  // this level would make those unreachable.
+  if (!sub || ((flags.help || flags.h) && sub !== "app")) {
     if (!sub && (flags.version || flags.v)) return version(flags);
     log(HELP);
     return;

package/src/commands.js

@@ -15,8 +15,9 @@ import {
 } from "./docker.js";
 import {
   resolveInstance, isMaterialized, materialize, readEnv, envHas, setEnv,
-  unsetEnv, kernelPort,
+  unsetEnv, kernelPort, pruneSnapshots,
 } from "./instance.js";
+export { updater } from "./updater.js";
 import { kernelUrl, health, version as kVersion, waitHealthy, waitPosture } from "./probe.js";
 import { buildConnect } from "./connect.js";
 import {
@@ -79,6 +80,71 @@ function archiveVolume(vol, outPath) {
   return r.status === 0;
 }
 
+/** Snapshots kept per box (owner, 2026-09-08): the newest three `pre-update-*.tgz`. */
+const SNAPSHOT_KEEP = 3;
+
+/**
+ * The compose PROFILES this instance runs with — every `up`/`down` must pass the same set, or
+ * a profiled service is left behind (a `down` without the profile leaves the updater running).
+ *
+ *  · `public`  — Caddy, when a domain is configured.
+ *  · `updater` — the updater sidecar (self-host-update-sidecar.md), unless the operator opted
+ *    out (`ALEXANDR_UPDATER=off`, written by `--no-updater`) — or unless THIS process is the
+ *    sidecar's own child (`ALEXANDR_UPDATER_INSIDE=1`): a container cannot recreate itself
+ *    mid-run, so the recipe run from inside leaves the `updater` service alone.
+ */
+function profileArgs(dir) {
+  const env = readEnv(dir);
+  const args = [];
+  if (envHas(dir, "ALEXANDR_DOMAIN")) args.push("--profile", "public");
+  const updaterOff = (env.ALEXANDR_UPDATER || "").trim().toLowerCase() === "off";
+  if (!updaterOff && process.env.ALEXANDR_UPDATER_INSIDE !== "1") args.push("--profile", "updater");
+  return args;
+}
+
+/**
+ * What the updater sidecar needs written into `.env` before compose can start it: the instance
+ * dir at its host path (mounted at the same path inside), the compose project name (so the
+ * recipe run from inside drives THIS project, not a re-derived one), and the sidecar's image
+ * tag — pinned to the CLI that installed it, so the sidecar's version is the CLI's version.
+ */
+function stampUpdaterEnv(inst) {
+  setEnv(inst.dir, "ALEXANDR_INSTANCE_DIR", hostPath(inst.dir));
+  setEnv(inst.dir, "ALEXANDR_COMPOSE_PROJECT", inst.projectName);
+  if (process.env.ALEXANDR_UPDATER_INSIDE !== "1") setEnv(inst.dir, "ALEXANDR_UPDATER_IMAGE_TAG", pkgVersion());
+}
+
+/**
+ * ⚠ THE SIDECAR MUST NEVER COST A BOOT. With the `updater` profile on, a `compose up` that
+ * cannot pull the updater image (the tag not yet published for this CLI version, an
+ * air-gapped host, a registry that serves the kernel but not this package) fails the WHOLE
+ * `up` — kernel included. So when `up` fails and the profile was on, probe the updater's
+ * pull alone; if THAT is what failed, say so once and retry without the sidecar. Nothing is
+ * persisted: the next `up` tries the sidecar again. Returns the compose status.
+ */
+function composeUpWithoutSidecarIfNeeded(inst, args, offline) {
+  if (!args.includes("updater")) return 1;
+  if (!offline) {
+    const probe = composeCapture(inst.dir, inst.projectName, ["--profile", "updater", "pull", "updater"]);
+    if (probe.status === 0) return 1; // the sidecar image is fine — the failure is elsewhere
+  }
+  warn("The updater sidecar's image isn't available yet — starting without it (the terminal `alexandr update` still works; the sidecar comes back on the next `alexandr up`).");
+  const without = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--profile" && args[i + 1] === "updater") {
+      i++;
+      continue;
+    }
+    without.push(args[i]);
+  }
+  return compose(inst.dir, inst.projectName, without).status;
+}
+
+function pkgVersion() {
+  const p = path.resolve(fileURLToPath(import.meta.url), "..", "..", "package.json");
+  return JSON.parse(fs.readFileSync(p, "utf8")).version;
+}
+
 function isRunning(dir, projectName) {
   const r = composeCapture(dir, projectName, ["ps", "--status", "running", "-q", "kernel"]);
   return r.status === 0 && r.stdout !== "";
@@ -182,6 +248,11 @@ export async function up(flags) {
   if (typeof flags.name === "string" && flags.name.trim()) {
     setEnv(inst.dir, "ALEXANDR_WORKSPACE_NAME", flags.name.trim());
   }
+  // The updater sidecar (self-host-update-sidecar.md): on by default, `--no-updater` records
+  // the opt-out in .env so every later compose call agrees; `--updater` turns it back on.
+  if (flags["no-updater"]) setEnv(inst.dir, "ALEXANDR_UPDATER", "off");
+  else if (flags.updater === true) unsetEnv(inst.dir, "ALEXANDR_UPDATER");
+  stampUpdaterEnv(inst);
 
   // Sign-in comes FIRST (account-required-runtimes D3) — now literally: the entitlement
   // gate fires before anything system-mutating, so a refused account walks away from a
@@ -209,9 +280,7 @@ export async function up(flags) {
   }
 
   const offline = Boolean(flags.offline || flags["no-pull"]);
-  const args = [];
-  if (hasDomain) args.push("--profile", "public");
-  args.push("up", "-d", "--pull", offline ? "never" : "missing");
+  const args = [...profileArgs(inst.dir), "up", "-d", "--pull", offline ? "never" : "missing"];
 
   step(`Starting alexandr (${inst.mode} · ${inst.dir})…`);
   let r = compose(inst.dir, inst.projectName, args);
@@ -219,7 +288,9 @@ export async function up(flags) {
     step("Retrying the start…");
     r = compose(inst.dir, inst.projectName, args);
   }
-  if (r.status !== 0) fail("`docker compose up` failed — see the output above. Try `alexandr doctor`.", EXIT.RUNTIME);
+  if (r.status !== 0 && composeUpWithoutSidecarIfNeeded(inst, args, offline) !== 0) {
+    fail("`docker compose up` failed — see the output above. Try `alexandr doctor`.", EXIT.RUNTIME);
+  }
 
   const base = kernelUrl(port);
   step("Waiting for the kernel to come up…");
@@ -236,7 +307,7 @@ export async function up(flags) {
     );
     await runLinkCeremony(inst, flags);
     step("Restarting the runtime with the fresh credentials…");
-    const restartArgs = hasDomain ? ["--profile", "public", "up", "-d"] : ["up", "-d"];
+    const restartArgs = [...profileArgs(inst.dir), "up", "-d"];
     if (compose(inst.dir, inst.projectName, restartArgs).status !== 0) {
       fail("`docker compose up` failed after re-linking — see the output above.", EXIT.RUNTIME);
     }
@@ -298,7 +369,7 @@ export async function down(flags) {
   const inst = resolveInstance(flags);
   if (!isMaterialized(inst.dir)) fail("No alexandr instance here. Run `alexandr up` first.", EXIT.NO_INSTANCE);
   step("Stopping alexandr (data preserved)…");
-  const r = compose(inst.dir, inst.projectName, ["down"]);
+  const r = compose(inst.dir, inst.projectName, [...profileArgs(inst.dir), "down"]);
   if (r.status === 0) ok("Stopped. Your data volume is untouched — `alexandr up` to resume.");
 }
 
@@ -351,7 +422,7 @@ export async function destroy(flags) {
     else warn("Couldn't remove it from your account — remove it from your account page instead.");
   }
   step(wipe ? "Removing alexandr AND its data volume…" : "Removing alexandr containers (data preserved)…");
-  const r = compose(inst.dir, inst.projectName, wipe ? ["down", "-v"] : ["down"]);
+  const r = compose(inst.dir, inst.projectName, [...profileArgs(inst.dir), "down", ...(wipe ? ["-v"] : [])]);
   if (r.status === 0) ok(wipe ? "Destroyed, including /data." : "Containers removed; /data volume kept.");
 }
 
@@ -530,6 +601,15 @@ export async function update(flags) {
     await ensureLinked(inst, flags);
   }
 
+  // The compose file is the CLI's template, re-staged on every `up`; an update re-stages it
+  // too, so the FIRST update after the updater sidecar shipped installs the sidecar
+  // (self-host-update-sidecar.md §6) — the image pin lives in .env, never in the file.
+  // ⚠ Not from inside the sidecar: its own compose run must not rewrite the file it is
+  // executing against, and it never carries the newer template anyway.
+  if (process.env.ALEXANDR_UPDATER_INSIDE !== "1") {
+    materialize(inst.dir);
+    stampUpdaterEnv(inst);
+  }
   const prevImage = readEnv(inst.dir).ALEXANDR_IMAGE || `${IMAGE_BASE}:latest`;
   const base = kernelUrl(kernelPort(inst.dir));
   const before = (await kVersion(base))?.version ?? "?";
@@ -580,14 +660,19 @@ export async function update(flags) {
       fail("Pull failed — check your network / the image tag.", EXIT.RUNTIME);
     }
   }
-  const args = [];
-  if (envHas(inst.dir, "ALEXANDR_DOMAIN")) args.push("--profile", "public");
-  args.push("up", "-d", "--pull", offline ? "never" : "missing");
+  const args = [...profileArgs(inst.dir), "up", "-d", "--pull", offline ? "never" : "missing"];
   step("Applying the update (data preserved)…");
-  if (compose(inst.dir, inst.projectName, args).status !== 0) fail("Update failed — see output above.", EXIT.RUNTIME);
+  if (compose(inst.dir, inst.projectName, args).status !== 0 && composeUpWithoutSidecarIfNeeded(inst, args, offline) !== 0) {
+    fail("Update failed — see output above.", EXIT.RUNTIME);
+  }
 
   const after = (await waitHealthy(base))?.version ?? "?";
   ok(`Updated: ${before} → ${after}`);
+  // The newest three snapshots stay (owner, 2026-09-08); a box updated from the app every
+  // train would otherwise fill its disk with tarballs. Pruned AFTER the update is verified, so
+  // a failed update never deletes the snapshot it may need.
+  const pruned = pruneSnapshots(inst.dir, SNAPSHOT_KEEP);
+  if (pruned.length) log(dim(`  Pruned ${pruned.length} older snapshot(s); the newest ${SNAPSHOT_KEEP} are kept in backups/.`));
 }
 
 // ---------------------------------------------------------------- connect

package/src/completion.js

@@ -6,12 +6,21 @@
 
 import { fail } from "./util.js";
 import { EXIT } from "./exit.js";
+import { APP_SUBCOMMANDS } from "./app/index.js";
 
 // One row per command: { name, usage, summary }. `usage` is the display form for
 // help (may carry an arg hint like "logs [-f]"); `name` is the bare verb used for
 // completion. Order is the help display order.
 export const COMMANDS = [
   { name: "up", usage: "up", summary: "Sign in (first run), pull + boot the runtime; print the URL" },
+  {
+    name: "app",
+    usage: "app <cmd>",
+    // ⚠ The CANDIDATES come from `APP_SUBCOMMANDS` (src/app/index.js), so tab
+    // completion is right on its own — this line is only the one-line summary a
+    // person reads, and it has to be kept in step by hand.
+    summary: "Develop an app: link | dev | build | deploy | secrets | config | publish | update | rollback | entitle",
+  },
   { name: "down", usage: "down", summary: "Stop the runtime (data preserved)" },
   { name: "status", usage: "status", summary: "Show state, version, URL, and data size" },
   { name: "ls", usage: "ls", summary: "List all alexandr instances" },
@@ -20,6 +29,7 @@ export const COMMANDS = [
   { name: "link", usage: "link", summary: "Re-link this runtime to your alexandr account (--force re-registers)" },
   { name: "login", usage: "login", summary: "Refresh the runtime-image pull credential (sign in, no re-register)" },
   { name: "update", usage: "update", summary: "Update the runtime image (--to <tag>, --rollback)" },
+  { name: "updater", usage: "updater serve", summary: "Run the updater sidecar (inside its container; `up` starts it)" },
   { name: "backup", usage: "backup", summary: "Archive the data volume (--out <file>)" },
   { name: "restore", usage: "restore <f>", summary: "Restore a data-volume archive (--yes)" },
   { name: "config", usage: "config", summary: "get | set | list | unset  (e.g. alexandr config set ai.url …)" },
@@ -37,6 +47,8 @@ const NAMES = COMMANDS.map((c) => c.name);
 
 // Sub-surfaces worth completing one level deep.
 const CONFIG_SUBS = ["get", "set", "list", "unset"];
+// The `app` verb family (app-system-stage-1.md §2 WP-E) — the laptop door.
+const APP_SUBS = APP_SUBCOMMANDS.map((c) => c.name);
 
 // ---- generators -------------------------------------------------------------
 
@@ -55,6 +67,7 @@ _alexandr() {
   case "\$cmd" in
     completion) COMPREPLY=( \$(compgen -W "${SHELLS.join(" ")}" -- "\$cur") ); return ;;
     config) if [ "\$COMP_CWORD" -eq 2 ]; then COMPREPLY=( \$(compgen -W "${CONFIG_SUBS.join(" ")}" -- "\$cur") ); return; fi ;;
+    app) if [ "\$COMP_CWORD" -eq 2 ]; then COMPREPLY=( \$(compgen -W "${APP_SUBS.join(" ")}" -- "\$cur") ); return; fi ;;
   esac
   if [[ "\$cur" == -* ]]; then
     COMPREPLY=( \$(compgen -W "${GLOBAL_FLAGS.join(" ")}" -- "\$cur") )
@@ -88,6 +101,7 @@ fi
 case "\${words[2]}" in
   completion) _values 'shell' ${SHELLS.join(" ")}; return ;;
   config) (( CURRENT == 3 )) && { _values 'subcommand' ${CONFIG_SUBS.join(" ")}; return } ;;
+  app) (( CURRENT == 3 )) && { _values 'subcommand' ${APP_SUBS.join(" ")}; return } ;;
 esac
 _describe -t options 'option' _alexandr_flags
 `;
@@ -104,6 +118,7 @@ function fishScript() {
   }
   lines.push("complete -c alexandr -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish'");
   lines.push(`complete -c alexandr -n '__fish_seen_subcommand_from config' -a '${CONFIG_SUBS.join(" ")}'`);
+  lines.push(`complete -c alexandr -n '__fish_seen_subcommand_from app' -a '${APP_SUBS.join(" ")}'`);
   for (const f of GLOBAL_FLAGS) {
     if (f.startsWith("--")) lines.push(`complete -c alexandr -l ${f.slice(2)}`);
   }