agent-skillboard 0.3.0 → 0.3.1

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;