@hypequery/cli 1.26.0 → 1.27.0

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0CpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAE9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AAySD,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0CpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAE9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AA2SD,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/cli.js

@@ -208,6 +208,7 @@ program
     .command('deployment:submit <bundle>')
     .description('Submit a prebuilt deployment bundle and release')
     .requiredOption('--release <path>', 'Target-bound release JSON path')
+    .option('--draft <name>', 'Save a named Cloud draft without publishing Production')
     .option('--endpoint <url>', 'HTTPS submission endpoint; requires HYPEQUERY_API_TOKEN')
     .option('--replace-restored', 'Intentionally replace a restored live release')
     .action(runCommand(async (bundle, options) => {
@@ -231,6 +232,7 @@ program
     .option('--project <project>', 'Target project identifier (advanced override)')
     .option('--environment <environment>', 'Target environment identifier (advanced override)')
     .option('--no-source', 'Exclude project source files from the deployment bundle')
+    .option('--draft <name>', 'Save a named Cloud draft without publishing Production')
     .option('--endpoint <url>', 'HTTPS submission endpoint; requires HYPEQUERY_API_TOKEN')
     .option('--replace-restored', 'Intentionally replace a restored live release')
     .option('--mcp-config', 'Also print MCP client configuration for the hosted endpoint')

package/dist/commands/deploy.d.ts

@@ -7,12 +7,14 @@ export interface SubmitDeploymentOptions {
     release?: string;
     endpoint?: string;
     replaceRestored?: boolean;
+    draft?: string;
     /** Also print MCP client configuration for the hosted endpoint. */
     mcpConfig?: boolean;
 }
 export interface DeployOptions {
     endpoint?: string;
     replaceRestored?: boolean;
+    draft?: string;
     project?: string;
     environment?: string;
     bundleOutput?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AASA,OAAO,EACL,mCAAmC,EAEnC,KAAK,4BAA4B,EAElC,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,KAAK,qBAAqB,EAC3B,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EACL,oBAAoB,EACrB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,sBAAsB,EACtB,+BAA+B,EAChC,MAAM,iBAAiB,CAAC;AAMzB,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,4BAA4B;IAC3C,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;IACtE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,mBAAmB,CAAC;IAChD,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,oBAAoB,CAAC;CACvD;AAED,MAAM,WAAW,kBAAmB,SAAQ,4BAA4B;IACtE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,sBAAsB,CAAC;IACzD,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,+BAA+B,CAAC;IAC3E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,uBAAuB,CAAC;CAC5D;AA4DD,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,uBAA4B,EACrC,YAAY,GAAE,4BAAiC,GAC9C,OAAO,CAAC,4BAA4B,CAAC,CAiFvC;AAsBD,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,aAAkB,EAC3B,YAAY,GAAE,kBAAuB,GACpC,OAAO,CAAC,4BAA4B,CAAC,CAwCvC"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AASA,OAAO,EACL,mCAAmC,EAEnC,KAAK,4BAA4B,EAElC,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EACL,KAAK,qBAAqB,EAC3B,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EACL,oBAAoB,EACrB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,sBAAsB,EACtB,+BAA+B,EAChC,MAAM,iBAAiB,CAAC;AAMzB,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,4BAA4B;IAC3C,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;IACtE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,mBAAmB,CAAC;IAChD,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,oBAAoB,CAAC;CACvD;AAED,MAAM,WAAW,kBAAmB,SAAQ,4BAA4B;IACtE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,sBAAsB,CAAC;IACzD,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,+BAA+B,CAAC;IAC3E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,uBAAuB,CAAC;CAC5D;AA4DD,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,uBAA4B,EACrC,YAAY,GAAE,4BAAiC,GAC9C,OAAO,CAAC,4BAA4B,CAAC,CA8FvC;AAsBD,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,aAAkB,EAC3B,YAAY,GAAE,kBAAuB,GACpC,OAAO,CAAC,4BAA4B,CAAC,CA0CvC"}

package/dist/commands/deploy.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { prepareProtocolDeploymentReleaseEnvelope, } from '@hypequery/protocol';
 import { DEPLOYMENT_BUNDLE_MANIFEST, verifyDeploymentBundle, } from '../utils/deployment-bundle.js';
 import { createHttpDeploymentUploadTransport, DeploymentUploadError, } from '../utils/deployment-upload.js';
+import { validateDraftDeploymentOptions } from '../utils/draft-deployment.js';
 import { logger } from '../utils/logger.js';
 import { resolveDeploymentCredential } from '../utils/cloud-deployment-access.js';
 import { fetchLiveDeployment } from '../utils/live-deployment.js';
@@ -73,6 +74,7 @@ export async function submitDeploymentCommand(bundlePath, options = {}, dependen
             + 'Usage: hypequery deployment:submit analytics/hypequery-deployment '
             + '--release analytics/hypequery-deployment.release.json');
     }
+    validateDraftDeploymentOptions(options);
     const releasePath = requiredConfiguration(options.release, 'Missing required --release <path>.');
     const { endpoint: deploymentEndpoint, token } = await resolveDeploymentCredential(options.endpoint, dependencies);
     let bundle;
@@ -95,7 +97,7 @@ export async function submitDeploymentCommand(bundlePath, options = {}, dependen
     if (release.release.bundleIdentity !== bundle.identity) {
         throw new DeploymentUploadError('HQ_UPLOAD_IDENTITY_MISMATCH', 'Release bundle identity does not match the verified deployment bundle.');
     }
-    const live = await (dependencies.fetchLive ?? fetchLiveDeployment)({
+    const live = options.draft !== undefined ? null : await (dependencies.fetchLive ?? fetchLiveDeployment)({
         endpoint: deploymentEndpoint,
         token,
         target: release.release.target,
@@ -115,8 +117,20 @@ export async function submitDeploymentCommand(bundlePath, options = {}, dependen
             ? { expectedActivationRevision: live.active?.revision ?? null }
             : {}),
         ...(options.replaceRestored ? { replaceRestored: true } : {}),
+        ...(options.draft !== undefined ? { draft: options.draft } : {}),
     };
     const result = await createTransport(transportOptions).submit(bundle, release);
+    if (options.draft !== undefined) {
+        if (!result.draft || result.draft.name !== options.draft) {
+            throw new DeploymentUploadError('HQ_UPLOAD_INVALID_RESPONSE', 'Deployment service did not acknowledge the requested draft.');
+        }
+        logger.success(`Draft saved: ${result.draft.name}`);
+        logger.info(`Draft ID: ${result.draft.draftId}`);
+        logger.info(`Staging endpoint: ${result.draft.stagingUrl}`);
+        logger.info(`Release identity: ${result.releaseIdentity}`);
+        logger.info('Review and publish this draft in Cloud when ready.');
+        return result;
+    }
     logger.success(result.status === 'accepted'
         ? 'Deployment release accepted'
         : 'Deployment release already exists');
@@ -150,6 +164,7 @@ async function rejectBundleDirectorySource(sourcePath) {
         + `${sourcePath} --release <file>\`.`);
 }
 export async function deployCommand(sourcePath, options = {}, dependencies = {}) {
+    validateDraftDeploymentOptions(options);
     if (!sourcePath) {
         throw new Error('Missing Cloud publication module path.\n\n'
             + 'Usage: hypequery deploy analytics/cloud.ts');
@@ -182,5 +197,6 @@ export async function deployCommand(sourcePath, options = {}, dependencies = {})
         endpoint: options.endpoint,
         replaceRestored: options.replaceRestored,
         mcpConfig: options.mcpConfig,
+        ...(options.draft !== undefined ? { draft: options.draft } : {}),
     }, dependencies);
 }

package/dist/commands/generate-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-client.d.ts","sourceRoot":"","sources":["../../src/commands/generate-client.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,qBAAqB;IAAG,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE;AAE5F,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhH"}
+{"version":3,"file":"generate-client.d.ts","sourceRoot":"","sources":["../../src/commands/generate-client.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,qBAAqB;IAAG,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE;AAE5F,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAoChH"}

package/dist/commands/generate-client.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { decodeProtocolClientContract } from '@hypequery/protocol';
 import { renderClientContract } from '../generators/client-contract/render.js';
-import { checkClientOutputPath, readClientArtifact, readClientOutput } from '../utils/client-contract-file.js';
+import { checkClientOutputPath, describeClientContractError, readClientArtifact, readClientOutput } from '../utils/client-contract-file.js';
 import { writeGeneratedFileAtomically } from '../utils/generated-file.js';
 import { logger } from '../utils/logger.js';
 import { updateCommandTelemetry, setCommandTelemetryError } from '../utils/telemetry/command-context.js';
@@ -16,7 +16,14 @@ export async function generateClientCommand(artifact, options = {}) {
         throw new Error('Client input and output must be different files.');
     await checkClientOutputPath(output);
     const current = await readClientOutput(output);
-    const contract = decodeProtocolClientContract(await readClientArtifact(input));
+    const text = await readClientArtifact(input);
+    let contract;
+    try {
+        contract = decodeProtocolClientContract(text);
+    }
+    catch (error) {
+        throw describeClientContractError(error);
+    }
     if (contract.view !== 'build')
         throw new Error('Client generation requires a build view exported by the definition owner.');
     const contents = renderClientContract(contract);

package/dist/generators/dataset-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-generator.d.ts","sourceRoot":"","sources":["../../src/generators/dataset-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AAG1E,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,8BAA8B,CAAC;IACxC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,MAAM,wBAAwB,GAChC;IACE,IAAI,EAAE,sBAAsB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,uBAAuB,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAkSN;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB;;;;;;;;GAyEtE"}
+{"version":3,"file":"dataset-generator.d.ts","sourceRoot":"","sources":["../../src/generators/dataset-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AAS1E,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,8BAA8B,CAAC;IACxC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,MAAM,wBAAwB,GAChC;IACE,IAAI,EAAE,sBAAsB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,uBAAuB,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAuTN;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB;;;;;;;;GAyEtE"}

package/dist/generators/dataset-generator.js

@@ -7,45 +7,14 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { getClickHouseClient } from '../utils/clickhouse-client.js';
+import { clickHouseDimensionType, namedTupleElements, } from '../utils/clickhouse-dimension-type.js';
+import { createFieldNamer } from '../utils/field-namer.js';
+const SQL_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /**
- * Determine the dataset dimension type from a ClickHouse type
- */
-function clickhouseToDimensionType(chType) {
-    const normalized = chType.toLowerCase();
-    // String types
-    if (normalized.includes('string') || normalized.includes('enum')) {
-        return 'string';
-    }
-    // Numeric types
-    if (normalized.includes('int') ||
-        normalized.includes('float') ||
-        normalized.includes('double') ||
-        normalized.includes('decimal')) {
-        return 'number';
-    }
-    // Date/Time types
-    if (normalized.includes('date') || normalized.includes('datetime')) {
-        return 'timestamp';
-    }
-    // Boolean
-    if (normalized.includes('bool')) {
-        return 'boolean';
-    }
-    // Default to string for unknown types
-    return 'string';
-}
-/**
- * Check if a column is likely a timestamp column
+ * Whether a column can be the dataset's timeKey: its values are dates or times.
  */
 function isTimestampColumn(column) {
-    const name = column.name.toLowerCase();
-    const type = column.type.toLowerCase();
-    return (type.includes('date') ||
-        type.includes('datetime') ||
-        name.includes('timestamp') ||
-        name.includes('_at') ||
-        name === 'created' ||
-        name === 'updated');
+    return clickHouseDimensionType(column.type) === 'timestamp';
 }
 /**
  * Check if a column name is worth presenting as a possible tenant key.
@@ -65,11 +34,7 @@ function isTenantKeyCandidate(column) {
  * Check if a column is numeric and suitable for measures
  */
 function isNumericColumn(column) {
-    const type = column.type.toLowerCase();
-    return (type.includes('int') ||
-        type.includes('float') ||
-        type.includes('double') ||
-        type.includes('decimal'));
+    return clickHouseDimensionType(column.type) === 'number';
 }
 /**
  * Check if a numeric column is more likely an identifier than an additive value.
@@ -169,39 +134,93 @@ async function generateDatasetForTable(client, tableName, tenantColumn) {
                 'Review them and add tenantKey explicitly only after configuring trusted runtime tenant scope.',
         });
     }
-    // Generate dimensions
+    // Generate dimensions. A named tuple becomes one dimension per scalar
+    // element; columns no dimension type describes are left out with a note.
+    const fields = [];
+    const skippedColumns = [];
+    for (const column of columns) {
+        const dimensionType = clickHouseDimensionType(column.type);
+        if (dimensionType) {
+            fields.push({ column, type: dimensionType, name: columnToCamelCase(column.name) });
+            continue;
+        }
+        const elements = SQL_IDENTIFIER.test(column.name) ? namedTupleElements(column.type) : null;
+        if (elements?.length) {
+            for (const element of elements) {
+                fields.push({
+                    column,
+                    element: element.name,
+                    type: element.type,
+                    name: columnToCamelCase(`${column.name}_${element.name}`),
+                });
+            }
+            continue;
+        }
+        skippedColumns.push(column);
+    }
+    // Field names are SQL aliases, so none may shadow a source column another
+    // field reads. A column spelled like its field keeps that name, then other
+    // columns, then tuple elements; a clash takes a numeric suffix instead.
+    const nameField = createFieldNamer(columns.map((column) => column.name));
+    const naming = [
+        ...fields.filter((field) => !field.element && field.name === field.column.name),
+        ...fields.filter((field) => !field.element && field.name !== field.column.name),
+        ...fields.filter((field) => field.element),
+    ];
+    for (const field of naming) {
+        const name = nameField(field.name, field.element ? undefined : field.column.name);
+        if (name !== field.name)
+            field.renamedFrom = field.name;
+        field.name = name;
+    }
+    const fieldNameByColumn = new Map(fields.filter((field) => !field.element).map((field) => [field.column.name, field.name]));
     const dimensionLines = [];
     for (const column of columns) {
-        const fieldName = columnToCamelCase(column.name);
-        const dimensionType = clickhouseToDimensionType(column.type);
-        const label = generateLabel(column.name);
-        // Skip if column name === fieldName (no transformation needed)
-        if (column.name === fieldName) {
-            dimensionLines.push(`    ${fieldName}: dimension.${dimensionType}({ label: '${label}' }),`);
+        if (skippedColumns.includes(column)) {
+            // ClickHouse can spell a nested type over several lines; keep the note on one comment line.
+            const type = column.type.replace(/\s+/g, ' ');
+            dimensionLines.push(`    // ${column.name} (${type}) is not included: no dimension type describes its values.`);
+            continue;
         }
-        else {
-            dimensionLines.push(`    ${fieldName}: dimension.${dimensionType}({ column: '${column.name}', label: '${label}' }),`);
+        for (const field of fields.filter((candidate) => candidate.column === column)) {
+            const label = generateLabel(column.name);
+            if (field.renamedFrom) {
+                dimensionLines.push(`    // ${field.element ? `${column.name}.${field.element}` : column.name} is ${field.name}: ${field.renamedFrom} is taken by another field or column.`);
+            }
+            if (field.element) {
+                dimensionLines.push(`    ${field.name}: dimension.${field.type}({ sql: "tupleElement(${column.name}, '${field.element}')", ` +
+                    `dependencies: ['${column.name}'], label: '${label} ${generateLabel(field.element)}' }),`);
+            }
+            else if (column.name === field.name) {
+                // No column option needed when the field is spelled like the column
+                dimensionLines.push(`    ${field.name}: dimension.${field.type}({ label: '${label}' }),`);
+            }
+            else {
+                dimensionLines.push(`    ${field.name}: dimension.${field.type}({ column: '${column.name}', label: '${label}' }),`);
+            }
         }
     }
     // Generate measures for numeric value columns only. IDs and coordinates stay
     // dimensions because summing or averaging them is usually noise.
     const numericColumns = columns.filter(isMeasureCandidate);
     const measureLines = [];
+    const countField = fields[0]?.name;
     if (numericColumns.length > 0) {
         measureLines.push(`    // Count measures`);
-        measureLines.push(`    totalCount: measure.count('${columnToCamelCase(columns[0].name)}', { label: 'Total Count' }),`);
+        measureLines.push(`    ${nameField('totalCount')}: measure.count('${countField}', { label: 'Total Count' }),`);
         measureLines.push(``);
         for (const column of numericColumns) {
-            const fieldName = columnToCamelCase(column.name);
+            const fieldName = fieldNameByColumn.get(column.name);
+            const measureSuffix = fieldName.charAt(0).toUpperCase() + fieldName.slice(1);
             const label = generateLabel(column.name);
             measureLines.push(`    // ${label} measures`);
-            measureLines.push(`    total${tableToPascalCase(column.name)}: measure.sum('${fieldName}', { label: 'Total ${label}' }),`);
-            measureLines.push(`    avg${tableToPascalCase(column.name)}: measure.avg('${fieldName}', { label: 'Average ${label}' }),`);
+            measureLines.push(`    ${nameField(`total${measureSuffix}`)}: measure.sum('${fieldName}', { label: 'Total ${label}' }),`);
+            measureLines.push(`    ${nameField(`avg${measureSuffix}`)}: measure.avg('${fieldName}', { label: 'Average ${label}' }),`);
             measureLines.push(``);
         }
     }
-    else {
-        measureLines.push(`    totalCount: measure.count('${columnToCamelCase(columns[0].name)}', { label: 'Total Count' }),`);
+    else if (countField) {
+        measureLines.push(`    ${nameField('totalCount')}: measure.count('${countField}', { label: 'Total Count' }),`);
     }
     // Build the dataset definition
     const datasetName = tableToPascalCase(tableName);

package/dist/utils/clickhouse-dimension-type.d.ts

@@ -0,0 +1,27 @@
+/** A dataset dimension type the scaffolder can emit. */
+export type ScaffoldDimensionType = 'string' | 'number' | 'boolean' | 'timestamp';
+export interface NamedTupleElement {
+    name: string;
+    type: ScaffoldDimensionType;
+}
+/**
+ * The value type behind `Nullable`, `LowCardinality` and
+ * `SimpleAggregateFunction(fn, T)` wrappers; none changes what a value is.
+ */
+export declare function unwrapClickHouseType(type: string): string;
+/**
+ * Maps a ClickHouse column type to a dataset dimension type, or null when no
+ * scalar dimension type describes its values (Array, Tuple, Map, geo, JSON,
+ * Interval, ...). The outer type name is matched exactly: a substring match
+ * reads `Point` or `Array(Int32)` as numbers. Mirrors Cloud's `protocolTypeOf`
+ * so a table scaffolds with the same field types in both.
+ */
+export declare function clickHouseDimensionType(type: string): ScaffoldDimensionType | null;
+/**
+ * The scalar elements of a named `Tuple(name T, ...)` column, each of which can
+ * be its own dimension through `tupleElement`. Null for any other type,
+ * including unnamed tuples, whose positions carry no meaning to name a field
+ * after. Elements without a scalar type or a plain identifier name are left out.
+ */
+export declare function namedTupleElements(type: string): NamedTupleElement[] | null;
+//# sourceMappingURL=clickhouse-dimension-type.d.ts.map

package/dist/utils/clickhouse-dimension-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clickhouse-dimension-type.d.ts","sourceRoot":"","sources":["../../src/utils/clickhouse-dimension-type.ts"],"names":[],"mappings":"AAEA,wDAAwD;AACxD,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;AAElF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,qBAAqB,CAAC;CAC7B;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASzD;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAOlF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,GAAG,IAAI,CAgB3E"}

package/dist/utils/clickhouse-dimension-type.js

@@ -0,0 +1,61 @@
+import { matchTypeCall } from './clickhouse-type-utils.js';
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * The value type behind `Nullable`, `LowCardinality` and
+ * `SimpleAggregateFunction(fn, T)` wrappers; none changes what a value is.
+ */
+export function unwrapClickHouseType(type) {
+    let current = type.trim();
+    const simple = /^SimpleAggregateFunction\(\s*[A-Za-z_][A-Za-z0-9_]*\s*,\s*(.+)\)$/s.exec(current);
+    if (simple)
+        current = simple[1].trim();
+    for (;;) {
+        const wrapped = /^(?:Nullable|LowCardinality)\((.*)\)$/s.exec(current);
+        if (!wrapped)
+            return current;
+        current = wrapped[1].trim();
+    }
+}
+/**
+ * Maps a ClickHouse column type to a dataset dimension type, or null when no
+ * scalar dimension type describes its values (Array, Tuple, Map, geo, JSON,
+ * Interval, ...). The outer type name is matched exactly: a substring match
+ * reads `Point` or `Array(Int32)` as numbers. Mirrors Cloud's `protocolTypeOf`
+ * so a table scaffolds with the same field types in both.
+ */
+export function clickHouseDimensionType(type) {
+    const value = unwrapClickHouseType(type);
+    if (/^(?:U?Int\d+|Float\d+|Decimal\d*)(?:\(.*\))?$/s.test(value))
+        return 'number';
+    if (/^(?:Date|Date32|DateTime|DateTime64)(?:\(.*\))?$/s.test(value))
+        return 'timestamp';
+    if (value === 'Bool')
+        return 'boolean';
+    if (/^(?:String|FixedString|UUID|Enum\d*|IPv4|IPv6)(?:\(.*\))?$/s.test(value))
+        return 'string';
+    return null;
+}
+/**
+ * The scalar elements of a named `Tuple(name T, ...)` column, each of which can
+ * be its own dimension through `tupleElement`. Null for any other type,
+ * including unnamed tuples, whose positions carry no meaning to name a field
+ * after. Elements without a scalar type or a plain identifier name are left out.
+ */
+export function namedTupleElements(type) {
+    const parts = matchTypeCall(unwrapClickHouseType(type), 'Tuple');
+    if (!parts?.length)
+        return null;
+    const elements = [];
+    for (const part of parts) {
+        const named = /^(\S+)\s+(.+)$/s.exec(part);
+        // Element types never contain top-level whitespace before their first
+        // `(`, so a part without a name-then-space prefix is an unnamed element.
+        if (!named || named[1].includes('('))
+            return null;
+        const elementType = clickHouseDimensionType(named[2]);
+        if (IDENTIFIER.test(named[1]) && elementType) {
+            elements.push({ name: named[1], type: elementType });
+        }
+    }
+    return elements;
+}

package/dist/utils/clickhouse-type-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clickhouse-type-utils.d.ts","sourceRoot":"","sources":["../../src/utils/clickhouse-type-utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA+CzD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG3E;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAGzE;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,UASpD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,WAE7C"}
+{"version":3,"file":"clickhouse-type-utils.d.ts","sourceRoot":"","sources":["../../src/utils/clickhouse-type-utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAqDzD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG3E;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAGzE;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,UASpD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,WAE7C"}

package/dist/utils/clickhouse-type-utils.js

@@ -3,10 +3,18 @@ export function splitTopLevelArgs(value) {
     let current = '';
     let depth = 0;
     let quote = null;
+    let escaped = false;
     for (const char of value) {
         if (quote) {
             current += char;
-            if (char === quote) {
+            // ClickHouse escapes a quote inside a literal with a backslash (`'can\'t'`).
+            if (escaped) {
+                escaped = false;
+            }
+            else if (char === '\\') {
+                escaped = true;
+            }
+            else if (char === quote) {
                 quote = null;
             }
             continue;

package/dist/utils/client-contract-file.d.ts

@@ -3,4 +3,9 @@ export declare function checkClientOutputPath(filePath: string): Promise<void>;
 /** Bound allocation before reading; O_NOFOLLOW also refuses a swapped final symlink. */
 export declare function readClientArtifact(filePath: string, maxBytes?: number): Promise<string>;
 export declare function readClientOutput(filePath: string): Promise<string | undefined>;
+/**
+ * Say where a client contract is invalid. An unknown field usually means the
+ * contract was exported by a newer hypequery than this CLI understands.
+ */
+export declare function describeClientContractError(error: unknown): unknown;
 //# sourceMappingURL=client-contract-file.d.ts.map

package/dist/utils/client-contract-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-contract-file.d.ts","sourceRoot":"","sources":["../../src/utils/client-contract-file.ts"],"names":[],"mappings":"AAIA,qFAAqF;AACrF,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe3E;AAED,wFAAwF;AACxF,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBhG;AAED,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAMpF"}
+{"version":3,"file":"client-contract-file.d.ts","sourceRoot":"","sources":["../../src/utils/client-contract-file.ts"],"names":[],"mappings":"AAMA,qFAAqF;AACrF,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB3E;AAsBD,wFAAwF;AACxF,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBhG;AAED,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAMpF;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQnE"}

package/dist/utils/client-contract-file.js

@@ -1,18 +1,27 @@
 import { constants } from 'node:fs';
-import { lstat, open } from 'node:fs/promises';
+import { lstat, open, realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
+import { ProtocolClientContractError } from '@hypequery/protocol';
+import { pointer } from './json-pointer.js';
 /** Refuse filesystem indirection for generated output and its existing ancestors. */
 export async function checkClientOutputPath(filePath) {
-    let current = path.resolve(filePath);
+    const target = path.resolve(filePath);
+    let current = target;
     while (true) {
         try {
             const info = await lstat(current);
-            if (info.isSymbolicLink() || (current === path.resolve(filePath) ? !info.isFile() : !info.isDirectory())) {
-                throw new Error('Client output must be a regular file under ordinary directories.');
+            if (info.isSymbolicLink())
+                throw await throughLink(filePath, target, current);
+            if (current === target ? !info.isFile() : !info.isDirectory()) {
+                throw new Error(current === target
+                    ? `Client output ${filePath} must be a regular file.`
+                    : `Client output ${filePath} must be a regular file under ordinary directories: ${current} is not a directory.`);
             }
         }
         catch (error) {
-            if (error.code !== 'ENOENT')
+            // Missing, or below a file: the ancestor that exists is checked next.
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR')
                 throw error;
         }
         const parent = path.dirname(current);
@@ -21,6 +30,27 @@ export async function checkClientOutputPath(filePath) {
         current = parent;
     }
 }
+/**
+ * Name the link, and the same output without it, e.g. /tmp → /private/tmp on macOS.
+ * The path is suggested only when the link resolves to what that position needs:
+ * a directory above the output, a regular file at the output itself.
+ */
+async function throughLink(filePath, target, link) {
+    const message = link === target
+        ? `Client output ${filePath} must be a regular file, not a symbolic link.`
+        : `Client output ${filePath} must be a regular file under ordinary directories: ${link} is a symbolic link.`;
+    try {
+        const real = await realpath(link);
+        const info = await stat(real);
+        if (link === target ? !info.isFile() : !info.isDirectory())
+            return new Error(message);
+        const resolved = path.join(real, path.relative(link, target));
+        return new Error(`${message} Use the path it points to instead: ${resolved}`);
+    }
+    catch {
+        return new Error(message);
+    }
+}
 /** Bound allocation before reading; O_NOFOLLOW also refuses a swapped final symlink. */
 export async function readClientArtifact(filePath, maxBytes = 1_048_576) {
     const handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
@@ -56,3 +86,17 @@ export async function readClientOutput(filePath) {
         throw error;
     }
 }
+/**
+ * Say where a client contract is invalid. An unknown field usually means the
+ * contract was exported by a newer hypequery than this CLI understands.
+ */
+export function describeClientContractError(error) {
+    if (!(error instanceof ProtocolClientContractError))
+        return error;
+    const at = error.field === undefined ? error.path : pointer(error.path, error.field);
+    const where = at ? ` at ${at}` : '';
+    const hint = error.code === 'HQ_CLIENT_UNKNOWN_FIELD'
+        ? ' The contract may come from a newer hypequery than this CLI; upgrade @hypequery/cli.'
+        : '';
+    return new Error(`${error.message.replace(/\.$/, '')}${where} (${error.code}).${hint}`, { cause: error });
+}

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

@@ -1,8 +1,11 @@
 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';
+import type { DeploymentSubmissionResponse as BaseDeploymentSubmissionResponse } from '@hypequery/deployment';
+import { type DraftDeploymentResult } from './draft-deployment.js';
+export type DeploymentSubmissionResponse = BaseDeploymentSubmissionResponse & {
+    readonly draft?: DraftDeploymentResult;
+};
 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;
@@ -29,6 +32,7 @@ export interface HttpDeploymentUploadTransportOptions {
     readonly token: string;
     readonly expectedActivationRevision?: string | null;
     readonly replaceRestored?: boolean;
+    readonly draft?: string;
     readonly timeoutMs?: number;
     readonly fetch?: DeploymentFetch;
 }

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

@@ -1 +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;AAEhC,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,0BAA0B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpD,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,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;AA+WD,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,oCAAoC,GAC5C,yBAAyB,CA+F3B"}
+{"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;AAEhC,OAAO,KAAK,EAAE,4BAA4B,IAAI,gCAAgC,EAAE,MAAM,uBAAuB,CAAC;AAC9G,OAAO,EAA8D,KAAK,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE/H,MAAM,MAAM,4BAA4B,GAAG,gCAAgC,GAAG;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,qBAAqB,CAAC;CACxC,CAAC;AAQF,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,0BAA0B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpD,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,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;AAoXD,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,oCAAoC,GAC5C,yBAAyB,CAqG3B"}

package/dist/utils/deployment-upload.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { prepareProtocolDeploymentBundleManifest, prepareProtocolDeploymentReleaseEnvelope, } from '@hypequery/protocol';
 import { DEPLOYMENT_BUNDLE_MANIFEST, } from './deployment-bundle.js';
 import { logger } from './logger.js';
+import { parseDraftDeploymentResult, validateDraftDeploymentOptions } from './draft-deployment.js';
 const SHA256_PATTERN = /^[0-9a-f]{64}$/;
 const MAX_RESPONSE_BYTES = 64 * 1024;
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -249,15 +250,18 @@ function exactRecord(value, fields) {
     }
     return record;
 }
-function validateSubmissionResponse(input, bundleIdentity, releaseIdentity, status) {
+function validateSubmissionResponse(input, bundleIdentity, releaseIdentity, status, expectedDraft) {
     const value = exactRecord(input, [
         'kind',
         'version',
         'status',
         'releaseIdentity',
         'bundleIdentity',
+        ...(expectedDraft ? ['draft'] : []),
     ]);
+    const draft = expectedDraft && value ? parseDraftDeploymentResult(value.draft, expectedDraft) : undefined;
     if (!value
+        || (expectedDraft && !draft)
         || value.kind !== 'hypequery-deployment-submission'
         || value.version !== 1
         || (value.status !== 'accepted' && value.status !== 'already-exists')
@@ -275,6 +279,7 @@ function validateSubmissionResponse(input, bundleIdentity, releaseIdentity, stat
         status: value.status,
         releaseIdentity: value.releaseIdentity,
         bundleIdentity: value.bundleIdentity,
+        ...(draft ? { draft } : {}),
     });
 }
 function rejectedMessage(response, body) {
@@ -319,6 +324,10 @@ function nestedUploadError(input) {
 }
 const defaultFetch = async (input, init) => fetch(input, init);
 export function createHttpDeploymentUploadTransport(options) {
+    validateDraftDeploymentOptions(options);
+    if (options.draft !== undefined && options.expectedActivationRevision !== undefined) {
+        configurationError('Draft uploads cannot specify an expected Production activation revision.');
+    }
     const endpoint = endpointUrl(options.endpoint);
     const token = bearerToken(options.token);
     const timeoutMs = timeout(options.timeoutMs);
@@ -347,6 +356,7 @@ export function createHttpDeploymentUploadTransport(options) {
                         'Idempotency-Key': preparedRelease.identity,
                         'X-HypeQuery-Bundle-Identity': manifest.identity,
                         'X-HypeQuery-Release-Identity': preparedRelease.identity,
+                        ...(options.draft !== undefined ? { 'X-HypeQuery-Draft-Name': options.draft } : {}),
                         ...(options.expectedActivationRevision !== undefined
                             ? {
                                 'X-HypeQuery-Expected-Activation-Revision': options.expectedActivationRevision ?? 'none',
@@ -387,7 +397,7 @@ export function createHttpDeploymentUploadTransport(options) {
             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 validateSubmissionResponse(input, manifest.identity, preparedRelease.identity, response.status, options.draft !== undefined ? { name: options.draft, endpoint, project: preparedRelease.release.target.project } : undefined);
         },
     };
     return Object.freeze(transport);

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

@@ -0,0 +1,16 @@
+export interface DraftDeploymentResult {
+    readonly draftId: string;
+    readonly name: string;
+    readonly stagingUrl: string;
+}
+export declare function validateDraftDeploymentOptions(options: {
+    draft?: string;
+    replaceRestored?: boolean;
+}): void;
+/** Accept only the requested draft and a staging endpoint on the deployment service. */
+export declare function parseDraftDeploymentResult(input: unknown, expected: {
+    name: string;
+    endpoint: string;
+    project: string;
+}): DraftDeploymentResult | undefined;
+//# sourceMappingURL=draft-deployment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"draft-deployment.d.ts","sourceRoot":"","sources":["../../src/utils/draft-deployment.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,IAAI,CAQP;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC5D,qBAAqB,GAAG,SAAS,CAmBnC"}

package/dist/utils/draft-deployment.js

@@ -0,0 +1,35 @@
+export function validateDraftDeploymentOptions(options) {
+    if (options.draft === undefined)
+        return;
+    if (options.draft.length > 64 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(options.draft)) {
+        throw new Error('--draft must be a lowercase name with letters, numbers and single hyphens (max 64 characters).');
+    }
+    if (options.replaceRestored) {
+        throw new Error('--draft cannot be combined with --replace-restored; draft uploads do not replace Production.');
+    }
+}
+/** Accept only the requested draft and a staging endpoint on the deployment service. */
+export function parseDraftDeploymentResult(input, expected) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)
+        || Object.getPrototypeOf(input) !== Object.prototype)
+        return undefined;
+    const value = input;
+    if (Object.keys(value).sort().join(',') !== 'draftId,name,stagingUrl'
+        || typeof value.draftId !== 'string'
+        || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value.draftId)
+        || value.name !== expected.name
+        || typeof value.stagingUrl !== 'string')
+        return undefined;
+    let url;
+    try {
+        url = new URL(value.stagingUrl, expected.endpoint);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.origin !== new URL(expected.endpoint).origin || url.username || url.password
+        || url.search || url.hash
+        || url.pathname !== `/api/gateway/${encodeURIComponent(expected.project)}/draft/${value.draftId}`)
+        return undefined;
+    return Object.freeze({ draftId: value.draftId, name: expected.name, stagingUrl: url.href });
+}

package/dist/utils/field-namer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Hands out the field names of one generated dataset. A field's name is also
+ * its SQL alias, and ClickHouse resolves an alias before a column of the same
+ * name, so a field may take a source column's name only when it reads exactly
+ * that column; otherwise every expression reading that column would read the
+ * aliased field instead. A name that is taken, or is another column's name,
+ * gets the lowest free numeric suffix (`fareTotal2`).
+ */
+export declare function createFieldNamer(columnNames: readonly string[]): (base: string, ownColumn?: string) => string;
+//# sourceMappingURL=field-namer.d.ts.map

package/dist/utils/field-namer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-namer.d.ts","sourceRoot":"","sources":["../../src/utils/field-namer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,IAGrD,MAAM,MAAM,EAAE,YAAY,MAAM,KAAG,MAAM,CAQlD"}

package/dist/utils/field-namer.js

@@ -0,0 +1,20 @@
+/**
+ * Hands out the field names of one generated dataset. A field's name is also
+ * its SQL alias, and ClickHouse resolves an alias before a column of the same
+ * name, so a field may take a source column's name only when it reads exactly
+ * that column; otherwise every expression reading that column would read the
+ * aliased field instead. A name that is taken, or is another column's name,
+ * gets the lowest free numeric suffix (`fareTotal2`).
+ */
+export function createFieldNamer(columnNames) {
+    const columns = new Set(columnNames);
+    const taken = new Set();
+    return (base, ownColumn) => {
+        let name = base;
+        for (let suffix = 2; taken.has(name) || (columns.has(name) && name !== ownColumn); suffix += 1) {
+            name = `${base}${suffix}`;
+        }
+        taken.add(name);
+        return name;
+    };
+}

package/dist/utils/json-pointer.d.ts

@@ -0,0 +1,3 @@
+/** RFC 6901: append *key* to the JSON pointer *path*. */
+export declare function pointer(path: string, key: string): string;
+//# sourceMappingURL=json-pointer.d.ts.map

package/dist/utils/json-pointer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-pointer.d.ts","sourceRoot":"","sources":["../../src/utils/json-pointer.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/utils/json-pointer.js

@@ -0,0 +1,4 @@
+/** RFC 6901: append *key* to the JSON pointer *path*. */
+export function pointer(path, key) {
+    return `${path}/${key.replaceAll('~', '~0').replaceAll('/', '~1')}`;
+}

package/dist/utils/telemetry/catalog.d.ts

@@ -625,7 +625,7 @@ export declare const EVENT_CATALOG: {
             readonly flags_used: {
                 readonly kind: "enum_list";
                 readonly description: string;
-                readonly values: readonly ("--path" | "--style" | "--database" | "--chdb-path" | "--auth" | "--all-tables" | "--tables" | "--exclude-tables" | "--no-example" | "--no-interactive" | "--force" | "--skip-connection" | "--port" | "--hostname" | "--no-watch" | "--no-cache" | "--cache" | "--redis-url" | "--open" | "--cors" | "--quiet" | "--tenant" | "--self-test" | "--url" | "--client-contract-url" | "--output" | "--tenant-column" | "--check" | "--diff" | "--cloud-url" | "--environment" | "--bundle-output" | "--release-output" | "--project" | "--no-source" | "--endpoint" | "--replace-restored" | "--mcp-config" | "--release" | "--no-telemetry" | "--help" | "--version")[];
+                readonly values: readonly ("--path" | "--style" | "--database" | "--chdb-path" | "--auth" | "--all-tables" | "--tables" | "--exclude-tables" | "--no-example" | "--no-interactive" | "--force" | "--skip-connection" | "--port" | "--hostname" | "--no-watch" | "--no-cache" | "--cache" | "--redis-url" | "--open" | "--cors" | "--quiet" | "--tenant" | "--self-test" | "--url" | "--client-contract-url" | "--output" | "--tenant-column" | "--check" | "--diff" | "--cloud-url" | "--environment" | "--bundle-output" | "--release-output" | "--project" | "--no-source" | "--endpoint" | "--replace-restored" | "--mcp-config" | "--draft" | "--release" | "--no-telemetry" | "--help" | "--version")[];
             };
             readonly outcome: {
                 readonly kind: "enum";

package/dist/utils/telemetry/domains.d.ts

@@ -18,11 +18,11 @@ export declare const COMMAND_FLAGS: {
     readonly 'generate:client': readonly ["--output", "--check", "--force"];
     readonly login: readonly ["--cloud-url", "--environment"];
     readonly logout: readonly [];
-    readonly deploy: readonly ["--bundle-output", "--release-output", "--project", "--environment", "--no-source", "--endpoint", "--replace-restored", "--mcp-config"];
+    readonly deploy: readonly ["--bundle-output", "--release-output", "--project", "--environment", "--no-source", "--endpoint", "--replace-restored", "--mcp-config", "--draft"];
     readonly 'deployment:build': readonly ["--bundle-output", "--no-source"];
     readonly 'deployment:validate': readonly [];
     readonly 'deployment:release': readonly ["--project", "--environment", "--output"];
-    readonly 'deployment:submit': readonly ["--release", "--endpoint", "--replace-restored"];
+    readonly 'deployment:submit': readonly ["--release", "--endpoint", "--replace-restored", "--draft"];
     readonly 'deployment:status': readonly ["--project", "--environment", "--endpoint", "--mcp-config"];
     readonly pull: readonly ["--output", "--project", "--environment", "--endpoint"];
     readonly diff: readonly ["--project", "--environment", "--endpoint"];
@@ -44,11 +44,11 @@ export declare const VALUE_FLAGS: {
     readonly 'generate:client': readonly ["--output"];
     readonly login: readonly ["--cloud-url", "--environment"];
     readonly logout: readonly [];
-    readonly deploy: readonly ["--bundle-output", "--release-output", "--project", "--environment", "--endpoint"];
+    readonly deploy: readonly ["--bundle-output", "--release-output", "--project", "--environment", "--endpoint", "--draft"];
     readonly 'deployment:build': readonly ["--bundle-output"];
     readonly 'deployment:validate': readonly [];
     readonly 'deployment:release': readonly ["--project", "--environment", "--output"];
-    readonly 'deployment:submit': readonly ["--release", "--endpoint"];
+    readonly 'deployment:submit': readonly ["--release", "--endpoint", "--draft"];
     readonly 'deployment:status': readonly ["--project", "--environment", "--endpoint"];
     readonly pull: readonly ["--output", "--project", "--environment", "--endpoint"];
     readonly diff: readonly ["--project", "--environment", "--endpoint"];

package/dist/utils/telemetry/domains.js

@@ -27,11 +27,11 @@ export const COMMAND_FLAGS = {
     'generate:client': ['--output', '--check', '--force'],
     login: ['--cloud-url', '--environment'],
     logout: [],
-    deploy: ['--bundle-output', '--release-output', '--project', '--environment', '--no-source', '--endpoint', '--replace-restored', '--mcp-config'],
+    deploy: ['--bundle-output', '--release-output', '--project', '--environment', '--no-source', '--endpoint', '--replace-restored', '--mcp-config', '--draft'],
     'deployment:build': ['--bundle-output', '--no-source'],
     'deployment:validate': [],
     'deployment:release': ['--project', '--environment', '--output'],
-    'deployment:submit': ['--release', '--endpoint', '--replace-restored'],
+    'deployment:submit': ['--release', '--endpoint', '--replace-restored', '--draft'],
     'deployment:status': ['--project', '--environment', '--endpoint', '--mcp-config'],
     pull: ['--output', '--project', '--environment', '--endpoint'],
     diff: ['--project', '--environment', '--endpoint'],
@@ -50,11 +50,11 @@ export const VALUE_FLAGS = {
     'generate:client': ['--output'],
     login: ['--cloud-url', '--environment'],
     logout: [],
-    deploy: ['--bundle-output', '--release-output', '--project', '--environment', '--endpoint'],
+    deploy: ['--bundle-output', '--release-output', '--project', '--environment', '--endpoint', '--draft'],
     'deployment:build': ['--bundle-output'],
     'deployment:validate': [],
     'deployment:release': ['--project', '--environment', '--output'],
-    'deployment:submit': ['--release', '--endpoint'],
+    'deployment:submit': ['--release', '--endpoint', '--draft'],
     'deployment:status': ['--project', '--environment', '--endpoint'],
     pull: ['--output', '--project', '--environment', '--endpoint'],
     diff: ['--project', '--environment', '--endpoint'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/cli",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "description": "CLI for scaffolding type-safe ClickHouse analytics, semantic datasets, React manifests, and deployments",
   "keywords": [
     "clickhouse",
@@ -30,8 +30,8 @@
     "open": "^11.0.4",
     "ora": "^8.0.1",
     "prompts": "^2.4.2",
-    "@hypequery/deployment": "0.11.0",
-    "@hypequery/protocol": "0.24.0"
+    "@hypequery/deployment": "0.11.1",
+    "@hypequery/protocol": "0.24.1"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "2.1.2"
@@ -54,8 +54,8 @@
     "@vitest/coverage-v8": "^5.0.5",
     "typescript": "^6.0.3",
     "vitest": "^5.0.5",
-    "@hypequery/mcp": "0.11.0",
-    "@hypequery/serve": "0.24.0"
+    "@hypequery/mcp": "0.11.1",
+    "@hypequery/serve": "0.24.1"
   },
   "repository": {
     "type": "git",