@graphit/cli 0.2.320 → 0.2.322

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Graphit CLI plugin for AI coding assistants",
-    "version": "0.2.320"
+    "version": "0.2.322"
   },
   "plugins": [
     {
@@ -16,9 +16,9 @@
       "source": {
         "source": "npm",
         "package": "@graphit/cli",
-        "version": "0.2.320"
+        "version": "0.2.322"
       },
-      "version": "0.2.320",
+      "version": "0.2.322",
       "category": "data-visualization",
       "tags": [
         "bi",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "graphit",
-  "version": "0.2.320",
+  "version": "0.2.322",
   "description": "Build custom HTML dashboards from real data using the Graphit CLI. KB-aware queries, entity wrapping, cached data sources.",
   "author": {
     "name": "Graphit",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "graphit",
-  "version": "0.2.320",
+  "version": "0.2.322",
   "description": "Build custom HTML dashboards from real data using the Graphit CLI. KB-aware queries, entity wrapping, cached data sources.",
   "author": {
     "name": "Graphit",

package/bin/graphit

@@ -14,7 +14,7 @@ if [ -z "${GRAPHIT_PLUGIN_ROOT:-}" ]; then
 fi
 
 # graphit:floor (stamped by scripts/sync-plugin-version.mjs from cli/package.json)
-FLOOR_VERSION="0.2.320"
+FLOOR_VERSION="0.2.322"
 
 PACKAGE_NAME="@graphit/cli"
 # Strict semver: anything else is rejected so a tampered cache cannot inject.

package/bin/graphit.ps1

@@ -7,7 +7,7 @@ if (-not $env:GRAPHIT_PLUGIN_ROOT) {
 }
 
 # graphit:floor (stamped by scripts/sync-plugin-version.mjs from cli/package.json)
-$FloorVersion = "0.2.320"
+$FloorVersion = "0.2.322"
 
 $PackageName = "@graphit/cli"
 # Strict semver: anything else is rejected so a tampered cache cannot inject.

package/dist/commands/sl/index.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerSlCommands(program: Command): void;

package/dist/commands/sl/index.js

@@ -0,0 +1,263 @@
+import { readFileSync } from "node:fs";
+import { apiClient } from "../../api/client.js";
+import { errorOutput } from "../../output/format.js";
+import { writeStderr } from "../../stderr.js";
+// The dbt-native semantic-layer command tree (dormant preview).
+//
+// GATED: registered only when GRAPHIT_SL=1 (see src/index.ts). This file lives
+// in a SUBDIRECTORY of commands/ deliberately - the SKILL.md/tool-manifest
+// generators walk only top-level dist/commands/*.js registrars, so nothing
+// here can reach the published skill, the verb-policy manifest, or the in-app
+// agent surface until the cutover promotes it. At cutover this tree replaces
+// the legacy `kb` group (same verbs, `kb` group name), the gate drops, a
+// top-level registrar makes the walk see it, verb-policy rows + skill
+// references land, and gen:commands regenerates - the full CLI change
+// checklist runs THEN, against commands users can actually run.
+//
+// The noun set mirrors the backend's typed descriptors: semantic-model,
+// metric, group. Nested entities/dimensions/measures mutate through
+// `update semantic-model` (a provided list replaces the stored list whole)
+// and are independently readable (`sl entity`, `sl get semantic-model`).
+const NOUNS = ["semantic-model", "metric", "group"];
+const ARG_NOUN = "Semantic-layer noun - semantic-model, metric or group";
+const ARG_NAME = "Asset name (lowercase snake_case), as returned by sl list or sl search";
+function requireNoun(noun) {
+    if (!NOUNS.includes(noun)) {
+        writeStderr(JSON.stringify({
+            error: `Unknown noun '${noun}'. Valid: ${NOUNS.join(", ")}`,
+        }));
+        process.exit(1);
+    }
+    return noun;
+}
+function payloadFromOpts(opts) {
+    if (!opts.file && !opts.json) {
+        writeStderr(JSON.stringify({ error: "Provide the definition via --file <path> or --json <string>" }));
+        process.exit(1);
+    }
+    if (opts.file && opts.json) {
+        writeStderr(JSON.stringify({ error: "--file and --json are mutually exclusive" }));
+        process.exit(1);
+    }
+    const raw = opts.file ? readFileSync(opts.file, "utf-8") : opts.json;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        writeStderr(JSON.stringify({ error: "Definition is not valid JSON" }));
+        process.exit(1);
+    }
+}
+function parseAxes(pairs) {
+    const axes = {};
+    for (const pair of pairs ?? []) {
+        const eq = pair.indexOf("=");
+        if (eq <= 0) {
+            writeStderr(JSON.stringify({ error: `--axis '${pair}' must be key=value` }));
+            process.exit(1);
+        }
+        axes[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    return axes;
+}
+export function registerSlCommands(program) {
+    const sl = program
+        .command("sl")
+        .description("Semantic layer (dbt-native Knowledge Base) - semantic models, metrics, groups");
+    // -- create ---------------------------------------------------------------
+    const create = sl.command("create").description("Create semantic-layer assets");
+    create
+        .command("semantic-model")
+        .description("Create a semantic model from a JSON definition (dbt shape: name, model, " +
+        "entities, dimensions, measures, defaults, group)")
+        .option("--file <path>", "Path to a JSON definition file")
+        .option("--json <string>", "Inline JSON definition")
+        .option("--unverified", "Create as draft instead of verified")
+        .action(async function () {
+        try {
+            const opts = this.opts();
+            const body = {
+                definition: payloadFromOpts(opts),
+                unverified: opts.unverified === true,
+            };
+            console.log(JSON.stringify(await apiClient.post("/api/v1/cli/sl/semantic-model", body)));
+        }
+        catch (err) {
+            errorOutput(err);
+        }
+    });
+    create
+        .command("metric")
+        .description("Create a metric from a JSON definition (type: simple, ratio, derived, " +
+        "cumulative or conversion, with type_params). --family/--axis tag a " +
+        "concrete member of a metric family")
+        .option("--file <path>", "Path to a JSON definition file")
+        .option("--json <string>", "Inline JSON definition")
+        .option("--family <name>", "Metric family this variant belongs to")
+        .option("--axis <key=value...>", "Axis value that generated this variant (repeatable)")
+        .option("--unverified", "Create as draft instead of verified")
+        .action(async function () {
+        try {
+            const opts = this.opts();
+            const definition = payloadFromOpts(opts);
+            if (opts.family) {
+                const meta = (definition.meta ??= {});
+                const graphit = (meta.graphit ??=
+                    {});
+                graphit.family ??= opts.family;
+                const axes = parseAxes(opts.axis);
+                if (Object.keys(axes).length > 0)
+                    graphit.axes ??= axes;
+            }
+            const body = { definition, unverified: opts.unverified === true };
+            console.log(JSON.stringify(await apiClient.post("/api/v1/cli/sl/metric", body)));
+        }
+        catch (err) {
+            errorOutput(err);
+        }
+    });
+    create
+        .command("group")
+        .description("Create a group (the domain analogue; admin only)")
+        .requiredOption("--name <name>", "Group name (lowercase snake_case)")
+        .option("--description <text>", "Group description")
+        .option("--owner-email <email>", "Owning analyst's email")
+        .option("--access <level>", "dbt group access level: private, protected or public")
+        .action(async function () {
+        try {
+            const opts = this.opts();
+            const definition = { name: opts.name };
+            if (opts.description)
+                definition.description = opts.description;
+            if (opts.ownerEmail)
+                definition.owner_email = opts.ownerEmail;
+            if (opts.access)
+                definition.access = opts.access;
+            console.log(JSON.stringify(await apiClient.post("/api/v1/cli/sl/group", { definition })));
+        }
+        catch (err) {
+            errorOutput(err);
+        }
+    });
+    // -- update ---------------------------------------------------------------
+    sl.command("update")
+        .argument("<noun>", ARG_NOUN)
+        .argument("<name>", ARG_NAME)
+        .description("Update an asset with a JSON patch. On semantic-model, a provided " +
+        "entities/dimensions/measures list replaces the stored list whole")
+        .option("--file <path>", "Path to a JSON patch file")
+        .option("--json <string>", "Inline JSON patch")
+        .action(async function (noun, name) {
+        try {
+            requireNoun(noun);
+            const body = { patch: payloadFromOpts(this.opts()) };
+            console.log(JSON.stringify(await apiClient.put(`/api/v1/cli/sl/${noun}/${encodeURIComponent(name)}`, body)));
+        }
+        catch (err) {
+            errorOutput(err);
+        }
+    });
+    // -- delete ---------------------------------------------------------------
+    sl.command("delete")
+        .argument("<noun>", ARG_NOUN)
+        .argument("<name>", ARG_NAME)
+        .description("Delete an asset (requires --yes). Refused while other definitions " +
+        "still reference it")
+        .requiredOption("--yes", "Confirm deletion")
+        .action(async function (noun, name) {
+        try {
+            requireNoun(noun);
+            await apiClient.delete(`/api/v1/cli/sl/${noun}/${encodeURIComponent(name)}`);
+            console.log(JSON.stringify({ status: "deleted", noun, name }));
+        }
+        catch (err) {
+            errorOutput(err);
+        }
+    });
+    // -- reads ----------------------------------------------------------------
+    sl.command("get")
+        .argument("<noun>", ARG_NOUN)
+        .argument("<name>", ARG_NAME)
+        .description("Fetch one asset. Metrics include their family and sibling variants")
+        .action(async function (noun, name) {
+        try {
+            requireNoun(noun);
+            console.log(JSON.stringify(await apiClient.get(`/api/v1/cli/sl/${noun}/${encodeURIComponent(name)}`)));
+        }
+        catch (err) {
+            errorOutput(err);
+        }
+    });
+    sl.command("list")
+        .argument("<noun>", ARG_NOUN)
+        .description("List all visible assets of one noun")
+        .action(async function (noun) {
+        try {
+            requireNoun(noun);
+            console.log(JSON.stringify(await apiClient.get(`/api/v1/cli/sl/${noun}`)));
+        }
+        catch (err) {
+            errorOutput(err);
+        }
+    });
+    sl.command("tree")
+        .description("The whole visible semantic layer: group -> semantic model -> assets, " +
+        "metric families collapsed to one card each")
+        .action(async function () {
+        try {
+            console.log(JSON.stringify(await apiClient.get("/api/v1/cli/sl/tree")));
+        }
+        catch (err) {
+            errorOutput(err);
+        }
+    });
+    sl.command("search")
+        .argument("<query>", "Search text (name or description)")
+        .description("Search semantic models, metrics, groups and nested components")
+        .option("--limit <n>", "Maximum results (default 50)")
+        .action(async function (query) {
+        try {
+            const rawLimit = this.opts().limit;
+            if (rawLimit !== undefined && !/^[1-9]\d*$/.test(rawLimit)) {
+                writeStderr(JSON.stringify({ error: `--limit '${rawLimit}' must be a positive integer` }));
+                process.exit(1);
+            }
+            const limit = rawLimit ? `&limit=${rawLimit}` : "";
+            console.log(JSON.stringify(await apiClient.get(`/api/v1/cli/sl/search?q=${encodeURIComponent(query)}${limit}`)));
+        }
+        catch (err) {
+            errorOutput(err);
+        }
+    });
+    sl.command("entity")
+        .argument("<name>", "Entity name (as declared inside semantic models)")
+        .description("One entity across every visible semantic model that declares it")
+        .action(async function (name) {
+        try {
+            console.log(JSON.stringify(await apiClient.get(`/api/v1/cli/sl/entity/${encodeURIComponent(name)}`)));
+        }
+        catch (err) {
+            errorOutput(err);
+        }
+    });
+    sl.command("family")
+        .argument("<family>", "Metric family name")
+        .description("Expand a metric family; with --axis constraints, resolve to the one " +
+        "concrete member (ambiguity answers with the still-open axes)")
+        .option("--axis <key=value...>", "Axis constraint to resolve against (repeatable)")
+        .action(async function (family) {
+        try {
+            const axes = parseAxes(this.opts().axis);
+            const entries = Object.entries(axes);
+            const encoded = encodeURIComponent(family);
+            const path = entries.length > 0
+                ? `/api/v1/cli/sl/family/${encoded}/resolve?axes=${encodeURIComponent(entries.map(([k, v]) => `${k}=${v}`).join(","))}`
+                : `/api/v1/cli/sl/family/${encoded}`;
+            console.log(JSON.stringify(await apiClient.get(path)));
+        }
+        catch (err) {
+            errorOutput(err);
+        }
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/sl/index.js.map

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

package/dist/index.js

@@ -7,6 +7,7 @@ import { Command } from "commander";
 import { registerAuthCommands } from "./commands/auth.js";
 import { registerStatusCommand } from "./commands/status.js";
 import { registerKBCommands } from "./commands/kb.js";
+import { registerSlCommands } from "./commands/sl/index.js";
 import { registerQueryCommands } from "./commands/query.js";
 import { registerDSCommands } from "./commands/ds.js";
 import { registerDashboardCommands } from "./commands/dashboard.js";
@@ -30,6 +31,13 @@ program
 registerAuthCommands(program);
 registerStatusCommand(program);
 registerKBCommands(program);
+// Dormant semantic-layer preview: the registrar lives in a commands/
+// SUBDIRECTORY (the doc/manifest walk scans only top-level registrars), so
+// this gate controls the runtime surface while the generated artifacts stay
+// stable by construction. The cutover ungates it as the kb replacement.
+if (process.env.GRAPHIT_SL === "1") {
+    registerSlCommands(program);
+}
 registerQueryCommands(program);
 registerDSCommands(program);
 registerDashboardCommands(program);

package/dist/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphit/cli",
-  "version": "0.2.320",
+  "version": "0.2.322",
   "description": "Graphit CLI - Build custom dashboards from any AI coding assistant",
   "repository": {
     "type": "git",

package/skills/graphit/SKILL.md

@@ -2,7 +2,7 @@
 name: graphit
 description: >-
   Use Graphit for ANY question about the user's business or product data: metrics, KPIs, revenue, retention, spend, users, cohorts, funnels, trends, comparisons, "why did X change", "how are we doing on Y", analysis, reports, or dashboards. Activate even when the user does not say "Graphit" or name any tool: if someone wants to understand their numbers, this is the tool. Graphit answers through a governed semantic layer (computed the team's way, reusable and safe to share) and delivers the answer as a fast cached-data query or a hand-authored interactive HTML dashboard, and can create the metrics, dimensions, and rules an answer needs. Prefer Graphit over hand-rolled one-off analysis whenever the data is, or could be, the user's business data. Skip only for pure software tasks (code, logs, config, infra) or data with nothing to do with the user's business.
-skill_version: "0.2.320"
+skill_version: "0.2.322"
 ---
 
 <!-- SIZE EXEMPTION (SKILL.md): standard hard limit 12,288 chars, exempted ceiling 31,872. Always-loaded: the collaboration/pace spine, hard constraints + scope gate, the loop, and the generated command table (COMMANDS markers, scripts/generate-commands-doc.mjs) - needed every turn, cannot defer to a reference. Marker sits after the frontmatter so the loader and sync-plugin-version.mjs parse it. Reviewed 2026-08-02. Raised from 29,952 on 2026-08-07 (founder-directed): a domain is now an access boundary, so loop step 2 must say that picking one decides who ever sees the work - load-bearing before any reference load can be relied on. Raised from 30,592 on 2026-08-13 (founder-directed): the living-context MUST bullet - explore placements answer path + pre-create fork. SIZING.md rules raises pay only for command-table growth; both raises are deliberate exceptions. Raised from 31,232 on 2026-08-16: the generated table gained `dashboard check` and its flags - table growth, the sanctioned kind - plus that verb's one router row. -->
@@ -157,7 +157,7 @@ Read the one that matches what you are doing now. Do not preload them. Exact com
 
 ## Commands
 
-Graphit is one CLI, but how you invoke it depends on your environment. On Claude Code the plugin provides a `graphit` wrapper, so `graphit <command>` runs the current CLI. On Codex, Cursor, a terminal, or CI there is no `graphit` wrapper - invoke the CLI explicitly with `npx -y @graphit/cli@0.2.320 <command>` (a stamped version, kept current by the build; pin an exact version for a reproducible run). The table below is generated from the CLI itself. For exact flags, run `graphit <command> --help` - never guess a flag.
+Graphit is one CLI, but how you invoke it depends on your environment. On Claude Code the plugin provides a `graphit` wrapper, so `graphit <command>` runs the current CLI. On Codex, Cursor, a terminal, or CI there is no `graphit` wrapper - invoke the CLI explicitly with `npx -y @graphit/cli@0.2.322 <command>` (a stamped version, kept current by the build; pin an exact version for a reproducible run). The table below is generated from the CLI itself. For exact flags, run `graphit <command> --help` - never guess a flag.
 
 <!-- COMMANDS:START -->
 

package/skills/graphit/VERSION.json

@@ -1,5 +1,5 @@
 {
   "package": "@graphit/cli",
-  "version": "0.2.320",
+  "version": "0.2.322",
   "source": "cli/package.json"
 }

package/skills/graphit/references/table.md

@@ -17,3 +17,27 @@ graphit.table('#detail-table', {
 ```
 
 `columns` entries are row keys, not display configs - there is no rename mapping. For readable headers, alias in SQL with quoted identifiers (`SELECT SUM(CREDIT_USED) AS "Total Credits"`) so the key itself is the display name, and use the same key in `columnFormats`. Columns without a `columnFormats` entry render raw. Percent values follow the non-scaling rule: multiply 0-1 ratios by 100 in SQL first.
+
+## Downloads: declare the columns a hand-rolled table shows
+
+The entity kebab menu offers Download CSV / Excel. It re-runs the entity's recorded query and serializes **every column that query returned**, which is correct for rows (the runtime caps rows after the query, so the file is deliberately fuller than the screen) and wrong for columns whenever the table shows fewer than it fetches.
+
+That gap is easy to create on purpose. A table with a column picker usually fetches a wide catalogue once so adding a column is instant with no re-query, and a table with rich tooltips may fetch helper columns (a ratio's numerator and denominator, a rank used only for ordering) that are never a visible column at all. One production dashboard fetched 235 columns to render 12; 136 of them existed only to feed a hover tooltip. Every one of them landed in the user's file.
+
+**`graphit.table` is not exempt.** Its `columns` list selects a subset, and rows are often reshaped or renamed in JS before being handed over, so the file can carry both extra columns and the raw SQL aliases (`active_players`) where the table shows the display names (`Active Players`). Declare whenever the table's `columns` differ from what the query returned, for either reason. A table that renders every column its query returned, under those names, needs nothing.
+
+```js
+// call it wherever you build the header row, with the SAME list, in the same order
+if (graphit.exportColumns) {
+  graphit.exportColumns('summary-table', [
+    { key: 'rowkey', label: 'Install Day' },      // row-label columns first
+    ...visibleCols.map(c => ({ key: c.key, label: c.label })),
+  ])
+}
+```
+
+- **Call it from the render path, not from setup.** The single function every consumer already goes through (headers, cells, totals) is the right place, because then the file cannot drift from the table. Calling it once at load leaves the declaration stale the moment the user hides a column.
+- **`label` becomes the file's header text**, so pass what the user is looking at, not the SQL alias. If a column renders as a percentage while the exported value is the raw count, name it for the value in the file, not the one on screen.
+- **Add the row-label columns yourself.** A visible-column list usually holds measure columns only, while the row label is rendered separately, so it has to be prepended or the file loses its key column.
+- **Guard with `if (graphit.exportColumns)`.** On an older platform build the call throws, and a throw inside a render function takes the whole table down with it.
+- **Declaring nothing is fine and is the default.** No declaration means the download is unchanged, which is right for any table whose query already matches what it shows. A declared key the query did not return is dropped, never invented, and a declaration matching nothing falls back to the full result rather than producing an empty file.