alexandr 0.1.0 → 0.1.1

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alexandr",
-  "version": "0.1.0",
+  "version": "0.1.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

@@ -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);
@@ -180,11 +174,23 @@ 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));
 
-  // 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";
@@ -120,11 +122,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 +175,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 +193,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 +240,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,6 +269,45 @@ 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() {
   let resolveFn, rejectFn;