@iowarp/clio-coder 0.4.4 → 0.4.5

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

@@ -1,3 +1,4 @@
+import { statSync } from "node:fs";
 import { detectProjectType } from "../session/workspace/project-type.js";
 import {
 	loadProjectClioMd,
@@ -5,7 +6,7 @@ import {
 	renderProjectContextFragment,
 	renderProjectTypeFragment,
 } from "./clio-md.js";
-import { readCodewiki } from "./codewiki/artifact.js";
+import { codewikiPath } from "./codewiki/artifact.js";
 import type { ProjectPromptContext } from "./contract.js";
 import { computeFingerprintCached, isStale } from "./fingerprint.js";
 import { readClioState } from "./state.js";
@@ -14,7 +15,7 @@ import { wikiCompleteness, wikiStaleness } from "./wiki/staleness.js";
 
 /**
  * Render the project prompt context for `cwd`: the project-type marker, the
- * effective CLIO-CODER.md fragments when parseable handbooks exist, the codewiki availability
+ * effective CLIO-CODER.md fragments when readable nonempty handbooks exist, 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
@@ -24,26 +25,59 @@ import { wikiCompleteness, wikiStaleness } from "./wiki/staleness.js";
 export const HANDBOOK_ABSENT_FRAGMENT =
 	"<handbook>none: this workspace has no CLIO-CODER.md, so do not read one; learn the repository from its files, and the operator can run /context init to write a handbook</handbook>";
 
+function codewikiArtifactPresent(cwd: string): boolean {
+	try {
+		return statSync(codewikiPath(cwd)).isFile();
+	} catch {
+		return false;
+	}
+}
+
 export function renderPromptContext(cwd: string): ProjectPromptContext {
-	const projectType = detectProjectType(cwd);
-	const pieces = [renderProjectTypeFragment(projectType)];
+	// Detection enumerates the tree and reads every `.h` header to classify it,
+	// and this renders on session compile and on every bounded dispatch. An
+	// indexed project already recorded its type when init, refresh, or the
+	// session-start check stamped state; the marker reads that and detects only
+	// where nothing has been recorded yet.
+	const state = readClioState(cwd);
+	const projectType = state?.projectType ?? detectProjectType(cwd);
+	const supportFragments = [renderProjectTypeFragment(projectType)];
+	const pieces = [...supportFragments];
+	const addSupport = (fragment: string): void => {
+		pieces.push(fragment);
+		supportFragments.push(fragment);
+	};
 	const warnings: string[] = [];
 	const loadedClioMd = loadProjectClioMd(cwd);
 	const clioMd: ParsedClioMd | null = loadedClioMd.value;
-	for (const file of loadedClioMd.files) pieces.push(renderProjectContextFragment(file.value, file.path));
+	for (const file of loadedClioMd.files) pieces.push(renderProjectContextFragment(file.source, file.path));
 	for (const issue of loadedClioMd.errors) {
-		warnings.push(`clio-coder: malformed ${issue.path} ignored: ${issue.error}`);
+		warnings.push(`clio-coder: unavailable ${issue.path} ignored: ${issue.error}`);
 	}
 	// Said where the handbook would have been: a model that sees no project
 	// context spends its first tool call reading CLIO-CODER.md and gets
 	// ENOENT, while the operator's header already says it is missing (#191).
-	if (loadedClioMd.files.length === 0 && loadedClioMd.errors.length === 0) pieces.push(HANDBOOK_ABSENT_FRAGMENT);
-	const codewiki = readCodewiki(cwd);
-	if (codewiki) {
-		const state = readClioState(cwd);
-		const stale = state ? isStale(state.fingerprint, computeFingerprintCached(cwd, codewiki)) : true;
+	if (loadedClioMd.files.length === 0 && loadedClioMd.errors.length === 0) addSupport(HANDBOOK_ABSENT_FRAGMENT);
+	// The marker states that an artifact is present and whether the recorded
+	// source fingerprint still matches the tree. It does not validate the
+	// artifact's contents: parsing the JSON here is main-thread work that grows
+	// with the index, on session compile and on every bounded dispatch, for a
+	// boolean. An unparseable artifact is still "available" in the sense the
+	// marker promises, because `code_nav` reads null for it and rebuilds from
+	// source under the lease before answering, and the session-start check does
+	// the same. The recorded fingerprint carries the line total the freshness
+	// check would otherwise have read off the artifact.
+	if (codewikiArtifactPresent(cwd)) {
+		let stale = true;
+		try {
+			if (state) {
+				stale = isStale(state.fingerprint, computeFingerprintCached(cwd, null, { artifactLoc: state.fingerprint.loc }));
+			}
+		} catch {
+			warnings.push("clio-coder: codewiki freshness unavailable; source could not be read; run /context refresh");
+		}
 		const suffix = stale ? " (stale; run /context refresh)" : "";
-		pieces.push(`<codewiki>available${suffix}; use code_nav</codewiki>`);
+		addSupport(`<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
@@ -63,7 +97,14 @@ export function renderPromptContext(cwd: string): ProjectPromptContext {
 		}
 		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>`);
+		addSupport(`<wiki>${pages.length} pages at .clio-coder/wiki (start: quickstart.md)${suffix}</wiki>`);
 	}
-	return { text: pieces.join("\n\n"), clioMd, warnings, handbookFiles: loadedClioMd.files.map((file) => file.path) };
+	return {
+		text: pieces.join("\n\n"),
+		clioMd,
+		warnings,
+		handbookFiles: loadedClioMd.files.map((file) => file.path),
+		handbookSources: loadedClioMd.files.map(({ path, source }) => ({ path, source })),
+		supportFragments,
+	};
 }

package/src/domains/context/refresh.ts

@@ -1,9 +1,7 @@
-import { writeFileSync } from "node:fs";
-import { join } from "node:path";
 import type { DecisionLedgerEntry } from "../session/entries.js";
 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 type { BootstrapIo, BootstrapProgressSink } from "./bootstrap.js";
+import { tryReadClioMd } from "./clio-md.js";
 import { coordinateCodewikiWrite } from "./codewiki/coordinator.js";
 import type { Codewiki } from "./codewiki/schema.js";
 import type { Fingerprint } from "./fingerprint.js";
@@ -14,8 +12,8 @@ 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`.
+ * `.clio-coder` state while preserving authored handbook bytes. Derived navigation
+ * stays in codewiki and the optional Markdown wiki.
  */
 
 export interface RunContextRefreshInput {
@@ -35,11 +33,11 @@ export interface RunContextRefreshInput {
 }
 
 /**
- * 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
+ * What refresh found at CLIO-CODER.md. "absent" covers missing, empty, and unreadable
+ * files: an unavailable handbook is never an error here, because a
  * repository must stay fully usable without one.
  */
-export type ClioMdCuration = "updated" | "unchanged" | "absent";
+export type ClioMdCuration = "unchanged" | "absent";
 
 export interface RunContextRefreshResult {
 	action: "refreshed";
@@ -50,49 +48,6 @@ export interface RunContextRefreshResult {
 	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;
 }
@@ -121,7 +76,7 @@ export async function runContextRefresh(input: RunContextRefreshInput = {}): Pro
 	const coordinated = await coordinateCodewikiWrite(cwd, () => ({ kind: "build", cwd, language: projectType }), {
 		afterCommit: (result, workspace) => {
 			fingerprint = result.fingerprint;
-			clioMd = curateClioMd(workspace, result.codewiki);
+			clioMd = tryReadClioMd(workspace)?.ok ? "unchanged" : "absent";
 			input.onProgress?.({ phase: "state", status: "running", message: "writing state" });
 			const latest = readClioState(workspace);
 			writeClioState(workspace, {
@@ -165,10 +120,7 @@ export async function runContextRefresh(input: RunContextRefreshInput = {}): Pro
 	}
 
 	const committedClioMd = clioMd as ClioMdCuration;
-	const handbookNote = committedClioMd === "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.io?.stdout(`clio-coder context refresh: codewiki rebuilt (${entries} source file${entries === 1 ? "" : "s"})\n`);
 	input.onProgress?.({ phase: "done", status: "completed", message: "context refreshed" });
 	return {
 		action: "refreshed",

package/src/domains/context/wiki/assemble.ts

@@ -15,7 +15,7 @@
  */
 
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, normalize, posix, relative } from "node:path";
+import { basename, dirname, join, posix, relative } from "node:path";
 import { readWikiPage, renderWikiPage, resolveSourcePath, type WikiPageMetadata } from "./frontmatter.js";
 import {
 	isGeneratedWikiFile,
@@ -289,15 +289,19 @@ export function pageSourceIndex(dir: string, sourceRoot: string): Map<string, st
 	const index = new Map<string, string[]>();
 	for (const relPath of wikiMarkdownFilesInDir(dir)) {
 		if (isGeneratedWikiFile(relPath)) continue;
-		const { metadata } = readWikiPage({ pagePath: relPath, content: readText(join(dir, relPath)), sourceRoot });
-		index.set(relPath, [...metadata.sources, ...metadata.tests]);
+		const { metadata, unresolvedPaths } = readWikiPage({
+			pagePath: relPath,
+			content: readText(join(dir, relPath)),
+			sourceRoot,
+		});
+		index.set(relPath, [
+			...new Set(
+				[...metadata.sources, ...metadata.tests, ...unresolvedPaths].map((cited) => {
+					const resolved = resolveSourcePath(sourceRoot, cited);
+					return resolved ? relative(sourceRoot, resolved).replace(/\\/g, "/") : cited;
+				}),
+			),
+		]);
 	}
 	return index;
 }
-
-/** Normalize a repository path for comparison against recorded page sources. */
-export function normalizeRepoPath(sourceRoot: string, candidate: string): string {
-	const resolved = normalize(join(sourceRoot, candidate));
-	const rel = relative(sourceRoot, resolved);
-	return rel.split("\\").join("/");
-}

package/src/domains/context/wiki/evidence.ts

@@ -0,0 +1,209 @@
+/** Mechanical publication checks; these do not prove a claim or that a writer read its source. */
+import { accessSync, constants, readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, isAbsolute, relative, resolve } from "node:path";
+import { parse } from "yaml";
+import { readWikiPage, resolveSourcePath, stripFrontmatter } from "./frontmatter.js";
+
+export interface WikiPageEvidenceInput {
+	pagePath: string;
+	content: string;
+	sourceRoot: string;
+}
+
+export interface WikiPageEvidenceResult {
+	ok: boolean;
+	/** At most eight actionable diagnostics, each bounded for the persisted retry reason. */
+	reasons: string[];
+	/** Canonical repository-relative evidence files, present only after successful validation. */
+	dependencies?: string[];
+}
+
+function within(root: string, path: string): boolean {
+	const rel = relative(root, path).replace(/\\/g, "/");
+	return rel !== ".." && !rel.startsWith("../") && !isAbsolute(rel);
+}
+
+/**
+ * Validate the original writer output BEFORE assembly repairs metadata. Existing
+ * frontmatter parsing supplies the references; no claims sidecar or prose schema
+ * is required. The supported body citation form is a backticked file path with
+ * optional :line[-end][:symbol] or #Lline[-Lend]. Markdown wiki links, commands,
+ * symbols and decision refs are not interpreted as source evidence.
+ */
+export function validateWikiPageEvidence(input: WikiPageEvidenceInput): WikiPageEvidenceResult {
+	const reasons: string[] = [];
+	const fail = (reason: string): void => {
+		if (reasons.length < 8) reasons.push(reason.slice(0, 300));
+	};
+	if (Buffer.byteLength(input.content, "utf8") > 2 * 1024 * 1024) {
+		return { ok: false, reasons: ["Page exceeds the 2 MiB evidence-check limit; split or shorten it before retrying."] };
+	}
+	const { body, metadata } = readWikiPage({ pagePath: input.pagePath, content: input.content });
+	if (
+		body
+			.replace(/<!--[\s\S]*?-->/g, "")
+			.replace(/^\s*#.*$/gm, "")
+			.trim().length === 0
+	) {
+		fail("Write a nonempty page body beyond headings and comments, grounded in current repository files.");
+	}
+	const { block } = stripFrontmatter(input.content);
+	if (block !== null) {
+		try {
+			const fields: unknown = parse(`\n${block}`, { schema: "core", uniqueKeys: true });
+			if (typeof fields !== "object" || fields === null || Array.isArray(fields)) {
+				fail("Repair the YAML frontmatter as a metadata mapping before retrying.");
+			} else {
+				for (const field of ["sources", "tests"] as const) {
+					const value = (fields as Record<string, unknown>)[field];
+					if (
+						value !== undefined &&
+						(!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item.trim()))
+					) {
+						fail(`Repair frontmatter ${field}: use a list of nonempty repository-relative file paths.`);
+					}
+				}
+			}
+		} catch {
+			fail("Repair invalid YAML frontmatter; source/test evidence cannot be checked until it parses.");
+		}
+	} else if (/^---\r?\n/.test(input.content)) {
+		fail("Close the YAML frontmatter with a standalone --- line before the page body.");
+	}
+
+	const declaredReferences = new Set([...metadata.sources, ...metadata.tests]);
+	const references = new Set(declaredReferences);
+	for (const reference of references) {
+		if (/[:#]/.test(reference))
+			fail(
+				`Use a plain file path in sources/tests: ${JSON.stringify(reference.slice(0, 160))}; put line/symbol citations in the body.`,
+			);
+	}
+	// Remove code fences: example programs and shell commands are not citations.
+	const prose = body.replace(/^\s*(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\s*\1\s*$/gm, "");
+	for (const match of prose.matchAll(/`([^`\s]+)`/g)) {
+		const cited = match[1] ?? "";
+		// A filename extension distinguishes a file citation from a symbol or a
+		// recorded decision ref. Include extensionless conventional repo files.
+		const pathLike = cited.includes("/") && /\.[\w-]+(?=[:#]|$)/.test(cited);
+		const rootFile =
+			/^[^/:#]+\.(?:[cm]?[jt]sx?|py|rs|go|c|h|cpp|hpp|java|rb|sh|json|ya?ml|toml|md|txt|ini|cfg|xml|html|css|sql)(?=[:#]|$)/i.test(
+				cited,
+			);
+		if (
+			!/^[a-z][a-z\d+.-]*:\/\//i.test(cited) &&
+			(pathLike || rootFile || /^(?:Makefile|Dockerfile|LICENSE)(?=[:#]|$)/.test(cited))
+		) {
+			references.add(cited);
+		}
+	}
+	if (references.size === 0)
+		fail("Cite at least one existing repository file in sources/tests or as a backticked source path.");
+	if (references.size > 512) {
+		fail("Page exceeds the 512-reference evidence-check limit; split or shorten it before retrying.");
+		return { ok: false, reasons };
+	}
+	let root: string;
+	try {
+		root = realpathSync(input.sourceRoot);
+	} catch {
+		fail("Repository root is unavailable; restore access and retry evidence validation.");
+		return { ok: false, reasons };
+	}
+	const dependencies = new Set<string>();
+	const declaredFilesByName = new Map<string, Set<string>>();
+	const linesByFile = new Map<string, number>();
+	let readBytes = 0;
+	for (const reference of references) {
+		const label = JSON.stringify(reference.slice(0, 160));
+		const match = /^([^:#]+)(?:(?::(\d+)(?:-(\d+))?)|(?:#L(\d+)(?:-L?(\d+))?))?(?::[A-Za-z_$][\w$.-]*)?$/.exec(reference);
+		if (!match) {
+			fail(`Repair citation ${label}: use path, path:line[-end], or path#Lline[-Lend].`);
+			continue;
+		}
+		const cited = match[1] ?? "";
+		try {
+			let source = resolveSourcePath(resolve(input.sourceRoot), cited);
+			if (source === null && !declaredReferences.has(reference) && !/[\\/]/.test(cited)) {
+				const declared = declaredFilesByName.get(cited);
+				if (declared?.size === 1) source = [...declared][0] ?? null;
+			}
+			if (source === null) {
+				fail(`Replace or remove unresolved repository reference ${label}; inspect the current file path.`);
+				continue;
+			}
+			const real = realpathSync(source);
+			const stat = statSync(real);
+			if (!within(root, real) || !stat.isFile()) {
+				fail(
+					`Replace ${label} with an existing file inside the repository; directories and escaping symlinks are not evidence.`,
+				);
+				continue;
+			}
+			accessSync(real, constants.R_OK);
+			// Declared references are checked first. Body shorthand can reuse only
+			// their verified files; frontmatter itself remains repository-relative.
+			if (declaredReferences.has(reference) && !/[:#]/.test(reference)) {
+				for (const name of [basename(cited), basename(real)]) {
+					const files = declaredFilesByName.get(name) ?? new Set<string>();
+					files.add(real);
+					declaredFilesByName.set(name, files);
+				}
+			}
+			dependencies.add(relative(root, real).split("\\").join("/"));
+			const startText = match[2] ?? match[4];
+			if (startText !== undefined) {
+				if (stat.size > 4 * 1024 * 1024) {
+					fail(`Cannot check lines in ${label}: file exceeds 4 MiB; cite the file and symbol without a line range.`);
+					continue;
+				}
+				let lines = linesByFile.get(real);
+				if (lines === undefined) {
+					if (readBytes + stat.size > 16 * 1024 * 1024) {
+						fail(
+							"Line citations exceed the 16 MiB total source-read limit; split the page or prefer file and symbol citations.",
+						);
+						continue;
+					}
+					readBytes += stat.size;
+					const text = readFileSync(real, "utf8");
+					lines = text.length === 0 ? 0 : text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+					linesByFile.set(real, lines);
+				}
+				const start = Number(startText);
+				const end = Number(match[3] ?? match[5] ?? startText);
+				if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 1 || end < start || end > lines) {
+					fail(
+						`Repair line range in ${label}: the current file has ${lines} lines; use an existing ordered range starting at 1.`,
+					);
+				}
+			}
+		} catch {
+			fail(`Cannot inspect ${label}; restore readable repository evidence or remove the unsupported reference.`);
+		}
+	}
+	return reasons.length === 0 ? { ok: true, reasons, dependencies: [...dependencies].sort() } : { ok: false, reasons };
+}
+
+/** Read a planned staging page with bounded IO before validating original evidence. */
+export function inspectWikiPageEvidence(input: {
+	pagePath: string;
+	outputDir: string;
+	sourceRoot: string;
+}): WikiPageEvidenceResult {
+	try {
+		const path = realpathSync(resolve(input.outputDir, input.pagePath));
+		const stat = statSync(path);
+		if (!within(realpathSync(input.outputDir), path) || !stat.isFile())
+			return { ok: false, reasons: ["planned page must be a regular file inside wiki staging"] };
+		if (stat.size > 2 * 1024 * 1024)
+			return { ok: false, reasons: ["page exceeds the 2 MiB evidence-check limit; split or shorten it"] };
+		return validateWikiPageEvidence({
+			pagePath: input.pagePath,
+			content: readFileSync(path, "utf8"),
+			sourceRoot: input.sourceRoot,
+		});
+	} catch {
+		return { ok: false, reasons: ["writer finished without a readable planned page file"] };
+	}
+}