@preapexis/pi-kit 1.0.0

package/extensions/update.ts

@@ -0,0 +1,245 @@
+// cSpell:words Varun Gaikwad preapexis npm PowerShell
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type EventContext = Parameters<Parameters<ExtensionAPI["on"]>[1]>[1];
+
+type UpdateOption = {
+  id: string;
+  label: string;
+  shell: string;
+};
+
+type ShellCommand = {
+  command: string;
+  args: string[];
+};
+
+const RUN_CHOICE = "▶ Run selected updates";
+const CANCEL_CHOICE = "✕ Cancel";
+
+export default function (pi: ExtensionAPI): void {
+  const options: UpdateOption[] = [
+    {
+      id: "pi",
+      label: "Update Pi CLI globally",
+      shell:
+        "npm install -g --ignore-scripts @earendil-works/pi-coding-agent@latest"
+    },
+    {
+      id: "kit-local",
+      label: "Re-link this local PreApeXis kit",
+      shell: "pi install -l ."
+    },
+    {
+      id: "kit-github",
+      label: "Update PreApeXis Pi Kit from GitHub",
+      shell: "pi install git:github.com/VarunGaikwad/preapexis-pi-kit@master"
+    },
+    {
+      id: "kit-npm",
+      label: "Update PreApeXis Pi Kit from npm",
+      shell: "pi install npm:preapexis-pi-kit"
+    },
+    {
+      id: "project-npm",
+      label: "Update current project npm packages",
+      shell: "npm update"
+    }
+  ];
+
+  function shellCommand(command: string): ShellCommand {
+    if (process.platform === "win32") {
+      return {
+        command: "cmd",
+        args: ["/d", "/s", "/c", command]
+      };
+    }
+
+    return {
+      command: "sh",
+      args: ["-lc", command]
+    };
+  }
+
+  function optionLabel(
+    option: UpdateOption,
+    selected: Map<string, UpdateOption>
+  ): string {
+    const marker = selected.has(option.id) ? "✓" : "×";
+    return `${marker} ${option.label}`;
+  }
+
+  function selectedSummary(selected: UpdateOption[]): string {
+    if (selected.length === 0) {
+      return "Selected: none";
+    }
+
+    return ["Selected:", ...selected.map((option) => `- ${option.label}`)].join(
+      "\n"
+    );
+  }
+
+  function buildMenu(selected: Map<string, UpdateOption>): {
+    items: string[];
+    optionByMenuItem: Map<string, UpdateOption>;
+  } {
+    const optionByMenuItem = new Map<string, UpdateOption>();
+
+    const optionItems = options.map((option) => {
+      const label = optionLabel(option, selected);
+      optionByMenuItem.set(label, option);
+      return label;
+    });
+
+    return {
+      items: [...optionItems, RUN_CHOICE, CANCEL_CHOICE],
+      optionByMenuItem
+    };
+  }
+
+  async function chooseUpdates(ctx: EventContext): Promise<UpdateOption[]> {
+    const selected = new Map<string, UpdateOption>();
+
+    while (true) {
+      const { items, optionByMenuItem } = buildMenu(selected);
+
+      const choice = await ctx.ui.select(
+        [
+          "What do you want to update?",
+          "",
+          "Pick an item to toggle it.",
+          "✓ = selected, × = not selected",
+          "",
+          selectedSummary([...selected.values()])
+        ].join("\n"),
+        items
+      );
+
+      if (!choice || choice === CANCEL_CHOICE) {
+        return [];
+      }
+
+      if (choice === RUN_CHOICE) {
+        if (selected.size === 0) {
+          ctx.ui.notify("Select at least one update first.", "warning");
+          continue;
+        }
+
+        return [...selected.values()];
+      }
+
+      const option = optionByMenuItem.get(choice);
+
+      if (!option) {
+        continue;
+      }
+
+      if (selected.has(option.id)) {
+        selected.delete(option.id);
+        ctx.ui.notify(`Removed: ${option.label}`, "info");
+      } else {
+        selected.set(option.id, option);
+        ctx.ui.notify(`Added: ${option.label}`, "info");
+      }
+    }
+  }
+
+  async function runUpdate(
+    option: UpdateOption,
+    ctx: EventContext
+  ): Promise<boolean> {
+    ctx.ui.notify(`Running update:\n\n${option.shell}`, "info");
+
+    const shell = shellCommand(option.shell);
+
+    const result = await pi.exec(shell.command, shell.args, {
+      cwd: ctx.cwd
+    });
+
+    const stdout = result.stdout?.trim() ?? "";
+    const stderr = result.stderr?.trim() ?? "";
+    const output = [stdout, stderr].filter(Boolean).join("\n\n");
+
+    if (result.code === 0) {
+      ctx.ui.notify(
+        [`Update completed: ${option.label}`, "", output || "No output."].join(
+          "\n"
+        ),
+        "info"
+      );
+
+      return true;
+    }
+
+    ctx.ui.notify(
+      [
+        `Update failed: ${option.label}`,
+        "",
+        `Command: ${option.shell}`,
+        `Exit code: ${result.code}`,
+        "",
+        output ||
+          "No output captured. Try running this command manually in PowerShell."
+      ].join("\n"),
+      "error"
+    );
+
+    return false;
+  }
+
+  pi.registerCommand("update", {
+    description: "Update Pi, this Pi kit, or project packages",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        console.log("The /update command requires the Pi UI.");
+        return;
+      }
+
+      const selected = await chooseUpdates(ctx);
+
+      if (selected.length === 0) {
+        ctx.ui.notify("Update cancelled.", "info");
+        return;
+      }
+
+      const summary = selected
+        .map((option) => `- ${option.label}\n  ${option.shell}`)
+        .join("\n");
+
+      const ok = await ctx.ui.confirm(
+        "Confirm updates",
+        `The following updates will run:\n\n${summary}\n\nContinue?`
+      );
+
+      if (!ok) {
+        ctx.ui.notify("Update cancelled.", "info");
+        return;
+      }
+
+      let passed = 0;
+      let failed = 0;
+
+      for (const option of selected) {
+        const updateOk = await runUpdate(option, ctx);
+
+        if (updateOk) {
+          passed += 1;
+        } else {
+          failed += 1;
+        }
+      }
+
+      ctx.ui.notify(
+        [
+          "Update finished.",
+          "",
+          `Passed: ${passed}`,
+          `Failed: ${failed}`,
+          "",
+          "Run /reload or restart Pi if needed."
+        ].join("\n"),
+        failed > 0 ? "warning" : "info"
+      );
+    }
+  });
+}

package/extensions/usage-tracker.ts

@@ -0,0 +1,154 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type EventContext = Parameters<Parameters<ExtensionAPI["on"]>[1]>[1];
+
+type AssistantMessageLike = {
+  role: "assistant";
+  usage?: {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    cost?: {
+      total?: number;
+    };
+  };
+};
+type UsageTotals = {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  cost: number;
+};
+
+export default function (pi: ExtensionAPI): void {
+  const STATUS_KEY = "usage-tracker";
+  let baseline: UsageTotals = emptyTotals();
+
+  function emptyTotals(): UsageTotals {
+    return {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: 0
+    };
+  }
+
+  function formatNumber(value: number): string {
+    if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}m`;
+    if (value >= 1_000) return `${(value / 1_000).toFixed(1)}k`;
+    return String(value);
+  }
+
+  function formatCost(value: number): string {
+    if (value < 0.001) return "$0.000";
+    return `$${value.toFixed(3)}`;
+  }
+
+  function subtractTotals(
+    current: UsageTotals,
+    base: UsageTotals
+  ): UsageTotals {
+    return {
+      input: Math.max(0, current.input - base.input),
+      output: Math.max(0, current.output - base.output),
+      cacheRead: Math.max(0, current.cacheRead - base.cacheRead),
+      cacheWrite: Math.max(0, current.cacheWrite - base.cacheWrite),
+      totalTokens: Math.max(0, current.totalTokens - base.totalTokens),
+      cost: Math.max(0, current.cost - base.cost)
+    };
+  }
+
+  function getUsageTotals(ctx: EventContext): UsageTotals {
+    const totals = emptyTotals();
+
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type !== "message") continue;
+      if (entry.message.role !== "assistant") continue;
+
+      const message = entry.message as AssistantMessageLike;
+      const usage = message.usage;
+
+      if (!usage) continue;
+
+      totals.input += usage.input ?? 0;
+      totals.output += usage.output ?? 0;
+      totals.cacheRead += usage.cacheRead ?? 0;
+      totals.cacheWrite += usage.cacheWrite ?? 0;
+      totals.cost += usage.cost?.total ?? 0;
+    }
+
+    totals.totalTokens =
+      totals.input + totals.output + totals.cacheRead + totals.cacheWrite;
+
+    return totals;
+  }
+
+  function updateStatus(ctx: EventContext): void {
+    if (!ctx.hasUI) return;
+
+    const totals = subtractTotals(getUsageTotals(ctx), baseline);
+
+    ctx.ui.setStatus(
+      STATUS_KEY,
+      `usage: ${formatNumber(totals.totalTokens)} ${formatCost(totals.cost)}`
+    );
+  }
+
+  function buildUsageReport(ctx: EventContext): string {
+    const totals = subtractTotals(getUsageTotals(ctx), baseline);
+
+    return [
+      "Token and price usage",
+      "",
+      `Input tokens: ${totals.input.toLocaleString()}`,
+      `Output tokens: ${totals.output.toLocaleString()}`,
+      `Cache read tokens: ${totals.cacheRead.toLocaleString()}`,
+      `Cache write tokens: ${totals.cacheWrite.toLocaleString()}`,
+      `Total tokens: ${totals.totalTokens.toLocaleString()}`,
+      `Estimated cost: ${formatCost(totals.cost)}`,
+      "",
+      `Model: ${ctx.model?.id ?? "unknown"}`
+    ].join("\n");
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    baseline = emptyTotals();
+    updateStatus(ctx);
+  });
+
+  pi.on("message_end", async (event, ctx) => {
+    if (event.message.role === "assistant") {
+      updateStatus(ctx);
+    }
+  });
+
+  pi.on("model_select", async (_event, ctx) => {
+    updateStatus(ctx);
+  });
+
+  pi.registerCommand("usage", {
+    description: "Show token and price usage for this session",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+      ctx.ui.notify(buildUsageReport(ctx), "info");
+      updateStatus(ctx);
+    }
+  });
+
+  pi.registerCommand("usage-reset", {
+    description: "Reset token and price tracker baseline",
+    handler: async (_args, ctx) => {
+      baseline = getUsageTotals(ctx);
+
+      if (ctx.hasUI) {
+        ctx.ui.notify("Usage tracker reset for this session.", "info");
+        updateStatus(ctx);
+      }
+    }
+  });
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@preapexis/pi-kit",
+  "version": "1.0.0",
+  "description": "Personal Pi coding-agent kit with safety extensions, status UI, prompt workflows, skills, and themes.",
+  "keywords": [
+    "pi-package",
+    "pi-coding-agent",
+    "coding-agent",
+    "prompts",
+    "skills",
+    "extensions"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ],
+    "themes": [
+      "./themes"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "author": "Varun Gaikwad",
+  "license": "ISC",
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/prompts/commit.md

@@ -0,0 +1,79 @@
+# Git Commit Message
+
+Analyze the current changes in this repository and propose a git commit message.
+
+Do not create the commit. Only suggest the message.
+
+## How to read the changes
+
+Run safe git read commands only:
+
+- `git status`
+- `git diff`
+- `git diff --cached`
+- `git log --oneline -5` if useful for style
+
+If there is nothing staged and nothing unstaged, report that no changes are ready to commit.
+
+## Output format
+
+Provide a commit message in this format:
+
+```txt
+<type>: <short summary>
+
+<plain-language explanation>
+
+<technical explanation>
+
+- <specific change 1>
+- <specific change 2>
+```
+
+## Guidelines
+
+1. Use a conventional commit type:
+   - `feat`
+   - `fix`
+   - `refactor`
+   - `docs`
+   - `test`
+   - `chore`
+   - `style`
+   - `build`
+   - `ci`
+
+2. The short summary must be:
+   - one line
+   - concise
+   - imperative mood
+   - no period at the end
+
+3. The plain-language paragraph should explain what changed and why.
+
+4. The technical paragraph should explain the implementation details briefly.
+
+5. The bullet list should include the most important changes.
+
+## Split commits
+
+If there are many unrelated changes, suggest splitting them into multiple commits.
+
+For each group, provide:
+
+```txt
+Commit 1:
+<message>
+
+Commit 2:
+<message>
+```
+
+## Rules
+
+- Do not commit.
+- Do not stage files.
+- Do not edit files.
+- Do not run destructive git commands.
+- Do not include secrets or long raw diffs in the message.
+- Keep the message clear and useful for humans.

package/prompts/implement.md

@@ -0,0 +1,41 @@
+# Implement Plan
+
+Implement the plan below. Do not change scope unless you ask first.
+
+## Plan
+
+{PLAN_CONTENT}
+
+Or, if the plan is saved as a file, provide the path and read it first.
+
+## Steps
+
+1. Read the plan carefully.
+2. Read the project files mentioned in the plan.
+3. Briefly explain the implementation approach before editing.
+4. Implement the steps one by one.
+5. Keep changes small and reviewable.
+6. Run tests, lint, or type checks if available.
+7. Do not delete files or rewrite history without approval.
+
+## Rules
+
+- Follow the plan closely.
+- If something is unclear or blocked, stop and ask.
+- Do not guess important missing details.
+- Prefer editing existing files when it fits the existing project structure.
+- Create new files only when the plan clearly requires it.
+- Match the project's existing style and conventions.
+- Add or update tests for new behavior when appropriate.
+- Run available checks: tests, lint, type check.
+- Do not touch secrets, env files, lockfiles, or generated files unless the plan explicitly requires it and the user approves.
+
+## Output
+
+At the end, summarize:
+
+- What was implemented
+- Files changed
+- Tests added or updated
+- Commands run
+- Anything still pending

package/prompts/init.md

@@ -0,0 +1,98 @@
+# Initialize Repository Understanding
+
+Initialize your understanding of this repository.
+
+Do not edit files.
+
+Your job is to inspect the project and produce a clear onboarding report for future work.
+
+If the repository is large, inspect the most important files first and clearly mention what was not inspected.
+
+## Steps
+
+1. Read the most important project files first:
+   - README.md
+   - AGENTS.md
+   - package.json / pyproject.toml / go.mod / Cargo.toml / pom.xml / build.gradle
+   - CONTRIBUTING.md
+   - docs/
+   - .github/workflows/
+   - docker-compose.yml / Dockerfile
+   - existing test configuration
+
+2. Identify the project structure:
+   - main application entry points
+   - important directories
+   - test locations
+   - config files
+   - generated/build output directories
+   - files that should be treated carefully
+
+3. Detect the development workflow:
+   - install command
+   - dev command
+   - build command
+   - test command
+   - lint command
+   - typecheck command
+   - formatting command
+
+4. Identify safety risks:
+   - secrets or env files
+   - deployment files
+   - database migrations
+   - production config
+   - generated files
+   - lockfiles
+   - destructive scripts
+   - commands that should require confirmation
+
+5. Infer coding conventions:
+   - language/framework
+   - naming style
+   - error handling style
+   - testing style
+   - API conventions
+   - dependency management
+
+## Output
+
+Return a repository onboarding report with these sections:
+
+# Repository Summary
+
+Briefly explain what this project appears to do.
+
+# Tech Stack
+
+List the detected languages, frameworks, libraries, and tools.
+
+# Project Map
+
+Explain the important folders and files.
+
+# Common Commands
+
+List install, dev, build, test, lint, typecheck, and format commands if found.
+
+# Safety Notes
+
+List files, directories, and commands that should be treated carefully.
+
+# Coding Conventions
+
+Summarize the project’s apparent patterns.
+
+# Recommended Agent Rules
+
+Suggest repo-specific rules that should be added to AGENTS.md or team instructions.
+
+# Open Questions
+
+List anything unclear or missing.
+
+# Inspection Notes
+
+Mention important files or areas that were not inspected.
+
+Do not modify the repository unless I explicitly ask.