@ultimat3/cli 21.0.0 → 22.1.0

package/src/cmd-ci-spec.ts

@@ -0,0 +1,24 @@
+// `x ci`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-ci.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+/** Log lines kept per failed job. Enough to hold a findings block, short enough to read. */
+export const TAIL_LINES = 40;
+
+export const ciSpec: CommandSpec = {
+  name: 'ci',
+  summary: 'the workflow runs for this branch, and the findings inside the failed steps log',
+  usage: 'x ci [--branch <name>] [--run <id>] [--repo owner/name] [--tail <n>] [--full] [--json]',
+  flags: [
+    { name: 'repo', type: 'string', summary: 'owner/name; the checkout own remote by default' },
+    { name: 'branch', type: 'string', summary: 'branch to read runs for; this one by default' },
+    { name: 'run', type: 'string', summary: 'one run id, instead of this branch latest' },
+    {
+      name: 'tail',
+      type: 'string',
+      summary: `log lines kept per failed job (default ${TAIL_LINES})`,
+    },
+    { name: 'full', type: 'boolean', summary: 'the whole failed-step log, not the tail' },
+  ],
+};

package/src/cmd-ci.ts

@@ -9,14 +9,18 @@ import type { CiLogLine } from './ci-log';
 import { findingsFrom, jobsInLog, parseLogLines, tailOf } from './ci-log';
 import type { CiJob, CiRun } from './ci-runs';
 import { failedLog, isFailed, isRunning, latestPerWorkflow, listRuns, viewRun } from './ci-runs';
+import { ciSpec, TAIL_LINES } from './cmd-ci-spec';
 import type { CliCommand, CommandContext } from './command';
 import { parseIntFlag } from './flag-number';
+import { commentBlock } from './foreign-text';
 import type { GhRepo } from './gh-target';
 import { currentBranch, resolveRepo } from './gh-target';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import { flagBool, flagString } from './parse';
 
+export { TAIL_LINES } from './cmd-ci-spec';
+
 /**
  * Every catalog key this command renders, declared — `msg()` answers `⟦key⟧` for a key nobody
  * added, which is loud in a terminal and SILENT to a build. `cmd-ci.test.ts` holds this list
@@ -34,9 +38,6 @@ export const CI_MESSAGE_KEYS = [
   'cli.ci.logs.empty',
 ] as const;
 
-/** Log lines kept per failed job. Enough to hold a findings block, short enough to read. */
-export const TAIL_LINES = 40;
-
 /** How far back a branch's run history is read before "the latest run of each workflow". */
 export const RUN_LOOKBACK = 20;
 
@@ -55,22 +56,7 @@ const RUN_FLAG = { name: 'run', command: 'ci', min: 1, example: 'x ci --run 3248
 const TAIL_FLAG = { name: 'tail', command: 'ci', min: 1, example: 'x ci --tail 80 --json' };
 
 export const ciCommand: CliCommand = {
-  spec: {
-    name: 'ci',
-    summary: 'the workflow runs for this branch, and the findings inside the failed steps log',
-    usage: 'x ci [--branch <name>] [--run <id>] [--repo owner/name] [--tail <n>] [--full] [--json]',
-    flags: [
-      { name: 'repo', type: 'string', summary: 'owner/name; the checkout own remote by default' },
-      { name: 'branch', type: 'string', summary: 'branch to read runs for; this one by default' },
-      { name: 'run', type: 'string', summary: 'one run id, instead of this branch latest' },
-      {
-        name: 'tail',
-        type: 'string',
-        summary: `log lines kept per failed job (default ${TAIL_LINES})`,
-      },
-      { name: 'full', type: 'boolean', summary: 'the whole failed-step log, not the tail' },
-    ],
-  },
+  spec: ciSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const repo = await resolveRepo(ctx, 'ci', flagString(ctx.args, 'repo'));
     const rawRun = flagString(ctx.args, 'run');
@@ -142,7 +128,14 @@ async function inspect(
     const pool: readonly CiLogLine[] = own.length > 0 ? own : lines;
     const job = failed.find((candidate) => candidate.name === name);
     for (const finding of findingsFrom(pool)) {
-      findings.push(finding.at === undefined ? { ...finding, at: name } : finding);
+      findings.push({
+        ...finding,
+        at: finding.at ?? name,
+        // Fenced and tagged: the log is foreign text, and a `fix:` reconstructed from it is the
+        // log author's instruction, not this CLI's. `commentBlock` is `x pr review`'s fence.
+        fix: commentBlock(`ci-log ${name}`, [finding.fix]).join('\n'),
+        source: 'ci-log',
+      });
     }
     failures.push({
       job: name,
@@ -229,7 +222,8 @@ function runLines(entry: RunReport): readonly string[] {
       continue;
     }
     out.push(msg('cli.ci.tail', { job: failure.job }));
-    for (const line of failure.tail) out.push(`      | ${line}`);
+    for (const line of commentBlock(`ci-log ${failure.job}`, failure.tail))
+      out.push(`      | ${line}`);
   }
   const jobs = entry.jobs;
   if (jobs !== undefined && jobs.length > failures.length) {
@@ -266,6 +260,8 @@ function runJson(entry: RunReport): JsonValue {
             job: failure.job,
             url: failure.url,
             failedSteps: [...failure.failedSteps],
+            // Raw lines for a machine, labelled as foreign: the log's author wrote every one.
+            tailSource: 'ci-log',
             tail: [...failure.tail],
           })),
         }),

package/src/cmd-db-branch.ts

@@ -23,12 +23,12 @@ import {
   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 } from './parse';
+import type { DevServices } from './runtime-bindings';
+import { resolveServices } from './runtime-bindings';
 import { portFromEnv } from './serve';
 import { renderTable } from './table';
 

package/src/cmd-db-spec.ts

@@ -0,0 +1,99 @@
+// `x db`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-db.ts`, which `registry.ts` imports only when the command runs.
+
+import { BRANCH_SUBCOMMANDS } from './db-branch';
+import type { CommandSpec } from './parse';
+
+export const DB_SUBCOMMANDS = [
+  'gen',
+  'migrate',
+  'reset',
+  'seed',
+  'studio',
+  'branch',
+  'backfill',
+] as const;
+
+export const dbSpec: CommandSpec = {
+  name: 'db',
+  summary: 'gen, migrate, reset, seed, studio, branch, backfill',
+  usage:
+    'x db gen "add publish_at" | migrate | reset | seed [<name>] [--tier reference|dev] [--dry-run] | studio | branch ls | branch create <name> | branch drop <name> | backfill [<name>|--all] [--write] [--force] | backfill --pending | backfill --list [--name n] [--status s] [--limit n]',
+  requiresApp: true,
+  subcommands: DB_SUBCOMMANDS,
+  // Declared from the constant `runBranchCommand` validates against, never a second literal: it
+  // is what lets the `errors` step resolve `x db branch ls` — a fix line three shipped errors
+  // hand out, which read `ls` as a branch name and cloned a database until 1.2.x.
+  subcommandPositionals: { branch: BRANCH_SUBCOMMANDS },
+  // Each flag whose summary begins `<subcommand>:` declares that scope, and the parser refuses
+  // it anywhere else: `x db gen --dry-run` used to parse, reach `runGen` and WRITE the
+  // migration. `cmd-db.test.ts` pins summary and scope to the same fact.
+  flags: [
+    {
+      name: 'name',
+      type: 'string',
+      summary: 'migration, branch or seed name, or backfill to filter',
+    },
+    {
+      name: 'tier',
+      type: 'string',
+      summary: 'seed: which tier to run — reference or dev; also ULTIMATE_SEED_TIER',
+      subcommands: ['seed'],
+    },
+    {
+      name: 'dry-run',
+      type: 'boolean',
+      summary: 'seed: report what each seed would write, and write nothing',
+      subcommands: ['seed'],
+    },
+    {
+      name: 'list',
+      type: 'boolean',
+      summary: 'backfill: print the x_backfills ledger',
+      subcommands: ['backfill'],
+    },
+    {
+      name: 'pending',
+      type: 'boolean',
+      summary: 'backfill: declared minus completed; non-zero exit when anything is unswept',
+      subcommands: ['backfill'],
+    },
+    {
+      name: 'all',
+      type: 'boolean',
+      summary: 'backfill: every pending sweep, isolated per name',
+      subcommands: ['backfill'],
+    },
+    {
+      name: 'write',
+      type: 'boolean',
+      summary: 'backfill: enqueue the pass; dry run without it',
+      subcommands: ['backfill'],
+    },
+    {
+      name: 'force',
+      type: 'boolean',
+      summary: 'backfill: sweep a name the ledger records as completed, as a NEW ledger row',
+      subcommands: ['backfill'],
+    },
+    {
+      name: 'status',
+      type: 'string',
+      summary: 'backfill: filter by running, completed or failed',
+      subcommands: ['backfill'],
+    },
+    {
+      name: 'limit',
+      type: 'string',
+      summary: 'backfill: max ledger rows to return',
+      subcommands: ['backfill'],
+    },
+    // Declared because `X_MIGRATION_IRREVERSIBLE`'s own fix line names it. A `fix:` is copied
+    // and run verbatim, so a flag the parser refuses would make the error unfollowable.
+    {
+      name: 'allow-destructive',
+      type: 'boolean',
+      summary: 'let x db gen emit a drop whose down cannot restore the rows',
+    },
+  ],
+};

package/src/cmd-db.ts

@@ -17,9 +17,9 @@ import { postgresDriver } from '@ultimat3/entity';
 import { requireAppRoot } from './app-root';
 import { runBackfillCommand } from './cmd-db-backfill';
 import { runBranchCommand } from './cmd-db-branch';
+import { DB_SUBCOMMANDS, dbSpec } from './cmd-db-spec';
 import { plannedSubcommand } from './cmd-planned';
 import type { CliCommand, CommandContext } from './command';
-import { BRANCH_SUBCOMMANDS } from './db-branch';
 import { stepFinding } from './db-finding';
 import { generateAppMigration, unrenderedJson, unrenderedLines } from './db-generate';
 import type { SeedPassRow } from './db-seed';
@@ -32,109 +32,20 @@ import {
   seedTotals,
   selectSeeds,
 } from './db-seed';
-import { resolveServices } from './dev-services';
+import { DevAlreadyRunningError, liveDevLock } from './dev-lock';
 import { CliNotImplementedError, MissingSubcommandError, UnknownCommandError } from './errors';
 import { withJobDriver } from './jobs-driver';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
 import { flagBool, flagString } from './parse';
+import { resolveServices } from './runtime-bindings';
 import { runMigrations } from './serve';
 
-export const DB_SUBCOMMANDS = [
-  'gen',
-  'migrate',
-  'reset',
-  'seed',
-  'studio',
-  'branch',
-  'backfill',
-] as const;
+export { DB_SUBCOMMANDS } from './cmd-db-spec';
 
 export const dbCommand: CliCommand = {
-  spec: {
-    name: 'db',
-    summary: 'gen, migrate, reset, seed, studio, branch, backfill',
-    usage:
-      'x db gen "add publish_at" | migrate | reset | seed [<name>] [--tier reference|dev] [--dry-run] | studio | branch ls | branch create <name> | branch drop <name> | backfill [<name>|--all] [--write] [--force] | backfill --pending | backfill --list [--name n] [--status s] [--limit n]',
-    requiresApp: true,
-    subcommands: DB_SUBCOMMANDS,
-    // Declared from the constant `runBranchCommand` validates against, never a second literal: it
-    // is what lets the `errors` step resolve `x db branch ls` — a fix line three shipped errors
-    // hand out, which read `ls` as a branch name and cloned a database until 1.2.x.
-    subcommandPositionals: { branch: BRANCH_SUBCOMMANDS },
-    // Each flag whose summary begins `<subcommand>:` declares that scope, and the parser refuses
-    // it anywhere else: `x db gen --dry-run` used to parse, reach `runGen` and WRITE the
-    // migration. `cmd-db.test.ts` pins summary and scope to the same fact.
-    flags: [
-      {
-        name: 'name',
-        type: 'string',
-        summary: 'migration, branch or seed name, or backfill to filter',
-      },
-      {
-        name: 'tier',
-        type: 'string',
-        summary: 'seed: which tier to run — reference or dev; also ULTIMATE_SEED_TIER',
-        subcommands: ['seed'],
-      },
-      {
-        name: 'dry-run',
-        type: 'boolean',
-        summary: 'seed: report what each seed would write, and write nothing',
-        subcommands: ['seed'],
-      },
-      {
-        name: 'list',
-        type: 'boolean',
-        summary: 'backfill: print the x_backfills ledger',
-        subcommands: ['backfill'],
-      },
-      {
-        name: 'pending',
-        type: 'boolean',
-        summary: 'backfill: declared minus completed; non-zero exit when anything is unswept',
-        subcommands: ['backfill'],
-      },
-      {
-        name: 'all',
-        type: 'boolean',
-        summary: 'backfill: every pending sweep, isolated per name',
-        subcommands: ['backfill'],
-      },
-      {
-        name: 'write',
-        type: 'boolean',
-        summary: 'backfill: enqueue the pass; dry run without it',
-        subcommands: ['backfill'],
-      },
-      {
-        name: 'force',
-        type: 'boolean',
-        summary: 'backfill: sweep a name the ledger records as completed, as a NEW ledger row',
-        subcommands: ['backfill'],
-      },
-      {
-        name: 'status',
-        type: 'string',
-        summary: 'backfill: filter by running, completed or failed',
-        subcommands: ['backfill'],
-      },
-      {
-        name: 'limit',
-        type: 'string',
-        summary: 'backfill: max ledger rows to return',
-        subcommands: ['backfill'],
-      },
-      // Declared because `X_MIGRATION_IRREVERSIBLE`'s own fix line names it. A `fix:` is copied
-      // and run verbatim, so a flag the parser refuses would make the error unfollowable.
-      {
-        name: 'allow-destructive',
-        type: 'boolean',
-        summary: 'let x db gen emit a drop whose down cannot restore the rows',
-      },
-    ],
-  },
+  spec: dbSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('db', ctx.cwd).dir;
     // No default, and no `?? 'migrate'` here either: `gen` writes a migration file and `reset`
@@ -299,6 +210,16 @@ async function runReset(ctx: CommandContext, root: string): Promise<CommandResul
       fix: 'drop and recreate the database yourself, then run: x db migrate',
     });
   }
+  // A running `x dev` has this directory open: deleting it under a live embedded Postgres is data
+  // loss mid-write, not a reset. The dev lock is the one fact that says someone holds it.
+  const holder = liveDevLock(services.stateDir);
+  if (holder !== undefined) {
+    throw new DevAlreadyRunningError({
+      lock: holder,
+      stateDir: services.stateDir,
+      embeddedDb: true,
+    });
+  }
   await rm(join(services.stateDir, 'pgdata'), { recursive: true, force: true });
   return runMigrate(ctx, root, msg('cli.db.reset.done'));
 }

package/src/cmd-deploy-helm.ts

@@ -0,0 +1,136 @@
+// The helm half of `x deploy`: which release, in which namespace, waited on for how long, and what
+// the rollout reported. Split from cmd-deploy.ts, which owns the plan and the compose method.
+//
+// `helm upgrade --install` with no `--wait` exits 0 the moment the API server ACCEPTS the objects,
+// so a deploy whose pods never became ready reported success; and helm's default 5m timeout failed
+// an upgrade whose migrate hook was still applying a long migration, leaving the Job running.
+
+// why: Bun exposes no path-join primitive; the chart path is handed to helm as one joined string.
+import { join } from 'node:path';
+import { UltimateError } from '@ultimat3/core';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+import { BadFlagError } from './errors';
+
+/** Long enough for a migration a pre-upgrade hook must finish; helm's own 5m default is not. */
+export const HELM_DEFAULT_TIMEOUT = '15m';
+
+/** What a helm deploy is aimed at, resolved once from the flags and `app.config.ts`. */
+export interface HelmTarget {
+  readonly release: string;
+  readonly namespace: string | undefined;
+  readonly timeout: string;
+}
+
+/** Helm's own `time.ParseDuration` grammar, positive units only: `15m`, `900s`, `1h30m`. */
+const DURATION = /^(?:\d+(?:h|m|s|ms))+$/;
+/** A namespace and a release are both DNS-1123 labels; helm caps a release at 53 characters. */
+const LABEL = /^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$/;
+const RELEASE_MAX = 53;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/** `--timeout`, screened: a value helm would reject is refused before anything is spawned. */
+export function readHelmTimeout(raw: string | undefined): string {
+  if (raw === undefined) return HELM_DEFAULT_TIMEOUT;
+  if (DURATION.test(raw) && /[1-9]/.test(raw)) return raw;
+  throw new BadFlagError({
+    flag: 'timeout',
+    command: 'deploy',
+    reason: 'it is not a positive helm duration such as 15m, 900s or 1h30m',
+    fix: 'x deploy --method helm --timeout 15m --json',
+  });
+}
+
+/** `--namespace` and `--release`, each a DNS-1123 label or a refusal naming the flag. */
+export function readLabel(flag: 'namespace' | 'release', raw: string): string {
+  const max = flag === 'release' ? RELEASE_MAX : 63;
+  if (raw.length <= max && LABEL.test(raw)) return raw;
+  throw new BadFlagError({
+    flag,
+    command: 'deploy',
+    reason: `it must be a lowercase DNS-1123 label of at most ${max} characters`,
+    fix:
+      flag === 'release'
+        ? 'x deploy --method helm --release my-app --json'
+        : 'x deploy --method helm --namespace my-namespace --json',
+  });
+}
+
+/**
+ * The release name: `--release`, else `app.config.ts`'s `name`. It was the literal `app` for every
+ * app, so two apps deployed to one namespace were one release and the second upgrade replaced the
+ * first. `--release` exists for a release that already carries another name — `app`, for every
+ * cluster an earlier version deployed to — because a release name is cluster state the framework
+ * does not own and cannot rename.
+ */
+export async function readReleaseName(root: string, flag: string | undefined): Promise<string> {
+  if (flag !== undefined) return readLabel('release', flag);
+  const module = (await import(join(root, APP_CONFIG_FILE))) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  const name = isRecord(config) ? config['name'] : undefined;
+  if (typeof name === 'string' && name.length <= RELEASE_MAX && LABEL.test(name)) return name;
+  throw new UltimateError({
+    code: 'X_CONFIG_INVALID',
+    cause:
+      typeof name === 'string'
+        ? `app.config.ts names the app "${name.slice(0, 80)}", which is not a helm release name (a DNS-1123 label of at most ${RELEASE_MAX} characters)`
+        : 'app.config.ts exports no config.name, and x deploy --method helm names the release after it',
+    fix: 'name the release explicitly: x deploy --method helm --release my-app --json',
+  });
+}
+
+/** The one `helm upgrade`, waited on: `--wait` for the rollout, `--output json` for the verdict. */
+export function helmUpgradeArgs(
+  root: string,
+  target: HelmTarget,
+  imageOverrides: readonly string[],
+): readonly string[] {
+  return [
+    'helm',
+    'upgrade',
+    '--install',
+    target.release,
+    join(root, 'docker', 'helm'),
+    ...(target.namespace === undefined ? [] : ['--namespace', target.namespace]),
+    '--wait',
+    '--timeout',
+    target.timeout,
+    '--output',
+    'json',
+    ...imageOverrides,
+  ];
+}
+
+/** What `--json` reports about the rollout helm waited on. */
+export interface Rollout {
+  readonly release: string;
+  readonly namespace: string | null;
+  readonly revision: number | null;
+  readonly status: string;
+}
+
+/**
+ * helm's `--output json` release record, read structurally. `status` is helm's own word —
+ * `deployed`, `failed`, `pending-upgrade` — and `unknown` only when helm printed no record at all,
+ * never a guess dressed as one.
+ */
+export function readRollout(target: HelmTarget, stdout: string): Rollout {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    parsed = undefined;
+  }
+  const info = isRecord(parsed) ? parsed['info'] : undefined;
+  const status = isRecord(info) ? info['status'] : undefined;
+  const revision = isRecord(parsed) ? parsed['version'] : undefined;
+  const namespace = isRecord(parsed) ? parsed['namespace'] : undefined;
+  return {
+    release: target.release,
+    namespace: typeof namespace === 'string' ? namespace : (target.namespace ?? null),
+    revision: typeof revision === 'number' ? revision : null,
+    status: typeof status === 'string' ? status : 'unknown',
+  };
+}

package/src/cmd-deploy-spec.ts

@@ -0,0 +1,40 @@
+// `x deploy`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-deploy.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const deploySpec: CommandSpec = {
+  name: 'deploy',
+  summary: 'run the container deploy plan: migrate first, then the serving roles',
+  usage:
+    'x deploy --image repo/app:tag [--method compose|helm] [--release name] [--namespace ns] [--timeout 15m] [--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: 'release',
+      type: 'string',
+      summary: 'helm release name (default: app.config.ts name)',
+    },
+    { name: 'namespace', type: 'string', summary: 'helm namespace (default: the kube context)' },
+    {
+      name: 'timeout',
+      type: 'string',
+      // No `default:` — the parser would then fill it on every compose deploy too, and the refusal
+      // of a helm-only flag there could not tell an operator's value from its own.
+      summary: 'how long helm waits for the migrate hook and the rollout (default 15m)',
+    },
+    // `--critical` was here and is gone. It parsed, it was echoed into the plan JSON as
+    // `critical: <bool>`, and no file in `packages/` read that field — so the flag changed
+    // nothing about what `x deploy` did, on either method. `flag-reads.ts`'s
+    // `X_CLI_FLAG_UNREAD` passed it, because that gate proves a flag is READ and this one was:
+    // into a field with no reader. It is not coming back: `@ultimat3/pwa`'s
+    // `updateSignal({ reason: 'security' })`, the call it was to have triggered, is **deleted**
+    // as of 9.0.0 for having had no runtime caller of its own, and nothing in the framework
+    // force-navigates a client. A deploy also has no channel to one — the plan is
+    // `docker compose up` / `helm upgrade`, and the client's build id is read by `http` (tier 2)
+    // and `sync` (tier 3), neither of which may import a tier-4 package to act on it.
+  ],
+};