@iowarp/clio-coder 0.4.0 → 0.4.1

package/src/domains/lifecycle/naming-resources.ts

@@ -0,0 +1,261 @@
+import {
+	cpSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import path from "node:path";
+
+import { parse as parseYaml } from "yaml";
+import { resolvePackageRoot } from "../../core/package-root.js";
+import { fsyncDirectory } from "../../core/safe-resource-write.js";
+import { resolveClioDirs } from "../../core/xdg.js";
+import { normalizedSkillHash, stripProvenanceFrontmatter } from "../resources/skills/content-hash.js";
+
+const LEGACY_SKILL_NAMES = [
+	["clio-dev", "clio-coder-dev"],
+	["clio-test", "clio-coder-test"],
+] as const;
+
+export type NamingResourceStatus = "absent" | "canonical-present" | "modified" | "renamable" | "renamed";
+
+export interface NamingResourceReport {
+	kind: "skill";
+	legacyPath: string;
+	canonicalPath: string;
+	status: NamingResourceStatus;
+	detail: string;
+}
+
+export interface NamingResourceOptions {
+	cwd?: string;
+	configDir?: string;
+	packageRoot?: string;
+	fix?: boolean;
+}
+
+function canonicalizeNamingText(text: string): string {
+	return text
+		.replaceAll("clio-dev", "clio-coder-dev")
+		.replaceAll("clio-test", "clio-coder-test")
+		.replace(/^clio:/gmu, "clio-coder:")
+		.replace(/^(\s*source:\s*)clio\s*$/gmu, "$1clio-coder");
+}
+
+function installedHash(raw: string): string | null {
+	const match = raw.match(/^\s*installed-hash:\s*["']?([0-9a-f]{64})["']?\s*$/mu);
+	return match?.[1] ?? null;
+}
+
+function regularFiles(root: string, current = root): string[] {
+	const out: string[] = [];
+	for (const entry of readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+		const full = path.join(current, entry.name);
+		if (entry.isDirectory()) out.push(...regularFiles(root, full));
+		else if (entry.isFile()) out.push(path.relative(root, full));
+		else return [];
+	}
+	return out;
+}
+
+function provesUnmodifiedShippedCopy(legacyDir: string, canonicalBundleDir: string): boolean {
+	let legacyFiles: string[];
+	let canonicalFiles: string[];
+	try {
+		legacyFiles = regularFiles(legacyDir);
+		canonicalFiles = regularFiles(canonicalBundleDir);
+	} catch {
+		return false;
+	}
+	if (legacyFiles.length === 0 || legacyFiles.join("\0") !== canonicalFiles.join("\0")) return false;
+	for (const relative of legacyFiles) {
+		const legacyRaw = readFileSync(path.join(legacyDir, relative), "utf8");
+		const canonicalRaw = readFileSync(path.join(canonicalBundleDir, relative), "utf8");
+		if (relative === "SKILL.md") {
+			const recordedHash = installedHash(legacyRaw);
+			if (recordedHash === null || recordedHash !== normalizedSkillHash(legacyRaw)) return false;
+			if (canonicalizeNamingText(stripProvenanceFrontmatter(legacyRaw)) !== stripProvenanceFrontmatter(canonicalRaw))
+				return false;
+			continue;
+		}
+		if (canonicalizeNamingText(legacyRaw) !== canonicalRaw) return false;
+	}
+	return true;
+}
+
+function rewriteStagedCopy(stage: string, canonicalBundleDir: string): void {
+	const canonicalSkillHash = normalizedSkillHash(readFileSync(path.join(canonicalBundleDir, "SKILL.md"), "utf8"));
+	for (const relative of regularFiles(stage)) {
+		const file = path.join(stage, relative);
+		let next = canonicalizeNamingText(readFileSync(file, "utf8"));
+		if (relative === "SKILL.md") {
+			next = next.replace(/^(\s*installed-hash:\s*).+$/mu, `$1"${canonicalSkillHash}"`);
+		}
+		writeFileSync(file, next, "utf8");
+	}
+}
+
+let resourceSwapSequence = 0;
+
+function migrateProvenSkill(legacyDir: string, canonicalDir: string, canonicalBundleDir: string): void {
+	const suffix = `${process.pid}-${++resourceSwapSequence}`;
+	const stage = `${canonicalDir}.clio-coder-naming-stage-${suffix}`;
+	const backup = `${legacyDir}.clio-coder-naming-backup-${suffix}`;
+	mkdirSync(path.dirname(canonicalDir), { recursive: true });
+	cpSync(legacyDir, stage, { recursive: true });
+	try {
+		rewriteStagedCopy(stage, canonicalBundleDir);
+		renameSync(legacyDir, backup);
+		try {
+			renameSync(stage, canonicalDir);
+		} catch (error) {
+			renameSync(backup, legacyDir);
+			throw error;
+		}
+		rmSync(backup, { recursive: true, force: true });
+		fsyncDirectory(path.dirname(canonicalDir));
+	} catch (error) {
+		rmSync(stage, { recursive: true, force: true });
+		throw error;
+	}
+}
+
+function existingDirectory(candidate: string): boolean {
+	try {
+		return statSync(candidate).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/** Inspect only the selected user root and current project; never scan arbitrary repositories. */
+export function inspectInstalledNamingResources(options: NamingResourceOptions = {}): NamingResourceReport[] {
+	const cwd = options.cwd ?? process.cwd();
+	const configDir = options.configDir ?? resolveClioDirs().config;
+	const packageRoot = options.packageRoot ?? resolvePackageRoot();
+	const roots = [path.join(configDir, "skills"), path.join(cwd, ".clio-coder", "skills")];
+	const reports: NamingResourceReport[] = [];
+	for (const root of roots) {
+		for (const [legacyName, canonicalName] of LEGACY_SKILL_NAMES) {
+			const legacyPath = path.join(root, legacyName);
+			const canonicalPath = path.join(root, canonicalName);
+			if (!existingDirectory(legacyPath)) {
+				reports.push({ kind: "skill", legacyPath, canonicalPath, status: "absent", detail: "legacy skill absent" });
+				continue;
+			}
+			if (existsSync(canonicalPath)) {
+				reports.push({
+					kind: "skill",
+					legacyPath,
+					canonicalPath,
+					status: "canonical-present",
+					detail: "canonical skill already exists; legacy copy left untouched",
+				});
+				continue;
+			}
+			const canonicalBundleDir = path.join(packageRoot, "skills", "meta", canonicalName);
+			if (!existingDirectory(canonicalBundleDir) || !provesUnmodifiedShippedCopy(legacyPath, canonicalBundleDir)) {
+				reports.push({
+					kind: "skill",
+					legacyPath,
+					canonicalPath,
+					status: "modified",
+					detail: "frontmatter/provenance/hash do not prove an unmodified shipped copy; left untouched",
+				});
+				continue;
+			}
+			if (options.fix) migrateProvenSkill(legacyPath, canonicalPath, canonicalBundleDir);
+			reports.push({
+				kind: "skill",
+				legacyPath,
+				canonicalPath,
+				status: options.fix ? "renamed" : "renamable",
+				detail: options.fix
+					? "proven unmodified shipped copy renamed and canonicalized"
+					: "proven unmodified shipped copy can be renamed by doctor --fix",
+			});
+		}
+	}
+	return reports;
+}
+
+export interface ModelOverlayNamingInspection {
+	path: string;
+	legacyFile: boolean;
+	legacyMetadataKeys: number;
+}
+
+export interface SkillMetadataNamingInspection {
+	path: string;
+	legacyMetadataKey: boolean;
+}
+
+function collectSkillFiles(root: string, current = root): string[] {
+	if (!existingDirectory(current)) return [];
+	const out: string[] = [];
+	for (const entry of readdirSync(current, { withFileTypes: true })) {
+		const full = path.join(current, entry.name);
+		if (entry.isDirectory()) out.push(...collectSkillFiles(root, full));
+		else if (entry.isFile() && entry.name === "SKILL.md") out.push(full);
+	}
+	return out;
+}
+
+/** Read-only inventory of released skill metadata keys in selected Clio Coder roots. */
+export function inspectSkillMetadataNaming(
+	options: Pick<NamingResourceOptions, "cwd" | "configDir"> = {},
+): SkillMetadataNamingInspection[] {
+	const cwd = options.cwd ?? process.cwd();
+	const configDir = options.configDir ?? resolveClioDirs().config;
+	const roots = [path.join(configDir, "skills"), path.join(cwd, ".clio-coder", "skills")];
+	return roots.flatMap((root) =>
+		collectSkillFiles(root).map((file) => ({
+			path: file,
+			legacyMetadataKey: /^clio:\s*(?:#.*)?$/mu.test(readFileSync(file, "utf8")),
+		})),
+	);
+}
+
+function countLegacyModelMetadata(value: unknown): number {
+	if (Array.isArray(value)) return value.reduce((count, entry) => count + countLegacyModelMetadata(entry), 0);
+	if (typeof value !== "object" || value === null) return 0;
+	const record = value as Record<string, unknown>;
+	return (
+		(Object.hasOwn(record, "clio") ? 1 : 0) +
+		Object.values(record).reduce<number>((count, entry) => count + countLegacyModelMetadata(entry), 0)
+	);
+}
+
+/** Read-only overlay inventory. User catalog files are never silently rewritten. */
+export function inspectModelOverlayNaming(
+	options: Pick<NamingResourceOptions, "cwd" | "configDir"> = {},
+): ModelOverlayNamingInspection[] {
+	const cwd = options.cwd ?? process.cwd();
+	const configDir = options.configDir ?? resolveClioDirs().config;
+	const roots = [path.join(configDir, "model-catalog.d"), path.join(cwd, ".clio-coder", "model-catalog.d")];
+	const inspections: ModelOverlayNamingInspection[] = [];
+	for (const root of roots) {
+		if (!existingDirectory(root)) continue;
+		for (const entry of readdirSync(root, { withFileTypes: true })) {
+			if (!entry.isFile() || (!entry.name.endsWith(".yaml") && !entry.name.endsWith(".yml"))) continue;
+			const file = path.join(root, entry.name);
+			let legacyMetadataKeys = 0;
+			try {
+				legacyMetadataKeys = countLegacyModelMetadata(parseYaml(readFileSync(file, "utf8")));
+			} catch {
+				// The catalog loader owns the parse diagnostic; naming still reports the filename.
+			}
+			inspections.push({
+				path: file,
+				legacyFile: entry.name === "clio-local-coding-targets.yaml",
+				legacyMetadataKeys,
+			});
+		}
+	}
+	return inspections;
+}

package/src/domains/lifecycle/naming-tool-markers.ts

@@ -0,0 +1,139 @@
+import { existsSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+import { fsyncDirectory } from "../../core/safe-resource-write.js";
+import { resolveClioDirs } from "../../core/xdg.js";
+import { findPinnedTool } from "../toolchain/registry.js";
+
+export const LEGACY_TOOL_MARKER = "clio-install.json";
+export const CANONICAL_TOOL_MARKER = "clio-coder-install.json";
+
+interface ValidToolMarker {
+	id: string;
+	version: string;
+	sha256: string;
+}
+
+export type ToolMarkerNamingStatus =
+	| "renamable"
+	| "renamed"
+	| "invalid-legacy"
+	| "canonical-conflict"
+	| "agreeing-duplicate"
+	| "duplicate-removed";
+
+export interface ToolMarkerNamingReport {
+	tool: string;
+	version: string;
+	legacyPath: string;
+	canonicalPath: string;
+	status: ToolMarkerNamingStatus;
+	detail: string;
+}
+
+export interface ToolMarkerNamingOptions {
+	dataDir?: string;
+	fix?: boolean;
+}
+
+function childDirectories(root: string): string[] {
+	try {
+		return readdirSync(root, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+			.map((entry) => entry.name)
+			.sort((left, right) => left.localeCompare(right));
+	} catch {
+		return [];
+	}
+}
+
+function readValidMarker(path: string, tool: string, version: string): ValidToolMarker | null {
+	try {
+		const value: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+		const marker = value as Record<string, unknown>;
+		if (marker.id !== tool || marker.version !== version) return null;
+		if (typeof marker.sha256 !== "string" || !/^[0-9a-f]{64}$/u.test(marker.sha256)) return null;
+		return { id: tool, version, sha256: marker.sha256 };
+	} catch {
+		return null;
+	}
+}
+
+function sameFacts(left: ValidToolMarker, right: ValidToolMarker): boolean {
+	return left.id === right.id && left.version === right.version && left.sha256 === right.sha256;
+}
+
+/**
+ * Inspect or migrate released tool markers only below known tool/version
+ * directories in the selected Clio Coder data root. Unknown tool roots and
+ * symlinks are never traversed.
+ */
+export function inspectToolMarkerNaming(options: ToolMarkerNamingOptions = {}): ToolMarkerNamingReport[] {
+	const toolsRoot = join(options.dataDir ?? resolveClioDirs().data, "tools");
+	const reports: ToolMarkerNamingReport[] = [];
+	for (const tool of childDirectories(toolsRoot)) {
+		if (findPinnedTool(tool) === null) continue;
+		for (const version of childDirectories(join(toolsRoot, tool))) {
+			const dir = join(toolsRoot, tool, version);
+			const legacyPath = join(dir, LEGACY_TOOL_MARKER);
+			if (!existsSync(legacyPath)) continue;
+			const canonicalPath = join(dir, CANONICAL_TOOL_MARKER);
+			const legacy = readValidMarker(legacyPath, tool, version);
+			if (legacy === null) {
+				reports.push({
+					tool,
+					version,
+					legacyPath,
+					canonicalPath,
+					status: "invalid-legacy",
+					detail: "legacy marker does not match its known tool/version path and checksum shape; left untouched",
+				});
+				continue;
+			}
+			if (!existsSync(canonicalPath)) {
+				if (options.fix) {
+					renameSync(legacyPath, canonicalPath);
+					fsyncDirectory(dir);
+				}
+				reports.push({
+					tool,
+					version,
+					legacyPath,
+					canonicalPath,
+					status: options.fix ? "renamed" : "renamable",
+					detail: options.fix ? "validated legacy marker renamed atomically" : "validated legacy marker can be renamed",
+				});
+				continue;
+			}
+			const canonical = readValidMarker(canonicalPath, tool, version);
+			if (canonical === null || !sameFacts(legacy, canonical)) {
+				reports.push({
+					tool,
+					version,
+					legacyPath,
+					canonicalPath,
+					status: "canonical-conflict",
+					detail:
+						"canonical and legacy marker facts disagree or canonical is invalid; canonical wins and legacy is left untouched",
+				});
+				continue;
+			}
+			if (options.fix) {
+				rmSync(legacyPath);
+				fsyncDirectory(dir);
+			}
+			reports.push({
+				tool,
+				version,
+				legacyPath,
+				canonicalPath,
+				status: options.fix ? "duplicate-removed" : "agreeing-duplicate",
+				detail: options.fix
+					? "validated agreeing legacy duplicate removed; canonical marker kept"
+					: "canonical and legacy facts agree; legacy duplicate can be removed",
+			});
+		}
+	}
+	return reports;
+}

package/src/domains/lifecycle/naming-yazi.ts

@@ -0,0 +1,81 @@
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { resolveClioDirs } from "../../core/xdg.js";
+import { ensureYaziProfile, resetYaziProfile, yaziProfileDir } from "../mux/yazi/profile.js";
+import { resolveToolBinary } from "../toolchain/resolve.js";
+
+export interface YaziNamingInspection {
+	profileDir: string;
+	present: boolean;
+	legacyEvents: number;
+	legacyEnvironmentNames: number;
+}
+
+export interface YaziNamingRegenerationReport extends YaziNamingInspection {
+	status: "absent" | "canonical" | "regenerated" | "removed-unresolved" | "regeneration-failed";
+	detail: string;
+}
+
+export interface YaziNamingOptions {
+	cacheDir?: string;
+	yaziPath?: string | null;
+	yaPath?: string | null;
+}
+
+function occurrences(text: string, pattern: RegExp): number {
+	return [...text.matchAll(pattern)].length;
+}
+
+/** Inspect only the generated keymap below the selected Clio Coder cache root. */
+export function inspectYaziNaming(cacheDir: string = resolveClioDirs().cache): YaziNamingInspection {
+	const profileDir = yaziProfileDir(cacheDir);
+	const present = statSync(profileDir, { throwIfNoEntry: false })?.isDirectory() === true;
+	let keymap = "";
+	try {
+		keymap = readFileSync(join(profileDir, "keymap.toml"), "utf8");
+	} catch {
+		// Missing or unreadable generated material is handled as disposable cache.
+	}
+	return {
+		profileDir,
+		present,
+		legacyEvents: occurrences(keymap, /(?<!clio-coder-)clio-pick/gmu),
+		legacyEnvironmentNames: occurrences(keymap, /\$CLIO_YAZI_PICK_TOKEN\b/gmu),
+	};
+}
+
+/**
+ * Replace the disposable managed profile from current inputs. Resolution is
+ * performed before removal so the report can state why a profile could not be
+ * rebuilt, while deletion remains confined to `<cache>/yazi/profile`.
+ */
+export function regenerateYaziNamingProfile(options: YaziNamingOptions = {}): YaziNamingRegenerationReport {
+	const cacheDir = options.cacheDir ?? resolveClioDirs().cache;
+	const before = inspectYaziNaming(cacheDir);
+	if (!before.present) {
+		return { ...before, status: "absent", detail: "managed Yazi profile is absent; next open writes canonical names" };
+	}
+	if (before.legacyEvents === 0 && before.legacyEnvironmentNames === 0) {
+		return { ...before, status: "canonical", detail: "managed Yazi profile already uses canonical names" };
+	}
+	const yaziPath = options.yaziPath === undefined ? resolveToolBinary("yazi").binaryPath : options.yaziPath;
+	const yaPath = options.yaPath === undefined ? resolveToolBinary("ya").binaryPath : options.yaPath;
+	resetYaziProfile(before.profileDir);
+	if (!yaziPath || !yaPath) {
+		return {
+			...before,
+			status: "removed-unresolved",
+			detail: "legacy managed profile removed; Yazi/ya is unresolved, so the next managed open will regenerate it",
+		};
+	}
+	const profile = ensureYaziProfile({ yaziPath, yaPath, profileDir: before.profileDir });
+	if (!profile) {
+		return {
+			...before,
+			status: "regeneration-failed",
+			detail: "legacy managed profile removed, but current Yazi rejected the regenerated profile",
+		};
+	}
+	return { ...before, status: "regenerated", detail: "managed Yazi profile regenerated with canonical names" };
+}

package/src/domains/lifecycle/upgrade-notice.ts

@@ -27,7 +27,7 @@ const KEYBOARD_FACING_CHANGES: Readonly<Record<string, string>> = Object.freeze(
  */
 export function describeUpgradeNotice(transition: UpgradeTransition): string {
 	const changes = KEYBOARD_FACING_CHANGES[transition.to];
-	const head = `clio: upgraded ${transition.from} → ${transition.to}.`;
+	const head = `clio-coder: upgraded ${transition.from} → ${transition.to}.`;
 	const tail = `Full notes: CHANGELOG.md, section ${transition.to}.`;
 	return changes === undefined
 		? `${head} What changed is in CHANGELOG.md, section ${transition.to}.`

package/src/domains/memory/task-memory-handoff.ts

@@ -11,7 +11,8 @@ import {
 } from "./task-bank.js";
 
 export const TASK_MEMORY_HANDOFF_VERSION = 2;
-export const TASK_MEMORY_HANDOFF_LANGUAGE = "clio-task-memory";
+export const TASK_MEMORY_HANDOFF_LANGUAGE = "clio-coder-task-memory";
+const LEGACY_TASK_MEMORY_HANDOFF_LANGUAGE = "clio-task-memory";
 const HANDOFF_MAX_BYTES = 1_000_000;
 
 export interface TaskMemoryHandoffEntry {
@@ -134,8 +135,10 @@ export function renderTaskMemoryHandoffSource(
 
 export function parseTaskMemoryHandoffSnapshot(text: string): TaskMemoryHandoffSnapshot | null {
 	if (typeof text !== "string" || text.length === 0 || text.length > HANDOFF_MAX_BYTES) return null;
-	const escapedLanguage = TASK_MEMORY_HANDOFF_LANGUAGE.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-	const match = new RegExp(`(?:^|\\n)\\x60{3}${escapedLanguage}\\r?\\n([^\\r\\n]+)\\r?\\n\\x60{3}(?:$|\\n)`, "u").exec(
+	const languages = [TASK_MEMORY_HANDOFF_LANGUAGE, LEGACY_TASK_MEMORY_HANDOFF_LANGUAGE]
+		.map((language) => language.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"))
+		.join("|");
+	const match = new RegExp(`(?:^|\\n)\\x60{3}(?:${languages})\\r?\\n([^\\r\\n]+)\\r?\\n\\x60{3}(?:$|\\n)`, "u").exec(
 		text,
 	);
 	if (match?.[1] === undefined) return null;

package/src/domains/middleware/index.ts

@@ -74,6 +74,13 @@ export {
 	spawnSyncCommandRunner,
 } from "./hooks-io.js";
 export { MiddlewareManifest } from "./manifest.js";
+export {
+	createMarketplaceOfferRegistration,
+	MARKETPLACE_OFFER_REGISTRATION_ID,
+	type MarketplaceOfferDeps,
+	marketplaceAutoInstallReminder,
+	marketplaceOfferReminder,
+} from "./marketplace-offer.js";
 export {
 	createMemoryInterventionRegistration,
 	MEMORY_INTERVENTION_DEFAULT_MAX_TOKENS,