alexandr 0.2.2 → 0.3.1

package/src/app/deploy.js

@@ -0,0 +1,234 @@
+// `alexandr app deploy` — build, package, checksum, upload.
+//
+// THE developer's push-to-update (app-system-foundation.md §4 Part 7). Four
+// steps, no magic:
+//
+//   1. build          the project's own @alexandr/app-build, same as `app build`
+//   2. pack           the WHOLE app folder + its sha256 (never node_modules, a
+//                     .git, a database, or .alexandr/)
+//   3. POST           /_kernel/apps/sideload as multipart: the `package` file
+//                     part and the `sha256` field, with a fresh workspace JWT
+//   4. tail           GET /_kernel/apps/<id>/logs until the install settles
+//
+// ⚠ The sha256 is REQUIRED and the kernel checks it before a byte reaches the
+// volume. It is not a convenience: sideload is the door that introduces NEW
+// executable code into a shared container, and the catalog path has verified for
+// as long as it has existed.
+
+import { readFileSync } from "node:fs";
+import { readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { bold, cyan, dim, fail, log, ok, step, warn, sleep } from "../util.js";
+import { getJson } from "../consent.js";
+import { EXIT } from "../exit.js";
+import { appDirOf, buildApp, loadBuilder } from "./build.js";
+import { buildMultipart } from "./multipart.js";
+import { isLocalTrust, readAuth, authUsable } from "./store.js";
+import { ensureWorkspaceToken } from "./token.js";
+import { requireLink } from "./dev.js";
+
+export const DEPLOY_HELP = `${bold("alexandr app deploy")} — put this app in the linked workspace
+
+${bold("USAGE")}
+  alexandr app deploy [--dir <path>] [--timeout <seconds>]
+
+${dim("Builds, packages the whole app folder with its sha256, and uploads it to /_kernel/apps/sideload. Needs the os.apps.create permission in that workspace.")}`;
+
+/** How long we tail the install log before saying so and stopping. */
+const DEFAULT_TIMEOUT_S = 180;
+
+export async function appDeploy(flags) {
+  if (flags.help || flags.h) return void log(DEPLOY_HELP);
+  const project = appDirOf(flags);
+  const link = requireLink(project);
+
+  // ── auth ────────────────────────────────────────────────────────────────────
+  let authorization = null;
+  let runtimeUrl = link.instanceUrl;
+  if (!isLocalTrust(link)) {
+    const session = readAuth();
+    if (!authUsable(session, link.cpUrl)) {
+      fail("Your account session has expired. Run `alexandr app link --relink`.", EXIT.GENERAL);
+    }
+    const minted = await ensureWorkspaceToken(link, session, { project, force: true });
+    if (!minted.ok) {
+      if (minted.pending) {
+        fail(`The workspace is ${minted.status} — start it, then deploy again.`, EXIT.NO_INSTANCE);
+      }
+      fail(`Couldn't get a workspace token: ${minted.error}`, EXIT.GENERAL);
+    }
+    authorization = `Bearer ${minted.token}`;
+    runtimeUrl = minted.url || runtimeUrl;
+  }
+  if (!runtimeUrl) fail("The linked workspace has no URL yet. Start it, then deploy again.", EXIT.NO_INSTANCE);
+  runtimeUrl = runtimeUrl.replace(/\/+$/, "");
+
+  // ── 1. build ────────────────────────────────────────────────────────────────
+  const built = await buildApp(project, { quiet: false });
+  if (!built.ok) fail(built.error, EXIT.GENERAL);
+
+  // ── 2. pack ─────────────────────────────────────────────────────────────────
+  const { pack } = await loadBuilder(project);
+  const outFile = resolve(tmpdir(), `alexandr-deploy-${process.pid}-${Date.now()}.tar.gz`);
+  step("Packaging…");
+  const packed = await pack(project, { outFile });
+  for (const w of packed.warnings ?? []) warn(w);
+  if (!packed.ok) fail(packed.error ?? "packaging failed", EXIT.GENERAL);
+  log(dim(`  ${packed.files.length} files, ${formatBytes(packed.bytes)}, sha256 ${packed.sha256.slice(0, 12)}…`));
+
+  // ── 3. upload ───────────────────────────────────────────────────────────────
+  // How long this app's log ring already is, so the tail below shows THIS
+  // install and not the history of every earlier one.
+  const logsBefore = await logRingLength(runtimeUrl, appIdOf(project), authorization);
+  try {
+    const archive = await readFile(packed.outFile);
+    const { body, contentType } = buildMultipart([
+      { name: "package", filename: "app.tar.gz", data: archive, contentType: "application/gzip" },
+      { name: "sha256", value: packed.sha256 },
+    ]);
+    step(`Uploading to ${cyan(runtimeUrl)}…`);
+    const res = await postMultipart(`${runtimeUrl}/_kernel/apps/sideload`, body, contentType, authorization);
+    if (!res.ok) {
+      if (res.status === 401 || res.status === 403) {
+        fail(
+          `The workspace refused the upload (${res.status}) — installing an app needs the 'os.apps.create' permission there. ${res.error ?? ""}`.trim(),
+          EXIT.GENERAL,
+        );
+      }
+      fail(`Upload failed: ${res.error}`, EXIT.GENERAL);
+    }
+    const { id, state } = res.data ?? {};
+    if (!id) fail("The workspace accepted the package but named no app.", EXIT.GENERAL);
+    ok(`Installed ${bold(id)} ${dim(`(${state ?? "installed"})`)}`);
+
+    // ── 4. tail ───────────────────────────────────────────────────────────────
+    const timeoutS = Number(flags.timeout) > 0 ? Number(flags.timeout) : DEFAULT_TIMEOUT_S;
+    const settled = await tailInstall(runtimeUrl, id, authorization, {
+      timeoutMs: timeoutS * 1000,
+      installedState: state,
+      startAt: logsBefore,
+    });
+    if (settled.state === "failed") {
+      fail(`${id} failed to start. Fix it and deploy again.`, EXIT.RUNTIME);
+    }
+    log("");
+    log(`${cyan("›")} Open it: ${dim(`${runtimeUrl}/apps/${id}/`)}`);
+  } finally {
+    await rm(packed.outFile, { force: true });
+  }
+}
+
+/**
+ * Follow the app's log ring until the install settles, printing new lines.
+ *
+ * ⚠ It does NOT wait for `ready`, and that is deliberate. `sideload` stages,
+ * migrates and builds synchronously, so a 200 already means installed; the app's
+ * SERVER, meanwhile, is spawned on demand by the first proxied request, so a
+ * freshly deployed app sits at `stopped` forever and a poll for `ready` would
+ * simply time out. What we wait for is the log going quiet — the build lines the
+ * kernel appended — or the state going `failed`.
+ */
+export async function tailInstall(
+  runtimeUrl,
+  id,
+  authorization,
+  {
+    timeoutMs = DEFAULT_TIMEOUT_S * 1000,
+    intervalMs = 1000,
+    quietPolls = 2,
+    installedState,
+    startAt = 0,
+    fetchJson = getJson,
+    // Injected so a unit test can drive the poll loop without writing to the
+    // process's stdout — Node's test runner multiplexes its own protocol there.
+    print = (line) => log(dim(`  ${line}`)),
+  } = {},
+) {
+  const headers = authorization ? { authorization } : {};
+  const deadline = Date.now() + timeoutMs;
+  // ⚠ Start from the ring length we measured BEFORE the upload, not from zero.
+  // `app_logs` is a per-app ring that survives reinstalls, so a second deploy
+  // would otherwise replay the first one's failures as if they had just
+  // happened — the most confusing possible output for someone who just fixed
+  // exactly those errors. Counting rather than timestamping keeps it free of
+  // clock skew between this laptop and the box.
+  let seen = startAt;
+  let quiet = 0;
+  let state = installedState ?? "unknown";
+
+  while (Date.now() < deadline) {
+    const res = await fetchJson(`${runtimeUrl}/_kernel/apps/${encodeURIComponent(id)}/logs`, headers);
+    if (res.error) {
+      // The logs door is a nicety; losing it must not fail a good deploy.
+      return { state, timedOut: false, unreachable: true };
+    }
+    const lines = res.data?.logs ?? [];
+    // A ring that WRAPPED is shorter than where we started — show what is there.
+    if (lines.length < seen) seen = 0;
+    for (const line of lines.slice(seen)) print(line.line ?? line);
+    quiet = lines.length === seen ? quiet + 1 : 0;
+    seen = lines.length;
+    state = res.data?.state ?? state;
+
+    if (state === "failed") return { state, timedOut: false };
+    if (state === "ready") return { state, timedOut: false };
+    if (quiet >= quietPolls) return { state, timedOut: false };
+    await sleep(intervalMs);
+  }
+  warn(`Stopped following the install after ${Math.round(timeoutMs / 1000)}s — check the app page.`);
+  return { state, timedOut: true };
+}
+
+/** The app id this folder declares. Unknown ids simply mean "no ring yet". */
+export function appIdOf(project) {
+  try {
+    const manifest = JSON.parse(readFileSync(resolve(project, "manifest.json"), "utf8"));
+    return typeof manifest?.id === "string" ? manifest.id : null;
+  } catch {
+    return null;
+  }
+}
+
+/** How many lines the app's log ring holds right now. 0 for an app that is new. */
+export async function logRingLength(runtimeUrl, id, authorization, fetchJson = getJson) {
+  if (!id) return 0;
+  const res = await fetchJson(`${runtimeUrl}/_kernel/apps/${encodeURIComponent(id)}/logs`, {
+    ...(authorization ? { authorization } : {}),
+  });
+  return res.data?.logs?.length ?? 0;
+}
+
+/** POST a prebuilt multipart body. Mirrors consent.js's postJson error shape. */
+export async function postMultipart(url, body, contentType, authorization) {
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": contentType, ...(authorization ? { authorization } : {}) },
+      body,
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      const detail = typeof data?.error === "string" && data.error ? ` — ${data.error}` : "";
+      return { ok: false, status: res.status, error: `HTTP ${res.status}${detail}` };
+    }
+    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;
+  }
+}
+
+export function formatBytes(bytes) {
+  if (!Number.isFinite(bytes)) return "?";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/src/app/dev.js

@@ -0,0 +1,177 @@
+// `alexandr app dev` — Vite against a real workspace.
+//
+// The whole verb is three things:
+//   1. make sure a workspace token exists and stays fresh (the CP mints a
+//      5-minute, audience-bound JWT; we re-mint on a timer while Vite runs),
+//   2. write it where the project's vite.config.ts proxy reads it
+//      (`.alexandr/token.json`, re-read per request so a re-mint needs no
+//      restart),
+//   3. spawn the project's OWN vite with ALEXANDR_RUNTIME_URL set.
+//
+// ⚠ The token never reaches the browser. The proxy attaches it server-side,
+// which is why local dev uses the proxied posture rather than the SDK's direct
+// mode: a workspace JWT in page JavaScript would be a credential in the DOM.
+//
+// ⚠ We spawn `node_modules/.bin/vite` directly, never `npm run dev` — the
+// template's `dev` script IS this command, and shelling back through it would
+// recurse.
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { bold, dim, fail, log, step, warn } from "../util.js";
+import { EXIT } from "../exit.js";
+import { appDirOf } from "./build.js";
+import { authUsable, clearToken, isLocalTrust, readAuth, readLink } from "./store.js";
+import { ensureWorkspaceToken, nextRemintDelay } from "./token.js";
+
+export const DEV_HELP = `${bold("alexandr app dev")} — run this app against the linked workspace
+
+${bold("USAGE")}
+  alexandr app dev [--dir <path>] [--port <n>]
+
+${dim("Keeps a fresh workspace token in .alexandr/token.json (the Vite proxy attaches it) and runs the project's vite. Link first: alexandr app link.")}`;
+
+/** The vite executable a project installed. Windows ships a `.cmd` shim. */
+export function viteBin(project, platform = process.platform) {
+  const name = platform === "win32" ? "vite.cmd" : "vite";
+  return resolve(project, "node_modules", ".bin", name);
+}
+
+/** Read the project's link, or exit saying how to make one. */
+export function requireLink(project) {
+  const link = readLink(project);
+  if (!link) {
+    fail("This project isn't linked to a workspace yet. Run `alexandr app link`.", EXIT.NO_INSTANCE);
+  }
+  return link;
+}
+
+/**
+ * The account session for a linked project, or exit.
+ * Local-trust projects never get here — they have nothing to present.
+ */
+export function requireSession(link) {
+  const session = readAuth();
+  if (!authUsable(session, link.cpUrl)) {
+    fail("Your account session has expired. Run `alexandr app link --relink`.", EXIT.GENERAL);
+  }
+  return session;
+}
+
+export async function appDev(flags) {
+  if (flags.help || flags.h) return void log(DEV_HELP);
+  const project = appDirOf(flags);
+  const link = requireLink(project);
+
+  const bin = viteBin(project);
+  if (!existsSync(bin)) {
+    fail(
+      `No vite in ${project}/node_modules — run \`npm install\` (or \`bun install\`) first.`,
+      EXIT.NO_INSTANCE,
+    );
+  }
+
+  let runtimeUrl = link.instanceUrl;
+  let stopRefresh = () => {};
+
+  if (isLocalTrust(link)) {
+    // A local-trust box serves the signed-in app on loopback with no CP rung —
+    // there is no token to mint, and presenting one would be meaningless.
+    clearToken(project);
+    step(`Local-trust box ${dim(runtimeUrl)} — no workspace token needed.`);
+  } else {
+    const session = requireSession(link);
+    const first = await ensureWorkspaceToken(link, session, { project, force: true });
+    if (!first.ok) {
+      if (first.pending) {
+        fail(
+          `The workspace is ${first.status} — start it from the Alexandr app, then run this again.`,
+          EXIT.NO_INSTANCE,
+        );
+      }
+      fail(`Couldn't get a workspace token: ${first.error}`, EXIT.GENERAL);
+    }
+    runtimeUrl = first.url || runtimeUrl;
+    if (!runtimeUrl) fail("The workspace has no URL yet — start it, then run this again.", EXIT.NO_INSTANCE);
+    step(`Linked to ${bold(link.workspaceName ?? link.workspaceId)} ${dim(runtimeUrl)}`);
+    stopRefresh = startTokenRefresh(link, session, project, first.expiresAt);
+  }
+
+  log(dim("  proxying /_kernel and /apps/<id>/api to the workspace"));
+  log("");
+
+  const args = ["--host", "127.0.0.1"];
+  // `--port` is the one argument a person supplies; with the Windows shell in
+  // play (below) it must be a bare number and nothing else.
+  if (flags.port) {
+    const port = Number.parseInt(String(flags.port), 10);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new Error(`--port must be a number between 1 and 65535, got "${flags.port}"`);
+    }
+    args.push("--port", String(port));
+  }
+  const child = spawn(bin, args, {
+    cwd: project,
+    stdio: "inherit",
+    env: { ...process.env, ALEXANDR_RUNTIME_URL: runtimeUrl },
+    // `vite.cmd` is a shell shim: since Node's CVE-2024-27980 fix a `.cmd` cannot
+    // be spawned without `shell` (EINVAL). Arguments are literals + the checked port.
+    shell: process.platform === "win32",
+  });
+
+  const stop = (signal) => {
+    stopRefresh();
+    if (!child.killed) child.kill(signal);
+  };
+  process.on("SIGINT", () => stop("SIGINT"));
+  process.on("SIGTERM", () => stop("SIGTERM"));
+
+  await new Promise((done) => {
+    child.on("exit", (code) => {
+      stopRefresh();
+      process.exitCode = code ?? 0;
+      done();
+    });
+    child.on("error", (err) => {
+      stopRefresh();
+      fail(`Couldn't start vite: ${err.message}`, EXIT.RUNTIME);
+    });
+  });
+}
+
+/**
+ * Keep `.alexandr/token.json` fresh for as long as the dev server runs.
+ *
+ * ⚠ Self-rescheduling rather than a fixed `setInterval`: the delay is computed
+ * from the token we actually hold (`nextRemintDelay`), so a CP that changes the
+ * TTL changes the cadence too. `unref()` keeps the timer from holding the
+ * process open after Vite exits.
+ */
+export function startTokenRefresh(link, session, project, expiresAt, deps = {}) {
+  const { ensure = ensureWorkspaceToken, delayOf = nextRemintDelay, timer = setTimeout } = deps;
+  let handle;
+  let stopped = false;
+
+  const schedule = (when) => {
+    handle = timer(async () => {
+      if (stopped) return;
+      const next = await ensure(link, session, { project, force: true });
+      if (!next.ok) {
+        // A blip is not fatal: the current token is still good for a while, and
+        // the next attempt is soon. A dead session says so once.
+        warn(`Couldn't refresh the workspace token (${next.error}) — retrying.`);
+        schedule(30_000);
+        return;
+      }
+      schedule(delayOf(next.expiresAt));
+    }, when);
+    handle?.unref?.();
+  };
+
+  schedule(delayOf(expiresAt));
+  return () => {
+    stopped = true;
+    if (handle) clearTimeout(handle);
+  };
+}

package/src/app/entitle.js

@@ -0,0 +1,139 @@
+// `alexandr app entitle <workspaceId>` — let one workspace install a PRIVATE app.
+//
+// A private release is LISTED for everyone and downloadable by nobody
+// (app-system-stage-3.md WP-O §1.9): being discoverable is the point, and taking
+// it is what needs a grant. This verb is the publisher's half of that — the
+// control-plane door `POST /apps/:appId/entitlements`, and `--remove` for the
+// DELETE.
+//
+// ⚠ AN ACCOUNT ACT, NOT A WORKSPACE ONE. It never touches the box: the CP asks
+// only whether the caller is the app's publisher (or an operator), because a
+// workspace cannot be allowed to entitle itself to somebody else's app. That is
+// also why there is no `--workspace` link to read — the workspace being entitled
+// is named on the command line, and it is somebody else's.
+//
+// ⚠ Public apps need none of this, and entitling one is a no-op with a
+// misleading tick — so the copy always says what an entitlement is FOR.
+
+import { bold, cyan, dim, fail, log, ok, step } from "../util.js";
+import { CP_URL, postJson } from "../consent.js";
+import { EXIT } from "../exit.js";
+import { ensureAccountSession } from "./link.js";
+import { projectFor, resolveAppId } from "./update.js";
+
+export const ENTITLE_HELP = `${bold("alexandr app entitle")} — let a workspace install this private app
+
+${bold("USAGE")}
+  alexandr app entitle <workspaceId> [--remove] [--app <id>] [--dir <path>]
+
+${bold("OPTIONS")}
+  --remove      Take the entitlement away again
+  --app <id>    The app, when it isn't the one in this folder
+  --dir <path>  The app folder, when it isn't the current one
+
+${dim("A private release is listed for everyone and downloadable only by an entitled workspace. Only the app's publisher (or an operator) may change that.")}`;
+
+export async function appEntitle(flags, project) {
+  // ⚠ `--help` before anything that can exit — see the note in publish.js.
+  if (flags.help || flags.h) return void log(ENTITLE_HELP);
+
+  const workspaceId = String(flags._.shift() ?? "").trim();
+  if (!workspaceId) {
+    fail("Name the workspace: `alexandr app entitle <workspaceId>`.", EXIT.USAGE);
+  }
+
+  const dir = project ?? projectFor(flags);
+  const chosen = resolveAppId(flags, dir);
+  if (chosen.error) fail(chosen.error, EXIT.USAGE);
+  const appId = chosen.id;
+
+  const session = await ensureAccountSession();
+  const cpUrl = session.cpUrl || CP_URL;
+  const base = `${cpUrl}/apps/${encodeURIComponent(appId)}/entitlements`;
+  const headers = { authorization: `Bearer ${session.token}` };
+  const removing = Boolean(flags.remove);
+
+  step(
+    `${removing ? "Removing" : "Granting"} ${bold(appId)} for ${bold(workspaceId)} ${dim(`(${cpUrl})`)}…`,
+  );
+  const res = removing
+    ? await deleteJson(`${base}/${encodeURIComponent(workspaceId)}`, headers)
+    : await postEntitlement(base, workspaceId, headers);
+
+  if (!res.ok) {
+    if (res.status === 403) {
+      fail(
+        `The control plane refused it (403) — only the app's publisher (or an admin) can change entitlements. ${res.error ?? ""}`.trim(),
+        EXIT.GENERAL,
+      );
+    }
+    if (res.status === 404) {
+      // Two different 404s, and the CP's own sentence tells them apart: an app
+      // with no releases has no publisher yet, and an unknown workspace id is a
+      // typo. Print what it said rather than guessing which.
+      fail(`${res.error} — nothing changed.`, EXIT.GENERAL);
+    }
+    fail(`Couldn't ${removing ? "remove" : "grant"} the entitlement: ${res.error}`, EXIT.GENERAL);
+  }
+
+  if (removing) {
+    ok(`${bold(workspaceId)} can no longer install ${bold(appId)}.`);
+  } else {
+    ok(`${bold(workspaceId)} can now install ${bold(appId)}.`);
+  }
+  log("");
+  log(
+    `${cyan("›")} ${dim(
+      removing
+        ? "A workspace that already installed it keeps what it has — the entitlement gates the download, not the copy on its volume."
+        : "An entitled workspace may download this private app; everyone else still only sees it listed.",
+    )}`,
+  );
+}
+
+/** POST the grant. `postJson` folds the status into its error string, so the
+ *  status is read back out — the same reason publish.js has `statusOf`. */
+async function postEntitlement(base, workspaceId, headers) {
+  const res = await postJson(base, { workspaceId }, headers);
+  if (res.error) {
+    const m = /^HTTP (\d{3})\b/.exec(res.error);
+    return { ok: false, status: m ? Number(m[1]) : 0, error: res.error };
+  }
+  return { ok: true, status: 200, data: res.data };
+}
+
+/**
+ * DELETE json → `{ ok, status, data, error }`.
+ *
+ * Written here because the CLI's shared helpers stop at GET, POST and PUT, and
+ * this is the only DELETE in the family.
+ *
+ * ⚠ THE SUCCESS CASE HAS NO BODY. The route answers 204, so there is nothing to
+ * parse — `res.json()` is allowed to reject and the rejection is swallowed,
+ * because calling `JSON.parse("")` on an empty 204 would turn the successful
+ * answer into a thrown SyntaxError.
+ */
+export async function deleteJson(url, headers = {}) {
+  try {
+    const res = await fetch(url, { method: "DELETE", headers });
+    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}`,
+      };
+    }
+    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/app/index.js

@@ -0,0 +1,125 @@
+// The `app` verb family — the LAPTOP door of the app system.
+//
+// `alexandr app link | dev | build | deploy` is the developer half of the
+// two-doors rule (app-system-foundation.md §3): everything the assistant can do
+// inside a workspace, a developer can do from a terminal, against the same
+// kernel engine. The UI door stays the primary one; this exists so an outside
+// developer is never blocked on it.
+//
+//   link      sign in, pick the workspace, remember both
+//   dev       Vite against that workspace — live data, hot reload
+//   build     the workspace's own builder, on your machine
+//   deploy    build -> package -> checksum -> sideload
+//   secrets   give the app a value it declared (prompt or pipe — never argv)
+//   config    say where each declared value comes from, and restart the app
+//   publish   build -> pack -> sign -> the catalog, as a release
+//   update    move the linked workspace onto the newest release
+//   rollback  put it back on the one before
+//   entitle   let a workspace install this private app
+//
+// The last four are the RELEASE half (app-system-stage-3.md §2 WP-P): `deploy`
+// puts a build in ONE workspace, `publish` puts a signed, immutable release
+// where every workspace can install it.
+//
+// The verbs live one per file; this module is the dispatcher and the help.
+
+import { bold, cyan, dim, fail, log } from "../util.js";
+import { EXIT } from "../exit.js";
+import { appLink, LINK_HELP } from "./link.js";
+import { appDev, DEV_HELP } from "./dev.js";
+import { appBuild, BUILD_HELP } from "./build.js";
+import { appDeploy, DEPLOY_HELP } from "./deploy.js";
+// The CONFIGURATION half (app-system-stage-2.md §2 WP-L): the same two steps the
+// app's own Configuration page takes, from a terminal.
+// ⚠ ONE module for both verbs — see the note at the top of ./config.js for why
+// it is not called secrets.js.
+import { appConfig, appSecrets, CONFIG_HELP, SECRETS_HELP } from "./config.js";
+// The RELEASE half (app-system-stage-3.md §2 WP-P). `publish` and `entitle` talk
+// to the CONTROL PLANE with the account session; `update` and `rollback` talk to
+// the BOX with a fresh workspace token — two different doors, deliberately.
+import { appPublish, PUBLISH_HELP } from "./publish.js";
+import { appUpdate, UPDATE_HELP } from "./update.js";
+import { appRollback, ROLLBACK_HELP } from "./rollback.js";
+import { appEntitle, ENTITLE_HELP } from "./entitle.js";
+
+/** One row per subcommand — help and completion read the same list. */
+export const APP_SUBCOMMANDS = [
+  { name: "link", summary: "Sign in and point this project at a workspace" },
+  { name: "dev", summary: "Run this app against the linked workspace (Vite + hot reload)" },
+  { name: "build", summary: "Build this app the way the workspace does" },
+  { name: "deploy", summary: "Build, package, and install it in the linked workspace" },
+  { name: "secrets", summary: "Give it a value it declared (from a prompt or a pipe, never argv)" },
+  { name: "config", summary: "Say where each declared value comes from; restarts the app" },
+  { name: "publish", summary: "Sign this version and publish it to the catalog" },
+  { name: "update", summary: "Move the linked workspace onto the newest release" },
+  { name: "rollback", summary: "Put it back on the previous release (your data keeps the newer layout)" },
+  { name: "entitle", summary: "Let a workspace install this private app" },
+];
+
+const HELP = `${bold("alexandr app")} — develop an alexandr app on this machine
+
+${bold("USAGE")}
+  alexandr app <command> [options]
+  npm create alexandr-app@latest my-app   ${dim("start a new one")}
+
+${bold("COMMANDS")}
+${APP_SUBCOMMANDS.map((c) => `  ${c.name.padEnd(9)} ${c.summary}`).join("\n")}
+
+${bold("THE LOOP")}
+  ${cyan("1.")} alexandr app link      ${dim("once per project")}
+  ${cyan("2.")} alexandr app dev       ${dim("while you work")}
+  ${cyan("3.")} alexandr app deploy    ${dim("when it is ready")}
+  ${cyan("4.")} alexandr app secrets set DATABASE_URL          ${dim("if it declared one")}
+     alexandr app config assign DATABASE_URL --connection shop-db
+  ${cyan("5.")} alexandr app publish   ${dim("when you want to share it")}
+
+${dim("alexandr app <command> --help for one command's options.")}`;
+
+const HELPS = {
+  link: LINK_HELP,
+  dev: DEV_HELP,
+  build: BUILD_HELP,
+  deploy: DEPLOY_HELP,
+  secrets: SECRETS_HELP,
+  config: CONFIG_HELP,
+  publish: PUBLISH_HELP,
+  update: UPDATE_HELP,
+  rollback: ROLLBACK_HELP,
+  entitle: ENTITLE_HELP,
+};
+
+const TABLE = {
+  link: appLink,
+  dev: appDev,
+  build: appBuild,
+  deploy: appDeploy,
+  secrets: appSecrets,
+  config: appConfig,
+  publish: appPublish,
+  update: appUpdate,
+  rollback: appRollback,
+  entitle: appEntitle,
+};
+
+/** `alexandr app …`. Registered in cli.js's TABLE beside the runtime verbs. */
+export async function app(flags) {
+  const sub = flags._.shift();
+  if (!sub) {
+    // `--help` with no subcommand is the family's help, not an error.
+    log(HELP);
+    if (!flags.help && !flags.h) process.exitCode = EXIT.OK;
+    return;
+  }
+  if (sub === "help") {
+    const target = flags._.shift();
+    return void log(HELPS[target] ?? HELP);
+  }
+  const handler = TABLE[sub];
+  if (!handler) {
+    fail(
+      `Unknown command 'app ${sub}'. Try: ${APP_SUBCOMMANDS.map((c) => c.name).join(" | ")}.`,
+      EXIT.USAGE,
+    );
+  }
+  await handler(flags);
+}