@a13xu/lucid 1.9.5 → 1.10.0

package/build/database.d.ts

@@ -36,6 +36,27 @@ export interface FileRewardRow {
     use_count: number;
     last_rewarded: number | null;
 }
+export interface PlanRow {
+    id: number;
+    title: string;
+    description: string;
+    user_story: string;
+    status: string;
+    created_at: number;
+    updated_at: number;
+}
+export interface PlanTaskRow {
+    id: number;
+    plan_id: number;
+    seq: number;
+    title: string;
+    description: string;
+    test_criteria: string;
+    status: string;
+    notes: string;
+    created_at: number;
+    updated_at: number;
+}
 export interface Statements {
     getFileByPath: Stmt<[string], FileContentRow>;
     upsertFile: WriteStmt<[string, Buffer, string, number, number, string]>;
@@ -83,6 +104,17 @@ export interface Statements {
     upsertFileReward: WriteStmt<[string, number]>;
     getFileRewards: Stmt<[], FileRewardRow>;
     getTopFileRewards: Stmt<[number], FileRewardRow>;
+    insertPlan: WriteStmt<[string, string, string]>;
+    getPlanById: Stmt<[number], PlanRow>;
+    getAllPlans: Stmt<[], PlanRow>;
+    updatePlanStatus: WriteStmt<[string, number]>;
+    insertPlanTask: WriteStmt<[number, number, string, string, string]>;
+    getTasksByPlanId: Stmt<[number], PlanTaskRow>;
+    getTaskById: Stmt<[number], PlanTaskRow>;
+    updateTaskStatus: WriteStmt<[string, string, number]>;
+    countRemainingTasks: Stmt<[number], {
+        count: number;
+    }>;
 }
 export declare function prepareStatements(db: Database.Database): Statements;
 export {};

package/build/database.js

@@ -143,6 +143,33 @@ function createSchema(db) {
       use_count     INTEGER NOT NULL DEFAULT 0,
       last_rewarded INTEGER
     );
+
+    -- Planning tables
+    CREATE TABLE IF NOT EXISTS plans (
+      id          INTEGER PRIMARY KEY,
+      title       TEXT NOT NULL,
+      description TEXT NOT NULL,
+      user_story  TEXT NOT NULL,
+      status      TEXT NOT NULL DEFAULT 'active',
+      created_at  INTEGER DEFAULT (unixepoch()),
+      updated_at  INTEGER DEFAULT (unixepoch())
+    );
+
+    CREATE TABLE IF NOT EXISTS plan_tasks (
+      id            INTEGER PRIMARY KEY,
+      plan_id       INTEGER NOT NULL REFERENCES plans(id) ON DELETE CASCADE,
+      seq           INTEGER NOT NULL,
+      title         TEXT NOT NULL,
+      description   TEXT NOT NULL,
+      test_criteria TEXT NOT NULL,
+      status        TEXT NOT NULL DEFAULT 'pending',
+      notes         TEXT NOT NULL DEFAULT '[]',
+      created_at    INTEGER DEFAULT (unixepoch()),
+      updated_at    INTEGER DEFAULT (unixepoch())
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_plan_tasks_plan ON plan_tasks(plan_id, seq);
+    CREATE INDEX IF NOT EXISTS idx_plans_status    ON plans(status);
   `);
 }
 export function prepareStatements(db) {
@@ -223,5 +250,16 @@ export function prepareStatements(db) {
          last_rewarded = unixepoch()`),
         getFileRewards: db.prepare("SELECT * FROM file_rewards"),
         getTopFileRewards: db.prepare("SELECT * FROM file_rewards WHERE total_reward > 0 ORDER BY total_reward DESC LIMIT ?"),
+        // plans
+        insertPlan: db.prepare("INSERT INTO plans (title, description, user_story) VALUES (?, ?, ?)"),
+        getPlanById: db.prepare("SELECT * FROM plans WHERE id = ?"),
+        getAllPlans: db.prepare("SELECT * FROM plans ORDER BY created_at DESC"),
+        updatePlanStatus: db.prepare("UPDATE plans SET status = ?, updated_at = unixepoch() WHERE id = ?"),
+        // plan_tasks
+        insertPlanTask: db.prepare("INSERT INTO plan_tasks (plan_id, seq, title, description, test_criteria) VALUES (?, ?, ?, ?, ?)"),
+        getTasksByPlanId: db.prepare("SELECT * FROM plan_tasks WHERE plan_id = ? ORDER BY seq"),
+        getTaskById: db.prepare("SELECT * FROM plan_tasks WHERE id = ?"),
+        updateTaskStatus: db.prepare("UPDATE plan_tasks SET status = ?, notes = ?, updated_at = unixepoch() WHERE id = ?"),
+        countRemainingTasks: db.prepare("SELECT COUNT(*) as count FROM plan_tasks WHERE plan_id = ? AND status != 'done'"),
     };
 }

package/build/index.js

@@ -20,6 +20,7 @@ import { handleSyncFile, SyncFileSchema, handleSyncProject, SyncProjectSchema, }
 import { handleGetContext, GetContextSchema, handleGetRecent, GetRecentSchema, } from "./tools/context.js";
 import { handleReward, RewardSchema, handlePenalize, PenalizeSchema, handleShowRewards, ShowRewardsSchema, } from "./tools/reward.js";
 import { handleGetCodingRules, handleCheckCodeQuality, CheckCodeQualitySchema, } from "./tools/coding-guard.js";
+import { handlePlanCreate, PlanCreateSchema, handlePlanList, PlanListSchema, handlePlanGet, PlanGetSchema, handlePlanUpdateTask, PlanUpdateTaskSchema, } from "./tools/plan.js";
 // ---------------------------------------------------------------------------
 // Init DB
 // ---------------------------------------------------------------------------
@@ -52,7 +53,7 @@ else {
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
-const server = new Server({ name: "lucid", version: "1.9.5" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "lucid", version: "1.10.0" }, { capabilities: { tools: {} } });
 // ---------------------------------------------------------------------------
 // Tool definitions
 // ---------------------------------------------------------------------------
@@ -322,6 +323,75 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
             },
         },
+        // ── Planning ─────────────────────────────────────────────────────────────
+        {
+            name: "plan_create",
+            description: "Create a plan with user story, ordered tasks, and test criteria. " +
+                "Call BEFORE writing any code to establish intent and acceptance criteria.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    title: { type: "string", description: "Short plan title." },
+                    description: { type: "string", description: "What this plan accomplishes." },
+                    user_story: { type: "string", description: "As a [user], I want [goal], so that [benefit]." },
+                    tasks: {
+                        type: "array",
+                        description: "Ordered list of implementation tasks (1–20).",
+                        items: {
+                            type: "object",
+                            properties: {
+                                title: { type: "string" },
+                                description: { type: "string" },
+                                test_criteria: { type: "string", description: "How to verify this task is done." },
+                            },
+                            required: ["title", "description", "test_criteria"],
+                        },
+                        minItems: 1,
+                        maxItems: 20,
+                    },
+                },
+                required: ["title", "description", "user_story", "tasks"],
+            },
+        },
+        {
+            name: "plan_list",
+            description: "List plans with progress summary. Defaults to active plans.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    status: {
+                        type: "string",
+                        enum: ["active", "completed", "abandoned", "all"],
+                        description: "Filter by plan status (default: active).",
+                    },
+                },
+            },
+        },
+        {
+            name: "plan_get",
+            description: "Get full plan details: tasks, test criteria, status, and notes.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    plan_id: { type: "number", description: "Plan ID from plan_create or plan_list." },
+                },
+                required: ["plan_id"],
+            },
+        },
+        {
+            name: "plan_update_task",
+            description: "Update a task status. Auto-completes the plan when all tasks are done. " +
+                "Statuses: pending → in_progress → done (or blocked).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "number", description: "Task ID from plan_get." },
+                    status: { type: "string", enum: ["pending", "in_progress", "done", "blocked"] },
+                    note: { type: "string", description: "Optional note appended to task history." },
+                },
+                required: ["task_id", "status"],
+            },
+        },
     ],
 }));
 // ---------------------------------------------------------------------------
@@ -404,6 +474,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "check_code_quality":
                 text = handleCheckCodeQuality(CheckCodeQualitySchema.parse(args));
                 break;
+            // Planning
+            case "plan_create":
+                text = handlePlanCreate(db, stmts, PlanCreateSchema.parse(args));
+                break;
+            case "plan_list":
+                text = handlePlanList(stmts, PlanListSchema.parse(args));
+                break;
+            case "plan_get":
+                text = handlePlanGet(stmts, PlanGetSchema.parse(args));
+                break;
+            case "plan_update_task":
+                text = handlePlanUpdateTask(stmts, PlanUpdateTaskSchema.parse(args));
+                break;
             default:
                 return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
         }

package/build/tools/plan.d.ts

@@ -0,0 +1,75 @@
+import Database from "better-sqlite3";
+import { z } from "zod";
+import type { Statements } from "../database.js";
+export declare const PlanCreateSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodString;
+    user_story: z.ZodString;
+    tasks: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodString;
+        test_criteria: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        title: string;
+        test_criteria: string;
+    }, {
+        description: string;
+        title: string;
+        test_criteria: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    title: string;
+    user_story: string;
+    tasks: {
+        description: string;
+        title: string;
+        test_criteria: string;
+    }[];
+}, {
+    description: string;
+    title: string;
+    user_story: string;
+    tasks: {
+        description: string;
+        title: string;
+        test_criteria: string;
+    }[];
+}>;
+export declare const PlanListSchema: z.ZodObject<{
+    status: z.ZodDefault<z.ZodOptional<z.ZodEnum<["active", "completed", "abandoned", "all"]>>>;
+}, "strip", z.ZodTypeAny, {
+    status: "all" | "active" | "completed" | "abandoned";
+}, {
+    status?: "all" | "active" | "completed" | "abandoned" | undefined;
+}>;
+export declare const PlanGetSchema: z.ZodObject<{
+    plan_id: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    plan_id: number;
+}, {
+    plan_id: number;
+}>;
+export declare const PlanUpdateTaskSchema: z.ZodObject<{
+    task_id: z.ZodNumber;
+    status: z.ZodEnum<["pending", "in_progress", "done", "blocked"]>;
+    note: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "blocked" | "done" | "pending" | "in_progress";
+    task_id: number;
+    note?: string | undefined;
+}, {
+    status: "blocked" | "done" | "pending" | "in_progress";
+    task_id: number;
+    note?: string | undefined;
+}>;
+type PlanCreateArgs = z.infer<typeof PlanCreateSchema>;
+type PlanListArgs = z.infer<typeof PlanListSchema>;
+type PlanGetArgs = z.infer<typeof PlanGetSchema>;
+type PlanUpdateTaskArgs = z.infer<typeof PlanUpdateTaskSchema>;
+export declare function handlePlanCreate(db: Database.Database, stmts: Statements, args: PlanCreateArgs): string;
+export declare function handlePlanList(stmts: Statements, args: PlanListArgs): string;
+export declare function handlePlanGet(stmts: Statements, args: PlanGetArgs): string;
+export declare function handlePlanUpdateTask(stmts: Statements, args: PlanUpdateTaskArgs): string;
+export {};

package/build/tools/plan.js

@@ -0,0 +1,148 @@
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+export const PlanCreateSchema = z.object({
+    title: z.string().min(1),
+    description: z.string().min(1),
+    user_story: z.string().min(1).describe("As a [user], I want [goal], so that [benefit]"),
+    tasks: z.array(z.object({
+        title: z.string().min(1),
+        description: z.string().min(1),
+        test_criteria: z.string().min(1),
+    })).min(1).max(20),
+});
+export const PlanListSchema = z.object({
+    status: z.enum(["active", "completed", "abandoned", "all"]).optional().default("active"),
+});
+export const PlanGetSchema = z.object({
+    plan_id: z.number().int().positive(),
+});
+export const PlanUpdateTaskSchema = z.object({
+    task_id: z.number().int().positive(),
+    status: z.enum(["pending", "in_progress", "done", "blocked"]),
+    note: z.string().optional(),
+});
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const STATUS_ICONS = {
+    pending: "⬜",
+    in_progress: "🔄",
+    done: "✅",
+    blocked: "🚫",
+};
+const PLAN_STATUS_ICONS = {
+    active: "active",
+    completed: "completed",
+    abandoned: "abandoned",
+};
+function progressBar(done, total) {
+    if (total === 0)
+        return "░".repeat(10);
+    const filled = Math.round((done / total) * 10);
+    return "█".repeat(filled) + "░".repeat(10 - filled);
+}
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+export function handlePlanCreate(db, stmts, args) {
+    const { title, description, user_story, tasks } = args;
+    const planId = db.transaction(() => {
+        const result = stmts.insertPlan.run(title, description, user_story);
+        const id = result.lastInsertRowid;
+        for (let i = 0; i < tasks.length; i++) {
+            const t = tasks[i];
+            stmts.insertPlanTask.run(id, i + 1, t.title, t.description, t.test_criteria);
+        }
+        return id;
+    })();
+    const lines = [
+        `[PLAN #${planId} active] ${title}`,
+        `User Story: ${user_story}`,
+        ``,
+    ];
+    for (let i = 0; i < tasks.length; i++) {
+        lines.push(`[TASK ${i + 1} #${planId * 100 + i + 1} pending] ${tasks[i].title}`);
+    }
+    lines.push(``, `Progress: 0/${tasks.length} done`);
+    return lines.join("\n");
+}
+export function handlePlanList(stmts, args) {
+    const { status } = args;
+    const all = stmts.getAllPlans.all();
+    const filtered = status === "all" ? all : all.filter(p => p.status === status);
+    if (filtered.length === 0) {
+        return `No ${status === "all" ? "" : status + " "}plans found.`;
+    }
+    const lines = [];
+    for (const plan of filtered) {
+        const tasks = stmts.getTasksByPlanId.all(plan.id);
+        const doneCount = tasks.filter(t => t.status === "done").length;
+        const label = PLAN_STATUS_ICONS[plan.status] ?? plan.status;
+        lines.push(`[#${plan.id} ${label}] ${plan.title} — ${doneCount}/${tasks.length} tasks done`);
+    }
+    return lines.join("\n");
+}
+export function handlePlanGet(stmts, args) {
+    const plan = stmts.getPlanById.get(args.plan_id);
+    if (!plan)
+        return `Error: Plan #${args.plan_id} not found.`;
+    const tasks = stmts.getTasksByPlanId.all(plan.id);
+    const doneCount = tasks.filter(t => t.status === "done").length;
+    const total = tasks.length;
+    const bar = progressBar(doneCount, total);
+    const label = PLAN_STATUS_ICONS[plan.status] ?? plan.status;
+    const lines = [
+        `[PLAN #${plan.id} | ${label}] ${plan.title}`,
+        `User Story: ${plan.user_story}`,
+        `Progress: ${doneCount}/${total} done ${bar}`,
+        ``,
+    ];
+    for (const task of tasks) {
+        const icon = STATUS_ICONS[task.status] ?? "❓";
+        lines.push(`[${task.seq}] ${icon} ${task.status}  — ${task.title}`);
+        lines.push(`    Desc: ${task.description}`);
+        lines.push(`    Test: ${task.test_criteria}`);
+        let parsedNotes = [];
+        try {
+            parsedNotes = JSON.parse(task.notes);
+        }
+        catch { /* ignore */ }
+        for (const n of parsedNotes) {
+            const date = new Date(n.ts * 1000).toISOString().slice(0, 10);
+            lines.push(`    Note: ${date} — ${n.text}`);
+        }
+        lines.push(``);
+    }
+    return lines.join("\n").trimEnd();
+}
+export function handlePlanUpdateTask(stmts, args) {
+    const { task_id, status, note } = args;
+    const task = stmts.getTaskById.get(task_id);
+    if (!task)
+        return `Error: Task #${task_id} not found.`;
+    let notes = [];
+    try {
+        notes = JSON.parse(task.notes);
+    }
+    catch { /* ignore */ }
+    if (note) {
+        notes.push({ text: note, ts: Math.floor(Date.now() / 1000) });
+    }
+    const notesJson = JSON.stringify(notes);
+    stmts.updateTaskStatus.run(status, notesJson, task_id);
+    const lines = [`✅ Task #${task_id} → ${status}`];
+    if (status === "done") {
+        const remaining = stmts.countRemainingTasks.get(task.plan_id);
+        if (remaining && remaining.count === 0) {
+            stmts.updatePlanStatus.run("completed", task.plan_id);
+            const plan = stmts.getPlanById.get(task.plan_id);
+            const taskCount = stmts.getTasksByPlanId.all(task.plan_id).length;
+            lines.push(`🎉 Plan #${task.plan_id} completat! Toate ${taskCount} task-uri done.`);
+            if (plan)
+                lines.push(`   "${plan.title}"`);
+        }
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a13xu/lucid",
-  "version": "1.9.5",
+  "version": "1.10.0",
   "description": "Token-efficient memory, code indexing, and validation for Claude Code agents — SQLite + FTS5, TF-IDF + Qdrant retrieval, AST skeleton pruning, diff-aware context, Logic Guardian drift detection",
   "type": "module",
   "bin": {