pi-crew 0.1.49 → 0.2.0

package/src/schema/validation-types.ts

@@ -0,0 +1,148 @@
+/**
+ * Validation severity levels for pi-crew config.
+ *
+ * - Required fields invalid → always ERROR
+ * - Optional fields invalid → ERROR (strict) / WARNING (lenient)
+ * - Missing recommended optional fields → INFO
+ * - Values outside recommended ranges → WARNING
+ */
+
+import { Value } from "typebox/value";
+import { PiTeamsConfigSchema } from "./config-schema.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ValidationSeverity = "ERROR" | "WARNING" | "INFO";
+
+export type ValidationMode = "strict" | "lenient";
+
+export interface ValidationFinding {
+	severity: ValidationSeverity;
+	message: string;
+	field?: string;
+	suggestion?: string;
+}
+
+export interface ValidationOutcome {
+	findings: ValidationFinding[];
+	mode: ValidationMode;
+	hasErrors: boolean;
+	hasWarnings: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MODE: ValidationMode = "strict";
+
+/** Recommended range constraints (not enforced by schema, but advisory). */
+const RECOMMENDED_RANGES: Record<string, { max: number; label: string }> = {
+	"limits.maxConcurrentWorkers": { max: 8, label: "maxConcurrentWorkers > 8 may degrade performance" },
+	"limits.maxTaskDepth": { max: 4, label: "maxTaskDepth > 4 may cause excessive nesting" },
+};
+
+/** Recommended optional top-level keys that should be explicitly set. */
+const RECOMMENDED_OPTIONAL_KEYS: readonly string[] = [
+	"limits",
+	"runtime",
+];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function getNestedValue(obj: Record<string, unknown>, dottedPath: string): unknown {
+	const parts = dottedPath.split(".");
+	let current: unknown = obj;
+	for (const part of parts) {
+		if (!isObject(current)) return undefined;
+		current = current[part];
+	}
+	return current;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a raw config value with severity-tagged findings.
+ *
+ * @param raw   The raw config value to validate.
+ * @param mode  Validation mode — 'strict' (default) or 'lenient'.
+ * @returns     A `ValidationOutcome` with findings grouped by severity.
+ */
+export function validateWithSeverity(raw: unknown, mode: ValidationMode = DEFAULT_MODE): ValidationOutcome {
+	const findings: ValidationFinding[] = [];
+
+	if (!isObject(raw)) {
+		findings.push({ severity: "ERROR", message: "config must be an object", field: "config" });
+		return { findings, mode, hasErrors: true, hasWarnings: false };
+	}
+
+	// --- Schema-based validation ---
+	const isValid = Value.Check(PiTeamsConfigSchema, raw);
+	if (!isValid) {
+		for (const error of Value.Errors(PiTeamsConfigSchema, raw)) {
+			const errRecord = error as unknown as Record<string, unknown>;
+			const rawPath = typeof errRecord.path === "string"
+				? errRecord.path
+				: typeof errRecord.instancePath === "string"
+					? errRecord.instancePath
+					: "config";
+
+			const message = typeof errRecord.message === "string"
+				? errRecord.message
+				: "invalid value";
+
+			const field = rawPath.replace(/^\//, "").replace(/\//g, ".") || undefined;
+
+			// Additional properties are less severe in lenient mode
+			if (errRecord.keyword === "additionalProperties") {
+				findings.push({
+					severity: mode === "lenient" ? "WARNING" : "ERROR",
+					message: `unknown property${field ? ` '${field}'` : ""}: ${message}`,
+					field,
+				});
+			} else {
+				findings.push({ severity: "ERROR", message, field });
+			}
+		}
+	}
+
+	// --- Missing recommended optional keys → INFO ---
+	for (const key of RECOMMENDED_OPTIONAL_KEYS) {
+		if (!(key in raw)) {
+			findings.push({
+				severity: "INFO",
+				message: `recommended config section '${key}' is not set`,
+				field: key,
+			});
+		}
+	}
+
+	// --- Values outside recommended ranges → WARNING ---
+	for (const [dottedPath, constraint] of Object.entries(RECOMMENDED_RANGES)) {
+		const value = getNestedValue(raw, dottedPath);
+		if (typeof value === "number" && value > constraint.max) {
+			findings.push({
+				severity: "WARNING",
+				message: constraint.label,
+				field: dottedPath,
+				suggestion: `consider using a value ≤ ${constraint.max}`,
+			});
+		}
+	}
+
+	const hasErrors = findings.some((f) => f.severity === "ERROR");
+	const hasWarnings = findings.some((f) => f.severity === "WARNING");
+
+	return { findings, mode, hasErrors, hasWarnings };
+}

package/src/skills/skill-templates.ts

@@ -0,0 +1,374 @@
+/**
+ * Template-based skill initialization for pi-crew.
+ *
+ * Provides builtin skill templates that can be instantiated with project-specific
+ * variables to produce ready-to-use SKILL.md files.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SkillVariable {
+	/** Variable name used as placeholder key in the template body, e.g. "language". */
+	name: string;
+	/** Human-readable description of what this variable controls. */
+	description: string;
+	/** When true the caller must supply a value (no default available). */
+	required: boolean;
+	/** Default value used when the variable is optional and no value is supplied. */
+	defaultValue?: string;
+	/** If set, the supplied value must be one of these strings. */
+	options?: string[];
+}
+
+export interface SkillTemplate {
+	/** Unique template identifier, e.g. "code-review". */
+	id: string;
+	/** Human-readable name. */
+	name: string;
+	/** Short description of the skill this template produces. */
+	description: string;
+	/** Category for grouping (e.g. "quality", "testing", "documentation"). */
+	category: string;
+	/** Template variables referenced via {varName} in the body. */
+	variables: SkillVariable[];
+	/** Markdown template body with {variableName} placeholders. */
+	body: string;
+	/** Hard rules the instantiated skill must follow. */
+	guardrails: string[];
+}
+
+export interface InstantiatedSkill {
+	/** Suggested filename, e.g. "code-review.SKILL.md". */
+	filename: string;
+	/** Fully rendered markdown content. */
+	content: string;
+}
+
+// ---------------------------------------------------------------------------
+// Builtin templates
+// ---------------------------------------------------------------------------
+
+const CODE_REVIEW_TEMPLATE: SkillTemplate = {
+	id: "code-review",
+	name: "Code Review",
+	description: "Systematic code review skill with configurable language and focus areas.",
+	category: "quality",
+	variables: [
+		{ name: "language", description: "Primary programming language of the codebase", required: true, options: ["TypeScript", "JavaScript", "Python", "Rust", "Go", "Java", "C#", "Other"] },
+		{ name: "focusAreas", description: "Comma-separated list of review focus areas", required: false, defaultValue: "correctness, readability, performance" },
+		{ name: "severityThreshold", description: "Minimum severity level to report", required: false, defaultValue: "warning", options: ["info", "warning", "error", "critical"] },
+	],
+	body: [
+		"---",
+		"description: Automated code review for {language} projects",
+		"---",
+		"",
+		"# Code Review Skill",
+		"",
+		"You are a code reviewer specializing in **{language}**.",
+		"",
+		"## Focus Areas",
+		"",
+		"Prioritize the following aspects (in order):",
+		"",
+		"{focusAreas}",
+		"",
+		"## Severity Threshold",
+		"",
+		"Only surface issues at or above **{severityThreshold}** severity.",
+		"",
+		"## Process",
+		"",
+		"1. Read the full diff / files before commenting.",
+		"2. Classify each finding by severity.",
+		"3. Provide actionable suggestions with code examples where helpful.",
+		"4. Summarize overall quality and risk assessment.",
+	].join("\n"),
+	guardrails: [
+		"Do not approve code you have not fully read.",
+		"Do not comment on style issues that are already handled by a linter.",
+		"Do not suggest changes without explaining the reasoning.",
+	],
+};
+
+const TESTING_TEMPLATE: SkillTemplate = {
+	id: "testing",
+	name: "Testing",
+	description: "Test writing skill with configurable framework and coverage targets.",
+	category: "testing",
+	variables: [
+		{ name: "framework", description: "Testing framework to use", required: true, options: ["vitest", "jest", "mocha", "pytest", "go-test", "cargo-test", "Other"] },
+		{ name: "coverageTarget", description: "Target coverage percentage", required: false, defaultValue: "80" },
+		{ name: "testType", description: "Primary type of tests to write", required: false, defaultValue: "unit", options: ["unit", "integration", "e2e", "all"] },
+	],
+	body: [
+		"---",
+		"description: Write tests using {framework} with {coverageTarget}% coverage target",
+		"---",
+		"",
+		"# Testing Skill",
+		"",
+		"You are a test engineer writing **{testType}** tests using **{framework}**.",
+		"",
+		"## Coverage Target",
+		"",
+		"Aim for at least **{coverageTarget}%** code coverage.",
+		"",
+		"## Guidelines",
+		"",
+		"1. Write descriptive test names that explain the expected behavior.",
+		"2. Follow the Arrange-Act-Assert pattern.",
+		"3. Test edge cases and error paths, not just the happy path.",
+		"4. Keep tests independent — no shared mutable state between tests.",
+		"5. Mock external dependencies; do not hit real network services.",
+	].join("\n"),
+	guardrails: [
+		"Do not skip testing error paths.",
+		"Do not write tests that depend on execution order.",
+		"Do not mock the system under test.",
+	],
+};
+
+const SECURITY_AUDIT_TEMPLATE: SkillTemplate = {
+	id: "security-audit",
+	name: "Security Audit",
+	description: "Security review skill with configurable scope and severity thresholds.",
+	category: "security",
+	variables: [
+		{ name: "scope", description: "Audit scope: what parts of the codebase to examine", required: true, options: ["full-codebase", "dependencies", "api-surface", "auth-flows", "input-handling"] },
+		{ name: "severityThreshold", description: "Minimum severity to report", required: false, defaultValue: "medium", options: ["low", "medium", "high", "critical"] },
+		{ name: "complianceFramework", description: "Compliance framework to check against (if applicable)", required: false, defaultValue: "OWASP Top 10" },
+	],
+	body: [
+		"---",
+		"description: Security audit focusing on {scope} (threshold: {severityThreshold})",
+		"---",
+		"",
+		"# Security Audit Skill",
+		"",
+		"You are a security auditor performing a **{scope}** review.",
+		"",
+		"## Severity Threshold",
+		"",
+		"Report all findings at or above **{severityThreshold}** severity.",
+		"",
+		"## Compliance Framework",
+		"",
+		"Check against: **{complianceFramework}**.",
+		"",
+		"## Methodology",
+		"",
+		"1. Identify the attack surface relevant to the chosen scope.",
+		"2. Trace data flows from untrusted inputs.",
+		"3. Check for common vulnerability classes (injection, auth bypass, etc.).",
+		"4. Verify that secrets/credentials are handled safely.",
+		"5. Document each finding with severity, description, and remediation.",
+	].join("\n"),
+	guardrails: [
+		"Do not ignore low-severity findings that could chain into higher-severity exploits.",
+		"Do not report theoretical issues without evidence in the code.",
+		"Do not store or log real secrets/credentials during the audit.",
+	],
+};
+
+const REFACTOR_TEMPLATE: SkillTemplate = {
+	id: "refactor",
+	name: "Refactor",
+	description: "Refactoring skill with configurable scope and constraints.",
+	category: "maintenance",
+	variables: [
+		{ name: "scope", description: "What to refactor: file, module, or architectural pattern", required: true },
+		{ name: "constraints", description: "Constraints to respect during refactoring", required: false, defaultValue: "preserve public API, maintain backward compatibility" },
+		{ name: "goal", description: "Primary refactoring goal", required: false, defaultValue: "improve readability and reduce complexity", options: ["improve readability and reduce complexity", "improve performance", "reduce coupling", "enable extensibility", "simplify testability"] },
+	],
+	body: [
+		"---",
+		"description: Refactoring skill targeting {scope}",
+		"---",
+		"",
+		"# Refactor Skill",
+		"",
+		"You are a refactoring specialist working on **{scope}**.",
+		"",
+		"## Goal",
+		"",
+		"Primary objective: **{goal}**.",
+		"",
+		"## Constraints",
+		"",
+		"The following constraints must be respected:",
+		"",
+		"- {constraints}",
+		"",
+		"## Approach",
+		"",
+		"1. Understand the current code structure and all usages.",
+		"2. Plan the refactoring in small, reviewable steps.",
+		"3. Run existing tests after each step to verify correctness.",
+		"4. Add new tests if the refactoring introduces new behavior.",
+		"5. Document any architectural decisions made during the refactor.",
+	].join("\n"),
+	guardrails: [
+		"Do not change public API signatures without explicit approval.",
+		"Do not mix refactoring with feature changes.",
+		"Do not skip running tests between steps.",
+	],
+};
+
+const DOCUMENTATION_TEMPLATE: SkillTemplate = {
+	id: "documentation",
+	name: "Documentation",
+	description: "Documentation writing skill with configurable format and audience.",
+	category: "documentation",
+	variables: [
+		{ name: "format", description: "Documentation format to produce", required: true, options: ["markdown", "jsdoc", "rustdoc", "godoc", "pydoc", "openapi"] },
+		{ name: "audience", description: "Target audience for the documentation", required: false, defaultValue: "developers", options: ["developers", "operators", "end-users", "contributors", "architects"] },
+		{ name: "detailLevel", description: "Level of detail", required: false, defaultValue: "standard", options: ["brief", "standard", "comprehensive"] },
+	],
+	body: [
+		"---",
+		"description: Write {format} documentation for {audience}",
+		"---",
+		"",
+		"# Documentation Skill",
+		"",
+		"You are a technical writer producing **{format}** documentation",
+		"for **{audience}**.",
+		"",
+		"## Detail Level",
+		"",
+		"Detail level: **{detailLevel}**.",
+		"",
+		"## Guidelines",
+		"",
+		"1. Start with a brief summary of what the module/function does.",
+		"2. Document all public APIs with parameter descriptions and return types.",
+		"3. Include usage examples for non-trivial functionality.",
+		"4. Keep language clear and avoid unnecessary jargon.",
+		"5. Cross-reference related modules where applicable.",
+	].join("\n"),
+	guardrails: [
+		"Do not document private/internal APIs unless specifically requested.",
+		"Do not generate placeholder content — every section must be meaningful.",
+		"Do not duplicate information already present in existing docs.",
+	],
+};
+
+const BUILTIN_TEMPLATES: SkillTemplate[] = [
+	CODE_REVIEW_TEMPLATE,
+	TESTING_TEMPLATE,
+	SECURITY_AUDIT_TEMPLATE,
+	REFACTOR_TEMPLATE,
+	DOCUMENTATION_TEMPLATE,
+];
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Return all builtin skill templates.
+ */
+export function getBuiltinTemplates(): SkillTemplate[] {
+	return BUILTIN_TEMPLATES;
+}
+
+/**
+ * Look up a builtin template by its id or name (case-insensitive).
+ */
+export function findTemplate(idOrName: string): SkillTemplate | undefined {
+	const lower = idOrName.toLowerCase();
+	return BUILTIN_TEMPLATES.find(
+		(t) => t.id.toLowerCase() === lower || t.name.toLowerCase() === lower,
+	);
+}
+
+/**
+ * Instantiate a skill template by filling in its variables.
+ *
+ * - Required variables that are missing throw an error.
+ * - Optional variables fall back to their `defaultValue` if not supplied.
+ * - Variables with `options` constrain the allowed values.
+ *
+ * @param template  The template to instantiate.
+ * @param variables User-supplied variable values.
+ * @returns An object with the suggested filename and rendered content.
+ */
+export function instantiateTemplate(
+	template: SkillTemplate,
+	variables: Record<string, string>,
+): InstantiatedSkill {
+	// Validate and resolve all variable values
+	const resolved: Record<string, string> = {};
+
+	for (const variable of template.variables) {
+		const value = variables[variable.name];
+
+		if (value === undefined || value === "") {
+			if (variable.required) {
+				throw new Error(
+					`Missing required variable "${variable.name}" for template "${template.id}" (${variable.description}).`,
+				);
+			}
+			resolved[variable.name] = variable.defaultValue ?? "";
+			continue;
+		}
+
+		// Validate options constraint
+		if (variable.options !== undefined && !variable.options.includes(value)) {
+			throw new Error(
+				`Invalid value "${value}" for variable "${variable.name}" in template "${template.id}". ` +
+				`Allowed values: ${variable.options.join(", ")}.`,
+			);
+		}
+
+		resolved[variable.name] = value;
+	}
+
+	// Render the template body by replacing all {varName} placeholders
+	let content = template.body;
+	for (const [key, value] of Object.entries(resolved)) {
+		// Use a global regex to replace all occurrences of {key}
+		const placeholderRegex = new RegExp(`\\{${escapeRegExp(key)}\\}`, "g");
+		content = content.replace(placeholderRegex, value);
+	}
+
+	// Build filename from template id
+	const filename = `${template.id}.SKILL.md`;
+
+	return { filename, content };
+}
+
+/**
+ * Return a simplified list of available templates suitable for display.
+ * Each entry contains id, name, description, category, and variable names.
+ */
+export function listTemplates(): Array<{
+	id: string;
+	name: string;
+	description: string;
+	category: string;
+	variables: Array<{ name: string; required: boolean }>;
+}> {
+	return BUILTIN_TEMPLATES.map((t) => ({
+		id: t.id,
+		name: t.name,
+		description: t.description,
+		category: t.category,
+		variables: t.variables.map((v) => ({ name: v.name, required: v.required })),
+	}));
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Escape special regex characters in a string so it can be used inside a
+ * RegExp constructor.
+ */
+function escapeRegExp(input: string): string {
+	return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/state/active-run-registry.ts

@@ -6,6 +6,7 @@ import { atomicWriteJson } from "./atomic-write.ts";
 import { userCrewRoot } from "../utils/paths.ts";
 import { isSafePathId } from "../utils/safe-paths.ts";
 import { sharedScanCache } from "../utils/scan-cache.ts";
+import { sleepSync } from "../utils/sleep.ts";
 
 export interface ActiveRunRegistryEntry {
 	runId: string;
@@ -23,16 +24,7 @@ function registryLockPath(): string {
 	return `${registryPath()}.lock`;
 }
 
-function sleepSync(ms: number): void {
-	try {
-		Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-	} catch {
-		const deadline = Date.now() + ms;
-		while (Date.now() < deadline) {
-			// Best-effort fallback for rare runtimes without Atomics.wait.
-		}
-	}
-}
+
 
 function lockCreatedAt(raw: string): number | undefined {
 	try {
@@ -125,6 +117,32 @@ function writeEntries(entries: ActiveRunRegistryEntry[]): void {
 	atomicWriteJson(registryPath(), entries.slice(0, DEFAULT_CACHE.manifestMaxEntries));
 }
 
+const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled", "blocked"]);
+
+/**
+ * Filter out entries that are no longer active: terminal status or missing manifest.
+ * This prevents unbounded growth of the active-run-index.json file.
+ */
+function filterAliveEntries(entries: ActiveRunRegistryEntry[]): ActiveRunRegistryEntry[] {
+	return entries.filter((entry) => {
+		// Quick checks first — skip heavy manifest read if CWD or state dir is gone
+		try {
+			if (!fs.existsSync(entry.cwd)) return false;
+			if (!fs.existsSync(entry.manifestPath)) return false;
+		} catch {
+			return false;
+		}
+		// Only read manifest if quick checks pass
+		try {
+			const raw = JSON.parse(fs.readFileSync(entry.manifestPath, "utf-8")) as { status?: string };
+			if (TERMINAL_STATUSES.has(raw.status ?? "")) return false;
+		} catch {
+			return false;
+		}
+		return true;
+	});
+}
+
 export function registerActiveRun(manifest: TeamRunManifest): void {
 	const entry: ActiveRunRegistryEntry = {
 		runId: manifest.runId,
@@ -134,7 +152,11 @@ export function registerActiveRun(manifest: TeamRunManifest): void {
 		updatedAt: manifest.updatedAt,
 	};
 	withRegistryLock(() => {
-		writeEntries([entry, ...readActiveRunRegistry().filter((item) => item.runId !== manifest.runId)]);
+		const existing = readActiveRunRegistry().filter((item) => item.runId !== manifest.runId);
+		// Inline cleanup: remove terminal-status and stale entries before writing.
+		// This prevents unbounded growth between sessions.
+		const alive = filterAliveEntries(existing);
+		writeEntries([entry, ...alive]);
 	});
 }
 
@@ -149,6 +171,8 @@ export function activeRunEntries(): ActiveRunRegistryEntry[] {
 	const entries: ActiveRunRegistryEntry[] = [];
 	for (const entry of readActiveRunRegistry()) {
 		try {
+			// Skip entries whose CWD no longer exists (temp test dirs, deleted projects)
+			if (!fs.existsSync(entry.cwd)) continue;
 			if (!fs.existsSync(entry.stateRoot) || !fs.existsSync(entry.manifestPath)) continue;
 			if (fs.lstatSync(entry.stateRoot).isSymbolicLink()) continue;
 			const cached = sharedScanCache.readAndCache("active-manifests", entry.runId, entry.manifestPath);