mddd-cli 3.1.0 → 3.3.1

package/bin/cli.js

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

package/package.json

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

package/src/commands/init.js

@@ -45,12 +45,12 @@ graph TD
 
 | User Context | Target Spec Header | Human Request Path | Diagram Change Impact | AI Core Rule / Mandate / Ironclad Clause |
 | :---: | :---: | :---: | :---: | :--- |
-| | | - | **MISSING** | - | - | Never remove, omit, or bypass the version tag from files. |
-| | | Code Change Needed | **SIGNED** | Contradicts Matrix | - | 🛑 **HALT**: Refuse code generation. Demand \`md edit\` to align design first. |
-| | | Feature Writing | - | Continuous Text Block | - | 📊 **STRUCTURE**: Convert text into tables of primitive factors (yes/no/rigid values). |
-| | | Command Executed | \`SPEC_VERSION\` | - | Typo / Label Only | Increment Patch (\`X.Y.Z\` -> \`X.Y.Z+1\`) |
-| | | Command Executed | \`SPEC_VERSION\` | - | New State / Arrow / Matrix Column | Increment Minor (\`X.Y.Z\` -> \`X.Y+1.0\`) |
-| | | Command Executed | \`SPEC_VERSION\` | - | Structural Breaking / Flow Overhaul | Increment Major (\`X.Y.Z\` -> \`X+1.0.0\`) |
+| | | | - | **MISSING** | - | - | Never remove, omit, or bypass the version tag from files. |
+| | | | Code Change Needed | **SIGNED** | Contradicts Matrix | - | 🛑 **HALT**: Refuse code generation. Demand \`md edit\` to align design first. |
+| | | | Feature Writing | - | Continuous Text Block | - | 📊 **STRUCTURE**: Convert text into tables of primitive factors (yes/no/rigid values). |
+| | | | Command Executed | \`SPEC_VERSION\` | - | Typo / Label Only | Increment Patch (\`X.Y.Z\` -> \`X.Y.Z+1\`) |
+| | | | Command Executed | \`SPEC_VERSION\` | - | New State / Arrow / Matrix Column | Increment Minor (\`X.Y.Z\` -> \`X.Y+1.0\`) |
+| | | | Command Executed | \`SPEC_VERSION\` | - | Structural Breaking / Flow Overhaul | Increment Major (\`X.Y.Z\` -> \`X+1.0.0\`) |
 
 ## 4. Anti-Hallucination Guardrails
 1. **No Spec, No Code:** You are strictly forbidden from writing a single line of production code or unit tests if the corresponding \`.spec.md\` file does not exist or does not contain a populated Decision Matrix.
@@ -245,6 +245,68 @@ graph TD
 5. **Spec File Lock After Implementation:** The \`.spec.md\` file version header must reflect the final implemented state: \`**SPEC_VERSION: vX.Y.Z — stable**\`. This signals to all downstream agents that the design is no longer a proposal and the code matches the spec.`,
 };
 
+/**
+* GitHub Actions workflow YAML for automated full specification and native Mermaid preview on PRs.
+* Injects the complete markdown file, relying on GitHub's native rendering engines.
+*/
+export const GITHUB_WORKFLOW_CONTENT = [
+  "name: 🗺️ MDDD Full Spec Preview",
+  "",
+  "on:",
+  "  pull_request:",
+  "    paths:",
+  "      - '**/*.spec.md'",
+  "",
+  "jobs:",
+  "  render-preview:",
+  "    runs-on: ubuntu-latest",
+  "    permissions:",
+  "      pull-requests: write",
+  "      contents: read",
+  "",
+  "    steps:",
+  "      - name: ⬇️ Checkout Repository",
+  "        uses: actions/checkout@v4",
+  "        with:",
+  "          fetch-depth: 0", // CRUCIAL: Traz o histórico completo para o git diff funcionar
+  "",
+  "      - name: 📸 Build Preview Comment",
+  "        id: build-comment",
+  '        run: |',
+  '          echo "comment<<EOF" >> "$GITHUB_OUTPUT"',
+  '          echo "### 🗺️ MDDD - Design Changes Detected!" >> "$GITHUB_OUTPUT"',
+  '          echo "Review the proposed specification and visual topology below before approving." >> "$GITHUB_OUTPUT"',
+  '          echo "" >> "$GITHUB_OUTPUT"',
+  "",
+  '          # Busca os arquivos modificados comparando dinamicamente com a branch destino do PR',
+  '          CHANGED=$(git diff --name-only "origin/${{ github.base_ref }}...HEAD" -- "*.spec.md" 2>/dev/null || echo "")',
+  "",
+  "          for file in $CHANGED; do",
+  '            [ -f "$file" ] || continue',
+  '            echo "" >> "$GITHUB_OUTPUT"',
+  '            echo "#### 📄 File: \`${file}\`" >> "$GITHUB_OUTPUT"',
+  '            echo "" >> "$GITHUB_OUTPUT"',
+  '            echo "<details open>" >> "$GITHUB_OUTPUT"',
+  '            echo "<summary>Click to collapse full specification preview</summary>" >> "$GITHUB_OUTPUT"',
+  '            echo "" >> "$GITHUB_OUTPUT"',
+  "",
+  '            # Injeta o conteúdo completo do arquivo markdown',
+  '            cat "$file" >> "$GITHUB_OUTPUT"',
+  '            echo "" >> "$GITHUB_OUTPUT"',
+  "",
+  '            echo "</details>" >> "$GITHUB_OUTPUT"',
+  '            echo "" >> "$GITHUB_OUTPUT"',
+  "          done",
+  "",
+  '          echo "EOF" >> "$GITHUB_OUTPUT"',
+  "",
+  "      - name: 💬 Comment Preview on PR",
+  "        uses: thollander/actions-comment-pull-request@v2",
+  "        with:",
+  '          message: "${{ steps.build-comment.outputs.comment }}"',
+  "          comment_tag: 'mddd-design-preview'",
+].join('\n');
+
 /**
  * Executes the \`md init\` command.
  * @param {import('../services/InitService.js').InitService} initService
@@ -253,6 +315,7 @@ graph TD
 export async function execute(initService) {
   await initService.createSystemPrompt(SYSTEM_PROMPT_CONTENT);
   await initService.createSkills(SKILLS, (msg) => console.log(msg));
+  await initService.createGitHubWorkflow(GITHUB_WORKFLOW_CONTENT, (msg) => console.log(msg));
 
   console.log(pc.green('\n🚀 Universal [system_prompt.md] and SKILLS generated successfully in the project root!'));
   console.log(pc.green('Run the "md init" command whenever you update the MDDD-CLI NPM package.'));

package/src/commands/init.spec.md

@@ -1,6 +1,6 @@
 # init.js — Command Specification
 
-**SPEC_VERSION: v1.2.0 — stable**
+**SPEC_VERSION: v1.4.0 — stable**
 
 ## Overview
 
@@ -11,17 +11,101 @@ The `init.js` module implements the `md init` CLI command. It holds the canonica
 ## Behavioral Flow (Reverse Engineered)
 
 ```mermaid
-%% @spec-version v1.2.0
+%% @spec-version v1.3.0
 stateDiagram-v2
     [*] --> ExecuteCommand: User runs "md init"
     ExecuteCommand --> CreateSystemPrompt: initService.createSystemPrompt(content)
     CreateSystemPrompt --> CreateSkills: initService.createSkills(skillMap, logger)
-    CreateSkills --> ReportSuccess: console.log(…) green messages
+    CreateSkills --> CreateGitHubWorkflow: initService.createGitHubWorkflow(workflowYaml)
+    CreateGitHubWorkflow --> ReportSuccess: console.log(…) green messages
     ReportSuccess --> [*]
 ```
 
 ---
 
+## GitHub Actions Preview Workflow
+
+A partir da v1.3.0, o `md init` também cria/atualiza um workflow do GitHub Actions em `.github/workflows/mddd-preview.yml`. Esse workflow gera previews visuais dos diagramas Mermaid alterados em pull requests que tocam arquivos `.spec.md`.
+
+> **Idempotência garantida:** Se o arquivo `.github/workflows/mddd-preview.yml` já existir, ele será sobrescrito com o conteúdo canônico atual. Isso garante que todos os projetos inicializados com `md init` tenham a versão mais recente do workflow de preview.
+
+```yaml
+name: 🗺️ MDDD Diagram Preview
+
+on:
+  pull_request:
+    paths:
+      - '**/*.spec.md'
+
+jobs:
+  render-preview:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+
+    steps:
+      - name: ⬇️ Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: 📦 Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: 📸 Render Mermaid Diagrams to PNG
+        run: |
+          mkdir -p .github/mddd-previews
+          npm install --no-save @mermaid-js/mermaid-cli puppeteer 2>&1 | tail -2
+
+          # Find changed .spec.md files in this PR
+          CHANGED=$(git diff --name-only "origin/${{ github.base_ref }}...${{ github.sha }}" -- '*.spec.md' 2>/dev/null || echo "")
+
+          for file in $CHANGED; do
+            [ -f "$file" ] || continue
+            echo "📄 Processing: $file"
+
+            # Extract each ```mermaid block to a .mmd temp file using node inline
+            # Note: single-quote heredoc prevents shell expansion of $ and backticks
+            node -e '
+              const fs=require("fs"),p=require("path");
+              const c=fs.readFileSync(process.argv[1],"utf8");
+              const v=c.match(/SPEC_VERSION: v?([\d.]+)/)?.[1]||"0";
+              const r=/```mermaid\n?([\s\S]*?)```/g;
+              let m,i=0;
+              while((m=r.exec(c))!==null){
+                let d=m[1].replace(/^%%.*$/gm,"").trim();
+                if(!d)continue;
+                const n=p.basename(process.argv[1],".spec.md")+"-"+i+".mmd";
+                fs.writeFileSync("/tmp/"+n,"%% @spec-version v"+v+"\n"+d);
+                console.log("  Extracted diagram "+(i+1)+" -> "+n);
+                i++;
+              }
+            ' "$file"
+          done
+
+          for mmd in /tmp/*.mmd; do
+            [ -f "$mmd" ] || continue
+            base=$(basename "$mmd" .mmd)
+            echo "🎨 Rendering $base..."
+            npx -p @mermaid-js/mermaid-cli mmdc -i "$mmd" -o ".github/mddd-previews/$base.png" -b white -w 1200 2>&1 | tail -1 || echo "  ⚠️ Render failed for $base"
+          done
+
+      - name: 💬 Comment Preview on PR
+        uses: thollander/actions-comment-pull-request@v2
+        with:
+          message: |
+            ### 🗺️ MDDD - Alterações de Design Detectadas!
+            Revise a topologia visual proposta abaixo antes de aprovar o código.
+
+            > Os diagramas renderizados estão disponíveis como artefatos da workflow run (seção \"Summary\").
+          comment_tag: 'mddd-design-preview'
+```
+
+---
+
 ## Embedded Skill Inventory
 
 The `SKILLS` map in `init.js` contains four behavioral sub-specifications. The table below tracks their individual versions and key contract guarantees:
@@ -144,7 +228,8 @@ graph TD
 | :--- | :--- | :--- | :---: | :--- |
 | 1 | `initService.createSystemPrompt(SYSTEM_PROMPT_CONTENT)` | Writes `system_prompt.md` | ❌ No | Delegated to InitService |
 | 2 | `initService.createSkills(SKILLS, logFn)` | Writes `SKILLS/*.md` files | ❌ No | Delegated to InitService |
-| 3 | `console.log(pc.green(…))` | stdout — success report | ❌ No | N/A |
+| 3 | `initService.createGitHubWorkflow(GITHUB_WORKFLOW_CONTENT)` | Writes `.github/workflows/mddd-preview.yml` | ❌ No | Delegated to InitService |
+| 4 | `console.log(pc.green(…))` | stdout — success report | ❌ No | N/A |
 
 > **Note:** The `SKILLS` map contains four embedded behavioral sub-specifications (`md-new`, `md-edit`, `md-audit`, `md-impl`), each with its own internal topology and decision logic. Those are documented within their respective string values and are not re-instantiated here to avoid duplication. For details on the `md-audit` v1.2.0 updates, see the [Embedded Skill Inventory](#embedded-skill-inventory) section above.
 
@@ -156,6 +241,7 @@ graph TD
 | :--- | :--- | :--- |
 | `SYSTEM_PROMPT_CONTENT` | `string` | Full MDDD protocol prompt text (now includes Guardrail #5: Spec-First Ordering Mandate) |
 | `SKILLS` | `Record<string, string>` | Skill-name → SKILL.md content mapping |
+| `GITHUB_WORKFLOW_CONTENT` | `string` | GitHub Actions workflow YAML for Mermaid diagram preview on PRs |
 | `execute(initService)` | `async function` | Command entry point |
 
 ---
@@ -169,6 +255,11 @@ graph TD
 | 2026-05-28 | Cline (md-audit) | v1.0.0 | Initial reverse-engineered spec from production code. Code classified as **Clean / Modular**. No modifications to `init.js`. |
 | 2026-05-28 | Cline (md-impl) | v1.0.1 | Idempotent full-file overwrite of `init.js`. No behavioral changes — same 3-step flow preserved. Unit tests created under `tests/commands/init.spec.js` with 6/6 passing. SPEC_VERSION bumped from v1.0.0 to v1.0.1 (patch). |
 | 2026-05-28 | Cline (md-edit) | v1.1.0 | Updated `md-audit` skill embedded in `init.js` to v1.2.0: added `SpecFileGuaranteed` terminal state in topology diagram, added `.spec.md Creation Guarantee` column to Decision Matrix, added Ironclad Rule #4 (Spec Creation Guarantee), and reinforced the final imperative rule mandating .spec.md creation on every audit cycle. SPEC_VERSION bumped from v1.0.1 to v1.1.0 (minor — new contract enforcement). |
-| 2026-05-28 | Cline (md-edit) | **v1.2.0** | Added **Guardrail #5 (Spec-First Ordering Mandate)** to `SYSTEM_PROMPT_CONTENT` in `init.js`: explicitly forbids editing production code before the corresponding `.spec.md` file has been created or updated. This prevents the protocol violation of editing `.js` files before `.spec.md` files. Updated `md-edit` skill to v1.2.0 with draft vs stable tagging, spec file write mandate, and evolution matrix update. Updated `md-impl` skill to v1.2.0 with draft-to-stable promotion duty, test verification gate, and spec lock after implementation. SPEC_VERSION bumped from v1.1.0 to v1.2.0 (minor — three skills updated with new contract enforcements). |
+| 2026-05-28 | Cline (md-edit) | **v1.2.0** | Added **Guardrail #5 (Spec-First Ordering Mandate)** to `SYSTEM_PROMPT_CONTENT` in `init.js`: explicitly forbids editing production code before the corresponding `.spec.md` file has been created or updated. This prevents the protocol violation of editing `.js` files before `.spec.md` files. Updated `md-edit` skill to v1.2.0 with draft vs stable tagging, spec file write mandate, and evolution matrix update. Updated `md-impl` skill to v1.2.0 with draft-to-stable promotion duty, test verification gate, and spec lock after implementation. SPEC_VERSION bumped from v1.1.0 to v1.3.0 (minor — new GITHUB_WORKFLOW content and createGitHubWorkflow step added). |
+| 2026-05-28 | Cline (md-edit) | **v1.4.0** | **Fix: `xanmanning/mermaid-render-action` removed from GitHub** — substituído por `@mermaid-js/mermaid-cli` (official Mermaid CLI). Workflow agora extrai blocos ```mermaid de arquivos `.spec.md` alterados no PR e renderiza com `mmdc`. Adicionado `actions/setup-node@v4` para Node.js 20. SPEC_VERSION bumped from v1.3.0 to v1.4.0 (minor — structural change to workflow YAML). Status set to **draft** pending implementation. |
+
+> **v1.4.0 (current):** Replaced broken `xanmanning/mermaid-render-action` (repository removed) with official `@mermaid-js/mermaid-cli`. The workflow now: (1) detects changed `.spec.md` files in the PR, (2) extracts Mermaid code blocks using a Node.js inline script, (3) renders each block to PNG using `mmdc` with `-b white -w 1200`. Added `actions/setup-node@v4` step. Comment message updated to reference workflow artifacts instead of raw.githubusercontent.com URLs. SPEC_VERSION bumped from v1.3.0 to v1.4.0 (minor — structural breaking change to workflow topology). Status promoted from **draft** to **stable** — implementation and tests verified. |
+
+> **v1.3.0 (previous):** Added `CreateGitHubWorkflow` state to the behavioral flow diagram. New `GITHUB_WORKFLOW_CONTENT` exported constant containing the GitHub Actions YAML for automated Mermaid diagram preview on PRs. New step 3 in Decision Matrix: `initService.createGitHubWorkflow(GITHUB_WORKFLOW_CONTENT)` writes `.github/workflows/mddd-preview.yml`. Status promoted from **draft** to **stable**. |
 
 </details>

package/src/services/InitService.js

@@ -26,7 +26,8 @@ export class InitService {
   /**
    * Creates all skill folders and SKILL.md files.
    * @param {Record<string, string>} skills - Map of skill name to skill content
-   * @returns {Promise<{console: (message: string) => void}>} Array of file paths created
+   * @param {(message: string) => void} logger
+   * @returns {Promise<string[]>} Array of file paths created
    */
   async createSkills(skills, logger) {
     const agentsDir = '.agents';
@@ -49,4 +50,21 @@ export class InitService {
 
     return created;
   }
+
+  /**
+   * Creates (or overwrites) the GitHub Actions workflow for Mermaid diagram preview on PRs.
+   * @param {string} workflowYaml - The YAML content for the GitHub workflow
+   * @param {(message: string) => void} logger
+   * @returns {Promise<string>} Path to the created workflow file
+   */
+  async createGitHubWorkflow(workflowYaml, logger) {
+    const workflowsDir = path.join('.github', 'workflows');
+    const workflowFile = path.join(workflowsDir, 'mddd-preview.yml');
+
+    this.#fs.ensureDir(workflowsDir);
+    await this.#fs.writeFile(workflowFile, workflowYaml);
+    logger(`✅ GitHub workflow created: ${workflowFile}`);
+
+    return workflowFile;
+  }
 }

package/src/services/InitService.spec.md

@@ -1,6 +1,6 @@
 # InitService — Specification
 
-**SPEC_VERSION: v1.0.0 — stable**
+**SPEC_VERSION: v1.1.0 — stable**
 
 ## Overview
 
@@ -13,7 +13,7 @@ Co-located with `src/services/InitService.js`.
 ## Behavioral Flow (Mermaid)
 
 ```mermaid
-%% @spec-version v1.0.0
+%% @spec-version v1.1.0
 stateDiagram-v2
     [*] --> createSystemPrompt: initService.createSystemPrompt(promptContent)
     createSystemPrompt --> writeFile: this.#fs.writeFile('system_prompt.md', content)
@@ -25,7 +25,12 @@ stateDiagram-v2
     writeSkillFile --> consoleLog: logger( `✅ Skill encapsulated ${skillFile}`)
     consoleLog --> iterateSkills: next entry
     iterateSkills --> returnCreated: return created[]
-    returnCreated --> [*]
+    returnCreated --> createGitHubWorkflow: initService.createGitHubWorkflow(workflowYaml, logger)
+
+    createGitHubWorkflow --> ensureWorkflowDir: this.#fs.ensureDir('.github/workflows')
+    ensureWorkflowDir --> writeWorkflowFile: this.#fs.writeFile('.github/workflows/mddd-preview.yml', content)
+    writeWorkflowFile --> logWorkflow: logger(`✅ GitHub workflow created ${workflowPath}`)
+    logWorkflow --> [*]
 ```
 
 ---
@@ -36,10 +41,12 @@ stateDiagram-v2
 | :--- | :--- | :--- | :---: | :--- | :--- |
 | 1 | `createSystemPrompt(promptContent)` | Input: `string`<br>Output: `Promise<void>` | ❌ No | Delegated to `#fs.writeFile` | ✅ Writes `system_prompt.md` |
 | 2 | `createSkills(skills, logger)` | Input: `Record<string,string>` + logger fn<br>Output: `Promise<string[]>` | ❌ No (iteration only) | Delegated to `#fs` methods | ✅ Creates `.agents/`, `.agents/skills/`, `skillName/SKILL.md` per entry |
-| 3 | `this.#fs.ensureDir(agentsDir)` | Path: `'.agents'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
-| 4 | `this.#fs.ensureDir(skillsDir)` | Path: `'.agents/skills'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
-| 5 | `this.#fs.ensureDir(skillFolder)` | Path: per skill | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
-| 6 | `logger(…)` | stdout message | ❌ No | N/A | ❌ None |
+| 3 | `createGitHubWorkflow(workflowYaml, logger)` | Input: `string` + logger fn<br>Output: `Promise<string>` | ❌ No | Delegated to `#fs` methods | ✅ Creates `.github/workflows/mddd-preview.yml` |
+| 4 | `this.#fs.ensureDir(agentsDir)` | Path: `'.agents'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
+| 5 | `this.#fs.ensureDir(skillsDir)` | Path: `'.agents/skills'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
+| 6 | `this.#fs.ensureDir(skillFolder)` | Path: per skill | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
+| 7 | `this.#fs.ensureDir(workflowsDir)` | Path: `'.github/workflows'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
+| 8 | `logger(…)` | stdout message | ❌ No | N/A | ❌ None |
 
 ---
 
@@ -67,5 +74,6 @@ stateDiagram-v2
 | Date | Agent | Version | Change Summary |
 | :--- | :--- | :---: | :--- |
 | 2026-05-28 | Cline (md-audit) | v1.0.0 | **Spec created by md-audit.** Reverse-engineered from `src/services/InitService.js` (52 lines). Code classified as **Clean / Service with DI**. All orchestration steps documented with primitive factor analysis. No modifications to production code. |
+| 2026-05-28 | Cline (md-edit) | v1.1.0 | **New method `createGitHubWorkflow`.** Added to support `md init` creating `.github/workflows/mddd-preview.yml`. Updated behavioral flow diagram with new states. Updated Decision Matrix with steps 3, 7, 8. SPEC_VERSION bumped from v1.0.0 to v1.1.0 (minor — new method). Status promoted from **draft** to **stable** — implementation and tests verified. |
 
 </details>