@mrclrchtr/supi-flow 0.6.1

package/src/cli.ts

@@ -0,0 +1,80 @@
+import { execFile } from "node:child_process";
+
+type ExecResult = { stdout: string; stderr: string };
+
+function toString(data: string | Buffer): string {
+  return typeof data === "string" ? data : data.toString("utf-8");
+}
+
+async function run(
+  file: string,
+  args: string[],
+  options?: { maxBuffer?: number; timeout?: number },
+): Promise<ExecResult> {
+  return new Promise<ExecResult>((resolve, reject) => {
+    const child = execFile(file, args, options, (error, stdout, stderr) => {
+      if (error) {
+        const msg = toString(stderr).trim() || error.message;
+        reject(new Error(`"${file} ${args.join(" ")}" failed: ${msg}`));
+        return;
+      }
+      resolve({
+        stdout: toString(stdout).trim(),
+        stderr: toString(stderr).trim(),
+      });
+    });
+  });
+}
+
+/**
+ * Run a tndm subcommand and return stdout/stderr.
+ * Throws on non-zero exit, timeout, or other exec error.
+ */
+export async function tndm(args: string[]): Promise<ExecResult> {
+  return run("tndm", args, { timeout: 30_000 });
+}
+
+/**
+ * Run a tndm subcommand with `--json` and parse the structured output.
+ * Throws if exit is non-zero or JSON is invalid.
+ */
+export async function tndmJson<T = Record<string, unknown>>(
+  args: string[],
+): Promise<T> {
+  const { stdout } = await tndm([...args, "--json"]);
+  if (!stdout) {
+    throw new Error(`tndm returned empty output for: ${args.join(" ")}`);
+  }
+  try {
+    return JSON.parse(stdout) as T;
+  } catch {
+    throw new Error(
+      `tndm returned invalid JSON for: ${args.join(" ")}\nOutput: ${stdout}`,
+    );
+  }
+}
+
+/**
+ * Run `git add .tndm/` and `git commit -m <message>`.
+ * Uses `git diff --cached --quiet` to check for staged changes via exit code,
+ * avoiding locale-dependent string parsing.
+ * Throws on non-zero exit from `git commit`.
+ */
+export async function gitAddCommit(message: string): Promise<{ commitHash: string }> {
+  await run("git", ["add", ".tndm/"]);
+
+  // Check exit code instead of parsing locale-dependent output strings.
+  // git diff --cached --quiet exits 0 (no staged changes), non-zero (changes exist or error).
+  try {
+    await run("git", ["diff", "--cached", "--quiet"]);
+    // Exit 0: no changes staged — nothing to commit
+    return { commitHash: "" };
+  } catch {
+    // Exit non-zero: changes exist, or a real git error.
+    // Proceed to commit; real errors will surface there.
+  }
+
+  const { stdout } = await run("git", ["commit", "-m", message]);
+  const match = stdout.match(/\[[^\]]+ ([a-f0-9]+)\]/);
+  return { commitHash: match ? match[1] : "" };
+}

package/src/index.ts

@@ -0,0 +1,167 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { tndmJson } from "./cli.js";
+import { supi_tndm_cli_params, executeTndmCli } from "./tools/tndm-cli.js";
+import {
+  supiFlowStartParams,
+  supiFlowPlanParams,
+  supiFlowCompleteTaskParams,
+  supiFlowCloseParams,
+  executeFlowStart,
+  executeFlowPlan,
+  executeFlowCompleteTask,
+  executeFlowClose,
+} from "./tools/flow-tools.js";
+
+const baseDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export default function (pi: ExtensionAPI) {
+  // ── Resource discovery ──────────────────────────────────────
+  pi.on("resources_discover", () => ({
+    skillPaths: [join(baseDir, "skills")],
+    promptPaths: [join(baseDir, "prompts")],
+  }));
+
+  // ── Tool: supi_tndm_cli ─────────────────────────────────────
+  pi.registerTool({
+    name: "supi_tndm_cli",
+    label: "TNDM CLI",
+    description:
+      "Execute tndm ticket operations. Action determines which params apply:\n" +
+      "- create: title (required), status, priority, type, tags, depends_on, effort, content\n" +
+      "- update: id (required), title, status, priority, type, tags, add_tags, remove_tags, depends_on, effort, content\n" +
+      "- show: id (required)\n" +
+      "- list: all (boolean), definition (ready|questions|unknown)\n" +
+      "- awareness: against (git ref, required)",
+    promptSnippet: "Execute tndm ticket operations via supi_tndm_cli",
+    promptGuidelines: [
+      "Use supi_tndm_cli for direct tndm operations instead of running tndm via bash",
+    ],
+    parameters: supi_tndm_cli_params,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      return executeTndmCli(params);
+    },
+  });
+
+  // ── Tool: supi_flow_start ───────────────────────────────────
+  pi.registerTool({
+    name: "supi_flow_start",
+    label: "Flow Start",
+    description:
+      "Start a new flow: creates a TNDM ticket with status=todo and tag=flow:brainstorm. " +
+      "Stores known design context in content.md and returns the ticket ID.",
+    promptSnippet: "Begin a new flow by creating a TNDM ticket",
+    promptGuidelines: [
+      "Use supi_flow_start at the beginning of every brainstorm to create the required ticket",
+      "Always include context (design intent/summary) when known",
+    ],
+    parameters: supiFlowStartParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      return executeFlowStart(params);
+    },
+  });
+
+  // ── Tool: supi_flow_plan ────────────────────────────────────
+  pi.registerTool({
+    name: "supi_flow_plan",
+    label: "Flow Plan",
+    description:
+      "Store an implementation plan in a ticket's plan.md while keeping content.md as the canonical design summary. " +
+      "Updates tags from flow:brainstorm to flow:planned. Tasks must be numbered as '**Task {N}**' in the plan.",
+    promptSnippet: "Store a plan in a TNDM ticket",
+    promptGuidelines: [
+      "Use supi_flow_plan after creating a plan to persist it in the ticket",
+      "Number tasks sequentially as **Task 1**, **Task 2**, etc.",
+    ],
+    parameters: supiFlowPlanParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      return executeFlowPlan(params);
+    },
+  });
+
+  // ── Tool: supi_flow_complete_task ───────────────────────────
+  pi.registerTool({
+    name: "supi_flow_complete_task",
+    label: "Flow Complete Task",
+    description:
+      "Mark a task as done in a ticket's plan.md by task number (1-based). " +
+      "Finds '- [ ] **Task N:**' and changes to '- [x] **Task N:**'.",
+    promptSnippet: "Check off a completed plan task in a TNDM ticket",
+    promptGuidelines: [
+      "Use supi_flow_complete_task after each task's verification passes during apply",
+      "Call this with the task number, not the description text",
+    ],
+    parameters: supiFlowCompleteTaskParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      return executeFlowCompleteTask(params);
+    },
+  });
+
+  // ── Tool: supi_flow_close ───────────────────────────────────
+  pi.registerTool({
+    name: "supi_flow_close",
+    label: "Flow Close",
+    description:
+      "Close a ticket and finalize the flow. " +
+      "Writes verification results to archive.md, sets status=done, tags=flow:done, " +
+      "and auto-commits .tndm/ changes.",
+    promptSnippet: "Close a TNDM ticket after implementation and verification",
+    promptGuidelines: [
+      "Use supi_flow_close at the end of the archive phase after all verification is complete",
+      "Pass the full verification evidence as verification_results",
+    ],
+    parameters: supiFlowCloseParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      return executeFlowClose(params);
+    },
+  });
+
+  // ── Command: /supi-flow-status ──────────────────────────────
+  pi.registerCommand("supi-flow-status", {
+    description: "Show current flow workflow state",
+    handler: async (_args, ctx) => {
+      const tickets = await tndmJson<Array<{ id: string; status: string; tags?: string[] }>>([
+        "ticket",
+        "list",
+      ]);
+      const activeTickets = tickets.filter((ticket) => {
+        if (ticket.status === "done") return false;
+        const tags = ticket.tags ?? [];
+        return tags.includes("flow:brainstorm") || tags.includes("flow:planned") || tags.includes("flow:applying");
+      });
+
+      if (activeTickets.length === 0) {
+        ctx.ui.notify("No active flow tickets. Start with /skill:supi-flow-brainstorm.", "info");
+        return;
+      }
+
+      const lines = activeTickets.map((ticket) => {
+        const tags = ticket.tags ?? [];
+        const nextStep = tags.includes("flow:applying")
+          ? `/skill:supi-flow-archive ${ticket.id}`
+          : tags.includes("flow:planned")
+            ? `/skill:supi-flow-apply ${ticket.id}`
+            : `/skill:supi-flow-plan ${ticket.id}`;
+        return `${ticket.id} (${ticket.status}) -> ${nextStep}`;
+      });
+
+      ctx.ui.notify(`Active flow tickets:\n${lines.join("\n")}`, "info");
+    },
+  });
+
+  // ── Command: /supi-flow ─────────────────────────────────────
+  pi.registerCommand("supi-flow", {
+    description: "List available flow workflow commands",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(
+        "Flow: /skill:supi-flow-brainstorm -> /skill:supi-flow-plan -> /skill:supi-flow-apply -> /skill:supi-flow-archive\n" +
+          "  /supi-flow-status -- show current state\n" +
+          "  /supi-flow        -- this help\n" +
+          "Available tools: supi_tndm_cli, supi_flow_start, supi_flow_plan, supi_flow_complete_task, supi_flow_close",
+        "info",
+      );
+    },
+  });
+}

package/src/tools/flow-tools.ts

@@ -0,0 +1,337 @@
+import { dirname, join } from "node:path";
+import { readFileSync, writeFileSync } from "node:fs";
+import { type Static, Type } from "typebox";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { gitAddCommit, tndm, tndmJson } from "../cli.js";
+
+// ─── supi_flow_start ───────────────────────────────────────────
+
+export const supiFlowStartParams = Type.Object({
+  title: Type.String({ description: "Ticket title describing the change" }),
+  priority: Type.Optional(
+    StringEnum(["p0", "p1", "p2", "p3", "p4"] as const, {
+      description: "Priority (default: p2)",
+    }),
+  ),
+  type: Type.Optional(
+    StringEnum(["task", "bug", "feature", "chore", "epic"] as const, {
+      description: "Ticket type (default: task)",
+    }),
+  ),
+  context: Type.Optional(
+    Type.String({
+      description: "Brief context to store in ticket content (brainstorm intent / design summary)",
+    }),
+  ),
+});
+
+export type FlowStartParams = Static<typeof supiFlowStartParams>;
+
+export async function executeFlowStart(params: FlowStartParams) {
+  const args: string[] = [
+    "ticket",
+    "create",
+    params.title,
+    "--status",
+    "todo",
+    "--tags",
+    "flow:brainstorm",
+  ];
+
+  if (params.priority) args.push("--priority", params.priority);
+  if (params.type) args.push("--type", params.type);
+
+  const result = await tndm(args);
+  const ticketId = result.stdout.trim();
+
+  if (params.context) {
+    await tndm(["ticket", "update", ticketId, "--content", params.context]);
+  }
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: `Created ticket ${ticketId} with status=todo and flow:brainstorm tag.`,
+      },
+    ],
+    details: { action: "flow_start", ticketId, status: "todo", tags: "flow:brainstorm" },
+  };
+}
+
+// ─── supi_flow_plan ────────────────────────────────────────────
+
+export const supiFlowPlanParams = Type.Object({
+  ticket_id: Type.String({ description: "Ticket ID (e.g. TNDM-A1B2C3)" }),
+  plan_content: Type.String({
+    description:
+      "Markdown plan content with tasks numbered as '**Task {N}**'.\n\n- [ ] **Task 1**: Description\n  - File: path/to/file\n  - Verification: command",
+  }),
+  append: Type.Optional(
+    Type.Boolean({
+      description:
+        "If true, append to existing content. If false (default), replace content entirely.",
+    }),
+  ),
+});
+
+export type FlowPlanParams = Static<typeof supiFlowPlanParams>;
+
+export async function executeFlowPlan(params: FlowPlanParams) {
+  // Create a "plan" document and get its path
+  const docResult = await tndm(["ticket", "doc", "create", params.ticket_id, "plan"]);
+  const docPath = docResult.stdout.trim();
+
+  let content = params.plan_content;
+
+  if (params.append) {
+    try {
+      const existingContent = readFileSync(docPath, "utf-8");
+      if (existingContent) {
+        content = existingContent + "\n\n" + content;
+      }
+    } catch {
+      // If reading fails, just use the new content
+    }
+  }
+
+  // Write the plan content to the document file
+  writeFileSync(docPath, content, "utf-8");
+
+  // Sync fingerprints and update tags
+  await tndm(["ticket", "sync", params.ticket_id]);
+  await tndm([
+    "ticket",
+    "update",
+    params.ticket_id,
+    "--add-tags",
+    "flow:planned",
+    "--remove-tags",
+    "flow:brainstorm",
+  ]);
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: `Plan stored in ${params.ticket_id} (${docPath}). Tags updated to flow:planned.`,
+      },
+    ],
+    details: { action: "flow_plan", ticketId: params.ticket_id, tags: "flow:planned", path: docPath },
+  };
+}
+
+// ─── supi_flow_complete_task ───────────────────────────────────
+
+export const supiFlowCompleteTaskParams = Type.Object({
+  ticket_id: Type.String({ description: "Ticket ID (e.g. TNDM-A1B2C3)" }),
+  task_number: Type.Number({
+    description: "1-based task number to mark as complete (e.g. 1, 2, 3)",
+  }),
+});
+
+export type FlowCompleteTaskParams = Static<typeof supiFlowCompleteTaskParams>;
+
+type CheckTaskResult =
+  | { kind: "unchecked"; updatedContent: string }
+  | { kind: "already_checked" }
+  | { kind: "not_found" };
+
+function checkTask(content: string, taskNumber: number): CheckTaskResult {
+  // Match a task line like "- [ ] **Task N:**" or "  - [ ] **Task N:**"
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trimStart();
+
+    const uncheckedMatch = trimmed.match(
+      new RegExp(`^- \\[ \\] \\*\\*Task ${taskNumber}\\*\\*:`),
+    );
+    if (uncheckedMatch) {
+      // Replace the [ ] with [x] in the trimmed version
+      const indent = line.slice(0, line.length - trimmed.length);
+      lines[i] = indent + trimmed.replace("- [ ]", "- [x]");
+      return { kind: "unchecked", updatedContent: lines.join("\n") };
+    }
+
+    const checkedMatch = trimmed.match(
+      new RegExp(`^- \\[x\\] \\*\\*Task ${taskNumber}\\*\\*:`),
+    );
+    if (checkedMatch) {
+      return { kind: "already_checked" };
+    }
+  }
+  return { kind: "not_found" };
+}
+
+export async function executeFlowCompleteTask(params: FlowCompleteTaskParams) {
+  const showResult = await tndmJson<{
+    id: string;
+    content_path?: string;
+    documents?: Array<{ name: string; path: string }>;
+  }>([
+    "ticket",
+    "show",
+    params.ticket_id,
+  ]);
+
+  const contentPath = showResult.content_path;
+  if (!contentPath) {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `No content path found in ticket ${params.ticket_id}.`,
+        },
+      ],
+      details: { action: "flow_complete_task", ticketId: params.ticket_id, error: "No content path" },
+    };
+  }
+
+  const planDocument = showResult.documents?.find((document) => document.name === "plan");
+  if (!planDocument) {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `No plan file is registered in ticket ${params.ticket_id}.`,
+        },
+      ],
+      details: {
+        action: "flow_complete_task",
+        ticketId: params.ticket_id,
+        error: "No plan file",
+      },
+    };
+  }
+
+  const planPath = join(dirname(contentPath), planDocument.path);
+
+  let content: string;
+  try {
+    content = readFileSync(planPath, "utf-8");
+  } catch {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `No plan file found at ${planPath}. No tasks to complete.`,
+        },
+      ],
+      details: { action: "flow_complete_task", ticketId: params.ticket_id, error: "No plan file" },
+    };
+  }
+
+  const result = checkTask(content, params.task_number);
+
+  switch (result.kind) {
+    case "unchecked":
+      writeFileSync(planPath, result.updatedContent, "utf-8");
+      await tndm(["ticket", "sync", params.ticket_id]);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Task ${params.task_number} checked off in ${params.ticket_id}.`,
+          },
+        ],
+        details: {
+          action: "flow_complete_task",
+          ticketId: params.ticket_id,
+          taskNumber: params.task_number,
+          completed: true,
+        },
+      };
+
+    case "already_checked":
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Task ${params.task_number} is already checked off in ${params.ticket_id}.`,
+          },
+        ],
+        details: {
+          action: "flow_complete_task",
+          ticketId: params.ticket_id,
+          taskNumber: params.task_number,
+          completed: true,
+          skipped: true,
+        },
+      };
+
+    case "not_found":
+      throw new Error(
+        `Task ${params.task_number} not found in ticket ${params.ticket_id}.` +
+        ` Task must exist as '- [ ] **Task N:**' or '- [x] **Task N:**'.`,
+      );
+  }
+}
+
+// ─── supi_flow_close ───────────────────────────────────────────
+
+export const supiFlowCloseParams = Type.Object({
+  ticket_id: Type.String({ description: "Ticket ID (e.g. TNDM-A1B2C3)" }),
+  verification_results: Type.Optional(
+    Type.String({
+      description:
+        "Verification results / evidence from the agent. Appended to the ticket content under ## Verification Results.",
+    }),
+  ),
+});
+
+export type FlowCloseParams = Static<typeof supiFlowCloseParams>;
+
+export async function executeFlowClose(params: FlowCloseParams) {
+  let archivePath = "";
+
+  if (params.verification_results) {
+    // Create/register archive.md via document registry, then write results
+    try {
+      const docResult = await tndm(["ticket", "doc", "create", params.ticket_id, "archive"]);
+      archivePath = docResult.stdout.trim();
+      writeFileSync(archivePath, `# Archive\n\n${params.verification_results}\n`, "utf-8");
+      await tndm(["ticket", "sync", params.ticket_id]);
+    } catch {
+      // Non-fatal if doc create fails
+    }
+  }
+
+  await tndm([
+    "ticket",
+    "update",
+    params.ticket_id,
+    "--status",
+    "done",
+    "--add-tags",
+    "flow:done",
+    "--remove-tags",
+    "flow:applying",
+  ]);
+
+  let commitHash = "";
+  try {
+    const commitResult = await gitAddCommit(`chore(tndm): close ${params.ticket_id}`);
+    commitHash = commitResult.commitHash;
+  } catch {
+    // Non-fatal if commit fails
+  }
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: `Ticket ${params.ticket_id} closed (status=done, flow:done).${
+          commitHash ? ` Committed as ${commitHash}.` : ""
+        }`,
+      },
+    ],
+    details: {
+      action: "flow_close",
+      ticketId: params.ticket_id,
+      status: "done",
+      tags: "flow:done",
+      commitHash,
+    },
+  };
+}