@ericminassian/plat 0.0.0-stage → 0.1.0

package/src/commands/observe.ts

@@ -0,0 +1,276 @@
+import { readFileSync } from 'node:fs';
+import type { LogLine, TelemetryEvent } from '@ericminassian/platform-core';
+import type { Command } from 'commander';
+import pc from 'picocolors';
+import { formatEvent } from '../dev/pretty.ts';
+import { CliError, EXIT, isJsonMode, result, sparkline, table } from '../util/output.ts';
+import { shortTime, sinceRange } from '../util/time.ts';
+import { action, apiFor, appFor, type CommonOpts, withTarget } from './common.ts';
+
+type TargetOpts = CommonOpts & { stage: string };
+
+export function registerObserve(program: Command): void {
+  withTarget(
+    program
+      .command('logs')
+      .description('search recent logs (web + worker); --follow streams live')
+      .option('--since <duration>', 'how far back', '1h')
+      .option('--filter <text>', 'only lines containing this text / CloudWatch filter pattern')
+      .option('--limit <n>', 'max lines', '200')
+      .option('-f, --follow', 'stream new lines (live tail)')
+      .option('--runtime', "include the Lambda runtime's own records (hidden by default)"),
+  ).action(
+    action(
+      async (
+        opts: TargetOpts & {
+          since: string;
+          filter?: string;
+          limit: string;
+          follow?: boolean;
+          runtime?: boolean;
+        },
+      ) => {
+        const keep = (l: LogLine) => opts.runtime || l.level !== 'system';
+        const api = apiFor(opts);
+        const app = appFor(opts);
+        if (opts.follow) {
+          const ac = new AbortController();
+          process.once('SIGINT', () => ac.abort());
+          try {
+            for await (const line of api.tailLogs(
+              app,
+              { stage: opts.stage, ...(opts.filter ? { filter: opts.filter } : {}) },
+              ac.signal,
+            )) {
+              if (!keep(line)) continue;
+              process.stdout.write(`${isJsonMode() ? JSON.stringify(line) : formatLogLine(line)}\n`);
+            }
+          } catch (err) {
+            if ((err as Error).name !== 'AbortError') throw err;
+          }
+          return;
+        }
+        const { from, to } = sinceRange(opts.since);
+        const res = await api.logs(app, {
+          stage: opts.stage,
+          from,
+          to,
+          limit: Number(opts.limit),
+          ...(opts.filter ? { filter: opts.filter } : {}),
+        });
+        const shown = { ...res, lines: res.lines.filter(keep) };
+        result(shown, (r) =>
+          r.lines.length ? r.lines.map(formatLogLine).join('\n') : pc.dim('(no log lines)'),
+        );
+      },
+    ),
+  );
+
+  withTarget(
+    program
+      .command('metrics')
+      .description('requests, errors, latency and jobs for a stage')
+      .option('--since <duration>', 'time range', '6h'),
+  ).action(
+    action(async (opts: TargetOpts & { since: string }) => {
+      const api = apiFor(opts);
+      const app = appFor(opts);
+      const range = sinceRange(opts.since);
+      const [metrics, routes, jobs] = await Promise.all([
+        api.metrics(app, { stage: opts.stage, ...range }),
+        api.routes(app, { stage: opts.stage, from: range.from, to: range.to }).catch(() => []),
+        api
+          .jobs(app, { stage: opts.stage, from: range.from, to: range.to })
+          .catch(() => ({ jobs: [], queues: [] })),
+      ]);
+      result({ metrics, routes, ...jobs }, (v) => {
+        const pts = v.metrics.points;
+        const total = pts.reduce((a, p) => a + p.req, 0);
+        const errors = pts.reduce((a, p) => a + p.s5xx, 0);
+        const p95s = pts.map((p) => p.p95).filter((x): x is number => x !== null);
+        const lines = [
+          `${pc.bold(app)} ${pc.dim(`${opts.stage} · last ${opts.since} · ${v.metrics.res} buckets`)}`,
+          '',
+          `  requests  ${String(total).padStart(8)}  ${sparkline(pts.map((p) => p.req))}`,
+          `  5xx       ${String(errors).padStart(8)}  ${pc.red(sparkline(pts.map((p) => p.s5xx)))}`,
+          `  p95 (ms)  ${String(p95s.length ? Math.max(...p95s) : '-').padStart(8)}  ${sparkline(pts.map((p) => p.p95))}`,
+          `  cold      ${String(pts.reduce((a, p) => a + p.cold, 0)).padStart(8)}  ${sparkline(pts.map((p) => p.cold))}`,
+        ];
+        if (v.routes.length) {
+          lines.push(
+            '',
+            pc.bold('routes'),
+            table(
+              v.routes.map((r) => ({
+                method: r.method,
+                route: r.route,
+                req: r.req,
+                '5xx': r.s5xx,
+                '4xx': r.s4xx,
+                p50: r.p50 ?? '-',
+                p95: r.p95 ?? '-',
+              })),
+            ),
+          );
+        }
+        if (v.jobs.length) {
+          lines.push(
+            '',
+            pc.bold('jobs'),
+            table(
+              v.jobs.map((j) => ({
+                job: `${j.kind}:${j.name}`,
+                ok: j.ok,
+                error: j.error,
+                p95: j.p95 ?? '-',
+                last: j.lastRun ? shortTime(j.lastRun) : '-',
+              })),
+            ),
+          );
+        }
+        if (v.queues.length) {
+          lines.push(
+            '',
+            pc.bold('queues'),
+            table(
+              v.queues.map((q) => ({
+                queue: q.name,
+                visible: q.visible,
+                inFlight: q.inFlight,
+                dlq: q.deadLetter,
+                oldest: q.oldestAgeSeconds ?? '-',
+              })),
+            ),
+          );
+        }
+        return lines.join('\n');
+      });
+    }),
+  );
+
+  withTarget(program.command('errors').description('grouped errors for a stage')).action(
+    action(async (opts: TargetOpts) => {
+      const groups = await apiFor(opts).errors(appFor(opts), { stage: opts.stage });
+      result(groups, (g) =>
+        table(
+          g.map((e) => ({
+            id: e.fingerprint,
+            status: e.status === 'open' ? pc.red('open') : e.status,
+            count: e.count,
+            error: `${e.name}: ${e.message}`.slice(0, 80),
+            where: e.sample.route ?? e.sample.job ?? '',
+            last: shortTime(e.lastSeen),
+            trace: e.sample.trace ?? '',
+          })),
+        ),
+      );
+    }),
+  );
+
+  withTarget(
+    program
+      .command('traces <traceId>')
+      .description('every event of one request/job across web, queues and worker'),
+  ).action(
+    action(async (traceId: string, opts: TargetOpts) => {
+      const t = await apiFor(opts).trace(appFor(opts), traceId, { stage: opts.stage });
+      result(t, (v) => formatTrace(v.events));
+    }),
+  );
+
+  withTarget(
+    program
+      .command('data [collection]')
+      .description('browse database collections or file stores')
+      .option('--partition <k=v...>', 'partition key values (repeatable)')
+      .option('--store <name>', 'list files in a storage store instead')
+      .option('--prefix <prefix>', 'file key prefix (with --store)')
+      .option('--cursor <cursor>', 'continue from a previous page')
+      .option('--limit <n>', 'page size', '50'),
+  ).action(
+    action(
+      async (
+        collection: string | undefined,
+        opts: TargetOpts & {
+          partition?: string[];
+          store?: string;
+          prefix?: string;
+          cursor?: string;
+          limit: string;
+        },
+      ) => {
+        const api = apiFor(opts);
+        const app = appFor(opts);
+        if (opts.store) {
+          const r = await api.files(app, {
+            stage: opts.stage,
+            store: opts.store,
+            ...(opts.prefix ? { prefix: opts.prefix } : {}),
+            ...(opts.cursor ? { cursor: opts.cursor } : {}),
+          });
+          result(
+            r,
+            (v) =>
+              `${table(v.objects.map((o) => ({ key: o.key, size: o.size, modified: o.lastModified ?? '' })))}${v.cursor ? `\n${pc.dim(`more: --cursor ${v.cursor}`)}` : ''}`,
+          );
+          return;
+        }
+        if (!collection) {
+          const cols = await api.collections(app, { stage: opts.stage });
+          result(cols, (c) => (c.length ? c.join('\n') : pc.dim('(no collections yet)')));
+          return;
+        }
+        const page = await api.items(app, {
+          stage: opts.stage,
+          collection,
+          limit: Number(opts.limit),
+          ...(opts.partition ? { partition: parsePartition(opts.partition) } : {}),
+          ...(opts.cursor ? { cursor: opts.cursor } : {}),
+        });
+        result(
+          page,
+          (v) =>
+            `${v.items.map((i) => JSON.stringify(i)).join('\n') || pc.dim('(no items)')}${v.cursor ? `\n${pc.dim(`more: --cursor ${v.cursor}`)}` : ''}`,
+        );
+      },
+    ),
+  );
+}
+
+/** `["userId=1", "kind=a"]` → `"userId=1&kind=a"` (URL-encoded pairs, as the API expects). */
+export function parsePartition(pairs: string[]): string {
+  const params = new URLSearchParams();
+  for (const p of pairs) {
+    const i = p.indexOf('=');
+    if (i <= 0) throw new CliError(`--partition expects key=value, got "${p}"`, { exitCode: EXIT.usage });
+    params.append(p.slice(0, i), p.slice(i + 1));
+  }
+  return params.toString();
+}
+
+export function formatLogLine(l: LogLine): string {
+  const ts = pc.dim(shortTime(l.ts));
+  const stream = l.stream === 'web' ? pc.green('web   ') : pc.yellow('worker');
+  const body = l.event ? (formatEvent(l.event, { spans: true }) ?? l.message) : l.message;
+  return `${ts} ${stream} ${body}`;
+}
+
+export function formatTrace(events: TelemetryEvent[]): string {
+  if (events.length === 0) return pc.dim('(no events for this trace)');
+  const sorted = [...events].sort((a, b) => a.ts - b.ts);
+  const t0 = sorted[0]!.ts;
+  return sorted
+    .map((e) => {
+      const offset = `+${String(e.ts - t0).padStart(5)}ms`;
+      return `${pc.dim(offset)} ${formatEvent(e, { spans: true }) ?? e.t}`;
+    })
+    .join('\n');
+}
+
+export function readStdin(): string {
+  try {
+    return readFileSync(0, 'utf8').replace(/\r?\n$/, '');
+  } catch {
+    return '';
+  }
+}

package/src/credentials.ts

@@ -0,0 +1,50 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/** What `plat login` stores. The token is a platform token, never a GitHub token. */
+export interface StoredCredentials {
+  apiUrl: string;
+  token: string;
+  github: string;
+  expiresAt: string;
+}
+
+export function configDir(): string {
+  if (process.env.PLAT_CONFIG_DIR) return process.env.PLAT_CONFIG_DIR;
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(base, 'plat');
+}
+
+export function credentialsPath(): string {
+  return join(configDir(), 'credentials.json');
+}
+
+export function saveCredentials(creds: StoredCredentials, path = credentialsPath()): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
+  // writeFileSync only applies `mode` when creating; enforce it on overwrite too.
+  chmodSync(path, 0o600);
+}
+
+export function loadCredentials(path = credentialsPath()): StoredCredentials | null {
+  if (!existsSync(path)) return null;
+  try {
+    const c = JSON.parse(readFileSync(path, 'utf8')) as StoredCredentials;
+    if (!c.token || !c.apiUrl) return null;
+    return c;
+  } catch {
+    return null;
+  }
+}
+
+export function clearCredentials(path = credentialsPath()): boolean {
+  if (!existsSync(path)) return false;
+  rmSync(path);
+  return true;
+}
+
+export function isExpired(c: StoredCredentials, now = Date.now()): boolean {
+  const t = Date.parse(c.expiresAt);
+  return Number.isFinite(t) && t <= now;
+}

package/src/deploy.ts

@@ -0,0 +1,138 @@
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import type {
+  ArtifactFile,
+  DeploymentEventEntry,
+  DeploymentRecord,
+  DeploymentStatus,
+  ManifestInput,
+  PresignedPost,
+} from '@ericminassian/platform-core';
+import pc from 'picocolors';
+import type { ApiClient } from './api.ts';
+import { buildApp } from './build.ts';
+import { appendStepSummary, deriveStage, gitInfo, isGitHubActions, setOutput } from './github.ts';
+import { loadProject } from './project.ts';
+import { CliError, EXIT, info, step, success } from './util/output.ts';
+
+export const TERMINAL_STATUSES: readonly DeploymentStatus[] = ['succeeded', 'failed', 'rolled_back'];
+
+export interface DeployOptions {
+  cwd: string;
+  stage?: string;
+  wait: boolean;
+  timeoutMs?: number;
+  pollMs?: number;
+}
+
+export interface DeployResult {
+  deployment: DeploymentRecord;
+  url?: string;
+}
+
+export async function deploy(api: ApiClient, opts: DeployOptions): Promise<DeployResult> {
+  const project = loadProject(opts.cwd);
+  const stage = deriveStage(opts.stage);
+  const app = project.manifest.name;
+
+  const { files } = await buildApp({ cwd: project.root });
+  // The API always issues an upload for manifest.json; `files` lists the optional bundles.
+  const fileNames = (Object.keys(files) as ArtifactFile[]).filter((f) => f !== 'manifest.json');
+  const git = gitInfo(project.root);
+
+  step(`creating deployment of ${pc.bold(app)} to ${pc.bold(stage)}`);
+  const created = await api.createDeployment(app, {
+    stage,
+    manifest: project.raw as ManifestInput,
+    files: fileNames,
+    ...git,
+  });
+  const id = created.deployment.id;
+
+  for (const name of Object.keys(files) as ArtifactFile[]) {
+    const post = created.uploads[name];
+    if (!post) throw new CliError(`the API did not return an upload URL for ${name}`);
+    step(`uploading ${name}`);
+    await uploadPresignedPost(post, files[name]!, name);
+  }
+
+  step('starting deployment');
+  let deployment = await api.startDeployment(id);
+  if (!opts.wait) {
+    info(`deployment ${id} is ${deployment.status}; follow with \`plat deployments --stage ${stage}\``);
+    return { deployment, url: deployment.url };
+  }
+
+  deployment = await waitForDeployment(api, id, {
+    timeoutMs: opts.timeoutMs ?? 15 * 60_000,
+    pollMs: opts.pollMs ?? 2_000,
+    onEvent: printEvent,
+  });
+  if (deployment.status !== 'succeeded') {
+    throw new CliError(
+      `deployment ${id} ${deployment.status}${deployment.error ? `: ${deployment.error}` : ''}`,
+      {
+        hint: `see \`plat logs --stage ${stage}\` and the events above`,
+        exitCode: EXIT.deployFailed,
+      },
+    );
+  }
+  const url = deployment.url;
+  success(`deployed ${app} to ${stage}${url ? `: ${pc.underline(url)}` : ''}`);
+  if (isGitHubActions()) {
+    if (url) setOutput('url', url);
+    setOutput('deployment', id);
+    appendStepSummary(
+      `### Deployed \`${app}\` → \`${stage}\`\n\n${url ? `**URL:** ${url}\n\n` : ''}Deployment \`${id}\`${git.commit ? ` at \`${git.commit.slice(0, 7)}\`` : ''}`,
+    );
+  }
+  return { deployment, url };
+}
+
+/** Builds the multipart body for an S3 presigned POST (policy fields first, file last). */
+export function presignedPostForm(post: PresignedPost, data: Uint8Array, filename: string): FormData {
+  const form = new FormData();
+  for (const [k, v] of Object.entries(post.fields)) form.append(k, v);
+  form.append('file', new Blob([new Uint8Array(data)]), filename);
+  return form;
+}
+
+export async function uploadPresignedPost(post: PresignedPost, path: string, name: string): Promise<void> {
+  const data = readFileSync(path);
+  const res = await fetch(post.url, { method: 'POST', body: presignedPostForm(post, data, basename(name)) });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new CliError(`upload of ${name} failed (HTTP ${res.status})`, {
+      hint: text.slice(0, 300) || undefined,
+    });
+  }
+}
+
+export async function waitForDeployment(
+  api: ApiClient,
+  id: string,
+  opts: { timeoutMs: number; pollMs: number; onEvent?: (e: DeploymentEventEntry) => void },
+): Promise<DeploymentRecord> {
+  const deadline = Date.now() + opts.timeoutMs;
+  let seen = 0;
+  for (;;) {
+    const d = await api.getDeployment(id);
+    const events = d.events ?? [];
+    for (const e of events.slice(seen)) opts.onEvent?.(e);
+    seen = Math.max(seen, events.length);
+    if (TERMINAL_STATUSES.includes(d.status)) return d;
+    if (Date.now() > deadline) {
+      throw new CliError(`timed out waiting for deployment ${id} (status ${d.status})`, {
+        exitCode: EXIT.deployFailed,
+      });
+    }
+    await new Promise((r) => setTimeout(r, opts.pollMs));
+  }
+}
+
+function printEvent(e: DeploymentEventEntry): void {
+  const color = e.level === 'error' ? pc.red : e.level === 'warn' ? pc.yellow : pc.dim;
+  info(
+    `  ${color(new Date(e.ts).toISOString().slice(11, 19))} ${e.msg}${e.resource ? pc.dim(` (${e.resource})`) : ''}`,
+  );
+}

package/src/dev/crons.ts

@@ -0,0 +1,70 @@
+import { CronExpressionParser } from 'cron-parser';
+
+/**
+ * Local stand-in for EventBridge Scheduler (the emulator creates schedules but
+ * never fires them). Same expressions as platform.json: 5-field cron in UTC
+ * (or the cron's timezone) or `rate(n unit)`.
+ */
+export interface LocalCron {
+  name: string;
+  schedule: string;
+  timezone?: string;
+}
+
+export function nextRun(cron: LocalCron, from = new Date()): Date {
+  const rate = /^rate\(\s*(\d+)\s+(minute|minutes|hour|hours|day|days)\s*\)$/.exec(cron.schedule.trim());
+  if (rate) {
+    const unit = rate[2]!.startsWith('minute')
+      ? 60_000
+      : rate[2]!.startsWith('hour')
+        ? 3_600_000
+        : 86_400_000;
+    return new Date(from.getTime() + Number(rate[1]) * unit);
+  }
+  return CronExpressionParser.parse(cron.schedule, { currentDate: from, tz: cron.timezone ?? 'UTC' })
+    .next()
+    .toDate();
+}
+
+export interface CronScheduler {
+  next(name: string): Date | undefined;
+  stop(): void;
+}
+
+export function scheduleCrons(
+  crons: LocalCron[],
+  fire: (name: string) => void | Promise<void>,
+): CronScheduler {
+  const timers = new Map<string, NodeJS.Timeout>();
+  const nexts = new Map<string, Date>();
+  const arm = (c: LocalCron) => {
+    const at = nextRun(c);
+    nexts.set(c.name, at);
+    // setTimeout caps at ~24.8 days; re-arm in steps.
+    const delay = Math.min(at.getTime() - Date.now(), 2 ** 31 - 1);
+    timers.set(
+      c.name,
+      setTimeout(
+        async () => {
+          if (Date.now() >= at.getTime() - 5) {
+            try {
+              await fire(c.name);
+            } catch {
+              // reported by `fire`
+            }
+          }
+          arm(c);
+        },
+        Math.max(delay, 0),
+      ),
+    );
+  };
+  for (const c of crons) arm(c);
+  return {
+    next: (name) => nexts.get(name),
+    stop: () => {
+      for (const t of timers.values()) clearTimeout(t);
+      timers.clear();
+    },
+  };
+}

package/src/dev/entries.ts

@@ -0,0 +1,23 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Path to tsx's CLI (it has no `./cli` export, so go through its package.json). */
+export function tsxCli(): string {
+  const pkg = createRequire(import.meta.url).resolve('tsx/package.json');
+  const bin = (JSON.parse(readFileSync(pkg, 'utf8')) as { bin: string | Record<string, string> }).bin;
+  const rel = typeof bin === 'string' ? bin : (bin.tsx ?? Object.values(bin)[0]!);
+  return join(dirname(pkg), rel);
+}
+
+/** A CLI-owned entry file next to this module (`.ts` in the repo, `.js` when published). */
+export function devEntry(name: 'server-entry' | 'worker-host'): string {
+  const ts = fileURLToPath(new URL(`./${name}.ts`, import.meta.url));
+  return existsSync(ts) ? ts : fileURLToPath(new URL(`./${name}.js`, import.meta.url));
+}
+
+/** argv for running an entry under tsx, optionally restarting on edits. */
+export function tsxArgs(name: 'server-entry' | 'worker-host', watch: boolean): string[] {
+  return watch ? [tsxCli(), 'watch', '--clear-screen=false', devEntry(name)] : [tsxCli(), devEntry(name)];
+}