onto-mcp 0.4.11 → 0.4.13

package/dist/tui/index.js

@@ -0,0 +1,108 @@
+/**
+ * `onto watch [session]` entry. Resolves a session (by id substring, by path, or
+ * most-recent when omitted) and mounts the Ink app. v1 is observe-only; the
+ * SessionSelector screen (no-arg browsing) and the Log screen arrive in Stage C.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createElement } from "react";
+import { render } from "ink";
+import { WatchApp } from "./app.js";
+import { discoverSessions } from "./data/session-discovery.js";
+function parseArgs(argv) {
+    let session;
+    let projectRoot = process.cwd();
+    let ontoHome;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--project-root") {
+            const value = argv[++index];
+            if (value)
+                projectRoot = path.resolve(value);
+        }
+        else if (arg === "--onto-home") {
+            const value = argv[++index];
+            if (value)
+                ontoHome = path.resolve(value);
+        }
+        else if (!arg.startsWith("-") && session === undefined) {
+            session = arg;
+        }
+    }
+    return {
+        ...(session !== undefined ? { session } : {}),
+        projectRoot,
+        ...(ontoHome !== undefined ? { ontoHome } : {}),
+    };
+}
+/** Derives a SessionRef from an explicit session-root path, when it resolves to
+ * a `.onto/{review,reconstruct}/<id>` directory. */
+function refFromPath(sessionPath) {
+    const resolved = path.resolve(sessionPath);
+    if (!fs.existsSync(resolved))
+        return null;
+    const parts = resolved.split(path.sep);
+    const idx = parts.lastIndexOf(".onto");
+    const pipeline = parts[idx + 1];
+    if (pipeline !== "review" && pipeline !== "reconstruct")
+        return null;
+    const stat = (() => {
+        try {
+            return fs.statSync(resolved).mtimeMs;
+        }
+        catch {
+            return 0;
+        }
+    })();
+    return {
+        pipeline,
+        sessionId: parts[parts.length - 1] ?? resolved,
+        sessionRoot: resolved,
+        modifiedMs: stat,
+    };
+}
+async function resolveWatch(args) {
+    const sessions = await discoverSessions(args.projectRoot);
+    if (!args.session) {
+        // No arg → open the SessionSelector (error only when there is nothing to show).
+        if (sessions.length === 0) {
+            return { sessions, error: `no review/reconstruct sessions under ${args.projectRoot}/.onto` };
+        }
+        return { sessions };
+    }
+    const byPath = refFromPath(args.session);
+    if (byPath) {
+        return { sessions: sessions.length ? sessions : [byPath], initialSession: byPath };
+    }
+    const matches = sessions.filter((s) => s.sessionId.includes(args.session));
+    if (matches.length === 0) {
+        return { sessions, error: `no session matching "${args.session}"` };
+    }
+    if (matches.length > 1) {
+        // Ambiguous token — don't silently attach to the newest; ask for a specific id.
+        return {
+            sessions,
+            error: `"${args.session}" matches ${matches.length} sessions: ` +
+                `${matches.map((s) => s.sessionId).join(", ")}. Use a more specific id.`,
+        };
+    }
+    return { sessions, initialSession: matches[0] };
+}
+export async function runWatch(argv) {
+    const args = parseArgs(argv);
+    const { sessions, initialSession, error } = await resolveWatch(args);
+    if (error) {
+        process.stderr.write(`[onto watch] ${error}\n`);
+        return 1;
+    }
+    const instance = render(createElement(WatchApp, {
+        sessions,
+        ...(initialSession ? { initialSession } : {}),
+        // projectRoot is for session discovery only; the read APIs resolve the
+        // onto-mcp install root themselves (or from an explicit --onto-home), so
+        // running `onto watch` from a non-install project does not break.
+        ...(args.ontoHome ? { ontoHome: args.ontoHome } : {}),
+    }));
+    await instance.waitUntilExit();
+    return 0;
+}

package/dist/tui/screens/log.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Log screen — a tail of a session's `runtime-events.ndjson` (fed by the
+ * event-follower in the app). Pure presentation: shows the most recent events
+ * with timestamp · source · stream · message. Read-only.
+ */
+import { Box, Text } from "ink";
+function clockTime(timestamp) {
+    // Render only HH:MM:SS from an ISO timestamp without constructing a Date
+    // (avoids locale/clock surprises and keeps it test-stable).
+    const match = /T(\d{2}:\d{2}:\d{2})/.exec(timestamp);
+    return match ? match[1] : timestamp.slice(0, 8);
+}
+const STREAM_COLOR = {
+    model_call: "magenta",
+    status: undefined,
+    chunk: "gray",
+};
+export function LogScreen({ sessionId, events, maxLines = 18, }) {
+    const tail = events.slice(-maxLines);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, children: `onto watch · ${sessionId} · log` }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: tail.length === 0 ? (_jsx(Text, { dimColor: true, children: "no events yet" })) : (tail.map((event, index) => {
+                    const sourceColor = STREAM_COLOR[event.stream];
+                    return (_jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: `${clockTime(event.timestamp)}  ` }), _jsx(Text, { ...(sourceColor ? { color: sourceColor } : {}), children: `${(event.source.label ?? event.source.kind).padEnd(16)} ` }), _jsx(Text, { children: event.message })] }, index));
+                })) }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: "[tab] tree  [q]uit" }) })] }));
+}

package/dist/tui/screens/node-detail.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Drill-down detail pane for the node selected in the WorkflowTree HUD — shows
+ * the node's status/owner/attempts/failure/output and a tail of its output (the
+ * running log / authored artifact). Pure presentation.
+ */
+import { Box, Text } from "ink";
+export function NodeDetail({ node, tail }) {
+    const meta = [`status ${node.status}`];
+    if (node.owner)
+        meta.push(`owner ${node.owner}`);
+    if (node.attempts && node.attempts > 1)
+        meta.push(`try${node.attempts}`);
+    if (node.signalAgeSec != null)
+        meta.push(`${node.signalAgeSec}s`);
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [_jsx(Text, { bold: true, children: node.label }), _jsx(Text, { dimColor: true, children: meta.join(" · ") }), node.failureMessage ? _jsx(Text, { color: "red", children: node.failureMessage }) : null, node.outputPath ? _jsx(Text, { dimColor: true, children: node.outputPath }) : null, tail.length > 0 ? (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "\u2500\u2500 output (tail) \u2500\u2500" }), tail.map((line, index) => (_jsx(Text, { children: line }, index)))] })) : null] }));
+}

package/dist/tui/screens/session-selector.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * SessionSelector — the `onto watch` entry screen when no session is given (or
+ * `s` from a session view). Lists review/reconstruct sessions (most recent
+ * first) with a cursor. Pure presentation: selection state is owned by the app.
+ */
+import { Box, Text } from "ink";
+function relativeAge(modifiedMs, nowMs) {
+    if (!modifiedMs)
+        return "";
+    const sec = Math.max(0, Math.round((nowMs - modifiedMs) / 1000));
+    if (sec < 60)
+        return `${sec}s ago`;
+    if (sec < 3600)
+        return `${Math.round(sec / 60)}m ago`;
+    if (sec < 86400)
+        return `${Math.round(sec / 3600)}h ago`;
+    return `${Math.round(sec / 86400)}d ago`;
+}
+export function SessionSelector({ sessions, selectedIndex, nowMs, }) {
+    const now = nowMs ?? Date.now();
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, children: "onto watch \u00B7 sessions" }), sessions.length === 0 ? (_jsx(Text, { dimColor: true, children: "no review/reconstruct sessions found" })) : (_jsx(Box, { flexDirection: "column", marginTop: 1, children: sessions.map((session, index) => {
+                    const active = index === selectedIndex;
+                    return (_jsxs(Box, { children: [_jsx(Text, { ...(active ? { color: "cyan" } : {}), children: `${active ? "›" : " "} ${session.pipeline.padEnd(11)} ` }), _jsx(Text, { bold: active, children: session.sessionId }), _jsx(Text, { dimColor: true, children: `  ${relativeAge(session.modifiedMs, now)}` })] }, `${session.pipeline}:${session.sessionRoot}`));
+                }) })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: "[\u2191\u2193] select  [enter] watch  [q]uit" }) })] }));
+}

package/dist/tui/screens/workflow-tree.js

@@ -0,0 +1,90 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * WorkflowTree HUD — the primary `onto watch` screen. Pure presentation: renders
+ * a {@link TreeViewModel} (header · narrator · phase-grouped unit tree · footer)
+ * for either pipeline. The HUD never branches on pipeline; the adapters already
+ * normalized the difference into the view model.
+ */
+import { Box, Text } from "ink";
+const NODE_ICON = {
+    completed: "✓",
+    running: "◐",
+    pending: "○",
+    failed: "✗",
+    halted: "◑",
+    skipped: "⊘",
+};
+const NODE_COLOR = {
+    completed: "green",
+    running: "cyan",
+    pending: "gray",
+    failed: "red",
+    halted: "yellow",
+    skipped: "gray",
+};
+const STATUS_BADGE = {
+    running: { label: "◐ running", color: "cyan" },
+    completed: { label: "✓ completed", color: "green" },
+    halted: { label: "◑ halted", color: "yellow" },
+    failed: { label: "✗ failed", color: "red" },
+};
+const SEVERITY_ORDER = ["blocker", "high", "medium", "low", "info"];
+const SEVERITY_ABBR = {
+    blocker: "blk",
+    high: "high",
+    medium: "med",
+    low: "low",
+    info: "info",
+};
+function NodeBadge({ node }) {
+    const parts = [];
+    if (node.owner)
+        parts.push(node.owner);
+    if (node.signalAgeSec != null)
+        parts.push(`${node.signalAgeSec}s`);
+    if (node.attempts && node.attempts > 1)
+        parts.push(`try${node.attempts}`);
+    if (node.failureMessage)
+        parts.push(node.failureMessage);
+    if (parts.length === 0)
+        return null;
+    return _jsx(Text, { dimColor: true, children: `  ${parts.join(" · ")}` });
+}
+/**
+ * Surfaces the run-control availability the status projection carries (observe-
+ * only: it reports what the operator can do via the MCP/CLI, the HUD never acts).
+ * Most relevant for halted/stale sessions where continue is the next step.
+ */
+function RunControlRow({ control }) {
+    const available = [];
+    if (control.continuable)
+        available.push("continue");
+    if (control.advanceable)
+        available.push("advance");
+    if (control.cancellable)
+        available.push("cancel");
+    if (available.length === 0)
+        return null;
+    return _jsx(Text, { dimColor: true, children: `Controls  ${available.join(" · ")} available` });
+}
+function Footer({ vm }) {
+    const { findings, counts } = vm.summary;
+    if (findings) {
+        return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { children: ["Findings  ", SEVERITY_ORDER.map((s) => `⬤${findings[s]} ${SEVERITY_ABBR[s]}`).join("  ")] }), findings.material.map((title, index) => (_jsx(Text, { dimColor: true, children: `  › ${title}` }, index)))] }));
+    }
+    if (counts) {
+        const pairs = Object.entries(counts)
+            .filter(([, value]) => value != null)
+            .map(([key, value]) => `${key} ${value}`);
+        return (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { children: ["Coverage  ", pairs.join(" · ")] }) }));
+    }
+    return _jsx(Box, { marginTop: 1 });
+}
+export function WorkflowTree({ vm, selectedNodeId }) {
+    const badge = STATUS_BADGE[vm.status];
+    const phasesDone = vm.phases.filter((p) => p.state === "completed").length;
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, children: "onto watch" }), _jsx(Text, { children: ` · ${vm.pipeline} · ${vm.sessionId} ` }), _jsx(Text, { color: badge.color, children: badge.label })] }), vm.headline ? _jsx(Text, { dimColor: true, children: vm.headline }) : null, _jsx(Text, { children: `▸ ${vm.narrator}` }), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { children: `Pipeline  ${phasesDone}/${vm.phases.length} phases` }), vm.liveness.secondsSinceSignal != null ? (_jsx(Text, { dimColor: true, children: `  · ${vm.liveness.secondsSinceSignal}s since signal` })) : null] }), _jsx(RunControlRow, { control: vm.runControl }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: vm.phases.map((phase) => (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: NODE_COLOR[phase.state], children: `${NODE_ICON[phase.state]} ${phase.label}` }), phase.nodes.map((node) => {
+                            const selected = node.id === selectedNodeId;
+                            return (_jsxs(Box, { children: [_jsx(Text, { color: NODE_COLOR[node.status], children: `${selected ? "›" : " "} ${NODE_ICON[node.status]} ` }), _jsx(Text, { bold: selected, children: node.label }), _jsx(NodeBadge, { node: node })] }, node.id));
+                        })] }, phase.id))) }), _jsx(Footer, { vm: vm }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: "[q]uit  [r]efresh" }) })] }));
+}

package/dist/tui/view-model/reconstruct-adapter.js

@@ -0,0 +1,162 @@
+/**
+ * v1 grouping: a single "pipeline" phase holds every reconstruct stage as a
+ * node, in canonical stage order (the projection already lists stages in
+ * `RECONSTRUCT_STAGE_IDS` order). This keeps the adapter simple and mirrors the
+ * design's "stages are the nodes" framing; finer maturation-stage grouping can
+ * be layered on later without changing the node mapping.
+ */
+const PIPELINE_PHASE_ID = "pipeline";
+const PIPELINE_PHASE_LABEL = "reconstruct pipeline";
+/**
+ * Map a reconstruct stage `state` to the shared {@link NodeState}. Reconstruct
+ * stage states are a strict subset (`pending | completed | skipped | halted`) —
+ * there is no per-stage `running` signal in the projection, so the in-flight
+ * stage is surfaced at the phase/headline level (see {@link derivePhaseState}),
+ * not on individual nodes.
+ */
+function stageStateToNodeState(state) {
+    switch (state) {
+        case "completed":
+            return "completed";
+        case "skipped":
+            return "skipped";
+        case "halted":
+            return "halted";
+        case "pending":
+            return "pending";
+    }
+}
+/** Human-ize a snake_case stageId for display, e.g. `ontology_seed` → `ontology seed`. */
+function humanizeStageId(stageId) {
+    return stageId.replace(/_/g, " ");
+}
+function stageToNode(stage, hiddenArtifactRef) {
+    const outputPath = stage.artifactRefs.find((ref) => ref !== hiddenArtifactRef) ?? null;
+    return {
+        id: stage.stageId,
+        label: humanizeStageId(stage.stageId),
+        status: stageStateToNodeState(stage.state),
+        // reconstruct nodes badge by stageId (kind) + carry the owner column.
+        kind: stage.stageId,
+        // owner is optional under exactOptionalPropertyTypes: omit when absent.
+        ...(stage.owner ? { owner: stage.owner } : {}),
+        // No per-stage live signal in the projection.
+        signalAgeSec: null,
+        // `reason` is the stage's terminal explanation (skip/halt rationale).
+        failureMessage: stage.reason,
+        // First authored artifact ref is the drill-down target.
+        outputPath,
+    };
+}
+/**
+ * Phase state for the single pipeline phase. A halted stage halts the phase;
+ * otherwise a completed run completes the phase; otherwise it is running (the
+ * pipeline is mid-flight regardless of which individual stages are still
+ * pending).
+ */
+function derivePhaseState(stages, workflowStatus) {
+    if (stages.some((stage) => stage.state === "halted"))
+        return "halted";
+    if (workflowStatus === "completed")
+        return "completed";
+    return "running";
+}
+/**
+ * Map record_stage + stage states to the shared {@link WorkflowStatus}.
+ * reconstruct has no `failed` record_stage and no per-stage `running`; we treat
+ * a halted stage as a halt (terminal-ish, surfaced for the operator) and a
+ * completed record as completed. Everything else is an in-flight run.
+ */
+function deriveWorkflowStatus(status) {
+    if (status.status === "failed")
+        return "failed";
+    if (status.status === "completed")
+        return "completed";
+    // A graceful terminal (design §16.7) is terminal but not completed: surface it as `halted` so
+    // the watch loop stops polling and the operator sees an honest stop, not a "session completed".
+    if (status.status === "blocked" || status.status === "limited")
+        return "halted";
+    if (status.progress.stages.some((stage) => stage.state === "halted")) {
+        return "halted";
+    }
+    return "running";
+}
+/** Flatten countSummary + answerabilitySummary into the footer label→value map. */
+function deriveCounts(progress) {
+    const c = progress.countSummary;
+    const a = progress.answerabilitySummary;
+    return {
+        observations: c.selectedObservationCount ?? c.sourceObservationCount,
+        claims: c.semanticClaimCount,
+        confirmed: c.confirmedClaimCount,
+        deferredClaims: c.deferredClaimCount,
+        CQ: c.competencyQuestionCount,
+        passRate: c.passRate,
+        // Answerability (maturation) summary — null until metrics are computed.
+        declared: a ? a.declaredQuestionCount : null,
+        supported: a ? a.supportedQuestionCount : null,
+        deferred: a ? a.deferredQuestionCount : null,
+        unsupported: a ? a.unsupportedQuestionCount : null,
+    };
+}
+/** One-line narrator from the current stage + the most informative counts. */
+function deriveNarrator(progress, workflowStatus) {
+    const stage = humanizeStageId(progress.currentStageId);
+    const a = progress.answerabilitySummary;
+    const lead = workflowStatus === "completed"
+        ? "reconstruct complete"
+        : workflowStatus === "failed"
+            ? `reconstruct failed at ${stage}`
+            : workflowStatus === "halted"
+                ? `halted at ${stage}`
+                : `reconstructing — ${stage}`;
+    if (a) {
+        return `${lead} · CQ ${a.declaredQuestionCount} · supported ${a.supportedQuestionCount} · deferred ${a.deferredQuestionCount} · unsupported ${a.unsupportedQuestionCount}`;
+    }
+    const claims = progress.countSummary.semanticClaimCount;
+    return claims === null ? lead : `${lead} · ${claims} claims`;
+}
+/**
+ * Pure projection: {@link ReconstructSessionStatus} → {@link TreeViewModel}.
+ *
+ * `sessionRoot` is threaded explicitly (the caller already knows it) so the view
+ * model header is independent of how the status was fetched.
+ */
+export function reconstructStatusToTreeViewModel(status, sessionRoot) {
+    const { progress } = status;
+    const workflowStatus = deriveWorkflowStatus(status);
+    const hiddenArtifactRef = status.status === "failed"
+        ? status.failure.failure_artifact_ref
+        : null;
+    const nodes = progress.stages.map((stage) => stageToNode(stage, hiddenArtifactRef));
+    const phase = {
+        id: PIPELINE_PHASE_ID,
+        label: PIPELINE_PHASE_LABEL,
+        state: derivePhaseState(progress.stages, workflowStatus),
+        nodes,
+    };
+    return {
+        pipeline: "reconstruct",
+        sessionId: status.sessionId,
+        sessionRoot,
+        status: workflowStatus,
+        narrator: deriveNarrator(progress, workflowStatus),
+        liveness: {
+            state: progress.liveness.state,
+            // The projection carries no per-signal timestamp for reconstruct.
+            secondsSinceSignal: null,
+            pollMs: progress.liveness.recommendedPollIntervalMs,
+        },
+        phases: [phase],
+        summary: { counts: deriveCounts(progress) },
+        // reconstruct status carries no rich run_control (unlike review): be
+        // conservative — only a still-running session is cancellable; continue /
+        // advance are display-only false until a control path exists (design §4,
+        // later stage E).
+        runControl: {
+            cancellable: workflowStatus === "running",
+            continuable: false,
+            advanceable: false,
+        },
+    };
+}