agent-first-data 0.15.0 → 0.16.0

package/dist/cli.d.ts

@@ -1,7 +1,7 @@
 /**
  * AFDATA CLI helpers — output format parsing, log filter normalization, error building.
  */
-import { JsonValue, type OutputOptions } from "./format.js";
+import { JsonValue, type OutputOptions, Event } from "./format.js";
 /** Output format for CLI and pipe/MCP modes. */
 export type OutputFormat = "json" | "yaml" | "plain";
 /**
@@ -13,29 +13,63 @@ export type OutputFormat = "json" | "yaml" | "plain";
  * cliParseOutput("xml")  // throws Error
  */
 export declare function cliParseOutput(s: string): OutputFormat;
+/**
+ * Normalized log filter result with enabled() matching and readonly filters property.
+ */
+export declare class LogFilters {
+    readonly filters: readonly string[];
+    constructor(entries: readonly string[]);
+    /**
+     * 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.
+     *
+     * @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 wild = new LogFilters(["*"]);
+     * wild.enabled("anything") // → true
+     */
+    enabled(event: string): boolean;
+}
 /**
  * Normalize --output flag entries: trim, lowercase, deduplicate, remove empty.
  * Accepts pre-split entries (e.g. after splitting on comma).
  *
  * @example
- * cliParseLogFilters(["Query", " error ", "query"]) // → ["query", "error"]
+ * const lf = cliParseLogFilters(["Query", " error ", "query"]);
+ * lf.enabled("QueryStarted") // → true
+ * lf.filters // → ["query", "error"]
  */
-export declare function cliParseLogFilters(entries: string[]): string[];
+export declare function cliParseLogFilters(entries: string[]): LogFilters;
 /**
- * Dispatch output formatting by OutputFormat.
- * Equivalent to calling outputJson, outputYaml, or outputPlain directly.
+ * Dispatch output formatting by OutputFormat, with optional explicit redaction and style.
+ * JSON ignores OutputStyle and preserves original keys and values after redaction.
  *
  * @example
- * cliOutput({ code: "ok" }, "plain") // → "code=ok"
- */
-export declare function cliOutput(value: JsonValue, format: OutputFormat): string;
-/**
- * Dispatch output formatting with explicit redaction and style.
- * JSON ignores OutputStyle and preserves original keys and values after redaction.
+ * cliOutput(jsonResult({ ok: true }).build(), "plain") // → "kind=result result.ok=true"
  */
-export declare function cliOutputWithOptions(value: JsonValue, format: OutputFormat, outputOptions: OutputOptions): string;
+export declare function cliOutput(value: JsonValue | Event, format: OutputFormat, options?: OutputOptions): string;
+export type CliEventWriter = (line: string) => void;
+/** Stateful emitter for finite structured CLI executions. */
+export declare class CliEmitter {
+    private readonly writer;
+    private readonly format;
+    private readonly outputOptions;
+    private terminalEmitted;
+    private logFieldsProvider?;
+    constructor(writer: CliEventWriter, format: OutputFormat, outputOptions?: OutputOptions);
+    withLogFields(provider: () => Record<string, JsonValue>): this;
+    emit(event: Event): void;
+    emitValidatedValue(value: JsonValue): void;
+}
 /** Build a standard CLI version value. */
-export declare function buildCliVersion(version: string): JsonValue;
+export declare function buildCliVersion(version: string): Event;
 /**
  * Render CLI version output.
  * Pass an OutputFormat for AFDATA JSON/YAML/plain. Pass null to preserve
@@ -57,4 +91,4 @@ export declare function cliHandleVersionOrContinue(rawArgs: string[], name: stri
  * console.log(outputJson(err));
  * process.exit(2);
  */
-export declare function buildCliError(message: string, hint?: string): JsonValue;
+export declare function buildCliError(message: string, hint?: string): Event;

package/dist/cli.js

@@ -1,7 +1,7 @@
 /**
  * AFDATA CLI helpers — output format parsing, log filter normalization, error building.
  */
-import { buildJson, outputJson, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, } from "./format.js";
+import { Event, jsonError, jsonResult, outputJson, outputYaml, outputPlain, validateProtocolEvent, } from "./format.js";
 /**
  * Parse the --output flag value into an OutputFormat.
  * Throws on unknown values; catch and pass message to buildCliError.
@@ -17,50 +17,138 @@ export function cliParseOutput(s) {
     throw new Error(`invalid --output format '${s}': expected json, yaml, or plain`);
 }
 /**
- * Normalize --output flag entries: trim, lowercase, deduplicate, remove empty.
- * Accepts pre-split entries (e.g. after splitting on comma).
- *
- * @example
- * cliParseLogFilters(["Query", " error ", "query"]) // → ["query", "error"]
+ * Normalized log filter result with enabled() matching and readonly filters property.
  */
-export function cliParseLogFilters(entries) {
-    const out = [];
-    for (const entry of entries) {
-        const s = entry.trim().toLowerCase();
-        if (s && !out.includes(s)) {
-            out.push(s);
+export class LogFilters {
+    filters;
+    constructor(entries) {
+        const out = [];
+        for (const entry of entries) {
+            const s = entry.trim().toLowerCase();
+            if (s && !out.includes(s)) {
+                out.push(s);
+            }
         }
+        this.filters = Object.freeze([...out]);
+    }
+    /**
+     * 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.
+     *
+     * @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 wild = new LogFilters(["*"]);
+     * wild.enabled("anything") // → true
+     */
+    enabled(event) {
+        if (this.filters.length === 0)
+            return false;
+        if (this.filters.includes("all") || this.filters.includes("*"))
+            return true;
+        const eventLower = event.toLowerCase();
+        for (const filter of this.filters) {
+            if (eventLower.startsWith(filter)) {
+                return true;
+            }
+        }
+        return false;
     }
-    return out;
 }
 /**
- * Dispatch output formatting by OutputFormat.
- * Equivalent to calling outputJson, outputYaml, or outputPlain directly.
+ * Normalize --output flag entries: trim, lowercase, deduplicate, remove empty.
+ * Accepts pre-split entries (e.g. after splitting on comma).
  *
  * @example
- * cliOutput({ code: "ok" }, "plain") // → "code=ok"
+ * const lf = cliParseLogFilters(["Query", " error ", "query"]);
+ * lf.enabled("QueryStarted") // → true
+ * lf.filters // → ["query", "error"]
  */
-export function cliOutput(value, format) {
-    if (format === "yaml")
-        return outputYaml(value);
-    if (format === "plain")
-        return outputPlain(value);
-    return outputJson(value);
+export function cliParseLogFilters(entries) {
+    return new LogFilters(entries);
 }
 /**
- * Dispatch output formatting with explicit redaction and style.
+ * Dispatch output formatting by OutputFormat, with optional explicit redaction and style.
  * JSON ignores OutputStyle and preserves original keys and values after redaction.
+ *
+ * @example
+ * cliOutput(jsonResult({ ok: true }).build(), "plain") // → "kind=result result.ok=true"
  */
-export function cliOutputWithOptions(value, format, outputOptions) {
+export function cliOutput(value, format, options = {}) {
+    const jsonValue = value instanceof Event ? value.toJSON() : value;
     if (format === "yaml")
-        return outputYamlWithOptions(value, outputOptions);
+        return outputYaml(jsonValue, options);
     if (format === "plain")
-        return outputPlainWithOptions(value, outputOptions);
-    return outputJsonWithOptions(value, outputOptions);
+        return outputPlain(jsonValue, options);
+    return outputJson(jsonValue, options);
+}
+/** Stateful emitter for finite structured CLI executions. */
+export class CliEmitter {
+    writer;
+    format;
+    outputOptions;
+    terminalEmitted = false;
+    logFieldsProvider;
+    constructor(writer, format, outputOptions = {}) {
+        this.writer = writer;
+        this.format = format;
+        this.outputOptions = outputOptions;
+    }
+    withLogFields(provider) {
+        this.logFieldsProvider = provider;
+        return this;
+    }
+    emit(event) {
+        const jsonValue = event.toJSON();
+        validateProtocolEvent(jsonValue);
+        const kind = jsonValue.kind;
+        if (kind === "log" || kind === "progress") {
+            if (this.terminalEmitted) {
+                throw new Error("cannot emit non-terminal event after terminal event");
+            }
+        }
+        else if (kind === "result" || kind === "error") {
+            if (this.terminalEmitted) {
+                throw new Error("cannot emit duplicate terminal event");
+            }
+        }
+        else {
+            throw new Error(`unsupported event kind ${JSON.stringify(kind)}`);
+        }
+        this.writer(`${cliOutput(jsonValue, this.format, this.outputOptions)}\n`);
+        if (kind === "result" || kind === "error")
+            this.terminalEmitted = true;
+    }
+    emitValidatedValue(value) {
+        validateProtocolEvent(value);
+        const kind = value.kind;
+        if (kind === "log" || kind === "progress") {
+            if (this.terminalEmitted) {
+                throw new Error("cannot emit non-terminal event after terminal event");
+            }
+        }
+        else if (kind === "result" || kind === "error") {
+            if (this.terminalEmitted) {
+                throw new Error("cannot emit duplicate terminal event");
+            }
+        }
+        else {
+            throw new Error(`unsupported event kind ${JSON.stringify(kind)}`);
+        }
+        this.writer(`${cliOutput(value, this.format, this.outputOptions)}\n`);
+        if (kind === "result" || kind === "error")
+            this.terminalEmitted = true;
+    }
 }
 /** Build a standard CLI version value. */
 export function buildCliVersion(version) {
-    return buildJson("version", { version });
+    return jsonResult({ version }).build();
 }
 /**
  * Render CLI version output.
@@ -88,6 +176,16 @@ export function cliHandleVersionOrContinue(rawArgs, name, version, defaultOutput
             i += 1;
             continue;
         }
+        if (allowOutputFormat && arg === "--json") {
+            if (outputFormat !== undefined && outputFormat !== "json") {
+                outputError = new Error("conflicting output formats: --json conflicts with previous output format");
+            }
+            else {
+                outputFormat = "json";
+            }
+            i += 1;
+            continue;
+        }
         if (allowOutputFormat && (arg === outputFlag || arg.startsWith(`${outputFlag}=`))) {
             let value;
             let step = 1;
@@ -103,7 +201,13 @@ export function cliHandleVersionOrContinue(rawArgs, name, version, defaultOutput
             }
             else {
                 try {
-                    outputFormat = cliParseOutput(value);
+                    const parsedOutput = cliParseOutput(value);
+                    if (outputFormat !== undefined && outputFormat !== parsedOutput) {
+                        outputError = new Error(`conflicting output formats: ${outputFlag} ${value} conflicts with previous output format`);
+                    }
+                    else {
+                        outputFormat = parsedOutput;
+                    }
                 }
                 catch (e) {
                     outputError = e;
@@ -131,11 +235,5 @@ export function cliHandleVersionOrContinue(rawArgs, name, version, defaultOutput
  * process.exit(2);
  */
 export function buildCliError(message, hint) {
-    const m = {
-        code: "error",
-        error: message,
-    };
-    if (hint !== undefined)
-        m.hint = hint;
-    return m;
+    return jsonError("cli_error", message).hintIfSome(hint).build();
 }

package/dist/format.d.ts

@@ -1,77 +1,171 @@
 /**
  * AFDATA output formatting and protocol templates.
  *
- * 21 public APIs and 4 types: protocol builders, value redactors (copy and
- * in-place; cover _secret and _url fields), output formatters, URL-string
- * redactors (redactUrlSecrets / WithOptions), parseSize, normalizeUtcOffset,
- * isValidRfc3339Date, isValidRfc3339Time, RedactionPolicy, RedactionOptions,
- * OutputStyle, and OutputOptions.
+ * Public APIs include protocol event builders, redactedValue (covers _secret
+ * and _url fields), output formatters, redactUrlSecrets, parseSize,
+ * normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time,
+ * RedactionPolicy, OutputStyle, and OutputOptions.
  */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
-/** Build {code: "ok", result, trace?}. */
-export declare function buildJsonOk(result: JsonValue, trace?: JsonValue): JsonValue;
-/** Build {code: "error", error: message, hint?, trace?}. */
-export declare function buildJsonError(message: string, hint?: string, trace?: JsonValue): JsonValue;
-/** Build {code: "<custom>", ...fields, trace?}. */
-export declare function buildJson(code: string, fields: JsonValue, trace?: JsonValue): JsonValue;
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Event is an opaque type wrapping a protocol event envelope.
+ * Guaranteed to be strict-valid by construction.
+ */
+export declare class Event {
+    private readonly value;
+    private readonly __brand;
+    constructor(value: JsonValue);
+    toJSON(): JsonValue;
+    valueOf(): JsonValue;
+}
+export declare class EventBuildError extends Error {
+    readonly issues: string[];
+    constructor(message: string, issues: string[]);
+}
+export declare class JsonResultBuilder {
+    private readonly payload;
+    private traceValue;
+    private issues;
+    constructor(payload: JsonValue);
+    trace(value: Record<string, JsonValue> | undefined): this;
+    build(): Event;
+}
+export declare class JsonErrorBuilder {
+    private readonly code;
+    private readonly message;
+    private retryableValue;
+    private hintValue;
+    private extensionFields;
+    private traceValue;
+    private issues;
+    constructor(code: string, message: string);
+    retryable(): this;
+    retryableIf(flag: boolean): this;
+    hint(value: string): this;
+    hintIfSome(value: string | undefined | null): this;
+    field(name: string, value: JsonValue): this;
+    fields(obj: unknown): this;
+    extend(obj: unknown): this;
+    trace(value: Record<string, JsonValue> | undefined): this;
+    private isReservedErrorField;
+    build(): Event;
+}
+export declare class JsonProgressBuilder {
+    private readonly message;
+    private extensionFields;
+    private traceValue;
+    private issues;
+    constructor(message: string);
+    field(name: string, value: JsonValue): this;
+    fields(obj: unknown): this;
+    extend(obj: unknown): this;
+    trace(value: Record<string, JsonValue> | undefined): this;
+    private isReservedProgressField;
+    build(): Event;
+}
+export declare class JsonLogBuilder {
+    private readonly level;
+    private readonly message;
+    private extensionFields;
+    private traceValue;
+    private issues;
+    constructor(level: LogLevel, message: string);
+    field(name: string, value: JsonValue): this;
+    fields(obj: unknown): this;
+    extend(obj: unknown): this;
+    trace(value: Record<string, JsonValue> | undefined): this;
+    private isReservedLogField;
+    build(): Event;
+}
+/** Fluent builder for result events. */
+export declare function jsonResult(payload: JsonValue): JsonResultBuilder;
+/** Fluent builder for error events. */
+export declare function jsonError(code: string, message: string): JsonErrorBuilder;
+/** Fluent builder for progress events. */
+export declare function jsonProgress(message: string): JsonProgressBuilder;
+/** Fluent builder for log events. */
+export declare function jsonLog(level: LogLevel, message: string): JsonLogBuilder;
+/** Validate one protocol event envelope. `strict` also enforces the recommended strict protocol profile (default true). */
+export declare function validateProtocolEvent(event: unknown, strict?: boolean): void;
+/** Validate finite CLI lifecycle: (log | progress)* -> exactly one terminal. `strict` also enforces the recommended strict protocol profile (default true). */
+export declare function validateProtocolStream(events: readonly unknown[], strict?: boolean): void;
+export type DecodedResult = {
+    kind: "result";
+    result: JsonValue;
+    trace?: Record<string, JsonValue>;
+};
+export type DecodedError = {
+    kind: "error";
+    code: string;
+    message: string;
+    retryable: boolean;
+    hint?: string;
+    fields: Record<string, JsonValue>;
+    trace?: Record<string, JsonValue>;
+};
+export type DecodedProgress = {
+    kind: "progress";
+    message: string;
+    fields: Record<string, JsonValue>;
+    trace?: Record<string, JsonValue>;
+};
+export type DecodedLog = {
+    kind: "log";
+    level: LogLevel;
+    message: string;
+    fields: Record<string, JsonValue>;
+    trace?: Record<string, JsonValue>;
+};
+/** Discriminated union of decoded protocol events, narrow on `kind`. */
+export type DecodedEvent = DecodedResult | DecodedError | DecodedProgress | DecodedLog;
+/** Thrown by decodeProtocolEvent for malformed JSON or a strict-invalid event. */
+export declare class EventDecodeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse one protocol line (a single JSON text value), strict-validate it, and
+ * return a typed decoded event. Extension fields are every payload key beyond
+ * the required ones, collected into `fields`.
+ */
+export declare function decodeProtocolEvent(text: string): DecodedEvent;
 export declare enum RedactionPolicy {
     RedactionTraceOnly = "RedactionTraceOnly",
     RedactionNone = "RedactionNone"
 }
-export type RedactionOptions = {
-    /** Optional scoped policy. Omitted means default full redaction. */
-    policy?: RedactionPolicy;
-    /**
-     * Field names to treat as secrets in addition to _secret suffixes.
-     * Matching is exact field-name equality at any nesting level. The same
-     * list also matches URL query-parameter names inside _url fields (see
-     * redactUrlSecrets).
-     */
-    secretNames?: readonly string[];
-};
 export declare enum OutputStyle {
     Readable = "Readable",
     Raw = "Raw"
 }
 export type OutputOptions = {
-    /** Redaction options applied before rendering. */
-    redaction?: RedactionOptions;
+    /** Redaction policy. Omitted means default full redaction. */
+    redaction?: {
+        /** Optional scoped policy. Omitted means default full redaction. */
+        policy?: RedactionPolicy;
+        /**
+         * Field names to treat as secrets in addition to _secret suffixes.
+         * Matching is exact field-name equality at any nesting level.
+         */
+        secretNames?: readonly string[];
+    };
     /** Rendering style for YAML/plain output. Omitted means readable. */
     style?: OutputStyle;
 };
+/** 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): string;
-/** Format as single-line JSON with explicit redaction policy. */
-export declare function outputJsonWith(value: JsonValue, redactionPolicy: RedactionPolicy): string;
-/** Format as single-line JSON with explicit output options. */
-export declare function outputJsonWithOptions(value: JsonValue, outputOptions: OutputOptions): string;
+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): string;
-/** Format as multi-line YAML with explicit output options. */
-export declare function outputYamlWithOptions(value: JsonValue, outputOptions: OutputOptions): string;
+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): string;
-/** Format as single-line logfmt with explicit output options. */
-export declare function outputPlainWithOptions(value: JsonValue, outputOptions: OutputOptions): string;
-/** Redact _secret fields in-place. */
-export declare function redactSecretsInPlace(value: JsonValue): void;
-/** Redact secret fields in-place using explicit redaction options. */
-export declare function redactSecretsInPlaceWithOptions(value: JsonValue, redactionOptions: RedactionOptions): void;
-/** Return a JSON-safe copy with default _secret redaction applied. */
-export declare function redactedValue(value: unknown): JsonValue;
-/** Return a JSON-safe copy with an explicit redaction policy applied. */
-export declare function redactedValueWith(value: unknown, redactionPolicy: RedactionPolicy): JsonValue;
-/** Return a JSON-safe copy with explicit redaction options applied. */
-export declare function redactedValueWithOptions(value: unknown, redactionOptions: RedactionOptions): JsonValue;
-/**
- * Redact secret components of a single URL string, using default options.
- *
- * Returns url with its userinfo password and any _secret-suffixed query
- * parameter values replaced by "***". See redactUrlSecretsWithOptions.
- */
-export declare function redactUrlSecrets(url: string): string;
+export declare function outputPlain(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;
+    secretNames?: readonly string[];
+}): JsonValue;
 /**
  * Redact secret components of a single URL string.
  *
@@ -82,11 +176,14 @@ export declare function redactUrlSecrets(url: string): string;
  * A string that is not a single, whitespace-free, scheme-prefixed URL
  * (including a URL embedded in surrounding prose) is returned unchanged.
  */
-export declare function redactUrlSecretsWithOptions(url: string, redactionOptions: RedactionOptions): string;
+export declare function redactUrlSecrets(url: string, options?: {
+    secretNames?: readonly string[];
+}): string;
 /**
  * Parse a human-readable size string into bytes.
- * Accepts bare numbers or numbers followed by a unit letter (B/K/M/G/T).
- * Case-insensitive. Trims whitespace. Returns null for invalid input.
+ * Accepts numbers followed by explicit units. Decimal units are
+ * B/kB/MB/GB/TB; binary units are KiB/MiB/GiB/TiB.
+ * Trims whitespace and rejects ambiguous K/M/G/T units.
  */
 export declare function parseSize(s: string): number | null;
 /**