@wrenai/genbi 0.0.1

package/dist-server/server/conn-config.d.ts

@@ -0,0 +1,30 @@
+export interface ConnConfig {
+    readonly datasource?: string;
+    readonly fields: Readonly<Record<string, string>>;
+}
+export interface ConnectionDetail {
+    readonly type: string;
+    readonly location: string;
+}
+export declare function loadConnConfig(projectDir: string): ConnConfig | undefined;
+export interface ProjectManifest {
+    /** `wren_project.yml`'s `data_source:` — always present on a real wren project; this is the connection panel's `type`. */
+    readonly dataSource?: string;
+    /** `wren_project.yml`'s `profile:` pin, if the project has bound one — the key into `~/.wren/profiles.yml`'s `profiles:` map. */
+    readonly profile?: string;
+}
+/** Reads `<projectDir>/wren_project.yml`'s persistent `data_source:`/`profile:` scalars. Unlike `conn.yml`, this file always exists on a bound wren project. Returns `undefined` only when the manifest itself is missing/unreadable — never throws. */
+export declare function loadProjectManifest(projectDir: string): ProjectManifest | undefined;
+/**
+ * Resolves the `(datasource, fields)` pair `describeConnection` needs, per
+ * the precedence documented in this module's doc comment: `conn.yml` first
+ * if it happens to exist and declares a `datasource:`, otherwise
+ * `wren_project.yml`'s `data_source:` for `type` plus its pinned `profile:`
+ * (looked up in `~/.wren/profiles.yml`) for the location `fields`. A project
+ * with no pin still reports its real `data_source`, with empty fields (→
+ * `describeConnection` renders an honest "—" location) — it never
+ * substitutes the profiles store's global `active:` profile.
+ */
+export declare function resolveConnectionSource(projectDir: string): ConnConfig;
+/** Maps a resolved `(datasource, fields)` pair to the connection panel's `type`/`location` — never fabricates a label and never surfaces a secret field. */
+export declare function describeConnection(datasource: string | undefined, fields: Readonly<Record<string, string>>): ConnectionDetail;

package/dist-server/server/conn-config.js

@@ -0,0 +1,253 @@
+/**
+ * Resolves the REAL datasource + connection fields behind the Harness page's
+ * connection panel — see `buildConnection` in `server/harness.ts` — and
+ * describes them into a safe, non-secret display shape.
+ *
+ * `<project>/conn.yml` is NOT a persistent part of a wren project: the wren
+ * CLI's onboarding wizard writes a *temporary* scratch file inside the
+ * project directory (under a name deliberately not `conn.yml`, e.g.
+ * `conn.profile.yml`) and feeds it to `wren profile add --from-file`, then
+ * deletes it once the profile is created — so it never leaves a `conn.yml`
+ * in the project directory itself. So `loadConnConfig` below only ever finds
+ * something to read on hand-authored fixtures (or a project laid out that
+ * way on purpose) — never on a project the CLI actually onboarded. The two
+ * files that ARE always there:
+ *   - `<project>/wren_project.yml` — its `data_source:` field is the real,
+ *     always-present datasource, and its `profile:` field (if set) pins which
+ *     stored profile the project actually connects through.
+ *   - `~/.wren/profiles.yml` (or `$WREN_HOME/profiles.yml`) — the pinned
+ *     profile's own field map (duckdb `url`, DB `host`/`port`/`database`, …),
+ *     read via `server/wren-profiles.ts`'s shared parser.
+ * `resolveConnectionSource` is the entry point every caller should use: it
+ * prefers `conn.yml` when one happens to exist (kept only so a fixture/hand
+ * laid out project isn't silently ignored), and otherwise resolves through
+ * the manifest + profiles store above — WITHOUT ever falling back to the
+ * profiles store's global `active:` profile when the project has no pin of
+ * its own, since a project must never display a connection it isn't bound
+ * to.
+ *
+ * `conn.yml`, when present, is a flat `key: value` file (no nesting) — e.g.
+ * ```
+ * datasource: duckdb
+ * url: ${DUCKDB_URL}
+ * format: ${DUCKDB_FORMAT}
+ * ```
+ * so a small line-based parser is enough here; pulling in a full YAML
+ * library for one flat file would be overkill. `wren_project.yml` only ever
+ * needs two scalar fields read out of it, so it gets the same small-parser
+ * treatment (mirrors `server/adopt.ts`'s own `readYamlScalarField`).
+ *
+ * SECURITY: `describeConnection` only ever reads from a fixed ALLOWLIST of
+ * non-secret field names (host/port/database/project id/…) when building the
+ * displayed location string. It never touches or forwards arbitrary
+ * `conn.yml`/`.env`/profile keys, so a field named
+ * `password`/`user`/`token`/`credentials`/`private_key` etc. can never reach
+ * the DTO even if present in the parsed config — there is no denylist to
+ * keep in sync as new datasources are added.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { loadProfileStore } from "./wren-profiles.js";
+function stripQuotes(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'"))
+            return value.slice(1, -1);
+    }
+    return value;
+}
+/** Parses a flat `key: value` YAML file — one mapping per line, no nested structures. */
+function parseFlatYaml(text) {
+    const result = {};
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const idx = line.indexOf(":");
+        if (idx === -1)
+            continue;
+        const key = line.slice(0, idx).trim();
+        if (!key)
+            continue;
+        result[key] = stripQuotes(line.slice(idx + 1).trim());
+    }
+    return result;
+}
+/** Parses a `.env` file — `KEY=value` per line, optional `export ` prefix, `#` comments. */
+function parseDotEnv(text) {
+    const result = {};
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const withoutExport = line.startsWith("export ") ? line.slice("export ".length) : line;
+        const idx = withoutExport.indexOf("=");
+        if (idx === -1)
+            continue;
+        const key = withoutExport.slice(0, idx).trim();
+        if (!key)
+            continue;
+        result[key] = stripQuotes(withoutExport.slice(idx + 1).trim());
+    }
+    return result;
+}
+const TEMPLATE_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/** Resolves `${VAR}` references via `lookup`; returns `undefined` (rather than a literal, broken `${VAR}`) if any reference can't be resolved. */
+function resolveTemplate(value, lookup) {
+    let unresolved = false;
+    const resolved = value.replace(TEMPLATE_RE, (_match, name) => {
+        const resolvedValue = lookup(name);
+        if (resolvedValue === undefined) {
+            unresolved = true;
+            return "";
+        }
+        return resolvedValue;
+    });
+    return unresolved ? undefined : resolved;
+}
+/**
+ * Reads `<projectDir>/conn.yml`, resolving any `${VAR}` values against
+ * `<projectDir>/.env` (a real environment variable of the same name, if set,
+ * wins over the project's `.env` — mirroring the wren CLI's own dotenv
+ * loading, so a shell-exported override still applies). Returns `undefined`
+ * when there's no `conn.yml` to read (unbound project, or a project laid out
+ * without one) rather than throwing — callers fall back to an honest "—".
+ */
+/**
+ * Resolves `${VAR}` references against a real environment variable, else the
+ * project's own `.env`. Shared by both connection sources: a stored profile
+ * holds the same `${VAR}` references `conn.yml` does — that is how wren keeps
+ * credentials out of `~/.wren/profiles.yml` — so a display that skipped this
+ * step showed the reference instead of the value.
+ */
+function envLookup(projectDir) {
+    const dotenvPath = path.join(projectDir, ".env");
+    let dotenv = {};
+    if (existsSync(dotenvPath)) {
+        try {
+            dotenv = parseDotEnv(readFileSync(dotenvPath, "utf-8"));
+        }
+        catch {
+            dotenv = {};
+        }
+    }
+    return (name) => process.env[name] ?? dotenv[name];
+}
+export function loadConnConfig(projectDir) {
+    const connPath = path.join(projectDir, "conn.yml");
+    if (!existsSync(connPath))
+        return undefined;
+    let raw;
+    try {
+        raw = parseFlatYaml(readFileSync(connPath, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+    const lookup = envLookup(projectDir);
+    const fields = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (key === "datasource")
+            continue;
+        const resolved = resolveTemplate(value, lookup);
+        if (resolved !== undefined)
+            fields[key] = resolved;
+    }
+    return raw.datasource !== undefined ? { datasource: raw.datasource, fields } : { fields };
+}
+/**
+ * Matches a `wren_project.yml` top-level `field: value` scalar line — a
+ * second small instance of `server/adopt.ts`'s own `readYamlScalarField`
+ * rather than an import from it: this module only ever needs the same two
+ * fields (`data_source`, `profile`), and adopt.ts's function isn't exported
+ * for reuse, so a four-line regex duplicated here is cheaper than adding a
+ * cross-module export just for it.
+ */
+function readManifestScalar(content, field) {
+    const re = new RegExp(`^${field}:\\s*(.+?)\\s*$`, "m");
+    const match = re.exec(content);
+    return match ? stripQuotes(match[1].trim()) : undefined;
+}
+/** Reads `<projectDir>/wren_project.yml`'s persistent `data_source:`/`profile:` scalars. Unlike `conn.yml`, this file always exists on a bound wren project. Returns `undefined` only when the manifest itself is missing/unreadable — never throws. */
+export function loadProjectManifest(projectDir) {
+    const manifestPath = path.join(projectDir, "wren_project.yml");
+    if (!existsSync(manifestPath))
+        return undefined;
+    try {
+        const content = readFileSync(manifestPath, "utf-8");
+        const dataSource = readManifestScalar(content, "data_source");
+        const profile = readManifestScalar(content, "profile");
+        return { ...(dataSource !== undefined ? { dataSource } : {}), ...(profile !== undefined ? { profile } : {}) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolves the `(datasource, fields)` pair `describeConnection` needs, per
+ * the precedence documented in this module's doc comment: `conn.yml` first
+ * if it happens to exist and declares a `datasource:`, otherwise
+ * `wren_project.yml`'s `data_source:` for `type` plus its pinned `profile:`
+ * (looked up in `~/.wren/profiles.yml`) for the location `fields`. A project
+ * with no pin still reports its real `data_source`, with empty fields (→
+ * `describeConnection` renders an honest "—" location) — it never
+ * substitutes the profiles store's global `active:` profile.
+ */
+export function resolveConnectionSource(projectDir) {
+    const connConfig = loadConnConfig(projectDir);
+    if (connConfig?.datasource !== undefined)
+        return connConfig;
+    const manifest = loadProjectManifest(projectDir);
+    if (!manifest?.dataSource)
+        return { fields: {} };
+    if (!manifest.profile)
+        return { datasource: manifest.dataSource, fields: {} };
+    const profileFields = loadProfileStore().profiles.get(manifest.profile);
+    if (!profileFields)
+        return { datasource: manifest.dataSource, fields: {} };
+    // A stored profile's values are `${VAR}` references into the project's
+    // `.env` — that is how wren keeps credentials out of `~/.wren/profiles.yml`.
+    // They need the same resolution `conn.yml` already gets; without it the
+    // connection panel rendered the literal `${BIGQUERY_PROJECT_ID}`.
+    const lookup = envLookup(projectDir);
+    const fields = {};
+    for (const [key, value] of profileFields) {
+        if (key === "datasource")
+            continue; // the manifest's data_source is authoritative for `type`; profiles.yml's own field is redundant and excluded from `fields`.
+        const resolved = resolveTemplate(value, lookup);
+        // An unresolved reference is dropped rather than shown: the panel's job is
+        // to say where this project connects, and `${SOMETHING}` answers that no
+        // better than showing nothing.
+        if (resolved !== undefined)
+            fields[key] = resolved;
+    }
+    return { datasource: manifest.dataSource, fields };
+}
+/** Filesystem-backed datasources — `url` IS the connection location (a local path, or a bucket/object URL with no embedded credentials in these connection info shapes). */
+const FILE_DATASOURCES = new Set(["duckdb", "local_file", "gcs_file", "minio_file", "s3_file"]);
+/**
+ * ALLOWLIST of non-secret field names used to build the displayed location
+ * string for DB-type datasources, in display order. Deliberately excludes
+ * every credential-shaped field (password, user, credentials, token,
+ * private_key, access_key/secret_key, client_id/client_secret, dsn, kwargs,
+ * …) — those are simply never read here, regardless of datasource.
+ */
+const LOCATION_FIELD_ORDER = ["database", "project_id", "dataset_id", "account", "schema", "warehouse", "region_name", "schema_name"];
+/** Maps a resolved `(datasource, fields)` pair to the connection panel's `type`/`location` — never fabricates a label and never surfaces a secret field. */
+export function describeConnection(datasource, fields) {
+    if (!datasource)
+        return { type: "—", location: "—" };
+    if (FILE_DATASOURCES.has(datasource)) {
+        return { type: datasource, location: fields.url ?? "—" };
+    }
+    const segments = [];
+    if (fields.host)
+        segments.push(fields.port ? `${fields.host}:${fields.port}` : fields.host);
+    for (const key of LOCATION_FIELD_ORDER) {
+        const value = fields[key];
+        if (value)
+            segments.push(value);
+    }
+    return { type: datasource, location: segments.length > 0 ? segments.join("/") : "—" };
+}

package/dist-server/server/context-files.d.ts

@@ -0,0 +1,12 @@
+import type { WrenContextShow } from "./context-source.js";
+import type { ContextFileNode, KnowledgeStatus } from "./wire-types.js";
+/**
+ * `instructionsPresent` from the real presence of at least one authored
+ * `knowledge/rules/*.md` file (as opposed to the placeholder-only
+ * subdirectories, e.g. `caveats/`/`glossary/`). `verifiedPairCount` is always
+ * 0 — there is no live Q-SQL verified-pair source over a real project yet
+ * (see `server/impact.ts`'s doc comment).
+ */
+export declare function computeKnowledgeStatus(projectDir: string): KnowledgeStatus;
+/** Builds the whole `GET /api/context/files` tree — one top-level group per entity kind, skipping any group that ends up with no readable files rather than emitting an empty section. */
+export declare function buildContextFileTree(projectDir: string, contextShow: WrenContextShow): ContextFileNode[];

package/dist-server/server/context-files.js

@@ -0,0 +1,117 @@
+/**
+ * Builds the Context page's file tree by reading the
+ * REAL bound project directory (model/cube/knowledge files, relationships.yml,
+ * wren_project.yml) rather than a seeded fixture. Each leaf's `content` is the
+ * actual file text on disk, so `FileViewer.tsx` renders real project source.
+ *
+ * Model/relationship/cube NAMES come from an already-loaded
+ * `WrenContextShow` (see `server/context-source.ts`) rather than re-parsing
+ * YAML here — `wren context show` is the authoritative parse of that data;
+ * this module only needs it to know which per-entity files exist and how to
+ * label them, then reads each file's raw bytes straight from disk.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+function readFileSafe(filePath) {
+    try {
+        return readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function buildModelNodes(projectDir, contextShow) {
+    return contextShow.models.flatMap((model) => {
+        const relPath = path.join("models", model.name, "metadata.yml");
+        const content = readFileSafe(path.join(projectDir, relPath));
+        if (content === undefined)
+            return [];
+        return [{ key: `file-model-${model.name}`, title: `${model.name}/metadata.yml`, kind: "model", path: relPath, entityKey: model.name, content }];
+    });
+}
+/** `relationships.yml` is a single file holding every relationship — one leaf per relationship, all sharing that same real file text, distinguished by `entityKey`. */
+function buildRelationshipNodes(projectDir, contextShow) {
+    const relPath = "relationships.yml";
+    const content = readFileSafe(path.join(projectDir, relPath));
+    if (content === undefined)
+        return [];
+    return contextShow.relationships.map((rel) => ({
+        key: `file-relationship-${rel.name}`,
+        title: rel.name,
+        kind: "relationship",
+        path: relPath,
+        entityKey: rel.name,
+        content,
+    }));
+}
+function buildCubeNodes(projectDir, contextShow) {
+    return contextShow.cubes.flatMap((cube) => {
+        const relPath = path.join("cubes", cube.name, "metadata.yml");
+        const content = readFileSafe(path.join(projectDir, relPath));
+        if (content === undefined)
+            return [];
+        return [{ key: `file-cube-${cube.name}`, title: `${cube.name}/metadata.yml`, kind: "cube", path: relPath, entityKey: cube.name, content }];
+    });
+}
+/** `knowledge/rules/*.md` are the only knowledge files with real authored content today (`caveats/`, `glossary/`, `metrics/`, `sql/` are placeholders) — plus `knowledge/knowledge.yml` when present. */
+function buildKnowledgeNodes(projectDir) {
+    const rulesDir = path.join(projectDir, "knowledge", "rules");
+    const nodes = [];
+    if (existsSync(rulesDir)) {
+        const entries = readdirSync(rulesDir)
+            .filter((name) => name.endsWith(".md"))
+            .sort();
+        for (const name of entries) {
+            const content = readFileSafe(path.join(rulesDir, name));
+            if (content === undefined)
+                continue;
+            const relPath = path.join("knowledge", "rules", name);
+            const entityKey = name.replace(/\.md$/, "");
+            nodes.push({ key: `file-knowledge-rule-${entityKey}`, title: name, kind: "knowledge", path: relPath, entityKey, content });
+        }
+    }
+    const knowledgeYamlPath = path.join(projectDir, "knowledge", "knowledge.yml");
+    const knowledgeYamlContent = readFileSafe(knowledgeYamlPath);
+    if (knowledgeYamlContent !== undefined) {
+        nodes.push({ key: "file-knowledge-config", title: "knowledge.yml", kind: "knowledge", path: path.join("knowledge", "knowledge.yml"), entityKey: "knowledge-config", content: knowledgeYamlContent });
+    }
+    return nodes;
+}
+function buildProjectNode(projectDir) {
+    const content = readFileSafe(path.join(projectDir, "wren_project.yml"));
+    if (content === undefined)
+        return [];
+    return [{ key: "file-wren-project", title: "wren_project.yml", path: "wren_project.yml", content }];
+}
+/**
+ * `instructionsPresent` from the real presence of at least one authored
+ * `knowledge/rules/*.md` file (as opposed to the placeholder-only
+ * subdirectories, e.g. `caveats/`/`glossary/`). `verifiedPairCount` is always
+ * 0 — there is no live Q-SQL verified-pair source over a real project yet
+ * (see `server/impact.ts`'s doc comment).
+ */
+export function computeKnowledgeStatus(projectDir) {
+    const rulesDir = path.join(projectDir, "knowledge", "rules");
+    const instructionsPresent = existsSync(rulesDir) && readdirSync(rulesDir).some((name) => name.endsWith(".md"));
+    return { instructionsPresent, verifiedPairCount: 0 };
+}
+/** Builds the whole `GET /api/context/files` tree — one top-level group per entity kind, skipping any group that ends up with no readable files rather than emitting an empty section. */
+export function buildContextFileTree(projectDir, contextShow) {
+    const groups = [];
+    const models = buildModelNodes(projectDir, contextShow);
+    if (models.length > 0)
+        groups.push({ key: "models", title: "Models", children: models });
+    const relationships = buildRelationshipNodes(projectDir, contextShow);
+    if (relationships.length > 0)
+        groups.push({ key: "relationships", title: "Relationships", children: relationships });
+    const cubes = buildCubeNodes(projectDir, contextShow);
+    if (cubes.length > 0)
+        groups.push({ key: "cubes", title: "Cubes", children: cubes });
+    const knowledge = buildKnowledgeNodes(projectDir);
+    if (knowledge.length > 0)
+        groups.push({ key: "knowledge", title: "Knowledge", children: knowledge });
+    const project = buildProjectNode(projectDir);
+    if (project.length > 0)
+        groups.push({ key: "project", title: "Project", children: project });
+    return groups;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Pure remap from `wren context show`'s output
+ * (`server/context-source.ts`) to the frozen UI wire contract
+ * (`server/wire-types.ts`). No I/O here; `server/app.ts`'s context routes are
+ * the only caller.
+ *
+ * `wren context show` carries no `key: pk/fk` on columns, no additivity flag
+ * on measures, and no ER layout positions — those are inferred/omitted
+ * heuristics, not authoritative facts from the semantic layer. Keep the
+ * inference simple and readable rather than over-fitting to one project's
+ * naming.
+ */
+import type { WrenContextCube, WrenContextModel, WrenContextRelationship, WrenContextShow } from "./context-source.js";
+import type { ContextOverview, KnowledgeStatus, MeasureAdditivity, SemanticMeasure, SemanticModel, SemanticRelationship } from "./wire-types.js";
+/** Maps `models[]` to `SemanticModel[]`, omitting `position` (no ER layout in `wren context show` — the UI's `ErDiagram` must lay itself out when position is absent). */
+export declare function mapModelsToWire(models: readonly WrenContextModel[], relationships: readonly WrenContextRelationship[]): SemanticModel[];
+/** Maps `relationships[]` (unordered `models:[a,b]` pair) to `SemanticRelationship[]` (`fromModel`/`toModel`). The wire type has no slot for the raw `condition` predicate — it's only consumed internally for fk inference above. */
+export declare function mapRelationshipsToWire(relationships: readonly WrenContextRelationship[]): SemanticRelationship[];
+/**
+ * `SUM`/`COUNT` aggregates are additive (safely re-summable across any
+ * dimension) — UNLESS the expression is itself a ratio of two such
+ * aggregates (e.g. `"SUM(revenue) / SUM(cost)"`), which is never additive
+ * regardless of what its parts are made of. `AVG` and anything else default
+ * to non-additive — the safer assumption when additivity can't be confirmed
+ * from the expression text alone.
+ */
+export declare function inferAdditivity(expression: string): MeasureAdditivity;
+/** Maps `cubes[]` to `SemanticMeasure[]` — one entry per measure (a cube can declare several), keyed `"<cube>.<measure>"` so measures with the same name in different cubes don't collide. */
+export declare function mapCubesToMeasures(cubes: readonly WrenContextCube[]): SemanticMeasure[];
+export declare function mapContextShowToOverview(contextShow: WrenContextShow, projectName: string, projectPath: string, knowledge: KnowledgeStatus): ContextOverview;

package/dist-server/server/context-map.js

@@ -0,0 +1,95 @@
+const JOIN_TYPE_MAP = {
+    ONE_TO_ONE: "one-to-one",
+    ONE_TO_MANY: "one-to-many",
+    MANY_TO_ONE: "many-to-one",
+    MANY_TO_MANY: "many-to-many",
+};
+/** `wren`'s `joinType` is an upper-snake enum (`"MANY_TO_ONE"`, ...) — falls back to `"one-to-many"` for anything unrecognized rather than throwing, since this is display-only. */
+function mapJoinType(joinType) {
+    return JOIN_TYPE_MAP[joinType] ?? "one-to-many";
+}
+/**
+ * A column is inferred `pk` when it matches the model's declared
+ * `primaryKey`, or `fk` when some relationship's `condition` string
+ * references `<model.name>.<column.name>` on either side of the join
+ * predicate (e.g. `"orders.customer_id = customers.id"` marks
+ * `orders.customer_id` as an fk). Both are heuristics over plain-text data —
+ * not something `wren context show` asserts directly.
+ */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function inferColumnKey(modelName, columnName, primaryKey, relationships) {
+    if (primaryKey !== undefined && columnName === primaryKey)
+        return "pk";
+    // Match `<model>.<column>` as a whole identifier reference, not a loose
+    // substring: the boundaries stop a model whose name is a suffix of another
+    // (e.g. `old_customer.id` must NOT satisfy a lookup for `customer.id`) or a
+    // column that is a prefix of another (`id` vs `identifier`) from matching.
+    const ref = new RegExp(`(?<![A-Za-z0-9_])${escapeRegExp(modelName)}\\.${escapeRegExp(columnName)}(?![A-Za-z0-9_])`);
+    if (relationships.some((rel) => ref.test(rel.condition)))
+        return "fk";
+    return undefined;
+}
+/** Maps `models[]` to `SemanticModel[]`, omitting `position` (no ER layout in `wren context show` — the UI's `ErDiagram` must lay itself out when position is absent). */
+export function mapModelsToWire(models, relationships) {
+    return models.map((model) => {
+        const columns = model.columns.map((col) => {
+            const key = inferColumnKey(model.name, col.name, model.primaryKey, relationships);
+            return key !== undefined ? { name: col.name, type: col.type, key } : { name: col.name, type: col.type };
+        });
+        return { key: model.name, name: model.name, columns };
+    });
+}
+/** Maps `relationships[]` (unordered `models:[a,b]` pair) to `SemanticRelationship[]` (`fromModel`/`toModel`). The wire type has no slot for the raw `condition` predicate — it's only consumed internally for fk inference above. */
+export function mapRelationshipsToWire(relationships) {
+    return relationships.map((rel) => ({
+        key: rel.name,
+        name: rel.name,
+        fromModel: rel.models[0],
+        toModel: rel.models[1],
+        type: mapJoinType(rel.joinType),
+    }));
+}
+/**
+ * `SUM`/`COUNT` aggregates are additive (safely re-summable across any
+ * dimension) — UNLESS the expression is itself a ratio of two such
+ * aggregates (e.g. `"SUM(revenue) / SUM(cost)"`), which is never additive
+ * regardless of what its parts are made of. `AVG` and anything else default
+ * to non-additive — the safer assumption when additivity can't be confirmed
+ * from the expression text alone.
+ */
+export function inferAdditivity(expression) {
+    const trimmedUpper = expression.trim().toUpperCase();
+    if (trimmedUpper.includes("/"))
+        return "non-additive";
+    if (/^(SUM|COUNT)\s*\(/.test(trimmedUpper))
+        return "additive";
+    return "non-additive";
+}
+/** Maps `cubes[]` to `SemanticMeasure[]` — one entry per measure (a cube can declare several), keyed `"<cube>.<measure>"` so measures with the same name in different cubes don't collide. */
+export function mapCubesToMeasures(cubes) {
+    const measures = [];
+    for (const cube of cubes) {
+        for (const measure of cube.measures) {
+            measures.push({
+                key: `${cube.name}.${measure.name}`,
+                name: measure.name,
+                baseModel: cube.baseObject,
+                expression: measure.expression,
+                additivity: inferAdditivity(measure.expression),
+            });
+        }
+    }
+    return measures;
+}
+export function mapContextShowToOverview(contextShow, projectName, projectPath, knowledge) {
+    return {
+        models: mapModelsToWire(contextShow.models, contextShow.relationships),
+        relationships: mapRelationshipsToWire(contextShow.relationships),
+        measures: mapCubesToMeasures(contextShow.cubes),
+        knowledge,
+        projectName,
+        projectPath,
+    };
+}

package/dist-server/server/context-source.d.ts

@@ -0,0 +1,68 @@
+export interface WrenContextColumn {
+    readonly name: string;
+    readonly type: string;
+    readonly properties?: {
+        readonly description?: string;
+    };
+}
+export interface WrenContextModel {
+    readonly name: string;
+    readonly properties?: {
+        readonly description?: string;
+    };
+    readonly tableReference?: unknown;
+    readonly primaryKey?: string;
+    readonly columns: readonly WrenContextColumn[];
+}
+/** `models` is an unordered pair — `condition` is the raw join predicate, e.g. `"orders.customer_id = customers.id"`. */
+export interface WrenContextRelationship {
+    readonly name: string;
+    readonly models: readonly [string, string];
+    readonly joinType: string;
+    readonly condition: string;
+}
+export interface WrenContextMeasure {
+    readonly name: string;
+    readonly expression: string;
+    readonly type?: string;
+}
+export interface WrenContextCube {
+    readonly name: string;
+    readonly baseObject: string;
+    readonly measures: readonly WrenContextMeasure[];
+    readonly dimensions?: readonly unknown[];
+    readonly timeDimensions?: readonly unknown[];
+    readonly properties?: Record<string, unknown>;
+}
+/** The full `wren context show -o json` document — a single JSON object, NOT JSONL (unlike `wren -o json` query output). */
+export interface WrenContextShow {
+    readonly catalog?: string;
+    readonly schema?: string;
+    readonly models: readonly WrenContextModel[];
+    readonly relationships: readonly WrenContextRelationship[];
+    readonly views?: readonly unknown[];
+    readonly cubes: readonly WrenContextCube[];
+    readonly dataSource?: string;
+    readonly layoutVersion?: number;
+}
+export declare class WrenBinaryNotFoundError extends Error {
+    constructor(detail: string);
+}
+/** Covers both "project not built yet" (missing `target/mdl.json`, checked up front) and a non-zero/unparseable `wren context show` run. */
+export declare class WrenContextShowError extends Error {
+    constructor(detail: string);
+}
+/** Evicts one cached project (or every entry, when called with no argument) — call after a context-changing operation (e.g. a setup "build context" turn). */
+export declare function invalidateContextShowCache(projectDir?: string): void;
+/**
+ * Runs `wren context show -o json` in `projectDir` and parses the single
+ * resulting JSON object. Throws {@link WrenBinaryNotFoundError} when `wren`
+ * isn't on PATH, or {@link WrenContextShowError} when the project hasn't
+ * been built (`target/mdl.json` missing — checked up front so the error names
+ * the real cause instead of a generic non-zero exit), the process exits
+ * non-zero, or stdout isn't valid JSON. Never auto-builds and never falls
+ * back to fabricated data.
+ */
+export declare function loadContextShow(projectDir: string, options?: {
+    readonly useCache?: boolean;
+}): Promise<WrenContextShow>;