@ericminassian/plat 0.1.0 → 0.2.0

package/src/project.ts

@@ -1,47 +1,64 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { ManifestError, parseManifest, type ResolvedManifest } from '@ericminassian/platform-core';
+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';
 
-export const MANIFEST_FILE = 'platform.json';
+/** 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 platform.json. */
+  /** Directory containing plat.config.ts. */
   root: string;
-  /** platform.json as written. */
+  /** 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 platform.json. */
-export function findProjectRoot(cwd: string): string | null {
+/** 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, MANIFEST_FILE))) return dir;
+    if (existsSync(join(dir, name))) return dir;
     const parent = dirname(dir);
     if (parent === dir) return null;
     dir = parent;
   }
 }
 
-export function loadProject(cwd: string): Project {
+/** 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) {
-    throw new CliError(`no ${MANIFEST_FILE} found in ${cwd} or its parents`, {
-      hint: 'run this inside an app, or create one with `plat init <dir> --name <app>`',
+    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,
     });
   }
-  let raw: Record<string, unknown>;
-  try {
-    raw = JSON.parse(readFileSync(join(root, MANIFEST_FILE), 'utf8'));
-  } catch (err) {
-    throw new CliError(`${MANIFEST_FILE} is not valid JSON: ${(err as Error).message}`, {
+  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) {
@@ -50,17 +67,54 @@ export function loadProject(cwd: string): Project {
   }
 }
 
-/** App name from `--app`, else the nearest platform.json. */
-export function resolveAppName(opt: string | undefined, cwd = process.cwd()): string {
+/**
+ * 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;
-  const root = findProjectRoot(cwd);
-  if (!root) {
+  if (!findProjectRoot(cwd)) {
     throw new CliError('no app given', {
       hint: 'pass --app <name> or run inside an app directory',
       exitCode: EXIT.usage,
     });
   }
-  return loadProject(root).manifest.name;
+  return (await loadProject(cwd)).manifest.name;
 }
 
 export function cliVersion(): string {

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/template/AGENTS.md

@@ -6,10 +6,13 @@ the app; the platform provisions, deploys, routes, signs users in and monitors i
 
 ## Golden rules
 
-1. **No infrastructure code and no AWS SDK in this repo.** Declare what you need in `platform.json`; use it
-   through `@ericminassian/platform`. No CDK, CloudFormation, Terraform or `@aws-sdk/*` imports.
-2. **Every name in `platform.json` must match code.** Each queue, event and cron needs a handler in
-   `src/worker.ts`, and every handler needs a `platform.json` entry.
+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
@@ -19,7 +22,7 @@ the app; the platform provisions, deploys, routes, signs users in and monitors i
 
 | Path                         | What                                                                                   |
 | ---------------------------- | -------------------------------------------------------------------------------------- |
-| `platform.json`              | Everything the app needs (web, auth, db, queues, events, crons, storage, secrets, env) |
+| `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                                                 |
@@ -29,7 +32,7 @@ the app; the platform provisions, deploys, routes, signs users in and monitors i
 
 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/"]`).
+`web.serverRoutes` (default `['/api/']`).
 
 ## SDK reference (`@ericminassian/platform`)
 
@@ -44,8 +47,8 @@ import { defineWorker, invokeJob } from '@ericminassian/platform/worker';
 | `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<EmailJob>('emails').send({ to, subject, body }, { delaySeconds: 60 })`                         |
-| `events.publish`            | `await events.publish('todo.created', { id })` (anything can publish; subscribers are listed in `events`)   |
+| `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(...)`                             |
@@ -54,7 +57,7 @@ import { defineWorker, invokeJob } from '@ericminassian/platform/worker';
 | `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: {...} })`                      |
+| `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,
@@ -63,32 +66,34 @@ queue send and `fetch` is traced automatically. Don't add your own tracing or me
 ## Recipes
 
 - **New collection or index.** Declare it in code; no infra change is needed. `db: true` must be in
-  `platform.json`. For a secondary index:
+  `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 `"queues": { "thumbnails": { "batchSize": 5 } }` to `platform.json`.
+  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 the type to `"events"`, then add an `events['order.paid']` handler.
-- **Cron.** Add `"crons": { "digest": "0 8 * * 1-5" }` (5-field cron, UTC; or
-  `{ "schedule": "...", "timezone": "America/Los_Angeles" }`, or `"rate(15 minutes)"`), then add a
+- **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 `"storage": ["avatars"]`, then use `storage('avatars')`. For browser uploads, return
+- **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 `"secrets": ["STRIPE_KEY"]` to `platform.json`.
+  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.
+  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`.
 

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;
+  }
+}

package/template/src/server.ts

@@ -2,7 +2,7 @@ import { auth, db, events, metrics, app as platform, queue } from '@ericminassia
 import { Hono } from 'hono';
 import { validator } from 'hono/validator';
 import { z } from 'zod';
-import type { EmailJob, Todo, TodoCreated } from './types.ts';
+import type { Todo } from './types.ts';
 
 // One collection per entity. Partition by user so each user's todos are one query.
 // Sort keys are time-ordered ids, so `query` returns oldest first.
@@ -50,9 +50,9 @@ const api = new Hono()
       createdAt: new Date().toISOString(),
     };
     await todos.put(todo, { ifNotExists: true });
-    await events.publish<TodoCreated>('todo.created', { userId: user.id, id: todo.id, title: todo.title });
+    await events.publish('todo.created', { userId: user.id, id: todo.id, title: todo.title });
     if (user.email) {
-      await queue<EmailJob>('emails').send({ to: user.email, subject: 'New todo', body: todo.title });
+      await queue('emails').send({ to: user.email, subject: 'New todo', body: todo.title });
     }
     metrics.count('todos.created');
     return c.json({ todo }, 201);

package/template/src/worker.ts

@@ -1,12 +1,12 @@
 import { log, metrics } from '@ericminassian/platform';
-import { defineWorker, type PlatformEvent, type QueueMessage } from '@ericminassian/platform/worker';
-import type { EmailJob, TodoCreated } from './types.ts';
+import { defineWorker } from '@ericminassian/platform/worker';
 
-// Every key here must match platform.json: `queues`, `events` and `crons`.
+// Handles exactly the `queues`, `events` and `crons` in plat.config.ts (a missing
+// or extra handler is a type error), with the payload types declared there.
 // Throwing retries the job (queues: up to maxReceiveCount, then the dead-letter queue).
 export default defineWorker({
   queues: {
-    emails: async (message: QueueMessage<EmailJob>) => {
+    emails: async (message) => {
       // Swap in a real email provider here (store its API key with `plat secrets set`).
       log.info('would send email', {
         to: message.body.to,
@@ -18,7 +18,7 @@ export default defineWorker({
   },
 
   events: {
-    'todo.created': async (event: PlatformEvent<TodoCreated>) => {
+    'todo.created': async (event) => {
       log.info('todo created', { id: event.detail.id, userId: event.detail.userId });
     },
   },

package/template/tsconfig.json

@@ -14,5 +14,5 @@
     "skipLibCheck": true,
     "noEmit": true
   },
-  "include": ["src", "test", "vitest.config.ts", "vitest.integration.config.ts"]
+  "include": ["plat.config.ts", "src", "test", "vitest.config.ts", "vitest.integration.config.ts"]
 }

package/template/platform.json

@@ -1,18 +0,0 @@
-{
-  "$schema": "https://raw.githubusercontent.com/eric-minassian/platform/main/packages/core/platform.schema.json",
-  "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": {} },
-  "events": ["todo.created"],
-  "crons": { "cleanup": "0 3 * * *" },
-  "storage": ["uploads"]
-}