@koan-labs/koan 0.2.0

package/dist/core/prd.js

@@ -0,0 +1,151 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { LAZY_DOCUMENTS, managedEnd, managedStart } from "./constants.js";
+import { executeWritePlan, readManagedSection, sanitizeRegionContent } from "./documents.js";
+import { adapterFor } from "./hostAdapter.js";
+import { findProjectRoot, loadProjectConfig } from "./project.js";
+import { DEFAULT_CONVERGENCE_THRESHOLD } from "./schemas.js";
+import { createInitialLedger, loadLedger, unresolvedAxes } from "./scoring.js";
+import { loadSessionState } from "./session.js";
+// §10 output contract order: philosophy first, residual ambiguity last.
+export const PRD_SECTIONS = [
+    { region: "philosophy", title: "Philosophy / Why", axis: "philosophical_intent" },
+    { region: "vision", title: "Product Vision", hostKey: "vision" },
+    { region: "core-value", title: "Core Value", hostKey: "coreValue" },
+    { region: "target-users", title: "Target Users", axis: "target_users" },
+    { region: "problem-anti-problem", title: "Problem and Anti-Problem", hostKey: "problemAntiProblem" },
+    { region: "scope", title: "Scope", axis: "scope" },
+    { region: "non-goals", title: "Non-Goals", axis: "non_goals" },
+    { region: "user-stories", title: "User Stories", hostKey: "userStories" },
+    { region: "success-criteria", title: "Success Criteria", axis: "success_criteria" },
+    { region: "implementation-plan", title: "Implementation Plan", axis: "implementation_plan" },
+    { region: "qa-criteria", title: "QA Criteria", axis: "qa_criteria" },
+    { region: "handoff-notes", title: "Handoff Notes", axis: "handoff_readiness" },
+    { region: "residual-ambiguity", title: "Residual Ambiguity" }
+];
+const NOT_CLARIFIED_PREFIX = "_Not yet clarified";
+const PENDING_SYNTHESIS_PREFIX = "_Pending host synthesis.";
+function notClarified(axis) {
+    return `${NOT_CLARIFIED_PREFIX} (answer the \`${axis}\` question)._`;
+}
+function pendingSynthesis(host) {
+    return `${PENDING_SYNTHESIS_PREFIX} ${adapterFor(host).prdSynthesisInstruction}_`;
+}
+function isPlaceholder(content) {
+    return (content === null ||
+        content.length === 0 ||
+        content.startsWith(NOT_CLARIFIED_PREFIX) ||
+        content.startsWith(PENDING_SYNTHESIS_PREFIX));
+}
+function prdSkeleton() {
+    const lines = [
+        "# PRD",
+        "",
+        "Synthesized by `koan prd` and `koan_synthesize_prd` from recorded Koan",
+        "answers and `koan/philosophy.md`. Managed regions are rewritten on every",
+        "synthesis; content outside the markers is preserved.",
+        ""
+    ];
+    for (const section of PRD_SECTIONS) {
+        lines.push(`## ${section.title}`, "", managedStart(section.region), managedEnd(section.region), "");
+    }
+    return lines.join("\n");
+}
+// Best-effort: collect the first line of each `## <iso> — koan insight` entry
+// appended by recordInsight, in file order.
+export function parseInsights(philosophyText) {
+    const insights = [];
+    const blocks = philosophyText.split(/^## /m).slice(1);
+    for (const block of blocks) {
+        const lines = block.split("\n");
+        if (!lines[0]?.includes("— koan insight"))
+            continue;
+        const body = lines.slice(1).find((line) => line.trim().length > 0);
+        if (body)
+            insights.push(body.trim());
+    }
+    return insights;
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function buildPrd(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 host = input.host ?? "generic";
+    const isoDate = input.isoDate ?? new Date().toISOString();
+    const latestAnswers = new Map();
+    for (const answer of state.answers) {
+        latestAnswers.set(answer.axis, answer.answer);
+    }
+    const prdPath = join(projectRoot, LAZY_DOCUMENTS.prd);
+    const prdExists = await exists(prdPath);
+    const existingText = prdExists ? await readFile(prdPath, "utf8") : "";
+    const philosophyText = await readFile(join(projectRoot, LAZY_DOCUMENTS.philosophy), "utf8").catch(() => "");
+    const insights = parseInsights(philosophyText);
+    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 operations = [];
+    if (!prdExists) {
+        operations.push({ type: "write", path: LAZY_DOCUMENTS.prd, content: prdSkeleton() });
+    }
+    for (const section of PRD_SECTIONS) {
+        let content;
+        if (section.region === "philosophy") {
+            const parts = [];
+            const answer = latestAnswers.get("philosophical_intent");
+            parts.push(answer ?? notClarified("philosophical_intent"));
+            if (insights.length > 0) {
+                parts.push("", "Insights (see `koan/philosophy.md` for the full log):");
+                parts.push(...insights.map((insight) => `- ${insight}`));
+            }
+            content = parts.join("\n");
+        }
+        else if (section.region === "residual-ambiguity") {
+            content =
+                unresolved.length === 0
+                    ? "None."
+                    : unresolved.map((axis) => `- \`${axis}\` is below the convergence threshold (${threshold}).`).join("\n");
+        }
+        else if (section.hostKey) {
+            const provided = input.sections?.[section.hostKey]?.trim();
+            const existing = prdExists ? readManagedSection(existingText, section.region) : null;
+            const seed = section.region === "vision" ? latestAnswers.get("purpose") : undefined;
+            content = provided || (!isPlaceholder(existing) ? existing : (seed ?? pendingSynthesis(host)));
+        }
+        else if (section.axis) {
+            content = latestAnswers.get(section.axis) ?? notClarified(section.axis);
+        }
+        else {
+            content = "";
+        }
+        operations.push({
+            type: "managed-region",
+            path: LAZY_DOCUMENTS.prd,
+            name: section.region,
+            content: sanitizeRegionContent(content)
+        });
+    }
+    const plan = { description: "Synthesize the PRD from recorded answers", operations };
+    if (input.dryRun) {
+        return { projectRoot, path: LAZY_DOCUMENTS.prd, plan, executed: false, document: null };
+    }
+    await executeWritePlan(projectRoot, plan, {
+        log: { command: "koan prd", summary: "Synthesized the PRD." }
+    });
+    const document = await readFile(prdPath, "utf8");
+    return { projectRoot, path: LAZY_DOCUMENTS.prd, plan, executed: true, document };
+}

package/dist/core/profile.d.ts

@@ -0,0 +1,8 @@
+import { type Language, type UserProfile } from "./schemas.js";
+export declare function getProfilePath(homeDir: string): string;
+export declare function defaultProfile(overrides?: Partial<UserProfile>): UserProfile;
+export declare function loadProfile(homeDir: string): Promise<UserProfile | null>;
+export declare function saveProfile(homeDir: string, profile: UserProfile): Promise<UserProfile>;
+export declare function updateProfile(homeDir: string, changes: Partial<UserProfile>): Promise<UserProfile>;
+export declare function resetProfile(homeDir: string): Promise<void>;
+export declare function normalizeLanguage(value: string): Language;

package/dist/core/profile.js

@@ -0,0 +1,47 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { UserProfileSchema } from "./schemas.js";
+export function getProfilePath(homeDir) {
+    return join(homeDir, ".koan/profile.json");
+}
+export function defaultProfile(overrides = {}) {
+    return {
+        developmentUnderstanding: "beginner",
+        explanationStyle: "example_first",
+        language: "ko",
+        outputUse: "agent_execution",
+        domainBackground: "",
+        learningMode: "approval_required",
+        ...overrides
+    };
+}
+export async function loadProfile(homeDir) {
+    try {
+        const raw = await readFile(getProfilePath(homeDir), "utf8");
+        return UserProfileSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveProfile(homeDir, profile) {
+    const parsed = UserProfileSchema.parse(profile);
+    const path = getProfilePath(homeDir);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
+    return parsed;
+}
+export async function updateProfile(homeDir, changes) {
+    const approved = UserProfileSchema.partial().parse(changes);
+    const base = (await loadProfile(homeDir)) ?? defaultProfile();
+    const defined = Object.fromEntries(Object.entries(approved).filter(([, value]) => value !== undefined));
+    return saveProfile(homeDir, { ...base, ...defined });
+}
+export async function resetProfile(homeDir) {
+    await rm(getProfilePath(homeDir), { force: true });
+}
+export function normalizeLanguage(value) {
+    if (value === "en" || value === "mixed")
+        return value;
+    return "ko";
+}

package/dist/core/profileRef.d.ts

@@ -0,0 +1,3 @@
+import { type UserProfileRef } from "./schemas.js";
+export declare function loadProfileRef(projectRoot: string): Promise<UserProfileRef | null>;
+export declare function ensureProfileRef(projectRoot: string, homeDir: string): Promise<UserProfileRef>;

package/dist/core/profileRef.js

@@ -0,0 +1,41 @@
+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 { UserProfileRefSchema } from "./schemas.js";
+import { withFileLock } from "./lock.js";
+import { getProfilePath } from "./profile.js";
+export async function loadProfileRef(projectRoot) {
+    try {
+        const raw = await readFile(join(projectRoot, STATE_FILES.userProfileRef), "utf8");
+        return UserProfileRefSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+export async function ensureProfileRef(projectRoot, homeDir) {
+    const path = join(projectRoot, STATE_FILES.userProfileRef);
+    const ref = { version: 1, profilePath: getProfilePath(homeDir), overrides: {} };
+    return withFileLock(projectRoot, async () => {
+        let raw = null;
+        try {
+            raw = await readFile(path, "utf8");
+        }
+        catch {
+            raw = null;
+        }
+        if (raw !== null) {
+            try {
+                return UserProfileRefSchema.parse(JSON.parse(raw));
+            }
+            catch {
+                await writeFile(`${path}.bak`, raw, "utf8");
+            }
+        }
+        await ensureStateGitignore(projectRoot);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, `${JSON.stringify(ref, null, 2)}\n`, "utf8");
+        return ref;
+    });
+}

package/dist/core/project.d.ts

@@ -0,0 +1,17 @@
+import { type ProjectConfig } from "./schemas.js";
+export interface ProjectInspection {
+    projectRoot: string;
+    isKoanProject: boolean;
+    hasAgentsMd: boolean;
+    hasClaudeMd: boolean;
+    hasKoanBootstrap: boolean;
+}
+export declare function findProjectRoot(start: string): Promise<string>;
+export declare function inspectProject(start: string): Promise<ProjectInspection>;
+export declare function patchBootstrap(existing: string): string;
+export declare const DEFAULT_ACTIVE_GOAL_PLACEHOLDER = "No active goal yet.";
+export declare const DEFAULT_PLAN_PLACEHOLDER = "No implementation plan recorded yet.";
+export declare const DEFAULT_STATUS_PLACEHOLDER = "No status recorded yet.";
+export declare const PHILOSOPHY_BOOTSTRAP = "# Philosophy\n\nWhy this product deserves to exist. Read this before implementing; if a\nrequested change conflicts with this philosophy, run a Koan clarification\nloop instead of silently expanding scope.\n";
+export declare function loadProjectConfig(projectRoot: string): Promise<ProjectConfig | null>;
+export declare function ensureKoanProject(start: string): Promise<ProjectConfig>;

package/dist/core/project.js

@@ -0,0 +1,126 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { BOOTSTRAP_END, BOOTSTRAP_START, CORE_DOCUMENTS, KOAN_DIR, KOAN_STATE_DIR, KOAN_VERSION, STATE_FILES } from "./constants.js";
+import { defaultKoanGitignore } from "./gitPolicy.js";
+import { withFileLock } from "./lock.js";
+import { DEFAULT_CONVERGENCE_THRESHOLD, ProjectConfigSchema } from "./schemas.js";
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function findProjectRoot(start) {
+    let current = resolve(start);
+    while (true) {
+        if ((await exists(join(current, "package.json"))) ||
+            (await exists(join(current, ".git"))) ||
+            (await exists(join(current, KOAN_DIR)))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return resolve(start);
+        current = parent;
+    }
+}
+export async function inspectProject(start) {
+    const projectRoot = await findProjectRoot(start);
+    const agentsPath = join(projectRoot, "AGENTS.md");
+    const claudePath = join(projectRoot, "CLAUDE.md");
+    const hasAgentsMd = await exists(agentsPath);
+    const hasClaudeMd = await exists(claudePath);
+    const isKoanProject = await exists(join(projectRoot, STATE_FILES.project));
+    const bootstrapTargets = [agentsPath, claudePath];
+    let hasKoanBootstrap = false;
+    for (const target of bootstrapTargets) {
+        if (await exists(target)) {
+            const text = await readFile(target, "utf8");
+            hasKoanBootstrap = hasKoanBootstrap || text.includes(BOOTSTRAP_START);
+        }
+    }
+    return { projectRoot, isKoanProject, hasAgentsMd, hasClaudeMd, hasKoanBootstrap };
+}
+function bootstrapBlock() {
+    return [
+        BOOTSTRAP_START,
+        "Before working in this project, read:",
+        "1. koan/philosophy.md if it exists — the product philosophy behind every goal",
+        "2. koan/goal.md",
+        "3. koan/status.md",
+        "4. koan/plan.md",
+        "5. koan/handoff.md if continuing prior work",
+        "",
+        "Stay aligned with Koan documents. If the requested work changes scope,",
+        "introduces a new direction, or conflicts with the product philosophy,",
+        "record it through `koan bright-idea` and ask the user to run a Koan",
+        "clarification loop instead of silently expanding scope.",
+        "",
+        "For review work, also read koan/qa.md when it exists.",
+        BOOTSTRAP_END,
+        ""
+    ].join("\n");
+}
+export function patchBootstrap(existing) {
+    const block = bootstrapBlock();
+    const start = existing.indexOf(BOOTSTRAP_START);
+    const end = existing.indexOf(BOOTSTRAP_END);
+    if (start >= 0 && end > start) {
+        return `${existing.slice(0, start)}${block}${existing.slice(end + BOOTSTRAP_END.length).replace(/^\n?/, "")}`;
+    }
+    return existing.trimEnd().length > 0 ? `${existing.trimEnd()}\n\n${block}` : block;
+}
+async function ensureFile(path, content) {
+    if (!(await exists(path))) {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, content, "utf8");
+    }
+}
+async function patchFile(path) {
+    const current = (await exists(path)) ? await readFile(path, "utf8") : "";
+    const next = patchBootstrap(current);
+    if (next !== current)
+        await writeFile(path, next, "utf8");
+}
+export const DEFAULT_ACTIVE_GOAL_PLACEHOLDER = "No active goal yet.";
+export const DEFAULT_PLAN_PLACEHOLDER = "No implementation plan recorded yet.";
+export const DEFAULT_STATUS_PLACEHOLDER = "No status recorded yet.";
+export const PHILOSOPHY_BOOTSTRAP = "# Philosophy\n\nWhy this product deserves to exist. Read this before implementing; if a\nrequested change conflicts with this philosophy, run a Koan clarification\nloop instead of silently expanding scope.\n";
+export async function loadProjectConfig(projectRoot) {
+    try {
+        const raw = await readFile(join(projectRoot, STATE_FILES.project), "utf8");
+        return ProjectConfigSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+export async function ensureKoanProject(start) {
+    const projectRoot = await findProjectRoot(start);
+    return withFileLock(projectRoot, async () => {
+        await mkdir(join(projectRoot, KOAN_DIR), { recursive: true });
+        await mkdir(join(projectRoot, KOAN_STATE_DIR), { recursive: true });
+        await ensureFile(join(projectRoot, CORE_DOCUMENTS.readme), "# Koan Project Memory\n\nRead `philosophy.md` first when it exists, then `goal.md`, `status.md`, and `plan.md`.\n");
+        await ensureFile(join(projectRoot, CORE_DOCUMENTS.goal), `# Goal\n\nThe active goal serves the product philosophy in \`philosophy.md\` when it exists.\n\n## Active Goal\n\n<!-- koan:section:start name="active-goal" -->\n${DEFAULT_ACTIVE_GOAL_PLACEHOLDER}\n<!-- koan:section:end name="active-goal" -->\n`);
+        await ensureFile(join(projectRoot, CORE_DOCUMENTS.status), `# Status\n\n<!-- koan:section:start name="current-status" -->\n${DEFAULT_STATUS_PLACEHOLDER}\n<!-- koan:section:end name="current-status" -->\n`);
+        await ensureFile(join(projectRoot, CORE_DOCUMENTS.plan), `# Plan\n\nImplementation must preserve the product philosophy in \`philosophy.md\` when it exists.\n\n<!-- koan:section:start name="implementation-plan" -->\n${DEFAULT_PLAN_PLACEHOLDER}\n<!-- koan:section:end name="implementation-plan" -->\n`);
+        await ensureFile(join(projectRoot, STATE_FILES.gitignore), defaultKoanGitignore());
+        await patchFile(join(projectRoot, "AGENTS.md"));
+        await patchFile(join(projectRoot, "CLAUDE.md"));
+        const existing = await loadProjectConfig(projectRoot);
+        const config = {
+            version: 1,
+            koanVersion: KOAN_VERSION,
+            projectRoot,
+            strictness: existing?.strictness ?? "advisory",
+            experimentalHandoff: existing?.experimentalHandoff ?? false,
+            documents: CORE_DOCUMENTS,
+            settings: existing?.settings ?? { convergenceThreshold: DEFAULT_CONVERGENCE_THRESHOLD }
+        };
+        await writeFile(join(projectRoot, STATE_FILES.project), `${JSON.stringify(config, null, 2)}\n`, "utf8");
+        return config;
+    });
+}

package/dist/core/qa.d.ts

@@ -0,0 +1,6 @@
+import { type HostId } from "./hostAdapter.js";
+export interface QaContext {
+    activeGoal: string | null;
+    planSection: string | null;
+}
+export declare function buildQaChecklist(context?: QaContext, host?: HostId): string;

package/dist/core/qa.js

@@ -0,0 +1,26 @@
+import { adapterFor } from "./hostAdapter.js";
+import { DEFAULT_ACTIVE_GOAL_PLACEHOLDER, DEFAULT_PLAN_PLACEHOLDER } from "./project.js";
+function stripListMarker(line) {
+    return line.replace(/^(?:\d+[.)]\s+|[-*+]\s+(?:\[.\]\s+)?)/, "");
+}
+export function buildQaChecklist(context = { activeGoal: null, planSection: null }, host = "generic") {
+    const lines = ["# QA"];
+    if (context.activeGoal !== null &&
+        context.activeGoal.trim().length > 0 &&
+        !context.activeGoal.startsWith(DEFAULT_ACTIVE_GOAL_PLACEHOLDER)) {
+        lines.push("", "## Active Goal Under Review", "", context.activeGoal);
+    }
+    lines.push("", "## Spec Compliance", "", "- Does the implementation follow `koan/goal.md`?", "- Does the implementation follow `koan/plan.md`?", "- Are scope changes recorded through `koan bright-idea`?", "", "## Philosophy Alignment", "", "- Does the implementation preserve the product philosophy in `koan/philosophy.md` (when it exists)?", "- Did any tradeoff quietly betray the stated core value or non-goals?", "", "## General Quality", "", "- Are targeted tests present?", "- Are destructive operations avoided?", "- Are privacy and local-first assumptions preserved?", "");
+    if (context.planSection !== null && !context.planSection.startsWith(DEFAULT_PLAN_PLACEHOLDER)) {
+        const checks = context.planSection
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .map((line) => `- [ ] ${stripListMarker(line)}`);
+        if (checks.length > 0) {
+            lines.push("## Plan-Derived Checks", "", ...checks, "");
+        }
+    }
+    lines.push("## MCP Host Agent Prompt", "", adapterFor(host).qaPrompt, "");
+    return lines.join("\n");
+}

package/dist/core/questions.d.ts

@@ -0,0 +1,10 @@
+import { type HostId } from "./hostAdapter.js";
+import type { AmbiguityAxis, UserProfile } from "./schemas.js";
+export interface KoanQuestion {
+    axis: AmbiguityAxis;
+    intent: string;
+    userFacingQuestion: string;
+    answerSchema: "free_text";
+    hostAgentInstruction: string;
+}
+export declare function getQuestion(axis: AmbiguityAxis, profile: UserProfile, host?: HostId): KoanQuestion;