@compilr-dev/sdk 0.1.7 → 0.1.8

package/dist/platform/tools/plan-tools.js

@@ -0,0 +1,325 @@
+/**
+ * Plan Tools — CRUD operations for plans.
+ *
+ * 5 tools: plan_create, plan_update, plan_get, plan_list, plan_delete
+ *
+ * Ported from CLI's src/tools/plan-tools.ts.
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createPlanTools(config) {
+    const { context: ctx } = config;
+    // ---------------------------------------------------------------------------
+    // plan_create
+    // ---------------------------------------------------------------------------
+    const planCreateTool = defineTool({
+        name: 'plan_create',
+        description: 'Create a new plan for the current project. Plans are used to document implementation approaches before coding. The plan is created with "draft" status.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Plan name (kebab-case, 3-5 words). Example: "auth-jwt-migration", "add-dark-mode-toggle"',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Plan content in markdown format. Should include: Context, Goals, Steps, Verification sections.',
+                },
+                work_item_id: {
+                    type: 'number',
+                    description: 'Optional: ID of the work item this plan is for. Links the plan to a backlog item.',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID (uses active project if not provided)',
+                },
+            },
+            required: ['name', 'content'],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
+                }
+                // Validate name format (kebab-case)
+                if (!/^[a-z][a-z0-9-]*[a-z0-9]$/.test(input.name) && input.name.length > 2) {
+                    if (input.name.length > 2 && !/^[a-z0-9-]+$/.test(input.name)) {
+                        return createErrorResult('Plan name should be kebab-case (lowercase letters, numbers, hyphens). Example: "auth-jwt-migration"');
+                    }
+                }
+                const createInput = {
+                    project_id: projectId,
+                    name: input.name,
+                    content: input.content,
+                    work_item_id: input.work_item_id,
+                };
+                const plan = await ctx.plans.create(createInput);
+                return createSuccessResult({
+                    success: true,
+                    message: `Plan "${plan.name}" created`,
+                    plan: {
+                        id: plan.id,
+                        name: plan.name,
+                        status: plan.status,
+                        workItemId: plan.workItemId,
+                        createdAt: plan.createdAt.toISOString(),
+                    },
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to create plan: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // plan_update
+    // ---------------------------------------------------------------------------
+    const planUpdateTool = defineTool({
+        name: 'plan_update',
+        description: 'Update an existing plan. Can update content, status, or work item link. Status transitions: draft→approved→in_progress→completed. Any status can transition to "abandoned".',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                plan_id: {
+                    type: 'number',
+                    description: 'ID of the plan to update',
+                },
+                content: {
+                    type: 'string',
+                    description: 'New plan content (optional)',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['draft', 'approved', 'in_progress', 'completed', 'abandoned'],
+                    description: 'New status (optional). Valid transitions: draft→approved, approved→in_progress, in_progress→completed. Any→abandoned. abandoned→draft.',
+                },
+                work_item_id: {
+                    type: ['number', 'null'],
+                    description: 'Work item ID to link (optional). Use null to unlink.',
+                },
+            },
+            required: ['plan_id'],
+        },
+        execute: async (input) => {
+            try {
+                const updateInput = {};
+                if (input.content !== undefined) {
+                    updateInput.content = input.content;
+                }
+                if (input.status !== undefined) {
+                    updateInput.status = input.status;
+                }
+                if (input.work_item_id !== undefined) {
+                    updateInput.work_item_id = input.work_item_id;
+                }
+                const plan = await ctx.plans.update(input.plan_id, updateInput);
+                if (!plan) {
+                    return createErrorResult(`Plan with ID ${String(input.plan_id)} not found`);
+                }
+                return createSuccessResult({
+                    success: true,
+                    message: `Plan "${plan.name}" updated`,
+                    plan: {
+                        id: plan.id,
+                        name: plan.name,
+                        status: plan.status,
+                        workItemId: plan.workItemId,
+                        updatedAt: plan.updatedAt.toISOString(),
+                    },
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to update plan: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // plan_get
+    // ---------------------------------------------------------------------------
+    const planGetTool = defineTool({
+        name: 'plan_get',
+        description: 'Get a plan by ID or name. Returns the full plan content and linked work item details.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                plan_id: {
+                    type: 'number',
+                    description: 'Plan ID (preferred)',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Plan name (alternative to ID)',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID (required if using name, uses active project if not provided)',
+                },
+            },
+            required: [],
+        },
+        execute: async (input) => {
+            try {
+                let plan;
+                if (input.plan_id) {
+                    plan = await ctx.plans.getWithWorkItem(input.plan_id);
+                }
+                else if (input.name) {
+                    const projectId = input.project_id ?? ctx.currentProjectId;
+                    if (!projectId) {
+                        return createErrorResult('No project specified and no active project. Provide plan_id or project_id.');
+                    }
+                    const basePlan = await ctx.plans.getByName(projectId, input.name);
+                    if (basePlan) {
+                        plan = await ctx.plans.getWithWorkItem(basePlan.id);
+                    }
+                }
+                else {
+                    return createErrorResult('Either plan_id or name is required');
+                }
+                if (!plan) {
+                    return createSuccessResult({
+                        success: true,
+                        plan: null,
+                        message: 'Plan not found',
+                    });
+                }
+                return createSuccessResult({
+                    success: true,
+                    plan: {
+                        id: plan.id,
+                        name: plan.name,
+                        content: plan.content,
+                        status: plan.status,
+                        workItemId: plan.workItemId,
+                        workItem: plan.workItem
+                            ? {
+                                id: plan.workItem.id,
+                                itemId: plan.workItem.itemId,
+                                title: plan.workItem.title,
+                                status: plan.workItem.status,
+                            }
+                            : null,
+                        createdAt: plan.createdAt.toISOString(),
+                        updatedAt: plan.updatedAt.toISOString(),
+                    },
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to get plan: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // plan_list
+    // ---------------------------------------------------------------------------
+    const planListTool = defineTool({
+        name: 'plan_list',
+        description: 'List plans for a project. Supports filtering by status and work item. Returns plan summaries without full content.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID (uses active project if not provided)',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['draft', 'approved', 'in_progress', 'completed', 'abandoned', 'all'],
+                    description: 'Filter by status (default: all)',
+                },
+                work_item_id: {
+                    type: 'number',
+                    description: 'Filter by linked work item',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum plans to return (default: 20)',
+                },
+                order_by: {
+                    type: 'string',
+                    enum: ['updated_desc', 'updated_asc', 'created_desc', 'name_asc'],
+                    description: 'Sort order (default: updated_desc)',
+                },
+            },
+            required: [],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
+                }
+                const options = {
+                    limit: input.limit ?? 20,
+                    order_by: input.order_by ?? 'updated_desc',
+                };
+                if (input.status && input.status !== 'all') {
+                    options.status = input.status;
+                }
+                if (input.work_item_id !== undefined) {
+                    options.work_item_id = input.work_item_id;
+                }
+                const plans = await ctx.plans.list(projectId, options);
+                const counts = await ctx.plans.countByStatus(projectId);
+                const planSummaries = plans.map((plan) => ({
+                    id: plan.id,
+                    name: plan.name,
+                    status: plan.status,
+                    workItemId: plan.workItemId,
+                    workItemTitle: plan.workItemTitle,
+                    workItemItemId: plan.workItemItemId,
+                    updatedAt: plan.updatedAt.toISOString(),
+                }));
+                return createSuccessResult({
+                    success: true,
+                    plans: planSummaries,
+                    count: planSummaries.length,
+                    statusCounts: counts,
+                    projectId,
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to list plans: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // plan_delete
+    // ---------------------------------------------------------------------------
+    const planDeleteTool = defineTool({
+        name: 'plan_delete',
+        description: 'Delete a plan by ID. This action cannot be undone.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                plan_id: {
+                    type: 'number',
+                    description: 'ID of the plan to delete',
+                },
+            },
+            required: ['plan_id'],
+        },
+        execute: async (input) => {
+            try {
+                const plan = await ctx.plans.getById(input.plan_id);
+                if (!plan) {
+                    return createErrorResult(`Plan with ID ${String(input.plan_id)} not found`);
+                }
+                const deleted = await ctx.plans.delete(input.plan_id);
+                if (!deleted) {
+                    return createErrorResult(`Failed to delete plan "${plan.name}"`);
+                }
+                return createSuccessResult({
+                    success: true,
+                    message: `Plan "${plan.name}" deleted`,
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to delete plan: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    return [planCreateTool, planUpdateTool, planGetTool, planListTool, planDeleteTool];
+}

package/dist/platform/tools/project-tools.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Project Tools — CRUD operations for projects.
+ *
+ * 4 tools: project_get, project_create, project_update, project_list
+ *
+ * Ported from CLI's src/tools/project-db.ts. Key adaptations:
+ * - getActiveProject()?.id → ctx.currentProjectId
+ * - setCurrentProject() → ctx.currentProjectId = id + hooks?.onProjectResolved()
+ * - awardFirstProject() → hooks?.onFirstProject()
+ * - process.cwd() → config.cwd ?? process.cwd()
+ * - All repo calls are properly await-ed
+ */
+import type { PlatformToolsConfig } from '../context.js';
+export declare function createProjectTools(config: PlatformToolsConfig): (import("@compilr-dev/agents").Tool<{
+    project_id?: number;
+    name?: string;
+    path?: string;
+}> | import("@compilr-dev/agents").Tool<{
+    name: string;
+    display_name: string;
+    description?: string;
+    path?: string;
+    type?: string;
+    workflow_mode?: string;
+    language?: string;
+    framework?: string;
+    package_manager?: string;
+}> | import("@compilr-dev/agents").Tool<{
+    project_id?: number;
+    status?: string;
+    description?: string;
+    workflow_mode?: string;
+    lifecycle_state?: string;
+    current_item_id?: string;
+    git_remote?: string;
+    git_branch?: string;
+    last_context?: Record<string, unknown>;
+}> | import("@compilr-dev/agents").Tool<{
+    status?: string;
+    limit?: number;
+}>)[];