5095a21 · a4db794 · 3b37a3c · cacf846
@@ -0,0 +1,48 @@
# A pinned forge (#8697)
A pinned forge is a forge the owner put on their own cloud. It has **no crew** and **no automatic release**. Its version and config change only through one explicit `Update`, recorded with who and when; `Rollback` is one action to the previous version.
## Doors (forge admin, admin-scope token)
- HTTP: `GET /api/v1/admin/pinned` (forges, their changes, the targets), `POST /api/v1/admin/pinned` (deploy), `POST /api/v1/admin/pinned/:name/update`, `POST /api/v1/admin/pinned/:name/rollback`.
- Terminal: palette → **Pinned forges** (forge admin): `d` deploy, `u` update, `r` roll back; it follows the bus, so a change made at any door shows at once (`src/tui/screens/pinned.ts`).
- MCP: `pinned_forge` with `verb` `list`, `deploy`, `update`, `rollback` — the same words and the same checks (`src/actions/pinned.ts`).
A deploy names a cloud account (Settings → Cloud accounts, **writes allowed**), the app (`owner/name`), a git `source` (https) and a `version` (a 40-character commit id or a tag like `v1.2.3` — never a branch, so nothing moves under it).
## Why it cannot move on its own
`pinned_forge.version` and `.config` are guarded by a SQLite trigger (migration `20261103090000-pinned-forge`): an UPDATE passes only with a `change_id` that points at a newer `update` or `rollback` row in `pinned_change` whose target is exactly the new version and config. `pinned_change` cannot be updated or deleted. `crew` and `auto_release` are CHECKed to 0. `test/pinned-forge.test.ts` tries each other way and fails if one works. A pinned forge is a row and a droplet, not a repository on this forge, so the crew, the release keeper and upstream following have nothing of it to touch.
## Credentials
The cloud token stays sealed. It is opened for the one call that needs it (a `secret.read` event names the run), sent as an `Authorization` header over HTTPS, and never reaches argv, a row, an event, a request body or the boot script. The boot script holds no secret: the new forge's first visitor claims it. Config refuses names that look like secrets.
## Targets: what runs, what it costs, what is refused
Prices are list prices as last read (USD a month); the owner's own bill is the truth. Source of truth in code: `src/cloud/targets.ts`.
| Target | Status | What runs | Cost | Refused / caveat |
|---|---|---|---|---|
| DigitalOcean | **deploys today** | One droplet (`s-1vcpu-2gb`, Ubuntu 24.04) with a 10 GiB block volume as `FORGE_APP_DATA`. An Update deletes the droplet and starts a new one on the same volume, so data is untouched. | ~$12 + ~$1.20 | A token cannot be narrowed below "create droplets and volumes". |
| AWS | not written | EC2 `t4g.small` + EBS gp3, same boot script; SigV4 already exists for reads. | ~$12 + ~$0.80 + public IPv4 ~$3.65 | Wants a role scoped to a tag rather than a long-lived key. |
| Azure | not written | B1ms VM + managed disk through a service principal on one resource group. | ~$15 + ~$1 + public IP ~$3.65 | Needs a resource group, network and public IP first: three calls more. |
| Cloudflare | **refused** | Workers/Durable Objects keep state, but not as files a Bun process opens. Containers run, with a disk wiped on sleep or replace. | Workers Paid from $5 | No volume that survives; the forge refuses rather than lose repositories quietly. |
| Vercel | **refused** | Functions and Sandboxes: short-lived, scratch disk. | Pro from $20/seat | No long-running process, no persistent disk. Vercel can host an app a forge ships, not the forge. |
The cloud facts for Cloudflare and Vercel are from memory of their documentation, last written 2026-11-02; check them before relying on a refusal for a decision beyond this forge.
## Prior art
Open-source "Deploy to" buttons (Heroku's `app.json`, Render's `render.yaml`, DigitalOcean's App Platform button, Railway templates) are a link carrying a repository and a settings file to a provider's sign-in. That is the shape for the button: a link with `app`, `source`, `version` that lands on the Deploy form after one sign-in. The older `deploy/` cloud path and the child-forge path (#4416, #2928, #3785) are the other prior art; neither pins.
## Failing half-way
Each id is recorded the moment it exists. A first deploy that fails before a droplet exists leaves a `failed` row with the volume's id; deploying the same name again reuses that volume. An Update deletes the old droplet and clears its id at once; a 404 on that delete counts as deleted, so after a failed create a Rollback or another Update goes straight to creating. A `failed` forge may be told the version it already has, to finish the replacement. The droplet installs the Bun in `BUN_VERSION` (`src/cloud/droplet.ts`), so the runtime moves only when a pull moves it.
## Not done
- No canary on a real account: #8746.
- No `Deploy to…` page or link: #8744.
- The droplet's address is not read back, so no URL is shown, no TLS or domain, no health check: #8745.
- AWS and Azure drivers.
@@ -0,0 +1,147 @@
/**
 * Pinned forges, as a forge admin reaches them (#8697): `deploy` puts one on
 * the owner's cloud, `update` is the only way its version or config change,
 * `rollback` is one action back to the previous version. All three are the
 * admin's, need the cloud account's writes switched on, and open the sealed
 * token for the one call that needs it (a `secret.read` event names it). Each
 * change is recorded with who and when before the cloud is touched; if the
 * cloud refuses, the record stays and the forge says `failed`, so nothing
 * moves without a line saying so.
 */
import type { App } from "../app.ts";
import { gatedFetch } from "../cloud/gate.ts";
import { provision, replace } from "../cloud/droplet.ts";
import type { Fetch } from "../cloud/providers.ts";
import { target as targetOf } from "../cloud/targets.ts";
import { getCloudAccount, secretNameOf } from "../core/cloud_account.ts";
import {
  APP, NAME, changesOf, checkConfig, getPinned, insertPinned, listPinned, previousOf,
  dropPinned, recordChange, setRemote, validSource, validVersion, type Change, type Pinned,
} from "../core/pinned.ts";
import { resolveSecrets } from "../core/secret_store.ts";
import type { User } from "../core/users.ts";
import { err, ok, type Result } from "../kernel/result.ts";
/** Swapped in tests; the real forge always uses `fetch`. */
export const net: { fetch: Fetch } = { fetch: (u, i) => fetch(u, i) };
const admin = (a: User | undefined): Result<User, string> => (a?.isAdmin ? ok(a) : err("not_found"));
export interface PinnedView extends Pinned {
  readonly crew: false;
  readonly autoRelease: false;
  readonly changes: Change[];
}
const view = (app: App, p: Pinned): PinnedView => ({ ...p, crew: false, autoRelease: false, changes: changesOf(app.db, p.id) });
export function pinnedForges(app: App, actor: User | undefined): Result<PinnedView[], string> {
  const who = admin(actor);
  return who.ok ? ok(listPinned(app.db).map((p) => view(app, p))) : who;
}
/** Open the account's token and run `go` with a gated fetch; the token never leaves this scope. */
async function withCloud<T>(app: App, who: User, p: Pinned, purpose: string, go: (f: Fetch, token: string) => Promise<T>): Promise<Result<T, string>> {
  const account = getCloudAccount(app.db, p.target, p.account);
  if (!account) return err("No such cloud account.");
  if (!account.writeAllowed) return err("That cloud account is read-only; allow writes on it first.");
  const secret = secretNameOf(account.provider, account.name);
  const token = resolveSecrets(app.db, app.config.dataDir, app.bus, [secret], { actor: who.id, run: `pinned:${purpose}` })[secret];
  if (token === undefined) return err("No such credential.");
  try {
    return ok(await go(gatedFetch(app.db, { provider: p.target, account: p.account }, `pinned:${purpose}`, net.fetch), token));
  } catch (e) {
    return err(`The cloud refused: ${e instanceof Error ? e.message.slice(0, 200) : "failed"}`);
  }
}
export async function deployPinned(
  app: App,
  actor: User | undefined,
  input: { name: string; target: string; account: string; app: string; source: string; version: string; config?: unknown },
): Promise<Result<PinnedView, string>> {
  const who = admin(actor);
  if (!who.ok) return who;
  const t = targetOf(input.target);
  if (!t) return err("That is not a target the forge knows.");
  if (t.status === "refused") return err(t.refused);
  if (t.status !== "first") return err(`${t.label} is not written yet: ${t.refused}`);
  if (!NAME.test(input.name)) return err("A name is lowercase letters, digits and dashes, starting with a letter.");
  if (!APP.test(input.app)) return err("Name the app as owner/name.");
  if (!validSource(input.source)) return err("The source is an https git address.");
  if (!validVersion(input.version)) return err("A version is a full 40-character commit id or a tag like v1.2.3.");
  const config = checkConfig(input.config);
  if (!config.ok) return config;
  // A first deploy that failed before any droplet exists may be tried again: its row goes,
  // its volume (if one was made) is kept for the retry, and the new deploy is recorded afresh.
  const old = getPinned(app.db, input.name);
  if (old && !(old.state === "failed" && old.remote === "" && old.target === t.id)) return err("A pinned forge has that name already.");
  if (old) dropPinned(app.db, old.name);
  const p = insertPinned(app.db, { ...input, target: t.id, config: config.value }, who.value.id);
  app.bus.append({ kind: "pinned.deployed", actorId: who.value.id, payload: { name: p.name, target: p.target, version: p.version } });
  if (old?.volume) setRemote(app.db, p.name, { volume: old.volume });
  const made = await withCloud(app, who.value, p, "deploy", (f, token) =>
    provision(f, token, getPinned(app.db, p.name)!, {
      ...(old?.volume ? { have: old.volume } : {}),
      onVolume: (volume) => setRemote(app.db, p.name, { volume }),
    }),
  );
  if (!made.ok) {
    setRemote(app.db, p.name, { state: "failed" });
    return made;
  }
  setRemote(app.db, p.name, { ...made.value, state: "running" });
  return ok(view(app, getPinned(app.db, p.name)!));
}
async function change(
  app: App,
  actor: User | undefined,
  name: string,
  kind: "update" | "rollback",
  next: (p: Pinned) => Result<{ version: string; config: Record<string, string> }, string>,
): Promise<Result<PinnedView, string>> {
  const who = admin(actor);
  if (!who.ok) return who;
  const before = getPinned(app.db, name);
  if (!before) return err("No such pinned forge.");
  const to = next(before);
  if (!to.ok) return to;
  const same = to.value.version === before.version && JSON.stringify(to.value.config) === JSON.stringify(before.config);
  // A failed forge may be asked again for what it already says, to finish the replacement; nothing new to record.
  if (same && before.state !== "failed") return err("That is what it runs already.");
  if (!same) {
    const c = recordChange(app.db, before, kind, to.value, who.value.id);
    app.bus.append({ kind: kind === "update" ? "pinned.update" : "pinned.rollback", actorId: who.value.id, payload: { name, from: c.fromVersion, to: c.toVersion } });
  }
  const after = getPinned(app.db, name)!;
  const done = await withCloud(app, who.value, after, kind, (f, token) => replace(f, token, after, { onDeleted: () => setRemote(app.db, name, { remote: "" }) }));
  if (!done.ok) {
    setRemote(app.db, name, { state: "failed" });
    return done;
  }
  setRemote(app.db, name, { ...done.value, state: "running" });
  return ok(view(app, getPinned(app.db, name)!));
}
/** The only door to a new version or config. Either may be left as it is. */
export const updatePinned = (
  app: App,
  actor: User | undefined,
  name: string,
  input: { version?: string | undefined; config?: unknown },
): Promise<Result<PinnedView, string>> =>
  change(app, actor, name, "update", (p) => {
    const version = input.version ?? p.version;
    if (!validVersion(version)) return err("A version is a full 40-character commit id or a tag like v1.2.3.");
    const config = input.config === undefined ? ok(p.config) : checkConfig(input.config);
    return config.ok ? ok({ version, config: config.value }) : config;
  });
/** One action back to what the latest change replaced. */
export const rollbackPinned = (app: App, actor: User | undefined, name: string): Promise<Result<PinnedView, string>> =>
  change(app, actor, name, "rollback", (p) => {
    const prev = previousOf(app.db, p);
    return prev ? ok(prev) : err("There is no previous version: this forge has only ever run one.");
  });
@@ -0,0 +1,123 @@
/**
 * DigitalOcean, the first target (#8697): the requests that put a pinned
 * forge on a droplet with a volume, and replace the droplet on an explicit
 * Update while the volume — the forge's data — stays. Plain data in, plain
 * data out: the caller owns the token and the fetch. The token travels in an
 * Authorization header over HTTPS, never on argv, and the boot script holds no
 * secret at all: the new forge's first visitor claims it at /first-admin.
 *
 * Calls (DigitalOcean API v2): POST /volumes, POST /droplets, DELETE /droplets/{id}.
 * The caller records each id the moment it exists (`onVolume`, `onDeleted`),
 * so a failure half-way leaves a row a retry can finish, never an orphan.
 */
import type { Fetch } from "./providers.ts";
import type { Pinned } from "../core/pinned.ts";
const API = "https://api.digitalocean.com/v2";
export const REGION = "nyc3";
export const SIZE = "s-1vcpu-2gb";
/** The Bun the droplet installs: it moves only when this line does, in a pull, so the runtime is pinned as the forge is. */
export const BUN_VERSION = "1.3.14";
/** cloud-config for the droplet: Bun, the pinned source at the pinned version, a systemd unit. */
export function bootConfig(p: Pick<Pinned, "name" | "source" | "version" | "config">): string {
  // DigitalOcean mounts a volume at /mnt/<its name, dashes as underscores>.
  const data = `/mnt/${volumeName(p.name).replace(/-/g, "_")}`;
  const env = Object.entries({ ...p.config, FORGE_APP_DATA: data })
    .map(([k, v]) => `${k}=${v}`)
    .join("\n");
  // Every interpolated value is validated in core/pinned.ts (version, source, config) or by NAME.
  return `#cloud-config
write_files:
  - path: /etc/forge/env
    permissions: "0600"
    content: ${JSON.stringify(env + "\n")}
  - path: /etc/systemd/system/forge.service
    content: |
      [Unit]
      Description=forge ${p.name} pinned at ${p.version}
      After=network-online.target
      [Service]
      EnvironmentFile=/etc/forge/env
      WorkingDirectory=/opt/forge
      ExecStart=/root/.bun/bin/bun run src/main.ts
      Restart=on-failure
      [Install]
      WantedBy=multi-user.target
runcmd:
  - curl -fsSL https://bun.sh/install | bash -s "bun-v${BUN_VERSION}"
  - git clone ${p.source} /opt/forge
  - git -C /opt/forge checkout --detach ${p.version}
  - systemctl enable --now forge.service
`;
}
const headers = (token: string) => ({ authorization: `Bearer ${token}`, "content-type": "application/json" });
async function call(f: Fetch, token: string, method: string, path: string, body?: unknown): Promise<any> {
  const res = await f(`${API}${path}`, {
    method,
    headers: headers(token),
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
    signal: AbortSignal.timeout(20_000),
  });
  if (!res.ok) throw new Error(`api.digitalocean.com answered ${res.status}`);
  return res.status === 204 ? {} : await res.json();
}
const volumeName = (name: string) => `forge-${name}-data`;
function createDroplet(f: Fetch, token: string, p: Pinned, volumeId: string) {
  return call(f, token, "POST", "/droplets", {
    name: `forge-${p.name}`,
    region: REGION,
    size: SIZE,
    image: "ubuntu-24-04-x64",
    volumes: [volumeId],
    user_data: bootConfig(p),
    tags: ["forge-pinned"],
  });
}
/**
 * Volume first, then the droplet that mounts it. A volume a failed earlier try
 * made (`have`) is reused; a new one is recorded through `onVolume` before the
 * droplet is asked for. Returns the ids to keep.
 */
export async function provision(
  f: Fetch, token: string, p: Pinned, hooks: { have?: string; onVolume(id: string): void },
): Promise<{ remote: string; volume: string }> {
  let volume = hooks.have ?? "";
  if (volume === "") {
    const v = await call(f, token, "POST", "/volumes", {
      name: volumeName(p.name), region: REGION, size_gigabytes: 10, filesystem_type: "ext4",
    });
    volume = String(v.volume?.id ?? "");
    if (!volume) throw new Error("DigitalOcean made no volume");
    hooks.onVolume(volume);
  }
  const d = await createDroplet(f, token, p, volume);
  return { remote: String(d.droplet?.id ?? ""), volume };
}
/**
 * An explicit Update or rollback: delete the old droplet, start a new one on
 * the same volume. A droplet already gone (404, or none recorded after a failed
 * create) counts as deleted, and `onDeleted` clears the recorded id at once, so
 * a retry after a failed create does not delete twice.
 */
export async function replace(f: Fetch, token: string, p: Pinned, hooks: { onDeleted(): void }): Promise<{ remote: string }> {
  if (p.volume === "") throw new Error("this forge has no volume to keep");
  if (p.remote !== "") {
    if (!/^\d+$/.test(p.remote)) throw new Error("this forge has no droplet to replace");
    try {
      await call(f, token, "DELETE", `/droplets/${p.remote}`);
    } catch (e) {
      if (!(e instanceof Error && e.message.endsWith("answered 404"))) throw e;
    }
    hooks.onDeleted();
  }
  const d = await createDroplet(f, token, p, p.volume);
  return { remote: String(d.droplet?.id ?? "") };
}
@@ -0,0 +1,64 @@
/**
 * Where a forge can be put, and what each place can and cannot hold (#8697).
 * A forge is a Bun process, SQLite and a disk that outlives the process, so a
 * target needs a machine and a volume. Prices are list prices for the
 * smallest size that runs a forge, USD a month, as last read; the page says
 * so, and the owner's own bill is the truth.
 */
export type TargetId = "digitalocean" | "aws" | "azure" | "cloudflare" | "vercel";
export interface Target {
  readonly id: TargetId;
  readonly label: string;
  /** `first` deploys today; `planned` has a machine and a volume but no driver yet; `refused` cannot hold a forge. */
  readonly status: "first" | "planned" | "refused";
  readonly runs: string;
  readonly cost: string;
  readonly refused: string;
}
export const TARGETS: readonly Target[] = [
  {
    id: "digitalocean",
    label: "DigitalOcean",
    status: "first",
    runs: "One droplet (Ubuntu, Bun from the pinned source) with one block volume mounted as FORGE_APP_DATA. Replacing the droplet keeps the volume, so a version change never touches the data.",
    cost: "about $12 (s-1vcpu-2gb) + $1.20 (10 GiB volume)",
    refused: "Nothing the forge needs is refused; the token must be able to create droplets and volumes, which DigitalOcean cannot narrow further.",
  },
  {
    id: "aws",
    label: "AWS",
    status: "planned",
    runs: "One EC2 instance (t4g.small) with one EBS gp3 volume, same boot script. Needs SigV4 signing for RunInstances, which providers.ts already does for reads.",
    cost: "about $12 + $0.80 (10 GiB gp3) + a public IPv4 address, about $3.65",
    refused: "A long-lived access key with EC2 write is the broadest credential of the three; the driver will ask for a role scoped to one tag, and is not written yet.",
  },
  {
    id: "azure",
    label: "Azure",
    status: "planned",
    runs: "One VM (B1ms) with one managed disk, through a service principal with Contributor on one resource group.",
    cost: "about $15 + $1 (10 GiB standard SSD) + a public IP, about $3.65",
    refused: "Not written yet: it needs a resource group, a network and a public IP created first, so it is three calls more than the droplet.",
  },
  {
    id: "cloudflare",
    label: "Cloudflare",
    status: "refused",
    runs: "Workers and Durable Objects hold state, but not as a file system a Bun process can open. Cloudflare Containers run a container, with a disk that is wiped when the container sleeps or is replaced.",
    cost: "Workers Paid, $5 a month minimum, plus container time",
    refused: "A forge keeps bare git repositories and SQLite on a disk that survives restarts. Cloudflare offers no such volume to a container, so the forge refuses to put one there rather than lose data quietly.",
  },
  {
    id: "vercel",
    label: "Vercel",
    status: "refused",
    runs: "Functions and Sandboxes: short-lived, one request or one task, with a scratch disk that does not persist.",
    cost: "Pro from $20 a seat a month",
    refused: "No long-running process and no persistent disk, so a forge cannot live there. Vercel can host an app a forge ships, which is a different thing.",
  },
];
export const target = (id: string): Target | undefined => TARGETS.find((t) => t.id === id);
@@ -0,0 +1,12 @@
import type { Route } from "../shared.ts";
export const route: Route = {
  method: "get",
  path: "/api/v1/admin/pinned",
  summary: "The forge's pinned forges with each one's recorded changes, and the targets with what each can and cannot host; a forge administrator's",
  auth: true,
  refusals: {
    not_found: "only a forge administrator sees this route",
    refused: "the request was understood and refused; the message says why (422)",
  },
};
@@ -35,6 +35,7 @@
export { route as getApiV1AdminDrills } from "./getApiV1AdminDrills.ts";
export { route as getApiV1AdminInvites } from "./getApiV1AdminInvites.ts";
export { route as getApiV1AdminLimits } from "./getApiV1AdminLimits.ts";
export { route as getApiV1AdminPeople } from "./getApiV1AdminPeople.ts";
export { route as getApiV1AdminPinned } from "./getApiV1AdminPinned.ts";
export { route as getApiV1AdminProfile } from "./getApiV1AdminProfile.ts";
export { route as getApiV1AdminQuotas } from "./getApiV1AdminQuotas.ts";
export { route as getApiV1AdminSettings } from "./getApiV1AdminSettings.ts";
@@ -193,6 +194,9 @@
export { route as postApiV1AdminAccountsUsernameSuspend } from "./postApiV1Admin
export { route as postApiV1AdminAccountsUsernameUnsuspend } from "./postApiV1AdminAccountsUsernameUnsuspend.ts";
export { route as postApiV1AdminAccountsUsernameVerify } from "./postApiV1AdminAccountsUsernameVerify.ts";
export { route as postApiV1AdminInvites } from "./postApiV1AdminInvites.ts";
export { route as postApiV1AdminPinned } from "./postApiV1AdminPinned.ts";
export { route as postApiV1AdminPinnedNameRollback } from "./postApiV1AdminPinnedNameRollback.ts";
export { route as postApiV1AdminPinnedNameUpdate } from "./postApiV1AdminPinnedNameUpdate.ts";
export { route as postApiV1AdminReleasesShaRollback } from "./postApiV1AdminReleasesShaRollback.ts";
export { route as postApiV1Agents } from "./postApiV1Agents.ts";
export { route as postApiV1Apps } from "./postApiV1Apps.ts";
@@ -0,0 +1,14 @@
import type { Route } from "../shared.ts";
export const route: Route = {
  method: "post",
  path: "/api/v1/admin/pinned",
  summary: "Put a pinned forge on the owner's cloud: no crew, no automatic release; needs an admin-scope token and a cloud account with writes allowed",
  auth: true,
  status: 201,
  body: { name: "string", target: "string", account: "string", app: "string", source: "string", version: "string", config: "object" },
  refusals: {
    not_found: "only a forge administrator sees this route",
    refused: "the request was understood and refused; the message says why (422)",
  },
};
@@ -0,0 +1,12 @@
import type { Route } from "../shared.ts";
export const route: Route = {
  method: "post",
  path: "/api/v1/admin/pinned/{name}/rollback",
  summary: "One action back to the version the latest change replaced; recorded like any change",
  auth: true,
  refusals: {
    not_found: "only a forge administrator sees this route",
    refused: "the request was understood and refused; the message says why (422)",
  },
};
@@ -0,0 +1,13 @@
import type { Route } from "../shared.ts";
export const route: Route = {
  method: "post",
  path: "/api/v1/admin/pinned/{name}/update",
  summary: "The only way a pinned forge changes version or config; recorded with who and when",
  auth: true,
  body: { version: "string", config: "object" },
  refusals: {
    not_found: "only a forge administrator sees this route",
    refused: "the request was understood and refused; the message says why (422)",
  },
};
@@ -176,6 +176,8 @@
export function classifiedAudience(kind: string): EventAudience | undefined {
    kind === "forge.upstream" ||
    kind === "forge.updates_taken" ||
    kind === "cloud.write_allowed" ||
    // A pinned forge's deploy, update and rollback name the owner's cloud (#8697).
    kind.startsWith("pinned.") ||
    // Which of a person's connected accounts a mirror syncs through is too.
    kind.startsWith("origin.") ||
    kind === "repo.settings_updated" ||
@@ -0,0 +1,1 @@
b0bf868cfb029ac5288cae0d3f2a0e01db2d98774f1072f220e6ef2c295df7a6
@@ -0,0 +1,50 @@
// A pinned forge (#8697): a forge the owner put on their own cloud, which has
// no crew and no automatic release. Its version and config are changed only by
// a row in pinned_change (who, when, from, to); the trigger refuses any other
// UPDATE of them, and the CHECKs keep crew and auto_release at 0. Additive.
export default `
  CREATE TABLE pinned_forge (
    id               TEXT PRIMARY KEY,
    name             TEXT NOT NULL UNIQUE,
    target           TEXT NOT NULL,
    account          TEXT NOT NULL,
    app              TEXT NOT NULL,
    source           TEXT NOT NULL,
    version          TEXT NOT NULL,
    config           TEXT NOT NULL,
    crew             INTEGER NOT NULL DEFAULT 0 CHECK (crew = 0),
    auto_release     INTEGER NOT NULL DEFAULT 0 CHECK (auto_release = 0),
    change_id        INTEGER NOT NULL DEFAULT 0,
    remote           TEXT NOT NULL DEFAULT '',
    volume           TEXT NOT NULL DEFAULT '',
    state            TEXT NOT NULL DEFAULT 'new',
    created_at       TEXT NOT NULL
  );
  CREATE TABLE pinned_change (
    id           INTEGER PRIMARY KEY,
    pinned_id    TEXT NOT NULL,
    kind         TEXT NOT NULL CHECK (kind IN ('deploy','update','rollback')),
    from_version TEXT,
    to_version   TEXT NOT NULL,
    from_config  TEXT,
    to_config    TEXT NOT NULL,
    by           TEXT NOT NULL,
    at           TEXT NOT NULL
  );
  CREATE INDEX pinned_change_forge ON pinned_change (pinned_id, id);
  CREATE TRIGGER pinned_change_kept BEFORE UPDATE ON pinned_change
    BEGIN SELECT RAISE(ABORT, 'pinned: a recorded change is history'); END;
  CREATE TRIGGER pinned_change_kept_del BEFORE DELETE ON pinned_change
    BEGIN SELECT RAISE(ABORT, 'pinned: a recorded change is history'); END;
  CREATE TRIGGER pinned_only_by_update
    BEFORE UPDATE OF version, config ON pinned_forge
    WHEN NEW.version IS NOT OLD.version OR NEW.config IS NOT OLD.config
    BEGIN
      SELECT RAISE(ABORT, 'pinned: version and config change only through an explicit Update')
      WHERE NEW.change_id <= OLD.change_id OR NOT EXISTS (
        SELECT 1 FROM pinned_change c
        WHERE c.id = NEW.change_id AND c.pinned_id = OLD.id
          AND c.kind IN ('update','rollback')
          AND c.to_version = NEW.version AND c.to_config = NEW.config);
    END;
  `;
@@ -0,0 +1,165 @@
/**
 * Pinned forges (#8697): rows, and the one way their version and config move.
 * `recordChange` is the only writer of either; the schema trigger refuses an
 * UPDATE that skips it (migration 20261103090000). A pinned forge has no crew
 * and no automatic release, and the CHECKs keep it so.
 */
import type { Database } from "bun:sqlite";
import { id as newId } from "../kernel/id.ts";
import { err, ok, type Result } from "../kernel/result.ts";
export interface Pinned {
  readonly id: string;
  readonly name: string;
  readonly target: string;
  readonly account: string;
  readonly app: string;
  readonly source: string;
  readonly version: string;
  readonly config: Record<string, string>;
  readonly remote: string;
  readonly volume: string;
  readonly state: string;
  readonly createdAt: string;
}
export interface Change {
  readonly id: number;
  readonly kind: "deploy" | "update" | "rollback";
  readonly fromVersion: string | null;
  readonly toVersion: string;
  readonly by: string;
  readonly at: string;
}
export const NAME = /^[a-z][a-z0-9-]{0,39}$/;
/** A full commit id or a release tag such as v1.4.2 — nothing a shell or git could read as a flag. */
export const VERSION = /^(?:[0-9a-f]{40}|v\d{1,4}\.\d{1,4}\.\d{1,4})$/;
export const APP = /^[a-z0-9][a-z0-9_-]{0,38}\/[a-z0-9][a-z0-9_.-]{0,99}$/;
const SOURCE = /^https:\/\/[a-z0-9][a-z0-9.-]{0,100}(?:\/[A-Za-z0-9._~-]{1,100}){1,4}$/;
const KEY = /^[A-Z][A-Z0-9_]{0,63}$/;
// A value is written to a systemd EnvironmentFile on the machine: no quote,
// backslash, dollar, backtick or newline can reach it.
const VALUE = /^[A-Za-z0-9 _.,:\/@+=-]{0,512}$/;
const SECRETISH = /SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE|CREDENTIAL|API_?KEY|ACCESS_?KEY/;
export function validVersion(v: string): boolean {
  return VERSION.test(v);
}
export function validSource(s: string): boolean {
  return SOURCE.test(s) && !s.includes("..");
}
/** Config is plain, non-secret settings; a secret-looking name is refused so none lands in a row. */
export function checkConfig(raw: unknown): Result<Record<string, string>, string> {
  if (raw === undefined) return ok({});
  if (typeof raw !== "object" || raw === null || Array.isArray(raw))
    return err("config is an object of NAME: value");
  const out: Record<string, string> = {};
  const entries = Object.entries(raw);
  if (entries.length > 40) return err("config holds at most 40 settings");
  for (const [k, v] of entries) {
    if (!KEY.test(k)) return err(`config name ${k.slice(0, 20)} is capitals, digits and underscores`);
    if (SECRETISH.test(k)) return err(`${k} looks like a secret; secrets are sealed in cloud accounts, never in config`);
    if (typeof v !== "string" || !VALUE.test(v)) return err(`config ${k} is plain text of letters, digits and . , : / @ + = - _`);
    out[k] = v;
  }
  return ok(Object.fromEntries(Object.entries(out).sort(([a], [b]) => (a < b ? -1 : 1))));
}
interface Row {
  id: string; name: string; target: string; account: string; app: string; source: string;
  version: string; config: string; remote: string; volume: string; state: string; created_at: string;
}
const toPinned = (r: Row): Pinned => ({
  id: r.id, name: r.name, target: r.target, account: r.account, app: r.app, source: r.source,
  version: r.version, config: JSON.parse(r.config) as Record<string, string>,
  remote: r.remote, volume: r.volume, state: r.state, createdAt: r.created_at,
});
export const listPinned = (db: Database): Pinned[] =>
  db.query<Row, []>("SELECT * FROM pinned_forge ORDER BY created_at, id").all().map(toPinned);
export function getPinned(db: Database, name: string): Pinned | undefined {
  const r = db.query<Row, [string]>("SELECT * FROM pinned_forge WHERE name = ?1").get(name);
  return r ? toPinned(r) : undefined;
}
export function changesOf(db: Database, pinnedId: string): Change[] {
  return db
    .query<{ id: number; kind: Change["kind"]; from_version: string | null; to_version: string; by: string; at: string }, [string]>(
      "SELECT id, kind, from_version, to_version, by, at FROM pinned_change WHERE pinned_id = ?1 ORDER BY id DESC",
    )
    .all(pinnedId)
    .map((c) => ({ id: c.id, kind: c.kind, fromVersion: c.from_version, toVersion: c.to_version, by: c.by, at: c.at }));
}
export function insertPinned(
  db: Database,
  p: { name: string; target: string; account: string; app: string; source: string; version: string; config: Record<string, string> },
  by: string,
): Pinned {
  const at = new Date().toISOString();
  const pid = newId();
  const config = JSON.stringify(p.config);
  db.transaction(() => {
    const c = db
      .query("INSERT INTO pinned_change (pinned_id, kind, from_version, to_version, from_config, to_config, by, at) VALUES (?1, 'deploy', NULL, ?2, NULL, ?3, ?4, ?5)")
      .run(pid, p.version, config, by, at);
    db.query(
      "INSERT INTO pinned_forge (id, name, target, account, app, source, version, config, change_id, created_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)",
    ).run(pid, p.name, p.target, p.account, p.app, p.source, p.version, config, Number(c.lastInsertRowid), at);
  })();
  return getPinned(db, p.name)!;
}
/**
 * The one explicit change: write who, when, from and to, then move the pin.
 * Returns the stored change. Rollback's target is the `from` of the latest
 * change, so it is always one action to the previous version.
 */
export function recordChange(
  db: Database,
  forge: Pinned,
  kind: "update" | "rollback",
  to: { version: string; config: Record<string, string> },
  by: string,
): Change {
  const at = new Date().toISOString();
  const toConfig = JSON.stringify(to.config);
  db.transaction(() => {
    const c = db
      .query("INSERT INTO pinned_change (pinned_id, kind, from_version, to_version, from_config, to_config, by, at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)")
      .run(forge.id, kind, forge.version, to.version, JSON.stringify(forge.config), toConfig, by, at);
    db.query("UPDATE pinned_forge SET version = ?1, config = ?2, change_id = ?3 WHERE id = ?4").run(
      to.version, toConfig, Number(c.lastInsertRowid), forge.id,
    );
  })();
  return changesOf(db, forge.id)[0]!;
}
/** What a rollback would restore: the latest change's `from`, if it had one. */
export function previousOf(db: Database, forge: Pinned): { version: string; config: Record<string, string> } | undefined {
  const r = db
    .query<{ from_version: string | null; from_config: string | null }, [string]>(
      "SELECT from_version, from_config FROM pinned_change WHERE pinned_id = ?1 ORDER BY id DESC LIMIT 1",
    )
    .get(forge.id);
  return r?.from_version != null && r.from_config != null
    ? { version: r.from_version, config: JSON.parse(r.from_config) as Record<string, string> }
    : undefined;
}
/** Machine facts the target reports back; they never touch version or config. */
export function setRemote(db: Database, name: string, f: { remote?: string; volume?: string; state?: string }): void {
  db.query("UPDATE pinned_forge SET remote = coalesce(?1, remote), volume = coalesce(?2, volume), state = coalesce(?3, state) WHERE name = ?4")
    .run(f.remote ?? null, f.volume ?? null, f.state ?? null, name);
}
/** The row of a deploy that never reached a droplet, so its name can be tried again; its recorded change stays as history. */
export function dropPinned(db: Database, name: string): void {
  db.query("DELETE FROM pinned_forge WHERE name = ?1 AND remote = '' AND state = 'failed'").run(name);
}
@@ -89,6 +89,7 @@
export const ASKING: Readonly<Record<string, Asking>> = {
  converge: { does: "have a fork's crew merge the parent's updates" },
  origins: { does: "sync an origin or replace the internal hosts one may live on", asks: not("action", "list", "repos") },
  cloud_account: { does: "change a cloud account" },
  pinned_forge: { does: "deploy, update or roll back a pinned forge on the owner's cloud", asks: not("verb", "list") },
  outsiders: { does: "let non-writers direct an app's crew, or stop them" },
  seal: { does: "seal or unseal an issue or pull" },
  migrate: { does: "bring a repository in from a public address" },
@@ -14,6 +14,8 @@
import { changeCapacity, listCapacity } from "../../actions/capacity.ts";
import { inviteLink, list as listInviteLinks, mint as mintInviteLink, revoke as revokeInviteLink } from "../../actions/invites.ts";
import { changeLimit, listLimits } from "../../actions/limits.ts";
import { setAccountCeilings, setAccountGrant } from "../../actions/model_grant.ts";
import { deployPinned, pinnedForges, rollbackPinned, updatePinned } from "../../actions/pinned.ts";
import { TARGETS } from "../../cloud/targets.ts";
import { changeQuotas, readQuotas } from "../../actions/quotas.ts";
import { setRole } from "../../actions/roles.ts";
import { SETTING_WORDS } from "../../actions/setting_words.ts";
@@ -37,6 +39,46 @@
export const accountAdmin = (ctx: Ctx, scope: "ro" | "admin"): Response | undefi
  ctx.auth.user?.isAdmin === true ? requireScope(ctx, scope) : notFound();
export function adminRoutes(router: Router<Handler>): void {
  // ---- pinned forges (#8697): one deploy, and a change only by Update ----
  const pinnedFail = (error: string): Response =>
    error === "not_found" || error === "No such pinned forge." ? notFound() : apiError("refused", 422, error);
  router.add("GET", "/api/v1/admin/pinned", (ctx) => {
    notePhase(ctx.request, "session", takeSessionTime(ctx.request));
    const denied = accountAdmin(ctx, "ro");
    if (denied) return denied;
    const seen = pinnedForges(ctx.app, ctx.auth.user);
    return seen.ok ? json({ items: seen.value, targets: TARGETS, next_cursor: null }) : notFound();
  });
  router.add("POST", "/api/v1/admin/pinned", async (ctx) => {
    const denied = accountAdmin(ctx, "admin");
    if (denied) return denied;
    const i = await body(ctx.request);
    const made = await deployPinned(ctx.app, ctx.auth.user, {
      name: str(i.name), target: str(i.target), account: str(i.account), app: str(i.app),
      source: str(i.source), version: str(i.version), config: i.config,
    });
    return made.ok ? json(made.value, 201) : pinnedFail(made.error);
  });
  router.add("POST", "/api/v1/admin/pinned/:name/update", async (ctx) => {
    const denied = accountAdmin(ctx, "admin");
    if (denied) return denied;
    const i = await body(ctx.request);
    const done = await updatePinned(ctx.app, ctx.auth.user, ctx.params.name!, {
      version: i.version === undefined ? undefined : str(i.version), config: i.config,
    });
    return done.ok ? json(done.value) : pinnedFail(done.error);
  });
  router.add("POST", "/api/v1/admin/pinned/:name/rollback", async (ctx) => {
    const denied = accountAdmin(ctx, "admin");
    if (denied) return denied;
    const done = await rollbackPinned(ctx.app, ctx.auth.user, ctx.params.name!);
    return done.ok ? json(done.value) : pinnedFail(done.error);
  });
  // ---- accounts: the owner's view of who joined (#660) ----
  const accountError = (error: string): Response =>
    error === "not_found"
@@ -98,6 +98,7 @@
export { tool as origins } from "./origins.ts";
export { tool as outsiders } from "./outsiders.ts";
export { tool as parent_unlink } from "./parent_unlink.ts";
export { tool as person } from "./person.ts";
export { tool as pinned_forge } from "./pinned_forge.ts";
export { tool as pins } from "./pins.ts";
export { tool as plan } from "./plan.ts";
export { tool as preview } from "./preview.ts";
@@ -0,0 +1,54 @@
import { deployPinned, pinnedForges, rollbackPinned, updatePinned } from "../../../actions/pinned.ts";
import { TARGETS } from "../../../cloud/targets.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { good, bad, type Tool, str } from "../shared.ts";
export const tool: Tool = {
  name: "pinned_forge",
  doc: "`{ verb, name?, target?, account?, app?, source?, version?, config? }`: a pinned forge on the owner's cloud has no crew and no automatic release. `list` shows them with every recorded change and the targets (what runs, what it costs, what is refused); `deploy` puts one on `target` with a cloud `account` (writes allowed) serving `app` owner/name from `source` at `version`; `update` is the only way its `version` or `config` change; `rollback` goes back one. A forge admin with an admin-scope token",
  description: "Pinned forges on your cloud: list, deploy, update, rollback (admin).",
  inputSchema: {
    type: "object",
    properties: {
      verb: { type: "string", enum: ["list", "deploy", "update", "rollback"] },
      name: { type: "string", maxLength: 40 },
      target: { type: "string", enum: TARGETS.map((t) => t.id) },
      account: { type: "string", maxLength: 32 },
      app: { type: "string", maxLength: 140 },
      source: { type: "string", maxLength: 300 },
      version: { type: "string", maxLength: 40, description: "A 40-character commit id or a tag like v1.2.3." },
      config: { type: "object", description: "Plain NAME: value settings; never a secret." },
    },
    required: ["verb"],
  },
  // Marked a write so a `ro` token never lists the owner's cloud arrangements.
  writes: true,
  async run(ctx, user, args) {
    if (!user.isAdmin) return bad("not_found", "no such tool here");
    const verb = str(args["verb"]);
    if (verb === "list") {
      const seen = pinnedForges(ctx.app, user);
      return seen.ok ? good({ items: seen.value, targets: TARGETS }) : bad("not_found", "no such tool here");
    }
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "changing a pinned forge needs an admin-scope token");
    const name = str(args["name"]);
    const done =
      verb === "deploy"
        ? await deployPinned(ctx.app, user, {
            name, target: str(args["target"]), account: str(args["account"]), app: str(args["app"]),
            source: str(args["source"]), version: str(args["version"]), config: args["config"],
          })
        : verb === "update"
          ? await updatePinned(ctx.app, user, name, {
              version: args["version"] === undefined ? undefined : str(args["version"]),
              config: args["config"],
            })
          : verb === "rollback"
            ? await rollbackPinned(ctx.app, user, name)
            : undefined;
    if (done === undefined) return bad("bad_verb", "verb is list, deploy, update or rollback");
    if (!done.ok) return bad("refused", done.error);
    return good({ says: `${verb} ${name}: now ${done.value.version}, ${done.value.state}.`, forge: done.value });
  },
};
@@ -29,6 +29,7 @@
import { entry as orgGrants } from "./orggrants.ts";
import { entry as orgTeams } from "./orgteams.ts";
import { entry as owner } from "./owner.ts";
import { entry as people } from "./people.ts";
import { entry as pinned } from "./pinned.ts";
import { entry as profile } from "./profile.ts";
import { entry as quotas } from "./quotas.ts";
import { entry as resilience } from "./resilience.ts";
@@ -82,6 +83,7 @@
export const ENTRIES: readonly PaletteEntry[] = [
  bulk,
  subscriptions,
  cloud,
  pinned,
  connections,
  domains,
  feed,
@@ -0,0 +1,112 @@
/**
 * Pinned forges in the terminal, a forge admin's (#8697): each forge with its
 * version, state and last changes, as the API lists them. `d` deploys, `u`
 * updates (the only way its version or config move), `r` rolls back to the
 * previous version, each through `actions/pinned.ts`, so the checks, the
 * record of who and when and the events the web screens follow are the API's.
 * Anyone else sees nothing and does nothing.
 */
import { deployPinned, pinnedForges, rollbackPinned, updatePinned } from "../../actions/pinned.ts";
import type { Ctx, Screen } from "../app/app.ts";
import { binding } from "../app/keys.ts";
import { style } from "../term/style.ts";
import { truncate } from "../term/width.ts";
import type { Session } from "../session.ts";
import { fill, len, split } from "../ui/layout.ts";
import { ListState, drawList, live, promptScreen, type ListRow } from "./common.ts";
import type { PaletteEntry } from "./entries.ts";
const short = (v: string): string => (v.length === 40 ? v.slice(0, 10) : v);
export function pinnedScreen(f: Session, ctx: Ctx): Screen {
  const state = new ListState();
  let note = "";
  const read = () => pinnedForges(f.app, f.user);
  const forges = () => {
    const r = read();
    return r.ok ? r.value : [];
  };
  const say = (text: string): void => {
    note = text;
    ctx.invalidate();
  };
  const settle = async (r: Promise<{ ok: true; value: { name: string; version: string } } | { ok: false; error: string }>, what: string): Promise<void> => {
    const made = await r;
    say(made.ok ? `${what} ${made.value.name} at ${short(made.value.version)}.` : made.error);
  };
  const deploy = (parent: Screen): Screen =>
    promptScreen(ctx, parent, {
      title: "Deploy a pinned forge",
      label: "name provider/account owner/app https-source version",
      placeholder: "acme digitalocean/main alice/shop https://host/alice/shop v1.0.0",
      onSubmit: (raw) => {
        const [name = "", cloud = "", app = "", source = "", version = "", ...rest] = raw.trim().split(/\s+/);
        const [target = "", account = "", ...more] = cloud.split("/");
        if (rest.length > 0 || more.length > 0 || version === "" || account === "") return "Write: name provider/account owner/app source version.";
        say(`Deploying ${name}…`);
        return settle(deployPinned(f.app, f.user, { name, target, account, app, source, version }), "Deployed");
      },
    });
  const screen: Screen = {
    title: "Pinned forges",
    keys: [binding(["j", "k"], "move cursor"), binding(["d"], "deploy"), binding(["u"], "update"), binding(["r"], "roll back")],
    async load(signal) {
      live(f, signal, { kinds: ["pinned.deployed", "pinned.update", "pinned.rollback"] }, () => ctx.invalidate());
    },
    render(area, s) {
      const c = ctx.theme.c;
      const r = read();
      const [head, list] = split(area, "v", [len(1), fill(1)]);
      const selected = forges()[state.index];
      const text = note !== "" ? note : !r.ok ? "Pinned forges are a forge admin's." : selected ? `${selected.app} from ${selected.source}` : "No pinned forge. Press d to deploy one.";
      s.text(head!.x, head!.y, truncate(text, head!.w), style(c.mutedFg, c.bg), head!.x + head!.w);
      const rows: ListRow[] = forges().map((p) => ({
        title: p.name,
        ...(p.state === "failed" ? { tone: "danger" as const } : {}),
        secondary: `${p.target} · ${short(p.version)} · ${p.state}`,
        meta: p.changes[0] ? `${p.changes[0].kind} ${p.changes[0].at.slice(0, 16).replace("T", " ")}` : "",
      }));
      drawList(s, list!, c, state, rows);
    },
    key(e) {
      if (state.key(e, forges().length)) return true;
      if (e.ctrl || e.alt || !read().ok) return false;
      if (e.key === "d") {
        ctx.push(deploy(screen));
        return true;
      }
      const p = forges()[state.index];
      if (p === undefined) return false;
      if (e.key === "r") {
        say(`Rolling ${p.name} back…`);
        void settle(rollbackPinned(f.app, f.user, p.name), "Rolled back");
      } else if (e.key === "u")
        ctx.push(
          promptScreen(ctx, screen, {
            title: `Update ${p.name}`,
            label: "the new version: a 40-character commit id or a tag",
            onSubmit: (version) => {
              say(`Updating ${p.name}…`);
              return settle(updatePinned(f.app, f.user, p.name, { version: version.trim() }), "Updated");
            },
          }),
        );
      else return false;
      return true;
    },
  };
  return screen;
}
/** Pinned forges, as the API and the MCP have them: a forge admin (#8697). */
export const entry: PaletteEntry = {
  id: "pinned",
  title: "Pinned forges",
  hint: "deploy, update and roll back a forge on your cloud",
  after: ["cloud"],
  offered: (session) => session.user?.isAdmin === true,
  run: (session, ctx) => ctx.push(pinnedScreen(session, ctx)),
};
@@ -137,7 +137,7 @@
describe("the one list of what asks first", () => {
      expect(listed || NOT_ASKED.has(t.name), `${t.name} writes: ask first (ASKING) or name it in NOT_ASKED`).toBe(true);
      expect(listed && NOT_ASKED.has(t.name), `${t.name} is on both lists`).toBe(false);
    }
    for (const name of ["land_past_gate", "share", "invites", "egress_grants", "sever", "parent_unlink", "quotas", "spawn", "app_deploy", "stop", "converge", "origins", "cloud_account", "outsiders", "seal", "migrate"])
    for (const name of ["land_past_gate", "share", "invites", "egress_grants", "sever", "parent_unlink", "quotas", "spawn", "app_deploy", "stop", "converge", "origins", "cloud_account", "pinned_forge", "outsiders", "seal", "migrate"])
      expect(ASKING[name], name).toBeDefined();
  });
@@ -303,6 +303,7 @@
describe("the forge over MCP", () => {
      "egress_grants",
      "explore",
      "person",
      "pinned_forge",
      "search",
      "feed",
      "feed_chips",
@@ -110,6 +110,7 @@
test("a site-admin person is offered the whole roster", () => {
    ["audit", "Who can do what", "each app's doors from its contract.json: yes, own or no"],
    ["archived", "Archived repositories", "put away, not gone: open one or wake it"],
    ["cloud", "Cloud accounts", "provider tokens, what they are used for, today's calls"],
    ["pinned", "Pinned forges", "deploy, update and roll back a forge on your cloud"],
    ["origins", "Connected origins", "the hosts your mirrors come from"],
    ["domains", "Failure domains", "failure domains and their last drill"],
    ["feed", "Feed", "what happened, ranked; r replies on a post about an issue or pull, l likes"],
@@ -164,6 +165,7 @@
test("a site-admin agent is offered the roster without the person-only entries",
    ["audit", "Who can do what", "each app's doors from its contract.json: yes, own or no"],
    ["archived", "Archived repositories", "put away, not gone: open one or wake it"],
    ["cloud", "Cloud accounts", "provider tokens, what they are used for, today's calls"],
    ["pinned", "Pinned forges", "deploy, update and roll back a forge on your cloud"],
    ["feed", "Feed", "what happened, ranked; r replies on a post about an issue or pull, l likes"],
    ["front", "Front page", "the apps a first visitor sees, ranked; an admin pins or hides"],
    ["forges", "Forges you sent", "each forge sent, claimed or not, and its apps"],
@@ -0,0 +1,153 @@
/**
 * A pinned forge that fails half-way is recoverable (#8697): a failed create
 * after the delete, a failed first deploy, and a volume made before the droplet
 * all leave a row a retry finishes. The terminal door reaches the same actions.
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { addAccount, allowWrite, net as cloudNet } from "../src/actions/cloud.ts";
import { deployPinned, net, rollbackPinned, updatePinned } from "../src/actions/pinned.ts";
import { BUN_VERSION, bootConfig } from "../src/cloud/droplet.ts";
import { getPinned } from "../src/core/pinned.ts";
import { createUser, getUserByName } from "../src/core/users.ts";
import { Session } from "../src/tui/session.ts";
import { entry, pinnedScreen } from "../src/tui/screens/pinned.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
const V1 = "a".repeat(40);
const V2 = "b".repeat(40);
const SOURCE = "https://forge.example.org/trevato/forge";
describe("pinned forge recovery", () => {
  let dataDir = "";
  let app: App;
  const calls: string[] = [];
  /** Paths whose next call fails, with the status. */
  const fail = new Map<string, number>();
  let deleted = new Set<string>();
  const admin = () => getUserByName(app.db, "alice")!;
  const input = (over: Record<string, unknown> = {}) => ({
    name: "acme", target: "digitalocean", account: "main", app: "alice/shop", source: SOURCE, version: V1, config: {}, ...over,
  });
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-pinned-rec-"));
    app = createApp({ dataDir, port: 0 });
    for (const [username, adminIfFirst] of [["alice", true], ["bob", false]] as const) {
      const made = await createUser(app.db, { origin: "seed", trusted: true, username, email: `${username}@f.test`, password: "a-good-passphrase", adminIfFirst });
      if (!made.ok) throw new Error(made.error);
    }
    cloudNet.fetch = async () => new Response(JSON.stringify({ account: { email: "[email protected]", status: "active" } }), { status: 200 });
    const added = await addAccount(app, admin(), "digitalocean", "main", "dop_v1_9Zq4TxLm7Kp2Vb8nWcR5");
    if (!added.ok) throw new Error(String(added.error));
    allowWrite(app, admin(), "digitalocean", "main", true);
    net.fetch = async (url, init) => {
      const path = new URL(url).pathname;
      const method = init?.method ?? "GET";
      calls.push(`${method} ${path}`);
      const key = `${method} ${path.replace(/\/\d+$/, "")}`;
      const status = fail.get(key);
      if (status !== undefined) { fail.delete(key); return new Response("{}", { status }); }
      if (path === "/v2/volumes") return new Response(JSON.stringify({ volume: { id: "vol-9" } }), { status: 201 });
      if (method === "DELETE") {
        if (deleted.has(path)) return new Response("{}", { status: 404 });
        deleted.add(path);
        return new Response(null, { status: 204 });
      }
      return new Response(JSON.stringify({ droplet: { id: 2000 + calls.length } }), { status: 202 });
    };
  });
  afterAll(async () => {
    app.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  test("a failed first deploy keeps its volume, and the same name deploys again reusing it", async () => {
    fail.set("POST /v2/droplets", 500);
    const first = await deployPinned(app, admin(), input());
    expect(first.ok).toBe(false);
    // The volume id was recorded before the droplet was asked for.
    expect(getPinned(app.db, "acme")).toMatchObject({ state: "failed", remote: "", volume: "vol-9" });
    calls.length = 0;
    const again = await deployPinned(app, admin(), input());
    expect(again.ok).toBe(true);
    expect(calls).toEqual(["POST /v2/droplets"]);
    expect(getPinned(app.db, "acme")).toMatchObject({ state: "running", volume: "vol-9" });
    // A running forge still owns its name.
    expect(await deployPinned(app, admin(), input())).toMatchObject({ ok: false, error: "A pinned forge has that name already." });
  });
  test("an Update whose create fails after the delete can be rolled back or tried again", async () => {
    fail.set("POST /v2/droplets", 500);
    expect((await updatePinned(app, admin(), "acme", { version: V2 })).ok).toBe(false);
    expect(getPinned(app.db, "acme")).toMatchObject({ state: "failed", remote: "", version: V2 });
    calls.length = 0;
    // The old droplet is not deleted a second time.
    const back = await rollbackPinned(app, admin(), "acme");
    expect(back.ok).toBe(true);
    expect(calls).toEqual(["POST /v2/droplets"]);
    expect(getPinned(app.db, "acme")).toMatchObject({ state: "running", version: V1 });
  });
  test("a droplet already gone (404) counts as deleted", async () => {
    app.db.run("UPDATE pinned_forge SET remote = '777' WHERE name = 'acme'");
    deleted.add("/v2/droplets/777");
    expect((await updatePinned(app, admin(), "acme", { version: V2 })).ok).toBe(true);
    expect(getPinned(app.db, "acme")).toMatchObject({ state: "running", version: V2 });
  });
  test("a failed forge may be told the version it already has, to finish the replacement", async () => {
    app.db.run("UPDATE pinned_forge SET state = 'failed', remote = '' WHERE name = 'acme'");
    expect((await updatePinned(app, admin(), "acme", { version: V2 })).ok).toBe(true);
    expect(getPinned(app.db, "acme")?.state).toBe("running");
  });
  test("the boot script installs the Bun version it names, not whatever is latest", () => {
    const script = bootConfig({ name: "acme", source: SOURCE, version: V1, config: {} });
    expect(script).toContain(`bash -s "bun-v${BUN_VERSION}"`);
    expect(BUN_VERSION).toMatch(/^\d+\.\d+\.\d+$/);
  });
  test("terminal: the palette offers Pinned forges to an admin only; d, u and r reach the actions", async () => {
    const bob = new Session(app, { sshUsername: "t", remoteAddress: "127.0.0.1", user: getUserByName(app.db, "bob")! });
    const alice = new Session(app, { sshUsername: "t", remoteAddress: "127.0.0.1", user: admin() });
    expect(entry.offered(bob)).toBe(false);
    expect(entry.offered(alice)).toBe(true);
    const pushed: any[] = [];
    const ctx = { push: (s: unknown) => pushed.push(s), invalidate() {}, pop() {}, toast() {}, setCursor() {} } as never;
    const key = (s: { key?: (e: never) => boolean }, k: string) => s.key?.({ type: "key", key: k, ctrl: false, alt: false, shift: false } as never);
    const refused = pinnedScreen(bob, ctx);
    for (const k of ["d", "u", "r"]) key(refused, k);
    expect(pushed).toEqual([]);
    const screen = pinnedScreen(alice, ctx);
    key(screen, "d");
    expect(pushed).toHaveLength(1);
    // r rolls back the forge under the cursor: one action, recorded.
    const before = getPinned(app.db, "acme")!.version;
    key(screen, "r");
    await new Promise((r) => setTimeout(r, 50));
    expect(getPinned(app.db, "acme")!.version).not.toBe(before);
  });
  test("terminal: the screen follows the bus while it is on the stack", async () => {
    const alice = new Session(app, { sshUsername: "t", remoteAddress: "127.0.0.1", user: admin() });
    let invalidated = 0;
    const ctx = { push() {}, invalidate: () => invalidated++ } as never;
    const abort = new AbortController();
    await pinnedScreen(alice, ctx).load!(abort.signal);
    const n = invalidated;
    await updatePinned(app, admin(), "acme", { version: V2 });
    await new Promise((r) => setTimeout(r, 120));
    expect(invalidated).toBeGreaterThan(n);
    abort.abort();
  });
});
@@ -0,0 +1,226 @@
/**
 * A pinned forge (#8697): deployed once, changed only by an explicit Update
 * that records who and when, rolled back in one action, and never holding a
 * credential in a row, an event or the boot script. Every other way to move
 * its version or config is tried here and refused.
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { addAccount, allowWrite, net as cloudNet } from "../src/actions/cloud.ts";
import { deployPinned, net, pinnedForges, rollbackPinned, updatePinned } from "../src/actions/pinned.ts";
import { bootConfig } from "../src/cloud/droplet.ts";
import { TARGETS } from "../src/cloud/targets.ts";
import { changesOf, checkConfig, getPinned } from "../src/core/pinned.ts";
import { createToken } from "../src/core/tokens.ts";
import { createUser, getUserByName } from "../src/core/users.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
const TOKEN = "dop_v1_9Zq4TxLm7Kp2Vb8nWcR5";
const V1 = "a".repeat(40);
const V2 = "b".repeat(40);
const SOURCE = "https://forge.example.org/trevato/forge";
describe("pinned forge", () => {
  let dataDir = "";
  let app: App;
  let servers: Servers;
  const calls: { method: string; url: string; auth: string | null; body: any }[] = [];
  let failNext = false;
  const admin = () => getUserByName(app.db, "alice")!;
  const input = (over: Record<string, unknown> = {}) => ({
    name: "acme", target: "digitalocean", account: "main", app: "alice/shop", source: SOURCE, version: V1, config: { PUBLIC_NAME: "Acme" }, ...over,
  });
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-pinned-"));
    app = createApp({ dataDir, port: 0 });
    servers = await serve(app);
    for (const [username, adminIfFirst] of [["alice", true], ["bob", false]] as const) {
      const made = await createUser(app.db, { origin: "seed", trusted: true, username, email: `${username}@f.test`, password: "a-good-passphrase", adminIfFirst });
      if (!made.ok) throw new Error(made.error);
    }
    cloudNet.fetch = async () => new Response(JSON.stringify({ account: { email: "[email protected]", status: "active" } }), { status: 200 });
    const added = await addAccount(app, admin(), "digitalocean", "main", TOKEN);
    if (!added.ok) throw new Error(String(added.error));
    net.fetch = async (url, init) => {
      const u = new URL(url);
      calls.push({ method: init?.method ?? "GET", url, auth: new Headers(init?.headers).get("authorization"), body: init?.body ? JSON.parse(String(init.body)) : undefined });
      if (failNext) { failNext = false; return new Response("{}", { status: 500 }); }
      if (u.pathname === "/v2/volumes") return new Response(JSON.stringify({ volume: { id: "vol-1" } }), { status: 201 });
      if (init?.method === "DELETE") return new Response(null, { status: 204 });
      return new Response(JSON.stringify({ droplet: { id: 1000 + calls.length } }), { status: 202 });
    };
  }, 30_000);
  afterAll(async () => {
    servers.stop();
    app.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  test("a deploy needs a cloud account that may write", async () => {
    const r = await deployPinned(app, admin(), input());
    expect(r).toMatchObject({ ok: false });
    expect(String((r as any).error)).toContain("read-only");
    expect(calls).toHaveLength(0);
    // The attempt is recorded, and the forge says it failed rather than running.
    expect(getPinned(app.db, "acme")?.state).toBe("failed");
  });
  test("deploy makes a volume, then a droplet on it; the token is a header, never in a body or the boot script", async () => {
    app.db.run("DELETE FROM pinned_forge");
    allowWrite(app, admin(), "digitalocean", "main", true);
    const r = await deployPinned(app, admin(), input());
    expect(r.ok).toBe(true);
    expect(calls.map((c) => `${c.method} ${new URL(c.url).pathname}`)).toEqual(["POST /v2/volumes", "POST /v2/droplets"]);
    expect(calls.every((c) => c.auth === `Bearer ${TOKEN}`)).toBe(true);
    const droplet = calls[1]!.body;
    expect(droplet.volumes).toEqual(["vol-1"]);
    expect(JSON.stringify(calls.map((c) => c.body))).not.toContain(TOKEN);
    expect(droplet.user_data).toContain(`checkout --detach ${V1}`);
    expect(droplet.user_data).toContain("FORGE_APP_DATA=/mnt/forge_acme_data");
    const p = getPinned(app.db, "acme")!;
    expect(p).toMatchObject({ state: "running", volume: "vol-1" });
    const events = JSON.stringify(app.db.query("SELECT payload FROM event WHERE kind LIKE 'pinned.%'").all());
    expect(events).not.toContain(TOKEN);
    expect(JSON.stringify(pinnedForges(app, admin()))).not.toContain(TOKEN);
  });
  test("a pinned forge has no crew and no automatic release, and the schema keeps it so", () => {
    const v = pinnedForges(app, admin());
    expect(v.ok && v.value[0]).toMatchObject({ crew: false, autoRelease: false });
    expect(() => app.db.run("UPDATE pinned_forge SET crew = 1")).toThrow();
    expect(() => app.db.run("UPDATE pinned_forge SET auto_release = 1")).toThrow();
  });
  test("version and config move only through Update: every other way is refused", async () => {
    const before = getPinned(app.db, "acme")!;
    // Straight SQL, as any other code path in the forge would try.
    expect(() => app.db.run("UPDATE pinned_forge SET version = ?1", [V2])).toThrow(/explicit Update/);
    expect(() => app.db.run("UPDATE pinned_forge SET config = '{}'")).toThrow(/explicit Update/);
    // Forging a change id that points at no matching change.
    expect(() => app.db.run("UPDATE pinned_forge SET version = ?1, change_id = change_id + 1", [V2])).toThrow(/explicit Update/);
    // A change recorded for one version cannot authorize another.
    const c = app.db.query("INSERT INTO pinned_change (pinned_id, kind, from_version, to_version, from_config, to_config, by, at) VALUES (?1,'update',?2,?3,'{}','{}','x','now')").run(before.id, V1, V2);
    expect(() => app.db.run("UPDATE pinned_forge SET version = ?1, config = ?2, change_id = ?3", ["c".repeat(40), "{}", Number(c.lastInsertRowid)])).toThrow(/explicit Update/);
    // A deploy-kind change cannot be replayed as an update.
    const d = app.db.query("SELECT id FROM pinned_change WHERE kind = 'deploy'").get() as { id: number };
    expect(() => app.db.run("UPDATE pinned_forge SET version = ?1, change_id = ?2", [V2, d.id])).toThrow();
    // History cannot be rewritten or deleted.
    expect(() => app.db.run("UPDATE pinned_change SET by = 'someone'")).toThrow(/history/);
    expect(() => app.db.run("DELETE FROM pinned_change")).toThrow(/history/);
    expect(getPinned(app.db, "acme")!.version).toBe(before.version);
    // Not an admin, not a thing.
    const bob = getUserByName(app.db, "bob");
    expect(await updatePinned(app, bob, "acme", { version: V2 })).toEqual({ ok: false, error: "not_found" });
    expect(await rollbackPinned(app, undefined, "acme")).toEqual({ ok: false, error: "not_found" });
    expect(getPinned(app.db, "acme")!.version).toBe(V1);
  });
  test("Update records who and when, replaces the droplet and keeps the volume", async () => {
    calls.length = 0;
    const r = await updatePinned(app, admin(), "acme", { version: V2, config: { PUBLIC_NAME: "Acme Ltd" } });
    expect(r.ok).toBe(true);
    expect(calls.map((c) => `${c.method} ${new URL(c.url).pathname}`)).toEqual([expect.stringMatching(/^DELETE \/v2\/droplets\/\d+$/), "POST /v2/droplets"]);
    expect(calls[1]!.body.volumes).toEqual(["vol-1"]);
    expect(calls[1]!.body.user_data).toContain(`checkout --detach ${V2}`);
    const [latest] = changesOf(app.db, getPinned(app.db, "acme")!.id);
    expect(latest).toMatchObject({ kind: "update", fromVersion: V1, toVersion: V2, by: admin().id });
    expect(Date.parse(latest!.at)).toBeGreaterThan(0);
  });
  test("Update refuses an unsafe version, secret-looking config, and a no-op", async () => {
    calls.length = 0;
    for (const version of ["main", "--upload-pack=x", `${V1}; rm -rf /`, "v1.2"])
      expect(await updatePinned(app, admin(), "acme", { version })).toMatchObject({ ok: false });
    expect(await updatePinned(app, admin(), "acme", { config: { API_TOKEN: "x" } })).toMatchObject({ ok: false });
    expect(await updatePinned(app, admin(), "acme", { config: { A: "$(id)" } })).toMatchObject({ ok: false });
    expect(await updatePinned(app, admin(), "acme", {})).toMatchObject({ ok: false, error: "That is what it runs already." });
    expect(calls).toHaveLength(0);
    expect(getPinned(app.db, "acme")!.version).toBe(V2);
  });
  test("Rollback is one action to the previous version and is recorded", async () => {
    const r = await rollbackPinned(app, admin(), "acme");
    expect(r.ok && r.value).toMatchObject({ version: V1, config: { PUBLIC_NAME: "Acme" } });
    const [latest] = changesOf(app.db, getPinned(app.db, "acme")!.id);
    expect(latest).toMatchObject({ kind: "rollback", fromVersion: V2, toVersion: V1 });
  });
  test("a cloud failure leaves the change recorded and the forge marked failed", async () => {
    failNext = true;
    const r = await updatePinned(app, admin(), "acme", { version: V2 });
    expect(r).toMatchObject({ ok: false });
    expect(getPinned(app.db, "acme")).toMatchObject({ version: V2, state: "failed" });
    expect(changesOf(app.db, getPinned(app.db, "acme")!.id)[0]).toMatchObject({ kind: "update", toVersion: V2 });
  });
  test("a forge with only its first version has nothing to roll back to", async () => {
    app.db.run("UPDATE pinned_forge SET name = 'old' WHERE name = 'acme'");
    const r = await deployPinned(app, admin(), input({ name: "fresh" }));
    expect(r.ok).toBe(true);
    expect(await rollbackPinned(app, admin(), "fresh")).toMatchObject({ ok: false });
  });
  test("Cloudflare and Vercel are refused with a reason; AWS and Azure are named as not written", async () => {
    for (const target of ["cloudflare", "vercel", "aws", "azure"]) {
      const r = await deployPinned(app, admin(), input({ name: `x-${target}`, target }));
      expect(r.ok).toBe(false);
    }
    expect(TARGETS.map((t) => t.id)).toEqual(["digitalocean", "aws", "azure", "cloudflare", "vercel"]);
    expect(getPinned(app.db, "x-vercel")).toBeUndefined();
  });
  test("boot script and config hold no shell metacharacter that user text could smuggle", () => {
    expect(checkConfig({ A: "x\nB=1" }).ok).toBe(false);
    expect(checkConfig({ A: 'x"y' }).ok).toBe(false);
    expect(checkConfig({ "a b": "x" }).ok).toBe(false);
    const script = bootConfig({ name: "acme", source: SOURCE, version: V1, config: { A: "b" } });
    expect(script).toContain("A=b");
    expect(script.startsWith("#cloud-config")).toBe(true);
  });
  test("HTTP: the admin routes list, update and roll back; a member sees nothing", async () => {
    const tok = createToken(app.db, admin().id, "admin", "admin").token;
    const bob = createToken(app.db, getUserByName(app.db, "bob")!.id, "admin", "admin").token;
    const h = (t: string) => ({ authorization: `Bearer ${t}`, "content-type": "application/json" });
    const list = await fetch(`${servers.url}/api/v1/admin/pinned`, { headers: h(tok) });
    expect(list.status).toBe(200);
    const body = (await list.json()) as any;
    expect(body.targets).toHaveLength(5);
    expect(body.items.length).toBeGreaterThan(0);
    expect((await fetch(`${servers.url}/api/v1/admin/pinned`, { headers: h(bob) })).status).toBeGreaterThanOrEqual(403);
    const up = await fetch(`${servers.url}/api/v1/admin/pinned/fresh/update`, { method: "POST", headers: h(tok), body: JSON.stringify({ version: V2 }) });
    expect(up.status).toBe(200);
    expect(((await up.json()) as any).version).toBe(V2);
    const back = await fetch(`${servers.url}/api/v1/admin/pinned/fresh/rollback`, { method: "POST", headers: h(tok), body: "{}" });
    expect(((await back.json()) as any).version).toBe(V1);
    const bad = await fetch(`${servers.url}/api/v1/admin/pinned/fresh/update`, { method: "POST", headers: h(tok), body: JSON.stringify({ version: "main" }) });
    expect(bad.status).toBe(422);
    const missing = await fetch(`${servers.url}/api/v1/admin/pinned/nope/rollback`, { method: "POST", headers: h(tok), body: "{}" });
    expect(missing.status).toBe(404);
  });
  test("MCP pinned_forge lists and updates for an admin-scope token", async () => {
    const tok = createToken(app.db, admin().id, "admin", "admin").token;
    const call = async (args: Record<string, unknown>) => {
      const res = await fetch(`${servers.url}/mcp`, {
        method: "POST",
        headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${tok}` },
        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "pinned_forge", arguments: args } }),
      });
      const text = ((await res.json()) as any).result.content[0].text as string;
      return text.startsWith("{") ? JSON.parse(text) : { text };
    };
    expect((await call({ verb: "list" })).items.length).toBeGreaterThan(0);
    expect((await call({ verb: "update", name: "fresh", version: V2 })).says).toContain(V2);
    expect((await call({ verb: "update", name: "fresh", version: "nope" })).text).toContain("full 40-character");
  });
});
		@@ -0,0 +1,48 @@
	1	# A pinned forge (#8697)
	2
	3	A pinned forge is a forge the owner put on their own cloud. It has no crew and no automatic release. Its version and config change only through one explicit `Update`, recorded with who and when; `Rollback` is one action to the previous version.
	4
	5	## Doors (forge admin, admin-scope token)
	6
	7	- HTTP: `GET /api/v1/admin/pinned` (forges, their changes, the targets), `POST /api/v1/admin/pinned` (deploy), `POST /api/v1/admin/pinned/:name/update`, `POST /api/v1/admin/pinned/:name/rollback`.
	8	- Terminal: palette → Pinned forges (forge admin): `d` deploy, `u` update, `r` roll back; it follows the bus, so a change made at any door shows at once (`src/tui/screens/pinned.ts`).
	9	- MCP: `pinned_forge` with `verb` `list`, `deploy`, `update`, `rollback` — the same words and the same checks (`src/actions/pinned.ts`).
	10
	11	A deploy names a cloud account (Settings → Cloud accounts, writes allowed), the app (`owner/name`), a git `source` (https) and a `version` (a 40-character commit id or a tag like `v1.2.3` — never a branch, so nothing moves under it).
	12
	13	## Why it cannot move on its own
	14
	15	`pinned_forge.version` and `.config` are guarded by a SQLite trigger (migration `20261103090000-pinned-forge`): an UPDATE passes only with a `change_id` that points at a newer `update` or `rollback` row in `pinned_change` whose target is exactly the new version and config. `pinned_change` cannot be updated or deleted. `crew` and `auto_release` are CHECKed to 0. `test/pinned-forge.test.ts` tries each other way and fails if one works. A pinned forge is a row and a droplet, not a repository on this forge, so the crew, the release keeper and upstream following have nothing of it to touch.
	16
	17	## Credentials
	18
	19	The cloud token stays sealed. It is opened for the one call that needs it (a `secret.read` event names the run), sent as an `Authorization` header over HTTPS, and never reaches argv, a row, an event, a request body or the boot script. The boot script holds no secret: the new forge's first visitor claims it. Config refuses names that look like secrets.
	20
	21	## Targets: what runs, what it costs, what is refused
	22
	23	Prices are list prices as last read (USD a month); the owner's own bill is the truth. Source of truth in code: `src/cloud/targets.ts`.
	24
	25	\| Target \| Status \| What runs \| Cost \| Refused / caveat \|
	26	\|---\|---\|---\|---\|---\|
	27	\| DigitalOcean \| deploys today \| One droplet (`s-1vcpu-2gb`, Ubuntu 24.04) with a 10 GiB block volume as `FORGE_APP_DATA`. An Update deletes the droplet and starts a new one on the same volume, so data is untouched. \| ~$12 + ~$1.20 \| A token cannot be narrowed below "create droplets and volumes". \|
	28	\| AWS \| not written \| EC2 `t4g.small` + EBS gp3, same boot script; SigV4 already exists for reads. \| ~$12 + ~$0.80 + public IPv4 ~$3.65 \| Wants a role scoped to a tag rather than a long-lived key. \|
	29	\| Azure \| not written \| B1ms VM + managed disk through a service principal on one resource group. \| ~$15 + ~$1 + public IP ~$3.65 \| Needs a resource group, network and public IP first: three calls more. \|
	30	\| Cloudflare \| refused \| Workers/Durable Objects keep state, but not as files a Bun process opens. Containers run, with a disk wiped on sleep or replace. \| Workers Paid from $5 \| No volume that survives; the forge refuses rather than lose repositories quietly. \|
	31	\| Vercel \| refused \| Functions and Sandboxes: short-lived, scratch disk. \| Pro from $20/seat \| No long-running process, no persistent disk. Vercel can host an app a forge ships, not the forge. \|
	32
	33	The cloud facts for Cloudflare and Vercel are from memory of their documentation, last written 2026-11-02; check them before relying on a refusal for a decision beyond this forge.
	34
	35	## Prior art
	36
	37	Open-source "Deploy to" buttons (Heroku's `app.json`, Render's `render.yaml`, DigitalOcean's App Platform button, Railway templates) are a link carrying a repository and a settings file to a provider's sign-in. That is the shape for the button: a link with `app`, `source`, `version` that lands on the Deploy form after one sign-in. The older `deploy/` cloud path and the child-forge path (#4416, #2928, #3785) are the other prior art; neither pins.
	38
	39	## Failing half-way
	40
	41	Each id is recorded the moment it exists. A first deploy that fails before a droplet exists leaves a `failed` row with the volume's id; deploying the same name again reuses that volume. An Update deletes the old droplet and clears its id at once; a 404 on that delete counts as deleted, so after a failed create a Rollback or another Update goes straight to creating. A `failed` forge may be told the version it already has, to finish the replacement. The droplet installs the Bun in `BUN_VERSION` (`src/cloud/droplet.ts`), so the runtime moves only when a pull moves it.
	42
	43	## Not done
	44
	45	- No canary on a real account: #8746.
	46	- No `Deploy to…` page or link: #8744.
	47	- The droplet's address is not read back, so no URL is shown, no TLS or domain, no health check: #8745.
	48	- AWS and Azure drivers.
		@@ -0,0 +1,147 @@
	1	/**
	2	* Pinned forges, as a forge admin reaches them (#8697): `deploy` puts one on
	3	* the owner's cloud, `update` is the only way its version or config change,
	4	* `rollback` is one action back to the previous version. All three are the
	5	* admin's, need the cloud account's writes switched on, and open the sealed
	6	* token for the one call that needs it (a `secret.read` event names it). Each
	7	* change is recorded with who and when before the cloud is touched; if the
	8	* cloud refuses, the record stays and the forge says `failed`, so nothing
	9	* moves without a line saying so.
	10	*/
	11
	12	import type { App } from "../app.ts";
	13	import { gatedFetch } from "../cloud/gate.ts";
	14	import { provision, replace } from "../cloud/droplet.ts";
	15	import type { Fetch } from "../cloud/providers.ts";
	16	import { target as targetOf } from "../cloud/targets.ts";
	17	import { getCloudAccount, secretNameOf } from "../core/cloud_account.ts";
	18	import {
	19	APP, NAME, changesOf, checkConfig, getPinned, insertPinned, listPinned, previousOf,
	20	dropPinned, recordChange, setRemote, validSource, validVersion, type Change, type Pinned,
	21	} from "../core/pinned.ts";
	22	import { resolveSecrets } from "../core/secret_store.ts";
	23	import type { User } from "../core/users.ts";
	24	import { err, ok, type Result } from "../kernel/result.ts";
	25
	26	/** Swapped in tests; the real forge always uses `fetch`. */
	27	export const net: { fetch: Fetch } = { fetch: (u, i) => fetch(u, i) };
	28
	29	const admin = (a: User \| undefined): Result<User, string> => (a?.isAdmin ? ok(a) : err("not_found"));
	30
	31	export interface PinnedView extends Pinned {
	32	readonly crew: false;
	33	readonly autoRelease: false;
	34	readonly changes: Change[];
	35	}
	36
	37	const view = (app: App, p: Pinned): PinnedView => ({ ...p, crew: false, autoRelease: false, changes: changesOf(app.db, p.id) });
	38
	39	export function pinnedForges(app: App, actor: User \| undefined): Result<PinnedView[], string> {
	40	const who = admin(actor);
	41	return who.ok ? ok(listPinned(app.db).map((p) => view(app, p))) : who;
	42	}
	43
	44	/** Open the account's token and run `go` with a gated fetch; the token never leaves this scope. */
	45	async function withCloud<T>(app: App, who: User, p: Pinned, purpose: string, go: (f: Fetch, token: string) => Promise<T>): Promise<Result<T, string>> {
	46	const account = getCloudAccount(app.db, p.target, p.account);
	47	if (!account) return err("No such cloud account.");
	48	if (!account.writeAllowed) return err("That cloud account is read-only; allow writes on it first.");
	49	const secret = secretNameOf(account.provider, account.name);
	50	const token = resolveSecrets(app.db, app.config.dataDir, app.bus, [secret], { actor: who.id, run: `pinned:${purpose}` })[secret];
	51	if (token === undefined) return err("No such credential.");
	52	try {
	53	return ok(await go(gatedFetch(app.db, { provider: p.target, account: p.account }, `pinned:${purpose}`, net.fetch), token));
	54	} catch (e) {
	55	return err(`The cloud refused: ${e instanceof Error ? e.message.slice(0, 200) : "failed"}`);
	56	}
	57	}
	58
	59	export async function deployPinned(
	60	app: App,
	61	actor: User \| undefined,
	62	input: { name: string; target: string; account: string; app: string; source: string; version: string; config?: unknown },
	63	): Promise<Result<PinnedView, string>> {
	64	const who = admin(actor);
	65	if (!who.ok) return who;
	66	const t = targetOf(input.target);
	67	if (!t) return err("That is not a target the forge knows.");
	68	if (t.status === "refused") return err(t.refused);
	69	if (t.status !== "first") return err(`${t.label} is not written yet: ${t.refused}`);
	70	if (!NAME.test(input.name)) return err("A name is lowercase letters, digits and dashes, starting with a letter.");
	71	if (!APP.test(input.app)) return err("Name the app as owner/name.");
	72	if (!validSource(input.source)) return err("The source is an https git address.");
	73	if (!validVersion(input.version)) return err("A version is a full 40-character commit id or a tag like v1.2.3.");
	74	const config = checkConfig(input.config);
	75	if (!config.ok) return config;
	76	// A first deploy that failed before any droplet exists may be tried again: its row goes,
	77	// its volume (if one was made) is kept for the retry, and the new deploy is recorded afresh.
	78	const old = getPinned(app.db, input.name);
	79	if (old && !(old.state === "failed" && old.remote === "" && old.target === t.id)) return err("A pinned forge has that name already.");
	80	if (old) dropPinned(app.db, old.name);
	81	const p = insertPinned(app.db, { ...input, target: t.id, config: config.value }, who.value.id);
	82	app.bus.append({ kind: "pinned.deployed", actorId: who.value.id, payload: { name: p.name, target: p.target, version: p.version } });
	83	if (old?.volume) setRemote(app.db, p.name, { volume: old.volume });
	84	const made = await withCloud(app, who.value, p, "deploy", (f, token) =>
	85	provision(f, token, getPinned(app.db, p.name)!, {
	86	...(old?.volume ? { have: old.volume } : {}),
	87	onVolume: (volume) => setRemote(app.db, p.name, { volume }),
	88	}),
	89	);
	90	if (!made.ok) {
	91	setRemote(app.db, p.name, { state: "failed" });
	92	return made;
	93	}
	94	setRemote(app.db, p.name, { ...made.value, state: "running" });
	95	return ok(view(app, getPinned(app.db, p.name)!));
	96	}
	97
	98	async function change(
	99	app: App,
	100	actor: User \| undefined,
	101	name: string,
	102	kind: "update" \| "rollback",
	103	next: (p: Pinned) => Result<{ version: string; config: Record<string, string> }, string>,
	104	): Promise<Result<PinnedView, string>> {
	105	const who = admin(actor);
	106	if (!who.ok) return who;
	107	const before = getPinned(app.db, name);
	108	if (!before) return err("No such pinned forge.");
	109	const to = next(before);
	110	if (!to.ok) return to;
	111	const same = to.value.version === before.version && JSON.stringify(to.value.config) === JSON.stringify(before.config);
	112	// A failed forge may be asked again for what it already says, to finish the replacement; nothing new to record.
	113	if (same && before.state !== "failed") return err("That is what it runs already.");
	114	if (!same) {
	115	const c = recordChange(app.db, before, kind, to.value, who.value.id);
	116	app.bus.append({ kind: kind === "update" ? "pinned.update" : "pinned.rollback", actorId: who.value.id, payload: { name, from: c.fromVersion, to: c.toVersion } });
	117	}
	118	const after = getPinned(app.db, name)!;
	119	const done = await withCloud(app, who.value, after, kind, (f, token) => replace(f, token, after, { onDeleted: () => setRemote(app.db, name, { remote: "" }) }));
	120	if (!done.ok) {
	121	setRemote(app.db, name, { state: "failed" });
	122	return done;
	123	}
	124	setRemote(app.db, name, { ...done.value, state: "running" });
	125	return ok(view(app, getPinned(app.db, name)!));
	126	}
	127
	128	/** The only door to a new version or config. Either may be left as it is. */
	129	export const updatePinned = (
	130	app: App,
	131	actor: User \| undefined,
	132	name: string,
	133	input: { version?: string \| undefined; config?: unknown },
	134	): Promise<Result<PinnedView, string>> =>
	135	change(app, actor, name, "update", (p) => {
	136	const version = input.version ?? p.version;
	137	if (!validVersion(version)) return err("A version is a full 40-character commit id or a tag like v1.2.3.");
	138	const config = input.config === undefined ? ok(p.config) : checkConfig(input.config);
	139	return config.ok ? ok({ version, config: config.value }) : config;
	140	});
	141
	142	/** One action back to what the latest change replaced. */
	143	export const rollbackPinned = (app: App, actor: User \| undefined, name: string): Promise<Result<PinnedView, string>> =>
	144	change(app, actor, name, "rollback", (p) => {
	145	const prev = previousOf(app.db, p);
	146	return prev ? ok(prev) : err("There is no previous version: this forge has only ever run one.");
	147	});
		@@ -0,0 +1,123 @@
	1	/**
	2	* DigitalOcean, the first target (#8697): the requests that put a pinned
	3	* forge on a droplet with a volume, and replace the droplet on an explicit
	4	* Update while the volume — the forge's data — stays. Plain data in, plain
	5	* data out: the caller owns the token and the fetch. The token travels in an
	6	* Authorization header over HTTPS, never on argv, and the boot script holds no
	7	* secret at all: the new forge's first visitor claims it at /first-admin.
	8	*
	9	* Calls (DigitalOcean API v2): POST /volumes, POST /droplets, DELETE /droplets/{id}.
	10	* The caller records each id the moment it exists (`onVolume`, `onDeleted`),
	11	* so a failure half-way leaves a row a retry can finish, never an orphan.
	12	*/
	13
	14	import type { Fetch } from "./providers.ts";
	15	import type { Pinned } from "../core/pinned.ts";
	16
	17	const API = "https://api.digitalocean.com/v2";
	18	export const REGION = "nyc3";
	19	export const SIZE = "s-1vcpu-2gb";
	20	/** The Bun the droplet installs: it moves only when this line does, in a pull, so the runtime is pinned as the forge is. */
	21	export const BUN_VERSION = "1.3.14";
	22
	23	/** cloud-config for the droplet: Bun, the pinned source at the pinned version, a systemd unit. */
	24	export function bootConfig(p: Pick<Pinned, "name" \| "source" \| "version" \| "config">): string {
	25	// DigitalOcean mounts a volume at /mnt/<its name, dashes as underscores>.
	26	const data = `/mnt/${volumeName(p.name).replace(/-/g, "_")}`;
	27	const env = Object.entries({ ...p.config, FORGE_APP_DATA: data })
	28	.map(([k, v]) => `${k}=${v}`)
	29	.join("\n");
	30	// Every interpolated value is validated in core/pinned.ts (version, source, config) or by NAME.
	31	return `#cloud-config
	32	write_files:
	33	- path: /etc/forge/env
	34	permissions: "0600"
	35	content: ${JSON.stringify(env + "\n")}
	36	- path: /etc/systemd/system/forge.service
	37	content: \|
	38	[Unit]
	39	Description=forge ${p.name} pinned at ${p.version}
	40	After=network-online.target
	41	[Service]
	42	EnvironmentFile=/etc/forge/env
	43	WorkingDirectory=/opt/forge
	44	ExecStart=/root/.bun/bin/bun run src/main.ts
	45	Restart=on-failure
	46	[Install]
	47	WantedBy=multi-user.target
	48	runcmd:
	49	- curl -fsSL https://bun.sh/install \| bash -s "bun-v${BUN_VERSION}"
	50	- git clone ${p.source} /opt/forge
	51	- git -C /opt/forge checkout --detach ${p.version}
	52	- systemctl enable --now forge.service
	53	`;
	54	}
	55
	56	const headers = (token: string) => ({ authorization: `Bearer ${token}`, "content-type": "application/json" });
	57
	58	async function call(f: Fetch, token: string, method: string, path: string, body?: unknown): Promise<any> {
	59	const res = await f(`${API}${path}`, {
	60	method,
	61	headers: headers(token),
	62	...(body === undefined ? {} : { body: JSON.stringify(body) }),
	63	signal: AbortSignal.timeout(20_000),
	64	});
	65	if (!res.ok) throw new Error(`api.digitalocean.com answered ${res.status}`);
	66	return res.status === 204 ? {} : await res.json();
	67	}
	68
	69	const volumeName = (name: string) => `forge-${name}-data`;
	70
	71	function createDroplet(f: Fetch, token: string, p: Pinned, volumeId: string) {
	72	return call(f, token, "POST", "/droplets", {
	73	name: `forge-${p.name}`,
	74	region: REGION,
	75	size: SIZE,
	76	image: "ubuntu-24-04-x64",
	77	volumes: [volumeId],
	78	user_data: bootConfig(p),
	79	tags: ["forge-pinned"],
	80	});
	81	}
	82
	83	/**
	84	* Volume first, then the droplet that mounts it. A volume a failed earlier try
	85	* made (`have`) is reused; a new one is recorded through `onVolume` before the
	86	* droplet is asked for. Returns the ids to keep.
	87	*/
	88	export async function provision(
	89	f: Fetch, token: string, p: Pinned, hooks: { have?: string; onVolume(id: string): void },
	90	): Promise<{ remote: string; volume: string }> {
	91	let volume = hooks.have ?? "";
	92	if (volume === "") {
	93	const v = await call(f, token, "POST", "/volumes", {
	94	name: volumeName(p.name), region: REGION, size_gigabytes: 10, filesystem_type: "ext4",
	95	});
	96	volume = String(v.volume?.id ?? "");
	97	if (!volume) throw new Error("DigitalOcean made no volume");
	98	hooks.onVolume(volume);
	99	}
	100	const d = await createDroplet(f, token, p, volume);
	101	return { remote: String(d.droplet?.id ?? ""), volume };
	102	}
	103
	104	/**
	105	* An explicit Update or rollback: delete the old droplet, start a new one on
	106	* the same volume. A droplet already gone (404, or none recorded after a failed
	107	* create) counts as deleted, and `onDeleted` clears the recorded id at once, so
	108	* a retry after a failed create does not delete twice.
	109	*/
	110	export async function replace(f: Fetch, token: string, p: Pinned, hooks: { onDeleted(): void }): Promise<{ remote: string }> {
	111	if (p.volume === "") throw new Error("this forge has no volume to keep");
	112	if (p.remote !== "") {
	113	if (!/^\d+$/.test(p.remote)) throw new Error("this forge has no droplet to replace");
	114	try {
	115	await call(f, token, "DELETE", `/droplets/${p.remote}`);
	116	} catch (e) {
	117	if (!(e instanceof Error && e.message.endsWith("answered 404"))) throw e;
	118	}
	119	hooks.onDeleted();
	120	}
	121	const d = await createDroplet(f, token, p, p.volume);
	122	return { remote: String(d.droplet?.id ?? "") };
	123	}
		@@ -0,0 +1,64 @@
	1	/**
	2	* Where a forge can be put, and what each place can and cannot hold (#8697).
	3	* A forge is a Bun process, SQLite and a disk that outlives the process, so a
	4	* target needs a machine and a volume. Prices are list prices for the
	5	* smallest size that runs a forge, USD a month, as last read; the page says
	6	* so, and the owner's own bill is the truth.
	7	*/
	8
	9	export type TargetId = "digitalocean" \| "aws" \| "azure" \| "cloudflare" \| "vercel";
	10
	11	export interface Target {
	12	readonly id: TargetId;
	13	readonly label: string;
	14	/** `first` deploys today; `planned` has a machine and a volume but no driver yet; `refused` cannot hold a forge. */
	15	readonly status: "first" \| "planned" \| "refused";
	16	readonly runs: string;
	17	readonly cost: string;
	18	readonly refused: string;
	19	}
	20
	21	export const TARGETS: readonly Target[] = [
	22	{
	23	id: "digitalocean",
	24	label: "DigitalOcean",
	25	status: "first",
	26	runs: "One droplet (Ubuntu, Bun from the pinned source) with one block volume mounted as FORGE_APP_DATA. Replacing the droplet keeps the volume, so a version change never touches the data.",
	27	cost: "about $12 (s-1vcpu-2gb) + $1.20 (10 GiB volume)",
	28	refused: "Nothing the forge needs is refused; the token must be able to create droplets and volumes, which DigitalOcean cannot narrow further.",
	29	},
	30	{
	31	id: "aws",
	32	label: "AWS",
	33	status: "planned",
	34	runs: "One EC2 instance (t4g.small) with one EBS gp3 volume, same boot script. Needs SigV4 signing for RunInstances, which providers.ts already does for reads.",
	35	cost: "about $12 + $0.80 (10 GiB gp3) + a public IPv4 address, about $3.65",
	36	refused: "A long-lived access key with EC2 write is the broadest credential of the three; the driver will ask for a role scoped to one tag, and is not written yet.",
	37	},
	38	{
	39	id: "azure",
	40	label: "Azure",
	41	status: "planned",
	42	runs: "One VM (B1ms) with one managed disk, through a service principal with Contributor on one resource group.",
	43	cost: "about $15 + $1 (10 GiB standard SSD) + a public IP, about $3.65",
	44	refused: "Not written yet: it needs a resource group, a network and a public IP created first, so it is three calls more than the droplet.",
	45	},
	46	{
	47	id: "cloudflare",
	48	label: "Cloudflare",
	49	status: "refused",
	50	runs: "Workers and Durable Objects hold state, but not as a file system a Bun process can open. Cloudflare Containers run a container, with a disk that is wiped when the container sleeps or is replaced.",
	51	cost: "Workers Paid, $5 a month minimum, plus container time",
	52	refused: "A forge keeps bare git repositories and SQLite on a disk that survives restarts. Cloudflare offers no such volume to a container, so the forge refuses to put one there rather than lose data quietly.",
	53	},
	54	{
	55	id: "vercel",
	56	label: "Vercel",
	57	status: "refused",
	58	runs: "Functions and Sandboxes: short-lived, one request or one task, with a scratch disk that does not persist.",
	59	cost: "Pro from $20 a seat a month",
	60	refused: "No long-running process and no persistent disk, so a forge cannot live there. Vercel can host an app a forge ships, which is a different thing.",
	61	},
	62	];
	63
	64	export const target = (id: string): Target \| undefined => TARGETS.find((t) => t.id === id);
		@@ -0,0 +1,12 @@
	1	import type { Route } from "../shared.ts";
	2
	3	export const route: Route = {
	4	method: "get",
	5	path: "/api/v1/admin/pinned",
	6	summary: "The forge's pinned forges with each one's recorded changes, and the targets with what each can and cannot host; a forge administrator's",
	7	auth: true,
	8	refusals: {
	9	not_found: "only a forge administrator sees this route",
	10	refused: "the request was understood and refused; the message says why (422)",
	11	},
	12	};
		@@ -35,6 +35,7 @@ export { route as getApiV1AdminDrills } from "./getApiV1AdminDrills.ts";
35	35	export { route as getApiV1AdminInvites } from "./getApiV1AdminInvites.ts";
36	36	export { route as getApiV1AdminLimits } from "./getApiV1AdminLimits.ts";
37	37	export { route as getApiV1AdminPeople } from "./getApiV1AdminPeople.ts";
	38	export { route as getApiV1AdminPinned } from "./getApiV1AdminPinned.ts";
38	39	export { route as getApiV1AdminProfile } from "./getApiV1AdminProfile.ts";
39	40	export { route as getApiV1AdminQuotas } from "./getApiV1AdminQuotas.ts";
40	41	export { route as getApiV1AdminSettings } from "./getApiV1AdminSettings.ts";
		@@ -193,6 +194,9 @@ export { route as postApiV1AdminAccountsUsernameSuspend } from "./postApiV1Admin
193	194	export { route as postApiV1AdminAccountsUsernameUnsuspend } from "./postApiV1AdminAccountsUsernameUnsuspend.ts";
194	195	export { route as postApiV1AdminAccountsUsernameVerify } from "./postApiV1AdminAccountsUsernameVerify.ts";
195	196	export { route as postApiV1AdminInvites } from "./postApiV1AdminInvites.ts";
	197	export { route as postApiV1AdminPinned } from "./postApiV1AdminPinned.ts";
	198	export { route as postApiV1AdminPinnedNameRollback } from "./postApiV1AdminPinnedNameRollback.ts";
	199	export { route as postApiV1AdminPinnedNameUpdate } from "./postApiV1AdminPinnedNameUpdate.ts";
196	200	export { route as postApiV1AdminReleasesShaRollback } from "./postApiV1AdminReleasesShaRollback.ts";
197	201	export { route as postApiV1Agents } from "./postApiV1Agents.ts";
198	202	export { route as postApiV1Apps } from "./postApiV1Apps.ts";
		@@ -0,0 +1,14 @@
	1	import type { Route } from "../shared.ts";
	2
	3	export const route: Route = {
	4	method: "post",
	5	path: "/api/v1/admin/pinned",
	6	summary: "Put a pinned forge on the owner's cloud: no crew, no automatic release; needs an admin-scope token and a cloud account with writes allowed",
	7	auth: true,
	8	status: 201,
	9	body: { name: "string", target: "string", account: "string", app: "string", source: "string", version: "string", config: "object" },
	10	refusals: {
	11	not_found: "only a forge administrator sees this route",
	12	refused: "the request was understood and refused; the message says why (422)",
	13	},
	14	};
		@@ -0,0 +1,13 @@
	1	import type { Route } from "../shared.ts";
	2
	3	export const route: Route = {
	4	method: "post",
	5	path: "/api/v1/admin/pinned/{name}/update",
	6	summary: "The only way a pinned forge changes version or config; recorded with who and when",
	7	auth: true,
	8	body: { version: "string", config: "object" },
	9	refusals: {
	10	not_found: "only a forge administrator sees this route",
	11	refused: "the request was understood and refused; the message says why (422)",
	12	},
	13	};
		@@ -176,6 +176,8 @@ export function classifiedAudience(kind: string): EventAudience \| undefined {
176	176	kind === "forge.upstream" \|\|
177	177	kind === "forge.updates_taken" \|\|
178	178	kind === "cloud.write_allowed" \|\|
	179	// A pinned forge's deploy, update and rollback name the owner's cloud (#8697).
	180	kind.startsWith("pinned.") \|\|
179	181	// Which of a person's connected accounts a mirror syncs through is too.
180	182	kind.startsWith("origin.") \|\|
181	183	kind === "repo.settings_updated" \|\|
		@@ -0,0 +1,1 @@
	1	b0bf868cfb029ac5288cae0d3f2a0e01db2d98774f1072f220e6ef2c295df7a6