@duckcodeailabs/dql-cli 0.1.0 → 0.1.2

package/dist/assets/templates/starter/README.md

@@ -0,0 +1,54 @@
+# __PROJECT_NAME__
+
+This starter gives you a local-first DQL project that is ready for parsing,
+previewing, notebook exploration, and experimentation.
+
+```text
+blocks/
+dashboards/
+data/
+dql.config.json
+notebooks/
+workbooks/
+semantic-layer/
+  metrics/
+  dimensions/
+  hierarchies/
+  blocks/
+```
+
+## Quick Start
+
+```bash
+dql doctor
+dql notebook
+dql new block "Pipeline Health"
+dql new semantic-block "ARR Growth"
+dql new dashboard "Revenue Overview"
+dql new workbook "Quarterly Review"
+dql parse blocks/pipeline_health.dql
+dql preview blocks/pipeline_health.dql --open
+dql build blocks/pipeline_health.dql
+dql serve dist/pipeline_health
+```
+
+## What's Included
+
+- `blocks/` — example charted and query-only DQL blocks
+- `dashboards/` — empty folder for dashboard scaffolds
+- `data/` — sample revenue CSV for local DuckDB/file preview flows
+- `dql.config.json` — starter project configuration
+- `notebooks/welcome.dqlnb` — guided notebook walkthrough for the browser notebook
+- `workbooks/` — empty folder for workbook scaffolds
+- `semantic-layer/` — example metrics, dimensions, hierarchies, and companion metadata
+
+## Adopt the Starter Safely
+
+- start in local file mode first
+- keep sample datasets under `data/`
+- run `dql doctor` before previewing if setup feels off
+- add tests to every reusable block
+
+## Learn More
+
+- See the main DQL documentation for `project-config` and `data-sources` guidance.

package/dist/assets/templates/starter/blocks/revenue_by_segment.dql

@@ -0,0 +1,29 @@
+block "Revenue by Segment" {
+    domain = "revenue"
+    type = "custom"
+    description = "Starter block for segment revenue analysis using local CSV sample data"
+    tags = ["starter", "revenue"]
+    owner = "template"
+
+    params {
+        period = "current_quarter"
+    }
+
+    query = """
+        SELECT segment_tier AS segment, SUM(amount) AS revenue
+        FROM read_csv_auto('./data/revenue.csv')
+        WHERE fiscal_period = ${period}
+        GROUP BY segment_tier
+        ORDER BY revenue DESC
+    """
+
+    visualization {
+        chart = "bar"
+        x = segment
+        y = revenue
+    }
+
+    tests {
+        assert row_count > 0
+    }
+}

package/dist/assets/templates/starter/blocks/revenue_trend_query_only.dql

@@ -0,0 +1,20 @@
+block "Revenue Trend Query" {
+    domain = "revenue"
+    type = "custom"
+    description = "Starter query-only block for monthly revenue trends using local CSV sample data"
+    tags = ["starter", "revenue", "query-only"]
+    owner = "template"
+
+    query = """
+        SELECT
+            DATE_TRUNC('month', CAST(recognized_at AS DATE)) AS revenue_month,
+            SUM(amount) AS total_revenue
+        FROM read_csv_auto('./data/revenue.csv')
+        GROUP BY 1
+        ORDER BY 1
+    """
+
+    tests {
+        assert row_count > 0
+    }
+}

package/dist/assets/templates/starter/dashboards/.gitkeep

@@ -0,0 +1 @@
+

package/dist/assets/templates/starter/data/revenue.csv

@@ -0,0 +1,13 @@
+recognized_at,segment_tier,amount,fiscal_period,fiscal_year,fiscal_quarter
+2025-01-03,Enterprise,185000,current_quarter,2025,Q1
+2025-01-14,Mid-Market,92000,current_quarter,2025,Q1
+2025-01-25,SMB,28000,current_quarter,2025,Q1
+2025-02-05,Enterprise,210000,current_quarter,2025,Q1
+2025-02-09,Mid-Market,101000,current_quarter,2025,Q1
+2025-02-18,SMB,31000,current_quarter,2025,Q1
+2025-03-02,Enterprise,223000,current_quarter,2025,Q1
+2025-03-11,Mid-Market,108000,current_quarter,2025,Q1
+2025-03-19,SMB,34000,current_quarter,2025,Q1
+2025-04-07,Enterprise,205000,next_quarter,2025,Q2
+2025-04-16,Mid-Market,99000,next_quarter,2025,Q2
+2025-04-23,SMB,29000,next_quarter,2025,Q2

package/dist/assets/templates/starter/dql.config.json

@@ -0,0 +1,13 @@
+{
+  "project": "__PROJECT_NAME__",
+  "defaultConnection": {
+    "driver": "file",
+    "filepath": ":memory:"
+  },
+  "dataDir": "./data",
+  "preview": {
+    "port": 3474,
+    "open": true,
+    "theme": "dark"
+  }
+}

package/dist/assets/templates/starter/semantic-layer/blocks/revenue_by_segment.yaml

@@ -0,0 +1,11 @@
+name: revenue_by_segment
+block: revenue_by_segment
+domain: revenue
+description: Optional companion metadata for the starter block
+tags:
+  - revenue
+  - starter
+semanticMappings:
+  segment: segment_tier
+  revenue: total_revenue
+reviewStatus: draft

package/dist/assets/templates/starter/semantic-layer/dimensions/segment_tier.yaml

@@ -0,0 +1,6 @@
+name: segment_tier
+label: Segment Tier
+description: Customer segment tier
+sql: segment_tier
+type: string
+table: fct_revenue

package/dist/assets/templates/starter/semantic-layer/hierarchies/revenue_time.yaml

@@ -0,0 +1,12 @@
+name: revenue_time
+label: Revenue Time
+description: Example fiscal calendar hierarchy
+domain: revenue
+levels:
+  - name: fiscal_year
+    dimension: fiscal_year
+    order: 1
+  - name: fiscal_quarter
+    dimension: fiscal_quarter
+    order: 2
+defaultRollup: sum

package/dist/assets/templates/starter/semantic-layer/metrics/revenue.yaml

@@ -0,0 +1,7 @@
+name: total_revenue
+label: Total Revenue
+description: Sum of recognized revenue
+domain: revenue
+sql: SUM(amount)
+type: sum
+table: fct_revenue

package/dist/assets/templates/starter/workbooks/.gitkeep

@@ -0,0 +1 @@
+

package/dist/assets/templates/taxi/README.md

@@ -0,0 +1,19 @@
+# __PROJECT_NAME__
+
+This template packages a city mobility analytics sandbox with taxi trip data.
+
+## Included assets
+
+- `blocks/revenue_by_segment.dql` — trip volume by pickup borough
+- `blocks/airport_mix.dql` — airport trip fare mix
+- `dashboards/city_operations.dql` — operations dashboard with fares and trip counts
+- `data/trips.csv` — local taxi trip sample dataset
+- `notebooks/welcome.dqlnb` — browser notebook walkthrough
+
+## Quick start
+
+```bash
+dql doctor
+dql notebook
+dql preview blocks/revenue_by_segment.dql --open
+```

package/dist/assets/templates/taxi/blocks/airport_mix.dql

@@ -0,0 +1,25 @@
+block "Airport Fare Mix" {
+    domain = "mobility"
+    type = "custom"
+    description = "Average fare for airport versus non-airport trips"
+    tags = ["taxi", "airport"]
+    owner = "template"
+
+    query = """
+        SELECT CASE WHEN airport_flag THEN 'Airport' ELSE 'City' END AS trip_type,
+               ROUND(AVG(fare_amount), 2) AS avg_fare
+        FROM read_csv_auto('./data/trips.csv')
+        GROUP BY trip_type
+        ORDER BY avg_fare DESC
+    """
+
+    visualization {
+        chart = "bar"
+        x = trip_type
+        y = avg_fare
+    }
+
+    tests {
+        assert row_count > 0
+    }
+}

package/dist/assets/templates/taxi/blocks/revenue_by_segment.dql

@@ -0,0 +1,24 @@
+block "Trips by Borough" {
+    domain = "mobility"
+    type = "custom"
+    description = "Trip count by pickup borough"
+    tags = ["taxi", "operations"]
+    owner = "template"
+
+    query = """
+        SELECT pickup_borough, COUNT(*) AS revenue
+        FROM read_csv_auto('./data/trips.csv')
+        GROUP BY pickup_borough
+        ORDER BY revenue DESC
+    """
+
+    visualization {
+        chart = "bar"
+        x = pickup_borough
+        y = revenue
+    }
+
+    tests {
+        assert row_count > 0
+    }
+}

package/dist/assets/templates/taxi/dashboards/city_operations.dql

@@ -0,0 +1,25 @@
+dashboard "City Operations" {
+  chart.kpi(
+    SELECT COUNT(*) AS total_trips
+    FROM read_csv_auto('./data/trips.csv'),
+    metrics = ["total_trips"],
+    title = "Total Trips"
+  )
+
+  chart.line(
+    SELECT pickup_hour, ROUND(AVG(fare_amount), 2) AS avg_fare
+    FROM read_csv_auto('./data/trips.csv')
+    GROUP BY pickup_hour
+    ORDER BY pickup_hour,
+    x = pickup_hour,
+    y = avg_fare,
+    title = "Average Fare by Hour"
+  )
+
+  chart.table(
+    SELECT pickup_date, pickup_borough, dropoff_borough, trip_miles, fare_amount, tip_amount
+    FROM read_csv_auto('./data/trips.csv')
+    ORDER BY fare_amount DESC,
+    title = "Highest Fare Trips"
+  )
+}

package/dist/assets/templates/taxi/data/trips.csv

@@ -0,0 +1,13 @@
+trip_id,pickup_date,pickup_hour,pickup_borough,dropoff_borough,payment_type,fare_amount,tip_amount,trip_miles,airport_flag
+T-001,2025-01-03,6,Manhattan,Queens,Card,32.5,6.2,8.4,true
+T-002,2025-01-03,7,Brooklyn,Manhattan,Card,21.4,4.1,5.6,false
+T-003,2025-01-04,8,Queens,Manhattan,Cash,27.8,0,7.1,true
+T-004,2025-01-04,9,Manhattan,Brooklyn,Card,18.9,3.7,4.9,false
+T-005,2025-01-05,11,Bronx,Manhattan,Card,25.7,5.1,6.8,false
+T-006,2025-01-05,12,Manhattan,Queens,Card,34.2,6.8,8.9,true
+T-007,2025-01-06,13,Queens,Brooklyn,Card,19.3,3.5,5.2,false
+T-008,2025-01-06,15,Manhattan,Manhattan,Card,14.6,3.2,2.8,false
+T-009,2025-01-07,17,Brooklyn,Queens,Cash,16.8,0,4.1,false
+T-010,2025-01-07,18,Manhattan,Staten Island,Card,41.1,7.4,12.3,false
+T-011,2025-01-08,19,Queens,Manhattan,Card,29.6,5.9,7.7,true
+T-012,2025-01-08,21,Brooklyn,Manhattan,Card,22.1,4.6,5.9,false

package/dist/assets/templates/taxi/dql.config.json

@@ -0,0 +1,13 @@
+{
+  "project": "__PROJECT_NAME__",
+  "defaultConnection": {
+    "driver": "file",
+    "filepath": ":memory:"
+  },
+  "dataDir": "./data",
+  "preview": {
+    "port": 3474,
+    "open": true,
+    "theme": "dark"
+  }
+}

package/dist/assets/templates/taxi/semantic-layer/.gitkeep

@@ -0,0 +1 @@
+

package/dist/assets/templates/taxi/workbooks/.gitkeep

@@ -0,0 +1 @@
+

package/dist/commands/build.d.ts

@@ -0,0 +1,3 @@
+import type { CLIFlags } from '../args.js';
+export declare function runBuild(filePath: string, flags: CLIFlags): Promise<void>;
+//# sourceMappingURL=build.d.ts.map

package/dist/commands/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAwC/E"}

package/dist/commands/build.js

@@ -0,0 +1,41 @@
+import { mkdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { compile, writeBundle } from '@duckcodeailabs/dql-compiler';
+import { findProjectRoot, loadProjectConfig } from '../local-runtime.js';
+export async function runBuild(filePath, flags) {
+    const absoluteFile = resolve(filePath);
+    const projectRoot = findProjectRoot(dirname(absoluteFile));
+    const config = loadProjectConfig(projectRoot);
+    const source = readFileSync(absoluteFile, 'utf-8');
+    const result = compile(source, {
+        file: absoluteFile,
+        theme: config.preview?.theme ?? 'light',
+    });
+    if (result.errors.length > 0) {
+        throw new Error(`Build failed:\n${result.errors.map((e) => `- ${e}`).join('\n')}`);
+    }
+    if (result.dashboards.length === 0) {
+        throw new Error('Build requires a charted block, dashboard, or workbook that compiles to HTML output.');
+    }
+    const name = basename(absoluteFile, extname(absoluteFile));
+    const outDir = resolve(flags.outDir || join(projectRoot, 'dist', name));
+    mkdirSync(outDir, { recursive: true });
+    writeBundle(result.dashboards[0], outDir);
+    if (flags.format === 'json') {
+        console.log(JSON.stringify({
+            source: absoluteFile,
+            outDir,
+            built: true,
+            files: ['index.html', 'dql-metadata.json', 'specs/'],
+        }, null, 2));
+        return;
+    }
+    console.log(`\n  ✓ Built DQL bundle`);
+    console.log(`    Source: ${absoluteFile}`);
+    console.log(`    Output: ${outDir}`);
+    console.log('');
+    console.log('  Next step:');
+    console.log(`    dql serve ${outDir}`);
+    console.log('');
+}
+//# sourceMappingURL=build.js.map

package/dist/commands/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEpE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAEzE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,QAAgB,EAAE,KAAe;IAC9D,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,WAAW,GAAG,eAAe,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE;QAC7B,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,IAAI,OAAO;KACxC,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,kBAAkB,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrF,CAAC;IAED,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,sFAAsF,CAAC,CAAC;IAC1G,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IACxE,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAE1C,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC5B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;YACzB,MAAM,EAAE,YAAY;YACpB,MAAM;YACN,KAAK,EAAE,IAAI;YACX,KAAK,EAAE,CAAC,YAAY,EAAE,mBAAmB,EAAE,QAAQ,CAAC;SACrD,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACb,OAAO;IACT,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;IACtC,OAAO,CAAC,GAAG,CAAC,eAAe,YAAY,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,eAAe,MAAM,EAAE,CAAC,CAAC;IACrC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC5B,OAAO,CAAC,GAAG,CAAC,iBAAiB,MAAM,EAAE,CAAC,CAAC;IACvC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAClB,CAAC"}

package/dist/commands/build.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=build.test.d.ts.map

package/dist/commands/build.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.test.d.ts","sourceRoot":"","sources":["../../src/commands/build.test.ts"],"names":[],"mappings":""}

package/dist/commands/build.test.js

@@ -0,0 +1,42 @@
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { describe, expect, it } from 'vitest';
+import { runBuild } from './build.js';
+describe('runBuild', () => {
+    it('writes an HTML bundle and metadata for a standalone block', async () => {
+        const projectDir = mkdtempSync(join(tmpdir(), 'dql-build-'));
+        const sourcePath = join(projectDir, 'sample.dql');
+        const outDir = join(projectDir, 'out');
+        writeFileSync(sourcePath, `block "Revenue Preview" {
+  domain = "revenue"
+  type = "custom"
+  query = """
+    SELECT 'Enterprise' AS segment, 100 AS revenue
+  """
+  visualization {
+    chart = "bar"
+    x = segment
+    y = revenue
+  }
+}`);
+        await runBuild(sourcePath, {
+            check: false,
+            chart: '',
+            domain: '',
+            format: 'json',
+            help: false,
+            open: null,
+            input: '',
+            outDir,
+            owner: '',
+            port: null,
+            queryOnly: false,
+            template: 'starter',
+            verbose: false,
+        });
+        expect(readFileSync(join(outDir, 'index.html'), 'utf-8')).toContain('Revenue Preview');
+        expect(readFileSync(join(outDir, 'dql-metadata.json'), 'utf-8')).toContain('Revenue Preview');
+    });
+});
+//# sourceMappingURL=build.test.js.map

package/dist/commands/build.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.test.js","sourceRoot":"","sources":["../../src/commands/build.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;IACxB,EAAE,CAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;QACzE,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC;QAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAEvC,aAAa,CAAC,UAAU,EAAE;;;;;;;;;;;EAW5B,CAAC,CAAC;QAEA,MAAM,QAAQ,CAAC,UAAU,EAAE;YACzB,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,EAAE;YACV,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,KAAK;YACX,IAAI,EAAE,IAAI;YACV,KAAK,EAAE,EAAE;YACT,MAAM;YACN,KAAK,EAAE,EAAE;YACT,IAAI,EAAE,IAAI;YACV,SAAS,EAAE,KAAK;YAChB,QAAQ,EAAE,SAAS;YACnB,OAAO,EAAE,KAAK;SACf,CAAC,CAAC;QAEH,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;QACvF,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;IAChG,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,3 @@
+import type { CLIFlags } from '../args.js';
+export declare function runDoctor(targetPath: string | null, flags: CLIFlags): Promise<void>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAS3C,wBAAsB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAmEzF"}

package/dist/commands/doctor.js

@@ -0,0 +1,127 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { QueryExecutor } from '@duckcodeailabs/dql-connectors';
+import { assertLocalQueryRuntimeReady, findProjectRoot, loadProjectConfig } from '../local-runtime.js';
+export async function runDoctor(targetPath, flags) {
+    const cwd = resolve(targetPath || '.');
+    const projectRoot = findProjectRoot(cwd);
+    const config = loadProjectConfig(projectRoot);
+    const checks = [
+        checkNodeVersion(),
+        {
+            name: 'Project root',
+            ok: existsSync(projectRoot),
+            detail: projectRoot,
+        },
+        {
+            name: 'dql.config.json',
+            ok: existsSync(join(projectRoot, 'dql.config.json')),
+            detail: existsSync(join(projectRoot, 'dql.config.json')) ? 'found' : 'missing',
+        },
+        {
+            name: 'blocks/',
+            ok: existsSync(join(projectRoot, 'blocks')),
+            detail: existsSync(join(projectRoot, 'blocks')) ? 'found' : 'missing',
+        },
+        {
+            name: 'semantic-layer/',
+            ok: existsSync(join(projectRoot, 'semantic-layer')),
+            detail: existsSync(join(projectRoot, 'semantic-layer')) ? 'found' : 'missing',
+        },
+        {
+            name: 'data/',
+            ok: existsSync(join(projectRoot, 'data')),
+            detail: existsSync(join(projectRoot, 'data')) ? 'found' : 'missing',
+        },
+        {
+            name: 'Default connection',
+            ok: Boolean(config.defaultConnection?.driver),
+            detail: config.defaultConnection?.driver ? `driver=${config.defaultConnection.driver}` : 'not configured',
+        },
+    ];
+    if (config.defaultConnection?.driver === 'file' || config.defaultConnection?.driver === 'duckdb') {
+        checks.push(checkDuckDBDependency(projectRoot));
+    }
+    if (config.defaultConnection?.driver) {
+        checks.push(await checkLocalQueryRuntime(projectRoot, config.defaultConnection));
+    }
+    const passed = checks.filter((check) => check.ok).length;
+    if (flags.format === 'json') {
+        console.log(JSON.stringify({
+            ok: passed === checks.length,
+            projectRoot,
+            checks,
+        }, null, 2));
+        return;
+    }
+    console.log(`\n  DQL Doctor`);
+    console.log(`    Project: ${projectRoot}`);
+    console.log('');
+    for (const check of checks) {
+        console.log(`  ${check.ok ? '✓' : '✗'} ${check.name}`);
+        console.log(`    ${check.detail}`);
+    }
+    console.log('');
+    console.log(`  Summary: ${passed}/${checks.length} checks passed`);
+    console.log('');
+}
+function checkNodeVersion() {
+    const match = process.versions.node.match(/^(\d+)/);
+    const major = match ? Number(match[1]) : 0;
+    return {
+        name: 'Node.js',
+        ok: major >= 18,
+        detail: `version=${process.versions.node} (requires >= 18)`,
+    };
+}
+function checkDuckDBDependency(projectRoot) {
+    const packageJsonPath = join(projectRoot, 'package.json');
+    if (!existsSync(packageJsonPath)) {
+        return {
+            name: 'duckdb dependency',
+            ok: true,
+            detail: 'no project package.json; skipping dependency check',
+        };
+    }
+    try {
+        const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+        const hasDuckDB = Boolean(pkg.dependencies?.duckdb || pkg.devDependencies?.duckdb);
+        return {
+            name: 'duckdb dependency',
+            ok: hasDuckDB,
+            detail: hasDuckDB ? 'duckdb listed in package.json' : 'add duckdb for file/duckdb local preview support',
+        };
+    }
+    catch {
+        return {
+            name: 'duckdb dependency',
+            ok: false,
+            detail: 'failed to parse package.json',
+        };
+    }
+}
+async function checkLocalQueryRuntime(projectRoot, connection) {
+    const previousCwd = process.cwd();
+    const executor = new QueryExecutor();
+    try {
+        process.chdir(projectRoot);
+        await assertLocalQueryRuntimeReady(executor, connection);
+        return {
+            name: 'Local query runtime',
+            ok: true,
+            detail: `driver=${connection.driver} is available`,
+        };
+    }
+    catch (error) {
+        return {
+            name: 'Local query runtime',
+            ok: false,
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        process.chdir(previousCwd);
+        await executor.disconnect().catch(() => { });
+    }
+}
+//# sourceMappingURL=doctor.js.map

package/dist/commands/doctor.js.map

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

package/dist/commands/doctor.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=doctor.test.d.ts.map

package/dist/commands/doctor.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.test.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.test.ts"],"names":[],"mappings":""}

package/dist/commands/doctor.test.js

@@ -0,0 +1,41 @@
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { describe, expect, it, vi } from 'vitest';
+import { runDoctor } from './doctor.js';
+describe('runDoctor', () => {
+    it('reports health for a starter-like project', async () => {
+        const projectDir = mkdtempSync(join(tmpdir(), 'dql-doctor-'));
+        mkdirSync(join(projectDir, 'blocks'));
+        mkdirSync(join(projectDir, 'semantic-layer'));
+        mkdirSync(join(projectDir, 'data'));
+        writeFileSync(join(projectDir, 'dql.config.json'), JSON.stringify({
+            defaultConnection: { driver: 'file', filepath: ':memory:' },
+        }, null, 2));
+        writeFileSync(join(projectDir, 'package.json'), JSON.stringify({
+            dependencies: { duckdb: '^1.1.0' },
+        }, null, 2));
+        const spy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        await runDoctor(projectDir, {
+            check: false,
+            chart: '',
+            domain: '',
+            format: 'text',
+            help: false,
+            open: null,
+            input: '',
+            outDir: '',
+            owner: '',
+            port: null,
+            queryOnly: false,
+            template: 'starter',
+            verbose: false,
+        });
+        expect(spy).toHaveBeenCalled();
+        const output = spy.mock.calls.flat().join('\n');
+        expect(output).toContain('DQL Doctor');
+        expect(output).toContain('blocks/');
+        spy.mockRestore();
+    });
+});
+//# sourceMappingURL=doctor.test.js.map

package/dist/commands/doctor.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.test.js","sourceRoot":"","sources":["../../src/commands/doctor.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;IACzB,EAAE,CAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;QACzD,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;QAC9D,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;QACtC,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC;QAC9C,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;QACpC,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,iBAAiB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC;YAChE,iBAAiB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE;SAC5D,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACb,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC;YAC7D,YAAY,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;SACnC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAEb,MAAM,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAElE,MAAM,SAAS,CAAC,UAAU,EAAE;YAC1B,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,EAAE;YACV,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,KAAK;YACX,IAAI,EAAE,IAAI;YACV,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,EAAE;YACV,KAAK,EAAE,EAAE;YACT,IAAI,EAAE,IAAI;YACV,SAAS,EAAE,KAAK;YAChB,QAAQ,EAAE,SAAS;YACnB,OAAO,EAAE,KAAK;SACf,CAAC,CAAC;QAEH,MAAM,CAAC,GAAG,CAAC,CAAC,gBAAgB,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChD,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QACpC,GAAG,CAAC,WAAW,EAAE,CAAC;IACpB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/commands/init.d.ts

@@ -0,0 +1,3 @@
+import type { CLIFlags } from '../args.js';
+export declare function runInit(targetArg: string | null, flags: CLIFlags): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAkB3C,wBAAsB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CA2DtF"}