agent-skillboard 0.1.2 → 0.2.1

package/src/config-helpers.mjs

@@ -1,24 +1,40 @@
-export function requireRecord(value, label) {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`${label} must be a mapping`);
-  }
-  return value;
-}
-
-export function readString(record, key, fallback) {
-  const value = record[key];
-  if (value === undefined) {
-    return fallback;
+export function requireRecord(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be a mapping`);
+  }
+  return value;
+}
+
+export function readOptionalRecord(record, key, label = key) {
+  const value = record[key];
+  if (value === undefined) {
+    return undefined;
+  }
+  return requireRecord(value, label);
+}
+
+export function readString(record, key, fallback) {
+  const value = record[key];
+  if (value === undefined) {
+    return fallback;
   }
   if (typeof value !== "string") {
     throw new Error(`${key} must be a string`);
-  }
-  return value;
-}
-
-export function readOptionalString(record, key) {
-  const value = record[key];
-  if (value === undefined) {
+  }
+  return value;
+}
+
+export function readRequiredString(record, key, label = key) {
+  const value = record[key];
+  if (typeof value !== "string") {
+    throw new Error(`${label} must be a string`);
+  }
+  return value;
+}
+
+export function readOptionalString(record, key) {
+  const value = record[key];
+  if (value === undefined) {
     return undefined;
   }
   if (typeof value !== "string") {

package/src/conflicts.mjs

@@ -0,0 +1,70 @@
+export function workflowConflictEntries(workspace, workflow) {
+  const selectable = workflowSelectableSkillIds(workflow);
+  const blocked = new Set(workflow.blockedSkills);
+  const active = new Set(selectable.filter((skillId) => !blocked.has(skillId)));
+  const entries = [];
+  const seen = new Set();
+
+  for (const skillId of active) {
+    const skill = workspace.skills.find((candidate) => candidate.id === skillId);
+    for (const conflictingSkill of skill?.conflictsWith ?? []) {
+      if (!active.has(conflictingSkill)) {
+        continue;
+      }
+      const key = [skillId, conflictingSkill].sort().join("\0");
+      if (seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      entries.push({
+        workflow: workflow.name,
+        skill: skillId,
+        conflictingSkill
+      });
+    }
+  }
+
+  return entries.sort((left, right) =>
+    left.workflow.localeCompare(right.workflow)
+      || left.skill.localeCompare(right.skill)
+      || left.conflictingSkill.localeCompare(right.conflictingSkill)
+  );
+}
+
+export function workflowConflictEntriesForSkill(workspace, workflow, skillId) {
+  return workflowConflictEntries(workspace, workflow).filter((entry) =>
+    entry.skill === skillId || entry.conflictingSkill === skillId
+  );
+}
+
+export function conflictingSkillIds(workspace, skillId) {
+  const direct = workspace.skills.find((skill) => skill.id === skillId)?.conflictsWith ?? [];
+  const reverse = workspace.skills
+    .filter((skill) => skill.conflictsWith.includes(skillId))
+    .map((skill) => skill.id);
+  return uniqueStrings([...direct, ...reverse]).sort((left, right) => left.localeCompare(right));
+}
+
+export function activeConflictEntriesForSkill(workspace, skillId) {
+  return workspace.workflows
+    .flatMap((workflow) => workflowConflictEntriesForSkill(workspace, workflow, skillId))
+    .sort((left, right) =>
+      left.workflow.localeCompare(right.workflow)
+        || left.skill.localeCompare(right.skill)
+        || left.conflictingSkill.localeCompare(right.conflictingSkill)
+    );
+}
+
+function workflowSelectableSkillIds(workflow) {
+  return uniqueStrings([
+    ...workflow.activeSkills,
+    ...workflow.requiredCapabilities.flatMap((capability) => [
+      capability.preferred,
+      ...capability.fallback
+    ])
+  ]);
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === "string" && value.length > 0))];
+}

package/src/control/can-use-guard.mjs

@@ -3,6 +3,7 @@ import {
   NON_CALLABLE_WORKFLOW_INVOCATIONS,
   NON_CALLABLE_WORKFLOW_STATUSES
 } from "../domain/constants.mjs";
+import { workflowConflictEntriesForSkill } from "../conflicts.mjs";
 import { isModelSelectableInvocation, isUserControlledSource } from "../domain/source-classes.mjs";
 import { classifySkillTrust, workflowSkillRole } from "./source-trust.mjs";
 
@@ -12,9 +13,6 @@ export function canUseSkill(workspace, skillId, workflowName) {
   const workflow = workspace.workflows.find((candidate) => candidate.name === workflowName);
   const reasons = [];
 
-  if (!policy.ok) {
-    reasons.push("Policy check failed.");
-  }
   if (skill === undefined) {
     reasons.push(`Unknown skill: ${skillId}`);
   }
@@ -26,6 +24,13 @@ export function canUseSkill(workspace, skillId, workflowName) {
   }
 
   const role = workflowSkillRole(workflow, skillId);
+  for (const conflict of workflowConflictEntriesForSkill(workspace, workflow, skillId)) {
+    const other = conflict.skill === skillId ? conflict.conflictingSkill : conflict.skill;
+    reasons.push(`Skill ${skillId} conflicts with active skill ${other} in workflow ${workflowName}.`);
+  }
+  if (!policy.ok) {
+    reasons.push("Policy check failed.");
+  }
   if (workflow.blockedSkills.includes(skillId)) {
     reasons.push(`Workflow ${workflowName} blocks skill ${skillId}.`);
   }

package/src/control/skill-crud.mjs

@@ -81,6 +81,68 @@ export async function addSkill(options) {
   return await writeCheckedConfig(document, originalText, validation, `Added ${options.skillId}`);
 }
 
+export async function addSkillVariant(options) {
+  const { document, originalText } = await loadConfig(options.configPath);
+  const skills = requireMapAt(document, ["skills"], "skills");
+  const baseSkill = requireConfigSkill(document, options.baseId);
+  const workflow = requireConfigWorkflow(document, options.workflow);
+  const capabilityDefinition = requireConfigCapability(document, options.capability);
+  const existingRequiredPolicy = readRequiredCapabilityPolicy(workflow, options.capability);
+  const required = ensureRequiredCapability(workflow, options.capability, document);
+  const existingVariant = skills.get(options.variantId, true);
+
+  if (existingVariant === undefined) {
+    if (options.path === undefined) {
+      throw new Error("--path is required when adding an undeclared variant skill");
+    }
+    if (options.ownerInstallUnit !== undefined) {
+      appendSkillToOwnerInstallUnit(document, options.ownerInstallUnit, options.variantId);
+    }
+    const invocation = variantInvocation(options, existingRequiredPolicy, capabilityDefinition);
+    validateSkillState("active", invocation, "exported");
+    skills.set(options.variantId, document.createNode(stripUndefined({
+      path: normalizeSkillPath(options.path, "skill path"),
+      status: "active",
+      invocation,
+      exposure: "exported",
+      category: options.category ?? readMapString(baseSkill, "category", "uncategorized"),
+      owner_install_unit: options.ownerInstallUnit
+    })));
+  } else {
+    requireYamlMap(existingVariant, `skills.${options.variantId}`);
+  }
+
+  const alternatives = ensureSeq(capabilityDefinition, "alternatives", document);
+  const canonical = readMapString(capabilityDefinition, "canonical", "");
+  if (canonical !== options.baseId && !sequenceIncludes(alternatives, options.baseId)) {
+    addUnique(alternatives, options.baseId);
+  }
+  if (canonical !== options.variantId && !sequenceIncludes(alternatives, options.variantId)) {
+    addUnique(alternatives, options.variantId);
+  }
+
+  const previousPreferred = readMapString(required, "preferred", "");
+  const fallback = ensureSeq(required, "fallback", document);
+  required.set("preferred", options.variantId);
+  setFallbackValues(
+    fallback,
+    orderedVariantFallbacks(
+      sequenceValues(fallback),
+      [previousPreferred, options.baseId, canonical],
+      options.variantId
+    )
+  );
+  addUnique(ensureSeq(workflow, "active_skills", document), options.variantId);
+  removeValue(ensureSeq(workflow, "blocked_skills", document), options.variantId);
+
+  return await writeCheckedConfig(
+    document,
+    originalText,
+    { ...options, validateUse: { skillId: options.variantId, workflow: options.workflow } },
+    `Added variant ${options.variantId} for ${options.baseId} in ${options.workflow}`
+  );
+}
+
 export async function blockSkill(options) {
   const { document, originalText } = await loadConfig(options.configPath);
   requireConfigSkill(document, options.skillId);
@@ -184,6 +246,33 @@ function requireConfigWorkflow(document, workflowName) {
   return raw;
 }
 
+function requireConfigCapability(document, capabilityName) {
+  const capabilities = requireMapAt(document, ["capabilities"], "capabilities");
+  const capability = capabilities.get(capabilityName, true);
+  if (capability === undefined) {
+    throw new Error(`Unknown capability: ${capabilityName}`);
+  }
+  return requireYamlMap(capability, `capabilities.${capabilityName}`);
+}
+
+function appendSkillToOwnerInstallUnit(document, unitId, skillId) {
+  const installUnits = optionalRootMap(document, "install_units");
+  if (installUnits === undefined) {
+    throw new Error(`Unknown install unit: ${unitId}`);
+  }
+  const installUnit = installUnits.get(unitId, true);
+  if (installUnit === undefined) {
+    throw new Error(`Unknown install unit: ${unitId}`);
+  }
+  const unit = requireYamlMap(installUnit, `install_units.${unitId}`);
+  let components = unit.get("components", true);
+  if (components === undefined) {
+    components = document.createNode({});
+    unit.set("components", components);
+  }
+  addUnique(ensureSeq(requireYamlMap(components, `install_units.${unitId}.components`), "skills", document), skillId);
+}
+
 function ensureRequiredCapability(workflow, capabilityName, document) {
   let capabilities = workflow.get("required_capabilities", true);
   if (capabilities === undefined) {
@@ -203,6 +292,59 @@ function ensureRequiredCapability(workflow, capabilityName, document) {
   return capability;
 }
 
+function readRequiredCapabilityPolicy(workflow, capabilityName) {
+  const capabilities = optionalMap(workflow, "required_capabilities");
+  if (capabilities === undefined) {
+    return "";
+  }
+  const capability = capabilities.get(capabilityName, true);
+  if (capability === undefined) {
+    return "";
+  }
+  return readMapString(requireYamlMap(capability, `required_capabilities.${capabilityName}`), "policy", "");
+}
+
+function variantInvocation(options, requiredPolicy, capabilityDefinition) {
+  const explicit = options.mode ?? options.invocation;
+  const computed = firstNonEmpty([
+    explicit,
+    requiredPolicy,
+    readMapString(capabilityDefinition, "default_policy", ""),
+    "manual-only"
+  ]);
+  return computed === "global-auto" ? "manual-only" : computed;
+}
+
+function firstNonEmpty(values) {
+  return values.find((value) => typeof value === "string" && value.length > 0) ?? "manual-only";
+}
+
+function sequenceValues(sequence) {
+  return sequence.items.map((item) => nodeScalarValue(item));
+}
+
+function orderedVariantFallbacks(existingValues, priorityValues, variantId) {
+  const next = [];
+  const seen = new Set();
+  for (const value of [...priorityValues, ...existingValues]) {
+    if (typeof value !== "string" || value.length === 0 || value === variantId || seen.has(value)) {
+      continue;
+    }
+    next.push(value);
+    seen.add(value);
+  }
+  return next;
+}
+
+function setFallbackValues(sequence, values) {
+  while (sequence.items.length > 0) {
+    sequence.delete(0);
+  }
+  for (const value of values) {
+    sequence.add(value);
+  }
+}
+
 function removeSkillFromRequiredCapabilities(workflow, skillId, document) {
   const capabilities = optionalMap(workflow, "required_capabilities");
   if (capabilities === undefined) {

package/src/control/skill-variants.mjs

@@ -0,0 +1,221 @@
+import { readFile } from "node:fs/promises";
+import { normalizeSkillPath } from "../skill-paths.mjs";
+import { loadWorkspace } from "../workspace.mjs";
+import {
+  loadConfig,
+  readMapString,
+  requireMapAt,
+  writeCheckedConfig
+} from "./config-write.mjs";
+import {
+  addVariantCapabilityAlternative,
+  appendSkillToOwnerInstallUnit,
+  promoteVariantInWorkflow,
+  readRequiredCapabilityPolicy,
+  requireConfigCapability,
+  requireConfigSkill,
+  requireConfigWorkflow,
+  stripUndefined,
+  variantConfigMetadata
+} from "./variant-lifecycle-config.mjs";
+import {
+  cleanupCreatedVariantFile,
+  copySkillFileForFork,
+  digestVariantFile,
+  resolveVariantLiveSkillFile,
+  variantSnapshotTarget,
+  writeVariantSnapshot
+} from "./variant-files.mjs";
+
+const APPROVE_INVOCATIONS = new Set(["manual-only", "router-only", "workflow-auto"]);
+
+export async function forkSkillVariant(options) {
+  const { document, originalText } = await loadConfig(options.configPath);
+  const skills = requireMapAt(document, ["skills"], "skills");
+  const baseSkill = requireConfigSkill(document, options.baseId);
+  const workflow = requireConfigWorkflow(document, options.workflow);
+  const capability = requireConfigCapability(document, options.capability);
+  if (skills.get(options.variantId, true) !== undefined) {
+    throw new Error(`Skill already exists: ${options.variantId}`);
+  }
+  if (options.path === undefined) {
+    throw new Error("--path is required when forking a variant skill");
+  }
+
+  const variantPath = normalizeSkillPath(options.path, "skill path");
+  const baseFile = resolveVariantLiveSkillFile({
+    skillsRoot: options.skillsRoot,
+    skill: { id: options.baseId, path: readMapString(baseSkill, "path", options.baseId) }
+  });
+  const targetFile = resolveVariantLiveSkillFile({
+    skillsRoot: options.skillsRoot,
+    skill: { id: options.variantId, path: variantPath }
+  });
+  const baseContent = await readBaseSkillFile(baseFile, options.baseId);
+  const baseDigest = await digestVariantFile(baseFile);
+  const snapshot = variantSnapshotTarget({ configPath: options.configPath, skillId: options.variantId, snapshotName: "base" });
+  const variant = draftVariantMetadata(options, baseDigest, snapshot.storedPath);
+
+  if (options.ownerInstallUnit !== undefined) {
+    appendSkillToOwnerInstallUnit(document, options.ownerInstallUnit, options.variantId);
+  }
+  skills.set(options.variantId, document.createNode(stripUndefined({
+    path: variantPath,
+    status: "candidate",
+    invocation: "manual-only",
+    exposure: "exported",
+    category: options.category ?? readMapString(baseSkill, "category", "uncategorized"),
+    owner_install_unit: options.ownerInstallUnit,
+    variant: variantConfigMetadata(variant)
+  })));
+  addVariantCapabilityAlternative(document, capability, options);
+
+  const filePlan = [];
+  let copied = false;
+  let snapshotWritten = false;
+  try {
+    filePlan.push(await copySkillFileForFork({
+      sourceFile: baseFile,
+      targetFile,
+      dryRun: options.dryRun === true
+    }));
+    copied = options.dryRun !== true;
+    filePlan.push(await writeVariantSnapshot({
+      configPath: options.configPath,
+      skillId: options.variantId,
+      snapshotName: "base",
+      content: baseContent,
+      expectedDigest: baseDigest,
+      dryRun: options.dryRun === true
+    }));
+    snapshotWritten = options.dryRun !== true;
+    const result = await writeCheckedConfig(
+      document,
+      originalText,
+      options,
+      `Forked draft variant ${options.variantId} from ${options.baseId}`
+    );
+    return { ...result, skill: options.variantId, variant, filePlan, warnings: [] };
+  } catch (error) {
+    if (snapshotWritten) {
+      await cleanupCreatedVariantFile(snapshot.absolutePath, { expectedDigest: baseDigest }).catch(() => undefined);
+    }
+    if (copied) {
+      await cleanupCreatedVariantFile(targetFile, { expectedDigest: baseDigest }).catch(() => undefined);
+    }
+    throw error;
+  }
+}
+
+export async function approveSkillVariant(options) {
+  const current = await lifecycleSkill(options);
+  const liveFile = resolveVariantLiveSkillFile({ skillsRoot: options.skillsRoot, skill: current });
+  const liveContent = await readLiveVariantFile(liveFile, options.variantId);
+  const liveDigest = await digestVariantFile(liveFile);
+  const { document, originalText } = await loadConfig(options.configPath);
+  const skill = requireConfigSkill(document, options.variantId);
+  const workflow = requireConfigWorkflow(document, current.variant.workflow);
+  const capability = requireConfigCapability(document, current.variant.capability);
+  const invocation = approvedInvocation(options, workflow, capability, current.variant.capability);
+  const snapshot = variantSnapshotTarget({ configPath: options.configPath, skillId: options.variantId, snapshotName: "approved" });
+  const variant = {
+    ...current.variant,
+    status: "approved",
+    approved: { contentDigest: liveDigest, snapshot: snapshot.storedPath }
+  };
+
+  skill.set("status", "active");
+  skill.set("invocation", invocation);
+  skill.set("variant", document.createNode(variantConfigMetadata(variant)));
+  addVariantCapabilityAlternative(document, capability, { baseId: variant.of, variantId: options.variantId });
+  promoteVariantInWorkflow(document, workflow, capability, { baseId: variant.of, variantId: options.variantId, capability: variant.capability });
+
+  const writeOptions = { ...options, validateUse: { skillId: options.variantId, workflow: variant.workflow } };
+  const filePlan = [await writeVariantSnapshot({
+    configPath: options.configPath,
+    skillId: options.variantId,
+    snapshotName: "approved",
+    content: liveContent,
+    expectedDigest: liveDigest,
+    allowOverwrite: true,
+    dryRun: true
+  })];
+  if (options.dryRun === true) {
+    const result = await writeCheckedConfig(document, originalText, writeOptions, `Approved variant ${options.variantId} for ${variant.workflow}`);
+    return { ...result, skill: options.variantId, variant, filePlan, warnings: [] };
+  }
+  await writeCheckedConfig(document, originalText, { ...writeOptions, dryRun: true }, `Approved variant ${options.variantId} for ${variant.workflow}`);
+  filePlan[0] = await writeVariantSnapshot({
+    configPath: options.configPath,
+    skillId: options.variantId,
+    snapshotName: "approved",
+    content: liveContent,
+    expectedDigest: liveDigest,
+    allowOverwrite: true
+  });
+  const result = await writeCheckedConfig(document, originalText, writeOptions, `Approved variant ${options.variantId} for ${variant.workflow}`);
+  return { ...result, skill: options.variantId, variant, filePlan, warnings: [] };
+}
+
+function draftVariantMetadata(options, baseDigest, snapshotPath) {
+  return {
+    of: options.baseId,
+    adaptedFor: options.adaptedFor ?? null,
+    capability: options.capability,
+    workflow: options.workflow,
+    status: "draft",
+    base: { contentDigest: baseDigest, snapshot: snapshotPath }
+  };
+}
+
+async function lifecycleSkill(options) {
+  const workspace = await loadWorkspace({ configPath: options.configPath, skillsRoot: options.skillsRoot });
+  const skill = workspace.skills.find((candidate) => candidate.id === options.variantId);
+  if (skill === undefined) {
+    throw new Error(`Unknown skill: ${options.variantId}`);
+  }
+  if (skill.variant === null || skill.variant === undefined) {
+    throw new Error(`Skill ${options.variantId} is not a lifecycle variant`);
+  }
+  return skill;
+}
+
+function approvedInvocation(options, workflow, capability, capabilityName) {
+  const computed = firstNonEmpty([
+    options.mode,
+    options.invocation,
+    readRequiredCapabilityPolicy(workflow, capabilityName),
+    readMapString(capability, "default_policy", ""),
+    "manual-only"
+  ]);
+  if (!APPROVE_INVOCATIONS.has(computed)) {
+    throw new Error("approve requires --mode manual-only, router-only, or workflow-auto");
+  }
+  return computed;
+}
+
+function firstNonEmpty(values) {
+  return values.find((value) => typeof value === "string" && value.length > 0) ?? "manual-only";
+}
+
+async function readBaseSkillFile(path, skillId) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error(`Missing base skill file for ${skillId}: ${path}`);
+    }
+    throw error;
+  }
+}
+
+async function readLiveVariantFile(path, skillId) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error(`Missing live variant skill file for ${skillId}: ${path}`);
+    }
+    throw error;
+  }
+}

package/src/control/source-trust.mjs

@@ -130,6 +130,7 @@ export function skillSummary(workspace, skill, workflow) {
     invocation: skill.invocation,
     exposure: skill.exposure,
     category: skill.category,
+    variant: skill.variant ?? null,
     sourceClass: source.class,
     sourcePriority: source.priority,
     ownerInstallUnit: source.ownerInstallUnit,