agent-first-data 0.17.3 → 0.19.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 /**
  * AFDATA CLI helpers — output format parsing, log filter normalization, error building.
  */
-import { Event, jsonError, jsonResult, outputJson, outputYaml, outputPlain, validateProtocolEvent, } from "./format.js";
+import { Event, jsonError, jsonResult, formatJsonValue, formatYamlValue, formatPlainValue, validateProtocolEvent, } from "./format.js";
 /**
  * Parse the --output flag value into an OutputFormat.
  * Throws on unknown values; catch and pass message to buildCliError.
@@ -33,24 +33,28 @@ export class LogFilters {
     }
     /**
      * Check if an event matches the filter set.
-     * Returns false for empty filters, true if "all" or "*" is present,
-     * otherwise checks if event.toLowerCase() starts with any filter.
+     *
+     * An empty filter set returns false (filtering is opt-in). The single
+     * wildcard word "all" returns true ("*" is not special — one wildcard
+     * spelling, not two). Otherwise returns true iff event.toLowerCase() starts
+     * with any filter (prefix match); a mistyped filter simply matches nothing
+     * and silently emits no output.
      *
      * @example
      * const lf = new LogFilters(["query", "error"]);
      * lf.enabled("QueryStarted") // → true (starts with "query")
      * lf.enabled("debug") // → false
      *
-     * const all = new LogFilters([]);
-     * all.enabled("anything") // → false (empty)
+     * const none = new LogFilters([]);
+     * none.enabled("anything") // → false (empty)
      *
-     * const wild = new LogFilters(["*"]);
+     * const wild = new LogFilters(["all"]);
      * wild.enabled("anything") // → true
      */
     enabled(event) {
         if (this.filters.length === 0)
             return false;
-        if (this.filters.includes("all") || this.filters.includes("*"))
+        if (this.filters.includes("all"))
             return true;
         const eventLower = event.toLowerCase();
         for (const filter of this.filters) {
@@ -74,36 +78,130 @@ export function cliParseLogFilters(entries) {
     return new LogFilters(entries);
 }
 /**
- * Dispatch output formatting by OutputFormat, with optional explicit redaction and style.
- * JSON ignores OutputStyle and preserves original keys and values after redaction.
+ * Single public render entry point: dispatch a value or Event to
+ * JSON/YAML/plain text by OutputFormat, with optional explicit redaction and
+ * style. `options.style` (PlainStyle) affects plain (logfmt) output only;
+ * JSON and YAML are structure-preserving and ignore it.
  *
  * @example
- * cliOutput(jsonResult({ ok: true }).build(), "plain") // → "kind=result result.ok=true"
+ * render(jsonResult({ ok: true }).build(), "plain") // → "kind=result result.ok=true"
  */
-export function cliOutput(value, format, options = {}) {
+export function render(value, format, options = {}) {
     const jsonValue = value instanceof Event ? value.toJSON() : value;
     if (format === "yaml")
-        return outputYaml(jsonValue, options);
+        return formatYamlValue(jsonValue, options);
     if (format === "plain")
-        return outputPlain(jsonValue, options);
-    return outputJson(jsonValue, options);
+        return formatPlainValue(jsonValue, options);
+    return formatJsonValue(jsonValue, options);
+}
+/**
+ * Parse an `--output-to` value into an OutputTo: "split" (default), "stdout", or
+ * "stderr". Throws on unknown values; catch and pass the message to
+ * buildCliError.
+ *
+ * @example
+ * parseOutputTo("split") // → "split"
+ * parseOutputTo("both")  // throws Error
+ */
+export function parseOutputTo(value) {
+    if (value === "split" || value === "stdout" || value === "stderr") {
+        return value;
+    }
+    throw new Error(`invalid --output-to '${value}': expected split, stdout, or stderr`);
 }
-/** Stateful emitter for finite structured CLI executions. */
+/** Event writer bound to the process stdout stream. */
+const processStdoutWriter = (line) => {
+    process.stdout.write(line);
+};
+/**
+ * Event writer bound to the process stderr stream. This is the CliEmitter's
+ * blessed diagnostic sink: stderr is sanctioned here, and only here, precisely
+ * because output flows through the emitter rather than an ad-hoc write. The
+ * `stderr-sink` marker is what no_stderr_policy.test.ts allows through.
+ */
+const processStderrWriter = (line) => {
+    process.stderr.write(line); // stderr-sink: CliEmitter diagnostic channel
+};
+/**
+ * Stateful emitter for structured CLI executions.
+ *
+ * Routing follows the consumption mode (OutputTo):
+ *
+ * - Finite one-shot (`CliEmitter.finite` / `finiteWith` /
+ *   `fromOutputTo("split")`): `result` → the primary writer (stdout);
+ *   `error`/`progress`/`log` → the diagnostic writer (stderr). The recommended
+ *   default for a one-shot CLI, so shell capture and pipelines never treat a
+ *   failure as data.
+ * - Event stream (`new CliEmitter(...)` / `CliEmitter.stream` /
+ *   `fromOutputTo("stdout"|"stderr")`): every event, including `error`, goes to
+ *   the single writer, preserving interleaved ordering.
+ */
 export class CliEmitter {
     writer;
     format;
     outputOptions;
     terminalEmitted = false;
     logFieldsProvider;
+    diagnostic;
+    /**
+     * Create an event-stream emitter: every event, including `error`, goes to the
+     * single `writer`. Use CliEmitter.finite for a one-shot command that should
+     * split `result`/`error` across stdout/stderr.
+     */
     constructor(writer, format, outputOptions = {}) {
         this.writer = writer;
         this.format = format;
         this.outputOptions = outputOptions;
     }
+    /**
+     * Create an event-stream emitter: every event goes to `writer`, preserving
+     * interleaved ordering. Pick this when the consumer reads one ordered stream
+     * and branches on `kind`. Alias for the constructor's unified form.
+     */
+    static stream(writer, format, outputOptions = {}) {
+        return new CliEmitter(writer, format, outputOptions);
+    }
+    /**
+     * Create a finite one-shot emitter with explicit sinks: `result` goes to
+     * `resultWriter`, while `error`/`progress`/`log` go to `diagnostic`.
+     */
+    static finiteWith(resultWriter, diagnostic, format, outputOptions = {}) {
+        const emitter = new CliEmitter(resultWriter, format, outputOptions);
+        emitter.diagnostic = diagnostic;
+        return emitter;
+    }
+    /**
+     * Create a finite one-shot emitter wired to the process streams: `result` →
+     * stdout, `error`/`progress`/`log` → stderr. The recommended default for a
+     * one-shot CLI.
+     */
+    static finite(format, outputOptions = {}) {
+        return CliEmitter.finiteWith(processStdoutWriter, processStderrWriter, format, outputOptions);
+    }
+    /**
+     * Build an emitter from a parsed OutputTo selector, wired to the process
+     * streams: "split" is finite mode (`result` → stdout, everything else →
+     * stderr); "stdout"/"stderr" are event-stream mode onto that one stream.
+     */
+    static fromOutputTo(selector, format, outputOptions = {}) {
+        if (selector === "split")
+            return CliEmitter.finite(format, outputOptions);
+        const writer = selector === "stdout" ? processStdoutWriter : processStderrWriter;
+        return CliEmitter.stream(writer, format, outputOptions);
+    }
     withLogFields(provider) {
         this.logFieldsProvider = provider;
         return this;
     }
+    /**
+     * Select the sink for an event by `kind`. Finite mode (a diagnostic sink is
+     * present) keeps `result` on the primary writer (stdout) and routes
+     * `error`/`progress`/`log` to the diagnostic writer (stderr). Event-stream
+     * mode (no diagnostic sink) keeps every event on the single writer.
+     */
+    sinkFor(kind) {
+        return kind !== "result" && this.diagnostic ? this.diagnostic : this.writer;
+    }
     emit(event) {
         const jsonValue = event.toJSON();
         validateProtocolEvent(jsonValue);
@@ -121,7 +219,7 @@ export class CliEmitter {
         else {
             throw new Error(`unsupported event kind ${JSON.stringify(kind)}`);
         }
-        this.writer(`${cliOutput(jsonValue, this.format, this.outputOptions)}\n`);
+        this.sinkFor(kind)(`${render(jsonValue, this.format, this.outputOptions)}\n`);
         if (kind === "result" || kind === "error")
             this.terminalEmitted = true;
     }
@@ -141,14 +239,44 @@ export class CliEmitter {
         else {
             throw new Error(`unsupported event kind ${JSON.stringify(kind)}`);
         }
-        this.writer(`${cliOutput(value, this.format, this.outputOptions)}\n`);
+        this.sinkFor(kind)(`${render(value, this.format, this.outputOptions)}\n`);
         if (kind === "result" || kind === "error")
             this.terminalEmitted = true;
     }
+    static isBrokenPipe(err) {
+        return (typeof err === "object" && err !== null && err.code === "EPIPE");
+    }
+    /**
+     * Emit `event` as the terminal event and resolve the outcome to a process
+     * exit code, so a one-shot CLI need not hand-roll the emit-then-exit dance.
+     *
+     * A successful write returns `successCode`; a broken pipe (the reader hung up)
+     * returns `0`; any other write or validation failure returns `4`. A library
+     * never calls process.exit itself — return this code and let the caller exit.
+     */
+    finish(event, successCode) {
+        try {
+            this.emit(event);
+            return successCode;
+        }
+        catch (err) {
+            return CliEmitter.isBrokenPipe(err) ? 0 : 4;
+        }
+    }
+    /**
+     * Convenience over finish: emit a `result` payload and return `0` on success.
+     *
+     * Errors — simple or rich — go through the builder instead: construct the event
+     * with jsonError(code, message).hint(...)…build() (the builder is the error
+     * "type", so it scales to `retryable`/extra fields) and call finish(event, code).
+     */
+    finishResult(payload) {
+        return this.finish(jsonResult(payload).build(), 0);
+    }
 }
 /** Build a standard CLI version value. */
 export function buildCliVersion(version) {
-    return jsonResult({ version }).build();
+    return jsonResult({ code: "version", version }).build();
 }
 /**
  * Render CLI version output.
@@ -156,14 +284,24 @@ export function buildCliVersion(version) {
  * conventional "<name> <version>" text.
  */
 export function cliRenderVersion(name, version, format = null) {
-    const rendered = format === null ? `${name} ${version}` : cliOutput(buildCliVersion(version), format);
+    const rendered = format === null ? `${name} ${version}` : render(buildCliVersion(version), format);
     return `${rendered.replace(/\n+$/u, "")}\n`;
 }
 /**
  * Render version output if --version/-V is present; otherwise return undefined.
  * Throws for malformed version requests, for example `--version --output xml`.
+ *
+ * One blessed behavior, not configurable: a bare version request renders
+ * conventional "<name> <version>" text; `--json` or `--output <fmt>` /
+ * `--output=<fmt>` alongside it selects the structured AFDATA payload
+ * instead.
+ *
+ * Only a top-level version request is recognized: scanning stops at the first
+ * positional argument (the subcommand) or `--`, so `tool sub --version <value>`
+ * leaves `--version` for the subcommand's parser rather than printing the
+ * tool version.
  */
-export function cliHandleVersionOrContinue(rawArgs, name, version, defaultOutput = null, outputFlag = "--output", allowOutputFormat = true) {
+export function cliHandleVersionOrContinue(rawArgs, name, version) {
     let versionRequested = false;
     let outputFormat;
     let outputError;
@@ -171,12 +309,17 @@ export function cliHandleVersionOrContinue(rawArgs, name, version, defaultOutput
         const arg = rawArgs[i];
         if (arg === "--")
             break;
+        // The first positional argument marks the subcommand boundary. Past it,
+        // --version and -V belong to the subcommand's own parser, matching
+        // git/cargo/clap: this pre-parser only owns a top-level version request.
+        if (!arg.startsWith("-"))
+            break;
         if (arg === "--version" || arg === "-V") {
             versionRequested = true;
             i += 1;
             continue;
         }
-        if (allowOutputFormat && arg === "--json") {
+        if (arg === "--json") {
             if (outputFormat !== undefined && outputFormat !== "json") {
                 outputError = new Error("conflicting output formats: --json conflicts with previous output format");
             }
@@ -186,24 +329,24 @@ export function cliHandleVersionOrContinue(rawArgs, name, version, defaultOutput
             i += 1;
             continue;
         }
-        if (allowOutputFormat && (arg === outputFlag || arg.startsWith(`${outputFlag}=`))) {
+        if (arg === "--output" || arg.startsWith("--output=")) {
             let value;
             let step = 1;
-            if (arg.startsWith(`${outputFlag}=`)) {
-                value = arg.slice(outputFlag.length + 1);
+            if (arg.startsWith("--output=")) {
+                value = arg.slice("--output=".length);
             }
             else if (rawArgs[i + 1] !== undefined && !rawArgs[i + 1].startsWith("-")) {
                 value = rawArgs[i + 1];
                 step = 2;
             }
             if (value === undefined) {
-                outputError = new Error(`missing value for ${outputFlag}: expected json, yaml, or plain`);
+                outputError = new Error("missing value for --output: expected json, yaml, or plain");
             }
             else {
                 try {
                     const parsedOutput = cliParseOutput(value);
                     if (outputFormat !== undefined && outputFormat !== parsedOutput) {
-                        outputError = new Error(`conflicting output formats: ${outputFlag} ${value} conflicts with previous output format`);
+                        outputError = new Error(`conflicting output formats: --output ${value} conflicts with previous output format`);
                     }
                     else {
                         outputFormat = parsedOutput;
@@ -222,18 +365,23 @@ export function cliHandleVersionOrContinue(rawArgs, name, version, defaultOutput
         return undefined;
     if (outputError !== undefined)
         throw outputError;
-    return cliRenderVersion(name, version, allowOutputFormat && outputFormat !== undefined ? outputFormat : defaultOutput);
+    return cliRenderVersion(name, version, outputFormat ?? null);
 }
 /**
- * Build a standard CLI parse error value.
+ * Build a standard CLI parse error value. This function cannot fail.
  * Use when flag parsing fails or a flag value is invalid.
- * Print with outputJson and exit with code 2.
+ * Print with render and exit with code 2.
+ *
+ * Always returns a strict-valid `kind:"error"` event with code `"cli_error"`.
+ * An empty `message` is replaced with a generic placeholder so the returned
+ * event stays strict-valid without throwing.
  *
  * @example
  * const err = buildCliError("--output: invalid value 'xml'");
- * console.log(outputJson(err));
+ * console.log(render(err, "json"));
  * process.exit(2);
  */
 export function buildCliError(message, hint) {
-    return jsonError("cli_error", message).hintIfSome(hint).build();
+    const msg = message && message !== "" ? message : "unspecified error";
+    return jsonError("cli_error", msg).hintIfSome(hint).build();
 }

package/dist/format.d.ts

@@ -2,9 +2,18 @@
  * AFDATA output formatting and protocol templates.
  *
  * Public APIs include protocol event builders, redactedValue (covers _secret
- * and _url fields), output formatters, redactUrlSecrets,
- * normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47,
- * RedactionPolicy, OutputStyle, and OutputOptions.
+ * and _url fields), redactUrlSecrets, normalizeUtcOffset, isValidRfc3339Date,
+ * isValidRfc3339Time, isValidRfc3339, isValidBcp47, RedactionPolicy,
+ * PlainStyle, and OutputOptions. The single render entry point (`render`)
+ * lives in cli.ts and calls this module's internal JSON/YAML/plain formatters.
+ *
+ * Number literal fidelity: decodeProtocolEvent parses with `lossless-json`
+ * instead of JSON.parse, so a number's exact source literal (arbitrary
+ * precision integers, high-precision floats, exponent forms, "-0") survives
+ * decode. Parsed numbers become LosslessNumber internally; every JSON/YAML
+ * rendering path here treats it as an opaque scalar leaf (never destructured
+ * as a plain object) and re-emits its exact literal text. This is internal —
+ * LosslessNumber is never part of the public JsonValue type or exports.
  */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
@@ -28,9 +37,9 @@ export declare class EventBuildError extends Error {
 export declare class JsonResultBuilder {
     private readonly payload;
     private traceValue;
-    private issues;
     constructor(payload: JsonValue);
     trace(value: Record<string, JsonValue> | undefined): this;
+    /** Build the event. This builder cannot fail. */
     build(): Event;
 }
 export declare class JsonErrorBuilder {
@@ -56,17 +65,17 @@ export declare class JsonErrorBuilder {
 export declare class JsonProgressBuilder {
     private readonly payload;
     private traceValue;
-    private issues;
     constructor(payload: JsonValue);
     trace(value: Record<string, JsonValue> | undefined): this;
+    /** Build the event. This builder cannot fail. */
     build(): Event;
 }
 export declare class JsonLogBuilder {
     private readonly payload;
     private traceValue;
-    private issues;
     constructor(payload: JsonValue);
     trace(value: Record<string, JsonValue> | undefined): this;
+    /** Build the event. This builder cannot fail. */
     build(): Event;
 }
 /** Fluent builder for result events. */
@@ -116,11 +125,13 @@ export declare class EventDecodeError extends Error {
  * return a typed decoded event.
  */
 export declare function decodeProtocolEvent(text: string): DecodedEvent;
+/** Which fields a redaction pass scrubs. The default is `All`. */
 export declare enum RedactionPolicy {
-    RedactionTraceOnly = "RedactionTraceOnly",
-    RedactionNone = "RedactionNone"
+    All = "All",
+    TraceOnly = "TraceOnly",
+    Off = "Off"
 }
-export declare enum OutputStyle {
+export declare enum PlainStyle {
     Readable = "Readable",
     Raw = "Raw"
 }
@@ -135,17 +146,33 @@ export type OutputOptions = {
          */
         secretNames?: readonly string[];
     };
-    /** Rendering style for YAML/plain output. Omitted means readable. */
-    style?: OutputStyle;
+    /** Rendering style for plain (logfmt) output only. Omitted means readable.
+     * JSON and YAML are structure-preserving and ignore this setting. */
+    style?: PlainStyle;
 };
 /** Convenience: build OutputOptions scoped to a RedactionPolicy. */
 export declare function outputOptionsForPolicy(policy: RedactionPolicy): OutputOptions;
-/** Format as single-line JSON. Secrets redacted, original keys, raw values. */
-export declare function outputJson(value: JsonValue | Event, options?: OutputOptions): string;
-/** Format as multi-line YAML. Keys stripped, values formatted, secrets redacted. */
-export declare function outputYaml(value: JsonValue | Event, options?: OutputOptions): string;
-/** Format as single-line logfmt. Keys stripped, values formatted, secrets redacted. */
-export declare function outputPlain(value: JsonValue | Event, options?: OutputOptions): string;
+/**
+ * Format as single-line JSON. Secrets redacted, original keys, raw values.
+ * Internal: called by `render` in cli.ts, which is the single public render
+ * entry point. Not re-exported from index.ts.
+ */
+export declare function formatJsonValue(value: JsonValue | Event, options?: OutputOptions): string;
+/**
+ * Format as multi-line YAML. Structure-preserving: like JSON, original keys,
+ * scalar types, and numeric semantics are kept after redaction; secrets are
+ * still redacted. `options.style` is ignored — YAML output does not vary by
+ * PlainStyle.
+ * Internal: called by `render` in cli.ts, which is the single public render
+ * entry point. Not re-exported from index.ts.
+ */
+export declare function formatYamlValue(value: JsonValue | Event, options?: OutputOptions): string;
+/**
+ * Format as single-line logfmt. Keys stripped, values formatted, secrets redacted.
+ * Internal: called by `render` in cli.ts, which is the single public render
+ * entry point. Not re-exported from index.ts.
+ */
+export declare function formatPlainValue(value: JsonValue | Event, options?: OutputOptions): string;
 /** Return a JSON-safe copy with redaction options applied (default: full _secret redaction). */
 export declare function redactedValue(value: unknown, options?: {
     policy?: RedactionPolicy;