alexandr 0.2.2 → 0.3.1

package/README.md

@@ -16,6 +16,18 @@ npm install -g alexandr
 alexandr up
 ```
 
+> **Prerequisite: Node 18+** (`npx` ships with it). On a fresh server without it, the
+> bootstrap does everything — installs Node LTS, then runs the command above (append
+> flags after `sh -s --`):
+>
+> ```sh
+> curl -fsSL https://get.alexandr.so | sh
+> ```
+>
+> The script is short and readable — its SHA-256 is published at
+> `https://get.alexandr.so/sha256` if you want to verify before running. Everything
+> else — Docker included — the installer handles itself.
+
 On a fresh machine `up` is interactive — it asks how the runtime should be
 reachable (just this machine, or a public domain with automatic HTTPS), the
 port or domain, and the workspace name. Flags (`--domain`, `--port`, `--name`),
@@ -53,16 +65,77 @@ rotation), `up` and `update` offer a quick re-sign-in on the spot — or run
 | `alexandr connect` | Print the `alexandr://connect` link / paste-string |
 | `alexandr link` | Re-link this runtime to your account (`--force` re-registers) |
 | `alexandr login` | Refresh the runtime-image pull credential (sign in, no re-register) |
-| `alexandr update` | Update the runtime image (`--to <tag>`, `--rollback`); auto-snapshots `/data` first (`--no-backup` to skip) |
+| `alexandr update` | Update the runtime image (`--to <tag>`, `--rollback`); auto-snapshots `/data` first (`--no-backup` to skip); keeps the newest 3 snapshots |
+| `alexandr updater serve` | The updater sidecar's entrypoint — runs inside its container; `up` starts it, so the desktop app's update sheet can press "Update now" (`--no-updater` on `up` opts out) |
 | `alexandr backup` / `restore <f>` | Archive / restore the data volume |
 | `alexandr config set <k> <v>` | Edit config (`ai.url`, `model`, `port`, `domain`, …) |
 | `alexandr init` | Write a committable `./alexandr` config folder |
 | `alexandr destroy [--volumes] [--unlink]` | Remove containers (and optionally `/data` / the account record) |
 | `alexandr completion <bash\|zsh\|fish>` | Print a shell completion script |
 | `alexandr doctor` | Check Docker, ports, config |
+| `alexandr app <cmd>` | Develop an app on this machine — see below |
 
 Common flags: `--port`, `--domain`, `--name`, `--dir`, `--open`, `--offline`, `--yes`.
 
+## Building an app
+
+The laptop half of the alexandr app system. Everything the assistant can do inside a
+workspace, you can do from a terminal, against the same engine.
+
+```sh
+npm create alexandr-app@latest my-app   # page | full-stack | tool
+cd my-app
+alexandr app link                       # sign in, pick the workspace  — once
+alexandr app dev                        # Vite, proxied to it          — while you work
+alexandr app deploy                     # build, package, install      — when it is ready
+alexandr app publish                    # sign it, release it          — when you want to share it
+```
+
+| Command | What it does |
+|---|---|
+| `alexandr app link` | Sign in and point this project at a workspace. `--workspace <id>` skips the picker; `--url <url>` links a local-trust box with no account |
+| `alexandr app dev` | Runs the project's Vite with `/_kernel` and `/apps/<id>/api` proxied to the workspace, keeping a short-lived workspace token fresh for the proxy |
+| `alexandr app build` | Runs the project's own `@alexandr/app-build` — the exact builder the workspace runs — into `dist/` |
+| `alexandr app deploy` | Build, package the whole folder, checksum it, and install it in the linked workspace |
+| `alexandr app publish` | Build, package, sign, and publish this version as a release. **Private by default** — listed for everyone, installable only by workspaces you entitled (`alexandr app entitle`); `--visibility public` needs a publisher grant from an admin. Also `--changelog`, `--license` |
+| `alexandr app update` | Move the linked workspace onto the newest release of this app (`--app <id>` for another one) |
+| `alexandr app rollback` | Put it back on the previous release. Your data keeps the newer layout — only additive changes are safe across a rollback |
+| `alexandr app entitle` | Let one workspace install this private app; `--remove` takes it away |
+
+`link` writes your account session to `~/.alexandr/auth.json` (owner-only) and this
+project's workspace to `.alexandr/link.json` (gitignored). The workspace token lives in
+`.alexandr/token.json`, is re-minted while `dev` runs, and is attached **by the proxy** —
+it never reaches the browser.
+
+`deploy` needs the `os.apps.create` permission in that workspace; `update` and `rollback`
+need `os.apps.manage`.
+
+`publish` mints one ed25519 signing key per machine on first use
+(`~/.alexandr/publisher.json`, owner-only) and registers its **public** half with the
+control plane. The private half never leaves that file — not into an argument, a log line,
+or the upload — so a control plane can refuse a release but never forge one. A published
+version is immutable: to publish again, bump `version` in `manifest.json`.
+
+### Publishing from CI
+
+A runner has no account and no browser, so it publishes **as the workspace** instead. A
+scaffolded project (and every repo alexandr creates) carries `.github/workflows/publish.yml`:
+push a tag `v<version>` — the same version as `manifest.json` — and the job builds, packages,
+signs and publishes the release. Every workspace that installed the app is offered the update.
+
+Repository secrets it reads:
+
+| Secret | What |
+|---|---|
+| `ALEXANDR_INSTANCE_ID` + `ALEXANDR_RUNTIME_SECRET` | the workspace's own credential — both are in a self-hosted box's `.env` (written by `npx alexandr link`) |
+| `ALEXANDR_PUBLISHER_KEY` | an ed25519 private key PEM, made once with `openssl genpkey -algorithm ed25519`; without it every run mints and registers a fresh key |
+| `ALEXANDR_CP_URL` | optional — the control plane, when it is not the public one |
+
+By hand: `CI=1 alexandr app publish` (or `--non-interactive`) with those variables set. With
+nothing to publish as, it fails immediately and names the two variables — it never waits for a
+sign-in that cannot happen. The runtime never pulls from git: a release is published, and the
+workspace's own update path installs it.
+
 ## Updates are reversible
 
 `alexandr update` snapshots the data volume into `<instance>/backups/` *before* it

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "alexandr",
-  "version": "0.2.2",
-  "description": "Run the alexandr workspace runtime locally — a thin Docker front door (npx alexandr up). Pulls + boots the published kernel image.",
+  "version": "0.3.1",
+  "description": "Run the alexandr workspace runtime locally (npx alexandr up), and develop alexandr apps against a workspace (alexandr app link | dev | build | deploy).",
   "type": "module",
   "bin": {
     "alexandr": "./bin.js"
   },
   "scripts": {
-    "check": "node scripts/check.mjs"
+    "check": "node scripts/check.mjs",
+    "test": "node --test \"test/**/*.test.js\""
   },
   "files": [
     "bin.js",

package/src/app/build.js

@@ -0,0 +1,124 @@
+// `alexandr app build` — run THE builder, the one the workspace runs.
+//
+// ⚠ The builder is not reimplemented here, and it is not bundled into this CLI
+// either. `@alexandr/app-build` is resolved from the PROJECT's own
+// node_modules, which is what makes a laptop build and a workspace build the
+// same bytes: the app pins a builder version in its package.json, and the app
+// that pinned it gets it. A builder baked into the CLI would drift from the
+// runtime the moment either shipped.
+//
+// A project without it is refused with the command that fixes it, never with a
+// module-not-found stack.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { bold, dim, fail, log, ok, step, warn } from "../util.js";
+import { EXIT } from "../exit.js";
+
+export const BUILD_HELP = `${bold("alexandr app build")} — build this app the way the workspace does
+
+${bold("USAGE")}
+  alexandr app build [--dir <path>]
+
+${dim("Runs the project's own @alexandr/app-build: the frontend bundle into dist/app.iife.js, and dist/server.bundle.js when the manifest declares a server.")}`;
+
+/**
+ * Find `@alexandr/app-build` for `project`: walk up from the project looking for
+ * `node_modules/@alexandr/app-build`, then read its package.json for the entry.
+ *
+ * ⚠ Hand-rolled rather than `require.resolve`. The published package's `exports`
+ * map declares only `types` + `import` (it is ESM), so CJS resolution answers
+ * ERR_PACKAGE_PATH_NOT_EXPORTED — and `import.meta.resolve` is not stable across
+ * every Node 18 this CLI supports. Reading the manifest is boring and works
+ * everywhere, including inside a pnpm store layout.
+ */
+export function resolveAppBuild(project) {
+  let dir = resolve(project);
+  for (;;) {
+    const pkgDir = resolve(dir, "node_modules", "@alexandr", "app-build");
+    const manifest = resolve(pkgDir, "package.json");
+    if (existsSync(manifest)) {
+      try {
+        const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+        const dot = pkg.exports?.["."];
+        const entry =
+          (typeof dot === "string" ? dot : dot?.import ?? dot?.default) ??
+          pkg.module ??
+          pkg.main ??
+          "index.js";
+        return { ok: true, dir: pkgDir, entry: resolve(pkgDir, entry), version: pkg.version };
+      } catch (e) {
+        return { ok: false, error: `@alexandr/app-build is installed but unreadable: ${e.message}` };
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return {
+    ok: false,
+    error:
+      "this project has no @alexandr/app-build. Install it: `npm install --save-dev @alexandr/app-build` (the app scaffold lists it already).",
+  };
+}
+
+/** Load the builder for `project`, or exit with the reason. */
+export async function loadBuilder(project) {
+  const found = resolveAppBuild(project);
+  if (!found.ok) fail(found.error, EXIT.NO_INSTANCE);
+  if (found.entry.endsWith(".ts")) {
+    fail(
+      `@alexandr/app-build at ${found.dir} resolves to TypeScript source, which Node cannot load. Install the published package, or run this verb with bun.`,
+      EXIT.GENERAL,
+    );
+  }
+  return import(pathToFileURL(found.entry).href);
+}
+
+/** The app folder this command acts on: `--dir`, else the cwd. */
+export function appDirOf(flags, cwd = process.cwd()) {
+  const dir = typeof flags.dir === "string" && flags.dir.trim() ? resolve(cwd, flags.dir) : resolve(cwd);
+  if (!existsSync(resolve(dir, "manifest.json"))) {
+    fail(
+      `No manifest.json in ${dir} — run this inside an app folder, or pass --dir. (New app: \`npm create alexandr-app@latest my-app\`.)`,
+      EXIT.NO_INSTANCE,
+    );
+  }
+  return dir;
+}
+
+/**
+ * Build the app. Returns `{ ok, bundlePath, serverBundled }`.
+ *
+ * Shared with `deploy`, which is `build` + `pack` + upload — so the two can never
+ * disagree about what "built" means.
+ */
+export async function buildApp(project, { quiet = false } = {}) {
+  const { buildFrontend, buildServer } = await loadBuilder(project);
+
+  if (!quiet) step("Building the frontend…");
+  const front = await buildFrontend(project);
+  for (const line of front.log ?? []) log(dim(`  ${line}`));
+  for (const w of front.warnings ?? []) warn(w);
+  if (!front.ok) return { ok: false, error: front.error ?? "frontend build failed" };
+
+  if (!quiet) step("Building the server…");
+  const server = await buildServer(project);
+  for (const line of server.log ?? []) log(dim(`  ${line}`));
+  // ⚠ The esbuild fallback (a laptop with no bun) is CLOSE, not byte-identical —
+  // it says so, and so do we, rather than letting a developer discover it when a
+  // release behaves differently from their local build.
+  for (const w of server.warnings ?? []) warn(w);
+  if (!server.ok) return { ok: false, error: server.error ?? "server build failed" };
+
+  return { ok: true, bundlePath: front.bundlePath, serverBundled: !server.skipped };
+}
+
+export async function appBuild(flags) {
+  if (flags.help || flags.h) return void log(BUILD_HELP);
+  const project = appDirOf(flags);
+  const res = await buildApp(project);
+  if (!res.ok) fail(res.error, EXIT.GENERAL);
+  ok(`Built ${dim(res.bundlePath)}${res.serverBundled ? dim(" + dist/server.bundle.js") : ""}`);
+}

package/src/app/config.js

@@ -0,0 +1,326 @@
+// `alexandr app config assign <NAME> --connection <id>` — the terminal door to
+// an app's slot BINDINGS (app-system-stage-2.md §2 WP-L, Part 7's two-doors rule).
+//
+// A slot is a name the app declared. This verb says where its value comes from:
+// a Database connection somebody made in Connections, or the literal that
+// `alexandr app secrets set` put in the secrets engine. Saving restarts the
+// app's server, so the process that comes back is the one with the new
+// environment.
+//
+// ⚠⚠ NO VALUE PASSES THROUGH HERE, in either direction. `GET` answers
+// `hasValue` booleans and connection NAMES; `PUT` accepts `{ connection }` or
+// `{ secret: true }` and REFUSES anything shaped like a value. A connection
+// string typed into this route would land in a plaintext record with no
+// encryption and no audit row — which is the exact thing the secrets engine
+// exists to prevent.
+//
+// ⚠ AND THE PUT IS A REPLACE, NOT A MERGE. Every command here therefore READS
+// the whole slot map first and sends it back with one entry changed. Sending
+// only the entry being assigned would silently un-bind every other slot the app
+// has — an app that started yesterday would stop starting today, for a reason
+// nothing on screen would explain.
+//
+// ⚠ ONE MODULE FOR BOTH VERBS, and the filename is `config.js` for a reason a
+// reader will otherwise trip over: `scripts/check.mjs` refuses to publish any
+// path in the tarball matching /secret/i — the guard that keeps a stray `.env`
+// or token file out of the npm package. A source file called `secrets.js` trips
+// it, and weakening a leak guard to accommodate a filename is the wrong trade.
+// The two verbs are one subject anyway: an app's configuration is its VALUES and
+// its BINDINGS, and `secrets set` performs both steps.
+
+import { bold, cyan, dim, fail, log, ok, step } from "../util.js";
+import { EXIT } from "../exit.js";
+import { getJson } from "../consent.js";
+import { readPipedSecret, secret as promptSecret } from "../prompt.js";
+import { appDirOf } from "./build.js";
+import { appIdOf } from "./deploy.js";
+import { APP_ID_RE, SECRET_NAME_RE, headersFor, putJson, reachWorkspace } from "./reach.js";
+
+export const CONFIG_HELP = `${bold("alexandr app config")} — say where each of this app's declared values comes from
+
+${bold("USAGE")}
+  alexandr app config assign <NAME> --connection <id>   ${dim("point a slot at a Database connection")}
+  alexandr app config assign <NAME> --secret            ${dim("point it at the value you set with `secrets set`")}
+  alexandr app config show                              ${dim("what this app declared, and what fills it")}
+
+${dim("Saving restarts the app's server so the new environment is the one its process has. No value is ever sent or returned here — a literal goes to `alexandr app secrets set`, and a connection is made in Connections.")}`;
+
+/** Read the app's configuration. Exits with the reason rather than half-answering. */
+export async function readConfig(url, authorization, appId) {
+  const res = await getJson(
+    `${url}/_kernel/apps/${encodeURIComponent(appId)}/config`,
+    headersFor(authorization),
+  );
+  if (res.error) {
+    if (res.status === 404) {
+      fail(`The workspace has no app called "${appId}" — deploy it first.`, EXIT.NO_INSTANCE);
+    }
+    if (res.status === 401 || res.status === 403) {
+      fail(
+        `The workspace refused it (${res.status}) — an app's configuration needs the 'os.apps.manage' permission there. ${res.error}`,
+        EXIT.GENERAL,
+      );
+    }
+    fail(`Couldn't read ${appId}'s configuration: ${res.error}`, EXIT.GENERAL);
+  }
+  return res.data;
+}
+
+/**
+ * The stored bindings, as the PUT wants them back.
+ *
+ * ⚠ THE READ-MODIFY-WRITE, in one function, so no caller can forget the read.
+ * `{ secret: true, hasValue: false }` is a slot with nothing behind it and is
+ * DROPPED — sending it back would claim a literal exists where none does.
+ */
+export function bindingsFrom(config) {
+  const out = {};
+  for (const [name, state] of Object.entries(config.slots ?? {})) {
+    if (state && typeof state === "object" && "connection" in state) out[name] = { connection: state.connection };
+    else if (state && state.secret === true && state.hasValue) out[name] = { secret: true };
+  }
+  return out;
+}
+
+/** Write the whole map back and restart the app. */
+export async function writeBindings(url, authorization, appId, slots) {
+  const res = await putJson(
+    `${url}/_kernel/apps/${encodeURIComponent(appId)}/config`,
+    { slots },
+    headersFor(authorization),
+  );
+  if (res.error) {
+    if (res.status === 401 || res.status === 403) {
+      fail(
+        `The workspace refused it (${res.status}) — an app's configuration needs the 'os.apps.manage' permission there. ${res.error}`,
+        EXIT.GENERAL,
+      );
+    }
+    fail(`Couldn't save the configuration: ${res.error}`, EXIT.GENERAL);
+  }
+  return res.data;
+}
+
+/**
+ * Bind ONE slot, keeping every other binding exactly as it was — the shape both
+ * `config assign` and `secrets set` need.
+ */
+export async function bindSlot(url, authorization, appId, name, binding) {
+  const config = await readConfig(url, authorization, appId);
+  const declared = (config.declared ?? []).some((s) => s.name === name);
+  if (!declared) return { bound: false, config };
+  const slots = { ...bindingsFrom(config), [name]: binding };
+  const after = await writeBindings(url, authorization, appId, slots);
+  // ⚠ The PUT answers the new slot STATES but not the declarations (it has no
+  // reason to repeat them) — so the caller gets the GET's shape with the fresh
+  // states folded in, and prints one table rather than two half-tables.
+  return { bound: true, config: { ...config, slots: after.slots ?? config.slots } };
+}
+
+/** One line per declared slot — what it is, and what fills it today. */
+function printSlots(config) {
+  for (const slot of config.declared ?? []) {
+    const state = config.slots?.[slot.name];
+    const filled =
+      state && "connection" in state
+        ? `→ ${state.name ?? state.connection}`
+        : state && state.hasValue
+          ? "→ ••••••••"
+          : dim("not set");
+    const need = slot.required === false ? dim(" (optional)") : "";
+    log(`  ${bold(slot.name.padEnd(24))} ${dim(slot.kind.padEnd(9))} ${filled}${need}`);
+    if (slot.description) log(`  ${dim(" ".repeat(24) + " " + slot.description)}`);
+  }
+}
+
+export async function appConfig(flags) {
+  const sub = flags._.shift();
+  if (flags.help || flags.h || !sub) return void log(CONFIG_HELP);
+  if (sub !== "assign" && sub !== "show") {
+    fail(`Unknown command 'app config ${sub}'. Try: assign | show.`, EXIT.USAGE);
+  }
+
+  const project = appDirOf(flags);
+  const appId = appIdOf(project);
+  if (!appId) fail("This folder's manifest.json names no app id.", EXIT.USAGE);
+  if (!APP_ID_RE.test(appId)) fail(`"${appId}" isn't a valid app id.`, EXIT.USAGE);
+  const { url, authorization } = await reachWorkspace(project);
+
+  if (sub === "show") {
+    const config = await readConfig(url, authorization, appId);
+    log(`${bold(appId)} ${dim(`· data: ${config.data}`)}`);
+    if ((config.declared ?? []).length === 0) {
+      log(dim("  This app declares no configuration."));
+      return;
+    }
+    printSlots(config);
+    return;
+  }
+
+  const name = flags._.shift();
+  if (!name) {
+    fail("Which slot? Usage: alexandr app config assign <NAME> --connection <id>", EXIT.USAGE);
+  }
+  if (!SECRET_NAME_RE.test(name)) {
+    fail(`"${name}" isn't a valid slot name. Letters, digits, _ and - only, up to 64 characters.`, EXIT.USAGE);
+  }
+  // ⚠ THE SAME REFUSAL AS `secrets set`, for the same reason: this route takes
+  // references, so a value on the command line is both unsafe and meaningless.
+  if (flags._.length > 0 || flags.value !== undefined) {
+    fail(
+      "This command takes a reference, not a value. Use --connection <id> for a Database connection, " +
+        "or set the literal with `alexandr app secrets set <NAME>` and then --secret.",
+      EXIT.USAGE,
+    );
+  }
+
+  const connection = typeof flags.connection === "string" ? flags.connection.trim() : "";
+  const literal = flags.secret === true;
+  if (!connection && !literal) {
+    fail("Say where the value comes from: --connection <id>, or --secret.", EXIT.USAGE);
+  }
+  if (connection && literal) {
+    fail("A slot has one source: --connection <id> OR --secret, not both.", EXIT.USAGE);
+  }
+
+  step(`Assigning ${bold(name)} on ${bold(appId)}…`);
+  const binding = connection ? { connection } : { secret: true };
+  const { bound, config } = await bindSlot(url, authorization, appId, name, binding);
+  if (!bound) {
+    fail(
+      `${appId} declares no slot called "${name}". Its manifest lists: ` +
+        ((config.declared ?? []).map((s) => s.name).join(", ") || "nothing") +
+        ".",
+      EXIT.USAGE,
+    );
+  }
+
+  ok(`${bold(name)} is assigned. ${dim("The app's server was restarted with it.")}`);
+  log("");
+  printSlots(config);
+  log("");
+  log(`${cyan("›")} ${dim("Watch it come back: alexandr app deploy tails the same log, or open the app's page in the workspace.")}`);
+}
+
+///////////////////////////////////////////////////////////////////////////////
+export const SECRETS_HELP = `${bold("alexandr app secrets")} — give this app a configuration value
+
+${bold("USAGE")}
+  alexandr app secrets set <NAME> [--dir <path>]
+
+${bold("THE VALUE COMES FROM A PROMPT OR A PIPE — never the command line")}
+  alexandr app secrets set STRIPE_SECRET_KEY          ${dim("asks, with the input hidden")}
+  printf %s "$KEY" | alexandr app secrets set STRIPE_SECRET_KEY
+  alexandr app secrets set KEY < key.txt
+
+${dim("Passing the value as an argument is refused: a command line is in your shell history and in ps output. The value is PUT to the workspace's secrets engine, encrypted at rest, and can never be read back — only replaced.")}
+
+${bold("IT ALSO BINDS THE SLOT")}
+${dim("Storing a value is only half of it: the app's process is given a slot's value only when the slot is BOUND, so this binds it and restarts the server — the same two steps the app's Configuration page takes on Save. To point a slot at a Database connection instead, use `alexandr app config assign`.")}`;
+
+/**
+ * Where the value comes from. Exported for the test, and separated from the
+ * request so the ONE rule this command exists to enforce can be checked without
+ * a workspace, a token or a network.
+ *
+ * `argvRest` is what is left on the command line after the NAME — anything at
+ * all is a refusal.
+ */
+export function refuseValueInArgv(argvRest, flags = {}) {
+  if (argvRest.length > 0) {
+    return (
+      "A value can't be passed on the command line — it would be in your shell history and in " +
+      "`ps` output. Run `alexandr app secrets set <NAME>` and paste it at the prompt, or pipe it: " +
+      `printf %s "$VALUE" | alexandr app secrets set ${argvRest.length ? "<NAME>" : "<NAME>"}`
+    );
+  }
+  for (const key of ["value", "secret", "val"]) {
+    if (flags[key] !== undefined) {
+      return `--${key} isn't accepted — a value comes from the prompt or from stdin, never from the command line.`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Read the value: the pipe when there is one, the hidden prompt otherwise.
+ *
+ * ⚠ `isTTY` IS THE TEST, not an interactivity flag. A piped run has no terminal
+ * to prompt on, so prompting there would hang a CI job forever with no output.
+ */
+export async function readSecretValue(name, { input = process.stdin, output = process.stdout } = {}) {
+  if (!input.isTTY) return await readPipedSecret(input);
+  return await promptSecret(`Value for ${name}`, { input, output });
+}
+
+export async function appSecrets(flags) {
+  const sub = flags._.shift();
+  if (flags.help || flags.h || !sub) return void log(SECRETS_HELP);
+  if (sub !== "set") {
+    fail(`Unknown command 'app secrets ${sub}'. The only one is: set.`, EXIT.USAGE);
+  }
+
+  const name = flags._.shift();
+  if (!name) fail("Which value? Usage: alexandr app secrets set <NAME>", EXIT.USAGE);
+  // ⚠ THE REFUSAL, BEFORE ANYTHING ELSE. Nothing is read, resolved or sent when
+  // a value was typed on the command line — the point is that it never travels.
+  const refusal = refuseValueInArgv(flags._, flags);
+  if (refusal) fail(refusal, EXIT.USAGE);
+  if (!SECRET_NAME_RE.test(name)) {
+    fail(
+      `"${name}" isn't a valid name. Letters, digits, _ and - only, starting with a letter or digit, up to 64 characters.`,
+      EXIT.USAGE,
+    );
+  }
+
+  const project = appDirOf(flags);
+  const appId = appIdOf(project);
+  if (!appId) fail("This folder's manifest.json names no app id.", EXIT.USAGE);
+  if (!APP_ID_RE.test(appId)) fail(`"${appId}" isn't a valid app id.`, EXIT.USAGE);
+
+  const value = await readSecretValue(name);
+  if (!value.trim()) fail("Nothing was given — the value is empty.", EXIT.USAGE);
+
+  const { url, authorization } = await reachWorkspace(project);
+  step(`Setting ${bold(name)} for ${bold(appId)}…`);
+  const res = await putJson(
+    `${url}/_kernel/secrets/app/${encodeURIComponent(appId)}/${encodeURIComponent(name)}`,
+    { value },
+    headersFor(authorization),
+  );
+  if (res.error) {
+    if (res.status === 401 || res.status === 403) {
+      fail(
+        `The workspace refused it (${res.status}) — setting an app's secret needs the 'os.apps.manage' permission there. ${res.error}`,
+        EXIT.GENERAL,
+      );
+    }
+    fail(`Couldn't set ${name}: ${res.error}`, EXIT.GENERAL);
+  }
+
+  // ⚠⚠ VALUE FIRST, BINDING SECOND — the same order the Configuration page saves
+  // in, and for the same reason: the binding PUT restarts the app, and a value
+  // written after it would be missing from the very start it was meant for.
+  //
+  // ⚠ AND THE BINDING IS PART OF THE COMMAND. `resolveAppEnv` reads the CONFIG
+  // record, not the secrets engine: a slot with a stored value and no binding
+  // still counts as missing, so a `set` that stopped at the value would leave the
+  // app refusing to start with the value it was just given sitting right there.
+  const { bound, config } = await bindSlot(url, authorization, appId, name, { secret: true });
+
+  ok(`${bold(name)} is set. ${dim("It is encrypted at rest and can never be read back — only replaced.")}`);
+  if (bound) {
+    log(dim(`  ${appId} is bound to it, and its server was restarted.`));
+  } else {
+    // Stored, deliberately, rather than refused: a manifest is edited and
+    // deployed separately, and a value waiting for its declaration is useful.
+    log(
+      dim(
+        `  ⚠ ${appId} declares no slot called ${name} yet, so nothing is bound. Its manifest lists: ` +
+          ((config.declared ?? []).map((s) => s.name).join(", ") || "nothing") +
+          ".",
+      ),
+    );
+    log(`${cyan("›")} Add it to the manifest's ${bold("secrets")} and deploy, then run this again.`);
+  }
+}