@everystack/cli 0.2.27 → 0.2.29

package/README.md

@@ -132,6 +132,22 @@ everystack update \
 
 This bundles your app, uploads assets to storage, creates a release record, and signs the manifest.
 
+Media assets configured in `app.config.js` under `extra.everystack.assets` are fingerprinted with 8-char content hashes (e.g., `logo.png` → `logo-a1b2c3d4.png`) and synced to the media bucket. A `media-manifest.json` mapping logical names to fingerprinted paths is written to the bucket root. Stale fingerprinted files from previous deploys are pruned automatically.
+
+```javascript
+// app.config.js
+extra: {
+  everystack: {
+    assets: [
+      { from: 'server/email/assets', to: 'email/', include: '*.{png,jpg}' },
+      { from: 'assets/og', to: 'og/' },
+    ],
+  },
+}
+```
+
+Use `@everystack/server/media` to resolve fingerprinted URLs at runtime in SSR, email templates, and workers.
+
 ### Code Signing
 
 Generate RSA key pair for manifest signing:
@@ -164,6 +180,24 @@ everystack db:psql --stage dev          # Open a psql session via Lambda
 
 `db:migrate` and `db:seed` dispatch to your Lambda's `onAction` handler. `db:psql` proxies a PostgreSQL session through the Lambda, so your database credentials never leave AWS.
 
+### Interactive Console
+
+```bash
+everystack console --stage dev          # Connect to deployed database
+everystack console --stage dev --sandbox  # Sandbox mode: rolls back after each expression
+```
+
+A REPL connected to your deployed database with `db`, `schema`, and `eq`/`and`/`or` helpers in scope. Supports multiline input, persistent history, and tab completion.
+
+**Dot commands:**
+- `.tables` / `.schema [table]` — Inspect database schema
+- `.login` — Authenticate with email/password (hidden input)
+- `.user` — Show current auth context
+- `.logout` — Clear auth context
+- `.sandbox` — Toggle sandbox mode
+
+After `.login`, queries run with RLS policies applied via `pgSettings`. The `current_user` variable is available in scope. Passwords are redacted from history.
+
 ## Client: React Native
 
 ### UpdatesProvider

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.2.27",
+  "version": "0.2.29",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/cli/aws.ts

@@ -96,6 +96,51 @@ export async function getFromS3(
   }
 }
 
+export async function listS3(
+  region: string,
+  bucket: string,
+  prefix?: string,
+): Promise<string[]> {
+  const client = await getS3(region);
+  const { ListObjectsV2Command } = await import('@aws-sdk/client-s3');
+  const keys: string[] = [];
+  let continuationToken: string | undefined;
+  do {
+    const response = await client.send(new ListObjectsV2Command({
+      Bucket: bucket,
+      ...(prefix && { Prefix: prefix }),
+      ContinuationToken: continuationToken,
+    }));
+    if (response.Contents) {
+      for (const obj of response.Contents) {
+        if (obj.Key) keys.push(obj.Key);
+      }
+    }
+    continuationToken = response.IsTruncated ? response.NextContinuationToken : undefined;
+  } while (continuationToken);
+  return keys;
+}
+
+export async function deleteS3(
+  region: string,
+  bucket: string,
+  keys: string[],
+): Promise<void> {
+  if (keys.length === 0) return;
+  const client = await getS3(region);
+  const { DeleteObjectsCommand } = await import('@aws-sdk/client-s3');
+  for (let i = 0; i < keys.length; i += 1000) {
+    const batch = keys.slice(i, i + 1000);
+    await client.send(new DeleteObjectsCommand({
+      Bucket: bucket,
+      Delete: {
+        Objects: batch.map(key => ({ Key: key })),
+        Quiet: true,
+      },
+    }));
+  }
+}
+
 export async function invokeAction(
   region: string,
   functionName: string,

package/src/cli/commands/console.ts

@@ -1,25 +1,187 @@
 /**
- * everystack console --stage <name>
+ * everystack console --stage <name> [--sandbox]
  *
  * Interactive REPL that executes expressions inside the deployed Lambda.
  * Each line is sent via IAM-authed Lambda invoke (_action: 'console').
- * The Lambda evaluates with db, schema, and Drizzle operators in scope.
+ * The Lambda evaluates with db, schema, Drizzle operators, and models in scope.
+ *
+ * Supports multiline input (bracket balancing), persistent history,
+ * dot commands (.tables, .columns, .rpc, .scope, .help, .clear),
+ * auth context (login/asUser/logout with pgSettings), and sandbox mode
+ * (--sandbox rolls back all changes after each expression).
  */
 
 import * as readline from 'node:readline';
-import { resolveConfig } from '../config.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { resolveConfig, type CliConfig } from '../config.js';
 import { invokeAction } from '../aws.js';
 import { success, fail, info } from '../output.js';
 import { formatResult } from '../utils/table.js';
+import { isComplete } from '../utils/bracket-counter.js';
+import { createCompleter } from '../utils/completer.js';
+
+const HISTORY_DIR = path.join(os.homedir(), '.everystack');
+const HISTORY_FILE = path.join(HISTORY_DIR, 'console_history');
+const HISTORY_MAX = 1000;
+
+// ─── Dot Command Formatting ─────────────────────────────────────────────────
+
+/** Format .tables output: comma-separated model names. */
+export function formatTables(meta: ConsoleMeta): string {
+  return meta.tables.map(t => t.name).join(', ');
+}
+
+/** Format .columns <Table> output: one column per line. */
+export function formatColumns(meta: ConsoleMeta, tableName: string): string {
+  const table = meta.tables.find(
+    t => t.name.toLowerCase() === tableName.toLowerCase(),
+  );
+  if (!table) {
+    const available = meta.tables.map(t => t.name).join(', ');
+    return `Unknown table: ${tableName}. Available: ${available}`;
+  }
+  return table.columns
+    .map(c => {
+      const flags: string[] = [];
+      if (c.primaryKey) flags.push('pk');
+      if (c.notNull && !c.primaryKey) flags.push('not null');
+      if (c.hasDefault) flags.push('default');
+      const suffix = flags.length ? `, ${flags.join(', ')}` : '';
+      return `  ${c.property} (${c.type}${suffix})`;
+    })
+    .join('\n');
+}
+
+/** Format .rpc output: comma-separated rpc names. */
+export function formatRpc(meta: ConsoleMeta): string {
+  if (meta.rpcNames.length === 0) return 'No RPCs registered';
+  return meta.rpcNames.join(', ');
+}
+
+/** Format .scope output: comma-separated scope variable names. */
+export function formatScope(meta: ConsoleMeta): string {
+  return meta.scope.join(', ');
+}
+
+/** Format .user output: current auth context. */
+export function formatUser(user: Record<string, unknown> | null): string {
+  if (!user) return 'No user context. Use .login or asUser(id) to authenticate.';
+  return Object.entries(user).map(([k, v]) => `  ${k}: ${JSON.stringify(v)}`).join('\n');
+}
+
+/** Format .help output. */
+export function formatHelp(): string {
+  return [
+    '  .tables            List all model names',
+    '  .columns <Table>   Show columns for a table',
+    '  .rpc               List registered RPC functions',
+    '  .scope             List all variables in scope',
+    '  .login             Log in with hidden password prompt',
+    '  .user              Show current auth context',
+    '  .logout            Clear auth context',
+    '  .clear             Clear the terminal',
+    '  .exit              Exit the console',
+    '',
+    '  Auth: asUser(id), current_user, logout()',
+  ].join('\n');
+}
+
+interface ConsoleMeta {
+  tables: Array<{
+    name: string;
+    dbName: string;
+    columns: Array<{
+      name: string;
+      property: string;
+      type: string;
+      notNull: boolean;
+      hasDefault: boolean;
+      primaryKey: boolean;
+    }>;
+  }>;
+  rpcNames: string[];
+  scope: string[];
+}
+
+// ─── Password Prompt ────────────────────────────────────────────────────────
+
+/** Prompt for a value with output suppressed (password entry). */
+export function questionHidden(
+  rl: readline.Interface,
+  prompt: string,
+): Promise<string> {
+  return new Promise((resolve) => {
+    const output = (rl as any).output as NodeJS.WritableStream;
+    const origWrite = output.write.bind(output);
+    let promptShown = false;
+
+    (output as any).write = function (str: string, ...args: any[]) {
+      if (!promptShown) {
+        promptShown = true;
+        return origWrite(str, ...args);
+      }
+      // Suppress echo of password characters
+      return true;
+    };
+
+    rl.question(prompt, (answer) => {
+      (output as any).write = origWrite;
+      origWrite('\n');
+      resolve(answer);
+    });
+  });
+}
+
+/** Redact password arguments in login() calls for history storage. */
+export function redactLogin(expression: string): string {
+  // Match login('email', 'password') or login("email", "password")
+  return expression.replace(
+    /(login\s*\([^,]+,\s*)(['"`]).*?\2(\s*\))/g,
+    "$1$2***$2$3",
+  );
+}
+
+// ─── History ─────────────────────────────────────────────────────────────────
+
+/** Load history from disk, truncating to HISTORY_MAX lines. */
+function loadHistory(): string[] {
+  try {
+    const content = fs.readFileSync(HISTORY_FILE, 'utf8');
+    const lines = content.split('\n').filter(Boolean);
+    if (lines.length > HISTORY_MAX) {
+      const trimmed = lines.slice(-HISTORY_MAX);
+      fs.writeFileSync(HISTORY_FILE, trimmed.join('\n') + '\n');
+      return trimmed;
+    }
+    return lines;
+  } catch {
+    return [];
+  }
+}
+
+/** Append a single expression to the history file. */
+function appendHistory(expression: string): void {
+  try {
+    fs.mkdirSync(HISTORY_DIR, { recursive: true });
+    fs.appendFileSync(HISTORY_FILE, expression + '\n');
+  } catch {
+    // Non-critical — don't let history IO break the REPL
+  }
+}
+
+// ─── Console Command ─────────────────────────────────────────────────────────
 
 export async function consoleCommand(flags: Record<string, string>): Promise<void> {
   const stage = flags.stage;
+  const sandbox = flags.sandbox !== undefined;
   if (!stage) {
     fail('--stage is required. Example: everystack console --stage dev');
     process.exit(1);
   }
 
-  let config;
+  let config: CliConfig;
   try {
     config = await resolveConfig(stage);
   } catch (err: any) {
@@ -28,33 +190,256 @@ export async function consoleCommand(flags: Record<string, string>): Promise<voi
   }
 
   success(`Connected to ${stage} (${config.region}) — ${config.apiFunctionName}`);
-  console.log('  Type expressions to evaluate. Ctrl+C or .exit to quit.\n');
+  if (sandbox) {
+    info('Sandbox mode: all changes will be rolled back after each expression.');
+  }
+  console.log('  Type expressions to evaluate. .help for commands. Ctrl+C or .exit to quit.\n');
+
+  const continuationPrompt = '... ';
+  const history = loadHistory();
+
+  const buffer: string[] = [];
+  let cachedMeta: ConsoleMeta | null = null;
+  let currentUser: Record<string, unknown> | null = null;
+
+  /** Build prompt string based on auth and sandbox state. */
+  function getPrompt(): string {
+    const suffix = sandbox ? '(sandbox)> ' : '> ';
+    if (currentUser) {
+      const label = (currentUser.email as string)?.split('@')[0]
+        ?? (currentUser.sub as string)?.slice(0, 8)
+        ?? '?';
+      return `everystack:${stage}[${label}]${suffix}`;
+    }
+    return `everystack:${stage}${suffix}`;
+  }
+
+  /** Fetch and cache console metadata from Lambda. */
+  async function getMeta(): Promise<ConsoleMeta> {
+    if (cachedMeta) return cachedMeta;
+    cachedMeta = await invokeAction(
+      config.region,
+      config.apiFunctionName,
+      'console:meta',
+      {},
+    ) as ConsoleMeta;
+    return cachedMeta;
+  }
+
+  const completer = createCompleter(async () => {
+    try { return await getMeta(); } catch { return null; }
+  });
 
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout,
-    prompt: `everystack:${stage}> `,
-  });
+    prompt: getPrompt(),
+    history,
+    historySize: HISTORY_MAX,
+    completer,
+  } as readline.ReadLineOptions);
 
   rl.prompt();
 
-  rl.on('line', async (line) => {
+  /**
+   * Handle a dot command. Returns true if the line was a dot command
+   * (even if it was unrecognized), false if it should be treated as code.
+   */
+  async function handleDotCommand(line: string): Promise<boolean> {
     const trimmed = line.trim();
-    if (!trimmed) { rl.prompt(); return; }
-    if (trimmed === '.exit') { rl.close(); return; }
+    if (!trimmed.startsWith('.') || trimmed.startsWith('..')) return false;
+
+    const parts = trimmed.split(/\s+/);
+    const cmd = parts[0].toLowerCase();
+    const arg = parts[1];
+
+    switch (cmd) {
+      case '.exit':
+        rl.close();
+        return true;
+
+      case '.clear':
+        process.stdout.write('\x1B[2J\x1B[0f');
+        rl.prompt();
+        return true;
+
+      case '.help':
+        console.log(formatHelp());
+        rl.prompt();
+        return true;
+
+      case '.tables': {
+        try {
+          const meta = await getMeta();
+          console.log(formatTables(meta));
+        } catch (err: any) {
+          fail(err.message);
+        }
+        rl.prompt();
+        return true;
+      }
+
+      case '.columns': {
+        if (!arg) {
+          fail('Usage: .columns <TableName>');
+          rl.prompt();
+          return true;
+        }
+        try {
+          const meta = await getMeta();
+          console.log(formatColumns(meta, arg));
+        } catch (err: any) {
+          fail(err.message);
+        }
+        rl.prompt();
+        return true;
+      }
+
+      case '.rpc': {
+        try {
+          const meta = await getMeta();
+          console.log(formatRpc(meta));
+        } catch (err: any) {
+          fail(err.message);
+        }
+        rl.prompt();
+        return true;
+      }
+
+      case '.scope': {
+        try {
+          const meta = await getMeta();
+          console.log(formatScope(meta));
+        } catch (err: any) {
+          fail(err.message);
+        }
+        rl.prompt();
+        return true;
+      }
+
+      case '.login': {
+        const email = await new Promise<string>((resolve) => {
+          rl.question('  Email: ', resolve);
+        });
+        if (!email.trim()) {
+          fail('Email is required');
+          rl.setPrompt(getPrompt());
+          rl.prompt();
+          return true;
+        }
+        const password = await questionHidden(rl, '  Password: ');
+        if (!password) {
+          rl.setPrompt(getPrompt());
+          rl.prompt();
+          return true;
+        }
+        try {
+          const loginPayload: Record<string, unknown> = {
+            expression: `await login(${JSON.stringify(email.trim())}, ${JSON.stringify(password)})`,
+          };
+          if (currentUser) loginPayload.user = currentUser;
+          if (sandbox) loginPayload.sandbox = true;
+
+          const loginResult: any = await invokeAction(
+            config.region,
+            config.apiFunctionName,
+            'console',
+            loginPayload,
+          );
+          if (loginResult?._auth !== undefined) {
+            currentUser = loginResult._auth.user;
+          }
+          if (loginResult?.error) {
+            fail(loginResult.error);
+          } else {
+            console.log(formatResult(loginResult?.result));
+          }
+        } catch (err: any) {
+          fail(err.message);
+        }
+        rl.setPrompt(getPrompt());
+        rl.prompt();
+        return true;
+      }
+
+      case '.user':
+        console.log(formatUser(currentUser));
+        rl.prompt();
+        return true;
+
+      case '.logout':
+        currentUser = null;
+        rl.setPrompt(getPrompt());
+        info('Logged out');
+        rl.prompt();
+        return true;
+
+      default:
+        if (trimmed.startsWith('.')) {
+          fail(`Unknown command: ${cmd}. Type .help for available commands.`);
+          rl.prompt();
+          return true;
+        }
+        return false;
+    }
+  }
+
+  rl.on('line', async (line) => {
+    // Empty line: if buffer is empty just re-prompt, otherwise keep it (preserves formatting)
+    if (!line.trim() && buffer.length === 0) {
+      rl.prompt();
+      return;
+    }
+
+    // Dot commands only when not in multiline mode
+    if (buffer.length === 0 && line.trim().startsWith('.')) {
+      const handled = await handleDotCommand(line);
+      if (handled) return;
+    }
+
+    buffer.push(line);
+    const joined = buffer.join('\n');
+
+    if (!isComplete(joined)) {
+      rl.setPrompt(continuationPrompt);
+      rl.prompt();
+      return;
+    }
+
+    // Expression is complete — send it
+    const expression = joined.trim();
+    buffer.length = 0;
+    rl.setPrompt(getPrompt());
+
+    if (!expression) {
+      rl.prompt();
+      return;
+    }
 
     try {
+      const payload: Record<string, unknown> = { expression };
+      if (currentUser) payload.user = currentUser;
+      if (sandbox) payload.sandbox = true;
+
       const result: any = await invokeAction(
         config.region,
         config.apiFunctionName,
         'console',
-        { expression: trimmed },
+        payload,
       );
+
+      // Handle auth side-channel (login/asUser/logout signals)
+      if (result?._auth !== undefined) {
+        currentUser = result._auth.user;
+        rl.setPrompt(getPrompt());
+      }
+
       if (result?.error) {
         fail(result.error);
       } else {
         console.log(formatResult(result?.result));
       }
+      appendHistory(redactLogin(expression));
     } catch (err: any) {
       fail(err.message);
     }

package/src/cli/commands/update.ts

@@ -6,12 +6,23 @@ import { pipeline } from 'node:stream/promises';
 import { createWriteStream } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { resolveConfig, type CliConfig } from '../config.js';
-import { uploadToS3, headS3, invokeAction } from '../aws.js';
+import { uploadToS3, headS3, listS3, deleteS3, invokeAction } from '../aws.js';
 import { step, success, warn, fail, info } from '../output.js';
 import { exportApp } from '../utils/export.js';
 import { walkDirectory } from '../utils/walk.js';
 import { loadSstSecrets } from '../utils/secrets.js';
 
+/**
+ * Embed an 8-char content hash in a filename for cache busting.
+ * `logo.png` + data → `logo-a1b2c3d4.png`
+ */
+export function fingerprintPath(relativePath: string, data: Buffer): string {
+  const hash8 = crypto.createHash('md5').update(data).digest('hex').slice(0, 8);
+  const ext = path.extname(relativePath);
+  const base = ext ? relativePath.slice(0, -ext.length) : relativePath;
+  return `${base}-${hash8}${ext}`;
+}
+
 export interface UpdateFlags {
   channel?: string;
   branch?: string;
@@ -410,7 +421,7 @@ export async function updateCommand(flags: UpdateFlags & Record<string, string>)
         }
       }
 
-      // 3.5. Sync media assets to the media bucket (email logos, OG images, etc.)
+      // 3.5. Sync fingerprinted media assets to the media bucket (email logos, OG images, etc.)
       const assetDirs: Array<{ from: string; to: string; include?: string }> | undefined =
         appConfig.extra?.everystack?.assets;
       if (assetDirs?.length) {
@@ -426,6 +437,7 @@ export async function updateCommand(flags: UpdateFlags & Record<string, string>)
           const MEDIA_CONCURRENCY = 10;
           let mediaUploaded = 0;
           let mediaSkipped = 0;
+          const manifestFiles: Record<string, string> = {};
 
           for (const { from: fromDir, to: toPrefix, include } of assetDirs) {
             const absFrom = path.resolve(fromDir);
@@ -445,13 +457,17 @@ export async function updateCommand(flags: UpdateFlags & Record<string, string>)
             for (let i = 0; i < files.length; i += MEDIA_CONCURRENCY) {
               const batch = files.slice(i, i + MEDIA_CONCURRENCY);
               await Promise.all(batch.map(async (file) => {
-                const s3Key = `${toPrefix}${file.relativePath}`;
                 const data = Buffer.from(file.data, 'base64');
+                const fingerprinted = fingerprintPath(file.relativePath, data);
+                const logicalKey = `${toPrefix}${file.relativePath}`;
+                const s3Key = `${toPrefix}${fingerprinted}`;
 
-                // Compare MD5 against S3 ETag for diffing
-                const md5 = `"${crypto.createHash('md5').update(data).digest('hex')}"`;
+                manifestFiles[logicalKey] = s3Key;
+
+                // Fingerprinted key encodes the content hash — if it exists, content is identical
                 const existing = await headS3(config.region, config.mediaBucket!, s3Key);
-                if (existing?.etag === md5) {
+                if (existing) {
+                  info(`  ${logicalKey} → ${s3Key} (unchanged)`);
                   mediaSkipped++;
                   return;
                 }
@@ -464,11 +480,40 @@ export async function updateCommand(flags: UpdateFlags & Record<string, string>)
                   file.contentType,
                   'public, max-age=31536000, immutable',
                 );
+                info(`  ${logicalKey} → ${s3Key}`);
                 mediaUploaded++;
               }));
             }
           }
 
+          // Write manifest (no-cache so CDN always revalidates)
+          const manifest = {
+            version: 1,
+            generatedAt: new Date().toISOString(),
+            files: manifestFiles,
+          };
+          await uploadToS3(
+            config.region,
+            config.mediaBucket!,
+            'media-manifest.json',
+            Buffer.from(JSON.stringify(manifest, null, 2)),
+            'application/json',
+            'no-cache',
+          );
+
+          // Prune stale fingerprinted files
+          const FINGERPRINT_RE = /-[0-9a-f]{8}\.[^.]+$/;
+          const allKeys = await listS3(config.region, config.mediaBucket!);
+          const currentValues = new Set(Object.values(manifestFiles));
+          currentValues.add('media-manifest.json');
+          const staleKeys = allKeys.filter(key =>
+            FINGERPRINT_RE.test(key) && !currentValues.has(key)
+          );
+          if (staleKeys.length > 0) {
+            await deleteS3(config.region, config.mediaBucket!, staleKeys);
+            info(`Pruned ${staleKeys.length} stale media asset(s)`);
+          }
+
           if (mediaUploaded > 0 || mediaSkipped > 0) {
             success(`Media: ${mediaUploaded} new, ${mediaSkipped} unchanged (skipped)`);
           }

package/src/cli/index.ts

@@ -173,7 +173,7 @@ Usage:
   everystack db:seed           [--stage <name>]  Seed database on deployed Lambda (dev only)
   everystack db:reset          [--stage <name>]  Drop all schemas + re-run migrations (dev only)
   everystack db:psql           [--stage <name>] -c <command>  Execute SQL query via Lambda (private RDS)
-  everystack console           --stage <name>    Interactive REPL on deployed Lambda
+  everystack console           --stage <name> [--sandbox]  Interactive REPL on deployed Lambda
   everystack certs:generate    [--output ./certs]
   everystack certs:configure   [--input ./certs] [--keyid main]
   everystack cache:purge       [--stage <name>]                  Bust all cached content (global epoch)

package/src/cli/utils/bracket-counter.ts

@@ -0,0 +1,124 @@
+/**
+ * Bracket counter for multiline REPL input.
+ *
+ * Determines whether a code string has balanced brackets, accounting for
+ * string literals (single, double, template), escape sequences, template
+ * expression nesting, and comments (line + block).
+ */
+
+/**
+ * Returns `true` when all brackets/parens/braces are balanced and all
+ * strings and comments are closed. Used by the console REPL to decide
+ * whether to send or continue accumulating lines.
+ */
+export function isComplete(code: string): boolean {
+  let parens = 0;   // ()
+  let braces = 0;   // {}
+  let brackets = 0; // []
+
+  // Template literal depth: when we hit ` outside a string we push 0;
+  // when inside a template and we hit ${ we push the current brace depth;
+  // when we close a brace back to that depth we pop and resume the template.
+  const templateStack: number[] = [];
+
+  let inSingle = false;
+  let inDouble = false;
+  let inTemplate = false;
+  let inLineComment = false;
+  let inBlockComment = false;
+
+  for (let i = 0; i < code.length; i++) {
+    const ch = code[i];
+    const next = code[i + 1];
+
+    // --- Line comment: skip to end of line ---
+    if (inLineComment) {
+      if (ch === '\n') inLineComment = false;
+      continue;
+    }
+
+    // --- Block comment: skip to */ ---
+    if (inBlockComment) {
+      if (ch === '*' && next === '/') {
+        inBlockComment = false;
+        i++; // skip /
+      }
+      continue;
+    }
+
+    // --- Inside single-quoted string ---
+    if (inSingle) {
+      if (ch === '\\') { i++; continue; } // skip escaped char
+      if (ch === "'") inSingle = false;
+      continue;
+    }
+
+    // --- Inside double-quoted string ---
+    if (inDouble) {
+      if (ch === '\\') { i++; continue; }
+      if (ch === '"') inDouble = false;
+      continue;
+    }
+
+    // --- Inside template literal ---
+    if (inTemplate) {
+      if (ch === '\\') { i++; continue; }
+      if (ch === '$' && next === '{') {
+        // Enter template expression — push current brace depth as marker
+        templateStack.push(braces);
+        braces++;
+        inTemplate = false;
+        i++; // skip {
+        continue;
+      }
+      if (ch === '`') {
+        inTemplate = false;
+      }
+      continue;
+    }
+
+    // --- Normal code context ---
+
+    // Comment detection (before string detection — // and /* aren't strings)
+    if (ch === '/' && next === '/') {
+      inLineComment = true;
+      i++; // skip second /
+      continue;
+    }
+    if (ch === '/' && next === '*') {
+      inBlockComment = true;
+      i++; // skip *
+      continue;
+    }
+
+    // String openers
+    if (ch === "'") { inSingle = true; continue; }
+    if (ch === '"') { inDouble = true; continue; }
+    if (ch === '`') { inTemplate = true; continue; }
+
+    // Brackets
+    if (ch === '(') parens++;
+    else if (ch === ')') parens--;
+    else if (ch === '[') brackets++;
+    else if (ch === ']') brackets--;
+    else if (ch === '{') braces++;
+    else if (ch === '}') {
+      braces--;
+      // Check if we're closing a template expression
+      if (templateStack.length > 0 && braces === templateStack[templateStack.length - 1]) {
+        templateStack.pop();
+        inTemplate = true; // back inside the template literal
+      }
+    }
+  }
+
+  return (
+    parens === 0 &&
+    braces === 0 &&
+    brackets === 0 &&
+    !inSingle &&
+    !inDouble &&
+    !inTemplate &&
+    !inBlockComment
+  );
+}

package/src/cli/utils/completer.ts

@@ -0,0 +1,154 @@
+/**
+ * Tab completion for the everystack console REPL.
+ *
+ * Completion sources (in priority order):
+ * 1. Dot commands: `.tables`, `.columns`, `.help`, etc.
+ * 2. Model methods: `Users.whe` → `Users.where(`
+ * 3. Chain methods: `.where({}).ord` → `.where({}).orderBy(`
+ * 4. RPC names: `rpc.forg` → `rpc.forgot_password(`
+ * 5. Scope variables: `Use` → `Users`, `sch` → `schema`
+ */
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const DOT_COMMANDS = ['.tables', '.columns', '.rpc', '.scope', '.login', '.user', '.logout', '.help', '.clear', '.exit'];
+
+const MODEL_METHODS = ['find(', 'where(', 'all()', 'first()', 'last()', 'count()', 'table'];
+const CHAIN_METHODS = ['where(', 'orderBy(', 'limit(', 'offset(', 'first()', 'last()', 'count()', 'all()'];
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+interface ConsoleMeta {
+  tables: Array<{ name: string; dbName: string; columns: Array<{ property: string }> }>;
+  rpcNames: string[];
+  scope: string[];
+}
+
+// ─── Token Extraction ───────────────────────────────────────────────────────
+
+/**
+ * Extract the completable token from the end of a line.
+ *
+ * Returns `{ prefix, token }` where:
+ * - `prefix` is everything before the token (for reinsertion)
+ * - `token` is the fragment the user is typing
+ *
+ * Splits on characters that can't appear in identifiers or member access:
+ * space, `(`, `)`, `[`, `]`, `{`, `}`, `,`, `;`, `=`, `+`, `-`, `*`, `/`, `!`, `<`, `>`, `?`, `:`, `&`, `|`, `~`, `^`, `%`
+ *
+ * Preserves `.` in the token so we can detect member access (e.g. `Users.whe`).
+ */
+export function extractToken(line: string): { prefix: string; token: string } {
+  // Walk backwards from end, collecting identifier chars and dots
+  let i = line.length - 1;
+  while (i >= 0) {
+    const ch = line[i];
+    if (/[a-zA-Z0-9_.$]/.test(ch)) {
+      i--;
+    } else {
+      break;
+    }
+  }
+  const start = i + 1;
+  return {
+    prefix: line.slice(0, start),
+    token: line.slice(start),
+  };
+}
+
+// ─── Completion Logic ───────────────────────────────────────────────────────
+
+/**
+ * Generate completions for a given line and cursor position.
+ *
+ * Returns `[completions, token]` in the format readline expects:
+ * - `completions`: full replacement strings for the token
+ * - `token`: the text being completed (readline uses this for display)
+ */
+export function getCompletions(
+  line: string,
+  meta: ConsoleMeta | null,
+): [string[], string] {
+  const trimmed = line.trimStart();
+
+  // 1. Dot commands (only at start of line)
+  if (trimmed.startsWith('.') && !trimmed.includes(' ') && !trimmed.includes('(')) {
+    const matches = DOT_COMMANDS.filter(c => c.startsWith(trimmed));
+    return [matches, trimmed];
+  }
+
+  // No meta yet — can't complete anything else
+  if (!meta) return [[], ''];
+
+  const { prefix, token } = extractToken(line);
+
+  // 2. Member access: `something.partial`
+  const dotIdx = token.lastIndexOf('.');
+  if (dotIdx >= 0) {
+    const obj = token.slice(0, dotIdx);
+    const partial = token.slice(dotIdx + 1);
+
+    // rpc.name completions
+    if (obj === 'rpc' || obj.endsWith('.rpc')) {
+      const rpcCompletions = meta.rpcNames
+        .filter(name => name.startsWith(partial))
+        .map(name => `${obj}.${name}(`);
+      return [rpcCompletions, token];
+    }
+
+    // Model method completions (e.g. Users.whe → Users.where()
+    const isModel = meta.tables.some(t => t.name === obj);
+    if (isModel) {
+      const matches = MODEL_METHODS
+        .filter(m => m.startsWith(partial))
+        .map(m => `${obj}.${m}`);
+      return [matches, token];
+    }
+
+    // Chain method completions after closing paren/bracket
+    // e.g. `).ord` or generic `something.meth`
+    const matches = CHAIN_METHODS
+      .filter(m => m.startsWith(partial))
+      .map(m => `${obj}.${m}`);
+    if (matches.length > 0) return [matches, token];
+  }
+
+  // 3. Bare word — scope variables
+  if (token.length > 0) {
+    const matches = meta.scope
+      .filter(s => s.startsWith(token))
+      .sort();
+    return [matches, token];
+  }
+
+  return [[], ''];
+}
+
+// ─── Readline Completer Factory ─────────────────────────────────────────────
+
+/**
+ * Create a readline-compatible completer function.
+ *
+ * The `getMeta` callback lazily fetches and caches console metadata.
+ * If meta isn't available yet, completions degrade gracefully (dot commands only).
+ */
+export function createCompleter(
+  getMeta: () => Promise<ConsoleMeta | null>,
+): (line: string, callback: (err: null, result: [string[], string]) => void) => void {
+  let cachedMeta: ConsoleMeta | null = null;
+  let metaFetched = false;
+
+  return (line: string, callback: (err: null, result: [string[], string]) => void) => {
+    if (!metaFetched) {
+      metaFetched = true;
+      getMeta().then(meta => {
+        cachedMeta = meta;
+        callback(null, getCompletions(line, cachedMeta));
+      }).catch(() => {
+        callback(null, getCompletions(line, null));
+      });
+    } else {
+      callback(null, getCompletions(line, cachedMeta));
+    }
+  };
+}