keri-ts 0.10.0 → 0.10.2

package/esm/keri/npm/src/app/cli/annotate.js

@@ -0,0 +1,99 @@
+import * as dntShim from "../../_dnt.shims.js";
+import { annotate } from "cesr-ts";
+import { spawn, withResolvers } from "effection";
+import { colorizeAnnotatedOutput } from "./annotate-color.js";
+const TEXT_DECODER = new TextDecoder();
+const STDIN_CHUNK_SIZE = 64 * 1024;
+const WOULD_BLOCK_RETRY_DELAY_MS = 5;
+/**
+ * Reads bytes from stdin in chunks and returns them as a single Uint8Array.
+ * Uses async reads so Node shim stdin pipes can recover from transient EAGAIN.
+ * @returns All bytes read from stdin
+ */
+async function readAllStdinAsync() {
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const chunk = new Uint8Array(STDIN_CHUNK_SIZE);
+        let read;
+        try {
+            read = await dntShim.Deno.stdin.read(chunk);
+        }
+        catch (error) {
+            if (isWouldBlockError(error)) {
+                await sleep(WOULD_BLOCK_RETRY_DELAY_MS);
+                continue;
+            }
+            throw error;
+        }
+        if (read === null)
+            break;
+        if (read === 0) {
+            await sleep(WOULD_BLOCK_RETRY_DELAY_MS);
+            continue;
+        }
+        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;
+}
+function isWouldBlockError(error) {
+    if (error instanceof dntShim.Deno.errors.WouldBlock)
+        return true;
+    if (!(error && typeof error === "object" && "code" in error))
+        return false;
+    const code = error.code;
+    return code === "EAGAIN" || code === "EWOULDBLOCK";
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function* readAllStdinOp() {
+    const { operation, resolve, reject } = withResolvers();
+    const task = yield* spawn(function* () {
+        readAllStdinAsync()
+            .then(resolve)
+            .catch((error) => reject(error instanceof Error ? error : new Error(String(error))));
+    });
+    yield* task;
+    return yield* operation;
+}
+/**
+ * CLI command wrapper for CESR annotation.
+ *
+ * This keeps `tufa annotate` aligned with the lower-level CESR annotator while
+ * handling runtime-specific stdin/stdout and optional terminal colorization.
+ */
+export function* annotateCommand(args) {
+    const options = {
+        inPath: args.inPath,
+        outPath: args.outPath,
+        qb2: args.qb2,
+        pretty: args.pretty,
+        colored: args.colored,
+    };
+    const inputBytes = options.inPath
+        ? dntShim.Deno.readFileSync(options.inPath)
+        : yield* readAllStdinOp();
+    const annotated = options.qb2
+        ? annotate(inputBytes, { domainHint: "bny", pretty: options.pretty })
+        : annotate(TEXT_DECODER.decode(inputBytes), {
+            domainHint: "txt",
+            pretty: options.pretty,
+        });
+    if (options.outPath) {
+        dntShim.Deno.writeTextFileSync(options.outPath, annotated);
+        return;
+    }
+    const output = options.colored
+        ? colorizeAnnotatedOutput(annotated)
+        : annotated;
+    console.log(output);
+}

package/esm/keri/npm/src/app/cli/benchmark.js

@@ -0,0 +1,209 @@
+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");
+}
+/**
+ * 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/keri/npm/src/app/cli/common/parsing.js

@@ -0,0 +1,215 @@
+import * as dntShim from "../../../_dnt.shims.js";
+import { ValidationError } from "../../../core/index.js";
+/**
+ * Normalize one threshold input from CLI/file JSON into the internal
+ * `ThresholdSith` representation.
+ *
+ * Accepted forms intentionally match the operator-facing KLI shapes:
+ * numeric, hex-string, weighted JSON-array string, or structured array data.
+ */
+function normalizeThresholdOption(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === "number") {
+        if (!Number.isInteger(value) || value < 0) {
+            throw new Error(`Invalid numeric threshold ${value}`);
+        }
+        return value.toString(16);
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed.length === 0) {
+            return undefined;
+        }
+        if (trimmed.startsWith("[")) {
+            return JSON.parse(trimmed);
+        }
+        return trimmed;
+    }
+    if (Array.isArray(value)) {
+        return structuredClone(value);
+    }
+    throw new Error(`Unsupported threshold option type ${typeof value}`);
+}
+/**
+ * Parse one CLI/file threshold input into semantic numeric or weighted form.
+ *
+ * This is a thin public seam over `normalizeThresholdOption(...)` so command
+ * modules do not duplicate threshold coercion rules.
+ */
+export function parseThresholdOption(value) {
+    return normalizeThresholdOption(value);
+}
+/**
+ * Parse inline JSON values or `@file` references used by CLI `--data` flags.
+ *
+ * KLI correspondence:
+ * - each `--data` value is interpreted independently
+ * - `@file` values must contain JSON that is inserted as one committed item
+ */
+export function parseDataItems(items) {
+    if (!items || items.length === 0)
+        return [];
+    const out = [];
+    for (const item of items) {
+        if (item.startsWith("@")) {
+            const file = item.slice(1);
+            const text = dntShim.Deno.readTextFileSync(file);
+            out.push(JSON.parse(text));
+            continue;
+        }
+        out.push(JSON.parse(item));
+    }
+    return out;
+}
+/** Load and parse one JSON document from disk without extra schema coercion. */
+function loadJson(path) {
+    return JSON.parse(dntShim.Deno.readTextFileSync(path));
+}
+/** Return true when a string can be losslessly treated as a JSON number literal. */
+function isNumber(value) {
+    if (value.trim().length === 0) {
+        return false;
+    }
+    return !Number.isNaN(Number(value));
+}
+/**
+ * Coerce one EXN `key=value` right-hand side like KERIpy's CLI.
+ *
+ * Plain strings stay strings, while obvious JSON scalars/containers are parsed
+ * into structured values when possible.
+ */
+function coerceExnDataValue(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return "";
+    }
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")
+        || trimmed === "true" || trimmed === "false" || trimmed === "null"
+        || isNumber(trimmed)) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return value;
+        }
+    }
+    return value;
+}
+/**
+ * Parse KERIpy-style repeatable EXN `--data` items into one payload object.
+ *
+ * Accepted item shapes:
+ * - `@file.json` containing one JSON object
+ * - one inline JSON object string
+ * - repeatable `key=value` items whose values coerce like KERIpy
+ */
+export function parseExnDataItems(items) {
+    if (!items || items.length === 0) {
+        return {};
+    }
+    const data = {};
+    for (const item of items) {
+        if (item === undefined || item === null) {
+            continue;
+        }
+        const trimmed = item.trim();
+        if (trimmed.length === 0) {
+            continue;
+        }
+        if (trimmed.startsWith("@")) {
+            const loaded = loadJson(trimmed.slice(1));
+            if (!loaded || typeof loaded !== "object" || Array.isArray(loaded)) {
+                throw new Error("@file must contain a JSON object");
+            }
+            Object.assign(data, loaded);
+            continue;
+        }
+        if (trimmed.startsWith("{")) {
+            const loaded = JSON.parse(trimmed);
+            if (!loaded || typeof loaded !== "object" || Array.isArray(loaded)) {
+                throw new Error("JSON must be an object");
+            }
+            Object.assign(data, loaded);
+            continue;
+        }
+        if (!trimmed.includes("=")) {
+            throw new Error(`invalid item '${trimmed}', expected key=value, JSON object, or @file.json`);
+        }
+        const [rawKey, ...rest] = trimmed.split("=");
+        const key = rawKey?.trim() ?? "";
+        if (key.length === 0) {
+            throw new Error(`invalid item '${trimmed}', empty key`);
+        }
+        data[key] = coerceExnDataValue(rest.join("="));
+    }
+    return data;
+}
+/**
+ * Load one JSON file of inception options using the CLI file-input contract.
+ *
+ * Threshold fields are normalized during load so later merge code can operate
+ * on one representation regardless of whether the value came from a file or a
+ * direct CLI flag.
+ */
+export function loadInceptFileOptions(path) {
+    const text = dntShim.Deno.readTextFileSync(path);
+    const loaded = JSON.parse(text);
+    return {
+        ...loaded,
+        isith: normalizeThresholdOption(loaded.isith),
+        nsith: normalizeThresholdOption(loaded.nsith),
+    };
+}
+/**
+ * Load one JSON file of rotation options using the CLI file-input contract.
+ *
+ * KLI compatibility notes:
+ * - threshold fields are normalized immediately
+ * - witness collections are filtered down to strings so malformed JSON does
+ *   not propagate surprising non-string values into witness math
+ */
+export function loadRotateFileOptions(path) {
+    const text = dntShim.Deno.readTextFileSync(path);
+    const loaded = JSON.parse(text);
+    return {
+        ...loaded,
+        isith: normalizeThresholdOption(loaded.isith),
+        nsith: normalizeThresholdOption(loaded.nsith),
+        wits: Array.isArray(loaded.wits)
+            ? loaded.wits.filter((value) => typeof value === "string")
+            : loaded.wits,
+        witsCut: Array.isArray(loaded.witsCut)
+            ? loaded.witsCut.filter((value) => typeof value === "string")
+            : loaded.witsCut,
+        witsAdd: Array.isArray(loaded.witsAdd)
+            ? loaded.witsAdd.filter((value) => typeof value === "string")
+            : loaded.witsAdd,
+    };
+}
+/**
+ * Load one required CLI text argument or `@file` reference as UTF-8 bytes.
+ *
+ * This preserves the KLI convention used by `sign` and `verify`: operator
+ * input is always interpreted as text, never raw binary.
+ */
+export function loadTextArgument(text) {
+    const source = text.startsWith("@")
+        ? dntShim.Deno.readTextFileSync(text.slice(1))
+        : text;
+    return new TextEncoder().encode(source);
+}
+/** Require a non-empty string argument (for name, alias, etc.). */
+export function requireText(value, label) {
+    if (!value) {
+        throw new ValidationError(`${label} is required and cannot be empty`);
+    }
+    return value;
+}
+/** Require a non-empty value (void-throwing variant used in several commands). */
+export function requireNonEmpty(value, label) {
+    if (!value) {
+        throw new ValidationError(`${label} is required and cannot be empty.`);
+    }
+}