agent-skillboard 0.2.8 → 0.2.10

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## Unreleased
 
+## 0.2.10 — 2026-07-03
+
+### Fixed
+
+- `sudo npm install -g agent-skillboard` now resolves `SUDO_USER` during
+  install-time setup so the SkillBoard guidance skill is written to the
+  invoking user's agent homes instead of `/root`.
+
+### Changed
+
+- Install docs and CLI help now describe both normal global npm installs and
+  sudo/system npm installs, including the distinction between agent-home setup
+  and npm's executable prefix.
+
+## 0.2.9 — 2026-07-03
+
+### Changed
+
+- Lowered the published runtime engine requirement from Node.js `>=20` to
+  `>=14.21` after validating CLI smoke on Node 14.21 and 16.20 plus the full
+  test suite on Node 18.19.
+
+### Fixed
+
+- Replaced runtime use of `node:readline/promises` and
+  `String.prototype.replaceAll` so the CLI can load and run on older Node.js
+  versions without npm `EBADENGINE` warnings on common system Node installs.
+
 ## 0.2.8 — 2026-07-03
 
 ### Added

package/README.md

@@ -93,6 +93,12 @@ AI/automation/operator details:
 npm install -g agent-skillboard
 ```
 
+If your system npm requires elevated permissions, `sudo npm install -g
+agent-skillboard` is also supported. In that flow, install-time setup resolves
+`SUDO_USER` and writes the user-level guidance skill under the invoking user's
+agent homes, while the `skillboard` binary still lands in the global prefix used
+by that npm command.
+
 The install-time setup writes a user-level `skillboard` guidance skill under
 detected agent homes. For Codex, detection includes `CODEX_HOME/skills`,
 `AGENTS_HOME/skills`, `~/.agents/skills`, and `~/.codex/skills`.

package/docs/install.md

@@ -19,12 +19,27 @@ Codex, Claude, OpenCode, and Hermes user skill roots. The setup is best-effort:
 it never fails the package install, does not edit agent config files, and does
 not create project policy files.
 
+The published CLI supports Node.js 14.21 or newer. Node 12 and older are not
+supported without a transpiled bundle because the source uses modern ESM and
+syntax such as nullish coalescing.
+
 AI/automation/operator details:
 
 ```bash
 npm install -g agent-skillboard
 ```
 
+If your system npm requires elevated permissions, this is also supported:
+
+```bash
+sudo npm install -g agent-skillboard
+```
+
+Under sudo, the postinstall setup resolves `SUDO_USER` and targets that user's
+agent homes instead of writing guidance under `/root`. The executable prefix is
+still decided by the npm command you run, so use the same npm/Node environment
+you expect to provide `skillboard` on `PATH`.
+
 The install-time setup writes a user-level SkillBoard guidance skill under
 detected agent homes such as `CODEX_HOME`, `AGENTS_HOME`, `CLAUDE_HOME`,
 `OPENCODE_HOME`, and `HERMES_HOME`. Codex detection also checks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-skillboard",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Let AI agents pick and use allowed skills in each workflow.",
   "keywords": [
     "ai-agent",
@@ -52,7 +52,7 @@
     "yaml": "^2.8.1"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=14.21"
   },
   "license": "MIT",
   "devDependencies": {

package/src/advisor/action-core.mjs

@@ -70,5 +70,5 @@ function emptyApplication(blockedReason) {
 }
 
 function shellQuote(value) {
-  return /^[A-Za-z0-9_./:=@-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+  return /^[A-Za-z0-9_./:=@-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
 }

package/src/agent-inventory-platforms.mjs

@@ -43,7 +43,7 @@ export function userHermesUnit(path, home) {
 }
 
 export function hermesProfileUnit(path, home) {
-  const profile = safeSegment(basename(dirname(path))).replaceAll(".", "-");
+  const profile = safeSegment(basename(dirname(path))).replace(/\./g, "-");
   return userSkillUnit(`hermes.profile.${profile}.skills`, path, home);
 }
 
@@ -55,7 +55,7 @@ export function customUserUnit(path, home) {
 }
 
 export function isHermesProfileSkillsPath(path) {
-  const normalized = path.replaceAll("\\", "/");
+  const normalized = path.replace(/\\/g, "/");
   return /\/\.hermes\/profiles\/[^/]+\/skills$/u.test(normalized);
 }
 
@@ -72,7 +72,7 @@ export function displayPath(path, home) {
     return "~";
   }
   if (!rel.startsWith("..") && !isAbsolute(rel)) {
-    return `~/${rel.replaceAll("\\", "/")}`;
+    return `~/${rel.replace(/\\/g, "/")}`;
   }
   return resolvedPath;
 }

package/src/agent-inventory.mjs

@@ -242,7 +242,7 @@ function localWorkflowTarget(unit) {
     const profile = unit.id.slice("hermes.profile.".length, -".skills".length);
     return { harness: "hermes", workflow: `hermes-${profile}-local-manual` };
   }
-  const base = safeSegment(unit?.id ?? "local").replaceAll(".", "-");
+  const base = safeSegment(unit?.id ?? "local").replace(/\./g, "-");
   return { harness: "local", workflow: `${base}-local-manual` };
 }
 
@@ -495,7 +495,7 @@ async function findSkillFiles(root, base, options, seen = new Set()) {
   const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
   for (const entry of entries) {
     const path = join(root, entry.name);
-    const rel = relative(base, path).replaceAll("\\", "/");
+    const rel = relative(base, path).replace(/\\/g, "/");
     if (options.excludeSystem === true && (rel === ".system" || rel.startsWith(".system/"))) {
       continue;
     }
@@ -539,7 +539,7 @@ function skillIdFor(unit, root, file, frontmatter) {
 }
 
 function skillPath(root, file) {
-  return relative(root, dirname(file)).replaceAll("\\", "/");
+  return relative(root, dirname(file)).replace(/\\/g, "/");
 }
 
 function skillNode(skill, defaults = {}) {

package/src/agent-skill-import.mjs

@@ -266,7 +266,7 @@ function digest(content) {
 }
 
 function resolveRelativeTarget(root, value) {
-  const relativePath = String(value).replaceAll("\\", "/");
+  const relativePath = String(value).replace(/\\/g, "/");
   if (relativePath.trim() === "" || relativePath.includes("\0")) {
     throw new Error("skill path must be a non-empty relative path");
   }

package/src/brief-renderer.mjs

@@ -565,8 +565,8 @@ function workflowSummary(workflow) {
 }
 
 function safeText(value, maxLength = 180) {
-  const compact = String(value).replaceAll(/\s+/g, " ").trim();
-  const withoutTicks = compact.replaceAll("`", "'");
+  const compact = String(value).replace(/\s+/g, " ").trim();
+  const withoutTicks = compact.replace(/`/g, "'");
   return withoutTicks.length > maxLength ? `${withoutTicks.slice(0, maxLength - 3)}...` : withoutTicks;
 }
 

package/src/cli.mjs

@@ -1097,7 +1097,7 @@ function formatList(values) {
 }
 
 function shellQuote(value) {
-  return /^[A-Za-z0-9_./:=@-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+  return /^[A-Za-z0-9_./:=@-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
 }
 
 function readCsv(value) {
@@ -1548,7 +1548,9 @@ function helpText() {
     "",
     "After global install:",
     "  npm install -g agent-skillboard",
+    "  sudo npm install -g agent-skillboard is also supported when system npm requires it.",
     "  The package postinstall auto-runs agent-layer guidance setup for detected supported agents.",
+    "  Under sudo, setup targets SUDO_USER's agent homes while npm still controls the binary prefix.",
     "  Run skillboard setup later after adding another supported agent or when install scripts were skipped.",
     "",
     "AI/automation operations:",

package/src/control/variant-files.mjs

@@ -35,7 +35,7 @@ export function resolveVariantSnapshotFile({ configPath, snapshotPath }) {
     throw new Error(`snapshot path must stay under ${SNAPSHOT_ROOT}`);
   }
   return {
-    storedPath: relative(configDir, absolutePath).replaceAll("\\", "/"),
+    storedPath: relative(configDir, absolutePath).replace(/\\/g, "/"),
     absolutePath,
     rootPath: root
   };
@@ -213,7 +213,7 @@ function normalizeStoredSnapshotPath(value) {
   if (value.includes("\0")) {
     throw new Error("snapshot path must not contain null bytes");
   }
-  const normalized = value.replaceAll("\\", "/");
+  const normalized = value.replace(/\\/g, "/");
   if (normalized.startsWith("/") || normalized.startsWith("//") || /^[A-Za-z]:\//.test(normalized)) {
     throw new Error("snapshot path must be relative to the config directory");
   }

package/src/hook-plan.mjs

@@ -143,7 +143,7 @@ function modeToPermissions(mode) {
 }
 
 function shellQuote(value) {
-  return `'${value.replaceAll("'", "'\\''")}'`;
+  return `'${value.replace(/'/g, "'\\''")}'`;
 }
 
 function safeHookFilePart(value) {

package/src/install-output-detector.mjs

@@ -315,9 +315,9 @@ function normalizePath(value, root) {
 
 function displayPath(path, root) {
   if (!isAbsolute(path)) {
-    return path.replaceAll("\\", "/");
+    return path.replace(/\\/g, "/");
   }
-  const rel = relative(root, path).replaceAll("\\", "/");
+  const rel = relative(root, path).replace(/\\/g, "/");
   return rel.startsWith("..") ? path : rel;
 }
 

package/src/lifecycle-cli.mjs

@@ -1,12 +1,15 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { createInterface } from "node:readline/promises";
+import { createInterface } from "node:readline";
+import { promisify } from "node:util";
 import { setupAgentSkillTargets, supportedAgentNames } from "./agent-skill-roots.mjs";
 import { initProject } from "./init.mjs";
 import { uninstallProject } from "./uninstall.mjs";
 
 const AGENT_INTEGRATION_START = "<!-- BEGIN SKILLBOARD AGENT INTEGRATION -->";
 const AGENT_INTEGRATION_END = "<!-- END SKILLBOARD AGENT INTEGRATION -->";
+const execFileAsync = promisify(execFile);
 
 export async function runInitCommand(options, stdout, runtime = defaultRuntime()) {
   const root = resolve(options.get("dir") ?? ".");
@@ -180,13 +183,19 @@ async function promptForSetup(runtime) {
     output: runtime.stdout
   });
   try {
-    const answer = await rl.question("Install SkillBoard agent integration now? [y/N] ");
+    const answer = await question(rl, "Install SkillBoard agent integration now? [y/N] ");
     return /^(y|yes)$/i.test(answer.trim());
   } finally {
     rl.close();
   }
 }
 
+function question(rl, prompt) {
+  return new Promise((resolve) => {
+    rl.question(prompt, resolve);
+  });
+}
+
 function formatList(values) {
   return values.length === 0 ? "none" : values.map((value) => `\`${value}\``).join(", ");
 }
@@ -212,7 +221,7 @@ function defaultRuntime() {
 
 async function agentSetupTargets(options, runtime) {
   const env = runtime.env ?? process.env;
-  const home = env.HOME ?? env.USERPROFILE;
+  const home = await resolveSetupHome(env, runtime);
   const requested = readCsv(options.get("agent"));
   const supported = new Set(supportedAgentNames());
   const names = requested.length === 0 ? supportedAgentNames() : requested;
@@ -226,6 +235,79 @@ async function agentSetupTargets(options, runtime) {
   return targets;
 }
 
+async function resolveSetupHome(env, runtime) {
+  const explicit = nonEmpty(env.SKILLBOARD_SETUP_HOME);
+  if (explicit !== null) {
+    return explicit;
+  }
+  if (shouldUseSudoUserHome(env)) {
+    const sudoHome = nonEmpty(env.SUDO_HOME)
+      ?? await passwdHome(env.SUDO_USER, runtime.passwdPath ?? "/etc/passwd")
+      ?? await getentHome(env.SUDO_USER, env)
+      ?? await conventionalUserHome(env.SUDO_USER);
+    if (sudoHome !== null) {
+      return sudoHome;
+    }
+  }
+  return env.HOME ?? env.USERPROFILE;
+}
+
+function shouldUseSudoUserHome(env) {
+  const sudoUser = nonEmpty(env.SUDO_USER);
+  return process.platform !== "win32"
+    && sudoUser !== null
+    && sudoUser !== "root"
+    && (
+      env.SUDO_UID !== undefined
+      || env.SUDO_GID !== undefined
+      || env.USER === "root"
+      || env.LOGNAME === "root"
+      || env.HOME === "/root"
+    );
+}
+
+async function passwdHome(user, passwdPath) {
+  const text = await readFile(passwdPath, "utf8").catch(() => "");
+  for (const line of text.split("\n")) {
+    if (line.startsWith(`${user}:`)) {
+      return nonEmpty(line.split(":")[5]);
+    }
+  }
+  return null;
+}
+
+async function getentHome(user, env) {
+  try {
+    const { stdout } = await execFileAsync("getent", ["passwd", user], {
+      env,
+      timeout: 1000
+    });
+    return nonEmpty(stdout.trim().split(":")[5]);
+  } catch {
+    return null;
+  }
+}
+
+async function conventionalUserHome(user) {
+  const candidates = process.platform === "darwin"
+    ? [`/Users/${user}`]
+    : [`/home/${user}`];
+  for (const candidate of candidates) {
+    if (await exists(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+async function exists(path) {
+  return access(path).then(() => true, () => false);
+}
+
+function nonEmpty(value) {
+  return value === undefined || value.trim() === "" ? null : value;
+}
+
 async function installAgentIntegration(targets) {
   const created = [];
   const updated = [];
@@ -299,7 +381,7 @@ ${AGENT_INTEGRATION_END}
 
 function commandPrefix(runtime) {
   const entrypoint = runtime.entrypointPath ?? "";
-  const normalized = entrypoint.replaceAll("\\", "/");
+  const normalized = entrypoint.replace(/\\/g, "/");
   if (normalized.includes("/_npx/")) {
     const packageSpec = runtime.packageSpec ?? "agent-skillboard";
     return `npx --yes --package ${shellQuote(packageSpec)} skillboard`;
@@ -314,7 +396,7 @@ function isSourceTreeEntrypoint(entrypoint) {
   if (entrypoint === "") {
     return false;
   }
-  const normalized = entrypoint.replaceAll("\\", "/");
+  const normalized = entrypoint.replace(/\\/g, "/");
   return (normalized === "bin/skillboard.mjs" || normalized.endsWith("/bin/skillboard.mjs"))
     && !normalized.includes("/node_modules/")
     && !normalized.includes("/_npx/")
@@ -323,7 +405,7 @@ function isSourceTreeEntrypoint(entrypoint) {
 
 function sourceTreeEntrypoint(entrypoint, cwd) {
   const absoluteEntrypoint = isAbsolute(entrypoint) ? entrypoint : resolve(cwd, entrypoint);
-  const relativeEntrypoint = relative(cwd, absoluteEntrypoint).replaceAll("\\", "/");
+  const relativeEntrypoint = relative(cwd, absoluteEntrypoint).replace(/\\/g, "/");
   if (!relativeEntrypoint.startsWith("../") && relativeEntrypoint !== ".." && !isAbsolute(relativeEntrypoint)) {
     return shellQuote(relativeEntrypoint);
   }
@@ -334,5 +416,5 @@ function shellQuote(value) {
   if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
     return value;
   }
-  return `'${value.replaceAll("'", "'\\''")}'`;
+  return `'${value.replace(/'/g, "'\\''")}'`;
 }

package/src/skill-paths.mjs

@@ -5,7 +5,7 @@ export function normalizeSkillPath(value, label = "skill path") {
   if (value.includes("\0")) {
     throw new Error(`${label} must not contain null bytes`);
   }
-  const normalized = value.replaceAll("\\", "/");
+  const normalized = value.replace(/\\/g, "/");
   if (normalized.startsWith("/") || normalized.startsWith("//") || /^[A-Za-z]:\//.test(normalized)) {
     throw new Error(`${label} must be relative to the skills root`);
   }

package/src/source-cache.mjs

@@ -164,7 +164,7 @@ function resolveUnderRoot(root, path) {
 }
 
 function relativePath(root, path) {
-  const rel = relative(root, path).replaceAll("\\", "/");
+  const rel = relative(root, path).replace(/\\/g, "/");
   return rel.startsWith("..") ? path : rel;
 }
 

package/src/source-profiles.mjs

@@ -14,7 +14,7 @@ export async function importSource(options) {
   const matchedFiles = files
     .map((file) => ({
       file,
-      relativeFile: relative(sourceRoot, file).replaceAll("\\", "/")
+      relativeFile: relative(sourceRoot, file).replace(/\\/g, "/")
     }))
     .filter((entry) => matchesAnyProfilePattern(entry.relativeFile, profile.skillPaths))
     .sort((left, right) => left.relativeFile.localeCompare(right.relativeFile));
@@ -238,9 +238,9 @@ function matchingPathRule(file, profile) {
 function patternToRegExp(pattern) {
   const escaped = pattern
     .replace(/[.+^${}()|[\]\\]/g, "\\$&")
-    .replaceAll("**", "\0")
-    .replaceAll("*", "[^/]*")
-    .replaceAll("\0", ".*");
+    .split("**").join("\0")
+    .split("*").join("[^/]*")
+    .split("\0").join(".*");
   return new RegExp(`^${escaped}$`);
 }
 

package/src/source-verification.mjs

@@ -165,7 +165,7 @@ export async function sourceDigest(path) {
 
 async function addPathDigest(hash, root, path) {
   const stats = await lstat(path);
-  const rel = relative(root, path).replaceAll("\\", "/") || ".";
+  const rel = relative(root, path).replace(/\\/g, "/") || ".";
   if (stats.isSymbolicLink()) {
     hash.update(`symlink\0${rel}\0${await readlink(path)}\n`);
     return;

package/src/workspace.mjs

@@ -51,7 +51,7 @@ async function discoverInstalledSkills(skillsRoot, declaredSkills, options = {})
     const skillFiles = await findSkillFiles(skillsRoot);
     for (const file of skillFiles) {
       const frontmatter = parseSkillFrontmatter(await readFile(file, "utf8"));
-      const path = relative(skillsRoot, file).replaceAll("\\", "/").replace(/\/SKILL\.md$/, "");
+      const path = relative(skillsRoot, file).replace(/\\/g, "/").replace(/\/SKILL\.md$/, "");
       const declared = declaredSkills.find((skill) => skill.path === path);
       appendInstalledSkill(installed, installedKeys, {
         id: declared?.id ?? frontmatter.name ?? path,