@did-btcr2/cli 0.1.0 → 0.1.2

package/src/cli.ts

@@ -1,44 +1,41 @@
-import { DidMethodError } from '@did-btcr2/common';
 import { Identifier } from '@did-btcr2/method';
-import { Command } from 'commander';
+import { Command, CommanderError } from 'commander';
 import { readFile } from 'fs/promises';
-import Btcr2Command from './command.js';
+import Btcr2Command, {
+  CommandRequest,
+  CommandResult,
+  CreateCommandOptions,
+  NetworkOption,
+  ResolveCommandOptions,
+  UpdateCommandOptions,
+} from './command.js';
+import { CLIError } from './error.js';
 
-/**
- * Custom CLI Error class extending DidMethodError.
- */
-export class CLIError extends DidMethodError {
-  constructor(message: string, type: string = 'CLIError', data?: Record<string, any>) {
-    super(message, { type, name: type, data });
-  }
-}
+const SUPPORTED_NETWORKS: NetworkOption[] = ['bitcoin', 'testnet3', 'testnet4', 'signet', 'mutinynet', 'regtest'];
 
 /**
- * A class-based CLI using Commander.
- * - No forced process.exit().
- * - Configurable by calling `run(argv?)`.
+ * CLI tool for the did:btcr2 method.
+ * @type {DidBtcr2Cli}
+ * @class DidBtcr2Cli
  */
 export class DidBtcr2Cli {
-  private CLI: Command;
+  public readonly program: Command;
 
   constructor() {
-    // Create the main Commander program
-    this.CLI = new Command()
-      .name('btcr2')
+    this.program = new Command('btcr2')
       .version('btcr2 0.1.0', '-v, --version', 'Output the current version')
       .description('CLI tool for the did:btcr2 method');
 
-    // Configure top-level options and subcommands
     this.configureCommands();
   }
 
   /**
-   * Configure the CLI commands and options.
-   * @private
+   * Configures the CLI commands.
+   * @returns {void}
    */
   private configureCommands(): void {
-    /* CREATE */
-    this.CLI
+    // Create command
+    this.program
       .command('create')
       .description('Create an identifier and initial DID document')
       .requiredOption('-t, --type <type>', 'Identifier type <k|x>', 'k')
@@ -52,36 +49,14 @@ export class DidBtcr2Cli {
         '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, [key: string]: any }) => {
-          if(!['k','x'].includes(options.type)) {
-            throw new CLIError(
-              'Invalid type. Must be "k" or "x".',
-              'INVALID_ARGUMENT_ERROR',
-              options
-            );
-          }
-          if(!['bitcoin','testnet3','testnet4','signet','mutinynet','regtest'].includes(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
-            );
-          }
-          await this.invokeCommand({ options, action: 'create', command: new Btcr2Command() });
-        }
-      );
+      .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);
+      });
 
-    /* READ / RESOLVE */
-    this.CLI
+    // Resolve command
+    this.program
       .command('resolve')
       .alias('read')
       .description('Resolve the DID document of the identifier.')
@@ -89,43 +64,13 @@ export class DidBtcr2Cli {
       .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 }) => {
-        try {
-          Identifier.decode(options.identifier);
-        } catch {
-          throw new CLIError(
-            'Invalid identifier. Must be a valid did:btcr2 identifier.',
-            'INVALID_ARGUMENT_ERROR',
-            options
-          );
-        }
-        if(options.resolutionOptions) {
-          try {
-            options.resolutionOptions = JSON.parse(options.resolutionOptions);
-          } catch {
-            throw new CLIError(
-              'Invalid options. Must be a valid JSON string.',
-              'INVALID_ARGUMENT_ERROR',
-              options
-            );
-          }
-        }
-        if(options.resolutionOptionsPath) {
-          try {
-            const data = await readFile(options.resolutionOptionsPath, 'utf-8');
-            options.resolutionOptions = JSON.parse(data);
-          } catch {
-            throw new CLIError(
-              'Invalid options path. Must be a valid path to a JSON file.',
-              'INVALID_ARGUMENT_ERROR',
-              options
-            );
-          }
-        }
-        await this.invokeCommand({ options, action: 'resolve', command: new Btcr2Command() });
+        const parsedOptions = await this.parseResolveOptions(options);
+        const result = await this.invokeCommand({ options: parsedOptions, action: 'resolve', command: new Btcr2Command() });
+        this.printResult(result);
       });
 
-    /* UPDATE */
-    this.CLI
+    // Update command
+    this.program
       .command('update')
       .description('Update a did:btcr2 document.')
       .requiredOption('-i, --identifier <identifier>', 'did:btcr2 identifier')
@@ -136,103 +81,299 @@ export class DidBtcr2Cli {
       .requiredOption('-b, --beaconIds <beaconIds>', 'Beacon IDs as a JSON string array')
       .action(async (options: {
         identifier: string;
-        sourceDocument: string; // stringified DidDocument; e.g. '{ "@context": "...", "id": "did:btcr2:...", ... }'
+        sourceDocument: string;
         sourceVersionId: number;
-        patch: string; // stringified PatchOperation[]; e.g. '[{ "op": "add", "path": "/foo", "value": "bar" }]'
+        patch: string;
         verificationMethodId: string;
-        beaconIds: string // stringified string[]; e.g. '["beaconId1","beaconId2"]'
-       }) => {
-        // Validate identifier by decoding
-        try {
-          Identifier.decode(options.identifier);
-        } catch {
-          throw new CLIError(
-            'Invalid identifier. Must be a valid did:btcr2 identifier.',
-            'INVALID_ARGUMENT_ERROR',
-            options
-          );
-        }
-        // Validate source document JSON
-        if(options.sourceDocument) {
-          try {
-            options.sourceDocument = JSON.parse(options.sourceDocument);
-          } catch {
-            throw new CLIError(
-              'Invalid options. Must be a valid JSON string.',
-              'INVALID_ARGUMENT_ERROR',
-              options
-            );
-          }
-        }
-        // Validate patch JSON
-        if(options.patch) {
-          try {
-            options.patch = JSON.parse(options.patch);
-          } catch {
-            throw new CLIError(
-              'Invalid options. Must be a valid JSON string.',
-              'INVALID_ARGUMENT_ERROR',
-              options
-            );
-          }
-        }
-        // Validate beacon IDs JSON
-        if(options.beaconIds) {
-          try {
-            options.beaconIds = JSON.parse(options.beaconIds);
-          } catch {
-            throw new CLIError(
-              'Invalid options. Must be a valid JSON string.',
-              'INVALID_ARGUMENT_ERROR',
-              options
-            );
-          }
-        }
-        await this.invokeCommand({ options, action: 'update', command: new Btcr2Command() });
+        beaconIds: string;
+      }) => {
+        const parsedOptions = this.parseUpdateOptions(options);
+        const result = await this.invokeCommand({ options: parsedOptions, action: 'update', command: new Btcr2Command() });
+        this.printResult(result);
       });
 
-    /* DEACTIVATE / DELETE */
-    this.CLI
+    // Deactivate command
+    this.program
       .command('deactivate')
       .alias('delete')
       .description('Deactivate the did:btcr2 identifier permanently.')
-      .action(async (options) => {
-        await this.invokeCommand({ options, action: 'deactivate', command: new Btcr2Command() });
+      .action(async () => {
+        const result = await this.invokeCommand({ options: {}, action: 'deactivate', command: new Btcr2Command() });
+        this.printResult(result);
       });
   }
 
   /**
-   * A helper to invoke the command logic without forcibly exiting.
+   * 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({ options, action, command }: {
+  private async invokeCommand(request: {
     options: any;
-    action: string;
+    action: CommandRequest['action'];
     command: Btcr2Command;
-  }): Promise<void> {
+  }): Promise<CommandResult> {
+    return await request.command.execute({ action: request.action, options: request.options } as CommandRequest);
+  }
+
+  /**
+   * Runs the CLI with the provided argv or process.argv.
+   * @param {string[]} [argv] The argv array to use. Defaults to process.argv.
+   */
+  public async run(argv?: string[]) {
     try {
-      await command.execute({ options, action });
-    } catch (error) {
-      console.error('Error executing command:', error);
+      const normalized = this.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);
     }
   }
 
   /**
-   * Parse and run the CLI.
+   * 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}
    */
-  public run(argv?: string[]): void {
-    if (argv) {
-      this.CLI.parse(argv, { from: 'user' });
-    } else {
-      // parse real process.argv
-      this.CLI.parse();
+  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;
+  }
 
-    // If no subcommand was given, show help
-    if (!this.CLI.args.length) {
-      this.CLI.help();
+  /**
+   * 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.identifier The did:btcr2 identifier
+   * @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.patch 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.beaconIds The beacon IDs as a JSON string array
+   * @returns {UpdateCommandOptions} The parsed update command options
+   */
+  private parseUpdateOptions(options: {
+    identifier: string;
+    sourceDocument: string;
+    sourceVersionId: number;
+    patch: string;
+    verificationMethodId: string;
+    beaconIds: string;
+  }): UpdateCommandOptions {
+    this.validateIdentifier(options.identifier, options);
+    const sourceDocument = this.parseJsonOption<UpdateCommandOptions['sourceDocument']>(
+      options.sourceDocument,
+      'Invalid options. Must be a valid JSON string.',
+      options
+    );
+    const patch = this.parseJsonOption<UpdateCommandOptions['patch']>(
+      options.patch,
+      'Invalid options. Must be a valid JSON string.',
+      options
+    );
+    const beaconIds = this.parseJsonOption<UpdateCommandOptions['beaconIds']>(
+      options.beaconIds,
+      'Invalid options. Must be a valid JSON string.',
+      options
+    );
+
+    return {
+      identifier           : options.identifier,
+      sourceDocument,
+      sourceVersionId      : Number(options.sourceVersionId),
+      patch,
+      verificationMethodId : options.verificationMethodId,
+      beaconIds,
+    } 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
+      );
+    }
+  }
 
-export default new DidBtcr2Cli().run();
+  /**
+   * 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
+      );
+    }
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * 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.metadata);
+        break;
+      case 'deactivate':
+      case 'delete':
+        this.log(result.message);
+        break;
+      default:
+        this.log(result);
+    }
+  }
+
+  /**
+   * 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));
+  }
+}

package/src/command.ts

@@ -1,49 +1,77 @@
-import { IdentifierTypes, Logger, MethodError } from '@did-btcr2/common';
-import { DidBtcr2, DidResolutionOptions } from '@did-btcr2/method';
+import { IdentifierTypes, Logger, MethodError, PatchOperation } from '@did-btcr2/common';
+import { DidBtcr2, DidDocument, DidResolutionOptions, DidResolutionResult, SignalsMetadata } from '@did-btcr2/method';
+
+export type NetworkOption = 'bitcoin' | 'testnet3' | 'testnet4' | 'signet' | 'mutinynet' | 'regtest';
 
 export interface CommandInterface {
-  execute(params: { options?: any; action?: string }): Promise<void>;
+  execute(request: CommandRequest): Promise<CommandResult>;
+}
+
+export interface CreateCommandOptions {
+  type: 'k' | 'x';
+  bytes: string;
+  network: NetworkOption;
+}
+
+export interface ResolveCommandOptions {
+  identifier: string;
+  options?: DidResolutionOptions;
+}
+
+export interface UpdateCommandOptions {
+  identifier: string;
+  sourceDocument: DidDocument;
+  sourceVersionId: number;
+  patch: PatchOperation[];
+  verificationMethodId: string;
+  beaconIds: string[];
 }
 
-interface ExecuteParams {
-  options?: any;
-  action?: string
+export interface DeactivateCommandOptions {
+  // Placeholder for future deactivate payload once implemented.
 }
 
+export type CommandRequest =
+  | { action: 'create'; options: CreateCommandOptions; }
+  | { action: 'resolve' | 'read'; options: ResolveCommandOptions; }
+  | { action: 'update'; options: UpdateCommandOptions; }
+  | { action: 'deactivate' | 'delete'; options: DeactivateCommandOptions; };
+
+export type CommandResult =
+  | { action: 'create'; did: string; }
+  | { action: 'resolve' | 'read'; resolution: DidResolutionResult; }
+  | { action: 'update'; metadata: SignalsMetadata; }
+  | { action: 'deactivate' | 'delete'; message: string; };
+
 export default class Btcr2Command implements CommandInterface {
-  async execute({ options, action }: ExecuteParams): Promise<void> {
-    try {
-      switch (action) {
-        case 'create':{
-          const { type, bytes } = options as { type: string; bytes: string };
-          const idType = type === 'k' ? IdentifierTypes.KEY : IdentifierTypes.EXTERNAL;
-          const genesisBytes = Buffer.from(bytes, 'hex').toArray().toUint8Array();
-          const did = await DidBtcr2.create({ idType, genesisBytes });
-          console.log(did);
-          break;
-        }
-        case 'read':
-        case 'resolve': {
-          const { identifier, options: resolutionOptions } = options as DidResolutionOptions;
-          const resolutionResult = await DidBtcr2.resolve(identifier, resolutionOptions);
-          console.log(JSON.stringify(resolutionResult, null, 2));
-          break;
-        }
-        case 'update': {
-          const update = await DidBtcr2.update(options);
-          console.log(JSON.stringify(update, null, 2));
-          break;
-        }
-        case 'delete':
-        case 'deactivate':
-          // await DidBtcr2.deactivate(options);
-          Logger.warn('// TODO: Update once DidBtcr2.deactivate implemented');
-          break;
-        default:
-          throw new MethodError(`Invalid command: ${action}`, 'INVALID_COMMAND');
+  async execute(request: CommandRequest): Promise<CommandResult> {
+    const action = request.action;
+    switch (action) {
+      case 'create': {
+        const { type, bytes, network } = request.options;
+        const idType = type === 'k' ? IdentifierTypes.KEY : IdentifierTypes.EXTERNAL;
+        const genesisBytes = Buffer.from(bytes, 'hex').toArray().toUint8Array();
+        const did = await DidBtcr2.create({ idType, genesisBytes, options: { network } });
+        return { action: 'create', did };
+      }
+      case 'read':
+      case 'resolve': {
+        const { identifier, options } = request.options;
+        const resolution = await DidBtcr2.resolve(identifier, options);
+        return { action: request.action, resolution };
+      }
+      case 'update': {
+        const metadata = await DidBtcr2.update(request.options as any);
+        return { action: 'update', metadata };
+      }
+      case 'delete':
+      case 'deactivate': {
+        Logger.warn('// TODO: Update once DidBtcr2.deactivate implemented');
+        return { action: 'deactivate', message: 'Deactivate not yet implemented' };
+      }
+      default:{
+        throw new MethodError(`Invalid command: ${action}`, 'INVALID_COMMAND');
       }
-    } catch (error: any) {
-      console.error(error);
     }
   }
 }

package/src/error.ts

@@ -0,0 +1,10 @@
+import { DidMethodError } from '@did-btcr2/common';
+
+/**
+ * Custom CLI Error class extending DidMethodError.
+ */
+export class CLIError extends DidMethodError {
+  constructor(message: string, type: string = 'CLIError', data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}

package/src/index.ts

@@ -1,2 +1,3 @@
 export * from './cli.js';
-export * from './command.js';
+export * from './command.js';
+export * from './error.js';