agentic-workflow-manager 2.0.0

package/dist/src/core/registries.js

@@ -0,0 +1,205 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGISTRY_MANIFEST_NAME = exports.CONTENT_DIR_NAMES = exports.REGISTRIES_CONFIG_PATH = exports.REGISTRIES_DIR = void 0;
+exports.registryContentRoot = registryContentRoot;
+exports.readRegistriesConfig = readRegistriesConfig;
+exports.writeRegistriesConfig = writeRegistriesConfig;
+exports.seedBaselineRegistry = seedBaselineRegistry;
+exports.listRegistries = listRegistries;
+exports.contentRoots = contentRoots;
+exports.capabilityRoot = capabilityRoot;
+exports.validateRegistryLayout = validateRegistryLayout;
+exports.syncRegistries = syncRegistries;
+exports.readRegistryManifest = readRegistryManifest;
+exports.registryNameForPath = registryNameForPath;
+exports.verifyMinCliVersions = verifyMinCliVersions;
+// src/core/registries.ts
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const simple_git_1 = __importDefault(require("simple-git"));
+const registry_1 = require("./registry");
+const versioning_1 = require("./versioning");
+const cli_version_1 = require("./cli-version");
+// Evaluated at require-time — tests must use jest.resetModules() + late require() to pick up env overrides.
+const AWM_HOME = process.env.AWM_HOME || path_1.default.join(process.env.HOME || os_1.default.homedir(), '.awm');
+exports.REGISTRIES_DIR = path_1.default.join(AWM_HOME, 'registries');
+exports.REGISTRIES_CONFIG_PATH = path_1.default.join(AWM_HOME, 'registries.json');
+exports.CONTENT_DIR_NAMES = ['skills', 'bundles', 'workflows', 'agents'];
+function registryContentRoot(name) {
+    const root = path_1.default.join(exports.REGISTRIES_DIR, name);
+    if (!path_1.default.resolve(root).startsWith(path_1.default.resolve(exports.REGISTRIES_DIR) + path_1.default.sep)) {
+        throw new Error(`Invalid registry name "${name}" — must not contain path separators`);
+    }
+    return root;
+}
+function readRegistriesConfig() {
+    if (!fs_1.default.existsSync(exports.REGISTRIES_CONFIG_PATH))
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(fs_1.default.readFileSync(exports.REGISTRIES_CONFIG_PATH, 'utf-8'));
+    }
+    catch (e) {
+        throw new Error(`Invalid registries config at ${exports.REGISTRIES_CONFIG_PATH}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!Array.isArray(raw)) {
+        throw new Error(`Invalid registries config at ${exports.REGISTRIES_CONFIG_PATH}: expected a JSON array`);
+    }
+    for (const entry of raw) {
+        if (typeof entry?.name !== 'string' || typeof entry?.remote !== 'string') {
+            throw new Error(`Invalid registries config at ${exports.REGISTRIES_CONFIG_PATH}: malformed entry ${JSON.stringify(entry)}`);
+        }
+        if (entry.name === '.' || entry.name.includes('/') || entry.name.includes('\\') || entry.name.includes('..')) {
+            throw new Error(`Invalid registries config at ${exports.REGISTRIES_CONFIG_PATH}: malformed entry name "${entry.name}" (path traversal)`);
+        }
+    }
+    return raw;
+}
+function writeRegistriesConfig(entries) {
+    fs_1.default.mkdirSync(AWM_HOME, { recursive: true });
+    fs_1.default.writeFileSync(exports.REGISTRIES_CONFIG_PATH, JSON.stringify(entries, null, 2) + '\n', 'utf-8');
+}
+/** Bootstrap de máquina (awm init): si no hay registries.json, lo crea con la
+ *  entrada baseline (remote por cadena WS-2: env > prefs > default).
+ *  Devuelve true si sembró. Nunca toca un registries.json existente. */
+function seedBaselineRegistry() {
+    if (fs_1.default.existsSync(exports.REGISTRIES_CONFIG_PATH))
+        return false;
+    writeRegistriesConfig([{ name: 'baseline', remote: (0, registry_1.resolveBaseRemote)() }]);
+    return true;
+}
+function listRegistries() {
+    return readRegistriesConfig().map((e) => ({ ...e, contentRoot: registryContentRoot(e.name) }));
+}
+/** Roots de contenido en orden de registries.json.
+ *  Un registry configurado pero ausente se omite (awm update lo re-clona). */
+function contentRoots() {
+    const roots = [];
+    for (const reg of listRegistries()) {
+        if (fs_1.default.existsSync(reg.contentRoot))
+            roots.push(reg.contentRoot);
+    }
+    return roots;
+}
+/** Primer content root configurado (en orden de registries.json) que contiene el
+ *  directorio pedido ('hooks', 'sensor-packs', 'skills'…). null si ninguno. */
+function capabilityRoot(dirName) {
+    for (const root of contentRoots()) {
+        if (fs_1.default.existsSync(path_1.default.join(root, dirName)))
+            return root;
+    }
+    return null;
+}
+/** Un registry válido tiene ≥1 dir de contenido en su raíz. */
+function validateRegistryLayout(root) {
+    return exports.CONTENT_DIR_NAMES.some((d) => fs_1.default.existsSync(path_1.default.join(root, d)));
+}
+/** Sincroniza cada registry configurado al ref resuelto (pin > último tag > HEAD);
+ *  re-clona si falta el dir. Errores por-registry NO fatales: se reportan en el resultado. */
+async function syncRegistries() {
+    const results = [];
+    for (const reg of listRegistries()) {
+        try {
+            const freshClone = !fs_1.default.existsSync(reg.contentRoot);
+            if (freshClone) {
+                fs_1.default.mkdirSync(exports.REGISTRIES_DIR, { recursive: true });
+                try {
+                    await (0, simple_git_1.default)().clone(reg.remote, reg.contentRoot);
+                }
+                catch (e) {
+                    fs_1.default.rmSync(reg.contentRoot, { recursive: true, force: true });
+                    throw e;
+                }
+            }
+            else {
+                await (0, simple_git_1.default)(reg.contentRoot).reset(['--hard']);
+            }
+            const git = (0, simple_git_1.default)(reg.contentRoot);
+            let resolved;
+            try {
+                resolved = await (0, versioning_1.resolveTargetRef)(reg.contentRoot, (0, versioning_1.machineVersionOpts)(reg.name));
+                await git.checkout(resolved.ref);
+                if (resolved.kind !== 'tag')
+                    await git.pull('origin', resolved.ref);
+            }
+            catch (e) {
+                if (freshClone)
+                    fs_1.default.rmSync(reg.contentRoot, { recursive: true, force: true });
+                throw e;
+            }
+            results.push({
+                name: reg.name,
+                action: freshClone ? 'recloned' : 'pulled',
+                version: resolved.kind === 'tag' ? `v${resolved.version}` : 'HEAD',
+            });
+        }
+        catch (e) {
+            results.push({ name: reg.name, action: 'error', error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    return results;
+}
+exports.REGISTRY_MANIFEST_NAME = 'awm-registry.json';
+function readRegistryManifest(root) {
+    const file = path_1.default.join(root, exports.REGISTRY_MANIFEST_NAME);
+    if (!fs_1.default.existsSync(file))
+        return { overrides: new Set() };
+    let raw;
+    try {
+        raw = JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+    }
+    catch (e) {
+        throw new Error(`Invalid registry manifest at ${file}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const overrides = raw?.overrides ?? [];
+    if (!Array.isArray(overrides) || overrides.some((n) => typeof n !== 'string')) {
+        throw new Error(`Invalid registry manifest at ${file}: "overrides" must be an array of strings`);
+    }
+    for (const name of overrides) {
+        if (!name || name === '.' || name.includes('..') || /[/\\]/.test(name)) {
+            throw new Error(`Invalid registry manifest at ${file}: override name "${name}" (path traversal)`);
+        }
+    }
+    let minCliVersion;
+    const rawMin = raw?.minCliVersion;
+    if (rawMin !== undefined) {
+        if (typeof rawMin !== 'string' || !/^v?\d+\.\d+\.\d+$/.test(rawMin)) {
+            throw new Error(`Invalid registry manifest at ${file}: "minCliVersion" must be "X.Y.Z", got ${JSON.stringify(rawMin)}`);
+        }
+        minCliVersion = rawMin.replace(/^v/, '');
+    }
+    return { overrides: new Set(overrides), minCliVersion };
+}
+/** Nombre del registry dueño de un path: el nombre del clone bajo REGISTRIES_DIR,
+ *  o null si no pertenece a ninguno. */
+function registryNameForPath(p) {
+    const resolved = path_1.default.resolve(p);
+    const regsRoot = path_1.default.resolve(exports.REGISTRIES_DIR) + path_1.default.sep;
+    if (resolved.startsWith(regsRoot)) {
+        const first = resolved.slice(regsRoot.length).split(path_1.default.sep)[0];
+        return first || null;
+    }
+    return null;
+}
+/** Registries cuyo manifest exige un CLI más nuevo que el actual (capa 3, WS-4). */
+function verifyMinCliVersions(current = (0, cli_version_1.cliVersion)()) {
+    const failures = [];
+    for (const reg of listRegistries()) {
+        if (!fs_1.default.existsSync(reg.contentRoot))
+            continue;
+        let min;
+        try {
+            min = readRegistryManifest(reg.contentRoot).minCliVersion;
+        }
+        catch {
+            continue;
+        }
+        if (min && (0, versioning_1.compareSemver)(current, min) < 0)
+            failures.push({ name: reg.name, min });
+    }
+    return failures;
+}

package/dist/src/core/registry.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REMOTE = void 0;
+exports.resolveBaseRemoteInfo = resolveBaseRemoteInfo;
+exports.resolveBaseRemote = resolveBaseRemote;
+// src/core/registry.ts
+//
+// Identidad del registry base (WS-4): el CLI no clona ni buildea nada acá —
+// solo conoce el remote default que `awm init` siembra en registries.json.
+const config_1 = require("../utils/config");
+exports.DEFAULT_REMOTE = "https://github.com/Kodria/awm-baseline-registry.git";
+/** Remote efectivo del registry base y su origen: env AWM_BASE_REMOTE > preferences.baseRemote > DEFAULT_REMOTE. */
+function resolveBaseRemoteInfo() {
+    if (process.env.AWM_BASE_REMOTE)
+        return { remote: process.env.AWM_BASE_REMOTE, source: 'env' };
+    try {
+        const prefs = (0, config_1.getPreferences)();
+        if (prefs.baseRemote)
+            return { remote: prefs.baseRemote, source: 'prefs' };
+    }
+    catch {
+        // preferencias ilegibles no deben bloquear — cae al default
+    }
+    return { remote: exports.DEFAULT_REMOTE, source: 'default' };
+}
+function resolveBaseRemote() {
+    return resolveBaseRemoteInfo().remote;
+}

package/dist/src/core/skill-integrity.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyGlobalSkills = classifyGlobalSkills;
+exports.repairGlobalSkills = repairGlobalSkills;
+exports.reconcileAllSkillLinks = reconcileAllSkillLinks;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const providers_1 = require("../providers");
+function findRegistrySkillPath(registryContentDirs, name) {
+    for (const root of registryContentDirs) {
+        const p = path_1.default.join(root, 'skills', name);
+        if (fs_1.default.existsSync(p))
+            return p;
+    }
+    return null;
+}
+/** Clasifica cada entrada de `skillsDir` (read-only, no muta nada). */
+function classifyGlobalSkills(skillsDir, registryContentDirs) {
+    const out = { valid: [], repairable: [], dead: [] };
+    let entries;
+    try {
+        entries = fs_1.default.readdirSync(skillsDir);
+    }
+    catch {
+        return out;
+    } // dir ausente → nada que clasificar
+    for (const name of entries) {
+        const p = path_1.default.join(skillsDir, name);
+        let lst;
+        try {
+            lst = fs_1.default.lstatSync(p);
+        }
+        catch {
+            continue;
+        }
+        if (!lst.isSymbolicLink())
+            continue; // dirs/archivos reales no son nuestro problema
+        if (fs_1.default.existsSync(p)) {
+            out.valid.push(name);
+            continue;
+        } // target vivo
+        // symlink colgante → ¿reparable o muerto?
+        if (findRegistrySkillPath(registryContentDirs, name))
+            out.repairable.push(name);
+        else
+            out.dead.push(name);
+    }
+    return out;
+}
+/** Re-linkea los repairable al primer root que tenga la skill y poda los dead. Idempotente. Cada
+ *  symlink aislado en try/catch — una falla no aborta el resto. */
+function repairGlobalSkills(skillsDir, registryContentDirs) {
+    const result = { relinked: [], pruned: [], failed: [] };
+    const { repairable, dead } = classifyGlobalSkills(skillsDir, registryContentDirs);
+    for (const name of repairable) {
+        const p = path_1.default.join(skillsDir, name);
+        try {
+            const target = findRegistrySkillPath(registryContentDirs, name);
+            if (!target) {
+                result.failed.push(name);
+                continue;
+            }
+            fs_1.default.rmSync(p, { force: true });
+            fs_1.default.symlinkSync(target, p, 'dir');
+            result.relinked.push(name);
+        }
+        catch {
+            result.failed.push(name);
+        }
+    }
+    for (const name of dead) {
+        const p = path_1.default.join(skillsDir, name);
+        try {
+            fs_1.default.rmSync(p, { force: true });
+            result.pruned.push(name);
+        }
+        catch {
+            result.failed.push(name);
+        }
+    }
+    return result;
+}
+/** Reconcilia los symlinks de skills de TODOS los providers con soporte de skills
+ *  cuyo dir global existe. Es mantenimiento machine-global (awm update): no hay un
+ *  único agente target. Cada provider en su propio path; un dir ausente se omite. */
+function reconcileAllSkillLinks(registryContentDirs) {
+    const out = [];
+    for (const agent of Object.keys(providers_1.PROVIDERS)) {
+        if (!fs_1.default.existsSync(providers_1.PROVIDERS[agent].skill.global))
+            continue;
+        out.push({ agent, result: repairGlobalSkills(providers_1.PROVIDERS[agent].skill.global, registryContentDirs) });
+    }
+    return out;
+}

package/dist/src/core/story-map-parser.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseStoryMap = parseStoryMap;
+exports.updateMiroFrameId = updateMiroFrameId;
+function parseFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match)
+        return { meta: {}, body: content };
+    const meta = {};
+    for (const line of match[1].split('\n')) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        const value = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
+        // Empty value is intentionally skipped — keys without values are not meaningful metadata
+        if (key && value)
+            meta[key] = value;
+    }
+    return { meta, body: match[2] };
+}
+function extractBackbone(body) {
+    const match = body.match(/## Backbone\n([\s\S]*?)(?=\n## |$)/);
+    return match ? match[1].trim() : '';
+}
+function parseBackbone(backbone) {
+    const activities = [];
+    const activityBlocks = backbone.split(/(?=^### 🟡 )/m).filter(Boolean);
+    for (const block of activityBlocks) {
+        const lines = block.split('\n');
+        const activityMatch = lines[0].match(/^### 🟡 (.+)$/);
+        if (!activityMatch)
+            continue;
+        const activity = { title: activityMatch[1].trim(), tasks: [] };
+        const taskContent = lines.slice(1).join('\n');
+        const taskBlocks = taskContent.split(/(?=^#### 🔵 Task: )/m).filter(s => s.trim());
+        for (const taskBlock of taskBlocks) {
+            const taskLines = taskBlock.split('\n');
+            const taskMatch = taskLines[0].match(/^#### 🔵 Task: (.+)$/);
+            if (!taskMatch)
+                continue;
+            const task = { title: taskMatch[1].trim(), stories: [] };
+            for (const line of taskLines.slice(1)) {
+                const storyMatch = line.match(/^- \*\*\[(.+?)\]\*\* (.+)$/);
+                if (storyMatch) {
+                    task.stories.push({ release: storyMatch[1].trim(), title: storyMatch[2].trim() });
+                }
+            }
+            activity.tasks.push(task);
+        }
+        activities.push(activity);
+    }
+    return activities;
+}
+function parseStoryMap(content) {
+    // Normalize CRLF to LF so all downstream regexes can assume Unix line endings
+    const normalized = content.replace(/\r\n/g, '\n');
+    const { meta, body } = parseFrontmatter(normalized);
+    const titleMatch = body.match(/^# Story Map — (.+)$/m);
+    const project = meta['project'] || (titleMatch ? titleMatch[1].trim() : 'Unknown');
+    const goalMatch = body.match(/## Goal\n>\s*(.+)/);
+    const goal = goalMatch ? goalMatch[1].trim() : '';
+    const backbone = extractBackbone(body);
+    const activities = parseBackbone(backbone);
+    return {
+        project,
+        goal,
+        miro_frame_id: meta['miro_frame_id'] || undefined,
+        activities,
+    };
+}
+function updateMiroFrameId(content, frameId) {
+    const match = content.match(/^(---\n)([\s\S]*?)(\n---\n?)([\s\S]*)$/);
+    if (!match) {
+        return `---\nmiro_frame_id: "${frameId}"\n---\n${content}`;
+    }
+    const [, open, frontmatter, close, body] = match;
+    if (frontmatter.includes('miro_frame_id:')) {
+        const updated = frontmatter.replace(/miro_frame_id:.*/, `miro_frame_id: "${frameId}"`);
+        return `${open}${updated}${close}${body}`;
+    }
+    return `${open}${frontmatter}\nmiro_frame_id: "${frameId}"${close}${body}`;
+}

package/dist/src/core/update-check-worker.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// cli/src/core/update-check-worker.ts
+//
+// Proceso detached lanzado por maybeNotifyUpdate: refresca el cache y muere.
+const update_check_1 = require("./update-check");
+(async () => {
+    const latest = await (0, update_check_1.fetchLatestVersion)();
+    (0, update_check_1.writeUpdateCache)({ lastCheck: Date.now(), latest });
+})();

package/dist/src/core/update-check.js

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readUpdateCache = readUpdateCache;
+exports.writeUpdateCache = writeUpdateCache;
+exports.fetchLatestVersion = fetchLatestVersion;
+exports.spawnRefreshWorker = spawnRefreshWorker;
+exports.maybeNotifyUpdate = maybeNotifyUpdate;
+exports.offerSelfUpdate = offerSelfUpdate;
+// cli/src/core/update-check.ts
+//
+// Actualización del CLI en capas (WS-4): capa 1 = aviso pasivo con cache de 24h
+// refrescado por un worker detached; capa 2 = self-update con confirmación en
+// `awm update`. AWM_NO_UPDATE_CHECK=1 desactiva ambas (tests, CI).
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const child_process_1 = require("child_process");
+const picocolors_1 = __importDefault(require("picocolors"));
+const prompts_1 = require("@clack/prompts");
+const cli_version_1 = require("./cli-version");
+const versioning_1 = require("./versioning");
+const TTL_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_URL = `https://registry.npmjs.org/${cli_version_1.CLI_PACKAGE_NAME}/latest`;
+function cacheFile() {
+    const home = process.env.AWM_HOME || path_1.default.join(process.env.HOME || os_1.default.homedir(), '.awm');
+    return path_1.default.join(home, 'update-check.json');
+}
+function readUpdateCache() {
+    try {
+        const raw = JSON.parse(fs_1.default.readFileSync(cacheFile(), 'utf-8'));
+        if (typeof raw.lastCheck === 'number')
+            return raw;
+    }
+    catch { /* ausente o corrupto → null */ }
+    return null;
+}
+function writeUpdateCache(c) {
+    fs_1.default.mkdirSync(path_1.default.dirname(cacheFile()), { recursive: true });
+    fs_1.default.writeFileSync(cacheFile(), JSON.stringify(c), 'utf-8');
+}
+/** Última versión publicada en npm, o null ante cualquier falla (timeout 2s). */
+async function fetchLatestVersion(fetchImpl = fetch) {
+    try {
+        const ctl = new AbortController();
+        const t = setTimeout(() => ctl.abort(), 2000).unref();
+        const res = await fetchImpl(REGISTRY_URL, { signal: ctl.signal });
+        clearTimeout(t);
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.version === 'string' ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Worker detached que refresca el cache sin bloquear el comando actual. */
+function spawnRefreshWorker() {
+    const worker = path_1.default.join(__dirname, 'update-check-worker.js');
+    if (!fs_1.default.existsSync(worker))
+        return; // ts-node / dev: sin worker compilado, skip
+    (0, child_process_1.spawn)(process.execPath, [worker], { detached: true, stdio: 'ignore', env: process.env }).unref();
+}
+/** Capa 1 — llamado al final de cualquier comando (hook postAction de Commander). */
+function maybeNotifyUpdate(opts) {
+    if (process.env.AWM_NO_UPDATE_CHECK)
+        return;
+    const now = opts?.now ?? Date.now();
+    const spawnWorker = opts?.spawnWorker ?? spawnRefreshWorker;
+    const cache = readUpdateCache();
+    if (cache?.latest && (0, versioning_1.compareSemver)(cache.latest, (0, cli_version_1.cliVersion)()) > 0) {
+        console.log(picocolors_1.default.dim(`\n⬆ awm v${cache.latest} disponible → npm i -g ${cli_version_1.CLI_PACKAGE_NAME}`));
+    }
+    if (!cache || now - cache.lastCheck > TTL_MS)
+        spawnWorker();
+}
+/** Capa 2 — en `awm update`: detecta, pregunta, ejecuta npm i -g; degrada a aviso. */
+async function offerSelfUpdate(deps = {}) {
+    if (process.env.AWM_NO_UPDATE_CHECK)
+        return;
+    const current = deps.current ?? (0, cli_version_1.cliVersion)();
+    const latest = deps.latest !== undefined ? deps.latest : await fetchLatestVersion(deps.fetchImpl ?? fetch);
+    writeUpdateCache({ lastCheck: Date.now(), latest: latest ?? null });
+    if (!latest || (0, versioning_1.compareSemver)(latest, current) <= 0)
+        return;
+    const confirmImpl = deps.confirmImpl ?? (async (message) => {
+        const r = await (0, prompts_1.confirm)({ message });
+        return !(0, prompts_1.isCancel)(r) && r === true;
+    });
+    const yes = await confirmImpl(`¿Actualizar awm v${current} → v${latest} ahora?`);
+    if (!yes) {
+        console.log(picocolors_1.default.dim(`  Para actualizar después: npm i -g ${cli_version_1.CLI_PACKAGE_NAME}`));
+        return;
+    }
+    const runner = deps.runner ?? ((cmd, args) => (0, child_process_1.spawnSync)(cmd, args, { stdio: 'inherit', shell: true }));
+    const r = runner('npm', ['i', '-g', `${cli_version_1.CLI_PACKAGE_NAME}@latest`]);
+    if (r.status === 0) {
+        console.log(picocolors_1.default.green(`  ✓ CLI actualizado a v${latest} (aplica desde el próximo comando)`));
+    }
+    else {
+        console.warn(picocolors_1.default.yellow(`  ⚠  No se pudo actualizar automáticamente — corré: npm i -g ${cli_version_1.CLI_PACKAGE_NAME}`));
+    }
+}

package/dist/src/core/versioning.js

@@ -0,0 +1,112 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePin = normalizePin;
+exports.resolveTargetRef = resolveTargetRef;
+exports.currentVersion = currentVersion;
+exports.machineVersionOpts = machineVersionOpts;
+exports.compareSemver = compareSemver;
+// src/core/versioning.ts
+//
+// Resolver de versiones por tags semver — WS-3. Sin estado propio: git es la
+// única fuente de verdad (la versión vigente se deriva de `git describe`).
+const simple_git_1 = __importDefault(require("simple-git"));
+const config_1 = require("../utils/config");
+const TAG_RE = /^v(\d+)\.(\d+)\.(\d+)$/;
+function normalizePin(pin) {
+    return pin.replace(/^v/, '');
+}
+function semverKey(tag) {
+    const m = TAG_RE.exec(tag);
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function bySemverAsc(a, b) {
+    const [a1, a2, a3] = semverKey(a);
+    const [b1, b2, b3] = semverKey(b);
+    return a1 - b1 || a2 - b2 || a3 - b3;
+}
+async function defaultBranch(git) {
+    try {
+        const ref = (await git.raw(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'])).trim();
+        const name = ref.split('/').slice(1).join('/');
+        if (name)
+            return name;
+    }
+    catch {
+        // origin/HEAD puede no estar seteado — probar candidatos
+    }
+    for (const cand of ['main', 'master']) {
+        try {
+            await git.raw(['rev-parse', '--verify', `origin/${cand}`]);
+            return cand;
+        }
+        catch {
+            // siguiente candidato
+        }
+    }
+    return 'main';
+}
+/** Tags semver vX.Y.Z del repo, orden ascendente. Hace fetch --tags --prune primero. */
+async function fetchVersionTags(git) {
+    await git.raw(['fetch', '--tags', '--prune', 'origin']);
+    const tags = (await git.tags()).all.filter((t) => TAG_RE.test(t));
+    return tags.sort(bySemverAsc);
+}
+/**
+ * Resuelve a qué ref debe quedar checkouteado un registry clonado:
+ * pin declarado > último tag semver (canal stable) > HEAD (canal dev o repo sin tags).
+ */
+async function resolveTargetRef(repoDir, opts) {
+    const git = (0, simple_git_1.default)(repoDir);
+    const tags = await fetchVersionTags(git);
+    if (opts.pin) {
+        const want = `v${normalizePin(opts.pin)}`;
+        if (!tags.includes(want)) {
+            const available = tags.length > 0
+                ? `available versions: ${tags.join(', ')}`
+                : 'the registry has no version tags';
+            throw new Error(`Pinned version ${want} not found in ${repoDir} — ${available}`);
+        }
+        return { kind: 'tag', ref: want, version: normalizePin(opts.pin) };
+    }
+    const branch = await defaultBranch(git);
+    if (opts.channel === 'dev')
+        return { kind: 'head', ref: branch };
+    if (tags.length === 0)
+        return { kind: 'head-fallback', ref: branch };
+    const latest = tags[tags.length - 1];
+    return { kind: 'tag', ref: latest, version: latest.slice(1) };
+}
+/** Versión checkouteada actual ("X.Y.Z") si HEAD coincide exactamente con un tag semver; null si sigue un branch. */
+async function currentVersion(repoDir) {
+    try {
+        const out = (await (0, simple_git_1.default)(repoDir).raw(['describe', '--tags', '--exact-match', 'HEAD'])).trim();
+        return TAG_RE.test(out) ? out.slice(1) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Opts de versionado de la máquina para un registry, desde preferences.
+ *  Preferences ilegibles → defaults (stable, sin pin) — patrón de resolveBaseRemoteInfo. */
+function machineVersionOpts(registryName) {
+    try {
+        const prefs = (0, config_1.getPreferences)();
+        const channel = prefs.channel === 'dev' ? 'dev' : 'stable';
+        const pin = prefs.pins && typeof prefs.pins[registryName] === 'string'
+            ? prefs.pins[registryName]
+            : undefined;
+        return { pin, channel };
+    }
+    catch {
+        return { pin: undefined, channel: 'stable' };
+    }
+}
+/** Compara "X.Y.Z" vs "X.Y.Z" (sin prefijo v) numéricamente. <0, 0, >0. */
+function compareSemver(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    return (pa[0] - pb[0]) || (pa[1] - pb[1]) || (pa[2] - pb[2]);
+}