@clearlysh/beehaven 0.8.16

package/dist/commands/agent-skills.js

@@ -0,0 +1,302 @@
+/**
+ * agent-skills — install the shipped Clearly SKILL.md files into every agent's home.
+ *
+ * ⚠⚠ THIS IS THE OTHER HALF OF "just install the CLI". `mcp install` gives an agent the TOOLS;
+ * this gives it the instructions for using them well. The Mac app has installed both on every
+ * launch for a while; the CLI installed neither, so a headless or Linux user got a bare tool list
+ * and no guidance.
+ *
+ * ⚠ NOT THE SAME AS `beehaven skills` (hive-paired skills). That command manages SKILL.md files
+ * that ship WITH an installed hive, and writes only to `~/.claude/skills`. These five are the
+ * product's own, they ship in this package, and they go to every agent home.
+ *
+ * ⚠ A SYMLINKED SKILL IS LEFT ALONE, IN BOTH DIRECTIONS. A developer who links a skill to iterate
+ * on it has made a deliberate statement — the repo owns that file. Writing through the symlink
+ * would silently EDIT THEIR CHECKOUT (`writeFileSync` follows links), and removing it would break
+ * the loop it was created for. Same rule the Mac app's installer follows.
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+import { fileURLToPath } from 'url';
+/**
+ * Where each agent looks for skills.
+ *
+ * ⚠ `~/.agents/skills` is the SHARED, cross-agent location and takes precedence over the per-agent
+ * directories for the agents that read it. The per-agent homes are kept because not every agent
+ * does.
+ */
+export const AGENT_SKILL_DIRS = [
+    { agent: 'shared', dir: path.join(os.homedir(), '.agents', 'skills') },
+    { agent: 'claude', dir: path.join(os.homedir(), '.claude', 'skills') },
+    { agent: 'codex', dir: path.join(os.homedir(), '.codex', 'skills') },
+    { agent: 'gemini', dir: path.join(os.homedir(), '.gemini', 'skills') },
+    { agent: 'pi', dir: path.join(os.homedir(), '.pi', 'agent', 'skills') },
+];
+/** Where this package's copies live — written by `scripts/sync-skills.mjs` at build time. */
+function skillSourceDir() {
+    // dist/commands/agent-skills.js → ../../skills
+    return path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'skills');
+}
+/**
+ * The shipped manifest.
+ *
+ * ⚠⚠ ACCEPTS BOTH SHAPES, IN BOTH DIRECTIONS. `index.json` was a bare `string[]` and is now
+ * `{name, files, sha}[]`. A CLI and its bundled skills travel together in one tarball, but a
+ * DEVELOPER checkout mixes them constantly — a rebuilt `dist/` against an unsynced `skills/`, or
+ * the reverse — and a manifest reader that handles only one shape turns that into a failed install
+ * with no skills at all. Reading both costs one `typeof`.
+ */
+export function shippedManifest() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(skillSourceDir(), 'index.json'), 'utf8'));
+        if (!Array.isArray(raw))
+            return [];
+        return raw.map((e) => (typeof e === 'string' ? { name: e } : e)).filter((e) => e?.name);
+    }
+    catch {
+        return [];
+    }
+}
+/** Names only — the old signature, kept so existing callers do not move. */
+export function shippedSkills() {
+    return shippedManifest().map((s) => s.name);
+}
+/**
+ * Has the user edited this installed skill?
+ *
+ * ⚠⚠ THE POINT IS TO STOP OVERWRITING SOMEBODY'S WORK IN SILENCE. The installer compared content
+ * and wrote whenever it differed, which cannot tell "stale, update it" from "the user changed it,
+ * leave it alone" — those are opposite instructions and both look like `existing !== desired`.
+ *
+ * The `.beehaven-skill` stamp records the sha that was INSTALLED. On the next run:
+ *   · on-disk matches the stamp        ⇒ untouched, safe to update
+ *   · on-disk differs from the stamp   ⇒ the user edited it, skip and say so
+ *   · no stamp (hand-placed, or older) ⇒ treated as untouched, because assuming an edit would
+ *     freeze every skill installed before stamping existed and updates would never land again
+ */
+function localSha(destDir, files) {
+    const h = crypto.createHash('sha256');
+    for (const f of files.slice().sort()) {
+        h.update(f);
+        try {
+            h.update(fs.readFileSync(path.join(destDir, f)));
+        }
+        catch {
+            h.update('\0missing');
+        }
+    }
+    return h.digest('hex').slice(0, 16);
+}
+/**
+ * Install a skill's SIBLING FILES — the scripts and data that make it more than prose.
+ *
+ * ⚠⚠ THE INSTALLER CARRIED EXACTLY ONE FILE PER SKILL, so a skill could only ever BE prose. That
+ * is a ceiling, not an oversight to route around: the two most reliable skills in this product
+ * (`growth-report`, `rank-report`) work because they ship `.mjs` files which collapse a dozen
+ * fragile commands into one, and neither could be distributed through this path. A prose skill
+ * tells the model to run twelve commands and it drifts on all twelve.
+ *
+ * ⚠ EXECUTABLE BIT ON `.mjs`/`.sh`, because a skill that documents `node x.mjs` still works
+ * without it but one that documents `./x.sh` does not — and the failure is a permission error the
+ * model cannot diagnose.
+ *
+ * ⚠ NEVER FATAL. A skill whose script fails to copy is a degraded skill; a throw here would abort
+ * the install of every remaining skill for every remaining agent home.
+ */
+/**
+ * Copies a skill's non-SKILL.md files (scripts, data) and RETURNS HOW MANY IT WROTE.
+ *
+ * ⚠⚠ THE COUNT IS NOT BOOKKEEPING — WITHOUT IT A SCRIPT-ONLY UPDATE REPORTED `current`. The caller
+ * decides `current` vs `updated` by comparing SKILL.md alone, so a skill whose SKILL.md is
+ * byte-identical and whose `survey.mjs` was rewritten landed the new script and told the operator
+ * nothing happened. Verified live before the fix: probe appended to `survey.mjs` → the installed
+ * copy contained it → every step still said `current`. Silent success is the same shape as silent
+ * failure to anyone reading the output, and a scripted skill is exactly where that matters.
+ */
+function installExtras(srcDir, name, destDir, warnings) {
+    const from = path.join(srcDir, name);
+    let wrote = 0;
+    let files = [];
+    try {
+        files = fs.readdirSync(from);
+    }
+    catch {
+        return 0;
+    }
+    for (const f of files) {
+        if (f === 'SKILL.md')
+            continue;
+        try {
+            const s = path.join(from, f);
+            if (!fs.statSync(s).isFile())
+                continue;
+            const d = path.join(destDir, f);
+            // ⚠ A symlinked extra is left alone, exactly as a symlinked SKILL.md is — same reasoning.
+            try {
+                if (fs.lstatSync(d).isSymbolicLink())
+                    continue;
+            }
+            catch { /* absent */ }
+            const body = fs.readFileSync(s);
+            let existing = null;
+            try {
+                existing = fs.readFileSync(d);
+            }
+            catch { /* not installed */ }
+            if (existing && existing.equals(body))
+                continue;
+            fs.mkdirSync(destDir, { recursive: true, mode: 0o755 });
+            fs.writeFileSync(d, body, { mode: /\.(mjs|js|sh)$/.test(f) ? 0o755 : 0o644 });
+            wrote++;
+        }
+        catch (e) {
+            warnings.push(`${name}/${f}: ${e?.message ?? String(e)}`);
+        }
+    }
+    return wrote;
+}
+/** Filename of the install stamp. ⚠ Dot-prefixed so it never reads as part of the skill. */
+const STAMP = '.beehaven-skill';
+/**
+ * Record what was installed, so the NEXT run can tell a stale copy from an edited one.
+ *
+ * ⚠ WRITTEN AFTER THE FILES, ALWAYS. Stamped first, a failed copy leaves a stamp claiming content
+ * that is not there — and the next run then reads the mismatch as a user edit and refuses to fix
+ * it. That is a self-inflicted permanent freeze.
+ *
+ * ⚠ NON-FATAL. An unstampable skill degrades to the old always-overwrite behaviour, which is what
+ * every skill did until now.
+ */
+function stamp(destDir, files, warnings) {
+    try {
+        fs.writeFileSync(path.join(destDir, STAMP), JSON.stringify({ sha: localSha(destDir, files), files, at: new Date().toISOString() }, null, 2), { mode: 0o644 });
+    }
+    catch (e) {
+        warnings.push(`stamp ${destDir}: ${e?.message ?? String(e)}`);
+    }
+}
+export function installAgentSkills() {
+    const steps = [];
+    const warnings = [];
+    const srcDir = skillSourceDir();
+    const names = shippedSkills();
+    if (!names.length) {
+        warnings.push(`no skills bundled in this build (${srcDir}) — run scripts/sync-skills.mjs before packing`);
+        return { steps, warnings };
+    }
+    const manifest = shippedManifest();
+    for (const name of names) {
+        const entry = manifest.find((m) => m.name === name);
+        /** Every file this skill ships — used for the stamp, so a script change counts as a change. */
+        const skillFiles = entry?.files?.length ? entry.files : ['SKILL.md'];
+        const src = path.join(srcDir, name, 'SKILL.md');
+        if (!fs.existsSync(src)) {
+            warnings.push(`source missing: ${name}`);
+            continue;
+        }
+        const desired = fs.readFileSync(src, 'utf8');
+        for (const { agent, dir } of AGENT_SKILL_DIRS) {
+            const destDir = path.join(dir, name);
+            const dest = path.join(destDir, 'SKILL.md');
+            try {
+                /**
+                 * ⚠ ONLY INTO A HOME THAT EXISTS. Creating `~/.gemini/skills` on a machine with no Gemini
+                 * scatters directories for software the user does not run.
+                 */
+                if (!fs.existsSync(dir) && !fs.existsSync(path.dirname(dir))) {
+                    continue;
+                }
+                let link = null;
+                try {
+                    if (fs.lstatSync(dest).isSymbolicLink())
+                        link = fs.readlinkSync(dest);
+                }
+                catch { /* absent */ }
+                if (link) {
+                    warnings.push(`${agent}/${name}: symlink → ${link} (left alone)`);
+                    steps.push(`${agent}/${name}=symlink-skipped`);
+                    continue;
+                }
+                let existing = '';
+                try {
+                    existing = fs.readFileSync(dest, 'utf8');
+                }
+                catch { /* not installed */ }
+                /**
+                 * ⚠⚠ A LOCALLY EDITED SKILL IS LEFT ALONE AND REPORTED. Without this the installer could
+                 * only ask "does it differ?" — which is true both when the shipped copy moved on and when
+                 * the USER changed theirs, and those are opposite instructions. Someone who tuned a skill
+                 * lost it on the next `beehaven skills install`, silently.
+                 *
+                 * ⚠ THE STAMP IS THE ARBITER, NOT THE SHIPPED SHA. Comparing on-disk against SHIPPED only
+                 * says "different"; comparing against what was INSTALLED says WHO changed it.
+                 *
+                 * ⚠ NO STAMP ⇒ TREATED AS UNTOUCHED. Every skill installed before stamping existed has
+                 * none, and assuming an edit there would freeze them permanently — updates would silently
+                 * stop landing, which is the failure mode this whole change exists to remove.
+                 */
+                if (existing) {
+                    let stamped = '';
+                    try {
+                        stamped = JSON.parse(fs.readFileSync(path.join(destDir, STAMP), 'utf8')).sha ?? '';
+                    }
+                    catch { /* unstamped */ }
+                    if (stamped && localSha(destDir, skillFiles) !== stamped) {
+                        warnings.push(`${agent}/${name}: edited locally — left alone (delete it to take the shipped copy)`);
+                        steps.push(`${agent}/${name}=locally-modified`);
+                        continue;
+                    }
+                }
+                if (existing === desired) {
+                    // ⚠ THE EXTRAS DECIDE THE WORD. SKILL.md matching does not mean the skill is unchanged —
+                    //   see `installExtras`. A rewritten script is an update and must say so.
+                    const wrote = installExtras(srcDir, name, destDir, warnings);
+                    stamp(destDir, skillFiles, warnings);
+                    steps.push(`${agent}/${name}=${wrote ? 'updated-scripts' : 'current'}`);
+                    continue;
+                }
+                fs.mkdirSync(destDir, { recursive: true, mode: 0o755 });
+                fs.writeFileSync(dest, desired, { mode: 0o644 });
+                installExtras(srcDir, name, destDir, warnings);
+                stamp(destDir, skillFiles, warnings);
+                steps.push(`${agent}/${name}=${existing ? 'updated' : 'written'}`);
+            }
+            catch (e) {
+                warnings.push(`${agent}/${name}: ${e?.message ?? String(e)}`);
+            }
+        }
+    }
+    return { steps, warnings };
+}
+export function removeAgentSkills() {
+    const steps = [];
+    const warnings = [];
+    for (const name of shippedSkills()) {
+        for (const { agent, dir } of AGENT_SKILL_DIRS) {
+            const destDir = path.join(dir, name);
+            const dest = path.join(destDir, 'SKILL.md');
+            try {
+                if (!fs.existsSync(destDir))
+                    continue;
+                let link = null;
+                try {
+                    if (fs.lstatSync(dest).isSymbolicLink())
+                        link = fs.readlinkSync(dest);
+                }
+                catch { /* absent */ }
+                if (link) {
+                    steps.push(`${agent}/${name}=symlink-kept`);
+                    continue;
+                }
+                fs.rmSync(destDir, { recursive: true, force: true });
+                steps.push(`${agent}/${name}=removed`);
+            }
+            catch (e) {
+                warnings.push(`${agent}/${name}: ${e?.message ?? String(e)}`);
+            }
+        }
+    }
+    return { steps, warnings };
+}