86254a3 · 754edec · adecc14
@@ -6,7 +6,7 @@
A pinned forge is a forge the owner put on their own cloud. It has **no crew** a
- 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`).
- MCP: `pinned_forge` with `verb` `list`, `deploy`, `update`, `rollback` (and `check`) — 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).
@@ -36,6 +36,10 @@
The cloud facts for Cloudflare and Vercel are from memory of their documentation
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.
## Address and health check (#8745)
`check` (`POST /api/v1/admin/pinned/:name/check`, MCP `pinned_forge` verb `check`, terminal `c`) reads the droplet from DigitalOcean (`GET /droplets/{id}`, read-only, no write permission needed), records its public IPv4 (`pinned_forge.address`, validated as IPv4), and probes `http://<address>:<PORT or 3000>/`. Every view carries `url` (empty until an address is read). A forge that answers is set `running`, so a `failed` one recovers by itself once its droplet is up; one that does not answer keeps its state and the result says `healthy: false`. Deploy and Update do not read the address: a new droplet has none for a while, so ask with `check`.
## 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.
@@ -44,5 +48,6 @@
Each id is recorded the moment it exists. A first deploy that fails before a dro
- 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.
- No TLS or domain: the URL is `http://<droplet IPv4>:<PORT or 3000>/`.
- No page in the web studio shows the pinned forges yet; the API, MCP and terminal do.
- AWS and Azure drivers.
@@ -11,30 +11,32 @@
import type { App } from "../app.ts";
import { gatedFetch } from "../cloud/gate.ts";
import { provision, replace } from "../cloud/droplet.ts";
import { provision, readDroplet, 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,
  dropPinned, recordChange, setRemote, urlOf, 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) };
export const net: { fetch: Fetch; probe: Fetch } = { fetch: (u, i) => fetch(u, i), probe: (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 {
  /** Where it is served, once the droplet's address is read; empty before. */
  readonly url: string;
  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) });
const view = (app: App, p: Pinned): PinnedView => ({ ...p, url: urlOf(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);
@@ -42,10 +44,10 @@
export function pinnedForges(app: App, actor: User | undefined): Result<PinnedVi
}
/** 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>> {
async function withCloud<T>(app: App, who: User, p: Pinned, purpose: string, go: (f: Fetch, token: string) => Promise<T>, writes = true): 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.");
  if (writes && !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.");
@@ -56,6 +58,16 @@
async function withCloud<T>(app: App, who: User, p: Pinned, purpose: string, go:
  }
}
/** Read the droplet back and record its public IPv4 (empty while none is assigned). The cloud's refusal is returned, so "no address yet" and "the call was refused" differ. */
async function readAddress(app: App, who: User, name: string): Promise<Result<string, string>> {
  const p = getPinned(app.db, name);
  if (!p || p.remote === "") return ok("");
  const seen = await withCloud(app, who, p, "address", (f, token) => readDroplet(f, token, p.remote), false);
  if (!seen.ok) return seen;
  if (seen.value.address !== "") setRemote(app.db, name, { address: seen.value.address });
  return ok(seen.value.address);
}
export async function deployPinned(
  app: App,
  actor: User | undefined,
@@ -116,12 +128,12 @@
async function change(
    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: "" }) }));
  const done = await withCloud(app, who.value, after, kind, (f, token) => replace(f, token, after, { onDeleted: () => setRemote(app.db, name, { remote: "", address: "" }) }));
  if (!done.ok) {
    setRemote(app.db, name, { state: "failed" });
    return done;
  }
  setRemote(app.db, name, { ...done.value, state: "running" });
  setRemote(app.db, name, { ...done.value, address: "", state: "running" });
  return ok(view(app, getPinned(app.db, name)!));
}
@@ -145,3 +157,35 @@
export const rollbackPinned = (app: App, actor: User | undefined, name: string):
    const prev = previousOf(app.db, p);
    return prev ? ok(prev) : err("There is no previous version: this forge has only ever run one.");
  });
/**
 * The health check: read the droplet's address back, ask the forge there for
 * its front page, and say what it answered. A forge that answers is `running`,
 * so one marked `failed` by a refused call recovers by itself once its droplet
 * is up; one that does not answer keeps its state, and `healthy` is false.
 */
export async function checkPinned(app: App, actor: User | undefined, name: string): Promise<Result<PinnedView & { healthy: boolean }, string>> {
  const who = admin(actor);
  if (!who.ok) return who;
  const p = getPinned(app.db, name);
  if (!p) return err("No such pinned forge.");
  if (p.remote === "") return err("This forge has no droplet yet; deploy or update it first.");
  const read = await readAddress(app, who.value, name);
  if (!read.ok) return read;
  const now = getPinned(app.db, name)!;
  let healthy = false;
  if (now.address !== "") {
    // The probe is audited like every other call made for this account; the address is a validated public IPv4 and the port is 1-65535.
    const probe = gatedFetch(app.db, { provider: now.target, account: now.account }, "pinned:probe", net.probe);
    try {
      const res = await probe(urlOf(now), { signal: AbortSignal.timeout(5_000), redirect: "manual" });
      healthy = res.status >= 200 && res.status < 400;
    } catch {
      healthy = false;
    }
  }
  if (healthy && now.state !== "running") setRemote(app.db, name, { state: "running" });
  const after = getPinned(app.db, name)!;
  app.bus.append({ kind: "pinned.check", actorId: who.value.id, payload: { name, address: after.address, state: after.state, healthy } });
  return ok({ ...view(app, after), healthy });
}
@@ -6,7 +6,8 @@
 * 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}.
 * Calls (DigitalOcean API v2): POST /volumes, POST /droplets, DELETE /droplets/{id}, GET /droplets/{id}
 * (the public IPv4 the droplet was given, read back after it boots).
 * 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.
 */
@@ -121,3 +122,14 @@
export async function replace(f: Fetch, token: string, p: Pinned, hooks: { onDel
  const d = await createDroplet(f, token, p, p.volume);
  return { remote: String(d.droplet?.id ?? "") };
}
const IPV4 = /^(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)$/;
/** Read the droplet back: its status and public IPv4 (empty while none is assigned). Only a well-formed address is returned. */
export async function readDroplet(f: Fetch, token: string, remote: string): Promise<{ status: string; address: string }> {
  if (!/^\d+$/.test(remote)) throw new Error("this forge has no droplet to read");
  const d = (await call(f, token, "GET", `/droplets/${remote}`)).droplet;
  const v4: unknown[] = Array.isArray(d?.networks?.v4) ? d.networks.v4 : [];
  const pub = v4.find((n: any) => n?.type === "public" && typeof n.ip_address === "string" && IPV4.test(n.ip_address)) as { ip_address: string } | undefined;
  return { status: String(d?.status ?? ""), address: pub?.ip_address ?? "" };
}
@@ -195,6 +195,7 @@
export { route as postApiV1AdminAccountsUsernameUnsuspend } from "./postApiV1Adm
export { route as postApiV1AdminAccountsUsernameVerify } from "./postApiV1AdminAccountsUsernameVerify.ts";
export { route as postApiV1AdminInvites } from "./postApiV1AdminInvites.ts";
export { route as postApiV1AdminPinned } from "./postApiV1AdminPinned.ts";
export { route as postApiV1AdminPinnedNameCheck } from "./postApiV1AdminPinnedNameCheck.ts";
export { route as postApiV1AdminPinnedNameRollback } from "./postApiV1AdminPinnedNameRollback.ts";
export { route as postApiV1AdminPinnedNameUpdate } from "./postApiV1AdminPinnedNameUpdate.ts";
export { route as postApiV1AdminReleasesShaRollback } from "./postApiV1AdminReleasesShaRollback.ts";
@@ -0,0 +1,12 @@
import type { Route } from "../shared.ts";
export const route: Route = {
  method: "post",
  path: "/api/v1/admin/pinned/{name}/check",
  summary: "Read the droplet's public address back, probe the forge there, and say whether it answers; one that does is marked running",
  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,1 @@
13d9c395c67ccf46eae79e8a3f5c0af8f1f1d7a163d02ca5af83e8408d3b7e60
@@ -0,0 +1,5 @@
// The public IPv4 a pinned forge's droplet was read back with (#8745), so the
// forge can show the address it is served at. Additive; empty until it is read.
export default `
  ALTER TABLE pinned_forge ADD COLUMN address TEXT NOT NULL DEFAULT '';
  `;
@@ -20,6 +20,7 @@
export interface Pinned {
  readonly config: Record<string, string>;
  readonly remote: string;
  readonly volume: string;
  readonly address: string;
  readonly state: string;
  readonly createdAt: string;
}
@@ -71,13 +72,13 @@
export function checkConfig(raw: unknown): Result<Record<string, string>, string
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;
  version: string; config: string; remote: string; volume: string; address: 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,
  remote: r.remote, volume: r.volume, address: r.address, state: r.state, createdAt: r.created_at,
});
export const listPinned = (db: Database): Pinned[] =>
@@ -154,12 +155,21 @@
export function previousOf(db: Database, forge: Pinned): { version: string; conf
}
/** 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);
export function setRemote(db: Database, name: string, f: { remote?: string; volume?: string; address?: string; state?: string }): void {
  db.query("UPDATE pinned_forge SET remote = coalesce(?1, remote), volume = coalesce(?2, volume), address = coalesce(?3, address), state = coalesce(?4, state) WHERE name = ?5")
    .run(f.remote ?? null, f.volume ?? null, f.address ?? 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);
}
/** The port the forge listens on at its droplet: the config's PORT, else the forge's own default. */
export const portOf = (p: Pick<Pinned, "config">): string => {
  const n = Number(p.config["PORT"]);
  return /^\d{1,5}$/.test(p.config["PORT"] ?? "") && n >= 1 && n <= 65535 ? String(n) : "3000";
};
/** Where a pinned forge is served, once its droplet's address is known; empty before. */
export const urlOf = (p: Pick<Pinned, "address" | "config">): string => (p.address === "" ? "" : `http://${p.address}:${portOf(p)}/`);
@@ -14,7 +14,7 @@
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 { checkPinned, 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";
@@ -72,6 +72,13 @@
export function adminRoutes(router: Router<Handler>): void {
    return done.ok ? json(done.value) : pinnedFail(done.error);
  });
  router.add("POST", "/api/v1/admin/pinned/:name/check", async (ctx) => {
    const denied = accountAdmin(ctx, "admin");
    if (denied) return denied;
    const done = await checkPinned(ctx.app, ctx.auth.user, ctx.params.name!);
    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;
@@ -1,16 +1,16 @@
import { deployPinned, pinnedForges, rollbackPinned, updatePinned } from "../../../actions/pinned.ts";
import { checkPinned, 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).",
  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; `check` reads the droplet's address back and probes it (`url`, `healthy`). A forge admin with an admin-scope token",
  description: "Pinned forges on your cloud: list, deploy, update, rollback, check (admin).",
  inputSchema: {
    type: "object",
    properties: {
      verb: { type: "string", enum: ["list", "deploy", "update", "rollback"] },
      verb: { type: "string", enum: ["list", "deploy", "update", "rollback", "check"] },
      name: { type: "string", maxLength: 40 },
      target: { type: "string", enum: TARGETS.map((t) => t.id) },
      account: { type: "string", maxLength: 32 },
@@ -46,9 +46,11 @@
export const tool: Tool = {
            })
          : verb === "rollback"
            ? await rollbackPinned(ctx.app, user, name)
            : undefined;
    if (done === undefined) return bad("bad_verb", "verb is list, deploy, update or rollback");
            : verb === "check"
              ? await checkPinned(ctx.app, user, name)
              : undefined;
    if (done === undefined) return bad("bad_verb", "verb is list, deploy, update, rollback or check");
    if (!done.ok) return bad("refused", done.error);
    return good({ says: `${verb} ${name}: now ${done.value.version}, ${done.value.state}.`, forge: done.value });
    return good({ says: `${verb} ${name}: now ${done.value.version}, ${done.value.state}${done.value.url ? ` at ${done.value.url}` : ""}.`, forge: done.value });
  },
};
@@ -2,12 +2,13 @@
 * 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.
 * previous version, `c` reads the address back and probes it, 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 { checkPinned, 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";
@@ -52,9 +53,9 @@
export function pinnedScreen(f: Session, ctx: Ctx): Screen {
  const screen: Screen = {
    title: "Pinned forges",
    keys: [binding(["j", "k"], "move cursor"), binding(["d"], "deploy"), binding(["u"], "update"), binding(["r"], "roll back")],
    keys: [binding(["j", "k"], "move cursor"), binding(["d"], "deploy"), binding(["u"], "update"), binding(["r"], "roll back"), binding(["c"], "check")],
    async load(signal) {
      live(f, signal, { kinds: ["pinned.deployed", "pinned.update", "pinned.rollback"] }, () => ctx.invalidate());
      live(f, signal, { kinds: ["pinned.deployed", "pinned.update", "pinned.rollback", "pinned.check"] }, () => ctx.invalidate());
    },
    render(area, s) {
      const c = ctx.theme.c;
@@ -66,7 +67,7 @@
export function pinnedScreen(f: Session, ctx: Ctx): Screen {
      const rows: ListRow[] = forges().map((p) => ({
        title: p.name,
        ...(p.state === "failed" ? { tone: "danger" as const } : {}),
        secondary: `${p.target} · ${short(p.version)} · ${p.state}`,
        secondary: `${p.target} · ${short(p.version)} · ${p.state}${p.url !== "" ? ` · ${p.url}` : ""}`,
        meta: p.changes[0] ? `${p.changes[0].kind} ${p.changes[0].at.slice(0, 16).replace("T", " ")}` : "",
      }));
      drawList(s, list!, c, state, rows);
@@ -83,6 +84,9 @@
export function pinnedScreen(f: Session, ctx: Ctx): Screen {
      if (e.key === "r") {
        say(`Rolling ${p.name} back…`);
        void settle(rollbackPinned(f.app, f.user, p.name), "Rolled back");
      } else if (e.key === "c") {
        say(`Checking ${p.name}…`);
        void checkPinned(f.app, f.user, p.name).then((r) => say(r.ok ? `${p.name} ${r.value.healthy ? "answers" : "does not answer"}${r.value.url ? ` at ${r.value.url}` : " yet: no address"}.` : r.error));
      } else if (e.key === "u")
        ctx.push(
          promptScreen(ctx, screen, {
@@ -0,0 +1,188 @@
/**
 * A pinned forge's droplet address is read back (#8745): shown as a URL, and a
 * health check lets a failed forge recover. Tried at every door: the action,
 * the HTTP route, the MCP verb and the terminal key.
 */
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 { checkPinned, deployPinned, net, pinnedForges } from "../src/actions/pinned.ts";
import { readDroplet } from "../src/cloud/droplet.ts";
import { getPinned, portOf, setRemote } 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 { Session } from "../src/tui/session.ts";
import { pinnedScreen } from "../src/tui/screens/pinned.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
describe("pinned forge address", () => {
  let dataDir = "";
  let app: App;
  let servers: Servers;
  let networks: unknown = { v4: [{ type: "private", ip_address: "10.0.0.2" }, { type: "public", ip_address: "203.0.113.7" }] };
  let probeStatus = 200;
  let readStatus = 200;
  const probed: string[] = [];
  const admin = () => getUserByName(app.db, "alice")!;
  const deploy = (name: string) =>
    deployPinned(app, admin(), { name, target: "digitalocean", account: "main", app: "alice/shop", source: "https://forge.example.org/trevato/forge", version: "a".repeat(40), config: { PORT: "8080" } });
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-pinned-addr-"));
    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 });
    await addAccount(app, admin(), "digitalocean", "main", "dop_v1_9Zq4TxLm7Kp2Vb8nWcR5");
    allowWrite(app, admin(), "digitalocean", "main", true);
    net.fetch = async (url, init) => {
      const path = new URL(url).pathname;
      if (path === "/v2/volumes") return new Response(JSON.stringify({ volume: { id: "vol-1" } }), { status: 201 });
      if ((init?.method ?? "GET") === "GET")
        return readStatus === 200
          ? new Response(JSON.stringify({ droplet: { id: 77, status: "active", networks } }), { status: 200 })
          : new Response("{}", { status: readStatus });
      return new Response(JSON.stringify({ droplet: { id: 77 } }), { status: 202 });
    };
    net.probe = async (url) => { probed.push(url); return new Response("ok", { status: probeStatus }); };
  }, 30_000);
  afterAll(async () => {
    servers.stop();
    app.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  test("a deploy has no address yet; the check reads the public IPv4 back and the view carries the served URL", async () => {
    const r = await deploy("acme");
    expect(r).toMatchObject({ ok: true, value: { address: "", url: "" } });
    expect(await checkPinned(app, admin(), "acme")).toMatchObject({ ok: true, value: { address: "203.0.113.7", url: "http://203.0.113.7:8080/" } });
    const listed = pinnedForges(app, admin());
    expect(listed.ok && listed.value[0]!.url).toBe("http://203.0.113.7:8080/");
  });
  test("only a well-formed public IPv4 is taken", async () => {
    const f = async () => new Response(JSON.stringify({ droplet: { status: "new", networks } }), { status: 200 });
    networks = { v4: [{ type: "public", ip_address: "1.2.3.4; rm -rf /" }, { type: "private", ip_address: "10.0.0.2" }] };
    expect(await readDroplet(f, "t", "77")).toEqual({ status: "new", address: "" });
    networks = {};
    expect((await readDroplet(f, "t", "77")).address).toBe("");
    networks = { v4: [{ type: "public", ip_address: "203.0.113.7" }] };
    await expect(readDroplet(f, "t", "../x")).rejects.toThrow();
  });
  test("PORT is 1 to 65535, else the forge's default", () => {
    for (const [port, want] of [["8080", "8080"], ["65535", "65535"], ["0", "3000"], ["65536", "3000"], ["99999", "3000"], ["", "3000"]] as const)
      expect(portOf({ config: { PORT: port } })).toBe(want);
    expect(portOf({ config: {} })).toBe("3000");
  });
  test("the check recovers a failed forge that answers, leaves one that does not, and says so on the bus", async () => {
    const seen: any[] = [];
    const off = app.bus.subscribe((e) => { if (e.kind === "pinned.check") seen.push(e.payload); });
    setRemote(app.db, "acme", { state: "failed" });
    probeStatus = 503;
    expect(await checkPinned(app, admin(), "acme")).toMatchObject({ ok: true, value: { healthy: false, state: "failed" } });
    probeStatus = 200;
    expect(await checkPinned(app, admin(), "acme")).toMatchObject({ ok: true, value: { healthy: true, state: "running" } });
    expect(probed.at(-1)).toBe("http://203.0.113.7:8080/");
    off();
    expect(seen).toEqual([
      { name: "acme", address: "203.0.113.7", state: "failed", healthy: false },
      { name: "acme", address: "203.0.113.7", state: "running", healthy: true },
    ]);
    // A subscriber who reads the row after the event sees the recovered state.
    expect(getPinned(app.db, "acme")?.state).toBe("running");
  });
  test("the probe is audited like the other calls made for the account", () => {
    const rows = app.db.query("SELECT target FROM cloud_audit WHERE purpose = 'pinned:probe'").all() as { target: string }[];
    expect(rows.length).toBeGreaterThan(0);
    expect(rows[0]!.target).toBe("203.0.113.7:8080/");
  });
  test("a refused read is returned, not turned into 'no address'; a read-only account may still check", async () => {
    readStatus = 401;
    const refused = await checkPinned(app, admin(), "acme");
    expect(refused).toMatchObject({ ok: false });
    expect(String((refused as any).error)).toContain("401");
    readStatus = 200;
    allowWrite(app, admin(), "digitalocean", "main", false);
    expect(await checkPinned(app, admin(), "acme")).toMatchObject({ ok: true, value: { healthy: true } });
    allowWrite(app, admin(), "digitalocean", "main", true);
  });
  test("the check is the admin's, and needs a droplet", async () => {
    expect(await checkPinned(app, undefined, "acme")).toMatchObject({ ok: false });
    expect(await checkPinned(app, getUserByName(app.db, "bob")!, "acme")).toMatchObject({ ok: false });
    expect(await checkPinned(app, admin(), "nope")).toMatchObject({ ok: false, error: "No such pinned forge." });
    const fresh = await deploy("bare");
    expect(fresh.ok).toBe(true);
    setRemote(app.db, "bare", { remote: "" });
    expect(await checkPinned(app, admin(), "bare")).toMatchObject({ ok: false });
  });
  test("HTTP: admin 200, member 403 (as the sibling routes), unknown name 404, no droplet 422", async () => {
    const h = (t: string) => ({ authorization: `Bearer ${t}`, "content-type": "application/json" });
    const tok = createToken(app.db, admin().id, "admin", "admin").token;
    const bob = createToken(app.db, getUserByName(app.db, "bob")!.id, "admin", "admin").token;
    const post = (name: string, t?: string) =>
      fetch(`${servers.url}/api/v1/admin/pinned/${name}/check`, { method: "POST", headers: t ? h(t) : { "content-type": "application/json" }, body: "{}" });
    const ok = await post("acme", tok);
    expect(ok.status).toBe(200);
    expect(await ok.json()).toMatchObject({ healthy: true, url: "http://203.0.113.7:8080/" });
    expect((await post("acme", bob)).status).toBe(403);
    expect((await post("acme")).status).toBeGreaterThanOrEqual(401);
    expect((await post("nope", tok)).status).toBe(404);
    expect((await post("bare", tok)).status).toBe(422);
  });
  test("MCP: the check verb says the url; a non-admin-scope token is refused", async () => {
    const call = async (t: string, 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 ${t}` },
        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 };
    };
    const tok = createToken(app.db, admin().id, "admin", "admin").token;
    const done = await call(tok, { verb: "check", name: "acme" });
    expect(done.says).toBe("check acme: now " + "a".repeat(40) + ", running at http://203.0.113.7:8080/.");
    expect(done.forge).toMatchObject({ healthy: true });
    const ro = createToken(app.db, admin().id, "ro", "ro").token;
    expect((await call(ro, { verb: "check", name: "acme" })).text ?? "").not.toContain("running at");
  });
  test("terminal: c checks the forge under the cursor and redraws; a member does nothing; the row shows the url", async () => {
    const mk = (user: ReturnType<typeof admin>) => new Session(app, { sshUsername: "t", remoteAddress: "127.0.0.1", user });
    let invalidated = 0;
    const ctx = { push() {}, invalidate: () => invalidated++ } 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 before = probed.length;
    expect(key(pinnedScreen(mk(getUserByName(app.db, "bob")!), ctx), "c")).toBeFalsy();
    expect(probed.length).toBe(before);
    const abort = new AbortController();
    const screen = pinnedScreen(mk(admin()), ctx);
    await screen.load!(abort.signal);
    const n = invalidated;
    expect(key(screen, "c")).toBe(true);
    await new Promise((r) => setTimeout(r, 150));
    expect(probed.length).toBe(before + 1);
    expect(invalidated).toBeGreaterThan(n);
    const list = pinnedForges(app, admin());
    expect(list.ok && list.value[0]!.url).toBe("http://203.0.113.7:8080/");
    abort.abort();
  });
});
		@@ -6,7 +6,7 @@ A pinned forge is a forge the owner put on their own cloud. It has no crew a
6	6
7	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	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`).
	9	- MCP: `pinned_forge` with `verb` `list`, `deploy`, `update`, `rollback` (and `check`) — the same words and the same checks (`src/actions/pinned.ts`).
10	10
11	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	12
		@@ -36,6 +36,10 @@ The cloud facts for Cloudflare and Vercel are from memory of their documentation
36	36
37	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	38
	39	## Address and health check (#8745)
	40
	41	`check` (`POST /api/v1/admin/pinned/:name/check`, MCP `pinned_forge` verb `check`, terminal `c`) reads the droplet from DigitalOcean (`GET /droplets/{id}`, read-only, no write permission needed), records its public IPv4 (`pinned_forge.address`, validated as IPv4), and probes `http://<address>:<PORT or 3000>/`. Every view carries `url` (empty until an address is read). A forge that answers is set `running`, so a `failed` one recovers by itself once its droplet is up; one that does not answer keeps its state and the result says `healthy: false`. Deploy and Update do not read the address: a new droplet has none for a while, so ask with `check`.
	42
39	43	## Failing half-way
40	44
41	45	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.
		@@ -44,5 +48,6 @@ Each id is recorded the moment it exists. A first deploy that fails before a dro
44	48
45	49	- No canary on a real account: #8746.
46	50	- 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.
	51	- No TLS or domain: the URL is `http://<droplet IPv4>:<PORT or 3000>/`.
	52	- No page in the web studio shows the pinned forges yet; the API, MCP and terminal do.
48	53	- AWS and Azure drivers.
		@@ -11,30 +11,32 @@
11	11
12	12	import type { App } from "../app.ts";
13	13	import { gatedFetch } from "../cloud/gate.ts";
14		import { provision, replace } from "../cloud/droplet.ts";
	14	import { provision, readDroplet, replace } from "../cloud/droplet.ts";
15	15	import type { Fetch } from "../cloud/providers.ts";
16	16	import { target as targetOf } from "../cloud/targets.ts";
17	17	import { getCloudAccount, secretNameOf } from "../core/cloud_account.ts";
18	18	import {
19	19	APP, NAME, changesOf, checkConfig, getPinned, insertPinned, listPinned, previousOf,
20		dropPinned, recordChange, setRemote, validSource, validVersion, type Change, type Pinned,
	20	dropPinned, recordChange, setRemote, urlOf, validSource, validVersion, type Change, type Pinned,
21	21	} from "../core/pinned.ts";
22	22	import { resolveSecrets } from "../core/secret_store.ts";
23	23	import type { User } from "../core/users.ts";
24	24	import { err, ok, type Result } from "../kernel/result.ts";
25	25
26	26	/** Swapped in tests; the real forge always uses `fetch`. */
27		export const net: { fetch: Fetch } = { fetch: (u, i) => fetch(u, i) };
	27	export const net: { fetch: Fetch; probe: Fetch } = { fetch: (u, i) => fetch(u, i), probe: (u, i) => fetch(u, i) };
28	28
29	29	const admin = (a: User \| undefined): Result<User, string> => (a?.isAdmin ? ok(a) : err("not_found"));
30	30
31	31	export interface PinnedView extends Pinned {
	32	/** Where it is served, once the droplet's address is read; empty before. */
	33	readonly url: string;
32	34	readonly crew: false;
33	35	readonly autoRelease: false;
34	36	readonly changes: Change[];
35	37	}
36	38
37		const view = (app: App, p: Pinned): PinnedView => ({ ...p, crew: false, autoRelease: false, changes: changesOf(app.db, p.id) });
	39	const view = (app: App, p: Pinned): PinnedView => ({ ...p, url: urlOf(p), crew: false, autoRelease: false, changes: changesOf(app.db, p.id) });
38	40
39	41	export function pinnedForges(app: App, actor: User \| undefined): Result<PinnedView[], string> {
40	42	const who = admin(actor);
		@@ -42,10 +44,10 @@ export function pinnedForges(app: App, actor: User \| undefined): Result<PinnedVi
42	44	}
43	45
44	46	/** 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>> {
	47	async function withCloud<T>(app: App, who: User, p: Pinned, purpose: string, go: (f: Fetch, token: string) => Promise<T>, writes = true): Promise<Result<T, string>> {
46	48	const account = getCloudAccount(app.db, p.target, p.account);
47	49	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.");
	50	if (writes && !account.writeAllowed) return err("That cloud account is read-only; allow writes on it first.");
49	51	const secret = secretNameOf(account.provider, account.name);
50	52	const token = resolveSecrets(app.db, app.config.dataDir, app.bus, [secret], { actor: who.id, run: `pinned:${purpose}` })[secret];
51	53	if (token === undefined) return err("No such credential.");
		@@ -56,6 +58,16 @@ async function withCloud<T>(app: App, who: User, p: Pinned, purpose: string, go:
56	58	}
57	59	}
58	60
	61	/** Read the droplet back and record its public IPv4 (empty while none is assigned). The cloud's refusal is returned, so "no address yet" and "the call was refused" differ. */
	62	async function readAddress(app: App, who: User, name: string): Promise<Result<string, string>> {
	63	const p = getPinned(app.db, name);
	64	if (!p \|\| p.remote === "") return ok("");
	65	const seen = await withCloud(app, who, p, "address", (f, token) => readDroplet(f, token, p.remote), false);
	66	if (!seen.ok) return seen;
	67	if (seen.value.address !== "") setRemote(app.db, name, { address: seen.value.address });
	68	return ok(seen.value.address);
	69	}
	70
59	71	export async function deployPinned(
60	72	app: App,
61	73	actor: User \| undefined,
		@@ -116,12 +128,12 @@ async function change(
116	128	app.bus.append({ kind: kind === "update" ? "pinned.update" : "pinned.rollback", actorId: who.value.id, payload: { name, from: c.fromVersion, to: c.toVersion } });
117	129	}
118	130	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: "" }) }));
	131	const done = await withCloud(app, who.value, after, kind, (f, token) => replace(f, token, after, { onDeleted: () => setRemote(app.db, name, { remote: "", address: "" }) }));
120	132	if (!done.ok) {
121	133	setRemote(app.db, name, { state: "failed" });
122	134	return done;
123	135	}
124		setRemote(app.db, name, { ...done.value, state: "running" });
	136	setRemote(app.db, name, { ...done.value, address: "", state: "running" });
125	137	return ok(view(app, getPinned(app.db, name)!));
126	138	}
127	139
		@@ -145,3 +157,35 @@ export const rollbackPinned = (app: App, actor: User \| undefined, name: string):
145	157	const prev = previousOf(app.db, p);
146	158	return prev ? ok(prev) : err("There is no previous version: this forge has only ever run one.");
147	159	});
	160
	161	/**
	162	* The health check: read the droplet's address back, ask the forge there for
	163	* its front page, and say what it answered. A forge that answers is `running`,
	164	* so one marked `failed` by a refused call recovers by itself once its droplet
	165	* is up; one that does not answer keeps its state, and `healthy` is false.
	166	*/
	167	export async function checkPinned(app: App, actor: User \| undefined, name: string): Promise<Result<PinnedView & { healthy: boolean }, string>> {
	168	const who = admin(actor);
	169	if (!who.ok) return who;
	170	const p = getPinned(app.db, name);
	171	if (!p) return err("No such pinned forge.");
	172	if (p.remote === "") return err("This forge has no droplet yet; deploy or update it first.");
	173	const read = await readAddress(app, who.value, name);
	174	if (!read.ok) return read;
	175	const now = getPinned(app.db, name)!;
	176	let healthy = false;
	177	if (now.address !== "") {
	178	// The probe is audited like every other call made for this account; the address is a validated public IPv4 and the port is 1-65535.
	179	const probe = gatedFetch(app.db, { provider: now.target, account: now.account }, "pinned:probe", net.probe);
	180	try {
	181	const res = await probe(urlOf(now), { signal: AbortSignal.timeout(5_000), redirect: "manual" });
	182	healthy = res.status >= 200 && res.status < 400;
	183	} catch {
	184	healthy = false;
	185	}
	186	}
	187	if (healthy && now.state !== "running") setRemote(app.db, name, { state: "running" });
	188	const after = getPinned(app.db, name)!;
	189	app.bus.append({ kind: "pinned.check", actorId: who.value.id, payload: { name, address: after.address, state: after.state, healthy } });
	190	return ok({ ...view(app, after), healthy });
	191	}
		@@ -6,7 +6,8 @@
6	6	* Authorization header over HTTPS, never on argv, and the boot script holds no
7	7	* secret at all: the new forge's first visitor claims it at /first-admin.
8	8	*
9		* Calls (DigitalOcean API v2): POST /volumes, POST /droplets, DELETE /droplets/{id}.
	9	* Calls (DigitalOcean API v2): POST /volumes, POST /droplets, DELETE /droplets/{id}, GET /droplets/{id}
	10	* (the public IPv4 the droplet was given, read back after it boots).
10	11	* The caller records each id the moment it exists (`onVolume`, `onDeleted`),
11	12	* so a failure half-way leaves a row a retry can finish, never an orphan.
12	13	*/
		@@ -121,3 +122,14 @@ export async function replace(f: Fetch, token: string, p: Pinned, hooks: { onDel
121	122	const d = await createDroplet(f, token, p, p.volume);
122	123	return { remote: String(d.droplet?.id ?? "") };
123	124	}
	125
	126	const IPV4 = /^(?:(?:25[0-5]\|2[0-4]\d\|1?\d?\d)\.){3}(?:25[0-5]\|2[0-4]\d\|1?\d?\d)$/;
	127
	128	/** Read the droplet back: its status and public IPv4 (empty while none is assigned). Only a well-formed address is returned. */
	129	export async function readDroplet(f: Fetch, token: string, remote: string): Promise<{ status: string; address: string }> {
	130	if (!/^\d+$/.test(remote)) throw new Error("this forge has no droplet to read");
	131	const d = (await call(f, token, "GET", `/droplets/${remote}`)).droplet;
	132	const v4: unknown[] = Array.isArray(d?.networks?.v4) ? d.networks.v4 : [];
	133	const pub = v4.find((n: any) => n?.type === "public" && typeof n.ip_address === "string" && IPV4.test(n.ip_address)) as { ip_address: string } \| undefined;
	134	return { status: String(d?.status ?? ""), address: pub?.ip_address ?? "" };
	135	}
		@@ -195,6 +195,7 @@ export { route as postApiV1AdminAccountsUsernameUnsuspend } from "./postApiV1Adm
195	195	export { route as postApiV1AdminAccountsUsernameVerify } from "./postApiV1AdminAccountsUsernameVerify.ts";
196	196	export { route as postApiV1AdminInvites } from "./postApiV1AdminInvites.ts";
197	197	export { route as postApiV1AdminPinned } from "./postApiV1AdminPinned.ts";
	198	export { route as postApiV1AdminPinnedNameCheck } from "./postApiV1AdminPinnedNameCheck.ts";
198	199	export { route as postApiV1AdminPinnedNameRollback } from "./postApiV1AdminPinnedNameRollback.ts";
199	200	export { route as postApiV1AdminPinnedNameUpdate } from "./postApiV1AdminPinnedNameUpdate.ts";
200	201	export { route as postApiV1AdminReleasesShaRollback } from "./postApiV1AdminReleasesShaRollback.ts";
		@@ -0,0 +1,12 @@
	1	import type { Route } from "../shared.ts";
	2
	3	export const route: Route = {
	4	method: "post",
	5	path: "/api/v1/admin/pinned/{name}/check",
	6	summary: "Read the droplet's public address back, probe the forge there, and say whether it answers; one that does is marked running",
	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	};
		@@ -0,0 +1,1 @@
	1	13d9c395c67ccf46eae79e8a3f5c0af8f1f1d7a163d02ca5af83e8408d3b7e60
		@@ -0,0 +1,5 @@
	1	// The public IPv4 a pinned forge's droplet was read back with (#8745), so the
	2	// forge can show the address it is served at. Additive; empty until it is read.
	3	export default `
	4	ALTER TABLE pinned_forge ADD COLUMN address TEXT NOT NULL DEFAULT '';
	5	`;
		@@ -20,6 +20,7 @@ export interface Pinned {
20	20	readonly config: Record<string, string>;
21	21	readonly remote: string;
22	22	readonly volume: string;
	23	readonly address: string;
23	24	readonly state: string;
24	25	readonly createdAt: string;
25	26	}
		@@ -71,13 +72,13 @@ export function checkConfig(raw: unknown): Result<Record<string, string>, string
71	72
72	73	interface Row {
73	74	id: string; name: string; target: string; account: string; app: string; source: string;
74		version: string; config: string; remote: string; volume: string; state: string; created_at: string;
	75	version: string; config: string; remote: string; volume: string; address: string; state: string; created_at: string;
75	76	}
76	77
77	78	const toPinned = (r: Row): Pinned => ({
78	79	id: r.id, name: r.name, target: r.target, account: r.account, app: r.app, source: r.source,
79	80	version: r.version, config: JSON.parse(r.config) as Record<string, string>,
80		remote: r.remote, volume: r.volume, state: r.state, createdAt: r.created_at,
	81	remote: r.remote, volume: r.volume, address: r.address, state: r.state, createdAt: r.created_at,
81	82	});
82	83
83	84	export const listPinned = (db: Database): Pinned[] =>
		@@ -154,12 +155,21 @@ export function previousOf(db: Database, forge: Pinned): { version: string; conf
154	155	}
155	156
156	157	/** Machine facts the target reports back; they never touch version or config. */
157		export function setRemote(db: Database, name: string, f: { remote?: string; volume?: string; state?: string }): void {
158		db.query("UPDATE pinned_forge SET remote = coalesce(?1, remote), volume = coalesce(?2, volume), state = coalesce(?3, state) WHERE name = ?4")
159		.run(f.remote ?? null, f.volume ?? null, f.state ?? null, name);
	158	export function setRemote(db: Database, name: string, f: { remote?: string; volume?: string; address?: string; state?: string }): void {
	159	db.query("UPDATE pinned_forge SET remote = coalesce(?1, remote), volume = coalesce(?2, volume), address = coalesce(?3, address), state = coalesce(?4, state) WHERE name = ?5")
	160	.run(f.remote ?? null, f.volume ?? null, f.address ?? null, f.state ?? null, name);
160	161	}
161	162
162	163	/** The row of a deploy that never reached a droplet, so its name can be tried again; its recorded change stays as history. */
163	164	export function dropPinned(db: Database, name: string): void {
164	165	db.query("DELETE FROM pinned_forge WHERE name = ?1 AND remote = '' AND state = 'failed'").run(name);
165	166	}
	167
	168	/** The port the forge listens on at its droplet: the config's PORT, else the forge's own default. */
	169	export const portOf = (p: Pick<Pinned, "config">): string => {
	170	const n = Number(p.config["PORT"]);
	171	return /^\d{1,5}$/.test(p.config["PORT"] ?? "") && n >= 1 && n <= 65535 ? String(n) : "3000";
	172	};
	173
	174	/** Where a pinned forge is served, once its droplet's address is known; empty before. */
	175	export const urlOf = (p: Pick<Pinned, "address" \| "config">): string => (p.address === "" ? "" : `http://${p.address}:${portOf(p)}/`);
		@@ -14,7 +14,7 @@ import { changeCapacity, listCapacity } from "../../actions/capacity.ts";
14	14	import { inviteLink, list as listInviteLinks, mint as mintInviteLink, revoke as revokeInviteLink } from "../../actions/invites.ts";
15	15	import { changeLimit, listLimits } from "../../actions/limits.ts";
16	16	import { setAccountCeilings, setAccountGrant } from "../../actions/model_grant.ts";
17		import { deployPinned, pinnedForges, rollbackPinned, updatePinned } from "../../actions/pinned.ts";
	17	import { checkPinned, deployPinned, pinnedForges, rollbackPinned, updatePinned } from "../../actions/pinned.ts";
18	18	import { TARGETS } from "../../cloud/targets.ts";
19	19	import { changeQuotas, readQuotas } from "../../actions/quotas.ts";
20	20	import { setRole } from "../../actions/roles.ts";
		@@ -72,6 +72,13 @@ export function adminRoutes(router: Router<Handler>): void {
72	72	return done.ok ? json(done.value) : pinnedFail(done.error);
73	73	});
74	74
	75	router.add("POST", "/api/v1/admin/pinned/:name/check", async (ctx) => {
	76	const denied = accountAdmin(ctx, "admin");
	77	if (denied) return denied;
	78	const done = await checkPinned(ctx.app, ctx.auth.user, ctx.params.name!);
	79	return done.ok ? json(done.value) : pinnedFail(done.error);
	80	});
	81
75	82	router.add("POST", "/api/v1/admin/pinned/:name/rollback", async (ctx) => {
76	83	const denied = accountAdmin(ctx, "admin");
77	84	if (denied) return denied;
		@@ -1,16 +1,16 @@
1		import { deployPinned, pinnedForges, rollbackPinned, updatePinned } from "../../../actions/pinned.ts";
	1	import { checkPinned, deployPinned, pinnedForges, rollbackPinned, updatePinned } from "../../../actions/pinned.ts";
2	2	import { TARGETS } from "../../../cloud/targets.ts";
3	3	import { scopeAllows } from "../../../core/tokens.ts";
4	4	import { good, bad, type Tool, str } from "../shared.ts";
5	5
6	6	export const tool: Tool = {
7	7	name: "pinned_forge",
8		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",
9		description: "Pinned forges on your cloud: list, deploy, update, rollback (admin).",
	8	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; `check` reads the droplet's address back and probes it (`url`, `healthy`). A forge admin with an admin-scope token",
	9	description: "Pinned forges on your cloud: list, deploy, update, rollback, check (admin).",
10	10	inputSchema: {
11	11	type: "object",
12	12	properties: {
13		verb: { type: "string", enum: ["list", "deploy", "update", "rollback"] },
	13	verb: { type: "string", enum: ["list", "deploy", "update", "rollback", "check"] },
14	14	name: { type: "string", maxLength: 40 },
15	15	target: { type: "string", enum: TARGETS.map((t) => t.id) },
16	16	account: { type: "string", maxLength: 32 },
		@@ -46,9 +46,11 @@ export const tool: Tool = {
46	46	})
47	47	: verb === "rollback"
48	48	? await rollbackPinned(ctx.app, user, name)
49		: undefined;
50		if (done === undefined) return bad("bad_verb", "verb is list, deploy, update or rollback");
	49	: verb === "check"
	50	? await checkPinned(ctx.app, user, name)
	51	: undefined;
	52	if (done === undefined) return bad("bad_verb", "verb is list, deploy, update, rollback or check");
51	53	if (!done.ok) return bad("refused", done.error);
52		return good({ says: `${verb} ${name}: now ${done.value.version}, ${done.value.state}.`, forge: done.value });
	54	return good({ says: `${verb} ${name}: now ${done.value.version}, ${done.value.state}${done.value.url ? ` at ${done.value.url}` : ""}.`, forge: done.value });
53	55	},
54	56	};