alexandr 0.1.2 → 0.2.1

package/README.md

@@ -25,9 +25,11 @@ never prompt (`up` stays an idempotent restart).
 Sign-in comes right after the questions: every runtime is linked to an alexandr
 account before it serves anyone, and the entitlement gate fires **before anything
 touches the system** — an account that may not register walks away from a box
-holding three text files, not a Docker install. On a desktop the CLI asks before
-opening your browser; on a headless server it prints the tunnel + link steps to
-run from your computer.
+holding three text files, not a Docker install. On a **headless server** the CLI
+uses the device flow: it shows a short code + link, you confirm from any browser
+on any device (no tunnels, no port forwarding), and the terminal continues by
+itself. On a desktop it asks before opening your browser for the instant
+loopback hand-off.
 
 Only after sign-in does `up` handle dependencies: on a fresh **Linux** server,
 when Docker or Compose v2 is missing it offers to install them right there

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alexandr",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "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/commands.js

@@ -258,13 +258,46 @@ 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)) {
+  let wipe = Boolean(flags.volumes || flags.data);
+  let unlink = Boolean(flags.unlink);
+
+  // Interactive teardown (owner feedback, 2026-08-14): a destructive verb should ASK about
+  // everything it could take, not hide the data behind a flag you learn about afterwards.
+  // On a TTY without --yes, walk the choices; flags pre-answer their question. Non-TTY
+  // keeps the strict behavior: destructive combinations demand --yes (exit 8), scripts
+  // stay explicit.
+  const interactive = !confirmed(flags) && Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (interactive) {
+    if (!wipe) {
+      wipe = await select("Also delete the workspace data (the /data volume)?", [
+        { label: "Keep the data", hint: "containers go, /data stays — `alexandr up` resumes it", value: false },
+        { label: "Delete everything", hint: "workspace DB, apps, files — irreversible", value: true },
+      ]);
+    }
+    if (!unlink && isLinked(inst.dir)) {
+      unlink = await select("Also remove this runtime from your alexandr account?", [
+        { label: "Keep the account link", hint: "the workspace stays listed in your hub", value: false },
+        { label: "Remove it", hint: "sign-in required — the hub entry disappears", value: true },
+      ]);
+    }
+    const go = await select(
+      wipe ? "Destroy this runtime AND its data?" : "Destroy this runtime (data preserved)?",
+      [
+        { label: "Cancel", value: false },
+        { label: wipe ? "Yes, destroy everything" : "Yes, destroy it", value: true },
+      ],
+    );
+    if (!go) {
+      log(dim("Nothing touched."));
+      return;
+    }
+  } else 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 (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.");
   }

package/src/link.js

@@ -14,7 +14,7 @@ import http from "node:http";
 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 } from "./util.js";
+import { log, dim, bold, cyan, fail, step, ok, warn, openURL, sleep } from "./util.js";
 import { resolveInstance, isMaterialized, readEnv, kernelPort, setEnv } from "./instance.js";
 import { kernelUrl, health, waitPosture } from "./probe.js";
 import { compose, exec } from "./docker.js";
@@ -90,8 +90,10 @@ export async function link(flags) {
   ok(`Linked. This runtime signs in with your alexandr account — open it in the Alexandr app (your account: ${APP_URL}/account).`);
 }
 
-/** The browser OAuth+PKCE ceremony + registration. Writes the .env credential trio on success;
- *  fails the process on any break in the chain. Exported for `up`'s revoked-recovery lane. */
+/** The account-link ceremony + registration. Writes the .env credential trio on success;
+ *  fails the process on any break in the chain. Exported for `up`'s revoked-recovery lane.
+ *  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
@@ -105,6 +107,23 @@ export async function runLinkCeremony(inst, flags) {
     (readEnv(inst.dir).ALEXANDR_WORKSPACE_NAME || "").trim() ||
     "My self-hosted workspace";
 
+  step(`Link ${boxUrl} to your alexandr account`);
+  let sessionToken;
+  if (useDeviceFlow()) {
+    try {
+      sessionToken = await deviceGrantToken(boxUrl, name, "link");
+    } catch (e) {
+      fail(`Link aborted: ${e.message}`);
+    }
+  } else {
+    sessionToken = await loopbackGrantToken({ boxUrl, name, domain });
+  }
+  await registerAndPersist(inst, { boxUrl, name, sessionToken });
+}
+
+/** 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 }) {
   // PKCE (S256) + a CSRF state for the loopback redirect.
   const verifier = b64url(crypto.randomBytes(32));
   const challenge = b64url(crypto.createHash("sha256").update(verifier).digest());
@@ -123,7 +142,6 @@ export async function runLinkCeremony(inst, flags) {
       name,
     }).toString();
 
-  step(`Link ${boxUrl} to your alexandr account`);
   await presentAuthUrl(authUrl, { port, domain });
 
   let cb;
@@ -143,10 +161,56 @@ export async function runLinkCeremony(inst, flags) {
   if (!tok.data?.token) {
     fail(`Link failed: could not exchange the authorization code (${tok.error ?? "malformed response"}).`);
   }
+  return tok.data.token;
+}
+
+/**
+ * The HEADLESS ceremony — the device-authorization flow (RFC 8628 shape), because a remote
+ * box can't receive a loopback redirect and making the user build an ssh tunnel for a
+ * sign-in was backwards. The CLI mints a grant, shows a short code + URL (any browser on
+ * any device), and polls until the signed-in owner confirms. Throws on fatal (the caller
+ * decides between fail() and best-effort skip); network blips just keep polling.
+ */
+async function deviceGrantToken(host, name, intent) {
+  const mint = await postJson(`${CP_URL}/cli-auth/device`, { host, name, intent });
+  if (!mint.data?.deviceCode || !mint.data?.userCode) {
+    throw new Error(`couldn't start the sign-in (${mint.error ?? "malformed response"}).`);
+  }
+  const { deviceCode, userCode, expiresIn = 600, interval = 3 } = mint.data;
+  log("");
+  step("Open this link on any device — your computer or your phone — and confirm the code:");
+  log(`     ${cyan(`${APP_URL}/cli-auth?code=${encodeURIComponent(userCode)}`)}`);
+  log("");
+  log(`     Code:  ${bold(userCode)}`);
+  log("");
+  log(dim(`  (waiting for the confirmation — ${Math.round(expiresIn / 60)} minutes; this updates by itself)`));
+  const deadline = Date.now() + expiresIn * 1000;
+  while (Date.now() < deadline) {
+    await sleep(interval * 1000);
+    const res = await postJson(`${CP_URL}/cli-auth/device/token`, { deviceCode });
+    if (res.data?.token) return res.data.token;
+    if (res.data?.status === "pending") continue;
+    if (res.error?.startsWith("HTTP")) throw new Error(`the sign-in was rejected (${res.error}).`);
+    // Network blip — keep polling until the code's own deadline.
+  }
+  throw new Error("the code expired before it was confirmed — run the command again.");
+}
+
+/** Which ceremony fits this machine: the device flow wherever a local browser can't
+ *  receive the redirect (headless servers), the instant loopback redirect elsewhere.
+ *  ALEXANDR_DEVICE_FLOW=1|0 overrides either way. */
+function useDeviceFlow() {
+  if (process.env.ALEXANDR_DEVICE_FLOW === "1") return true;
+  if (process.env.ALEXANDR_DEVICE_FLOW === "0") return false;
+  return isHeadless();
+}
+
+/** Register the runtime with a freshly-granted session and persist the credential trio. */
+async function registerAndPersist(inst, { boxUrl, name, sessionToken }) {
   const reg = await postJson(
     `${CP_URL}/instances`,
     { name, url: boxUrl },
-    { authorization: `Bearer ${tok.data.token}` },
+    { authorization: `Bearer ${sessionToken}` },
   );
   if (!reg.data?.instanceId || !reg.data?.telemetryToken) {
     fail(`Link failed: could not register this runtime (${reg.error ?? "malformed response"}).`);
@@ -173,7 +237,7 @@ export async function runLinkCeremony(inst, flags) {
   setEnv(inst.dir, "ALEXANDR_RUNTIME_SECRET", reg.data.telemetryToken);
   if (reg.data.workspaceId) setEnv(inst.dir, "ALEXANDR_WORKSPACE_ID", reg.data.workspaceId);
   ok("Signed in — this runtime is linked to your account.");
-  await registryLogin(tok.data.token);
+  await registryLogin(sessionToken);
 }
 
 /**
@@ -194,7 +258,14 @@ async function registryLogin(sessionToken) {
     {},
     { authorization: `Bearer ${sessionToken}` },
   );
-  if (!r.data?.token || !r.data?.username) return;
+  if (!r.data?.token || !r.data?.username) {
+    // LOUD on purpose (the silent skip hid a dead prod credential on the first real
+    // install, 2026-08-14): the image is private, so no credential = the pull WILL fail.
+    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;
+  }
   pendingPullCred = r.data;
   applyRegistryLogin();
 }
@@ -226,6 +297,25 @@ export async function unlinkFromAccount(inst, flags) {
     log(dim("  (no workspace id recorded — remove it from your account page instead)"));
     return false;
   }
+  step("Sign in to remove this runtime from your account…");
+  if (useDeviceFlow()) {
+    let token;
+    try {
+      token = await deviceGrantToken(kernelUrl(kernelPort(inst.dir)), "Unlink this runtime", "unlink");
+    } catch (e) {
+      log(dim(`  (unlink skipped: ${e.message})`));
+      return false;
+    }
+    try {
+      const res = await fetch(`${CP_URL}/instances/${encodeURIComponent(workspaceId)}`, {
+        method: "DELETE",
+        headers: { authorization: `Bearer ${token}` },
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
   const verifier = b64url(crypto.randomBytes(32));
   const challenge = b64url(crypto.createHash("sha256").update(verifier).digest());
   const state = b64url(crypto.randomBytes(16));
@@ -241,7 +331,6 @@ export async function unlinkFromAccount(inst, flags) {
       host: kernelUrl(kernelPort(inst.dir)),
       name: "Unlink this runtime",
     }).toString();
-  step("Sign in to remove this runtime from your account…");
   await presentAuthUrl(authUrl, { port, domain: (env.ALEXANDR_DOMAIN || "").trim() || undefined });
   let cb;
   try {