agent-first-data 0.20.0 → 0.22.0

package/dist/skill.d.ts

@@ -1,96 +0,0 @@
-/**
- * Reusable Agent Skill installer for spore CLIs.
- *
- * 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, Hermes).
- *
- * The function performs the filesystem work and returns the protocol value (rendered by
- * the caller with `render`) or throws a {@link SkillError}. It never writes to
- * stdout/stderr itself.
- */
-/**
- * Identity of the skill being managed and the tool that manages it.
- *
- * `name` is both the skill directory name and the `name:` front-matter field. `source` is
- * the bundled `SKILL.md`. `title` is a human label for error messages. `markerSlug` seeds
- * the managed-skill marker and the `Generated by <slug> skill install` comment, and is
- * referenced in hints (e.g. `afwidget`).
- */
-export interface SkillSpec {
-    name: string;
-    source: string;
-    title: string;
-    markerSlug: string;
-}
-/** The skill action to perform. */
-export type SkillAction = "status" | "install" | "uninstall";
-/** Where to install the skill. */
-export type SkillScope = "personal" | "workspace";
-/** Which agent target(s) to manage. */
-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" | "hermes";
-/** Options shared by every skill action. */
-export interface SkillOptions {
-    agent: SkillAgentSelection;
-    scope: SkillScope;
-    /** Explicit skills directory; requires a single concrete `agent`. */
-    skillsDir?: string;
-    /** Overwrite or remove a skill that this tool did not manage. */
-    force?: boolean;
-}
-/** A skill admin failure with an operator-facing message and optional hint. */
-export declare class SkillError extends Error {
-    readonly hint?: string;
-    constructor(message: string, hint?: string);
-}
-/** Per-target outcome of `status` / `install`. */
-export interface SkillTargetStatus {
-    agent: SkillAgent;
-    scope: SkillScope;
-    skills_dir: string;
-    skill_path: string;
-    installed: boolean;
-    managed: boolean;
-    valid: boolean;
-    current: boolean;
-    validation_error: string | null;
-}
-/** Per-target outcome of `uninstall`. */
-export interface SkillUninstallStatus {
-    agent: SkillAgent;
-    scope: SkillScope;
-    skills_dir: string;
-    skill_path: string;
-    removed: boolean;
-}
-/**
- * The result of a skill action. Read fields off the discriminated union (narrow on
- * `code`), or pass it to `render` to serialize — every field is already JSON-shaped.
- */
-export type SkillReport = {
-    code: "skill_status";
-    skill: string;
-    installed_all: boolean;
-    valid_all: boolean;
-    current_all: boolean;
-    targets: SkillTargetStatus[];
-} | {
-    code: "skill_install";
-    skill: string;
-    installed: boolean;
-    targets: SkillTargetStatus[];
-    hint: string;
-} | {
-    code: "skill_uninstall";
-    skill: string;
-    removed_any: boolean;
-    targets: SkillUninstallStatus[];
-};
-/**
- * Install, uninstall, or report status of `spec`'s skill across the selected agent
- * target(s). Returns the protocol value (caller renders with `render`) or throws a
- * {@link SkillError}. Does not touch stdout/stderr.
- */
-export declare function runSkillAdmin(spec: SkillSpec, action: SkillAction, options: SkillOptions): SkillReport;

package/dist/skill.js

@@ -1,493 +0,0 @@
-/**
- * Reusable Agent Skill installer for spore CLIs.
- *
- * 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, Hermes).
- *
- * The function performs the filesystem work and returns the protocol value (rendered by
- * the caller with `render`) or throws a {@link SkillError}. It never writes to
- * stdout/stderr itself.
- */
-import * as fs from "node:fs";
-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;
-    constructor(message, hint) {
-        super(message);
-        this.name = "SkillError";
-        this.hint = hint;
-    }
-}
-/**
- * Install, uninstall, or report status of `spec`'s skill across the selected agent
- * target(s). Returns the protocol value (caller renders with `render`) or throws a
- * {@link SkillError}. Does not touch stdout/stderr.
- */
-export function runSkillAdmin(spec, action, options) {
-    validateSpec(spec);
-    switch (action) {
-        case "status":
-            return status(spec, options);
-        case "install":
-            return install(spec, options);
-        case "uninstall":
-            return uninstall(spec, options);
-        default:
-            throw new SkillError(`unknown skill action '${action}'`);
-    }
-}
-function status(spec, options) {
-    const targets = resolveTargets(spec, options);
-    const statuses = targets.map((target) => targetStatus(spec, target));
-    return {
-        code: "skill_status",
-        skill: spec.name,
-        installed_all: statuses.every((s) => s.installed),
-        valid_all: statuses.every((s) => s.valid),
-        current_all: statuses.every((s) => s.current),
-        targets: statuses,
-    };
-}
-function install(spec, options) {
-    validateSkillText(spec, spec.source);
-    const targets = resolveTargets(spec, options);
-    const content = managedSkillContents(spec);
-    const installed = [];
-    for (const target of targets) {
-        fs.mkdirSync(target.skillDir, { recursive: true });
-        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");
-            }
-        }
-        writeSkillAtomic(target, content);
-        validateInstalledSkill(spec, target.skillPath);
-        installed.push(targetStatus(spec, target));
-    }
-    return {
-        code: "skill_install",
-        skill: spec.name,
-        installed: true,
-        targets: installed,
-        hint: "restart the agent so it reloads installed skills",
-    };
-}
-function uninstall(spec, options) {
-    const targets = resolveTargets(spec, options);
-    const removed = [];
-    for (const target of targets) {
-        const st = lstatOrNull(target.skillPath);
-        if (st === null) {
-            removed.push(targetUninstallStatus(target, false));
-            continue;
-        }
-        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);
-        // Prune the now-empty skill dir; ignore if not empty.
-        try {
-            fs.rmdirSync(target.skillDir);
-        }
-        catch {
-            // directory not empty or already gone
-        }
-        removed.push(targetUninstallStatus(target, true));
-    }
-    return {
-        code: "skill_uninstall",
-        skill: spec.name,
-        removed_any: removed.some((s) => s.removed),
-        targets: removed,
-    };
-}
-function resolveTargets(spec, options) {
-    if (options.skillsDir !== undefined && options.agent === "all") {
-        throw new SkillError("--skills-dir requires a single --agent", "custom skills directories are ambiguous when --agent all is used");
-    }
-    const { agent, scope } = options;
-    if (agent === "all" && scope === "personal") {
-        return [
-            resolveTarget(spec, "codex", "personal", undefined),
-            resolveTarget(spec, "claude-code", "personal", undefined),
-            resolveTarget(spec, "opencode", "personal", undefined),
-            resolveTarget(spec, "hermes", "personal", undefined),
-        ];
-    }
-    if (agent === "all" && scope === "workspace") {
-        return [
-            resolveTarget(spec, "codex", "workspace", undefined),
-            resolveTarget(spec, "claude-code", "workspace", undefined),
-            resolveTarget(spec, "opencode", "workspace", undefined),
-            resolveTarget(spec, "hermes", "workspace", undefined),
-        ];
-    }
-    if (agent === "codex") {
-        return [resolveTarget(spec, "codex", scope, options.skillsDir)];
-    }
-    if (agent === "claude-code") {
-        return [resolveTarget(spec, "claude-code", scope, options.skillsDir)];
-    }
-    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) {
-    const base = skillsDir !== undefined ? expandTilde(skillsDir) : defaultSkillsDir(agent, scope);
-    const skillDir = join(base, spec.name);
-    return {
-        agent,
-        scope,
-        skillsDir: base,
-        skillDir,
-        skillPath: join(skillDir, SKILL_FILE_NAME),
-    };
-}
-function defaultSkillsDir(agent, scope) {
-    if (agent === "codex") {
-        if (scope !== "personal") {
-            return join(process.cwd(), ".codex", "skills");
-        }
-        const codexHome = process.env["CODEX_HOME"];
-        if (codexHome !== undefined) {
-            return join(codexHome, "skills");
-        }
-        return join(homeDir(), ".codex", "skills");
-    }
-    if (agent === "claude-code") {
-        if (scope !== "personal") {
-            return join(process.cwd(), ".claude", "skills");
-        }
-        return join(homeDir(), ".claude", "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 hermesHome = process.env["HERMES_HOME"];
-    if (hermesHome !== undefined) {
-        return join(hermesHome, "skills");
-    }
-    return join(homeDir(), ".hermes", "skills");
-}
-function targetStatus(spec, target) {
-    const st = lstatOrNull(target.skillPath);
-    const installed = st !== null;
-    let valid = false;
-    let current = false;
-    let managed = false;
-    let validationError = null;
-    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 = !skillTextHasLegacyMarker(spec, text) && normalizeSkillText(spec, text) === normalizeSkillText(spec, spec.source);
-        const error = validateSkillTextError(spec, text);
-        if (error === null) {
-            valid = true;
-        }
-        else {
-            validationError = error;
-        }
-    }
-    else if (installed) {
-        validationError = "target SKILL.md is not a regular file";
-    }
-    return {
-        agent: target.agent,
-        scope: target.scope,
-        skills_dir: target.skillsDir,
-        skill_path: target.skillPath,
-        installed,
-        managed,
-        valid,
-        current,
-        validation_error: validationError,
-    };
-}
-function targetUninstallStatus(target, removed) {
-    return {
-        agent: target.agent,
-        scope: target.scope,
-        skills_dir: target.skillsDir,
-        skill_path: target.skillPath,
-        removed,
-    };
-}
-function generatedBy(spec) {
-    return `Generated by ${spec.markerSlug} skill install`;
-}
-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 block = managedMarkerBlock(spec);
-    const lines = splitLines(spec.source);
-    const out = [];
-    let inserted = false;
-    lines.forEach((line, i) => {
-        out.push(line);
-        if (i === 0)
-            return;
-        if (!inserted && line.trim() === "---") {
-            out.push(block, "");
-            inserted = true;
-        }
-    });
-    if (!inserted) {
-        out.push(block);
-    }
-    return out.map((line) => line + "\n").join("");
-}
-function validateInstalledSkill(spec, path) {
-    validateSkillText(spec, fs.readFileSync(path, "utf-8"));
-}
-function validateSkillText(spec, text) {
-    const error = validateSkillTextError(spec, text);
-    if (error !== null) {
-        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 { error: "missing YAML front matter" };
-    }
-    if (lines[0].trim() !== "---") {
-        return { error: "missing opening --- YAML front matter delimiter" };
-    }
-    let foundEnd = false;
-    let name;
-    let hasDescription = false;
-    for (let idx = 1; idx < lines.length; idx++) {
-        const line = lines[idx];
-        const lineNo = idx + 1;
-        const trimmed = line.trim();
-        if (trimmed === "---") {
-            foundEnd = true;
-            break;
-        }
-        if (trimmed === "" || trimmed.startsWith("#")) {
-            continue;
-        }
-        if (line.startsWith(" ") || line.startsWith("\t")) {
-            return { error: `line ${lineNo}: nested YAML is not supported here` };
-        }
-        const colon = line.indexOf(":");
-        if (colon === -1) {
-            return { error: `line ${lineNo}: expected key: value` };
-        }
-        const key = line.slice(0, colon).trim();
-        if (key === "") {
-            return { error: `line ${lineNo}: empty key` };
-        }
-        const value = line.slice(colon + 1).replace(/^\s+/, "");
-        if (key === "name")
-            name = parseFrontmatterScalar(value);
-        if (key === "description")
-            hasDescription = true;
-        if (value.startsWith('"') || value.startsWith("'")) {
-            continue;
-        }
-        if (value.includes(": ")) {
-            return { error: `line ${lineNo}: unquoted scalar contains ': '; quote the value` };
-        }
-    }
-    if (!foundEnd) {
-        return { error: "missing closing --- YAML front matter delimiter" };
-    }
-    if (name === undefined) {
-        return { error: "missing required name field" };
-    }
-    if (!hasDescription) {
-        return { error: "missing required description field" };
-    }
-    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) {
-    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) {
-    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 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) {
-    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 === "" && out.length > 0 && out[out.length - 1].trim() === "") {
-            continue;
-        }
-        out.push(line);
-    }
-    return out.join("\n").trim();
-}
-function homeDir() {
-    const home = process.env["HOME"] ?? process.env["USERPROFILE"];
-    if (home !== undefined) {
-        return home;
-    }
-    throw new SkillError("cannot determine home directory", "pass --skills-dir explicitly");
-}
-function expandTilde(input) {
-    if (input === "~") {
-        return homeDir();
-    }
-    if (input.startsWith("~/")) {
-        return join(homeDir(), input.slice(2));
-    }
-    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 splitLines(s) {
-    const lines = s.replace(/\r\n/g, "\n").split("\n");
-    if (lines.length > 0 && lines[lines.length - 1] === "") {
-        lines.pop();
-    }
-    return lines;
-}

package/dist/stream_redirect.d.ts

@@ -1,21 +0,0 @@
-/**
- * Optional stdout/stderr file redirection for AFDATA CLIs.
- *
- * This redirects Node's process stdout/stderr file descriptors to append-only
- * files. It is not an AFDATA formatter and does not convert stderr diagnostics
- * into JSON.
- */
-export declare const STDOUT_FILE_ARG = "--stdout-file";
-export declare const STDERR_FILE_ARG = "--stderr-file";
-export interface StreamRedirectConfig {
-    stdoutFile?: string;
-    stderrFile?: string;
-}
-export interface InstalledStreamRedirect {
-    stdoutFile?: string;
-    stderrFile?: string;
-    processLifetime: true;
-}
-export declare function configFromRawArgs(args: readonly string[]): StreamRedirectConfig | undefined;
-export declare function installStreamRedirectFromRawArgs(args?: string[]): InstalledStreamRedirect | undefined;
-export declare function installStreamRedirect(config: StreamRedirectConfig): InstalledStreamRedirect | undefined;