iterate-plugin 2.4.0 → 2.6.0

package/src/tools/history.ts

@@ -0,0 +1,162 @@
+/**
+ * src/tools/history.ts — iteration history reader.
+ *
+ *   iterate_history — read the decision-log entries (with optional filters)
+ *                     plus a summary of the fix registry, so the user or the
+ *                     orchestrator can review exactly what the run did.
+ *
+ * Complements `iterate_status` (compact summary) with the actual detail.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import { resolveProjectRoot } from '../config-loader.ts'
+import { readDecisionEntries } from './decision-log.ts'
+import { readRegistry } from './fix.ts'
+import type { DecisionLogEntry, FixRegistry } from '../types.ts'
+
+const DEFAULT_LIMIT = 50
+const MAX_LIMIT = 200
+
+/** Clamp a caller-supplied `limit` to a sane range. */
+export function clampHistoryLimit(limit: number | undefined): number {
+  if (typeof limit !== 'number' || !Number.isInteger(limit) || limit <= 0) {
+    return DEFAULT_LIMIT
+  }
+  return Math.min(limit, MAX_LIMIT)
+}
+
+/**
+ * Filter + cap decision-log entries. Pure, unit-tested.
+ * Returns the newest `limit` matching entries plus the total match count
+ * (before the cap), so callers can tell when the result was truncated.
+ */
+export function filterDecisionEntries(
+  entries: DecisionLogEntry[],
+  opts: { type?: unknown; since?: unknown; limit?: unknown },
+): { entries: DecisionLogEntry[]; filteredCount: number; limit: number } {
+  const type = typeof opts.type === 'string' && opts.type ? opts.type : undefined
+  const since = typeof opts.since === 'string' && opts.since ? opts.since : undefined
+  const limit = clampHistoryLimit(opts.limit as number | undefined)
+
+  const matching = (Array.isArray(entries) ? entries : []).filter((e) => {
+    if (type && e.type !== type) return false
+    if (since && e.timestamp <= since) return false
+    return true
+  })
+  return {
+    entries: matching.slice(-limit),
+    filteredCount: matching.length,
+    limit,
+  }
+}
+
+/** Per-round fix counts + totals from a fix registry. Pure, unit-tested. */
+export function summarizeFixRegistry(registry: FixRegistry): {
+  totalFixed: number
+  totalFailed: number
+  roundCount: number
+  rounds: { round: number; fixedCount: number; failedCount: number }[]
+} {
+  const rounds = (registry.rounds ?? []).map((r) => ({
+    round: r.round,
+    fixedCount: r.fixedCount,
+    failedCount: r.failedCount,
+  }))
+  return {
+    totalFixed: rounds.reduce((s, r) => s + r.fixedCount, 0),
+    totalFailed: rounds.reduce((s, r) => s + r.failedCount, 0),
+    roundCount: rounds.length,
+    rounds,
+  }
+}
+
+/**
+ * Register the `iterate_history` tool.
+ * Reads the decision log (optionally filtered by type / since / limit) and a
+ * fix-registry summary. Read-only; never modifies the filesystem.
+ */
+export function registerHistoryTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_history',
+      description:
+        'Read the iteration history: decision-log entries (optionally filtered by entry `type`, `since` ' +
+        'timestamp, and a `limit`) plus a summary of the fix registry (per-round fixed/failed counts). ' +
+        'Read-only — use it to review what the run did, audit a log, or inspect fixes.',
+      parameters: {
+        type: {
+          type: 'string',
+          description:
+            'Optional entry-type filter: round_start, review_result, atomic_fix, architectural_fix, ' +
+            'revert, validation, decision, report.',
+        },
+        since: {
+          type: 'string',
+          description: 'Optional ISO timestamp; only entries AFTER this timestamp are returned.',
+        },
+        limit: {
+          type: 'integer',
+          description: `Max entries to return (default: ${DEFAULT_LIMIT}, cap: ${MAX_LIMIT}). Newest first.`,
+        },
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean', required: true },
+            kind: { type: 'string' },
+            count: { type: 'integer' },
+            filteredCount: { type: 'integer' },
+            limit: { type: 'integer' },
+            log: { type: 'json' },
+            fixes: { type: 'json' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (!value.ok) return [{ type: 'text', text: `history failed: ${value.error}` }]
+          const log = (value.log as DecisionLogEntry[] | undefined) ?? []
+          const fixes = (value.fixes as { totalFixed: number; totalFailed: number; roundCount: number } | undefined)
+          const lines = [
+            `Decision-log entries: ${value.count} (filtered to ${value.limit})`,
+            fixes
+              ? `Fixes: ${fixes.totalFixed} applied · ${fixes.totalFailed} failed · across ${fixes.roundCount} round(s)`
+              : 'Fixes: none',
+            '',
+            ...log.map((e) => `[${e.timestamp}] r${e.round} ${e.type}: ${JSON.stringify(e.data ?? {})}`),
+          ]
+          return [{ type: 'text', text: lines.join('\n') }]
+        },
+      },
+
+      async execute(args) {
+        const resolved = resolveProjectRoot(args.path)
+        if (!resolved.ok) return { ok: false, kind: 'history', error: resolved.reason }
+        const projectRoot = resolved.root
+
+        const { entries, filteredCount, limit } = filterDecisionEntries(
+          readDecisionEntries(projectRoot),
+          { type: args.type, since: args.since, limit: args.limit },
+        )
+        const fixes = summarizeFixRegistry(readRegistry(projectRoot))
+
+        return {
+          ok: true,
+          kind: 'history',
+          count: entries.length,
+          filteredCount,
+          limit,
+          log: entries as unknown as JsonValue,
+          fixes: fixes as unknown as JsonValue,
+        }
+      },
+    }),
+  )
+}

package/src/tools/prune.ts

@@ -0,0 +1,313 @@
+/**
+ * src/tools/prune.ts — runtime artifact cleanup for the iterate loop.
+ *
+ *   iterate_prune — inspect or remove stale runtime artifacts (.iterate/).
+ *                   Defaults to dry-run (report-only); set `dryRun: false` to
+ *                   actually delete.
+ *
+ * Artifacts managed:
+ *   - Decision-log entries older than `retainDays` (default 30, via since).
+ *   - Stale checkpoint files (checkpoint.json).
+ *   - Fix backups left over from old rounds (backups whose fix-id no longer
+ *     appears in the registry).
+ *   - Empty fix rounds (rounds with 0 records).
+ *
+ * Security model:
+ *   - Only operates under the resolved project `.iterate/` directory.
+ *   - 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 { join } from 'node:path'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import { resolveProjectRoot } from '../config-loader.ts'
+import { readDecisionEntries, appendDecisionEntry } from './decision-log.ts'
+import { readRegistry, removeRecord, recomputeRoundCounts } from './fix.ts'
+import { iterateDir, fixesDir, checkpointPath, fixRegistryPath } from '../paths.ts'
+import type { FixRegistry } from '../types.ts'
+
+/** Default retention for decision-log entries (in days). */
+const DEFAULT_RETAIN_DAYS = 30
+const MIN_RETAIN_DAYS = 1
+const MAX_RETAIN_DAYS = 365
+
+/** Clamp retainDays to a sane range. */
+export function clampRetainDays(days: number | undefined): number {
+  if (typeof days !== 'number' || !Number.isInteger(days) || days <= 0) {
+    return DEFAULT_RETAIN_DAYS
+  }
+  return Math.min(Math.max(days, MIN_RETAIN_DAYS), MAX_RETAIN_DAYS)
+}
+
+/** Build the cutoff timestamp for a given retainDays. */
+export function cutoffTimestamp(retainDays: number): string {
+  const d = new Date()
+  d.setDate(d.getDate() - retainDays)
+  return d.toISOString()
+}
+
+/**
+ * Inspect the runtime state and report what would be pruned.
+ * Pure (no deletions). Returns a structured report.
+ */
+export function inspectPrune(
+  projectRoot: string,
+  retainDays: number,
+): {
+  oldLogEntries: number
+  hasCheckpoint: boolean
+  staleBackups: string[]
+  emptyRounds: number[]
+  totalLogEntries: number
+  registryRounds: number
+} {
+  const cutoff = cutoffTimestamp(retainDays)
+
+  // 1. Decision-log entries older than retainDays.
+  const entries = readDecisionEntries(projectRoot)
+  const oldLogEntries = entries.filter((e) => e.timestamp < cutoff).length
+
+  // 2. Checkpoint presence.
+  const hasCheckpoint = existsSync(checkpointPath(projectRoot))
+
+  // 3. Stale fix backups: .bak files whose fix-id prefix is not in the registry.
+  const registry = readRegistry(projectRoot)
+  const activeIds = new Set<string>()
+  for (const r of registry.rounds) {
+    for (const rec of r.records) {
+      activeIds.add(rec.id)
+    }
+  }
+  const staleBackups: string[] = []
+  const fixDir = fixesDir(projectRoot)
+  if (existsSync(fixDir)) {
+    for (const entry of readdirSync(fixDir)) {
+      if (!entry.endsWith('.bak')) continue
+      // Extract the fix-id prefix (up to the first underscore after the id).
+      // e.g. "fix-abc123_2026-08-17T00-00-00-000Z.bak" → "fix-abc123"
+      const match = entry.match(/^(fix-[a-z0-9]+)_/)
+      const id = match?.[1]
+      if (id && !activeIds.has(id)) {
+        staleBackups.push(entry)
+      }
+    }
+  }
+
+  // 4. Empty rounds (rounds with 0 records).
+  const emptyRounds = registry.rounds
+    .filter((r) => r.records.length === 0)
+    .map((r) => r.round)
+
+  return {
+    oldLogEntries,
+    hasCheckpoint,
+    staleBackups,
+    emptyRounds,
+    totalLogEntries: entries.length,
+    registryRounds: registry.rounds.length,
+  }
+}
+
+/**
+ * Actually prune the runtime artifacts (only called when dryRun=false).
+ * Returns a detailed report of what was deleted.
+ */
+export function executePrune(
+  projectRoot: string,
+  retainDays: number,
+  report: ReturnType<typeof inspectPrune>,
+): {
+  deletedLogEntries: number
+  deletedCheckpoint: boolean
+  deletedBackups: string[]
+  trimmedEmptyRounds: number
+  errors: string[]
+} {
+  const cutoff = cutoffTimestamp(retainDays)
+  const result = {
+    deletedLogEntries: 0,
+    deletedCheckpoint: false,
+    deletedBackups: [] as string[],
+    trimmedEmptyRounds: 0,
+    errors: [] as string[],
+  }
+
+  // 1. Rewrite the decision log, keeping only recent entries.
+  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',
+      )
+    }
+  } catch (err) {
+    result.errors.push(`failed to rewrite decision log: ${String(err)}`)
+    result.deletedLogEntries = 0
+  }
+
+  // 2. Remove checkpoint.
+  if (report.hasCheckpoint) {
+    try {
+      rmSync(checkpointPath(projectRoot), { force: true })
+      result.deletedCheckpoint = true
+    } catch (err) {
+      result.errors.push(`failed to remove checkpoint: ${String(err)}`)
+    }
+  }
+
+  // 3. Delete stale backups.
+  for (const bak of report.staleBackups) {
+    try {
+      unlinkSync(join(fixesDir(projectRoot), bak))
+      result.deletedBackups.push(bak)
+    } catch (err) {
+      result.errors.push(`failed to delete backup ${bak}: ${String(err)}`)
+    }
+  }
+
+  // 4. Trim empty rounds from the registry.
+  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)
+        }
+      }
+      registry = recomputeRoundCounts(registry)
+      writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(registry, null, 2), 'utf-8')
+      result.trimmedEmptyRounds = report.emptyRounds.length
+    } catch (err) {
+      result.errors.push(`failed to trim empty rounds: ${String(err)}`)
+    }
+  }
+
+  return result
+}
+
+/**
+ * Register the `iterate_prune` tool.
+ * Defaults to dry-run: inspects the runtime state and reports what would be
+ * cleaned up. Pass `dryRun: false` to actually delete.
+ */
+export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_prune',
+      description:
+        'Inspect or clean up old iterate runtime artifacts (.iterate/). ' +
+        'Defaults to dry-run (report-only, no deletion). Pass `dryRun: false` to actually prune. ' +
+        'Manages: old decision-log entries, stale checkpoints, orphaned fix backups, empty fix rounds. ' +
+        'Each deletion is logged to the decision log.',
+      parameters: {
+        dryRun: {
+          type: 'boolean',
+          description: 'When true (default), only report what would be pruned without deleting anything.',
+        },
+        retainDays: {
+          type: 'integer',
+          description: `Keep entries newer than this many days (default: ${DEFAULT_RETAIN_DAYS}, range: ${MIN_RETAIN_DAYS}-${MAX_RETAIN_DAYS}).`,
+        },
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean', required: true },
+            dryRun: { type: 'boolean', required: true },
+            retainDays: { type: 'integer' },
+            report: { type: 'json' },
+            result: { type: 'json' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (!value.ok) return [{ type: 'text', text: `prune failed: ${value.error}` }]
+          const report = value.report as Record<string, unknown> | undefined
+          const result = value.result as Record<string, unknown> | undefined
+          if (value.dryRun) {
+            const lines = [
+              `[dry-run] prune report (retainDays=${value.retainDays}):`,
+              `  Decision-log entries to remove: ${report?.oldLogEntries ?? '?'} (of ${report?.totalLogEntries ?? '?'})`,
+              `  Checkpoint to delete: ${report?.hasCheckpoint ? 'yes' : 'none'}`,
+              `  Stale backups to delete: ${(report?.staleBackups as string[] | undefined)?.length ?? 0}`,
+              `  Empty rounds to trim: ${(report?.emptyRounds as number[] | undefined)?.length ?? 0}`,
+              '',
+              'Pass dryRun:false to execute the prune.',
+            ]
+            return [{ type: 'text', text: lines.join('\n') }]
+          }
+          const lines = [
+            `Prune complete (retainDays=${value.retainDays}):`,
+            `  Deleted ${result?.deletedLogEntries ?? 0} old log entries.`,
+            `  Checkpoint deleted: ${result?.deletedCheckpoint ? 'yes' : 'no'}`,
+            `  Deleted ${(result?.deletedBackups as string[] | undefined)?.length ?? 0} stale backups.`,
+            `  Trimmed ${result?.trimmedEmptyRounds ?? 0} empty rounds.`,
+          ]
+          const errs = (result?.errors as string[] | undefined) ?? []
+          if (errs.length > 0) {
+            lines.push('', '  Warnings:')
+            for (const e of errs) lines.push(`    - ${e}`)
+          }
+          return [{ type: 'text', text: lines.join('\n') }]
+        },
+      },
+
+      async execute(args) {
+        const resolved = resolveProjectRoot(args.path)
+        if (!resolved.ok) return { ok: false, dryRun: true, error: resolved.reason }
+        const projectRoot = resolved.root
+        const retainDays = clampRetainDays(args.retainDays as number | undefined)
+        const dryRun = args.dryRun !== false
+
+        const report = inspectPrune(projectRoot, retainDays)
+
+        if (dryRun) {
+          return {
+            ok: true,
+            dryRun: true,
+            retainDays,
+            report: report as unknown as JsonValue,
+          }
+        }
+
+        const result = executePrune(projectRoot, retainDays, report)
+
+        // Log the prune to the decision log.
+        appendDecisionEntry(projectRoot, {
+          timestamp: new Date().toISOString(),
+          round: 0,
+          type: 'decision',
+          data: {
+            action: 'prune',
+            retainDays,
+            deletedLogEntries: result.deletedLogEntries,
+            deletedCheckpoint: result.deletedCheckpoint,
+            deletedBackups: result.deletedBackups.length,
+            trimmedEmptyRounds: result.trimmedEmptyRounds,
+          },
+        })
+
+        return {
+          ok: true,
+          dryRun: false,
+          retainDays,
+          report: report as unknown as JsonValue,
+          result: result as unknown as JsonValue,
+        }
+      },
+    }),
+  )
+}

package/src/tools/triage.ts

@@ -12,6 +12,9 @@ const CONFIG_FILE = 'iterate.config.yaml'
 const PERSONALIZATION_KEY = 'personalization'
 const KNOWN_INTENTIONAL_KEY = 'known_intentional'
 
+/** Max entries per single `apply` call. */
+const MAX_ENTRIES = 500
+
 /** Whole-file marker line (matches review.ts filterKnownIntentional semantics). */
 const WHOLE_FILE_LINE = 0
 
@@ -45,6 +48,10 @@ export function validateTriageEntries(entries: unknown): string[] {
     errors.push('entries must be an array')
     return errors
   }
+  if (entries.length > MAX_ENTRIES) {
+    errors.push(`entries must not exceed ${MAX_ENTRIES} items (got ${entries.length})`)
+    return errors
+  }
   for (let i = 0; i < entries.length; i++) {
     const prefix = `entries[${i}]`
     const e = entries[i]

package/src/types.ts

@@ -97,4 +97,68 @@ export interface KnownIntentional {
   line?: number
   dimension: string
   reason: string
+}
+
+/** ─── Fix system ──────────────────────────────────────────────────────────── */
+
+/** A single fix record: one finding → one fix operation on one file. */
+export interface FixRecord {
+  id: string
+  timestamp: string
+  round: number
+  finding: ReviewFinding
+  backupPath: string
+  diffSummary: string
+  linesAdded: number
+  linesRemoved: number
+  success: boolean
+  error?: string
+}
+
+/** Fix registry metadata (per-round summary). */
+export interface FixRegistry {
+  rounds: FixRoundRecord[]
+}
+export interface FixRoundRecord {
+  round: number
+  fixedCount: number
+  failedCount: number
+  records: FixRecord[]
+}
+
+/** Hunk-level diff for a single file. */
+export interface FileDiffHunk {
+  oldStart: number
+  oldLines: number
+  newStart: number
+  newLines: number
+  content: string
+}
+
+/** ─── Checkpoint / resume ─────────────────────────────────────────────────── */
+
+export interface IterationCheckpoint {
+  mode: 'dry-run' | 'normal'
+  round: number
+  maxRounds: number
+  fixedCount: number
+  architecturalCount: number
+  findings: ReviewFinding[]
+  startedAt: string
+  updatedAt: string
+}
+
+/** ─── Status summary ──────────────────────────────────────────────────────── */
+
+export interface IterationStatus {
+  mode: 'dry-run' | 'normal' | null
+  currentRound: number
+  totalRounds: number
+  fixedCount: number
+  architecturalCount: number
+  findingsCount: number
+  totalDecisionLogEntries: number
+  hasCheckpoint: boolean
+  checkpoint: IterationCheckpoint | null
+  lastUpdated: string | null
 }