agent-skillboard 0.1.0

package/src/config-helpers.mjs

@@ -0,0 +1,72 @@
+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;
+  }
+  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 undefined;
+  }
+  if (typeof value !== "string") {
+    throw new Error(`${key} must be a string`);
+  }
+  return value;
+}
+
+export function readBoolean(record, key, fallback) {
+  const value = record[key];
+  if (value === undefined) {
+    return fallback;
+  }
+  if (typeof value !== "boolean") {
+    throw new Error(`${key} must be a boolean`);
+  }
+  return value;
+}
+
+export function readNumber(record, key, fallback) {
+  const value = record[key];
+  if (value === undefined) {
+    return fallback;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${key} must be a number`);
+  }
+  return value;
+}
+
+export function readOptionalNumber(record, key) {
+  const value = record[key];
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${key} must be a number`);
+  }
+  return value;
+}
+
+export function readStringList(record, key) {
+  const value = record[key];
+  if (value === undefined) {
+    return [];
+  }
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${key} must be a list of strings`);
+  }
+  return value;
+}

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

@@ -0,0 +1,91 @@
+import { checkPolicy } from "../policy.mjs";
+import {
+  NON_CALLABLE_WORKFLOW_INVOCATIONS,
+  NON_CALLABLE_WORKFLOW_STATUSES
+} from "../domain/constants.mjs";
+import { isModelSelectableInvocation, isUserControlledSource } from "../domain/source-classes.mjs";
+import { classifySkillTrust, workflowSkillRole } from "./source-trust.mjs";
+
+export function canUseSkill(workspace, skillId, workflowName) {
+  const policy = checkPolicy(workspace);
+  const skill = workspace.skills.find((candidate) => candidate.id === skillId);
+  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}`);
+  }
+  if (workflow === undefined) {
+    reasons.push(`Unknown workflow: ${workflowName}`);
+  }
+  if (skill === undefined || workflow === undefined) {
+    return canUseResult(false, skillId, workflowName, skill, workflow, reasons);
+  }
+
+  const role = workflowSkillRole(workflow, skillId);
+  if (workflow.blockedSkills.includes(skillId)) {
+    reasons.push(`Workflow ${workflowName} blocks skill ${skillId}.`);
+  }
+  reasons.push(...trustUseReasons(workspace, skill));
+  if (role.roles.length === 0 && skill.invocation !== "global-auto") {
+    reasons.push(`Skill ${skillId} is not active, preferred, or fallback in workflow ${workflowName}.`);
+  }
+  if (NON_CALLABLE_WORKFLOW_STATUSES.has(skill.status)) {
+    reasons.push(`Skill ${skillId} has non-callable status: ${skill.status}.`);
+  }
+  if (NON_CALLABLE_WORKFLOW_INVOCATIONS.has(skill.invocation)) {
+    reasons.push(`Skill ${skillId} has non-callable invocation: ${skill.invocation}.`);
+  }
+  if (skill.invocation === "global-auto" && skill.exposure !== "global-meta") {
+    reasons.push(`Skill ${skillId} is global-auto but not global-meta.`);
+  }
+
+  return canUseResult(reasons.length === 0, skillId, workflowName, skill, workflow, reasons, role, classifySkillTrust(workspace, skill));
+}
+
+function trustUseReasons(workspace, skill) {
+  const unit = skill.ownerInstallUnit === undefined
+    ? undefined
+    : workspace.installUnits.find((candidate) => candidate.id === skill.ownerInstallUnit);
+  if (unit === undefined) {
+    return [];
+  }
+  const trust = classifySkillTrust(workspace, skill);
+  const reasons = [];
+  if (!unit.enabled) {
+    reasons.push(`Install unit ${unit.id} is disabled.`);
+  }
+  if (trust.level === "blocked") {
+    reasons.push(`Install unit ${unit.id} is blocked by source trust policy.`);
+  }
+  if (unit.enabled && !isUserControlledSource(unit) && trust.level === "unreviewed") {
+    reasons.push(`Skill ${skill.id} belongs to unreviewed non-user source ${unit.id}.`);
+  }
+  if (!isUserControlledSource(unit) && isModelSelectableInvocation(skill.invocation) && trust.level === "unreviewed") {
+    reasons.push(`Skill ${skill.id} is model-selectable but source ${unit.id} is unreviewed.`);
+  }
+  if (skill.invocation === "global-auto" && !trust.reviewed) {
+    reasons.push(`Skill ${skill.id} is global-auto but source ${unit.id} is not reviewed or trusted.`);
+  }
+  return reasons;
+}
+
+export function canUseResult(allowed, skillId, workflowName, skill, workflow, reasons, role = { roles: [], capabilityRoles: [] }, trust = null) {
+  const automaticAllowed = allowed && ["workflow-auto", "global-auto"].includes(skill?.invocation ?? "");
+  return {
+    allowed,
+    automaticAllowed,
+    skill: skillId,
+    workflow: workflowName,
+    invocation: skill?.invocation ?? null,
+    status: skill?.status ?? null,
+    workflowKnown: workflow !== undefined,
+    trust,
+    roles: role.roles,
+    capabilityRoles: role.capabilityRoles,
+    reasons
+  };
+}

package/src/control/config-write.mjs

@@ -0,0 +1,163 @@
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join } from "node:path";
+import YAML from "yaml";
+import { loadWorkspace } from "../workspace.mjs";
+import { checkPolicy } from "../policy.mjs";
+import { textChangePlan } from "../change-plan.mjs";
+import { canUseSkill } from "./can-use-guard.mjs";
+
+export async function loadConfig(path) {
+  const text = await readFile(path, "utf8");
+  const document = YAML.parseDocument(text);
+  if (document.errors.length > 0) {
+    throw new Error(`Invalid YAML config: ${document.errors.map((error) => error.message).join("; ")}`);
+  }
+  requireYamlMap(document.contents, "config root");
+  return {
+    document,
+    originalText: text
+  };
+}
+
+export async function writeCheckedConfig(document, originalText, options, message) {
+  const nextText = preserveLineEndings(String(document), originalText);
+  const plan = textChangePlan(originalText, nextText);
+  const tempPath = tempConfigPath(options.configPath);
+  await writeFile(tempPath, nextText, { encoding: "utf8", flag: "wx" });
+  try {
+    const workspace = await loadWorkspace({ configPath: tempPath, skillsRoot: options.skillsRoot });
+    const policy = checkPolicy(workspace);
+    if (!policy.ok) {
+      throw new Error(`Policy update would create invalid config:\n${policy.errors.join("\n")}`);
+    }
+    const validateUses = options.validateUses ?? (options.validateUse === undefined ? [] : [options.validateUse]);
+    for (const useRequest of validateUses) {
+      const use = canUseSkill(workspace, useRequest.skillId, useRequest.workflow);
+      if (!use.allowed) {
+        throw new Error(`Control update would not be usable:\n${use.reasons.join("\n")}`);
+      }
+    }
+    if (options.dryRun === true) {
+      return { message, policy, dryRun: true, changed: plan.changed, plan };
+    }
+    if (plan.changed) {
+      await rename(tempPath, options.configPath);
+    }
+    return { message, policy, dryRun: false, changed: plan.changed, plan };
+  } finally {
+    await rm(tempPath, { force: true });
+  }
+}
+
+function tempConfigPath(configPath) {
+  return join(dirname(configPath), `.${basename(configPath)}.${randomUUID()}.tmp`);
+}
+
+function preserveLineEndings(text, reference) {
+  return reference.includes("\r\n") ? text.replace(/\n/g, "\r\n") : text;
+}
+
+export function requireMapAt(document, path, label) {
+  return requireYamlMap(document.getIn(path, true), label);
+}
+
+export function ensureMapAt(document, path, label) {
+  const existing = document.getIn(path, true);
+  if (existing !== undefined) {
+    const map = requireYamlMap(existing, label);
+    map.flow = false;
+    return map;
+  }
+  const next = document.createNode({});
+  next.flow = false;
+  document.setIn(path, next);
+  return next;
+}
+
+export function requireYamlMap(value, label) {
+  if (!YAML.isMap(value)) {
+    throw new Error(`${label} must be a mapping`);
+  }
+  return value;
+}
+
+export function ensureSeq(map, key, document) {
+  const existing = map.get(key, true);
+  if (existing === undefined) {
+    const next = document.createNode([]);
+    next.flow = false;
+    map.set(key, next);
+    return next;
+  }
+  if (!YAML.isSeq(existing)) {
+    throw new Error(`${key} must be a list`);
+  }
+  existing.flow = false;
+  return existing;
+}
+
+export function optionalSeq(map, key) {
+  const existing = map.get(key, true);
+  if (existing === undefined) {
+    return undefined;
+  }
+  if (!YAML.isSeq(existing)) {
+    throw new Error(`${key} must be a list`);
+  }
+  return existing;
+}
+
+export function optionalMap(map, key) {
+  const existing = map.get(key, true);
+  if (existing === undefined) {
+    return undefined;
+  }
+  return requireYamlMap(existing, key);
+}
+
+export function mapValues(map, label) {
+  return map.items.map((pair) => requireYamlMap(pair.value, label));
+}
+
+export function readMapString(map, key, fallback) {
+  const value = map.get(key);
+  if (value === undefined) {
+    return fallback;
+  }
+  if (typeof value !== "string") {
+    throw new Error(`${key} must be a string`);
+  }
+  return value;
+}
+
+export function addUnique(values, value) {
+  if (!sequenceIncludes(values, value)) {
+    values.add(value);
+  }
+}
+
+export function removeValue(values, value) {
+  for (let index = values.items.length - 1; index >= 0; index -= 1) {
+    if (nodeScalarValue(values.items[index]) === value) {
+      values.delete(index);
+    }
+  }
+}
+
+export function optionalRootMap(document, key) {
+  const existing = document.get(key, true);
+  return existing === undefined ? undefined : requireYamlMap(existing, key);
+}
+
+export function sequenceIncludes(sequence, value) {
+  return sequence.items.some((item) => nodeScalarValue(item) === value);
+}
+
+export function uniqueValues(values) {
+  return [...new Set(values)];
+}
+
+export function nodeScalarValue(node) {
+  return node !== null && typeof node === "object" && "value" in node ? node.value : node;
+}