iterate-plugin 2.9.4 → 2.11.0

package/dist/tools/checkpoint.js

@@ -8,7 +8,7 @@
  *
  * Checkpoint layout: `.iterate/checkpoint.json`.
  */
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
 import { checkpointPath, iterateDir } from "../paths.js";
@@ -89,7 +89,9 @@ export function computeStatus(input) {
         totalRounds,
         fixedCount,
         architecturalCount,
-        findingsCount: checkpoint?.findings.length ?? 0,
+        // A checkpoint may predate the `findings` field (or be hand-edited) — a
+        // missing findings must degrade to 0, never throw.
+        findingsCount: Array.isArray(checkpoint?.findings) ? checkpoint.findings.length : 0,
         totalDecisionLogEntries: entries.length,
         hasCheckpoint: checkpoint !== null,
         // A checkpoint left on disk means the previous run was interrupted before
@@ -187,7 +189,12 @@ export function registerCheckpointTool(ctx) {
                 };
                 try {
                     mkdirSync(iterateDir(projectRoot), { recursive: true });
-                    writeFileSync(checkpointPath(projectRoot), JSON.stringify(checkpoint, null, 2), 'utf-8');
+                    // Atomic write (temp + rename): a crash mid-write must not corrupt
+                    // the checkpoint and silently lose the interruption state.
+                    const cpPath = checkpointPath(projectRoot);
+                    const tmpPath = `${cpPath}.tmp-${Date.now()}`;
+                    writeFileSync(tmpPath, JSON.stringify(checkpoint, null, 2), 'utf-8');
+                    renameSync(tmpPath, cpPath);
                 }
                 catch (err) {
                     return { operation: 'save', ok: false, error: `failed to write checkpoint: ${String(err)}` };

package/dist/tools/context.js

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, statSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { defineTool } from '@deepseek-ai/dsh-tools';
@@ -241,7 +241,8 @@ export function registerContextTool(ctx) {
                 return { found: false, error: resolved.reason, searched: [] };
             }
             const projectRoot = resolved.root;
-            const requested = (args.files ?? '')
+            // Guard: `files` must be a comma-separated string (model-controlled).
+            const requested = (typeof args.files === 'string' ? args.files : '')
                 .split(',')
                 .map((s) => s.trim().toLowerCase())
                 .filter(Boolean);
@@ -262,8 +263,19 @@ export function registerContextTool(ctx) {
                 // are all supported.
                 const skillRoot = findSkillRoot(PLUGIN_SRC_DIR);
                 const candidates = [];
-                if (args.skillDir)
-                    candidates.push(args.skillDir);
+                // skillDir is a model-controlled path; only honor it when it is an
+                // existing directory (resolve it first) — otherwise fall through to
+                // the auto-detected root / project root.
+                if (typeof args.skillDir === 'string' && args.skillDir.trim()) {
+                    try {
+                        const dir = resolve(args.skillDir);
+                        if (existsSync(dir) && statSync(dir).isDirectory())
+                            candidates.push(dir);
+                    }
+                    catch {
+                        // unreadable/invalid skillDir — skip it
+                    }
+                }
                 if (skillRoot)
                     candidates.push(skillRoot);
                 candidates.push(projectRoot);

package/dist/tools/decision-log.js

@@ -45,12 +45,20 @@ function logPath(projectRoot) {
 }
 /**
  * Append one entry to the decision log (JSONL format).
- * Returns the entry count after appending.
+ * Returns the entry count after appending. Never throws — a disk failure is
+ * surfaced through `error` so callers (fix/prune) can report the audit-trail
+ * miss without failing the mutation they already performed.
  */
 export function appendDecisionEntry(projectRoot, entry) {
-    const filePath = logPath(projectRoot);
-    const line = JSON.stringify(entry) + '\n';
-    appendFileSync(filePath, line, 'utf-8');
+    let filePath;
+    try {
+        filePath = logPath(projectRoot);
+        const line = JSON.stringify(entry) + '\n';
+        appendFileSync(filePath, line, 'utf-8');
+    }
+    catch (err) {
+        return { count: -1, path: join(projectRoot, LOG_DIR, LOG_FILE), error: `failed to append decision log: ${String(err)}` };
+    }
     // Count entries
     let count = 0;
     try {
@@ -64,21 +72,33 @@ export function appendDecisionEntry(projectRoot, entry) {
 }
 /**
  * Read all entries from the decision log.
+ * A single corrupt line (partial write, hand-edit) is SKIPPED, not fatal —
+ * one bad line must never empty the whole history for every reader.
  */
 export function readDecisionEntries(projectRoot) {
     const filePath = join(projectRoot, LOG_DIR, LOG_FILE);
     if (!existsSync(filePath))
         return [];
+    let content;
     try {
-        const content = readFileSync(filePath, 'utf-8');
-        return content
-            .split('\n')
-            .filter((l) => l.trim().length > 0)
-            .map((l) => JSON.parse(l));
+        content = readFileSync(filePath, 'utf-8');
     }
     catch {
         return [];
     }
+    const out = [];
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            out.push(JSON.parse(trimmed));
+        }
+        catch {
+            // skip the corrupt line, keep the rest
+        }
+    }
+    return out;
 }
 /**
  * Register the `iterate_decision_log` tool.

package/dist/tools/fix.js

@@ -16,8 +16,8 @@
  *   - Backups are written before any write, so a failure never destroys data.
  *   - Atomicity is enforced against `config.atomic.max_lines` unless `force`.
  */
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { join, sep } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { loadEffectiveConfig, resolveProjectRootForExec } from "../config-loader.js";
 import { countTouchedMethods } from "../method-scope.js";
@@ -117,6 +117,9 @@ export function readRegistry(projectRoot) {
         const parsed = JSON.parse(readFileSync(file, 'utf-8'));
         if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.rounds))
             return emptyRegistry();
+        // Defensive: a hand-edited or partially-written registry may contain a
+        // round without a `records` array — normalize instead of crashing readers.
+        parsed.rounds = parsed.rounds.filter((r) => r && typeof r === 'object' && Array.isArray(r.records));
         return parsed;
     }
     catch {
@@ -191,9 +194,64 @@ export function resolveProjectFile(projectRoot, file) {
     if (resolved === projectRoot || !resolved.startsWith(projectRoot + '/') && !resolved.startsWith(projectRoot + '\\')) {
         return { ok: false, reason: 'file resolves outside the project root' };
     }
+    // Symlink containment: the lexical prefix check above does not resolve
+    // symlinks. If the target exists, verify its REAL path stays inside the REAL
+    // project root so a symlinked directory/file inside the repo can never route
+    // a fix (write/rollback/diff) outside the project.
+    if (existsSync(resolved)) {
+        let rootReal;
+        let real;
+        try {
+            rootReal = realpathSync(projectRoot);
+            real = realpathSync(resolved);
+        }
+        catch {
+            return { ok: false, reason: 'failed to resolve real path for containment check' };
+        }
+        const rootPrefix = rootReal.endsWith(sep) ? rootReal : rootReal + sep;
+        if (real !== rootReal && !real.startsWith(rootPrefix)) {
+            return { ok: false, reason: 'file resolves outside the project root (symlink escape)' };
+        }
+    }
     return { ok: true, resolved };
 }
 // ─── Shared execute helpers ──────────────────────────────────────────────────
+/**
+ * Minimal glob matcher for personalization.protected_paths.
+ * Supports `*` (any run of chars within one segment) and `**` (any chars,
+ * including separators). All other characters are literal. Pure, unit-testable.
+ */
+export function globMatch(path, pattern) {
+    if (typeof path !== 'string' || typeof pattern !== 'string')
+        return false;
+    // Escape regex specials except our two wildcards.
+    let re = '';
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === '*') {
+            const isDouble = pattern[i + 1] === '*';
+            if (isDouble) {
+                re += '[\\s\\S]*';
+                i++;
+            }
+            else {
+                re += '[^/\\\\]*';
+            }
+        }
+        else if ('.[]{}()+-^$|?'.includes(ch)) {
+            re += '\\' + ch;
+        }
+        else {
+            re += ch;
+        }
+    }
+    try {
+        return new RegExp('^' + re + '$').test(path);
+    }
+    catch {
+        return false;
+    }
+}
 /** Read the current content of a file under the project root. */
 function readProjectFile(projectRoot, file) {
     const resolved = resolveProjectFile(projectRoot, file);
@@ -304,6 +362,28 @@ export function registerFixTool(ctx) {
             if (typeof finding.dimension !== 'string' || finding.dimension.trim().length === 0) {
                 return { ok: false, error: 'finding.dimension must be a non-empty string' };
             }
+            // The finding must reference the file being fixed — the fix id and the
+            // rollback/diff target are derived from finding.file, so a mismatch
+            // would back up/restore the WRONG file.
+            if (finding.file !== file) {
+                return { ok: false, error: `finding.file ("${finding.file}") must match the file being fixed ("${file}")` };
+            }
+            // Full finding validation, mirroring the review schema: malformed
+            // findings would produce lossy registry/log entries and a degraded id.
+            const SEVERITY_SET = new Set(['critical', 'high', 'medium', 'low']);
+            if (!SEVERITY_SET.has(finding.severity)) {
+                return { ok: false, error: 'finding.severity must be one of critical/high/medium/low' };
+            }
+            if (typeof finding.summary !== 'string' || finding.summary.trim().length === 0) {
+                return { ok: false, error: 'finding.summary must be a non-empty string' };
+            }
+            if (typeof finding.is_atomic !== 'boolean') {
+                return { ok: false, error: 'finding.is_atomic must be a boolean' };
+            }
+            if (finding.line !== undefined && finding.line !== null &&
+                (typeof finding.line !== 'number' || !Number.isInteger(finding.line) || finding.line < 0)) {
+                return { ok: false, error: 'finding.line must be a non-negative integer (0 = whole-file)' };
+            }
             const current = readProjectFile(projectRoot, file);
             if (!current.ok)
                 return { ok: false, error: current.reason };
@@ -332,6 +412,27 @@ export function registerFixTool(ctx) {
             const target = resolveProjectFile(projectRoot, file);
             if (!target.ok)
                 return { ok: false, error: target.reason };
+            // Personalization guards (SKILL.md Phase 2): protected_paths veto the
+            // fix outright; forbidden_fixes veto fix approaches appearing in the
+            // new content. Both are security-relevant, so they are enforced here
+            // in the tool, not left to the model.
+            const pers = config.personalization;
+            const protectedPaths = Array.isArray(pers?.protected_paths)
+                ? pers.protected_paths.filter((p) => typeof p === 'string' && p.length > 0)
+                : [];
+            for (const pattern of protectedPaths) {
+                if (globMatch(file, pattern)) {
+                    return { ok: false, error: `skipped: ${file} matches protected path "${pattern}" (personalization.protected_paths forbids modifying it)` };
+                }
+            }
+            const forbiddenFixes = Array.isArray(pers?.forbidden_fixes)
+                ? pers.forbidden_fixes.filter((f) => typeof f === 'string' && f.length > 0)
+                : [];
+            for (const forbidden of forbiddenFixes) {
+                if (args.content.includes(forbidden)) {
+                    return { ok: false, error: `fix uses a forbidden approach: "${forbidden}" appears in the new content (personalization.forbidden_fixes)` };
+                }
+            }
             const timestamp = new Date().toISOString();
             const backupPath = fixBackupPath(projectRoot, id, timestamp);
             try {
@@ -363,7 +464,20 @@ export function registerFixTool(ctx) {
                 writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(nextRegistry, null, 2), 'utf-8');
             }
             catch (err) {
-                return { ok: false, error: `failed to write fix registry: ${String(err)}` };
+                // Registry write failed → the file was already modified but no record
+                // exists, so a later rollback/diff could never see it and a retry would
+                // back up the already-fixed content as "original". Restore the file
+                // from the backup to leave the tree exactly as it was.
+                try {
+                    copyFileSync(backupPath, target.resolved);
+                }
+                catch (restoreErr) {
+                    return {
+                        ok: false,
+                        error: `failed to write fix registry: ${String(err)}; additionally failed to restore ${file} from backup: ${String(restoreErr)}`,
+                    };
+                }
+                return { ok: false, error: `failed to write fix registry: ${String(err)} (file restored from backup)` };
             }
             appendDecisionEntry(projectRoot, {
                 timestamp,
@@ -467,6 +581,9 @@ export function registerDiffTool(ctx) {
                     if (existing) {
                         existing.linesAdded += r.linesAdded;
                         existing.linesRemoved += r.linesRemoved;
+                        // Recompute the summary from the summed counts so a multi-fix
+                        // file's text does not contradict its accumulated numbers.
+                        existing.diffSummary = `+${existing.linesAdded}/-${existing.linesRemoved} lines`;
                     }
                     else {
                         files.push({

package/dist/tools/prune.js

@@ -17,12 +17,12 @@
  *   - dryRun=true by default — the caller must explicitly opt into deletion.
  *   - Each deletion is logged to the decision log (when not dry-run).
  */
-import { existsSync, readdirSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
 import { readDecisionEntries, appendDecisionEntry } from "./decision-log.js";
-import { readRegistry, removeRecord, recomputeRoundCounts } from "./fix.js";
+import { readRegistry, recomputeRoundCounts } from "./fix.js";
 import { iterateDir, fixesDir, checkpointPath, fixRegistryPath } from "../paths.js";
 /** Default retention for decision-log entries (in days). */
 const DEFAULT_RETAIN_DAYS = 30;
@@ -101,13 +101,17 @@ export function executePrune(projectRoot, retainDays, report) {
         trimmedEmptyRounds: 0,
         errors: [],
     };
-    // 1. Rewrite the decision log, keeping only recent entries.
+    // 1. Rewrite the decision log, keeping only recent entries. Atomic
+    // (temp + rename) so a crash mid-write can never truncate the log.
     try {
         const entries = readDecisionEntries(projectRoot);
         const kept = entries.filter((e) => e.timestamp >= cutoff);
         result.deletedLogEntries = entries.length - kept.length;
         if (result.deletedLogEntries > 0) {
-            writeFileSync(join(iterateDir(projectRoot), 'decision-log.jsonl'), kept.map((e) => JSON.stringify(e)).join('\n') + '\n', 'utf-8');
+            const logPath = join(iterateDir(projectRoot), 'decision-log.jsonl');
+            const tmpPath = `${logPath}.tmp-${Date.now()}`;
+            writeFileSync(tmpPath, kept.map((e) => JSON.stringify(e)).join('\n') + '\n', 'utf-8');
+            renameSync(tmpPath, logPath);
         }
     }
     catch (err) {
@@ -138,11 +142,14 @@ export function executePrune(projectRoot, retainDays, report) {
     if (report.emptyRounds.length > 0) {
         try {
             let registry = readRegistry(projectRoot);
-            for (const round of report.emptyRounds) {
-                for (const rec of [...registry.rounds.find((r) => r.round === round)?.records ?? []]) {
-                    registry = removeRecord(registry, rec.id);
-                }
-            }
+            const emptyRoundNos = new Set(report.emptyRounds);
+            // Drop whole empty rounds (records.length === 0) instead of only
+            // removing their records — an empty round has no records to remove, so
+            // the old loop was a no-op that still reported trimmedEmptyRounds.
+            registry = {
+                ...registry,
+                rounds: registry.rounds.filter((r) => !emptyRoundNos.has(r.round) || (r.records?.length ?? 0) > 0),
+            };
             registry = recomputeRoundCounts(registry);
             writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(registry, null, 2), 'utf-8');
             result.trimmedEmptyRounds = report.emptyRounds.length;

package/dist/tools/review.js

@@ -145,7 +145,10 @@ export function registerReviewTool(ctx) {
                     .map((r) => {
                     const rr = r;
                     const findings = Array.isArray(rr?.findings) ? rr.findings : [];
-                    return { round: typeof rr?.round === 'number' ? rr.round : 0, findings };
+                    const readFiles = Array.isArray(rr?.readFiles)
+                        ? rr.readFiles.filter((f) => typeof f === 'string')
+                        : [];
+                    return { round: typeof rr?.round === 'number' ? rr.round : 0, findings, readFiles };
                 })
                     .filter((r) => r.round > 0);
                 if (rounds.length === 0) {

package/dist/tools/triage.js

@@ -1,4 +1,4 @@
-import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import yaml from 'js-yaml';
@@ -194,19 +194,22 @@ function applyEntries(projectRoot, incoming) {
         writeFileSync(configPath, yamlText, 'utf-8');
     }
     catch (err) {
-        // Rollback: restore the backup (or delete the file we just created).
+        // Rollback: restore the backup, or REMOVE the file we just created when
+        // there was no prior config — an empty file left behind would poison all
+        // future config reads (empty YAML is not a valid mapping).
+        let rollbackError = '';
         try {
             if (backupPath)
                 copyFileSync(backupPath, configPath);
             else if (existsSync(configPath))
-                writeFileSync(configPath, '', 'utf-8');
+                rmSync(configPath, { force: true });
         }
-        catch {
-            // Rollback failure is reported, not swallowed silently.
+        catch (rbErr) {
+            rollbackError = `; rollback also failed: ${String(rbErr)}`;
         }
         return {
             ok: false,
-            error: `Failed to write config: ${String(err)}`,
+            error: `Failed to write config: ${String(err)}${rollbackError}`,
         };
     }
     return { ok: true, added, skipped, count: merged.length, configPath, backupPath };

package/dist/tools/validate.js

@@ -30,10 +30,13 @@ async function runCommand(command, cwd, timeoutMs) {
             env: { ...process.env, PAGER: 'cat' },
         }, (error, stdout, stderr) => {
             const durationMs = Math.round(performance.now() - start);
-            // error.code is the exit code when the command ran; error.killed means timeout
+            // error.code is the exit code when the command ran; when the binary
+            // cannot be spawned Node sets error.code to a STRING ('ENOENT' etc).
+            // Coerce to a number so the integer output schema is never violated.
+            const exitCode = typeof error?.code === 'number' ? error.code : (error ? 1 : 0);
             resolve({
                 command,
-                exitCode: error?.code ?? (error ? 1 : 0),
+                exitCode,
                 stdout: stdout ?? '',
                 stderr: stderr ?? '',
                 timedOut: error?.killed === true,