keri-ts 0.2.3 → 0.3.1

package/README.md

@@ -1,25 +1,87 @@
 # keri-ts
 
-KERI TypeScript runtime package with the `tufa` CLI and foundational
-database/runtime modules.
+KERI TypeScript runtime package with the `tufa` CLI.
 
 ## Install
 
 ```bash
+# As a dependency
 npm install keri-ts
+
+# Global CLI install
+npm install -g keri-ts
 ```
 
-## CLI
+## CLI quick start
+
+`tufa version` and `tufa annotate` are the fastest way to verify your setup.
 
 ```bash
-npx tufa --help
-npx tufa version
+# Version
+tufa version
+tufa --version
+
+# Annotate CESR from file
+tufa annotate --in ./mystream.cesr
+
+# Annotate from stdin
+cat ./mystream.cesr | tufa annotate
+```
+
+## Benchmark CESR parser
+
+Benchmark any CESR stream from file or stdin:
+
+```bash
+# Benchmark a stream file
+tufa benchmark cesr --in ./mystream.cesr
+
+# Benchmark from stdin with explicit chunk simulation
+cat ./mystream.cesr | tufa benchmark cesr --chunk-size 256 --iterations 25 --warmup 5
 ```
 
-## Deno tasks (package-local)
+- `--in <path>`: input file path (defaults to stdin)
+- `--iterations <count>`: measured benchmark runs (default `50`)
+- `--warmup <count>`: warmup runs before measurement (default `5`)
+- `--chunk-size <bytes>`: chunk size for streaming simulation (`0` = full
+  stream)
+- `--framed`: benchmark parser in framed mode
+- `--compat`: benchmark parser with compat attachment dispatch mode
+- `--allow-errors`: continue benchmark even when parse errors are emitted
+- `--json`: print one JSON result line
+
+## Annotate options
 
 ```bash
+tufa annotate --in <path> --out <path> --pretty
+tufa annotate --qb2 --in <binary.qb2> --out <annotation.txt>
+```
+
+- `--in <path>`: input file path (defaults to stdin)
+- `--out <path>`: output file path (defaults to stdout)
+- `--qb2`: parse input as qb2 binary
+- `--pretty`: pretty-print annotation output
+- `--colored`: colorize annotation output on stdout only (ignored with `--out`)
+
+Optional color overrides:
+
+- File: `$HOME/.tufa/annot-color.yaml` or `$HOME/.tufa/annot-color.yml`
+- Keys: `counter`, `group`, `body`, `signature`, `said`, `opaque`, `comment`
+- Values: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`,
+  or bright variants (`brightBlack` ... `brightWhite`)
+
+## Package entrypoints
+
+```bash
+# CLI help
+npx tufa --help
+
+# From source in this repo
 deno task tufa --help
-deno task test:quality
-deno task build:npm
+deno task tufa version
 ```
+
+## License
+
+Licensed under the Apache License, Version 2.0 (`Apache-2.0`). See the
+top-level `LICENSE` file in this repository.

package/esm/app/cli/agent.js

@@ -1,19 +1,5 @@
 import { ValidationError } from "../../core/errors.js";
 import { startServer } from "../server.js";
-function printAgentHelp() {
-    console.log(`
-tufa agent - Start the KERI agent server
-
-Usage: tufa agent [options]
-
-Options:
-  --port, -p <port>           Port number for the server (default: 8000)
-  --help, -h                  Show this help message
-
-The agent server provides HTTP endpoints for interacting with keri-ts.
-The server will run until interrupted with SIGINT (Ctrl+C).
-`);
-}
 /**
  * Agent command operation - starts the HTTP server
  *
@@ -21,11 +7,6 @@ The server will run until interrupted with SIGINT (Ctrl+C).
  * @returns Operation that runs the server until shutdown
  */
 export function* agentCommand(args) {
-    // Check for help flag
-    if (args.help || args.h) {
-        printAgentHelp();
-        return;
-    }
     // Extract port from args (default to 8000)
     const port = args.port ? Number(args.port) : 8000;
     // Validate port number

package/esm/app/cli/annotate-color.js

@@ -0,0 +1,215 @@
+import * as dntShim from "../../_dnt.shims.js";
+const ANSI_CODES = {
+    black: "\x1b[30m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    blue: "\x1b[34m",
+    magenta: "\x1b[35m",
+    cyan: "\x1b[36m",
+    white: "\x1b[37m",
+    brightBlack: "\x1b[90m",
+    brightRed: "\x1b[91m",
+    brightGreen: "\x1b[92m",
+    brightYellow: "\x1b[93m",
+    brightBlue: "\x1b[94m",
+    brightMagenta: "\x1b[95m",
+    brightCyan: "\x1b[96m",
+    brightWhite: "\x1b[97m",
+};
+const RESET = "\x1b[0m";
+const COLOR_KEYS = [
+    "counter",
+    "group",
+    "body",
+    "signature",
+    "said",
+    "opaque",
+    "comment",
+];
+const DEFAULT_COLORS = {
+    counter: "cyan",
+    group: "magenta",
+    body: "green",
+    signature: "yellow",
+    said: "brightBlue",
+    opaque: "brightRed",
+    comment: "brightBlack",
+};
+const SAID_CAPTURE = /(said=)(\S+)/g;
+const COMMENT_DELIM = " # ";
+function isColorName(value) {
+    return typeof value === "string" && value in ANSI_CODES;
+}
+function parseColorConfig(raw) {
+    const parsed = {};
+    const lines = raw.split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const match = /^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.+?)\s*$/.exec(trimmed);
+        if (!match)
+            return null;
+        const key = match[1];
+        let value = match[2];
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        parsed[key] = value;
+    }
+    const config = {};
+    for (const key of COLOR_KEYS) {
+        const value = parsed[key];
+        if (value === undefined)
+            continue;
+        if (!isColorName(value))
+            return null;
+        config[key] = value;
+    }
+    return config;
+}
+function resolveConfigPath(homeDir) {
+    const basePath = `${homeDir}/.tufa`;
+    const yamlPath = `${basePath}/annot-color.yaml`;
+    const ymlPath = `${basePath}/annot-color.yml`;
+    try {
+        const stat = dntShim.Deno.statSync(yamlPath);
+        if (stat.isFile)
+            return yamlPath;
+    }
+    catch {
+        // Continue to .yml fallback
+    }
+    try {
+        const stat = dntShim.Deno.statSync(ymlPath);
+        if (stat.isFile)
+            return ymlPath;
+    }
+    catch {
+        // No config file, use defaults
+    }
+    return null;
+}
+function readUserColorConfig() {
+    const homeDir = dntShim.Deno.env.get("HOME");
+    if (!homeDir)
+        return null;
+    const configPath = resolveConfigPath(homeDir);
+    if (!configPath)
+        return null;
+    try {
+        return parseColorConfig(dntShim.Deno.readTextFileSync(configPath));
+    }
+    catch {
+        return null;
+    }
+}
+function toAnsiColors(userConfig) {
+    const names = { ...DEFAULT_COLORS };
+    if (userConfig) {
+        for (const key of COLOR_KEYS) {
+            const value = userConfig[key];
+            if (value)
+                names[key] = value;
+        }
+    }
+    return {
+        counter: ANSI_CODES[names.counter],
+        group: ANSI_CODES[names.group],
+        body: ANSI_CODES[names.body],
+        signature: ANSI_CODES[names.signature],
+        said: ANSI_CODES[names.said],
+        opaque: ANSI_CODES[names.opaque],
+        comment: ANSI_CODES[names.comment],
+    };
+}
+function color(text, ansiCode) {
+    if (!text)
+        return text;
+    return `${ansiCode}${text}${RESET}`;
+}
+function colorizeComment(comment, colors) {
+    const saidTinted = comment.replace(SAID_CAPTURE, (_whole, prefix, said) => `${prefix}${color(said, colors.said)}`);
+    return color(saidTinted, colors.comment);
+}
+function colorizeValue(value, comment, colors) {
+    const text = value.trim();
+    if (!text)
+        return value;
+    if (comment && /opaque/i.test(comment)) {
+        return color(value, colors.opaque);
+    }
+    if (comment && /(Indexer|Sig|Sigs|Signature)/.test(comment)) {
+        return color(value, colors.signature);
+    }
+    if (comment && /(Group|count=|counter)/.test(comment)) {
+        return color(value, colors.group);
+    }
+    if (comment && /SERDER/.test(comment)) {
+        return color(value, colors.body);
+    }
+    if (/^[\[{]/.test(text)) {
+        return color(value, colors.body);
+    }
+    if (/^-[A-Za-z0-9_-]+$/.test(text)) {
+        return color(value, colors.counter);
+    }
+    return value;
+}
+function colorizeLine(line, colors) {
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("#")) {
+        return color(line, colors.comment);
+    }
+    const idx = line.indexOf(COMMENT_DELIM);
+    if (idx === -1) {
+        return colorizeValue(line, null, colors);
+    }
+    const value = line.slice(0, idx);
+    const comment = line.slice(idx + COMMENT_DELIM.length);
+    const valueTinted = colorizeValue(value, comment, colors);
+    const commentTinted = colorizeComment(comment, colors);
+    return `${valueTinted}${COMMENT_DELIM}${commentTinted}`;
+}
+/**
+ * Apply ANSI styling for CLI-only CESR annotation display.
+ * This is intentionally presentation-only and must not alter persisted output.
+ */
+export function colorizeAnnotatedOutput(annotated) {
+    const colors = toAnsiColors(readUserColorConfig());
+    const lines = annotated.split("\n");
+    const out = [];
+    let inPrettyJsonBody = false;
+    // support colorizing lines even with --pretty arg
+    for (const line of lines) {
+        const idx = line.indexOf(COMMENT_DELIM);
+        const value = idx === -1 ? line : line.slice(0, idx);
+        const comment = idx === -1 ? null : line.slice(idx + COMMENT_DELIM.length);
+        const trimmed = value.trim();
+        if (comment && /SERDER/.test(comment)) {
+            if (trimmed === "}" || trimmed === "]") {
+                const valueTinted = color(value, colors.body);
+                const commentTinted = colorizeComment(comment, colors);
+                out.push(`${valueTinted}${COMMENT_DELIM}${commentTinted}`);
+                inPrettyJsonBody = false;
+                continue;
+            }
+            out.push(colorizeLine(line, colors));
+            inPrettyJsonBody = false;
+            continue;
+        }
+        if (inPrettyJsonBody && idx === -1) {
+            out.push(color(line, colors.body));
+            continue;
+        }
+        if (idx === -1 && (trimmed === "{" || trimmed === "[")) {
+            inPrettyJsonBody = true;
+            out.push(color(line, colors.body));
+            continue;
+        }
+        out.push(colorizeLine(line, colors));
+    }
+    return out.join("\n");
+}

package/esm/app/cli/annotate.js

@@ -1,13 +1,19 @@
 import * as dntShim from "../../_dnt.shims.js";
 import { annotate } from "cesr-ts";
+import { colorizeAnnotatedOutput } from "./annotate-color.js";
 const TEXT_DECODER = new TextDecoder();
+/**
+ * Reads bytes from stdin in chunks of 64KB and returns them as a single Uint8Array
+ * @returns All bytes read from stdin
+ */
 function readAllStdinSync() {
     const chunks = [];
     let total = 0;
     while (true) {
-        const chunk = new Uint8Array(64 * 1024);
-        const read = dntShim.Deno.stdin.readSync(chunk);
+        const chunk = new Uint8Array(64 * 1024); // 64KB chunk size
+        const read = dntShim.Deno.stdin.readSync(chunk); // reads up to 64KB chunk, returns num bytes
         if (read === null) {
+            // read until EOF (null)
             break;
         }
         const used = chunk.subarray(0, read);
@@ -29,6 +35,7 @@ export function* annotateCommand(args) {
         outPath: args.outPath,
         qb2: args.qb2,
         pretty: args.pretty,
+        colored: args.colored,
     };
     const inputBytes = options.inPath
         ? dntShim.Deno.readFileSync(options.inPath)
@@ -43,5 +50,8 @@ export function* annotateCommand(args) {
         dntShim.Deno.writeTextFileSync(options.outPath, annotated);
         return;
     }
-    console.log(annotated);
+    const output = options.colored
+        ? colorizeAnnotatedOutput(annotated)
+        : annotated;
+    console.log(output);
 }

package/esm/app/cli/benchmark.js

@@ -0,0 +1,210 @@
+import * as dntShim from "../../_dnt.shims.js";
+import { createParser } from "cesr-ts";
+/**
+ * Synchronously consume stdin for CLI benchmark mode.
+ *
+ * Maintainer note:
+ * - Synchronous read keeps CLI command implementation simple and deterministic.
+ * - This function should remain isolated; parser benchmark internals themselves
+ *   are IO-agnostic.
+ */
+function readAllStdinSync() {
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const chunk = new Uint8Array(64 * 1024);
+        const read = dntShim.Deno.stdin.readSync(chunk);
+        if (read === null) {
+            break;
+        }
+        const used = chunk.subarray(0, read);
+        chunks.push(used);
+        total += read;
+    }
+    const output = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return output;
+}
+/**
+ * Validate positive integer options with explicit field-scoped errors.
+ */
+function asPositiveInteger(value, fallback, fieldName) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`${fieldName} must be a positive integer`);
+    }
+    return value;
+}
+/**
+ * Validate non-negative integer options with explicit field-scoped errors.
+ */
+function asNonNegativeInteger(value, fallback, fieldName) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+        throw new Error(`${fieldName} must be a non-negative integer`);
+    }
+    return value;
+}
+/**
+ * Normalize optional chunk sizing into a legal parse feed shape.
+ */
+function normalizeChunkSize(chunkSize, inputLength) {
+    if (chunkSize <= 0 || chunkSize >= inputLength) {
+        return inputLength;
+    }
+    return chunkSize;
+}
+/**
+ * Build ordered chunk views over the input stream.
+ *
+ * Invariant:
+ * - uses `subarray` so benchmark execution does not add avoidable copy overhead.
+ */
+function createChunks(input, chunkSize) {
+    if (chunkSize >= input.length) {
+        return [input];
+    }
+    const chunks = [];
+    for (let offset = 0; offset < input.length; offset += chunkSize) {
+        chunks.push(input.subarray(offset, Math.min(offset + chunkSize, input.length)));
+    }
+    return chunks;
+}
+/**
+ * Execute one complete parser pass and aggregate frame/error events.
+ */
+function parseStreamOnce(input, chunkSize, parserOptions) {
+    const parser = createParser(parserOptions);
+    let frameCount = 0;
+    let errorCount = 0;
+    for (const chunk of createChunks(input, chunkSize)) {
+        for (const event of parser.feed(chunk)) {
+            if (event.type === "frame") {
+                frameCount++;
+            }
+            else {
+                errorCount++;
+            }
+        }
+    }
+    for (const event of parser.flush()) {
+        if (event.type === "frame") {
+            frameCount++;
+        }
+        else {
+            errorCount++;
+        }
+    }
+    return { frameCount, errorCount };
+}
+/**
+ * Run timed parser benchmark loop for `tufa benchmark cesr`.
+ *
+ * Boundary contract:
+ * - warmup runs are excluded from timing.
+ * - correctness remains first: parse errors fail the benchmark unless
+ *   explicitly allowed.
+ */
+function benchmarkParser(input, options) {
+    if (input.length === 0) {
+        throw new Error("Benchmark input stream must not be empty");
+    }
+    const iterations = asPositiveInteger(options.iterations, 50, "iterations");
+    const warmupIterations = asNonNegativeInteger(options.warmupIterations, 5, "warmup");
+    const parsedChunkSize = asNonNegativeInteger(options.chunkSize, 0, "chunkSize");
+    const chunkSize = normalizeChunkSize(parsedChunkSize, input.length);
+    const failOnParseError = !(options.allowErrors ?? false);
+    const parserOptions = {
+        framed: options.framed ?? false,
+        attachmentDispatchMode: options.compat ? "compat" : "strict",
+    };
+    for (let i = 0; i < warmupIterations; i++) {
+        parseStreamOnce(input, chunkSize, parserOptions);
+    }
+    let totalFrames = 0;
+    let totalErrors = 0;
+    const startMs = performance.now();
+    for (let i = 0; i < iterations; i++) {
+        const summary = parseStreamOnce(input, chunkSize, parserOptions);
+        totalFrames += summary.frameCount;
+        totalErrors += summary.errorCount;
+        if (failOnParseError && summary.errorCount > 0) {
+            throw new Error(`Benchmark run produced parse errors (run=${i + 1}, errorCount=${summary.errorCount})`);
+        }
+    }
+    const elapsedMs = Math.max(performance.now() - startMs, Number.EPSILON);
+    const throughputMiBPerSec = ((input.length * iterations * 1000) / elapsedMs) /
+        (1024 * 1024);
+    const framesPerSec = (totalFrames * 1000) / elapsedMs;
+    return {
+        iterations,
+        warmupIterations,
+        bytesPerIteration: input.length,
+        chunkSize,
+        totalFrames,
+        totalErrors,
+        elapsedMs,
+        avgIterationMs: elapsedMs / iterations,
+        throughputMiBPerSec,
+        framesPerSec,
+    };
+}
+/**
+ * Render maintainer-oriented benchmark output for terminal use.
+ */
+function formatBenchmarkText(sourceLabel, result) {
+    const chunkLabel = result.chunkSize === result.bytesPerIteration
+        ? "full stream"
+        : `${result.chunkSize} bytes`;
+    return [
+        "CESR parser benchmark",
+        `source: ${sourceLabel}`,
+        `iterations: ${result.iterations} (warmup: ${result.warmupIterations})`,
+        `input bytes/iteration: ${result.bytesPerIteration}`,
+        `chunk size: ${chunkLabel}`,
+        `frames/iteration: ${(result.totalFrames / result.iterations).toFixed(2)}`,
+        `errors/iteration: ${(result.totalErrors / result.iterations).toFixed(2)}`,
+        `avg iteration: ${result.avgIterationMs.toFixed(3)} ms`,
+        `throughput: ${result.throughputMiBPerSec.toFixed(3)} MiB/s`,
+        `frame rate: ${result.framesPerSec.toFixed(2)} frames/s`,
+    ].join("\n");
+}
+// deno-lint-ignore require-yield
+/**
+ * Effection command handler for `tufa benchmark cesr`.
+ *
+ * Responsibility boundary:
+ * - parse command options from dispatch args,
+ * - read stream input from file/stdin,
+ * - execute benchmark and emit one result payload (text or JSON).
+ */
+export function* benchmarkCommand(args) {
+    const options = {
+        inPath: args.inPath,
+        iterations: args.iterations,
+        warmupIterations: args.warmupIterations,
+        chunkSize: args.chunkSize,
+        framed: args.framed,
+        compat: args.compat,
+        allowErrors: args.allowErrors,
+        json: args.json,
+    };
+    const sourceLabel = options.inPath ? options.inPath : "stdin";
+    const inputBytes = options.inPath
+        ? dntShim.Deno.readFileSync(options.inPath)
+        : readAllStdinSync();
+    const result = benchmarkParser(inputBytes, options);
+    if (options.json) {
+        console.log(JSON.stringify({ source: sourceLabel, ...result }));
+        return;
+    }
+    console.log(formatBenchmarkText(sourceLabel, result));
+}