@did-btcr2/cli 0.3.1 → 0.5.0

package/src/cli.ts

@@ -1,374 +1,87 @@
-import { Identifier } from '@did-btcr2/method';
 import { Command, CommanderError } from 'commander';
-import { readFile } from 'fs/promises';
-import Btcr2Command, {
-  CommandRequest,
-  CommandResult,
-  CreateCommandOptions,
-  NetworkOption,
-  ResolveCommandOptions,
-  UpdateCommandOptions,
-} from './command.js';
+import { DidBtcr2Api, createApi } from '@did-btcr2/api';
+import {
+  registerCreateCommand,
+  registerDeactivateCommand,
+  registerResolveCommand,
+  registerUpdateCommand,
+} from './commands/index.js';
 import { CLIError } from './error.js';
-
-const SUPPORTED_NETWORKS: NetworkOption[] = ['bitcoin', 'testnet3', 'testnet4', 'signet', 'mutinynet', 'regtest'];
+import { GlobalOptions } from './types.js';
+import { VERSION } from './version.js';
 
 /**
  * CLI tool for the did:btcr2 method.
- * @type {DidBtcr2Cli}
- * @class DidBtcr2Cli
  */
 export class DidBtcr2Cli {
   public readonly program: Command;
-
-  constructor() {
-    this.program = new Command('btcr2')
-      .version('btcr2 0.1.0', '-v, --version', 'Output the current version')
-      .description('CLI tool for the did:btcr2 method');
-
-    this.configureCommands();
-  }
+  private readonly api: DidBtcr2Api;
 
   /**
-   * Configures the CLI commands.
-   * @returns {void}
+   * Initializes the CLI with an optional pre-configured API instance.
+   * @param {DidBtcr2Api} api - Optional API instance. Defaults to an unconfigured instance.
    */
-  private configureCommands(): void {
-    // Create command
-    this.program
-      .command('create')
-      .description('Create an identifier and initial DID document')
-      .requiredOption('-t, --type <type>', 'Identifier type <k|x>', 'k')
-      .requiredOption(
-        '-n, --network <network>',
-        'Identifier bitcoin network <bitcoin|testnet3|testnet4|signet|mutinynet|regtest>'
-      )
-      .requiredOption(
-        '-b, --bytes <bytes>',
-        'The genesis bytes used to create a DID and DID document as a hex string. ' +
-        'If type=k, MUST be secp256k1 public key. ' +
-        'If type=x, MUST be SHA-256 hash of a genesis document'
-      )
-      .action(async (options: { type: string; network: string; bytes: string }) => {
-        const parsedOptions = this.parseCreateOptions(options);
-        const result = await this.invokeCommand({ options: parsedOptions, action: 'create', command: new Btcr2Command() });
-        this.printResult(result);
-      });
-
-    // Resolve command
-    this.program
-      .command('resolve')
-      .alias('read')
-      .description('Resolve the DID document of the identifier.')
-      .requiredOption('-i, --identifier <identifier>', 'did:btcr2 identifier')
-      .option('-r, --resolutionOptions <resolutionOptions>', 'JSON string containing resolution options')
-      .option('-p, --resolutionOptionsPath <resolutionOptionsPath>', 'Path to a JSON file containing resolution options')
-      .action(async (options: { identifier: string; resolutionOptions?: string; resolutionOptionsPath?: string }) => {
-        const parsedOptions = await this.parseResolveOptions(options);
-        const result = await this.invokeCommand({ options: parsedOptions, action: 'resolve', command: new Btcr2Command() });
-        this.printResult(result);
-      });
-
-    // Update command
-    this.program
-      .command('update')
-      .description('Update a did:btcr2 document.')
-      .requiredOption('-i, --identifier <identifier>', 'did:btcr2 identifier')
-      .requiredOption('-s, --sourceDocument <sourceDocument>', 'Source DID document as JSON string')
-      .requiredOption('-v, --sourceVersionId <sourceVersionId>', 'Source version ID as a number')
-      .requiredOption('-p, --patch <patch>', 'JSON Patch operations as a JSON string array')
-      .requiredOption('-m, --verificationMethodId <verificationMethodId>', 'Did document verification method ID as a string')
-      .requiredOption('-b, --beaconIds <beaconIds>', 'Beacon IDs as a JSON string array')
-      .action(async (options: {
-        sourceDocument: string;
-        sourceVersionId: number;
-        patches: string;
-        verificationMethodId: string;
-        beaconId: string;
-      }) => {
-        const parsedOptions = this.parseUpdateOptions(options);
-        const result = await this.invokeCommand({ options: parsedOptions, action: 'update', command: new Btcr2Command() });
-        this.printResult(result);
-      });
-
-    // Deactivate command
-    this.program
-      .command('deactivate')
-      .alias('delete')
-      .description('Deactivate the did:btcr2 identifier permanently.')
-      .action(async () => {
-        const result = await this.invokeCommand({ options: {}, action: 'deactivate', command: new Btcr2Command() });
-        this.printResult(result);
-      });
-  }
-
-  /**
-   * Invokes a command with the provided request.
-   * @param {object} request The command request
-   * @param {any} request.options The command options
-   * @param {CommandRequest['action']} request.action The command action
-   * @param {Btcr2Command} request.command The command instance
-   * @returns {Promise<CommandResult>} The command result
-   */
-  private async invokeCommand(request: {
-    options: any;
-    action: CommandRequest['action'];
-    command: Btcr2Command;
-  }): Promise<CommandResult> {
-    return await request.command.execute({ action: request.action, options: request.options } as CommandRequest);
+  constructor(api: DidBtcr2Api = createApi()) {
+    this.api = api;
+    this.program = new Command('btcr2')
+      .version(`btcr2 ${VERSION}`, '-v, --version', 'Output the current version')
+      .description('CLI tool for the did:btcr2 method')
+      .option('-o, --output <format>', 'Output format <json|text>', 'text')
+      .option('--verbose', 'Verbose output', false)
+      .option('--quiet', 'Suppress non-essential output', false);
+
+    const globals = (): GlobalOptions => this.program.opts() as GlobalOptions;
+
+    registerCreateCommand(this.program, this.api, globals);
+    registerResolveCommand(this.program, this.api, globals);
+    registerUpdateCommand(this.program, this.api, globals);
+    registerDeactivateCommand(this.program, this.api, globals);
   }
 
   /**
    * Runs the CLI with the provided argv or process.argv.
-   * @param {string[]} [argv] The argv array to use. Defaults to process.argv.
+   * @param {string[]} [argv] - Optional array of command-line arguments.
+   * @returns {Promise<void>} - Resolves when execution is complete.
    */
-  public async run(argv?: string[]) {
+  public async run(argv?: string[]): Promise<void> {
     try {
-      const normalized = this.normalizeArgv(argv ?? process.argv);
+      const normalized = normalizeArgv(argv ?? process.argv);
       await this.program.parseAsync(normalized, { from: 'node' });
       if (!this.program.args.length) this.program.outputHelp();
-    } catch (error: any) {
-      this.handleError(error);
-    }
-  }
-
-  /**
-   * Normalizes argv to ensure it has at least two elements.
-   * @param {string[]} argv The argv array to normalize
-   * @returns {string[]} Normalized argv array
-   */
-  private normalizeArgv(argv: string[]): string[] {
-    if (argv.length >= 2) return argv;
-    if (argv.length === 1) return ['node', argv[0]];
-    return ['node', 'btcr2'];
-  }
-
-  /**
-   * Handles errors thrown during CLI execution.
-   * @param {unknown} error The error to handle
-   * @returns {void}
-   */
-  private handleError(error: unknown): void {
-    if (error instanceof CommanderError && (error.code === 'commander.helpDisplayed' || error.code === 'commander.help')) {
-      return;
-    }
-    if (error instanceof CLIError) {
-      console.error(error.message);
-      process.exitCode ??= 1;
-      return;
-    }
-    console.error(error);
-    process.exitCode ??= 1;
-  }
-
-  /**
-   * Parses create command options and throws CLIError on invalid input.
-   * @param {object} options The create command options
-   * @param {string} options.type The identifier type
-   * @param {string} options.network The bitcoin network
-   * @param {string} options.bytes The genesis bytes as a hex string
-   * @returns {CreateCommandOptions} The parsed create command options
-   */
-  private parseCreateOptions(options: { type: string; network: string; bytes: string; }): CreateCommandOptions {
-    if (!['k', 'x'].includes(options.type)) {
-      throw new CLIError(
-        'Invalid type. Must be "k" or "x".',
-        'INVALID_ARGUMENT_ERROR',
-        options
-      );
-    }
-    if (!this.isNetworkValid(options.network)) {
-      throw new CLIError(
-        'Invalid network. Must be one of "bitcoin", "testnet3", "testnet4", "signet", "mutinynet", or "regtest".',
-        'INVALID_ARGUMENT_ERROR',
-        options
-      );
-    }
-    if (Buffer.from(options.bytes, 'hex').length === 0) {
-      throw new CLIError(
-        'Invalid bytes. Must be a non-empty hex string.',
-        'INVALID_ARGUMENT_ERROR',
-        options
-      );
-    }
-    return {
-      type    : options.type as CreateCommandOptions['type'],
-      network : options.network as NetworkOption,
-      bytes   : options.bytes,
-    };
-  }
-
-  /**
-   * Parses resolve command options and throws CLIError on invalid input.
-   * @param {object} options The resolve command options
-   * @param {string} options.identifier The did:btcr2 identifier
-   * @param {string} [options.resolutionOptions] JSON string of resolution options
-   * @param {string} [options.resolutionOptionsPath] Path to a JSON file of resolution options
-   * @returns {Promise<ResolveCommandOptions>} The parsed resolve command options
-   */
-  private async parseResolveOptions(options: {
-    identifier: string;
-    resolutionOptions?: string;
-    resolutionOptionsPath?: string;
-  }): Promise<ResolveCommandOptions> {
-    this.validateIdentifier(options.identifier, options);
-    const resolutionOptions = await this.parseResolutionOptions(options);
-    return {
-      identifier : options.identifier,
-      ...(resolutionOptions && { options: resolutionOptions }),
-    };
-  }
-
-  /**
-   * Parses update command options and throws CLIError on invalid input.
-   * @param {object} options The update command options
-   * @param {string} options.sourceDocument The source DID document as a JSON string
-   * @param {number} options.sourceVersionId The source version ID as a number
-   * @param {string} options.patches The JSON Patch operations as a JSON string array
-   * @param {string} options.verificationMethodId The DID document verification method ID as a string
-   * @param {string} options.beaconId The beacon IDs as a JSON string array
-   * @returns {UpdateCommandOptions} The parsed update command options
-   */
-  private parseUpdateOptions(options: {
-    sourceDocument: string;
-    sourceVersionId: number;
-    patches: string;
-    verificationMethodId: string;
-    beaconId: string;
-  }): UpdateCommandOptions {
-    const sourceDocument = this.parseJsonOption<UpdateCommandOptions['sourceDocument']>(
-      options.sourceDocument,
-      'Invalid options. Must be a valid JSON string.',
-      options
-    );
-    const patches = this.parseJsonOption<UpdateCommandOptions['patches']>(
-      options.patches,
-      'Invalid options. Must be a valid JSON string.',
-      options
-    );
-    const beaconId = this.parseJsonOption<UpdateCommandOptions['beaconId']>(
-      options.beaconId,
-      'Invalid options. Must be a valid JSON string.',
-      options
-    );
-
-    return {
-      sourceDocument,
-      sourceVersionId      : Number(options.sourceVersionId),
-      patches,
-      verificationMethodId : options.verificationMethodId,
-      beaconId,
-    } as UpdateCommandOptions;
-  }
-
-  /**
-   * Parses a JSON option and throws a CLIError on failure.
-   * @param {string} value JSON string to parse
-   * @param {string} errorMessage Error message to use on failure
-   * @param {Record<string, any>} data Additional data to include in the error
-   * @returns {T} Parsed JSON object
-   */
-  private parseJsonOption<T>(value: string, errorMessage: string, data: Record<string, any>): T {
-    try {
-      return JSON.parse(value) as T;
-    } catch {
-      throw new CLIError(
-        errorMessage,
-        'INVALID_ARGUMENT_ERROR',
-        data
-      );
-    }
-  }
-
-  /**
-   * Parses resolution options from JSON string or file path.
-   * @param {object} options The options containing resolution options
-   * @param {string} [options.resolutionOptions] JSON string of resolution options
-   * @param {string} [options.resolutionOptionsPath] Path to a JSON file of resolution options
-   * @returns {Promise<any>} The parsed resolution options
-   */
-  private async parseResolutionOptions(options: { resolutionOptions?: string; resolutionOptionsPath?: string; }): Promise<any> {
-    if (options.resolutionOptions) {
-      return this.parseJsonOption(options.resolutionOptions, 'Invalid options. Must be a valid JSON string.', options);
-    }
-    if (options.resolutionOptionsPath) {
-      try {
-        const data = await readFile(options.resolutionOptionsPath, 'utf-8');
-        return JSON.parse(data);
-      } catch {
-        throw new CLIError(
-          'Invalid options path. Must be a valid path to a JSON file.',
-          'INVALID_ARGUMENT_ERROR',
-          options
-        );
-      }
-    }
-    return undefined;
-  }
-
-  /**
-   * Validates the did:btcr2 identifier format.
-   * @param {string} identifier The identifier to validate
-   * @param {Record<string, any>} data Additional data to include in the error
-   * @returns {void}
-   */
-  private validateIdentifier(identifier: string, data: Record<string, any>): void {
-    try {
-      Identifier.decode(identifier);
-    } catch {
-      throw new CLIError(
-        'Invalid identifier. Must be a valid did:btcr2 identifier.',
-        'INVALID_ARGUMENT_ERROR',
-        data
-      );
+    } catch (error: unknown) {
+      handleError(error);
     }
   }
+}
 
-  /**
-   * Validates if the provided network is supported.
-   * @param {string} network The network to validate
-   * @returns {boolean} True if the network is valid
-   */
-  private isNetworkValid(network: string): network is NetworkOption {
-    return SUPPORTED_NETWORKS.includes(network as NetworkOption);
-  }
+/**
+ * Normalizes argv to ensure it has at least two elements.
+ * @param {string[]} argv - The original argv array.
+ * @returns {string[]} - The normalized argv array.
+ */
+function normalizeArgv(argv: string[]): string[] {
+  if (argv.length >= 2) return argv;
+  if (argv.length === 1) return ['node', argv[0]];
+  return ['node', 'btcr2'];
+}
 
-  /**
-   * Prints the command result to the console.
-   * @param {CommandResult} result The command result to print
-   * @returns {void}
-   */
-  private printResult(result: CommandResult): void {
-    switch (result.action) {
-      case 'create':
-        this.log(result.did);
-        break;
-      case 'resolve':
-      case 'read':
-        this.log(result.resolution);
-        break;
-      case 'update':
-        this.log(result.signed);
-        break;
-      case 'deactivate':
-      case 'delete':
-        this.log(result.message);
-        break;
-      default:
-        this.log(result);
-    }
+/**
+ * Handles errors thrown during CLI execution.
+ * @param {unknown} error - The error to handle.
+ * @returns {void}
+ */
+function handleError(error: unknown): void {
+  if (
+    error instanceof CommanderError &&
+    (error.code === 'commander.helpDisplayed' || error.code === 'commander.help')
+  ) {
+    return;
   }
-
-  /**
-   * Logs a payload to the console, formatting objects as JSON.
-   * @param {unknown} payload The payload to log
-   * @returns {void}
-   */
-  private log(payload: unknown): void {
-    if (typeof payload === 'string') {
-      console.log(payload);
-      return;
-    }
-    console.log(JSON.stringify(payload, null, 2));
+  if (error instanceof CLIError) {
+    console.error(error.message);
+    process.exitCode ??= 1;
+    return;
   }
+  console.error(error);
+  process.exitCode ??= 1;
 }

package/src/commands/create.ts

@@ -0,0 +1,87 @@
+import type { DidBtcr2Api } from '@did-btcr2/api';
+import { Command } from 'commander';
+import { CLIError } from '../error.js';
+import { formatResult } from '../output.js';
+import {
+  CreateCommandOptions,
+  GlobalOptions,
+  NetworkOption,
+  SUPPORTED_NETWORKS,
+} from '../types.js';
+
+/** Expected byte length per identifier type: compressed secp256k1 = 33, SHA-256 hash = 32. */
+const EXPECTED_BYTES: Record<'k' | 'x', { length: number; label: string }> = {
+  k : { length: 33, label: 'secp256k1 compressed public key (33 bytes)' },
+  x : { length: 32, label: 'SHA-256 hash (32 bytes)' },
+};
+
+export function registerCreateCommand(
+  program : Command,
+  api     : DidBtcr2Api,
+  globals : () => GlobalOptions,
+): void {
+  program
+    .command('create')
+    .description('Create an identifier and initial DID document')
+    .requiredOption('-t, --type <type>', 'Identifier type <k|x>', 'k')
+    .requiredOption(
+      '-n, --network <network>',
+      'Identifier bitcoin network <bitcoin|testnet3|testnet4|signet|mutinynet|regtest>'
+    )
+    .requiredOption(
+      '-b, --bytes <bytes>',
+      'Genesis bytes as a hex string. ' +
+      'If type=k, MUST be secp256k1 public key. ' +
+      'If type=x, MUST be SHA-256 hash of a genesis document'
+    )
+    .action(async (options: { type: string; network: string; bytes: string }) => {
+      const parsed = validateCreateOptions(options);
+      const type = parsed.type === 'k' ? 'deterministic' : 'external';
+      const genesisBytes = Buffer.from(parsed.bytes, 'hex');
+      const data = api.createDid(type, genesisBytes, { network: parsed.network });
+      const result = { action: 'create' as const, data };
+      console.log(formatResult(result, globals()));
+    });
+}
+
+function validateCreateOptions(
+  options: { type: string; network: string; bytes: string }
+): CreateCommandOptions {
+  if (!['k', 'x'].includes(options.type)) {
+    throw new CLIError(
+      'Invalid type. Must be "k" or "x".',
+      'INVALID_ARGUMENT_ERROR',
+      options
+    );
+  }
+  if (!SUPPORTED_NETWORKS.includes(options.network as NetworkOption)) {
+    throw new CLIError(
+      'Invalid network. Must be one of "bitcoin", "testnet3", "testnet4", "signet", "mutinynet", or "regtest".',
+      'INVALID_ARGUMENT_ERROR',
+      options
+    );
+  }
+
+  const buf = Buffer.from(options.bytes, 'hex');
+  if (buf.length === 0) {
+    throw new CLIError(
+      'Invalid bytes. Must be a non-empty hex string.',
+      'INVALID_ARGUMENT_ERROR',
+      options
+    );
+  }
+  const expected = EXPECTED_BYTES[options.type as 'k' | 'x'];
+  if (buf.length !== expected.length) {
+    throw new CLIError(
+      `Invalid bytes length for type="${options.type}": expected ${expected.label}, got ${buf.length} bytes.`,
+      'INVALID_ARGUMENT_ERROR',
+      options
+    );
+  }
+
+  return {
+    type    : options.type as 'k' | 'x',
+    network : options.network as NetworkOption,
+    bytes   : options.bytes,
+  };
+}

package/src/commands/deactivate.ts

@@ -0,0 +1,72 @@
+import type { DidBtcr2Api } from '@did-btcr2/api';
+import { Command } from 'commander';
+import { CLIError } from '../error.js';
+import { formatResult } from '../output.js';
+import { 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 }];
+
+export function registerDeactivateCommand(
+  program : Command,
+  api     : DidBtcr2Api,
+  globals : () => GlobalOptions,
+): void {
+  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'),
+    )
+    .action(async (options: {
+      sourceDocument       : unknown;
+      sourceVersionId      : string;
+      verificationMethodId : string;
+      beaconId             : unknown;
+    }) => {
+      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 data = await api.btcr2.update(parsed);
+      const result = { action: 'deactivate' as const, data };
+      console.log(formatResult(result, globals()));
+    });
+}
+
+/**
+ * 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/index.ts

@@ -0,0 +1,4 @@
+export { registerCreateCommand } from './create.js';
+export { registerResolveCommand } from './resolve.js';
+export { registerUpdateCommand } from './update.js';
+export { registerDeactivateCommand } from './deactivate.js';

package/src/commands/resolve.ts

@@ -0,0 +1,65 @@
+import type { DidBtcr2Api } from '@did-btcr2/api';
+import { Identifier } from '@did-btcr2/api';
+import { Command } from 'commander';
+import { readFile } from 'node:fs/promises';
+import { CLIError } from '../error.js';
+import { formatResult } from '../output.js';
+import { GlobalOptions, ResolveCommandOptions } from '../types.js';
+
+export function registerResolveCommand(
+  program : Command,
+  api     : DidBtcr2Api,
+  globals : () => GlobalOptions,
+): void {
+  program
+    .command('resolve')
+    .alias('read')
+    .description('Resolve the DID document of the identifier.')
+    .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')
+    .action(async (options: {
+      identifier: string;
+      resolutionOptions?: string;
+      resolutionOptionsPath?: string;
+    }) => {
+      const parsed = await validateResolveOptions(options);
+      const data = await api.resolveDid(parsed.identifier, parsed.options);
+      const result = { action: 'resolve' as const, data };
+      console.log(formatResult(result, globals()));
+    });
+}
+
+async function validateResolveOptions(options: {
+  identifier: string;
+  resolutionOptions?: string;
+  resolutionOptionsPath?: string;
+}): 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
+      );
+    }
+  }
+  return { identifier: options.identifier, options: resolutionOptions };
+}