@iowarp/clio-coder 0.4.6 → 0.4.8

package/src/domains/resources/package-references.ts

@@ -0,0 +1,66 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { readPluginManifest } from "../plugins/index.js";
+
+export interface PackageReferenceContext {
+	rootPath?: string;
+	/** Only plugin-owned content interprets package references. */
+	plugin?: boolean;
+}
+
+/** Prose markers with a portable, space-free slash suffix. */
+const REFERENCE_PATTERN = /\$\{(pluginRoot|component:([^}]+))\}(\/[A-Za-z0-9._~%+@/-]*)?/g;
+/** The same reference occupying an entire argv/data value, spaces and Unicode included. */
+const COMPLETE_REFERENCE = /^\$\{(pluginRoot|component:([^}]+))\}(\/[\s\S]*)?$/u;
+
+function referenceResolver(context: PackageReferenceContext & { rootPath: string }) {
+	const root = realpathSync(context.rootPath);
+	let components: Map<string, string> | undefined;
+	return (reference: string, _token: string, ref: string | undefined, suffix: string | undefined): string => {
+		if (suffix && /[\\\0\r\n]/u.test(suffix)) throw new Error(`unsupported package path syntax: ${reference}`);
+		let relative = "";
+		if (ref !== undefined) {
+			if (!components) {
+				const candidate = readPluginManifest(root);
+				if (!candidate.valid || !candidate.manifest) throw new Error("plugin manifest unavailable for component reference");
+				components = new Map(
+					candidate.manifest.clio.components.map((component) => [`${component.kind}:${component.id}`, component.path]),
+				);
+			}
+			const componentPath = components.get(ref);
+			if (componentPath === undefined) throw new Error(`unresolved component reference: ${ref}`);
+			relative = componentPath;
+		}
+		const target = path.resolve(root, relative + (suffix ?? ""));
+		const contained = (value: string): boolean => {
+			const rel = path.relative(root, value);
+			return rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+		};
+		try {
+			// A root token's slash suffix is package-relative, never filesystem-absolute.
+			const resolved = ref === undefined ? path.resolve(root, `.${suffix ?? ""}`) : target;
+			if (!contained(resolved) || !contained(realpathSync(resolved))) throw new Error("outside package");
+			return resolved;
+		} catch {
+			throw new Error(`unresolved or escaping package reference: ${reference}`);
+		}
+	};
+}
+
+/**
+ * Expand prose markers with portable, space-free slash suffixes. Surrounding
+ * prose is not a filesystem path; data arguments use the complete-path parser.
+ */
+export function resolvePackageReferences(body: string, context: PackageReferenceContext): string {
+	if (!context.rootPath || !context.plugin || !body.includes("${")) return body;
+	return body.replace(REFERENCE_PATTERN, referenceResolver({ ...context, rootPath: context.rootPath }));
+}
+
+/** Resolve an entire argv/data path, including spaces and Unicode, before use. */
+export function resolvePackagePathReference(value: string, context: PackageReferenceContext): string {
+	if (!context.rootPath || !context.plugin || !/\$\{(?:pluginRoot|component:)/u.test(value)) return value;
+	const match = COMPLETE_REFERENCE.exec(value);
+	if (!match || match[3]?.includes("${"))
+		throw new Error("package path references must occupy one complete argument with no embedded expressions");
+	return referenceResolver({ ...context, rootPath: context.rootPath })(value, match[1] ?? "", match[2], match[3]);
+}

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

@@ -1,4 +1,4 @@
-import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import { parseCommandArgs, substituteArgs } from "../../../engine/prompt-templates.js";
@@ -17,6 +17,7 @@ import {
 	splitYamlFrontmatter,
 	stringField,
 } from "../common-loader.js";
+import { resolvePackageReferences } from "../package-references.js";
 import { projectCompatTrusted } from "../skills/loader.js";
 
 export interface PromptTemplate {
@@ -36,11 +37,18 @@ export interface PromptTemplate {
 	 */
 	unavailable?: string;
 	argumentHint?: string;
+	/**
+	 * Frontmatter `display-only: true`. The body is written for the operator,
+	 * not the model: invoking the command renders it locally and sends nothing,
+	 * records nothing in model-facing session context, and spends no tokens.
+	 */
+	displayOnly: boolean;
 }
 
 export interface PromptTemplateRoot {
+	plugin?: boolean;
 	path: string;
-	/** Present only for an installed extension resource root. */
+	/** Present only for an installed plugin resource root. */
 	rootPath?: string;
 	scope: ResourceScope;
 	source?: string;
@@ -77,6 +85,13 @@ export type PromptTemplateExpansion =
 			 * slash, so sending the literal `/name` to the model answers nothing.
 			 */
 			refusal?: { template: PromptTemplate; message: string };
+			/**
+			 * Set when the input named a display-only template. `text` is what the
+			 * operator reads; it is never model text, which is why this rides the
+			 * not-expanded shape: a caller that only checks `expanded` cannot send
+			 * it anywhere by accident.
+			 */
+			display?: { template: PromptTemplate; text: string };
 	  }
 	| {
 			expanded: true;
@@ -117,7 +132,13 @@ function defaultPromptTemplateRoots(input: LoadPromptTemplatesInput = {}): Promp
 			});
 		}
 	}
-	return [...defaultScopedResourceRoots("prompts", cwd), ...compat];
+	return [
+		...defaultScopedResourceRoots("prompts", cwd).map((root) => ({
+			...root,
+			trusted: root.trusted !== false || trustProject,
+		})),
+		...compat,
+	];
 }
 
 function splitOptionalFrontmatter(
@@ -148,20 +169,6 @@ 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));
-}
-
 /**
  * The outcome of a step that may leave the template with no usable body.
  * `reason` is the one sentence that becomes both the diagnostic the `/prompts`
@@ -171,43 +178,27 @@ function contained(root: string, candidate: string): boolean {
 type BodyResolution = { body: string } | { reason: string };
 
 /**
- * Resolve only existing paths contained by the declaring extension package.
+ * Resolve only existing paths contained by the declaring plugin package.
  *
  * The safety half is unchanged: a missing or escaping reference never expands
  * and never reads outside the package. What changed is what the caller does
  * with the failure, which used to be dropping the template entirely.
  */
-function resolveExtensionReferences(body: string, root: PromptTemplateRoot): BodyResolution {
-	if (root.rootPath === undefined || !body.includes(EXTENSION_ROOT_TOKEN)) return { body };
-	let canonicalRoot: string;
+function resolvePackageRootReferences(body: string, root: PromptTemplateRoot): BodyResolution {
+	if (!root.plugin) return { body };
 	try {
-		canonicalRoot = realpathSync(root.rootPath);
+		return { body: resolvePackageReferences(body, root) };
 	} catch (error) {
-		return { reason: `extension root could not be resolved: ${error instanceof Error ? error.message : String(error)}` };
-	}
-	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) {
-		return { reason: `prompt template has an unresolved or escaping extension reference: ${invalid}` };
+		return { reason: `prompt template: ${error instanceof Error ? error.message : String(error)}` };
 	}
-	return { body: resolved };
 }
 
 /**
  * A template that exists and cannot run.
  *
  * Dropping it made the operator's namespaced command answer "not a command",
- * so an extension author's single bad `${extensionRoot}` path read to their
- * users as "the prompt was never installed" (issue #245). The template is
+ * so a plugin author's single bad `${pluginRoot}` path read to their users as
+ * "the prompt was never installed" (issue #245). The template is
  * loaded with an empty body and the reason attached instead, which is the same
  * shape an untrusted project template already had, so the existing refusal
  * path carries it to the operator with no new machinery.
@@ -232,11 +223,44 @@ function unavailableTemplate(
 			sourceInfo,
 			trusted: root.trusted !== false,
 			unavailable: `${reason} (${filePath})`,
+			displayOnly: false,
 		},
 		source: sourceInfo,
 	};
 }
 
+/** A frontmatter flag is only ever the YAML boolean; any other value reads as unset. */
+function booleanField(frontmatter: Record<string, unknown>, key: string): boolean | null {
+	const value = frontmatter[key];
+	return typeof value === "boolean" ? value : null;
+}
+
+/**
+ * What a display-only template shows: the first fenced code block when the
+ * body has one, otherwise the whole body. Authors write these as "display this
+ * block" with the block fenced, so the fence is the reference and the prose
+ * around it was instructions for a model that is no longer in the loop.
+ */
+export function promptTemplateDisplayText(template: Pick<PromptTemplate, "content">): string {
+	const content = template.content.replace(/\r\n?/g, "\n");
+	const lines = content.split("\n");
+	for (let start = 0; start < lines.length; start++) {
+		const opening = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(lines[start] ?? "");
+		const fence = opening?.[1];
+		if (!fence || (fence[0] === "`" && opening?.[2]?.includes("`"))) continue;
+		for (let end = start + 1; end < lines.length; end++) {
+			const closing = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(lines[end] ?? "")?.[1];
+			if (closing && closing[0] === fence[0] && closing.length >= fence.length)
+				return lines
+					.slice(start + 1, end)
+					.join("\n")
+					.trimEnd();
+		}
+		break;
+	}
+	return content.trimEnd();
+}
+
 function loadPromptFile(
 	filePath: string,
 	root: PromptTemplateRoot,
@@ -272,7 +296,7 @@ function loadPromptFile(
 
 	const { frontmatter, body } = splitOptionalFrontmatter(raw, filePath, diagnostics);
 	const declaredDescription = stringField(frontmatter, "description");
-	const resolution = resolveExtensionReferences(body, root);
+	const resolution = resolvePackageRootReferences(body, root);
 	if ("reason" in resolution) {
 		return unavailableTemplate(name, filePath, root, resolution.reason, diagnostics, declaredDescription ?? undefined);
 	}
@@ -286,6 +310,7 @@ function loadPromptFile(
 		filePath,
 		sourceInfo,
 		trusted: root.trusted !== false,
+		displayOnly: booleanField(frontmatter, "display-only") ?? booleanField(frontmatter, "displayOnly") ?? false,
 	};
 	if (argumentHint) template.argumentHint = argumentHint;
 	return { name, value: template, source: sourceInfo };
@@ -403,6 +428,15 @@ export function expandPromptTemplateInput(input: string, templates: PromptTempla
 		};
 	}
 	const args = parseCommandArgs(command.rest);
+	if (template.displayOnly) {
+		return {
+			expanded: false,
+			text: input,
+			args,
+			diagnostics: templates.diagnostics,
+			display: { template, text: promptTemplateDisplayText(template) },
+		};
+	}
 	return {
 		expanded: true,
 		text: substituteArgs(template.content, args, command.rest),

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

@@ -23,7 +23,7 @@ const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const CLONE_TIMEOUT_MS = 60_000;
 
 /** True when the value has the bare skill-name shape (lowercase, hyphenated). */
-export function isSkillName(value: string): boolean {
+function isSkillName(value: string): boolean {
 	return value.length > 0 && value.length <= 64 && SKILL_NAME_PATTERN.test(value);
 }
 
@@ -141,7 +141,7 @@ export function parseSkillSourceSpec(source: string): SkillSourceSpec | null {
  * Whether this process is running inside a dispatched worker rather than the
  * operator's own interactive session. `worker/entry.ts` sets this on itself at
  * launch, so it rides the environment into every bash-tool child a worker
- * spawns, including a `clio-coder skills install` a worker runs directly.
+ * spawns, including a `clio-coder library install` a worker runs directly.
  */
 function installingAsWorker(): boolean {
 	return process.env.CLIO_CODER_WORKER_RUN === "1";

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

@@ -6,10 +6,11 @@ import { warnLegacyNaming } from "../../../core/naming-compat.js";
 import type { PendingSkillRequest } from "../../../core/skill-activation.js";
 import { type ToolName, ToolNames } from "../../../core/tool-names.js";
 import { clioConfigDir } from "../../../core/xdg.js";
-import { enabledExtensionResourceRoots } from "../../extensions/index.js";
 import { INTEROP_AGENT_KINDS, interopSourceRank } from "../../interop/registry.js";
+import { enabledPluginResourceRoots, pluginBaseDir } from "../../plugins/index.js";
 import type { ResourceDiagnostic, ResourceScope, ResourceSourceInfo } from "../collision.js";
 import { readRootEntries, splitYamlFrontmatter, stringField } from "../common-loader.js";
+import { resolvePackageReferences } from "../package-references.js";
 import { normalizedSkillHash } from "./content-hash.js";
 import { getMarketplaceSkills } from "./marketplace.js";
 
@@ -54,7 +55,7 @@ export type SkillSource =
 	| "codex"
 	| "copilot"
 	| "opencode"
-	| "extension"
+	| "plugin"
 	| "path"
 	| "cli";
 
@@ -80,7 +81,7 @@ export interface Skill {
 	content: string;
 	sourceInfo: ResourceSourceInfo;
 	disableModelInvocation: boolean;
-	/** Semantic source root (clio, agents, codex, extension, ...). */
+	/** Semantic source root (clio, agents, codex, plugin, ...). */
 	source: SkillSource;
 	/** Mirror of sourceInfo.scope for convenient access. */
 	scope: ResourceScope;
@@ -116,10 +117,12 @@ export interface Skill {
 }
 
 export interface SkillRoot {
+	rootPath?: string;
+	plugin?: boolean;
 	path: string;
 	scope: ResourceScope;
 	source?: SkillSource;
-	/** sourceInfo.source string, e.g. "config", "agents-user", "extension:user:id". */
+	/** sourceInfo.source string, e.g. "config", "agents-user", "plugin:user:id". */
 	origin?: string;
 	/** Collision precedence override; defaults are derived from scope. */
 	precedence?: number;
@@ -137,9 +140,8 @@ export interface SkillRoot {
 	 * share one skills tree across checkouts, but nothing may reach outside the
 	 * tree the operator is working in.
 	 *
-	 * Undefined disables the check. An extension root is laid out by a package
-	 * manager that symlinks by design, and an explicit skill path names its own
-	 * target, so neither has a containing scope to be measured against.
+	 * Undefined disables the check for standalone explicit paths. Installed
+	 * package roots use the package directory as their containment boundary.
 	 */
 	containment?: string;
 }
@@ -187,7 +189,7 @@ export type SkillExpansion =
 
 /** Collision precedence tiers; higher wins. */
 const SKILL_PRECEDENCE = {
-	extension: 10,
+	package: 10,
 	userCompat: 20,
 	user: 30,
 	projectCompat: 40,
@@ -202,7 +204,7 @@ function sha256(value: string): string {
 function defaultPrecedenceForScope(scope: ResourceScope): number {
 	switch (scope) {
 		case "package":
-			return SKILL_PRECEDENCE.extension;
+			return SKILL_PRECEDENCE.package;
 		case "user":
 			return SKILL_PRECEDENCE.user;
 		case "project":
@@ -223,7 +225,7 @@ export function projectCompatTrusted(explicit?: boolean): boolean {
 
 /**
  * Discovery roots, lowest to highest precedence:
- *  1. package/extension skills
+ *  1. plugin skills
  *  2. shared user compat roots, one per interop agent kind that owns a skills directory
  *  3. Clio user root (<config>/skills)
  *  4. the same agents' project roots, trusted only on opt-in
@@ -240,14 +242,17 @@ export function defaultSkillRoots(input: LoadSkillsInput = {}): SkillRoot[] {
 	const trustProject = projectCompatTrusted(input.trustProjectCompatRoots);
 	const roots: SkillRoot[] = [];
 
-	for (const root of enabledExtensionResourceRoots("skills", cwd)) {
+	for (const root of enabledPluginResourceRoots("skills", cwd)) {
 		roots.push({
 			path: root.path,
 			scope: "package",
-			source: "extension",
+			source: "plugin",
+			rootPath: root.rootPath,
+			plugin: true,
+			containment: root.rootPath,
 			origin: root.source,
-			precedence: SKILL_PRECEDENCE.extension,
-			trusted: true,
+			precedence: SKILL_PRECEDENCE.package,
+			trusted: root.trust !== "foreign" || trustProject,
 		});
 	}
 
@@ -671,12 +676,19 @@ function loadSkillFile(
 	const provenance = extractProvenance(parsed.frontmatter, filePath);
 	const allowedTools = declaredToolSurface(parsed.frontmatter, "allowed-tools", filePath, diagnostics);
 	const disallowedTools = declaredToolSurface(parsed.frontmatter, "disallowed-tools", filePath, diagnostics);
+	let content: string;
+	try {
+		content = resolvePackageReferences(parsed.body.trim(), root);
+	} catch (error) {
+		diagnostics.push({ type: "warning", message: String(error), path: filePath });
+		return { candidate: null, diagnostics };
+	}
 	const skill: Skill = {
 		name,
 		description,
 		filePath,
 		baseDir,
-		content: parsed.body.trim(),
+		content,
 		sourceInfo,
 		disableModelInvocation: booleanField(parsed.frontmatter, "disable-model-invocation"),
 		...(allowedTools ? { allowedTools } : {}),
@@ -760,9 +772,42 @@ function explicitSkillRoot(filePath: string): SkillRoot {
 	};
 }
 
-function loadExplicitSkillPath(inputPath: string, diagnostics: ResourceDiagnostic[]): SkillCandidate[] {
+function loadExplicitSkillPath(
+	inputPath: string,
+	diagnostics: ResourceDiagnostic[],
+	packageRoots: ReadonlyArray<SkillRoot>,
+	cwd: string,
+): SkillCandidate[] {
 	const resolved = path.resolve(inputPath);
-	const root = explicitSkillRoot(resolved);
+	const identity = canonicalizePath(resolved);
+	const owner = packageRoots.find((candidate) => {
+		const relative = path.relative(canonicalizePath(candidate.path), identity);
+		return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+	});
+	if (
+		!owner &&
+		(["user", "project"] as const).some((scope) => {
+			const relative = path.relative(canonicalizePath(pluginBaseDir(scope, cwd)), identity);
+			return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+		})
+	) {
+		diagnostics.push({
+			type: "warning",
+			message: "explicit skill belongs to an inactive or undeclared plugin resource",
+			path: resolved,
+		});
+		return [];
+	}
+	const root = {
+		...explicitSkillRoot(resolved),
+		...(owner
+			? {
+					...(owner.rootPath ? { rootPath: owner.rootPath, containment: owner.rootPath } : {}),
+					...(owner.plugin !== undefined ? { plugin: owner.plugin } : {}),
+					trusted: owner.trusted,
+				}
+			: {}),
+	};
 	if (!existsSync(resolved)) {
 		diagnostics.push({ type: "warning", message: `explicit skill path does not exist: ${resolved}`, path: resolved });
 		return [];
@@ -790,12 +835,16 @@ function loadExplicitSkillPath(inputPath: string, diagnostics: ResourceDiagnosti
 
 /**
  * Ascending order for a set of candidates competing for one name or one
- * canonical file, so the last entry is the winner. Precedence decides first.
+ * canonical file, so the last entry is the winner. Trusted candidates win
+ * before scope precedence: an untrusted compatibility copy cannot hide an
+ * admitted native skill and then disappear from model-visible discovery.
  * Two compatibility roots share a precedence tier, and ranking those by path
  * spelling made the winner depend on what the agents happen to be called, so
- * the second key is the registry's own agent order.
+ * equal-precedence candidates use the registry's own agent order.
  */
 function compareSkillCandidates(a: Skill, b: Skill): number {
+	const trust = Number(a.trusted) - Number(b.trusted);
+	if (trust !== 0) return trust;
 	const precedence = a.precedence - b.precedence;
 	if (precedence !== 0) return precedence;
 	const rank = interopSourceRank(b.source) - interopSourceRank(a.source);
@@ -835,7 +884,7 @@ function dedupeCanonicalSkillPaths(
 	return winners;
 }
 
-/** Resolve name collisions by precedence (higher wins), tiebroken by registry order. */
+/** Resolve name collisions by trust, then precedence and registry order. */
 function resolveSkillCollisions(candidates: ReadonlyArray<SkillCandidate>): {
 	winners: Skill[];
 	diagnostics: ResourceDiagnostic[];
@@ -898,9 +947,15 @@ function requiresDiagnostics(winners: ReadonlyArray<Skill>): ResourceDiagnostic[
 export function loadSkills(input: LoadSkillsInput = {}): SkillList {
 	const roots = input.roots ?? (input.disableDiscovery === true ? [] : defaultSkillRoots(input));
 	const diagnostics: ResourceDiagnostic[] = [];
+	const packageRoots =
+		(input.explicitSkillPaths?.length ?? 0) > 0
+			? defaultSkillRoots(input).filter((root) => root.scope === "package")
+			: [];
 	const candidates = [
 		...roots.flatMap((root) => loadSkillRoot(root, diagnostics)),
-		...(input.explicitSkillPaths ?? []).flatMap((skillPath) => loadExplicitSkillPath(skillPath, diagnostics)),
+		...(input.explicitSkillPaths ?? []).flatMap((skillPath) =>
+			loadExplicitSkillPath(skillPath, diagnostics, packageRoots, input.cwd ?? process.cwd()),
+		),
 	];
 	const deduped = dedupeCanonicalSkillPaths(candidates, diagnostics);
 	const resolved = resolveSkillCollisions(deduped);
@@ -925,7 +980,7 @@ export interface SkillCatalogValidity {
 }
 
 /**
- * The rule `clio-coder skills validate` applies, in one place.
+ * The rule `clio-coder library validate` applies, in one place.
  *
  * A scanned file that produced no loaded skill is malformed, and a collision
  * drops a skill: both make the catalog invalid, as does any hard error. Benign