@hominis/fireforge 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 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

@@ -196,13 +196,21 @@ If the manifest drifts after an interrupted export or manual edits, `fireforge i
 | `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 >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  |
 
+**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 TypeScript-based 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 — the pass 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.
 
 </details>
@@ -291,6 +299,51 @@ fireforge furnace diff moz-button                  # unified diff against baseli
 
 `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.
 
+## 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
 
 `fireforge.json` at your project root:

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,9 +17,10 @@ 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');

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) {

package/dist/src/core/ast-utils.d.ts

@@ -1,3 +1,4 @@
+import * as acorn from 'acorn';
 import type * as estree from 'estree';
 import { walk } from 'estree-walker';
 /**
@@ -16,6 +17,15 @@ export type AcornESTreeNode<T extends estree.Node = estree.Node> = T & {
  * `customElements.js`, etc.) are scripts that run in a privileged scope.
  */
 export declare function parseScript(content: string): AcornESTreeNode<estree.Program>;
+/**
+ * Parse JavaScript source as an **ES module**.
+ * Used for `.sys.mjs` files which use static import/export syntax.
+ *
+ * @param content - Source text to parse
+ * @param onComment - Optional array that acorn fills with comment nodes
+ * @returns Parsed program AST with character-offset positions
+ */
+export declare function parseModule(content: string, onComment?: acorn.Comment[]): AcornESTreeNode<estree.Program>;
 /**
  * Convenience cast from `acorn.Node` (or the generic ESTree union returned
  * by estree-walker callbacks) to a positioned, narrowly-typed node.

package/dist/src/core/ast-utils.js

@@ -12,6 +12,24 @@ export function parseScript(content) {
         ecmaVersion: 'latest',
     });
 }
+/**
+ * Parse JavaScript source as an **ES module**.
+ * Used for `.sys.mjs` files which use static import/export syntax.
+ *
+ * @param content - Source text to parse
+ * @param onComment - Optional array that acorn fills with comment nodes
+ * @returns Parsed program AST with character-offset positions
+ */
+export function parseModule(content, onComment) {
+    const opts = {
+        sourceType: 'module',
+        ecmaVersion: 'latest',
+        locations: true,
+    };
+    if (onComment)
+        opts.onComment = onComment;
+    return acorn.parse(content, opts);
+}
 /**
  * Convenience cast from `acorn.Node` (or the generic ESTree union returned
  * by estree-walker callbacks) to a positioned, narrowly-typed node.

package/dist/src/core/config-paths.d.ts

@@ -17,9 +17,9 @@ export declare const CONFIGS_DIR = "configs";
 /** Name of the source directory */
 export declare const SRC_DIR = "src";
 /** Supported top-level fireforge.json keys backed by the current schema. */
-export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "license", "wire"];
+export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "license", "wire", "patchLint"];
 /** Supported config paths that can be read or set without --force. */
-export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "build", "build.jobs", "wire", "wire.subscriptDir"];
+export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "build", "build.jobs", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs"];
 /**
  * Gets all project paths based on a root directory.
  * @param root - Root directory of the project

package/dist/src/core/config-paths.js

@@ -27,6 +27,7 @@ export const SUPPORTED_CONFIG_ROOT_KEYS = [
     'build',
     'license',
     'wire',
+    'patchLint',
 ];
 /** Supported config paths that can be read or set without --force. */
 export const SUPPORTED_CONFIG_PATHS = [
@@ -42,6 +43,8 @@ export const SUPPORTED_CONFIG_PATHS = [
     'build.jobs',
     'wire',
     'wire.subscriptDir',
+    'patchLint',
+    'patchLint.checkJs',
 ];
 /**
  * Gets all project paths based on a root directory.

package/dist/src/core/config-validate.js

@@ -5,7 +5,7 @@
 import { ConfigError } from '../errors/config.js';
 import { verbose } from '../utils/logger.js';
 import { parseObject } from '../utils/parse.js';
-import { isContainedRelativePath } from '../utils/paths.js';
+import { isContainedRelativePath, isExplicitAbsolutePath } from '../utils/paths.js';
 import { isValidAppId, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, validateFirefoxProductVersionCompatibility, } from '../utils/validation.js';
 import { SUPPORTED_CONFIG_ROOT_KEYS } from './config-paths.js';
 /**
@@ -27,8 +27,14 @@ export function validateConfig(data) {
     const vendor = requireConfigString(rec, 'vendor');
     const appId = requireConfigString(rec, 'appId');
     const binaryName = requireConfigString(rec, 'binaryName');
-    if (binaryName.includes('..') || binaryName.includes('/') || binaryName.includes('\\')) {
-        throw new ConfigError('Config field "binaryName" must not contain path separators or ".."');
+    if (binaryName.includes('..') ||
+        binaryName.includes('/') ||
+        binaryName.includes('\\') ||
+        binaryName.includes('\0')) {
+        throw new ConfigError('Config field "binaryName" must not contain path separators, "..", or null bytes');
+    }
+    if (isExplicitAbsolutePath(binaryName)) {
+        throw new ConfigError('Config field "binaryName" must not be an absolute path');
     }
     if (!isValidAppId(appId)) {
         throw new ConfigError('Config field "appId" must be a valid reverse-domain identifier (e.g., "org.example.browser")');
@@ -101,6 +107,18 @@ export function validateConfig(data) {
         }
         config.license = licenseRaw;
     }
+    // PatchLint
+    const patchLintRec = optionalConfigObject(rec, 'patchLint');
+    if (patchLintRec) {
+        config.patchLint = {};
+        const checkJs = patchLintRec.raw('checkJs');
+        if (checkJs !== undefined) {
+            if (typeof checkJs !== 'boolean') {
+                throw new ConfigError('Config field "patchLint.checkJs" must be a boolean');
+            }
+            config.patchLint.checkJs = checkJs;
+        }
+    }
     // Warn on unknown root keys
     const knownRootKeys = new Set(SUPPORTED_CONFIG_ROOT_KEYS);
     for (const key of rec.keys()) {

package/dist/src/core/file-lock.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { mkdir, rm, stat } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { ensureDir } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
@@ -25,6 +25,20 @@ function getNodeErrorCode(error) {
 export function createSiblingLockPath(filePath, suffix = '.fireforge.lock') {
     return `${filePath}${suffix}`;
 }
+const LOCK_PID_FILE = 'pid';
+/**
+ * Checks whether a process with the given PID is still running.
+ * Uses `kill(pid, 0)` which sends no signal but checks existence.
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
     try {
         const lockStat = await stat(lockPath);
@@ -32,6 +46,21 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
         if (ageMs <= staleMs) {
             return false;
         }
+        // If the lock directory contains a PID file, check whether the owning
+        // process is still running before removing. This prevents premature
+        // removal when a slow operation (e.g. mach build) legitimately holds
+        // the lock past the stale threshold.
+        try {
+            const pidContent = await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8');
+            const pid = parseInt(pidContent.trim(), 10);
+            if (Number.isFinite(pid) && isProcessAlive(pid)) {
+                verbose(`Lock at ${lockPath} is ${Math.round(ageMs / 1000)}s old but PID ${pid} is still running — not removing`);
+                return false;
+            }
+        }
+        catch {
+            // No PID file or unreadable — fall through to stale removal
+        }
         const staleMessage = onStaleLockMessage?.(ageMs);
         if (staleMessage) {
             warn(staleMessage);
@@ -84,6 +113,14 @@ export async function withFileLock(lockPath, operation, options = {}) {
             await sleep(pollMs);
         }
     }
+    // Write PID into the lock directory so stale-lock recovery can check
+    // whether the owning process is still alive before removing.
+    try {
+        await writeFile(join(lockPath, LOCK_PID_FILE), String(process.pid), 'utf-8');
+    }
+    catch {
+        // Non-fatal: stale recovery falls back to age-only heuristic
+    }
     try {
         return await operation();
     }

package/dist/src/core/furnace-apply.js

@@ -349,7 +349,8 @@ export async function applyAllComponents(root, dryRun = false, options) {
                     // Rollback itself failed: the engine is in a partially restored
                     // state. Persist a pending-repair marker so the next `fireforge
                     // doctor --repair-furnace` run knows to reconcile.
-                    await recordFurnaceRollbackFailure(root, 'apply-rollback', toError(rollbackError).message);
+                    const failedComponents = result.errors.map((e) => e.name).join(', ');
+                    await recordFurnaceRollbackFailure(root, 'apply-rollback', `failed component(s): ${failedComponents || '(unknown)'}: ${toError(rollbackError).message}`);
                     throw rollbackError;
                 }
             }

package/dist/src/core/furnace-config.js

@@ -4,6 +4,7 @@ import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
+import { isExplicitAbsolutePath } from '../utils/paths.js';
 import { isArray, isBoolean, isObject, isString } from '../utils/validation.js';
 import { FIREFORGE_DIR } from './config.js';
 import { resolveFtlDir } from './furnace-constants.js';
@@ -99,8 +100,11 @@ function parseCustomConfig(data, name) {
     if (!isString(data['targetPath'])) {
         throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must be a string`);
     }
-    if (data['targetPath'].includes('..')) {
-        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must not contain ".." (path traversal)`);
+    if (data['targetPath'].includes('..') || data['targetPath'].includes('\0')) {
+        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must not contain ".." or null bytes (path traversal)`);
+    }
+    if (isExplicitAbsolutePath(data['targetPath'])) {
+        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must not be an absolute path`);
     }
     if (!isBoolean(data['register'])) {
         throw new FurnaceError(`Furnace config: custom "${name}.register" must be a boolean`);

package/dist/src/core/patch-apply.js

@@ -3,7 +3,8 @@
  * Patch orchestration — coordinates patch discovery, application, and validation.
  * Pure parsing, content transformation, and lock management are in separate modules.
  */
-import { join } from 'node:path';
+import { lstat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
 import { PatchError } from '../errors/patch.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
@@ -34,7 +35,7 @@ async function applySinglePatch(patch, engineDir) {
     try {
         patchContent = await readText(patch.path);
         affectedFiles = extractAffectedFiles(patchContent);
-        validatePatchTargets(patch, affectedFiles);
+        await validatePatchTargets(patch, affectedFiles, engineDir);
         await applyPatchIdempotent(patch.path, engineDir);
         return { patch, success: true };
     }
@@ -143,7 +144,7 @@ export async function validatePatches(patchesDir, engineDir) {
     for (const patch of patches) {
         try {
             const patchContent = await readText(patch.path);
-            validatePatchTargets(patch, extractAffectedFiles(patchContent));
+            await validatePatchTargets(patch, extractAffectedFiles(patchContent), engineDir);
         }
         catch (error) {
             errors.push(`${patch.filename}: ${toError(error).message}`);
@@ -157,11 +158,32 @@ export async function validatePatches(patchesDir, engineDir) {
     }
     return { valid: errors.length === 0, errors };
 }
-function validatePatchTargets(patch, affectedFiles) {
+async function validatePatchTargets(patch, affectedFiles, engineDir) {
     for (const file of affectedFiles) {
         if (!isContainedRelativePath(file)) {
             throw new PatchError(`Patch targets a path outside engine/: ${file}`, patch.filename);
         }
+        // When the engine directory is known, verify that existing target paths
+        // are not symlinks pointing outside the engine tree. A crafted patch
+        // could otherwise write through a symlink to an arbitrary location.
+        if (engineDir) {
+            const targetPath = join(engineDir, file);
+            try {
+                const stats = await lstat(targetPath);
+                if (stats.isSymbolicLink()) {
+                    const realPath = resolve(engineDir, file);
+                    const resolvedEngine = resolve(engineDir);
+                    if (!realPath.startsWith(resolvedEngine + '/') && realPath !== resolvedEngine) {
+                        throw new PatchError(`Patch targets a symlink that resolves outside engine/: ${file}`, patch.filename);
+                    }
+                }
+            }
+            catch (error) {
+                // File doesn't exist yet (new file) or stat fails — skip check
+                if (error instanceof PatchError)
+                    throw error;
+            }
+        }
     }
 }
 /**

package/dist/src/core/patch-lint-checkjs.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Optional TypeScript `checkJs` pass for patch-owned `.sys.mjs` files.
+ *
+ * Loads the TypeScript compiler API via dynamic import so it is only
+ * required when `patchLint.checkJs` is enabled in `fireforge.json`.
+ * TypeScript remains a dev-dependency — if a user enables checkJs
+ * without installing it, the pass emits a clear error explaining
+ * how to fix it.
+ *
+ * Separated from `patch-lint.ts` to keep both files within the
+ * project's per-file line budget.
+ */
+import type { PatchLintIssue } from '../types/commands/index.js';
+/**
+ * Runs TypeScript's checkJs pass on patch-owned `.sys.mjs` files.
+ *
+ * @param repoDir - Absolute path to the engine (repository) directory
+ * @param patchOwnedFiles - Set of patch-owned `.sys.mjs` file paths (relative to repoDir)
+ * @returns Array of lint issues from TS diagnostics
+ */
+export declare function runCheckJs(repoDir: string, patchOwnedFiles: Set<string>): Promise<PatchLintIssue[]>;