@hypequery/cli 1.8.0 → 1.9.1

package/README.md

@@ -204,6 +204,33 @@ Options:
 - `--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;AAcpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AAsKD,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

@@ -7,6 +7,7 @@ import { generateCommand } from './commands/generate.js';
 import { generateDatasetsCommand } from './commands/generate-datasets.js';
 import { generateManifestCommand } from './commands/generate-manifest.js';
 import { buildDeploymentCommand, prepareDeploymentReleaseCommand, validateDeploymentCommand, } from './commands/deployment.js';
+import { deployCommand, } from './commands/deploy.js';
 const program = new Command();
 function getCliVersion() {
     try {
@@ -138,6 +139,14 @@ program
     .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]')
@@ -171,6 +180,7 @@ program.on('--help', () => {
     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/utils/deployment-bundle.d.ts

@@ -1,6 +1,8 @@
 import { type PreparedProtocolDeploymentContract, type ProtocolDeploymentBundleManifest, type ProtocolDeploymentContract } from '@hypequery/protocol';
-export declare const DEPLOYMENT_BUNDLE_MANIFEST = "bundle.json";
-export declare const DEPLOYMENT_BUNDLE_CONTRACT = "deployment.json";
+import { DEPLOYMENT_BUNDLE_CONTRACT, DEPLOYMENT_BUNDLE_MANIFEST, verifyDeploymentBundle } from '@hypequery/deployment';
+import type { VerifiedDeploymentBundle } from '@hypequery/deployment';
+export { DEPLOYMENT_BUNDLE_CONTRACT, DEPLOYMENT_BUNDLE_MANIFEST, verifyDeploymentBundle, };
+export type { VerifiedDeploymentBundle };
 export interface DeploymentBundleRuntimeFile {
     readonly runtime: 'node' | 'python';
     readonly sha256: string;
@@ -12,8 +14,6 @@ export interface WrittenDeploymentBundle {
     readonly identity: string;
     readonly contract: ProtocolDeploymentContract;
 }
-export type VerifiedDeploymentBundle = WrittenDeploymentBundle;
 export declare function writeDeploymentBundle(outputDirectory: string, prepared: PreparedProtocolDeploymentContract, runtimeFiles: readonly DeploymentBundleRuntimeFile[]): Promise<WrittenDeploymentBundle>;
 export declare function readDeploymentRuntimeFile(filePath: string): Promise<Uint8Array>;
-export declare function verifyDeploymentBundle(bundleDirectory: string): Promise<VerifiedDeploymentBundle>;
 //# sourceMappingURL=deployment-bundle.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"deployment-bundle.d.ts","sourceRoot":"","sources":["../../src/utils/deployment-bundle.ts"],"names":[],"mappings":"AAaA,OAAO,EAIL,KAAK,kCAAkC,EAEvC,KAAK,gCAAgC,EACrC,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAG7B,eAAO,MAAM,0BAA0B,gBAAgB,CAAC;AACxD,eAAO,MAAM,0BAA0B,oBAAoB,CAAC;AAE5D,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,gCAAgC,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;CAC/C;AAED,MAAM,MAAM,wBAAwB,GAAG,uBAAuB,CAAC;AA+F/D,wBAAsB,qBAAqB,CACzC,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,kCAAkC,EAC5C,YAAY,EAAE,SAAS,2BAA2B,EAAE,GACnD,OAAO,CAAC,uBAAuB,CAAC,CA6ElC;AAgDD,wBAAsB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAMrF;AA+FD,wBAAsB,sBAAsB,CAC1C,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,wBAAwB,CAAC,CA+DnC"}
+{"version":3,"file":"deployment-bundle.d.ts","sourceRoot":"","sources":["../../src/utils/deployment-bundle.ts"],"names":[],"mappings":"AAYA,OAAO,EAGL,KAAK,kCAAkC,EACvC,KAAK,gCAAgC,EACrC,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,sBAAsB,EACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAGtE,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,sBAAsB,GACvB,CAAC;AACF,YAAY,EAAE,wBAAwB,EAAE,CAAC;AAEzC,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,gCAAgC,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;CAC/C;AA+FD,wBAAsB,qBAAqB,CACzC,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,kCAAkC,EAC5C,YAAY,EAAE,SAAS,2BAA2B,EAAE,GACnD,OAAO,CAAC,uBAAuB,CAAC,CA6ElC;AAoCD,wBAAsB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAMrF"}

package/dist/utils/deployment-bundle.js

@@ -1,11 +1,10 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { constants, lstat, mkdir, mkdtemp, open, readdir, rename, rm, writeFile, } from 'node:fs/promises';
+import { constants, lstat, mkdir, mkdtemp, open, rename, rm, writeFile, } from 'node:fs/promises';
 import path from 'node:path';
-import { DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS, prepareProtocolDeploymentBundleManifest, prepareProtocolDeploymentContract, } from '@hypequery/protocol';
+import { DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS, prepareProtocolDeploymentBundleManifest, } from '@hypequery/protocol';
+import { DEPLOYMENT_BUNDLE_CONTRACT, DEPLOYMENT_BUNDLE_MANIFEST, verifyDeploymentBundle, } from '@hypequery/deployment';
 import { logger } from './logger.js';
-export const DEPLOYMENT_BUNDLE_MANIFEST = 'bundle.json';
-export const DEPLOYMENT_BUNDLE_CONTRACT = 'deployment.json';
-const utf8Decoder = new TextDecoder('utf-8', { fatal: true });
+export { DEPLOYMENT_BUNDLE_CONTRACT, DEPLOYMENT_BUNDLE_MANIFEST, verifyDeploymentBundle, };
 const utf8Encoder = new TextEncoder();
 function sha256(bytes) {
     return createHash('sha256').update(bytes).digest('hex');
@@ -185,138 +184,6 @@ async function readBoundedAbsoluteRegularFile(absolutePath, displayPath, maximum
         await handle?.close();
     }
 }
-async function readBoundedRegularFile(root, relativePath, maximum) {
-    return readBoundedAbsoluteRegularFile(path.join(root, ...relativePath.split('/')), relativePath, maximum);
-}
 export async function readDeploymentRuntimeFile(filePath) {
     return readBoundedAbsoluteRegularFile(path.resolve(filePath), filePath, DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxArtifactBytes);
 }
-function expectedDirectories(files) {
-    const result = new Set();
-    for (const file of files) {
-        const segments = file.split('/');
-        for (let index = 1; index < segments.length; index += 1) {
-            result.add(segments.slice(0, index).join('/'));
-        }
-    }
-    return result;
-}
-async function verifyExactEntries(root, manifest) {
-    const expectedFiles = new Set([
-        DEPLOYMENT_BUNDLE_MANIFEST,
-        manifest.deployment.path,
-        ...manifest.artifacts.map(artifact => artifact.path),
-    ]);
-    const expectedDirectoryPaths = expectedDirectories([...expectedFiles]);
-    const seenFiles = new Set();
-    const seenDirectories = new Set();
-    async function visit(relativeDirectory) {
-        const absoluteDirectory = relativeDirectory
-            ? path.join(root, ...relativeDirectory.split('/'))
-            : root;
-        const names = await readdir(absoluteDirectory);
-        names.sort();
-        for (const name of names) {
-            const relativePath = relativeDirectory ? `${relativeDirectory}/${name}` : name;
-            const stat = await lstat(path.join(absoluteDirectory, name));
-            if (stat.isSymbolicLink()) {
-                throw new Error(`Bundle entries must not be symbolic links: ${relativePath}`);
-            }
-            if (stat.isDirectory()) {
-                if (!expectedDirectoryPaths.has(relativePath)) {
-                    throw new Error(`Deployment bundle contains an undeclared directory: ${relativePath}`);
-                }
-                seenDirectories.add(relativePath);
-                await visit(relativePath);
-            }
-            else if (stat.isFile()) {
-                if (!expectedFiles.has(relativePath)) {
-                    throw new Error(`Deployment bundle contains an undeclared file: ${relativePath}`);
-                }
-                seenFiles.add(relativePath);
-            }
-            else {
-                throw new Error(`Bundle entry is not a regular file or directory: ${relativePath}`);
-            }
-        }
-    }
-    await visit('');
-    const missingFiles = [...expectedFiles].filter(file => !seenFiles.has(file)).sort();
-    if (missingFiles.length > 0) {
-        throw new Error(`Deployment bundle is missing files: ${missingFiles.join(', ')}`);
-    }
-    const missingDirectories = [...expectedDirectoryPaths]
-        .filter(directory => !seenDirectories.has(directory))
-        .sort();
-    if (missingDirectories.length > 0) {
-        throw new Error(`Deployment bundle is missing directories: ${missingDirectories.join(', ')}`);
-    }
-}
-function verifyFile(bytes, file) {
-    if (bytes.byteLength !== file.byteLength) {
-        throw new Error(`Bundle entry byte length does not match the manifest: ${file.path}`);
-    }
-    if (sha256(bytes) !== file.sha256) {
-        throw new Error(`Bundle entry SHA-256 does not match the manifest: ${file.path}`);
-    }
-}
-function verifyRuntimeReferences(contract, artifacts) {
-    requireClosedContractArtifactSet(contract);
-    const declared = new Map(contract.artifacts.map(artifact => [artifact.artifactSha256, artifact.runtime]));
-    if (declared.size !== artifacts.length) {
-        throw new Error('Bundle runtime artifacts do not match the deployment contract.');
-    }
-    for (const artifact of artifacts) {
-        if (declared.get(artifact.sha256) !== artifact.runtime) {
-            throw new Error(`Bundle artifact ${artifact.sha256} does not match a deployment runtime reference.`);
-        }
-    }
-}
-export async function verifyDeploymentBundle(bundleDirectory) {
-    const root = path.resolve(bundleDirectory);
-    const rootStat = await lstat(root);
-    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
-        throw new Error(`Deployment bundle path must be a regular directory: ${bundleDirectory}`);
-    }
-    const manifestBytes = await readBoundedRegularFile(root, DEPLOYMENT_BUNDLE_MANIFEST, 1024 * 1024);
-    let input;
-    try {
-        input = JSON.parse(utf8Decoder.decode(manifestBytes));
-    }
-    catch (error) {
-        throw new Error(`Invalid deployment bundle manifest: ${path.join(root, DEPLOYMENT_BUNDLE_MANIFEST)}\n\n`
-            + (error instanceof Error ? error.message : String(error)));
-    }
-    const preparedManifest = prepareProtocolDeploymentBundleManifest(input);
-    const expectedManifestBytes = utf8Encoder.encode(`${preparedManifest.canonical}\n`);
-    if (!Buffer.from(manifestBytes).equals(Buffer.from(expectedManifestBytes))) {
-        throw new Error('Deployment bundle manifest must contain canonical JSON followed by one newline.');
-    }
-    await verifyExactEntries(root, preparedManifest.manifest);
-    const deployment = preparedManifest.manifest.deployment;
-    const deploymentBytes = await readBoundedRegularFile(root, deployment.path, DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxDeploymentBytes);
-    verifyFile(deploymentBytes, deployment);
-    let contractInput;
-    try {
-        contractInput = JSON.parse(utf8Decoder.decode(deploymentBytes));
-    }
-    catch (error) {
-        throw new Error(`Invalid deployment JSON in bundle: ${deployment.path}\n\n`
-            + (error instanceof Error ? error.message : String(error)));
-    }
-    const preparedContract = prepareProtocolDeploymentContract(contractInput);
-    if (preparedContract.identity !== deployment.identity) {
-        throw new Error('Deployment identity does not match the bundle manifest.');
-    }
-    for (const artifact of preparedManifest.manifest.artifacts) {
-        const bytes = await readBoundedRegularFile(root, artifact.path, DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxArtifactBytes);
-        verifyFile(bytes, artifact);
-    }
-    verifyRuntimeReferences(preparedContract.contract, preparedManifest.manifest.artifacts);
-    return Object.freeze({
-        directory: root,
-        manifest: preparedManifest.manifest,
-        identity: preparedManifest.identity,
-        contract: preparedContract.contract,
-    });
-}

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

@@ -0,0 +1,37 @@
+import type { ReadableStream } from 'node:stream/web';
+import { type PreparedProtocolDeploymentReleaseEnvelope } from '@hypequery/protocol';
+import { type VerifiedDeploymentBundle } from './deployment-bundle.js';
+import type { DeploymentSubmissionResponse } from '@hypequery/deployment';
+export type { DeploymentSubmissionResponse } from '@hypequery/deployment';
+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 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;AAChC,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAE1E,YAAY,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAQ1E,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,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.8.0",
+  "version": "1.9.1",
   "description": "Command-line interface for hypequery",
   "license": "Apache-2.0",
   "type": "module",
@@ -19,7 +19,8 @@
     "open": "^10.0.0",
     "ora": "^8.0.1",
     "prompts": "^2.4.2",
-    "@hypequery/protocol": "0.5.0"
+    "@hypequery/deployment": "0.2.0",
+    "@hypequery/protocol": "0.6.0"
   },
   "peerDependencies": {
     "@hypequery/clickhouse": "*",
@@ -37,7 +38,7 @@
     "typescript": "^5.7.3",
     "vitest": "^3.2.6",
     "@hypequery/clickhouse": "2.4.0",
-    "@hypequery/serve": "0.13.2"
+    "@hypequery/serve": "0.13.3"
   },
   "repository": {
     "type": "git",