@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/core/tool-names.ts

@@ -0,0 +1,65 @@
+/**
+ * Canonical tool names. Everything that dispatches a tool call references these constants
+ * so mode matrices, safety classifiers, and audit filters never diverge on spelling.
+ *
+ * The surface is organized in seven planes; each plane is one policy unit
+ * (action class, size posture, details schema, concurrency rule):
+ *   OBSERVE      read, grep, find, ls, code_nav, context, credential_present
+ *   MUTATE       write, edit
+ *   EXECUTE      bash, git, verify
+ *   ORCHESTRATE  dispatch, monitor, steer, tasks
+ *   RETRIEVE     web_fetch
+ *   INTERACT     ask_user
+ *   ARTIFACT     artifact
+ */
+
+export const ToolNames = {
+	// OBSERVE
+	Read: "read",
+	Grep: "grep",
+	Find: "find",
+	Ls: "ls",
+	CodeNav: "code_nav",
+	Context: "context",
+	CredentialPresent: "credential_present",
+	// MUTATE
+	Write: "write",
+	Edit: "edit",
+	// EXECUTE
+	Bash: "bash",
+	Git: "git",
+	Verify: "verify",
+	// ORCHESTRATE
+	Dispatch: "dispatch",
+	Monitor: "monitor",
+	Steer: "steer",
+	Tasks: "tasks",
+	Ledger: "ledger",
+	// RETRIEVE
+	WebFetch: "web_fetch",
+	// INTERACT
+	AskUser: "ask_user",
+	// ARTIFACT
+	Artifact: "artifact",
+	// DESIGN-RESERVED, not implemented: gateway, the MCP/DB proxy. One fixed
+	// schema; external capabilities are surfaced through find/describe/call
+	// RESULTS, never as per-capability schemas in the prompt prefix. Contract
+	// sketch: gateway(op: "find" | "describe" | "call", capability?, args?)
+	// -> JSON capability listings / schemas / call results, network action
+	// class, sequential. Reserving the name here keeps classifiers and
+	// profiles from ever assigning "gateway" to a dynamic tool.
+	// Gateway: "gateway",
+} as const;
+
+export type BuiltinToolName = (typeof ToolNames)[keyof typeof ToolNames];
+
+declare const dynamicToolNameBrand: unique symbol;
+export type DynamicToolName = string & { readonly [dynamicToolNameBrand]: "dynamic-tool-name" };
+
+export type ToolName = BuiltinToolName | DynamicToolName;
+
+export const ALL_TOOL_NAMES: ReadonlyArray<BuiltinToolName> = Object.values(ToolNames);
+
+export function isBuiltinToolName(name: ToolName): name is BuiltinToolName {
+	return (ALL_TOOL_NAMES as ReadonlyArray<string>).includes(name);
+}

package/src/core/verification-scripts.ts

@@ -0,0 +1,13 @@
+export const VERIFICATION_SCRIPT_FAMILY_HINT = "test*/lint*/build*/typecheck*/check*/format*/ci*";
+
+const VERIFICATION_SCRIPT_PATTERN = /^(?:test|lint|build|typecheck|check|format|ci)(?:[:.-].*)?$/;
+
+export function isVerificationScriptName(name: string): boolean {
+	return VERIFICATION_SCRIPT_PATTERN.test(name);
+}
+
+export function declaredVerificationScripts(scripts: Record<string, unknown>): string[] {
+	return Object.keys(scripts)
+		.filter((name) => isVerificationScriptName(name))
+		.sort((a, b) => a.localeCompare(b));
+}

package/src/core/workspace-files.ts

@@ -0,0 +1,492 @@
+import { execFile, execFileSync } from "node:child_process";
+import fs, { type Dir } from "node:fs";
+import { join, sep } from "node:path";
+import { performance } from "node:perf_hooks";
+
+/**
+ * Cooperative-yield surface for the async enumeration forms. Structurally
+ * compatible with the context domain's CooperativeSlicer, so callers that
+ * already hold one pass it straight through; callers without one get a local
+ * time-budgeted default. Core cannot import the domain type, by boundary.
+ */
+export interface WorkspaceEnumerationTick {
+	tick(): Promise<void>;
+}
+
+const DEFAULT_YIELD_BUDGET_MS = 8;
+
+function createDefaultTick(budgetMs = DEFAULT_YIELD_BUDGET_MS): WorkspaceEnumerationTick {
+	let sliceStart = performance.now();
+	return {
+		async tick(): Promise<void> {
+			if (performance.now() - sliceStart < budgetMs) return;
+			await new Promise<void>((resolve) => {
+				setImmediate(resolve);
+			});
+			sliceStart = performance.now();
+		},
+	};
+}
+
+const GIT_OUTPUT_LIMIT_BYTES = 128 * 1024 * 1024;
+const MAX_ENUMERATION_DIAGNOSTIC_PATH_CHARS = 200;
+
+export interface WorkspaceFallbackLimits {
+	maxVisitedEntries: number;
+	maxDepth: number;
+	maxPathBytes: number;
+	maxDurationMs: number;
+}
+
+export type WorkspaceFallbackLimitKind = "entries" | "depth" | "path-bytes" | "time";
+export type WorkspaceEnumerationOperation = "open-root" | "read-directory" | "open-directory" | "inspect-entry";
+
+const DEFAULT_WORKSPACE_FALLBACK_LIMITS: Readonly<WorkspaceFallbackLimits> = Object.freeze({
+	maxVisitedEntries: 100_000,
+	maxDepth: 64,
+	maxPathBytes: 64 * 1024 * 1024,
+	maxDurationMs: 5_000,
+});
+
+/**
+ * Explicit failure for a non-Git scan that cannot prove it saw the whole
+ * workspace within its resource contract. Callers must never publish the
+ * partial prefix as an authoritative file set.
+ */
+export class WorkspaceEnumerationLimitError extends Error {
+	readonly code = "WORKSPACE_ENUMERATION_LIMIT";
+
+	constructor(
+		readonly kind: WorkspaceFallbackLimitKind,
+		readonly limit: number,
+	) {
+		super(`non-Git workspace enumeration exceeded ${kind} limit (${limit})`);
+		this.name = "WorkspaceEnumerationLimitError";
+	}
+}
+
+function boundedDiagnosticPath(path: string): string {
+	const printable = Array.from(path.length > 0 ? path : ".", (character) => {
+		const codePoint = character.codePointAt(0) ?? 0;
+		return codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f) ? "?" : character;
+	});
+	if (printable.length <= MAX_ENUMERATION_DIAGNOSTIC_PATH_CHARS) return printable.join("");
+	const side = Math.floor((MAX_ENUMERATION_DIAGNOSTIC_PATH_CHARS - 1) / 2);
+	return `${printable.slice(0, side).join("")}\u2026${printable.slice(-side).join("")}`;
+}
+
+function boundedSystemErrorCode(cause: unknown): string {
+	if (typeof cause !== "object" || cause === null || !("code" in cause)) return "UNKNOWN";
+	const code = (cause as { code?: unknown }).code;
+	return typeof code === "string" && /^[A-Z][A-Z0-9_]{0,31}$/.test(code) ? code : "UNKNOWN";
+}
+
+const ENUMERATION_OPERATION_LABELS: Readonly<Record<WorkspaceEnumerationOperation, string>> = Object.freeze({
+	"open-root": "open the workspace root",
+	"read-directory": "read a workspace directory",
+	"open-directory": "open a workspace directory",
+	"inspect-entry": "inspect a workspace entry",
+});
+
+/**
+ * Explicit failure for a non-Git scan whose filesystem view became incomplete.
+ * Only a bounded workspace-relative path and a validated system error code are
+ * retained; arbitrary filesystem error text is deliberately not propagated.
+ */
+export class WorkspaceEnumerationIncompleteError extends Error {
+	readonly code = "WORKSPACE_ENUMERATION_INCOMPLETE";
+	readonly operation: WorkspaceEnumerationOperation;
+	readonly path: string;
+	readonly causeCode: string;
+
+	constructor(operation: WorkspaceEnumerationOperation, path: string, cause: unknown) {
+		const diagnosticPath = boundedDiagnosticPath(path);
+		const causeCode = boundedSystemErrorCode(cause);
+		super(
+			`non-Git workspace enumeration could not ${ENUMERATION_OPERATION_LABELS[operation]} at '${diagnosticPath}' (${causeCode})`,
+		);
+		this.name = "WorkspaceEnumerationIncompleteError";
+		this.operation = operation;
+		this.path = diagnosticPath;
+		this.causeCode = causeCode;
+	}
+}
+
+/**
+ * Directories omitted even when Git tracks files beneath them. Git ignore
+ * rules complement this policy; they do not override it.
+ */
+export const WORKSPACE_EXCLUDED_DIRS: ReadonlySet<string> = new Set([
+	".git",
+	".hg",
+	".svn",
+	".clio-coder",
+	"node_modules",
+	"dist",
+	"build",
+	"coverage",
+	".venv",
+	"venv",
+	"__pycache__",
+	"target",
+	"vendor",
+	".superpowers",
+	".codex",
+	".claude",
+	".clio-coder-benchmark",
+]);
+
+function comparePaths(a: string, b: string): number {
+	return a === b ? 0 : a < b ? -1 : 1;
+}
+
+function normalizeRelativePath(path: string): string | null {
+	const posixPath = sep === "\\" ? path.replaceAll("\\", "/") : path;
+	const normalized = posixPath.replace(/^\.\//, "");
+	if (normalized.length === 0 || normalized.includes("\0") || normalized.startsWith("/")) return null;
+	if (/^[A-Za-z]:\//.test(normalized)) return null;
+	const segments = normalized.split("/");
+	if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) return null;
+	return segments.join("/");
+}
+
+function isWorkspacePathExcluded(
+	relPath: string,
+	excludedDirs: ReadonlySet<string> = WORKSPACE_EXCLUDED_DIRS,
+): boolean {
+	return relPath.split("/").some((segment) => excludedDirs.has(segment));
+}
+
+function isDisappearedWorkspaceEntry(cause: unknown): boolean {
+	if (typeof cause !== "object" || cause === null || !("code" in cause)) return false;
+	const code = (cause as { code?: unknown }).code;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+
+function isRegularWorkspaceFile(cwd: string, relPath: string, requireCompleteSnapshot: boolean): boolean {
+	try {
+		// lstat deliberately excludes symlinks. Gitlinks resolve to directories,
+		// so full scans do not enter submodules either.
+		const stat = fs.lstatSync(join(cwd, relPath));
+		if (stat.isFile()) return true;
+		if (requireCompleteSnapshot && stat.isDirectory()) {
+			// The fallback walker observed this path as a file. If it became a
+			// directory before validation, that directory may contain entries the
+			// completed walk never visited, so the snapshot is no longer complete.
+			throw new WorkspaceEnumerationIncompleteError("inspect-entry", relPath, { code: "ENTRY_TYPE_CHANGED" });
+		}
+		return false;
+	} catch (cause) {
+		if (cause instanceof WorkspaceEnumerationIncompleteError) throw cause;
+		if (requireCompleteSnapshot) {
+			// A vanished file (or an ancestor replaced by a non-directory) is no
+			// longer part of the workspace at validation time and may be omitted.
+			// Permission, I/O, and stale-handle errors leave its visibility unknown
+			// and must invalidate the complete non-Git snapshot.
+			if (isDisappearedWorkspaceEntry(cause)) return false;
+			throw new WorkspaceEnumerationIncompleteError("inspect-entry", relPath, cause);
+		}
+		return false;
+	}
+}
+
+function gitVisibleFilesArgs(candidates?: ReadonlyArray<string>): string[] {
+	const args = ["--literal-pathspecs", "ls-files", "-z", "--cached", "--others", "--exclude-standard"];
+	if (candidates) args.push("--", ...candidates);
+	return args;
+}
+
+function splitGitPathOutput(output: string): string[] {
+	return output.split("\0").filter((path) => path.length > 0);
+}
+
+function gitVisibleFiles(cwd: string, candidates?: ReadonlyArray<string>): string[] | null {
+	let output: Buffer;
+	try {
+		output = execFileSync("git", gitVisibleFilesArgs(candidates), {
+			cwd,
+			maxBuffer: GIT_OUTPUT_LIMIT_BYTES,
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+	} catch {
+		return null;
+	}
+	return splitGitPathOutput(output.toString("utf8"));
+}
+
+function gitVisibleFilesAsync(cwd: string, candidates?: ReadonlyArray<string>): Promise<string[] | null> {
+	return new Promise((resolve) => {
+		execFile("git", gitVisibleFilesArgs(candidates), { cwd, maxBuffer: GIT_OUTPUT_LIMIT_BYTES }, (error, stdout) => {
+			resolve(error ? null : splitGitPathOutput(stdout));
+		});
+	});
+}
+
+function resolveFallbackLimits(overrides: Partial<WorkspaceFallbackLimits> | undefined): WorkspaceFallbackLimits {
+	const limits = { ...DEFAULT_WORKSPACE_FALLBACK_LIMITS, ...overrides };
+	for (const [name, value] of Object.entries(limits)) {
+		if (!Number.isFinite(value) || value < 0 || !Number.isInteger(value)) {
+			throw new RangeError(`workspace fallback ${name} must be a non-negative integer`);
+		}
+	}
+	return limits;
+}
+
+interface WalkFrame {
+	dir: Dir;
+	absPath: string;
+	prefix: string;
+	depth: number;
+}
+
+type FallbackEntryKind = "directory" | "file" | "other" | "disappeared";
+
+function fallbackEntryKind(absPath: string, relPath: string, entry: ReturnType<Dir["readSync"]>): FallbackEntryKind {
+	if (!entry) return "disappeared";
+	if (entry.isDirectory()) return "directory";
+	if (entry.isFile()) return "file";
+	try {
+		// Some network and facility filesystems report DT_UNKNOWN. Inspect those
+		// entries rather than treating a potentially populated directory as a
+		// special file and silently omitting its subtree.
+		const stat = fs.lstatSync(absPath);
+		if (stat.isDirectory()) return "directory";
+		if (stat.isFile()) return "file";
+		return "other";
+	} catch (cause) {
+		if (isDisappearedWorkspaceEntry(cause)) return "disappeared";
+		throw new WorkspaceEnumerationIncompleteError("inspect-entry", relPath, cause);
+	}
+}
+
+function closeFrame(frame: WalkFrame): void {
+	try {
+		frame.dir.closeSync();
+	} catch {
+		// Best-effort cleanup after an unreadable directory or bounded failure.
+	}
+}
+
+/**
+ * The bounded walk as a step generator: one yield per processed entry, so a
+ * synchronous driver drains it in place and the async driver interleaves a
+ * cooperative tick between steps. One body means the two forms cannot drift on
+ * limit enforcement, symlink policy, or failure classification. `elapsedMs`
+ * feeds the time limit: the sync driver passes wall time, the async driver
+ * passes accumulated walk time so event-loop turns spent elsewhere do not
+ * count against the walk's own budget.
+ */
+function* fallbackFilesWalk(
+	cwd: string,
+	excludedDirs: ReadonlySet<string>,
+	limits: WorkspaceFallbackLimits,
+	elapsedMs: () => number,
+): Generator<void, string[]> {
+	let visitedEntries = 0;
+	let pathBytes = 0;
+	let root: Dir;
+	try {
+		root = fs.opendirSync(cwd);
+	} catch (cause) {
+		throw new WorkspaceEnumerationIncompleteError("open-root", ".", cause);
+	}
+	const stack: WalkFrame[] = [{ dir: root, absPath: cwd, prefix: "", depth: 0 }];
+	const files: string[] = [];
+	try {
+		while (stack.length > 0) {
+			yield;
+			if (elapsedMs() >= limits.maxDurationMs) {
+				throw new WorkspaceEnumerationLimitError("time", limits.maxDurationMs);
+			}
+			const frame = stack.at(-1);
+			if (!frame) break;
+			let entry: ReturnType<Dir["readSync"]>;
+			try {
+				entry = frame.dir.readSync();
+			} catch (cause) {
+				throw new WorkspaceEnumerationIncompleteError("read-directory", frame.prefix || ".", cause);
+			}
+			if (!entry) {
+				closeFrame(frame);
+				stack.pop();
+				continue;
+			}
+
+			visitedEntries += 1;
+			if (visitedEntries > limits.maxVisitedEntries) {
+				throw new WorkspaceEnumerationLimitError("entries", limits.maxVisitedEntries);
+			}
+			const depth = frame.depth + 1;
+			if (depth > limits.maxDepth) {
+				throw new WorkspaceEnumerationLimitError("depth", limits.maxDepth);
+			}
+			const relPath = frame.prefix.length > 0 ? `${frame.prefix}/${entry.name}` : entry.name;
+			pathBytes += Buffer.byteLength(relPath, "utf8");
+			if (pathBytes > limits.maxPathBytes) {
+				throw new WorkspaceEnumerationLimitError("path-bytes", limits.maxPathBytes);
+			}
+			const absPath = join(frame.absPath, entry.name);
+			const kind = fallbackEntryKind(absPath, relPath, entry);
+			if (kind === "disappeared" || kind === "other") continue;
+			if (kind === "directory") {
+				if (excludedDirs.has(entry.name)) continue;
+				let child: Dir;
+				try {
+					child = fs.opendirSync(absPath);
+				} catch (cause) {
+					if (isDisappearedWorkspaceEntry(cause)) continue;
+					throw new WorkspaceEnumerationIncompleteError("open-directory", relPath, cause);
+				}
+				stack.push({ dir: child, absPath, prefix: relPath, depth });
+				continue;
+			}
+			// Only direct or lstat-confirmed regular files reach this branch;
+			// symlinks and special files remain excluded, matching the Git path.
+			files.push(relPath);
+		}
+		return files;
+	} finally {
+		for (const frame of stack) closeFrame(frame);
+	}
+}
+
+function fallbackFiles(
+	cwd: string,
+	excludedDirs: ReadonlySet<string>,
+	overrides?: Partial<WorkspaceFallbackLimits>,
+): string[] {
+	const limits = resolveFallbackLimits(overrides);
+	const startedAt = performance.now();
+	const walk = fallbackFilesWalk(cwd, excludedDirs, limits, () => performance.now() - startedAt);
+	let step = walk.next();
+	while (!step.done) step = walk.next();
+	return step.value;
+}
+
+async function fallbackFilesAsync(
+	cwd: string,
+	excludedDirs: ReadonlySet<string>,
+	overrides: Partial<WorkspaceFallbackLimits> | undefined,
+	cooperate: WorkspaceEnumerationTick,
+): Promise<string[]> {
+	const limits = resolveFallbackLimits(overrides);
+	let activeMs = 0;
+	let resumedAt = performance.now();
+	const walk = fallbackFilesWalk(cwd, excludedDirs, limits, () => activeMs + (performance.now() - resumedAt));
+	let step = walk.next();
+	while (!step.done) {
+		activeMs += performance.now() - resumedAt;
+		await cooperate.tick();
+		resumedAt = performance.now();
+		step = walk.next();
+	}
+	return step.value;
+}
+
+/** Visibility validation as steps; one yield per path so the async driver can breathe. */
+function* normalizeVisibleFilesSteps(
+	cwd: string,
+	paths: ReadonlyArray<string>,
+	excludedDirs: ReadonlySet<string>,
+	requireCompleteSnapshot: boolean,
+): Generator<void, string[]> {
+	const visible = new Set<string>();
+	for (const path of paths) {
+		yield;
+		const normalized = normalizeRelativePath(path);
+		if (!normalized) {
+			if (requireCompleteSnapshot) {
+				throw new WorkspaceEnumerationIncompleteError("inspect-entry", path, { code: "INVALID_RELATIVE_PATH" });
+			}
+			continue;
+		}
+		if (isWorkspacePathExcluded(normalized, excludedDirs)) continue;
+		if (isRegularWorkspaceFile(cwd, normalized, requireCompleteSnapshot)) visible.add(normalized);
+	}
+	return [...visible].sort(comparePaths);
+}
+
+function normalizeVisibleFiles(
+	cwd: string,
+	paths: ReadonlyArray<string>,
+	excludedDirs: ReadonlySet<string>,
+	requireCompleteSnapshot = false,
+): string[] {
+	const steps = normalizeVisibleFilesSteps(cwd, paths, excludedDirs, requireCompleteSnapshot);
+	let step = steps.next();
+	while (!step.done) step = steps.next();
+	return step.value;
+}
+
+async function normalizeVisibleFilesAsync(
+	cwd: string,
+	paths: ReadonlyArray<string>,
+	excludedDirs: ReadonlySet<string>,
+	requireCompleteSnapshot: boolean,
+	cooperate: WorkspaceEnumerationTick,
+): Promise<string[]> {
+	const steps = normalizeVisibleFilesSteps(cwd, paths, excludedDirs, requireCompleteSnapshot);
+	let step = steps.next();
+	while (!step.done) {
+		await cooperate.tick();
+		step = steps.next();
+	}
+	return step.value;
+}
+
+/**
+ * List tracked files plus untracked, nonignored work in progress. Non-Git
+ * workspaces (and hosts without a usable Git binary) retain the filesystem
+ * walker behavior.
+ */
+export function enumerateWorkspaceFiles(
+	cwd: string,
+	excludedDirs: ReadonlySet<string> = WORKSPACE_EXCLUDED_DIRS,
+	fallbackLimits?: Partial<WorkspaceFallbackLimits>,
+): string[] {
+	const gitFiles = gitVisibleFiles(cwd);
+	if (gitFiles) return normalizeVisibleFiles(cwd, gitFiles, excludedDirs);
+	return normalizeVisibleFiles(cwd, fallbackFiles(cwd, excludedDirs, fallbackLimits), excludedDirs, true);
+}
+
+/**
+ * `enumerateWorkspaceFiles` without the synchronous floor: the `git ls-files`
+ * subprocess runs async, and both the per-path lstat validation and the
+ * non-Git fallback walk yield cooperatively. The bounded-walk contract is
+ * unchanged with one deliberate reading: the time limit meters the walk's own
+ * accumulated work rather than wall clock, so a busy event loop cannot fail an
+ * enumeration that did no more work than its budget allows.
+ */
+export async function enumerateWorkspaceFilesAsync(
+	cwd: string,
+	excludedDirs: ReadonlySet<string> = WORKSPACE_EXCLUDED_DIRS,
+	fallbackLimits?: Partial<WorkspaceFallbackLimits>,
+	cooperate: WorkspaceEnumerationTick = createDefaultTick(),
+): Promise<string[]> {
+	const gitFiles = await gitVisibleFilesAsync(cwd);
+	if (gitFiles) return normalizeVisibleFilesAsync(cwd, gitFiles, excludedDirs, false, cooperate);
+	const walked = await fallbackFilesAsync(cwd, excludedDirs, fallbackLimits, cooperate);
+	return normalizeVisibleFilesAsync(cwd, walked, excludedDirs, true, cooperate);
+}
+
+/** Apply the same visibility rules to one incremental batch without walking the tree. */
+export function filterWorkspaceFileCandidates(
+	cwd: string,
+	paths: ReadonlyArray<string>,
+	excludedDirs: ReadonlySet<string> = WORKSPACE_EXCLUDED_DIRS,
+	fallbackLimits?: Partial<WorkspaceFallbackLimits>,
+): string[] {
+	const candidates = paths
+		.map(normalizeRelativePath)
+		.filter((path): path is string => path !== null && !isWorkspacePathExcluded(path, excludedDirs));
+	if (candidates.length === 0) return [];
+	const gitFiles = gitVisibleFiles(cwd, candidates);
+	if (gitFiles) return normalizeVisibleFiles(cwd, gitFiles, excludedDirs);
+	// Outside Git, incremental candidates must be reconciled against the same
+	// complete bounded snapshot as a full build. Otherwise a notification can
+	// add a path that a bounded full scan could not authoritatively enumerate.
+	const fallbackVisible = new Set(
+		normalizeVisibleFiles(cwd, fallbackFiles(cwd, excludedDirs, fallbackLimits), excludedDirs, true),
+	);
+	return candidates.filter((path) => fallbackVisible.has(path)).sort(comparePaths);
+}