@ultimat3/cli 6.0.0 → 7.0.0

package/CLAUDE.md

@@ -67,6 +67,17 @@ and the `tsc -b` that proves it took. Private packages are exempt (a generated a
 private), and a root that declares **no** `references` array is not judged at all: project
 references are opt-in, and a scaffolded app builds through `extends` + `include`.
 
+`workspace-graph.ts` is `package-shape`'s fifth rule: **every cross-workspace import is declared
+in the importing workspace's own manifest**. Without it a scaffolded repo's dependency graph exists
+only inside `tsc` — imports resolve through the root `tsconfig.json` `paths`, so affected-package
+detection, `bun --filter` ordering and "what breaks if I change this" all read manifests and all
+answer too small a set (issue #239, found in a real app where a change reaching five packages
+reported one). `X_WORKSPACE_DEP_UNDECLARED` names the manifest and the exact line to add. Shipped
+source only: a test file's import is not judged, because `packages/*` here declares no
+`devDependencies` by design and the root's hoist is what resolves them. A manifest the scan cannot
+read is its own finding rather than a silent skip — a skipped workspace is a hiding place for the
+very edge the rule is looking for.
+
 `app-agents-md.ts` is why the `manifest` step declares no `applies` at all. The drift half needs
 a committed `x.manifest.json` to compare against, but `AGENTS.md` is required of every repo the
 gate runs in — so the step always has a question to answer, and gating both halves on the file
@@ -139,6 +150,38 @@ emits a file `defineCatalogs` rejects at the app's first boot. `merge: 'json'` u
 (`json-merge.ts`) for the same reason: `x new` and `x g resource` both contribute under `app`, and
 a shallow spread keeps one of them.
 
+## Three commands that reach outside the process, and none of them is a gate step
+
+`x shot`, `x pr` and `x ci` exist because of the one line in the root `CLAUDE.md` that shapes this
+whole package: **the primary developer is an AI agent.** An agent cannot open a browser, cannot look
+at a running dev server and cannot read the GitHub web UI. It can read a file, and it can run a
+command that prints. These three turn each of those into a file and a print.
+
+They are also the only three commands that need something the process does not have — a browser, a
+network, a GitHub token — which is why **none of them is a step of `x verify`**, and why that is not
+an oversight to be corrected later. A gate that needs a browser goes red for reasons unrelated to the
+change, and CI does not install one.
+
+| | Reaches for | Never |
+|---|---|---|
+| `x shot <route>` | `x dev` on a scratch port, plus the app's own `puppeteer-core` through `@ultimat3/scraping` | the static build — `--target static` prerenders `site/` only, so an `app/` route would photograph the landing page |
+| `x pr review\|resolve\|reply` | `gh api graphql`, through the injected `Runner` | `gh pr view --comments`, which shows *issue* comments and not the line-anchored threads that carry the findings |
+| `x ci` | `gh run view --log-failed`, one call | a per-job log fetch — the run and all its jobs come back together |
+
+**`verdict.json` names its own blind spots, and that is the design.** `x shot` reports what it could
+not observe alongside what it did. A capture tool that silently omits what it cannot see is worse
+than one that says so, because the omission reads as a clean result.
+
+**`x shot` reuses a running `x dev` rather than booting a second one.** Embedded Postgres is
+single-writer, so a second boot is `X_DEV_ALREADY_RUNNING` and no picture is ever taken. A reused
+server's `stop()` deliberately does not clear the other process's lock.
+
+**`gh` is invoked through `ctx.runner`, never `Bun.spawn` directly** — that is what lets every test
+supply a reply table and assert the exact argv with no network and no `gh` installed. `GhOptions.fix`
+is a **required** field, so shelling out to GitHub without stating a remedy is a type error rather
+than a review comment. A GraphQL response is untrusted input and is parsed against a schema, never
+cast: a `null` where an id was expected would otherwise become a mutation against `undefined`.
+
 ## The `errors` step enforces the error contract
 
 | File | Job |
@@ -816,10 +859,13 @@ typechecked there by default; an app whose tsconfig names an explicit `include`
 ## Two generators that scaffold something other than a primitive
 
 `x g island <name> [--at <dir>]` writes a **client entry point**, not a component: the filename is
-how the bundler discovers it and `mount` is how the hydration runtime calls it, so those two are
-what `templates/island.test.ts` pins and everything else in the file is example code. `--at` takes
-the directory directly rather than deriving one, because the caller that cannot guess is
-`X_ISLAND_INVALID` — its cause already holds the exact path a page's `src` resolved to, so its
+how the bundler discovers it and `mount` is how the hydration runtime calls it, so the filename,
+the `mount` export and that `mount` RENDERS are what `templates/island.test.ts` pins — it builds
+the emitted entry with `buildIslands` and drives it with `mountIsland`, so a template that
+typechecks and does not mount is a failing test. It runs the mutation too, rather than describing
+it: the same island with `{count()}` replaced by `{0}` must fail the assertion the live one passes.
+`--at` takes the directory directly rather than deriving one, because the caller that cannot guess
+is `X_ISLAND_INVALID` — its cause already holds the exact path a page's `src` resolved to, so its
 `fix:` hands that path straight back.
 
 `x g admin:page <name> --permission <perm> [--at <dir>]` writes an ordinary TSX component and **no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,29 +37,30 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "6.0.0",
-    "@ultimat3/admin": "6.0.0",
-    "@ultimat3/ai": "6.0.0",
-    "@ultimat3/cache": "6.0.0",
-    "@ultimat3/core": "6.0.0",
-    "@ultimat3/db": "6.0.0",
-    "@ultimat3/entity": "6.0.0",
-    "@ultimat3/http": "6.0.0",
-    "@ultimat3/i18n": "6.0.0",
-    "@ultimat3/jobs": "6.0.0",
-    "@ultimat3/mail": "6.0.0",
-    "@ultimat3/manifest": "6.0.0",
-    "@ultimat3/mcp": "6.0.0",
-    "@ultimat3/policy": "6.0.0",
-    "@ultimat3/pwa": "6.0.0",
-    "@ultimat3/query": "6.0.0",
-    "@ultimat3/realtime": "6.0.0",
-    "@ultimat3/render": "6.0.0",
-    "@ultimat3/schema": "6.0.0",
-    "@ultimat3/seo": "6.0.0",
-    "@ultimat3/storage": "6.0.0",
-    "@ultimat3/testing": "6.0.0",
-    "@ultimat3/time": "6.0.0",
+    "@ultimat3/action": "7.0.0",
+    "@ultimat3/admin": "7.0.0",
+    "@ultimat3/ai": "7.0.0",
+    "@ultimat3/cache": "7.0.0",
+    "@ultimat3/core": "7.0.0",
+    "@ultimat3/db": "7.0.0",
+    "@ultimat3/entity": "7.0.0",
+    "@ultimat3/http": "7.0.0",
+    "@ultimat3/i18n": "7.0.0",
+    "@ultimat3/jobs": "7.0.0",
+    "@ultimat3/mail": "7.0.0",
+    "@ultimat3/manifest": "7.0.0",
+    "@ultimat3/mcp": "7.0.0",
+    "@ultimat3/policy": "7.0.0",
+    "@ultimat3/pwa": "7.0.0",
+    "@ultimat3/query": "7.0.0",
+    "@ultimat3/realtime": "7.0.0",
+    "@ultimat3/render": "7.0.0",
+    "@ultimat3/schema": "7.0.0",
+    "@ultimat3/scraping": "7.0.0",
+    "@ultimat3/seo": "7.0.0",
+    "@ultimat3/storage": "7.0.0",
+    "@ultimat3/testing": "7.0.0",
+    "@ultimat3/time": "7.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/affected.ts

@@ -0,0 +1,320 @@
+// What a diff touches: the changed-file list read out of git, and the workspaces that list forces
+// a re-test of — closed TRANSITIVELY over the workspace graph, because A → B → C means an edit in
+// C breaks A and a single pass over an unordered list only ever reaches B.
+//
+// The diff defaults to a REF, never the working tree. Several agents share one checkout here (root
+// `CLAUDE.md`, the "Note": no worktrees, "run them as a team in this same checkout"), so a
+// working-tree diff returns every other agent's uncommitted work and the "affected" set silently
+// widens to nearly the whole monorepo — the command stops narrowing anything and nobody can tell.
+// A ref diff is stable under that concurrency; `--dirty` opts back in, which is right for one
+// developer iterating alone and wrong as a default here.
+
+// `join`/`relative` are `node:`-only by necessity: Bun exposes no path primitive, and a workspace
+// directory is checkout-relative while a caller's scan yields paths relative to its own root.
+import { join, relative } from 'node:path';
+import { singleLine, UltimateError } from '@ultimat3/core';
+import { docsFor } from './error-codes';
+import { BadFlagError } from './errors';
+import type { ExecResult, Runner } from './exec';
+import { execOutput } from './exec';
+import type { JsonValue } from './output';
+import type { ParsedArgs } from './parse';
+import { flagBool, flagString } from './parse';
+import type { WorkspaceNode } from './workspace-graph';
+import { readWorkspaceGraph } from './workspace-graph';
+
+/** The branch a change is measured against when `--base` says nothing. */
+export const DEFAULT_BASE = 'main';
+
+/**
+ * Root files that belong to no workspace and change what every workspace compiles to: a compiler
+ * option, a lint rule, the root manifest, the resolved dependency tree, the test preload, the app
+ * config. A "scoped" run that skipped them reports green over packages the edit just broke.
+ *
+ * Matched on the WHOLE path — `packages/cli/package.json` is the cli workspace's own file and
+ * reaches only cli's dependents, `package.json` at the root reaches everything.
+ */
+export const ROOT_WIDE_FILES: readonly string[] = [
+  'app.config.ts',
+  'biome.json',
+  'bun.lock',
+  'bunfig.toml',
+  'package.json',
+  'tsconfig.json',
+];
+
+/**
+ * A file with no compilation unit behind it. A doc or a plan re-checks nothing, so it maps to no
+ * workspace at all rather than to the one it happens to sit inside — `packages/cli/README.md` is
+ * not a reason to run `packages/cli`'s tests.
+ */
+const isDoc = (path: string): boolean => path.endsWith('.md');
+
+const owns = (node: WorkspaceNode, path: string): boolean =>
+  path === node.dir || path.startsWith(`${node.dir}/`);
+
+/**
+ * The workspace a path belongs to, longest directory first: nested workspaces exist (a scaffolded
+ * app's `apps/web` inside its own root), and the shorter prefix would swallow the inner one.
+ */
+export function owningWorkspace(
+  graph: readonly WorkspaceNode[],
+  path: string,
+): WorkspaceNode | undefined {
+  let best: WorkspaceNode | undefined;
+  for (const node of graph) {
+    if (!owns(node, path)) continue;
+    if (best === undefined || node.dir.length > best.dir.length) best = node;
+  }
+  return best;
+}
+
+/**
+ * Every workspace that depends on one of `seeds`, however many edges away.
+ *
+ * A queue with a growing cursor, not one pass over `seeds`: with `A → B → C`, one pass answers
+ * `{ C, B }` and leaves A untested while the change that broke it is in the diff — a green
+ * checkmark on a broken repo, which is the whole reason this command exists rather than each agent
+ * inventing its own scoping. `reached` doubles as the cycle guard.
+ */
+function withDependents(
+  graph: readonly WorkspaceNode[],
+  seeds: ReadonlySet<string>,
+): ReadonlySet<string> {
+  const dependents = new Map<string, string[]>();
+  for (const node of graph) {
+    for (const dependency of node.dependencies) {
+      const known = dependents.get(dependency);
+      if (known === undefined) dependents.set(dependency, [node.name]);
+      else known.push(node.name);
+    }
+  }
+  const reached = new Set(seeds);
+  const queue = [...reached];
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    const name = queue[cursor];
+    if (name === undefined) continue;
+    for (const dependent of dependents.get(name) ?? []) {
+      if (reached.has(dependent)) continue;
+      reached.add(dependent);
+      queue.push(dependent);
+    }
+  }
+  return reached;
+}
+
+export interface AffectedPlan {
+  /** Every path the diff reported, verbatim and in git's order. */
+  readonly changed: readonly string[];
+  /** The subset with no compilation unit behind it, named so an empty answer explains itself. */
+  readonly ignored: readonly string[];
+  /** The root files that forced every workspace in, empty when none did. */
+  readonly rootWide: readonly string[];
+  readonly workspaces: readonly WorkspaceNode[];
+}
+
+const byName = (a: WorkspaceNode, b: WorkspaceNode): number => (a.name > b.name ? 1 : -1);
+
+/**
+ * Pure: the graph and the file list in, the plan out. No git, no disk — so the transitive rule is
+ * testable without a checkout whose state would decide the verdict.
+ */
+export function planAffected(
+  graph: readonly WorkspaceNode[],
+  changed: readonly string[],
+): AffectedPlan {
+  const ignored = changed.filter(isDoc);
+  const considered = changed.filter((path) => !isDoc(path));
+  const rootWide = considered.filter((path) => ROOT_WIDE_FILES.includes(path));
+  if (rootWide.length > 0) {
+    return { changed, ignored, rootWide, workspaces: [...graph].sort(byName) };
+  }
+  const seeds = new Set<string>();
+  for (const path of considered) {
+    const node = owningWorkspace(graph, path);
+    if (node !== undefined) seeds.add(node.name);
+  }
+  const reached = withDependents(graph, seeds);
+  return {
+    changed,
+    ignored,
+    rootWide,
+    workspaces: graph.filter((node) => reached.has(node.name)).sort(byName),
+  };
+}
+
+/**
+ * How the calling command spells this scoping, so a `fix:` re-runs the invocation that actually
+ * failed. `x test --base main` is refused by `x test` itself — without `--affected` the flag
+ * narrows nothing — so a fix line that dropped it would reproduce its own failure, verbatim.
+ */
+const invocationOf = (command: string): string =>
+  command === 'affected' ? 'x affected' : `x ${command} --affected`;
+
+export interface AffectedSelection {
+  readonly base: string;
+  readonly dirty: boolean;
+}
+
+/**
+ * One reader for `--base` and `--dirty`, shared by `x affected` and `x test --affected`: two
+ * readers would be two answers to "what is this diff measured against", and the second command's
+ * scoping is only trustworthy if it is the first command's.
+ */
+export function readAffectedSelection(args: ParsedArgs, command: string): AffectedSelection {
+  const base = flagString(args, 'base') ?? DEFAULT_BASE;
+  if (base.trim().length === 0) {
+    throw new BadFlagError({
+      flag: 'base',
+      command,
+      reason: 'needs a git ref and got an empty value',
+      fix: `${invocationOf(command)} --base ${DEFAULT_BASE} --json`,
+    });
+  }
+  return { base, dirty: flagBool(args, 'dirty') };
+}
+
+const git = (runner: Runner, cwd: string, args: readonly string[]): Promise<ExecResult> =>
+  runner(['git', ...args], { cwd });
+
+/** NUL-delimited, so a path holding a space, a quote or a newline survives the read intact. */
+const paths = (stdout: string): readonly string[] =>
+  stdout.split('\0').filter((path) => path.length > 0);
+
+/**
+ * The checkout's own root, which is what every path git prints is relative to — so it is also the
+ * root the workspace graph has to be read from, or a `packages/cli/...` path would be matched
+ * against dirs resolved somewhere else.
+ */
+export async function gitRoot(runner: Runner, cwd: string, command: string): Promise<string> {
+  const result = await git(runner, cwd, ['rev-parse', '--show-toplevel']);
+  if (result.ok) return result.stdout.trim();
+  throw new UltimateError({
+    code: 'X_CLI_UNEXPECTED',
+    cause: `x ${command} reads its diff from git and "git rev-parse --show-toplevel" exited ${result.code} in ${cwd}: ${singleLine(execOutput(result))}`,
+    fix: `run x ${command} from inside a git checkout — confirm with: git rev-parse --show-toplevel`,
+    docs: docsFor('X_CLI_UNEXPECTED'),
+  });
+}
+
+export interface ChangedFilesOptions {
+  readonly cwd: string;
+  readonly command: string;
+  readonly selection: AffectedSelection;
+}
+
+/**
+ * `<base>...HEAD` — three dots, so the answer is "what this branch changed since it forked",
+ * never "how this branch differs from a base that has moved on underneath it". A two-dot diff
+ * reports someone else's merged commits as this branch's work.
+ *
+ * `--dirty` unions the working tree on top: tracked edits against HEAD, plus untracked files that
+ * are not ignored. Both halves are needed — a brand-new file is invisible to `git diff`.
+ */
+export async function changedFiles(
+  runner: Runner,
+  options: ChangedFilesOptions,
+): Promise<readonly string[]> {
+  const { base, dirty } = options.selection;
+  const resolved = await git(runner, options.cwd, [
+    'rev-parse',
+    '--verify',
+    '--quiet',
+    `${base}^{commit}`,
+  ]);
+  if (!resolved.ok) {
+    throw new BadFlagError({
+      flag: 'base',
+      command: options.command,
+      reason: `git resolves no commit named "${base}" in this checkout`,
+      fix: `git fetch --no-tags origin ${base}:${base}, then re-run: ${invocationOf(options.command)} --base ${base} --json`,
+    });
+  }
+  const runs = [
+    await git(runner, options.cwd, ['diff', '--name-only', '-z', `${base}...HEAD`]),
+    ...(dirty
+      ? [
+          await git(runner, options.cwd, ['diff', '--name-only', '-z', 'HEAD']),
+          await git(runner, options.cwd, ['ls-files', '-z', '--others', '--exclude-standard']),
+        ]
+      : []),
+  ];
+  const failed = runs.find((run) => !run.ok);
+  if (failed !== undefined) {
+    throw new UltimateError({
+      code: 'X_CLI_UNEXPECTED',
+      cause: `"${failed.command.join(' ')}" exited ${failed.code} in ${options.cwd}: ${singleLine(execOutput(failed))}`,
+      fix: `run it yourself to see why: ${failed.command.join(' ')}`,
+      docs: docsFor('X_CLI_UNEXPECTED'),
+    });
+  }
+  return [...new Set(runs.flatMap((run) => paths(run.stdout)))].sort();
+}
+
+/**
+ * One resolved answer, in the two shapes its two callers need: the `plan` (`x affected` reports
+ * it) and the `prefixes` (`x test --affected` selects with them). `plan.workspaces` holds dirs
+ * relative to the CHECKOUT; `prefixes` is the same set relative to the directory the caller scans,
+ * which is what its own paths are relative to.
+ */
+export interface AffectedScope {
+  readonly selection: AffectedSelection;
+  /** The checkout root git reported every path against. */
+  readonly root: string;
+  readonly plan: AffectedPlan;
+  readonly prefixes: readonly string[];
+}
+
+/**
+ * An empty prefix means the scan root IS an affected workspace, so every path it yields is in
+ * scope; a prefix starting with `..` is a workspace outside that root, which has no file there to
+ * select and must not be allowed to collapse into a match-everything empty string.
+ */
+const scopePrefixes = (root: string, cwd: string, dirs: readonly string[]): readonly string[] =>
+  dirs
+    .map((dir) => relative(cwd, join(root, dir)).split('\\').join('/'))
+    .filter((path) => !path.startsWith('..'));
+
+export const inScope = (path: string, prefixes: readonly string[]): boolean =>
+  prefixes.some((prefix) => prefix === '' || path === prefix || path.startsWith(`${prefix}/`));
+
+export interface AffectedScopeOptions {
+  readonly runner: Runner;
+  /** The directory the caller scans, which the prefixes come back relative to. */
+  readonly cwd: string;
+  readonly args: ParsedArgs;
+  readonly command: string;
+}
+
+/**
+ * The whole answer, resolved once: the diff, the graph, the closure and the prefixes. `x affected`
+ * and `x test --affected` both come through here, so the second can never scope a run differently
+ * from what the first reports — an invented scoping that misses a transitive dependent is a green
+ * checkmark on a broken repo, and two implementations is how one of them gets it wrong.
+ */
+export async function affectedScope(options: AffectedScopeOptions): Promise<AffectedScope> {
+  const selection = readAffectedSelection(options.args, options.command);
+  const root = await gitRoot(options.runner, options.cwd, options.command);
+  const plan = planAffected(
+    await readWorkspaceGraph(root),
+    await changedFiles(options.runner, { cwd: root, command: options.command, selection }),
+  );
+  return {
+    selection,
+    root,
+    plan,
+    prefixes: scopePrefixes(
+      root,
+      options.cwd,
+      plan.workspaces.map((workspace) => workspace.dir),
+    ),
+  };
+}
+
+/** The scope as `--json` carries it, from whichever command narrowed by it. */
+export const affectedScopeJson = (scope: AffectedScope): JsonValue => ({
+  base: scope.selection.base,
+  dirty: scope.selection.dirty,
+  changed: scope.plan.changed.length,
+  workspaces: scope.plan.workspaces.map((workspace) => workspace.dir),
+});

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 }),
+  });
+}