@ericminassian/plat 0.0.0-stage → 0.2.0

package/src/project.ts

@@ -0,0 +1,143 @@
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import {
+  APP_CONFIG_FILE,
+  ManifestError,
+  parseManifest,
+  type ResolvedManifest,
+} from '@ericminassian/platform-core';
+import { build as esbuild } from 'esbuild';
+import { buildFailureList } from './util/esbuild.ts';
+import { CliError, EXIT } from './util/output.ts';
+
+/** Apps configured with JSON before `plat.config.ts`; only detected to say how to move. */
+const LEGACY_MANIFEST_FILE = 'platform.json';
+
+export interface Project {
+  /** Directory containing plat.config.ts. */
+  root: string;
+  /** The config's default export as JSON: exactly what is validated, built and deployed. */
+  raw: Record<string, unknown>;
+  manifest: ResolvedManifest;
+}
+
+/** Walk up from `cwd` to the nearest directory containing `name`. */
+function findUp(cwd: string, name: string): string | null {
+  let dir = resolve(cwd);
+  for (;;) {
+    if (existsSync(join(dir, name))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** Walk up from `cwd` to the nearest plat.config.ts. */
+export function findProjectRoot(cwd: string): string | null {
+  return findUp(cwd, APP_CONFIG_FILE);
+}
+
+export async function loadProject(cwd: string): Promise<Project> {
+  const root = findProjectRoot(cwd);
+  if (!root) {
+    const legacy = findUp(cwd, LEGACY_MANIFEST_FILE);
+    throw new CliError(`no ${APP_CONFIG_FILE} found in ${cwd} or its parents`, {
+      hint: legacy
+        ? `${join(legacy, LEGACY_MANIFEST_FILE)} is no longer read: move its fields into ${APP_CONFIG_FILE} as \`export default defineApp({ ... })\` from '@ericminassian/platform/config'`
+        : 'run this inside an app, or create one with `plat init <dir> --name <app>`',
+      exitCode: EXIT.usage,
+    });
+  }
+  const exported = await importConfig(root);
+  if (exported === null || typeof exported !== 'object' || Array.isArray(exported)) {
+    throw new CliError(`${APP_CONFIG_FILE} must default-export the app config`, {
+      hint: "export default defineApp({ name: '...' }) from '@ericminassian/platform/config'",
+      exitCode: EXIT.usage,
+    });
+  }
+  // The platform receives JSON, so validate (and later deploy) the JSON form.
+  const raw = JSON.parse(JSON.stringify(exported)) as Record<string, unknown>;
+  try {
+    return { root, raw, manifest: parseManifest(raw) };
+  } catch (err) {
+    if (err instanceof ManifestError) throw new CliError(err.message, { exitCode: EXIT.usage });
+    throw err;
+  }
+}
+
+/**
+ * Bundles the config (its relative imports included, packages left external)
+ * into `.plat/` and imports that, like Vite does for vite.config.ts. This
+ * works whatever the app's package `type` is, and a fresh file name means a
+ * changed config is always re-read.
+ */
+async function importConfig(root: string): Promise<unknown> {
+  const outfile = join(root, '.plat', `config-${process.pid}-${Date.now()}.mjs`);
+  try {
+    await esbuild({
+      entryPoints: [join(root, APP_CONFIG_FILE)],
+      outfile,
+      bundle: true,
+      packages: 'external',
+      platform: 'node',
+      format: 'esm',
+      target: 'node24',
+      sourcemap: 'inline',
+      logLevel: 'silent',
+      absWorkingDir: root,
+    });
+  } catch (err) {
+    throw new CliError(`could not compile ${APP_CONFIG_FILE}:${buildFailureList(err)}`, {
+      exitCode: EXIT.usage,
+    });
+  }
+  try {
+    const mod = (await import(pathToFileURL(outfile).href)) as { default?: unknown };
+    return mod.default;
+  } catch (err) {
+    throw new CliError(`${APP_CONFIG_FILE} threw while loading: ${(err as Error).message}`, {
+      exitCode: EXIT.usage,
+    });
+  } finally {
+    rmSync(outfile, { force: true });
+  }
+}
+
+/** App name from `--app`, else the nearest plat.config.ts. */
+export async function resolveAppName(opt: string | undefined, cwd = process.cwd()): Promise<string> {
+  if (opt) return opt;
+  if (!findProjectRoot(cwd)) {
+    throw new CliError('no app given', {
+      hint: 'pass --app <name> or run inside an app directory',
+      exitCode: EXIT.usage,
+    });
+  }
+  return (await loadProject(cwd)).manifest.name;
+}
+
+export function cliVersion(): string {
+  return (cliPackageJson().version as string | undefined) ?? '0.0.0';
+}
+
+export function cliPackageRoot(): string {
+  return fileURLToPath(new URL('..', import.meta.url));
+}
+
+function cliPackageJson(): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(cliPackageRoot(), 'package.json'), 'utf8'));
+}
+
+/**
+ * Resolve a module the way the *app* would (its own node_modules first), so
+ * the server wrapper and app code share one copy of the SDK. Falls back to the
+ * CLI's own dependency.
+ */
+export function resolveFromApp(appRoot: string, specifier: string): string {
+  try {
+    return createRequire(join(appRoot, 'package.json')).resolve(specifier);
+  } catch {
+    return createRequire(import.meta.url).resolve(specifier);
+  }
+}

package/src/util/esbuild.ts

@@ -0,0 +1,10 @@
+/** An esbuild failure as `file:line: message` items (or the error's message), for a CliError list. */
+export function buildFailureList(err: unknown): string {
+  const errors = (
+    err as { errors?: Array<{ text: string; location?: { file: string; line: number } | null }> }
+  ).errors;
+  const lines = errors?.length
+    ? errors.map((e) => (e.location ? `${e.location.file}:${e.location.line}: ${e.text}` : e.text))
+    : [(err as Error).message];
+  return `\n  - ${lines.join('\n  - ')}`;
+}

package/src/util/net.ts

@@ -0,0 +1,33 @@
+import { createServer } from 'node:net';
+
+/** A free TCP port on 127.0.0.1. */
+export function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.once('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const addr = srv.address();
+      const port = typeof addr === 'object' && addr ? addr.port : 0;
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+/** Resolves once something accepts TCP connections on host:port. */
+export async function waitForPort(port: number, host = '127.0.0.1', timeoutMs = 30_000): Promise<void> {
+  const { connect } = await import('node:net');
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const ok = await new Promise<boolean>((resolve) => {
+      const s = connect(port, host);
+      s.once('connect', () => {
+        s.end();
+        resolve(true);
+      });
+      s.once('error', () => resolve(false));
+    });
+    if (ok) return;
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  throw new Error(`nothing listening on ${host}:${port} after ${timeoutMs}ms`);
+}

package/src/util/output.ts

@@ -0,0 +1,117 @@
+import pc from 'picocolors';
+
+/**
+ * Output conventions: human-readable by default, `--json` prints exactly one
+ * JSON document on stdout (progress goes to stderr) so agents can parse it.
+ */
+export class CliError extends Error {
+  readonly hint?: string;
+  readonly exitCode: number;
+  constructor(message: string, opts: { hint?: string; exitCode?: number } = {}) {
+    super(message);
+    this.hint = opts.hint;
+    this.exitCode = opts.exitCode ?? 1;
+  }
+}
+
+export const EXIT = {
+  ok: 0,
+  error: 1,
+  usage: 2,
+  auth: 3,
+  notFound: 4,
+  deployFailed: 5,
+} as const;
+
+export interface OutputOptions {
+  json?: boolean;
+}
+
+let jsonMode = false;
+
+export function setJsonMode(on: boolean): void {
+  jsonMode = on;
+}
+
+export function isJsonMode(): boolean {
+  return jsonMode;
+}
+
+/** Progress/status lines; stderr so `--json` stdout stays clean. */
+export function info(msg: string): void {
+  process.stderr.write(`${msg}\n`);
+}
+
+export function step(msg: string): void {
+  info(`${pc.cyan('›')} ${msg}`);
+}
+
+export function success(msg: string): void {
+  info(`${pc.green('✓')} ${msg}`);
+}
+
+export function warn(msg: string): void {
+  info(`${pc.yellow('!')} ${msg}`);
+}
+
+/** Prints the command result: JSON in `--json` mode, else via `human`. */
+export function result<T>(value: T, human: (v: T) => string | undefined): void {
+  if (jsonMode) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+    return;
+  }
+  const text = human(value);
+  if (text) process.stdout.write(`${text}\n`);
+}
+
+export function formatError(err: unknown): { message: string; hint?: string; exitCode: number } {
+  if (err instanceof CliError) return { message: err.message, hint: err.hint, exitCode: err.exitCode };
+  if (err instanceof Error) return { message: err.message, exitCode: EXIT.error };
+  return { message: String(err), exitCode: EXIT.error };
+}
+
+export function reportError(err: unknown): number {
+  const { message, hint, exitCode } = formatError(err);
+  if (jsonMode) {
+    process.stdout.write(`${JSON.stringify({ error: { message, hint, exitCode } }, null, 2)}\n`);
+  } else {
+    info(`${pc.red('✗')} ${message}`);
+    if (hint) info(`  ${pc.dim(hint)}`);
+  }
+  return exitCode;
+}
+
+/** Plain-text table with padded columns. */
+export function table(rows: Array<Record<string, unknown>>, columns?: string[]): string {
+  if (rows.length === 0) return pc.dim('(none)');
+  const cols = columns ?? Object.keys(rows[0]!);
+  const cell = (v: unknown) =>
+    v === undefined || v === null ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v);
+  const widths = cols.map((c) => Math.max(c.length, ...rows.map((r) => visibleLength(cell(r[c])))));
+  const line = (vals: string[]) =>
+    vals.map((v, i) => v + ' '.repeat(widths[i]! - visibleLength(v))).join('  ');
+  return [pc.bold(line(cols)), ...rows.map((r) => line(cols.map((c) => cell(r[c]))))].join('\n');
+}
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching ANSI escape codes is the point
+const ANSI = /\x1b\[[0-9;]*m/g;
+function visibleLength(s: string): number {
+  return s.replace(ANSI, '').length;
+}
+
+const SPARKS = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+
+/** Unicode sparkline; nulls render as spaces. */
+export function sparkline(values: Array<number | null>): string {
+  const nums = values.filter((v): v is number => v !== null && Number.isFinite(v));
+  if (nums.length === 0) return '';
+  const min = Math.min(...nums);
+  const max = Math.max(...nums);
+  return values
+    .map((v) => {
+      if (v === null || !Number.isFinite(v)) return ' ';
+      if (max === min) return v === 0 ? SPARKS[0] : SPARKS[3];
+      return SPARKS[Math.round(((v - min) / (max - min)) * (SPARKS.length - 1))];
+    })
+    .join('');
+}

package/src/util/prompt.ts

@@ -0,0 +1,20 @@
+import { createInterface } from 'node:readline/promises';
+import { CliError, EXIT } from './output.ts';
+
+export async function prompt(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+/** Ask the user to type `expected` back; `--yes` skips it, and non-interactive runs must pass it. */
+export async function confirmByTyping(question: string, expected: string, yes?: boolean): Promise<void> {
+  if (yes) return;
+  if (!process.stdin.isTTY)
+    throw new CliError('confirmation needed', { hint: 'pass --yes', exitCode: EXIT.usage });
+  const answer = await prompt(`${question} type ${expected} to confirm: `);
+  if (answer.trim() !== expected) throw new CliError('aborted', { exitCode: EXIT.usage });
+}

package/src/util/time.ts

@@ -0,0 +1,32 @@
+import type { Resolution } from '@ericminassian/platform-core';
+import { CliError, EXIT } from './output.ts';
+
+const UNITS: Record<string, number> = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+
+/** `"90s" | "15m" | "6h" | "7d" | "2w"` → milliseconds. */
+export function parseDuration(input: string): number {
+  const m = /^(\d+(?:\.\d+)?)\s*([smhdw])$/.exec(input.trim());
+  if (!m)
+    throw new CliError(`invalid duration "${input}"`, { hint: 'use e.g. 30m, 6h, 7d', exitCode: EXIT.usage });
+  return Number(m[1]) * UNITS[m[2]!]!;
+}
+
+/** Pick a rollup resolution that yields a readable number of points. */
+export function resolutionFor(rangeMs: number): Resolution {
+  if (rangeMs <= 6 * UNITS.h!) return '1m';
+  if (rangeMs <= 14 * UNITS.d!) return '1h';
+  return '1d';
+}
+
+export function sinceRange(since: string, now = Date.now()): { from: number; to: number; res: Resolution } {
+  const ms = parseDuration(since);
+  return { from: now - ms, to: now, res: resolutionFor(ms) };
+}
+
+export function shortTime(iso: string | number): string {
+  const d = new Date(iso);
+  return d
+    .toISOString()
+    .replace('T', ' ')
+    .replace(/\.\d+Z$/, 'Z');
+}

package/src/util/zip.ts

@@ -0,0 +1,46 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { unzipSync, type Zippable, zipSync } from 'fflate';
+
+/** Every file under `dir`, as zip paths (forward slashes) → absolute paths. */
+export function listFiles(dir: string): Array<{ zipPath: string; absPath: string }> {
+  const out: Array<{ zipPath: string; absPath: string }> = [];
+  const walk = (d: string) => {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const abs = join(d, entry.name);
+      if (entry.isDirectory()) walk(abs);
+      else if (entry.isFile()) out.push({ zipPath: relative(dir, abs).split(sep).join('/'), absPath: abs });
+    }
+  };
+  walk(dir);
+  return out.sort((a, b) => a.zipPath.localeCompare(b.zipPath));
+}
+
+/** Zip a directory. Timestamps are fixed so identical inputs produce identical zips. */
+export function zipDirectory(dir: string): Uint8Array {
+  const files: Zippable = {};
+  for (const f of listFiles(dir)) files[f.zipPath] = [readFileSync(f.absPath), { mtime: FIXED_MTIME }];
+  return zipSync(files, { level: 6 });
+}
+
+export function zipEntries(entries: Record<string, Uint8Array | string>): Uint8Array {
+  const files: Zippable = {};
+  for (const [name, data] of Object.entries(entries)) {
+    files[name] = [typeof data === 'string' ? new TextEncoder().encode(data) : data, { mtime: FIXED_MTIME }];
+  }
+  return zipSync(files, { level: 6 });
+}
+
+export function zipFileNames(zip: Uint8Array): string[] {
+  return Object.keys(unzipSync(zip)).sort();
+}
+
+export function dirExists(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+const FIXED_MTIME = new Date('2020-01-01T00:00:00Z');

package/template/.github/workflows/platform.yml

@@ -0,0 +1,24 @@
+# Test, build and deploy on the platform. PRs get a preview at
+# https://template-app--pr-<n>.ericminassian.com (removed when the PR closes);
+# main deploys https://template-app.ericminassian.com. No AWS credentials:
+# CI signs in to the platform with GitHub's OIDC token.
+name: platform
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+
+permissions:
+  id-token: write
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: platform-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  platform:
+    uses: eric-minassian/platform/.github/workflows/app.yml@main

package/template/AGENTS.md

@@ -0,0 +1,139 @@
+# template-app: agent guide
+
+This app runs on **the platform** (github.com/eric-minassian/platform), a PaaS for small apps. You write
+the app; the platform provisions, deploys, routes, signs users in and monitors it. Live at
+`https://template-app.ericminassian.com`.
+
+## Golden rules
+
+1. **No infrastructure code and no AWS SDK in this repo.** Declare what you need in `plat.config.ts`; use
+   it through `@ericminassian/platform`. No CDK, CloudFormation, Terraform or `@aws-sdk/*` imports.
+2. **`plat.config.ts` is the source of truth for names and payload types.** `pnpm typecheck` fails unless
+   `src/worker.ts` handles exactly its queues, events and crons, and every `queue()`, `events.publish()`,
+   `storage()` and `secrets.get()` uses a declared name with the declared payload type. Declare message
+   types there (`queue<EmailJob>()`, `event<TodoCreated>()`) rather than annotating handlers, and keep the
+   `Register` block at the end of the file.
+3. **Never commit secrets.** Use `plat secrets set NAME` for deployed stages and `.env.local` (git-ignored)
+   for `plat dev`. Declare each name under `secrets`.
+4. **Run `pnpm typecheck && pnpm test` before you push.** CI runs the same checks, plus `plat test` when
+   `*.integration.test.ts` files exist.
+
+## Layout
+
+| Path                         | What                                                                                   |
+| ---------------------------- | -------------------------------------------------------------------------------------- |
+| `plat.config.ts`             | Everything the app needs (web, auth, db, queues, events, crons, storage, secrets, env) |
+| `src/server.ts`              | HTTP API (Hono). `export default app`. Routes under `/api/*`                           |
+| `src/worker.ts`              | Background handlers: `defineWorker({ queues, events, crons })`                         |
+| `src/types.ts`               | Types shared by server, worker and web                                                 |
+| `web/`                       | React SPA (Vite), built into `web/dist`, served from the edge                          |
+| `test/*.test.ts`             | Unit tests with a mocked SDK (`pnpm test`)                                             |
+| `test/*.integration.test.ts` | Real SDK against the AWS Emulator (`plat test`)                                        |
+
+Requests for `/api/*` and `/__platform/*` go to the server; files go to `web/dist`. Any other path
+serves `index.html`, which is how client-side routing works. Change the server prefixes with
+`web.serverRoutes` (default `['/api/']`).
+
+## SDK reference (`@ericminassian/platform`)
+
+```ts
+import { app, auth, db, events, log, metrics, queue, secrets, storage } from '@ericminassian/platform';
+import { defineWorker, invokeJob } from '@ericminassian/platform/worker';
+```
+
+| Export                      | Example                                                                                                     |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `app`                       | `app.name`, `app.stage` (`prod`, `pr-12`, `local`, `test`), `app.url`, `app.isLocal`                        |
+| `db.collection`             | `const todos = db.collection<Todo>('todos', { partition: 'userId', sort: 'id' })`                           |
+| `.get/.put/.update/.delete` | `await todos.put(t, { ifNotExists: true })`, `await todos.update({ userId, id }, { done: true })`           |
+| `.query`                    | `await todos.query({ userId }, { beginsWith: '2026', limit: 20, reverse: true })` → `{ items, cursor }`     |
+| `queue(name).send`          | `await queue('emails').send({ to, subject, body }, { delaySeconds: 60 })`                                   |
+| `events.publish`            | `await events.publish('todo.created', { userId, id, title })`                                               |
+| `storage(name)`             | `await storage('uploads').put(key, bytes, { contentType })`, `.get`, `.getText`, `.list(prefix)`, `.delete` |
+|                             | `await storage('uploads').uploadUrl(key, { contentType })`: browser-direct upload URL (HTTP PUT)            |
+| `secrets.get`               | `await secrets.get('STRIPE_KEY')` (throws if unset), `secrets.getOptional(...)`                             |
+| `auth.getUser`              | `await auth.getUser(c.req.raw)` → `{ id, email, name, groups }` or `null`                                   |
+| `auth.requireUser`          | `await auth.requireUser(c.req.raw)`: throws a 401 `Response` when signed out                                |
+| `auth.loginUrl/logoutUrl`   | `auth.loginUrl('/dashboard')` → `/__platform/auth/login?redirect=...`                                       |
+| `metrics`                   | `metrics.count('signups')`, `metrics.value('cart.total', 42.5, 'usd')`: free, shows up in the console       |
+| `log`                       | `log.info('charged', { orderId })`, `log.error('failed', err)`: structured, traced, searchable              |
+| `defineWorker`              | `defineWorker({ queues: { emails: async (msg) => {} }, events: {...}, crons: {...} })`; `msg.body` is typed |
+| `invokeJob`                 | `await invokeJob('reindex', { id })`: async call to an `invoke` handler on this stage's worker              |
+
+User ids (`user.id`) are stable and shared across all platform apps. Every request, job, database call,
+queue send and `fetch` is traced automatically. Don't add your own tracing or metrics plumbing.
+
+## Recipes
+
+- **New collection or index.** Declare it in code; no infra change is needed. `db: true` must be in
+  `plat.config.ts`. For a secondary index:
+  `db.collection<User>('users', { partition: 'id', indexes: { byEmail: { slot: 1, partition: 'email' } } })`,
+  then `users.query({ email }, { index: 'byEmail' })`.
+  - Slots 1-3 are fixed GSIs. Never reuse a slot for a different key in the same collection.
+  - For expiry, set `ttl: 'expiresAt'` (epoch seconds).
+- **Queue.**
+  1. Add `thumbnails: queue<ThumbnailJob>({ batchSize: 5 })` under `queues` in `plat.config.ts`, with
+     `ThumbnailJob` in `src/types.ts`.
+  2. Add a `queues.thumbnails` handler in `src/worker.ts`.
+  3. Send with `queue('thumbnails').send(...)`.
+
+  Throwing in the handler retries the message; after `maxReceiveCount` (default 5) it goes to the
+  dead-letter queue, which you can inspect and redrive from the console.
+- **Event subscription.** Add `'order.paid': event<OrderPaid>()` under `events`, then add an
+  `events['order.paid']` handler. Publish with `events.publish('order.paid', detail)`.
+- **Cron.** Add `digest: '0 8 * * 1-5'` under `crons` (5-field cron, UTC; or
+  `{ schedule: '...', timezone: 'America/Los_Angeles' }`, or `'rate(15 minutes)'`), then add a
+  `crons.digest` handler.
+- **File store.** Add `'avatars'` to `storage`, then use `storage('avatars')`. For browser uploads, return
+  `uploadUrl(...)` from an API route and `PUT` the file to it.
+- **Secret.**
+  1. Add `'STRIPE_KEY'` to `secrets` in `plat.config.ts`.
+  2. Set it: `plat secrets set STRIPE_KEY --stage prod`, or `--shared` for all stages.
+  3. Locally, put `STRIPE_KEY=...` in `.env.local`.
+  4. Read it: `await secrets.get('STRIPE_KEY')`.
+- **Protected route.** Call `const user = await auth.requireUser(c.req.raw)` first. To require sign-in
+  for everything, set `auth: { required: true }`.
+- **Plain config.** Use `env: { FEATURE_X: 'on' }`, read via `process.env.FEATURE_X`. Not for secrets.
+- **Custom metric.** Use `metrics.count('name')` or `metrics.value('name', n)`. It appears in the console
+  and in `plat metrics`.
+
+## Local loop
+
+```sh
+pnpm install
+pnpm dev                     # whole app on the AWS Emulator: http://template-app.localhost:3000
+pnpm test                    # unit tests (mocked SDK)
+pnpm test:integration        # plat test: real SDK against a throwaway emulator
+plat dev run-cron cleanup    # fire a cron in the running `plat dev`
+```
+
+`plat dev` has these properties:
+
+- It provisions real (emulated) DynamoDB, SQS, EventBridge, S3, Cognito and SSM.
+- The worker runs as a real Lambda inside the emulator.
+- The server restarts when you edit, and so does the worker.
+- Sign-in uses a local page where any email works.
+- State is in memory and is gone when it stops.
+- It needs the `aws-emulator` binary (see the hint it prints).
+
+## Deploying
+
+- **Pull request:** deploys a preview to `https://template-app--pr-<n>.ericminassian.com`. The URL is
+  commented on the PR, and the preview is destroyed when the PR closes.
+- **Merge to `main`:** deploys `https://template-app.ericminassian.com`.
+- Deploys take seconds. A failed deploy never goes live. Roll back with `plat rollback`.
+- One-time per app: `plat apps create template-app --repo <owner>/<repo>` registers the repo with the
+  platform. Without it, CI deploys are rejected.
+
+## Debugging (add `--json` for machine output)
+
+```sh
+plat logs --since 30m [--stage pr-12] [--filter "error"] [--follow]
+plat errors                         # grouped errors with sample stack + trace id
+plat traces <traceId>               # one request across server → queue → worker
+plat metrics --since 6h             # requests, 5xx, p95, cold starts, per-route and per-job stats
+plat data todos --partition userId=<id>
+plat deployments / plat stages / plat rollback
+```
+
+The console at https://platform.ericminassian.com shows the same data with graphs.

package/template/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/README.md

@@ -0,0 +1,13 @@
+# template-app
+
+A todo app on [the platform](https://github.com/eric-minassian/platform), with sign-in, a database, a
+queue, an event, a cron and file storage. It lives at https://template-app.ericminassian.com.
+
+```sh
+pnpm install
+pnpm dev        # http://template-app.localhost:3000 (AWS Emulator; install `aws-emulator` once)
+pnpm test
+```
+
+Pull requests deploy previews and `main` deploys production (`.github/workflows/platform.yml`). For
+everything else (the SDK, recipes, debugging) see [AGENTS.md](./AGENTS.md).

package/template/_gitignore

@@ -0,0 +1,8 @@
+node_modules/
+.plat/
+dist/
+web/dist/
+coverage/
+.env.local
+*.log
+.DS_Store

package/template/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "platform-app-template",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "plat dev",
+    "build": "plat build",
+    "deploy": "plat deploy",
+    "test": "vitest run",
+    "test:integration": "plat test",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p web/tsconfig.json"
+  },
+  "dependencies": {
+    "@ericminassian/platform": "workspace:*",
+    "hono": "^4.13.18",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@ericminassian/plat": "workspace:*",
+    "@types/node": "^24.19.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.3.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.8",
+    "vitest": "^5.1.0"
+  }
+}

package/template/plat.config.ts

@@ -0,0 +1,31 @@
+import { defineApp, event, queue } from '@ericminassian/platform/config';
+import type { EmailJob, TodoCreated } from './src/types.ts';
+
+// Everything this app needs from the platform. `plat` evaluates this file and
+// provisions what it declares; the SDK checks names and payload types in code
+// against it (see `Register` below).
+const app = defineApp({
+  name: 'template-app',
+  description: 'A todo app on the platform',
+  web: {
+    server: 'src/server.ts',
+    static: 'web/dist',
+    build: 'vite build --config web/vite.config.ts',
+    dev: { command: 'vite --config web/vite.config.ts', port: 5173 },
+    spa: true,
+  },
+  auth: true,
+  db: true,
+  queues: { emails: queue<EmailJob>() },
+  events: { 'todo.created': event<TodoCreated>() },
+  crons: { cleanup: '0 3 * * *' },
+  storage: ['uploads'],
+});
+
+export default app;
+
+declare module '@ericminassian/platform' {
+  interface Register {
+    app: typeof app;
+  }
+}