alexandr 0.0.1 → 0.1.0

package/src/commands.js

@@ -0,0 +1,576 @@
+// The verb implementations. Each receives the parsed flags object.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import {
+  log, ok, warn, step, fail, bold, dim, cyan, green, parseArgs, confirmed,
+  isPortFree, openURL,
+} from "./util.js";
+import {
+  dockerProblems, compose, composeCapture, exec,
+} from "./docker.js";
+import {
+  resolveInstance, isMaterialized, materialize, readEnv, envHas, setEnv,
+  unsetEnv, kernelPort,
+} from "./instance.js";
+import { kernelUrl, health, version as kVersion, waitHealthy, waitPosture } from "./probe.js";
+import { buildConnect } from "./connect.js";
+import { ensureLinked, isLinked, runLinkCeremony, unlinkFromAccount } from "./link.js";
+import { select, ask } from "./prompt.js";
+import { offerDependencyInstall } from "./deps.js";
+import { EXIT } from "./exit.js";
+
+// `alexandr link` — the explicit re-link/repair verb (`up` links automatically as step one).
+export { link } from "./link.js";
+
+const IMAGE_BASE = "ghcr.io/alexandrco/alexandr-kernel";
+
+// Docker wants forward slashes in -v host paths on Windows (C:\x → C:/x).
+const hostPath = (p) => p.replace(/\\/g, "/");
+
+// Keys whose values are secrets — masked in `config list`.
+const SECRET_KEY = /TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL/;
+
+// Friendly config keys → env vars. Raw ALEXANDR_* keys also accepted.
+const CONFIG_ALIASES = {
+  port: "ALEXANDR_KERNEL_PORT",
+  domain: "ALEXANDR_DOMAIN",
+  "public-url": "ALEXANDR_PUBLIC_URL",
+  image: "ALEXANDR_IMAGE",
+  "ai.url": "ALEXANDR_AI_BASE_URL",
+  model: "ALEXANDR_COPILOT_MODEL",
+  catalog: "ALEXANDR_CATALOG_URL",
+  releases: "ALEXANDR_RELEASES_URL",
+};
+const toEnvKey = (k) => CONFIG_ALIASES[k] || (k.startsWith("ALEXANDR_") ? k : null);
+
+function ensureDocker(problems = dockerProblems()) {
+  if (problems.length) {
+    for (const p of problems) warn(p.message);
+    // Exit with the first problem's specific class (docker missing vs daemon
+    // down vs compose missing) so callers can branch on the cause.
+    fail("Docker isn't ready — run `alexandr doctor` for details.", problems[0].exit);
+  }
+}
+
+// Does this instance's named data volume exist yet? (No volume = nothing to
+// back up / restore — and `docker run -v vol:/data` would silently create an
+// empty one, which we'd rather not do behind the user's back.)
+const dataVolumeExists = (vol) => exec("docker", ["volume", "inspect", vol]).status === 0;
+
+// Tar a data volume to outPath via a throwaway alpine container (the documented
+// recipe — no manual ritual). Shared by `backup` and the pre-update snapshot.
+// Returns true on success. Creates the destination directory if needed.
+function archiveVolume(vol, outPath) {
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  const r = spawnSync(
+    "docker",
+    ["run", "--rm", "-v", `${vol}:/data:ro`, "-v", `${hostPath(path.dirname(outPath))}:/backup`, "alpine",
+      "tar", "czf", `/backup/${path.basename(outPath)}`, "-C", "/data", "."],
+    { stdio: "inherit" },
+  );
+  return r.status === 0;
+}
+
+function isRunning(dir, projectName) {
+  const r = composeCapture(dir, projectName, ["ps", "--status", "running", "-q", "kernel"]);
+  return r.status === 0 && r.stdout !== "";
+}
+
+// The URL a CLIENT should connect to (the "advertised URL"). Precedence:
+//   ALEXANDR_PUBLIC_URL  — explicit, for a reverse proxy / known-reachable host
+//   > https://<ALEXANDR_DOMAIN>  — Caddy's "public" profile exposes + TLS-terminates it
+//   > http://127.0.0.1:<port>    — loopback: reachable ONLY from this machine.
+function clientUrl(dir) {
+  const env = readEnv(dir);
+  const explicit = (env.ALEXANDR_PUBLIC_URL || "").trim();
+  if (explicit) return explicit.replace(/\/+$/, "");
+  if (env.ALEXANDR_DOMAIN) return `https://${env.ALEXANDR_DOMAIN}`;
+  return kernelUrl(kernelPort(dir));
+}
+
+// A loopback advertised URL is only reachable from the same machine as the runtime.
+const isLoopbackUrl = (url) => /^https?:\/\/(127\.0\.0\.1|localhost|\[?::1\]?)(:|\/|$)/i.test(url);
+
+function printConnect(dir) {
+  const url = clientUrl(dir);
+  const local = isLoopbackUrl(url);
+  const { deepLink, pasteString } = buildConnect({ url });
+
+  log("");
+  log(bold(local ? "  Open in your browser (this Mac only):" : "  Open in your browser:"));
+  log(`    ${cyan(url)}`);
+  log(dim("    Sign in with your alexandr account — this runtime is linked to it, so it's"));
+  log(dim("    already in your hub (and in the desktop app)."));
+  // Headless fallback: a server with no browser hands the runtime to a Mac via the one-click
+  // link / paste-string. URL-only — membership is verified against the account, no token to carry.
+  log("");
+  log(dim("  Open in the desktop app directly:"));
+  log(`    ${cyan(deepLink)}`);
+  log(dim(`    …or paste into Connect Server:  ${pasteString}`));
+
+  if (local) {
+    log("");
+    warn("This is a local address — it only works on THIS machine.");
+    log(dim("    To connect from another computer, expose the runtime with a domain:"));
+    log(dim("      alexandr config set domain your-host.example.com    # Caddy auto-provisions HTTPS"));
+    log(dim("    then re-run `alexandr up`. (Or set ALEXANDR_PUBLIC_URL to an already-reachable URL.)"));
+  }
+}
+
+// ---------------------------------------------------------------- up
+// The first-run wizard (create-vite style): a bare `alexandr up` on a fresh instance asks
+// its few questions interactively instead of requiring flags. Runs ONLY when installing —
+// never on a re-run (`up` stays an idempotent restart), never when any shaping flag was
+// passed (scripts keep exact behavior), never without a real TTY (CI/pipes), and `--yes`
+// means "defaults, don't ask". Mutates `flags` so the answers flow through the exact same
+// code path as flags would — the wizard is input, not a second implementation.
+function wizardApplies(flags, fresh) {
+  return (
+    fresh &&
+    !flags.domain && !flags.port && !flags.name && !flags.offline && !flags["no-pull"] &&
+    !confirmed(flags) &&
+    Boolean(process.stdin.isTTY && process.stdout.isTTY)
+  );
+}
+
+async function firstRunWizard(flags) {
+  log(`${bold("alexandr")} ${dim("— let's set up this runtime. A few questions (Ctrl-C aborts):")}`);
+  log();
+  const reach = await select("How should this runtime be reachable?", [
+    { label: "Just this machine", hint: "http://localhost — open it from this computer", value: "local" },
+    { label: "A public domain", hint: "automatic HTTPS via Caddy — needs DNS pointing here", value: "public" },
+  ]);
+  if (reach === "public") {
+    flags.domain = await ask("Domain", {
+      validate: (v) =>
+        /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i.test(v)
+          ? null
+          : "That doesn't look like a domain (e.g. alexandr.example.com) — try again.",
+    });
+  } else {
+    flags.port = await ask("Port", {
+      def: "3030",
+      validate: (v) => (/^\d{2,5}$/.test(v) ? null : "A port is a number (e.g. 3030) — try again."),
+    });
+  }
+  // Becomes the workspace's display name in the account/desktop app (link.js).
+  flags.name = await ask("Workspace name", { def: "My self-hosted workspace" });
+  log();
+}
+
+export async function up(flags) {
+  // Install (the missing dependencies), don't just diagnose: on a fresh Linux box, `up`
+  // offers to set up Docker + Compose itself (deps.js), then re-checks. Declined /
+  // non-Linux / non-TTY → the normal per-cause failure below.
+  let problems = dockerProblems();
+  if (problems.length && (await offerDependencyInstall(problems))) problems = dockerProblems();
+  ensureDocker(problems);
+  const inst = resolveInstance(flags);
+  const fresh = !isMaterialized(inst.dir);
+  materialize(inst.dir);
+  // NB: after resolveInstance on purpose — the wizard's `flags.name` is the workspace
+  // DISPLAY name for the link ceremony; it must not retarget the instance directory.
+  if (wizardApplies(flags, fresh)) await firstRunWizard(flags);
+
+  if (flags.port) setEnv(inst.dir, "ALEXANDR_KERNEL_PORT", String(flags.port));
+  if (flags.domain) setEnv(inst.dir, "ALEXANDR_DOMAIN", String(flags.domain));
+
+  // Sign-in comes FIRST (account-required-runtimes D3): every runtime must be linked to an
+  // account before it serves anyone — an unlinked box boots into a static refusal page. The
+  // ceremony is a no-op when the .env already carries the credential trio, so re-running
+  // `alexandr up` never re-prompts.
+  await ensureLinked(inst, flags);
+  const hasDomain = envHas(inst.dir, "ALEXANDR_DOMAIN");
+
+  // Port pre-flight (clear message instead of an opaque Docker bind error).
+  const port = kernelPort(inst.dir);
+  if (!isRunning(inst.dir, inst.projectName) && !(await isPortFree(port))) {
+    fail(`Port ${port} is already in use. Re-run with --port <n> (e.g. \`alexandr up --port 3040\`).`, EXIT.PORT_BUSY);
+  }
+
+  const offline = Boolean(flags.offline || flags["no-pull"]);
+  const args = [];
+  if (hasDomain) args.push("--profile", "public");
+  args.push("up", "-d", "--pull", offline ? "never" : "missing");
+
+  step(`Starting alexandr (${inst.mode} · ${inst.dir})…`);
+  const 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);
+
+  const base = kernelUrl(port);
+  step("Waiting for the kernel to come up…");
+  let h = await waitHealthy(base);
+  if (h?.auth?.posture === "unlinked") {
+    // The credential trio in .env is PRESENT but DEAD (the workspace was removed from the
+    // account — the CP deleted this instance's record), so ensureLinked sailed through and
+    // the box booted straight into the kernel's refusal page. Recover in place: fresh
+    // sign-in, fresh trio, restart, and verify the box actually serves before celebrating.
+    warn(
+      h.auth.postureReason === "revoked"
+        ? "This runtime's account link was revoked — signing you in to re-link…"
+        : "This runtime came up unlinked — signing you in to link it…",
+    );
+    await runLinkCeremony(inst, flags);
+    step("Restarting the runtime with the fresh credentials…");
+    const restartArgs = hasDomain ? ["--profile", "public", "up", "-d"] : ["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);
+    }
+    h = await waitPosture(base, "cp");
+    if (!h) warn("Re-linked, but the runtime didn't come back serving in time. Check `alexandr logs`.");
+  } else if (!h) {
+    warn("Started, but the kernel didn't report healthy in time. Check `alexandr logs`.");
+  }
+  if (h) ok(`alexandr is running — ${bold(clientUrl(inst.dir))}  (kernel v${h.version ?? "?"})`);
+  printConnect(inst.dir);
+  if (flags.open) openURL(clientUrl(inst.dir));
+}
+
+// ---------------------------------------------------------------- down
+export async function down(flags) {
+  ensureDocker();
+  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"]);
+  if (r.status === 0) ok("Stopped. Your data volume is untouched — `alexandr up` to resume.");
+}
+
+// ---------------------------------------------------------------- destroy
+export async function destroy(flags) {
+  ensureDocker();
+  const inst = resolveInstance(flags);
+  if (!isMaterialized(inst.dir)) fail("No alexandr instance here.", EXIT.NO_INSTANCE);
+  const wipe = Boolean(flags.volumes || flags.data);
+  if (wipe && !confirmed(flags)) {
+    fail("`destroy --volumes` deletes /data (workspace DB, apps, blobs) irreversibly. Re-run with --yes to confirm.", EXIT.CONFIRMATION);
+  }
+  // Optional account-side cleanup: sign in and remove the workspace record too, so the hub
+  // doesn't keep a phantom entry. Off by default — destroying the containers never needs it.
+  if (flags.unlink && isLinked(inst.dir)) {
+    if (await unlinkFromAccount(inst, flags)) ok("Removed from your account.");
+    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"]);
+  if (r.status === 0) ok(wipe ? "Destroyed, including /data." : "Containers removed; /data volume kept.");
+}
+
+// ---------------------------------------------------------------- status
+export async function status(flags) {
+  ensureDocker();
+  const inst = resolveInstance(flags);
+  if (!isMaterialized(inst.dir)) {
+    if (flags.json) log(JSON.stringify({ exists: false }));
+    else log("No alexandr instance here. Run `alexandr up`.");
+    return;
+  }
+  const running = isRunning(inst.dir, inst.projectName);
+  const base = kernelUrl(kernelPort(inst.dir));
+  const v = running ? await kVersion(base) : null;
+  const h = running ? await health(base) : null;
+  const vol = `${inst.projectName}_data`;
+  // Cheap existence check by default; exact size only with --size (spawns a container).
+  const volExists = dataVolumeExists(vol);
+  const size = flags.size && volExists ? volumeSize(vol) : volExists ? "present" : "none";
+
+  if (flags.json) {
+    log(JSON.stringify({
+      exists: true, mode: inst.mode, dir: inst.dir, project: inst.projectName,
+      running, url: clientUrl(inst.dir), version: v?.version ?? null,
+      linked: isLinked(inst.dir), posture: h?.auth?.posture ?? null,
+      authActive: h?.auth?.active ?? null, dataVolume: vol, dataSize: size,
+    }, null, 2));
+    return;
+  }
+  log(`${bold("alexandr")}  (${inst.mode})`);
+  log(`  state    ${running ? green("running") : dim("stopped")}`);
+  log(`  url      ${clientUrl(inst.dir)}`);
+  log(`  version  ${v?.version ?? dim("—")}`);
+  if (h?.auth?.posture === "unlinked") {
+    warn(`  account  NOT LINKED${h.auth.postureReason === "revoked" ? " (revoked)" : ""} — the runtime refuses to serve. Run \`alexandr link\`.`);
+  } else {
+    log(`  account  ${isLinked(inst.dir) ? "linked" : dim("not linked — run `alexandr link`")}`);
+  }
+  log(`  data     ${vol}  ${dim(`(${size})`)}`);
+  log(`  config   ${inst.dir}`);
+}
+
+function volumeSize(vol) {
+  const r = spawnSync(
+    "docker",
+    ["run", "--rm", "-v", `${vol}:/v`, "alpine", "du", "-sh", "/v"],
+    { encoding: "utf8", timeout: 8000 },
+  );
+  if (r.status !== 0 || !r.stdout) return "—";
+  return r.stdout.trim().split(/\s+/)[0] || "—";
+}
+
+// ---------------------------------------------------------------- ls
+export async function ls(flags) {
+  ensureDocker();
+  const r = exec("docker", ["compose", "ls", "-a", "--format", "json"]);
+  let projects = [];
+  try {
+    const parsed = JSON.parse(r.stdout || "[]");
+    projects = (Array.isArray(parsed) ? parsed : []).filter((p) =>
+      (p.Name || "").startsWith("alexandr"),
+    );
+  } catch {
+    /* ignore parse issues */
+  }
+  if (flags.json) {
+    log(JSON.stringify(projects, null, 2));
+    return;
+  }
+  if (!projects.length) {
+    log("No alexandr instances found. Run `alexandr up` to create one.");
+    return;
+  }
+  log(bold("INSTANCE        STATE"));
+  for (const p of projects) log(`${(p.Name || "").padEnd(15)} ${p.Status || ""}`);
+}
+
+// ---------------------------------------------------------------- logs
+export async function logs(flags) {
+  ensureDocker();
+  const inst = resolveInstance(flags);
+  if (!isMaterialized(inst.dir)) fail("No alexandr instance here.", EXIT.NO_INSTANCE);
+  const args = ["logs", "kernel"];
+  if (flags.f || flags.follow) args.splice(1, 0, "-f");
+  compose(inst.dir, inst.projectName, args);
+}
+
+// ---------------------------------------------------------------- config
+export async function config(flags) {
+  const [sub, key, value] = flags._;
+  const inst = resolveInstance(flags);
+  materialize(inst.dir);
+
+  if (sub === "list" || !sub) {
+    const env = readEnv(inst.dir);
+    log(bold(`config — ${inst.dir}/.env`));
+    const keys = Object.keys(env);
+    if (!keys.length) log(dim("  (nothing set — all defaults)"));
+    for (const k of keys) log(`  ${k}=${SECRET_KEY.test(k) ? dim("••• (hidden)") : env[k]}`);
+    return;
+  }
+  if (sub === "get") {
+    if (!key) fail("usage: alexandr config get <key>", EXIT.USAGE);
+    const ek = toEnvKey(key);
+    if (!ek) fail(`Unknown config key '${key}'.`, EXIT.USAGE);
+    log(readEnv(inst.dir)[ek] ?? "");
+    return;
+  }
+  if (sub === "set") {
+    if (!key || value === undefined) fail("usage: alexandr config set <key> <value>", EXIT.USAGE);
+    const ek = toEnvKey(key);
+    if (!ek) fail(`Unknown config key '${key}'. Try one of: ${Object.keys(CONFIG_ALIASES).join(", ")}, or a raw ALEXANDR_* var.`, EXIT.USAGE);
+    setEnv(inst.dir, ek, String(value));
+    ok(`set ${ek}`);
+    return;
+  }
+  if (sub === "unset") {
+    if (!key) fail("usage: alexandr config unset <key>", EXIT.USAGE);
+    const ek = toEnvKey(key);
+    if (!ek) fail(`Unknown config key '${key}'.`, EXIT.USAGE);
+    unsetEnv(inst.dir, ek);
+    ok(`unset ${ek}`);
+    return;
+  }
+  fail(`Unknown config subcommand '${sub}'. Use get | set | list | unset.`, EXIT.USAGE);
+}
+
+// ---------------------------------------------------------------- init
+export async function init(flags) {
+  const dir = path.resolve(String(flags.dir || "alexandr"));
+  if (isMaterialized(dir) && !flags.force) {
+    fail(`${dir} already has an alexandr config. Re-run with --force to overwrite.`, EXIT.USAGE);
+  }
+  materialize(dir);
+  // Keep the real .env (secrets) out of git; commit the compose + an example.
+  const tpl = path.resolve(fileURLToPath(import.meta.url), "..", "..", "templates", "env.example");
+  fs.copyFileSync(tpl, path.join(dir, ".env.example"));
+  appendGitignore(dir);
+  ok(`Initialized ${dir}`);
+  log(dim("  committed:  docker-compose.yml · Caddyfile · .env.example"));
+  log(dim("  gitignored: .env  (created on first `alexandr up`)"));
+  log("");
+  log(`Next: ${bold("alexandr up")}`);
+}
+
+function appendGitignore(dir) {
+  // Find the nearest .git ancestor. If there isn't one, keep the ignore LOCAL to
+  // `dir` (a self-contained dir/.gitignore) rather than scribbling on some
+  // unrelated parent or the filesystem root.
+  let gitRoot = null;
+  for (let d = path.dirname(dir); ; d = path.dirname(d)) {
+    if (fs.existsSync(path.join(d, ".git"))) { gitRoot = d; break; }
+    if (path.dirname(d) === d) break;
+  }
+  const root = gitRoot || dir;
+  const gi = path.join(root, ".gitignore");
+  const rel = gitRoot ? path.relative(gitRoot, path.join(dir, ".env")) : ".env";
+  const existing = fs.existsSync(gi) ? fs.readFileSync(gi, "utf8") : "";
+  if (!existing.split("\n").includes(rel)) {
+    fs.writeFileSync(gi, `${existing}${existing && !existing.endsWith("\n") ? "\n" : ""}${rel}\n`);
+  }
+}
+
+// ---------------------------------------------------------------- update
+export async function update(flags) {
+  ensureDocker();
+  const inst = resolveInstance(flags);
+  if (!isMaterialized(inst.dir)) fail("No alexandr instance here. Run `alexandr up` first.", EXIT.NO_INSTANCE);
+
+  // Legacy migration (account-required-runtimes D8): a pre-link-first box (old static-token
+  // .env, or account-free) would update straight onto a kernel that refuses to serve — link it
+  // FIRST so the updated box comes up serving.
+  if (!isLinked(inst.dir)) {
+    step("This runtime predates account-required runtimes — the updated kernel refuses to serve unlinked.");
+    await ensureLinked(inst, flags);
+  }
+
+  const prevImage = readEnv(inst.dir).ALEXANDR_IMAGE || `${IMAGE_BASE}:latest`;
+  const base = kernelUrl(kernelPort(inst.dir));
+  const before = (await kVersion(base))?.version ?? "?";
+
+  // Auto-snapshot /data BEFORE touching the image, so the update is reversible by
+  // construction (a new kernel may run forward-only migrations a rolled-back image
+  // can't read). Skipped with --no-backup, or when there's no data volume yet.
+  const vol = `${inst.projectName}_data`;
+  if (!flags["no-backup"] && dataVolumeExists(vol)) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const tag = before && before !== "?" ? `v${before}` : "current";
+    const out = path.join(inst.dir, "backups", `pre-update-${tag}-${stamp}.tgz`);
+    step(`Snapshotting /data before updating → ${out}…`);
+    if (!archiveVolume(vol, out)) {
+      fail("Pre-update backup failed — not updating. Fix the issue, or re-run with --no-backup to skip.", EXIT.RUNTIME);
+    }
+    ok(`Snapshot saved: ${out}`);
+    log(dim(`  Roll back data if needed:  alexandr restore "${out}" --yes`));
+  }
+
+  if (flags.rollback) {
+    const ptr = path.join(inst.dir, ".previous-image");
+    if (!fs.existsSync(ptr)) fail("No previous image recorded to roll back to.", EXIT.USAGE);
+    const target = fs.readFileSync(ptr, "utf8").trim();
+    fs.writeFileSync(ptr, prevImage); // swap, so a second rollback returns here
+    setEnv(inst.dir, "ALEXANDR_IMAGE", target);
+  } else if (flags.to) {
+    fs.writeFileSync(path.join(inst.dir, ".previous-image"), prevImage);
+    setEnv(inst.dir, "ALEXANDR_IMAGE", `${IMAGE_BASE}:${flags.to}`);
+  } else {
+    fs.writeFileSync(path.join(inst.dir, ".previous-image"), prevImage);
+  }
+
+  // `--offline` / `--no-pull` mirrors `up`: skip the registry pull and boot the
+  // locally-present image. For airgapped hosts and the dev loop (self-host boxes run
+  // source-built local tags that no registry serves — pulling them always fails).
+  const offline = Boolean(flags.offline || flags["no-pull"]);
+  if (offline) {
+    step("Offline update — using the locally-present image (no pull).");
+  } else {
+    step("Pulling the runtime image…");
+    if (compose(inst.dir, inst.projectName, ["pull", "kernel"]).status !== 0) {
+      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");
+  step("Applying the update (data preserved)…");
+  if (compose(inst.dir, inst.projectName, args).status !== 0) fail("Update failed — see output above.", EXIT.RUNTIME);
+
+  const after = (await waitHealthy(base))?.version ?? "?";
+  ok(`Updated: ${before} → ${after}`);
+}
+
+// ---------------------------------------------------------------- connect
+export async function connect(flags) {
+  const inst = resolveInstance(flags);
+  if (!isMaterialized(inst.dir)) fail("No alexandr instance here. Run `alexandr up` first.", EXIT.NO_INSTANCE);
+  printConnect(inst.dir);
+  if (flags.open) openURL(clientUrl(inst.dir));
+}
+
+// ---------------------------------------------------------------- backup / restore
+export async function backup(flags) {
+  ensureDocker();
+  const inst = resolveInstance(flags);
+  if (!isMaterialized(inst.dir)) fail("No alexandr instance here.", EXIT.NO_INSTANCE);
+  const vol = `${inst.projectName}_data`;
+  if (!dataVolumeExists(vol)) fail("No data volume to back up yet — run `alexandr up` first.", EXIT.NO_INSTANCE);
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  // Stamp the kernel version into the default name so a folder of archives is
+  // self-describing (kernel migrations are forward-only — restoring an archive into
+  // an OLDER kernel can break, so knowing each archive's version matters). An explicit
+  // --out wins; if the kernel isn't running the version is simply omitted.
+  const v = (await kVersion(kernelUrl(kernelPort(inst.dir))))?.version;
+  const tag = v ? `v${v}-` : "";
+  const out = path.resolve(String(flags.out || `alexandr-backup-${tag}${stamp}.tgz`));
+  step(`Backing up ${vol} → ${out}…`);
+  if (archiveVolume(vol, out)) ok(`Backup written: ${out}`);
+  else fail("Backup failed.", EXIT.RUNTIME);
+}
+
+export async function restore(flags) {
+  ensureDocker();
+  const inst = resolveInstance(flags);
+  if (!isMaterialized(inst.dir)) fail("No alexandr instance here.", EXIT.NO_INSTANCE);
+  const file = flags._[0] && path.resolve(flags._[0]);
+  if (!file || !fs.existsSync(file)) fail("usage: alexandr restore <backup.tgz>", EXIT.USAGE);
+  if (!confirmed(flags)) fail(`Restore OVERWRITES /data with ${file}. Re-run with --yes to confirm.`, EXIT.CONFIRMATION);
+  const vol = `${inst.projectName}_data`;
+  step(`Restoring ${file} → ${vol}…`);
+  // Pass the filename as a positional ($1), never interpolated into the script —
+  // immune to spaces and shell metacharacters in the backup filename.
+  const r = spawnSync(
+    "docker",
+    ["run", "--rm", "-v", `${vol}:/data`, "-v", `${hostPath(path.dirname(file))}:/backup`, "alpine",
+      "sh", "-c", 'rm -rf /data/* /data/..?* 2>/dev/null; tar xzf "/backup/$1" -C /data', "--", path.basename(file)],
+    { stdio: "inherit" },
+  );
+  if (r.status === 0) ok("Restored. Run `alexandr up` to (re)start.");
+  else fail("Restore failed.", EXIT.RUNTIME);
+}
+
+// ---------------------------------------------------------------- doctor
+export async function doctor() {
+  log(bold("alexandr doctor\n"));
+  const problems = dockerProblems();
+  if (!problems.length) ok("Docker + Compose v2 ready");
+  else {
+    for (const p of problems) warn(p.message);
+    if (process.platform === "linux") log(dim("  • `alexandr up` can install these for you (Docker's official script, root/sudo)."));
+  }
+
+  // Platform note for the classic WSL daemon-location footgun (fires on native
+  // Windows AND inside a WSL distro, where process.platform is "linux").
+  if (process.platform === "win32" || process.env.WSL_DISTRO_NAME) {
+    log(dim("  • Windows/WSL: run inside WSL2 with Docker Desktop's WSL integration on, so the daemon is reachable from this shell."));
+  }
+  // Is the default instance present / on a free port?
+  const inst = resolveInstance({});
+  if (isMaterialized(inst.dir)) {
+    const port = kernelPort(inst.dir);
+    const free = await isPortFree(port);
+    const running = problems.length ? false : isRunning(inst.dir, inst.projectName);
+    if (running) ok(`Instance running on :${port}`);
+    else if (free) ok(`Instance configured (:${port} free)`);
+    else warn(`Port ${port} is in use but the instance isn't running — stop the other process or set --port.`);
+    if (isLinked(inst.dir)) ok("Linked to an alexandr account");
+    else warn("Not linked to an account — the runtime refuses to serve until it is (run `alexandr up` or `alexandr link`).");
+    if (envHas(inst.dir, "ALEXANDR_AUTH_TOKEN")) {
+      warn("ALEXANDR_AUTH_TOKEN is set but RETIRED — it no longer opens anything; remove it (`alexandr config unset ALEXANDR_AUTH_TOKEN`).");
+    }
+  } else {
+    log(dim("  • No instance yet — run `alexandr up`."));
+  }
+  if (problems.length) process.exit(problems[0].exit);
+}