@ultimat3/cli 6.0.0 → 8.0.0

package/src/browser-launcher.ts

@@ -0,0 +1,109 @@
+// The app's own browser library, resolved from the app's own `node_modules` — never a dependency
+// of this package. `@ultimat3/scraping` declares the launcher's shape structurally (`cdp-port.ts`)
+// precisely so the framework can drive a browser without shipping one, and `x shot` is a CLI
+// command holding to the same bargain: the app installs `puppeteer-core`, the CLI asks for it.
+
+import { existsSync } from 'node:fs';
+import { UltimateError } from '@ultimat3/core';
+import type { CdpLauncherLike, ScrapeDriver } from '@ultimat3/scraping';
+import { localBrowser } from '@ultimat3/scraping';
+import { docsFor } from './error-codes';
+
+/**
+ * The one library this works against. Playwright is not an alternative and is not a flag:
+ * `packages/scraping/src/cdp-port.ts` records that its `connectOverCDP` cannot perform the
+ * WebSocket upgrade under Bun (oven-sh/bun#9911), verified against puppeteer-core 25.8.0.
+ */
+export const BROWSER_PACKAGE = 'puppeteer-core';
+
+/** Where a browser binary is named when the flag does not name one. Read in this order. */
+export const BROWSER_PATH_VARS = ['PUPPETEER_EXECUTABLE_PATH', 'CHROME_PATH'] as const;
+
+/**
+ * A missing browser is an instruction, not a crash (axiom 4). The cause distinguishes the two
+ * shapes — nothing resolved, or something resolved that is not a launcher — while the fix is the
+ * same install either way, because both are answered by putting the real package in the app.
+ */
+export class ShotBrowserMissingError extends UltimateError {
+  constructor(input: { root: string; detail: string }) {
+    super({
+      code: 'X_SHOT_BROWSER_MISSING',
+      cause: `x shot drives a real browser and ${BROWSER_PACKAGE} ${input.detail} from ${input.root}`,
+      // One literal, not `bun add -d ${BROWSER_PACKAGE}`: `fix-scan.ts` can only read a fix that IS
+      // one literal, and a fix line the gate cannot read is a fix line nothing holds to the
+      // contract. `browser-launcher.test.ts` pins it against the constant instead.
+      fix: 'bun add -d puppeteer-core',
+      docs: docsFor('X_SHOT_BROWSER_MISSING'),
+      meta: { root: input.root, package: BROWSER_PACKAGE },
+    });
+  }
+}
+
+/**
+ * Structural, because this is somebody else's module: a namespace object, a CJS `default`, or a
+ * transpiled interop wrapper are all shapes `import()` legitimately hands back, and only one
+ * question decides — is there a `launch` to call?
+ */
+const launcherIn = (module: unknown): CdpLauncherLike | undefined => {
+  if (typeof module !== 'object' || module === null) return undefined;
+  const candidate = module as { launch?: unknown; default?: unknown };
+  if (typeof candidate.launch === 'function') return candidate as CdpLauncherLike;
+  // `module.exports.default = module.exports` is a real CJS interop shape, so the self-reference is
+  // refused rather than followed: one unbounded recursion here is a stack overflow instead of the
+  // instruction this whole function exists to produce.
+  if (candidate.default === undefined || candidate.default === candidate) return undefined;
+  return launcherIn(candidate.default);
+};
+
+export interface AppBrowserOptions {
+  readonly root: string;
+  /** `--browser`, then `PUPPETEER_EXECUTABLE_PATH`, then `CHROME_PATH`. */
+  readonly executablePath?: string | undefined;
+  /** Test seam: the resolver and the loader, so a test proves the refusal without an install. */
+  readonly resolve?: (specifier: string, from: string) => string;
+  readonly load?: (path: string) => Promise<unknown>;
+}
+
+/** The path a run will launch, or `undefined` for "let the library find its own". */
+export const executablePathFrom = (
+  flag: string | undefined,
+  env: Readonly<Record<string, string | undefined>>,
+): string | undefined => {
+  if (flag !== undefined && flag.length > 0) return flag;
+  for (const name of BROWSER_PATH_VARS) {
+    const value = env[name];
+    if (value !== undefined && value.length > 0) return value;
+  }
+  return undefined;
+};
+
+/** True when a named executable is really there — a bad `--browser` is refused before a boot. */
+export const browserBinaryExists = (path: string): boolean => existsSync(path);
+
+/**
+ * The app's `puppeteer-core`, as a `ScrapeDriver`. Resolved FROM THE APP ROOT rather than from
+ * this module: `import('puppeteer-core')` here would find the CLI's own tree, which by design has
+ * no such dependency, and would answer "missing" for an app that installed it correctly.
+ */
+export async function appBrowser(options: AppBrowserOptions): Promise<ScrapeDriver> {
+  const resolve = options.resolve ?? ((specifier, from) => Bun.resolveSync(specifier, from));
+  const load = options.load ?? ((path: string) => import(path) as Promise<unknown>);
+  let entry: string;
+  try {
+    entry = resolve(BROWSER_PACKAGE, options.root);
+  } catch {
+    throw new ShotBrowserMissingError({ root: options.root, detail: 'does not resolve' });
+  }
+  const launcher = launcherIn(await load(entry));
+  if (launcher === undefined) {
+    throw new ShotBrowserMissingError({
+      root: options.root,
+      detail: `resolved to ${entry}, which exports no launch()`,
+    });
+  }
+  return localBrowser({
+    launcher,
+    headless: true,
+    ...(options.executablePath === undefined ? {} : { executablePath: options.executablePath }),
+  });
+}

package/src/ci-runs.ts

@@ -0,0 +1,179 @@
+// Which workflow runs `x ci` is about, and the three `gh run` calls that answer it. Selection
+// lives here rather than in the command so "the latest run of each workflow on this branch" is one
+// testable function over plain rows instead of a shape only a subprocess can produce.
+
+import { t } from '@ultimat3/schema';
+import type { GhHost } from './gh';
+import { ghJson, runGh } from './gh';
+import type { GhRepo } from './gh-target';
+
+/** The fields both `gh run list` and `gh run view` accept, named once so the two agree. */
+export const RUN_FIELDS =
+  'databaseId,status,conclusion,headBranch,displayTitle,workflowName,url,createdAt';
+
+const RUN_ROW = t.object({
+  databaseId: t.number,
+  status: t.string,
+  conclusion: t.nullable(t.string),
+  headBranch: t.string,
+  displayTitle: t.string,
+  workflowName: t.string,
+  url: t.string,
+  createdAt: t.string,
+});
+
+const STEP = t.object({ name: t.string, conclusion: t.nullable(t.string), number: t.number });
+
+const JOB = t.object({
+  name: t.string,
+  status: t.string,
+  conclusion: t.nullable(t.string),
+  url: t.string,
+  steps: t.array(STEP),
+});
+
+const RUN_LIST = t.array(RUN_ROW);
+const RUN_VIEW = RUN_ROW.extend({ jobs: t.array(JOB) });
+
+export interface CiStep {
+  readonly name: string;
+  readonly conclusion: string | null;
+  readonly number: number;
+}
+
+export interface CiJob {
+  readonly name: string;
+  readonly status: string;
+  readonly conclusion: string | null;
+  readonly url: string;
+  readonly steps: readonly CiStep[];
+}
+
+export interface CiRun {
+  readonly id: number;
+  readonly status: string;
+  readonly conclusion: string | null;
+  readonly branch: string;
+  readonly title: string;
+  readonly workflow: string;
+  readonly url: string;
+  readonly createdAt: string;
+}
+
+/**
+ * The conclusions that mean "this run is not green". `cancelled` and `timed_out` are in it because
+ * a cancelled run has told the reader nothing about their change, and a command that reported it
+ * as passing would be a green verdict over an unanswered question. `skipped` is not: a workflow
+ * whose conditions did not match was never asked.
+ */
+export const FAILED_CONCLUSIONS: readonly string[] = [
+  'failure',
+  'cancelled',
+  'timed_out',
+  'startup_failure',
+  'action_required',
+  'stale',
+];
+
+export const isFailed = (run: CiRun): boolean =>
+  run.conclusion !== null && FAILED_CONCLUSIONS.includes(run.conclusion);
+
+export const isRunning = (run: CiRun): boolean => run.status !== 'completed';
+
+interface RunRow {
+  readonly databaseId: number;
+  readonly status: string;
+  readonly conclusion: string | null;
+  readonly headBranch: string;
+  readonly displayTitle: string;
+  readonly workflowName: string;
+  readonly url: string;
+  readonly createdAt: string;
+}
+
+const runOf = (row: RunRow): CiRun => ({
+  id: row.databaseId,
+  status: row.status,
+  conclusion: row.conclusion,
+  branch: row.headBranch,
+  title: row.displayTitle,
+  workflow: row.workflowName,
+  url: row.url,
+  createdAt: row.createdAt,
+});
+
+/**
+ * The newest run of EACH workflow, which is the honest answer to "is CI green on this branch".
+ * Taking the newest run overall reports whichever workflow happened to finish last — this repo
+ * runs `ci` and `deploy-social-demo` off the same push, so half the time that is a verdict about
+ * a workflow the caller was not asking about.
+ */
+export function latestPerWorkflow(runs: readonly CiRun[]): readonly CiRun[] {
+  const newest = new Map<string, CiRun>();
+  for (const run of runs) {
+    const held = newest.get(run.workflow);
+    if (held === undefined || run.createdAt > held.createdAt) newest.set(run.workflow, run);
+  }
+  return [...newest.values()];
+}
+
+export async function listRuns(
+  host: GhHost,
+  repo: GhRepo,
+  branch: string,
+  limit: number,
+): Promise<readonly CiRun[]> {
+  const rows = await ghJson(
+    host,
+    [
+      'run',
+      'list',
+      '--repo',
+      repo.slug,
+      '--branch',
+      branch,
+      '--limit',
+      String(limit),
+      '--json',
+      RUN_FIELDS,
+    ],
+    RUN_LIST,
+    {
+      label: `gh run list --branch ${branch}`,
+      fix: `x ci --branch ${branch} --repo ${repo.slug} --json`,
+    },
+  );
+  return rows.map(runOf);
+}
+
+/** One run, with its jobs — `gh run view --json` carries both, so this is one round trip. */
+export async function viewRun(
+  host: GhHost,
+  repo: GhRepo,
+  id: number,
+): Promise<{ readonly run: CiRun; readonly jobs: readonly CiJob[] }> {
+  const viewed = await ghJson(
+    host,
+    ['run', 'view', String(id), '--repo', repo.slug, '--json', `${RUN_FIELDS},jobs`],
+    RUN_VIEW,
+    { label: `gh run view ${id}`, fix: `x ci --run ${id} --repo ${repo.slug} --json` },
+  );
+  return { run: runOf(viewed), jobs: viewed.jobs };
+}
+
+/**
+ * The failed steps' log, and only those. `--log` is the whole run — setup, caches, every green
+ * step — where `--log-failed` is the part a triage starts from, which is the difference between
+ * one command and three.
+ */
+export async function failedLog(host: GhHost, repo: GhRepo, id: number): Promise<string> {
+  const result = await runGh(
+    host,
+    ['run', 'view', String(id), '--repo', repo.slug, '--log-failed'],
+    {
+      label: `gh run view ${id} --log-failed`,
+      fix: `gh run view ${id} --repo ${repo.slug} --log   # the whole log, when the failed steps carry none`,
+    },
+  );
+  return result.stdout;
+}

package/src/cmd-affected.ts

@@ -0,0 +1,109 @@
+// `x affected` — the workspaces a diff forces a re-test of, closed transitively over the workspace
+// graph. `x verify` runs everything, which is right for a gate and wrong for the loop an agent
+// iterates in; without this command that agent invents its own scoping, and an invented one that
+// misses a transitive dependent is a green checkmark on a broken repo.
+//
+// CLI wiring only. What a diff touches is `affected.ts`, what the workspaces are is
+// `workspace-graph.ts` — the `cmd-jobs.ts` / `jobs-report.ts` split, repeated.
+
+import { affectedScope, DEFAULT_BASE } from './affected';
+import type { CliCommand, CommandContext } from './command';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { flagBool } from './parse';
+import { renderTable } from './table';
+
+const HEADER = ['workspace', 'dir'] as const;
+
+/**
+ * Every catalog row the affected surface renders — this command's four and the one `x test
+ * --affected` prints when nothing is affected. One list, because the two commands are one surface
+ * and a per-file list would leave whichever half nobody thought about unchecked.
+ *
+ * The rule it exists for: `msg()` answers `⟦key⟧` for a key the catalog lacks, which is loud in the
+ * terminal and completely silent to a build, so a command can ship a summary no locale renders.
+ * `cmd-affected.test.ts` holds `messages.ts` to this list.
+ */
+export const AFFECTED_MESSAGE_KEYS = [
+  'cli.affected.count',
+  'cli.affected.none',
+  'cli.affected.rootWide',
+  'cli.affected.dirty',
+  'cli.test.affected.none',
+] as const;
+
+export const affectedCommand: CliCommand = {
+  spec: {
+    name: 'affected',
+    summary: 'the workspaces a diff touches, and every workspace that depends on one of them',
+    usage: 'x affected [--base <ref>] [--dirty] [--paths] [--json]',
+    flags: [
+      {
+        name: 'base',
+        type: 'string',
+        summary: `git ref to diff against, merge-base style (default: ${DEFAULT_BASE})`,
+      },
+      {
+        name: 'dirty',
+        type: 'boolean',
+        summary: 'also count uncommitted work — every agent sharing this checkout, not only yours',
+      },
+      { name: 'paths', type: 'boolean', summary: 'print bare directories instead of a table' },
+    ],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    // The one resolver `x test --affected` narrows with, so this command reports exactly what that
+    // one runs. It reads `--base` before git is spawned (a malformed ref must not cost a
+    // subprocess) and takes the diff at the CHECKOUT root, which is what git prints paths against.
+    const { selection, root, plan } = await affectedScope({
+      runner: ctx.runner,
+      cwd: ctx.cwd,
+      args: ctx.args,
+      command: 'affected',
+    });
+    const params = { base: selection.base, changed: plan.changed.length };
+    const table = renderTable(
+      HEADER,
+      plan.workspaces.map((workspace) => [workspace.name, workspace.dir]),
+    ).map((line) => `  ${line}`);
+    const data: JsonValue = {
+      base: selection.base,
+      dirty: selection.dirty,
+      root,
+      changed: [...plan.changed],
+      ignored: [...plan.ignored],
+      rootWide: [...plan.rootWide],
+      workspaces: plan.workspaces.map((workspace) => ({
+        name: workspace.name,
+        dir: workspace.dir,
+      })),
+      paths: plan.workspaces.map((workspace) => workspace.dir),
+    };
+    return {
+      // An empty answer is a fact, not a failure: a `.md`-only diff genuinely re-checks nothing,
+      // and reporting it red would fail a build for editing a doc. The count is in the summary and
+      // `data.changed`/`data.ignored` say what was looked at, so "green because nothing is
+      // affected" is never mistaken for "green because everything passed".
+      ok: true,
+      command: 'affected',
+      summary:
+        plan.workspaces.length === 0
+          ? msg('cli.affected.none', params)
+          : msg('cli.affected.count', { ...params, count: plan.workspaces.length }),
+      lines: [
+        ...(selection.dirty ? [msg('cli.affected.dirty')] : []),
+        ...(plan.rootWide.length === 0
+          ? []
+          : [msg('cli.affected.rootWide', { files: plan.rootWide.join(', ') })]),
+        ...(plan.workspaces.length === 0
+          ? []
+          : // `--paths` changes only what the human sees; `--json` carries both projections on
+            // every run, so the two renderers can never state different sets.
+            flagBool(ctx.args, 'paths')
+            ? plan.workspaces.map((workspace) => workspace.dir)
+            : table),
+      ],
+      data,
+    };
+  },
+};

package/src/cmd-build.ts

@@ -14,6 +14,13 @@ import { execOutput } from './exec';
 import { msg } from './messages';
 import type { CommandResult } from './output';
 import { flagString } from './parse';
+import type { StaticReport } from './static-report';
+import {
+  readStaticReport,
+  removeStaticReport,
+  renderStaticReport,
+  staticReportData,
+} from './static-report';
 
 export const BUILD_TARGETS = ['docker', 'binary', 'static'] as const;
 
@@ -111,14 +118,19 @@ export function preflightResult(verify: CommandResult): CommandResult {
  * `✗ 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.
+ *
+ * `report` is the static target's inventory, and BOTH renderers get it: `--json` is the house rule,
+ * but an agent reading terminal output is the primary developer here, so a silent human path is the
+ * same defect in a different costume. `lines` still carries nothing `data` does not (#242).
  */
 export function buildResult(input: {
   readonly target: BuildTarget;
   readonly artifact: string;
   readonly command: readonly string[];
   readonly result: ExecResult;
+  readonly report?: StaticReport;
 }): CommandResult {
-  const { result, target } = input;
+  const { report, result, target } = input;
   const output = result.ok ? '' : execOutput(result);
   return {
     ok: result.ok,
@@ -139,8 +151,13 @@ export function buildResult(input: {
       artifact: input.artifact,
       durationMs: result.durationMs,
       ...(result.ok ? {} : { output }),
+      ...staticReportData(report),
     },
-    lines: result.ok ? [] : output.split('\n'),
+    lines: result.ok
+      ? report === undefined
+        ? []
+        : renderStaticReport(report)
+      : output.split('\n'),
   };
 }
 
@@ -178,11 +195,20 @@ export const buildCommand: CliCommand = {
       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 });
+    // Removed BEFORE the builder runs, so a build that writes no inventory can never be reported
+    // with the last one's: a stale emitted list is worse than none, because it reads as this run's.
+    if (target === 'static') await removeStaticReport(root);
+    const result = await ctx.runner(command, { cwd: root });
+    // `prerenderSite` writes it; an app whose `apps/web/prerender.ts` does not call that writes no
+    // `.x/build-stats.json` either, and `x verify`'s `budgets` step already reds that app with
+    // `X_BUDGET_UNMEASURED` — so the absence needs no second code here.
+    const report = target === 'static' && result.ok ? await readStaticReport(root) : undefined;
     return buildResult({
       target,
       artifact: target === 'docker' ? tag : out,
       command,
-      result: await ctx.runner(command, { cwd: root }),
+      result,
+      ...(report === undefined ? {} : { report }),
     });
   },
 };