codecartographer-pi 0.1.0

package/core/prompts.ts

@@ -0,0 +1,183 @@
+// Prompt builders + closeout/thread-log helpers. The phase prompt is the
+// single biggest fidelity surface — both Pi and the MCP server emit
+// byte-identical text by importing buildPhasePrompt from here.
+
+import { copyFile, mkdir, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type {
+	CarryForwardEntry,
+	OpenQuestionEntry,
+	PipelinePhase,
+	ValidationResult,
+	WorkspaceState,
+} from "./types.ts";
+import { dateOnly, pathExists } from "./utils.ts";
+
+export function describeEntry(entry: OpenQuestionEntry | CarryForwardEntry): string {
+	const parts: string[] = [];
+	if (entry.id) parts.push(entry.id);
+	if (entry.kind) parts.push(`(${entry.kind})`);
+	if (entry.description) parts.push(entry.description);
+	else if (entry.deferred_reason) parts.push(entry.deferred_reason);
+	return parts.join(" ").trim() || "(unlabeled entry)";
+}
+
+export function collectRoutedCarryForward(state: WorkspaceState, targetPhaseId: string): CarryForwardEntry[] {
+	const routed: CarryForwardEntry[] = [];
+	for (const phase of Object.values(state.status.phases)) {
+		for (const entry of phase.carry_forward ?? []) {
+			if (entry.target_phase === targetPhaseId) routed.push(entry);
+		}
+	}
+	return routed;
+}
+
+export async function buildPhasePrompt(state: WorkspaceState, phase: PipelinePhase, forced: boolean): Promise<string> {
+	const lines = [
+		`Read .codecarto/GUIDE.md and continue the CodeCartographer workflow for the phase \`${phase.id}\`.`,
+		`Work on this phase only. The analyzed source code is the repository outside .codecarto/.`,
+		"",
+		"Required reads before analysis:",
+		"- .codecarto/GUIDE.md",
+		"- .codecarto/workflow/status.yaml",
+	];
+
+	const primaryOutput = phase.primary_output ? `.codecarto/${phase.primary_output}` : undefined;
+	if (primaryOutput) {
+		lines.push(`- ${primaryOutput} if it already exists (continue instead of duplicating work)`);
+	}
+	if (phase.skill_path) lines.push(`- .codecarto/${phase.skill_path}`);
+	if (phase.output_template) lines.push(`- .codecarto/${phase.output_template}`);
+
+	const staticReads = new Set(["GUIDE.md", "workflow/status.yaml"]);
+	const phaseReads = (phase.required_reads ?? []).filter((path) => path && !staticReads.has(path));
+	for (const path of phaseReads) {
+		lines.push(`- .codecarto/${path}`);
+	}
+
+	const conventionsPath = join(state.workspaceDir, "CONVENTIONS.md");
+	if (await pathExists(conventionsPath)) {
+		lines.push("- .codecarto/CONVENTIONS.md (cross-cutting patterns the orchestrator has promoted)");
+	}
+	const decisionsPath = join(state.workspaceDir, "DECISIONS.md");
+	if (await pathExists(decisionsPath)) {
+		lines.push("- .codecarto/DECISIONS.md (numbered project decisions; new entries are appended in your closeout)");
+	}
+
+	const routed = collectRoutedCarryForward(state, phase.id);
+	if (routed.length > 0) {
+		lines.push("", `Items routed to \`${phase.id}\` for closure (carry_forward from earlier phases):`);
+		for (const entry of routed) {
+			lines.push(`- ${describeEntry(entry)}`);
+		}
+		lines.push("Close each item by editing your phase output to address it, then remove the entry from the source phase's carry_forward in workflow/status.yaml.");
+	}
+
+	if (phase.id === "reimplementation-spec") {
+		lines.push("");
+		lines.push("Strategic Alignment Hook (run BEFORE producing the spec):");
+		lines.push("- Confirm with the user whether this spec should be language-agnostic or opinionated:");
+		lines.push("    - language-agnostic → use templates/reimplementation-spec.md (default).");
+		lines.push("    - opinionated (target stack locked) → use templates/reimplementation-spec-opinionated.md.");
+		lines.push("- Record the chosen variant in the spec front-matter and in your validation block.");
+	}
+
+	lines.push("", "Rules:");
+	lines.push("- Do not modify source files outside .codecarto/.");
+	lines.push("- Follow the active pipeline and validation protocol.");
+	lines.push("- Update findings under .codecarto/findings/ for this phase.");
+	lines.push("- Distinguish open_questions (genuinely unknown) from carry_forward (routed to a specific later phase) when updating workflow/status.yaml — see GUIDE.md \"Open Questions vs Carry-Forward\".");
+
+	if (forced) {
+		lines.push("- The user explicitly requested this phase even if it is not the next eligible phase.");
+	}
+
+	if (phase.depends_on && phase.depends_on.length > 0) {
+		const unmet = phase.depends_on.filter((dependencyId) => state.status.phases[dependencyId]?.status !== "complete");
+		if (unmet.length > 0) {
+			lines.push(`- Warning: dependencies not complete yet: ${unmet.join(", ")}`);
+		}
+	}
+
+	if (phase.handoff_requirements && phase.handoff_requirements.length > 0) {
+		lines.push("", "Handoff requirements (from the active pipeline):");
+		for (const requirement of phase.handoff_requirements) {
+			lines.push(`- ${requirement}`);
+		}
+	}
+
+	if (primaryOutput) {
+		lines.push("", `Primary output target: ${primaryOutput}`);
+	}
+
+	return lines.join("\n");
+}
+
+export function closeoutFileName(date: string, phaseOrModule: string): string {
+	return `${date}-${phaseOrModule}.md`;
+}
+
+export function buildThreadLogEntry(phaseOrModule: string, validation: ValidationResult, timestamp: string): string {
+	const date = dateOnly(timestamp);
+	const file = closeoutFileName(date, phaseOrModule);
+	return `- ${date} — ${phaseOrModule} — Validation: ${validation.overall} — [closeout](closeouts/${file})\n`;
+}
+
+export async function ensureCloseoutStub(workspaceDir: string, phaseOrModule: string, timestamp: string): Promise<string | null> {
+	const date = dateOnly(timestamp);
+	const closeoutsDir = join(workspaceDir, "closeouts");
+	const closeoutPath = join(closeoutsDir, closeoutFileName(date, phaseOrModule));
+	if (await pathExists(closeoutPath)) return null;
+	const templatePath = join(workspaceDir, "templates", "closeout-template.md");
+	if (!(await pathExists(templatePath))) return null;
+	await mkdir(closeoutsDir, { recursive: true });
+	await copyFile(templatePath, closeoutPath);
+	return closeoutPath;
+}
+
+export async function listSkillNames(workspaceDir: string): Promise<string[]> {
+	const skillsDir = join(workspaceDir, "skills");
+	if (!(await pathExists(skillsDir))) return [];
+	try {
+		const entries = await readdir(skillsDir, { withFileTypes: true });
+		const names: string[] = [];
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			const skillFile = join(skillsDir, entry.name, "SKILL.md");
+			if (await pathExists(skillFile)) names.push(entry.name);
+		}
+		return names.sort();
+	} catch {
+		return [];
+	}
+}
+
+export async function buildSkillPrompt(state: WorkspaceState, skillName: string): Promise<string> {
+	const lines = [
+		`Read .codecarto/GUIDE.md and run the post-pipeline skill \`${skillName}\`.`,
+		"This is post-pipeline work. The pipeline is `complete`. Do not change `current_phase` or `phase_order` in workflow/status.yaml.",
+		"",
+		"Required reads before starting:",
+		"- .codecarto/GUIDE.md",
+		"- .codecarto/workflow/status.yaml",
+		`- .codecarto/skills/${skillName}/SKILL.md`,
+	];
+
+	const conventionsPath = join(state.workspaceDir, "CONVENTIONS.md");
+	if (await pathExists(conventionsPath)) {
+		lines.push("- .codecarto/CONVENTIONS.md (cross-cutting patterns the orchestrator has promoted)");
+	}
+	const decisionsPath = join(state.workspaceDir, "DECISIONS.md");
+	if (await pathExists(decisionsPath)) {
+		lines.push("- .codecarto/DECISIONS.md (numbered project decisions; new entries are appended in your closeout)");
+	}
+
+	lines.push("", "Rules:");
+	lines.push("- Do not modify source files outside .codecarto/.");
+	lines.push("- Follow the SKILL.md instructions exactly; the skill enforces its own discipline (see GUIDE.md).");
+	lines.push("- Update only the artifacts the skill calls for. Do NOT touch phase status entries.");
+	lines.push("- On completion, write a closeout at .codecarto/closeouts/<YYYY-MM-DD>-<skill-or-module>.md and append a one-line index entry to THREAD_LOG.md.");
+	lines.push("- If your work resolves entries in any phase's open_questions or carry_forward, remove only those resolved entries.");
+
+	return lines.join("\n");
+}

package/core/status.ts

@@ -0,0 +1,155 @@
+// Status normalization, atomic writes, and file-lock primitives. Pure
+// framework logic shared by every wrapper.
+
+import { open, rm, stat } from "node:fs/promises";
+import { basename } from "node:path";
+import type {
+	CarryForwardEntry,
+	NormalizedStatus,
+	OpenQuestionEntry,
+	PipelineFile,
+	PipelinePhase,
+	StatusFile,
+	StatusPhase,
+} from "./types.ts";
+import { sleep } from "./utils.ts";
+
+export const LOCK_RETRY_MS = 125;
+export const LOCK_TIMEOUT_MS = 5000;
+export const STALE_LOCK_MS = 60_000;
+
+export function ensureArray(value: unknown): string[] {
+	return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+}
+
+function coerceEntry(value: unknown, allowTargetPhase: boolean): OpenQuestionEntry | CarryForwardEntry | null {
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		if (!trimmed) return null;
+		return { description: trimmed };
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const raw = value as Record<string, unknown>;
+	const entry: CarryForwardEntry = {};
+	if (typeof raw.id === "string" && raw.id.trim()) entry.id = raw.id.trim();
+	if (typeof raw.kind === "string" && raw.kind.trim()) entry.kind = raw.kind.trim();
+	if (typeof raw.description === "string" && raw.description.trim()) entry.description = raw.description.trim();
+	if (typeof raw.deferred_reason === "string" && raw.deferred_reason.trim()) entry.deferred_reason = raw.deferred_reason.trim();
+	if (allowTargetPhase && typeof raw.target_phase === "string" && raw.target_phase.trim()) entry.target_phase = raw.target_phase.trim();
+	return Object.keys(entry).length > 0 ? entry : null;
+}
+
+export function ensureEntryArray<T extends OpenQuestionEntry>(value: unknown, allowTargetPhase: boolean = false): T[] {
+	if (!Array.isArray(value)) return [];
+	const result: T[] = [];
+	for (const item of value) {
+		const coerced = coerceEntry(item, allowTargetPhase);
+		if (coerced) result.push(coerced as T);
+	}
+	return result;
+}
+
+export function ensurePhaseRecord(value: unknown): Record<string, StatusPhase> {
+	if (!value || typeof value !== "object") return {};
+	const record = value as Record<string, unknown>;
+	const result: Record<string, StatusPhase> = {};
+	for (const [phaseId, phaseValue] of Object.entries(record)) {
+		const phase = (phaseValue ?? {}) as Partial<StatusPhase>;
+		result[phaseId] = {
+			status: typeof phase.status === "string" ? phase.status : "pending",
+			owner_notes: ensureArray(phase.owner_notes),
+			outputs_present: ensureArray(phase.outputs_present),
+			open_questions: ensureEntryArray<OpenQuestionEntry>(phase.open_questions, false),
+			carry_forward: ensureEntryArray<CarryForwardEntry>(phase.carry_forward, true),
+		};
+	}
+	return result;
+}
+
+export function createEmptyStatus(projectName: string, pipelinePath: string, pipeline: PipelineFile): NormalizedStatus {
+	const phases: Record<string, StatusPhase> = {};
+	for (const phaseId of pipeline.phase_order) {
+		phases[phaseId] = {
+			status: "pending",
+			owner_notes: [],
+			outputs_present: [],
+			open_questions: [],
+			carry_forward: [],
+		};
+	}
+
+	const firstPhase = pipeline.phase_order[0] ?? "complete";
+	const phaseMap = new Map<string, PipelinePhase>(pipeline.phases.map((phase) => [phase.id, phase]));
+	const firstPhaseConfig = phaseMap.get(firstPhase);
+
+	return {
+		project_name: projectName,
+		pipeline: pipelinePath,
+		current_phase: firstPhase,
+		last_updated: "",
+		phases,
+		next_actions: firstPhaseConfig?.primary_output
+			? [`Begin ${firstPhase} phase by producing ${firstPhaseConfig.primary_output}`]
+			: ["Begin the first pending phase."],
+	};
+}
+
+export function normalizeStatus(status: StatusFile, pipeline: PipelineFile, pipelinePath: string, cwd: string): NormalizedStatus {
+	const phases = ensurePhaseRecord(status.phases);
+	for (const phaseId of pipeline.phase_order) {
+		if (!phases[phaseId]) {
+			phases[phaseId] = {
+				status: "pending",
+				owner_notes: [],
+				outputs_present: [],
+				open_questions: [],
+				carry_forward: [],
+			};
+		}
+	}
+
+	return {
+		project_name: status.project_name?.trim() || basename(cwd),
+		pipeline: status.pipeline?.trim() || pipelinePath,
+		current_phase: status.current_phase?.trim() || pipeline.phase_order[0] || "complete",
+		last_updated: status.last_updated?.trim() || "",
+		phases,
+		next_actions: ensureArray(status.next_actions),
+	};
+}
+
+export async function acquireLock(lockPath: string): Promise<{ release: () => Promise<void> }> {
+	const startedAt = Date.now();
+
+	while (true) {
+		try {
+			const handle = await open(lockPath, "wx");
+			await handle.writeFile(`${process.pid}\n${new Date().toISOString()}\n`, "utf8");
+			await handle.close();
+			return {
+				release: async () => {
+					await rm(lockPath, { force: true }).catch(() => undefined);
+				},
+			};
+		} catch (error) {
+			const nodeError = error as NodeJS.ErrnoException;
+			if (nodeError.code !== "EEXIST") throw error;
+
+			try {
+				const lockStat = await stat(lockPath);
+				if (Date.now() - lockStat.mtimeMs > STALE_LOCK_MS) {
+					await rm(lockPath, { force: true }).catch(() => undefined);
+					continue;
+				}
+			} catch {
+				continue;
+			}
+
+			if (Date.now() - startedAt > LOCK_TIMEOUT_MS) {
+				throw new Error(`Timed out waiting for lock: ${lockPath}`);
+			}
+
+			await sleep(LOCK_RETRY_MS);
+		}
+	}
+}

package/core/types.ts

@@ -0,0 +1,96 @@
+// Shared schema types for the CodeCartographer framework.
+// Both the Pi extension and the MCP server import from here so the schema
+// has a single source of truth.
+
+export type PhaseStatusValue = "pending" | "complete" | "partial" | "in-progress";
+
+export const OPEN_QUESTION_KINDS = [
+	"needs-runtime-test",
+	"needs-maintainer-decision",
+	"needs-spec-ruling",
+	"defer-to-phase",
+	"needs-fixture-capture",
+] as const;
+
+export type EntryKind = (typeof OPEN_QUESTION_KINDS)[number] | string;
+
+export type OpenQuestionEntry = {
+	id?: string;
+	kind?: EntryKind;
+	description?: string;
+	deferred_reason?: string;
+};
+
+export type CarryForwardEntry = OpenQuestionEntry & {
+	target_phase?: string;
+};
+
+export type StatusPhase = {
+	status: PhaseStatusValue | string;
+	owner_notes: string[];
+	outputs_present: string[];
+	open_questions: OpenQuestionEntry[];
+	carry_forward: CarryForwardEntry[];
+};
+
+export type StatusFile = {
+	project_name?: string;
+	pipeline?: string;
+	current_phase?: string;
+	last_updated?: string;
+	phases?: Record<string, StatusPhase>;
+	next_actions?: string[];
+};
+
+export type SecondaryOutput = {
+	path: string;
+	mode?: string;
+};
+
+export type PipelinePhase = {
+	id: string;
+	purpose?: string;
+	skill_path?: string;
+	output_template?: string;
+	depends_on?: string[];
+	primary_output?: string;
+	secondary_outputs?: SecondaryOutput[];
+	required_reads?: string[];
+	completion_criteria?: string[];
+	handoff_requirements?: string[];
+};
+
+export type PipelineFile = {
+	workflow_name?: string;
+	workflow_version?: number;
+	workflow_goal?: string;
+	source_location?: string;
+	validation_protocol?: string;
+	phase_order: string[];
+	phases: PipelinePhase[];
+};
+
+export type NormalizedStatus = Required<Pick<StatusFile, "project_name" | "pipeline" | "current_phase" | "last_updated" | "phases" | "next_actions">>;
+
+export type WorkspaceState = {
+	cwd: string;
+	workspaceDir: string;
+	statusPath: string;
+	pipelinePath: string;
+	status: NormalizedStatus;
+	pipeline: PipelineFile;
+};
+
+export type ValidationOverall = "PASS" | "PASS WITH GAPS" | "FAIL" | "MISSING";
+
+export type ValidationResult = {
+	phaseId: string;
+	primaryOutput: string;
+	outputPath: string;
+	exists: boolean;
+	hasValidationBlock: boolean;
+	overall: ValidationOverall;
+	rows: Array<{ criterion: string; result: string; evidence: string }>;
+	gaps: string[];
+	errors: string[];
+};

package/core/utils.ts

@@ -0,0 +1,52 @@
+// General-purpose helpers used by yaml/status/prompts and by wrapper-specific
+// path-boundary enforcement (Pi tool interception, MCP cwd validation).
+
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { normalize, resolve } from "node:path";
+import { realpath } from "node:fs/promises";
+
+export function sleep(ms: number): Promise<void> {
+	return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+
+export async function pathExists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function canonicalPath(path: string): Promise<string> {
+	try {
+		return await realpath(path);
+	} catch {
+		return resolve(path);
+	}
+}
+
+export function normalizeForComparison(path: string): string {
+	const normalized = normalize(path);
+	return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+export function isWithinPath(path: string, root: string): boolean {
+	const normalizedPath = normalizeForComparison(resolve(path));
+	const normalizedRoot = normalizeForComparison(resolve(root));
+	if (normalizedPath === normalizedRoot) return true;
+	return normalizedPath.startsWith(`${normalizedRoot}${process.platform === "win32" ? "\\" : "/"}`);
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function uniqueStrings(items: string[]): string[] {
+	return [...new Set(items.filter(Boolean))];
+}
+
+export function dateOnly(timestamp: string): string {
+	return timestamp.slice(0, 10);
+}

package/core/workspace.ts

@@ -0,0 +1,81 @@
+// Workspace bootstrap: resolves the packaged .codecarto/ template directory
+// (so the MCP server and Pi can both copy from it on /codecarto-init), loads
+// + normalizes the per-project workspace state from disk, and provides the
+// atomic status-update primitive used by /codecarto-complete.
+
+import { appendFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { acquireLock, normalizeStatus } from "./status.ts";
+import type { PipelineFile, StatusFile, WorkspaceState } from "./types.ts";
+import { pathExists } from "./utils.ts";
+import { loadYamlFile, stringifySimpleYaml } from "./yaml.ts";
+
+const coreDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(coreDir, "..");
+
+// Path to the packaged framework template directory. Wrappers copy this on
+// /codecarto-init.
+export const packagedWorkspaceDir = join(packageRoot, ".codecarto");
+
+export async function getWorkspaceState(cwd: string): Promise<WorkspaceState | null> {
+	const workspaceDir = join(cwd, ".codecarto");
+	const statusPath = join(workspaceDir, "workflow", "status.yaml");
+	if (!(await pathExists(statusPath))) return null;
+
+	const rawStatus = await loadYamlFile<StatusFile>(statusPath);
+	const pipelineRelativePath = rawStatus.pipeline?.trim();
+	if (!pipelineRelativePath) {
+		throw new Error(`Missing pipeline in ${relative(cwd, statusPath) || statusPath}`);
+	}
+
+	const pipelinePath = join(workspaceDir, pipelineRelativePath);
+	if (!(await pathExists(pipelinePath))) {
+		throw new Error(`Active pipeline does not exist: ${relative(cwd, pipelinePath) || pipelinePath}`);
+	}
+
+	const pipeline = await loadYamlFile<PipelineFile>(pipelinePath);
+	const status = normalizeStatus(rawStatus, pipeline, pipelineRelativePath, cwd);
+
+	return {
+		cwd,
+		workspaceDir,
+		statusPath,
+		pipelinePath,
+		pipeline,
+		status,
+	};
+}
+
+export async function updateStatusAtomically(
+	cwd: string,
+	updater: (state: WorkspaceState) => Promise<{ state: WorkspaceState; threadLogEntry?: string }> | { state: WorkspaceState; threadLogEntry?: string },
+): Promise<WorkspaceState> {
+	const workspaceDir = join(cwd, ".codecarto");
+	const statusPath = join(workspaceDir, "workflow", "status.yaml");
+	const lockPath = `${statusPath}.lock`;
+	const lock = await acquireLock(lockPath);
+
+	try {
+		const currentState = await getWorkspaceState(cwd);
+		if (!currentState) {
+			throw new Error("CodeCartographer workspace not found. Run /codecarto-init first.");
+		}
+
+		const result = await updater(currentState);
+		const nextState = result.state;
+		const serialized = `${stringifySimpleYaml(nextState.status)}\n`;
+		const tempPath = `${statusPath}.${process.pid}.${Date.now()}.tmp`;
+		await writeFile(tempPath, serialized, "utf8");
+		await rename(tempPath, statusPath);
+
+		if (result.threadLogEntry) {
+			const threadLogPath = join(workspaceDir, "THREAD_LOG.md");
+			await appendFile(threadLogPath, result.threadLogEntry, "utf8");
+		}
+
+		return nextState;
+	} finally {
+		await lock.release();
+	}
+}