@everystack/cli 0.2.37 → 0.3.0

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

@@ -0,0 +1,83 @@
+/**
+ * `everystack db:pull` — generate `field()` Models from a live database (the brownfield on-ramp).
+ *
+ *   db:pull --stage <name> [--schema public] [--out models/index.ts]
+ *
+ * The reverse of db:generate: that writes migrations FROM Models; this writes Models FROM the
+ * database. It introspects the deployed schema through the read-only ops Lambda `db:query`
+ * action and renders the TypeScript a Model is written in — a starting point you review and
+ * refine (it flags, as inline comments, anything the field builder can't yet express).
+ *
+ * The rendered source is the artifact: it goes to stdout (so `db:pull > models.ts` works) or
+ * to `--out`. Every progress/diagnostic line goes to stderr, so the stdout pipe stays pure
+ * source. The renderer (model-render.ts) is pure; this shell is the IO.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { introspectSchema } from '../schema-introspect.js';
+import { renderModelSource } from '../model-render.js';
+import type { QueryRunner } from '../authz-contract.js';
+import { resolveConfig, opsFunction } from '../config.js';
+import { invokeAction } from '../aws.js';
+import { fail } from '../output.js';
+
+// Progress → stderr, so stdout carries only the rendered source (this command is codegen,
+// not a report — the shared output helpers write to stdout, which would corrupt a redirect).
+const note = (m: string) => console.error(`  > ${m}`);
+const ok = (m: string) => console.error(`  ✓ ${m}`);
+const detail = (m: string) => console.error(`  ${m}`);
+const caution = (m: string) => console.error(`  ! ${m}`);
+
+/** A QueryRunner backed by the ops Lambda `db:query` action (read-only). */
+function lambdaRunner(region: string, fn: string): QueryRunner {
+  return async (sql: string) => {
+    const result: any = await invokeAction(region, fn, 'db:query', { sql });
+    if (result?.error) throw new Error(`Introspection query failed: ${result.error}`);
+    return result?.rows ?? [];
+  };
+}
+
+export async function dbPullCommand(flags: Record<string, string>): Promise<void> {
+  const schema = flags.schema || 'public';
+
+  let current;
+  try {
+    note('Resolving deployed config...');
+    const config = await resolveConfig(flags.stage);
+    detail(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+    note(`Introspecting live database (schema: ${schema})...`);
+    current = await introspectSchema(lambdaRunner(config.region, opsFunction(config)));
+  } catch (err: any) {
+    fail(err.message);
+    detail('Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.');
+    process.exit(1);
+  }
+
+  const pulled = current.tables.filter((t) => t.table.startsWith(`${schema}.`));
+  if (pulled.length === 0) {
+    fail(`No tables found in schema "${schema}".`);
+    process.exit(1);
+  }
+
+  const source = renderModelSource(current, { schema });
+
+  if (flags.out) {
+    const outPath = path.resolve(flags.out);
+    try {
+      await fs.mkdir(path.dirname(outPath), { recursive: true });
+      await fs.writeFile(outPath, source, 'utf8');
+    } catch (err: any) {
+      fail(`Could not write ${flags.out}: ${err.message}`);
+      process.exit(1);
+    }
+    ok(`Wrote ${path.relative(process.cwd(), outPath)} — ${pulled.length} model(s).`);
+  } else {
+    process.stdout.write(source);
+    ok(`Rendered ${pulled.length} model(s) from schema "${schema}" (stdout — redirect or pass --out to save).`);
+  }
+
+  const flagged = (source.match(/\/\/ (FIXME|TODO|composite|CHECK|FK →)/g) ?? []).length;
+  if (flagged) caution(`${flagged} inline comment(s) flag things to review (unmapped types, checks, cross-schema FKs).`);
+  process.exit(0);
+}

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

@@ -0,0 +1,113 @@
+/**
+ * db:snapshot / db:snapshots — RDS *physical* snapshots, the thin `aws rds` control-plane wrapper.
+ *
+ * Unlike db:backup (logical pg_dump, runs in the ops Lambda), these are plain RDS management calls
+ * made directly from the CLI with the operator's IAM — no Lambda, no VPC, no pg_dump layer. They
+ * only apply when the DB is an RDS instance; for any other Postgres, use db:backup. See
+ * docs/plans/db-backup-restore.md.
+ */
+
+import { resolveConfig, type CliConfig } from '../config.js';
+import { createRdsSnapshot, describeRdsSnapshots, type RdsSnapshotSummary } from '../aws.js';
+import { utcStamp } from '../backup.js';
+import { rdsSnapshotIdentifier } from '../rds-snapshot.js';
+import { step, success, fail, info } from '../output.js';
+
+/**
+ * Resolve the RDS DB instance identifier: explicit `--instance` wins, else the deployed
+ * `databaseInstanceId` stack output. A missing or `placeholder` value means the DB isn't RDS (or
+ * the stage is in dev mode) — fail with a pointer to db:backup rather than calling AWS with junk.
+ */
+function resolveInstanceId(config: CliConfig, flags: Record<string, string>): string {
+  const id = flags.instance ?? config.databaseInstanceId;
+  if (!id || id === 'placeholder') {
+    fail(
+      'No RDS instance id available. db:snapshot needs an RDS instance.\n' +
+      '  - If your DB is RDS: redeploy so the `databaseInstanceId` output is present, or pass --instance <id>.\n' +
+      '  - If your DB is not RDS (Aurora, a container, self-hosted): use `everystack db:backup` for a portable logical backup.',
+    );
+    process.exit(1);
+  }
+  return id;
+}
+
+/** Only an authorization failure warrants the IAM hint; other RDS errors (state, quota) don't. */
+function isAccessDenied(err: any): boolean {
+  const name = String(err?.name ?? '');
+  return /AccessDenied|Unauthorized|NotAuthorized/i.test(name);
+}
+
+function fmtSize(gib?: number): string {
+  return gib == null ? '-' : `${gib} GiB`;
+}
+
+function fmtDate(d?: Date): string {
+  return d ? d.toISOString().replace('.000Z', 'Z') : '(creating)';
+}
+
+export async function dbSnapshotCommand(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  let config: CliConfig;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  const instanceId = resolveInstanceId(config, flags);
+  const snapshotId = rdsSnapshotIdentifier(flags.stage ?? 'manual', utcStamp(new Date()));
+
+  info(`Region: ${config.region}, Instance: ${instanceId}`);
+  step(`Creating RDS snapshot ${snapshotId}...`);
+
+  try {
+    const snap = await createRdsSnapshot(config.region, instanceId, snapshotId);
+    success(`Snapshot ${snap.identifier} (${snap.status}) — physical RDS image of ${instanceId}.`);
+    info('It becomes restorable once status is "available". Track it with `everystack db:snapshots`.');
+  } catch (err: any) {
+    fail(`Snapshot failed: ${err.message}`);
+    if (isAccessDenied(err)) {
+      info('Ensure your IAM identity has rds:CreateDBSnapshot on this instance.');
+    } else if (/not currently in the available state|InvalidDBInstanceState/i.test(String(err?.message ?? err?.name))) {
+      info('The instance is busy (another snapshot may be in progress). Wait for it to finish, then retry.');
+    }
+    process.exit(1);
+  }
+}
+
+export async function dbSnapshotsCommand(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  let config: CliConfig;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  const instanceId = resolveInstanceId(config, flags);
+  step(`Listing manual RDS snapshots for ${instanceId}...`);
+
+  let snaps: RdsSnapshotSummary[];
+  try {
+    snaps = await describeRdsSnapshots(config.region, instanceId);
+  } catch (err: any) {
+    fail(`List failed: ${err.message}`);
+    if (isAccessDenied(err)) {
+      info('Ensure your IAM identity has rds:DescribeDBSnapshots.');
+    }
+    process.exit(1);
+  }
+
+  if (snaps.length === 0) {
+    info('No manual snapshots. Create one with `everystack db:snapshot`.');
+    return;
+  }
+
+  for (const s of snaps) {
+    const enc = s.encrypted ? ' [encrypted]' : '';
+    info(`${s.identifier}  ${s.status.padEnd(10)}  ${fmtSize(s.sizeGiB).padEnd(8)}  pg${s.engineVersion ?? '?'}  ${fmtDate(s.created)}${enc}`);
+  }
+  success(`${snaps.length} snapshot${snaps.length === 1 ? '' : 's'}.`);
+}

package/src/cli/commands/db.ts

@@ -9,6 +9,34 @@ import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
 
+/** Secret-store keys that may hold the privileged (operator) connection URL,
+ *  in precedence order. Names vary by deployment; --secret-name overrides. */
+const ADMIN_URL_KEYS = ['ADMIN_DATABASE_URL', 'AdminDatabaseUrl', 'ADMIN_URL'];
+
+/**
+ * Parse a postgres connection URL into psql's PG* environment variables.
+ *
+ * Passing the credential via env (not argv) keeps the password out of the
+ * process table and shell history. Pure and side-effect free — it never logs;
+ * callers must never log the result either (it contains PGPASSWORD).
+ */
+export function pgEnvFromUrl(url: string): Record<string, string> {
+  const u = new URL(url);
+  if (!/^postgres(ql)?:$/.test(u.protocol)) {
+    throw new Error(`Not a postgres connection URL (protocol: ${u.protocol})`);
+  }
+  const env: Record<string, string> = {};
+  if (u.hostname) env.PGHOST = decodeURIComponent(u.hostname);
+  if (u.port) env.PGPORT = u.port;
+  if (u.username) env.PGUSER = decodeURIComponent(u.username);
+  if (u.password) env.PGPASSWORD = decodeURIComponent(u.password);
+  const database = u.pathname.replace(/^\//, '');
+  if (database) env.PGDATABASE = decodeURIComponent(database);
+  const sslmode = u.searchParams.get('sslmode');
+  if (sslmode) env.PGSSLMODE = sslmode;
+  return env;
+}
+
 export async function dbMigrateCommand(flags: Record<string, string>): Promise<void> {
   step('Resolving deployed config...');
   let config;
@@ -115,6 +143,130 @@ export async function dbResetCommand(flags: Record<string, string>): Promise<voi
   }
 }
 
+export async function dbProvisionCommand(flags: Record<string, string>): Promise<void> {
+  if (!flags.stage) {
+    fail('--stage is required for db:provision (it writes the DATABASE_URL secret for that stage)');
+    process.exit(1);
+  }
+
+  step('Resolving deployed config...');
+  let config;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+  info('Creating the least-privilege role chain on your EXISTING database (no database is created).');
+  step('Provisioning roles...');
+
+  // Generate the login password and keep it in memory only — it is written straight into
+  // the secret store and is NEVER printed, logged, or returned to a human.
+  const { randomBytes } = await import('node:crypto');
+  const authPassword = randomBytes(24).toString('hex');
+
+  let result: any;
+  try {
+    result = await invokeAction(config.region, opsFunction(config), 'db:provision', { authPassword });
+  } catch (err: any) {
+    fail(`db:provision failed: ${err.message}`);
+    info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+    process.exit(1);
+  }
+  if (result?.error) {
+    fail(`db:provision failed: ${result.error}`);
+    process.exit(1);
+  }
+  success(`Role chain ready: ${result.loginRole} (LOGIN, NOINHERIT, no BYPASSRLS) → can SET ROLE to ${result.appRoles.join(', ')}`);
+
+  // Resolve host/port/db (not secret) to build the connection string in memory.
+  let conn: any;
+  try {
+    conn = await invokeAction(config.region, opsFunction(config), 'db:psql', {});
+  } catch {
+    /* handled below */
+  }
+  if (!conn?.host) {
+    fail('Could not resolve the database host to build DATABASE_URL.');
+    info('Provide a db:psql connectionInfo callback, or set the DATABASE_URL secret yourself.');
+    process.exit(1);
+  }
+  const url = `postgresql://${result.loginRole}:${authPassword}@${conn.host}:${conn.port ?? 5432}/${conn.database}`;
+
+  // Write the secret directly to the SST secret store — never display it.
+  step('Writing the DATABASE_URL secret (not displayed)...');
+  try {
+    const { loadSstSecrets, putSstSecrets } = await import('../utils/secrets.js');
+    const { parseAppName } = await import('../discover.js');
+    const ctx = { appName: await parseAppName(), stage: flags.stage, region: config.region };
+    const secrets = await loadSstSecrets(ctx);
+    secrets.DATABASE_URL = url;
+    await putSstSecrets(ctx, secrets);
+  } catch (err: any) {
+    fail(`Failed to write the DATABASE_URL secret: ${err.message}`);
+    info('Ensure your IAM role can write the SST secret store (s3:PutObject, kms:Encrypt).');
+    process.exit(1);
+  }
+
+  success(`DATABASE_URL secret set for stage "${flags.stage}" → role ${result.loginRole}. No credential was displayed.`);
+  console.log('');
+  info('Finish the wiring in sst.config.ts (one-time): declare `new sst.Secret("DatabaseUrl")`,');
+  info('link it to the Api function, and remove the raw Postgres component from the Api link');
+  info('(keep it on the ops/worker functions). Then redeploy.');
+  info(`Verify:  everystack db:doctor --stage ${flags.stage}`);
+}
+
+export async function dbDoctorCommand(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  let config;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+  step('Probing database connections (api + operator)...');
+
+  let report: any;
+  try {
+    report = await invokeAction(config.region, opsFunction(config), 'db:doctor', {});
+  } catch (err: any) {
+    fail(`db:doctor failed: ${err.message}`);
+    info('Ensure your IAM user/role has lambda:InvokeFunction permission.');
+    process.exit(1);
+  }
+
+  if (report?.error) {
+    fail(`db:doctor failed: ${report.error}`);
+    process.exit(1);
+  }
+
+  console.log('');
+  info(`api connection (DATABASE_URL):    role=${report.api.role}  superuser=${report.api.isSuperuser}  bypassrls=${report.api.bypassRls}`);
+  info(`operator connection (ADMIN_URL):  role=${report.admin.role}  superuser=${report.admin.isSuperuser}  bypassrls=${report.admin.bypassRls}`);
+  console.log('');
+
+  for (const c of report.checks as Array<{ name: string; status: string; detail: string; remediation?: string }>) {
+    if (c.status === 'pass') success(`${c.name} — ${c.detail}`);
+    else if (c.status === 'warn') warn(`${c.name} — ${c.detail}`);
+    else fail(`${c.name} — ${c.detail}`);
+    if (c.status === 'fail' && c.remediation) info(`    fix: ${c.remediation}`);
+  }
+
+  console.log('');
+  if (report.ok) {
+    success('db:doctor — database is least-privilege and RLS-subject');
+    process.exit(0);
+  } else {
+    fail('db:doctor — the api connection is NOT correctly least-privilege (see failures above)');
+    process.exit(1);
+  }
+}
+
 export async function dbPsqlCommand(flags: Record<string, string>): Promise<void> {
   step('Resolving deployed config...');
   let config;
@@ -180,9 +332,67 @@ export async function dbPsqlCommand(flags: Record<string, string>): Promise<void
     }
   }
 
-  // Interactive mode: not supported for private RDS
-  fail('Interactive psql mode not supported for private RDS instances.');
-  info('Use -c flag to execute SQL queries via Lambda: everystack db:psql -c "SELECT * FROM users;"');
-  info('The Lambda function executes queries from within the VPC where it can reach the database.');
-  process.exit(1);
+  // Interactive mode — break-glass admin psql.
+  //
+  // Authorization IS your AWS identity: resolving the admin URL requires reading
+  // the SST secret store (SSM passphrase + S3 blob + KMS decrypt). If your
+  // profile can't, you don't get a session — the permission is the policy, no
+  // confirmation prompt. CloudTrail records the decrypt, so the access is
+  // audited for free. The URL is resolved in-process and handed to psql via PG*
+  // env vars: it never touches your terminal, argv, clipboard, or psql history.
+  if (!flags.stage) {
+    fail('--stage is required for an interactive session. Example: everystack db:psql --stage production');
+    info('Or run a one-off query via Lambda: everystack db:psql -c "SELECT 1" --stage production');
+    process.exit(1);
+  }
+
+  step('Resolving the admin connection from the secret store...');
+  let secrets: Record<string, string>;
+  try {
+    const { loadSstSecrets } = await import('../utils/secrets.js');
+    const { parseAppName } = await import('../discover.js');
+    const appName = await parseAppName();
+    secrets = await loadSstSecrets({ appName, stage: flags.stage, region: config.region });
+  } catch (err: any) {
+    fail('Could not read the secret store — your AWS profile lacks secrets access.');
+    info('db:psql opens an ADMIN session; it requires SSM + S3 + KMS access to the SST state.');
+    info('If you should have it, check your IAM permissions; otherwise you should not be in psql.');
+    process.exit(1);
+  }
+
+  const keyName = flags['secret-name'] || ADMIN_URL_KEYS.find((k) => secrets[k]);
+  const adminUrl = keyName ? secrets[keyName] : undefined;
+  if (!adminUrl) {
+    fail(`No admin database URL found for stage "${flags.stage}".`);
+    // Names only — never values.
+    info(`Looked for: ${ADMIN_URL_KEYS.join(', ')}. Available secret names: ${Object.keys(secrets).join(', ') || '(none)'}.`);
+    info('Provision one with `everystack db:provision`, or point at an existing key with --secret-name <KEY>.');
+    process.exit(1);
+  }
+
+  let pgEnv: Record<string, string>;
+  try {
+    pgEnv = pgEnvFromUrl(adminUrl);
+  } catch {
+    fail(`The resolved ${keyName} is not a valid postgres connection URL.`);
+    process.exit(1);
+  }
+
+  // Confirm the target (host/user/db are infra identifiers, not the credential);
+  // the password is in PGPASSWORD and is never displayed.
+  success(
+    `Admin psql → ${flags.stage} as ${pgEnv.PGUSER ?? '?'}@${pgEnv.PGHOST ?? '?'}/${pgEnv.PGDATABASE ?? ''} (credential not displayed)`,
+  );
+
+  const { spawn } = await import('node:child_process');
+  const child = spawn('psql', [], { stdio: 'inherit', env: { ...process.env, ...pgEnv } });
+  child.on('error', (err: any) => {
+    if (err.code === 'ENOENT') {
+      fail('psql not found on PATH. Install the PostgreSQL client to use interactive mode.');
+    } else {
+      fail(`Failed to launch psql: ${err.message}`);
+    }
+    process.exit(1);
+  });
+  child.on('close', (code) => process.exit(code ?? 0));
 }

package/src/cli/commands/deploy.ts

@@ -0,0 +1,46 @@
+/**
+ * `everystack deploy` — deploy the stack's infrastructure.
+ *
+ * A thin wrapper over `sst deploy` so a consumer never has to type or know about SST: the
+ * framework owns the infra tool, the consumer just runs `everystack deploy --stage <name>`.
+ * Infra only — migrations (`db:migrate`) and OTA (`update`) stay explicit, the same split
+ * `sst deploy` itself has.
+ *
+ * The arg build is pure (unit-tested); the command streams sst's output through and exits
+ * with its code so CI sees a failed deploy.
+ */
+
+import { spawn } from 'node:child_process';
+import { step, success, fail, info } from '../output.js';
+
+/** The `sst` argv `everystack deploy` runs. Pure, so the mapping is unit-tested. */
+export function buildDeployArgs(flags: Record<string, string>): string[] {
+  const stage = flags.stage || 'dev';
+  return ['sst', 'deploy', '--stage', stage];
+}
+
+export async function deployCommand(flags: Record<string, string>): Promise<void> {
+  const stage = flags.stage || 'dev';
+  const args = buildDeployArgs(flags);
+
+  step(`Deploying stage "${stage}"...`);
+  await new Promise<void>((resolve) => {
+    // `npx` resolves the consumer's local sst (the same way the export step runs expo).
+    const child = spawn('npx', args, { stdio: 'inherit', env: { ...process.env, FORCE_COLOR: '1' } });
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        fail(`Deploy failed (exit ${code}).`);
+        process.exit(code ?? 1);
+      }
+    });
+    child.on('error', (err) => {
+      fail(`Could not run sst: ${err.message}`);
+      info('Install it as a dev dependency: `pnpm add -D sst`.');
+      process.exit(1);
+    });
+  });
+  success(`Deployed stage "${stage}".`);
+  info('Next: `everystack db:migrate --stage ' + stage + '` to apply migrations, `everystack update` to publish the app bundle.');
+}

package/src/cli/commands/logs.ts

@@ -133,6 +133,62 @@ function resolveFunctionForOrigin(
   }
 }
 
+/** One FilterLogEvents page (the subset of the AWS shape this command reads). */
+interface FilterLogEventsPage {
+  events?: Array<{ eventId?: string; timestamp?: number; message?: string }>;
+  nextToken?: string;
+}
+
+/** Carries the tail window across polls so a re-query can't reprint events. */
+export interface TailState {
+  /** Highest event timestamp printed so far. Only moves forward. */
+  lastTimestamp: number;
+  /** eventId → timestamp for events at the boundary millisecond — the only ones
+   *  an inclusive-startTime re-query can return again. Pruned each drain so it
+   *  never grows past one millisecond's worth of events. */
+  seen: Map<string, number>;
+}
+
+/**
+ * Drain one poll's worth of pages, printing only events not seen before and
+ * advancing the window forward.
+ *
+ * The loop bug this fixes: FilterLogEvents `startTime` is INCLUSIVE, so a poll
+ * with `startTime = lastTimestamp` re-returns every event sharing that newest
+ * millisecond. The old code advanced `lastTimestamp` only on a strictly-greater
+ * comparison and never deduped, so the boundary batch reprinted on every 2s poll
+ * forever. Here we dedup by `eventId` and advance to the max timestamp, then
+ * prune `seen` to just the boundary millisecond (the only ids that can recur).
+ *
+ * Exported for unit testing without the AWS SDK or the setTimeout poll loop.
+ */
+export async function drainLogEvents(
+  send: (params: { startTime: number; nextToken?: string }) => Promise<FilterLogEventsPage>,
+  state: TailState,
+  emit: (line: string) => void,
+): Promise<void> {
+  let nextToken: string | undefined;
+  do {
+    const page = await send({ startTime: state.lastTimestamp, nextToken });
+    for (const event of page.events ?? []) {
+      const id = event.eventId;
+      const ts = event.timestamp ?? state.lastTimestamp;
+      if (id && state.seen.has(id)) continue; // already printed this one
+      const timestamp = event.timestamp ? new Date(event.timestamp).toISOString() : '';
+      emit(`[${timestamp}] ${(event.message || '').trimEnd()}`);
+      if (id) state.seen.set(id, ts);
+      if (ts > state.lastTimestamp) state.lastTimestamp = ts;
+    }
+    nextToken = page.nextToken;
+  } while (nextToken);
+
+  // Only events at exactly lastTimestamp can be returned again (startTime is
+  // inclusive); drop everything older so `seen` stays bounded.
+  for (const [id, ts] of state.seen) {
+    if (ts < state.lastTimestamp) state.seen.delete(id);
+  }
+}
+
 export async function logsTailCommand(flags: Record<string, string>): Promise<void> {
   step('Resolving deployed config...');
   let config;
@@ -174,42 +230,20 @@ export async function logsTailCommand(flags: Record<string, string>): Promise<vo
 
     success(`Streaming logs from ${logGroupName}...\n`);
 
-    // Poll for new logs every 2 seconds
-    let nextToken: string | undefined;
-    let lastTimestamp = startTime;
+    // Poll for new logs every 2 seconds. State carries the window + dedup set
+    // across polls — see drainLogEvents for why both are required.
+    const state: TailState = { lastTimestamp: startTime, seen: new Map() };
+    const send = (params: { startTime: number; nextToken?: string }) =>
+      client.send(new FilterLogEventsCommand({
+        logGroupName,
+        startTime: params.startTime,
+        filterPattern,
+        ...(params.nextToken ? { nextToken: params.nextToken } : {}),
+      }));
 
     const poll = async () => {
       try {
-        const params: any = {
-          logGroupName,
-          startTime: lastTimestamp,
-          filterPattern,
-        };
-
-        if (nextToken) {
-          params.nextToken = nextToken;
-        }
-
-        const response = await client.send(new FilterLogEventsCommand(params));
-
-        if (response.events && response.events.length > 0) {
-          for (const event of response.events) {
-            if (event.timestamp && event.timestamp > lastTimestamp) {
-              lastTimestamp = event.timestamp;
-            }
-
-            const timestamp = event.timestamp
-              ? new Date(event.timestamp).toISOString()
-              : '';
-            const message = event.message || '';
-
-            console.log(`[${timestamp}] ${message.trimEnd()}`);
-          }
-        }
-
-        nextToken = response.nextToken;
-
-        // Continue polling
+        await drainLogEvents(send, state, (line) => console.log(line));
         setTimeout(poll, 2000);
       } catch (err: any) {
         if (err.name === 'ResourceNotFoundException') {