@did-btcr2/cli 0.20.0 → 0.21.0

package/src/commands/deactivate.ts

@@ -1,156 +1,28 @@
-import type { PublishToCasMode } from '@did-btcr2/api';
-import { KeyManagerSigner } from '@did-btcr2/key-manager';
 import type { Command } from 'commander';
-import { assertKeystoreAllowedForNetwork, deriveNetwork, resolveBroadcastOptions, resolveSigningKeyRef, type ApiFactory } from '../config.js';
-import { CLIError } from '../error.js';
+import type { ApiFactory } from '../config.js';
 import { printWatchHint } from '../hints.js';
-import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
 import { formatResult } from '../output.js';
-import type { GlobalOptions, UpdateCommandOptions } from '../types.js';
-
-/** The JSON Patch that marks a DID document as permanently deactivated. */
-const DEACTIVATION_PATCH = [{ op: 'add' as const, path: '/deactivated', value: true }];
+import type { GlobalOptions } from '../types.js';
+import { prepareWrite, registerWriteOptions, type WriteFlags } from './write.js';
 
 export function registerDeactivateCommand(
   program : Command,
   factory : ApiFactory,
   globals : () => GlobalOptions,
 ): void {
-  program
+  const command = program
     .command('deactivate')
     .alias('delete')
     .description('Deactivate the did:btcr2 identifier permanently. This is irreversible.')
-    .requiredOption(
-      '-s, --source-document <json>',
-      'Current DID document as JSON string',
-      parseJsonArg('--source-document'),
-    )
-    .requiredOption(
-      '--source-version-id <number>',
-      'Current version ID of the DID document'
-    )
-    .requiredOption(
-      '-m, --verification-method-id <id>',
-      'DID document verification method ID used to sign the deactivation'
-    )
-    .requiredOption(
-      '-b, --beacon-id <json>',
-      'Beacon ID as a JSON string',
-      parseJsonArg('--beacon-id'),
-    )
-    .option(
-      '--publish-to-cas <mode>',
-      'Publish update artifacts to a writable CAS before broadcast: auto|always|never. '
-        + 'CAS publication is optional; the default distributes the returned artifacts via sidecar.',
-      parsePublishToCasMode,
-      'never',
-    )
-    .option(
-      '--fee-rate <satsPerVByte>',
-      'Fee rate in sats/vByte for the beacon transaction (default: 5). '
-        + 'Raise it under congestion so the transaction confirms.',
-    )
-    .option(
-      '--change-address <address>',
-      'Send transaction change to this address instead of the beacon address, '
-        + 'so a DID\'s announcements are not linked on-chain (ADR 044).',
-    )
-    .action(async (options: {
-      sourceDocument       : unknown;
-      sourceVersionId      : string;
-      verificationMethodId : string;
-      beaconId             : unknown;
-      publishToCas         : PublishToCasMode;
-      feeRate?             : string;
-      changeAddress?       : string;
-    }) => {
-      if (!/^\d+$/.test(options.sourceVersionId)) {
-        throw new CLIError(
-          '--source-version-id must be a non-negative integer.',
-          'INVALID_ARGUMENT_ERROR',
-          { value: options.sourceVersionId },
-        );
-      }
-      const parsed: UpdateCommandOptions = {
-        sourceDocument       : options.sourceDocument as UpdateCommandOptions['sourceDocument'],
-        patches              : DEACTIVATION_PATCH,
-        sourceVersionId      : Number(options.sourceVersionId),
-        verificationMethodId : options.verificationMethodId,
-        beaconId             : options.beaconId as UpdateCommandOptions['beaconId'],
-      };
-      const did = parsed.sourceDocument?.id;
-      if (!did) {
-        throw new CLIError(
-          'Source document must contain an "id" field.',
-          'INVALID_ARGUMENT_ERROR',
-          options
-        );
-      }
-      // Deactivation is an update that applies the deactivation patch. The core
-      // method has no separate deactivate path, so this routes through update.
-      const network = deriveNetwork(did);
-      // Refuse to sign a mainnet deactivation with an unencrypted dev keystore (ADR 080).
-      assertKeystoreAllowedForNetwork(network, globals());
-      const api = factory(network, globals());
-      const keyId = resolveKeyRef(api.kms.kms, resolveSigningKeyRef(globals()));
-      const signer = new KeyManagerSigner(api.kms.kms, keyId);
-      // Resolve fee-rate/change-address through the flag -> env -> profile chain
-      // into beacon broadcast options. Undefined when neither is set, so the
-      // SDK defaults (5 sat/vB, change back to the beacon address) still apply.
-      const broadcastOptions = resolveBroadcastOptions(network, globals(), {
-        feeRate       : options.feeRate,
-        changeAddress : options.changeAddress,
-      });
-      // CAS publication is optional and never required: every beacon update can
-      // be completed and shared via sidecar alone. It is opt-in and defaults to
-      // 'never'; pass --publish-to-cas auto|always to publish the signed update
-      // (and, for CAS beacons, the announcement) to a writable CAS configured
-      // via --cas-rpc-url. The returned artifacts (txid, announcement, proof)
-      // are always printed for sidecar distribution regardless.
-      const data = await api.btcr2.update({
-        sourceDocument       : parsed.sourceDocument,
-        patches              : parsed.patches,
-        sourceVersionId      : parsed.sourceVersionId,
-        verificationMethodId : parsed.verificationMethodId,
-        beaconId             : parsed.beaconId,
-        signer,
-        publishToCas         : options.publishToCas,
-        ...(broadcastOptions ? { broadcastOptions } : {}),
-      });
-      console.log(formatResult({ action: 'deactivate', data }, globals()));
-      printWatchHint(globals(), network, data.txid);
+    .requiredOption('-i, --identifier <identifier>', 'did:btcr2 identifier to deactivate');
+  registerWriteOptions(command)
+    .action(async (options: WriteFlags) => {
+      const g = globals();
+      const { network, api, params } = await prepareWrite(options, factory, g);
+      // The api supplies the deactivation patch (ADR 094) and refuses a
+      // document that is deactivated already (ADR 100).
+      const data = await api.deactivateDid(params);
+      console.log(formatResult({ action: 'deactivate', data }, g));
+      printWatchHint(g, network, data.txid);
     });
 }
-
-/**
- * Commander argParser for `--publish-to-cas`. Validates the value is one of the
- * three {@link PublishToCasMode} policies, erroring at parse time otherwise.
- */
-function parsePublishToCasMode(value: string): PublishToCasMode {
-  if (value !== 'auto' && value !== 'always' && value !== 'never') {
-    throw new CLIError(
-      '--publish-to-cas must be one of "auto", "always", or "never".',
-      'INVALID_ARGUMENT_ERROR',
-      { value },
-    );
-  }
-  return value;
-}
-
-/**
- * Returns a commander argParser that validates JSON.
- * Errors at parse time with a clear flag reference.
- */
-function parseJsonArg(flagName: string): (value: string) => unknown {
-  return (value: string): unknown => {
-    try {
-      return JSON.parse(value);
-    } catch {
-      throw new CLIError(
-        `Invalid JSON for ${flagName}. Must be a valid JSON string.`,
-        'INVALID_ARGUMENT_ERROR',
-        { flagName, value }
-      );
-    }
-  };
-}

package/src/commands/resolve.ts

@@ -1,9 +1,8 @@
-import { DEFAULT_MIN_CONF, Identifier } from '@did-btcr2/api';
+import { Identifier } from '@did-btcr2/api';
 import type { Command } from 'commander';
-import { readFile } from 'node:fs/promises';
 import { deriveNetwork, type ApiFactory } from '../config.js';
-import { CLIError } from '../error.js';
 import { formatResult } from '../output.js';
+import { MIN_CONF_HELP, parseMinConf, readResolutionOptions, type ResolutionOptionFlags } from '../resolution-options.js';
 import type { GlobalOptions, ResolveCommandOptions } from '../types.js';
 
 export function registerResolveCommand(
@@ -18,18 +17,8 @@ export function registerResolveCommand(
     .requiredOption('-i, --identifier <identifier>', 'did:btcr2 identifier')
     .option('-r, --resolution-options <json>', 'JSON string containing resolution options')
     .option('-p, --resolution-options-path <path>', 'Path to a JSON file containing resolution options')
-    .option(
-      '--min-conf <n>',
-      'Minimum block confirmations a beacon signal needs before resolution applies it '
-      + `(positive integer, default: ${DEFAULT_MIN_CONF}). Overrides minConf inside -r/-p`,
-      parseMinConf,
-    )
-    .action(async (options: {
-      identifier: string;
-      resolutionOptions?: string;
-      resolutionOptionsPath?: string;
-      minConf?: number;
-    }) => {
+    .option('--min-conf <n>', MIN_CONF_HELP, parseMinConf)
+    .action(async (options: { identifier: string } & ResolutionOptionFlags) => {
       const parsed = await validateResolveOptions(options);
       const network = deriveNetwork(parsed.identifier);
       const api = factory(network, globals());
@@ -39,56 +28,11 @@ export function registerResolveCommand(
     });
 }
 
-async function validateResolveOptions(options: {
-  identifier: string;
-  resolutionOptions?: string;
-  resolutionOptionsPath?: string;
-  minConf?: number;
-}): Promise<ResolveCommandOptions> {
+async function validateResolveOptions(
+  options: { identifier: string } & ResolutionOptionFlags,
+): Promise<ResolveCommandOptions> {
   // Validate identifier format early
   Identifier.decode(options.identifier);
-
-  let resolutionOptions = undefined;
-  if (options.resolutionOptions) {
-    try {
-      resolutionOptions = JSON.parse(options.resolutionOptions);
-    } catch {
-      throw new CLIError(
-        'Invalid resolution options. Must be a valid JSON string.',
-        'INVALID_ARGUMENT_ERROR',
-        options
-      );
-    }
-  } else if (options.resolutionOptionsPath) {
-    try {
-      const content = await readFile(options.resolutionOptionsPath, 'utf-8');
-      resolutionOptions = JSON.parse(content);
-    } catch {
-      throw new CLIError(
-        'Invalid resolution options path. Must be a valid path to a JSON file.',
-        'INVALID_ARGUMENT_ERROR',
-        options
-      );
-    }
-  }
-  // The flag wins over a minConf inside the JSON options.
-  if (options.minConf !== undefined) {
-    resolutionOptions = { ...(resolutionOptions ?? {}), minConf: options.minConf };
-  }
+  const resolutionOptions = await readResolutionOptions(options);
   return { identifier: options.identifier, options: resolutionOptions };
 }
-
-/**
- * Commander argParser for `--min-conf`. Accepts a positive integer (minimum 1),
- * the domain the specification gives `minConf`. Errors at parse time otherwise.
- */
-function parseMinConf(value: string): number {
-  if (!/^[1-9]\d*$/.test(value)) {
-    throw new CLIError(
-      '--min-conf must be a positive integer (minimum 1).',
-      'INVALID_ARGUMENT_ERROR',
-      { value },
-    );
-  }
-  return Number(value);
-}

package/src/commands/update.ts

@@ -1,156 +1,36 @@
-import type { PublishToCasMode } from '@did-btcr2/api';
-import { KeyManagerSigner } from '@did-btcr2/key-manager';
+import type { PatchOperation } from '@did-btcr2/common';
 import type { Command } from 'commander';
-import { assertKeystoreAllowedForNetwork, deriveNetwork, resolveBroadcastOptions, resolveSigningKeyRef, type ApiFactory } from '../config.js';
-import { CLIError } from '../error.js';
+import type { ApiFactory } from '../config.js';
 import { printWatchHint } from '../hints.js';
-import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
 import { formatResult } from '../output.js';
-import type { GlobalOptions, UpdateCommandOptions } from '../types.js';
+import type { GlobalOptions } from '../types.js';
+import { parseJsonArg, prepareWrite, registerWriteOptions, type WriteFlags } from './write.js';
 
 export function registerUpdateCommand(
   program : Command,
   factory : ApiFactory,
   globals : () => GlobalOptions,
 ): void {
-  program
+  const command = program
     .command('update')
     .description('Update a did:btcr2 document.')
-    .requiredOption(
-      '-s, --source-document <json>',
-      'Source DID document as JSON string',
-      parseJsonArg('--source-document'),
-    )
-    .requiredOption(
-      '--source-version-id <number>',
-      'Source version ID as a number'
-    )
+    .requiredOption('-i, --identifier <identifier>', 'did:btcr2 identifier to update')
     .requiredOption(
       '-p, --patches <json>',
       'JSON Patch operations as a JSON string array',
       parseJsonArg('--patches'),
-    )
-    .requiredOption(
-      '-m, --verification-method-id <id>',
-      'DID document verification method ID'
-    )
-    .requiredOption(
-      '-b, --beacon-id <json>',
-      'Beacon ID as a JSON string',
-      parseJsonArg('--beacon-id'),
-    )
-    .option(
-      '--publish-to-cas <mode>',
-      'Publish update artifacts to a writable CAS before broadcast: auto|always|never. '
-        + 'CAS publication is optional; the default distributes the returned artifacts via sidecar.',
-      parsePublishToCasMode,
-      'never',
-    )
-    .option(
-      '--fee-rate <satsPerVByte>',
-      'Fee rate in sats/vByte for the beacon transaction (default: 5). '
-        + 'Raise it under congestion so the transaction confirms.',
-    )
-    .option(
-      '--change-address <address>',
-      'Send transaction change to this address instead of the beacon address, '
-        + 'so a DID\'s announcements are not linked on-chain (ADR 044).',
-    )
-    .action(async (options: {
-      sourceDocument       : unknown;
-      sourceVersionId      : string;
-      patches              : unknown;
-      verificationMethodId : string;
-      beaconId             : unknown;
-      publishToCas         : PublishToCasMode;
-      feeRate?             : string;
-      changeAddress?       : string;
-    }) => {
-      if (!/^\d+$/.test(options.sourceVersionId)) {
-        throw new CLIError(
-          '--source-version-id must be a non-negative integer.',
-          'INVALID_ARGUMENT_ERROR',
-          { value: options.sourceVersionId },
-        );
-      }
-      const parsed: UpdateCommandOptions = {
-        sourceDocument       : options.sourceDocument as UpdateCommandOptions['sourceDocument'],
-        patches              : options.patches as UpdateCommandOptions['patches'],
-        sourceVersionId      : Number(options.sourceVersionId),
-        verificationMethodId : options.verificationMethodId,
-        beaconId             : options.beaconId as UpdateCommandOptions['beaconId'],
-      };
-      const did = parsed.sourceDocument?.id;
-      if (!did) {
-        throw new CLIError(
-          'Source document must contain an "id" field.',
-          'INVALID_ARGUMENT_ERROR',
-          options
-        );
-      }
-      const network = deriveNetwork(did);
-      // Refuse to sign a mainnet update with an unencrypted dev keystore (ADR 080).
-      assertKeystoreAllowedForNetwork(network, globals());
-      const api = factory(network, globals());
-      const keyId = resolveKeyRef(api.kms.kms, resolveSigningKeyRef(globals()));
-      const signer = new KeyManagerSigner(api.kms.kms, keyId);
-      // Resolve fee-rate/change-address through the flag -> env -> profile chain
-      // into beacon broadcast options. Undefined when neither is set, so the
-      // SDK defaults (5 sat/vB, change back to the beacon address) still apply.
-      const broadcastOptions = resolveBroadcastOptions(network, globals(), {
-        feeRate       : options.feeRate,
-        changeAddress : options.changeAddress,
-      });
-      // CAS publication is optional and never required: every beacon update can
-      // be completed and shared via sidecar alone. It is opt-in and defaults to
-      // 'never'; pass --publish-to-cas auto|always to publish the signed update
-      // (and, for CAS beacons, the announcement) to a writable CAS configured
-      // via --cas-rpc-url. The returned artifacts (txid, announcement, proof)
-      // are always printed for sidecar distribution regardless.
-      const data = await api.btcr2.update({
-        sourceDocument       : parsed.sourceDocument,
-        patches              : parsed.patches,
-        sourceVersionId      : parsed.sourceVersionId,
-        verificationMethodId : parsed.verificationMethodId,
-        beaconId             : parsed.beaconId,
-        signer,
-        publishToCas         : options.publishToCas,
-        ...(broadcastOptions ? { broadcastOptions } : {}),
-      });
-      console.log(formatResult({ action: 'update', data }, globals()));
-      printWatchHint(globals(), network, data.txid);
-    });
-}
-
-/**
- * Commander argParser for `--publish-to-cas`. Validates the value is one of the
- * three {@link PublishToCasMode} policies, erroring at parse time otherwise.
- */
-function parsePublishToCasMode(value: string): PublishToCasMode {
-  if (value !== 'auto' && value !== 'always' && value !== 'never') {
-    throw new CLIError(
-      '--publish-to-cas must be one of "auto", "always", or "never".',
-      'INVALID_ARGUMENT_ERROR',
-      { value },
     );
-  }
-  return value;
-}
-
-/**
- * Returns a commander argParser that validates JSON.
- * Errors at parse time with a clear flag reference.
- */
-function parseJsonArg(flagName: string): (value: string) => unknown {
-  return (value: string): unknown => {
-    try {
-      return JSON.parse(value);
-    } catch {
-      throw new CLIError(
-        `Invalid JSON for ${flagName}. Must be a valid JSON string.`,
-        'INVALID_ARGUMENT_ERROR',
-        { flagName, value }
-      );
-    }
-  };
+  registerWriteOptions(command)
+    .action(async (options: WriteFlags & { patches: unknown }) => {
+      const g = globals();
+      const { network, api, params } = await prepareWrite(options, factory, g);
+      // The api resolves the source document if the source pair is absent,
+      // derives an omitted verification method and beacon, and publishes to
+      // the CAS only under --publish-to-cas auto|always. The returned
+      // artifacts (txid, signed update, announcement, proof) are printed for
+      // sidecar distribution in every case.
+      const data = await api.updateDid({ ...params, patches: options.patches as PatchOperation[] });
+      console.log(formatResult({ action: 'update', data }, g));
+      printWatchHint(g, network, data.txid);
+    });
 }

package/src/commands/write.ts

@@ -0,0 +1,198 @@
+import type { Btcr2DidDocument, DidBtcr2Api, PublishToCasMode } from '@did-btcr2/api';
+import { KeyManagerSigner } from '@did-btcr2/key-manager';
+import type { Command } from 'commander';
+import {
+  assertKeystoreAllowedForNetwork,
+  deriveNetwork,
+  resolveBroadcastOptions,
+  resolveSigningKeyRef,
+  type ApiFactory,
+} from '../config.js';
+import { CLIError } from '../error.js';
+import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
+import { MIN_CONF_HELP, parseMinConf, readResolutionOptions, type ResolutionOptionFlags } from '../resolution-options.js';
+import type { GlobalOptions, NetworkOption, UpdateCommandOptions } from '../types.js';
+
+/** The parsed flags that `update` and `deactivate` share. */
+export type WriteFlags = ResolutionOptionFlags & {
+  identifier            : string;
+  sourceDocument?       : unknown;
+  sourceVersionId?      : number;
+  verificationMethodId? : string;
+  beaconId?             : string;
+  publishToCas          : PublishToCasMode;
+  feeRate?              : string;
+  changeAddress?        : string;
+};
+
+/**
+ * Registers the flags that `update` and `deactivate` share. Each command
+ * registers `-i/--identifier` (and `update` its `-p/--patches`) before it
+ * calls this function, so those flags lead the help output.
+ */
+export function registerWriteOptions(command: Command): Command {
+  return command
+    .option(
+      '-s, --source-document <json>',
+      'Source DID document as a JSON string. Requires --source-version-id. '
+        + 'Omit both to resolve the current document first',
+      parseJsonArg('--source-document'),
+    )
+    .option(
+      '--source-version-id <number>',
+      'Version ID of the source document, a non-negative integer. Requires --source-document',
+      parseSourceVersionId,
+    )
+    .option(
+      '-m, --verification-method-id <id>',
+      'Verification method that signs the update '
+        + '(default: the one method of the document that publishes the signing key)',
+    )
+    .option(
+      '-b, --beacon-id <id>',
+      'Beacon service that announces the update, as a DID URL '
+        + '(default: the only beacon of the document, else the one beacon with a spendable UTXO)',
+    )
+    .option(
+      '-r, --resolution-options <json>',
+      'Resolution options as a JSON string, for the resolution of the source document',
+    )
+    .option(
+      '--resolution-options-path <path>',
+      'Path to a JSON file with resolution options, for the resolution of the source document',
+    )
+    .option('--min-conf <n>', MIN_CONF_HELP, parseMinConf)
+    .option(
+      '--publish-to-cas <mode>',
+      'Publish update artifacts to a writable CAS before broadcast: auto|always|never. '
+        + 'CAS publication is optional; the default distributes the returned artifacts via sidecar.',
+      parsePublishToCasMode,
+      'never',
+    )
+    .option(
+      '--fee-rate <satsPerVByte>',
+      'Fee rate in sats/vByte for the beacon transaction (default: 5). '
+        + 'Raise it under congestion so the transaction confirms.',
+    )
+    .option(
+      '--change-address <address>',
+      'Send transaction change to this address instead of the beacon address, '
+        + 'so a DID\'s announcements are not linked on-chain (ADR 044).',
+    );
+}
+
+/**
+ * Validates the shared write flags, derives the network from the identifier,
+ * applies the mainnet keystore guard, builds the signer, and returns the
+ * parameters for `updateDid` and `deactivateDid`.
+ *
+ * The checks run in this order, before any key material is read:
+ * 1. The identifier decodes and names a supported network.
+ * 2. `--source-document` and `--source-version-id` come together or not at
+ *    all (ADR 101). The api refuses a half pair too; the cli names the flags.
+ * 3. The resolution flags come only without the source pair. The api ignores
+ *    `resolutionOptions` when the pair is supplied (ADR 098). A silent ignore
+ *    of `--min-conf` would mislead.
+ * 4. A mainnet write is refused with an unencrypted dev keystore (ADR 080).
+ */
+export async function prepareWrite(
+  options : WriteFlags,
+  factory : ApiFactory,
+  g       : GlobalOptions,
+): Promise<{ network: NetworkOption; api: DidBtcr2Api; params: UpdateCommandOptions }> {
+  const did = options.identifier;
+  const network = deriveNetwork(did);
+  const hasDocument = options.sourceDocument !== undefined;
+  const hasVersion = options.sourceVersionId !== undefined;
+  if (hasDocument !== hasVersion) {
+    throw new CLIError(
+      'Provide both --source-document and --source-version-id, or neither. '
+        + 'Omit both to resolve the current document first.',
+      'INVALID_ARGUMENT_ERROR',
+      { did },
+    );
+  }
+  const hasResolutionFlags = options.resolutionOptions !== undefined
+    || options.resolutionOptionsPath !== undefined
+    || options.minConf !== undefined;
+  if (hasDocument && hasResolutionFlags) {
+    throw new CLIError(
+      '--resolution-options, --resolution-options-path, and --min-conf apply only when '
+        + '--source-document and --source-version-id are omitted. A supplied source pair skips resolution.',
+      'INVALID_ARGUMENT_ERROR',
+      { did },
+    );
+  }
+  assertKeystoreAllowedForNetwork(network, g);
+  const resolutionOptions = await readResolutionOptions(options);
+  const api = factory(network, g);
+  const keyId = resolveKeyRef(api.kms.kms, resolveSigningKeyRef(g));
+  const signer = new KeyManagerSigner(api.kms.kms, keyId);
+  // Resolve fee-rate/change-address through the flag, env, and profile layers
+  // into beacon broadcast options. Undefined when no layer sets one, so the
+  // SDK defaults (5 sat/vB, change back to the beacon address) still apply.
+  const broadcastOptions = resolveBroadcastOptions(network, g, {
+    feeRate       : options.feeRate,
+    changeAddress : options.changeAddress,
+  });
+  return {
+    network,
+    api,
+    params : {
+      did,
+      signer,
+      sourceDocument       : options.sourceDocument as Btcr2DidDocument | undefined,
+      sourceVersionId      : options.sourceVersionId,
+      verificationMethodId : options.verificationMethodId,
+      beaconId             : options.beaconId,
+      resolutionOptions,
+      publishToCas         : options.publishToCas,
+      broadcastOptions,
+    },
+  };
+}
+
+/** Commander argParser for `--source-version-id`: digits only, a non-negative integer. */
+function parseSourceVersionId(value: string): number {
+  if (!/^\d+$/.test(value)) {
+    throw new CLIError(
+      '--source-version-id must be a non-negative integer.',
+      'INVALID_ARGUMENT_ERROR',
+      { value },
+    );
+  }
+  return Number(value);
+}
+
+/**
+ * Commander argParser for `--publish-to-cas`. Validates the value is one of the
+ * three {@link PublishToCasMode} policies, erroring at parse time otherwise.
+ */
+function parsePublishToCasMode(value: string): PublishToCasMode {
+  if (value !== 'auto' && value !== 'always' && value !== 'never') {
+    throw new CLIError(
+      '--publish-to-cas must be one of "auto", "always", or "never".',
+      'INVALID_ARGUMENT_ERROR',
+      { value },
+    );
+  }
+  return value;
+}
+
+/**
+ * Returns a commander argParser that validates JSON.
+ * Errors at parse time with a clear flag reference.
+ */
+export function parseJsonArg(flagName: string): (value: string) => unknown {
+  return (value: string): unknown => {
+    try {
+      return JSON.parse(value);
+    } catch {
+      throw new CLIError(
+        `Invalid JSON for ${flagName}. Must be a valid JSON string.`,
+        'INVALID_ARGUMENT_ERROR',
+        { flagName, value }
+      );
+    }
+  };
+}