@hypequery/cli 1.5.0 → 1.6.0

package/README.md

@@ -142,18 +142,19 @@ 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
+npx hypequery deployment:build analytics/api.ts
 ```
 
-The runtime artifact digest is required when named Serve handlers cannot be
-lowered to a portable implementation. Dataset-only APIs can omit it.
+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 the built runtime artifact
+- `--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`
 

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;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"}
+{"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

@@ -114,7 +114,8 @@ program
     .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('--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) => {

package/dist/commands/deployment.d.ts

@@ -3,6 +3,7 @@ export interface BuildDeploymentOptions {
     output?: string;
     runtime?: 'node' | 'python';
     runtimeArtifact?: string;
+    runtimeOutput?: string;
     entrypointPrefix?: string;
     hashOutput?: string;
 }

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

@@ -1 +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"}
+{"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

@@ -1,19 +1,23 @@
 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 runtimeArtifact(options) {
+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.');
     }
-    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,
@@ -22,23 +26,72 @@ function runtimeArtifact(options) {
             : {}),
     };
 }
+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 artifact = runtimeArtifact(options);
+    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 outputPath = options.output ?? 'analytics/hypequery-deployment.json';
-    const hashOutputPath = options.hashOutput ?? `${outputPath}.sha256`;
+    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); '
@@ -48,8 +101,16 @@ export async function buildDeploymentCommand(apiPath, options = {}) {
     ].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;

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.5.0",
+  "version": "1.6.0",
   "description": "Command-line interface for hypequery",
   "license": "Apache-2.0",
   "type": "module",
@@ -37,7 +37,7 @@
     "typescript": "^5.7.3",
     "vitest": "^3.2.6",
     "@hypequery/clickhouse": "2.4.0",
-    "@hypequery/serve": "0.12.0"
+    "@hypequery/serve": "0.13.0"
   },
   "repository": {
     "type": "git",