agent-first-data 0.15.0 → 0.16.0

package/dist/index.d.ts

@@ -1,8 +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 { STDOUT_FILE_ARG, STDERR_FILE_ARG, type StreamRedirectConfig, type InstalledStreamRedirect, configFromRawArgs as streamRedirectConfigFromRawArgs, installStreamRedirect, installStreamRedirectFromRawArgs, } from "./stream_redirect.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,8 +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 { STDOUT_FILE_ARG, STDERR_FILE_ARG, configFromRawArgs as streamRedirectConfigFromRawArgs, installStreamRedirect, installStreamRedirectFromRawArgs, } from "./stream_redirect.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.js

@@ -5,7 +5,7 @@
  * files. It is not an AFDATA formatter and does not convert stderr diagnostics
  * into JSON.
  */
-import { closeSync, openSync } from "node:fs";
+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;
@@ -81,7 +81,7 @@ function takeValue(args, idx, flag) {
 function validateWritable(path) {
     if (path === undefined)
         return;
-    const fd = openSync(path, "a");
+    const fd = openAppendSecure(path);
     closeSync(fd);
 }
 function redirectFd(targetFd, path) {
@@ -94,12 +94,26 @@ function redirectFd(targetFd, path) {
     catch {
         // The target fd may already be closed in unusual embedding environments.
     }
-    const fd = openSync(path, "a");
+    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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-first-data",
-  "version": "0.15.0",
+  "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,17 +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": {
+    "./stream-redirect": {
       "import": "./dist/stream_redirect.js",
       "types": "./dist/stream_redirect.d.ts"
     }
   },
   "files": [
     "dist",
+    "assets",
     "README.md"
   ],
   "scripts": {
@@ -34,8 +35,8 @@
     "test": "tsx --test src/*.test.ts examples/agent_cli.ts"
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
-    "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);
-}