@iowarp/clio-coder 0.3.6 → 0.3.8

package/src/domains/resources/prompts/loader.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import { parseCommandArgs, substituteArgs } from "../../../engine/prompt-templates.js";
@@ -13,7 +13,6 @@ import {
 import {
 	COMPAT_RESOURCE_PRECEDENCE,
 	defaultScopedResourceRoots,
-	readRootEntries,
 	sourceInfoForRoot,
 	splitYamlFrontmatter,
 	stringField,
@@ -33,6 +32,8 @@ export interface PromptTemplate {
 
 export interface PromptTemplateRoot {
 	path: string;
+	/** Present only for an installed extension resource root. */
+	rootPath?: string;
 	scope: ResourceScope;
 	source?: string;
 	precedence?: number;
@@ -139,6 +140,61 @@ function fallbackDescription(body: string): string {
 	return normalized.length > 60 ? `${normalized.slice(0, 57)}...` : normalized;
 }
 
+// Keep the suffix deliberately conservative. Prompt prose commonly places a
+// comma, parenthesis, or full stop immediately after an @path; treating that
+// punctuation as part of the filesystem reference makes a valid template look
+// unresolved. Extension bundles use portable path components, so these are the
+// only characters needed in a reference while still allowing `..` to be
+// detected and rejected by the containment check below.
+const EXTENSION_ROOT_REFERENCE = /\$\{extensionRoot\}(\/[A-Za-z0-9._~%+@/-]*)?/g;
+const EXTENSION_ROOT_TOKEN = "$" + "{extensionRoot}";
+
+function contained(root: string, candidate: string): boolean {
+	const relative = path.relative(root, candidate);
+	return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+/** Resolve only existing paths contained by the declaring extension package. */
+function resolveExtensionReferences(
+	body: string,
+	root: PromptTemplateRoot,
+	filePath: string,
+	diagnostics: ResourceDiagnostic[],
+): string | null {
+	if (root.rootPath === undefined || !body.includes(EXTENSION_ROOT_TOKEN)) return body;
+	let canonicalRoot: string;
+	try {
+		canonicalRoot = realpathSync(root.rootPath);
+	} catch (error) {
+		diagnostics.push({
+			type: "warning",
+			message: `extension root could not be resolved: ${error instanceof Error ? error.message : String(error)}`,
+			path: filePath,
+		});
+		return null;
+	}
+	let invalid: string | null = null;
+	const resolved = body.replace(EXTENSION_ROOT_REFERENCE, (reference, suffix: string | undefined) => {
+		const candidate = path.resolve(canonicalRoot, `.${suffix ?? ""}`);
+		try {
+			const canonicalCandidate = realpathSync(candidate);
+			if (!contained(canonicalRoot, canonicalCandidate)) invalid = reference;
+		} catch {
+			invalid = reference;
+		}
+		return candidate;
+	});
+	if (invalid !== null) {
+		diagnostics.push({
+			type: "warning",
+			message: `prompt template has an unresolved or escaping extension reference: ${invalid}`,
+			path: filePath,
+		});
+		return null;
+	}
+	return resolved;
+}
+
 function loadPromptFile(
 	filePath: string,
 	root: PromptTemplateRoot,
@@ -155,16 +211,28 @@ function loadPromptFile(
 		return null;
 	}
 
-	const name = path.basename(filePath, ext);
+	const relativePath = path.relative(root.path, filePath);
+	if (
+		relativePath === "" ||
+		relativePath === ".." ||
+		relativePath.startsWith(`..${path.sep}`) ||
+		path.isAbsolute(relativePath)
+	) {
+		diagnostics.push({ type: "warning", message: "prompt template escaped its discovery root", path: filePath });
+		return null;
+	}
+	const name = relativePath.slice(0, -ext.length).split(path.sep).join(":");
 	if (name.trim().length === 0) return null;
 	const { frontmatter, body } = splitOptionalFrontmatter(raw, filePath, diagnostics);
-	const description = stringField(frontmatter, "description") ?? fallbackDescription(body);
+	const resolvedBody = resolveExtensionReferences(body, root, filePath, diagnostics);
+	if (resolvedBody === null) return null;
+	const description = stringField(frontmatter, "description") ?? fallbackDescription(resolvedBody);
 	const argumentHint = stringField(frontmatter, "argument-hint") ?? stringField(frontmatter, "argumentHint");
 	const sourceInfo: ResourceSourceInfo = sourceInfoForRoot(root, filePath);
 	const template: PromptTemplate = {
 		name,
 		description,
-		content: body.trim(),
+		content: resolvedBody.trim(),
 		filePath,
 		sourceInfo,
 		trusted: root.trusted !== false,
@@ -178,10 +246,42 @@ function loadPromptRoot(
 	diagnostics: ResourceDiagnostic[],
 ): ResourceCandidate<PromptTemplate>[] {
 	const candidates: ResourceCandidate<PromptTemplate>[] = [];
-	for (const entry of readRootEntries(root, "prompt template", diagnostics)) {
-		if (!entry.isFile()) continue;
-		const candidate = loadPromptFile(path.join(root.path, entry.name), root, diagnostics);
-		if (candidate) candidates.push(candidate);
+	const pending = [root.path];
+	while (pending.length > 0) {
+		const directory = pending.pop();
+		if (!directory) continue;
+		let entries: import("node:fs").Dirent[];
+		try {
+			const stat = lstatSync(directory);
+			if (stat.isSymbolicLink() || !stat.isDirectory()) {
+				diagnostics.push({
+					type: "warning",
+					message: "prompt template root contains a non-directory or symbolic link",
+					path: directory,
+				});
+				continue;
+			}
+			entries = readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+			diagnostics.push({
+				type: "warning",
+				message: `prompt template directory could not be read: ${error instanceof Error ? error.message : String(error)}`,
+				path: directory,
+			});
+			continue;
+		}
+		for (const entry of [...entries].reverse()) {
+			const filePath = path.join(directory, entry.name);
+			if (entry.isSymbolicLink()) {
+				diagnostics.push({ type: "warning", message: "prompt template symbolic link was ignored", path: filePath });
+			} else if (entry.isDirectory()) {
+				pending.push(filePath);
+			} else if (entry.isFile()) {
+				const candidate = loadPromptFile(filePath, root, diagnostics);
+				if (candidate) candidates.push(candidate);
+			}
+		}
 	}
 	return candidates;
 }
@@ -210,13 +310,18 @@ export function loadPromptTemplates(input: LoadPromptTemplatesInput = {}): Promp
 }
 
 function parsePromptCommand(input: string): { name: string; rest: string } | null {
-	const trimmed = input.trim();
-	if (!trimmed.startsWith("/")) return null;
-	const withoutSlash = trimmed.slice(1);
+	const framed = input.trimStart();
+	if (!framed.startsWith("/")) return null;
+	const withoutSlash = framed.slice(1);
 	const separator = withoutSlash.search(/\s/);
 	const name = separator === -1 ? withoutSlash : withoutSlash.slice(0, separator);
 	if (name.length === 0 || name.includes("/")) return null;
-	const rest = separator === -1 ? "" : withoutSlash.slice(separator).trim();
+	// Leading whitespace before `/` and the first whitespace after the command
+	// are framing. A CRLF pair is one delimiter. Every subsequent byte belongs
+	// to the argument payload, including indentation, blank lines, and trailing
+	// whitespace, so raw `$ARGUMENTS` substitution can be exact at its boundary.
+	const delimiterWidth = separator !== -1 && withoutSlash.slice(separator, separator + 2) === "\r\n" ? 2 : 1;
+	const rest = separator === -1 ? "" : withoutSlash.slice(separator + delimiterWidth);
 	return { name, rest };
 }
 
@@ -238,7 +343,7 @@ export function expandPromptTemplateInput(input: string, templates: PromptTempla
 	const args = parseCommandArgs(command.rest);
 	return {
 		expanded: true,
-		text: substituteArgs(template.content, args),
+		text: substituteArgs(template.content, args, command.rest),
 		args,
 		template,
 		diagnostics: templates.diagnostics,

package/src/domains/resources/skills/marketplace.ts

@@ -35,6 +35,8 @@ import { loadSkills, type Skill } from "./loader.js";
  */
 
 export type MarketplaceSkillOrigin = "catalog" | "index";
+export type LibraryEntryKind = "skill" | "agent" | "prompt" | "fleet";
+export type LibraryRequirementRef = `${LibraryEntryKind}:${string}`;
 
 /**
  * The diagnostic that means "nothing is wrong, nothing is configured". Callers
@@ -44,6 +46,7 @@ export type MarketplaceSkillOrigin = "catalog" | "index";
 export const MARKETPLACE_UNCONFIGURED = "no local skill marketplace catalog or index configured";
 
 export interface MarketplaceSkill {
+	kind: LibraryEntryKind;
 	name: string;
 	description: string;
 	/** Local path or URL accepted by `clio-coder skills install`. */
@@ -53,6 +56,7 @@ export interface MarketplaceSkill {
 	/** Catalog grouping ("git", "research", ...); absent in a flat catalog. */
 	category?: string;
 	origin: MarketplaceSkillOrigin;
+	requires?: LibraryRequirementRef[];
 }
 
 export type MarketplaceStatus = "installed" | "installable" | "unavailable";
@@ -131,7 +135,7 @@ function indexAudit(value: unknown): MarketplaceSkill["audit"] {
 	return value === "pass" || value === "warn" || value === "fail" || value === "unknown" ? value : undefined;
 }
 
-function indexSkills(indexPath: string, diagnostics: string[]): MarketplaceSkill[] {
+function parseMarketplaceIndex(indexPath: string, diagnostics: string[] = []): MarketplaceSkill[] {
 	try {
 		const parsed = JSON.parse(readFileSync(indexPath, "utf8")) as unknown;
 		const rawSkills = Array.isArray(parsed)
@@ -139,7 +143,7 @@ function indexSkills(indexPath: string, diagnostics: string[]): MarketplaceSkill
 			: parsed && typeof parsed === "object" && Array.isArray((parsed as { skills?: unknown }).skills)
 				? (parsed as { skills: unknown[] }).skills
 				: [];
-		return rawSkills.filter(isIndexSkill).map((skill) => {
+		return rawSkills.filter(isIndexSkill).flatMap((skill): MarketplaceSkill[] => {
 			const record = skill as unknown as Record<string, unknown>;
 			// Version, audit and category are published by `npm run skills:pin`.
 			// They are advisory display metadata; an index entry stays installable
@@ -147,15 +151,35 @@ function indexSkills(indexPath: string, diagnostics: string[]): MarketplaceSkill
 			const version = optionalString(record.version);
 			const audit = indexAudit(record.audit);
 			const category = optionalString(record.category);
-			return {
-				name: skill.name.trim(),
-				description: skill.description.trim(),
-				sourceUrl: skill.sourceUrl.trim(),
-				...(version ? { version } : {}),
-				...(audit ? { audit } : {}),
-				...(category ? { category } : {}),
-				origin: "index" as const,
-			};
+			if (record.kind !== undefined && !["skill", "agent", "prompt", "fleet"].includes(String(record.kind))) {
+				diagnostics.push(`skill marketplace index entry has unsupported kind: ${skill.name}`);
+				return [];
+			}
+			if (
+				record.requires !== undefined &&
+				(!Array.isArray(record.requires) || record.requires.some((entry) => typeof entry !== "string"))
+			) {
+				diagnostics.push(`library_requirement_malformed: ${skill.name}`);
+				return [];
+			}
+			const kind: LibraryEntryKind =
+				record.kind === "agent" || record.kind === "prompt" || record.kind === "fleet" ? record.kind : "skill";
+			const requires = Array.isArray(record.requires)
+				? record.requires.filter((entry): entry is LibraryRequirementRef => typeof entry === "string")
+				: undefined;
+			return [
+				{
+					kind,
+					name: skill.name.trim(),
+					description: skill.description.trim(),
+					sourceUrl: skill.sourceUrl.trim(),
+					...(version ? { version } : {}),
+					...(audit ? { audit } : {}),
+					...(category ? { category } : {}),
+					...(requires ? { requires } : {}),
+					origin: "index" as const,
+				},
+			];
 		});
 	} catch (err) {
 		diagnostics.push(`skill marketplace index unreadable: ${err instanceof Error ? err.message : String(err)}`);
@@ -226,6 +250,7 @@ function catalogEntry(skill: Skill, catalogDir: string): MarketplaceSkill {
 		...(skill.provenance?.audit ? { audit: skill.provenance.audit } : {}),
 		...(category ? { category } : {}),
 		origin: "catalog",
+		kind: "skill",
 	};
 }
 
@@ -256,7 +281,7 @@ export function discoverMarketplaceSkills(options: DiscoverMarketplaceOptions =
 		options.indexPath === null ? null : (options.indexPath ?? process.env.CLIO_CODER_SKILL_MARKETPLACE_INDEX ?? null);
 	const resolvedIndexPath = indexPath ?? defaultIndexPath();
 	if (options.indexPath !== null && resolvedIndexPath && existsSync(resolvedIndexPath)) {
-		for (const skill of indexSkills(resolvedIndexPath, diagnostics)) {
+		for (const skill of parseMarketplaceIndex(resolvedIndexPath, diagnostics)) {
 			if (seen.has(skill.name)) continue;
 			seen.add(skill.name);
 			skills.push(skill);

package/src/domains/safety/policy-engine.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { artifactDefaultPath } from "../../core/artifact-paths.js";
+import { pathBoundaryCovers, resolvePathBoundary } from "../../core/path-boundary.js";
 import { canonicalizeExistingPath } from "../../core/path-canonical.js";
 import { ToolNames } from "../../core/tool-names.js";
 import { clioConfigDir } from "../../core/xdg.js";
@@ -89,7 +90,8 @@ export interface SafetyPolicyEngineOptions {
 	rulePacks?: RulePacks;
 	projectPolicy?: LoadedProjectSafetyPolicy;
 	/**
-	 * Absolute directories a write-class tool call is confined to for this run.
+	 * Absolute path boundaries a write-class tool call is confined to for this run.
+	 * Exact files omit a trailing slash and subtrees retain one.
 	 * When present and non-empty, a write/edit target outside every root is a
 	 * final BLOCK (reason code "write-root"). Empty or absent disables the check.
 	 * Enforced at the worker safety seam so both the native worker registry and
@@ -182,9 +184,7 @@ function evaluateWriteRoots(roots: ReadonlyArray<string>, writeRootCwd: string,
 	const target = writeRootTargetPath(call);
 	if (target === null) return null;
 	const resolved = path.resolve(writeRootCwd, target);
-	for (const root of roots) {
-		if (resolved === root || resolved.startsWith(`${root}${path.sep}`)) return null;
-	}
+	if (pathBoundaryCovers(roots, resolved)) return null;
 	return `write target '${target}' resolves to '${resolved}', which is outside the permitted write roots for this run: ${roots.join(", ")}`;
 }
 
@@ -193,7 +193,7 @@ export function createSafetyPolicyEngine(options: SafetyPolicyEngineOptions = {}
 	// Write-root containment resolves lexically, so it keeps its own un-canonicalized
 	// cwd and roots to compare like against like (the design mandates no symlink chasing).
 	const writeRootCwd = path.resolve(options.cwd ?? process.cwd());
-	const writeRoots = (options.writeRoots ?? []).map((root) => path.resolve(root));
+	const writeRoots = (options.writeRoots ?? []).map((root) => resolvePathBoundary(writeRootCwd, root));
 	const packs = options.rulePacks ?? getCachedDefaultRulePacks();
 	const projectPolicy = options.projectPolicy ?? loadProjectSafetyPolicy(cwd);
 	const projectPolicyRoot =

package/src/domains/safety/run-effects.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { ToolNames } from "../../core/tool-names.js";
+import { classify } from "./action-classifier.js";
 import { typedValidationSummary } from "./finish-contract.js";
 import {
 	detectValidationCommand,
@@ -25,6 +26,13 @@ import {
  * bash command that writes through a script) leaves the path absent from the
  * set and the validator falls back to the filesystem rather than to a failed
  * conformance.
+ *
+ * `writeRecordComplete` is the other half of that sentence, and it exists for
+ * the reader that cannot fall back to the filesystem. The write boundary uses
+ * this record the other way round, to decide that a path the run did *not*
+ * write is somebody else's and must survive. Reading an under-reporting set as
+ * a closed list would clear a step of a write it really made, so the recorder
+ * says outright whether the set is closed.
  */
 export interface RunEffects {
 	/** Absolute paths the run's successful tool calls aimed a mutation at. */
@@ -56,6 +64,18 @@ export interface RunEffects {
 	 * wider set.
 	 */
 	verificationCommands: ReadonlySet<string>;
+	/**
+	 * False once the run made a successful call to a tool that can mutate a path
+	 * its own arguments do not name. After such a call `mutatedPaths` is a lower
+	 * bound rather than the whole list, so a reader that would treat an absent
+	 * path as proof the run did not write it has to stop treating it that way.
+	 *
+	 * The downgrade covers the whole run rather than the one call, because an
+	 * opaque call's effect is unbounded. A shell command, a project script, or a
+	 * spawned worker can write anywhere the process can reach, so once one has
+	 * run there is no path left in the checkout that the record can clear.
+	 */
+	writeRecordComplete: boolean;
 }
 
 export interface RunEffectsRecorder {
@@ -70,6 +90,39 @@ interface PendingEffects {
 	paths: ReadonlyArray<string>;
 	validationCommand: string | null;
 	verificationCommand: string | null;
+	opaque: boolean;
+}
+
+/**
+ * Action classes whose successful calls write only paths their own arguments
+ * name. `read` covers the observe, retrieve, interact, and orchestrate-bookkeeping
+ * tools, none of which touch a source-workspace file: `git` is a closed
+ * status/diff/log surface, and `tasks`, `ledger`, and `context` write Clio's own
+ * state. `write` covers `write`, `edit`, and `artifact`, whose target
+ * `toolMutationPaths` resolves from the call itself, including the artifact
+ * tool's default path.
+ */
+const ENUMERABLE_ACTION_CLASSES: ReadonlySet<string> = new Set(["read", "write"]);
+
+/**
+ * Whether a successful call to this tool can mutate a path its own recorded
+ * arguments do not name.
+ *
+ * Asked of the classifier rather than of a hand-written list, because
+ * `src/tools/policy.ts` asserts at bootstrap that every registered tool's
+ * `baseActionClass` equals what this classifier returns and what the plane
+ * table declares. A tool added to the execute or orchestrate-dispatch plane is
+ * therefore opaque the day it is registered, with no list to remember to update.
+ *
+ * The classifier is asked about the tool name alone. Bash's argument scan can
+ * escalate a single call to `system_modify` or `git_destructive`, and those are
+ * still bash; the question here is what the tool can do, not what one call was
+ * caught doing. An unregistered name (a dynamic or MCP tool) classifies as
+ * `unknown` and is opaque, which is the fail-closed answer for a tool whose
+ * arguments this process has no schema for.
+ */
+export function toolWritesOpaquely(toolName: string): boolean {
+	return !ENUMERABLE_ACTION_CLASSES.has(classify({ tool: toolName }).actionClass);
 }
 
 /**
@@ -157,18 +210,23 @@ export function createRunEffectsRecorder(cwd: string): RunEffectsRecorder {
 	const failedMutationPaths = new Set<string>();
 	const validationCommands = new Set<string>();
 	const verificationCommands = new Set<string>();
+	let opaqueWriteObserved = false;
 	return {
 		start(toolCallId, toolName, args) {
 			const paths = mutationTargets(toolName, args);
 			const validationCommand = validationCommandOf(toolName, args, "finish-contract");
 			const verificationCommand = validationCommandOf(toolName, args, "grounding");
-			if (paths.length === 0 && validationCommand === null && verificationCommand === null) return;
+			const opaque = toolWritesOpaquely(toolName);
+			// An opaque call is tracked even when it exposed no path and no
+			// command, because the fact that it ran at all is the finding.
+			if (!opaque && paths.length === 0 && validationCommand === null && verificationCommand === null) return;
 			// A bash call may re-base its relative paths with its own cwd argument.
 			const base = typeof args?.cwd === "string" && args.cwd.length > 0 ? path.resolve(cwd, args.cwd) : cwd;
 			pending.set(toolCallId, {
 				paths: paths.map((target) => path.resolve(base, target)),
 				validationCommand,
 				verificationCommand,
+				opaque,
 			});
 		},
 		finish(toolCallId, failed) {
@@ -179,6 +237,10 @@ export function createRunEffectsRecorder(cwd: string): RunEffectsRecorder {
 				for (const target of effects.paths) failedMutationPaths.add(target);
 				return;
 			}
+			// Success-gated on purpose. A shell command the safety policy blocked,
+			// or one that came back an error, never reached the filesystem, so it
+			// leaves the record closed.
+			if (effects.opaque) opaqueWriteObserved = true;
 			for (const target of effects.paths) mutatedPaths.add(target);
 			if (effects.validationCommand !== null) validationCommands.add(effects.validationCommand);
 			if (effects.verificationCommand !== null) verificationCommands.add(effects.verificationCommand);
@@ -191,6 +253,7 @@ export function createRunEffectsRecorder(cwd: string): RunEffectsRecorder {
 				failedMutationPaths: new Set([...failedMutationPaths].filter((target) => !mutatedPaths.has(target))),
 				validationCommands: new Set(validationCommands),
 				verificationCommands: new Set(verificationCommands),
+				writeRecordComplete: !opaqueWriteObserved,
 			};
 		},
 	};

package/src/domains/safety/scope.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { asDirectoryPathBoundary, pathBoundaryEntryCovers, resolvePathBoundary } from "../../core/path-boundary.js";
 import type { ActionClass } from "./action-classifier.js";
 
 /**
@@ -15,15 +16,7 @@ export interface ScopeSpec {
 }
 
 function normalizeRoot(root: string): string {
-	return path.resolve(root);
-}
-
-function isUnder(child: string, parent: string): boolean {
-	const c = normalizeRoot(child);
-	const p = normalizeRoot(parent);
-	if (c === p) return true;
-	const rel = path.relative(p, c);
-	return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+	return resolvePathBoundary(process.cwd(), root);
 }
 
 export function isSubset(worker: ScopeSpec, orchestrator: ScopeSpec): boolean {
@@ -31,7 +24,9 @@ export function isSubset(worker: ScopeSpec, orchestrator: ScopeSpec): boolean {
 		if (!orchestrator.allowedActions.has(action)) return false;
 	}
 	for (const root of worker.allowedWriteRoots) {
-		const covered = orchestrator.allowedWriteRoots.some((outer) => isUnder(root, outer));
+		const covered = orchestrator.allowedWriteRoots.some((outer) =>
+			pathBoundaryEntryCovers(normalizeRoot(outer), normalizeRoot(root)),
+		);
 		if (!covered) return false;
 	}
 	if (worker.allowNetwork && !orchestrator.allowNetwork) return false;
@@ -48,14 +43,14 @@ export const READONLY_SCOPE: ScopeSpec = {
 
 export const WORKSPACE_SCOPE: ScopeSpec = {
 	allowedActions: new Set<ActionClass>(["read", "write", "execute", "dispatch"]),
-	allowedWriteRoots: [process.cwd()],
+	allowedWriteRoots: [asDirectoryPathBoundary(path.resolve(process.cwd()))],
 	allowNetwork: true,
 	allowDispatch: true,
 };
 
 export const CONFIRMED_SCOPE: ScopeSpec = {
 	allowedActions: new Set<ActionClass>(["read", "write", "execute", "dispatch", "system_modify"]),
-	allowedWriteRoots: [process.cwd()],
+	allowedWriteRoots: [asDirectoryPathBoundary(path.resolve(process.cwd()))],
 	allowNetwork: true,
 	allowDispatch: true,
 };