iterate-plugin 2.6.0 → 2.7.1

package/dist/tools/checkpoint.js

@@ -0,0 +1,260 @@
+/**
+ * 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 { resolveProjectRoot } from "../config-loader.js";
+import { checkpointPath, iterateDir } from "../paths.js";
+import { readRegistry } from "./fix.js";
+import { readDecisionEntries } from "./decision-log.js";
+// ─── Pure helpers (exported for unit tests) ─────────────────────────────────
+/** Read a checkpoint from disk (missing/corrupt → null). */
+export function readCheckpoint(projectRoot) {
+    const file = checkpointPath(projectRoot);
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+        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) {
+    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) {
+    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) {
+    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 ?? 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 = {
+                    mode: args.mode,
+                    round: args.round,
+                    maxRounds: args.maxRounds,
+                    fixedCount: args.fixedCount,
+                    architecturalCount: args.architecturalCount,
+                    findings: (Array.isArray(args.findings) ? args.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 };
+            }
+            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) {
+    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/dist/tools/config.js

@@ -0,0 +1,134 @@
+import { join } from 'node:path';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { loadEffectiveConfig, validateConfig, resolveProjectRoot } from "../config-loader.js";
+import { applyConfigUpdates, readRawConfig, validateConfigUpdates, writeConfigFile, } from "../config-write.js";
+/**
+ * Register the `iterate_config` tool.
+ * 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) {
+    ctx.tools.register(defineTool({
+        name: 'iterate_config',
+        description: '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, ' +
+            '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).',
+            },
+            section: {
+                type: 'string',
+                description: 'Optional config section to return: dimensions, validation, git, atomic, review, personalization, onboarding, or goal.',
+            },
+            validate: {
+                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: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    found: { type: 'boolean', required: true },
+                    valid: { type: 'boolean' },
+                    errors: { type: 'array', items: { type: 'string' } },
+                    section: { type: 'string' },
+                    data: { type: 'json' },
+                    config: { type: 'json' },
+                    availableSections: { type: 'array', items: { type: 'string' } },
+                    operation: { type: 'string' },
+                    ok: { type: 'boolean' },
+                    backupPath: { type: 'string' },
+                    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 { found: false, error: resolved.reason };
+            }
+            const projectRoot = resolved.root;
+            // ── Write operation ────────────────────────────────────────────────
+            if (args.operation === 'write') {
+                const updates = args.updates;
+                const updateErrors = validateConfigUpdates(updates ?? {});
+                if (updateErrors.length > 0) {
+                    return { operation: 'write', ok: false, found: false, errors: updateErrors };
+                }
+                let base;
+                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,
+                };
+            }
+            // ── Read operations (original behavior) ────────────────────────────
+            const { config, source } = loadEffectiveConfig(projectRoot);
+            const hasOverride = source === 'override';
+            if (args.validate) {
+                const errors = validateConfig(config);
+                return {
+                    found: hasOverride,
+                    valid: errors.length === 0,
+                    errors: errors.length > 0 ? errors : undefined,
+                    section: 'validation_report',
+                };
+            }
+            if (args.section) {
+                const configRecord = config;
+                const section = configRecord[args.section];
+                if (section === undefined) {
+                    return {
+                        found: hasOverride,
+                        error: `Section "${args.section}" not found in config.`,
+                        availableSections: Object.keys(configRecord),
+                    };
+                }
+                return { found: hasOverride, section: args.section, data: section };
+            }
+            return { found: hasOverride, config: config };
+        },
+    }));
+}

package/dist/tools/context.js

@@ -0,0 +1,160 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { resolveProjectRoot } from "../config-loader.js";
+/** How many ancestor directories we walk up looking for a SKILL.md. */
+const MAX_SKILL_DIR_LOOKUP_DEPTH = 12;
+/**
+ * The directory this source file lives in (…/src/tools). The plugin's own
+ * package root is one level up (…/src), and the skill root is typically a few
+ * levels above that. We use it as the anchor for auto-detecting where the
+ * original SKILL.md lives.
+ */
+const PLUGIN_SRC_DIR = dirname(fileURLToPath(import.meta.url));
+/**
+ * Walk up from the plugin's own location until a directory containing SKILL.md
+ * is found. This is how the plugin locates the ORIGINAL skill (skill 目录)
+ * without any hardcoded absolute path — it works whether the plugin is mounted
+ * from the source tree or bundled next to the skill.
+ *
+ * Returns the absolute directory containing SKILL.md, or null if none found
+ * within `MAX_SKILL_DIR_LOOKUP_DEPTH` ancestors.
+ */
+function findSkillRoot(startDir) {
+    let dir = resolve(startDir);
+    for (let depth = 0; depth < MAX_SKILL_DIR_LOOKUP_DEPTH; depth++) {
+        if (existsSync(join(dir, 'SKILL.md')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // reached the filesystem root
+        dir = parent;
+    }
+    return null;
+}
+/** Exported for unit tests. See the private `findSkillRoot` above. */
+export { findSkillRoot };
+/**
+ * Read a file from a candidate directory, returning its content or null.
+ */
+function readProjectFile(projectRoot, filename) {
+    const filePath = join(projectRoot, filename);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        return readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Locate the first existing SKILL.md across the candidate directories, in
+ * priority order:
+ *   1. explicit skillDir (custom path / 自定义路径)
+ *   2. auto-detected skill root walking up from the plugin (skill 目录)
+ *   3. project root (项目根)
+ * Returns the file content plus the directory it was found in, or null.
+ */
+function findSkillMd(candidates) {
+    for (const dir of candidates) {
+        if (!dir)
+            continue;
+        const content = readProjectFile(dir, 'SKILL.md');
+        if (content !== null)
+            return { content, sourceDir: dir };
+    }
+    return null;
+}
+/** Exported for unit tests. See the private `findSkillMd` above. */
+export { findSkillMd };
+/**
+ * Register the `iterate_context` tool.
+ * Reads SKILL.md (original skill instructions) from the skill directory,
+ * project root, or a custom path, and ITERATE.md from the project root.
+ * Provides the model with the original skill instructions and project knowledge base.
+ */
+export function registerContextTool(ctx) {
+    ctx.tools.register(defineTool({
+        name: 'iterate_context',
+        description: 'Read project context files (SKILL.md and/or ITERATE.md). ' +
+            'SKILL.md contains the original iterate skill instructions; it is searched in ' +
+            'the skill directory (auto-detected), the project root, or an explicit `skillDir`. ' +
+            'ITERATE.md contains the project-specific knowledge base and onboarding information. ' +
+            'Use this to understand the skill workflow and project context.',
+        parameters: {
+            files: {
+                type: 'string',
+                required: true,
+                description: 'Comma-separated list of files to read: "skill", "project", or "skill,project" for both.',
+            },
+            path: {
+                type: 'string',
+                description: 'Project root directory (default: current working directory).',
+            },
+            skillDir: {
+                type: 'string',
+                description: 'Custom directory to search for SKILL.md (highest priority). ' +
+                    'When omitted, SKILL.md is auto-detected from the skill directory, then the project root.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    found: { type: 'boolean', required: true },
+                    skill: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+                    project: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+                    skillSource: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+                    error: { type: 'string' },
+                    searched: { type: 'array', items: { type: 'string' } },
+                },
+            },
+            render: (_args, value) => {
+                const parts = [];
+                if (value.skill)
+                    parts.push(`--- SKILL.md (${value.skillSource ?? '?source?'}) ---\n${value.skill}`);
+                if (value.project)
+                    parts.push(`--- ITERATE.md ---\n${value.project}`);
+                if (!value.skill && !value.project) {
+                    parts.push('No files found. Searched: ' + (value.searched?.join(', ') ?? 'none'));
+                }
+                return [{ type: 'text', text: parts.join('\n\n') }];
+            },
+        },
+        async execute(args) {
+            const resolved = resolveProjectRoot(args.path);
+            if (!resolved.ok) {
+                return { found: false, error: resolved.reason, searched: [] };
+            }
+            const projectRoot = resolved.root;
+            const requested = (args.files ?? '')
+                .split(',')
+                .map((s) => s.trim().toLowerCase())
+                .filter(Boolean);
+            const result = { found: true, searched: [] };
+            if (requested.includes('skill') || requested.includes('skill.md')) {
+                // Candidate dirs in priority order: custom path → auto-detected skill
+                // root → project root. This is how "skill 目录、项目根、自定义路径"
+                // are all supported.
+                const skillRoot = findSkillRoot(PLUGIN_SRC_DIR);
+                const candidates = [];
+                if (args.skillDir)
+                    candidates.push(args.skillDir);
+                if (skillRoot)
+                    candidates.push(skillRoot);
+                candidates.push(projectRoot);
+                result.searched = candidates;
+                const found = findSkillMd(candidates);
+                result.skill = found ? found.content : null;
+                result.skillSource = found ? found.sourceDir : null;
+            }
+            if (requested.includes('project') || requested.includes('iterate.md')) {
+                result.project = readProjectFile(projectRoot, 'ITERATE.md');
+            }
+            return result;
+        },
+    }));
+}