@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/context/project-rules.ts

@@ -0,0 +1,227 @@
+/**
+ * Path-scoped project rules under `.clio-coder/rules/**\/*.md`. A rule is a markdown
+ * file with optional YAML frontmatter:
+ *
+ *   - `paths:`    activation globs. When present the rule is path-scoped and
+ *                 activates only while a matching file is already in working
+ *                 context. Absent means the rule is unconditional and loads
+ *                 with project context.
+ *   - `excludes:` globs contributed to the project context-exclude set.
+ *   - `enabled:`  defaults true.
+ *   - `description:` one-line summary for the inspector.
+ *
+ * Loading is deterministic and cache-stable: rules sort by id (their path under
+ * `.clio-coder/rules`), so the prompt prefix a local model caches does not reorder
+ * between runs. Every rule carries a content hash and a token estimate so an
+ * activated rule can be accounted in the context ledger. Reads are best-effort:
+ * a malformed file is reported and skipped.
+ */
+
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { compileGlobRegex, normalizeGlobInput } from "../../tools/ignore-policy.js";
+import { ceilChars } from "../session/context-accounting.js";
+
+export interface ProjectRule {
+	/** Stable id: the rule's posix path under `.clio-coder/rules`. */
+	id: string;
+	sourcePath: string;
+	hash: string;
+	tokenEstimate: number;
+	/** Activation globs; absent means the rule is unconditional. */
+	paths?: string[];
+	enabled: boolean;
+	description?: string;
+	/** Markdown body after frontmatter; the text that enters the prompt. */
+	body: string;
+}
+
+export interface ProjectRulesLoad {
+	rules: ProjectRule[];
+	/** Aggregated `context.excludes` globs from every rule's frontmatter. */
+	excludes: string[];
+	issues: string[];
+}
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function readStringArray(value: unknown): string[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const out: string[] = [];
+	for (const item of value) {
+		if (typeof item === "string" && item.length > 0) out.push(item);
+	}
+	return out.length > 0 ? out : undefined;
+}
+
+function validateGlobArray(
+	value: unknown,
+	field: "paths" | "excludes",
+	id: string,
+	issues: string[],
+): string[] | undefined {
+	const parsed = readStringArray(value);
+	if (parsed === undefined) {
+		issues.push(`${id}: frontmatter ${field} must be a non-empty string array`);
+		return undefined;
+	}
+	for (const pattern of parsed) {
+		try {
+			compileGlobRegex(pattern);
+		} catch (err) {
+			issues.push(
+				`${id}: invalid ${field} glob ${JSON.stringify(pattern)}: ${err instanceof Error ? err.message : String(err)}`,
+			);
+			return undefined;
+		}
+	}
+	return parsed;
+}
+
+function walkMarkdown(dir: string, root: string, out: string[]): void {
+	let entries: import("node:fs").Dirent[];
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) walkMarkdown(full, root, out);
+		else if (entry.isFile() && entry.name.endsWith(".md")) out.push(full);
+	}
+}
+
+function parseRule(filePath: string, root: string, issues: string[]): { rule?: ProjectRule; excludes: string[] } {
+	let text: string;
+	try {
+		text = readFileSync(filePath, "utf8").replace(/\r\n/g, "\n");
+	} catch (err) {
+		issues.push(`${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+		return { excludes: [] };
+	}
+	const id = relative(root, filePath).split(sep).join("/");
+	let body = text;
+	let paths: string[] | undefined;
+	let excludes: string[] = [];
+	let enabled = true;
+	let description: string | undefined;
+	let invalidFrontmatter = false;
+
+	const match = FRONTMATTER_RE.exec(text);
+	if (match) {
+		body = text.slice(match[0].length);
+		try {
+			const front = parseYaml(match[1] ?? "");
+			if (isRecord(front)) {
+				if (Object.hasOwn(front, "paths")) {
+					const parsedPaths = validateGlobArray(front.paths, "paths", id, issues);
+					if (parsedPaths === undefined) invalidFrontmatter = true;
+					else paths = parsedPaths;
+				}
+				if (Object.hasOwn(front, "excludes")) {
+					const parsedExcludes = validateGlobArray(front.excludes, "excludes", id, issues);
+					if (parsedExcludes === undefined) invalidFrontmatter = true;
+					else excludes = parsedExcludes;
+				}
+				if (Object.hasOwn(front, "enabled")) {
+					if (typeof front.enabled === "boolean") enabled = front.enabled;
+					else {
+						issues.push(`${id}: frontmatter enabled must be a boolean`);
+						invalidFrontmatter = true;
+					}
+				}
+				if (Object.hasOwn(front, "description")) {
+					if (typeof front.description === "string") description = front.description;
+					else {
+						issues.push(`${id}: frontmatter description must be a string`);
+						invalidFrontmatter = true;
+					}
+				}
+			} else if (front !== null && front !== undefined) {
+				issues.push(`${id}: frontmatter must be a mapping`);
+				invalidFrontmatter = true;
+			}
+		} catch (err) {
+			issues.push(`${id}: invalid frontmatter: ${err instanceof Error ? err.message : String(err)}`);
+			invalidFrontmatter = true;
+		}
+	} else if (text.startsWith("---\n")) {
+		issues.push(`${id}: invalid frontmatter: missing closing marker`);
+		invalidFrontmatter = true;
+	}
+	if (invalidFrontmatter) return { excludes: [] };
+
+	const trimmedBody = body.trim();
+	const hash = createHash("sha256").update(trimmedBody).digest("hex").slice(0, 16);
+	const rule: ProjectRule = {
+		id,
+		sourcePath: join(".clio-coder", "rules", id),
+		hash,
+		tokenEstimate: ceilChars(trimmedBody.length),
+		enabled,
+		body: trimmedBody,
+	};
+	if (paths !== undefined) rule.paths = paths;
+	if (description !== undefined) rule.description = description;
+	return { rule, excludes };
+}
+
+/**
+ * Load every rule under `.clio-coder/rules`, deterministically ordered by id. Returns
+ * the rules, the aggregated exclude set, and any per-file issues.
+ */
+export function loadProjectRules(cwd: string): ProjectRulesLoad {
+	const root = join(cwd, ".clio-coder", "rules");
+	const issues: string[] = [];
+	const files: string[] = [];
+	walkMarkdown(root, root, files);
+	files.sort();
+	const rules: ProjectRule[] = [];
+	const excludeSet = new Set<string>();
+	for (const file of files) {
+		const parsed = parseRule(file, root, issues);
+		if (parsed.rule) rules.push(parsed.rule);
+		for (const glob of parsed.excludes) excludeSet.add(glob);
+	}
+	rules.sort((a, b) => a.id.localeCompare(b.id));
+	return { rules, excludes: [...excludeSet], issues };
+}
+
+function ruleMatchesAnyPath(rule: ProjectRule, workingPaths: ReadonlyArray<string>): boolean {
+	for (const pattern of rule.paths ?? []) {
+		let regex: RegExp;
+		try {
+			regex = compileGlobRegex(pattern);
+		} catch {
+			continue;
+		}
+		for (const path of workingPaths) {
+			if (regex.test(normalizeGlobInput(path))) return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Select the rules that should load now. Unconditional rules (no `paths`) always
+ * load; a path-scoped rule loads only when one of its globs matches a path
+ * already in working context. Disabled rules never load. Order is preserved for
+ * cache stability.
+ */
+export function selectActiveRules(
+	rules: ReadonlyArray<ProjectRule>,
+	workingContextPaths: ReadonlyArray<string>,
+): ProjectRule[] {
+	return rules.filter((rule) => {
+		if (!rule.enabled) return false;
+		if (rule.paths === undefined) return true;
+		return ruleMatchesAnyPath(rule, workingContextPaths);
+	});
+}

package/src/domains/context/prompt-context.ts

@@ -0,0 +1,62 @@
+import { detectProjectType } from "../session/workspace/project-type.js";
+import {
+	type ParsedClioMd,
+	renderProjectContextFragment,
+	renderProjectTypeFragment,
+	tryReadClioMd,
+} from "./clio-md.js";
+import { readCodewiki } from "./codewiki/indexer.js";
+import type { ProjectPromptContext } from "./contract.js";
+import { computeFingerprintCached, isStale } from "./fingerprint.js";
+import { readClioState } from "./state.js";
+import { listWikiPages } from "./wiki/layout.js";
+import { wikiCompleteness, wikiStaleness } from "./wiki/staleness.js";
+
+/**
+ * Render the project prompt context for `cwd`: the project-type marker, the
+ * CLIO-CODER.md fragment when a parseable handbook exists, the codewiki availability
+ * marker, and the Markdown wiki marker when a valid wiki exists. Shared by the
+ * prompts extension (session compile),
+ * context-init preload reporting, and `clio-coder config inspect`, so every surface
+ * measures the same text the session prompt would preload.
+ */
+export function renderPromptContext(cwd: string): ProjectPromptContext {
+	const projectType = detectProjectType(cwd);
+	const pieces = [renderProjectTypeFragment(projectType)];
+	const warnings: string[] = [];
+	const clio = tryReadClioMd(cwd);
+	let clioMd: ParsedClioMd | null = null;
+	if (clio?.ok) {
+		clioMd = clio.value;
+		pieces.push(renderProjectContextFragment(clio.value));
+	}
+	if (clio && !clio.ok) warnings.push(`clio: malformed CLIO-CODER.md ignored: ${clio.error}`);
+	const codewiki = readCodewiki(cwd);
+	if (codewiki) {
+		const state = readClioState(cwd);
+		const stale = state ? isStale(state.fingerprint, computeFingerprintCached(cwd, codewiki)) : true;
+		const suffix = stale ? " (stale; run /context refresh)" : "";
+		pieces.push(`<codewiki>available${suffix}; use code_nav</codewiki>`);
+	}
+	// A wiki is advertised whenever one exists. There is no invalid-layout state
+	// to gate on: every structural defect is repaired by the assembly pass before
+	// a tree is promoted, so a promoted wiki is by construction navigable.
+	const staleness = wikiStaleness(cwd);
+	if (staleness.state !== "absent") {
+		const pages = listWikiPages(cwd);
+		// Coverage before freshness: a partial wiki can be perfectly current with
+		// the tree, so reporting only staleness would let a model read "12 pages"
+		// as complete coverage of the repository and stop looking.
+		const completeness = wikiCompleteness(cwd);
+		const notes: string[] = [];
+		if (completeness && completeness.owed > 0) {
+			notes.push(
+				`incomplete: ${completeness.pagesWritten} of ${completeness.pagesPlanned} planned pages written, ${completeness.owed} owed`,
+			);
+		}
+		if (staleness.state === "stale") notes.push("stale");
+		const suffix = notes.length > 0 ? ` (${notes.join("; ")}; run clio-coder context wiki --update)` : "";
+		pieces.push(`<wiki>${pages.length} pages at .clio-coder/wiki (start: quickstart.md)${suffix}</wiki>`);
+	}
+	return { text: pieces.join("\n\n"), clioMd, warnings };
+}

package/src/domains/context/refresh.ts

@@ -0,0 +1,170 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { detectProjectType } from "../session/workspace/project-type.js";
+import { type BootstrapIo, type BootstrapProgressSink, codewikiSections } from "./bootstrap.js";
+import { serializeClioMd, tryReadClioMd } from "./clio-md.js";
+import { buildCodewiki, type Codewiki, writeCodewiki } from "./codewiki/indexer.js";
+import { computeFingerprint, type Fingerprint } from "./fingerprint.js";
+import { readClioState, writeClioState } from "./state.js";
+import { type RunWikiGenerateResult, runWikiGenerate, type WikiGenerate } from "./wiki/generate.js";
+import { readWikiMeta } from "./wiki/meta.js";
+import { wikiCompleteness, wikiStaleness } from "./wiki/staleness.js";
+
+/**
+ * `/context refresh` and `clio-coder context refresh`: rebuild the codewiki index and
+ * `.clio-coder` state, then re-derive the handbook sections the index owns. Authoring
+ * handbook prose stays with `/context init`.
+ */
+
+export interface RunContextRefreshInput {
+	cwd?: string;
+	io?: BootstrapIo;
+	now?: () => Date;
+	onProgress?: BootstrapProgressSink;
+	wiki?: boolean;
+	wikiGenerate?: WikiGenerate;
+	/**
+	 * Resolved wire model id of the documenter target, recorded on the wiki
+	 * metadata when `--wiki` updates run. Supplied by the CLI, which can load the
+	 * providers contract; absent for callers that never trigger wiki generation.
+	 */
+	wikiModel?: string;
+}
+
+/**
+ * What refresh did to CLIO-CODER.md. "absent" covers no handbook and an unparseable
+ * one alike: a missing or broken handbook is never an error here, because a
+ * repository must stay fully usable without one.
+ */
+export type ClioMdCuration = "updated" | "unchanged" | "absent";
+
+export interface RunContextRefreshResult {
+	action: "refreshed";
+	codewikiEntries: number;
+	fingerprint: Fingerprint;
+	clioMd: ClioMdCuration;
+	wiki?: RunWikiGenerateResult;
+	hint?: string;
+}
+
+/**
+ * Re-derive the index-owned sections of an existing handbook against the codewiki
+ * this run just built. Only sections whose title the index authors are replaced,
+ * and only when they are already present, so a human's handbook is never grown a
+ * section it did not ask for and never loses one it wrote. Best-effort by
+ * construction: nothing here may turn a routine refresh into a failure.
+ */
+function curateClioMd(cwd: string, codewiki: Codewiki): ClioMdCuration {
+	try {
+		const parsed = tryReadClioMd(cwd);
+		if (!parsed?.ok) return "absent";
+		const handbook = parsed.value;
+		const fresh = new Map(codewikiSections(codewiki).map((section) => [section.title, section.body] as const));
+		let changed = false;
+		const sections = handbook.sections.map((section) => {
+			const body = fresh.get(section.title);
+			if (body === undefined || body === section.body) return section;
+			changed = true;
+			return { title: section.title, body };
+		});
+		// Rewrite only when an index-owned body actually moved. Serializing on every
+		// refresh would silently reformat a hand-written handbook into the generator's
+		// canonical rendering, which is a diff the author never asked for.
+		if (!changed) return "unchanged";
+		writeFileSync(
+			join(cwd, "CLIO-CODER.md"),
+			serializeClioMd({
+				projectName: handbook.projectName,
+				identity: handbook.identity,
+				conventions: handbook.conventions,
+				invariants: handbook.invariants,
+				sections,
+				...(handbook.importedAgentContext ? { importedAgentContext: handbook.importedAgentContext } : {}),
+				fingerprint: handbook.fingerprint,
+			}),
+			"utf8",
+		);
+		return "updated";
+	} catch {
+		return "absent";
+	}
+}
+
+function indexedSourceFileCount(codewiki: Codewiki): number {
+	return codewiki.files.filter((file) => file.lang !== "config").length;
+}
+
+const STALE_WIKI_REFRESH_HINT =
+	"wiki is stale; run clio-coder context refresh --wiki or clio-coder context wiki --update";
+const NO_WIKI_HINT = "no wiki exists, so --wiki had nothing to update; run clio-coder context wiki to build one";
+
+function incompleteWikiHint(cwd: string): string | undefined {
+	const completeness = wikiCompleteness(cwd);
+	if (!completeness || completeness.owed === 0) return undefined;
+	return `wiki is incomplete: ${completeness.pagesWritten} of ${completeness.pagesPlanned} planned pages written, ${completeness.owed} owed; run clio-coder context wiki --update to resume`;
+}
+
+export async function runContextRefresh(input: RunContextRefreshInput = {}): Promise<RunContextRefreshResult> {
+	const cwd = input.cwd ?? process.cwd();
+	const now = input.now ?? (() => new Date());
+	const prev = readClioState(cwd);
+	const hasWiki = readWikiMeta(cwd) !== null;
+	const projectType = prev?.projectType ?? detectProjectType(cwd);
+	const indexedAt = now().toISOString();
+
+	input.onProgress?.({ phase: "codewiki", status: "started", message: "rebuilding codewiki" });
+	const codewiki = await buildCodewiki({ cwd, language: projectType, generatedAt: indexedAt });
+	writeCodewiki(cwd, codewiki);
+	const fingerprint = computeFingerprint(cwd, codewiki);
+	const clioMd = curateClioMd(cwd, codewiki);
+
+	input.onProgress?.({ phase: "state", status: "running", message: "writing state" });
+	writeClioState(cwd, {
+		version: 1,
+		projectType,
+		fingerprint,
+		codewikiVersion: codewiki.version,
+		...(prev?.contextSources ? { contextSources: prev.contextSources } : {}),
+		...(prev?.contextSourceHash ? { contextSourceHash: prev.contextSourceHash } : {}),
+		...(prev?.lastBootstrap ? { lastBootstrap: prev.lastBootstrap } : {}),
+		...(prev?.lastInitAt ? { lastInitAt: prev.lastInitAt } : {}),
+		lastSessionAt: prev?.lastSessionAt ?? indexedAt,
+		lastIndexedAt: indexedAt,
+	});
+
+	const entries = indexedSourceFileCount(codewiki);
+	let wikiResult: RunWikiGenerateResult | undefined;
+	let hint: string | undefined;
+	if (input.wiki === true && hasWiki) {
+		wikiResult = await runWikiGenerate({
+			cwd,
+			mode: "update",
+			model: input.wikiModel ?? "unresolved-documenter-target",
+			...(input.wikiGenerate ? { generate: input.wikiGenerate } : {}),
+			...(input.onProgress ? { onProgress: input.onProgress } : {}),
+		});
+	} else if (input.wiki === true) {
+		// --wiki with no wiki on disk used to return silently, so an operator who
+		// asked for an update got a bare "codewiki rebuilt" and no way to tell the
+		// request had been dropped.
+		hint = NO_WIKI_HINT;
+	} else if (hasWiki) {
+		// Incompleteness is checked before staleness: a partial wiki is often
+		// perfectly fresh, and that combination used to produce no hint at all.
+		hint = incompleteWikiHint(cwd) ?? (wikiStaleness(cwd).state === "stale" ? STALE_WIKI_REFRESH_HINT : undefined);
+	}
+
+	const handbookNote = clioMd === "updated" ? "; CLIO-CODER.md index sections updated" : "";
+	input.io?.stdout(
+		`clio-coder context refresh: codewiki rebuilt (${entries} source file${entries === 1 ? "" : "s"})${handbookNote}\n`,
+	);
+	input.onProgress?.({ phase: "done", status: "completed", message: "context refreshed" });
+	return {
+		action: "refreshed",
+		codewikiEntries: entries,
+		fingerprint,
+		clioMd,
+		...(wikiResult ? { wiki: wikiResult } : {}),
+		...(hint ? { hint } : {}),
+	};
+}

package/src/domains/context/sibling-files.ts

@@ -0,0 +1,10 @@
+export interface SiblingContextFile {
+	source: string;
+	path: string;
+	content: string;
+}
+
+export interface LoadSiblingContextFilesOptions {
+	homeDir?: string;
+	includeGlobal?: boolean;
+}