@ultimat3/cli 1.0.0

package/src/cmd-db.ts

@@ -0,0 +1,187 @@
+// `x db gen|migrate|reset|studio|branch` — everything that touches the database, including the
+// branch DB that makes destructive work safe. An agent that can clone the database in a second
+// can migrate, seed and break things without a human deciding whether to let it.
+
+import { existsSync, readdirSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { branchPglite } from '@ultimat3/db';
+import { requireAppRoot } from './app-root';
+import type { CliCommand, CommandContext } from './command';
+import { resolveServices } from './dev-services';
+import { checkDrift, writeSchemaHash } from './drift';
+import { CliNotImplementedError } from './errors';
+import type { ExecResult } from './exec';
+import { execOutput } from './exec';
+import { msg } from './messages';
+import type { CommandResult, Finding } from './output';
+import { findingFrom } from './output';
+import { flagString } from './parse';
+
+export const DB_SUBCOMMANDS = ['gen', 'migrate', 'reset', 'studio', 'branch'] as const;
+
+const failure = (result: ExecResult, code: string, fix: string): Finding => ({
+  code,
+  cause: `${result.command.join(' ')} exited ${result.code}: ${execOutput(result).slice(0, 400)}`,
+  fix,
+  docs: `https://ultimate.dev/errors/${code}`,
+});
+
+/** `x db branch <name>` on a real Postgres: copy-on-write clone, cheap and disposable. */
+export function branchSql(source: string, branch: string): string {
+  return `CREATE DATABASE "${branch}" TEMPLATE "${source}"`;
+}
+
+export function branchDatabaseName(source: string, branch: string): string {
+  return `${source}_branch_${branch.replace(/[^a-zA-Z0-9_]/g, '_')}`;
+}
+
+export const previewUrl = (branch: string, port: number): string =>
+  `http://${branch}.localhost:${port}`;
+
+async function runBranch(
+  ctx: CommandContext,
+  root: string,
+  branch: string,
+): Promise<CommandResult> {
+  const services = resolveServices(root, ctx.env);
+  const port = Number.parseInt(ctx.env['PORT'] ?? '3000', 10);
+  const url = previewUrl(branch, port);
+  if (services.db.mode === 'embedded') {
+    // @ultimat3/db owns embedded branching, name validation and the on-disk layout. Shelling out
+    // to `cp` here was a second implementation of all three — and `--reflink` is a GNU-only flag.
+    try {
+      const info = await branchPglite(branch, { from: services.db.url });
+      return {
+        ok: true,
+        command: 'db',
+        summary: msg('cli.db.branch.ready', { name: branch }),
+        data: { branch, database: info.dataDir, preview: url, mode: 'embedded' },
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        command: 'db',
+        summary: msg('cli.usage'),
+        findings: [findingFrom(error)],
+      };
+    }
+  }
+  const source = services.db.url.split('/').at(-1) ?? 'postgres';
+  const database = branchDatabaseName(source, branch);
+  const psql = await ctx.runner(['psql', services.db.url, '-c', branchSql(source, database)], {
+    cwd: root,
+  });
+  if (!psql.ok) {
+    return {
+      ok: false,
+      command: 'db',
+      summary: msg('cli.usage'),
+      findings: [
+        failure(
+          psql,
+          'X_DB_BRANCH_FAILED',
+          `close open connections to "${source}" (a TEMPLATE clone needs none), then retry`,
+        ),
+      ],
+    };
+  }
+  return {
+    ok: true,
+    command: 'db',
+    summary: msg('cli.db.branch.ready', { name: branch }),
+    data: { branch, database, preview: url, mode: 'external' },
+  };
+}
+
+export const dbCommand: CliCommand = {
+  spec: {
+    name: 'db',
+    summary: 'gen, migrate, reset, studio, branch',
+    usage: 'x db gen "add publish_at" | migrate | reset | studio | branch <name>',
+    requiresApp: true,
+    subcommands: DB_SUBCOMMANDS,
+    flags: [{ name: 'name', type: 'string', summary: 'migration or branch name' }],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('db', ctx.cwd).dir;
+    const sub = ctx.args.subcommand ?? 'migrate';
+    const argument = ctx.args.positionals[0] ?? flagString(ctx.args, 'name');
+
+    if (sub === 'gen') {
+      const name = (argument ?? 'change').replace(/[^a-zA-Z0-9]+/g, '_').toLowerCase();
+      const result = await ctx.runner(['bunx', 'drizzle-kit', 'generate', '--name', name], {
+        cwd: root,
+      });
+      if (!result.ok) {
+        return {
+          ok: false,
+          command: 'db',
+          summary: msg('cli.usage'),
+          findings: [failure(result, 'X_DB_GEN_FAILED', 'x doctor --json')],
+        };
+      }
+      const hash = await writeSchemaHash(root, latestMigration(root, name));
+      return {
+        ok: true,
+        command: 'db',
+        summary: `migration ${name} generated`,
+        data: { migration: name, schemaHash: hash },
+      };
+    }
+
+    if (sub === 'migrate') {
+      const result = await ctx.runner(['bunx', 'drizzle-kit', 'migrate'], { cwd: root });
+      const drift = await checkDrift(root);
+      return {
+        ok: result.ok && drift.length === 0,
+        command: 'db',
+        summary: result.ok ? 'migrations applied' : 'migration failed',
+        findings: result.ok ? drift : [failure(result, 'X_DB_MIGRATE_FAILED', 'x db reset')],
+        data: { applied: result.ok },
+      };
+    }
+
+    if (sub === 'reset') {
+      const services = resolveServices(root, ctx.env);
+      if (services.db.mode === 'external') {
+        throw new CliNotImplementedError({
+          feature: 'x db reset against an external Postgres',
+          fix: 'drop and recreate the database yourself, then run: x db migrate',
+        });
+      }
+      await rm(join(services.stateDir, 'pgdata'), { recursive: true, force: true });
+      const migrate = await ctx.runner(['bunx', 'drizzle-kit', 'migrate'], { cwd: root });
+      return {
+        ok: migrate.ok,
+        command: 'db',
+        summary: migrate.ok ? 'database reset and migrated' : 'reset failed',
+        findings: migrate.ok ? [] : [failure(migrate, 'X_DB_MIGRATE_FAILED', 'x doctor --json')],
+        data: { stateDir: services.stateDir },
+      };
+    }
+
+    if (sub === 'studio') {
+      const result = await ctx.runner(['bunx', 'drizzle-kit', 'studio'], { cwd: root });
+      return {
+        ok: result.ok,
+        command: 'db',
+        summary: result.ok ? 'studio exited' : 'studio failed to start',
+        findings: result.ok ? [] : [failure(result, 'X_DB_STUDIO_FAILED', 'x doctor --json')],
+      };
+    }
+
+    return runBranch(ctx, root, argument ?? 'preview');
+  },
+};
+
+/** drizzle-kit names files `<index>_<name>.sql`; the hash sidecar has to match that base name. */
+function latestMigration(root: string, name: string): string {
+  const dir = join(root, 'packages', 'db', 'migrations');
+  if (!existsSync(dir)) return `0000_${name}`;
+  const matches = readdirSync(dir)
+    .filter((file) => file.endsWith(`_${name}.sql`))
+    .sort();
+  const newest = matches.at(-1);
+  return newest === undefined ? `0000_${name}` : newest.replace(/\.sql$/, '');
+}

package/src/cmd-deploy.ts

@@ -0,0 +1,124 @@
+// `x deploy` — containers only. The framework knows about images, roles and a registry; it does
+// not know the name of a cloud, a KV store or an edge runtime (axiom 7). What it emits is a plan
+// anything that runs containers can execute.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { requireAppRoot } from './app-root';
+import type { CliCommand, CommandContext } from './command';
+import { CliNotImplementedError } from './errors';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { flagBool, flagString } from './parse';
+
+export const DEPLOY_ROLES = ['migrate', 'web', 'sync', 'worker', 'scheduler'] as const;
+
+export interface DeployPlan {
+  readonly image: string;
+  /** Ordered: migrate runs to completion before any role that serves traffic starts. */
+  readonly steps: readonly { readonly role: string; readonly command: readonly string[] }[];
+}
+
+export function planDeploy(image: string, method: 'compose' | 'helm', root: string): DeployPlan {
+  if (method === 'helm') {
+    return {
+      image,
+      steps: [
+        {
+          role: 'all',
+          command: [
+            'helm',
+            'upgrade',
+            '--install',
+            'app',
+            join(root, 'docker', 'helm'),
+            '--set',
+            `image=${image}`,
+          ],
+        },
+      ],
+    };
+  }
+  return {
+    image,
+    steps: DEPLOY_ROLES.map((role) => ({
+      role,
+      command: [
+        'docker',
+        'compose',
+        '-f',
+        join(root, 'docker', 'docker-compose.prod.yml'),
+        role === 'migrate' ? 'run' : 'up',
+        role === 'migrate' ? '--rm' : '-d',
+        role,
+      ],
+    })),
+  };
+}
+
+export const deployCommand: CliCommand = {
+  spec: {
+    name: 'deploy',
+    summary: 'run the container deploy plan: migrate first, then the serving roles',
+    usage: 'x deploy --image repo/app:tag [--method compose|helm] [--dry-run] [--json]',
+    requiresApp: true,
+    flags: [
+      { name: 'image', type: 'string', summary: 'image reference to deploy' },
+      { name: 'method', type: 'string', summary: 'compose | helm', default: 'compose' },
+      { name: 'dry-run', type: 'boolean', summary: 'print the plan, run nothing' },
+      { name: 'critical', type: 'boolean', summary: 'security deploy: forces clients to reload' },
+    ],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('deploy', ctx.cwd).dir;
+    const image = flagString(ctx.args, 'image') ?? 'ultimate-app:dev';
+    const method = flagString(ctx.args, 'method') === 'helm' ? 'helm' : 'compose';
+    if (method === 'helm' && !existsSync(join(root, 'docker', 'helm'))) {
+      throw new CliNotImplementedError({
+        feature: 'helm deploy without docker/helm in the app',
+        fix: 'copy docker/helm from the framework repo, or use: x deploy --method compose',
+      });
+    }
+    const plan = planDeploy(image, method, root);
+    const planJson: JsonValue = {
+      image: plan.image,
+      method,
+      critical: flagBool(ctx.args, 'critical'),
+      steps: plan.steps.map((step) => ({ role: step.role, command: step.command.join(' ') })),
+    };
+    if (flagBool(ctx.args, 'dry-run')) {
+      return {
+        ok: true,
+        command: 'deploy',
+        summary: msg('cli.deploy.plan', { images: 1, roles: DEPLOY_ROLES.join(',') }),
+        data: planJson,
+        lines: plan.steps.map((step) => `  ${step.role.padEnd(10)} ${step.command.join(' ')}`),
+      };
+    }
+    for (const step of plan.steps) {
+      const result = await ctx.runner(step.command, { cwd: root });
+      if (!result.ok) {
+        return {
+          ok: false,
+          command: 'deploy',
+          summary: msg('cli.deploy.plan', { images: 1, roles: step.role }),
+          findings: [
+            {
+              code: 'X_DEPLOY_FAILED',
+              cause: `role "${step.role}" step exited ${result.code}`,
+              fix: `${step.command.join(' ')}   # run it directly to see the full output`,
+              docs: 'https://ultimate.dev/errors/X_DEPLOY_FAILED',
+            },
+          ],
+          data: planJson,
+        };
+      }
+    }
+    return {
+      ok: true,
+      command: 'deploy',
+      summary: msg('cli.deploy.plan', { images: 1, roles: DEPLOY_ROLES.join(',') }),
+      data: planJson,
+    };
+  },
+};

package/src/cmd-dev.ts

@@ -0,0 +1,286 @@
+// `x dev` — the app, booted. Every role in one Bun process, embedded Postgres/events/storage
+// started for real, the app's own modules loaded into the framework's registries, and the route
+// table those registries hold served over HTTP. `@ultimat3/admin`'s `/_x` dashboard is mounted
+// alongside it — mounted, never re-implemented — so an agent can introspect the running app.
+// No Docker, no env setup: an unset variable means the embedded default.
+
+import { watch } from 'node:fs';
+import { join } from 'node:path';
+import { listActions, toRoute } from '@ultimat3/action';
+import type { Role } from '@ultimat3/core';
+import { configureTelemetry, noopExporter } from '@ultimat3/core';
+import type { Route } from '@ultimat3/http';
+import type { Manifest } from '@ultimat3/manifest';
+import { MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { loadApp } from './app-load';
+import { appManifest } from './app-manifest';
+import { requireAppRoot } from './app-root';
+import type { CliCommand, CommandContext } from './command';
+import { assetRoutes } from './dev-assets';
+import type { DevDashboardInput, DevStatus } from './dev-dashboard';
+import { devDashboardRoutes, devPanels } from './dev-dashboard';
+import { appRoutes } from './dev-render';
+import type { RunningRoles } from './dev-roles';
+import { DEV_ROLES, selectRoles, startRoles } from './dev-roles';
+import type { RunningServices } from './dev-runtime';
+import { cdnLabel, describeCdn, describeMail, mailLabel, startServices } from './dev-runtime';
+import type { DevServices } from './dev-services';
+import { describeServices, resolveServices } from './dev-services';
+import { createTraceRecorder } from './dev-traces';
+import { holdUntilShutdown } from './hold';
+import { msg } from './messages';
+import type { CommandResult, Finding } from './output';
+import { findingFrom } from './output';
+import { flagString } from './parse';
+
+const DEFAULT_PORT = 3000;
+
+export interface DevServer {
+  readonly url: string;
+  readonly services: DevServices;
+  readonly roles: readonly Role[];
+  /** The manifest as it stands now — a reload that registers a new route moves it. */
+  readonly buildId: string;
+  /** Modules that would not import, primitives that would not register, reloads that would not build. */
+  readonly findings: readonly Finding[];
+  readonly running: RunningRoles;
+  readonly runtime: RunningServices;
+  /** Panel keys `/_x` mounted, in tab order. Reported so `--json` names what is reachable. */
+  readonly panels: readonly string[];
+  stop(): Promise<void>;
+}
+
+interface DevState {
+  manifest: Manifest;
+  reloads: number;
+  /** A save that will not build. Replaced on every attempt, so a fixed file clears it. */
+  reloadFinding: Finding | undefined;
+}
+
+/** Debounced: a save that touches five files is one reload, not five. */
+function watchApp(root: string, onChange: (file: string) => void): () => void {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let last = '';
+  const watcher = watch(root, { recursive: true }, (_event, filename) => {
+    if (filename === null || filename.includes('.x/') || filename.includes('node_modules')) return;
+    last = filename;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = setTimeout(() => onChange(last), 30);
+  });
+  return () => {
+    if (timer !== undefined) clearTimeout(timer);
+    watcher.close();
+  };
+}
+
+export interface StartDevOptions {
+  readonly root: string;
+  readonly port: number;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly roles?: readonly Role[];
+  readonly onReload?: (file: string, durationMs: number) => void;
+}
+
+/**
+ * The environment `devDashboard` refuses to mount in. Spread conditionally rather than passed as
+ * `undefined`: `exactOptionalPropertyTypes` makes "absent" and "explicitly undefined" different
+ * answers, and only the absent one lets the dashboard read the process environment itself.
+ */
+const envOf = (env: StartDevOptions['env']): { env?: string } => {
+  const value = env['NODE_ENV'] ?? env['X_ENV'];
+  return value === undefined ? {} : { env: value };
+};
+
+/**
+ * Boot order is the production order: services first, then the app's modules (importing them IS
+ * the registration), then the roles that serve what those modules registered. A module that
+ * fails to import becomes a finding rather than a dead process — the point of the dev loop is to
+ * still be reachable while something is broken.
+ */
+export async function startDev(options: StartDevOptions): Promise<DevServer> {
+  const services = resolveServices(options.root, options.env);
+  const runtime: RunningServices = await startServices(services, options.env);
+  // Installed before the app loads, so a span opened during registration is already recorded.
+  // Tracing is always on in the framework and free until an exporter is configured; `x dev` is
+  // what configures one, which is the whole reason `/_x/timeline` has anything to draw.
+  const traces = createTraceRecorder();
+  configureTelemetry({ exporter: traces.exporter });
+  const app = await loadApp(options.root);
+  const state: DevState = {
+    manifest: (await appManifest(options.root)).manifest,
+    reloads: 0,
+    reloadFinding: undefined,
+  };
+  // The manifest's build id is a content hash of every fact below it, so a dev document's
+  // `x-ultimate-build` header names the exact shape the client was served against. Pinned at
+  // boot on purpose: the header is handed to the HTTP config and the render modes once, and a
+  // reload cannot re-pin it — `state.manifest.buildId` is what `/_x` and `--json` report, so a
+  // divergence between the two is visible rather than silent, and a restart closes it.
+  const buildId = state.manifest.buildId;
+
+  let server: DevServer;
+  // Read at request time, never captured at boot: `/_x/services` must report the reload counter
+  // and the findings as they are now, not as they were when the route table was built.
+  const dashboard: DevDashboardInput = {
+    root: options.root,
+    runtime,
+    status: (): DevStatus => ({
+      url: server.url,
+      services: server.services,
+      roles: server.roles,
+      findings: server.findings,
+      reloads: state.reloads,
+    }),
+    traces,
+    ...envOf(options.env),
+  };
+  const panels = devPanels(dashboard).map((panel) => panel.key);
+
+  const routes: readonly Route[] = [
+    ...devDashboardRoutes(dashboard),
+    ...listActions().map(toRoute),
+    // The image pipeline's only HTTP surface: the icons the web manifest declares, and the
+    // variants every `srcset` promises. Mounted before the app's own routes so a page route can
+    // never shadow `/icons` or `/media`.
+    ...assetRoutes({ root: options.root, storage: runtime.storage }),
+    ...appRoutes({ buildId }),
+  ];
+
+  const running = await startRoles({
+    roles: options.roles ?? DEV_ROLES,
+    port: options.port,
+    buildId,
+    runtime,
+    routes,
+    env: options.env,
+  });
+
+  const stopWatching = watchApp(options.root, (file) => {
+    const started = performance.now();
+    void appManifest(options.root)
+      .then(({ manifest }) => {
+        state.manifest = manifest;
+        state.reloads += 1;
+        state.reloadFinding = undefined;
+        options.onReload?.(file, Math.round(performance.now() - started));
+      })
+      // Same rule as a module that will not import: a save the manifest cannot be rebuilt from is
+      // a finding on `/_x`, never an unhandled rejection that takes the dev server down.
+      .catch((error: unknown) => {
+        state.reloadFinding = { ...findingFrom(error), at: file };
+      });
+  });
+
+  server = {
+    url: running.url ?? `http://localhost:${options.port}`,
+    services,
+    roles: running.roles,
+    get buildId(): string {
+      return state.manifest.buildId;
+    },
+    // A getter, not a snapshot: `/_x` and `--json` must show the reload that just failed, not the
+    // findings as they were when the route table was built.
+    get findings(): readonly Finding[] {
+      return state.reloadFinding === undefined
+        ? app.findings
+        : [...app.findings, state.reloadFinding];
+    },
+    running,
+    runtime,
+    panels,
+    async stop() {
+      stopWatching();
+      await running.stop();
+      await runtime.stop();
+      // Released after the roles: a span opened by an in-flight request still has an exporter to
+      // end into. `configureTelemetry` merges, so handing back the noop is how it is uninstalled —
+      // leaving it in place would keep every span of the next `startDev` in this process's buffer.
+      configureTelemetry({ exporter: noopExporter });
+      traces.reset();
+    },
+  };
+  return server;
+}
+
+export const devCommand: CliCommand = {
+  spec: {
+    name: 'dev',
+    summary: 'all roles in one process: embedded services, sub-second reload, /_x mounted',
+    usage: 'x dev [--port 3000] [--role web,worker] [--json]',
+    requiresApp: true,
+    flags: [
+      { name: 'port', type: 'string', summary: 'HTTP port', default: String(DEFAULT_PORT) },
+      {
+        name: 'role',
+        type: 'string',
+        summary: `roles to run (default: all of ${DEV_ROLES.join(',')})`,
+      },
+      { name: 'once', type: 'boolean', summary: 'boot, report, exit — for smoke tests and CI' },
+    ],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('dev', ctx.cwd).dir;
+    const port = Number.parseInt(flagString(ctx.args, 'port') ?? String(DEFAULT_PORT), 10);
+    const roles = selectRoles(flagString(ctx.args, 'role'));
+    const server = await startDev({
+      root,
+      port,
+      roles,
+      env: ctx.env,
+      onReload: (file, durationMs) => {
+        if (!ctx.args.json)
+          process.stdout.write(`${msg('cli.dev.hmr', { file, ms: durationMs })}\n`);
+      },
+    });
+    const result: CommandResult = {
+      ok: server.findings.length === 0,
+      command: 'dev',
+      summary: msg('cli.dev.ready', {
+        url: server.url,
+        panels: server.panels.length,
+        // Rendered text, so the mail and CDN halves come from the catalog; `data` below carries the
+        // status values a script parses, which is why the two are different calls and not one.
+        services: `${describeServices(server.services)} ${mailLabel(server.runtime)} ${cdnLabel(server.runtime)}`,
+      }),
+      findings: server.findings,
+      // Every fact `lines` prints is a fact `--json` carries, `manifest` included — or the two
+      // renderers have drifted and only one of them can be scripted against.
+      data: {
+        url: server.url,
+        roles: [...server.roles],
+        sync: server.running.syncUrl,
+        stateDir: server.services.stateDir,
+        db: server.services.db.url,
+        events: server.services.events.url,
+        storage: server.services.storage.url,
+        // The selecting env key, never the credential behind it: `SMTP_URL` carries a password
+        // and this line is printed, logged and scraped.
+        mail: describeMail(server.runtime),
+        cdn: describeCdn(server.runtime),
+        // The slot this process holds, or null when the replicator was not selected. Two of these
+        // on one database is the one topology mistake that cannot be seen from the outside, so the
+        // slot is a scriptable fact rather than a line in a log.
+        replicationSlot: server.running.replicator?.slot ?? null,
+        buildId: server.buildId,
+        manifest: join(root, MANIFEST_FILENAME),
+        introspect: `${server.url}/_x`,
+        panels: [...server.panels],
+      },
+      lines: [
+        msg('cli.dev.roles', { roles: server.roles.join(', ') }),
+        msg('cli.dev.panels', { panels: server.panels.join(', ') }),
+        msg('cli.dev.manifest', { path: join(root, MANIFEST_FILENAME) }),
+        msg('cli.dev.introspect', { url: `${server.url}/_x` }),
+      ],
+    };
+    if (ctx.args.flags.get('once') === true) {
+      await server.stop();
+      return result;
+    }
+    // Long-running: `dispatch` awaits this instead of exiting, so the watcher keeps reloading and
+    // `/_x` stays reachable. Ctrl-C drains the web role through core's phases first and releases
+    // the embedded Postgres, the worker and the watcher after — a hard kill leaves the PGlite
+    // directory locked by a process that no longer exists.
+    return { ...result, hold: holdUntilShutdown('dev', () => server.stop()) };
+  },
+};