@juicesharp/rpiv-pi 0.4.0

package/agents/web-search-researcher.md

@@ -0,0 +1,107 @@
+---
+name: web-search-researcher
+description: Do you find yourself desiring information that you don't quite feel well-trained (confident) on? Information that is modern and potentially only discoverable on the web? Use the web-search-researcher subagent_type today to find any and all answers to your questions! It will research deeply to figure out and attempt to answer your questions! If you aren't immediately satisfied you can get your money back! (Not really - but you can re-run web-search-researcher with an altered prompt in the event you're not satisfied the first time)
+tools: web_search, web_fetch, read, grep, find, ls
+---
+
+You are an expert web research specialist focused on finding accurate, relevant information from web sources. Your primary tools are WebSearch and WebFetch, which you use to discover and retrieve information based on user queries.
+
+## Core Responsibilities
+
+When you receive a research query, you will:
+
+1. **Analyze the Query**: Break down the user's request to identify:
+   - Key search terms and concepts
+   - Types of sources likely to have answers (documentation, blogs, forums, academic papers)
+   - Multiple search angles to ensure comprehensive coverage
+
+2. **Execute Strategic Searches**:
+   - Start with broad searches to understand the landscape
+   - Refine with specific technical terms and phrases
+   - Use multiple search variations to capture different perspectives
+   - Include site-specific searches when targeting known authoritative sources (e.g., "site:docs.stripe.com webhook signature")
+
+3. **Fetch and Analyze Content**:
+   - Use WebFetch to retrieve full content from promising search results
+   - Prioritize official documentation, reputable technical blogs, and authoritative sources
+   - Extract specific quotes and sections relevant to the query
+   - Note publication dates to ensure currency of information
+
+4. **Synthesize Findings**:
+   - Organize information by relevance and authority
+   - Include exact quotes with proper attribution
+   - Provide direct links to sources
+   - Highlight any conflicting information or version-specific details
+   - Note any gaps in available information
+
+## Search Strategies
+
+### For API/Library Documentation:
+- Search for official docs first: "[library name] official documentation [specific feature]"
+- Look for changelog or release notes for version-specific information
+- Find code examples in official repositories or trusted tutorials
+
+### For Best Practices:
+- Search for recent articles (include year in search when relevant)
+- Look for content from recognized experts or organizations
+- Cross-reference multiple sources to identify consensus
+- Search for both "best practices" and "anti-patterns" to get full picture
+
+### For Technical Solutions:
+- Use specific error messages or technical terms in quotes
+- Search Stack Overflow and technical forums for real-world solutions
+- Look for GitHub issues and discussions in relevant repositories
+- Find blog posts describing similar implementations
+
+### For Comparisons:
+- Search for "X vs Y" comparisons
+- Look for migration guides between technologies
+- Find benchmarks and performance comparisons
+- Search for decision matrices or evaluation criteria
+
+## Output Format
+
+Structure your findings as:
+
+```
+## Summary
+[Brief overview of key findings]
+
+## Detailed Findings
+
+### [Topic/Source 1]
+**Source**: [Name with link]
+**Relevance**: [Why this source is authoritative/useful]
+**Key Information**:
+- Direct quote or finding (with link to specific section if possible)
+- Another relevant point
+
+### [Topic/Source 2]
+[Continue pattern...]
+
+## Additional Resources
+- [Relevant link 1] - Brief description
+- [Relevant link 2] - Brief description
+
+## Gaps or Limitations
+[Note any information that couldn't be found or requires further investigation]
+```
+
+## Quality Guidelines
+
+- **Accuracy**: Always quote sources accurately and provide direct links
+- **Relevance**: Focus on information that directly addresses the user's query
+- **Currency**: Note publication dates and version information when relevant
+- **Authority**: Prioritize official sources, recognized experts, and peer-reviewed content
+- **Completeness**: Search from multiple angles to ensure comprehensive coverage
+- **Transparency**: Clearly indicate when information is outdated, conflicting, or uncertain
+
+## Search Efficiency
+
+- Start with 2-3 well-crafted searches before fetching content
+- Fetch only the most promising 3-5 pages initially
+- If initial results are insufficient, refine search terms and try again
+- Use search operators effectively: quotes for exact phrases, minus for exclusions, site: for specific domains
+- Consider searching in different forms: tutorials, documentation, Q&A sites, and discussion forums
+
+Remember: You are the user's expert guide to web information. Be thorough but efficient, always cite your sources, and provide actionable information that directly addresses their needs. Think deeply as you work.

package/extensions/rpiv-core/agents.ts

@@ -0,0 +1,312 @@
+/**
+ * Agent auto-copy — copies bundled agents into <cwd>/.pi/agents/.
+ *
+ * Pure utility. No ExtensionAPI interactions.
+ */
+
+import {
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	copyFileSync,
+	readFileSync,
+	writeFileSync,
+	unlinkSync,
+} from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Package-root resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolves the rpiv-pi package root from this module's file URL.
+ * Walks up from `extensions/rpiv-core/agents.ts` to the repo root.
+ */
+export const PACKAGE_ROOT = (() => {
+	const thisFile = fileURLToPath(import.meta.url);
+	// extensions/rpiv-core/agents.ts -> rpiv-pi/
+	return dirname(dirname(dirname(thisFile)));
+})();
+
+export const BUNDLED_AGENTS_DIR = join(PACKAGE_ROOT, "agents");
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SyncError {
+	file?: string;
+	op: "read-src" | "read-dest" | "copy" | "remove" | "manifest-read" | "manifest-write";
+	message: string;
+}
+
+export interface SyncResult {
+	/** New files copied (present in source, absent from destination). */
+	added: string[];
+	/** Existing managed files overwritten with updated source content. */
+	updated: string[];
+	/** Managed files whose destination content matches source exactly. */
+	unchanged: string[];
+	/** Stale managed files removed (present in manifest but absent from source). */
+	removed: string[];
+	/** Managed files with different destination content (detected but not applied). */
+	pendingUpdate: string[];
+	/** Managed files no longer in source (detected but not removed). */
+	pendingRemove: string[];
+	/** Per-file errors collected during sync. */
+	errors: SyncError[];
+
+	// -- Legacy aliases (backward compat for existing callers) --
+	/** Alias: added + updated (files written by this run). */
+	copied: string[];
+	/** Alias: unchanged + pendingUpdate + files that errored during read and were not written. */
+	skipped: string[];
+}
+
+/** Create an empty SyncResult with all arrays initialized. */
+function emptySyncResult(): SyncResult {
+	return {
+		added: [],
+		updated: [],
+		unchanged: [],
+		removed: [],
+		pendingUpdate: [],
+		pendingRemove: [],
+		errors: [],
+		copied: [],
+		skipped: [],
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Manifest
+// ---------------------------------------------------------------------------
+
+const MANIFEST_FILE = ".rpiv-managed.json";
+
+/**
+ * Read the managed-file manifest from the target directory.
+ * Returns an empty array on missing/invalid/unreadable manifest.
+ * Fail-soft: never throws.
+ */
+function readManifest(targetDir: string): string[] {
+	const manifestPath = join(targetDir, MANIFEST_FILE);
+	if (!existsSync(manifestPath)) return [];
+	try {
+		const raw = readFileSync(manifestPath, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter((e): e is string => typeof e === "string");
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Write the managed-file manifest to the target directory.
+ * Fail-soft: swallows write errors (permissions, disk full, etc.).
+ */
+function writeManifest(targetDir: string, filenames: string[]): void {
+	const manifestPath = join(targetDir, MANIFEST_FILE);
+	try {
+		writeFileSync(manifestPath, JSON.stringify(filenames, null, 2) + "\n", "utf-8");
+	} catch {
+		// non-fatal — sync results will still be correct for this run;
+		// next run will re-bootstrap if manifest is missing
+	}
+}
+
+/**
+ * Bootstrap the managed-file manifest on first run after upgrade.
+ *
+ * When no manifest exists, claims all existing destination files whose
+ * names match the current bundled source list as rpiv-managed.
+ * Writes the manifest and returns the managed set.
+ *
+ * If a manifest already exists, returns it as-is.
+ */
+function bootstrapManifest(targetDir: string, sourceNames: Set<string>): string[] {
+	const existing = readManifest(targetDir);
+	if (existing.length > 0) return existing;
+
+	const managed: string[] = [];
+	try {
+		const destEntries = readdirSync(targetDir).filter((f) => f.endsWith(".md"));
+		for (const name of destEntries) {
+			if (sourceNames.has(name)) {
+				managed.push(name);
+			}
+		}
+	} catch {
+		// dest dir may not exist yet — that's fine, empty manifest
+	}
+
+	writeManifest(targetDir, managed);
+	return managed;
+}
+
+// ---------------------------------------------------------------------------
+// Agent Sync Engine
+// ---------------------------------------------------------------------------
+
+/**
+ * Synchronize bundled agents from <PACKAGE_ROOT>/agents/ into <cwd>/.pi/agents/.
+ *
+ * When `apply` is false (session_start): adds new files only.
+ * Detects pending updates and removals without applying them.
+ * When `apply` is true (/rpiv-update-agents): adds new, overwrites changed
+ * managed files, removes stale managed files.
+ *
+ * Never throws — errors are collected in `result.errors`.
+ */
+export function syncBundledAgents(cwd: string, apply: boolean): SyncResult {
+	const result = emptySyncResult();
+
+	if (!existsSync(BUNDLED_AGENTS_DIR)) {
+		return result;
+	}
+
+	const targetDir = join(cwd, ".pi", "agents");
+	try {
+		mkdirSync(targetDir, { recursive: true });
+	} catch {
+		result.errors.push({ op: "manifest-write", message: "Failed to create target directory" });
+		return result;
+	}
+
+	// 1. Enumerate source files
+	let sourceEntries: string[];
+	try {
+		sourceEntries = readdirSync(BUNDLED_AGENTS_DIR).filter((f) => f.endsWith(".md"));
+	} catch {
+		result.errors.push({ op: "read-src", message: "Failed to read bundled agents directory" });
+		return result;
+	}
+
+	const sourceNames = new Set(sourceEntries);
+
+	// 2. Bootstrap manifest and get managed set
+	const managedNames = new Set(bootstrapManifest(targetDir, sourceNames));
+
+	// 3. Process each source file
+	for (const entry of sourceEntries) {
+		const src = join(BUNDLED_AGENTS_DIR, entry);
+		const dest = join(targetDir, entry);
+
+		if (!existsSync(dest)) {
+			try {
+				copyFileSync(src, dest);
+				result.added.push(entry);
+			} catch (e) {
+				result.errors.push({
+					file: entry,
+					op: "copy",
+					message: e instanceof Error ? e.message : String(e),
+				});
+			}
+			continue;
+		}
+
+		let srcContent: Buffer;
+		let destContent: Buffer;
+		try {
+			srcContent = readFileSync(src);
+		} catch (e) {
+			result.errors.push({
+				file: entry,
+				op: "read-src",
+				message: e instanceof Error ? e.message : String(e),
+			});
+			result.skipped.push(entry);
+			continue;
+		}
+		try {
+			destContent = readFileSync(dest);
+		} catch (e) {
+			result.errors.push({
+				file: entry,
+				op: "read-dest",
+				message: e instanceof Error ? e.message : String(e),
+			});
+			result.skipped.push(entry);
+			continue;
+		}
+
+		if (Buffer.compare(srcContent, destContent) === 0) {
+			result.unchanged.push(entry);
+			result.skipped.push(entry);
+		} else if (apply) {
+			try {
+				copyFileSync(src, dest);
+				result.updated.push(entry);
+				result.copied.push(entry);
+			} catch (e) {
+				result.errors.push({
+					file: entry,
+					op: "copy",
+					message: e instanceof Error ? e.message : String(e),
+				});
+			}
+		} else {
+			result.pendingUpdate.push(entry);
+			result.skipped.push(entry);
+		}
+	}
+
+	// 4. Process stale managed files (in manifest but not in source)
+	for (const name of managedNames) {
+		if (sourceNames.has(name)) continue;
+
+		const destPath = join(targetDir, name);
+		if (!existsSync(destPath)) continue;
+
+		if (apply) {
+			try {
+				unlinkSync(destPath);
+				result.removed.push(name);
+			} catch (e) {
+				result.errors.push({
+					file: name,
+					op: "remove",
+					message: e instanceof Error ? e.message : String(e),
+				});
+			}
+		} else {
+			result.pendingRemove.push(name);
+		}
+	}
+
+	// 5. Update manifest to reflect what's currently managed on disk.
+	// apply=true: stale files were removed, so manifest = sourceEntries.
+	// apply=false: stale files still exist on disk and must stay tracked
+	// so the next apply can remove them.
+	const manifestEntries = apply
+		? sourceEntries
+		: [...sourceEntries, ...result.pendingRemove];
+	writeManifest(targetDir, manifestEntries);
+
+	// 6. Populate legacy `copied` alias (added + updated)
+	for (const name of result.added) {
+		result.copied.push(name);
+	}
+	// updated files were pushed to `copied` inline in the loop above
+
+	return result;
+}
+
+// ---------------------------------------------------------------------------
+// Backward-compatible wrapper
+// ---------------------------------------------------------------------------
+
+/**
+ * Legacy entry point — delegates to syncBundledAgents.
+ * Kept for backward compatibility; prefer syncBundledAgents for new callers.
+ */
+export function copyBundledAgents(cwd: string, overwrite: boolean): {
+	copied: string[];
+	skipped: string[];
+} {
+	return syncBundledAgents(cwd, overwrite);
+}

package/extensions/rpiv-core/git-context.ts

@@ -0,0 +1,81 @@
+/**
+ * Cached branch + short commit. Injected into the transcript once at
+ * session_start, re-injected on session_compact (transcript cleared) and
+ * only when the cached value changes (e.g. after a mutating git command).
+ * Two parallel `git rev-parse` calls — one call can't combine
+ * `--abbrev-ref` and `--short` cleanly because the `--abbrev-ref` mode
+ * persists to subsequent revs. git itself resolves worktree gitdir
+ * redirection, so either form is worktree-safe.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+type GitContext = { branch: string; commit: string; user: string };
+
+// Signature (branch+commit) of the last message pushed into the transcript.
+// null = transcript has nothing current and needs re-injection.
+let lastInjectedSig: string | null = null;
+
+// undefined = not loaded yet, null = not a git repo / failed, object = valid
+let cache: GitContext | null | undefined = undefined;
+
+export async function getGitContext(pi: ExtensionAPI): Promise<GitContext | null> {
+	if (cache !== undefined) return cache;
+	cache = await loadGitContext(pi);
+	return cache;
+}
+
+export function clearGitContextCache(): void {
+	cache = undefined;
+}
+
+// Detached HEAD emits literal "HEAD" for --abbrev-ref; remap so frontmatter is meaningful.
+async function loadGitContext(pi: ExtensionAPI): Promise<GitContext | null> {
+	try {
+		const [branchRes, commitRes] = await Promise.all([
+			pi.exec("git", ["rev-parse", "--abbrev-ref", "HEAD"], { timeout: 5000 }),
+			pi.exec("git", ["rev-parse", "--short", "HEAD"], { timeout: 5000 }),
+		]);
+		const rawBranch = branchRes.stdout.trim();
+		const commit = commitRes.stdout.trim();
+		if (!rawBranch && !commit) return null;
+		const branch = rawBranch === "HEAD" ? "detached" : rawBranch;
+		let user = "";
+		try {
+			const r2 = await pi.exec("git", ["config", "user.name"], { timeout: 5000 });
+			user = r2.stdout.trim();
+		} catch {
+			// fall through to env fallback
+		}
+		if (!user) user = process.env.USER || "unknown";
+		return {
+			branch: branch || "no-branch",
+			commit: commit || "no-commit",
+			user,
+		};
+	} catch {
+		return null;
+	}
+}
+
+export function resetInjectedMarker(): void {
+	lastInjectedSig = null;
+}
+
+// Returns the message content to inject, or null if the transcript is
+// already up-to-date or we're not in a git repo. Updates the marker
+// whenever it returns non-null.
+export async function takeGitContextIfChanged(pi: ExtensionAPI): Promise<string | null> {
+	const g = await getGitContext(pi);
+	if (!g) return null;
+	const sig = `${g.branch}\n${g.commit}\n${g.user}`;
+	if (sig === lastInjectedSig) return null;
+	lastInjectedSig = sig;
+	return `## Git Context\n- Branch: ${g.branch}\n- Commit: ${g.commit}\n- User: ${g.user}`;
+}
+
+export function isGitMutatingCommand(cmd: string): boolean {
+	return /\bgit\s+(checkout|switch|commit|merge|rebase|pull|reset|revert|cherry-pick|worktree|am|stash)\b/.test(
+		cmd,
+	);
+}