@umbral/cli 0.0.1

package/dist/mcp-entry.js

@@ -0,0 +1,596 @@
+// ../mcp-server/src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// ../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 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));
+    }
+  };
+}
+
+// ../persistence/src/grill-store.ts
+function createGrillStore(db) {
+  return {
+    saveSession(session) {
+      db.prepare(
+        `INSERT OR REPLACE INTO grill_sessions (id, ede_id, data, status, alignment_score, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`
+      ).run(
+        session.id,
+        session.edeId,
+        JSON.stringify(session),
+        session.status,
+        session.alignmentScore,
+        session.createdAt,
+        session.updatedAt
+      );
+    },
+    getSession(id) {
+      const row = db.prepare("SELECT data FROM grill_sessions WHERE id = ?").get(id);
+      return row ? JSON.parse(row.data) : null;
+    },
+    getActiveSession() {
+      const row = db.prepare(
+        "SELECT data FROM grill_sessions WHERE status = 'in_progress' ORDER BY updated_at DESC LIMIT 1"
+      ).get();
+      return row ? JSON.parse(row.data) : null;
+    },
+    saveDebt(debt) {
+      db.prepare(
+        `INSERT INTO cognitive_debts (id, session_id, ede_id, gap, reason, created_at)
+         VALUES (?, ?, ?, ?, ?, ?)`
+      ).run(debt.id, debt.sessionId, debt.edeId, debt.gap, debt.reason, debt.createdAt);
+    },
+    getDebts() {
+      return db.prepare("SELECT * FROM cognitive_debts ORDER BY created_at DESC").all();
+    }
+  };
+}
+
+// ../persistence/src/semantic-store.ts
+function createSemanticStore(db) {
+  return {
+    index(node) {
+      db.prepare(
+        `INSERT OR REPLACE INTO session_nodes (id, session_id, type, content, metadata, source_doc_node, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`
+      ).run(
+        node.id,
+        node.sessionId,
+        node.type,
+        node.content,
+        JSON.stringify(node.metadata),
+        node.sourceDocNode,
+        node.createdAt
+      );
+      db.prepare(
+        `INSERT OR REPLACE INTO session_nodes_fts (node_id, content, session_id, type)
+         VALUES (?, ?, ?, ?)`
+      ).run(node.id, node.content, node.sessionId, node.type);
+    },
+    search(query, filters) {
+      let ftsQuery = `SELECT node_id FROM session_nodes_fts WHERE content MATCH ?`;
+      const params = [query];
+      if (filters?.type) {
+        ftsQuery += ` AND type = ?`;
+        params.push(filters.type);
+      }
+      if (filters?.sessionId) {
+        ftsQuery += ` AND session_id = ?`;
+        params.push(filters.sessionId);
+      }
+      const ids = db.prepare(ftsQuery).pluck().all(...params);
+      if (ids.length === 0) return [];
+      const placeholders = ids.map(() => "?").join(",");
+      const rows = db.prepare(
+        `SELECT * FROM session_nodes WHERE id IN (${placeholders})`
+      ).all(...ids);
+      return rows.map((r) => ({
+        id: r.id,
+        sessionId: r.session_id,
+        type: r.type,
+        content: r.content,
+        metadata: JSON.parse(r.metadata || "{}"),
+        sourceDocNode: r.source_doc_node,
+        createdAt: r.created_at
+      }));
+    }
+  };
+}
+
+// ../orchestrator/src/gates/code-guard.ts
+var codeGuard = {
+  id: "code-guard",
+  mode: "coercive",
+  evaluate: (context) => {
+    if (!context.edeId) {
+      return { pass: false, reason: "[S12] Modificaci\xF3n sin EDE asociada: bloqueada." };
+    }
+    if (context.edeStatus !== "accepted") {
+      return {
+        pass: false,
+        reason: `[S12] EDE ${context.edeId} no est\xE1 aprobada (status: ${context.edeStatus}): bloqueada.`
+      };
+    }
+    return { pass: true };
+  }
+};
+
+// ../orchestrator/src/gates/plan-guard.ts
+var planGuard = {
+  id: "plan-guard",
+  mode: "normative",
+  evaluate: (context) => {
+    if (!context.plan) {
+      return { pass: false, reason: "[S12] Plan ausente: rechazado." };
+    }
+    if (context.plan.unitTests.length === 0) {
+      return { pass: false, reason: "[S12] Plan sin tests unitarios: rechazado." };
+    }
+    if (context.plan.sadPaths.length === 0) {
+      return { pass: false, reason: "[S12] Plan sin sad-paths: rechazado." };
+    }
+    return { pass: true };
+  }
+};
+
+// ../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");
+}
+
+// ../mcp-server/src/tools.ts
+var TOOL_DEFINITIONS = [
+  {
+    name: "umbral_ede_list",
+    description: "List all EDEs (Explicit Decision Structures) in the project. Returns id, title, status, and cognitive level for each.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: {
+          type: "string",
+          enum: ["accepted", "proposed", "deprecated"],
+          description: "Filter by status. Omit to list all."
+        }
+      }
+    }
+  },
+  {
+    name: "umbral_ede_get",
+    description: "Get full details of a specific EDE by ID. Includes decision, mechanism, rationale, anti-patterns, contracts, and tests.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "EDE ID (e.g. EDE-000-persistence)" }
+      },
+      required: ["id"]
+    }
+  },
+  {
+    name: "umbral_ede_search",
+    description: "Search EDEs by text query. Matches against title, decision, mechanism, rationale, and anti-patterns.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query text" }
+      },
+      required: ["query"]
+    }
+  },
+  {
+    name: "umbral_context",
+    description: "Get the full assembled Umbral governance context. Contains all active decisions, anti-patterns, layer contracts, and rules.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "umbral_grill_status",
+    description: "Get the current Grill Me alignment session status. Shows active session, alignment score, and cognitive debts.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "umbral_semantic_search",
+    description: "Search indexed session content using FTS5 full-text search.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "FTS5 search query" },
+        type: { type: "string", description: "Filter by node type" }
+      },
+      required: ["query"]
+    }
+  },
+  {
+    name: "umbral_gate_check",
+    description: "Run a gate validation check. Validates EDE status and test plan against CodeGuard and PlanGuard.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        edeId: { type: "string", description: "EDE ID to validate" },
+        edeStatus: { type: "string", description: "EDE status (accepted/proposed/deprecated)" },
+        unitTests: {
+          type: "array",
+          items: { type: "string" },
+          description: "List of unit test identifiers"
+        },
+        sadPaths: {
+          type: "array",
+          items: { type: "string" },
+          description: "List of sad path test identifiers"
+        }
+      },
+      required: ["edeId"]
+    }
+  }
+];
+function searchEdes(edes, query) {
+  const q = query.toLowerCase();
+  return edes.filter((e) => {
+    const searchable = [
+      e.id,
+      e.title,
+      e.whatAndHow.decision,
+      e.whatAndHow.mechanism,
+      e.why.rationale,
+      ...e.whatNotToDo.antiPatterns
+    ].join(" ").toLowerCase();
+    return searchable.includes(q);
+  });
+}
+function handleToolCall(toolName, args, db) {
+  const edeStore = createEdeStore(db);
+  switch (toolName) {
+    case "umbral_ede_list": {
+      const all = edeStore.getAll();
+      const filtered = args.status ? all.filter((e) => e.status === args.status) : all;
+      return filtered.map((e) => ({
+        id: e.id,
+        title: e.title,
+        status: e.status,
+        cognitiveLevel: e.cognitiveLevel,
+        complexityTier: e.complexityTier,
+        decision: e.whatAndHow.decision
+      }));
+    }
+    case "umbral_ede_get": {
+      const ede = edeStore.getById(args.id);
+      if (!ede) return { error: `EDE ${args.id} not found` };
+      return ede;
+    }
+    case "umbral_ede_search": {
+      const all = edeStore.getAll();
+      const results = searchEdes(all, args.query);
+      return results.map((e) => ({
+        id: e.id,
+        title: e.title,
+        status: e.status,
+        decision: e.whatAndHow.decision,
+        mechanism: e.whatAndHow.mechanism
+      }));
+    }
+    case "umbral_context": {
+      const all = edeStore.getAll();
+      return { context: assembleClaudeContext(all) };
+    }
+    case "umbral_grill_status": {
+      const grillStore = createGrillStore(db);
+      const active = grillStore.getActiveSession();
+      const debts = grillStore.getDebts();
+      return {
+        activeSession: active ? {
+          id: active.id,
+          edeId: active.edeId,
+          status: active.status,
+          alignmentScore: active.alignmentScore,
+          roundCount: active.rounds.length
+        } : null,
+        cognitiveDebts: debts.length,
+        debts: debts.slice(0, 5)
+      };
+    }
+    case "umbral_semantic_search": {
+      const semanticStore = createSemanticStore(db);
+      const results = semanticStore.search(
+        args.query,
+        args.type ? { type: args.type } : void 0
+      );
+      return results.map((r) => ({
+        id: r.id,
+        type: r.type,
+        content: r.content.slice(0, 500),
+        sourceDocNode: r.sourceDocNode
+      }));
+    }
+    case "umbral_gate_check": {
+      const ctx = {
+        edeId: args.edeId,
+        edeStatus: args.edeStatus ?? "accepted",
+        plan: {
+          unitTests: args.unitTests ?? [],
+          sadPaths: args.sadPaths ?? [],
+          coverageTarget: 0.8
+        }
+      };
+      const codeResult = codeGuard.evaluate(ctx);
+      if (!codeResult.pass) {
+        return { pass: false, gate: "CodeGuard", reason: codeResult.reason };
+      }
+      const planResult = planGuard.evaluate(ctx);
+      if (!planResult.pass) {
+        return { pass: false, gate: "PlanGuard", reason: planResult.reason };
+      }
+      return { pass: true, gates: ["CodeGuard", "PlanGuard"] };
+    }
+    default:
+      return { error: `Unknown tool: ${toolName}` };
+  }
+}
+
+// ../mcp-server/src/index.ts
+var server = new Server(
+  { name: "umbral-mcp", version: "0.0.1" },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOL_DEFINITIONS
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const db = openDb();
+  try {
+    const result = handleToolCall(name, args ?? {}, db);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: err instanceof Error ? err.message : String(err)
+          })
+        }
+      ],
+      isError: true
+    };
+  } finally {
+    db.close();
+  }
+});
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("Umbral MCP server failed to start:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@umbral/cli",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "umbral": "./dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "build:tsc": "tsc",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1",
+    "commander": "^12",
+    "better-sqlite3": "^11",
+    "sqlite-vec": "^0.1",
+    "zod": "^3"
+  },
+  "devDependencies": {
+    "@umbral/contracts": "workspace:*",
+    "@umbral/persistence": "workspace:*",
+    "@umbral/orchestrator": "workspace:*",
+    "@umbral/mcp-server": "workspace:*",
+    "@umbral/specialists": "workspace:*",
+    "@types/better-sqlite3": "^7",
+    "@types/node": "^22",
+    "tsup": "^8",
+    "typescript": "^5",
+    "vitest": "^3"
+  }
+}