@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/cli/context-map.ts

@@ -0,0 +1,114 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { CLIO_ARTIFACT_DIR } from "../core/artifact-paths.js";
+import { readCodewiki } from "../domains/context/codewiki/artifact.js";
+import { buildArchitectureSeed, serializeArchitectureSeed } from "../domains/context/wiki/map-seed.js";
+
+const HELP = `Usage:
+  clio-coder context map [--out <path>] [--json]
+
+Write an archify architecture seed for the current repository from the codewiki
+index, without model calls. The seed is the starting spec for the archify skill:
+components are the largest directory areas, connections are collapsed import
+edges, and sources point at indexed files and lines.
+
+Options:
+  --out <path>    where to write the seed (default: ${CLIO_ARTIFACT_DIR}/maps/<repo>.architecture.json)
+  --json          print machine-readable details about the written seed
+`;
+
+/** Where the seed lands when the operator names no path: a human-transient map artifact. */
+function defaultMapSeedPath(cwd: string): string {
+	return path.join(cwd, CLIO_ARTIFACT_DIR, "maps", `${path.basename(cwd)}.architecture.json`);
+}
+
+function gitValue(cwd: string, args: string[]): string | null {
+	try {
+		const out = execFileSync("git", args, { cwd, timeout: 5000, stdio: ["ignore", "pipe", "ignore"] })
+			.toString("utf8")
+			.trim();
+		return out.length > 0 ? out : null;
+	} catch {
+		return null;
+	}
+}
+
+/** The origin remote as an https URL and HEAD as a full sha, when git can say. */
+function repositoryFacts(cwd: string): { url: string; revision: string } | undefined {
+	const remote = gitValue(cwd, ["remote", "get-url", "origin"]);
+	const revision = gitValue(cwd, ["rev-parse", "--verify", "HEAD"]);
+	if (!remote || !revision) return undefined;
+	let url = remote.endsWith(".git") ? remote.slice(0, -4) : remote;
+	const ssh = /^git@([^:]+):(.+)$/.exec(url);
+	if (ssh) url = `https://${ssh[1]}/${ssh[2]}`;
+	return { url, revision };
+}
+
+export async function runContextMapCommand(args: string[]): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	let out: string | null = null;
+	let json = false;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index] as string;
+		if (arg === "--json") {
+			json = true;
+			continue;
+		}
+		if (arg === "--out") {
+			const value = args[index + 1];
+			if (!value || value.startsWith("--")) {
+				process.stderr.write("clio-coder context map: --out requires a path\n");
+				return 2;
+			}
+			out = value;
+			index += 1;
+			continue;
+		}
+		process.stderr.write(`clio-coder context map: unknown flag ${arg}\n`);
+		return 2;
+	}
+	const cwd = process.cwd();
+	const codewiki = readCodewiki(cwd);
+	if (!codewiki) {
+		process.stderr.write(
+			"clio-coder context map: no codewiki index in .clio-coder/codewiki.json; run `clio-coder context index` first\n",
+		);
+		return 1;
+	}
+	const seed = buildArchitectureSeed(codewiki, {
+		title: path.basename(cwd),
+		repository: repositoryFacts(cwd),
+	});
+	const target = out ? path.resolve(cwd, out) : defaultMapSeedPath(cwd);
+	mkdirSync(path.dirname(target), { recursive: true });
+	writeFileSync(target, serializeArchitectureSeed(seed), "utf8");
+	const payload = {
+		path: target,
+		components: seed.components.length,
+		connections: seed.connections.length,
+		repository: seed.meta.repository ?? null,
+	};
+	if (json) {
+		process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+		return 0;
+	}
+	process.stdout.write(
+		[
+			`clio-coder context map wrote ${target}`,
+			`  ${payload.components} components, ${payload.connections} connections${
+				payload.repository
+					? `, sources pinned at ${payload.repository.revision.slice(0, 12)}`
+					: "; no GitHub origin at a full revision, so no source citations"
+			}`,
+			payload.repository
+				? "  next: validate and deliver it with the archify skill, passing --repo-root ."
+				: "  next: validate and deliver it with the archify skill (without --repo-root)",
+			"",
+		].join("\n"),
+	);
+	return 0;
+}

package/src/cli/context.ts

@@ -10,6 +10,7 @@ const HELP = `Usage:
                     [--target <id>] [--model <id>] [--thinking off|low|medium|high]
   clio-coder context reset [--all] [--yes]
   clio-coder context index [--json]
+  clio-coder context map [--out <path>] [--json]
   clio-coder context replay --sessions <path>... [options]
   clio-coder context working-set --session <id|path>
 
@@ -20,6 +21,7 @@ Project context commands:
   clio-coder context wiki         generate or inspect the agent-authored Markdown wiki
   clio-coder context reset        clear accumulated project context artifacts
   clio-coder context index        build the codewiki index without model calls
+  clio-coder context map          write an archify architecture seed from the codewiki index
   clio-coder context replay       compare working-set policies over Clio ledgers
   clio-coder context working-set  inspect one session's working-set fold and path index
 `;
@@ -317,6 +319,8 @@ export async function runContextCommand(args: string[]): Promise<number> {
 			return (await import("./context-clear.js")).runContextClearCommand(rest);
 		case "index":
 			return (await import("./context-index.js")).runContextIndexCommand(rest);
+		case "map":
+			return (await import("./context-map.js")).runContextMapCommand(rest);
 		case "replay":
 			return (await import("./context-working-set.js")).runContextReplayCommand(rest);
 		case "working-set":

package/src/cli/docs.ts

@@ -1,13 +1,13 @@
 import { spawn } from "node:child_process";
-import { createReadStream, readdirSync, statSync } from "node:fs";
+import { createReadStream, readdirSync, realpathSync, statSync } from "node:fs";
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import type { AddressInfo } from "node:net";
 import { relative, resolve } from "node:path";
 import chalk from "chalk";
 import { resolvePackageRoot } from "../core/package-root.js";
-import { printError, printHeader } from "./shared.js";
+import { printError, printHeader } from "./argv.js";
 
-// Human-facing viewer over the bundled HTML blueprints. It binds an ephemeral
+// Human-facing viewer over the source-checkout HTML blueprints. It binds an ephemeral
 // static file server to 127.0.0.1 only, serves docs/html/index.html as the
 // menu plus the blueprint pages, prints the URL, and runs until SIGINT. It
 // uses only Node's built-in http and fs: zero new dependencies, no daemon, no
@@ -21,7 +21,8 @@ const HELP = `clio-coder docs [topic] [--no-open]
 
 Serve Clio Coder's interactive HTML documentation locally and open it in a
 browser. The blueprints live in docs/html of a source checkout; the npm package
-ships the Markdown guides in docs/ only. The server binds an ephemeral port on
+ships the categorized Markdown reference tree under docs/ and excludes HTML.
+The server binds an ephemeral port on
 127.0.0.1, keeps no state, runs no daemon, and reaches no external network.
 Press Ctrl+C to stop it.
 
@@ -64,7 +65,7 @@ export interface DocsMenuEntry {
 	label: string;
 }
 
-/** Resolve docs/html from the package root; present in a source checkout, absent from the npm package. */
+/** Resolve the source-checkout HTML root. The npm package deliberately excludes it. */
 function resolveDocsHtmlDir(): string {
 	return resolve(resolvePackageRoot(), "docs", "html");
 }
@@ -159,8 +160,8 @@ function listHtmlFiles(htmlDir: string): string[] {
 }
 
 /** Build the static request handler for one html root. */
-function createDocsRequestHandler(htmlDir: string): (req: IncomingMessage, res: ServerResponse) => void {
-	const root = resolve(htmlDir);
+export function createDocsRequestHandler(htmlDir: string): (req: IncomingMessage, res: ServerResponse) => void {
+	const root = realpathSync(resolve(htmlDir));
 	return (req, res) => {
 		if (req.method !== "GET" && req.method !== "HEAD") {
 			res.writeHead(405, { "content-type": "text/plain; charset=utf-8", allow: "GET, HEAD" });
@@ -174,20 +175,27 @@ function createDocsRequestHandler(htmlDir: string): (req: IncomingMessage, res:
 			res.end(resolved.reason);
 			return;
 		}
-		const target = resolve(root, resolved.relative);
-		if (!isWithin(target, root)) {
+		const requestedTarget = resolve(root, resolved.relative);
+		if (!isWithin(requestedTarget, root)) {
 			res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
 			res.end("forbidden");
 			return;
 		}
 		let size: number | null = null;
+		let target: string | null = null;
 		try {
+			target = realpathSync(requestedTarget);
+			if (!isWithin(target, root)) {
+				res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
+				res.end("forbidden");
+				return;
+			}
 			const stat = statSync(target);
 			if (stat.isFile()) size = stat.size;
 		} catch {
 			size = null;
 		}
-		if (size === null) {
+		if (size === null || target === null) {
 			res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
 			res.end("not found");
 			return;
@@ -263,7 +271,7 @@ function openBrowser(url: string): void {
 	}
 }
 
-function waitForShutdown(): Promise<void> {
+export function waitForShutdown(): Promise<void> {
 	return new Promise((resolveShutdown) => {
 		const onSignal = (): void => {
 			process.removeListener("SIGINT", onSignal);
@@ -304,14 +312,14 @@ export async function runDocsCommand(args: ReadonlyArray<string> = []): Promise<
 	try {
 		htmlDir = resolveDocsHtmlDir();
 	} catch (err) {
-		printError(`could not resolve bundled docs: ${err instanceof Error ? err.message : String(err)}`);
+		printError(`could not resolve the docs HTML root: ${err instanceof Error ? err.message : String(err)}`);
 		return 1;
 	}
 	const files = listHtmlFiles(htmlDir);
 	if (files.length === 0) {
 		printError(`no HTML docs at ${htmlDir}`);
 		process.stdout.write(
-			`  the npm package ships the Markdown guides only: ${resolve(resolvePackageRoot(), "docs")}\n` +
+			`  the npm package ships only the categorized Markdown reference tree: ${resolve(resolvePackageRoot(), "docs")}\n` +
 				"  the interactive blueprints are in a source checkout and at https://github.com/iowarp/clio-coder/tree/main/docs/html\n",
 		);
 		return 1;
@@ -333,7 +341,7 @@ export async function runDocsCommand(args: ReadonlyArray<string> = []): Promise<
 	const handle = await startDocsServer({ htmlDir });
 	const landingUrl = landing === "index.html" ? handle.url : `${handle.url}${landing}`;
 	printHeader("Clio docs viewer");
-	process.stdout.write(`  serving ${htmlDir}\n`);
+	process.stdout.write(`  serving HTML root ${htmlDir}\n`);
 	process.stdout.write(`  open ${chalk.cyan(landingUrl)}\n`);
 	process.stdout.write("  bound to 127.0.0.1 only: no external network, no daemon, no state.\n");
 	process.stdout.write("  press Ctrl+C to stop.\n");

package/src/cli/doctor-naming.ts

@@ -88,7 +88,7 @@ function namingResourceFindings(options: NamingDoctorOptions): DoctorFinding[] {
 					`${renamed} proven skills renamed`,
 					`${renamable} proven skills await doctor --fix`,
 					`${conflicts} modified/conflicting skills left untouched`,
-					`${skillMetadata.length} legacy skill metadata keys`,
+					`${skillMetadata.length} legacy skill metadata keys${skillMetadata.length > 0 ? ` (rename \`clio:\` to \`clio-coder:\` in ${skillMetadata.map((entry) => entry.path).join(", ")})` : ""}`,
 					`${overlays.length} legacy model overlay files/metadata (manual migration required)`,
 				].join("; "),
 			},
@@ -145,7 +145,7 @@ function yaziNamingFinding(fix: boolean, enabled: boolean): DoctorFinding {
 	if (!enabled) {
 		return {
 			ok: true,
-			name: "naming yazi profile",
+			name: "naming files profile",
 			detail: "disabled by settings",
 		};
 	}
@@ -154,7 +154,7 @@ function yaziNamingFinding(fix: boolean, enabled: boolean): DoctorFinding {
 	if (legacy === 0) {
 		return {
 			ok: true,
-			name: "naming yazi profile",
+			name: "naming files profile",
 			detail: inspection.present
 				? `${inspection.profileDir} uses canonical event and environment identifiers`
 				: `${inspection.profileDir} is absent; the next managed open will generate canonical identifiers`,
@@ -164,7 +164,7 @@ function yaziNamingFinding(fix: boolean, enabled: boolean): DoctorFinding {
 		return {
 			ok: true,
 			level: "warn",
-			name: "naming yazi profile",
+			name: "naming files profile",
 			detail: `${inspection.profileDir}: ${inspection.legacyEvents} legacy events and ${inspection.legacyEnvironmentNames} legacy environment names (run \`clio-coder doctor --fix\`)`,
 		};
 	}
@@ -172,7 +172,7 @@ function yaziNamingFinding(fix: boolean, enabled: boolean): DoctorFinding {
 	return {
 		ok: report.status !== "regeneration-failed",
 		...(report.status === "regeneration-failed" ? {} : { level: "ok" as const }),
-		name: "naming yazi profile",
+		name: "naming files profile",
 		detail: report.detail,
 	};
 }

package/src/cli/doctor-toolchain.ts

@@ -16,7 +16,7 @@ function yaziProfileFinding(enabled: boolean): DoctorFinding {
 	if (!enabled) {
 		return {
 			ok: true,
-			name: "yazi managed profile",
+			name: "files pane profile",
 			detail: "disabled by settings",
 		};
 	}
@@ -24,14 +24,14 @@ function yaziProfileFinding(enabled: boolean): DoctorFinding {
 		const profile = inspectCurrentYaziProfile();
 		return {
 			ok: true,
-			name: "yazi managed profile",
+			name: "files pane profile",
 			detail: describeYaziProfile(profile),
 			level: profile.state === "current" ? "ok" : "warn",
 		};
 	} catch (error) {
 		return {
 			ok: true,
-			name: "yazi managed profile",
+			name: "files pane profile",
 			level: "warn",
 			detail: `${yaziProfileDir()} could not be inspected (${error instanceof Error ? error.message : String(error)}); user config ${userYaziConfigDir()} is separate and untouched`,
 		};

package/src/cli/eval.ts

@@ -115,8 +115,7 @@ function parseEvalArgs(args: ReadonlyArray<string>): ParsedEvalArgs {
 				index += 1;
 				continue;
 			}
-			// `--clio-entry` is the pre-0.3.1 spelling and still parses.
-			if (arg === "--clio-coder-entry" || arg === "--clio-entry") {
+			if (arg === "--clio-coder-entry") {
 				parsed.clioEntry = requiredValue(args, index, arg);
 				index += 1;
 				continue;

package/src/cli/extensions.ts

@@ -91,10 +91,11 @@ function resourceSummary(extension: InstalledExtension): string {
 }
 
 function stateLabel(extension: InstalledExtension): string {
+	if (!extension.valid) return "invalid";
 	if (!extension.compatible) return "incompatible";
 	if (!extension.enabled) return "disabled";
 	if (!extension.effective) return `shadowed:${extension.overriddenBy ?? "higher"}`;
-	return "active";
+	return extension.loadable ? "active" : "inactive";
 }
 
 function printList(items: ReadonlyArray<InstalledExtension>): void {

package/src/cli/fleet.ts

@@ -373,7 +373,7 @@ async function runFleet(args: ReadonlyArray<string>): Promise<number> {
 		return fail("required domains unavailable (dispatch/agents/safety)");
 	}
 	const fleetSettings = config?.get() ?? readSettings();
-	// Install `panes.journal` the same way the interactive composition root
+	// Install `fleet.history.journal` the same way the interactive composition root
 	// does, so a fleet run honours the setting without the journal ever reading
 	// settings.yaml from the dispatch event path.
 	configureRunEventJournal(fleetSettings.fleet.history.journal);

package/src/cli/index.ts

@@ -48,6 +48,7 @@ Usage:
   clio-coder auth list|status|login|logout [target-or-runtime]
   clio-coder doctor [--fix]       diagnose state; --fix creates or repairs it
   clio-coder paths [--json]       print resolved config/data/cache directories
+  clio-coder config inspect [--json]  inspect effective customization and provenance
   clio-coder reset                recover or wipe Clio Coder state
   clio-coder context              show project context status (CLIO-CODER.md, preload, codewiki)
   clio-coder context init [--yes] [--preview|--heuristic]  explore the repo and bootstrap CLIO-CODER.md and codewiki
@@ -55,6 +56,7 @@ Usage:
   clio-coder context wiki [--update] [--status] [--depth auto|simple|medium|detailed] [--target <id>] [--model <id>]
   clio-coder context reset [--all] [--yes]  clear accumulated project context artifacts
   clio-coder context index [--json]  build the codewiki index without model calls
+  clio-coder context map [--out <path>] [--json]  write an archify architecture seed from the codewiki index
   clio-coder context replay --sessions <path>...  compare working-set policies over Clio ledgers
   clio-coder context working-set --session <id|path>  inspect one session's working-set state
   clio-coder uninstall            remove all Clio Coder state; --remove-binary also unlinks the launcher
@@ -72,7 +74,7 @@ Usage:
   clio-coder verifiers            discover, inspect, author, validate, edit, or dry-run project checks
   clio-coder tools list|status|install|remove <id>  pinned external programs Clio can drive
   clio-coder interop inspect --json  detected external coding agents and how far each one is wired
-  clio-coder panes install        install the pane multiplexer (alias for 'tools install herdr')
+  clio-coder panes install|theme  install the pane multiplexer (alias for 'tools install herdr'), or print Clio's theme as a herdr block
   clio-coder docs [topic]         serve the HTML docs of a source checkout on 127.0.0.1 (--no-open to skip browser)
   clio-coder dev <command>        harness instruments; run 'clio-coder dev' for the list
   clio-coder --help, -h           this message

package/src/cli/internal-dispatch.ts

@@ -9,7 +9,7 @@
  * operator cancel.
  */
 
-import { GUARDRAIL_ENV_VARS, resolveGuardrail } from "../core/guardrails.js";
+import { resolveGuardrail } from "../core/guardrails.js";
 import type { DispatchContract } from "../domains/dispatch/contract.js";
 
 export interface InternalDispatchDeadline {
@@ -25,10 +25,9 @@ export function armInternalDispatchDeadline(
 	dispatch: DispatchContract,
 	runId: string,
 	label: string,
-	env: NodeJS.ProcessEnv = process.env,
 	maxTimeoutMs?: number,
 ): InternalDispatchDeadline {
-	const configuredTimeoutMs = resolveGuardrail("internalDispatchTimeoutMs", env);
+	const configuredTimeoutMs = resolveGuardrail("internalDispatchTimeoutMs");
 	const timeoutMs =
 		maxTimeoutMs === undefined ? configuredTimeoutMs : Math.min(configuredTimeoutMs, Math.max(1, maxTimeoutMs));
 	const productCapped = timeoutMs < configuredTimeoutMs;
@@ -50,6 +49,6 @@ export function armInternalDispatchDeadline(
 			productCapped
 				? `${label} exceeded its ${Math.round(timeoutMs / 1000)}s latency ceiling and was aborted.`
 				: `${label} timed out after ${Math.round(timeoutMs / 1000)}s and was aborted. ` +
-					`Raise guardrails.internalDispatchTimeoutMs (env ${GUARDRAIL_ENV_VARS.internalDispatchTimeoutMs}) for slower targets.`,
+					"Raise fleet.limits.internalRunTimeoutMs for slower targets.",
 	};
 }