@preapexis/pi-kit 1.0.0

package/extensions/brand-ui.ts

@@ -0,0 +1,107 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type EventContext = Parameters<Parameters<ExtensionAPI["on"]>[1]>[1];
+
+const PREAPEXIS_ART = [
+  "██████╗ ██████╗ ███████╗ █████╗ ██████╗ ███████╗██╗  ██╗██╗███████╗",
+  "██╔══██╗██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔════╝╚██╗██╔╝██║██╔════╝",
+  "██████╔╝██████╔╝█████╗  ███████║██████╔╝█████╗   ╚███╔╝ ██║███████╗",
+  "██╔═══╝ ██╔══██╗██╔══╝  ██╔══██║██╔═══╝ ██╔══╝   ██╔██╗ ██║╚════██║",
+  "██║     ██║  ██║███████╗██║  ██║██║     ███████╗██╔╝ ██╗██║███████║",
+  "╚═╝     ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝     ╚══════╝╚═╝  ╚═╝╚═╝╚══════╝"
+];
+
+const COMPACT_HEADER = "π  PreApeXis  π";
+
+const RAINBOW = [
+  [255, 90, 90],
+  [255, 170, 70],
+  [255, 230, 90],
+  [90, 220, 130],
+  [90, 190, 255],
+  [180, 130, 255]
+] as const;
+
+function rgb(text: string, r: number, g: number, b: number): string {
+  return `\x1b[1;38;2;${r};${g};${b}m${text}\x1b[0m`;
+}
+
+function rainbowText(text: string): string {
+  let colorIndex = 0;
+
+  return [...text]
+    .map((char) => {
+      if (char === " ") return char;
+
+      const [r, g, b] = RAINBOW[colorIndex % RAINBOW.length];
+      colorIndex += 1;
+
+      return rgb(char, r, g, b);
+    })
+    .join("");
+}
+
+function rainbowPi(): string {
+  return rainbowText("π");
+}
+
+export default function (pi: ExtensionAPI): void {
+  function applyBrandUI(ctx: EventContext): void {
+    if (!ctx.hasUI || ctx.mode !== "tui") return;
+
+    ctx.ui.setTitle("PreApeXis");
+
+    ctx.ui.setHeader((_tui, theme) => ({
+      render(width: number): string[] {
+        if (width < 90) {
+          return [
+            rainbowText(COMPACT_HEADER),
+            theme.fg("dim", "safe changes · clear plans")
+          ];
+        }
+
+        return [
+          ...PREAPEXIS_ART.map((line) => rainbowText(line)),
+          theme.fg("dim", "safe changes · clear plans")
+        ];
+      },
+      invalidate() {}
+    }));
+
+    ctx.ui.setWorkingMessage("Thinking");
+
+    ctx.ui.setWorkingIndicator({
+      frames: [
+        rainbowPi(),
+        `${rainbowPi()}·`,
+        `${rainbowPi()}··`,
+        `${rainbowPi()}···`
+      ],
+      intervalMs: 300
+    });
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    applyBrandUI(ctx);
+  });
+
+  pi.registerCommand("brand", {
+    description: "Re-apply PreApeXis brand UI",
+    handler: async (_args, ctx) => {
+      applyBrandUI(ctx);
+      ctx.ui.notify("PreApeXis brand UI applied.", "info");
+    }
+  });
+
+  pi.registerCommand("brand-reset", {
+    description: "Restore default Pi header and working indicator",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+
+      ctx.ui.setHeader(undefined);
+      ctx.ui.setWorkingMessage();
+      ctx.ui.setWorkingIndicator();
+      ctx.ui.notify("Default Pi UI restored.", "info");
+    }
+  });
+}

package/extensions/git-guard.ts

@@ -0,0 +1,134 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI): void {
+  const CHECKPOINT_PREFIX = "pi-checkpoint";
+
+  async function git(
+    cwd: string,
+    args: string[]
+  ): Promise<{ stdout: string; stderr: string; code: number }> {
+    try {
+      const result = await pi.exec("git", args, { cwd });
+
+      return {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        code: result.code
+      };
+    } catch (error) {
+      return {
+        stdout: "",
+        stderr: error instanceof Error ? error.message : String(error),
+        code: 1
+      };
+    }
+  }
+
+  async function isGitRepo(cwd: string): Promise<boolean> {
+    const { code } = await git(cwd, ["rev-parse", "--git-dir"]);
+    return code === 0;
+  }
+
+  async function getBranch(cwd: string): Promise<string | null> {
+    const { stdout, code } = await git(cwd, ["branch", "--show-current"]);
+
+    if (code !== 0) return null;
+
+    const branch = stdout.trim();
+    return branch.length > 0 ? branch : null;
+  }
+
+  async function isDirty(cwd: string): Promise<boolean> {
+    const { stdout, code } = await git(cwd, ["status", "--porcelain"]);
+
+    if (code !== 0) return false;
+
+    return stdout.trim().length > 0;
+  }
+
+  pi.on("before_agent_start", async (_event, ctx) => {
+    if (!ctx.hasUI || !(await isGitRepo(ctx.cwd))) return;
+
+    if (await isDirty(ctx.cwd)) {
+      ctx.ui.notify(
+        "Git working tree is dirty. Consider committing or stashing before making changes.",
+        "warning"
+      );
+    }
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName === "bash") {
+      const command = String(event.input.command ?? "");
+
+      if (/\bgit\s+push\s+.*(--force|-f)\b/i.test(command)) {
+        return {
+          block: true,
+          reason: "Force-push blocked by git-guard."
+        };
+      }
+
+      if (/\bgit\s+reset\s+--hard\b/i.test(command)) {
+        if (!ctx.hasUI) {
+          return {
+            block: true,
+            reason:
+              "git reset --hard blocked by git-guard: no UI available for confirmation."
+          };
+        }
+
+        const ok = await ctx.ui.confirm(
+          "git reset --hard detected",
+          "This will discard uncommitted changes. Are you sure?"
+        );
+
+        if (!ok) {
+          return {
+            block: true,
+            reason: "git reset --hard cancelled by user."
+          };
+        }
+      }
+    }
+
+    if (
+      (event.toolName === "write" || event.toolName === "edit") &&
+      (await isGitRepo(ctx.cwd)) &&
+      (await isDirty(ctx.cwd))
+    ) {
+      const branch = await getBranch(ctx.cwd);
+      const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+
+      const checkpointName = branch
+        ? `${CHECKPOINT_PREFIX}-${branch}-${timestamp}`
+        : `${CHECKPOINT_PREFIX}-${timestamp}`;
+
+      const { code, stderr } = await git(ctx.cwd, ["branch", checkpointName]);
+
+      if (code !== 0) {
+        if (!ctx.hasUI) {
+          return {
+            block: true,
+            reason: "Blocked because git checkpoint could not be created."
+          };
+        }
+
+        const ok = await ctx.ui.confirm(
+          "Git checkpoint failed",
+          `Could not create checkpoint branch: ${stderr}\n\nContinue editing anyway?`
+        );
+
+        if (!ok) {
+          return {
+            block: true,
+            reason: "Blocked because git checkpoint could not be created."
+          };
+        }
+      } else if (ctx.hasUI) {
+        ctx.ui.notify(`Git checkpoint created: ${checkpointName}`, "info");
+      }
+    }
+
+    return undefined;
+  });
+}

package/extensions/prompts.ts

@@ -0,0 +1,53 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI): void {
+  const prompts = [
+    {
+      name: "init",
+      description: "Inspect the repository and create an onboarding report",
+      usage: "/init"
+    },
+    {
+      name: "plan",
+      description:
+        "Create a read-only plan with batches, model choice, and effort guidance",
+      usage: "/plan <your request>"
+    },
+    {
+      name: "save-plan",
+      description: "Save a generated plan as a markdown file",
+      usage: "/save-plan <plan content>"
+    },
+    {
+      name: "implement",
+      description: "Implement a saved plan or pasted plan content",
+      usage: "/implement <plan file path or plan content>"
+    },
+    {
+      name: "commit",
+      description: "Generate a git commit message from current changes",
+      usage: "/commit"
+    },
+    {
+      name: "review-safe",
+      description: "Review the project safely without editing files",
+      usage: "/review-safe"
+    },
+    {
+      name: "security",
+      description: "Run a read-only security review",
+      usage: "/security"
+    }
+  ];
+
+  pi.registerCommand("prompts", {
+    description: "List available prompt workflows",
+    handler: async (_args, ctx) => {
+      const list = prompts
+        .map((prompt) => `${prompt.usage} - ${prompt.description}`)
+        .join("\n");
+
+      ctx.ui.notify(`Available prompts:\n\n${list}`, "info");
+    }
+  });
+}

package/extensions/safety.ts

@@ -0,0 +1,242 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import * as path from "path";
+
+/**
+ * General safety extension for Pi.
+ *
+ * git-guard.ts handles Git-specific safety.
+ * This file handles:
+ * - risky shell commands
+ * - secret file protection
+ * - protected generated/dependency paths
+ * - safety instructions in the system prompt
+ */
+
+export default function (pi: ExtensionAPI): void {
+  // Do NOT include git push/reset checks here.
+  // Those belong in git-guard.ts to avoid duplicate prompts.
+  const riskyCommands = [
+    // Recursive/forced remove
+    /\brm\s+(-[a-z]*[rf][a-z]*|--recursive|--force)\b/i,
+
+    // Admin / permission risky
+    /\bsudo\b/i,
+    /\bchmod\b.*\b777\b/i,
+
+    // Running remote scripts
+    /\bcurl\b.*\|\s*(sh|bash|zsh)\b/i,
+    /\bwget\b.*\|\s*(sh|bash|zsh)\b/i,
+
+    // Package install/remove
+    /\b(npm|yarn|pnpm)\s+(install|add|remove|uninstall|ci)\b/i,
+    /\b(pip|pip3)\s+(install|uninstall)\b/i,
+    /\b(apt-get|apt)\s+(install|remove|purge)\b/i,
+    /\bbrew\s+(install|uninstall|remove)\b/i,
+
+    // Docker cleanup
+    /\bdocker\s+system\s+prune/i,
+    /\bdocker\s+(container|image|volume|network)\s+prune/i,
+
+    // Disk / filesystem destructive
+    /\bdd\s+if=.+of=\/dev\/[sh]d[a-z]/i,
+    /\bmkfs\b/i,
+    /\b(fdisk|parted)\b/i,
+    />\s*\/dev\/[sh]d[a-z]/i,
+
+    // Shutdown/reboot
+    /\bshutdown\b|\breboot\b|\bpoweroff\b/i,
+
+    // Windows destructive commands
+    /\bformat\s+[a-z]:/i,
+    /\bdiskpart\b/i,
+    /\brd\s+\/s\s+\/q\b/i,
+    /\bdel\s+\/f\s+\/s\s+\/q\b/i
+  ];
+
+  const secretFileNames = [
+    ".env",
+    ".env.local",
+    ".env.production",
+    ".env.development",
+    ".env.test",
+    ".envrc"
+  ];
+
+  const blockedEditSegments = [
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    "coverage"
+  ];
+
+  const confirmEditFileNames = [
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "bun.lockb"
+  ];
+
+  function getPathSegments(filePath: string): string[] {
+    return path
+      .normalize(filePath)
+      .replaceAll("\\", "/")
+      .split("/")
+      .filter(Boolean);
+  }
+
+  function getFileName(filePath: string): string {
+    const segments = getPathSegments(filePath);
+    return segments.at(-1) ?? "";
+  }
+
+  function findSecretFile(filePath: string): string | undefined {
+    const fileName = getFileName(filePath);
+    return secretFileNames.find((name) => name === fileName);
+  }
+
+  function findBlockedEditSegment(filePath: string): string | undefined {
+    const segments = getPathSegments(filePath);
+    return blockedEditSegments.find((entry) => segments.includes(entry));
+  }
+
+  function findConfirmEditFile(filePath: string): string | undefined {
+    const fileName = getFileName(filePath);
+    return confirmEditFileNames.find((name) => name === fileName);
+  }
+
+  function isRiskyCommand(command: string): boolean {
+    return riskyCommands.some((pattern) => pattern.test(command));
+  }
+
+  pi.on("before_agent_start", async (event) => {
+    return {
+      systemPrompt:
+        event.systemPrompt +
+        `
+    Safety rules:
+      - Make small, reviewable changes.
+      - Do not read or edit secret files such as .env files.
+      - Ask before installing or removing packages.
+      - Explain risky commands before running them.
+      - Prefer safe, additive changes.
+      - Run tests or type checks after code changes when available.
+
+    Clarification rules:
+      - If the request is unclear, ask questions before editing files.
+      - Ask only important questions.
+      - Do not ask more than 5 questions.
+      - If the task is clear, continue without asking.
+      - Do not edit files until the user answers clarification questions.
+`
+    };
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName === "bash") {
+      const command = String(event.input.command ?? "");
+
+      if (isRiskyCommand(command)) {
+        if (!ctx.hasUI) {
+          return {
+            block: true,
+            reason:
+              "Risky shell command blocked because no UI is available to confirm it."
+          };
+        }
+
+        const choice = await ctx.ui.select(
+          `Risky shell command detected:\n\n${command}\n\nAllow it?`,
+          ["No", "Yes"]
+        );
+
+        if (choice !== "Yes") {
+          return {
+            block: true,
+            reason: "Blocked by safety extension."
+          };
+        }
+
+        console.log(`[safety] User approved risky command: ${command}`);
+      }
+    }
+
+    if (event.toolName === "read") {
+      const filePath = String(event.input.path ?? "");
+      const secretHit = findSecretFile(filePath);
+
+      if (secretHit) {
+        const reason = `Reading secret file blocked: ${secretHit}`;
+
+        if (ctx.hasUI) {
+          ctx.ui.notify(reason, "warning");
+        }
+
+        return { block: true, reason };
+      }
+    }
+
+    if (event.toolName === "write" || event.toolName === "edit") {
+      const filePath = String(event.input.path ?? "");
+
+      const secretHit = findSecretFile(filePath);
+      if (secretHit) {
+        const reason = `Editing secret file blocked: ${secretHit}`;
+
+        if (ctx.hasUI) {
+          ctx.ui.notify(reason, "warning");
+        }
+
+        return { block: true, reason };
+      }
+
+      const blockedSegment = findBlockedEditSegment(filePath);
+      if (blockedSegment) {
+        const reason = `Protected path blocked: ${blockedSegment}`;
+
+        if (ctx.hasUI) {
+          ctx.ui.notify(reason, "warning");
+        }
+
+        return { block: true, reason };
+      }
+
+      const confirmFile = findConfirmEditFile(filePath);
+      if (confirmFile) {
+        if (!ctx.hasUI) {
+          return {
+            block: true,
+            reason: `Editing ${confirmFile} blocked because no UI is available to confirm it.`
+          };
+        }
+
+        const choice = await ctx.ui.select(
+          `Protected file edit detected:\n\n${filePath}\n\nAllow editing ${confirmFile}?`,
+          ["No", "Yes"]
+        );
+
+        if (choice !== "Yes") {
+          return {
+            block: true,
+            reason: `Editing ${confirmFile} cancelled by user.`
+          };
+        }
+
+        console.log(`[safety] User approved protected file edit: ${filePath}`);
+      }
+    }
+
+    return undefined;
+  });
+
+  pi.registerCommand("safety", {
+    description: "Show active safety rules",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(
+        "Safety enabled: risky command confirmation, .env read/edit blocking, dependency/build path protection, and lockfile edit confirmation.",
+        "info"
+      );
+    }
+  });
+}

package/extensions/sound-cues.ts

@@ -0,0 +1,88 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type EventContext = Parameters<Parameters<ExtensionAPI["on"]>[1]>[1];
+
+type SoundName = "start" | "done" | "need-input" | "error";
+
+export default function (pi: ExtensionAPI): void {
+  let enabled = true;
+
+  function bell(count = 1): void {
+    if (!enabled) return;
+
+    for (let i = 0; i < count; i += 1) {
+      setTimeout(() => {
+        process.stdout.write("\u0007");
+      }, i * 150);
+    }
+  }
+
+  function play(sound: SoundName): void {
+    if (sound === "start") bell(1);
+    if (sound === "done") bell(2);
+    if (sound === "need-input") bell(3);
+    if (sound === "error") bell(4);
+  }
+
+  pi.on("before_agent_start", async () => {
+    play("start");
+  });
+
+  pi.on("agent_end", async () => {
+    play("done");
+  });
+
+  pi.on("tool_call", async (event) => {
+    if (event.toolName === "bash") {
+      const command = String(event.input.command ?? "");
+
+      if (
+        /\bnpm\s+install\b/i.test(command) ||
+        /\bnpm\s+update\b/i.test(command) ||
+        /\bgit\s+reset\s+--hard\b/i.test(command)
+      ) {
+        play("need-input");
+      }
+    }
+  });
+
+  pi.on("tool_result", async (event) => {
+    const maybeResult = event as {
+      result?: {
+        code?: number;
+      };
+    };
+
+    if (
+      typeof maybeResult.result?.code === "number" &&
+      maybeResult.result.code !== 0
+    ) {
+      play("error");
+    }
+  });
+
+  pi.registerCommand("sound-on", {
+    description: "Enable PreApeXis sound cues",
+    handler: async (_args, ctx: EventContext) => {
+      enabled = true;
+      play("done");
+      ctx.ui.notify("Sound cues enabled.", "info");
+    }
+  });
+
+  pi.registerCommand("sound-off", {
+    description: "Disable PreApeXis sound cues",
+    handler: async (_args, ctx: EventContext) => {
+      enabled = false;
+      ctx.ui.notify("Sound cues disabled.", "info");
+    }
+  });
+
+  pi.registerCommand("sound-test", {
+    description: "Test PreApeXis sound cues",
+    handler: async (_args, ctx: EventContext) => {
+      play("need-input");
+      ctx.ui.notify("Sound test played.", "info");
+    }
+  });
+}

package/extensions/status.ts

@@ -0,0 +1,86 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import * as fs from "fs/promises";
+import * as path from "path";
+
+type EventContext = Parameters<Parameters<ExtensionAPI["on"]>[1]>[1];
+
+export default function (pi: ExtensionAPI): void {
+  const STATUS_KEY = "preapexis-kit-status";
+
+  let testStatus = "tests:none";
+
+  async function detectTests(ctx: EventContext): Promise<void> {
+    try {
+      const pkgPath = path.join(ctx.cwd, "package.json");
+      const content = await fs.readFile(pkgPath, "utf-8");
+      const pkg = JSON.parse(content) as {
+        scripts?: Record<string, string>;
+      };
+
+      testStatus =
+        typeof pkg.scripts?.test === "string" ? "tests:not-run" : "tests:none";
+    } catch {
+      testStatus = "tests:none";
+    }
+  }
+
+  function getRepoTrust(ctx: EventContext): string {
+    try {
+      const isProjectTrusted = (
+        ctx as {
+          isProjectTrusted?: () => boolean;
+        }
+      ).isProjectTrusted;
+
+      return isProjectTrusted?.() ? "trusted" : "untrusted";
+    } catch {
+      return "unknown";
+    }
+  }
+
+  function updateStatus(ctx: EventContext): void {
+    if (!ctx.hasUI) return;
+
+    const trust = getRepoTrust(ctx);
+
+    ctx.ui.setStatus(STATUS_KEY, `kit: safe · ${trust} · ${testStatus}`);
+  }
+
+  async function updateAll(ctx: EventContext): Promise<void> {
+    if (!ctx.hasUI) return;
+
+    await detectTests(ctx);
+    updateStatus(ctx);
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    await updateAll(ctx);
+  });
+
+  pi.registerCommand("test-pass", {
+    description: "Mark tests as passed",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+      testStatus = "tests:passed";
+      updateStatus(ctx);
+    }
+  });
+
+  pi.registerCommand("test-fail", {
+    description: "Mark tests as failed",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+      testStatus = "tests:failed";
+      updateStatus(ctx);
+    }
+  });
+
+  pi.registerCommand("test-none", {
+    description: "Mark tests as not run",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+      testStatus = "tests:not-run";
+      updateStatus(ctx);
+    }
+  });
+}