jorgex-stack 1.0.1 → 1.0.3

package/README.md

@@ -1,56 +1,68 @@
-# JorgeX Stack
-
-Harness multi-agente portable: una sola fuente de configuración — 15 agentes, 18 skills, hooks, memoria persistente ([Engram](https://github.com/Gentleman-Programming/engram)), MCPs y system prompt — instalable con un comando en **Claude Code**, **Codex CLI** y **OpenCode**.
-
-> Inspirado en [gentle-ai](https://github.com/Gentleman-Programming/gentle-ai), reconstruido para el stack JorgeX.
-
-## Uso
-
-Instalación y uso vía npm (no requiere clonar el repo):
-
-```
-pnpm dlx jorgex-stack install    # interactivo: elige runtimes y confirma
-pnpm dlx jorgex-stack models     # picker de modelos por runtime y tier (strong/standard/cheap)
-pnpm dlx jorgex-stack sync       # re-aplica la config (idempotente; limpia huérfanos)
-pnpm dlx jorgex-stack doctor     # verifica que todo está sano (Engram, drift, hooks, keys)
-pnpm dlx jorgex-stack update     # interactivo: scan stack/Engram/skills, multiselect, diff/confirm
-                                 # Con --check: solo informe sin cambios
-                                 # Con --yes: modo batch (solo informe)
-pnpm dlx jorgex-stack restore    # restaura un backup
-pnpm dlx jorgex-stack uninstall  # desinstala lo nuestro y conserva lo del usuario (Engram intacto)
-```
-
-En desarrollo (desde un clon), los mismos comandos van por `pnpm cli <comando>` (ver [Desarrollo](#desarrollo)).
-
-Todo comando soporta `--dry-run`, `--yes` y `--target-dir <dir>` (pruebas sin tocar la config real). Las escrituras llevan backup automático y verificación de idempotencia; el merge en configs de usuario es quirúrgico (secciones marcadas en markdown, upsert en JSON/TOML) — lo tuyo no se toca jamás.
-
-### Update: flujo interactivo
-
-`update` gestiona tres fuentes:
-
-1. **Stack** (jorgex-stack): detecta si es clon git o instalación global, oferece actualización con confirmación.
-2. **Engram** (binario): detecta la versión instalada, ofrece actualización con **canal nativo** (brew → `go install` → URL releases). No hace falta parar nada: igual que el upstream en macOS/Linux, los procesos vivos siguen con la versión antigua hasta reiniciar los clientes; en Windows el `.exe` en uso se rota por rename antes de instalar. **Backup automático de la DB antes de actualizar**. La base de datos y las memorias jamás se tocan.
-3. **Skills vendorizadas**: detecta cambios en los upstream registrados en `upstreams.json`, descarga el upstream a temporal, **muestra diff obligatorio** y solicita confirmación. Las skills con cambios locales (`modified: true`) alertan y exigen doble confirmación.
-
-Uso:
-- `update --check`: scan de versiones sin aplicar cambios.
-- `update` (TTY, sin `--yes`): multiselect interactivo con diffs visibles y confirmaciones paso a paso.
-- `update --yes` o sin TTY: se comporta como `--check` (solo informe).
-
-Autenticación con GitHub: las consultas usan `GH_TOKEN`/`GITHUB_TOKEN` del entorno o, si no existen, el token de tu sesión de `gh` CLI (`gh auth token` — solo lectura local, nunca se loguea ni persiste). Sin token, GitHub limita las consultas en paralelo y algunos upstreams pueden salir como "sin conexión".
-
-## Estado
-
-**v1.0.0 — publicada en [npm](https://www.npmjs.com/package/jorgex-stack).** CLI completo y migración real ejecutada (F6); el stack es la única fuente de configuración. El diseño, las decisiones (D1–D9) y el roadmap están en [PRD.md](PRD.md).
-
-## Desarrollo
-
-Requisitos: Node ≥ 20 y pnpm (nunca npm).
-
-```
-pnpm install
-pnpm build        # tsup → dist/
-pnpm typecheck
-pnpm test         # vitest
-pnpm cli --help
-```
+# JorgeX Stack
+
+Harness multi-agente portable: una sola fuente de configuración — 15 agentes, 18 skills, hooks, memoria persistente ([Engram](https://github.com/Gentleman-Programming/engram)), MCPs y system prompt — instalable con un comando en **Claude Code**, **Codex CLI** y **OpenCode**.
+
+> Inspirado en [gentle-ai](https://github.com/Gentleman-Programming/gentle-ai), reconstruido para el stack JorgeX.
+
+## Uso
+
+Instalación y uso vía npm (no requiere clonar el repo):
+
+```
+pnpm dlx jorgex-stack install    # interactivo: elige runtimes y confirma
+pnpm dlx jorgex-stack models     # picker de modelos por runtime y tier (strong/standard/cheap)
+pnpm dlx jorgex-stack sync       # re-aplica la config (idempotente; limpia huérfanos)
+pnpm dlx jorgex-stack doctor     # verifica que todo está sano (Engram, drift, hooks, keys)
+pnpm dlx jorgex-stack update     # interactivo: scan stack/Engram/skills, multiselect, diff/confirm
+                                 # Con --check: solo informe sin cambios
+                                 # Con --yes: modo batch (solo informe)
+pnpm dlx jorgex-stack restore    # restaura un backup
+pnpm dlx jorgex-stack uninstall  # desinstala lo nuestro y conserva lo del usuario (Engram intacto)
+```
+
+En desarrollo (desde un clon), los mismos comandos van por `pnpm cli <comando>` (ver [Desarrollo](#desarrollo)).
+
+Todo comando soporta `--dry-run`, `--yes` y `--target-dir <dir>` (pruebas sin tocar la config real). Las escrituras llevan backup automático y verificación de idempotencia; el merge en configs de usuario es quirúrgico (secciones marcadas en markdown, upsert en JSON/TOML) — lo tuyo no se toca jamás.
+
+### Update: flujo interactivo
+
+`update` gestiona tres fuentes:
+
+1. **Stack** (jorgex-stack): detecta si es clon git o instalación global, oferece actualización con confirmación.
+2. **Engram** (binario): detecta la versión instalada, ofrece actualización con **canal nativo** (brew → `go install` → URL releases). No hace falta parar nada: igual que el upstream en macOS/Linux, los procesos vivos siguen con la versión antigua hasta reiniciar los clientes; en Windows el `.exe` en uso se rota por rename antes de instalar. **Backup automático de la DB antes de actualizar**. La base de datos y las memorias jamás se tocan.
+3. **Skills vendorizadas**: detecta cambios en los upstream registrados en `upstreams.json`, descarga el upstream a temporal, **muestra diff obligatorio** y solicita confirmación. Las skills con cambios locales (`modified: true`) alertan y exigen doble confirmación.
+
+Uso:
+- `update --check`: scan de versiones sin aplicar cambios.
+- `update` (TTY, sin `--yes`): multiselect interactivo con diffs visibles y confirmaciones paso a paso.
+- `update --yes` o sin TTY: se comporta como `--check` (solo informe).
+
+Autenticación con GitHub: las consultas usan `GH_TOKEN`/`GITHUB_TOKEN` del entorno o, si no existen, el token de tu sesión de `gh` CLI (`gh auth token` — solo lectura local, nunca se loguea ni persiste). Sin token, GitHub limita las consultas en paralelo y algunos upstreams pueden salir como "sin conexión".
+
+## Estado
+
+CLI completo y migración real ejecutada (F6); el stack es la única fuente de configuración. Las versiones se publican automáticamente en [npm](https://www.npmjs.com/package/jorgex-stack) según el flujo descrito en [Publicación](#publicación). El diseño, las decisiones (D1–D9) y el roadmap están en [PRD.md](PRD.md).
+
+## Publicación
+
+La release la dispara el push/merge a `main` y GitHub Actions; también hay `workflow_dispatch` de recuperación sobre `main` con `release_sha` opcional. `validate` resuelve una sola vez la SHA objetivo y la expone como `target_sha`; `bump` reutiliza esa SHA. Si no pasas `release_sha`, `validate` fija `target_sha` a `origin/main` tras `fetch`; si la pasas, debe ser una SHA completa de 40 hex perteneciente a `main` o falla en rojo con instrucción de recuperación. El modo sin `release_sha` solo es válido para publicar `origin/main` cuando la versión aún no existe en npm; si la versión ya existe y falta el tag, el workflow falla y exige `workflow_dispatch` con `release_sha=<sha publicada>`. No se usa `pnpm publish` ni hace falta login de npm:
+
+- **Patch automático**: si el push a `main` contiene cambios publicables y la versión actual de `package.json` ya está en npm, el workflow busca el primer patch libre (`x+1`, `x+2`, …), commitea `chore(release): bump version to v…` y publica. Si ya existe el tag `v<package.version>`, usa ese punto como base acumulada; si no, cae a `github.event.before`. Las runs obsoletas se abortan tras `git fetch origin main --tags` si `origin/main` ya no coincide con `GITHUB_SHA`.
+- **Recuperación manual**: una ejecución manual sobre `main` con `release_sha` publica esa SHA si todavía no existe en npm, sin volver a bumpear; si la versión ya está en npm pero falta el tag `v<version>`, el workflow falla y te obliga a relanzar con `release_sha=<sha publicada>` para no tagear `origin/main`. `release_sha` debe ser una SHA completa de 40 hex y pertenecer a `main`; refs mutables (`main`, tags, `main~1`) se rechazan. Si no pasas `release_sha`, `validate` resuelve `origin/main` una vez, lo expone como `target_sha` y `bump` usa esa SHA validada.
+- **Sin release**: cambios solo en `work/`, `worktrees/`, tests o archivos no listados como publicables (`src/`, `stack/`, `upstreams.json`, `package.json`, `pnpm-lock.yaml`, `tsconfig.json`, `tsup.config.ts`, `README.md`, `PRD.md`) no generan release.
+- **Minor y major manuales**: bump explícito de `package.json` en el PR (el workflow detecta que el siguiente patch ya existe en npm y exige el bump).
+- **OIDC / trusted publishing**: el job de publicación usa `id-token: write` y `registry-url` de `setup-node`; el job de bump/push solo tiene `contents: write`; el `tag-release` solo escribe `contents` y no usa OIDC. No hay `NPM_TOKEN` ni `NODE_AUTH_TOKEN` en ningún secreto. El `tag-release` solo corre si `publish` fue `success` o `skipped` con `tag_needed=true` y conserva su validación SHA como última defensa. La única excepción a la regla "pnpm siempre" son `npm pack --dry-run --ignore-scripts` y `npm publish --ignore-scripts --provenance` en el paso final, por compatibilidad y hardening del registry.
+
+Los detalles de diseño están en [PRD §7.6](PRD.md#76-publicación-automática-en-npm).
+
+## Desarrollo
+
+Requisitos: Node ≥ 20 y pnpm (nunca npm).
+
+```
+pnpm install
+pnpm build        # tsup → dist/
+pnpm typecheck
+pnpm test         # vitest
+pnpm cli --help
+```

package/dist/cli.js

@@ -1098,8 +1098,13 @@ function createBackup(files, label, root = backupsRoot()) {
   const checksum = compositeChecksum(existing);
   const latest = listBackups(root)[0];
   if (latest?.checksum === checksum) return latest;
-  const id = `${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}-${label}`;
-  const dir = path10.join(root, id);
+  const base = `${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}-${label}`;
+  let id = base;
+  let dir = path10.join(root, id);
+  for (let n = 1; fs6.existsSync(dir); n++) {
+    id = `${base}-${n}`;
+    dir = path10.join(root, id);
+  }
   ensureDir(path10.join(dir, "files"));
   const entries = existing.map((original, i) => {
     const stored = path10.join(dir, "files", `${String(i).padStart(4, "0")}-${path10.basename(original)}`);
@@ -2703,8 +2708,37 @@ function cancelled() {
   return 1;
 }
 
+// src/lib/release.ts
+import fs17 from "fs";
+import path24 from "path";
+import { execFileSync as execFileSync5 } from "child_process";
+import { fileURLToPath as fileURLToPath2 } from "url";
+function findPackageJson() {
+  let dir = path24.dirname(fileURLToPath2(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const candidate = path24.join(dir, "package.json");
+    if (fs17.existsSync(candidate)) return candidate;
+    dir = path24.dirname(dir);
+  }
+  throw new Error("No se encontr\xF3 package.json cerca del CLI.");
+}
+function readPackageVersion() {
+  return readPackageMetadata().version;
+}
+function readPackageMetadata() {
+  const packageJson = findPackageJson();
+  const raw = fs17.readFileSync(packageJson, "utf8");
+  const parsed = JSON.parse(raw);
+  const name = typeof parsed.name === "string" ? parsed.name.trim() : "";
+  const version = typeof parsed.version === "string" ? parsed.version.trim() : "";
+  if (name === "" || version === "") {
+    throw new Error("package.json no expone nombre o versi\xF3n v\xE1lidos.");
+  }
+  return { name, version };
+}
+
 // src/cli.ts
-var VERSION = "0.6.0";
+var VERSION = readPackageVersion();
 var COMMANDS = ["install", "sync", "models", "update", "doctor", "restore", "uninstall"];
 function parseFlags(args) {
   const flags = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Harness multi-agente portable: instala la config JorgeX (agentes, skills, hooks, Engram, MCPs) en Claude Code, Codex CLI y OpenCode",
   "type": "module",
   "license": "MIT",

package/stack/agents/code-simplifier.md

@@ -9,14 +9,15 @@ bash: git-read
 
 # Code Simplifier
 
-You are an expert code simplification specialist focused on enhancing code clarity, consistency, and maintainability while preserving exact functionality. Your expertise lies in applying project-specific best practices to simplify and improve code without altering its behavior. You prioritize readable, explicit code over overly compact solutions.
+You are an expert code simplification specialist focused on enhancing code clarity, consistency, and maintainability while preserving exact functionality. Use the `lean-code` skill as your anti-bloat lens and source of truth for when code should disappear, shrink, or reuse existing helpers. You prioritize readable, explicit code over overly compact solutions.
 
 You are read-only: you analyze recently modified code and **propose** refinements as concrete suggestions (with file path, line and a before/after snippet). You never write or edit files yourself.
 
 **First actions, in order**:
 
-1. **Get the diff.** When you're given BASE and HEAD branches, review only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no branches are given, review the working diff (`git diff`).
-2. Load the `agent-delegation` skill.
+1. **Resolve scope.** If you're given an audit scope (repo/path root), audit only that path and do not fall back to `git diff`. Otherwise, when you're given BASE and HEAD branches, review only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no audit scope or branches are given, review the working diff (`git diff`).
+2. Load the `lean-code` skill.
+3. Load the `agent-delegation` skill.
 
 **Final output, last of all**: your final report (ending with the Result contract) must be the very last thing you emit. If you need to save anything to memory, do it BEFORE that output — never after.
 
@@ -24,6 +25,13 @@ You are read-only: you analyze recently modified code and **propose** refinement
 
 Your lane: behavior-preserving clarity and structure of the CODE itself — nothing else. Bugs, guideline violations and comment quality belong to other specialists (the `agent-delegation` skill has the map): don't report them — note them as delegations in your Result contract. Don't propose adding, rewriting or deleting comments.
 
+## 4R Readability Lens
+
+- Propose simplifications only when they clearly reduce cognitive load: magic numbers with business meaning, long parameter lists, duplicated logic, dead code, naming drift, or deep nesting.
+- Back proposals with evidence from the code shape, not taste; avoid subjective style nits.
+- Keep the scope strictly readability/maintainability: do not turn bug fixes, security concerns, test gaps, or error-handling problems into simplification suggestions.
+- Prefer small, local clarifications over structural rewrites that change how the code is organized without a clear readability win.
+
 Your proposed refinements must:
 
 1. **Preserve Functionality**: Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.
@@ -46,20 +54,23 @@ Your proposed refinements must:
    - Prioritize "fewer lines" over readability (e.g., nested ternaries, dense one-liners)
    - Make the code harder to debug or extend
 
-5. **Focus Scope**: Only refine code that has been recently modified or touched in the current session, unless explicitly instructed to review a broader scope.
+5. **Focus Scope**: Only refine code that has been recently modified or touched in the current session, unless explicitly instructed to review a broader audit scope.
 
 Your process:
 
 1. Identify the recently modified code sections
-2. Analyze for opportunities to improve elegance and consistency
-3. Check proposals against project-specific best practices and coding standards
-4. Ensure proposed changes keep all functionality unchanged
-5. Verify the proposed code is simpler and more maintainable
-6. Report only significant changes that affect understanding
+2. Run a lean deletion pass first: what can disappear, become stdlib/native/platform code, reuse existing project code, or lose a premature abstraction?
+3. Analyze remaining opportunities to improve elegance and consistency
+4. Check proposals against project-specific best practices and coding standards
+5. Ensure proposed changes keep all functionality unchanged
+6. Verify the proposed code is simpler and more maintainable
+7. Report only significant changes that affect understanding
 
 ## Output format
 
-For each suggestion provide: file path and line, what to simplify and why, and a before/after snippet. If nothing meaningful can be simplified, say so briefly. Your goal is to surface refinements that meet the highest standards of elegance and maintainability while preserving complete functionality — the implementer applies them.
+For each suggestion provide: file path and line, what to simplify and why, and a before/after snippet when useful. Prefix each lean finding with the matching `lean-code` tag (for example `shrink:` or `delete:`).
+
+End lean-heavy reports with `net: -<N> lines possible` when you can estimate it. If nothing meaningful can be simplified, say so briefly. Your goal is to surface refinements that meet the highest standards of elegance and maintainability while preserving complete functionality — the implementer applies them.
 
 ## Types of refinement to propose
 

package/stack/agents/implementer.md

@@ -23,6 +23,7 @@ You usually receive a clear design (often from an analyst), and the project's st
 
 1. **Confirm the libraries you'll actually use** when you're unsure of the exact one or its API: check `package.json` (or the equivalent manifest) and the touched files — e.g. state (Zustand, Redux), data-fetching (TanStack Query, SWR), forms, styling, ORM. Use each library's real API and patterns; don't hand-roll what a present library already does.
 2. **Mirror existing conventions**: look at the files you'll touch and their neighbors, and follow their style, patterns and imports. Don't introduce a new pattern without need.
+3. **Load `lean-code` before non-trivial code**: use it as the ladder before you add a helper, wrapper, abstraction, or dependency. Ask whether the code is needed at all, whether stdlib/native/project helpers already solve it, and whether a smaller change works.
 
 ## Contract