pi-crew 0.2.3 → 0.2.5

package/src/schema/validation-types.ts

@@ -1,148 +1,151 @@
-/**
- * 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 };
-}
+/**
+ * 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 "@sinclair/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 / unknown keys are less severe in lenient mode.
+			// @sinclair/typebox uses keyword=undefined with message="Unexpected property" for these.
+			const isUnknownProperty = errRecord.keyword === "additionalProperties" ||
+				message === "Unexpected property" || message.startsWith("Unexpected property");
+			if (isUnknownProperty) {
+				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/discover-skills.ts

@@ -1,67 +1,67 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import { logInternalError } from "../utils/internal-error.ts";
-import { isSafePathId, resolveContainedPath, resolveRealContainedPath } from "../utils/safe-paths.ts";
-
-const PACKAGE_SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
-
-export interface SkillDescriptor {
-	name: string;
-	description: string;
-	source: "project" | "package";
-	path: string;
-}
-
-function listSkillDirs(cwd: string): Array<{ root: string; source: "project" | "package" }> {
-	return [
-		{ root: path.resolve(cwd, "skills"), source: "project" },
-		{ root: PACKAGE_SKILLS_DIR, source: "package" },
-	];
-}
-
-function frontmatterDescription(content: string): string | undefined {
-	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
-	if (!match) return undefined;
-	const line = match[1].split(/\r?\n/).find((entry) => entry.startsWith("description:"));
-	return line?.slice("description:".length).trim();
-}
-
-export function discoverSkills(cwd: string): SkillDescriptor[] {
-	const results: SkillDescriptor[] = [];
-	for (const dir of listSkillDirs(cwd)) {
-		if (!fs.existsSync(dir.root)) continue;
-		try {
-			for (const entry of fs.readdirSync(dir.root, { withFileTypes: true })) {
-				if (!entry.isDirectory()) continue;
-				if (!isSafePathId(entry.name)) continue;
-				const skillDirPath = path.join(dir.root, entry.name);
-				try {
-					if (fs.lstatSync(skillDirPath).isSymbolicLink()) continue;
-				} catch { continue; }
-				const skillMdRelative = path.join(entry.name, "SKILL.md");
-				let skillMdPath: string;
-				try {
-					skillMdPath = resolveContainedPath(dir.root, skillMdRelative);
-				} catch { continue; }
-				if (!fs.existsSync(skillMdPath)) continue;
-				try {
-					if (fs.lstatSync(skillMdPath).isSymbolicLink()) continue;
-				} catch { continue; }
-				let description = "";
-				try {
-					const realPath = resolveRealContainedPath(dir.root, skillMdRelative);
-					const content = fs.readFileSync(realPath, "utf-8");
-					description = frontmatterDescription(content) ?? "";
-					skillMdPath = realPath;
-				} catch (error) {
-					logInternalError("discoverSkills.readSkill", error, `skill=${entry.name}`);
-				}
-				results.push({ name: entry.name, description, source: dir.source, path: skillMdPath });
-			}
-		} catch (error) {
-			logInternalError("discoverSkills.readdir", error, `root=${dir.root}`);
-		}
-	}
-	return results;
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { logInternalError } from "../utils/internal-error.ts";
+import { isSafePathId, resolveContainedPath, resolveRealContainedPath } from "../utils/safe-paths.ts";
+
+const PACKAGE_SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
+
+export interface SkillDescriptor {
+	name: string;
+	description: string;
+	source: "project" | "package";
+	path: string;
+}
+
+function listSkillDirs(cwd: string): Array<{ root: string; source: "project" | "package" }> {
+	return [
+		{ root: path.resolve(cwd, "skills"), source: "project" },
+		{ root: PACKAGE_SKILLS_DIR, source: "package" },
+	];
+}
+
+function frontmatterDescription(content: string): string | undefined {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+	if (!match) return undefined;
+	const line = match[1].split(/\r?\n/).find((entry) => entry.startsWith("description:"));
+	return line?.slice("description:".length).trim();
+}
+
+export function discoverSkills(cwd: string): SkillDescriptor[] {
+	const results: SkillDescriptor[] = [];
+	for (const dir of listSkillDirs(cwd)) {
+		if (!fs.existsSync(dir.root)) continue;
+		try {
+			for (const entry of fs.readdirSync(dir.root, { withFileTypes: true })) {
+				if (!entry.isDirectory()) continue;
+				if (!isSafePathId(entry.name)) continue;
+				const skillDirPath = path.join(dir.root, entry.name);
+				try {
+					if (fs.lstatSync(skillDirPath).isSymbolicLink()) continue;
+				} catch { continue; }
+				const skillMdRelative = path.join(entry.name, "SKILL.md");
+				let skillMdPath: string;
+				try {
+					skillMdPath = resolveContainedPath(dir.root, skillMdRelative);
+				} catch { continue; }
+				if (!fs.existsSync(skillMdPath)) continue;
+				try {
+					if (fs.lstatSync(skillMdPath).isSymbolicLink()) continue;
+				} catch { continue; }
+				let description = "";
+				try {
+					const realPath = resolveRealContainedPath(dir.root, skillMdRelative);
+					const content = fs.readFileSync(realPath, "utf-8");
+					description = frontmatterDescription(content) ?? "";
+					skillMdPath = realPath;
+				} catch (error) {
+					logInternalError("discoverSkills.readSkill", error, `skill=${entry.name}`);
+				}
+				results.push({ name: entry.name, description, source: dir.source, path: skillMdPath });
+			}
+		} catch (error) {
+			logInternalError("discoverSkills.readdir", error, `root=${dir.root}`);
+		}
+	}
+	return results;
+}