@wirecat/cli-base 0.58.0 → 0.59.0

package/CHANGELOG.md

@@ -8,6 +8,20 @@ Versions before 0.8.0 are in the [git tags](https://github.com/WireCatLabs/cli-b
 Every entry says what changed as a caller sees it, why, and what to watch for — the rules are
 [`docs/dev/CONVENTIONS.md`](docs/dev/CONVENTIONS.md#the-changelog).
 
+## 0.59.0 — 26.10.2026
+
+### Added
+
+- **`skill install --for hermes` gives Hermes Agent the skill, and `skill status` reports what Hermes reads.** It writes
+  the `~/.agents/skills` copy, then adds that folder to Hermes's `skills.external_dirs` through Hermes's own
+  `hermes config set`, keeping every folder already listed. When Hermes is not on PATH or refuses, it copies the file
+  into `$HERMES_HOME/skills/<app>/` and says why; with neither `hermes` on PATH nor a Hermes home folder it fails
+  with `not_found` and writes nothing. `--for all` stays Claude Code and `~/.agents/skills`: it is the
+  default, and a bare `skill install` must not change another program's settings. `skill status --json` gains
+  `hermes: { path, installed, state, via }` beside `targets`, which keeps its two entries. It runs
+  `hermes config get` only when `HERMES_HOME` (else `~/.hermes`) exists, so a test with a temporary `HOME` starts no
+  Hermes unless its environment sets `HERMES_HOME`.
+
 ## 0.58.0 — 25.10.2026
 
 ### Changed — may break callers

package/dist/skill/index.d.ts

@@ -35,6 +35,53 @@ export interface SkillTargetStatus {
 }
 /** Each target's installed copy against this CLI's version; reads only, and an unreadable file is missing. */
 export declare const skillStatus: (app: SkillApp, env?: Env) => SkillTargetStatus[];
+export interface ProgramResult {
+    status: number | null;
+    error?: Error;
+    stdout: string;
+}
+/** Runs a program with no shell, found and started with the `env` given, never `process.env`. */
+export type RunProgram = (file: string, args: readonly string[], env: Env) => ProgramResult;
+/** How Hermes reads the skill: the `~/.agents/skills` folder listed in its `skills.external_dirs`, or a copy of its own. */
+export type HermesRoute = "external_dirs" | "copy";
+/** `HERMES_HOME`, else the folder Hermes itself defaults to. */
+export declare const hermesHome: (env: Env, platform?: NodeJS.Platform) => string;
+export declare const hermesCopyPath: (appName: string, env: Env) => string;
+export interface HermesInstall {
+    via: HermesRoute;
+    /** The file Hermes reads. */
+    path: string;
+    /** Why the copy was written instead, when it was. */
+    reason?: string;
+    /** An earlier copy this CLI wrote, taken out because Hermes refuses a skill name it finds twice. */
+    removed?: string;
+}
+/**
+ * Writes the skill to `~/.agents/skills`, then has Hermes read that folder by adding it to `skills.external_dirs`
+ * with Hermes's own `config set`, keeping every folder already listed. When Hermes is not on PATH, cannot be asked,
+ * or does not keep the folder, the skill is copied into `$HERMES_HOME/skills` instead — but only when that home exists:
+ * with neither the program nor its home, Hermes is not installed, and nothing is written.
+ */
+export declare const installHermesSkill: (app: SkillApp, skill: URL, { env, run }?: {
+    env?: Env;
+    run?: RunProgram;
+}) => {
+    written: string[];
+    hermes: HermesInstall;
+};
+export interface HermesSkillStatus extends Omit<SkillTargetStatus, "target"> {
+    /** How Hermes reads the copy reported; `null` when it reads none. */
+    via: HermesRoute | null;
+}
+/**
+ * The copy Hermes reads: its own `skills/<app>` first, as Hermes scans it first, else the `~/.agents/skills` one when
+ * `skills.external_dirs` lists that folder. Asks Hermes through `config get` when its home exists, so a host calls it
+ * only when asked.
+ */
+export declare const hermesSkillStatus: (app: SkillApp, { env, run }?: {
+    env?: Env;
+    run?: RunProgram;
+}) => HermesSkillStatus;
 /** What the command writes to and where home is, for this invocation — the host's own output resolution. */
 export type SkillEnvironment = (command: Command) => {
     renderer: Renderer;

package/dist/skill/index.js

@@ -5,12 +5,14 @@
  * Nothing here prints by itself. The command writes through the renderer and streams the host hands
  * it, and the hint is a string the host puts on stderr — never stdout, which an agent parses.
  */
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { Command, Option } from "commander";
+import crossSpawn from "cross-spawn";
 import { annotate } from "../commands/index.js";
 import { CliError } from "../errors.js";
+import { executableEnvironment, executableOnPath } from "../executable.js";
 import { CHECK_EVERY_MS, isNewer, readNoticeState, writeUpdateState } from "../update/index.js";
 export const SKILL_TARGETS = ["claude", "agents"];
 const homeOf = (env) => env.HOME || env.USERPROFILE || homedir();
@@ -91,18 +93,133 @@ export const installSkill = (app, skill, { targets = SKILL_TARGETS, env = proces
 /** Each target's installed copy against this CLI's version; reads only, and an unreadable file is missing. */
 export const skillStatus = (app, env = process.env) => SKILL_TARGETS.map((target) => {
     const path = skillPath(target, app.appName, env);
+    return { target, ...(copyStatus(app, path) ?? { path, installed: null, state: "missing" }) };
+});
+const copyStatus = (app, path) => {
     let content;
     try {
         content = readFileSync(path, "utf8");
     }
     catch {
-        return { target, path, installed: null, state: "missing" };
+        return undefined;
     }
     const installed = skillVersion(content);
     if (installed === undefined)
-        return { target, path, installed: null, state: "unversioned" };
-    return { target, path, installed, state: isNewer(app.version, installed) ? "stale" : "current" };
-});
+        return { path, installed: null, state: "unversioned" };
+    return { path, installed, state: isNewer(app.version, installed) ? "stale" : "current" };
+};
+const runProgram = (file, args, env) => {
+    const result = crossSpawn.sync(executableOnPath(file, env), [...args], {
+        encoding: "utf8",
+        timeout: 30_000,
+        maxBuffer: 256_000,
+        env: executableEnvironment(env),
+    });
+    return { status: result.status, ...(result.error ? { error: result.error } : {}), stdout: result.stdout ?? "" };
+};
+/** `HERMES_HOME`, else the folder Hermes itself defaults to. */
+export const hermesHome = (env, platform = process.platform) => {
+    const set = env.HERMES_HOME?.trim();
+    if (set)
+        return set;
+    if (platform === "win32")
+        return join(env.LOCALAPPDATA || join(homeOf(env), "AppData", "Local"), "hermes");
+    return join(homeOf(env), ".hermes");
+};
+export const hermesCopyPath = (appName, env) => join(hermesHome(env), "skills", appName, "SKILL.md");
+const EXTERNAL_DIRS = "skills.external_dirs";
+/**
+ * The folders Hermes lists in `skills.external_dirs`, as its own `config get` answers, or `undefined` when Hermes
+ * cannot be asked or the setting is neither a list nor one folder — a value this code must never overwrite.
+ */
+const externalDirs = (env, run) => {
+    const answer = run("hermes", ["config", "get", EXTERNAL_DIRS, "--json"], env);
+    if (answer.error || answer.status !== 0)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(answer.stdout);
+    }
+    catch {
+        return undefined;
+    }
+    if (value === null)
+        return [];
+    if (typeof value === "string")
+        return [value];
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : undefined;
+};
+/** Hermes expands `~` and environment variables in each entry before it resolves the path. */
+const expanded = (entry, env) => resolve(entry
+    .replace(/^~(?=$|[\\/])/, homeOf(env))
+    .replace(/\$\{(\w+)\}|\$(\w+)/g, (whole, braced, bare) => env[braced ?? bare ?? ""] ?? whole));
+const lists = (dirs, folder, env) => dirs.some((entry) => expanded(entry, env) === resolve(folder));
+/** Our own earlier copy, alone in its folder: anything else there was put by someone else and stays. */
+const removeOwnCopy = (appName, env) => {
+    const path = hermesCopyPath(appName, env);
+    try {
+        if (readdirSync(dirname(path)).join() !== "SKILL.md")
+            return undefined;
+        if (skillName(readFileSync(path, "utf8")) !== appName)
+            return undefined;
+        rmSync(path);
+        rmdirSync(dirname(path));
+        return path;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Has Hermes list `folder` in `skills.external_dirs`, keeping the folders there; why not, when it does not. */
+const readFolder = (folder, env, run) => {
+    const dirs = externalDirs(env, run);
+    if (dirs === undefined)
+        return "Hermes could not be asked for skills.external_dirs";
+    if (lists(dirs, folder, env))
+        return undefined;
+    const set = run("hermes", ["config", "set", EXTERNAL_DIRS, JSON.stringify([...dirs, folder])], env);
+    if (set.error || set.status !== 0)
+        return "hermes config set failed";
+    const after = externalDirs(env, run);
+    return after !== undefined && lists(after, folder, env) ? undefined : "Hermes did not keep the folder";
+};
+/**
+ * Writes the skill to `~/.agents/skills`, then has Hermes read that folder by adding it to `skills.external_dirs`
+ * with Hermes's own `config set`, keeping every folder already listed. When Hermes is not on PATH, cannot be asked,
+ * or does not keep the folder, the skill is copied into `$HERMES_HOME/skills` instead — but only when that home exists:
+ * with neither the program nor its home, Hermes is not installed, and nothing is written.
+ */
+export const installHermesSkill = (app, skill, { env = process.env, run = runProgram } = {}) => {
+    if (!existsSync(hermesHome(env)) && run("hermes", ["--version"], env).error)
+        throw new CliError("not_found", "Hermes is not installed here; install Hermes first, or set HERMES_HOME");
+    const [shared] = installSkill(app, skill, { targets: ["agents"], env });
+    const reason = readFolder(dirname(dirname(shared)), env, run);
+    if (reason === undefined) {
+        const removed = removeOwnCopy(app.appName, env);
+        return { written: [shared], hermes: { via: "external_dirs", path: shared, ...(removed ? { removed } : {}) } };
+    }
+    const copy = hermesCopyPath(app.appName, env);
+    mkdirSync(dirname(copy), { recursive: true });
+    writeFileSync(copy, readFileSync(shared));
+    return { written: [shared, copy], hermes: { via: "copy", path: copy, reason } };
+};
+/**
+ * The copy Hermes reads: its own `skills/<app>` first, as Hermes scans it first, else the `~/.agents/skills` one when
+ * `skills.external_dirs` lists that folder. Asks Hermes through `config get` when its home exists, so a host calls it
+ * only when asked.
+ */
+export const hermesSkillStatus = (app, { env = process.env, run = runProgram } = {}) => {
+    const own = copyStatus(app, hermesCopyPath(app.appName, env));
+    if (own)
+        return { ...own, via: "copy" };
+    const shared = skillPath("agents", app.appName, env);
+    // Asked with no home of its own, Hermes creates one: a status that only reads never starts it there.
+    const dirs = existsSync(hermesHome(env)) ? externalDirs(env, run) : undefined;
+    const read = dirs !== undefined && lists(dirs, dirname(dirname(shared)), env) ? copyStatus(app, shared) : undefined;
+    if (read)
+        return { ...read, via: "external_dirs" };
+    return { path: shared, installed: null, state: "missing", via: null };
+};
 /**
  * `more`: skills a library ships for every CLI built on it, by name — `skill show <name>` prints one with
  * `{{command}}` turned into this CLI's command. They are printed, not installed: two CLIs would install
@@ -159,10 +276,22 @@ export const skillCommand = (app, skill, environment, more = {}) => {
     });
     annotate(command.command("install"), { effects: { remote: "none", local: "write" } })
         .summary("install the tool's instructions for AI agents")
-        .description(`write SKILL.md to ~/.claude/skills/${app.appName}/ (Claude Code) and ~/.agents/skills/${app.appName}/ (Codex, Gemini CLI)`)
-        .addOption(new Option("--for <agents>", "which agents to install for").choices(["claude", "agents", "all"]).default("all"))
+        .description(`write SKILL.md to ~/.claude/skills/${app.appName}/ (Claude Code) and ~/.agents/skills/${app.appName}/ (Codex, Gemini CLI, OpenClaw); --for hermes also has Hermes read ~/.agents/skills, which changes Hermes's own settings, so all leaves it out`)
+        .addOption(new Option("--for <agents>", "which agents to install for")
+        .choices(["claude", "agents", "hermes", "all"])
+        .default("all"))
         .action(function ({ for: chosen }) {
         const { renderer, env } = environment(this);
+        if (chosen === "hermes") {
+            const { written, hermes } = installHermesSkill(app, skill, env ? { env } : {});
+            renderer.result({ name: app.appName, version: app.version, written, hermes });
+            renderer.success(hermes.via === "external_dirs"
+                ? `${app.appName} ${app.version} skill installed: ${hermes.path}; Hermes reads ${dirname(dirname(hermes.path))} (skills.external_dirs)`
+                : `${app.appName} ${app.version} skill installed: ${hermes.path}, a copy for Hermes (${hermes.reason})`);
+            if (hermes.removed)
+                renderer.note(`removed the earlier copy Hermes would also have found: ${hermes.removed}`);
+            return;
+        }
         const targets = chosen === "all" ? SKILL_TARGETS : [chosen];
         const written = installSkill(app, skill, { targets, ...(env ? { env } : {}) });
         renderer.result({ name: app.appName, version: app.version, written });
@@ -173,11 +302,14 @@ export const skillCommand = (app, skill, environment, more = {}) => {
         examples: [`${app.command} skill status`, `${app.command} skill status --json`],
     })
         .summary("whether the installed instructions for AI agents match this version")
-        .description(`for each place \`${app.command} skill install\` writes to: the path, the version installed there, and whether it is current, stale, missing or unversioned`)
+        .description(`for each place \`${app.command} skill install\` writes to, and for the copy Hermes reads: the path, the version installed there, and whether it is current, stale, missing or unversioned`)
         .action(function () {
         const { renderer, env } = environment(this);
+        // Hermes is its own key, not a third target: it is no folder `skill install` writes, and a caller that
+        // expects the two targets keeps working.
         const targets = skillStatus(app, env ?? process.env);
-        renderer.result({ name: app.appName, version: app.version, targets });
+        const hermes = hermesSkillStatus(app, env ? { env } : {});
+        renderer.result({ name: app.appName, version: app.version, targets, hermes });
     });
     return command;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-base",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "The parts every command line tool needs: output modes, terminal rendering, error model, exit codes, credentials, clocks",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",