@hypequery/cli 1.24.1 → 1.25.0

package/README.md

@@ -37,12 +37,44 @@ npx hypequery init \
 | `hypequery dev` | Local API, docs, and hot reload |
 | `hypequery generate` | Fresh TypeScript types from ClickHouse or chDB |
 | `hypequery generate:datasets` | Dataset definitions scaffolded from tables |
+| `hypequery generate:client` | TypeScript API types and routes from a Python client contract |
 | `hypequery generate:manifest` | A browser-safe route manifest for React hooks |
 | `hypequery pull` / `diff` | Live source inspection and comparison |
 | `hypequery deployment:status` | Live release and Cloud-provided connection URLs |
 
 Non-interactive ClickHouse commands read `CLICKHOUSE_URL`, `CLICKHOUSE_DATABASE`, `CLICKHOUSE_USERNAME`, and `CLICKHOUSE_PASSWORD`.
 
+## Generate a client for Python endpoints
+
+Export a build contract from your Python definition-only factory, then generate
+one TypeScript file with no backend imports:
+
+```bash
+# In the Python project (the factory returns export_client_contract(...)):
+hypequery export client-contract --factory analytics.contract:build --output client-contract.json
+
+# In the frontend project:
+npx hypequery generate:client ../backend/client-contract.json --output src/hypequery-client.ts
+npx hypequery generate:client ../backend/client-contract.json --output src/hypequery-client.ts --check
+```
+
+The file exports `ClientApi`, `clientManifest`, `clientContractHash` and public
+response metadata types. It preserves installed POST paths, endpoint schema
+hashes, metric aliases, default measures, field-specific filter types and wire
+nullability. Numeric dimensions can be strings on the wire; aggregate values are
+strings or null. Time buckets may be null when the physical time column is null.
+Results use optional fields until a consumer narrows the query's selections.
+
+Generation reads local JSON only (1 MiB maximum); it never evaluates a backend
+module or fetches an endpoint. Signed identities, duplicate JSON members and
+strict contract bounds are checked before writing. Use the owner-controlled
+`build` view; principal-specific live discovery is for runtime consumers.
+`--check` detects drift without creating directories or changing files. Existing
+output requires `--force` to replace, and symlinked output paths are refused.
+Generated output is bounded to 16 MiB. TypeScript describes structural inputs;
+the Python endpoint still validates timezones, selection dependencies, query
+budgets and authorization on every request.
+
 ## Why use the CLI
 
 - Get correct ClickHouse runtime types instead of guessing interfaces.
@@ -58,3 +90,36 @@ Non-interactive ClickHouse commands read `CLICKHOUSE_URL`, `CLICKHOUSE_DATABASE`
 ## License
 
 Apache-2.0.
+
+### Python HTTP datasets over MCP
+
+For a Python API exposing an authorized client-contract endpoint, install a
+compatible `@hypequery/mcp` alongside the CLI in your Node project, then run:
+
+```bash
+# Supply the backend principal's Bearer credential through your environment.
+# Omit it only when your backend intentionally authorizes public access.
+export HYPEQUERY_API_KEY='your-backend-credential'
+hypequery mcp --client-contract-url https://api.example.com/v1/client-contract --self-test
+hypequery mcp --client-contract-url https://api.example.com/v1/client-contract
+```
+
+The self-test checks authorized discovery and tool schemas without querying
+business data. Serving uses MCP stdio: stdout carries protocol messages and
+status/errors go to stderr. Use the second command as your MCP client's command
+and arguments; supply the credential using that client's secret/environment
+configuration. Never put the credential in a URL or command argument.
+
+Python owns authentication, tenant resolution, policy and SQL execution. One
+bridge process serves one backend principal. Restart it after changing principal
+or after a stale-contract error; it never silently replaces pinned schemas or
+replays a query. HTTPS is required except on loopback, and redirects are refused.
+
+`--client-contract-url` cannot be combined with a local file, `--path`, `--tenant`
+or `--url`. The existing `--self-test --url` checks a hosted MCP endpoint; the
+new flag points at a Python HTTP discovery endpoint. No local analytics module
+or Python process is loaded by this mode. Node is needed for the MCP bridge;
+the Python API itself does not require Node.
+
+The npm packages must contain the matching client-contract features. Workspace
+qualification does not imply that these changes have already been published.

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;AAyCpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAE9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AA8RD,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;AAySD,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/cli.js

@@ -4,6 +4,7 @@ import { mcpCommand } from './commands/mcp.js';
 import { devCommand } from './commands/dev.js';
 import { generateCommand } from './commands/generate.js';
 import { generateDatasetsCommand } from './commands/generate-datasets.js';
+import { generateClientCommand } from './commands/generate-client.js';
 import { generateManifestCommand } from './commands/generate-manifest.js';
 import { buildDeploymentCommand, prepareDeploymentReleaseCommand, validateDeploymentCommand, } from './commands/deployment.js';
 import { deployCommand, submitDeploymentCommand, } from './commands/deploy.js';
@@ -132,11 +133,12 @@ program
 }));
 program
     .command('mcp [file]')
-    .description('Serve this project\'s datasets to an MCP client over stdio')
+    .description('Serve local datasets or authorized HTTP client endpoints over MCP stdio')
     .option('--path <path>', 'Analytics directory (loads <path>/api.ts or <path>/queries.ts)')
     .option('--tenant <id>', 'Trusted tenant applied to every tenant-scoped dataset')
     .option('--self-test', 'Check the entrypoint and exit without speaking MCP')
     .option('--url <url>', 'With --self-test: check a hosted MCP endpoint (key from HYPEQUERY_API_KEY)')
+    .option('--client-contract-url <url>', 'Bridge authorized HTTP client endpoints to MCP (Bearer key from HYPEQUERY_API_KEY)')
     .action(runCommand(async (file, options) => {
     await mcpCommand(file, options);
 }));
@@ -163,6 +165,15 @@ program
     .action(runCommand(async (options) => {
     await generateDatasetsCommand(options);
 }));
+program
+    .command('generate:client <contract>')
+    .description('Generate browser-safe TypeScript API types and routes from a client contract JSON file')
+    .option('-o, --output <path>', 'Output TypeScript file (default: analytics/hypequery-client.ts)')
+    .option('--check', 'Check for drift without writing')
+    .option('--force', 'Replace an existing output file')
+    .action(runCommand(async (contract, options) => {
+    await generateClientCommand(contract, options);
+}));
 program
     .command('generate:manifest <api>')
     .description('Generate a static React hook manifest from a hypequery API module')

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

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAkCA,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,iBA2OvE"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,iBA8OvE"}

package/dist/commands/dev.js

@@ -1,3 +1,4 @@
+import { loadServeDev } from '../utils/load-serve-dev.js';
 import { exitWith, finishAndExit } from '../utils/command-exit.js';
 import { telemetryErrorCode } from '../utils/telemetry/error-code.js';
 import { DevSession } from '../utils/telemetry/dev-session.js';
@@ -69,6 +70,9 @@ export async function devCommand(file, options = {}) {
         const dbSpinner = ora('Connecting to ClickHouse...').start();
         let loading = true;
         try {
+            // Before the API module: it imports @hypequery/serve itself, and failing
+            // there would hide which package to install.
+            const { serveDev } = await loadServeDev();
             // Load the API module
             const api = await loadApiModule(queriesFile);
             loading = false;
@@ -92,7 +96,6 @@ export async function devCommand(file, options = {}) {
             logger.success(`Registered ${queryCount} ${queryCount === 1 ? 'query' : 'queries'}`);
             logger.newline();
             // Start the server
-            const { serveDev } = await import('@hypequery/serve/dev');
             currentServer = await serveDev(api, {
                 port: options.port,
                 hostname: options.hostname,

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

@@ -0,0 +1,7 @@
+export interface GenerateClientOptions {
+    output?: string;
+    check?: boolean;
+    force?: boolean;
+}
+export declare function generateClientCommand(artifact: string, options?: GenerateClientOptions): Promise<void>;
+//# sourceMappingURL=generate-client.d.ts.map

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

@@ -0,0 +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"}

package/dist/commands/generate-client.js

@@ -0,0 +1,45 @@
+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 { writeGeneratedFileAtomically } from '../utils/generated-file.js';
+import { logger } from '../utils/logger.js';
+import { updateCommandTelemetry, setCommandTelemetryError } from '../utils/telemetry/command-context.js';
+import { countBucket } from '../utils/telemetry/buckets.js';
+export async function generateClientCommand(artifact, options = {}) {
+    updateCommandTelemetry('generate:client', { mode: options.check ? 'check' : 'write', force: !!options.force, custom_output: options.output !== undefined });
+    if (options.force && options.check)
+        throw new Error('--force cannot be combined with --check.');
+    const input = path.resolve(artifact);
+    const output = path.resolve(options.output ?? 'analytics/hypequery-client.ts');
+    if (input === output)
+        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));
+    if (contract.view !== 'build')
+        throw new Error('Client generation requires a build view exported by the definition owner.');
+    const contents = renderClientContract(contract);
+    if (Buffer.byteLength(contents) > 16 * 1_048_576)
+        throw new Error('Generated client exceeds the 16 MiB output limit.');
+    updateCommandTelemetry('generate:client', { endpoint_count_bucket: countBucket(contract.endpoints.length) });
+    if (current === contents) {
+        updateCommandTelemetry('generate:client', { check_result: 'up_to_date' });
+        logger.success('Client types and routes are up to date.');
+        return;
+    }
+    if (options.check) {
+        updateCommandTelemetry('generate:client', { check_result: current === undefined ? 'missing' : 'out_of_date' });
+        setCommandTelemetryError(current === undefined ? 'output_missing' : 'output_out_of_date');
+        process.exitCode = 1;
+        logger.error('Client types and routes are missing or out of date.');
+        return;
+    }
+    if (current !== undefined && !options.force)
+        throw new Error('Refusing to overwrite client types; use --check or --force.');
+    await checkClientOutputPath(output);
+    if (await readClientOutput(output) !== current)
+        throw new Error('Client output changed during generation; retry after reviewing it.');
+    await writeGeneratedFileAtomically(output, contents, { overwrite: options.force === true });
+    logger.success('Generated client types and routes.');
+}

package/dist/commands/mcp.d.ts

@@ -9,6 +9,8 @@ export interface McpOptions {
     selfTest?: boolean;
     /** With `selfTest`: check this hosted MCP endpoint instead of a local entrypoint. */
     url?: string;
+    /** Authorized HTTP client-contract discovery; no local analytics entrypoint. */
+    clientContractUrl?: string;
 }
 export interface McpDependencies {
     loadApi?: (file: string) => Promise<unknown>;

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

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AASvF,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAMnF,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE;QACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,SAAS,EAAE,OAAO,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAClC,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAC/E,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CACpD;AAoED,wBAAsB,UAAU,CAC9B,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,GAAE,UAAe,EACxB,YAAY,GAAE,eAAoB,GACjC,OAAO,CAAC,IAAI,CAAC,CA0Ef"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AASvF,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAMnF,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE;QACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,SAAS,EAAE,OAAO,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAClC,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAC/E,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CACpD;AAoED,wBAAsB,UAAU,CAC9B,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,GAAE,UAAe,EACxB,YAAY,GAAE,eAAoB,GACjC,OAAO,CAAC,IAAI,CAAC,CAiFf"}

package/dist/commands/mcp.js

@@ -1,3 +1,4 @@
+import { runHttpMcp } from '../utils/mcp-http.js';
 import { exitWith } from '../utils/command-exit.js';
 import { runMcpUntilSignal } from '../utils/mcp-lifecycle.js';
 import { routeConsoleOutputToStderr } from '../utils/mcp-console.js';
@@ -77,7 +78,10 @@ function resolveSource(api, file) {
 }
 export async function mcpCommand(file, options = {}, dependencies = {}) {
     const telemetry = new McpSession();
-    updateCommandTelemetry('mcp', { mode: options.selfTest ? 'self_test' : 'serve', hosted: !!options.url, tenant_used: !!options.tenant });
+    updateCommandTelemetry('mcp', { mode: options.selfTest ? 'self_test' : 'serve', hosted: !!options.url, tenant_used: !!options.tenant, http_backend: !!options.clientContractUrl });
+    if (options.clientContractUrl !== undefined && (file !== undefined || options.path !== undefined || options.tenant !== undefined || options.url !== undefined)) {
+        fail('--client-contract-url cannot be combined with a file, --path, --tenant or --url.');
+    }
     if (options.url && !options.selfTest) {
         fail('--url is only used with --self-test.', [
             'MCP clients connect to the hosted endpoint directly; this command serves a local project.',
@@ -85,6 +89,10 @@ export async function mcpCommand(file, options = {}, dependencies = {}) {
     }
     const restoreConsole = routeConsoleOutputToStderr();
     try {
+        if (options.clientContractUrl !== undefined) {
+            await runHttpMcp(options.clientContractUrl, !!options.selfTest, dependencies, telemetry);
+            return;
+        }
         if (options.url) {
             await remoteSelfTest(options.url, dependencies);
             return;

package/dist/generators/client-contract/input-types.d.ts

@@ -0,0 +1,7 @@
+import type { ProtocolClientEndpoint } from '@hypequery/protocol';
+export declare const literal: (value: string) => string;
+export declare const union: (values: readonly string[]) => string;
+export declare const names: (values: readonly string[]) => string;
+/** Structural types mirror the closed profile; runtime also checks selection dependencies and budgets. */
+export declare function clientInputType(endpoint: ProtocolClientEndpoint): string;
+//# sourceMappingURL=input-types.d.ts.map

package/dist/generators/client-contract/input-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-types.d.ts","sourceRoot":"","sources":["../../../src/generators/client-contract/input-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,KAAG,MAA+B,CAAC;AACxE,eAAO,MAAM,KAAK,GAAI,QAAQ,SAAS,MAAM,EAAE,KAAG,MAAsD,CAAC;AACzG,eAAO,MAAM,KAAK,GAAI,QAAQ,SAAS,MAAM,EAAE,KAAG,MAAgD,CAAC;AAWnG,0GAA0G;AAC1G,wBAAgB,eAAe,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,CAqBxE"}

package/dist/generators/client-contract/input-types.js

@@ -0,0 +1,34 @@
+export const literal = (value) => JSON.stringify(value);
+export const union = (values) => values.length ? values.join(' | ') : 'never';
+export const names = (values) => union([...values].sort().map(literal));
+function predicate(field, definition, having = false) {
+    const scalar = definition.type === 'number' ? 'number' : definition.type === 'boolean' ? 'boolean' : 'string';
+    return [...definition.operators].sort().map(operator => {
+        const value = operator === 'between' ? `readonly [${scalar}, ${scalar}]`
+            : operator === 'in' || operator === 'notIn' ? `readonly [${scalar}, ...${scalar}[]]` : scalar;
+        return `{ readonly ${having ? 'measure' : 'field'}: ${literal(field)}; readonly operator: ${literal(operator)}; readonly value: ${value} }`;
+    });
+}
+/** Structural types mirror the closed profile; runtime also checks selection dependencies and budgets. */
+export function clientInputType(endpoint) {
+    const dimensions = Object.keys(endpoint.dimensions).filter(key => endpoint.dimensions[key].groupable);
+    const measures = Object.keys(endpoint.measures);
+    const filters = Object.keys(endpoint.filters).sort().flatMap(key => predicate(key, endpoint.filters[key]));
+    const having = measures.filter(key => endpoint.measures[key].having).sort().flatMap(key => predicate(key, {
+        type: 'number', operators: ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'between', 'in', 'notIn'],
+    }, true));
+    const ordered = [...dimensions.filter(key => endpoint.dimensions[key].orderable), ...measures,
+        ...(endpoint.time ? ['period'] : [])];
+    return `{
+    readonly dimensions?: readonly (${names(dimensions)})[];
+    readonly filters?: readonly (${union(filters)})[];
+    readonly orderBy?: readonly { readonly field: ${names(ordered)}; readonly direction: 'asc' | 'desc' }[];
+    readonly limit?: number;
+    readonly offset?: number;
+    readonly includeMeta?: ${endpoint.metadata ? 'boolean' : 'false'};
+    ${endpoint.kind === 'dataset' ? `readonly measures?: readonly (${names(measures)})[];
+    readonly having?: readonly (${union(having)})[];` : ''}
+    ${endpoint.time ? `readonly by?: ${names(endpoint.time.grains)};
+    ${endpoint.time.timezone ? 'readonly timezone?: string;' : ''}` : ''}
+  }`;
+}

package/dist/generators/client-contract/render.d.ts

@@ -0,0 +1,3 @@
+/** Data-only generator: no API module evaluation, credentials, drivers or server dependencies. */
+export declare function renderClientContract(source: unknown): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/generators/client-contract/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/generators/client-contract/render.ts"],"names":[],"mappings":"AA0BA,kGAAkG;AAClG,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAqB5D"}

package/dist/generators/client-contract/render.js

@@ -0,0 +1,46 @@
+import { validateProtocolClientContract } from '@hypequery/protocol';
+import { clientInputType, literal } from './input-types.js';
+function dimensionType(definition) {
+    const wire = definition.wireType === 'number-or-string' ? 'number | string' : definition.wireType;
+    return wire + (definition.nullable === false ? '' : ' | null');
+}
+function endpointType(endpoint) {
+    const dimensions = Object.keys(endpoint.dimensions).sort().filter(key => endpoint.dimensions[key].groupable)
+        .map(key => `readonly ${literal(key)}?: ${dimensionType(endpoint.dimensions[key])};`);
+    const measures = Object.keys(endpoint.measures).sort().map(key => `readonly ${literal(key)}?: string | null;`);
+    // The physical time column may be nullable; the descriptor makes no non-null guarantee.
+    const row = `{ ${[...dimensions, ...measures, ...(endpoint.time ? ['readonly period?: string | null;'] : [])].join('\n')} }`;
+    const semantic = {
+        version: 1, kind: endpoint.kind, dimensions: Object.fromEntries(Object.keys(endpoint.dimensions).sort().map(key => [key, { wireType: endpoint.dimensions[key].wireType, nullable: endpoint.dimensions[key].nullable }])),
+        ...(endpoint.kind === 'dataset' ? { measures: Object.fromEntries(Object.keys(endpoint.measures).sort().map(key => [key, { wireType: 'string', nullable: true }])), defaultMeasures: endpoint.defaultMeasures }
+            : { metricName: Object.keys(endpoint.measures)[0] }),
+    };
+    return `{
+    input: ${clientInputType(endpoint)};
+    output: { data: ${row}[]; meta?: ClientResponseMeta | null };
+    readonly __hypequeryClientSemantic?: ${JSON.stringify(semantic)};
+  }`;
+}
+/** Data-only generator: no API module evaluation, credentials, drivers or server dependencies. */
+export function renderClientContract(source) {
+    const contract = validateProtocolClientContract(source);
+    const endpoints = [...contract.endpoints].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    const entries = endpoints.map(endpoint => ({ endpoint, key: endpoint.kind === 'dataset' ? `dataset:${endpoint.id}` : endpoint.id }));
+    return `// Generated by hypequery generate:client. Do not edit.
+// Runtime validation still enforces selection dependencies, timezones and query budgets.
+export interface ClientResponseMeta {
+  requestId: string;
+  timingMs: number;
+  rowCount: number;
+  pagination: { limit: number; offset: number; hasMore: boolean };
+  cache?: { hit: boolean };
+}
+export type ClientApi = {
+${entries.map(({ endpoint, key }) => `  ${literal(key)}: ${endpointType(endpoint)};`).join('\n')}
+};
+export const clientManifest = {
+${entries.map(({ endpoint, key }) => `  [${literal(key)}]: { method: 'POST', path: ${literal(endpoint.path)}, schemaHash: ${literal(endpoint.schemaHash)} },`).join('\n')}
+} as const;
+export const clientContractHash = ${literal(contract.contentHash)} as const;
+`;
+}

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

@@ -0,0 +1,6 @@
+/** Refuse filesystem indirection for generated output and its existing ancestors. */
+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>;
+//# sourceMappingURL=client-contract-file.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,58 @@
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import path from 'node:path';
+/** Refuse filesystem indirection for generated output and its existing ancestors. */
+export async function checkClientOutputPath(filePath) {
+    let current = path.resolve(filePath);
+    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.');
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return;
+        current = parent;
+    }
+}
+/** 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);
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.size > maxBytes)
+            throw new Error('Client artifact must be a regular file within the byte limit.');
+        const buffer = Buffer.alloc(maxBytes + 1);
+        let size = 0;
+        while (size < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, size, buffer.length - size, null);
+            if (!bytesRead)
+                break;
+            size += bytesRead;
+        }
+        const after = await handle.stat();
+        if (size > maxBytes || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) {
+            throw new Error('Client artifact exceeded its byte limit or changed while reading.');
+        }
+        return new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, size));
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function readClientOutput(filePath) {
+    try {
+        return await readClientArtifact(filePath, 16 * 1_048_576);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}

package/dist/utils/dependency-installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dependency-installer.d.ts","sourceRoot":"","sources":["../../src/utils/dependency-installer.ts"],"names":[],"mappings":"AAWA,KAAK,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;AAC5C,KAAK,gBAAgB,GAAG,YAAY,GAAG,MAAM,CAAC;AAwE9C,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEpE;AAqCD,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,KAAK,GAAE,aAAyB,EAChC,QAAQ,GAAE,gBAA+B,GACxC,MAAM,EAAE,CAmBV;AAsBD,wBAAsB,2BAA2B,CAC/C,KAAK,GAAE,aAAyB,EAChC,QAAQ,GAAE,gBAA+B,iBAyD1C;AAED,eAAO,MAAM,wBAAwB,oCAA8B,CAAC"}
+{"version":3,"file":"dependency-installer.d.ts","sourceRoot":"","sources":["../../src/utils/dependency-installer.ts"],"names":[],"mappings":"AAWA,KAAK,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;AAC5C,KAAK,gBAAgB,GAAG,YAAY,GAAG,MAAM,CAAC;AAwE9C,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEpE;AAqCD,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,KAAK,GAAE,aAAyB,EAChC,QAAQ,GAAE,gBAA+B,GACxC,MAAM,EAAE,CAmBV;AA8CD,wBAAsB,2BAA2B,CAC/C,KAAK,GAAE,aAAyB,EAChC,QAAQ,GAAE,gBAA+B,iBAyD1C;AAED,eAAO,MAAM,wBAAwB,oCAA8B,CAAC"}

package/dist/utils/dependency-installer.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { logger } from './logger.js';
-const ZOD_SCAFFOLD_VERSION = '^3.23.8';
+const ZOD_SCAFFOLD_VERSION = '^4.6.6';
 // chdb/hypequery (the embedded adapter subpath) ships from chdb 3.2.0.
 const CHDB_SCAFFOLD_VERSION = '^3.2.0';
 const STABLE_SCAFFOLD_PACKAGES = ['@hypequery/clickhouse', '@hypequery/serve', `zod@${ZOD_SCAFFOLD_VERSION}`];
@@ -120,12 +120,36 @@ export function resolveScaffoldPackages(cliVersion, style = 'queries', database
         ...(includeChdb ? [`chdb@${CHDB_SCAFFOLD_VERSION}`] : []),
     ];
 }
+/** The oldest Zod 3 that Serve's `zod` peer range (`^3.23.8 || ^4.0.0`) accepts. */
+const SERVE_MIN_ZOD_3 = [3, 23, 8];
+/**
+ * Whether a project's `zod` range can only resolve versions Serve accepts:
+ * its lowest version, the first `x.y.z` in it (missing parts count as 0), is
+ * Zod 4 or at least 3.23.8. So `^3.23.8`, `~4.1.0` and `4` are kept, while
+ * `3.1.0`, `~3.1.0` and `3` are upgraded. Tags such as `latest` are upgraded.
+ */
+function isServeCompatibleZodRange(range) {
+    const match = /(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(range);
+    if (!match)
+        return false;
+    const [major, minor, patch] = [match[1], match[2], match[3]].map(part => Number(part ?? 0));
+    if (major === 4)
+        return true;
+    if (major !== 3)
+        return false;
+    const [, minMinor, minPatch] = SERVE_MIN_ZOD_3;
+    return minor > minMinor || (minor === minMinor && patch >= minPatch);
+}
 function shouldInstallPackage(pkgJson, specifier) {
     const name = packageNameFromSpecifier(specifier);
     const existingVersion = getDependencyVersion(pkgJson, name);
     if (!existingVersion) {
         return true;
     }
+    // Serve accepts Zod 3 or Zod 4, so keep whichever the project already uses.
+    if (name === 'zod' && isServeCompatibleZodRange(existingVersion)) {
+        return false;
+    }
     const desiredHasPinnedVersion = specifier.startsWith('@')
         ? specifier.indexOf('@', specifier.indexOf('/') + 1) !== -1
         : specifier.includes('@');

package/dist/utils/load-env-files.js

@@ -18,7 +18,7 @@ export async function loadEnvFiles(directory) {
         const { config } = await import('dotenv');
         for (const file of envFiles(process.env.NODE_ENV)) {
             // Missing files are a no-op.
-            config({ path: path.join(resolved, file) });
+            config({ path: path.join(resolved, file), quiet: true });
         }
     }
     catch {

package/dist/utils/load-serve-dev.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@hypequery/serve` is an optional peer: projects that only generate clients
+ * (a React app, for example) should not have server packages installed for them.
+ */
+export declare function loadServeDev(load?: () => Promise<typeof import('@hypequery/serve/dev')>): Promise<typeof import('@hypequery/serve/dev')>;
+//# sourceMappingURL=load-serve-dev.d.ts.map

package/dist/utils/load-serve-dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-serve-dev.d.ts","sourceRoot":"","sources":["../../src/utils/load-serve-dev.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAsB,YAAY,CAChC,IAAI,GAAE,MAAM,OAAO,CAAC,cAAc,sBAAsB,CAAC,CAAwC,GAChG,OAAO,CAAC,cAAc,sBAAsB,CAAC,CAAC,CAYhD"}

package/dist/utils/load-serve-dev.js

@@ -0,0 +1,18 @@
+/**
+ * `@hypequery/serve` is an optional peer: projects that only generate clients
+ * (a React app, for example) should not have server packages installed for them.
+ */
+export async function loadServeDev(load = () => import('@hypequery/serve/dev')) {
+    try {
+        return await load();
+    }
+    catch (error) {
+        const code = error.code;
+        const message = error instanceof Error ? error.message : '';
+        // Only serve itself: a module serve fails to find is a different problem.
+        if ((code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') && message.includes("'@hypequery/serve")) {
+            throw new Error('hypequery dev needs @hypequery/serve. Install it: npm install @hypequery/serve');
+        }
+        throw error;
+    }
+}

package/dist/utils/mcp-http.d.ts

@@ -0,0 +1,12 @@
+import type { McpSession } from './telemetry/mcp-session.js';
+interface HttpMcpDependencies {
+    loadMcp?: () => Promise<unknown>;
+    env?: Readonly<Record<string, string | undefined>>;
+}
+type HttpMcpPackage = Pick<typeof import('@hypequery/mcp'), 'createMCPHttpExecutor' | 'createMCPProtocolServer' | 'connectMCPServerStdio'>;
+/** Load the user's optional peer without requiring or importing an analytics entrypoint. */
+export declare function loadHttpMcp(load?: () => Promise<unknown>): Promise<HttpMcpPackage>;
+/** One backend principal per process. Python resolves authorization and tenant context. */
+export declare function runHttpMcp(url: string, selfTest: boolean, dependencies: HttpMcpDependencies, telemetry: McpSession): Promise<void>;
+export {};
+//# sourceMappingURL=mcp-http.d.ts.map

package/dist/utils/mcp-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-http.d.ts","sourceRoot":"","sources":["../../src/utils/mcp-http.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D,UAAU,mBAAmB;IAC3B,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CACpD;AACD,KAAK,cAAc,GAAG,IAAI,CAAC,cAAc,gBAAgB,CAAC,EAAE,uBAAuB,GAAG,yBAAyB,GAAG,uBAAuB,CAAC,CAAC;AAE3I,4FAA4F;AAC5F,wBAAsB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAUxF;AAED,2FAA2F;AAC3F,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAgCxI"}

package/dist/utils/mcp-http.js

@@ -0,0 +1,65 @@
+import path from 'node:path';
+import { importFromProject } from './project-root.js';
+import { runMcpUntilSignal } from './mcp-lifecycle.js';
+import { MCP_API_KEY_VARIABLE } from './hosted-endpoints.js';
+import { logger } from './logger.js';
+/** Load the user's optional peer without requiring or importing an analytics entrypoint. */
+export async function loadHttpMcp(load) {
+    let candidate;
+    try {
+        candidate = await (load ?? (() => importFromProject('@hypequery/mcp', path.join(process.cwd(), '__hypequery_mcp__.js'), () => import('@hypequery/mcp'))))();
+    }
+    catch {
+        throw new Error('Install @hypequery/mcp with HTTP client-contract support in this project.');
+    }
+    const module = candidate;
+    if (!module || typeof module.createMCPHttpExecutor !== 'function' || typeof module.createMCPProtocolServer !== 'function' || typeof module.connectMCPServerStdio !== 'function') {
+        throw new Error('Upgrade @hypequery/mcp in this project to a version with createMCPHttpExecutor support.');
+    }
+    return module;
+}
+/** One backend principal per process. Python resolves authorization and tenant context. */
+export async function runHttpMcp(url, selfTest, dependencies, telemetry) {
+    const module = await loadHttpMcp(dependencies.loadMcp);
+    const key = (dependencies.env ?? process.env)[MCP_API_KEY_VARIABLE]?.trim();
+    const create = async (signal) => {
+        try {
+            return await module.createMCPHttpExecutor({ url, ...(key ? { headers: { authorization: `Bearer ${key}` } } : {}) }, signal);
+        }
+        catch {
+            if (signal?.aborted)
+                throw signal.reason;
+            // Do not echo a URL, credential, backend response or user-installed peer's error.
+            throw new Error('Could not initialize the HTTP MCP bridge. Check the discovery URL, backend access and client-contract compatibility.');
+        }
+    };
+    if (selfTest) {
+        const executor = await create();
+        let tools;
+        try {
+            tools = await executor.listTools();
+        }
+        catch {
+            throw new Error('HTTP MCP discovery check failed. Check backend access and reconnect after contract changes.');
+        }
+        logger.success('Authorized HTTP client contract is ready for MCP.');
+        logger.info(`Tools: ${tools.tools.length}`);
+        logger.info('No query tool was called. Python resolves the principal and tenant.');
+        return;
+    }
+    await runMcpUntilSignal(async (signal) => {
+        const executor = await create(signal);
+        signal.throwIfAborted();
+        const server = module.createMCPProtocolServer({ executor: telemetry.instrument(executor) });
+        try {
+            await module.connectMCPServerStdio(server);
+        }
+        catch {
+            await server.close().catch(() => undefined);
+            throw new Error('Could not connect the MCP stdio transport.');
+        }
+        telemetry.start({ mode: 'serve', tenant_used: false, http_backend: true });
+        process.stderr.write('hypequery MCP serving an authorized HTTP client contract.\n');
+        return server;
+    });
+}

package/dist/utils/mcp-lifecycle.d.ts

@@ -2,5 +2,5 @@ export interface CloseableMcpServer {
     close(): Promise<void>;
 }
 /** Own signal listeners for exactly the lifetime of the stdio server. */
-export declare function runMcpUntilSignal(start: () => Promise<CloseableMcpServer>): Promise<void>;
+export declare function runMcpUntilSignal(start: (signal: AbortSignal) => Promise<CloseableMcpServer>): Promise<void>;
 //# sourceMappingURL=mcp-lifecycle.d.ts.map

package/dist/utils/mcp-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-lifecycle.d.ts","sourceRoot":"","sources":["../../src/utils/mcp-lifecycle.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,yEAAyE;AACzE,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB/F"}
+{"version":3,"file":"mcp-lifecycle.d.ts","sourceRoot":"","sources":["../../src/utils/mcp-lifecycle.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,yEAAyE;AACzE,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBlH"}

package/dist/utils/mcp-lifecycle.js

@@ -1,13 +1,21 @@
 /** Own signal listeners for exactly the lifetime of the stdio server. */
 export async function runMcpUntilSignal(start) {
+    const controller = new AbortController();
     let stop;
-    const stopped = new Promise(resolve => { stop = resolve; });
+    const stopped = new Promise(resolve => { stop = () => { controller.abort(); resolve(); }; });
     // Install before awaiting startup so a signal during connection is retained.
     process.on('SIGINT', stop);
     process.on('SIGTERM', stop);
     let server;
     try {
-        server = await start();
+        try {
+            server = await start(controller.signal);
+        }
+        catch (error) {
+            if (controller.signal.aborted && error === controller.signal.reason)
+                return;
+            throw error;
+        }
         await stopped;
     }
     finally {

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

@@ -111,7 +111,7 @@ export declare const COMMAND_PROPERTIES: {
         readonly help_topic: {
             readonly kind: "enum";
             readonly description: string;
-            readonly values: readonly ["root", "init", "dev", "mcp", "generate", "generate:types", "generate:datasets", "generate:manifest", "login", "logout", "deploy", "deployment:build", "deployment:validate", "deployment:release", "deployment:submit", "deployment:status", "pull", "diff", "help", "version", "telemetry", "unknown"];
+            readonly values: readonly ["root", "init", "dev", "mcp", "generate", "generate:types", "generate:datasets", "generate:manifest", "generate:client", "login", "logout", "deploy", "deployment:build", "deployment:validate", "deployment:release", "deployment:submit", "deployment:status", "pull", "diff", "help", "version", "telemetry", "unknown"];
         } & {
             readonly optional: true;
         };
@@ -259,6 +259,12 @@ export declare const COMMAND_PROPERTIES: {
         } & {
             readonly optional: true;
         };
+        readonly http_backend: {
+            readonly kind: "boolean";
+            readonly description: string;
+        } & {
+            readonly optional: true;
+        };
         readonly dataset_count_bucket: {
             readonly kind: "enum";
             readonly description: string;
@@ -436,6 +442,41 @@ export declare const COMMAND_PROPERTIES: {
             readonly optional: true;
         };
     };
+    readonly 'generate:client': {
+        readonly mode: {
+            readonly kind: "enum";
+            readonly description: string;
+            readonly values: readonly ["write", "check"];
+        } & {
+            readonly optional: true;
+        };
+        readonly check_result: {
+            readonly kind: "enum";
+            readonly description: string;
+            readonly values: readonly ["up_to_date", "out_of_date", "missing"];
+        } & {
+            readonly optional: true;
+        };
+        readonly force: {
+            readonly kind: "boolean";
+            readonly description: string;
+        } & {
+            readonly optional: true;
+        };
+        readonly custom_output: {
+            readonly kind: "boolean";
+            readonly description: string;
+        } & {
+            readonly optional: true;
+        };
+        readonly endpoint_count_bucket: {
+            readonly kind: "enum";
+            readonly description: string;
+            readonly values: readonly ["0", "1", "2-5", "6-20", "21-100", "101+"];
+        } & {
+            readonly optional: true;
+        };
+    };
     readonly 'generate:manifest': {
         readonly query_count_bucket: {
             readonly kind: "enum";
@@ -497,6 +538,14 @@ export declare const SESSION_START_PROPERTIES: {
             readonly kind: "enum";
             readonly description: string;
             readonly values: readonly ["hypequery.ts", "api.ts", "queries.ts", "explicit_file", "unknown"];
+        } & {
+            readonly optional: true;
+        };
+        readonly http_backend: {
+            readonly kind: "boolean";
+            readonly description: string;
+        } & {
+            readonly optional: true;
         };
         readonly mode: {
             readonly kind: "enum";
@@ -507,6 +556,8 @@ export declare const SESSION_START_PROPERTIES: {
             readonly kind: "enum";
             readonly description: string;
             readonly values: readonly ["0", "1", "2-5", "6-20", "21-100", "101+"];
+        } & {
+            readonly optional: true;
         };
         readonly tenant_used: {
             readonly kind: "boolean";
@@ -516,6 +567,8 @@ export declare const SESSION_START_PROPERTIES: {
             readonly kind: "enum";
             readonly description: string;
             readonly values: readonly ["0", "1", "2-5", "6-20", "21-100", "101+"];
+        } & {
+            readonly optional: true;
         };
     };
 };
@@ -567,12 +620,12 @@ export declare const EVENT_CATALOG: {
             readonly command: {
                 readonly kind: "enum";
                 readonly description: string;
-                readonly values: readonly ["init", "dev", "mcp", "generate", "generate:types", "generate:datasets", "generate:manifest", "login", "logout", "deploy", "deployment:build", "deployment:validate", "deployment:release", "deployment:submit", "deployment:status", "pull", "diff", "help", "version", "telemetry", "unknown"];
+                readonly values: readonly ["init", "dev", "mcp", "generate", "generate:types", "generate:datasets", "generate:manifest", "generate:client", "login", "logout", "deploy", "deployment:build", "deployment:validate", "deployment:release", "deployment:submit", "deployment:status", "pull", "diff", "help", "version", "telemetry", "unknown"];
             };
             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" | "--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" | "--release" | "--no-telemetry" | "--help" | "--version")[];
             };
             readonly outcome: {
                 readonly kind: "enum";
@@ -597,7 +650,7 @@ export declare const EVENT_CATALOG: {
                 readonly help_topic: {
                     readonly kind: "enum";
                     readonly description: string;
-                    readonly values: readonly ["root", "init", "dev", "mcp", "generate", "generate:types", "generate:datasets", "generate:manifest", "login", "logout", "deploy", "deployment:build", "deployment:validate", "deployment:release", "deployment:submit", "deployment:status", "pull", "diff", "help", "version", "telemetry", "unknown"];
+                    readonly values: readonly ["root", "init", "dev", "mcp", "generate", "generate:types", "generate:datasets", "generate:manifest", "generate:client", "login", "logout", "deploy", "deployment:build", "deployment:validate", "deployment:release", "deployment:submit", "deployment:status", "pull", "diff", "help", "version", "telemetry", "unknown"];
                 } & {
                     readonly optional: true;
                 };
@@ -745,6 +798,12 @@ export declare const EVENT_CATALOG: {
                 } & {
                     readonly optional: true;
                 };
+                readonly http_backend: {
+                    readonly kind: "boolean";
+                    readonly description: string;
+                } & {
+                    readonly optional: true;
+                };
                 readonly dataset_count_bucket: {
                     readonly kind: "enum";
                     readonly description: string;
@@ -922,6 +981,41 @@ export declare const EVENT_CATALOG: {
                     readonly optional: true;
                 };
             };
+            readonly 'generate:client': {
+                readonly mode: {
+                    readonly kind: "enum";
+                    readonly description: string;
+                    readonly values: readonly ["write", "check"];
+                } & {
+                    readonly optional: true;
+                };
+                readonly check_result: {
+                    readonly kind: "enum";
+                    readonly description: string;
+                    readonly values: readonly ["up_to_date", "out_of_date", "missing"];
+                } & {
+                    readonly optional: true;
+                };
+                readonly force: {
+                    readonly kind: "boolean";
+                    readonly description: string;
+                } & {
+                    readonly optional: true;
+                };
+                readonly custom_output: {
+                    readonly kind: "boolean";
+                    readonly description: string;
+                } & {
+                    readonly optional: true;
+                };
+                readonly endpoint_count_bucket: {
+                    readonly kind: "enum";
+                    readonly description: string;
+                    readonly values: readonly ["0", "1", "2-5", "6-20", "21-100", "101+"];
+                } & {
+                    readonly optional: true;
+                };
+            };
             readonly 'generate:manifest': {
                 readonly query_count_bucket: {
                     readonly kind: "enum";
@@ -993,6 +1087,14 @@ export declare const EVENT_CATALOG: {
                     readonly kind: "enum";
                     readonly description: string;
                     readonly values: readonly ["hypequery.ts", "api.ts", "queries.ts", "explicit_file", "unknown"];
+                } & {
+                    readonly optional: true;
+                };
+                readonly http_backend: {
+                    readonly kind: "boolean";
+                    readonly description: string;
+                } & {
+                    readonly optional: true;
                 };
                 readonly mode: {
                     readonly kind: "enum";
@@ -1003,6 +1105,8 @@ export declare const EVENT_CATALOG: {
                     readonly kind: "enum";
                     readonly description: string;
                     readonly values: readonly ["0", "1", "2-5", "6-20", "21-100", "101+"];
+                } & {
+                    readonly optional: true;
                 };
                 readonly tenant_used: {
                     readonly kind: "boolean";
@@ -1012,6 +1116,8 @@ export declare const EVENT_CATALOG: {
                     readonly kind: "enum";
                     readonly description: string;
                     readonly values: readonly ["0", "1", "2-5", "6-20", "21-100", "101+"];
+                } & {
+                    readonly optional: true;
                 };
             };
         };
@@ -1083,7 +1189,7 @@ export declare const EVENT_CATALOG: {
             readonly command: {
                 readonly kind: "enum";
                 readonly description: string;
-                readonly values: readonly ["init", "dev", "mcp", "generate", "generate:types", "generate:datasets", "generate:manifest", "login", "logout", "deploy", "deployment:build", "deployment:validate", "deployment:release", "deployment:submit", "deployment:status", "pull", "diff", "help", "version", "telemetry", "unknown"];
+                readonly values: readonly ["init", "dev", "mcp", "generate", "generate:types", "generate:datasets", "generate:manifest", "generate:client", "login", "logout", "deploy", "deployment:build", "deployment:validate", "deployment:release", "deployment:submit", "deployment:status", "pull", "diff", "help", "version", "telemetry", "unknown"];
             };
             readonly exception_class: {
                 readonly kind: "enum";

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

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/catalog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/catalog.ts"],"names":[],"mappings":"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"}

package/dist/utils/telemetry/catalog.js

@@ -36,7 +36,7 @@ const generation = {
     unsupported_type_families: optional(enumList('Which built-in type families need mapping? Never full type expressions.', TYPE_FAMILIES)),
     custom_output: optional(output),
 };
-const INSTRUMENTED = ['init', 'dev', 'mcp', 'generate', 'generate:types', 'generate:datasets', 'generate:manifest', 'help'];
+const INSTRUMENTED = ['init', 'dev', 'mcp', 'generate', 'generate:types', 'generate:datasets', 'generate:manifest', 'generate:client', 'help'];
 /** Command-specific completion fields; absence means that stage was not reached. */
 export const COMMAND_PROPERTIES = {
     init: {
@@ -62,6 +62,7 @@ export const COMMAND_PROPERTIES = {
     mcp: {
         mode: optional(enumeration('Is MCP used for validation or serving?', ['self_test', 'serve'])),
         hosted: optional(boolean('Is MCP self-test targeting a hosted endpoint?')),
+        http_backend: optional(boolean('Is MCP using an authorized HTTP client contract? Never its URL or principal.')),
         dataset_count_bucket: optional(count('How many datasets are exposed to agents?')),
         tenant_used: optional(boolean('Is a trusted tenant supplied? Never its value.')),
         tenant_dataset_count_bucket: optional(count('How many datasets require tenant scope?')),
@@ -78,6 +79,13 @@ export const COMMAND_PROPERTIES = {
         datasets_generated_bucket: optional(count('How many dataset definitions are generated?')),
         warning_counts: optional(record('Which tenant-scaffolding warnings need improvement?', fieldsFor(WARNING_CODES, optional(count('Bucketed warning occurrences.'))))),
     },
+    'generate:client': {
+        mode: optional(enumeration('Are client types generated or checked in CI?', ['write', 'check'])),
+        check_result: optional(enumeration('Does CI find stale client types?', ['up_to_date', 'out_of_date', 'missing'])),
+        force: optional(boolean('Are generated client types replaced?')),
+        custom_output: optional(output),
+        endpoint_count_bucket: optional(count('How many public endpoints need client types?')),
+    },
     'generate:manifest': {
         query_count_bucket: optional(count('How much query-based React integration is adopted?')),
         endpoint_count_bucket: optional(count('How much endpoint-based React integration is adopted?')),
@@ -99,11 +107,12 @@ export const SESSION_START_PROPERTIES = {
         quiet: boolean('Is quiet startup adopted?'),
     },
     mcp: {
-        entry_type: entry,
+        entry_type: optional(entry),
+        http_backend: optional(boolean('Is MCP using an authorized HTTP client contract? Never its URL or principal.')),
         mode: enumeration('Is MCP serving or validating?', ['self_test', 'serve']),
-        dataset_count_bucket: count('How many datasets are exposed to agents?'),
+        dataset_count_bucket: optional(count('How many local datasets are exposed to agents? Omit for HTTP contracts.')),
         tenant_used: boolean('Is tenant scope supplied? Never its value.'),
-        tenant_dataset_count_bucket: count('How many exposed datasets require tenant scope?'),
+        tenant_dataset_count_bucket: optional(count('How many local datasets require tenant scope? Omit for HTTP contracts.')),
     },
 };
 export const SESSION_END_PROPERTIES = {

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

@@ -4,17 +4,18 @@ export declare const DURATION_BUCKETS: readonly ["<100ms", "100ms-1s", "1s-10s",
 export declare const ERROR_CODES: readonly ["unknown", "connection_failed", "auth_failed", "entrypoint_not_found", "compile_error", "prompt_cancelled", "validation_failed", "cloud_network_error", "cloud_rejected", "not_installed", "engine_error", "no_tables", "no_datasets", "tenant_required", "load_error", "output_missing", "output_out_of_date", "unknown_command", "unknown_option"];
 export declare const OUTCOMES: readonly ["success", "failure", "cancelled", "interrupted"];
 export declare const DATABASES: readonly ["clickhouse", "chdb", "bigquery", "unknown"];
-export declare const COMMANDS: readonly ["init", "dev", "mcp", "generate", "generate:types", "generate:datasets", "generate:manifest", "login", "logout", "deploy", "deployment:build", "deployment:validate", "deployment:release", "deployment:submit", "deployment:status", "pull", "diff", "help", "version", "telemetry", "unknown"];
+export declare const COMMANDS: readonly ["init", "dev", "mcp", "generate", "generate:types", "generate:datasets", "generate:manifest", "generate:client", "login", "logout", "deploy", "deployment:build", "deployment:validate", "deployment:release", "deployment:submit", "deployment:status", "pull", "diff", "help", "version", "telemetry", "unknown"];
 export type TelemetryCommand = typeof COMMANDS[number];
 /** Canonical long names, including negated flags. Values and aliases never leave the CLI. */
 export declare const COMMAND_FLAGS: {
     readonly init: readonly ["--path", "--style", "--database", "--chdb-path", "--auth", "--all-tables", "--tables", "--exclude-tables", "--no-example", "--no-interactive", "--force", "--skip-connection"];
     readonly dev: readonly ["--port", "--hostname", "--no-watch", "--no-cache", "--cache", "--redis-url", "--open", "--cors", "--path", "--quiet"];
-    readonly mcp: readonly ["--path", "--tenant", "--self-test", "--url"];
+    readonly mcp: readonly ["--path", "--tenant", "--self-test", "--url", "--client-contract-url"];
     readonly generate: readonly ["--output", "--path", "--tables", "--database", "--chdb-path"];
     readonly 'generate:types': readonly ["--output", "--path", "--tables", "--database", "--chdb-path"];
     readonly 'generate:datasets': readonly ["--output", "--path", "--tables", "--exclude-tables", "--tenant-column", "--force", "--check", "--diff"];
     readonly 'generate:manifest': readonly ["--output"];
+    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"];
@@ -35,11 +36,12 @@ export declare const GLOBAL_FLAGS: readonly ["--no-telemetry", "--help", "--vers
 export declare const VALUE_FLAGS: {
     readonly init: readonly ["--path", "--style", "--database", "--chdb-path", "--auth", "--tables", "--exclude-tables"];
     readonly dev: readonly ["--port", "--hostname", "--cache", "--redis-url", "--path"];
-    readonly mcp: readonly ["--path", "--tenant", "--url"];
+    readonly mcp: readonly ["--path", "--tenant", "--url", "--client-contract-url"];
     readonly generate: readonly ["--output", "--path", "--tables", "--database", "--chdb-path"];
     readonly 'generate:types': readonly ["--output", "--path", "--tables", "--database", "--chdb-path"];
     readonly 'generate:datasets': readonly ["--output", "--path", "--tables", "--exclude-tables", "--tenant-column"];
     readonly 'generate:manifest': readonly ["--output"];
+    readonly 'generate:client': readonly ["--output"];
     readonly login: readonly ["--cloud-url", "--environment"];
     readonly logout: readonly [];
     readonly deploy: readonly ["--bundle-output", "--release-output", "--project", "--environment", "--endpoint"];

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

@@ -1 +1 @@
-{"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/domains.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,eAAO,MAAM,aAAa,sDAAuD,CAAC;AAClF,eAAO,MAAM,gBAAgB,gFAAiF,CAAC;AAC/G,eAAO,MAAM,WAAW,gWAKd,CAAC;AACX,eAAO,MAAM,QAAQ,6DAA8D,CAAC;AACpF,eAAO,MAAM,SAAS,wDAAyD,CAAC;AAChF,eAAO,MAAM,QAAQ,4SAKX,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;AAEvD,6FAA6F;AAC7F,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;CAmBsC,CAAC;AACjE,eAAO,MAAM,YAAY,oDAAqD,CAAC;AAC/E,yFAAyF;AACzF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;CAmBoE,CAAC;AAC7F,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;AACzG,eAAO,MAAM,WAAW;;;;;;CAAwG,CAAC;AACjI,eAAO,MAAM,kBAAkB,0NAA2N,CAAC;AAC3P,eAAO,MAAM,aAAa,4DAA6D,CAAC;AACxF,eAAO,MAAM,aAAa,4NAA6N,CAAC"}
+{"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/domains.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,eAAO,MAAM,aAAa,sDAAuD,CAAC;AAClF,eAAO,MAAM,gBAAgB,gFAAiF,CAAC;AAC/G,eAAO,MAAM,WAAW,gWAKd,CAAC;AACX,eAAO,MAAM,QAAQ,6DAA8D,CAAC;AACpF,eAAO,MAAM,SAAS,wDAAyD,CAAC;AAChF,eAAO,MAAM,QAAQ,+TAKX,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;AAEvD,6FAA6F;AAC7F,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;CAoBsC,CAAC;AACjE,eAAO,MAAM,YAAY,oDAAqD,CAAC;AAC/E,yFAAyF;AACzF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;CAoBoE,CAAC;AAC7F,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;AACzG,eAAO,MAAM,WAAW;;;;;;CAAwG,CAAC;AACjI,eAAO,MAAM,kBAAkB,0NAA2N,CAAC;AAC3P,eAAO,MAAM,aAAa,4DAA6D,CAAC;AACxF,eAAO,MAAM,aAAa,4NAA6N,CAAC"}

package/dist/utils/telemetry/domains.js

@@ -11,7 +11,7 @@ export const OUTCOMES = ['success', 'failure', 'cancelled', 'interrupted'];
 export const DATABASES = ['clickhouse', 'chdb', 'bigquery', 'unknown'];
 export const COMMANDS = [
     'init', 'dev', 'mcp', 'generate', 'generate:types', 'generate:datasets',
-    'generate:manifest', 'login', 'logout', 'deploy', 'deployment:build',
+    'generate:manifest', 'generate:client', 'login', 'logout', 'deploy', 'deployment:build',
     'deployment:validate', 'deployment:release', 'deployment:submit', 'deployment:status',
     'pull', 'diff', 'help', 'version', 'telemetry', 'unknown',
 ];
@@ -19,11 +19,12 @@ export const COMMANDS = [
 export const COMMAND_FLAGS = {
     init: ['--path', '--style', '--database', '--chdb-path', '--auth', '--all-tables', '--tables', '--exclude-tables', '--no-example', '--no-interactive', '--force', '--skip-connection'],
     dev: ['--port', '--hostname', '--no-watch', '--no-cache', '--cache', '--redis-url', '--open', '--cors', '--path', '--quiet'],
-    mcp: ['--path', '--tenant', '--self-test', '--url'],
+    mcp: ['--path', '--tenant', '--self-test', '--url', '--client-contract-url'],
     generate: ['--output', '--path', '--tables', '--database', '--chdb-path'],
     'generate:types': ['--output', '--path', '--tables', '--database', '--chdb-path'],
     'generate:datasets': ['--output', '--path', '--tables', '--exclude-tables', '--tenant-column', '--force', '--check', '--diff'],
     'generate:manifest': ['--output'],
+    'generate:client': ['--output', '--check', '--force'],
     login: ['--cloud-url', '--environment'],
     logout: [],
     deploy: ['--bundle-output', '--release-output', '--project', '--environment', '--no-source', '--endpoint', '--replace-restored', '--mcp-config'],
@@ -41,11 +42,12 @@ export const GLOBAL_FLAGS = ['--no-telemetry', '--help', '--version'];
 export const VALUE_FLAGS = {
     init: ['--path', '--style', '--database', '--chdb-path', '--auth', '--tables', '--exclude-tables'],
     dev: ['--port', '--hostname', '--cache', '--redis-url', '--path'],
-    mcp: ['--path', '--tenant', '--url'],
+    mcp: ['--path', '--tenant', '--url', '--client-contract-url'],
     generate: ['--output', '--path', '--tables', '--database', '--chdb-path'],
     'generate:types': ['--output', '--path', '--tables', '--database', '--chdb-path'],
     'generate:datasets': ['--output', '--path', '--tables', '--exclude-tables', '--tenant-column'],
     'generate:manifest': ['--output'],
+    'generate:client': ['--output'],
     login: ['--cloud-url', '--environment'],
     logout: [],
     deploy: ['--bundle-output', '--release-output', '--project', '--environment', '--endpoint'],

package/dist/utils/telemetry/mcp-session.js

@@ -11,8 +11,8 @@ export class McpSession {
     }
     instrument(executor) {
         return {
-            listTools: () => executor.listTools(), listPrompts: () => executor.listPrompts(),
-            getPrompt: (name, args) => executor.getPrompt(name, args), getManifestHash: () => executor.getManifestHash(),
+            listTools: signal => executor.listTools(signal), listPrompts: signal => executor.listPrompts(signal),
+            getPrompt: (name, args, signal) => executor.getPrompt(name, args, signal), getManifestHash: () => executor.getManifestHash(),
             callTool: async (name, args, signal) => {
                 if (Object.hasOwn(toolKinds, name))
                     this.calls[toolKinds[name]]++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/cli",
-  "version": "1.24.1",
+  "version": "1.25.0",
   "description": "CLI for scaffolding type-safe ClickHouse analytics, semantic datasets, React manifests, and deployments",
   "keywords": [
     "clickhouse",
@@ -22,19 +22,19 @@
     "dist"
   ],
   "dependencies": {
-    "@clickhouse/client": "^1.24.0",
+    "@clickhouse/client": "^1.24.1",
     "chalk": "^5.3.0",
-    "commander": "^12.0.0",
-    "dotenv": "^16.4.7",
+    "commander": "^15.0.0",
+    "dotenv": "^18.0.8",
     "esbuild": "^0.28.2",
-    "open": "^10.0.0",
+    "open": "^11.0.4",
     "ora": "^8.0.1",
     "prompts": "^2.4.2",
-    "@hypequery/deployment": "0.9.6",
-    "@hypequery/protocol": "0.20.0"
+    "@hypequery/deployment": "0.10.0",
+    "@hypequery/protocol": "0.21.0"
   },
   "optionalDependencies": {
-    "@napi-rs/keyring": "1.3.0"
+    "@napi-rs/keyring": "2.1.2"
   },
   "peerDependencies": {
     "@hypequery/mcp": "*",
@@ -43,16 +43,19 @@
   "peerDependenciesMeta": {
     "@hypequery/mcp": {
       "optional": true
+    },
+    "@hypequery/serve": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/node": "^20.11.30",
     "@types/prompts": "^2.4.9",
-    "@vitest/coverage-v8": "^5.0.2",
+    "@vitest/coverage-v8": "^5.0.5",
     "typescript": "^6.0.3",
-    "vitest": "^5.0.2",
-    "@hypequery/mcp": "0.9.0",
-    "@hypequery/serve": "0.21.0"
+    "vitest": "^5.0.5",
+    "@hypequery/mcp": "0.10.0",
+    "@hypequery/serve": "0.22.0"
   },
   "repository": {
     "type": "git",