pi-crew 0.9.50 → 0.9.52

package/src/config/markers.ts

@@ -1,330 +0,0 @@
-import * as fs from "node:fs";
-
-/**
- * Marker delimiters used to bracket pi-crew guidance sections inside
- * markdown files (e.g. AGENTS.md).  Using HTML comments keeps them
- * invisible when rendered.
- */
-export const MARKER_START = "<!-- PI-CREW:GUIDANCE:START -->";
-export const MARKER_END = "<!-- PI-CREW:GUIDANCE:END -->";
-
-/** A single guidance section to inject between markers. */
-export interface GuidanceBlock {
-	/**
-	 * Unique identifier for this guidance section (e.g. "team-tool-usage").
-	 * Must match `/^[a-zA-Z0-9_-]+$/`.
-	 */
-	id: string;
-	/**
-	 * Markdown content to inject.
-	 *
-	 * **WARNING:** Content must be from trusted sources only. Guidance blocks
-	 * are injected into markdown files that AI agents read. Untrusted content
-	 * could contain prompt-injection payloads that manipulate agent behavior.
-	 */
-	content: string;
-	/** Higher priority = appears first. Default 0. */
-	priority?: number;
-}
-
-/** Regex for valid guidance block IDs. */
-const VALID_BLOCK_ID = /^[a-zA-Z0-9_-]+$/;
-
-/**
- * Sanitize guidance content to reduce prompt-injection risk.
- *
- * Strips HTML comment patterns and instruction-like directives that could
- * be used for prompt injection. This is a best-effort defense — content
- * should still come from trusted sources.
- */
-/**
- * Best-effort content sanitizer for guidance blocks.
- *
- * WARNING: This is NOT a security boundary. Content should come from trusted
- * sources only. This sanitizer handles common injection patterns but cannot
- * prevent all bypasses (e.g., base64, ROT13, semantic tricks).
- */
-export function sanitizeGuidanceContent(content: string): string {
-	let sanitized = content;
-	// Strip zero-width and invisible Unicode characters (potential bypass vectors)
-	sanitized = sanitized.replace(/[\u200B-\u200F\u2028-\u202F\u2060-\u206F\uFEFF]/g, "");
-	// Strip HTML comments (potential instruction hiding)
-	sanitized = sanitized.replace(/<!--[\s\S]*?-->/g, "");
-	// Strip lines that look like system directives (e.g. "SYSTEM:", "INSTRUCTION:", "IGNORE PREVIOUS")
-	sanitized = sanitized.replace(/^\s*(?:SYSTEM|INSTRUCTION|IGNORE\s+PREVIOUS|OVERRIDE)\s*:.*$/gim, "");
-	// Collapse multiple blank lines left by removals
-	sanitized = sanitized.replace(/\n{3,}/g, "\n\n");
-	return sanitized.trim();
-}
-
-/** Result of an injection or removal operation. */
-export interface InjectionResult {
-	path: string;
-	modified: boolean;
-	/** Block IDs that were added or updated. */
-	added: string[];
-	/** Block IDs that were removed (content was empty). */
-	removed: string[];
-}
-
-/**
- * Render a sorted list of guidance blocks into the markdown content that
- * sits between the START and END markers.
- *
- * Each block is wrapped in its own id-tagged comment so we can later
- * parse individual blocks back out.
- */
-function renderBlocks(blocks: GuidanceBlock[]): string {
-	const sorted = [...blocks].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
-	return sorted.map((block) => `<!-- PI-CREW:BLOCK:${block.id} -->\n${block.content}\n<!-- PI-CREW:/BLOCK:${block.id} -->`).join("\n\n");
-}
-
-/**
- * Parse the inner marker content and return the set of block IDs present.
- */
-export function extractGuidanceIds(content: string): string[] {
-	const ids: string[] = [];
-	const regex = /<!-- PI-CREW:BLOCK:([^\s>]+) -->/g;
-	let match: RegExpExecArray | null = regex.exec(content);
-	while (match !== null) {
-		const captured = match[1];
-		if (captured !== undefined) ids.push(captured);
-		match = regex.exec(content);
-	}
-	return ids;
-}
-
-/**
- * Parse existing blocks from marker content into a map of id → GuidanceBlock.
- */
-function parseExistingBlocks(inner: string): Map<string, GuidanceBlock> {
-	const map = new Map<string, GuidanceBlock>();
-	const regex = /<!-- PI-CREW:BLOCK:([^\s>]+) -->\n([\s\S]*?)<!-- PI-CREW:\/BLOCK:\1 -->/g;
-	let match: RegExpExecArray | null = regex.exec(inner);
-	while (match !== null) {
-		const id = match[1];
-		const blockContent = match[2];
-		if (id !== undefined && blockContent !== undefined) {
-			map.set(id, { id, content: blockContent.replace(/\n$/, "") });
-		}
-		match = regex.exec(inner);
-	}
-	return map;
-}
-
-/**
- * Build the full marker section string.
- */
-function buildMarkerSection(blocks: GuidanceBlock[]): string {
-	const body = renderBlocks(blocks);
-	return `\n${MARKER_START}\n${body}\n${MARKER_END}\n`;
-}
-
-/**
- * Inject (or update) pi-crew guidance blocks inside `filePath`.
- *
- * - If the file does not exist, it is created with only the marker section.
- * - If the file exists but has no markers, the marker section is appended.
- * - If the file already has markers, existing blocks are merged with the
- *   supplied `blocks`.  Blocks with matching IDs are overwritten; blocks
- *   not present in `blocks` are preserved unless their content is empty
- *   (handled via the `removeGuidance` helper instead).
- * - Blocks whose `content` is an empty string are treated as "remove" —
- *   they are excluded from the merged output.
- * - Content outside the markers is preserved exactly.
- */
-export function injectGuidance(filePath: string, blocks: GuidanceBlock[]): InjectionResult {
-	// Validate block IDs before processing (M1)
-	for (const block of blocks) {
-		if (!VALID_BLOCK_ID.test(block.id)) {
-			throw new Error(`Invalid guidance block ID '${block.id}': must match /^[a-zA-Z0-9_-]+$/.`);
-		}
-	}
-
-	const original = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf-8") : "";
-
-	const startIdx = original.indexOf(MARKER_START);
-	const endIdx = original.indexOf(MARKER_END);
-
-	let existingBlocks = new Map<string, GuidanceBlock>();
-	let before = original;
-	let after = "";
-
-	if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-		// Extract content around markers
-		before = original.slice(0, startIdx);
-		after = original.slice(endIdx + MARKER_END.length);
-
-		const inner = original.slice(startIdx + MARKER_START.length, endIdx);
-		existingBlocks = parseExistingBlocks(inner);
-	} else {
-		// No markers: whole file is "before"
-		before = original;
-		after = "";
-	}
-
-	// Merge: apply new blocks on top of existing
-	const added: string[] = [];
-	const removed: string[] = [];
-
-	for (const block of blocks) {
-		if (block.content === "") {
-			// Empty content signals removal
-			if (existingBlocks.has(block.id)) {
-				existingBlocks.delete(block.id);
-				removed.push(block.id);
-			}
-		} else {
-			existingBlocks.set(block.id, {
-				...block,
-				content: sanitizeGuidanceContent(block.content),
-			});
-			added.push(block.id);
-		}
-	}
-
-	const merged = [...existingBlocks.values()];
-
-	// Nothing to write if there are no blocks and no markers existed
-	const hadMarkers = startIdx !== -1;
-	if (merged.length === 0 && !hadMarkers) {
-		return { path: filePath, modified: false, added: [], removed: [] };
-	}
-
-	// If all blocks removed and markers existed, remove the whole section
-	if (merged.length === 0 && hadMarkers) {
-		const newContent = trimTrailingNewlines(before) + after;
-		if (newContent === original) {
-			return { path: filePath, modified: false, added: [], removed };
-		}
-		fs.writeFileSync(filePath, newContent, "utf-8");
-		return { path: filePath, modified: true, added: [], removed };
-	}
-
-	const section = buildMarkerSection(merged);
-	const newContent = trimTrailingNewlines(before) + section + trimLeadingNewlines(after);
-
-	if (newContent === original) {
-		return { path: filePath, modified: false, added: [], removed };
-	}
-
-	// Ensure parent directory exists
-	const dir = filePath.substring(0, Math.max(filePath.lastIndexOf("/"), filePath.lastIndexOf("\\")));
-	if (dir && !fs.existsSync(dir)) {
-		fs.mkdirSync(dir, { recursive: true });
-	}
-
-	fs.writeFileSync(filePath, newContent, "utf-8");
-	return { path: filePath, modified: true, added, removed };
-}
-
-/**
- * Remove specific guidance blocks (by ID) or the entire marker section
- * from `filePath`.
- *
- * - If `ids` is `undefined`, the entire marker section is removed.
- * - If `ids` is an array, only the listed block IDs are removed.
- * - Content outside markers is preserved exactly.
- */
-export function removeGuidance(filePath: string, ids?: string[]): InjectionResult {
-	if (!fs.existsSync(filePath)) {
-		return { path: filePath, modified: false, added: [], removed: [] };
-	}
-
-	const original = fs.readFileSync(filePath, "utf-8");
-	const startIdx = original.indexOf(MARKER_START);
-	const endIdx = original.indexOf(MARKER_END);
-
-	if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
-		return { path: filePath, modified: false, added: [], removed: [] };
-	}
-
-	const before = original.slice(0, startIdx);
-	const after = original.slice(endIdx + MARKER_END.length);
-	const inner = original.slice(startIdx + MARKER_START.length, endIdx);
-
-	if (ids === undefined) {
-		// Remove entire marker section
-		const allIds = extractGuidanceIds(inner);
-		const newContent = trimTrailingNewlines(before) + after;
-		if (newContent === original) {
-			return { path: filePath, modified: false, added: [], removed: [] };
-		}
-		fs.writeFileSync(filePath, newContent, "utf-8");
-		return { path: filePath, modified: true, added: [], removed: allIds };
-	}
-
-	// Remove specific block IDs
-	const existingBlocks = parseExistingBlocks(inner);
-	const removed: string[] = [];
-	for (const id of ids) {
-		if (existingBlocks.delete(id)) {
-			removed.push(id);
-		}
-	}
-
-	if (removed.length === 0) {
-		return { path: filePath, modified: false, added: [], removed: [] };
-	}
-
-	const merged = [...existingBlocks.values()];
-
-	if (merged.length === 0) {
-		const newContent = trimTrailingNewlines(before) + after;
-		fs.writeFileSync(filePath, newContent, "utf-8");
-		return { path: filePath, modified: true, added: [], removed };
-	}
-
-	const section = buildMarkerSection(merged);
-	const newContent = trimTrailingNewlines(before) + section + trimLeadingNewlines(after);
-	fs.writeFileSync(filePath, newContent, "utf-8");
-	return { path: filePath, modified: true, added: [], removed };
-}
-
-/**
- * Generate standard pi-crew guidance blocks for injection into project
- * files (e.g. AGENTS.md).
- *
- * @param version — current pi-crew package version for version-aware updates
- */
-export function standardGuidanceBlocks(version: string): GuidanceBlock[] {
-	return [
-		{
-			id: "pi-crew-overview",
-			priority: 10,
-			content: [
-				"## pi-crew",
-				"",
-				`> Managed by **pi-crew v${version}** — do not edit this section manually.`,
-				"",
-				"pi-crew is a Pi extension for coordinated AI agent teams, workflows,",
-				"worktrees, and async task orchestration.",
-			].join("\n"),
-		},
-		{
-			id: "pi-crew-commands",
-			priority: 5,
-			content: [
-				"### Quick Commands",
-				"",
-				"| Command | Description |",
-				"|---|---|",
-				"| `team action='init'` | Initialize pi-crew for this project |",
-				"| `team action='run'` | Start a team run |",
-				"| `team action='status'` | Check run status |",
-				"| `team action='list'` | List available teams/agents/workflows |",
-				"| `team action='recommend'` | Get team/workflow recommendations |",
-			].join("\n"),
-		},
-	];
-}
-
-/** Remove trailing newlines from a string, ensuring at most one trailing newline. */
-function trimTrailingNewlines(s: string): string {
-	return s.replace(/\n+$/, "");
-}
-
-/** Remove leading newlines from a string. */
-function trimLeadingNewlines(s: string): string {
-	return s.replace(/^\n+/, "");
-}

package/src/config/resilient-parser.ts

@@ -1,117 +0,0 @@
-/**
- * Per-field resilient config parsing — continues on error, collects all field-level issues.
- */
-
-import type { TSchema } from "@sinclair/typebox";
-import { Value } from "@sinclair/typebox/value";
-import { PiTeamsConfigSchema } from "../schema/config-schema.ts";
-import { type PiTeamsConfig, parseConfig } from "./config.ts";
-import { suggestConfigKey } from "./suggestions.ts";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface FieldError {
-	field: string;
-	message: string;
-	value: unknown;
-	suggestion?: string;
-}
-
-export interface ResilientParseResult {
-	config: Record<string, unknown>;
-	errors: FieldError[];
-	warnings: string[];
-	valid: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-const KNOWN_TOP_LEVEL_KEYS: readonly string[] = Object.keys(PiTeamsConfigSchema.properties ?? {});
-
-function isObject(value: unknown): value is Record<string, unknown> {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
-// ---------------------------------------------------------------------------
-// Implementation
-// ---------------------------------------------------------------------------
-
-/**
- * Parse a raw config value field-by-field.
- *
- * - Each top-level key is validated independently via TypeBox sub-schemas.
- * - Fields that fail are recorded as errors but do not block others.
- * - Unknown keys get a fuzzy suggestion via Levenshtein distance.
- * - The returned `config` contains only successfully-parsed fields (via `parseConfig`).
- */
-export function parseConfigResilient(raw: unknown): ResilientParseResult {
-	const errors: FieldError[] = [];
-	const warnings: string[] = [];
-
-	if (!isObject(raw)) {
-		return {
-			config: {},
-			errors: [
-				{
-					field: "config",
-					message: "config must be an object",
-					value: raw,
-				},
-			],
-			warnings,
-			valid: false,
-		};
-	}
-
-	// Collect unknown top-level keys with suggestions
-	for (const key of Object.keys(raw)) {
-		if (!KNOWN_TOP_LEVEL_KEYS.includes(key)) {
-			const suggestion = suggestConfigKey(key, KNOWN_TOP_LEVEL_KEYS);
-			errors.push({
-				field: key,
-				message: `unknown config key '${key}'`,
-				value: raw[key],
-				suggestion: suggestion ?? undefined,
-			});
-		}
-	}
-
-	// Use TypeBox per-field validation for known keys
-	for (const key of KNOWN_TOP_LEVEL_KEYS) {
-		if (!(key in raw)) continue;
-		const value = raw[key];
-		const subSchema = (PiTeamsConfigSchema.properties as Record<string, unknown>)[key];
-		if (subSchema && !Value.Check(subSchema as TSchema, value)) {
-			// Collect ALL errors for this field
-			const fieldErrors = [...Value.Errors(subSchema as TSchema, value)];
-			for (const err of fieldErrors) {
-				const errObj = err as unknown as Record<string, unknown>;
-				const msg = typeof errObj.message === "string" ? errObj.message : "invalid value";
-				errors.push({
-					field: key,
-					message: msg,
-					value,
-				});
-			}
-		}
-	}
-
-	// Build the valid subset using existing parseConfig (which silently drops invalid fields)
-	const parsed: PiTeamsConfig = parseConfig(raw);
-	const config: Record<string, unknown> = {};
-	for (const key of Object.keys(parsed)) {
-		const val = (parsed as Record<string, unknown>)[key];
-		if (val !== undefined) config[key] = val;
-	}
-
-	return {
-		config,
-		errors,
-		warnings,
-		valid: errors.length === 0,
-	};
-}

package/src/config/role-tools.ts

@@ -1,118 +0,0 @@
-/**
- * Role-based tool configurations for pi-crew agents.
- * Uses the excludeTools option from pi v0.77.0.
- */
-
-export interface RoleToolConfig {
-	/** Explicit list of tools to use (if undefined, use all default tools) */
-	tools?: string[];
-	/** Tools to exclude from the default set */
-	excludeTools?: string[];
-}
-
-export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
-	// Explorer - Read-only exploration; bash is included for git log/show
-	// (decisions stream needs commit-history mining) but edit/write stay
-	// excluded. State-mutation safety is enforced separately by
-	// READ_ONLY_ROLES in role-permission.ts.
-	explorer: {
-		tools: ["read", "grep", "find", "ls", "glob", "bash"],
-		excludeTools: ["edit", "write", "web"],
-	},
-
-	// Analyst - Read and analyze, limited execution
-	analyst: {
-		excludeTools: ["edit", "write", "ask_question"],
-	},
-
-	// Planner - Read-only planning; emits plans as TEXT (runner persists result).
-	// F2/F3: strengthened to a read-only tool-set matching its READ_ONLY_ROLES
-	// classification. Deliverables are emitted as RESULT TEXT (consumed by
-	// adaptive-plan.ts / runner shared-output), NOT file writes — so the
-	// plan-approval gate boundary (planner = read-only) is preserved. Moving
-	// planner to WRITE_ROLES would fire the gate before planning, breaking the
-	// default/implementation workflows.
-	planner: {
-		tools: ["read", "grep", "find", "ls", "glob"],
-		excludeTools: ["edit", "write", "bash", "web", "ask_question"],
-	},
-
-	// Critic - Read-only plan/design critique (F2: was missing from the map,
-	// so a custom critic agent had no tool-level read-only enforcement).
-	critic: {
-		tools: ["read", "grep", "find", "ls", "glob"],
-		excludeTools: ["edit", "write", "bash", "web"],
-	},
-
-	// Executor - Full access (default)
-	executor: {
-		// No restrictions - full tool access
-	},
-
-	// Reviewer - Read and review, no write
-	reviewer: {
-		tools: ["read", "grep", "find", "ls", "glob", "bash"],
-		excludeTools: ["edit", "write"],
-	},
-
-	// Writer - Documentation focused
-	writer: {
-		tools: ["read", "edit", "write", "ls"],
-		excludeTools: ["bash", "web", "ask_question"],
-	},
-
-	// Security Reviewer - Strict restrictions
-	// F1: key is hyphenated to match the runtime role string (agents/
-	// security-reviewer.md → "security-reviewer"). The underscore form never
-	// resolved at runtime (returned {}), silently dropping enforcement.
-	"security-reviewer": {
-		tools: ["read", "grep", "find"],
-		excludeTools: ["edit", "write", "bash", "web", "ask_question"],
-	},
-
-	// Verifier - Runs tests (needs bash) but must NOT edit source (F4: moved
-	// from READ_ONLY_ROLES to WRITE_ROLES — the read-only prompt gate forbids
-	// the test-running redirects / cache writes its task requires, contradicting
-	// agents/verifier.md). Tool-set keeps bash but excludes edit/write so source
-	// integrity is preserved during verification. Mirrors cold-verifier behavior.
-	verifier: {
-		tools: ["read", "grep", "find", "ls", "bash"],
-		excludeTools: ["edit", "write", "web"],
-	},
-
-	// Test Engineer - Can write tests (F1: hyphenated key)
-	"test-engineer": {
-		tools: ["read", "edit", "write", "bash", "ls"],
-		excludeTools: ["web"],
-	},
-};
-
-/**
- * Get tool configuration for a specific role.
- */
-export function getToolConfig(role: string): RoleToolConfig {
-	// F1: normalize hyphen/underscore. Runtime role strings are hyphenated
-	// (agents/security-reviewer.md → "security-reviewer") but map keys were
-	// historically underscored, silently returning {} at runtime — the same
-	// defect class as the v0.9.10 writer incident (opposite direction:
-	// under-enforce instead of over-enforce). Accept both forms.
-	const key = role.includes("_") ? role.replaceAll("_", "-") : role;
-	return ROLE_TOOL_CONFIGS[key] ?? ROLE_TOOL_CONFIGS[role] ?? {};
-}
-
-/**
- * Check if a role has any tool restrictions.
- */
-export function hasToolRestrictions(role: string): boolean {
-	const config = getToolConfig(role);
-	return config.tools !== undefined || config.excludeTools !== undefined;
-}
-
-/**
- * Get all restricted roles.
- */
-export function getRestrictedRoles(): string[] {
-	return Object.entries(ROLE_TOOL_CONFIGS)
-		.filter(([, config]) => config.tools !== undefined || config.excludeTools !== undefined)
-		.map(([role]) => role);
-}

package/src/config/suggestions.ts

@@ -1,75 +0,0 @@
-/**
- * Fuzzy config key suggestions — Levenshtein-based typo correction for pi-crew config keys.
- *
- * SECURITY NOTE: The levenshtein() function processes user-supplied input and compares
- * against a known list. While the timing variance across edit distances is minimal
- * and the input is typically config key names (not secrets), there is a theoretical
- * timing attack risk if an attacker could measure response times for different inputs.
- * Risk level: LOW — mitigated by the small alphabet (config key names only) and
- * the fixed-size DP array used in this implementation.
- */
-
-/**
- * Classic Levenshtein edit distance between two strings.
- * See security note above regarding timing attack considerations.
- */
-export function levenshtein(a: string, b: string): number {
-	const la = a.length;
-	const lb = b.length;
-	if (la === 0) return lb;
-	if (lb === 0) return la;
-
-	// Single-row DP to keep memory O(min(n,m))
-	let prev = new Uint32Array(lb + 1);
-	let curr = new Uint32Array(lb + 1);
-
-	for (let j = 0; j <= lb; j++) prev[j] = j;
-
-	for (let i = 1; i <= la; i++) {
-		curr[0] = i;
-		for (let j = 1; j <= lb; j++) {
-			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-			curr[j] = Math.min(
-				prev[j] + 1, // deletion
-				curr[j - 1] + 1, // insertion
-				prev[j - 1] + cost, // substitution
-			);
-		}
-		const swap = prev;
-		prev = curr;
-		curr = swap;
-	}
-
-	return prev[lb];
-}
-
-const DEFAULT_MAX_DISTANCE = 3;
-
-/**
- * Find the closest matching key from a list of valid keys.
- * Case-insensitive. Returns null if no match within `maxDistance`.
- */
-export function findClosestKey(input: string, validKeys: readonly string[], maxDistance: number = DEFAULT_MAX_DISTANCE): string | null {
-	if (validKeys.length === 0) return null;
-
-	const lower = input.toLowerCase();
-	let bestKey: string | null = null;
-	let bestDist = maxDistance + 1;
-
-	for (const key of validKeys) {
-		const dist = levenshtein(lower, key.toLowerCase());
-		if (dist < bestDist) {
-			bestDist = dist;
-			bestKey = key;
-		}
-	}
-
-	return bestDist <= maxDistance ? bestKey : null;
-}
-
-/**
- * Convenience wrapper — suggest the closest known config key for a potentially mistyped input.
- */
-export function suggestConfigKey(input: string, knownKeys: readonly string[]): string | null {
-	return findClosestKey(input, knownKeys);
-}