keri-ts 0.2.3 → 0.3.0

package/README.md

@@ -1,25 +1,74 @@
 # 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
 ```
 
-## Deno tasks (package-local)
+## 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
+```
+
+- `--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
+
+## 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
 ```

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.js

@@ -1,13 +1,18 @@
 import * as dntShim from "../../_dnt.shims.js";
 import { annotate } from "cesr-ts";
 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);

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));
+}

package/esm/app/cli/cli.js

@@ -1,9 +1,8 @@
 import * as dntShim from "../../_dnt.shims.js";
 import { Command } from "commander";
 import { AppError } from "../../core/errors.js";
-import { createCoreCommandHandlers, registerCoreCommands, } from "./command-definitions.js";
-import { createStubCommandHandlers, isStubCommandsEnabled, registerStubCommands, } from "./stub-commands.js";
 import { DISPLAY_VERSION } from "../version.js";
+import { createCmdHandlers, registerCmds } from "./command-definitions.js";
 /**
  * Create the CLI program with action handlers that signal command execution.
  * Command declaration is delegated to focused command modules.
@@ -13,68 +12,67 @@ function createCLIProgram(onCommand) {
     program.name("tufa").version(DISPLAY_VERSION).description("Trust Utilities for Agents CLI");
     // Prevent Commander from exiting automatically so we can run Effection operations
     program.exitOverride();
-    registerCoreCommands(program, onCommand);
-    if (isStubCommandsEnabled()) {
-        registerStubCommands(program, onCommand);
-    }
+    registerCmds(program, onCommand);
     return program;
 }
+function parseCLIArgs(program, args) {
+    // Commander expects full argv or args array.
+    // In Deno, Deno.args gives us the arguments without executable info.
+    const argsToParse = args.length > 0 ? args : dntShim.Deno.args;
+    program.parse(argsToParse, { from: "user" });
+}
+function isCommanderExitError(error) {
+    return !!(error && typeof error === "object" && "code" in error);
+}
+function isExpectedCommanderExit(code) {
+    return (code === "commander.help" ||
+        code === "commander.helpDisplayed" ||
+        code === "commander.version" ||
+        code === "commander.unknownCommand" ||
+        code === "commander.missingArgument");
+}
+function handleParseError(error) {
+    if (isCommanderExitError(error) && isExpectedCommanderExit(error.code)) {
+        // Commander already printed any relevant help/error output.
+        return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof AppError && error.context) {
+        console.error(`Error: ${message}`, error.context);
+    }
+    else {
+        console.error(`Error: ${message}`);
+    }
+    throw error;
+}
+function* runCmd(selection, commandHandlers) {
+    if (!selection) {
+        return;
+    }
+    const handler = commandHandlers.get(selection.name);
+    if (!handler) {
+        return;
+    }
+    // Execute command operation within Effection's structured concurrency.
+    yield* handler(selection.args);
+}
 /**
  * Main CLI operation - runs within Effection's structured concurrency
  * This is the outermost runtime, not JavaScript's event loop
  */
 export function* tufa(args = []) {
-    const executionContext = {};
-    const commandHandlers = createCoreCommandHandlers();
-    if (isStubCommandsEnabled()) {
-        for (const [key, handler] of createStubCommandHandlers()) {
-            commandHandlers.set(key, handler);
-        }
-    }
+    const dispatch = {};
+    const commandHandlers = createCmdHandlers();
     // Use Commander.js for all command parsing
     const program = createCLIProgram((next) => {
-        executionContext.selection = next;
+        dispatch.selection = next;
     });
     try {
-        // Parse arguments - Commander expects full argv or args array
-        // In Deno, Deno.args gives us the arguments without the executable info
-        const argsToParse = args.length > 0 ? args : dntShim.Deno.args;
-        program.parse(argsToParse, { from: "user" });
+        parseCLIArgs(program, args);
     }
     catch (error) {
-        // Handle Commander-specific errors
-        if (error && typeof error === "object" && "code" in error) {
-            const commanderError = error;
-            // Help was requested - Commander already printed it, just return
-            if (commanderError.code === "commander.help" ||
-                commanderError.code === "commander.helpDisplayed" ||
-                commanderError.code === "commander.version") {
-                return;
-            }
-            // Unknown command or other parsing errors - Commander already printed the error
-            if (commanderError.code === "commander.unknownCommand" ||
-                commanderError.code === "commander.missingArgument") {
-                // Commander already printed the error message, just exit gracefully
-                return;
-            }
-        }
-        // For other errors, log and rethrow
-        const message = error instanceof Error ? error.message : String(error);
-        if (error instanceof AppError && error.context) {
-            console.error(`Error: ${message}`, error.context);
-        }
-        else {
-            console.error(`Error: ${message}`);
-        }
-        throw error;
-    }
-    // Execute the appropriate command operation based on context
-    const selected = executionContext.selection;
-    if (selected) {
-        const handler = commandHandlers.get(selected.name);
-        if (handler) {
-            // Execute the command operation within Effection's structured concurrency
-            yield* handler(selected.args);
-        }
+        handleParseError(error);
+        return;
     }
+    yield* runCmd(dispatch.selection, commandHandlers);
 }