agent-skillboard 0.2.18 → 0.3.1

package/src/user-uninstall.mjs

@@ -0,0 +1,161 @@
+import { lstat, readdir, readFile, rm } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { uninstallAgentIntegration } from "./agent-integration-files.mjs";
+import { resolveSetupHome } from "./agent-integration-home.mjs";
+import {
+  agentSkillRootCandidates,
+  supportedAgentNames
+} from "./agent-skill-roots.mjs";
+
+const SHARE_MARKER = ".skillboard-share.json";
+
+export async function uninstallUser(options = {}) {
+  const env = options.env ?? process.env;
+  const home = await resolveSetupHome(env, options.runtime ?? {});
+  const planned = await planUserUninstall(home, env);
+  if (options.dryRun) {
+    const guidance = await uninstallAgentIntegration(planned.guidanceTargets, true);
+    return result(home, true, planned.managedCopies, guidance, planned.statePaths, planned.preserved);
+  }
+
+  const removedCopies = [];
+  const preserved = [...planned.preserved];
+  for (const copy of planned.managedCopies) {
+    if (await removeManagedCopy(copy)) {
+      removedCopies.push(copy);
+    } else {
+      preserved.push(copy.path);
+    }
+  }
+  const guidance = await uninstallAgentIntegration(planned.guidanceTargets, false);
+  const removedState = [];
+  for (const state of planned.statePaths) {
+    if (await removeStatePath(state)) removedState.push(state);
+    else preserved.push(state);
+  }
+  return result(home, false, removedCopies, guidance, removedState, preserved);
+}
+
+async function planUserUninstall(home, env) {
+  const preserved = [];
+  const roots = [{ root: join(home, ".agents", "shared-skills"), agent: null }];
+  for (const agent of supportedAgentNames()) {
+    for (const candidate of await agentSkillRootCandidates(agent, home, env)) {
+      roots.push({ root: candidate.skillRoot, agent });
+    }
+  }
+  const managedCopies = [];
+  const seenRoots = new Set();
+  for (const entry of roots) {
+    const root = resolve(entry.root);
+    if (seenRoots.has(root)) continue;
+    seenRoots.add(root);
+    managedCopies.push(...await managedCopiesInRoot(root, entry.agent, preserved));
+  }
+
+  const guidanceTargets = [];
+  for (const agent of supportedAgentNames()) {
+    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)),
+    guidanceTargets,
+    statePaths: await existingStatePaths(home),
+    preserved: [...new Set(preserved)].sort()
+  };
+}
+
+async function managedCopiesInRoot(root, agent, preserved) {
+  const stats = await pathStats(root);
+  if (stats === null) return [];
+  if (stats.isSymbolicLink() || !stats.isDirectory()) {
+    preserved.push(root);
+    return [];
+  }
+  const copies = [];
+  const entries = await readdir(root, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+    const path = join(root, entry.name);
+    const marker = await readManagedMarker(path, entry.name, agent);
+    if (marker !== null) copies.push({ path, skill: entry.name, agent, mode: marker.mode });
+  }
+  return copies;
+}
+
+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(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;
+  if (stats.isSymbolicLink() || !stats.isDirectory()) return false;
+  const marker = await readManagedMarker(copy.path, copy.skill, copy.agent);
+  if (marker === null || marker.mode !== copy.mode) return false;
+  await rm(copy.path, { recursive: true, force: true });
+  return true;
+}
+
+async function existingStatePaths(home) {
+  const result = [];
+  for (const path of [join(home, "skillboard.config.yaml"), join(home, ".skillboard")]) {
+    if (await pathStats(path) !== null) result.push(path);
+  }
+  return result;
+}
+
+async function removeStatePath(path) {
+  const stats = await pathStats(path);
+  if (stats === null) return true;
+  const name = basename(path);
+  const supported = name === "skillboard.config.yaml"
+    ? stats.isFile() || stats.isSymbolicLink()
+    : name === ".skillboard" && (stats.isDirectory() || stats.isSymbolicLink());
+  if (!supported) return false;
+  await rm(path, { recursive: stats.isDirectory(), force: true });
+  return true;
+}
+
+function result(home, dryRun, managedCopies, guidance, statePaths, preserved) {
+  return {
+    ok: true,
+    mode: "user",
+    dry_run: dryRun,
+    home,
+    managed_copies: managedCopies,
+    guidance,
+    state_paths: statePaths,
+    preserved: [...new Set([...preserved, ...guidance.preserved])].sort()
+  };
+}
+
+async function pathStats(path) {
+  return await lstat(path).catch((error) => {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  });
+}

package/src/workspace.mjs

@@ -1,7 +1,7 @@
 import { readdir, readFile, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import YAML from "yaml";
+import YAML from "yaml";
 import {
   readBoolean,
   readOptionalRecord,
@@ -19,16 +19,26 @@ import {
 } from "./domain/constants.mjs";
 import { parseInstallUnits } from "./install-units.mjs";
 import { normalizeSkillPath } from "./skill-paths.mjs";
+import { parseV2Policy, serializeV2Policy } from "./domain/v2-policy.mjs";
+import { loadV2InventoryIndex } from "./control/v2-guard.mjs";
+import { compatibilityForVersion } from "./compatibility.mjs";
 
+export { serializeV2Policy };
+
+/** @returns {Promise<any>} */
 export async function loadWorkspace(options) {
-  const configText = await readFile(options.configPath, "utf8");
-  const parsed = YAML.parse(configText);
+  const configText = await readFile(options.configPath, "utf8");
+  const parsed = YAML.parse(configText);
   const config = requireRecord(parsed, "config root");
   const version = parseVersion(config.version);
+  if (version === 2) {
+    return loadV2Workspace(config, options);
+  }
   const skills = parseSkills(config.skills);
   const installUnits = parseInstallUnits(config.install_units);
   return {
     version,
+    compatibility: compatibilityForVersion(version),
     defaults: parseDefaults(config.defaults),
     installedSkills: await discoverInstalledSkills(options.skillsRoot, skills, {
       configPath: options.configPath,
@@ -44,6 +54,29 @@ export async function loadWorkspace(options) {
   };
 }
 
+async function loadV2Workspace(config, options) {
+  const { workflows, skills } = parseV2Policy(config);
+  const inventoryPath = options.inventoryPath ?? join(dirname(options.configPath), ".skillboard", "inventory.json");
+  const inventory = await loadV2InventoryIndex(inventoryPath);
+  return {
+    version: 2,
+    compatibility: null,
+    defaults: {},
+    installedSkills: await discoverInstalledSkills(options.skillsRoot, skills, {
+      configPath: options.configPath,
+      env: options.env ?? process.env,
+      home: options.home,
+      installUnits: []
+    }),
+    skills,
+    capabilities: [],
+    harnesses: [],
+    installUnits: inventory.installUnits ?? [],
+    workflows,
+    inventory
+  };
+}
+
 async function discoverInstalledSkills(skillsRoot, declaredSkills, options = {}) {
   const installed = [];
   const installedKeys = new Set();
@@ -123,7 +156,7 @@ function resolveStoredPath(value, options) {
   }
   return resolve(dirname(options.configPath ?? "."), value);
 }
-
+
 async function findSkillFiles(root, seen = new Set()) {
   const files = [];
   const resolvedRoot = await realpath(root).catch(() => root);
@@ -148,8 +181,8 @@ async function findSkillFiles(root, seen = new Set()) {
     }
   }
   return files;
-}
-
+}
+
 function parseSkillFrontmatter(text) {
   const match = /^---[ \t]*\r?\n(?<body>[\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
   if (match?.groups === undefined) {
@@ -170,49 +203,56 @@ function parseSkillFrontmatter(text) {
     description: readString(raw, "description", "")
   };
 }
-
-function parseVersion(value) {
-  if (value === undefined) {
-    return 1;
-  }
-  if (value !== 1) {
-    throw new Error(`Unsupported config version: ${value}`);
-  }
-  return value;
-}
-
-function parseDefaults(value) {
-  const raw = requireRecord(value ?? {}, "defaults");
-  return {
-    invocationPolicy: readString(raw, "invocation_policy", "deny-by-default"),
-    allowModelInvocation: readBoolean(raw, "allow_model_invocation", false),
-    requireExplicitWorkflow: readBoolean(raw, "require_explicit_workflow", true)
-  };
-}
-
-function parseSkills(value) {
-  const raw = requireRecord(value ?? {}, "skills");
-  return Object.entries(raw).map(([id, entry]) => {
-    const skill = requireRecord(entry, `skills.${id}`);
-    const status = readString(skill, "status", "vendor");
-    const invocation = readString(skill, "invocation", "manual-only");
-    const exposure = readString(skill, "exposure", "exported");
-    if (!STATUS_VALUES.has(status)) {
-      throw new Error(`Unsupported status for ${id}: ${status}`);
-    }
-    if (!INVOCATION_VALUES.has(invocation)) {
-      throw new Error(`Unsupported invocation for ${id}: ${invocation}`);
-    }
-    if (!EXPOSURE_VALUES.has(exposure)) {
-      throw new Error(`Unsupported exposure for ${id}: ${exposure}`);
-    }
+
+function parseVersion(value) {
+  if (value === undefined) {
+    return 1;
+  }
+  if (value !== 1 && value !== 2) {
+    throw new Error(`Unsupported config version: ${value}`);
+  }
+  return value;
+}
+
+function parseDefaults(value) {
+  const raw = requireRecord(value ?? {}, "defaults");
+  return {
+    invocationPolicy: readString(raw, "invocation_policy", "deny-by-default"),
+    allowModelInvocation: readBoolean(raw, "allow_model_invocation", false),
+    requireExplicitWorkflow: readBoolean(raw, "require_explicit_workflow", true)
+  };
+}
+
+function parseSkills(value) {
+  const raw = requireRecord(value ?? {}, "skills");
+  return Object.entries(raw).map(([id, entry]) => {
+    const skill = requireRecord(entry, `skills.${id}`);
+    const v2Keys = ["enabled", "shared", "preference"].filter((key) => Object.prototype.hasOwnProperty.call(skill, key));
+    if (v2Keys.length > 0) {
+      throw new Error(
+        `skills.${id} uses version 2 key ${v2Keys.join(", ")} in a version 1 config. ` +
+        "Run `skillboard migrate v2` to convert the complete policy."
+      );
+    }
+    const status = readString(skill, "status", "vendor");
+    const invocation = readString(skill, "invocation", "manual-only");
+    const exposure = readString(skill, "exposure", "exported");
+    if (!STATUS_VALUES.has(status)) {
+      throw new Error(`Unsupported status for ${id}: ${status}`);
+    }
+    if (!INVOCATION_VALUES.has(invocation)) {
+      throw new Error(`Unsupported invocation for ${id}: ${invocation}`);
+    }
+    if (!EXPOSURE_VALUES.has(exposure)) {
+      throw new Error(`Unsupported exposure for ${id}: ${exposure}`);
+    }
     return {
       id,
       path: normalizeSkillPath(readString(skill, "path", id), `skills.${id}.path`),
-      status,
-      invocation,
-      exposure,
-      category: readString(skill, "category", "uncategorized"),
+      status,
+      invocation,
+      exposure,
+      category: readString(skill, "category", "uncategorized"),
       canonicalFor: readStringList(skill, "canonical_for"),
       conflictsWith: readStringList(skill, "conflicts_with"),
       replacedBy: readOptionalString(skill, "replaced_by"),
@@ -266,39 +306,39 @@ function parseCapabilities(value) {
     };
   });
 }
-
-function parseHarnesses(value) {
-  const raw = requireRecord(value ?? {}, "harnesses");
-  return Object.entries(raw).map(([name, entry]) => {
-    const harness = requireRecord(entry, `harnesses.${name}`);
-    const status = readString(harness, "status", "available");
-    if (!HARNESS_STATUS_VALUES.has(status)) {
-      throw new Error(`Unsupported harness status for ${name}: ${status}`);
-    }
-    return {
-      name,
-      status,
-      workflows: readStringList(harness, "workflows"),
-      commands: readStringList(harness, "commands")
-    };
-  });
-}
-
-function parseWorkflows(value) {
-  const raw = requireRecord(value ?? {}, "workflows");
-  return Object.entries(raw).map(([name, entry]) => {
-    const workflow = requireRecord(entry, `workflows.${name}`);
-    return {
-      name,
-      harness: readString(workflow, "harness", "unspecified"),
-      activeSkills: readStringList(workflow, "active_skills"),
-      blockedSkills: readStringList(workflow, "blocked_skills"),
-      requiredOutputs: readStringList(workflow, "required_outputs"),
-      requiredCapabilities: parseRequiredCapabilities(workflow.required_capabilities, `workflows.${name}.required_capabilities`)
-    };
-  });
-}
-
+
+function parseHarnesses(value) {
+  const raw = requireRecord(value ?? {}, "harnesses");
+  return Object.entries(raw).map(([name, entry]) => {
+    const harness = requireRecord(entry, `harnesses.${name}`);
+    const status = readString(harness, "status", "available");
+    if (!HARNESS_STATUS_VALUES.has(status)) {
+      throw new Error(`Unsupported harness status for ${name}: ${status}`);
+    }
+    return {
+      name,
+      status,
+      workflows: readStringList(harness, "workflows"),
+      commands: readStringList(harness, "commands")
+    };
+  });
+}
+
+function parseWorkflows(value) {
+  const raw = requireRecord(value ?? {}, "workflows");
+  return Object.entries(raw).map(([name, entry]) => {
+    const workflow = requireRecord(entry, `workflows.${name}`);
+    return {
+      name,
+      harness: readString(workflow, "harness", "unspecified"),
+      activeSkills: readStringList(workflow, "active_skills"),
+      blockedSkills: readStringList(workflow, "blocked_skills"),
+      requiredOutputs: readStringList(workflow, "required_outputs"),
+      requiredCapabilities: parseRequiredCapabilities(workflow.required_capabilities, `workflows.${name}.required_capabilities`)
+    };
+  });
+}
+
 function parseRequiredCapabilities(value, label) {
   const raw = requireRecord(value ?? {}, label);
   return Object.entries(raw).map(([name, entry]) => {