alexandr 0.2.2 → 0.3.0

package/src/app/link.js

@@ -0,0 +1,187 @@
+// `alexandr app link` — point THIS project at a workspace.
+//
+// Two lanes, deliberately different:
+//
+//   alexandr app link                  the account lane. The consent ceremony
+//                                      with scope "app-dev" (a 30-day sliding
+//                                      `cli` session, so a laptop stays linked),
+//                                      then GET /me -> pick a workspace.
+//   alexandr app link --url http://…   the local-trust lane. A box booted with
+//                                      ALEXANDR_LOCAL_TRUST=1 has no CP and no
+//                                      login: record the URL and stop. Nothing
+//                                      is minted because nothing is presented.
+//
+// The account session lands in ~/.alexandr/auth.json (one per machine); the
+// workspace choice lands in <project>/.alexandr/link.json (one per project,
+// gitignored). See ./store.js for why the two are separate files.
+
+import { hostname } from "node:os";
+import { bold, cyan, dim, fail, log, ok, step, warn } from "../util.js";
+import { select } from "../prompt.js";
+import { CP_URL, consentSession, getJson } from "../consent.js";
+import { EXIT } from "../exit.js";
+import { authUsable, clearToken, linkPath, readAuth, writeAuth, writeLink } from "./store.js";
+
+export const APP_DEV_SCOPE = "app-dev";
+
+export const LINK_HELP = `${bold("alexandr app link")} — point this project at a workspace
+
+${bold("USAGE")}
+  alexandr app link [--workspace <id|slug>] [--url <runtime-url>]
+
+${bold("OPTIONS")}
+  --workspace <id>  Pick the workspace without the prompt (id or slug)
+  --url <url>       Link to a local-trust box by URL; no account, no token
+  --relink          Sign in again even if this machine already has a session
+
+${dim("Writes ~/.alexandr/auth.json (your account session) and .alexandr/link.json (this project's workspace).")}`;
+
+export async function appLink(flags, project = process.cwd()) {
+  if (flags.help || flags.h) return void log(LINK_HELP);
+
+  // ── the local-trust lane ────────────────────────────────────────────────────
+  if (typeof flags.url === "string" && flags.url.trim()) {
+    const instanceUrl = normalizeUrl(flags.url);
+    writeLink({ instanceUrl, localTrust: true, linkedAt: new Date().toISOString() }, project);
+    clearToken(project); // a stale token from an account link would only confuse
+    ok(`Linked to ${cyan(instanceUrl)} ${dim("(local trust — no account, no token)")}`);
+    log(dim(`  ${linkPath(project)}`));
+    log("");
+    log(`${cyan("›")} Next: ${bold("alexandr app dev")}`);
+    return;
+  }
+
+  // ── the account lane ────────────────────────────────────────────────────────
+  const session = await ensureAccountSession(Boolean(flags.relink));
+
+  const me = await getJson(`${CP_URL}/me`, { authorization: `Bearer ${session.token}` });
+  if (me.error) {
+    if (me.status === 401) {
+      fail("Your session is no longer valid. Run `alexandr app link --relink`.", EXIT.GENERAL);
+    }
+    fail(`Couldn't read your workspaces: ${me.error}`, EXIT.GENERAL);
+  }
+
+  const workspaces = (me.data?.workspaces ?? []).filter((w) => w?.instanceId);
+  if (workspaces.length === 0) {
+    fail(
+      "No workspace on your account has a runtime yet. Open the Alexandr app and create one, then run this again.",
+      EXIT.NO_INSTANCE,
+    );
+  }
+
+  const chosen = await pickWorkspace(workspaces, flags.workspace);
+  const link = {
+    cpUrl: CP_URL,
+    workspaceId: chosen.id,
+    workspaceName: chosen.name,
+    instanceId: chosen.instanceId,
+    instanceUrl: chosen.instance?.url ?? null,
+    linkedAt: new Date().toISOString(),
+  };
+  writeLink(link, project);
+  clearToken(project);
+
+  ok(`Linked to ${bold(chosen.name)} ${dim(`(${chosen.id})`)}`);
+  if (!link.instanceUrl) {
+    warn("Its runtime isn't running yet — `alexandr app dev` will wait for it.");
+  } else {
+    log(dim(`  ${link.instanceUrl}`));
+  }
+  log("");
+  log(`${cyan("›")} Next: ${bold("alexandr app dev")}`);
+}
+
+/**
+ * The account session this machine holds, signing in if it has none.
+ *
+ * ⚠ Reusing a stored session is the whole reason the `app-dev` scope exists: a
+ * 10-minute `cli-link` grant would mean a browser round trip every time a
+ * developer opened their laptop. `authUsable` checks the CP URL too — a session
+ * minted against a dev control plane is worthless against production.
+ */
+export async function ensureAccountSession(relink = false) {
+  const stored = readAuth();
+  if (!relink && authUsable(stored, CP_URL)) return stored;
+
+  step(`Sign in to your alexandr account ${dim(`(${CP_URL})`)}`);
+  let granted;
+  try {
+    // `name` is what the consent card shows under "Machine" — the box the
+    // developer is sitting at, so they can tell it apart from any other session
+    // on their account page later.
+    granted = await consentSession({
+      host: hostname(),
+      name: hostname(),
+      intent: "link",
+      scope: APP_DEV_SCOPE,
+    });
+  } catch (e) {
+    fail(`Sign-in aborted: ${e.message}`, EXIT.GENERAL);
+  }
+  if (granted.scope && granted.scope !== APP_DEV_SCOPE) {
+    // Fail-closed downgrade: the CP recorded a narrower grant than we asked for.
+    // Say so — a silent 10-minute session becomes a mysterious 401 an hour later.
+    warn(
+      `The control plane granted '${granted.scope}' rather than '${APP_DEV_SCOPE}' — this session is short-lived and you will be asked to sign in again.`,
+    );
+  }
+  const session = {
+    cpUrl: CP_URL,
+    token: granted.token,
+    expiresAt: granted.expiresAt ?? null,
+    client: granted.client ?? null,
+    scope: granted.scope ?? APP_DEV_SCOPE,
+  };
+  writeAuth(session);
+  ok("Signed in.");
+  return session;
+}
+
+/** `--workspace <id|slug>` when given, the picker when a TTY, an error otherwise. */
+async function pickWorkspace(workspaces, wanted) {
+  if (typeof wanted === "string" && wanted.trim()) {
+    const needle = wanted.trim().toLowerCase();
+    const found = workspaces.find(
+      (w) => w.id.toLowerCase() === needle || (w.slug ?? "").toLowerCase() === needle,
+    );
+    if (!found) {
+      fail(
+        `No workspace '${wanted}' with a runtime on your account. Available: ${workspaces
+          .map((w) => w.slug || w.id)
+          .join(", ")}.`,
+        EXIT.USAGE,
+      );
+    }
+    return found;
+  }
+  if (workspaces.length === 1) return workspaces[0];
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    fail(
+      `Several workspaces — name one with --workspace <id|slug>: ${workspaces
+        .map((w) => w.slug || w.id)
+        .join(", ")}.`,
+      EXIT.USAGE,
+    );
+  }
+  return select(
+    "Which workspace does this app develop against?",
+    workspaces.map((w, i) => ({
+      label: `${i + 1}. ${w.name}`,
+      hint: w.instance?.url || w.slug || w.id,
+      value: w,
+    })),
+  );
+}
+
+/** A runtime URL the CLI will actually talk to: origin + no trailing slash. */
+export function normalizeUrl(raw) {
+  const trimmed = String(raw).trim();
+  const withScheme = /^https?:\/\//.test(trimmed) ? trimmed : `http://${trimmed}`;
+  try {
+    const u = new URL(withScheme);
+    return `${u.protocol}//${u.host}`;
+  } catch {
+    return fail(`'${raw}' is not a URL.`, EXIT.USAGE);
+  }
+}

package/src/app/multipart.js

@@ -0,0 +1,53 @@
+// A `multipart/form-data` body, built by hand.
+//
+// ⚠ Hand-rolled rather than `FormData` + `File` on purpose. This CLI declares
+// Node >= 18, where `File` is only in `node:buffer` (it became a global in 20)
+// and `FormData`'s multipart serializer is not something a test can inspect. The
+// sideload route reads exactly two parts — a `package` file and a `sha256`
+// field — so the body is a dozen lines, and a dozen lines that a unit test can
+// read byte for byte beat a global that behaves differently across the versions
+// we support.
+//
+// Zero dependencies, like everything else here.
+
+import { randomBytes } from "node:crypto";
+
+const CRLF = "\r\n";
+
+/**
+ * Build the body for `POST /_kernel/apps/sideload`.
+ *
+ * `parts` is an ordered list of `{ name, value }` (a text field) or
+ * `{ name, filename, data, contentType }` (a file part, `data` a Buffer).
+ * Returns `{ body, contentType, boundary }` — hand `body` straight to `fetch`.
+ */
+export function buildMultipart(parts, boundary = `alexandrFormBoundary${randomBytes(16).toString("hex")}`) {
+  const chunks = [];
+  for (const part of parts) {
+    if (!part?.name) throw new Error("every multipart part needs a name");
+    const headers = [`--${boundary}`];
+    if (part.filename !== undefined) {
+      headers.push(
+        `Content-Disposition: form-data; name="${part.name}"; filename="${part.filename}"`,
+        `Content-Type: ${part.contentType || "application/octet-stream"}`,
+      );
+    } else {
+      headers.push(`Content-Disposition: form-data; name="${part.name}"`);
+    }
+    chunks.push(Buffer.from(headers.join(CRLF) + CRLF + CRLF, "utf8"));
+    chunks.push(part.filename !== undefined ? toBuffer(part.data) : Buffer.from(String(part.value), "utf8"));
+    chunks.push(Buffer.from(CRLF, "utf8"));
+  }
+  chunks.push(Buffer.from(`--${boundary}--${CRLF}`, "utf8"));
+  return {
+    body: Buffer.concat(chunks),
+    contentType: `multipart/form-data; boundary=${boundary}`,
+    boundary,
+  };
+}
+
+function toBuffer(data) {
+  if (Buffer.isBuffer(data)) return data;
+  if (data instanceof Uint8Array) return Buffer.from(data);
+  return Buffer.from(String(data ?? ""), "utf8");
+}

package/src/app/publish.js

@@ -0,0 +1,421 @@
+// `alexandr app publish` — put THIS version of the app in the catalog.
+//
+// The laptop half of the release story (app-system-stage-3.md WP-P, Part 7's
+// two-doors rule). `deploy` puts a build in ONE workspace; `publish` puts a
+// signed, immutable release where every workspace can install it. Six steps:
+//
+//   1. sign in       the account session `app link` already earned
+//   2. read          manifest.json — the id and the version ARE the release
+//   3. key           mint this machine's publisher key once, register the
+//                    PUBLIC half with the control plane
+//   4. build + pack  the same builder and the same packer `deploy` runs
+//   5. sign          ed25519 over `id\nversion\nsha256` (see ./signing.js)
+//   6. POST          /apps/releases as multipart, and print the entry
+//
+// ⚠ A VERSION IS IMMUTABLE. There is no overwrite and no `--force`: the CP
+// answers 409 for a version it already holds, because republishing a number
+// would silently change what every box that already installed it believes it
+// has. The fix is always a version bump, and the message says so.
+//
+// ⚠⚠ THE PRIVATE KEY IS NOT PART OF THIS REQUEST. It is not a field, not an
+// argument, not a log line — only the signature it produced travels. See the
+// header of ./signing.js, and the test that reads the built body back looking
+// for it (`test/app-publish.test.js`).
+
+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 } from "../util.js";
+import { CP_URL, postJson } from "../consent.js";
+import { EXIT } from "../exit.js";
+import { appDirOf, buildApp, loadBuilder } from "./build.js";
+import { formatBytes, postMultipart } from "./deploy.js";
+import { ensureAccountSession } from "./link.js";
+import { buildMultipart } from "./multipart.js";
+import { APP_ID_RE } from "./reach.js";
+import { authUsable, readAuth } from "./store.js";
+import { loadOrMintPublisherKey, markRegistered, mintEphemeralPublisherKey, publisherKeyFromEnv, signRelease } from "./signing.js";
+
+export const PUBLISH_HELP = `${bold("alexandr app publish")} — publish this version to the catalog
+
+${bold("USAGE")}
+  alexandr app publish [--visibility public|private] [--changelog <file|text>]
+                       [--license <spdx>] [--dir <path>]
+
+${bold("OPTIONS")}
+  --visibility <v>  private (only workspaces you entitled — the default) or public (anyone may
+                    install). Public listing needs a publisher grant from an admin; private
+                    publishing is self-serve and always has been
+  --changelog <x>   A file to read, or the notes themselves
+  --license <spdx>  e.g. Apache-2.0 — shown on the app page
+  --dir <path>      The app folder, when it isn't the current one
+  --non-interactive Never open a sign-in: publish with what is already here, or fail at once (CI sets this)
+
+${bold("IN CI")} ${dim("(unattended — no account, no browser)")}
+  ALEXANDR_INSTANCE_ID + ALEXANDR_RUNTIME_SECRET   the workspace's own credential — the release is
+                                                   published AS THAT WORKSPACE (publisher: workspace:<id>)
+  ALEXANDR_PUBLISHER_KEY                           an ed25519 private key PEM (openssl genpkey -algorithm ed25519);
+                                                   without it every run mints and registers a fresh key
+  ALEXANDR_CP_URL                                  the control plane, when it is not the public one
+  CI=1 implies --non-interactive.
+
+${dim("Builds, packages, signs with this machine's publisher key (~/.alexandr/publisher.json, minted on first use) and uploads to the control plane. The version in manifest.json is the release, and a published version is never overwritten — bump it to publish again.")}`;
+
+/** semver.org's grammar, loosely: core + optional prerelease + optional build.
+ *  ⚠ Deliberately a touch looser than the CP's `isSemver` — this check exists to
+ *  say "bump `version`" BEFORE a two-minute build, not to be the authority. The
+ *  control plane is the authority and refuses anything this lets through. */
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+const VISIBILITIES = ["public", "private"];
+
+export async function appPublish(flags, project) {
+  // ⚠ `--help` is answered BEFORE the folder is resolved, which is why `project`
+  // has no `= appDirOf(flags)` default: a default parameter is evaluated before
+  // the body runs, and `appDirOf` EXITS when there is no manifest.json — so
+  // `alexandr app publish --help` outside an app folder would print nothing but
+  // a refusal. The parameter stays injectable for tests.
+  if (flags.help || flags.h) return void log(PUBLISH_HELP);
+  const dir = project ?? appDirOf(flags);
+
+  const visibility = readVisibility(flags.visibility);
+  const changelog = readChangelog(flags.changelog);
+  const license = typeof flags.license === "string" && flags.license.trim() ? flags.license.trim() : null;
+
+  // ── 1. who publishes ────────────────────────────────────────────────────────
+  // A PERSON (the account session — the release belongs to whoever signed it) or,
+  // unattended, a BOX: with `ALEXANDR_INSTANCE_ID` + `ALEXANDR_RUNTIME_SECRET` the
+  // release is published AS THAT WORKSPACE through the envelope the control plane
+  // already accepts (app-system-stage-4.md D9). Non-interactive mode never opens
+  // a sign-in — the alternative on a headless runner was a five-minute device-code
+  // poll nobody would ever answer.
+  const publisher = await resolvePublisher(flags, process.env);
+  const cpUrl = publisher.cpUrl;
+
+  // ── 2. the manifest IS the release ──────────────────────────────────────────
+  const manifestRaw = readManifest(dir);
+  const { id, version } = identityOf(manifestRaw, dir);
+
+  // ── 3. the publisher key ────────────────────────────────────────────────────
+  let record;
+  if (publisher.kind === "instance") {
+    // CI: the key from the environment, or one for this run alone.
+    record = publisherKeyFromEnv(process.env);
+    if (!record) {
+      record = mintEphemeralPublisherKey();
+      warn(
+        `No ALEXANDR_PUBLISHER_KEY — minted a key for this run (${record.keyId}); the workspace keeps ` +
+          "it registered so the release stays verifiable. Set the variable to make every run sign with one key.",
+      );
+    }
+    await registerPublisherKey(record, publisher, cpUrl);
+  } else {
+    let minted;
+    ({ record, minted } = loadOrMintPublisherKey());
+    if (minted) step(`Minted this machine's publisher key ${dim(record.keyId)}`);
+    if (minted || !record.registrations?.[cpUrl]) {
+      await registerPublisherKey(record, publisher, cpUrl);
+      record = markRegistered(undefined, record, cpUrl);
+    }
+  }
+
+  // ── 4. build, then pack ─────────────────────────────────────────────────────
+  const built = await buildApp(dir, { quiet: false });
+  if (!built.ok) fail(built.error, EXIT.GENERAL);
+
+  const { pack } = await loadBuilder(dir);
+  step("Packaging…");
+  const packed = await pack(dir, {
+    outFile: resolve(tmpdir(), `alexandr-publish-${process.pid}-${Date.now()}.tar.gz`),
+  });
+  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)}…`));
+
+  try {
+    // ── 5. sign ───────────────────────────────────────────────────────────────
+    const signature = signRelease(record.privateKey, id, version, packed.sha256);
+
+    // ── 6. upload ─────────────────────────────────────────────────────────────
+    const archive = await readFile(packed.outFile);
+    const { body, contentType } = buildMultipart(
+      publishParts({
+        manifestRaw,
+        archive,
+        id,
+        version,
+        signature,
+        keyId: record.keyId,
+        visibility,
+        changelog,
+        license,
+        // The BOX's envelope rides the body; a person's session rides the header.
+        ...(publisher.kind === "instance" ? { instanceId: publisher.instanceId, secret: publisher.secret } : {}),
+      }),
+    );
+    step(
+      `Publishing ${bold(`${id} ${version}`)} to ${cyan(cpUrl)}${
+        publisher.kind === "instance" ? dim(" as the workspace") : ""
+      }…`,
+    );
+    const res = await postMultipart(
+      `${cpUrl}/apps/releases`,
+      body,
+      contentType,
+      publisher.kind === "session" ? `Bearer ${publisher.token}` : undefined,
+    );
+    if (!res.ok) fail(publishFailure(res, id, version), EXIT.GENERAL);
+
+    const entry = res.data ?? {};
+    ok(
+      `Published ${bold(`${entry.id ?? id} ${entry.version ?? version}`)} ${dim(
+        `(${entry.visibility ?? visibility})`,
+      )}`,
+    );
+    if (entry.sha256) log(dim(`  sha256 ${entry.sha256}`));
+    if (entry.releasedAt) log(dim(`  released ${entry.releasedAt}`));
+    log("");
+    if ((entry.visibility ?? visibility) === "private") {
+      // A private release is LISTED for everyone and downloadable by nobody until
+      // a workspace is entitled — so the next step is not optional, it is the
+      // difference between a release and an installable one.
+      log(`${cyan("›")} Let a workspace install it: ${bold(`alexandr app entitle <workspaceId>`)}`);
+    } else {
+      log(`${cyan("›")} It reaches the catalog on the registry's next merge.`);
+      log(`${cyan("›")} Move a workspace onto it: ${bold("alexandr app update")}`);
+    }
+  } finally {
+    // ⚠ The tarball is a build artifact in the system temp dir, and it outlives
+    // the command unless someone removes it. `finally`, so a refused publish
+    // cleans up exactly like a good one.
+    await rm(packed.outFile, { force: true });
+  }
+}
+
+/**
+ * The multipart parts, in the order the CP's route reads them.
+ *
+ * Split out so a test can read the body back byte for byte: this is the one
+ * place a private key could plausibly be added by accident, and the assertion
+ * that it never appears has to have something to assert against.
+ */
+export function publishParts({
+  manifestRaw,
+  archive,
+  id,
+  version,
+  signature,
+  keyId,
+  visibility,
+  changelog,
+  license,
+  instanceId,
+  secret,
+}) {
+  return [
+    // The RAW manifest text, not a re-serialization: the CP parses this to take
+    // the id, the version and the apiVersion, and stores it whole. Re-encoding it
+    // here would mean the record differs from the file the developer wrote.
+    { name: "manifest", value: manifestRaw },
+    { name: "package", filename: `${id}-${version}.tar.gz`, data: archive, contentType: "application/gzip" },
+    { name: "signature", value: signature },
+    { name: "keyId", value: keyId },
+    { name: "visibility", value: visibility },
+    // Absent, not empty: the CP reads a blank field as unset anyway, but sending
+    // one would claim the developer wrote empty release notes.
+    ...(changelog ? [{ name: "changelog", value: changelog }] : []),
+    ...(license ? [{ name: "license", value: license }] : []),
+    // The workspace's credential, ONLY when a box publishes (CI). The control
+    // plane resolves the pair to `workspace:<id>` and ignores any bearer.
+    ...(instanceId && secret
+      ? [
+          { name: "instanceId", value: instanceId },
+          { name: "secret", value: secret },
+        ]
+      : []),
+  ];
+}
+
+/**
+ * Who this command publishes as.
+ *
+ *   { kind: "instance", instanceId, secret, cpUrl }  — a BOX (CI), from the environment
+ *   { kind: "session",  token, cpUrl }               — a PERSON, from the stored account session
+ *
+ * Non-interactive (`--non-interactive`, or `CI` set to anything but 0/false): no
+ * ceremony is ever started. A usable stored session still counts — a developer's
+ * own script is not a stranger — but nothing else does, and the failure names
+ * exactly the two variables a runner needs.
+ */
+export async function resolvePublisher(flags, env = process.env, deps = {}) {
+  const machine = machineCredential(env);
+  if (machine) return machine;
+  const stored = (deps.readAuth ?? readAuth)();
+  if ((deps.authUsable ?? authUsable)(stored, CP_URL)) {
+    return { kind: "session", token: stored.token, cpUrl: stored.cpUrl || CP_URL };
+  }
+  if (isNonInteractive(flags, env)) {
+    return (deps.fail ?? fail)(
+      "Nothing to publish as: no account session here and no workspace credential. In CI set " +
+        "ALEXANDR_INSTANCE_ID and ALEXANDR_RUNTIME_SECRET (the workspace's own credential — the " +
+        "release is published as that workspace), or run `alexandr app link` on a machine with a browser.",
+      EXIT.USAGE,
+    );
+  }
+  const session = await (deps.ensureAccountSession ?? ensureAccountSession)();
+  return { kind: "session", token: session.token, cpUrl: session.cpUrl || CP_URL };
+}
+
+/** The workspace credential a CI job holds, or null. Both halves or nothing. */
+export function machineCredential(env = process.env) {
+  const instanceId = typeof env.ALEXANDR_INSTANCE_ID === "string" ? env.ALEXANDR_INSTANCE_ID.trim() : "";
+  const secret = typeof env.ALEXANDR_RUNTIME_SECRET === "string" ? env.ALEXANDR_RUNTIME_SECRET.trim() : "";
+  if (!instanceId || !secret) return null;
+  const cpUrl = (typeof env.ALEXANDR_CP_URL === "string" && env.ALEXANDR_CP_URL.trim()) || CP_URL;
+  return { kind: "instance", instanceId, secret, cpUrl: cpUrl.replace(/\/+$/, "") };
+}
+
+/** `--non-interactive`, or the `CI` convention every runner sets. */
+export function isNonInteractive(flags, env = process.env) {
+  if (flags?.["non-interactive"] === true) return true;
+  const ci = typeof env.CI === "string" ? env.CI.trim().toLowerCase() : "";
+  return ci !== "" && ci !== "0" && ci !== "false";
+}
+
+/** The raw manifest text — the release's own record of itself. */
+function readManifest(project) {
+  try {
+    return readFileSync(resolve(project, "manifest.json"), "utf8");
+  } catch (e) {
+    return fail(`Couldn't read ${resolve(project, "manifest.json")}: ${e.message}`, EXIT.NO_INSTANCE);
+  }
+}
+
+/**
+ * The `id` + `version` this folder publishes as, refused here rather than after
+ * a build.
+ *
+ * ⚠ The version gets its OWN message. "manifest.json is invalid" is useless to
+ * someone whose real problem is that they already published 1.0.0 — the one
+ * thing they have to do is bump a number, so the error says that and nothing
+ * else.
+ */
+export function identityOf(manifestRaw, project = ".") {
+  let manifest;
+  try {
+    manifest = JSON.parse(manifestRaw);
+  } catch (e) {
+    return fail(`${resolve(project, "manifest.json")} is not valid JSON: ${e.message}`, EXIT.USAGE);
+  }
+  const id = typeof manifest?.id === "string" ? manifest.id.trim() : "";
+  const version = typeof manifest?.version === "string" ? manifest.version.trim() : "";
+  if (!APP_ID_RE.test(id)) {
+    fail(`manifest.json's id ${id ? `('${id}') ` : ""}must be lowercase letters, digits and dashes.`, EXIT.USAGE);
+  }
+  if (!SEMVER_RE.test(version)) {
+    fail(`'${version}' is not a version — bump \`version\` in manifest.json (e.g. 1.0.0).`, EXIT.USAGE);
+  }
+  // Build metadata is legal semver and NOT installable (a version is a directory name in a
+  // box's release pool). The control plane refuses it too; saying so here saves the build.
+  if (version.includes("+")) {
+    const core = version.split("+")[0];
+    const instead = core.includes("-") ? core : `${core}-rc.1`;
+    fail(
+      `'${version}' carries build metadata (+…), which no workspace can install — use '${instead}' instead (a prerelease tag carries what build metadata would).`,
+      EXIT.USAGE,
+    );
+  }
+  return { id, version };
+}
+
+/**
+ * `private` unless `public` was asked for; anything else is a typo, not a third policy.
+ *
+ * ⚠ THE DEFAULT CHANGED on 2026-09-06 (app-system-stage-5.md WP-X, D18): it was `public`.
+ * A publish that says nothing about who may take the app is a publish nobody thought about,
+ * and "listed for everyone, downloadable by the workspaces you entitled" is the answer that
+ * cannot surprise anybody. The control plane defaults the same way, so an old CLI against a
+ * new control plane and a new CLI against either both land on private.
+ */
+export function readVisibility(raw) {
+  if (raw === undefined || raw === true || raw === "") return "private";
+  const value = String(raw).trim().toLowerCase();
+  if (!VISIBILITIES.includes(value)) {
+    fail(`--visibility must be ${VISIBILITIES.join(" or ")} (got '${raw}').`, EXIT.USAGE);
+  }
+  return value;
+}
+
+/**
+ * `--changelog` is a path OR the notes themselves.
+ *
+ * ⚠ A path that does not exist is TEXT, not an error. Release notes are short
+ * prose, and prose that happens to look like a filename ("v2.md rewrite") must
+ * not become a refusal — so the file is tried, and its absence simply means the
+ * developer typed the notes.
+ */
+export function readChangelog(raw, readText = (f) => readFileSync(f, "utf8")) {
+  if (typeof raw !== "string" || !raw.trim()) return null;
+  try {
+    return readText(resolve(raw)).trim() || null;
+  } catch {
+    return raw.trim();
+  }
+}
+
+/**
+ * Register the PUBLIC half with the control plane.
+ *
+ * ⚠ A 409 IS SUCCESS. The key id is derived from the key bytes, so "already
+ * registered" can only mean the CP holds exactly this key — the same reasoning
+ * that lets the box re-register on every boot (`os/kernel/src/apps/publisher-key.ts`).
+ * Treating it as a failure would strand any laptop whose local record of the
+ * registration was lost while the CP's was not.
+ */
+async function registerPublisherKey(record, publisher, cpUrl) {
+  step(publisher.kind === "instance" ? "Registering the signing key as the workspace…" : "Registering this machine's signing key…");
+  const res = await postJson(
+    `${cpUrl}/publishers/keys`,
+    // The PUBLIC half only. There is no branch of this function that sends the
+    // private one, and there must never be. A box's envelope rides the body.
+    {
+      keyId: record.keyId,
+      publicKey: record.publicKey,
+      ...(publisher.kind === "instance" ? { instanceId: publisher.instanceId, secret: publisher.secret } : {}),
+    },
+    publisher.kind === "session" ? { authorization: `Bearer ${publisher.token}` } : {},
+  );
+  if (res.error && statusOf(res.error) !== 409) {
+    fail(`Couldn't register your signing key: ${res.error}`, EXIT.GENERAL);
+  }
+}
+
+/**
+ * The HTTP status inside one of `postJson`'s error strings.
+ *
+ * ⚠ `postJson` folds the status into the message (`HTTP 409 — …`) and returns no
+ * `status` field, unlike `getJson` and `postMultipart`. Reading it back out here
+ * is deliberately local: consent.js is the shared ceremony both `link` verbs
+ * run, and widening its return shape for one caller is a change to the
+ * security-critical half of the CLI for a cosmetic reason.
+ */
+export function statusOf(error) {
+  const m = /^HTTP (\d{3})\b/.exec(String(error ?? ""));
+  return m ? Number(m[1]) : 0;
+}
+
+/** What went wrong, said as the thing to do about it. */
+export function publishFailure(res, id, version) {
+  if (res.status === 409) {
+    return `${id} ${version} is already published — bump \`version\` in manifest.json and publish again.`;
+  }
+  if (res.status === 403) {
+    // The CP refuses a key it does not hold for this account, and a re-run
+    // re-registers it: the local record of the registration is the only thing
+    // that can be wrong here, and publishing again is what repairs it.
+    return `${res.error} — run \`alexandr app publish\` again to re-register your signing key.`;
+  }
+  if (res.status === 503) return `${res.error} — the control plane cannot store releases right now.`;
+  return `Publish failed: ${res.error}`;
+}