@ronaldjdevfs/forge 1.2.0 → 1.3.0-beta

package/README.md

@@ -1,5 +1,7 @@
 <img src="favicon.svg" alt="Forge Logo" width="100" height="100">
 
+> **v1.3.0-beta** — Multi-Agent: OpenCode · Claude Code · Cursor · Codex CLI · Gemini
+
 ## Forge — Backend Architecture Operating System
 
 **Forge** es un **sistema operativo arquitectónico** para backend. Modela, construye, audita, protege y evoluciona sistemas completos en cuatro dominios arquitectónicos: **Platform**, **Features**, **Shared** e **Infrastructure**.
@@ -356,7 +358,11 @@ Donde vive toda la inteligencia arquitectónica:
 | `scripts/formatter.mjs` | Output unificado: colores, JSON, scoreBar, formatCheck |
 | `scripts/registry/rules.mjs` | Registry de reglas R1-R9 + custom rules desacoplado |
 | `scripts/assay.mjs` | Ensayo multi-persona (Bezos, Fowler, Hacker, PM, Arquitecta) |
-| `scripts/posttool.mjs` | PostToolUse hook con `--reminder` y `--strict` |
+| `scripts/forgeSentinel.mjs` | PostToolUse hook adapter para Claude/Codex/agents |
+| `scripts/forgeSentinel-lib.mjs` | Lógica compartida del hook PostToolUse |
+| `scripts/forgeSmith.mjs` | preToolUse gate para Cursor (deniega escrituras con violaciones CRITICAL/ERROR) |
+| `scripts/forgeSmith-admin.mjs` | Gestión de hooks (on/off/status) para Cursor |
+| `scripts/posttool.mjs` | PostToolUse hook (deprecated — usar forgeSentinel) |
 | `scripts/forge-config.mjs` | Persistencia de config, estado e histórico |
 | `scripts/forge-state.mjs` | CLI wrapper de estado post-auditoría |
 | `scripts/forge-signals.mjs` | Manejo de señales (SIGINT, SIGTERM) |
@@ -381,29 +387,22 @@ Donde vive toda la inteligencia arquitectónica:
 
 ## Instalación
 
-### En un proyecto
-
 ```bash
-npx @ronaldjdev/forge install
+npx @ronaldjdevfs/forge install          # Wizard interactivo
+npx @ronaldjdevfs/forge install --all    # Todos los agentes detectados
+npx @ronaldjdevfs/forge install --cursor # Solo Cursor
+npx @ronaldjdevfs/forge install --claude # Solo Claude Code
 ```
 
-Esto copia la skill en `.opencode/skills/forge/` del proyecto actual.
-
-### Global (disponible en todos los proyectos)
-
-```bash
-npx @ronaldjdev/forge install --global
-```
-
-Esto copia la skill en `~/.config/opencode/skills/forge/`.
-
-### Con instalación global del CLI
-
-```bash
-npm install -g @ronaldjdev/forge
-forge install      # proyecto actual
-forge install -g   # global
-```
+| Flag | Agente | Hook activo |
+|------|--------|-------------|
+| `--opencode` | OpenCode | forgeSentinel (vía SKILL.md) |
+| `--cursor` | Cursor | forgeSmith (preToolUse) |
+| `--claude` | Claude Code | forgeSentinel (PostToolUse) |
+| `--codex` | Codex CLI | forgeSentinel (PostToolUse) |
+| `--gemini` | Gemini Code Assist | — |
+| `--all` | Todos los anteriores | — |
+| `--global` | `~/.config/opencode/` | forgeSentinel |
 
 **Requisitos**: Node.js ≥ 18
 
@@ -436,6 +435,22 @@ Una vez instalada, OpenCode carga automáticamente la skill `forge` al trabajar
 
 ---
 
+### Sistema de Hooks Multi-Agent
+
+Forge se despliega como **skill** en múltiples agentes de IA simultáneamente, con hooks adaptados a cada plataforma:
+
+| Agente | Hook | Cuándo se ejecuta | Efecto |
+|--------|------|-------------------|--------|
+| **OpenCode** | forgeSentinel | PostToolUse tras Edit/Write | Reporta violaciones como reminder |
+| **Claude Code** | forgeSentinel | PostToolUse tras Edit/Write/MultiEdit | Reporta violaciones como reminder |
+| **Cursor** | forgeSmith | preToolUse antes de cada escritura | Puede DENEGAR la escritura |
+| **Codex CLI** | forgeSentinel | PostToolUse tras Edit/Write/apply_patch | Reporta violaciones como reminder |
+| **Gemini** | SKILL.md | Al cargar el agente | Instrucciones arquitectónicas |
+
+Todos los hooks comparten la misma lógica de detección de violaciones R1-R9 a través de `forgeSentinel-lib.mjs`.
+
+---
+
 ## Desarrollo
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ronaldjdevfs/forge",
-  "version": "1.2.0",
+  "version": "1.3.0-beta",
   "description": "Forge — Architecture Operating System for backend systems. Arquitectura Hexagonal, DDD pragmático y vertical slices.",
   "type": "module",
   "bin": {
@@ -13,7 +13,12 @@
     "NOTICE"
   ],
   "scripts": {
-    "install:local": "node ./src/cli.js install"
+    "install:local": "node ./src/cli.js install",
+    "prepublishOnly": "node -e \"const p=require('./package.json'); if(p.dependencies && p.dependencies[p.name]) { console.error('ERROR: self-referencing dependency detected. Remove before publish.'); process.exit(1); }\"",
+    "test:forgeSentinel": "node .opencode/skills/forge/scripts/forgeSentinel.mjs --reminder",
+    "test:forgeSmith": "echo '{\"toolName\":\"Write\",\"args\":{\"filePath\":\"src/test.ts\"}}' | node .opencode/skills/forge/scripts/forgeSmith.mjs",
+    "test:pin": "node .opencode/skills/forge/scripts/pin.mjs nail cast",
+    "test:all": "pnpm install:local && pnpm test:forgeSentinel && pnpm test:forgeSmith"
   },
   "keywords": [
     "opencode",

package/skills/forge/SKILL.md

@@ -82,7 +82,8 @@ ANTES de cualquier acción, Forge DEBE ejecutar esta secuencia. Si no lo haces,
 6. **inspect.mjs** — Auditoría completa con ownership + platform
 7. **architecture.mjs** — Generar/actualizar ARCHITECTURE.md
 8. **Ejecutar comando solicitado** — cast, quench, temper, etc.
-9. **Actualizar ARCHITECTURE.md** — Reflejar nuevo estado
+9. **forgeSentinel** — Verificar cambios tras escritura (`scripts/forgeSentinel.mjs --reminder`)
+10. **Actualizar ARCHITECTURE.md** — Reflejar nuevo estado
 
 ```bash
 # Template de setup que debes ejecutar:
@@ -133,8 +134,9 @@ Para cada comando, Forge sigue este flujo:
 4. **Referencia**: Cargar `reference/<command>.md`
 5. **Ejecutar**: Aplicar el flujo definido en la referencia, usando los scripts según corresponda
 6. **Verificar**: Ejecutar `scripts/detect.mjs` para verificar que no se introdujeron violaciones
-7. **Actualizar ARCHITECTURE.md**: Reflejar el nuevo estado (`architecture.mjs`)
-8. **Reportar**: Mostrar resultado al usuario con severidades
+7. **forgeSentinel**: Ejecutar `scripts/forgeSentinel.mjs --reminder` para reportar cambios
+8. **Actualizar ARCHITECTURE.md**: Reflejar el nuevo estado (`architecture.mjs`)
+9. **Reportar**: Mostrar resultado al usuario con severidades
 
 ---
 
@@ -235,10 +237,13 @@ El agente DEBE leer este archivo al inicio de cada interacción y actualizarlo a
 | `reference/help.md` | Lista completa de comandos y flags de Forge |
 | `reference/assay.md` | Ensayo arquitectónico multi-persona — interpretación cualitativa del audit |
 | `profiles/` | Perfiles tecnológicos detallados (Express, Fastify, NestJS, etc.) |
-| `scripts/` | Scripts: context, detect, inspect, chain, profile, graph, architecture, armorer, bootstrap, forge-config, forge-signals, forge-state, forge-api, pin, update, rollback, hook, posttool, formatter, assay, registry/rules |
+| `scripts/` | Scripts: context, detect, inspect, chain, profile, graph, architecture, armorer, bootstrap, forge-config, forge-signals, forge-state, forge-api, pin, update, rollback, hook, forgeSentinel, forgeSentinel-lib, forgeSmith, forgeSmith-admin, formatter, assay, registry/rules |
 | `scripts/registry/rules.mjs` | Anti-pattern rule registry (R1-R9 + custom rules desacopladas de detect.mjs) |
 | `scripts/formatter.mjs` | Output formatter unificado (JSON, tabla, severidad coloreada, scoreBar, formatCheck, formatViolation) |
-| `scripts/posttool.mjs` | PostToolUse hook — analiza archivos modificados tras escritura y reporta violaciones |
+| `scripts/forgeSentinel.mjs` | PostToolUse hook — analiza archivos modificados tras escritura y reporta violaciones |
+| `scripts/forgeSentinel-lib.mjs` | Lógica compartida para hooks forgeSentinel y forgeSmith |
+| `scripts/forgeSmith.mjs` | preToolUse gate — previene escrituras con violaciones CRITICAL/ERROR (Cursor) |
+| `scripts/forgeSmith-admin.mjs` | Gestión de hooks (on/off/status) |
 | `scripts/assay.mjs` | Motor de ensayo arquitectónico multi-persona (Bezos, Fowler, Hacker, PM, Arquitecta Senior) |
 | `templates/feature/` | Templates de feature (entity, repository, uc, controller, routes, schema, mapper) |
 | `templates/platform/` | Templates de platform (config, server, database, logger, http, di) |
@@ -264,7 +269,7 @@ node --test .opencode/skills/forge/tests/core.test.mjs
 | `formatter.mjs` | 4 | Output format, colores, JSON |
 | `registry/rules.mjs` | 4 | R1-R9, evaluación, custom rules |
 | `detect.mjs` (inline ignores) | 5 | parseInlineIgnores, isIgnored |
-| `posttool.mjs` | 1 | PostToolUse hook |
+| `forgeSentinel.mjs` | 1 | PostToolUse hook |
 | `assay.mjs` | 4 | Personas, generateAssay, opiniones |
 
 ### Flags adicionales

package/skills/forge/scripts/forgeSentinel-lib.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { buildGraph } from "./graph.mjs";
+import { buildContext } from "./context.mjs";
+import { detectFeaturesOnSrc, allChecks, loadAllInlineIgnores, isIgnored } from "./detect.mjs";
+import { evaluateRules } from "./registry/rules.mjs";
+
+const ROOT = process.cwd();
+
+export async function runSentinelCheck(files, opts = {}) {
+  const { strict = false, reminder = false } = opts;
+
+  if (!files || files.length === 0) {
+    return { violations: [], graphViolations: [], total: 0, hasCritical: false, hasErrors: false, filesChecked: 0, summary: "Sin archivos fuente modificados" };
+  }
+
+  const ctx = await buildContext();
+  const features = detectFeaturesOnSrc();
+  const graph = buildGraph(ROOT);
+  const results = allChecks(features, graph, ctx);
+
+  const allIgnores = loadAllInlineIgnores(join(ROOT, "src"));
+
+  const violations = [];
+  for (const [, cat] of Object.entries(results)) {
+    for (const check of cat.checks) {
+      if (check.pass) continue;
+
+      const touchesFile = files.some(f =>
+        (check.detail && check.detail.includes(f)) ||
+        (check.label && check.label.includes(f))
+      );
+
+      if (!touchesFile && !reminder) continue;
+
+      if (isIgnored(check, allIgnores)) continue;
+
+      violations.push(check);
+    }
+  }
+
+  const graphViolations = evaluateRules(graph, ctx).filter(v => {
+    const touchesFile = files.some(f =>
+      (v.file && v.file.includes(f)) ||
+      (v.from && v.from.includes(f)) ||
+      (v.to && v.to.includes(f))
+    );
+    return touchesFile || reminder;
+  });
+
+  const allViolations = [...violations, ...graphViolations];
+  const hasCritical = allViolations.some(v => v.severity === "CRITICAL");
+  const hasErrors = allViolations.some(v => v.severity === "ERROR");
+
+  return {
+    violations: allViolations,
+    total: allViolations.length,
+    hasCritical,
+    hasErrors,
+    filesChecked: files.length,
+    summary: hasCritical
+      ? `⚠ ${allViolations.length} violación(es) — ${allViolations.filter(v => v.severity === "CRITICAL").length} CRITICAL, ${allViolations.filter(v => v.severity === "ERROR").length} ERROR`
+      : hasErrors
+        ? `⚠ ${allViolations.length} violación(es) — ${allViolations.filter(v => v.severity === "ERROR").length} ERROR`
+        : `${allViolations.length} violación(es) menores (WARNING/INFO)`,
+  };
+}
+
+export function writeAuditLog(env, data, cwd) {
+  try {
+    const dir = join(cwd, ".forge", "audit");
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, "forgeSentinel.json");
+    const log = [];
+    if (existsSync(path)) {
+      try {
+        const existing = JSON.parse(readFileSync(path, "utf-8"));
+        if (Array.isArray(existing)) log.push(...existing);
+      } catch {}
+    }
+    log.push({ ...data, ts: data.ts || new Date().toISOString() });
+    writeFileSync(path, JSON.stringify(log, null, 2) + "\n", "utf-8");
+  } catch {}
+}

package/skills/forge/scripts/forgeSentinel.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { execFileSync } from "child_process";
+import { buildGraph } from "./graph.mjs";
+import { buildContext } from "./context.mjs";
+import { detectFeaturesOnSrc, allChecks, loadAllInlineIgnores, isIgnored } from "./detect.mjs";
+import { evaluateRules } from "./registry/rules.mjs";
+import {
+  CYAN, GREEN, RED, YELLOW, BOLD, RESET, DIM,
+  formatCheck, formatJson,
+} from "./formatter.mjs";
+import { runSentinelCheck, writeAuditLog } from "./forgeSentinel-lib.mjs";
+
+const ROOT = process.cwd();
+
+function getChangedFiles() {
+  let files = [];
+  try {
+    const defaultBranch = execFileSync("git", ["symbolic-ref", "refs/remotes/origin/HEAD"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] })
+      .trim().replace("refs/remotes/origin/", "");
+    const raw = execFileSync("git", ["diff", "--name-only", "--diff-filter=ACMR", `${defaultBranch}...HEAD`], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+    files = raw.trim().split("\n").filter(Boolean);
+  } catch {}
+
+  if (files.length === 0) {
+    try {
+      const raw = execFileSync("git", ["status", "--porcelain"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+      files = raw.split("\n").filter(Boolean).map(l => l.slice(3));
+    } catch {}
+  }
+
+  return files.filter(f => f.startsWith("src/"));
+}
+
+function parseHookEvent(stdin) {
+  if (!stdin) return null;
+  try {
+    const event = JSON.parse(stdin);
+    let files = [];
+
+    // Claude Code format: { toolUse: { name, input: { filePath, content } } }
+    if (event.toolUse?.input?.filePath) {
+      files = [event.toolUse.input.filePath];
+    }
+
+    // Cursor/Codex format: may have files array or filePath property
+    if (Array.isArray(event.files)) {
+      files = event.files.map(f => typeof f === "string" ? f : f.filePath).filter(Boolean);
+    }
+    if (event.filePath) {
+      files.push(event.filePath);
+    }
+
+    return files.length > 0 ? [...new Set(files)] : null;
+  } catch {
+    return null;
+  }
+}
+
+function printResult(result, opts = {}) {
+  const { reminder = false, hook = false } = opts;
+
+  const prefix = hook ? "" : `\n${BOLD}${CYAN}═══ forgeSentinel ═══${RESET}`;
+  if (!hook) console.log(prefix);
+
+  if (result.total === 0) {
+    if (!hook) {
+      console.log(` ${GREEN}✔${RESET} Sin violaciones arquitectónicas en archivos modificados`);
+      console.log(` ${DIM}Archivos revisados: ${result.filesChecked}${RESET}\n`);
+    }
+    return;
+  }
+
+  if (reminder || hook) {
+    if (!hook) {
+      console.log(`  ${YELLOW}Recordatorio:${RESET} ${result.total} violación(es) arquitectónica(s).`);
+      console.log(`  Ejecuta ${CYAN}forge quench${RESET} para ver el detalle completo.\n`);
+    }
+
+    if (result.hasCritical) {
+      const c = result.violations.filter(v => v.severity === "CRITICAL").length;
+      if (hook) {
+        const lines = [`[forgeSentinel] ⚠ ${c} CRITICAL, ${result.violations.filter(v => v.severity === "ERROR").length} ERROR`];
+        const toShow = result.violations.slice(0, 5);
+        for (const v of toShow) {
+          lines.push(`  [${v.severity}] ${v.label}${v.file ? ` (${v.file})` : ""}`);
+        }
+        if (result.violations.length > 5) {
+          lines.push(`  ${DIM}... y ${result.violations.length - 5} más. Ejecutá 'forge quench' para el detalle completo.${RESET}`);
+        }
+        console.log(lines.join("\n"));
+      } else {
+        console.log(`  ${RED}⚠ ${c} violación(es) CRITICAL detectadas${RESET}`);
+      }
+    }
+    if (result.hasErrors) {
+      const e = result.violations.filter(v => v.severity === "ERROR").length;
+      console.log(`  ${RED}⚠ ${e} violación(es) ERROR detectadas${RESET}`);
+    }
+
+    if (!hook) {
+      const toShow = result.violations.slice(0, 5);
+      for (const v of toShow) {
+        console.log(formatCheck(v));
+      }
+      if (result.violations.length > 5) {
+        console.log(`  ${DIM}... y ${result.violations.length - 5} más${RESET}`);
+      }
+      console.log();
+    }
+    return;
+  }
+
+  for (const v of result.violations) {
+    console.log(formatCheck(v));
+  }
+
+  console.log(`\n  ${BOLD}Resumen:${RESET} ${result.summary}`);
+  if (result.hasCritical) {
+    console.log(`  ${RED}⚠ Se requiere acción correctiva antes de continuar${RESET}`);
+  }
+  console.log();
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const isJson = args.includes("--json");
+  const isHook = args.includes("--hook");
+  const reminder = args.includes("--reminder");
+  const isDiff = args.includes("--diff");
+
+  let files;
+  if (isHook) {
+    const chunks = [];
+    if (!process.stdin.isTTY) {
+      for await (const chunk of process.stdin) chunks.push(chunk);
+    }
+    const stdin = Buffer.concat(chunks).toString("utf-8");
+    const hookFiles = parseHookEvent(stdin);
+    if (hookFiles) {
+      files = hookFiles;
+    }
+  }
+
+  if (!files || files.length === 0) {
+    if (isDiff) {
+      files = getChangedFiles();
+    } else {
+      files = args.filter(a => !a.startsWith("--"));
+      if (files.length === 0) {
+        files = getChangedFiles();
+      }
+    }
+  }
+
+  files = (files || []).filter(f =>
+    f.endsWith(".ts") || f.endsWith(".mjs") || f.endsWith(".js") || f.endsWith(".tsx")
+  );
+
+  const result = await runSentinelCheck(files, { strict: false, reminder: reminder || isHook });
+
+  writeAuditLog(process.env, {
+    ts: new Date().toISOString(),
+    hook: isHook ? "forgeSentinel" : "cli",
+    total: result.total,
+    hasCritical: result.hasCritical,
+    hasErrors: result.hasErrors,
+    filesChecked: result.filesChecked,
+  }, ROOT);
+
+  if (isJson) {
+    console.log(formatJson(result));
+  } else {
+    printResult(result, { reminder: reminder || isHook, hook: isHook });
+  }
+
+  process.exit(0);
+}
+
+if (process.argv[1]?.endsWith("forgeSentinel.mjs")) {
+  main().catch(() => process.exit(0));
+}

package/skills/forge/scripts/forgeSmith-admin.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+
+const ROOT = process.cwd();
+const FORGE_DIR = join(ROOT, ".forge");
+const CONFIG_PATH = join(FORGE_DIR, "hooks-config.json");
+const AUDIT_DIR = join(FORGE_DIR, "audit");
+
+const DEFAULT_CONFIG = {
+  forgeSentinel: { enabled: true },
+  forgeSmith: { enabled: true },
+};
+
+function readConfig() {
+  try {
+    if (existsSync(CONFIG_PATH)) {
+      const data = JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+      return { ...DEFAULT_CONFIG, ...data };
+    }
+  } catch {}
+  return { ...DEFAULT_CONFIG };
+}
+
+function writeConfig(config) {
+  mkdirSync(FORGE_DIR, { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+function cmdStatus() {
+  const config = readConfig();
+  const auditPath = join(AUDIT_DIR, "forgeSentinel.json");
+  let lastRun = null;
+  try {
+    if (existsSync(auditPath)) {
+      const log = JSON.parse(readFileSync(auditPath, "utf-8"));
+      if (Array.isArray(log) && log.length > 0) {
+        lastRun = log[log.length - 1];
+      }
+    }
+  } catch {}
+
+  console.log("── forgeSmith-admin ──");
+  console.log(`  forgeSentinel (PostToolUse): ${config.forgeSentinel.enabled ? "✓ activo" : "✘ inactivo"}`);
+  console.log(`  forgeSmith (preToolUse):     ${config.forgeSmith.enabled ? "✓ activo" : "✘ inactivo"}`);
+  if (lastRun) {
+    console.log(`  Último forgeSentinel: ${lastRun.ts} (${lastRun.filesChecked || 0} archivos, ${lastRun.total || 0} violaciones)`);
+  }
+  console.log(`  Config: ${CONFIG_PATH}`);
+}
+
+function cmdOn(hookName) {
+  const config = readConfig();
+  if (hookName === "all" || hookName === "forgeSentinel") {
+    config.forgeSentinel.enabled = true;
+  }
+  if (hookName === "all" || hookName === "forgeSmith") {
+    config.forgeSmith.enabled = true;
+  }
+  writeConfig(config);
+  console.log(`forgeSmith-admin: hooks activados (${hookName})`);
+}
+
+function cmdOff(hookName) {
+  const config = readConfig();
+  if (hookName === "all" || hookName === "forgeSentinel") {
+    config.forgeSentinel.enabled = false;
+  }
+  if (hookName === "all" || hookName === "forgeSmith") {
+    config.forgeSmith.enabled = false;
+  }
+  writeConfig(config);
+  console.log(`forgeSmith-admin: hooks desactivados (${hookName})`);
+}
+
+function cmdReset() {
+  writeConfig(DEFAULT_CONFIG);
+  console.log("forgeSmith-admin: configuración restaurada a valores por defecto");
+}
+
+const [,, action, arg] = process.argv;
+
+switch (action) {
+  case "status":
+    cmdStatus();
+    break;
+  case "on":
+    cmdOn(arg || "all");
+    break;
+  case "off":
+    cmdOff(arg || "all");
+    break;
+  case "reset":
+    cmdReset();
+    break;
+  default:
+    console.log("Uso: node forgeSmith-admin.mjs <status|on|off|reset> [hook-name]");
+    console.log("\n  status              Mostrar estado de hooks");
+    console.log("  on [forgeSentinel|forgeSmith|all]  Activar hook(s)");
+    console.log("  off [forgeSentinel|forgeSmith|all] Desactivar hook(s)");
+    console.log("  reset               Restaurar configuración por defecto");
+    process.exit(1);
+}