qualia-framework 3.2.0 → 3.3.0

package/bin/install.js

@@ -13,8 +13,11 @@ const YELLOW = "\x1b[38;2;234;179;8m";
 const RED = "\x1b[38;2;239;68;68m";
 const RESET = "\x1b[0m";
 
+const CLAUDE_DIR = path.join(require("os").homedir(), ".claude");
+const FRAMEWORK_DIR = path.resolve(__dirname, "..");
+
 // ─── Team codes ──────────────────────────────────────────
-const TEAM = {
+const DEFAULT_TEAM = {
   "QS-FAWZI-01": {
     name: "Fawzi Goussous",
     role: "OWNER",
@@ -23,27 +26,40 @@ const TEAM = {
   "QS-HASAN-02": {
     name: "Hasan",
     role: "EMPLOYEE",
-    description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+    description: "Developer. Feature branches only. Cannot push to main.",
   },
   "QS-MOAYAD-03": {
     name: "Moayad",
     role: "EMPLOYEE",
-    description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+    description: "Developer. Feature branches only. Cannot push to main.",
   },
   "QS-RAMA-04": {
     name: "Rama",
     role: "EMPLOYEE",
-    description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+    description: "Developer. Feature branches only. Cannot push to main.",
   },
   "QS-SALLY-05": {
     name: "Sally",
     role: "EMPLOYEE",
-    description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+    description: "Developer. Feature branches only. Cannot push to main.",
   },
 };
 
-const CLAUDE_DIR = path.join(require("os").homedir(), ".claude");
-const FRAMEWORK_DIR = path.resolve(__dirname, "..");
+// Load team from external file, fall back to embedded defaults.
+function loadTeam() {
+  const teamFile = path.join(CLAUDE_DIR, ".qualia-team.json");
+  try {
+    if (fs.existsSync(teamFile)) {
+      const external = JSON.parse(fs.readFileSync(teamFile, "utf8"));
+      if (external && typeof external === "object" && Object.keys(external).length > 0) {
+        return external;
+      }
+    }
+  } catch {}
+  return DEFAULT_TEAM;
+}
+
+const TEAM = loadTeam();
 
 let installed = 0;
 let errors = 0;
@@ -65,14 +81,96 @@ function copy(src, dest) {
   fs.copyFileSync(src, dest);
 }
 
+// Recursively copy a directory tree from src to dest.
+// Skips hidden files (dot-prefixed) to avoid syncing .DS_Store, editor temp files, etc.
+function copyTree(src, dest) {
+  if (!fs.existsSync(src)) return;
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name.startsWith(".")) continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyTree(srcPath, destPath);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// Surgically remove orphaned v2.6 install cruft from ~/.claude/ on upgrade.
+// v2.6 installed a separate ~/.claude/qualia-framework/ directory with workflows/,
+// references/, assets/, bin/qualia-tools.js. v3 doesn't use any of that — it was
+// just never cleaned up. Also removes broken qualia-*.md agents from the v2.6 era
+// that reference /home/qualia/ paths which don't exist.
+function cleanupLegacyV26() {
+  const removed = { dirs: [], files: [] };
+
+  // Remove the entire v2.6 framework leftover directory.
+  const v26Dir = path.join(CLAUDE_DIR, "qualia-framework");
+  try {
+    if (fs.existsSync(v26Dir)) {
+      const versionFile = path.join(v26Dir, "VERSION");
+      // Safety: only remove if it has the v2.6 shape (VERSION file exists)
+      if (fs.existsSync(versionFile)) {
+        fs.rmSync(v26Dir, { recursive: true, force: true });
+        removed.dirs.push("~/.claude/qualia-framework/ (v2.6 leftover)");
+      }
+    }
+  } catch {}
+
+  // Remove broken v2.6 agent files that reference /home/qualia/ paths.
+  // The canonical v3 agents ship with the framework (planner.md, builder.md, etc.)
+  // — scan all qualia-*.md files in agents/ and remove any that contain the
+  // /home/qualia/ signature (v2.6 broken absolute paths).
+  const agentsDest = path.join(CLAUDE_DIR, "agents");
+  try {
+    if (fs.existsSync(agentsDest)) {
+      for (const name of fs.readdirSync(agentsDest)) {
+        if (!name.startsWith("qualia-") || !name.endsWith(".md")) continue;
+        const p = path.join(agentsDest, name);
+        try {
+          const content = fs.readFileSync(p, "utf8");
+          if (content.includes("/home/qualia/.claude")) {
+            fs.unlinkSync(p);
+            removed.files.push(`agents/${name}`);
+          }
+        } catch {}
+      }
+    }
+  } catch {}
+
+  return removed;
+}
+
+// ─── Branded Header ─────────────────────────────────────
+const BOLD = "\x1b[1m";
+const TEAL_GLOW = "\x1b[38;2;0;170;175m";
+const PKG_VERSION = require("../package.json").version;
+const RULE = "━".repeat(48);
+
+function printHeader() {
+  console.log("");
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}⬢  Q U A L I A${RESET}`);
+  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log(`  ${WHITE}Framework v${PKG_VERSION}${RESET}  ${DIM}·${RESET}  ${TEAL_GLOW}Qualia Solutions${RESET}`);
+  console.log(`  ${DIM}Plan → Build → Verify → Ship${RESET}`);
+  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log("");
+}
+
+function printSection(title) {
+  console.log("");
+  console.log(`  ${TEAL}▸${RESET} ${WHITE}${BOLD}${title}${RESET}`);
+  console.log(`  ${DIM}${"─".repeat(40)}${RESET}`);
+}
+
 // ─── Prompt for code ─────────────────────────────────────
 function askCode() {
   return new Promise((resolve) => {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
-    console.log("");
-    console.log(`${TEAL}  ⬢ Qualia Framework v2${RESET}`);
-    console.log(`${DIM}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
-    console.log("");
+    printHeader();
     rl.question(`  ${WHITE}Enter install code:${RESET} `, (answer) => {
       rl.close();
       resolve(answer.trim());
@@ -111,10 +209,9 @@ async function main() {
   }
 
   console.log("");
-  log(`${GREEN}✓${RESET} ${WHITE}${member.name}${RESET} ${DIM}(${member.role})${RESET}`);
-  console.log("");
-  log(`Installing to ${WHITE}${CLAUDE_DIR}${RESET}`);
-  console.log("");
+  const roleColor = member.role === "OWNER" ? TEAL : GREEN;
+  console.log(`  ${GREEN}✓${RESET} ${WHITE}${BOLD}Welcome, ${member.name}${RESET}`);
+  console.log(`  ${DIM}  Role:${RESET} ${roleColor}${member.role}${RESET}  ${DIM}·${RESET}  ${DIM}Target:${RESET} ${WHITE}${CLAUDE_DIR}${RESET}`);
 
   // ─── Skills ──────────────────────────────────────────
   const skillsDir = path.join(FRAMEWORK_DIR, "skills");
@@ -122,7 +219,7 @@ async function main() {
     .readdirSync(skillsDir)
     .filter((d) => fs.statSync(path.join(skillsDir, d)).isDirectory());
 
-  log(`${WHITE}Skills${RESET}`);
+  printSection("Skills");
   for (const skill of skills) {
     try {
       copy(
@@ -136,7 +233,7 @@ async function main() {
   }
 
   // ─── Agents ────────────────────────────────────────────
-  log(`${WHITE}Agents${RESET}`);
+  printSection("Agents");
   const agentsDir = path.join(FRAMEWORK_DIR, "agents");
   for (const file of fs.readdirSync(agentsDir)) {
     try {
@@ -148,7 +245,7 @@ async function main() {
   }
 
   // ─── Rules ─────────────────────────────────────────────
-  log(`${WHITE}Rules${RESET}`);
+  printSection("Rules");
   const rulesDir = path.join(FRAMEWORK_DIR, "rules");
   for (const file of fs.readdirSync(rulesDir)) {
     try {
@@ -160,24 +257,26 @@ async function main() {
   }
 
   // ─── Hooks ─────────────────────────────────────────────
-  log(`${WHITE}Hooks${RESET}`);
+  printSection("Hooks");
   const hooksSource = path.join(FRAMEWORK_DIR, "hooks");
   const hooksDest = path.join(CLAUDE_DIR, "hooks");
   if (!fs.existsSync(hooksDest)) fs.mkdirSync(hooksDest, { recursive: true });
-  // Clean up legacy .sh hooks from previous installs so no orphans
-  // remain on disk after upgrading to the pure-Node hooks.
-  // Also purge explicitly-deprecated hooks by name (these are no longer
-  // shipped in framework/hooks/ but may linger on existing installs).
-  const DEPRECATED_HOOKS = [
-    "block-env-edit.js",  // v3.2.0: team decision to unblock .env read/write
-  ];
+  // Clean up legacy .sh hooks from previous v2.5/v2.6 installs so no orphans
+  // remain on disk after upgrading to the pure-Node v2.7+ hooks.
   try {
     for (const f of fs.readdirSync(hooksDest)) {
-      if (f.endsWith(".sh") || DEPRECATED_HOOKS.includes(f)) {
+      if (f.endsWith(".sh")) {
         try { fs.unlinkSync(path.join(hooksDest, f)); } catch {}
       }
     }
   } catch {}
+  // v3.2.0: purge deprecated hooks from existing installs on upgrade.
+  // block-env-edit.js was retired — team now has full read/write on .env*.
+  const DEPRECATED_HOOKS = ["block-env-edit.js"];
+  for (const f of DEPRECATED_HOOKS) {
+    const p = path.join(hooksDest, f);
+    try { if (fs.existsSync(p)) fs.unlinkSync(p); } catch {}
+  }
   for (const file of fs.readdirSync(hooksSource)) {
     try {
       const dest = path.join(hooksDest, file);
@@ -190,32 +289,56 @@ async function main() {
     }
   }
 
-  // ─── Status line ───────────────────────────────────────
-  log(`${WHITE}Status line${RESET}`);
-  try {
-    const slDest = path.join(CLAUDE_DIR, "bin", "statusline.js");
-    copy(path.join(FRAMEWORK_DIR, "bin", "statusline.js"), slDest);
-    ok("statusline.js");
-  } catch (e) {
-    warn(`statusline.js — ${e.message}`);
-  }
-
-  // ─── Templates ─────────────────────────────────────────
-  log(`${WHITE}Templates${RESET}`);
+  // ─── Templates (recursive — supports nested projects/ and research-project/) ─
+  printSection("Templates");
   const tmplDir = path.join(FRAMEWORK_DIR, "templates");
   const tmplDest = path.join(CLAUDE_DIR, "qualia-templates");
   if (!fs.existsSync(tmplDest)) fs.mkdirSync(tmplDest, { recursive: true });
-  for (const file of fs.readdirSync(tmplDir)) {
+  for (const entry of fs.readdirSync(tmplDir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".")) continue;
+    const srcPath = path.join(tmplDir, entry.name);
+    const destPath = path.join(tmplDest, entry.name);
     try {
-      copy(path.join(tmplDir, file), path.join(tmplDest, file));
-      ok(file);
+      if (entry.isDirectory()) {
+        copyTree(srcPath, destPath);
+        ok(`${entry.name}/ (directory)`);
+      } else {
+        copy(srcPath, destPath);
+        ok(entry.name);
+      }
     } catch (e) {
-      warn(`${file} — ${e.message}`);
+      warn(`${entry.name} — ${e.message}`);
+    }
+  }
+
+  // ─── References (methodology docs loaded by skills at runtime) ────
+  printSection("References");
+  const refDir = path.join(FRAMEWORK_DIR, "references");
+  const refDest = path.join(CLAUDE_DIR, "qualia-references");
+  if (fs.existsSync(refDir)) {
+    if (!fs.existsSync(refDest)) fs.mkdirSync(refDest, { recursive: true });
+    for (const file of fs.readdirSync(refDir)) {
+      try {
+        copy(path.join(refDir, file), path.join(refDest, file));
+        ok(file);
+      } catch (e) {
+        warn(`${file} — ${e.message}`);
+      }
     }
+  } else {
+    log(`${DIM}(no references/ in framework — skipping)${RESET}`);
+  }
+
+  // ─── Cleanup legacy v2.6 install cruft ────────────────────
+  const legacy = cleanupLegacyV26();
+  if (legacy.dirs.length > 0 || legacy.files.length > 0) {
+    printSection("Cleanup (v2.6 leftover)");
+    for (const d of legacy.dirs) ok(`removed ${d}`);
+    for (const f of legacy.files) ok(`removed ${f}`);
   }
 
   // ─── CLAUDE.md with role ───────────────────────────────
-  log(`${WHITE}CLAUDE.md${RESET}`);
+  printSection("Configuration");
   try {
     let claudeMd = fs.readFileSync(
       path.join(FRAMEWORK_DIR, "CLAUDE.md"),
@@ -231,7 +354,7 @@ async function main() {
   }
 
   // ─── Scripts ─────────────────────────────────────────────
-  log(`${WHITE}Scripts${RESET}`);
+  printSection("Scripts");
   try {
     const binDest = path.join(CLAUDE_DIR, "bin");
     if (!fs.existsSync(binDest)) fs.mkdirSync(binDest, { recursive: true });
@@ -267,7 +390,7 @@ async function main() {
   }
 
   // ─── Knowledge directory ─────────────────────────────────
-  log(`${WHITE}Knowledge${RESET}`);
+  printSection("Knowledge Base");
   const knowledgeDir = path.join(CLAUDE_DIR, "knowledge");
   if (!fs.existsSync(knowledgeDir)) fs.mkdirSync(knowledgeDir, { recursive: true });
   const knowledgeFiles = {
@@ -333,7 +456,7 @@ Recurring issues and their solutions.
 **Symptom:** \`/qualia-ship\` is blocked with "service_role found in client code" for a file that's actually a Server Component (runs server-side only).
 **Cause:** pre-deploy-gate.js skips files matching \`.server.\` filename pattern OR \`server/\` directory path. If the Server Component is at \`app/admin/page.tsx\` (no .server. marker, not in a server/ dir), the scan flags it.
 **Workaround:** Rename to \`.server.tsx\` OR move to a \`server/\` subdirectory OR extract the service_role usage into a helper in \`lib/server/\`.
-**Framework version:** Known issue; better heuristic planned for a future release.
+**Framework version:** Known issue as of v2.8.1; better heuristic planned for v3.0.
 `,
     "client-prefs.md": `# Client Preferences
 
@@ -368,11 +491,16 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     role: member.role,
     version: require("../package.json").version,
     installed_at: new Date().toISOString().split("T")[0],
+    erp: {
+      enabled: true,
+      url: "https://portal.qualiasolutions.net",
+      api_key_file: ".erp-api-key",
+    },
   };
   fs.writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n");
 
   // ─── ERP API key (for report uploads) ──────────────────
-  log(`${WHITE}ERP integration${RESET}`);
+  printSection("ERP Integration");
   const erpKeyFile = path.join(CLAUDE_DIR, ".erp-api-key");
   if (!fs.existsSync(erpKeyFile)) {
     fs.writeFileSync(erpKeyFile, "qualia-claude-2026", { mode: 0o600 });
@@ -474,7 +602,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
             type: "command",
             if: "Bash(git push*)",
             command: nodeCmd("branch-guard.js"),
-            timeout: 10,
+            timeout: 5,
             statusMessage: "⬢ Checking branch permissions...",
           },
           {
@@ -521,38 +649,44 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     ],
   };
 
-  // Permissions
+  // Permissions — no restrictions on env files or branches.
+  // Everyone can read/write .env, push to main.
   if (!settings.permissions) settings.permissions = {};
   if (!settings.permissions.allow) settings.permissions.allow = [];
-  if (!settings.permissions.deny) {
-    settings.permissions.deny = [
-      "Read(./.env)",
-      "Read(./.env.*)",
-      "Read(./secrets/**)",
-    ];
+  if (!settings.permissions.deny) settings.permissions.deny = [];
+
+  // ─── Optional: next-devtools MCP ─────────────────────────
+  // Wire next-devtools-mcp for runtime error visibility in Next.js projects
+  if (!settings.mcpServers) settings.mcpServers = {};
+  if (!settings.mcpServers["next-devtools"]) {
+    settings.mcpServers["next-devtools"] = {
+      command: "npx",
+      args: ["next-devtools-mcp@0.3.10"],
+      disabled: false,
+    };
+    ok("MCP: next-devtools (runtime error visibility for Next.js projects)");
   }
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 
-  ok("Hooks: session-start, auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact");
+  ok("Hooks: session-start, auto-update, branch-guard, pre-push, migration-guard, deploy-gate, pre-compact");
   ok("Status line + spinner configured");
   ok("Environment variables + permissions");
 
   // ─── Summary ───────────────────────────────────────────
   console.log("");
-  console.log(`${TEAL}  ⬢ Installed ✓${RESET}`);
-  console.log(`${DIM}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
-  console.log(`  ${WHITE}${member.name}${RESET} ${DIM}(${member.role})${RESET}`);
-  console.log(`  Skills:       ${WHITE}${skills.length}${RESET}`);
+  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log(`  ${TEAL}${BOLD}⬢  INSTALLED${RESET}`);
+  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log("");
+  console.log(`  ${WHITE}${BOLD}${member.name}${RESET}  ${DIM}·${RESET}  ${roleColor}${member.role}${RESET}  ${DIM}·${RESET}  ${DIM}v${PKG_VERSION}${RESET}`);
+  console.log("");
   const agentCount = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')).length;
-  console.log(`  Agents:       ${WHITE}${agentCount}${RESET} ${DIM}(planner, builder, verifier, qa-browser)${RESET}`);
-  console.log(`  Hooks:        ${WHITE}8${RESET} ${DIM}(session-start, auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact)${RESET}`);
-  console.log(`  Rules:        ${WHITE}${fs.readdirSync(rulesDir).length}${RESET} ${DIM}(security, frontend, design-reference, deployment)${RESET}`);
-  console.log(`  Scripts:      ${WHITE}3${RESET} ${DIM}(state.js, qualia-ui.js, statusline.js)${RESET}`);
-  console.log(`  Knowledge:    ${WHITE}3${RESET} ${DIM}(patterns, fixes, client prefs)${RESET}`);
-  console.log(`  Templates:    ${WHITE}${fs.readdirSync(tmplDir).length}${RESET}`);
-  console.log(`  Status line:  ${GREEN}✓${RESET}`);
-  console.log(`  CLAUDE.md:    ${GREEN}✓${RESET} ${DIM}(${member.role})${RESET}`);
+  const hookCount = fs.readdirSync(hooksSource).length;
+  const ruleCount = fs.readdirSync(rulesDir).length;
+  const tmplCount = fs.readdirSync(tmplDir).length;
+  console.log(`  ${DIM}Skills${RESET}    ${TEAL}${skills.length}${RESET}     ${DIM}Agents${RESET}  ${TEAL}${agentCount}${RESET}     ${DIM}Hooks${RESET}   ${TEAL}${hookCount}${RESET}`);
+  console.log(`  ${DIM}Rules${RESET}     ${TEAL}${ruleCount}${RESET}     ${DIM}Scripts${RESET} ${TEAL}3${RESET}     ${DIM}Templates${RESET} ${TEAL}${tmplCount}${RESET}`);
 
   if (errors > 0) {
     console.log("");
@@ -560,7 +694,22 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   }
 
   console.log("");
-  console.log(`  Restart Claude Code, then type ${TEAL}/qualia${RESET} in any project.`);
+  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log(`  ${WHITE}${BOLD}Quick Start${RESET}`);
+  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log("");
+  console.log(`  ${TEAL}1.${RESET} ${WHITE}Restart Claude Code${RESET} ${DIM}(loads new settings)${RESET}`);
+  console.log(`  ${TEAL}2.${RESET} ${WHITE}cd into any project${RESET} ${DIM}and run${RESET} ${TEAL}claude${RESET}`);
+  console.log(`  ${TEAL}3.${RESET} ${WHITE}Type${RESET} ${TEAL}${BOLD}/qualia${RESET} ${DIM}— it tells you what to do next${RESET}`);
+  console.log("");
+  console.log(`  ${DIM}New project?${RESET}    ${TEAL}/qualia-new${RESET}`);
+  console.log(`  ${DIM}Quick fix?${RESET}      ${TEAL}/qualia-quick${RESET}`);
+  console.log(`  ${DIM}End of day?${RESET}     ${TEAL}/qualia-report${RESET} ${DIM}(mandatory)${RESET}`);
+  console.log(`  ${DIM}Stuck?${RESET}          ${TEAL}/qualia${RESET}`);
+  console.log("");
+  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log(`  ${TEAL}${BOLD}Welcome to the future with Qualia.${RESET}`);
+  console.log(`  ${DIM}${RULE}${RESET}`);
   console.log("");
 }
 

package/bin/qualia-ui.js

@@ -249,6 +249,16 @@ function cmdNext(cmd) {
   console.log("");
 }
 
+function cmdEnd(status, nextCmd) {
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}⬢${RESET} ${WHITE}${BOLD}${status || "DONE"}${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+  if (nextCmd) {
+    console.log(`  ${TEAL}⟶${RESET} ${WHITE}Next:${RESET}  ${TEAL}${BOLD}${nextCmd}${RESET}`);
+  }
+  console.log("");
+}
+
 function cmdUpdate(current, latest) {
   if (!current || !latest) return;
   console.log("");
@@ -262,16 +272,6 @@ function cmdUpdate(current, latest) {
   console.log("");
 }
 
-function cmdEnd(status, nextCmd) {
-  console.log("");
-  console.log(`  ${TEAL}${BOLD}⬢${RESET} ${WHITE}${BOLD}${status || "DONE"}${RESET}`);
-  console.log(`  ${RULE_DIM}`);
-  if (nextCmd) {
-    console.log(`  ${TEAL}⟶${RESET} ${WHITE}Next:${RESET}  ${TEAL}${BOLD}${nextCmd}${RESET}`);
-  }
-  console.log("");
-}
-
 // ─── Main ────────────────────────────────────────────────
 const [cmd, ...rest] = process.argv.slice(2);
 switch (cmd) {
@@ -293,7 +293,7 @@ switch (cmd) {
   case "update":   cmdUpdate(rest[0], rest[1]); break;
   default:
     console.error(
-      `Usage: qualia-ui.js <banner|context|divider|ok|fail|warn|info|spawn|wave|task|done|next|end> [args]`
+      `Usage: qualia-ui.js <banner|context|divider|ok|fail|warn|info|spawn|wave|task|done|next|end|update> [args]`
     );
     process.exit(1);
 }