@everystack/cli 0.3.27 → 0.3.31

package/src/cli/commands/db-reconcile.ts

@@ -35,7 +35,7 @@ import {
   renderSchemaLogInsert,
   ENSURE_RECONCILER_SQL,
 } from '../derived-apply.js';
-import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { currentGitRef } from '../state-apply.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
@@ -70,6 +70,18 @@ export interface ReconcileRun {
  * Plan — and under `apply`, execute — one reconcile. Pure orchestration over
  * an injected QueryRunner; the CLI shell below owns flags, files, and exits.
  */
+/** Statements Postgres forbids inside a transaction block — they implicitly commit. */
+export const NON_TRANSACTIONAL_RE = /\bCONCURRENTLY\b|\bVACUUM\b/i;
+
+/**
+ * Whether the whole batch can run inside one transaction. Almost always yes — the escape hatch
+ * is a consumer whose matview source carries a `CREATE INDEX CONCURRENTLY` (rendered verbatim) or
+ * a `VACUUM`, which self-commit and cannot live in a transaction block.
+ */
+export function isTransactionalBatch(statements: string[]): boolean {
+  return statements.every((s) => !NON_TRANSACTIONAL_RE.test(s));
+}
+
 export async function executeReconcile(
   runner: QueryRunner,
   sources: SourceFile[],
@@ -102,14 +114,52 @@ export async function executeReconcile(
   await runner(ENSURE_RECONCILER_SQL.join(';\n'));
 
   const started = now();
-  let outcome = 'applied';
+
+  // Atomicity: the DDL and the provenance/schema_log that describe it go in ONE transaction, so a
+  // failure rolls the whole thing back — live and its bookkeeping can never diverge. That divergence
+  // (objects changed, provenance stale) is exactly the drift that strands a stage after a partial
+  // apply. The one exception is a batch with statements Postgres forbids inside a transaction block
+  // (CONCURRENTLY index builds, VACUUM); those self-commit, so we fall back to the unwrapped path.
+  const atomic = isTransactionalBatch(rendered.statements);
+
+  if (atomic) await runner('BEGIN');
   try {
     if (rendered.statements.length > 0) {
       await runner(rendered.statements.join(';\n'));
     }
+
+    // Re-read the catalog so provenance records the def hashes of what NOW exists, not what we hoped
+    // would exist. Inside the transaction this reads the batch's own not-yet-committed writes.
+    const after = await introspectDerived(runner);
+    const liveById = new Map(after.objects.map((o) => [o.identity, o]));
+    const srcById = new Map(parsed.objects.map((o) => [o.identity, o]));
+
+    const bookkeeping: string[] = [];
+    for (const identity of rendered.record) {
+      const src = srcById.get(identity);
+      const liveObj = liveById.get(identity);
+      if (!src || !liveObj) {
+        throw new Error(`reconcile applied but ${identity} is not introspectable afterwards — provenance not recorded, investigate`);
+      }
+      bookkeeping.push(renderProvenanceUpsert(identity, src.hash, liveObj.defHash));
+    }
+    for (const identity of rendered.remove) bookkeeping.push(renderProvenanceDelete(identity));
+    bookkeeping.push(renderSchemaLogInsert({
+      kind: 'compute reconcile',
+      sql: rendered.statements.join(';\n') || '-- provenance-only (baseline/prune)',
+      outcome: 'applied',
+      actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
+      durationMs: now() - started,
+    }));
+    await runner(bookkeeping.join(';\n'));
+
+    if (atomic) await runner('COMMIT');
   } catch (err: any) {
-    outcome = 'failed';
-    // The batch rolled back; record the attempt, then surface the failure.
+    // Roll the whole batch back — no half-applied DDL, no stale provenance — THEN record the failed
+    // attempt in its own transaction (the memoir must survive the rollback).
+    if (atomic) {
+      try { await runner('ROLLBACK'); } catch { /* the connection may already be aborted */ }
+    }
     try {
       await runner(renderSchemaLogInsert({
         kind: 'compute reconcile', sql: rendered.statements.join(';\n'),
@@ -118,37 +168,31 @@ export async function executeReconcile(
         durationMs: now() - started,
       }));
     } catch { /* the memoir is best-effort on failure */ }
-    throw err;
+    throw explainReconcileError(err);
   }
 
-  // The batch committed — re-read the catalog so provenance records the def
-  // hashes of what NOW exists, not what we hoped would exist.
-  const after = await introspectDerived(runner);
-  const liveById = new Map(after.objects.map((o) => [o.identity, o]));
-  const srcById = new Map(parsed.objects.map((o) => [o.identity, o]));
-
-  const bookkeeping: string[] = [];
-  for (const identity of rendered.record) {
-    const src = srcById.get(identity);
-    const liveObj = liveById.get(identity);
-    if (!src || !liveObj) {
-      throw new Error(`reconcile applied but ${identity} is not introspectable afterwards — provenance not recorded, investigate`);
-    }
-    bookkeeping.push(renderProvenanceUpsert(identity, src.hash, liveObj.defHash));
-  }
-  for (const identity of rendered.remove) bookkeeping.push(renderProvenanceDelete(identity));
-  bookkeeping.push(renderSchemaLogInsert({
-    kind: 'compute reconcile',
-    sql: rendered.statements.join(';\n') || '-- provenance-only (baseline/prune)',
-    outcome,
-    actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
-    durationMs: now() - started,
-  }));
-  await runner(bookkeeping.join(';\n'));
-
   return { plan, applied: true, statements: rendered.statements };
 }
 
+/**
+ * reconcile's `create` is a bare `CREATE` (no drop-first, no IF NOT EXISTS), so when its plan
+ * and reality disagree — a partial earlier run, a hand-created object — Postgres answers with a
+ * cryptic unique-violation on `pg_type`/`pg_class` instead of anything actionable. Turn that into
+ * a message that tells the operator what to do.
+ */
+export function explainReconcileError(err: unknown): Error {
+  const msg = String((err as any)?.message ?? err);
+  if (/pg_type_typname_nsp_index|pg_class_relname_nsp_index|already exists/i.test(msg)) {
+    return new Error(
+      `${msg}\n\nreconcile tried to CREATE a derived object whose name already exists — usually a partial `
+      + `earlier run or a hand-created object (its create is not idempotent). Resolve by explicitly dropping `
+      + `the colliding object (DROP MATERIALIZED VIEW / VIEW … CASCADE) and re-running, or, if the plan reports `
+      + `it as drift, re-run with --overwrite-drift.`,
+    );
+  }
+  return err instanceof Error ? err : new Error(msg);
+}
+
 // ---------------------------------------------------------------------------
 // Report rendering (pure).
 // ---------------------------------------------------------------------------
@@ -241,6 +285,20 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     process.exit(1);
   }
 
+  // --baseline only writes under --apply (executeReconcile returns the plan and executes nothing
+  // when apply=false). Passing it alone used to print "recording provenance…" and exit 0 while
+  // persisting nothing — a silent no-op. Fail loudly instead; the plan already lists needsBaseline.
+  if (flags.baseline === 'true' && !apply) {
+    fail('--baseline only persists with --apply — on its own it records nothing (it silently no-op\'d before). Re-run with --apply, or drop --baseline to just see the plan (it already lists what needs baseline).');
+    process.exit(1);
+  }
+
+  // --rebuild and --baseline are opposite answers to the same "can't verify first contact" question.
+  if (flags.rebuild === 'true' && flags.baseline === 'true') {
+    fail('--rebuild and --baseline are opposites: --baseline TRUSTS that live already matches source, --rebuild REBUILDS from source to guarantee it. Pick one.');
+    process.exit(1);
+  }
+
   let sources: SourceFile[];
   try {
     sources = await readSqlDir(sqlDir);
@@ -252,7 +310,7 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
   let runner: QueryRunner;
   let end: (() => Promise<void>) | undefined;
   if (dbSource.kind === 'url') {
-    step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+    step(connectingVia(dbSource));
     ({ runner, end } = await createUrlRunner(dbSource.url));
   } else {
     step('Resolving deployed config...');
@@ -264,6 +322,7 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     const run = await executeReconcile(runner, sources, {
       apply,
       baseline: flags.baseline === 'true',
+      rebuild: flags.rebuild === 'true',
       overwriteDrift: flags['overwrite-drift'] === 'true',
       actor: process.env.USER ?? null,
       gitRef: currentGitRef(),
@@ -277,6 +336,9 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
         fail(`not applied: ${run.refusal}`);
       } else if (run.applied) {
         success(`Applied ${run.statements.length} statement(s); provenance and schema_log recorded.`);
+        if (run.plan.actions.some((a) => a.action === 'baseline')) {
+          warn('baseline recorded trust WITHOUT verifying live matches source — on first contact it CANNOT compare a source hash to a live deparse, so it trusts your assertion, it does not check. If you need a guarantee that live == db/sql, drop the object and let reconcile recreate it (or --overwrite-drift when the plan reports drift).');
+        }
       } else if (apply) {
         success('Nothing to apply — derived layer matches source.');
       } else if (run.statements.length > 0) {

package/src/cli/commands/db-sync.ts

@@ -45,11 +45,12 @@ import {
 import { fingerprintModels } from '../schema-fingerprint.js';
 import { compileDrizzleSource } from '../schema-source.js';
 import type { SourceFile } from '../derived-source.js';
-import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { planBackfills, readBackfillLog } from '../backfill.js';
 import { resolveModelsPath } from '../models-path.js';
 import { executeReconcile, buildReconcileReport, type ReconcileRun } from './db-reconcile.js';
 import { loadModels } from './db-generate.js';
+import { reportPipelineLastRun } from './pipeline-run.js';
 import { step, success, fail, info, warn } from '../output.js';
 
 const DEFAULT_SQL_DIR = 'db/sql';
@@ -169,6 +170,16 @@ export function buildSyncReport(run: SyncRun): string[] {
     lines.push(`· ${state.classified.notices.length} notice(s) — manual follow-ups, nothing executed for them`);
   }
 
+  // The base fingerprint is a STATE-layer fact: both endpoints are sampled around
+  // the state apply, before compute runs. Print it here, adjacent to the state
+  // section, so an empty→full move never reads as if the compute step caused it —
+  // the derived layer (functions/views/matviews) is not fingerprinted at all.
+  lines.push(
+    state.toFingerprint === state.fromFingerprint
+      ? `base fingerprint: ${short(state.toFingerprint)} (unchanged)`
+      : `base fingerprint: ${short(state.fromFingerprint)} → ${short(state.toFingerprint)} (across the state apply)`,
+  );
+
   // Compute.
   if (compute === null) {
     lines.push('· compute: no db/sql directory — derived layer not declared, skipped');
@@ -181,12 +192,7 @@ export function buildSyncReport(run: SyncRun): string[] {
     }
   }
 
-  // Fingerprint.
-  lines.push(
-    state.toFingerprint === state.fromFingerprint
-      ? `fingerprint: ${short(state.toFingerprint)} (unchanged)`
-      : `fingerprint: ${short(state.fromFingerprint)} → ${short(state.toFingerprint)}`,
-  );
+  // Verdict.
   if (run.fingerprintMatch) {
     lines.push('MATCH — the database is the state your checkout declares');
   } else if (run.stateConverged) {
@@ -260,7 +266,7 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
   const sqlDir = flags['sql-dir'] || DEFAULT_SQL_DIR;
   const sources = await readSqlDirIfPresent(sqlDir);
 
-  step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+  step(connectingVia(dbSource));
   const { runner, end } = await createUrlRunner(dbSource.url);
 
   try {
@@ -338,6 +344,7 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
       if (backfills && backfills.pending > 0) {
         info(`· ${backfills.pending} backfill(s) pending — data jobs run deliberately, never as a sync side effect: everystack db:backfill --apply`);
       }
+      await reportPipelineLastRun(runner);
       console.log('');
       if (!run.converged) {
         fail('NOT converged — fix the findings above and re-run db:sync.');

package/src/cli/commands/deploy.ts

@@ -12,6 +12,7 @@
 
 import { spawn } from 'node:child_process';
 import { step, success, fail, info } from '../output.js';
+import { invalidateCachedConfig } from '../discover.js';
 
 /** The `sst` argv `everystack deploy` runs. Pure, so the mapping is unit-tested. */
 export function buildDeployArgs(flags: Record<string, string>): string[] {
@@ -42,5 +43,8 @@ export async function deployCommand(flags: Record<string, string>): Promise<void
     });
   });
   success(`Deployed stage "${stage}".`);
+  // A deploy can change topology (a new Ops/Worker function, rotated Lambda hashes) that a
+  // stale per-stage cache would shadow — bust it so the next stage command re-discovers live.
+  await invalidateCachedConfig(stage);
   info('Next: `everystack db:migrate --stage ' + stage + '` to apply migrations, `everystack update` to publish the app bundle.');
 }

package/src/cli/commands/pipeline-run.ts

@@ -0,0 +1,269 @@
+/**
+ * `everystack pipeline:run` / `pipeline:list` — reproduce data from committed
+ * source (Phase 3, Brick 2, local-direct).
+ *
+ *   pipeline:run  [--database-url <url>] [--rebuild | --curate]
+ *                 [--only <substr> | --from <id> | --to <id>]
+ *                 [--resume [--run-id <id>]] [--dry-run] [--continue-on-error] [--json]
+ *   pipeline:list [--rebuild | --curate] [--only | --from | --to]
+ *
+ * The orchestrator (topo order, the provenance-lane wall, resume, the memoir)
+ * lives in @everystack/server/pipeline and runs identically here (local, over a
+ * --database-url) and — later, Brick 5 — in the ops Lambda. This command loads
+ * the consumer's pipeline definition (as db:generate loads the models barrel),
+ * builds a transactional runner, and drives runPipeline.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { resolveDbSource, createUrlPipelineRunner, connectingVia, type DbSource } from '../db-source.js';
+import { resolvePipelinePath, PIPELINE_HOMES } from '../pipeline-path.js';
+import { resolveConfig, opsFunction } from '../config.js';
+import { invokeAction } from '../aws.js';
+import { currentGitRef } from '../state-apply.js';
+import { step, success, fail, info, warn } from '../output.js';
+import {
+  loadServerPipeline,
+  type Pipeline,
+  type PipelineLane,
+  type RunPipelineOptions,
+  type PipelineRunOutcome,
+} from '../pipeline-loader.js';
+
+/** --rebuild → rebuild, --curate → curate, neither → all. Both is a contradiction. */
+export function pipelineLaneFromFlags(flags: Record<string, string>): PipelineLane {
+  const rebuild = flags.rebuild === 'true';
+  const curate = flags.curate === 'true';
+  if (rebuild && curate) {
+    throw new Error('--rebuild and --curate are mutually exclusive — a run targets one lane, or omit both to run all in order.');
+  }
+  if (rebuild) return 'rebuild';
+  if (curate) return 'curate';
+  return 'all';
+}
+
+/** Map the CLI flags to the orchestrator's run options (pure; runId injected). */
+export function pipelineRunOptions(flags: Record<string, string>, runId: string): RunPipelineOptions {
+  return {
+    runId,
+    lane: pipelineLaneFromFlags(flags),
+    ...(flags.only ? { only: flags.only } : {}),
+    ...(flags.from ? { from: flags.from } : {}),
+    ...(flags.to ? { to: flags.to } : {}),
+    resume: flags.resume === 'true',
+    dryRun: flags['dry-run'] === 'true',
+    continueOnError: flags['continue-on-error'] === 'true',
+    actor: process.env.USER ?? null,
+    gitRef: currentGitRef(),
+  };
+}
+
+/** Load the consumer's pipeline definition — `pipeline` (or default) from the barrel. */
+export async function loadPipeline(pipelinePath: string): Promise<Pipeline> {
+  const abs = path.resolve(pipelinePath);
+  let mod: any;
+  try {
+    mod = await import(pathToFileURL(abs).href);
+  } catch (err: any) {
+    throw new Error(`Could not load the pipeline from ${pipelinePath}: ${err.message}`);
+  }
+  const pipeline = mod.pipeline ?? mod.default;
+  if (!pipeline || !Array.isArray(pipeline.stages)) {
+    throw new Error(`${pipelinePath} must export a \`pipeline\` built with definePipeline (got ${typeof pipeline}).`);
+  }
+  return pipeline;
+}
+
+function renderOutcome(outcome: PipelineRunOutcome, json: boolean, dryRun: boolean): void {
+  if (json) {
+    console.log(JSON.stringify(outcome, null, 2));
+    return;
+  }
+  if (dryRun) {
+    info(`plan — ${outcome.plan.length} stage(s) in run order:`);
+    for (const id of outcome.plan) info(`  · ${id}`);
+    success('dry run — nothing executed.');
+    return;
+  }
+  for (const r of outcome.results) {
+    if (r.outcome === 'applied') info(`  ✓ ${r.stageId}${r.rows != null ? ` (${r.rows} row(s))` : ''}`);
+    else if (r.outcome === 'skipped') info(`  · ${r.stageId} (skipped)`);
+    else if (r.outcome === 'failed') fail(`  ✗ ${r.stageId}: ${r.error}`);
+  }
+  const applied = outcome.results.filter((r) => r.outcome === 'applied').length;
+  if (outcome.failed) fail('pipeline run FAILED — fix the stage and re-run with --resume.');
+  else success(`pipeline run complete — ${applied} stage(s) applied.`);
+}
+
+/**
+ * Surface the pipeline's most recent run — the analog of the pending-backfill
+ * nudge in db:sync / db:plan. Gated on a pipeline existing (non-pipeline
+ * consumers pay nothing) and best-effort (a missing memoir is silent).
+ */
+export async function reportPipelineLastRun(query: (sql: string) => Promise<any[]>): Promise<void> {
+  if (!PIPELINE_HOMES.some((home) => existsSync(home))) return;
+  try {
+    const { readLastRun } = await loadServerPipeline();
+    const last = await readLastRun(query);
+    if (!last) return;
+    if (last.failed > 0) {
+      warn(`pipeline: last run left ${last.failed} stage(s) failed (${last.failedStages.join(', ')}) — resume: everystack pipeline:run --resume`);
+    } else {
+      info(`· pipeline: last run applied ${last.applied} stage(s)${last.at ? ` at ${last.at}` : ''}.`);
+    }
+  } catch {
+    // Visibility is best-effort — never let it break the schema verb.
+  }
+}
+
+/**
+ * pipeline:run --stage: the orchestrator runs in the ops Lambda, credential-free.
+ * The Lambda owns the bundled pipeline (registered via dbPlugin, like `seed`);
+ * the CLI passes only the run options and renders the outcome. Resume with no
+ * explicit run id is resolved Lambda-side against everystack.pipeline_log.
+ */
+async function pipelineRunViaStage(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  const config = await resolveConfig(flags.stage);
+  const { region } = config;
+  const fn = opsFunction(config);
+
+  const resume = flags.resume === 'true';
+  const dryRun = flags['dry-run'] === 'true';
+  const options: RunPipelineOptions = {
+    // Fresh runs get a client-minted id; resume with no --run-id is resolved
+    // in the Lambda (it reads the latest run on the stage).
+    runId: flags['run-id'] ?? (resume ? '' : randomUUID()),
+    lane: pipelineLaneFromFlags(flags),
+    ...(flags.only ? { only: flags.only } : {}),
+    ...(flags.from ? { from: flags.from } : {}),
+    ...(flags.to ? { to: flags.to } : {}),
+    resume,
+    dryRun,
+    continueOnError: flags['continue-on-error'] === 'true',
+    actor: process.env.USER ?? null,
+    gitRef: currentGitRef(),
+  };
+  // Drop an empty runId so the Lambda's resume resolution kicks in.
+  const payload: Record<string, unknown> = { ...options };
+  if (!payload.runId) delete payload.runId;
+
+  step('Running the pipeline in the ops Lambda (credential-free — no database URL held)...');
+  const outcome: any = await invokeAction(region, fn, 'pipeline:run', payload);
+  if (outcome?.error) {
+    fail(`pipeline:run failed: ${outcome.error}`);
+    process.exit(1);
+  }
+  renderOutcome(outcome as PipelineRunOutcome, flags.json === 'true', dryRun);
+  if (outcome.failed) process.exit(1);
+}
+
+export async function pipelineRunCommand(flags: Record<string, string>): Promise<void> {
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  // Validate the lane before anything.
+  try {
+    pipelineLaneFromFlags(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  // Deployed stage: the orchestrator runs credential-free in the ops Lambda —
+  // no URL held here. The Lambda owns the bundled pipeline; we pass options only.
+  if (dbSource.kind === 'stage') {
+    await pipelineRunViaStage(flags);
+    return;
+  }
+
+  const pipelinePath = resolvePipelinePath(flags.pipeline);
+  let pipeline: Pipeline;
+  try {
+    step(`Loading pipeline from ${pipelinePath}...`);
+    pipeline = await loadPipeline(pipelinePath);
+    info(`${pipeline.stages.length} stage(s).`);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  step(connectingVia(dbSource));
+  const runner = await createUrlPipelineRunner(dbSource.url);
+  try {
+    const { runPipeline, latestRunId } = await loadServerPipeline();
+
+    let runId = flags['run-id'];
+    const resume = flags.resume === 'true';
+    if (!runId) {
+      if (resume) {
+        const latest = await latestRunId(runner.query);
+        if (!latest) {
+          fail('nothing to resume — this pipeline has not run against this database yet.');
+          process.exit(1);
+        }
+        runId = latest;
+        info(`resuming run ${runId.slice(0, 8)}.`);
+      } else {
+        runId = randomUUID();
+      }
+    }
+
+    const options = pipelineRunOptions(flags, runId);
+    if (options.dryRun) info('dry run — computing the plan, executing nothing.');
+    const outcome = await runPipeline(runner, pipeline, options);
+    renderOutcome(outcome, flags.json === 'true', options.dryRun === true);
+    if (outcome.failed) process.exit(1);
+  } catch (err: any) {
+    fail(`pipeline:run failed: ${err.message}`);
+    process.exit(1);
+  } finally {
+    await runner.end();
+  }
+}
+
+export async function pipelineListCommand(flags: Record<string, string>): Promise<void> {
+  const pipelinePath = resolvePipelinePath(flags.pipeline);
+  let pipeline: Pipeline;
+  try {
+    pipeline = await loadPipeline(pipelinePath);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  let lane: PipelineLane;
+  try {
+    lane = pipelineLaneFromFlags(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  const { topoSortStages, selectStages } = await loadServerPipeline();
+  let selected;
+  try {
+    const ordered = topoSortStages(pipeline.stages);
+    selected = selectStages(ordered, {
+      lane,
+      ...(flags.only ? { only: flags.only } : {}),
+      ...(flags.from ? { from: flags.from } : {}),
+      ...(flags.to ? { to: flags.to } : {}),
+    });
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  info(`${selected.length} stage(s) in run order:`);
+  for (const s of selected) {
+    const edges = [...(s.dependsOn ?? []), ...(s.after ?? [])];
+    info(`  ${s.id}  [${s.lane}]${edges.length ? `  ← ${edges.join(', ')}` : ''}${s.heavy ? '  (heavy)' : ''}`);
+  }
+}

package/src/cli/db-source.ts

@@ -10,10 +10,14 @@
  *   the target schema exists only on a local Postgres (migrations applied locally, no
  *   interim deploy), there is no Lambda to ask.
  *
- * Precedence is explicit-over-ambient: `--database-url` beats an explicit `--stage`,
- * which beats an inherited `DATABASE_URL`, which beats the default stage. An explicit
- * `--stage` deliberately wins over the env var so a shell with DATABASE_URL exported
- * still introspects the stage you named.
+ * Precedence is explicit-over-ambient: `--database-url` beats an explicit `--stage`, which beats
+ * an inherited env URL, which beats the default stage. An explicit `--stage` deliberately wins
+ * over the env var so a shell with a URL exported still introspects the stage you named.
+ *
+ * Between the two env credentials, `ADMIN_DATABASE_URL` (the migrator/owner) wins over
+ * `DATABASE_URL` (the least-privilege authenticator). These verbs run DDL — the authenticator
+ * can't — so the CLI's direct path is an operator path. Mirrors the server's
+ * `getAdminDatabaseUrl() ?? getDatabaseUrl()`.
  *
  * The driver is loaded lazily: `postgres` ships with @everystack/server (every deployed
  * consumer has it hoisted), so the deployed path never pays the import and a missing
@@ -23,7 +27,7 @@
 import type { QueryRunner } from './authz-contract.js';
 
 export type DbSource =
-  | { kind: 'url'; url: string; from: 'flag' | 'env' }
+  | { kind: 'url'; url: string; from: 'flag' | 'env' | 'admin-env' }
   | { kind: 'stage' };
 
 /** Decide which path serves this invocation. Pure; env injectable for tests. */
@@ -36,16 +40,26 @@ export function resolveDbSource(
     // parseFlags encodes a value-less flag as 'true'
     if (flagUrl === 'true') {
       throw new Error(
-        '--database-url needs a connection string (or omit the flag and set DATABASE_URL in the environment).',
+        '--database-url needs a connection string (or omit the flag and set ADMIN_DATABASE_URL / DATABASE_URL in the environment).',
       );
     }
     return { kind: 'url', url: flagUrl, from: 'flag' };
   }
   if (flags.stage) return { kind: 'stage' };
+  // Operator/schema verbs run DDL; prefer the admin (migrator/owner) credential over the
+  // least-privilege authenticator, which cannot. Mirrors getAdminDatabaseUrl() ?? getDatabaseUrl().
+  if (env.ADMIN_DATABASE_URL) return { kind: 'url', url: env.ADMIN_DATABASE_URL, from: 'admin-env' };
   if (env.DATABASE_URL) return { kind: 'url', url: env.DATABASE_URL, from: 'env' };
   return { kind: 'stage' };
 }
 
+/** The "Connecting via …" line, honest about which credential source was chosen. */
+export function connectingVia(source: Extract<DbSource, { kind: 'url' }>): string {
+  if (source.from === 'flag') return 'Connecting via --database-url...';
+  if (source.from === 'admin-env') return 'Connecting via ADMIN_DATABASE_URL...';
+  return 'Connecting via DATABASE_URL...';
+}
+
 export interface UrlRunner {
   runner: QueryRunner;
   /** Close the client so the process can exit cleanly. */
@@ -69,9 +83,67 @@ export async function createUrlRunner(
     );
   }
   const postgres = mod.default ?? mod;
-  const sql = postgres(url, { max: 1, onnotice: () => {} });
+  const sql = postgres(url, { max: 1, onnotice: () => {}, ...sslDefaults(url) });
   return {
     runner: async (query: string) => Array.from(await sql.unsafe(query)),
     end: () => sql.end({ timeout: 5 }),
   };
 }
+
+export interface UrlPipelineRunner {
+  query: (sql: string) => Promise<any[]>;
+  transaction: <T>(fn: (tx: (sql: string) => Promise<any[]>) => Promise<T>) => Promise<T>;
+  /** Close the client so the process can exit cleanly. */
+  end: () => Promise<void>;
+}
+
+/**
+ * A pipeline runner over a direct postgres.js connection — the local-direct
+ * path for `pipeline:run`. Unlike the introspection runner it carries a real
+ * `transaction` (postgres.js `sql.begin`), so each stage's writes and its
+ * memoir row commit or roll back together.
+ */
+export async function createUrlPipelineRunner(
+  url: string,
+  load: () => Promise<any> = () => import('postgres'),
+): Promise<UrlPipelineRunner> {
+  let mod: any;
+  try {
+    mod = await load();
+  } catch {
+    throw new Error(
+      'The direct-connection path needs the "postgres" driver. It ships with @everystack/server; in a project without it: pnpm add -D postgres',
+    );
+  }
+  const postgres = mod.default ?? mod;
+  const sql = postgres(url, { max: 1, onnotice: () => {}, ...sslDefaults(url) });
+  return {
+    query: async (query: string) => Array.from(await sql.unsafe(query)),
+    transaction: async (fn) =>
+      sql.begin((tx: any) => fn(async (query: string) => Array.from(await tx.unsafe(query)))),
+    end: () => sql.end({ timeout: 5 }),
+  };
+}
+
+/**
+ * Managed Postgres (RDS / Supabase / Neon) requires TLS — a direct connection without it
+ * is rejected with pg_hba "no encryption". Default `ssl: 'require'` for remote hosts so the
+ * direct-connection path just works, and leave local dev DBs plaintext (they don't serve TLS).
+ * An explicit `?sslmode=` in the URL always wins — postgres.js parses it — so we never override
+ * the operator's choice; we only fill the gap when they said nothing.
+ */
+export function sslDefaults(url: string): { ssl?: 'require' } {
+  let host = '';
+  let hasSslMode = false;
+  try {
+    const u = new URL(url);
+    host = u.hostname;
+    hasSslMode = u.searchParams.has('sslmode');
+  } catch {
+    return {};
+  }
+  const isLocal =
+    host === 'localhost' || host === '127.0.0.1' || host === '::1' || host.endsWith('.local');
+  if (isLocal || hasSslMode) return {};
+  return { ssl: 'require' };
+}