@graphenedata/cli 0.0.16 → 0.0.18

package/README.md

@@ -25,23 +25,35 @@
 
 ## Why Graphene?
 
-In the future, we believe **most low-level data analytics work will be done by agents**, allowing humans to focus on insights and decision-making. However, today's tools weren't built with agents in mind:
+Graphene is an everything-as-code analytics framework for SQL-based data exploration, visualization, and reporting. It is designed with coding agents in mind as the primary user persona.
 
-- They are GUI centric. Lots of actions can only be done via GUI and aren't accessible to external agents like Claude.
-- They focus on raising the floor at the expense of lowering the ceiling (limited viz types, simplified querying APIs).
-- They assume the human user has the tribal knowledge and business context necessary for analysis.
+It provides two critical pieces that allow coding agents to do better data work:
 
-If we really want agents to be more productive with data, an entirely new toolset is needed.
+1. **A semantic layer**, which yields more accurate queries. GSQL combines the power of SQL with the governance of metrics and modeled joins.
+2. **A dashboard file type**, which yields more consistent and polished visuals compared to raw Python or Javascript.
 
-Graphene is:
+**Design goals**
 
-- [x] **Built for agents**. Everything is code, written only in languages that are prevalent in training data (SQL, Markdown, HTML). All actions are CLIs; nothing is trapped in a button.
-- [x] **High-ceiling**. Agents can create any visualization that's supported by ECharts, one of the most feature-complete visualization libraries. And Graphene's query language is as powerful as ANSI SQL, which supports 170+ functions, CTEs, subqueries, set operations, window functions, arrays, and more.
-- [x] **Optimized for agent context**. Graphene's SQL language contains a semantic layer which allows metrics and join relationships to be invoked in queries. When combined with [agent skills](https://agentskills.io/home) for general business context and best practices, agents perform at human levels of competency.
+- Token efficiency. Languages are designed to be brief with minimal boilerplate.
+- Agent ergonomics. Graphene is controlled entirely via CLI. All documentation is inside our agent skill.
+- High ceilings. GSQL follows ANSI and supports over 170 functions; Graphene's visualizations support anything that can be expressed with ECharts.
+
+### Versus traditional BI
+
+We believe coding agents coupled with an everything-as-code analytics stack beats traditional BI in several ways:
+
+- Broad ecosystem of SOTA LLMs, harnesses, skills, and tools
+- Leverage business-wide context from other tools or repos
+- Perform end-to-end tasks across tools, where analytics is just one step
+- More graceful change management and bulk refactors
+- Easily promote/demote logic into or out of the semantic layer
+- Version control and CI. Revert agent mistakes. Run tests on mission-critical dashboards.
+- Tight, complete iteration loops. Agents can validate before running, view dashboards, and iterate locally
+- Leverage continuous agents for self-healing codebases
 
 ### Open, forever
 
-Importantly, Graphene is **open**. You can use this project for internal purposes for free, forever, and aren't locked in to a contract with us. More details [below](#faq).
+Graphene is free to use, forever. Your business logic lives in your repo and is never locked into a contract with us.
 
 ### Rich visualizations
 
@@ -49,16 +61,13 @@ Graphene pages support visualizations, input components for filtering and dynami
 
 <img alt="Graphene Screenshots" src="./assets/page_examples.png"/>
 
-### Powerful workflows
+### Powerful, next-generation semantic layer
 
-When you deconstruct data analytics into code, CLIs, and coding agents, things that used to be hard become easy:
+Traditional semantic layers give you governance at the expense of capability. They tend to expose niche query APIs that agents aren't familiar with.
 
-- Promote metrics from pages into the model, or demote metrics out of the model back into pages
-- Bulk refactors in a single atomic commit/PR
-- Ability to use extensive skill/MCP ecosystem to augment agent behavior
-- Iterate on a dashboard (edit, run, view) without needing to push up to some API or open a SaaS portal
-- Validate SQL and page syntax instantaneously as you type
-- Set up a recurring agent that de-bloats, consolidates your model over time
+GSQL's goal is to bring governance _without_ sacrificing capability. It behaves like regular SQL—with CTEs, subqueries, window functions, set operators, and more—but also adds in the concepts of measures and modeled joins from semantic layers.
+
+GSQL is inspired by [Malloy](https://github.com/malloydata/malloy), from the creators of LookML Lloyd Tabb and Michael Toy, but implements it as good old SQL for agent familiarity.
 
 ## Get started
 
@@ -71,13 +80,10 @@ Once your project is set up, simply start the dev server via `npm exec graphene
 
 ## How it works
 
-A Graphene project can either be a standalone repo or a directory within a larger codebase (such as dbt). It is comprised of:
-
-- **Semantic models**, via .gsql files. GSQL is both a modeling language and a query language, in the same way that SQL has both DDL and DML.
-- **Pages**, via .md files. Pages are typically used for dashboards, but can also contain notebook-style narratives, documentation, and other visual content.
-
 Graphene itself is a CLI which can be installed via npm (or pnpm, yarn, etc.). The CLI can run and compile GSQL queries, render pages in the browser, check syntax, print screenshots, and more.
 
+A Graphene project can either be a standalone repo or a directory within a larger codebase (such as dbt). It is comprised of _semantic models_ via .gsql files and _pages_ via .md files.
+
 ### GSQL and Graphene markdown
 
 Semantic models are defined like so:
@@ -127,12 +133,42 @@ Graphene's entire documentation ships as an agent skill in the Graphene npm pack
 
 ## FAQ
 
-<details>
-<summary><b>So does everyone have to use git and a coding agent to use Graphene for BI?</b></summary>
-If you just want to use this project and nothing more, yes. Our managed service, Graphene Cloud, offers a Slack agent, MCP server, and browser-based SaaS experience.
+<details><summary><b>Why coding agents?</b></summary>
+  <br/>
+  Context, mostly. If your BI stack lives in a folder right next to the rest of your company’s data and code, an agent can make smarter decisions on what it should be analyzing and why it matters.
+  <br/><br/>
+  The reverse is also true. If you’re working on building out some new feature or a recommendation for a new client, the agent doing that work can ground it’s approach in real data and past analytical insights.
+  <br/><br/>
+  Lock-in is the other big reason we hear. Folks post-SaaS are wary of having their data and dashboards locked away in some proprietary tool, or forced to use a single LLM provider. With Graphene, you own all the files in your repo. You can use whatever agent or LLM you’d like.
+</details>
+
+<details><summary><b>How do you make money?</b></summary>
+  <br/>
+  We’re building out Graphene Cloud as a turnkey solution to host the dashboards and reports your agent builds. We also host an MCP server and Slack bot that you can use for quick questions. If you'd like to pilot it, contact us <a href="https://graphenedata.com/contact-us">here</a>.
 </details>
 
-<details>
-<summary><b>What software license does this use?</b></summary>
-Graphene is licensed under the Elastic License 2.0 which allows you to use it for internal use cases for free, forever. If you would like to use the Graphene Cloud services above, or if you would like a commercial license, please contact us <a href="https://graphenedata.com/contact-us">here</a>.
+<details><summary><b>So does everyone have to use git and a coding agent to use Graphene for BI?</b></summary>
+  <br/>
+  If you just want to use this project and nothing more, yes. Our managed service, Graphene Cloud, offers a Slack agent, MCP server, and browser-based SaaS experience.
+</details>
+
+<details><summary><b>Is my data team out of a job?</b></summary>
+  <br/>
+  No, but we think the nature of the work is going to change. Instead of manually building out reports, data experts are going to be shaping the skills, models, and tools that the rest of their team uses to answer data questions.
+  <br/><br/>
+  Data teams are going to be focused on guiding agents on how to approach the trickiest and most nebulous data questions at a company. Questions that still require a data expert’s taste to get a good solution.
+</details>
+
+<details><summary><b>Can’t I just vibe code dashboards?</b></summary>
+  <br/>
+  You could! In fact a lot of the folks we’ve talked to have started down this route. The main problem you’ll run into is consistency. The look and feel of your dashboards and reports are all over the place, and in the worst case they end up using different formula to compute the same key metric.
+  <br/><br/>
+  GSQL codifies metrics into deterministic objects you can directly invoke in queries. Not only does this ensure that every use of "EBITDA" will be the same, the metadata tags we attach can hint our charts into formatting data correctly.
+  <br/><br/>
+  Graphene raises the floor so that pages you generate with the help of an agent look beautiful by default, so you can move faster with less tokens.
+</details>
+
+<details><summary><b>What software license does this use?</b></summary>
+  <br/>
+  Graphene is licensed under the Elastic License 2.0 which allows you to use it for internal use cases for free, forever. If you would like to build your own commercial application with Graphene, please contact us <a href="https://graphenedata.com/contact-us">here</a>.
 </details>

package/dist/cli/{bigQuery-I3F46SC6.js → bigQuery-YIWXZPY6.js}

@@ -1,6 +1,6 @@
 import {
   config
-} from "./chunk-QAXEOZ43.js";
+} from "./chunk-SQVXTHE5.js";
 
 // connections/bigQuery.ts
 import { BigQuery, BigQueryDate, BigQueryTimestamp } from "@google-cloud/bigquery";
@@ -72,4 +72,4 @@ var BigQueryConnection = class {
 export {
   BigQueryConnection
 };
-//# sourceMappingURL=bigQuery-I3F46SC6.js.map
+//# sourceMappingURL=bigQuery-YIWXZPY6.js.map

package/dist/cli/{chunk-QAXEOZ43.js → chunk-SQVXTHE5.js}

@@ -23,7 +23,7 @@ function normalizeConfig(input, defaultRoot = process.cwd()) {
     dialect,
     root: path.resolve(cfg.root || defaultRoot),
     port: cfg.port || Number(process.env.GRAPHENE_PORT) || 4e3,
-    ignoredFiles: cfg.ignoredFiles || ["**/agents.md", "**/claude.md"],
+    ignoredFiles: cfg.ignoredFiles || [],
     envFile
   };
 }
@@ -50,4 +50,4 @@ export {
   setGlobalConfig,
   loadConfig
 };
-//# sourceMappingURL=chunk-QAXEOZ43.js.map
+//# sourceMappingURL=chunk-SQVXTHE5.js.map

package/dist/cli/chunk-SQVXTHE5.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../lang/config.ts"],
+  "sourcesContent": ["import {existsSync} from 'node:fs'\nimport {readFile} from 'node:fs/promises'\nimport path from 'path'\n\nexport interface Config {\n  root: string\n  dialect: string\n  defaultNamespace?: string\n  ignoredFiles: string[]\n  telemetry?: boolean\n  port?: number\n  host?: string\n  envFile: string[] // array of paths where we can look for the env file\n\n  bigquery?: {\n    projectId?: string\n    keyPath?: string\n  }\n\n  snowflake?: {\n    account: string\n    username: string\n    privateKeyPath: string\n    schema?: string\n    database?: string\n  }\n\n  clickhouse?: {\n    url?: string\n    username?: string\n    database?: string\n    requestTimeout?: number\n  }\n\n  duckdb?: {\n    path?: string\n  }\n}\n\nexport type ConfigInput = Omit<Config, 'root' | 'dialect' | 'ignoredFiles' | 'envFile'> & {\n  root?: string\n  dialect?: Config['dialect']\n  ignoredFiles?: Config['ignoredFiles']\n  envFile?: string | string[]\n  namespace?: string\n}\n\nexport let config: Config = {dialect: 'duckdb', root: ''} as Config\n\nexport function setGlobalConfig(cfg: ConfigInput) {\n  Object.keys(config).forEach(key => delete config[key])\n  Object.assign(config, normalizeConfig(cfg))\n}\n\nexport function normalizeConfig(input: ConfigInput, defaultRoot = process.cwd()): Config {\n  let cfg = {...input}\n  if (cfg.namespace && !cfg.defaultNamespace) cfg.defaultNamespace = cfg.namespace\n\n  let dialect = cfg.dialect || 'duckdb'\n  if (cfg.bigquery) dialect = 'bigquery'\n  else if (cfg.snowflake) dialect = 'snowflake'\n  else if (cfg.clickhouse) dialect = 'clickhouse'\n  else if (cfg.duckdb) dialect = 'duckdb'\n  let envFile = ['.env']\n  if (Array.isArray(cfg.envFile)) envFile = cfg.envFile\n  else if (cfg.envFile) envFile = [cfg.envFile]\n\n  return {\n    ...cfg,\n    dialect,\n    root: path.resolve(cfg.root || defaultRoot),\n    port: cfg.port || Number(process.env.GRAPHENE_PORT) || 4000,\n    ignoredFiles: cfg.ignoredFiles || [],\n    envFile,\n  } as Config\n}\n\n// Read graphene config from the nearest parent package.json.\nexport async function loadConfig(dir: string, envLoader: (envFiles: string[]) => void): Promise<Config> {\n  // seek upwards from dir looking for package.json\n  let configDir = path.resolve(dir)\n  while (!existsSync(path.join(configDir, 'package.json'))) {\n    let parent = path.dirname(configDir)\n    if (parent == configDir) throw new Error(`No package.json found in ${path.resolve(dir)} or its parents`)\n    configDir = parent\n  }\n\n  let txt = await readFile(path.join(configDir, 'package.json'), 'utf8')\n  let graphene = JSON.parse(txt).graphene\n  if (!graphene || typeof graphene != 'object' || Array.isArray(graphene)) {\n    throw new Error(`No graphene config found in ${path.join(configDir, 'package.json')}`)\n  }\n\n  // config can provide 1 or more env files that Graphene should load. Default to just `.env`\n  let envFiles = Array.isArray(graphene.envFile) ? graphene.envFile : [graphene.envFile || '.env']\n  envLoader(envFiles.map(file => path.resolve(configDir, file)))\n\n  let cfg = normalizeConfig({...graphene, root: configDir}, configDir)\n  return cfg\n}\n"],
+  "mappings": ";AAAA,SAAQ,kBAAiB;AACzB,SAAQ,gBAAe;AACvB,OAAO,UAAU;AA6CV,IAAI,SAAiB,EAAC,SAAS,UAAU,MAAM,GAAE;AAEjD,SAAS,gBAAgB,KAAkB;AAChD,SAAO,KAAK,MAAM,EAAE,QAAQ,SAAO,OAAO,OAAO,GAAG,CAAC;AACrD,SAAO,OAAO,QAAQ,gBAAgB,GAAG,CAAC;AAC5C;AAEO,SAAS,gBAAgB,OAAoB,cAAc,QAAQ,IAAI,GAAW;AACvF,MAAI,MAAM,EAAC,GAAG,MAAK;AACnB,MAAI,IAAI,aAAa,CAAC,IAAI,iBAAkB,KAAI,mBAAmB,IAAI;AAEvE,MAAI,UAAU,IAAI,WAAW;AAC7B,MAAI,IAAI,SAAU,WAAU;AAAA,WACnB,IAAI,UAAW,WAAU;AAAA,WACzB,IAAI,WAAY,WAAU;AAAA,WAC1B,IAAI,OAAQ,WAAU;AAC/B,MAAI,UAAU,CAAC,MAAM;AACrB,MAAI,MAAM,QAAQ,IAAI,OAAO,EAAG,WAAU,IAAI;AAAA,WACrC,IAAI,QAAS,WAAU,CAAC,IAAI,OAAO;AAE5C,SAAO;AAAA,IACL,GAAG;AAAA,IACH;AAAA,IACA,MAAM,KAAK,QAAQ,IAAI,QAAQ,WAAW;AAAA,IAC1C,MAAM,IAAI,QAAQ,OAAO,QAAQ,IAAI,aAAa,KAAK;AAAA,IACvD,cAAc,IAAI,gBAAgB,CAAC;AAAA,IACnC;AAAA,EACF;AACF;AAGA,eAAsB,WAAW,KAAa,WAA0D;AAEtG,MAAI,YAAY,KAAK,QAAQ,GAAG;AAChC,SAAO,CAAC,WAAW,KAAK,KAAK,WAAW,cAAc,CAAC,GAAG;AACxD,QAAI,SAAS,KAAK,QAAQ,SAAS;AACnC,QAAI,UAAU,UAAW,OAAM,IAAI,MAAM,4BAA4B,KAAK,QAAQ,GAAG,CAAC,iBAAiB;AACvG,gBAAY;AAAA,EACd;AAEA,MAAI,MAAM,MAAM,SAAS,KAAK,KAAK,WAAW,cAAc,GAAG,MAAM;AACrE,MAAI,WAAW,KAAK,MAAM,GAAG,EAAE;AAC/B,MAAI,CAAC,YAAY,OAAO,YAAY,YAAY,MAAM,QAAQ,QAAQ,GAAG;AACvE,UAAM,IAAI,MAAM,+BAA+B,KAAK,KAAK,WAAW,cAAc,CAAC,EAAE;AAAA,EACvF;AAGA,MAAI,WAAW,MAAM,QAAQ,SAAS,OAAO,IAAI,SAAS,UAAU,CAAC,SAAS,WAAW,MAAM;AAC/F,YAAU,SAAS,IAAI,UAAQ,KAAK,QAAQ,WAAW,IAAI,CAAC,CAAC;AAE7D,MAAI,MAAM,gBAAgB,EAAC,GAAG,UAAU,MAAM,UAAS,GAAG,SAAS;AACnE,SAAO;AACT;",
+  "names": []
+}