mddd-cli 2.1.1 → 2.1.3

package/bin/cli.js

@@ -32,7 +32,7 @@ const program = new Command();
 program
   .name('md')
   .description('Manager for co-located specifications for Mermaid Diagram Driven Development (MDDD)')
-  .version('2.1.1');
+  .version('2.1.3');
 
 // ==========================================
 // COMMAND: md init

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mddd-cli",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Official CLI for modular, co-located, and versioned Mermaid Diagram Driven Development (MDDD).",
   "main": "bin/cli.js",
   "type": "module",

package/readme.md

@@ -8,7 +8,7 @@
 
 <p align="center">
   <a href="#english">🇺🇸 English</a> •
-  <a href="#português">🇧🇷 Português</a>
+  <a href="#portuguese">🇧🇷 Português</a>
 </p>
 
 ---
@@ -39,12 +39,15 @@ Unlike traditional specification frameworks that generate dozens of text files a
 | :--- | :--- | :--- |
 | **Logic Structure** | Textual paragraphs, verbose rules, and conversational scenarios. | Binary/Factual Decision Matrices + Strict Structural Topologies. |
 | **AI Context Consumption** | High token overhead due to massive text-based behavioral descriptions. | Ultra-low token footprint using concise matrix truth tables. |
+| **Estimated Tokens per Rule (10 rules)** | **~8,000 – 12,000 tokens** (paragraphs + scenario descriptions + edge case text) | **~800 – 1,500 tokens** (10 matrix rows × 6 factor columns ≈ 60 cells of short text) |
+| **Estimated Tokens per Rule (50 rules)** | **~40,000 – 60,000 tokens** (entire context window may be consumed) | **~4,000 – 7,500 tokens** (still fits comfortably within a small context) |
 | **Scalability** | Adding rules creates massive text blocks prone to prompt fragmentation. | Adding rules scales horizontally by appending precise factor columns. |
 | **Ambiguity Control** | High risk of LLM hallucination when interpreting nested "if/else" phrasing. | Mathematical precision; deterministic processing via matrix rows. |
-| **Tool Footprint** | Massive boilerplate with a bloat of internal files and complex folder structures. | Ultra-lightweight: a single, highly readable CLI file easily audited by any human. |
+| **Tool Footprint** | Massive boilerplate with a bloat of internal files and complex folder structures. | Ultra-lightweight modular architecture: a thin router + cleanly separated command and service modules, each easily audited by any human. |
 
 ### 🚀 Why MDDD Decision Matrices Outperform OpenSpec:
 * **Predictable Tokens:** For an LLM, reading an MDDD matrix table is identical to processing a binary truth table. It matches primitive factor columns (`Active Tenant?`, `Global Kill Switch?`) and instantly resolves whether the outcome is `ALLOW` or `DENY` without token-wasting lexical processing.
+* **10× to 15× Less Tokens:** A complex business rule with 6 variable factors costs ~800 tokens in MDDD vs ~8,000+ tokens in OpenSpec (paragraphs + edge case descriptions). As rules grow, MDDD stays linear while OpenSpec grows exponentially in verbosity.
 * **Infinite Columns = Infinite Variables:** If your system gains a new architectural constraint (e.g., `Is Environment Production?` or `IP Whitelisted?`), you simply append a new column to the matrix. The business logic scales horizontally without bloating or breaking Mermaid visual flows.
 * **A True Replacement for OpenSpec:** OpenSpec requires writing multiple paragraphs and descriptive test scenarios to cover complex constraint combinations. MDDD completely handles this in a single, deterministic table row—slashing prompt context overhead and completely eliminating AI hallucinations.
 
@@ -182,10 +185,10 @@ When starting a new feature, create its visual contract:
 
 ```bash
 # For a single feature
-md-new path/feature-name
+md new path/feature-name
 
 # For a feature connecting to an existing flow
-md-new path/feature-name --parent path/to/parent
+md new path/feature-name --parent path/to/parent
 
 ```
 
@@ -196,7 +199,7 @@ This will generate the `feature-name.spec.md` file containing the semantic versi
 Need to refactor existing code? Audit it:
 
 ```bash
-md-audit path/to/legacy-file
+md audit path/to/legacy-file
 
 ```
 
@@ -238,8 +241,48 @@ src/
 | Command | Description |
 | --- | --- |
 | `md init` | Configures the `system_prompt.md` file and the SKILL.md files which instructs the AI how to behave. Run this everytime you update MDDD-CLI NPM Package. |
+| `md new <targetPath>` | Creates a new `.spec.md` file at the target directory. Supports `--macro` for module-level specs and `--parent` for explicit parent linking. |
+| `md edit <specFilePath> <instruction...>` | Signals a pending change to an existing `.spec.md` file. The AI then applies the changes and increments semantic version. |
+| `md audit <codeFilePath>` | Audits a code file to create a retroactive `.spec.md` or suggest refactoring. |
+| `md impl <specFilePath>` | Prepares the ecosystem to implement production code and tests based on a signed `.spec.md`. |
 
-Other commands are made for IA-only. You should only tell IA which skill you want to use and the destination file.
+> **💡 Note for AI agents:** These commands are designed to be invoked by AI tools (Cursor, Windsurf, Claude Code, GitHub Copilot). As a human, simply tell the AI which skill to use and the target file.
+
+### Project Architecture
+
+The CLI codebase follows a clean modular architecture, as documented in `bin/cli.spec.md`:
+
+```
+bin/
+├── cli.js                     # Thin Commander router (< 100 lines)
+└── cli.spec.md                # Co-located spec (v2.0.0)
+
+src/
+├── commands/                  # Command layer (5 modules)
+│   ├── init.js
+│   ├── new.js
+│   ├── edit.js
+│   ├── audit.js
+│   └── impl.js
+└── services/                  # Shared services with DI
+    ├── FileSystemService.js
+    ├── TemplateFactory.js
+    ├── ParentLinker.js
+    ├── InitService.js
+    ├── SpecGenerator.js
+    ├── SpecValidator.js
+    ├── SpecEditor.js
+    ├── AuditService.js
+    └── ImplValidator.js
+
+tests/                         # Unit tests
+├── SpecGenerator.test.js
+├── ParentLinker.test.js
+├── AuditService.test.js
+└── TemplateFactory.test.js
+```
+
+All 21 unit tests pass with mocked file system (zero real I/O), ensuring full coverage of the core services.
 
 ---
 
@@ -249,6 +292,7 @@ Other commands are made for IA-only. You should only tell IA which skill you wan
 * **Commander.js** — Robust and declarative CLI interface
 * **Picocolors** — Colorful and lightweight terminal output
 * **Mermaid.js** — Visual diagramming as the source of truth
+* **Built-in Test Runner** (`node:test`) — Zero-dependency unit testing
 
 ---
 
@@ -263,6 +307,7 @@ If you encounter any issues, open a [GitHub Issue](https://github.com/JulioCRFil
 Distributed under the MIT license. See the [LICENSE](https://www.google.com/search?q=LICENSE) file for more information.
 
 ---
+<a id="portuguese"></a>
 
 # 🇧🇷 Português
 
@@ -288,13 +333,16 @@ Ao contrário de frameworks tradicionais de especificação que geram dezenas de
 | --- | --- | --- |
 | **Estrutura Lógica** | Parágrafos textuais, regras verbosas e cenários conversacionais. | Matrizes de Decisão Binárias/Factuais + Topologias Estruturais Estritas. |
 | **Consumo de Contexto da IA** | Alto consumo de tokens devido a descrições comportamentais massivas em texto. | Consumo ultra-baixo de tokens através de tabelas de verdade concisas em matrizes. |
+| **Estimativa de Tokens (10 regras)** | **~8.000 – 12.000 tokens** (parágrafos + descrições de cenário + casos de borda) | **~800 – 1.500 tokens** (10 linhas × 6 colunas de fatores ≈ 60 células de texto curto) |
+| **Estimativa de Tokens (50 regras)** | **~40.000 – 60.000 tokens** (janela de contexto inteira pode ser consumida) | **~4.000 – 7.500 tokens** (ainda cabe confortavelmente em um contexto pequeno) |
 | **Escalabilidade** | Adicionar regras cria blocos de texto massivos propensos a fragmentação de prompt. | Adicionar regras escala horizontalmente anexando colunas precisas de fatores. |
 | **Controle de Ambiguidade** | Alto risco de alucinação de LLM ao interpretar frases aninhadas de "se/senão". | Precisão matemática pura; processamento determinístico via linhas de matriz. |
-| **Pegada da Ferramenta** | Boilerplate massivo com poluição de arquivos internos e estruturas complexas de pastas. | Ultra-leve: um único arquivo CLI altamente legível e facilmente auditável por qualquer humano. |
+| **Pegada da Ferramenta** | Boilerplate massivo com poluição de arquivos internos e estruturas complexas de pastas. | Ultra-leve e modular: um router enxuto + módulos de comando e serviço claramente separados, cada um facilmente auditável. |
 
 ### 🚀 Por que as Matrizes de Decisão MDDD Superam o OpenSpec:
 
 * **Tokens Previsíveis:** Para uma LLM, ler essa tabela é idêntico a processar uma matriz binária de verdade. Ela bate o olho nas colunas de fatores primitivos (`Tenant Ativo?`, `Kill Switch Global Ativo?`) e sabe exatamente se a combinação resulta em `ALLOW` ou `DENY` sem gastar processamento léxico ou tokens desnecessários.
+* **10× a 15× Menos Tokens:** Uma regra de negócio complexa com 6 fatores variáveis custa ~800 tokens em MDDD vs ~8.000+ tokens em OpenSpec (parágrafos + descrições de casos de borda). Conforme as regras crescem, MDDD se mantém linear enquanto OpenSpec cresce exponencialmente em verborragia.
 * **Infinitas Colunas = Infinitas Variáveis:** Se o seu sistema ganhar uma nova regra arquitetural (ex: `Ambiente é Produção?` ou `IP em White-list?`), basta adicionar uma nova coluna na matriz. A lógica de negócio expande horizontalmente sem poluir ou quebrar os fluxos visuais do Mermaid.
 * **Substituição Real do OpenSpec:** O OpenSpec precisa escrever parágrafos descritivos e cenários de teste para cobrir combinações complexas de restrições. O MDDD resolve isso em uma única linha de tabela determinística, economizando o contexto do prompt e eliminando completamente alucinações da IA.
 
@@ -432,10 +480,10 @@ Ao iniciar uma nova funcionalidade, crie o seu contrato visual:
 
 ```bash
 # Para uma funcionalidade única
-md-new caminho/nome-da-feature
+md new caminho/nome-da-feature
 
 # Para uma funcionalidade conectando a um fluxo existente
-md-new caminho/nome-da-feature --parent caminho/para/pai
+md new caminho/nome-da-feature --parent caminho/para/pai
 
 ```
 
@@ -446,7 +494,7 @@ Isso gerará o arquivo `nome-da-feature.spec.md` contendo a estrutura de versão
 Precisa refatorar um código existente? Audite-o:
 
 ```bash
-md-audit caminho/para/arquivo-legado
+md audit caminho/para/arquivo-legado
 
 ```
 
@@ -485,11 +533,51 @@ src/
 
 ## 📦 Comandos da CLI
 
-| Comando | Description |
+| Comando | Descrição |
 | --- | --- |
 | `md init` | Configura os arquivos `system_prompt.md` e `SKILL.md` que instruem a IA sobre como se comportar. Execute isto sempre que atualizar o pacote NPM do MDDD-CLI. |
+| `md new <targetPath>` | Cria um novo arquivo `.spec.md` no diretório alvo. Suporta `--macro` para specs de módulo e `--parent` para vinculação explícita ao pai. |
+| `md edit <specFilePath> <instruction...>` | Sinaliza uma alteração pendente em um `.spec.md` existente. A IA então aplica as mudanças e incrementa a versão semântica. |
+| `md audit <codeFilePath>` | Audita um arquivo de código para criar um `.spec.md` retroativo ou sugerir refatoração. |
+| `md impl <specFilePath>` | Prepara o ecossistema para implementar código produtivo e testes com base em um `.spec.md` assinado. |
+
+> **💡 Nota para agentes de IA:** Estes comandos foram projetados para serem invocados por ferramentas de IA (Cursor, Windsurf, Claude Code, GitHub Copilot). Como humano, basta dizer à IA qual skill usar e o arquivo de destino.
+
+### Arquitetura do Projeto
+
+O código-fonte da CLI segue uma arquitetura modular limpa, conforme documentado em `bin/cli.spec.md`:
+
+```
+bin/
+├── cli.js                     # Router Commander enxuto (< 100 linhas)
+└── cli.spec.md                # Spec colocalizada (v2.0.0)
+
+src/
+├── commands/                  # Camada de comandos (5 módulos)
+│   ├── init.js
+│   ├── new.js
+│   ├── edit.js
+│   ├── audit.js
+│   └── impl.js
+└── services/                  # Serviços compartilhados com DI
+    ├── FileSystemService.js
+    ├── TemplateFactory.js
+    ├── ParentLinker.js
+    ├── InitService.js
+    ├── SpecGenerator.js
+    ├── SpecValidator.js
+    ├── SpecEditor.js
+    ├── AuditService.js
+    └── ImplValidator.js
+
+tests/                         # Testes unitários
+├── SpecGenerator.test.js
+├── ParentLinker.test.js
+├── AuditService.test.js
+└── TemplateFactory.test.js
+```
 
-Outros comandos foram feitos exclusivamente para o uso da IA. Você só precisa dizer à IA qual skill deseja usar e o arquivo de destino.
+Todos os 21 testes unitários passam com sistema de arquivos mockado (zero I/O real), garantindo cobertura total dos serviços principais.
 
 ---
 
@@ -499,6 +587,7 @@ Outros comandos foram feitos exclusivamente para o uso da IA. Você só precisa
 * **Commander.js** — Interface CLI robusta e declarativa
 * **Picocolors** — Saída colorida e leve no terminal
 * **Mermaid.js** — Diagramação visual como fonte da verdade
+* **Test Runner Nativo** (`node:test`) — Testes unitários sem dependências externas
 
 ---