@danypops/papyrus 0.28.3 → 0.29.0

package/extension/src/playbook-bridge.ts

@@ -1,90 +1,80 @@
 /**
- * playbook-bridge.ts — materializes active Papyrus Playbooks as real SKILL.md files so they
- * show up in Pi's own native skill catalog and become /skill:name-invocable, through Pi's
- * unmodified, documented resources_discover mechanism (no Pi source touched).
+ * playbook-bridge.ts — materializes active Papyrus Playbooks as their own /playbook:name slash
+ * commands, one per playbook, the same one-entry-per-item autocomplete experience Pi's own
+ * /skill:name gives real skills.
  *
- * Playbooks live in SQLite, not on disk, so they can't satisfy Pi's skill-loading pipeline
- * directly (Skill.filePath is required there). This bridges the gap the other direction:
- * on every resources_discover (session start and /reload), wipe and rebuild a cache directory
- * from the current playbooks.list, so a disabled/removed/renamed Playbook's stale file is never
- * served. Any failure degrades to "no extra skills this cycle" -- a Papyrus daemon hiccup must
- * never break Pi's own resource discovery.
+ * /skill:name itself is a hardcoded core mechanism (Pi's interactive mode builds it directly
+ * from its own skill loader) -- not something an extension can retarget to a different prefix.
+ * pi.registerCommand(name, ...) accepts any string, colons included, so "playbook:<slug>"
+ * registers and invokes as literally /playbook:<slug> -- a real, supported extension API, no
+ * core touched.
+ *
+ * Real limitation: ExtensionAPI has no unregisterCommand. A disabled or renamed playbook's old
+ * /playbook:<slug> command lingers until a full Pi restart -- registerCommand can only add or
+ * overwrite, never remove. Mitigated two ways: registrations refresh on every resources_discover
+ * (session start and /reload), so a renamed playbook's NEW slug appears promptly even though the
+ * old one lingers; and each command's handler re-fetches the live playbook by id at invocation
+ * time rather than baking in stale content, so even a lingering stale name fails cleanly with a
+ * real error instead of running deleted content.
  */
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import { callService } from "./service-client.ts";
 
 const PLAYBOOK_BRIDGE_MAX_PLAYBOOKS = 100;
-const PLAYBOOK_BRIDGE_DESCRIPTION_MAX_CHARACTERS = 1000;
 
 function slugify(title: string): string {
 	const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
 	return slug.length > 0 ? slug : "playbook";
 }
 
-function playbookCacheDir(): string {
-	const base = process.env["XDG_CACHE_HOME"] ?? join(homedir(), ".cache");
-	return join(base, "papyrus", "playbooks");
-}
-
-function stringList(value: unknown): string[] {
-	return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+async function activePlaybooks(): Promise<Artifact[]> {
+	return callService<Record<string, unknown>, Artifact[]>("playbooks.list", { status: "active", limit: PLAYBOOK_BRIDGE_MAX_PLAYBOOKS });
 }
 
-function playbookSkillMarkdown(playbook: Artifact): string {
-	const trigger = typeof playbook.extra["trigger"] === "string" ? playbook.extra["trigger"] : "manual invocation";
-	const steps = stringList(playbook.extra["steps"]);
-	const tools = stringList(playbook.extra["tools"]);
-	const description = trigger.replace(/\n/g, " ").slice(0, PLAYBOOK_BRIDGE_DESCRIPTION_MAX_CHARACTERS);
-	return [
-		"---",
-		`name: ${slugify(playbook.title)}`,
-		`description: ${description}`,
-		"---",
-		"",
-		`# ${playbook.title}`,
-		"",
-		`Materialized from a live Papyrus playbook; edits here are lost on the next refresh. Edit the playbook itself instead (the playbooks tool, action=update), then /reload.`,
-		"",
-		`Trigger: ${trigger}`,
-		"",
-		...(playbook.body ? [`Context: ${playbook.body}`, ""] : []),
-		...(steps.length > 0 ? ["## Steps", "", ...steps.map((step, index) => `${index + 1}. ${step}`), ""] : []),
-		...(tools.length > 0 ? [`Tools: ${tools.join(", ")}`, ""] : []),
-	].join("\n");
+/** Exported for direct testing without a real ExtensionAPI. */
+export function playbookCommandName(title: string): string {
+	return `playbook:${slugify(title)}`;
 }
 
-/** Exported for direct testing without a real ExtensionAPI. */
-export async function materializePlaybookSkillPaths(): Promise<string[]> {
-	const dir = playbookCacheDir();
-	if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
-	const playbooks = await callService<Record<string, unknown>, Artifact[]>("playbooks.list", { status: "active", limit: PLAYBOOK_BRIDGE_MAX_PLAYBOOKS });
-	if (playbooks.length === 0) return [];
-	mkdirSync(dir, { recursive: true });
-	const usedSlugs = new Set<string>();
-	const paths: string[] = [];
-	for (const playbook of playbooks) {
-		let slug = slugify(playbook.title);
-		if (usedSlugs.has(slug)) slug = `${slug}-${playbook.id.slice(0, 8)}`; // a real title collision, not the common case
-		usedSlugs.add(slug);
-		const skillDir = join(dir, slug);
-		mkdirSync(skillDir, { recursive: true });
-		const filePath = join(skillDir, "SKILL.md");
-		writeFileSync(filePath, playbookSkillMarkdown(playbook), "utf8");
-		paths.push(filePath);
-	}
-	return paths;
+/** Exported for direct testing without a real ExtensionAPI: what would be registered right now. */
+export async function planPlaybookCommandRegistrations(): Promise<Array<{ name: string; id: string; title: string; trigger: string }>> {
+	const playbooks = await activePlaybooks();
+	const usedNames = new Set<string>();
+	return playbooks.map((playbook) => {
+		let name = playbookCommandName(playbook.title);
+		if (usedNames.has(name)) name = `${name}-${playbook.id.slice(0, 8)}`; // a real title collision, not the common case
+		usedNames.add(name);
+		const trigger = typeof playbook.extra["trigger"] === "string" ? playbook.extra["trigger"] : "manual invocation";
+		return { name, id: playbook.id, title: playbook.title, trigger };
+	});
 }
 
 export function registerPlaybookBridge(pi: ExtensionAPI): void {
-	pi.on("resources_discover", async () => {
+	const refresh = async () => {
 		try {
-			return { skillPaths: await materializePlaybookSkillPaths() };
+			const registrations = await planPlaybookCommandRegistrations();
+			for (const { name, id, title, trigger } of registrations) {
+				pi.registerCommand(name, {
+					description: trigger,
+					handler: async (_args, ctx) => {
+						try {
+							// Re-fetched live, not captured at registration time: a lingering stale
+							// command (renamed or disabled since, since registerCommand can't be
+							// unregistered) must fail cleanly, never run deleted/stale content.
+							const invocation = await callService<Record<string, unknown>, string>("playbooks.invoke", { id });
+							ctx.ui.setEditorText(invocation);
+							ctx.ui.notify(`"${title}" invocation placed in the editor`, "info");
+						} catch (error) {
+							ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+						}
+					},
+				});
+			}
 		} catch {
-			return {};
+			// A Papyrus daemon hiccup must never break Pi's own resource discovery -- degrades to
+			// "no new/updated playbook commands this cycle", not a broken session start.
 		}
-	});
+	};
+	pi.on("resources_discover", async () => { await refresh(); return {}; });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.28.3",
+  "version": "0.29.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],