pi-short-links 0.1.0

package/docs/template-sync-checklist.md

@@ -0,0 +1,69 @@
+# Template Sync Checklist
+
+`create-pi-extension` CLI を publish する前に、テンプレートソース（このリポジトリルート）と CLI にバンドルされるテンプレートが一致していることを確認するためのチェックリスト。
+
+## Before sync
+
+- [ ] `docs/examples.md` が現在の extension / skill / prompt / theme の example を正しく説明している
+- [ ] 新しく追加したファイルが `sync-template.ts` の exclude リストで除外されていない
+- [ ] 削除したファイルが `sync-template.ts` の exclude リストから削除されている
+- [ ] 新規 resource type（extension, skill, prompt, theme）を追加した場合、`docs/examples.md` に例を追記した
+- [ ] `scaffold/package-readme.md` に新しい resource type の記述が反映されている（該当する場合）
+
+## Run sync
+
+- [ ] `bun run sync:template` を実行して `packages/create-pi-extension/template/` を再生成する
+- [ ] 生成されたファイル数が期待通りであることを確認する（目安: 47 ファイル。`ROADMAP.md` は maintainer-only のため除外）
+
+## Verify synced template
+
+- [ ] `packages/create-pi-extension/template/` に必要なファイルがすべて含まれている
+  - [ ] `package.json`（workspaces 削除・sync:template script 削除済み）
+  - [ ] `README.md`（scaffold/package-readme.md の内容）
+  - [ ] `extensions/hello.ts`, `extensions/index.ts`, `extensions/tui-dashboard.ts`, `extensions/skill-bridge/`, `extensions/package-layout/`
+  - [ ] `skills/example-skill/SKILL.md`
+  - [ ] `prompts/example.md`
+  - [ ] `themes/example-theme.json`
+  - [ ] `docs/examples.md`
+  - [ ] `.github/workflows/ci.yml` と `.github/workflows/publish.yml`
+- [ ] 除外されるべきディレクトリが含まれていないこと
+  - [ ] `packages/` がない
+  - [ ] `.git/` がない
+  - [ ] `node_modules/` がない
+  - [ ] `package-lock.json` がない
+
+## Verify template package.json
+
+- [ ] `workspaces` フィールドが削除されている
+- [ ] `scripts.ci` が `"npm run typecheck && npm test && npm run pack:check"` になっている
+- [ ] `scripts["sync:template"]` と `scripts["sync:template:check"]` が削除されている
+- [ ] `scripts["pack:check"]` が `"npm pack --dry-run"` になっている
+- [ ] `version` が root `package.json` の repository version と一致している
+
+## CI check
+
+- [ ] `npm run typecheck` が通る
+- [ ] `npm test` がすべてのテストにパスする
+  - [ ] `tests/greeting.test.mjs`
+  - [ ] `tests/format-table.test.mjs`
+  - [ ] `tests/smoke.test.mjs`
+  - [ ] `tests/create-pi-extension-cli.test.mjs`
+- [ ] `npm run sync:template` を再実行して `tests/sync-template.test.mjs` がパスする
+- [ ] `node --test tests/sync-template.test.mjs` がパスする
+
+## CLI scaffold test（オプションだが推奨）
+
+- [ ] 一時ディレクトリで `node packages/create-pi-extension/src/cli.mjs test-refresh-pkg` を実行する
+- [ ] 生成されたプロジェクトで `npm run ci` が通る
+- [ ] `pi -e .` が extension をロードできる（Pi が利用可能な環境で）
+
+## Before publish
+
+- [ ] CHANGELOG.md に新しいバージョンのリリースノートを追記した
+- [ ] 既存の issue / PR と競合していないことを確認した
+- [ ] `docs/release.md` の手順に従って publish する準備ができている
+
+## Post-publish
+
+- [ ] `npm view create-pi-extension` で新しいバージョンが反映されていることを確認する
+- [ ] 新しいバージョンの CLI で scaffold して動作確認する

package/docs/template-sync.md

@@ -0,0 +1,42 @@
+# Template sync for create-pi-extension
+
+The `create-pi-extension` CLI package ships a generated copy of the **template source** (this repository root). Maintainers refresh that bundle before publishing the CLI.
+
+## Command
+
+From the repository root:
+
+```bash
+bun run sync:template
+```
+
+This writes to `packages/create-pi-extension/template/`. The directory is gitignored because it is generated output.
+
+## What gets copied
+
+Everything under the repository root is copied recursively, except the **sync exclusion list**:
+
+- `packages/`
+- `scaffold/`
+- `node_modules/`
+- `.git/`
+- root `package-lock.json`
+- root `bun.lock` / `bun.lockb`
+- `ROADMAP.md` (maintainer-only planning doc for this repository)
+
+## Version sync
+
+The root `package.json` **repository version** is copied into `packages/create-pi-extension/package.json` on every sync.
+
+## Template package.json cleanup
+
+The synced `template/package.json` has monorepo-only fields removed (`workspaces`, `sync:template` script) so the bundled template stays a standalone Pi package.
+
+## CI check
+
+`npm run ci` runs `sync:template:check`, which regenerates the template and runs `tests/sync-template.test.mjs`.
+
+## See also
+
+- [`docs/template-sync-checklist.md`](template-sync-checklist.md) — maintainer checklist before publishing the CLI
+- [`packages/create-pi-extension/`](../packages/create-pi-extension/) — scaffold CLI source

package/docs/typescript.md

@@ -0,0 +1,97 @@
+# TypeScript Guide
+
+> **Template bootstrap doc.** Use while learning this template's TypeScript layout and dependency rules. Delete this file or summarize the policies you keep in README Development once setup is done, unless it still adds maintainer value.
+
+This is a TypeScript-first Pi package template.
+
+## Layout
+
+```txt
+extensions/*.ts      Pi extension entrypoints
+lib/*.ts             Shared TypeScript helpers
+skills/*/SKILL.md    Agent Skills
+prompts/*.md         Prompt templates
+themes/*.json        Themes
+tests/*.test.mjs     Smoke tests
+tests/*.test.ts      Optional TypeScript tests if you add a TS test runner
+```
+
+Pi loads TypeScript extensions directly, so no build step is required for normal use.
+
+## Strict mode
+
+`tsconfig.json` keeps `strict: true`. Prefer fixing types over loosening compiler options.
+
+## Extension entrypoints
+
+Two entrypoint styles are shown:
+
+- `extensions/hello.ts`: single-file extension
+- `extensions/index.ts`: index-style extension that imports shared code from `lib/`
+
+For larger packages, keep entrypoints thin and put reusable logic in `lib/`.
+
+Both files are listed explicitly under `pi.extensions` in `package.json`. Do not
+"simplify" this to the directory shorthand `["./extensions"]`: Pi resolves a
+manifest directory entry to its `index.ts`, so `hello.ts` (and its
+`/template-hello` command) would silently fail to load. Listing each entry file
+keeps every documented entrypoint active.
+
+## TypeBox schemas
+
+Use TypeBox schemas for custom tool parameters.
+
+```ts
+import { Type } from "typebox";
+
+const parameters = Type.Object({
+  name: Type.String({ description: "Name to greet" }),
+});
+```
+
+## String enums
+
+For string choices, use `StringEnum` from `@earendil-works/pi-ai`.
+
+```ts
+import { StringEnum } from "@earendil-works/pi-ai";
+
+const mode = StringEnum(["short", "friendly"] as const, {
+  description: "Greeting style",
+});
+```
+
+This emits a JSON Schema `enum`, which is friendlier to model providers than a union of string literals.
+
+## TUI availability (`ctx.hasUI`)
+
+Extensions may run in headless or RPC-only sessions where `ctx.ui` is unavailable.
+Guard every `ctx.ui` call with `ctx.hasUI` (or return early from command handlers when `!ctx.hasUI`).
+
+```ts
+pi.on("session_start", async (_event, ctx) => {
+  if (ctx.hasUI) {
+    ctx.ui.setStatus("my-ext", "ready");
+  }
+});
+```
+
+## Runtime dependencies vs peer dependencies
+
+Pi bundles core packages for extension authors. Keep Pi-provided packages as `peerDependencies` and also install them as `devDependencies` for local typechecking.
+
+Use `peerDependencies` for:
+
+- `@earendil-works/pi-coding-agent`
+- `@earendil-works/pi-agent-core`
+- `@earendil-works/pi-ai`
+- `@earendil-works/pi-tui`
+- `typebox`
+
+Use `dependencies` for runtime packages your extension imports that Pi does not provide.
+
+Use `devDependencies` for local-only tools such as TypeScript, test runners, and linters.
+
+## Package contents
+
+Control npm package contents with `package.json` `files`. Prefer this over `.npmignore` so the published package stays explicit.

package/extensions/hello.ts

@@ -0,0 +1,128 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+
+interface TemplateStatusEntry {
+  message: string;
+  timestamp: number;
+}
+
+export default function (pi: ExtensionAPI) {
+  let injectTemplateHint = true;
+  let turnCount = 0;
+
+  pi.registerEntryRenderer<TemplateStatusEntry>("template-status", (entry, { expanded }, theme) => {
+    const data = entry.data ?? { message: "Template status", timestamp: Date.now() };
+    const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+    box.addChild(new Text(`${theme.fg("accent", "[template]")} ${data.message}`, 0, 0));
+    if (expanded) {
+      box.addChild(new Text(theme.fg("dim", new Date(data.timestamp).toLocaleString()), 0, 0));
+    }
+    return box;
+  });
+
+  // Fires once when a Pi session starts (new or resumed).
+  pi.on("session_start", async (_event, ctx) => {
+    turnCount = 0;
+    if (ctx.hasUI) {
+      ctx.ui.setStatus("template", "Pi template loaded");
+    }
+  });
+
+  // Fires before each agent turn, after the system prompt is assembled.
+  // Return { systemPrompt } to append teaching context without blocking the turn.
+  pi.on("before_agent_start", async (event) => {
+    if (!injectTemplateHint) {
+      return undefined;
+    }
+    injectTemplateHint = false;
+
+    return {
+      systemPrompt:
+        event.systemPrompt +
+        "\n\n[pi-extension-template] Event handlers in extensions/hello.ts are active. Type ?template for help, or try /template-dashboard and /template-layout.",
+    };
+  });
+
+  // Fires when the user submits input, before the agent processes it.
+  // Return { action: "handled" } to short-circuit the agent for simple commands.
+  pi.on("input", async (event, ctx) => {
+    if (event.source === "extension") {
+      return { action: "continue" };
+    }
+
+    if (event.text.trim() === "?template") {
+      if (ctx.hasUI) {
+        ctx.ui.notify(
+          "Pi extension template loaded. Try /template-hello, /template-dashboard, /template-layout, /template-skill-info, or inspect tool_call / tool_result logs.",
+          "info",
+        );
+      }
+      return { action: "handled" };
+    }
+
+    return { action: "continue" };
+  });
+
+  pi.on("turn_start", async (_event, ctx) => {
+    turnCount += 1;
+    if (ctx.hasUI) {
+      ctx.ui.setStatus("template", `Turn ${turnCount}...`);
+    }
+  });
+
+  pi.on("turn_end", async (_event, ctx) => {
+    if (ctx.hasUI) {
+      ctx.ui.setStatus("template", `Turn ${turnCount} complete`);
+    }
+  });
+
+  // Fires when tool execution begins. Use alongside tool_call when you need both
+  // lifecycle logging and argument mutation/blocking hooks.
+  pi.on("tool_execution_start", async (event) => {
+    console.log(`[pi-extension-template] tool_execution_start: ${event.toolName} (${event.toolCallId})`);
+    return undefined;
+  });
+
+  // Fires before a built-in or extension tool executes. Non-blocking logging only.
+  pi.on("tool_call", async (event) => {
+    console.log(`[pi-extension-template] tool_call: ${event.toolName} (${event.toolCallId})`);
+    return undefined;
+  });
+
+  // Fires after a tool finishes. Logs outcome; extensions may also return content/details overrides.
+  pi.on("tool_result", async (event) => {
+    const status = event.isError ? "error" : "ok";
+    console.log(`[pi-extension-template] tool_result: ${event.toolName} ${status} (${event.toolCallId})`);
+    return undefined;
+  });
+
+  pi.on("tool_execution_end", async (event) => {
+    const status = event.isError ? "error" : "ok";
+    console.log(`[pi-extension-template] tool_execution_end: ${event.toolName} ${status} (${event.toolCallId})`);
+    return undefined;
+  });
+
+  pi.on("session_shutdown", async () => {
+    turnCount = 0;
+  });
+
+  pi.registerCommand("template-hello", {
+    description: "Show a hello message from this Pi package template",
+    handler: async (args, ctx) => {
+      const name = args.trim() || "Pi";
+      if (ctx.hasUI) {
+        ctx.ui.notify(`Hello, ${name}!`, "info");
+      }
+    },
+  });
+
+  pi.registerCommand("template-status", {
+    description: "Append a TUI-only status card that is not sent to the LLM",
+    handler: async (args) => {
+      pi.appendEntry<TemplateStatusEntry>("template-status", {
+        message: args.trim() || "Template package loaded",
+        timestamp: Date.now(),
+      });
+    },
+  });
+}

package/extensions/index.ts

@@ -0,0 +1,90 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { formatGreeting, type GreetingMode } from "../lib/greeting.ts";
+import { StringEnum } from "@earendil-works/pi-ai";
+
+const greetParameters = Type.Object({
+  name: Type.String({ description: "Name to greet" }),
+  mode: StringEnum(["short", "friendly"] as const, {
+    description: "Greeting style. Prefer short unless the user asks for more warmth.",
+  }),
+});
+
+type GreetParams = {
+  name: string;
+  mode: GreetingMode;
+};
+
+function normalizeGreetArgs(args: unknown): GreetParams {
+  if (!args || typeof args !== "object") {
+    return args as GreetParams;
+  }
+
+  const input = args as {
+    name?: string;
+    mode?: GreetingMode;
+    greetingStyle?: GreetingMode;
+  };
+
+  if (input.greetingStyle && input.mode === undefined) {
+    return { name: input.name ?? "Pi", mode: input.greetingStyle };
+  }
+
+  return args as GreetParams;
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("template-info", {
+    description: "Show TypeScript template information",
+    handler: async (_args, ctx) => {
+      if (ctx.hasUI) {
+        ctx.ui.notify("TypeScript-first Pi package template loaded.", "info");
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "template_greet",
+    label: "Template Greet",
+    description: "Return a typed greeting from the Pi package template",
+    promptSnippet: "template_greet: return a typed greeting from the template package",
+    promptGuidelines: [
+      "Use template_greet only when testing this template package or greeting the user.",
+    ],
+    parameters: greetParameters,
+    prepareArguments: normalizeGreetArgs,
+    async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+      if (signal?.aborted) {
+        return { content: [{ type: "text", text: "Cancelled" }], details: {} };
+      }
+
+      const message = formatGreeting(params);
+
+      return {
+        content: [{ type: "text", text: message }],
+        details: { message, mode: params.mode },
+      };
+    },
+
+    renderCall(args, theme, _context) {
+      let text = theme.fg("toolTitle", theme.bold("template_greet "));
+      text += theme.fg("accent", `name=${args.name}`);
+      text += theme.fg("dim", ` mode=${args.mode}`);
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme, _context) {
+      const details = result.details as { message: string; mode: string } | undefined;
+      const content = result.content[0];
+      const message =
+        details?.message ?? (content?.type === "text" ? content.text : "");
+
+      let text = theme.fg("success", "→ ") + theme.fg("text", message);
+      if (expanded && details) {
+        text += `\n${theme.fg("dim", `mode: ${details.mode}`)}`;
+      }
+      return new Text(text, 0, 0);
+    },
+  });
+}

package/extensions/package-layout/index.ts

@@ -0,0 +1,49 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { formatTable } from "../../lib/format-table.ts";
+import { defaultPackageLayoutConfig } from "./lib/config.ts";
+import { getPackageResourceRows } from "./lib/stats.ts";
+
+const config = defaultPackageLayoutConfig;
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    if (ctx.hasUI) {
+      ctx.ui.setStatus(config.statusLabel, config.title);
+    }
+  });
+
+  pi.registerCommand("template-layout", {
+    description: "Show Pi package resource layout from a multi-file extension",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        return;
+      }
+
+      const rows = getPackageResourceRows();
+      const tableLines = formatTable(rows, [
+        { header: "Kind", render: (row) => row.kind },
+        { header: "Path", render: (row) => row.path },
+        { header: "Examples", render: (row) => row.examples },
+      ]);
+
+      const widgetLines = [config.title, "", ...tableLines];
+      if (config.showSkillHint) {
+        widgetLines.push("", "Skills: static skills/ dir + extensions/skill-bridge via resources_discover");
+      }
+
+      ctx.ui.setWidget("template-layout", widgetLines, { placement: "belowEditor" });
+      ctx.ui.notify("Package layout shown below the editor. Clear with /template-layout-clear.", "info");
+    },
+  });
+
+  pi.registerCommand("template-layout-clear", {
+    description: "Clear the package layout widget",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        return;
+      }
+
+      ctx.ui.setWidget("template-layout", undefined);
+    },
+  });
+}

package/extensions/package-layout/lib/config.ts

@@ -0,0 +1,9 @@
+import { parsePackageLayoutConfig, type PackageLayoutConfig } from "../../../lib/config-contract.ts";
+
+export type { PackageLayoutConfig } from "../../../lib/config-contract.ts";
+
+export const defaultPackageLayoutConfig: PackageLayoutConfig = parsePackageLayoutConfig({
+  title: "Pi package layout",
+  statusLabel: "layout",
+  showSkillHint: true,
+});

package/extensions/package-layout/lib/stats.ts

@@ -0,0 +1,35 @@
+export interface PackageResourceRow {
+  kind: string;
+  path: string;
+  examples: string;
+}
+
+export function getPackageResourceRows(): PackageResourceRow[] {
+  return [
+    {
+      kind: "extensions",
+      path: "extensions/",
+      examples: "hello.ts, index.ts, tui-dashboard.ts, skill-bridge/, package-layout/",
+    },
+    {
+      kind: "skills",
+      path: "skills/",
+      examples: "example-skill/SKILL.md",
+    },
+    {
+      kind: "prompts",
+      path: "prompts/",
+      examples: "example.md",
+    },
+    {
+      kind: "themes",
+      path: "themes/",
+      examples: "example-theme.json",
+    },
+    {
+      kind: "shared lib",
+      path: "lib/",
+      examples: "greeting.ts, format-table.ts",
+    },
+  ];
+}

package/extensions/short-links.ts

@@ -0,0 +1,64 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getCapabilities, setCapabilities } from "@earendil-works/pi-tui";
+import {
+	getMaxLabelWidth,
+	shortenAssistantText,
+	shouldForceHyperlinks,
+} from "../lib/shorten.ts";
+
+function enableHyperlinksIfNeeded(): boolean {
+	if (!shouldForceHyperlinks()) return false;
+	const caps = getCapabilities();
+	if (caps.hyperlinks) return false;
+	setCapabilities({ ...caps, hyperlinks: true });
+	return true;
+}
+
+export default function (pi: ExtensionAPI) {
+	const forcedAtLoad = enableHyperlinksIfNeeded();
+
+	pi.on("session_start", async (_event, ctx) => {
+		const justForced = enableHyperlinksIfNeeded();
+		if (!ctx.hasUI || !(forcedAtLoad || justForced) || !getCapabilities().hyperlinks) {
+			return;
+		}
+		ctx.ui.setStatus("pi-short-links", "short-links: OSC 8 on");
+		setTimeout(() => {
+			try {
+				ctx.ui.setStatus("pi-short-links", undefined);
+			} catch {
+				// session may already be gone
+			}
+		}, 2500);
+	});
+
+	pi.on("message_end", (event, ctx) => {
+		if (event.message.role !== "assistant") return;
+
+		const message = event.message;
+		if (!("content" in message) || !Array.isArray(message.content)) return;
+
+		const maxWidth = getMaxLabelWidth();
+		let changed = false;
+		const content = message.content.map((block) => {
+			if (!block || typeof block !== "object" || !("type" in block)) return block;
+			if (block.type !== "text" || typeof block.text !== "string") return block;
+			const rewritten = shortenAssistantText(block.text, {
+				maxWidth,
+				cwd: ctx.cwd,
+			});
+			if (rewritten === block.text) return block;
+			changed = true;
+			return { ...block, text: rewritten };
+		});
+
+		if (!changed) return;
+
+		return {
+			message: {
+				...message,
+				content,
+			},
+		};
+	});
+}

package/extensions/skill-bridge/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: template-skill-bridge
+description: Template skill contributed by extensions/skill-bridge via resources_discover. Use when testing extension-provided Agent Skills or /skill:template-skill-bridge.
+---
+
+# Template Skill Bridge
+
+This skill is registered at runtime by `extensions/skill-bridge/index.ts` through the `resources_discover` event.
+
+## When to use
+
+- Verify that an extension can contribute skills without editing `package.json`
+- Demonstrate dynamic skill discovery alongside static `skills/` package resources
+
+## Response pattern
+
+- Confirm the skill loaded from the extension directory
+- Mention `/template-skill-info` for the companion command
+- Point maintainers to `extensions/skill-bridge/SKILL.md` as the file to customize

package/extensions/skill-bridge/index.ts

@@ -0,0 +1,25 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const baseDir = dirname(fileURLToPath(import.meta.url));
+
+export default function (pi: ExtensionAPI) {
+  pi.on("resources_discover", () => ({
+    skillPaths: [join(baseDir, "SKILL.md")],
+  }));
+
+  pi.registerCommand("template-skill-info", {
+    description: "Explain how this extension contributes an Agent Skill",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        return;
+      }
+
+      ctx.ui.notify(
+        "Skill bridge active. Try /skill:template-skill-bridge or ask the agent to use the template skill.",
+        "info",
+      );
+    },
+  });
+}