agent-first-data 0.12.2 → 0.13.1

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, internalRedactSecrets, internalRedactSecretsWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, redactUrlSecrets, redactUrlSecretsWithOptions, parseSize, } 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, } 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, internalRedactSecrets, internalRedactSecretsWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, redactUrlSecrets, redactUrlSecretsWithOptions, parseSize, } 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, } 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/dist/skill.js

@@ -10,8 +10,11 @@
  * stdout/stderr itself.
  */
 import * as fs from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 const SKILL_FILE_NAME = "SKILL.md";
+const FNV1A64_OFFSET = 0xcbf29ce484222325n;
+const FNV1A64_PRIME = 0x100000001b3n;
+const FNV1A64_MASK = 0xffffffffffffffffn;
 /** A skill admin failure with an operator-facing message and optional hint. */
 export class SkillError extends Error {
     hint;
@@ -27,6 +30,7 @@ export class SkillError extends Error {
  * {@link SkillError}. Does not touch stdout/stderr.
  */
 export function runSkillAdmin(spec, action, options) {
+    validateSpec(spec);
     switch (action) {
         case "status":
             return status(spec, options);
@@ -57,10 +61,18 @@ function install(spec, options) {
     const installed = [];
     for (const target of targets) {
         fs.mkdirSync(target.skillDir, { recursive: true });
-        if (fs.existsSync(target.skillPath) && !isManagedOrBundledSkill(spec, target.skillPath) && !options.force) {
-            throw new SkillError(`refusing to overwrite unmanaged skill at ${target.skillPath}`, "pass --force to replace it, or choose another --skills-dir");
+        const st = lstatOrNull(target.skillPath);
+        if (st !== null) {
+            if (st.isSymbolicLink()) {
+                if (!options.force) {
+                    throw new SkillError(`refusing to overwrite symlinked skill at ${target.skillPath}`, "pass --force to replace the symlink itself, or choose another --skills-dir");
+                }
+            }
+            else if (!isManagedOrBundledSkill(spec, target.skillPath) && !options.force) {
+                throw new SkillError(`refusing to overwrite unmanaged skill at ${target.skillPath}`, "pass --force to replace it, or choose another --skills-dir");
+            }
         }
-        fs.writeFileSync(target.skillPath, content);
+        writeSkillAtomic(target, content);
         validateInstalledSkill(spec, target.skillPath);
         installed.push(targetStatus(spec, target));
     }
@@ -76,11 +88,17 @@ function uninstall(spec, options) {
     const targets = resolveTargets(spec, options);
     const removed = [];
     for (const target of targets) {
-        if (!fs.existsSync(target.skillPath)) {
+        const st = lstatOrNull(target.skillPath);
+        if (st === null) {
             removed.push(targetUninstallStatus(target, false));
             continue;
         }
-        if (!isManagedOrBundledSkill(spec, target.skillPath) && !options.force) {
+        if (st.isSymbolicLink()) {
+            if (!options.force) {
+                throw new SkillError(`refusing to remove symlinked skill at ${target.skillPath}`, "pass --force to remove the symlink itself");
+            }
+        }
+        else if (!isManagedOrBundledSkill(spec, target.skillPath) && !options.force) {
             throw new SkillError(`refusing to remove unmanaged skill at ${target.skillPath}`, `only skills generated by ${spec.markerSlug} skill install can be removed without --force`);
         }
         fs.rmSync(target.skillPath);
@@ -172,16 +190,20 @@ function defaultSkillsDir(agent, scope) {
     return join(homeDir(), ".config", "opencode", "skills");
 }
 function targetStatus(spec, target) {
-    const installed = isFile(target.skillPath);
+    const st = lstatOrNull(target.skillPath);
+    const installed = st !== null;
     let valid = false;
     let current = false;
     let managed = false;
     let validationError = null;
-    if (installed) {
+    if (st?.isSymbolicLink()) {
+        validationError = "target SKILL.md is a symlink; refusing to follow it";
+    }
+    else if (st?.isFile()) {
         const text = fs.readFileSync(target.skillPath, "utf-8");
         managed = skillTextIsManagedOrBundled(spec, text);
-        current = normalizeSkillText(spec, text) === normalizeSkillText(spec, spec.source);
-        const error = validateSkillFrontmatter(text);
+        current = !skillTextHasLegacyMarker(spec, text) && normalizeSkillText(spec, text) === normalizeSkillText(spec, spec.source);
+        const error = validateSkillTextError(spec, text);
         if (error === null) {
             valid = true;
         }
@@ -189,6 +211,9 @@ function targetStatus(spec, target) {
             validationError = error;
         }
     }
+    else if (installed) {
+        validationError = "target SKILL.md is not a regular file";
+    }
     return {
         agent: target.agent,
         scope: target.scope,
@@ -216,9 +241,30 @@ function generatedBy(spec) {
 function marker(spec) {
     return `${spec.markerSlug}-managed-skill: true`;
 }
+function sourceHash(spec) {
+    let hash = FNV1A64_OFFSET;
+    for (const byte of Buffer.from(spec.source, "utf-8")) {
+        hash ^= BigInt(byte);
+        hash = (hash * FNV1A64_PRIME) & FNV1A64_MASK;
+    }
+    return hash.toString(16).padStart(16, "0");
+}
+function managedMarkerBlock(spec) {
+    const slug = spec.markerSlug;
+    return [
+        "<!--",
+        generatedBy(spec),
+        `${slug}-managed-skill: true`,
+        `${slug}-managed-skill-name: ${spec.name}`,
+        `${slug}-managed-skill-source-hash-fnv1a64: ${sourceHash(spec)}`,
+        "-->",
+    ].join("\n");
+}
+function legacyMarkerBlock(spec) {
+    return `<!-- ${generatedBy(spec)} -->\n<!-- ${marker(spec)} -->`;
+}
 function managedSkillContents(spec) {
-    const gen = generatedBy(spec);
-    const mark = marker(spec);
+    const block = managedMarkerBlock(spec);
     const lines = splitLines(spec.source);
     const out = [];
     let inserted = false;
@@ -227,12 +273,12 @@ function managedSkillContents(spec) {
         if (i === 0)
             return;
         if (!inserted && line.trim() === "---") {
-            out.push(`<!-- ${gen} -->`, `<!-- ${mark} -->`, "");
+            out.push(block, "");
             inserted = true;
         }
     });
     if (!inserted) {
-        out.push(`<!-- ${gen} -->`, `<!-- ${mark} -->`);
+        out.push(block);
     }
     return out.map((line) => line + "\n").join("");
 }
@@ -240,21 +286,37 @@ function validateInstalledSkill(spec, path) {
     validateSkillText(spec, fs.readFileSync(path, "utf-8"));
 }
 function validateSkillText(spec, text) {
-    const error = validateSkillFrontmatter(text);
+    const error = validateSkillTextError(spec, text);
     if (error !== null) {
-        throw new SkillError(`invalid ${spec.title} skill front matter: ${error}`, "quote scalar values that contain ': ', especially description");
+        const hint = error.includes("does not match expected")
+            ? `set front matter name to ${spec.name}`
+            : "quote scalar values that contain ': ', especially description";
+        throw new SkillError(`invalid ${spec.title} skill front matter: ${error}`, hint);
+    }
+}
+function validateSkillTextError(spec, text) {
+    const parsed = parseSkillFrontmatter(text);
+    if (parsed.error !== null) {
+        return parsed.error;
     }
+    if (parsed.name !== spec.name) {
+        return `name ${JSON.stringify(parsed.name)} does not match expected ${JSON.stringify(spec.name)}`;
+    }
+    return null;
 }
 function validateSkillFrontmatter(text) {
+    return parseSkillFrontmatter(text).error;
+}
+function parseSkillFrontmatter(text) {
     const lines = splitLines(text);
     if (lines.length === 0) {
-        return "missing YAML front matter";
+        return { error: "missing YAML front matter" };
     }
     if (lines[0].trim() !== "---") {
-        return "missing opening --- YAML front matter delimiter";
+        return { error: "missing opening --- YAML front matter delimiter" };
     }
     let foundEnd = false;
-    let hasName = false;
+    let name;
     let hasDescription = false;
     for (let idx = 1; idx < lines.length; idx++) {
         const line = lines[idx];
@@ -268,67 +330,84 @@ function validateSkillFrontmatter(text) {
             continue;
         }
         if (line.startsWith(" ") || line.startsWith("\t")) {
-            return `line ${lineNo}: nested YAML is not supported here`;
+            return { error: `line ${lineNo}: nested YAML is not supported here` };
         }
         const colon = line.indexOf(":");
         if (colon === -1) {
-            return `line ${lineNo}: expected key: value`;
+            return { error: `line ${lineNo}: expected key: value` };
         }
         const key = line.slice(0, colon).trim();
         if (key === "") {
-            return `line ${lineNo}: empty key`;
+            return { error: `line ${lineNo}: empty key` };
         }
         const value = line.slice(colon + 1).replace(/^\s+/, "");
         if (key === "name")
-            hasName = true;
+            name = parseFrontmatterScalar(value);
         if (key === "description")
             hasDescription = true;
         if (value.startsWith('"') || value.startsWith("'")) {
             continue;
         }
         if (value.includes(": ")) {
-            return `line ${lineNo}: unquoted scalar contains ': '; quote the value`;
+            return { error: `line ${lineNo}: unquoted scalar contains ': '; quote the value` };
         }
     }
     if (!foundEnd) {
-        return "missing closing --- YAML front matter delimiter";
+        return { error: "missing closing --- YAML front matter delimiter" };
     }
-    if (!hasName) {
-        return "missing required name field";
+    if (name === undefined) {
+        return { error: "missing required name field" };
     }
     if (!hasDescription) {
-        return "missing required description field";
+        return { error: "missing required description field" };
     }
-    return null;
+    return { name, error: null };
+}
+function parseFrontmatterScalar(value) {
+    value = value.trim();
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
 }
 function isManagedOrBundledSkill(spec, path) {
-    if (!fs.existsSync(path)) {
+    const st = lstatOrNull(path);
+    if (st === null) {
         return false;
     }
+    if (st.isSymbolicLink()) {
+        throw new SkillError(`refusing to inspect symlinked skill at ${path}`, "pass --force to replace or remove the symlink itself");
+    }
     return skillTextIsManagedOrBundled(spec, fs.readFileSync(path, "utf-8"));
 }
 function skillTextIsManagedOrBundled(spec, text) {
-    const mark = marker(spec);
-    const gen = generatedBy(spec);
-    if (text.includes(mark) && text.includes(gen)) {
+    if (skillTextHasCurrentMarker(spec, text) || skillTextHasLegacyMarker(spec, text)) {
         return true;
     }
     return normalizeSkillText(spec, text) === normalizeSkillText(spec, spec.source);
 }
+function skillTextHasCurrentMarker(spec, text) {
+    return text.replace(/\r\n/g, "\n").includes(managedMarkerBlock(spec));
+}
+function skillTextHasLegacyMarker(spec, text) {
+    return text.replace(/\r\n/g, "\n").includes(legacyMarkerBlock(spec));
+}
 /**
- * Drop the managed-marker lines, then collapse runs of blank lines to one so that the
+ * Drop the managed-marker blocks, then collapse runs of blank lines to one so that the
  * blank line `managedSkillContents` inserts after the marker block does not make a
  * managed install compare unequal to the bundled source.
  */
 function normalizeSkillText(spec, text) {
-    const mark = marker(spec);
-    const gen = generatedBy(spec);
+    text = text.replace(/\r\n/g, "\n");
+    text = text.replace(managedMarkerBlock(spec), "");
+    text = text.replace(legacyMarkerBlock(spec), "");
     const out = [];
     for (const line of splitLines(text)) {
         const trimmed = line.trim();
-        if (trimmed.includes(mark) || trimmed.includes(gen)) {
-            continue;
-        }
         if (trimmed === "" && out.length > 0 && out[out.length - 1].trim() === "") {
             continue;
         }
@@ -352,14 +431,47 @@ function expandTilde(input) {
     }
     return input;
 }
+function validateSpec(spec) {
+    validateSlug("skill name", spec.name);
+    validateSlug("marker slug", spec.markerSlug);
+    validateSkillText(spec, spec.source);
+}
+function validateSlug(field, value) {
+    if (slugIsValid(value)) {
+        return;
+    }
+    throw new SkillError(`invalid ${field} ${JSON.stringify(value)}: expected a lowercase slug matching [a-z0-9][a-z0-9-]*[a-z0-9]`, "use lowercase ASCII letters, digits, and single hyphen-separated words");
+}
+function slugIsValid(value) {
+    if (value.length === 0)
+        return false;
+    const isLowerAlnum = (ch) => (ch >= "a" && ch <= "z") || (ch >= "0" && ch <= "9");
+    return isLowerAlnum(value[0]) && isLowerAlnum(value[value.length - 1]) &&
+        [...value].every((ch) => isLowerAlnum(ch) || ch === "-");
+}
+function lstatOrNull(path) {
+    return fs.lstatSync(path, { throwIfNoEntry: false }) ?? null;
+}
+function writeSkillAtomic(target, content) {
+    const tmp = join(target.skillDir, `.${basename(SKILL_FILE_NAME)}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
+    try {
+        fs.writeFileSync(tmp, content);
+        fs.renameSync(tmp, target.skillPath);
+    }
+    catch (error) {
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch {
+            // ignore cleanup errors
+        }
+        throw error;
+    }
+}
 /**
  * Mirror Rust's `str::lines`: split on `\n` (normalizing `\r\n`), dropping a single
  * trailing empty element from a final newline.
  */
-function isFile(p) {
-    const st = fs.statSync(p, { throwIfNoEntry: false });
-    return st !== undefined && st.isFile();
-}
 function splitLines(s) {
     const lines = s.replace(/\r\n/g, "\n").split("\n");
     if (lines.length > 0 && lines[lines.length - 1] === "") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-first-data",
-  "version": "0.12.2",
+  "version": "0.13.1",
   "description": "A naming convention that lets AI agents understand your data without being told what it means.",
   "license": "MIT",
   "repository": {
@@ -26,6 +26,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "prepack": "npm run build",
     "test": "tsx --test src/*.test.ts examples/agent_cli.ts"
   },
   "devDependencies": {