@everystack/cli 0.2.18 → 0.2.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.2.18",
+  "version": "0.2.21",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "publishConfig": {
@@ -30,6 +30,14 @@
     "./plugin": {
       "types": "./src/plugin.ts",
       "default": "./src/plugin.ts"
+    },
+    "./env": {
+      "types": "./src/env.ts",
+      "default": "./src/env.ts"
+    },
+    "./sst": {
+      "types": "./src/sst.ts",
+      "default": "./src/sst.ts"
     }
   },
   "bin": {

package/src/cli/aws.ts

@@ -123,13 +123,67 @@ export async function invokeAction(
 
 /**
  * Resolve the CloudWatch log group for a Lambda function.
- * Uses the conventional `/aws/lambda/{functionName}` naming — no IAM call needed.
+ *
+ * First checks if the conventional `/aws/lambda/{functionName}` log group exists.
+ * If not (e.g. SST replaced the function during deploy, changing the hash suffix),
+ * searches for a log group matching the function's base name prefix.
  */
-export function resolveLogGroup(
-  _region: string,
+export async function resolveLogGroup(
+  region: string,
   functionName: string,
-): string {
-  return `/aws/lambda/${functionName}`;
+): Promise<string> {
+  const conventional = `/aws/lambda/${functionName}`;
+
+  const {
+    CloudWatchLogsClient,
+    DescribeLogGroupsCommand,
+  } = await import('@aws-sdk/client-cloudwatch-logs');
+
+  const client = new CloudWatchLogsClient({ region });
+
+  // Fast path: conventional name exists
+  try {
+    const res = await client.send(
+      new DescribeLogGroupsCommand({
+        logGroupNamePrefix: conventional,
+        limit: 1,
+      }),
+    );
+    if (res.logGroups?.some(lg => lg.logGroupName === conventional)) {
+      return conventional;
+    }
+  } catch {
+    // Fall through to prefix search
+  }
+
+  // SST names functions like {app}-{stage}-{ResourceName}{Random}-{hash}.
+  // After deploy, the hash changes but the base prefix stays the same.
+  // Strip the final -{hash} segment and search by prefix.
+  const lastDash = functionName.lastIndexOf('-');
+  if (lastDash > 0) {
+    const basePrefix = `/aws/lambda/${functionName.slice(0, lastDash)}`;
+    try {
+      const res = await client.send(
+        new DescribeLogGroupsCommand({
+          logGroupNamePrefix: basePrefix,
+          limit: 5,
+        }),
+      );
+      if (res.logGroups?.length) {
+        // Return the most recently created matching log group
+        const sorted = res.logGroups
+          .filter(lg => lg.logGroupName)
+          .sort((a, b) => (b.creationTime || 0) - (a.creationTime || 0));
+        if (sorted.length > 0) {
+          return sorted[0].logGroupName!;
+        }
+      }
+    } catch {
+      // Fall through to conventional name
+    }
+  }
+
+  return conventional;
 }
 
 /**

package/src/cli/commands/diag.ts

@@ -25,10 +25,7 @@ interface DiagResult {
   cacheStatus?: string;
   cacheAge?: string;
   cacheControl?: string;
-  bundleKey?: string;
-  updateId?: string;
-  runtimeVersion?: string;
-  releaseCreated?: string;
+  serverDebug?: string;
 }
 
 interface Manifest {
@@ -38,13 +35,6 @@ interface Manifest {
   storagePrefix?: string;
 }
 
-function extractStoragePrefix(bundleKey: string): string | null {
-  // Bundle key format: releases/{branch}/{version}/{groupId}/{platform}/bundle.tar.br
-  // Storage prefix:    releases/{branch}/{version}/{groupId}
-  const match = bundleKey.match(/^(.+)\/web\/bundle\.tar\.br$/);
-  return match?.[1] ?? null;
-}
-
 export async function diagCommand(
   positionalUrl: string | undefined,
   flags: Record<string, string>,
@@ -95,10 +85,7 @@ export async function diagCommand(
       cacheStatus: response.headers.get('x-cache') ?? undefined,
       cacheAge: response.headers.get('age') ?? undefined,
       cacheControl: response.headers.get('cache-control') ?? undefined,
-      bundleKey: response.headers.get('x-bundle-key') ?? undefined,
-      updateId: response.headers.get('x-update-id') ?? undefined,
-      runtimeVersion: response.headers.get('x-runtime-version') ?? undefined,
-      releaseCreated: response.headers.get('x-release-created') ?? undefined,
+      serverDebug: response.headers.get('x-server-debug') ?? undefined,
     };
 
     // Fetch full HTML if hydration analysis requested
@@ -148,20 +135,10 @@ export async function diagCommand(
   }
 
   // Served release info
-  if (diag.bundleKey) {
-    console.log(`  Bundle Key:       ${diag.bundleKey}`);
-  }
-  if (diag.updateId) {
-    console.log(`  Update ID:        ${diag.updateId}`);
-  }
-  if (diag.runtimeVersion) {
-    console.log(`  Runtime Version:  ${diag.runtimeVersion}`);
-  }
-  if (diag.releaseCreated) {
-    console.log(`  Release Created:  ${diag.releaseCreated}`);
-  }
-  if (!diag.bundleKey && !diag.updateId) {
-    warn('  No release headers found. Update @everystack/server to get version headers on SSR responses.');
+  if (diag.serverDebug) {
+    console.log(`  Serving Release:  ${diag.serverDebug}`);
+  } else {
+    warn('  No X-Server-Debug header found. Update @everystack/server to get release timestamp on SSR responses.');
   }
   console.log('');
 
@@ -191,27 +168,15 @@ export async function diagCommand(
   // 4. Version comparison
   if (!manifest) {
     warn('  Cannot compare: no manifest available.');
-  } else if (diag.updateId && manifest.updateId) {
-    // Primary comparison: updateId
-    if (diag.updateId === manifest.updateId) {
+  } else if (diag.serverDebug && manifest.createdAt) {
+    if (diag.serverDebug === manifest.createdAt) {
       success('  Version match: serving the latest release');
     } else {
-      fail(`  Version mismatch: serving ${diag.updateId}, latest is ${manifest.updateId}`);
+      fail(`  Version mismatch: serving ${diag.serverDebug}, latest is ${manifest.createdAt}`);
       info('  Run `everystack cache:purge --origin web` to bust the CDN cache.');
     }
-  } else if (diag.bundleKey && manifest.storagePrefix) {
-    // Fallback comparison: storagePrefix from bundle key
-    const servedPrefix = extractStoragePrefix(diag.bundleKey);
-    if (servedPrefix && servedPrefix === manifest.storagePrefix) {
-      success('  Version match: serving the latest release (matched via bundle key)');
-    } else if (servedPrefix) {
-      fail(`  Version mismatch: serving ${servedPrefix}, latest is ${manifest.storagePrefix}`);
-      info('  Run `everystack cache:purge --origin web` to bust the CDN cache.');
-    } else {
-      warn('  Cannot determine served version from bundle key.');
-    }
   } else {
-    warn('  Cannot compare: missing version headers. Update @everystack/server to emit release metadata.');
+    warn('  Cannot compare: missing X-Server-Debug header or manifest timestamp.');
   }
 
   console.log('');

package/src/cli/commands/secrets.ts

@@ -13,8 +13,11 @@
  * Requires IAM permissions: ssm:GetParameter, s3:GetObject, s3:PutObject, kms:Decrypt.
  */
 
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import { step, success, fail, info, warn } from '../output.js';
 import { loadSstSecrets, putSstSecrets } from '../utils/secrets.js';
+import { parseDotenv, serializeDotenv } from '../utils/dotenv.js';
 
 interface SecretsContext {
   appName: string;
@@ -112,6 +115,101 @@ async function removeSecret(ctx: SecretsContext, name: string): Promise<void> {
   success(`${name} removed from stage "${ctx.stage}"`);
 }
 
+// ---------------------------------------------------------------------------
+// Import
+// ---------------------------------------------------------------------------
+
+async function importSecrets(
+  ctx: SecretsContext,
+  filePath: string,
+  flags: Record<string, string>,
+): Promise<void> {
+  step(`Importing secrets from ${filePath}...`);
+
+  let content: string;
+  try {
+    content = await fs.readFile(path.resolve(filePath), 'utf8');
+  } catch (err: any) {
+    if (err.code === 'ENOENT') {
+      fail(`File not found: ${filePath}`);
+    } else {
+      fail(`Could not read file: ${err.message}`);
+    }
+    process.exit(1);
+  }
+
+  const parsed = parseDotenv(content);
+  const parsedCount = Object.keys(parsed).length;
+
+  if (parsedCount === 0) {
+    warn(`No secrets found in ${filePath}`);
+    return;
+  }
+
+  let merged: Record<string, string>;
+
+  if (flags.replace === 'true') {
+    // Replace mode: parsed entries become the entire secrets map
+    const existing = await loadSstSecrets(ctx);
+    const existingCount = Object.keys(existing).length;
+    if (existingCount > 0) {
+      warn(`Replacing all ${existingCount} existing secret(s)`);
+    }
+    merged = parsed;
+  } else {
+    // Merge mode (default): add new keys, overwrite matching keys, preserve the rest
+    const existing = await loadSstSecrets(ctx);
+    const existingKeys = new Set(Object.keys(existing));
+    let updated = 0;
+    for (const key of Object.keys(parsed)) {
+      if (existingKeys.has(key)) updated++;
+    }
+    merged = { ...existing, ...parsed };
+    const newCount = parsedCount - updated;
+    const detail = updated > 0 ? ` (${newCount} new, ${updated} updated)` : '';
+    await putSstSecrets(ctx, merged);
+    success(`${parsedCount} secret(s) imported to stage "${ctx.stage}"${detail}`);
+    return;
+  }
+
+  await putSstSecrets(ctx, merged);
+  success(`${parsedCount} secret(s) imported to stage "${ctx.stage}"`);
+}
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+
+async function exportSecrets(ctx: SecretsContext, filePath: string | undefined): Promise<void> {
+  if (filePath) {
+    step(`Exporting secrets from ${ctx.appName}/${ctx.stage}...`);
+  }
+
+  const secrets = await loadSstSecrets(ctx);
+  const count = Object.keys(secrets).length;
+
+  if (count === 0) {
+    warn('No secrets to export');
+    return;
+  }
+
+  const serialized = serializeDotenv(secrets);
+
+  if (filePath) {
+    const resolved = path.resolve(filePath);
+    try {
+      await fs.writeFile(resolved, serialized, 'utf8');
+    } catch (err: any) {
+      fail(`Could not write file: ${err.message}`);
+      process.exit(1);
+    }
+    success(`${count} secret(s) exported to ${filePath}`);
+  } else {
+    // Stdout mode: raw output, pipeable
+    process.stdout.write(serialized);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Command entry point
 // ---------------------------------------------------------------------------
@@ -174,6 +272,23 @@ export async function secretsCommand(
         break;
       }
 
+      case 'import': {
+        const filePath = positionalArgs[0];
+        if (!filePath) {
+          fail('Missing file path');
+          info('Usage: everystack secrets import <file> --stage <stage> [--replace]');
+          process.exit(1);
+        }
+        await importSecrets(ctx, filePath, flags);
+        break;
+      }
+
+      case 'export': {
+        const filePath = positionalArgs[0]; // optional — stdout if omitted
+        await exportSecrets(ctx, filePath);
+        break;
+      }
+
       default:
         fail(`Unknown secrets subcommand: ${subcommand}`);
         printSecretsHelp();
@@ -195,12 +310,21 @@ Usage:
   everystack secrets get  <name>       --stage <name>    Print a secret value
   everystack secrets set  <name> <value> --stage <name>  Set or update a secret
   everystack secrets remove <name>     --stage <name>    Delete a secret
+  everystack secrets import <file>     --stage <name>    Import secrets from .env file (merge)
+  everystack secrets export [file]     --stage <name>    Export secrets to .env file (or stdout)
 
 Examples:
   everystack secrets list --stage production
   everystack secrets set MAPBOX_API_KEY "pk.abc123" --stage production
   everystack secrets get JWT_SECRET --stage dev
   everystack secrets remove OLD_KEY --stage dev
+  everystack secrets import .env.production --stage production
+  everystack secrets import .env --stage dev --replace
+  everystack secrets export --stage dev > .env.local
+  everystack secrets export secrets.env --stage production
+
+Flags:
+  --replace   (import only) Replace all secrets instead of merging
 
 Interop:
   Secrets are stored in the SST Ion S3 state backend with AES-256-GCM encryption.

package/src/cli/commands/update.ts

@@ -17,7 +17,6 @@ export interface UpdateFlags {
   branch?: string;
   message?: string;
   platform?: string;
-  environment?: string;
   export?: string;
 }
 
@@ -28,18 +27,13 @@ export async function updateCommand(flags: UpdateFlags & Record<string, string>)
   // (e.g. localhost overrides → LAN IP) to leak into the manifest.
   process.env.EVERYSTACK_UPDATE = '1';
 
-  // Resolve ENVIRONMENT before app.config.js evaluation so the manifest
-  // snapshots the correct API URLs and feature flags for the target.
-  // Priority: --environment flag > eas.json channel match > existing env.
-  if (flags.environment) {
-    process.env.ENVIRONMENT ||= flags.environment;
-  } else if (!process.env.ENVIRONMENT) {
-    // Derive ENVIRONMENT from eas.json by matching --channel to a build profile.
-    // EAS profiles define ENVIRONMENT in their env blocks (e.g. production → "production").
-    const channel = flags.channel || flags.branch || flags.stage || 'production';
-    const easEnv = resolveEasEnvironment(channel);
-    if (easEnv) {
-      process.env.ENVIRONMENT = easEnv;
+  // stage === environment. Set ENVIRONMENT before app.config.js evaluation
+  // so the manifest snapshots the correct API URLs and feature flags.
+  // --stage is the canonical source; fall back to --channel/--branch.
+  if (!process.env.ENVIRONMENT) {
+    const stage = flags.stage || flags.channel || flags.branch;
+    if (stage) {
+      process.env.ENVIRONMENT = stage;
     }
   }
 
@@ -61,9 +55,9 @@ export async function updateCommand(flags: UpdateFlags & Record<string, string>)
     }
 
     // Inject SST secrets into process.env so app.config.js / Metro can read them.
-    // The CLI injects ALL secrets — the app's deny-by-default filter (e.g.
-    // expo-secrets.config.js) is the security boundary that gates what reaches
-    // the bundle. This avoids requiring `sst shell` in deploy scripts.
+    // The CLI injects ALL secrets — @everystack/cli/env is the deny-by-default
+    // filter that gates what reaches the bundle (see env.config.js tiers).
+    // This avoids requiring `sst shell` in deploy scripts.
     try {
       const { parseAppName } = await import('../discover.js');
       const appName = await parseAppName();
@@ -619,40 +613,6 @@ async function createArchive(sourceDir: string, archivePath: string): Promise<vo
   await tarExit;
 }
 
-/**
- * Read eas.json and find ENVIRONMENT for a given channel.
- * Matches --channel to a build profile's `channel` field, then reads
- * ENVIRONMENT from that profile's env block. Falls back to profile name
- * match (e.g. --channel production matches the "production" profile).
- * @internal Exported for testing.
- */
-export function resolveEasEnvironment(channel: string, cwd?: string): string | undefined {
-  try {
-    const easPath = path.resolve(cwd || process.cwd(), 'eas.json');
-    // Synchronous read — runs once before export, performance irrelevant.
-    const eas = JSON.parse(require('fs').readFileSync(easPath, 'utf8'));
-    const profiles = eas?.build;
-    if (!profiles || typeof profiles !== 'object') return undefined;
-
-    // First pass: match on explicit channel field
-    for (const [, profile] of Object.entries(profiles)) {
-      const p = profile as any;
-      if (p?.channel === channel && p?.env?.ENVIRONMENT) {
-        return p.env.ENVIRONMENT;
-      }
-    }
-
-    // Second pass: match on profile name (e.g. "production" profile for --channel production)
-    if (profiles[channel]?.env?.ENVIRONMENT) {
-      return profiles[channel].env.ENVIRONMENT;
-    }
-
-    return undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 /**
  * Extract expo-router SSR flags from the resolved app config.
  * Checks the plugins array for the expo-router entry.

package/src/cli/discover.ts

@@ -145,7 +145,7 @@ export async function discoverFunction(
   } = await import('@aws-sdk/client-lambda');
 
   const client = new LambdaClient({ region });
-  const needle = `${prefix}${resourceName}-`.toLowerCase();
+  const needle = `${prefix}${resourceName}`.toLowerCase();
 
   let marker: string | undefined;
 
@@ -259,7 +259,9 @@ export async function discoverConfig(
     discoverLambda(region, prefix),
     discoverBuckets(region, prefix),
     discoverFunction(region, prefix, 'ImageFunction').catch(() => undefined),
-    discoverFunction(region, prefix, 'WorkerFunction').catch(() => undefined),
+    discoverFunction(region, prefix, 'WorkerFunction')
+      .then(fn => fn || discoverFunction(region, prefix, 'JobsSubscriber'))
+      .catch(() => undefined),
   ]);
 
   // Distribution discovery is best-effort (not critical for most CLI operations)

package/src/cli/index.ts

@@ -167,8 +167,8 @@ function printHelp() {
 everystack - CLI for Expo apps on everystack
 
 Usage:
-  everystack update            --branch <name> --message <msg> [--platform ios|android|web|all] [--stage <name>] [--environment <name>] [--skip-export]
-  everystack update            --channel <name> --message <msg> [--platform ios|android|web|all] [--stage <name>] [--environment <name>] [--skip-export]
+  everystack update            --branch <name> --message <msg> [--platform ios|android|web|all] [--stage <name>] [--skip-export]
+  everystack update            --channel <name> --message <msg> [--platform ios|android|web|all] [--stage <name>] [--skip-export]
   everystack db:migrate        [--stage <name>]  Run database migrations on deployed Lambda
   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)
@@ -196,6 +196,8 @@ Usage:
   everystack secrets get       <name> --stage <name>                Print a secret value
   everystack secrets set       <name> <value> --stage <name>        Set or update a secret
   everystack secrets remove    <name> --stage <name>                Delete a secret
+  everystack secrets import    <file> --stage <name> [--replace]    Import secrets from .env file
+  everystack secrets export    [file] --stage <name>                Export secrets to .env format
 
 Stage resolution:
   --stage <name>  Discover AWS resources for the given stage by querying AWS APIs.
@@ -204,8 +206,7 @@ Stage resolution:
 
   Without --stage, reads .sst/outputs.json (written by the last \`sst deploy\`).
 
-  --environment <name>  Set ENVIRONMENT for app.config.js evaluation (e.g. development, staging, production).
-                        Use this when your SST stage name differs from your EAS build profile name.
+  --stage also sets ENVIRONMENT for app.config.js evaluation. stage === environment.
 
 Auth:
   All commands use AWS IAM credentials (default credential chain).

package/src/cli/utils/dotenv.ts

@@ -0,0 +1,105 @@
+/**
+ * Pure .env parser and serializer. No dependencies.
+ *
+ * Supports:
+ *   KEY=value
+ *   KEY="double quoted value"
+ *   KEY='single quoted value'
+ *   # comments (full-line)
+ *   Empty/whitespace-only lines (skipped)
+ *   export KEY=value (optional prefix)
+ *   Escape sequences in double quotes: \n, \r, \t, \\, \"
+ *   UTF-8 BOM stripping
+ */
+
+/**
+ * Parse a .env-formatted string into key-value pairs.
+ * Duplicate keys: last one wins.
+ */
+export function parseDotenv(content: string): Record<string, string> {
+  const result: Record<string, string> = {};
+
+  // Strip UTF-8 BOM
+  const clean = content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
+
+  for (const rawLine of clean.split('\n')) {
+    const line = rawLine.trim();
+
+    // Skip empty lines and comments
+    if (!line || line.startsWith('#')) continue;
+
+    // Strip optional `export ` prefix
+    const stripped = line.startsWith('export ') ? line.slice(7) : line;
+
+    // Find first `=`
+    const eqIndex = stripped.indexOf('=');
+    if (eqIndex === -1) continue;
+
+    const key = stripped.slice(0, eqIndex).trim();
+    if (!key) continue;
+
+    let value = stripped.slice(eqIndex + 1);
+
+    if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+      // Double-quoted: strip quotes and process escapes
+      value = value.slice(1, -1);
+      // Process escapes — use a single pass to avoid double-expansion
+      value = value.replace(/\\([nrt"\\])/g, (_, ch) => {
+        switch (ch) {
+          case 'n': return '\n';
+          case 'r': return '\r';
+          case 't': return '\t';
+          case '"': return '"';
+          case '\\': return '\\';
+          default: return ch;
+        }
+      });
+    } else if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+      // Single-quoted: strip quotes, literal (no escape processing)
+      value = value.slice(1, -1);
+    } else {
+      // Unquoted: trim whitespace
+      value = value.trim();
+    }
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+/**
+ * Serialize a key-value map to .env format.
+ *
+ * Keys are sorted alphabetically for deterministic output.
+ * Values are double-quoted when they contain whitespace, quotes, #, backslashes, or newlines.
+ */
+export function serializeDotenv(secrets: Record<string, string>): string {
+  const keys = Object.keys(secrets).sort();
+  if (keys.length === 0) return '';
+
+  const lines: string[] = [];
+
+  for (const key of keys) {
+    const value = secrets[key];
+
+    if (needsQuoting(value)) {
+      const escaped = value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+      lines.push(`${key}="${escaped}"`);
+    } else {
+      lines.push(`${key}=${value}`);
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+function needsQuoting(value: string): boolean {
+  if (value === '') return true;
+  return /[\s"'#\\]/.test(value) || value.includes('\n');
+}

package/src/env.ts

@@ -0,0 +1,181 @@
+/**
+ * @everystack/cli/env — Deny-by-default environment variable filtering.
+ *
+ * One import in app.config.js. Auto-discovers env.config.js.
+ * Detects build surface, filters secrets by tier, sets EXPO_PUBLIC_* vars.
+ *
+ * Usage:
+ *   const { extra } = require('@everystack/cli/env').load();
+ *   module.exports = { expo: { extra } };
+ *
+ * With explicit config path:
+ *   const { extra } = require('@everystack/cli/env').load({ path: './env.config' });
+ *
+ * Multiple stages. Four buckets. One gate. One file.
+ *
+ * @module
+ */
+
+import path from 'path';
+import fs from 'fs';
+
+/**
+ * Environment tier configuration.
+ *
+ * Each key is declared in exactly one tier:
+ * - server:  Lambda runtime only. NEVER in any client bundle.
+ * - build:   CI/build tooling only (source maps, etc). NEVER in any client bundle.
+ * - mobile:  Native binary (iOS/Android). Excluded from web bundles.
+ * - web:     Safe for all client bundles. Gets EXPO_PUBLIC_* for web delivery.
+ */
+export interface EnvConfig {
+  /** Lambda/server secrets. NEVER in any client bundle. */
+  server?: string[];
+  /** CI/build-time only. NEVER in any client bundle. */
+  build?: string[];
+  /** Native binary only. Excluded from web bundles. */
+  mobile?: string[];
+  /** Safe for all client bundles. Gets EXPO_PUBLIC_* for web delivery. */
+  web?: string[];
+}
+
+/** Build surface — determines which tiers pass through the filter. */
+export type Surface = 'local' | 'native' | 'web';
+
+/**
+ * Detect the current build surface from environment signals.
+ *
+ * EAS_BUILD / EAS_BUILD_PLATFORM  -> native (EAS native build)
+ * EAS_UPDATE                      -> native (EAS OTA update)
+ * EVERYSTACK_UPDATE               -> web    (everystack update)
+ * none of the above               -> local  (pnpm dev)
+ */
+export function detectSurface(): Surface {
+  if (process.env.EAS_BUILD || process.env.EAS_BUILD_PLATFORM || process.env.EAS_UPDATE) {
+    return 'native';
+  }
+  if (process.env.EVERYSTACK_UPDATE) {
+    return 'web';
+  }
+  return 'local';
+}
+
+/**
+ * Load env config from a file path or auto-discover env.config.js in cwd.
+ */
+export function loadEnvConfig(configPath?: string): EnvConfig {
+  const resolved = configPath
+    ? path.resolve(configPath)
+    : findEnvConfig();
+
+  // Synchronous require — same pattern used throughout the CLI package.
+  // Works in Metro (CJS interop), tsx (SST), and Node CJS.
+  delete require.cache?.[resolved];
+  const mod = require(resolved);
+  return mod.default || mod;
+}
+
+/**
+ * Auto-discover env.config.js in the current working directory.
+ */
+function findEnvConfig(): string {
+  const name = 'env.config.js';
+  const fullPath = path.resolve(process.cwd(), name);
+  if (fs.existsSync(fullPath)) {
+    return fullPath;
+  }
+  throw new Error(
+    'No env.config.js found. Create one:\n\n'
+    + '  module.exports = {\n'
+    + '    server: [],\n'
+    + '    build: [],\n'
+    + '    mobile: [],\n'
+    + '    web: [],\n'
+    + '  };\n'
+  );
+}
+
+/**
+ * Filter process.env through tier allowlists based on the detected surface.
+ *
+ * Deny-by-default: undeclared keys are dropped.
+ * Server and build tiers are NEVER passed through, even if duplicated in other tiers.
+ *
+ * Surface behavior:
+ *   local  -> web + mobile tiers pass
+ *   native -> web + mobile tiers pass
+ *   web    -> web tier only
+ */
+export function filterEnv(surface: Surface, config: EnvConfig): Record<string, string> {
+  // Build the allowlist: web tier always passes
+  const allowed = new Set(config.web || []);
+
+  // Mobile tier: passes on native and local, blocked on web
+  if (surface !== 'web') {
+    for (const k of (config.mobile || [])) {
+      allowed.add(k);
+    }
+  }
+
+  // server and build tiers are NEVER added to the allowlist.
+  // Actively remove them in case a key appears in multiple tiers.
+  const blocked = new Set([
+    ...(config.server || []),
+    ...(config.build || []),
+  ]);
+  for (const k of blocked) {
+    allowed.delete(k);
+  }
+
+  // Collect values for allowed keys from process.env
+  const result: Record<string, string> = {};
+  for (const key of allowed) {
+    if (process.env[key] !== undefined) {
+      result[key] = process.env[key]!;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Set EXPO_PUBLIC_* process.env vars for web delivery.
+ *
+ * Constants.expoConfig.extra does NOT work on web — Metro never sets
+ * APP_MANIFEST, so Constants.expoConfig is null in the browser. The only
+ * way to deliver env values to web client code is via EXPO_PUBLIC_* vars,
+ * which Metro inlines as literal strings at compile time.
+ *
+ * Sets EXPO_PUBLIC_* for ALL filtered keys so consumers can use either
+ * delivery path (extra on native, EXPO_PUBLIC_* on web).
+ */
+export function setExpoPublicVars(filtered: Record<string, string>): void {
+  for (const [key, value] of Object.entries(filtered)) {
+    process.env[`EXPO_PUBLIC_${key}`] = value;
+  }
+}
+
+/**
+ * Load and filter environment variables for the current build surface.
+ *
+ * Auto-discovers env.config.js in the current working directory,
+ * or accepts an explicit path. Detects the build surface, filters
+ * process.env through the tier allowlists, sets EXPO_PUBLIC_* vars,
+ * and returns the filtered object for expo.extra.
+ *
+ * @example
+ * // app.config.js — auto-discover env.config.js
+ * const { extra } = require('@everystack/cli/env').load();
+ * module.exports = { expo: { extra } };
+ *
+ * @example
+ * // app.config.js — explicit path
+ * const { extra } = require('@everystack/cli/env').load({ path: './env.config' });
+ */
+export function load(options?: { path?: string }): { extra: Record<string, string> } {
+  const config = loadEnvConfig(options?.path);
+  const surface = detectSurface();
+  const filtered = filterEnv(surface, config);
+  setExpoPublicVars(filtered);
+  return { extra: filtered };
+}

package/src/sst.ts

@@ -0,0 +1,15 @@
+/**
+ * @everystack/cli/sst — Shared env config for SST infrastructure.
+ *
+ * Reads the same env.config.js that @everystack/cli/env uses,
+ * ensuring sst.config.ts and app.config.js stay in sync.
+ *
+ * Usage in sst.config.ts:
+ *   import { loadEnvConfig } from '@everystack/cli/sst';
+ *   const env = loadEnvConfig();
+ *   // env.server = ['DATABASE_URL', 'JWT_SECRET']
+ *
+ * @module
+ */
+
+export { loadEnvConfig, type EnvConfig } from './env.js';