@bcts/provenance-mark-cli 1.0.0-alpha.13

package/src/cmd/new.ts

@@ -0,0 +1,235 @@
+/**
+ * New command - 1:1 port of new.rs
+ *
+ * Initialize a directory with a new provenance mark chain.
+ */
+
+/* eslint-disable no-console, no-undef */
+
+import * as fs from "fs";
+import * as path from "path";
+import {
+  ProvenanceMarkGenerator,
+  ProvenanceMarkInfo,
+  ProvenanceMarkResolution,
+  type ProvenanceSeed,
+} from "@bcts/provenance-mark";
+
+import type { Exec } from "../exec.js";
+import { readNewPath } from "../utils.js";
+import { type InfoArgs, parseInfoArgs } from "./info.js";
+
+/**
+ * Output format for the creation summary.
+ *
+ * Corresponds to Rust `OutputFormat`
+ */
+export enum OutputFormat {
+  Markdown = "markdown",
+  Ur = "ur",
+  Json = "json",
+}
+
+/**
+ * Resolution level for the provenance mark chain.
+ *
+ * Corresponds to Rust `Resolution`
+ */
+export enum Resolution {
+  /** Good for physical works of art and applications requiring minimal mark size. */
+  Low = "low",
+  /** Good for digital works of art. */
+  Medium = "medium",
+  /** Good for general use. */
+  Quartile = "quartile",
+  /** Industrial strength, largest mark. */
+  High = "high",
+}
+
+/**
+ * Convert Resolution to ProvenanceMarkResolution.
+ */
+function resolutionToProvenanceMarkResolution(res: Resolution): ProvenanceMarkResolution {
+  switch (res) {
+    case Resolution.Low:
+      return ProvenanceMarkResolution.Low;
+    case Resolution.Medium:
+      return ProvenanceMarkResolution.Medium;
+    case Resolution.Quartile:
+      return ProvenanceMarkResolution.Quartile;
+    case Resolution.High:
+      return ProvenanceMarkResolution.High;
+  }
+}
+
+/**
+ * Parse a resolution string.
+ */
+export function parseResolution(value: string): Resolution {
+  switch (value.toLowerCase()) {
+    case "low":
+      return Resolution.Low;
+    case "medium":
+      return Resolution.Medium;
+    case "quartile":
+      return Resolution.Quartile;
+    case "high":
+      return Resolution.High;
+    default:
+      throw new Error(`Invalid resolution: ${value}. Must be one of: low, medium, quartile, high`);
+  }
+}
+
+/**
+ * Parse an output format string.
+ */
+export function parseOutputFormat(value: string): OutputFormat {
+  switch (value.toLowerCase()) {
+    case "markdown":
+      return OutputFormat.Markdown;
+    case "ur":
+      return OutputFormat.Ur;
+    case "json":
+      return OutputFormat.Json;
+    default:
+      throw new Error(`Invalid format: ${value}. Must be one of: markdown, ur, json`);
+  }
+}
+
+/**
+ * Arguments for the new command.
+ *
+ * Corresponds to Rust `CommandArgs`
+ */
+export interface NewCommandArgs {
+  /** Path to directory to be created. Must not already exist. */
+  path: string;
+  /** A seed to use for the provenance mark chain, encoded as base64. */
+  seed?: ProvenanceSeed;
+  /** The resolution of the provenance mark chain. */
+  resolution: Resolution;
+  /** A comment to be included for the genesis mark. */
+  comment: string;
+  /** The date of the genesis mark. If not supplied, the current date is used. */
+  date?: Date;
+  /** Suppress informational status output on stderr/stdout. */
+  quiet: boolean;
+  /** Output format for the creation summary. */
+  format: OutputFormat;
+  /** Info args for the mark. */
+  info: InfoArgs;
+}
+
+/**
+ * Create default args for the new command.
+ */
+export function defaultNewCommandArgs(): NewCommandArgs {
+  return {
+    path: "",
+    resolution: Resolution.Quartile,
+    comment: "Genesis mark.",
+    quiet: false,
+    format: OutputFormat.Markdown,
+    info: {},
+  };
+}
+
+/**
+ * New command implementation.
+ *
+ * Corresponds to Rust `impl Exec for CommandArgs`
+ */
+export class NewCommand implements Exec {
+  private readonly args: NewCommandArgs;
+
+  constructor(args: NewCommandArgs) {
+    this.args = args;
+  }
+
+  exec(): string {
+    // Create the directory, ensuring it doesn't already exist.
+    const dirPath = this.createDir();
+
+    // Create the `marks` subdirectory inside `path`.
+    const marksPath = path.join(dirPath, "marks");
+    fs.mkdirSync(marksPath);
+
+    // Create the generator
+    const resolution = resolutionToProvenanceMarkResolution(this.args.resolution);
+    let generator: ProvenanceMarkGenerator;
+    if (this.args.seed !== undefined) {
+      generator = ProvenanceMarkGenerator.newWithSeed(resolution, this.args.seed);
+    } else {
+      generator = ProvenanceMarkGenerator.newRandom(resolution);
+    }
+
+    // Generate the genesis mark.
+    const date = this.args.date ?? new Date();
+    const info = parseInfoArgs(this.args.info);
+    const mark = generator.next(date, info);
+    const markInfo = ProvenanceMarkInfo.new(mark, this.args.comment);
+
+    // Serialize the mark to JSON and write it as `mark-seq.json` to `path/marks`.
+    const markJson = JSON.stringify(markInfo.toJSON(), null, 2);
+    const markPath = path.join(marksPath, `mark-${mark.seq()}.json`);
+    fs.writeFileSync(markPath, markJson);
+
+    // Serialize `generator` to JSON and write it as `generator.json` to `path`.
+    const generatorJson = JSON.stringify(generator.toJSON(), null, 2);
+    const generatorPath = path.join(dirPath, "generator.json");
+    fs.writeFileSync(generatorPath, generatorJson);
+
+    // Return output based on format.
+    const statusLines = [
+      `Provenance mark chain created at: ${dirPath}`,
+      `Mark ${mark.seq()} written to: ${markPath}`,
+    ];
+
+    switch (this.args.format) {
+      case OutputFormat.Markdown: {
+        const paragraphs: string[] = [];
+        if (!this.args.quiet) {
+          paragraphs.push(...statusLines);
+        }
+        paragraphs.push(markInfo.markdownSummary());
+        return paragraphs.join("\n\n");
+      }
+      case OutputFormat.Ur: {
+        if (!this.args.quiet) {
+          for (const line of statusLines) {
+            console.error(line);
+          }
+        }
+        return markInfo.ur().toString();
+      }
+      case OutputFormat.Json: {
+        if (!this.args.quiet) {
+          for (const line of statusLines) {
+            console.error(line);
+          }
+        }
+        return JSON.stringify(markInfo.toJSON(), null, 2);
+      }
+    }
+  }
+
+  private createDir(): string {
+    const dirPath = readNewPath(this.args.path);
+
+    // Ensure the directory doesn't already exist.
+    if (fs.existsSync(dirPath)) {
+      throw new Error(`Path already exists: ${dirPath}`);
+    }
+
+    // Ensure the parent directory exists.
+    const parent = path.dirname(dirPath);
+    if (!fs.existsSync(parent)) {
+      throw new Error(`Parent directory does not exist: ${parent}`);
+    }
+
+    // Create the new directory.
+    fs.mkdirSync(dirPath);
+
+    return dirPath;
+  }
+}

package/src/cmd/next.ts

@@ -0,0 +1,119 @@
+/**
+ * Next command - 1:1 port of next.rs
+ *
+ * Generate the next provenance mark in a chain.
+ */
+
+/* eslint-disable no-console, no-undef */
+
+import * as fs from "fs";
+import * as path from "path";
+import { ProvenanceMarkGenerator, ProvenanceMarkInfo } from "@bcts/provenance-mark";
+
+import type { Exec } from "../exec.js";
+import { readExistingDirectoryPath } from "../utils.js";
+import { type InfoArgs, parseInfoArgs } from "./info.js";
+import { OutputFormat, parseOutputFormat } from "./new.js";
+
+/**
+ * Arguments for the next command.
+ *
+ * Corresponds to Rust `CommandArgs`
+ */
+export interface NextCommandArgs {
+  /** Path to the chain's directory. Must already exist. */
+  path: string;
+  /** A comment to be included for the mark. */
+  comment: string;
+  /** The date of the next mark. If not supplied, the current date is used. */
+  date?: Date;
+  /** Suppress informational status output on stderr/stdout. */
+  quiet: boolean;
+  /** Output format for the mark. */
+  format: OutputFormat;
+  /** Info args for the mark. */
+  info: InfoArgs;
+}
+
+/**
+ * Create default args for the next command.
+ */
+export function defaultNextCommandArgs(): NextCommandArgs {
+  return {
+    path: "",
+    comment: "Blank.",
+    quiet: false,
+    format: OutputFormat.Markdown,
+    info: {},
+  };
+}
+
+/**
+ * Next command implementation.
+ *
+ * Corresponds to Rust `impl Exec for CommandArgs`
+ */
+export class NextCommand implements Exec {
+  private readonly args: NextCommandArgs;
+
+  constructor(args: NextCommandArgs) {
+    this.args = args;
+  }
+
+  exec(): string {
+    // Get the chain's directory path.
+    const dirPath = readExistingDirectoryPath(this.args.path);
+
+    // Read the generator from `path/generator.json`.
+    const generatorPath = path.join(dirPath, "generator.json");
+    const generatorJson = fs.readFileSync(generatorPath, "utf-8");
+    const generator = ProvenanceMarkGenerator.fromJSON(
+      JSON.parse(generatorJson) as Record<string, unknown>,
+    );
+
+    // Generate the next mark.
+    const date = this.args.date ?? new Date();
+    const info = parseInfoArgs(this.args.info);
+    const mark = generator.next(date, info);
+    const markInfo = ProvenanceMarkInfo.new(mark, this.args.comment);
+
+    // Serialize the mark to JSON and write it as `mark-seq.json` to `path/marks`.
+    const marksPath = path.join(dirPath, "marks");
+    const markJson = JSON.stringify(markInfo.toJSON(), null, 2);
+    const markPath = path.join(marksPath, `mark-${mark.seq()}.json`);
+    fs.writeFileSync(markPath, markJson);
+
+    // Serialize `generator` to JSON and write it back to `path/generator.json`.
+    const newGeneratorJson = JSON.stringify(generator.toJSON(), null, 2);
+    fs.writeFileSync(generatorPath, newGeneratorJson);
+
+    // Return output based on format.
+    const statusLine = `Mark ${mark.seq()} written to: ${markPath}`;
+
+    switch (this.args.format) {
+      case OutputFormat.Markdown: {
+        const paragraphs: string[] = [];
+        if (!this.args.quiet) {
+          paragraphs.push(statusLine);
+        }
+        paragraphs.push(markInfo.markdownSummary());
+        return paragraphs.join("\n\n");
+      }
+      case OutputFormat.Ur: {
+        if (!this.args.quiet) {
+          console.error(statusLine);
+        }
+        return markInfo.ur().toString();
+      }
+      case OutputFormat.Json: {
+        if (!this.args.quiet) {
+          console.error(statusLine);
+        }
+        return JSON.stringify(markInfo.toJSON(), null, 2);
+      }
+    }
+  }
+}
+
+// Re-export for convenience
+export { OutputFormat, parseOutputFormat };

package/src/cmd/print.ts

@@ -0,0 +1,108 @@
+/**
+ * Print command - 1:1 port of print.rs
+ *
+ * Prints provenance marks in a chain.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { ProvenanceMarkGenerator, ProvenanceMarkInfo } from "@bcts/provenance-mark";
+
+import type { Exec } from "../exec.js";
+import { readExistingDirectoryPath } from "../utils.js";
+import { OutputFormat, parseOutputFormat } from "./new.js";
+
+/**
+ * Arguments for the print command.
+ *
+ * Corresponds to Rust `CommandArgs`
+ */
+export interface PrintCommandArgs {
+  /** Path to the chain's directory. Must already exist. */
+  path: string;
+  /** The sequence number of the first mark to print. */
+  start: number;
+  /** The sequence number of the last mark to print. */
+  end?: number;
+  /** Output format for the rendered marks. */
+  format: OutputFormat;
+}
+
+/**
+ * Create default args for the print command.
+ */
+export function defaultPrintCommandArgs(): PrintCommandArgs {
+  return {
+    path: "",
+    start: 0,
+    format: OutputFormat.Markdown,
+  };
+}
+
+/**
+ * Print command implementation.
+ *
+ * Corresponds to Rust `impl Exec for CommandArgs`
+ */
+export class PrintCommand implements Exec {
+  private readonly args: PrintCommandArgs;
+
+  constructor(args: PrintCommandArgs) {
+    this.args = args;
+  }
+
+  exec(): string {
+    // Get the chain's directory path.
+    const dirPath = readExistingDirectoryPath(this.args.path);
+
+    // Read the generator from `path/generator.json`.
+    const generatorPath = path.join(dirPath, "generator.json");
+    const generatorJson = fs.readFileSync(generatorPath, "utf-8");
+    const generator = ProvenanceMarkGenerator.fromJSON(
+      JSON.parse(generatorJson) as Record<string, unknown>,
+    );
+
+    // Validate the start and end sequence numbers.
+    const lastValidSeq = generator.nextSeq() - 1;
+    const startSeq = this.args.start;
+    const endSeq = this.args.end ?? lastValidSeq;
+
+    if (startSeq > endSeq) {
+      throw new Error(
+        "The start sequence number must be less than or equal to the end sequence number.",
+      );
+    }
+    if (endSeq > lastValidSeq) {
+      throw new Error(
+        "The end sequence number must be less than or equal to the last valid sequence number.",
+      );
+    }
+
+    // Collect the requested marks.
+    const markInfos: ProvenanceMarkInfo[] = [];
+    for (let seq = startSeq; seq <= endSeq; seq++) {
+      const markPath = path.join(dirPath, "marks", `mark-${seq}.json`);
+      const markJson = fs.readFileSync(markPath, "utf-8");
+      const markInfo = ProvenanceMarkInfo.fromJSON(JSON.parse(markJson) as Record<string, unknown>);
+      markInfos.push(markInfo);
+    }
+
+    switch (this.args.format) {
+      case OutputFormat.Markdown: {
+        const summaries = markInfos.map((info) => info.markdownSummary());
+        return summaries.join("\n");
+      }
+      case OutputFormat.Ur: {
+        const urs = markInfos.map((info) => info.ur().toString());
+        return urs.join("\n");
+      }
+      case OutputFormat.Json: {
+        const jsonArray = markInfos.map((info) => info.toJSON());
+        return JSON.stringify(jsonArray, null, 2);
+      }
+    }
+  }
+}
+
+// Re-export for convenience
+export { OutputFormat, parseOutputFormat };

package/src/cmd/seed.ts

@@ -0,0 +1,114 @@
+/**
+ * Seed parsing - 1:1 port of seed.rs
+ *
+ * Functions for parsing provenance seeds from various formats.
+ */
+
+import { UR } from "@bcts/uniform-resources";
+import { Seed } from "@bcts/components";
+import { ProvenanceSeed, PROVENANCE_SEED_LENGTH } from "@bcts/provenance-mark";
+import { fromBase64, hexToBytes } from "../utils.js";
+
+/**
+ * Parse a seed from a string.
+ *
+ * Supports the following formats:
+ * - `ur:seed/...` - UR-encoded seed
+ * - `0x...` or hex string - Hex-encoded seed
+ * - Base64 string - Base64-encoded seed
+ *
+ * Corresponds to Rust `parse_seed()`
+ */
+export function parseSeed(input: string): ProvenanceSeed {
+  const trimmed = input.trim();
+  if (trimmed === "") {
+    throw new Error("seed string is empty");
+  }
+
+  // Try UR format first
+  if (trimmed.toLowerCase().startsWith("ur:")) {
+    return parseSeedUr(trimmed);
+  }
+
+  // Try hex format
+  const hexResult = parseSeedHex(trimmed);
+  if (hexResult !== undefined) {
+    return hexResult;
+  }
+
+  // Fall back to base64
+  return parseSeedBase64(trimmed);
+}
+
+/**
+ * Parse a seed from a UR string.
+ *
+ * Corresponds to Rust `parse_seed_ur()`
+ */
+function parseSeedUr(input: string): ProvenanceSeed {
+  try {
+    const ur = UR.fromURString(input);
+    const seed = Seed.fromUR(ur);
+    return seedFromExact(seed.toData());
+  } catch (e: unknown) {
+    const message = e instanceof Error ? e.message : String(e);
+    throw new Error(`failed to parse seed UR: ${message}`);
+  }
+}
+
+/**
+ * Parse a seed from a hex string.
+ *
+ * Returns undefined if the string is not valid hex format.
+ *
+ * Corresponds to Rust `parse_seed_hex()`
+ */
+function parseSeedHex(input: string): ProvenanceSeed | undefined {
+  const source = input.startsWith("0x") ? input.slice(2) : input;
+  if (source === "") {
+    return undefined;
+  }
+
+  // Check if it's valid hex
+  if (source.length % 2 !== 0) {
+    return undefined;
+  }
+  if (!/^[0-9a-fA-F]+$/.test(source)) {
+    return undefined;
+  }
+
+  try {
+    const bytes = hexToBytes(source);
+    return seedFromExact(bytes);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    throw new Error(`failed to decode hex seed: ${message}`);
+  }
+}
+
+/**
+ * Parse a seed from a base64 string.
+ *
+ * Corresponds to Rust `parse_seed_base64()`
+ */
+function parseSeedBase64(input: string): ProvenanceSeed {
+  try {
+    const bytes = fromBase64(input);
+    return seedFromExact(bytes);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    throw new Error(`failed to decode base64 seed: ${message}`);
+  }
+}
+
+/**
+ * Create a seed from exactly PROVENANCE_SEED_LENGTH bytes.
+ *
+ * Corresponds to Rust `seed_from_exact()`
+ */
+function seedFromExact(bytes: Uint8Array): ProvenanceSeed {
+  if (bytes.length !== PROVENANCE_SEED_LENGTH) {
+    throw new Error(`seed must be ${PROVENANCE_SEED_LENGTH} bytes but found ${bytes.length}`);
+  }
+  return ProvenanceSeed.fromBytes(bytes);
+}