@kuyper/harness 0.1.0

package/dist/capabilities.js

@@ -0,0 +1,361 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseDocument } from 'yaml';
+import { isTempPath } from './atomicWrite.js';
+import { isValidCapabilityName, normalizeLineEndings } from './lock.js';
+export class CapabilityValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(issues.map((i) => `${i.path}: ${i.message}`).join('\n'));
+        this.issues = issues;
+        this.name = 'CapabilityValidationError';
+    }
+}
+/** `undefined` quando o texto não começa com `---` na primeira linha. */
+export function splitFrontmatter(normalizedText) {
+    const lines = normalizedText.split('\n');
+    if (lines[0] !== '---')
+        return undefined;
+    let closeIndex = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i] === '---') {
+            closeIndex = i;
+            break;
+        }
+    }
+    if (closeIndex === -1)
+        return undefined;
+    return {
+        yamlText: lines.slice(1, closeIndex).join('\n'),
+        body: lines.slice(closeIndex + 1).join('\n'),
+    };
+}
+export function parseFrontmatterYaml(yamlText) {
+    const doc = parseDocument(yamlText);
+    if (doc.errors.length > 0) {
+        return { error: doc.errors[0]?.message ?? 'YAML malformado' };
+    }
+    const data = doc.toJS() ?? {};
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        return { error: 'frontmatter não é um mapa' };
+    }
+    return { data: data };
+}
+/**
+ * Normalização de corpo para a **materialização da rule** (SPEC §3): linhas
+ * vazias no início e no fim removidas, exatamente um LF no final. Não se
+ * aplica a skills — o `SKILL.md` é copiado inteiro (§4/§6), só com LF e um
+ * único newline final.
+ */
+export function normalizeRuleBody(body) {
+    const lines = body.split('\n');
+    let start = 0;
+    while (start < lines.length && lines[start].trim() === '')
+        start++;
+    let end = lines.length;
+    while (end > start && lines[end - 1].trim() === '')
+        end--;
+    const trimmed = lines.slice(start, end).join('\n');
+    return trimmed.length > 0 ? `${trimmed}\n` : '';
+}
+/** Só LF, com exatamente um newline final — usado para copiar o `SKILL.md` inteiro. */
+export function normalizeWholeFile(text) {
+    const normalized = normalizeLineEndings(text);
+    return `${normalized.replace(/\n+$/u, '')}\n`;
+}
+const RULE_FRONTMATTER_KEYS = new Set(['title', 'replaces']);
+function parseRuleFile(sourcePath, name, origin, raw) {
+    const normalized = normalizeLineEndings(raw);
+    const split = splitFrontmatter(normalized);
+    if (!split) {
+        return { path: sourcePath, message: 'frontmatter ausente ou malformado — o arquivo precisa começar com "---"' };
+    }
+    const parsed = parseFrontmatterYaml(split.yamlText);
+    if ('error' in parsed) {
+        return { path: sourcePath, message: `frontmatter inválido: ${parsed.error}` };
+    }
+    const unknown = Object.keys(parsed.data).filter((k) => !RULE_FRONTMATTER_KEYS.has(k));
+    if (unknown.length > 0) {
+        return { path: sourcePath, message: `campo desconhecido: ${unknown.join(', ')}` };
+    }
+    const title = parsed.data['title'];
+    if (typeof title !== 'string' || title.trim().length === 0 || title.includes('\n')) {
+        return { path: sourcePath, message: 'title ausente, vazio ou com múltiplas linhas' };
+    }
+    const replacesRaw = parsed.data['replaces'];
+    let replaces;
+    if (replacesRaw !== undefined) {
+        if (origin === 'core') {
+            return { path: sourcePath, message: 'replaces não é permitido em rule do core' };
+        }
+        if (typeof replacesRaw !== 'string' || !/^core:[a-z0-9]+(-[a-z0-9]+)*$/.test(replacesRaw)) {
+            return { path: sourcePath, message: `replaces inválido: ${JSON.stringify(replacesRaw)} (esperado core:<nome>)` };
+        }
+        replaces = replacesRaw;
+    }
+    const body = normalizeRuleBody(split.body);
+    if (body.length === 0) {
+        return { path: sourcePath, message: 'corpo vazio' };
+    }
+    return { name, origin, title, replaces, body, sourcePath };
+}
+/** Descobre `<raiz>/rules/*.md`, um nível, ignorando `.kuyper-tmp`. */
+export async function discoverRules(rulesDir, origin) {
+    const items = [];
+    const issues = [];
+    let entries;
+    try {
+        entries = await readdir(rulesDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { items, issues };
+        throw err;
+    }
+    for (const entry of entries) {
+        if (isTempPath(entry.name))
+            continue;
+        const fullPath = join(rulesDir, entry.name);
+        if (!entry.isFile() || !entry.name.endsWith('.md')) {
+            issues.push({ path: fullPath, message: 'estrutura inesperada em rules/ — só arquivos <nome>.md são aceitos' });
+            continue;
+        }
+        const name = entry.name.slice(0, -'.md'.length);
+        if (!isValidCapabilityName(name)) {
+            issues.push({ path: fullPath, message: `nome inválido: ${name}` });
+            continue;
+        }
+        const raw = await readFile(fullPath, 'utf8');
+        const result = parseRuleFile(fullPath, name, origin, raw);
+        if ('name' in result)
+            items.push(result);
+        else
+            issues.push(result);
+    }
+    return { items, issues };
+}
+const SKILL_FRONTMATTER_KEYS = new Set(['name', 'description', 'replaces']);
+const SKILL_MD = 'SKILL.md';
+const SCRIPTS_DIR = 'scripts';
+function isBinary(buf) {
+    const scanLength = Math.min(buf.length, 8000);
+    for (let i = 0; i < scanLength; i++) {
+        if (buf[i] === 0)
+            return true;
+    }
+    return false;
+}
+async function collectScripts(scriptsDir, prefix, issues) {
+    const out = [];
+    let entries;
+    try {
+        entries = await readdir(scriptsDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return out;
+        throw err;
+    }
+    for (const entry of entries) {
+        if (isTempPath(entry.name))
+            continue;
+        const relPath = `${prefix}${entry.name}`;
+        const fullPath = join(scriptsDir, entry.name);
+        if (entry.isSymbolicLink()) {
+            issues.push({ path: fullPath, message: 'symlink não é permitido dentro de scripts/' });
+            continue;
+        }
+        if (entry.isDirectory()) {
+            out.push(...(await collectScripts(fullPath, `${relPath}/`, issues)));
+            continue;
+        }
+        if (!entry.isFile()) {
+            issues.push({ path: fullPath, message: 'tipo de arquivo não suportado em scripts/' });
+            continue;
+        }
+        const stats = await stat(fullPath);
+        const raw = await readFile(fullPath);
+        if (isBinary(raw)) {
+            issues.push({ path: fullPath, message: 'arquivo binário não é permitido em scripts/' });
+            continue;
+        }
+        const normalized = normalizeWholeFile(raw.toString('utf8'));
+        out.push({ relPath, content: Buffer.from(normalized, 'utf8'), mode: stats.mode & 0o777 });
+    }
+    return out;
+}
+async function parseSkillDir(sourceDir, name, origin) {
+    const issues = [];
+    let entries;
+    try {
+        entries = await readdir(sourceDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [{ path: sourceDir, message: 'diretório da skill não existe' }];
+        throw err;
+    }
+    let hasSkillMd = false;
+    for (const entry of entries) {
+        if (isTempPath(entry.name))
+            continue;
+        if (entry.name === SKILL_MD && entry.isFile()) {
+            hasSkillMd = true;
+            continue;
+        }
+        if (entry.name === SCRIPTS_DIR && entry.isDirectory())
+            continue;
+        issues.push({
+            path: join(sourceDir, entry.name),
+            message: `estrutura inesperada na skill — só ${SKILL_MD} e ${SCRIPTS_DIR}/ são aceitos (sensível a maiúsculas)`,
+        });
+    }
+    if (!hasSkillMd) {
+        issues.push({ path: join(sourceDir, SKILL_MD), message: `${SKILL_MD} ausente` });
+    }
+    if (issues.length > 0)
+        return issues;
+    const skillMdPath = join(sourceDir, SKILL_MD);
+    const raw = await readFile(skillMdPath, 'utf8');
+    const normalized = normalizeLineEndings(raw);
+    const split = splitFrontmatter(normalized);
+    if (!split) {
+        return [{ path: skillMdPath, message: 'frontmatter ausente ou malformado — o arquivo precisa começar com "---"' }];
+    }
+    const parsed = parseFrontmatterYaml(split.yamlText);
+    if ('error' in parsed) {
+        return [{ path: skillMdPath, message: `frontmatter inválido: ${parsed.error}` }];
+    }
+    const unknown = Object.keys(parsed.data).filter((k) => !SKILL_FRONTMATTER_KEYS.has(k));
+    if (unknown.length > 0) {
+        return [{ path: skillMdPath, message: `campo desconhecido: ${unknown.join(', ')}` }];
+    }
+    const skillNameRaw = parsed.data['name'];
+    const skillIssues = [];
+    if (typeof skillNameRaw !== 'string' || skillNameRaw.length < 1 || skillNameRaw.length > 64) {
+        skillIssues.push({ path: skillMdPath, message: 'name ausente ou fora de 1–64 caracteres' });
+    }
+    else if (skillNameRaw !== name) {
+        skillIssues.push({ path: skillMdPath, message: `name (${skillNameRaw}) diverge do diretório (${name})` });
+    }
+    const descriptionRaw = parsed.data['description'];
+    if (typeof descriptionRaw !== 'string' ||
+        descriptionRaw.trim().length === 0 ||
+        descriptionRaw.length > 1024 ||
+        descriptionRaw.includes('\n')) {
+        skillIssues.push({ path: skillMdPath, message: 'description ausente, vazia, multi-linha ou maior que 1024 caracteres' });
+    }
+    const replacesRaw = parsed.data['replaces'];
+    let replaces;
+    if (replacesRaw !== undefined) {
+        if (origin === 'core') {
+            skillIssues.push({ path: skillMdPath, message: 'replaces não é permitido em skill do core' });
+        }
+        else if (typeof replacesRaw !== 'string' || !isValidCapabilityName(replacesRaw)) {
+            skillIssues.push({ path: skillMdPath, message: `replaces inválido: ${JSON.stringify(replacesRaw)} (esperado o nome puro de uma skill, sem prefixo core:)` });
+        }
+        else {
+            replaces = replacesRaw;
+        }
+    }
+    const bodyTrimmed = split.body
+        .split('\n')
+        .filter((l) => l.trim() !== '')
+        .join('');
+    if (bodyTrimmed.length === 0) {
+        skillIssues.push({ path: skillMdPath, message: 'corpo Markdown vazio' });
+    }
+    if (skillIssues.length > 0)
+        return skillIssues;
+    const scripts = await collectScripts(join(sourceDir, SCRIPTS_DIR), `${SCRIPTS_DIR}/`, issues);
+    if (issues.length > 0)
+        return issues;
+    return {
+        name,
+        origin,
+        skillName: skillNameRaw,
+        description: descriptionRaw,
+        replaces,
+        normalizedSkillMd: normalizeWholeFile(raw),
+        scripts,
+        sourceDir,
+    };
+}
+/** Descobre `<raiz>/skills/<nome>/`, um nível, ignorando `.kuyper-tmp`. */
+export async function discoverSkills(skillsDir, origin) {
+    const items = [];
+    const issues = [];
+    let entries;
+    try {
+        entries = await readdir(skillsDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { items, issues };
+        throw err;
+    }
+    for (const entry of entries) {
+        if (isTempPath(entry.name))
+            continue;
+        const fullPath = join(skillsDir, entry.name);
+        if (!entry.isDirectory()) {
+            issues.push({ path: fullPath, message: 'estrutura inesperada em skills/ — só diretórios <nome>/ são aceitos' });
+            continue;
+        }
+        if (!isValidCapabilityName(entry.name)) {
+            issues.push({ path: fullPath, message: `nome inválido: ${entry.name}` });
+            continue;
+        }
+        const result = await parseSkillDir(fullPath, entry.name, origin);
+        if (Array.isArray(result))
+            issues.push(...result);
+        else
+            items.push(result);
+    }
+    return { items, issues };
+}
+// ---------------------------------------------------------------------------
+// Materialização das rules (SPEC §5)
+// ---------------------------------------------------------------------------
+const INSTRUCTION_HEADER = '<!-- gerado por @kuyper/harness — não editar -->';
+/**
+ * Filtra as rules do core apontadas por `replaces:`, ordena core e projeto
+ * separadamente por nome (ASCII, sem locale) e concatena core primeiro.
+ */
+export function compileInstructionFile(coreRules, projectRules) {
+    const replaced = new Set(projectRules.map((r) => r.replaces).filter((r) => r !== undefined).map((r) => r.slice('core:'.length)));
+    const effectiveCore = coreRules.filter((r) => !replaced.has(r.name)).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const effectiveProject = [...projectRules].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const sections = [...effectiveCore, ...effectiveProject].map((r) => `## ${r.title}\n\n${r.body}`);
+    return `${INSTRUCTION_HEADER}\n\n${sections.join('\n')}`;
+}
+// ---------------------------------------------------------------------------
+// Lista de roteamento de skills (SPEC §7) — sem fonte, computada toda vez.
+// ---------------------------------------------------------------------------
+const SKILL_ROUTING_TITLE = 'Quais skills usar';
+/**
+ * A primeira frase da `description` — não a `description` inteira. O campo
+ * existe pensando em quem decide invocar a skill sozinha ("o que faz e
+ * quando usar", SPEC §4); a lista de roteamento é uma linha por skill, então
+ * a cláusula de "quando usar" (a segunda frase, por convenção) sobra: já é o
+ * próprio propósito da lista.
+ */
+function firstSentence(description) {
+    const match = /^[^.]*\.?/u.exec(description);
+    return (match?.[0] ?? description).trim();
+}
+/**
+ * Uma linha por skill ativa. Skill de projeto com `replaces: <nome>` tira a
+ * linha da skill `<nome>` do core desta lista — a skill em si continua sendo
+ * copiada para os providers (§6); só a recomendação muda. Sem fonte em disco,
+ * então a validação de referência (R9/R10) fica em `checkReferences`
+ * (`generate.ts`), que já cobre o mesmo caso para rule.
+ */
+export function compileSkillRoutingSection(coreSkills, projectSkills) {
+    const replacedNames = new Set(projectSkills.map((s) => s.replaces).filter((r) => r !== undefined));
+    const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    const effectiveCore = coreSkills.filter((s) => !replacedNames.has(s.name)).sort(byName);
+    const effectiveProject = [...projectSkills].sort(byName);
+    const lines = [...effectiveCore, ...effectiveProject].map((s) => `- ${firstSentence(s.description)} → skill \`${s.name}\``);
+    return `## ${SKILL_ROUTING_TITLE}\n\n${lines.join('\n')}\n`;
+}

package/dist/capabilityCommands.js

@@ -0,0 +1,285 @@
+import { execFile } from 'node:child_process';
+import { cp, lstat, mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { writeFileAtomic } from './atomicWrite.js';
+import { KuyperRefusal } from './errors.js';
+import { generate } from './generate.js';
+import { getCoreHooksPath, setCoreHooksPath } from './hooks.js';
+import { isValidCapabilityName } from './lock.js';
+const execFileAsync = promisify(execFile);
+const PROJECT_COPY_PATHS = ['.kuyper', '.claude', '.agents', 'CLAUDE.md', 'AGENTS.md'];
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+}
+function usage(kind, detail) {
+    throw new KuyperRefusal({
+        headline: `Uso incompleto de kuyper ${kind}.`,
+        details: [detail],
+        route: [
+            `pnpm exec kuyper ${kind} create <nome> --from <arquivo|-> [--dry-run]`,
+            `pnpm exec kuyper ${kind} edit <nome> [--from <arquivo|->] [--dry-run]`,
+            `pnpm exec kuyper ${kind} delete <nome> [--dry-run]`,
+        ],
+    });
+}
+function parseArgs(kind, args) {
+    const positionals = [];
+    let from;
+    let dryRun = false;
+    for (let index = 0; index < args.length; index++) {
+        const value = args[index];
+        if (value === '--dry-run') {
+            if (dryRun)
+                usage(kind, '--dry-run foi informado mais de uma vez.');
+            dryRun = true;
+            continue;
+        }
+        if (value === '--from') {
+            if (from !== undefined)
+                usage(kind, '--from foi informado mais de uma vez.');
+            const next = args[index + 1];
+            if (next === undefined || next.startsWith('--'))
+                usage(kind, '--from exige um arquivo ou "-" para stdin.');
+            from = next;
+            index++;
+            continue;
+        }
+        if (value.startsWith('--'))
+            usage(kind, `Opção desconhecida: ${value}`);
+        positionals.push(value);
+    }
+    const [actionRaw, name, ...extra] = positionals;
+    if (actionRaw !== 'create' && actionRaw !== 'edit' && actionRaw !== 'delete') {
+        usage(kind, 'A ação precisa ser create, edit ou delete.');
+    }
+    if (name === undefined || extra.length > 0)
+        usage(kind, 'Informe exatamente um nome de capacidade.');
+    if (actionRaw === 'create' && from === undefined)
+        usage(kind, 'create exige --from <arquivo|->.');
+    if (actionRaw === 'delete' && from !== undefined)
+        usage(kind, 'delete não aceita --from.');
+    return { action: actionRaw, name, from, dryRun };
+}
+function sourceRelPath(kind, origin, name) {
+    return kind === 'rule'
+        ? join('.kuyper', origin, 'rules', `${name}.md`)
+        : join('.kuyper', origin, 'skills', name);
+}
+function canonicalFilePath(kind, sourcePath) {
+    return kind === 'rule' ? sourcePath : join(sourcePath, 'SKILL.md');
+}
+function refuseInvalidName(kind, name) {
+    const extra = kind === 'skill' ? ' e ter no máximo 64 caracteres' : '';
+    throw new KuyperRefusal({
+        code: 'R25',
+        headline: 'O nome da capacidade é inválido.',
+        details: [`recebido: ${name}`, `esperado: ^[a-z0-9]+(-[a-z0-9]+)*$${extra}`],
+        route: [`Escolha outro nome e rode kuyper ${kind} novamente.`],
+    });
+}
+function refuseCore(action, kind, name, code) {
+    const verb = action === 'create' ? 'já pertence' : 'pertence';
+    throw new KuyperRefusal({
+        code,
+        headline: `core:${name} ${verb} ao Harness.`,
+        details: [
+            action === 'create'
+                ? `Não é possível criar uma ${kind} do projeto com o mesmo nome.`
+                : `Não é possível ${action === 'edit' ? 'editar' : 'remover'} uma capacidade core.`,
+        ],
+        route: [
+            kind === 'rule'
+                ? 'Crie uma rule do projeto com outro nome e declare replaces: core:<nome> no frontmatter.'
+                : 'Crie uma skill do projeto com outro nome; para trocar a recomendação, declare replaces: <nome> no frontmatter.',
+        ],
+    });
+}
+function refuseProjectExists(kind, name) {
+    throw new KuyperRefusal({
+        code: 'R9',
+        headline: `A ${kind} ${name} já existe no projeto.`,
+        route: [`Use kuyper ${kind} edit ${name} para revalidar ou substituir o arquivo canônico.`],
+    });
+}
+function refuseMissing(kind, name) {
+    throw new KuyperRefusal({
+        code: 'R13',
+        headline: `A ${kind} ${name} não existe.`,
+        route: [`Crie com kuyper ${kind} create ${name} --from <arquivo|->.`],
+    });
+}
+async function copyIfPresent(from, to) {
+    if (!(await exists(from)))
+        return;
+    await cp(from, to, { recursive: true, preserveTimestamps: true });
+}
+async function createShadow(projectRoot) {
+    const shadow = await mkdtemp(join(tmpdir(), 'kuyper-capability-'));
+    try {
+        for (const relPath of PROJECT_COPY_PATHS) {
+            await copyIfPresent(join(projectRoot, relPath), join(shadow, relPath));
+        }
+        await execFileAsync('git', ['init', '-q'], { cwd: shadow });
+        const hooksPath = await getCoreHooksPath(projectRoot);
+        if (hooksPath !== undefined)
+            await setCoreHooksPath(shadow, hooksPath);
+        return shadow;
+    }
+    catch (err) {
+        await rm(shadow, { recursive: true, force: true });
+        throw err;
+    }
+}
+async function readInput(kind, parsed, projectRoot, options) {
+    if (parsed.from === undefined)
+        return undefined;
+    if (parsed.from === '-') {
+        if (options.readStdin === undefined)
+            usage(kind, '--from - exige conteúdo em stdin.');
+        return options.readStdin();
+    }
+    try {
+        return await readFile(resolve(projectRoot, parsed.from), 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new KuyperRefusal({
+                headline: 'O arquivo informado em --from não existe.',
+                details: [parsed.from],
+                route: [`Crie o arquivo canônico completo e rode kuyper ${kind} novamente.`],
+            });
+        }
+        throw err;
+    }
+}
+async function applyMutation(root, kind, action, name, input) {
+    const source = join(root, sourceRelPath(kind, 'project', name));
+    if (action === 'delete') {
+        await rm(source, { recursive: true, force: true });
+        return;
+    }
+    if (input !== undefined) {
+        await writeFileAtomic(canonicalFilePath(kind, source), input);
+    }
+}
+function affectedPaths(report) {
+    return [...new Set([...report.written, ...report.removed])].sort();
+}
+function remapShadowRefusal(err, shadow, projectRoot) {
+    const remap = (value) => value.split(shadow).join(projectRoot);
+    return new KuyperRefusal({
+        ...(err.opts.code !== undefined ? { code: err.opts.code } : {}),
+        headline: remap(err.opts.headline),
+        ...(err.opts.details !== undefined ? { details: err.opts.details.map(remap) } : {}),
+        ...(err.opts.route !== undefined ? { route: err.opts.route.map(remap) } : {}),
+    });
+}
+function formatReport(kind, parsed, report) {
+    const paths = affectedPaths(report);
+    const actionText = parsed.action === 'create' ? 'criada' : parsed.action === 'edit' ? 'editada' : 'removida';
+    const prefix = parsed.dryRun ? '○  dry-run:' : '✓ ';
+    const verb = parsed.dryRun ? `seria ${actionText}` : actionText;
+    const noChange = parsed.action === 'edit' && paths.length === 0;
+    const lines = [noChange ? `${prefix} ${kind} ${parsed.name}: nada mudou.` : `${prefix} ${kind} ${parsed.name} ${verb}.`];
+    if (paths.length > 0) {
+        lines.push('');
+        for (const path of paths)
+            lines.push(`   ${path}`);
+    }
+    if (parsed.dryRun)
+        lines.push('', '   achados: nenhum; nenhum arquivo foi alterado.');
+    if (parsed.action === 'create' && kind === 'skill') {
+        lines.push('', `   Para usar: "use a skill ${parsed.name} para ..."`);
+    }
+    return lines.join('\n');
+}
+async function rollbackSource(actualSource, backup, existedBefore) {
+    await rm(actualSource, { recursive: true, force: true });
+    if (existedBefore) {
+        await mkdir(dirname(actualSource), { recursive: true });
+        await cp(backup, actualSource, { recursive: true, preserveTimestamps: true });
+    }
+}
+/**
+ * PRD §3.7 / SPEC formato-canônico §8. A mutação é primeiro aplicada numa
+ * cópia de disco e passa pelo `generate` real. Só depois desse preflight a
+ * fonte verdadeira muda; o comando não mantém uma segunda implementação das
+ * validações de R7–R10/R25.
+ */
+export async function runCapabilityCommand(kind, args, options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const parsed = parseArgs(kind, args);
+    if (!isValidCapabilityName(parsed.name) || (kind === 'skill' && parsed.name.length > 64)) {
+        refuseInvalidName(kind, parsed.name);
+    }
+    const coreSource = join(projectRoot, sourceRelPath(kind, 'core', parsed.name));
+    const projectSource = join(projectRoot, sourceRelPath(kind, 'project', parsed.name));
+    const [coreExists, projectExists] = await Promise.all([exists(coreSource), exists(projectSource)]);
+    if (parsed.action === 'create') {
+        if (coreExists)
+            refuseCore(parsed.action, kind, parsed.name, 'R12');
+        if (projectExists)
+            refuseProjectExists(kind, parsed.name);
+    }
+    else {
+        if (!projectExists && coreExists)
+            refuseCore(parsed.action, kind, parsed.name, 'R11');
+        if (!projectExists)
+            refuseMissing(kind, parsed.name);
+    }
+    const input = await readInput(kind, parsed, projectRoot, options);
+    const shadow = await createShadow(projectRoot);
+    const backup = join(shadow, '.source-backup');
+    const print = options.print ?? console.log;
+    try {
+        await applyMutation(shadow, kind, parsed.action, parsed.name, input);
+        let preview;
+        try {
+            preview = await generate({
+                projectRoot: shadow,
+                ...(options.packageCoreDir !== undefined ? { packageCoreDir: options.packageCoreDir } : {}),
+                silent: true,
+            });
+        }
+        catch (err) {
+            if (err instanceof KuyperRefusal)
+                throw remapShadowRefusal(err, shadow, projectRoot);
+            throw err;
+        }
+        if (parsed.dryRun) {
+            print(formatReport(kind, parsed, preview));
+            return 0;
+        }
+        const existedBefore = await exists(projectSource);
+        if (existedBefore)
+            await cp(projectSource, backup, { recursive: true, preserveTimestamps: true });
+        await applyMutation(projectRoot, kind, parsed.action, parsed.name, input);
+        let report;
+        try {
+            report = await generate({
+                projectRoot,
+                ...(options.packageCoreDir !== undefined ? { packageCoreDir: options.packageCoreDir } : {}),
+                silent: true,
+            });
+        }
+        catch (err) {
+            await rollbackSource(projectSource, backup, existedBefore);
+            throw err;
+        }
+        print(formatReport(kind, parsed, report));
+        return 0;
+    }
+    finally {
+        await rm(shadow, { recursive: true, force: true });
+    }
+}