@aliou/pi-dev-kit 0.4.9 → 0.6.0

package/README.md

@@ -0,0 +1,60 @@
+# Pi Dev Kit
+
+Tools and commands for building, maintaining, and updating Pi extensions.
+
+## Demo
+
+
+
+https://github.com/user-attachments/assets/44a96009-0653-4803-8590-d5a8a5131f4c
+
+<small>
+  <a href="https://assets.aliou.me/pi-extensions/2026-02-02-pi-extension-dev-demo.mp4">Non sped-up version</a>
+</small>
+
+
+## Installation
+
+```bash
+pi install npm:@aliou/pi-dev-kit
+```
+
+Or from git:
+
+```bash
+pi install git:github.com/aliou/pi-dev-kit
+```
+
+Formerly `@aliou/pi-extension-dev`. This package continues from the same release line under a new name.
+
+## Commands
+
+### `/extensions:update [VERSION]`
+
+Update Pi extensions to a target version. Without an argument, checks npm for the latest version and lets you choose between latest and installed. With a version argument, targets that version directly.
+
+Runs a guided workflow: detects the package manager, compares versions, reads changelogs and docs, analyzes source files for breaking changes, presents an update plan, and applies changes after confirmation.
+
+## Tools
+
+### `detect_package_manager`
+
+Detects the package manager used in the current project. Checks the `packageManager` field in `package.json` first, then falls back to lockfile detection (`pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `bun.lockb`). Walks up from the working directory to the git root.
+
+Returns the package manager name, version (if declared), lockfile path, and install/run commands.
+
+### `pi_version`
+
+Returns the version of the currently running Pi instance.
+
+### `pi_docs`
+
+Lists all Pi documentation files from the Pi installation: `README.md`, individual files in `docs/`, and the `examples/` directory path.
+
+### `pi_changelog`
+
+Parses the Pi changelog and returns entries for a specific version (or the latest). When the requested version is newer than the installed Pi, fetches the changelog from GitHub.
+
+## Compatibility
+
+Compatible with Pi 0.50.x and 0.51.0+. Tools that need the extension context use a runtime shim to handle the execute signature difference between versions.

package/package.json

@@ -1,9 +1,70 @@
 {
   "name": "@aliou/pi-dev-kit",
-  "version": "0.4.9",
+  "version": "0.6.0",
   "license": "MIT",
+  "type": "module",
   "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "dev-kit",
+    "meta"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aliou/pi-dev-kit"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./src/skills"
+    ],
+    "prompts": [
+      "./src/prompts"
+    ],
+    "video": "https://assets.aliou.me/pi-extensions/2026-02-02-pi-extension-dev-demo.mp4"
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aliou/pi-utils-ui": "^0.1.0",
+    "@sinclair/typebox": "^0.34.41"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "0.64.0",
+    "@mariozechner/pi-tui": "0.64.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.13",
+    "@changesets/cli": "^2.27.11",
+    "@mariozechner/pi-coding-agent": "0.64.0",
+    "@mariozechner/pi-tui": "0.64.0",
+    "@types/node": "^25.0.10",
+    "husky": "^9.1.7",
+    "typescript": "^5.9.3"
+  },
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-coding-agent": {
+      "optional": true
+    },
+    "@mariozechner/pi-tui": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "format": "biome check --write",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm changeset publish"
   }
-}
+}

package/src/commands/index.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerUpdateCommand } from "./update";
+
+export function registerCommands(pi: ExtensionAPI) {
+  registerUpdateCommand(pi);
+}

package/src/commands/update.ts

@@ -0,0 +1,144 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { VERSION } from "@mariozechner/pi-coding-agent";
+
+const NPM_REGISTRY_URL =
+  "https://registry.npmjs.org/@mariozechner/pi-coding-agent/latest";
+
+async function fetchLatestVersion(): Promise<string | null> {
+  try {
+    const res = await fetch(NPM_REGISTRY_URL);
+    if (!res.ok) return null;
+    const data = (await res.json()) as { version?: string };
+    return data.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+const UPDATE_PROMPT = `# Update Pi Extensions
+
+Update this project's Pi extensions, themes, and components to the specified target Pi version.
+
+## Steps
+
+### 1. Detect Package Manager
+
+Use \`detect_package_manager\` to identify the package manager (npm, pnpm, yarn, bun). Use its install and run commands for all subsequent steps.
+
+### 2. Version Check
+
+The target Pi version is provided above. Read \`./package.json\` to find the current Pi package versions. The relevant packages are any of:
+- \`@mariozechner/pi-ai\`
+- \`@mariozechner/pi-coding-agent\`
+- \`@mariozechner/pi-tui\`
+- \`@mariozechner/pi-agent-core\`
+
+Report the current version in package.json vs the target version. If versions match, stop here -- nothing to update.
+
+### 3. Gather Documentation
+
+If there's a version mismatch:
+1. Use \`pi_changelog\` to get changelog entries for versions between current and target
+2. Use \`pi_docs\` to get paths to Pi documentation
+3. Read the relevant docs, especially:
+   - \`docs/extensions.md\` for extension API changes
+   - Any migration guides or breaking changes noted in changelogs
+
+### 4. Analyze Source
+
+Scan all source files that import from Pi packages:
+1. Find all \`.ts\` and \`.tsx\` files that import from \`@mariozechner/pi-*\`
+2. For each file, identify API usage that needs updating based on changelog/docs
+3. Check overridden tools or tool wrappers for delegated \`tool.execute(...)\` calls; update forwarded parameter order and optional args
+4. Note deprecated patterns or new recommended approaches
+5. Look for custom utility functions that duplicate functionality now available in the Pi SDK -- if the SDK provides an equivalent, flag it for replacement
+
+### 5. Create Update Plan
+
+Present a detailed plan:
+- Package version updates needed (in root and any sub-package.json files with peerDependencies)
+- For each affected file:
+  - Specific API migrations required
+  - Breaking changes and how to address them
+- New features from the changelog that could improve existing code
+- Custom utilities replaceable by SDK exports
+
+### 6. User Confirmation
+
+Present the plan and ask for confirmation before proceeding. Wait for feedback. Iterate on the plan based on user input until agreement is reached.
+
+### 7. Execute Updates
+
+Once confirmed:
+1. Update Pi package versions in \`./package.json\` and any sub-package files (peerDependencies) to the exact target version. Use exact versions (e.g., \`0.51.0\`), not ranges.
+2. Apply the planned code changes
+3. Run the install command from step 1
+4. Run typecheck (\`tsc --build\` or the project's typecheck script)
+5. Run lint if the project has a lint script
+6. Report results and any issues encountered
+
+### 8. Commit Changes
+
+After successful verification:
+1. Check \`git status\` to see all changed files
+2. Stage only files changed by this update -- do not use \`git add .\`
+3. Commit with message format: \`chore: update pi packages to X.Y.Z\`
+4. Include a brief summary of breaking changes addressed in the commit body
+
+## Fallback
+
+If the extension tools (\`pi_changelog\`, \`pi_docs\`, \`detect_package_manager\`) fail -- which can happen when the very update being applied changes the tool calling convention -- fall back to:
+- Changelog: read \`CHANGELOG.md\` from the Pi installation directory
+- Docs: read \`README.md\` and list \`docs/\` from the Pi installation directory
+- Package manager: check for lockfiles manually (\`pnpm-lock.yaml\`, \`yarn.lock\`, \`package-lock.json\`, \`bun.lockb\`)
+
+## Important
+
+- Preserve existing functionality while updating to new APIs
+- Keep changes minimal and focused on API compatibility
+- If unsure about a migration, ask for clarification`;
+
+export function registerUpdateCommand(pi: ExtensionAPI) {
+  pi.registerCommand("extensions:update", {
+    description: "Update Pi extensions to a target version (current or latest)",
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI) return;
+
+      let targetVersion: string;
+
+      if (args?.trim()) {
+        // Version passed as argument.
+        targetVersion = args.trim().replace(/^v/, "");
+      } else {
+        // Fetch latest and let user choose.
+        ctx.ui.setStatus("extensions:update", "Checking latest version...");
+        const latest = await fetchLatestVersion();
+        ctx.ui.setStatus("extensions:update", undefined);
+
+        if (!latest || latest === VERSION) {
+          // Either fetch failed or already on latest -- use installed version.
+          targetVersion = VERSION;
+          if (!latest) {
+            ctx.ui.notify(
+              "Could not fetch latest version from npm, using installed version.",
+              "warning",
+            );
+          }
+        } else {
+          const choice = await ctx.ui.select(
+            `Installed: ${VERSION}, Latest: ${latest}`,
+            [`${latest} (latest)`, `${VERSION} (installed)`],
+          );
+
+          if (choice === undefined) return; // cancelled
+
+          targetVersion = choice.startsWith(latest) ? latest : VERSION;
+        }
+      }
+
+      pi.sendUserMessage(
+        `Target Pi version: ${targetVersion}\n\n${UPDATE_PROMPT}`,
+      );
+    },
+  });
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerCommands } from "./commands";
+import { setupTools } from "./tools";
+
+export default function (pi: ExtensionAPI) {
+  setupTools(pi);
+  registerCommands(pi);
+}

package/src/prompts/setup-demo.md

@@ -0,0 +1,35 @@
+---
+description: Create a demo environment for a Pi extension
+---
+
+Set up a demo directory for a Pi extension. Load the `demo-setup` skill first, then follow these steps:
+
+## 1. Find the extension
+
+If the current directory contains a `package.json` with a `pi` key, use it. Otherwise, ask the user for the path to the extension.
+
+Read the extension's `package.json`, `README.md`, and source files to understand:
+- What tools it registers
+- What commands it provides
+- What hooks it uses
+- Whether it's a provider, theme, or standard extension
+
+## 2. Create the demo directory
+
+```bash
+demo_dir=$(mktemp -d -t pi-demo-XXXXXX)
+mkdir -p "$demo_dir/.pi/prompts"
+```
+
+## 3. Set up the demo
+
+Follow the `demo-setup` skill to create:
+- `.pi/settings.json` registering the extension by absolute path
+- `.pi/prompts/demo.md` with steps covering each feature
+- Fixture files appropriate for the extension type
+- `AGENTS.md` if the agent needs behavioral instructions
+- `.pi/extensions/<name>.json` if config overrides are needed
+
+## 4. Print the result
+
+Print the demo directory path and instructions for the user.

package/src/skills/demo-setup/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: demo-setup
+description: Set up demo environments for Pi extensions to record videos or screenshots for the Pi package browser. Use when preparing a demo, recording a video, or creating preview assets for an extension or theme.
+---
+
+# Demo Setup
+
+Set up self-contained demo directories for Pi extensions. The demo directory contains everything needed to showcase an extension: a prompt that runs through the features, fixture files, and pi configuration.
+
+## Pi Package Browser
+
+The Pi website has a package browser at `buildwithpi.ai/packages`. Packages can display preview media.
+
+### Adding Preview Media to package.json
+
+```json
+{
+  "pi": {
+    "extensions": ["./index.ts"],
+    "video": "https://example.com/demo.mp4",
+    "image": "https://example.com/preview.png"
+  }
+}
+```
+
+Both `video` and `image` are optional. Video takes precedence when present.
+
+### Video/Image Specs
+
+- **Aspect ratio**: 16:9 (enforced by `aspect-ratio: 16/9` CSS)
+- **Recommended resolution**: 1920x1080
+- **Object fit**: `contain` on black background
+- **Modal max width**: 900px
+- **Format**: `.mp4` for video, `.png`/`.jpg`/`.jpeg`/`.webp`/`.gif` for image
+- **Caching**: Client-side localStorage, 15-minute TTL. New visitors or cleared cache see updates immediately.
+
+### For Themes
+
+Themes show better as images (screenshots of dark and light variants side by side). A single 16:9 image with both variants is ideal.
+
+## Northwind Base Project
+
+Northwind is a fictive Node.js REST API project used as the base environment for demos. It provides a realistic project structure with shell scripts, config files, and database workflows that extensions can hook into.
+
+Use Northwind when the demo needs a project context. Customize it freely -- add files, remove scripts, tweak behavior to highlight the extension's features. Northwind is a starting point, not a rigid template.
+
+### Project context
+
+Northwind is a trading company API with:
+- Customers, products, orders, categories, suppliers
+- PostgreSQL database with migrations and seed data
+- A "shipping address" feature being developed (used for stateful test flows)
+- Config files: `.env`, `.env.example`, `drizzle.config.ts`
+- Common project files: `package.json`, `tsconfig.json`, `scripts/`
+
+### Available scripts
+
+These are the full set. Pick only what your demo needs.
+
+| Script | Command | Behavior |
+|--------|---------|----------|
+| `scripts/server.sh` | `npm run server` | Long-running API server with request logs on port 4000 |
+| `scripts/dev.sh` | `npm run dev` | Long-running dev server with HMR updates |
+| `scripts/test.sh` | `npm run test` | Stateful test suite (see below) |
+| `scripts/migrate.sh` | `npm run migrate` | Runs migrations (creates `/tmp/northwind-migrated`) |
+| `scripts/seed.sh` | `npm run seed` | Seeds fake data (creates `/tmp/northwind-seeded`) |
+| `scripts/reset.sh` | `npm run reset` | Clears state files for re-runs |
+| `scripts/build.sh` | `npm run build` | 5-step production build, exits 0 |
+| `scripts/lint.sh` | `npm run lint` | Lint check with warnings and errors, exits 1 |
+| `scripts/typecheck.sh` | `npm run typecheck` | Type check with 2 errors, exits 1 |
+| `scripts/test-watch.sh` | `npm run test:watch` | Continuous test watcher |
+
+### Stateful test flow
+
+The test script uses marker files (`/tmp/northwind-migrated`, `/tmp/northwind-seeded`) to determine which stage the project is at:
+
+1. **No migration**: tests fail with `relation "shipping_addresses" does not exist`
+2. **Migrated, no seed**: tests fail with `customer.shippingAddress` undefined
+3. **Migrated + seeded**: all tests pass
+
+Run `npm run reset` before each demo to clear state.
+
+### Customizing Northwind for your extension
+
+You should adapt the project to create scenarios that naturally exercise your extension. Examples:
+
+- **Guardrails**: add `.env` with real-looking secrets, `.env.example` with safe patterns, `drizzle.config.ts` for ORM config. The demo prompt can ask the agent to manually write a migration file (which guardrails should block, since the project uses `drizzle-kit generate`).
+- **Processes**: use the long-running scripts (server, dev, test-watch) to show background process management.
+- **Custom tools**: add project files that the tool operates on.
+- **Hooks**: add files or configs that trigger hook patterns (blocked and allowed cases).
+
+Add whatever files make sense: `.env`, `drizzle.config.ts`, `src/` stubs, `docker-compose.yml`, etc. The scripts are just bash with sleep/echo -- easy to create new ones or modify existing ones.
+
+## Demo Directory Structure
+
+```
+<demo-dir>/
+├── northwind/                     # The fake project (agent runs pi here)
+│   ├── .pi/
+│   │   ├── settings.json          # Registers the extension as a local path
+│   │   └── prompts/
+│   │       └── <demo-name>.md     # The demo prompt
+│   ├── AGENTS.md                  # Agent instructions
+│   ├── package.json               # npm scripts pointing to shell scripts
+│   └── scripts/                   # Simulated shell scripts
+├── shell.nix                      # Nix dev environment (outside northwind)
+└── .envrc                         # direnv config (outside northwind)
+```
+
+The outer directory holds the Nix/direnv setup. The inner `northwind/` directory is where pi runs. This way oh-my-posh (or similar prompt tools) display "northwind" in the terminal prompt.
+
+## Setup Workflow
+
+### 1. Detect the Extension
+
+Check `package.json` in the target directory for a `pi` key with `extensions`, `themes`, or `skills`. Read the README and source to understand what the extension provides: tools, commands, hooks, providers, themes.
+
+### 2. Create Demo Directory
+
+```bash
+demo_dir="<path>"
+mkdir -p "$demo_dir/northwind/.pi/prompts"
+mkdir -p "$demo_dir/northwind/scripts"
+```
+
+### 3. Register the Extension
+
+Create `northwind/.pi/settings.json` pointing to the extension's absolute path:
+
+```json
+{
+  "packages": [
+    "/absolute/path/to/extension"
+  ],
+  "defaultThinkingLevel": "off"
+}
+```
+
+Use `defaultThinkingLevel: "off"` to keep responses fast and visible during demos.
+
+### 4. Write the Demo Prompt
+
+Create `northwind/.pi/prompts/<demo-name>.md`. Name it after what the demo shows (e.g., `test-shipping-feature.md`). Structure it as numbered steps that run without user confirmation between steps.
+
+```markdown
+---
+description: Showcase the <extension-name> extension
+---
+
+Demo the <extension-name> extension by <scenario>. Run through all steps without waiting for confirmation. Keep messages short.
+
+## 1. <Step Name>
+
+<What to do.>
+
+## 2. <Next Step>
+
+...
+```
+
+### 5. Add Fixture Files
+
+Start from the Northwind base and customize:
+
+- Copy relevant scripts into `northwind/scripts/`
+- Create `northwind/package.json` with npm script entries
+- Add project files the extension needs (`.env`, config files, source stubs, etc.)
+- Create new scripts if the demo needs behaviors Northwind doesn't provide
+
+### 6. Add AGENTS.md
+
+Always add a `northwind/AGENTS.md` that:
+- Describes the project briefly
+- Lists available scripts and project files
+- Instructs the agent to NOT search the codebase or read source files
+- Tells the agent to just run the scripts and use the files as-is
+
+The AGENTS.md should make the agent feel like it's working in a real project. Tailor it to the extension -- for guardrails, mention the ORM and conventions; for processes, emphasize which scripts are long-running.
+
+## Demo Prompt Patterns by Extension Type
+
+### Extensions with Tools
+
+Build a narrative workflow (like "test a new feature" or "set up the project") that naturally exercises the tools. The agent should encounter problems and react to them, not just call tools in sequence.
+
+### Extensions with Hooks
+
+Build a workflow where the agent naturally triggers hooks. Include both blocked and allowed cases so the demo shows the extension intervening and also stepping aside. For example: the agent tries to manually write a migration (blocked), then uses the ORM generate command instead (allowed).
+
+### Extensions with Commands
+
+Run each command (e.g., `/extension:command`) to show the interactive UI.
+
+### Extensions with Providers
+
+1. Switch to the provider: `/model <provider>`
+2. Send a test message
+3. Show provider-specific commands (quotas, usage, balance)
+4. If the provider has tools (web search), use them
+5. Switch back to default provider
+
+### Themes
+
+Themes don't need Northwind. Just switch themes and write a code file for syntax highlighting.
+
+## Output
+
+After creating the demo directory, print the path and instructions:
+
+```
+Demo ready at: <path>
+
+  cd <path>/northwind
+  pi
+
+Then type /<demo-name> to start.
+```