iterate-plugin 3.11.0 → 3.13.0

package/dist/tools/preflight.js

@@ -0,0 +1,280 @@
+/**
+ * src/tools/preflight.ts — `iterate_preflight` tool.
+ *
+ * Answers one question BEFORE a run starts: "is this project ready to iterate
+ * safely, and what must be fixed first?" It reads only local state (config,
+ * git, persisted artifacts, checkpoint) and returns a structured checklist the
+ * observatory renders as a preflight panel (F11).
+ *
+ * Why it exists: the most expensive failure mode is starting a run that cannot
+ * prove anything — an empty `validation.commands` means the loop has no way to
+ * tell a fix from a regression, and a stale FAIL certificate or a leftover
+ * interrupted checkpoint makes the first round lie about its starting state.
+ * Preflight surfaces those conditions before the model spends a round
+ * discovering them mid-flight.
+ *
+ * Read-only: never mutates config, files, or artifacts.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { resolveProjectRootForExec, loadEffectiveConfig, flattenCommands } from "../config-loader.js";
+import { runGit } from "../git-scope.js";
+import { readQualityGate } from "./quality-store.js";
+import { readCheckpoint, computeStatus } from "./checkpoint.js";
+import { readDecisionEntries } from "./decision-log.js";
+import { readRegistry } from "./fix.js";
+import { resultHeadline } from "./present.js";
+import { detectValidationCommands } from "../validation-detect.js";
+/**
+ * Build the readiness checklist from already-gathered facts (pure).
+ *
+ * The five checks and why each exists:
+ *   1. `validation`            — empty command set ⇒ the loop cannot prove a
+ *                                fix; the product is fail-closed here, so this
+ *                                is a BLOCKING `fail`, not a warning.
+ *   2. `git`                   — changed-only scope + `iterate_diff` need a
+ *                                repository; full-scope review still works, so
+ *                                absent is a `warn`.
+ *   3. `dirty-tree`            — a run over uncommitted work mixes the user's
+ *                                WIP with the plugin's fixes; advisory `warn`.
+ *                                Unknown (null) is treated as pass so a git
+ *                                hiccup never fabricates a warning.
+ *   4. `stale-gate`            — a persisted FAIL certificate makes the first
+ *                                round read stale; `warn` + clear before a
+ *                                fresh run.
+ *   5. `interrupted-checkpoint`— a leftover checkpoint from a run that never
+ *                                progressed; `warn` + resume or clear.
+ */
+export function buildPreflightReport(input) {
+    const suggestions = Array.isArray(input.suggestedCommands) ? input.suggestedCommands.filter((c) => typeof c === 'string' && c.length > 0) : [];
+    const checks = [
+        {
+            id: 'validation',
+            status: input.validationCommandCount > 0 ? 'pass' : 'fail',
+            detail: {
+                commandCount: input.validationCommandCount,
+                // Only meaningful when the blocking case is hit; the client turns these
+                // into a one-click "apply detected commands" action.
+                ...(input.validationCommandCount === 0 && suggestions.length > 0
+                    ? {
+                        suggestedCommands: suggestions,
+                        ecosystem: input.ecosystem ?? null,
+                        detectedFrom: Array.isArray(input.detectedFrom) ? input.detectedFrom : [],
+                    }
+                    : {}),
+            },
+        },
+        {
+            id: 'git',
+            status: input.isGitRepo ? 'pass' : 'warn',
+            detail: { isRepo: input.isGitRepo },
+        },
+        {
+            id: 'dirty-tree',
+            status: input.changedFiles !== null && input.changedFiles > 0 ? 'warn' : 'pass',
+            detail: { changedFiles: input.changedFiles },
+        },
+        {
+            id: 'stale-gate',
+            status: input.gateOverallStatus === 'fail' ? 'warn' : 'pass',
+            detail: { overallStatus: input.gateOverallStatus },
+        },
+        {
+            id: 'interrupted-checkpoint',
+            status: input.interrupted ? 'warn' : 'pass',
+            detail: { interrupted: input.interrupted, resumeCount: input.resumeCount },
+        },
+    ];
+    const blocking = checks.filter((c) => c.status === 'fail').length;
+    const warnings = checks.filter((c) => c.status === 'warn').length;
+    return { ok: true, ready: blocking === 0, blocking, warnings, checks };
+}
+/** Human-readable (English, for the model-facing render) description per check. */
+function describeCheck(id, detail) {
+    switch (id) {
+        case 'validation': {
+            const n = Number(detail.commandCount ?? 0);
+            if (n > 0)
+                return `${n} validation command(s) configured`;
+            const suggested = Array.isArray(detail.suggestedCommands)
+                ? detail.suggestedCommands.map((c) => String(c))
+                : [];
+            if (suggested.length > 0) {
+                return ('no validation.commands configured — the run cannot prove fixes (blocking); ' +
+                    `detected ${String(detail.ecosystem ?? 'project')} commands: ${suggested.join(', ')}`);
+            }
+            return 'no validation.commands configured — the run cannot prove fixes (blocking)';
+        }
+        case 'git':
+            return detail.isRepo === true
+                ? 'git repository detected'
+                : 'not a git repository — changed-only scope and iterate_diff need one';
+        case 'dirty-tree': {
+            const n = detail.changedFiles;
+            if (n === null || n === undefined)
+                return 'uncommitted changes: unknown';
+            const num = Number(n);
+            return num > 0
+                ? `${num} uncommitted/untracked file(s) — commit or stash before a run`
+                : 'working tree clean';
+        }
+        case 'stale-gate': {
+            const s = detail.overallStatus;
+            if (s === 'fail')
+                return 'a stale FAIL quality gate is persisted — clear it before a fresh run';
+            return s ? `quality gate: ${String(s)}` : 'no persisted quality gate';
+        }
+        case 'interrupted-checkpoint': {
+            if (detail.interrupted === true) {
+                const rc = Number(detail.resumeCount ?? 0);
+                return `an interrupted checkpoint is waiting (resumed ${rc}x) — resume or clear it`;
+            }
+            return 'no interrupted checkpoint';
+        }
+        default:
+            return '';
+    }
+}
+/**
+ * Register the `iterate_preflight` tool.
+ */
+export function registerPreflightTool(ctx) {
+    ctx.tools.register(defineTool({
+        name: 'iterate_preflight',
+        // Pure read of on-disk state + git → safe to join a parallel group.
+        isConcurrencySafe: () => true,
+        presentResult: (_args, result) => {
+            const title = resultHeadline(result);
+            return title ? { card: 'generic', title } : undefined;
+        },
+        description: 'Read-only readiness check to run BEFORE starting an iterate run. Returns a checklist: whether ' +
+            'validation.commands is configured (an empty set means the loop cannot prove fixes — blocking), ' +
+            'whether the project is a git repository, how many files are uncommitted, whether a stale FAIL ' +
+            'quality gate is persisted, and whether an interrupted checkpoint is waiting. Use it before a fresh ' +
+            'run so you fix the environment first instead of discovering it mid-round.',
+        parameters: {
+            path: { type: 'string', description: 'Project root directory (default: current working directory).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    ok: { type: 'boolean', required: true },
+                    ready: { type: 'boolean' },
+                    blocking: { type: 'integer' },
+                    warnings: { type: 'integer' },
+                    checks: { type: 'json', description: 'Per-check outcomes: { id, status: pass|warn|fail, detail }.' },
+                    error: { type: 'string' },
+                },
+            },
+            render: (_args, value) => {
+                if (!value.ok)
+                    return [{ type: 'text', text: `preflight failed: ${value.error}` }];
+                const checks = Array.isArray(value.checks) ? value.checks : [];
+                const warnings = Number(value.warnings ?? 0);
+                const noun = warnings === 1 ? 'warning' : 'warnings';
+                const head = value.ready
+                    ? `Preflight: READY (${Number(value.blocking ?? 0)} blocking, ${warnings} ${noun})`
+                    : `Preflight: NOT READY (${Number(value.blocking ?? 0)} blocking, ${warnings} ${noun})`;
+                const lines = checks.map((c) => {
+                    const check = c;
+                    const id = String(check.id ?? '?');
+                    const status = String(check.status ?? '?').toUpperCase();
+                    return `  ${status} ${id} — ${describeCheck(id, check.detail ?? {})}`;
+                });
+                return [{ type: 'text', text: [head, ...lines].join('\n') }];
+            },
+        },
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
+            if (!resolved.ok) {
+                return { ok: false, ready: false, blocking: 0, warnings: 0, checks: [], error: resolved.reason };
+            }
+            const projectRoot = resolved.root;
+            // 1. validation.commands — the load-bearing check.
+            let validationCommandCount = 0;
+            try {
+                const effective = loadEffectiveConfig(projectRoot);
+                validationCommandCount = flattenCommands(effective.config.validation?.commands).length;
+            }
+            catch {
+                validationCommandCount = 0;
+            }
+            // 1b. When nothing is configured, inspect the project manifest so the
+            //     blocking check ships with an actionable, ready-to-apply set.
+            let suggestedCommands = [];
+            let detectedEcosystem = null;
+            let detectedFrom = [];
+            if (validationCommandCount === 0) {
+                try {
+                    const detection = detectValidationCommands(projectRoot);
+                    suggestedCommands = detection.commands;
+                    detectedEcosystem = detection.ecosystem;
+                    detectedFrom = detection.sources.map((s) => s.file);
+                }
+                catch {
+                    suggestedCommands = [];
+                    detectedEcosystem = null;
+                    detectedFrom = [];
+                }
+            }
+            // 2/3. git repo + dirty tree (best-effort; any failure degrades to unknown).
+            let isGitRepo = false;
+            let changedFiles = null;
+            try {
+                const inside = await runGit(['rev-parse', '--is-inside-work-tree'], projectRoot, { signal: exec.signal });
+                isGitRepo = inside.ok && inside.stdout.trim() === 'true';
+                if (isGitRepo) {
+                    const status = await runGit(['status', '--porcelain', '-z'], projectRoot, { signal: exec.signal });
+                    if (status.ok) {
+                        // `-z` NUL-terminates each entry; a rename emits two NUL-separated
+                        // paths for one entry, but counting non-empty tokens is still a
+                        // faithful "there is uncommitted work" signal (>=1 when dirty).
+                        changedFiles = status.stdout.split('\u0000').filter((s) => s.length > 0).length;
+                    }
+                }
+            }
+            catch {
+                isGitRepo = false;
+                changedFiles = null;
+            }
+            // 4. stale quality gate.
+            let gateOverallStatus = null;
+            try {
+                gateOverallStatus = readQualityGate(projectRoot).overallStatus ?? null;
+            }
+            catch {
+                gateOverallStatus = null;
+            }
+            // 5. interrupted checkpoint (reuse the exact status logic so preflight
+            //    and iterate_status can never disagree about "interrupted").
+            let interrupted = false;
+            let resumeCount = 0;
+            try {
+                const status = computeStatus({
+                    checkpoint: readCheckpoint(projectRoot),
+                    decisionEntries: readDecisionEntries(projectRoot),
+                    fixRegistry: readRegistry(projectRoot),
+                });
+                interrupted = status.interrupted;
+                resumeCount = status.resumeCount;
+            }
+            catch {
+                interrupted = false;
+                resumeCount = 0;
+            }
+            const report = buildPreflightReport({
+                validationCommandCount,
+                isGitRepo,
+                changedFiles,
+                gateOverallStatus,
+                interrupted,
+                resumeCount,
+                suggestedCommands,
+                ecosystem: detectedEcosystem,
+                detectedFrom,
+            });
+            return { ...report, checks: report.checks };
+        },
+    }));
+}

package/dist/validation-detect.js

@@ -0,0 +1,193 @@
+/**
+ * src/validation-detect.ts — detect a project's validation commands.
+ *
+ * Why it exists: the iterate loop is fail-closed on `validation.commands` — an
+ * empty set means it cannot tell a fix from a regression, so `iterate_preflight`
+ * blocks the run. Until now the only remedy was to hand-write the YAML, which is
+ * error-prone (wrong nesting, wrong module key, commands the project does not
+ * actually expose). This module inspects the project's own manifest files and
+ * proposes a small, curated command set that the config tool can apply in one
+ * call.
+ *
+ * Detection is advisory and read-only: it only proposes commands the project's
+ * manifest actually advertises (package.json scripts, pytest/ruff/mypy config,
+ * Cargo, Go, Make targets). It never invents a command and never executes one.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Hard cap so a project with many scripts cannot flood the config. */
+const MAX_COMMANDS = 6;
+function readText(path) {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function readJsonObject(path) {
+    const text = readText(path);
+    if (text === null)
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        // A JSON array / scalar is not a manifest object — treat it as absent.
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function existsFile(root, name) {
+    try {
+        return existsSync(join(root, name));
+    }
+    catch {
+        return false;
+    }
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+/** Node: only scripts the manifest explicitly defines, in a curated order. */
+function detectNode(root, add) {
+    const pkg = readJsonObject(join(root, 'package.json'));
+    if (!pkg)
+        return false;
+    const scripts = asRecord(pkg.scripts);
+    const has = (name) => typeof scripts[name] === 'string' && scripts[name].trim().length > 0;
+    // test/typecheck/lint/build are the four signals that actually prove a change
+    // is sound. Arbitrary user scripts are intentionally NOT auto-run.
+    if (has('test'))
+        add('npm test', 'package.json', 'scripts.test');
+    if (has('typecheck'))
+        add('npm run typecheck', 'package.json', 'scripts.typecheck');
+    if (has('lint'))
+        add('npm run lint', 'package.json', 'scripts.lint');
+    if (has('build'))
+        add('npm run build', 'package.json', 'scripts.build');
+    return true;
+}
+/** Python: pytest plus configured ruff / mypy. A bare pyproject is not pytest. */
+function detectPython(root, add) {
+    const pyproject = readText(join(root, 'pyproject.toml'));
+    const setupCfg = readText(join(root, 'setup.cfg'));
+    const pytestIni = existsFile(root, 'pytest.ini');
+    const toxIni = existsFile(root, 'tox.ini');
+    const testsDir = existsFile(root, 'tests');
+    const pyprojectPytest = pyproject !== null && /\[tool\.pytest/.test(pyproject);
+    const setupCfgPytest = setupCfg !== null && /\[tool:pytest\]/.test(setupCfg);
+    const matched = pyproject !== null || setupCfg !== null || pytestIni || toxIni || testsDir;
+    if (!matched)
+        return false;
+    if (pytestIni)
+        add('pytest -q', 'pytest.ini', 'pytest');
+    else if (toxIni)
+        add('pytest -q', 'tox.ini', 'pytest');
+    else if (pyprojectPytest)
+        add('pytest -q', 'pyproject.toml', 'tool.pytest');
+    else if (setupCfgPytest)
+        add('pytest -q', 'setup.cfg', 'tool:pytest');
+    else if (testsDir)
+        add('pytest -q', 'tests', 'tests-dir');
+    if (pyproject !== null && /\[tool\.ruff/.test(pyproject))
+        add('ruff check .', 'pyproject.toml', 'tool.ruff');
+    if (pyproject !== null && /\[tool\.mypy\]/.test(pyproject))
+        add('mypy .', 'pyproject.toml', 'tool.mypy');
+    return true;
+}
+/** Rust: cargo test, plus clippy/rustfmt when the project configures them. */
+function detectRust(root, add) {
+    if (!existsFile(root, 'Cargo.toml'))
+        return false;
+    add('cargo test', 'Cargo.toml', 'cargo.test');
+    if (existsFile(root, 'clippy.toml') || existsFile(root, '.clippy.toml')) {
+        add('cargo clippy --all-targets -- -D warnings', 'clippy.toml', 'cargo.clippy');
+    }
+    if (existsFile(root, 'rustfmt.toml') || existsFile(root, '.rustfmt.toml')) {
+        add('cargo fmt --check', 'rustfmt.toml', 'cargo.fmt');
+    }
+    return true;
+}
+/** Go: test + vet are the two checks a go module always supports. */
+function detectGo(root, add) {
+    if (!existsFile(root, 'go.mod'))
+        return false;
+    add('go test ./...', 'go.mod', 'go.test');
+    add('go vet ./...', 'go.mod', 'go.vet');
+    return true;
+}
+/** Make: the generic fallback, only when no ecosystem-specific command exists. */
+function detectMake(root, add) {
+    const makefile = ['Makefile', 'makefile', 'GNUmakefile'].find((name) => existsFile(root, name));
+    if (!makefile)
+        return false;
+    const text = readText(join(root, makefile)) ?? '';
+    const targets = new Set();
+    for (const line of text.split(/\r?\n/)) {
+        // `target:`, but NOT a `VAR := value` / `VAR = value` assignment. The
+        // lookahead has to skip the optional space before `=` (`test := nope`).
+        const match = /^([A-Za-z0-9_.-]+)\s*:(?!=|\s*=)/.exec(line);
+        if (match)
+            targets.add(match[1]);
+    }
+    if (targets.has('test'))
+        add('make test', makefile, 'target.test');
+    if (targets.has('check'))
+        add('make check', makefile, 'target.check');
+    return true;
+}
+/**
+ * Inspect `projectRoot` and return a curated, ordered validation-command set.
+ *
+ * Never throws: unreadable or malformed manifests simply contribute nothing.
+ * The returned `commands` and `sources` always have the same length.
+ */
+export function detectValidationCommands(projectRoot) {
+    const commands = [];
+    const sources = [];
+    const seen = new Set();
+    const add = (command, file, reason) => {
+        if (commands.length >= MAX_COMMANDS)
+            return;
+        if (seen.has(command))
+            return;
+        seen.add(command);
+        commands.push(command);
+        sources.push({ file, reason });
+    };
+    let ecosystem = null;
+    const run = (name, detect) => {
+        const before = commands.length;
+        let matched = false;
+        try {
+            matched = detect(add);
+        }
+        catch {
+            matched = false;
+        }
+        if (matched && commands.length > before && ecosystem === null)
+            ecosystem = name;
+    };
+    run('node', (a) => detectNode(projectRoot, a));
+    run('python', (a) => detectPython(projectRoot, a));
+    run('rust', (a) => detectRust(projectRoot, a));
+    run('go', (a) => detectGo(projectRoot, a));
+    // Make is the generic wrapper: only consult it when nothing else produced a
+    // command, so a Makefile that just calls `npm test` does not double-report.
+    if (commands.length === 0)
+        run('make', (a) => detectMake(projectRoot, a));
+    return { ecosystem, commands, sources };
+}
+/**
+ * Build the partial config update that installs a detected command set under
+ * the `default` module. The config tool deep-merges this into an existing
+ * `validation.commands` map, so other modules are preserved.
+ */
+export function buildValidationUpdates(commands) {
+    return { validation: { commands: { default: [...commands] } } };
+}