@did-btcr2/cli 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "CLI for interacting with did-btcr2-js, the JavaScript/TypeScript reference implementation of the did:btcr2 method. Exposes various parts of multiple packages in the did-btcr2-js monorepo.",
   "main": "./dist/cjs/index.js",
@@ -58,9 +58,9 @@
   "dependencies": {
     "@web5/dids": "^1.2.0",
     "commander": "^13.1.0",
-    "@did-btcr2/cryptosuite": "5.1.0",
-    "@did-btcr2/common": "4.0.1",
-    "@did-btcr2/method": "0.22.0"
+    "@did-btcr2/common": "5.0.0",
+    "@did-btcr2/cryptosuite": "6.0.0",
+    "@did-btcr2/method": "0.23.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.21.0",
@@ -95,7 +95,7 @@
     "wipe": "pnpm clean && pnpm clean:deps",
     "reinstall": "pnpm install --force",
     "build": "pnpm clean:build && pnpm build:esm && pnpm build:cjs",
-    "build:esm": "rimraf dist/esm dist/types && pnpm tsc -p tsconfig.json",
+    "build:esm": "rimraf dist/esm dist/types && pnpm tsc -p tsconfig.json && chmod +x dist/esm/bin/btcr2.js",
     "build:cjs": "rimraf dist/cjs && tsc -p tsconfig.cjs.json && echo '{\"type\": \"commonjs\"}' > ./dist/cjs/package.json",
     "build:tests": "pnpm clean:tests && pnpm tsc -p tests/tsconfig.json",
     "build:all": "pnpm build && pnpm build:tests",
@@ -103,7 +103,6 @@
     "lint:fix": "eslint . --fix",
     "test": "pnpm c8 mocha",
     "build:test": "pnpm build && pnpm build:tests && pnpm c8 mocha",
-    "build:lint": "pnpm build && pnpm build:tests && pnpm lint:fix",
-    "prepublish": "pnpm build"
+    "build:lint": "pnpm build && pnpm build:tests && pnpm lint:fix"
   }
 }

package/src/cli.ts

@@ -1,374 +1,94 @@
-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 { DidBtcr2 } from '@did-btcr2/method';
+import {
+  registerCreateCommand,
+  registerDeactivateCommand,
+  registerResolveCommand,
+  registerUpdateCommand,
+} from './commands/index.js';
 import { CLIError } from './error.js';
+import { GlobalOptions, MethodOperations } from './types.js';
+import { VERSION } from './version.js';
 
-const SUPPORTED_NETWORKS: NetworkOption[] = ['bitcoin', 'testnet3', 'testnet4', 'signet', 'mutinynet', 'regtest'];
+/** Default MethodOperations delegating to DidBtcr2 static methods. */
+const defaultOps: MethodOperations = {
+  create  : (genesisBytes, options) => DidBtcr2.create(genesisBytes, options),
+  resolve : (identifier, options) => DidBtcr2.resolve(identifier, options),
+  update  : (params) => DidBtcr2.update(params),
+};
 
 /**
  * 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 ops: MethodOperations;
 
   /**
-   * Configures the CLI commands.
-   * @returns {void}
+   * Initializes the CLI with optional custom MethodOperations.
+   * @param {MethodOperations} ops - Custom operations for create, resolve, and update.
    */
-  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(ops: MethodOperations = defaultOps) {
+    this.ops = ops;
+    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.ops, globals);
+    registerResolveCommand(this.program, this.ops, globals);
+    registerUpdateCommand(this.program, this.ops, globals);
+    registerDeactivateCommand(this.program, this.ops, 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,88 @@
+import { IdentifierTypes } from '@did-btcr2/common';
+import { Command } from 'commander';
+import { CLIError } from '../error.js';
+import { formatResult } from '../output.js';
+import {
+  CreateCommandOptions,
+  GlobalOptions,
+  MethodOperations,
+  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,
+  ops     : MethodOperations,
+  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 idType = parsed.type === 'k' ? IdentifierTypes.KEY : IdentifierTypes.EXTERNAL;
+      const genesisBytes = Buffer.from(parsed.bytes, 'hex');
+      const data = ops.create(genesisBytes, { idType, 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,71 @@
+import { Command } from 'commander';
+import { CLIError } from '../error.js';
+import { formatResult } from '../output.js';
+import { GlobalOptions, MethodOperations, 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,
+  ops     : MethodOperations,
+  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 ops.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';