agent-skillboard 0.1.0

package/src/advisor/schema.mjs

@@ -0,0 +1,112 @@
+import { isAbsolute, resolve } from "node:path";
+import { uninstallProject } from "../uninstall.mjs";
+import { sortedStrings } from "./sort.mjs";
+
+const SCHEMA_VERSION = 1;
+const EMPTY_SKILL_GROUPS = Object.freeze({
+  automatic_allowed: Object.freeze([]),
+  manual_allowed: Object.freeze([]),
+  needs_review: Object.freeze([]),
+  blocked: Object.freeze([]),
+  not_in_workflow: Object.freeze([]),
+  installed_only: Object.freeze([])
+});
+
+export function buildBrief(data) {
+  const brief = {
+    ok: data.ok,
+    schema_version: SCHEMA_VERSION
+  };
+  if (data.error !== undefined) {
+    brief.error = data.error;
+  }
+  brief.health = data.health;
+  brief.workflow = data.workflow;
+  brief.skills = data.skills;
+  brief.sources = data.sources;
+  brief.review_queue = data.reviewQueue;
+  brief.cleanup = data.cleanup;
+  if (data.actions !== undefined) {
+    brief.actions = data.actions;
+  }
+  return brief;
+}
+
+export function resolveProjectPaths(options) {
+  const root = resolve(options.root ?? ".");
+  return {
+    root,
+    configPath: resolveUnderRoot(root, options.configPath ?? "skillboard.config.yaml"),
+    skillsRoot: resolveUnderRoot(root, options.skillsRoot ?? "skills")
+  };
+}
+
+export async function buildCleanup(root) {
+  const conservative = await uninstallProject({
+    root,
+    dryRun: true,
+    removeConfig: false,
+    removeEmptyDirs: true
+  });
+  const fullReset = await uninstallProject({
+    root,
+    dryRun: true,
+    resetConfig: true,
+    removeReports: true,
+    removeHooks: true,
+    removeEmptyDirs: true
+  });
+  return {
+    conservative,
+    full_reset: fullReset
+  };
+}
+
+export function healthFromDoctor(doctor, paths) {
+  return {
+    mode: doctor.mode,
+    review_required: doctor.reviewRequired,
+    strict_ok: doctor.strictOk,
+    initialized: doctor.initialized,
+    root: paths.root,
+    config_path: paths.configPath,
+    skills_root: paths.skillsRoot,
+    config: {
+      exists: doctor.config.exists,
+      valid: doctor.config.valid,
+      version: doctor.config.version,
+      error: doctor.config.error
+    },
+    policy: {
+      ok: doctor.policy.ok,
+      errors: sortedStrings(doctor.policy.errors),
+      warnings: sortedStrings(doctor.policy.warnings)
+    }
+  };
+}
+
+export function emptyWorkflowState() {
+  return {
+    selected: null,
+    defaulted: false,
+    needs_selection: false,
+    candidates: [],
+    unknown: false,
+    blocked_reason: null
+  };
+}
+
+export function emptySkillGroups() {
+  return {
+    automatic_allowed: [...EMPTY_SKILL_GROUPS.automatic_allowed],
+    manual_allowed: [...EMPTY_SKILL_GROUPS.manual_allowed],
+    needs_review: [...EMPTY_SKILL_GROUPS.needs_review],
+    blocked: [...EMPTY_SKILL_GROUPS.blocked],
+    not_in_workflow: [...EMPTY_SKILL_GROUPS.not_in_workflow],
+    installed_only: [...EMPTY_SKILL_GROUPS.installed_only]
+  };
+}
+
+function resolveUnderRoot(root, path) {
+  return isAbsolute(path) ? path : resolve(root, path);
+}

package/src/advisor/setup-actions.mjs

@@ -0,0 +1,42 @@
+import { command, makeAction } from "./action-core.mjs";
+
+export function buildSetupGuidanceActions({ paths, workflow, skills, reviewQueue, workspace }) {
+  if (!isInitializedEmptyWorkspace(workflow, skills, reviewQueue, workspace)) {
+    return [];
+  }
+  return [makeAction({
+    kind: "setup-guidance",
+    targetId: paths.root,
+    label: "Start setup by refreshing inventory",
+    reason: "This initialized project has no usable skills or workflows yet. Discover installed agent assets, then add a harness and workflow when ready.",
+    risk: "low",
+    dryRun: command([
+      "skillboard", "inventory", "refresh",
+      "--dir", paths.root,
+      "--config", paths.configPath,
+      "--dry-run",
+      "--json"
+    ]),
+    apply: null,
+    appliesTo: { kind: "project", id: paths.root },
+    blockedReason: null,
+    advanced: { root: paths.root, config_path: paths.configPath }
+  })];
+}
+
+function isInitializedEmptyWorkspace(workflow, skills, reviewQueue, workspace) {
+  return workflow.selected === null
+    && workflow.needs_selection === false
+    && workflow.unknown === false
+    && arrayEmpty(workflow.candidates)
+    && Object.values(skills).every(arrayEmpty)
+    && arrayEmpty(reviewQueue)
+    && arrayEmpty(workspace.skills)
+    && arrayEmpty(workspace.workflows)
+    && arrayEmpty(workspace.harnesses)
+    && arrayEmpty(workspace.installUnits);
+}
+
+function arrayEmpty(value) {
+  return Array.isArray(value) && value.length === 0;
+}

package/src/advisor/skills.mjs

@@ -0,0 +1,191 @@
+import {
+  canUseSkill,
+  explainSkill,
+  listSkills
+} from "../control.mjs";
+import { emptySkillGroups } from "./schema.mjs";
+import { sortById } from "./sort.mjs";
+
+export function skillsWithoutWorkflow(workspace) {
+  const groups = emptySkillGroups();
+  groups.installed_only = installedOnlyEntries(workspace);
+  return sortSkillGroups(groups);
+}
+
+export function skillsForWorkflow(workspace, workflowName, sourceAudit = { units: [] }) {
+  if (workflowName === null) {
+    const groups = emptySkillGroups();
+    groups.installed_only = installedOnlyEntries(workspace);
+    return sortSkillGroups(groups);
+  }
+
+  const groups = emptySkillGroups();
+  const sourceFindings = findingsBySource(sourceAudit);
+  for (const summary of listSkills(workspace)) {
+    const skill = workspace.skills.find((candidate) => candidate.id === summary.id);
+    const explanation = explainSkill(workspace, summary.id);
+    const use = canUseSkill(workspace, summary.id, workflowName);
+    const group = groupForDeclaredSkill(workspace, skill, use, sourceFindings);
+    const entry = declaredSkillEntry(summary, explanation, use, group);
+    if (use.allowed) {
+      if (use.automaticAllowed) {
+        groups.automatic_allowed.push(entry);
+      } else {
+        groups.manual_allowed.push(entry);
+      }
+    } else {
+      groups[group].push(entry);
+    }
+  }
+  groups.installed_only = installedOnlyEntries(workspace);
+  return sortSkillGroups(groups);
+}
+
+function declaredSkillEntry(summary, explanation, use, group) {
+  return {
+    id: summary.id,
+    label: summary.id,
+    path: summary.path,
+    reason: reasonForGroup(group, use?.reasons ?? []),
+    advanced: {
+      status: summary.status,
+      invocation: summary.invocation,
+      exposure: summary.exposure,
+      category: summary.category,
+      source_class: explanation.source.class,
+      owner_install_unit: explanation.source.ownerInstallUnit,
+      workflow_roles: use?.roles ?? summary.workflowRoles,
+      capability_roles: use?.capabilityRoles ?? [],
+      trust: explanation.trust
+    }
+  };
+}
+
+function groupForDeclaredSkill(workspace, skill, use, sourceFindings) {
+  if (use.allowed) {
+    return use.automaticAllowed ? "automatic_allowed" : "manual_allowed";
+  }
+  const findings = sourceFindings.get(skill?.ownerInstallUnit) ?? [];
+  const hardBlocked = hasHardSafetyBlock(workspace, skill, use.reasons, findings);
+  if (isNotInWorkflow(use.reasons)) {
+    return hardBlocked ? "blocked" : "not_in_workflow";
+  }
+  if (!hardBlocked && isReviewableTrustGap(workspace, skill, use.reasons)) {
+    return "needs_review";
+  }
+  return "blocked";
+}
+
+function installedOnlyEntries(workspace) {
+  const declaredPaths = new Set(workspace.skills.map((skill) => skill.path));
+  return workspace.installedSkills
+    .filter((skill) => !declaredPaths.has(skill.path))
+    .map((skill) => ({
+      id: skill.id,
+      label: skill.name ?? skill.id,
+      path: skill.path,
+      reason: "Discovered on disk but not declared in skillboard.config.yaml.",
+      advanced: {
+        name: skill.name ?? null,
+        description: skill.description ?? null
+      }
+    }))
+    .sort(sortById);
+}
+
+function reasonForGroup(group, reasons) {
+  if (group === "not_in_workflow") {
+    return reasons.find(isNotInWorkflowReason) ?? reasons[0] ?? null;
+  }
+  if (group === "needs_review") {
+    return reasons.find(isReviewReason) ?? reasons[0] ?? null;
+  }
+  if (group === "blocked") {
+    return reasons.find(isHardReason) ?? reasons[0] ?? null;
+  }
+  return reasons[0] ?? null;
+}
+
+function isNotInWorkflow(reasons) {
+  return reasons.some(isNotInWorkflowReason);
+}
+
+function isReviewableTrustGap(workspace, skill, reasons) {
+  return hasKnownProvenance(workspace, skill) && reasons.some(isReviewReason);
+}
+
+function hasHardSafetyBlock(workspace, skill, reasons, findings) {
+  if (hasMissingProvenance(workspace, skill)) {
+    return true;
+  }
+  if (isNonCallableSkill(skill)) {
+    return true;
+  }
+  return reasons.some(isHardReason) || findings.some(isHardFinding);
+}
+
+function hasMissingProvenance(workspace, skill) {
+  if (skill === undefined) {
+    return true;
+  }
+  if (skill.exposure === "unit-managed" && skill.ownerInstallUnit === undefined) {
+    return true;
+  }
+  return skill.ownerInstallUnit !== undefined
+    && !workspace.installUnits.some((unit) => unit.id === skill.ownerInstallUnit);
+}
+
+function hasKnownProvenance(workspace, skill) {
+  return skill?.ownerInstallUnit !== undefined
+    && workspace.installUnits.some((unit) => unit.id === skill.ownerInstallUnit);
+}
+
+function isNonCallableSkill(skill) {
+  return ["blocked", "quarantined", "deprecated", "archived", "removed"].includes(skill?.status)
+    || ["blocked", "deprecated"].includes(skill?.invocation);
+}
+
+function findingsBySource(sourceAudit) {
+  return new Map((sourceAudit.units ?? []).map((unit) => [unit.id, unit.findings ?? []]));
+}
+
+function isNotInWorkflowReason(reason) {
+  return reason.includes("is not active, preferred, or fallback in workflow");
+}
+
+function isReviewReason(reason) {
+  const normalized = reason.toLowerCase();
+  return normalized.includes("unreviewed")
+    || normalized.includes("not reviewed")
+    || normalized.includes("not trusted");
+}
+
+function isHardReason(reason) {
+  const normalized = reason.toLowerCase();
+  return normalized.includes("policy check failed")
+    || normalized.includes("unknown skill")
+    || normalized.includes("unknown workflow")
+    || normalized.includes("blocks skill")
+    || normalized.includes("source trust policy")
+    || (normalized.includes("install unit") && normalized.includes("disabled"))
+    || normalized.includes("non-callable")
+    || normalized.includes("global-auto but not global-meta");
+}
+
+function isHardFinding(finding) {
+  if (isReviewReason(finding.message)) {
+    return false;
+  }
+  return finding.severity === "error";
+}
+
+function sortSkillGroups(groups) {
+  return {
+    automatic_allowed: groups.automatic_allowed.sort(sortById),
+    manual_allowed: groups.manual_allowed.sort(sortById),
+    needs_review: groups.needs_review.sort(sortById),
+    blocked: groups.blocked.sort(sortById),
+    not_in_workflow: groups.not_in_workflow.sort(sortById),
+    installed_only: groups.installed_only.sort(sortById)
+  };
+}

package/src/advisor/sort.mjs

@@ -0,0 +1,15 @@
+export function sortById(left, right) {
+  return left.id.localeCompare(right.id);
+}
+
+export function sortedStrings(values) {
+  return [...values].sort((left, right) => left.localeCompare(right));
+}
+
+export function slug(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80) || "finding";
+}

package/src/advisor/sources.mjs

@@ -0,0 +1,160 @@
+import { recommendTrustLevel } from "./trust-policy.mjs";
+import { sortById, sortedStrings, slug } from "./sort.mjs";
+
+export function emptySources() {
+  return {
+    ok: false,
+    errors: [],
+    warnings: [],
+    units: []
+  };
+}
+
+export function sourcesFromDoctor(doctor) {
+  return {
+    ok: doctor.sources.ok,
+    errors: sortedStrings(doctor.sources.errors),
+    warnings: sortedStrings(doctor.sources.warnings),
+    units: []
+  };
+}
+
+export function summarizeSources(sourceAudit) {
+  return {
+    ok: sourceAudit.ok,
+    errors: sortedStrings(sourceAudit.errors),
+    warnings: sortedStrings(sourceAudit.warnings),
+    units: sourceAudit.units.map((unit) => ({
+      id: unit.id,
+      kind: unit.kind,
+      enabled: unit.enabled,
+      risk: unit.permissionRisk,
+      reviewed: ["trusted", "reviewed"].includes(unit.trustLevel),
+      findings: unit.findings
+        .map((finding) => ({
+          severity: finding.severity,
+          message: finding.message
+        }))
+        .sort(sortFinding),
+      advanced: {
+        source_class: unit.sourceClass,
+        trust_level: unit.trustLevel,
+        signed: unit.signed,
+        pinned: unit.pinned,
+        verified_at: unit.verifiedAt,
+        automatic_skills: sortedStrings(unit.automaticSkills)
+      }
+    })).sort(sortById)
+  };
+}
+
+export function buildReviewQueue(workspace, sourceAudit) {
+  const entries = [];
+  const installUnitsById = new Map(workspace.installUnits.map((unit) => [unit.id, unit]));
+  for (const unit of sourceAudit.units) {
+    if (unit.enabled && unit.sourceClass !== "user" && unit.trustLevel === "unreviewed") {
+      const recommended = recommendTrustLevel(installUnitsById.get(unit.id) ?? unit);
+      entries.push({
+        kind: "install_unit",
+        id: `install_unit:${unit.id}`,
+        label: `Review ${unit.id}`,
+        reason: `Source is enabled but not reviewed. Recommended trust level: ${recommended}.`,
+        risk: normalizeRisk(unit.permissionRisk),
+        action_ids: [],
+        advanced: {
+          install_unit: unit.id,
+          source_class: unit.sourceClass,
+          trust_level: unit.trustLevel,
+          recommended_trust_level: recommended
+        }
+      });
+    }
+    for (const finding of unit.findings) {
+      entries.push({
+        kind: "source_finding",
+        id: sourceFindingId(unit.id, finding),
+        label: `Review ${unit.id}`,
+        reason: finding.message,
+        risk: riskForFinding(finding),
+        action_ids: [],
+        advanced: {
+          source_id: unit.id,
+          severity: finding.severity
+        }
+      });
+    }
+  }
+  for (const skill of workspace.skills) {
+    if (skill.status === "quarantined") {
+      entries.push({
+        kind: "skill",
+        id: `skill:${skill.id}`,
+        label: `Review ${skill.id}`,
+        reason: "Skill is quarantined.",
+        risk: "high",
+        action_ids: [],
+        advanced: {
+          skill_id: skill.id,
+          status: skill.status,
+          owner_install_unit: skill.ownerInstallUnit ?? null
+        }
+      });
+    }
+  }
+  return entries.sort(sortReviewQueue);
+}
+
+function sourceFindingId(sourceId, finding) {
+  return `source_finding:${sourceId}:${finding.severity}:${slug(finding.message)}`;
+}
+
+function riskForFinding(finding) {
+  if (finding.severity === "error") {
+    return "high";
+  }
+  const message = finding.message.toLowerCase();
+  if (message.includes("runtime") || message.includes("high-risk")) {
+    return "high";
+  }
+  if (message.includes("not pinned") || message.includes("provenance")) {
+    return "medium";
+  }
+  return "low";
+}
+
+function normalizeRisk(value) {
+  if (["low", "medium", "high"].includes(value)) {
+    return value;
+  }
+  return "medium";
+}
+
+function sortReviewQueue(left, right) {
+  return reviewQueueBucket(left) - reviewQueueBucket(right)
+    || left.id.localeCompare(right.id);
+}
+
+function reviewQueueBucket(entry) {
+  if (entry.kind === "source_finding" && entry.risk === "high") {
+    return 0;
+  }
+  if (entry.kind === "install_unit") {
+    return 1;
+  }
+  if (entry.kind === "skill") {
+    return 2;
+  }
+  if (entry.kind === "source_finding" && isUnpinnedFinding(entry)) {
+    return 3;
+  }
+  return 4;
+}
+
+function isUnpinnedFinding(entry) {
+  const reason = entry.reason.toLowerCase();
+  return reason.includes("not pinned") || reason.includes("provenance");
+}
+
+function sortFinding(left, right) {
+  return left.severity.localeCompare(right.severity) || left.message.localeCompare(right.message);
+}

package/src/advisor/trust-policy.mjs

@@ -0,0 +1,65 @@
+import { hasRuntimeComponents, installUnitSourceClass } from "../domain/source-classes.mjs";
+
+/**
+ * Recommend the next trust_level for an install unit based on its
+ * source class, permission risk, and runtime surface.
+ *
+ * The recommendation is a suggestion used by advisor action cards.
+ * The final authorization is still performed by `skillboard review` validation.
+ */
+export function recommendTrustLevel(unit) {
+  const sourceClass = installUnitSourceClass(unit);
+  const risk = unit.permissionRisk ?? "unknown";
+  const runtime = hasRuntimeComponents(unit);
+
+  if (unit.trustLevel === "trusted" || unit.trustLevel === "blocked") {
+    return unit.trustLevel;
+  }
+
+  // User-controlled local sources are trusted by default because the user owns the files.
+  if (sourceClass === "user" && risk === "low") {
+    return "trusted";
+  }
+
+  // High-risk sources should not be activated from advisor suggestions without explicit blocking/review.
+  if (risk === "high") {
+    return "blocked";
+  }
+
+  // Unknown risk always requires at least a review before any automatic use.
+  if (risk === "unknown") {
+    return "reviewed";
+  }
+
+  // Medium-risk or runtime-related sources should be reviewed, not blindly trusted.
+  if (risk === "medium" || runtime) {
+    return "reviewed";
+  }
+
+  return "trusted";
+}
+
+/**
+ * Map a trust recommendation to an advisor action kind and label.
+ */
+export function trustRecommendationAction(recommended) {
+  if (recommended === "trusted") {
+    return {
+      kind: "trust-install-unit",
+      label: "Trust source",
+      reason: "Low-risk source can be trusted after explicit user confirmation."
+    };
+  }
+  if (recommended === "blocked") {
+    return {
+      kind: "block-install-unit",
+      label: "Decide whether to block source",
+      reason: "High-risk or runtime-extending source needs a one-time decision before its skills appear again."
+    };
+  }
+  return {
+    kind: "review-install-unit",
+    label: "Review source",
+    reason: "Review the source before enabling its model-selectable skills."
+  };
+}

package/src/advisor/workflow.mjs

@@ -0,0 +1,41 @@
+export function resolveWorkflow(workflows, requestedWorkflow) {
+  const candidates = workflows.map((workflow) => workflow.name).sort((left, right) => left.localeCompare(right));
+  if (requestedWorkflow !== undefined) {
+    return {
+      selected: requestedWorkflow,
+      defaulted: false,
+      needs_selection: false,
+      candidates,
+      unknown: !candidates.includes(requestedWorkflow),
+      blocked_reason: candidates.includes(requestedWorkflow) ? null : `Unknown workflow: ${requestedWorkflow}`
+    };
+  }
+  if (candidates.length === 1) {
+    return {
+      selected: candidates[0],
+      defaulted: true,
+      needs_selection: false,
+      candidates,
+      unknown: false,
+      blocked_reason: null
+    };
+  }
+  if (candidates.length > 1) {
+    return {
+      selected: null,
+      defaulted: false,
+      needs_selection: true,
+      candidates,
+      unknown: false,
+      blocked_reason: "Multiple workflows exist; pass a workflow to classify skill availability."
+    };
+  }
+  return {
+    selected: null,
+    defaulted: false,
+    needs_selection: false,
+    candidates,
+    unknown: false,
+    blocked_reason: "No workflows are configured."
+  };
+}