@hypequery/cli 1.3.1 → 1.5.0

package/README.md

@@ -4,9 +4,10 @@ CLI for scaffolding and running the main hypequery path.
 
 Use it to:
 
-- generate schema types from ClickHouse
+- generate schema types from ClickHouse or embedded chDB
 - scaffold `analytics/` files
 - run the local dev server with docs
+- build and validate portable deployment contracts
 
 ## Quick Start
 
@@ -36,27 +37,36 @@ npx hypequery init
 
 It will:
 
-- generate schema types
+- connect to ClickHouse or start an embedded chDB session
+- generate schema types when the database is available
 - create client and query files
-- write `.env` values
-- update `.gitignore`
-- install scaffold dependencies, including `zod`
+- write `.env` values for ClickHouse connections
+- update `.gitignore`, including a project-local persistent chDB directory
+- install scaffold dependencies, including `zod` and the selected database adapter
 
 Options:
 
 - `--path <path>`: output directory, default `analytics/`
 - `--style <style>`: `queries` (default) or `datasets`
+- `--database <type>`: `clickhouse` (default) or `chdb`
+- `--chdb-path <path>`: persistent chDB data directory; omit for an in-memory session
 - `--auth <mode>`: `none` (default) or `context`
 - `--all-tables`: with `--style datasets`, scaffold every table
 - `--tables <names>`: with `--style datasets`, scaffold these comma-separated tables
 - `--exclude-tables <names>`: with `--style datasets`, exclude these comma-separated tables
 - `--no-example`: skip the example query
-- `--no-interactive`: read connection details from env vars
+- `--no-interactive`: skip prompts; ClickHouse connection details come from env vars
 - `--force`: overwrite existing scaffold files
-- `--skip-connection`: skip testing the ClickHouse connection before scaffolding
+- `--skip-connection`: skip testing the selected database before scaffolding
 
 Set `HYPEQUERY_SKIP_INSTALL=1` to skip the automatic dependency install.
 
+To scaffold against persistent embedded chDB without server credentials:
+
+```bash
+npx hypequery init --database chdb --chdb-path ./analytics.chdb --no-interactive
+```
+
 ### `hypequery dev`
 
 Runs the local serve runtime with docs and hot reload.
@@ -78,7 +88,7 @@ The CLI understands TypeScript entry files directly, so `analytics/queries.ts` w
 
 ### `hypequery generate`
 
-Regenerates schema types from ClickHouse.
+Regenerates schema types from ClickHouse or embedded chDB.
 
 ```bash
 npx hypequery generate
@@ -89,7 +99,14 @@ Options:
 - `--output <path>`: default `analytics/schema.ts`
 - `--path <path>`: analytics directory (derives `<path>/schema.ts`)
 - `--tables <names>`: comma-separated table list
-- `--database <type>`: currently `clickhouse`
+- `--database <type>`: `clickhouse` or `chdb`; chDB generation must be selected explicitly
+- `--chdb-path <path>`: persistent chDB data directory; omit for an in-memory session
+
+For a persistent chDB scaffold, pass the same path used by `init`:
+
+```bash
+npx hypequery generate --database chdb --chdb-path ./analytics.chdb
+```
 
 `hypequery generate:types` is an alias for `hypequery generate`.
 
@@ -119,9 +136,42 @@ npx hypequery generate:manifest analytics/api.ts --output analytics/hypequery-ma
 The output is the exact serializable JSON returned by `api.manifest()`, including
 semantic keys such as `dataset:orders`.
 
+### `hypequery deployment:build`
+
+Builds deployment metadata for an exported HypeQuery API and writes the
+artifact with its identity sidecar.
+
+```bash
+npx hypequery deployment:build analytics/api.ts \
+  --runtime-artifact 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+```
+
+The runtime artifact digest is required when named Serve handlers cannot be
+lowered to a portable implementation. Dataset-only APIs can omit it.
+
+Options:
+
+- `--output <path>`: default `analytics/hypequery-deployment.json`
+- `--runtime <runtime>`: `node` (default) or `python`
+- `--runtime-artifact <sha256>`: lowercase SHA-256 of the built runtime artifact
+- `--entrypoint-prefix <prefix>`: default `queries`
+- `--hash-output <path>`: default `<output>.sha256`
+
+The identity sidecar is not compatible with `sha256sum -c`. Use
+`deployment:validate` to validate the artifact and report its identity.
+
+### `hypequery deployment:validate`
+
+Validates an existing deployment artifact and reports its datasets, queries,
+runtime artifacts, and identity.
+
+```bash
+npx hypequery deployment:validate analytics/hypequery-deployment.json
+```
+
 ## Non-interactive Setup
 
-`hypequery init --no-interactive` reads:
+For ClickHouse, `hypequery init --no-interactive` reads:
 
 - `CLICKHOUSE_URL` or deprecated `CLICKHOUSE_HOST`
 - `CLICKHOUSE_DATABASE`
@@ -133,6 +183,7 @@ semantic keys such as `dataset:orders`.
 - 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
+- chDB runs in memory unless `--chdb-path` is provided; persistent paths must be reused by later `generate` commands
 
 ## Docs
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AAgID,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AAwJD,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/cli.js

@@ -6,6 +6,7 @@ import { devCommand } from './commands/dev.js';
 import { generateCommand } from './commands/generate.js';
 import { generateDatasetsCommand } from './commands/generate-datasets.js';
 import { generateManifestCommand } from './commands/generate-manifest.js';
+import { buildDeploymentCommand, validateDeploymentCommand, } from './commands/deployment.js';
 const program = new Command();
 function getCliVersion() {
     try {
@@ -43,7 +44,8 @@ function addTypeGenerationOptions(command) {
         .option('-o, --output <path>', 'Output file (default: analytics/schema.ts)')
         .option('--path <path>', 'Analytics directory (derives <path>/schema.ts)')
         .option('--tables <names>', 'Only generate for specific tables (comma-separated)')
-        .option('--database <type>', 'Database driver to use (default: auto-detect)');
+        .option('--database <type>', 'Database driver to use: clickhouse or chdb (default: auto-detect)')
+        .option('--chdb-path <path>', 'Embedded chDB data directory (with --database chdb; omit for in-memory)');
 }
 // Init command
 program
@@ -51,6 +53,8 @@ program
     .description('Initialize a new hypequery project')
     .option('--path <path>', 'Output directory (default: analytics/)')
     .option('--style <style>', 'Scaffold style: queries or datasets')
+    .option('--database <type>', 'Database driver: clickhouse (default) or chdb for embedded, zero-server ClickHouse')
+    .option('--chdb-path <path>', 'Embedded chDB data directory (with --database chdb; omit for in-memory)')
     .option('--auth <mode>', 'Auth scaffold mode: none or context')
     .option('--all-tables', 'Generate datasets for all discovered tables when using --style datasets')
     .option('--tables <names>', 'Generate datasets for specific tables when using --style datasets (comma-separated)')
@@ -105,6 +109,23 @@ program
     .action(runCommand(async (api, options) => {
     await generateManifestCommand(api, options);
 }));
+program
+    .command('deployment:build <api>')
+    .description('Build a validated, canonical deployment contract and identity')
+    .option('-o, --output <path>', 'Output JSON file (default: analytics/hypequery-deployment.json)')
+    .option('--runtime <runtime>', 'Runtime for non-portable handlers: node or python (default: node)')
+    .option('--runtime-artifact <sha256>', 'SHA-256 identity of the built runtime artifact')
+    .option('--entrypoint-prefix <prefix>', 'Runtime entrypoint prefix (default: queries)')
+    .option('--hash-output <path>', 'Deployment identity sidecar path (default: <output>.sha256)')
+    .action(runCommand(async (api, options) => {
+    await buildDeploymentCommand(api, options);
+}));
+program
+    .command('deployment:validate <artifact>')
+    .description('Validate a deployment contract and report its identity')
+    .action(runCommand(async (artifact) => {
+    await validateDeploymentCommand(artifact);
+}));
 // Help command
 program
     .command('help [command]')
@@ -135,6 +156,8 @@ program.on('--help', () => {
     console.log('  hypequery generate:types --output analytics/schema.ts');
     console.log('  hypequery generate:datasets');
     console.log('  hypequery generate:manifest analytics/api.ts --output analytics/hypequery-manifest.json');
+    console.log('  hypequery deployment:build analytics/api.ts --runtime-artifact <sha256>');
+    console.log('  hypequery deployment:validate analytics/hypequery-deployment.json');
     console.log('');
     console.log('Docs: https://hypequery.com/docs');
 });

package/dist/commands/deployment.d.ts

@@ -0,0 +1,11 @@
+import { type ProtocolDeploymentContract } from '@hypequery/protocol';
+export interface BuildDeploymentOptions {
+    output?: string;
+    runtime?: 'node' | 'python';
+    runtimeArtifact?: string;
+    entrypointPrefix?: string;
+    hashOutput?: string;
+}
+export declare function buildDeploymentCommand(apiPath: string | undefined, options?: BuildDeploymentOptions): Promise<ProtocolDeploymentContract>;
+export declare function validateDeploymentCommand(artifactPath: string | undefined): Promise<ProtocolDeploymentContract>;
+//# sourceMappingURL=deployment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deployment.d.ts","sourceRoot":"","sources":["../../src/commands/deployment.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAM7B,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8BD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CAuCrC;AAED,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CAoCrC"}

package/dist/commands/deployment.js

@@ -0,0 +1,84 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { prepareProtocolDeploymentContract, } from '@hypequery/protocol';
+import { loadApiModule } from '../utils/load-api.js';
+import { logger } from '../utils/logger.js';
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+function runtimeArtifact(options) {
+    if (options.runtimeArtifact === undefined)
+        return undefined;
+    if (!SHA256_PATTERN.test(options.runtimeArtifact)) {
+        throw new Error('--runtime-artifact must be a lowercase 64-character SHA-256 digest.');
+    }
+    const runtime = options.runtime ?? 'node';
+    if (runtime !== 'node' && runtime !== 'python') {
+        throw new Error('--runtime must be either node or python.');
+    }
+    return {
+        runtime,
+        artifactSha256: options.runtimeArtifact,
+        ...(options.entrypointPrefix !== undefined
+            ? { entrypointPrefix: options.entrypointPrefix }
+            : {}),
+    };
+}
+export async function buildDeploymentCommand(apiPath, options = {}) {
+    if (!apiPath) {
+        throw new Error('Missing API module path.\n\n'
+            + 'Usage: hypequery deployment:build analytics/api.ts');
+    }
+    const artifact = runtimeArtifact(options);
+    const api = await loadApiModule(apiPath);
+    if (typeof api.deploymentContract !== 'function') {
+        throw new Error(`Invalid API module: ${apiPath}\n\n`
+            + 'The exported API must provide deploymentContract(). '
+            + 'Upgrade @hypequery/serve and export the value returned by createAPI() or serve().');
+    }
+    const contract = api.deploymentContract(artifact ? { runtimeArtifact: artifact } : {});
+    const prepared = prepareProtocolDeploymentContract(contract);
+    const { canonical, contract: validated, identity: digest } = prepared;
+    const outputPath = options.output ?? 'analytics/hypequery-deployment.json';
+    const hashOutputPath = options.hashOutput ?? `${outputPath}.sha256`;
+    const identitySidecar = [
+        '# Hypequery deployment identity v1; not a file checksum or sha256sum input.',
+        '# SHA-256(UTF-8("hypequery:deployment:v1") || 0x00 || RFC 8785 canonical bytes); '
+            + 'the output newline is excluded.',
+        `${digest}  ${path.basename(outputPath)}`,
+        '',
+    ].join('\n');
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    await mkdir(path.dirname(hashOutputPath), { recursive: true });
+    await writeFile(outputPath, `${canonical}\n`, 'utf8');
+    await writeFile(hashOutputPath, identitySidecar, 'utf8');
+    logger.success(`Deployment contract written to ${outputPath}`);
+    logger.info(`Identity: ${digest}`);
+    return validated;
+}
+export async function validateDeploymentCommand(artifactPath) {
+    if (!artifactPath) {
+        throw new Error('Missing deployment artifact path.\n\n'
+            + 'Usage: hypequery deployment:validate analytics/hypequery-deployment.json');
+    }
+    let input;
+    try {
+        input = JSON.parse(await readFile(artifactPath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Invalid deployment JSON: ${artifactPath}\n\n`
+            + (error instanceof Error ? error.message : String(error)));
+    }
+    let prepared;
+    try {
+        prepared = prepareProtocolDeploymentContract(input);
+    }
+    catch (error) {
+        throw new Error(`Invalid deployment contract: ${artifactPath}\n\n`
+            + (error instanceof Error ? error.message : String(error)));
+    }
+    const { contract, identity: digest } = prepared;
+    logger.success(`Valid deployment contract: ${artifactPath}`);
+    logger.info(`${contract.datasets.length} datasets, ${contract.queries.length} queries, `
+        + `${contract.artifacts.length} runtime artifacts`);
+    logger.info(`Identity: ${digest}`);
+    return contract;
+}

package/dist/commands/generate.d.ts

@@ -4,6 +4,7 @@ export interface GenerateOptions {
     path?: string;
     tables?: string;
     database?: DatabaseType;
+    chdbPath?: string;
     commandName?: string;
 }
 export declare function generateCommand(options?: GenerateOptions): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/commands/generate.ts"],"names":[],"mappings":"AAIA,OAAO,EAAiC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAI/F,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,eAAe,CAAC,OAAO,GAAE,eAAoB,iBA4HlE"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/commands/generate.ts"],"names":[],"mappings":"AAIA,OAAO,EAAiC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAK/F,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,eAAe,CAAC,OAAO,GAAE,eAAoB,iBAoJlE"}

package/dist/commands/generate.js

@@ -3,6 +3,7 @@ import ora from 'ora';
 import { logger } from '../utils/logger.js';
 import { findSchemaFile } from '../utils/find-files.js';
 import { detectDatabase, getTableCount } from '../utils/detect-database.js';
+import { ensureChdbInstalled } from '../utils/chdb-client.js';
 import { getTypeGenerator } from '../generators/index.js';
 import { redactConnectionUrl } from '../utils/redact-connection-url.js';
 export async function generateCommand(options = {}) {
@@ -33,20 +34,38 @@ export async function generateCommand(options = {}) {
         : undefined;
     const requestedDbType = options.database;
     const dbType = requestedDbType ?? (await detectDatabase());
+    const chdbPath = dbType === 'chdb' ? options.chdbPath : undefined;
+    if (dbType === 'chdb' && !requestedDbType) {
+        throw new Error('chDB generation must be explicit. Re-run with --database chdb and add --chdb-path <dir> for persistent storage.');
+    }
     logger.newline();
     logger.header(options.commandName ?? 'hypequery generate');
     const spinner = ora(`Connecting to ${dbType}...`).start();
+    let activeSpinner = spinner;
+    let failureMessage = dbType === 'chdb'
+        ? 'Failed to start embedded chDB'
+        : 'Failed to generate types';
     try {
         const generator = getTypeGenerator(dbType);
+        // Surface a missing chdb install as the connection failure it is —
+        // getTableCount swallows errors, so without this probe the spinner
+        // would report a successful connection and 0 tables before type
+        // generation fails.
+        if (dbType === 'chdb') {
+            await ensureChdbInstalled();
+        }
         // Get table count
-        const tableCount = await getTableCount(dbType);
-        spinner.succeed(`Connected to ${dbType === 'clickhouse' ? 'ClickHouse' : dbType}`);
+        const tableCount = await getTableCount(dbType, { chdbPath });
+        spinner.succeed(`Connected to ${dbType === 'clickhouse' ? 'ClickHouse' : dbType === 'chdb' ? 'embedded chDB' : dbType}`);
         logger.success(`Found ${tableCount} tables`);
         // Generate types
         const typeSpinner = ora('Generating types...').start();
+        activeSpinner = typeSpinner;
+        failureMessage = 'Failed to generate types';
         await generator({
             outputPath,
             includeTables: parsedTables,
+            chdbPath,
         });
         typeSpinner.succeed(`Generated types for ${tableCount} tables`);
         logger.success(`Updated ${path.relative(process.cwd(), outputPath)}`);
@@ -55,7 +74,7 @@ export async function generateCommand(options = {}) {
         logger.newline();
     }
     catch (error) {
-        spinner.fail('Failed to generate types');
+        activeSpinner.fail(failureMessage);
         logger.newline();
         if (error instanceof Error) {
             logger.error(error.message);

package/dist/commands/init.d.ts

@@ -3,6 +3,8 @@ import { type AuthTemplateMode } from '../templates/queries.js';
 export interface InitOptions {
     path?: string;
     style?: InitStyle;
+    database?: string;
+    chdbPath?: string;
     allTables?: boolean;
     tables?: string;
     excludeTables?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAIA,OAAO,EAUL,KAAK,SAAS,EACf,MAAM,qBAAqB,CAAC;AAS7B,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAQzF,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAwFD,wBAAsB,WAAW,CAAC,OAAO,GAAE,WAAgB,iBAsT1D"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAIA,OAAO,EAWL,KAAK,SAAS,EACf,MAAM,qBAAqB,CAAC;AAe7B,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAQzF,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AA4JD,wBAAsB,WAAW,CAAC,OAAO,GAAE,WAAgB,iBAyZ1D"}