agent-first-data 0.13.0 → 0.13.1

package/README.md

@@ -20,7 +20,7 @@ console.log(outputJson(value));
 console.log(outputPlain(value));
 ```
 
-Useful names use TypeScript casing: `outputJson`, `outputYaml`, `outputPlain`, `outputJsonWithOptions`, `redactedValue`, `redactSecretsInPlace`, `redactUrlSecrets`, `parseSize`, `normalizeUtcOffset`, `cliParseOutput`, `cliOutput`, and `buildCliError`.
+Useful names use TypeScript casing: `outputJson`, `outputYaml`, `outputPlain`, `outputJsonWithOptions`, `redactedValue`, `redactSecretsInPlace`, `redactUrlSecrets`, `parseSize`, `normalizeUtcOffset`, `cliParseOutput`, `cliOutput`, `buildCliError`, `buildCliVersion`, and `cliHandleVersionOrContinue`.
 
 Logging is available through `initJson`, `initPlain`, `initYaml`, `span`, and `log`.
 
@@ -37,6 +37,7 @@ initJson({ secretNames: ["authorization"] });
 - YAML/plain quote and escape keys as well as values, sort by UTF-16 code unit order, and render nested objects in arrays as canonical JSON.
 - Logging records use `code: "log"` plus a separate `level` field, so error-level logs are not terminal protocol errors.
 - `build_cli_error(message, hint?)` returns `{code:"error", error: message, hint?}` only.
+- Use `cliHandleVersionOrContinue()` before argument parsing so bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.
 
 ## Reference
 

package/dist/cli.d.ts

@@ -34,6 +34,19 @@ export declare function cliOutput(value: JsonValue, format: OutputFormat): strin
  * JSON ignores OutputStyle and preserves original keys and values after redaction.
  */
 export declare function cliOutputWithOptions(value: JsonValue, format: OutputFormat, outputOptions: OutputOptions): string;
+/** Build a standard CLI version value. */
+export declare function buildCliVersion(version: string): JsonValue;
+/**
+ * Render CLI version output.
+ * Pass an OutputFormat for AFDATA JSON/YAML/plain. Pass null to preserve
+ * conventional "<name> <version>" text.
+ */
+export declare function cliRenderVersion(name: string, version: string, format?: OutputFormat | null): string;
+/**
+ * Render version output if --version/-V is present; otherwise return undefined.
+ * Throws for malformed version requests, for example `--version --output xml`.
+ */
+export declare function cliHandleVersionOrContinue(rawArgs: string[], name: string, version: string, defaultOutput?: OutputFormat | null, outputFlag?: string, allowOutputFormat?: boolean): string | undefined;
 /**
  * Build a standard CLI parse error value.
  * Use when flag parsing fails or a flag value is invalid.

package/dist/cli.js

@@ -1,7 +1,7 @@
 /**
  * AFDATA CLI helpers — output format parsing, log filter normalization, error building.
  */
-import { outputJson, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, } from "./format.js";
+import { buildJson, outputJson, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, } from "./format.js";
 /**
  * Parse the --output flag value into an OutputFormat.
  * Throws on unknown values; catch and pass message to buildCliError.
@@ -58,6 +58,68 @@ export function cliOutputWithOptions(value, format, outputOptions) {
         return outputPlainWithOptions(value, outputOptions);
     return outputJsonWithOptions(value, outputOptions);
 }
+/** Build a standard CLI version value. */
+export function buildCliVersion(version) {
+    return buildJson("version", { version });
+}
+/**
+ * Render CLI version output.
+ * Pass an OutputFormat for AFDATA JSON/YAML/plain. Pass null to preserve
+ * conventional "<name> <version>" text.
+ */
+export function cliRenderVersion(name, version, format = null) {
+    const rendered = format === null ? `${name} ${version}` : cliOutput(buildCliVersion(version), format);
+    return `${rendered.replace(/\n+$/u, "")}\n`;
+}
+/**
+ * Render version output if --version/-V is present; otherwise return undefined.
+ * Throws for malformed version requests, for example `--version --output xml`.
+ */
+export function cliHandleVersionOrContinue(rawArgs, name, version, defaultOutput = null, outputFlag = "--output", allowOutputFormat = true) {
+    let versionRequested = false;
+    let outputFormat;
+    let outputError;
+    for (let i = 0; i < rawArgs.length;) {
+        const arg = rawArgs[i];
+        if (arg === "--")
+            break;
+        if (arg === "--version" || arg === "-V") {
+            versionRequested = true;
+            i += 1;
+            continue;
+        }
+        if (allowOutputFormat && (arg === outputFlag || arg.startsWith(`${outputFlag}=`))) {
+            let value;
+            let step = 1;
+            if (arg.startsWith(`${outputFlag}=`)) {
+                value = arg.slice(outputFlag.length + 1);
+            }
+            else if (rawArgs[i + 1] !== undefined && !rawArgs[i + 1].startsWith("-")) {
+                value = rawArgs[i + 1];
+                step = 2;
+            }
+            if (value === undefined) {
+                outputError = new Error(`missing value for ${outputFlag}: expected json, yaml, or plain`);
+            }
+            else {
+                try {
+                    outputFormat = cliParseOutput(value);
+                }
+                catch (e) {
+                    outputError = e;
+                }
+            }
+            i += step;
+            continue;
+        }
+        i += 1;
+    }
+    if (!versionRequested)
+        return undefined;
+    if (outputError !== undefined)
+        throw outputError;
+    return cliRenderVersion(name, version, allowOutputFormat && outputFormat !== undefined ? outputFormat : defaultOutput);
+}
 /**
  * Build a standard CLI parse error value.
  * Use when flag parsing fails or a flag value is invalid.

package/dist/index.d.ts

@@ -3,5 +3,5 @@
  */
 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, } from "./format.js";
 export { log, span, initJson, initPlain, initYaml } from "./afdata_logging.js";
-export { type OutputFormat, cliParseOutput, cliParseLogFilters, cliOutput, cliOutputWithOptions, buildCliError, } from "./cli.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";

package/dist/index.js

@@ -3,5 +3,5 @@
  */
 export { buildJsonOk, buildJsonError, buildJson, RedactionPolicy, OutputStyle, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, redactSecretsInPlace, redactSecretsInPlaceWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, redactUrlSecrets, redactUrlSecretsWithOptions, parseSize, normalizeUtcOffset, } from "./format.js";
 export { log, span, initJson, initPlain, initYaml } from "./afdata_logging.js";
-export { cliParseOutput, cliParseLogFilters, cliOutput, cliOutputWithOptions, buildCliError, } from "./cli.js";
+export { cliParseOutput, cliParseLogFilters, cliOutput, cliOutputWithOptions, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";
 export { SkillError, runSkillAdmin, } from "./skill.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-first-data",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "A naming convention that lets AI agents understand your data without being told what it means.",
   "license": "MIT",
   "repository": {