@windyroad/style-guide 0.2.0 → 0.2.1-preview.75

package/README.md

@@ -0,0 +1,57 @@
+# @windyroad/style-guide
+
+**Style guide enforcement for Claude Code.** Reviews CSS and UI component changes against your design system before they're applied.
+
+Part of [Windy Road Agent Plugins](../../README.md).
+
+## What It Does
+
+AI agents generate CSS that works but doesn't match your design system. They pick arbitrary colours, invent spacing values, and ignore your component patterns. This plugin catches that.
+
+The style-guide plugin:
+
+1. **Detects** when an edit touches CSS, style tokens, or visual styling
+2. **Blocks** the edit until the style-guide agent has reviewed it
+3. **Reviews** the proposed changes against your `docs/STYLE-GUIDE.md`
+4. **Reports** violations with suggested fixes
+
+## Install
+
+```bash
+npx @windyroad/style-guide
+```
+
+Restart Claude Code after installing.
+
+## Usage
+
+The plugin works automatically. On first use in a project without a style guide, it blocks edits and directs you to create one:
+
+```
+/wr-style-guide:update-guide
+```
+
+This examines your existing CSS, components, and design patterns, then asks about your style preferences to generate a `docs/STYLE-GUIDE.md`.
+
+## How It Works
+
+| Hook | Trigger | What it does |
+|------|---------|-------------|
+| `style-guide-eval.sh` | Every prompt | Evaluates whether the task involves visual styling |
+| `style-guide-enforce-edit.sh` | Edit or Write | Blocks edits until the style-guide agent has reviewed |
+| `style-guide-mark-reviewed.sh` | Agent completes | Marks the review as done (TTL: 1800s) |
+
+## Agent
+
+The `wr-style-guide:agent` reads your `docs/STYLE-GUIDE.md` and reviews proposed changes against your documented design system.
+
+## Updating and Uninstalling
+
+```bash
+npx @windyroad/style-guide --update
+npx @windyroad/style-guide --uninstall
+```
+
+## Licence
+
+[MIT](../../LICENSE)

package/bin/install.mjs

@@ -4,7 +4,7 @@ import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const utils = await import(resolve(__dirname, "../../shared/install-utils.mjs"));
+const utils = await import(resolve(__dirname, "../lib/install-utils.mjs"));
 
 const PLUGIN = "wr-style-guide";
 const DEPS = [];
@@ -20,6 +20,7 @@ Style guide enforcement for CSS and UI components
 Options:
   --update     Update this plugin and its skills
   --uninstall  Remove this plugin
+  --scope      Installation scope: project (default) or user
   --dry-run    Show what would be done without executing
   --help, -h   Show this help
 `);
@@ -36,7 +37,7 @@ utils.checkPrerequisites();
 if (flags.uninstall) {
   utils.uninstallPackage(PLUGIN);
 } else if (flags.update) {
-  utils.updatePackage(PLUGIN);
+  utils.updatePackage(PLUGIN, { scope: flags.scope });
 } else {
-  utils.installPackage(PLUGIN, { deps: DEPS });
+  utils.installPackage(PLUGIN, { deps: DEPS, scope: flags.scope });
 }

package/hooks/hooks.json

@@ -8,9 +8,6 @@
     ],
     "PostToolUse": [
       { "matcher": "Agent", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/style-guide-mark-reviewed.sh" }] }
-    ],
-    "Stop": [
-      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/style-guide-reset-marker.sh" }] }
     ]
   }
 }

package/hooks/lib/gate-helpers.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+# Shared portable helpers for gate enforcement hooks.
+# Sourced by architect-gate.sh, risk-gate.sh, and all hook scripts.
+# Provides: _mtime, _hashcmd, _doc_exclusions, _err_trap, _get_*
+
+# ---------------------------------------------------------------------------
+# Portable utilities
+# ---------------------------------------------------------------------------
+
+# Portable mtime: tries GNU stat, falls back to macOS stat
+_mtime() { stat -c%Y "$1" 2>/dev/null || /usr/bin/stat -f%m "$1" 2>/dev/null || echo 0; }
+
+# Portable hash: tries md5sum, falls back to md5 -r, then shasum
+_hashcmd() { md5sum 2>/dev/null || md5 -r 2>/dev/null || shasum 2>/dev/null; }
+
+# Paths excluded from pipeline state hashing and docs-only detection.
+_doc_exclusions() {
+    echo ':!docs/' ':!.risk-reports/' ':!.changeset/' ':!governance/' ':!.claude/plans/' ':!CLAUDE.md' ':!AGENTS.md' ':!PRINCIPLES.md' ':!DECISION-MANAGEMENT.md' ':!AGENTIC_RISK_REGISTER.md' ':!PROBLEM-MANAGEMENT.md'
+}
+
+# ---------------------------------------------------------------------------
+# ERR trap: outputs diagnostic JSON on hook errors (P010)
+# Usage: source gate-helpers.sh at top of hook, then call _enable_err_trap
+# ---------------------------------------------------------------------------
+
+_enable_err_trap() {
+    trap '_err_trap_handler "$BASH_SOURCE" "$LINENO" "$BASH_COMMAND"' ERR
+}
+
+_err_trap_handler() {
+    local script="$1" line="$2" cmd="$3"
+    local name
+    name=$(basename "$script" 2>/dev/null || echo "$script")
+    # Output diagnostic as systemMessage so it's visible in conversation
+    cat <<EOF
+{
+  "systemMessage": "Hook error in ${name} at line ${line}: ${cmd}"
+}
+EOF
+}
+
+# ---------------------------------------------------------------------------
+# JSON input parsing: standardised helpers replacing inline python3
+# Each reads from _HOOK_INPUT (set by the hook before calling these)
+# ---------------------------------------------------------------------------
+
+# Store hook input for reuse by parsing helpers
+_HOOK_INPUT=""
+
+_parse_input() {
+    _HOOK_INPUT=$(cat)
+}
+
+_get_tool_name() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_name', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_session_id() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('session_id', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_command() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('command', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_file_path() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    ti = data.get('tool_input', {})
+    print(ti.get('file_path', ti.get('path', '')))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_subagent_type() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('subagent_type', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_user_prompt() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('user_prompt', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_tool_output() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    # PostToolUse provides tool_response (dict with content array), not tool_output
+    tr = data.get('tool_response', {})
+    if isinstance(tr, dict):
+        content = tr.get('content', [])
+        if isinstance(content, list):
+            texts = [c.get('text', '') for c in content if isinstance(c, dict) and c.get('type') == 'text']
+            if texts:
+                print('\n'.join(texts))
+                sys.exit(0)
+    # Fallback for older/different hook formats
+    print(data.get('tool_output', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+# ---------------------------------------------------------------------------
+# Session-scoped tmp directory for risk files
+# ---------------------------------------------------------------------------
+
+# Returns the session-scoped directory for risk temp files.
+# Creates the directory if it doesn't exist.
+# Usage: DIR=$(_risk_dir "$SESSION_ID"); echo "1" > "$DIR/commit"
+_risk_dir() {
+  local sid="$1"
+  local dir="${TMPDIR:-/tmp}/claude-risk-${sid}"
+  mkdir -p "$dir"
+  echo "$dir"
+}
+
+# ---------------------------------------------------------------------------
+# Non-doc file detection for WIP gating
+# ---------------------------------------------------------------------------
+
+_is_doc_file() {
+    local file_path="$1"
+    local EXCL
+    EXCL=$(_doc_exclusions)
+    for pattern in $EXCL; do
+        local clean="${pattern#:!}"
+        case "$file_path" in
+            *"$clean"*) return 0 ;;
+        esac
+    done
+    case "$file_path" in
+        *.claude/*|*.risk-reports/*|*RISK-POLICY.md) return 0 ;;
+    esac
+    return 1
+}

package/hooks/lib/review-gate.sh

@@ -16,7 +16,7 @@ check_review_gate() {
   local POLICY_FILE="$3"   # e.g., "docs/STYLE-GUIDE.md"
   local MARKER="/tmp/${SYSTEM}-reviewed-${SESSION_ID}"
   local HASH_FILE="/tmp/${SYSTEM}-reviewed-${SESSION_ID}.hash"
-  local TTL_SECONDS="${REVIEW_TTL:-600}"
+  local TTL_SECONDS="${REVIEW_TTL:-1800}"
 
   # 1. Marker must exist
   if [ ! -f "$MARKER" ]; then

package/hooks/style-guide-enforce-edit.sh

@@ -35,6 +35,16 @@ if [ -z "$FILE_PATH" ]; then
   exit 0
 fi
 
+# P004: Only gate files inside the project root.
+case "$FILE_PATH" in
+  /*)
+    case "$FILE_PATH" in
+      "$PWD"/*) ;;
+      *) exit 0 ;;
+    esac
+    ;;
+esac
+
 # Gate all UI source files (CSS and component files)
 case "$FILE_PATH" in
   *.css|*.html|*.jsx|*.tsx|*.vue|*.svelte|*.ejs|*.hbs) ;;
@@ -45,7 +55,7 @@ BASENAME=$(basename "$FILE_PATH")
 
 # If no policy file exists, block and direct to create skill
 if [ ! -f "docs/STYLE-GUIDE.md" ]; then
-  review_gate_deny "BLOCKED: Cannot edit '${BASENAME}' because docs/STYLE-GUIDE.md does not exist. Run /wr-style-guide:create to generate a style guide for this project, then delegate to wr-style-guide:agent for review."
+  review_gate_deny "BLOCKED: Cannot edit '${BASENAME}' because docs/STYLE-GUIDE.md does not exist. Run /wr-style-guide:update-guide to generate a style guide for this project, then delegate to wr-style-guide:agent for review."
   exit 0
 fi
 

package/hooks/style-guide-eval.sh

@@ -28,7 +28,7 @@ else
     cat <<'HOOK_OUTPUT'
 NOTE: This project has UI files but no docs/STYLE-GUIDE.md.
 If the user's task involves editing CSS or UI components, the edit will be blocked
-until a style guide exists. Run /wr-style-guide:create to generate one.
+until a style guide exists. Run /wr-style-guide:update-guide to generate one.
 HOOK_OUTPUT
   fi
 fi

package/hooks/test/style-guide-no-stop-hook.bats

@@ -0,0 +1,15 @@
+#!/usr/bin/env bats
+
+# P001 / ADR-009: Stop-hook marker reset removed.
+
+setup() {
+  PLUGIN_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/../.." && pwd)"
+}
+
+@test "style-guide: hooks.json has no Stop hook entry (ADR-009)" {
+  ! grep -q '"Stop"' "$PLUGIN_DIR/hooks/hooks.json"
+}
+
+@test "style-guide: style-guide-reset-marker.sh has been removed" {
+  [ ! -f "$PLUGIN_DIR/hooks/style-guide-reset-marker.sh" ]
+}

package/hooks/test/style-guide-project-root.bats

@@ -0,0 +1,20 @@
+#!/usr/bin/env bats
+
+# P004: style-guide-enforce-edit.sh project-root check.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/style-guide-enforce-edit.sh"
+}
+
+run_hook_with_file() {
+  local file_path="$1"
+  local json="{\"tool_input\":{\"file_path\":\"${file_path}\"},\"session_id\":\"test-$$\"}"
+  echo "$json" | bash "$HOOK"
+}
+
+@test "style-guide project-root: absolute .css outside project exits 0" {
+  run run_hook_with_file "/Users/other/project/src/style.css"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}

package/lib/install-utils.mjs

@@ -0,0 +1,146 @@
+/**
+ * Shared install utilities for @windyroad/* packages.
+ * Used by both per-plugin installers and the meta-installer.
+ */
+
+import { execSync } from "node:child_process";
+
+const MARKETPLACE_REPO = "windyroad/agent-plugins";
+const MARKETPLACE_NAME = "windyroad";
+
+let _dryRun = false;
+
+export { MARKETPLACE_REPO, MARKETPLACE_NAME };
+
+export function setDryRun(value) {
+  _dryRun = value;
+}
+
+export function isDryRun() {
+  return _dryRun;
+}
+
+export function run(cmd, label) {
+  console.log(`  ${label}...`);
+  if (_dryRun) {
+    console.log(`    [dry-run] ${cmd}`);
+    return true;
+  }
+  try {
+    execSync(cmd, { stdio: "inherit" });
+    return true;
+  } catch {
+    console.error(`  FAILED: ${label}`);
+    return false;
+  }
+}
+
+export function checkPrerequisites() {
+  if (_dryRun) return;
+
+  try {
+    execSync("claude --version", { stdio: "pipe" });
+  } catch {
+    console.error(
+      "Error: 'claude' CLI not found. Install Claude Code first:\n  https://docs.anthropic.com/en/docs/claude-code\n"
+    );
+    process.exit(1);
+  }
+}
+
+export function addMarketplace() {
+  return run(
+    `claude plugin marketplace add ${MARKETPLACE_REPO}`,
+    `Marketplace: ${MARKETPLACE_NAME}`
+  );
+}
+
+export function installPlugin(pluginName, { scope = "project" } = {}) {
+  return run(
+    `claude plugin install ${pluginName}@${MARKETPLACE_NAME} --scope ${scope}`,
+    pluginName
+  );
+}
+
+export function updatePlugin(pluginName, { scope = "project" } = {}) {
+  return run(
+    `claude plugin update "${pluginName}@${MARKETPLACE_NAME}" --scope ${scope}`,
+    pluginName
+  );
+}
+
+export function uninstallPlugin(pluginName) {
+  return run(`claude plugin uninstall ${pluginName}`, `Removing ${pluginName}`);
+}
+
+/**
+ * Install a single package: marketplace add + plugin install.
+ */
+export function installPackage(pluginName, { deps = [], scope = "project" } = {}) {
+  console.log(`\nInstalling @windyroad/${pluginName.replace("wr-", "")} (${scope} scope)...\n`);
+
+  addMarketplace();
+  installPlugin(pluginName, { scope });
+
+  if (deps.length > 0) {
+    console.log(`\nNote: This plugin works best with:`);
+    for (const dep of deps) {
+      console.log(`  - @windyroad/${dep.replace("wr-", "")} (npx @windyroad/${dep.replace("wr-", "")})`);
+    }
+  }
+
+  console.log(
+    `\nDone! Restart Claude Code to activate.\n`
+  );
+}
+
+/**
+ * Update a single package.
+ */
+export function updatePackage(pluginName, { scope = "project" } = {}) {
+  console.log(`\nUpdating @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  run(
+    `claude plugin marketplace update ${MARKETPLACE_NAME}`,
+    "Updating marketplace"
+  );
+  updatePlugin(pluginName, { scope });
+
+  console.log("\nDone! Restart Claude Code to apply updates.\n");
+}
+
+/**
+ * Uninstall a single package.
+ */
+export function uninstallPackage(pluginName) {
+  console.log(`\nUninstalling @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  uninstallPlugin(pluginName);
+
+  console.log("\nDone. Restart Claude Code to apply changes.\n");
+}
+
+/**
+ * Parse standard flags used by all per-plugin installers.
+ */
+export function parseStandardArgs(argv) {
+  const args = argv.slice(2);
+  const flags = {
+    help: args.includes("--help") || args.includes("-h"),
+    uninstall: args.includes("--uninstall"),
+    update: args.includes("--update"),
+    dryRun: args.includes("--dry-run"),
+    scope: "project",
+  };
+  const scopeIdx = args.indexOf("--scope");
+  if (scopeIdx !== -1 && args[scopeIdx + 1]) {
+    const val = args[scopeIdx + 1];
+    if (["project", "user", "local"].includes(val)) {
+      flags.scope = val;
+    } else {
+      console.error("--scope requires: project, user, or local");
+      process.exit(1);
+    }
+  }
+  return flags;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/style-guide",
-  "version": "0.2.0",
+  "version": "0.2.1-preview.75",
   "description": "Style guide enforcement for CSS and UI components",
   "bin": {
     "windyroad-style-guide": "./bin/install.mjs"
@@ -23,6 +23,7 @@
     "agents/",
     "hooks/",
     "skills/",
-    ".claude-plugin/"
+    ".claude-plugin/",
+    "lib/"
   ]
 }

package/skills/{wr:style-guide → update-guide}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: wr:style-guide
+name: wr-style-guide:update-guide
 description: Create or update the project's docs/STYLE-GUIDE.md by examining existing CSS, components, and design patterns, then asking the user about style preferences.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---

package/hooks/style-guide-reset-marker.sh

@@ -1,22 +0,0 @@
-#!/bin/bash
-# Style Guide - Stop hook
-# Removes the session marker so the next prompt requires a fresh style review.
-# This tightens the gate from per-session to per-turn.
-
-INPUT=$(cat)
-
-SESSION_ID=$(echo "$INPUT" | python3 -c "
-import sys, json
-data = json.load(sys.stdin)
-print(data.get('session_id', ''))
-" 2>/dev/null)
-
-if [ -n "$SESSION_ID" ]; then
-  rm -f "/tmp/style-guide-reviewed-${SESSION_ID}" \
-        "/tmp/style-guide-reviewed-${SESSION_ID}.hash" \
-        "/tmp/style-guide-verdict" \
-        "/tmp/style-guide-plan-reviewed-${SESSION_ID}" \
-        "/tmp/style-guide-plan-verdict"
-fi
-
-exit 0