@north-light/crouter 0.3.154

package/dist/daemon/api/handlers/canvas.js

@@ -0,0 +1,463 @@
+// Canvas-wide read + maintenance handlers (spec §6.3). Attention/history/snapshot
+// are cross-canvas reads; prune/rebuild-index are the maintenance verbs backing
+// `crtr canvas prune` / `crtr canvas rebuild-index`.
+//
+// The CLI leaves (Stage B-6) are pure clients: every canvas.db touch these verbs
+// had — pruneNodes/pruneToLimit/reapEmptyNodes, the rebuild + fail-loud check,
+// the enriched snapshot roster, and the whole
+// buildCorpus/resolveRef search corpus — runs HERE, server-side. map.ts carries
+// no projector for these readers (frozen under concurrency with the sibling
+// handler author), so the field-mapping is inlined \u2014 a server-side projection,
+// the sanctioned place for it.
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { listNodes, nowIso, ticketsAcrossCanvas } from '../../../index.js';
+import { getNode, pruneNodes, pruneToLimit, rebuildIndex, rosterEdges, rosterNodes, subscriptionsOf } from '../../../core/canvas/canvas.js';
+import { dashboardRowsAll, enrichRows } from '../../../core/canvas/render.js';
+import { ticketCountsForNodes } from '../../../core/canvas/attention.js';
+import { buildCorpus, resolveRef, } from '../../../core/canvas/history.js';
+import { nodeDir, nodesRoot } from '../../../core/canvas/paths.js';
+import { reapEmptyNodes } from '../../../core/runtime/placement.js';
+import { general, notFound, usage } from '../../../core/errors.js';
+function handleAttention() {
+    const body = {
+        items: ticketsAcrossCanvas().map((t) => ({
+            node_id: t.node_id,
+            name: t.name,
+            cwd: t.cwd,
+            count: t.count,
+        })),
+    };
+    return { status: 200, body };
+}
+/** The attach viewer refreshes a small live slice every five seconds. Its ticket
+ * badges must never force the enriched full-canvas snapshot, which synchronously
+ * reads every node's metadata and telemetry before it can answer any request. */
+function handleAttentionCounts(ctx) {
+    const raw = ctx.body;
+    if (raw === null || typeof raw !== 'object' || !Array.isArray(raw['node_ids'])) {
+        throw usage('attention count request requires node_ids: string[]');
+    }
+    const rawIds = raw['node_ids'];
+    if (!rawIds.every((id) => typeof id === 'string')) {
+        throw usage('attention count request node_ids must contain only strings');
+    }
+    const body = { counts: ticketCountsForNodes(rawIds) };
+    return { status: 200, body };
+}
+// ---------------------------------------------------------------------------
+// history search / grep / read \u2014 the ranked corpus search, the required-
+// pattern line-hit search, and ref resolution. Lifted verbatim from
+// `commands/canvas-history/{search,grep,read}.ts`' run() bodies: the pure
+// ranking/snippet/pagination is unchanged; only the caller relocated (the CLI
+// now parses+validates flags and POSTs the normalized query). search and grep
+// share the corpus builder and cursor helpers but are distinct wire contracts
+// \u2014 no `--grep` flag survives on the search query.
+// ---------------------------------------------------------------------------
+function encodeCursor(offset) {
+    return Buffer.from(String(offset), 'utf8').toString('base64');
+}
+function decodeCursor(c) {
+    const n = Number(Buffer.from(c, 'base64').toString('utf8'));
+    if (!Number.isInteger(n) || n < 0)
+        throw usage(`invalid cursor: ${c}`);
+    return n;
+}
+/** One snippet block: the matching line(s), `lines` deep. Falls back to the
+ *  title or the first body lines when nothing matched on the body. */
+function snippet(a, terms, lines) {
+    const body = a.loadBody();
+    const rows = body.split('\n');
+    if (terms.length > 0) {
+        const idx = rows.findIndex((r) => {
+            const lc = r.toLowerCase();
+            return terms.some((t) => lc.includes(t));
+        });
+        if (idx !== -1) {
+            return rows
+                .slice(idx, idx + lines)
+                .map((r) => r.trim())
+                .filter((r) => r !== '')
+                .join(' \u23ce ');
+        }
+    }
+    const lead = rows.map((r) => r.trim()).filter((r) => r !== '').slice(0, lines).join(' \u23ce ');
+    return lead !== '' ? lead : a.title;
+}
+function sortArtifacts(arts, mode, scored) {
+    const out = [...arts];
+    if (mode === 'relevance' && scored !== undefined) {
+        out.sort((x, y) => (scored.get(y.ref) ?? 0) - (scored.get(x.ref) ?? 0) || y.tsMs - x.tsMs || x.ref.localeCompare(y.ref));
+    }
+    else if (mode === 'oldest') {
+        out.sort((x, y) => x.tsMs - y.tsMs || x.ref.localeCompare(y.ref));
+    }
+    else {
+        out.sort((x, y) => y.tsMs - x.tsMs || x.ref.localeCompare(y.ref));
+    }
+    return out;
+}
+function parseSearchBody(body) {
+    if (body === undefined || body === null)
+        return {};
+    if (typeof body !== 'object')
+        throw usage('history search body must be a JSON object');
+    return body;
+}
+function parseGrepBody(body) {
+    if (body === null || typeof body !== 'object')
+        throw usage('history grep body must be a JSON object');
+    const q = body;
+    if (typeof q.pattern !== 'string' || q.pattern === '')
+        throw usage('history grep body requires a non-empty pattern');
+    return q;
+}
+function buildCorpusFromQuery(q) {
+    const scope = {
+        cwd: q.cwd,
+        allCwds: q.all_cwds === true,
+        under: q.under,
+        nodes: q.nodes,
+    };
+    const corpusFilter = {
+        types: q.types,
+        reportKind: q.report_kind,
+        kinds: q.kinds,
+        statuses: q.statuses,
+        sinceMs: q.since_ms,
+        untilMs: q.until_ms,
+    };
+    return buildCorpus(scope, corpusFilter);
+}
+function handleHistoryGrep(ctx) {
+    const q = parseGrepBody(ctx.body);
+    const limit = Math.min(100, Math.max(1, q.limit ?? 20));
+    const arts = buildCorpusFromQuery(q);
+    const offset = q.cursor !== undefined ? decodeCursor(q.cursor) : 0;
+    let re;
+    try {
+        re = new RegExp(q.pattern, 'i');
+    }
+    catch {
+        throw usage(`invalid regex pattern: ${q.pattern}`);
+    }
+    const lineHits = [];
+    for (const a of arts) {
+        const rows = a.loadBody().split('\n');
+        rows.forEach((text, i) => {
+            if (re.test(text))
+                lineHits.push({ ref: a.ref, node: `${a.nodeName} (${a.nodeId})`, ts: a.ts, line: i + 1, text: text.trim() });
+        });
+    }
+    lineHits.sort((x, y) => x.ref.localeCompare(y.ref) || x.line - y.line);
+    const page = lineHits.slice(offset, offset + limit);
+    const nextCursor = offset + limit < lineHits.length ? encodeCursor(offset + limit) : null;
+    const body = { hits: page, next_cursor: nextCursor, total: lineHits.length };
+    return { status: 200, body };
+}
+function handleHistorySearch(ctx) {
+    const q = parseSearchBody(ctx.body);
+    const query = (q.query ?? '').trim();
+    const weighBody = q.weigh_body === true;
+    const full = q.full === true;
+    const snippetLines = Math.max(1, q.snippet_lines ?? 1);
+    const limit = Math.min(100, Math.max(1, q.limit ?? 20));
+    const arts = buildCorpusFromQuery(q);
+    const offset = q.cursor !== undefined ? decodeCursor(q.cursor) : 0;
+    // --- ranked / browse mode ---
+    const terms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 0);
+    let pool = arts;
+    let scored;
+    const sortMode = q.sort ?? (terms.length > 0 ? 'relevance' : 'recency');
+    if (terms.length > 0 && sortMode === 'relevance') {
+        scored = new Map();
+        const matched = [];
+        for (const a of arts) {
+            const titleLc = a.title.toLowerCase();
+            const nameLc = a.nodeName.toLowerCase();
+            const descLc = a.nodeDesc.toLowerCase();
+            const bodyLc = weighBody ? a.loadBody().toLowerCase() : null;
+            let score = 0;
+            for (const t of terms) {
+                if (titleLc.includes(t))
+                    score += 10;
+                if (nameLc.includes(t))
+                    score += 5;
+                if (descLc.includes(t))
+                    score += 3;
+                if (bodyLc !== null && bodyLc.includes(t))
+                    score += 1;
+            }
+            if (score > 0) {
+                scored.set(a.ref, score);
+                matched.push(a);
+            }
+        }
+        pool = matched;
+    }
+    else if (terms.length > 0) {
+        // Query present but a timeline sort requested: filter by match, order by ts.
+        pool = arts.filter((a) => {
+            const hay = `${a.title}\n${a.nodeName}\n${a.nodeDesc}${weighBody ? '\n' + a.loadBody() : ''}`.toLowerCase();
+            return terms.some((t) => hay.includes(t));
+        });
+    }
+    const sorted = sortArtifacts(pool, sortMode, scored);
+    const page = sorted.slice(offset, offset + limit);
+    const nextCursor = offset + limit < sorted.length ? encodeCursor(offset + limit) : null;
+    const hits = page.map((a) => {
+        const base = {
+            ref: a.ref,
+            node: `${a.nodeName} (${a.nodeId})`,
+            kind: a.nodeKind,
+            source: a.source === 'report' && a.reportKind ? `report:${a.reportKind}` : a.source,
+            ts: a.ts,
+        };
+        if (sortMode === 'relevance' && scored !== undefined)
+            base['score'] = scored.get(a.ref) ?? 0;
+        if (full)
+            base['body'] = a.loadBody();
+        else
+            base['snippet'] = snippet(a, terms, snippetLines);
+        return base;
+    });
+    const body = { hits, next_cursor: nextCursor, total: sorted.length };
+    return { status: 200, body };
+}
+function handleHistoryRead(ctx) {
+    const ref = (ctx.query.get('ref') ?? '').trim();
+    const includeFrontmatter = ctx.query.get('frontmatter') === 'true';
+    if (!ref.includes(':')) {
+        throw usage(`ref must be <node-id>:<relpath>; received: ${ref}`, {
+            received: ref,
+            next: 'Get a valid ref from `canvas history search` or `node inspect artifacts <node-id>`.',
+        });
+    }
+    let resolved;
+    try {
+        resolved = resolveRef(ref);
+    }
+    catch (e) {
+        throw usage(`ref rejected: ${e.message}`, {
+            received: ref,
+            next: 'Refs come verbatim from `canvas history search`; do not hand-construct relpaths.',
+        });
+    }
+    if (resolved === null) {
+        throw notFound(`no artifact for ref: ${ref}`, {
+            ref,
+            next: 'The node or file may not exist. Re-run `canvas history search` for a current ref, or `node inspect artifacts <node-id>` to list a node\'s artifacts.',
+        });
+    }
+    const source = resolved.source === 'report' && resolved.reportKind ? `report:${resolved.reportKind}` : resolved.source;
+    const content = includeFrontmatter && resolved.raw !== null ? resolved.raw : resolved.body;
+    const body = {
+        ref,
+        node: `${resolved.nodeName} (${resolved.nodeId})`,
+        source,
+        ts: resolved.ts,
+        content,
+    };
+    return { status: 200, body };
+}
+// ---------------------------------------------------------------------------
+// snapshot \u2014 the enriched browser canvas roster + subscribes_to adjacency.
+// Lifted from `commands/canvas-snapshot.ts` run() (dashboardRowsAll + enrichRows).
+// ---------------------------------------------------------------------------
+function handleSnapshot() {
+    const rows = dashboardRowsAll();
+    enrichRows(rows);
+    const nodes = rows.map((row) => {
+        const meta = getNode(row.node_id);
+        const hostKind = meta?.host_kind ?? 'tmux';
+        return {
+            node_id: row.node_id,
+            name: row.name,
+            kind: row.kind,
+            mode: row.mode,
+            lifecycle: row.lifecycle ?? meta?.lifecycle,
+            status: row.status,
+            cwd: row.cwd,
+            parent: meta?.parent ?? null,
+            created: row.created,
+            host_kind: hostKind,
+            enterable: hostKind === 'broker',
+            attention_count: row.asks,
+            ...(meta?.cycles !== undefined ? { cycles: meta.cycles } : {}),
+            ...(row.mtimeMs !== undefined ? { last_activity: new Date(row.mtimeMs).toISOString() } : {}),
+            ctx_tokens: row.ctx_tokens,
+            streaming: row.streaming ?? false,
+            hanging: (row.hanging ?? null),
+            viewed: row.viewed ?? false,
+        };
+    });
+    const subscriptions = Object.fromEntries(rows.map((row) => [row.node_id, subscriptionsOf(row.node_id).map((ref) => ref.node_id)]));
+    const body = { generated_at: nowIso(), nodes, subscriptions };
+    return { status: 200, body };
+}
+// ---------------------------------------------------------------------------
+// roster - the lean, set-based topology read (daemon-starvation fix step 2).
+// Exactly two indexed queries (rosterNodes() + rosterEdges()), no enrichRows,
+// no per-row getNode/subscriptionsOf loop, no isStreaming/isPidAlive process
+// probe. Single-flighted below so a burst of concurrent pollers (attach +
+// browser, or several attach viewers) shares one DB pass instead of stacking N.
+// ---------------------------------------------------------------------------
+function buildRoster() {
+    const nodes = rosterNodes().map((row) => {
+        const hostKind = row.host_kind ?? 'tmux';
+        return {
+            node_id: row.node_id,
+            name: row.name,
+            kind: row.kind,
+            mode: row.mode,
+            lifecycle: row.lifecycle,
+            status: row.status,
+            cwd: row.cwd,
+            host_kind: hostKind,
+            enterable: hostKind === 'broker',
+            parent: row.parent,
+            created: row.created,
+        };
+    });
+    const edges = rosterEdges().map((e) => ({
+        from_id: e.from_id,
+        to_id: e.to_id,
+        active: e.active,
+        created: e.created,
+    }));
+    return { generated_at: nowIso(), nodes, edges };
+}
+/** Single-flight: concurrent callers during an in-flight pass share its result
+ *  instead of each starting their own DB pass. A caller that arrives AFTER the
+ *  in-flight pass already started is not served that (possibly already stale)
+ *  result - it schedules at most one trailing re-run and awaits that, so the
+ *  roster never falls behind a burst of writes but never stacks unbounded
+ *  concurrent passes either. */
+let rosterInFlight = null;
+let rosterTrailing = null;
+function rosterCoalesced() {
+    if (rosterInFlight === null) {
+        rosterInFlight = Promise.resolve()
+            .then(() => buildRoster())
+            .finally(() => {
+            rosterInFlight = null;
+        });
+        return rosterInFlight;
+    }
+    if (rosterTrailing === null) {
+        rosterTrailing = rosterInFlight
+            .then(() => buildRoster())
+            .finally(() => {
+            rosterTrailing = null;
+        });
+    }
+    return rosterTrailing;
+}
+async function handleRoster() {
+    const body = await rosterCoalesced();
+    return { status: 200, body };
+}
+// ---------------------------------------------------------------------------
+// prune \u2014 the three exclusive modes (COUNT > EMPTY > TTL sweep) + target-gone
+// notification. Lifted from `commands/canvas-prune.ts` run().
+// ---------------------------------------------------------------------------
+/** Validate + narrow the prune body (all fields optional). */
+function parsePruneBody(body) {
+    if (body === undefined || body === null)
+        return {};
+    if (typeof body !== 'object')
+        throw usage('prune body must be a JSON object');
+    const b = body;
+    const num = (name) => {
+        const v = b[name];
+        if (v === undefined)
+            return undefined;
+        if (typeof v !== 'number' || !Number.isFinite(v))
+            throw usage(`${name} must be a number`);
+        return v;
+    };
+    const bool = (name) => {
+        const v = b[name];
+        if (v === undefined)
+            return undefined;
+        if (typeof v !== 'boolean')
+            throw usage(`${name} must be a boolean`);
+        return v;
+    };
+    const out = {};
+    const limit = num('limit');
+    if (limit !== undefined)
+        out.limit = limit;
+    const ttlDays = num('ttl_days');
+    if (ttlDays !== undefined)
+        out.ttl_days = ttlDays;
+    const includeStale = bool('include_stale');
+    if (includeStale !== undefined)
+        out.include_stale = includeStale;
+    const empty = bool('empty');
+    if (empty !== undefined)
+        out.empty = empty;
+    const dryRun = bool('dry_run');
+    if (dryRun !== undefined)
+        out.dry_run = dryRun;
+    return out;
+}
+function handlePrune(ctx) {
+    const req = parsePruneBody(ctx.body);
+    const ttlDays = req.ttl_days ?? 14;
+    const dryRun = req.dry_run ?? false;
+    // Precedence COUNT (limit) > EMPTY > TTL sweep \u2014 matching the CLI leaf.
+    let pruned;
+    if (req.limit !== undefined) {
+        const result = pruneToLimit({ maxNodes: req.limit, dryRun });
+        pruned = result.pruned.map((p) => ({ node_id: p.node_id, status: p.status, created: p.created }));
+    }
+    else if (req.empty === true) {
+        const ids = reapEmptyNodes({ dryRun });
+        pruned = ids.map((node_id) => ({ node_id, status: 'empty', created: '' }));
+    }
+    else {
+        const result = pruneNodes({ ttlDays, dryRun, includeStale: req.include_stale ?? false });
+        pruned = result.pruned.map((p) => ({ node_id: p.node_id, status: p.status, created: p.created }));
+    }
+    const body = { pruned, dry_run: dryRun, ttl_days: ttlDays };
+    return { status: 200, body };
+}
+// ---------------------------------------------------------------------------
+// rebuild-index \u2014 re-derive rows from on-disk metas + the fail-loud guard.
+// Lifted from `commands/canvas-rebuild-index.ts` (countOnDiskMetas + throw).
+// ---------------------------------------------------------------------------
+function countOnDiskMetas() {
+    const root = nodesRoot();
+    if (!existsSync(root))
+        return 0;
+    let n = 0;
+    for (const id of readdirSync(root)) {
+        if (existsSync(join(nodeDir(id), 'meta.json')))
+            n++;
+    }
+    return n;
+}
+function handleRebuildIndex() {
+    const metas = countOnDiskMetas();
+    rebuildIndex();
+    const rows = listNodes().length;
+    if (metas > 0 && rows === 0) {
+        // A non-500 CrtrError so the specific diagnostic survives the error body
+        // (toErrorBody scrubs 500 messages for hygiene).
+        throw general(`rebuild-index found ${metas} on-disk meta.json file(s) under ${nodesRoot()} but produced 0 node rows in canvas.db \u2014 rebuild failed; refusing to leave an empty index`);
+    }
+    const body = { metas, rows };
+    return { status: 200, body };
+}
+export const canvasRoutes = [
+    { method: 'GET', pattern: '/v1/canvas/attention', handler: handleAttention },
+    { method: 'POST', pattern: '/v1/canvas/attention/counts', handler: handleAttentionCounts },
+    { method: 'POST', pattern: '/v1/canvas/history/search', handler: handleHistorySearch },
+    { method: 'POST', pattern: '/v1/canvas/history/grep', handler: handleHistoryGrep },
+    { method: 'GET', pattern: '/v1/canvas/history/read', handler: handleHistoryRead },
+    { method: 'GET', pattern: '/v1/canvas/snapshot', handler: handleSnapshot },
+    { method: 'GET', pattern: '/v1/canvas/roster', handler: handleRoster },
+    { method: 'POST', pattern: '/v1/canvas/prune', handler: handlePrune },
+    { method: 'POST', pattern: '/v1/canvas/rebuild-index', handler: handleRebuildIndex },
+];

package/dist/daemon/api/handlers/crons.d.ts

@@ -0,0 +1,2 @@
+import type { RouteTable } from '../router.js';
+export declare const cronRoutes: RouteTable;