@herbertgao/pi-extensions 2026.8.3 → 2026.8.5

package/node_modules/pi-lens/dist/clients/formatters.js

@@ -8,14 +8,22 @@
  *
  * Inspired by OpenCode's formatter.ts pattern
  */
+import { logExtension } from "./extension-log.js";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { BoundedLruCache } from "./bounded-cache.js";
+import { normalizeMapKey } from "./path-utils.js";
+import { TERRAGRUNT_FILENAMES } from "./file-kinds.js";
+import { detectIndentation, hasDetectableIndentation, } from "./dispatch/indent-detect.js";
 import { logLatency } from "./latency-logger.js";
 import { findGlobalBinary } from "./package-manager.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
-import { getAutoInstallToolIdForFormatter, getFormatterPolicyForFile, getSmartDefaultFormatterName, hasBiomeConfig, hasBlackConfig, hasClangFormatConfig, hasCljfmtConfig, hasCmakeFormatConfig, hasGoogleJavaFormatConfig, hasKtfmtConfig, hasNearestPackageJsonDependency, hasNearestPackageJsonField, hasOcamlformatConfig, hasOxfmtConfig, hasPhpCsFixerConfig, hasPrettierConfig, hasRubocopConfig, hasRuffConfig, hasSqlfluffConfig, hasStandardrbConfig, hasStyluaConfig, hasVitePlusConfig, } from "./tool-policy.js";
+import { assertInstallAllowed } from "./project-trust.js";
+import { getAutoInstallToolIdForFormatter, getFormatterPolicyForFile, getSmartDefaultFormatterName, hasBiomeConfig, hasBlackConfig, hasClangFormatConfig, hasCljfmtConfig, hasCmakeFormatConfig, hasGoogleJavaFormatConfig, hasKtfmtConfig, hasKtlintConfig, hasNearestPackageJsonDependency, hasNearestPackageJsonField, hasOcamlformatConfig, hasOxfmtConfig, hasOxfmtSvelteConfig, hasPhpCsFixerConfig, hasPrettierConfig, hasRubocopConfig, hasRuffConfig, hasSqlfluffConfig, hasStandardrbConfig, hasStyluaConfig, hasVitePlusConfig, OXFMT_SUPPORTED_EXTENSIONS, } from "./tool-policy.js";
 const _lazyInstallAttempts = new Set();
 export async function tryLazyInstallFormatterTool(tool, cwd) {
+    if (!assertInstallAllowed(`formatter lazy install: ${tool}`))
+        return false;
     const attemptKey = `${tool}:${cwd}`;
     if (_lazyInstallAttempts.has(attemptKey))
         return false;
@@ -28,7 +36,11 @@ export async function tryLazyInstallFormatterTool(tool, cwd) {
         });
         const ok = !res.error && res.status === 0;
         if (!ok) {
-            console.error(`[format] lazy-install rubocop failed: ${res.error?.message ?? res.stderr ?? "exit " + res.status}`);
+            logExtension({
+                subsystem: "format",
+                message: `lazy-install rubocop failed: ${res.error?.message ?? res.stderr ?? "exit " + res.status}`,
+                metadata: { tool: "rubocop", cwd },
+            });
         }
         return ok;
     }
@@ -39,10 +51,23 @@ export async function tryLazyInstallFormatterTool(tool, cwd) {
     });
     const ok = !res.error && res.status === 0;
     if (!ok) {
-        console.error(`[format] lazy-install rustfmt failed: ${res.error?.message ?? res.stderr ?? "exit " + res.status}`);
+        logExtension({
+            subsystem: "format",
+            message: `lazy-install rustfmt failed: ${res.error?.message ?? res.stderr ?? "exit " + res.status}`,
+            metadata: { tool: "rustfmt", cwd },
+        });
     }
     return ok;
 }
+// --- Types ---
+/**
+ * Sentinel a `resolveCommand` returns to mean "do not format this file at
+ * all" — distinct from `null`, which means "fall back to the static
+ * `command`". #1144's style-preserving resolvers return this when the repo
+ * has no config AND the file's indentation is undetectable: running the
+ * stock command there is exactly the stock-style imposition the fix bans.
+ */
+export const SKIP_FORMATTING = "skip-formatting";
 // --- Utility Functions ---
 async function fileExists(filePath) {
     try {
@@ -189,13 +214,23 @@ async function resolveManagedSmartDefaultCommand(formatterName, filePath, args)
         return null;
     return [installed, ...args, filePath];
 }
-function hasExplicitFormatterConfig(formatterName, cwd) {
+function hasExplicitFormatterConfig(formatterName, cwd, ext) {
     switch (formatterName) {
         case "biome":
             return hasBiomeConfig(cwd);
         case "prettier":
             return (hasPrettierConfig(cwd) || hasNearestPackageJsonField(cwd, "prettier"));
         case "oxfmt":
+            // .svelte is conditional beyond "an oxfmt config exists": oxfmt
+            // requires the `svelte` package installed AND the config's `svelte`
+            // flag enabled (verified empirically — see hasOxfmtSvelteConfig).
+            // The generic checks below are NOT sufficient for .svelte — an
+            // oxfmt.toml with no svelte flag, or an oxfmt dependency alone,
+            // both fail at runtime for .svelte specifically (other extensions
+            // are unaffected by this stricter gate).
+            if (ext === ".svelte") {
+                return hasOxfmtSvelteConfig(cwd);
+            }
             return (hasOxfmtConfig(cwd) ||
                 hasVitePlusConfig(cwd) ||
                 // The published package is `oxfmt`; `@oxc-project/oxfmt` does not
@@ -224,6 +259,8 @@ function hasExplicitFormatterConfig(formatterName, cwd) {
             return hasGoogleJavaFormatConfig(cwd);
         case "ktfmt":
             return hasKtfmtConfig(cwd);
+        case "ktlint":
+            return hasKtlintConfig(cwd);
         case "cljfmt":
             return hasCljfmtConfig(cwd);
         case "cmake-format":
@@ -242,28 +279,94 @@ async function hasEditorConfig(cwd) {
         return false;
     }
 }
+async function indentationArgs(filePath, tool, cwd) {
+    if (await hasEditorConfig(cwd) || hasExplicitFormatterConfig(tool, cwd, path.extname(filePath))) {
+        return [];
+    }
+    let content;
+    try {
+        content = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        // Resolution tests and callers may probe a path before it exists.
+        return [];
+    }
+    if (!hasDetectableIndentation(content))
+        return null;
+    const indentation = detectIndentation(content);
+    if (tool === "shfmt")
+        return indentation.style === "tab" ? ["-i", "0"] : ["-i", String(indentation.width)];
+    if (tool === "prettier") {
+        return [indentation.style === "tab" ? "--use-tabs" : "--no-use-tabs", "--tab-width", String(indentation.width)];
+    }
+    if (tool === "ruff") {
+        // `ruff format` has NO --indent-style/--indent-width flags (it errors with
+        // "unexpected argument" and exits 2, which formatFile reported as a silent
+        // clean no-op back when exit-code strictness was opt-in). Style is pinned
+        // through inline TOML overrides instead (#1144 follow-up).
+        return [
+            "--config",
+            `indent-width=${indentation.width}`,
+            "--config",
+            `format.indent-style='${indentation.style}'`,
+        ];
+    }
+    return ["--indent-style", indentation.style, "--indent-width", String(indentation.width)];
+}
+/**
+ * Every biome invocation must carry this. Biome exits 1 with "No files were
+ * processed in the specified paths" when the path is ignored by the repo's own
+ * biome.json or carries an extension biome does not handle — a benign outcome
+ * that, under #1337's strict default, would otherwise report a formatting
+ * failure on every edit under an ignored directory. Verified against biome
+ * 2.4.12: ignored path → exit 1, +flag → exit 0; unsupported extension → exit
+ * 1, +flag → exit 0; and a real syntax error still exits 1 WITH the flag, so
+ * strictness is preserved for actual failures.
+ *
+ * `clients/dispatch/runners/biome-check.ts:108` already passes this on the lint
+ * path; the formatter path did not, which is what made biome the one
+ * misclassified formatter in the #1337 audit.
+ */
+const BIOME_UNMATCHED_FLAG = "--no-errors-on-unmatched";
 export const biomeFormatter = {
     name: "biome",
-    command: ["npx", "@biomejs/biome", "format", "--write", "$FILE"],
+    command: [
+        "npx",
+        "@biomejs/biome",
+        "format",
+        "--write",
+        BIOME_UNMATCHED_FLAG,
+        "$FILE",
+    ],
     async resolveCommand(filePath, cwd) {
         const editorConfigFlag = (await hasEditorConfig(cwd))
             ? ["--use-editorconfig=true"]
             : [];
+        const styleArgs = await indentationArgs(filePath, "biome", cwd);
+        if (styleArgs === null)
+            return SKIP_FORMATTING;
+        const args = [
+            "format",
+            "--write",
+            BIOME_UNMATCHED_FLAG,
+            ...editorConfigFlag,
+            ...styleArgs,
+        ];
         const local = await findInNodeModules("biome", cwd);
         if (local)
-            return [local, "format", "--write", ...editorConfigFlag, filePath];
+            return [local, ...args, filePath];
         // Any package manager's global bin dir (npm/pnpm/yarn/bun) before we
         // auto-install — catches a `pnpm add -g @biomejs/biome` PATH misses (#375).
         const global = await findGlobalBinary("biome");
         if (global)
-            return [global, "format", "--write", ...editorConfigFlag, filePath];
+            return [global, ...args, filePath];
         const toolId = getAutoInstallToolIdForFormatter("biome");
         if (!toolId)
             return null;
         const { ensureTool } = await import("./installer/index.js");
         const installed = await ensureTool(toolId);
         if (installed)
-            return [installed, "format", "--write", ...editorConfigFlag, filePath];
+            return [installed, ...args, filePath];
         return null;
     },
     extensions: [
@@ -294,14 +397,18 @@ export const prettierFormatter = {
     name: "prettier",
     command: ["npx", "prettier", "--write", "$FILE"],
     async resolveCommand(filePath, cwd) {
+        const styleArgs = await indentationArgs(filePath, "prettier", cwd);
+        if (styleArgs === null)
+            return SKIP_FORMATTING;
+        const args = ["--write", ...styleArgs];
         const local = await findInNodeModules("prettier", cwd);
         if (local)
-            return [local, "--write", filePath];
+            return [local, ...args, filePath];
         // Global bin of any manager (npm/pnpm/yarn/bun) before auto-install (#375).
         const global = await findGlobalBinary("prettier");
         if (global)
-            return [global, "--write", filePath];
-        return resolveManagedSmartDefaultCommand("prettier", filePath, ["--write"]);
+            return [global, ...args, filePath];
+        return resolveManagedSmartDefaultCommand("prettier", filePath, args);
     },
     extensions: [
         ".js",
@@ -338,6 +445,11 @@ export const prettierFormatter = {
 export const oxfmtFormatter = {
     name: "oxfmt",
     command: ["oxfmt", "$FILE"],
+    // #1337 audit: oxfmt (and the `vp fmt --write` path) publish no exit-code
+    // table. `--write` is the default and `--check` is the separate verification
+    // mode, so there is no documented nonzero-on-reformat. Absent a documented
+    // benign-nonzero mode, it stays strict — the safe direction, since the failure
+    // mode of guessing wrong the other way is a silent no-op (#1336).
     async resolveCommand(filePath, cwd) {
         if (hasVitePlusConfig(cwd)) {
             const localVp = await findInNodeModules("vp", cwd);
@@ -355,18 +467,10 @@ export const oxfmtFormatter = {
             return [found, filePath];
         return null;
     },
-    extensions: [
-        ".js", ".jsx", ".mjs", ".cjs",
-        ".ts", ".tsx", ".mts", ".cts",
-        ".vue",
-        ".css", ".scss", ".less",
-        ".html", ".htm",
-        ".json", ".jsonc",
-        ".yaml", ".yml",
-        ".md", ".mdx",
-        ".graphql", ".gql",
-        ".toml",
-    ],
+    // Single source of truth: OXFMT_SUPPORTED_EXTENSIONS in tool-policy.ts.
+    // Do not hand-maintain a second copy of this list (#1134 — previously two
+    // parallel hand-maintained lists, the #883 single-source-of-truth class).
+    extensions: [...OXFMT_SUPPORTED_EXTENSIONS],
     async detect(cwd) {
         return (hasOxfmtConfig(cwd) ||
             hasVitePlusConfig(cwd) ||
@@ -379,17 +483,25 @@ export const ruffFormatter = {
     name: "ruff",
     command: ["ruff", "format", "$FILE"],
     extensions: [".py", ".pyi"],
+    // Strict (the #1337 default): `ruff format` exits 0 on a successful in-place
+    // rewrite and 2 on argument rejection / syntax error (verified, ruff 0.x:
+    // well-formed → 0, reformatted → 0, unparseable → 2). The exit-2 no-op is
+    // exactly what hid the bad --indent-style flags for a full release cycle.
     async resolveCommand(filePath, cwd) {
+        const styleArgs = await indentationArgs(filePath, "ruff", cwd);
+        if (styleArgs === null)
+            return SKIP_FORMATTING;
+        const args = ["format", ...styleArgs];
         const venv = await findInVenv("ruff", cwd);
         if (venv)
-            return [venv, "format", filePath];
+            return [venv, ...args, filePath];
         const toolId = getAutoInstallToolIdForFormatter("ruff");
         if (!toolId)
             return null;
         const { ensureTool } = await import("./installer/index.js");
         const installed = await ensureTool(toolId);
         if (installed)
-            return [installed, "format", filePath];
+            return [installed, ...args, filePath];
         return null;
     },
     async detect(cwd) {
@@ -420,6 +532,11 @@ export const sqlfluffFormatter = {
     name: "sqlfluff",
     command: ["sqlfluff", "fix", "--force", "$FILE"],
     extensions: [".sql"],
+    lenientExitCode: "lint-autofix: `sqlfluff fix` writes the corrected file and then exits 1 " +
+        "when unfixable violations remain (its documented exit codes are 0 = all " +
+        "clean, 1 = violations remain, 2 = command/config failure), so a nonzero " +
+        "exit routinely accompanies a successful rewrite.",
+    lenientStatuses: [1],
     async resolveCommand(filePath, cwd) {
         const venv = await findInVenv("sqlfluff", cwd);
         if (venv)
@@ -481,11 +598,14 @@ export const shfmtFormatter = {
     name: "shfmt",
     command: ["shfmt", "-w", "$FILE"],
     extensions: [".sh", ".bash"],
-    async resolveCommand(filePath, _cwd) {
+    async resolveCommand(filePath, cwd) {
+        const styleArgs = await indentationArgs(filePath, "shfmt", cwd);
+        if (styleArgs === null)
+            return SKIP_FORMATTING;
         const inPath = await which("shfmt");
         if (inPath)
-            return [inPath, "-w", filePath];
-        return resolveManagedSmartDefaultCommand("shfmt", filePath, ["-w"]);
+            return [inPath, "-w", ...styleArgs, filePath];
+        return resolveManagedSmartDefaultCommand("shfmt", filePath, ["-w", ...styleArgs]);
     },
     async detect(_cwd) {
         if ((await which("shfmt")) !== null)
@@ -497,6 +617,9 @@ export const shfmtFormatter = {
 export const nixfmtFormatter = {
     name: "nixfmt",
     command: ["nixfmt", "$FILE"],
+    // #1337 audit: nixfmt's README documents in-place formatting but has no
+    // exit-code section and no change-detection mode, so nothing documents a
+    // benign nonzero. Strict by default (see oxfmt above for the rationale).
     extensions: [".nix"],
     async detect(_cwd) {
         return (await which("nixfmt")) !== null;
@@ -540,6 +663,11 @@ export const ktlintFormatter = {
     name: "ktlint",
     command: ["ktlint", "-F", "$FILE"],
     extensions: [".kt", ".kts"],
+    lenientExitCode: "lint-autofix: `ktlint -F` autocorrects what it can and then exits 1 if " +
+        "any lint error remains unfixed — the documented CLI contract (ktlint " +
+        "exits nonzero whenever violations are reported, and -F does not suppress " +
+        "the ones it cannot correct).",
+    lenientStatuses: [1],
     async resolveCommand(filePath, _cwd) {
         const inPath = await which("ktlint");
         if (inPath)
@@ -576,6 +704,12 @@ export const rubocopFormatter = {
     name: "rubocop",
     command: ["rubocop", "-a", "--no-color", "$FILE"],
     extensions: [".rb", ".rake", ".gemspec", ".ru"],
+    lenientExitCode: "lint-autofix: `rubocop -a` exits 1 whenever ANY offense remains after it " +
+        "has already rewritten the file. Verified locally (rubocop on Ruby 3.4): a " +
+        "file with an unfixable Lint/UselessAssignment exits 1, and even a " +
+        "tidy file exits 1 on an unfixable Style/Documentation offense — nonzero " +
+        "is the normal outcome, not a failure.",
+    lenientStatuses: [1],
     async resolveCommand(filePath, cwd) {
         if (await canUseBundleExec(cwd))
             return ["bundle", "exec", "rubocop", "-a", "--no-color", filePath];
@@ -594,6 +728,9 @@ export const standardrbFormatter = {
     name: "standardrb",
     command: ["standardrb", "--fix", "$FILE"],
     extensions: [".rb", ".rake"],
+    lenientExitCode: "lint-autofix: standardrb is a RuboCop wrapper and inherits its exit " +
+        "contract — `--fix` exits 1 when offenses remain after the rewrite.",
+    lenientStatuses: [1],
     async resolveCommand(filePath, cwd) {
         if (await canUseBundleExec(cwd))
             return ["bundle", "exec", "standardrb", "--fix", filePath];
@@ -625,6 +762,18 @@ export const terraformFormatter = {
         return (await which("terraform")) !== null;
     },
 };
+export const terragruntHclFormatter = {
+    name: "terragrunt-hcl",
+    command: ["terragrunt", "hcl", "fmt", "--file", "$FILE"],
+    extensions: [],
+    filenames: TERRAGRUNT_FILENAMES,
+    // Strict (the #1337 default): verified exit 0 on a successful in-place format
+    // against terragrunt v1.1.2. A binary predating the `hcl` command group exits
+    // nonzero and touches nothing, which unguarded reads as "already formatted".
+    async detect(_cwd) {
+        return (await which("terragrunt")) !== null;
+    },
+};
 export const phpCsFixerFormatter = {
     name: "php-cs-fixer",
     command: ["php-cs-fixer", "fix", "$FILE"],
@@ -766,24 +915,44 @@ export const cmakeFormatFormatter = {
         return hasCmakeFormatConfig(cwd);
     },
 };
+/**
+ * The PowerShell one-liner behind `psscriptanalyzer-format`.
+ *
+ * #1337 audit finding: without `$ErrorActionPreference = 'Stop'`, a failing
+ * `Invoke-Formatter` is a NON-TERMINATING error — pwsh still exits 0, so this
+ * formatter could never report a failure through the strict seam and the #1336
+ * silent-no-op class survived intact for `.ps1/.psm1/.psd1`. Verified: an
+ * `Invoke-Formatter` argument-validation failure exits 0 under the old script.
+ *
+ * Two more defects fixed here rather than left as landmines:
+ *  - the old script ran `Set-Content -Value $formatted` even when `$formatted`
+ *    was `$null`, which TRUNCATES the file it was asked to format;
+ *  - single-quoted interpolation broke on any path containing an apostrophe.
+ * An empty/whitespace-only file exits 0 without touching anything, so "nothing
+ * to format" stays a clean no-op rather than a reported failure.
+ */
+function psScriptAnalyzerCommand(filePath) {
+    // PowerShell single-quoted strings escape an apostrophe by doubling it.
+    const quoted = filePath.replace(/'/g, "''");
+    return [
+        "$ErrorActionPreference = 'Stop'",
+        `$p = '${quoted}'`,
+        "$content = Get-Content -Raw -LiteralPath $p",
+        "if ([string]::IsNullOrWhiteSpace($content)) { exit 0 }",
+        "$formatted = Invoke-Formatter -ScriptDefinition $content",
+        "if ($null -eq $formatted) { throw 'Invoke-Formatter returned no output' }",
+        "Set-Content -LiteralPath $p -Value $formatted",
+    ].join("; ");
+}
 export const psscriptanalyzerFormatFormatter = {
     name: "psscriptanalyzer-format",
-    command: [
-        "pwsh",
-        "-Command",
-        "Invoke-Formatter -ScriptDefinition (Get-Content -Raw '$FILE') | Set-Content '$FILE'",
-    ],
+    command: ["pwsh", "-NoProfile", "-Command", psScriptAnalyzerCommand("$FILE")],
     extensions: [".ps1", ".psm1", ".psd1"],
     async resolveCommand(filePath, _cwd) {
         const pwsh = (await which("pwsh")) ?? (await which("powershell"));
         if (!pwsh)
             return null;
-        return [
-            pwsh,
-            "-NoProfile",
-            "-Command",
-            `$content = Get-Content -Raw '${filePath}'; $formatted = Invoke-Formatter -ScriptDefinition $content; Set-Content -Path '${filePath}' -Value $formatted`,
-        ];
+        return [pwsh, "-NoProfile", "-Command", psScriptAnalyzerCommand(filePath)];
     },
     async detect(_cwd) {
         const pwsh = (await which("pwsh")) ?? (await which("powershell"));
@@ -799,7 +968,11 @@ export const psscriptanalyzerFormatFormatter = {
     },
 };
 // --- Registry ---
-const ALL_FORMATTERS = [
+// Exported for the formatter/policy drift guard (tests/clients/
+// formatter-policy-consistency.test.ts, #1135): the test cross-checks these
+// definitions against tool-policy.ts's FORMATTER_POLICY_BY_EXTENSION so the two
+// hand-maintained inverse mappings can never silently diverge.
+export const ALL_FORMATTERS = [
     biomeFormatter,
     prettierFormatter,
     oxfmtFormatter,
@@ -818,6 +991,7 @@ const ALL_FORMATTERS = [
     ktlintFormatter,
     ktfmtFormatter,
     terraformFormatter,
+    terragruntHclFormatter,
     phpCsFixerFormatter,
     csharpierFormatter,
     fantomasFormatter,
@@ -833,27 +1007,70 @@ const ALL_FORMATTERS = [
     cmakeFormatFormatter,
     psscriptanalyzerFormatFormatter,
 ];
+// Basenames claimed by a filename-keyed formatter, e.g. terragrunt.hcl.
+const FILENAME_FORMATTER_BASENAMES = new Set(ALL_FORMATTERS.flatMap((f) => f.filenames ?? []));
 // Cache for detection results - stores array of enabled formatter names per cwd+ext
-const detectionCache = new Map();
+const detectionCache = new BoundedLruCache(32);
+// These are the formatter configuration files consulted by the policy helpers
+// above. Their metadata is part of detection cache identity: changing a file
+// must re-run detection even when PATH and installed tools are unchanged.
+const FORMATTER_CONFIG_FILES = [
+    "package.json", "biome.json", "biome.jsonc", ".prettierrc", ".prettierrc.json",
+    ".prettierrc.yml", ".prettierrc.yaml", ".prettierrc.js", ".prettierrc.cjs",
+    ".prettierrc.mjs", "prettier.config.js", "prettier.config.cjs", "prettier.config.mjs",
+    "prettier.config.ts", "pyproject.toml", "ruff.toml", ".ruff.toml", "black.toml",
+    ".black", "tox.ini", "requirements.txt", "Pipfile", ".sqlfluff", ".rubocop.yml", ".rubocop.yaml", "Gemfile", ".clang-format",
+    "_clang-format", ".php-cs-fixer.php", ".php-cs-fixer.dist.php", "stylua.toml",
+    ".stylua.toml", ".ocamlformat", ".editorconfig", ".ktfmt", ".ktfmt.kts",
+    ".cljfmt.edn", "cmake-format.py", ".cmake-format.yaml", ".cmake-format.json",
+    "oxfmt.toml", ".oxfmtrc.json", "vite.config.ts", "vite.config.js", "vite.config.mjs",
+];
+async function formatterConfigSignature(cwd) {
+    const paths = await findUp(FORMATTER_CONFIG_FILES, cwd);
+    const parts = await Promise.all(paths.sort((a, b) => a.localeCompare(b)).map(async (filePath) => {
+        try {
+            const stat = await fs.stat(filePath);
+            return `${filePath}:${stat.mtimeMs}:${stat.size}`;
+        }
+        catch {
+            return `${filePath}:missing`;
+        }
+    }));
+    return parts.join("|");
+}
 // --- Public API ---
 export async function getFormattersForFile(filePath, cwd) {
     const ext = path.extname(filePath).toLowerCase();
-    const cacheKey = `${cwd}:${ext}`;
+    const base = path.basename(filePath).toLowerCase();
+    // Filename-keyed formatters (e.g. terragrunt.hcl) can share an extension
+    // with unrelated files in the same dir (.terraform.lock.hcl next to
+    // terragrunt.hcl). Fold the basename into the cache key only when a
+    // filename-based formatter actually applies, so a plain .hcl file cached
+    // first doesn't poison the cache for terragrunt.hcl/root.hcl, or vice versa.
+    const normalizedCwd = normalizeMapKey(cwd);
+    const cacheKey = FILENAME_FORMATTER_BASENAMES.has(base)
+        ? `${normalizedCwd}:${ext}:${base}`
+        : `${normalizedCwd}:${ext}`;
+    const configSignature = await formatterConfigSignature(cwd);
     // Check cache
-    let cached = detectionCache.get(cwd);
+    let cached = detectionCache.get(normalizedCwd);
+    if (cached?.signature !== configSignature) {
+        cached = undefined;
+        detectionCache.delete(normalizedCwd);
+    }
     if (!cached) {
-        cached = new Map();
-        detectionCache.set(cwd, cached);
+        cached = { signature: configSignature, entries: new Map() };
+        detectionCache.set(normalizedCwd, cached);
     }
-    if (cached.has(cacheKey)) {
-        const enabledNames = cached.get(cacheKey);
+    if (cached.entries.has(cacheKey)) {
+        const enabledNames = cached.entries.get(cacheKey);
         if (!enabledNames || enabledNames.length === 0)
             return [];
         // Return cached formatters by name (preserves priority order)
         return ALL_FORMATTERS.filter((f) => enabledNames.includes(f.name));
     }
-    // Detect formatters for this extension
-    const matching = ALL_FORMATTERS.filter((f) => f.extensions.includes(ext));
+    // Detect formatters for this extension (or exact filename, e.g. terragrunt.hcl)
+    const matching = ALL_FORMATTERS.filter((f) => f.extensions.includes(ext) || f.filenames?.includes(base));
     const formatterPolicy = getFormatterPolicyForFile(filePath);
     const smartDefaultFormatterName = getSmartDefaultFormatterName(filePath);
     const candidateFormatters = formatterPolicy?.formatterNames?.length
@@ -861,7 +1078,7 @@ export async function getFormattersForFile(filePath, cwd) {
         : matching;
     let selected;
     if (formatterPolicy) {
-        const explicitlyConfigured = candidateFormatters.filter((formatter) => hasExplicitFormatterConfig(formatter.name, cwd));
+        const explicitlyConfigured = candidateFormatters.filter((formatter) => hasExplicitFormatterConfig(formatter.name, cwd, ext));
         if (explicitlyConfigured.length > 0) {
             // A formatter with explicit project config was found — use it.
             // Prefer the policy's defaultFormatter only if it has explicit config,
@@ -892,7 +1109,11 @@ export async function getFormattersForFile(filePath, cwd) {
             }
             catch (err) {
                 // pi-lens-ignore: missing-error-propagation — optional formatter detection, skip on failure
-                console.error(`[format] Detection failed for ${formatter.name}:`, err);
+                logExtension({
+                    subsystem: "format",
+                    message: `Detection failed for ${formatter.name}: ${err instanceof Error ? err.message : String(err)}`,
+                    metadata: { formatter: formatter.name, cwd },
+                });
             }
         }
     }
@@ -905,7 +1126,7 @@ export async function getFormattersForFile(filePath, cwd) {
         selectionReason = "detect";
     }
     else {
-        selectionReason = candidateFormatters.some((f) => hasExplicitFormatterConfig(f.name, cwd))
+        selectionReason = candidateFormatters.some((f) => hasExplicitFormatterConfig(f.name, cwd, ext))
             ? "explicit-config"
             : "smart-default";
     }
@@ -922,7 +1143,7 @@ export async function getFormattersForFile(filePath, cwd) {
     });
     // Store the list of enabled formatter names in cache
     const enabledNames = enabled.map((f) => f.name);
-    cached.set(cacheKey, enabledNames);
+    cached.entries.set(cacheKey, enabledNames);
     return enabled;
 }
 export function clearFormatterCache() {
@@ -932,27 +1153,103 @@ export function clearFormatterRuntimeState() {
     detectionCache.clear();
     _lazyInstallAttempts.clear();
 }
+// ESC is built via fromCharCode so no raw control byte sits in the source.
+const ANSI_ESCAPE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*[A-Za-z]`, "g");
+const BOX_DRAWING_GLOBAL = /[\u2500-\u257F]/g;
+const HAS_BOX_DRAWING = /[\u2500-\u257F]/;
+/**
+ * First line of `text` that actually carries a diagnostic.
+ *
+ * #1337 made nonzero exits user-visible, which put whatever this returns in
+ * front of the agent (`clients/pipeline.ts`) and in the end-of-turn summary
+ * (`clients/runtime-agent-end.ts`) — so "first line of stderr" is no longer
+ * good enough. Biome opens stderr with a decorated section rule
+ * (`format ━━━━━━━━━━━`), which as an error message is pure noise.
+ *
+ * Skips blank lines, pure box-drawing rules, and short banner headings; strips
+ * ANSI colour so the message stays readable in a plain-text surface.
+ */
+export function firstDiagnosticLine(text) {
+    for (const raw of (text ?? "").split("\n")) {
+        const line = raw.replace(ANSI_ESCAPE, "").trimEnd();
+        const stripped = line.replace(BOX_DRAWING_GLOBAL, "").trim();
+        if (!stripped)
+            continue;
+        // "format ━━━━━━━━" is a section banner, not a diagnostic. Require a rule
+        // AND a short remainder so a real one-line error containing a box
+        // character is not discarded.
+        if (HAS_BOX_DRAWING.test(line) && stripped.length <= 24)
+            continue;
+        return stripped.slice(0, 300);
+    }
+    return undefined;
+}
+/**
+ * Resolve a formatter command without allowing the static command fallback to
+ * bypass a resolver's style-preservation refusal (#1345). `null` means the
+ * primary command is unavailable; the explicit sentinel means formatting is
+ * forbidden for this file and must be returned before the static command is
+ * materialized.
+ */
+async function resolveFormatterCommand(formatter, absolutePath, cwd) {
+    const resolved = formatter.resolveCommand
+        ? await formatter.resolveCommand(absolutePath, cwd)
+        : null;
+    if (resolved === SKIP_FORMATTING)
+        return SKIP_FORMATTING;
+    if (resolved !== null)
+        return resolved;
+    const fallback = formatter.command.map((c) => c.replace("$FILE", absolutePath));
+    // Trust gate on the install-capable static fallback (#1334 S5): npx can
+    // DOWNLOAD packages, so an untrusted project treats the fallback as
+    // unavailable -- a skip, not a formatter failure; may converge next turn.
+    if (fallback[0] === "npx" &&
+        !assertInstallAllowed(`formatter npx fallback: ${formatter.name}`)) {
+        // No second ledger entry here (#1366 review): assertInstallAllowed just
+        // recorded the trust-refusal with this formatter's context — recording
+        // formatter-skip too would count one user-visible degradation twice.
+        return SKIP_FORMATTING;
+    }
+    return fallback;
+}
 export async function formatFile(filePath, formatter) {
     try {
         const absolutePath = path.resolve(filePath);
         const cwd = path.dirname(absolutePath);
         const contentBefore = await fs.readFile(absolutePath, "utf-8");
-        // Resolve command: prefer local (venv/vendor/node_modules) over global
-        const resolved = formatter.resolveCommand
-            ? await formatter.resolveCommand(absolutePath, cwd)
-            : null;
-        const cmd = resolved ??
-            formatter.command.map((c) => c.replace("$FILE", absolutePath));
+        // Resolve command: prefer local (venv/vendor/node_modules) over global.
+        // The shared seam must honor SKIP_FORMATTING before selecting the static
+        // command, including its npx fallback (#1345).
+        const cmd = await resolveFormatterCommand(formatter, absolutePath, cwd);
+        if (cmd === SKIP_FORMATTING) {
+            // Style-preserving refusal (#1144): no repo config and no detectable
+            // indentation to pin — formatting would impose the tool's stock style.
+            return { success: true, changed: false };
+        }
         // Run formatter without blocking the event loop.
         const result = await safeSpawnAsync(cmd[0], cmd.slice(1), {
             timeout: 15000,
             cwd,
         });
-        if (result.error) {
+        // Strict by default (#1337): only a formatter with a documented
+        // benign-nonzero mode (`lenientExitCode`) may exit nonzero and still be
+        // read as a successful run. Everything else that exits nonzero never
+        // rewrote the file, and reporting {success: true, changed: false} there is
+        // indistinguishable from "already formatted" — the #1336 silent no-op.
+        const lenientOk = formatter.lenientExitCode !== undefined &&
+            result.status !== null &&
+            (formatter.lenientStatuses ?? []).includes(result.status);
+        if (result.error || (result.status !== 0 && !lenientOk)) {
             return {
                 success: false,
                 changed: false,
-                error: result.error.message,
+                error: result.error?.message ||
+                    firstDiagnosticLine(result.stderr) ||
+                    // biome, ktlint and `mix format` report on STDOUT; without this
+                    // their diagnostic is discarded and the user is told only that
+                    // the tool "exited with status 1".
+                    firstDiagnosticLine(result.stdout) ||
+                    `${formatter.name} exited with status ${result.status}`,
             };
         }
         // Check if content changed