flowbook 0.2.2 → 0.2.4

package/dist/cli.js

@@ -330,10 +330,10 @@ function resolveAgents(agentArg) {
 }
 function installFile(src, destDir, destFilename) {
   const dest = resolve3(destDir, destFilename);
-  if (existsSync2(dest)) return false;
+  const existed = existsSync2(dest);
   mkdirSync(destDir, { recursive: true });
   copyFileSync(src, dest);
-  return true;
+  return { action: existed ? "updated" : "installed" };
 }
 function installSkills(agentArg, global) {
   const agents = resolveAgents(agentArg);
@@ -343,32 +343,32 @@ function installSkills(agentArg, global) {
     console.error("  \u2717 Skill source file not found. Reinstall flowbook.");
     process.exit(1);
   }
-  let skillCount = 0;
-  let cmdCount = 0;
+  let installedSkills = 0;
+  let updatedSkills = 0;
+  let installedCmds = 0;
+  let updatedCmds = 0;
   for (const agent of agents) {
     const skillDir = resolve3(base, global ? agent.skill.global : agent.skill.project);
-    if (installFile(skillSrc, skillDir, "SKILL.md")) {
-      skillCount++;
-    }
+    const skillResult = installFile(skillSrc, skillDir, "SKILL.md");
+    if (skillResult.action === "installed") installedSkills++;
+    else if (skillResult.action === "updated") updatedSkills++;
     if (agent.command) {
       const cmdSrc = getCommandSrc(agent.command.format);
       if (existsSync2(cmdSrc)) {
         const cmdDir = resolve3(base, global ? agent.command.global : agent.command.project);
-        if (installFile(cmdSrc, cmdDir, "flowbook.md")) {
-          cmdCount++;
-        }
+        const cmdResult = installFile(cmdSrc, cmdDir, "flowbook.md");
+        if (cmdResult.action === "installed") installedCmds++;
+        else if (cmdResult.action === "updated") updatedCmds++;
       }
     }
   }
   const scope = global ? "global" : "project";
   const agentNames = agents.map((a) => a.name).join(", ");
-  if (skillCount > 0 || cmdCount > 0) {
-    if (skillCount > 0) console.log(`  \u2713 Installed skill to ${skillCount} ${scope} director${skillCount > 1 ? "ies" : "y"}`);
-    if (cmdCount > 0) console.log(`  \u2713 Installed /flowbook command to ${cmdCount} ${scope} director${cmdCount > 1 ? "ies" : "y"}`);
-    console.log(`  Agents: ${agentNames}`);
-  } else {
-    console.log(`  \u2713 Already installed for: ${agentNames}`);
-  }
+  if (installedSkills > 0) console.log(`  \u2713 Installed skill to ${installedSkills} ${scope} director${installedSkills > 1 ? "ies" : "y"}`);
+  if (updatedSkills > 0) console.log(`  \u2713 Updated skill in ${updatedSkills} ${scope} director${updatedSkills > 1 ? "ies" : "y"}`);
+  if (installedCmds > 0) console.log(`  \u2713 Installed /flowbook command to ${installedCmds} ${scope} director${installedCmds > 1 ? "ies" : "y"}`);
+  if (updatedCmds > 0) console.log(`  \u2713 Updated /flowbook command in ${updatedCmds} ${scope} director${updatedCmds > 1 ? "ies" : "y"}`);
+  console.log(`  Agents: ${agentNames}`);
 }
 function printSkillUsage() {
   console.log(`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowbook",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "bin": {
     "flowbook": "./dist/cli.js"

package/src/node/skill.ts

@@ -135,12 +135,12 @@ function resolveAgents(agentArg: string): AgentConfig[] {
   return found;
 }
 
-function installFile(src: string, destDir: string, destFilename: string): boolean {
+function installFile(src: string, destDir: string, destFilename: string): { action: "installed" | "updated" | "skipped" } {
   const dest = resolve(destDir, destFilename);
-  if (existsSync(dest)) return false;
+  const existed = existsSync(dest);
   mkdirSync(destDir, { recursive: true });
   copyFileSync(src, dest);
-  return true;
+  return { action: existed ? "updated" : "installed" };
 }
 
 export function installSkills(agentArg: string, global: boolean): void {
@@ -153,22 +153,24 @@ export function installSkills(agentArg: string, global: boolean): void {
     process.exit(1);
   }
 
-  let skillCount = 0;
-  let cmdCount = 0;
+  let installedSkills = 0;
+  let updatedSkills = 0;
+  let installedCmds = 0;
+  let updatedCmds = 0;
 
   for (const agent of agents) {
     const skillDir = resolve(base, global ? agent.skill.global : agent.skill.project);
-    if (installFile(skillSrc, skillDir, "SKILL.md")) {
-      skillCount++;
-    }
+    const skillResult = installFile(skillSrc, skillDir, "SKILL.md");
+    if (skillResult.action === "installed") installedSkills++;
+    else if (skillResult.action === "updated") updatedSkills++;
 
     if (agent.command) {
       const cmdSrc = getCommandSrc(agent.command.format);
       if (existsSync(cmdSrc)) {
         const cmdDir = resolve(base, global ? agent.command.global : agent.command.project);
-        if (installFile(cmdSrc, cmdDir, "flowbook.md")) {
-          cmdCount++;
-        }
+        const cmdResult = installFile(cmdSrc, cmdDir, "flowbook.md");
+        if (cmdResult.action === "installed") installedCmds++;
+        else if (cmdResult.action === "updated") updatedCmds++;
       }
     }
   }
@@ -176,13 +178,11 @@ export function installSkills(agentArg: string, global: boolean): void {
   const scope = global ? "global" : "project";
   const agentNames = agents.map((a) => a.name).join(", ");
 
-  if (skillCount > 0 || cmdCount > 0) {
-    if (skillCount > 0) console.log(`  ✓ Installed skill to ${skillCount} ${scope} director${skillCount > 1 ? "ies" : "y"}`);
-    if (cmdCount > 0) console.log(`  ✓ Installed /flowbook command to ${cmdCount} ${scope} director${cmdCount > 1 ? "ies" : "y"}`);
-    console.log(`  Agents: ${agentNames}`);
-  } else {
-    console.log(`  ✓ Already installed for: ${agentNames}`);
-  }
+  if (installedSkills > 0) console.log(`  ✓ Installed skill to ${installedSkills} ${scope} director${installedSkills > 1 ? "ies" : "y"}`);
+  if (updatedSkills > 0) console.log(`  ✓ Updated skill in ${updatedSkills} ${scope} director${updatedSkills > 1 ? "ies" : "y"}`);
+  if (installedCmds > 0) console.log(`  ✓ Installed /flowbook command to ${installedCmds} ${scope} director${installedCmds > 1 ? "ies" : "y"}`);
+  if (updatedCmds > 0) console.log(`  ✓ Updated /flowbook command in ${updatedCmds} ${scope} director${updatedCmds > 1 ? "ies" : "y"}`);
+  console.log(`  Agents: ${agentNames}`);
 }
 
 /** Used by init.ts — installs skills only (no commands) to all agents at project level */
@@ -191,14 +191,13 @@ export function installAllProjectSkills(): number {
   const skillSrc = getSkillSrc();
   if (!existsSync(skillSrc)) return 0;
 
-  let installed = 0;
+  let count = 0;
   for (const agent of AGENTS) {
     const dir = resolve(cwd, agent.skill.project);
-    if (installFile(skillSrc, dir, "SKILL.md")) {
-      installed++;
-    }
+    const result = installFile(skillSrc, dir, "SKILL.md");
+    if (result.action !== "skipped") count++;
   }
-  return installed;
+  return count;
 }
 
 export function printSkillUsage(): void {

package/src/skills/flowbook/SKILL.md

@@ -275,6 +275,37 @@ flowchart TD
     I[\Output\]             %% Reverse parallelogram: response
 ```
 
+#### Label Quoting Rules (MANDATORY)
+
+Node labels containing special characters **MUST** be wrapped in double quotes to prevent Mermaid parse errors.
+
+**Characters that REQUIRE quoting:**
+
+| Character | Why it breaks | Unquoted (BROKEN) | Quoted (CORRECT) |
+|-----------|--------------|-------------------|------------------|
+| `()` | Conflicts with `([...])` stadium and `(...)` rounded shapes | `A([Agent run() Start])` | `A(["Agent run() Start"])` |
+| `{}` | Conflicts with `{...}` diamond shape | `B{tokio::select!{}}` | `B{"tokio::select!{}"}` |
+| `[]` | Conflicts with `[...]` rectangle shape | `C[arr[0] value]` | `C["arr[0] value"]` |
+| `::` | Interpreted as Mermaid class/namespace syntax | `D[std::io::Error]` | `D["std::io::Error"]` |
+| `#` | Interpreted as Unicode escape or comment | `E[Issue #42]` | `E["Issue #42"]` |
+| `&` | Interpreted as HTML entity start | `F[A & B]` | `F["A & B"]` |
+
+**Rule: When in doubt, quote it.** Quoting a label that doesn't need it causes no harm. Unquoted special characters WILL break rendering.
+
+**Examples of correct quoting by node shape:**
+
+```mermaid
+flowchart TD
+    A(["fn main() entry"])         %% Stadium with parens
+    B["process_data(input)"]       %% Rectangle with parens
+    C{"is_valid(x)?"}              %% Diamond with parens
+    D[["handle_error(err)"]]       %% Subroutine with parens
+    E{{"validate(req)"}}           %% Hexagon with parens
+    F["Config::new()"]             %% Rectangle with double colon
+```
+
+**NEVER generate unquoted labels containing `()`, `{}`, `[]`, `::`, `#`, or `&`.**
+
 #### Edge Labels
 
 ```mermaid
@@ -369,7 +400,7 @@ description: POST /api/auth/login — validates credentials and returns JWT toke
 ```mermaid
 flowchart TD
     A([POST /api/auth/login]) --> B[/Parse Request Body/]
-    B --> C{{Validate Email & Password}}
+    B --> C{{"Validate Email & Password"}}
     C -->|Invalid| D[\400 Bad Request/]
     C -->|Valid| E[(Find User by Email)]
     E -->|Not Found| F[\401 Unauthorized/]
@@ -402,6 +433,16 @@ For each generated `.flow.md` file:
 1. Verify YAML frontmatter is valid (title, category present)
 2. Verify mermaid code block is properly fenced (``` mermaid ```)
 3. Verify mermaid syntax has no obvious errors (matched brackets, valid node IDs)
+4. **Special Character Validation (CRITICAL)**: Scan ALL node labels for unquoted special characters:
+   - `()` inside any node shape → MUST be quoted: `A(["label()"])` not `A([label()])`
+   - `{}` inside any node shape → MUST be quoted: `A{"label{}"}` not `A{label{}}`
+   - `[]` inside any node shape → MUST be quoted: `A["label[]"]` not `A[label[]]`
+   - `::` anywhere in labels → MUST be quoted: `A["std::io"]` not `A[std::io]`
+   - `#` anywhere in labels → MUST be quoted: `A["Issue #1"]` not `A[Issue #1]`
+   - `&` anywhere in labels → MUST be quoted: `A["A & B"]` not `A[A & B]`
+   - If ANY unquoted special characters are found, fix them BEFORE proceeding to build
+5. Verify all node IDs are unique within each diagram
+6. Verify subgraph labels don't contain special characters
 
 ### 5.2 Build Verification
 
@@ -483,6 +524,12 @@ Build: ✅ / ❌
 ### Mermaid syntax errors
 - **Brackets**: Every `[`, `{`, `(` must be closed
 - **Special characters in labels**: Wrap in double quotes: `A["User's Input"]`
+- **Parentheses in labels** (MOST COMMON): `A([run() Start])` → Parse error. Fix: `A(["run() Start"])`
+- **Double colons in labels**: `A[std::io::Error]` → Interpreted as class syntax. Fix: `A["std::io::Error"]`
+- **Curly braces in labels**: `B{select!{}}` → Conflicts with diamond shape. Fix: `B{"select!{}"}` 
+- **Square brackets in labels**: `C[arr[0]]` → Conflicts with rectangle shape. Fix: `C["arr[0]"]`
+- **Hash in labels**: `D[Issue #42]` → Unicode escape. Fix: `D["Issue #42"]`
+- **Ampersand in labels**: `E[A & B]` → HTML entity. Fix: `E["A & B"]`
 - **Arrow syntax**: Use `-->` for solid, `-.->` for dotted, `==>` for thick
 - **Node ID reuse**: Each node ID must be unique per diagram. Reuse ID to reference same node.
 - **Subgraph naming**: Subgraph labels cannot contain special characters