@noeos/verification-engine-cli 0.0.0

package/dist/esm/io/json-input.js

@@ -0,0 +1,249 @@
+// SPDX-License-Identifier: Apache-2.0
+import { Buffer } from "node:buffer";
+export class CliInputError extends Error {
+    code;
+    line;
+    constructor(code, line) {
+        super(code);
+        this.code = code;
+        this.line = line;
+        this.name = "CliInputError";
+    }
+}
+export function parseJsonDocument(text, limits) {
+    if (text.codePointAt(0) === 0xfeff)
+        throw new CliInputError("UTF8_INVALID");
+    if (Buffer.byteLength(text, "utf8") > limits.maxBytes) {
+        throw new CliInputError("INPUT_LIMIT_EXCEEDED");
+    }
+    const scanner = new JsonStructureScanner(text, limits);
+    scanner.scan();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new CliInputError("JSON_SYNTAX_INVALID");
+    }
+}
+export function decodeUtf8(bytes) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new CliInputError("UTF8_INVALID");
+    }
+}
+export async function* parseNdjson(chunks, limits) {
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    let pending = "";
+    let line = 0;
+    let sawInput = false;
+    try {
+        for await (const chunk of chunks) {
+            /* Node's native V8 report loses this assignment in async-generator resumes. */
+            /* node:coverage ignore next */
+            sawInput = true;
+            pending += decoder.decode(chunk, { stream: true });
+            let newline = pending.indexOf("\n");
+            while (newline >= 0) {
+                /* c8 ignore next -- covered by the NDJSON conformance tests; V8 attributes the slice to the loop header. */
+                const rawLine = pending.slice(0, newline);
+                pending = pending.slice(newline + 1);
+                line += 1;
+                const text = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+                /* Covered by the empty-line conformance test. */
+                /* node:coverage ignore next */
+                if (text.length === 0)
+                    throw new CliInputError("NDJSON_LINE_EMPTY", line);
+                if (Buffer.byteLength(text, "utf8") > limits.maxBytes) {
+                    throw new CliInputError("NDJSON_LINE_TOO_LARGE", line);
+                }
+                try {
+                    yield parseJsonDocument(text, limits);
+                }
+                catch (error) {
+                    if (error instanceof CliInputError) {
+                        throw new CliInputError(error.code, line);
+                    }
+                    throw new CliInputError("JSON_SYNTAX_INVALID", line);
+                }
+                /* Covered by the multi-line conformance test. */
+                /* node:coverage ignore next */
+                newline = pending.indexOf("\n");
+            }
+            /* Covered by the unterminated-line limit test. */
+            /* node:coverage ignore next */
+            if (Buffer.byteLength(pending, "utf8") > limits.maxBytes) {
+                throw new CliInputError("NDJSON_LINE_TOO_LARGE", line + 1);
+            }
+        }
+        pending += decoder.decode();
+    }
+    catch (error) {
+        /* Covered by the invalid UTF-8 conformance test. */
+        /* node:coverage ignore next */
+        if (error instanceof TypeError)
+            throw new CliInputError("UTF8_INVALID", line + 1);
+        throw error;
+    }
+    if (pending.length > 0) {
+        line += 1;
+        /* Covered by the trailing-line limit test. */
+        /* node:coverage ignore next */
+        if (Buffer.byteLength(pending, "utf8") > limits.maxBytes) {
+            throw new CliInputError("NDJSON_LINE_TOO_LARGE", line);
+        }
+        try {
+            yield parseJsonDocument(pending, limits);
+        }
+        catch (error) {
+            if (error instanceof CliInputError)
+                throw new CliInputError(error.code, line);
+            throw new CliInputError("JSON_SYNTAX_INVALID", line);
+        }
+    }
+    else if (!sawInput) {
+        return;
+    }
+}
+class JsonStructureScanner {
+    text;
+    limits;
+    position = 0;
+    constructor(text, limits) {
+        this.text = text;
+        this.limits = limits;
+    }
+    scan() {
+        this.skipWhitespace();
+        this.scanValue(0);
+        this.skipWhitespace();
+        if (this.position !== this.text.length)
+            throw new CliInputError("JSON_SYNTAX_INVALID");
+    }
+    scanValue(depth) {
+        if (depth > this.limits.maxDepth)
+            throw new CliInputError("INPUT_LIMIT_EXCEEDED");
+        const character = this.text[this.position];
+        if (character === "{") {
+            this.scanObject(depth + 1);
+            return;
+        }
+        if (character === "[") {
+            this.scanArray(depth + 1);
+            return;
+        }
+        if (character === '"') {
+            this.scanString();
+            return;
+        }
+        this.scanPrimitive();
+    }
+    scanObject(depth) {
+        this.position += 1;
+        this.skipWhitespace();
+        const keys = new Set();
+        if (this.text[this.position] === "}") {
+            this.position += 1;
+            return;
+        }
+        /* V8 does not attribute the first async scanner iteration consistently. */
+        /* node:coverage ignore next */
+        let count = 0;
+        for (;;) {
+            if (this.text[this.position] !== '"')
+                throw new CliInputError("JSON_SYNTAX_INVALID");
+            const start = this.position;
+            this.scanString();
+            let key;
+            try {
+                key = JSON.parse(this.text.slice(start, this.position));
+            }
+            catch {
+                throw new CliInputError("JSON_SYNTAX_INVALID");
+            }
+            if (typeof key !== "string")
+                throw new CliInputError("JSON_SYNTAX_INVALID");
+            if (keys.has(key))
+                throw new CliInputError("JSON_DUPLICATE_KEY");
+            keys.add(key);
+            count += 1;
+            if (count > this.limits.maxObjectProperties)
+                throw new CliInputError("INPUT_LIMIT_EXCEEDED");
+            this.skipWhitespace();
+            if (this.text[this.position] !== ":")
+                throw new CliInputError("JSON_SYNTAX_INVALID");
+            this.position += 1;
+            this.skipWhitespace();
+            this.scanValue(depth);
+            this.skipWhitespace();
+            const separator = this.text[this.position];
+            if (separator === "}") {
+                this.position += 1;
+                return;
+            }
+            if (separator !== ",")
+                throw new CliInputError("JSON_SYNTAX_INVALID");
+            this.position += 1;
+            this.skipWhitespace();
+        }
+    }
+    scanArray(depth) {
+        this.position += 1;
+        this.skipWhitespace();
+        if (this.text[this.position] === "]") {
+            this.position += 1;
+            return;
+        }
+        let count = 0;
+        for (;;) {
+            count += 1;
+            if (count > this.limits.maxArrayElements)
+                throw new CliInputError("INPUT_LIMIT_EXCEEDED");
+            this.scanValue(depth);
+            this.skipWhitespace();
+            const separator = this.text[this.position];
+            if (separator === "]") {
+                this.position += 1;
+                return;
+            }
+            if (separator !== ",")
+                throw new CliInputError("JSON_SYNTAX_INVALID");
+            this.position += 1;
+            this.skipWhitespace();
+        }
+    }
+    scanString() {
+        this.position += 1;
+        while (this.position < this.text.length) {
+            const character = this.text[this.position];
+            if (character === '"') {
+                this.position += 1;
+                return;
+            }
+            if (character === "\\") {
+                this.position += 2;
+            }
+            else {
+                if (character !== undefined && character < " ") {
+                    throw new CliInputError("JSON_SYNTAX_INVALID");
+                }
+                this.position += 1;
+            }
+        }
+        throw new CliInputError("JSON_SYNTAX_INVALID");
+    }
+    scanPrimitive() {
+        const start = this.position;
+        while (this.position < this.text.length && !/[\s,\]}]/u.test(this.text[this.position] ?? "")) {
+            this.position += 1;
+        }
+        if (start === this.position)
+            throw new CliInputError("JSON_SYNTAX_INVALID");
+    }
+    skipWhitespace() {
+        while (this.position < this.text.length && /\s/u.test(this.text[this.position] ?? "")) {
+            this.position += 1;
+        }
+    }
+}

package/dist/esm/io/output.js

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: Apache-2.0
+import { open, rename, rm, lstat } from "node:fs/promises";
+import { resolve } from "node:path";
+export async function openLineWriter(format, options, stdout) {
+    if (options.path === undefined) {
+        return new StreamLineWriter(format, stdout);
+    }
+    const outputPath = resolve(options.path);
+    await ensureOutputPath(outputPath, options.force);
+    const target = options.atomic ? await createTemporaryPath(outputPath) : outputPath;
+    const handle = await open(target, options.atomic ? "wx" : options.force ? "w" : "wx", 0o600);
+    return new FileLineWriter(format, handle, outputPath, target, options.atomic);
+}
+class StreamLineWriter {
+    format;
+    stream;
+    constructor(format, stream) {
+        this.format = format;
+        this.stream = stream;
+    }
+    async write(value) {
+        const text = formatValue(this.format, value);
+        if (!this.stream.write(text)) {
+            await onceDrain(this.stream);
+        }
+    }
+    async close() {
+        // stdout/stderr belong to the host process and must never be closed by the CLI.
+    }
+}
+class FileLineWriter {
+    format;
+    handle;
+    outputPath;
+    target;
+    atomic;
+    manifestPath;
+    constructor(format, handle, outputPath, target, atomic, manifestPath = `${outputPath}.manifest.json`) {
+        this.format = format;
+        this.handle = handle;
+        this.outputPath = outputPath;
+        this.target = target;
+        this.atomic = atomic;
+        this.manifestPath = manifestPath;
+    }
+    async write(value) {
+        await this.handle.write(formatValue(this.format, value), undefined, "utf8");
+    }
+    async close(success) {
+        try {
+            if (success) {
+                await this.handle.sync();
+                await this.handle.close();
+                if (this.atomic)
+                    await rename(this.target, this.outputPath);
+                else
+                    await writeCompletionManifest(this.manifestPath, true);
+            }
+            else {
+                await this.handle.close();
+                if (this.atomic)
+                    await rm(this.target, { force: true });
+                else
+                    await writeCompletionManifest(this.manifestPath, false);
+            }
+            /* Defensive cleanup runs only after a second I/O failure. */
+            /* node:coverage disable */
+        }
+        catch (error) {
+            try {
+                await this.handle.close();
+            }
+            catch {
+                // Preserve the original output failure.
+            }
+            if (!this.atomic) {
+                try {
+                    await writeCompletionManifest(this.manifestPath, false);
+                }
+                catch {
+                    // Preserve the original output failure.
+                }
+            }
+            throw error;
+        }
+        /* node:coverage enable */
+    }
+}
+function formatValue(format, value) {
+    if (format === "human")
+        return `${formatHuman(value)}\n`;
+    const serialized = JSON.stringify(value);
+    if (typeof serialized !== "string")
+        throw new Error("output serialization failed");
+    return `${serialized}\n`;
+}
+function formatHuman(value) {
+    if (typeof value !== "object" || value === null)
+        return String(value);
+    const record = value;
+    const operationValue = record.operation;
+    const statusValue = record.status;
+    const okValue = record.ok;
+    const operation = typeof operationValue === "string" ? operationValue : "operation";
+    const status = typeof statusValue === "string" ? statusValue : okValue === true ? "ok" : "error";
+    return `${operation}: ${status}`;
+}
+async function ensureOutputPath(path, force) {
+    try {
+        const current = await lstat(path);
+        if (current.isSymbolicLink() || !current.isFile())
+            throw new Error("OUTPUT_EXISTS");
+        if (!force)
+            throw new Error("OUTPUT_EXISTS");
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return;
+        }
+        throw error;
+    }
+}
+async function createTemporaryPath(path) {
+    const base = `${path}.noeos-tmp-${String(process.pid)}`;
+    for (let attempt = 0; attempt < 32; attempt += 1) {
+        const candidate = `${base}-${String(attempt)}`;
+        try {
+            await lstat(candidate);
+        }
+        catch (error) {
+            if (isMissing(error))
+                return candidate;
+            throw error;
+        }
+    }
+    /* Exhausting all 32 private temporary names is an operational collision. */
+    /* node:coverage ignore next */
+    throw new Error("IO_WRITE_FAILED");
+}
+async function writeCompletionManifest(path, complete) {
+    const target = await createTemporaryPath(path);
+    const handle = await open(target, "wx", 0o600);
+    try {
+        const value = JSON.stringify({ version: 1, complete, format: "ndjson" });
+        await handle.write(`${value}\n`, undefined, "utf8");
+        await handle.sync();
+        await handle.close();
+        await rename(target, path);
+    }
+    catch (error) {
+        try {
+            await handle.close();
+        }
+        catch {
+            // Preserve the original manifest failure.
+        }
+        await rm(target, { force: true });
+        throw error;
+    }
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function onceDrain(stream) {
+    return new Promise((resolvePromise, reject) => {
+        const onDrain = () => {
+            stream.off("error", onError);
+            resolvePromise();
+        };
+        const onError = (error) => {
+            stream.off("drain", onDrain);
+            reject(error);
+        };
+        stream.once("drain", onDrain);
+        stream.once("error", onError);
+    });
+}

package/dist/esm/main.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+import { runCli } from "./cli.js";
+const exitCode = await runCli(process.argv.slice(2), {
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+});
+process.exitCode = exitCode;

package/dist/types/cli.d.ts

@@ -0,0 +1,10 @@
+import type { Writable } from "node:stream";
+interface CliStreams {
+    readonly stdin: AsyncIterable<Uint8Array>;
+    readonly stdout: Writable & {
+        readonly isTTY?: boolean;
+    };
+    readonly stderr: Writable;
+}
+export declare function runCli(argv: readonly string[], streams: CliStreams): Promise<number>;
+export {};

package/dist/types/io/json-input.d.ts

@@ -0,0 +1,14 @@
+export interface JsonInputLimits {
+    readonly maxBytes: number;
+    readonly maxDepth: number;
+    readonly maxObjectProperties: number;
+    readonly maxArrayElements: number;
+}
+export declare class CliInputError extends Error {
+    readonly code: "JSON_SYNTAX_INVALID" | "JSON_DUPLICATE_KEY" | "INPUT_LIMIT_EXCEEDED" | "NDJSON_LINE_EMPTY" | "NDJSON_LINE_TOO_LARGE" | "UTF8_INVALID";
+    readonly line?: number | undefined;
+    constructor(code: "JSON_SYNTAX_INVALID" | "JSON_DUPLICATE_KEY" | "INPUT_LIMIT_EXCEEDED" | "NDJSON_LINE_EMPTY" | "NDJSON_LINE_TOO_LARGE" | "UTF8_INVALID", line?: number | undefined);
+}
+export declare function parseJsonDocument(text: string, limits: JsonInputLimits): unknown;
+export declare function decodeUtf8(bytes: Uint8Array): string;
+export declare function parseNdjson(chunks: AsyncIterable<Uint8Array>, limits: JsonInputLimits): AsyncGenerator<unknown, void, undefined>;

package/dist/types/io/output.d.ts

@@ -0,0 +1,12 @@
+import type { Writable } from "node:stream";
+export type OutputFormat = "json" | "ndjson" | "human";
+export interface OutputOptions {
+    readonly path?: string;
+    readonly force: boolean;
+    readonly atomic: boolean;
+}
+export interface LineWriter {
+    write(value: unknown): Promise<void>;
+    close(success: boolean): Promise<void>;
+}
+export declare function openLineWriter(format: OutputFormat, options: OutputOptions, stdout: Writable): Promise<LineWriter>;

package/dist/types/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@noeos/verification-engine-cli",
+  "version": "0.0.0",
+  "private": false,
+  "description": "Command-line interface for the Noeos verification engine.",
+  "license": "Apache-2.0",
+  "author": "Noeos contributors",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.14.0 <23 || >=24.0.0 <25"
+  },
+  "main": "./dist/esm/main.js",
+  "bin": {
+    "noeos-ve": "./dist/esm/main.js"
+  },
+  "types": "./dist/types/main.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/main.d.ts",
+      "import": "./dist/esm/main.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@noeos/verification-engine": "0.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noeos/verification-engine.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/noeos/verification-engine/issues"
+  },
+  "homepage": "https://github.com/noeos/verification-engine#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  }
+}