iterate-plugin 3.11.0 → 3.13.0

package/src/tools/preflight.ts

@@ -0,0 +1,337 @@
+/**
+ * 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 type { JsonValue } from '@deepseek-ai/dsh-util-values'
+import { resolveProjectRootForExec, loadEffectiveConfig, flattenCommands } from '../config-loader.ts'
+import { runGit } from '../git-scope.ts'
+import { readQualityGate } from './quality-store.ts'
+import { readCheckpoint, computeStatus } from './checkpoint.ts'
+import { readDecisionEntries } from './decision-log.ts'
+import { readRegistry } from './fix.ts'
+import { resultHeadline } from './present.ts'
+import { detectValidationCommands } from '../validation-detect.ts'
+
+/** A single check's outcome. `fail` blocks a clean run; `warn` is advisory. */
+export type PreflightStatus = 'pass' | 'warn' | 'fail'
+
+/** One readiness check. `detail` is structured facts (no prose) so the client
+ *  can localize the message and offer the right fix action. */
+export interface PreflightCheck {
+  /** Stable id the client maps to a localized label + fix action. */
+  id: string
+  status: PreflightStatus
+  detail: Record<string, unknown>
+}
+
+/** The full preflight report. */
+export interface PreflightReport {
+  ok: boolean
+  /** True when no check is `fail` (warnings do not block). */
+  ready: boolean
+  /** Count of `fail` checks. */
+  blocking: number
+  /** Count of `warn` checks. */
+  warnings: number
+  checks: PreflightCheck[]
+  error?: string
+}
+
+/** Facts gathered from disk/git before the pure decision runs. */
+export interface PreflightInput {
+  /** Number of configured validation commands (flattened across modules). */
+  validationCommandCount: number
+  /** Whether the project root is inside a git work tree. */
+  isGitRepo: boolean
+  /** Uncommitted/untracked file count, or null when git could not answer. */
+  changedFiles: number | null
+  /** Persisted quality-gate overall status, or null when none is stored. */
+  gateOverallStatus: 'pass' | 'fail' | 'pending' | null
+  /** True when a leftover checkpoint is genuinely interrupted (nothing newer). */
+  interrupted: boolean
+  /** How many times the leftover checkpoint has already been resumed. */
+  resumeCount: number
+  /** Commands auto-detected from the project manifest (only when none are configured). */
+  suggestedCommands?: string[]
+  /** Ecosystem that produced the suggestions (node/python/rust/go/make). */
+  ecosystem?: string | null
+  /** Manifest files the suggestions were derived from. */
+  detectedFrom?: string[]
+}
+
+/**
+ * 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: PreflightInput): PreflightReport {
+  const suggestions = Array.isArray(input.suggestedCommands) ? input.suggestedCommands.filter((c) => typeof c === 'string' && c.length > 0) : []
+  const checks: PreflightCheck[] = [
+    {
+      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: string, detail: Record<string, unknown>): string {
+  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: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  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 as { id?: unknown; status?: unknown; detail?: Record<string, unknown> }
+            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: [] as unknown as JsonValue, 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: string[] = []
+        let detectedEcosystem: string | null = null
+        let detectedFrom: string[] = []
+        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: number | null = 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: 'pass' | 'fail' | 'pending' | null = 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 as unknown as JsonValue }
+      },
+    }),
+  )
+}

package/src/validation-detect.ts

@@ -0,0 +1,207 @@
+/**
+ * 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'
+
+/** Ecosystems this module knows how to read a manifest for. */
+export type Ecosystem = 'node' | 'python' | 'rust' | 'go' | 'make'
+
+/** One manifest fact that produced a command. */
+export interface DetectionSource {
+  /** Manifest file, relative to the project root. */
+  file: string
+  /** Short machine-stable reason, e.g. `scripts.test`. */
+  reason: string
+}
+
+/** The result of inspecting a project root. */
+export interface ValidationDetection {
+  /** The ecosystem that produced the first command, or null when none matched. */
+  ecosystem: Ecosystem | null
+  /** Ordered, de-duplicated commands for `validation.commands.default`. */
+  commands: string[]
+  /** One entry per command, same order/length as `commands`. */
+  sources: DetectionSource[]
+}
+
+/** Hard cap so a project with many scripts cannot flood the config. */
+const MAX_COMMANDS = 6
+
+function readText(path: string): string | null {
+  try {
+    return readFileSync(path, 'utf-8')
+  } catch {
+    return null
+  }
+}
+
+function readJsonObject(path: string): Record<string, unknown> | null {
+  const text = readText(path)
+  if (text === null) return null
+  try {
+    const parsed: unknown = 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 as Record<string, unknown>)
+      : null
+  } catch {
+    return null
+  }
+}
+
+function existsFile(root: string, name: string): boolean {
+  try {
+    return existsSync(join(root, name))
+  } catch {
+    return false
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {}
+}
+
+type AddCommand = (command: string, file: string, reason: string) => void
+
+/** Node: only scripts the manifest explicitly defines, in a curated order. */
+function detectNode(root: string, add: AddCommand): boolean {
+  const pkg = readJsonObject(join(root, 'package.json'))
+  if (!pkg) return false
+  const scripts = asRecord(pkg.scripts)
+  const has = (name: string): boolean =>
+    typeof scripts[name] === 'string' && (scripts[name] as string).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: string, add: AddCommand): boolean {
+  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: string, add: AddCommand): boolean {
+  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: string, add: AddCommand): boolean {
+  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: string, add: AddCommand): boolean {
+  const makefile = ['Makefile', 'makefile', 'GNUmakefile'].find((name) => existsFile(root, name))
+  if (!makefile) return false
+  const text = readText(join(root, makefile)) ?? ''
+  const targets = new Set<string>()
+  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] as string)
+  }
+  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: string): ValidationDetection {
+  const commands: string[] = []
+  const sources: DetectionSource[] = []
+  const seen = new Set<string>()
+  const add: AddCommand = (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: Ecosystem | null = null
+  const run = (name: Ecosystem, detect: (add: AddCommand) => boolean): void => {
+    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: string[]): Record<string, unknown> {
+  return { validation: { commands: { default: [...commands] } } }
+}