@northtek/overstory 0.1.0

package/dist/serve/server.d.ts

@@ -0,0 +1,9 @@
+import { Server } from 'node:http';
+import type { ChatProvider } from '../llm/provider.js';
+export interface ServeOptions {
+    provider: ChatProvider | null;
+    port?: number;
+    onReady?: (url: string) => void;
+}
+export declare const createOverstoryHttpServer: (root: string, opts: ServeOptions) => Server;
+export declare const serve: (root: string, opts: ServeOptions) => Promise<Server>;

package/dist/serve/server.js

@@ -0,0 +1,180 @@
+import { createServer } from 'node:http';
+import { stat } from 'node:fs/promises';
+import { z } from 'zod';
+import { loadCorpus } from '../core/corpus.js';
+import { verifyTree } from '../core/gate.js';
+import { loadTree, treePath } from '../core/store.js';
+import { ask, buildClaimIndex } from '../query/ask.js';
+import { notarizeClaims } from '../query/notarize.js';
+import { buildSiteData } from '../site/data.js';
+import { appHtml } from './app.js';
+import { ThreadStore } from './threads.js';
+const askBodySchema = z.object({
+    question: z.string().min(2).max(2000),
+    threadId: z.string().optional(),
+});
+const verifyBodySchema = z.object({
+    claims: z
+        .array(z.object({
+        text: z.string(),
+        citations: z.array(z.object({ file: z.string(), startLine: z.number().int().min(1), endLine: z.number().int().min(1) })),
+    }))
+        .min(1)
+        .max(30),
+});
+const sendJson = (res, status, value) => {
+    const body = JSON.stringify(value);
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(body);
+};
+const readBody = async (req) => {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > 1_000_000)
+            throw new Error('body too large');
+        chunks.push(chunk);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+};
+/** Suggested questions derived from what the tree actually knows. */
+const suggestionsFor = (tree) => {
+    const dirs = Object.values(tree.nodes)
+        .filter((n) => n.kind === 'dir' && n.claims.length > 0)
+        .slice(0, 2)
+        .map((n) => `What lives in ${n.path}/ and how does it fit together?`);
+    return [
+        `What does ${tree.name} do, in one paragraph?`,
+        ...dirs,
+        'Where would a new contributor start reading?',
+    ].slice(0, 4);
+};
+export const createOverstoryHttpServer = (root, opts) => {
+    const threads = new ThreadStore(root);
+    let cached = null;
+    const load = async () => {
+        let mtimeMs = 0;
+        try {
+            mtimeMs = (await stat(treePath(root))).mtimeMs;
+        }
+        catch {
+            return null;
+        }
+        const now = Date.now();
+        if (cached && cached.treeMtimeMs === mtimeMs && now - cached.corpusAt < 10_000)
+            return cached;
+        const tree = await loadTree(treePath(root));
+        if (!tree)
+            return null;
+        const corpus = await loadCorpus(root, tree.corpusOptions ?? {});
+        const scanCorpus = tree.corpusOptions?.include
+            ? await loadCorpus(root, { maxFiles: tree.corpusOptions.maxFiles })
+            : corpus;
+        const verification = verifyTree(tree, corpus);
+        cached = { tree, corpus, scanCorpus, verification, treeMtimeMs: mtimeMs, corpusAt: now };
+        return cached;
+    };
+    const server = createServer(async (req, res) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const route = `${req.method} ${url.pathname}`;
+        try {
+            if (route === 'GET /') {
+                res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+                res.end(appHtml());
+                return;
+            }
+            if (route === 'GET /api/overview') {
+                const state = await load();
+                if (!state)
+                    return sendJson(res, 404, { error: 'No tree found. Run: overstory build' });
+                const { tree, verification } = state;
+                return sendJson(res, 200, {
+                    name: tree.name,
+                    builtAt: tree.builtAt,
+                    generator: tree.generator,
+                    provider: opts.provider?.name ?? 'extractive (no LLM)',
+                    freshness: verification.freshness,
+                    verified: [...verification.verdicts.values()].filter((v) => v === 'VERIFIED').length,
+                    total: verification.verdicts.size,
+                    nodes: Object.keys(tree.nodes).length,
+                    suggestions: suggestionsFor(tree),
+                });
+            }
+            if (route === 'GET /api/tree') {
+                const state = await load();
+                if (!state)
+                    return sendJson(res, 404, { error: 'No tree found. Run: overstory build' });
+                return sendJson(res, 200, buildSiteData(state.tree, state.verification, state.scanCorpus));
+            }
+            if (route === 'GET /api/threads')
+                return sendJson(res, 200, await threads.list());
+            if (route === 'GET /api/thread') {
+                const thread = await threads.get(url.searchParams.get('id') ?? '');
+                return thread ? sendJson(res, 200, thread) : sendJson(res, 404, { error: 'no such thread' });
+            }
+            if (route === 'DELETE /api/thread') {
+                const ok = await threads.remove(url.searchParams.get('id') ?? '');
+                return sendJson(res, ok ? 200 : 404, { ok });
+            }
+            if (route === 'POST /api/verify') {
+                const state = await load();
+                if (!state)
+                    return sendJson(res, 404, { error: 'No tree found. Run: overstory build' });
+                const body = verifyBodySchema.parse(await readBody(req));
+                const { index, byId } = buildClaimIndex(state.tree);
+                return sendJson(res, 200, notarizeClaims(body.claims, state.tree, state.corpus, state.verification, index, byId));
+            }
+            if (route === 'POST /api/ask') {
+                const state = await load();
+                if (!state)
+                    return sendJson(res, 404, { error: 'No tree found. Run: overstory build' });
+                const body = askBodySchema.parse(await readBody(req));
+                res.writeHead(200, {
+                    'content-type': 'text/event-stream',
+                    'cache-control': 'no-cache',
+                    connection: 'keep-alive',
+                });
+                const send = (event, data) => {
+                    res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+                };
+                const thread = body.threadId
+                    ? (await threads.get(body.threadId)) ?? (await threads.create(body.question))
+                    : await threads.create(body.question);
+                send('thread', { id: thread.id, title: thread.title });
+                try {
+                    const result = await ask(body.question, state.tree, state.corpus, opts.provider, {
+                        onPhase: (e) => send('phase', e),
+                    });
+                    await threads.addTurn(thread.id, { question: body.question, result, at: new Date().toISOString() });
+                    send('answer', result);
+                }
+                catch (err) {
+                    send('error', { message: err instanceof Error ? err.message : String(err) });
+                }
+                res.end();
+                return;
+            }
+            sendJson(res, 404, { error: 'not found' });
+        }
+        catch (err) {
+            if (!res.headersSent) {
+                sendJson(res, 400, { error: err instanceof Error ? err.message : String(err) });
+            }
+            else {
+                res.end();
+            }
+        }
+    });
+    return server;
+};
+export const serve = async (root, opts) => {
+    const server = createOverstoryHttpServer(root, opts);
+    const port = opts.port ?? 7433;
+    await new Promise((resolvePromise, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => resolvePromise());
+    });
+    opts.onReady?.(`http://127.0.0.1:${port}`);
+    return server;
+};

package/dist/serve/threads.d.ts

@@ -0,0 +1,31 @@
+import type { AskResult } from '../query/ask.js';
+export interface ThreadTurn {
+    question: string;
+    result: AskResult;
+    at: string;
+}
+export interface Thread {
+    id: string;
+    title: string;
+    createdAt: string;
+    turns: ThreadTurn[];
+}
+export declare class ThreadStore {
+    private root;
+    private threads;
+    private loaded;
+    private chain;
+    constructor(root: string);
+    private loadOnce;
+    private persist;
+    list(): Promise<Array<{
+        id: string;
+        title: string;
+        createdAt: string;
+        turns: number;
+    }>>;
+    get(id: string): Promise<Thread | null>;
+    create(title: string): Promise<Thread>;
+    addTurn(id: string, turn: ThreadTurn): Promise<void>;
+    remove(id: string): Promise<boolean>;
+}

package/dist/serve/threads.js

@@ -0,0 +1,69 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+const threadsPath = (root) => join(root, '.overstory', 'threads.json');
+export class ThreadStore {
+    root;
+    threads = [];
+    loaded = false;
+    chain = Promise.resolve();
+    constructor(root) {
+        this.root = root;
+    }
+    async loadOnce() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        try {
+            const raw = JSON.parse(await readFile(threadsPath(this.root), 'utf8'));
+            if (Array.isArray(raw.threads))
+                this.threads = raw.threads;
+        }
+        catch {
+            this.threads = [];
+        }
+    }
+    persist() {
+        const snapshot = JSON.stringify({ threads: this.threads });
+        this.chain = this.chain
+            .then(async () => {
+            const path = threadsPath(this.root);
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(`${path}.tmp`, snapshot, 'utf8');
+            await rename(`${path}.tmp`, path);
+        })
+            .catch(() => { });
+    }
+    async list() {
+        await this.loadOnce();
+        return [...this.threads]
+            .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+            .map((t) => ({ id: t.id, title: t.title, createdAt: t.createdAt, turns: t.turns.length }));
+    }
+    async get(id) {
+        await this.loadOnce();
+        return this.threads.find((t) => t.id === id) ?? null;
+    }
+    async create(title) {
+        await this.loadOnce();
+        const thread = { id: randomUUID(), title: title.slice(0, 120), createdAt: new Date().toISOString(), turns: [] };
+        this.threads.push(thread);
+        this.persist();
+        return thread;
+    }
+    async addTurn(id, turn) {
+        await this.loadOnce();
+        const thread = this.threads.find((t) => t.id === id);
+        if (!thread)
+            return;
+        thread.turns.push(turn);
+        this.persist();
+    }
+    async remove(id) {
+        await this.loadOnce();
+        const before = this.threads.length;
+        this.threads = this.threads.filter((t) => t.id !== id);
+        this.persist();
+        return this.threads.length < before;
+    }
+}

package/dist/site/data.d.ts

@@ -0,0 +1,58 @@
+import type { CorpusSnapshot, Tree, TreeVerification, Verdict } from '../core/types.js';
+export interface SiteSpan {
+    file: string;
+    startLine: number;
+    endLine: number;
+    text: string;
+    hash: string;
+}
+export interface SiteClaim {
+    id: string;
+    text: string;
+    verdict: Verdict;
+    faithfulness: 'supported' | 'unsupported' | 'unchecked';
+    spans: SiteSpan[];
+    refs: Array<{
+        nodeId: string;
+        claimId: string;
+    }>;
+}
+export interface SiteNode {
+    id: string;
+    kind: 'leaf' | 'dir' | 'root';
+    path: string;
+    title: string;
+    claims: SiteClaim[];
+    childIds: string[];
+    builtWith: string;
+    provider?: string;
+    /** Worst verdict anywhere in this subtree — drives the trust dot in the rail. */
+    worst: Verdict;
+    verified: number;
+    total: number;
+}
+export interface SiteFinding {
+    kind: string;
+    severity: 1 | 2 | 3;
+    title: string;
+    detail: string;
+    receipts: number;
+    /** The complete paste-ready prompt (composed server-side, spec shape). */
+    prompt: string;
+}
+export interface SiteData {
+    name: string;
+    builtAt: string;
+    generator: string;
+    freshness: number;
+    verified: number;
+    total: number;
+    root: string;
+    nodes: Record<string, SiteNode>;
+    /** Present when a corpus was available at render time (fix prompts need the code). */
+    findings?: SiteFinding[];
+}
+/** Flatten the tree + verification into the self-contained model the explorer embeds.
+ * With a corpus, also runs the deterministic finding scanner so the explorer can offer
+ * paste-ready, receipt-grounded fix prompts. */
+export declare const buildSiteData: (tree: Tree, verification: TreeVerification, corpus?: CorpusSnapshot) => SiteData;

package/dist/site/data.js

@@ -0,0 +1,88 @@
+import { scanFindings } from '../fix/scan.js';
+import { findingToPrompt } from '../fix/prompts.js';
+const SEVERITY = { VERIFIED: 0, STALE: 1, OUT_OF_CORPUS: 2, UNGROUNDED: 3 };
+/** Flatten the tree + verification into the self-contained model the explorer embeds.
+ * With a corpus, also runs the deterministic finding scanner so the explorer can offer
+ * paste-ready, receipt-grounded fix prompts. */
+export const buildSiteData = (tree, verification, corpus) => {
+    const nodes = {};
+    let verifiedTotal = 0;
+    let claimTotal = 0;
+    for (const node of Object.values(tree.nodes)) {
+        const counts = verification.byNode.get(node.id) ?? { verified: 0, total: 0 };
+        verifiedTotal += counts.verified;
+        claimTotal += counts.total;
+        nodes[node.id] = {
+            id: node.id,
+            kind: node.kind,
+            path: node.path,
+            title: node.title,
+            childIds: node.childIds,
+            builtWith: node.builtWith,
+            provider: node.provider,
+            worst: 'VERIFIED',
+            verified: counts.verified,
+            total: counts.total,
+            claims: node.claims.map((c) => ({
+                id: c.id,
+                text: c.text,
+                verdict: c.verdict ?? verification.verdicts.get(c.id) ?? 'UNGROUNDED',
+                faithfulness: c.faithfulness ?? 'unchecked',
+                spans: c.citations
+                    .filter((x) => x.kind === 'span')
+                    .map((x) => ({
+                    file: x.span.file,
+                    startLine: x.span.startLine,
+                    endLine: x.span.endLine,
+                    text: x.span.text,
+                    hash: x.span.contentHash,
+                })),
+                refs: c.citations
+                    .filter((x) => x.kind === 'claim')
+                    .map((x) => x.ref),
+            })),
+        };
+    }
+    const worstOf = (id, seen = new Set()) => {
+        // Revisits report the already-computed worst (diamond shapes), never a blind VERIFIED.
+        if (seen.has(id))
+            return nodes[id]?.worst ?? 'VERIFIED';
+        seen.add(id);
+        const node = nodes[id];
+        if (!node)
+            return 'VERIFIED';
+        let worst = 'VERIFIED';
+        for (const claim of node.claims)
+            if (SEVERITY[claim.verdict] > SEVERITY[worst])
+                worst = claim.verdict;
+        for (const child of node.childIds) {
+            const w = worstOf(child, seen);
+            if (SEVERITY[w] > SEVERITY[worst])
+                worst = w;
+        }
+        node.worst = worst;
+        return worst;
+    };
+    worstOf(tree.root);
+    const findings = corpus
+        ? scanFindings(corpus, tree, verification).map((f, i) => ({
+            kind: f.kind,
+            severity: f.severity,
+            title: f.title,
+            detail: f.detail,
+            receipts: f.receipts.length,
+            prompt: findingToPrompt(f, i + 1),
+        }))
+        : undefined;
+    return {
+        name: tree.name,
+        builtAt: tree.builtAt,
+        generator: tree.generator,
+        freshness: claimTotal === 0 ? 1 : verifiedTotal / claimTotal,
+        verified: verifiedTotal,
+        total: claimTotal,
+        root: tree.root,
+        nodes,
+        ...(findings ? { findings } : {}),
+    };
+};

package/dist/site/generate.d.ts

@@ -0,0 +1,21 @@
+import type { SiteData } from './data.js';
+export interface AskPanelOptions {
+    /** Repo clone URL for the run-locally instructions. */
+    cloneUrl: string;
+    repoLabel: string;
+}
+export interface ShareMetaOptions {
+    /** Absolute canonical URL of this page (og:url). */
+    url: string;
+    /** e.g. "94% of 2,477 statements verified against the code right now". */
+    status: string;
+}
+/** Render the self-contained explorer. One HTML file, zero external scripts; data embedded
+ * as JSON; fonts degrade gracefully offline (air-gapped is a product promise).
+ * `ask` (registry pages only) adds the Ask panel: run-locally instructions plus browser-side
+ * BYO-key ask — the visitor's key calls Anthropic directly from their browser; the server
+ * never sees keys, questions, or answers. */
+export declare const generateSiteHtml: (data: SiteData, opts?: {
+    ask?: AskPanelOptions;
+    share?: ShareMetaOptions;
+}) => string;