agent-first-data 0.14.2 → 0.16.0

package/dist/index.d.ts

@@ -1,7 +1,5 @@
 /**
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
-export { buildJsonOk, buildJsonError, buildJson, type JsonValue, RedactionPolicy, type RedactionOptions, OutputStyle, type OutputOptions, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, redactSecretsInPlace, redactSecretsInPlaceWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, redactUrlSecrets, redactUrlSecretsWithOptions, parseSize, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, } from "./format.js";
-export { log, span, initJson, initPlain, initYaml } from "./afdata_logging.js";
-export { type OutputFormat, cliParseOutput, cliParseLogFilters, cliOutput, cliOutputWithOptions, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";
-export { type SkillSpec, type SkillAction, type SkillScope, type SkillAgentSelection, type SkillAgent, type SkillOptions, type SkillTargetStatus, type SkillUninstallStatus, type SkillReport, SkillError, runSkillAdmin, } from "./skill.js";
+export { jsonResult, jsonError, jsonProgress, jsonLog, Event, EventBuildError, JsonResultBuilder, JsonErrorBuilder, JsonProgressBuilder, JsonLogBuilder, type LogLevel, validateProtocolEvent, validateProtocolStream, decodeProtocolEvent, type DecodedEvent, type DecodedResult, type DecodedError, type DecodedProgress, type DecodedLog, EventDecodeError, type JsonValue, RedactionPolicy, OutputStyle, type OutputOptions, outputOptionsForPolicy, outputJson, outputYaml, outputPlain, redactedValue, redactUrlSecrets, parseSize, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, } from "./format.js";
+export { type OutputFormat, type CliEventWriter, CliEmitter, LogFilters, cliParseOutput, cliParseLogFilters, cliOutput, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";

package/dist/index.js

@@ -1,7 +1,5 @@
 /**
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
-export { buildJsonOk, buildJsonError, buildJson, RedactionPolicy, OutputStyle, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, redactSecretsInPlace, redactSecretsInPlaceWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, redactUrlSecrets, redactUrlSecretsWithOptions, parseSize, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, } from "./format.js";
-export { log, span, initJson, initPlain, initYaml } from "./afdata_logging.js";
-export { cliParseOutput, cliParseLogFilters, cliOutput, cliOutputWithOptions, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";
-export { SkillError, runSkillAdmin, } from "./skill.js";
+export { jsonResult, jsonError, jsonProgress, jsonLog, Event, EventBuildError, JsonResultBuilder, JsonErrorBuilder, JsonProgressBuilder, JsonLogBuilder, validateProtocolEvent, validateProtocolStream, decodeProtocolEvent, EventDecodeError, RedactionPolicy, OutputStyle, outputOptionsForPolicy, outputJson, outputYaml, outputPlain, redactedValue, redactUrlSecrets, parseSize, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, } from "./format.js";
+export { CliEmitter, LogFilters, cliParseOutput, cliParseLogFilters, cliOutput, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";

package/dist/stream_redirect.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Optional stdout/stderr file redirection for AFDATA CLIs.
+ *
+ * This redirects Node's process stdout/stderr file descriptors to append-only
+ * files. It is not an AFDATA formatter and does not convert stderr diagnostics
+ * into JSON.
+ */
+export declare const STDOUT_FILE_ARG = "--stdout-file";
+export declare const STDERR_FILE_ARG = "--stderr-file";
+export interface StreamRedirectConfig {
+    stdoutFile?: string;
+    stderrFile?: string;
+}
+export interface InstalledStreamRedirect {
+    stdoutFile?: string;
+    stderrFile?: string;
+    processLifetime: true;
+}
+export declare function configFromRawArgs(args: readonly string[]): StreamRedirectConfig | undefined;
+export declare function installStreamRedirectFromRawArgs(args?: string[]): InstalledStreamRedirect | undefined;
+export declare function installStreamRedirect(config: StreamRedirectConfig): InstalledStreamRedirect | undefined;

package/dist/stream_redirect.js

@@ -0,0 +1,128 @@
+/**
+ * Optional stdout/stderr file redirection for AFDATA CLIs.
+ *
+ * This redirects Node's process stdout/stderr file descriptors to append-only
+ * files. It is not an AFDATA formatter and does not convert stderr diagnostics
+ * into JSON.
+ */
+import { closeSync, constants, existsSync, lstatSync, openSync } from "node:fs";
+export const STDOUT_FILE_ARG = "--stdout-file";
+export const STDERR_FILE_ARG = "--stderr-file";
+let installed = false;
+const fillerFds = [];
+export function configFromRawArgs(args) {
+    const config = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--")
+            break;
+        if (arg === STDOUT_FILE_ARG) {
+            const [value, next] = takeValue(args, i, STDOUT_FILE_ARG);
+            config.stdoutFile = value;
+            i = next;
+        }
+        else if (arg.startsWith(`${STDOUT_FILE_ARG}=`)) {
+            config.stdoutFile = arg.slice(STDOUT_FILE_ARG.length + 1);
+        }
+        else if (arg === STDERR_FILE_ARG) {
+            const [value, next] = takeValue(args, i, STDERR_FILE_ARG);
+            config.stderrFile = value;
+            i = next;
+        }
+        else if (arg.startsWith(`${STDERR_FILE_ARG}=`)) {
+            config.stderrFile = arg.slice(STDERR_FILE_ARG.length + 1);
+        }
+    }
+    validateConfig(config);
+    return config.stdoutFile === undefined && config.stderrFile === undefined ? undefined : config;
+}
+export function installStreamRedirectFromRawArgs(args = process.argv.slice(2)) {
+    const config = configFromRawArgs(args);
+    return config === undefined ? undefined : installStreamRedirect(config);
+}
+export function installStreamRedirect(config) {
+    validateConfig(config);
+    if (config.stdoutFile === undefined && config.stderrFile === undefined) {
+        return undefined;
+    }
+    if (installed) {
+        throw new Error("stream redirection already installed");
+    }
+    installed = true;
+    // Validate both files before changing fd 1/2. Node does not expose dup2, so
+    // this helper is intended for process-lifetime CLI setup rather than scoped
+    // redirection that can be restored later.
+    validateWritable(config.stdoutFile);
+    validateWritable(config.stderrFile);
+    redirectFd(1, config.stdoutFile);
+    redirectFd(2, config.stderrFile);
+    return {
+        stdoutFile: config.stdoutFile,
+        stderrFile: config.stderrFile,
+        processLifetime: true,
+    };
+}
+function validateConfig(config) {
+    if (config.stdoutFile === "") {
+        throw new Error("--stdout-file must not be empty");
+    }
+    if (config.stderrFile === "") {
+        throw new Error("--stderr-file must not be empty");
+    }
+}
+function takeValue(args, idx, flag) {
+    const next = idx + 1;
+    const value = args[next];
+    if (value === undefined || value.startsWith("--")) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return [value, next];
+}
+function validateWritable(path) {
+    if (path === undefined)
+        return;
+    const fd = openAppendSecure(path);
+    closeSync(fd);
+}
+function redirectFd(targetFd, path) {
+    if (path === undefined)
+        return;
+    fillLowerFds(targetFd);
+    try {
+        closeSync(targetFd);
+    }
+    catch {
+        // The target fd may already be closed in unusual embedding environments.
+    }
+    const fd = openAppendSecure(path);
+    if (fd !== targetFd) {
+        closeSync(fd);
+        throw new Error(`failed to redirect fd ${targetFd} to ${path}`);
+    }
+}
+function openAppendSecure(path) {
+    const nofollow = constants.O_NOFOLLOW ?? 0;
+    if (existsSync(path)) {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink()) {
+            throw new Error("stream redirection target must not be a symbolic link");
+        }
+        if (!stat.isFile()) {
+            throw new Error("stream redirection target must be a regular file");
+        }
+        return openSync(path, constants.O_WRONLY | constants.O_APPEND | nofollow);
+    }
+    return openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_EXCL | nofollow, 0o600);
+}
+function fillLowerFds(targetFd) {
+    const nullDevice = process.platform === "win32" ? "NUL" : "/dev/null";
+    while (true) {
+        const fd = openSync(nullDevice, "r");
+        if (fd < targetFd) {
+            fillerFds.push(fd);
+            continue;
+        }
+        closeSync(fd);
+        return;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-first-data",
-  "version": "0.14.2",
+  "version": "0.16.0",
   "description": "A naming convention that lets AI agents understand your data without being told what it means.",
   "license": "MIT",
   "repository": {
@@ -15,13 +15,18 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
-    "./afdata_logging": {
-      "import": "./dist/afdata_logging.js",
-      "types": "./dist/afdata_logging.d.ts"
+    "./skill": {
+      "import": "./dist/skill.js",
+      "types": "./dist/skill.d.ts"
+    },
+    "./stream-redirect": {
+      "import": "./dist/stream_redirect.js",
+      "types": "./dist/stream_redirect.d.ts"
     }
   },
   "files": [
     "dist",
+    "assets",
     "README.md"
   ],
   "scripts": {
@@ -30,8 +35,8 @@
     "test": "tsx --test src/*.test.ts examples/agent_cli.ts"
   },
   "devDependencies": {
-    "@types/node": "^25.9.3",
-    "tsx": "^4.22.4",
-    "typescript": "^6.0.3"
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.0",
+    "typescript": "^7.0.2"
   }
 }

package/dist/afdata_logging.d.ts

@@ -1,44 +0,0 @@
-/**
- * AFDATA-compliant structured logging.
- *
- * Outputs log events using agent-first-data formatting functions:
- * - JSON: single-line JSONL via outputJson (secrets redacted, original keys)
- * - Plain: single-line logfmt via outputPlain (keys stripped, values formatted)
- * - YAML: multi-line via outputYaml (keys stripped, values formatted)
- *
- * Span fields are carried via AsyncLocalStorage (async-safe).
- *
- * Usage:
- *   import { log, span, initJson, initPlain, initYaml } from "agent-first-data/afdata_logging";
- *   initJson();  // or initPlain() or initYaml()
- *   log.info("Server started");
- *   await span({ request_id: "abc" }, async () => {
- *     log.info("Processing", { domain: "example.com" });
- *   });
- */
-type LoggingRedactionOptions = {
-    secretNames?: readonly string[];
-};
-/** Set log output to single-line JSONL (secrets redacted, original keys). */
-export declare function initJson(options?: LoggingRedactionOptions): void;
-/** Set log output to single-line logfmt (keys stripped, values formatted). */
-export declare function initPlain(options?: LoggingRedactionOptions): void;
-/** Set log output to multi-line YAML (keys stripped, values formatted). */
-export declare function initYaml(options?: LoggingRedactionOptions): void;
-/**
- * AFDATA logger. Each method outputs a single log line to stdout.
- * Format is controlled by initJson/initPlain/initYaml (default: JSON).
- */
-export declare const log: {
-    trace: (msg: string, fields?: Record<string, unknown>) => void;
-    debug: (msg: string, fields?: Record<string, unknown>) => void;
-    info: (msg: string, fields?: Record<string, unknown>) => void;
-    warn: (msg: string, fields?: Record<string, unknown>) => void;
-    error: (msg: string, fields?: Record<string, unknown>) => void;
-};
-/**
- * Run fn within a span that adds fields to all log events.
- * Spans nest: inner spans inherit and can override outer span fields.
- */
-export declare function span<T>(fields: Record<string, unknown>, fn: () => T): T;
-export {};

package/dist/afdata_logging.js

@@ -1,90 +0,0 @@
-/**
- * AFDATA-compliant structured logging.
- *
- * Outputs log events using agent-first-data formatting functions:
- * - JSON: single-line JSONL via outputJson (secrets redacted, original keys)
- * - Plain: single-line logfmt via outputPlain (keys stripped, values formatted)
- * - YAML: multi-line via outputYaml (keys stripped, values formatted)
- *
- * Span fields are carried via AsyncLocalStorage (async-safe).
- *
- * Usage:
- *   import { log, span, initJson, initPlain, initYaml } from "agent-first-data/afdata_logging";
- *   initJson();  // or initPlain() or initYaml()
- *   log.info("Server started");
- *   await span({ request_id: "abc" }, async () => {
- *     log.info("Processing", { domain: "example.com" });
- *   });
- */
-import { AsyncLocalStorage } from "node:async_hooks";
-import { outputJsonWithOptions, outputYamlWithOptions, outputPlainWithOptions, } from "./format.js";
-const spanStore = new AsyncLocalStorage();
-let currentFormat = "json";
-let currentRedaction = {};
-function setFormat(format, options) {
-    currentFormat = format;
-    currentRedaction = options?.secretNames ? { secretNames: options.secretNames } : {};
-}
-/** Set log output to single-line JSONL (secrets redacted, original keys). */
-export function initJson(options) { setFormat("json", options); }
-/** Set log output to single-line logfmt (keys stripped, values formatted). */
-export function initPlain(options) { setFormat("plain", options); }
-/** Set log output to multi-line YAML (keys stripped, values formatted). */
-export function initYaml(options) { setFormat("yaml", options); }
-function emit(level, message, fields) {
-    const entry = {
-        timestamp_epoch_ms: Date.now(),
-        message,
-        code: "log",
-        level,
-    };
-    // Span fields (from AsyncLocalStorage)
-    const spanFields = spanStore.getStore();
-    if (spanFields) {
-        for (const [k, v] of Object.entries(spanFields)) {
-            entry[k] = v;
-        }
-    }
-    // Event fields override span fields, except protocol code is always "log".
-    if (fields) {
-        for (const [k, v] of Object.entries(fields)) {
-            if (k === "code")
-                continue;
-            entry[k] = v;
-        }
-    }
-    // Format using the library's own output functions
-    const value = entry;
-    let line;
-    switch (currentFormat) {
-        case "plain":
-            line = outputPlainWithOptions(value, { redaction: currentRedaction });
-            break;
-        case "yaml":
-            line = outputYamlWithOptions(value, { redaction: currentRedaction });
-            break;
-        default:
-            line = outputJsonWithOptions(value, { redaction: currentRedaction });
-            break;
-    }
-    process.stdout.write(line + "\n");
-}
-/**
- * AFDATA logger. Each method outputs a single log line to stdout.
- * Format is controlled by initJson/initPlain/initYaml (default: JSON).
- */
-export const log = {
-    trace: (msg, fields) => emit("trace", msg, fields),
-    debug: (msg, fields) => emit("debug", msg, fields),
-    info: (msg, fields) => emit("info", msg, fields),
-    warn: (msg, fields) => emit("warn", msg, fields),
-    error: (msg, fields) => emit("error", msg, fields),
-};
-/**
- * Run fn within a span that adds fields to all log events.
- * Spans nest: inner spans inherit and can override outer span fields.
- */
-export function span(fields, fn) {
-    const parent = spanStore.getStore() ?? {};
-    return spanStore.run({ ...parent, ...fields }, fn);
-}