@1aboveio/skills 0.12.1 → 0.14.0

package/runtime/skills/engineering/engineering-runtime/scripts/invocation-policy.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { isMainModule } from './main-module.mjs';
+
+export const MANUAL_ONLY = 'manual-only';
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function frontmatterBounds(contents) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(contents);
+  if (!match) throw new Error('SKILL.md must begin with YAML frontmatter');
+  return { body: match[1], end: match[0].length };
+}
+
+function manualOnlySkill(contents) {
+  const frontmatter = frontmatterBounds(contents);
+  const declarations = frontmatter.body.match(/^disable-model-invocation\s*:\s*.*$/gm) ?? [];
+  if (declarations.length > 1) throw new Error('SKILL.md repeats disable-model-invocation');
+
+  const body = declarations.length === 1
+    ? frontmatter.body.replace(/^disable-model-invocation\s*:\s*.*$/m, 'disable-model-invocation: true')
+    : `${frontmatter.body}\ndisable-model-invocation: true`;
+  return `---\n${body}\n---\n${contents.slice(frontmatter.end)}`;
+}
+
+function manualOnlyOpenAi(contents) {
+  const policyHeaders = contents.match(/^policy\s*:\s*$/gm) ?? [];
+  if (policyHeaders.length > 1) throw new Error('agents/openai.yaml repeats policy');
+  if (policyHeaders.length === 0) {
+    const prefix = contents.length === 0 || contents.endsWith('\n') ? contents : `${contents}\n`;
+    return `${prefix}policy:\n  allow_implicit_invocation: false\n`;
+  }
+
+  const lines = contents.split('\n');
+  const policyIndex = lines.findIndex((line) => /^policy\s*:\s*$/.test(line));
+  let policyEnd = lines.length;
+  for (let index = policyIndex + 1; index < lines.length; index += 1) {
+    if (/^[^\s#][^:]*\s*:/.test(lines[index])) {
+      policyEnd = index;
+      break;
+    }
+  }
+  const declarations = lines
+    .slice(policyIndex + 1, policyEnd)
+    .filter((line) => /^\s+allow_implicit_invocation\s*:/.test(line));
+  if (declarations.length > 1) throw new Error('agents/openai.yaml repeats policy.allow_implicit_invocation');
+  if (declarations.length === 1) {
+    return lines.map((line, index) => (
+      index > policyIndex && index < policyEnd && /^\s+allow_implicit_invocation\s*:/.test(line)
+        ? '  allow_implicit_invocation: false'
+        : line
+    )).join('\n');
+  }
+  lines.splice(policyIndex + 1, 0, '  allow_implicit_invocation: false');
+  return lines.join('\n');
+}
+
+export function manualOnlyPolicyFindings(skillDirectory) {
+  const findings = [];
+  const skillPath = join(skillDirectory, 'SKILL.md');
+  const openaiPath = join(skillDirectory, 'agents', 'openai.yaml');
+  if (!existsSync(skillPath)) return ['SKILL.md is missing'];
+  const skill = readFileSync(skillPath, 'utf8');
+  const declarations = frontmatterBounds(skill).body.match(/^disable-model-invocation\s*:\s*true\s*$/gm) ?? [];
+  if (declarations.length !== 1) findings.push('SKILL.md must declare disable-model-invocation: true exactly once');
+  if (!existsSync(openaiPath)) {
+    findings.push('agents/openai.yaml is missing');
+  } else {
+    const openai = readFileSync(openaiPath, 'utf8');
+    const policies = openai.match(/^policy\s*:\s*$/gm) ?? [];
+    const implicit = openai.match(/^\s+allow_implicit_invocation\s*:\s*false\s*$/gm) ?? [];
+    if (policies.length !== 1 || implicit.length !== 1) {
+      findings.push('agents/openai.yaml must declare policy.allow_implicit_invocation: false exactly once');
+    }
+  }
+  return findings;
+}
+
+// Restore the reviewed upstream bytes for source-integrity hashing. The installed tree must first
+// pass manualOnlyPolicyFindings; these exact trailing additions are the only intentional divergence.
+export function reviewedSourceInjections(skillDirectory, policy) {
+  if (policy !== MANUAL_ONLY) return [];
+  const findings = manualOnlyPolicyFindings(skillDirectory);
+  if (findings.length > 0) throw new Error(findings.join('; '));
+  const skill = readFileSync(join(skillDirectory, 'SKILL.md'), 'utf8')
+    .replace(/^disable-model-invocation: true\n/m, '');
+  const openai = readFileSync(join(skillDirectory, 'agents', 'openai.yaml'), 'utf8')
+    .replace(/policy:\n  allow_implicit_invocation: false\n?$/, '');
+  return [
+    { relativePath: 'SKILL.md', contents: skill },
+    { relativePath: 'agents/openai.yaml', contents: openai },
+  ];
+}
+
+export function clearInvocationPolicy({ installName, policy, skillsRoot = join(homedir(), '.agents', 'skills') }) {
+  if (!SKILL_NAME.test(installName ?? '')) throw new Error(`invalid installed skill name ${JSON.stringify(installName)}`);
+  if (policy !== MANUAL_ONLY) throw new Error(`unsupported invocation policy ${JSON.stringify(policy)}`);
+  const skillDirectory = join(skillsRoot, installName);
+  const skillPath = join(skillDirectory, 'SKILL.md');
+  const openaiPath = join(skillDirectory, 'agents', 'openai.yaml');
+  if (!existsSync(skillPath) || !existsSync(openaiPath)) throw new Error(`installed skill is incomplete: ${skillDirectory}`);
+  const skill = readFileSync(skillPath, 'utf8');
+  const openai = readFileSync(openaiPath, 'utf8');
+  const hasSkillPolicy = /^disable-model-invocation\s*:/m.test(frontmatterBounds(skill).body);
+  const hasOpenAiPolicy = /^policy\s*:\s*$/m.test(openai) || /^\s+allow_implicit_invocation\s*:/m.test(openai);
+  if (!hasSkillPolicy && !hasOpenAiPolicy) {
+    return { installName, policy: 'implicit', skillDirectory, changed: false };
+  }
+  const injected = Object.fromEntries(reviewedSourceInjections(skillDirectory, policy)
+    .map((entry) => [entry.relativePath, entry.contents]));
+  writeFileSync(skillPath, injected['SKILL.md']);
+  writeFileSync(openaiPath, injected['agents/openai.yaml']);
+  return { installName, policy: 'implicit', skillDirectory, changed: true };
+}
+
+export function applyInvocationPolicy({ installName, policy, skillsRoot = join(homedir(), '.agents', 'skills') }) {
+  if (!SKILL_NAME.test(installName ?? '')) throw new Error(`invalid installed skill name ${JSON.stringify(installName)}`);
+  if (policy !== MANUAL_ONLY) throw new Error(`unsupported invocation policy ${JSON.stringify(policy)}`);
+  const skillDirectory = join(skillsRoot, installName);
+  const skillPath = join(skillDirectory, 'SKILL.md');
+  if (!existsSync(skillPath)) throw new Error(`installed skill is missing: ${skillPath}`);
+  const openaiPath = join(skillDirectory, 'agents', 'openai.yaml');
+
+  const skillBefore = readFileSync(skillPath, 'utf8');
+  const skillAfter = manualOnlySkill(skillBefore);
+  if (skillAfter !== skillBefore) writeFileSync(skillPath, skillAfter);
+
+  mkdirSync(dirname(openaiPath), { recursive: true });
+  const openaiBefore = existsSync(openaiPath) ? readFileSync(openaiPath, 'utf8') : '';
+  const openaiAfter = manualOnlyOpenAi(openaiBefore);
+  if (openaiAfter !== openaiBefore) writeFileSync(openaiPath, openaiAfter);
+
+  const findings = manualOnlyPolicyFindings(skillDirectory);
+  if (findings.length > 0) throw new Error(findings.join('; '));
+  return { installName, policy, skillDirectory, changed: skillAfter !== skillBefore || openaiAfter !== openaiBefore };
+}
+
+function selectionEnablesTdd(env = process.env) {
+  const stateHome = env.XDG_STATE_HOME || join(env.HOME || homedir(), '.local', 'state');
+  const path = join(stateHome, '1aboveio-skills', 'selection.json');
+  if (!existsSync(path)) return true;
+  try {
+    const state = JSON.parse(readFileSync(path, 'utf8'));
+    if (state.tddImplicitInvocation === undefined) return true;
+    if (typeof state.tddImplicitInvocation !== 'boolean') {
+      throw new Error('tddImplicitInvocation must be a boolean');
+    }
+    return state.tddImplicitInvocation;
+  } catch (error) {
+    throw new Error(`cannot read TDD invocation selection at ${path}: ${error.message}`);
+  }
+}
+
+export function reconcileInvocationPolicy(options) {
+  return selectionEnablesTdd(options.env)
+    ? clearInvocationPolicy(options)
+    : applyInvocationPolicy(options);
+}
+
+function parseArgs(argv) {
+  const parsed = { installName: null, policy: null, skillsRoot: undefined, fromSelection: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--skill') parsed.installName = argv[++index];
+    else if (arg === '--policy') parsed.policy = argv[++index];
+    else if (arg === '--skills-root') parsed.skillsRoot = argv[++index];
+    else if (arg === '--from-selection') parsed.fromSelection = true;
+    else throw new Error(`unknown argument ${arg}`);
+  }
+  return parsed;
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    const parsed = parseArgs(process.argv.slice(2));
+    const result = parsed.fromSelection
+      ? reconcileInvocationPolicy(parsed)
+      : applyInvocationPolicy(parsed);
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stderr.write(`invocation-policy: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}