baldart 3.6.2

package/framework/.claude/hooks/framework-edit-gate.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * framework-edit-gate — Claude Code PreToolUse hook.
+ *
+ * Intercepts Edit / Write / MultiEdit calls whose target resolves (via
+ * symlink) to a path inside `.framework/` — i.e. the BALDART subtree that
+ * flows upstream via `baldart push`. Runs the contamination scanner on the
+ * new content and blocks the call with an informative `reason` if any
+ * project-specific tokens are present (Neo-Brutalism, merchant, fidelity,
+ * Recharts, hardcoded paths, etc.).
+ *
+ * Effect: Claude sees the block reason and either reformulates the content
+ * generically (referencing `${paths.X}` / `identity.X`) or moves the change
+ * into `.baldart/overlays/<skill>.md`. Project-specific tokens never reach
+ * the framework subtree silently.
+ *
+ * Registration: see src/utils/hooks.js — `baldart add` and `baldart update`
+ * auto-register this hook in the consumer's `.claude/settings.json`.
+ *
+ * Fail-safe contract: this hook MUST NOT block legitimate work. If anything
+ * unexpected happens (missing scanner, parse error, IO error), it exits 0
+ * and lets the tool call through. We optimise for false negatives over
+ * false blocks — the scanner is a safety net, not a tribunal.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function safeExit() {
+  process.exit(0);
+}
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch (_) {
+    return '';
+  }
+}
+
+function parseInput(raw) {
+  if (!raw) return null;
+  try { return JSON.parse(raw); } catch (_) { return null; }
+}
+
+function extractNewContent(toolName, toolInput) {
+  if (!toolInput) return '';
+  if (toolName === 'Edit') return String(toolInput.new_string || '');
+  if (toolName === 'Write') return String(toolInput.content || '');
+  if (toolName === 'MultiEdit') {
+    const edits = Array.isArray(toolInput.edits) ? toolInput.edits : [];
+    return edits.map((e) => String(e.new_string || '')).join('\n');
+  }
+  if (toolName === 'NotebookEdit') return String(toolInput.new_source || '');
+  return '';
+}
+
+function resolveReal(targetPath) {
+  if (!targetPath) return null;
+  // If file exists, realpath resolves symlinks all the way.
+  if (fs.existsSync(targetPath)) {
+    try { return fs.realpathSync(targetPath); } catch (_) {}
+  }
+  // For files about to be created, resolve the parent and rejoin.
+  try {
+    const parent = path.dirname(targetPath);
+    if (fs.existsSync(parent)) {
+      return path.join(fs.realpathSync(parent), path.basename(targetPath));
+    }
+  } catch (_) {}
+  return path.resolve(targetPath);
+}
+
+function findFrameworkRoot(realPath) {
+  // realPath looks like .../<consumer>/.framework/framework/.claude/skills/...
+  // Find the segment ".framework" and return the path up through it.
+  const sep = path.sep;
+  const idx = realPath.lastIndexOf(`${sep}.framework${sep}`);
+  if (idx === -1) return null;
+  return realPath.slice(0, idx + `${sep}.framework`.length);
+}
+
+function loadScanner(frameworkRoot) {
+  // Prefer the scanner from the same framework subtree the file lives in.
+  const candidates = [
+    path.join(frameworkRoot, 'src', 'utils', 'contamination.js'),
+    path.join(process.cwd(), '.framework', 'src', 'utils', 'contamination.js'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) {
+      try { return require(c); } catch (_) { /* try next */ }
+    }
+  }
+  return null;
+}
+
+function blockReason(realPath, decisions, blockings) {
+  const findingLines = [...blockings, ...decisions]
+    .slice(0, 12)
+    .map((f) => `  • L${f.lineNum}: ${f.label} (matched: "${f.match.slice(0, 40)}") — ${f.advice}`)
+    .join('\n');
+  const more = (decisions.length + blockings.length) > 12
+    ? `\n  • … and ${decisions.length + blockings.length - 12} more`
+    : '';
+
+  const blockNote = blockings.length
+    ? `\n\nIMPORTANT: ${blockings.length} of these are HARD BLOCKS (look like secrets or credentials). Even forcing through will require manual cleanup.`
+    : '';
+
+  return [
+    `framework-edit-gate: you are about to write to`,
+    `  ${realPath}`,
+    `which is inside the BALDART framework subtree (\`.framework/\`).`,
+    `Changes here flow UPSTREAM via \`baldart push\`. The contamination`,
+    `scanner detected ${decisions.length + blockings.length} project-specific token(s):`,
+    ``,
+    findingLines + more,
+    blockNote,
+    ``,
+    `Decide which case this is:`,
+    ``,
+    `(A) Generic improvement (useful to all consumers of the framework)`,
+    `    → Reformulate WITHOUT these tokens:`,
+    `      - hardcoded paths       → use \${paths.X} (e.g. \${paths.design_system})`,
+    `      - "Neo-Brutalism" etc.  → reference identity.design_philosophy`,
+    `      - "merchant"/"customer" → reference identity.audience_segments`,
+    `      - "recharts" / "@nivo"  → reference stack.charting.canonical`,
+    `    Then retry the edit. The scanner will let it through.`,
+    ``,
+    `(B) Project-specific opinion (only relevant to THIS consumer)`,
+    `    → Do not write to \`.framework/\`. Instead write to:`,
+    `      .baldart/overlays/<skill-name>.md`,
+    `    This file is consumer-owned, never pushed upstream.`,
+    ``,
+    `(C) Legitimate illustrative example (e.g. docs that quote the canonical`,
+    `    paths as examples — \`PROJECT-CONFIGURATION.md\`, \`project-context.md\`)`,
+    `    → Add the opt-out marker at the top of the file:`,
+    `      <!-- contamination-scan: skip -->`,
+    `    or in the YAML frontmatter:`,
+    `      contamination_scan: skip`,
+    `    Then retry the edit.`,
+    ``,
+    `If you are sure none of A/B/C apply, ask the user explicitly before`,
+    `forcing the change through (e.g. by temporarily disabling this hook).`,
+  ].join('\n');
+}
+
+function main() {
+  const raw = readStdin();
+  const input = parseInput(raw);
+  if (!input) safeExit();
+
+  const toolName = input.tool_name;
+  if (!['Edit', 'Write', 'MultiEdit', 'NotebookEdit'].includes(toolName)) safeExit();
+
+  const filePath = input.tool_input && input.tool_input.file_path;
+  if (!filePath || typeof filePath !== 'string') safeExit();
+
+  const realPath = resolveReal(filePath);
+  if (!realPath) safeExit();
+
+  const frameworkRoot = findFrameworkRoot(realPath);
+  if (!frameworkRoot) safeExit(); // outside .framework/ — nothing to do.
+
+  // Allow writes to .baldart/overlays/ even if the realPath has .framework in
+  // it for some reason — paranoid guard, shouldn't normally fire.
+  if (realPath.includes(`${path.sep}.baldart${path.sep}overlays${path.sep}`)) safeExit();
+
+  const scanner = loadScanner(frameworkRoot);
+  if (!scanner) safeExit(); // fail-safe — scanner missing, let it through.
+
+  const newContent = extractNewContent(toolName, input.tool_input);
+  if (!newContent) safeExit();
+
+  let findings;
+  try {
+    const r = scanner.scan(newContent);
+    if (r.optedOut) safeExit(); // file declared opt-out — let through.
+    findings = r.findings || [];
+  } catch (_) {
+    safeExit();
+  }
+
+  const decisions = findings.filter((f) => f.severity === 'requires-decision');
+  const blockings = findings.filter((f) => f.severity === 'block');
+  if (decisions.length === 0 && blockings.length === 0) safeExit();
+
+  const reason = blockReason(realPath, decisions, blockings);
+
+  try {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    }));
+  } catch (_) {
+    // Fallback to legacy mode: exit code 2 + stderr.
+    process.stderr.write(reason + '\n');
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+try { main(); } catch (_) { safeExit(); }

package/framework/.claude/hooks/lint-before-commit.sh.template

@@ -0,0 +1,66 @@
+#!/bin/bash
+# Lint check hook - runs before git commit to catch errors early
+#
+# Exit codes:
+#   0 = allow command to proceed
+#   2 = block command and show error to Claude
+#
+# SETUP INSTRUCTIONS:
+# 1. Copy this file to .claude/hooks/lint-before-commit.sh
+# 2. Make it executable: chmod +x .claude/hooks/lint-before-commit.sh
+# 3. Customize the lint/build commands for your project
+# 4. Test it: echo '{"command":"git commit -m test"}' | .claude/hooks/lint-before-commit.sh
+
+# Read hook input from stdin (JSON with tool_input)
+INPUT=$(cat)
+
+# Extract command - handle both direct command and nested structure
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // .command // empty' 2>/dev/null)
+
+# Only run lint check for git commit commands
+if echo "$COMMAND" | grep -qE 'git commit'; then
+  echo "Running lint check before commit..." >&2
+
+  # Run linter - CUSTOMIZE THIS FOR YOUR PROJECT
+  # Examples:
+  # - Node.js/npm: npm run lint
+  # - Python: pylint src/ or flake8 src/
+  # - Ruby: rubocop
+  # - Go: golangci-lint run
+  LINT_OUTPUT=$(npm run lint 2>&1)  # <-- CUSTOMIZE THIS COMMAND
+  LINT_EXIT=$?
+
+  if [ $LINT_EXIT -ne 0 ]; then
+    echo "" >&2
+    echo "LINT ERRORS - must fix before committing:" >&2
+    echo "$LINT_OUTPUT" >&2
+    echo "" >&2
+    echo "Fix these errors and try the commit again." >&2
+    exit 2  # Block the git commit
+  fi
+
+  echo "Lint check passed." >&2
+
+  # Run build check - CUSTOMIZE THIS FOR YOUR PROJECT
+  # Examples:
+  # - Node.js/npm: npm run build
+  # - Python: python setup.py build
+  # - Go: go build
+  # - Rust: cargo build
+  echo "Running build check before commit..." >&2
+  BUILD_OUTPUT=$(npm run build 2>&1)  # <-- CUSTOMIZE THIS COMMAND
+  BUILD_EXIT=$?
+
+  if [ $BUILD_EXIT -ne 0 ]; then
+    echo "" >&2
+    echo "BUILD ERRORS - must fix before committing:" >&2
+    echo "$BUILD_OUTPUT" >&2
+    echo "" >&2
+    echo "Fix these errors and try the commit again." >&2
+    exit 2  # Block the git commit
+  fi
+
+  echo "Build check passed." >&2
+fi
+
+exit 0  # Allow the command

package/framework/.claude/settings.local.json.example

@@ -0,0 +1,32 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cd *)",
+      "Bash(npm *)",
+      "Bash(npx *)",
+      "Bash(node *)",
+      "Bash(git *)",
+      "Bash(gh *)",
+      "Bash(ls *)",
+      "Bash(cat *)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(find *)",
+      "Bash(grep *)",
+      "Bash(rg *)",
+      "Bash(diff *)",
+      "Bash(wc *)",
+      "Bash(test *)",
+      "Bash(echo *)",
+      "WebFetch",
+      "WebSearch"
+    ],
+    "deny": [
+      "Bash(git push --force *)",
+      "Bash(git push -f *)",
+      "Bash(git reset --hard *)",
+      "Bash(git branch -D *)",
+      "Bash(rm -rf *)"
+    ]
+  }
+}