agent-skillboard 0.1.0

package/src/brief-cli.mjs

@@ -0,0 +1,40 @@
+import { dirname, isAbsolute } from "node:path";
+import { buildSkillBrief } from "./advisor.mjs";
+import { renderSkillBrief } from "./brief-renderer.mjs";
+
+export async function runBriefCommand(options, stdout, paths) {
+  const json = options.get("json") === "true";
+  const result = await buildSkillBrief({
+    root: briefRoot(options),
+      configPath: paths.configPath,
+      skillsRoot: paths.skillsRoot,
+      workflow: options.get("workflow"),
+      includeActions: options.get("include-actions") === "true" || !json
+    });
+  writeBriefOutput(stdout, result, options);
+  return briefExitCode(result);
+}
+
+function briefRoot(options) {
+  const dir = options.get("dir");
+  if (dir !== undefined) {
+    return dir;
+  }
+  const config = options.get("config");
+  return config !== undefined && isAbsolute(config) ? dirname(config) : ".";
+}
+
+function briefExitCode(result) {
+  if (result.ok) {
+    return 0;
+  }
+  return result.error?.code === "unknown-workflow" ? 2 : 1;
+}
+
+function writeBriefOutput(stdout, result, options) {
+  if (options.get("json") === "true") {
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  stdout.write(renderSkillBrief(result, { verbose: options.get("verbose") === "true" }));
+}

package/src/brief-renderer.mjs

@@ -0,0 +1,362 @@
+const SKILL_SECTIONS = [
+  ["What your AI can use now", "automatic_allowed"],
+  ["Manual only", "manual_allowed"],
+  ["Needs your decision", "needs_review"],
+  ["Blocked for safety", "blocked"]
+];
+
+const PRIMARY_ACTION_KINDS = new Set([
+  "setup-guidance",
+  "block-install-unit",
+  "review-install-unit",
+  "trust-install-unit",
+  "activate-skill",
+  "hook-install"
+]);
+
+const CLEANUP_ACTION_KINDS = new Set([
+  "remove-skill-force",
+  "reset-cleanup"
+]);
+const COMPACT_SKILL_LIMIT = 5;
+const TOP_CATEGORY_LIMIT = 5;
+const MAX_ACTIONS_PER_TEXT_SECTION = 5;
+const ACTION_KIND_RANK = new Map([
+  ["setup-guidance", 0],
+  ["block-install-unit", 0],
+  ["review-install-unit", 0],
+  ["trust-install-unit", 0],
+  ["activate-skill", 1],
+  ["hook-install", 2],
+  ["block-skill", 3],
+  ["remove-skill-force", 4],
+  ["reset-cleanup", 5]
+]);
+
+export function renderSkillBrief(brief, options = {}) {
+  const verbose = options.verbose === true;
+  const counts = briefCounts(brief);
+  const lines = [
+    "# SkillBoard Brief",
+    "",
+    `AI can use now: ${counts.usable} (${counts.automatic} automatic, ${counts.manual} manual)`,
+    `Needs your decision: ${counts.needsDecision}`,
+    `Blocked for safety: ${counts.blocked}`,
+    `Workflow: ${workflowSummary(brief.workflow)}`,
+    ""
+  ];
+  if (brief.error !== undefined) {
+    lines.push(`Error: ${safeText(brief.error.message)}`, "");
+  }
+  emitCategorySummary(lines, brief);
+  emitNextAction(lines, brief, { verbose });
+  for (const [title, key] of SKILL_SECTIONS) {
+    emitSkillSection(lines, title, brief.skills[key], {
+      brief,
+      groupLabel: compactGroupLabel(key),
+      verbose
+    });
+  }
+  emitSkillSection(lines, "Not in this workflow", [
+    ...brief.skills.not_in_workflow,
+    ...brief.skills.installed_only
+  ], {
+    brief,
+    groupLabel: "inactive or undeclared skills",
+    verbose
+  });
+  emitActions(lines, brief, { verbose });
+  return `${lines.join("\n")}\n`;
+}
+
+function briefCounts(brief) {
+  const automatic = brief.skills.automatic_allowed.length;
+  const manual = brief.skills.manual_allowed.length;
+  return {
+    automatic,
+    manual,
+    usable: automatic + manual,
+    needsDecision: brief.skills.needs_review.length,
+    blocked: brief.skills.blocked.length
+  };
+}
+
+function emitSkillSection(lines, title, entries, options) {
+  lines.push(`## ${title}`, "");
+  if (entries.length === 0) {
+    lines.push("- none", "");
+    return;
+  }
+  const visibleEntries = options.verbose ? entries : entries.slice(0, COMPACT_SKILL_LIMIT);
+  for (const entry of visibleEntries) {
+    const path = entry.path === undefined ? "" : ` (${safeText(entry.path)})`;
+    const reason = entry.reason === null || entry.reason === undefined
+      ? ""
+      : ` - ${safeText(entry.reason)}`;
+    lines.push(`- ${code(entry.id)}${path}${reason}`);
+  }
+  const hidden = entries.length - visibleEntries.length;
+  if (hidden > 0) {
+    lines.push(`- ${hidden} more ${options.groupLabel} hidden. Run ${code(verboseCommand(options.brief))} or ${code(listCommand(options.brief))}.`);
+  }
+  lines.push("");
+}
+
+function emitCategorySummary(lines, brief) {
+  const categories = categoryCounts(brief);
+  lines.push("## Top categories", "");
+  if (categories.length === 0) {
+    lines.push("- none", "");
+    return;
+  }
+  for (const [category, count] of categories.slice(0, TOP_CATEGORY_LIMIT)) {
+    lines.push(`- ${safeText(category)}: ${count}`);
+  }
+  const hidden = categories.length - TOP_CATEGORY_LIMIT;
+  if (hidden > 0) {
+    lines.push(`- ${hidden} more categories hidden.`);
+  }
+  lines.push("");
+}
+
+function categoryCounts(brief) {
+  const counts = new Map();
+  for (const entry of allSkillEntries(brief)) {
+    const category = entry.advanced?.category ?? "uncategorized";
+    counts.set(category, (counts.get(category) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort((left, right) => {
+    return right[1] - left[1] || left[0].localeCompare(right[0]);
+  });
+}
+
+function allSkillEntries(brief) {
+  return [
+    ...brief.skills.automatic_allowed,
+    ...brief.skills.manual_allowed,
+    ...brief.skills.needs_review,
+    ...brief.skills.blocked,
+    ...brief.skills.not_in_workflow,
+    ...brief.skills.installed_only
+  ];
+}
+
+function compactGroupLabel(key) {
+  if (key === "automatic_allowed") {
+    return "automatic skills";
+  }
+  if (key === "manual_allowed") {
+    return "manual-only skills";
+  }
+  if (key === "needs_review") {
+    return "decision items";
+  }
+  return "blocked skills";
+}
+
+function verboseCommand(brief) {
+  return `skillboard brief --verbose${workflowOption(brief)}`;
+}
+
+function listCommand(brief) {
+  return `skillboard list skills${workflowOption(brief)}`;
+}
+
+function workflowOption(brief) {
+  const selected = brief.workflow.selected;
+  if (selected === null || brief.workflow.unknown) {
+    return "";
+  }
+  return ` --workflow ${selected}`;
+}
+
+function emitActions(lines, brief, options) {
+  const actions = actionsForTextBrief(brief);
+  lines.push("## Suggested next actions", "");
+  if (actions.length === 0) {
+    lines.push("- none", "");
+    return;
+  }
+  const ordered = orderedActions(actions, prioritizeSourceDecisions(brief));
+  const primary = ordered.filter((action) => PRIMARY_ACTION_KINDS.has(action.kind));
+  const other = ordered.filter((action) => !PRIMARY_ACTION_KINDS.has(action.kind) && !CLEANUP_ACTION_KINDS.has(action.kind));
+  const cleanup = ordered.filter((action) => CLEANUP_ACTION_KINDS.has(action.kind));
+  if (primary.length === 0 && other.length === 0 && cleanup.length === 0) {
+    lines.push("- none", "");
+    return;
+  }
+  emitActionList(lines, primary, { ...options, brief });
+  if (!options.verbose) {
+    const hiddenSecondary = other.length + cleanup.length;
+    if (hiddenSecondary > 0) {
+      if (lines.at(-1) === "") {
+        lines.pop();
+      }
+      lines.push(`- ${hiddenSecondary} safety and cleanup actions hidden. Run ${code(`skillboard brief --verbose${workflowOption(brief)}`)}.`);
+      lines.push("");
+    }
+    return;
+  }
+  if (other.length > 0) {
+    lines.push("## Other safety actions", "");
+    emitActionList(lines, other, { ...options, brief });
+  }
+  if (cleanup.length > 0) {
+    lines.push("## Advanced cleanup actions", "");
+    emitActionList(lines, cleanup, { ...options, brief });
+  }
+}
+
+function emitNextAction(lines, brief, options) {
+  lines.push("## Next safe action", "");
+  const action = nextSafeAction(brief);
+  if (action === null) {
+    lines.push("- none", "");
+    return;
+  }
+  emitAction(lines, action, { ...options, brief, listOnly: false });
+  lines.push("");
+}
+
+function nextSafeAction(brief) {
+  const actions = actionsForTextBrief(brief);
+  if (actions.length === 0) {
+    return null;
+  }
+  const ordered = orderedActions(actions, prioritizeSourceDecisions(brief));
+  return ordered.find((action) => PRIMARY_ACTION_KINDS.has(action.kind) && action.blocked_reason === null)
+    ?? ordered.find((action) => PRIMARY_ACTION_KINDS.has(action.kind))
+    ?? null;
+}
+
+function actionsForTextBrief(brief) {
+  return brief.actions ?? [];
+}
+
+function orderedActions(actions, prioritizeDecisions) {
+  return [...actions].sort((left, right) => {
+    return actionRank(left, prioritizeDecisions) - actionRank(right, prioritizeDecisions)
+      || left.id.localeCompare(right.id);
+  });
+}
+
+function prioritizeSourceDecisions(brief) {
+  return brief.skills.needs_review.length > 0;
+}
+
+function actionRank(action, prioritizeDecisions) {
+  if (!prioritizeDecisions && isSourceDecisionAction(action)) {
+    return 2;
+  }
+  return ACTION_KIND_RANK.get(action.kind) ?? 10;
+}
+
+function isSourceDecisionAction(action) {
+  return action.kind === "block-install-unit"
+    || action.kind === "review-install-unit"
+    || action.kind === "trust-install-unit";
+}
+
+function emitActionList(lines, actions, options) {
+  if (actions.length === 0) {
+    lines.push("- none", "");
+    return;
+  }
+  for (const action of actions.slice(0, MAX_ACTIONS_PER_TEXT_SECTION)) {
+    emitAction(lines, action, { ...options, listOnly: !options.verbose });
+  }
+  const hidden = actions.length - MAX_ACTIONS_PER_TEXT_SECTION;
+  if (hidden > 0) {
+    const details = options.verbose
+      ? "skillboard brief --include-actions --json"
+      : `skillboard brief --verbose${workflowOption(options.brief)}`;
+    lines.push(`- ${hidden} more action cards available with ${code(details)}.`);
+  }
+  lines.push("");
+}
+
+function emitAction(lines, action, options) {
+  if (options.listOnly) {
+    emitCompactActionListItem(lines, action);
+    return;
+  }
+
+  lines.push(`- ${safeText(action.label)} (${action.risk})`);
+  lines.push(`  - why: ${safeText(action.reason)}`);
+  if (action.blocked_reason !== null) {
+    lines.push(`  - blocked: ${safeText(action.blocked_reason)}`);
+  }
+  if (!options.verbose) {
+    emitCompactActionCommands(lines, action, options.brief);
+    return;
+  }
+  if (action.application?.preview !== undefined && action.application.preview !== null) {
+    lines.push(`  - preview action: ${code(action.application.preview.display, Number.POSITIVE_INFINITY)}`);
+  }
+  if (action.application?.apply !== undefined && action.application.apply !== null) {
+    lines.push(`  - apply action: ${code(action.application.apply.display, Number.POSITIVE_INFINITY)}`);
+  }
+  if (action.dry_run !== null) {
+    lines.push(`  - ${rawLabel(action, "preview")}: ${code(action.dry_run.display)}`);
+  }
+  if (action.apply !== null) {
+    lines.push(`  - ${rawLabel(action, "apply")}: ${code(action.apply.display)}`);
+  }
+}
+
+function emitCompactActionListItem(lines, action) {
+  const blocked = action.blocked_reason === null ? "" : ` - blocked: ${safeText(action.blocked_reason)}`;
+  lines.push(`- ${safeText(action.label)} (${action.risk})${blocked}`);
+}
+
+function emitCompactActionCommands(lines, action, brief) {
+  let emittedCommand = false;
+  if (action.application?.preview !== undefined && action.application.preview !== null) {
+    lines.push(`  - preview: ${code(compactApplyActionCommand(action, brief, "preview"))}`);
+    emittedCommand = true;
+  }
+  if (action.application?.apply !== undefined && action.application.apply !== null) {
+    lines.push(`  - apply: ${code(compactApplyActionCommand(action, brief, "apply"))}`);
+    emittedCommand = true;
+  }
+  if (action.application?.blocked_reason !== undefined && action.application.blocked_reason !== null) {
+    lines.push(`  - blocked: ${safeText(action.application.blocked_reason)}`);
+  }
+  if (!emittedCommand && action.dry_run !== null) {
+    lines.push(`  - preview: ${code(action.dry_run.display, Number.POSITIVE_INFINITY)}`);
+  }
+  lines.push(`  - details: ${code(`skillboard brief --verbose${workflowOption(brief)}`)}`);
+}
+
+function compactApplyActionCommand(action, brief, mode) {
+  const flag = mode === "preview" ? "--dry-run" : "--yes";
+  const destructive = mode === "apply" && action.kind === "reset-cleanup" ? " --allow-destructive" : "";
+  return `skillboard apply-action ${action.id}${workflowOption(brief)} ${flag}${destructive}`;
+}
+
+function rawLabel(action, label) {
+  return action.application?.preview === undefined ? label : `underlying ${label}`;
+}
+
+function workflowSummary(workflow) {
+  if (workflow.unknown) {
+    return `${workflow.selected} (unknown)`;
+  }
+  if (workflow.needs_selection) {
+    return `needs selection: ${workflow.candidates.join(", ")}`;
+  }
+  if (workflow.selected === null) {
+    return "none selected";
+  }
+  return `${workflow.selected}${workflow.defaulted ? " (defaulted)" : ""}`;
+}
+
+function safeText(value, maxLength = 180) {
+  const compact = String(value).replaceAll(/\s+/g, " ").trim();
+  const withoutTicks = compact.replaceAll("`", "'");
+  return withoutTicks.length > maxLength ? `${withoutTicks.slice(0, maxLength - 3)}...` : withoutTicks;
+}
+
+function code(value, maxLength = 180) {
+  return `\`${safeText(value, maxLength)}\``;
+}

package/src/change-plan.mjs

@@ -0,0 +1,169 @@
+import YAML from "yaml";
+
+const DEFAULT_SEMANTIC_LIMIT = 50;
+
+export function textChangePlan(before, after) {
+  const beforeLines = before.split(/\r?\n/u);
+  const afterLines = after.split(/\r?\n/u);
+  const semantic = semanticChangePlan(before, after, { limit: DEFAULT_SEMANTIC_LIMIT });
+  return {
+    changed: before !== after,
+    beforeBytes: Buffer.byteLength(before),
+    afterBytes: Buffer.byteLength(after),
+    beforeLines: beforeLines.length,
+    afterLines: afterLines.length,
+    changedLineCount: countChangedLinePositions(beforeLines, afterLines),
+    semanticAvailable: semantic.available,
+    semanticError: semantic.error,
+    semanticChangeCount: semantic.changeCount,
+    semanticTruncated: semantic.truncated,
+    semanticChanges: semantic.changes
+  };
+}
+
+function countChangedLinePositions(beforeLines, afterLines) {
+  const length = Math.max(beforeLines.length, afterLines.length);
+  let count = 0;
+  for (let index = 0; index < length; index += 1) {
+    if (beforeLines[index] !== afterLines[index]) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+function semanticChangePlan(before, after, options) {
+  try {
+    const beforeValue = YAML.parse(before) ?? null;
+    const afterValue = YAML.parse(after) ?? null;
+    const state = { changes: [], total: 0, truncated: false, limit: options.limit };
+    collectSemanticChanges(beforeValue, afterValue, [], state);
+    return {
+      available: true,
+      error: null,
+      changeCount: state.total,
+      truncated: state.truncated,
+      changes: state.changes
+    };
+  } catch (error) {
+    return {
+      available: false,
+      error: error instanceof Error ? error.message : String(error),
+      changeCount: 0,
+      truncated: false,
+      changes: []
+    };
+  }
+}
+
+function collectSemanticChanges(beforeValue, afterValue, path, state) {
+  if (jsonEqual(beforeValue, afterValue)) {
+    return;
+  }
+  if (beforeValue === undefined) {
+    addSemanticChange(state, "added", path, "absent", valueSummary(afterValue));
+    return;
+  }
+  if (afterValue === undefined) {
+    addSemanticChange(state, "removed", path, valueSummary(beforeValue), "absent");
+    return;
+  }
+  if (isRecord(beforeValue) && isRecord(afterValue)) {
+    const keys = [...new Set([...Object.keys(beforeValue), ...Object.keys(afterValue)])].sort((left, right) => left.localeCompare(right));
+    for (const key of keys) {
+      collectSemanticChanges(beforeValue[key], afterValue[key], [...path, key], state);
+    }
+    return;
+  }
+  if (Array.isArray(beforeValue) && Array.isArray(afterValue)) {
+    collectArrayChanges(beforeValue, afterValue, path, state);
+    return;
+  }
+  addSemanticChange(state, "changed", path, valueSummary(beforeValue), valueSummary(afterValue));
+}
+
+function collectArrayChanges(beforeValue, afterValue, path, state) {
+  if (beforeValue.every(isScalar) && afterValue.every(isScalar)) {
+    const beforeCounts = countedScalars(beforeValue);
+    const afterCounts = countedScalars(afterValue);
+    const keys = [...new Set([...beforeCounts.keys(), ...afterCounts.keys()])].sort((left, right) => left.localeCompare(right));
+    let emitted = false;
+    for (const key of keys) {
+      const beforeCount = beforeCounts.get(key) ?? 0;
+      const afterCount = afterCounts.get(key) ?? 0;
+      const scalar = JSON.parse(key);
+      if (afterCount > beforeCount) {
+        addSemanticChange(state, "added", [...path, scalar], "absent", `scalar x${afterCount - beforeCount}`);
+        emitted = true;
+      } else if (beforeCount > afterCount) {
+        addSemanticChange(state, "removed", [...path, scalar], `scalar x${beforeCount - afterCount}`, "absent");
+        emitted = true;
+      }
+    }
+    if (emitted) {
+      return;
+    }
+  }
+  addSemanticChange(state, "changed", path, valueSummary(beforeValue), valueSummary(afterValue));
+}
+
+function addSemanticChange(state, type, path, before, after) {
+  state.total += 1;
+  if (state.changes.length >= state.limit) {
+    state.truncated = true;
+    return;
+  }
+  state.changes.push({
+    type,
+    path: jsonPointer(path),
+    before,
+    after
+  });
+}
+
+function countedScalars(values) {
+  const counts = new Map();
+  for (const value of values) {
+    const key = JSON.stringify(value);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return counts;
+}
+
+function valueSummary(value) {
+  if (value === undefined) {
+    return "absent";
+  }
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return `sequence(${value.length})`;
+  }
+  if (isRecord(value)) {
+    return `mapping(${Object.keys(value).length})`;
+  }
+  if (typeof value === "string") {
+    return value.length > 80 ? `string(${value.length})` : JSON.stringify(value);
+  }
+  return String(value);
+}
+
+function jsonPointer(path) {
+  if (path.length === 0) {
+    return "/";
+  }
+  return `/${path.map((part) => String(part).replace(/~/g, "~0").replace(/\//g, "~1")).join("/")}`;
+}
+
+function jsonEqual(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isScalar(value) {
+  return value === null || ["string", "number", "boolean"].includes(typeof value);
+}