sdd-gl 0.6.0 → 0.6.2

package/README.es.md

@@ -2,7 +2,8 @@
 
 ![SDD-GL Portada](assets/sdd-gl-cover.png)
 
-[![Version](https://img.shields.io/badge/version-0.6.0-blue)](CHANGELOG.md)
+[![npm](https://img.shields.io/npm/v/sdd-gl)](https://www.npmjs.com/package/sdd-gl)
+[![Version](https://img.shields.io/badge/version-0.6.2-blue)](CHANGELOG.md)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![MCP Protocol](https://img.shields.io/badge/MCP-Protocol%20Ready-purple)](mcp/sdd-gl-mcp-spec.md)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-orange)](https://docs.claude.ai/code)
@@ -285,7 +286,30 @@ Sigue esta guía paso a paso para configurar y comenzar a utilizar SDD-GL en tu
 
 ### 2. Elige tu Método de Instalación
 
-#### 🌐 Método 1: Servidor MCP Universal (Cursor, Windsurf, OpenCode, Warp, Claude Desktop, VS Code)
+#### 📦 Método 0: paquete npm (recomendado)
+Publicado como **`sdd-gl`** en npm — sin clonar ni spec de GitHub:
+
+```bash
+npm install -g sdd-gl      # instala dos comandos: sdd (CLI) y sdd-gl-mcp (servidor)
+sdd --help                 # verificar
+```
+
+Para la configuración de un cliente MCP, apuntá al binario del servidor:
+
+```json
+{
+  "mcpServers": {
+    "sdd-gl": {
+      "command": "npx",
+      "args": ["-y", "--package", "sdd-gl", "sdd-gl-mcp"]
+    }
+  }
+}
+```
+
+> Un paquete con dos binarios no se resuelve solo por el nombre del paquete, así que `npx` siempre nombra el binario: `--package sdd-gl sdd-gl-mcp`.
+
+#### 🌐 Método 1: Servidor MCP Universal desde GitHub (Cursor, Windsurf, OpenCode, Warp, Claude Desktop, VS Code)
 Sin necesidad de clonar repositorios manualmente. Añade el servidor MCP directamente desde GitHub a la configuración de tu IDE o cliente de terminal (`~/.cursor/mcp.json`, `claude_desktop_config.json`, configuración de OpenCode o Cline MCP):
 
 ```json
@@ -780,6 +804,7 @@ sdd-gl/
 ├── docs/
 │   ├── index.html           ← Dashboard público del showcase (solo examples/, nunca los contratos privados).
 │   ├── INSTALACION.md       ← Instalación paso a paso por plataforma.
+│   ├── DEPLOY.md            ← Checklist de publicación para mantenedores.
 │   └── assets/
 │       └── dashboard-sample.png ← Captura real de un proyecto de ejemplo.
 ├── protocol/
@@ -801,6 +826,8 @@ sdd-gl/
 ├── examples/
 │   └── contracts/           ← Contratos showcase públicos (curados y resueltos).
 ├── contracts/               ← Specs de trabajo locales (gitignored — privadas).
+├── scripts/
+│   └── release.js           ← Sube la versión en manifiestos y badges, y verifica la deriva.
 ├── test-sandbox/            ← 15 suites: core, CLI, métricas, uso, CI, interop y fixtures.
 ├── .claude/
 │   ├── agents/              ← 6 adaptadores de agente (español).

package/README.md

@@ -2,7 +2,8 @@
 
 ![SDD-GL Cover](assets/sdd-gl-cover.png)
 
-[![Version](https://img.shields.io/badge/version-0.6.0-blue)](CHANGELOG.md)
+[![npm](https://img.shields.io/npm/v/sdd-gl)](https://www.npmjs.com/package/sdd-gl)
+[![Version](https://img.shields.io/badge/version-0.6.2-blue)](CHANGELOG.md)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![MCP Protocol](https://img.shields.io/badge/MCP-Protocol%20Ready-purple)](mcp/sdd-gl-mcp-spec.md)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-orange)](https://docs.claude.ai/code)
@@ -284,7 +285,30 @@ Follow this step-by-step guide to configure and start using SDD-GL in your prefe
 
 ### 2. Choose Your Installation Method
 
-#### 🌐 Method 1: Universal MCP Server (Cursor, Windsurf, OpenCode, Warp, Claude Desktop, VS Code)
+#### 📦 Method 0: npm package (recommended)
+Published as **`sdd-gl`** on npm — no cloning, no GitHub spec:
+
+```bash
+npm install -g sdd-gl      # installs two commands: sdd (CLI) and sdd-gl-mcp (server)
+sdd --help                 # verify
+```
+
+For an MCP client configuration, point it at the server binary:
+
+```json
+{
+  "mcpServers": {
+    "sdd-gl": {
+      "command": "npx",
+      "args": ["-y", "--package", "sdd-gl", "sdd-gl-mcp"]
+    }
+  }
+}
+```
+
+> A package with two binaries cannot be resolved by package name alone, so `npx` always names the binary: `--package sdd-gl sdd-gl-mcp`.
+
+#### 🌐 Method 1: Universal MCP Server from GitHub (Cursor, Windsurf, OpenCode, Warp, Claude Desktop, VS Code)
 No repository cloning needed. Add the MCP server directly from GitHub to your IDE / terminal client configuration (`~/.cursor/mcp.json`, `claude_desktop_config.json`, OpenCode settings, or Cline MCP settings):
 
 ```json
@@ -779,6 +803,7 @@ sdd-gl/
 ├── docs/
 │   ├── index.html           ← Public showcase dashboard (examples/ only, never the private contracts).
 │   ├── INSTALACION.md       ← Step-by-step installation per platform.
+│   ├── DEPLOY.md            ← Release checklist for maintainers.
 │   └── assets/
 │       └── dashboard-sample.png ← Real capture of an example project.
 ├── protocol/
@@ -800,6 +825,8 @@ sdd-gl/
 ├── examples/
 │   └── contracts/           ← Public showcase contracts (curated and resolved).
 ├── contracts/               ← Local working specs (gitignored — private).
+├── scripts/
+│   └── release.js           ← Version bump across manifests and README badges, plus the drift check.
 ├── test-sandbox/            ← 15 suites: core, CLI, metrics, usage, CI, interop and fixtures.
 ├── .claude/
 │   ├── agents/              ← 6 agent adapters (Spanish).

package/bin/sdd.js

@@ -32,7 +32,7 @@ const ROOT = rootFlag ? path.resolve(rootFlag) : process.cwd();
 
 process.env.SDD_PROJECT_ROOT = ROOT;
 
-const { handleToolCall, TOOLS } = require('../mcp/server.js');
+const { handleToolCall, TOOLS, isContractText, looksLikeContract } = require('../mcp/server.js');
 
 // CLI usage is real usage of the methodology: it is counted and attributed to the
 // contract type it serves (feature/fix) when a contract is involved.
@@ -588,17 +588,28 @@ function commandDoctor() {
 
   const unreadable = [];
   const stalled = [];
+  const ignored = [];
+  let contracts = 0;
 
   if (fs.existsSync(contractsDir)) {
     for (const name of fs.readdirSync(contractsDir).filter(entry => entry.toLowerCase().endsWith('.md'))) {
       const text = fs.readFileSync(path.join(contractsDir, name), 'utf8');
-      if (!/^#\s*ID:/m.test(text) || !/^#\s*Status:/m.test(text)) unreadable.push(name);
+
+      // `contracts/` may also hold a README or notes: only files with a contract
+      // header are counted, and only a broken contract header is a failure.
+      if (!isContractText(text)) {
+        if (looksLikeContract(text)) unreadable.push(name);
+        else ignored.push(name);
+        continue;
+      }
+
+      contracts += 1;
       if (/^\s*#.*\|\s*⏳\s*$/m.test(text)) stalled.push(name);
     }
   }
 
   if (unreadable.length > 0) add('contratos', 'FAIL', `encabezado ilegible: ${unreadable.join(', ')}`);
-  else add('contratos', 'OK', 'todos los encabezados son legibles');
+  else add('contratos', 'OK', `${contracts} contrato(s) legibles${ignored.length ? ` · ignorados: ${ignored.join(', ')}` : ''}`);
 
   if (stalled.length > 0) add('en curso', 'WARN', `ítems en ⏳ (reanudar): ${stalled.join(', ')}`);
   else add('en curso', 'OK', 'sin ítems interrumpidos');
@@ -1320,6 +1331,7 @@ function commandReview() {
 
   for (const file of fs.readdirSync(contractsDir).filter(name => name.toLowerCase().endsWith('.md'))) {
     const text = fs.readFileSync(path.join(contractsDir, file), 'utf8');
+    if (!isContractText(text)) continue;
     const id = (text.match(/^#\s*ID:\s*(\S+)\s*$/m) || [])[1] || file.replace(/\.md$/, '');
     const status = (text.match(/^#\s*Status:\s*(\w+)\s*$/m) || [])[1] || 'UNKNOWN';
     const criteria = readCriteria(text);

package/mcp/server.js

@@ -327,12 +327,30 @@ function inferContractType(contractId, text, fileName) {
   return 'feature';
 }
 
+// A contract is recognized by its header, not by its extension: `contracts/` may
+// also hold a README or free-form notes that must be ignored.
+function isContractText(text) {
+  return /^#\s*ID:/m.test(text) && /^#\s*Status:/m.test(text);
+}
+
+// Files that *look* like contracts but cannot be read as one are real errors.
+function looksLikeContract(text) {
+  return /^#\s*CONTRACT:/m.test(text);
+}
+
 function listContractFiles() {
   if (!fs.existsSync(CONTRACTS_DIR)) return [];
   return fs
     .readdirSync(CONTRACTS_DIR, { withFileTypes: true })
     .filter(entry => entry.isFile() && entry.name.toLowerCase().endsWith('.md'))
-    .map(entry => entry.name);
+    .map(entry => entry.name)
+    .filter(name => {
+      try {
+        return isContractText(fs.readFileSync(path.join(CONTRACTS_DIR, name), 'utf8'));
+      } catch (error) {
+        return false;
+      }
+    });
 }
 
 // Finds a contract by ID regardless of the file naming convention
@@ -1483,7 +1501,7 @@ ${evidence}
 
     case 'sdd_get_status': {
       if (!fs.existsSync(CONTRACTS_DIR)) return { total_contracts: 0, contracts: [] };
-      const files = fs.readdirSync(CONTRACTS_DIR).filter(f => f.endsWith('.md'));
+      const files = listContractFiles();
 
       const summary = files.map(file => {
         const content = fs.readFileSync(path.join(CONTRACTS_DIR, file), 'utf8');
@@ -1517,7 +1535,7 @@ ${evidence}
       const response = { ...metrics, source };
       if (warning) response.warning = warning;
       if (fs.existsSync(CONTRACTS_DIR)) {
-        response.total_contracts = fs.readdirSync(CONTRACTS_DIR).filter(f => f.endsWith('.md')).length;
+        response.total_contracts = listContractFiles().length;
       } else {
         response.total_contracts = 0;
       }
@@ -1527,7 +1545,7 @@ ${evidence}
     case 'sdd_audit_traceability': {
       // BR-005: real coverage. Nothing here is a fixed value.
       const contractFiles = fs.existsSync(CONTRACTS_DIR)
-        ? fs.readdirSync(CONTRACTS_DIR).filter(file => file.endsWith('.md'))
+        ? listContractFiles()
         : [];
 
       const specs = [];
@@ -1665,7 +1683,7 @@ function main() {
   });
 }
 
-module.exports = { TOOLS, handleToolCall, computeNextContractId, reconcileContract, computeCriteriaHashes };
+module.exports = { TOOLS, handleToolCall, computeNextContractId, reconcileContract, computeCriteriaHashes, isContractText, looksLikeContract };
 
 if (require.main === module) {
   main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-gl",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Model Context Protocol (MCP) Server and CLI for Spec-Driven Development (SDD-GL)",
   "main": "mcp/server.js",
   "bin": {
@@ -35,8 +35,10 @@
     "dashboard": "node mcp/dashboard-gen.js",
     "dashboard:public": "node mcp/dashboard-gen.js --public",
     "fixture": "node test-sandbox/fixtures/demo-project.js",
-    "test": "node test-sandbox/id-generation.test.js && node test-sandbox/step-loop.test.js && node test-sandbox/mcp-core.test.js && node test-sandbox/neutral-format.test.js && node test-sandbox/atomicity.test.js && node test-sandbox/metrics.test.js && node test-sandbox/usage.test.js && node test-sandbox/fix-0001-docs.test.js && node test-sandbox/ci-workflow.test.js && node test-sandbox/interop.test.js && node test-sandbox/cli.test.js && node test-sandbox/fixture-project.test.js && node test-sandbox/split.test.js && node test-sandbox/reconcile.test.js && node test-sandbox/review.test.js && node test-sandbox/publish.test.js && node test-sandbox/multilayer-verifier.test.js && node test-sandbox/escrow.test.js && node test-sandbox/mcp-client-e2e.js",
-    "prepublishOnly": "npm test"
+    "test": "node test-sandbox/id-generation.test.js && node test-sandbox/step-loop.test.js && node test-sandbox/mcp-core.test.js && node test-sandbox/neutral-format.test.js && node test-sandbox/atomicity.test.js && node test-sandbox/metrics.test.js && node test-sandbox/usage.test.js && node test-sandbox/fix-0001-docs.test.js && node test-sandbox/ci-workflow.test.js && node test-sandbox/interop.test.js && node test-sandbox/cli.test.js && node test-sandbox/fixture-project.test.js && node test-sandbox/split.test.js && node test-sandbox/reconcile.test.js && node test-sandbox/review.test.js && node test-sandbox/publish.test.js && node test-sandbox/doctor.test.js && node test-sandbox/orchestrator-docs.test.js && node test-sandbox/multilayer-verifier.test.js && node test-sandbox/escrow.test.js && node test-sandbox/mcp-client-e2e.js",
+    "prepublishOnly": "npm test && node scripts/release.js --check",
+    "release:check": "node scripts/release.js --check",
+    "release:prepare": "node scripts/release.js"
   },
   "keywords": [
     "mcp",