agent-skillboard 0.3.0 → 0.3.2

package/src/install-health.mjs

@@ -0,0 +1,177 @@
+import { constants } from "node:fs";
+import { access, lstat, readFile, realpath } from "node:fs/promises";
+import { basename, delimiter, dirname, join, resolve } from "node:path";
+
+const PACKAGE_NAME = "agent-skillboard";
+const POSIX_COMMANDS = ["skillboard", "agent-skillboard"];
+const WINDOWS_COMMANDS = [
+  "skillboard.cmd",
+  "skillboard.exe",
+  "skillboard",
+  "agent-skillboard.cmd",
+  "agent-skillboard.exe",
+  "agent-skillboard"
+];
+
+export async function inspectInstallation(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const pathDelimiter = options.pathDelimiter ?? delimiter;
+  const entrypoint = resolve(options.entrypointPath ?? process.argv[1] ?? "bin/skillboard.mjs");
+  const currentRealPath = await resolvedPath(entrypoint);
+  const currentPackage = await packageForEntrypoint(currentRealPath);
+  const pathCandidates = await findPathCandidates(options.env?.PATH ?? "", {
+    pathDelimiter,
+    platform,
+    currentRealPath,
+    currentPackageRoot: currentPackage?.root ?? null
+  });
+  const pathSelected = pathCandidates.find((candidate) => isPrimaryCommand(candidate.path, platform)) ?? null;
+  const installations = uniqueInstallations(pathCandidates);
+  const duplicateInstallations = installations.length > 1;
+  const shadowed = pathSelected !== null && !pathSelected.current;
+  const current = {
+    version: options.packageVersion ?? currentPackage?.version ?? null,
+    entrypoint,
+    realPath: currentRealPath,
+    packageRoot: currentPackage?.root ?? null
+  };
+  const warnings = installWarnings({ current, pathSelected, installations, duplicateInstallations, shadowed });
+  return {
+    current,
+    pathSelected,
+    pathCandidates,
+    installations,
+    duplicateInstallations,
+    shadowed,
+    warnings
+  };
+}
+
+async function findPathCandidates(pathValue, options) {
+  const commands = options.platform === "win32" ? WINDOWS_COMMANDS : POSIX_COMMANDS;
+  const directories = pathValue.split(options.pathDelimiter).filter((entry) => entry.trim() !== "");
+  const candidates = [];
+  const observedPaths = new Set();
+  for (const directory of directories) {
+    for (const command of commands) {
+      const path = resolve(directory, command);
+      if (observedPaths.has(path) || !await isExecutable(path, options.platform)) continue;
+      observedPaths.add(path);
+      candidates.push(await inspectCandidate(path, options));
+    }
+  }
+  return candidates;
+}
+
+async function inspectCandidate(path, options) {
+  const realPath = await resolvedPath(path);
+  const packageMetadata = await packageForCandidate(path, realPath);
+  const packageRoot = packageMetadata?.root ?? null;
+  return {
+    path,
+    realPath,
+    packageRoot,
+    version: packageMetadata?.version ?? null,
+    current: realPath === options.currentRealPath
+      || (packageRoot !== null && packageRoot === options.currentPackageRoot)
+  };
+}
+
+async function packageForCandidate(path, realPath) {
+  const fromTarget = await packageForEntrypoint(realPath);
+  if (fromTarget !== null) return fromTarget;
+  const commandDirectory = dirname(path);
+  for (const root of [
+    join(commandDirectory, "node_modules", PACKAGE_NAME),
+    resolve(commandDirectory, "..", PACKAGE_NAME)
+  ]) {
+    const metadata = await readPackage(root);
+    if (metadata !== null) return metadata;
+  }
+  return null;
+}
+
+async function packageForEntrypoint(path) {
+  let directory = dirname(path);
+  for (let depth = 0; depth < 6; depth += 1) {
+    const metadata = await readPackage(directory);
+    if (metadata !== null) return metadata;
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  return null;
+}
+
+async function readPackage(root) {
+  try {
+    const parsed = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+    if (parsed?.name !== PACKAGE_NAME || typeof parsed.version !== "string") return null;
+    return { root: await realpath(root), version: parsed.version };
+  } catch (error) {
+    if (error?.code === "ENOENT" || error instanceof SyntaxError) return null;
+    throw error;
+  }
+}
+
+async function isExecutable(path, platform) {
+  try {
+    const stats = await lstat(path);
+    if (!stats.isFile() && !stats.isSymbolicLink()) return false;
+    await access(path, platform === "win32" ? constants.F_OK : constants.X_OK);
+    return true;
+  } catch (error) {
+    if (["EACCES", "ELOOP", "ENOENT", "ENOTDIR"].includes(error?.code)) return false;
+    throw error;
+  }
+}
+
+async function resolvedPath(path) {
+  try {
+    return await realpath(path);
+  } catch (error) {
+    if (error?.code === "ENOENT") return resolve(path);
+    throw error;
+  }
+}
+
+function uniqueInstallations(candidates) {
+  const installations = [];
+  const observed = new Set();
+  for (const candidate of candidates) {
+    if (candidate.packageRoot === null || observed.has(candidate.packageRoot)) continue;
+    observed.add(candidate.packageRoot);
+    installations.push(candidate);
+  }
+  return installations;
+}
+
+function isPrimaryCommand(path, platform) {
+  const command = basename(path).toLowerCase();
+  return platform === "win32"
+    ? ["skillboard", "skillboard.cmd", "skillboard.exe"].includes(command)
+    : command === "skillboard";
+}
+
+function installWarnings(result) {
+  const warnings = [];
+  if (result.shadowed) {
+    warnings.push(
+      `PATH selects SkillBoard ${displayVersion(result.pathSelected.version)} at ${result.pathSelected.path} instead of this ${displayVersion(result.current.version)} invocation at ${result.current.entrypoint}.`
+    );
+  }
+  if (result.duplicateInstallations) {
+    warnings.push(
+      `Multiple SkillBoard installations were found on PATH: ${result.installations.map(displayInstallation).join(", ")}. Keep one npm prefix active and uninstall stale copies with the npm installation that owns them.`
+    );
+  }
+  return warnings;
+}
+
+function displayVersion(version) {
+  return version === null ? "with unknown version" : `version ${version}`;
+}
+
+function displayInstallation(candidate) {
+  return `${candidate.version ?? "unknown"} at ${candidate.path}`;
+}

package/src/inventory-refresh.mjs

@@ -29,7 +29,8 @@ async function refreshLocked(options) {
   const inventory = options.inventory ?? await discoverAgentSkillInventory({
     roots: options.roots,
     home: options.home,
-    env: options.env
+    env: options.env,
+    registeredRoots: options.registeredRoots
   });
   const configVersion = YAML.parse(current)?.version;
   const generatedInventory = configVersion === 2
@@ -43,9 +44,12 @@ async function refreshLocked(options) {
   const previousInventoryText = inventoryText === null
     ? null
     : await readFile(inventoryPath, "utf8").catch((error) => error?.code === "ENOENT" ? "" : Promise.reject(error));
-  const merged = configVersion === 2
+  const projected = configVersion === 2
     ? mergeV2InventoryPolicy(current, inventory)
     : mergeAgentSkillInventory(current, inventory);
+  const merged = configVersion === 1 && options.preserveLegacyPolicy === true
+    ? { ...projected, text: current }
+    : projected;
   const plan = textChangePlan(current, merged.text);
   const dryRun = options.dryRun === true;
 
@@ -81,6 +85,7 @@ async function refreshLocked(options) {
     bootstrappedV2,
     configPath: relativeArtifactPath(root, configPath),
     inventoryPath: generatedInventory === null ? null : relativeArtifactPath(root, inventoryPath),
+    observedSkillIds: inventory.skills.map(({ id }) => id).sort((left, right) => left.localeCompare(right)),
     inventoryChanged,
     changed: plan.changed,
     plan,

package/src/migration/automatic-v2.mjs

@@ -0,0 +1,14 @@
+const SAFE_AMBIGUITY_KIND = "review_only_quarantine";
+
+export function canAutomaticallyMigrateV2(report) {
+  if (report?.mode !== "preview" || report.changed !== true || report.target_version !== 2) return false;
+  if (!Array.isArray(report.ambiguities)) return false;
+  return report.ambiguities.every((ambiguity) => (
+    ambiguity?.kind === SAFE_AMBIGUITY_KIND
+    && ambiguity.mapped_enabled === true
+    && ambiguity.requires_grouped_confirmation === true
+    && Array.isArray(ambiguity.skill_ids)
+    && ambiguity.skill_ids.length > 0
+    && ambiguity.skill_ids.every((skillId) => typeof skillId === "string" && skillId.length > 0)
+  ));
+}

package/src/migration/v2-projection.mjs

@@ -103,6 +103,7 @@ export function unchangedMigrationResult(inputBytes) {
     ambiguities: [],
     grouped_decision: null,
     backup: null,
-    manifest: null
+    manifest: null,
+    inventory_backup: null
   };
 }

package/src/migration/v2-transaction.mjs

@@ -46,6 +46,9 @@ export async function migrateV2(options) {
 
 async function migrateForward(configPath, inventoryPath, options) {
   const inputBytes = await readFile(configPath);
+  if (options.expectedInputSha256 !== undefined && sha256(inputBytes) !== options.expectedInputSha256) {
+    throw new Error("Config changed after migration preview; no files were changed.");
+  }
   const inputText = inputBytes.toString("utf8");
   const { document, parsed } = parseMigrationConfig(inputText);
   const version = parsed.version ?? 1;
@@ -85,6 +88,7 @@ async function migrateForward(configPath, inventoryPath, options) {
       changed: true,
       backup: basename(backup.configBackupPath),
       manifest: basename(backup.manifestPath),
+      inventory_backup: backup.inventoryBackupPath === null ? null : basename(backup.inventoryBackupPath),
       ...report
     };
   } catch (error) {

package/src/setup-policy-migration.mjs

@@ -0,0 +1,43 @@
+import { dirname, join, resolve } from "node:path";
+import { canAutomaticallyMigrateV2 } from "./migration/automatic-v2.mjs";
+import { migrateV2 } from "./migration/v2-transaction.mjs";
+
+export async function upgradeLegacyUserPolicy(options) {
+  if (options.inventoryPath !== null) {
+    return { status: "current", inventoryPath: options.inventoryPath, artifacts: [] };
+  }
+
+  const inventoryPath = resolve(options.home, ".skillboard", "inventory.json");
+  const migrationOptions = {
+    configPath: options.configPath,
+    inventoryPath,
+    failpoint: options.failpoint
+  };
+  const preview = await migrateV2({ ...migrationOptions, apply: false });
+  const observed = new Set(options.observedSkillIds);
+  const unobservedSkillIds = preview.skills.map(({ id }) => id).filter((id) => !observed.has(id));
+  if (!canAutomaticallyMigrateV2(preview) || unobservedSkillIds.length > 0) {
+    return {
+      status: "decision-required",
+      inventoryPath: null,
+      artifacts: [],
+      preview,
+      unobservedSkillIds
+    };
+  }
+
+  const applied = await migrateV2({
+    ...migrationOptions,
+    apply: true,
+    expectedInputSha256: preview.input_sha256
+  });
+  const directory = dirname(options.configPath);
+  const artifactNames = [applied.backup, applied.manifest, applied.inventory_backup].filter(Boolean);
+  return {
+    status: "upgraded",
+    inventoryPath,
+    backupPath: join(directory, applied.backup),
+    artifacts: artifactNames.map((name) => join(directory, name)),
+    report: applied
+  };
+}

package/src/shared-skill-reconcile.mjs

@@ -0,0 +1,97 @@
+import { lstat, readFile, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { analyzeAgentCompatibility } from "./agent-skill-import.mjs";
+import {
+  assertShareTargetAvailable,
+  copyManaged,
+  managedShareMetadata,
+  marker,
+  shareTarget
+} from "./shared-skill.mjs";
+import { loadWorkspace } from "./workspace.mjs";
+
+export async function reconcileSharedSkills(options) {
+  const workspace = await loadWorkspace({
+    configPath: options.configPath,
+    inventoryPath: options.inventoryPath
+  });
+  const targets = uniqueTargets(options.targets ?? []);
+  const created = [];
+  const unchanged = [];
+  const preserved = [];
+  const blocked = [];
+
+  try {
+    for (const policy of workspace.skills.filter((skill) => skill.shared)) {
+      const source = shareTarget(join(options.home, ".agents", "shared-skills"), policy.id);
+      const sourceMarker = await managedShareMetadata(source, policy.id);
+      if (sourceMarker?.mode !== "shared-source") {
+        blocked.push({ skill: policy.id, reason: "managed shared source is missing" });
+        continue;
+      }
+      const content = await readFile(join(source, "SKILL.md"), "utf8");
+      for (const target of targets) {
+        const path = shareTarget(target.root, policy.id);
+        const existing = await pathStats(path);
+        if (existing !== null) {
+          if (await managedShareMetadata(path, policy.id) !== null) {
+            unchanged.push({ agent: target.agent, skill: policy.id, path });
+          } else {
+            preserved.push({ agent: target.agent, skill: policy.id, path });
+          }
+          continue;
+        }
+        if (target.agent !== sourceMarker.source_agent) {
+          const compatibility = analyzeAgentCompatibility(content, {
+            sourceAgent: sourceMarker.source_agent,
+            targetAgent: target.agent
+          });
+          if (!compatibility.compatible) {
+            blocked.push({
+              agent: target.agent,
+              skill: policy.id,
+              path,
+              reason: compatibility.reasons.join("; ")
+            });
+            continue;
+          }
+        }
+        await assertShareTargetAvailable(target.root, path, options.home, policy.id);
+        if (await copyManaged(source, path, marker(
+          policy.id,
+          sourceMarker.source_agent,
+          "agent-copy",
+          target.agent
+        ), options)) {
+          created.push({ agent: target.agent, skill: policy.id, path });
+        }
+      }
+    }
+  } catch (error) {
+    const rollbackErrors = [];
+    for (const entry of created.reverse()) {
+      await rm(entry.path, { recursive: true, force: true }).catch((rollbackError) => rollbackErrors.push(rollbackError));
+    }
+    if (rollbackErrors.length === 0) throw error;
+    const original = error instanceof Error ? error.message : String(error);
+    const rollback = rollbackErrors.map((entry) => entry instanceof Error ? entry.message : String(entry)).join("; ");
+    throw new Error(`${original} Reconcile rollback also failed: ${rollback}`);
+  }
+
+  return { created, unchanged, preserved, blocked };
+}
+
+function uniqueTargets(targets) {
+  const byRoot = new Map();
+  for (const target of targets) {
+    byRoot.set(resolve(target.root), { agent: target.agent, root: resolve(target.root) });
+  }
+  return [...byRoot.values()].sort((left, right) => left.root.localeCompare(right.root));
+}
+
+async function pathStats(path) {
+  return await lstat(path).catch((error) => {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  });
+}

package/src/shared-skill.mjs

@@ -2,8 +2,8 @@ import { constants as fsConstants } from "node:fs";
 import { copyFile, lstat, mkdir, readFile, readdir, readlink, realpath, rename, rm, symlink, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { analyzeAgentCompatibility, agentSkillRoot, findSourceSkillInRoots } from "./agent-skill-import.mjs";
-import { detectedAgentSkillRoots, supportedAgentNames } from "./agent-skill-roots.mjs";
+import { analyzeAgentCompatibility, findSourceSkillInRoots } from "./agent-skill-import.mjs";
+import { agentSkillRootCandidates, detectedAgentSkillRoots, supportedAgentNames } from "./agent-skill-roots.mjs";
 import { setV2SkillShared } from "./control/v2-skill-crud.mjs";
 import { refreshAgentInventory } from "./inventory-refresh.mjs";
 import { loadWorkspace } from "./workspace.mjs";
@@ -43,10 +43,10 @@ async function shareSkill(options, workspace, policy) {
   }
   const sharedRoot = join(options.home, ".agents", "shared-skills");
   const sharedDir = shareTarget(sharedRoot, options.skillId);
-  const targets = await Promise.all(targetAgents.map(async (agent) => {
-    const root = await agentSkillRoot(agent, options.home, options.env);
-    return { agent, root, path: shareTarget(root, options.skillId) };
-  }));
+  const targets = uniqueTargets((await Promise.all(targetAgents.map(async (agent) => {
+    const roots = await detectedAgentSkillRoots(agent, options.home, options.env, { includeFallback: true });
+    return roots.map((root) => ({ agent, root: root.skillRoot, path: shareTarget(root.skillRoot, options.skillId) }));
+  }))).flat());
   await assertShareTargetAvailable(sharedRoot, sharedDir, options.home, options.skillId);
   for (const target of targets) {
     await assertShareTargetAvailable(target.root, target.path, options.home, options.skillId);
@@ -88,9 +88,10 @@ async function shareSkill(options, workspace, policy) {
 async function unshareSkill(options, policy) {
   const managed = [];
   for (const agent of supportedAgentNames()) {
-    const root = await agentSkillRoot(agent, options.home, options.env);
-    const path = shareTarget(root, options.skillId);
-    if (await managedShare(path, options.skillId)) managed.push(path);
+    for (const root of await agentSkillRootCandidates(agent, options.home, options.env)) {
+      const path = shareTarget(root.skillRoot, options.skillId);
+      if (await managedShare(path, options.skillId)) managed.push(path);
+    }
   }
   const sharedDir = shareTarget(join(options.home, ".agents", "shared-skills"), options.skillId);
   if (await managedShare(sharedDir, options.skillId)) managed.push(sharedDir);
@@ -146,7 +147,7 @@ function refreshedInventoryAgents(workspace, options) {
   return agents(workspace.inventory.skills.find((skill) => skill.id === options.skillId)?.installed_on);
 }
 
-async function copyManaged(source, target, metadata, options) {
+export async function copyManaged(source, target, metadata, options = {}) {
   if (await exists(target)) {
     if (!await managedShare(target, metadata.skill)) {
       throw new Error(`Share target already exists and is not managed by SkillBoard: ${target}`);
@@ -192,12 +193,29 @@ async function copyDirectory(source, target) {
   }
 }
 
-async function managedShare(path, skillId) {
-  const value = await readFile(join(path, MARKER), "utf8").then(JSON.parse, () => null);
-  return value?.version === 1 && value.skill === skillId;
+export async function managedShareMetadata(path, skillId) {
+  const directory = await pathStats(path);
+  if (directory === null || directory.isSymbolicLink() || !directory.isDirectory()) return null;
+  const markerPath = join(path, MARKER);
+  const markerStats = await pathStats(markerPath);
+  if (markerStats === null || markerStats.isSymbolicLink() || !markerStats.isFile()) return null;
+  const value = await readFile(markerPath, "utf8").then(parseJsonOrNull, () => null);
+  return value?.version === 1 && value.managed_by === "skillboard" && value.skill === skillId ? value : null;
+}
+
+function parseJsonOrNull(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
 }
 
-function marker(skill, sourceAgent, mode, targetAgent = null) {
+export async function managedShare(path, skillId) {
+  return await managedShareMetadata(path, skillId) !== null;
+}
+
+export function marker(skill, sourceAgent, mode, targetAgent = null) {
   return { version: 1, managed_by: "skillboard", mode, skill, source_agent: sourceAgent, target_agent: targetAgent };
 }
 
@@ -235,7 +253,7 @@ async function exists(path) {
   return lstat(path).then(() => true, () => false);
 }
 
-function shareTarget(root, skillId) {
+export function shareTarget(root, skillId) {
   const value = String(skillId).replace(/\\/g, "/");
   if (value.trim() === "" || value.includes("\0") || value.startsWith("/") || /^[A-Za-z]:\//.test(value)) {
     throw new Error("skill id must identify a relative skill directory");
@@ -249,7 +267,7 @@ function shareTarget(root, skillId) {
   return target;
 }
 
-async function assertShareTargetAvailable(root, target, home, skillId) {
+export async function assertShareTargetAvailable(root, target, home, skillId) {
   const resolvedRoot = resolve(root);
   const resolvedHome = resolve(home);
   const boundary = resolvedRoot === resolvedHome || isInside(resolvedRoot, resolvedHome)
@@ -274,6 +292,12 @@ async function assertShareTargetAvailable(root, target, home, skillId) {
   }
 }
 
+function uniqueTargets(targets) {
+  const byPath = new Map();
+  for (const target of targets) byPath.set(resolve(target.path), target);
+  return [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
+
 function directoryComponents(boundary, targetDir) {
   const components = [];
   let current = resolve(targetDir);

package/src/user-uninstall.mjs

@@ -4,7 +4,6 @@ import { uninstallAgentIntegration } from "./agent-integration-files.mjs";
 import { resolveSetupHome } from "./agent-integration-home.mjs";
 import {
   agentSkillRootCandidates,
-  setupAgentSkillTargets,
   supportedAgentNames
 } from "./agent-skill-roots.mjs";
 
@@ -56,7 +55,15 @@ async function planUserUninstall(home, env) {
 
   const guidanceTargets = [];
   for (const agent of supportedAgentNames()) {
-    guidanceTargets.push(...await setupAgentSkillTargets(agent, home, env));
+    for (const candidate of await agentSkillRootCandidates(agent, home, env)) {
+      guidanceTargets.push({
+        agent,
+        home,
+        skillPath: join(candidate.skillRoot, "skillboard", "SKILL.md"),
+        root: candidate.skillRoot,
+        source: candidate.source
+      });
+    }
   }
   return {
     managedCopies: managedCopies.sort((left, right) => left.path.localeCompare(right.path)),
@@ -88,13 +95,21 @@ async function readManagedMarker(path, skill, agent) {
   const markerPath = join(path, SHARE_MARKER);
   const stats = await pathStats(markerPath);
   if (stats === null || stats.isSymbolicLink() || !stats.isFile()) return null;
-  const value = await readFile(markerPath, "utf8").then(JSON.parse, () => null);
+  const value = await readFile(markerPath, "utf8").then(parseJsonOrNull, () => null);
   if (value?.version !== 1 || value.managed_by !== "skillboard" || value.skill !== skill) return null;
   if (agent === null && value.mode === "shared-source") return value;
   if (agent !== null && value.mode === "agent-copy" && value.target_agent === agent) return value;
   return null;
 }
 
+function parseJsonOrNull(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
 async function removeManagedCopy(copy) {
   const stats = await pathStats(copy.path);
   if (stats === null) return true;