qualia-framework 2.5.1 → 3.1.0

package/hooks/branch-guard.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/branch-guard.js — block non-OWNER push to main/master.
+// PreToolUse hook on `git push*` commands. Reads role from
+// ~/.claude/.qualia-config.json (single source of truth).
+// Exits 1 to BLOCK. Exits 0 to allow.
+// Cross-platform (Windows/macOS/Linux).
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+const _traceStart = Date.now();
+
+const CONFIG = path.join(os.homedir(), ".claude", ".qualia-config.json");
+
+function _trace(hookName, result, extra) {
+  try {
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: hookName,
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+function fail(msg) {
+  console.log(msg);
+  _trace("branch-guard", "block", { reason: msg });
+  process.exit(2);
+}
+
+let role = "";
+try {
+  const cfg = JSON.parse(fs.readFileSync(CONFIG, "utf8"));
+  role = cfg.role || "";
+} catch {
+  fail(`BLOCKED: ${CONFIG} missing or unreadable. Run: npx qualia-framework install`);
+}
+
+if (!role) {
+  fail(`BLOCKED: Cannot determine role from ${CONFIG}. Defaulting to deny.`);
+}
+
+// Ask git for the current branch --show-current. Works identically on Windows/macOS/Linux.
+const r = spawnSync("git", ["branch", "--show-current"], {
+  encoding: "utf8",
+  timeout: 3000,
+});
+const branch = ((r.stdout || "").trim());
+
+if (branch === "main" || branch === "master") {
+  if (role !== "OWNER") {
+    console.log(`BLOCKED: Employees cannot push to ${branch}. Create a feature branch first.`);
+    console.log("Run: git checkout -b feature/your-feature-name");
+    _trace("branch-guard", "block", { reason: `non-owner push to ${branch}` });
+    process.exit(2);
+  }
+}
+
+_trace("branch-guard", "allow");
+process.exit(0);

package/hooks/migration-guard.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/migration-guard.js — catch dangerous SQL patterns in migrations.
+// PreToolUse hook on Edit/Write tool calls. Reads tool input as JSON on stdin.
+// Exits 2 to BLOCK. Exits 0 to allow.
+// Cross-platform (Windows/macOS/Linux).
+
+const fs = require("fs");
+
+const _traceStart = Date.now();
+
+function readInput() {
+  try {
+    const raw = fs.readFileSync(0, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+const input = readInput();
+const ti = input.tool_input || {};
+const file = String(ti.file_path || "").replace(/\\/g, "/");
+const content = String(ti.content || ti.new_string || "");
+
+function _trace(hookName, result, extra) {
+  try {
+    const os = require("os");
+    const path = require("path");
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: hookName,
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const filePath = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(filePath, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+// Only inspect migration/SQL files
+if (!/migration|migrate|\.sql$/i.test(file)) {
+  _trace("migration-guard", "allow", { reason: "non-migration file" });
+  process.exit(0);
+}
+
+const errors = [];
+
+// DROP TABLE without IF EXISTS
+if (/DROP\s+TABLE/i.test(content) && !/IF\s+EXISTS/i.test(content)) {
+  errors.push("DROP TABLE without IF EXISTS");
+}
+
+// DELETE without WHERE
+if (/DELETE\s+FROM/i.test(content) && !/WHERE/i.test(content)) {
+  errors.push("DELETE FROM without WHERE clause");
+}
+
+// TRUNCATE (almost always wrong in migrations)
+if (/TRUNCATE/i.test(content)) {
+  errors.push("TRUNCATE detected — are you sure?");
+}
+
+// CREATE TABLE without RLS
+if (/CREATE\s+TABLE/i.test(content) && !/ENABLE\s+ROW\s+LEVEL\s+SECURITY/i.test(content)) {
+  errors.push("CREATE TABLE without ENABLE ROW LEVEL SECURITY");
+}
+
+if (errors.length > 0) {
+  console.log("⬢ Migration guard — dangerous patterns found:");
+  for (const e of errors) {
+    console.log(`  ✗ ${e}`);
+  }
+  console.log("");
+  console.log("Fix these before proceeding. If intentional, ask Fawzi to approve.");
+  _trace("migration-guard", "block", { errors });
+  process.exit(2);
+}
+
+_trace("migration-guard", "allow");
+process.exit(0);

package/hooks/pre-compact.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/pre-compact.js — commit STATE.md before context compaction.
+// PreCompact hook. Silent on failure — context compaction must never be blocked.
+// Cross-platform (Windows/macOS/Linux).
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const _traceStart = Date.now();
+
+const STATE_FILE = path.join(".planning", "STATE.md");
+
+try {
+  if (fs.existsSync(STATE_FILE)) {
+    console.log("QUALIA: Saving state before compaction...");
+    // Check if STATE.md has uncommitted changes
+    const diff = spawnSync("git", ["diff", "--name-only", STATE_FILE], {
+      encoding: "utf8",
+      timeout: 3000,
+    });
+    if ((diff.stdout || "").includes("STATE.md")) {
+      spawnSync("git", ["add", STATE_FILE], { timeout: 3000 });
+      spawnSync("git", ["commit", "-m", "state: pre-compaction save"], {
+        timeout: 5000,
+        stdio: "ignore",
+      });
+    }
+  }
+} catch {
+  // Silent — never block compaction
+}
+
+function _trace(hookName, result, extra) {
+  try {
+    const os = require("os");
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: hookName,
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+_trace("pre-compact", "allow");
+process.exit(0);

package/hooks/pre-deploy-gate.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/pre-deploy-gate.js — quality gates before production deploy.
+// PreToolUse hook on `vercel --prod*` commands. Runs tsc, lint, tests, build,
+// then scans for service_role leaks in client code.
+// Exits 1 to BLOCK deploy. Exits 0 to allow.
+// Cross-platform (Windows/macOS/Linux). No `grep` or `find` — pure Node.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const _traceStart = Date.now();
+
+function _trace(hookName, result, extra) {
+  try {
+    const os = require("os");
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: hookName,
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+function runGate(label, cmd, args, { required = true } = {}) {
+  const r = spawnSync(cmd, args, {
+    stdio: "ignore",
+    timeout: 180000,
+    shell: process.platform === "win32",
+  });
+  if (r.status === 0) {
+    console.log(`  ✓ ${label}`);
+    return true;
+  }
+  if (required) {
+    console.log(`BLOCKED: ${label} errors. Fix before deploying.`);
+    _trace("pre-deploy-gate", "block", { gate: label });
+    process.exit(1);
+  }
+  return false;
+}
+
+function hasScript(name) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+    return pkg.scripts && typeof pkg.scripts[name] === "string";
+  } catch {
+    return false;
+  }
+}
+
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (e.name === "node_modules" || e.name.startsWith(".")) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      walk(full, out);
+    } else if (/\.(ts|tsx|js|jsx|mjs|cjs)$/.test(e.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function scanServiceRoleLeaks() {
+  const roots = ["app", "components", "src", "pages", "lib"];
+  const leaks = [];
+  for (const root of roots) {
+    for (const file of walk(root)) {
+      // --- Path-based skips (no I/O needed) ---
+
+      // Skip server-only files (convention: *.server.ts, server/ dirs)
+      if (/\.server\.|[\\/]server[\\/]/.test(file)) continue;
+
+      // Skip App Router route handlers (always server-side)
+      if (/[\\/]route\.(ts|tsx|js|jsx|mjs)$/.test(file)) continue;
+
+      // Skip middleware (always server-side)
+      if (/[\\/]middleware\.(ts|tsx|js|jsx|mjs)$/.test(file)) continue;
+
+      // Skip files in app/api/ directory (always server-side)
+      if (/[\\/]app[\\/]api[\\/]/.test(file)) continue;
+
+      // --- Content-based checks (requires reading file) ---
+      try {
+        const content = fs.readFileSync(file, "utf8");
+
+        // Skip files with "use server" directive (Server Actions / Server Components)
+        if (/^["']use server["']/m.test(content)) continue;
+
+        if (/service_role/.test(content)) {
+          leaks.push(file);
+        }
+      } catch {}
+    }
+  }
+  return leaks;
+}
+
+console.log("⬢ Pre-deploy gate...");
+
+// TypeScript
+if (fs.existsSync("tsconfig.json")) {
+  runGate("TypeScript", "npx", ["tsc", "--noEmit"]);
+}
+
+// Lint
+if (hasScript("lint")) {
+  runGate("Lint", "npm", ["run", "lint"]);
+}
+
+// Tests
+if (hasScript("test")) {
+  runGate("Tests", "npm", ["test"]);
+}
+
+// Build
+if (hasScript("build")) {
+  runGate("Build", "npm", ["run", "build"]);
+}
+
+// Security: no service_role in client code
+const leaks = scanServiceRoleLeaks();
+if (leaks.length > 0) {
+  console.log("BLOCKED: service_role found in client code. Remove before deploying.");
+  for (const f of leaks.slice(0, 10)) {
+    console.log(`  ✗ ${f}`);
+  }
+  _trace("pre-deploy-gate", "block", { gate: "security", leaks: leaks.slice(0, 10) });
+  process.exit(1);
+}
+console.log("  ✓ Security");
+console.log("⬢ All gates passed.");
+
+_trace("pre-deploy-gate", "allow");
+process.exit(0);

package/hooks/pre-push.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/pre-push.js — update tracking.json with last commit + timestamp.
+// PreToolUse hook on `git push*` commands. state.js handles phase/status sync;
+// this just stamps the file so the ERP sees fresh commit info on every push.
+// Cross-platform (Windows/macOS/Linux).
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const _traceStart = Date.now();
+
+const TRACKING = path.join(".planning", "tracking.json");
+
+try {
+  if (fs.existsSync(TRACKING)) {
+    const r = spawnSync("git", ["log", "--oneline", "-1", "--format=%h"], {
+      encoding: "utf8",
+      timeout: 3000,
+    });
+    const lastCommit = ((r.stdout || "").trim());
+    const now = new Date().toISOString().replace(/\.\d+Z$/, "Z");
+
+    const t = JSON.parse(fs.readFileSync(TRACKING, "utf8"));
+    if (lastCommit) t.last_commit = lastCommit;
+    t.last_updated = now;
+    fs.writeFileSync(TRACKING, JSON.stringify(t, null, 2) + "\n");
+
+    spawnSync("git", ["add", TRACKING], { timeout: 3000 });
+  }
+} catch (err) {
+  process.stderr.write(`WARNING: tracking sync failed: ${err.message}\n`);
+}
+
+function _trace(hookName, result, extra) {
+  try {
+    const os = require("os");
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: hookName,
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+_trace("pre-push", "allow");
+process.exit(0);

package/hooks/session-start.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/session-start.js — branded context panel on session start.
+// Cross-platform (Windows/macOS/Linux). Zero shell dependencies.
+//
+// CRITICAL: this hook must NEVER exit non-zero. Claude Code treats any non-zero
+// exit from a SessionStart hook as a "hook error" and shows a red banner. The
+// banner is purely informational — we'd rather render nothing than block a
+// session. Every call is wrapped in try/catch and we always exit 0 at the end.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+const _traceStart = Date.now();
+
+const HOME = os.homedir();
+const UI = path.join(HOME, ".claude", "bin", "qualia-ui.js");
+const STATE_FILE = path.join(".planning", "STATE.md");
+const CONTINUE_HERE = ".continue-here.md";
+
+function runUi(...args) {
+  if (!fs.existsSync(UI)) return;
+  try {
+    spawnSync(process.execPath, [UI, ...args], {
+      stdio: "inherit",
+      timeout: 3000,
+    });
+  } catch {}
+}
+
+function getNextCommand() {
+  const stateJs = path.join(HOME, ".claude", "bin", "state.js");
+  if (!fs.existsSync(stateJs)) return "";
+  try {
+    const r = spawnSync(process.execPath, [stateJs, "check"], {
+      encoding: "utf8",
+      timeout: 3000,
+    });
+    if (!r.stdout) return "";
+    const j = JSON.parse(r.stdout);
+    return j.next_command || "";
+  } catch {
+    return "";
+  }
+}
+
+function fallbackText() {
+  // If qualia-ui.js is missing, emit plain text. Keeps the session informative
+  // even on a broken install.
+  if (fs.existsSync(STATE_FILE)) {
+    try {
+      const content = fs.readFileSync(STATE_FILE, "utf8");
+      const phase = (content.match(/^Phase:\s*(.+)$/m) || [])[1] || "—";
+      const status = (content.match(/^Status:\s*(.+)$/m) || [])[1] || "—";
+      console.log(`QUALIA: Project loaded. Phase: ${phase.trim()} | Status: ${status.trim()}`);
+      console.log("QUALIA: Run /qualia for next step.");
+    } catch {
+      console.log("QUALIA: Project detected but STATE.md could not be read.");
+    }
+  } else if (fs.existsSync(CONTINUE_HERE)) {
+    console.log("QUALIA: Handoff file found. Read .continue-here.md to resume.");
+  } else {
+    console.log("QUALIA: No project detected. Run /qualia-new to start.");
+  }
+}
+
+try {
+  if (!fs.existsSync(UI)) {
+    fallbackText();
+  } else if (fs.existsSync(STATE_FILE)) {
+    runUi("banner", "router");
+    const next = getNextCommand();
+    if (next) {
+      console.log("");
+      runUi("next", next);
+    }
+  } else if (fs.existsSync(CONTINUE_HERE)) {
+    runUi("banner", "resume");
+    runUi("warn", "Previous session found — type /qualia-resume to pick up where you left off");
+    console.log("");
+  } else {
+    // No project — show a welcoming first-run experience
+    const config = readConfig();
+    const name = config.installed_by || "";
+    runUi("banner", "router");
+    if (name) {
+      console.log(`  ${TEAL}Ready when you are, ${name}.${RESET}`);
+    }
+    console.log("");
+    console.log(`  ${DIM}Start here:${RESET}`);
+    console.log(`    ${TEAL}/qualia-new${RESET}    ${DIM}Set up a new project${RESET}`);
+    console.log(`    ${TEAL}/qualia${RESET}        ${DIM}What should I do next?${RESET}`);
+    console.log(`    ${TEAL}/qualia-quick${RESET}  ${DIM}Quick fix (skip planning)${RESET}`);
+    console.log("");
+  }
+} catch {
+  // Deliberately silent — hook must never fail
+}
+
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(HOME, ".claude", ".qualia-config.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function _trace(hookName, result, extra) {
+  try {
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: hookName,
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+_trace("session-start", "allow");
+process.exit(0);

package/package.json

@@ -1,29 +1,43 @@
 {
   "name": "qualia-framework",
-  "version": "2.5.1",
-  "description": "Qualia Solutions — Claude Code Framework",
+  "version": "3.1.0",
+  "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
   },
-  "files": [
-    "bin/",
-    "framework/",
-    "profiles/",
-    "templates/"
+  "keywords": [
+    "claude-code",
+    "claude",
+    "ai",
+    "framework",
+    "workflow",
+    "qualia",
+    "agents",
+    "automation"
   ],
-  "engines": {
-    "node": ">=18.0.0"
-  },
+  "author": "Qualia Solutions <hello@qualia.solutions>",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Qualiasolutions/qualia-framework.git"
   },
-  "keywords": [
-    "claude-code",
-    "qualia",
-    "framework",
-    "ai-dev"
+  "homepage": "https://github.com/Qualiasolutions/qualia-framework#readme",
+  "scripts": {
+    "test": "node --test tests/runner.js"
+  },
+  "files": [
+    "bin/",
+    "agents/",
+    "hooks/",
+    "rules/",
+    "skills/",
+    "templates/",
+    "tests/",
+    "docs/",
+    "CLAUDE.md",
+    "guide.md"
   ],
-  "author": "Qualia Solutions",
-  "license": "UNLICENSED"
+  "engines": {
+    "node": ">=18"
+  }
 }