@juicesharp/rpiv-pi 0.4.0

package/extensions/rpiv-core/guidance.ts

@@ -0,0 +1,213 @@
+/**
+ * Guidance injection — resolves and injects subfolder guidance files.
+ *
+ * At each directory depth from project root down to the touched file's
+ * directory, picks the first existing of:
+ *   AGENTS.md > CLAUDE.md > .rpiv/guidance/<sub>/architecture.md
+ *
+ * Depth 0 (project root) skips AGENTS.md/CLAUDE.md because Pi's own
+ * resource-loader (loadContextFileFromDir at resource-loader.js:30-46)
+ * already loads <cwd>/AGENTS.md or <cwd>/CLAUDE.md into the system
+ * prompt's # Project Context block. Depth 0 still checks
+ * <cwd>/.rpiv/guidance/architecture.md — Pi's loader does not see that
+ * path.
+ *
+ * `resolveGuidance` is pure logic with no ExtensionAPI references
+ * (utility-module rule from extensions/rpiv-core/CLAUDE.md). Side
+ * effects (sendMessage, in-memory dedup Set) live in
+ * `handleToolCallGuidance`, `injectRootGuidance`, and
+ * `clearInjectionState`.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, relative, sep, isAbsolute, join } from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+// ---------------------------------------------------------------------------
+// Guidance Resolution
+// ---------------------------------------------------------------------------
+
+type GuidanceKind = "agents" | "claude" | "architecture";
+
+interface GuidanceFile {
+	/** Forward-slash-normalized path from project root — stable dedup key. */
+	relativePath: string;
+	absolutePath: string;
+	content: string;
+	kind: GuidanceKind;
+}
+
+/**
+ * Resolve guidance files for a given file path.
+ *
+ * Walks from project root to the file's directory. At each depth, picks
+ * the first existing of AGENTS.md > CLAUDE.md > architecture.md (Pi's
+ * own per-dir precedence at resource-loader.js:30-46, extended with
+ * architecture.md as a third candidate). Depth 0 only checks
+ * architecture.md — Pi's loader already handles <cwd>/AGENTS.md and
+ * <cwd>/CLAUDE.md.
+ *
+ * Returns files root-first (general → specific), at most one per depth.
+ */
+export function resolveGuidance(filePath: string, projectDir: string): GuidanceFile[] {
+	const fileDir = dirname(filePath);
+	const relativeDir = relative(projectDir, fileDir);
+
+	// Guard: file is outside project root
+	if (relativeDir.startsWith("..") || isAbsolute(relativeDir)) {
+		return [];
+	}
+
+	const parts = relativeDir ? relativeDir.split(sep) : [];
+	const results: GuidanceFile[] = [];
+
+	for (let depth = 0; depth <= parts.length; depth++) {
+		const subPath = parts.slice(0, depth).join(sep);
+
+		// Per-depth candidate ladder. First-match wins.
+		const candidates: Array<{ relative: string; kind: GuidanceKind }> = [];
+
+		// Depth 0: skip AGENTS/CLAUDE — Pi's loader handles <cwd> already.
+		if (depth > 0) {
+			candidates.push({ relative: join(subPath, "AGENTS.md"), kind: "agents" });
+			candidates.push({ relative: join(subPath, "CLAUDE.md"), kind: "claude" });
+		}
+		candidates.push({
+			relative: subPath
+				? join(".rpiv", "guidance", subPath, "architecture.md")
+				: join(".rpiv", "guidance", "architecture.md"),
+			kind: "architecture",
+		});
+
+		for (const candidate of candidates) {
+			const absolute = join(projectDir, candidate.relative);
+			if (existsSync(absolute)) {
+				results.push({
+					relativePath: candidate.relative.split(sep).join("/"),
+					absolutePath: absolute,
+					content: readFileSync(absolute, "utf-8"),
+					kind: candidate.kind,
+				});
+				break; // first-match wins at this depth
+			}
+		}
+	}
+
+	return results;
+}
+
+// ---------------------------------------------------------------------------
+// Session State
+// ---------------------------------------------------------------------------
+
+/** In-memory set of injected guidance paths per session. */
+const injectedGuidance = new Set<string>();
+
+export function clearInjectionState() {
+	injectedGuidance.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Root Guidance Injection (session_start)
+// ---------------------------------------------------------------------------
+
+/**
+ * Inject the root `.rpiv/guidance/architecture.md` at session start.
+ *
+ * Called from `session_start` so the root guidance is available before the
+ * first agent turn — without waiting for a read/edit/write tool_call.
+ * Uses the same `injectedGuidance` Set for dedup, so `handleToolCallGuidance`
+ * won't re-inject it later.
+ */
+export function injectRootGuidance(cwd: string, pi: ExtensionAPI): void {
+	const relativePath = ".rpiv/guidance/architecture.md";
+
+	if (injectedGuidance.has(relativePath)) return;
+
+	const absolutePath = join(cwd, relativePath);
+	if (!existsSync(absolutePath)) return;
+
+	let content: string;
+	try {
+		content = readFileSync(absolutePath, "utf-8");
+	} catch {
+		// Silent failure mirrors handleToolCallGuidance's posture — session_start
+		// runs before any UI is bound, so a permissions/race error here must not
+		// crash the hook. Don't mark as injected so a later tool_call can retry.
+		return;
+	}
+	injectedGuidance.add(relativePath);
+
+	const label = formatLabel({
+		relativePath,
+		absolutePath,
+		content,
+		kind: "architecture",
+	});
+	pi.sendMessage({
+		customType: "rpiv-guidance",
+		content: `## Project Guidance: ${label}\n\n${content}`,
+		display: false,
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Tool-call Handler
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle guidance injection on tool_call events for read/edit/write.
+ * Sends hidden messages via pi.sendMessage as a side effect.
+ */
+export function handleToolCallGuidance(
+	event: { toolName: string; input: Record<string, unknown> },
+	ctx: { cwd: string },
+	pi: ExtensionAPI,
+): void {
+	if (!["read", "edit", "write"].includes(event.toolName)) return;
+
+	const filePath = (event.input as any).file_path ?? (event.input as any).path;
+	if (!filePath) return;
+
+	const resolved = resolveGuidance(filePath, ctx.cwd);
+	if (resolved.length === 0) return;
+
+	const newFiles = resolved.filter((g) => !injectedGuidance.has(g.relativePath));
+	if (newFiles.length === 0) return;
+
+	// Mark before sendMessage — idempotence > reliability.
+	for (const g of newFiles) {
+		injectedGuidance.add(g.relativePath);
+	}
+
+	const contextParts = newFiles.map(
+		(g) => `## Project Guidance: ${formatLabel(g)}\n\n${g.content}`,
+	);
+
+	pi.sendMessage({
+		customType: "rpiv-guidance",
+		content: contextParts.join("\n\n---\n\n"),
+		display: false,
+	});
+}
+
+/**
+ * Format a guidance file's heading label.
+ *   extensions/rpiv-core/AGENTS.md          → "extensions/rpiv-core (AGENTS.md)"
+ *   scripts/CLAUDE.md                       → "scripts (CLAUDE.md)"
+ *   .rpiv/guidance/scripts/architecture.md  → "scripts (architecture.md)"
+ *   .rpiv/guidance/architecture.md          → "root (architecture.md)"
+ */
+function formatLabel(g: GuidanceFile): string {
+	if (g.kind === "architecture") {
+		const stripped = g.relativePath.replace(/^\.rpiv\/guidance\//, "");
+		const sub = stripped === "architecture.md"
+			? ""
+			: stripped.replace(/\/architecture\.md$/, "");
+		return `${sub || "root"} (architecture.md)`;
+	}
+	const fileName = g.kind === "agents" ? "AGENTS.md" : "CLAUDE.md";
+	const idx = g.relativePath.lastIndexOf("/");
+	const sub = idx > 0 ? g.relativePath.slice(0, idx) : "";
+	return `${sub || "root"} (${fileName})`;
+}

package/extensions/rpiv-core/index.ts

@@ -0,0 +1,275 @@
+/**
+ * rpiv-core — Orchestrator extension for the rpiv-pi package
+ *
+ * Provides:
+ * - Guidance injection (replaces inject-guidance.js hook)
+ * - Git context injection (replaces !`git ...` shell evaluation in skills)
+ * - thoughts/ directory scaffolding on session start
+ * - Bundled-agent auto-copy into <cwd>/.pi/agents/
+ * - Aggregated session_start warning for missing sibling plugins
+ * - /rpiv-update-agents, /rpiv-setup slash commands
+ *
+ * Tool-owning plugins are siblings: @juicesharp/rpiv-ask-user-question,
+ * @juicesharp/rpiv-todo, @juicesharp/rpiv-advisor, @juicesharp/rpiv-web-tools.
+ * Install via /rpiv-setup.
+ */
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { isToolCallEventType, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { clearInjectionState, handleToolCallGuidance, injectRootGuidance } from "./guidance.js";
+import {
+	clearGitContextCache,
+	isGitMutatingCommand,
+	resetInjectedMarker,
+	takeGitContextIfChanged,
+} from "./git-context.js";
+import { syncBundledAgents } from "./agents.js";
+import {
+	hasPiSubagentsInstalled,
+	hasRpivAskUserQuestionInstalled,
+	hasRpivTodoInstalled,
+	hasRpivAdvisorInstalled,
+	hasRpivWebToolsInstalled,
+} from "./package-checks.js";
+
+export default function (pi: ExtensionAPI) {
+	// ── Session Start ──────────────────────────────────────────────────────
+	pi.on("session_start", async (_event, ctx) => {
+		clearInjectionState();
+		injectRootGuidance(ctx.cwd, pi);
+
+		// Scaffold thoughts/ directory structure (artifact chain)
+		const dirs = [
+			"thoughts/shared/research",
+			"thoughts/shared/questions",
+			"thoughts/shared/designs",
+			"thoughts/shared/plans",
+			"thoughts/shared/handoffs",
+		];
+		for (const dir of dirs) {
+			mkdirSync(join(ctx.cwd, dir), { recursive: true });
+		}
+
+		// Inject git context once into the transcript
+		const gitMsg = await takeGitContextIfChanged(pi);
+		if (gitMsg) {
+			pi.sendMessage({ customType: "rpiv-git-context", content: gitMsg, display: false });
+		}
+
+		// Sync bundled agents into <cwd>/.pi/agents/
+		// Detect-only mode: adds new files, detects drift, does NOT overwrite or remove.
+		const agentResult = syncBundledAgents(ctx.cwd, false);
+		if (ctx.hasUI) {
+			if (agentResult.added.length > 0) {
+				ctx.ui.notify(
+					`Copied ${agentResult.added.length} rpiv-pi agent(s) to .pi/agents/`,
+					"info",
+				);
+			}
+			const driftCount = agentResult.pendingUpdate.length + agentResult.pendingRemove.length;
+			if (driftCount > 0) {
+				const parts: string[] = [];
+				if (agentResult.pendingUpdate.length > 0) {
+					parts.push(`${agentResult.pendingUpdate.length} outdated`);
+				}
+				if (agentResult.pendingRemove.length > 0) {
+					parts.push(`${agentResult.pendingRemove.length} removed from bundle`);
+				}
+				ctx.ui.notify(
+					`${parts.join(", ")} agent(s). Run /rpiv-update-agents to sync.`,
+					"info",
+				);
+			}
+		}
+
+		// Aggregated warning for any missing sibling plugins
+		if (ctx.hasUI) {
+			const missing: string[] = [];
+			if (!hasPiSubagentsInstalled()) missing.push("@tintinweb/pi-subagents");
+			if (!hasRpivAskUserQuestionInstalled()) missing.push("@juicesharp/rpiv-ask-user-question");
+			if (!hasRpivTodoInstalled()) missing.push("@juicesharp/rpiv-todo");
+			if (!hasRpivAdvisorInstalled()) missing.push("@juicesharp/rpiv-advisor");
+			if (!hasRpivWebToolsInstalled()) missing.push("@juicesharp/rpiv-web-tools");
+			if (missing.length > 0) {
+				ctx.ui.notify(
+					`rpiv-pi requires ${missing.length} sibling extension(s): ${missing.join(", ")}. Run /rpiv-setup to install them.`,
+					"warning",
+				);
+			}
+		}
+	});
+
+	// ── Session Compact — drop injection state, re-inject root guidance ────
+	pi.on("session_compact", async (_event, ctx) => {
+		clearInjectionState();
+		clearGitContextCache();
+		resetInjectedMarker();
+		injectRootGuidance(ctx.cwd, pi);
+		const gitMsg = await takeGitContextIfChanged(pi);
+		if (gitMsg) {
+			pi.sendMessage({ customType: "rpiv-git-context", content: gitMsg, display: false });
+		}
+	});
+
+	// ── Session Shutdown ───────────────────────────────────────────────────
+	pi.on("session_shutdown", async (_event, _ctx) => {
+		clearInjectionState();
+		clearGitContextCache();
+		resetInjectedMarker();
+	});
+
+	// ── Guidance Injection + Git Cache Invalidation ────────────────────────
+	pi.on("tool_call", async (event, ctx) => {
+		handleToolCallGuidance(event, ctx, pi);
+		if (isToolCallEventType("bash", event) && isGitMutatingCommand(event.input.command)) {
+			clearGitContextCache();
+		}
+	});
+
+	// ── Git Context Injection (only when cache diverges from transcript) ───
+	pi.on("before_agent_start", async (_event, _ctx) => {
+		const content = await takeGitContextIfChanged(pi);
+		if (!content) return;
+		return {
+			message: { customType: "rpiv-git-context", content, display: false },
+		};
+	});
+
+	// ── /rpiv-update-agents Command ────────────────────────────────────────
+	pi.registerCommand("rpiv-update-agents", {
+		description: "Sync rpiv-pi bundled agents into .pi/agents/: add new, update changed, remove stale",
+		handler: async (_args, ctx) => {
+			const result = syncBundledAgents(ctx.cwd, true);
+			if (!ctx.hasUI) return;
+
+			const totalSynced = result.added.length + result.updated.length + result.removed.length;
+			if (totalSynced === 0 && result.errors.length === 0) {
+				ctx.ui.notify("All agents already up-to-date.", "info");
+				return;
+			}
+
+			const parts: string[] = [];
+			if (result.added.length > 0) parts.push(`${result.added.length} added`);
+			if (result.updated.length > 0) parts.push(`${result.updated.length} updated`);
+			if (result.removed.length > 0) parts.push(`${result.removed.length} removed`);
+
+			const summary = parts.length > 0
+				? `Synced agents: ${parts.join(", ")}.`
+				: "No changes needed.";
+
+			if (result.errors.length > 0) {
+				ctx.ui.notify(
+					`${summary} ${result.errors.length} error(s): ${result.errors.map((e) => e.message).join("; ")}`,
+					"warning",
+				);
+			} else {
+				ctx.ui.notify(summary, "info");
+			}
+		},
+	});
+
+	// ── /rpiv-setup Command ────────────────────────────────────────────────
+	pi.registerCommand("rpiv-setup", {
+		description: "Install rpiv-pi's sibling extension plugins",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("/rpiv-setup requires interactive mode", "error");
+				return;
+			}
+
+			const missing: Array<{ pkg: string; reason: string }> = [];
+			if (!hasPiSubagentsInstalled()) {
+				missing.push({
+					pkg: "npm:@tintinweb/pi-subagents",
+					reason: "required — provides Agent / get_subagent_result / steer_subagent tools",
+				});
+			}
+			if (!hasRpivAskUserQuestionInstalled()) {
+				missing.push({
+					pkg: "npm:@juicesharp/rpiv-ask-user-question",
+					reason: "required — provides the ask_user_question tool",
+				});
+			}
+			if (!hasRpivTodoInstalled()) {
+				missing.push({
+					pkg: "npm:@juicesharp/rpiv-todo",
+					reason: "required — provides the todo tool + /todos command + overlay widget",
+				});
+			}
+			if (!hasRpivAdvisorInstalled()) {
+				missing.push({
+					pkg: "npm:@juicesharp/rpiv-advisor",
+					reason: "required — provides the advisor tool + /advisor command",
+				});
+			}
+			if (!hasRpivWebToolsInstalled()) {
+				missing.push({
+					pkg: "npm:@juicesharp/rpiv-web-tools",
+					reason: "required — provides web_search + web_fetch tools + /web-search-config",
+				});
+			}
+
+			if (missing.length === 0) {
+				ctx.ui.notify(
+					"All rpiv-pi sibling dependencies already installed.",
+					"info",
+				);
+				return;
+			}
+
+			const lines = [
+				"rpiv-pi will install the following Pi packages via `pi install`:",
+				"",
+				...missing.map((m) => `  • ${m.pkg}  (${m.reason})`),
+				"",
+				"Each install is a separate `pi install <pkg>` invocation. Your",
+				"~/.pi/agent/settings.json will be updated. Proceed?",
+			];
+
+			const confirmed = await ctx.ui.confirm("Install rpiv-pi dependencies?", lines.join("\n"));
+			if (!confirmed) {
+				ctx.ui.notify("/rpiv-setup cancelled", "info");
+				return;
+			}
+
+			const succeeded: string[] = [];
+			const failed: Array<{ pkg: string; error: string }> = [];
+			for (const { pkg } of missing) {
+				ctx.ui.notify(`Installing ${pkg}…`, "info");
+				try {
+					const result = await pi.exec("pi", ["install", pkg], { timeout: 120_000 });
+					if (result.code === 0) {
+						succeeded.push(pkg);
+					} else {
+						failed.push({
+							pkg,
+							error: (result.stderr || result.stdout || `exit ${result.code}`).trim().slice(0, 300),
+						});
+					}
+				} catch (err) {
+					failed.push({
+						pkg,
+						error: err instanceof Error ? err.message : String(err),
+					});
+				}
+			}
+
+			const report: string[] = [];
+			if (succeeded.length > 0) {
+				report.push(`✓ Installed: ${succeeded.join(", ")}`);
+			}
+			if (failed.length > 0) {
+				report.push(`✗ Failed:`);
+				for (const { pkg, error } of failed) {
+					report.push(`  ${pkg}: ${error}`);
+				}
+			}
+			if (succeeded.length > 0) {
+				report.push("");
+				report.push("Restart your Pi session to load the newly-installed extensions.");
+			}
+			ctx.ui.notify(report.join("\n"), failed.length > 0 ? "warning" : "info");
+		},
+	});
+}

package/extensions/rpiv-core/package-checks.ts

@@ -0,0 +1,51 @@
+/**
+ * Package presence checks — detects whether sibling pi packages are installed.
+ *
+ * Pure utility. No ExtensionAPI interactions.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const PI_AGENT_SETTINGS = join(homedir(), ".pi", "agent", "settings.json");
+
+// ---------------------------------------------------------------------------
+// Package Detection
+// ---------------------------------------------------------------------------
+
+export function readInstalledPackages(): string[] {
+	if (!existsSync(PI_AGENT_SETTINGS)) return [];
+	try {
+		const raw = readFileSync(PI_AGENT_SETTINGS, "utf-8");
+		const settings = JSON.parse(raw) as { packages?: unknown };
+		if (!Array.isArray(settings.packages)) return [];
+		return settings.packages.filter((e): e is string => typeof e === "string");
+	} catch {
+		return [];
+	}
+}
+
+export function hasPiSubagentsInstalled(): boolean {
+	return readInstalledPackages().some((entry) => /@tintinweb\/pi-subagents/i.test(entry));
+}
+
+export function hasRpivAskUserQuestionInstalled(): boolean {
+	return readInstalledPackages().some((entry) => /rpiv-ask-user-question/i.test(entry));
+}
+
+export function hasRpivTodoInstalled(): boolean {
+	return readInstalledPackages().some((entry) => /rpiv-todo/i.test(entry));
+}
+
+export function hasRpivAdvisorInstalled(): boolean {
+	return readInstalledPackages().some((entry) => /rpiv-advisor/i.test(entry));
+}
+
+export function hasRpivWebToolsInstalled(): boolean {
+	return readInstalledPackages().some((entry) => /rpiv-web-tools/i.test(entry));
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@juicesharp/rpiv-pi",
+  "version": "0.4.0",
+  "description": "Skill-based development workflow for Pi — research, design, plan, implement, review",
+  "keywords": ["pi-package", "pi-extension", "rpiv", "skills", "workflow"],
+  "license": "MIT",
+  "author": "juicesharp",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juicesharp/rpiv-pi.git"
+  },
+  "homepage": "https://github.com/juicesharp/rpiv-pi#readme",
+  "bugs": {
+    "url": "https://github.com/juicesharp/rpiv-pi/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["extensions/", "skills/", "agents/", "scripts/", "README.md"],
+  "pi": {
+    "extensions": ["./extensions"],
+    "skills": ["./skills"]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*",
+    "@tintinweb/pi-subagents": "*",
+    "@juicesharp/rpiv-ask-user-question": "*",
+    "@juicesharp/rpiv-todo": "*",
+    "@juicesharp/rpiv-advisor": "*",
+    "@juicesharp/rpiv-web-tools": "*"
+  }
+}