@umbral/cli 0.0.1

package/dist/index.js

@@ -0,0 +1,1223 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/detect/node.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+var NodeDetector = class {
+  detect(projectPath) {
+    const pkgPath = join(projectPath, "package.json");
+    if (!existsSync(pkgPath)) return [];
+    const results = [];
+    let pkg;
+    try {
+      pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    } catch {
+      return [];
+    }
+    const engines = pkg.engines;
+    const nodeVersion = engines?.node ?? "";
+    results.push({
+      category: "runtime",
+      name: `Node.js${nodeVersion ? ` (${nodeVersion})` : ""}`,
+      slug: "nodejs",
+      confidence: 1,
+      evidence: ["package.json existe"],
+      metadata: { nodeVersion }
+    });
+    if (existsSync(join(projectPath, "pnpm-lock.yaml"))) {
+      results.push({ category: "package-manager", name: "pnpm", slug: "pnpm", confidence: 1, evidence: ["pnpm-lock.yaml"], metadata: {} });
+    } else if (existsSync(join(projectPath, "yarn.lock"))) {
+      results.push({ category: "package-manager", name: "Yarn", slug: "yarn", confidence: 1, evidence: ["yarn.lock"], metadata: {} });
+    } else if (existsSync(join(projectPath, "bun.lockb"))) {
+      results.push({ category: "package-manager", name: "Bun", slug: "bun", confidence: 1, evidence: ["bun.lockb"], metadata: {} });
+    } else if (existsSync(join(projectPath, "package-lock.json"))) {
+      results.push({ category: "package-manager", name: "npm", slug: "npm", confidence: 1, evidence: ["package-lock.json"], metadata: {} });
+    }
+    return results;
+  }
+};
+
+// src/detect/framework.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
+function readDeps(projectPath) {
+  try {
+    const pkg = JSON.parse(readFileSync2(join2(projectPath, "package.json"), "utf-8"));
+    return {
+      deps: pkg.dependencies ?? {},
+      devDeps: pkg.devDependencies ?? {}
+    };
+  } catch {
+    return { deps: {}, devDeps: {} };
+  }
+}
+var FrameworkDetector = class {
+  detect(projectPath) {
+    const { deps, devDeps } = readDeps(projectPath);
+    const all = { ...devDeps, ...deps };
+    const results = [];
+    if (all["next"]) {
+      const version = deps["next"] ?? devDeps["next"] ?? "";
+      const hasAppDir = existsSync2(join2(projectPath, "app")) || existsSync2(join2(projectPath, "src", "app"));
+      const hasPagesDir = existsSync2(join2(projectPath, "pages")) || existsSync2(join2(projectPath, "src", "pages"));
+      const router = hasAppDir ? "App Router" : hasPagesDir ? "Pages Router" : "App Router";
+      const slug = hasAppDir || !hasPagesDir ? "nextjs-app-router" : "nextjs-pages";
+      results.push({
+        category: "framework",
+        name: `Next.js ${version.replace("^", "")} (${router})`,
+        slug,
+        confidence: 1,
+        evidence: [`next@${version} en dependencies`, `${router} detectado`],
+        metadata: { version: version.replace("^", ""), router: router.toLowerCase() }
+      });
+    } else if (all["nuxt"]) {
+      results.push({ category: "framework", name: "Nuxt", slug: "nuxt", confidence: 1, evidence: ["nuxt en dependencies"], metadata: {} });
+    } else if (all["@remix-run/node"] || all["@remix-run/react"]) {
+      results.push({ category: "framework", name: "Remix", slug: "remix", confidence: 1, evidence: ["@remix-run en dependencies"], metadata: {} });
+    } else if (all["express"]) {
+      results.push({ category: "framework", name: "Express.js", slug: "express", confidence: 1, evidence: ["express en dependencies"], metadata: {} });
+    } else if (all["hono"]) {
+      results.push({ category: "framework", name: "Hono", slug: "hono", confidence: 1, evidence: ["hono en dependencies"], metadata: {} });
+    } else if (all["fastify"]) {
+      results.push({ category: "framework", name: "Fastify", slug: "fastify", confidence: 1, evidence: ["fastify en dependencies"], metadata: {} });
+    }
+    return results;
+  }
+};
+
+// src/detect/database.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { join as join3 } from "path";
+function readDeps2(projectPath) {
+  try {
+    const pkg = JSON.parse(readFileSync3(join3(projectPath, "package.json"), "utf-8"));
+    return { ...pkg.devDependencies ?? {}, ...pkg.dependencies ?? {} };
+  } catch {
+    return {};
+  }
+}
+function detectPrismaProvider(projectPath) {
+  const schemaPath = join3(projectPath, "prisma", "schema.prisma");
+  if (!existsSync3(schemaPath)) return null;
+  try {
+    const content = readFileSync3(schemaPath, "utf-8");
+    const match = content.match(/provider\s*=\s*"(\w+)"/);
+    return match?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+var DatabaseDetector = class {
+  detect(projectPath) {
+    const deps = readDeps2(projectPath);
+    const results = [];
+    if (deps["@prisma/client"] || deps["prisma"]) {
+      const provider = detectPrismaProvider(projectPath);
+      const dbName = provider === "postgresql" ? "PostgreSQL" : provider === "mysql" ? "MySQL" : provider === "sqlite" ? "SQLite" : provider === "mongodb" ? "MongoDB" : "SQL";
+      const slug = `${(provider ?? "sql").toLowerCase()}-prisma`;
+      results.push({
+        category: "database",
+        name: `${dbName} (Prisma)`,
+        slug,
+        confidence: provider ? 1 : 0.7,
+        evidence: [
+          "@prisma/client en dependencies",
+          ...provider ? [`provider: ${provider} en prisma/schema.prisma`] : []
+        ],
+        metadata: { orm: "prisma", provider: provider ?? "unknown" }
+      });
+    } else if (deps["drizzle-orm"]) {
+      const hasPostgres = !!deps["pg"] || !!deps["postgres"] || !!deps["@neondatabase/serverless"];
+      const slug = hasPostgres ? "postgresql-drizzle" : "sql-drizzle";
+      results.push({
+        category: "database",
+        name: `${hasPostgres ? "PostgreSQL" : "SQL"} (Drizzle)`,
+        slug,
+        confidence: 0.9,
+        evidence: ["drizzle-orm en dependencies"],
+        metadata: { orm: "drizzle" }
+      });
+    } else if (deps["mongoose"]) {
+      results.push({
+        category: "database",
+        name: "MongoDB (Mongoose)",
+        slug: "mongodb-mongoose",
+        confidence: 1,
+        evidence: ["mongoose en dependencies"],
+        metadata: { orm: "mongoose" }
+      });
+    } else if (deps["better-sqlite3"]) {
+      results.push({
+        category: "database",
+        name: "SQLite (better-sqlite3)",
+        slug: "sqlite-bettersqlite3",
+        confidence: 1,
+        evidence: ["better-sqlite3 en dependencies"],
+        metadata: { orm: "better-sqlite3" }
+      });
+    } else if (deps["pg"]) {
+      results.push({
+        category: "database",
+        name: "PostgreSQL (pg)",
+        slug: "postgresql-pg",
+        confidence: 0.9,
+        evidence: ["pg en dependencies"],
+        metadata: { orm: "pg" }
+      });
+    }
+    return results;
+  }
+};
+
+// src/detect/testing.ts
+import { readFileSync as readFileSync4 } from "fs";
+import { join as join4 } from "path";
+var TestingDetector = class {
+  detect(projectPath) {
+    let deps = {};
+    try {
+      const pkg = JSON.parse(readFileSync4(join4(projectPath, "package.json"), "utf-8"));
+      deps = { ...pkg.devDependencies ?? {}, ...pkg.dependencies ?? {} };
+    } catch {
+      return [];
+    }
+    if (deps["vitest"]) {
+      return [{ category: "testing", name: "Vitest", slug: "vitest", confidence: 1, evidence: ["vitest en devDependencies"], metadata: {} }];
+    }
+    if (deps["jest"]) {
+      return [{ category: "testing", name: "Jest", slug: "jest", confidence: 1, evidence: ["jest en devDependencies"], metadata: {} }];
+    }
+    if (deps["@playwright/test"]) {
+      return [{ category: "testing", name: "Playwright", slug: "playwright", confidence: 1, evidence: ["@playwright/test en devDependencies"], metadata: {} }];
+    }
+    if (deps["cypress"]) {
+      return [{ category: "testing", name: "Cypress", slug: "cypress", confidence: 1, evidence: ["cypress en devDependencies"], metadata: {} }];
+    }
+    return [];
+  }
+};
+
+// src/detect/build.ts
+import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
+import { join as join5 } from "path";
+var BuildDetector = class {
+  detect(projectPath) {
+    const results = [];
+    if (existsSync4(join5(projectPath, "turbo.json"))) {
+      results.push({ category: "build", name: "Turborepo", slug: "turborepo", confidence: 1, evidence: ["turbo.json existe"], metadata: {} });
+    } else if (existsSync4(join5(projectPath, "nx.json"))) {
+      results.push({ category: "build", name: "Nx", slug: "nx", confidence: 1, evidence: ["nx.json existe"], metadata: {} });
+    }
+    let deps = {};
+    try {
+      const pkg = JSON.parse(readFileSync5(join5(projectPath, "package.json"), "utf-8"));
+      deps = { ...pkg.devDependencies ?? {}, ...pkg.dependencies ?? {} };
+    } catch {
+      return results;
+    }
+    if (!results.length && deps["vite"]) {
+      results.push({ category: "build", name: "Vite", slug: "vite", confidence: 0.8, evidence: ["vite en devDependencies"], metadata: {} });
+    }
+    return results;
+  }
+};
+
+// src/detect/styling.ts
+import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
+import { join as join6 } from "path";
+var StylingDetector = class {
+  detect(projectPath) {
+    let deps = {};
+    try {
+      const pkg = JSON.parse(readFileSync6(join6(projectPath, "package.json"), "utf-8"));
+      deps = { ...pkg.devDependencies ?? {}, ...pkg.dependencies ?? {} };
+    } catch {
+      return [];
+    }
+    if (deps["tailwindcss"]) {
+      const hasConfig = existsSync5(join6(projectPath, "tailwind.config.ts")) || existsSync5(join6(projectPath, "tailwind.config.js"));
+      return [{
+        category: "styling",
+        name: "Tailwind CSS",
+        slug: "tailwindcss",
+        confidence: hasConfig ? 1 : 0.8,
+        evidence: ["tailwindcss en devDependencies", ...hasConfig ? ["tailwind.config.* existe"] : []],
+        metadata: {}
+      }];
+    }
+    if (deps["styled-components"]) {
+      return [{ category: "styling", name: "Styled Components", slug: "styled-components", confidence: 1, evidence: ["styled-components en dependencies"], metadata: {} }];
+    }
+    if (deps["sass"] || deps["node-sass"]) {
+      return [{ category: "styling", name: "Sass", slug: "sass", confidence: 1, evidence: ["sass en devDependencies"], metadata: {} }];
+    }
+    return [];
+  }
+};
+
+// src/analyze.ts
+var DETECTORS = [
+  new NodeDetector(),
+  new FrameworkDetector(),
+  new DatabaseDetector(),
+  new TestingDetector(),
+  new BuildDetector(),
+  new StylingDetector()
+];
+function analyzeProject(projectPath) {
+  const detections = DETECTORS.flatMap((d) => d.detect(projectPath));
+  detections.sort((a, b) => b.confidence - a.confidence);
+  return { projectPath, detections };
+}
+
+// src/templates.ts
+var TEMPLATES = [
+  {
+    slugs: ["nextjs-app-router"],
+    cognitiveLevel: "navigator",
+    complexityTier: 2,
+    title: () => "Next.js App Router como framework frontend",
+    decision: (d) => `El frontend utiliza Next.js ${d.metadata.version ?? ""} con App Router para renderizado y routing.`.trim(),
+    mechanism: () => "App Router con Server Components por defecto. Rutas en app/. API routes en app/api/. Client Components marcados explicitamente con 'use client'.",
+    rationale: () => "Next.js App Router provee Server Components, streaming y layouts anidados. Simplifica el data-fetching server-side y mejora el rendimiento versus client-side rendering puro.",
+    alternatives: () => [
+      { option: "Pages Router", rejectedBecause: "Patron legacy; App Router es el futuro de Next.js." },
+      { option: "Remix", rejectedBecause: "Ecosistema mas reducido; Next.js tiene mayor adopcion y soporte." }
+    ],
+    antiPatterns: () => [
+      "No usar 'use client' en componentes que pueden ser Server Components.",
+      "No hacer fetch de datos en componentes cliente cuando un Server Component puede hacerlo.",
+      "No importar modulos de servidor (fs, db) en componentes cliente."
+    ]
+  },
+  {
+    slugs: ["nextjs-pages"],
+    cognitiveLevel: "navigator",
+    complexityTier: 2,
+    title: () => "Next.js Pages Router como framework frontend",
+    decision: (d) => `El frontend utiliza Next.js ${d.metadata.version ?? ""} con Pages Router.`.trim(),
+    mechanism: () => "Pages Router con getServerSideProps/getStaticProps para data-fetching. Rutas basadas en la estructura de pages/.",
+    rationale: () => "Pages Router es el modelo estable y probado de Next.js. El proyecto ya esta estructurado con este patron.",
+    alternatives: () => [
+      { option: "App Router", rejectedBecause: "Requiere migracion significativa del codebase existente." }
+    ],
+    antiPatterns: () => [
+      "No mezclar patrones de App Router (server components) con Pages Router.",
+      "No hacer fetching de datos en el cliente si getServerSideProps puede proveerlos."
+    ]
+  },
+  {
+    slugs: ["express"],
+    cognitiveLevel: "navigator",
+    complexityTier: 1,
+    title: () => "Express.js como servidor HTTP",
+    decision: () => "El backend utiliza Express.js como servidor HTTP principal.",
+    mechanism: () => "Middlewares encadenados para request processing. Rutas definidas con app.get/post/etc. Error handling centralizado.",
+    rationale: () => "Express es el framework HTTP mas adoptado en Node.js. Ecosistema maduro de middlewares y amplia documentacion.",
+    alternatives: () => [
+      { option: "Fastify", rejectedBecause: "Menor base de middlewares existentes." },
+      { option: "Hono", rejectedBecause: "Framework mas nuevo con menor adopcion." }
+    ],
+    antiPatterns: () => [
+      "No manejar errores async sin try-catch o middleware de error.",
+      "No almacenar estado mutable en variables globales del servidor."
+    ]
+  },
+  {
+    slugs: ["postgresql-prisma"],
+    cognitiveLevel: "anchor",
+    complexityTier: 2,
+    title: () => "PostgreSQL via Prisma ORM como persistencia relacional",
+    decision: () => "La persistencia relacional utiliza PostgreSQL con Prisma ORM para type-safety y migraciones.",
+    mechanism: () => "Prisma schema en prisma/schema.prisma define los modelos. Migraciones via prisma migrate. Cliente generado provee queries type-safe.",
+    rationale: () => "Prisma genera tipos TypeScript desde el schema, eliminando divergencia entre modelo de datos y codigo. Las migraciones son declarativas y reproducibles.",
+    alternatives: () => [
+      { option: "Drizzle ORM", rejectedBecause: "Menor madurez en tooling de migraciones." },
+      { option: "TypeORM", rejectedBecause: "Decoradores y patrones Active Record anaden complejidad." },
+      { option: "SQL crudo", rejectedBecause: "Sin type-safety; propenso a errores en queries complejas." }
+    ],
+    antiPatterns: () => [
+      "No ejecutar queries SQL crudas fuera de Prisma si el ORM lo soporta.",
+      "No modificar el schema de la DB sin crear una migracion.",
+      "No ignorar las validaciones de tipos generados por Prisma."
+    ]
+  },
+  {
+    slugs: ["postgresql-drizzle", "sql-drizzle"],
+    cognitiveLevel: "anchor",
+    complexityTier: 2,
+    title: () => "PostgreSQL via Drizzle ORM",
+    decision: () => "La persistencia utiliza Drizzle ORM para queries SQL type-safe con control granular.",
+    mechanism: () => "Schema definido en TypeScript con drizzle-kit para migraciones. Queries builder type-safe sin magic strings.",
+    rationale: () => "Drizzle ofrece control SQL granular con type-safety completo. Menor overhead que ORMs tradicionales.",
+    alternatives: () => [
+      { option: "Prisma", rejectedBecause: "Mayor abstraccion que puede ocultar queries ineficientes." }
+    ],
+    antiPatterns: () => [
+      "No mezclar queries raw SQL con el query builder de Drizzle.",
+      "No modificar tablas sin generar migraciones con drizzle-kit."
+    ]
+  },
+  {
+    slugs: ["mongodb-mongoose"],
+    cognitiveLevel: "anchor",
+    complexityTier: 2,
+    title: () => "MongoDB via Mongoose como persistencia documental",
+    decision: () => "La persistencia utiliza MongoDB con Mongoose para modelado de documentos.",
+    mechanism: () => "Schemas de Mongoose definen la estructura de documentos. Validacion en la capa de aplicacion. Indices definidos en el schema.",
+    rationale: () => "MongoDB permite esquemas flexibles para datos no-relacionales. Mongoose agrega validacion y tipado sobre la API nativa.",
+    alternatives: () => [
+      { option: "PostgreSQL", rejectedBecause: "Requiere esquema rigido para datos con estructura variable." }
+    ],
+    antiPatterns: () => [
+      "No almacenar relaciones complejas que requieren joins frecuentes.",
+      "No omitir indices en campos usados en queries frecuentes."
+    ]
+  },
+  {
+    slugs: ["sqlite-bettersqlite3"],
+    cognitiveLevel: "anchor",
+    complexityTier: 1,
+    title: () => "SQLite via better-sqlite3 como persistencia local",
+    decision: () => "La persistencia utiliza SQLite con better-sqlite3 para almacenamiento local sin servidor.",
+    mechanism: () => "Base de datos en un unico archivo. Queries sincronas via better-sqlite3. WAL mode para lecturas concurrentes.",
+    rationale: () => "SQLite elimina la necesidad de un servidor de base de datos externo. Ideal para aplicaciones local-first y embebidas.",
+    alternatives: () => [
+      { option: "PostgreSQL", rejectedBecause: "Requiere servidor externo; over-engineering para uso local." }
+    ],
+    antiPatterns: () => [
+      "No abrir multiples conexiones de escritura concurrentes.",
+      "No usar SQLite para cargas de escritura masivas concurrentes."
+    ]
+  },
+  {
+    slugs: ["mysql-prisma"],
+    cognitiveLevel: "anchor",
+    complexityTier: 2,
+    title: () => "MySQL via Prisma ORM como persistencia relacional",
+    decision: () => "La persistencia relacional utiliza MySQL con Prisma ORM.",
+    mechanism: () => "Prisma schema define los modelos con provider mysql. Migraciones via prisma migrate.",
+    rationale: () => "MySQL es un motor relacional maduro y ampliamente soportado. Prisma agrega type-safety y migraciones declarativas.",
+    alternatives: () => [
+      { option: "PostgreSQL", rejectedBecause: "Proyecto ya configurado con MySQL." }
+    ],
+    antiPatterns: () => [
+      "No ejecutar queries crudas fuera de Prisma.",
+      "No modificar el schema sin generar migraciones."
+    ]
+  },
+  {
+    slugs: ["turborepo"],
+    cognitiveLevel: "navigator",
+    complexityTier: 2,
+    title: () => "Turborepo como orquestador de monorepo",
+    decision: () => "El monorepo utiliza Turborepo para orquestacion de builds, tests y tareas.",
+    mechanism: () => "turbo.json define el pipeline de tareas con dependsOn y cache. Cada paquete declara sus scripts en package.json.",
+    rationale: () => "Turborepo provee caching incremental y ejecucion paralela. Reduce tiempos de build significativamente en monorepos.",
+    alternatives: () => [
+      { option: "Nx", rejectedBecause: "Mayor complejidad de configuracion para proyectos medianos." },
+      { option: "Lerna", rejectedBecause: "Menor rendimiento sin caching nativo." }
+    ],
+    antiPatterns: () => [
+      "No saltarse el pipeline de Turbo ejecutando scripts directamente en paquetes interdependientes.",
+      "No ignorar los outputs de cache en turbo.json."
+    ]
+  }
+];
+function getTemplate(detection) {
+  return TEMPLATES.find((t) => t.slugs.includes(detection.slug)) ?? null;
+}
+
+// src/generate.ts
+function generateProposals(detections) {
+  const proposals = [];
+  let counter = 1;
+  for (const detection of detections) {
+    const template = getTemplate(detection);
+    if (!template) continue;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const id = `EDE-${String(counter).padStart(3, "0")}-${detection.slug}`;
+    proposals.push({
+      id,
+      title: template.title(detection),
+      version: 1,
+      status: "proposed",
+      cognitiveLevel: template.cognitiveLevel,
+      complexityTier: template.complexityTier,
+      whatAndHow: {
+        decision: template.decision(detection),
+        mechanism: template.mechanism(detection)
+      },
+      why: {
+        rationale: template.rationale(detection),
+        alternativesConsidered: template.alternatives(detection),
+        references: []
+      },
+      whatNotToDo: {
+        antiPatterns: template.antiPatterns(detection)
+      },
+      whatsNext: {
+        continuations: [],
+        openQuestions: []
+      },
+      contracts: {
+        layerContracts: [],
+        verifiedBy: []
+      },
+      tests: {
+        unitTests: [],
+        sadPaths: [],
+        coverageTarget: 0.8
+      },
+      provenance: {
+        phase: "onboarding",
+        slice: null,
+        createdBy: "umbral-cli",
+        createdAt: now,
+        lastUpdated: now
+      }
+    });
+    counter++;
+  }
+  return proposals;
+}
+
+// src/ui.ts
+import { createInterface } from "readline/promises";
+import { stdin, stdout } from "process";
+async function reviewEde(ede, index, total) {
+  const rl = createInterface({ input: stdin, output: stdout });
+  stdout.write(`
+  ${index}/${total}  ${ede.id}
+`);
+  stdout.write(`       ${ede.title}
+`);
+  stdout.write(`       Decision: ${ede.whatAndHow.decision}
+`);
+  stdout.write(`       [A]ceptar  [E]ditar  [S]altar
+`);
+  const answer = await rl.question("       > ");
+  const choice = answer.trim().toLowerCase();
+  if (choice === "e" || choice === "editar") {
+    const title = await rl.question(`       Titulo [enter = mantener]: `);
+    const decision = await rl.question(`       Decision [enter = mantener]: `);
+    const rationale = await rl.question(`       Rationale [enter = mantener]: `);
+    rl.close();
+    return {
+      action: "accept",
+      edits: {
+        title: title.trim() || void 0,
+        decision: decision.trim() || void 0,
+        rationale: rationale.trim() || void 0
+      }
+    };
+  }
+  rl.close();
+  if (choice === "s" || choice === "saltar") return { action: "skip" };
+  return { action: "accept" };
+}
+
+// src/setup/database.ts
+import { homedir as homedir2 } from "os";
+
+// ../persistence/src/db.ts
+import Database from "better-sqlite3";
+import * as sqliteVec from "sqlite-vec";
+import { mkdirSync } from "fs";
+import { homedir } from "os";
+import { dirname } from "path";
+
+// ../persistence/src/migrate.ts
+var migrations = [
+  {
+    id: "001_edes",
+    up: `CREATE TABLE IF NOT EXISTS edes (
+      id TEXT PRIMARY KEY,
+      data TEXT NOT NULL,
+      title TEXT NOT NULL,
+      status TEXT NOT NULL,
+      cognitive_level TEXT NOT NULL,
+      created_at TEXT,
+      updated_at TEXT
+    )`
+  },
+  {
+    id: "002_grill_sessions",
+    up: `CREATE TABLE IF NOT EXISTS grill_sessions (
+      id TEXT PRIMARY KEY,
+      ede_id TEXT NOT NULL,
+      data TEXT NOT NULL,
+      status TEXT NOT NULL,
+      alignment_score REAL NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS cognitive_debts (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      ede_id TEXT NOT NULL,
+      gap REAL NOT NULL,
+      reason TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    )`
+  },
+  {
+    id: "003_semantic_embeddings",
+    up: `CREATE TABLE IF NOT EXISTS session_nodes (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      type TEXT NOT NULL,
+      content TEXT NOT NULL,
+      metadata TEXT,
+      source_doc_node TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+    CREATE VIRTUAL TABLE IF NOT EXISTS session_nodes_fts USING fts5(
+      node_id UNINDEXED, content, session_id UNINDEXED, type UNINDEXED
+    );
+    CREATE TABLE IF NOT EXISTS doc_chunks (
+      rowid INTEGER PRIMARY KEY AUTOINCREMENT,
+      id TEXT UNIQUE NOT NULL,
+      doc_id TEXT NOT NULL,
+      content TEXT NOT NULL,
+      source_doc_node TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+    CREATE VIRTUAL TABLE IF NOT EXISTS doc_chunks_vec USING vec0(
+      embedding float[384]
+    )`
+  },
+  {
+    id: "004_terminal_sessions",
+    up: `CREATE TABLE IF NOT EXISTS terminal_sessions (
+      id TEXT PRIMARY KEY,
+      ede_id TEXT,
+      pid INTEGER NOT NULL,
+      status TEXT NOT NULL DEFAULT 'active',
+      working_directory TEXT NOT NULL,
+      claude_md_path TEXT,
+      created_at TEXT NOT NULL,
+      last_activity_at TEXT NOT NULL,
+      terminated_at TEXT
+    )`
+  }
+];
+function runMigrations(db) {
+  db.exec(
+    `CREATE TABLE IF NOT EXISTS _migrations (
+      id TEXT PRIMARY KEY,
+      applied_at TEXT NOT NULL
+    )`
+  );
+  const applied = new Set(
+    db.prepare("SELECT id FROM _migrations").pluck().all()
+  );
+  for (const m of migrations) {
+    if (!applied.has(m.id)) {
+      db.exec(m.up);
+      db.prepare("INSERT INTO _migrations (id, applied_at) VALUES (?, ?)").run(
+        m.id,
+        (/* @__PURE__ */ new Date()).toISOString()
+      );
+    }
+  }
+}
+
+// ../persistence/src/db.ts
+var DEFAULT_DB_PATH = `${homedir()}/.umbral/umbral.db`;
+function openDb(path = DEFAULT_DB_PATH) {
+  mkdirSync(dirname(path), { recursive: true });
+  const db = new Database(path);
+  try {
+    sqliteVec.load(db);
+  } catch (err) {
+    db.close();
+    throw new Error(
+      `[S13] sqlite-vec extension failed to load \u2014 the app will not start. Cause: ${err instanceof Error ? err.message : err}`
+    );
+  }
+  db.pragma("journal_mode = WAL");
+  const ok = db.pragma("integrity_check", { simple: true });
+  if (ok !== "ok") {
+    db.close();
+    throw new Error("[S13] DB integrity check failed \u2014 the app will not start.");
+  }
+  runMigrations(db);
+  return db;
+}
+
+// ../persistence/src/ede-store.ts
+import { z } from "zod";
+var edeSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  version: z.number(),
+  status: z.enum(["proposed", "accepted", "deprecated"]),
+  cognitiveLevel: z.enum(["explorer", "navigator", "anchor"]),
+  complexityTier: z.union([z.literal(1), z.literal(2), z.literal(3)]),
+  whatAndHow: z.object({ decision: z.string(), mechanism: z.string() }),
+  why: z.object({
+    rationale: z.string(),
+    alternativesConsidered: z.array(
+      z.object({ option: z.string(), rejectedBecause: z.string() })
+    ),
+    references: z.array(z.string())
+  }),
+  whatNotToDo: z.object({ antiPatterns: z.array(z.string()) }),
+  whatsNext: z.object({
+    continuations: z.array(z.string()),
+    openQuestions: z.array(z.string())
+  }),
+  contracts: z.object({
+    layerContracts: z.array(z.string()),
+    verifiedBy: z.array(z.string())
+  }),
+  tests: z.object({
+    unitTests: z.array(z.string()),
+    sadPaths: z.array(z.string()),
+    coverageTarget: z.number()
+  }),
+  provenance: z.object({
+    phase: z.string(),
+    slice: z.number().nullable(),
+    createdBy: z.string(),
+    createdAt: z.string().nullable(),
+    lastUpdated: z.string().nullable()
+  })
+});
+function loadEde(json) {
+  const result = edeSchema.safeParse(json);
+  if (!result.success)
+    throw new Error(`[S13] EDE inv\xE1lida: ${result.error.message}`);
+  if (!result.data.why.rationale.trim())
+    throw new Error("[S13] EDE sin rationale no es una EDE.");
+  return result.data;
+}
+function createEdeStore(db) {
+  return {
+    save(ede) {
+      db.prepare(
+        `INSERT OR REPLACE INTO edes (id, data, title, status, cognitive_level, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`
+      ).run(
+        ede.id,
+        JSON.stringify(ede),
+        ede.title,
+        ede.status,
+        ede.cognitiveLevel,
+        ede.provenance.createdAt,
+        ede.provenance.lastUpdated
+      );
+    },
+    getById(id) {
+      const row = db.prepare("SELECT data FROM edes WHERE id = ?").get(id);
+      return row ? JSON.parse(row.data) : null;
+    },
+    getAll() {
+      const rows = db.prepare("SELECT data FROM edes ORDER BY id").all();
+      return rows.map((r) => JSON.parse(r.data));
+    }
+  };
+}
+
+// src/setup/database.ts
+function setupDatabase(edes) {
+  const db = openDb();
+  const store = createEdeStore(db);
+  let saved = 0;
+  for (const ede of edes) {
+    const validated = loadEde(ede);
+    store.save(validated);
+    saved++;
+  }
+  db.close();
+  return { saved, dbPath: `${homedir2()}/.umbral/umbral.db` };
+}
+
+// src/setup/hooks.ts
+import { existsSync as existsSync6, readFileSync as readFileSync7, writeFileSync, mkdirSync as mkdirSync2 } from "fs";
+import { join as join7 } from "path";
+function setupHooks(projectPath) {
+  const claudeDir = join7(projectPath, ".claude");
+  mkdirSync2(claudeDir, { recursive: true });
+  const settingsPath = join7(claudeDir, "settings.json");
+  let existing = {};
+  if (existsSync6(settingsPath)) {
+    try {
+      existing = JSON.parse(readFileSync7(settingsPath, "utf-8"));
+    } catch {
+    }
+  }
+  const settings = {
+    ...existing,
+    hooks: {
+      SessionStart: [
+        {
+          matcher: "",
+          hooks: [
+            {
+              type: "command",
+              command: "npx @umbral/cli hook session-start",
+              timeout: 10,
+              statusMessage: "Cargando contexto de gobernanza Umbral..."
+            }
+          ]
+        }
+      ],
+      PreToolUse: [
+        {
+          matcher: "Edit|Write",
+          hooks: [
+            {
+              type: "command",
+              command: "npx @umbral/cli hook pre-tool-use",
+              timeout: 10,
+              statusMessage: "Verificando gates Umbral..."
+            }
+          ]
+        }
+      ]
+    },
+    mcpServers: {
+      ...typeof existing.mcpServers === "object" && existing.mcpServers !== null ? existing.mcpServers : {},
+      umbral: {
+        command: "npx",
+        args: ["@umbral/cli", "mcp"]
+      }
+    }
+  };
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+}
+
+// src/setup/context.ts
+import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync3 } from "fs";
+import { join as join8 } from "path";
+
+// ../orchestrator/src/claude-context.ts
+function assembleClaudeContext(edes) {
+  const accepted = edes.filter((e) => e.status === "accepted");
+  const sections = [];
+  sections.push("# Umbral \u2014 Contexto del Proyecto\n");
+  sections.push("> Auto-generado por Umbral. No editar manualmente.\n");
+  if (accepted.length === 0) {
+    sections.push("No hay EDEs activas.\n");
+    return sections.join("\n");
+  }
+  sections.push("## Decisiones Activas (EDEs)\n");
+  sections.push("Estas decisiones son vinculantes. Resp\xE9talas en todo c\xF3digo que generes.\n");
+  for (const ede of accepted) {
+    sections.push(`### ${ede.id}: ${ede.title}
+`);
+    sections.push(`**Decisi\xF3n:** ${ede.whatAndHow.decision}
+`);
+    sections.push(`**Mecanismo:** ${ede.whatAndHow.mechanism}
+`);
+    sections.push(`**Rationale:** ${ede.why.rationale}
+`);
+    if (ede.whatNotToDo.antiPatterns.length > 0) {
+      sections.push("**Anti-patterns (PROHIBIDO):**");
+      for (const ap of ede.whatNotToDo.antiPatterns) {
+        sections.push(`- ${ap}`);
+      }
+      sections.push("");
+    }
+    if (ede.contracts.layerContracts.length > 0) {
+      sections.push(
+        `**Contratos de capa:** ${ede.contracts.layerContracts.join(", ")}
+`
+      );
+    }
+  }
+  sections.push("## Reglas Generales\n");
+  sections.push("- Fail-fast (S13): todo error de validaci\xF3n debe lanzar inmediatamente, nunca degradar en silencio.");
+  sections.push("- Fuente \xFAnica (S2): solo S2 detecta cambios. Otros subsistemas reaccionan al DocRegenEvent.");
+  sections.push("- Local-first: la base de datos vive en ~/.umbral/umbral.db (SQLite con FTS5 + sqlite-vec).");
+  sections.push("- No agregar dependencias externas sin justificaci\xF3n en una EDE.");
+  sections.push("");
+  return sections.join("\n");
+}
+
+// ../orchestrator/src/hook-dispatch.ts
+var READ_ONLY_DIRS = ["umbral-docs/", "umbral-docs\\"];
+function isReadOnlyPath(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  return READ_ONLY_DIRS.some((dir) => normalized.includes(dir));
+}
+function dispatchSessionStart(edes) {
+  const context = assembleClaudeContext(edes);
+  return { action: "context", context };
+}
+function dispatchPreToolUse(input, edes) {
+  const toolName = input.toolName ?? "";
+  if (toolName !== "Edit" && toolName !== "Write") {
+    return { action: "allow" };
+  }
+  const filePath = input.toolInput?.file_path ?? "";
+  if (!filePath) return { action: "allow" };
+  if (isReadOnlyPath(filePath)) {
+    return {
+      action: "deny",
+      reason: `[S14] umbral-docs/ es read-only. Las decisiones se gestionan via EDEs en la DB.`
+    };
+  }
+  const accepted = edes.filter((e) => e.status === "accepted");
+  const antiPatterns = accepted.flatMap(
+    (e) => e.whatNotToDo.antiPatterns.map((ap) => ({ edeId: e.id, pattern: ap }))
+  );
+  if (antiPatterns.length > 0) {
+    return {
+      action: "allow",
+      context: formatAntiPatternReminder(antiPatterns)
+    };
+  }
+  return { action: "allow" };
+}
+function formatAntiPatternReminder(patterns) {
+  const lines = patterns.map((p) => `- [${p.edeId}] ${p.pattern}`);
+  return `Anti-patterns activos (no violar):
+${lines.join("\n")}`;
+}
+function dispatchHook(input, edes) {
+  switch (input.hookEventName) {
+    case "SessionStart":
+      return dispatchSessionStart(edes);
+    case "PreToolUse":
+      return dispatchPreToolUse(input, edes);
+    default:
+      return { action: "allow" };
+  }
+}
+
+// src/setup/context.ts
+function setupContext(projectPath) {
+  const db = openDb();
+  const edes = createEdeStore(db).getAll();
+  db.close();
+  const content = assembleClaudeContext(edes);
+  const claudeDir = join8(projectPath, ".claude");
+  mkdirSync3(claudeDir, { recursive: true });
+  writeFileSync2(join8(claudeDir, "CLAUDE.md"), content, "utf-8");
+}
+
+// src/commands/init.ts
+async function initCommand(options) {
+  const projectPath = options.path ?? process.cwd();
+  const w = (s) => process.stdout.write(s);
+  w("\n  Umbral  \u2014  Inicializacion de gobernanza\n\n");
+  w("  Analizando proyecto...\n");
+  const analysis = analyzeProject(projectPath);
+  if (analysis.detections.length === 0) {
+    w("  No se detectaron tecnologias en este directorio.\n");
+    w("  Puedes crear EDEs manualmente despues.\n\n");
+  } else {
+    for (const d of analysis.detections) {
+      w(`    + ${d.name}
+`);
+    }
+  }
+  const proposals = generateProposals(analysis.detections);
+  if (proposals.length === 0) {
+    w("\n  No hay propuestas de EDEs para generar.\n");
+    w("  Configurando infraestructura base...\n\n");
+  } else {
+    w(`
+  Propuestas de EDEs (${proposals.length}):
+`);
+  }
+  const accepted = [];
+  for (let i = 0; i < proposals.length; i++) {
+    const ede = proposals[i];
+    if (options.yes) {
+      ede.status = "accepted";
+      accepted.push(ede);
+      w(`    + ${ede.id}: ${ede.title}
+`);
+      continue;
+    }
+    const result = await reviewEde(ede, i + 1, proposals.length);
+    if (result.action === "skip") {
+      w("       -- saltado\n");
+      continue;
+    }
+    if (result.edits?.title) ede.title = result.edits.title;
+    if (result.edits?.decision) ede.whatAndHow.decision = result.edits.decision;
+    if (result.edits?.rationale) ede.why.rationale = result.edits.rationale;
+    ede.status = "accepted";
+    accepted.push(ede);
+    w("       + aceptado\n");
+  }
+  w("\n  Configurando infraestructura...\n");
+  if (accepted.length > 0) {
+    const dbResult = setupDatabase(accepted);
+    w(`    + ${dbResult.dbPath}
+`);
+    w(`    + ${dbResult.saved} EDEs guardadas
+`);
+  } else {
+    w("    - Sin EDEs para guardar\n");
+  }
+  setupHooks(projectPath);
+  w("    + .claude/settings.json (hooks + MCP)\n");
+  setupContext(projectPath);
+  w("    + .claude/CLAUDE.md (contexto para Claude)\n");
+  w("\n  Umbral listo. Claude Code ahora tiene gobernanza.\n\n");
+}
+
+// src/commands/hook.ts
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+async function hookCommand(_event) {
+  const raw = await readStdin();
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+  let edes;
+  try {
+    const db = openDb();
+    edes = createEdeStore(db).getAll();
+    db.close();
+  } catch {
+    process.exit(0);
+  }
+  const result = dispatchHook(
+    {
+      hookEventName: input.hook_event_name,
+      toolName: input.tool_name,
+      toolInput: input.tool_input,
+      cwd: input.cwd,
+      source: input.source
+    },
+    edes
+  );
+  if (input.hook_event_name === "SessionStart" && result.action === "context") {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "SessionStart",
+          additionalContext: result.context
+        }
+      })
+    );
+    return;
+  }
+  if (input.hook_event_name === "PreToolUse") {
+    if (result.action === "deny") {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: result.reason
+          }
+        })
+      );
+      return;
+    }
+    if (result.context) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "allow"
+          },
+          additionalContext: result.context
+        })
+      );
+    }
+  }
+}
+
+// src/commands/mcp.ts
+import { execFileSync } from "child_process";
+import { join as join9, dirname as dirname2 } from "path";
+import { fileURLToPath } from "url";
+async function mcpCommand() {
+  const __dirname = dirname2(fileURLToPath(import.meta.url));
+  const mcpEntry = join9(__dirname, "mcp-entry.js");
+  execFileSync(process.execPath, [mcpEntry], {
+    stdio: "inherit"
+  });
+}
+
+// src/commands/start.ts
+import { execSync, spawn } from "child_process";
+import { writeFileSync as writeFileSync3, mkdirSync as mkdirSync4 } from "fs";
+import { join as join10 } from "path";
+import { homedir as homedir3 } from "os";
+import { createServer } from "net";
+var UMBRAL_DIR = join10(homedir3(), ".umbral");
+var COMPOSE_PATH = join10(UMBRAL_DIR, "docker-compose.yml");
+var DOCKER_IMAGE = process.env.UMBRAL_IMAGE ?? "umbral/web:latest";
+function dockerInstalled() {
+  try {
+    execSync("docker --version", { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function composeInstalled() {
+  try {
+    execSync("docker compose version", { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function findFreePort(start) {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.listen(start, "127.0.0.1", () => {
+      const addr = server.address();
+      const port = typeof addr === "object" && addr ? addr.port : start;
+      server.close(() => resolve(port));
+    });
+    server.on("error", () => {
+      if (start < 65535) resolve(findFreePort(start + 1));
+      else reject(new Error("No free port found"));
+    });
+  });
+}
+function generateCompose(webPort, wsPort) {
+  const dbPath = join10(UMBRAL_DIR, "umbral.db").replace(/\\/g, "/");
+  const dbDir = UMBRAL_DIR.replace(/\\/g, "/");
+  return `# Auto-generated by Umbral CLI \u2014 do not edit manually
+name: umbral
+
+services:
+  neo4j:
+    image: neo4j:5-community
+    ports:
+      - "7474:7474"
+      - "7687:7687"
+    environment:
+      NEO4J_AUTH: neo4j/umbral-dev
+    volumes:
+      - neo4j-data:/data
+    healthcheck:
+      test: ["CMD", "neo4j", "status"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  web:
+    image: ${DOCKER_IMAGE}
+    ports:
+      - "${webPort}:3000"
+      - "${wsPort}:3099"
+    environment:
+      NEO4J_URI: bolt://neo4j:7687
+      NEO4J_USER: neo4j
+      NEO4J_PASSWORD: umbral-dev
+      UMBRAL_WS_PORT: "3099"
+      UMBRAL_DB_PATH: /data/umbral.db
+    volumes:
+      - "${dbDir}:/data"
+    depends_on:
+      neo4j:
+        condition: service_healthy
+
+volumes:
+  neo4j-data:
+`;
+}
+async function startCommand(options) {
+  const w = (s) => process.stdout.write(s);
+  w("\n  Umbral  \u2014  Iniciando plataforma\n\n");
+  if (!dockerInstalled()) {
+    w("  \u2717 Docker no esta instalado.\n");
+    w("    Instala Docker Desktop: https://docs.docker.com/get-docker/\n\n");
+    process.exit(1);
+  }
+  if (!composeInstalled()) {
+    w("  \u2717 Docker Compose no esta disponible.\n");
+    w("    Actualiza Docker Desktop o instala el plugin Compose.\n\n");
+    process.exit(1);
+  }
+  w("  \u2713 Docker detectado\n");
+  const webPort = options.port ? parseInt(options.port, 10) : await findFreePort(3e3);
+  const wsPort = await findFreePort(webPort + 99);
+  mkdirSync4(UMBRAL_DIR, { recursive: true });
+  const compose = generateCompose(webPort, wsPort);
+  writeFileSync3(COMPOSE_PATH, compose, "utf-8");
+  w(`  \u2713 docker-compose.yml generado
+`);
+  w("  \u27F3 Descargando imagenes y levantando servicios...\n\n");
+  const detach = options.detach !== false;
+  try {
+    if (detach) {
+      execSync(`docker compose -f "${COMPOSE_PATH}" up -d`, {
+        stdio: "inherit"
+      });
+    } else {
+      const child = spawn("docker", ["compose", "-f", COMPOSE_PATH, "up"], {
+        stdio: "inherit"
+      });
+      child.on("close", (code) => process.exit(code ?? 0));
+      return;
+    }
+  } catch {
+    w("\n  \u2717 Error al iniciar los servicios.\n");
+    w("    Revisa que Docker Desktop este corriendo.\n\n");
+    process.exit(1);
+  }
+  w(`
+  \u2713 Umbral corriendo
+`);
+  w(`    Dashboard:  http://localhost:${webPort}
+`);
+  w(`    Neo4j:      http://localhost:7474
+`);
+  w(`    WebSocket:  ws://localhost:${wsPort}
+
+`);
+  w(`  Para detener:  umbral stop
+
+`);
+}
+
+// src/commands/stop.ts
+import { execSync as execSync2 } from "child_process";
+import { existsSync as existsSync8 } from "fs";
+import { join as join11 } from "path";
+import { homedir as homedir4 } from "os";
+var COMPOSE_PATH2 = join11(homedir4(), ".umbral", "docker-compose.yml");
+function stopCommand() {
+  const w = (s) => process.stdout.write(s);
+  w("\n  Umbral  \u2014  Deteniendo plataforma\n\n");
+  if (!existsSync8(COMPOSE_PATH2)) {
+    w("  \u2717 No se encontro docker-compose.yml en ~/.umbral/\n");
+    w("    Ejecuta 'umbral start' primero.\n\n");
+    process.exit(1);
+  }
+  try {
+    execSync2(`docker compose -f "${COMPOSE_PATH2}" down`, {
+      stdio: "inherit"
+    });
+    w("\n  \u2713 Servicios detenidos.\n\n");
+  } catch {
+    w("\n  \u2717 Error al detener los servicios.\n\n");
+    process.exit(1);
+  }
+}
+
+// src/index.ts
+var program = new Command();
+program.name("umbral").description("Umbral \u2014 Framework de gobernanza para proyectos con Claude Code").version("0.0.1");
+program.command("init").description("Inicializar Umbral en el proyecto actual").option("--yes", "Aceptar todas las propuestas sin preguntar").option("--path <path>", "Ruta al proyecto (default: directorio actual)").action(initCommand);
+program.command("start").description("Levantar la plataforma Umbral (Neo4j + Dashboard web)").option("--port <port>", "Puerto para el dashboard (default: auto)").option("--no-detach", "Correr en primer plano (sin -d)").action(startCommand);
+program.command("stop").description("Detener la plataforma Umbral").action(stopCommand);
+program.command("hook <event>").description("Despachar un hook event de Claude Code (stdin/stdout)").action(hookCommand);
+program.command("mcp").description("Iniciar el servidor MCP de Umbral (transporte stdio)").action(mcpCommand);
+program.parse();