iterate-plugin 2.12.2 → 3.2.1

package/src/tools/defense-store.ts

@@ -0,0 +1,113 @@
+/**
+ * src/tools/defense-store.ts — defense event storage layer.
+ *
+ * Provides read/write access to defense events stored in
+ * .iterate/defense-events.json. Events are accumulated during iteration.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import type { DefenseEvent, DefenseEventStream, DefenseEventType } from '../types.ts'
+
+const DEFENSE_EVENTS_FILE = 'defense-events.json'
+
+/** Valid defense event types (must stay in sync with DefenseEventType). */
+const VALID_EVENT_TYPES: ReadonlySet<DefenseEventType> = new Set<DefenseEventType>([
+  'precondition_failed',
+  'rollback',
+  'invariant_violated',
+  'assumption_falsified',
+])
+
+/**
+ * Bump the count for an event type. Unknown types (malformed JSON on disk,
+ * or a caller passing an untyped value) are ignored rather than crashing or
+ * creating garbage keys in the counts object.
+ */
+function bumpCount(counts: Record<DefenseEventType, number>, type: unknown): void {
+  if (typeof type === 'string' && VALID_EVENT_TYPES.has(type as DefenseEventType)) {
+    counts[type as DefenseEventType]++
+  }
+}
+
+/** Default empty defense event stream. */
+function emptyStream(): DefenseEventStream {
+  return {
+    events: [],
+    lastUpdated: new Date().toISOString(),
+    counts: {
+      precondition_failed: 0,
+      rollback: 0,
+      invariant_violated: 0,
+      assumption_falsified: 0,
+    },
+  }
+}
+
+/** Read the defense events stream from disk. */
+export function readDefenseEvents(projectRoot: string): DefenseEventStream {
+  const filePath = path.join(projectRoot, '.iterate', DEFENSE_EVENTS_FILE)
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8')
+    const parsed = JSON.parse(content) as DefenseEventStream
+    if (parsed && Array.isArray(parsed.events)) {
+      return parsed
+    }
+  } catch {
+    // File not found or invalid JSON
+  }
+  return emptyStream()
+}
+
+/** Write the defense events stream to disk. */
+export function writeDefenseEvents(projectRoot: string, stream: DefenseEventStream): void {
+  const dirPath = path.join(projectRoot, '.iterate')
+  const filePath = path.join(dirPath, DEFENSE_EVENTS_FILE)
+
+  try {
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true })
+    }
+    fs.writeFileSync(filePath, JSON.stringify(stream, null, 2), 'utf-8')
+  } catch {
+    // Silently fail - defense events are not critical
+  }
+}
+
+/** Add a defense event to the stream. */
+export function addDefenseEvent(
+  stream: DefenseEventStream,
+  event: Omit<DefenseEvent, 'id' | 'timestamp'>
+): DefenseEventStream {
+  const id = `def-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  const newEvent: DefenseEvent = {
+    id,
+    timestamp: new Date().toISOString(),
+    ...event,
+  }
+
+  const newCounts = { ...stream.counts }
+  bumpCount(newCounts, event.type)
+
+  return {
+    events: [...stream.events, newEvent],
+    lastUpdated: new Date().toISOString(),
+    counts: newCounts,
+  }
+}
+
+/** Compute counts from events array (for consistency). */
+export function computeCounts(events: DefenseEvent[]): Record<DefenseEventType, number> {
+  const counts: Record<DefenseEventType, number> = {
+    precondition_failed: 0,
+    rollback: 0,
+    invariant_violated: 0,
+    assumption_falsified: 0,
+  }
+
+  for (const event of events) {
+    bumpCount(counts, event.type)
+  }
+
+  return counts
+}

package/src/tools/experience-bank.ts

@@ -0,0 +1,264 @@
+/**
+ * src/tools/experience-bank.ts — experience bank query tool.
+ *
+ *   iterate_experience — browse, search, query, and add project experience entries.
+ *
+ * Experiences are accumulated across sessions and stored in .iterate/experience.json.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+import { resolveProjectRootForExec } from '../config-loader.ts'
+import { readExperienceBank, writeExperienceBank, searchExperienceEntries, upsertExperience } from './experience-store.ts'
+import type { ExperienceEntryInput } from './experience-store.ts'
+import type { ExperienceEntry } from '../types.ts'
+
+const DEFAULT_LIMIT = 50
+const MAX_LIMIT = 100
+
+/** Clamp a caller-supplied limit to a sane range. */
+function clampLimit(limit: number | undefined): number {
+  if (typeof limit !== 'number' || !Number.isInteger(limit) || limit <= 0) {
+    return DEFAULT_LIMIT
+  }
+  return Math.min(limit, MAX_LIMIT)
+}
+
+/** Validate a caller-supplied experience entry object. Returns error strings. */
+function validateExperienceInput(raw: unknown): string[] {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return ['entry must be a JSON object']
+  }
+  const e = raw as Record<string, unknown>
+  const errors: string[] = []
+  if (typeof e.pattern !== 'string' || !e.pattern.trim()) errors.push('.pattern is required')
+  if (typeof e.dimension !== 'string' || !e.dimension.trim()) errors.push('.dimension is required')
+  if (typeof e.description !== 'string' || !e.description.trim()) errors.push('.description is required')
+  if (typeof e.verifiedFix !== 'string' || !e.verifiedFix.trim()) errors.push('.verifiedFix is required')
+  if (typeof e.findingSummary !== 'string' || !e.findingSummary.trim()) errors.push('.findingSummary is required')
+  const severity = e.severity
+  if (severity !== 'critical' && severity !== 'high' && severity !== 'medium' && severity !== 'low') {
+    errors.push('.severity must be one of critical, high, medium, low')
+  }
+  if (!Array.isArray(e.files) || !e.files.every((f) => typeof f === 'string' && f.length > 0)) {
+    errors.push('.files must be an array of non-empty strings')
+  }
+  if (!Array.isArray(e.tags) || !e.tags.every((t) => typeof t === 'string')) {
+    errors.push('.tags must be an array of strings')
+  }
+  return errors
+}
+
+/** Normalize a validated raw entry into the store input shape. */
+function normalizeExperienceInput(raw: Record<string, unknown>): ExperienceEntryInput {
+  return {
+    ...(typeof raw.id === 'string' && raw.id.length > 0 ? { id: raw.id } : {}),
+    pattern: raw.pattern as string,
+    description: raw.description as string,
+    verifiedFix: raw.verifiedFix as string,
+    dimension: raw.dimension as string,
+    findingSummary: raw.findingSummary as string,
+    severity: raw.severity as ExperienceEntryInput['severity'],
+    files: raw.files as string[],
+    tags: raw.tags as string[],
+  }
+}
+
+/**
+ * Register the `iterate_experience` tool.
+ * Queries the experience bank for historical fixes and patterns.
+ */
+export function registerExperienceBankTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_experience',
+      description:
+        'Query or extend the experience bank: browse/search historical fixes and patterns, ' +
+        'or record a new verified fix (operation:"add"). ' +
+        'List/search/get return matching entries with hit counts, verified fixes, and related context. ' +
+        '"add" upserts an experience entry into .iterate/experience.json — a repeat of the same ' +
+        'pattern+dimension increments its hit count instead of duplicating it. ' +
+        'Use it to remember fixes that worked so future rounds apply them first.',
+      parameters: {
+        operation: {
+          type: 'string',
+          description: 'Operation: list (browse all), search (by query), get (by id), add (add a new experience). Default: list.',
+          enum: ['list', 'search', 'get', 'add'],
+        },
+        query: {
+          type: 'string',
+          description: 'Search query (for search operation). Matches against pattern, description, files, tags.',
+        },
+        dimension: {
+          type: 'string',
+          description: 'Filter by dimension (e.g., correctness, security, performance).',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Filter by tags (AND logic).',
+        },
+        id: {
+          type: 'string',
+          description: 'Experience ID (for get operation, or to update a specific entry via add).',
+        },
+        entry: {
+          type: 'json',
+          description:
+            'Experience entry object (required for add). Fields: id (optional), pattern, dimension, description, ' +
+            'verifiedFix, findingSummary, severity (critical|high|medium|low), files (string[]), tags (string[]).',
+        },
+        limit: {
+          type: 'integer',
+          description: `Max entries to return (default: ${DEFAULT_LIMIT}, cap: ${MAX_LIMIT}).`,
+        },
+        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' },
+            operation: { type: 'string' },
+            count: { type: 'integer' },
+            entries: { type: 'json' },
+            entry: { type: 'json' },
+            totalHits: { type: 'integer' },
+            added: { type: 'boolean' },
+            errors: { type: 'json' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (!value.ok) return [{ type: 'text', text: `experience query failed: ${value.error}` }]
+          if (value.operation === 'add' && value.entry) {
+            const entry = value.entry as unknown as ExperienceEntry
+            return [{ type: 'text', text: [
+              value.added
+                ? `Recorded new experience: ${entry.id}`
+                : `Experience already known (hit ${entry.hitCount}): ${entry.id}`,
+              `Pattern: ${entry.pattern}`,
+              `Dimension: ${entry.dimension}`,
+              `Description: ${entry.description}`,
+              `Fix: ${entry.verifiedFix}`,
+              `Files: ${entry.files.join(', ')}`,
+              `Tags: ${entry.tags.join(', ')}`,
+            ].join('\n') }]
+          }
+          if (value.operation === 'get' && value.entry) {
+            const entry = value.entry as unknown as ExperienceEntry
+            return [{ type: 'text', text: [
+              `Experience: ${entry.id}`,
+              `Pattern: ${entry.pattern}`,
+              `Description: ${entry.description}`,
+              `Fix: ${entry.verifiedFix}`,
+              `Files: ${entry.files.join(', ')}`,
+              `Hits: ${entry.hitCount}`,
+              `Tags: ${entry.tags.join(', ')}`,
+            ].join('\n') }]
+          }
+          const entries = (value.entries as unknown as ExperienceEntry[] | undefined) ?? []
+          const lines = [
+            `Found ${value.count} experience(s) (total hits: ${value.totalHits})`,
+            '',
+            ...entries.map((e) => `[${e.id}] ${e.pattern} (hits: ${e.hitCount}) - ${e.description}`),
+          ]
+          return [{ type: 'text', text: lines.join('\n') }]
+        },
+      },
+
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
+        if (!resolved.ok) return { ok: false, kind: 'experience', error: resolved.reason }
+        const projectRoot = resolved.root
+
+        const operation = typeof args.operation === 'string' ? args.operation : 'list'
+        const limit = clampLimit(args.limit as number | undefined)
+
+        if (operation === 'add') {
+          const raw = args.entry
+          const errors = validateExperienceInput(raw)
+          if (errors.length > 0) {
+            return {
+              ok: false,
+              kind: 'experience',
+              operation: 'add',
+              errors: errors as unknown as JsonValue,
+              error: `Invalid experience entry: ${errors.join('; ')}`,
+            }
+          }
+          const bank = readExperienceBank(projectRoot)
+          const { bank: next, added, entryId } = upsertExperience(bank, normalizeExperienceInput(raw as Record<string, unknown>))
+          writeExperienceBank(projectRoot, next)
+          const entry = next.entries.find((e) => e.id === entryId)
+          return {
+            ok: true,
+            kind: 'experience',
+            operation: 'add',
+            added,
+            count: next.entries.length,
+            entry: entry as unknown as JsonValue,
+            totalHits: next.totalHits,
+          }
+        }
+
+        const bank = readExperienceBank(projectRoot)
+
+        if (operation === 'get' && typeof args.id === 'string') {
+          const entry = bank.entries.find((e) => e.id === args.id)
+          if (!entry) {
+            return { ok: false, kind: 'experience', error: `Experience not found: ${args.id}` }
+          }
+          return {
+            ok: true,
+            kind: 'experience',
+            operation: 'get',
+            count: 1,
+            entry: entry as unknown as JsonValue,
+            totalHits: bank.totalHits,
+          }
+        }
+
+        if (operation === 'search' && typeof args.query === 'string') {
+          const entries = searchExperienceEntries(bank.entries, args.query, {
+            dimension: typeof args.dimension === 'string' ? args.dimension : undefined,
+            tags: Array.isArray(args.tags) ? args.tags : undefined,
+          }).slice(0, limit)
+
+          return {
+            ok: true,
+            kind: 'experience',
+            operation: 'search',
+            count: entries.length,
+            entries: entries as unknown as JsonValue,
+            totalHits: bank.totalHits,
+          }
+        }
+
+        // Default: list with optional filters
+        let entries = bank.entries
+        if (typeof args.dimension === 'string' && args.dimension) {
+          entries = entries.filter((e) => e.dimension === args.dimension)
+        }
+        if (Array.isArray(args.tags) && args.tags.length > 0) {
+          entries = entries.filter((e) => args.tags!.every((t: string) => e.tags.includes(t)))
+        }
+
+        return {
+          ok: true,
+          kind: 'experience',
+          operation: 'list',
+          count: Math.min(entries.length, limit),
+          entries: entries.slice(0, limit) as unknown as JsonValue,
+          totalHits: bank.totalHits,
+        }
+      },
+    }),
+  )
+}

package/src/tools/experience-store.ts

@@ -0,0 +1,160 @@
+/**
+ * src/tools/experience-store.ts — experience bank storage layer.
+ *
+ * Provides read/write access to the experience bank stored in
+ * .iterate/experience.json. Experiences are accumulated across sessions.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import type { ExperienceBank, ExperienceEntry } from '../types.ts'
+
+const EXPERIENCE_FILE = 'experience.json'
+
+/** Default empty experience bank. */
+function emptyBank(): ExperienceBank {
+  return {
+    entries: [],
+    lastUpdated: new Date().toISOString(),
+    totalHits: 0,
+  }
+}
+
+/** Read the experience bank from disk. Returns empty bank if not found. */
+export function readExperienceBank(projectRoot: string): ExperienceBank {
+  const filePath = path.join(projectRoot, '.iterate', EXPERIENCE_FILE)
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8')
+    const parsed = JSON.parse(content) as ExperienceBank
+    if (parsed && Array.isArray(parsed.entries)) {
+      return parsed
+    }
+  } catch {
+    // File not found or invalid JSON
+  }
+  return emptyBank()
+}
+
+/** Write the experience bank to disk. */
+export function writeExperienceBank(projectRoot: string, bank: ExperienceBank): void {
+  const dirPath = path.join(projectRoot, '.iterate')
+  const filePath = path.join(dirPath, EXPERIENCE_FILE)
+
+  try {
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true })
+    }
+    fs.writeFileSync(filePath, JSON.stringify(bank, null, 2), 'utf-8')
+  } catch {
+    // Silently fail - experience bank is not critical
+  }
+}
+
+/** Search experience entries by query string. */
+export function searchExperienceEntries(
+  entries: ExperienceEntry[],
+  query: string,
+  opts: { dimension?: string; tags?: string[] } = {},
+): ExperienceEntry[] {
+  const lowerQuery = query.toLowerCase()
+
+  return entries.filter((entry) => {
+    // Dimension filter
+    if (opts.dimension && entry.dimension !== opts.dimension) {
+      return false
+    }
+
+    // Tags filter (AND logic)
+    if (opts.tags && opts.tags.length > 0) {
+      if (!opts.tags.every((t) => entry.tags.includes(t))) {
+        return false
+      }
+    }
+
+    // Text search across multiple fields
+    if (query) {
+      const searchableText = [
+        entry.pattern,
+        entry.description,
+        entry.verifiedFix,
+        entry.findingSummary,
+        entry.dimension,
+        ...entry.files,
+        ...entry.tags,
+      ].join(' ').toLowerCase()
+
+      if (!searchableText.includes(lowerQuery)) {
+        return false
+      }
+    }
+
+    return true
+  })
+}
+
+/** Fields the caller may supply when adding/updating an experience entry. */
+export type ExperienceEntryInput = Omit<
+  ExperienceEntry,
+  'id' | 'timestamp' | 'hitCount' | 'lastHitAt'
+> & { id?: string }
+
+/**
+ * Add or update an experience entry.
+ *
+ * An entry with an `id` that already exists, OR a new entry whose
+ * `pattern`+`dimension` pair matches an existing entry, is treated as a HIT:
+ * the matching entry's hitCount is incremented (lastHitAt refreshed) so
+ * repeated encounters of the same pattern do not create duplicates. Otherwise
+ * a fresh entry is appended with hitCount 1. Never mutates the input bank.
+ *
+ * Returns the resulting bank plus whether a NEW entry was created and the id
+ * of the affected entry.
+ */
+export function upsertExperience(
+  bank: ExperienceBank,
+  entry: ExperienceEntryInput
+): { bank: ExperienceBank; added: boolean; entryId: string } {
+  const lastUpdated = new Date().toISOString()
+  const existing = entry.id
+    ? bank.entries.find((e) => e.id === entry.id)
+    : bank.entries.find((e) => e.pattern === entry.pattern && e.dimension === entry.dimension)
+
+  if (existing) {
+    const updated: ExperienceEntry = {
+      ...existing,
+      hitCount: (existing.hitCount ?? 0) + 1,
+      lastHitAt: lastUpdated,
+    }
+    return {
+      bank: {
+        ...bank,
+        entries: bank.entries.map((e) => (e.id === existing.id ? updated : e)),
+        lastUpdated,
+        totalHits: (bank.totalHits ?? 0) + 1,
+      },
+      added: false,
+      entryId: existing.id,
+    }
+  }
+
+  // Add new entry
+  const id = entry.id || `exp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  const newEntry: ExperienceEntry = {
+    id,
+    timestamp: lastUpdated,
+    hitCount: 1,
+    lastHitAt: lastUpdated,
+    ...entry,
+  }
+
+  return {
+    bank: {
+      ...bank,
+      entries: [...bank.entries, newEntry],
+      lastUpdated,
+      totalHits: (bank.totalHits ?? 0) + 1,
+    },
+    added: true,
+    entryId: id,
+  }
+}

package/src/tools/fix.ts

@@ -20,7 +20,7 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
 import { join, sep } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { loadEffectiveConfig, resolveProjectRootForExec } from '../config-loader.ts'
 import { runWithJob } from '../jobs.ts'
 import { countTouchedMethods } from '../method-scope.ts'

package/src/tools/history.ts

@@ -9,7 +9,7 @@
  */
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import { readDecisionEntries } from './decision-log.ts'
 import { readRegistry } from './fix.ts'

package/src/tools/prune.ts

@@ -21,7 +21,7 @@
 import { existsSync, readdirSync, renameSync, 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 type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import { readDecisionEntries, appendDecisionEntry } from './decision-log.ts'
 import { readRegistry, removeRecord, recomputeRoundCounts } from './fix.ts'