alexandr 0.1.0 → 0.1.2

package/README.md

@@ -22,14 +22,20 @@ port or domain, and the workspace name. Flags (`--domain`, `--port`, `--name`),
 `--yes`, or a non-TTY skip the questions and keep `up` fully scriptable; re-runs
 never prompt (`up` stays an idempotent restart).
 
-On a fresh **Linux** server `up` also handles its own dependencies: when Docker
-or Compose v2 is missing it offers to install them right there (Docker's
-official `get.docker.com` script + a systemd start; root or sudo, always asked
-first). macOS/Windows get instructions instead — Docker Desktop can't be
-installed silently.
-
-Sign-in comes next: every runtime is linked to an alexandr account before it
-serves anyone — `up` opens the browser once, then boots the box already linked.
+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.
+
+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
+(Docker's official `get.docker.com` script + a systemd start; root or sudo,
+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.
 
 ## Commands
 

package/bin.js

@@ -1,7 +1,20 @@
 #!/usr/bin/env node
 // Public entrypoint for the `alexandr` CLI. Keep this a thin shim; logic lives
-// in ./src. Plain Node (no Bun, no deps) so it runs anywhere Node 20+ is.
-import { run } from "./src/cli.js";
+// in ./src. Plain Node (no Bun, no deps) so it runs anywhere Node 18+ is.
+
+// Our own version guard, so nobody meets npm's EBADENGINE wall: package.json
+// declares >=18 (what Ubuntu LTS's apt ships, and provably sufficient — the CLI
+// is dependency-free), and anything older gets ONE styled line instead of a trace.
+const major = Number(process.versions.node.split(".")[0]);
+if (major < 18) {
+  process.stderr.write(
+    `\x1b[31m✗\x1b[0m alexandr needs Node 18 or newer — this is Node ${process.versions.node}.\n` +
+    `  On Ubuntu/Debian: apt install -y npm    (or use nodesource for a current LTS)\n`,
+  );
+  process.exit(1);
+}
+
+const { run } = await import("./src/cli.js");
 
 run().catch((err) => {
   process.stderr.write(`${err?.stack || err}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alexandr",
-  "version": "0.1.0",
+  "version": "0.1.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": {
@@ -17,7 +17,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=18"
   },
   "license": "Apache-2.0",
   "repository": {

package/src/commands.js

@@ -19,7 +19,7 @@ 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 } from "./link.js";
+import { ensureLinked, isLinked, runLinkCeremony, unlinkFromAccount, applyRegistryLogin } from "./link.js";
 import { select, ask } from "./prompt.js";
 import { offerDependencyInstall } from "./deps.js";
 import { EXIT } from "./exit.js";
@@ -164,12 +164,6 @@ async function firstRunWizard(flags) {
 }
 
 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);
@@ -179,12 +173,30 @@ export async function up(flags) {
 
   if (flags.port) setEnv(inst.dir, "ALEXANDR_KERNEL_PORT", String(flags.port));
   if (flags.domain) setEnv(inst.dir, "ALEXANDR_DOMAIN", String(flags.domain));
+  // Persist the display name so a RETRIED ceremony reuses the wizard's answer — the
+  // first attempt on the aos box lost "AOS" to the default because it lived only in
+  // that run's memory (the ceremony it fed timed out).
+  if (typeof flags.name === "string" && flags.name.trim()) {
+    setEnv(inst.dir, "ALEXANDR_WORKSPACE_NAME", flags.name.trim());
+  }
 
-  // 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.
+  // 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
+  // box holding three text files in ~/.alexandr, not a Docker install. Only the wizard
+  // precedes it, because its questions are free and the consent card should name the
+  // real domain. The ceremony is a no-op when .env already carries the credential trio,
+  // so re-running `alexandr up` never re-prompts.
   await ensureLinked(inst, flags);
+
+  // Dependencies AFTER auth — only an entitled account installs anything. 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.
+  let problems = dockerProblems();
+  if (problems.length && (await offerDependencyInstall(problems))) problems = dockerProblems();
+  ensureDocker(problems);
+  // The pull credential fetched at the ceremony was held until docker existed — apply it.
+  applyRegistryLogin();
+
   const hasDomain = envHas(inst.dir, "ALEXANDR_DOMAIN");
 
   // Port pre-flight (clear message instead of an opaque Docker bind error).

package/src/link.js

@@ -11,8 +11,10 @@
 // re-link/repair verb.
 
 import http from "node:http";
+import os from "node:os";
 import crypto from "node:crypto";
-import { log, dim, fail, step, ok, warn, openURL } from "./util.js";
+import readline from "node:readline";
+import { log, dim, bold, cyan, fail, step, ok, warn, openURL } 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";
@@ -99,7 +101,9 @@ export async function runLinkCeremony(inst, flags) {
     ? `https://${String(domain).replace(/^https?:\/\//, "").replace(/\/+$/, "")}`
     : kernelUrl(kernelPort(inst.dir));
   const name =
-    typeof flags.name === "string" && flags.name.trim() ? flags.name.trim() : "My self-hosted workspace";
+    (typeof flags.name === "string" && flags.name.trim()) ||
+    (readEnv(inst.dir).ALEXANDR_WORKSPACE_NAME || "").trim() ||
+    "My self-hosted workspace";
 
   // PKCE (S256) + a CSRF state for the loopback redirect.
   const verifier = b64url(crypto.randomBytes(32));
@@ -120,11 +124,7 @@ export async function runLinkCeremony(inst, flags) {
     }).toString();
 
   step(`Link ${boxUrl} to your alexandr account`);
-  log(dim("Opening your browser to sign in and confirm…"));
-  log(dim(authUrl));
-  log(dim("Headless box? Forward the callback port and open the URL from your desktop:"));
-  log(dim(`  ssh -L ${port}:127.0.0.1:${port} <this-server>   (keep this command waiting)`));
-  openURL(authUrl);
+  await presentAuthUrl(authUrl, { port, domain });
 
   let cb;
   try {
@@ -177,14 +177,17 @@ export async function runLinkCeremony(inst, flags) {
 }
 
 /**
- * Best-effort `docker login` with the CP-minted pull credential
- * (docs/plans/private-runtime-image.md): once the kernel image is a private package, the
- * compose pull that follows the ceremony needs it. The CP gates the credential on the same
- * entitlement as registration, so a session that just registered can always fetch it.
- * Docker persists the login in its credential store — that is what `alexandr update`'s
- * later pulls ride on. Older CP (404) / credential unconfigured (503) / any other failure
- * → skip quietly: anonymous pulls keep working while the package is public.
+ * The CP-minted pull credential (docs/plans/private-runtime-image.md): the kernel image is
+ * a private package, and the CP gates the credential on the same entitlement as
+ * registration — so a session that just registered can always fetch it. Fetched IMMEDIATELY
+ * after the ceremony (the login session is short-lived) but the `docker login` may run
+ * LATER: under sign-in-first ordering, auth precedes the Docker install, so the credential
+ * is held in memory until the docker CLI exists (`applyRegistryLogin`). Docker persists the
+ * login in its credential store — that is what `alexandr update`'s later pulls ride on.
+ * Older CP (404) / credential unconfigured (503) / any other failure → skip quietly.
  */
+let pendingPullCred = null;
+
 async function registryLogin(sessionToken) {
   const r = await postJson(
     `${CP_URL}/registry/pull-token`,
@@ -192,12 +195,23 @@ async function registryLogin(sessionToken) {
     { authorization: `Bearer ${sessionToken}` },
   );
   if (!r.data?.token || !r.data?.username) return;
-  const registry = r.data.registry || "ghcr.io";
-  const login = exec("docker", ["login", registry, "-u", r.data.username, "--password-stdin"], {
-    input: r.data.token,
+  pendingPullCred = r.data;
+  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. */
+export function applyRegistryLogin() {
+  if (!pendingPullCred) return;
+  if (exec("docker", ["--version"]).status !== 0) return; // 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;
 }
 
 /**
@@ -228,7 +242,7 @@ export async function unlinkFromAccount(inst, flags) {
       name: "Unlink this runtime",
     }).toString();
   step("Sign in to remove this runtime from your account…");
-  openURL(authUrl);
+  await presentAuthUrl(authUrl, { port, domain: (env.ALEXANDR_DOMAIN || "").trim() || undefined });
   let cb;
   try {
     cb = await done;
@@ -257,8 +271,47 @@ export async function unlinkFromAccount(inst, flags) {
   }
 }
 
+/** 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) {
+  return platform === "linux" && !env.DISPLAY && !env.WAYLAND_DISPLAY;
+}
+
+/**
+ * Present the consent URL honestly, by what this machine can actually do:
+ *  - HEADLESS (a server): never pretend a browser opened. Numbered steps, tunnel FIRST
+ *    (the redirect lands on the desktop's loopback and must reach this box), URL bright.
+ *  - DESKTOP + TTY: ask before taking over the browser — the URL is printed either way,
+ *    so "open it yourself" is always available.
+ *  - DESKTOP non-TTY (scripts): old behavior — print + best-effort open, nothing blocks.
+ */
+export async function presentAuthUrl(authUrl, { port, domain, headless = isHeadless() }) {
+  const sshTarget = `${process.env.USER || "root"}@${domain || os.hostname()}`;
+  if (headless) {
+    log("");
+    step("This machine has no browser — finish the sign-in from your computer:");
+    log(`  1. Forward the callback port ${dim("(keep this running until you're done)")}:`);
+    log(`       ${bold(`ssh -L ${port}:127.0.0.1:${port} ${sshTarget}`)}`);
+    log(`  2. Open this link in a browser signed in to your alexandr account:`);
+    log(`       ${cyan(authUrl)}`);
+    log(dim(`  (waiting for the confirmation — ${TIMEOUT_MS / 60000} minutes)`));
+    return;
+  }
+  log(dim(authUrl));
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    await new Promise((resolve) => {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      rl.question(`${cyan("›")} Press Enter to open your browser and confirm ${dim("(or open the link above yourself)")} `, () => {
+        rl.close();
+        resolve();
+      });
+    });
+  }
+  openURL(authUrl);
+}
+
 /** Start a loopback listener for the OAuth redirect. Resolves {code,state} when /callback is hit. */
-function startLoopback() {
+export function startLoopback() {
   let resolveFn, rejectFn;
   const done = new Promise((res, rej) => {
     resolveFn = res;
@@ -266,6 +319,20 @@ function startLoopback() {
   });
   const server = http.createServer((req, res) => {
     const u = new URL(req.url, "http://127.0.0.1");
+    // Reachability probe for the consent page: /cli-auth pings this before the user
+    // clicks Link, so a missing ssh tunnel becomes a guided "start the tunnel" notice
+    // instead of a dead browser error page after the click. The PNA header answers
+    // Chrome's public→loopback preflight; ACAO lets the page read the success.
+    if (u.pathname === "/ping") {
+      res.writeHead(204, {
+        "access-control-allow-origin": "*",
+        "access-control-allow-methods": "GET, OPTIONS",
+        "access-control-allow-headers": "*",
+        "access-control-allow-private-network": "true",
+      });
+      res.end();
+      return;
+    }
     if (u.pathname !== "/callback") {
       res.writeHead(404);
       res.end();

package/templates/env.example

@@ -21,6 +21,8 @@
 # ALEXANDR_INSTANCE_ID=
 # ALEXANDR_RUNTIME_SECRET=
 # ALEXANDR_WORKSPACE_ID=        # account-side record id (used by `destroy --unlink`)
+# ALEXANDR_WORKSPACE_NAME=      # display name for registration (the wizard writes it,
+#                               # so a retried sign-in reuses your answer)
 
 # Public domain for Caddy auto-HTTPS. Setting this starts the "public" profile — the
 # supported way to reach the runtime from another machine. Without a domain the