agent-first-data 0.13.1 → 0.14.0

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`, `buildCliError`, `buildCliVersion`, and `cliHandleVersionOrContinue`.
+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`.
 
@@ -41,7 +41,7 @@ initJson({ secretNames: ["authorization"] });
 
 ## Reference
 
-- Full convention and API groups: [../docs/overview.md](../docs/overview.md)
-- Formal cross-language contract: [../spec/agent-first-data.md](../spec/agent-first-data.md)
-- Conformance fixtures: [../spec/fixtures](../spec/fixtures)
-- Agent skill: [../skills/agent-first-data.md](../skills/agent-first-data.md)
+- Full convention and API groups: [docs/overview.md](https://github.com/agentfirstkit/agent-first-data/blob/main/docs/overview.md)
+- Formal cross-language contract: [spec/agent-first-data.md](https://github.com/agentfirstkit/agent-first-data/blob/main/spec/agent-first-data.md)
+- Conformance fixtures: [spec/fixtures](https://github.com/agentfirstkit/agent-first-data/tree/main/spec/fixtures)
+- Agent skill: [skills/agent-first-data.md](https://github.com/agentfirstkit/agent-first-data/blob/main/skills/agent-first-data.md)

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, 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, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";
 export { SkillError, runSkillAdmin, } from "./skill.js";

package/dist/skill.d.ts

@@ -3,7 +3,7 @@
  *
  * A spore that embeds its `SKILL.md` describes itself with a {@link SkillSpec} and calls
  * {@link runSkillAdmin} to install, uninstall, or report status of that skill across
- * supported coding agents (Codex, Claude Code, opencode).
+ * supported coding agents (Codex, Claude Code, opencode, Hermes).
  *
  * The function performs the filesystem work and returns the protocol value (rendered by
  * the caller with `cliOutput`) or throws a {@link SkillError}. It never writes to
@@ -26,11 +26,11 @@ export interface SkillSpec {
 /** The skill action to perform. */
 export type SkillAction = "status" | "install" | "uninstall";
 /** Where to install the skill. */
-export type SkillScope = "personal" | "project";
+export type SkillScope = "personal" | "workspace";
 /** Which agent target(s) to manage. */
-export type SkillAgentSelection = "all" | "codex" | "claude-code" | "opencode";
+export type SkillAgentSelection = "all" | "codex" | "claude-code" | "opencode" | "hermes";
 /** A concrete agent a skill is installed for (no `all`). */
-export type SkillAgent = "codex" | "claude-code" | "opencode";
+export type SkillAgent = "codex" | "claude-code" | "opencode" | "hermes";
 /** Options shared by every skill action. */
 export interface SkillOptions {
     agent: SkillAgentSelection;

package/dist/skill.js

@@ -3,7 +3,7 @@
  *
  * A spore that embeds its `SKILL.md` describes itself with a {@link SkillSpec} and calls
  * {@link runSkillAdmin} to install, uninstall, or report status of that skill across
- * supported coding agents (Codex, Claude Code, opencode).
+ * supported coding agents (Codex, Claude Code, opencode, Hermes).
  *
  * The function performs the filesystem work and returns the protocol value (rendered by
  * the caller with `cliOutput`) or throws a {@link SkillError}. It never writes to
@@ -128,20 +128,19 @@ function resolveTargets(spec, options) {
             resolveTarget(spec, "codex", "personal", undefined),
             resolveTarget(spec, "claude-code", "personal", undefined),
             resolveTarget(spec, "opencode", "personal", undefined),
+            resolveTarget(spec, "hermes", "personal", undefined),
         ];
     }
-    // Codex has no project scope, so --agent all --scope project skips it.
-    if (agent === "all" && scope === "project") {
+    if (agent === "all" && scope === "workspace") {
         return [
-            resolveTarget(spec, "claude-code", "project", undefined),
-            resolveTarget(spec, "opencode", "project", undefined),
+            resolveTarget(spec, "codex", "workspace", undefined),
+            resolveTarget(spec, "claude-code", "workspace", undefined),
+            resolveTarget(spec, "opencode", "workspace", undefined),
+            resolveTarget(spec, "hermes", "workspace", undefined),
         ];
     }
-    if (agent === "codex" && scope === "project") {
-        throw new SkillError("Codex project skill scope is not supported", "use personal scope for Codex, or --agent claude-code/opencode --scope project");
-    }
     if (agent === "codex") {
-        return [resolveTarget(spec, "codex", "personal", options.skillsDir)];
+        return [resolveTarget(spec, "codex", scope, options.skillsDir)];
     }
     if (agent === "claude-code") {
         return [resolveTarget(spec, "claude-code", scope, options.skillsDir)];
@@ -149,6 +148,9 @@ function resolveTargets(spec, options) {
     if (agent === "opencode") {
         return [resolveTarget(spec, "opencode", scope, options.skillsDir)];
     }
+    if (agent === "hermes") {
+        return [resolveTarget(spec, "hermes", scope, options.skillsDir)];
+    }
     throw new SkillError(`invalid --agent '${agent}'`);
 }
 function resolveTarget(spec, agent, scope, skillsDir) {
@@ -164,8 +166,8 @@ function resolveTarget(spec, agent, scope, skillsDir) {
 }
 function defaultSkillsDir(agent, scope) {
     if (agent === "codex") {
-        if (scope === "project") {
-            throw new SkillError("Codex project skill scope is not supported");
+        if (scope !== "personal") {
+            return join(process.cwd(), ".codex", "skills");
         }
         const codexHome = process.env["CODEX_HOME"];
         if (codexHome !== undefined) {
@@ -174,20 +176,30 @@ function defaultSkillsDir(agent, scope) {
         return join(homeDir(), ".codex", "skills");
     }
     if (agent === "claude-code") {
-        if (scope === "project") {
+        if (scope !== "personal") {
             return join(process.cwd(), ".claude", "skills");
         }
         return join(homeDir(), ".claude", "skills");
     }
-    // opencode
-    if (scope === "project") {
-        return join(process.cwd(), ".opencode", "skills");
+    if (agent === "opencode") {
+        if (scope !== "personal") {
+            return join(process.cwd(), ".opencode", "skills");
+        }
+        const xdg = process.env["XDG_CONFIG_HOME"];
+        if (xdg !== undefined) {
+            return join(xdg, "opencode", "skills");
+        }
+        return join(homeDir(), ".config", "opencode", "skills");
+    }
+    // hermes
+    if (scope !== "personal") {
+        return join(process.cwd(), ".hermes", "skills");
     }
-    const xdg = process.env["XDG_CONFIG_HOME"];
-    if (xdg !== undefined) {
-        return join(xdg, "opencode", "skills");
+    const hermesHome = process.env["HERMES_HOME"];
+    if (hermesHome !== undefined) {
+        return join(hermesHome, "skills");
     }
-    return join(homeDir(), ".config", "opencode", "skills");
+    return join(homeDir(), ".hermes", "skills");
 }
 function targetStatus(spec, target) {
     const st = lstatOrNull(target.skillPath);

package/package.json

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