ndomo 0.1.0

package/src/db/plan-archive.ts

@@ -0,0 +1,274 @@
+/**
+ * ndomo DB — Plan archive (serialize to markdown + soft delete).
+ *
+ * When a plan reaches a terminal status (completed/failed/abandoned),
+ * this module serializes it to a markdown file in <projectDir>/.ndomo/archives/plans/
+ * (resolved by the caller via resolveArchiveDir) and sets archived_at on the
+ * plan, its tasks, and its sessions.
+ *
+ * The archive is transactional: if the DB updates fail, the markdown
+ * file is rolled back (deleted) to maintain consistency.
+ */
+
+import type { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getPlan } from "./plans.ts";
+import { listSessions } from "./sessions.ts";
+import { listTasksByPlan } from "./tasks.ts";
+import type { Plan, PlanTask, Session } from "./types.ts";
+
+export interface ArchiveResult {
+  planId: string;
+  slug: string;
+  filePath: string;
+  byteSize: number;
+  archivedAt: number;
+  tasksCount: number;
+  sessionsCount: number;
+}
+
+/** Sanitize a slug to safe ASCII kebab-case for filenames. */
+function sanitizeSlug(slug: string): string {
+  return slug
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/--+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+/**
+ * Serialize a plan, its tasks, and sessions into a markdown string.
+ * Follows the exact format specified in the v5 migration spec.
+ */
+export function serializePlanToMarkdown(
+  plan: Plan,
+  tasks: PlanTask[],
+  sessions: Session[],
+  archivedAt: number,
+): string {
+  const archivedDate = new Date(archivedAt).toISOString();
+
+  const doneTasks = tasks.filter((t) => t.status === "done").length;
+  const failedTasks = tasks.filter((t) => t.status === "failed").length;
+
+  const taskLines = tasks.map((t) => {
+    const checkbox = t.status === "done" ? "[x]" : "[ ]";
+    const parts = [
+      `- ${checkbox} **${t.description}** — agent: ${t.agent}, complexity: ${t.complexity}, status: ${t.status}`,
+    ];
+    if (t.result) {
+      parts.push(`  - result: ${t.result}`);
+    }
+    if (t.error) {
+      parts.push(`  - error: ${t.error}`);
+    }
+    return parts.join("\n");
+  });
+
+  const sessionBlocks = sessions.map((s) => {
+    const idShort = s.id.slice(0, 8);
+    const lines = [
+      `### Session ${idShort}`,
+      "",
+      `- Started: ${s.startedAt ? new Date(s.startedAt).toISOString() : "N/A"}`,
+      `- Ended: ${s.endedAt ? new Date(s.endedAt).toISOString() : "ongoing"}`,
+      `- Goal: ${s.goal}`,
+    ];
+    if (s.keyDecisions) {
+      lines.push(`- Key decisions: ${s.keyDecisions}`);
+    }
+    return lines.join("\n");
+  });
+
+  const sections = [
+    `# Plan: ${plan.title}`,
+    "",
+    `**Slug:** ${plan.slug}  `,
+    `**Status:** ${plan.status}  `,
+    `**Archived:** ${archivedDate}  `,
+    `**Priority:** ${plan.priority}  `,
+    `**Complexity:** ${plan.complexity}  `,
+    `**Plan ID:** ${plan.id}`,
+    "",
+    "## Overview",
+    "",
+    plan.overview,
+  ];
+
+  // v8: agent execution tracking
+  if (plan.createdByAgent || plan.executedByAgent) {
+    sections.push("", "## Agent Trail", "");
+    if (plan.createdByAgent) {
+      sections.push(`- **Created by agent:** ${plan.createdByAgent}`);
+    }
+    if (plan.executedByAgent) {
+      sections.push(`- **Executed by agent:** ${plan.executedByAgent}`);
+    }
+    if (plan.executedBySession) {
+      sections.push(`- **Executed by session:** ${plan.executedBySession}`);
+    }
+  }
+
+  // v6: write-once audit trail — original plan data snapshot
+  // HIGH 6: sanitize triple backticks inside JSON to prevent markdown breakage
+  if (plan.originalPlanData) {
+    const safeJson = plan.originalPlanData.replace(/```/g, "\\`\\`\\`");
+    sections.push("", "## Original Plan Data (write-once)", "", "```json", safeJson, "```");
+  }
+
+  if (plan.approach) {
+    sections.push("", "## Approach", "", plan.approach);
+  }
+
+  sections.push(
+    "",
+    `## Tasks (${tasks.length} total, ${doneTasks} done, ${failedTasks} failed)`,
+    "",
+    ...taskLines,
+    "",
+    `## Sessions (${sessions.length})`,
+    "",
+    ...sessionBlocks,
+    "",
+    "## Metadata",
+    "",
+    "```json",
+    JSON.stringify(plan.metadata, null, 2),
+    "```",
+    "",
+  );
+
+  return sections.join("\n");
+}
+
+/**
+ * Build the archive filename from a plan slug and timestamp.
+ * Format: `<slug>-YYYY-MM-DD.md`
+ */
+export function buildArchiveFilename(plan: Plan, archivedAt: number): string {
+  const safeSlug = sanitizeSlug(plan.slug);
+  const d = new Date(archivedAt);
+  const year = d.getFullYear();
+  const month = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${safeSlug}-${year}-${month}-${day}.md`;
+}
+
+/**
+ * Resolve the per-project plan archive directory.
+ * Path: <projectDir>/.ndomo/archives/plans/
+ * Creates the directory if it does not exist.
+ *
+ * @param projectDir - Absolute path to the project root.
+ * @returns Absolute path to the archive directory.
+ */
+export function resolveArchiveDir(projectDir: string): string {
+  const dir = join(projectDir, ".ndomo", "archives", "plans");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Archive a plan: serialize to markdown + soft delete in DB.
+ *
+ * Steps:
+ * 1. Load plan (throw if not found or already archived)
+ * 2. Load tasks and sessions (including archived ones)
+ * 3. Resolve mem directory and ensure it exists
+ * 4. Serialize to markdown
+ * 5. Build filename (with HHMMSS suffix if file exists)
+ * 6. Write markdown file
+ * 7. Transactional DB update (archived_at on plan, tasks, sessions)
+ * 8. Rollback: unlink file if DB update fails
+ *
+ * @param db - Database instance
+ * @param planId - Plan ID to archive
+ * @param opts - Archive options.
+ * @param opts.memDir - Absolute path to the archive directory (required).
+ *   Typically resolved via {@link resolveArchiveDir}.
+ */
+export function archivePlan(db: Database, planId: string, opts: { memDir: string }): ArchiveResult {
+  // 1. Load plan
+  const plan = getPlan(db, planId);
+  if (!plan) {
+    throw new Error(`ndomo: plan not found: ${planId}`);
+  }
+  if (plan.archivedAt !== null) {
+    throw new Error("ndomo: plan already archived");
+  }
+
+  // 2. Load tasks and sessions (include archived for completeness)
+  const tasks = listTasksByPlan(db, planId, { includeArchived: true });
+  const sessions = listSessions(db, { planId, includeArchived: true, limit: 1000 });
+
+  // 3. Resolve mem directory
+  const memDir = opts.memDir;
+  mkdirSync(memDir, { recursive: true });
+
+  // 4. Serialize
+  const now = Date.now();
+  const md = serializePlanToMarkdown(plan, tasks, sessions, now);
+
+  // 5. Build filename (with HHMMSS suffix if collision)
+  let filename = buildArchiveFilename(plan, now);
+  let absPath = join(memDir, filename);
+  if (existsSync(absPath)) {
+    const d = new Date(now);
+    const hh = String(d.getHours()).padStart(2, "0");
+    const mm = String(d.getMinutes()).padStart(2, "0");
+    const ss = String(d.getSeconds()).padStart(2, "0");
+    const base = filename.replace(/\.md$/, "");
+    filename = `${base}-${hh}${mm}${ss}.md`;
+    absPath = join(memDir, filename);
+  }
+
+  // 6. Write markdown file
+  writeFileSync(absPath, md, "utf-8");
+
+  // 7. Transactional DB update
+  try {
+    const txn = db.transaction(() => {
+      db.query("UPDATE plans SET archived_at = ? WHERE id = ? AND archived_at IS NULL").run(
+        now,
+        planId,
+      );
+
+      // Verify the plan was actually archived (changes count includes FTS
+      // trigger side-effects in bun:sqlite, so we verify with a SELECT)
+      const check = db.query("SELECT archived_at FROM plans WHERE id = ?").get(planId) as {
+        archived_at: number | null;
+      } | null;
+      if (!check || check.archived_at === null) {
+        throw new Error("ndomo: archive failed — plan not archived after UPDATE");
+      }
+
+      db.query(
+        "UPDATE plan_tasks SET archived_at = ? WHERE plan_id = ? AND archived_at IS NULL",
+      ).run(now, planId);
+
+      db.query("UPDATE sessions SET archived_at = ? WHERE plan_id = ? AND archived_at IS NULL").run(
+        now,
+        planId,
+      );
+    });
+    txn();
+  } catch (err) {
+    // 8. Rollback: remove the markdown file
+    try {
+      unlinkSync(absPath);
+    } catch {
+      // Best-effort cleanup — file removal failure is non-fatal
+    }
+    throw err;
+  }
+
+  return {
+    planId,
+    slug: plan.slug,
+    filePath: absPath,
+    byteSize: Buffer.byteLength(md, "utf-8"),
+    archivedAt: now,
+    tasksCount: tasks.length,
+    sessionsCount: sessions.length,
+  };
+}

package/src/db/plan-create.test.ts

@@ -0,0 +1,276 @@
+/**
+ * Integration tests for planCreateExecutor — the extracted plan_create tool logic.
+ *
+ * Validates that the executor correctly:
+ * - Persists a plan with all mapped fields
+ * - Auto-creates a session row when ctx.sessionID is provided
+ * - Skips session creation when ctx.sessionID is undefined
+ * - Passes through metadata, priority, complexity, and other optional fields
+ *
+ * Uses in-memory SQLite via bun:sqlite. Each test gets a fresh DB
+ * with the full schema applied by runMigrations.
+ *
+ * NOTE: The DB enforces priority 1-4 via CHECK trigger, so all tests
+ * pass explicit priority values to avoid the default-0 constraint error.
+ * The executor's `priority: args.priority ?? 0` matches the original code.
+ */
+
+import { Database } from "bun:sqlite";
+import { beforeEach, describe, expect, test } from "bun:test";
+import { runMigrations } from "./migrations.ts";
+import { planCreateExecutor } from "./plan-create.ts";
+import { getPlan } from "./plans.ts";
+import { getSession } from "./sessions.ts";
+import { createTasksBatch, getTask } from "./tasks.ts";
+
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  db.exec("PRAGMA foreign_keys = ON");
+  runMigrations(db);
+});
+
+describe("planCreateExecutor", () => {
+  test("creates plan in DB with correct fields", () => {
+    const plan = planCreateExecutor(
+      db,
+      { slug: "test-2026-06-19", title: "My Test Plan", overview: "do stuff", priority: 2 },
+      { agent: "foreman", sessionID: "ses_test_int", messageID: "msg_test_int" },
+    );
+    expect(plan.slug).toBe("test-2026-06-19");
+    expect(plan.title).toBe("My Test Plan");
+    expect(plan.overview).toBe("do stuff");
+    expect(plan.status).toBe("draft");
+    expect(plan.priority).toBe(2);
+    expect(plan.complexity).toBe(3);
+    expect(plan.createdBy).toBe("foreman");
+    expect(plan.updatedBy).toBe("foreman");
+    expect(plan.sourceSessionId).toBe("ses_test_int");
+    expect(plan.sourceMessageId).toBe("msg_test_int");
+    // Verify it actually persisted
+    const fetched = getPlan(db, plan.id);
+    expect(fetched).not.toBeNull();
+    expect(fetched?.slug).toBe("test-2026-06-19");
+  });
+
+  test("auto-creates session row with goal derived from title", () => {
+    planCreateExecutor(
+      db,
+      { slug: "s2", title: "Title Two", overview: "o", priority: 2 },
+      { agent: "foreman", sessionID: "ses_auto_test" },
+    );
+    const sess = getSession(db, "ses_auto_test");
+    expect(sess).not.toBeNull();
+    expect(sess?.goal).toBe("Plan: Title Two");
+    expect(sess?.createdBy).toBe("auto");
+  });
+
+  test("does NOT create session when ctx.sessionID is undefined", () => {
+    planCreateExecutor(
+      db,
+      { slug: "s3", title: "No Sess", overview: "o", priority: 2 },
+      { agent: "foreman" }, // no sessionID
+    );
+    // Verify NO row in sessions table (the executor guarded the call)
+    const rows = db.query("SELECT * FROM sessions").all();
+    expect(rows).toHaveLength(0);
+  });
+
+  test("defaults agent to 'unknown' when ctx.agent is undefined", () => {
+    const plan = planCreateExecutor(
+      db,
+      { slug: "s4", title: "No Agent", overview: "o", priority: 2 },
+      {}, // no agent
+    );
+    expect(plan.createdBy).toBe("unknown");
+    expect(plan.updatedBy).toBe("unknown");
+  });
+
+  test("respects custom priority and complexity", () => {
+    const plan = planCreateExecutor(
+      db,
+      { slug: "s5", title: "Custom", overview: "o", priority: 4, complexity: 1 },
+      { agent: "test" },
+    );
+    expect(plan.priority).toBe(4);
+    expect(plan.complexity).toBe(1);
+  });
+
+  test("passes through approach field", () => {
+    const plan = planCreateExecutor(
+      db,
+      { slug: "s6", title: "With Approach", overview: "o", priority: 2, approach: "TDD first" },
+      { agent: "test" },
+    );
+    expect(plan.approach).toBe("TDD first");
+  });
+
+  test("passes through metadata with category", () => {
+    const plan = planCreateExecutor(
+      db,
+      {
+        slug: "s7",
+        title: "With Meta",
+        overview: "o",
+        priority: 2,
+        metadata: { category: "bugfix" },
+      },
+      { agent: "test" },
+    );
+    expect(plan.category).toBe("bugfix");
+    expect(plan.metadata.category).toBe("bugfix");
+  });
+
+  test("sessionId arg is stored on plan (distinct from ctx.sessionID)", () => {
+    const plan = planCreateExecutor(
+      db,
+      {
+        slug: "s8",
+        title: "Linked",
+        overview: "o",
+        priority: 2,
+        sessionId: "ses_linked",
+      },
+      { agent: "test", sessionID: "ses_source" },
+    );
+    // args.sessionId → plan.sessionId (the FK link)
+    expect(plan.sessionId).toBe("ses_linked");
+    // ctx.sessionID → plan.sourceSessionId (the origin)
+    expect(plan.sourceSessionId).toBe("ses_source");
+  });
+
+  test("sets created_by_agent from ctx.agent", () => {
+    const plan = planCreateExecutor(
+      db,
+      { slug: "s9", title: "Agent Test", overview: "o", priority: 2 },
+      { agent: "foreman" },
+    );
+    expect(plan.createdByAgent).toBe("foreman");
+
+    const fetched = getPlan(db, plan.id);
+    expect(fetched?.createdByAgent).toBe("foreman");
+  });
+
+  test("created_by_agent defaults to null when ctx.agent is undefined", () => {
+    const plan = planCreateExecutor(
+      db,
+      { slug: "s10", title: "No Agent", overview: "o", priority: 2 },
+      {},
+    );
+    expect(plan.createdByAgent).toBeNull();
+  });
+
+  test("original_plan_data is set on creation", () => {
+    const plan = planCreateExecutor(
+      db,
+      { slug: "s11", title: "Snapshot", overview: "do stuff", priority: 2 },
+      { agent: "foreman" },
+    );
+    expect(plan.originalPlanData).not.toBeNull();
+
+    const fetched = getPlan(db, plan.id);
+    const opd = fetched?.originalPlanData;
+    expect(opd).not.toBeNull();
+
+    const data = JSON.parse(opd as string);
+    expect(data.slug).toBe("s11");
+    expect(data.title).toBe("Snapshot");
+    expect(data.createdBy).toBe("foreman");
+  });
+});
+
+describe("createTasksBatch", () => {
+  test("updated_by defaults to createdBy when undefined", () => {
+    const plan = planCreateExecutor(
+      db,
+      { slug: "task-test", title: "Task Test", overview: "test", priority: 2 },
+      { agent: "foreman" },
+    );
+
+    const tasks = createTasksBatch(db, plan.id, [
+      {
+        orderIndex: 0,
+        description: "test task",
+        agent: "js-smith",
+        files: [],
+        complexity: 1,
+        dependencies: [],
+        createdBy: "foreman",
+        updatedBy: undefined as unknown as string, // explicitly undefined
+        sourceSessionId: null,
+        sourceMessageId: null,
+        reviewedBy: null,
+        tokensUsed: null,
+        durationMs: null,
+        artifacts: [],
+        metadata: {},
+      },
+    ]);
+
+    expect(tasks).toHaveLength(1);
+    expect(tasks[0]).toBeDefined();
+    const task0id = tasks[0]?.id as string;
+    const fetched = getTask(db, task0id);
+    expect(fetched).not.toBeNull();
+    expect(fetched?.updatedBy).toBe("foreman"); // defaults to createdBy
+  });
+});
+
+// ─── Issue 3: plan_files insertion ───────────────────────────────────────────
+
+describe("planCreateExecutor — plan_files insertion", () => {
+  test("with files → N rows in plan_files with role='input'", () => {
+    const plan = planCreateExecutor(
+      db,
+      {
+        slug: "files-test",
+        title: "Files Test",
+        overview: "o",
+        priority: 2,
+        files: ["src/a.ts", "src/b.ts"],
+      },
+      { agent: "foreman" },
+    );
+
+    const rows = db
+      .query("SELECT * FROM plan_files WHERE plan_id = ? ORDER BY file_path")
+      .all(plan.id) as Array<{ plan_id: string; file_path: string; role: string }>;
+
+    expect(rows).toHaveLength(2);
+    expect(rows[0]?.file_path).toBe("src/a.ts");
+    expect(rows[0]?.role).toBe("input");
+    expect(rows[1]?.file_path).toBe("src/b.ts");
+    expect(rows[1]?.role).toBe("input");
+  });
+
+  test("without files → 0 rows in plan_files", () => {
+    const plan = planCreateExecutor(
+      db,
+      { slug: "no-files", title: "No Files", overview: "o", priority: 2 },
+      { agent: "foreman" },
+    );
+
+    const rows = db.query("SELECT * FROM plan_files WHERE plan_id = ?").all(plan.id);
+
+    expect(rows).toHaveLength(0);
+  });
+
+  test("duplicate files → no break (PK dedup)", () => {
+    const plan = planCreateExecutor(
+      db,
+      {
+        slug: "dup-files",
+        title: "Dup",
+        overview: "o",
+        priority: 2,
+        files: ["src/x.ts", "src/x.ts"],
+      },
+      { agent: "foreman" },
+    );
+
+    const rows = db.query("SELECT * FROM plan_files WHERE plan_id = ?").all(plan.id);
+
+    expect(rows).toHaveLength(1); // PK dedup
+  });
+});

package/src/db/plan-create.ts

@@ -0,0 +1,78 @@
+/**
+ * ndomo DB — plan_create tool executor.
+ *
+ * Pure function extracted from the MCP tool wrapper in src/plugin.ts
+ * to enable unit testing without spinning up the full MCP harness.
+ *
+ * Behavior preserved verbatim from the original execute function.
+ */
+
+import type { Database } from "bun:sqlite";
+import { createPlan } from "./plans.ts";
+import { ensureSession } from "./sessions.ts";
+import type { Plan, PlanMetadata } from "./types.ts";
+
+export interface PlanCreateArgs {
+  slug: string;
+  title: string;
+  overview: string;
+  approach?: string | undefined;
+  priority?: number | undefined;
+  complexity?: number | undefined;
+  sessionId?: string | undefined;
+  metadata?: PlanMetadata | undefined;
+  files?: string[] | undefined;
+}
+
+export interface PlanCreateContext {
+  agent?: string | undefined;
+  sessionID?: string | undefined;
+  messageID?: string | undefined;
+}
+
+export function planCreateExecutor(
+  db: Database,
+  args: PlanCreateArgs,
+  ctx: PlanCreateContext,
+): Plan {
+  const typedMeta = (args.metadata ?? {}) as PlanMetadata;
+  // Fix: auto-create session row for FK integrity (hybrid (a) — eager)
+  if (ctx.sessionID) {
+    ensureSession(db, ctx.sessionID, `Plan: ${args.title}`);
+  }
+  const plan = createPlan(db, {
+    id: crypto.randomUUID(),
+    slug: args.slug,
+    title: args.title,
+    status: "draft" as const,
+    priority: args.priority ?? 0,
+    approvedAt: null,
+    completedAt: null,
+    sessionId: args.sessionId ?? null,
+    overview: args.overview,
+    approach: args.approach ?? null,
+    complexity: args.complexity ?? 3,
+    createdBy: ctx.agent ?? "unknown",
+    updatedBy: ctx.agent ?? "unknown",
+    sourceSessionId: ctx.sessionID ?? null,
+    sourceMessageId: ctx.messageID ?? null,
+    category: typedMeta.category ?? null,
+    metadata: typedMeta,
+    archivedAt: null,
+    originalPlanData: null,
+    createdByAgent: ctx.agent ?? null,
+    executedByAgent: null,
+    executedBySession: null,
+  });
+
+  // Issue 3: insert files into plan_files with role='input'
+  if (args.files && args.files.length > 0) {
+    for (const filePath of args.files) {
+      db.query(
+        "INSERT OR IGNORE INTO plan_files (plan_id, file_path, role) VALUES (?, ?, 'input')",
+      ).run(plan.id, filePath);
+    }
+  }
+
+  return plan;
+}