@hypequery/cli 1.4.0 → 1.6.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,40 @@ 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
+```
+
+Named Serve handlers are bundled into a Node runtime artifact automatically.
+Dataset-only APIs do not produce a runtime artifact. Use `--runtime-artifact`
+to reference a separately built Node or Python artifact instead.
+
+Options:
+
+- `--output <path>`: default `analytics/hypequery-deployment.json`
+- `--runtime <runtime>`: `node` (default) or `python`
+- `--runtime-artifact <sha256>`: lowercase SHA-256 of a prebuilt runtime artifact
+- `--runtime-output <path>`: default beside the deployment JSON as `hypequery-runtime.mjs`
+- `--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;AAyJD,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,24 @@ 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>', 'Use a prebuilt runtime artifact with this SHA-256 identity')
+    .option('--runtime-output <path>', 'Bundled Node runtime path (default: beside deployment JSON)')
+    .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 +157,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,12 @@
+import { type ProtocolDeploymentContract } from '@hypequery/protocol';
+export interface BuildDeploymentOptions {
+    output?: string;
+    runtime?: 'node' | 'python';
+    runtimeArtifact?: string;
+    runtimeOutput?: 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;AAW7B,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAkDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CA0FrC;AAED,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CAoCrC"}

package/dist/commands/deployment.js

@@ -0,0 +1,145 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { prepareProtocolDeploymentContract, } from '@hypequery/protocol';
+import { buildNodeRuntimeArtifact, getDeploymentRuntimeEntrypoints, } from '../utils/deployment-runtime-artifact.js';
+import { loadApiModule } from '../utils/load-api.js';
+import { logger } from '../utils/logger.js';
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+function runtimeName(options) {
+    const runtime = options.runtime ?? 'node';
+    if (runtime !== 'node' && runtime !== 'python') {
+        throw new Error('--runtime must be either node or python.');
+    }
+    return runtime;
+}
+function configuredRuntimeArtifact(options, runtime) {
+    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.');
+    }
+    return {
+        runtime,
+        artifactSha256: options.runtimeArtifact,
+        ...(options.entrypointPrefix !== undefined
+            ? { entrypointPrefix: options.entrypointPrefix }
+            : {}),
+    };
+}
+function assertDistinctOutputPaths(paths) {
+    const seen = new Map();
+    for (const [label, value] of Object.entries(paths)) {
+        if (value === undefined)
+            continue;
+        const resolved = path.resolve(value);
+        const existing = seen.get(resolved);
+        if (existing) {
+            throw new Error(`${label} must use a different path from ${existing}.`);
+        }
+        seen.set(resolved, label);
+    }
+}
+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 runtime = runtimeName(options);
+    const configuredArtifact = configuredRuntimeArtifact(options, runtime);
+    if (configuredArtifact && options.runtimeOutput !== undefined) {
+        throw new Error('--runtime-output cannot be used with a prebuilt --runtime-artifact.');
+    }
+    const outputPath = options.output ?? 'analytics/hypequery-deployment.json';
+    const hashOutputPath = options.hashOutput ?? `${outputPath}.sha256`;
+    if (options.runtimeOutput !== undefined) {
+        assertDistinctOutputPaths({
+            '--output': outputPath,
+            '--hash-output': hashOutputPath,
+            '--runtime-output': options.runtimeOutput,
+        });
+    }
+    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().');
+    }
+    let builtArtifact;
+    let artifact = configuredArtifact;
+    if (!artifact) {
+        const runtimeEntrypoints = getDeploymentRuntimeEntrypoints(api);
+        if (runtimeEntrypoints.length > 0) {
+            if (runtime !== 'node') {
+                throw new Error('Automatic runtime artifact builds currently support Node only. '
+                    + 'Provide --runtime-artifact for Python deployments.');
+            }
+            builtArtifact = await buildNodeRuntimeArtifact(apiPath, runtimeEntrypoints, options.entrypointPrefix);
+            artifact = {
+                runtime: 'node',
+                artifactSha256: builtArtifact.artifactSha256,
+                entrypointPrefix: builtArtifact.entrypointPrefix,
+            };
+        }
+    }
+    const contract = api.deploymentContract(artifact ? { runtimeArtifact: artifact } : {});
+    const prepared = prepareProtocolDeploymentContract(contract);
+    const { canonical, contract: validated, identity: digest } = prepared;
+    const runtimeOutputPath = builtArtifact
+        ? options.runtimeOutput ?? path.join(path.dirname(outputPath), 'hypequery-runtime.mjs')
+        : undefined;
+    assertDistinctOutputPaths({
+        '--output': outputPath,
+        '--hash-output': hashOutputPath,
+        '--runtime-output': runtimeOutputPath,
+    });
+    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 });
+    if (runtimeOutputPath && builtArtifact) {
+        await mkdir(path.dirname(runtimeOutputPath), { recursive: true });
+        await writeFile(runtimeOutputPath, builtArtifact.bytes);
+    }
+    await writeFile(outputPath, `${canonical}\n`, 'utf8');
+    await writeFile(hashOutputPath, identitySidecar, 'utf8');
+    if (runtimeOutputPath && builtArtifact) {
+        logger.success(`Runtime artifact written to ${runtimeOutputPath}`);
+        logger.info(`Runtime artifact SHA-256: ${builtArtifact.artifactSha256}`);
+    }
+    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/utils/deployment-runtime-artifact.d.ts

@@ -0,0 +1,9 @@
+export interface NodeRuntimeArtifact {
+    readonly bytes: Uint8Array;
+    readonly artifactSha256: string;
+    readonly entrypointPrefix: string;
+    readonly runtimeEntrypoints: readonly string[];
+}
+export declare function getDeploymentRuntimeEntrypoints(input: unknown): readonly string[];
+export declare function buildNodeRuntimeArtifact(apiPath: string, runtimeEntrypoints: readonly string[], entrypointPrefix?: string): Promise<NodeRuntimeArtifact>;
+//# sourceMappingURL=deployment-runtime-artifact.d.ts.map

package/dist/utils/deployment-runtime-artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-runtime-artifact.d.ts","sourceRoot":"","sources":["../../src/utils/deployment-runtime-artifact.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD;AASD,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CA6BjF;AA6CD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,EACf,kBAAkB,EAAE,SAAS,MAAM,EAAE,EACrC,gBAAgB,SAAY,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CAmD9B"}

package/dist/utils/deployment-runtime-artifact.js

@@ -0,0 +1,142 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { parseProtocolIdentifier, parseProtocolQualifiedIdentifier, } from '@hypequery/protocol';
+import { build } from 'esbuild';
+import { findNearestTsconfig } from './load-api.js';
+const deploymentBuildSourceSymbol = Symbol.for('hypequery.deployment-build-source.v1');
+function executableQuery(query) {
+    return typeof query === 'function'
+        || (typeof query === 'object'
+            && query !== null
+            && typeof query.run === 'function');
+}
+export function getDeploymentRuntimeEntrypoints(input) {
+    if (typeof input !== 'object' || input === null) {
+        throw new Error('Invalid API module: deployment build metadata is unavailable.');
+    }
+    const api = input;
+    const source = api[deploymentBuildSourceSymbol];
+    if (source?.version !== 1 || !Array.isArray(source.runtimeEntrypoints)) {
+        throw new Error('The exported API does not expose deployment build metadata. '
+            + 'Upgrade @hypequery/serve before building runtime artifacts.');
+    }
+    const names = source.runtimeEntrypoints.map((name) => {
+        try {
+            return parseProtocolIdentifier(name);
+        }
+        catch {
+            throw new Error(`Invalid runtime entrypoint name: ${String(name)}`);
+        }
+    });
+    if (new Set(names).size !== names.length) {
+        throw new Error('Deployment build metadata contains duplicate runtime entrypoints.');
+    }
+    for (const name of names) {
+        if (!executableQuery(api.queries?.[name]?.query)) {
+            throw new Error(`Serve query "${name}" does not expose an executable runtime handler.`);
+        }
+    }
+    return Object.freeze([...names].sort());
+}
+function projectRelativeImport(apiPath) {
+    const resolved = path.resolve(process.cwd(), apiPath);
+    const relative = path.relative(process.cwd(), resolved);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error('The API module must be inside the current project for deterministic bundling.');
+    }
+    const portable = relative.split(path.sep).join('/');
+    return {
+        resolved,
+        specifier: portable.startsWith('.') ? portable : `./${portable}`,
+    };
+}
+function runtimeEntrySource(apiSpecifier, runtimeEntrypoints, entrypointPrefix) {
+    const prefix = parseProtocolQualifiedIdentifier(entrypointPrefix).split('.');
+    const names = JSON.stringify(runtimeEntrypoints);
+    let registryExpression = 'runtimeEntries';
+    for (let index = prefix.length - 1; index >= 1; index -= 1) {
+        registryExpression = `Object.freeze({ ${prefix[index]}: ${registryExpression} })`;
+    }
+    return [
+        `import * as apiModule from ${JSON.stringify(apiSpecifier)};`,
+        'const api = apiModule.api ?? Reflect.get(apiModule, "default");',
+        'if (!api || typeof api !== "object") throw new Error("Runtime API export is unavailable.");',
+        'const resolveQuery = (name) => {',
+        '  const query = api.queries?.[name]?.query;',
+        '  if (typeof query === "function") return query;',
+        '  if (query && typeof query === "object" && typeof query.run === "function") {',
+        '    return query.run.bind(query);',
+        '  }',
+        '  throw new Error(`Runtime entrypoint ${name} is unavailable.`);',
+        '};',
+        `const runtimeEntries = Object.freeze(Object.fromEntries(${names}.map(name => [name, resolveQuery(name)])));`,
+        `export const ${prefix[0]} = ${registryExpression};`,
+        '',
+    ].join('\n');
+}
+export async function buildNodeRuntimeArtifact(apiPath, runtimeEntrypoints, entrypointPrefix = 'queries') {
+    if (runtimeEntrypoints.length === 0) {
+        throw new Error('Cannot build a runtime artifact without Serve query entrypoints.');
+    }
+    const names = getValidatedEntrypointNames(runtimeEntrypoints);
+    const { resolved, specifier } = projectRelativeImport(apiPath);
+    let source;
+    try {
+        source = runtimeEntrySource(specifier, names, entrypointPrefix);
+    }
+    catch {
+        throw new Error(`Invalid runtime entrypoint prefix: ${entrypointPrefix}`);
+    }
+    try {
+        const result = await build({
+            stdin: {
+                contents: source,
+                loader: 'ts',
+                resolveDir: process.cwd(),
+                sourcefile: 'hypequery-runtime-entry.ts',
+            },
+            absWorkingDir: process.cwd(),
+            bundle: true,
+            charset: 'utf8',
+            format: 'esm',
+            legalComments: 'none',
+            logLevel: 'warning',
+            minify: true,
+            platform: 'node',
+            sourcemap: false,
+            target: ['node18'],
+            treeShaking: true,
+            tsconfig: await findNearestTsconfig(resolved) ?? undefined,
+            write: false,
+        });
+        const output = result.outputFiles?.find(file => file.path.endsWith('.js'))
+            ?? result.outputFiles?.[0];
+        if (!output)
+            throw new Error('esbuild produced no output');
+        const bytes = output.contents;
+        return Object.freeze({
+            bytes,
+            artifactSha256: createHash('sha256').update(bytes).digest('hex'),
+            entrypointPrefix,
+            runtimeEntrypoints: names,
+        });
+    }
+    catch (error) {
+        throw new Error(`Failed to build the Node runtime artifact from ${apiPath}.\n`
+            + `Original error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function getValidatedEntrypointNames(input) {
+    const names = input.map((name) => {
+        try {
+            return parseProtocolIdentifier(name);
+        }
+        catch {
+            throw new Error(`Invalid runtime entrypoint name: ${name}`);
+        }
+    });
+    if (new Set(names).size !== names.length) {
+        throw new Error('Runtime entrypoint names must be unique.');
+    }
+    return Object.freeze([...names].sort());
+}

package/dist/utils/load-api.d.ts

@@ -1,3 +1,4 @@
 export declare function loadApiModule(modulePath: string): Promise<any>;
 export declare function loadModule(modulePath: string): Promise<any>;
+export declare function findNearestTsconfig(filePath: string): Promise<string | null>;
 //# sourceMappingURL=load-api.d.ts.map

package/dist/utils/load-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-api.d.ts","sourceRoot":"","sources":["../../src/utils/load-api.ts"],"names":[],"mappings":"AAaA,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,gBA2DrD;AAED,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,gBAkClD"}
+{"version":3,"file":"load-api.d.ts","sourceRoot":"","sources":["../../src/utils/load-api.ts"],"names":[],"mappings":"AAaA,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,gBA2DrD;AAED,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,gBAkClD;AA0JD,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,0BA8BzD"}

package/dist/utils/load-api.js

@@ -217,7 +217,7 @@ async function bundleTypeScriptModule(entryPath) {
             `Original error: ${error?.message ?? error}`);
     }
 }
-async function findNearestTsconfig(filePath) {
+export async function findNearestTsconfig(filePath) {
     let dir = path.dirname(filePath);
     const visited = [];
     while (dir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/cli",
-  "version": "1.4.0",
+  "version": "1.6.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.13.0"
   },
   "repository": {
     "type": "git",