@ronaldjdevfs/forge 1.0.2 → 1.2.0

package/skills/forge/scripts/rollback.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+
+/**
+ * rollback.mjs — Backup & rollback para relocate/reforge.
+ *
+ * Uso:
+ *   node rollback.mjs backup <target>        → backup feature/dir
+ *   node rollback.mjs restore <backup-dir>   → restaurar backup
+ *   node rollback.mjs list [target]          → listar backups
+ *   node rollback.mjs verify <backup-dir>    → diff + score check
+ *
+ * Funciones exportadas para uso desde SKILL.md / agente:
+ *   createBackup(target)     → { id, path, timestamp }
+ *   restoreBackup(id)        → boolean
+ *   listBackups(target?)     → BackupMeta[]
+ *   verifyAfterChange()      → { score, improved, suggestedCommit }
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, cpSync, rmSync, statSync } from "fs";
+import { join, relative, resolve, basename } from "path";
+import { execFileSync } from "child_process";
+
+const ROOT = process.cwd();
+const BACKUP_DIR = join(ROOT, ".forge", "backups");
+const TIMESTAMP = () => new Date().toISOString().replace(/[:.]/g, "-");
+
+function sanitize(name) {
+  return name.replace(/[^a-zA-Z0-9_\-/]/g, "_").replace(/\//g, "--");
+}
+
+function shell(cmd, args, cwd = ROOT) {
+  try {
+    return execFileSync(cmd, args, { encoding: "utf-8", cwd }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function createBackup(target) {
+  const targetPath = resolve(ROOT, target);
+  if (!existsSync(targetPath)) {
+    console.error(`rollback: target no existe: ${target}`);
+    return null;
+  }
+
+  const ts = TIMESTAMP();
+  const id = `${sanitize(target)}--${ts}`;
+  const dest = join(BACKUP_DIR, id);
+
+  mkdirSync(dest, { recursive: true });
+  const rel = relative(ROOT, targetPath);
+
+  // Try git stash push -k first (preserves working tree, stashes only target)
+  const gitRoot = shell("git", ["rev-parse", "--show-toplevel"]);
+  let method = "copy";
+  if (gitRoot) {
+    try {
+      shell("git", ["stash", "push", "-k", "--", target]);
+      method = "git-stash";
+      // Copy from git (unstashed) — actually stash pop restores
+      // For git mode, we save the diff instead
+    } catch {
+      // fall through to copy
+    }
+  }
+
+  // Copy files to backup dir
+  if (statSync(targetPath).isDirectory()) {
+    cpSync(targetPath, join(dest, basename(targetPath)), { recursive: true });
+  } else {
+    const parent = join(dest, rel.replace(/\//g, "--"));
+    mkdirSync(parent, { recursive: true });
+    cpSync(targetPath, join(parent, basename(targetPath)));
+  }
+
+  // Save metadata
+  const meta = {
+    id,
+    target: rel,
+    timestamp: new Date().toISOString(),
+    method,
+    files: collectFiles(targetPath),
+  };
+  writeFileSync(join(dest, "backup.json"), JSON.stringify(meta, null, 2) + "\n", "utf-8");
+
+  console.log(`rollback: backup creado → ${rel} (${id})`);
+  return meta;
+}
+
+function collectFiles(targetPath) {
+  if (!statSync(targetPath).isDirectory()) return [targetPath];
+  const files = [];
+  function walk(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else files.push(full);
+    }
+  }
+  walk(targetPath);
+  return files;
+}
+
+export function restoreBackup(id) {
+  const backupPath = join(BACKUP_DIR, id);
+  if (!existsSync(backupPath)) {
+    console.error(`rollback: backup no encontrado: ${id}`);
+    return false;
+  }
+
+  const metaPath = join(backupPath, "backup.json");
+  if (!existsSync(metaPath)) {
+    console.error(`rollback: metadatos no encontrados en ${id}`);
+    return false;
+  }
+
+  const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+  const targetPath = resolve(ROOT, meta.target);
+
+  // Restore files
+  if (existsSync(targetPath)) {
+    rmSync(targetPath, { recursive: true, force: true });
+  }
+
+  const backupData = join(backupPath, basename(targetPath));
+  if (existsSync(backupData)) {
+    cpSync(backupData, targetPath, { recursive: true });
+  }
+
+  console.log(`rollback: restaurado → ${meta.target} (from ${id})`);
+  return true;
+}
+
+export function listBackups(target) {
+  if (!existsSync(BACKUP_DIR)) return [];
+
+  const entries = readdirSync(BACKUP_DIR, { withFileTypes: true });
+  const backups = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const metaPath = join(BACKUP_DIR, entry.name, "backup.json");
+    if (!existsSync(metaPath)) continue;
+
+    try {
+      const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+      if (!target || meta.target.includes(target)) {
+        backups.push(meta);
+      }
+    } catch {
+      // skip invalid
+    }
+  }
+
+  return backups.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+}
+
+export function verifyAfterChange() {
+  try {
+    const out = shell("node", [join(import.meta.url, "..", "inspect.mjs"), "--diff", "--json"]);
+    if (!out) return { score: 0, improved: false, error: "inspect falló" };
+
+    const result = JSON.parse(out);
+    const score = result.total || result.diff?.totalScore || 0;
+    const improved = result.diff?.improved !== false;
+
+    let suggestedCommit = null;
+    if (improved && score > 0) {
+      const branch = shell("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
+      suggestedCommit = `git add -A && git commit -m "forge: relocate/reforge (score: ${score}/110)"`;
+    }
+
+    return { score, improved, suggestedCommit };
+  } catch {
+    return { score: 0, improved: false, error: "verify falló" };
+  }
+}
+
+// ── Export for agent use ──
+export const rollback = { createBackup, restoreBackup, listBackups, verifyAfterChange };
+
+// ── CLI ──
+const [,, action, arg] = process.argv;
+
+if (action === "backup" && arg) {
+  process.exit(createBackup(arg) ? 0 : 1);
+} else if (action === "restore" && arg) {
+  process.exit(restoreBackup(arg) ? 0 : 1);
+} else if (action === "list") {
+  const backups = listBackups(arg);
+  if (backups.length === 0) {
+    console.log("No hay backups disponibles.");
+  } else {
+    console.log("\n── Backups ──\n");
+    for (const b of backups) {
+      const date = b.timestamp.slice(0, 19).replace("T", " ");
+      console.log(`  ${b.id.padEnd(50)} ${date}  (${b.files?.length || 0} archivos)`);
+    }
+    console.log();
+  }
+  process.exit(0);
+} else if (action === "verify") {
+  const result = verifyAfterChange();
+  if (result.error) {
+    console.error(`rollback: ${result.error}`);
+    process.exit(1);
+  }
+  console.log(`Score: ${result.score}/110 | ${result.improved ? "✓ Mejoró/igual" : "✘ Empeoró"}${result.suggestedCommit ? `\nSugerencia: ${result.suggestedCommit}` : ""}`);
+  process.exit(result.improved ? 0 : 1);
+} else {
+  console.log("Uso: node rollback.mjs <backup|restore|list|verify> [target|id]");
+  process.exit(1);
+}

package/skills/forge/scripts/update.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+/**
+ * forge update — Version check contra forge.dev/latest.
+ * Cache de 24h en .forge/version-cache.json.
+ * No auto-actualiza; solo notifica.
+ *
+ * Uso:
+ *   node update.mjs
+ *   node update.mjs --json
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+
+const ROOT = process.cwd();
+const CACHE_PATH = join(ROOT, ".forge", "version-cache.json");
+const CACHE_TTL = 86400000; // 24h
+const VERSION_URL = "https://forge.dev/latest";
+const CURRENT_VERSION = "1.0.2";
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(path, data) {
+  try {
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function fetchLatestVersion() {
+  try {
+    const response = await fetch(VERSION_URL, { signal: AbortSignal.timeout(5000) });
+    if (!response.ok) return null;
+    const data = await response.json();
+    return data.version || data.latest || null;
+  } catch {
+    return null;
+  }
+}
+
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const na = pa[i] || 0;
+    const nb = pb[i] || 0;
+    if (na > nb) return 1;
+    if (na < nb) return -1;
+  }
+  return 0;
+}
+
+async function main() {
+  const isJson = process.argv.includes("--json");
+
+  // Check cache
+  const cached = readJson(CACHE_PATH);
+  if (cached && cached.timestamp && (Date.now() - cached.timestamp) < CACHE_TTL) {
+    const cmp = compareVersions(cached.latest, CURRENT_VERSION);
+    const updateAvailable = cmp > 0;
+
+    if (isJson) {
+      console.log(JSON.stringify({ current: CURRENT_VERSION, latest: cached.latest, updateAvailable, changelog: cached.changelog || null, cached: true }, null, 2));
+    } else if (updateAvailable) {
+      console.log(`📦 Forge ${cached.latest} disponible (tienes ${CURRENT_VERSION}).`);
+      if (cached.changelog) console.log(`   Changelog: ${cached.changelog}`);
+      console.log("   Para actualizar: npm install -g @ronaldjdevfs/forge");
+    } else {
+      console.log(`Forge ${CURRENT_VERSION} — última versión.`);
+    }
+    process.exit(0);
+  }
+
+  // Fetch from network
+  const latest = await fetchLatestVersion();
+  if (!latest) {
+    if (isJson) {
+      console.log(JSON.stringify({ current: CURRENT_VERSION, latest: null, error: "No se pudo conectar con forge.dev/latest" }, null, 2));
+    } else {
+      console.log("No se pudo verificar versión. Revisa tu conexión.");
+    }
+    process.exit(0);
+  }
+
+  // Update cache
+  writeJson(CACHE_PATH, { latest, timestamp: Date.now(), changelog: null });
+
+  const cmp = compareVersions(latest, CURRENT_VERSION);
+  const updateAvailable = cmp > 0;
+
+  if (isJson) {
+    console.log(JSON.stringify({ current: CURRENT_VERSION, latest, updateAvailable }, null, 2));
+  } else if (updateAvailable) {
+    console.log(`📦 Forge ${latest} disponible (tienes ${CURRENT_VERSION}).`);
+    console.log("   Para actualizar: npm install -g @ronaldjdevfs/forge");
+  } else {
+    console.log(`Forge ${CURRENT_VERSION} — última versión.`);
+  }
+  process.exit(0);
+}
+
+if (process.argv[1] && (process.argv[1].endsWith("update.mjs") || process.argv[1].endsWith("update.js"))) {
+  main().catch(console.error);
+}

package/skills/forge/templates/agents/claude/CLAUDE.md

@@ -0,0 +1,98 @@
+# Forge — Backend Architecture Operating System
+
+Forge es un sistema operativo arquitectónico para backend. Diseña, construye, audita y evoluciona arquitecturas basadas en **Arquitectura Hexagonal**, **DDD pragmático** y **vertical slices**.
+
+## Boot Sequence
+
+Ejecutar en orden antes de cualquier acción:
+
+1. `node .opencode/skills/forge/scripts/context.mjs` — stack + layers detection
+2. `node .opencode/skills/forge/scripts/armorer.mjs` — ownership, orphans, duplicates
+3. `node .opencode/skills/forge/scripts/profile.mjs --extended` — tech profile
+4. `node .opencode/skills/forge/scripts/graph.mjs --json` — 4-layer graph
+5. `node .opencode/skills/forge/scripts/chain.mjs --json` — dependency analysis
+6. `node .opencode/skills/forge/scripts/inspect.mjs --json` — full audit
+7. `node .opencode/skills/forge/scripts/architecture.mjs` — update ARCHITECTURE.md
+8. Execute user command (cast, quench, relocate, etc.)
+9. Run architecture.mjs again
+
+## Architecture Model
+
+Cuatro capas obligatorias:
+
+| Layer | Propósito |
+|-------|-----------|
+| `src/platform/` | config, database, http, server, logger, cache, security, events, di |
+| `src/features/<name>/` | domain/, application/use-cases/, application/mappers/, adapters/in/http/, adapters/out/persistence/ |
+| `src/shared/` | errors/, contracts/, types/, utils/ (puro, sin lógica de negocio) |
+| `src/infra/` | prisma/, mongodb/, redis/, mail/ (implementaciones, sin reglas de negocio) |
+
+### Dependency Rules
+
+**Permitido:** `feature → platform`, `feature → shared`, `platform → infra`, `adapter → infra`, `feature → domain`
+
+**Prohibido (CRITICAL):**
+- R1: `feature → infra`
+- R2: `platform → feature`
+- R3: `shared → feature`
+- R4: `shared → infra`
+- R5: `domain → infra`
+- R6: `domain → platform`
+- R7: `infra → feature`
+- R8: cross-feature direct imports
+- R9: cycles
+
+## Naming Conventions
+
+| Elemento | Formato |
+|----------|---------|
+| Directorios | `kebab-case/` |
+| Archivos | `<PascalCase>.<artefacto>.ts` |
+| Interfaces | `I<PascalCase>.<artefacto>.ts` |
+| Use cases | `<Action>.uc.ts` |
+| Clases | `PascalCase` |
+| Funciones/variables | `camelCase` |
+| Constantes | `UPPER_SNAKE_CASE` |
+| Barrel files | `index.ts` con named exports, no `export default` |
+| Imports ESM | con extensión `.js`: `import { X } from "./foo.js"` |
+
+## Commands
+
+| Comando | Acción |
+|---------|--------|
+| `forge` | Init project (context + bootstrap + profile + graph) |
+| `cast` | New feature (verifica platform/shared/infra primero) |
+| `inspect` | Full audit (6 categorías, 110pts → 0-100) |
+| `quench` | Validate dependency rules |
+| `chain` | Topological dependency sort |
+| `graph` | Architecture graph con R1-R9 |
+| `armorer` | Ownership report (orphans, duplicates, misplaced) |
+| `smelt` | Extract code to shared/ |
+| `relocate` | Migrate legacy to platform/, shared/, infra/ or features/ |
+| `reforge` | Refactor considering all 4 layers |
+| `temper` | Harden DI (constructor injection) |
+| `inscribe` | Generate ARCHITECTURE.md |
+
+## Architecture Principles
+
+1. **Hexagonal basado en features** — unidad de organización = feature, no capa técnica
+2. **DDD ligero** — sin sobreingeniería, pragmatismo sobre dogma
+3. **Separación dominio e infraestructura** — domain/ no sabe de frameworks ni BD
+4. **Feature autónomo** — todo lo del dominio vive dentro de `features/<name>/`
+5. **Dependencias unidireccionales** — `adapters → application → domain → (nada)`
+6. **Cero lógica en controllers** — parsean, delegan, responden
+7. **Cero BD fuera de repositories** — única puerta a datos
+8. **DI disciplinada** — constructor injection, sin service locators
+9. **Errores tipados** — clases explícitas, no `throw Error()`
+10. **Grafo arquitectónico vivo** — todo componente es un nodo, toda relación un edge validado
+
+## Key Files
+
+- `skills/forge/SKILL.md` — orchestrator principal
+- `skills/forge/reference/principles.md` — manifiesto y 15 principios
+- `skills/forge/reference/patterns.md` — naming conventions
+- `skills/forge/scripts/` — context, detect, inspect, chain, profile, graph, architecture, armorer, bootstrap
+- `skills/forge/profiles/` — 10 tech profiles (express, fastify, nestjs × mongodb, postgres, prisma, drizzle)
+- `skills/forge/templates/` — templates para feature, platform, shared, infra
+- `AGENTS.md` — guía para agentes de IA
+- `ARCHITECTURE.md` — estado actual de la arquitectura

package/skills/forge/templates/agents/cursor/.cursorrules

@@ -0,0 +1,80 @@
+You are an AI assistant for a project that uses Forge — a Backend Architecture Operating System. Tu función es ayudar a diseñar, construir, auditar y evolucionar la arquitectura usando Arquitectura Hexagonal, DDD pragmático y vertical slices.
+
+## Architecture Model
+
+The project uses four mandatory layers:
+
+```
+src/
+├── platform/          # Config, database, http, server, logger, cache, security, events, di
+├── features/<name>/   # domain/, application/use-cases/, application/mappers/, adapters/in/http/, adapters/out/persistence/
+├── shared/            # errors/, contracts/, types/, utils/ (pure code, no business logic)
+└── infra/             # prisma/, mongodb/, redis/, mail/ (implementations, no business rules)
+```
+
+## Dependency Rules (CRITICAL — never violate)
+
+**Allowed:** `feature → platform`, `feature → shared`, `platform → infra`, `adapter → infra`, `feature → domain`
+
+**Prohibited:**
+- R1: `feature → infra`
+- R2: `platform → feature`
+- R3: `shared → feature`
+- R4: `shared → infra`
+- R5: `domain → infra`
+- R6: `domain → platform`
+- R7: `infra → feature`
+- R8: cross-feature direct imports
+- R9: cycles
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Directories | `kebab-case/` | `credit-card/` |
+| Files | `<PascalCase>.<artifact>.ts` | `User.entity.ts` |
+| Interfaces | `I<PascalCase>.<artifact>.ts` | `IUser.repository.ts` |
+| Use cases | `<Action>.uc.ts` | `CreateUser.uc.ts` |
+| Classes | `PascalCase` | `UserController` |
+| Functions/vars | `camelCase` | `formatDate` |
+| Constants | `UPPER_SNAKE_CASE` | `MAX_RETRY_COUNT` |
+| Barrels | `index.ts` | named exports only, no `export default` |
+| ESM imports | with `.js` extension | `import { X } from "./foo.js"` |
+
+## Code Principles
+
+1. **Zero business logic in controllers** — parse, delegate, respond
+2. **Zero DB access outside repositories** — only repositories touch the database
+3. **Constructor injection only** — no service locators, no `container.resolve()` in business logic
+4. **Typed domain errors** — explicit error classes, never generic `throw Error()`
+5. **Unidirectional dependencies** — `adapters → application → domain → (nothing)`
+6. **Domain knows nothing about infrastructure** — no framework, database, or external service imports in domain/
+7. **Features are autonomous** — no direct imports between features, only via injected interfaces
+8. **Explicit over magic** — prefer explicit imports and declared types over hidden decorators
+
+## Available Commands
+
+| Command | Action |
+|---------|--------|
+| `forge` | Initialize project |
+| `cast` | Create new feature |
+| `inspect` | Full architecture audit |
+| `quench` | Validate dependency rules |
+| `chain` | Dependency graph (topological) |
+| `graph` | Architecture graph with rules |
+| `armorer` | Ownership report |
+| `smelt` | Extract to shared/ |
+| `relocate` | Migrate legacy code |
+| `reforge` | Refactor architecture |
+| `temper` | Harden dependency injection |
+| `inscribe` | Generate ARCHITECTURE.md |
+
+## Key Files Reference
+
+- `skills/forge/SKILL.md` — orchestrator
+- `skills/forge/reference/principles.md` — 15 principles
+- `skills/forge/reference/patterns.md` — naming conventions
+- `skills/forge/scripts/` — all engine scripts
+- `skills/forge/profiles/` — tech profiles
+- `AGENTS.md` — agent guide
+- `ARCHITECTURE.md` — current architecture state

package/skills/forge/templates/feature/domain-error.ts.md

@@ -0,0 +1,9 @@
+```typescript
+// src/features/<domain>/domain/errors/<Domain>NotFound.error.ts
+export class <Domain>NotFoundError extends Error {
+  constructor(id: string) {
+    super(`<Domain> with id ${id} not found`);
+    this.name = "<Domain>NotFoundError";
+  }
+}
+```

package/skills/forge/templates/feature/domain-event.ts.md

@@ -0,0 +1,9 @@
+```typescript
+// src/features/<domain>/domain/events/<Domain>Created.event.ts
+export class <Domain>CreatedEvent {
+  constructor(
+    public readonly <domain>Id: string,
+    public readonly occurredAt: Date = new Date(),
+  ) {}
+}
+```

package/skills/forge/templates/feature/event-handler.ts.md

@@ -0,0 +1,10 @@
+```typescript
+// src/features/<domain>/adapters/out/events/<Domain>Created.handler.ts
+import type { <Domain>CreatedEvent } from "../../domain/events/<Domain>Created.event.js";
+
+export class <Domain>CreatedHandler {
+  async handle(event: <Domain>CreatedEvent): Promise<void> {
+    // Reaccionar al evento (ej: enviar email, notificar, auditar)
+  }
+}
+```

package/skills/forge/templates/feature/use-case.ts.md

@@ -4,16 +4,24 @@ import { injectable, inject } from "tsyringe";
 import type { <Domain> } from "../../domain/<Domain>.entity.js";
 import type { I<Domain>Repository } from "../../domain/I<Domain>.repository.js";
 import { UseCaseError } from "@/shared/errors/UseCaseError.js";
+// Opcional: errores de dominio y eventos
+// import { <Domain>NotFoundError } from "../../domain/errors/<Domain>NotFound.error.js";
+// import type { IEventBus } from "@/platform/events/IEventBus.js";
+// import { <Domain>CreatedEvent } from "../../domain/events/<Domain>Created.event.js";
 
 @injectable()
 export class Create<Domain> {
   constructor(
-    @inject(I<Domain>Repository) private readonly repo: I<Domain>Repository
+    @inject(I<Domain>Repository) private readonly repo: I<Domain>Repository,
+    // @inject(IEventBus) private readonly eventBus: IEventBus,
   ) {}
 
   async execute(data: Partial<<Domain>>): Promise<<Domain>> {
     if (!data) throw new UseCaseError("Datos requeridos");
-    return this.repo.create(data);
+    const created = await this.repo.create(data);
+    // Opcional: emitir evento de dominio
+    // this.eventBus.publish(new <Domain>CreatedEvent(created.id));
+    return created;
   }
 }
 ```