@everystack/server 0.4.11 → 0.4.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -159,9 +159,9 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/cli": "0.4.25",
     "@everystack/auth": "0.4.0",
-    "@everystack/pg-tools": "0.4.0"
+    "@everystack/pg-tools": "0.4.1",
+    "@everystack/cli": "0.4.29"
   },
   "scripts": {
     "test": "jest",

package/src/db.ts

@@ -110,6 +110,25 @@ export function getAdminDatabaseUrl(): string | null {
   return null;
 }
 
+/**
+ * The OPERATOR connection the privileged write lanes run on: the provisioned admin
+ * (migrator/owner) credential when present, else the linked SST Postgres master. Never the
+ * least-privilege authenticator (`DATABASE_URL`) — these lanes run DDL the authenticator
+ * cannot. Reports which source won so the caller can log the venue (not the credential).
+ *
+ * This is the resolution the `--direct` write lanes and `db:swap --stage` share (the
+ * stage-write-lanes foundation): the ops action returns this URL to an IAM-gated caller,
+ * which holds it in process memory and never prints it. Returns null when no operator
+ * connection is configured at all.
+ */
+export function getOperatorDatabaseUrl(): { url: string; source: 'admin' | 'master' } | null {
+  const admin = getAdminDatabaseUrl();
+  if (admin) return { url: admin, source: 'admin' };
+  const master = getMasterDatabaseUrl();
+  if (master) return { url: master, source: 'master' };
+  return null;
+}
+
 export function getJwtSecret(): Uint8Array {
   // PascalCase Secret (SST_RESOURCE_JwtSecret → { value })
   const pascal = sstLink('JwtSecret')?.value as string | undefined;

package/src/plugin.ts

@@ -625,6 +625,25 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       return { host: db.host, port: db.port, database: db.database, username: db.username, password: db.password };
     };
 
+    // --- db:operator-url ---
+    // The stage-write-lanes foundation (brick 1): resolve the OPERATOR connection
+    // (admin/migrator, else the linked master — never the least-privilege authenticator)
+    // and return it to the IAM-gated caller. The CLI's `--direct` write verbs and
+    // `db:swap --stage` invoke this, hold the URL in process memory, execute CLI-side with
+    // an unbounded clock, and never print it. The URL travels only in the Lambda invoke
+    // response — the same in-process channel db:psql uses for its components.
+    actions['db:operator-url'] = async () => {
+      const { getOperatorDatabaseUrl } = await import('./db');
+      const operator = getOperatorDatabaseUrl();
+      if (!operator) {
+        return {
+          error:
+            'no operator connection available — provision an admin credential (ADMIN_DATABASE_URL / AdminDatabaseUrl) or link an sst.aws.Postgres component for the master fallback.',
+        };
+      }
+      return { url: operator.url, source: operator.source };
+    };
+
     // --- db:query ---
     actions['db:query'] = async (payload, _ctx) => {
       const { sql: querySql } = payload as { sql: string };
@@ -1015,6 +1034,61 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       }
     };
 
+    // --- db:backfill — the one-shot data-job lane, stage-side (stage-write-lanes brick 4) ---
+    // db:backfill was direct-connection only: the sanctioned agent path for a committed,
+    // content-addressed, idempotent data job ended at "paste SQL into psql". This runs the
+    // same backfill core on the operator connection: the CLI ships the *.sql files, this plans
+    // (by content identity, against everystack.backfill_log), and under apply runs the pending
+    // jobs in order and records each. A least-privileged operator never holds a URL for a small
+    // data job; the --direct lane (CLI-side) is the escape for jobs too big for the 900s clock.
+    actions['db:backfill'] = async (payload, _ctx) => {
+      const p = (payload ?? {}) as {
+        files?: { file: string; sql: string }[];
+        apply?: boolean;
+        markApplied?: string;
+        actor?: string | null;
+        gitRef?: string | null;
+      };
+      try {
+        const {
+          planBackfills, readBackfillLog, executeBackfills, markBackfillApplied,
+        } = await import('@everystack/cli/backfill');
+        const { sql } = await import('drizzle-orm');
+        const runner = async (query: string): Promise<any[]> => {
+          const result: any = await opsDb.execute(sql.raw(query));
+          return Array.isArray(result) ? result : result?.rows ?? [];
+        };
+        const files = p.files ?? [];
+        const opts = { actor: p.actor ?? null, gitRef: p.gitRef ?? null };
+
+        // Adopt hatch: record a file as applied WITHOUT running it.
+        if (p.markApplied) {
+          const file = files.find((f) => f.file.endsWith(`/${p.markApplied}`) || f.file === p.markApplied);
+          if (!file) return { error: `--mark-applied names a file not shipped: ${p.markApplied}` };
+          const identity = await markBackfillApplied(runner, file as any, opts);
+          return { markedApplied: file.file, identity };
+        }
+
+        const plan = await (async () => planBackfills(files as any, await readBackfillLog(runner)))();
+        const planOut = {
+          applied: plan.applied,
+          pending: plan.pending.map(({ sql: _sql, ...rest }: any) => rest),
+          blocked: plan.blocked,
+        };
+        if (!p.apply) return { plan: planOut, applied: false };
+
+        const result = await executeBackfills(runner, plan, opts);
+        return {
+          plan: planOut,
+          applied: true,
+          ran: result.ran,
+          failed: result.failed ?? null,
+        };
+      } catch (err: any) {
+        return { error: err?.message || String(err) };
+      }
+    };
+
     // --- db:refresh — the credential-free DATA lane's refresh half (the reconcile-lane twin) ---
     // db:reconcile deploys the derived DEFINITION but no-ops on an unchanged def, so a pure
     // DATA-changed matview refresh had no credential-free path. This runs the refresh HERE on

package/src/provision.ts

@@ -20,7 +20,7 @@
  * without a database; plugin.ts wires the real deps.
  */
 
-import { generateRoleChainSQL, generateAdminRoleSQL } from './role-chain';
+import { generateRoleChainSQL, generateAdminRoleSQL, generateSearchPathSQL } from './role-chain';
 
 export interface ProvisionPayload {
   /** Password for the least-privilege API login. Alphanumeric only. */
@@ -30,6 +30,13 @@ export interface ProvisionPayload {
   loginRole?: string;
   adminRole?: string;
   appRoles?: string[];
+  /**
+   * The declared schema set (ordered, deduped, ending in 'public' — declaredSearchPath). When
+   * present, provision sets it as the ROLE default (ALTER ROLE … SET search_path) on both login
+   * roles, so bare refs resolve without a URL param (the search-path-ownership design). Absent or
+   * empty = all-public app, no path set (byte-identical to the pre-search-path-ownership behavior).
+   */
+  searchPath?: string[];
 }
 
 export interface ProvisionDeps {
@@ -59,7 +66,7 @@ export async function runProvision(
   payload: ProvisionPayload,
   deps: ProvisionDeps,
 ): Promise<ProvisionResult> {
-  const { authPassword, adminPassword, loginRole, adminRole, appRoles } = payload;
+  const { authPassword, adminPassword, loginRole, adminRole, appRoles, searchPath } = payload;
 
   // Passwords are generated (RandomPassword special:false / hex) — reject anything else
   // BEFORE any DDL runs, so nothing untrusted is interpolated into an ALTER ROLE literal.
@@ -89,11 +96,21 @@ export async function runProvision(
     passwordSet: false,
   };
 
+  // The role-default search_path (search-path-ownership): set it on the login role now that it
+  // exists. The right layer — a clean connection secret, bare refs resolved for every direct
+  // connection, and it persists through the API's SET ROLE. No-op for an all-public app.
+  const searchPathSql = searchPath ? generateSearchPathSQL(login, searchPath) : null;
+  if (searchPathSql) await deps.execute(searchPathSql);
+
   // Admin side FIRST — created and verified before the authenticator swap can happen.
   if (adminPassword && adminSql) {
     const admin = adminRole ?? 'migrator';
     await deps.execute(adminSql);
     await deps.execute(`ALTER ROLE ${admin} WITH LOGIN PASSWORD '${adminPassword}';`);
+    // The operator role gets the same role-default search_path — this is the role db:swap/apply/
+    // reconcile --direct connect as, so a clean URL (no ?search_path=) still resolves bare refs.
+    const adminSearchPathSql = searchPath ? generateSearchPathSQL(admin, searchPath) : null;
+    if (adminSearchPathSql) await deps.execute(adminSearchPathSql);
     result.adminRole = admin;
     result.adminPasswordSet = true;
 

package/src/role-chain.ts

@@ -74,6 +74,27 @@ export function generateRoleChainSQL(options: RoleChainOptions = {}): string {
   return lines.join('\n') + '\n';
 }
 
+/**
+ * `ALTER ROLE <role> SET search_path = <schemas>` — the role-default search_path
+ * (docs/plans/search-path-ownership.md). This is the RIGHT layer for a multi-schema app's
+ * bare-reference resolution: it lives on the ROLE, not baked into the connection secret. Every
+ * direct connection (psql, pg_restore, local scripts, the `--direct` write lanes) then resolves
+ * bare refs with a CLEAN connection URL — no `?search_path=` query param, which libpq rejects as
+ * an unknown keyword (the db:swap --direct break). Persists through `SET ROLE` (proven: search_path
+ * is a session GUC, SET ROLE does not reset it), so the API's authenticator login carries it to the
+ * app roles it switches to. Schema tooling resets to canonical per session (withCanonicalSearchPath),
+ * so regclass defaults still render qualified and the role default never causes false drift.
+ *
+ * Idempotent (ALTER ROLE SET is last-writer-wins). Returns null for an all-public app (no path
+ * needed) — byte-identical to today. `searchPath` is the ORDERED, deduped list (declaredSearchPath).
+ */
+export function generateSearchPathSQL(role: string, searchPath: string[]): string | null {
+  assertIdent(role, 'role');
+  if (!searchPath.length) return null;
+  searchPath.forEach((s) => assertIdent(s, 'schema'));
+  return `ALTER ROLE ${role} SET search_path = ${searchPath.join(', ')};\n`;
+}
+
 export interface AdminRoleOptions {
   /**
    * The LOGIN role operator tasks (migrate/seed/DDL/console) connect as — the OTHER half