alexandr 0.0.1 → 0.1.0

package/src/link.js

@@ -0,0 +1,326 @@
+// The account-link ceremony — bind this runtime to an alexandr account via a browser login
+// (docs/plans/runtime-connection-redesign.md Phase 4, Goal 2; account-required-runtimes D3).
+// OAuth authorization-code + PKCE: we open the browser to the account site, the signed-in
+// developer confirms linking THIS host, the loopback redirect hands back a code, we exchange it
+// (with our PKCE verifier) for a short-lived token, and register this runtime. The connected
+// coordinates land in the box's .env so it boots signed-in from the first request.
+// Phishing-safe: whoever runs this on the box IS the authenticated owner (no confused deputy).
+//
+// Under account-required runtimes this is NOT optional: `alexandr up` runs `ensureLinked` as
+// step one (an unlinked box refuses to serve), and `alexandr link` remains the explicit
+// re-link/repair verb.
+
+import http from "node:http";
+import crypto from "node:crypto";
+import { log, dim, 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";
+
+const b64url = (buf) => buf.toString("base64url");
+// Default to the hosted control plane + the WEBSITE (the one web property — the web app retired,
+// website-account-surface.md); override for dev (e.g. http://localhost:4000 + http://localhost:3000)
+// via env. The link-consent page (/cli-auth) + the account page are website surfaces now.
+const CP_URL = (process.env.ALEXANDR_CP_URL || "https://api.alexandr.so").replace(/\/+$/, "");
+const APP_URL = (process.env.ALEXANDR_APP_URL || "https://alexandr.so").replace(/\/+$/, "");
+const TIMEOUT_MS = 5 * 60 * 1000;
+
+/** Whether this instance's .env already carries the connected credential trio. */
+export function isLinked(dir) {
+  const env = readEnv(dir);
+  return Boolean(
+    (env.ALEXANDR_CP_URL || "").trim() &&
+      (env.ALEXANDR_INSTANCE_ID || "").trim() &&
+      (env.ALEXANDR_RUNTIME_SECRET || "").trim(),
+  );
+}
+
+/**
+ * Make sure this instance is linked to an account — the sign-in-first step of `alexandr up`.
+ * Already linked → returns false untouched. Otherwise runs the browser ceremony, writes the
+ * credential trio into .env, and returns true. Exits the process (fail) when the ceremony
+ * can't complete — there is no account-free fallback.
+ */
+export async function ensureLinked(inst, flags) {
+  if (isLinked(inst.dir)) return false;
+  step("This runtime isn't linked to an alexandr account yet — sign-in comes first.");
+  await runLinkCeremony(inst, flags);
+  return true;
+}
+
+// ---------------------------------------------------------------- link (the explicit verb)
+export async function link(flags) {
+  const inst = resolveInstance(flags);
+  if (!isMaterialized(inst.dir)) {
+    fail("No runtime here yet — run `alexandr up` (it signs you in as step one).");
+  }
+  if (isLinked(inst.dir) && !flags.force) {
+    // A revoked box (its workspace removed from the account) still carries the dead credential
+    // trio in .env — presence isn't validity. When the box is RUNNING and its health says it
+    // refuses, plain `link` is a repair, not a no-op. (--force stays the explicit override for
+    // a stopped box / re-registering afresh.)
+    const h = await health(kernelUrl(kernelPort(inst.dir)));
+    if (h?.auth?.posture === "unlinked") {
+      step(
+        h.auth.postureReason === "revoked"
+          ? "This runtime's account link was revoked — signing you in to re-link…"
+          : "This runtime is running unlinked — signing you in to link it…",
+      );
+    } else {
+      ok("Already linked to an account. Re-run with --force to register it afresh.");
+      return;
+    }
+  }
+  await runLinkCeremony(inst, flags);
+
+  if (await isRunning(inst.dir)) {
+    step("Restarting the runtime so it boots signed-in…");
+    const r = compose(inst.dir, inst.projectName, ["up", "-d"], { stdio: "ignore" });
+    if (r.status !== 0) {
+      ok("Linked. Run `alexandr up` to apply (couldn't auto-restart).");
+      return;
+    }
+    if (!(await waitPosture(kernelUrl(kernelPort(inst.dir)), "cp"))) {
+      warn("Linked, but the runtime didn't come back serving in time. Check `alexandr logs`.");
+      return;
+    }
+  }
+  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. */
+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 name =
+    typeof flags.name === "string" && flags.name.trim() ? flags.name.trim() : "My self-hosted workspace";
+
+  // PKCE (S256) + a CSRF state for the loopback redirect.
+  const verifier = b64url(crypto.randomBytes(32));
+  const challenge = b64url(crypto.createHash("sha256").update(verifier).digest());
+  const state = b64url(crypto.randomBytes(16));
+
+  const { port, done } = await startLoopback();
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  const authUrl =
+    `${APP_URL}/cli-auth?` +
+    new URLSearchParams({
+      redirect_uri: redirectUri,
+      state,
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      host: boxUrl,
+      name,
+    }).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);
+
+  let cb;
+  try {
+    cb = await done;
+  } catch (e) {
+    fail(`Link aborted: ${e.message}`);
+  }
+  if (cb.state !== state) fail("Link aborted: state mismatch (possible interception).");
+
+  // Exchange the code (+ PKCE verifier) for a short-lived session, then register this runtime.
+  const tok = await postJson(`${CP_URL}/cli-auth/token`, {
+    code: cb.code,
+    codeVerifier: verifier,
+    redirectUri,
+  });
+  if (!tok.data?.token) {
+    fail(`Link failed: could not exchange the authorization code (${tok.error ?? "malformed response"}).`);
+  }
+  const reg = await postJson(
+    `${CP_URL}/instances`,
+    { name, url: boxUrl },
+    { authorization: `Bearer ${tok.data.token}` },
+  );
+  if (!reg.data?.instanceId || !reg.data?.telemetryToken) {
+    fail(`Link failed: could not register this runtime (${reg.error ?? "malformed response"}).`);
+  }
+
+  // Write the connected coordinates into the box's .env so it boots signed-in. The box proves itself
+  // to the CP with its per-instance credential; for self-host that's the telemetry token (the CP
+  // hash-matches it on /code/exchange) carried in the runtime-secret slot. The workspace id isn't
+  // read by the kernel — it's kept for account-side operations (`destroy --unlink`).
+  //
+  // Loopback CP (a dev control plane on this machine): inside the kernel's container,
+  // "localhost" is the container itself — write the Docker host alias for the kernel's
+  // CP calls (JWKS, heartbeat) and keep the loopback form as the BROWSER-facing CP url
+  // (redirects/chrome run on the host). Real deployments (a resolvable CP domain) write
+  // one url, reachable from both.
+  const loopbackCp = /^https?:\/\/(localhost|127\.0\.0\.1)(:|$|\/)/.test(CP_URL);
+  if (loopbackCp) {
+    setEnv(inst.dir, "ALEXANDR_CP_URL", CP_URL.replace(/localhost|127\.0\.0\.1/, "host.docker.internal"));
+    setEnv(inst.dir, "ALEXANDR_CP_PUBLIC_URL", CP_URL);
+  } else {
+    setEnv(inst.dir, "ALEXANDR_CP_URL", CP_URL);
+  }
+  setEnv(inst.dir, "ALEXANDR_INSTANCE_ID", reg.data.instanceId);
+  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);
+}
+
+/**
+ * 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.
+ */
+async function registryLogin(sessionToken) {
+  const r = await postJson(
+    `${CP_URL}/registry/pull-token`,
+    {},
+    { 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,
+  });
+  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"})`);
+}
+
+/**
+ * Sign in and remove this runtime's workspace from the account (`destroy --unlink`): the same
+ * browser ceremony for a fresh session, then `DELETE /instances/:workspaceId`. Best-effort by
+ * design — the caller already decided to destroy the local containers either way.
+ */
+export async function unlinkFromAccount(inst, flags) {
+  const env = readEnv(inst.dir);
+  const workspaceId = (env.ALEXANDR_WORKSPACE_ID || "").trim();
+  if (!workspaceId) {
+    log(dim("  (no workspace id recorded — remove it from your account page instead)"));
+    return false;
+  }
+  const verifier = b64url(crypto.randomBytes(32));
+  const challenge = b64url(crypto.createHash("sha256").update(verifier).digest());
+  const state = b64url(crypto.randomBytes(16));
+  const { port, done } = await startLoopback();
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  const authUrl =
+    `${APP_URL}/cli-auth?` +
+    new URLSearchParams({
+      redirect_uri: redirectUri,
+      state,
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      host: kernelUrl(kernelPort(inst.dir)),
+      name: "Unlink this runtime",
+    }).toString();
+  step("Sign in to remove this runtime from your account…");
+  openURL(authUrl);
+  let cb;
+  try {
+    cb = await done;
+  } catch (e) {
+    log(dim(`  (unlink skipped: ${e.message})`));
+    return false;
+  }
+  if (cb.state !== state) return false;
+  const tok = await postJson(`${CP_URL}/cli-auth/token`, {
+    code: cb.code,
+    codeVerifier: verifier,
+    redirectUri,
+  });
+  if (!tok.data?.token) {
+    log(dim(`  (unlink skipped: ${tok.error ?? "malformed response"})`));
+    return false;
+  }
+  try {
+    const res = await fetch(`${CP_URL}/instances/${encodeURIComponent(workspaceId)}`, {
+      method: "DELETE",
+      headers: { authorization: `Bearer ${tok.data.token}` },
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/** Start a loopback listener for the OAuth redirect. Resolves {code,state} when /callback is hit. */
+function startLoopback() {
+  let resolveFn, rejectFn;
+  const done = new Promise((res, rej) => {
+    resolveFn = res;
+    rejectFn = rej;
+  });
+  const server = http.createServer((req, res) => {
+    const u = new URL(req.url, "http://127.0.0.1");
+    if (u.pathname !== "/callback") {
+      res.writeHead(404);
+      res.end();
+      return;
+    }
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(
+      "<!doctype html><meta charset=utf-8><body style='font:16px system-ui;padding:3rem;text-align:center'>Linked — you can close this tab and return to your terminal.</body>",
+    );
+    clearTimeout(timer);
+    setTimeout(() => server.close(), 200);
+    const code = u.searchParams.get("code");
+    const st = u.searchParams.get("state");
+    if (code && st) resolveFn({ code, state: st });
+    else rejectFn(new Error("no authorization code in the redirect"));
+  });
+  const timer = setTimeout(() => {
+    server.close();
+    rejectFn(new Error("timed out waiting for the browser confirmation"));
+  }, TIMEOUT_MS);
+  return new Promise((ready, readyErr) => {
+    server.once("error", (e) => {
+      rejectFn(e);
+      readyErr(e);
+    });
+    server.listen(0, "127.0.0.1", () => ready({ port: server.address().port, done }));
+  });
+}
+
+/** POST json → `{ data }` on success, `{ error }` on failure. The CP writes human-readable
+ *  `error` strings (e.g. the closed-alpha 403 explains exactly who may register), so failures
+ *  must carry WHY — a bare null renders as "could not register this runtime" with the real
+ *  reason swallowed. Callers surface `error` in their fail/skip message. */
+async function postJson(url, body, headers = {}) {
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...headers },
+      body: JSON.stringify(body),
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      const detail = typeof data?.error === "string" && data.error ? ` — ${data.error}` : "";
+      return { error: `HTTP ${res.status}${detail}` };
+    }
+    return data == null ? { error: "malformed response" } : { data };
+  } catch (e) {
+    return { error: `couldn't reach ${new URL(url).origin}: ${e?.message ?? e}` };
+  }
+}
+
+async function isRunning(dir) {
+  try {
+    return !!(await health(kernelUrl(kernelPort(dir))));
+  } catch {
+    return false;
+  }
+}

package/src/probe.js

@@ -0,0 +1,47 @@
+// Health/version probing of a running kernel over its loopback port. Uses the
+// global fetch (Node 18+). All probes are best-effort and never throw.
+
+export const kernelUrl = (port = 3030) => `http://127.0.0.1:${port}`;
+
+async function getJson(url, timeoutMs = 2500) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: ctrl.signal });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// GET /_kernel/health — liveness + (when unauthenticated-and-open) inventory.
+export const health = (base) => getJson(`${base}/_kernel/health`);
+// GET /_kernel/version — version stamp, open pre-auth.
+export const version = (base) => getJson(`${base}/_kernel/version`);
+
+// Poll until the kernel reports healthy, or time out. Returns the health body or null.
+export async function waitHealthy(base, timeoutMs = 90000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const h = await health(base);
+    if (h && h.ok) return h;
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return null;
+}
+
+// Poll until the kernel serves under the wanted auth posture ("cp" | "local" | "unlinked"),
+// or time out. Health alone isn't enough after a re-link: a box is healthy the moment it
+// answers, but only the posture says whether it serves or refuses.
+export async function waitPosture(base, posture, timeoutMs = 90000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const h = await health(base);
+    if (h && h.ok && h.auth?.posture === posture) return h;
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return null;
+}

package/src/prompt.js

@@ -0,0 +1,116 @@
+// Tiny zero-dependency interactive prompts (arrow-key select · line input) for the
+// first-run wizard. Pure Node, no Bun, no npm deps — same contract as util.js.
+//
+// Streams are injectable for tests (a fake stdin EventEmitter with setRawMode/isTTY
+// drives the whole state machine); production callers pass nothing. Callers are
+// expected to guard on a real TTY before prompting — these render ANSI unconditionally.
+
+import readline from "node:readline";
+import { bold, dim, green, cyan } from "./util.js";
+
+const CTRL_C = "\x03";
+const CTRL_D = "\x04";
+
+/** Ctrl-C during a prompt = the user aborted the install. 130 = 128 + SIGINT. */
+function abort(output) {
+  output.write("\x1b[?25h\n");
+  process.exit(130);
+}
+
+/**
+ * Arrow-key single select, create-vite style:
+ *
+ *   › How should this runtime be reachable?
+ *     ❯ Just this machine   http://localhost:3030
+ *       A public domain     automatic HTTPS via Caddy
+ *
+ * choices: [{ label, hint?, value }]. ↑/↓ (or j/k, or 1-9) move, Enter picks.
+ * On pick the block collapses to one confirmed line: `✓ <question> · <label>`.
+ */
+export function select(question, choices, { input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolve) => {
+    let index = 0;
+    const width = Math.max(...choices.map((c) => c.label.length));
+
+    const render = (first = false) => {
+      if (!first) output.write(`\x1b[${choices.length + 1}A`); // back to the question line
+      output.write(`\x1b[2K${cyan("›")} ${bold(question)}\n`);
+      for (let i = 0; i < choices.length; i++) {
+        const c = choices[i];
+        const line =
+          i === index
+            ? `  ${cyan("❯")} ${bold(c.label.padEnd(width))}${c.hint ? `   ${dim(c.hint)}` : ""}`
+            : `    ${c.label.padEnd(width)}${c.hint ? `   ${dim(c.hint)}` : ""}`;
+        output.write(`\x1b[2K${line}\n`);
+      }
+    };
+
+    output.write("\x1b[?25l"); // hide the cursor while the list is live
+    render(true);
+    input.setRawMode?.(true);
+    input.resume?.();
+
+    // One chunk can carry SEVERAL keys (fast typing, paste, test harnesses) — split it
+    // into key tokens: a CSI escape sequence (\x1b[ + final byte) or a single char.
+    const tokenize = (s) => {
+      const keys = [];
+      for (let i = 0; i < s.length; i++) {
+        if (s[i] === "\x1b" && s[i + 1] === "[" && i + 2 < s.length) {
+          keys.push(s.slice(i, i + 3));
+          i += 2;
+        } else keys.push(s[i]);
+      }
+      return keys;
+    };
+
+    const onData = (data) => {
+      for (const key of tokenize(String(data))) {
+        if (key === CTRL_C || key === CTRL_D) abort(output);
+        if (key === "\x1b[A" || key === "k") index = (index - 1 + choices.length) % choices.length;
+        else if (key === "\x1b[B" || key === "j" || key === "\t") index = (index + 1) % choices.length;
+        else if (/^[1-9]$/.test(key) && Number(key) <= choices.length) index = Number(key) - 1;
+        else if (key === "\r" || key === "\n") {
+          input.off("data", onData);
+          input.setRawMode?.(false);
+          input.pause?.();
+          // Collapse the whole block to a single confirmed line.
+          output.write(`\x1b[${choices.length + 1}A`);
+          for (let i = 0; i <= choices.length; i++) output.write("\x1b[2K\x1b[1B");
+          output.write(`\x1b[${choices.length + 1}A`);
+          output.write(`${green("✓")} ${question} ${dim("·")} ${choices[index].label}\n`);
+          output.write("\x1b[?25h");
+          resolve(choices[index].value);
+          return;
+        }
+      }
+      render();
+    };
+    input.on("data", onData);
+  });
+}
+
+/**
+ * One-line text input with a default and an optional validator.
+ * `validate` returns an error string to re-ask, or null/undefined to accept.
+ */
+export async function ask(question, { def = "", validate, input = process.stdin, output = process.stdout } = {}) {
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const rl = readline.createInterface({ input, output });
+    const suffix = def ? ` ${dim(`(${def})`)}` : "";
+    const answer = await new Promise((resolve) => {
+      rl.on("SIGINT", () => abort(output));
+      rl.question(`${cyan("›")} ${bold(question)}${suffix} `, resolve);
+    });
+    rl.close();
+    const value = (answer || "").trim() || def;
+    const problem = validate?.(value);
+    if (problem) {
+      output.write(`  ${dim(problem)}\n`);
+      continue;
+    }
+    // Re-print as a confirmed line (overwrite the prompt line the answer echoed onto).
+    output.write(`\x1b[1A\x1b[2K${green("✓")} ${question} ${dim("·")} ${value}\n`);
+    return value;
+  }
+}

package/src/util.js

@@ -0,0 +1,96 @@
+// Tiny zero-dependency utilities: colored output, arg parsing, port probing,
+// and a cross-platform URL opener. Pure Node (no Bun, no npm deps).
+
+import { spawn } from "node:child_process";
+import net from "node:net";
+
+const useColor = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+
+export const bold = paint("1");
+export const dim = paint("2");
+export const red = paint("31");
+export const green = paint("32");
+export const yellow = paint("33");
+export const cyan = paint("36");
+
+export function log(msg = "") {
+  process.stdout.write(`${msg}\n`);
+}
+export function ok(msg) {
+  log(`${green("✓")} ${msg}`);
+}
+export function warn(msg) {
+  log(`${yellow("!")} ${msg}`);
+}
+export function step(msg) {
+  log(`${cyan("›")} ${msg}`);
+}
+export function fail(msg, code = 1) {
+  process.stderr.write(`${red("✗")} ${msg}\n`);
+  process.exit(code);
+}
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Minimal flag parser. Returns { _: [positionals], <flag>: value|true, ... }.
+// Supports --key value, --key=value, --bool, and bundled short bools (-fy).
+// A token only counts as a flag if a letter follows the dash(es) — so values
+// like negative numbers (-1) are consumed as values, not mistaken for flags.
+const looksLikeFlag = (s) => /^--?[A-Za-z]/.test(s);
+
+export function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq !== -1) {
+        out[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (next !== undefined && !looksLikeFlag(next)) {
+          out[key] = next;
+          i++;
+        } else {
+          out[key] = true;
+        }
+      }
+    } else if (/^-[A-Za-z]/.test(a)) {
+      for (const ch of a.slice(1)) out[ch] = true;
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+// True if a confirmation flag was passed (-y / --yes).
+export const confirmed = (flags) => Boolean(flags.yes || flags.y);
+
+// Resolve whether a TCP port is free to bind on the loopback interface.
+export function isPortFree(port, host = "127.0.0.1") {
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once("error", () => resolve(false));
+    srv.once("listening", () => srv.close(() => resolve(true)));
+    srv.listen(port, host);
+  });
+}
+
+// Open a URL in the default handler. Best-effort, non-fatal, cross-platform.
+export function openURL(url) {
+  try {
+    if (process.platform === "darwin") {
+      spawn("open", [url], { stdio: "ignore", detached: true }).unref();
+    } else if (process.platform === "win32") {
+      spawn("cmd", ["/c", "start", "", url], { stdio: "ignore", detached: true }).unref();
+    } else {
+      spawn("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/templates/Caddyfile

@@ -0,0 +1,6 @@
+# The public front door (only used when ALEXANDR_DOMAIN is set — see the
+# "public" profile in docker-compose.yml). With a domain, Caddy provisions +
+# renews HTTPS automatically; without one it would serve plain HTTP on :80.
+{$ALEXANDR_DOMAIN::80} {
+	reverse_proxy kernel:3030
+}

package/templates/docker-compose.yml

@@ -0,0 +1,51 @@
+# alexandr runtime — managed by the `alexandr` CLI.
+# Do not edit by hand; use `alexandr config …` or re-run `alexandr up`.
+# Pulls the published kernel image (no source build). Update with `alexandr update`.
+#
+# Host ports + image are templated so the CLI can override them via the .env it
+# writes next to this file (ALEXANDR_KERNEL_PORT / ALEXANDR_HTTP_PORT / …).
+
+services:
+  kernel:
+    image: ${ALEXANDR_IMAGE:-ghcr.io/alexandrco/alexandr-kernel:latest}
+    environment:
+      # The installer's placement stamp: a self-hosted box is an engine behind the
+      # desktop app — browsers at its root get the "open in the Alexandr app" page,
+      # never the web shell (that's the managed placement's surface).
+      ALEXANDR_PLACEMENT: self-hosted
+      # The HOST side of the port map below — inside the container the kernel only
+      # knows its internal port, and must not advertise that as its reachable URL.
+      ALEXANDR_ADVERTISED_PORT: ${ALEXANDR_KERNEL_PORT:-3030}
+    env_file:
+      - path: ./.env
+        required: false            # every var is optional; the CLI writes this file
+    volumes:
+      - data:/data                 # instance state: OS db, installed apps, blobs
+    ports:
+      - "127.0.0.1:${ALEXANDR_KERNEL_PORT:-3030}:3030"   # loopback only
+    restart: unless-stopped
+
+  # Public front door. Only started under the "public" profile — i.e. when a
+  # domain is configured (`alexandr up --domain …`). Pure-local runs skip it, so
+  # no root is needed for :80/:443 and there's no TLS machinery to babysit.
+  caddy:
+    image: caddy:2-alpine
+    profiles: ["public"]
+    depends_on:
+      - kernel
+    env_file:
+      - path: ./.env
+        required: false            # reads ALEXANDR_DOMAIN
+    ports:
+      - "${ALEXANDR_HTTP_PORT:-80}:80"
+      - "${ALEXANDR_HTTPS_PORT:-443}:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    restart: unless-stopped
+
+volumes:
+  data:
+  caddy_data:
+  caddy_config: