@bcts/dcbor-cli 1.0.0-alpha.13

package/src/cli.ts

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/* eslint-disable no-console, no-undef, no-restricted-globals, @typescript-eslint/no-unsafe-argument */
+/**
+ * dcbor CLI - Command line parser/validator for deterministic CBOR (dCBOR)
+ *
+ * A command line tool for composing, parsing and validating Gordian dCBOR.
+ * See the main repo README: https://github.com/leonardocustodio/bcts
+ */
+
+import { Command, Option } from "commander";
+import { VERSION } from "./index.js";
+import { run, type Command as CmdType } from "./run.js";
+import type { InputFormat, OutputFormat } from "./format.js";
+import type { MatchOutputFormat } from "./cmd/match.js";
+
+const program = new Command();
+
+program
+  .name("dcbor")
+  .description("Command line parser/validator for deterministic CBOR (dCBOR)")
+  .version(VERSION);
+
+// Default command arguments (when no subcommand is provided)
+program
+  .argument("[input]", "Input dCBOR in the format specified by --in")
+  .addOption(
+    new Option("-i, --in <format>", "The input format")
+      .choices(["diag", "hex", "bin"])
+      .default("diag"),
+  )
+  .addOption(
+    new Option("-o, --out <format>", "The output format")
+      .choices(["diag", "hex", "bin", "none"])
+      .default("hex"),
+  )
+  .option("-a, --annotate", "Output diagnostic notation or hexadecimal with annotations")
+  .action(
+    async (
+      input: string | undefined,
+      options: {
+        in: InputFormat;
+        out: OutputFormat;
+        annotate?: boolean;
+      },
+    ) => {
+      // Read stdin if needed
+      let stdinContent: string | undefined;
+      if (input === undefined && options.in !== "bin") {
+        stdinContent = await readStdin();
+      } else if (options.in === "bin") {
+        stdinContent = await readStdin();
+      }
+
+      const command: CmdType = {
+        type: "default",
+        input,
+        in: options.in,
+        out: options.out,
+        annotate: options.annotate ?? false,
+      };
+
+      const result = run({ command, stdinContent });
+
+      if (!result.ok) {
+        console.error(`Error: ${result.error.message}`);
+        process.exit(1);
+      }
+
+      writeOutput(result.value.output, result.value.isBinary);
+    },
+  );
+
+// Array subcommand
+program
+  .command("array")
+  .description("Compose a dCBOR array from the provided elements")
+  .argument("<elements...>", "Each element is parsed as a dCBOR item in diagnostic notation")
+  .addOption(
+    new Option("-o, --out <format>", "The output format")
+      .choices(["diag", "hex", "bin", "none"])
+      .default("hex"),
+  )
+  .option("-a, --annotate", "Output diagnostic notation or hexadecimal with annotations")
+  .action(
+    (
+      elements: string[],
+      options: {
+        out: OutputFormat;
+        annotate?: boolean;
+      },
+    ) => {
+      const command: CmdType = {
+        type: "array",
+        elements,
+        out: options.out,
+        annotate: options.annotate ?? false,
+      };
+
+      const result = run({ command });
+
+      if (!result.ok) {
+        console.error(`Error: ${result.error.message}`);
+        process.exit(1);
+      }
+
+      writeOutput(result.value.output, result.value.isBinary);
+    },
+  );
+
+// Map subcommand
+program
+  .command("map")
+  .description("Compose a dCBOR map from the provided keys and values")
+  .argument(
+    "<pairs...>",
+    "Each alternating key and value is parsed as a dCBOR item in diagnostic notation",
+  )
+  .addOption(
+    new Option("-o, --out <format>", "The output format")
+      .choices(["diag", "hex", "bin", "none"])
+      .default("hex"),
+  )
+  .option("-a, --annotate", "Output diagnostic notation or hexadecimal with annotations")
+  .action(
+    (
+      pairs: string[],
+      options: {
+        out: OutputFormat;
+        annotate?: boolean;
+      },
+    ) => {
+      const command: CmdType = {
+        type: "map",
+        kvPairs: pairs,
+        out: options.out,
+        annotate: options.annotate ?? false,
+      };
+
+      const result = run({ command });
+
+      if (!result.ok) {
+        console.error(`Error: ${result.error.message}`);
+        process.exit(1);
+      }
+
+      writeOutput(result.value.output, result.value.isBinary);
+    },
+  );
+
+// Match subcommand
+program
+  .command("match")
+  .description("Match dCBOR data against a pattern")
+  .argument("<pattern>", "The pattern to match against")
+  .argument("[input]", "dCBOR input (hex, diag, or binary). If not provided, reads from stdin")
+  .addOption(
+    new Option("-i, --in <format>", "Input format").choices(["diag", "hex", "bin"]).default("diag"),
+  )
+  .addOption(
+    new Option("-o, --out <format>", "Output format")
+      .choices(["paths", "diag", "hex", "bin"])
+      .default("paths"),
+  )
+  .option("--no-indent", "Disable indentation of path elements")
+  .option("--last-only", "Show only the last element of each path")
+  .option("--annotate", "Add annotations to output")
+  .option("--captures", "Include capture information in output")
+  .action(
+    async (
+      pattern: string,
+      input: string | undefined,
+      options: {
+        in: InputFormat;
+        out: MatchOutputFormat;
+        indent: boolean;
+        lastOnly?: boolean;
+        annotate?: boolean;
+        captures?: boolean;
+      },
+    ) => {
+      // Read stdin if needed
+      let stdinContent: string | undefined;
+      if (input === undefined) {
+        stdinContent = await readStdin();
+      }
+
+      const command: CmdType = {
+        type: "match",
+        pattern,
+        input,
+        in: options.in,
+        out: options.out,
+        noIndent: !options.indent,
+        lastOnly: options.lastOnly ?? false,
+        annotate: options.annotate ?? false,
+        captures: options.captures ?? false,
+      };
+
+      const result = run({ command, stdinContent });
+
+      if (!result.ok) {
+        console.error(`Error: ${result.error.message}`);
+        process.exit(1);
+      }
+
+      writeOutput(result.value.output, result.value.isBinary);
+    },
+  );
+
+/**
+ * Read from stdin
+ */
+async function readStdin(): Promise<string> {
+  // Check if stdin is a TTY (interactive terminal)
+  if (process.stdin.isTTY) {
+    return "";
+  }
+
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * Write output to stdout
+ */
+function writeOutput(output: string, isBinary: boolean): void {
+  if (isBinary) {
+    // For binary output, decode hex back to bytes
+    const bytes = Buffer.from(output, "hex");
+    process.stdout.write(bytes);
+  } else if (output.length > 0) {
+    console.log(output);
+  }
+}
+
+program.parse();

package/src/cmd/array.ts

@@ -0,0 +1,41 @@
+/**
+ * Compose a dCBOR array from the provided elements
+ * Equivalent to Rust's cmd/array.rs
+ */
+
+import { type Result, errorMsg } from "@bcts/dcbor";
+import { composeDcborArray, composeErrorMessage } from "@bcts/dcbor-parse";
+import type { Exec } from "./index.js";
+import { type OutputFormat, formatOutput } from "../format.js";
+
+/**
+ * Command arguments for array composition
+ */
+export interface ArrayCommandArgs {
+  /** Each element is parsed as a dCBOR item in diagnostic notation */
+  elements: string[];
+  /** The output format (default: hex) */
+  out: OutputFormat;
+  /** Output with annotations */
+  annotate: boolean;
+}
+
+/**
+ * Execute array command
+ */
+export function execArray(args: ArrayCommandArgs): Result<string> {
+  const result = composeDcborArray(args.elements);
+  if (!result.ok) {
+    return { ok: false, error: errorMsg(composeErrorMessage(result.error)) };
+  }
+  return formatOutput(result.value, args.out, args.annotate);
+}
+
+/**
+ * Create an Exec implementation for array command
+ */
+export function createArrayCommand(args: ArrayCommandArgs): Exec {
+  return {
+    exec: () => execArray(args),
+  };
+}

package/src/cmd/default.ts

@@ -0,0 +1,108 @@
+/**
+ * Default parsing and validation behavior
+ * Equivalent to Rust's cmd/default.rs
+ */
+/* eslint-disable @typescript-eslint/restrict-template-expressions, @typescript-eslint/strict-boolean-expressions */
+
+import { type Cbor, type Result, decodeCbor, hexToBytes, errorMsg } from "@bcts/dcbor";
+import { parseDcborItem, fullErrorMessage } from "@bcts/dcbor-parse";
+import type { Exec } from "./index.js";
+import { type InputFormat, type OutputFormat, formatOutput } from "../format.js";
+
+/**
+ * Command arguments for default parsing behavior
+ */
+export interface DefaultCommandArgs {
+  /** Input dCBOR in the format specified by `in`. Optional - reads from stdin if not provided */
+  input?: string | undefined;
+  /** The input format (default: diag) */
+  in: InputFormat;
+  /** The output format (default: hex) */
+  out: OutputFormat;
+  /** Output with annotations */
+  annotate: boolean;
+}
+
+/**
+ * Execute default command with a reader function for stdin
+ */
+export function execDefaultWithReader(
+  args: DefaultCommandArgs,
+  readString: () => string,
+  readData: () => Uint8Array,
+): Result<string> {
+  let cbor: Cbor;
+
+  try {
+    switch (args.in) {
+      case "diag": {
+        if (args.input !== undefined) {
+          const result = parseDcborItem(args.input);
+          if (!result.ok) {
+            return {
+              ok: false,
+              error: errorMsg(fullErrorMessage(result.error, args.input)),
+            };
+          }
+          cbor = result.value;
+        } else {
+          const diag = readString();
+          const result = parseDcborItem(diag);
+          if (!result.ok) {
+            return {
+              ok: false,
+              error: errorMsg(fullErrorMessage(result.error, diag)),
+            };
+          }
+          cbor = result.value;
+        }
+        break;
+      }
+      case "hex": {
+        if (args.input !== undefined) {
+          cbor = decodeCbor(hexToBytes(args.input));
+        } else {
+          const hexStr = readString().trim();
+          cbor = decodeCbor(hexToBytes(hexStr));
+        }
+        break;
+      }
+      case "bin": {
+        const data = readData();
+        cbor = decodeCbor(data);
+        break;
+      }
+      default:
+        return { ok: false, error: errorMsg(`Unknown input format: ${args.in}`) };
+    }
+  } catch (e) {
+    return { ok: false, error: errorMsg(e instanceof Error ? e.message : String(e)) };
+  }
+
+  return formatOutput(cbor, args.out, args.annotate);
+}
+
+/**
+ * Execute default command (reads from stdin if input not provided)
+ */
+export function execDefault(args: DefaultCommandArgs, stdinContent?: string): Result<string> {
+  return execDefaultWithReader(
+    args,
+    () => stdinContent ?? "",
+    () => {
+      if (stdinContent) {
+        return new TextEncoder().encode(stdinContent);
+      }
+      return new Uint8Array(0);
+    },
+  );
+}
+
+/**
+ * Create an Exec implementation for default command
+ */
+export function createDefaultCommand(args: DefaultCommandArgs, stdinContent?: string): Exec {
+  return {
+    exec: () => execDefault(args, stdinContent),
+  };
+}

package/src/cmd/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Command module organization
+ * Equivalent to Rust's cmd/mod.rs
+ */
+
+import type { Result } from "@bcts/dcbor";
+
+export * from "./array.js";
+export * from "./default.js";
+export * from "./map.js";
+export * from "./match.js";
+
+/**
+ * Trait for command execution
+ * Equivalent to Rust's `pub trait Exec`
+ */
+export interface Exec {
+  exec(): Result<string>;
+}

package/src/cmd/map.ts

@@ -0,0 +1,41 @@
+/**
+ * Compose a dCBOR map from the provided keys and values
+ * Equivalent to Rust's cmd/map.rs
+ */
+
+import { type Result, errorMsg } from "@bcts/dcbor";
+import { composeDcborMap, composeErrorMessage } from "@bcts/dcbor-parse";
+import type { Exec } from "./index.js";
+import { type OutputFormat, formatOutput } from "../format.js";
+
+/**
+ * Command arguments for map composition
+ */
+export interface MapCommandArgs {
+  /** Alternating keys and values parsed as dCBOR items in diagnostic notation */
+  kvPairs: string[];
+  /** The output format (default: hex) */
+  out: OutputFormat;
+  /** Output with annotations */
+  annotate: boolean;
+}
+
+/**
+ * Execute map command
+ */
+export function execMap(args: MapCommandArgs): Result<string> {
+  const result = composeDcborMap(args.kvPairs);
+  if (!result.ok) {
+    return { ok: false, error: errorMsg(composeErrorMessage(result.error)) };
+  }
+  return formatOutput(result.value, args.out, args.annotate);
+}
+
+/**
+ * Create an Exec implementation for map command
+ */
+export function createMapCommand(args: MapCommandArgs): Exec {
+  return {
+    exec: () => execMap(args),
+  };
+}

package/src/cmd/match.ts

@@ -0,0 +1,196 @@
+/**
+ * Match dCBOR data against a pattern
+ * Equivalent to Rust's cmd/match.rs
+ */
+/* eslint-disable @typescript-eslint/restrict-template-expressions, @typescript-eslint/switch-exhaustiveness-check */
+
+import { type Cbor, type Result, decodeCbor, hexToBytes, errorMsg } from "@bcts/dcbor";
+import { parseDcborItem, fullErrorMessage } from "@bcts/dcbor-parse";
+import {
+  parse as parsePattern,
+  pathsWithCaptures,
+  formatPathsWithCaptures,
+  FormatPathsOptsBuilder,
+  type Error as PatternParseError,
+} from "@bcts/dcbor-pattern";
+import type { Exec } from "./index.js";
+import { type OutputFormat, formatOutput } from "../format.js";
+import type { InputFormat } from "../format.js";
+
+/**
+ * Match output format options
+ */
+export type MatchOutputFormat = "paths" | "diag" | "hex" | "bin";
+
+/**
+ * Command arguments for match command
+ */
+export interface MatchCommandArgs {
+  /** The pattern to match against */
+  pattern: string;
+  /** dCBOR input (hex, diag, or binary). If not provided, reads from stdin */
+  input?: string | undefined;
+  /** Input format (default: diag) */
+  in: InputFormat;
+  /** Output format (default: paths) */
+  out: MatchOutputFormat;
+  /** Disable indentation of path elements */
+  noIndent: boolean;
+  /** Show only the last element of each path */
+  lastOnly: boolean;
+  /** Add annotations to output */
+  annotate: boolean;
+  /** Include capture information in output */
+  captures: boolean;
+}
+
+/**
+ * Format a parse error with context
+ */
+function formatPatternError(error: PatternParseError, patternStr: string): string {
+  switch (error.type) {
+    case "UnrecognizedToken": {
+      const start = Math.min(error.span.start, patternStr.length);
+      const end = Math.min(error.span.end, patternStr.length);
+      const errorText = start < patternStr.length ? patternStr.slice(start, end) : "<end of input>";
+      return `Failed to parse pattern at position ${start}..${end}: unrecognized token '${errorText}'\nPattern: ${patternStr}\n         ${" ".repeat(start)}^`;
+    }
+
+    case "ExtraData": {
+      const start = Math.min(error.span.start, patternStr.length);
+      return `Failed to parse pattern: extra data at position ${start}\nPattern: ${patternStr}\n         ${" ".repeat(start)}^`;
+    }
+
+    case "UnexpectedToken": {
+      const start = Math.min(error.span.start, patternStr.length);
+      return `Failed to parse pattern at position ${start}: unexpected token\nPattern: ${patternStr}\n         ${" ".repeat(start)}^`;
+    }
+
+    default:
+      return `Failed to parse pattern: ${error.type}`;
+  }
+}
+
+/**
+ * Execute match command
+ */
+export function execMatch(args: MatchCommandArgs, stdinContent?: string): Result<string> {
+  // Read input data
+  let inputData: Uint8Array;
+  if (args.input !== undefined) {
+    inputData = new TextEncoder().encode(args.input);
+  } else if (stdinContent !== undefined) {
+    inputData = new TextEncoder().encode(stdinContent);
+  } else {
+    inputData = new Uint8Array(0);
+  }
+
+  // Parse input based on format
+  let cbor: Cbor;
+  try {
+    switch (args.in) {
+      case "diag": {
+        const inputStr = new TextDecoder().decode(inputData).trim();
+        const result = parseDcborItem(inputStr);
+        if (!result.ok) {
+          return {
+            ok: false,
+            error: errorMsg(fullErrorMessage(result.error, inputStr)),
+          };
+        }
+        cbor = result.value;
+        break;
+      }
+      case "hex": {
+        const inputStr = new TextDecoder().decode(inputData).trim();
+        cbor = decodeCbor(hexToBytes(inputStr));
+        break;
+      }
+      case "bin": {
+        cbor = decodeCbor(inputData);
+        break;
+      }
+      default:
+        return { ok: false, error: errorMsg(`Unknown input format: ${args.in}`) };
+    }
+  } catch (e) {
+    return { ok: false, error: errorMsg(e instanceof Error ? e.message : String(e)) };
+  }
+
+  // Parse pattern
+  const patternResult = parsePattern(args.pattern);
+  if (!patternResult.ok) {
+    return {
+      ok: false,
+      error: errorMsg(formatPatternError(patternResult.error, args.pattern)),
+    };
+  }
+  const pattern = patternResult.value;
+
+  // Execute pattern matching
+  const { paths, captures } = pathsWithCaptures(pattern, cbor);
+
+  // Check for matches
+  if (paths.length === 0) {
+    return { ok: false, error: errorMsg("No match") };
+  }
+
+  // Format output based on requested format
+  switch (args.out) {
+    case "paths": {
+      // Build format options from command line arguments
+      const formatOptions = FormatPathsOptsBuilder.new()
+        .indent(!args.noIndent)
+        .lastElementOnly(args.lastOnly)
+        .build();
+
+      // Show captures only if explicitly requested
+      if (args.captures) {
+        return {
+          ok: true,
+          value: formatPathsWithCaptures(paths, captures, formatOptions),
+        };
+      } else {
+        // Show paths without captures
+        return {
+          ok: true,
+          value: formatPathsWithCaptures(paths, new Map(), formatOptions),
+        };
+      }
+    }
+
+    case "diag":
+    case "hex":
+    case "bin": {
+      // For data format outputs, extract the matched elements
+      const outputFormat: OutputFormat = args.out;
+
+      const elementsToOutput = args.lastOnly
+        ? paths.map((path) => path[path.length - 1]).filter(Boolean)
+        : paths.map((path) => path[0]).filter(Boolean);
+
+      const results: string[] = [];
+      for (const element of elementsToOutput) {
+        const result = formatOutput(element, outputFormat, args.annotate);
+        if (!result.ok) {
+          return result;
+        }
+        results.push(result.value);
+      }
+
+      return { ok: true, value: results.join("\n") };
+    }
+
+    default:
+      return { ok: false, error: errorMsg(`Unknown output format: ${args.out}`) };
+  }
+}
+
+/**
+ * Create an Exec implementation for match command
+ */
+export function createMatchCommand(args: MatchCommandArgs, stdinContent?: string): Exec {
+  return {
+    exec: () => execMatch(args, stdinContent),
+  };
+}