nodedex 0.1.0

package/dist/engine/providers/usage-ledger.js

@@ -0,0 +1,209 @@
+// ═══════════════════════════════════════════════════════════════════════════════
+// USAGE LEDGER — call-level API-key metering  (2026-06-01)
+//
+// Why this exists:
+//   The existing cost telemetry (reflectTokenStats / cost-breakdown) is PER-PASS
+//   and, by design, incomplete. That left a blind spot: "was the API key called
+//   at all, and how much did THIS call cost?" When credit drops there was no local
+//   ground-truth ledger to diff against the provider dashboard.
+//
+//   This wraps the LLM provider at the ONE seam every structured key call goes
+//   through — getLLMProvider() — so EVERY generateStructured() (every provider,
+//   every caller, present and future) is metered into an append-only JSONL ledger
+//   (default ~/.nodedex/api-usage.jsonl), one line per call:
+//     { ts, model, input, output, thinking, cost_usd, cost_source, wall_ms }
+//
+// Design invariants:
+//   - Metering NEVER breaks a generation. The inner result is sacred; all ledger
+//     work is wrapped in try/catch and swallowed on failure.
+//   - Only real key calls are recorded — gated on `result.model` being set (the
+//     no-API-key early return carries no model, so it's correctly skipped).
+//   - cost_usd prefers the provider's ACTUAL billed cost (usage.costUsd, populated
+//     on the OpenRouter path) and falls back to the static-table estimate; every
+//     line is tagged with cost_source so the total is never a silent mix.
+//   - Default ON (observability before optimization). NODEDEX_USAGE_LEDGER=off to
+//     disable; NODEDEX_USAGE_LEDGER_PATH to relocate (tests point it at a temp file).
+//
+// Layering note: imports computeCost from middleware/reflect/cost-pricing, a pure
+// LEAF module (zero internal imports). No cycle.
+// ═══════════════════════════════════════════════════════════════════════════════
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import path from "path";
+import { computeCost } from "../../middleware/reflect/cost-pricing.js";
+function ledgerPath() {
+    return (process.env.NODEDEX_USAGE_LEDGER_PATH ??
+        path.join(homedir(), ".nodedex", "api-usage.jsonl"));
+}
+function ledgerEnabled() {
+    return (process.env.NODEDEX_USAGE_LEDGER ?? "on").toLowerCase() !== "off";
+}
+/** Append one call to the ledger file. Best-effort — callers must not depend on it. */
+function recordCall(res, wallMs) {
+    const u = res.usage; // { input, thinking, output, costUsd? }
+    const tokens = u ? { input: u.input, output: u.output, thinking: u.thinking } : undefined;
+    // Prefer the provider's ACTUAL billed cost; else the static-table estimate.
+    const actual = u?.costUsd;
+    const estimated = computeCost(tokens, res.model);
+    const cost_usd = actual ?? estimated;
+    const cost_source = actual !== undefined && actual !== null
+        ? "openrouter_actual"
+        : estimated !== null
+            ? "estimated"
+            : "unknown";
+    const entry = {
+        ts: new Date().toISOString(),
+        model: res.model ?? "(unknown)",
+        input: tokens?.input ?? null,
+        output: tokens?.output ?? null,
+        thinking: tokens?.thinking ?? null,
+        cost_usd,
+        cost_source,
+        wall_ms: wallMs,
+    };
+    const p = ledgerPath();
+    const dir = path.dirname(p);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    appendFileSync(p, JSON.stringify(entry) + "\n", "utf8");
+}
+/**
+ * Wrap a provider so every generateStructured() call is metered into the ledger.
+ * The single seam — applied once in getLLMProvider(). All other methods delegate
+ * untouched. Only calls that actually hit the API (result.model set) are recorded.
+ */
+export function wrapWithUsageLedger(inner) {
+    return {
+        getName: () => inner.getName(),
+        isAvailable: () => inner.isAvailable(),
+        ping: () => inner.ping(),
+        generate: (prompt) => inner.generate(prompt), // free-form: no usage to meter
+        async generateStructured(systemPrompt, userInput, schema, options) {
+            const t0 = Date.now();
+            const res = await inner.generateStructured(systemPrompt, userInput, schema, options);
+            try {
+                // Only record genuine key calls — the no-client early return has no model.
+                if (ledgerEnabled() && res.model !== undefined)
+                    recordCall(res, Date.now() - t0);
+            }
+            catch {
+                /* metering must never break a generation */
+            }
+            return res;
+        },
+    };
+}
+function emptyModelTotal() {
+    return { calls: 0, input: 0, output: 0, thinking: 0, cost_usd: 0 };
+}
+/**
+ * Summarize the ledger file (all-time — survives restarts, unlike any in-memory
+ * counter). Returns zeros if the ledger doesn't exist. Reads the whole file per
+ * call (fine for a local dev ledger); `recent` caps the tail (default 20).
+ * Malformed lines are skipped, not fatal.
+ */
+export function getUsageSummary(opts = {}) {
+    const recentN = opts.recent ?? 20;
+    const p = ledgerPath();
+    const summary = {
+        ledger_path: p,
+        enabled: ledgerEnabled(),
+        total: { ...emptyModelTotal(), unpriced_calls: 0 },
+        cost_sources: { openrouter_actual: 0, estimated: 0, unknown: 0 },
+        by_model: {},
+        since: null,
+        latest: null,
+        recent: [],
+    };
+    if (!existsSync(p))
+        return summary;
+    let lines;
+    try {
+        lines = readFileSync(p, "utf8").split("\n").filter((l) => l.trim().length > 0);
+    }
+    catch {
+        return summary;
+    }
+    const parsed = [];
+    for (const line of lines) {
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        parsed.push(e);
+        summary.total.calls += 1;
+        summary.total.input += e.input ?? 0;
+        summary.total.output += e.output ?? 0;
+        summary.total.thinking += e.thinking ?? 0;
+        if (e.cost_usd === null || e.cost_usd === undefined) {
+            summary.total.unpriced_calls += 1;
+        }
+        else {
+            summary.total.cost_usd += e.cost_usd;
+        }
+        const src = e.cost_source ?? "estimated";
+        summary.cost_sources[src] = (summary.cost_sources[src] ?? 0) + 1;
+        const m = (summary.by_model[e.model] ??= emptyModelTotal());
+        m.calls += 1;
+        m.input += e.input ?? 0;
+        m.output += e.output ?? 0;
+        m.thinking += e.thinking ?? 0;
+        m.cost_usd += e.cost_usd ?? 0;
+    }
+    if (parsed.length > 0) {
+        summary.since = parsed[0].ts ?? null;
+        summary.latest = parsed[parsed.length - 1].ts ?? null;
+        summary.recent = parsed.slice(-recentN);
+    }
+    // Round money so the JSON isn't float-noise.
+    summary.total.cost_usd = Math.round(summary.total.cost_usd * 1e6) / 1e6;
+    for (const m of Object.values(summary.by_model)) {
+        m.cost_usd = Math.round(m.cost_usd * 1e6) / 1e6;
+    }
+    return summary;
+}
+/**
+ * Sum cost_usd for ledger entries with `startMs <= ts <= endMs` (epoch millis) —
+ * the fast, LOCAL windowed-spend read. Two consumers: the cost breaker's
+ * rolling-window guard (via getSpendSince), and per-stage v2 front-half cost
+ * attribution (each stage's [start,end] timing window → its spend, since the
+ * stages run sequentially so windows don't overlap). Accurate because 97.8% of
+ * entries carry the real billed cost; the blind spots (free-form generate(),
+ * embeddings) aren't ledgered. Missing/unreadable ledger → 0. Malformed lines
+ * skipped; null-cost entries contribute 0.
+ */
+export function getSpendBetween(startMs, endMs) {
+    const p = ledgerPath();
+    if (!existsSync(p))
+        return 0;
+    let lines;
+    try {
+        lines = readFileSync(p, "utf8").split("\n").filter((l) => l.trim().length > 0);
+    }
+    catch {
+        return 0;
+    }
+    let sum = 0;
+    for (const line of lines) {
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const t = Date.parse(e.ts);
+        if (!Number.isFinite(t) || t < startMs || t > endMs)
+            continue;
+        if (typeof e.cost_usd === "number")
+            sum += e.cost_usd;
+    }
+    return Math.round(sum * 1e6) / 1e6;
+}
+export function getSpendSince(sinceMs) {
+    return getSpendBetween(sinceMs, Number.POSITIVE_INFINITY);
+}
+//# sourceMappingURL=usage-ledger.js.map

package/dist/engine/providers/usage-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ledger.js","sourceRoot":"","sources":["../../../src/engine/providers/usage-ledger.ts"],"names":[],"mappings":"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"}

package/dist/engine/search-core.d.ts

@@ -0,0 +1,40 @@
+import { WorkspaceDB, Block } from "../store/database.js";
+import { EmbeddingEngine } from "./embeddings.js";
+export interface SearchHit {
+    block: Block;
+    score: number;
+    matchTypes: string[];
+}
+export interface SearchSignals {
+    semantic: boolean;
+    keyword: boolean;
+    concept: boolean;
+}
+export interface SearchOptions {
+    query: string;
+    type?: string;
+    limit?: number;
+}
+/** Three-signal search: semantic similarity (embedding cosine) + keyword match +
+ *  concept overlap. Signals ADD, so a block matching two ways beats one matching
+ *  once; each hit carries matchTypes explaining why it surfaced. Embeddings are
+ *  optional — without them the semantic signal is skipped and the other two
+ *  still work (signals.semantic reports what actually ran). */
+export declare function searchBlocks(db: WorkspaceDB, embeddings: EmbeddingEngine | undefined, opts: SearchOptions): Promise<{
+    hits: SearchHit[];
+    signals: SearchSignals;
+}>;
+/** True when the ENTIRE result set is weak (semantic-only, sub-0.3): the graph
+ *  likely has nothing on this topic. One strong hit anywhere → not weak. */
+export declare function allWeak(hits: SearchHit[]): boolean;
+export declare const WEAK_NOTE = "weak matches only \u2014 nothing matched by keyword or concept; the graph likely has nothing on this topic. These are just the nearest blocks, not an answer.";
+export interface RootContext {
+    root_label: string;
+    root_essence: string;
+}
+/** Root context for a set of hits — the same containment the tree query renders,
+ *  attached to retrieval results so the agent can judge "which world is this hit
+ *  from?" per line instead of resolving project_id block-by-block. One lookup per
+ *  DISTINCT root. */
+export declare function rootContextFor(db: WorkspaceDB, blocks: Block[]): Map<string, RootContext>;
+//# sourceMappingURL=search-core.d.ts.map

package/dist/engine/search-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-core.d.ts","sourceRoot":"","sources":["../../src/engine/search-core.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AASlD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;+DAI+D;AAC/D,wBAAsB,YAAY,CAChC,EAAE,EAAE,WAAW,EACf,UAAU,EAAE,eAAe,GAAG,SAAS,EACvC,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC;IAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC,CAiExD;AAaD;4EAC4E;AAC5E,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,OAAO,CAIlD;AAED,eAAO,MAAM,SAAS,kKACsI,CAAC;AAE7J,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;qBAGqB;AACrB,wBAAgB,cAAc,CAAC,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAczF"}

package/dist/engine/search-core.js

@@ -0,0 +1,109 @@
+import { cosineSim } from "./vector-math.js";
+const SEARCH_STOPWORDS = new Set([
+    "the", "is", "a", "an", "to", "of", "in", "for", "on", "with", "and", "or", "but", "it",
+    "this", "that", "how", "what", "why", "can", "do", "be", "are", "was", "were", "will",
+    "i", "my", "we", "our",
+]);
+/** Three-signal search: semantic similarity (embedding cosine) + keyword match +
+ *  concept overlap. Signals ADD, so a block matching two ways beats one matching
+ *  once; each hit carries matchTypes explaining why it surfaced. Embeddings are
+ *  optional — without them the semantic signal is skipped and the other two
+ *  still work (signals.semantic reports what actually ran). */
+export async function searchBlocks(db, embeddings, opts) {
+    const limit = opts.limit || 10;
+    const queryConcepts = opts.query
+        .toLowerCase().replace(/[^a-z0-9_ ]/g, " ").split(/\s+/)
+        .filter((w) => w.length > 2 && !SEARCH_STOPWORDS.has(w));
+    const scoreMap = new Map();
+    const add = (block, delta, tag) => {
+        const e = scoreMap.get(block.id);
+        if (e) {
+            e.score += delta;
+            e.matchTypes.add(tag);
+        }
+        else
+            scoreMap.set(block.id, { block, score: delta, matchTypes: new Set([tag]) });
+    };
+    // ── 1. Semantic — meaning, not wording ("auth" finds the "login" block) ──
+    const queryEmbedding = embeddings ? await embeddings.embed(opts.query) : null;
+    if (queryEmbedding) {
+        const semResults = db.semanticSearch(queryEmbedding, limit * 2, opts.type);
+        for (const block of semResults) {
+            const bv = JSON.parse(block.embedding);
+            add(block, cosineSim(queryEmbedding, bv) * 0.5, "semantic");
+        }
+    }
+    // ── 2. Keyword — exact words in label/essence/content ──
+    const kwResults = db.keywordSearch(opts.query, limit * 2, opts.type);
+    for (const block of kwResults)
+        add(block, 0.3, "keyword");
+    // ── 3. Concept overlap — pipeline-stamped tags bridge domains ──
+    if (queryConcepts.length > 0) {
+        const allBlocks = db.getAllBlocks().filter((b) => b.status !== "archived" && (!opts.type || b.type === opts.type));
+        for (const block of allBlocks) {
+            let blockConcepts = [];
+            try {
+                const c = typeof block.content === "string" ? JSON.parse(block.content) : block.content;
+                blockConcepts = (c?.concepts || []).map((x) => x.toLowerCase());
+            }
+            catch { /* ignore */ }
+            if (!blockConcepts.length)
+                continue;
+            const matched = queryConcepts.filter((qc) => blockConcepts.some((bc) => bc.includes(qc) || qc.includes(bc)));
+            if (matched.length > 0) {
+                add(block, Math.min(matched.length * 0.2, 0.6) * 0.4, `concept(${matched.join(",")})`);
+            }
+        }
+    }
+    const hits = Array.from(scoreMap.values())
+        .sort((a, b) => b.score - a.score ||
+        String(b.block.updated_at ?? "").localeCompare(String(a.block.updated_at ?? "")))
+        .slice(0, limit)
+        .map(({ block, score, matchTypes }) => ({ block, score, matchTypes: [...matchTypes] }));
+    return {
+        hits,
+        signals: {
+            semantic: !!queryEmbedding,
+            keyword: true,
+            concept: queryConcepts.length > 0,
+        },
+    };
+}
+// ── Weak-result detection ─────────────────────────────────────────────────────
+// The semantic signal is nearest-neighbor: it always returns the CLOSEST blocks,
+// even when nothing is actually close — so an off-graph query ("kubernetes" on a
+// garden db) still yields hits. Measured signature of that noise (dogfood graph,
+// 2026-07-03): EVERY hit semantic-only at a flat ~0.26, while any real result
+// set has at least one multi-signal hit scoring 0.4+. We LABEL it, never drop
+// it: a silent [] can't be told apart from "search broke" (fail-loud rule), and
+// a weak semantic hit is occasionally a true one (measured: a relevant dead-end
+// at 0.22).
+const WEAK_SCORE = 0.3;
+/** True when the ENTIRE result set is weak (semantic-only, sub-0.3): the graph
+ *  likely has nothing on this topic. One strong hit anywhere → not weak. */
+export function allWeak(hits) {
+    return hits.length > 0 && hits.every((h) => h.score < WEAK_SCORE && h.matchTypes.length === 1 && h.matchTypes[0] === "semantic");
+}
+export const WEAK_NOTE = "weak matches only — nothing matched by keyword or concept; the graph likely has nothing on this topic. These are just the nearest blocks, not an answer.";
+/** Root context for a set of hits — the same containment the tree query renders,
+ *  attached to retrieval results so the agent can judge "which world is this hit
+ *  from?" per line instead of resolving project_id block-by-block. One lookup per
+ *  DISTINCT root. */
+export function rootContextFor(db, blocks) {
+    const out = new Map();
+    for (const b of blocks) {
+        const pid = b.project_id;
+        if (!pid || typeof pid !== "string" || out.has(pid))
+            continue;
+        const root = db.getBlock(pid);
+        if (!root)
+            continue;
+        const ess = root.essence || "";
+        out.set(pid, {
+            root_label: root.label,
+            root_essence: ess.length > 100 ? ess.slice(0, 100) + "…" : ess,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=search-core.js.map

package/dist/engine/search-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-core.js","sourceRoot":"","sources":["../../src/engine/search-core.ts"],"names":[],"mappings":"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"}

package/dist/engine/vector-math.d.ts

@@ -0,0 +1,5 @@
+/** Cosine similarity of two equal-length numeric vectors. Returns 0 on any
+ *  degenerate input: null/undefined, empty, length mismatch, or a zero-magnitude
+ *  vector. */
+export declare function cosineSim(a: number[], b: number[]): number;
+//# sourceMappingURL=vector-math.d.ts.map

package/dist/engine/vector-math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-math.d.ts","sourceRoot":"","sources":["../../src/engine/vector-math.ts"],"names":[],"mappings":"AASA;;cAEc;AACd,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAU1D"}

package/dist/engine/vector-math.js

@@ -0,0 +1,25 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Vector math — the single cosine-similarity implementation.
+//
+// Consolidated 2026-06-14 from SEVEN divergent copies (context, pass4-slice,
+// retrieve-graph-slice, stage-audit-graph, recall, database, tools/helpers) that
+// computed the same value but carried different degenerate-input guards. This is
+// the UNION of those guards. Pure / side-effect-free.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Cosine similarity of two equal-length numeric vectors. Returns 0 on any
+ *  degenerate input: null/undefined, empty, length mismatch, or a zero-magnitude
+ *  vector. */
+export function cosineSim(a, b) {
+    if (!a || !b || a.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0, na = 0, nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+//# sourceMappingURL=vector-math.js.map

package/dist/engine/vector-math.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-math.js","sourceRoot":"","sources":["../../src/engine/vector-math.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,6DAA6D;AAC7D,EAAE;AACF,6EAA6E;AAC7E,iFAAiF;AACjF,iFAAiF;AACjF,sDAAsD;AACtD,gFAAgF;AAEhF;;cAEc;AACd,MAAM,UAAU,SAAS,CAAC,CAAW,EAAE,CAAW;IAChD,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC;IAClE,IAAI,GAAG,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACnB,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAClB,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IACD,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACnC,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/C,CAAC"}

package/dist/home-env.d.ts

@@ -0,0 +1,26 @@
+export declare const NODEDEX_HOME: string;
+export declare const HOME_ENV_PATH: string;
+/** Strip a trailing inline ` # comment` (whitespace-then-#, standard .env semantics) and
+ *  surrounding whitespace. A bare `#` with NO preceding whitespace (e.g. a hex `#ff0000`)
+ *  is kept as part of the value. */
+export declare function stripInlineComment(value: string): string;
+/** Parse a flat KEY=VALUE .env file into a map. Ignores blank lines + full-line `#`
+ *  comments, and strips trailing inline `# comments` from values (so an annotated
+ *  `KEY=2  # note` parses to `2`, not `2  # note` → which would `Number()`→`NaN`).
+ *  The first `=` splits key/value (values may contain `=`). Pure / testable. */
+export declare function parseEnvFile(content: string): Map<string, string>;
+/** An EXISTING repo `.env`, or null. */
+export declare function findExistingRepoEnv(): string | null;
+/** Where the config endpoint WRITES settings: an existing repo `.env` (so dev keeps using
+ *  server/.env) else the user-home `~/.nodedex/.env` (created on first write — the
+ *  fresh-install target). NEVER null, so a fresh install always has somewhere to persist. */
+export declare function resolveEnvWriteTarget(): string;
+/** Apply a key→value map to process.env, but ONLY keys not already set (so an explicit
+ *  env / --env-file / repo .env wins). Returns how many were applied. Pure-ish (mutates
+ *  process.env, which is the point); separated for testability. */
+export declare function applyUnsetEnv(map: Map<string, string>): number;
+/** Load ~/.nodedex/.env at boot, applying only keys not already set. Returns the count
+ *  applied (0 if the file is absent / unreadable). This is what makes web-UI-saved
+ *  settings take effect on the next restart. `envPath` is injectable for tests. */
+export declare function loadHomeEnv(envPath?: string): number;
+//# sourceMappingURL=home-env.d.ts.map

package/dist/home-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"home-env.d.ts","sourceRoot":"","sources":["../src/home-env.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,YAAY,QAAiC,CAAC;AAC3D,eAAO,MAAM,aAAa,QAAgC,CAAC;AAE3D;;oCAEoC;AACpC,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED;;;gFAGgF;AAChF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAUjE;AASD,wCAAwC;AACxC,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,IAAI,CAGnD;AAED;;6FAE6F;AAC7F,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;mEAEmE;AACnE,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAM9D;AAED;;mFAEmF;AACnF,wBAAgB,WAAW,CAAC,OAAO,GAAE,MAAsB,GAAG,MAAM,CAOnE"}

package/dist/home-env.js

@@ -0,0 +1,87 @@
+// home-env.ts — the user-home config home (~/.nodedex/.env).
+//
+// WHY: the engine is env-var-native (every setting is read from process.env). A FRESH
+// install has no repo `server/.env`, so settings set via the web-UI config endpoint had
+// nowhere durable to live (applied in-memory, lost on restart). This makes ~/.nodedex/.env
+// that durable home — the same ~/.nodedex/ dir that already holds reflect-pause, pidfiles,
+// and the TUI config. ONE config model end-to-end (env vars), no JSON↔env mapping layer.
+//
+// PRECEDENCE (highest → lowest): explicit process env / --env-file (e.g. dev server/.env)
+// > ~/.nodedex/.env. loadHomeEnv only fills keys NOT already set, so a dev .env or a real
+// env var always wins; the home file is the fallback that a fresh install relies on.
+import { homedir } from "os";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { existsSync, readFileSync } from "fs";
+export const NODEDEX_HOME = resolve(homedir(), ".nodedex");
+export const HOME_ENV_PATH = resolve(NODEDEX_HOME, ".env");
+/** Strip a trailing inline ` # comment` (whitespace-then-#, standard .env semantics) and
+ *  surrounding whitespace. A bare `#` with NO preceding whitespace (e.g. a hex `#ff0000`)
+ *  is kept as part of the value. */
+export function stripInlineComment(value) {
+    const m = value.match(/\s#/);
+    return (m ? value.slice(0, m.index) : value).trim();
+}
+/** Parse a flat KEY=VALUE .env file into a map. Ignores blank lines + full-line `#`
+ *  comments, and strips trailing inline `# comments` from values (so an annotated
+ *  `KEY=2  # note` parses to `2`, not `2  # note` → which would `Number()`→`NaN`).
+ *  The first `=` splits key/value (values may contain `=`). Pure / testable. */
+export function parseEnvFile(content) {
+    const map = new Map();
+    for (const line of (content ?? "").split("\n")) {
+        const t = line.trim();
+        if (!t || t.startsWith("#"))
+            continue;
+        const eq = t.indexOf("=");
+        if (eq < 0)
+            continue;
+        map.set(t.slice(0, eq).trim(), stripInlineComment(t.slice(eq + 1)));
+    }
+    return map;
+}
+/** Repo `.env` candidates (the DEV file): server/.env (one level up from src|dist) or
+ *  the cwd .env. */
+function repoEnvCandidates() {
+    const here = dirname(fileURLToPath(import.meta.url)); // server/src or server/dist
+    return [resolve(here, "../.env"), resolve(process.cwd(), ".env")];
+}
+/** An EXISTING repo `.env`, or null. */
+export function findExistingRepoEnv() {
+    for (const p of repoEnvCandidates())
+        if (existsSync(p))
+            return p;
+    return null;
+}
+/** Where the config endpoint WRITES settings: an existing repo `.env` (so dev keeps using
+ *  server/.env) else the user-home `~/.nodedex/.env` (created on first write — the
+ *  fresh-install target). NEVER null, so a fresh install always has somewhere to persist. */
+export function resolveEnvWriteTarget() {
+    return findExistingRepoEnv() ?? HOME_ENV_PATH;
+}
+/** Apply a key→value map to process.env, but ONLY keys not already set (so an explicit
+ *  env / --env-file / repo .env wins). Returns how many were applied. Pure-ish (mutates
+ *  process.env, which is the point); separated for testability. */
+export function applyUnsetEnv(map) {
+    let applied = 0;
+    for (const [k, v] of map) {
+        if (process.env[k] === undefined) {
+            process.env[k] = v;
+            applied++;
+        }
+    }
+    return applied;
+}
+/** Load ~/.nodedex/.env at boot, applying only keys not already set. Returns the count
+ *  applied (0 if the file is absent / unreadable). This is what makes web-UI-saved
+ *  settings take effect on the next restart. `envPath` is injectable for tests. */
+export function loadHomeEnv(envPath = HOME_ENV_PATH) {
+    try {
+        if (!existsSync(envPath))
+            return 0;
+        return applyUnsetEnv(parseEnvFile(readFileSync(envPath, "utf8")));
+    }
+    catch {
+        return 0;
+    }
+}
+//# sourceMappingURL=home-env.js.map

package/dist/home-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"home-env.js","sourceRoot":"","sources":["../src/home-env.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server.d.ts

@@ -0,0 +1,13 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WorkspaceDB } from "./store/database.js";
+import { EmbeddingEngine } from "./engine/embeddings.js";
+export declare const WORKSPACE_INSTRUCTIONS = "Nodedex is your persistent memory \u2014 a graph of what was decided, tried, ABANDONED, and constrained across sessions. You did NOT write it \u2014 a background pipeline extracts it from your conversation, so DON'T call save/write tools in normal work (they're for fixing graph errors only). READ before you act.\n\nREACH THE GRAPH ONLY THROUGH THESE TOOLS. Don't go hunting the filesystem or shell \u2014 never read Nodedex's database, log, or config files directly, and don't run raw SQL: you'd get rows stripped of the chains that carry the meaning, and you'd miss the dedup/heal the tools apply. NAVIGATE (traverse), don't blindly query. Touch the underlying DB/files ONLY if you genuinely need something no tool can reach \u2014 that's the rare exception, not the default.\n\nTWO REFLEXES \u2014 do these unprompted:\n1. BEFORE proposing ANY approach, check what already failed \u2014 suggesting something abandoned, or that breaks a constraint, is the worst outcome. \u2192 workspace_filter the approach's concepts (or workspace_get a dead_end label); read the dead_ends + constraints FIRST.\n2. When you need context, TRAVERSE \u2014 don't keyword-search. A block is a headline; the causal CHAIN it sits on is the story. Anchor on a block, then walk.\n\nTHE LOOP (traversal-first):\n- New task, no anchor? \u2192 workspace_filter(concepts) \u2014 first-principle terms of your task (technologies, mechanisms, failure-modes; NOT \"fix\"/\"issue\"). Returns relevant project ROOTS + entry blocks.\n- Know it exists but not the label? \u2192 workspace_search (fuzzy \u2014 the FALLBACK; isolated matches).\n- Know exactly what you want? \u2192 CONSTRUCT the label and get it directly: {project}_{entity}_{type}_{concept} ('_' between dimensions, '-' within a concept, entity optional).\n- Have a block? \u2192 workspace_get(label, detail=\"relations\") \u2014 returns the block PLUS the chain(s) it sits on AND the chains they lead to / rest on (the connected story). That is the unit of meaning; read it, open the next block, keep walking.\n\ndetail: surface (scan) \u2192 relations (block + its chain \u2014 the traversal default) \u2192 full. Graph knowledge is established; your own conclusions are hypotheses until the graph agrees.\n\nFirst time connecting in this project? Call workspace_onboard ONCE \u2014 it offers to persist these reflexes into your own standing config (it checks whether you can, and you explain why + ask the user first). If you can't persist, this advisory copy still applies for the session.";
+/** Whether write/admin/maintenance tools are exposed (default off → read-only surface). */
+export declare function writesExposed(): boolean;
+/** The tool names the agent surface exposes given current env flags (for boot logging). */
+export declare function agentToolAllowlist(): Set<string>;
+/** Build a Workspace MCP server: instructions, read-only gating, and every tool registered.
+ *  A fresh instance is cheap (registration is pure) — the HTTP path builds one per session;
+ *  db + embeddings are shared singletons passed in. */
+export declare function buildWorkspaceServer(db: WorkspaceDB, embeddings: EmbeddingEngine): McpServer;
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAWzD,eAAO,MAAM,sBAAsB,q+EAEmP,CAAC;AAYvR,2FAA2F;AAC3F,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,IAAI,GAAG,CAAC,MAAM,CAAC,CAMhD;AAED;;uDAEuD;AACvD,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,GAAG,SAAS,CAmC5F"}