@hypequery/cli 1.7.0 → 1.9.0

package/README.md

@@ -182,6 +182,55 @@ are still accepted for metadata-only validation.
 npx hypequery deployment:validate analytics/hypequery-deployment
 ```
 
+### `hypequery deployment:release`
+
+Prepares a deterministic release request from a verified deployment bundle and
+an explicit project/environment target. This command does not upload, authorize,
+or execute the release.
+
+```bash
+npx hypequery deployment:release analytics/hypequery-deployment \
+  --project my-project \
+  --environment production
+```
+
+The default output is `analytics/hypequery-deployment.release.json`. It is
+written beside the bundle because adding it inside the closed bundle would
+invalidate bundle verification.
+
+Options:
+
+- `--project <project>`: required target project identifier
+- `--environment <environment>`: required target environment identifier
+- `--output <path>`: release JSON path, default beside the bundle
+
+### `hypequery deploy`
+
+Submits a verified deployment bundle with an already-prepared target-bound
+release. The command verifies both inputs again, requires their bundle
+identities to match, and streams only the files declared by the bundle.
+
+```bash
+HYPEQUERY_API_TOKEN=<token> \
+npx hypequery deploy analytics/hypequery-deployment \
+  --release analytics/hypequery-deployment.release.json \
+  --endpoint https://deploy.example.com/v1/releases
+```
+
+The token is accepted only through `HYPEQUERY_API_TOKEN`, keeping it out of
+shell history. The submission endpoint must use HTTPS, may also be supplied by
+`HYPEQUERY_DEPLOYMENT_ENDPOINT`, and must not contain credentials or a URL
+fragment. The release identity is sent as the idempotency key, so an unchanged
+release can be submitted safely again.
+
+This command submits immutable deployment inputs. Activation, status changes,
+promotion, and rollback remain control-plane operations.
+
+Options:
+
+- `--release <path>`: required target-bound release JSON
+- `--endpoint <url>`: HTTPS submission endpoint; defaults to `HYPEQUERY_DEPLOYMENT_ENDPOINT`
+
 ## 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;AAYpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AA2JD,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;AAkBpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AAgLD,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/cli.js

@@ -6,7 +6,8 @@ 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';
+import { buildDeploymentCommand, prepareDeploymentReleaseCommand, validateDeploymentCommand, } from './commands/deployment.js';
+import { deployCommand, } from './commands/deploy.js';
 const program = new Command();
 function getCliVersion() {
     try {
@@ -129,6 +130,23 @@ program
     .action(runCommand(async (artifact) => {
     await validateDeploymentCommand(artifact);
 }));
+program
+    .command('deployment:release <bundle>')
+    .description('Prepare a target-bound release from a verified deployment bundle')
+    .requiredOption('--project <project>', 'Target project identifier')
+    .requiredOption('--environment <environment>', 'Target environment identifier')
+    .option('-o, --output <path>', 'Release JSON path (default: beside the bundle)')
+    .action(runCommand(async (bundle, options) => {
+    await prepareDeploymentReleaseCommand(bundle, options);
+}));
+program
+    .command('deploy <bundle>')
+    .description('Submit a verified deployment bundle and release')
+    .requiredOption('--release <path>', 'Target-bound release JSON path')
+    .option('--endpoint <url>', 'HTTPS submission endpoint (or HYPEQUERY_DEPLOYMENT_ENDPOINT)')
+    .action(runCommand(async (bundle, options) => {
+    await deployCommand(bundle, options);
+}));
 // Help command
 program
     .command('help [command]')
@@ -161,6 +179,8 @@ program.on('--help', () => {
     console.log('  hypequery generate:manifest analytics/api.ts --output analytics/hypequery-manifest.json');
     console.log('  hypequery deployment:build analytics/api.ts');
     console.log('  hypequery deployment:validate analytics/hypequery-deployment');
+    console.log('  hypequery deployment:release analytics/hypequery-deployment --project my-project --environment production');
+    console.log('  hypequery deploy analytics/hypequery-deployment --release analytics/hypequery-deployment.release.json');
     console.log('');
     console.log('Docs: https://hypequery.com/docs');
 });

package/dist/commands/deploy.d.ts

@@ -0,0 +1,11 @@
+import { createHttpDeploymentUploadTransport, type DeploymentSubmissionResponse } from '../utils/deployment-upload.js';
+export interface DeployOptions {
+    release?: string;
+    endpoint?: string;
+}
+export interface DeployDependencies {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly createTransport?: typeof createHttpDeploymentUploadTransport;
+}
+export declare function deployCommand(bundlePath: string | undefined, options?: DeployOptions, dependencies?: DeployDependencies): Promise<DeploymentSubmissionResponse>;
+//# sourceMappingURL=deploy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,mCAAmC,EAEnC,KAAK,4BAA4B,EAElC,MAAM,+BAA+B,CAAC;AAMvC,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,mCAAmC,CAAC;CACvE;AA4DD,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,aAAkB,EAC3B,YAAY,GAAE,kBAAuB,GACpC,OAAO,CAAC,4BAA4B,CAAC,CA0DvC"}

package/dist/commands/deploy.js

@@ -0,0 +1,102 @@
+import { constants, open } from 'node:fs/promises';
+import { prepareProtocolDeploymentReleaseEnvelope, } from '@hypequery/protocol';
+import { verifyDeploymentBundle } from '../utils/deployment-bundle.js';
+import { createHttpDeploymentUploadTransport, DeploymentUploadError, } from '../utils/deployment-upload.js';
+import { logger } from '../utils/logger.js';
+const MAX_RELEASE_FILE_BYTES = 16 * 1024;
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true });
+async function readReleaseFile(releasePath) {
+    let handle;
+    let bytes;
+    let fileFailure;
+    try {
+        handle = await open(releasePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new Error('Release JSON must be a regular file.');
+        if (stat.size > MAX_RELEASE_FILE_BYTES) {
+            throw new Error('Release JSON exceeds 16384 bytes.');
+        }
+        const buffer = new Uint8Array(MAX_RELEASE_FILE_BYTES + 1);
+        let total = 0;
+        while (total < buffer.byteLength) {
+            const { bytesRead } = await handle.read(buffer, total, buffer.byteLength - total, total);
+            if (bytesRead === 0)
+                break;
+            total += bytesRead;
+        }
+        if (total > MAX_RELEASE_FILE_BYTES) {
+            throw new Error('Release JSON exceeds 16384 bytes.');
+        }
+        bytes = buffer.subarray(0, total);
+    }
+    catch (error) {
+        fileFailure = { error };
+    }
+    if (handle) {
+        try {
+            await handle.close();
+        }
+        catch (error) {
+            fileFailure ??= { error };
+        }
+    }
+    if (fileFailure) {
+        throw new Error(`Cannot read deployment release file: ${releasePath}\n\n`
+            + (fileFailure.error instanceof Error
+                ? fileFailure.error.message
+                : String(fileFailure.error)));
+    }
+    try {
+        return JSON.parse(utf8Decoder.decode(bytes));
+    }
+    catch (error) {
+        throw new Error(`Invalid deployment release JSON: ${releasePath}\n\n`
+            + (error instanceof Error ? error.message : String(error)));
+    }
+}
+function requiredConfiguration(value, message) {
+    if (value === undefined || value.length === 0)
+        throw new Error(message);
+    return value;
+}
+export async function deployCommand(bundlePath, options = {}, dependencies = {}) {
+    if (!bundlePath) {
+        throw new Error('Missing deployment bundle path.\n\n'
+            + 'Usage: hypequery deploy analytics/hypequery-deployment '
+            + '--release analytics/hypequery-deployment.release.json');
+    }
+    const releasePath = requiredConfiguration(options.release, 'Missing required --release <path>.');
+    const env = dependencies.env ?? process.env;
+    const endpoint = requiredConfiguration(options.endpoint ?? env.HYPEQUERY_DEPLOYMENT_ENDPOINT, 'Missing deployment endpoint. Pass --endpoint or set HYPEQUERY_DEPLOYMENT_ENDPOINT.');
+    const token = requiredConfiguration(env.HYPEQUERY_API_TOKEN, 'Missing HYPEQUERY_API_TOKEN.');
+    let bundle;
+    try {
+        bundle = await verifyDeploymentBundle(bundlePath);
+    }
+    catch (error) {
+        throw new Error(`Cannot push an invalid deployment bundle: ${bundlePath}\n\n`
+            + (error instanceof Error ? error.message : String(error)));
+    }
+    const releaseInput = await readReleaseFile(releasePath);
+    let release;
+    try {
+        release = prepareProtocolDeploymentReleaseEnvelope(releaseInput);
+    }
+    catch (error) {
+        throw new Error(`Invalid deployment release: ${releasePath}\n\n`
+            + (error instanceof Error ? error.message : String(error)));
+    }
+    if (release.release.bundleIdentity !== bundle.identity) {
+        throw new DeploymentUploadError('HQ_UPLOAD_IDENTITY_MISMATCH', 'Release bundle identity does not match the verified deployment bundle.');
+    }
+    const createTransport = dependencies.createTransport ?? createHttpDeploymentUploadTransport;
+    const transportOptions = { endpoint, token };
+    const result = await createTransport(transportOptions).submit(bundle, release);
+    logger.success(result.status === 'accepted'
+        ? 'Deployment release accepted'
+        : 'Deployment release already exists');
+    logger.info(`Release identity: ${result.releaseIdentity}`);
+    logger.info(`Bundle identity: ${result.bundleIdentity}`);
+    return result;
+}

package/dist/commands/deployment.d.ts

@@ -1,4 +1,4 @@
-import { type ProtocolDeploymentContract } from '@hypequery/protocol';
+import { type ProtocolDeploymentContract, type ProtocolDeploymentReleaseEnvelope } from '@hypequery/protocol';
 export interface BuildDeploymentOptions {
     bundleOutput?: string;
     output?: string;
@@ -9,6 +9,12 @@ export interface BuildDeploymentOptions {
     entrypointPrefix?: string;
     hashOutput?: string;
 }
+export interface PrepareDeploymentReleaseOptions {
+    project?: string;
+    environment?: string;
+    output?: string;
+}
 export declare function buildDeploymentCommand(apiPath: string | undefined, options?: BuildDeploymentOptions): Promise<ProtocolDeploymentContract>;
 export declare function validateDeploymentCommand(artifactPath: string | undefined): Promise<ProtocolDeploymentContract>;
+export declare function prepareDeploymentReleaseCommand(bundlePath: string | undefined, options?: PrepareDeploymentReleaseOptions): Promise<ProtocolDeploymentReleaseEnvelope>;
 //# sourceMappingURL=deployment.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"deployment.d.ts","sourceRoot":"","sources":["../../src/commands/deployment.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAiB7B,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAoDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CAwIrC;AAED,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CA2ErC"}
+{"version":3,"file":"deployment.d.ts","sourceRoot":"","sources":["../../src/commands/deployment.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,0BAA0B,EAC/B,KAAK,iCAAiC,EACvC,MAAM,qBAAqB,CAAC;AAiB7B,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,+BAA+B;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAoDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CAwIrC;AAED,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CA2ErC;AA0DD,wBAAsB,+BAA+B,CACnD,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,iCAAiC,CAAC,CA8C5C"}

package/dist/commands/deployment.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
-import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { prepareProtocolDeploymentContract, } from '@hypequery/protocol';
+import { prepareProtocolDeploymentReleaseEnvelope, prepareProtocolDeploymentContract, } from '@hypequery/protocol';
 import { writeDeploymentBundle, verifyDeploymentBundle, readDeploymentRuntimeFile, } from '../utils/deployment-bundle.js';
 import { buildNodeRuntimeArtifact, getDeploymentRuntimeEntrypoints, } from '../utils/deployment-runtime-artifact.js';
 import { loadApiModule } from '../utils/load-api.js';
@@ -217,3 +217,100 @@ export async function validateDeploymentCommand(artifactPath) {
     logger.info(`Identity: ${digest}`);
     return contract;
 }
+function assertOutputOutsideBundle(bundlePath, outputPath) {
+    const bundle = path.resolve(bundlePath);
+    const output = path.resolve(outputPath);
+    const relative = path.relative(bundle, output);
+    const outside = relative === '..'
+        || relative.startsWith(`..${path.sep}`)
+        || path.isAbsolute(relative);
+    if (relative === '' || !outside) {
+        throw new Error('--output must be outside the closed deployment bundle directory.');
+    }
+}
+async function prospectiveRealPath(inputPath) {
+    let current = path.resolve(inputPath);
+    const missingSegments = [];
+    for (;;) {
+        try {
+            return path.join(await realpath(current), ...missingSegments);
+        }
+        catch (error) {
+            if (!(typeof error === 'object' && error !== null && 'code' in error
+                && error.code === 'ENOENT')) {
+                throw error;
+            }
+            try {
+                const stat = await lstat(current);
+                if (stat.isSymbolicLink()) {
+                    throw new Error('--output must not traverse a dangling symbolic link.');
+                }
+            }
+            catch (lstatError) {
+                if (!(typeof lstatError === 'object' && lstatError !== null && 'code' in lstatError
+                    && lstatError.code === 'ENOENT')) {
+                    throw lstatError;
+                }
+            }
+            const parent = path.dirname(current);
+            if (parent === current)
+                throw error;
+            missingSegments.unshift(path.basename(current));
+            current = parent;
+        }
+    }
+}
+async function assertOutputIsNotSymbolicLink(outputPath) {
+    try {
+        const outputStat = await lstat(outputPath);
+        if (outputStat.isSymbolicLink()) {
+            throw new Error('--output must not be a symbolic link.');
+        }
+    }
+    catch (error) {
+        if (!(typeof error === 'object' && error !== null && 'code' in error
+            && error.code === 'ENOENT')) {
+            throw error;
+        }
+    }
+}
+export async function prepareDeploymentReleaseCommand(bundlePath, options = {}) {
+    if (!bundlePath) {
+        throw new Error('Missing deployment bundle path.\n\n'
+            + 'Usage: hypequery deployment:release analytics/hypequery-deployment '
+            + '--project <project> --environment <environment>');
+    }
+    if (options.project === undefined) {
+        throw new Error('Missing required --project <project>.');
+    }
+    if (options.environment === undefined) {
+        throw new Error('Missing required --environment <environment>.');
+    }
+    const outputPath = options.output ?? `${bundlePath.replace(/[\\/]+$/, '')}.release.json`;
+    assertOutputOutsideBundle(bundlePath, outputPath);
+    let bundle;
+    try {
+        bundle = await verifyDeploymentBundle(bundlePath);
+    }
+    catch (error) {
+        throw new Error(`Cannot prepare a release from an invalid deployment bundle: ${bundlePath}\n\n`
+            + (error instanceof Error ? error.message : String(error)));
+    }
+    assertOutputOutsideBundle(bundle.directory, await prospectiveRealPath(outputPath));
+    const prepared = prepareProtocolDeploymentReleaseEnvelope({
+        kind: 'hypequery-deployment-release',
+        version: 1,
+        bundleIdentity: bundle.identity,
+        target: {
+            project: options.project,
+            environment: options.environment,
+        },
+    });
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    await assertOutputIsNotSymbolicLink(outputPath);
+    await writeFile(outputPath, `${prepared.canonical}\n`, 'utf8');
+    logger.success(`Deployment release written to ${outputPath}`);
+    logger.info(`Release identity: ${prepared.identity}`);
+    logger.info(`Bundle identity: ${bundle.identity}`);
+    return prepared.release;
+}

package/dist/utils/deployment-upload.d.ts

@@ -0,0 +1,42 @@
+import type { ReadableStream } from 'node:stream/web';
+import { type PreparedProtocolDeploymentReleaseEnvelope } from '@hypequery/protocol';
+import { type VerifiedDeploymentBundle } from './deployment-bundle.js';
+export type DeploymentUploadErrorCode = 'HQ_UPLOAD_CONFIGURATION' | 'HQ_UPLOAD_IDENTITY_MISMATCH' | 'HQ_UPLOAD_BUNDLE_CHANGED' | 'HQ_UPLOAD_NETWORK' | 'HQ_UPLOAD_REJECTED' | 'HQ_UPLOAD_INVALID_RESPONSE';
+export declare class DeploymentUploadError extends Error {
+    readonly code: DeploymentUploadErrorCode;
+    readonly status?: number;
+    constructor(code: DeploymentUploadErrorCode, message: string, status?: number);
+}
+export interface DeploymentSubmissionResponse {
+    readonly kind: 'hypequery-deployment-submission';
+    readonly version: 1;
+    readonly status: 'accepted' | 'already-exists';
+    readonly releaseIdentity: string;
+    readonly bundleIdentity: string;
+}
+export interface DeploymentHttpResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: ReadableStream<Uint8Array> | null;
+}
+export interface DeploymentFetchInit {
+    readonly method: 'POST';
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: AsyncIterable<Uint8Array>;
+    readonly duplex: 'half';
+    readonly redirect: 'error';
+    readonly signal: AbortSignal;
+}
+export type DeploymentFetch = (input: string, init: DeploymentFetchInit) => Promise<DeploymentHttpResponse>;
+export interface HttpDeploymentUploadTransportOptions {
+    readonly endpoint: string;
+    readonly token: string;
+    readonly timeoutMs?: number;
+    readonly fetch?: DeploymentFetch;
+}
+export interface DeploymentUploadTransport {
+    submit(bundle: VerifiedDeploymentBundle, release: PreparedProtocolDeploymentReleaseEnvelope): Promise<DeploymentSubmissionResponse>;
+}
+export declare function createHttpDeploymentUploadTransport(options: HttpDeploymentUploadTransportOptions): DeploymentUploadTransport;
+//# sourceMappingURL=deployment-upload.d.ts.map

package/dist/utils/deployment-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-upload.d.ts","sourceRoot":"","sources":["../../src/utils/deployment-upload.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAIL,KAAK,yCAAyC,EAC/C,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,wBAAwB,CAAC;AAQhC,MAAM,MAAM,yBAAyB,GACjC,yBAAyB,GACzB,6BAA6B,GAC7B,0BAA0B,GAC1B,mBAAmB,GACnB,oBAAoB,GACpB,4BAA4B,CAAC;AAEjC,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,IAAI,EAAE,yBAAyB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAM9E;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,gBAAgB,CAAC;IAC/C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,MAAM,eAAe,GAAG,CAC5B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,mBAAmB,KACtB,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAErC,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;CAClC;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,CACJ,MAAM,EAAE,wBAAwB,EAChC,OAAO,EAAE,yCAAyC,GACjD,OAAO,CAAC,4BAA4B,CAAC,CAAC;CAC1C;AAmVD,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,oCAAoC,GAC5C,yBAAyB,CAsF3B"}

package/dist/utils/deployment-upload.js

@@ -0,0 +1,359 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, open } from 'node:fs/promises';
+import path from 'node:path';
+import { prepareProtocolDeploymentBundleManifest, prepareProtocolDeploymentReleaseEnvelope, } from '@hypequery/protocol';
+import { DEPLOYMENT_BUNDLE_MANIFEST, } from './deployment-bundle.js';
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+const MAX_RESPONSE_BYTES = 64 * 1024;
+const DEFAULT_TIMEOUT_MS = 120_000;
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder('utf-8', { fatal: true });
+export class DeploymentUploadError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(`${code}: ${message}`);
+        this.name = 'DeploymentUploadError';
+        this.code = code;
+        if (status !== undefined)
+            this.status = status;
+    }
+}
+function configurationError(message) {
+    throw new DeploymentUploadError('HQ_UPLOAD_CONFIGURATION', message);
+}
+function endpointUrl(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        configurationError('Deployment endpoint must be an absolute HTTPS URL.');
+    }
+    if (url.protocol !== 'https:') {
+        configurationError('Deployment endpoint must use HTTPS.');
+    }
+    if (url.username || url.password) {
+        configurationError('Deployment endpoint must not contain credentials.');
+    }
+    if (url.hash)
+        configurationError('Deployment endpoint must not contain a URL fragment.');
+    return url.toString();
+}
+function bearerToken(input) {
+    if (input.length < 1 || input.length > 4096 || input.trim() !== input
+        || [...input].some(character => {
+            const code = character.charCodeAt(0);
+            return code < 0x21 || code > 0x7e;
+        })) {
+        configurationError('HYPEQUERY_API_TOKEN contains invalid characters or length.');
+    }
+    return input;
+}
+function timeout(input) {
+    const value = input ?? DEFAULT_TIMEOUT_MS;
+    if (!Number.isSafeInteger(value) || value < 1 || value > 10 * 60_000) {
+        configurationError('Deployment upload timeout must be between 1 and 600000 milliseconds.');
+    }
+    return value;
+}
+function multipartBundlePath(input) {
+    if (!/^[\x21-\x7e]+$/.test(input) || input.includes('"') || input.includes('\\')) {
+        throw new DeploymentUploadError('HQ_UPLOAD_BUNDLE_CHANGED', 'A bundle path cannot be safely encoded as a multipart header.');
+    }
+    return input;
+}
+function validateMultipartBundlePaths(bundle) {
+    multipartBundlePath(bundle.manifest.deployment.path);
+    for (const artifact of bundle.manifest.artifacts)
+        multipartBundlePath(artifact.path);
+}
+function partHeader(boundary, part) {
+    const headers = [
+        `--${boundary}`,
+        `Content-Disposition: form-data; name="${part.name}"; filename="${part.filename}"`,
+        `Content-Type: ${part.contentType}`,
+        ...(part.bundlePath
+            ? [`X-HypeQuery-Bundle-Path: ${multipartBundlePath(part.bundlePath)}`]
+            : []),
+        '',
+        '',
+    ].join('\r\n');
+    return textEncoder.encode(headers);
+}
+function uploadParts(bundle, release, manifest) {
+    const root = bundle.directory;
+    return Object.freeze([
+        {
+            kind: 'bytes',
+            name: 'release',
+            filename: 'release.json',
+            contentType: 'application/json',
+            bytes: release.bytes,
+        },
+        {
+            kind: 'bytes',
+            name: 'bundle',
+            filename: DEPLOYMENT_BUNDLE_MANIFEST,
+            contentType: 'application/json',
+            bundlePath: DEPLOYMENT_BUNDLE_MANIFEST,
+            bytes: textEncoder.encode(`${manifest.canonical}\n`),
+        },
+        {
+            kind: 'file',
+            name: 'bundle',
+            filename: path.basename(manifest.manifest.deployment.path),
+            contentType: 'application/json',
+            absolutePath: path.join(root, ...manifest.manifest.deployment.path.split('/')),
+            bundlePath: manifest.manifest.deployment.path,
+            byteLength: manifest.manifest.deployment.byteLength,
+            sha256: manifest.manifest.deployment.sha256,
+        },
+        ...manifest.manifest.artifacts.map(artifact => ({
+            kind: 'file',
+            name: 'bundle',
+            filename: path.basename(artifact.path),
+            contentType: 'application/octet-stream',
+            absolutePath: path.join(root, ...artifact.path.split('/')),
+            bundlePath: artifact.path,
+            byteLength: artifact.byteLength,
+            sha256: artifact.sha256,
+        })),
+    ]);
+}
+async function* streamVerifiedFile(part) {
+    let handle;
+    try {
+        handle = await open(part.absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const initial = await handle.stat();
+        if (!initial.isFile() || initial.size !== part.byteLength) {
+            throw new DeploymentUploadError('HQ_UPLOAD_BUNDLE_CHANGED', `Bundle entry changed after verification: ${part.bundlePath}`);
+        }
+        const digest = createHash('sha256');
+        let bytesRead = 0;
+        for await (const value of handle.createReadStream({ autoClose: false })) {
+            const chunk = value;
+            bytesRead += chunk.byteLength;
+            if (bytesRead > part.byteLength) {
+                throw new DeploymentUploadError('HQ_UPLOAD_BUNDLE_CHANGED', `Bundle entry changed after verification: ${part.bundlePath}`);
+            }
+            digest.update(chunk);
+            yield chunk;
+        }
+        if (bytesRead !== part.byteLength || digest.digest('hex') !== part.sha256) {
+            throw new DeploymentUploadError('HQ_UPLOAD_BUNDLE_CHANGED', `Bundle entry changed after verification: ${part.bundlePath}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof DeploymentUploadError)
+            throw error;
+        throw new DeploymentUploadError('HQ_UPLOAD_BUNDLE_CHANGED', `Cannot safely read verified bundle entry ${part.bundlePath}: `
+            + (error instanceof Error ? error.message : String(error)));
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function multipartLength(boundary, parts) {
+    const separatorBytes = 2;
+    const ending = textEncoder.encode(`--${boundary}--\r\n`).byteLength;
+    return parts.reduce((total, part) => (total + partHeader(boundary, part).byteLength
+        + (part.kind === 'bytes' ? part.bytes.byteLength : part.byteLength)
+        + separatorBytes), ending);
+}
+async function* multipartBody(boundary, parts) {
+    const separator = textEncoder.encode('\r\n');
+    for (const part of parts) {
+        yield partHeader(boundary, part);
+        if (part.kind === 'bytes') {
+            yield part.bytes;
+        }
+        else {
+            yield* streamVerifiedFile(part);
+        }
+        yield separator;
+    }
+    yield textEncoder.encode(`--${boundary}--\r\n`);
+}
+async function readBoundedResponse(response) {
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > MAX_RESPONSE_BYTES) {
+                await reader.cancel().catch(() => undefined);
+                throw new DeploymentUploadError('HQ_UPLOAD_INVALID_RESPONSE', 'Deployment service response exceeds 65536 bytes.', response.status);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return textDecoder.decode(bytes);
+    }
+    catch {
+        throw new DeploymentUploadError('HQ_UPLOAD_INVALID_RESPONSE', 'Deployment service response is not valid UTF-8.', response.status);
+    }
+}
+function exactRecord(value, fields) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)
+        || Object.getPrototypeOf(value) !== Object.prototype)
+        return undefined;
+    const record = value;
+    const keys = Object.keys(record).sort();
+    const expected = [...fields].sort();
+    if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])) {
+        return undefined;
+    }
+    return record;
+}
+function validateSubmissionResponse(input, bundleIdentity, releaseIdentity, status) {
+    const value = exactRecord(input, [
+        'kind',
+        'version',
+        'status',
+        'releaseIdentity',
+        'bundleIdentity',
+    ]);
+    if (!value
+        || value.kind !== 'hypequery-deployment-submission'
+        || value.version !== 1
+        || (value.status !== 'accepted' && value.status !== 'already-exists')
+        || typeof value.releaseIdentity !== 'string'
+        || typeof value.bundleIdentity !== 'string'
+        || !SHA256_PATTERN.test(value.releaseIdentity)
+        || !SHA256_PATTERN.test(value.bundleIdentity)
+        || value.releaseIdentity !== releaseIdentity
+        || value.bundleIdentity !== bundleIdentity) {
+        throw new DeploymentUploadError('HQ_UPLOAD_INVALID_RESPONSE', 'Deployment service returned an invalid or mismatched submission response.', status);
+    }
+    return Object.freeze({
+        kind: value.kind,
+        version: value.version,
+        status: value.status,
+        releaseIdentity: value.releaseIdentity,
+        bundleIdentity: value.bundleIdentity,
+    });
+}
+function rejectedMessage(response, body) {
+    let detail = '';
+    try {
+        const parsed = JSON.parse(body);
+        const error = typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+            ? parsed.error
+            : undefined;
+        if (typeof error === 'object' && error !== null && !Array.isArray(error)) {
+            const code = error.code;
+            const message = error.message;
+            if (typeof code === 'string' && /^[A-Z0-9_:-]{1,64}$/.test(code))
+                detail += ` ${code}`;
+            if (typeof message === 'string') {
+                const safe = [...message].map(character => {
+                    const codePoint = character.codePointAt(0) ?? 0;
+                    return codePoint <= 0x1f || codePoint === 0x7f ? ' ' : character;
+                }).join('').slice(0, 512).trim();
+                if (safe)
+                    detail += `: ${safe}`;
+            }
+        }
+    }
+    catch {
+        // Rejection bodies are optional; status remains authoritative.
+    }
+    return `Deployment service rejected the submission (${response.status} ${response.statusText})${detail}.`;
+}
+function nestedUploadError(input) {
+    const seen = new Set();
+    let current = input;
+    while (typeof current === 'object' && current !== null && !seen.has(current)) {
+        if (current instanceof DeploymentUploadError)
+            return current;
+        seen.add(current);
+        if (!('cause' in current))
+            return undefined;
+        current = current.cause;
+    }
+    return undefined;
+}
+const defaultFetch = async (input, init) => fetch(input, init);
+export function createHttpDeploymentUploadTransport(options) {
+    const endpoint = endpointUrl(options.endpoint);
+    const token = bearerToken(options.token);
+    const timeoutMs = timeout(options.timeoutMs);
+    const fetchImplementation = options.fetch ?? defaultFetch;
+    const transport = {
+        async submit(bundle, release) {
+            validateMultipartBundlePaths(bundle);
+            const manifest = prepareProtocolDeploymentBundleManifest(bundle.manifest);
+            const preparedRelease = prepareProtocolDeploymentReleaseEnvelope(release.release);
+            if (manifest.identity !== bundle.identity
+                || preparedRelease.identity !== release.identity
+                || preparedRelease.release.bundleIdentity !== manifest.identity) {
+                throw new DeploymentUploadError('HQ_UPLOAD_IDENTITY_MISMATCH', 'Release and bundle identities do not match their verified content.');
+            }
+            const boundary = `hypequery-${randomUUID()}`;
+            const parts = uploadParts(bundle, preparedRelease, manifest);
+            let response;
+            try {
+                response = await fetchImplementation(endpoint, {
+                    method: 'POST',
+                    headers: {
+                        Accept: 'application/json',
+                        Authorization: `Bearer ${token}`,
+                        'Content-Type': `multipart/form-data; boundary=${boundary}`,
+                        'Content-Length': String(multipartLength(boundary, parts)),
+                        'Idempotency-Key': preparedRelease.identity,
+                        'X-HypeQuery-Bundle-Identity': manifest.identity,
+                        'X-HypeQuery-Release-Identity': preparedRelease.identity,
+                    },
+                    body: multipartBody(boundary, parts),
+                    duplex: 'half',
+                    redirect: 'error',
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+            }
+            catch (error) {
+                const uploadError = nestedUploadError(error);
+                if (uploadError)
+                    throw uploadError;
+                throw new DeploymentUploadError('HQ_UPLOAD_NETWORK', `Deployment service request failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            let body;
+            try {
+                body = await readBoundedResponse(response);
+            }
+            catch (error) {
+                if (error instanceof DeploymentUploadError)
+                    throw error;
+                throw new DeploymentUploadError('HQ_UPLOAD_NETWORK', `Deployment service response failed: ${error instanceof Error ? error.message : String(error)}`, response.status);
+            }
+            if (!response.ok) {
+                throw new DeploymentUploadError('HQ_UPLOAD_REJECTED', rejectedMessage(response, body), response.status);
+            }
+            let input;
+            try {
+                input = JSON.parse(body);
+            }
+            catch {
+                throw new DeploymentUploadError('HQ_UPLOAD_INVALID_RESPONSE', 'Deployment service returned invalid JSON.', response.status);
+            }
+            return validateSubmissionResponse(input, manifest.identity, preparedRelease.identity, response.status);
+        },
+    };
+    return Object.freeze(transport);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/cli",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Command-line interface for hypequery",
   "license": "Apache-2.0",
   "type": "module",
@@ -19,7 +19,7 @@
     "open": "^10.0.0",
     "ora": "^8.0.1",
     "prompts": "^2.4.2",
-    "@hypequery/protocol": "0.4.0"
+    "@hypequery/protocol": "0.5.0"
   },
   "peerDependencies": {
     "@hypequery/clickhouse": "*",
@@ -37,7 +37,7 @@
     "typescript": "^5.7.3",
     "vitest": "^3.2.6",
     "@hypequery/clickhouse": "2.4.0",
-    "@hypequery/serve": "0.13.1"
+    "@hypequery/serve": "0.13.2"
   },
   "repository": {
     "type": "git",