@hominis/fireforge 0.11.2 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.13.0
+
+### Setup
+
+- **`fireforge bootstrap` now runs targeted post-bootstrap checks** instead of pattern-matching output text. When `mach bootstrap` exits successfully but sub-downloads fail (e.g. HTTP 403 from Apple's CDN), FireForge validates actual system state — checking whether a macOS SDK is available via Xcode — and reports actionable results using the same `✓`/`!`/`✗` severity rendering as `fireforge doctor`. Non-critical issues (SDK download failed but Xcode provides one) are reported as warnings rather than alarming "did not complete successfully" errors.
+
+### Lint fixes
+
+- **`file-too-large` now uses tiered severity thresholds.** The old single 650-line warning is replaced with a three-tier system (notice / warning / error) that distinguishes general files from test files. General files: 500–749 lines notice, 750–899 warning, 900+ error. Test files (paths containing `/test/`, or filenames matching `browser_*.js`, `test_*.js`, `xpcshell_*.js`): 1200–1399 notice, 1400–1599 warning, 1600+ error. Messages include the applicable thresholds so users know where they stand. The new `notice` severity is displayed but does not count toward warning or error totals and does not block export.
+- **`observer-topic-naming` no longer matches across newlines.** The regex that extracts topic strings from `notifyObservers`/`addObserver`/`removeObserver` calls now anchors to a single line, preventing false positives when the call spans multiple lines and an unrelated string literal appears later.
+- **`raw-color-value` now supports a file allowlist and inline suppression.** New `patchLint.rawColorAllowlist` config array in `fireforge.json` exempts file paths (exact or basename match) from the raw-color check — intended for design token files that must contain raw color values. Individual declarations can also be suppressed with an inline `/* fireforge-ignore: raw-color-value */` comment.
+- **`large-patch-lines` now uses tiered severity thresholds.** The old single >300-line warning is replaced with a three-tier system matching the `file-too-large` pattern. General patches: 800+ lines notice, 1500+ warning, 3000+ error. Test-only patches (all files match test patterns): 1500+ notice, 3000+ warning, 6000+ error. The previous threshold was too restrictive relative to file LOC limits — creating a single new file at the `file-too-large` notice tier (500 LOC) already exceeded it. Messages now include the applicable soft and hard limits.
+
+### General Improvements
+
+- **Minor Refactor**
+
+## 0.12.0
+
+### JSDoc validation (breaking)
+
+- **JSDoc enforcement is now AST-based and severity `error`.** The previous heuristic (walk backwards from `export` to find `*/`) has been replaced with Acorn-based AST analysis. Exported functions must have a JSDoc block with `@param` for each parameter (names must match) and `@returns` when returning a value. Exported classes require a JSDoc block. Exported constants require `@type`. This is a breaking change: projects that previously passed with incomplete JSDoc will now see lint errors.
+- **Patch-owned scope.** JSDoc enforcement now applies to all patch-owned `.sys.mjs` files, not just files new in the current diff. A file is patch-owned if it was created by the current diff or by any existing patch in the queue.
+- New check: **`jsdoc-param-mismatch`** (error) — flags `@param` tags that are missing or have the wrong name.
+- New check: **`jsdoc-missing-returns`** (error) — flags functions that return a value but lack `@returns`.
+- Exported constants and classes require a JSDoc block but do not require specific tags like `@type`.
+
+### Optional checkJs pass
+
+- **`patchLint.checkJs`** — new opt-in config field in `fireforge.json`. When enabled, runs TypeScript's `checkJs` pass (`allowJs + checkJs + noEmit`) on patch-owned `.sys.mjs` files only. Firefox globals are shimmed automatically. Diagnostics are filtered to patch-owned files so upstream noise is suppressed.
+- New check: **`checkjs-type-error`** (error/warning) — surfaces type errors from the TypeScript compiler.
+
+### Hardening
+
+- **Path validation.** `binaryName` in `fireforge.json` now rejects null bytes and absolute paths (including Windows drive letters). `isContainedRelativePath` and `isPathInsideRoot` reject null bytes. Furnace custom component `targetPath` rejects null bytes and absolute paths.
+- **Symlink traversal protection.** Patch target validation now checks whether existing paths are symlinks resolving outside the engine tree before applying.
+- **PID-aware stale lock recovery.** The file lock writes the owning PID into the lock directory. Stale lock recovery checks whether the PID is still alive before removing, preventing premature removal when a slow operation legitimately holds the lock.
+- **Forward-import detection** now catches `ChromeUtils.importESModule()` calls in addition to static/dynamic ES imports and `defineESModuleGetters`.
+- **Furnace rollback failure markers** now include the component name and operation context, improving diagnostics in `fireforge doctor`.
+- New lint check in README: **`modified-file-missing-header`** (warning) was implemented but not documented; now listed in the lint checks table.
+
 ## 0.11.0
 
 ### New commands

package/README.md

@@ -8,7 +8,7 @@
 
 **Build and maintain your own Firefox-based browser with a patch-first workflow**
 
-FireForge gives you a toolkit for forking Firefox: download a specific ESR release, manage your customisations as a series of patches, survive version upgrades with semi-automated rebase, wire custom code into Mozilla's startup paths, and build the result. It also ships **Furnace**, a component system for creating and overriding Firefox custom elements under `toolkit/content/widgets`.
+FireForge gives you a toolkit for forking Firefox: download a specific ESR release, manage your customisations as a series of patches, survive version upgrades with semi-automated rebase, wire custom code into Mozilla's startup paths and build the result. It also ships **Furnace**, a component system for creating and overriding Firefox custom elements under `toolkit/content/widgets`.
 
 Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon](https://github.com/dothq/melon).
 
@@ -18,7 +18,7 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 
 - **Semi-automated ESR rebase** `fireforge rebase` replays your patch stack onto new Firefox source with escalating fuzz matching. When a patch fails, you fix it manually and `--continue`. The full stack gets re-exported with updated version stamps.
 
-- **Wiring and registration** `fireforge wire` and `fireforge register` inject your code into Mozilla's startup paths, build manifests, and JAR files with a single command. The injection is AST-based (via Acorn), so it survives formatting changes applied between versions.
+- **Wiring and registration** `fireforge wire` and `fireforge register` inject your code into Mozilla's startup paths, build manifests and JAR files with a single command. The injection is AST-based (via Acorn), so it survives formatting changes applied between versions.
 
 - **Furnace component system** Override existing Firefox custom elements or create new ones under `toolkit/content/widgets` (CSS-only restyles, full behavioural forks, or entirely new widgets).
 
@@ -26,7 +26,7 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 
 - **Quality checks** `fireforge lint` catches fork-specific issues (raw colours, missing licence headers, relative imports, large patches, cross-patch ordering problems) before you export. `fireforge verify` runs a read-only integrity check over the whole patch queue. `fireforge doctor` diagnoses project health including Furnace component validation.
 
-- **Built and validated against real Firefox code** Developed by editing a real Firefox ESR codebase, learning from existing patch tools, observing the breakages and edge cases that surfaced, and turning those findings into a realistic test suite. In-repo tests are thus grounded in actual development scenarios. Yes, we mock quite a bit, but when building a tool that modifies a separate code base, I think it's a solid compromise for the time being. Full end-to-end runs are currently run locally, as they require about 30 GB of disk and significant compute for multiple full builds. Full end-to-end via Github Actions will be added soonishlyTM.
+- **Built and validated against real Firefox code** Developed by editing a real Firefox ESR codebase, learning from existing patch tools, observing the breakages and edge cases that surfaced and turning those findings into a realistic test suite. In-repo tests are thus grounded in actual development scenarios. Yes, we mock quite a bit, but when building a tool that modifies a separate code base, I think it's a solid compromise for the time being. Full end-to-end runs are currently run locally, as they require about 30 GB of disk and significant compute for multiple full builds. Full end-to-end via Github Actions will be added soonishlyTM.
 
 ## Quick Start
 
@@ -52,7 +52,7 @@ npx fireforge build               # build the browser
 npx fireforge run                 # launch it
 ```
 
-Your project now has `fireforge.json`, an `engine/` directory with Firefox source, and a `patches/` directory with an empty `patches.json` manifest ready for your first customisation.
+Your project now has `fireforge.json`, an `engine/` directory with Firefox source and a `patches/` directory with an empty `patches.json` manifest ready for your first customisation.
 
 ### Workflow Overview
 
@@ -71,14 +71,14 @@ npx fireforge export browser/base/content/browser.js \
 npx fireforge reset --yes
 npx fireforge import              # --dry-run to preview without applying
 
-# 5. When Firefox releases a new ESR, update fireforge.json, re-download, and rebase
+# 5. When Firefox releases a new ESR, update fireforge.json, re-download and rebase
 npx fireforge download --force
 npx fireforge rebase
 ```
 
 ## Patch Workflow
 
-Patches live in `patches/`, applied by numeric filename prefix, and tracked in `patches/patches.json`:
+Patches live in `patches/`, applied by numeric filename prefix and tracked in `patches/patches.json`:
 
 ```
 patches/
@@ -186,22 +186,30 @@ If the manifest drifts after an interrupted export or manual edits, `fireforge i
 <details>
 <summary>Patch lint checks</summary>
 
-`fireforge lint` runs automatically during export, export-all, and re-export. Use `--skip-lint` to downgrade errors to warnings. Errors block the export; warnings are printed but do not block.
-
-| Check                          | Scope                                 | Severity |
-| ------------------------------ | ------------------------------------- | -------- |
-| `missing-license-header`       | New files (JS/CSS/FTL)                | error    |
-| `relative-import`              | JS/MJS files                          | error    |
-| `token-prefix-violation`       | CSS files (with furnace)              | error    |
-| `raw-color-value`              | Introduced CSS color values           | error    |
-| `duplicate-new-file-creation`  | Same path created by multiple patches | error    |
-| `forward-import`               | Patch imports from a later-patch file | error    |
-| `missing-modification-comment` | Modified upstream JS/MJS              | warning  |
-| `file-too-large`               | New files >650 lines                  | warning  |
-| `missing-jsdoc`                | Exports in new `.sys.mjs`             | warning  |
-| `observer-topic-naming`        | Observer topics with binaryName       | warning  |
-| `large-patch-files`            | Patches affecting >5 files            | warning  |
-| `large-patch-lines`            | Patches >300 lines                    | warning  |
+`fireforge lint` runs automatically during export, export-all and re-export. Use `--skip-lint` to downgrade errors to warnings. Errors block the export; warnings are printed but do not block.
+
+| Check                          | Scope                                                                 | Severity                 |
+| ------------------------------ | --------------------------------------------------------------------- | ------------------------ |
+| `missing-license-header`       | New files (JS/CSS/FTL)                                                | error                    |
+| `relative-import`              | JS/MJS files                                                          | error                    |
+| `token-prefix-violation`       | CSS files (with furnace)                                              | error                    |
+| `raw-color-value`              | Introduced CSS color values                                           | error                    |
+| `duplicate-new-file-creation`  | Same path created by multiple patches                                 | error                    |
+| `forward-import`               | Patch imports from a later-patch file                                 | error                    |
+| `missing-jsdoc`                | Exports in patch-owned `.sys.mjs`                                     | error                    |
+| `jsdoc-param-mismatch`         | Exports in patch-owned `.sys.mjs`                                     | error                    |
+| `jsdoc-missing-returns`        | Exports in patch-owned `.sys.mjs`                                     | error                    |
+| `checkjs-type-error`           | Patch-owned `.sys.mjs` (opt-in)                                       | error                    |
+| `missing-modification-comment` | Modified upstream JS/MJS                                              | warning                  |
+| `modified-file-missing-header` | Modified upstream files (JS/CSS/FTL)                                  | warning                  |
+| `file-too-large`               | New files (tiered: 500/750/900 general, 1200/1400/1600 test)          | notice / warning / error |
+| `observer-topic-naming`        | Observer topics with binaryName                                       | warning                  |
+| `large-patch-files`            | Patches affecting >5 files                                            | warning                  |
+| `large-patch-lines`            | Patch line count (tiered: 800/1500/3000 general, 1500/3000/6000 test) | notice / warning / error |
+
+**JSDoc validation** uses AST-based analysis (Acorn) to validate exported APIs in patch-owned `.sys.mjs` files. A file is "patch-owned" if it was newly created by the current diff or by an existing patch in the queue. Functions must document every `@param` (names must match) and include `@returns` when the function returns a value. Exported constants and classes require a JSDoc block.
+
+**Optional `checkJs` pass.** Enable a TypeScript-esque bastardization of type checking for patch-owned `.sys.mjs` files by adding `"patchLint": { "checkJs": true }` to `fireforge.json`. This uses the TypeScript compiler API with `allowJs + checkJs + noEmit`, scoped only to patch-owned files. Firefox globals (`Services`, `ChromeUtils`, `lazy`, etc.) are shimmed automatically. Module-resolution errors from Firefox's `resource://` and `chrome://` URL schemes are suppressed since TypeScript cannot follow these. This pass solely focuses on type errors within the patch-owned code itself (mismatched JSDoc types, wrong argument counts, unreachable code, etc.).
 
 The two cross-patch rules (`duplicate-new-file-creation` and `forward-import`) run over the whole patch queue rather than a single diff, catching ordering issues that only surface during `import`. Forward-import detection compares leaf filenames, so a false positive is theoretically possible when two patches create files with the same basename in different directories. Suppress with an inline `// fireforge-ignore: forward-import` comment on or above the import line. This is currently the only lint rule that supports inline suppression.
 
@@ -209,7 +217,7 @@ The two cross-patch rules (`duplicate-new-file-creation` and `forward-import`) r
 
 ### Repairing a broken patch queue
 
-When a patch queue drifts — overlapping new-file creations, forward imports, manifest desync — start with diagnosis:
+When a patch queue drifts, e.g. due to overlapping new-file creations, forward imports, manifest desync, etc. start with diagnosing the root cause:
 
 ```bash
 fireforge verify                    # fsck: manifest + cross-patch lint
@@ -229,7 +237,7 @@ Then fix with the appropriate primitive:
 | Manifest references a missing patch file       | `fireforge doctor --repair-patches-manifest`                          |
 | Unmanaged changes you want to discard          | `fireforge discard <file>` or `fireforge reset`                       |
 
-Every destructive command defaults to an interactive confirmation with a change summary. `--dry-run` previews without writing; `--yes` skips the prompt for CI; `--force-unsafe` bypasses structural refusals when you have context the linter cannot see. Do not hand-edit `patches.json` — it is owned by FireForge.
+Every destructive command defaults to an interactive confirmation with a change summary. `--dry-run` previews without writing; `--yes` skips the prompt for CI; `--force-unsafe` bypasses structural refusals when you have context the linter cannot see. Do not hand-edit `patches.json` as the file is owned by FireForge.
 
 ## Wiring Custom Code
 
@@ -270,7 +278,7 @@ fireforge register browser/modules/mybrowser/MyStore.sys.mjs
 
 ## Furnace (UI Component System)
 
-Furnace manages Firefox custom elements (`MozLitElement`) under `toolkit/content/widgets`. You can override existing components or create new ones. Changes feed into the same patch workflow as everything else — Furnace is not a separate persistence layer.
+Furnace manages Firefox custom elements (`MozLitElement`) under `toolkit/content/widgets`. You can override existing components or create new ones. Changes feed into the same patch workflow as everything else, Furnace is not a separate persistence layer.
 
 There are three component types:
 
@@ -289,7 +297,52 @@ fireforge furnace status                           # workspace vs engine drift
 fireforge furnace diff moz-button                  # unified diff against baseline
 ```
 
-`furnace deploy` validates components before applying — errors block, warnings are advisory. `fireforge build` and `fireforge test --build` run apply automatically. Use `fireforge doctor --repair-furnace` if the engine gets out of sync.
+`furnace deploy` validates components before applying. As always, errors block, warnings are advisory. `fireforge build` and `fireforge test --build` run apply automatically. Use `fireforge doctor --repair-furnace` if the engine gets out of sync.
+
+## Additional Commands
+
+The commands below cover project configuration, patch queue management, build packaging and development utilities. Run `fireforge <command> --help` for full option details.
+
+### Configuration
+
+```bash
+# Read a config value
+fireforge config firefox.version
+
+# Set a config value
+fireforge config firefox.version 145.0.0esr
+
+# Set a value at a non-standard path (requires --force)
+fireforge config customKey "value" --force
+```
+
+### Patch queue management
+
+```bash
+# Delete a patch from the queue
+fireforge patch delete 003-ui-sidebar-tweaks.patch
+
+# Reorder a patch to a new position
+fireforge patch reorder 003-ui-sidebar-tweaks.patch --to 1
+
+# Move a patch before or after another
+fireforge patch reorder 003-ui-sidebar.patch --before 001-branding-logo.patch
+```
+
+Both subcommands support `--dry-run` and `--yes`.
+
+### Additional workflow commands
+
+```bash
+# Package the built browser for distribution
+fireforge package
+
+# Watch for file changes and auto-rebuild
+fireforge watch
+
+# Add a CSS design token
+fireforge token --name "--my-color" --value "light-dark(#fff, #000)"
+```
 
 ## Configuration
 

package/dist/src/commands/bootstrap-checks.d.ts

@@ -0,0 +1,16 @@
+import type { DoctorCheck } from '../types/commands/index.js';
+/** Tags representing distinct issues detected in bootstrap output. */
+export type BootstrapIssue = 'sdk-fetch-403' | 'python-traceback' | 'missing-origin-remote';
+/**
+ * Scans bootstrap output for known failure patterns and returns structured
+ * issue tags. A Python traceback paired with an HTTP 403 is collapsed into
+ * a single `sdk-fetch-403` tag since the traceback is just the stack trace
+ * from the HTTP error.
+ */
+export declare function detectBootstrapIssues(output: string): BootstrapIssue[];
+/**
+ * Runs targeted post-bootstrap checks based on the detected issues.
+ * Returns doctor-compatible check results so the caller can render them
+ * with the standard `reportDoctorResults` display.
+ */
+export declare function runPostBootstrapChecks(issues: BootstrapIssue[]): Promise<DoctorCheck[]>;

package/dist/src/commands/bootstrap-checks.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { execFile } from 'node:child_process';
+import { failure, warning } from './doctor.js';
+/**
+ * Scans bootstrap output for known failure patterns and returns structured
+ * issue tags. A Python traceback paired with an HTTP 403 is collapsed into
+ * a single `sdk-fetch-403` tag since the traceback is just the stack trace
+ * from the HTTP error.
+ */
+export function detectBootstrapIssues(output) {
+    const normalized = output.replace(/\r\n/g, '\n');
+    const issues = [];
+    const hasTraceback = /traceback \(most recent call last\):/i.test(normalized);
+    const has403 = /\bhttp(?:\s+error)?\s*403\b/i.test(normalized) || /\b403\b.*forbidden/i.test(normalized);
+    if (has403) {
+        // The traceback is just the stack trace from the HTTP error — report once.
+        issues.push('sdk-fetch-403');
+    }
+    else if (hasTraceback) {
+        issues.push('python-traceback');
+    }
+    if (/no such remote ['"]origin['"]/i.test(normalized) ||
+        /remote ['"]origin['"] does not exist/i.test(normalized) ||
+        /missing git remote ['"]origin['"]/i.test(normalized)) {
+        issues.push('missing-origin-remote');
+    }
+    return issues;
+}
+/** Checks whether `xcrun --show-sdk-path` returns a valid macOS SDK path. */
+async function hasMacOsSdk() {
+    return new Promise((resolve) => {
+        execFile('xcrun', ['--show-sdk-path'], { timeout: 10_000 }, (err, stdout) => {
+            resolve(!err && stdout.trim().length > 0);
+        });
+    });
+}
+/**
+ * Runs targeted post-bootstrap checks based on the detected issues.
+ * Returns doctor-compatible check results so the caller can render them
+ * with the standard `reportDoctorResults` display.
+ */
+export async function runPostBootstrapChecks(issues) {
+    const checks = [];
+    for (const issue of issues) {
+        switch (issue) {
+            case 'sdk-fetch-403': {
+                const sdkAvailable = await hasMacOsSdk();
+                if (sdkAvailable) {
+                    checks.push(warning('macOS SDK download', "SDK download from Apple's CDN failed (HTTP 403), but a macOS SDK was found via Xcode. This is safe to ignore."));
+                }
+                else {
+                    checks.push(failure('macOS SDK', 'SDK download failed and no macOS SDK found on your system.', 'Install Xcode Command Line Tools with "xcode-select --install"'));
+                }
+                break;
+            }
+            case 'python-traceback':
+                checks.push(warning('Python traceback', 'Bootstrap emitted a Python traceback. This may indicate a non-critical issue.', 'Review the bootstrap output above for details.'));
+                break;
+            case 'missing-origin-remote':
+                checks.push(failure('Git remote', 'Bootstrap expected an "origin" git remote in the Firefox source checkout.', 'Run "git remote add origin <url>" in the engine directory.'));
+                break;
+        }
+    }
+    return checks;
+}
+//# sourceMappingURL=bootstrap-checks.js.map

package/dist/src/commands/bootstrap.js

@@ -4,7 +4,13 @@ import { bootstrapWithOutput } from '../core/mach.js';
 import { GeneralError } from '../errors/base.js';
 import { BootstrapError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
-import { error, info, intro, outro } from '../utils/logger.js';
+import { error, info, intro, outro, warn } from '../utils/logger.js';
+import { detectBootstrapIssues, runPostBootstrapChecks } from './bootstrap-checks.js';
+import { reportDoctorResults } from './doctor.js';
+/**
+ * Builds a human-readable failure message for hard failures (non-zero exit).
+ * Used only when mach bootstrap itself reports failure.
+ */
 function buildBootstrapFailureMessage(output) {
     const normalized = output.replace(/\r\n/g, '\n');
     const issues = [];
@@ -52,15 +58,27 @@ export async function bootstrapCommand(projectRoot) {
         throw new BootstrapError();
     }
     // mach bootstrap may exit 0 even when sub-downloads fail (e.g. HTTP 403).
-    // Scan output for known failure patterns and surface them prominently.
-    const softFailure = buildBootstrapFailureMessage(`${result.stdout}\n${result.stderr}`);
-    if (softFailure) {
+    // Instead of guessing from output text, detect what went wrong and run
+    // targeted checks to determine whether the issues are actually actionable.
+    const output = `${result.stdout}\n${result.stderr}`;
+    const issues = detectBootstrapIssues(output);
+    if (issues.length > 0) {
+        const checks = await runPostBootstrapChecks(issues);
+        const hasErrors = checks.some((c) => c.severity === 'error' || (!c.passed && !c.warning));
         info('');
-        error('Bootstrap completed with issues:');
-        info(softFailure);
-        info('Run "fireforge doctor" to verify your build environment. ' +
-            'These issues may cause build failures if not resolved.');
-        outro('Build dependencies installed with warnings');
+        if (hasErrors) {
+            warn('Bootstrap completed with issues:');
+        }
+        else {
+            warn('Bootstrap completed with warnings:');
+        }
+        reportDoctorResults(checks);
+        if (hasErrors) {
+            outro('Build dependencies installed with errors');
+        }
+        else {
+            outro('Build dependencies installed with warnings');
+        }
         return;
     }
     outro('Build dependencies installed successfully!');

package/dist/src/commands/doctor.d.ts

@@ -1,4 +1,5 @@
 import { Command } from 'commander';
+import { ExitCode } from '../errors/codes.js';
 import type { CommandContext } from '../types/cli.js';
 import type { DoctorCheck, DoctorOptions } from '../types/commands/index.js';
 import type { FireForgeConfig, FireForgeState, ProjectPaths } from '../types/config.js';
@@ -116,6 +117,13 @@ export declare function failure(name: string, message: string, fix?: string): Do
  * think through the consequences.
  */
 export declare const DOCTOR_CHECK_ORDER: readonly string[];
+/**
+ * Renders a list of doctor checks to the console and returns the
+ * appropriate exit code (success when no errors, general error otherwise).
+ * @param checks - The check results to display
+ * @returns The exit code reflecting the overall result
+ */
+export declare function reportDoctorResults(checks: DoctorCheck[]): ExitCode;
 /**
  * Result of the doctor command, carrying the exit code so the caller
  * (or test) can inspect it without relying on process.exitCode.

package/dist/src/commands/doctor.js

@@ -342,7 +342,13 @@ validateCheckDependencies(DOCTOR_CHECKS);
  * think through the consequences.
  */
 export const DOCTOR_CHECK_ORDER = DOCTOR_CHECKS.map((check) => check.name);
-function reportDoctorResults(checks) {
+/**
+ * Renders a list of doctor checks to the console and returns the
+ * appropriate exit code (success when no errors, general error otherwise).
+ * @param checks - The check results to display
+ * @returns The exit code reflecting the overall result
+ */
+export function reportDoctorResults(checks) {
     info('');
     let passedCount = 0;
     let warningCount = 0;

package/dist/src/commands/export-flow.js

@@ -11,7 +11,7 @@ import { join } from 'node:path';
 import { findAllPatchesForFilesWithDetails, planExport } from '../core/patch-export.js';
 import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../core/patch-lock.js';
-import { addPatchToManifest, loadPatchesManifest, renumberPatchesInManifest, savePatchesManifest, } from '../core/patch-manifest.js';
+import { addPatchToManifest, loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, savePatchesManifest, } from '../core/patch-manifest.js';
 import { extractNewFileContentFromDiff } from '../core/patch-transform.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
@@ -32,14 +32,6 @@ function buildFilenameForPlacement(category, name, order, width) {
     const padded = String(order).padStart(Math.max(3, width), '0');
     return `${padded}-${category}-${sanitizeExportName(name)}.patch`;
 }
-function resolvePatchByIdentifier(identifier, patches) {
-    if (/^\d+$/.test(identifier)) {
-        const order = parseInt(identifier, 10);
-        return patches.find((p) => p.order === order) ?? null;
-    }
-    const normalized = identifier.endsWith('.patch') ? identifier : `${identifier}.patch`;
-    return patches.find((p) => p.filename === normalized) ?? null;
-}
 function getSortedRenameEntries(renameMap) {
     return Array.from(renameMap.entries()).sort((a, b) => a[1].newOrder - b[1].newOrder);
 }
@@ -115,7 +107,7 @@ export async function resolvePlacementPlan(patchesDir, options, category, name)
         targetOrder = options.order;
     }
     else if (options.before !== undefined) {
-        const anchor = resolvePatchByIdentifier(options.before, existingPatches);
+        const anchor = resolvePatchIdentifier(options.before, existingPatches);
         if (!anchor) {
             throw new InvalidArgumentError(`--before anchor "${options.before}" not found.`, '--before');
         }
@@ -126,7 +118,7 @@ export async function resolvePlacementPlan(patchesDir, options, category, name)
         if (afterAnchorId === undefined) {
             throw new InvalidArgumentError('Placement flag resolver reached --after branch with no value set.', '--after');
         }
-        const anchor = resolvePatchByIdentifier(afterAnchorId, existingPatches);
+        const anchor = resolvePatchIdentifier(afterAnchorId, existingPatches);
         if (!anchor) {
             throw new InvalidArgumentError(`--after anchor "${afterAnchorId}" not found.`, '--after');
         }

package/dist/src/commands/export-shared.d.ts

@@ -10,8 +10,9 @@ import type { SpinnerHandle } from '../utils/logger.js';
  * @param diffContent - Raw unified diff string
  * @param config - Project configuration
  * @param skipLint - If true, downgrade errors to warnings
+ * @param patchQueueCtx - Optional cross-patch context for ownership resolution
  */
-export declare function runPatchLint(engineDir: string, filesAffected: string[], diffContent: string, config: FireForgeConfig, skipLint?: boolean): Promise<void>;
+export declare function runPatchLint(engineDir: string, filesAffected: string[], diffContent: string, config: FireForgeConfig, skipLint?: boolean, patchQueueCtx?: import('../core/patch-lint-cross.js').PatchQueueContext): Promise<void>;
 /**
  * Resolves patch metadata interactively or from flags, with shared validation.
  * @param options - Export command options

package/dist/src/commands/export-shared.js

@@ -17,13 +17,18 @@ import { isValidPatchCategory, PATCH_CATEGORIES, validatePatchName } from '../ut
  * @param diffContent - Raw unified diff string
  * @param config - Project configuration
  * @param skipLint - If true, downgrade errors to warnings
+ * @param patchQueueCtx - Optional cross-patch context for ownership resolution
  */
-export async function runPatchLint(engineDir, filesAffected, diffContent, config, skipLint) {
-    const issues = await lintExportedPatch(engineDir, filesAffected, diffContent, config);
+export async function runPatchLint(engineDir, filesAffected, diffContent, config, skipLint, patchQueueCtx) {
+    const issues = await lintExportedPatch(engineDir, filesAffected, diffContent, config, patchQueueCtx);
     if (issues.length === 0)
         return;
     const errors = issues.filter((i) => i.severity === 'error');
     const warnings = issues.filter((i) => i.severity === 'warning');
+    const notices = issues.filter((i) => i.severity === 'notice');
+    for (const issue of notices) {
+        info(`NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
+    }
     for (const issue of warnings) {
         warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
     }

package/dist/src/commands/furnace/create.js

@@ -315,7 +315,7 @@ async function performCreateMutations(args) {
             await restoreRollbackJournalOrThrow(journal, `Failed to create custom component "${args.componentName}"`);
         }
         catch (rollbackError) {
-            await recordFurnaceRollbackFailure(args.projectRoot, 'create-rollback', toError(rollbackError).message);
+            await recordFurnaceRollbackFailure(args.projectRoot, 'create-rollback', `component "${args.componentName}": ${toError(rollbackError).message}`);
             throw rollbackError;
         }
         throw error;

package/dist/src/commands/furnace/deploy.js

@@ -125,7 +125,7 @@ async function restoreNamedDeployRollback(rollbackJournal, name, projectRoot) {
     }
     catch (rollbackError) {
         if (projectRoot) {
-            await recordFurnaceRollbackFailure(projectRoot, 'deploy-rollback', toError(rollbackError).message);
+            await recordFurnaceRollbackFailure(projectRoot, 'deploy-rollback', `component "${name}": ${toError(rollbackError).message}`);
         }
         throw rollbackError;
     }

package/dist/src/commands/furnace/override.js

@@ -116,7 +116,7 @@ async function performOverrideMutations(args) {
                 await restoreRollbackJournalOrThrow(journal, `Failed to override component "${args.componentName}"`);
             }
             catch (rollbackError) {
-                await recordFurnaceRollbackFailure(args.projectRoot, 'override-rollback', toError(rollbackError).message);
+                await recordFurnaceRollbackFailure(args.projectRoot, 'override-rollback', `component "${args.componentName}": ${toError(rollbackError).message}`);
                 throw rollbackError;
             }
             throw error;

package/dist/src/commands/furnace/refresh.js

@@ -149,7 +149,7 @@ async function refreshSingleOverride(projectRoot, name, options = {}) {
                     await restoreRollbackJournalOrThrow(journal, `Failed to refresh override "${name}"`);
                 }
                 catch (rollbackError) {
-                    await recordFurnaceRollbackFailure(projectRoot, 'refresh-rollback', toError(rollbackError).message);
+                    await recordFurnaceRollbackFailure(projectRoot, 'refresh-rollback', `override "${name}": ${toError(rollbackError).message}`);
                     throw rollbackError;
                 }
             }

package/dist/src/commands/furnace/remove.js

@@ -343,7 +343,7 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
                 await restoreRollbackJournalOrThrow(journal, `Failed to remove component "${name}"`);
             }
             catch (rollbackError) {
-                await recordFurnaceRollbackFailure(projectRoot, 'remove-rollback', toError(rollbackError).message);
+                await recordFurnaceRollbackFailure(projectRoot, 'remove-rollback', `component "${name}": ${toError(rollbackError).message}`);
                 throw rollbackError;
             }
             throw error;

package/dist/src/commands/furnace/rename.js

@@ -185,7 +185,7 @@ async function performRenameMutations(args) {
                 await restoreRollbackJournalOrThrow(journal, `Failed to rename component "${oldName}" to "${newName}"`);
             }
             catch (rollbackError) {
-                await recordFurnaceRollbackFailure(projectRoot, 'rename-rollback', toError(rollbackError).message);
+                await recordFurnaceRollbackFailure(projectRoot, 'rename-rollback', `rename "${oldName}" → "${newName}": ${toError(rollbackError).message}`);
                 throw rollbackError;
             }
             throw error;

package/dist/src/commands/furnace/scan.js

@@ -67,7 +67,7 @@ async function promptAddComponents(components, tracked, projectRoot) {
                 await restoreRollbackJournalOrThrow(journal, 'Failed to update furnace.json during scan');
             }
             catch (rollbackError) {
-                await recordFurnaceRollbackFailure(projectRoot, 'scan-rollback', toError(rollbackError).message);
+                await recordFurnaceRollbackFailure(projectRoot, 'scan-rollback', `furnace.json update during scan: ${toError(rollbackError).message}`);
                 throw rollbackError;
             }
             throw error;

package/dist/src/commands/lint.js

@@ -85,14 +85,19 @@ export async function lintCommand(projectRoot, files) {
     }
     const config = await loadConfig(projectRoot);
     const filesAffected = extractAffectedFiles(diff);
+    // Build patch queue context once so it can be shared between the
+    // per-patch ownership resolver and the cross-patch rules.
+    let ctx;
+    if (await pathExists(paths.patches)) {
+        ctx = await buildPatchQueueContext(paths.patches);
+    }
     const issues = [
-        ...(await lintExportedPatch(paths.engine, filesAffected, diff, config)),
+        ...(await lintExportedPatch(paths.engine, filesAffected, diff, config, ctx)),
     ];
     // Cross-patch rules operate over the whole queue, so run them whenever a
     // patches directory exists — they surface duplicate /dev/null creations
     // and forward-import chains that the per-patch orchestrator cannot see.
-    if (await pathExists(paths.patches)) {
-        const ctx = await buildPatchQueueContext(paths.patches);
+    if (ctx) {
         issues.push(...lintPatchQueue(ctx));
     }
     if (issues.length === 0) {
@@ -102,6 +107,10 @@ export async function lintCommand(projectRoot, files) {
     }
     const errors = issues.filter((i) => i.severity === 'error');
     const warnings = issues.filter((i) => i.severity === 'warning');
+    const notices = issues.filter((i) => i.severity === 'notice');
+    for (const issue of notices) {
+        info(`NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
+    }
     for (const issue of warnings) {
         warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
     }

package/dist/src/commands/patch/delete.js

@@ -12,26 +12,12 @@ import { getProjectPaths } from '../../core/config.js';
 import { appendHistory, confirmDestructive } from '../../core/destructive.js';
 import { buildPatchQueueContext, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, isForwardImportableFile, } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
-import { loadPatchesManifest, removePatchFileAndManifest } from '../../core/patch-manifest.js';
+import { loadPatchesManifest, removePatchFileAndManifest, resolvePatchIdentifier, } from '../../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { pickDefined } from '../../utils/options.js';
-/**
- * Resolves `<name>` (ordinal number or filename) to a manifest entry.
- * Mirrors re-export's `resolvePatchIdentifier` so the two resolvers behave
- * consistently — future work can lift this into a shared helper once a
- * third consumer appears.
- */
-function resolvePatchIdentifier(identifier, patches) {
-    if (/^\d+$/.test(identifier)) {
-        const order = parseInt(identifier, 10);
-        return patches.find((p) => p.order === order) ?? null;
-    }
-    const normalized = identifier.endsWith('.patch') ? identifier : `${identifier}.patch`;
-    return patches.find((p) => p.filename === normalized) ?? null;
-}
 /**
  * Runs the `patch delete` command: removes a patch file and its manifest
  * row atomically, refusing when a later patch imports a leaf owned by the