@ultimat3/cli 1.2.0 → 3.0.0

package/src/cmd-build.ts

@@ -3,13 +3,15 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { frameworkVersion, VERSION_DEFINE } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
 import { runVerify } from './cmd-verify';
 import type { CliCommand, CommandContext } from './command';
 import { BuildEntryMissingError, UnknownCommandError } from './errors';
+import type { ExecResult } from './exec';
 import { execOutput } from './exec';
 import { msg } from './messages';
-import type { CommandResult, Finding } from './output';
+import type { CommandResult } from './output';
 import { flagString } from './parse';
 
 export const BUILD_TARGETS = ['docker', 'binary', 'static'] as const;
@@ -51,12 +53,20 @@ export function dockerArgs(root: string, tag: string): readonly string[] {
   return ['docker', 'build', '-f', join(root, BUILD_ENTRY.docker), '-t', tag, root];
 }
 
+/**
+ * The define is not optional. A single-file executable carries no `package.json`, so
+ * `frameworkVersion()` has nothing to read and throws — which is exactly how this target came to
+ * compile an artifact that could never boot. The value is this CLI's own `@ultimat3/core`, which is
+ * the app's too: the packages release in lockstep and `x new` pins them together.
+ */
 export function binaryArgs(root: string, out: string): readonly string[] {
   return [
     'bun',
     'build',
     '--compile',
     '--minify',
+    '--define',
+    `${VERSION_DEFINE}=${JSON.stringify(frameworkVersion())}`,
     join(root, BUILD_ENTRY.binary),
     '--outfile',
     out,
@@ -76,6 +86,57 @@ export function argsFor(
   return staticArgs(paths.root, paths.out);
 }
 
+/**
+ * The static gate refused, so nothing was built. Reported under `build`, not `verify`: `command`
+ * is the field an agent keys `--json` off, and answering `"verify"` sent it to re-run a gate it
+ * never asked for while hiding that the build had not started. The steps and the summary are the
+ * gate's own — they are what says which check to fix.
+ */
+export function preflightResult(verify: CommandResult): CommandResult {
+  return { ...verify, command: 'build' };
+}
+
+/**
+ * The build's result from the builder's, kept pure so the two things a reader acts on — the
+ * summary line and the `--json` payload — are testable without spawning `docker`.
+ *
+ * `summary` used to be `msg('cli.build.done')` whatever the exit code, so a failed build printed
+ * `✗ built docker`; and the builder's own logs went only into `lines`, which is declared human-only
+ * and which `renderJson` drops — so CI, which runs `--json`, got the exit code and nothing to act
+ * on. The output now rides in `data` and `lines` renders that same string.
+ */
+export function buildResult(input: {
+  readonly target: BuildTarget;
+  readonly artifact: string;
+  readonly command: readonly string[];
+  readonly result: ExecResult;
+}): CommandResult {
+  const { result, target } = input;
+  const output = result.ok ? '' : execOutput(result);
+  return {
+    ok: result.ok,
+    command: 'build',
+    summary: msg(result.ok ? 'cli.build.done' : 'cli.build.failed', { target }),
+    findings: result.ok
+      ? []
+      : [
+          {
+            code: 'X_BUILD_FAILED',
+            cause: `${input.command.join(' ')} exited ${result.code}`,
+            fix: target === 'docker' ? 'x doctor --json && docker info' : 'x verify --json',
+            docs: 'https://ultimate.dev/errors/X_BUILD_FAILED',
+          },
+        ],
+    data: {
+      target,
+      artifact: input.artifact,
+      durationMs: result.durationMs,
+      ...(result.ok ? {} : { output }),
+    },
+    lines: result.ok ? [] : output.split('\n'),
+  };
+}
+
 export const buildCommand: CliCommand = {
   spec: {
     name: 'build',
@@ -103,31 +164,18 @@ export const buildCommand: CliCommand = {
     );
     const verifyResult = await runVerify(verifySteps, { root, runner: ctx.runner });
     if (!verifyResult.ok) {
-      return verifyResult;
+      return preflightResult(verifyResult);
     }
 
     const out =
       flagString(ctx.args, 'out') ?? join(root, '.x', target === 'static' ? 'static' : 'app');
     const tag = flagString(ctx.args, 'tag') ?? 'ultimate-app:dev';
     const command = argsFor(target, { root, tag, out });
-    const result = await ctx.runner(command, { cwd: root });
-    const findings: readonly Finding[] = result.ok
-      ? []
-      : [
-          {
-            code: 'X_BUILD_FAILED',
-            cause: `${command.join(' ')} exited ${result.code}`,
-            fix: target === 'docker' ? 'x doctor --json && docker info' : 'x verify --json',
-            docs: 'https://ultimate.dev/errors/X_BUILD_FAILED',
-          },
-        ];
-    return {
-      ok: result.ok,
-      command: 'build',
-      summary: msg('cli.build.done', { target }),
-      findings,
-      data: { target, artifact: target === 'docker' ? tag : out, durationMs: result.durationMs },
-      lines: result.ok ? [] : execOutput(result).split('\n'),
-    };
+    return buildResult({
+      target,
+      artifact: target === 'docker' ? tag : out,
+      command,
+      result: await ctx.runner(command, { cwd: root }),
+    });
   },
 };

package/src/cmd-db-branch.ts

@@ -0,0 +1,219 @@
+// `x db branch ls|create|drop` — the wiring alone: which verb, which database, which refusal.
+// A VERB is required and comes from a closed set, so a branch name can never be read as one:
+// `x db branch ls` used to clone a database called `ls`, because the argument was the name.
+// The facts (what a branch is, per mode) are `db-branch.ts`; the client lifetime is here.
+
+import { createPostgresClient, type DbClient } from '@ultimat3/db';
+import type { CommandContext } from './command';
+import type { BranchRow } from './db-branch';
+import {
+  BRANCH_SUBCOMMANDS,
+  branchDatabaseName,
+  createExternalBranch,
+  createPgliteBranch,
+  databaseNameOf,
+  dropExternalBranch,
+  dropPgliteBranch,
+  isBranchName,
+  isBranchSubcommand,
+  listExternalBranches,
+  listPgliteBranches,
+  pgliteBranchLocation,
+  previewUrl,
+} from './db-branch';
+import { stepFinding } from './db-finding';
+import type { DevServices } from './dev-services';
+import { resolveServices } from './dev-services';
+import { MissingPositionalError, UnknownCommandError } from './errors';
+import { msg } from './messages';
+import type { CommandResult, Finding } from './output';
+import { flagString, nearest } from './parse';
+import { portFromEnv } from './serve';
+import { renderTable } from './table';
+
+/**
+ * Always runnable, always the next thing a caller needs: what branches there are. Spelled twice
+ * because `UnknownCommandError` prefixes its `suggestion` with `x ` and `MissingPositionalError`
+ * takes a whole invocation — one of them handed back `x x db branch ls --json`.
+ */
+const LIST_ARGV = 'db branch ls --json';
+const LIST_FIX = `x ${LIST_ARGV}`;
+
+/**
+ * A near miss on a three-verb set is a typo; anything else is the bare-name form this replaced —
+ * `x db branch feat-new-billing` used to CREATE, so the refusal hands the caller's own name back
+ * inside the command that still does it. Every answer here is a complete, runnable invocation,
+ * `x` excluded — the error class adds it.
+ */
+function branchRetry(word: string, name: string | undefined): string {
+  const near = nearest(word, [...BRANCH_SUBCOMMANDS]);
+  if (near !== undefined) return name === undefined ? LIST_ARGV : `db branch ${near} ${name}`;
+  return isBranchName(word) ? `db branch create ${word}` : LIST_ARGV;
+}
+
+/**
+ * `x db branch` against an external Postgres, on ONE connection.
+ *
+ * `role: 'migrate'` is the profile, not a decoration: it is `max: 1` with no statement timeout, and
+ * both halves are load-bearing. `CREATE DATABASE ... TEMPLATE` is refused while any OTHER session
+ * is connected to the template, so a pool that spread three statements over three connections
+ * would leave two idle sessions holding the source open against itself; and cloning a real
+ * database routinely outlives the 10s a `web` profile allows.
+ */
+async function withBranchClient<T>(url: string, fn: (client: DbClient) => Promise<T>): Promise<T> {
+  const client = createPostgresClient({ url, role: 'migrate', applicationName: 'x-db-branch' });
+  try {
+    return await fn(client);
+  } finally {
+    // Or the CLI exits holding a connection, and the next command waits for it to time out.
+    await client.close();
+  }
+}
+
+const branchesOf = (services: DevServices): Promise<readonly BranchRow[]> =>
+  services.db.mode === 'embedded'
+    ? listPgliteBranches(services.db.url)
+    : withBranchClient(services.db.url, listExternalBranches);
+
+const failure = (summary: string, finding: Finding): CommandResult => ({
+  ok: false,
+  command: 'db',
+  summary,
+  findings: [finding],
+});
+
+export async function runBranchCommand(ctx: CommandContext, root: string): Promise<CommandResult> {
+  const verb = ctx.args.positionals[0];
+  if (verb === undefined) {
+    throw new MissingPositionalError({
+      command: 'db branch',
+      positional: BRANCH_SUBCOMMANDS.join('|'),
+      example: LIST_FIX,
+    });
+  }
+  const name = ctx.args.positionals[1] ?? flagString(ctx.args, 'name');
+  if (!isBranchSubcommand(verb)) {
+    throw new UnknownCommandError({
+      path: `db branch ${verb}`,
+      known: BRANCH_SUBCOMMANDS,
+      suggestion: branchRetry(verb, name),
+    });
+  }
+  const services = resolveServices(root, ctx.env);
+  if (verb === 'ls') return runList(services);
+  if (name === undefined) {
+    throw new MissingPositionalError({
+      command: `db branch ${verb}`,
+      positional: 'name',
+      example: `x db branch ${verb} feature-x`,
+    });
+  }
+  return verb === 'create' ? runCreate(ctx, services, name) : runDrop(services, name);
+}
+
+const row = (branch: BranchRow): readonly string[] => [
+  branch.name,
+  branch.location,
+  branch.createdAt ?? msg('cli.db.branch.unknown'),
+  branch.sizeBytes === null ? msg('cli.db.branch.unknown') : String(branch.sizeBytes),
+];
+
+async function runList(services: DevServices): Promise<CommandResult> {
+  let branches: readonly BranchRow[];
+  try {
+    branches = await branchesOf(services);
+  } catch (error) {
+    return failure(msg('cli.db.branch.failed'), stepFinding(error, 'X_DB_BRANCH_FAILED'));
+  }
+  return {
+    ok: true,
+    command: 'db',
+    summary:
+      branches.length === 0
+        ? msg('cli.db.branch.none')
+        : msg('cli.db.branch.listed', { count: branches.length }),
+    lines:
+      branches.length === 0
+        ? []
+        : renderTable(['name', 'location', 'created-at', 'size-bytes'], branches.map(row)).map(
+            (line) => `  ${line}`,
+          ),
+    data: branches.map((branch) => ({ ...branch })),
+  };
+}
+
+async function runCreate(
+  ctx: CommandContext,
+  services: DevServices,
+  name: string,
+): Promise<CommandResult> {
+  // `portFromEnv`, never a bare `Number.parseInt`: the latter reads `PORT=abc` as `NaN` and put
+  // `http://feat.localhost:NaN` in `data.preview` — a machine-readable field naming no port.
+  const port = portFromEnv(ctx.env);
+  let branch: BranchRow;
+  try {
+    branch =
+      services.db.mode === 'embedded'
+        ? await createPgliteBranch(services.db.url, name)
+        : await withBranchClient(services.db.url, (client) => createExternalBranch(client, name));
+  } catch (error) {
+    return failure(msg('cli.db.branch.failed'), stepFinding(error, 'X_DB_BRANCH_FAILED'));
+  }
+  return {
+    ok: true,
+    command: 'db',
+    summary: msg('cli.db.branch.ready', { name: branch.name }),
+    data: {
+      branch: branch.name,
+      database: branch.location,
+      preview: previewUrl(branch.name, port),
+      mode: services.db.mode,
+    },
+  };
+}
+
+/**
+ * You may only drop what `ls` shows, and that is the whole guard — stronger than a confirmation
+ * flag, because it is the typo that is impossible rather than the keystroke that is tedious. An
+ * external branch is a database carrying `createBranch`'s marker comment AND this database's own
+ * prefix, so neither the shared database this session is connected to nor another app's clone on
+ * the same server is in the set; an embedded one is a `pgdata-<name>` directory, so `pgdata` itself
+ * is not either. `@ultimat3/db`'s own `X_BRANCH_EXISTS` fix line is `x db branch drop <name>` with
+ * no flag on it, so a flag here would break a shipped instruction.
+ *
+ * The check is not made here, and that is the point: `false` from either drop means "there was no
+ * such branch", decided by the same call that deletes, on the same connection, one statement
+ * earlier. A listing taken here and acted on below is two connections and a window wide enough to
+ * hold a whole `create` — and the wiring layer is exactly where a guard must not live.
+ */
+async function runDrop(services: DevServices, name: string): Promise<CommandResult> {
+  try {
+    const dropped =
+      services.db.mode === 'embedded'
+        ? await dropPgliteBranch(services.db.url, name)
+        : await withBranchClient(services.db.url, (client) => dropExternalBranch(client, name));
+    if (!dropped) return notABranch(services, name);
+    return {
+      ok: true,
+      command: 'db',
+      summary: msg('cli.db.branch.dropped', { name }),
+      data: { branch: name, mode: services.db.mode },
+    };
+  } catch (error) {
+    return failure(msg('cli.db.branch.failed'), stepFinding(error, 'X_DB_BRANCH_FAILED'));
+  }
+}
+
+/** Names what the drop WOULD have touched, so the refusal is checkable rather than assertable. */
+function notABranch(services: DevServices, name: string): CommandResult {
+  const target =
+    services.db.mode === 'embedded'
+      ? pgliteBranchLocation(services.db.url, name)
+      : branchDatabaseName(databaseNameOf(services.db.url), name);
+  return failure(msg('cli.db.branch.failed'), {
+    code: 'X_DB_BRANCH_FAILED',
+    cause: `"${name}" is not a branch of this database, so nothing was dropped (it would be ${target})`,
+    fix: LIST_FIX,
+    docs: 'https://ultimate.dev/errors/X_DB_BRANCH_FAILED',
+  });
+}