agent-first-data 0.26.2 → 0.28.0

package/dist/cli.d.ts

@@ -105,8 +105,8 @@ export declare class CliEmitter {
     private readonly format;
     private readonly outputOptions;
     private terminalEmitted;
-    private logFieldsProvider?;
     private diagnostic?;
+    private strictProtocol;
     /**
      * Create an event-stream emitter: every event, including `error`, goes to the
      * single `writer`. Use CliEmitter.finite for a one-shot command that should
@@ -136,7 +136,6 @@ export declare class CliEmitter {
      * stderr); "stdout"/"stderr" are event-stream mode onto that one stream.
      */
     static fromOutputTo(selector: OutputTo, format: OutputFormat, outputOptions?: OutputOptions): CliEmitter;
-    withLogFields(provider: () => Record<string, JsonValue>): 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
@@ -144,6 +143,8 @@ export declare class CliEmitter {
      * mode (no diagnostic sink) keeps every event on the single writer.
      */
     private sinkFor;
+    /** Opt this emitter into the AFDATA recommended strict profile. */
+    withStrictProtocol(): this;
     emit(event: Event): void;
     emitValidatedValue(value: JsonValue): void;
     private static isBrokenPipe;
@@ -181,26 +182,6 @@ export declare function buildCliVersion(name: string, displayName: string | unde
  * conventional-text path — `format` is required.
  */
 export declare function cliRenderVersion(name: string, displayName: string | undefined, version: string, build: string | undefined, format: OutputFormat): string;
-/**
- * Render version output if --version/-V is present; otherwise return undefined.
- * Throws for malformed version requests, for example `--version --output xml`.
- *
- * The one blessed behavior: `--version` always answers with a protocol-v1
- * `kind:"result"` version event. An explicit `--output` wins; otherwise
- * `defaultOutput` should be the command's normal output default.
- *
- * `valueFlags` is the caller's own value-taking global long flags (with or
- * without leading dashes; the leading dashes are stripped internally). It is the
- * TS analog of Rust's `&clap::Command`: the pre-parser consults it so a global
- * flag's space-separated value (e.g. `--log request,startup`) is never mistaken
- * for the subcommand boundary, which would hide a later `--version`/`--output`.
- *
- * 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 declare function cliHandleVersionOrContinue(rawArgs: string[], valueFlags: string[], name: string, displayName: string | undefined, version: string, build: string | undefined, defaultOutput?: OutputFormat): string | undefined;
 /**
  * Build a standard CLI parse error value. This function cannot fail.
  * Use when flag parsing fails or a flag value is invalid.

package/dist/cli.js

@@ -141,8 +141,8 @@ export class CliEmitter {
     format;
     outputOptions;
     terminalEmitted = false;
-    logFieldsProvider;
     diagnostic;
+    strictProtocol = false;
     /**
      * Create an event-stream emitter: every event, including `error`, goes to the
      * single `writer`. Use CliEmitter.finite for a one-shot command that should
@@ -189,10 +189,6 @@ export class CliEmitter {
         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
@@ -202,9 +198,14 @@ export class CliEmitter {
     sinkFor(kind) {
         return kind !== "result" && this.diagnostic ? this.diagnostic : this.writer;
     }
+    /** Opt this emitter into the AFDATA recommended strict profile. */
+    withStrictProtocol() {
+        this.strictProtocol = true;
+        return this;
+    }
     emit(event) {
         const jsonValue = event.toJSON();
-        validateProtocolEvent(jsonValue);
+        validateProtocolEvent(jsonValue, this.strictProtocol);
         const kind = jsonValue.kind;
         if (kind === "log" || kind === "progress") {
             if (this.terminalEmitted) {
@@ -301,109 +302,6 @@ export function cliRenderVersion(name, displayName, version, build, format) {
     const rendered = render(buildCliVersion(name, displayName, version, build), format);
     return `${rendered.replace(/\n+$/u, "")}\n`;
 }
-/**
- * Split a flag argument into its long name (leading dashes stripped, any
- * `=value` suffix dropped) and inline value. Returns `undefined` name for a
- * non-flag or the bare `-`. `--output=` yields an empty-string inline value.
- */
-function splitFlag(arg) {
-    if (!arg.startsWith("-") || arg === "-")
-        return { name: undefined, inlineValue: undefined };
-    const eq = arg.indexOf("=");
-    const flag = eq === -1 ? arg : arg.slice(0, eq);
-    const inlineValue = eq === -1 ? undefined : arg.slice(eq + 1);
-    const name = flag.replace(/^-+/u, "");
-    if (name === "")
-        return { name: undefined, inlineValue: undefined };
-    return { name, inlineValue };
-}
-/**
- * Render version output if --version/-V is present; otherwise return undefined.
- * Throws for malformed version requests, for example `--version --output xml`.
- *
- * The one blessed behavior: `--version` always answers with a protocol-v1
- * `kind:"result"` version event. An explicit `--output` wins; otherwise
- * `defaultOutput` should be the command's normal output default.
- *
- * `valueFlags` is the caller's own value-taking global long flags (with or
- * without leading dashes; the leading dashes are stripped internally). It is the
- * TS analog of Rust's `&clap::Command`: the pre-parser consults it so a global
- * flag's space-separated value (e.g. `--log request,startup`) is never mistaken
- * for the subcommand boundary, which would hide a later `--version`/`--output`.
- *
- * 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, valueFlags, name, displayName, version, build, defaultOutput = "json") {
-    const valueFlagSet = new Set(valueFlags.map((flag) => flag.replace(/^-+/u, "")));
-    let versionRequested = false;
-    let outputFormat;
-    let outputError;
-    for (let i = 0; i < rawArgs.length;) {
-        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;
-        const { name: flagName, inlineValue } = splitFlag(arg);
-        if (arg === "--version") {
-            versionRequested = true;
-            i += 1;
-            continue;
-        }
-        // `--output-to` takes a value but does not affect version text output.
-        // Consume its space-separated value so it is not mistaken for the
-        // subcommand boundary (which would hide a later `--version`/`--output`).
-        if (flagName === "output-to") {
-            const hasSpaceValue = inlineValue === undefined && rawArgs[i + 1] !== undefined && !rawArgs[i + 1].startsWith("-");
-            i += hasSpaceValue ? 2 : 1;
-            continue;
-        }
-        if (flagName === "output") {
-            let value;
-            if (inlineValue !== undefined) {
-                value = inlineValue;
-            }
-            else if (rawArgs[i + 1] !== undefined && !rawArgs[i + 1].startsWith("-")) {
-                value = rawArgs[i + 1];
-            }
-            if (value === undefined) {
-                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: --output ${value} conflicts with previous output format`);
-                    }
-                    else {
-                        outputFormat = parsedOutput;
-                    }
-                }
-                catch (e) {
-                    outputError = e;
-                }
-            }
-            i += inlineValue !== undefined || value === undefined ? 1 : 2;
-            continue;
-        }
-        // Any other flag: consult the caller's own value-taking global flags so a
-        // flag's space-separated value is never mistaken for the subcommand
-        // boundary above.
-        const hasSpaceValue = inlineValue === undefined && rawArgs[i + 1] !== undefined && !rawArgs[i + 1].startsWith("-");
-        i += hasSpaceValue && flagName !== undefined && valueFlagSet.has(flagName) ? 2 : 1;
-    }
-    if (!versionRequested)
-        return undefined;
-    if (outputError !== undefined)
-        throw outputError;
-    return cliRenderVersion(name, displayName, version, build, outputFormat ?? defaultOutput);
-}
 /**
  * Build a standard CLI parse error value. This function cannot fail.
  * Use when flag parsing fails or a flag value is invalid.

package/dist/format.d.ts

@@ -12,10 +12,11 @@
  * 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.
+ * as a plain object) and re-emits its exact literal text. Native bigint values
+ * are also supported so callers can render integers beyond Number's safe
+ * range without first corrupting them.
  */
-export type JsonValue = string | number | boolean | null | JsonValue[] | {
+export type JsonValue = string | number | bigint | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 export type LogLevel = "debug" | "info" | "warn" | "error";
@@ -125,7 +126,14 @@ 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`. */
+/**
+ * Which fields a redaction pass scrubs. The default is `All`.
+ *
+ * The policy selects a *scope* inside a structured value. A command line
+ * (`redactArgv`) and a bare URL string (`redactUrlSecrets`) have no
+ * result/trace split to scope to, so on those two paths `TraceOnly` redacts in
+ * full like `All`, and only `Off` turns redaction off.
+ */
 export declare enum RedactionPolicy {
     All = "All",
     TraceOnly = "TraceOnly",
@@ -182,14 +190,21 @@ export declare function redactedValue(value: unknown, options?: {
  * Redact secret components of a single URL string.
  *
  * A query parameter is redacted iff its (form-decoded) name ends in
- * _secret/_SECRET or matches an exact entry in secretNames. The userinfo
- * password (scheme://user:pass@host) is always redacted as a structural rule.
- * Only the secret spans are replaced with "***"; every other byte is preserved.
- * A string that is not a single, whitespace-free, scheme-prefixed URL
- * (including a URL embedded in surrounding prose) is returned unchanged.
+ * _secret/_SECRET or matches an exact entry in secretNames. A fragment written
+ * in the same `k=v&k=v` shape — how an OAuth implicit-flow response carries its
+ * token — is redacted by that same rule; any other fragment passes through
+ * byte-for-byte. The userinfo password (scheme://user:pass@host) is always
+ * redacted as a structural rule. Only the secret spans are replaced with "***";
+ * every other byte is preserved. A string that is not a single,
+ * whitespace-free, scheme-prefixed URL (including a URL embedded in surrounding
+ * prose) is returned unchanged.
+ *
+ * A URL is unscoped input: `RedactionPolicy.Off` returns it unchanged, every
+ * other policy redacts it in full.
  */
 export declare function redactUrlSecrets(url: string, options?: {
     secretNames?: readonly string[];
+    policy?: RedactionPolicy;
 }): string;
 /**
  * Redact secret values out of a command line.
@@ -211,6 +226,9 @@ export declare function redactUrlSecrets(url: string, options?: {
  * Intended for CLIs that record their own invocation — startup diagnostics,
  * audit trails, crash reports — where writing argv verbatim would put a
  * credential in the log.
+ *
+ * A command line is unscoped input: `RedactionPolicy.Off` returns `args`
+ * unchanged, every other policy redacts in full.
  */
 export declare function redactArgv(args: readonly string[], options?: {
     secretNames?: readonly string[];