@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/domains/resources/collision.ts

@@ -0,0 +1,92 @@
+export type ResourceScope = "package" | "user" | "project" | "cli";
+
+export interface ResourceSourceInfo {
+	path: string;
+	scope: ResourceScope;
+	source?: string;
+	/**
+	 * Collision rank, higher wins, for kinds that split a scope into tiers the
+	 * way skills split user roots into compatibility and Clio's own. Set it for
+	 * every candidate of a kind or none of them; a mixed set compares two scales.
+	 */
+	precedence?: number;
+}
+
+export interface ResourceCollision {
+	name: string;
+	winnerPath: string;
+	loserPath: string;
+	winnerScope: ResourceScope;
+	loserScope: ResourceScope;
+}
+
+export interface ResourceDiagnostic {
+	type: "warning" | "error" | "collision";
+	message: string;
+	path?: string;
+	collision?: ResourceCollision;
+}
+
+export interface ResourceCandidate<T> {
+	name: string;
+	value: T;
+	source: ResourceSourceInfo;
+}
+
+export interface CollisionResolution<T> {
+	winners: T[];
+	diagnostics: ResourceDiagnostic[];
+}
+
+const SCOPE_RANK: Record<ResourceScope, number> = {
+	package: 0,
+	user: 1,
+	project: 2,
+	cli: 3,
+};
+
+function rankOf(info: ResourceSourceInfo): number {
+	return info.precedence ?? SCOPE_RANK[info.scope];
+}
+
+function compareCandidates<T>(a: ResourceCandidate<T>, b: ResourceCandidate<T>): number {
+	const rankDelta = rankOf(a.source) - rankOf(b.source);
+	if (rankDelta !== 0) return rankDelta;
+	return a.source.path.localeCompare(b.source.path);
+}
+
+export function resolveResourceCollisions<T>(candidates: ReadonlyArray<ResourceCandidate<T>>): CollisionResolution<T> {
+	const byName = new Map<string, ResourceCandidate<T>[]>();
+	for (const candidate of candidates) {
+		const key = candidate.name.trim();
+		if (key.length === 0) continue;
+		const list = byName.get(key) ?? [];
+		list.push(candidate);
+		byName.set(key, list);
+	}
+
+	const winners: T[] = [];
+	const diagnostics: ResourceDiagnostic[] = [];
+	for (const [name, entries] of byName.entries()) {
+		const sorted = [...entries].sort(compareCandidates);
+		const winner = sorted[sorted.length - 1];
+		if (!winner) continue;
+		winners.push(winner.value);
+		for (const loser of sorted.slice(0, -1)) {
+			diagnostics.push({
+				type: "collision",
+				message: `${name} from ${winner.source.scope} overrides ${loser.source.scope}`,
+				path: loser.source.path,
+				collision: {
+					name,
+					winnerPath: winner.source.path,
+					loserPath: loser.source.path,
+					winnerScope: winner.source.scope,
+					loserScope: loser.source.scope,
+				},
+			});
+		}
+	}
+
+	return { winners, diagnostics };
+}

package/src/domains/resources/common-loader.ts

@@ -0,0 +1,140 @@
+import { type Dirent, existsSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { clioConfigDir } from "../../core/xdg.js";
+import { type ExtensionResourceKind, enabledExtensionResourceRoots } from "../extensions/index.js";
+import type { ResourceDiagnostic, ResourceScope, ResourceSourceInfo } from "./collision.js";
+
+export interface ResourceRoot {
+	path: string;
+	scope: ResourceScope;
+	source?: string;
+	/** Collision rank, higher wins. See {@link ResourceSourceInfo.precedence}. */
+	precedence?: number;
+	/** Whether the resource is usable without an explicit trust opt-in. Defaults to true. */
+	trusted?: boolean;
+}
+
+/**
+ * Collision tiers shared by every compatibility-aware resource kind. They match
+ * the skill precedence table so a foreign prompt root ranks against Clio's own
+ * roots exactly the way a foreign skill root does.
+ */
+export const COMPAT_RESOURCE_PRECEDENCE = {
+	extension: 10,
+	userCompat: 20,
+	user: 30,
+	projectCompat: 40,
+	project: 50,
+} as const;
+
+export type FrontmatterSplitResult =
+	| {
+			ok: true;
+			frontmatter: Record<string, unknown>;
+			body: string;
+	  }
+	| {
+			ok: false;
+			reason: string;
+			body: string;
+	  };
+
+export function defaultScopedResourceRoots(kind: ExtensionResourceKind, cwd: string): ResourceRoot[] {
+	return [
+		...enabledExtensionResourceRoots(kind, cwd).map((root) => ({
+			path: root.path,
+			scope: "package" as const,
+			source: root.source,
+			precedence: COMPAT_RESOURCE_PRECEDENCE.extension,
+		})),
+		{
+			path: path.join(clioConfigDir(), kind),
+			scope: "user" as const,
+			source: "config",
+			precedence: COMPAT_RESOURCE_PRECEDENCE.user,
+		},
+		{
+			path: path.join(cwd, ".clio-coder", kind),
+			scope: "project" as const,
+			source: "project",
+			precedence: COMPAT_RESOURCE_PRECEDENCE.project,
+		},
+	];
+}
+
+export function sourceInfoForRoot(root: ResourceRoot, filePath: string): ResourceSourceInfo {
+	return {
+		path: filePath,
+		scope: root.scope,
+		...(root.source ? { source: root.source } : {}),
+		...(root.precedence !== undefined ? { precedence: root.precedence } : {}),
+	};
+}
+
+export function readRootEntries(
+	root: ResourceRoot,
+	label: string,
+	diagnostics: ResourceDiagnostic[],
+): Dirent<string>[] {
+	if (!existsSync(root.path)) return [];
+	let stat: ReturnType<typeof statSync>;
+	try {
+		stat = statSync(root.path);
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		diagnostics.push({
+			type: "warning",
+			message: `${label} root could not be stat'ed: ${reason}`,
+			path: root.path,
+		});
+		return [];
+	}
+	if (!stat.isDirectory()) {
+		diagnostics.push({ type: "warning", message: `${label} root is not a directory`, path: root.path });
+		return [];
+	}
+
+	try {
+		return readdirSync(root.path, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		diagnostics.push({ type: "warning", message: `${label} root could not be read: ${reason}`, path: root.path });
+		return [];
+	}
+}
+
+export function splitYamlFrontmatter(raw: string): FrontmatterSplitResult {
+	const opening = raw.match(/^---\r?\n/);
+	if (!opening) return { ok: false, reason: "missing", body: raw };
+
+	const closeRegex = /\r?\n---(?:\r?\n|$)/g;
+	closeRegex.lastIndex = opening[0].length;
+	const closing = closeRegex.exec(raw);
+	if (!closing) return { ok: false, reason: "missing closing delimiter", body: raw };
+
+	const body = raw.slice(closing.index + closing[0].length);
+	const frontmatterText = raw.slice(opening[0].length, closing.index);
+	let parsed: unknown;
+	try {
+		parsed = parseYaml(frontmatterText);
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		return { ok: false, reason: `invalid YAML: ${reason}`, body };
+	}
+
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return { ok: false, reason: "must be a YAML object", body };
+	}
+
+	return {
+		ok: true,
+		frontmatter: parsed as Record<string, unknown>,
+		body,
+	};
+}
+
+export function stringField(frontmatter: Record<string, unknown>, key: string): string | null {
+	const value = frontmatter[key];
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}

package/src/domains/resources/contract.ts

@@ -0,0 +1,24 @@
+import type { DomainContract } from "../../core/domain-loader.js";
+import type { PendingSkillRequest } from "../../core/skill-activation.js";
+import type { ResourceDiagnostic } from "./collision.js";
+import type { PromptTemplate, PromptTemplateExpansion } from "./prompts/loader.js";
+import type { Skill, SkillExpansion, SkillExpansionOptions } from "./skills/loader.js";
+
+export interface ResourceList<T> {
+	items: T[];
+	diagnostics: ResourceDiagnostic[];
+}
+
+export interface ResourcesContract extends DomainContract {
+	skills(cwd?: string): ResourceList<Skill>;
+	expandSkillInvocation(text: string, cwd?: string, options?: SkillExpansionOptions): SkillExpansion;
+	parsePendingSkillRequests(
+		text: string,
+		cwd?: string,
+		options?: SkillExpansionOptions,
+	): { text: string; pendingSkillRequests: PendingSkillRequest[] };
+	prompts(cwd?: string): ResourceList<PromptTemplate>;
+	expandPromptTemplate(text: string, cwd?: string): PromptTemplateExpansion;
+	resolvePath(value: string, cwd?: string): string;
+	reload(): Promise<void>;
+}

package/src/domains/resources/extension.ts

@@ -0,0 +1,59 @@
+import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
+import type { ConfigContract } from "../config/contract.js";
+import type { ResourcesContract } from "./contract.js";
+import { createResourcesLoader, type ResourceLoaderOptions } from "./loader.js";
+
+export function createResourcesBundle(
+	context: DomainContext,
+	options: ResourceLoaderOptions = {},
+): DomainBundle<ResourcesContract> {
+	const config = (): ConfigContract | undefined => context.getContract<ConfigContract>("config");
+	const loader = createResourcesLoader({
+		...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+		...(options.reservedPromptNames !== undefined ? { reservedPromptNames: options.reservedPromptNames } : {}),
+		skills: () => ({
+			...skillOptions(config()?.get().skills.trustProjectCompatRoots === true, options),
+		}),
+	});
+	const extension: DomainExtension = {
+		start() {
+			return undefined;
+		},
+	};
+	const contract: ResourcesContract = {
+		skills(cwd) {
+			return loader.skills(cwd);
+		},
+		expandSkillInvocation(text, cwd, options) {
+			return loader.expandSkillInvocation(text, cwd, options);
+		},
+		parsePendingSkillRequests(text, cwd, options) {
+			return loader.parsePendingSkillRequests(text, cwd, options);
+		},
+		prompts(cwd) {
+			return loader.prompts(cwd);
+		},
+		expandPromptTemplate(text, cwd) {
+			return loader.expandPromptTemplate(text, cwd);
+		},
+		resolvePath(value, cwd) {
+			return loader.resolvePath(value, cwd);
+		},
+		reload() {
+			return loader.reload();
+		},
+	};
+	return { extension, contract };
+}
+
+function skillOptions(
+	trustProjectCompatRoots: boolean,
+	options: ResourceLoaderOptions,
+): ReturnType<NonNullable<ResourceLoaderOptions["skills"]>> {
+	const runtime = options.skills?.() ?? {};
+	return {
+		trustProjectCompatRoots: runtime.trustProjectCompatRoots ?? trustProjectCompatRoots,
+		...(runtime.disableDiscovery !== undefined ? { disableDiscovery: runtime.disableDiscovery } : {}),
+		...(runtime.explicitSkillPaths !== undefined ? { explicitSkillPaths: runtime.explicitSkillPaths } : {}),
+	};
+}

package/src/domains/resources/index.ts

@@ -0,0 +1,74 @@
+import type { DomainModule } from "../../core/domain-loader.js";
+import { createResourcesBundle } from "./extension.js";
+import type { ResourceLoaderOptions } from "./loader.js";
+import { ResourcesManifest } from "./manifest.js";
+
+export const ResourcesDomainModule: DomainModule = {
+	manifest: ResourcesManifest,
+	createExtension: createResourcesBundle,
+};
+
+export function createResourcesDomainModule(options: ResourceLoaderOptions = {}): DomainModule {
+	return {
+		manifest: ResourcesManifest,
+		createExtension: (context) => createResourcesBundle(context, options),
+	};
+}
+
+export type { ResourceDiagnostic, ResourceScope, ResourceSourceInfo } from "./collision.js";
+export { resolveResourceCollisions } from "./collision.js";
+export type { ResourceList, ResourcesContract } from "./contract.js";
+export { createResourcesLoader, type ResourceLoaderOptions } from "./loader.js";
+export { ResourcesManifest } from "./manifest.js";
+export {
+	expandPromptTemplateInput,
+	loadPromptTemplates,
+	type PromptTemplate,
+	type PromptTemplateExpansion,
+	type PromptTemplateList,
+	type PromptTemplateRoot,
+} from "./prompts/loader.js";
+export { parseCommandArgs, substituteArgs } from "./prompts/substitute.js";
+export { parseSkillEvals, type SkillEvalParseResult, type SkillEvalScenario } from "./skills/evals.js";
+export {
+	type InstallSkillInput,
+	type InstallSkillResult,
+	normalizedSkillHash,
+	parseSkillSourceSpec,
+	type SkillSourceSpec,
+	type SkillUpdateReport,
+	type SkillUpdateStatus,
+	type UpdateSkillsInput,
+	updateSkills,
+} from "./skills/install.js";
+export {
+	defaultSkillRoots,
+	expandSkillInvocationInput,
+	type LoadSkillsInput,
+	loadSkills,
+	modelVisibleSkills,
+	parsePendingSkillRequests,
+	parseSkillCommand,
+	type Skill,
+	type SkillExpansion,
+	type SkillList,
+	type SkillProvenance,
+	type SkillRoot,
+	type SkillSource,
+} from "./skills/loader.js";
+export {
+	type DiscoverMarketplaceOptions,
+	discoverMarketplaceSkills,
+	getMarketplaceSkills,
+	installSkill,
+	MARKETPLACE_UNCONFIGURED,
+	type MarketplaceDiscoveryResult,
+	type MarketplaceSkill,
+	type MarketplaceSkillOrigin,
+	type MarketplaceStatus,
+} from "./skills/marketplace.js";
+export {
+	checkSkillDrift,
+	type SkillDriftVerdict,
+	type SkillPinEntry,
+} from "./skills/provenance-pin.js";

package/src/domains/resources/loader.ts

@@ -0,0 +1,85 @@
+import { expandConfigPath } from "../../core/resolve-config-value.js";
+import type { PendingSkillRequest } from "../../core/skill-activation.js";
+import type { ResourceDiagnostic } from "./collision.js";
+import {
+	expandPromptTemplateInput,
+	type LoadPromptTemplatesInput,
+	loadPromptTemplates,
+	type PromptTemplate,
+	type PromptTemplateExpansion,
+} from "./prompts/loader.js";
+import {
+	expandSkillInvocationInput,
+	type LoadSkillsInput,
+	loadSkills,
+	parsePendingSkillRequests,
+	type Skill,
+	type SkillExpansion,
+	type SkillExpansionOptions,
+} from "./skills/loader.js";
+
+export interface ResourceList<T> {
+	items: T[];
+	diagnostics: ResourceDiagnostic[];
+}
+
+export interface ResourceLoaderOptions {
+	cwd?: string;
+	/** Slash-command names prompt templates may not claim. */
+	reservedPromptNames?: ReadonlySet<string>;
+	skills?: () => Pick<LoadSkillsInput, "trustProjectCompatRoots" | "disableDiscovery" | "explicitSkillPaths">;
+}
+
+export interface ResourcesLoader {
+	skills(cwd?: string): ResourceList<Skill>;
+	expandSkillInvocation(text: string, cwd?: string, options?: SkillExpansionOptions): SkillExpansion;
+	parsePendingSkillRequests(
+		text: string,
+		cwd?: string,
+		options?: SkillExpansionOptions,
+	): { text: string; pendingSkillRequests: PendingSkillRequest[] };
+	prompts(cwd?: string): ResourceList<PromptTemplate>;
+	expandPromptTemplate(text: string, cwd?: string): PromptTemplateExpansion;
+	resolvePath(value: string, cwd?: string): string;
+	reload(): Promise<void>;
+}
+
+export function createResourcesLoader(options: ResourceLoaderOptions = {}): ResourcesLoader {
+	const defaultCwd = options.cwd ?? process.cwd();
+	const skillOptions = (): Pick<
+		LoadSkillsInput,
+		"trustProjectCompatRoots" | "disableDiscovery" | "explicitSkillPaths"
+	> => options.skills?.() ?? {};
+	// Prompts share the skills opt-in: a project compatibility root is the same
+	// trust decision whichever kind is read out of it.
+	const promptOptions = (cwd: string): LoadPromptTemplatesInput => ({
+		cwd,
+		...(options.reservedPromptNames !== undefined ? { reservedNames: options.reservedPromptNames } : {}),
+		...(skillOptions().trustProjectCompatRoots !== undefined
+			? { trustProjectCompatRoots: skillOptions().trustProjectCompatRoots === true }
+			: {}),
+	});
+	return {
+		skills(cwd = defaultCwd) {
+			return loadSkills({ cwd, ...skillOptions() });
+		},
+		expandSkillInvocation(text, cwd = defaultCwd, expansionOptions = {}) {
+			return expandSkillInvocationInput(text, loadSkills({ cwd, ...skillOptions() }), expansionOptions);
+		},
+		parsePendingSkillRequests(text, cwd = defaultCwd, expansionOptions = {}) {
+			return parsePendingSkillRequests(text, loadSkills({ cwd, ...skillOptions() }), { cwd, ...expansionOptions });
+		},
+		prompts(cwd = defaultCwd) {
+			return loadPromptTemplates(promptOptions(cwd));
+		},
+		expandPromptTemplate(text, cwd = defaultCwd) {
+			return expandPromptTemplateInput(text, loadPromptTemplates(promptOptions(cwd)));
+		},
+		resolvePath(value, cwd = defaultCwd) {
+			return expandConfigPath(value, { cwd });
+		},
+		async reload() {
+			return undefined;
+		},
+	};
+}

package/src/domains/resources/manifest.ts

@@ -0,0 +1,6 @@
+import type { DomainManifest } from "../../core/domain-loader.js";
+
+export const ResourcesManifest: DomainManifest = {
+	name: "resources",
+	dependsOn: ["config"],
+};