pi-crew 0.1.49 → 0.2.0

package/src/config/markers.ts

@@ -0,0 +1,327 @@
+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;
+  while ((match = regex.exec(content)) !== null) {
+    ids.push(match[1]!);
+  }
+  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;
+  while ((match = regex.exec(inner)) !== null) {
+    const id = match[1]!;
+    const content = match[2]!;
+    map.set(id, { id, content: content.replace(/\n$/, "") });
+  }
+  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

@@ -0,0 +1,108 @@
+/**
+ * Per-field resilient config parsing — continues on error, collects all field-level issues.
+ */
+
+import { PiTeamsConfigSchema } from "../schema/config-schema.ts";
+import { Value } from "typebox/value";
+import { suggestConfigKey } from "./suggestions.ts";
+import {
+	parseConfig,
+	type PiTeamsConfig,
+} from "./config.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 { [key: string]: unknown }, value)) {
+			// Collect the first error for this field
+			const fieldErrors = [...Value.Errors(subSchema as { [key: string]: unknown }, value)];
+			if (fieldErrors.length > 0) {
+				const first = fieldErrors[0] as unknown as Record<string, unknown>;
+				const msg = typeof first.message === "string" ? first.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/suggestions.ts

@@ -0,0 +1,74 @@
+/**
+ * Fuzzy config key suggestions — Levenshtein-based typo correction for pi-crew config keys.
+ */
+
+/**
+ * Classic Levenshtein edit distance between two strings.
+ */
+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);
+}