iterate-plugin 2.5.0 → 2.7.0

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;
+        },
+    }));
+}

package/dist/tools/decision-log.js

@@ -0,0 +1,162 @@
+import { appendFileSync, readFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { resolveProjectRoot } from "../config-loader.js";
+const LOG_DIR = '.iterate';
+const LOG_FILE = 'decision-log.jsonl';
+/**
+ * Resolve the log file path, creating the directory if needed.
+ */
+function logPath(projectRoot) {
+    const dir = join(projectRoot, LOG_DIR);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    return join(dir, LOG_FILE);
+}
+/**
+ * Append one entry to the decision log (JSONL format).
+ * Returns the entry count after appending.
+ */
+export function appendDecisionEntry(projectRoot, entry) {
+    const filePath = logPath(projectRoot);
+    const line = JSON.stringify(entry) + '\n';
+    appendFileSync(filePath, line, 'utf-8');
+    // Count entries
+    let count = 0;
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        count = content.split('\n').filter((l) => l.trim().length > 0).length;
+    }
+    catch {
+        count = 1;
+    }
+    return { count, path: filePath };
+}
+/**
+ * Read all entries from the decision log.
+ */
+export function readDecisionEntries(projectRoot) {
+    const filePath = join(projectRoot, LOG_DIR, LOG_FILE);
+    if (!existsSync(filePath))
+        return [];
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        return content
+            .split('\n')
+            .filter((l) => l.trim().length > 0)
+            .map((l) => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Register the `iterate_decision_log` tool.
+ * Append-only decision log stored in .iterate/decision-log.jsonl.
+ * Supports `append` and `read` operations.
+ */
+export function registerDecisionLogTool(ctx) {
+    ctx.tools.register(defineTool({
+        name: 'iterate_decision_log',
+        description: 'Append-only decision log for the iterate loop. ' +
+            'Use `append` to record a round start, review finding, fix, validation result, or decision. ' +
+            'Use `read` to retrieve all entries for review. ' +
+            'The log is stored in .iterate/decision-log.jsonl and persists across sessions.',
+        parameters: {
+            operation: {
+                type: 'string',
+                required: true,
+                description: '"append" to add an entry, "read" to retrieve all entries.',
+                enum: ['append', 'read'],
+            },
+            type: {
+                type: 'string',
+                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',
+                description: 'Current iteration round number (required for append).',
+            },
+            data: {
+                type: 'json',
+                description: 'Entry payload as JSON object (required for append).',
+            },
+            path: {
+                type: 'string',
+                description: 'Project root directory (default: current working directory).',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    operation: { type: 'string', required: true },
+                    entryCount: { type: 'integer' },
+                    logPath: { type: 'string' },
+                    entries: { type: 'json' },
+                    success: { type: 'boolean' },
+                    entry: { type: 'json' },
+                    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, error: resolved.reason };
+            }
+            const projectRoot = resolved.root;
+            if (args.operation === 'read') {
+                const entries = readDecisionEntries(projectRoot);
+                return {
+                    operation: 'read',
+                    entryCount: entries.length,
+                    logPath: join(projectRoot, LOG_DIR, LOG_FILE),
+                    entries: entries,
+                };
+            }
+            if (args.operation === 'append') {
+                if (!args.type || !args.round) {
+                    return {
+                        operation: 'append',
+                        error: 'type and round are required for append operation.',
+                    };
+                }
+                const entry = {
+                    timestamp: new Date().toISOString(),
+                    round: args.round,
+                    type: args.type,
+                    data: args.data ?? {},
+                };
+                const result = appendDecisionEntry(projectRoot, entry);
+                return {
+                    operation: 'append',
+                    success: true,
+                    entryCount: result.count,
+                    logPath: result.path,
+                    entry: entry,
+                };
+            }
+            return {
+                operation: args.operation,
+                error: `Unknown operation "${args.operation}". Use "append" or "read".`,
+            };
+        },
+    }));
+}