@everystack/cli 0.1.0

package/README.md

@@ -0,0 +1,255 @@
+# @everystack/cli
+
+CLI and OTA updates for Expo apps on everystack. Database management (`db:migrate`, `db:seed`), OTA publishing, Expo Updates protocol (v0/v1), pluggable storage, RSA-SHA256 code signing, and channels.
+
+## Install
+
+```bash
+pnpm add @everystack/cli drizzle-orm structured-headers
+```
+
+For S3 storage:
+
+```bash
+pnpm add @aws-sdk/client-s3
+```
+
+## Entry Points
+
+| Import | Description |
+|--------|-------------|
+| `@everystack/cli` | Server: handler, storage adapters |
+| `@everystack/cli/client` | Client: UpdatesProvider, AppStateUpdateProvider |
+| `@everystack/cli/schema` | Drizzle tables (channels, releases, assets) |
+
+## Server: Handler
+
+Creates a Web Standard handler implementing the Expo Updates manifest protocol:
+
+```typescript
+import { createUpdatesHandler, createStorage } from '@everystack/cli';
+import { db } from './db';
+
+const storage = createStorage({
+  type: 'filesystem',
+  directory: './updates',
+});
+
+const handler = createUpdatesHandler({
+  db,
+  storage,
+  baseUrl: 'https://myapp.com',
+  basePath: '/api/updates',
+  defaultChannel: 'production',
+  auth: {
+    verifyToken: async (token) => verifyJWT(token),
+  },
+  privateKey: process.env.CODE_SIGNING_PRIVATE_KEY, // PEM for RSA-SHA256
+});
+```
+
+### Mounting
+
+```typescript
+// app/api/updates/[...path]+api.ts
+export function GET(request: Request) { return handler(request); }
+export function POST(request: Request) { return handler(request); }
+```
+
+### Handler Endpoints
+
+The handler serves:
+- **Manifest requests** — Expo Updates protocol v0/v1 manifest responses with multipart/mixed format
+- **Asset downloads** — Binary assets from your configured storage
+- **Publish endpoint** — Authenticated upload of new releases (used by the CLI)
+
+### Handler Options
+
+```typescript
+interface UpdatesHandlerOptions {
+  db: DrizzleDb;                // Drizzle instance
+  storage: StorageAdapter;      // Filesystem or S3
+  baseUrl: string;              // Public URL (for asset references in manifests)
+  basePath?: string;            // URL prefix to strip
+  auth?: {
+    verifyToken: (token: string) => Promise<Record<string, unknown> | null>;
+  };
+  privateKey?: string;          // PEM for RSA-SHA256 code signing
+  defaultChannel?: string;      // Default channel (default: 'production')
+}
+```
+
+## Storage Adapters
+
+### Filesystem
+
+```typescript
+import { createStorage } from '@everystack/cli';
+
+const storage = createStorage({
+  type: 'filesystem',
+  directory: './updates',
+});
+```
+
+### S3
+
+```typescript
+const storage = createStorage({
+  type: 's3',
+  bucket: 'my-updates-bucket',
+  region: 'us-east-1',
+  endpoint: 'https://s3.us-east-1.amazonaws.com', // Optional
+});
+```
+
+### Custom Adapter
+
+Implement the `StorageAdapter` interface:
+
+```typescript
+interface StorageAdapter {
+  put(key: string, data: Buffer | Uint8Array, contentType?: string): Promise<void>;
+  get(key: string): Promise<{ data: Buffer; contentType: string } | null>;
+  exists(key: string): Promise<boolean>;
+  list(prefix: string): Promise<string[]>;
+  delete(key: string): Promise<void>;
+}
+```
+
+## CLI
+
+Publish updates, manage certificates, and channels from the command line.
+
+### Publish an Update
+
+```bash
+everystack update \
+  --channel production \
+  --message "Fix login bug" \
+  --platform ios          # ios | android | web | all (default: all)
+```
+
+This bundles your app, uploads assets to storage, creates a release record, and signs the manifest.
+
+### Code Signing
+
+Generate RSA key pair for manifest signing:
+
+```bash
+everystack certs:generate --output ./certs
+# Creates ./certs/private-key.pem and ./certs/certificate.pem
+
+everystack certs:configure --input ./certs --keyid main
+# Configures your app to use the generated certificates
+```
+
+### Channel Management
+
+```bash
+everystack channels list
+everystack channels create --name staging
+everystack channels create --name production
+```
+
+### Database Management
+
+These commands invoke your Lambda function directly via IAM (no database credentials exposed):
+
+```bash
+everystack db:migrate                   # Run Drizzle migrations
+everystack db:seed                      # Seed database (dev only)
+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.
+
+## Client: React Native
+
+### UpdatesProvider
+
+Wraps your app to check for and apply OTA updates:
+
+```tsx
+import { UpdatesProvider } from '@everystack/cli/client';
+
+function App() {
+  return (
+    <UpdatesProvider
+      url="https://myapp.com/api/updates"
+      channel="production"
+      checkInterval={60000} // Check every 60 seconds
+      onUpdateAvailable={(update) => {
+        // Optional: prompt user or auto-apply
+        console.log('Update available:', update.message);
+      }}
+      onUpdateApplied={() => {
+        console.log('Update applied, restarting...');
+      }}
+    >
+      <MyApp />
+    </UpdatesProvider>
+  );
+}
+```
+
+### AppStateUpdateProvider
+
+Checks for updates when the app returns from background:
+
+```tsx
+import { AppStateUpdateProvider } from '@everystack/cli/client';
+
+function App() {
+  return (
+    <AppStateUpdateProvider url="https://myapp.com/api/updates" channel="production">
+      <MyApp />
+    </AppStateUpdateProvider>
+  );
+}
+```
+
+## Schema
+
+Add the updates tables to your Drizzle migrations:
+
+```typescript
+import { channels, releases, assets } from '@everystack/cli/schema';
+```
+
+Tables:
+- **channels** — Named release channels (production, staging, etc.)
+- **releases** — Published update bundles with metadata
+- **assets** — Individual asset files referenced by releases
+
+## Expo Updates Protocol
+
+The handler implements the full Expo Updates manifest protocol:
+
+- **Protocol v0**: Legacy format for older Expo SDK versions
+- **Protocol v1**: Modern multipart/mixed response format
+- **Code signing**: RSA-SHA256 signatures on manifest directives
+- **Platform filtering**: Serves platform-specific bundles based on request headers
+- **Channel routing**: Multiple release channels with independent version tracks
+
+### How It Works
+
+1. The Expo app sends a manifest request with platform, runtime version, and current update ID
+2. The handler finds the latest release for the requested channel and platform
+3. If a newer release exists, it returns a signed manifest with asset URLs
+4. The Expo runtime downloads assets and applies the update
+
+## Peer Dependencies
+
+| Package | Version | Required |
+|---------|---------|----------|
+| `drizzle-orm` | `>=0.30.0` | Yes |
+| `structured-headers` | `^1.0.0` | Yes (runtime dep) |
+| `@aws-sdk/client-s3` | `>=3.0.0` | For S3 storage |
+| `expo-updates` | `>=0.25.0` | Client SDK |
+| `react` | `>=18.0.0` | Client SDK |
+| `react-native` | `>=18.0.0` | Client SDK |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@everystack/cli",
+  "version": "0.1.0",
+  "description": "CLI and OTA updates for Expo apps on everystack",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./client": {
+      "types": "./src/client/index.ts",
+      "default": "./src/client/index.ts"
+    },
+    "./schema": {
+      "types": "./src/schema.ts",
+      "default": "./src/schema.ts"
+    },
+    "./handler": {
+      "types": "./src/handler/index.ts",
+      "default": "./src/handler/index.ts"
+    }
+  },
+  "bin": {
+    "everystack": "./src/cli/index.ts"
+  },
+  "dependencies": {
+    "glob": "13.0.6",
+    "node-forge": "^1.4.0",
+    "structured-headers": "^1.0.0",
+    "tsx": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-cloudfront": ">=3.0.0",
+    "@aws-sdk/client-cloudfront-keyvaluestore": ">=3.0.0",
+    "@aws-sdk/client-cloudwatch-logs": ">=3.0.0",
+    "@aws-sdk/client-lambda": ">=3.0.0",
+    "@aws-sdk/client-s3": ">=3.0.0",
+    "@aws-sdk/signature-v4a": ">=3.0.0",
+    "drizzle-orm": ">=0.30.0",
+    "expo-updates": ">=0.25.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-cloudfront": {
+      "optional": true
+    },
+    "@aws-sdk/client-cloudwatch-logs": {
+      "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/client-lambda": {
+      "optional": true
+    },
+    "@aws-sdk/client-cloudfront-keyvaluestore": {
+      "optional": true
+    },
+    "@aws-sdk/signature-v4a": {
+      "optional": true
+    },
+    "expo-updates": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aws-sdk/client-cloudfront": "^3.700.0",
+    "@aws-sdk/client-cloudfront-keyvaluestore": "^3.700.0",
+    "@aws-sdk/client-cloudwatch-logs": "^3.1047.0",
+    "@aws-sdk/client-lambda": "^3.700.0",
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/signature-v4a": "^3.1031.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.0.0",
+    "@types/node-forge": "^1.3.14",
+    "@types/react": "~19.2.14",
+    "drizzle-orm": "^0.41.0",
+    "jest": "^29.7.0",
+    "react": "19.2.0",
+    "ts-jest": "^29.3.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "build": "tsc --build",
+    "lint": "tsc --noEmit"
+  }
+}

package/src/cli/aws.ts

@@ -0,0 +1,121 @@
+/**
+ * AWS SDK wrappers for CLI operations.
+ *
+ * S3 for direct uploads, Lambda for direct invoke, KVS for cache versioning.
+ * Authentication uses the developer's IAM credentials (default credential chain).
+ */
+
+import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';
+import { LambdaClient, InvokeCommand } from '@aws-sdk/client-lambda';
+
+let s3Client: S3Client | null = null;
+let lambdaClient: LambdaClient | null = null;
+let kvsClient: import('@aws-sdk/client-cloudfront-keyvaluestore').CloudFrontKeyValueStoreClient | null = null;
+
+function getS3(region: string): S3Client {
+  if (!s3Client) s3Client = new S3Client({ region });
+  return s3Client;
+}
+
+function getLambda(region: string): LambdaClient {
+  if (!lambdaClient) lambdaClient = new LambdaClient({ region });
+  return lambdaClient;
+}
+
+export async function uploadToS3(
+  region: string,
+  bucket: string,
+  key: string,
+  body: Buffer | Uint8Array,
+  contentType: string,
+): Promise<void> {
+  const client = getS3(region);
+  await client.send(new PutObjectCommand({
+    Bucket: bucket,
+    Key: key,
+    Body: body,
+    ContentType: contentType,
+  }));
+}
+
+export async function getFromS3(
+  region: string,
+  bucket: string,
+  key: string,
+): Promise<Buffer | null> {
+  const client = getS3(region);
+  try {
+    const response = await client.send(new GetObjectCommand({
+      Bucket: bucket,
+      Key: key,
+    }));
+    if (!response.Body) return null;
+    const bytes = await response.Body.transformToByteArray();
+    return Buffer.from(bytes);
+  } catch (err: unknown) {
+    if (err && typeof err === 'object' && 'name' in err && (err as { name: string }).name === 'NoSuchKey') {
+      return null;
+    }
+    throw err;
+  }
+}
+
+export async function invokeAction(
+  region: string,
+  functionName: string,
+  action: string,
+  payload: unknown,
+): Promise<unknown> {
+  const client = getLambda(region);
+  const response = await client.send(new InvokeCommand({
+    FunctionName: functionName,
+    Payload: new TextEncoder().encode(JSON.stringify({
+      _action: action,
+      _payload: payload,
+    })),
+  }));
+
+  if (response.FunctionError) {
+    const errorBody = response.Payload
+      ? JSON.parse(new TextDecoder().decode(response.Payload))
+      : { errorMessage: 'Unknown Lambda error' };
+    throw new Error(errorBody.errorMessage || response.FunctionError);
+  }
+
+  if (!response.Payload) return null;
+  return JSON.parse(new TextDecoder().decode(response.Payload));
+}
+
+/**
+ * Write a versioning key to CloudFront KeyValueStore.
+ * KVS requires ETag for optimistic concurrency — DescribeKeyValueStore first.
+ */
+export async function putKvsKey(
+  region: string,
+  kvsArn: string,
+  key: string,
+  value: string,
+): Promise<void> {
+  // KVS requires SigV4a (asymmetric) signing — load pure-JS implementation
+  await import('@aws-sdk/signature-v4a');
+  const {
+    CloudFrontKeyValueStoreClient,
+    DescribeKeyValueStoreCommand,
+    PutKeyCommand,
+  } = await import('@aws-sdk/client-cloudfront-keyvaluestore');
+
+  if (!kvsClient) kvsClient = new CloudFrontKeyValueStoreClient({ region });
+
+  const desc = await kvsClient.send(
+    new DescribeKeyValueStoreCommand({ KvsARN: kvsArn })
+  );
+
+  await kvsClient.send(
+    new PutKeyCommand({
+      KvsARN: kvsArn,
+      Key: key,
+      Value: value,
+      IfMatch: desc.ETag!,
+    })
+  );
+}

package/src/cli/commands/analyze.ts

@@ -0,0 +1,61 @@
+/**
+ * analyze — static analysis commands.
+ *
+ * Subcommands:
+ *   analyze:ssr — scan app code for SSR anti-patterns
+ *
+ * Usage:
+ *   everystack analyze:ssr [--app ./app] [--json]
+ */
+
+import path from 'node:path';
+import { analyzeSSRPatterns, generateSSRReport } from '../ssr-analyzer.js';
+import { step, success, fail, info } from '../output.js';
+
+export async function analyzeSSRCommand(
+  _positional: string | undefined,
+  flags: Record<string, string>,
+): Promise<void> {
+  const appDir = flags.app || path.join(process.cwd(), 'app');
+
+  step(`Scanning ${appDir} for SSR patterns...`);
+
+  let analysis;
+  try {
+    analysis = await analyzeSSRPatterns(appDir);
+  } catch (err: any) {
+    fail(`Failed to analyze app directory: ${err.message}`);
+    info('Make sure you\'re running this from an Expo Router project root.');
+    process.exit(1);
+  }
+
+  // JSON output for scripting
+  if (flags.json === 'true' || flags.json === '1') {
+    console.log(JSON.stringify(analysis, null, 2));
+    return;
+  }
+
+  // Human-readable output
+  console.log('');
+  const report = generateSSRReport(analysis);
+  console.log(report);
+  console.log('');
+
+  if (analysis.issues.length > 0) {
+    const errors = analysis.issues.filter(i => i.severity === 'error').length;
+    const warnings = analysis.issues.filter(i => i.severity === 'warning').length;
+    const infos = analysis.issues.filter(i => i.severity === 'info').length;
+
+    if (errors > 0) {
+      fail(`Found ${errors} error(s), ${warnings} warning(s), ${infos} info(s)`);
+    } else if (warnings > 0) {
+      info(`Found ${warnings} warning(s), ${infos} info(s)`);
+    } else {
+      info(`Found ${infos} info(s) — review for optimization opportunities`);
+    }
+  } else {
+    success('No SSR anti-patterns detected');
+  }
+
+  console.log('');
+}

package/src/cli/commands/branches.ts

@@ -0,0 +1,97 @@
+export async function branchesCommand(subcommand: string, flags: Record<string, string>): Promise<void> {
+  switch (subcommand) {
+    case 'list':
+      await listBranches(flags);
+      break;
+    case 'create':
+      await createBranch(flags);
+      break;
+    case 'delete':
+      await deleteBranch(flags);
+      break;
+    default:
+      console.log('Usage: everystack branches <list|create|delete> [--name <name>]');
+  }
+}
+
+async function listBranches(_flags: Record<string, string>): Promise<void> {
+  const baseUrl = getBaseUrl();
+  const token = getToken();
+
+  const response = await fetch(`${baseUrl}/branches`, {
+    headers: token ? { authorization: `Bearer ${token}` } : {},
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to list branches: ${response.status}`);
+  }
+
+  const body = await response.json() as any;
+  const branches = body.branches || [];
+  if (branches.length === 0) {
+    console.log('No branches found.');
+    return;
+  }
+
+  console.log('Branches:');
+  for (const branch of branches) {
+    console.log(`  ${branch.name} (created: ${branch.createdAt})`);
+  }
+}
+
+async function createBranch(flags: Record<string, string>): Promise<void> {
+  const name = flags.name;
+  if (!name) {
+    throw new Error('--name is required');
+  }
+
+  const baseUrl = getBaseUrl();
+  const token = getToken();
+
+  const response = await fetch(`${baseUrl}/branches`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(token ? { authorization: `Bearer ${token}` } : {}),
+    },
+    body: JSON.stringify({ name }),
+  });
+
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({}));
+    throw new Error(`Failed to create branch: ${(body as any).error || response.status}`);
+  }
+
+  console.log(`Branch "${name}" created.`);
+}
+
+async function deleteBranch(flags: Record<string, string>): Promise<void> {
+  const name = flags.name;
+  if (!name) {
+    throw new Error('--name is required');
+  }
+
+  const baseUrl = getBaseUrl();
+  const token = getToken();
+
+  const response = await fetch(`${baseUrl}/branches/${encodeURIComponent(name)}`, {
+    method: 'DELETE',
+    headers: token ? { authorization: `Bearer ${token}` } : {},
+  });
+
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({}));
+    throw new Error(`Failed to delete branch: ${(body as any).error || response.status}`);
+  }
+
+  console.log(`Branch "${name}" deleted.`);
+}
+
+function getBaseUrl(): string {
+  if (process.env.EVERYSTACK_URL) return process.env.EVERYSTACK_URL;
+  throw new Error('EVERYSTACK_URL environment variable is required');
+}
+
+function getToken(): string | undefined {
+  return process.env.EVERYSTACK_TOKEN;
+}

package/src/cli/commands/cache.ts

@@ -0,0 +1,72 @@
+/**
+ * cache:purge — bust CloudFront cache via KVS version bump.
+ *
+ * No args → global epoch bump → all cached content refreshes.
+ * --origin api|media|web → per-origin epoch bump → only that origin refreshes.
+ * --path "/api/posts" → per-URL version bump → only that path refreshes.
+ *
+ * Writes directly to CloudFront KVS — no Lambda invoke, no CF invalidation API.
+ */
+
+import { resolveConfig } from '../config.js';
+import { putKvsKey } from '../aws.js';
+import { step, success, fail, info } from '../output.js';
+
+const VALID_ORIGINS = ['api', 'media', 'web'] as const;
+type CacheOrigin = typeof VALID_ORIGINS[number];
+
+export async function cachePurgeCommand(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);
+  }
+
+  if (!config.kvsArn) {
+    fail('No kvsArn found in .sst/outputs.json. Deploy with cache versioning enabled first.');
+    info('Add `kvsArn: cacheVersionStore.arn` to the return block in sst.config.ts and redeploy.');
+    process.exit(1);
+  }
+
+  // Key resolution: --path wins > --origin > global
+  let key: string;
+  if (flags.path) {
+    // Normalize: strip query params (they're not part of the cache key) and ensure leading /
+    let path = flags.path.split('?')[0];
+    if (!path.startsWith('/')) path = '/' + path;
+    key = path;
+  } else if (flags.origin) {
+    if (!VALID_ORIGINS.includes(flags.origin as CacheOrigin)) {
+      fail(`Invalid origin: ${flags.origin}. Valid origins: ${VALID_ORIGINS.join(', ')}`);
+      process.exit(1);
+    }
+    key = `__epoch__:${flags.origin}`;
+  } else {
+    key = '__epoch__';
+  }
+
+  const epoch = String(Math.floor(Date.now() / 1000));
+
+  step(`Writing version ${epoch} for key "${key}"...`);
+  try {
+    await putKvsKey(config.region, config.kvsArn, key, epoch);
+  } catch (err: any) {
+    fail(`KVS write failed: ${err.message}`);
+    info('Ensure your IAM user/role has cloudfront-keyvaluestore:PutKey and DescribeKeyValueStore permissions.');
+    process.exit(1);
+  }
+
+  if (flags.path) {
+    success(`Cache purged: ${flags.path} → version ${epoch}`);
+    info(`Cached content at ${flags.path} will refresh on next request.`);
+  } else if (flags.origin) {
+    success(`Cache purged: ${flags.origin} origin → version ${epoch}`);
+    info(`All ${flags.origin} content will refresh on next request.`);
+  } else {
+    success(`Cache epoch updated to ${epoch}`);
+    info('All cached content will refresh on next request.');
+  }
+}