@wtfalch/foundry 0.61.0 → 0.63.0

package/dist/plan/stage-signin.js

@@ -0,0 +1,133 @@
+import { createHash } from 'node:crypto';
+import { bgKey } from './blue-green.js';
+/** Tries the broker write this many times (CLAUDE.md, Platform steps, rule 1). */
+export const STAGE_SIGNIN_DELIVERY_TRIES = 3;
+/** The guard value for a subject that does not sign in. */
+export const STAGE_SIGNIN_NONE = 'none';
+/** Fixed text and ids only: safe to log, record and return. */
+export class StageSignInError extends Error {
+    name = 'StageSignInError';
+}
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+/**
+ * Makes stage's client, mints its app key once and writes its broker entry. Order: the client first (its ids
+ * recorded and persisted at once, a lost answer is adopted by name), then the key (held, its ref recorded under
+ * {@link bgKey.stageSignInKey} and persisted before anything is delivered), then the broker entry (retried).
+ * A run that failed halfway finds both and does the rest; the key is never minted twice. When the ref is
+ * recorded but the held store no longer has the key, this stops: it never mints another.
+ */
+export async function ensureStageSignIn(input) {
+    const { id, port } = input;
+    const at = `stage sign-in for ${id}`;
+    let appId = input.recorded()[bgKey.stageClient(id)];
+    let clientId = input.recorded()[bgKey.stageClientId(id)];
+    if (!appId || !clientId) {
+        const found = await port.findClient(port.spec.clientName);
+        if (found) {
+            if (!found.clientId) {
+                throw new StageSignInError(`${at}: client ${found.appId} exists but its id cannot be read`);
+            }
+            appId = found.appId;
+            clientId = found.clientId;
+        }
+        else {
+            const created = await port.createClient(port.spec);
+            appId = created.appId;
+            clientId = created.clientId;
+        }
+        input.record(bgKey.stageClient(id), appId);
+        input.record(bgKey.stageClientId(id), clientId);
+        await input.persist();
+    }
+    // One mint: the key goes to the held store, its ref is recorded and persisted, and only then is it used.
+    let appKey = await port.held.resolve();
+    if (appKey) {
+        input.secret(appKey);
+    }
+    else {
+        if (input.recorded()[bgKey.stageSignInKey(id)]) {
+            throw new StageSignInError(`${at}: key ${port.held.ref} was minted but is no longer held; restore the held value`);
+        }
+        appKey = input.generate();
+        input.secret(appKey);
+        await port.held.put(appKey);
+        input.record(bgKey.stageSignInKey(id), port.held.ref);
+        await input.persist();
+    }
+    const entry = {
+        name: port.spec.brokerName,
+        organizationId: port.spec.organizationId,
+        clientId,
+        origins: port.spec.origins,
+        from: port.spec.from,
+        registration: port.spec.registration,
+        ...(port.spec.emailLink === undefined ? {} : { emailLink: port.spec.emailLink }),
+    };
+    const sleep = input.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    for (let attempt = 1;; attempt++) {
+        try {
+            await port.writeBrokerEntry(entry, appKey);
+            break;
+        }
+        catch {
+            // The cause can echo the key; the ref is all a reader needs.
+            if (attempt >= STAGE_SIGNIN_DELIVERY_TRIES) {
+                throw new StageSignInError(`${at}: delivering key ${port.held.ref} to the broker entry ${port.spec.brokerName} failed after ${STAGE_SIGNIN_DELIVERY_TRIES} tries`);
+            }
+            await sleep(1000 * attempt);
+        }
+    }
+    input.record(bgKey.stageBroker(id), JSON.stringify({ name: entry.name, organizationId: entry.organizationId }));
+    await input.persist();
+    return {
+        env: [
+            { key: 'AUTH_CLIENT_ID', value: clientId },
+            { key: 'AUTH_APP_KEY', value: appKey },
+        ],
+        guard: stageSignInGuard({ appId, clientId, brokerName: entry.name, origins: entry.origins }),
+    };
+}
+/** `ok:<sha256 of the ids>`: the client, the app, the broker entry's name and its origins. No value goes in. */
+export function stageSignInGuard(input) {
+    return `ok:${sha256(JSON.stringify([input.appId, input.clientId, input.brokerName, [...input.origins].sort()]))}`;
+}
+/** Whether the recorded `bg.<id>.stagesignin` lets the copy go on. */
+export const stageSignInReady = (value) => value === STAGE_SIGNIN_NONE || value?.startsWith('ok:') === true;
+/**
+ * Makes the public client of a static SPA's stage (Agora): found by name or created, its ids recorded and
+ * persisted at once. There is no key and no broker entry, so nothing secret exists. The guard hashes the app id,
+ * the client id, the client name and the origins.
+ */
+export async function ensureStagePublicClient(input) {
+    const { id, port } = input;
+    const at = `stage sign-in for ${id}`;
+    let appId = input.recorded()[bgKey.stageClient(id)];
+    let clientId = input.recorded()[bgKey.stageClientId(id)];
+    if (!appId || !clientId) {
+        const found = await port.findClient(port.spec.clientName);
+        if (found) {
+            if (!found.clientId) {
+                throw new StageSignInError(`${at}: client ${found.appId} exists but its id cannot be read`);
+            }
+            appId = found.appId;
+            clientId = found.clientId;
+        }
+        else {
+            const created = await port.createClient(port.spec);
+            appId = created.appId;
+            clientId = created.clientId;
+        }
+        input.record(bgKey.stageClient(id), appId);
+        input.record(bgKey.stageClientId(id), clientId);
+        await input.persist();
+    }
+    return {
+        clientId,
+        guard: stageSignInGuard({
+            appId,
+            clientId,
+            brokerName: port.spec.clientName,
+            origins: port.spec.origins,
+        }),
+    };
+}

package/dist/plan/stage-sink.d.ts

@@ -26,6 +26,8 @@ type SinkOrg = Pick<DeclaredOrg, 'slug'>;
 export declare const stageSinkAppName: (org: SinkOrg) => string;
 /** The sink's HTTP address on the company's Docker network. */
 export declare const stageSinkInternalUrl: (org: SinkOrg) => string;
+/** The sender stage mails carry. Apps send only when `MAIL_FROM` is set; the address cannot receive mail. */
+export declare const STAGE_MAIL_FROM = "Stage <noreply@stage.invalid>";
 /**
  * The only mail env stage holds. `@wtfalch/mailer` 0.6.0 posts every message to `MAIL_SINK_URL` when it is set,
  * so stage holds no mail token and no Lettermint setting.

package/dist/plan/stage-sink.js

@@ -24,10 +24,15 @@ export const STAGE_SINK_VERSION = 1;
 export const stageSinkAppName = (org) => `${org.slug}-stage-sink`;
 /** The sink's HTTP address on the company's Docker network. */
 export const stageSinkInternalUrl = (org) => `http://${stageSinkAppName(org)}:${STAGE_SINK_HTTP_PORT}`;
+/** The sender stage mails carry. Apps send only when `MAIL_FROM` is set; the address cannot receive mail. */
+export const STAGE_MAIL_FROM = 'Stage <noreply@stage.invalid>';
 /**
  * The only mail env stage holds. `@wtfalch/mailer` 0.6.0 posts every message to `MAIL_SINK_URL` when it is set,
  * so stage holds no mail token and no Lettermint setting.
  */
 export function stageMailEnv(org) {
-    return [{ key: 'MAIL_SINK_URL', value: stageSinkInternalUrl(org) }];
+    return [
+        { key: 'MAIL_SINK_URL', value: stageSinkInternalUrl(org) },
+        { key: 'MAIL_FROM', value: STAGE_MAIL_FROM },
+    ];
 }

package/dist/platform.d.ts

@@ -72,7 +72,7 @@ export declare function uptimeArtifactUrl(tag: string): string;
  * holds the Cloudflare token `<username>.<org domain>` claims use, so no
  * hosting entry ever holds that credential itself.
  */
-export type PlatformServiceKey = 'auth' | 'mail' | 'sfu' | 'files' | 'ai' | 'jobs' | 'integrations' | 'archon' | 'edge' | 'hc' | 'coolify';
+export type PlatformServiceKey = 'auth' | 'mail' | 'sfu' | 'files' | 'ai' | 'jobs' | 'integrations' | 'archon' | 'edge' | 'hc' | 'registry' | 'coolify';
 export declare const PLATFORM_SERVICE_KEYS: readonly PlatformServiceKey[];
 /**
  * The one shared platform every org's services run on -- decided in #165 as
@@ -123,6 +123,12 @@ export interface DeclaredPlatform {
      * `plan/platform-diff.ts`'s `planHeartbeats`.
      */
     hc: PlatformService;
+    /**
+     * The platform's image registry (`registry:3`, htpasswd sign-in): the images the build workflow
+     * pushes and the company servers pull. `gitRef` is the image tag, pinned by digest in
+     * `versions.json` like `hc`'s. See `plan/platform-registry.ts`.
+     */
+    registry: PlatformService;
     /**
      * The Coolify panel. Its address is declared so the platform's hostnames
      * include it; foundry never deploys it, so `enabled` stays false and

package/dist/platform.js

@@ -15,6 +15,7 @@ export const PLATFORM_SERVICE_KEYS = [
     'archon',
     'edge',
     'hc',
+    'registry',
     'coolify',
 ];
 /** The only values {@link DeclaredPlatform.heartbeatsProvider} may hold. */

package/dist/release/decide.d.ts

@@ -51,6 +51,8 @@ export interface Recorded {
     /** Set while window.kind is step, inconclusive, window or cap. */
     release: ActiveRelease | null;
     held: string[];
+    /** Stage holds the sink env. Absent reads as no. */
+    stageSink?: boolean;
 }
 export interface ColorCounts {
     requests: number;
@@ -85,6 +87,14 @@ export type ReleaseEffect = {
  | {
     kind: 'deploy_stage';
     ref: string;
+}
+/**
+ * Run the stage copy (or undo it) for the first open request of that kind. The runner does not execute it: it
+ * hands it to its caller, who runs it after this run's other effects, writes and weights are done.
+ */
+ | {
+    kind: 'stage_copy';
+    mode: 'copy' | 'undo';
 };
 export interface Decision {
     recorded: Recorded;
@@ -94,6 +104,8 @@ export interface Decision {
     blocked: string[];
     /** Actions that changed nothing, with a fixed reason. */
     refused: string[];
+    /** The reason a `copy_prod_to_stage` request was refused here, for `bg.<id>.stagecopy`; else null. */
+    stageRefusal: string | null;
 }
 export declare function normalizeSteps(steps: readonly number[] | undefined): number[];
 /** The time a health read should cover: from the step or window start to now. */

package/dist/release/decide.js

@@ -81,6 +81,7 @@ function applyActions(r, actions, now, out, kind) {
     let ended = false;
     let approved = false;
     let opened = false;
+    const stageRequests = [];
     for (const a of actions) {
         if (a.kind === 'deploy_stage') {
             if (typeof a.ref === 'string' && STAGE_REF_PATTERN.test(a.ref))
@@ -135,6 +136,9 @@ function applyActions(r, actions, now, out, kind) {
                 promoted = true;
             }
         }
+        else if (a.kind === 'copy_prod_to_stage' || a.kind === 'undo_stage_copy') {
+            stageRequests.push(a.kind);
+        }
         else if (a.kind === 'rollback') {
             if (!cur.release)
                 out.refused.push('rollback refused: no release is running');
@@ -157,6 +161,26 @@ function applyActions(r, actions, now, out, kind) {
             }
         }
     }
+    // The stage requests are judged last, against the release the other actions of this run left.
+    for (const kind of stageRequests) {
+        const copy = kind === 'copy_prod_to_stage';
+        const name = copy ? 'copy' : 'undo';
+        if (out.effects.some((e) => e.kind === 'stage_copy')) {
+            out.refused.push(`${name} refused: one stage copy request runs at a time`);
+        }
+        else if (cur.release) {
+            // A copy takes up to ~45 minutes; a release that is stepping needs the runner free to roll back.
+            out.refused.push(`${name} refused: a release is running`);
+            out.stageRefusal = 'release';
+        }
+        else if (copy && !cur.stageSink) {
+            out.refused.push('copy refused: stage sink is not applied');
+            out.stageRefusal = 'sink';
+        }
+        else {
+            out.effects.push({ kind: 'stage_copy', mode: copy ? 'copy' : 'undo' });
+        }
+    }
     return { recorded: cur, promoted, ended, approved, opened };
 }
 /**
@@ -168,7 +192,11 @@ export function decide(input) {
     const { now, observation } = input;
     const steps = normalizeSteps(input.steps);
     const holdMs = (input.stepHoldMinutes ?? DEFAULT_STEP_HOLD_MINUTES) * MINUTE;
-    const out = { effects: [], refused: [] };
+    const out = {
+        effects: [],
+        refused: [],
+        stageRefusal: null,
+    };
     const advance = input.advance ?? DEFAULT_ADVANCE;
     const minRequests = input.minRequests ?? RELATIVE_MIN_REQUESTS;
     const errorMargin = input.errorMargin ?? ERROR_RATE_MARGIN;
@@ -285,7 +313,14 @@ export function decide(input) {
     }
     if (r.window.kind === 'cap')
         blocked.push('release window reached the cap without enough data: pass or roll back in Archon');
-    return { recorded: r, signal, effects: out.effects, blocked, refused: out.refused };
+    return {
+        recorded: r,
+        signal,
+        effects: out.effects,
+        blocked,
+        refused: out.refused,
+        stageRefusal: out.stageRefusal,
+    };
 }
 function stepTo(r, rel, percent, now) {
     const at = now.toISOString();

package/dist/release/migration-compatibility.d.ts

@@ -0,0 +1,66 @@
+import { type WorkerAppConfig } from '../worker-app-config.js';
+/**
+ * Whether a release's database changes may go to idle (foundry#934, estate DECISIONS.md,
+ * 2026-10-21 "Releases and versions"). Idle shares the live database with whatever release is
+ * live, so a release may only add -- never drop, narrow, rename or retype something the live
+ * release still reads or writes, and never delete a Durable Object class the live release still
+ * uses. A removal needs two releases: one that stops using the object, a later one -- once that
+ * first release is no longer on live, idle or draining anywhere -- that removes it.
+ *
+ * Pure: no database connection, no network call, no data read. The caller supplies everything it
+ * already has: what the previous live release applied (`liveMigrationIds`, `liveDoTag`), what
+ * release tags are deployed anywhere right now (`deployedReleases`), and which removals this
+ * release declares as the drained second step of an earlier one (`declaredRemovals`). There is no
+ * override beyond that declaration: a destructive step with no declaration, or whose declared
+ * release has not drained, is refused every time.
+ *
+ * A SQL statement declares its own removal with a `-- removal-since: <release>` comment directly
+ * above it (the same convention `@wtfalch/db`'s migration safety check uses for
+ * `-- destructive: <reason>`); a Durable Object class removal is declared in `declaredRemovals`,
+ * since `deleted_classes` carries no comment of its own.
+ *
+ * The SQL classifier is pattern-based, not a real SQL parser: it is a safety rail against an
+ * accidental incompatible release, not a boundary against someone deliberately hiding a drop
+ * inside a string. A statement it cannot classify is refused rather than guessed as safe.
+ */
+/** A Durable Object class removal this release declares as the drained second step of an earlier one. */
+export interface DeclaredClassRemoval {
+    /** The class name a `deleted_classes` step of this release removes. */
+    className: string;
+    /** The earlier release that stopped using the class. Must have fully drained before this passes. */
+    sinceRelease: string;
+}
+export interface MigrationCompatibilityInput {
+    /** This release's own `migrations.json` (SQL), or `null` for a release with none. */
+    migrationsJson: string | null;
+    /** The SQL migration ids the previous live release already applied, in order. Default: none. */
+    liveMigrationIds?: readonly string[];
+    /** This release's full, declared Durable Object migrations, in order. Default: none. */
+    doMigrations?: WorkerAppConfig['durableObjects']['migrations'];
+    /** The Durable Object migration tag the previous live release holds, if any. */
+    liveDoTag?: string;
+    /** Durable Object class removals this release declares. Default: none. */
+    declaredRemovals?: readonly DeclaredClassRemoval[];
+    /** Release tags that are, right now, on live, idle or draining anywhere for this app. Default: none. */
+    deployedReleases?: readonly string[];
+}
+export interface MigrationCompatibilityProblem {
+    /** The SQL migration id or Durable Object migration tag the statement is in. */
+    migration: string;
+    /** The statement or step that is refused, trimmed to one line. */
+    statement: string;
+    /** Why it is refused, and what to do about it, in plain words. */
+    reason: string;
+}
+export type MigrationCompatibilityResult = {
+    ok: true;
+} | {
+    ok: false;
+    problems: MigrationCompatibilityProblem[];
+};
+/**
+ * Whether a release's migrations (SQL and Durable Object) may go to idle, given what the
+ * previous live release already applied and which releases are deployed anywhere right now. See
+ * the module docstring for the rule and the removal convention.
+ */
+export declare function checkMigrationCompatibility(input: MigrationCompatibilityInput): MigrationCompatibilityResult;