@ultimat3/cli 6.0.0 → 7.0.0

package/src/cmd-test.ts

@@ -1,14 +1,20 @@
 // `x test`'s command surface: the flags and the one positional it accepts, and the refusals that
 // happen before a single process starts. Which files run is test-select.ts, how they are split and
 // spawned is test-shards.ts — this file only turns argv into their inputs, so a parsing bug can
-// never be read as a sharding one.
+// never be read as a sharding one. `--affected` is the one narrowing decided here rather than
+// there, because it is a fact about a git diff and not about a path: what the diff touches is
+// `affected.ts`, and this file only maps that answer onto the paths discovery yields.
 
+import type { AffectedScope } from './affected';
+import { affectedScope, affectedScopeJson, DEFAULT_BASE, inScope } from './affected';
 import type { CliCommand, CommandContext } from './command';
+import { ok } from './command';
 import { BadFlagError, NoTestFilesError } from './errors';
 import { readIntFlag } from './flag-number';
-import type { CommandResult } from './output';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
 import type { ParsedArgs } from './parse';
-import { flagString } from './parse';
+import { flagBool, flagString } from './parse';
 import { quoteArg } from './shell-quote';
 import { discoverTests, missingSelection, readSample, readType, sampleFiles } from './test-select';
 import { runShards } from './test-shards';
@@ -53,12 +59,52 @@ function readOnlyType(positionals: readonly string[]): TestType | undefined {
   });
 }
 
+/**
+ * `--affected`, and the two flags that only mean something with it. The scope itself is
+ * `affected.ts`'s — `x affected` reports exactly what this narrows to, or the two commands would
+ * be two answers to one question and only one of them would be the one an agent trusts.
+ */
+async function readAffectedScope(ctx: CommandContext): Promise<AffectedScope | undefined> {
+  if (flagBool(ctx.args, 'affected')) {
+    return affectedScope({ runner: ctx.runner, cwd: ctx.cwd, args: ctx.args, command: 'test' });
+  }
+  // A flag that parses and changes nothing is a promise `x help test` cannot keep: without
+  // `--affected` the whole suite runs, and a `--base` on the line would read as if it had not.
+  const idle = flagString(ctx.args, 'base') !== undefined ? 'base' : 'dirty';
+  if (flagString(ctx.args, 'base') !== undefined || flagBool(ctx.args, 'dirty')) {
+    throw new BadFlagError({
+      flag: idle,
+      command: 'test',
+      reason: 'only narrows a run together with --affected, and on its own it changes nothing',
+      fix: `x test --affected --${idle}${idle === 'base' ? ` ${DEFAULT_BASE}` : ''}`,
+    });
+  }
+  return undefined;
+}
+
+// The cast is guarded by the three lines above it and is the narrowing TS will not do on its own:
+// `Array.isArray` is declared `value is any[]`, which does not remove `readonly JsonValue[]` from
+// the union, so every branch here still carries the array arm however the check is written.
+const asObject = (value: JsonValue | undefined): Readonly<Record<string, JsonValue>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Readonly<Record<string, JsonValue>>)
+    : {};
+
+/**
+ * The scope, carried onto whatever the shards reported. `--json` is what an agent reads, and a
+ * narrowed run that does not say what it narrowed to is indistinguishable from a full one.
+ */
+const withScope = (result: CommandResult, scope: AffectedScope): CommandResult => ({
+  ...result,
+  data: { ...asObject(result.data), affected: affectedScopeJson(scope) },
+});
+
 export const testCommand: CliCommand = {
   spec: {
     name: 'test',
     summary:
       'run one test type — or the whole suite — across N processes, one isolated database per worker',
-    usage: `x test [${TEST_TYPES.join('|')}] [--filter text] [--sample N] [--workers N] [--worker I] [--json]`,
+    usage: `x test [${TEST_TYPES.join('|')}] [--filter text] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--worker I] [--json]`,
     positionalChoices: TEST_TYPES,
     flags: [
       {
@@ -78,17 +124,53 @@ export const testCommand: CliCommand = {
         summary:
           'run at most N files of the selected type — a fast signal for the eval loop, never a gate',
       },
+      {
+        name: 'affected',
+        type: 'boolean',
+        summary: 'only the workspaces a diff touches, and everything that depends on one of them',
+      },
+      {
+        name: 'base',
+        type: 'string',
+        summary: `--affected: git ref to diff against, merge-base style (default: ${DEFAULT_BASE})`,
+      },
+      {
+        name: 'dirty',
+        type: 'boolean',
+        summary:
+          '--affected: also count uncommitted work, whichever agent in this checkout made it',
+      },
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const type = readOnlyType(ctx.args.positionals);
     const filter = flagString(ctx.args, 'filter');
     const sample = readSample(ctx.args);
+    const scope = await readAffectedScope(ctx);
     const discovered = await discoverTests(ctx.cwd, filter, type);
     if (discovered.length === 0) {
       throw new NoTestFilesError({ root: ctx.cwd, ...missingSelection(type, filter) });
     }
-    const files = sample === undefined ? discovered : sampleFiles(discovered, sample);
+    const selected =
+      scope === undefined
+        ? discovered
+        : discovered.filter((file) => inScope(file.path, scope.prefixes));
+    if (scope !== undefined && selected.length === 0) {
+      // Green, and it spawns nothing — a `.md`-only diff genuinely re-checks nothing, and failing
+      // a build for editing a doc is the wrong answer. It never reads as "the suite passed": the
+      // summary counts the files that ran (zero) and `data.affected` names the diff it asked about,
+      // so a caller can always tell "green because nothing is affected" from "green because
+      // everything passed". Nothing reaches `runShards`, whose empty file list would be a
+      // `bun test` with no arguments — that is, the whole suite.
+      return ok('test', msg('cli.test.affected.none', { base: scope.selection.base }), {
+        data: {
+          ...(type === undefined ? {} : { type }),
+          files: 0,
+          affected: affectedScopeJson(scope),
+        },
+      });
+    }
+    const files = sample === undefined ? selected : sampleFiles(selected, sample);
     const requested = readIndex(ctx.args, 'workers', 1) ?? defaultWorkers();
     const workers = Math.max(1, Math.min(requested, files.length));
     const only = readIndex(ctx.args, 'worker', 0);
@@ -99,7 +181,7 @@ export const testCommand: CliCommand = {
         reason: `shard ${only} does not exist in a ${workers}-worker split (0..${workers - 1})`,
       });
     }
-    return runShards({
+    const result = await runShards({
       root: ctx.cwd,
       runner: ctx.runner,
       files,
@@ -108,7 +190,14 @@ export const testCommand: CliCommand = {
       ...(filter === undefined ? {} : { filter }),
       ...(type === undefined ? {} : { type }),
       // `kept` is the corpus the split saw; a `--worker` rerun must name it, not its own shard.
-      ...(sample === undefined ? {} : { sample: { kept: files.length, total: discovered.length } }),
+      // `selected`, not `discovered`: with `--affected` the sample was taken from the narrowed
+      // set, and reporting the whole tree as its total would name a corpus no run ever had.
+      ...(sample === undefined ? {} : { sample: { kept: files.length, total: selected.length } }),
+      // The fourth input to the split. Without it a failing shard's `fix:` re-splits the whole
+      // corpus, so its shard 2 is a different shard 2 — reproducing nothing, which is the one
+      // thing `reproduceFor` exists to prevent.
+      ...(scope === undefined ? {} : { affected: scope.selection }),
     });
+    return scope === undefined ? result : withScope(result, scope);
   },
 };

package/src/error-codes.ts

@@ -96,6 +96,14 @@ export const CLI_OWNED_ERROR_CODES = [
   // CLI's problem alone, and core would have no `fix:` to offer for one.
   'X_SECRETS_EDITOR_MISSING',
   'X_SECRETS_EDIT_FAILED',
+  'X_WORKSPACE_DEP_UNDECLARED',
+  'X_SHOT_BROWSER_MISSING',
+  'X_GH_UNAVAILABLE',
+  'X_GH_NOT_AUTHENTICATED',
+  'X_GH_COMMAND_FAILED',
+  'X_GH_RESPONSE_INVALID',
+  'X_PR_NOT_FOUND',
+  'X_CI_RUN_NOT_FOUND',
 ] as const;
 
 /**
@@ -188,6 +196,14 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_CLI_FLAG_UNREAD: 'a command declares a flag no code reads',
   X_SECRETS_EDITOR_MISSING: 'no $EDITOR to open the decrypted secrets in',
   X_SECRETS_EDIT_FAILED: 'the editor exited non-zero, so nothing was resealed',
+  X_WORKSPACE_DEP_UNDECLARED: 'a workspace imports another workspace it does not declare',
+  X_SHOT_BROWSER_MISSING: 'x shot found no browser library in the app',
+  X_GH_UNAVAILABLE: 'the GitHub CLI is not runnable from here',
+  X_GH_NOT_AUTHENTICATED: 'gh holds no credentials for this host',
+  X_GH_COMMAND_FAILED: 'a gh invocation exited non-zero',
+  X_GH_RESPONSE_INVALID: "gh's output is not the shape the command reads",
+  X_PR_NOT_FOUND: 'no pull request for this checkout',
+  X_CI_RUN_NOT_FOUND: 'no workflow run for this branch',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/gh-target.ts

@@ -0,0 +1,118 @@
+// Which repository, which pull request, which branch — the three facts `x pr` and `x ci` both
+// need before they can ask GitHub anything, resolved once here so the two commands can never
+// disagree about what "this checkout" means.
+
+import { UltimateError } from '@ultimat3/core';
+import { t } from '@ultimat3/schema';
+import { BadFlagError } from './errors';
+import type { GhHost } from './gh';
+import { GhFailedError, ghJson } from './gh';
+
+/** `owner/name`, split once so a caller never re-splits it and never re-joins it wrong. */
+export interface GhRepo {
+  readonly owner: string;
+  readonly name: string;
+  /** The `owner/name` spelling, which is what `--repo` takes and what every render prints. */
+  readonly slug: string;
+}
+
+/**
+ * A repository name is `[A-Za-z0-9._-]+` on both sides of one slash. Refused here rather than by
+ * GitHub, because `--repo` is the one field a caller types by hand: `--repo ultimate` reaches the
+ * API as an owner with no name and comes back `Could not resolve to a Repository`, which reads as
+ * "that repository is gone" rather than "that is not a repository reference".
+ */
+const SLUG = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+const REPO_VIEW = t.object({ nameWithOwner: t.string });
+
+/** No pull request for the branch this checkout is on. A number the caller knows closes it. */
+export class PrNotFoundError extends UltimateError {
+  constructor(input: { detail: string }) {
+    super({
+      code: 'X_PR_NOT_FOUND',
+      cause: `GitHub reports no pull request for this checkout: ${input.detail}`,
+      fix: 'x pr review --pr 241 --json   # or open one first with: gh pr create',
+    });
+  }
+}
+
+/**
+ * The repository this command is about. `--repo` when given, otherwise `gh repo view`, which
+ * resolves the same remote `gh pr` and `gh run` resolve — asking git for the remote here would be
+ * a second answer to a question gh already owns.
+ */
+export async function resolveRepo(
+  host: GhHost,
+  command: string,
+  flag: string | undefined,
+): Promise<GhRepo> {
+  if (flag !== undefined) {
+    if (!SLUG.test(flag)) {
+      throw new BadFlagError({
+        flag: 'repo',
+        command,
+        reason: `"${flag}" is not an owner/name repository reference`,
+        fix: `x ${command} --repo developerz-ai/ultimate --json`,
+      });
+    }
+    return repoOf(flag);
+  }
+  const viewed = await ghJson(host, ['repo', 'view', '--json', 'nameWithOwner'], REPO_VIEW, {
+    label: 'gh repo view',
+    fix: `x ${command} --repo developerz-ai/ultimate --json`,
+  });
+  return repoOf(viewed.nameWithOwner);
+}
+
+function repoOf(slug: string): GhRepo {
+  const [owner = '', name = ''] = slug.split('/');
+  return { owner, name, slug };
+}
+
+const PR_VIEW = t.object({ number: t.number });
+
+/**
+ * The pull request for the current branch. gh exits non-zero when there is none, with a message
+ * that names the branch — so the refusal keeps gh's own sentence and adds the remedy gh has no
+ * opinion about: name the number, or open the PR.
+ */
+export async function resolvePrNumber(host: GhHost, repo: GhRepo): Promise<number> {
+  try {
+    const viewed = await ghJson(
+      host,
+      ['pr', 'view', '--repo', repo.slug, '--json', 'number'],
+      PR_VIEW,
+      { label: 'gh pr view', fix: 'x pr review --pr 241 --json' },
+    );
+    return viewed.number;
+  } catch (error) {
+    if (error instanceof GhFailedError) throw new PrNotFoundError({ detail: error.cause });
+    throw error;
+  }
+}
+
+/**
+ * The branch this checkout is on, from git rather than from gh: gh has no "current branch"
+ * question, only commands that answer one for you. A detached HEAD answers `HEAD`, which matches
+ * no branch on GitHub — the caller's own "no run for this branch" refusal names `--branch`, so a
+ * second refusal here would only move the same instruction one step earlier.
+ *
+ * Spawn failures are deliberately NOT caught: `exec.ts` refuses a missing program with a fix that
+ * already names `git`, and re-labelling that as a GitHub problem would send the reader to the
+ * wrong install.
+ */
+export async function currentBranch(host: GhHost): Promise<string> {
+  const result = await host.runner(['git', 'rev-parse', '--abbrev-ref', 'HEAD'], {
+    cwd: host.cwd,
+  });
+  if (!result.ok) {
+    throw new GhFailedError({
+      label: 'git rev-parse --abbrev-ref HEAD',
+      code: result.code,
+      detail: result.stderr.split('\n')[0]?.trim() ?? '',
+      fix: 'x ci --branch main --json',
+    });
+  }
+  return result.stdout.trim();
+}

package/src/gh.ts

@@ -0,0 +1,204 @@
+// The one seam between the CLI and the `gh` binary. Every GitHub call is built here and spawned
+// through the injected `Runner`, so a test asserts the exact argv with no network and no `gh`
+// installed — and the four ways this shell-out fails (no binary, no credentials, a non-zero exit,
+// an answer that will not parse) each get one code and one executable fix instead of a stack trace.
+
+import { renderThrowable, singleLine, UltimateError } from '@ultimat3/core';
+import type { AnySchema, InferOutput } from '@ultimat3/schema';
+import { formatPath } from '@ultimat3/schema';
+import type { ExecResult, Runner } from './exec';
+import { execOutput } from './exec';
+
+/** What a gh call needs from a `CommandContext`, and nothing more — so a test passes two fields. */
+export interface GhHost {
+  readonly runner: Runner;
+  readonly cwd: string;
+}
+
+export interface GhOptions {
+  /**
+   * A short name for this call. Every refusal is titled with it rather than with the argv,
+   * because a GraphQL document pasted into a `cause:` is a page of text where a reader needs a
+   * sentence.
+   */
+  readonly label: string;
+  /**
+   * The caller's remedy, and REQUIRED: the seam knows a call failed and never what the operator
+   * was trying to do, so a generic fix here would be axiom 4 inverted at the one boundary every
+   * GitHub call crosses. Making it a field of the options is what turns "state a remedy" into a
+   * build error rather than a convention.
+   */
+  readonly fix: string;
+}
+
+/** The one binary this file spawns. Named once, so every argv assertion has a single source. */
+export const GH_BIN = 'gh';
+
+/**
+ * No `gh` on PATH. `exec.ts` already refuses a missing program with `X_CLI_UNEXPECTED`, and that
+ * code's fix names the binary — but "the CLI itself failed" is the wrong sentence for a machine
+ * that simply has no GitHub client, and `gh auth login` is not reachable from it.
+ */
+export class GhUnavailableError extends UltimateError {
+  constructor(input: { cwd: string; detail: string }) {
+    super({
+      code: 'X_GH_UNAVAILABLE',
+      cause: `the GitHub CLI could not be run from ${input.cwd}: ${input.detail}`,
+      fix: 'install the GitHub CLI from https://cli.github.com, then run: gh auth login',
+    });
+  }
+}
+
+/** `gh` is installed and holds no usable credentials for this host. One command closes it. */
+export class GhNotAuthenticatedError extends UltimateError {
+  constructor(input: { label: string; detail: string }) {
+    super({
+      code: 'X_GH_NOT_AUTHENTICATED',
+      cause: `${input.label} was refused by GitHub: ${input.detail}`,
+      fix: 'gh auth login',
+    });
+  }
+}
+
+/** Any other non-zero exit — a bad id, a repository that is not there, a rate limit. */
+export class GhFailedError extends UltimateError {
+  constructor(input: { label: string; code: number; detail: string; fix: string }) {
+    super({
+      code: 'X_GH_COMMAND_FAILED',
+      cause: `${input.label} exited ${input.code}: ${input.detail}`,
+      fix: input.fix,
+    });
+  }
+}
+
+/**
+ * `gh` answered, and the answer is not the shape this command reads. A cast would carry the
+ * mismatch into the render and print `undefined` at whichever field moved; the parse refuses at
+ * the boundary instead, which is the only place the argv that produced it is still known.
+ */
+export class GhResponseInvalidError extends UltimateError {
+  constructor(input: { label: string; detail: string; fix: string }) {
+    super({
+      code: 'X_GH_RESPONSE_INVALID',
+      cause: `${input.label} answered something this command cannot read: ${input.detail}`,
+      fix: input.fix,
+    });
+  }
+}
+
+/**
+ * The spellings `gh` uses when the token is the problem. Matched against its own output rather
+ * than against an exit code, because every one of these exits 1 exactly like a typo'd id does —
+ * and the two have different remedies.
+ */
+const UNAUTHENTICATED =
+  /not logged in|gh auth login|HTTP 401|Bad credentials|GH_TOKEN|GITHUB_TOKEN|authentication/i;
+
+/** The first line a human would read, escaped and bounded — a `cause:` is one line by contract. */
+export function ghDetail(result: ExecResult): string {
+  const merged = execOutput(result);
+  const first = merged.split('\n').find((line) => line.trim().length > 0) ?? '';
+  const text = singleLine(first.trim().replace(/^gh:\s*/, ''));
+  return text.length > 200 ? `${text.slice(0, 200)}…` : text;
+}
+
+/**
+ * One `gh` invocation, refused four ways. A spawn failure is mapped rather than rethrown: it is
+ * the "no GitHub CLI on this machine" case, and `exec.ts`'s own refusal cannot offer `gh auth
+ * login` as the next step.
+ */
+export async function runGh(
+  host: GhHost,
+  args: readonly string[],
+  options: GhOptions,
+): Promise<ExecResult> {
+  let result: ExecResult;
+  try {
+    result = await host.runner([GH_BIN, ...args], { cwd: host.cwd });
+  } catch (error) {
+    // Never interpolated: the thrown value is genuinely unknown here (Bun raises `ENOENT` for a
+    // missing program and `EACCES` for an unrunnable one), which is what `bun run error-render`
+    // refuses to see reach a `cause:` through `${…}`.
+    throw new GhUnavailableError({ cwd: host.cwd, detail: renderThrowable(error) });
+  }
+  if (result.ok) return result;
+  const detail = ghDetail(result);
+  if (UNAUTHENTICATED.test(detail)) {
+    throw new GhNotAuthenticatedError({ label: options.label, detail });
+  }
+  throw new GhFailedError({ label: options.label, code: result.code, detail, fix: options.fix });
+}
+
+/**
+ * `gh --json`, parsed rather than cast. The response is untrusted input — a different `gh`
+ * version, a proxy that answered HTML, a field GitHub renamed — so it goes through the schema the
+ * caller declared and a mismatch is a coded refusal naming the call that produced it.
+ */
+export async function ghJson<S extends AnySchema>(
+  host: GhHost,
+  args: readonly string[],
+  schema: S,
+  options: GhOptions,
+): Promise<InferOutput<S>> {
+  const result = await runGh(host, args, options);
+  let payload: unknown;
+  try {
+    payload = JSON.parse(result.stdout);
+  } catch (error) {
+    throw new GhResponseInvalidError({
+      label: options.label,
+      detail: renderThrowable(error),
+      fix: options.fix,
+    });
+  }
+  const parsed = schema.safeParse(payload);
+  if (parsed.issues !== undefined) {
+    const first = parsed.issues[0];
+    // `formatPath` is the schema package's own renderer for an issue path — a second spelling of
+    // `items[0].price` here would be a field name that does not match the one every other
+    // validation failure in the framework prints.
+    throw new GhResponseInvalidError({
+      label: options.label,
+      detail:
+        first === undefined
+          ? 'the response matched no field this command declares'
+          : `${formatPath(first.path)} ${first.message}`.trim(),
+      fix: options.fix,
+    });
+  }
+  return parsed.value as InferOutput<S>;
+}
+
+/**
+ * A GraphQL call, and the two `gh` field flags are not interchangeable — the type of the variable
+ * decides which one is correct, so the type of the value decides here.
+ *
+ * A **string** rides as `-f`, never `-F`: `-F` reads `@file` as "load this from disk", so a review
+ * reply whose body begins with an `@` would post the contents of a local file. A **number** has to
+ * ride as `-F`, because `-f` sends every value as a GraphQL `String` and a `$n:Int!` parameter
+ * refuses one (measured: `gh api graphql … -f n=238` against `Int!` is a `variableNotUsed`/type
+ * error, `-F n=238` succeeds). `-F` is safe for a number precisely because a number can never
+ * spell `@file`.
+ *
+ * The caller's schema describes the WHOLE envelope (`{ data: … }`) rather than its inside: gh
+ * exits non-zero whenever the response carries `errors`, so a partial answer never reaches here,
+ * and a caller that spells out the envelope keeps every nullable GitHub returns visible.
+ */
+export async function ghGraphql<S extends AnySchema>(
+  host: GhHost,
+  document: string,
+  variables: Readonly<Record<string, string | number>>,
+  schema: S,
+  options: GhOptions,
+): Promise<InferOutput<S>> {
+  const args = [
+    'api',
+    'graphql',
+    '-f',
+    `query=${document}`,
+    ...Object.entries(variables).flatMap(([name, value]) =>
+      typeof value === 'number' ? ['-F', `${name}=${value}`] : ['-f', `${name}=${value}`],
+    ),
+  ];
+  return ghJson(host, args, schema, options);
+}

package/src/index.ts

@@ -60,6 +60,12 @@ export {
   plannedCommands,
   plannedSubcommand,
 } from './cmd-planned';
+// `shotCommand`, `prCommand` and `ciCommand` are deliberately NOT re-exported here. They reach
+// `x` through `registry.ts`, which is the only thing that makes a command exist — and the barrel
+// is the surface an APP imports. Exporting them puts `cmd-shot.ts` in the module graph of every
+// app that imports `@ultimat3/cli`, which then has to resolve `@ultimat3/scraping` — a browser
+// driver it never uses. Measured: it reds `tsc -b` on `dummy/social-media-clone` with five
+// TS2307s in files that app never calls. The app path does not pay for the tool path.
 export { actionsCommand, entitiesCommand, queriesCommand } from './cmd-registries';
 export { renderRouteTable, routesCommand } from './cmd-routes';
 export { testCommand } from './cmd-test';
@@ -177,6 +183,13 @@ export type { DeclaredFlag } from './flag-reads';
 export { checkFlagReads, declaredFlags, readsFlag } from './flag-reads';
 export type { Guard } from './guards';
 export { findingProblem, GUARD_DIR, guardFindings, guardPaths } from './guards';
+// The island bundler, and only its entry point. An island is the one module Ultimate ships to a
+// browser, so an app has to be able to build one to TEST one — `mountIsland` from
+// `@ultimat3/testing` takes this function as its `build` parameter (issue #260). `discoverIslands`,
+// `islandBundle`, `writeIslands`, `ISLAND_BASE_PATH` and `ISLAND_GLOB` stay internal: they are
+// `x build`'s and `x dev`'s wiring, and every name here is a semver promise forever.
+export type { IslandBundle, IslandChunk } from './island-bundle';
+export { buildIslands } from './island-bundle';
 export type { DrainFailure, DrainOutcome, DrainSkip } from './jobs-drain';
 export { drainJobs } from './jobs-drain';
 export type { JobsListFilter, JobsListResult } from './jobs-report';
@@ -235,6 +248,24 @@ export {
   isVendored,
   SOURCE_GLOBS,
 } from './source-files';
+export type {
+  EmittedPage,
+  RouteFacts,
+  SkippedRoute,
+  SkipReason,
+  StaticReport,
+} from './static-report';
+export {
+  parseStaticReport,
+  readStaticReport,
+  removeStaticReport,
+  renderStaticReport,
+  SKIP_REASONS,
+  STATIC_REPORT_FILE,
+  skippedRoute,
+  skipReasonFor,
+  writeStaticReport,
+} from './static-report';
 export type { TestCounts } from './test-counts';
 export { countsOf } from './test-counts';
 export type { TestFile } from './test-select';
@@ -286,4 +317,10 @@ export {
   SEMVER,
   workspacePackages,
 } from './workspace-checks';
+export type { WorkspaceNode, WorkspaceScan } from './workspace-graph';
+// The graph itself, not just the gate's verdict on it: issue #239's complaint is that a
+// scaffolded repo's dependency graph exists only inside `tsc`, so an app's own tooling has
+// nothing to read. `checkWorkspaceDependencies` stays internal — it is reached through
+// `x verify`, which is the one way a rule is enforced here.
+export { readWorkspaceGraph, scanWorkspaces } from './workspace-graph';
 export { writeLine } from './write-line';

package/src/island-bundle.ts

@@ -13,6 +13,8 @@ import {
   islandModuleId,
 } from '@ultimat3/render';
 import { IslandBuildFailedError } from './errors';
+import { solidProductionPlugin } from './island-solid-production';
+import { islandStylesPlugin } from './island-styles';
 import { solidJsxPlugin } from './solid-loader';
 
 /**
@@ -84,7 +86,13 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
       // an island. The app's tsconfig says `jsx: "preserve"`, which makes the bundler fall back to
       // classic `React.createElement` — emitted into a browser chunk that imports no React, with
       // `success: true` and no log. Every island shipped that way through five majors.
-      plugins: [solidJsxPlugin],
+      //
+      // The other two close the same shape of failure — a wrong answer `Bun.build` reports as
+      // `success: true`: without the second, `target: 'browser'` resolves the `development`
+      // export condition and the chunk carries Solid's dev build; without the third, Bun's file
+      // loader resolves a `.module.scss` to its asset PATH, so `styles['x']` is `undefined` and
+      // every element renders unclassed.
+      plugins: [solidJsxPlugin, solidProductionPlugin, islandStylesPlugin],
     });
   } catch (error) {
     throw new IslandBuildFailedError({ file, logs: describeBuildError(error) });
@@ -121,13 +129,64 @@ function describeBuildError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+export interface BuildIslandsOptions {
+  /**
+   * Build ONE island, named app-root-relative — the whole option surface. A test that mounts a
+   * single island otherwise pays every OTHER island's Babel pass and `Bun.build` on every file,
+   * and the reference app is the one that feels it.
+   *
+   * Optional, and it must stay optional: `buildIslands` is on `@ultimat3/cli`'s public surface and
+   * `@ultimat3/testing`'s `IslandBuilder` satisfies it STRUCTURALLY as `(root: string) => …`, which
+   * is what keeps the `cli -> testing` edge pointing the one legal way.
+   */
+  readonly only?: string;
+}
+
 /** Build every island in the app. An app with none returns an empty bundle and costs one glob. */
-export async function buildIslands(root: string): Promise<IslandBundle> {
-  const files = await discoverIslands(root);
+export async function buildIslands(
+  root: string,
+  options: BuildIslandsOptions = {},
+): Promise<IslandBundle> {
+  const discovered = await discoverIslands(root);
+  const only = options.only;
+  const files = only === undefined ? discovered : discovered.filter((file) => file === only);
+  // A filter that matches nothing is a typo in the CALLER, never an app with no islands. Answering
+  // an empty bundle here would surface two steps later, as a chunk table with no entry for a file
+  // the caller can see on disk.
+  if (only !== undefined && files.length === 0) throw onlyMissing(only, discovered);
   const chunks = await Promise.all(files.map((file) => buildOne(root, file)));
   return islandBundle(chunks);
 }
 
+/**
+ * Same code as an unbuildable `src`: "this path cannot become a client entry" is one condition.
+ *
+ * Two fixes, because there are two causes and only one of them can be repaired by naming a path.
+ * The line was `pass only: '<app-root-relative path>.island.tsx'` — a placeholder nobody can run,
+ * which no gate could see: `fixProblem` fails a fix only for ADVICE with no command token, and a
+ * sentence with neither is not advice. Both forms below are constructed from what the caller
+ * already handed in, so neither can name a path this app does not have.
+ */
+function onlyMissing(only: string, discovered: readonly string[]): IslandInvalidError {
+  const cause =
+    `buildIslands was asked for ${JSON.stringify(only)} alone, which is not one of the ` +
+    `${discovered.length} islands this app has (${discovered.length === 0 ? 'none' : discovered.join(', ')})`;
+  // The basename match first: a filter that misses normally missed on the PREFIX — a route-relative
+  // specifier where `discoverIslands`' app-root-relative path was wanted — and the filename
+  // survives that. Falling back to the first keeps the fix a real path rather than a shape.
+  const nearest =
+    discovered.find((file) => posix.basename(file) === posix.basename(only)) ?? discovered[0];
+  // An app with no islands cannot be pointed at one, so the fix WRITES the file that was asked
+  // for — the same command `entryMissing` hands back, split off the same path.
+  if (nearest === undefined) {
+    return new IslandInvalidError(
+      cause,
+      `x g island ${posix.basename(only, ISLAND_EXTENSION)} --at ${posix.dirname(only)}`,
+    );
+  }
+  return new IslandInvalidError(cause, `buildIslands(root, { only: '${nearest}' })`);
+}
+
 export function islandBundle(chunks: readonly IslandChunk[]): IslandBundle {
   const byFile = new Map(chunks.map((chunk) => [chunk.file, chunk]));
   const byUrl = new Map(chunks.map((chunk) => [chunk.url, chunk]));