agent-skillboard 0.2.18 → 0.3.1

package/src/source-profiles.mjs

@@ -1,26 +1,26 @@
-import { readdir, readFile } from "node:fs/promises";
-import { basename, dirname, join, relative, resolve } from "node:path";
-import YAML from "yaml";
+import { readdir, readFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import YAML from "yaml";
 import { readString, requireRecord } from "./config-helpers.mjs";
 import { textChangePlan } from "./change-plan.mjs";
 import { loadSourceProfile } from "./source-profile-loader.mjs";
-
-export { loadSourceProfile };
-
-export async function importSource(options) {
-  const sourceRoot = resolve(options.sourceRoot);
-  const profile = options.profile;
-  const files = await findSkillFiles(sourceRoot);
-  const matchedFiles = files
-    .map((file) => ({
-      file,
+
+export { loadSourceProfile };
+
+export async function importSource(options) {
+  const sourceRoot = resolve(options.sourceRoot);
+  const profile = options.profile;
+  const files = await findSkillFiles(sourceRoot);
+  const matchedFiles = files
+    .map((file) => ({
+      file,
       relativeFile: relative(sourceRoot, file).replace(/\\/g, "/")
-    }))
-    .filter((entry) => matchesAnyProfilePattern(entry.relativeFile, profile.skillPaths))
-    .sort((left, right) => left.relativeFile.localeCompare(right.relativeFile));
-  const skills = [];
-  const warnings = [];
-
+    }))
+    .filter((entry) => matchesAnyProfilePattern(entry.relativeFile, profile.skillPaths))
+    .sort((left, right) => left.relativeFile.localeCompare(right.relativeFile));
+  const skills = [];
+  const warnings = [];
+
   for (const entry of matchedFiles) {
     const frontmatter = parseSkillFrontmatter(await readFile(entry.file, "utf8"));
     const pathRule = matchingPathRule(entry.relativeFile, profile);
@@ -30,6 +30,7 @@ export async function importSource(options) {
     skills.push({
       id,
       path,
+      skillFile: entry.file,
       status: pathRule?.status ?? profile.defaultStatus,
       invocation: safeDefaultInvocation(pathRule?.invocation ?? profile.defaultInvocation),
       exposure: pathRule?.exposure ?? profile.defaultExposure,
@@ -37,17 +38,17 @@ export async function importSource(options) {
       ownerInstallUnit: profile.id,
       description: frontmatter.description
     });
-  }
-
-  if (skills.length === 0) {
-    warnings.push(`No SKILL.md files matched profile ${profile.id} under ${sourceRoot}`);
-  }
-
-  return {
-    profile,
-    sourceRoot,
-    skills,
-    installUnit: {
+  }
+
+  if (skills.length === 0) {
+    warnings.push(`No SKILL.md files matched profile ${profile.id} under ${sourceRoot}`);
+  }
+
+  return {
+    profile,
+    sourceRoot,
+    skills,
+    installUnit: {
       id: profile.id,
       kind: profile.kind,
       sourceClass: profile.sourceClass,
@@ -58,37 +59,40 @@ export async function importSource(options) {
       publicKey: profile.publicKey,
       verifiedAt: profile.verifiedAt,
       source: profile.source || sourceRoot,
-      scope: profile.scope,
-      manifestPath: profile.manifestPath,
-      cachePath: profile.cachePath,
-      providedComponents: profile.providedComponents,
-      components: {
-        skills: skills.map((skill) => skill.id),
-        commands: profile.components.commands,
-        hooks: profile.components.hooks,
-        mcpServers: profile.components.mcpServers
-      },
-      modifiedConfigFiles: profile.modifiedConfigFiles,
-      autoUpdate: profile.autoUpdate,
-      enabled: profile.enabled,
-      workflowDependencies: profile.workflowDependencies,
-      permissionRisk: profile.permissionRisk,
-      rollback: profile.rollback
-    },
-    warnings
-  };
-}
-
-export function renderImportFragment(imported) {
-  return YAML.stringify(importFragment(imported));
-}
-
+      scope: profile.scope,
+      manifestPath: profile.manifestPath,
+      cachePath: profile.cachePath,
+      providedComponents: profile.providedComponents,
+      components: {
+        skills: skills.map((skill) => skill.id),
+        commands: profile.components.commands,
+        hooks: profile.components.hooks,
+        mcpServers: profile.components.mcpServers
+      },
+      modifiedConfigFiles: profile.modifiedConfigFiles,
+      autoUpdate: profile.autoUpdate,
+      enabled: profile.enabled,
+      workflowDependencies: profile.workflowDependencies,
+      permissionRisk: profile.permissionRisk,
+      rollback: profile.rollback
+    },
+    warnings
+  };
+}
+
+export function renderImportFragment(imported) {
+  return YAML.stringify(importFragment(imported));
+}
+
 export function mergeImportFragment(configText, imported, options = {}) {
   const document = YAML.parseDocument(configText);
   if (document.errors.length > 0) {
     throw new Error(`Invalid YAML config: ${document.errors.map((error) => error.message).join("; ")}`);
   }
   requireYamlMap(document.contents, "config root");
+  if (document.get("version") === 2) {
+    return mergeV2ImportFragment(document, configText, imported);
+  }
   const fragment = importFragment(imported);
   const replace = options.replace === true;
   const skillIds = Object.keys(fragment.skills);
@@ -117,7 +121,30 @@ export function mergeImportFragment(configText, imported, options = {}) {
     addedSkills: skillIds,
     addedInstallUnits: unitIds,
     replacedSkills: duplicateSkills,
-    replacedInstallUnits: duplicateUnits
+    replacedInstallUnits: duplicateUnits
+  };
+}
+
+function mergeV2ImportFragment(document, configText, imported) {
+  const existingSkills = ensureMap(document, "skills");
+  const addedSkills = [];
+  for (const skill of imported.skills) {
+    if (existingSkills.get(skill.id, true) !== undefined) {
+      continue;
+    }
+    existingSkills.set(skill.id, document.createNode({ enabled: true, shared: false }));
+    addedSkills.push(skill.id);
+  }
+  const text = preserveLineEndings(String(document), configText);
+  const plan = textChangePlan(configText, text);
+  return {
+    text,
+    changed: plan.changed,
+    plan,
+    addedSkills,
+    addedInstallUnits: [],
+    replacedSkills: [],
+    replacedInstallUnits: []
   };
 }
 
@@ -141,20 +168,20 @@ function requireYamlMap(value, label) {
 function preserveLineEndings(text, reference) {
   return reference.includes("\r\n") ? text.replace(/\n/g, "\r\n") : text;
 }
-
+
 function importFragment(imported) {
-  const skills = {};
-  for (const skill of imported.skills) {
-    skills[skill.id] = {
-      path: skill.path,
-      status: skill.status,
-      invocation: skill.invocation,
-      exposure: skill.exposure,
-      category: skill.category,
-      owner_install_unit: skill.ownerInstallUnit
-    };
-  }
-  const unit = imported.installUnit;
+  const skills = {};
+  for (const skill of imported.skills) {
+    skills[skill.id] = {
+      path: skill.path,
+      status: skill.status,
+      invocation: skill.invocation,
+      exposure: skill.exposure,
+      category: skill.category,
+      owner_install_unit: skill.ownerInstallUnit
+    };
+  }
+  const unit = imported.installUnit;
   return stripUndefined({
     skills,
     install_units: {
@@ -168,64 +195,64 @@ function importFragment(imported) {
         public_key: unit.publicKey,
         verified_at: unit.verifiedAt,
         source: unit.source,
-        scope: unit.scope,
-        manifest_path: unit.manifestPath,
-        cache_path: unit.cachePath,
-        provided_components: unit.providedComponents,
-        components: {
-          skills: unit.components.skills,
-          commands: unit.components.commands,
-          hooks: unit.components.hooks,
-          mcp_servers: unit.components.mcpServers
-        },
-        modified_config_files: unit.modifiedConfigFiles,
-        auto_update: unit.autoUpdate,
-        enabled: unit.enabled,
-        workflow_dependencies: unit.workflowDependencies,
-        permission_risk: unit.permissionRisk,
+        scope: unit.scope,
+        manifest_path: unit.manifestPath,
+        cache_path: unit.cachePath,
+        provided_components: unit.providedComponents,
+        components: {
+          skills: unit.components.skills,
+          commands: unit.components.commands,
+          hooks: unit.components.hooks,
+          mcp_servers: unit.components.mcpServers
+        },
+        modified_config_files: unit.modifiedConfigFiles,
+        auto_update: unit.autoUpdate,
+        enabled: unit.enabled,
+        workflow_dependencies: unit.workflowDependencies,
+        permission_risk: unit.permissionRisk,
         rollback: unit.rollback
       }
     }
   });
 }
-
-function duplicateMessage(skillIds, unitIds) {
-  const parts = [];
-  if (skillIds.length > 0) {
-    parts.push(`skills already exist: ${skillIds.join(", ")}`);
-  }
-  if (unitIds.length > 0) {
-    parts.push(`install units already exist: ${unitIds.join(", ")}`);
-  }
-  return `${parts.join("; ")}. Re-run with --replace to overwrite.`;
-}
-
-async function findSkillFiles(root) {
-  const files = [];
-  const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
-  for (const entry of entries) {
-    const path = join(root, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...(await findSkillFiles(path)));
-    } else if (entry.isFile() && entry.name === "SKILL.md") {
-      files.push(path);
-    }
-  }
-  return files;
-}
-
-function parseSkillFrontmatter(text) {
-  const match = /^---[ \t]*\r?\n(?<body>[\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
-  if (match?.groups === undefined) {
-    throw new Error("SKILL.md is missing YAML frontmatter");
-  }
-  const raw = requireRecord(YAML.parse(match.groups.body), "SKILL.md frontmatter");
-  return {
-    name: readString(raw, "name", ""),
-    description: readString(raw, "description", "")
-  };
-}
-
+
+function duplicateMessage(skillIds, unitIds) {
+  const parts = [];
+  if (skillIds.length > 0) {
+    parts.push(`skills already exist: ${skillIds.join(", ")}`);
+  }
+  if (unitIds.length > 0) {
+    parts.push(`install units already exist: ${unitIds.join(", ")}`);
+  }
+  return `${parts.join("; ")}. Re-run with --replace to overwrite.`;
+}
+
+async function findSkillFiles(root) {
+  const files = [];
+  const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await findSkillFiles(path)));
+    } else if (entry.isFile() && entry.name === "SKILL.md") {
+      files.push(path);
+    }
+  }
+  return files;
+}
+
+function parseSkillFrontmatter(text) {
+  const match = /^---[ \t]*\r?\n(?<body>[\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
+  if (match?.groups === undefined) {
+    throw new Error("SKILL.md is missing YAML frontmatter");
+  }
+  const raw = requireRecord(YAML.parse(match.groups.body), "SKILL.md frontmatter");
+  return {
+    name: readString(raw, "name", ""),
+    description: readString(raw, "description", "")
+  };
+}
+
 function matchesAnyProfilePattern(file, patterns) {
   const activePatterns = patterns.length === 0 ? ["**/SKILL.md"] : patterns;
   return activePatterns.some((pattern) => patternToRegExp(pattern).test(file));
@@ -234,16 +261,16 @@ function matchesAnyProfilePattern(file, patterns) {
 function matchingPathRule(file, profile) {
   return (profile.pathRules ?? []).find((rule) => patternToRegExp(rule.pattern).test(file));
 }
-
-function patternToRegExp(pattern) {
-  const escaped = pattern
-    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+
+function patternToRegExp(pattern) {
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
     .split("**").join("\0")
     .split("*").join("[^/]*")
     .split("\0").join(".*");
-  return new RegExp(`^${escaped}$`);
-}
-
+  return new RegExp(`^${escaped}$`);
+}
+
 function skillSlug(relativeFile, frontmatter, profile) {
   if (profile.idStrategy === "frontmatter-name" && frontmatter.name.length > 0) {
     const segments = frontmatter.name.split(".");
@@ -251,14 +278,14 @@ function skillSlug(relativeFile, frontmatter, profile) {
   }
   return normalizeSlug(basename(dirname(relativeFile)));
 }
-
-function skillId(slug, frontmatter, profile) {
-  if (profile.idStrategy === "frontmatter-name" && frontmatter.name.includes(".")) {
-    return frontmatter.name;
-  }
-  return profile.namespace.length === 0 ? slug : `${profile.namespace}.${slug}`;
-}
-
+
+function skillId(slug, frontmatter, profile) {
+  if (profile.idStrategy === "frontmatter-name" && frontmatter.name.includes(".")) {
+    return frontmatter.name;
+  }
+  return profile.namespace.length === 0 ? slug : `${profile.namespace}.${slug}`;
+}
+
 function skillTargetPath(slug, profile) {
   return profile.targetPathPrefix.length === 0 ? slug : `${profile.targetPathPrefix}/${slug}`;
 }
@@ -276,13 +303,13 @@ function categoryFromPath(relativeFile, profile) {
 }
 
 function normalizeSlug(value) {
-  return value
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9._-]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-}
-
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
 function safeDefaultInvocation(invocation) {
   return invocation === "global-auto" ? "blocked" : invocation;
 }

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);
+}