iterate-plugin 2.3.7 → 2.5.0

package/src/tools/checkpoint.ts

@@ -0,0 +1,285 @@
+/**
+ * src/tools/checkpoint.ts — iteration checkpoint + status tools.
+ *
+ *   iterate_checkpoint — save / load / clear a resume checkpoint so a long
+ *                        iteration can continue where it left off.
+ *   iterate_status     — summarize the current iteration state from the
+ *                        decision log, fix registry, and checkpoint.
+ *
+ * Checkpoint layout: `.iterate/checkpoint.json`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import { resolveProjectRoot } from '../config-loader.ts'
+import { checkpointPath, iterateDir } from '../paths.ts'
+import { readRegistry } from './fix.ts'
+import { readDecisionEntries } from './decision-log.ts'
+import type { IterationCheckpoint, IterationStatus } from '../types.ts'
+
+// ─── Pure helpers (exported for unit tests) ─────────────────────────────────
+
+/** Read a checkpoint from disk (missing/corrupt → null). */
+export function readCheckpoint(projectRoot: string): IterationCheckpoint | null {
+  const file = checkpointPath(projectRoot)
+  if (!existsSync(file)) return null
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf-8')) as IterationCheckpoint
+    if (!parsed || typeof parsed !== 'object') return null
+    if (parsed.mode !== 'dry-run' && parsed.mode !== 'normal') return null
+    if (typeof parsed.round !== 'number') return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+/** Validate a checkpoint payload (returns error string or null). */
+export function validateCheckpoint(input: {
+  mode: unknown
+  round: unknown
+  maxRounds: unknown
+  fixedCount: unknown
+  architecturalCount: unknown
+}): string | null {
+  if (input.mode !== 'dry-run' && input.mode !== 'normal') {
+    return 'mode must be "dry-run" or "normal"'
+  }
+  if (typeof input.round !== 'number' || !Number.isInteger(input.round) || input.round < 0) {
+    return 'round must be a non-negative integer'
+  }
+  if (typeof input.maxRounds !== 'number' || !Number.isInteger(input.maxRounds) || input.maxRounds < 1) {
+    return 'maxRounds must be a positive integer'
+  }
+  if (typeof input.fixedCount !== 'number' || !Number.isInteger(input.fixedCount) || input.fixedCount < 0) {
+    return 'fixedCount must be a non-negative integer'
+  }
+  if (typeof input.architecturalCount !== 'number' || !Number.isInteger(input.architecturalCount) || input.architecturalCount < 0) {
+    return 'architecturalCount must be a non-negative integer'
+  }
+  return null
+}
+
+/**
+ * Compute a status summary from the runtime artifacts.
+ * Pure (no I/O) — all reads are injected, so it is unit-testable.
+ */
+export function computeStatus(input: {
+  checkpoint: IterationCheckpoint | null
+  decisionEntries: { timestamp: string; type: string; round?: number; data?: Record<string, unknown> }[]
+  fixRegistry: { rounds: { round: number; fixedCount: number; failedCount: number }[] }
+}): IterationStatus {
+  const checkpoint = input.checkpoint
+  const entries = input.decisionEntries
+  const registry = input.fixRegistry
+
+  const lastEntry = entries.length > 0 ? entries[entries.length - 1] : null
+  const lastUpdated = lastEntry?.timestamp ?? checkpoint?.updatedAt ?? null
+
+  // Round = checkpoint.round (explicit) or max round seen in the decision log.
+  let currentRound = checkpoint?.round ?? 0
+  if (!checkpoint) {
+    for (const e of entries) {
+      if (typeof e.round === 'number' && e.round > currentRound) currentRound = e.round
+    }
+  }
+
+  const totalRounds = checkpoint?.maxRounds ?? currentRound
+  const registryFixed = registry.rounds.reduce((sum, r) => sum + r.fixedCount, 0)
+  const failedCount = registry.rounds.reduce((sum, r) => sum + r.failedCount, 0)
+  // When a checkpoint exists, its snapshot fields are authoritative for resume
+  // (fixedCount / architecturalCount / findings); otherwise derive from the
+  // live fix registry and decision log.
+  const fixedCount = checkpoint ? checkpoint.fixedCount : registryFixed
+  const architecturalCount = checkpoint?.architecturalCount ?? 0
+
+  return {
+    mode: checkpoint?.mode ?? null,
+    currentRound,
+    totalRounds,
+    fixedCount,
+    architecturalCount,
+    findingsCount: checkpoint?.findings.length ?? 0,
+    totalDecisionLogEntries: entries.length,
+    hasCheckpoint: checkpoint !== null,
+    checkpoint,
+    lastUpdated,
+  }
+}
+
+// ─── iterate_checkpoint ──────────────────────────────────────────────────────
+
+/**
+ * Register the `iterate_checkpoint` tool.
+ * Saves progress so the orchestrator can resume a long iteration.
+ */
+export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_checkpoint',
+      description:
+        'Save / load / clear the iteration checkpoint. The workflow saves a checkpoint at the start of ' +
+        'each round (so a long run can resume) and clears it when the iteration completes.',
+      parameters: {
+        operation: {
+          type: 'string',
+          required: true,
+          description: '"save" to persist the current progress, "load" to read it back, "clear" to remove it.',
+          enum: ['save', 'load', 'clear'],
+        },
+        mode: { type: 'string', description: 'Required for save: "dry-run" or "normal".' },
+        round: { type: 'integer', description: 'Required for save: current round number (0 = none started).' },
+        maxRounds: { type: 'integer', description: 'Required for save: total round cap.' },
+        fixedCount: { type: 'integer', description: 'Required for save: number of fixes applied so far.' },
+        architecturalCount: { type: 'integer', description: 'Required for save: architectural findings left unfixed.' },
+        findings: { type: 'json', description: 'Optional for save: the current deduped findings to resume from.' },
+        path: { type: 'string', description: 'Project root directory (default: current working directory).' },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            operation: { type: 'string', required: true },
+            ok: { type: 'boolean', required: true },
+            checkpoint: { type: 'json' },
+            existed: { type: 'boolean' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => [
+          { type: 'text', text: JSON.stringify(value, null, 2) },
+        ],
+      },
+
+      async execute(args) {
+        const resolved = resolveProjectRoot(args.path)
+        if (!resolved.ok) return { operation: args.operation, ok: false, error: resolved.reason }
+        const projectRoot = resolved.root
+
+        if (args.operation === 'load') {
+          const checkpoint = readCheckpoint(projectRoot)
+          return { operation: 'load', ok: true, checkpoint: (checkpoint as unknown as JsonValue | null) ?? undefined }
+        }
+
+        if (args.operation === 'clear') {
+          const existed = existsSync(checkpointPath(projectRoot))
+          if (existed) {
+            try { rmSync(checkpointPath(projectRoot), { force: true }) } catch (err) {
+              return { operation: 'clear', ok: false, existed, error: `failed to clear checkpoint: ${String(err)}` }
+            }
+          }
+          return { operation: 'clear', ok: true, existed }
+        }
+
+        if (args.operation === 'save') {
+          const invalid = validateCheckpoint({
+            mode: args.mode,
+            round: args.round,
+            maxRounds: args.maxRounds,
+            fixedCount: args.fixedCount,
+            architecturalCount: args.architecturalCount,
+          })
+          if (invalid) return { operation: 'save', ok: false, error: invalid }
+          const checkpoint: IterationCheckpoint = {
+            mode: args.mode as 'dry-run' | 'normal',
+            round: args.round as number,
+            maxRounds: args.maxRounds as number,
+            fixedCount: args.fixedCount as number,
+            architecturalCount: args.architecturalCount as number,
+            findings: (Array.isArray(args.findings) ? args.findings : []) as unknown as IterationCheckpoint['findings'],
+            startedAt: readCheckpoint(projectRoot)?.startedAt ?? new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+          }
+          try {
+            mkdirSync(iterateDir(projectRoot), { recursive: true })
+            writeFileSync(checkpointPath(projectRoot), JSON.stringify(checkpoint, null, 2), 'utf-8')
+          } catch (err) {
+            return { operation: 'save', ok: false, error: `failed to write checkpoint: ${String(err)}` }
+          }
+          return { operation: 'save', ok: true, checkpoint: checkpoint as unknown as JsonValue }
+        }
+
+        return { operation: args.operation, ok: false, error: 'unknown operation. Use "save", "load", or "clear".' }
+      },
+    }),
+  )
+}
+
+// ─── iterate_status ──────────────────────────────────────────────────────────
+
+/**
+ * Register the `iterate_status` tool.
+ * Summarizes the current iteration state (mode, round, fixed count, findings).
+ */
+export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_status',
+      description:
+        'Summarize the current iterate run: mode, current round vs total, fixes applied, architectural ' +
+        'findings remaining, decision-log size, and whether a resume checkpoint exists.',
+      parameters: {
+        path: { type: 'string', description: 'Project root directory (default: current working directory).' },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean', required: true },
+            mode: { type: 'string' },
+            currentRound: { type: 'integer' },
+            totalRounds: { type: 'integer' },
+            fixedCount: { type: 'integer' },
+            architecturalCount: { type: 'integer' },
+            findingsCount: { type: 'integer' },
+            totalDecisionLogEntries: { type: 'integer' },
+            hasCheckpoint: { type: 'boolean' },
+            lastUpdated: { type: 'string' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (!value.ok) return [{ type: 'text', text: `status failed: ${value.error}` }]
+          const lines = [
+            `Mode: ${value.mode ?? 'none'}`,
+            `Round: ${value.currentRound} / ${value.totalRounds}`,
+            `Fixed: ${value.fixedCount} · Architectural remaining: ${value.architecturalCount}`,
+            `Findings in checkpoint: ${value.findingsCount}`,
+            `Decision-log entries: ${value.totalDecisionLogEntries}`,
+            `Checkpoint: ${value.hasCheckpoint ? 'yes' : 'no'}`,
+            value.lastUpdated ? `Last updated: ${value.lastUpdated}` : '',
+          ]
+          return [{ type: 'text', text: lines.filter(Boolean).join('\n') }]
+        },
+      },
+
+      async execute(args) {
+        const resolved = resolveProjectRoot(args.path)
+        if (!resolved.ok) return { ok: false, error: resolved.reason }
+        const projectRoot = resolved.root
+        const status = computeStatus({
+          checkpoint: readCheckpoint(projectRoot),
+          decisionEntries: readDecisionEntries(projectRoot),
+          fixRegistry: readRegistry(projectRoot),
+        })
+        return {
+          ok: true,
+          mode: status.mode ?? undefined,
+          currentRound: status.currentRound,
+          totalRounds: status.totalRounds,
+          fixedCount: status.fixedCount,
+          architecturalCount: status.architecturalCount,
+          findingsCount: status.findingsCount,
+          totalDecisionLogEntries: status.totalDecisionLogEntries,
+          hasCheckpoint: status.hasCheckpoint,
+          lastUpdated: status.lastUpdated ?? undefined,
+        }
+      },
+    }),
+  )
+}

package/src/tools/config.ts

@@ -1,10 +1,18 @@
+import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { loadEffectiveConfig, validateConfig, resolveProjectRoot } from '../config-loader.ts'
+import {
+  applyConfigUpdates,
+  readRawConfig,
+  validateConfigUpdates,
+  writeConfigFile,
+} from '../config-write.ts'
 
 /**
  * Register the `iterate_config` tool.
- * Reads and returns the iterate.config.yaml configuration.
+ * Reads and returns the iterate.config.yaml configuration, or writes a
+ * validated partial update back to it (with backup + rollback).
  * Model-facing: returns JSON with the full config, a specific section, or validation errors.
  */
 export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
@@ -12,11 +20,17 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
     defineTool({
       name: 'iterate_config',
       description:
-        'Read the iterate.config.yaml configuration from the project root. ' +
+        'Read or update the iterate.config.yaml configuration from the project root. ' +
         'Returns the full parsed config, a specific section, or validation errors. ' +
-        'Use this to discover available dimensions, validation commands, git settings, and personalization rules.',
+        'Use this to discover available dimensions, validation commands, git settings, and personalization rules, ' +
+        'or to write back validated changes (goal, dimensions, max_rounds, review, atomic, validation, git, etc.).',
 
       parameters: {
+        operation: {
+          type: 'string',
+          description: 'Default "read". "write" validates and applies a partial config update (backed up first).',
+          enum: ['read', 'write'],
+        },
         path: {
           type: 'string',
           description: 'Project root directory (default: current working directory).',
@@ -30,6 +44,13 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
           type: 'boolean',
           description: 'If true, validate the config schema and return any missing fields.',
         },
+        updates: {
+          type: 'json',
+          description:
+            'For operation "write": a partial config object to merge in, e.g. ' +
+            '{"goal":"...","dimensions":["correctness","security"],"max_rounds":5}. ' +
+            'Supported keys: goal, language, dimensions, max_rounds, review, atomic, git, validation, personalization, onboarding.',
+        },
       },
 
       output: {
@@ -44,6 +65,9 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
             data: { type: 'json' },
             config: { type: 'json' },
             availableSections: { type: 'array', items: { type: 'string' } },
+            operation: { type: 'string' },
+            ok: { type: 'boolean' },
+            backupPath: { type: 'string' },
             error: { type: 'string' },
           },
         },
@@ -58,9 +82,43 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
           return { found: false, error: resolved.reason }
         }
         const projectRoot = resolved.root
-        // Effective config = defaults (Master) merged with any project-root
-        // overrides. Never null: a project without a config file runs on the
-        // built-in defaults, so the workflow stays usable out of the box.
+
+        // ── Write operation ────────────────────────────────────────────────
+        if (args.operation === 'write') {
+          const updates = args.updates as Record<string, unknown> | undefined
+          const updateErrors = validateConfigUpdates(updates ?? {})
+          if (updateErrors.length > 0) {
+            return { operation: 'write', ok: false, found: false, errors: updateErrors }
+          }
+          let base: Record<string, unknown>
+          try {
+            base = readRawConfig(join(projectRoot, 'iterate.config.yaml'))
+          } catch (err) {
+            return { operation: 'write', ok: false, found: false, error: `failed to read config: ${String(err)}` }
+          }
+          const merged = applyConfigUpdates(base, updates ?? {})
+          const schemaErrors = validateConfig(merged)
+          if (schemaErrors.length > 0) {
+            return {
+              operation: 'write',
+              ok: false,
+              found: false,
+              errors: schemaErrors.map((e) => `missing/required field: ${e}`),
+            }
+          }
+          const result = writeConfigFile(projectRoot, merged)
+          if (!result.ok) return { operation: 'write', ok: false, found: false, error: result.error }
+          const { config } = loadEffectiveConfig(projectRoot)
+          return {
+            operation: 'write',
+            ok: true,
+            found: true,
+            backupPath: result.backupPath ?? undefined,
+            config: config as unknown as JsonValue,
+          }
+        }
+
+        // ── Read operations (original behavior) ────────────────────────────
         const { config, source } = loadEffectiveConfig(projectRoot)
         const hasOverride = source === 'override'
 

package/src/tools/decision-log.ts

@@ -23,7 +23,7 @@ function logPath(projectRoot: string): string {
  * Append one entry to the decision log (JSONL format).
  * Returns the entry count after appending.
  */
-function appendEntry(projectRoot: string, entry: DecisionLogEntry): { count: number; path: string } {
+export function appendDecisionEntry(projectRoot: string, entry: DecisionLogEntry): { count: number; path: string } {
   const filePath = logPath(projectRoot)
   const line = JSON.stringify(entry) + '\n'
   appendFileSync(filePath, line, 'utf-8')
@@ -41,7 +41,7 @@ function appendEntry(projectRoot: string, entry: DecisionLogEntry): { count: num
 /**
  * Read all entries from the decision log.
  */
-function readEntries(projectRoot: string): DecisionLogEntry[] {
+export function readDecisionEntries(projectRoot: string): DecisionLogEntry[] {
   const filePath = join(projectRoot, LOG_DIR, LOG_FILE)
   if (!existsSync(filePath)) return []
   try {
@@ -82,6 +82,16 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
           description:
             'Entry type (required for append): round_start, review_result, atomic_fix, ' +
             'architectural_fix, revert, validation, decision, report.',
+          enum: [
+            'round_start',
+            'review_result',
+            'atomic_fix',
+            'architectural_fix',
+            'revert',
+            'validation',
+            'decision',
+            'report',
+          ],
         },
         round: {
           type: 'integer',
@@ -124,7 +134,7 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
         const projectRoot = resolved.root
 
         if (args.operation === 'read') {
-          const entries = readEntries(projectRoot)
+          const entries = readDecisionEntries(projectRoot)
           return {
             operation: 'read',
             entryCount: entries.length,
@@ -148,7 +158,7 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
             data: (args.data as Record<string, unknown>) ?? {},
           }
 
-          const result = appendEntry(projectRoot, entry)
+          const result = appendDecisionEntry(projectRoot, entry)
           return {
             operation: 'append',
             success: true,