@koan-labs/koan 0.2.0

package/dist/core/crystallize.js

@@ -0,0 +1,124 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { CORE_DOCUMENTS, LAZY_DOCUMENTS } from "./constants.js";
+import { executeWritePlan, sanitizeRegionContent } from "./documents.js";
+import { defaultProfile, loadProfile } from "./profile.js";
+import { PHILOSOPHY_BOOTSTRAP, findProjectRoot, loadProjectConfig } from "./project.js";
+import { getQuestion } from "./questions.js";
+import { DEFAULT_CONVERGENCE_THRESHOLD } from "./schemas.js";
+import { createInitialLedger, loadLedger, unresolvedAxes } from "./scoring.js";
+import { loadSessionState } from "./session.js";
+// Deterministic mapping from answered axes to managed regions. goal.md and
+// plan.md always exist after hello; lazy documents are bootstrapped with their
+// H1 the first time an answer lands in them.
+const AXIS_TARGETS = [
+    { axis: "current_goal", path: CORE_DOCUMENTS.goal, region: "active-goal" },
+    { axis: "purpose", path: CORE_DOCUMENTS.goal, region: "purpose" },
+    { axis: "target_users", path: CORE_DOCUMENTS.goal, region: "target-users" },
+    { axis: "scope", path: CORE_DOCUMENTS.goal, region: "scope" },
+    { axis: "non_goals", path: CORE_DOCUMENTS.goal, region: "non-goals" },
+    { axis: "success_criteria", path: CORE_DOCUMENTS.goal, region: "success-criteria" },
+    { axis: "constraints", path: CORE_DOCUMENTS.goal, region: "constraints" },
+    { axis: "implementation_plan", path: CORE_DOCUMENTS.plan, region: "implementation-plan" },
+    {
+        axis: "philosophical_intent",
+        path: LAZY_DOCUMENTS.philosophy,
+        region: "philosophy",
+        bootstrapHeader: PHILOSOPHY_BOOTSTRAP
+    },
+    { axis: "qa_criteria", path: LAZY_DOCUMENTS.qa, region: "qa-criteria", bootstrapHeader: "# QA\n" },
+    { axis: "handoff_readiness", path: LAZY_DOCUMENTS.handoff, region: "handoff-context", bootstrapHeader: "# Handoff\n" }
+];
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function crystallize(input) {
+    const projectRoot = await findProjectRoot(input.cwd);
+    const state = await loadSessionState(projectRoot);
+    if (!state)
+        throw new Error("No active Koan session. Run koan hello first.");
+    if (!state.activeGoalId || state.phase === "archived") {
+        throw new Error("No active goal. Run koan hello first.");
+    }
+    const isoDate = input.isoDate ?? new Date().toISOString();
+    const description = "Crystallize recorded answers into project documents";
+    const latestAnswers = new Map();
+    for (const answer of state.answers) {
+        latestAnswers.set(answer.axis, answer.answer);
+    }
+    const targets = AXIS_TARGETS.filter((target) => latestAnswers.has(target.axis));
+    const crystallizedAxes = targets.map((target) => target.axis);
+    if (crystallizedAxes.length === 0) {
+        return {
+            projectRoot,
+            plan: { description, operations: [] },
+            executed: false,
+            files: [],
+            crystallizedAxes: []
+        };
+    }
+    const operations = [];
+    for (const target of targets) {
+        if (target.bootstrapHeader && !(await exists(join(projectRoot, target.path)))) {
+            operations.push({ type: "write", path: target.path, content: target.bootstrapHeader });
+        }
+        operations.push({
+            type: "managed-region",
+            path: target.path,
+            name: target.region,
+            content: sanitizeRegionContent((latestAnswers.get(target.axis) ?? "").trim())
+        });
+    }
+    const stored = await loadLedger(projectRoot);
+    const ledger = stored && stored.goalId === state.activeGoalId ? stored : createInitialLedger(state.activeGoalId, isoDate);
+    const threshold = (await loadProjectConfig(projectRoot))?.settings.convergenceThreshold ?? DEFAULT_CONVERGENCE_THRESHOLD;
+    const unresolved = unresolvedAxes(ledger, threshold);
+    const hasOpenQuestionsFile = await exists(join(projectRoot, LAZY_DOCUMENTS.openQuestions));
+    if (unresolved.length > 0) {
+        const profile = (await loadProfile(input.homeDir)) ?? defaultProfile();
+        if (!hasOpenQuestionsFile) {
+            operations.push({ type: "write", path: LAZY_DOCUMENTS.openQuestions, content: "# Open Questions\n" });
+        }
+        operations.push({
+            type: "managed-region",
+            path: LAZY_DOCUMENTS.openQuestions,
+            name: "open-questions",
+            content: unresolved
+                .map((axis) => `- ${axis}: ${getQuestion(axis, profile).userFacingQuestion}`)
+                .join("\n")
+        });
+    }
+    else if (hasOpenQuestionsFile) {
+        operations.push({
+            type: "managed-region",
+            path: LAZY_DOCUMENTS.openQuestions,
+            name: "open-questions",
+            content: "None."
+        });
+    }
+    operations.push({
+        type: "append",
+        path: LAZY_DOCUMENTS.decisions,
+        content: `## ${isoDate} — koan crystallize\n\nCrystallized axes: ${crystallizedAxes.join(", ")}.`,
+        headerIfMissing: "# Decisions"
+    });
+    const plan = { description, operations };
+    const files = [];
+    for (const operation of operations) {
+        if (!files.includes(operation.path))
+            files.push(operation.path);
+    }
+    if (input.dryRun) {
+        return { projectRoot, plan, executed: false, files, crystallizedAxes };
+    }
+    await executeWritePlan(projectRoot, plan, {
+        log: { command: "koan crystallize", summary: `Crystallized ${crystallizedAxes.length} axes.` }
+    });
+    return { projectRoot, plan, executed: true, files, crystallizedAxes };
+}

package/dist/core/documents.d.ts

@@ -0,0 +1,11 @@
+import { type CommandLogInput } from "./commandLog.js";
+import { type WritePlan } from "./schemas.js";
+export interface WritePlanOptions {
+    log?: CommandLogInput;
+}
+export declare function replaceManagedRegion(input: string, name: string, content: string): string;
+export declare function readManagedSection(text: string, name: string): string | null;
+export declare function appendLogEntry(input: string, source: string, content: string, isoDate?: string): string;
+export declare function buildManagedRegion(name: string, content: string): string;
+export declare function sanitizeRegionContent(text: string): string;
+export declare function executeWritePlan(projectRoot: string, plan: WritePlan, options?: WritePlanOptions): Promise<void>;

package/dist/core/documents.js

@@ -0,0 +1,72 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { appendCommandLogInLock } from "./commandLog.js";
+import { managedEnd, managedStart } from "./constants.js";
+import { withFileLock } from "./lock.js";
+async function readExisting(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+export function replaceManagedRegion(input, name, content) {
+    const startMarker = managedStart(name);
+    const endMarker = managedEnd(name);
+    const start = input.indexOf(startMarker);
+    const end = input.indexOf(endMarker);
+    const block = `${startMarker}\n${content.trimEnd()}\n${endMarker}`;
+    if (start >= 0 && end > start) {
+        return `${input.slice(0, start)}${block}${input.slice(end + endMarker.length)}`;
+    }
+    const prefix = input.trimEnd().length > 0 ? `${input.trimEnd()}\n\n` : "";
+    return `${prefix}${block}\n`;
+}
+export function readManagedSection(text, name) {
+    const startMarker = managedStart(name);
+    const endMarker = managedEnd(name);
+    const start = text.indexOf(startMarker);
+    const end = text.indexOf(endMarker);
+    if (start < 0 || end <= start)
+        return null;
+    return text.slice(start + startMarker.length, end).trim();
+}
+export function appendLogEntry(input, source, content, isoDate = new Date().toISOString()) {
+    const entry = [`## ${isoDate} — ${source}`, "", content.trimEnd(), ""].join("\n");
+    return `${input.trimEnd()}\n\n${entry}`;
+}
+export function buildManagedRegion(name, content) {
+    return `${managedStart(name)}\n${content.trimEnd()}\n${managedEnd(name)}`;
+}
+export function sanitizeRegionContent(text) {
+    return text.replaceAll("<!-- koan:", "<!- koan:");
+}
+export async function executeWritePlan(projectRoot, plan, options = {}) {
+    await withFileLock(projectRoot, async () => {
+        for (const operation of plan.operations) {
+            const absolute = join(projectRoot, operation.path);
+            await mkdir(dirname(absolute), { recursive: true });
+            if (operation.type === "write") {
+                await writeFile(absolute, operation.content, "utf8");
+            }
+            if (operation.type === "append") {
+                const current = await readExisting(absolute);
+                const base = current.trimEnd();
+                const prefix = base.length > 0
+                    ? `${base}\n\n`
+                    : operation.headerIfMissing
+                        ? `${operation.headerIfMissing.trimEnd()}\n\n`
+                        : "";
+                await writeFile(absolute, `${prefix}${operation.content.trimEnd()}\n`, "utf8");
+            }
+            if (operation.type === "managed-region") {
+                const current = await readExisting(absolute);
+                await writeFile(absolute, replaceManagedRegion(current, operation.name, operation.content), "utf8");
+            }
+        }
+        if (options.log) {
+            await appendCommandLogInLock(projectRoot, options.log);
+        }
+    });
+}

package/dist/core/gitPolicy.d.ts

@@ -0,0 +1,2 @@
+export declare function defaultKoanGitignore(): string;
+export declare function ensureStateGitignore(projectRoot: string): Promise<void>;

package/dist/core/gitPolicy.js

@@ -0,0 +1,25 @@
+import { access, mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { STATE_FILES } from "./constants.js";
+export function defaultKoanGitignore() {
+    return [
+        "user-profile-ref.json",
+        "session-state.json",
+        "ambiguity-ledger.json",
+        "command-log.json",
+        "mcp-cache.json",
+        "write.lock*",
+        "*.bak",
+        ""
+    ].join("\n");
+}
+export async function ensureStateGitignore(projectRoot) {
+    const path = join(projectRoot, STATE_FILES.gitignore);
+    try {
+        await access(path);
+    }
+    catch {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, defaultKoanGitignore(), "utf8");
+    }
+}

package/dist/core/handoff.d.ts

@@ -0,0 +1,5 @@
+export interface HandoffDocumentInput {
+    summary: string;
+    experimentalHandoff: boolean;
+}
+export declare function buildHandoffDocument(input: HandoffDocumentInput): string;

package/dist/core/handoff.js

@@ -0,0 +1,20 @@
+export function buildHandoffDocument(input) {
+    const experimentalStatus = input.experimentalHandoff
+        ? "MVP status: extension flag enabled, but no touchless adapter is implemented."
+        : "MVP status: disabled. This handoff is document-based.";
+    return [
+        "# Handoff",
+        "",
+        "Read `koan/philosophy.md` first when it exists. Keep the continuation",
+        "aligned with the product philosophy, not just the remaining task list.",
+        "",
+        "## Current Summary",
+        "",
+        input.summary,
+        "",
+        "## Experimental Touchless Handoff",
+        "",
+        experimentalStatus,
+        ""
+    ].join("\n");
+}

package/dist/core/hostAdapter.d.ts

@@ -0,0 +1,8 @@
+export type HostId = "claude" | "codex" | "generic";
+export interface HostAdapter {
+    questionInstruction: string;
+    qaPrompt: string;
+    prdSynthesisInstruction: string;
+}
+export declare function detectHost(clientName?: string): HostId;
+export declare function adapterFor(host: HostId): HostAdapter;

package/dist/core/hostAdapter.js

@@ -0,0 +1,34 @@
+// Host adapters tune how Koan speaks to the host agent, not what it says:
+// every variant must carry the same contract (preserve user reasoning,
+// structured answer recording, philosophy-aware QA, no invented requirements)
+// in the phrasing that works best for that model family. The variants are
+// static strings — no network, no model calls. See docs/host-adapters.md for
+// the vendor-guide rationale behind each variant.
+export function detectHost(clientName) {
+    const name = clientName?.toLowerCase() ?? "";
+    if (name.includes("claude"))
+        return "claude";
+    if (name.includes("codex") || name.includes("openai") || name.includes("gpt"))
+        return "codex";
+    return "generic";
+}
+const adapters = {
+    generic: {
+        questionInstruction: "Preserve the user's reasoning. If using MCP mode, structure the answer into decision, reasoning, constraints, out-of-scope, and project context before recording it. If the answer reveals that the real product differs from the surface request, record that realization with koan_record_insight.",
+        qaPrompt: "Compare the implementation summary against Koan documents, including `koan/philosophy.md` when it exists. Separate Koan-spec compliance issues, philosophy-alignment issues, and general quality issues.",
+        prdSynthesisInstruction: "Synthesize this section from the recorded answers and `koan/philosophy.md` only; do not invent requirements the user never stated. Write the result with koan_synthesize_prd."
+    },
+    claude: {
+        questionInstruction: "Preserve the user's exact reasoning — quote their key phrases instead of paraphrasing them away. Before recording, structure the answer as: decision, reasoning, constraints, out-of-scope, and project context. Consider what the answer implies before scoring clarity. If the answer reveals that the real product differs from the surface request, record that realization with koan_record_insight before asking the next question.",
+        qaPrompt: "Review the implementation against the Koan documents, reading `koan/philosophy.md` first when it exists. Report findings in three separate groups — Koan-spec compliance issues, philosophy-alignment issues, and general quality issues — and cite the document passage each finding violates.",
+        prdSynthesisInstruction: "Synthesize this section strictly from the recorded answers and `koan/philosophy.md`: ground every sentence in something the user actually said and prefer their own wording. Do not invent requirements the user never stated. Write the result with koan_synthesize_prd."
+    },
+    codex: {
+        questionInstruction: "Preserve the user's reasoning verbatim where possible. Record the answer structured as: decision; reasoning; constraints; out-of-scope; project context. Score clarity conservatively. If the answer reveals that the real product differs from the surface request, call koan_record_insight with that realization.",
+        qaPrompt: "Compare the implementation against Koan documents; read `koan/philosophy.md` first when it exists. Output three lists: Koan-spec compliance issues; philosophy-alignment issues; general quality issues. Review only — do not fix.",
+        prdSynthesisInstruction: "Synthesize from the recorded answers and `koan/philosophy.md` only. Do not invent requirements the user never stated. Keep the user's wording. Write the result with koan_synthesize_prd."
+    }
+};
+export function adapterFor(host) {
+    return adapters[host];
+}

package/dist/core/lock.d.ts

@@ -0,0 +1,5 @@
+export declare const LOCK_STALE_MS: number;
+export declare class KoanLockError extends Error {
+    constructor(message: string);
+}
+export declare function withFileLock<T>(projectRoot: string, fn: () => Promise<T>): Promise<T>;

package/dist/core/lock.js

@@ -0,0 +1,142 @@
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { STATE_FILES } from "./constants.js";
+export const LOCK_STALE_MS = 10 * 60 * 1000;
+export class KoanLockError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "KoanLockError";
+    }
+}
+function lockPayload(token) {
+    return `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString(), token })}\n`;
+}
+function parseLockInfo(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.pid !== "number" || typeof parsed.createdAt !== "string")
+            return null;
+        if (Number.isNaN(Date.parse(parsed.createdAt)))
+            return null;
+        return {
+            pid: parsed.pid,
+            createdAt: parsed.createdAt,
+            token: typeof parsed.token === "string" ? parsed.token : null
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function inspectLock(lockPath) {
+    let raw;
+    try {
+        raw = await readFile(lockPath, "utf8");
+    }
+    catch {
+        return { stale: true, holderPid: null, raw: null };
+    }
+    const info = parseLockInfo(raw);
+    if (info) {
+        const expired = Date.now() - Date.parse(info.createdAt) > LOCK_STALE_MS;
+        return { stale: !isPidAlive(info.pid) || expired, holderPid: info.pid, raw };
+    }
+    try {
+        const stats = await stat(lockPath);
+        return { stale: Date.now() - stats.mtimeMs > LOCK_STALE_MS, holderPid: null, raw };
+    }
+    catch {
+        return { stale: true, holderPid: null, raw };
+    }
+}
+async function tryAcquire(lockPath, token) {
+    try {
+        await writeFile(lockPath, lockPayload(token), { encoding: "utf8", flag: "wx" });
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+}
+async function reclaimStaleLock(lockPath, expectedRaw) {
+    // rename is atomic: of N processes that judged the same lock stale, only
+    // the rename winner proceeds; losers fall through to the single retry.
+    const reclaimPath = `${lockPath}.reclaim-${process.pid}-${randomUUID()}`;
+    try {
+        await rename(lockPath, reclaimPath);
+    }
+    catch {
+        return;
+    }
+    let reclaimedRaw = null;
+    try {
+        reclaimedRaw = await readFile(reclaimPath, "utf8");
+    }
+    catch {
+        reclaimedRaw = null;
+    }
+    if (reclaimedRaw !== null && reclaimedRaw !== expectedRaw) {
+        // The lock changed between inspection and rename: a fresh holder was
+        // displaced. Restore it; if restore loses a race to a newer acquirer,
+        // the displaced holder's release is token-checked and harmless.
+        try {
+            await rename(reclaimPath, lockPath);
+            return;
+        }
+        catch {
+            // fall through to remove the displaced copy
+        }
+    }
+    await rm(reclaimPath, { force: true });
+}
+async function releaseLock(lockPath, token) {
+    let raw;
+    try {
+        raw = await readFile(lockPath, "utf8");
+    }
+    catch {
+        return;
+    }
+    if (parseLockInfo(raw)?.token === token) {
+        await rm(lockPath, { force: true });
+    }
+}
+// Advisory single-writer lock (spec §6.4): stop-on-conflict guidance for a
+// one-writer-at-a-time model, not contention-grade mutual exclusion. Without
+// OS-level flock a microsecond window remains between staleness inspection
+// and reclaim/release; reclaim verifies the displaced payload and restores
+// fresh locks, and release only removes a lock holding its own token.
+export async function withFileLock(projectRoot, fn) {
+    const lockPath = join(projectRoot, STATE_FILES.lock);
+    await mkdir(dirname(lockPath), { recursive: true });
+    const token = randomUUID();
+    if (!(await tryAcquire(lockPath, token))) {
+        const inspection = await inspectLock(lockPath);
+        if (!inspection.stale) {
+            const holder = inspection.holderPid === null ? "another process" : `pid ${inspection.holderPid}`;
+            throw new KoanLockError(`Koan write lock at ${STATE_FILES.lock} is held by ${holder}. Remove ${STATE_FILES.lock} if no Koan process is running.`);
+        }
+        await reclaimStaleLock(lockPath, inspection.raw);
+        if (!(await tryAcquire(lockPath, token))) {
+            throw new KoanLockError(`Koan write lock already exists at ${STATE_FILES.lock}`);
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await releaseLock(lockPath, token);
+    }
+}

package/dist/core/mcpCache.d.ts

@@ -0,0 +1,4 @@
+import { type McpCache } from "./schemas.js";
+export declare function loadMcpCache(projectRoot: string): Promise<McpCache>;
+export declare function saveMcpCache(projectRoot: string, cache: McpCache): Promise<void>;
+export declare function updateMcpCache(projectRoot: string, mutate: (cache: McpCache) => McpCache): Promise<McpCache>;

package/dist/core/mcpCache.js

@@ -0,0 +1,37 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { STATE_FILES } from "./constants.js";
+import { ensureStateGitignore } from "./gitPolicy.js";
+import { McpCacheSchema } from "./schemas.js";
+import { withFileLock } from "./lock.js";
+function freshMcpCache() {
+    return { version: 1, lastQuestion: null, rawIntent: null };
+}
+export async function loadMcpCache(projectRoot) {
+    try {
+        const raw = await readFile(join(projectRoot, STATE_FILES.mcpCache), "utf8");
+        return McpCacheSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        return freshMcpCache();
+    }
+}
+// Caller must hold the project write lock.
+async function writeMcpCacheUnlocked(projectRoot, cache) {
+    const parsed = McpCacheSchema.parse(cache);
+    const path = join(projectRoot, STATE_FILES.mcpCache);
+    await ensureStateGitignore(projectRoot);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
+    return parsed;
+}
+export async function saveMcpCache(projectRoot, cache) {
+    await withFileLock(projectRoot, async () => {
+        await writeMcpCacheUnlocked(projectRoot, cache);
+    });
+}
+// Atomic read-modify-write: load, mutate, and persist happen inside a single
+// file lock so concurrent tool calls cannot interleave between read and write.
+export async function updateMcpCache(projectRoot, mutate) {
+    return withFileLock(projectRoot, async () => writeMcpCacheUnlocked(projectRoot, mutate(await loadMcpCache(projectRoot))));
+}

package/dist/core/prd.d.ts

@@ -0,0 +1,33 @@
+import { type HostId } from "./hostAdapter.js";
+import { type AmbiguityAxis, type WritePlan } from "./schemas.js";
+export interface PrdHostSections {
+    vision?: string;
+    coreValue?: string;
+    problemAntiProblem?: string;
+    userStories?: string;
+}
+export interface BuildPrdInput {
+    cwd: string;
+    homeDir: string;
+    sections?: PrdHostSections;
+    host?: HostId;
+    dryRun?: boolean;
+    isoDate?: string;
+}
+export interface BuildPrdResult {
+    projectRoot: string;
+    path: string;
+    plan: WritePlan;
+    executed: boolean;
+    document: string | null;
+}
+interface PrdSection {
+    region: string;
+    title: string;
+    axis?: AmbiguityAxis;
+    hostKey?: keyof PrdHostSections;
+}
+export declare const PRD_SECTIONS: readonly PrdSection[];
+export declare function parseInsights(philosophyText: string): string[];
+export declare function buildPrd(input: BuildPrdInput): Promise<BuildPrdResult>;
+export {};