@graphit/cli 0.2.107 → 0.2.113

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -7,7 +7,7 @@
7
7
  },
8
8
  "metadata": {
9
9
  "description": "Graphit CLI plugin for AI coding assistants",
10
- "version": "0.2.107"
10
+ "version": "0.2.113"
11
11
  },
12
12
  "plugins": [
13
13
  {
@@ -16,9 +16,9 @@
16
16
  "source": {
17
17
  "source": "npm",
18
18
  "package": "@graphit/cli",
19
- "version": "0.2.107"
19
+ "version": "0.2.113"
20
20
  },
21
- "version": "0.2.107",
21
+ "version": "0.2.113",
22
22
  "category": "data-visualization",
23
23
  "tags": [
24
24
  "bi",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "graphit",
3
- "version": "0.2.107",
3
+ "version": "0.2.113",
4
4
  "description": "Build custom HTML dashboards from real data using the Graphit CLI. KB-aware queries, entity wrapping, cached data sources.",
5
5
  "author": {
6
6
  "name": "Graphit",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "graphit",
3
- "version": "0.2.107",
3
+ "version": "0.2.113",
4
4
  "description": "Build custom HTML dashboards from real data using the Graphit CLI. KB-aware queries, entity wrapping, cached data sources.",
5
5
  "author": {
6
6
  "name": "Graphit",
package/bin/graphit CHANGED
@@ -14,7 +14,7 @@ if [ -z "${GRAPHIT_PLUGIN_ROOT:-}" ]; then
14
14
  fi
15
15
 
16
16
  # graphit:floor (stamped by scripts/sync-plugin-version.mjs from cli/package.json)
17
- FLOOR_VERSION="0.2.107"
17
+ FLOOR_VERSION="0.2.113"
18
18
 
19
19
  PACKAGE_NAME="@graphit/cli"
20
20
  # Strict semver: anything else is rejected so a tampered cache cannot inject.
package/bin/graphit.ps1 CHANGED
@@ -7,7 +7,7 @@ if (-not $env:GRAPHIT_PLUGIN_ROOT) {
7
7
  }
8
8
 
9
9
  # graphit:floor (stamped by scripts/sync-plugin-version.mjs from cli/package.json)
10
- $FloorVersion = "0.2.107"
10
+ $FloorVersion = "0.2.113"
11
11
 
12
12
  $PackageName = "@graphit/cli"
13
13
  # Strict semver: anything else is rejected so a tampered cache cannot inject.
@@ -28,9 +28,10 @@ export function registerConnectorCommands(program) {
28
28
  .requiredOption("--account <account>", "Snowflake account identifier")
29
29
  .requiredOption("--user <user>", "Snowflake username")
30
30
  .requiredOption("--key <path>", "Path to private key file (.p8)")
31
- .option("--warehouse <wh>", "Default warehouse")
32
- .option("--role <role>", "Default role")
33
- .option("--database <db>", "Default database")
31
+ .option("--name <name>", 'Connection name (defaults to "Snowflake (<account>)")')
32
+ .requiredOption("--warehouse <wh>", "Default warehouse")
33
+ .requiredOption("--role <role>", "Default role")
34
+ .requiredOption("--database <db>", "Default database")
34
35
  .action(async function () {
35
36
  try {
36
37
  const opts = this.opts();
@@ -44,6 +45,7 @@ export function registerConnectorCommands(program) {
44
45
  account: opts.account,
45
46
  user: opts.user,
46
47
  private_key_pem: keyPem,
48
+ name: opts.name || null,
47
49
  warehouse: opts.warehouse || null,
48
50
  role: opts.role || null,
49
51
  database: opts.database || null,
@@ -1 +1 @@
1
- {"version":3,"file":"connector.js","sourceRoot":"","sources":["../../src/commands/connector.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"connector.js","sourceRoot":"","sources":["../../src/commands/connector.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@graphit/cli",
3
- "version": "0.2.107",
3
+ "version": "0.2.113",
4
4
  "description": "Graphit CLI - Build custom dashboards from any AI coding assistant",
5
5
  "repository": {
6
6
  "type": "git",
@@ -2,10 +2,10 @@
2
2
  name: graphit
3
3
  description: >-
4
4
  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.
5
- skill_version: "0.2.107"
5
+ skill_version: "0.2.113"
6
6
  ---
7
7
 
8
- <!-- SIZE EXEMPTION (SKILL.md): standard hard limit 12,288 chars, exempted ceiling 27,648. This router always-loads the collaboration/pace spine (brainstorm, ask-user, present-result, plan-next), the hard constraints + scope gate, the investigation loop, and the generated command table (between the COMMANDS markers, written by scripts/generate-commands-doc.mjs) - all needed every turn, so they cannot defer to a reference. The marker sits after the YAML frontmatter so the loader and sync-plugin-version.mjs still parse it. Reviewed 2026-07-11. -->
8
+ <!-- SIZE EXEMPTION (SKILL.md): standard hard limit 12,288 chars, exempted ceiling 26,624. This router always-loads the collaboration/pace spine (brainstorm, ask-user, present-result, plan-next), the hard constraints + scope gate, the investigation loop, and the generated command table (between the COMMANDS markers, written by scripts/generate-commands-doc.mjs) - all needed every turn, so they cannot defer to a reference. The marker sits after the YAML frontmatter so the loader and sync-plugin-version.mjs still parse it. Reviewed 2026-07-11. -->
9
9
 
10
10
  # Graphit CLI
11
11
 
@@ -49,7 +49,7 @@ Two interlocking jobs: use the knowledge base (investigate, then build the dashb
49
49
 
50
50
  You are a colleague building WITH the user, not a batch job that explores in silence and returns a finished product. The user cannot see your command output: the KB you listed, the SQL you ran, the rows that came back are invisible unless you surface them. So you are the rendering layer, and the work is a conversation: think the question through together, then move one small step at a time - do one thing, show it, let the user react, then do the next. Each step is a cheap chance to redirect before you have built in the wrong direction.
51
51
 
52
- If the user is not set up yet (not authenticated, or no data source connected), treat that as the start of the job: offer to connect and onboard, then proceed. Do not bail because setup is missing.
52
+ If the workspace is empty - not authenticated, or no connector or data source yet - onboarding IS the job, not a blocker: follow references/onboarding.md. Do not bail because setup is missing.
53
53
 
54
54
  ### Brainstorm before you charge off
55
55
 
@@ -97,7 +97,7 @@ One loop serves both jobs. Each step names the reference to read when you need d
97
97
 
98
98
  1. Understand the question and its depth (retrieve / monitor / diagnose / predict). At low confidence, brainstorm what the user is really trying to learn before scoping. One clarifying question beats a wrong dashboard.
99
99
  2. Establish scope by asking - never assume it (BLOCKING; holds even under "just build it"). Do not infer the domain, data source, or assets and charge off; let the user choose at each fork, and skip a fork only when the user already named that choice - never because you guessed it.
100
- - Domain. `graphit kb list domains` lists the real domains; present them and ask which one (`graphit kb explore topic <NAME>` finds the domain when a concept spans several). If none fits, or no source under it covers the data, offer to create one.
100
+ - Domain. `graphit kb list domains` lists the real domains; present them and ask which one (`graphit kb explore topic <NAME>` finds the domain when a concept spans several). If it is empty (brand-new workspace), see references/onboarding.md; if none fits, offer to create one.
101
101
  - Data source. `graphit kb explore domain <NAME>` returns that domain's data sources plus their metrics, dimensions, and rules in one traversal (`graphit ds list` for the full list); present the sources, ask which one, or offer to create one if none fits.
102
102
  - Assets. Present the chosen source's metrics, dimensions, and rules as the working set and confirm it. If the user's wording doesn't match an asset, resolve it with `graphit kb search` (semantic, ranked by relevance) before assuming a mapping; for a cross-domain investigation, broaden across the whole KB. A 0-result search is not proof of absence (results are ranked and capped) - confirm a specific name with `kb get` first. Then proceed.
103
103
  Ask via the structured ask-user tool above, options pre-populated from what you listed. Read references/kb-discovery.md, references/kb-traversal.md, references/data-sources.md.
@@ -131,6 +131,7 @@ Read the one that matches what you are doing now. Do not preload them. Exact com
131
131
 
132
132
  | Situation | Read |
133
133
  |---|---|
134
+ | a brand-new or empty workspace, nothing connected yet | onboarding.md |
134
135
  | scoping to a domain, data source, and assets | kb-discovery.md, kb-traversal.md, data-sources.md |
135
136
  | building or curating KB assets (the gate) | kb-structure.md, kb-actions.md, parameterized-metrics.md |
136
137
  | writing or validating a query | sql-reference.md, governance.md |
@@ -142,7 +143,7 @@ Read the one that matches what you are doing now. Do not preload them. Exact com
142
143
 
143
144
  ## Commands
144
145
 
145
- 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.107 <command>` (a stamped version, kept current automatically by the build), or pin an exact one - `npx -y @graphit/cli@<exact> <command>` - for a reproducible run. The table below is the always-loaded command map, generated from the CLI itself, so it is the source of truth for which commands, subcommands, and flags exist. For exact flag values and full descriptions, run `graphit <command> --help` - never guess a flag.
146
+ 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.113 <command>` (a stamped version, kept current automatically by the build), or pin an exact one - `npx -y @graphit/cli@<exact> <command>` - for a reproducible run. The table below is the always-loaded command map, generated from the CLI itself, so it is the source of truth for which commands, subcommands, and flags exist. For exact flag values and full descriptions, run `graphit <command> --help` - never guess a flag.
146
147
 
147
148
  <!-- COMMANDS:START -->
148
149
 
@@ -210,7 +211,7 @@ _Generated from the CLI by `npm run gen:commands` - do not hand-edit between the
210
211
 
211
212
  **connector** - Connection management. OAuth and GitHub connections are set up in the Graphit web app.
212
213
  - `connector list` - List active connections
213
- - `connector add snowflake-keypair` - Add Snowflake via keypair auth - `--account --user --key --warehouse --role --database`
214
+ - `connector add snowflake-keypair` - Add Snowflake via keypair auth - `--account --user --key --name --warehouse --role --database`
214
215
  - `connector test <id>` - Test a connection
215
216
  - `connector remove <id>` - Remove a connection (requires --yes) - `--yes`
216
217
 
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "package": "@graphit/cli",
3
- "version": "0.2.107",
3
+ "version": "0.2.113",
4
4
  "source": "cli/package.json"
5
5
  }
@@ -0,0 +1,61 @@
1
+ # First Run: From an Empty Workspace to a First Dashboard
2
+
3
+ Load this when the user is signed in but the workspace is empty - `graphit kb list domains` (and `graphit ds list`) come back with nothing. That means no data is connected yet. Onboarding IS the job here, not a blocker: walk the user through it one step at a time, surfacing each result. This flow self-limits - once a data source and KB assets exist, `kb list domains` is no longer empty and you land in the normal loop instead.
4
+
5
+ ## The arc
6
+
7
+ 1. Connect a source.
8
+ 2. Ask what they want to investigate.
9
+ 3. Create the data source for it.
10
+ 4. Create the KB assets it needs.
11
+ 5. Offer a dashboard.
12
+ 6. On the first dashboard, show what they got for free.
13
+
14
+ One step at a time - do it, show the result, let the user react, then the next. Don't run the whole chain silently and drop a finished workspace at the end.
15
+
16
+ ## 1. Connect a source
17
+
18
+ Two ways in. Lead with the warehouse; offer the file as the lighter path.
19
+
20
+ **Warehouse (recommended).** Run `graphit connector list` first. If a connection already exists, use it. If none:
21
+
22
+ - Creating a connection needs an org admin. If the user is not an admin, connector creation returns 403 - point them to the Graphit web app or to ask an admin, and do not retry the command.
23
+ - Snowflake keypair from the CLI: `graphit connector add snowflake-keypair` needs `--account --user --key --warehouse --role --database` (all required), plus optional `--name` for a friendly label (it defaults to `Snowflake (<account>)`). It validates the connection before saving, so a success really did connect.
24
+ - OAuth and GitHub connections are set up in the Graphit web app, not the CLI - name that handoff when it applies.
25
+
26
+ **File (lighter).** For a quick start with no warehouse, `graphit ds create --file ./data.csv` uploads a CSV or Excel file and creates a data source directly - no connector needed.
27
+
28
+ Present the outcome: which connection is live, or the exact web-app / admin step the user has to finish.
29
+
30
+ ## 2. Ask what to investigate
31
+
32
+ Before creating anything, ask what business question the user wants to answer. The goal drives which data source and which KB assets you build - don't create assets in a vacuum. One structured question is enough to start.
33
+
34
+ ## 3. Create the data source
35
+
36
+ Explain that answering the question fast needs a cached data source over the connection, not repeated live-warehouse queries. Create it, then activate it:
37
+
38
+ ```bash
39
+ graphit ds create --name "MY_DS" --sql "SELECT ..." --connection <id>
40
+ graphit ds verify <id> --accept-schema
41
+ ```
42
+
43
+ Shape it for the question - grain, only the columns dashboards use, low cardinality (see data-sources.md). Show the scanned schema and confirm before moving on.
44
+
45
+ ## 4. Create the KB assets
46
+
47
+ Explain that governed answers need KB assets - the metrics, dimensions, and rules the question implies. This is the readiness gate, narrated as first-run teaching, never skipped. Show a short gap list (what is missing, the proposed definition), get approval, then create and verify (see kb-structure.md, kb-actions.md).
48
+
49
+ ## 5. Offer a dashboard
50
+
51
+ Ask whether the user wants a quick query answer or a deployed HTML dashboard. Build the dashboard only if they want one - a genuine one-off doesn't need it.
52
+
53
+ ## 6. First-dashboard reveal (first time only)
54
+
55
+ After the first dashboard is deployed, tell the user - concisely - what they get for free on it. Keep this to the first dashboard; it never needs repeating, because onboarding stops firing once the workspace has data.
56
+
57
+ - **Each graph's 3-dot (hamburger) menu**: "view details" opens a panel with the SQL, live query results, and the trust tier plus any enforced rules (the KB assets it lists open as explorable tabs); "save as template" reuses that graph elsewhere.
58
+ - **The dashboard's own hamburger** (top bar): share it, schedule a recurring email report, export to PNG or PDF, and browse version history.
59
+ - **Themes and colors** are automatic - dark and light mode, and the brand palette, with no extra work.
60
+
61
+ Then continue in the normal loop; the workspace is no longer empty.