@hypequery/cli 1.16.1 → 1.16.2

package/README.md

@@ -239,15 +239,44 @@ arguments, keeping them out of shell history. The submission endpoint must not
 contain credentials or a URL fragment, and must use HTTPS except for
 `127.0.0.1`/`localhost`, which is permitted for local development and warns that
 the token is sent in cleartext. The release identity is sent as the idempotency
-key, so an unchanged release can be submitted safely again.
-
-This command submits immutable deployment inputs. Activation, status changes,
-promotion, and rollback remain control-plane operations.
+key, so an unchanged release can be submitted safely again. An accepted release
+becomes live immediately. The CLI pins the upload to the current activation
+revision, so a concurrent deploy or restore returns a conflict. If the current
+release was restored, pass `--replace-restored` to confirm that a different
+release should replace it.
 
 Options:
 
 - `--release <path>`: required target-bound release JSON
 - `--endpoint <url>`: HTTPS submission endpoint; requires `HYPEQUERY_API_TOKEN`
+- `--replace-restored`: intentionally replace a restored live release
+
+### `hypequery pull`
+
+Downloads the exact multi-file TypeScript source snapshot stored with the live
+release. Pull requires an interactive Cloud credential with source-read access;
+run `hypequery login` again if the credential predates this capability.
+
+```bash
+npx hypequery pull
+```
+
+By default the snapshot is written to a new release-specific directory under
+`.hypequery/live/<environment>/`. Use `--output <directory>` to choose another
+new directory. Pull never overwrites an existing path.
+
+### `hypequery diff [source]`
+
+Compares the local TypeScript dependency graph with the live release snapshot
+and reports added (`A`), modified (`M`), and deleted (`D`) files. The deployed
+entrypoint is used when `source` is omitted.
+
+```bash
+npx hypequery diff analytics/api.ts
+```
+
+Both commands use the target selected by `hypequery login`. Advanced and CI
+usage can pass `--project`, `--environment`, and `--endpoint` explicitly.
 
 ## Non-interactive Setup
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0BpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AA+ND,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgCpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AA4PD,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/cli.js

@@ -9,6 +9,7 @@ import { generateManifestCommand } from './commands/generate-manifest.js';
 import { buildDeploymentCommand, prepareDeploymentReleaseCommand, validateDeploymentCommand, } from './commands/deployment.js';
 import { deployCommand, submitDeploymentCommand, } from './commands/deploy.js';
 import { loginCommand, logoutCommand, } from './commands/login.js';
+import { diffCommand, pullCommand, } from './commands/live-source.js';
 import { isPromptCancelled } from './utils/prompts.js';
 const program = new Command();
 function getCliVersion() {
@@ -44,6 +45,25 @@ program
     .action(runCommand(async () => {
     await logoutCommand();
 }));
+program
+    .command('pull')
+    .description('Download the source snapshot from the live deployment')
+    .option('-o, --output <directory>', 'New destination directory')
+    .option('--project <project>', 'Target project identifier (advanced override)')
+    .option('--environment <environment>', 'Target environment identifier (advanced override)')
+    .option('--endpoint <url>', 'HTTPS submission endpoint; requires HYPEQUERY_API_TOKEN')
+    .action(runCommand(async (options) => {
+    await pullCommand(options);
+}));
+program
+    .command('diff [source]')
+    .description('Compare local source with the live deployment')
+    .option('--project <project>', 'Target project identifier (advanced override)')
+    .option('--environment <environment>', 'Target environment identifier (advanced override)')
+    .option('--endpoint <url>', 'HTTPS submission endpoint; requires HYPEQUERY_API_TOKEN')
+    .action(runCommand(async (source, options) => {
+    await diffCommand(source, options);
+}));
 function runCommand(action) {
     return async (...args) => {
         try {
@@ -167,6 +187,7 @@ program
     .description('Submit a prebuilt deployment bundle and release')
     .requiredOption('--release <path>', 'Target-bound release JSON path')
     .option('--endpoint <url>', 'HTTPS submission endpoint; requires HYPEQUERY_API_TOKEN')
+    .option('--replace-restored', 'Intentionally replace a restored live release')
     .action(runCommand(async (bundle, options) => {
     await submitDeploymentCommand(bundle, options);
 }));
@@ -180,6 +201,7 @@ program
     .option('--release <path>', 'Submit a prebuilt bundle with this release (legacy)')
     .option('--no-source', 'Exclude project source files from the deployment bundle')
     .option('--endpoint <url>', 'HTTPS submission endpoint; requires HYPEQUERY_API_TOKEN')
+    .option('--replace-restored', 'Intentionally replace a restored live release')
     .action(runCommand(async (source, options) => {
     await deployCommand(source, options);
 }));

package/dist/commands/deploy.d.ts

@@ -1,9 +1,11 @@
 import { createHttpDeploymentUploadTransport, type DeploymentSubmissionResponse } from '../utils/deployment-upload.js';
 import { type StoredCloudCredential } from '../utils/cloud-credential-store.js';
+import { fetchLiveDeployment } from '../utils/live-deployment.js';
 import { buildDeploymentCommand, prepareDeploymentReleaseCommand } from './deployment.js';
 export interface SubmitDeploymentOptions {
     release?: string;
     endpoint?: string;
+    replaceRestored?: boolean;
 }
 export interface DeployOptions extends SubmitDeploymentOptions {
     project?: string;
@@ -16,6 +18,7 @@ export interface SubmitDeploymentDependencies {
     readonly env?: Readonly<Record<string, string | undefined>>;
     readonly createTransport?: typeof createHttpDeploymentUploadTransport;
     readonly loadCredential?: () => Promise<StoredCloudCredential | null>;
+    readonly fetchLive?: typeof fetchLiveDeployment;
 }
 export interface DeployDependencies extends SubmitDeploymentDependencies {
     readonly buildDeployment?: typeof buildDeploymentCommand;

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,EAEL,KAAK,qBAAqB,EAC3B,MAAM,oCAAoC,CAAC;AAC5C,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;CACnB;AAED,MAAM,WAAW,aAAc,SAAQ,uBAAuB;IAC5D,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;CAClB;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;CACvE;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;AA8GD,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,uBAA4B,EACrC,YAAY,GAAE,4BAAiC,GAC9C,OAAO,CAAC,4BAA4B,CAAC,CAwDvC;AAmDD,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,aAAkB,EAC3B,YAAY,GAAE,kBAAuB,GACpC,OAAO,CAAC,4BAA4B,CAAC,CAmDvC"}
+{"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,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;CAC3B;AAED,MAAM,WAAW,aAAc,SAAQ,uBAAuB;IAC5D,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;CAClB;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;CACjD;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,CA0EvC;AAmDD,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,aAAkB,EAC3B,YAAY,GAAE,kBAAuB,GACpC,OAAO,CAAC,4BAA4B,CAAC,CAqDvC"}

package/dist/commands/deploy.js

@@ -4,7 +4,8 @@ import { prepareProtocolDeploymentReleaseEnvelope, } from '@hypequery/protocol';
 import { DEPLOYMENT_BUNDLE_MANIFEST, verifyDeploymentBundle, } from '../utils/deployment-bundle.js';
 import { createHttpDeploymentUploadTransport, DeploymentUploadError, } from '../utils/deployment-upload.js';
 import { logger } from '../utils/logger.js';
-import { loadCloudCredential, } from '../utils/cloud-credential-store.js';
+import { resolveDeploymentCredential } from '../utils/cloud-deployment-access.js';
+import { fetchLiveDeployment } from '../utils/live-deployment.js';
 import { buildDeploymentCommand, prepareDeploymentReleaseCommand, } from './deployment.js';
 const MAX_RELEASE_FILE_BYTES = 16 * 1024;
 const DEFAULT_BUNDLE_PATH = 'analytics/hypequery-deployment';
@@ -64,39 +65,6 @@ function requiredConfiguration(value, message) {
         throw new Error(message);
     return value;
 }
-/**
- * Resolves the submission endpoint and token. Kept separate from
- * `submitDeploymentCommand` so `deployCommand` can run it as a preflight
- * before the bundle build.
- */
-async function resolveDeploymentCredential(endpointOption, dependencies) {
-    const env = dependencies.env ?? process.env;
-    let deploymentEndpoint = endpointOption ?? env.HYPEQUERY_DEPLOYMENT_ENDPOINT;
-    let token = env.HYPEQUERY_API_TOKEN;
-    const hasExplicitEndpoint = Boolean(deploymentEndpoint);
-    const hasExplicitToken = Boolean(token);
-    if (hasExplicitEndpoint !== hasExplicitToken) {
-        throw new Error(hasExplicitEndpoint
-            ? 'An explicit deployment endpoint requires HYPEQUERY_API_TOKEN.'
-            : 'HYPEQUERY_API_TOKEN requires --endpoint or HYPEQUERY_DEPLOYMENT_ENDPOINT.\n\n'
-                + 'If you meant to use `hypequery login`, unset HYPEQUERY_API_TOKEN — '
-                + 'the CLI also reads it from a project .env file.');
-    }
-    if (!hasExplicitEndpoint) {
-        const credential = await (dependencies.loadCredential ?? loadCloudCredential)();
-        if (credential) {
-            if (Date.parse(credential.expiresAt) <= Date.now()) {
-                throw new Error('The stored Cloud credential has expired. Run `hypequery login` again.');
-            }
-            deploymentEndpoint = credential.deploymentEndpoint;
-            token = credential.token;
-        }
-    }
-    return {
-        endpoint: requiredConfiguration(deploymentEndpoint, 'Missing deployment endpoint. Run `hypequery login`, pass --endpoint, or set HYPEQUERY_DEPLOYMENT_ENDPOINT.'),
-        token: requiredConfiguration(token, 'Missing deployment credential. Run `hypequery login` or set HYPEQUERY_API_TOKEN.'),
-    };
-}
 export async function submitDeploymentCommand(bundlePath, options = {}, dependencies = {}) {
     if (!bundlePath) {
         throw new Error('Missing deployment bundle path.\n\n'
@@ -125,10 +93,26 @@ 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)({
+        endpoint: deploymentEndpoint,
+        token,
+        target: release.release.target,
+        resource: 'state',
+    });
+    if (live?.active?.restored
+        && live.active.releaseIdentity !== release.identity
+        && !options.replaceRestored) {
+        throw new Error('The live deployment is a restored release. '
+            + 'Run the command again with --replace-restored to replace it intentionally.');
+    }
     const createTransport = dependencies.createTransport ?? createHttpDeploymentUploadTransport;
     const transportOptions = {
         endpoint: deploymentEndpoint,
         token,
+        ...(live
+            ? { expectedActivationRevision: live.active?.revision ?? null }
+            : {}),
+        ...(options.replaceRestored ? { replaceRestored: true } : {}),
     };
     const result = await createTransport(transportOptions).submit(bundle, release);
     logger.success(result.status === 'accepted'
@@ -190,6 +174,7 @@ export async function deployCommand(sourcePath, options = {}, dependencies = {})
         return submitDeploymentCommand(sourcePath, {
             release: options.release,
             endpoint: options.endpoint,
+            replaceRestored: options.replaceRestored,
         }, dependencies);
     }
     await rejectBundleDirectorySource(sourcePath);
@@ -220,5 +205,6 @@ export async function deployCommand(sourcePath, options = {}, dependencies = {})
     return submit(bundlePath, {
         release: releasePath,
         endpoint: options.endpoint,
+        replaceRestored: options.replaceRestored,
     }, dependencies);
 }

package/dist/commands/live-source.d.ts

@@ -0,0 +1,22 @@
+import { type CloudDeploymentAccessDependencies } from '../utils/cloud-deployment-access.js';
+import { captureDeploymentSourceSnapshot } from '../utils/deployment-source-snapshot.js';
+import { fetchLiveDeployment } from '../utils/live-deployment.js';
+export interface LiveSourceOptions {
+    readonly endpoint?: string;
+    readonly project?: string;
+    readonly environment?: string;
+}
+export interface PullOptions extends LiveSourceOptions {
+    readonly output?: string;
+}
+export interface LiveSourceDependencies extends CloudDeploymentAccessDependencies {
+    readonly fetchLive?: typeof fetchLiveDeployment;
+    readonly captureSource?: typeof captureDeploymentSourceSnapshot;
+}
+export type LiveSourceDifference = {
+    readonly status: 'A' | 'M' | 'D';
+    readonly path: string;
+};
+export declare function pullCommand(options?: PullOptions, dependencies?: LiveSourceDependencies): Promise<string>;
+export declare function diffCommand(sourcePath: string | undefined, options?: LiveSourceOptions, dependencies?: LiveSourceDependencies): Promise<readonly LiveSourceDifference[]>;
+//# sourceMappingURL=live-source.d.ts.map

package/dist/commands/live-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-source.d.ts","sourceRoot":"","sources":["../../src/commands/live-source.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,iCAAiC,EACvC,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,+BAA+B,EAAE,MAAM,wCAAwC,CAAC;AACzF,OAAO,EACL,mBAAmB,EAEpB,MAAM,6BAA6B,CAAC;AAGrC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,WAAY,SAAQ,iBAAiB;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAuB,SAAQ,iCAAiC;IAC/E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,mBAAmB,CAAC;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,+BAA+B,CAAC;CACjE;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAkEF,wBAAsB,WAAW,CAC/B,OAAO,GAAE,WAAgB,EACzB,YAAY,GAAE,sBAA2B,mBAuC1C;AAED,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,iBAAsB,EAC/B,YAAY,GAAE,sBAA2B,GACxC,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAAC,CA0B1C"}

package/dist/commands/live-source.js

@@ -0,0 +1,119 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { validateProtocolDeploymentReleaseTarget, } from '@hypequery/protocol';
+import { CLOUD_SOURCE_SCOPE, } from '../utils/cloud-credential-store.js';
+import { resolveDeploymentCredential, } from '../utils/cloud-deployment-access.js';
+import { captureDeploymentSourceSnapshot } from '../utils/deployment-source-snapshot.js';
+import { fetchLiveDeployment, } from '../utils/live-deployment.js';
+import { logger } from '../utils/logger.js';
+function targetFromOptions(options, credential) {
+    if ((options.project === undefined) !== (options.environment === undefined)) {
+        throw new Error('Pass both --project and --environment, or omit both.');
+    }
+    const input = options.project === undefined
+        ? credential?.target
+        : { project: options.project, environment: options.environment };
+    if (!input) {
+        throw new Error('Missing deployment target. Run `hypequery login` or pass both '
+            + '--project and --environment.');
+    }
+    try {
+        return validateProtocolDeploymentReleaseTarget(input);
+    }
+    catch {
+        throw new Error('The deployment target is invalid.');
+    }
+}
+async function liveSource(options, dependencies) {
+    const access = await resolveDeploymentCredential(options.endpoint, dependencies);
+    if (access.storedCredential
+        && access.storedCredential.scope !== CLOUD_SOURCE_SCOPE) {
+        throw new Error('The stored CLI credential cannot read deployed source. Run `hypequery login` again.');
+    }
+    const target = targetFromOptions(options, access.storedCredential);
+    const live = await (dependencies.fetchLive ?? fetchLiveDeployment)({
+        endpoint: access.endpoint,
+        token: access.token,
+        target,
+        resource: 'source',
+    });
+    if (!live?.active?.source) {
+        throw new Error('The live deployment does not include a source snapshot.');
+    }
+    return live;
+}
+function digest(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+async function exists(input) {
+    try {
+        await stat(input);
+        return true;
+    }
+    catch (error) {
+        if (typeof error === 'object' && error !== null && 'code' in error
+            && error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+export async function pullCommand(options = {}, dependencies = {}) {
+    const live = await liveSource(options, dependencies);
+    const active = live.active;
+    const source = active.source;
+    const destination = path.resolve(options.output
+        ?? path.join('.hypequery', 'live', live.target.environment, active.releaseIdentity.slice(0, 12)));
+    if (destination === path.parse(destination).root || await exists(destination)) {
+        throw new Error(`Refusing to overwrite an existing pull destination: ${destination}`);
+    }
+    const parent = path.dirname(destination);
+    await mkdir(parent, { recursive: true });
+    const staging = path.join(parent, `.${path.basename(destination)}.${randomUUID()}.tmp`);
+    await mkdir(staging, { mode: 0o700 });
+    try {
+        for (const file of source.files) {
+            const output = path.join(staging, ...file.path.split('/'));
+            await mkdir(path.dirname(output), { recursive: true });
+            await writeFile(output, file.bytes, { flag: 'wx' });
+        }
+        await rename(staging, destination);
+    }
+    catch (error) {
+        await rm(staging, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+    logger.success(`Live source pulled to ${destination}`);
+    logger.info(`Release identity: ${active.releaseIdentity}`);
+    logger.info(`Entrypoint: ${source.entrypoint}`);
+    return destination;
+}
+export async function diffCommand(sourcePath, options = {}, dependencies = {}) {
+    const live = await liveSource(options, dependencies);
+    const active = live.active;
+    const source = active.source;
+    const local = await (dependencies.captureSource ?? captureDeploymentSourceSnapshot)(sourcePath ?? source.entrypoint);
+    const liveFiles = new Map(source.files.map(file => [file.path, file.sha256]));
+    const localFiles = new Map(local.files.map(file => [file.path, digest(file.bytes)]));
+    const paths = [...new Set([...liveFiles.keys(), ...localFiles.keys()])].sort();
+    const differences = [];
+    for (const file of paths) {
+        const liveDigest = liveFiles.get(file);
+        const localDigest = localFiles.get(file);
+        if (liveDigest === undefined)
+            differences.push({ status: 'A', path: file });
+        else if (localDigest === undefined)
+            differences.push({ status: 'D', path: file });
+        else if (liveDigest !== localDigest)
+            differences.push({ status: 'M', path: file });
+    }
+    if (differences.length === 0) {
+        logger.success('Local source matches the live deployment');
+    }
+    else {
+        for (const difference of differences) {
+            logger.info(`${difference.status} ${difference.path}`);
+        }
+    }
+    return Object.freeze(differences);
+}

package/dist/commands/login.js

@@ -2,7 +2,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { createServer } from 'node:http';
 import open from 'open';
 import { validateProtocolDeploymentReleaseTarget } from '@hypequery/protocol';
-import { CLOUD_DEPLOYMENT_SCOPE, deleteCloudCredential, loadCloudCredential, normalizeCloudDeploymentEndpoint, normalizeCloudOrigin, saveCloudCredential, } from '../utils/cloud-credential-store.js';
+import { CLOUD_SOURCE_SCOPE, deleteCloudCredential, loadCloudCredential, normalizeCloudDeploymentEndpoint, normalizeCloudOrigin, saveCloudCredential, } from '../utils/cloud-credential-store.js';
 import { logger } from '../utils/logger.js';
 const DEFAULT_CLOUD_URL = 'https://cloud.hypequery.com';
 const LOGIN_TIMEOUT_MS = 5 * 60_000;
@@ -131,7 +131,7 @@ function tokenResponse(input, origin, now) {
         || value.token_type !== 'Bearer'
         || typeof value.expires_at !== 'string'
         || !Number.isFinite(Date.parse(value.expires_at))
-        || value.scope !== CLOUD_DEPLOYMENT_SCOPE
+        || value.scope !== CLOUD_SOURCE_SCOPE
         || typeof value.deployment_endpoint !== 'string'
         || value.deployment_target === undefined) {
         throw new Error('Cloud returned an invalid CLI token response.');

package/dist/utils/cloud-credential-store.d.ts

@@ -1,5 +1,6 @@
 import { type ProtocolDeploymentReleaseTarget } from '@hypequery/protocol';
 export declare const CLOUD_DEPLOYMENT_SCOPE = "deploy:submit";
+export declare const CLOUD_SOURCE_SCOPE = "deploy:submit deploy:read-source";
 export interface StoredCloudCredential {
     readonly cloudUrl: string;
     readonly deploymentEndpoint: string;

package/dist/utils/cloud-credential-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloud-credential-store.d.ts","sourceRoot":"","sources":["../../src/utils/cloud-credential-store.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,qBAAqB,CAAC;AAI7B,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AAGtD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,+BAA+B,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAYD,UAAU,YAAY;IACpB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,WAAW,IAAI,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtD,cAAc,IAAI,OAAO,CAAC;CAC3B;AAQD,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CACrC;AAyCD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAc1D;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,MAAM,CAmBR;AAmFD,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,qBAAqB,EACjC,YAAY,GAAE,gCAAqC,iBAiEpD;AAED,wBAAsB,mBAAmB,CACvC,YAAY,GAAE,gCAAqC,GAClD,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAsBvC;AA0BD,wBAAsB,qBAAqB,CACzC,YAAY,GAAE,gCAAqC,iBA0BpD"}
+{"version":3,"file":"cloud-credential-store.d.ts","sourceRoot":"","sources":["../../src/utils/cloud-credential-store.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,qBAAqB,CAAC;AAI7B,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AACtD,eAAO,MAAM,kBAAkB,qCAAqC,CAAC;AAGrE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,+BAA+B,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAYD,UAAU,YAAY;IACpB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,WAAW,IAAI,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtD,cAAc,IAAI,OAAO,CAAC;CAC3B;AAQD,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CACrC;AAyCD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAc1D;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,MAAM,CAmBR;AAmFD,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,qBAAqB,EACjC,YAAY,GAAE,gCAAqC,iBAkEpD;AAED,wBAAsB,mBAAmB,CACvC,YAAY,GAAE,gCAAqC,GAClD,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAsBvC;AA0BD,wBAAsB,qBAAqB,CACzC,YAAY,GAAE,gCAAqC,iBA0BpD"}

package/dist/utils/cloud-credential-store.js

@@ -6,6 +6,7 @@ import { validateProtocolDeploymentReleaseTarget, } from '@hypequery/protocol';
 const KEYCHAIN_SERVICE = 'dev.hypequery.cli';
 const PROFILE_FILE = 'cloud-profile.json';
 export const CLOUD_DEPLOYMENT_SCOPE = 'deploy:submit';
+export const CLOUD_SOURCE_SCOPE = 'deploy:submit deploy:read-source';
 const MAX_KEYCHAIN_ACCOUNT_LENGTH = 2048;
 function defaultConfigDirectory(env, platform) {
     if (env.HYPEQUERY_CONFIG_DIR)
@@ -97,7 +98,7 @@ function parseProfile(input) {
         deploymentEndpoint = normalizeCloudDeploymentEndpoint(value.deploymentEndpoint, cloudUrl);
         if (value.keychainAccount !== cloudUrl
             || !Number.isFinite(Date.parse(value.expiresAt))
-            || value.scope !== CLOUD_DEPLOYMENT_SCOPE) {
+            || (value.scope !== CLOUD_DEPLOYMENT_SCOPE && value.scope !== CLOUD_SOURCE_SCOPE)) {
             throw new Error('profile invariant mismatch');
         }
         target = value.target === undefined
@@ -164,7 +165,8 @@ export async function saveCloudCredential(credential, dependencies = {}) {
     const cloudUrl = normalizeCloudOrigin(credential.cloudUrl);
     const deploymentEndpoint = normalizeCloudDeploymentEndpoint(credential.deploymentEndpoint, cloudUrl);
     if (!Number.isFinite(Date.parse(credential.expiresAt))
-        || credential.scope !== CLOUD_DEPLOYMENT_SCOPE) {
+        || (credential.scope !== CLOUD_DEPLOYMENT_SCOPE
+            && credential.scope !== CLOUD_SOURCE_SCOPE)) {
         throw new Error('Cannot store an invalid Hypequery Cloud credential.');
     }
     const keychainAccount = cloudUrl;

package/dist/utils/cloud-deployment-access.d.ts

@@ -0,0 +1,12 @@
+import { type StoredCloudCredential } from './cloud-credential-store.js';
+export interface CloudDeploymentAccessDependencies {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly loadCredential?: () => Promise<StoredCloudCredential | null>;
+}
+export interface ResolvedDeploymentCredential {
+    readonly endpoint: string;
+    readonly token: string;
+    readonly storedCredential?: StoredCloudCredential;
+}
+export declare function resolveDeploymentCredential(endpointOption: string | undefined, dependencies: CloudDeploymentAccessDependencies): Promise<ResolvedDeploymentCredential>;
+//# sourceMappingURL=cloud-deployment-access.d.ts.map

package/dist/utils/cloud-deployment-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-deployment-access.d.ts","sourceRoot":"","sources":["../../src/utils/cloud-deployment-access.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,6BAA6B,CAAC;AAErC,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;CACnD;AAUD,wBAAsB,2BAA2B,CAC/C,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,YAAY,EAAE,iCAAiC,GAC9C,OAAO,CAAC,4BAA4B,CAAC,CAsCvC"}

package/dist/utils/cloud-deployment-access.js

@@ -0,0 +1,37 @@
+import { loadCloudCredential, } from './cloud-credential-store.js';
+function requiredConfiguration(value, message) {
+    if (value === undefined || value.length === 0)
+        throw new Error(message);
+    return value;
+}
+export async function resolveDeploymentCredential(endpointOption, dependencies) {
+    const env = dependencies.env ?? process.env;
+    let deploymentEndpoint = endpointOption ?? env.HYPEQUERY_DEPLOYMENT_ENDPOINT;
+    let token = env.HYPEQUERY_API_TOKEN;
+    let storedCredential;
+    const hasExplicitEndpoint = Boolean(deploymentEndpoint);
+    const hasExplicitToken = Boolean(token);
+    if (hasExplicitEndpoint !== hasExplicitToken) {
+        throw new Error(hasExplicitEndpoint
+            ? 'An explicit deployment endpoint requires HYPEQUERY_API_TOKEN.'
+            : 'HYPEQUERY_API_TOKEN requires --endpoint or HYPEQUERY_DEPLOYMENT_ENDPOINT.\n\n'
+                + 'If you meant to use `hypequery login`, unset HYPEQUERY_API_TOKEN — '
+                + 'the CLI also reads it from a project .env file.');
+    }
+    if (!hasExplicitEndpoint) {
+        const credential = await (dependencies.loadCredential ?? loadCloudCredential)();
+        if (credential) {
+            if (Date.parse(credential.expiresAt) <= Date.now()) {
+                throw new Error('The stored Cloud credential has expired. Run `hypequery login` again.');
+            }
+            deploymentEndpoint = credential.deploymentEndpoint;
+            token = credential.token;
+            storedCredential = credential;
+        }
+    }
+    return {
+        endpoint: requiredConfiguration(deploymentEndpoint, 'Missing deployment endpoint. Run `hypequery login`, pass --endpoint, or set HYPEQUERY_DEPLOYMENT_ENDPOINT.'),
+        token: requiredConfiguration(token, 'Missing deployment credential. Run `hypequery login` or set HYPEQUERY_API_TOKEN.'),
+        ...(storedCredential ? { storedCredential } : {}),
+    };
+}

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

@@ -27,6 +27,8 @@ export type DeploymentFetch = (input: string, init: DeploymentFetchInit) => Prom
 export interface HttpDeploymentUploadTransportOptions {
     readonly endpoint: string;
     readonly token: string;
+    readonly expectedActivationRevision?: string | null;
+    readonly replaceRestored?: boolean;
     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,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,CAsF3B"}
+{"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"}

package/dist/utils/deployment-upload.js

@@ -347,6 +347,14 @@ export function createHttpDeploymentUploadTransport(options) {
                         'Idempotency-Key': preparedRelease.identity,
                         'X-HypeQuery-Bundle-Identity': manifest.identity,
                         'X-HypeQuery-Release-Identity': preparedRelease.identity,
+                        ...(options.expectedActivationRevision !== undefined
+                            ? {
+                                'X-HypeQuery-Expected-Activation-Revision': options.expectedActivationRevision ?? 'none',
+                            }
+                            : {}),
+                        ...(options.replaceRestored
+                            ? { 'X-HypeQuery-Replace-Restored': 'true' }
+                            : {}),
                     },
                     body: multipartBody(boundary, parts),
                     duplex: 'half',

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

@@ -0,0 +1,36 @@
+import { type ProtocolDeploymentReleaseTarget } from '@hypequery/protocol';
+export type LiveDeploymentSourceFile = {
+    readonly path: string;
+    readonly sha256: string;
+    readonly bytes: Uint8Array;
+};
+export type LiveDeploymentSource = {
+    readonly entrypoint: string;
+    readonly files: readonly LiveDeploymentSourceFile[];
+    readonly revision?: {
+        readonly kind: 'git';
+        readonly commit: string;
+        readonly branch?: string;
+        readonly dirty: boolean;
+    };
+};
+export type LiveDeployment = {
+    readonly target: ProtocolDeploymentReleaseTarget;
+    readonly active: null | {
+        readonly revision: string;
+        readonly releaseIdentity: string;
+        readonly activatedAt: string;
+        readonly restored: boolean;
+        readonly hasSource: boolean;
+        readonly source?: LiveDeploymentSource;
+    };
+};
+export type LiveDeploymentFetch = typeof fetch;
+export declare function fetchLiveDeployment(input: {
+    readonly endpoint: string;
+    readonly token: string;
+    readonly target: ProtocolDeploymentReleaseTarget;
+    readonly resource: 'state' | 'source';
+    readonly fetch?: LiveDeploymentFetch;
+}): Promise<LiveDeployment | undefined>;
+//# sourceMappingURL=live-deployment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"live-deployment.d.ts","sourceRoot":"","sources":["../../src/utils/live-deployment.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,+BAA+B,EACrC,MAAM,qBAAqB,CAAC;AAO7B,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;QACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;KACzB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,MAAM,EAAE,+BAA+B,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG;QACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;QAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC;KACxC,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,OAAO,KAAK,CAAC;AA8K/C,wBAAsB,mBAAmB,CAAC,KAAK,EAAE;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,+BAA+B,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC;CACtC,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAuCtC"}

package/dist/utils/live-deployment.js

@@ -0,0 +1,205 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS, validateProtocolDeploymentReleaseTarget, } from '@hypequery/protocol';
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+const MAX_RESPONSE_BYTES = Math.ceil(DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxSourceBytes * 1.4) + 1_000_000;
+function liveUrl(endpoint, target, resource) {
+    const url = new URL(endpoint);
+    if (!/\/v1\/deployments\/submissions\/?$/.test(url.pathname)) {
+        return undefined;
+    }
+    const loopbackHttp = url.protocol === 'http:'
+        && (url.hostname === '127.0.0.1' || url.hostname === 'localhost');
+    if ((url.protocol !== 'https:' && !loopbackHttp)
+        || url.username
+        || url.password
+        || url.hash) {
+        throw new Error('The deployment endpoint cannot be used to read live state safely.');
+    }
+    url.pathname = `/v1/deployments/targets/${encodeURIComponent(target.project)}`
+        + `/${encodeURIComponent(target.environment)}/${resource}`;
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
+function safePath(input) {
+    return typeof input === 'string'
+        && input.length > 0
+        && input.length <= 1024
+        && input.split(path.sep).join('/') === input
+        && !path.isAbsolute(input)
+        && input.split('/').every(segment => segment && segment !== '.' && segment !== '..');
+}
+function decodeFile(input) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        throw new Error('Cloud returned an invalid live source snapshot.');
+    }
+    const value = input;
+    if (!safePath(value.path)
+        || typeof value.sha256 !== 'string'
+        || !SHA256_PATTERN.test(value.sha256)
+        || !Number.isSafeInteger(value.byteLength)
+        || value.byteLength < 0
+        || value.byteLength
+            > DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxSourceFileBytes
+        || typeof value.contentsBase64 !== 'string'
+        || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value.contentsBase64)) {
+        throw new Error('Cloud returned an invalid live source snapshot.');
+    }
+    const bytes = Buffer.from(value.contentsBase64, 'base64');
+    if (bytes.byteLength !== value.byteLength
+        || createHash('sha256').update(bytes).digest('hex') !== value.sha256) {
+        throw new Error('Cloud returned a corrupt live source snapshot.');
+    }
+    return Object.freeze({ path: value.path, sha256: value.sha256, bytes });
+}
+function parseSource(input) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        throw new Error('Cloud returned an invalid live source snapshot.');
+    }
+    const value = input;
+    if (!safePath(value.entrypoint) || !Array.isArray(value.files)
+        || value.files.length < 1
+        || value.files.length > DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxSourceFiles) {
+        throw new Error('Cloud returned an invalid live source snapshot.');
+    }
+    const files = value.files.map(decodeFile);
+    const paths = new Set();
+    let total = 0;
+    for (const file of files) {
+        const folded = file.path.toLowerCase();
+        if (paths.has(folded))
+            throw new Error('Cloud returned duplicate live source paths.');
+        paths.add(folded);
+        total += file.bytes.byteLength;
+    }
+    if (total > DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxSourceBytes
+        || !files.some(file => file.path === value.entrypoint)) {
+        throw new Error('Cloud returned an invalid live source snapshot.');
+    }
+    let revision;
+    if (value.revision !== undefined) {
+        if (typeof value.revision !== 'object' || value.revision === null
+            || Array.isArray(value.revision)) {
+            throw new Error('Cloud returned an invalid live source revision.');
+        }
+        const candidate = value.revision;
+        if (candidate.kind !== 'git'
+            || typeof candidate.commit !== 'string'
+            || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(candidate.commit)
+            || typeof candidate.dirty !== 'boolean'
+            || (candidate.branch !== undefined && typeof candidate.branch !== 'string')) {
+            throw new Error('Cloud returned an invalid live source revision.');
+        }
+        revision = {
+            kind: 'git',
+            commit: candidate.commit,
+            dirty: candidate.dirty,
+            ...(candidate.branch !== undefined ? { branch: candidate.branch } : {}),
+        };
+    }
+    return Object.freeze({
+        entrypoint: value.entrypoint,
+        files: Object.freeze(files),
+        ...(revision ? { revision: Object.freeze(revision) } : {}),
+    });
+}
+function parseResponse(input, expectedTarget) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        throw new Error('Cloud returned an invalid live deployment response.');
+    }
+    const value = input;
+    let target;
+    try {
+        target = validateProtocolDeploymentReleaseTarget(value.target);
+    }
+    catch {
+        throw new Error('Cloud returned an invalid live deployment target.');
+    }
+    if (value.kind !== 'hypequery-live-deployment' || value.version !== 1
+        || target.project !== expectedTarget.project
+        || target.environment !== expectedTarget.environment) {
+        throw new Error('Cloud returned a mismatched live deployment response.');
+    }
+    if (value.active === null)
+        return Object.freeze({ target, active: null });
+    if (typeof value.active !== 'object' || Array.isArray(value.active)) {
+        throw new Error('Cloud returned an invalid live deployment response.');
+    }
+    const active = value.active;
+    if (typeof active.revision !== 'string' || !SHA256_PATTERN.test(active.revision)
+        || typeof active.releaseIdentity !== 'string'
+        || !SHA256_PATTERN.test(active.releaseIdentity)
+        || typeof active.activatedAt !== 'string'
+        || !Number.isFinite(Date.parse(active.activatedAt))
+        || typeof active.restored !== 'boolean'
+        || typeof active.hasSource !== 'boolean'
+        || (active.source !== undefined && !active.hasSource)) {
+        throw new Error('Cloud returned an invalid live deployment response.');
+    }
+    return Object.freeze({
+        target,
+        active: Object.freeze({
+            revision: active.revision,
+            releaseIdentity: active.releaseIdentity,
+            activatedAt: active.activatedAt,
+            restored: active.restored,
+            hasSource: active.hasSource,
+            ...(active.source !== undefined ? { source: parseSource(active.source) } : {}),
+        }),
+    });
+}
+async function errorMessage(response) {
+    try {
+        const input = await response.json();
+        const code = typeof input.error?.code === 'string' ? `${input.error.code}: ` : '';
+        const message = typeof input.error?.message === 'string'
+            ? input.error.message
+            : response.statusText;
+        return `${code}${message}`;
+    }
+    catch {
+        return response.statusText;
+    }
+}
+export async function fetchLiveDeployment(input) {
+    if (input.token.length < 1 || input.token.length > 4096
+        || input.token.trim() !== input.token
+        || [...input.token].some(character => {
+            const code = character.charCodeAt(0);
+            return code < 0x21 || code > 0x7e;
+        })) {
+        throw new Error('The deployment credential contains invalid characters or length.');
+    }
+    const request = input.fetch ?? fetch;
+    const url = liveUrl(input.endpoint, input.target, input.resource);
+    if (!url)
+        return undefined;
+    const response = await request(url, {
+        method: 'GET',
+        headers: { Accept: 'application/json', Authorization: `Bearer ${input.token}` },
+        redirect: 'error',
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (input.resource === 'state' && response.status === 404)
+        return undefined;
+    if (!response.ok) {
+        throw new Error(`Could not read the live deployment (${response.status}): ${await errorMessage(response)}`);
+    }
+    const contentLength = Number(response.headers.get('content-length'));
+    if (Number.isFinite(contentLength) && contentLength > MAX_RESPONSE_BYTES) {
+        throw new Error('Cloud returned an oversized live deployment response.');
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (bytes.byteLength > MAX_RESPONSE_BYTES) {
+        throw new Error('Cloud returned an oversized live deployment response.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new Error('Cloud returned an invalid live deployment response.');
+    }
+    return parseResponse(parsed, input.target);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/cli",
-  "version": "1.16.1",
+  "version": "1.16.2",
   "description": "Command-line interface for hypequery",
   "license": "Apache-2.0",
   "type": "module",