agent-skillboard 0.2.17 → 0.3.0

package/src/source-verification.mjs

@@ -1,11 +1,14 @@
-import { lstat, readFile, readdir, readlink, writeFile } from "node:fs/promises";
-import { createHash, verify as verifySignature } from "node:crypto";
+import { lstat, readFile, writeFile } from "node:fs/promises";
+import { verify as verifySignature } from "node:crypto";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import YAML from "yaml";
+import { auditPath, expandPortablePath, portableObservation, redactPathError } from "./audit-paths.mjs";
 import { installUnitSourceClass, isLocalSourceReference } from "./domain/source-classes.mjs";
+import { V1_MUTATION_ERROR } from "./compatibility.mjs";
+import { skillContentDigest, sourceDigest } from "./source-digest.mjs";
 
-const DIGEST_PREFIX = "sha256:";
+export { skillContentDigest, sourceDigest };
 
 export async function verifySources(workspace, options = {}) {
   const configDir = options.configPath === undefined ? process.cwd() : dirname(resolve(options.configPath));
@@ -24,6 +27,7 @@ export async function verifySources(workspace, options = {}) {
 }
 
 export async function writeLockfile(workspace, options) {
+  if (workspace.version === 1) throw new Error(V1_MUTATION_ERROR);
   const verified = await verifySources(workspace, { configPath: options.configPath, rootDir: options.rootDir });
   if (!verified.ok && options.allowUnverified !== true) {
     throw new Error(`Cannot write lockfile because source verification failed:\n${verified.errors.join("\n")}`);
@@ -34,6 +38,7 @@ export async function writeLockfile(workspace, options) {
 }
 
 export async function renderLockfile(workspace, options = {}) {
+  if (workspace.version === 2) return renderV2Lockfile(workspace, options);
   const verified = options.verified ?? await verifySources(workspace, { configPath: options.configPath, rootDir: options.rootDir });
   const generatedAt = options.generatedAt ?? new Date().toISOString();
   const skillDigests = await skillContentDigests(workspace, options.skillsRoot);
@@ -76,6 +81,20 @@ export async function renderLockfile(workspace, options = {}) {
   });
 }
 
+async function renderV2Lockfile(workspace, options) {
+  const generatedAt = options.generatedAt ?? new Date().toISOString();
+  return YAML.stringify({
+    version: 2,
+    policy_projection_version: 2,
+    generated_at: generatedAt,
+    audit_authoritative_for_availability: false,
+    skills: Object.fromEntries(workspace.skills.map((skill) => [skill.id, {
+      enabled: skill.enabled,
+      shared: skill.shared
+    }]))
+  });
+}
+
 async function verifyInstallUnit(unit, options) {
   const target = await verificationTarget(unit, options);
   const localPath = target.path;
@@ -87,7 +106,7 @@ async function verifyInstallUnit(unit, options) {
 
   if (localPath !== null && options.restrictToRoot === true && !isPathInside(options.rootDir, localPath)) {
     status = "unverified";
-    findings.push({ severity: "error", message: `${target.field} is outside the allowed root: ${localPath}` });
+    findings.push({ severity: "error", message: `${target.field} is outside the allowed root: ${auditPath(localPath, options)}` });
   } else if (localPath === null) {
     if (unit.sourceDigest === undefined) {
       findings.push({ severity: "warning", message: "remote or command source has no source_digest pin" });
@@ -117,16 +136,16 @@ async function verifyInstallUnit(unit, options) {
       }
     } catch (error) {
       status = "unverified";
-      findings.push({ severity: "error", message: `cannot verify local source: ${error instanceof Error ? error.message : String(error)}` });
+      findings.push({ severity: "error", message: `cannot verify local source: ${redactPathError(error, options)}` });
     }
   }
 
   return {
     id: unit.id,
     kind: unit.kind,
-    source: unit.source,
-    cachePath: unit.cachePath.length === 0 ? null : unit.cachePath,
-    verifiedPath: localPath,
+    source: portableObservation(unit.source, options),
+    cachePath: unit.cachePath.length === 0 ? null : portableObservation(unit.cachePath, options),
+    verifiedPath: localPath === null ? null : auditPath(localPath, options),
     verifiedField: target.field,
     sourceClass: installUnitSourceClass(unit),
     trustLevel: unit.trustLevel,
@@ -156,39 +175,6 @@ async function verificationTarget(unit, options) {
   return { path: await localSourcePath(unit.source, options, { allowBareRelative: false }), field: "source" };
 }
 
-export async function sourceDigest(path) {
-  const hash = createHash("sha256");
-  hash.update("skillboard-source-digest-v1\n");
-  await addPathDigest(hash, path, path);
-  return `${DIGEST_PREFIX}${hash.digest("hex")}`;
-}
-
-async function addPathDigest(hash, root, path) {
-  const stats = await lstat(path);
-  const rel = relative(root, path).replace(/\\/g, "/") || ".";
-  if (stats.isSymbolicLink()) {
-    hash.update(`symlink\0${rel}\0${await readlink(path)}\n`);
-    return;
-  }
-  if (stats.isDirectory()) {
-    hash.update(`dir\0${rel}\n`);
-    const entries = (await readdir(path, { withFileTypes: true }))
-      .filter((entry) => entry.name !== ".git" && entry.name !== "node_modules")
-      .sort((left, right) => left.name.localeCompare(right.name));
-    for (const entry of entries) {
-      await addPathDigest(hash, root, join(path, entry.name));
-    }
-    return;
-  }
-  if (!stats.isFile()) {
-    hash.update(`other\0${rel}\n`);
-    return;
-  }
-  hash.update(`file\0${rel}\0${stats.size}\0`);
-  hash.update(await readFile(path));
-  hash.update("\n");
-}
-
 function verifyDigestSignature(digest, signature, publicKey) {
   try {
     return verifySignature("sha256", Buffer.from(digest), publicKey, Buffer.from(signature, "base64"));
@@ -198,7 +184,10 @@ function verifyDigestSignature(digest, signature, publicKey) {
 }
 
 async function localSourcePath(source, paths, options) {
-  const value = source.trim();
+  const value = expandPortablePath(source.trim(), paths);
+  if (value === null) {
+    return null;
+  }
   if (!isLocalSourceReference(value, options)) {
     return null;
   }
@@ -215,6 +204,7 @@ async function localSourcePath(source, paths, options) {
   return await firstExistingPath(candidates) ?? candidates[0] ?? null;
 }
 
+
 async function firstExistingPath(paths) {
   for (const path of paths) {
     try {
@@ -233,12 +223,6 @@ function uniquePaths(paths) {
   return [...new Set(paths)];
 }
 
-export async function skillContentDigest(skillFilePath) {
-  const hash = createHash("sha256");
-  hash.update(await readFile(skillFilePath));
-  return `${DIGEST_PREFIX}${hash.digest("hex")}`;
-}
-
 async function skillContentDigests(workspace, skillsRoot) {
   const digests = new Map();
   if (skillsRoot === undefined) {

package/src/uninstall.mjs

@@ -54,6 +54,12 @@ export async function uninstallProject(options) {
       }
       recordFileResult(entry.label, result, { removed, updated, preserved });
     }
+    if (!keepBridge) {
+      const inventoryPath = join(root, ".skillboard", "inventory.json");
+      const inventoryResult = await removeGeneratedInventory(inventoryPath, dryRun, root);
+      if (inventoryResult === "removed") plannedRemovedPaths.add(inventoryPath);
+      recordFileResult(".skillboard/inventory.json", inventoryResult, { removed, updated, preserved });
+    }
   }
 
   if (options.removeReports === true && options.removeProjectState !== true) {
@@ -200,6 +206,22 @@ async function removeGeneratedFile(path, expected, dryRun, root = null) {
   return "removed";
 }
 
+async function removeGeneratedInventory(path, dryRun, root) {
+  if (await hasUnsafeAncestor(path, root)) return "preserved";
+  const stats = await pathStats(path);
+  if (stats === null) return "absent";
+  if (stats.isSymbolicLink() || !stats.isFile()) return "preserved";
+  let inventory;
+  try {
+    inventory = JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return "preserved";
+  }
+  if (inventory?.generated !== true || inventory?.authoritative_for_availability !== false) return "preserved";
+  if (!dryRun) await rm(path);
+  return "removed";
+}
+
 async function removeConfigFile(path, dryRun) {
   const stats = await pathStats(path);
   if (stats === null) {

package/src/user-state-paths.mjs

@@ -0,0 +1,19 @@
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+export function resolveUserStatePaths(options = {}) {
+  const home = resolve(options.home ?? options.env?.HOME ?? options.env?.USERPROFILE ?? homedir());
+  const configPath = options.configPath === undefined
+    ? join(home, "skillboard.config.yaml")
+    : resolveFrom(options.configPath, options.cwd ?? process.cwd());
+  const inventoryPath = options.inventoryPath === undefined
+    ? options.configPath === undefined
+      ? join(home, ".skillboard", "inventory.json")
+      : join(dirname(configPath), ".skillboard", "inventory.json")
+    : resolveFrom(options.inventoryPath, options.cwd ?? process.cwd());
+  return { home, configPath, inventoryPath, stateRoot: dirname(inventoryPath) };
+}
+
+function resolveFrom(path, cwd) {
+  return isAbsolute(path) ? resolve(path) : resolve(cwd, path);
+}

package/src/user-uninstall.mjs

@@ -0,0 +1,146 @@
+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,
+  setupAgentSkillTargets,
+  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()) {
+    guidanceTargets.push(...await setupAgentSkillTargets(agent, home, env));
+  }
+  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(JSON.parse, () => 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;
+}
+
+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

@@ -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 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();
@@ -175,7 +208,7 @@ function parseVersion(value) {
   if (value === undefined) {
     return 1;
   }
-  if (value !== 1) {
+  if (value !== 1 && value !== 2) {
     throw new Error(`Unsupported config version: ${value}`);
   }
   return value;
@@ -194,6 +227,13 @@ 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");