iterate-plugin 2.12.2 → 3.2.1

package/dist/tools/defense-events.js

@@ -0,0 +1,260 @@
+/**
+ * src/tools/defense-events.ts — defense event stream query & record tool.
+ *
+ *   iterate_defense_events — browse/search defense events from the current
+ *                            iteration, or record a new one.
+ *
+ * Defense events include: precondition failures, rollbacks, invariant violations,
+ * and assumption falsifications. Read operations give visibility into defensive
+ * actions; "record" persists a new event to .iterate/defense-events.json.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { resolveProjectRootForExec, loadEffectiveConfig } from "../config-loader.js";
+import { readDefenseEvents, writeDefenseEvents, addDefenseEvent } from "./defense-store.js";
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 100;
+const EVENT_TYPES = [
+    'precondition_failed',
+    'rollback',
+    'invariant_violated',
+    'assumption_falsified',
+];
+/** Clamp a caller-supplied limit to a sane range. */
+function clampLimit(limit) {
+    if (typeof limit !== 'number' || !Number.isInteger(limit) || limit <= 0) {
+        return DEFAULT_LIMIT;
+    }
+    return Math.min(limit, MAX_LIMIT);
+}
+/** Bilingual, config-driven human-readable labels for defense event types. */
+const EVENT_TYPE_LABELS = {
+    precondition_failed: { zh: '前置校验失败', en: 'precondition failed' },
+    rollback: { zh: '回滚', en: 'rollback' },
+    invariant_violated: { zh: '不变量违反', en: 'invariant violated' },
+    assumption_falsified: { zh: '假设被证伪', en: 'assumption falsified' },
+};
+/** Label for a defense event type in the requested language (fallback: English). */
+function labelFor(type, language) {
+    const labels = EVENT_TYPE_LABELS[type];
+    return labels ? labels[language] : type;
+}
+/** Validate arguments for the record operation. */
+function validateRecordInput(args) {
+    const errors = [];
+    if (typeof args.type !== 'string' || !EVENT_TYPES.includes(args.type)) {
+        errors.push(`type must be one of: ${EVENT_TYPES.join(', ')}`);
+    }
+    if (typeof args.round !== 'number' || !Number.isInteger(args.round) || args.round < 1) {
+        errors.push('round must be a positive integer');
+    }
+    if (typeof args.description !== 'string' || !args.description.trim()) {
+        errors.push('description is required');
+    }
+    if (typeof args.defense !== 'string' || !args.defense.trim()) {
+        errors.push('defense is required');
+    }
+    if (typeof args.outcome !== 'string' || !args.outcome.trim()) {
+        errors.push('outcome is required');
+    }
+    const severity = args.severity;
+    if (severity !== 'critical' && severity !== 'high' && severity !== 'medium' && severity !== 'low') {
+        errors.push('severity must be one of critical, high, medium, low');
+    }
+    return errors;
+}
+/**
+ * Register the `iterate_defense_events` tool.
+ * Queries defense events from the current iteration.
+ */
+export function registerDefenseEventsTool(ctx) {
+    ctx.tools.register(defineTool({
+        name: 'iterate_defense_events',
+        description: 'Query or record defense events: precondition failures, rollbacks, invariant violations, ' +
+            'and assumption falsifications. ' +
+            'List/counts return events with descriptions, outcomes, and summary counts; ' +
+            '"record" persists a new event to .iterate/defense-events.json. ' +
+            'Use it to review defensive actions taken, or to log one when a defense fires.',
+        parameters: {
+            operation: {
+                type: 'string',
+                description: 'Operation: list (browse all), counts (summary by type), record (log a new event). Default: list.',
+                enum: ['list', 'counts', 'record'],
+            },
+            type: {
+                type: 'string',
+                description: 'Event type (filter for list; required for record): precondition_failed, rollback, invariant_violated, assumption_falsified.',
+            },
+            round: {
+                type: 'integer',
+                description: 'Round number (filter for list; required for record).',
+            },
+            severity: {
+                type: 'string',
+                description: 'Severity (filter for list; required for record): critical, high, medium, low.',
+            },
+            description: {
+                type: 'string',
+                description: 'What was being checked (required for record).',
+            },
+            defense: {
+                type: 'string',
+                description: 'The defense that was triggered (required for record).',
+            },
+            outcome: {
+                type: 'string',
+                description: 'Outcome: what was protected against (required for record).',
+            },
+            file: {
+                type: 'string',
+                description: 'Optional file/location context (record).',
+            },
+            line: {
+                type: 'integer',
+                description: 'Optional line number context (record).',
+            },
+            language: {
+                type: 'string',
+                description: 'Label language for readable output: en (default) or zh. Falls back to the project config language.',
+                enum: ['en', 'zh'],
+            },
+            limit: {
+                type: 'integer',
+                description: `Max events 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' },
+                    events: { type: 'json' },
+                    counts: { type: 'json' },
+                    event: { type: 'json' },
+                    language: { type: 'string' },
+                    errors: { type: 'json' },
+                    error: { type: 'string' },
+                },
+            },
+            render: (_args, value) => {
+                if (!value.ok)
+                    return [{ type: 'text', text: `defense events query failed: ${value.error}` }];
+                const language = value.language === 'zh' ? 'zh' : 'en';
+                if (value.operation === 'counts' && value.counts) {
+                    const counts = value.counts;
+                    const lines = [
+                        'Defense Event Summary:',
+                        ...EVENT_TYPES.map((type) => `  ${labelFor(type, language)}: ${counts[type] ?? 0}`),
+                        `  Total: ${EVENT_TYPES.reduce((sum, type) => sum + (counts[type] ?? 0), 0)}`,
+                    ];
+                    return [{ type: 'text', text: lines.join('\n') }];
+                }
+                if (value.operation === 'record' && value.event) {
+                    const e = value.event;
+                    return [{ type: 'text', text: [
+                                `Recorded defense event: ${e.id}`,
+                                `  Round ${e.round} - ${labelFor(e.type, language)} (${e.severity})`,
+                                `  Check: ${e.description}`,
+                                `  Defense: ${e.defense}`,
+                                `  Outcome: ${e.outcome}`,
+                                e.file ? `  File: ${e.file}${e.line ? `:${e.line}` : ''}` : '',
+                            ].filter(Boolean).join('\n') }];
+                }
+                const events = value.events ?? [];
+                if (events.length === 0) {
+                    return [{ type: 'text', text: 'No defense events recorded.' }];
+                }
+                const lines = [
+                    `Defense Events (${value.count} total):`,
+                    '',
+                    ...events.map((e) => {
+                        const typeLabel = labelFor(e.type, language);
+                        return `[${e.id}] Round ${e.round} - ${typeLabel}\n  ${e.description}\n  Outcome: ${e.outcome}`;
+                    }),
+                ];
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
+            if (!resolved.ok)
+                return { ok: false, kind: 'defense_events', error: resolved.reason };
+            const projectRoot = resolved.root;
+            const configLang = loadEffectiveConfig(projectRoot).config.language;
+            const language = args.language === 'zh' || args.language === 'en' ? args.language : configLang;
+            const operation = typeof args.operation === 'string' ? args.operation : 'list';
+            const limit = clampLimit(args.limit);
+            if (operation === 'record') {
+                const errors = validateRecordInput(args);
+                if (errors.length > 0) {
+                    return {
+                        ok: false,
+                        kind: 'defense_events',
+                        operation: 'record',
+                        errors: errors,
+                        error: `Invalid defense event: ${errors.join('; ')}`,
+                    };
+                }
+                const stream = readDefenseEvents(projectRoot);
+                const next = addDefenseEvent(stream, {
+                    round: args.round,
+                    type: args.type,
+                    description: args.description,
+                    defense: args.defense,
+                    outcome: args.outcome,
+                    severity: args.severity,
+                    ...(typeof args.file === 'string' && args.file.length > 0 ? { file: args.file } : {}),
+                    ...(typeof args.line === 'number' ? { line: args.line } : {}),
+                });
+                writeDefenseEvents(projectRoot, next);
+                const event = next.events[next.events.length - 1];
+                return {
+                    ok: true,
+                    kind: 'defense_events',
+                    operation: 'record',
+                    language,
+                    event: event,
+                    counts: next.counts,
+                };
+            }
+            const stream = readDefenseEvents(projectRoot);
+            if (operation === 'counts') {
+                return {
+                    ok: true,
+                    kind: 'defense_events',
+                    operation: 'counts',
+                    language,
+                    counts: stream.counts,
+                };
+            }
+            // Filter events
+            let events = stream.events;
+            if (typeof args.type === 'string' && args.type) {
+                events = events.filter((e) => e.type === args.type);
+            }
+            if (typeof args.round === 'number') {
+                events = events.filter((e) => e.round === args.round);
+            }
+            if (typeof args.severity === 'string' && args.severity) {
+                events = events.filter((e) => e.severity === args.severity);
+            }
+            // Sort by timestamp descending (newest first)
+            events.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+            return {
+                ok: true,
+                kind: 'defense_events',
+                operation: 'list',
+                language,
+                count: Math.min(events.length, limit),
+                events: events.slice(0, limit),
+            };
+        },
+    }));
+}

package/dist/tools/defense-store.js

@@ -0,0 +1,97 @@
+/**
+ * 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';
+const DEFENSE_EVENTS_FILE = 'defense-events.json';
+/** Valid defense event types (must stay in sync with DefenseEventType). */
+const VALID_EVENT_TYPES = new Set([
+    '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, type) {
+    if (typeof type === 'string' && VALID_EVENT_TYPES.has(type)) {
+        counts[type]++;
+    }
+}
+/** Default empty defense event stream. */
+function emptyStream() {
+    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) {
+    const filePath = path.join(projectRoot, '.iterate', DEFENSE_EVENTS_FILE);
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(content);
+        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, stream) {
+    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, event) {
+    const id = `def-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const newEvent = {
+        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) {
+    const counts = {
+        precondition_failed: 0,
+        rollback: 0,
+        invariant_violated: 0,
+        assumption_falsified: 0,
+    };
+    for (const event of events) {
+        bumpCount(counts, event.type);
+    }
+    return counts;
+}

package/dist/tools/experience-bank.js

@@ -0,0 +1,248 @@
+/**
+ * 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 { resolveProjectRootForExec } from "../config-loader.js";
+import { readExperienceBank, writeExperienceBank, searchExperienceEntries, upsertExperience } from "./experience-store.js";
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 100;
+/** Clamp a caller-supplied limit to a sane range. */
+function clampLimit(limit) {
+    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) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return ['entry must be a JSON object'];
+    }
+    const e = raw;
+    const errors = [];
+    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) {
+    return {
+        ...(typeof raw.id === 'string' && raw.id.length > 0 ? { id: raw.id } : {}),
+        pattern: raw.pattern,
+        description: raw.description,
+        verifiedFix: raw.verifiedFix,
+        dimension: raw.dimension,
+        findingSummary: raw.findingSummary,
+        severity: raw.severity,
+        files: raw.files,
+        tags: raw.tags,
+    };
+}
+/**
+ * Register the `iterate_experience` tool.
+ * Queries the experience bank for historical fixes and patterns.
+ */
+export function registerExperienceBankTool(ctx) {
+    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;
+                    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;
+                    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 ?? [];
+                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);
+            if (operation === 'add') {
+                const raw = args.entry;
+                const errors = validateExperienceInput(raw);
+                if (errors.length > 0) {
+                    return {
+                        ok: false,
+                        kind: 'experience',
+                        operation: 'add',
+                        errors: errors,
+                        error: `Invalid experience entry: ${errors.join('; ')}`,
+                    };
+                }
+                const bank = readExperienceBank(projectRoot);
+                const { bank: next, added, entryId } = upsertExperience(bank, normalizeExperienceInput(raw));
+                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,
+                    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,
+                    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,
+                    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) => e.tags.includes(t)));
+            }
+            return {
+                ok: true,
+                kind: 'experience',
+                operation: 'list',
+                count: Math.min(entries.length, limit),
+                entries: entries.slice(0, limit),
+                totalHits: bank.totalHits,
+            };
+        },
+    }));
+}