@koan-labs/koan 0.2.0 → 0.3.0

package/README.md

@@ -1,5 +1,9 @@
 # Koan
 
+[![npm](https://img.shields.io/npm/v/%40koan-labs%2Fkoan)](https://www.npmjs.com/package/@koan-labs/koan)
+[![CI](https://github.com/project820/koan/actions/workflows/ci.yml/badge.svg)](https://github.com/project820/koan/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
 Koan is a local-first philosophical PRD tool. It helps you clarify why a
 product should exist — before asking humans or AI agents to build it — and
 crystallizes that intent into readable project documents: philosophy, goals,
@@ -35,6 +39,9 @@ or API key is required.
 - `koan hello --reset-profile [--yes]` — delete the global profile (`--yes`
   skips confirmation).
 - `koan status` — show goal, status, and next action without writing.
+- `koan dashboard [--once]` — live read-only view of per-axis clarity, the
+  next question, insights, and warnings; refreshes as project files change
+  (`q` to quit, `--once` or a pipe prints a single frame).
 - `koan status --update <text>` — record a status update.
 - `koan status --archive` — archive the active goal to `koan/archive/<goal-id>/`.
 - `koan answer <axis> <text>` — record an answer for one ambiguity axis.
@@ -71,6 +78,7 @@ From a checkout, `npm run mcp` starts the same server.
 | `koan_synthesize_prd` | Synthesize `koan/prd.md`; hosts may supply vision, core value, problem/anti-problem, and user stories grounded in recorded answers. |
 | `koan_prepare_qa` | Generate `koan/qa.md` with spec-compliance and quality checks; embeds an optional implementation summary and returns the checklist. |
 | `koan_prepare_handoff` | Generate `koan/handoff.md` (summary text optional); returns the document and next action; touchless handoff stays disabled. |
+| `koan_get_dashboard` | Read-only snapshot of session phase, per-axis clarity, next question, insights, and warnings — the same data behind `koan dashboard`. |
 
 All tool results are JSON in the first text content block; inputs are
 zod-validated and failures surface as MCP errors.

package/dist/cli/dashboard.d.ts

@@ -0,0 +1,15 @@
+import { type DashboardSnapshot } from "../core/dashboard.js";
+export declare function displayWidth(text: string): number;
+export declare function truncateToWidth(text: string, maxWidth: number): string;
+export interface RenderOptions {
+    width: number;
+    color: boolean;
+    live: boolean;
+}
+export declare function renderDashboard(snapshot: DashboardSnapshot, options: RenderOptions): string;
+export interface RunDashboardInput {
+    cwd: string;
+    homeDir: string;
+    once?: boolean;
+}
+export declare function runDashboard(input: RunDashboardInput): Promise<number>;

package/dist/cli/dashboard.js

@@ -0,0 +1,183 @@
+import { watch } from "node:fs";
+import { basename, join } from "node:path";
+import { KOAN_DIR, KOAN_STATE_DIR } from "../core/constants.js";
+import { collectDashboardSnapshot } from "../core/dashboard.js";
+import { findProjectRoot } from "../core/project.js";
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const BAR_CELLS = 10;
+const LABELS = {
+    en: {
+        next: "Next",
+        goal: "Goal",
+        status: "Status",
+        insights: "Insights",
+        threshold: "threshold",
+        unresolved: "unresolved",
+        noSession: "no session — run koan hello",
+        converged: "converged — ready to crystallize and archive",
+        quit: "q quit",
+        live: "live",
+        last: "last"
+    },
+    ko: {
+        next: "다음 질문",
+        goal: "목표",
+        status: "상태",
+        insights: "인사이트",
+        threshold: "임계",
+        unresolved: "축 미해결",
+        noSession: "세션 없음 — koan hello를 실행하세요",
+        converged: "수렴 완료 — crystallize 후 archive 가능",
+        quit: "q 종료",
+        live: "실시간",
+        last: "최근"
+    }
+};
+// CJK codepoints occupy two terminal columns; everything else is treated as
+// one. Close enough for truncation — exact wcwidth is not worth a dependency.
+const WIDE_CHAR = new RegExp("[\\u1100-\\u115F\\u2E80-\\uA4CF\\uAC00-\\uD7A3\\uF900-\\uFAFF\\uFE30-\\uFE4F\\uFF00-\\uFF60\\uFFE0-\\uFFE6]");
+function charWidth(char) {
+    return WIDE_CHAR.test(char) ? 2 : 1;
+}
+export function displayWidth(text) {
+    let width = 0;
+    for (const char of text)
+        width += charWidth(char);
+    return width;
+}
+export function truncateToWidth(text, maxWidth) {
+    if (displayWidth(text) <= maxWidth)
+        return text;
+    let width = 0;
+    let out = "";
+    for (const char of text) {
+        const next = width + charWidth(char);
+        if (next > maxWidth - 1)
+            break;
+        out += char;
+        width = next;
+    }
+    return `${out}…`;
+}
+export function renderDashboard(snapshot, options) {
+    const width = Math.max(40, options.width);
+    const paint = (text, code) => (options.color ? `${code}${text}${RESET}` : text);
+    const labels = LABELS[snapshot.profileLanguage === "ko" ? "ko" : "en"];
+    const lines = [];
+    const title = `Koan — ${basename(snapshot.projectRoot)}`;
+    const session = snapshot.goalId === null ? labels.noSession : `goal ${snapshot.goalId} · ${snapshot.phase}`;
+    const gap = width - displayWidth(title) - displayWidth(session);
+    lines.push(gap >= 2
+        ? `${paint(title, BOLD)}${" ".repeat(gap)}${paint(session, DIM)}`
+        : truncateToWidth(`${title} · ${session}`, width));
+    lines.push("─".repeat(width));
+    const axisColumn = Math.max(...snapshot.axes.map((entry) => entry.axis.length));
+    for (const entry of snapshot.axes) {
+        const filled = Math.round(entry.clarity * BAR_CELLS);
+        const bar = "█".repeat(filled) + "░".repeat(BAR_CELLS - filled);
+        const barColor = entry.clarity >= snapshot.threshold ? GREEN : entry.clarity > 0 ? YELLOW : DIM;
+        const marker = snapshot.nextQuestion?.axis === entry.axis ? "  ← next" : "";
+        lines.push(`${entry.axis.padEnd(axisColumn)} ${paint(bar, barColor)} ${entry.clarity.toFixed(1)}${paint(marker, DIM)}`);
+    }
+    lines.push(paint(snapshot.converged
+        ? labels.converged
+        : `${labels.threshold} ${snapshot.threshold} · ${snapshot.unresolvedCount} ${labels.unresolved}`, DIM));
+    lines.push("─".repeat(width));
+    if (snapshot.nextQuestion) {
+        lines.push(truncateToWidth(`${labels.next}: ${snapshot.nextQuestion.userFacingQuestion}`, width));
+    }
+    if (snapshot.activeGoal) {
+        lines.push(truncateToWidth(`${labels.goal}: ${snapshot.activeGoal.split("\n")[0]}`, width));
+    }
+    if (snapshot.latestStatus) {
+        lines.push(truncateToWidth(`${labels.status}: ${snapshot.latestStatus.split("\n")[0]}`, width));
+    }
+    if (snapshot.insights.length > 0) {
+        const recent = snapshot.insights.slice(-2).join(" · ");
+        lines.push(truncateToWidth(`${labels.insights}(${snapshot.insights.length}): ${recent}`, width));
+    }
+    for (const warning of snapshot.staleWarnings) {
+        lines.push(paint(truncateToWidth(`⚠ ${warning}`, width), YELLOW));
+    }
+    lines.push(truncateToWidth(`→ ${snapshot.nextAction}`, width));
+    const footerParts = [];
+    if (options.live)
+        footerParts.push(labels.quit, labels.live);
+    if (snapshot.lastCommand) {
+        footerParts.push(`${labels.last}: ${snapshot.lastCommand.command} (${snapshot.lastCommand.at})`);
+    }
+    if (footerParts.length > 0) {
+        lines.push(paint(truncateToWidth(footerParts.join(" · "), width), DIM));
+    }
+    return lines.join("\n");
+}
+export async function runDashboard(input) {
+    const live = input.once !== true && process.stdout.isTTY === true && process.stdin.isTTY === true;
+    const color = process.stdout.isTTY === true && !process.env.NO_COLOR;
+    const render = async () => {
+        const snapshot = await collectDashboardSnapshot({ cwd: input.cwd, homeDir: input.homeDir });
+        return renderDashboard(snapshot, { width: process.stdout.columns ?? 80, color, live });
+    };
+    if (!live) {
+        console.log(await render());
+        return 0;
+    }
+    const projectRoot = await findProjectRoot(input.cwd);
+    const watchers = [];
+    let redrawTimer = null;
+    let pollTimer = null;
+    let finished = false;
+    const draw = async () => {
+        const frame = await render().catch((error) => error instanceof Error ? error.message : String(error));
+        if (!finished)
+            process.stdout.write(`\x1b[H\x1b[2J${frame}\n`);
+    };
+    const scheduleDraw = () => {
+        if (redrawTimer)
+            clearTimeout(redrawTimer);
+        redrawTimer = setTimeout(() => void draw(), 150);
+    };
+    return new Promise((resolve) => {
+        const cleanup = () => {
+            if (finished)
+                return;
+            finished = true;
+            if (redrawTimer)
+                clearTimeout(redrawTimer);
+            if (pollTimer)
+                clearInterval(pollTimer);
+            for (const watcher of watchers)
+                watcher.close();
+            process.stdin.setRawMode?.(false);
+            process.stdin.pause();
+            process.stdout.removeListener("resize", scheduleDraw);
+            process.stdout.write("\x1b[?1049l\x1b[?25h");
+            resolve(0);
+        };
+        process.stdout.write("\x1b[?1049h\x1b[?25l");
+        for (const dir of [join(projectRoot, KOAN_STATE_DIR), join(projectRoot, KOAN_DIR)]) {
+            try {
+                watchers.push(watch(dir, scheduleDraw));
+            }
+            catch {
+                // Directory may not exist yet (bare project); the poll timer covers it.
+            }
+        }
+        pollTimer = setInterval(() => void draw(), 5000);
+        process.stdout.on("resize", scheduleDraw);
+        process.stdin.setRawMode?.(true);
+        process.stdin.resume();
+        process.stdin.on("data", (chunk) => {
+            const key = chunk.toString("utf8");
+            if (key === "q" || key === "Q" || key === "\x03")
+                cleanup();
+        });
+        process.once("SIGINT", cleanup);
+        process.once("SIGTERM", cleanup);
+        void draw();
+    });
+}

package/dist/cli/main.js

@@ -4,6 +4,7 @@ import { acceptClarity, recordAnswer } from "../core/answers.js";
 import { archive, brightIdea, handoff, hello, qa, recordInsight, status, updateStatus } from "../core/commands.js";
 import { crystallize } from "../core/crystallize.js";
 import { buildPrd } from "../core/prd.js";
+import { runDashboard } from "./dashboard.js";
 import { defaultProfile, loadProfile, resetProfile, saveProfile } from "../core/profile.js";
 import { getQuestion } from "../core/questions.js";
 import { ANSWERED_CLARITY } from "../core/scoring.js";
@@ -30,6 +31,7 @@ const COMMAND_CONTRACTS = {
     enough: { flags: [], positionals: "none" },
     crystallize: { flags: ["--dry-run"], positionals: "none" },
     "bright-idea": { flags: ["--classify"], positionals: "text" },
+    dashboard: { flags: ["--once"], positionals: "none" },
     insight: { flags: [], positionals: "text" },
     prd: { flags: ["--dry-run"], positionals: "none" },
     qa: { flags: [], positionals: "none" },
@@ -57,6 +59,7 @@ function usage() {
         "  crystallize [--dry-run]    write recorded answers into project documents",
         "  bright-idea [--classify <type>] <text>",
         "                             record a new idea without changing the plan",
+        "  dashboard [--once]         live read-only view of clarity, goal, and insights",
         "  insight <text>             append a product realization to philosophy.md",
         "  prd [--dry-run]            synthesize koan/prd.md from recorded answers",
         "  qa                         create or refresh QA checklist",
@@ -334,6 +337,12 @@ async function main(argv) {
         console.log(`Bright idea recorded (${result.classification}). ${result.recommendation}`);
         return 0;
     }
+    if (command === "dashboard") {
+        const parsed = parseCommandArgs("dashboard", rest);
+        if (parsed === null)
+            return 1;
+        return runDashboard({ cwd, homeDir, once: parsed.flags.includes("--once") });
+    }
     if (command === "insight") {
         const parsed = parseCommandArgs("insight", rest);
         if (parsed === null)

package/dist/core/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const KOAN_VERSION = "0.2.0";
+export declare const KOAN_VERSION = "0.3.0";
 export declare const KOAN_DIR = "koan";
 export declare const KOAN_STATE_DIR = ".koan";
 export declare const CORE_DOCUMENTS: {

package/dist/core/constants.js

@@ -1,4 +1,4 @@
-export const KOAN_VERSION = "0.2.0";
+export const KOAN_VERSION = "0.3.0";
 export const KOAN_DIR = "koan";
 export const KOAN_STATE_DIR = ".koan";
 export const CORE_DOCUMENTS = {

package/dist/core/dashboard.d.ts

@@ -0,0 +1,29 @@
+import { type HostId } from "./hostAdapter.js";
+import { type KoanQuestion } from "./questions.js";
+import { type AmbiguityAxis, type CommandLogEntry, type Language } from "./schemas.js";
+export interface DashboardAxis {
+    axis: AmbiguityAxis;
+    clarity: number;
+}
+export interface DashboardSnapshot {
+    projectRoot: string;
+    goalId: string | null;
+    phase: string | null;
+    axes: DashboardAxis[];
+    threshold: number;
+    converged: boolean;
+    unresolvedCount: number;
+    nextQuestion: KoanQuestion | null;
+    nextAction: string;
+    activeGoal: string | null;
+    latestStatus: string | null;
+    insights: string[];
+    staleWarnings: string[];
+    lastCommand: CommandLogEntry | null;
+    profileLanguage: Language;
+}
+export declare function collectDashboardSnapshot(input: {
+    cwd: string;
+    homeDir: string;
+    host?: HostId;
+}): Promise<DashboardSnapshot>;

package/dist/core/dashboard.js

@@ -0,0 +1,61 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadCommandLog } from "./commandLog.js";
+import { status } from "./commands.js";
+import { CORE_DOCUMENTS, LAZY_DOCUMENTS } from "./constants.js";
+import { readManagedSection } from "./documents.js";
+import { parseInsights } from "./prd.js";
+import { defaultProfile, loadProfile } from "./profile.js";
+import { DEFAULT_ACTIVE_GOAL_PLACEHOLDER, DEFAULT_STATUS_PLACEHOLDER, findProjectRoot, loadProjectConfig } from "./project.js";
+import { getQuestion } from "./questions.js";
+import { DEFAULT_CONVERGENCE_THRESHOLD } from "./schemas.js";
+import { AXIS_PRIORITY, isConverged, loadLedger, selectMostUnclearAxis, unresolvedAxes } from "./scoring.js";
+import { loadSessionState } from "./session.js";
+async function readRegion(path, region, placeholder) {
+    const text = await readFile(path, "utf8").catch(() => null);
+    if (text === null)
+        return null;
+    const section = readManagedSection(text, region);
+    if (section === null || section.length === 0 || section.startsWith(placeholder))
+        return null;
+    return section;
+}
+export async function collectDashboardSnapshot(input) {
+    const projectRoot = await findProjectRoot(input.cwd);
+    const state = await loadSessionState(projectRoot);
+    const profile = (await loadProfile(input.homeDir)) ?? defaultProfile();
+    const threshold = (await loadProjectConfig(projectRoot))?.settings.convergenceThreshold ?? DEFAULT_CONVERGENCE_THRESHOLD;
+    const hasGoal = state !== null && state.activeGoalId !== null && state.phase !== "archived";
+    const stored = await loadLedger(projectRoot);
+    const ledger = hasGoal && stored && stored.goalId === state.activeGoalId ? stored : null;
+    const clarityByAxis = new Map(ledger?.axes.map((entry) => [entry.axis, entry.clarity]) ?? []);
+    const axes = AXIS_PRIORITY.map((axis) => ({
+        axis,
+        clarity: clarityByAxis.get(axis) ?? 0
+    }));
+    const converged = hasGoal && (state.phase === "ready" || (ledger !== null && isConverged(ledger, threshold)));
+    const nextQuestion = hasGoal && !converged && ledger !== null
+        ? getQuestion(selectMostUnclearAxis(ledger), profile, input.host ?? "generic")
+        : null;
+    const unresolvedCount = ledger !== null && !converged ? unresolvedAxes(ledger, threshold).length : 0;
+    const { nextAction, staleWarnings } = await status({ cwd: projectRoot });
+    const philosophyText = await readFile(join(projectRoot, LAZY_DOCUMENTS.philosophy), "utf8").catch(() => "");
+    const log = await loadCommandLog(projectRoot);
+    return {
+        projectRoot,
+        goalId: hasGoal ? state.activeGoalId : null,
+        phase: state?.phase ?? null,
+        axes,
+        threshold,
+        converged,
+        unresolvedCount,
+        nextQuestion,
+        nextAction,
+        activeGoal: await readRegion(join(projectRoot, CORE_DOCUMENTS.goal), "active-goal", DEFAULT_ACTIVE_GOAL_PLACEHOLDER),
+        latestStatus: await readRegion(join(projectRoot, CORE_DOCUMENTS.status), "current-status", DEFAULT_STATUS_PLACEHOLDER),
+        insights: parseInsights(philosophyText),
+        staleWarnings,
+        lastCommand: log.entries.at(-1) ?? null,
+        profileLanguage: profile.language
+    };
+}

package/dist/index.d.ts

@@ -16,3 +16,4 @@ export * from "./core/crystallize.js";
 export * from "./core/commands.js";
 export * from "./core/hostAdapter.js";
 export * from "./core/prd.js";
+export * from "./core/dashboard.js";

package/dist/index.js

@@ -16,3 +16,4 @@ export * from "./core/crystallize.js";
 export * from "./core/commands.js";
 export * from "./core/hostAdapter.js";
 export * from "./core/prd.js";
+export * from "./core/dashboard.js";

package/dist/mcp/server.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-export declare const toolNames: readonly ["koan_get_profile", "koan_update_profile", "koan_inspect_project", "koan_start_session", "koan_get_next_question", "koan_record_answer", "koan_crystallize_documents", "koan_get_status", "koan_update_status", "koan_record_bright_idea", "koan_record_insight", "koan_synthesize_prd", "koan_prepare_qa", "koan_prepare_handoff"];
+export declare const toolNames: readonly ["koan_get_profile", "koan_update_profile", "koan_inspect_project", "koan_start_session", "koan_get_next_question", "koan_record_answer", "koan_crystallize_documents", "koan_get_status", "koan_update_status", "koan_record_bright_idea", "koan_record_insight", "koan_synthesize_prd", "koan_prepare_qa", "koan_prepare_handoff", "koan_get_dashboard"];
 export declare function createServer(): Server;
 export declare function runServer(): Promise<void>;

package/dist/mcp/server.js

@@ -11,6 +11,7 @@ import { recordAnswer } from "../core/answers.js";
 import { brightIdea, handoff, hello, qa, recordInsight, status, updateStatus } from "../core/commands.js";
 import { CORE_DOCUMENTS, KOAN_VERSION, LAZY_DOCUMENTS, STATE_FILES } from "../core/constants.js";
 import { crystallize } from "../core/crystallize.js";
+import { collectDashboardSnapshot } from "../core/dashboard.js";
 import { defaultKoanGitignore } from "../core/gitPolicy.js";
 import { adapterFor, detectHost } from "../core/hostAdapter.js";
 import { buildPrd } from "../core/prd.js";
@@ -36,7 +37,8 @@ export const toolNames = [
     "koan_record_insight",
     "koan_synthesize_prd",
     "koan_prepare_qa",
-    "koan_prepare_handoff"
+    "koan_prepare_handoff",
+    "koan_get_dashboard"
 ];
 const BrightIdeaClassificationSchema = z.enum(["clarify", "change-goal", "later-follow-up", "reject"]);
 const profileFieldProperties = {
@@ -464,6 +466,22 @@ const tools = {
             return { prepared: true, path: LAZY_DOCUMENTS.qa, checklist: result.checklist };
         }
     },
+    koan_get_dashboard: {
+        description: "Read-only snapshot of session phase, per-axis clarity in question-priority order, next question, document summaries, insights, and warnings. Never writes project state.",
+        inputSchema: {
+            type: "object",
+            properties: { projectRoot: { type: "string" }, homeDir: { type: "string" } },
+            required: ["projectRoot", "homeDir"]
+        },
+        handler: async (args, context) => {
+            const parsed = z.object({ projectRoot: z.string(), homeDir: z.string() }).parse(args);
+            return collectDashboardSnapshot({
+                cwd: parsed.projectRoot,
+                homeDir: parsed.homeDir,
+                host: context.host
+            });
+        }
+    },
     koan_prepare_handoff: {
         description: "Write the document-based handoff at koan/handoff.md from the optional session summary and return the document with the next action.",
         inputSchema: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koan-labs/koan",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local-first philosophical PRD tool that crystallizes vague intent into product requirements, QA criteria, and AI-agent-ready handoff documents.",
   "license": "MIT",
   "repository": {