@hominis/fireforge 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 0.14.0
+
+### Concurrency and atomicity
+
+- Patch body and manifest writes in `re-export`, `rebase --continue`, and the post-apply re-export loop in `rebase` are now atomic via `updatePatchAndMetadata`, so a concurrent `resolve` / `re-export` / `patch compact` / `patch reorder` cannot leave body and metadata disagreeing.
+- State writes in `import`, `resolve`, and `rebase` (abort, continue, patch loop) use transactional `updateState` so a concurrent command's unrelated keys are no longer clobbered.
+- `rebase` apply + session persist is guarded by a new `runInSignalCriticalSection` primitive in `src/core/signal-critical.ts`; SIGINT / SIGTERM between apply and persist (5 s ceiling) no longer leaves an applied patch marked pending, so `--continue` does not re-apply it.
+
+### Rebase
+
+- Per-patch re-export failures after apply are collected instead of silently dropped. The session stays on disk and `sourceEsrVersion` is not stamped until every re-export succeeds, so `--continue` can retry after the root cause is fixed.
+- `rebase --continue` retries the post-apply pipeline when the apply loop has already finished; the prior "session may be corrupt" rejection no longer blocks resumption.
+- `rebase --abort` splits into four sequenced steps (git reset, furnace state clear, `pendingResolution` clear, session clear) so failures get correctly-labelled errors and the session stays on disk for retry.
+
+### Download
+
+- `download` restores patch-touched files to baseline after the initial commit (or a resumed partial init), so extraction artefacts and line-ending normalisation no longer force `fireforge import --force` on a clean install. Pre-existing uncommitted edits are preserved and warned about.
+- `cleanPatchTouchedFiles` runs before stamping `state.downloadedVersion`, preserving the invariant that the stamped version matches a clean engine.
+- Resume preserves the original error cause (timeout, permission denied, corrupted git object, disk full) instead of discarding it behind a generic `PartialEngineExistsError`. Unexpected errors during the partial-engine probe are also wrapped rather than re-thrown bare.
+
+### Import
+
+- Classification no longer swallows structural errors as "unmanaged dirty file". Only pure-IO errors (`ENOENT`, `EACCES`, `EPERM`, `EISDIR`, `EBUSY`) fall through; `PatchError`, manifest corruption, and patch-parse failures re-throw with the original diagnostic.
+- Patch integrity issues prompt in interactive mode and error in non-interactive mode instead of warn-and-continue; `--force` still bypasses with an explicit warning.
+
+### Furnace
+
+- `furnace apply --watch` picks up newly-created component directories dynamically, remembers edits that arrive during an in-flight apply (a second cycle runs automatically), and classifies errors errno-aware (`EACCES`, `ENOSPC`, `EBUSY`, `ENOENT`, `ETIMEDOUT`) instead of collapsing into a generic "Apply failed".
+- `furnace override` rejects collisions with `config.stock` and `config.custom` in both single and batch paths, and wraps snapshot + copy pairs in per-file error context so a mid-copy failure names the failing file.
+- `furnace remove` requires a git engine for custom components (not just overrides) and hoists the precondition outside the lock and journal registration. A summary line surfaces when test-file cleanup fails partway.
+- `furnace rename` does prefix-only filename replacement; the prior substring replacement mangled names when `oldName` appeared more than once. Content regexes now escape every metacharacter.
+- `furnace deploy` asserts `applied[0].name` matches the requested component before persisting state; state-mismatch errors recommend `fireforge doctor --repair-furnace`.
+- `furnace validate --fix` reports the actual delta from re-validation instead of inflating the count on no-op fixes.
+- `furnace list -v` tolerates missing or unreadable component directories, rendering `unavailable` instead of terminating the listing.
+- `furnace diff` surfaces `--reset-base` recovery in the primary error rather than a secondary catch block.
+- `furnace init --ftl-base-path` traversal check uses path normalisation instead of substring match, rejecting absolute paths, null bytes, and `..` segments. Interactive detection checks both `stdin.isTTY` and `stdout.isTTY` to match every other interactive command.
+
+### Other commands
+
+- `setup` rejects project names whose sanitised slug is empty (emoji-only, pure punctuation, `---`). `validateConfig` similarly rejects empty `name`, `vendor`, `appId`, `binaryName`.
+- `config --force` no longer bypasses structural validation for known keys in `SUPPORTED_CONFIG_PATHS`; the flag is only an escape hatch for unknown keys.
+- `watch` probes `watchman --version` with a 5 s timeout before starting, and runs the furnace staleness check previously only in `run`. Both commands share a new `warnIfFurnaceStale` helper in `src/core/furnace-staleness.ts`.
+- `test` path normalisation is case-insensitive, accepts `\` as well as `/`, and trims whitespace, so `Engine/foo/bar` on macOS / Windows no longer reaches `mach` with the prefix intact.
+- `status` caps untracked-directory expansion at 5 000 files per directory (configurable via `FIREFORGE_MAX_UNTRACKED_FILES`) and renders a top-of-output banner when directories were truncated, so large outputs don't hide the warning in scrollback.
+- `export` empty-diff error distinguishes the `--skip-lint` case; `export-shared` always announces when `--skip-lint` is active.
+- `wire <name>` and `register --after <entry>` validate their inputs against strict regexes, rejecting path separators, parent-dir segments, control characters, and line terminators before any filesystem operation.
+- `token add --mode` uses Commander's `.choices()` so invalid modes fail with the built-in message and `--help` lists the valid options.
+- `run` whitelisted exit codes (0, 130 SIGINT, 143 SIGTERM) are documented inline; SIGKILL (137) and other abnormal signal codes surface as build errors.
+- `discard` wraps error causes via `toError` so thrown strings or numbers propagate as real Errors with stack traces.
+
+### Internal
+
+- New unit tests for `validateCheckDependencies` in `src/commands/doctor.ts` assert the forward-only dependency invariant so a regression cannot slip in when reordering checks.
+
 ## 0.13.0
 
 ### Setup
@@ -12,6 +66,17 @@
 - **`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.
+- **`large-patch-lines` now ignores binary content.** Patches whose diff contains GIT binary patch hunks (PNG, ICO, ICNS, BMP, etc.) no longer count base85-encoded data toward the line limit. This removes the need for `--skip-lint` on branding asset patches that are predominantly binary.
+- **`modified-file-missing-header` no longer false-positives on upstream files.** Modified upstream files (e.g. `BrowserGlue.sys.mjs`) that carry an MPL-2.0 header in `/* */` block-comment style were incorrectly flagged because the check only tried the comment style inferred from the file extension. The check now cascades through all comment styles and falls back to scanning leading lines for raw license identifier strings (MPL, Apache, MIT, GPL, SPDX).
+
+### New commands
+
+- **`fireforge patch compact`** — closes ordinal gaps in the patch queue in a single atomic operation. After deletes or splits, patch ordinals may have gaps (e.g. 1, 3, 7); `compact` renumbers them sequentially (1, 2, 3). Previously this required N sequential `patch reorder` calls. Supports `--dry-run` and `--yes`.
+
+### Register improvements
+
+- **`register` now supports `.xhtml` and `.css` files in `browser/base/content/`.** Previously only `.js` and `.mjs` files were accepted; XHTML and CSS files required manual `jar.mn` edits.
+- **`register` now gives actionable advice for unregistrable file types.** Attempting to register a `.ftl` locale file explains that FTL files are auto-discovered via `jar.mn` glob patterns. Attempting to register an individual test file explains that it should be added to the corresponding `browser.toml` and suggests the correct `register` invocation for the test directory manifest.
 
 ### General Improvements
 

package/README.md

@@ -233,6 +233,7 @@ Then fix with the appropriate primitive:
 | Two patches each creating the same file        | `fireforge patch delete <duplicate>` or `fireforge re-export --files` |
 | A patch imports from a module in a later patch | `fireforge patch reorder <later> --before <importer>`                 |
 | Wrong patch ordering                           | `fireforge patch reorder <patch> --to <N>`                            |
+| Ordinal gaps after deletes/splits              | `fireforge patch compact`                                             |
 | A patch claims files that belong elsewhere     | `fireforge re-export --files <subset> <patch>`                        |
 | Manifest references a missing patch file       | `fireforge doctor --repair-patches-manifest`                          |
 | Unmanaged changes you want to discard          | `fireforge discard <file>` or `fireforge reset`                       |
@@ -266,13 +267,13 @@ fireforge register browser/modules/mybrowser/MyStore.sys.mjs
 <details>
 <summary>Supported register patterns</summary>
 
-| File pattern                               | Manifest                              | Entry format                        |
-| ------------------------------------------ | ------------------------------------- | ----------------------------------- |
-| `browser/themes/shared/*.css`              | `browser/themes/shared/jar.inc.mn`    | `skin/classic/browser/{name}.css`   |
-| `browser/base/content/*.{js,mjs}`          | `browser/base/jar.mn`                 | `content/browser/{file}`            |
-| `browser/base/content/test/*/browser.toml` | `browser/base/moz.build`              | `"content/test/{dir}/browser.toml"` |
-| `browser/modules/mybrowser/*.sys.mjs`      | `browser/modules/mybrowser/moz.build` | `"{name}.sys.mjs"`                  |
-| `toolkit/content/widgets/*/*.{mjs,css}`    | `toolkit/content/jar.mn`              | `content/global/elements/{file}`    |
+| File pattern                                | Manifest                              | Entry format                        |
+| ------------------------------------------- | ------------------------------------- | ----------------------------------- |
+| `browser/themes/shared/*.css`               | `browser/themes/shared/jar.inc.mn`    | `skin/classic/browser/{name}.css`   |
+| `browser/base/content/*.{js,mjs,xhtml,css}` | `browser/base/jar.mn`                 | `content/browser/{file}`            |
+| `browser/base/content/test/*/browser.toml`  | `browser/base/moz.build`              | `"content/test/{dir}/browser.toml"` |
+| `browser/modules/mybrowser/*.sys.mjs`       | `browser/modules/mybrowser/moz.build` | `"{name}.sys.mjs"`                  |
+| `toolkit/content/widgets/*/*.{mjs,css}`     | `toolkit/content/jar.mn`              | `content/global/elements/{file}`    |
 
 </details>
 
@@ -327,9 +328,12 @@ 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
+
+# Close ordinal gaps after deletes or splits (e.g. 1, 3, 7 → 1, 2, 3)
+fireforge patch compact
 ```
 
-Both subcommands support `--dry-run` and `--yes`.
+All subcommands support `--dry-run` and `--yes`.
 
 ### Additional workflow commands
 

package/dist/bin/fireforge.js

@@ -10,7 +10,15 @@
  */
 import { installBrokenPipeHandler, main } from '../src/cli.js';
 import { isSignalRollbackInFlight, rollbackActiveOperationsForSignal, } from '../src/core/furnace-operation.js';
+import { waitForActiveCriticalSections } from '../src/core/signal-critical.js';
 import { CommandError } from '../src/errors/base.js';
+/**
+ * Upper bound (ms) the signal handler will wait for any in-flight critical
+ * section (e.g. rebase apply + session persist) to finish before calling
+ * process.exit. Keep short so a stuck I/O operation cannot indefinitely
+ * postpone the exit a user requested with Ctrl+C.
+ */
+const SIGNAL_CRITICAL_SECTION_TIMEOUT_MS = 5_000;
 installBrokenPipeHandler();
 process.on('unhandledRejection', (reason) => {
     console.error('Fatal error (unhandled rejection):', reason instanceof Error ? reason.message : reason);
@@ -33,11 +41,17 @@ function installFurnaceSignalHandler(signal, exitCode) {
             // rather than queueing another rollback that will race the first.
             process.exit(exitCode);
         }
-        rollbackActiveOperationsForSignal(signal)
-            .catch((error) => {
-            console.error(`Furnace rollback after ${signal} failed:`, error instanceof Error ? error.message : error);
-        })
-            .finally(() => {
+        // Run furnace rollback and signal-critical-section drain in parallel.
+        // Rebase-style operations register critical sections (apply + session
+        // persist) via `runInSignalCriticalSection`; awaiting them here ensures
+        // the CLI never exits with a patch applied to the engine but a stale
+        // session file that would mis-track progress on `--continue`.
+        void Promise.allSettled([
+            rollbackActiveOperationsForSignal(signal).catch((error) => {
+                console.error(`Furnace rollback after ${signal} failed:`, error instanceof Error ? error.message : error);
+            }),
+            waitForActiveCriticalSections(SIGNAL_CRITICAL_SECTION_TIMEOUT_MS),
+        ]).finally(() => {
             process.exit(exitCode);
         });
     });

package/dist/src/commands/config.js

@@ -105,8 +105,14 @@ export async function configCommand(projectRoot, key, value, options = {}) {
             throw new InvalidArgumentError(`Unknown config key: "${key}". Known keys: ${SUPPORTED_CONFIG_PATHS.join(', ')}. Use --force to set anyway.`);
         }
         const parsedValue = parseValue(value, key);
+        const keyIsKnown = SUPPORTED_CONFIG_PATHS.includes(key);
         try {
-            if (options.force) {
+            // `--force` is intended as an escape hatch for *unknown* keys; it
+            // should not also let the user write a structurally invalid value
+            // for a *known* key. Apply strict validation whenever the key is
+            // listed in SUPPORTED_CONFIG_PATHS, regardless of --force, and only
+            // skip validation for genuinely unknown key paths.
+            if (options.force && !keyIsKnown) {
                 const updatedConfig = mutateConfig(config, key, parsedValue, true);
                 await writeConfigDocument(projectRoot, updatedConfig);
             }

package/dist/src/commands/discard.js

@@ -7,6 +7,7 @@ import { discardStatusEntry } from '../core/git-file-ops.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { GitError } from '../errors/git.js';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, isCancel, outro, spinner, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
@@ -79,7 +80,11 @@ export async function discardCommand(projectRoot, file, options = {}) {
         }
         throw new GitError(`Failed to discard ${file}`, statusEntry.isUntracked
             ? `rm ${statusEntry.file}`
-            : `restore --source HEAD --staged --worktree -- ${statusEntry.file}`, error instanceof Error ? error : undefined);
+            : `restore --source HEAD --staged --worktree -- ${statusEntry.file}`, 
+        // Always attach the cause via toError so thrown primitives (strings,
+        // numbers) produced by poorly-behaved utilities still propagate as
+        // an Error, preserving stack traces for verbose-mode triage.
+        toError(error));
     }
 }
 /** Registers the discard command on the CLI program. */

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

@@ -109,6 +109,18 @@ export declare function warning(name: string, message: string, fix?: string): Do
  * Exported for sibling check modules — see {@link ok}.
  */
 export declare function failure(name: string, message: string, fix?: string): DoctorCheck;
+/**
+ * Validates that every check's `dependsOn` entries appear earlier in the
+ * registry. Called once at module load time so a broken reorder surfaces
+ * immediately as a thrown error rather than producing a subtle
+ * context-population bug at runtime.
+ *
+ * Exported so tests can exercise the forward-only invariant against
+ * fixtures — the real DOCTOR_CHECKS list is also validated at import
+ * time, but a targeted unit test makes the contract explicit and
+ * prevents regressions if the validator is ever relaxed.
+ */
+export declare function validateCheckDependencies(checks: readonly DoctorCheckDefinition[]): void;
 /**
  * Ordered list of the doctor check names, exported for tests. Pinning
  * the order here is intentional: any reorder that breaks the

package/dist/src/commands/doctor.js

@@ -135,8 +135,13 @@ async function runEngineGitChecks(ctx) {
  * registry. Called once at module load time so a broken reorder surfaces
  * immediately as a thrown error rather than producing a subtle
  * context-population bug at runtime.
+ *
+ * Exported so tests can exercise the forward-only invariant against
+ * fixtures — the real DOCTOR_CHECKS list is also validated at import
+ * time, but a targeted unit test makes the contract explicit and
+ * prevents regressions if the validator is ever relaxed.
  */
-function validateCheckDependencies(checks) {
+export function validateCheckDependencies(checks) {
     const seen = new Set();
     for (const check of checks) {
         if (check.dependsOn) {

package/dist/src/commands/download.js

@@ -4,10 +4,68 @@ import { getProjectPaths, loadConfig, updateState } from '../core/config.js';
 import { downloadFirefoxSource, formatBytes } from '../core/firefox.js';
 import { getFurnacePaths, updateFurnaceState } from '../core/furnace-config.js';
 import { getHead, initRepository, isGitRepository, isMissingHeadError, resumeRepository, } from '../core/git.js';
+import { restoreTrackedPath } from '../core/git-file-ops.js';
+import { getDirtyFiles } from '../core/git-status.js';
+import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { EngineExistsError, PartialEngineExistsError } from '../errors/download.js';
+import { toError } from '../utils/errors.js';
 import { checkDiskSpace, ensureDir, pathExists, removeDir } from '../utils/fs.js';
-import { info, intro, outro, spinner, step, warn } from '../utils/logger.js';
+import { info, intro, outro, spinner, step, verbose, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
+/**
+ * Collects the set of patch-touched files from the manifest.
+ * Returns an empty set when the patches directory or manifest is absent.
+ */
+async function getPatchTouchedFiles(patchesDir) {
+    if (!(await pathExists(patchesDir)))
+        return new Set();
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest || manifest.patches.length === 0)
+        return new Set();
+    const files = new Set();
+    for (const patch of manifest.patches) {
+        for (const file of patch.filesAffected) {
+            files.add(file);
+        }
+    }
+    return files;
+}
+/**
+ * Restores patch-touched files to their committed (HEAD) state so that a
+ * subsequent `fireforge import` does not see spurious uncommitted changes.
+ *
+ * Files that were already dirty *before* the download started (tracked via
+ * `preExistingDirty`) are left untouched and warned about.
+ */
+async function cleanPatchTouchedFiles(engineDir, patchesDir, preExistingDirty) {
+    const patchFiles = await getPatchTouchedFiles(patchesDir);
+    if (patchFiles.size === 0)
+        return;
+    const dirtyFiles = await getDirtyFiles(engineDir, [...patchFiles]);
+    if (dirtyFiles.length === 0)
+        return;
+    const toClean = preExistingDirty
+        ? dirtyFiles.filter((f) => !preExistingDirty.has(f))
+        : dirtyFiles;
+    const preserved = preExistingDirty ? dirtyFiles.filter((f) => preExistingDirty.has(f)) : [];
+    for (const file of toClean) {
+        try {
+            await restoreTrackedPath(engineDir, file);
+        }
+        catch {
+            warn(`Could not restore patch-touched file: ${file}`);
+        }
+    }
+    if (toClean.length > 0) {
+        info(`Restored ${toClean.length} patch-touched file(s) to baseline state.`);
+    }
+    if (preserved.length > 0) {
+        warn(`${preserved.length} patch-touched file(s) had pre-existing changes and were left as-is:`);
+        for (const file of preserved) {
+            warn(`  ${file}`);
+        }
+    }
+}
 /**
  * Runs the download command.
  * @param projectRoot - Root directory of the project
@@ -33,6 +91,12 @@ export async function downloadCommand(projectRoot, options) {
                     if (isMissingHeadError(error)) {
                         // Partial init detected — attempt to resume instead of requiring --force
                         info('Detected partially initialized engine. Attempting to resume...');
+                        // Snapshot patch-touched files that are already dirty so we
+                        // can preserve them after the resume commit.
+                        const patchFiles = await getPatchTouchedFiles(paths.patches);
+                        const preExistingDirty = patchFiles.size > 0
+                            ? new Set(await getDirtyFiles(paths.engine, [...patchFiles]))
+                            : new Set();
                         const resumeSpinner = spinner('Resuming git repository initialization...');
                         try {
                             await resumeRepository(paths.engine, {
@@ -45,6 +109,14 @@ export async function downloadCommand(projectRoot, options) {
                             });
                             const baseCommit = await getHead(paths.engine);
                             resumeSpinner.stop('Git repository resumed successfully');
+                            // Restore patch-touched files BEFORE stamping state. If this
+                            // step fails (disk full, permission denied, git object issue),
+                            // state.json keeps the previous downloadedVersion so the
+                            // invariant "state.downloadedVersion matches a clean engine"
+                            // holds. A retry of `fireforge download` then re-enters the
+                            // resume path instead of declaring success against a dirty
+                            // engine.
+                            await cleanPatchTouchedFiles(paths.engine, paths.patches, preExistingDirty);
                             await updateState(projectRoot, {
                                 downloadedVersion: version,
                                 baseCommit,
@@ -53,14 +125,31 @@ export async function downloadCommand(projectRoot, options) {
                             return;
                         }
                         catch (error) {
-                            void error;
                             resumeSpinner.error('Resume failed');
-                            throw new PartialEngineExistsError(paths.engine);
+                            // Preserve the underlying cause so the user sees *why* the
+                            // resume failed (timeout, permission denied, corrupted object,
+                            // disk full, …) instead of only the generic "partial engine
+                            // exists" story. Verbose mode prints the stack for deeper
+                            // triage.
+                            const cause = toError(error);
+                            verbose(`Resume failure detail: ${cause.message}`);
+                            if (cause.stack) {
+                                verbose(cause.stack);
+                            }
+                            throw new PartialEngineExistsError(paths.engine, cause);
                         }
                     }
-                    // Re-throw unexpected git errors (e.g. corrupted objects) rather
-                    // than masking them behind the generic EngineExistsError below.
-                    throw error;
+                    // Re-throw unexpected git errors (corrupted objects, permission
+                    // denied, …) wrapped in PartialEngineExistsError so the user sees
+                    // both narratives: "we detected a partial engine and attempted
+                    // resume" AND the underlying git failure. Without the wrap the
+                    // raw git error loses the context that resume was in flight.
+                    const cause = toError(error);
+                    verbose(`Partial-engine probe failed with unexpected error: ${cause.message}`);
+                    if (cause.stack) {
+                        verbose(cause.stack);
+                    }
+                    throw new PartialEngineExistsError(paths.engine, cause);
                 }
             }
             throw new EngineExistsError(paths.engine);
@@ -122,7 +211,17 @@ export async function downloadCommand(projectRoot, options) {
         warn('engine/ may now contain a partially initialized git repository. Re-run "fireforge download --force" to recreate the baseline cleanly.');
         throw error;
     }
-    // Update state
+    // Restore any patch-touched files that ended up dirty after the initial
+    // commit (e.g. line-ending normalisation or extraction artefacts) so that
+    // a subsequent `fireforge import` works without --force.
+    //
+    // This runs BEFORE updateState so a restore failure keeps the previous
+    // downloadedVersion in state.json. The invariant we preserve is
+    // "state.downloadedVersion matches a clean engine": stamping the new
+    // version only after the restore succeeds means a failed clean-up will
+    // re-enter the resume path on the next `fireforge download` rather than
+    // reporting success against a dirty engine.
+    await cleanPatchTouchedFiles(paths.engine, paths.patches);
     await updateState(projectRoot, {
         downloadedVersion: version,
         baseCommit,

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

@@ -47,6 +47,13 @@ export async function runPatchLint(engineDir, filesAffected, diffContent, config
         }
         info(`Lint: ${errors.length} error(s) downgraded to warnings (--skip-lint)`);
     }
+    else if (skipLint) {
+        // Always announce that --skip-lint was honoured, even when there were
+        // no errors to downgrade, so the operator can confirm the flag took
+        // effect. Without this, a clean `--skip-lint` run emitted nothing
+        // about the flag and looked identical to an unflagged run.
+        info('Lint: 0 error(s); --skip-lint is active (no effect on this run).');
+    }
     const warnCount = warnings.length + (skipLint ? errors.length : 0);
     if (warnCount > 0) {
         info(`Patch lint: ${warnCount} warning(s)`);

package/dist/src/commands/export.js

@@ -139,6 +139,11 @@ export async function exportCommand(projectRoot, files, options) {
     }
     let diff = await generatePatchDiff(paths.engine, allFiles);
     if (!diff.trim()) {
+        if (options.skipLint) {
+            throw new GeneralError('The specified paths have no diff content to export. ' +
+                '(--skip-lint is set; lint checks were bypassed but there are still no content changes — ' +
+                'the paths may have only been lint-level differences that resolved, or the working tree is already clean.)');
+        }
         throw new GeneralError('The specified paths have no diff content to export.');
     }
     // Ensure patches directory exists