@molecule/api-ai-tools 1.0.0

package/dist/schemas.js

@@ -0,0 +1,225 @@
+/**
+ * Pure tool schema definitions — name, description, and JSON Schema parameters.
+ * No execution logic, no imports beyond types.
+ *
+ * @module
+ */
+/**
+ * Canonical tool schemas shared by the agent runtime and documentation.
+ */
+export const TOOL_SCHEMAS = {
+    list_files: {
+        name: 'list_files',
+        description: 'List files and directories at a given path. Returns entry names with type indicators.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: "Directory path to list. Omit or use '/' for project root. Supports relative or absolute paths.",
+                },
+            },
+            required: [],
+        },
+    },
+    read_file: {
+        name: 'read_file',
+        description: 'Read the full content of a file as text. Always read a file before editing it.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Path to the file to read (relative or absolute).',
+                },
+            },
+            required: ['path'],
+        },
+    },
+    write_file: {
+        name: 'write_file',
+        description: 'Create or overwrite a file with full content. Use edit_file for small targeted changes instead.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Path to the file to write.',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Full file content to write.',
+                },
+            },
+            required: ['path', 'content'],
+        },
+    },
+    edit_file: {
+        name: 'edit_file',
+        description: 'Make targeted search-and-replace edits to a file. Preferred over write_file for small changes. Each old_string must match exactly once in the file.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Path to the file to edit.',
+                },
+                replacements: {
+                    type: 'array',
+                    description: 'List of search-and-replace operations to apply sequentially.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            old_string: {
+                                type: 'string',
+                                description: 'Exact string to find. Must match exactly once in the file.',
+                            },
+                            new_string: {
+                                type: 'string',
+                                description: 'Replacement string.',
+                            },
+                        },
+                        required: ['old_string', 'new_string'],
+                    },
+                },
+            },
+            required: ['path', 'replacements'],
+        },
+    },
+    search_files: {
+        name: 'search_files',
+        description: 'Search for a text pattern across files using grep. Returns matching lines with file paths and line numbers.',
+        parameters: {
+            type: 'object',
+            properties: {
+                pattern: {
+                    type: 'string',
+                    description: 'Text or regex pattern to search for.',
+                },
+                path: {
+                    type: 'string',
+                    description: 'Directory to search in. Defaults to project root.',
+                },
+                include: {
+                    type: 'string',
+                    description: "File glob pattern to filter files (e.g. '*.ts', '*.tsx'). Optional.",
+                },
+            },
+            required: ['pattern'],
+        },
+    },
+    find_files: {
+        name: 'find_files',
+        description: "Find files by name or glob pattern recursively. Excludes node_modules and .git. Use for discovering files by name (e.g. '*.tsx', 'Dashboard*', 'index.*').",
+        parameters: {
+            type: 'object',
+            properties: {
+                pattern: {
+                    type: 'string',
+                    description: "File name or glob pattern (e.g. '*.tsx', 'Dashboard*').",
+                },
+                path: {
+                    type: 'string',
+                    description: 'Directory to search in. Defaults to project root.',
+                },
+            },
+            required: ['pattern'],
+        },
+    },
+    create_directory: {
+        name: 'create_directory',
+        description: 'Create a directory and any necessary parent directories.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Directory path to create.',
+                },
+            },
+            required: ['path'],
+        },
+    },
+    rename_file: {
+        name: 'rename_file',
+        description: 'Rename or move a file or directory.',
+        parameters: {
+            type: 'object',
+            properties: {
+                old_path: {
+                    type: 'string',
+                    description: 'Current path of the file or directory.',
+                },
+                new_path: {
+                    type: 'string',
+                    description: 'New path for the file or directory.',
+                },
+            },
+            required: ['old_path', 'new_path'],
+        },
+    },
+    delete_file: {
+        name: 'delete_file',
+        description: 'Delete a file.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Path to the file to delete.',
+                },
+            },
+            required: ['path'],
+        },
+    },
+    exec_command: {
+        name: 'exec_command',
+        description: 'Run a shell command and return its output. Use for build checks, npm commands, verification, etc.',
+        parameters: {
+            type: 'object',
+            properties: {
+                command: {
+                    type: 'string',
+                    description: 'Shell command to execute.',
+                },
+                cwd: {
+                    type: 'string',
+                    description: 'Working directory. Defaults to project root.',
+                },
+            },
+            required: ['command'],
+        },
+    },
+    save_plan: {
+        name: 'save_plan',
+        description: 'Save an implementation plan as a markdown file in .agents/plans/.',
+        parameters: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Short descriptive name for the plan.',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Full plan content in markdown. MUST be a checklist: every actionable step is a `- [ ]` checkbox (grouped under short headings) so each one can be flipped to `- [x]` in this file as it is completed.',
+                },
+            },
+            required: ['name', 'content'],
+        },
+    },
+    load_skill: {
+        name: 'load_skill',
+        description: 'Load a skill guide by name. Returns the full SKILL.md content for detailed reference on a topic.',
+        parameters: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Skill name (e.g. "api-patterns", "styling") or relative path to SKILL.md.',
+                },
+            },
+            required: ['name'],
+        },
+    },
+};

package/dist/system-prompt.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Composable system prompt builder for AI agents.
+ *
+ * Produces the coding-rules and tool-usage sections that any agent needs.
+ * Consumers wrap this with domain-specific sections (Synthase adds sandbox/IDE rules,
+ * polish pipeline adds design/ClassMap rules).
+ *
+ * @module
+ */
+import type { ExecutionBackend, SkillEntry } from './types.js';
+import type { PromptContext } from './types.js';
+/**
+ * Re-export SkillEntry as DiscoveredSkill for backwards compatibility.
+ * @deprecated Use SkillEntry from types.js instead.
+ */
+export type DiscoveredSkill = SkillEntry;
+/**
+ * Discover skills from a project directory.
+ *
+ * Scans `.agents/skills/` and `.claude/skills/` for SKILL.md files.
+ * Reads the YAML frontmatter of each to extract `name:` and `description:` fields.
+ *
+ * @param backend - Execution backend to use for filesystem access
+ * @returns Array of discovered skills with name, description, and path
+ */
+export declare function discoverSkills(backend: ExecutionBackend): Promise<SkillEntry[]>;
+/**
+ * Build a coding-focused system prompt from composable sections.
+ *
+ * Returns a string that includes:
+ * - Agent identity
+ * - Available tools listing
+ * - Coding best practices
+ * - Tool argument formatting guidance
+ * - Project docs (if provided)
+ * - Discovered skills listing (if provided)
+ * - Inline skills (if provided)
+ * - Custom sections (if provided)
+ *
+ * @param ctx - Prompt construction inputs (tools, docs, skills, etc.).
+ * @returns Fully assembled system prompt text for the coding agent.
+ */
+export declare function buildAgentPrompt(ctx: PromptContext): string;
+//# sourceMappingURL=system-prompt.d.ts.map

package/dist/system-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../src/system-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAkB/C;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAA;AAExC;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAoDrF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAgE3D"}

package/dist/system-prompt.js

@@ -0,0 +1,146 @@
+/**
+ * Composable system prompt builder for AI agents.
+ *
+ * Produces the coding-rules and tool-usage sections that any agent needs.
+ * Consumers wrap this with domain-specific sections (Synthase adds sandbox/IDE rules,
+ * polish pipeline adds design/ClassMap rules).
+ *
+ * @module
+ */
+import { TOOL_SCHEMAS } from './schemas.js';
+/** Tool descriptions for the prompt, keyed by tool name. */
+const TOOL_DESCRIPTIONS = {
+    list_files: 'Browse the file tree',
+    read_file: 'Read any source file',
+    write_file: 'Create or overwrite files (full content)',
+    edit_file: 'Make targeted search-and-replace edits (preferred for small changes)',
+    search_files: 'Search for text patterns across files (grep)',
+    find_files: 'Find files by name/glob pattern recursively',
+    create_directory: 'Create directories (with parents)',
+    rename_file: 'Rename or move files and directories',
+    delete_file: 'Remove files',
+    exec_command: 'Run shell commands (build checks, npm, verification)',
+    save_plan: 'Save an implementation plan as markdown',
+    load_skill: 'Load a skill guide for detailed reference on a topic',
+};
+/**
+ * Discover skills from a project directory.
+ *
+ * Scans `.agents/skills/` and `.claude/skills/` for SKILL.md files.
+ * Reads the YAML frontmatter of each to extract `name:` and `description:` fields.
+ *
+ * @param backend - Execution backend to use for filesystem access
+ * @returns Array of discovered skills with name, description, and path
+ */
+export async function discoverSkills(backend) {
+    const root = backend.projectRoot;
+    const skills = [];
+    const skillDirs = ['.agents/skills', '.claude/skills'];
+    for (const skillDir of skillDirs) {
+        const dirPath = `${root}/${skillDir}`;
+        let entries;
+        try {
+            entries = await backend.readDir(dirPath);
+        }
+        catch (_error) {
+            continue; // directory doesn't exist — skill dirs are optional
+        }
+        for (const entry of entries) {
+            if (entry.type !== 'directory')
+                continue;
+            const skillMdPath = `${dirPath}/${entry.name}/SKILL.md`;
+            let content;
+            try {
+                content = await backend.readFile(skillMdPath);
+            }
+            catch (_error) {
+                continue; // no SKILL.md in this subdirectory — individual skill files are optional
+            }
+            // Parse YAML frontmatter (--- delimited block at file start)
+            const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+            if (!frontmatterMatch) {
+                // No frontmatter — use directory name as skill name, first heading as description
+                const headingMatch = content.match(/^#\s+(.+)/m);
+                skills.push({
+                    name: entry.name,
+                    description: headingMatch ? headingMatch[1].trim() : entry.name,
+                    path: `${skillDir}/${entry.name}/SKILL.md`,
+                });
+                continue;
+            }
+            const frontmatter = frontmatterMatch[1];
+            const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+            const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+            skills.push({
+                name: nameMatch ? nameMatch[1].trim() : entry.name,
+                description: descMatch ? descMatch[1].trim() : entry.name,
+                path: `${skillDir}/${entry.name}/SKILL.md`,
+            });
+        }
+    }
+    return skills;
+}
+/**
+ * Build a coding-focused system prompt from composable sections.
+ *
+ * Returns a string that includes:
+ * - Agent identity
+ * - Available tools listing
+ * - Coding best practices
+ * - Tool argument formatting guidance
+ * - Project docs (if provided)
+ * - Discovered skills listing (if provided)
+ * - Inline skills (if provided)
+ * - Custom sections (if provided)
+ *
+ * @param ctx - Prompt construction inputs (tools, docs, skills, etc.).
+ * @returns Fully assembled system prompt text for the coding agent.
+ */
+export function buildAgentPrompt(ctx) {
+    const sections = [];
+    // Identity
+    sections.push(`You are ${ctx.agentName}, an AI coding agent with full access to the project at \`${ctx.projectRoot}\`.`);
+    // Tool listing
+    const toolLines = ctx.tools
+        .filter((name) => TOOL_DESCRIPTIONS[name] || TOOL_SCHEMAS[name])
+        .map((name) => `- **${name}** — ${TOOL_DESCRIPTIONS[name] || TOOL_SCHEMAS[name]?.description || ''}`);
+    if (toolLines.length > 0) {
+        sections.push(`\n## Available Tools\n\n${toolLines.join('\n')}`);
+    }
+    // Coding rules
+    sections.push(`
+## Coding Rules
+
+1. **Always read before editing.** Use read_file to understand the current content before making changes with edit_file or write_file. Never guess file contents.
+2. **Use edit_file for small changes.** When modifying a few lines in an existing file, use edit_file with precise search-and-replace. Use write_file only for new files or complete rewrites.
+3. **Implement fully.** Do not stop partway through a task. Do not describe remaining work — just do it. Do not ask "would you like me to continue?" — always continue.
+4. **Verify your changes.** After editing, use exec_command to run build checks or type-checks to catch errors immediately. Fix any errors before moving on.
+5. **Search before inventing.** Use search_files and find_files to discover existing patterns, utilities, and conventions before writing new code. Reuse what exists.
+6. **Keep changes minimal.** Fix what was asked. Do not refactor surrounding code, add comments to unchanged code, or "improve" things that weren't requested.
+
+## Tool Argument Formatting
+
+When passing file content to write_file or edit_file, use real newlines in the JSON string value — NOT literal \\\\n escape sequences. Your tool arguments are JSON-parsed, so a JSON string \`"line1\\nline2"\` produces actual newlines. Never double-escape.
+
+For edit_file: each old_string must match **exactly once** in the file. If it matches 0 times, you have the wrong string. If it matches multiple times, include more surrounding context to make it unique.`);
+    // Project docs
+    if (ctx.projectDocs) {
+        sections.push(`\n## Project Guidelines\n\n${ctx.projectDocs}`);
+    }
+    // Discovered skills (on-demand via load_skill)
+    if (ctx.discoveredSkills?.length) {
+        const skillLines = ctx.discoveredSkills.map((s) => `- **${s.name}** — ${s.description} \u2192 \`${s.path}\``);
+        sections.push(`\n## Available Skills\n\nThe project has detailed skill guides. Use \`load_skill\` to read them when relevant:\n${skillLines.join('\n')}`);
+    }
+    // Inline skills (full content injected directly)
+    if (ctx.skills?.length) {
+        sections.push(`\n## Reference\n\n${ctx.skills.join('\n\n')}`);
+    }
+    // Custom sections
+    if (ctx.customSections?.length) {
+        for (const section of ctx.customSections) {
+            sections.push(`\n${section}`);
+        }
+    }
+    return sections.join('\n');
+}

package/dist/tools.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tool factory — builds AITool[] from schemas + ExecutionBackend.
+ *
+ * Each tool's execute() delegates to the backend for I/O,
+ * with shared validation, path resolution, and output formatting.
+ *
+ * @module
+ */
+import type { AITool } from '@molecule/api-ai';
+import type { ExecutionBackend, ToolBuildConfig } from './types.js';
+/**
+ * Build a complete set of AI agent tools bound to an execution backend.
+ *
+ * @param backend - The execution environment (sandbox or local filesystem)
+ * @param config - Optional configuration for security, callbacks, and tool selection
+ * @returns Array of AITool objects ready to pass to an AI provider
+ */
+export declare function buildTools(backend: ExecutionBackend, config?: ToolBuildConfig): AITool[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAG9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoBnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CA0nBxF"}