alexandr 0.2.2 → 0.3.0

package/src/app/update.js

@@ -0,0 +1,163 @@
+// `alexandr app update` — move the linked workspace onto the newest release.
+//
+// The terminal door to `POST /_kernel/store/update` (app-system-stage-3.md
+// WP-N), which re-reads the feed, refuses anything that is not strictly newer,
+// then stages and switches. One request, one answer: `{ ok, version, previous }`.
+//
+// ⚠ THIS VERB DOES NOT PUBLISH AND DOES NOT BUILD. It moves a box between
+// releases that already exist — which is why the box gates it on
+// `os.apps.manage` (install/uninstall/switch) rather than `os.apps.create` (new
+// code arriving from a laptop, the `deploy` gate).
+//
+// ⚠ A 409 HERE IS AN ANSWER, NOT A FAILURE. "notes is already at 1.2.0" is the
+// truthful reply to "update notes", and a CLI that exited non-zero on it would
+// make `alexandr app update` unusable in any script that runs it more than once.
+// Only a refusal that leaves the box somewhere it should not be is an error.
+//
+// This module also holds the two helpers the three release verbs share
+// (`postKernelJson`, `resolveAppId`) — `rollback` and `entitle` import them from
+// here rather than each transcribing the same eight lines, and deliberately NOT
+// from `reach.js`, which is the "how do I talk to the box" module and has no
+// business knowing what an app id is.
+
+import { resolve } from "node:path";
+import { bold, cyan, dim, fail, log, ok, step, warn } from "../util.js";
+import { EXIT } from "../exit.js";
+import { appIdOf } from "./deploy.js";
+import { APP_ID_RE, headersFor, reachWorkspace } from "./reach.js";
+
+export const UPDATE_HELP = `${bold("alexandr app update")} — move the linked workspace onto the newest release
+
+${bold("USAGE")}
+  alexandr app update [--app <id>] [--dir <path>]
+
+${bold("OPTIONS")}
+  --app <id>    The app to update, when it isn't the one in this folder
+  --dir <path>  The app folder, when it isn't the current one
+
+${dim("Re-reads the catalog and switches the workspace onto the newest release. Refuses anything that isn't strictly newer — that is `alexandr app rollback`'s job. Needs the os.apps.manage permission in that workspace.")}`;
+
+export async function appUpdate(flags, project) {
+  // ⚠ `--help` before anything that can exit — see the note in publish.js.
+  if (flags.help || flags.h) return void log(UPDATE_HELP);
+  const dir = project ?? projectFor(flags);
+  const chosen = resolveAppId(flags, dir);
+  if (chosen.error) fail(chosen.error, EXIT.USAGE);
+  const id = chosen.id;
+
+  const { url, authorization } = await reachWorkspace(dir);
+  step(`Updating ${bold(id)} in ${cyan(url)}…`);
+  const res = await postKernelJson(`${url}/_kernel/store/update`, { id }, headersFor(authorization, true));
+
+  if (!res.ok) {
+    if (res.status === 403) {
+      fail(
+        `The workspace refused it (403) — changing which version an app runs needs the 'os.apps.manage' permission in that workspace. ${res.error ?? ""}`.trim(),
+        EXIT.GENERAL,
+      );
+    }
+    if (res.status === 409) {
+      // The door's own sentence, verbatim: it already names the installed version
+      // and what the catalog offers, which is more than this side knows.
+      const conflict = updateConflict(res.error, id);
+      return void (conflict.kind === "ok" ? ok(conflict.message) : warn(conflict.message));
+    }
+    // A build that failed AFTER the switch has already put the previous release
+    // back by the time this answers — say so, or the developer goes looking for a
+    // half-updated box that does not exist.
+    if (res.rolledBack) warn(`${id} is back on its previous release.`);
+    fail(`Couldn't update ${id}: ${res.error}`, EXIT.GENERAL);
+  }
+
+  const { version, previous } = res.data ?? {};
+  ok(`${bold(id)} is on ${bold(version ?? "its newest release")}${previous ? dim(` (was ${previous})`) : ""}`);
+}
+
+/**
+ * A 409 from the update door, classified.
+ *
+ * "already at X" is the happy answer to a re-run and reads as a tick; anything
+ * else the door refuses with (a catalog that does not name a version for this
+ * app) is a real gap the developer should see as a warning. Neither is an exit
+ * code — see the header.
+ */
+export function updateConflict(error, id) {
+  const message = typeof error === "string" && error.trim() ? error.trim() : `${id} has nothing newer to move to.`;
+  return { kind: /already at/i.test(message) ? "ok" : "warn", message };
+}
+
+/**
+ * The folder these verbs act in: `--dir`, else the cwd.
+ *
+ * ⚠ NOT `appDirOf` — and the difference is the point. `update`, `rollback` and
+ * `entitle` can name their app with `--app`, so a folder with no manifest.json
+ * is a perfectly legitimate place to run them from (what they need is the
+ * project's `.alexandr/link.json`, not its manifest). `appDirOf` would refuse
+ * that folder, and refuse it with the wrong reason.
+ */
+export function projectFor(flags, cwd = process.cwd()) {
+  return typeof flags.dir === "string" && flags.dir.trim() ? resolve(cwd, flags.dir) : resolve(cwd);
+}
+
+/**
+ * Which app: `--app` when given, else the one this folder declares.
+ *
+ * Pure — it answers `{ id }` or `{ error }` rather than exiting, so the choice
+ * is testable without a process. `--app` is validated against the same grammar
+ * the kernel mints ids with, so a typo is refused here with the rule spelled
+ * out instead of arriving as a 404 from the box.
+ */
+export function resolveAppId(flags, project) {
+  const named = typeof flags.app === "string" ? flags.app.trim() : "";
+  if (named) {
+    if (!APP_ID_RE.test(named)) {
+      return { error: `'${named}' is not an app id — lowercase letters, digits and dashes.` };
+    }
+    return { id: named };
+  }
+  const declared = appIdOf(project);
+  if (!declared) {
+    return {
+      error: `No manifest.json in ${project} to read an app id from — name the app with \`--app <id>\`, or run this inside its folder.`,
+    };
+  }
+  return { id: declared };
+}
+
+/**
+ * POST json to a kernel door → `{ ok, status, data, error, rolledBack }`.
+ *
+ * The kernel's store routes answer with a BODY on failure too (`{ error }`, and
+ * `rolledBack` when an update undid itself), so the status alone is never the
+ * whole answer — a helper that threw away the body would lose the only sentence
+ * worth printing. Shaped like `postMultipart` in deploy.js for the same reason.
+ */
+export async function postKernelJson(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) {
+      return {
+        ok: false,
+        status: res.status,
+        error: typeof data?.error === "string" && data.error ? data.error : `HTTP ${res.status}`,
+        rolledBack: data?.rolledBack === true,
+      };
+    }
+    return { ok: true, status: res.status, data };
+  } catch (e) {
+    return { ok: false, status: 0, error: `couldn't reach ${safeOrigin(url)}: ${e?.message ?? e}` };
+  }
+}
+
+function safeOrigin(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return url;
+  }
+}

package/src/cli.js

@@ -10,6 +10,7 @@ import * as cmd from "./commands.js";
 import { resolveInstance, isMaterialized, kernelPort } from "./instance.js";
 import { kernelUrl, version as kVersion } from "./probe.js";
 import { COMMANDS, completion } from "./completion.js";
+import { app } from "./app/index.js";
 import { EXIT } from "./exit.js";
 
 const pkg = JSON.parse(
@@ -51,6 +52,7 @@ async function version(flags) {
 }
 
 const TABLE = {
+  app,
   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, login: cmd.login, backup: cmd.backup,
@@ -61,7 +63,10 @@ export async function run(argv = process.argv.slice(2)) {
   const flags = parseArgs(argv);
   const sub = flags._.shift();
 
-  if (!sub || flags.help || flags.h) {
+  // ⚠ `--help` is handled HERE for every verb except `app`, whose subcommands
+  // each have their own help (`alexandr app deploy --help`). Swallowing it at
+  // this level would make those unreachable.
+  if (!sub || ((flags.help || flags.h) && sub !== "app")) {
     if (!sub && (flags.version || flags.v)) return version(flags);
     log(HELP);
     return;

package/src/completion.js

@@ -6,12 +6,21 @@
 
 import { fail } from "./util.js";
 import { EXIT } from "./exit.js";
+import { APP_SUBCOMMANDS } from "./app/index.js";
 
 // One row per command: { name, usage, summary }. `usage` is the display form for
 // help (may carry an arg hint like "logs [-f]"); `name` is the bare verb used for
 // completion. Order is the help display order.
 export const COMMANDS = [
   { name: "up", usage: "up", summary: "Sign in (first run), pull + boot the runtime; print the URL" },
+  {
+    name: "app",
+    usage: "app <cmd>",
+    // ⚠ The CANDIDATES come from `APP_SUBCOMMANDS` (src/app/index.js), so tab
+    // completion is right on its own — this line is only the one-line summary a
+    // person reads, and it has to be kept in step by hand.
+    summary: "Develop an app: link | dev | build | deploy | secrets | config | publish | update | rollback | entitle",
+  },
   { name: "down", usage: "down", summary: "Stop the runtime (data preserved)" },
   { name: "status", usage: "status", summary: "Show state, version, URL, and data size" },
   { name: "ls", usage: "ls", summary: "List all alexandr instances" },
@@ -37,6 +46,8 @@ const NAMES = COMMANDS.map((c) => c.name);
 
 // Sub-surfaces worth completing one level deep.
 const CONFIG_SUBS = ["get", "set", "list", "unset"];
+// The `app` verb family (app-system-stage-1.md §2 WP-E) — the laptop door.
+const APP_SUBS = APP_SUBCOMMANDS.map((c) => c.name);
 
 // ---- generators -------------------------------------------------------------
 
@@ -55,6 +66,7 @@ _alexandr() {
   case "\$cmd" in
     completion) COMPREPLY=( \$(compgen -W "${SHELLS.join(" ")}" -- "\$cur") ); return ;;
     config) if [ "\$COMP_CWORD" -eq 2 ]; then COMPREPLY=( \$(compgen -W "${CONFIG_SUBS.join(" ")}" -- "\$cur") ); return; fi ;;
+    app) if [ "\$COMP_CWORD" -eq 2 ]; then COMPREPLY=( \$(compgen -W "${APP_SUBS.join(" ")}" -- "\$cur") ); return; fi ;;
   esac
   if [[ "\$cur" == -* ]]; then
     COMPREPLY=( \$(compgen -W "${GLOBAL_FLAGS.join(" ")}" -- "\$cur") )
@@ -88,6 +100,7 @@ fi
 case "\${words[2]}" in
   completion) _values 'shell' ${SHELLS.join(" ")}; return ;;
   config) (( CURRENT == 3 )) && { _values 'subcommand' ${CONFIG_SUBS.join(" ")}; return } ;;
+  app) (( CURRENT == 3 )) && { _values 'subcommand' ${APP_SUBS.join(" ")}; return } ;;
 esac
 _describe -t options 'option' _alexandr_flags
 `;
@@ -104,6 +117,7 @@ function fishScript() {
   }
   lines.push("complete -c alexandr -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish'");
   lines.push(`complete -c alexandr -n '__fish_seen_subcommand_from config' -a '${CONFIG_SUBS.join(" ")}'`);
+  lines.push(`complete -c alexandr -n '__fish_seen_subcommand_from app' -a '${APP_SUBS.join(" ")}'`);
   for (const f of GLOBAL_FLAGS) {
     if (f.startsWith("--")) lines.push(`complete -c alexandr -l ${f.slice(2)}`);
   }

package/src/consent.js

@@ -0,0 +1,272 @@
+// THE consent ceremony — one implementation, two callers.
+//
+// Extracted from link.js 2026-09-05 (app-system-stage-1.md §2 WP-E). It was
+// written for `alexandr link` (bind this box to an account) and is now also what
+// `alexandr app link` runs, asking for a different SCOPE. Copying it would have
+// meant two ceremonies drifting apart on the security-critical half of the CLI,
+// so it moved here and grew one parameter.
+//
+// Two grant shapes, one ceremony:
+//   - DEVICE (RFC 8628 shape) on a headless machine: the CLI mints a grant,
+//     prints a short code + URL, and polls until a signed-in owner confirms from
+//     ANY device. No tunnel.
+//   - LOOPBACK (OAuth authorization-code + PKCE) on a desktop: the browser and
+//     the CLI share a machine, so the redirect lands instantly.
+//
+// SCOPE (WP-E). The CLI asks at the START and the owner sees it on the consent
+// card; the CP records it on the grant and reads it back at redeem, never from
+// the token request — a PKCE verifier (or a device code) proves possession, not
+// authorization.
+//
+//   (omitted)   -> client "cli-link", 10 minutes. `alexandr link` uses it once.
+//   "app-dev"   -> client "cli", 30 days sliding. `alexandr app link` keeps it.
+//
+// Zero dependencies. Plain Node, like the rest of this CLI.
+
+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, sleep, openURL } from "./util.js";
+
+const b64url = (buf) => buf.toString("base64url");
+
+// 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:47400 + http://localhost:47300) via env. The link-consent
+// page (/cli-auth) is a website surface.
+export const CP_URL = (process.env.ALEXANDR_CP_URL || "https://api.alexandr.so").replace(/\/+$/, "");
+export const APP_URL = (process.env.ALEXANDR_APP_URL || "https://alexandr.so").replace(/\/+$/, "");
+export const TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Run the ceremony this machine can actually complete and return the session it
+ * earned: `{ token, expiresAt, client, scope }` (older control planes answer
+ * with `token` alone, so read the rest defensively).
+ *
+ * Throws on any break in the chain — the caller decides between `fail()` and a
+ * soft skip.
+ */
+export async function consentSession({ host, name, intent = "link", scope, domain } = {}) {
+  return useDeviceFlow()
+    ? deviceGrantSession({ host, name, intent, scope })
+    : loopbackGrantSession({ host, name, intent, scope, domain });
+}
+
+/** The DESKTOP grant — authorization-code + PKCE against a loopback redirect. */
+export async function loopbackGrantSession({ host, name, intent, scope, domain }) {
+  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: host ?? "",
+      name: name ?? "",
+      // ⚠ The consent page relays this into POST /cli-auth/authorize. WITHOUT it
+      // every PKCE `app-dev` link silently gets the 10-minute session instead.
+      ...(scope ? { scope } : {}),
+      // Copy-only hint for the consent card ("refresh" renews the image
+      // credential and registers nothing) — the grant's power is identical.
+      ...(intent && intent !== "link" ? { intent } : {}),
+    }).toString();
+
+  await presentAuthUrl(authUrl, { port, domain });
+
+  const cb = await done;
+  if (cb.state !== state) throw new Error("state mismatch (possible interception).");
+
+  const tok = await postJson(`${CP_URL}/cli-auth/token`, {
+    code: cb.code,
+    codeVerifier: verifier,
+    redirectUri,
+  });
+  if (!tok.data?.token) {
+    throw new Error(
+      `could not exchange the authorization code (${tok.error ?? "malformed response"}).`,
+    );
+  }
+  return tok.data;
+}
+
+/**
+ * The HEADLESS ceremony — the device-authorization flow, because a remote box
+ * can't receive a loopback redirect and making the user build an ssh tunnel for
+ * a sign-in was backwards. Network blips just keep polling; a real rejection
+ * throws.
+ */
+export async function deviceGrantSession({ host, name, intent, scope }) {
+  const mint = await postJson(`${CP_URL}/cli-auth/device`, { host, name, intent, scope });
+  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;
+    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. ALEXANDR_DEVICE_FLOW=1|0 overrides. */
+export function useDeviceFlow() {
+  if (process.env.ALEXANDR_DEVICE_FLOW === "1") return true;
+  if (process.env.ALEXANDR_DEVICE_FLOW === "0") return false;
+  return isHeadless();
+}
+
+/** No local browser to open — a Linux box with no display server. 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).
+ *  - 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): 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. */
+export 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");
+    // Reachability probe for the consent page: /cli-auth pings this before the
+    // user clicks, so a missing ssh tunnel becomes a guided 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();
+      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.
+ */
+export 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}` };
+  }
+}
+
+/** GET json -> `{ data }` / `{ error }`, the read half of postJson. */
+export async function getJson(url, headers = {}) {
+  try {
+    const res = await fetch(url, { headers });
+    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}`, status: res.status };
+    }
+    return data == null ? { error: "malformed response" } : { data };
+  } catch (e) {
+    return { error: `couldn't reach ${new URL(url).origin}: ${e?.message ?? e}` };
+  }
+}
+
+// `fail` is re-exported so callers that want the process-exiting form don't have
+// to import two modules for one ceremony.
+export { fail };

package/src/deps.js

@@ -2,8 +2,7 @@
 // LINUX box (the self-host case), it offers to install them right there — Docker's official
 // convenience script (get.docker.com) + systemd start — instead of failing with a doc link.
 // Interactive-only (a real TTY, an explicit yes), root or sudo. macOS/Windows stay
-// guidance-only: Docker Desktop can't be installed silently, and the product's Mac story
-// ("On this Mac") uses the desktop app's own VM, never Docker.
+// guidance-only: Docker Desktop can't be installed silently.
 
 import { spawnSync } from "node:child_process";
 import { log, ok, warn, step, dim, bold } from "./util.js";