@iowarp/clio-coder 0.4.2 → 0.4.3

package/src/domains/safety/protected-artifacts.ts

@@ -74,8 +74,18 @@ interface NormalizedArtifact {
 	artifact: ProtectedArtifact;
 }
 
-const COMMAND_SEPARATORS = new Set([";", "&&", "||", "|"]);
+const COMMAND_SEPARATORS = new Set([";", "&", "&&", "||", "|"]);
 const SHELL_WRAPPERS = new Set(["command", "builtin", "sudo", "doas"]);
+const SHELL_REDIRECTIONS = new Set([">", ">>", "<", "<<", "<<<", "<&", ">&", "<>", ">|", "&>", "&>>"]);
+const SHELL_WRITE_REDIRECTIONS = new Set([">", ">>", ">&", "<>", ">|", "&>", "&>>"]);
+
+export interface ShellToken {
+	value: string;
+	operator: boolean;
+	quoted: boolean;
+	start: number;
+	end: number;
+}
 
 /**
  * Paths a tool call would mutate, derived from the tool's path argument.
@@ -149,9 +159,9 @@ function classifyDestructiveCommand(
 	const artifacts = normalizedArtifacts(protectedArtifacts);
 	if (artifacts.length === 0) return { kind: "benign", matches: [] };
 
-	const tokens = tokenizeShellLike(command);
-	for (const segment of splitSegments(tokens)) {
-		const redirect = classifyRedirect(segment, artifacts);
+	for (const tokens of splitSegments(scanShellLike(command))) {
+		const segment = shellCommandArguments(tokens);
+		const redirect = classifyRedirect(tokens, artifacts);
 		if (redirect.kind === "destructive") return redirect;
 
 		const commandIndex = commandTokenIndex(segment);
@@ -217,8 +227,8 @@ export function detectValidationCommand(
 	command: string,
 	scope: ValidationCommandScope = "finish-contract",
 ): ValidationCommandDetection {
-	const tokens = tokenizeShellLike(command);
-	for (const segment of splitSegments(tokens)) {
+	for (const tokens of splitSegments(scanShellLike(command))) {
+		const segment = shellCommandArguments(tokens);
 		const commandIndex = commandTokenIndex(segment);
 		if (commandIndex === null) continue;
 		const executable = basenameToken(segment[commandIndex]);
@@ -248,10 +258,11 @@ export function detectValidationCommand(
  */
 export function extractCommandWriteTargets(command: string): string[] {
 	const targets: string[] = [];
-	for (const segment of expandedSegments(command)) {
+	for (const segment of expandedShellSegments(command)) {
 		collectRedirectTargets(segment, targets);
-		collectInvokedWriteTargets(segment, targets);
-		collectInPlaceEditTargets(segment, targets);
+		const argv = shellCommandArguments(segment);
+		collectInvokedWriteTargets(argv, targets);
+		collectInPlaceEditTargets(argv, targets);
 	}
 	return targets.filter(isInterestingWriteTarget);
 }
@@ -295,14 +306,14 @@ function segmentShellScript(segment: ReadonlyArray<string>): string | null {
  * segments of the script it runs. The wrapper segment itself is kept: a
  * scanner that reads its operands (`cp`, `tee`) must still see them.
  */
-function expandedSegments(command: string, depth = 0): string[][] {
-	const segments = splitSegments(tokenizeShellLike(command));
+function expandedShellSegments(command: string, depth = 0): ShellToken[][] {
+	const segments = splitSegments(scanShellLike(command));
 	if (depth >= INNER_SHELL_MAX_DEPTH) return segments;
-	const out: string[][] = [];
+	const out: ShellToken[][] = [];
 	for (const segment of segments) {
 		out.push(segment);
-		const script = segmentShellScript(segment);
-		if (script !== null) out.push(...expandedSegments(script, depth + 1));
+		const script = segmentShellScript(shellCommandArguments(segment));
+		if (script !== null) out.push(...expandedShellSegments(script, depth + 1));
 	}
 	return out;
 }
@@ -313,11 +324,11 @@ function expandedSegments(command: string, depth = 0): string[][] {
  * script rather than treating `sh` as an unrecognized executable.
  */
 export function inlineShellScript(command: string): string | null {
-	const segments = splitSegments(tokenizeShellLike(command));
+	const segments = splitSegments(scanShellLike(command));
 	if (segments.length !== 1) return null;
 	const segment = segments[0];
 	if (segment === undefined) return null;
-	return segmentShellScript(segment);
+	return segmentShellScript(shellCommandArguments(segment));
 }
 
 /**
@@ -331,7 +342,8 @@ export function inlineShellScript(command: string): string | null {
  */
 export function extractCommandCdTargets(command: string): string[] {
 	const targets: string[] = [];
-	for (const segment of expandedSegments(command)) {
+	for (const tokens of expandedShellSegments(command)) {
+		const segment = shellCommandArguments(tokens);
 		const commandIndex = commandTokenIndex(segment);
 		if (commandIndex === null) continue;
 		const executable = basenameToken(segment[commandIndex]);
@@ -349,7 +361,8 @@ export function extractCommandCdTargets(command: string): string[] {
  */
 export function extractCommandDeleteTargets(command: string): string[] {
 	const targets: string[] = [];
-	for (const segment of expandedSegments(command)) {
+	for (const tokens of expandedShellSegments(command)) {
+		const segment = shellCommandArguments(tokens);
 		const commandIndex = commandTokenIndex(segment);
 		if (commandIndex === null) continue;
 		const executable = basenameToken(segment[commandIndex]);
@@ -369,17 +382,108 @@ export function extractCommandDeleteTargets(command: string): string[] {
 	return targets.filter(isInterestingWriteTarget);
 }
 
+/** Recognizable operator CLI installation paths invoked through a model shell.
+ * This is command inspection, not confinement of arbitrary scripts or aliases.
+ */
+export function invokesClioSkillMutation(command: string): boolean {
+	for (const segment of expandedShellSegments(command)) {
+		const argv = shellCommandArguments(segment);
+		const index = commandTokenIndex(argv);
+		if (index === null) continue;
+		let args = argv.slice(index);
+		const executable = basenameToken(args[0]);
+		if (executable === "npx" || (executable === "npm" && args[1] === "exec")) {
+			args = args.slice(executable === "npm" ? 2 : 1);
+			while (args[0]?.startsWith("-")) args = args.slice(1);
+		}
+		const program = args[0] ?? "";
+		if (basenameToken(program) === "node" || basenameToken(program) === "tsx") {
+			// The checked-in and built entry points are also operator CLIs.
+			if (!/(?:^|\/)(?:src|dist)\/cli\/index\.(?:js|ts)$/.test(args[1] ?? "")) continue;
+			args = args.slice(2);
+		} else if (/^(?:@iowarp\/)?clio-coder(?:@[^/]+)?$/.test(program) || basenameToken(program) === "clio-coder") {
+			args = args.slice(1);
+		} else continue;
+		if (args.includes("--version") || args.includes("-v")) continue;
+		let rootHelp = false;
+		let firstRootFlag: string | undefined;
+		while (args[0]?.startsWith("-")) {
+			const flag = args[0];
+			// Startup flags are consumed before dispatch. Help is terminal only
+			// when it is the first flag left in the root dispatcher's argv.
+			if (flag === "--all" || flag === "--help" || flag === "-h") firstRootFlag ??= flag;
+			rootHelp = firstRootFlag === "--help" || firstRootFlag === "-h";
+			args = args.slice(flag === "--skill" || flag === "--api-key" ? 2 : 1);
+		}
+		if (rootHelp) continue;
+		if (args[0] !== "skills" && args[0] !== "library") continue;
+		if (resourceCliMutatesSkills(args[0], args.slice(1))) return true;
+	}
+	return false;
+}
+
+function shellCommandArguments(segment: ReadonlyArray<ShellToken>): string[] {
+	const args: ShellToken[] = [];
+	for (let index = 0; index < segment.length; index += 1) {
+		const token = segment[index];
+		if (token === undefined) continue;
+		if (token.operator && SHELL_REDIRECTIONS.has(token.value)) {
+			// A redirection target is consumed by the shell, not passed to Clio.
+			// Only an adjacent, unquoted number is its optional file descriptor.
+			const previous = args.at(-1);
+			if (previous && previous.end === token.start && !previous.quoted && /^\d+$/.test(previous.value)) args.pop();
+			if (segment[index + 1]?.operator === false) index += 1;
+			continue;
+		}
+		args.push(token);
+	}
+	return args.map((token) => token.value);
+}
+
+function resourceCliMutatesSkills(resource: "skills" | "library", args: ReadonlyArray<string>): boolean {
+	// Both resource parsers accept flags before the verb. Consume their value
+	// options so a catalog path called --yes or --help is not treated as a flag.
+	const valueOptions =
+		resource === "skills"
+			? ["--name", "--category", "--scenario", "--target", "--workspace", "--timeout"]
+			: ["--kind", "--from"];
+	let verb: string | undefined;
+	let confirmed = false;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === undefined) continue;
+		if (valueOptions.includes(arg)) {
+			index += 1;
+			continue;
+		}
+		if (arg === "--help" || arg === "-h") return false;
+		if (arg === "--yes") confirmed = true;
+		if (!arg.startsWith("-")) verb ??= arg;
+	}
+	if (resource === "skills") return verb === "install" || verb === "update" || verb === "sync";
+	// Unconfirmed library add only prints a plan. A confirmed add can install
+	// skill dependencies of any resource kind, or resolve an untyped skill ref.
+	return verb === "add" && confirmed;
+}
+
 const STANDARD_DEV_TARGETS = new Set(["/dev/null", "/dev/stdout", "/dev/stderr", "/dev/tty", "/dev/zero"]);
 
-function collectRedirectTargets(segment: ReadonlyArray<string>, out: string[]): void {
+function collectRedirectTargets(segment: ReadonlyArray<ShellToken>, out: string[]): void {
 	for (let index = 0; index < segment.length - 1; index += 1) {
-		const token = segment[index];
-		if (token !== ">" && token !== ">>") continue;
-		const target = segment[index + 1];
-		if (target !== undefined) out.push(target);
+		const target = redirectWriteTarget(segment[index], segment[index + 1]);
+		if (target !== null) out.push(target);
 	}
 }
 
+function redirectWriteTarget(operator: ShellToken | undefined, target: ShellToken | undefined): string | null {
+	if (!operator?.operator || target === undefined || target.operator || !SHELL_WRITE_REDIRECTIONS.has(operator.value))
+		return null;
+	// >& duplicates or closes a descriptor when its operand is a number or -;
+	// Bash also accepts a filename here, redirecting stdout and stderr to it.
+	if (operator.value === ">&" && /^(?:\d+-?|-)$/u.test(target.value)) return null;
+	return target.value;
+}
+
 function collectInvokedWriteTargets(segment: ReadonlyArray<string>, out: string[]): void {
 	const cmdIndex = commandTokenIndex(segment);
 	if (cmdIndex === null) return;
@@ -430,7 +534,6 @@ function hasSedInPlaceFlag(segment: ReadonlyArray<string>, cmdIndex: number): bo
 	for (let index = cmdIndex + 1; index < segment.length; index += 1) {
 		const token = segment[index];
 		if (token === undefined) continue;
-		if (COMMAND_SEPARATORS.has(token)) break;
 		if (token === "--") break;
 		if (token === "--in-place" || token.startsWith("--in-place=")) return true;
 		if (token.startsWith("--")) continue;
@@ -453,7 +556,6 @@ function sedFileOperands(segment: ReadonlyArray<string>, cmdIndex: number): stri
 	for (let index = cmdIndex + 1; index < segment.length; index += 1) {
 		const token = segment[index];
 		if (token === undefined) continue;
-		if (COMMAND_SEPARATORS.has(token)) break;
 		if (!endOfOptions && token === "--") {
 			endOfOptions = true;
 			continue;
@@ -487,20 +589,20 @@ function sedFileOperands(segment: ReadonlyArray<string>, cmdIndex: number): stri
 
 function isInterestingWriteTarget(target: string): boolean {
 	if (target.length === 0) return false;
-	if (target.startsWith("&")) return false;
 	if (STANDARD_DEV_TARGETS.has(target)) return false;
 	if (target.startsWith("/dev/fd/")) return false;
 	return true;
 }
 
 function classifyRedirect(
-	segment: ReadonlyArray<string>,
+	segment: ReadonlyArray<ShellToken>,
 	artifacts: ReadonlyArray<NormalizedArtifact>,
 ): DestructiveCommandClassification {
 	for (let index = 0; index < segment.length; index += 1) {
-		if (segment[index] !== ">") continue;
-		const target = segment[index + 1];
-		if (target === undefined) continue;
+		// Keep the existing distinction between overwriting and appending here.
+		if (segment[index]?.value === ">>" || segment[index]?.value === "&>>") continue;
+		const target = redirectWriteTarget(segment[index], segment[index + 1]);
+		if (target === null) continue;
 		const matches = matchesForPaths([target], artifacts, "target", "redirect can overwrite protected artifacts");
 		if (matches.length > 0) {
 			return {
@@ -738,36 +840,47 @@ function isPythonExecutable(executable: string): boolean {
 	return executable === "python" || executable === "python3" || /^python3\.\d+$/.test(executable);
 }
 
+/** Input is one command's argv. Literal words must never be reparsed as shell syntax. */
 function pathArgs(segment: ReadonlyArray<string>, commandIndex: number): string[] {
 	const args: string[] = [];
 	let endOfOptions = false;
 	for (let index = commandIndex + 1; index < segment.length; index += 1) {
 		const token = segment[index];
 		if (token === undefined) continue;
-		if (COMMAND_SEPARATORS.has(token)) break;
 		if (!endOfOptions && token === "--") {
 			endOfOptions = true;
 			continue;
 		}
 		if (!endOfOptions && token.startsWith("-")) continue;
-		if (token === ">" || token === ">>" || token === "<" || token === "<<") {
-			index += 1;
-			continue;
-		}
 		args.push(token);
 	}
 	return args;
 }
 
+/** Flat compatibility values; use scanShellLike when operator identity matters. */
 export function tokenizeShellLike(command: string): string[] {
-	const tokens: string[] = [];
+	return scanShellLike(command).map((token) => token.value);
+}
+
+/** Literal argv by command, with actual operators and redirections removed. */
+export function commandArgumentSegments(command: string): string[][] {
+	return splitSegments(scanShellLike(command)).map(shellCommandArguments);
+}
+
+/** Literal shell words and operators only; no expansion or script execution. */
+export function scanShellLike(command: string): ShellToken[] {
+	const tokens: ShellToken[] = [];
 	let current = "";
+	let wordStart: number | null = null;
+	let quoted = false;
 	let quote: "'" | '"' | null = null;
 
-	const pushCurrent = (): void => {
-		if (current.length === 0) return;
-		tokens.push(current);
+	const pushCurrent = (end: number): void => {
+		if (wordStart === null) return;
+		tokens.push({ value: current, operator: false, quoted, start: wordStart, end });
 		current = "";
+		wordStart = null;
+		quoted = false;
 	};
 
 	for (let index = 0; index < command.length; index += 1) {
@@ -779,80 +892,70 @@ export function tokenizeShellLike(command: string): string[] {
 				continue;
 			}
 			if (quote === '"' && char === "\\" && index + 1 < command.length) {
-				index += 1;
-				current += command[index] ?? "";
-				continue;
+				const next = command[index + 1] ?? "";
+				if (next === "\n" || '$`"\\'.includes(next)) {
+					index += 1;
+					if (next !== "\n") current += next;
+					continue;
+				}
 			}
 			current += char;
 			continue;
 		}
 
 		if (char === "'" || char === '"') {
+			wordStart ??= index;
+			quoted = true;
 			quote = char;
 			continue;
 		}
 		if (char === "\\" && index + 1 < command.length) {
-			index += 1;
-			current += command[index] ?? "";
-			continue;
-		}
-		if (/\s/.test(char)) {
-			pushCurrent();
-			if (char === "\n") tokens.push(";");
-			continue;
-		}
-		if (char === ";") {
-			pushCurrent();
-			tokens.push(";");
-			continue;
-		}
-		if (char === "&" && command[index + 1] === "&") {
-			pushCurrent();
-			tokens.push("&&");
+			// Backslash-newline joins lines before tokenization, even between words.
+			if (command[index + 1] !== "\n") {
+				wordStart ??= index;
+				quoted = true;
+				current += command[index + 1] ?? "";
+			}
 			index += 1;
 			continue;
 		}
-		if (char === "|") {
-			pushCurrent();
-			if (command[index + 1] === "|") {
-				tokens.push("||");
-				index += 1;
-			} else {
-				tokens.push("|");
-			}
+		if (char === "#" && wordStart === null) {
+			// A comment starts only at an unquoted word boundary. Leave its newline
+			// for normal separation so a following command is still inspected.
+			while (index + 1 < command.length && command[index + 1] !== "\n") index += 1;
 			continue;
 		}
-		if (char === ">") {
-			pushCurrent();
-			if (command[index + 1] === ">") {
-				tokens.push(">>");
-				index += 1;
-			} else {
-				tokens.push(">");
-			}
+		if (/\s/.test(char)) {
+			pushCurrent(index);
+			if (char === "\n") tokens.push({ value: ";", operator: true, quoted: false, start: index, end: index + 1 });
 			continue;
 		}
-		if (char === "<") {
-			pushCurrent();
-			if (command[index + 1] === "<") {
-				tokens.push("<<");
-				index += 1;
-			} else {
-				tokens.push("<");
-			}
+		if (";&|><".includes(char)) {
+			pushCurrent(index);
+			const three = command.slice(index, index + 3);
+			const two = command.slice(index, index + 2);
+			const value =
+				SHELL_REDIRECTIONS.has(three) || COMMAND_SEPARATORS.has(three)
+					? three
+					: SHELL_REDIRECTIONS.has(two) || COMMAND_SEPARATORS.has(two)
+						? two
+						: char;
+			tokens.push({ value, operator: true, quoted: false, start: index, end: index + value.length });
+			index += value.length - 1;
 			continue;
 		}
+		wordStart ??= index;
 		current += char;
 	}
-	pushCurrent();
+	pushCurrent(command.length);
 	return tokens;
 }
 
-function splitSegments(tokens: ReadonlyArray<string>): string[][] {
-	const segments: string[][] = [];
-	let current: string[] = [];
+function splitSegments(tokens: ReadonlyArray<ShellToken>): ShellToken[][] {
+	const segments: ShellToken[][] = [];
+	let current: ShellToken[] = [];
 	for (const token of tokens) {
-		if (COMMAND_SEPARATORS.has(token)) {
+		if (token.operator && COMMAND_SEPARATORS.has(token.value)) {
 			if (current.length > 0) segments.push(current);
 			current = [];
 			continue;

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

@@ -3,10 +3,10 @@ import { ToolNames } from "../../core/tool-names.js";
 import { classify } from "./action-classifier.js";
 import { typedValidationSummary } from "./finish-contract.js";
 import {
+	commandArgumentSegments,
 	detectValidationCommand,
 	extractCommandDeleteTargets,
 	extractCommandWriteTargets,
-	tokenizeShellLike,
 	toolMutationPaths,
 	type ValidationCommandScope,
 } from "./protected-artifacts.js";
@@ -155,7 +155,7 @@ const GIT_PATH_MUTATIONS: ReadonlySet<string> = new Set(["mv", "rm"]);
 
 function gitPathOperands(command: string): string[] {
 	const targets: string[] = [];
-	for (const segment of splitCommandSegments(command)) {
+	for (const segment of commandArgumentSegments(command)) {
 		if (segment[0] !== "git") continue;
 		const subcommand = segment[1];
 		if (subcommand === undefined || !GIT_PATH_MUTATIONS.has(subcommand)) continue;
@@ -167,26 +167,6 @@ function gitPathOperands(command: string): string[] {
 	return targets;
 }
 
-/**
- * Split the shared tokenizer's output on command separators. Only the
- * git-operand scan above needs segments, and it needs them after tokenization
- * rather than off the raw string.
- */
-function splitCommandSegments(command: string): string[][] {
-	const segments: string[][] = [];
-	let current: string[] = [];
-	for (const token of tokenizeShellLike(command)) {
-		if (token === ";" || token === "&&" || token === "||" || token === "|") {
-			if (current.length > 0) segments.push(current);
-			current = [];
-			continue;
-		}
-		current.push(token);
-	}
-	if (current.length > 0) segments.push(current);
-	return segments;
-}
-
 function commandOf(args: Record<string, unknown> | undefined): string | null {
 	const command = args?.command;
 	return typeof command === "string" && command.length > 0 ? command : null;

package/src/domains/safety/skill-authority.ts

@@ -0,0 +1,55 @@
+import { homedir } from "node:os";
+import path from "node:path";
+import { canonicalizeExistingPath } from "../../core/path-canonical.js";
+import { clioConfigDir } from "../../core/xdg.js";
+import { isSameOrDescendant, type PathPolicyOperation } from "./path-policy.js";
+import { extractCommandCdTargets } from "./protected-artifacts.js";
+
+/** Active Clio skill trees are operator-owned, independently of optional path
+ * defaults. Keep lexical roots and resolve them again at admission: an operator
+ * may install or replace a symlink after the session starts. Reads stay allowed.
+ */
+export function activeClioSkillRoots(cwd: string): string[] {
+	return [path.join(cwd, ".clio-coder", "skills"), path.join(clioConfigDir(), "skills")];
+}
+
+export function skillMutationReason(
+	roots: ReadonlyArray<string>,
+	targets: ReadonlyArray<{ operation: PathPolicyOperation; path: string }>,
+	cwd: string,
+	command: string | null,
+): string | null {
+	const workingDirs = [cwd];
+	// Existing shell inspection extracts literal path-bearing operations. Include
+	// their possible cd bases so a visible cd cannot hide the protected target.
+	// This deliberately cannot interpret arbitrary programs, variables or aliases.
+	if (command !== null) {
+		for (const destination of extractCommandCdTargets(command)) {
+			workingDirs.push(path.resolve(workingDirs.at(-1) ?? cwd, expandHome(destination)));
+		}
+	}
+	for (const target of targets) {
+		if (target.operation === "read") continue;
+		for (const directory of workingDirs) {
+			const lexical = path.resolve(directory, expandHome(target.path));
+			const resolved = canonicalizeExistingPath(lexical);
+			for (const root of roots) {
+				for (const boundary of [root, canonicalizeExistingPath(root)]) {
+					for (const candidate of [lexical, resolved]) {
+						if (
+							isSameOrDescendant(candidate, boundary) ||
+							(target.operation === "delete" && isSameOrDescendant(boundary, candidate))
+						) {
+							return `active skill tree ${root} is operator-owned; draft changes outside active skill roots and ask the operator to install or update them`;
+						}
+					}
+				}
+			}
+		}
+	}
+	return null;
+}
+
+function expandHome(value: string): string {
+	return value === "~" ? homedir() : value.startsWith("~/") ? path.join(homedir(), value.slice(2)) : value;
+}