@dsalazardev/ai-hub-cli 0.2.0 → 0.3.0

package/dist/harness/memory/ledger.js

@@ -114,6 +114,44 @@ export function queryLedger(events, filter) {
     return events.filter((event) => (filter.changeId === undefined || event.changeId === filter.changeId) &&
         (filter.sessionId === undefined || event.sessionId === filter.sessionId));
 }
+const FEATURE_PREFIX = 'specs/';
+/**
+ * Feature de Spec Kit: la nombra `.planning/state.json` (`activeChange: specs/<feature>`) o,
+ * si no, el puntero local `.specify/feature.json`. Solo se referencia la ruta; nunca se copia
+ * el contenido de la feature a `.planning/`.
+ */
+async function activeFeature(root, state) {
+    if (state?.activeChange?.startsWith(FEATURE_PREFIX)) {
+        return { dir: state.activeChange.replace(/\/+$/, ''), source: 'state' };
+    }
+    if (state?.activeChange) {
+        return null;
+    }
+    const raw = await fs.readFile(path.join(root, '.specify', 'feature.json'), 'utf8').catch(() => null);
+    if (raw === null) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed.feature_directory === 'string' && parsed.feature_directory.startsWith(FEATURE_PREFIX)
+            ? { dir: parsed.feature_directory.replace(/\/+$/, ''), source: 'local' }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function countTasks(root, dir) {
+    const text = await fs.readFile(path.join(root, ...dir.split('/'), 'tasks.md'), 'utf8').catch(() => null);
+    if (text === null) {
+        return null;
+    }
+    const lines = text.split(/\r?\n/);
+    return {
+        total: lines.filter((line) => /^\s*-\s*\[[ xX]\]/.test(line)).length,
+        done: lines.filter((line) => /^\s*-\s*\[[xX]\]/.test(line)).length,
+    };
+}
 export async function resumeLedger(root) {
     const events = await readLedger(root, 1);
     const last = events.length > 0 ? events[events.length - 1] : null;
@@ -126,11 +164,15 @@ export async function resumeLedger(root) {
             throw error;
         }
     }
+    const feature = await activeFeature(root, state);
+    const featureTasks = feature === null ? null : await countTasks(root, feature.dir);
+    const tasks = featureTasks ?? state?.tasks ?? { total: 0, done: 0 };
     return {
         last,
-        activeChange: state?.activeChange ?? null,
+        activeChange: state?.activeChange ?? feature?.dir ?? null,
         phase: state?.phase ?? 'idle',
-        tasks: state?.tasks ?? { total: 0, done: 0 },
+        tasks,
         state,
+        feature: feature === null ? null : { ...feature, pending: tasks.total - tasks.done },
     };
 }

package/dist/manifest/manifest.d.ts

@@ -2,6 +2,7 @@ import { ENGINE_COUNTS, type EngineManifest } from '../engine/engine.js';
 import { type ResolvedPreset } from '../presets/resolve.js';
 import type { PresetDangerPattern } from '../presets/schema.js';
 import type { SelectionMode } from '../catalog.js';
+import { type ProjectSpeckit } from '../speckit/settings.js';
 export declare const MANIFEST_FILE = "manifest.yaml";
 export declare const INVENTORY_RELATIVE = "core/manifest.json";
 export { ENGINE_COUNTS };
@@ -58,6 +59,7 @@ export interface ProjectManifest {
     mcp?: {
         source: string;
     };
+    speckit?: ProjectSpeckit;
 }
 export declare class ManifestError extends Error {
     readonly errors: string[];
@@ -94,7 +96,7 @@ export interface ManifestInventory {
         id: string;
         lane: string;
         role: string;
-        skill: string;
+        speckit: string;
     }>;
     labels: string[];
     targets: string[];

package/dist/manifest/manifest.js

@@ -5,9 +5,10 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Ajv } from 'ajv';
 import { parse } from 'yaml';
-import { ENGINE_COUNTS, ENGINE_SKILLS_DIR, loadEngine } from '../engine/engine.js';
+import { ENGINE_COUNTS, loadEngine } from '../engine/engine.js';
 import { frontmatterString, splitFrontmatter } from '../frontmatter.js';
 import { resolvePreset } from '../presets/resolve.js';
+import { validateProjectSpeckit } from '../speckit/settings.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SCHEMA_PATH = path.join(__dirname, '..', '..', 'schema', 'manifest.schema.json');
 const ENGINE_AGENTS = path.join(__dirname, '..', '..', 'agents');
@@ -69,6 +70,18 @@ export async function loadManifestContext(root) {
     return validateManifestData(await readManifestFile(root), root);
 }
 export async function validateManifestData(data, root = process.cwd()) {
+    if (typeof data === 'object' && data !== null && 'speckit' in data) {
+        // Los campos del motor se explican antes del schema, que solo diría "additional property".
+        const record = data;
+        const targets = Array.isArray(record.targets)
+            ? record.targets.filter((item) => typeof item === 'string')
+            : [];
+        const block = record.speckit;
+        const speckitErrors = validateProjectSpeckit(block, targets, await loadEngine());
+        if (speckitErrors.length > 0) {
+            throw new ManifestError(speckitErrors);
+        }
+    }
     const validate = await validator();
     if (!validate(data)) {
         throw new ManifestError((validate.errors ?? []).map((error) => {
@@ -105,13 +118,6 @@ export async function validateManifestData(data, root = process.cwd()) {
             errors.push(`skills.publish "${skill}" no existe en ${manifest.skills.source}`);
         }
     }
-    for (const skill of new Set(engine.commands.map((command) => command.skill))) {
-        const file = path.join(ENGINE_SKILLS_DIR, skill, 'SKILL.md');
-        skillFiles.add(file);
-        if (!(await exists(file))) {
-            errors.push(`skill del motor "${skill}" no existe en ${ENGINE_SKILLS_DIR}`);
-        }
-    }
     for (const file of skillFiles) {
         if (await exists(file)) {
             await validateCatalogFile(file, errors);
@@ -160,9 +166,9 @@ export function buildInventory(manifest, engine) {
     const roles = engine.roles.map((role) => role.id).sort();
     const commands = [...engine.commands]
         .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
-        .map((command) => ({ id: command.id, lane: command.lane, role: command.role, skill: command.skill }));
+        .map((command) => ({ id: command.id, lane: command.lane, role: command.role, speckit: command.speckit }));
     const labels = [...engine.labels].sort();
-    const skills = [...new Set([...engine.commands.map((command) => command.skill), ...manifest.skills.publish])].sort();
+    const skills = [...new Set(manifest.skills.publish)].sort();
     const agents = [...manifest.agents.publish].sort();
     const rules = [...manifest.rules.publish].sort();
     return {

package/dist/presets/materialize.d.ts

@@ -24,3 +24,8 @@ export declare function materializeAgent(root: string, id: string, sourceFile?:
 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

@@ -190,3 +190,33 @@ export async function materializeCatalog(root, skillIds, agentIds) {
     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;
+}

package/dist/speckit/seal.d.ts

@@ -0,0 +1,12 @@
+/** Archivos que sella `ai::spec-ready`, dentro de `specs/<feature>/`. */
+export declare const SEALED_FILES: readonly ["plan.md", "spec.md", "tasks.md"];
+export declare class IncompleteFeatureError extends Error {
+    readonly missing: string[];
+    constructor(missing: string[]);
+}
+/**
+ * Sello SHA-256 de una feature de Spec Kit (implementación de referencia del contrato de
+ * `hermes-control`, AGENTS.md §5): rutas relativas a la raíz, ordenadas, separador `/`;
+ * por archivo `ruta + "\n" + bytes` normalizados a LF y sin BOM; SHA-256 sobre la secuencia.
+ */
+export declare function featureSeal(root: string, featureDir: string): Promise<string>;