agent-skillboard 0.1.0

package/src/control.mjs

@@ -0,0 +1,197 @@
+import { chmod, lstat, mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import {
+  installUnitSourceClass,
+  installUnitPriority
+} from "./domain/source-classes.mjs";
+import { canUseSkill } from "./control/can-use-guard.mjs";
+import {
+  auditSources,
+  classifySkillSource,
+  classifySkillTrust,
+  skillSummary
+} from "./control/source-trust.mjs";
+import {
+  activateSkill,
+  addSkill,
+  blockSkill,
+  preferSkill,
+  quarantineSkill,
+  removeSkill
+} from "./control/skill-crud.mjs";
+import { addHarness, addWorkflow } from "./control/workflow-crud.mjs";
+import {
+  GUARD_HOOK_MODE,
+  assertGuardHookPlanIsInstallable,
+  buildGuardHookInstallPlan,
+  planGuardHookInstall
+} from "./hook-plan.mjs";
+
+export { planGuardHookInstall } from "./hook-plan.mjs";
+
+export function listSkills(workspace, options = {}) {
+  const workflow = options.workflow === undefined ? undefined : workflowByName(workspace, options.workflow);
+  const skillIds = workflow === undefined
+    ? new Set(workspace.skills.map((skill) => skill.id))
+    : new Set([
+      ...workflow.activeSkills,
+      ...workflow.blockedSkills,
+      ...workflow.requiredCapabilities.flatMap((capability) => {
+        return [capability.preferred, ...capability.fallback].filter((skillId) => skillId.length > 0);
+      })
+    ]);
+
+  return workspace.skills
+    .filter((skill) => skillIds.has(skill.id))
+    .map((skill) => skillSummary(workspace, skill, workflow))
+    .sort((left, right) => {
+      return right.sourcePriority - left.sourcePriority || left.id.localeCompare(right.id);
+    });
+}
+
+export function listWorkflows(workspace) {
+  return workspace.workflows.map((workflow) => ({
+    name: workflow.name,
+    harness: workflow.harness,
+    activeSkills: workflow.activeSkills,
+    blockedSkills: workflow.blockedSkills,
+    requiredCapabilities: workflow.requiredCapabilities.map((capability) => capability.name)
+  })).sort((left, right) => left.name.localeCompare(right.name));
+}
+
+export function listHarnesses(workspace) {
+  return workspace.harnesses.map((harness) => ({
+    name: harness.name,
+    status: harness.status,
+    workflows: harness.workflows,
+    commands: harness.commands
+  })).sort((left, right) => left.name.localeCompare(right.name));
+}
+
+export function listInstallUnits(workspace) {
+  return workspace.installUnits.map((unit) => ({
+    id: unit.id,
+    kind: unit.kind,
+    sourceClass: installUnitSourceClass(unit),
+    priority: installUnitPriority(unit),
+    trustLevel: unit.trustLevel,
+    sourceDigest: unit.sourceDigest ?? null,
+    signature: unit.signature ?? null,
+    publicKey: unit.publicKey ?? null,
+    verifiedAt: unit.verifiedAt ?? null,
+    source: unit.source,
+    scope: unit.scope,
+    enabled: unit.enabled,
+    skills: unit.components.skills,
+    permissionRisk: unit.permissionRisk
+  })).sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function explainSkill(workspace, skillId) {
+  const skill = skillById(workspace, skillId);
+  const source = classifySkillSource(workspace, skill);
+  const workflows = workspace.workflows
+    .map((workflow) => workflowSkillRole(workspace, workflow, skillId))
+    .filter((entry) => entry.roles.length > 0);
+  const capabilities = workspace.capabilities
+    .filter((capability) => capability.canonical === skillId || capability.alternatives.includes(skillId))
+    .map((capability) => ({
+      name: capability.name,
+      role: capability.canonical === skillId ? "canonical" : "alternative",
+      defaultPolicy: capability.defaultPolicy
+    }));
+
+  return {
+    ...skillSummary(workspace, skill),
+    source,
+    trust: classifySkillTrust(workspace, skill),
+    workflows,
+    capabilities,
+    replacedBy: skill.replacedBy ?? null,
+    conflictsWith: skill.conflictsWith
+  };
+}
+
+export {
+  activateSkill,
+  addHarness,
+  addSkill,
+  addWorkflow,
+  auditSources,
+  blockSkill,
+  canUseSkill,
+  classifySkillSource,
+  classifySkillTrust,
+  preferSkill,
+  quarantineSkill,
+  removeSkill
+};
+
+export async function installGuardHook(options) {
+  const { plan, script } = await buildGuardHookInstallPlan(options);
+  assertGuardHookPlanIsInstallable(plan);
+
+  await mkdir(dirname(plan.path), { recursive: true });
+  await assertNewNonSymlinkPath(plan.path);
+  await writeFile(plan.path, script, { encoding: "utf8", flag: "wx", mode: GUARD_HOOK_MODE });
+  await assertRegularFile(plan.path);
+  await chmod(plan.path, GUARD_HOOK_MODE);
+  return { path: plan.path, workflow: plan.workflow, executable: true };
+}
+
+async function assertNewNonSymlinkPath(path) {
+  const existing = await lstat(path).catch((error) => {
+    if (error?.code === "ENOENT") {
+      return undefined;
+    }
+    throw error;
+  });
+  if (existing !== undefined) {
+    throw new Error(`Refusing to overwrite existing hook path: ${path}`);
+  }
+}
+
+async function assertRegularFile(path) {
+  const stats = await lstat(path);
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw new Error(`Hook path is not a regular file: ${path}`);
+  }
+}
+
+function workflowByName(workspace, name) {
+  const workflow = workspace.workflows.find((candidate) => candidate.name === name);
+  if (workflow === undefined) {
+    throw new Error(`Unknown workflow: ${name}`);
+  }
+  return workflow;
+}
+
+function skillById(workspace, skillId) {
+  const skill = workspace.skills.find((candidate) => candidate.id === skillId);
+  if (skill === undefined) {
+    throw new Error(`Unknown skill: ${skillId}`);
+  }
+  return skill;
+}
+
+function workflowSkillRole(workspace, workflow, skillId) {
+  const roles = [];
+  const capabilityRoles = [];
+  if (workflow.activeSkills.includes(skillId)) {
+    roles.push("active");
+  }
+  if (workflow.blockedSkills.includes(skillId)) {
+    roles.push("blocked");
+  }
+  for (const capability of workflow.requiredCapabilities) {
+    if (capability.preferred === skillId) {
+      roles.push("preferred");
+      capabilityRoles.push({ capability: capability.name, role: "preferred", policy: capability.policy });
+    }
+    if (capability.fallback.includes(skillId)) {
+      roles.push("fallback");
+      capabilityRoles.push({ capability: capability.name, role: "fallback", policy: capability.policy });
+    }
+  }
+  return { workflow: workflow.name, roles: [...new Set(roles)], capabilityRoles };
+}

package/src/doctor.mjs

@@ -0,0 +1,299 @@
+import { access, readFile } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { auditSources } from "./control.mjs";
+import { hasRuntimeComponents, installUnitSourceClass, isModelSelectableInvocation } from "./domain/source-classes.mjs";
+import { BRIDGE_END, BRIDGE_START } from "./lifecycle-content.mjs";
+import { checkPolicy } from "./policy.mjs";
+import { verifySources } from "./source-verification.mjs";
+import { uninstallProject } from "./uninstall.mjs";
+import { loadWorkspace } from "./workspace.mjs";
+
+export async function doctorProject(options = {}) {
+  const root = resolve(options.root ?? ".");
+  const configPath = resolveUnderRoot(root, options.configPath ?? "skillboard.config.yaml");
+  const skillsRoot = resolveUnderRoot(root, options.skillsRoot ?? "skills");
+  const bridges = await bridgeStatuses(root);
+  const uninstall = await uninstallProject({
+    root,
+    dryRun: true,
+    removeConfig: false,
+    removeEmptyDirs: true
+  });
+  const configExists = await exists(configPath);
+  const base = {
+    ok: false,
+    strictOk: false,
+    reviewRequired: false,
+    mode: "not-initialized",
+    root,
+    configPath,
+    skillsRoot,
+    initialized: false,
+    config: {
+      exists: configExists,
+      valid: false,
+      version: null,
+      error: configExists ? null : "skillboard.config.yaml was not found"
+    },
+    bridges,
+    workspace: emptyWorkspaceSummary(),
+    policy: { ok: false, errors: [], warnings: [] },
+    sources: { checked: false, verified: options.verifySources === true, ok: false, errors: [], warnings: [], blockingWarnings: [], units: [] },
+    uninstall,
+    recommendations: [],
+    reviewSummary: emptyReviewSummary()
+  };
+
+  if (!configExists) {
+    return finalizeDoctor(base, ["run skillboard init"]);
+  }
+
+  let workspace;
+  if (options.workspace !== undefined) {
+    workspace = options.workspace;
+  } else {
+    try {
+      workspace = await loadWorkspace({ configPath, skillsRoot });
+    } catch (error) {
+      return finalizeDoctor({
+        ...base,
+        config: {
+          exists: true,
+          valid: false,
+          version: null,
+          error: error instanceof Error ? error.message : String(error)
+        }
+      }, ["fix skillboard.config.yaml, then run skillboard check"]);
+    }
+  }
+
+  const policy = checkPolicy(workspace);
+  const sourceAudit = options.verifySources === true
+    ? await verifySources(workspace, { configPath, rootDir: root, restrictToRoot: true })
+    : auditSources(workspace);
+  const blockingWarnings = blockingSourceWarnings(sourceAudit.warnings);
+  const workspaceSummary = summarizeWorkspace(workspace);
+  const result = {
+    ...base,
+    initialized: true,
+    config: {
+      exists: true,
+      valid: true,
+      version: workspace.version,
+      error: null
+    },
+    workspace: workspaceSummary,
+    policy,
+    sources: {
+      checked: true,
+      verified: options.verifySources === true,
+      ok: sourceAudit.ok,
+      errors: sourceAudit.errors,
+      warnings: sourceAudit.warnings,
+      blockingWarnings,
+      units: sourceAudit.units
+    }
+  };
+
+  return finalizeDoctor(result, doctorRecommendations(result));
+}
+
+function finalizeDoctor(result, recommendations) {
+  const bridgeOk = result.bridges.every((bridge) => bridge.status === "installed" || bridge.status === "absent")
+    && result.bridges.some((bridge) => bridge.status === "installed");
+  const ok = result.config.valid && bridgeOk && result.policy.ok && result.sources.ok;
+  const reviewRequired = ok && reviewRequiredFor(result);
+  const strictOk = ok && !reviewRequired;
+  return {
+    ...result,
+    ok,
+    strictOk,
+    reviewRequired,
+    mode: ok ? reviewRequired ? "safe-mode" : "passed" : result.initialized ? "failed" : "not-initialized",
+    recommendations: [...new Set(recommendations)],
+    reviewSummary: reviewSummaryFor(result)
+  };
+}
+
+function doctorRecommendations(result) {
+  const recommendations = [];
+  if (!result.bridges.some((bridge) => bridge.status === "installed")) {
+    recommendations.push("run skillboard init to install agent bridge blocks");
+  }
+  if (result.bridges.some((bridge) => bridge.status === "unmanaged")) {
+    recommendations.push("run skillboard init to add SkillBoard bridge blocks to unmanaged agent files");
+  }
+  if (result.bridges.some((bridge) => bridge.status === "broken")) {
+    recommendations.push("repair AGENTS.md or CLAUDE.md SkillBoard bridge markers");
+  }
+  if (!result.policy.ok) {
+    recommendations.push("run skillboard check and fix policy errors");
+  }
+  if (!result.sources.ok) {
+    recommendations.push("run skillboard audit sources --verify and fix source verification errors");
+  } else if (result.sources.blockingWarnings.length > 0) {
+    recommendations.push("review high-risk runtime extension warnings before enabling automatic invocation");
+  } else if (result.sources.warnings.length > 0) {
+    recommendations.push("review source audit warnings before enabling automatic invocation");
+  }
+  if (result.workspace.skills.byStatus.quarantined > 0) {
+    recommendations.push("review quarantined skills with skillboard explain before activation");
+  }
+  if (result.workspace.installUnits.highRisk.length > 0) {
+    recommendations.push("review high-risk install units before trusting runtime extensions");
+  }
+  return recommendations;
+}
+
+function reviewRequiredFor(result) {
+  return result.sources.blockingWarnings.length > 0
+    || result.sources.warnings.length > 0
+    || result.workspace.skills.byStatus.quarantined > 0
+    || result.workspace.installUnits.highRisk.length > 0;
+}
+
+function reviewSummaryFor(result) {
+  const highRiskReviewUnits = result.sources.units
+    .filter((unit) => {
+      return unit.permissionRisk === "high" && !["trusted", "reviewed"].includes(unit.trustLevel);
+    })
+    .map((unit) => unit.id)
+    .sort((left, right) => left.localeCompare(right));
+  const runtimeReviewUnits = result.sources.units
+    .filter((unit) => unit.enabled && unit.trustLevel === "unreviewed" && result.workspace.installUnits.runtimeExtensions.includes(unit.id))
+    .map((unit) => unit.id)
+    .sort((left, right) => left.localeCompare(right));
+  return {
+    reviewRequired: reviewRequiredFor(result),
+    blockingWarnings: result.sources.blockingWarnings.length,
+    warnings: result.sources.warnings.length,
+    quarantinedSkills: result.workspace.skills.byStatus.quarantined,
+    modelSelectableSkills: result.workspace.skills.modelSelectable,
+    highRiskInstallUnits: highRiskReviewUnits,
+    runtimeExtensionInstallUnits: runtimeReviewUnits
+  };
+}
+
+function blockingSourceWarnings(warnings) {
+  return warnings.filter((warning) => {
+    return warning.includes("high-risk source is not reviewed or trusted")
+      || warning.includes("runtime extension source is unreviewed");
+  });
+}
+
+function summarizeWorkspace(workspace) {
+  const skillsByStatus = countBy(workspace.skills, (skill) => skill.status);
+  const skillsByInvocation = countBy(workspace.skills, (skill) => skill.invocation);
+  const installUnitsByClass = countBy(workspace.installUnits, (unit) => installUnitSourceClass(unit));
+  const highRisk = workspace.installUnits
+    .filter((unit) => unit.permissionRisk === "high")
+    .map((unit) => unit.id)
+    .sort((left, right) => left.localeCompare(right));
+  const runtimeExtensions = workspace.installUnits
+    .filter((unit) => hasRuntimeComponents(unit))
+    .map((unit) => unit.id)
+    .sort((left, right) => left.localeCompare(right));
+  const modelSelectable = workspace.skills
+    .filter((skill) => isModelSelectableInvocation(skill.invocation))
+    .map((skill) => skill.id)
+    .sort((left, right) => left.localeCompare(right));
+
+  return {
+    skills: {
+      declared: workspace.skills.length,
+      installed: workspace.installedSkills.length,
+      modelSelectable: modelSelectable.length,
+      byStatus: withKnownKeys(skillsByStatus, ["active", "candidate", "vendor", "quarantined", "blocked", "deprecated"]),
+      byInvocation: withKnownKeys(skillsByInvocation, ["manual-only", "router-only", "workflow-auto", "global-auto", "blocked", "deprecated"])
+    },
+    workflows: workspace.workflows.length,
+    harnesses: workspace.harnesses.length,
+    installUnits: {
+      total: workspace.installUnits.length,
+      bySourceClass: withKnownKeys(installUnitsByClass, ["user", "skill-pack", "workflow-bundle", "harness-bundle", "runtime-extension", "package-manager", "external-package", "unknown"]),
+      highRisk,
+      runtimeExtensions
+    }
+  };
+}
+
+function emptyWorkspaceSummary() {
+  return {
+    skills: {
+      declared: 0,
+      installed: 0,
+      modelSelectable: 0,
+      byStatus: withKnownKeys({}, ["active", "candidate", "vendor", "quarantined", "blocked", "deprecated"]),
+      byInvocation: withKnownKeys({}, ["manual-only", "router-only", "workflow-auto", "global-auto", "blocked", "deprecated"])
+    },
+    workflows: 0,
+    harnesses: 0,
+    installUnits: {
+      total: 0,
+      bySourceClass: withKnownKeys({}, ["user", "skill-pack", "workflow-bundle", "harness-bundle", "runtime-extension", "package-manager", "external-package", "unknown"]),
+      highRisk: [],
+      runtimeExtensions: []
+    }
+  };
+}
+
+function emptyReviewSummary() {
+  return {
+    reviewRequired: false,
+    blockingWarnings: 0,
+    warnings: 0,
+    quarantinedSkills: 0,
+    modelSelectableSkills: 0,
+    highRiskInstallUnits: [],
+    runtimeExtensionInstallUnits: []
+  };
+}
+
+async function bridgeStatuses(root) {
+  return await Promise.all(["AGENTS.md", "CLAUDE.md"].map(async (filename) => {
+    const path = join(root, filename);
+    if (!(await exists(path))) {
+      return { file: filename, status: "absent" };
+    }
+    const text = await readFile(path, "utf8");
+    const hasStart = text.includes(BRIDGE_START);
+    const hasEnd = text.includes(BRIDGE_END);
+    if (hasStart && hasEnd) {
+      return { file: filename, status: "installed" };
+    }
+    if (hasStart || hasEnd) {
+      return { file: filename, status: "broken" };
+    }
+    return { file: filename, status: "unmanaged" };
+  }));
+}
+
+function countBy(values, keyFor) {
+  const counts = {};
+  for (const value of values) {
+    const key = keyFor(value);
+    counts[key] = (counts[key] ?? 0) + 1;
+  }
+  return counts;
+}
+
+function withKnownKeys(counts, keys) {
+  const next = {};
+  for (const key of keys) {
+    next[key] = counts[key] ?? 0;
+  }
+  for (const [key, value] of Object.entries(counts)) {
+    if (next[key] === undefined) {
+      next[key] = value;
+    }
+  }
+  return next;
+}
+
+function resolveUnderRoot(root, path) {
+  return isAbsolute(path) ? path : resolve(root, path);
+}
+
+async function exists(path) {
+  return access(path).then(() => true, () => false);
+}

package/src/domain/constants.mjs

@@ -0,0 +1,47 @@
+export const STATUS_VALUES = new Set([
+  "discovered",
+  "quarantined",
+  "vendor",
+  "candidate",
+  "active",
+  "active-manual",
+  "active-router",
+  "active-auto",
+  "canonical",
+  "blocked",
+  "deprecated",
+  "archived",
+  "removed"
+]);
+
+export const INVOCATION_VALUES = new Set([
+  "manual-only",
+  "router-only",
+  "workflow-auto",
+  "global-auto",
+  "blocked",
+  "deprecated"
+]);
+
+export const HARNESS_STATUS_VALUES = new Set(["available", "configured", "primary", "fallback", "disabled", "removed"]);
+export const EXPOSURE_VALUES = new Set(["exported", "global-meta", "unit-managed", "private"]);
+
+export const INSTALL_UNIT_KIND_VALUES = new Set([
+  "skill",
+  "workflow",
+  "plugin",
+  "marketplace",
+  "package-manager-dependency",
+  "harness",
+  "mcp-server",
+  "hook",
+  "agent",
+  "lsp",
+  "custom"
+]);
+
+export const PERMISSION_RISK_VALUES = new Set(["low", "medium", "high", "unknown"]);
+export const TRUST_LEVEL_VALUES = new Set(["trusted", "reviewed", "unreviewed", "blocked"]);
+
+export const NON_CALLABLE_WORKFLOW_STATUSES = new Set(["blocked", "quarantined", "deprecated", "archived", "removed"]);
+export const NON_CALLABLE_WORKFLOW_INVOCATIONS = new Set(["blocked", "deprecated"]);

package/src/domain/indexes.mjs

@@ -0,0 +1,29 @@
+export function buildPolicyContext(workspace) {
+  const skillsById = new Map(workspace.skills.map((skill) => [skill.id, skill]));
+  const workflowsByName = new Map(workspace.workflows.map((workflow) => [workflow.name, workflow]));
+  const harnessesByName = new Map(workspace.harnesses.map((harness) => [harness.name, harness]));
+  const installUnitsById = new Map(workspace.installUnits.map((unit) => [unit.id, unit]));
+  const capabilitiesByName = new Map(workspace.capabilities.map((capability) => [capability.name, capability]));
+  const workflowScopedSkillIds = new Set(workspace.workflows.flatMap((workflow) => {
+    const capabilitySkills = workflow.requiredCapabilities.flatMap((capability) => {
+      return capability.preferred === "" ? capability.fallback : [capability.preferred, ...capability.fallback];
+    });
+    return [...workflow.activeSkills, ...capabilitySkills];
+  }));
+
+  return {
+    workspace,
+    defaults: workspace.defaults,
+    skills: workspace.skills,
+    workflows: workspace.workflows,
+    harnesses: workspace.harnesses,
+    installUnits: workspace.installUnits,
+    capabilities: workspace.capabilities,
+    skillsById,
+    workflowsByName,
+    harnessesByName,
+    installUnitsById,
+    capabilitiesByName,
+    workflowScopedSkillIds
+  };
+}

package/src/domain/rules/capabilities.mjs

@@ -0,0 +1,33 @@
+import { INVOCATION_VALUES } from "../constants.mjs";
+
+export const capabilityRules = [
+  {
+    id: "CAP-REF-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const capability of ctx.capabilities) {
+        if (capability.canonical !== "" && !ctx.skillsById.has(capability.canonical)) {
+          diagnostics.push(`Capability requirement ${capability.name} references undeclared canonical skill: ${capability.canonical}`);
+        }
+        for (const skillId of capability.alternatives) {
+          if (!ctx.skillsById.has(skillId)) {
+            diagnostics.push(`Capability requirement ${capability.name} references undeclared alternative skill: ${skillId}`);
+          }
+        }
+      }
+      return diagnostics;
+    }
+  },
+  {
+    id: "CAP-POLICY-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const capability of ctx.capabilities) {
+        if (!INVOCATION_VALUES.has(capability.defaultPolicy)) {
+          diagnostics.push(`Capability ${capability.name} has unsupported default_policy: ${capability.defaultPolicy}`);
+        }
+      }
+      return diagnostics;
+    }
+  }
+];

package/src/domain/rules/harnesses.mjs

@@ -0,0 +1,16 @@
+export const harnessRules = [
+  {
+    id: "HARNESS-REF-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const harness of ctx.harnesses) {
+        for (const workflow of harness.workflows) {
+          if (!ctx.workflowsByName.has(workflow)) {
+            diagnostics.push(`Harness ${harness.name} references undeclared workflow: ${workflow}`);
+          }
+        }
+      }
+      return diagnostics;
+    }
+  }
+];