pi-gauntlet 4.0.0

package/extensions/plan-tracker.ts

@@ -0,0 +1,308 @@
+/**
+ * Plan Tracker Extension
+ *
+ * A native pi tool for tracking plan progress.
+ * State is stored in tool result details for proper branching support.
+ * Shows a persistent TUI widget above the editor.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { type Static, Type } from "@sinclair/typebox";
+
+type TaskStatus = "pending" | "in_progress" | "complete";
+
+interface Task {
+  name: string;
+  status: TaskStatus;
+}
+
+interface PlanTrackerDetails {
+  action: "init" | "update" | "status" | "clear";
+  tasks: Task[];
+  error?: string;
+}
+
+const PlanTrackerParams = Type.Object({
+  action: StringEnum(["init", "update", "status", "clear"] as const, {
+    description: "Action to perform",
+  }),
+  tasks: Type.Optional(
+    Type.Array(Type.String(), {
+      description: "Task names (for init)",
+    }),
+  ),
+  index: Type.Optional(
+    Type.Integer({
+      minimum: 0,
+      description: "Task index, 0-based (for update)",
+    }),
+  ),
+  status: Type.Optional(
+    StringEnum(["pending", "in_progress", "complete"] as const, {
+      description: "New status (for update)",
+    }),
+  ),
+});
+
+export type PlanTrackerInput = Static<typeof PlanTrackerParams>;
+
+function formatWidget(tasks: Task[], theme: Theme): string {
+  if (tasks.length === 0) return "";
+
+  const complete = tasks.filter((t) => t.status === "complete").length;
+  const icons = tasks
+    .map((t) => {
+      switch (t.status) {
+        case "complete":
+          return theme.fg("success", "✓");
+        case "in_progress":
+          return theme.fg("warning", "→");
+        default:
+          return theme.fg("dim", "○");
+      }
+    })
+    .join("");
+
+  // Find current task (first in_progress, or first pending)
+  const current = tasks.find((t) => t.status === "in_progress") ?? tasks.find((t) => t.status === "pending");
+  const currentName = current ? `  ${current.name}` : "";
+
+  return `${theme.fg("muted", "Tasks:")} ${icons} ${theme.fg("muted", `(${complete}/${tasks.length})`)}${currentName}`;
+}
+
+function formatStatus(tasks: Task[]): string {
+  if (tasks.length === 0) return "No plan active.";
+
+  const complete = tasks.filter((t) => t.status === "complete").length;
+  const inProgress = tasks.filter((t) => t.status === "in_progress").length;
+  const pending = tasks.filter((t) => t.status === "pending").length;
+
+  const lines: string[] = [];
+  lines.push(`Plan: ${complete}/${tasks.length} complete (${inProgress} in progress, ${pending} pending)`);
+  lines.push("");
+  for (let i = 0; i < tasks.length; i++) {
+    const t = tasks[i];
+    const icon = t.status === "complete" ? "✓" : t.status === "in_progress" ? "→" : "○";
+    lines.push(`  ${icon} [${i}] ${t.name}`);
+  }
+  return lines.join("\n");
+}
+
+export default function (pi: ExtensionAPI) {
+  let tasks: Task[] = [];
+
+  const reconstructState = (ctx: ExtensionContext) => {
+    tasks = [];
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type !== "message") continue;
+      const msg = entry.message;
+      if (msg.role !== "toolResult" || msg.toolName !== "plan_tracker") continue;
+      const details = msg.details as PlanTrackerDetails | undefined;
+      if (details && !details.error) {
+        tasks = details.tasks.map((t) => ({ ...t }));
+      }
+    }
+  };
+
+  const updateWidget = (ctx: ExtensionContext) => {
+    if (!ctx.hasUI) return;
+    if (tasks.length === 0) {
+      ctx.ui.setWidget("plan_tracker", undefined);
+    } else {
+      ctx.ui.setWidget("plan_tracker", (_tui, theme) => {
+        return new Text(formatWidget(tasks, theme), 0, 0);
+      });
+    }
+  };
+
+  // Reconstruct state + widget on session events
+  for (const event of ["session_start", "session_switch", "session_fork", "session_tree"] as const) {
+    pi.on(event, async (_event, ctx) => {
+      reconstructState(ctx);
+      updateWidget(ctx);
+    });
+  }
+
+  pi.registerTool({
+    name: "plan_tracker",
+    label: "Plan Tracker",
+    description:
+      "Track progress while EXECUTING an implementation plan — the implement phase only. Actions: init (set task list), update (change task status), status (show current state), clear (remove plan). Do NOT use for brainstorming, research, or planning checklists: those phases are open-ended and a bounded task list misrepresents them as a fixed N-step process.",
+    parameters: PlanTrackerParams,
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      switch (params.action) {
+        case "init": {
+          if (!params.tasks || params.tasks.length === 0) {
+            return {
+              content: [{ type: "text", text: "Error: tasks array required for init" }],
+              details: {
+                action: "init",
+                tasks: tasks.map((t) => ({ ...t })),
+                error: "tasks required",
+              } as PlanTrackerDetails,
+            };
+          }
+          tasks = params.tasks.map((name) => ({ name, status: "pending" as TaskStatus }));
+          updateWidget(ctx);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Plan initialized with ${tasks.length} tasks.\n${formatStatus(tasks)}`,
+              },
+            ],
+            details: { action: "init", tasks: tasks.map((t) => ({ ...t })) } as PlanTrackerDetails,
+          };
+        }
+
+        case "update": {
+          if (params.index === undefined || !params.status) {
+            return {
+              content: [{ type: "text", text: "Error: index and status required for update" }],
+              details: {
+                action: "update",
+                tasks: tasks.map((t) => ({ ...t })),
+                error: "index and status required",
+              } as PlanTrackerDetails,
+            };
+          }
+          if (tasks.length === 0) {
+            return {
+              content: [{ type: "text", text: "Error: no plan active. Use init first." }],
+              details: {
+                action: "update",
+                tasks: [],
+                error: "no plan active",
+              } as PlanTrackerDetails,
+            };
+          }
+          if (params.index < 0 || params.index >= tasks.length) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Error: index ${params.index} out of range (0-${tasks.length - 1})`,
+                },
+              ],
+              details: {
+                action: "update",
+                tasks: tasks.map((t) => ({ ...t })),
+                error: `index ${params.index} out of range`,
+              } as PlanTrackerDetails,
+            };
+          }
+          tasks[params.index].status = params.status;
+          updateWidget(ctx);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Task ${params.index} "${tasks[params.index].name}" → ${params.status}\n${formatStatus(tasks)}`,
+              },
+            ],
+            details: { action: "update", tasks: tasks.map((t) => ({ ...t })) } as PlanTrackerDetails,
+          };
+        }
+
+        case "status": {
+          return {
+            content: [{ type: "text", text: formatStatus(tasks) }],
+            details: { action: "status", tasks: tasks.map((t) => ({ ...t })) } as PlanTrackerDetails,
+          };
+        }
+
+        case "clear": {
+          const count = tasks.length;
+          tasks = [];
+          updateWidget(ctx);
+          return {
+            content: [
+              {
+                type: "text",
+                text: count > 0 ? `Plan cleared (${count} tasks removed).` : "No plan was active.",
+              },
+            ],
+            details: { action: "clear", tasks: [] } as PlanTrackerDetails,
+          };
+        }
+
+        default:
+          return {
+            content: [{ type: "text", text: `Unknown action: ${params.action}` }],
+            details: {
+              action: "status",
+              tasks: tasks.map((t) => ({ ...t })),
+              error: `unknown action`,
+            } as PlanTrackerDetails,
+          };
+      }
+    },
+
+    renderCall(args, theme) {
+      let text = theme.fg("toolTitle", theme.bold("plan_tracker "));
+      text += theme.fg("muted", args.action);
+      if (args.action === "update" && args.index !== undefined) {
+        text += ` ${theme.fg("accent", `[${args.index}]`)}`;
+        if (args.status) text += ` → ${theme.fg("dim", args.status)}`;
+      }
+      if (args.action === "init" && args.tasks) {
+        text += ` ${theme.fg("dim", `(${args.tasks.length} tasks)`)}`;
+      }
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as PlanTrackerDetails | undefined;
+      if (!details) {
+        const text = result.content[0];
+        return new Text(text?.type === "text" ? text.text : "", 0, 0);
+      }
+
+      if (details.error) {
+        return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
+      }
+
+      const taskList = details.tasks;
+      switch (details.action) {
+        case "init":
+          return new Text(
+            theme.fg("success", "✓ ") + theme.fg("muted", `Plan initialized with ${taskList.length} tasks`),
+            0,
+            0,
+          );
+        case "update": {
+          const complete = taskList.filter((t) => t.status === "complete").length;
+          return new Text(
+            theme.fg("success", "✓ ") + theme.fg("muted", `Updated (${complete}/${taskList.length} complete)`),
+            0,
+            0,
+          );
+        }
+        case "status": {
+          if (taskList.length === 0) {
+            return new Text(theme.fg("dim", "No plan active"), 0, 0);
+          }
+          const complete = taskList.filter((t) => t.status === "complete").length;
+          let text = theme.fg("muted", `${complete}/${taskList.length} complete`);
+          for (const t of taskList) {
+            const icon =
+              t.status === "complete"
+                ? theme.fg("success", "✓")
+                : t.status === "in_progress"
+                  ? theme.fg("warning", "→")
+                  : theme.fg("dim", "○");
+            text += `\n${icon} ${theme.fg("muted", t.name)}`;
+          }
+          return new Text(text, 0, 0);
+        }
+        case "clear":
+          return new Text(theme.fg("success", "✓ ") + theme.fg("muted", "Plan cleared"), 0, 0);
+        default:
+          return new Text(theme.fg("dim", "Done"), 0, 0);
+      }
+    },
+  });
+}

package/extensions/verify-before-ship.ts

@@ -0,0 +1,132 @@
+/**
+ * Verify-before-ship extension
+ *
+ * Single-session verification gate for shipping commands (git commit / git push /
+ * gh pr create). Tracks whether a recognised verification command has succeeded
+ * since the last source-file write; injects an advisory warning into the tool
+ * result of any ship command when verification is stale.
+ *
+ * In-memory only. No persisted state.
+ *
+ * Configurable via settings.json:
+ *
+ *   {
+ *     "piGauntlet": {
+ *       "verifyBeforeShip": {
+ *         "testCommands": ["make ci", "make test", "pytest", "rspec"],
+ *         "warningReference": "doc/testing.md"
+ *       }
+ *     }
+ *   }
+ *
+ * Defaults match common multi-language verification entrypoints. Override
+ * `testCommands` to match your project's conventions.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// Default verification entrypoints. Override via settings.
+const DEFAULT_TEST_COMMANDS = [
+  "make\\s+(?:ci|test)(?![-\\w])", // rejects make test-smoke, test-corpus, etc.
+  "npm\\s+(?:test|run\\s+test)",
+  "pnpm\\s+test",
+  "yarn\\s+test",
+  "pytest",
+  "rspec",
+  "cargo\\s+test",
+  "go\\s+test",
+];
+
+const SHIP_CMD = /\b(git\s+commit|git\s+push|gh\s+pr\s+create)\b/;
+const SOURCE_EXT = /\.(ts|tsx|js|jsx|py|rb|go|rs|java|swift|kt)$/;
+const TEST_PATH = /(^|\/)(tests?|__tests__)\/|\.(test|spec)\.|_test\.(py|go|rb)$/;
+
+type Settings = {
+  piGauntlet?: {
+    verifyBeforeShip?: {
+      testCommands?: string[];
+      warningReference?: string;
+    };
+  };
+};
+
+const isSourceWrite = (filePath: string | undefined): boolean => {
+  if (!filePath) return false;
+  return SOURCE_EXT.test(filePath) && !TEST_PATH.test(filePath);
+};
+
+const buildTestCmdRegex = (commands: string[]): RegExp =>
+  new RegExp(`\\b(${commands.join("|")})\\b`);
+
+const formatWarning = (command: string, testCommands: string[], reference: string | undefined): string => {
+  const examples = testCommands
+    .slice(0, 3)
+    .map((c) => "`" + c.replace(/\\s\+/g, " ").replace(/\\b|\(\?!.*?\)/g, "") + "`")
+    .join(" / ");
+  const refLine = reference ? `\nReference: ${reference}` : "";
+  return (
+    `⚠️ Ship command \`${command.trim()}\` ran without verification.\n\n` +
+    `No successful ${examples} run since the last source edit in this session.\n` +
+    `Run your project's verification target before continuing, or confirm with the user that you are deliberately skipping it.${refLine}`
+  );
+};
+
+export default function (pi: ExtensionAPI) {
+  const settings = (pi.settings ?? {}) as Settings;
+  const cfg = settings.piGauntlet?.verifyBeforeShip ?? {};
+  const testCommands = cfg.testCommands ?? DEFAULT_TEST_COMMANDS;
+  const testRegex = buildTestCmdRegex(testCommands);
+  const reference = cfg.warningReference;
+
+  let verified = false;
+  let pendingTestCallId: string | null = null;
+  const pendingShipWarnings = new Map<string, string>();
+
+  const getCommand = (event: { input: unknown }): string => {
+    const input = event.input as { command?: unknown } | undefined;
+    return typeof input?.command === "string" ? input.command : "";
+  };
+
+  const getPath = (event: { input: unknown }): string | undefined => {
+    const input = event.input as { path?: unknown } | undefined;
+    return typeof input?.path === "string" ? input.path : undefined;
+  };
+
+  pi.on("tool_call", async (event) => {
+    if (event.toolName === "write" || event.toolName === "edit") {
+      if (isSourceWrite(getPath(event))) verified = false;
+      return undefined;
+    }
+
+    if (event.toolName !== "bash") return undefined;
+    const command = getCommand(event);
+    if (!command) return undefined;
+
+    if (testRegex.test(command)) {
+      pendingTestCallId = event.toolCallId;
+      return undefined;
+    }
+
+    if (SHIP_CMD.test(command) && !verified) {
+      pendingShipWarnings.set(event.toolCallId, formatWarning(command, testCommands, reference));
+    }
+    return undefined;
+  });
+
+  pi.on("tool_result", async (event) => {
+    if (event.toolName !== "bash") return undefined;
+
+    if (pendingTestCallId === event.toolCallId) {
+      pendingTestCallId = null;
+      if (!event.isError) verified = true;
+    }
+
+    const warning = pendingShipWarnings.get(event.toolCallId);
+    if (!warning) return undefined;
+    pendingShipWarnings.delete(event.toolCallId);
+
+    return {
+      content: [{ type: "text" as const, text: warning }, ...event.content],
+    };
+  });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "pi-gauntlet",
+  "version": "4.0.0",
+  "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jjuraszek/pi-gauntlet.git"
+  },
+  "homepage": "https://github.com/jjuraszek/pi-gauntlet#readme",
+  "bugs": {
+    "url": "https://github.com/jjuraszek/pi-gauntlet/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "skills",
+    "agents",
+    "workflow"
+  ],
+  "files": [
+    "skills",
+    "extensions",
+    "agents",
+    "bin",
+    "CHANGELOG.md"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ],
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "scripts": {
+    "postinstall": "node ./bin/install-agents.mjs",
+    "link-agents": "node ./bin/install-agents.mjs",
+    "test": "node scripts/ci.mjs"
+  }
+}