@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

package/node_modules/pi-lens/dist/clients/ast-grep-client.js

@@ -7,12 +7,13 @@
  * Requires: npm install -D @ast-grep/cli
  * Rules: ./rules/ directory
  */
+import { createSubsystemLogger } from "./extension-log.js";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { AstGrepRuleManager } from "./ast-grep-rule-manager.js";
 import { resolvePackagePath } from "./package-root.js";
-import { SgRunner } from "./sg-runner.js";
+import { SgRunner, } from "./sg-runner.js";
 // --- Client ---
 function extractDebugAst(raw) {
     const lines = raw.split(/\r?\n/);
@@ -53,7 +54,7 @@ const VALIDATION_SNIPPETS = {
     html: { ext: "html", source: "<main>pi-lens</main>\n" },
     java: { ext: "java", source: "class Main { void run() {} }\n" },
     javascript: { ext: "js", source: "const piLensValidate = 1;\n" },
-    json: { ext: "json", source: "{\"piLensValidate\":true}\n" },
+    json: { ext: "json", source: '{"piLensValidate":true}\n' },
     kotlin: { ext: "kt", source: "fun main() {}\n" },
     lua: { ext: "lua", source: "local pi_lens_validate = 1\n" },
     php: { ext: "php", source: "<?php $piLensValidate = 1;\n" },
@@ -66,7 +67,10 @@ const VALIDATION_SNIPPETS = {
 };
 function validationSnippetFor(language) {
     const key = language.toLowerCase().replace(/^"|"$/g, "");
-    return VALIDATION_SNIPPETS[key] ?? { ext: key.replace(/[^a-z0-9_-]/gi, "") || "txt", source: "pi_lens_validate\n" };
+    return (VALIDATION_SNIPPETS[key] ?? {
+        ext: key.replace(/[^a-z0-9_-]/gi, "") || "txt",
+        source: "pi_lens_validate\n",
+    });
 }
 function validateInputShape(value, maxChars, label) {
     if (value.includes("\0"))
@@ -110,7 +114,7 @@ export class AstGrepClient {
                     ? projectRuleDir
                     : resolvePackagePath(import.meta.url, "rules"));
         this.log = verbose
-            ? (msg) => console.error(`[ast-grep] ${msg}`)
+            ? createSubsystemLogger("ast-grep")
             : () => { };
         this.ruleManager = new AstGrepRuleManager(this.ruleDir, this.log);
         this.runner = new SgRunner(verbose);
@@ -129,9 +133,18 @@ export class AstGrepClient {
         const allMatches = [];
         for (const scanPath of paths) {
             if (apply) {
-                // Stale-preview check: dry-run first
-                const preCheck = await this.runner.tempScanAsync(scanPath, "agent-rule", ruleYaml);
-                if (preCheck.length === 0) {
+                // Stale-preview check: dry-run first. Preserve CLI failures instead of
+                // treating an invalid rule as a stale, no-match preview.
+                const preCheck = await this.tempScanDetailed(scanPath, ruleYaml);
+                if (preCheck.failure || preCheck.error) {
+                    return {
+                        matches: allMatches,
+                        totalMatches: allMatches.length,
+                        applied: false,
+                        error: preCheck.error ?? "ast-grep preview failed",
+                    };
+                }
+                if (preCheck.matches.length === 0) {
                     return {
                         matches: [],
                         totalMatches: 0,
@@ -162,12 +175,31 @@ export class AstGrepClient {
      * Routes through sg scan --config rather than sg run -p.
      * Each path is scanned independently; results are merged.
      */
-    async searchWithRule(ruleYaml, paths) {
+    async tempScanDetailed(dir, ruleYaml, options = {}) {
+        // Keep tests and older embedders that replace the runner with the historic
+        // match-only seam working. The production SgRunner always has the detailed
+        // method, so failures cannot be mistaken for an empty result there.
+        const detailed = this.runner.tempScanDetailedAsync;
+        if (detailed) {
+            return detailed.call(this.runner, dir, "agent-rule", ruleYaml, 30_000, options);
+        }
+        const matches = await this.runner.tempScanAsync(dir, "agent-rule", ruleYaml, 30_000, options);
+        return { matches, status: 0 };
+    }
+    async searchWithRule(ruleYaml, paths, options = {}) {
         const allMatches = [];
         for (const scanPath of paths) {
             try {
-                const results = await this.runner.tempScanAsync(scanPath, "agent-rule", ruleYaml);
-                allMatches.push(...results);
+                const results = await this.tempScanDetailed(scanPath, ruleYaml, options);
+                if (results.failure || results.error) {
+                    return {
+                        matches: allMatches,
+                        totalMatches: allMatches.length,
+                        error: results.error ||
+                            `ast-grep scan failed (${results.failure ?? "unknown failure"})`,
+                    };
+                }
+                allMatches.push(...results.matches);
             }
             catch (err) {
                 return {
@@ -227,11 +259,24 @@ export class AstGrepClient {
             if (options?.strictness)
                 args.push("--strictness", options.strictness);
             args.push(tmpFile);
-            const result = await this.runner.execRaw(args);
+            const result = await this.runner.execRaw(args, 10_000, options);
             const stderr = result.stderr.trim();
             const stdout = result.stdout.trim();
             if (result.error)
                 return { valid: false, error: result.error };
+            if (result.status !== 0 && !(result.status === 1 && !stderr)) {
+                return {
+                    valid: false,
+                    error: stderr ||
+                        `ast-grep validation failed with exit code ${result.status}`,
+                };
+            }
+            if (result.outputTruncated) {
+                return {
+                    valid: false,
+                    error: "ast-grep validation output was truncated",
+                };
+            }
             if (stderrHasError(stderr))
                 return { valid: false, error: stderr };
             const warning = stderr || stdout || undefined;
@@ -249,7 +294,7 @@ export class AstGrepClient {
             }
         }
     }
-    async validateRule(ruleYaml) {
+    async validateRule(ruleYaml, options = {}) {
         const shapeError = validateInputShape(ruleYaml, MAX_VALIDATE_RULE_CHARS, "rule");
         if (shapeError)
             return { valid: false, error: shapeError };
@@ -258,7 +303,14 @@ export class AstGrepClient {
         const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-lens-sg-rule-"));
         try {
             fs.writeFileSync(path.join(tmpDir, `snippet.${snippet.ext}`), snippet.source, "utf-8");
-            await this.runner.tempScanAsync(tmpDir, "agent-rule", ruleYaml, 10000);
+            const result = await this.tempScanDetailed(tmpDir, ruleYaml, options);
+            if (result.failure || result.error) {
+                return {
+                    valid: false,
+                    error: result.error ||
+                        `ast-grep rule validation failed (${result.failure ?? "unknown failure"})`,
+                };
+            }
             return { valid: true };
         }
         catch (err) {
@@ -332,7 +384,7 @@ export class AstGrepClient {
             args.push("--strictness", options.strictness);
         }
         args.push(...paths);
-        const result = await this.runner.exec(args);
+        const result = await this.runner.exec(args, options);
         return {
             matches: result.matches,
             totalMatches: result.totalMatches,
@@ -505,8 +557,8 @@ message: found
         }
         return exports;
     }
-    formatMatches(matches, isDryRun = false, showModeIndicator = false) {
-        return this.runner.formatMatches(matches, isDryRun, 50, showModeIndicator);
+    formatMatches(matches, isDryRun = false, showModeIndicator = false, maxItems = 50) {
+        return this.runner.formatMatches(matches, isDryRun, maxItems, showModeIndicator);
     }
     /**
      * Format diagnostics for LLM consumption

package/node_modules/pi-lens/dist/clients/ast-grep-types.js

@@ -3,7 +3,6 @@
  *
  * Extracted to prevent circular dependencies between:
  * - ast-grep-client.ts
- * - ast-grep-parser.ts
  * - ast-grep-rule-manager.ts
  */
 export {};

package/node_modules/pi-lens/dist/clients/ast-grep-yaml-synth.js

@@ -21,7 +21,12 @@ const NODE_KIND_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
  * Returns true when at least one structural-intent field is present.
  */
 export function hasStructuralIntent(intent) {
-    return !!(intent.insideKind || intent.hasKind || intent.follows || intent.precedes);
+    return !!(intent.nodeKind ||
+        intent.insideKind ||
+        intent.hasKind ||
+        intent.hasDescendantKind ||
+        intent.follows ||
+        intent.precedes);
 }
 /**
  * Synthesize an ast-grep YAML rule for replace operations.
@@ -33,26 +38,48 @@ export function synthesizeReplaceRule(intent) {
     return `${base}fix: ${JSON.stringify(intent.rewrite)}\n`;
 }
 /**
- * Synthesize an ast-grep YAML rule from a pattern and structural constraints.
+ * Synthesize an ast-grep YAML rule from a pattern (or node kind) and
+ * structural constraints.
  *
- * The generated rule uses `stopBy: end` on `inside` so the search climbs
- * all ancestors, not just the immediate parent.
+ * The generated rule uses `stopBy: end` on `inside` and
+ * `hasDescendantKind`, so those two explicit recursive forms climb all
+ * ancestors/descendants. `hasKind` intentionally retains ast-grep's default
+ * immediate-child semantics for compatibility.
  *
- * @throws if pattern is empty
+ * @throws if neither pattern nor nodeKind is supplied, or both are supplied
  */
 export function synthesizeRule(intent) {
-    assertSafePattern(intent.pattern, "pattern");
+    const hasPattern = !!intent.pattern?.trim();
+    const hasNodeKind = !!intent.nodeKind?.trim();
+    if (hasPattern === hasNodeKind) {
+        throw new Error("provide exactly one of pattern or nodeKind");
+    }
+    const pattern = intent.pattern;
+    if (hasPattern && pattern)
+        assertSafePattern(pattern, "pattern");
+    if (intent.hasKind?.trim() && intent.hasDescendantKind?.trim()) {
+        throw new Error("hasKind and hasDescendantKind are mutually exclusive");
+    }
     // Canonical language name for the YAML header (ast-grep is case-sensitive here).
     const language = canonicalLanguage(intent.lang);
-    const rule = {
-        pattern: intent.pattern,
-    };
+    const rule = hasNodeKind
+        ? { kind: assertSafeNodeKind(intent.nodeKind ?? "", "nodeKind") }
+        : { pattern };
     if (intent.insideKind) {
-        rule.inside = { kind: assertSafeNodeKind(intent.insideKind, "insideKind"), stopBy: "end" };
+        rule.inside = {
+            kind: assertSafeNodeKind(intent.insideKind, "insideKind"),
+            stopBy: "end",
+        };
     }
     if (intent.hasKind) {
         rule.has = { kind: assertSafeNodeKind(intent.hasKind, "hasKind") };
     }
+    if (intent.hasDescendantKind) {
+        rule.has = {
+            kind: assertSafeNodeKind(intent.hasDescendantKind, "hasDescendantKind"),
+            stopBy: "end",
+        };
+    }
     if (intent.follows) {
         assertSafePattern(intent.follows, "follows");
         rule.follows = { pattern: intent.follows };

package/node_modules/pi-lens/dist/clients/atomic-write-staging.js

@@ -0,0 +1,63 @@
+/** Owns the generic atomic-write `.tmp-<pid>-<threadId>-<seq>` namespace. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { threadId } from "node:worker_threads";
+let stageSeq = 0;
+export const STAGE_TMP_PATTERN = /\.tmp-(0|[1-9]\d*)-(0|[1-9]\d*)-(0|[1-9]\d*)$/;
+const STAGE_TMP_PID_PATTERN = /\.tmp-(0|[1-9]\d*)-(?:0|[1-9]\d*)-(?:0|[1-9]\d*)$/;
+export function stagePathFor(targetPath) {
+    return `${targetPath}.tmp-${process.pid}-${threadId}-${stageSeq++}`;
+}
+export function stageOwnerPidFromName(name) {
+    if (!STAGE_TMP_PATTERN.test(name))
+        return undefined;
+    const match = STAGE_TMP_PID_PATTERN.exec(name);
+    if (!match)
+        return undefined;
+    const pid = Number(match[1]);
+    return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+}
+export async function sweepOwnStagingFiles(directories, options) {
+    const uniqueDirectories = [...new Set(directories)].filter(Boolean);
+    const result = { directories: uniqueDirectories.length, scanned: 0, removed: 0, liveSkipped: 0, truncated: false };
+    for (const directory of uniqueDirectories) {
+        let handle;
+        try {
+            handle = await fs.promises.opendir(directory);
+        }
+        catch {
+            continue;
+        }
+        try {
+            let reachedEntryCap = true;
+            for (let i = 0; i < options.maxEntries; i++) {
+                const entry = await handle.read();
+                if (entry === null) {
+                    reachedEntryCap = false;
+                    break;
+                }
+                result.scanned++;
+                if (!entry.isFile())
+                    continue;
+                const pid = stageOwnerPidFromName(entry.name);
+                if (pid === undefined)
+                    continue;
+                if (pid === process.pid || options.isPidAlive(pid)) {
+                    result.liveSkipped++;
+                    continue;
+                }
+                try {
+                    await fs.promises.rm(path.join(directory, entry.name), { force: true });
+                    result.removed++;
+                }
+                catch { /* leave it for the next bounded sweep */ }
+            }
+            result.truncated ||= reachedEntryCap;
+        }
+        catch { /* best-effort directory scan */ }
+        finally {
+            await handle.close().catch(() => { });
+        }
+    }
+    return result;
+}

package/node_modules/pi-lens/dist/clients/atomic-write.js

@@ -1,16 +1,62 @@
 /**
  * Shared atomic tmp+rename file writer (closes #762).
  *
- * The `${target}.tmp-${process.pid}` + `renameSync` shape was independently
- * hand-rolled in five places (`instance-registry.ts`, `session-state-store.ts`,
+ * The `${target}.tmp-…` + `renameSync` shape was independently hand-rolled in
+ * five places (`instance-registry.ts`, `session-state-store.ts`,
  * `recent-touches.ts`, `review-graph/builder.ts`, `diagnostic-dispositions.ts`)
- * as each one picked up the need for a cross-process reader to never observe a
- * partially-written file: `rename()` replaces the destination atomically on
- * both POSIX and Windows (libuv uses `MOVEFILE_REPLACE_EXISTING`), so a
- * concurrent reader always sees either the fully-old or fully-new file, never
- * a torn write. Five independent copies of the same shape invite drift (e.g.
- * forgetting the tmp-file cleanup on the failure path) — this module is the
- * single implementation the rest re-use.
+ * as each one picked up the need for a reader to never observe a
+ * partially-written file. Five independent copies of the same shape invite
+ * drift (e.g. forgetting the tmp-file cleanup on the failure path) — this
+ * module is the single implementation the rest re-use.
+ *
+ * ## What this guarantees (#1205)
+ *
+ * Data is written in full to a staging file that no other writer can name,
+ * then `rename()`d over the target. On POSIX, `rename()` replaces the
+ * destination atomically by construction. On Windows, libuv uses
+ * `MoveFileEx` with `MOVEFILE_REPLACE_EXISTING`, which is atomic in practice
+ * on a same-volume NTFS replace but — unlike POSIX `rename()` — is not a
+ * formally guaranteed atomic primitive (`ReplaceFile` /
+ * `SetFileInformationByHandle` are the stronger APIs). Therefore, modulo that
+ * caveat:
+ *
+ *   - **Crash-safe replacement.** A crash mid-write leaves the target holding
+ *     its previous complete contents plus an orphan staging file; it never
+ *     leaves the target half-written.
+ *   - **Tear-free publication.** Any reader — same process or not — observes
+ *     either the fully-old or the fully-new file at the target path. Because
+ *     the staging name is unique *per call* (pid + thread id + a monotonic
+ *     per-thread counter), this now holds for concurrent writes from the same
+ *     process too, on any thread. Before #1205 the staging name was only
+ *     `.tmp-${pid}`, so two in-flight same-process writes to one target
+ *     shared a staging inode; the first `rename` published it while the
+ *     second writer was still writing into it, publishing a torn hybrid file.
+ *
+ * ## What this explicitly does NOT provide
+ *
+ *   - **No read-modify-write isolation.** Concurrent read → mutate → write
+ *     cycles still lose updates: each writer publishes the state it computed
+ *     from the snapshot it read, and last-rename-wins silently discards the
+ *     other's mutation. Callers needing this must serialize themselves (see
+ *     `lspChildRemovalTail` in `instance-registry.ts`).
+ *   - **No ordering.** Nothing sequences concurrent writers, within or across
+ *     processes. The winner is whichever `rename` lands last, which is not
+ *     necessarily the write that started or finished last.
+ *   - **No mutual exclusion.** This is not a lock. Overlapping writes are
+ *     permitted and expected; only *torn* output is prevented.
+ *   - **No fsync/durability guarantee.** Neither the staging file nor the
+ *     parent directory is fsync'd, so a power loss (as opposed to a process
+ *     crash) may lose the rename.
+ *   - **No self-reaping.** A process killed between the staging write and the
+ *     rename leaves an orphan staging file. The next session_start performs a
+ *     bounded, liveness-checked sweep through the instance-reaper lifecycle
+ *     seam (#1228); this writer never watches or reaps its own files.
+ *   - **Windows-specific loss under `bestEffort: true`.** `MoveFileEx` with
+ *     `MOVEFILE_REPLACE_EXISTING` fails if a reader holds the destination
+ *     open without `FILE_SHARE_DELETE`. On Windows this silently drops the
+ *     write (swallowed like any other `bestEffort: true` failure); the
+ *     identical code path succeeds on POSIX, where `rename()` does not care
+ *     whether a reader has the destination open.
  *
  * Per-write-site error policy varies and is NOT a detail this helper should
  * paper over:
@@ -29,8 +75,62 @@
  *     it swallowed. See the #757 CHANGELOG entry for the full reasoning.
  */
 import * as fs from "node:fs";
+export { STAGE_TMP_PATTERN, stageOwnerPidFromName, stagePathFor, } from "./atomic-write-staging.js";
+import { stagePathFor } from "./atomic-write-staging.js";
+/**
+ * Monotonic counter that makes each staging path unique per CALL, not merely
+ * per process (#1205).
+ *
+ * A counter is used rather than `randomBytes`: it is allocation-free and
+ * synchronous on what are hot per-turn/per-touch write paths, and it is
+ * *exactly* as unique as needed — collisions only matter between two writes
+ * live at the same instant, and a monotonic counter makes those impossible by
+ * construction rather than merely improbable.
+ *
+ * The counter alone is per-THREAD, not per-process: a worker gets its own
+ * module instance and so its own `_stageSeq` starting at 0, while sharing
+ * `process.pid` with the main thread and every sibling worker. Two threads
+ * would therefore each mint `${target}.tmp-<samepid>-0` — the exact collision
+ * the counter exists to prevent. `threadId` (0 on the main thread, distinct
+ * per worker) closes that axis, so the three parts cover the three ways two
+ * writes can be concurrent: `process.pid` across processes, `threadId` across
+ * threads, `_stageSeq` within one thread (#1217).
+ */
+/**
+ * Staging path for one write call: `${targetPath}.tmp-<pid>-<threadId>-<seq>`.
+ *
+ * Exported so that callers which cannot use {@link writeFileAtomic} wholesale
+ * — `gzip-stage-write.ts` needs its own streaming pipeline — still source the
+ * *name* here rather than re-deriving the scheme, and so that sweepers of
+ * orphaned staging files stay in lockstep with it (see
+ * {@link STAGE_TMP_PATTERN}).
+ */
+/**
+ * Matches the trailing staging-file marker produced by {@link stagePathFor},
+ * for the session-start sweeper that garbage-collects staging files orphaned
+ * by a crashed process (#1228). The writer itself does not reap or watch files.
+ *
+ * Only the current four-component shape is matched:
+ * `.tmp-<pid>-<threadId>-<seq>` (#1217). Older one- and two-number suffixes
+ * are deliberately left alone: their shape is indistinguishable from
+ * legitimate user filenames, so deletion safety outweighs reclaiming the
+ * handful of pre-#1208 leftovers.
+ *
+ * CAUTION for any sweeper adopting this pattern: it matches staging files by
+ * shape, not by writer identity, so it also matches this process's own
+ * still-being-written staging files. A safe sweeper must separately protect
+ * `process.pid` and use the shared conservative liveness check for foreign
+ * pids. The review-graph builder's narrower stage sweep intentionally remains
+ * separate because it owns a different `.stage-<pid>-<generation>` namespace.
+ *
+ * Anchoring is correct for both consumer styles in this repo today
+ * (matching against a full path or a bare basename), but this is confined to
+ * pi-lens's own cache directories — a consumer sweeping a directory it does
+ * not fully control should not assume every match is one of this module's
+ * staging files.
+ */
 /**
- * Synchronous atomic write of text or binary data to `${targetPath}.tmp-${pid}`,
+ * Synchronous atomic write of text or binary data to a per-call staging file,
  * then `fs.renameSync` over `targetPath`. On any failure (from either step),
  * attempts a best-effort `fs.rmSync(tmp, { force: true })` cleanup, then
  * either swallows (default) or rethrows per `options.bestEffort`.
@@ -41,7 +141,7 @@ import * as fs from "node:fs";
  */
 export function writeFileAtomic(targetPath, data, options) {
     const bestEffort = options?.bestEffort ?? true;
-    const tmpPath = `${targetPath}.tmp-${process.pid}`;
+    const tmpPath = stagePathFor(targetPath);
     try {
         fs.writeFileSync(tmpPath, data, typeof data === "string" ? "utf-8" : undefined);
         fs.renameSync(tmpPath, targetPath);
@@ -60,12 +160,12 @@ export function writeFileAtomic(targetPath, data, options) {
 /**
  * Async counterpart of {@link writeFileAtomic}, built on `fs.promises` instead
  * of the sync `fs` API — for call sites that must not block the event loop
- * (e.g. writes on a hot per-turn/per-touch path). Same tmp-naming, cleanup,
- * and `bestEffort` semantics.
+ * (e.g. writes on a hot per-turn/per-touch path). Same per-call tmp-naming,
+ * cleanup, and `bestEffort` semantics.
  */
 export async function writeFileAtomicAsync(targetPath, data, options) {
     const bestEffort = options?.bestEffort ?? true;
-    const tmpPath = `${targetPath}.tmp-${process.pid}`;
+    const tmpPath = stagePathFor(targetPath);
     try {
         await fs.promises.writeFile(tmpPath, data, typeof data === "string" ? "utf-8" : undefined);
         await fs.promises.rename(tmpPath, targetPath);