@wtfalch/foundry 0.7.1 → 0.9.0

package/dist/plan.d.ts

@@ -53,4 +53,47 @@ export interface Plan {
     orgId: OrgId;
     steps: PlanStep[];
     unmanaged: UnmanagedItem[];
+    /**
+     * #251: see {@link VersionChangeItem}. Optional so a `Plan` built before
+     * this field existed, or a test fixture that predates it, still satisfies
+     * this type with none.
+     */
+    versionChanges?: VersionChangeItem[];
+}
+/**
+ * The action kind a {@link VersionChangeItem} carries -- a distinct, typed
+ * value so Archon can key off it to render and later gate these lines
+ * (wtfalch/archon#133), and so it is never mistaken for a `StepAction.kind`
+ * (`plan/diff.ts`) any `StepExecutor` dispatches on.
+ *
+ * #251 round 3: an earlier attempt planned these as ordinary `PlanStep`s in
+ * `Plan.steps`. That made a plan holding only version-change lines for
+ * zitadel/synapse/mas (whose own step never re-applies a running app's
+ * image tag -- see {@link VersionChangeItem}) never read as empty, which is
+ * the condition `bootstrap/drive.ts` loops on, and `apply` tried to run a
+ * step for those services that does nothing. Version-change lines are
+ * carried on their own `Plan.versionChanges` field instead, never on
+ * `steps`, so they are display-only everywhere a `Plan` is read.
+ */
+export declare const VERSION_CHANGE_KIND = "version-change";
+/**
+ * One informational line reporting a service whose version has drifted --
+ * either from what the next apply would actually put live (mail, archon,
+ * ai, files, integrations: each already redeploys when its own recorded
+ * applied ref differs from the declared one), or, for a service whose own
+ * step never patches a running app's image tag once created (zitadel,
+ * synapse, mas), from what is actually live. #251: the data to show this
+ * already existed per-service with no line anywhere saying a foundry
+ * release bumping a pinned version, or an operator changing a declared
+ * `gitRef`, had changed what the next apply would do -- or, for the second
+ * group, that it would do nothing at all.
+ *
+ * Never a {@link PlanStep}: it creates or changes nothing live, and is never
+ * passed to a `StepExecutor`.
+ */
+export interface VersionChangeItem {
+    kind: typeof VERSION_CHANGE_KIND;
+    /** The service this line is about, e.g. 'mail', 'archon', 'zitadel'. */
+    service: string;
+    description: string;
 }

package/dist/plan.js

@@ -1 +1,16 @@
-export {};
+/**
+ * The action kind a {@link VersionChangeItem} carries -- a distinct, typed
+ * value so Archon can key off it to render and later gate these lines
+ * (wtfalch/archon#133), and so it is never mistaken for a `StepAction.kind`
+ * (`plan/diff.ts`) any `StepExecutor` dispatches on.
+ *
+ * #251 round 3: an earlier attempt planned these as ordinary `PlanStep`s in
+ * `Plan.steps`. That made a plan holding only version-change lines for
+ * zitadel/synapse/mas (whose own step never re-applies a running app's
+ * image tag -- see {@link VersionChangeItem}) never read as empty, which is
+ * the condition `bootstrap/drive.ts` loops on, and `apply` tried to run a
+ * step for those services that does nothing. Version-change lines are
+ * carried on their own `Plan.versionChanges` field instead, never on
+ * `steps`, so they are display-only everywhere a `Plan` is read.
+ */
+export const VERSION_CHANGE_KIND = 'version-change';

package/dist/platform.d.ts

@@ -4,7 +4,7 @@ import type { OrgId } from './org.js';
  * {@link DeclaredPlatform}. `enabled` turns the service's own provisioning
  * on; `hostname` is where it is served (default `<service>.<apex>`,
  * {@link defaultPlatformHostname}); `gitRef` is the release it runs, the
- * same "declared, not discovered" shape `HostingConfig.gitBranch` uses for
+ * same "declared, not discovered" shape `HostingEntry.branch` uses for
  * an org's own app (`org.ts`).
  */
 export interface PlatformService {

package/dist/store/audit.d.ts

@@ -21,23 +21,19 @@ import type { FoundryStoreDb } from './postgres.js';
  * backfill can still be written later, where discarding the old rows
  * outright could not be undone.
  *
- * `checkRuntimeRole` defaults to `false` here, the opposite of
- * `createLedger`'s own default (#232, needs a human call -- flagged
- * `ai:needs-human`, not decided here): that check requires the connection
- * to be a real, restricted `<database>_rt` role, the one 0001's migration
- * revokes UPDATE/DELETE/TRUNCATE from by name
- * (`current_database() || '_rt'`). foundry has no such role for its own
- * database -- `FOUNDRY_DATABASE_URL` is one connection, no owner/runtime
- * split the way archon's, manage's or lokessmie's own `DATABASE_URL_OWNER`/
- * `DATABASE_URL` pair is (see #239, the same split for a *hosted* app's
- * database -- this is foundry's *own*). Leaving the default on would make
- * every real call throw `UnsafeRuntimeRoleError`, since the revoke in
- * 0001_audit.sql never ran against whatever role `FOUNDRY_DATABASE_URL`
- * actually is; the append-only guard and the chain still hold at the
- * database level regardless (0001's triggers, 0004's hashing), only the
- * extra fail-closed check on the *connection* is off. Options, not a second
- * positional argument (`CLAUDE.md` rule 7): a caller -- today only a test
- * fixture -- can pass `true` once foundry's own database gets that split.
+ * `checkRuntimeRole` defaults to `true`, `createLedger`'s own default. The
+ * connection must be a restricted role: not a superuser, no BYPASSRLS, and no
+ * UPDATE, DELETE or TRUNCATE on `audit_events`. A call through the owner
+ * connection throws `UnsafeRuntimeRoleError`. The check reads attributes of
+ * the connected role, not its name.
+ *
+ * The host provides that role. After it migrates with the owner URL, it calls
+ * `ensureRuntimeRole` from `@wtfalch/db/runtime-role` with
+ * `appendOnly: ['audit_events']` and the four audit functions in `grants`
+ * (README, "Foundry's own Postgres"), then connects the server as the runtime
+ * role. A test fixture without that split (PGlite's one user is a superuser)
+ * passes `checkRuntimeRole: false`. Options, not a second positional argument
+ * (`CLAUDE.md` rule 7).
  */
 export declare function createPostgresAuditLog(db: FoundryStoreDb, options?: {
     checkRuntimeRole?: boolean;

package/dist/store/audit.js

@@ -61,29 +61,25 @@ function boundPlan(plan) {
  * backfill can still be written later, where discarding the old rows
  * outright could not be undone.
  *
- * `checkRuntimeRole` defaults to `false` here, the opposite of
- * `createLedger`'s own default (#232, needs a human call -- flagged
- * `ai:needs-human`, not decided here): that check requires the connection
- * to be a real, restricted `<database>_rt` role, the one 0001's migration
- * revokes UPDATE/DELETE/TRUNCATE from by name
- * (`current_database() || '_rt'`). foundry has no such role for its own
- * database -- `FOUNDRY_DATABASE_URL` is one connection, no owner/runtime
- * split the way archon's, manage's or lokessmie's own `DATABASE_URL_OWNER`/
- * `DATABASE_URL` pair is (see #239, the same split for a *hosted* app's
- * database -- this is foundry's *own*). Leaving the default on would make
- * every real call throw `UnsafeRuntimeRoleError`, since the revoke in
- * 0001_audit.sql never ran against whatever role `FOUNDRY_DATABASE_URL`
- * actually is; the append-only guard and the chain still hold at the
- * database level regardless (0001's triggers, 0004's hashing), only the
- * extra fail-closed check on the *connection* is off. Options, not a second
- * positional argument (`CLAUDE.md` rule 7): a caller -- today only a test
- * fixture -- can pass `true` once foundry's own database gets that split.
+ * `checkRuntimeRole` defaults to `true`, `createLedger`'s own default. The
+ * connection must be a restricted role: not a superuser, no BYPASSRLS, and no
+ * UPDATE, DELETE or TRUNCATE on `audit_events`. A call through the owner
+ * connection throws `UnsafeRuntimeRoleError`. The check reads attributes of
+ * the connected role, not its name.
+ *
+ * The host provides that role. After it migrates with the owner URL, it calls
+ * `ensureRuntimeRole` from `@wtfalch/db/runtime-role` with
+ * `appendOnly: ['audit_events']` and the four audit functions in `grants`
+ * (README, "Foundry's own Postgres"), then connects the server as the runtime
+ * role. A test fixture without that split (PGlite's one user is a superuser)
+ * passes `checkRuntimeRole: false`. Options, not a second positional argument
+ * (`CLAUDE.md` rule 7).
  */
 export function createPostgresAuditLog(db, options = {}) {
     const ledger = createLedger({
         vocabulary: FOUNDRY_LEDGER_VOCABULARY,
         hashChain: true,
-        checkRuntimeRole: options.checkRuntimeRole ?? false,
+        checkRuntimeRole: options.checkRuntimeRole,
     });
     const targetFor = (orgId, target) => ({
         type: target === 'platform' ? 'platform' : 'org',

package/dist/store/postgres.d.ts

@@ -7,6 +7,20 @@ import type { DeclaredOrgStore, PlatformStore, RequestedChangeStore } from '../s
  * connection itself.
  */
 export type FoundryStoreDb = PgDatabase<PgQueryResultHKT, any, any>;
+/**
+ * The Postgres unique-violation constraint name, however the driver hands the
+ * error back -- directly (PGlite in this package's own tests) or wrapped in
+ * drizzle-orm's own `DrizzleQueryError`, whose `cause` carries the raw driver
+ * error (postgres-js in a host) -- or `undefined` when this is not a unique
+ * violation. Checked by Postgres error code, never by message text, since
+ * message text is not a contract. Same code-check pattern as
+ * `../runner/runner.ts`'s own `isUniqueViolation` -- kept as a local copy
+ * here rather than shared, since neither module depends on the other; this
+ * one additionally reads the constraint name (`constraint` under node-postgres and PGlite, `constraint_name` under postgres-js) so `create`/`update` can tell a slug
+ * collision from a domain collision (#131) rather than reporting both the
+ * same way.
+ */
+export declare function uniqueViolationConstraint(error: unknown): string | undefined;
 /**
  * Thrown by `create` and `update` when the store refuses a write: an id
  * that already exists, an id that does not, a slug that fails

package/dist/store/postgres.js

@@ -19,17 +19,22 @@ const NON_NEGATIVE_INTEGER = /^(0|[1-9]\d*)$/;
  * message text is not a contract. Same code-check pattern as
  * `../runner/runner.ts`'s own `isUniqueViolation` -- kept as a local copy
  * here rather than shared, since neither module depends on the other; this
- * one additionally reads `constraint` so `create`/`update` can tell a slug
+ * one additionally reads the constraint name (`constraint` under node-postgres and PGlite, `constraint_name` under postgres-js) so `create`/`update` can tell a slug
  * collision from a domain collision (#131) rather than reporting both the
  * same way.
  */
-function uniqueViolationConstraint(error) {
-    const direct = error;
-    if (direct?.code === UNIQUE_VIOLATION)
-        return direct.constraint;
-    const cause = error?.cause;
-    if (cause?.code === UNIQUE_VIOLATION)
-        return cause.constraint;
+export function uniqueViolationConstraint(error) {
+    // Walk `cause`: drizzle-orm wraps the driver error, and how deep differs by version. Bounded so a cyclic `cause` ends.
+    let current = error;
+    for (let depth = 0; depth < 5 && current !== null && typeof current === 'object'; depth += 1) {
+        const e = current;
+        if (e.code === UNIQUE_VIOLATION) {
+            // node-postgres spells it `constraint`; postgres-js spells it `constraint_name`.
+            const name = e.constraint ?? e.constraint_name;
+            return typeof name === 'string' ? name : undefined;
+        }
+        current = e.cause;
+    }
     return undefined;
 }
 /**
@@ -74,13 +79,9 @@ function rowToOrg(row) {
         hosting: {
             enabled: row.hostingEnabled,
             usesDomain: row.hostingUsesDomain,
-            database: row.hostingDatabase,
             tunnel: row.hostingTunnel,
-            gitBranch: row.hostingGitBranch,
-            buildPack: row.hostingBuildPack,
             issuerApps: row.hostingIssuerApps,
-            accessEmails: row.hostingAccessEmails,
-            appEnv: row.hostingAppEnv,
+            entries: row.hostingEntries,
         },
         sso: { enabled: row.ssoEnabled },
         guests: { enabled: row.guestsEnabled },
@@ -117,13 +118,9 @@ function orgToRow(org) {
         siteUsesDomain: org.site.usesDomain,
         hostingEnabled: org.hosting.enabled,
         hostingUsesDomain: org.hosting.usesDomain,
-        hostingDatabase: org.hosting.database,
         hostingTunnel: org.hosting.tunnel,
-        hostingGitBranch: org.hosting.gitBranch,
-        hostingBuildPack: org.hosting.buildPack,
         hostingIssuerApps: org.hosting.issuerApps,
-        hostingAccessEmails: org.hosting.accessEmails,
-        hostingAppEnv: org.hosting.appEnv ?? {},
+        hostingEntries: org.hosting.entries,
         ssoEnabled: org.sso.enabled,
         guestsEnabled: org.guests.enabled,
         soloEnabled: org.solo.enabled,

package/dist/store/schema.d.ts

@@ -1,4 +1,4 @@
-import type { AppEnvSource, IssuerApp } from '../org.js';
+import type { AppEnvSource, HostingEntry, IssuerApp } from '../org.js';
 import type { Plan } from '../plan.js';
 import type { Checkpoint } from '../state.js';
 /**
@@ -463,6 +463,25 @@ export declare const declaredOrgs: import("drizzle-orm/pg-core").PgTableWithColu
         }, {}, {
             $type: Record<string, AppEnvSource>;
         }>;
+        hostingEntries: import("drizzle-orm/pg-core").PgColumn<{
+            name: "hosting_entries";
+            tableName: "foundry_declared_orgs";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: HostingEntry[];
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: HostingEntry[];
+        }>;
         ssoEnabled: import("drizzle-orm/pg-core").PgColumn<{
             name: "sso_enabled";
             tableName: "foundry_declared_orgs";

package/dist/store/schema.js

@@ -43,11 +43,17 @@ export const declaredOrgs = pgTable('foundry_declared_orgs', {
     hostingIssuerApps: jsonb('hosting_issuer_apps').notNull().default([]).$type(),
     hostingAccessEmails: jsonb('hosting_access_emails').notNull().default([]).$type(),
     // HostingConfig.appEnv (org.ts, #243). Maps the app's own env var names to
-    // values the plan already mints; empty by default.
+    // values the plan already mints; empty by default. Read only by migration
+    // 0029, which copies it into `hostingEntries`.
     hostingAppEnv: jsonb('hosting_app_env')
         .notNull()
         .default({})
         .$type(),
+    // HostingConfig.entries (org.ts): one entry per app. Replaces the flat
+    // hosting_database, hosting_git_branch, hosting_build_pack,
+    // hosting_access_emails and hosting_app_env columns, which stay for an older
+    // reader and are no longer written.
+    hostingEntries: jsonb('hosting_entries').notNull().default([]).$type(),
     ssoEnabled: boolean('sso_enabled').notNull().default(false),
     guestsEnabled: boolean('guests_enabled').notNull().default(false),
     soloEnabled: boolean('solo_enabled').notNull().default(false),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",
@@ -15,6 +15,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./migrations-dir": {
+      "types": "./dist/migrations-dir.d.ts",
+      "default": "./dist/migrations-dir.js"
+    },
     "./migrations/*.sql": "./dist/migrations/*.sql",
     "./package.json": "./package.json"
   },
@@ -30,7 +34,6 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "db:provision": "node scripts/foundry-db-provision.mjs",
-    "db:migrate": "node scripts/foundry-db-migrate.mjs",
     "calls-sfu:deploy": "node scripts/calls-sfu-deploy.mjs"
   },
   "peerDependencies": {
@@ -47,8 +50,8 @@
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.8",
     "@types/node": "^22",
+    "@wtfalch/db": "0.5.2",
     "drizzle-orm": "0.45.2",
-    "postgres": "3.4.9",
     "typescript": "^5.9.0",
     "vitest": "^4.1.6"
   }

package/versions.json

@@ -2,7 +2,7 @@
   "zitadel": "v4.17.3",
   "synapse": "v1.161.0",
   "mas": "1.24.0",
-  "livekit": "latest",
+  "livekit": "v1.13.7",
   "cloudflared": "2026.9.3",
   "stalwart": "v0.16.24"
 }

package/dist/migrate.d.ts

@@ -1,38 +0,0 @@
-/** This package's own migrations -- `../migrations` from `src/`, `./migrations` once built to `dist/` (`package.json`'s `build` script copies the `.sql` files there alongside `migrate.js`). */
-export declare const MIGRATIONS_DIR: string;
-/**
- * The one capability `migrate` needs from a driver: run SQL text (one
- * statement or several) and run a callback inside a transaction. Deliberately
- * not a drizzle `PgDatabase` or a concrete driver type -- drizzle's own
- * `.execute()` routes a multi-statement string through a single prepared
- * query on PGlite, which rejects it, so a migration file's raw text has to
- * reach the driver's own multi-statement path (`postgres`'s `.unsafe()`,
- * PGlite's `.exec()`) instead. Same "narrow port, no concrete client type"
- * shape `plan/executor.ts`'s `CoolifyPort` uses, for the same reason: a real
- * driver satisfies this structurally, with a few lines of adapter at the
- * call site (see `scripts/foundry-db-migrate.mjs` and `migrate.test.ts`).
- */
-export interface MigrateSql {
-    /** Run SQL text and discard any result -- the tracking table's own DDL, and each migration file's contents. */
-    exec(text: string): Promise<void>;
-    /**
-     * Run one literal SELECT and return its rows. Only ever called here with
-     * fixed text this module builds itself (the tracking table's name, and a
-     * migration filename already checked against `/^\d{4}_.+\.sql$/`), so
-     * there is no external input to inject.
-     */
-    query<T = Record<string, unknown>>(text: string): Promise<T[]>;
-    /** Run `fn` inside one transaction, handing it a `MigrateSql` scoped to it; rolled back if `fn` throws. */
-    transaction<T>(fn: (tx: MigrateSql) => Promise<T>): Promise<T>;
-}
-export interface MigrationResult {
-    /** Names of the migration files applied this run, in filename order -- empty when the database was already current. */
-    applied: string[];
-}
-/**
- * Applies every migration file in `dir` (default: this package's own
- * `../migrations`) not yet recorded in `foundry_schema_migrations`, in
- * filename order, one transaction per file. Safe to call repeatedly: a file
- * already recorded is never re-read, let alone re-run.
- */
-export declare function migrate(sql: MigrateSql, dir?: string): Promise<MigrationResult>;

package/dist/migrate.js

@@ -1,47 +0,0 @@
-import { readFileSync, readdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-// #R2 (map gap: foundry's own Postgres, two commands): a tracked, idempotent
-// migration runner. `./test/db.ts` and `./runner/test/db.ts` already read
-// and sort this same directory to build one concatenated blob for a fresh
-// PGlite -- fine for a test fixture that always starts empty, wrong for a
-// real host that must apply only what a `foundry_schema_migrations` table
-// does not yet list. `migrationFiles` below is that same discovery, reused
-// rather than re-implemented, kept per-file instead of concatenated.
-const here = dirname(fileURLToPath(import.meta.url));
-/** This package's own migrations -- `../migrations` from `src/`, `./migrations` once built to `dist/` (`package.json`'s `build` script copies the `.sql` files there alongside `migrate.js`). */
-export const MIGRATIONS_DIR = join(here, 'migrations');
-const TRACKING_TABLE = 'foundry_schema_migrations';
-function migrationFiles(dir) {
-    return readdirSync(dir)
-        .filter((f) => /^\d{4}_.+\.sql$/.test(f))
-        .sort()
-        .map((name) => ({ name, path: join(dir, name) }));
-}
-/**
- * Applies every migration file in `dir` (default: this package's own
- * `../migrations`) not yet recorded in `foundry_schema_migrations`, in
- * filename order, one transaction per file. Safe to call repeatedly: a file
- * already recorded is never re-read, let alone re-run.
- */
-export async function migrate(sql, dir = MIGRATIONS_DIR) {
-    await sql.exec(`create table if not exists ${TRACKING_TABLE} (name text primary key, applied_at timestamptz not null default now())`);
-    const appliedRows = await sql.query(`select name from ${TRACKING_TABLE}`);
-    const applied = new Set(appliedRows.map((row) => row.name));
-    const pending = migrationFiles(dir).filter((file) => !applied.has(file.name));
-    const done = [];
-    for (const file of pending) {
-        const text = readFileSync(file.path, 'utf8');
-        await sql.transaction(async (tx) => {
-            await tx.exec(text);
-            // `file.name` is drawn from `migrationFiles`' own regex-filtered
-            // `readdirSync`, never from outside this module -- see `MigrateSql`'s
-            // doc comment. Quotes are still escaped, so an oddly-named future
-            // migration file cannot break the statement.
-            const escaped = file.name.replace(/'/g, "''");
-            await tx.exec(`insert into ${TRACKING_TABLE} (name) values ('${escaped}')`);
-        });
-        done.push(file.name);
-    }
-    return { applied: done };
-}