agent-skillboard 0.2.18 → 0.3.0

package/src/inventory-json.mjs

@@ -0,0 +1,279 @@
+import { basename, isAbsolute, relative, resolve } from "node:path";
+import YAML from "yaml";
+import { coalesceInventoryInstallUnits } from "./inventory-install-units.mjs";
+import { normalizeSkillPath } from "./skill-paths.mjs";
+import { skillContentDigest } from "./source-verification.mjs";
+
+const FORMAT_VERSION = 1;
+
+export async function buildGeneratedInventory(inventory, options = {}) {
+  const redactions = redactionContext(options);
+  const integrityErrors = [];
+  const skills = [];
+  for (const skill of [...(inventory.skills ?? [])].sort(byId)) {
+    try {
+      skills.push(await inventorySkillRecord(skill, redactions));
+    } catch (error) {
+      integrityErrors.push(`${skill?.id || "<missing-id>"}: ${errorMessage(error)}`);
+    }
+  }
+  if (integrityErrors.length > 0) {
+    throw new Error(`Inventory integrity error:\n${integrityErrors.join("\n")}`);
+  }
+  const installUnits = coalesceInventoryInstallUnits([...(inventory.installUnits ?? [])]
+    .sort(byId)
+    .map((unit) => inventoryInstallUnitRecord(unit, redactions)));
+  return {
+    format_version: FORMAT_VERSION,
+    generated: true,
+    authoritative_for_availability: false,
+    skills,
+    install_units: installUnits,
+    redactions: {
+      path_count: redactions.pathCount,
+      warnings: [...redactions.warnings].sort()
+    }
+  };
+}
+
+export function renderGeneratedInventory(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+export function mergeGeneratedInventory(existingText, added, options = {}) {
+  const existing = parseExistingInventory(existingText);
+  const replace = options.replace === true;
+  const skills = mergeRecords(existing.skills, added.skills ?? [], replace);
+  const installUnits = mergeRecords(existing.install_units ?? [], added.install_units ?? [], replace);
+  const warnings = uniqueStrings([
+    ...(existing.redactions?.warnings ?? []),
+    ...(added.redactions?.warnings ?? [])
+  ]);
+  return renderGeneratedInventory({
+    ...existing,
+    format_version: FORMAT_VERSION,
+    generated: true,
+    authoritative_for_availability: false,
+    skills,
+    install_units: installUnits,
+    redactions: {
+      path_count: countPortablePaths(skills, installUnits),
+      warnings
+    }
+  });
+}
+
+export function mergeV2InventoryPolicy(configText, inventory) {
+  const document = YAML.parseDocument(configText);
+  if (document.errors.length > 0) {
+    throw new Error(`Invalid YAML config: ${document.errors.map((error) => error.message).join("; ")}`);
+  }
+  if (document.get("version") !== 2) {
+    throw new Error("v2 inventory policy projection requires config version 2");
+  }
+  let skills = document.get("skills", true);
+  if (skills === undefined) {
+    skills = document.createNode({});
+    document.set("skills", skills);
+  }
+  if (!YAML.isMap(skills)) {
+    throw new Error("skills must be a mapping");
+  }
+  const addedSkills = [];
+  for (const skill of [...(inventory.skills ?? [])].sort(byId)) {
+    validateSkillIdentity(skill);
+    if (skills.get(skill.id, true) !== undefined) {
+      continue;
+    }
+    skills.set(skill.id, document.createNode({ enabled: true, shared: false }));
+    addedSkills.push(skill.id);
+  }
+  const parsed = document.toJS();
+  const policyProjection = Object.fromEntries(
+    Object.entries(parsed.skills ?? {}).map(([id, policy]) => [id, policy])
+  );
+  const text = preserveLineEndings(String(document), configText);
+  return { text, changed: text !== configText, addedSkills, policyProjection };
+}
+
+async function inventorySkillRecord(skill, redactions) {
+  validateSkillIdentity(skill);
+  const aliases = uniqueAliases(skill.sourceAliases ?? []);
+  let contentDigest = null;
+  if (typeof skill.skillFile === "string" && skill.skillFile.length > 0) {
+    if (!isAbsolute(skill.skillFile)) {
+      throw new Error("skill file must be absolute");
+    }
+    contentDigest = await skillContentDigest(skill.skillFile);
+  }
+  return compact({
+    id: skill.id,
+    path: normalizeSkillPath(skill.path, `inventory skill ${skill.id} path`),
+    owner_install_unit: nonEmptyString(skill.ownerInstallUnit, `inventory skill ${skill.id} owner install unit`),
+    source: portableSource(skill.source, redactions),
+    category: skill.category,
+    description: skill.description,
+    content_digest: contentDigest,
+    installed_on: installedAgents(skill),
+    aliases
+  });
+}
+
+function installedAgents(skill) {
+  return uniqueStrings([
+    agentForInstallUnit(skill.ownerInstallUnit),
+    ...(skill.sourceAliases ?? []).map((alias) => agentForInstallUnit(alias.ownerInstallUnit))
+  ]);
+}
+
+function agentForInstallUnit(unitId) {
+  if (typeof unitId !== "string") return "";
+  for (const agent of ["codex", "claude", "opencode", "hermes"]) {
+    if (unitId === agent || unitId.startsWith(`${agent}.`)) return agent;
+  }
+  return "";
+}
+
+function inventoryInstallUnitRecord(unit, redactions) {
+  return compact({
+    id: nonEmptyString(unit.id, "inventory install unit id"),
+    kind: unit.kind,
+    source: portableSource(unit.source, redactions),
+    source_class: unit.sourceClass,
+    manifest_path: portablePath(unit.manifestPath, redactions),
+    cache_path: portablePath(unit.cachePath, redactions),
+    trust_observation: unit.trustLevel,
+    permission_risk: unit.permissionRisk,
+    source_digest: unit.sourceDigest,
+    signature_observed: typeof unit.signature === "string" && unit.signature.length > 0,
+    runtime_components: {
+      commands: uniqueStrings(unit.commands ?? unit.components?.commands ?? []),
+      hooks: uniqueStrings(unit.hooks ?? unit.components?.hooks ?? []),
+      mcp_servers: uniqueStrings(unit.mcpServers ?? unit.components?.mcpServers ?? [])
+    },
+    skills: uniqueStrings(unit.skills ?? unit.components?.skills ?? []),
+    alias_skills: uniqueStrings(unit.sourceAliasSkills ?? [])
+  });
+}
+
+function validateSkillIdentity(skill) {
+  if (skill === null || typeof skill !== "object") {
+    throw new Error("inventory skill must be an object");
+  }
+  nonEmptyString(skill.id, "inventory skill id");
+  normalizeSkillPath(skill.path, `inventory skill ${skill.id} path`);
+  nonEmptyString(skill.ownerInstallUnit, `inventory skill ${skill.id} owner install unit`);
+}
+
+function uniqueAliases(aliases) {
+  const seen = new Set();
+  const result = [];
+  for (const alias of aliases) {
+    const owner = nonEmptyString(alias.ownerInstallUnit, "inventory alias owner install unit");
+    const path = normalizeSkillPath(alias.path, "inventory alias path");
+    const key = `${owner}\0${path}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push({ owner_install_unit: owner, path });
+    }
+  }
+  return result.sort((left, right) => `${left.owner_install_unit}\0${left.path}`.localeCompare(`${right.owner_install_unit}\0${right.path}`));
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === "string" && value.length > 0))].sort();
+}
+
+function mergeRecords(existing, added, replace) {
+  const records = new Map(existing.map((record) => [record.id, record]));
+  for (const record of added) {
+    if (replace || !records.has(record.id)) records.set(record.id, record);
+  }
+  return [...records.values()].sort(byId);
+}
+
+function parseExistingInventory(text) {
+  if (text === null || text === undefined || text.trim() === "") {
+    return { skills: [], install_units: [] };
+  }
+  const value = JSON.parse(text);
+  if (value?.format_version !== FORMAT_VERSION || value.generated !== true || value.authoritative_for_availability !== false) {
+    throw new Error("Existing generated inventory has an unsupported format");
+  }
+  if (!Array.isArray(value.skills) || (value.install_units !== undefined && !Array.isArray(value.install_units))) {
+    throw new Error("Existing generated inventory records must be arrays");
+  }
+  return value;
+}
+
+function countPortablePaths(skills, installUnits) {
+  return [
+    ...skills.map((skill) => skill.source),
+    ...installUnits.flatMap((unit) => [
+      ...(unit.source_observations ?? [unit.source]),
+      ...(unit.manifest_path_observations ?? [unit.manifest_path]),
+      ...(unit.cache_path_observations ?? [unit.cache_path])
+    ])
+  ].filter((value) => typeof value === "string" && /^(?:\$\{PROJECT\}|\$\{HOME\}|<external>)(?:\/|$)/u.test(value)).length;
+}
+
+function redactionContext(options) {
+  return {
+    root: options.root === undefined ? undefined : resolve(options.root),
+    home: options.home === undefined ? undefined : resolve(options.home),
+    pathCount: 0,
+    warnings: new Set()
+  };
+}
+
+function portableSource(value, context) {
+  return typeof value === "string" && (isAbsolute(value) || value.startsWith("~/"))
+    ? portablePath(value, context)
+    : value;
+}
+
+function portablePath(value, context) {
+  if (typeof value !== "string" || value.length === 0) return value;
+  if (value.startsWith("~/")) {
+    context.pathCount += 1;
+    return `\${HOME}/${value.slice(2)}`;
+  }
+  if (!isAbsolute(value)) return value;
+  context.pathCount += 1;
+  const projectPath = tokenizedPath(value, context.root, "PROJECT");
+  if (projectPath !== null) return projectPath;
+  const homePath = tokenizedPath(value, context.home, "HOME");
+  if (homePath !== null) return homePath;
+  context.warnings.add("Generated inventory redacted one or more external absolute paths.");
+  return `<external>/${basename(value)}`;
+}
+
+function tokenizedPath(path, base, token) {
+  if (base === undefined) return null;
+  const rel = relative(base, resolve(path));
+  if (rel.startsWith("..") || isAbsolute(rel)) return null;
+  return rel === "" ? `\${${token}}` : `\${${token}}/${rel.replace(/\\/g, "/")}`;
+}
+
+function compact(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+
+function nonEmptyString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function byId(left, right) {
+  return String(left?.id ?? "").localeCompare(String(right?.id ?? ""));
+}
+
+function preserveLineEndings(text, original) {
+  return original.includes("\r\n") ? text.replace(/(?<!\r)\n/g, "\r\n") : text;
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/inventory-refresh.mjs

@@ -1,45 +1,190 @@
-import { readFile, writeFile } from "node:fs/promises";
-import { isAbsolute, resolve } from "node:path";
+import { chmod, lstat, mkdir, open, readFile, realpath, rm } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import YAML from "yaml";
 import { discoverAgentSkillInventory, mergeAgentSkillInventory } from "./agent-inventory.mjs";
 import { textChangePlan } from "./change-plan.mjs";
+import { buildGeneratedInventory, mergeV2InventoryPolicy, renderGeneratedInventory } from "./inventory-json.mjs";
+import { atomicWrite, optionalRead } from "./migration/v2-files.mjs";
+import { loadWorkspace } from "./workspace.mjs";
+
+const MINIMAL_V2_POLICY = "version: 2\nskills: {}\n";
 
 export async function refreshAgentInventory(options = {}) {
   const root = resolve(options.root ?? ".");
-  const configPath = resolveUnderRoot(root, options.configPath ?? "skillboard.config.yaml");
-  const inventory = await discoverAgentSkillInventory({
+  const configPath = resolveUnderRoot(root, options.configPath ?? "skillboard.config.yaml", "Inventory refresh config path");
+  return withRefreshLock(root, async () => refreshLocked({ ...options, root, configPath }));
+}
+
+async function refreshLocked(options) {
+  const { root, configPath } = options;
+  const configStats = await lstat(configPath).catch(missingOnly);
+  if (configStats?.isSymbolicLink()) {
+    throw new Error("Inventory refresh config path must not be a symbolic link.");
+  }
+  const bootstrappedV2 = configStats === undefined;
+  const current = bootstrappedV2 ? MINIMAL_V2_POLICY : await readFile(configPath, "utf8");
+  if (!bootstrappedV2) {
+    await loadWorkspace({ configPath });
+  }
+  const inventory = options.inventory ?? await discoverAgentSkillInventory({
     roots: options.roots,
     home: options.home,
     env: options.env
   });
-  const current = await readFile(configPath, "utf8");
-  const merged = mergeAgentSkillInventory(current, inventory);
+  const configVersion = YAML.parse(current)?.version;
+  const generatedInventory = configVersion === 2
+    ? await buildGeneratedInventory(inventory, { root, home: options.home ?? options.env?.HOME })
+    : null;
+  const inventoryPath = resolveUnderRoot(root, options.inventoryPath ?? ".skillboard/inventory.json", "Generated inventory target");
+  const inventoryText = generatedInventory === null ? null : renderGeneratedInventory(generatedInventory);
+  if (inventoryText !== null) {
+    await assertGeneratedInventoryTarget(root, inventoryPath);
+  }
+  const previousInventoryText = inventoryText === null
+    ? null
+    : await readFile(inventoryPath, "utf8").catch((error) => error?.code === "ENOENT" ? "" : Promise.reject(error));
+  const merged = configVersion === 2
+    ? mergeV2InventoryPolicy(current, inventory)
+    : mergeAgentSkillInventory(current, inventory);
   const plan = textChangePlan(current, merged.text);
   const dryRun = options.dryRun === true;
 
-  if (plan.changed && !dryRun) {
-    await writeFile(configPath, merged.text, "utf8");
+  const inventoryChanged = inventoryText !== null && inventoryText !== previousInventoryText;
+  if (!dryRun) {
+    const [previousConfig, previousInventory] = await Promise.all([
+      optionalRead(configPath),
+      inventoryText === null ? Promise.resolve(null) : optionalRead(inventoryPath)
+    ]);
+    try {
+      if (inventoryChanged) {
+        await mkdir(dirname(inventoryPath), { recursive: true });
+        const writeInventory = options.writeInventory ?? writeInventoryFile;
+        await writeInventory(inventoryPath, inventoryText);
+      }
+      if (bootstrappedV2) {
+        const writeConfig = options.writeConfig ?? atomicWrite;
+        await writeConfig(configPath, Buffer.from(merged.text));
+      } else if (plan.changed) {
+        const writeConfig = options.writeConfig ?? atomicWrite;
+        await writeConfig(configPath, Buffer.from(merged.text));
+      }
+      if (inventoryText !== null) await chmod(inventoryPath, 0o600);
+    } catch (error) {
+      await restoreFile(configPath, previousConfig);
+      if (inventoryText !== null) await restoreFile(inventoryPath, previousInventory);
+      throw error;
+    }
   }
 
   return {
     dryRun,
-    configPath,
+    bootstrappedV2,
+    configPath: relativeArtifactPath(root, configPath),
+    inventoryPath: generatedInventory === null ? null : relativeArtifactPath(root, inventoryPath),
+    inventoryChanged,
     changed: plan.changed,
     plan,
     scan: {
       scannedSkills: inventory.scannedSkills ?? inventory.skills.length,
       scannedInstallUnits: inventory.installUnits.length,
       addedSkills: merged.addedSkills,
-      addedInstallUnits: merged.addedInstallUnits,
-      updatedInstallUnits: merged.updatedInstallUnits,
-      addedWorkflows: merged.addedWorkflows,
-      addedHarnesses: merged.addedHarnesses,
-      skippedSkills: merged.skippedSkills,
-      reviewNotes: merged.reviewNotes,
-      warnings: inventory.warnings ?? []
+      addedInstallUnits: merged.addedInstallUnits ?? [],
+      updatedInstallUnits: merged.updatedInstallUnits ?? [],
+      addedWorkflows: merged.addedWorkflows ?? [],
+      addedHarnesses: merged.addedHarnesses ?? [],
+      skippedSkills: merged.skippedSkills ?? [],
+      reviewNotes: merged.reviewNotes ?? [],
+      warnings: [...(inventory.warnings ?? []), ...(generatedInventory?.redactions.warnings ?? [])],
+      redactedPaths: generatedInventory?.redactions.path_count ?? 0
     }
   };
 }
 
-function resolveUnderRoot(root, path) {
-  return isAbsolute(path) ? path : resolve(root, path);
+async function withRefreshLock(root, operation) {
+  const lockPath = join(root, ".skillboard-inventory-refresh.lock");
+  let handle;
+  try {
+    handle = await open(lockPath, "wx", 0o600);
+  } catch (error) {
+    if (error?.code === "EEXIST") {
+      throw new Error("Another inventory refresh is already using this project.");
+    }
+    throw error;
+  }
+  try {
+    await handle.writeFile(`${process.pid}\n`);
+    return await operation();
+  } finally {
+    await handle.close();
+    await rm(lockPath, { force: true });
+  }
+}
+
+function resolveUnderRoot(root, path, label) {
+  const target = isAbsolute(path) ? resolve(path) : resolve(root, path);
+  if (!isPathInside(root, target)) {
+    throw new Error(`${label} must remain inside the project root.`);
+  }
+  return target;
+}
+
+async function assertGeneratedInventoryTarget(root, target) {
+  if (!isPathInside(root, target)) {
+    throw new Error(`Generated inventory target is outside the project root: ${target}`);
+  }
+  const targetStats = await lstat(target).catch(missingOnly);
+  if (targetStats?.isSymbolicLink()) {
+    throw new Error(`Generated inventory target is a symlink and may resolve outside the project root: ${target}`);
+  }
+  const existingParent = await nearestExistingDirectory(dirname(target));
+  const [realRoot, realParent] = await Promise.all([realpath(root), realpath(existingParent)]);
+  if (!isPathInside(realRoot, realParent)) {
+    throw new Error(`Generated inventory target resolves outside the project root: ${target}`);
+  }
+}
+
+async function nearestExistingDirectory(start) {
+  let candidate = start;
+  while (true) {
+    const stats = await lstat(candidate).catch(missingOnly);
+    if (stats !== undefined) {
+      if (!stats.isDirectory() && !stats.isSymbolicLink()) {
+        throw new Error(`Generated inventory parent is not a directory: ${candidate}`);
+      }
+      return candidate;
+    }
+    const parent = dirname(candidate);
+    if (parent === candidate) {
+      throw new Error(`Generated inventory parent does not exist: ${start}`);
+    }
+    candidate = parent;
+  }
+}
+
+function missingOnly(error) {
+  if (error?.code === "ENOENT") {
+    return undefined;
+  }
+  throw error;
+}
+
+function isPathInside(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+async function writeInventoryFile(path, text) {
+  await atomicWrite(path, Buffer.from(text));
+}
+
+async function restoreFile(path, bytes) {
+  if (bytes === null) {
+    await rm(path, { force: true });
+    return;
+  }
+  await atomicWrite(path, bytes);
+}
+
+function relativeArtifactPath(root, path) {
+  return relative(root, path).replace(/\\/g, "/") || ".";
 }

package/src/lifecycle-cli.mjs

@@ -2,6 +2,7 @@ import { isAbsolute, relative, resolve } from "node:path";
 import { runAgentLayerUninstallCommand } from "./agent-integration-cli.mjs";
 import { initProject } from "./init.mjs";
 import { uninstallProject } from "./uninstall.mjs";
+import { uninstallUser } from "./user-uninstall.mjs";
 
 export { runSetupCommand } from "./agent-integration-cli.mjs";
 
@@ -40,6 +41,9 @@ export async function runInitCommand(options, stdout, runtime = defaultRuntime()
 }
 
 export async function runUninstallCommand(options, stdout, runtime = defaultRuntime()) {
+  if (options.get("user") === "true") {
+    return await runUserUninstallCommand(options, stdout, runtime);
+  }
   if (options.get("agent-layer") === "true") {
     return await runAgentLayerUninstallCommand(options, stdout, runtime);
   }
@@ -82,6 +86,36 @@ export async function runUninstallCommand(options, stdout, runtime = defaultRunt
   return 0;
 }
 
+async function runUserUninstallCommand(options, stdout, runtime) {
+  const allowed = new Set(["user", "dry-run", "yes", "json"]);
+  for (const option of options.keys()) {
+    if (!allowed.has(option)) {
+      throw new Error(`Unknown option for uninstall --user: --${option}`);
+    }
+  }
+  const dryRun = options.get("dry-run") === "true";
+  if (!dryRun && options.get("yes") !== "true") {
+    throw new Error("skillboard uninstall --user requires --yes; preview first with --dry-run");
+  }
+  const result = await uninstallUser({
+    dryRun,
+    env: runtime.env ?? process.env,
+    runtime
+  });
+  if (options.get("json") === "true") {
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+  }
+  stdout.write(`${dryRun ? "Dry run: " : ""}Uninstalled SkillBoard user state.\n`);
+  writeList(stdout, "Managed copies", result.managed_copies.map((copy) => copy.path));
+  writeList(stdout, "Guidance removed", result.guidance.removed);
+  writeList(stdout, "Guidance updated", result.guidance.updated);
+  writeList(stdout, "State", result.state_paths);
+  writeList(stdout, "Preserved", result.preserved);
+  if (dryRun) stdout.write("Run skillboard uninstall --user --yes to apply this plan.\n");
+  return 0;
+}
+
 function writeList(stdout, label, values) {
   if (values.length > 0) {
     stdout.write(`${label}: ${formatList(values)}\n`);
@@ -104,18 +138,12 @@ function writeCountedList(stdout, label, values) {
 
 function writeSafetyDefault(stdout, safety) {
   stdout.write("Skill selection default:\n");
-  stdout.write("- Installed user skills are usable unless runtime, user, or local instructions disable them.\n");
-  if (safety.automatic === 0) {
-    stdout.write("- No automatic model invocation was enabled.\n");
-  } else {
-    stdout.write(`- ${safety.automatic} automatic skills enabled by existing policy.\n`);
-  }
-  stdout.write("- Imported local skills are available on request in generated local policy.\n");
-  stdout.write("- Runtime/plugin/system skills require source review before automatic invocation.\n");
-  stdout.write(`- ${safety.automatic} automatic skills enabled\n`);
-  stdout.write(`- ${safety.manualOnly} manual-only skills available\n`);
-  stdout.write(`- ${safety.routerOnly} router-only skills available\n`);
-  stdout.write(`- ${safety.blocked} blocked/quarantined for safety\n`);
+  stdout.write("- Valid installed skills default to enabled and agent-local.\n");
+  stdout.write("- Users may disable a skill or explicitly share that skill across agents.\n");
+  stdout.write("- Optional preference ranks candidates and never changes availability.\n");
+  stdout.write("- Source and provenance are audit metadata, never availability.\n");
+  stdout.write(`- ${safety.enabled} enabled skills\n`);
+  stdout.write(`- ${safety.disabled} disabled skills\n`);
 }
 
 function writeNextCommands(stdout, next) {