@everystack/cli 0.4.48 → 0.4.50

package/src/cli/derived-render.ts

@@ -18,6 +18,7 @@ import type { ColumnSchema, SequenceSchema, TableSchema } from './schema-introsp
 import { parseIndexDefinition } from './schema-introspect.js';
 import { modelFileName, renderFieldLines } from './model-render.js';
 import { splitFunctionIdentity } from './pg-argtypes.js';
+import { GOVERNED_VOCABULARY, KNOWN_ROLES } from './authz-derive.js';
 
 export interface DerivedRenderResult {
   /** The source block: `export const … = defineView(…)` etc., dependency-ordered. */
@@ -77,26 +78,61 @@ function tsTemplate(body: string): string {
   return body.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
 }
 
+/** An object key, bare when it is a valid identifier and quoted when it is not — a role
+ *  name is a PostgreSQL identifier and may hold characters JavaScript will not take bare. */
+function tsKey(s: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(s) ? s : tsString(s);
+}
+
 function tsString(s: string): string {
   return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
 
-/** The relation grant shapes `abilities` can say. Null = inexpressible (caller FIXMEs). */
-function relationAbilities(grants: Record<string, string[]>): string[] | null {
-  const roles = Object.keys(grants);
-  for (const role of roles) {
-    if (role.toUpperCase() === 'PUBLIC') return null;
-    if (grants[role].some((p) => p !== 'SELECT')) return null;
+/**
+ * Split a relation's live ACL into what `abilities` can SAY and what must be RECORDED.
+ *
+ * A grantee whose privileges are exactly `SELECT`, and which is a named app role, is an
+ * intended read audience — `can('read')`. Everything else is fact without intent:
+ * `PUBLIC` (not a role the ability vocabulary addresses) and any privilege beyond SELECT
+ * (write grants, REFERENCES/TRIGGER/TRUNCATE). Those become `privileges`.
+ *
+ * Splitting rather than rejecting is the whole of R1: previously ANY inexpressible grant
+ * discarded the entire object, body included.
+ */
+function splitRelationGrants(
+  grants: Record<string, string[]>,
+): { abilities: string[]; privileges: Record<string, string[]>; foreign: string[] } {
+  const readRoles = new Set<string>();
+  const privileges: Record<string, string[]> = {};
+  const foreign: string[] = [];
+  for (const [grantee, privs] of Object.entries(grants)) {
+    const selectOnly = privs.length === 1 && privs[0] === 'SELECT';
+    // ABILITIES are limited to the compiler's own vocabulary (authz-derive's KNOWN_ROLES).
+    // A foreign grantee is FACT, not opinion, so it is RECORDED — never declared as an
+    // intended audience. The views path used to render any select-only grantee as an
+    // ability, so one pull could declare a role as an ABILITY on a view while the table
+    // recorded it as a foreign grantee, and the reachability gate then demanded table-side
+    // reach the tables path will never render. The contract contradicted itself.
+    //
+    // RECORDED, not dropped — and that is the part the obvious fix gets wrong. On a TABLE,
+    // "not rendered" is safe because the table reconciler leaves an ungoverned grantee
+    // alone. On a DERIVED object there is no such carve-out: diffObjectGrants unions the
+    // declared and live grantees, so a grantee we omit is a grantee we REVOKE. Measured:
+    // declared {anon,authenticated} against live +outbound_migrator plans
+    // `REVOKE SELECT, UPDATE ON public.v FROM outbound_migrator`. Dropping them would
+    // reintroduce the silent revoke this whole branch exists to prevent.
+    if (!GOVERNED_VOCABULARY.has(grantee)) foreign.push(grantee);
+    if (selectOnly && KNOWN_ROLES.has(grantee)) readRoles.add(grantee);
+    else privileges[grantee] = [...privs].sort();
   }
-  const set = new Set(roles);
-  const out: string[] = [];
-  if (set.has('anon') && set.has('authenticated')) {
-    out.push(`can('read')`);
-    set.delete('anon');
-    set.delete('authenticated');
+  const abilities: string[] = [];
+  if (readRoles.has('anon') && readRoles.has('authenticated')) {
+    abilities.push(`can('read')`);
+    readRoles.delete('anon');
+    readRoles.delete('authenticated');
   }
-  for (const role of [...set].sort()) out.push(`can('read', { role: ${tsString(role)} })`);
-  return out;
+  for (const role of [...readRoles].sort()) abilities.push(`can('read', { role: ${tsString(role)} })`);
+  return { abilities, privileges, foreign: foreign.sort() };
 }
 
 /**
@@ -202,6 +238,32 @@ function renderTableIndexBuilder(indexdef: string): string | null {
   return s;
 }
 
+/**
+ * A collision-free variable for a trigger binding, chosen deterministically so a re-pull of
+ * an unchanged database is byte-stable. In order: the bare name, then `<name>Trigger`, then
+ * owner-qualified, then owner-qualified + `Trigger`. The last step cannot collide —
+ * a trigger name is unique within its table, so table + name is unique in the schema.
+ */
+function uniqueVar(base: string, o: LiveObject, used: Set<string>): string {
+  const ownerName = (o.table ?? '').split('.').pop() ?? '';
+  for (const candidate of [
+    base,
+    `${base}Trigger`,
+    toCamelCase(`${ownerName}_${o.name}`),
+    toCamelCase(`${ownerName}_${o.name}_trigger`),
+  ]) {
+    if (!used.has(candidate)) {
+      used.add(candidate);
+      return candidate;
+    }
+  }
+  // Unreachable on a real catalog; a counter beats throwing on a name.
+  let i = 2;
+  while (used.has(`${base}Trigger${i}`)) i += 1;
+  used.add(`${base}Trigger${i}`);
+  return `${base}Trigger${i}`;
+}
+
 export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRenderOptions): DerivedRenderResult {
   const warnings: string[] = [];
   const lines: string[] = [];
@@ -227,10 +289,12 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
 
   // -- emission order: dependencies first (Kahn over derived→derived edges) ---
 
+  // Triggers are held out of the topological pass and emitted LAST (see the trigger block
+  // at the end). A binding needs BOTH its target and its execute function to already
+  // exist, and the catalog records no trigger→function edge, so file order — not the
+  // dependency sort — is what guarantees it.
   const renderable = catalog.objects.filter((o) => o.kind !== 'trigger');
-  for (const t of catalog.objects.filter((o) => o.kind === 'trigger')) {
-    warnings.push(`${t.identity}: live trigger not rendered — declare it on its model with trigger() (v1 renders relations, functions, and sequences).`);
-  }
+  const triggers = catalog.objects.filter((o) => o.kind === 'trigger');
   const byIdentity = new Map(renderable.map((o) => [o.identity, o]));
   // Var names carry the schema for non-public objects — two schemas can share a bare name.
   // OVERLOADS share everything but their argument types, so a bare name would emit two
@@ -302,22 +366,42 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
     const { refs, fixmes } = depsFor(o.identity);
 
     if (o.kind === 'view' || o.kind === 'materialized view') {
-      const abilities = relationAbilities(o.grants ?? {});
-      if (abilities === null) {
-        const grantText = Object.entries(o.grants ?? {}).map(([r, p]) => `${r}: ${p.join('/')}`).join(', ');
+      // The live ACL splits in two: the part `can('read')` can SAY (plain SELECT to named
+      // app roles) becomes abilities, and everything else is RECORDED as `privileges`.
+      //
+      // This used to skip the object outright — definition and all — whenever any grant
+      // was inexpressible, which on a real brownfield schema is every relation it has:
+      // three roles hold the blanket DELETE/INSERT/REFERENCES/SELECT/TRIGGER/TRUNCATE/
+      // UPDATE that `GRANT ALL ON ALL TABLES IN SCHEMA` leaves behind, and PUBLIC holds
+      // SELECT on a few. The adopter got a FIXME instead of their view.
+      //
+      // Recording is also what makes rendering SAFE, and it is why the silent-REVOKE
+      // question that blocked this no longer needs an answer: emitting the view with only
+      // the abilities we can express would leave the write grants undeclared, so the next
+      // generate would plan a REVOKE for each — a silent skip traded for a silent revoke.
+      // Declared == live means nothing is planned at all.
+      const { abilities, privileges, foreign } = splitRelationGrants(o.grants ?? {});
+      if (foreign.length) {
+        warnings.push(
+          `${o.identity}: grants exist for ${foreign.join(', ')} — recorded as \`privileges\`, not declared as ` +
+          'abilities. Abilities name the roles the model governs (anon/authenticated/admin); a grantee outside ' +
+          'that vocabulary is fact, not an intended audience. Recorded rather than dropped because a derived ' +
+          'object REVOKES any live grantee the declaration omits.',
+        )
+      }
+      const writeGrants = Object.values(privileges).some((ps) =>
+        ps.some((p) => p === 'INSERT' || p === 'UPDATE' || p === 'DELETE'),
+      );
+      if (writeGrants) {
         // A view carrying INSERT/UPDATE/DELETE almost never means someone intended a
         // writable view — it usually traces to a blanket `GRANT ALL ON ALL TABLES IN
         // SCHEMA public` in an old migration, which sweeps views up with the tables.
         // Naming that here saves the diagnosis; an adopter paid for it once already.
-        const writeGrants = Object.values(o.grants ?? {}).some((ps) =>
-          ps.some((p) => p === 'INSERT' || p === 'UPDATE' || p === 'DELETE'),
+        const grantText = Object.entries(privileges).map(([r, p]) => `${r}: ${p.join('/')}`).join(', ');
+        warnings.push(
+          `${o.identity}: write privileges (${grantText}) recorded as \`privileges\` — the object is declared and nothing will be revoked. ` +
+          'Write privileges on a view usually come from a blanket `GRANT ALL ON ALL TABLES IN SCHEMA …` rather than a deliberate writable view — check that first, then revoke and re-pull.',
         );
-        const hint = writeGrants
-          ? ' Write privileges on a view usually come from a blanket `GRANT ALL ON ALL TABLES IN SCHEMA …` rather than a deliberate writable view — check that first.'
-          : '';
-        warnings.push(`${o.identity}: live grants (${grantText}) are not expressible as relation abilities (read-only, role-shaped) — object skipped; migrate it by hand.${hint}`);
-        lines.push(`// FIXME: ${o.identity} skipped — live grants (${grantText}) are not expressible as abilities (views are read surfaces).`, '');
-        continue;
       }
 
       // --matviews-as-tables (the gap-B consumer flip): the matview renders as a
@@ -359,7 +443,13 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
           lines.push(
             ...fixmes,
             `export const ${varName} = defineMaterializedTable(${tsString(o.name)}, {`,
-            `  ${abilities.length ? `abilities: [${abilities.join(', ')}],` : 'private: true,'}`,
+            // Same split as the relation path: a model carries `privileges` too, so the
+            // inexpressible grants are recorded rather than dropped on this branch either.
+            ...(abilities.length ? [`  abilities: [${abilities.join(', ')}],`]
+              : Object.keys(privileges).length ? [] : ['  private: true,']),
+            ...(Object.keys(privileges).length
+              ? [`  privileges: { ${Object.keys(privileges).sort().map((g) => `${tsKey(g)}: [${privileges[g].map(tsString).join(', ')}]`).join(', ')} },`]
+              : []),
             ...(o.schema !== 'public' ? [`  schema: ${tsString(o.schema)},`] : []),
             '  fields: {',
             ...fieldLines,
@@ -377,12 +467,21 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       }
 
       const props: string[] = [];
+      const hasPrivileges = Object.keys(privileges).length > 0;
       if (o.kind === 'view') props.push(`securityInvoker: ${o.securityInvoker === true},`);
-      if (abilities.length === 0) props.push('private: true,');
-      else {
+      // `private: true` means "declared dark, no grants" — it contradicts a recorded
+      // grant, and the model refuses the pair. A relation whose only reach is recorded
+      // (PUBLIC SELECT, or a write grant) is not dark; it just has no CHOSEN audience.
+      if (abilities.length === 0 && !hasPrivileges) props.push('private: true,');
+      else if (abilities.length) {
         props.push(`abilities: [${abilities.join(', ')}],`);
         need('can');
       }
+      if (hasPrivileges) {
+        const entries = Object.keys(privileges).sort()
+          .map((g) => `${tsKey(g)}: [${privileges[g].map(tsString).join(', ')}]`);
+        props.push(`privileges: { ${entries.join(', ')} },`);
+      }
       if (refs.length) props.push(`dependsOn: [${refs.join(', ')}],`);
       if (o.kind === 'materialized view') {
         const builders = o.indexes.map((def) => {
@@ -458,6 +557,11 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       props.push(`abilities: [${roleGrants.map((r) => `can('execute', { role: ${tsString(r)} })`).join(', ')}],`);
       need('can');
     }
+    // A live PUBLIC EXECUTE is RECORDED, not converted into an ability. Rendering it as
+    // can('execute', { role: … }) would invent an audience the database never named, and
+    // dropping it silently would make the descriptor plan a REVOKE on adoption. Both are
+    // the adopter's database being changed to suit our vocabulary.
+    if (publicExec) props.push(`privileges: { PUBLIC: ['EXECUTE'] },`);
     if (refs.length) props.push(`dependsOn: [${refs.join(', ')}],`);
     if (o.comment) props.push(`comment: ${tsString(o.comment)},`);
     props.push(`body: sql\`${tsTemplate(f.src.trim())}\`,`);
@@ -465,8 +569,11 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
     need('sql');
     lines.push(
       ...fixmes,
-      ...(publicExec
-        ? [`// FIXME: ${o.identity} — live grants EXECUTE to PUBLIC; descriptors ALWAYS revoke PUBLIC. Declare the intended callers (adopting this descriptor applies the revoke).`]
+      // Not a FIXME any more — `privileges: { PUBLIC: ['EXECUTE'] }` above says it, and
+      // adopting the descriptor no longer applies a revoke. It is still worth a look on a
+      // SECURITY DEFINER function, which is what db:check now WARNs about.
+      ...(publicExec && f.secdef
+        ? [`// NOTE: ${o.identity} is SECURITY DEFINER and live-granted EXECUTE to PUBLIC — recorded, not chosen. Narrow it to can('execute', { role }) once you know the intended callers.`]
         : []),
       `export const ${varName} = defineFunction(${tsString(declaredName(o))}, {`,
       ...props.map((p) => `  ${p}`),
@@ -476,6 +583,69 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
     names.push(varName);
   }
 
+  // -- trigger bindings, last -------------------------------------------------
+  //
+  // Every identifier the file has already exported. A trigger's variable must dodge all of
+  // them, not just other triggers.
+  const usedVars = new Set<string>([...names, ...sequenceNames, ...materializedTableNames]);
+  //
+  // One descriptor per BINDING, never per function. The two are many-to-one — on the
+  // reference schema 18 bindings share 11 functions, `_touch_updated_at()` alone serving
+  // five tables — so a renderer keyed on the function would silently emit 11 and lose the
+  // rest. The target may be a MODEL (imported) or a derived VIEW (declared above).
+  for (const o of [...triggers].sort((a, b) => a.identity.localeCompare(b.identity))) {
+    const owner = o.ownerIdentity ?? (o.table?.includes('.') ? o.table : `${o.schema}.${o.table ?? ''}`);
+    const modelVar = opts.knownTables.get(owner);
+    const targetVar = modelVar ?? varOf.get(owner);
+    if (!o.trg || !targetVar) {
+      warnings.push(
+        `${o.identity}: trigger not rendered — ${!o.trg
+          ? 'the introspection carried no structured binding (pre-R2 catalog read)'
+          : `its target '${owner}' is neither a known model nor a rendered view`}.`,
+      );
+      continue;
+    }
+    // The function is matched by identity. Trigger functions take no arguments, so the
+    // catalog's signature is always `()` — no overload can exist to disambiguate.
+    const fnVar = varOf.get(`${o.trg.functionIdentity}()`);
+    if (!fnVar) {
+      warnings.push(`${o.identity}: trigger not rendered — its function '${o.trg.functionIdentity}' is not in the rendered set.`);
+      continue;
+    }
+    // Registered only once the binding actually renders — an import emitted for a skipped
+    // trigger would be an unused name in generated code.
+    if (modelVar) modelRefs.add(owner);
+    // A trigger's name collides freely: with its OWN function (`update_users_tsvector` is
+    // both, on the reference schema) and with a same-named trigger on another table
+    // (trigger names are unique per table, not per schema). Either collision emits two
+    // `export const X` — the file does not compile, and `execute: X` would bind the
+    // trigger to itself. Suffix only on collision, so an uncontended schema renders
+    // byte-identically to a name-per-object scheme.
+    const varName = uniqueVar(
+      toCamelCase(o.schema === 'public' ? o.name : `${o.schema}_${o.name}`),
+      o,
+      usedVars,
+    );
+    const props = [
+      `on: ${targetVar},`,
+      `timing: ${tsString(o.trg.shape.timing)},`,
+      `events: [${o.trg.shape.events.map(tsString).join(', ')}],`,
+      `forEach: ${tsString(o.trg.shape.forEach)},`,
+      ...(o.trg.updateOf?.length ? [`of: [${o.trg.updateOf.map(tsString).join(', ')}],`] : []),
+      ...(o.trg.when ? [`condition: sql\`${tsTemplate(o.trg.when)}\`,`] : []),
+      `execute: ${fnVar},`,
+    ];
+    if (o.trg.when) need('sql');
+    need('defineTrigger');
+    lines.push(
+      `export const ${varName} = defineTrigger(${tsString(o.name)}, {`,
+      ...props.map((p) => `  ${p}`),
+      '});',
+      '',
+    );
+    names.push(varName);
+  }
+
   return {
     block: lines.join('\n').trimEnd(),
     names,

package/src/cli/index.ts

@@ -359,7 +359,7 @@ Usage:
   everystack db:export         --schema <name> [--stage <name> | --database-url <url> [--out <file.dump>]] [--models <barrel>]  Schema-scoped pg_dump artifact, stamped with the DECLARED schema fingerprint (the canonical-sync export; db:swap gates on that stamp). --stage dumps the stage's private DB via the ops Lambda → S3; --database-url (explicit flag, never the env) dumps a reachable DB to a local .dump + .meta.json — the build-locally → publish → swap on-ramp
   everystack db:swap           --schema <name> --from <artifact.dump | artifact-id> [--stage <name> --direct | --database-url <url>] --confirm [--fingerprint <hash>] [--snapshot physical|logical|none] [--snapshot-ref <id>] [--rebuild-derived] [--dump-build <file.json>]  Land a schema artifact atomically: fingerprint gate → pre-flight refusals → CONFIRMED snapshot → restore into <schema>_incoming (COPY-safe rewrite) → build the paired derived layer → one txn (drop+rename+recreate app→schema FKs, re-apply authz + schema USAGE) → assertions → drop retiring. Refresh-free; app.* untouched; the derived layer is never absent. DESTRUCTIVE. The venue is EXPLICIT — DATABASE_URL in the env is refused, and --stage requires --direct (a multi-GB restore exceeds the ops-Lambda 900s clock). The rollback point defaults to a PHYSICAL RDS snapshot on a stage that exposes databaseInstanceId (no locks, no pg_dump contending with the restore) and a WAITED logical db:backup otherwise; a bare --database-url refuses without --snapshot-ref <id> or --snapshot none. docs/schema-swap.md
   everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--schema-out db/schema.generated.ts] [--allow-drops] [--apply] [--dry-run]  Diff models vs the live DB → next migration file, or with --apply execute it directly (one transaction, schema_log recorded, verified by re-diff — no drizzle folder needed; direct connection only; DROPs held back unless --allow-drops). --dry-run prints the edge and writes NOTHING (no migration, no journal entry, no schema refresh) — the preview verb; db:diff computes a models-vs-models edge with no database at all. The resolved --schema-out is recorded in the migration journal: later flag-less runs reuse it (flag > recorded > default), a differing flag updates the record and says so
-  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored); --abilities public-read stamps the common stanza (public read, admin write) uncommented — explicit generated code, never a runtime default. --matviews-as-tables renders every matview as defineMaterializedTable with INTROSPECTED fields (the canonical-sync flip: a pipeline-owned table everystack migrates but never refreshes) — names land in an exported materializedTables array to spread into your models; fields come back nullable/unkeyed (matviews carry no PK/NOT NULL) — tighten on review; add --suggest-keys to probe the LIVE rows for functionally-unique columns (one scan per matview) and surface each as a commented .primaryKey() suggestion. docs/derived-objects.md#flipping-a-matview-to-a-materialized-table---matviews-as-tables
+  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities live|public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored). **--abilities live is the brownfield mode**: derive each model's authz from the grants and policies the database ALREADY has, and write the foreign-grantee baseline (db/authz-baseline.json) — this is what you want when adopting an existing schema. --abilities public-read stamps the common stanza (public read, admin write) uncommented — greenfield only, since on an existing database it declares public read of every table. Both are explicit generated code, never a runtime default. --matviews-as-tables renders every matview as defineMaterializedTable with INTROSPECTED fields (the canonical-sync flip: a pipeline-owned table everystack migrates but never refreshes) — names land in an exported materializedTables array to spread into your models; fields come back nullable/unkeyed (matviews carry no PK/NOT NULL) — tighten on review; add --suggest-keys to probe the LIVE rows for functionally-unique columns (one scan per matview) and surface each as a commented .primaryKey() suggestion. docs/derived-objects.md#flipping-a-matview-to-a-materialized-table---matviews-as-tables
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
   everystack db:fingerprint    [--stage <name> | --database-url <url>] [--models <barrel>] [--json]  Content-address the live base schema (tables+constraints+authz) and compare against the models — MATCH/MISMATCH (exit 1), plus the unfingerprinted-objects report
   everystack db:reconcile      [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--overwrite-drift] [--only a,b] [--json]  Reconcile the derived layer (functions/views/matviews/triggers) against the DECLARED descriptors (defineView/defineMaterializedView/defineFunction/defineSql/trigger() on models, from the barrel) — the single home (db/sql is retired; leftover .sql files fail with the migration path): plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (atomic — DDL + provenance in one transaction) and records provenance + schema_log; --apply --stage runs credential-free in the ops Lambda (no admin URL on the deployer, the db:apply twin), --apply --database-url runs direct. Hand-edits are drift (never overwritten silently). First contact with existing objects: --baseline TRUSTS live == source (records provenance, verifies nothing), --rebuild GUARANTEES it (drop+create from source). They are mutually exclusive. --only <schema.name,…> restricts the run to the named objects (surgical); with --rebuild it FORCES those to rebuild from source even when the hashes show no diff — the recovery exit when a mistaken --rebaseline left a self-consistent-but-wrong provenance row (the dependency cascade rebuilds their live dependents).

package/src/cli/parse-flags.ts

@@ -25,12 +25,32 @@ function isFlag(arg: string): boolean {
   return arg.startsWith('-') && arg.length > 1;
 }
 
-/** Parse `--key value` / `-k value` pairs; a flag with no value becomes `'true'`. */
+/** Parse `--key value`, `--key=value`, `-k value`; a flag with no value becomes `'true'`. */
 export function parseFlags(args: string[]): Record<string, string> {
   const flags: Record<string, string> = {};
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (!isFlag(arg)) continue;
+
+    // `--key=value`. Split on the FIRST `=` only: the value is routinely a connection string
+    // whose own query carries more (`postgresql://h/db?sslmode=require`), and splitting on
+    // every `=` would truncate it to the host.
+    //
+    // This form used to be dropped ENTIRELY — the whole `--database-url=…` token parsed as a
+    // key with no value, so the flag was simply absent. For a venue flag that is not a parse
+    // error, it is a silent CHANGE OF TARGET: `db:plan --database-url=postgres://localhost/x`
+    // found no url source, fell through to the stage lane, and went to AWS. A consumer lost an
+    // afternoon to it against a local database with no AWS at all. On a destructive verb the
+    // same slip aims at the deployed stage instead of the local database.
+    const eq = arg.indexOf('=');
+    if (eq > 1) {
+      const rawKey = arg.slice(0, eq);
+      const key = rawKey.startsWith('--') ? rawKey.slice(2) : rawKey.slice(1);
+      // The empty string is a VALUE, not an absent one — same rule as `--set ''` below.
+      flags[key] = arg.slice(eq + 1);
+      continue;
+    }
+
     const key = arg.startsWith('--') ? arg.slice(2) : arg.slice(1);
     const next = args[i + 1];
     flags[key] = next !== undefined && !isFlag(next) ? args[++i] : 'true';

package/src/plugin.ts

@@ -9,17 +9,35 @@
 
 import type { StorageAdapter } from './storage/index';
 
-/** Minimal plugin context (compatible with @everystack/server/plugin PluginContext) */
+/**
+ * These types MIRROR @everystack/server/plugin. They are not imported from it, and that
+ * is deliberate: server imports `@everystack/cli/apply`, `/reconcile`, `/exec` and more,
+ * so a type import in the other direction closes a package cycle. Both packages ship
+ * TypeScript source, so a type-only import still drags the whole module graph in.
+ *
+ * The copy going stale is what broke a consumer: server made `publishJob` optional and
+ * gave it an options argument, nothing here compared the two declarations, and `Plugin`
+ * is contravariant in `ctx` — so cli's `Plugin` silently stopped being assignable to
+ * server's and the TS2322 landed in their build instead of ours.
+ *
+ * **The link is `__tests__/cli/plugin-type-compat.test.ts`**, which imports BOTH and
+ * asserts assignability at compile time. The test can cross the boundary because it is
+ * not part of either package's published graph. Drift now fails there, in this repo, on
+ * the commit that causes it. If you change a shape below, that test is the gate.
+ */
+
+/** Mirrors @everystack/server/plugin PluginContext. `publishJob` is OPTIONAL (a lean app
+ *  with no @everystack/jobs never sets it) and takes an options argument. */
 interface PluginContext {
   db: any;
   schema: Record<string, any>;
   verifyToken: (token: string) => Promise<Record<string, unknown> | null>;
   environment: string;
-  publishJob: (type: string, payload: unknown) => Promise<string>;
+  publishJob?: (type: string, payload: unknown, options?: { schedulable?: boolean; runAt?: Date }) => Promise<string>;
   [key: string]: unknown;
 }
 
-/** Minimal route type (compatible with @everystack/server Route) */
+/** Mirrors @everystack/server Route. */
 interface Route {
   path: string;
   method?: string;
@@ -27,10 +45,10 @@ interface Route {
   handler: (req: Request) => Promise<Response>;
 }
 
-/** Action handler type (compatible with @everystack/server/plugin ActionHandler) */
+/** Mirrors @everystack/server/plugin ActionHandler. */
 type ActionHandler = (payload: unknown, ctx: PluginContext) => Promise<unknown>;
 
-/** Plugin factory function */
+/** Mirrors @everystack/server/plugin Plugin. */
 type Plugin = (ctx: PluginContext) => Promise<{
   routes?: Route[];
   actions?: Record<string, ActionHandler>;