alexandr 0.2.1 → 0.2.2

package/README.md

@@ -37,7 +37,9 @@ when Docker or Compose v2 is missing it offers to install them right there
 always asked first). macOS/Windows get instructions instead. The runtime image
 itself is a private package — it pulls with a credential the control plane mints
 for your signed-in account, so the download is gated by the same entitlement as
-registration.
+registration. If the registry ever rejects a pull (say, after a credential
+rotation), `up` and `update` offer a quick re-sign-in on the spot — or run
+`alexandr login` any time.
 
 ## Commands
 
@@ -50,6 +52,7 @@ registration.
 | `alexandr logs -f` | Tail kernel logs |
 | `alexandr connect` | Print the `alexandr://connect` link / paste-string |
 | `alexandr link` | Re-link this runtime to your account (`--force` re-registers) |
+| `alexandr login` | Refresh the runtime-image pull credential (sign in, no re-register) |
 | `alexandr update` | Update the runtime image (`--to <tag>`, `--rollback`); auto-snapshots `/data` first (`--no-backup` to skip) |
 | `alexandr backup` / `restore <f>` | Archive / restore the data volume |
 | `alexandr config set <k> <v>` | Edit config (`ai.url`, `model`, `port`, `domain`, …) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alexandr",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Run the alexandr workspace runtime locally — a thin Docker front door (npx alexandr up). Pulls + boots the published kernel image.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -53,7 +53,7 @@ async function version(flags) {
 const TABLE = {
   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, backup: cmd.backup,
+  update: cmd.update, connect: cmd.connect, link: cmd.link, login: cmd.login, backup: cmd.backup,
   restore: cmd.restore, completion, doctor: cmd.doctor, version,
 };
 

package/src/commands.js

@@ -19,7 +19,10 @@ import {
 } from "./instance.js";
 import { kernelUrl, health, version as kVersion, waitHealthy, waitPosture } from "./probe.js";
 import { buildConnect } from "./connect.js";
-import { ensureLinked, isLinked, runLinkCeremony, unlinkFromAccount, applyRegistryLogin } from "./link.js";
+import {
+  ensureLinked, isLinked, runLinkCeremony, unlinkFromAccount, applyRegistryLogin,
+  refreshRegistryLogin,
+} from "./link.js";
 import { select, ask } from "./prompt.js";
 import { offerDependencyInstall } from "./deps.js";
 import { EXIT } from "./exit.js";
@@ -211,7 +214,11 @@ export async function up(flags) {
   args.push("up", "-d", "--pull", offline ? "never" : "missing");
 
   step(`Starting alexandr (${inst.mode} · ${inst.dir})…`);
-  const r = compose(inst.dir, inst.projectName, args);
+  let r = compose(inst.dir, inst.projectName, args);
+  if (r.status !== 0 && !offline && (await recoverUnauthorizedPull(inst, 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);
 
   const base = kernelUrl(port);
@@ -243,6 +250,48 @@ export async function up(flags) {
   if (flags.open) openURL(clientUrl(inst.dir));
 }
 
+/**
+ * A failed compose start/pull might be the registry rejecting us — the box's `docker login`
+ * is missing or expired (fleet-wide whenever the CP-held pull PAT rotates). Probe with a
+ * captured pull; on an auth rejection offer the credential-refresh ceremony (interactive)
+ * or point at `alexandr login` (scripts). Returns true when a refreshed login landed and
+ * the caller should retry ONCE.
+ */
+async function recoverUnauthorizedPull(inst, flags) {
+  const probe = composeCapture(inst.dir, inst.projectName, ["pull", "kernel"]);
+  if (probe.status === 0) return true; // the pull works now (transient failure) — retry
+  if (!/unauthorized|denied|authentication required/i.test(`${probe.stderr}\n${probe.stdout}`)) return false;
+  warn("The registry rejected the image pull — this box's image credential is missing or expired.");
+  if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+    warn("Run `alexandr login` to refresh it, then re-run this command.");
+    return false;
+  }
+  try {
+    return await refreshRegistryLogin(inst, flags);
+  } catch (e) {
+    warn(`Couldn't refresh the credential: ${e.message}`);
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------- login
+/** Refresh the runtime-image pull credential on demand — sign in, mint the pull
+ *  credential, `docker login`. The standalone repair verb for `unauthorized` pulls. */
+export async function login(flags) {
+  ensureDocker();
+  const inst = resolveInstance(flags);
+  if (!isMaterialized(inst.dir)) fail("No alexandr instance here. Run `alexandr up` first.", EXIT.NO_INSTANCE);
+  try {
+    if (await refreshRegistryLogin(inst, flags)) {
+      ok("Image credential refreshed — pulls use your account again.");
+      return;
+    }
+  } catch (e) {
+    fail(`Login aborted: ${e.message}`);
+  }
+  fail("The sign-in completed but the registry credential didn't apply — see the warnings above.");
+}
+
 // ---------------------------------------------------------------- down
 export async function down(flags) {
   ensureDocker();
@@ -522,7 +571,12 @@ export async function update(flags) {
     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) {
+    let pull = compose(inst.dir, inst.projectName, ["pull", "kernel"]);
+    if (pull.status !== 0 && (await recoverUnauthorizedPull(inst, flags))) {
+      step("Retrying the pull…");
+      pull = compose(inst.dir, inst.projectName, ["pull", "kernel"]);
+    }
+    if (pull.status !== 0) {
       fail("Pull failed — check your network / the image tag.", EXIT.RUNTIME);
     }
   }

package/src/completion.js

@@ -18,6 +18,7 @@ export const COMMANDS = [
   { name: "logs", usage: "logs [-f]", summary: "Show kernel logs (-f to follow)" },
   { name: "connect", usage: "connect", summary: "Print the desktop-app connect link / paste-string" },
   { 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: "backup", usage: "backup", summary: "Archive the data volume (--out <file>)" },
   { name: "restore", usage: "restore <f>", summary: "Restore a data-volume archive (--yes)" },

package/src/link.js

@@ -15,7 +15,7 @@ import os from "node:os";
 import crypto from "node:crypto";
 import readline from "node:readline";
 import { log, dim, bold, cyan, fail, step, ok, warn, openURL, sleep } from "./util.js";
-import { resolveInstance, isMaterialized, readEnv, kernelPort, setEnv } from "./instance.js";
+import { resolveInstance, isMaterialized, readEnv, kernelPort, setEnv, unsetEnv } from "./instance.js";
 import { kernelUrl, health, waitPosture } from "./probe.js";
 import { compose, exec } from "./docker.js";
 
@@ -95,13 +95,7 @@ export async function link(flags) {
  *  Two grant shapes, one registration: the DEVICE flow on headless machines (a short code
  *  confirmed from any browser — no tunnel), the instant loopback PKCE redirect on desktops. */
 export async function runLinkCeremony(inst, flags) {
-  // The URL the CP records + the SSO handoff redirects back to. --domain (or a domain already in
-  // .env) for a publicly-reachable box; otherwise the loopback kernel URL (fine for a box you open
-  // locally — and the runtime self-reports its origin on heartbeat either way).
-  const domain = flags.domain || readEnv(inst.dir).ALEXANDR_DOMAIN;
-  const boxUrl = domain
-    ? `https://${String(domain).replace(/^https?:\/\//, "").replace(/\/+$/, "")}`
-    : kernelUrl(kernelPort(inst.dir));
+  const { domain, boxUrl } = instanceCoords(inst, flags);
   const name =
     (typeof flags.name === "string" && flags.name.trim()) ||
     (readEnv(inst.dir).ALEXANDR_WORKSPACE_NAME || "").trim() ||
@@ -121,9 +115,20 @@ export async function runLinkCeremony(inst, flags) {
   await registerAndPersist(inst, { boxUrl, name, sessionToken });
 }
 
+/** The URL the CP records + the consent card names. --domain (or a domain already in .env)
+ *  for a publicly-reachable box; otherwise the loopback kernel URL (fine for a box you open
+ *  locally — and the runtime self-reports its origin on heartbeat either way). */
+function instanceCoords(inst, flags) {
+  const domain = flags.domain || readEnv(inst.dir).ALEXANDR_DOMAIN;
+  const boxUrl = domain
+    ? `https://${String(domain).replace(/^https?:\/\//, "").replace(/\/+$/, "")}`
+    : kernelUrl(kernelPort(inst.dir));
+  return { domain, boxUrl };
+}
+
 /** The DESKTOP grant — OAuth authorization-code + PKCE against a loopback redirect the
  *  browser on THIS machine can reach. Returns the short-lived session token. */
-async function loopbackGrantToken({ boxUrl, name, domain }) {
+async function loopbackGrantToken({ boxUrl, name, domain, intent }) {
   // PKCE (S256) + a CSRF state for the loopback redirect.
   const verifier = b64url(crypto.randomBytes(32));
   const challenge = b64url(crypto.createHash("sha256").update(verifier).digest());
@@ -140,6 +145,9 @@ async function loopbackGrantToken({ boxUrl, name, domain }) {
       code_challenge_method: "S256",
       host: boxUrl,
       name,
+      // Copy-only hint for the consent card ("refresh" renews the image credential and
+      // registers nothing) — the grant's power is identical either way.
+      ...(intent && intent !== "link" ? { intent } : {}),
     }).toString();
 
   await presentAuthUrl(authUrl, { port, domain });
@@ -264,25 +272,48 @@ async function registryLogin(sessionToken) {
     warn(
       `The control plane couldn't provide the runtime-image credential (${r.error ?? "malformed response"}) — the image pull will fail. Retry later, or contact your operator.`,
     );
-    return;
+    return "none";
   }
   pendingPullCred = r.data;
-  applyRegistryLogin();
+  return applyRegistryLogin();
 }
 
-/** Run the held `docker login` if the docker CLI is available; no-op otherwise (the caller
- *  re-invokes after installing dependencies). Exported for `up`'s sign-in-first ordering. */
+/** Run the held `docker login` if the docker CLI is available; "held" otherwise (the caller
+ *  re-invokes after installing dependencies). Exported for `up`'s sign-in-first ordering.
+ *  Returns "done" | "failed" | "held" | "none" so recovery flows can branch on the outcome. */
 export function applyRegistryLogin() {
-  if (!pendingPullCred) return;
-  if (exec("docker", ["--version"]).status !== 0) return; // not installed yet — hold on
+  if (!pendingPullCred) return "none";
+  if (exec("docker", ["--version"]).status !== 0) return "held"; // not installed yet — hold on
   const { username, token } = pendingPullCred;
   const registry = pendingPullCred.registry || "ghcr.io";
   const login = exec("docker", ["login", registry, "-u", username, "--password-stdin"], {
     input: token,
   });
-  if (login.status === 0) log(dim(`  Registry sign-in ok — the runtime image pulls with your account.`));
-  else warn(`Couldn't sign in to ${registry} — a private runtime image won't pull. (${login.stderr || "docker login failed"})`);
   pendingPullCred = null;
+  if (login.status === 0) {
+    log(dim(`  Registry sign-in ok — the runtime image pulls with your account.`));
+    return "done";
+  }
+  warn(`Couldn't sign in to ${registry} — a private runtime image won't pull. (${login.stderr || "docker login failed"})`);
+  return "failed";
+}
+
+/**
+ * Refresh THIS box's image-pull credential without touching its registration — the recovery
+ * for an expired/missing `docker login` (fleet-wide whenever the CP-held PAT rotates). A
+ * quick sign-in (device flow on servers, loopback on desktops, intent "refresh" so the
+ * consent card says what's actually happening) mints the short-lived session, and the
+ * pull credential rides it. Returns true when the docker login landed. Throws on ceremony
+ * failure — callers decide between fail() and a soft fallback.
+ */
+export async function refreshRegistryLogin(inst, flags) {
+  const { domain, boxUrl } = instanceCoords(inst, flags);
+  const name = (readEnv(inst.dir).ALEXANDR_WORKSPACE_NAME || "").trim() || "Self-hosted runtime";
+  step("Sign in to refresh this runtime's image credential…");
+  const token = useDeviceFlow()
+    ? await deviceGrantToken(boxUrl, name, "refresh")
+    : await loopbackGrantToken({ boxUrl, name, domain, intent: "refresh" });
+  return (await registryLogin(token)) === "done";
 }
 
 /**
@@ -311,6 +342,7 @@ export async function unlinkFromAccount(inst, flags) {
         method: "DELETE",
         headers: { authorization: `Bearer ${token}` },
       });
+      if (res.ok) scrubCredentials(inst.dir);
       return res.ok;
     } catch {
       return false;
@@ -354,12 +386,22 @@ export async function unlinkFromAccount(inst, flags) {
       method: "DELETE",
       headers: { authorization: `Bearer ${tok.data.token}` },
     });
+    if (res.ok) scrubCredentials(inst.dir);
     return res.ok;
   } catch {
     return false;
   }
 }
 
+/** After a successful unlink the .env trio is DEAD — presence isn't validity, and leaving
+ *  it made the next `up` skip the ceremony entirely and die at an unauthorized pull (hit
+ *  live 2026-08-14). Scrub it so `isLinked` answers honestly and `up` signs in afresh. */
+function scrubCredentials(dir) {
+  unsetEnv(dir, "ALEXANDR_INSTANCE_ID");
+  unsetEnv(dir, "ALEXANDR_RUNTIME_SECRET");
+  unsetEnv(dir, "ALEXANDR_WORKSPACE_ID");
+}
+
 /** No local browser to open — a Linux box with no display server. The PRIMARY self-host
  *  case, so it must be first-class, not a dim afterthought. Pure for tests. */
 export function isHeadless(platform = process.platform, env = process.env) {