create-dql-app 0.11.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,123 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner.
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work and such
+Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof
+in any medium, with or without modifications, and in Source or Object form,
+provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any part
+of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in the Work by You to the Licensor shall be under the terms and
+conditions of this License, without any additional terms or conditions.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names, trademarks,
+service marks, or product names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides the
+Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+express or implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR
+PURPOSE.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law, shall any Contributor
+be liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a result of this
+License or out of the use or inability to use the Work.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may choose to
+offer, and charge a fee for, acceptance of support, warranty, indemnity, or
+other liability obligations and/or rights consistent with this License.
+
+END OF TERMS AND CONDITIONS

package/bin/create-dql-app.mjs

@@ -12,10 +12,10 @@
 
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve, basename } from 'node:path';
+import { dirname, join, resolve, basename, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const VERSION = '0.11.0';
+const VERSION = '1.0.1';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = resolve(__dirname, '..', 'templates');
 
@@ -100,6 +100,13 @@ function detectDbtSibling(target) {
   return null;
 }
 
+function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent ?? '';
+  if (ua.startsWith('pnpm/')) return 'pnpm';
+  if (ua.startsWith('yarn/')) return 'yarn';
+  return 'npm';
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (!args.dir) {
@@ -129,28 +136,38 @@ async function main() {
   copyDir(tplDir, target);
 
   const dbtSibling = detectDbtSibling(target);
+  // Store dbt path as relative-to-project — keeps dql.config.json portable.
+  const dbtRel = dbtSibling ? (relative(target, dbtSibling) || '.') : '../my-dbt-project';
   const vars = {
     PROJECT_NAME: projectName,
     YEAR: String(new Date().getFullYear()),
-    DBT_PROJECT_DIR: dbtSibling ? resolve(dbtSibling) : '../my-dbt-project',
+    DBT_PROJECT_DIR: dbtRel,
     DBT_DETECTED: dbtSibling ? 'true' : 'false',
   };
   for (const f of walk(target)) substitute(f, vars);
 
   if (dbtSibling) {
     console.log(c.dim(`  detected sibling dbt project at ${dbtSibling}`));
-    console.log(c.dim(`  wired into cdql.yaml — run 'dql sync dbt' to import\n`));
+    console.log(c.dim(`  wired into dql.config.json — run 'dql sync dbt' to import\n`));
   }
 
   // Best-effort: try to run `git init` so users get a clean first commit.
   const gitResult = spawnSync('git', ['init', '-q'], { cwd: target });
   if (gitResult.status === 0) console.log(c.dim('  initialized git repo'));
 
+  const pm = detectPackageManager();
+  const installCmd = pm === 'npm' ? 'npm install' : `${pm} install`;
+  const runCmd = pm === 'npm' ? 'npm run notebook' : `${pm} notebook`;
+  const dbtTip = dbtSibling
+    ? `\n\n${c.dim('Tip:')} run ${c.bold('dbt parse')} inside ${c.dim(dbtSibling)}\n     first, then ${c.bold(pm === 'npm' ? 'npm run sync' : `${pm} sync`)} to import the dbt DAG.`
+    : '';
+
   console.log(`
 ${c.green('✓ Ready.')} Next steps:
 
   ${c.bold(`cd ${args.dir}`)}
-  ${c.bold('npx @duckcodeailabs/dql-cli notebook')}
+  ${c.bold(installCmd)}
+  ${c.bold(runCmd)}${dbtTip}
 
 Your notebook will open at ${c.cyan('http://localhost:5173')}.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-dql-app",
-  "version": "0.11.0",
+  "version": "1.0.1",
   "description": "Scaffold a new DQL project. Run with: npx create-dql-app <name>",
   "license": "MIT",
   "author": "DuckCode AI Labs",
@@ -10,7 +10,14 @@
     "url": "https://github.com/duckcode-ai/dql.git",
     "directory": "packages/create-dql-app"
   },
-  "keywords": ["dql", "dbt", "analytics", "notebook", "semantic-layer", "lineage"],
+  "keywords": [
+    "dql",
+    "dbt",
+    "analytics",
+    "notebook",
+    "semantic-layer",
+    "lineage"
+  ],
   "bin": {
     "create-dql-app": "./bin/create-dql-app.mjs"
   },
@@ -20,14 +27,14 @@
     "README.md"
   ],
   "type": "module",
-  "scripts": {
-    "test": "node test/smoke.mjs",
-    "build": "echo 'no build step — pure JS'"
-  },
   "engines": {
     "node": ">=20"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs",
+    "build": "echo 'no build step — pure JS'"
   }
-}
+}

package/templates/empty/dql.config.json

@@ -0,0 +1,13 @@
+{
+  "project": "{{PROJECT_NAME}}",
+  "connections": {
+    "default": {
+      "driver": "duckdb",
+      "filepath": ":memory:"
+    }
+  },
+  "semanticLayer": {
+    "provider": "dql",
+    "path": "semantic-layer"
+  }
+}

package/templates/empty/notebooks/welcome.dqlnb

@@ -0,0 +1,20 @@
+{
+  "version": 1,
+  "metadata": {
+    "title": "{{PROJECT_NAME}} — Welcome",
+    "description": "Replace this cell with your first query."
+  },
+  "cells": [
+    {
+      "id": "intro",
+      "type": "markdown",
+      "source": "# {{PROJECT_NAME}}\n\nWelcome to DQL. Connect a warehouse in `dql.config.json`, then edit the cell below."
+    },
+    {
+      "id": "first_query",
+      "type": "sql",
+      "title": "First query",
+      "source": "select 1 as hello"
+    }
+  ]
+}

package/templates/empty/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "notebook": "dql notebook",
+    "compile": "dql compile",
+    "doctor": "dql doctor"
+  },
+  "devDependencies": {
+    "@duckcodeailabs/dql-cli": "^1.0.0"
+  }
+}

package/templates/jaffle-shop/README.md

@@ -5,24 +5,38 @@ A DQL analytics project, scaffolded by `create-dql-app`.
 ## Run
 
 ```bash
-npx @duckcodeailabs/dql-cli notebook
+npm install
+npm run notebook
 ```
 
-Opens the notebook at <http://localhost:5173>.
+Opens the notebook at <http://localhost:5173>. (`pnpm install && pnpm notebook`
+works too.)
 
 ## Layout
 
 ```
-cdql.yaml              project config (connections, dbt, governance)
-notebooks/             analytics notebooks (.dql)
-blocks/                certified reusable blocks, grouped by domain
+dql.config.json        project config (connections, dbt, semantic layer)
+package.json           npm scripts — `notebook`, `compile`, `sync`, `doctor`
+notebooks/             .dqlnb notebooks (JSON format)
+blocks/                certified reusable .dql blocks
 semantic-layer/        metrics + dimensions authored locally
 dashboards/            compiled static HTML dashboards (git-ignored)
 ```
 
+## Using with dbt
+
+If your dbt project is a sibling (e.g. `../dbt`), it was auto-wired into
+`dql.config.json` under the `dbt:` key. Then:
+
+```bash
+(cd ../dbt && dbt parse)   # produces target/manifest.json
+npm run sync               # refreshes the DQL cache from dbt
+npm run compile            # builds dql-manifest.json with lineage
+```
+
 ## Next steps
 
-1. **Run the welcome notebook** — `notebooks/welcome.dql`
+1. **Run the welcome notebook** — `notebooks/welcome.dqlnb`
 2. **Connect your warehouse** — [docs.duckcode.ai/guides/connect-warehouse](https://docs.duckcode.ai/guides/connect-warehouse/)
 3. **Import your dbt project** — [docs.duckcode.ai/guides/import-dbt](https://docs.duckcode.ai/guides/import-dbt/)
 4. **Author a certified block** — [docs.duckcode.ai/guides/authoring-blocks](https://docs.duckcode.ai/guides/authoring-blocks/)

package/templates/jaffle-shop/blocks/revenue_by_segment.dql

@@ -0,0 +1,29 @@
+// dql-format: 1
+
+block "Revenue by segment" {
+  domain = "finance"
+  type = "custom"
+  description = "Gross revenue grouped by customer segment."
+  tags = ["revenue", "sample"]
+
+  query = """
+    SELECT
+      c.customer_segment AS segment,
+      SUM(o.amount) AS revenue,
+      COUNT(DISTINCT o.customer_id) AS customers
+    FROM orders o
+    JOIN customers c ON c.customer_id = o.customer_id
+    GROUP BY 1
+    ORDER BY revenue DESC
+  """
+
+  visualization {
+    chart = "bar"
+    x = segment
+    y = revenue
+  }
+
+  tests {
+    assert row_count > 0
+  }
+}

package/templates/jaffle-shop/dashboards/overview.dql

@@ -1,22 +1,29 @@
 // dql-format: 1
 
-dashboard: {
-  title: "{{PROJECT_NAME}} — Overview"
-  description: "Revenue overview generated by create-dql-app."
-  layout: "grid"
-}
-
----
-type: markdown
----
-
-# Overview — {{YEAR}}
+dashboard "{{PROJECT_NAME}} — Overview" {
+  chart.kpi(
+    SELECT SUM(amount) as revenue FROM orders,
+    metrics = ["revenue"]
+  )
 
-Compiled with `dql compile dashboards/overview.dql --out build/`. Host the
-resulting HTML anywhere.
+  chart.bar(
+    SELECT customer_id, SUM(amount) as spend
+    FROM orders
+    GROUP BY customer_id
+    ORDER BY spend DESC
+    LIMIT 10,
+    x = customer_id,
+    y = spend,
+    title = "Top 10 customers by spend"
+  )
 
----
-type: dql
----
-
-@block("revenue_by_segment")
+  chart.line(
+    SELECT order_date, SUM(amount) as revenue
+    FROM orders
+    GROUP BY order_date
+    ORDER BY order_date,
+    x = order_date,
+    y = revenue,
+    title = "Daily revenue"
+  )
+}

package/templates/jaffle-shop/dql.config.json

@@ -0,0 +1,20 @@
+{
+  "project": "{{PROJECT_NAME}}",
+  "connections": {
+    "default": {
+      "driver": "duckdb",
+      "filepath": ":memory:"
+    }
+  },
+  "semanticLayer": {
+    "provider": "dql",
+    "path": "semantic-layer"
+  },
+  "dbt": {
+    "projectDir": "{{DBT_PROJECT_DIR}}",
+    "manifestPath": "target/manifest.json"
+  },
+  "governance": {
+    "required_fields": ["domain", "owner", "description"]
+  }
+}

package/templates/jaffle-shop/notebooks/welcome.dqlnb

@@ -0,0 +1,32 @@
+{
+  "version": 1,
+  "metadata": {
+    "title": "{{PROJECT_NAME}} — Welcome",
+    "description": "A tour of DQL in four cells. Run them top-to-bottom with Cmd+Enter."
+  },
+  "cells": [
+    {
+      "id": "intro",
+      "type": "markdown",
+      "source": "# Welcome to {{PROJECT_NAME}}\n\nThis notebook runs against a DuckDB-backed Jaffle Shop dataset — the same demo data dbt ships.\n\n- Run each cell with `Cmd/Ctrl + Enter`.\n- Charts render inline from SQL results.\n- The certified block in cell 4 lives in `blocks/revenue_by_segment.dql` and can be reused across notebooks and dashboards."
+    },
+    {
+      "id": "orders_overview",
+      "type": "sql",
+      "title": "Orders overview",
+      "source": "select\n  count(*) as total_orders,\n  count(distinct customer_id) as unique_customers,\n  sum(amount) as lifetime_revenue\nfrom orders"
+    },
+    {
+      "id": "daily_revenue",
+      "type": "sql",
+      "title": "Daily revenue",
+      "source": "select\n  order_date,\n  sum(amount) as revenue\nfrom orders\ngroup by 1\norder by 1"
+    },
+    {
+      "id": "revenue_by_segment",
+      "type": "dql",
+      "title": "Revenue by segment (certified block)",
+      "source": "@block(\"Revenue by segment\")"
+    }
+  ]
+}

package/templates/jaffle-shop/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "DQL analytics project.",
+  "scripts": {
+    "notebook": "dql notebook",
+    "compile": "dql compile",
+    "sync": "dql sync dbt",
+    "doctor": "dql doctor",
+    "test": "dql test"
+  },
+  "devDependencies": {
+    "@duckcodeailabs/dql-cli": "^1.0.0"
+  }
+}

package/templates/empty/cdql.yaml

@@ -1,13 +0,0 @@
-project:
-  name: {{PROJECT_NAME}}
-  version: 1
-
-connections:
-  # Swap this for your warehouse — postgres, snowflake, bigquery, etc.
-  # See https://docs.duckcode.ai/reference/connectors/
-  default:
-    driver: duckdb
-    path: ./warehouse.duckdb
-
-governance:
-  required_fields: [domain, owner, description]

package/templates/empty/notebooks/welcome.dql

@@ -1,17 +0,0 @@
-// dql-format: 1
-
----
-type: markdown
----
-
-# {{PROJECT_NAME}}
-
-Welcome to DQL. Start by connecting a warehouse (`cdql.yaml`), then replace
-this cell with your first query.
-
----
-type: sql
-name: first_query
----
-
-select 1 as hello;

package/templates/jaffle-shop/blocks/finance/revenue_by_segment.dql

@@ -1,23 +0,0 @@
-// dql-format: 1
-
-block revenue_by_segment {
-  domain: "finance"
-  owner: "analytics@{{PROJECT_NAME}}.local"
-  tags: ["revenue", "sample"]
-  description: "Gross revenue grouped by customer segment."
-
-  query: |
-    select
-      c.segment,
-      sum(o.order_total) as revenue,
-      count(distinct o.customer_id) as customers
-    from orders o
-    join customers c on c.customer_id = o.customer_id
-    group by 1
-    order by revenue desc
-
-  visualization: bar(x: "segment", y: "revenue", title: "Revenue by segment")
-
-  tests:
-    - row_count > 0
-}

package/templates/jaffle-shop/cdql.yaml

@@ -1,17 +0,0 @@
-project:
-  name: {{PROJECT_NAME}}
-  version: 1
-
-connections:
-  default:
-    driver: duckdb
-    path: ./warehouse.duckdb
-
-# Remove this block if you aren't using dbt. DQL reads target/manifest.json
-# directly — see https://docs.duckcode.ai/guides/import-dbt/
-dbt:
-  projectDir: {{DBT_PROJECT_DIR}}
-  manifestPath: target/manifest.json
-
-governance:
-  required_fields: [domain, owner, description]

package/templates/jaffle-shop/notebooks/welcome.dql

@@ -1,44 +0,0 @@
-// dql-format: 1
-
-// Welcome to DQL. This notebook runs against a DuckDB-backed Jaffle Shop
-// dataset — the same demo data dbt ships. Press ⌘↵ on each cell.
-
----
-type: markdown
----
-
-# {{PROJECT_NAME}}
-
-A tour of DQL in four cells. Run them top-to-bottom.
-
----
-type: sql
-name: orders_overview
----
-
-select
-  count(*)                  as total_orders,
-  count(distinct customer_id) as unique_customers,
-  sum(order_total)          as lifetime_revenue
-from orders;
-
----
-type: sql
-name: daily_revenue
----
-
-select
-  order_date,
-  sum(order_total) as revenue
-from orders
-group by 1
-order by 1;
-
----
-type: dql
-name: revenue_by_segment
----
-
-// Reference a certified block. The block lives in blocks/finance/ and can
-// be reused across notebooks, dashboards, and other blocks.
-@block("revenue_by_segment")