@dsalazardev/ai-hub-cli 0.1.0 → 0.3.0

package/dist/presets/materialize.d.ts

@@ -15,4 +15,17 @@ export interface MaterializeResult {
     collisions: string[];
 }
 export declare function readScaffold(root: string): Promise<ScaffoldRecord>;
-export declare function materializePreset(root: string, preset: ResolvedPreset): Promise<MaterializeResult>;
+export declare function materializePreset(root: string, preset: ResolvedPreset, selectedRules?: string[]): Promise<MaterializeResult>;
+/** Copia una skill del catálogo o del preset a `.ai-hub/skills/<id>`. */
+export declare function materializeSkill(root: string, id: string, sourceDir?: string, sourceKey?: string): Promise<MaterializeResult>;
+/** Copia un agente del catálogo o del preset a `.ai-hub/agents/<id>.md`. */
+export declare function materializeAgent(root: string, id: string, sourceFile?: string, sourceKey?: string): Promise<MaterializeResult>;
+/** Copia las 4 rúbricas universales desde el paquete a `.ai-hub/rules/skill-quality/`. */
+export declare function materializeUniversalRules(root: string, preset: ResolvedPreset, selectedRules?: string[]): Promise<MaterializeResult>;
+/** Copia skills y agentes seleccionados del catálogo. */
+export declare function materializeCatalog(root: string, skillIds: string[], agentIds: string[]): Promise<MaterializeResult>;
+/**
+ * Borra un activo materializado solo si lo escribió ai-hub (registro de scaffold o marcador);
+ * un archivo del proyecto se conserva.
+ */
+export declare function removeOwned(root: string, relative: string, directory: boolean): Promise<void>;

package/dist/presets/materialize.js

@@ -1,10 +1,11 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { mapLimit } from '../concurrency.js';
+import { ENGINE_SKILLS_DIR } from '../engine/engine.js';
+import { ENGINE_AGENTS_DIR, ENGINE_RULES_DIR, RUBRIC_RULE_IDS, normalizeRuleId, } from '../catalog.js';
 import { sha256 } from '../sync/lock.js';
 import { findPresetAsset } from './resolve.js';
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-export const ENGINE_AGENTS = path.join(__dirname, '..', '..', 'agents');
+export const ENGINE_AGENTS = ENGINE_AGENTS_DIR;
 export const SCAFFOLD_RELATIVE = '.ai-hub/.scaffold.json';
 async function exists(file) {
     return fs.access(file).then(() => true, () => false);
@@ -38,10 +39,11 @@ export async function readScaffold(root) {
 }
 async function writeScaffold(root, record) {
     const file = path.join(root, SCAFFOLD_RELATIVE);
+    const files = Object.fromEntries(Object.entries(record.files).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)));
     await fs.mkdir(path.dirname(file), { recursive: true });
-    await fs.writeFile(file, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+    await fs.writeFile(file, `${JSON.stringify({ version: 1, files }, null, 2)}\n`, 'utf8');
 }
-async function copyOnce(root, source, destination, record, result) {
+async function copyOnce(root, source, destination, record, result, sourceKey = source) {
     const content = await fs.readFile(source, 'utf8');
     const hash = sha256(content);
     const abs = path.join(root, destination);
@@ -49,6 +51,7 @@ async function copyOnce(root, source, destination, record, result) {
         const previous = record.files[destination];
         const current = sha256(await fs.readFile(abs, 'utf8').catch(() => ''));
         if (previous && previous.sha256 === current) {
+            previous.source = sourceKey;
             result.kept.push(destination);
             return;
         }
@@ -57,18 +60,22 @@ async function copyOnce(root, source, destination, record, result) {
     }
     await fs.mkdir(path.dirname(abs), { recursive: true });
     await fs.writeFile(abs, content, 'utf8');
-    record.files[destination] = { sha256: hash, source };
+    record.files[destination] = { sha256: hash, source: sourceKey };
     result.written.push(destination);
 }
-export async function materializePreset(root, preset) {
+export async function materializePreset(root, preset, selectedRules) {
     const result = { written: [], kept: [], collisions: [] };
     const record = await readScaffold(root);
+    const wantedRules = selectedRules === undefined ? null : new Set(selectedRules);
     for (const rule of preset.rules) {
+        if (wantedRules !== null && !wantedRules.has(normalizeRuleId(rule))) {
+            continue;
+        }
         const source = await findPresetAsset(preset.chain, rule);
         if (source === null) {
             throw new Error(`el preset "${preset.id}" declara la regla "${rule}" pero no existe`);
         }
-        await copyOnce(root, source, `.ai-hub/rules/${path.basename(rule)}`, record, result);
+        await copyOnce(root, source, `.ai-hub/rules/${normalizeRuleId(rule)}.md`, record, result, `@preset/${preset.id}/${rule.replace(/\\/g, '/')}`);
     }
     for (const agent of preset.agents) {
         const fromPreset = await findPresetAsset(preset.chain, `agents/${agent}.md`);
@@ -76,13 +83,13 @@ export async function materializePreset(root, preset) {
         if (!(await exists(source))) {
             throw new Error(`el agente "${agent}" no existe ni en el preset ni en el motor`);
         }
-        await copyOnce(root, source, `.ai-hub/agents/${agent}.md`, record, result);
+        await copyOnce(root, source, `.ai-hub/agents/${agent}.md`, record, result, fromPreset ? `@preset/${preset.id}/agents/${agent}.md` : `@engine/agents/${agent}.md`);
     }
     const harness = await findPresetAsset(preset.chain, 'harness');
     if (harness !== null) {
         for (const source of await walk(harness)) {
             const relative = path.relative(harness, source).split(path.sep).join('/');
-            await copyOnce(root, source, `.ai-hub/harness/${relative}`, record, result);
+            await copyOnce(root, source, `.ai-hub/harness/${relative}`, record, result, `@preset/${preset.id}/harness/${relative}`);
         }
     }
     for (const skill of preset.skills) {
@@ -93,9 +100,123 @@ export async function materializePreset(root, preset) {
         const files = await walk(dir);
         for (const source of files) {
             const relative = path.relative(dir, source).split(path.sep).join('/');
-            await copyOnce(root, source, `.ai-hub/skills/${skill}/${relative}`, record, result);
+            await copyOnce(root, source, `.ai-hub/skills/${skill}/${relative}`, record, result, `@preset/${preset.id}/skills/${skill}/${relative}`);
         }
     }
     await writeScaffold(root, record);
     return result;
 }
+/** Copia una skill del catálogo o del preset a `.ai-hub/skills/<id>`. */
+export async function materializeSkill(root, id, sourceDir = path.join(ENGINE_SKILLS_DIR, id), sourceKey = `@engine/skills/shared/${id}`) {
+    const result = { written: [], kept: [], collisions: [] };
+    const record = await readScaffold(root);
+    if (!(await exists(sourceDir))) {
+        throw new Error(`la skill "${id}" no existe en ${sourceDir}`);
+    }
+    for (const source of await walk(sourceDir)) {
+        const relative = path.relative(sourceDir, source).split(path.sep).join('/');
+        await copyOnce(root, source, `.ai-hub/skills/${id}/${relative}`, record, result, `${sourceKey}/${relative}`);
+    }
+    await writeScaffold(root, record);
+    return result;
+}
+/** Copia un agente del catálogo o del preset a `.ai-hub/agents/<id>.md`. */
+export async function materializeAgent(root, id, sourceFile = path.join(ENGINE_AGENTS, `${id}.md`), sourceKey = `@engine/agents/${id}.md`) {
+    const result = { written: [], kept: [], collisions: [] };
+    const record = await readScaffold(root);
+    if (!(await exists(sourceFile))) {
+        throw new Error(`el agente "${id}" no existe en ${sourceFile}`);
+    }
+    await copyOnce(root, sourceFile, `.ai-hub/agents/${id}.md`, record, result, sourceKey);
+    await writeScaffold(root, record);
+    return result;
+}
+/** Copia las 4 rúbricas universales desde el paquete a `.ai-hub/rules/skill-quality/`. */
+export async function materializeUniversalRules(root, preset, selectedRules = [...RUBRIC_RULE_IDS]) {
+    const result = { written: [], kept: [], collisions: [] };
+    const record = await readScaffold(root);
+    const core = await findPresetAsset(preset.chain, 'rules/core.md');
+    if (core === null) {
+        throw new Error(`el preset "${preset.id}" no declara rules/core.md`);
+    }
+    await copyOnce(root, core, '.ai-hub/rules/core.md', record, result, `@preset/${preset.id}/rules/core.md`);
+    const wanted = new Set(selectedRules.filter((id) => id.startsWith('skill-quality/')));
+    for (const id of RUBRIC_RULE_IDS) {
+        if (!wanted.has(id)) {
+            continue;
+        }
+        const source = path.join(ENGINE_RULES_DIR, `${id}.md`);
+        if (!(await exists(source))) {
+            throw new Error(`falta la rúbrica universal "${id}" en ${ENGINE_RULES_DIR}`);
+        }
+        await copyOnce(root, source, `.ai-hub/rules/${id}.md`, record, result, `@engine/rules/${id}.md`);
+    }
+    await writeScaffold(root, record);
+    return result;
+}
+/** Copia skills y agentes seleccionados del catálogo. */
+export async function materializeCatalog(root, skillIds, agentIds) {
+    const result = { written: [], kept: [], collisions: [] };
+    const record = await readScaffold(root);
+    const copies = [];
+    for (const id of [...skillIds].sort()) {
+        const sourceDir = path.join(ENGINE_SKILLS_DIR, id);
+        if (!(await exists(sourceDir))) {
+            throw new Error(`la skill de catálogo "${id}" no existe en ${ENGINE_SKILLS_DIR}`);
+        }
+        for (const source of await walk(sourceDir)) {
+            const relative = path.relative(sourceDir, source).split(path.sep).join('/');
+            copies.push({
+                source,
+                destination: `.ai-hub/skills/${id}/${relative}`,
+                sourceKey: `@engine/skills/shared/${id}/${relative}`,
+            });
+        }
+    }
+    for (const id of [...agentIds].sort()) {
+        const source = path.join(ENGINE_AGENTS, `${id}.md`);
+        if (!(await exists(source))) {
+            throw new Error(`el agente de catálogo "${id}" no existe en ${ENGINE_AGENTS}`);
+        }
+        copies.push({
+            source,
+            destination: `.ai-hub/agents/${id}.md`,
+            sourceKey: `@engine/agents/${id}.md`,
+        });
+    }
+    await mapLimit(copies, 24, async (copy) => {
+        await copyOnce(root, copy.source, copy.destination, record, result, copy.sourceKey);
+    });
+    await writeScaffold(root, record);
+    return result;
+}
+/**
+ * Borra un activo materializado solo si lo escribió ai-hub (registro de scaffold o marcador);
+ * un archivo del proyecto se conserva.
+ */
+export async function removeOwned(root, relative, directory) {
+    const absolute = path.join(root, relative);
+    if (!(await exists(absolute))) {
+        return;
+    }
+    const record = await readScaffold(root);
+    const relativePosix = relative.split(path.sep).join('/');
+    if (directory) {
+        const files = record.files;
+        const prefix = `${relativePosix}/`;
+        const owned = Object.entries(files).filter(([name]) => name.startsWith(prefix));
+        if (owned.length === 0) {
+            const marker = await fs.readFile(path.join(absolute, 'SKILL.md'), 'utf8').catch(() => '');
+            if (!marker.includes('GENERADO por ai-hub')) {
+                return;
+            }
+        }
+        await fs.rm(absolute, { recursive: true, force: true });
+        return;
+    }
+    const text = await fs.readFile(absolute, 'utf8').catch(() => null);
+    const owned = record.files[relativePosix] !== undefined;
+    if (text === null || owned || text.includes('GENERADO por ai-hub')) {
+        await fs.rm(absolute, { force: true });
+    }
+}

package/dist/speckit/binding.d.ts

@@ -0,0 +1,15 @@
+import type { EngineManifest } from '../engine/engine.js';
+import { type ToolId } from '../sync/targets.js';
+/**
+ * Regla generada que enlaza Spec Kit con AI-Hub: roles por comando, invocación en la notación
+ * de cada destino, efecto de cada estado de salida sobre las etiquetas, rutas canónicas y sello.
+ * Se llama `ai-hub-speckit` y no `speckit-binding` porque en Pi el directorio de reglas
+ * (`.pi/prompts`) es también el de comandos de Spec Kit, donde `speckit-*` está reservado.
+ */
+export declare const BINDING_RULE_ID = "ai-hub-speckit";
+export declare const BINDING_SOURCE = "@engine/engine/engine.yaml";
+export declare const BINDING_MARKER_SOURCE = "engine/engine.yaml";
+/** Estados de salida en el orden en que aparecen en los comandos. */
+export declare function exitStates(engine: EngineManifest): string[];
+/** Cuerpo de la regla para un destino. Copilot no tiene Spec Kit y su copia no invoca comandos. */
+export declare function bindingRule(engine: EngineManifest, tool: ToolId): string;

package/dist/speckit/binding.js

@@ -0,0 +1,66 @@
+import { TARGETS } from '../sync/targets.js';
+import { invocationFor } from './commands.js';
+/**
+ * Regla generada que enlaza Spec Kit con AI-Hub: roles por comando, invocación en la notación
+ * de cada destino, efecto de cada estado de salida sobre las etiquetas, rutas canónicas y sello.
+ * Se llama `ai-hub-speckit` y no `speckit-binding` porque en Pi el directorio de reglas
+ * (`.pi/prompts`) es también el de comandos de Spec Kit, donde `speckit-*` está reservado.
+ */
+export const BINDING_RULE_ID = 'ai-hub-speckit';
+export const BINDING_SOURCE = '@engine/engine/engine.yaml';
+export const BINDING_MARKER_SOURCE = 'engine/engine.yaml';
+/** Estados de salida en el orden en que aparecen en los comandos. */
+export function exitStates(engine) {
+    const states = [];
+    for (const command of engine.commands) {
+        for (const state of command.exit) {
+            if (!states.includes(state)) {
+                states.push(state);
+            }
+        }
+    }
+    return states;
+}
+function stateTable(engine) {
+    return [
+        '## Estados de salida y etiquetas',
+        '',
+        '| Estado | Efecto sobre la etiqueta |',
+        '|---|---|',
+        ...exitStates(engine).map((state) => `| \`${state}\` | ${engine.exit_effects[state]} |`),
+        '',
+        'Ningún agente mueve una etiqueta. `hermes-control` aplica el efecto; ante `KILL` (assess-decide) o',
+        '`INVALID` (bug-assess) solo **propone** `ai::done` y un humano autorizado lo confirma.',
+        `Se mantienen las ${engine.labels.length} etiquetas: ${engine.labels.map((label) => `\`${label}\``).join(', ')}.`,
+    ];
+}
+const ARTIFACTS = [
+    '## Artefactos canónicos (rutas relativas a la raíz del repositorio)',
+    '',
+    '- Constitución: `.specify/memory/constitution.md`',
+    '- Assessment: `.specify/assessments/<slug>/{intake,research,problem,concept,decision}.md`',
+    '- Feature: `specs/<feature>/{spec,plan,tasks}.md` (Spec Kit crea `<feature>` como `NNN-slug`)',
+    '- Bug: `.specify/bugs/<slug>/{assessment,fix,test}.md`',
+];
+const SEAL = [
+    '## Sello de `ai::spec-ready`',
+    '',
+    'SHA-256 sobre `specs/<feature>/plan.md`, `specs/<feature>/spec.md` y `specs/<feature>/tasks.md`:',
+    'rutas relativas a la raíz, ordenadas, separador `/`, contenido con LF y sin BOM; por archivo',
+    '`ruta + "\\n" + bytes`. Cualquier cambio posterior invalida la aprobación y una feature con',
+    'alguno de los tres archivos ausente no se puede sellar.',
+];
+/** Cuerpo de la regla para un destino. Copilot no tiene Spec Kit y su copia no invoca comandos. */
+export function bindingRule(engine, tool) {
+    const speckit = TARGETS[tool].speckit;
+    const lines = ['# Spec Kit en AI-Hub: roles, estados y etiquetas', ''];
+    if (speckit === null) {
+        lines.push(`Este destino (${tool}) no tiene Spec Kit instalado: sus comandos no están disponibles aquí.`, 'La ejecución ocurre en un destino con Spec Kit (Claude, OpenCode, Pi o Cursor) o por la CLI de Spec Kit.', 'Esta regla solo informa de cómo se interpretan sus resultados.', '', ...stateTable(engine), '', ...ARTIFACTS, '', ...SEAL, '');
+        return lines.join('\n');
+    }
+    lines.push(`Spec Kit (\`${engine.speckit.package}\` ${engine.speckit.pin}) ejecuta los ${engine.commands.length} comandos.`, 'AI-Hub define qué rol invoca cada uno, cómo se interpreta su salida y qué etiqueta se aplica.', '', '## Comandos', '', '| Comando | Invocación | Carril | Rol | Artefactos | Estados de salida |', '|---|---|---|---|---|---|', ...engine.commands.map((command) => {
+        const roles = [command.role, ...(command.co_roles ?? [])].join(', ');
+        return `| \`${command.speckit}\` | \`${invocationFor(command.speckit, speckit.separator)}\` | ${command.lane} | ${roles} | ${command.artifacts.join(', ')} | ${command.exit.join(', ')} |`;
+    }), '', 'Un agente solo invoca los comandos asignados a su rol; un comando de otro rol se rechaza.', '', ...stateTable(engine), '', ...ARTIFACTS, '', ...SEAL, '');
+    return lines.join('\n');
+}

package/dist/speckit/commands.d.ts

@@ -0,0 +1,46 @@
+import { TARGETS } from '../sync/targets.js';
+import { type ProcessRunner } from './runner.js';
+import type { SpeckitSettings } from './settings.js';
+/** Argumentos de `uvx` que fijan el paquete y la fecha de resolución. */
+export declare function uvxPrefix(settings: SpeckitSettings): string[];
+/**
+ * Secuencia de instalación (design D3, paso 9). Cada elemento son los argumentos de `uvx`.
+ * Nunca incluye `extension add --force`: borra la extensión de la integración anterior.
+ * `integration use` registra de forma aditiva las extensiones ya instaladas.
+ */
+export declare function speckitSequence(settings: SpeckitSettings): string[][];
+export interface SpeckitEnvironment {
+    uvx: 'found' | 'missing';
+    cached: 'yes' | 'no' | 'unknown';
+    shell: 'found' | 'missing';
+    shellCommand: string;
+}
+/**
+ * Ejecuta el shell en lugar de buscarlo en el PATH: en Windows `bash` puede ser el lanzador
+ * de WSL, que existe pero no ejecuta sin una distribución instalada.
+ */
+export declare function probeShell(settings: SpeckitSettings, runner: ProcessRunner, cwd: string): Promise<{
+    ok: boolean;
+    command: string;
+}>;
+/** Sonda del entorno para el plan: describe la máquina y no entra en el hash. */
+export declare function probeEnvironment(settings: SpeckitSettings, runner: ProcessRunner, cwd: string): Promise<SpeckitEnvironment>;
+export interface PreflightResult {
+    ok: boolean;
+    problems: string[];
+}
+/**
+ * Preflight (design D3, paso 6). Se ejecuta antes de escribir cualquier archivo.
+ * Comprueba uv, la resolución de la versión fijada (caché o red) y el shell del script declarado.
+ */
+export declare function speckitPreflight(settings: SpeckitSettings, runner: ProcessRunner, cwd: string): Promise<PreflightResult>;
+export interface SpeckitRunResult {
+    ok: boolean;
+    steps: string[][];
+    failure: string | null;
+}
+/** Ejecuta la secuencia de instalación en `root`. Se detiene en el primer paso fallido. */
+export declare function runSpeckitSequence(settings: SpeckitSettings, runner: ProcessRunner, root: string): Promise<SpeckitRunResult>;
+/** Comando de Spec Kit en la notación de un destino: `/speckit-bug-assess` o `/speckit.bug.assess`. */
+export declare function invocationFor(canonical: string, separator: '-' | '.'): string;
+export declare function speckitTargetOf(tool: keyof typeof TARGETS): (typeof TARGETS)[keyof typeof TARGETS]['speckit'];

package/dist/speckit/commands.js

@@ -0,0 +1,131 @@
+import { TARGETS } from '../sync/targets.js';
+import { succeeded } from './runner.js';
+/** Argumentos de `uvx` que fijan el paquete y la fecha de resolución. */
+export function uvxPrefix(settings) {
+    return ['--from', `${settings.package}==${settings.version}`, '--exclude-newer', settings.excludeNewer, 'specify'];
+}
+/**
+ * Secuencia de instalación (design D3, paso 9). Cada elemento son los argumentos de `uvx`.
+ * Nunca incluye `extension add --force`: borra la extensión de la integración anterior.
+ * `integration use` registra de forma aditiva las extensiones ya instaladas.
+ */
+export function speckitSequence(settings) {
+    if (settings.defaultIntegration === null) {
+        return [];
+    }
+    const prefix = uvxPrefix(settings);
+    const extensions = Object.keys(settings.extensions)
+        .sort()
+        .reverse()
+        .flatMap((id) => ['--extension', id]);
+    const steps = [
+        [
+            ...prefix,
+            'init',
+            '.',
+            '--here',
+            '--force',
+            '--non-interactive',
+            '--integration',
+            settings.defaultIntegration,
+            '--script',
+            settings.script,
+            ...extensions,
+        ],
+    ];
+    for (const integration of settings.integrations.slice(1)) {
+        steps.push([...prefix, 'integration', 'install', integration, '--script', settings.script]);
+        steps.push([...prefix, 'integration', 'use', integration]);
+    }
+    if (settings.integrations.length > 1) {
+        steps.push([...prefix, 'integration', 'use', settings.defaultIntegration]);
+    }
+    return steps;
+}
+function shellCandidates(settings) {
+    return settings.script === 'ps'
+        ? [
+            { command: 'pwsh', args: ['-NoProfile', '-Command', 'echo ok'] },
+            { command: 'powershell', args: ['-NoProfile', '-Command', 'echo ok'] },
+        ]
+        : [{ command: 'bash', args: ['-c', 'echo ok'] }];
+}
+/**
+ * Ejecuta el shell en lugar de buscarlo en el PATH: en Windows `bash` puede ser el lanzador
+ * de WSL, que existe pero no ejecuta sin una distribución instalada.
+ */
+export async function probeShell(settings, runner, cwd) {
+    const candidates = shellCandidates(settings);
+    for (const candidate of candidates) {
+        const result = await runner(candidate.command, candidate.args, { cwd, timeoutMs: 30_000 });
+        if (succeeded(result) && result.stdout.trim() === 'ok') {
+            return { ok: true, command: candidate.command };
+        }
+    }
+    return { ok: false, command: candidates[0].command };
+}
+async function uvxAvailable(runner, cwd) {
+    return succeeded(await runner('uvx', ['--version'], { cwd, timeoutMs: 30_000 }));
+}
+/** Sonda del entorno para el plan: describe la máquina y no entra en el hash. */
+export async function probeEnvironment(settings, runner, cwd) {
+    const uvx = await uvxAvailable(runner, cwd);
+    let cached = 'unknown';
+    if (uvx) {
+        const offline = await runner('uvx', ['--offline', ...uvxPrefix(settings), '--version'], { cwd, timeoutMs: 60_000 });
+        cached = succeeded(offline) ? 'yes' : 'no';
+    }
+    const shell = await probeShell(settings, runner, cwd);
+    return {
+        uvx: uvx ? 'found' : 'missing',
+        cached,
+        shell: shell.ok ? 'found' : 'missing',
+        shellCommand: shell.command,
+    };
+}
+/**
+ * Preflight (design D3, paso 6). Se ejecuta antes de escribir cualquier archivo.
+ * Comprueba uv, la resolución de la versión fijada (caché o red) y el shell del script declarado.
+ */
+export async function speckitPreflight(settings, runner, cwd) {
+    const problems = [];
+    if (!(await uvxAvailable(runner, cwd))) {
+        problems.push('uv no está disponible (uvx no está en el PATH). Instálalo: https://docs.astral.sh/uv/getting-started/installation/ ' +
+            '— o repite con --no-speckit para instalar sin Spec Kit (el arnés quedará degradado).');
+        return { ok: false, problems };
+    }
+    const resolved = await runner('uvx', [...uvxPrefix(settings), '--version'], { cwd });
+    if (!succeeded(resolved)) {
+        problems.push(`no se pudo resolver ${settings.package}==${settings.version} con uvx: sin red y sin caché, o la versión no existe. ` +
+            'Ejecuta una vez con red (uvx descarga y cachea la versión fijada) o usa --no-speckit.' +
+            (resolved.stderr.trim() !== '' ? `\n${resolved.stderr.trim().split(/\r?\n/).slice(-3).join('\n')}` : ''));
+    }
+    const shell = await probeShell(settings, runner, cwd);
+    if (!shell.ok) {
+        problems.push(settings.script === 'ps'
+            ? 'PowerShell no está disponible (pwsh o powershell) y speckit.script es ps. Instala PowerShell o usa speckit.script: sh.'
+            : 'bash no está disponible o no ejecuta `bash -c "echo ok"`, y speckit.script es sh. ' +
+                'En Windows instala Git for Windows (Git Bash) y ponlo en el PATH; el lanzador de WSL sin distribución no sirve. ' +
+                'Alternativa: declara speckit.script: ps en manifest.yaml.');
+    }
+    return { ok: problems.length === 0, problems };
+}
+/** Ejecuta la secuencia de instalación en `root`. Se detiene en el primer paso fallido. */
+export async function runSpeckitSequence(settings, runner, root) {
+    const steps = speckitSequence(settings);
+    for (const step of steps) {
+        const result = await runner('uvx', step, { cwd: root });
+        if (!succeeded(result)) {
+            const detail = (result.error ?? result.stderr ?? result.stdout).trim().split(/\r?\n/).slice(-5).join('\n');
+            return { ok: false, steps, failure: `uvx ${step.join(' ')} falló (${result.status ?? 'sin código'}): ${detail}` };
+        }
+    }
+    return { ok: true, steps, failure: null };
+}
+/** Comando de Spec Kit en la notación de un destino: `/speckit-bug-assess` o `/speckit.bug.assess`. */
+export function invocationFor(canonical, separator) {
+    return `/${canonical.replace(/\./g, separator)}`;
+}
+export function speckitTargetOf(tool) {
+    return TARGETS[tool].speckit;
+}

package/dist/speckit/doctor.d.ts

@@ -0,0 +1,14 @@
+import type { EngineManifest } from '../engine/engine.js';
+import type { ProjectManifest } from '../manifest/manifest.js';
+import type { ProcessRunner } from './runner.js';
+export interface SpeckitCheck {
+    id: string;
+    ok: boolean;
+    detail: string;
+}
+/** Ids de los checks de Spec Kit, en el orden en que `doctor` los imprime. */
+export declare const SPECKIT_CHECK_IDS: readonly ["speckit:managed", "speckit:installed", "speckit:version", "speckit:shell", "speckit:integrations", "speckit:extensions", "speckit:integrity", "speckit:collision", "speckit:constitution", "speckit:versioning"];
+/** Checks de doctor para una instalación (dev-cli "Doctor verifies the Spec Kit installation"). */
+export declare function speckitDoctorChecks(root: string, manifest: ProjectManifest, engine: EngineManifest, runner: ProcessRunner): Promise<SpeckitCheck[]>;
+/** En el checkout del motor los checks de Spec Kit no aplican: su .specify/ es del mantenedor. */
+export declare function speckitNotApplicable(): SpeckitCheck[];

package/dist/speckit/doctor.js

@@ -0,0 +1,103 @@
+import { spawnSync } from 'node:child_process';
+import { readLock } from '../sync/lock.js';
+import { probeShell } from './commands.js';
+import { effectiveSpeckit } from './settings.js';
+import { checkExtensions, checkIntegrations, checkIntegrity, constitutionIsTemplate, inReservedNamespace, readSpeckitState, speckitOwnedPaths, } from './state.js';
+/** Ids de los checks de Spec Kit, en el orden en que `doctor` los imprime. */
+export const SPECKIT_CHECK_IDS = [
+    'speckit:managed',
+    'speckit:installed',
+    'speckit:version',
+    'speckit:shell',
+    'speckit:integrations',
+    'speckit:extensions',
+    'speckit:integrity',
+    'speckit:collision',
+    'speckit:constitution',
+    'speckit:versioning',
+];
+/** Estado de Spec Kit que el consumidor debe versionar: si git lo ignora, se pierde. */
+const VERSIONED_STATE = ['.specify/memory/constitution.md', '.specify/init-options.json', 'specs/'];
+function list(items, limit = 5) {
+    return items.slice(0, limit).join('; ') + (items.length > limit ? ` (+${items.length - limit})` : '');
+}
+function gitIgnored(root, rel) {
+    const inside = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: root, encoding: 'utf8', shell: false });
+    if (inside.status !== 0 || (inside.stdout ?? '').trim() !== 'true') {
+        return null;
+    }
+    const result = spawnSync('git', ['check-ignore', '-q', '--no-index', rel], { cwd: root, encoding: 'utf8', shell: false });
+    return result.status === 0;
+}
+/** Checks de doctor para una instalación (dev-cli "Doctor verifies the Spec Kit installation"). */
+export async function speckitDoctorChecks(root, manifest, engine, runner) {
+    const checks = [];
+    const add = (id, ok, detail) => {
+        checks.push({ id, ok, detail });
+    };
+    const settings = effectiveSpeckit(manifest, engine);
+    const copilot = manifest.targets.includes('copilot');
+    if (!settings.managed) {
+        add('speckit:managed', false, 'degradado: speckit.managed es false (--no-speckit); ejecuta ai-hub install para instalar Spec Kit');
+        for (const id of SPECKIT_CHECK_IDS.slice(1)) {
+            add(id, true, 'no aplica: Spec Kit no gestionado');
+        }
+        return checks;
+    }
+    add('speckit:managed', true, `gestionado: ${settings.package} ${settings.version} vía uvx`);
+    const state = await readSpeckitState(root);
+    add('speckit:installed', state.initOptions !== null, state.initOptions !== null ? '.specify/init-options.json presente' : 'falta .specify/init-options.json; ejecuta ai-hub install');
+    const installed = state.initOptions?.speckit_version;
+    add('speckit:version', installed === settings.version, installed === settings.version
+        ? `${installed}`
+        : `instalada ${installed ?? '(ninguna)'}; se esperaba ${settings.version}; ejecuta ai-hub install`);
+    const shell = await probeShell(settings, runner, root);
+    add('speckit:shell', shell.ok, shell.ok
+        ? `${shell.command} ejecuta los scripts ${settings.script}`
+        : settings.script === 'ps'
+            ? 'PowerShell (pwsh o powershell) no está disponible para los scripts ps'
+            : 'bash no está disponible o no ejecuta; en Windows instala Git Bash, o declara speckit.script: ps');
+    const integrations = checkIntegrations(settings, state);
+    add('speckit:integrations', integrations.length === 0, integrations.length === 0
+        ? `${settings.integrations.join(', ')} (por defecto ${settings.defaultIntegration ?? '-'})`
+        : list(integrations));
+    if (copilot) {
+        add('speckit:targets', true, 'copilot: sin Spec Kit (recibe agentes y reglas de AI-Hub; sus comandos se ejecutan en otro destino)');
+    }
+    const extensions = await checkExtensions(root, settings, state);
+    add('speckit:extensions', extensions.length === 0, extensions.length === 0
+        ? Object.entries(settings.extensions)
+            .map(([id, version]) => `${id} ${version}`)
+            .join(', ') + ` en ${settings.targets.length} destinos`
+        : list(extensions));
+    const integrity = await checkIntegrity(root, state);
+    add('speckit:integrity', integrity.missing.length === 0, integrity.missing.length > 0
+        ? `faltan ${integrity.missing.length} archivos de Spec Kit: ${list(integrity.missing)}; ejecuta ai-hub install`
+        : integrity.modified.length > 0
+            ? `aviso: ${integrity.modified.length} archivos de Spec Kit modificados; el próximo init los sobrescribe (usa overrides): ${list(integrity.modified)}`
+            : `${integrity.checked} archivos de Spec Kit íntegros`);
+    const owned = await speckitOwnedPaths(root, manifest.targets);
+    const lock = await readLock(root).catch(() => null);
+    const shared = Object.keys(lock?.files ?? {})
+        .filter((rel) => owned.has(rel) || (state.present && inReservedNamespace(rel, manifest.targets)))
+        .sort();
+    add('speckit:collision', shared.length === 0, shared.length === 0 ? 'ninguna ruta de sync.lock.json pertenece a Spec Kit' : `rutas compartidas con Spec Kit: ${list(shared)}`);
+    const template = await constitutionIsTemplate(root);
+    add('speckit:constitution', true, template === true
+        ? 'aviso: la constitución sigue siendo la plantilla; ejecuta /speckit.constitution'
+        : template === null
+            ? 'aviso: no hay .specify/memory/constitution.md'
+            : 'constitución propia del proyecto');
+    const ignored = VERSIONED_STATE.filter((rel) => gitIgnored(root, rel) === true);
+    const applicable = gitIgnored(root, VERSIONED_STATE[0]) !== null;
+    add('speckit:versioning', ignored.length === 0, !applicable
+        ? 'no aplica (sin repositorio git)'
+        : ignored.length === 0
+            ? 'constitución, init-options.json y specs/ versionables'
+            : `git ignora estado del proyecto: ${ignored.join(', ')}; quítalo de .gitignore`);
+    return checks;
+}
+/** En el checkout del motor los checks de Spec Kit no aplican: su .specify/ es del mantenedor. */
+export function speckitNotApplicable() {
+    return SPECKIT_CHECK_IDS.map((id) => ({ id, ok: true, detail: 'no aplica en el checkout del motor' }));
+}

package/dist/speckit/runner.d.ts

@@ -0,0 +1,19 @@
+export interface RunResult {
+    /** Código de salida; `null` si el proceso no llegó a ejecutarse o fue interrumpido. */
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    /** Error de arranque (por ejemplo `ENOENT` cuando el ejecutable no existe). */
+    error?: string;
+}
+export interface RunOptions {
+    cwd: string;
+    timeoutMs?: number;
+}
+/**
+ * Ejecuta un proceso externo. Los argumentos viajan como array, nunca a través de un shell,
+ * para que las rutas con espacios no se interpreten. La entrada estándar se cierra.
+ */
+export type ProcessRunner = (command: string, args: string[], options: RunOptions) => Promise<RunResult>;
+export declare const defaultRunner: ProcessRunner;
+export declare function succeeded(result: RunResult): boolean;

package/dist/speckit/runner.js

@@ -0,0 +1,22 @@
+import { spawnSync } from 'node:child_process';
+const DEFAULT_TIMEOUT_MS = 300_000;
+export const defaultRunner = async (command, args, options) => {
+    const result = spawnSync(command, args, {
+        cwd: options.cwd,
+        shell: false,
+        encoding: 'utf8',
+        input: '',
+        windowsHide: true,
+        timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        env: { ...process.env, PYTHONIOENCODING: 'utf-8', NO_COLOR: '1' },
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        ...(result.error ? { error: result.error.message } : {}),
+    };
+};
+export function succeeded(result) {
+    return result.error === undefined && result.status === 0;
+}