create-dql-app 0.11.0

package/README.md

@@ -0,0 +1,40 @@
+# create-dql-app
+
+The fastest way to start a DQL project.
+
+```bash
+npx create-dql-app my-analytics
+cd my-analytics
+npx @duckcodeailabs/dql-cli notebook
+```
+
+Opens a running notebook at <http://localhost:5173> in under 5 minutes on a
+clean machine. No global install required.
+
+## Templates
+
+| Template | What you get |
+| --- | --- |
+| `jaffle-shop` *(default)* | DuckDB + the Jaffle Shop dataset + a sample notebook, certified block, and dashboard |
+| `empty` | Just a `cdql.yaml` and project layout — bring your own warehouse |
+
+```bash
+npx create-dql-app finance-reports --template empty
+```
+
+## Flags
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--template <name>` | `jaffle-shop` | Starter template |
+| `--no-install` | off | Skip downloading the Jaffle Shop seed data |
+
+## Docs
+
+- [Quickstart](https://docs.duckcode.ai/get-started/quickstart/)
+- [Concepts](https://docs.duckcode.ai/get-started/concepts/)
+- [Connect your own warehouse](https://docs.duckcode.ai/guides/connect-warehouse/)
+
+## License
+
+MIT

package/bin/create-dql-app.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// create-dql-app — self-contained scaffolder.
+//
+// Contract (from the v1.0 "demo gate"): on a clean machine, `npx
+// create-dql-app` followed by `cd … && npx @duckcodeailabs/dql-cli notebook`
+// produces a running notebook in under 5 minutes.
+//
+// Design: this package writes template files *itself* rather than
+// delegating to `dql init`, so it stays self-contained and installable
+// with zero-peer-dep friction. Templates live under ../templates/ and are
+// copied verbatim.
+
+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 { fileURLToPath } from 'node:url';
+
+const VERSION = '0.11.0';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = resolve(__dirname, '..', 'templates');
+
+// Tiny ANSI helpers — no dep on chalk/kleur so the bin runs before
+// `npm install` finishes on slow machines.
+const c = {
+  cyan:   (s) => `\x1b[36m${s}\x1b[0m`,
+  green:  (s) => `\x1b[32m${s}\x1b[0m`,
+  red:    (s) => `\x1b[31m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  bold:   (s) => `\x1b[1m${s}\x1b[0m`,
+  dim:    (s) => `\x1b[2m${s}\x1b[0m`,
+};
+
+function usage() {
+  console.log(`create-dql-app ${VERSION}
+
+Usage:
+  npx create-dql-app <project-dir> [options]
+
+Options:
+  --template <name>   Starter template: jaffle-shop (default), empty
+  --help, -h          Show this help
+  --version, -v       Show version
+
+Examples:
+  npx create-dql-app my-analytics
+  npx create-dql-app finance-reports --template empty
+`);
+}
+
+function parseArgs(argv) {
+  const args = { dir: null, template: 'jaffle-shop' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') { usage(); process.exit(0); }
+    if (a === '--version' || a === '-v') { console.log(VERSION); process.exit(0); }
+    if (a === '--template') { args.template = argv[++i]; continue; }
+    if (a.startsWith('--')) { console.error(`Unknown flag: ${a}`); process.exit(2); }
+    if (!args.dir) args.dir = a;
+  }
+  return args;
+}
+
+function isEmptyDir(dir) {
+  try { return readdirSync(dir).length === 0; } catch { return true; }
+}
+
+function copyDir(src, dst) {
+  mkdirSync(dst, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const s = join(src, entry);
+    const d = join(dst, entry);
+    if (statSync(s).isDirectory()) copyDir(s, d);
+    else writeFileSync(d, readFileSync(s));
+  }
+}
+
+function substitute(file, vars) {
+  const raw = readFileSync(file, 'utf-8');
+  const out = raw.replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k] ?? `{{${k}}}`);
+  if (out !== raw) writeFileSync(file, out, 'utf-8');
+}
+
+function walk(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    const p = join(dir, entry);
+    if (statSync(p).isDirectory()) out.push(...walk(p));
+    else out.push(p);
+  }
+  return out;
+}
+
+function detectDbtSibling(target) {
+  // Walk up 2 levels looking for a dbt_project.yml — common layout is
+  // myproject/dql + myproject/dbt, or myproject with dbt + dql as siblings.
+  for (const rel of ['..', '../..', '../dbt', '../../dbt']) {
+    const probe = resolve(target, rel, 'dbt_project.yml');
+    if (existsSync(probe)) return resolve(target, rel);
+  }
+  return null;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.dir) {
+    console.error('Error: project directory is required.\n');
+    usage();
+    process.exit(2);
+  }
+
+  const target = resolve(process.cwd(), args.dir);
+  const projectName = basename(target);
+
+  if (existsSync(target) && !isEmptyDir(target)) {
+    console.error(c.red(`✗ Target directory "${args.dir}" exists and is not empty.`));
+    process.exit(1);
+  }
+
+  const tplDir = join(TEMPLATES_DIR, args.template);
+  if (!existsSync(tplDir)) {
+    console.error(c.red(`✗ Unknown template: ${args.template}`));
+    console.error(`   Available: ${readdirSync(TEMPLATES_DIR).join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log(c.cyan(`\n⌁ create-dql-app ${VERSION}`));
+  console.log(`  scaffolding ${c.bold(projectName)} (template: ${c.bold(args.template)})\n`);
+
+  copyDir(tplDir, target);
+
+  const dbtSibling = detectDbtSibling(target);
+  const vars = {
+    PROJECT_NAME: projectName,
+    YEAR: String(new Date().getFullYear()),
+    DBT_PROJECT_DIR: dbtSibling ? resolve(dbtSibling) : '../my-dbt-project',
+    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`));
+  }
+
+  // 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'));
+
+  console.log(`
+${c.green('✓ Ready.')} Next steps:
+
+  ${c.bold(`cd ${args.dir}`)}
+  ${c.bold('npx @duckcodeailabs/dql-cli notebook')}
+
+Your notebook will open at ${c.cyan('http://localhost:5173')}.
+
+Docs:   ${c.cyan('https://docs.duckcode.ai')}
+Issues: ${c.cyan('https://github.com/duckcode-ai/dql/issues')}
+`);
+}
+
+main().catch((e) => {
+  console.error(c.red(`\n✗ ${e.message}`));
+  process.exit(1);
+});

package/package.json

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

package/templates/empty/README.md

@@ -0,0 +1,18 @@
+# {{PROJECT_NAME}}
+
+An empty DQL project, scaffolded by `create-dql-app --template empty`.
+
+## Connect your warehouse
+
+Edit `cdql.yaml` — DQL ships 15 drivers out of the box:
+[docs.duckcode.ai/reference/connectors](https://docs.duckcode.ai/reference/connectors/).
+
+```bash
+npx @duckcodeailabs/dql-cli test-connection
+```
+
+## Start the notebook
+
+```bash
+npx @duckcodeailabs/dql-cli notebook
+```

package/templates/empty/cdql.yaml

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,17 @@
+// 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/README.md

@@ -0,0 +1,34 @@
+# {{PROJECT_NAME}}
+
+A DQL analytics project, scaffolded by `create-dql-app`.
+
+## Run
+
+```bash
+npx @duckcodeailabs/dql-cli notebook
+```
+
+Opens the notebook at <http://localhost:5173>.
+
+## Layout
+
+```
+cdql.yaml              project config (connections, dbt, governance)
+notebooks/             analytics notebooks (.dql)
+blocks/                certified reusable blocks, grouped by domain
+semantic-layer/        metrics + dimensions authored locally
+dashboards/            compiled static HTML dashboards (git-ignored)
+```
+
+## Next steps
+
+1. **Run the welcome notebook** — `notebooks/welcome.dql`
+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/)
+
+## Learn
+
+- [Quickstart](https://docs.duckcode.ai/get-started/quickstart/)
+- [Concepts](https://docs.duckcode.ai/get-started/concepts/)
+- [CLI reference](https://docs.duckcode.ai/reference/cli/)

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

@@ -0,0 +1,23 @@
+// 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

@@ -0,0 +1,17 @@
+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/dashboards/overview.dql

@@ -0,0 +1,22 @@
+// dql-format: 1
+
+dashboard: {
+  title: "{{PROJECT_NAME}} — Overview"
+  description: "Revenue overview generated by create-dql-app."
+  layout: "grid"
+}
+
+---
+type: markdown
+---
+
+# Overview — {{YEAR}}
+
+Compiled with `dql compile dashboards/overview.dql --out build/`. Host the
+resulting HTML anywhere.
+
+---
+type: dql
+---
+
+@block("revenue_by_segment")

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

@@ -0,0 +1,44 @@
+// 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")

package/templates/jaffle-shop/semantic-layer/dimensions/customer.yaml

@@ -0,0 +1,14 @@
+dimensions:
+  - name: segment
+    label: Customer segment
+    type: string
+    sql: segment
+    table: customers
+    domain: finance
+
+  - name: region
+    label: Region
+    type: string
+    sql: region
+    table: customers
+    domain: finance

package/templates/jaffle-shop/semantic-layer/metrics/revenue.yaml

@@ -0,0 +1,9 @@
+metrics:
+  - name: revenue
+    label: Revenue
+    description: Gross revenue across all orders
+    type: sum
+    sql: order_total
+    table: orders
+    domain: finance
+    tags: [revenue, core]