@ericminassian/plat 0.0.0-stage → 0.1.0

package/src/dev/index.ts

@@ -0,0 +1,281 @@
+import { type ChildProcess, spawn } from 'node:child_process';
+import type { Server } from 'node:http';
+import { resolve } from 'node:path';
+import { LOCAL_STAGE, type ResolvedManifest } from '@ericminassian/platform-core';
+import { EMULATOR_INSTALL_HINT } from '@ericminassian/platform-engine';
+import pc from 'picocolors';
+import { SDK_SERVER, withLocalBin } from '../build.ts';
+import { loadProject, resolveFromApp } from '../project.ts';
+import { freePort, waitForPort } from '../util/net.ts';
+import { CliError, info, step, success, warn } from '../util/output.ts';
+import { type LocalCron, scheduleCrons } from './crons.ts';
+import { tsxArgs } from './entries.ts';
+import { type LocalStage, localEnv, startLocalStage } from './local-stage.ts';
+import { prefixer } from './pretty.ts';
+import { killTree } from './proc.ts';
+import { type Interceptor, type LocalRouterState, localRouteRecord, startLocalRouter } from './router.ts';
+import { type Dispatcher, startLocalWorker, startWorkerDispatch } from './worker.ts';
+
+export interface DevOptions {
+  cwd: string;
+  port: number;
+  /** Print SDK trace spans too. */
+  spans?: boolean;
+}
+
+export const DEV_CONTROL_PREFIX = '/__plat_dev/';
+
+/**
+ * `plat dev`: the whole app locally against the AWS Emulator.
+ *
+ *  emulator ← engine (same code as prod; `webMode: 'external'`)
+ *  web server (SDK wrapper, tsx watch) ─┐
+ *  frontend dev server (web.dev) ───────┼─ local router (core `decide()`)
+ *  local sign-in page ──────────────────┘
+ *  worker (real Node, tsx watch) ← dispatcher (emulator SQS + EventBridge tap + local crons)
+ */
+export async function runDev(opts: DevOptions): Promise<void> {
+  const { root, manifest } = loadProject(opts.cwd);
+  const children: ChildProcess[] = [];
+  const cleanups: Array<() => void | Promise<void>> = [];
+  let stage: LocalStage | undefined;
+  let router: Server | undefined;
+  let shuttingDown = false;
+
+  const shutdown = async (code = 0) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    info(pc.dim('\nstopping…'));
+    for (const fn of cleanups) await fn();
+    for (const c of children) killTree(c);
+    router?.close();
+    await stage?.stop();
+    process.exit(code);
+  };
+  process.once('SIGINT', () => void shutdown(0));
+  process.once('SIGTERM', () => void shutdown(0));
+
+  try {
+    step('starting the AWS Emulator');
+    stage = await startLocalStage({
+      root,
+      manifest,
+      stage: LOCAL_STAGE,
+      port: opts.port,
+      log: (e) => {
+        if (e.level !== 'info' || process.env.PLAT_DEV_VERBOSE) info(pc.dim(`  engine ${e.level}: ${e.msg}`));
+      },
+    });
+  } catch (err) {
+    await stage?.stop();
+    if ((err as Error).message === EMULATOR_INSTALL_HINT) {
+      throw new CliError('the AWS Emulator is not installed', { hint: EMULATOR_INSTALL_HINT });
+    }
+    throw err;
+  }
+  success(`provisioned ${manifest.name} (${stage.result.resources.length} resources) in the emulator`);
+
+  const state: LocalRouterState = {
+    record: localRouteRecord({
+      app: manifest.name,
+      stage: LOCAL_STAGE,
+      deploymentId: stage.deploymentId,
+      hasServer: !!manifest.web?.server,
+      hasStatic: !!(manifest.web?.static || manifest.web?.dev),
+      serverRoutes: manifest.web?.serverRoutes ?? ['/api/'],
+      spa: manifest.web?.spa ?? true,
+    }),
+    ...(manifest.web?.static ? { staticDir: resolve(root, manifest.web.static) } : {}),
+  };
+
+  // ------------------------------------------------------------ worker
+  let dispatcher: Dispatcher | undefined;
+  let workerPort: number | undefined;
+  if (manifest.worker) {
+    const worker = await startLocalWorker(stage, manifest, root);
+    workerPort = worker.port;
+    children.push(worker.child);
+    const out = prefixer(pc.yellow('worker│'), (s) => process.stdout.write(s), { spans: opts.spans });
+    worker.child.stdout!.on('data', out);
+    worker.child.stderr!.on('data', out);
+    dispatcher = await startWorkerDispatch(stage, manifest, worker, (kind, name, outcome, detail) => {
+      if (outcome === 'error') warn(`${kind} ${name} failed${detail ? `: ${detail}` : ''}`);
+    });
+    cleanups.push(() => dispatcher?.stop());
+  }
+
+  const runCron = async (name: string) => {
+    if (!dispatcher) throw new CliError('this app has no worker');
+    if (!manifest.crons[name]) {
+      throw new CliError(`no cron named ${name}`, {
+        hint: `crons: ${Object.keys(manifest.crons).join(', ') || '(none)'}`,
+      });
+    }
+    info(`${pc.magenta('cron  │')} running ${name}`);
+    const r = await dispatcher.runCron(name);
+    if (!r.ok) throw new CliError(`cron ${name} failed: ${r.error?.message}`);
+  };
+  const crons = dispatcher
+    ? scheduleCrons(
+        Object.entries(manifest.crons).map(([name, c]): LocalCron => ({ name, ...c })),
+        (name) => runCron(name).catch((err) => warn((err as Error).message)),
+      )
+    : undefined;
+  if (crons) cleanups.push(() => crons.stop());
+
+  // ------------------------------------------------------------ web server
+  if (manifest.web?.server) {
+    const { child, port: serverPort } = await spawnWebServer(stage, manifest, root, {
+      ...(workerPort ? { workerUrl: `http://127.0.0.1:${workerPort}/` } : {}),
+    });
+    children.push(child);
+    const out = prefixer(pc.green('web   │'), (s) => process.stdout.write(s), { spans: opts.spans });
+    child.stdout!.on('data', out);
+    child.stderr!.on('data', out);
+    child.once('exit', (code) => {
+      if (!shuttingDown) warn(`web server exited (code ${code})`);
+    });
+    void waitForPort(serverPort, '127.0.0.1', 60_000)
+      .then(() => {
+        state.server = { host: '127.0.0.1', port: serverPort };
+      })
+      .catch((err) => warn(`web server did not start: ${(err as Error).message}`));
+  }
+
+  // ------------------------------------------------------------ frontend dev server
+  if (manifest.web?.dev) {
+    const { command, port } = manifest.web.dev;
+    const child = spawn(command, {
+      cwd: root,
+      shell: true,
+      detached: true,
+      env: withLocalBin(root, { ...process.env, PLATFORM_DEV_ROUTER: `http://localhost:${opts.port}` }),
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    children.push(child);
+    const out = prefixer(pc.blue('front │'), (s) => process.stdout.write(s));
+    child.stdout!.on('data', out);
+    child.stderr!.on('data', out);
+    state.webDevStarting = true;
+    // Dev servers often bind `localhost` (::1 on many systems); connect the same way.
+    void waitForPort(port, 'localhost', 60_000)
+      .then(() => {
+        state.webDev = { host: 'localhost', port };
+      })
+      .catch((err) => warn(`frontend dev server did not start: ${(err as Error).message}`))
+      .finally(() => {
+        state.webDevStarting = false;
+      });
+  }
+
+  // ------------------------------------------------------------ router
+  const intercept: Interceptor[] = [
+    async (req, res, url) => {
+      if (!url.pathname.startsWith(DEV_CONTROL_PREFIX)) return false;
+      const cron = /^\/__plat_dev\/cron\/([^/]+)$/.exec(url.pathname);
+      if (cron && req.method === 'POST') {
+        try {
+          await runCron(decodeURIComponent(cron[1]!));
+          res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ ok: true }));
+        } catch (err) {
+          res
+            .writeHead(400, { 'content-type': 'application/json' })
+            .end(JSON.stringify({ error: (err as Error).message }));
+        }
+        return true;
+      }
+      if (url.pathname === `${DEV_CONTROL_PREFIX}status`) {
+        res
+          .writeHead(200, { 'content-type': 'application/json' })
+          .end(
+            JSON.stringify({ app: manifest.name, bindings: stage!.bindings, emulator: stage!.conn.endpoint }),
+          );
+        return true;
+      }
+      res.writeHead(404).end();
+      return true;
+    },
+  ];
+  // Local sign-in (`/__platform/auth/*`) is served by the SDK's server wrapper in local mode.
+  router = await startLocalRouter({ port: opts.port, host: '127.0.0.1', state: () => state, intercept });
+
+  printBanner(manifest, stage, opts.port, crons);
+  await new Promise(() => {}); // run until signalled
+}
+
+/**
+ * The app's server exactly as the Web Function runs it (SDK wrapper, bindings,
+ * `AWS_LAMBDA_HTTP_ENDPOINT`), under `tsx watch` so edits restart it.
+ */
+export async function spawnWebServer(
+  stage: LocalStage,
+  manifest: ResolvedManifest,
+  root: string,
+  opts: { watch?: boolean; workerUrl?: string } = {},
+): Promise<{ child: ChildProcess; port: number }> {
+  if (!manifest.web?.server) throw new Error('manifest has no web.server');
+  const port = await freePort();
+  const env = localEnv(stage, manifest, {
+    AWS_LAMBDA_HTTP_ENDPOINT: `127.0.0.1:${port}`,
+    PLATFORM_LOG_PRETTY: '1',
+    PLATFORM_ENTRY: resolve(root, manifest.web.server),
+    PLATFORM_SDK_SERVER: resolveFromApp(root, SDK_SERVER),
+    // `invokeJob` locally: the SDK posts here instead of invoking the emulator's sandboxed Lambda.
+    ...(opts.workerUrl ? { PLATFORM_LOCAL_WORKER_URL: opts.workerUrl } : {}),
+  });
+  const child = spawn(process.execPath, tsxArgs('server-entry', opts.watch !== false), {
+    cwd: root,
+    env,
+    detached: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return { child, port };
+}
+
+function printBanner(
+  manifest: ResolvedManifest,
+  stage: LocalStage,
+  port: number,
+  crons: ReturnType<typeof scheduleCrons> | undefined,
+): void {
+  const b = stage.bindings;
+  const lines = [
+    '',
+    `  ${pc.bold(manifest.name)} ${pc.dim('running locally on the AWS Emulator')}`,
+    '',
+    `  ${pc.green('➜')} App:       ${pc.underline(`http://${manifest.name}.localhost:${port}`)}  ${pc.dim(`(or http://localhost:${port})`)}`,
+    `  ${pc.dim('➜')} Emulator:  ${stage.conn.endpoint}`,
+  ];
+  if (b.table) lines.push(`  ${pc.dim('➜')} Database:  ${b.table}`);
+  const queues = Object.keys(b.queues);
+  if (queues.length) lines.push(`  ${pc.dim('➜')} Queues:    ${queues.join(', ')}`);
+  if (manifest.events.length) lines.push(`  ${pc.dim('➜')} Events:    ${manifest.events.join(', ')}`);
+  if (b.storage) lines.push(`  ${pc.dim('➜')} Storage:   ${b.storage.stores.join(', ')}`);
+  if (b.auth) lines.push(`  ${pc.dim('➜')} Auth:      local sign-in at /__platform/auth/login (any email)`);
+  for (const name of Object.keys(manifest.crons)) {
+    const next = crons?.next(name);
+    lines.push(
+      `  ${pc.dim('➜')} Cron:      ${name} ${pc.dim(`next ${next?.toISOString() ?? '?'} · now: plat dev run-cron ${name}`)}`,
+    );
+  }
+  lines.push('', pc.dim('  Ctrl+C to stop. Emulator state lives in memory and is discarded on exit.'), '');
+  info(lines.join('\n'));
+}
+
+/** `plat dev run-cron <name>`: ask a running `plat dev` to fire a cron now. */
+export async function runCronOnDev(name: string, port: number): Promise<void> {
+  let res: Response;
+  try {
+    res = await fetch(`http://127.0.0.1:${port}${DEV_CONTROL_PREFIX}cron/${encodeURIComponent(name)}`, {
+      method: 'POST',
+    });
+  } catch {
+    throw new CliError(`no \`plat dev\` running on port ${port}`, {
+      hint: 'start it with `plat dev` (or pass --port)',
+    });
+  }
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as { error?: string };
+    throw new CliError(body.error ?? `HTTP ${res.status}`);
+  }
+}

package/src/dev/local-stage.ts

@@ -0,0 +1,176 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { Agent } from 'node:https';
+import { join } from 'node:path';
+import { PutParameterCommand, SSMClient } from '@aws-sdk/client-ssm';
+import {
+  type Bindings,
+  encodeBindings,
+  names,
+  newDeploymentId,
+  type PlatformRuntimeConfig,
+  type ResolvedManifest,
+} from '@ericminassian/platform-core';
+import {
+  createEngine,
+  type DeployStageResult,
+  type EmulatorConnection,
+  type Engine,
+  type EngineLogEntry,
+  emulatorChildEnv,
+  ensureLocalPlatform,
+  type S3Location,
+  startEmulator,
+} from '@ericminassian/platform-engine';
+import { bundleWorker, zipBundle } from '../build.ts';
+import { CliError } from '../util/output.ts';
+
+/**
+ * A stage running inside a private AWS Emulator: shared platform resources
+ * (`ensureLocalPlatform`) plus this app's resources, created by the same
+ * engine that deploys to AWS. The web server runs outside the emulator
+ * (`webMode: 'external'`) because the emulator doesn't serve Web Function
+ * endpoints yet.
+ */
+export interface LocalStage {
+  conn: EmulatorConnection;
+  engine: Engine;
+  platform: PlatformRuntimeConfig;
+  result: DeployStageResult;
+  bindings: Bindings;
+  deploymentId: string;
+  stage: string;
+  stop(): Promise<void>;
+}
+
+export interface StartLocalStageOptions {
+  root: string;
+  manifest: ResolvedManifest;
+  stage: 'local' | 'test';
+  /** Public port of the local router (used in URLs, auth redirects). */
+  port: number;
+  log?: (e: EngineLogEntry) => void;
+  onEmulatorLog?: (line: string) => void;
+}
+
+export async function startLocalStage(opts: StartLocalStageOptions): Promise<LocalStage> {
+  const conn = await startEmulator({ port: 0, idleTimeoutSeconds: 6 * 3600, onLog: opts.onEmulatorLog });
+  try {
+    const engine = createEngine({
+      region: conn.region,
+      emulator: { endpoint: conn.endpoint, caFile: conn.caFile, credentials: conn.credentials },
+      log: opts.log,
+    });
+    const platform = await ensureLocalPlatform(engine, { port: opts.port, jwksBaseUrl: conn.endpoint });
+    const deploymentId = newDeploymentId();
+    const worker = opts.manifest.worker
+      ? await uploadWorker(engine, platform, opts.root, opts.manifest, opts.stage, deploymentId)
+      : undefined;
+    const result = await engine.deployStage({
+      manifest: opts.manifest,
+      stage: opts.stage,
+      deploymentId,
+      platform,
+      artifacts: worker ? { worker } : {},
+      webMode: 'external',
+      logRetentionDays: 1,
+    });
+    await seedSecrets(conn, result.bindings, opts.root);
+    return {
+      conn,
+      engine,
+      platform,
+      result,
+      bindings: result.bindings,
+      deploymentId,
+      stage: opts.stage,
+      stop: () => conn.stop(),
+    };
+  } catch (err) {
+    await conn.stop();
+    throw err;
+  }
+}
+
+export async function uploadWorker(
+  engine: Engine,
+  platform: PlatformRuntimeConfig,
+  root: string,
+  manifest: ResolvedManifest,
+  stage: string,
+  deploymentId: string,
+): Promise<S3Location> {
+  const dir = await bundleWorker(root, manifest, join(root, '.plat', stage, 'worker'), { minify: false });
+  const zip = zipBundle(dir);
+  return engine.putArtifact(
+    platform,
+    names.artifactKey(manifest.name, stage, deploymentId, 'worker.zip'),
+    zip,
+  );
+}
+
+/** Environment for the local web server, worker tests and `plat test`. */
+export function localEnv(
+  stage: LocalStage,
+  manifest: ResolvedManifest,
+  extra: Record<string, string> = {},
+): NodeJS.ProcessEnv {
+  return {
+    ...emulatorChildEnv(stage.conn),
+    ...manifest.env,
+    PLATFORM_BINDINGS: encodeBindings(stage.bindings),
+    PLATFORM_LOCAL: '1',
+    ...extra,
+  };
+}
+
+/** AWS SDK client config for talking to the emulator from the CLI process itself. */
+export function emulatorClientConfig(conn: EmulatorConnection) {
+  return {
+    region: conn.region,
+    endpoint: conn.endpoint,
+    credentials: conn.credentials,
+    requestHandler: { httpsAgent: new Agent({ ca: readFileSync(conn.caFile), keepAlive: true }) },
+  };
+}
+
+/**
+ * `.env.local` (KEY=VALUE, not committed) → SecureString parameters, so
+ * `secrets.get()` works locally exactly as deployed. Only names declared in
+ * platform.json are loaded.
+ */
+async function seedSecrets(conn: EmulatorConnection, bindings: Bindings, root: string): Promise<void> {
+  const values = readDotEnv(join(root, '.env.local'));
+  const declared = new Set(bindings.secrets.names);
+  const entries = Object.entries(values).filter(([k]) => declared.has(k));
+  if (entries.length === 0) return;
+  const ssm = new SSMClient(emulatorClientConfig(conn));
+  try {
+    for (const [name, value] of entries) {
+      await ssm.send(
+        new PutParameterCommand({
+          Name: `${bindings.secrets.path}${name}`,
+          Value: value,
+          Type: 'SecureString',
+          Overwrite: true,
+        }),
+      );
+    }
+  } catch (err) {
+    throw new CliError(`could not load .env.local secrets into the emulator: ${(err as Error).message}`);
+  } finally {
+    ssm.destroy();
+  }
+}
+
+export function readDotEnv(path: string): Record<string, string> {
+  if (!existsSync(path)) return {};
+  const out: Record<string, string> = {};
+  for (const line of readFileSync(path, 'utf8').split(/\r?\n/)) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/.exec(line);
+    if (!m) continue;
+    let v = m[2]!;
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    out[m[1]!] = v;
+  }
+  return out;
+}

package/src/dev/pretty.ts

@@ -0,0 +1,90 @@
+import { isTelemetryEvent, type TelemetryEvent } from '@ericminassian/platform-core';
+import pc from 'picocolors';
+
+/**
+ * Human formatting for telemetry lines (`{"_p":1,...}`) printed by the SDK in
+ * the local web server and worker. Non-telemetry lines pass through as-is.
+ * Returns null for lines that are noise locally (spans, Lambda START/END).
+ */
+export function prettyLine(line: string, opts: { spans?: boolean } = {}): string | null {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  if (/^(START|END) RequestId:/.test(trimmed)) return null;
+  if (trimmed.startsWith('REPORT RequestId:')) {
+    const dur = /Duration: ([\d.]+) ms/.exec(trimmed)?.[1];
+    return pc.dim(`lambda invocation ${dur ? `${Math.round(Number(dur))}ms` : 'done'}`);
+  }
+  // Lambda prefixes console output with "<ts>\t<requestId>\t<LEVEL>\t" in text log format.
+  const jsonStart = trimmed.indexOf('{');
+  if (jsonStart === -1) return trimmed;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed.slice(jsonStart));
+  } catch {
+    return trimmed;
+  }
+  if (!isTelemetryEvent(parsed)) return trimmed;
+  return formatEvent(parsed, opts);
+}
+
+export function formatEvent(e: TelemetryEvent, opts: { spans?: boolean } = {}): string | null {
+  const trace = e.trace ? pc.dim(` ${e.trace.slice(0, 8)}`) : '';
+  switch (e.t) {
+    case 'req': {
+      const color = e.status >= 500 ? pc.red : e.status >= 400 ? pc.yellow : pc.green;
+      return `${pc.bold(e.method.padEnd(6))} ${e.path} ${color(String(e.status))} ${pc.dim(`${Math.round(e.dur)}ms`)}${e.cold ? pc.magenta(' cold') : ''}${trace}`;
+    }
+    case 'err': {
+      const head = `${pc.red('✗')} ${pc.red(`${e.name}: ${e.message}`)}${e.route ? pc.dim(` at ${e.route}`) : ''}${e.job ? pc.dim(` in ${e.job}`) : ''}${trace}`;
+      const stack = e.stack
+        ?.split('\n')
+        .slice(1, 4)
+        .map((l) => pc.dim(`    ${l.trim()}`))
+        .join('\n');
+      return stack ? `${head}\n${stack}` : head;
+    }
+    case 'job': {
+      const status = e.status === 'ok' ? pc.green('ok') : pc.red('error');
+      return `${pc.cyan('job')} ${e.kind}:${e.name} ${status} ${pc.dim(`${Math.round(e.dur)}ms`)}${e.attempt && e.attempt > 1 ? pc.yellow(` attempt ${e.attempt}`) : ''}${trace}`;
+    }
+    case 'log': {
+      const { _p, t, ts, app, stage, rev, trace: tr, span, parent, level, msg, ...fields } = e;
+      const color =
+        level === 'error'
+          ? pc.red
+          : level === 'warn'
+            ? pc.yellow
+            : level === 'debug'
+              ? pc.dim
+              : (s: string) => s;
+      const extra = Object.keys(fields).length ? pc.dim(` ${JSON.stringify(fields)}`) : '';
+      return `${color(level.toUpperCase().padEnd(5))} ${msg}${extra}${trace}`;
+    }
+    case 'metric':
+      return pc.blue(`metric ${e.name}=${e.value}${e.unit ? e.unit : ''}`);
+    case 'env':
+      return pc.dim(
+        `${e.runtime} environment ${e.event}${e.initMs !== undefined ? ` (${Math.round(e.initMs)}ms init)` : ''}`,
+      );
+    case 'span':
+      return opts.spans
+        ? pc.dim(`  span ${e.op}${e.name ? ` ${e.name}` : ''} ${Math.round(e.dur)}ms ${e.status}`)
+        : null;
+  }
+}
+
+/** Prefix every line of a child process stream. */
+export function prefixer(label: string, write: (s: string) => void, opts: { spans?: boolean } = {}) {
+  let buf = '';
+  return (chunk: Buffer | string) => {
+    buf += chunk.toString();
+    let idx = buf.indexOf('\n');
+    while (idx !== -1) {
+      const line = buf.slice(0, idx);
+      buf = buf.slice(idx + 1);
+      const pretty = prettyLine(line, opts);
+      if (pretty !== null) write(`${label} ${pretty.split('\n').join(`\n${label} `)}\n`);
+      idx = buf.indexOf('\n');
+    }
+  };
+}

package/src/dev/proc.ts

@@ -0,0 +1,15 @@
+import type { ChildProcess } from 'node:child_process';
+
+/**
+ * Dev children are spawned `detached` so each leads its own process group:
+ * `shell: true` commands (`pnpm --dir web dev` → pnpm → vite) and `tsx watch`
+ * fork grandchildren that a plain `child.kill()` leaves running.
+ */
+export function killTree(child: ChildProcess, signal: NodeJS.Signals = 'SIGTERM'): void {
+  if (child.exitCode !== null || child.signalCode !== null || !child.pid) return;
+  try {
+    process.kill(-child.pid, signal);
+  } catch {
+    child.kill(signal);
+  }
+}