@dsalazardev/ai-hub-cli 0.3.0 → 0.3.1

package/README.md

@@ -95,6 +95,7 @@ ejecuta Python ni `uvx`. En el checkout del motor todos informan `no aplica`.
 | `speckit:managed` | `speckit.managed` no es `false`; un arnés con `--no-speckit` es **degradado** y `doctor` sale 1 | `ai-hub install` (sin `--no-speckit`) |
 | `speckit:installed` | Existe `.specify/init-options.json` | `ai-hub install` |
 | `speckit:version` | `speckit_version` coincide con la versión fijada (o la que restrinja `speckit.version`) | `ai-hub install` |
+| `speckit:script` | El script declarado en el manifest coincide con el instalado en `.specify/init-options.json` (`sh`/`ps`) | `ai-hub install` |
 | `speckit:shell` | El shell del script declarado ejecuta `echo ok` (`bash` para `sh`, PowerShell para `ps`) | Instalar Git Bash/bash, o declarar `speckit.script: ps` |
 | `speckit:integrations` | `.specify/integration.json` tiene exactamente las integraciones de los destinos con Spec Kit, sin `copilot`, y la integración por defecto declarada | `ai-hub install`; si aparece `copilot`, `specify integration uninstall copilot` |
 | `speckit:targets` | Informativo: `copilot: sin Spec Kit` (recibe agentes y reglas, no comandos) | — |

package/dist/cli/onboarding.js

@@ -37,9 +37,25 @@ function speckitPlan(settings) {
         extensions: settings.extensions,
     };
 }
-/** Bloque `speckit` a escribir: conserva las restricciones del proyecto y fija `managed`. */
-function speckitBlock(existing, managed) {
-    return { ...(existing ?? {}), managed };
+/** Bloque `speckit` a escribir: conserva las restricciones del proyecto y fija `managed` y el script explícito. */
+function speckitBlock(existing, managed, script) {
+    return { ...(existing ?? {}), managed, ...(script !== undefined ? { script } : {}) };
+}
+/**
+ * Lee `--script <sh|ps>` (design D3): valida antes de cualquier sondeo y nombra el comando concreto.
+ * Devuelve `undefined` cuando la bandera no se usó y `null` cuando es inválida (ya reportado).
+ */
+function parseScriptFlag(args, ctx, command) {
+    if (!('script' in args.flags)) {
+        return undefined;
+    }
+    const value = flagString(args, 'script');
+    if (value === 'sh' || value === 'ps') {
+        return value;
+    }
+    ctx.io.err(`--script acepta sh o ps${value === null ? ' y necesita un valor' : ` (recibido: ${value})`}; ` +
+        `ejecuta ai-hub ${command} --script sh o ai-hub ${command} --script ps`);
+    return null;
 }
 function speckitSettingsFor(targets, block, engine) {
     return effectiveSpeckit({ targets, speckit: block }, engine);
@@ -51,8 +67,8 @@ async function environmentFor(settings, ctx) {
     return probeEnvironment(settings, ctx.exec, ctx.root);
 }
 /** Preflight de Spec Kit; devuelve `false` y explica el motivo si hay que salir con 2. */
-async function preflightOrReport(settings, ctx) {
-    const preflight = await speckitPreflight(settings, ctx.exec, ctx.root);
+async function preflightOrReport(settings, ctx, command) {
+    const preflight = await speckitPreflight(settings, ctx.exec, ctx.root, command);
     if (!preflight.ok) {
         ctx.io.err('preflight de Spec Kit fallido; no se escribió nada:');
         for (const problem of preflight.problems) {
@@ -359,6 +375,10 @@ async function resolveSelection(args, ctx) {
     };
 }
 export async function cmdInit(args, ctx) {
+    const scriptFlag = parseScriptFlag(args, ctx, 'init');
+    if (scriptFlag === null) {
+        return 2;
+    }
     const sourceCheckout = await isEngineCheckout(ctx.root);
     let selection;
     try {
@@ -394,7 +414,7 @@ export async function cmdInit(args, ctx) {
     }
     const includeMcp = await exists(path.join(ctx.root, 'mcp-manifest.yaml'));
     const assets = await buildAssetPlan(spec, engine, selection.targets, includeMcp);
-    const speckit = speckitBlock(existing?.speckit, !args.flags['no-speckit']);
+    const speckit = speckitBlock(existing?.speckit, !args.flags['no-speckit'], scriptFlag);
     const speckitSettings = speckitSettingsFor(selection.targets, speckit, engine);
     // El taller nunca ejecuta Spec Kit: su .specify/ es del mantenedor.
     const runSpeckit = speckitSettings.managed && !sourceCheckout;
@@ -429,7 +449,7 @@ export async function cmdInit(args, ctx) {
         }
         return 0;
     }
-    if (runSpeckit && !(await preflightOrReport(speckitSettings, ctx))) {
+    if (runSpeckit && !(await preflightOrReport(speckitSettings, ctx, 'init'))) {
         return 2;
     }
     // Backup restaurable antes de que Spec Kit toque un proyecto existente (constitución incluida).
@@ -538,6 +558,10 @@ async function retiredCatalogSkills(ids) {
     return ids.filter((id) => retired.has(id));
 }
 export async function cmdInstall(args, ctx) {
+    const scriptFlag = parseScriptFlag(args, ctx, 'install');
+    if (scriptFlag === null) {
+        return 2;
+    }
     let context;
     try {
         context = await loadManifestContext(ctx.root);
@@ -556,7 +580,7 @@ export async function cmdInstall(args, ctx) {
     }
     const includeMcp = await exists(path.join(ctx.root, 'mcp-manifest.yaml'));
     // install sin --no-speckit reactiva Spec Kit en un arnés degradado; con la bandera lo mantiene apagado.
-    const speckit = speckitBlock(context.manifest.speckit, !args.flags['no-speckit']);
+    const speckit = speckitBlock(context.manifest.speckit, !args.flags['no-speckit'], scriptFlag);
     const speckitSettings = speckitSettingsFor(context.manifest.targets, speckit, context.engine);
     const runSpeckit = speckitSettings.managed && !(await isEngineCheckout(ctx.root));
     if (args.flags['dry-run']) {
@@ -575,7 +599,7 @@ export async function cmdInstall(args, ctx) {
         }, null, 2));
         return 0;
     }
-    if (runSpeckit && !(await preflightOrReport(speckitSettings, ctx))) {
+    if (runSpeckit && !(await preflightOrReport(speckitSettings, ctx, 'install'))) {
         return 2;
     }
     const backupId = runSpeckit ? (await createBackup(ctx.root, 'install')).id : null;

package/dist/speckit/commands.d.ts

@@ -15,14 +15,31 @@ export interface SpeckitEnvironment {
     shell: 'found' | 'missing';
     shellCommand: string;
 }
+export interface ShellCandidate {
+    command: string;
+    args: 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.
+ * Rutas estándar de Git for Windows (design D1), construidas desde el entorno del proceso;
+ * una variable ausente omite sus candidatos. Nunca hay rutas de usuario hardcodeadas.
+ */
+export declare function gitBashCandidates(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Candidatos del script declarado, en orden de preferencia. Para `sh` en Windows va primero el
+ * `bash` del PATH y después las rutas estándar de Git for Windows; en Linux y macOS sólo el del PATH.
  */
-export declare function probeShell(settings: SpeckitSettings, runner: ProcessRunner, cwd: string): Promise<{
+export declare function shellCandidates(settings: SpeckitSettings, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): ShellCandidate[];
+export interface ShellProbe {
     ok: boolean;
     command: string;
-}>;
+    /** Comandos probados en orden; las rutas absolutas inexistentes no se prueban. */
+    tried: 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, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): Promise<ShellProbe>;
 /** 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 {
@@ -32,8 +49,9 @@ export interface PreflightResult {
 /**
  * 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.
+ * `command` nombra la bandera exacta en el mensaje; nunca se remite a un manifest que no existe.
  */
-export declare function speckitPreflight(settings: SpeckitSettings, runner: ProcessRunner, cwd: string): Promise<PreflightResult>;
+export declare function speckitPreflight(settings: SpeckitSettings, runner: ProcessRunner, cwd: string, command?: 'init' | 'install'): Promise<PreflightResult>;
 export interface SpeckitRunResult {
     ok: boolean;
     steps: string[][];

package/dist/speckit/commands.js

@@ -1,3 +1,5 @@
+import path from 'node:path';
+import { existsSync } from 'node:fs';
 import { TARGETS } from '../sync/targets.js';
 import { succeeded } from './runner.js';
 /** Argumentos de `uvx` que fijan el paquete y la fecha de resolución. */
@@ -42,27 +44,63 @@ export function speckitSequence(settings) {
     }
     return steps;
 }
-function shellCandidates(settings) {
-    return settings.script === 'ps'
-        ? [
+/**
+ * Rutas estándar de Git for Windows (design D1), construidas desde el entorno del proceso;
+ * una variable ausente omite sus candidatos. Nunca hay rutas de usuario hardcodeadas.
+ */
+export function gitBashCandidates(env = process.env) {
+    const candidates = [];
+    const programFiles = env['ProgramFiles'];
+    const programFilesX86 = env['ProgramFiles(x86)'];
+    const localAppData = env['LOCALAPPDATA'];
+    if (programFiles !== undefined) {
+        candidates.push(path.join(programFiles, 'Git', 'bin', 'bash.exe'));
+    }
+    if (programFilesX86 !== undefined) {
+        candidates.push(path.join(programFilesX86, 'Git', 'bin', 'bash.exe'));
+    }
+    if (localAppData !== undefined) {
+        candidates.push(path.join(localAppData, 'Programs', 'Git', 'bin', 'bash.exe'));
+    }
+    if (programFiles !== undefined) {
+        candidates.push(path.join(programFiles, 'Git', 'usr', 'bin', 'bash.exe'));
+    }
+    return candidates;
+}
+/**
+ * Candidatos del script declarado, en orden de preferencia. Para `sh` en Windows va primero el
+ * `bash` del PATH y después las rutas estándar de Git for Windows; en Linux y macOS sólo el del PATH.
+ */
+export function shellCandidates(settings, platform = process.platform, env = process.env) {
+    if (settings.script === 'ps') {
+        return [
             { command: 'pwsh', args: ['-NoProfile', '-Command', 'echo ok'] },
             { command: 'powershell', args: ['-NoProfile', '-Command', 'echo ok'] },
-        ]
-        : [{ command: 'bash', args: ['-c', 'echo ok'] }];
+        ];
+    }
+    if (platform !== 'win32') {
+        return [{ command: 'bash', args: ['-c', 'echo ok'] }];
+    }
+    return [
+        { command: 'bash', args: ['-c', 'echo ok'] },
+        ...gitBashCandidates(env).map((command) => ({ command, 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);
+export async function probeShell(settings, runner, cwd, platform = process.platform, env = process.env) {
+    const candidates = shellCandidates(settings, platform, env).filter((candidate) => !path.isAbsolute(candidate.command) || existsSync(candidate.command));
+    const tried = [];
     for (const candidate of candidates) {
+        tried.push(candidate.command);
         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: true, command: candidate.command, tried };
         }
     }
-    return { ok: false, command: candidates[0].command };
+    return { ok: false, command: candidates[0]?.command ?? 'bash', tried };
 }
 async function uvxAvailable(runner, cwd) {
     return succeeded(await runner('uvx', ['--version'], { cwd, timeoutMs: 30_000 }));
@@ -86,8 +124,9 @@ export async function probeEnvironment(settings, runner, cwd) {
 /**
  * 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.
+ * `command` nombra la bandera exacta en el mensaje; nunca se remite a un manifest que no existe.
  */
-export async function speckitPreflight(settings, runner, cwd) {
+export async function speckitPreflight(settings, runner, cwd, command = 'init') {
     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/ ' +
@@ -103,10 +142,11 @@ export async function speckitPreflight(settings, runner, cwd) {
     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.');
+            ? `PowerShell no ejecuta \`echo ok\` (probados: ${shell.tried.join(', ')}). ` +
+                `Instala PowerShell (pwsh o powershell). Alternativa: ai-hub ${command} --script sh.`
+            : `ningún bash ejecuta \`bash -c "echo ok"\` (probados: ${shell.tried.join(', ')}). ` +
+                'En Windows instala Git for Windows (Git Bash); el lanzador de WSL sin distribución no sirve. ' +
+                `Alternativa sin bash: ai-hub ${command} --script ps.`);
     }
     return { ok: problems.length === 0, problems };
 }

package/dist/speckit/doctor.d.ts

@@ -1,5 +1,6 @@
-import type { EngineManifest } from '../engine/engine.js';
+import type { EngineManifest, SpeckitScript } from '../engine/engine.js';
 import type { ProjectManifest } from '../manifest/manifest.js';
+import { type ShellProbe } from './commands.js';
 import type { ProcessRunner } from './runner.js';
 export interface SpeckitCheck {
     id: string;
@@ -7,7 +8,9 @@ export interface SpeckitCheck {
     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"];
+export declare const SPECKIT_CHECK_IDS: readonly ["speckit:managed", "speckit:installed", "speckit:version", "speckit:script", "speckit:shell", "speckit:integrations", "speckit:extensions", "speckit:integrity", "speckit:collision", "speckit:constitution", "speckit:versioning"];
+/** Detalle del check `speckit:shell`: distingue el shell resuelto fuera del PATH del que está en el PATH. */
+export declare function speckitShellDetail(probe: ShellProbe, script: SpeckitScript): string;
 /** 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. */

package/dist/speckit/doctor.js

@@ -1,4 +1,5 @@
 import { spawnSync } from 'node:child_process';
+import path from 'node:path';
 import { readLock } from '../sync/lock.js';
 import { probeShell } from './commands.js';
 import { effectiveSpeckit } from './settings.js';
@@ -8,6 +9,7 @@ export const SPECKIT_CHECK_IDS = [
     'speckit:managed',
     'speckit:installed',
     'speckit:version',
+    'speckit:script',
     'speckit:shell',
     'speckit:integrations',
     'speckit:extensions',
@@ -21,6 +23,17 @@ const VERSIONED_STATE = ['.specify/memory/constitution.md', '.specify/init-optio
 function list(items, limit = 5) {
     return items.slice(0, limit).join('; ') + (items.length > limit ? ` (+${items.length - limit})` : '');
 }
+/** Detalle del check `speckit:shell`: distingue el shell resuelto fuera del PATH del que está en el PATH. */
+export function speckitShellDetail(probe, script) {
+    if (probe.ok) {
+        return path.isAbsolute(probe.command)
+            ? `${probe.command} (resuelto fuera del PATH) ejecuta los scripts ${script}`
+            : `${probe.command} ejecuta los scripts ${script}`;
+    }
+    return script === 'ps'
+        ? `PowerShell no ejecuta (probados: ${probe.tried.join(', ')}); instala PowerShell, o ejecuta ai-hub install --script sh`
+        : `bash no está disponible o no ejecuta (probados: ${probe.tried.join(', ')}); en Windows instala Git for Windows, o ejecuta ai-hub install --script ps`;
+}
 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') {
@@ -51,12 +64,15 @@ export async function speckitDoctorChecks(root, manifest, engine, runner) {
     add('speckit:version', installed === settings.version, installed === settings.version
         ? `${installed}`
         : `instalada ${installed ?? '(ninguna)'}; se esperaba ${settings.version}; ejecuta ai-hub install`);
+    // speckit:script (design D7): el manifest y la instalación deben declarar el mismo script.
+    const installedScript = state.initOptions?.script ?? null;
+    add('speckit:script', state.initOptions === null || installedScript === settings.script, state.initOptions === null
+        ? 'no aplica: falta .specify/init-options.json'
+        : installedScript === settings.script
+            ? `manifest e instalación coinciden: ${settings.script}`
+            : `desvío: manifest ${settings.script}, instalación ${installedScript}; 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');
+    add('speckit:shell', shell.ok, speckitShellDetail(shell, settings.script));
     const integrations = checkIntegrations(settings, state);
     add('speckit:integrations', integrations.length === 0, integrations.length === 0
         ? `${settings.integrations.join(', ')} (por defecto ${settings.defaultIntegration ?? '-'})`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsalazardev/ai-hub-cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "author": "Daner Alejandro Salazar Colorado",
   "license": "MIT",
   "type": "module",