@hypequery/cli 1.1.0 → 1.1.2

package/README.md

@@ -1,211 +1,109 @@
 # @hypequery/cli
 
-Command-line interface for Hypequery - the type-safe analytics layer for ClickHouse.
+CLI for scaffolding and running the main hypequery path.
 
-## Quick Start
+Use it to:
 
-The CLI scaffolds and runs the main hypequery path:
+- generate schema types from ClickHouse
+- scaffold `analytics/` files
+- run the local dev server with docs
 
-1. Generate schema types from ClickHouse
-2. Build queries with the typed query builder
-3. Wrap reusable queries with `query({ ... })`
-4. Add `serve({ queries })` when you want HTTP routes and docs
+## Quick Start
 
-Use `npx` to run commands directly:
+Run it directly:
 
 ```bash
-# Initialize a new project
 npx @hypequery/cli init
-
-# Start development server
 npx @hypequery/cli dev
-
-# Generate types from database
 npx @hypequery/cli generate
 ```
 
-## Installation (Optional)
-
-For frequent use, install as a dev dependency:
+Or install it once:
 
 ```bash
 npm install -D @hypequery/cli
-# or
-pnpm add -D @hypequery/cli
-# or
-yarn add -D @hypequery/cli
 ```
 
-Then use the shorter `hypequery` command:
-
-```bash
-npx hypequery dev
-```
-
-Or add to your `package.json` scripts:
-
-```json
-{
-  "scripts": {
-    "hypequery:init": "hypequery init",
-    "hypequery:dev": "hypequery dev",
-    "hypequery:generate": "hypequery generate"
-  }
-}
-```
-
-## TypeScript Support
-
-`hypequery dev` bundles a TypeScript runtime (powered by `tsx`), so pointing it at `analytics/queries.ts` or any `.ts/.tsx` file just works—no extra install or custom runner required. If your project already compiles to JavaScript you can keep targeting the generated `.js` file instead.
-
 ## Commands
 
 ### `hypequery init`
 
-Interactive setup wizard that scaffolds a new Hypequery project.
+Scaffolds the standard hypequery setup.
 
 ```bash
-# Without installation
-npx @hypequery/cli init
-
-# With installation
 npx hypequery init
 ```
 
-**What it does:**
-- Connects to your ClickHouse database
-- Generates TypeScript types from your schema
-- Creates the client, query, and serve files for the main path
-- Sets up `.env` with connection details
-- Updates `.gitignore` to protect secrets
-
-**Options:**
-- `--database <type>` - Database type (currently only `clickhouse`)
-- `--path <path>` - Output directory (default: `analytics/`)
-- `--no-example` - Skip example query generation
-- `--no-interactive` - Non-interactive mode (uses environment variables)
-- `--force` - Overwrite existing files without confirmation
-
-**Example:**
-```bash
-# Interactive mode (recommended)
-npx @hypequery/cli init
+It will:
 
-# Non-interactive with custom path
-npx @hypequery/cli init --path src/analytics --no-interactive
-```
+- generate schema types
+- create client and query files
+- write `.env` values
+- update `.gitignore`
+- install scaffold dependencies, including `zod`
+
+Options:
+
+- `--path <path>`: output directory, default `analytics/`
+- `--no-example`: skip the example query
+- `--no-interactive`: read connection details from env vars
+- `--force`: overwrite existing scaffold files
+- `--skip-connection`: skip testing the ClickHouse connection before scaffolding
 
 ### `hypequery dev`
 
-Start development server with live reload and query playground.
+Runs the local serve runtime with docs and hot reload.
 
 ```bash
-# Without installation
-npx @hypequery/cli dev
-
-# With installation
 npx hypequery dev
-
-# With TypeScript file
-npx @hypequery/cli dev src/analytics/queries.ts
 ```
 
-**What it does:**
-- Starts a local HTTP server for your queries
-- Provides interactive API documentation at `/docs`
-- Auto-reloads on file changes
-- Displays query execution stats
-
-**Options:**
-- `-p, --port <port>` - Port number (default: `4000`)
-- `-h, --hostname <host>` - Hostname to bind (default: `localhost`)
-- `--no-watch` - Disable file watching
-- `--cache <provider>` - Cache provider (`memory` | `redis` | `none`)
-- `--open` - Open browser automatically
-- `--cors` - Enable CORS
-- `-q, --quiet` - Suppress startup messages
-
-**Example:**
-```bash
-# Basic usage
-npx @hypequery/cli dev
+Options:
 
-# Custom port with browser auto-open
-npx @hypequery/cli dev --port 3000 --open
+- `--port <port>`: default `4000`
+- `--hostname <host>`: default `localhost`
+- `--no-watch`: disable file watching
+- `--cache <provider>`: `memory`, `redis`, or `none`
+- `--open`: open the browser automatically
+- `--cors`: enable CORS
+- `--quiet`: reduce startup output
 
-# Disable caching for debugging
-npx @hypequery/cli dev --cache none
-```
-
-**Common Issues:**
-
-If you see "Unexpected token" errors while loading your queries, double-check that you're pointing the CLI at the TypeScript source file (e.g. `analytics/queries.ts`). The CLI bundles the loader and should not require additional dependencies.
+The CLI understands TypeScript entry files directly, so `analytics/queries.ts` works without an extra runner.
 
 ### `hypequery generate`
 
-Regenerate TypeScript types from ClickHouse schema.
+Regenerates schema types from ClickHouse.
 
 ```bash
-# Without installation
-npx @hypequery/cli generate
-
-# With installation
 npx hypequery generate
 ```
 
-The CLI bundles the ClickHouse driver directly, so you can run this command without installing `@hypequery/clickhouse`. Specify `--database <type>` once additional drivers become available.
+Options:
 
-**What it does:**
-- Connects to ClickHouse
-- Introspects your database schema
-- Generates TypeScript interfaces for all tables
-- Updates your schema file with type-safe definitions
+- `--output <path>`: default `analytics/schema.ts`
+- `--tables <names>`: comma-separated table list
+- `--database <type>`: currently `clickhouse`
 
-**Options:**
-- `-o, --output <path>` - Output file (default: `analytics/schema.ts`)
-- `--tables <names>` - Only generate for specific tables (comma-separated)
-- `--database <type>` - Override detected database (currently only `clickhouse`)
+## Non-interactive Setup
 
-**Example:**
-```bash
-# Generate all tables
-npx @hypequery/cli generate
-
-# Generate specific tables
-npx @hypequery/cli generate --tables users,events
-
-# Custom output path
-npx @hypequery/cli generate --output src/schema.ts
-```
+`hypequery init --no-interactive` reads:
 
-## Package Scripts
+- `CLICKHOUSE_URL` or deprecated `CLICKHOUSE_HOST`
+- `CLICKHOUSE_DATABASE`
+- `CLICKHOUSE_USERNAME` or `CLICKHOUSE_USER`
+- `CLICKHOUSE_PASSWORD`
 
-Add these to your `package.json` for easy access:
-
-```json
-{
-  "scripts": {
-    "db:init": "hypequery init",
-    "db:dev": "hypequery dev",
-    "db:generate": "hypequery generate"
-  }
-}
-```
-
-Then run with:
-```bash
-npm run db:dev
-```
+## Notes
 
-## Documentation
+- generated scaffold files use NodeNext-safe local `.js` imports
+- `CLICKHOUSE_URL` is now the preferred connection variable
+- the CLI bundles the ClickHouse driver for schema generation
 
-Visit the main docs flow:
+## Docs
 
-- [Quick Start](https://hypequery.com/docs/quick-start)
-- [Core Concepts](https://hypequery.com/docs/core-concepts)
-- [Query Building](https://hypequery.com/docs/query-building/basics)
-- [Serve Runtime Reference](https://hypequery.com/docs/reference/runtime)
+- [Quick start](https://hypequery.com/docs/quick-start)
+- [CLI reference](https://hypequery.com/docs/reference/api/cli)
 
 ## License
 
-Apache-2.0
+Apache-2.0.

package/dist/cli.d.ts

@@ -1,4 +1,7 @@
 import { Command } from 'commander';
 declare const program: Command;
+export declare function normalizeInitOptions(options: Record<string, unknown>): {
+    noInteractive: boolean;
+};
 export { program };
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AA8F9B,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAE9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AA6FD,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/cli.js

@@ -1,3 +1,14 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -39,6 +50,9 @@ import { initCommand } from './commands/init.js';
 import { devCommand } from './commands/dev.js';
 import { generateCommand } from './commands/generate.js';
 var program = new Command();
+export function normalizeInitOptions(options) {
+    return __assign(__assign({}, options), { noInteractive: options.noInteractive === true || options.interactive === false });
+}
 program
     .name('hypequery')
     .description('Type-safe analytics layer for ClickHouse')
@@ -47,7 +61,6 @@ program
 program
     .command('init')
     .description('Initialize a new hypequery project')
-    .option('--database <type>', 'Database type (clickhouse|bigquery)')
     .option('--path <path>', 'Output directory (default: analytics/)')
     .option('--no-example', 'Skip example query generation')
     .option('--no-interactive', 'Non-interactive mode (use env vars)')
@@ -59,7 +72,7 @@ program
         switch (_a.label) {
             case 0:
                 _a.trys.push([0, 2, , 3]);
-                return [4 /*yield*/, initCommand(options)];
+                return [4 /*yield*/, initCommand(normalizeInitOptions(options))];
             case 1:
                 _a.sent();
                 return [3 /*break*/, 3];

package/dist/commands/generate.js

@@ -118,7 +118,7 @@ export function generateCommand() {
                             logger.indent('• Firewall blocking connection');
                             logger.newline();
                             logger.info('Check your configuration:');
-                            logger.indent('CLICKHOUSE_HOST=' + (process.env.CLICKHOUSE_HOST || 'not set'));
+                            logger.indent('CLICKHOUSE_URL=' + (process.env.CLICKHOUSE_URL || process.env.CLICKHOUSE_HOST || 'not set'));
                             logger.newline();
                             logger.info('Docs: https://hypequery.com/docs/troubleshooting#connection-errors');
                         }

package/dist/commands/init.d.ts

@@ -1,5 +1,4 @@
 export interface InitOptions {
-    database?: string;
     path?: string;
     noExample?: boolean;
     noInteractive?: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAgFD,wBAAsB,WAAW,CAAC,OAAO,GAAE,WAAgB,iBAoO1D"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAiED,wBAAsB,WAAW,CAAC,OAAO,GAAE,WAAgB,iBAwO1D"}