@hypequery/cli 1.4.0 → 1.5.0

package/README.md

@@ -7,6 +7,7 @@ Use it to:
 - 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
 
@@ -135,6 +136,39 @@ 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
 
 For ClickHouse, `hypequery init --no-interactive` reads:

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;AAmID,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 {
@@ -108,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]')
@@ -138,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/cli",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Command-line interface for hypequery",
   "license": "Apache-2.0",
   "type": "module",
@@ -18,7 +18,8 @@
     "esbuild": "^0.25.0",
     "open": "^10.0.0",
     "ora": "^8.0.1",
-    "prompts": "^2.4.2"
+    "prompts": "^2.4.2",
+    "@hypequery/protocol": "0.3.0"
   },
   "peerDependencies": {
     "@hypequery/clickhouse": "*",
@@ -36,7 +37,7 @@
     "typescript": "^5.7.3",
     "vitest": "^3.2.6",
     "@hypequery/clickhouse": "2.4.0",
-    "@hypequery/serve": "0.11.0"
+    "@hypequery/serve": "0.12.0"
   },
   "repository": {
     "type": "git",