mddd-cli 3.1.0 → 3.2.0

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.2.0');
 
 // ==========================================
 // COMMAND: md init

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mddd-cli",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "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,45 @@ 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 Mermaid diagram preview on PRs.
+ */
+export const GITHUB_WORKFLOW_CONTENT = `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
+
+      - name: 📸 Render Mermaid Diagrams to Images
+        uses: xanmanning/mermaid-render-action@v1.2.1
+        id: mermaid-render
+        with:
+          manifest: 'mddd-manifest.json'
+          output-dir: '.github/mddd-previews'
+          format: 'png'
+
+      - 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:
+
+            ![Diagram Preview](https://raw.githubusercontent.com/\${{ github.repository }}/\${{ github.head_ref }}/.github/mddd-previews/changed-diagram.png)
+          comment_tag: 'mddd-design-preview'`;
+
 /**
  * Executes the \`md init\` command.
  * @param {import('../services/InitService.js').InitService} initService
@@ -253,6 +292,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.3.0 — stable**
 
 ## Overview
 
@@ -11,17 +11,64 @@ 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
+
+      - name: 📸 Render Mermaid Diagrams to Images
+        uses: xanmanning/mermaid-render-action@v1.2.1
+        id: mermaid-render
+        with:
+          manifest: 'mddd-manifest.json'
+          output-dir: '.github/mddd-previews'
+          format: 'png'
+
+      - 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:
+
+            ![Diagram Preview](https://raw.githubusercontent.com/${{ github.repository }}/${{ github.head_ref }}/.github/mddd-previews/changed-diagram.png)
+          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 +191,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 +204,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 +218,8 @@ 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). |
+
+> **v1.3.0 (current):** 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`. New "GitHub Actions Preview Workflow" section documenting the idempotent overwrite behavior. SPEC_VERSION bumped from v1.2.0 to v1.3.0 (minor — new state node/flow addition). Status promoted from **draft** to **stable** — implementation and tests verified. |
 
 </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>