agent-first-data 0.3.0 → 0.4.1

package/README.md

@@ -63,7 +63,7 @@ Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_fil
 
 ## API Reference
 
-Total: **8 public APIs** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **12 public APIs and 1 type** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat`)
 
 ### Protocol Builders (returns JsonValue)
 
@@ -177,6 +177,42 @@ parseSize("1.5K"); // 1536
 parseSize("512");  // 512
 ```
 
+### CLI Helpers (for tools built on AFDATA)
+
+Shared helpers that prevent flag-parsing drift between CLI tools. Use these instead of reimplementing `--output` and `--log` handling in each tool.
+
+```typescript
+type OutputFormat = "json" | "yaml" | "plain"
+
+cliParseOutput(s: string): OutputFormat             // Parse --output flag; throws on unknown
+cliParseLogFilters(entries: string[]): string[]     // Normalize --log: trim, lowercase, dedup, remove empty
+cliOutput(value: JsonValue, format: OutputFormat): string  // Dispatch to outputJson/Yaml/Plain
+buildCliError(message: string): JsonValue           // {code:"error", error_code:"invalid_request", retryable:false, trace:{duration_ms:0}}
+```
+
+**Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:
+
+```typescript
+import {
+  type OutputFormat, cliParseOutput, cliParseLogFilters,
+  cliOutput, buildCliError, outputJson,
+} from "agent-first-data";
+
+let fmt: OutputFormat;
+try {
+  fmt = cliParseOutput(outputArg);
+} catch (e) {
+  console.log(outputJson(buildCliError((e as Error).message)));
+  process.exit(2);
+}
+
+const log = cliParseLogFilters(logArg ? logArg.split(",") : []);
+// ... do work ...
+console.log(cliOutput(result, fmt));
+```
+
+See `examples/agent_cli.ts` for the complete working example (`npx tsx --test examples/agent_cli.ts`).
+
 ## Usage Examples
 
 ### Example 1: REST API
@@ -265,6 +301,7 @@ const result = buildJsonOk(
 );
 
 // Print JSONL to stdout (secrets redacted, one JSON object per line)
+// Channel policy: machine-readable protocol/log events must not use stderr.
 console.log(outputJson(result));
 // {"code":"ok","result":{"status":"success"},"trace":{"api_key_secret":"***","duration_ms":250}}
 ```

package/dist/cli.d.ts

@@ -0,0 +1,42 @@
+/**
+ * AFDATA CLI helpers — output format parsing, log filter normalization, error building.
+ */
+import { JsonValue } from "./format.js";
+/** Output format for CLI and pipe/MCP modes. */
+export type OutputFormat = "json" | "yaml" | "plain";
+/**
+ * Parse the --output flag value into an OutputFormat.
+ * Throws on unknown values; catch and pass message to buildCliError.
+ *
+ * @example
+ * cliParseOutput("json") // → "json"
+ * cliParseOutput("xml")  // throws Error
+ */
+export declare function cliParseOutput(s: string): OutputFormat;
+/**
+ * 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"]
+ */
+export declare function cliParseLogFilters(entries: string[]): string[];
+/**
+ * Dispatch output formatting by OutputFormat.
+ * Equivalent to calling outputJson, outputYaml, or outputPlain directly.
+ *
+ * @example
+ * cliOutput({ code: "ok" }, "plain") // → "code=ok"
+ */
+export declare function cliOutput(value: JsonValue, format: OutputFormat): string;
+/**
+ * Build a standard CLI parse error value.
+ * Use when flag parsing fails or a flag value is invalid.
+ * Print with outputJson and exit with code 2.
+ *
+ * @example
+ * const err = buildCliError("--output: invalid value 'xml'");
+ * console.log(outputJson(err));
+ * process.exit(2);
+ */
+export declare function buildCliError(message: string): JsonValue;

package/dist/cli.js

@@ -0,0 +1,68 @@
+/**
+ * AFDATA CLI helpers — output format parsing, log filter normalization, error building.
+ */
+import { outputJson, outputYaml, outputPlain } from "./format.js";
+/**
+ * Parse the --output flag value into an OutputFormat.
+ * Throws on unknown values; catch and pass message to buildCliError.
+ *
+ * @example
+ * cliParseOutput("json") // → "json"
+ * cliParseOutput("xml")  // throws Error
+ */
+export function cliParseOutput(s) {
+    if (s === "json" || s === "yaml" || s === "plain") {
+        return 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"]
+ */
+export function cliParseLogFilters(entries) {
+    const out = [];
+    for (const entry of entries) {
+        const s = entry.trim().toLowerCase();
+        if (s && !out.includes(s)) {
+            out.push(s);
+        }
+    }
+    return out;
+}
+/**
+ * Dispatch output formatting by OutputFormat.
+ * Equivalent to calling outputJson, outputYaml, or outputPlain directly.
+ *
+ * @example
+ * cliOutput({ code: "ok" }, "plain") // → "code=ok"
+ */
+export function cliOutput(value, format) {
+    if (format === "yaml")
+        return outputYaml(value);
+    if (format === "plain")
+        return outputPlain(value);
+    return outputJson(value);
+}
+/**
+ * Build a standard CLI parse error value.
+ * Use when flag parsing fails or a flag value is invalid.
+ * Print with outputJson and exit with code 2.
+ *
+ * @example
+ * const err = buildCliError("--output: invalid value 'xml'");
+ * console.log(outputJson(err));
+ * process.exit(2);
+ */
+export function buildCliError(message) {
+    return {
+        code: "error",
+        error_code: "invalid_request",
+        error: message,
+        retryable: false,
+        trace: { duration_ms: 0 },
+    };
+}

package/dist/index.d.ts

@@ -3,3 +3,4 @@
  */
 export { buildJsonOk, buildJsonError, buildJson, outputJson, outputYaml, outputPlain, internalRedactSecrets, parseSize } from "./format.js";
 export { log, span, initJson, initPlain, initYaml } from "./afdata_logging.js";
+export { type OutputFormat, cliParseOutput, cliParseLogFilters, cliOutput, buildCliError } from "./cli.js";

package/dist/index.js

@@ -3,3 +3,4 @@
  */
 export { buildJsonOk, buildJsonError, buildJson, outputJson, outputYaml, outputPlain, internalRedactSecrets, parseSize } from "./format.js";
 export { log, span, initJson, initPlain, initYaml } from "./afdata_logging.js";
+export { cliParseOutput, cliParseLogFilters, cliOutput, buildCliError } from "./cli.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-first-data",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents",
   "license": "MIT",
   "repository": {