@ericminassian/plat 0.0.0-stage → 0.1.0

package/src/commands/apps.ts

@@ -0,0 +1,102 @@
+import { validateAppName } from '@ericminassian/platform-core';
+import type { Command } from 'commander';
+import pc from 'picocolors';
+import { CliError, EXIT, result, table } from '../util/output.ts';
+import { confirmByTyping } from '../util/prompt.ts';
+import { shortTime } from '../util/time.ts';
+import { action, apiFor, type CommonOpts, withCommon } from './common.ts';
+
+export function registerApps(program: Command): void {
+  const apps = program
+    .command('apps')
+    .description('register and inspect apps (repos are created by you, not the CLI)');
+
+  withCommon(
+    apps
+      .command('create <name>')
+      .description('register an app with the platform')
+      .requiredOption('--repo <owner/name>', 'GitHub repository whose CI may deploy this app')
+      .option('--description <text>', 'one-line description'),
+  ).action(
+    action(async (name: string, opts: CommonOpts & { repo: string; description?: string }) => {
+      const err = validateAppName(name);
+      if (err) throw new CliError(err, { exitCode: EXIT.usage });
+      if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(opts.repo)) {
+        throw new CliError(`--repo must look like owner/name, got "${opts.repo}"`, { exitCode: EXIT.usage });
+      }
+      const app = await apiFor(opts).createApp({
+        name,
+        repo: opts.repo,
+        ...(opts.description ? { description: opts.description } : {}),
+      });
+      result(app, (a) =>
+        [
+          `${pc.green('✓')} registered ${pc.bold(a.name)} (deploys from ${a.repo})`,
+          '',
+          '  next:',
+          '    1. push the repo with the platform workflow (.github/workflows/platform.yml)',
+          `    2. merging to main deploys https://${a.name}.<domain>; PRs get previews`,
+        ].join('\n'),
+      );
+    }),
+  );
+
+  withCommon(apps.command('list').description('list apps you can see')).action(
+    action(async (opts: CommonOpts) => {
+      const list = await apiFor(opts).listApps();
+      result(list, (l) =>
+        table(
+          l.map((s) => ({
+            app: s.app.name,
+            repo: s.app.repo,
+            stages: s.stages.map((st) => st.stage).join(','),
+            up:
+              s.health?.up === null || s.health === null
+                ? '-'
+                : s.health.up
+                  ? pc.green('up')
+                  : pc.red('down'),
+            'req/min': s.health?.reqPerMin ?? '-',
+            p95: s.health?.p95 != null ? `${s.health.p95}ms` : '-',
+            'cost MTD': s.costMonthToDateUsd != null ? `$${s.costMonthToDateUsd.toFixed(2)}` : '-',
+          })),
+        ),
+      );
+    }),
+  );
+
+  withCommon(apps.command('show <name>').description('app details, stages and health')).action(
+    action(async (name: string, opts: CommonOpts) => {
+      const s = await apiFor(opts).getApp(name);
+      result(s, (v) =>
+        [
+          `${pc.bold(v.app.name)}  ${pc.dim(v.app.description ?? '')}`,
+          `repo: ${v.app.repo}   owners: ${v.app.owners.join(', ')}   created: ${shortTime(v.app.createdAt)}`,
+          '',
+          table(
+            v.stages.map((st) => ({
+              stage: st.stage,
+              status: st.status,
+              url: st.url,
+              deployment: st.currentDeployment ?? '',
+              updated: shortTime(st.updatedAt),
+            })),
+          ),
+        ].join('\n'),
+      );
+    }),
+  );
+
+  withCommon(
+    apps
+      .command('delete <name>')
+      .description('unregister an app (destroy its stages first)')
+      .option('--yes', 'skip the confirmation prompt'),
+  ).action(
+    action(async (name: string, opts: CommonOpts & { yes?: boolean }) => {
+      await confirmByTyping(`unregister ${name}?`, name, opts.yes);
+      await apiFor(opts).deleteApp(name);
+      result({ app: name, deleted: true }, () => `${pc.green('✓')} unregistered ${name}`);
+    }),
+  );
+}

package/src/commands/common.ts

@@ -0,0 +1,51 @@
+import { type Command, Option } from 'commander';
+import { ApiClient } from '../api.ts';
+import { resolveAppName } from '../project.ts';
+import { reportError, setJsonMode } from '../util/output.ts';
+
+export interface CommonOpts {
+  json?: boolean;
+  apiUrl?: string;
+  app?: string;
+  stage?: string;
+}
+
+/** `--json` and `--api-url` on every command. */
+export function withCommon(cmd: Command): Command {
+  return cmd
+    .option('--json', 'machine-readable JSON output on stdout')
+    .addOption(new Option('--api-url <url>', 'platform API base URL').env('PLATFORM_API_URL'));
+}
+
+/** `--app` (defaults to platform.json) and `--stage` (defaults to prod). */
+export function withTarget(cmd: Command, stageDefault: string | false = 'prod'): Command {
+  cmd.option('--app <name>', 'app name (default: from platform.json)');
+  if (stageDefault) cmd.option('--stage <stage>', 'stage', stageDefault);
+  else cmd.option('--stage <stage>', 'stage');
+  return withCommon(cmd);
+}
+
+export function apiFor(opts: CommonOpts): ApiClient {
+  return new ApiClient(opts.apiUrl ? { baseUrl: opts.apiUrl } : {});
+}
+
+export function appFor(opts: CommonOpts): string {
+  return resolveAppName(opts.app);
+}
+
+/**
+ * Wraps a command action: applies `--json`, turns errors into a concise
+ * message + hint and a meaningful exit code.
+ */
+export function action<A extends unknown[]>(fn: (...args: A) => Promise<void> | void) {
+  return async (...args: A) => {
+    const cmd = args[args.length - 1] as Command;
+    const opts = (typeof cmd?.optsWithGlobals === 'function' ? cmd.optsWithGlobals() : {}) as CommonOpts;
+    setJsonMode(!!opts.json);
+    try {
+      await fn(...args);
+    } catch (err) {
+      process.exitCode = reportError(err);
+    }
+  };
+}

package/src/commands/lifecycle.ts

@@ -0,0 +1,139 @@
+import { relative } from 'node:path';
+import { PLATFORM_DEFAULTS } from '@ericminassian/platform-core';
+import { type Command, Option } from 'commander';
+import pc from 'picocolors';
+import { initApp } from '../init.ts';
+import { CliError, EXIT, result, success } from '../util/output.ts';
+import { action, apiFor, type CommonOpts, withCommon } from './common.ts';
+
+export function registerLifecycle(program: Command): void {
+  withCommon(
+    program
+      .command('init [dir]')
+      .description('scaffold a new app from the template (local files only; create the GitHub repo yourself)')
+      .option('--name <app>', 'app name (default: directory name)')
+      .option('--force', 'write into a non-empty directory'),
+  ).action(
+    action(async (dir: string | undefined, opts: CommonOpts & { name?: string; force?: boolean }) => {
+      const target = dir ?? opts.name ?? '.';
+      const r = initApp({
+        dir: target,
+        ...(opts.name ? { name: opts.name } : {}),
+        ...(opts.force ? { force: true } : {}),
+      });
+      const rel = relative(process.cwd(), r.dir) || '.';
+      result(r, (v) =>
+        [
+          `${pc.green('✓')} created ${pc.bold(v.name)} in ${rel} (${v.files.length} files)`,
+          '',
+          '  next:',
+          rel === '.' ? '' : `    cd ${rel}`,
+          '    pnpm install',
+          '    pnpm dev                                   # local, on the AWS Emulator',
+          `    gh repo create <owner>/${v.name} --private --source . --push`,
+          `    plat apps create ${v.name} --repo <owner>/${v.name}`,
+        ]
+          .filter(Boolean)
+          .join('\n'),
+      );
+    }),
+  );
+
+  withCommon(
+    program
+      .command('build')
+      .description('bundle the app into deployable artifacts (.plat/build)')
+      .option('--out <dir>', 'output directory')
+      .option('--no-minify', 'skip minification'),
+  ).action(
+    action(async (opts: CommonOpts & { out?: string; minify: boolean }) => {
+      const { buildApp } = await import('../build.ts');
+      const r = await buildApp({
+        cwd: process.cwd(),
+        ...(opts.out ? { outDir: opts.out } : {}),
+        minify: opts.minify,
+      });
+      result({ app: r.manifest.name, files: r.files }, (v) => {
+        success(`built ${v.app}`);
+        return Object.entries(v.files)
+          .map(([k, p]) => `  ${k.padEnd(14)} ${relative(process.cwd(), p as string)}`)
+          .join('\n');
+      });
+    }),
+  );
+
+  withCommon(
+    program
+      .command('deploy')
+      .description('build and deploy (CI derives the stage: PR → pr-<n>, main → prod)')
+      .option('--stage <stage>', 'target stage (required outside CI)')
+      .option('--no-wait', "don't wait for the deployment to finish"),
+  ).action(
+    action(async (opts: CommonOpts & { stage?: string; wait: boolean }) => {
+      const { deploy } = await import('../deploy.ts');
+      const r = await deploy(apiFor(opts), {
+        cwd: process.cwd(),
+        ...(opts.stage ? { stage: opts.stage } : {}),
+        wait: opts.wait,
+      });
+      result({ deployment: r.deployment, url: r.url }, (v) => (v.url ? v.url : undefined));
+    }),
+  );
+
+  const dev = withCommon(
+    program
+      .command('dev')
+      .description('run the app locally against the AWS Emulator')
+      .addOption(
+        new Option('--port <port>', 'local router port')
+          .default(String(PLATFORM_DEFAULTS.localPort))
+          .env('PLAT_DEV_PORT'),
+      )
+      .option('--spans', 'also print trace spans (db, queue, fetch calls)'),
+  ).action(
+    action(async (opts: CommonOpts & { port: string; spans?: boolean }) => {
+      const { runDev } = await import('../dev/index.ts');
+      await runDev({
+        cwd: process.cwd(),
+        port: parsePort(opts.port),
+        ...(opts.spans ? { spans: true } : {}),
+      });
+    }),
+  );
+
+  withCommon(
+    dev
+      .command('run-cron <name>')
+      .description('fire a cron now in a running `plat dev` (same --port as `plat dev`)'),
+  ).action(
+    action(async (name: string, _opts: CommonOpts, cmd: Command) => {
+      // `--port` belongs to `plat dev` (the parent); commander parses it there.
+      const port =
+        (cmd.parent?.opts() as { port?: string } | undefined)?.port ?? String(PLATFORM_DEFAULTS.localPort);
+      const { runCronOnDev } = await import('../dev/index.ts');
+      await runCronOnDev(name, parsePort(port));
+      result({ cron: name, triggered: true }, () => `${pc.green('✓')} ran ${name}`);
+    }),
+  );
+
+  withCommon(
+    program
+      .command('test')
+      .description('run integration tests against a throwaway AWS Emulator with this app provisioned')
+      .argument('[vitestArgs...]', 'extra arguments for vitest')
+      .allowUnknownOption(),
+  ).action(
+    action(async (vitestArgs: string[]) => {
+      const { runTests } = await import('../dev/test.ts');
+      const code = await runTests({ cwd: process.cwd(), args: vitestArgs ?? [] });
+      if (code !== 0) throw new CliError(`tests failed (vitest exit ${code})`, { exitCode: code });
+    }),
+  );
+}
+
+export function parsePort(v: string): number {
+  const n = Number(v);
+  if (!Number.isInteger(n) || n <= 0 || n > 65535)
+    throw new CliError(`invalid port ${v}`, { exitCode: EXIT.usage });
+  return n;
+}

package/src/commands/manage.ts

@@ -0,0 +1,169 @@
+import { ENV_NAME_PATTERN, PROD_STAGE } from '@ericminassian/platform-core';
+import type { Command } from 'commander';
+import pc from 'picocolors';
+import { CliError, EXIT, result, table } from '../util/output.ts';
+import { confirmByTyping, prompt } from '../util/prompt.ts';
+import { shortTime } from '../util/time.ts';
+import { action, apiFor, appFor, type CommonOpts, withTarget } from './common.ts';
+import { readStdin } from './observe.ts';
+
+type TargetOpts = CommonOpts & { stage: string };
+
+export function registerManage(program: Command): void {
+  // ------------------------------------------------------------ secrets
+  const secrets = program.command('secrets').description('app secrets (values never shown)');
+
+  withTarget(secrets.command('list').description('secret names for a stage (and shared ones)')).action(
+    action(async (opts: TargetOpts) => {
+      const list = await apiFor(opts).listSecrets(appFor(opts), { stage: opts.stage });
+      result(list, (l) =>
+        table(
+          l.map((s) => ({
+            name: s.name,
+            scope: s.scope,
+            stage: s.stage ?? '',
+            updated: s.updatedAt ? shortTime(s.updatedAt) : '',
+          })),
+        ),
+      );
+    }),
+  );
+
+  withTarget(
+    secrets
+      .command('set <name> [value]')
+      .description('set a secret (value from the argument or stdin)')
+      .option('--shared', 'app-wide: every stage without its own value uses it'),
+  ).action(
+    action(async (name: string, value: string | undefined, opts: TargetOpts & { shared?: boolean }) => {
+      checkSecretName(name);
+      const v = value ?? (process.stdin.isTTY ? await prompt(`value for ${name}: `) : readStdin());
+      if (!v) throw new CliError('empty secret value', { exitCode: EXIT.usage });
+      const info = await apiFor(opts).setSecret(
+        appFor(opts),
+        name,
+        opts.shared ? { value: v, shared: true } : { value: v, stage: opts.stage },
+      );
+      result(
+        info,
+        () =>
+          `${pc.green('✓')} set ${name} (${opts.shared ? 'shared' : opts.stage}); new value applies within ~5 minutes`,
+      );
+    }),
+  );
+
+  withTarget(
+    secrets
+      .command('rm <name>')
+      .description('delete a secret')
+      .option('--shared', 'delete the app-wide value'),
+  ).action(
+    action(async (name: string, opts: TargetOpts & { shared?: boolean }) => {
+      checkSecretName(name);
+      await apiFor(opts).deleteSecret(
+        appFor(opts),
+        name,
+        opts.shared ? { shared: true } : { stage: opts.stage },
+      );
+      result({ deleted: name }, () => `${pc.green('✓')} deleted ${name}`);
+    }),
+  );
+
+  // ------------------------------------------------------------ deployments & stages
+  withTarget(program.command('deployments').description('recent deployments'), false).action(
+    action(async (opts: CommonOpts & { stage?: string }) => {
+      const list = await apiFor(opts).listDeployments(appFor(opts), opts.stage);
+      result(list, (l) =>
+        table(
+          l.map((d) => ({
+            id: d.id,
+            stage: d.stage,
+            status:
+              d.status === 'succeeded'
+                ? pc.green(d.status)
+                : d.status === 'failed'
+                  ? pc.red(d.status)
+                  : d.status,
+            commit: d.commit?.slice(0, 7) ?? '',
+            message: (d.message ?? '').slice(0, 50),
+            by: d.actor,
+            at: shortTime(d.createdAt),
+          })),
+        ),
+      );
+    }),
+  );
+
+  withTarget(program.command('stages').description('stages of an app'), false).action(
+    action(async (opts: CommonOpts) => {
+      const list = await apiFor(opts).listStages(appFor(opts));
+      result(list, (l) =>
+        table(
+          l.map((s) => ({
+            stage: s.stage,
+            status: s.status,
+            url: s.url,
+            deployment: s.currentDeployment ?? '',
+            updated: shortTime(s.updatedAt),
+          })),
+        ),
+      );
+    }),
+  );
+
+  withTarget(
+    program
+      .command('rollback')
+      .description('point a stage back at its previous deployment (instant)')
+      .option('--to <deploymentId>', 'a specific earlier deployment'),
+  ).action(
+    action(async (opts: TargetOpts & { to?: string }) => {
+      const r = await apiFor(opts).rollback(appFor(opts), opts.stage, opts.to);
+      result(r, () => `${pc.green('✓')} rolled back ${opts.stage}`);
+    }),
+  );
+
+  withTarget(
+    program
+      .command('destroy')
+      .description('delete a stage and its resources')
+      .option('--yes', 'skip the confirmation prompt')
+      .option('--force', 'required to destroy prod'),
+    false,
+  ).action(
+    action(async (opts: CommonOpts & { stage?: string; yes?: boolean; force?: boolean }) => {
+      if (!opts.stage) throw new CliError('--stage is required', { exitCode: EXIT.usage });
+      if (opts.stage === PROD_STAGE && !opts.force) {
+        throw new CliError('refusing to destroy prod', {
+          hint: 'pass --force if you really mean it',
+          exitCode: EXIT.usage,
+        });
+      }
+      const app = appFor(opts);
+      await confirmByTyping(`destroy ${app}/${opts.stage}?`, opts.stage, opts.yes);
+      await apiFor(opts).destroyStage(app, opts.stage);
+      result(
+        { app, stage: opts.stage, destroyed: true },
+        () => `${pc.green('✓')} destroying ${app}/${opts.stage}`,
+      );
+    }),
+  );
+
+  // ------------------------------------------------------------ crons
+  const cron = program.command('cron').description('scheduled jobs');
+  withTarget(cron.command('run <name>').description('run a cron now on a deployed stage')).action(
+    action(async (name: string, opts: TargetOpts) => {
+      await apiFor(opts).runCron(appFor(opts), name, opts.stage);
+      result(
+        { cron: name, stage: opts.stage, triggered: true },
+        () => `${pc.green('✓')} triggered ${name} on ${opts.stage}`,
+      );
+    }),
+  );
+}
+
+function checkSecretName(name: string): void {
+  if (!ENV_NAME_PATTERN.test(name)) {
+    throw new CliError(`secret names are UPPER_SNAKE_CASE, got "${name}"`, { exitCode: EXIT.usage });
+  }
+}