@ultimat3/cli 19.2.0 → 19.3.2

package/src/doctor-offline.ts

@@ -0,0 +1,122 @@
+// `x doctor`'s offline-fallback check: the path the app DECLARED, against the routes it really
+// serves. Its own file because answering it needs the app's config and its route table, and
+// `cmd-doctor.ts`'s job is the probe rather than the loading — the `db-backfill.ts` split, one
+// diagnostic over.
+
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { describeRoutes } from '@ultimat3/render';
+import { loadApp } from './app-load';
+import { APP_CONFIG_FILE } from './app-root';
+import type { Finding } from './output';
+import { loadPwaArtifacts } from './pwa-artifacts';
+
+/** A route as this check reads one: the URL it answers, and the surface that answers it. */
+export interface NavigableRoute {
+  readonly path: string;
+  readonly surface: string;
+}
+
+export interface OfflineFallbackFact {
+  /**
+   * `pwa.offline.fallback` as `loadPwaArtifacts` read it, or `null` — which is both "this app
+   * declares no PWA" and "it declares one with no fallback". Either way no service worker is
+   * emitted at all (`serviceWorkerArtifacts` answers `undefined`), so the two share one remedy.
+   */
+  readonly fallback: string | null;
+  /**
+   * Every registered route, or `undefined` when the app would not load. `appEntities`' rule
+   * (`schema-drift.ts`) one registry over: a module that will not import leaves the registry
+   * short, and a short registry reads as "no route serves it" — a generator handed out for a route
+   * the app already has, over one file's syntax error.
+   */
+  readonly routes: readonly NavigableRoute[] | undefined;
+}
+
+/**
+ * The one surface an OFFLINE navigation can land on. `api/` answers a JSON document and `shared/`
+ * is not a URL at all — the pair `sw-artifacts.ts` excludes for the same reason — and `app/` is
+ * excluded for a third: `SURFACE_SPECS` allows it `stream | ssr` and nothing else, only a `static`
+ * route is prerendered, and the service worker precaches a rendered DOCUMENT
+ * (`serviceWorkerArtifacts` reads `documents.get(fallback)`). So an `app/` fallback has nothing
+ * to precache and the offline navigation it is supposed to answer reaches the network and fails —
+ * this check passing for it is the false green it exists to prevent.
+ *
+ * It accepted `app` until 2026-09, on the argument that both surfaces answer the same URL and it
+ * is the FIX that is opinionated. True about URLs and wrong about offline: the fix's own comment
+ * below already refuses `--surface app`, so the check and the remedy disagreed about one code.
+ *
+ * Residual, and NOT closed by this: a `site/` route declaring `render: 'ssr'` is not prerendered
+ * either. `NavigableRoute` carries no render mode, and `describeRoutes()` has one — the narrower
+ * check belongs with it.
+ */
+const NAVIGABLE: ReadonlySet<string> = new Set(['site']);
+
+/**
+ * A fallback `x g route <name> --surface site` can actually create: ONE path segment, which is
+ * what the generator turns into `apps/<app>/site/<name>/page.tsx` and therefore into `/<name>`. A
+ * nested or punctuated path would be slugified into a DIFFERENT url (`/support/offline` →
+ * `/support-offline`), so offering the command there is a fix that runs and leaves the finding
+ * exactly where it was.
+ *
+ * `--surface site`, and never `app`: the document that answers a lost network must render with no
+ * network, no session and no database, which `app/` (`ssr | stream`) cannot promise — the reason
+ * `x new` scaffolds it under `site/` (`wiki/Upgrading.md`) — and it is the line `@ultimat3/pwa`'s
+ * own `X_PWA_NO_OFFLINE_FALLBACK` hands out. Two fixes for one code are two answers.
+ */
+const GENERATABLE = /^\/([a-z][a-z0-9-]*)$/;
+
+const finding = (cause: string, fix: string): Finding => ({
+  code: 'X_PWA_NO_OFFLINE_FALLBACK',
+  cause,
+  fix,
+  docs: ERROR_DOCS_URL,
+  at: APP_CONFIG_FILE,
+});
+
+/**
+ * The declared fallback, judged against the route table — never against a filename.
+ *
+ * It WAS a filename: the literal `apps/web/app/offline.tsx`, which `assertRouteFilename` refuses
+ * outright (the directory is the URL, so a page is `page.tsx`), while `x new` scaffolds
+ * `apps/web/site/offline/page.tsx` and this finding's own `fix:` writes
+ * `apps/web/app/offline/page.tsx`. Every one of the three is a different path, so the check was
+ * red for every app the framework has ever produced and no invocation could clear it — the shape
+ * `budgets.ts` calls a false green read backwards, and the reason a diagnostic is held to being
+ * closable by its own fix.
+ */
+export function offlineFallbackFinding(fact: OfflineFallbackFact): Finding | undefined {
+  if (fact.routes === undefined) return undefined;
+  const fallback = fact.fallback;
+  if (fallback === null) {
+    return finding(
+      'no pwa.offline.fallback is declared, so no service worker is emitted and an offline navigation falls back to the browser error page',
+      `set pwa: { offline: { fallback: '/offline' } } in ${APP_CONFIG_FILE}`,
+    );
+  }
+  if (fact.routes.some((route) => route.path === fallback && NAVIGABLE.has(route.surface))) {
+    return undefined;
+  }
+  const cause = `pwa.offline.fallback is "${fallback}" and no site/ route serves it, so an offline navigation falls back to the browser error page`;
+  const name = GENERATABLE.exec(fallback)?.[1];
+  return name === undefined
+    ? finding(cause, `set pwa.offline.fallback in ${APP_CONFIG_FILE} to a path a route serves`)
+    : finding(cause, `x g route ${name} --surface site`);
+}
+
+/**
+ * The fact, read off a real app root. Both halves come from the framework's own answers — the
+ * config through `loadPwaArtifacts` (the one reader of that file) and the routes through
+ * `describeRoutes()` (the projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all
+ * built from), so this check and the service worker cannot disagree about which routes exist.
+ */
+export async function offlineFallbackProbe(root: string): Promise<OfflineFallbackFact> {
+  const pwa = await loadPwaArtifacts(root);
+  const app = await loadApp(root);
+  return {
+    fallback: pwa?.offline.fallback ?? null,
+    routes:
+      app.findings.length > 0
+        ? undefined
+        : describeRoutes().map((route) => ({ path: route.path, surface: route.surface })),
+  };
+}

package/src/error-catalog.ts

@@ -3,7 +3,7 @@
 // commands actually need — so without this, `x errors explain X_UNAUTHENTICATED` answered "not a
 // registered error code" for a code the framework throws on every unauthenticated request.
 
-import { listErrorCodes } from '@ultimat3/core';
+import { listErrorCodes, stringField } from '@ultimat3/core';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 
@@ -82,10 +82,9 @@ let cached: Promise<ErrorCatalog> | undefined;
  * the host gap. Anything else escaped the package's own module evaluation and is its defect.
  */
 const isUnresolved = (thrown: unknown): boolean =>
-  typeof thrown === 'object' &&
-  thrown !== null &&
-  'code' in thrown &&
-  thrown.code === 'ERR_MODULE_NOT_FOUND';
+  // `stringField`, never `'code' in thrown && thrown.code`: see `cmd-i18n.ts`'s `isAlreadyExists`
+  // — an `in` guard narrows the type and reads the property off a foreign value all the same.
+  stringField(thrown, 'code') === 'ERR_MODULE_NOT_FOUND';
 
 /** The package's own error, named and located, so the report says what broke and what to run. */
 function initFailure(specifier: string, thrown: unknown): Finding {

package/src/fix-command.ts

@@ -45,6 +45,18 @@ const CITATION = new RegExp(
  */
 const FLAG = /(?:^|\s)--(?:no-)?([a-z][a-z\d-]*)/g;
 
+/**
+ * A bare `--`: the boundary past which the words belong to ANOTHER tool, not to `x`. Only `x test`
+ * declares one (`CommandSpec.passthrough`), and every other command refuses a non-empty tail — so
+ * this is read for two reasons at once: the tail's flags are not the command's, and a tail cited
+ * on a command that hands nothing on is a documented `X_CLI_BAD_FLAG`.
+ *
+ * Without it, `x test unit -- --coverage --bail` — the only spelling that reaches bun's own flags
+ * — read as `x test --coverage`, and the one line documenting the passthrough was a standing
+ * false finding on the rule written to keep documented invocations runnable.
+ */
+const BARE_TAIL = /(?:^|\s)--(?=\s|$)/;
+
 /**
  * Where a citation's argument list ends. `;`, `|` and `&` start a second shell word, `#` starts a
  * comment, and a backtick or a quote closes the span the citation was written in — past any of
@@ -60,6 +72,11 @@ export interface FixCitation {
   readonly positional: string | undefined;
   /** Long flags written after it, in order, `--` and any `no-` stripped. */
   readonly flags: readonly string[];
+  /**
+   * The words after a bare `--`, when the citation has one. Absent otherwise, so a citation with
+   * no tail is the same object it has always been.
+   */
+  readonly tail?: readonly string[];
 }
 
 /**
@@ -82,11 +99,24 @@ export function fixCitations(fix: string): readonly FixCitation[] {
     const tail = fix.slice(start, next);
     const stop = ARGUMENT_END.exec(tail)?.index;
     const args = stop === undefined ? tail : tail.slice(0, stop);
+    // The tail is split off BEFORE the flags are read: `--coverage` after a bare `--` is bun's
+    // flag, and charging it to `x test` is the same error as charging a second citation's flags
+    // to the first one, which the slice above already exists to prevent.
+    const cut = BARE_TAIL.exec(args);
+    const head = cut === null ? args : args.slice(0, cut.index);
+    const handed =
+      cut === null
+        ? undefined
+        : args
+            .slice(cut.index + cut[0].length)
+            .split(/\s+/)
+            .filter((word) => word !== '');
     return {
       command: match[1] as string,
       sub: match[2],
       positional: match[3],
-      flags: [...args.matchAll(FLAG)].map((flag) => flag[1] as string),
+      flags: [...head.matchAll(FLAG)].map((flag) => flag[1] as string),
+      ...(handed === undefined ? {} : { tail: handed }),
     };
   });
 }
@@ -222,6 +252,15 @@ export function citationFault(
     }
   }
   if (planned) return undefined;
+  // Judged before the flags, because a tail is why they are not the command's. A command that
+  // declares no `passthrough` refuses a non-empty `--` outright (`parse.ts`), so a page handing a
+  // reader one is handing them `X_CLI_BAD_FLAG` — the same class as an undeclared flag.
+  if (citation.tail !== undefined && citation.tail.length > 0 && spec.passthrough !== true) {
+    return {
+      subject: `x ${spec.name} --`,
+      reason: `and ${spec.name} hands nothing to another tool — the parser refuses the -- with X_CLI_BAD_FLAG rather than dropping ${citation.tail.join(' ')}`,
+    };
+  }
   const declared = declaredFlags(spec);
   const unknown = citation.flags.find((flag) => !declared.has(flag));
   if (unknown === undefined) return undefined;

package/src/fix-path.ts

@@ -5,10 +5,11 @@
 
 // why: Bun exposes no synchronous existence primitive — `Bun.file(p).exists()` is async and answers
 // false for a DIRECTORY, and this rule has to judge both. Delete when Bun ships one.
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 // why: Bun exposes no path-join or dirname primitive. The same necessity `error-contract.ts`
 // already records for `join`.
 import { dirname, join } from 'node:path';
+import { readIgnoreFile } from './gitignore';
 
 /**
  * The extensions a fix line may cite a file by — the SAME set `COMMAND_TOKENS`' file pattern is
@@ -77,22 +78,20 @@ function isJudgeable(token: string, root: string): boolean {
 /**
  * The directories the root `.gitignore` lists as ignored, as `dir/` prefixes. Only the plain
  * directory form is read (`.personal/`, `/tmp/`, `dist`): a negation, a glob or a nested pattern
- * is a rule about files the repo may still hold, and this exclusion errs towards judging.
+ * is a rule about files the repo may still hold, and this exclusion errs towards judging — which
+ * is why it keeps its own narrow policy over `parseGitignore`'s answer rather than asking
+ * `isGitIgnored`. What it may NOT keep is a second PARSER: `dev-watch.ts` needs full gitignore
+ * semantics, and two readers of one file are two answers to what an app committed.
  */
 const ignoredDirs = new Map<string, readonly string[]>();
 
 function ignoredDirectories(root: string): readonly string[] {
   const known = ignoredDirs.get(root);
   if (known !== undefined) return known;
-  const file = join(root, '.gitignore');
-  const lines = existsSync(file) ? readFileSync(file, 'utf8').split('\n') : [];
-  const dirs = lines
-    .map((line) => line.trim())
-    .filter((line) => line !== '' && !line.startsWith('#') && !line.startsWith('!'))
-    .filter((line) => !/[*?[\]]/.test(line))
-    .map((line) => line.replace(/^\//, '').replace(/\/$/, ''))
-    .filter((line) => line !== '' && !line.includes('/'))
-    .map((dir) => `${dir}/`);
+  const dirs = readIgnoreFile(root)
+    .filter((pattern) => !pattern.negated)
+    .filter((pattern) => !/[*?[\]]/.test(pattern.glob) && !pattern.glob.includes('/'))
+    .map((pattern) => `${pattern.glob}/`);
   ignoredDirs.set(root, dirs);
   return dirs;
 }

package/src/flag-number.ts

@@ -65,3 +65,18 @@ export const PORT_RANGE = { min: 0, max: 65_535 } as const;
  */
 export const neighbouringPort = (port: number): number =>
   port < PORT_RANGE.max ? port + 1 : PORT_RANGE.max - 1;
+
+/**
+ * The same suggestion for a caller that binds a PAIR. `x dev --port N` occupies N and N + 1, so
+ * `neighbouringPort` hands back the neighbour — which, when it is the neighbour that was taken, is
+ * the very socket the refusal is about: `x dev --port 3999` died on 4000 and its `fix:` said
+ * `x dev --port 4000`, and `x doctor` said it too, about the same pair (both pinned by a test
+ * named "its fix is a command that ends the failure"). Two above is the nearest base whose own
+ * pair touches neither.
+ *
+ * Downward at the top of the range, for `neighbouringPort`'s reason and one further: the answer's
+ * OWN neighbour has to be a port, or `syncPortFor` refuses the suggestion with `X_PORT_INVALID`.
+ * Only reachable above 65532, so the subtraction can never go below the range.
+ */
+export const portPairAfter = (port: number): number =>
+  port + 2 < PORT_RANGE.max ? port + 2 : port - 2;

package/src/generate-files.ts

@@ -48,6 +48,13 @@ export interface GenerateOptions {
    * package, and only then does a generated file import `t` from `@ultimat3/i18n` instead.
    */
   readonly catalogModule?: string;
+  /**
+   * `action` and `mutator`: the slice's `errors.ts` as it stands on disk, absent when there is
+   * none. Supplied by `run` for `catalogModule`'s reason — whether the slice declares
+   * `<Feature>NotFoundError` is a fact about THIS app, and a template that assumed it wrote an
+   * import of a class the app never declared. Read at `sliceDir(surface, feature)/errors.ts`.
+   */
+  readonly sliceErrors?: string;
 }
 
 const DEFAULT_SURFACE_DIR: Record<Surface, string> = {
@@ -55,6 +62,10 @@ const DEFAULT_SURFACE_DIR: Record<Surface, string> = {
   app: 'apps/web/app',
 };
 
+/** Where a feature slice lives, relative to the app root — the one derivation `run` reads from. */
+export const sliceDir = (surface: Surface, feature: string): string =>
+  `${DEFAULT_SURFACE_DIR[surface]}/${feature}`;
+
 /**
  * Pure: returns the files a generator would write. `x g` writes them, the generator test asserts
  * on them, and nothing has to run a filesystem to review what a generator produces.
@@ -76,9 +87,20 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
         }),
       );
     case 'action':
-      return dedupe(actionFiles(options.name, target));
+      return dedupe(
+        actionFiles(options.name, {
+          ...target,
+          ...(options.sliceErrors === undefined ? {} : { sliceErrors: options.sliceErrors }),
+        }),
+      );
     case 'mutator':
-      return dedupe(actionFiles(options.name, { ...target, mutator: true }));
+      return dedupe(
+        actionFiles(options.name, {
+          ...target,
+          mutator: true,
+          ...(options.sliceErrors === undefined ? {} : { sliceErrors: options.sliceErrors }),
+        }),
+      );
     case 'backfill':
       return dedupe(backfillFiles(options.name, target));
     case 'entity':

package/src/generate-kinds.ts

@@ -3,7 +3,12 @@
 // that held both had reached the 500-line ceiling, one generator short of failing its own gate.
 
 import { nearestName } from '@ultimat3/core';
-import { BadFlagError, MissingPositionalError, UnknownCommandError } from './errors';
+import {
+  BadFlagError,
+  MissingPositionalError,
+  MissingSubcommandError,
+  UnknownCommandError,
+} from './errors';
 import type { Surface } from './templates';
 
 export const GENERATORS = [
@@ -57,14 +62,26 @@ export function assertSurfaceSupported(kind: Generator, surface: Surface, name:
  * pins for a command that resembles nothing, and the reason `nearestName` is never asked about an
  * ABSENT kind: the empty string is within the cutoff of `job`, so `x g` would "suggest" a
  * generator nobody typed.
+ *
+ * And a THIRD rule, for the word that is not there at all: no generator is a missing subcommand,
+ * never an unknown command — see the branch below.
  */
 export function readKind(raw: string | undefined): Generator {
   const kinds: readonly string[] = GENERATORS;
   if (raw !== undefined && kinds.includes(raw)) return raw as Generator;
-  const near = raw === undefined ? undefined : nearestName(raw, kinds);
+  // A MISSING generator is not an unknown command. `x g --json` answered `X_CLI_UNKNOWN_COMMAND:
+  // "x g" is not a command` — false, and it sends an agent hunting a typo it did not make: `g` is
+  // in `x help`, the parser reaches it, and `x g route foo` runs. The same argument `readName`
+  // makes below about the missing `<name>`, one word earlier. `MissingSubcommandError` because
+  // the generator is a closed vocabulary the caller did not choose from — its cause lists every
+  // one, which is the answer to "which of these did I leave out"; the near-miss reader below is
+  // deliberately never asked about an absent word, since the empty string is within `job`'s
+  // cutoff and would "suggest" a generator nobody typed.
+  if (raw === undefined) throw new MissingSubcommandError({ command: 'g', known: GENERATORS });
+  const near = nearestName(raw, kinds);
   const suggestion = GENERATORS.find((kind) => kind === near);
   throw new UnknownCommandError({
-    path: `g ${raw ?? ''}`.trim(),
+    path: `g ${raw}`.trim(),
     known: GENERATORS,
     suggestion: suggestion === undefined ? 'help g' : `g ${suggestion} ${EXAMPLE_NAME[suggestion]}`,
   });
@@ -93,7 +110,40 @@ export function readName(raw: string | undefined, kind: Generator): string {
   throw new MissingPositionalError({
     command: `g ${kind}`,
     positional: 'name',
-    example: `x g ${kind} ${EXAMPLE_NAME[kind]}`,
+    example: exampleFor(kind),
+  });
+}
+
+/**
+ * The one read of `EXAMPLE_NAME`, and it is guarded: `kind` is a validated union today, which is
+ * the argument every instance `scripts/proto-index.ts` reports had before it stopped being true —
+ * a `Record` object literal answers an `Object.prototype` member for a key nobody declared, and
+ * this string is pasted into a shell. Two callers, one read.
+ */
+const exampleFor = (kind: Generator): string =>
+  `x g ${kind} ${Object.hasOwn(EXAMPLE_NAME, kind) ? EXAMPLE_NAME[kind] : '<name>'}`;
+
+/**
+ * `resource:verb`, or nothing is written. `--permission` reaches the generated page in three
+ * places — the `permissions:` array, a `definePermissions()` call and a `PermissionRegistry`
+ * augmentation — and `@ultimat3/policy`'s `Permission` type is `${string}:${string}`, so
+ * `x g admin:page ops --permission ops` used to emit a page that does not compile. A quote or a
+ * space is refused for the same reason one step earlier: the value is spliced into a string
+ * literal in emitted source, and neither is a permission any app declares.
+ *
+ * It cannot ask whether the app DECLARES the permission — `x g` writes files against a root, it
+ * never loads the app, and an app that will not import is exactly when a generator is reached for.
+ * The generated page declaring it is what closes that half (`templates/admin-page.ts`).
+ */
+const PERMISSION_SHAPE = /^[a-z0-9][a-z0-9_.-]*:[a-z0-9*][a-z0-9_.*-]*$/i;
+
+export function readPermission(raw: string | undefined, kind: Generator): string | undefined {
+  if (raw === undefined || PERMISSION_SHAPE.test(raw)) return raw;
+  throw new BadFlagError({
+    flag: 'permission',
+    command: 'g',
+    reason: `expects a permission of the form <resource>:<verb>, got "${raw}"`,
+    fix: `${exampleFor(kind)} --permission ops:read`,
   });
 }
 

package/src/generate-write.ts

@@ -27,11 +27,34 @@ function parseJsonObject(text: string): Record<string, unknown> | undefined {
     : undefined;
 }
 
+/**
+ * Every key of every level, sorted. A catalog is authored NESTED (`{ nav: { home: … } }`) and this
+ * sorted the top level only, so the keys INSIDE `app` kept the order their generators ran in —
+ * `x g route zebra` then `x g route alpha` wrote different bytes from the same two runs in the
+ * other order, which is the reordering diff the sort exists to prevent. Arrays keep their order:
+ * a list's order is its content.
+ *
+ * CODE UNIT, never `localeCompare`: it is `Intl`-backed, so the bytes a catalog is written with
+ * moved with the machine's locale and its ICU version — `x g route` on a `tr-TR` box and the same
+ * command in CI produced two orderings of one file, which is exactly the reordering diff this sort
+ * exists to prevent, one layer down. `@ultimat3/render` states the same rule as `byCodeUnit`; the
+ * comparison is inlined rather than imported because that one is package-internal and this is the
+ * whole of it.
+ */
+function sortDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortDeep);
+  if (typeof value !== 'object' || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([key, entry]) => [key, sortDeep(entry)]),
+  );
+}
+
 /** Deterministic catalog bytes: sorted keys, 2-space indent, trailing newline — a diff shows only
  * the keys a run actually changed, never a reordering. */
 function prettyJson(value: Record<string, unknown>): string {
-  const sorted = Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
-  return `${JSON.stringify(sorted, null, 2)}\n`;
+  return `${JSON.stringify(sortDeep(value), null, 2)}\n`;
 }
 
 /**

package/src/gitignore.ts

@@ -0,0 +1,145 @@
+// What git ignores, as data. The one reader of a `.gitignore` in this package: `dev-watch.ts` asks
+// it which directories `x dev` must not watch, and `fix-path.ts` asks it which citations name a
+// file this repository never commits. A second reader would be a second answer, and the two would
+// disagree on the first pattern neither author anticipated.
+
+// why: Bun exposes no synchronous file read and no synchronous existence primitive —
+// `Bun.file(p).text()` is async, and the ignore set is rebuilt inside an `fs.watch` callback where
+// an await opens a window for the next event. Delete when Bun ships sync equivalents.
+import { existsSync, readFileSync } from 'node:fs';
+// why: Bun exposes no path-join, dirname or relative primitive. The same necessity `fix-path.ts`
+// already records for `join`.
+import { dirname, join, relative, sep } from 'node:path';
+
+/** One line of a `.gitignore`, read for what it states rather than for what a reader assumes. */
+export interface IgnorePattern {
+  /** The glob, without its leading `/` or trailing `/`. */
+  readonly glob: string;
+  /** Held against the whole path relative to the file's own directory, never the basename. */
+  readonly anchored: boolean;
+  /** A trailing `/`: it matches a directory and never a file of that name. */
+  readonly directoryOnly: boolean;
+  /** A leading `!`: it re-includes what an earlier pattern ignored, at the same level. */
+  readonly negated: boolean;
+}
+
+/** One `.gitignore` file and the directory every one of its patterns is relative to. */
+export interface IgnoreScope {
+  readonly base: string;
+  readonly patterns: readonly IgnorePattern[];
+}
+
+/**
+ * A pattern is ANCHORED when it holds a `/` anywhere but at its end — git's own rule, and the one
+ * a hand-rolled reader gets wrong in both directions: `coverage/` ignores a `coverage` directory at
+ * any depth, while `/coverage/` and a pattern holding an inner slash only ever match where they
+ * are written.
+ */
+export function parseGitignore(text: string): readonly IgnorePattern[] {
+  const patterns: IgnorePattern[] = [];
+  for (const raw of text.split('\n')) {
+    // Trailing whitespace carries no rule unless escaped; a leading `#` is a comment, and `\#` is
+    // a filename that starts with one.
+    const line = raw.replace(/\\?\s+$/, (match) => (match.startsWith('\\') ? match : ''));
+    if (line === '' || line.startsWith('#')) continue;
+    const negated = line.startsWith('!');
+    const body = (negated ? line.slice(1) : line).replace(/^\\(?=[#!])/, '');
+    if (body === '' || body === '/') continue;
+    const directoryOnly = body.endsWith('/');
+    const trimmed = directoryOnly ? body.slice(0, -1) : body;
+    const rooted = trimmed.startsWith('/');
+    const glob = rooted ? trimmed.slice(1) : trimmed;
+    if (glob === '') continue;
+    patterns.push({ glob, anchored: rooted || glob.includes('/'), directoryOnly, negated });
+  }
+  return patterns;
+}
+
+/** The patterns one directory's own `.gitignore` states, or none where it has no such file. */
+export function readIgnoreFile(directory: string): readonly IgnorePattern[] {
+  const file = join(directory, '.gitignore');
+  return existsSync(file) ? parseGitignore(readFileSync(file, 'utf8')) : [];
+}
+
+/**
+ * The `.gitignore` files that govern `root`: its own last, then every ancestor up to and including
+ * the directory holding `.git`. Outermost first, so a nearer file's pattern is read last and wins —
+ * `examples/dummy` carries no ignore file of its own and every rule about it lives in the
+ * repository root's, which is why reading one file made `touch tsconfig.tsbuildinfo` a full reload.
+ */
+export function ignoreScopes(root: string): readonly IgnoreScope[] {
+  const scopes: IgnoreScope[] = [];
+  let directory = root;
+  for (;;) {
+    const patterns = readIgnoreFile(directory);
+    if (patterns.length > 0) scopes.unshift({ base: directory, patterns });
+    if (existsSync(join(directory, '.git'))) break;
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  return scopes;
+}
+
+/** Compiled once per pattern: one `x dev` walk asks the same glob of every directory it meets. */
+const globs = new Map<string, Bun.Glob>();
+
+function globFor(pattern: string): Bun.Glob {
+  const known = globs.get(pattern);
+  if (known !== undefined) return known;
+  const glob = new Bun.Glob(pattern);
+  globs.set(pattern, glob);
+  return glob;
+}
+
+/** The path relative to `base`, POSIX-separated, or `undefined` when it is not under it. */
+function relativeUnder(base: string, path: string): string | undefined {
+  const rel = relative(base, path).split(sep).join('/');
+  return rel === '' || rel.startsWith('../') || rel === '..' ? undefined : rel;
+}
+
+function matches(pattern: IgnorePattern, path: string, isDirectory: boolean): boolean {
+  if (pattern.directoryOnly && !isDirectory) return false;
+  const subject = pattern.anchored ? path : (path.split('/').at(-1) ?? path);
+  return globFor(pattern.glob).match(subject);
+}
+
+/** Last match wins, across every scope in order — git's rule, and the reason `!` works at all. */
+function verdictFor(
+  scopes: readonly IgnoreScope[],
+  path: string,
+  isDirectory: boolean,
+): boolean | undefined {
+  let verdict: boolean | undefined;
+  for (const scope of scopes) {
+    const rel = relativeUnder(scope.base, path);
+    if (rel === undefined) continue;
+    for (const pattern of scope.patterns) {
+      if (matches(pattern, rel, isDirectory)) verdict = !pattern.negated;
+    }
+  }
+  return verdict;
+}
+
+/**
+ * Whether git would ignore this absolute path. Every ancestor between the outermost scope and the
+ * path is judged as a DIRECTORY first: an ignored directory takes everything under it, which is how
+ * `coverage/` reaches `coverage/lcov.info` and the only reason a walk may prune at all.
+ */
+export function isGitIgnored(
+  scopes: readonly IgnoreScope[],
+  path: string,
+  isDirectory: boolean,
+): boolean {
+  const outermost = scopes[0];
+  if (outermost === undefined) return false;
+  const rel = relativeUnder(outermost.base, path);
+  if (rel === undefined) return false;
+  const segments = rel.split('/');
+  for (let depth = 0; depth < segments.length; depth += 1) {
+    const prefix = join(outermost.base, ...segments.slice(0, depth + 1));
+    const last = depth === segments.length - 1;
+    if (verdictFor(scopes, prefix, last ? isDirectory : true) === true) return true;
+  }
+  return false;
+}