agent-first-data 0.13.0 → 0.13.2

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`, `isValidRfc3339Date`, `isValidRfc3339Time`, `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/format.d.ts

@@ -1,10 +1,11 @@
 /**
  * AFDATA output formatting and protocol templates.
  *
- * 19 public APIs and 4 types: protocol builders, value redactors (copy and
+ * 21 public APIs and 4 types: protocol builders, value redactors (copy and
  * in-place; cover _secret and _url fields), output formatters, URL-string
  * redactors (redactUrlSecrets / WithOptions), parseSize, normalizeUtcOffset,
- * RedactionPolicy, RedactionOptions, OutputStyle, and OutputOptions.
+ * isValidRfc3339Date, isValidRfc3339Time, RedactionPolicy, RedactionOptions,
+ * OutputStyle, and OutputOptions.
  */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
@@ -94,3 +95,7 @@ export declare function parseSize(s: string): number | null;
  * are intentionally out of scope.
  */
 export declare function normalizeUtcOffset(value: string): string | null;
+/** Return true when value is an RFC 3339 full-date (YYYY-MM-DD). */
+export declare function isValidRfc3339Date(value: string): boolean;
+/** Return true when value is an RFC 3339 partial-time (HH:MM:SS[.fraction]). */
+export declare function isValidRfc3339Time(value: string): boolean;

package/dist/format.js

@@ -1,10 +1,11 @@
 /**
  * AFDATA output formatting and protocol templates.
  *
- * 19 public APIs and 4 types: protocol builders, value redactors (copy and
+ * 21 public APIs and 4 types: protocol builders, value redactors (copy and
  * in-place; cover _secret and _url fields), output formatters, URL-string
  * redactors (redactUrlSecrets / WithOptions), parseSize, normalizeUtcOffset,
- * RedactionPolicy, RedactionOptions, OutputStyle, and OutputOptions.
+ * isValidRfc3339Date, isValidRfc3339Time, RedactionPolicy, RedactionOptions,
+ * OutputStyle, and OutputOptions.
  */
 // ═══════════════════════════════════════════
 // Public API: Protocol Builders
@@ -202,6 +203,32 @@ export function normalizeUtcOffset(value) {
         return "UTC";
     return `${s[0]}${hours.toString().padStart(2, "0")}:${minutes.toString().padStart(2, "0")}`;
 }
+/** Return true when value is an RFC 3339 full-date (YYYY-MM-DD). */
+export function isValidRfc3339Date(value) {
+    if (value.length !== 10 || value[4] !== "-" || value[7] !== "-")
+        return false;
+    const year = parseFixedDigits(value.slice(0, 4));
+    const month = parseFixedDigits(value.slice(5, 7));
+    const day = parseFixedDigits(value.slice(8, 10));
+    if (year === null || month === null || day === null)
+        return false;
+    return month >= 1 && month <= 12 && day >= 1 && day <= daysInMonth(year, month);
+}
+/** Return true when value is an RFC 3339 partial-time (HH:MM:SS[.fraction]). */
+export function isValidRfc3339Time(value) {
+    if (value.length < 8 || value[2] !== ":" || value[5] !== ":")
+        return false;
+    const hour = parseFixedDigits(value.slice(0, 2));
+    const minute = parseFixedDigits(value.slice(3, 5));
+    const second = parseFixedDigits(value.slice(6, 8));
+    if (hour === null || minute === null || second === null)
+        return false;
+    if (hour > 23 || minute > 59 || second > 59)
+        return false;
+    if (value.length === 8)
+        return true;
+    return value[8] === "." && value.length > 9 && /^[0-9]+$/.test(value.slice(9));
+}
 function parseUtcOffsetBody(body) {
     if (!body)
         return null;
@@ -224,6 +251,23 @@ function parseUtcOffsetBody(body) {
         return [Number(body.slice(0, 2)), Number(body.slice(2))];
     return null;
 }
+function parseFixedDigits(value) {
+    if (!/^[0-9]+$/.test(value))
+        return null;
+    return Number(value);
+}
+function daysInMonth(year, month) {
+    if ([1, 3, 5, 7, 8, 10, 12].includes(month))
+        return 31;
+    if ([4, 6, 9, 11].includes(month))
+        return 30;
+    if (month === 2)
+        return isLeapYear(year) ? 29 : 28;
+    return 0;
+}
+function isLeapYear(year) {
+    return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+}
 const DEFAULT_CONTEXT = {
     secretNames: new Set(),
 };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * 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, } from "./format.js";
+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, } 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

@@ -1,7 +1,7 @@
 /**
  * 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, } from "./format.js";
+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, } 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.2",
   "description": "A naming convention that lets AI agents understand your data without being told what it means.",
   "license": "MIT",
   "repository": {