phronesis 1.0.0

package/src/skill-discovery.js

@@ -0,0 +1,117 @@
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import fse from 'fs-extra';
+import { loadSkills, resolveActionTypes } from '@phronesis/core';
+
+export const SKILL_DISCOVERY_BEGIN = '<!-- skills:begin -->';
+export const SKILL_DISCOVERY_END = '<!-- skills:end -->';
+
+function cell(value) {
+  return String(value).replace(/\|/g, '\\|').replace(/\s+/g, ' ').trim();
+}
+
+export function triggerSummary(invocation) {
+  if (invocation.explicit.length) {
+    return [invocation.explicit[0], invocation.suggested[0]].filter(Boolean);
+  }
+  if (invocation.suggested.length) return invocation.suggested.slice(0, 2);
+  if (invocation.woven) return ['(woven)'];
+  return ['(no trigger)'];
+}
+
+export function buildSkillDiscoveryBlock(skills) {
+  const rows = [
+    SKILL_DISCOVERY_BEGIN,
+    '| Skill | Directory | Triggers |',
+    '|---|---|---|',
+  ];
+  for (const [name, skill] of Object.entries(skills)) {
+    const triggers = triggerSummary(skill.invocation).map((t) => `\`${cell(t)}\``).join(', ');
+    rows.push(`| \`${cell(name)}\` | \`skills/${cell(name)}/\` | ${triggers} |`);
+  }
+  rows.push(
+    'Read a skill\'s `SKILL.md` only when its trigger fires; never preload all skills.',
+    'Raw-stage skills (`ingest`, `research`) feed `compile`.',
+    SKILL_DISCOVERY_END,
+  );
+  return rows.join('\n');
+}
+
+export function replaceSkillDiscoveryBlock(agents, block) {
+  const start = agents.indexOf(SKILL_DISCOVERY_BEGIN);
+  const end = agents.indexOf(SKILL_DISCOVERY_END);
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error('AGENTS.md section 4 is missing the skills:begin/end markers');
+  }
+  return `${agents.slice(0, start)}${block}${agents.slice(end + SKILL_DISCOVERY_END.length)}`;
+}
+
+export async function buildSkillDiscoveryForRegistry({ installRoot, registry }) {
+  const action = resolveActionTypes(registry);
+  if (action.errors.length) {
+    return { errors: action.errors.map((e) => `action-type registry invalid: ${e}`), block: null, skills: {} };
+  }
+  const loaded = await loadSkills({
+    installRoot,
+    registry,
+    registeredActionTypes: Object.keys(action.effective),
+  });
+  if (loaded.errors.length) return { errors: loaded.errors, block: null, skills: {} };
+  return { errors: [], block: buildSkillDiscoveryBlock(loaded.skills), skills: loaded.skills };
+}
+
+export async function refreshSkillDiscovery({ installRoot, domain, registry }) {
+  const agentsPath = join(installRoot, 'domains', domain, 'AGENTS.md');
+  const rendered = await buildSkillDiscoveryForRegistry({ installRoot, registry });
+  if (rendered.errors.length) {
+    throw new Error(`cannot render AGENTS.md skill discovery: ${rendered.errors.join('; ')}`);
+  }
+  const agents = await readFile(agentsPath, 'utf8');
+  await fse.writeFile(agentsPath, replaceSkillDiscoveryBlock(agents, rendered.block));
+  return rendered;
+}
+
+export function extractSkillDiscoveryBlock(agents) {
+  const start = agents.indexOf(SKILL_DISCOVERY_BEGIN);
+  const end = agents.indexOf(SKILL_DISCOVERY_END);
+  if (start === -1 || end === -1 || end < start) return null;
+  return agents.slice(start, end + SKILL_DISCOVERY_END.length);
+}
+
+export async function checkSkillDiscoveryStaleness({ installRoot }) {
+  let registry;
+  try {
+    registry = await fse.readJson(join(installRoot, '.phronesis', 'registry.json'));
+  } catch (err) {
+    return [{ domain: null, message: `could not read .phronesis/registry.json for skill discovery: ${err.message}` }];
+  }
+  const domains = Array.isArray(registry.domains) ? registry.domains : [];
+  const rendered = await buildSkillDiscoveryForRegistry({ installRoot, registry });
+  if (rendered.errors.length) {
+    return rendered.errors.map((e) => ({ domain: null, message: `cannot recompute AGENTS.md skill discovery: ${e}` }));
+  }
+  const expectedTable = extractSkillDiscoveryBlock(rendered.block);
+  const findings = [];
+  for (const domain of domains) {
+    const rel = `domains/${domain}/AGENTS.md`;
+    let agents;
+    try {
+      agents = await readFile(join(installRoot, rel), 'utf8');
+    } catch (err) {
+      findings.push({ domain, message: `${rel}: could not read AGENTS.md (${err.message})` });
+      continue;
+    }
+    const actualTable = extractSkillDiscoveryBlock(agents);
+    if (!actualTable) {
+      findings.push({ domain, message: `${rel}: missing skill-discovery marker block` });
+      continue;
+    }
+    if (actualTable !== expectedTable) {
+      findings.push({
+        domain,
+        message: `${rel}: skill discovery table is stale; regenerate from .phronesis/registry.json and skills/*/SKILL.md`,
+      });
+    }
+  }
+  return findings;
+}