claude-code-autoconfig 1.0.74 → 1.0.78

package/.claude/commands/autoconfig.md

@@ -65,14 +65,16 @@ Focus on what Claude Code actually needs to work effectively. Claude can explore
 **Wrap content in markers** so `/sync-claude-md` knows what's auto-generated:
 
 ```markdown
-<!-- AUTO-GENERATED BY /autoconfig — Do not edit. Use .claude/feedback/ for corrections. -->
+<!-- AUTO-GENERATED BY /autoconfig at {TIMESTAMP} UTC — Do not edit. Use .claude/feedback/ for corrections. -->
 
 # Project Name
 ...content...
 
-<!-- END AUTO-GENERATED -->
+<!-- END AUTO-GENERATED at {TIMESTAMP} UTC — Use .claude/feedback/ for corrections. -->
 ```
 
+Replace `{TIMESTAMP}` with the current UTC time in format `YYYY-MM-DD HH:MM:SS` (e.g., `2026-01-14 16:30:45`). Use the same timestamp in both markers.
+
 **Always include:**
 - **Project name + one-liner**: What is this thing?
 - **Tech stack**: Runtime, framework, database, key services (so Claude uses correct patterns)
@@ -111,7 +113,67 @@ Write .claude/rules/.gitkeep with empty content
 
 Rules are path-scoped context files that load automatically when Claude works on matching files. Effective rules require deep understanding of your codebase patterns, team conventions, and quality goals — they should be crafted intentionally, not auto-generated.
 
-## Step 5: Configure Settings
+## Step 5: Configure Formatter (JS/Node Projects)
+
+**Only for projects with `package.json`:**
+
+1. Check if `scripts.format` already exists in `package.json`
+
+2. **If `scripts.format` exists:**
+   - Skip to adding the hook (Step 5b)
+
+3. **If `scripts.format` does NOT exist:**
+   - Ask the user:
+   ```
+   No formatter detected. Adding one ensures Claude's output
+   matches your project's style.
+
+   Should I add Prettier to this project? (y/n)
+   ```
+
+4. **If user says yes:**
+   - Run: `npm install -D prettier`
+   - Add to `package.json` scripts:
+     ```json
+     "format": "[ -f .prettierrc ] && prettier --write . || echo 'Create .prettierrc to enable formatting'"
+     ```
+   - Create `.prettierrc.example` in project root:
+     ```json
+     {
+       "semi": true,
+       "singleQuote": false,
+       "tabWidth": 2
+     }
+     ```
+   - Inform user: "Formatting is ready but inactive. Rename `.prettierrc.example` to `.prettierrc` when your team decides on style preferences."
+
+5. **If user says no:**
+   - Skip formatter setup, continue to Step 6
+
+**Step 5b: Add PostToolUse Format Hook**
+
+If the project has `scripts.format` (either existing or just added), add the format hook to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          { "type": "command", "command": "node .claude/hooks/format.js" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The format hook script (`.claude/hooks/format.js`) runs `npm run format` after Write/Edit operations on source files. Users can customize this script to add file filtering or different formatting logic.
+
+**Important:** Merge this with any existing hooks. Don't overwrite existing hooks.
+
+## Step 6: Configure Settings
 
 Update `.claude/settings.json` using the official schema.
 
@@ -173,7 +235,7 @@ Set session-level env vars:
 - Optimize for Claude's efficiency, not human documentation
 - When uncertain, leave it out — Claude can ask or explore
 
-## Step 6: Update the Docs
+## Step 7: Update the Docs
 
 After populating CLAUDE.md, update the docs file preview to show the actual content:
 
@@ -212,4 +274,14 @@ Run `/show-docs` to view the interactive documentation (requires full install vi
 
 ---
 
-**IMPORTANT**: Do not add any additional text, summaries, or details after this message. The finale should be clean and punchy - end here.
+**IMPORTANT**: Do not add any additional text, summaries, or details after this message. The finale should be clean and punchy - end here.
+
+### Windows Cleanup
+
+On Windows, if a `nul` file was accidentally created in the project root (a common artifact from bash/Unix command translation), delete it silently using the Bash tool:
+
+```bash
+del nul 2>NUL
+```
+
+Do this cleanup silently without any output to the user.

package/.claude/commands/commit-and-push.md

@@ -1,15 +1,17 @@
-<!-- @description Stages all changes, generates a conventional commit message from the diff, commits, and pushes. One command, full workflow. -->
+<!-- @description Runs tests, then stages all changes, generates a conventional commit message, commits, and pushes. -->
 
 # Commit and Push
 
-Stage all changes, create a commit with a good message, and push to the current branch.
+Run tests, stage all changes, create a commit with a good message, and push to the current branch.
 
 ## Steps
 
-1. Stage all changes (`git add -A`)
-2. Generate a conventional commit message based on the diff
-3. Commit the changes
-4. Push to the current branch
+1. Run the project's test suite (e.g., `npm test`)
+2. **If tests fail, stop here.** Do not commit or push failing code.
+3. Stage all changes (`git add -A`)
+4. Generate a conventional commit message based on the diff
+5. Commit the changes
+6. Push to the current branch
 
 ## Commit Message Format
 

package/.claude/commands/sync-claude-md.md

@@ -10,7 +10,11 @@ Run this when your project has changed significantly:
 - Restructured the project
 - Switched databases or services
 
-## Step 1: Re-analyze the Project
+## Step 1: Check for Team Feedback
+
+Before regenerating, check `.claude/feedback/FEEDBACK.md` for any corrections or guidance from the team. Review and incorporate relevant feedback into your regeneration.
+
+## Step 2: Re-analyze the Project
 
 Scan for current project indicators:
 
@@ -26,17 +30,19 @@ Scan for current project indicators:
 **Infrastructure:**
 - Docker, Terraform, CI/CD configs
 
-## Step 2: Update CLAUDE.md
+## Step 3: Update CLAUDE.md
 
 CLAUDE.md uses markers to identify auto-generated content:
 
 ```markdown
-<!-- AUTO-GENERATED BY /autoconfig — Do not edit. Use .claude/feedback/ for corrections. -->
+<!-- AUTO-GENERATED BY /autoconfig at {TIMESTAMP} UTC — Do not edit. Use .claude/feedback/ for corrections. -->
 ...content...
-<!-- END AUTO-GENERATED -->
+<!-- END AUTO-GENERATED at {TIMESTAMP} UTC — Use .claude/feedback/ for corrections. -->
 ```
 
-**Only regenerate content between these markers.** If content exists outside the markers (user added it despite the warning), preserve it.
+**IMPORTANT:** Always replace `{TIMESTAMP}` with the CURRENT UTC time in format `YYYY-MM-DD HH:MM:SS` (e.g., `2026-01-14 16:30:45`).
+
+**Only regenerate content between these markers.** Content outside markers will be removed on next sync - users should add feedback to `.claude/feedback/FEEDBACK.md` instead.
 
 Compare detected state with current CLAUDE.md and update:
 
@@ -49,7 +55,7 @@ Compare detected state with current CLAUDE.md and update:
 - The `## Retro` section pointer
 - The `## Team Feedback` section pointer
 
-## Step 3: Confirm Changes
+## Step 4: Confirm Changes
 
 Show the user what changed in CLAUDE.md before finishing.
 

package/.claude/docs/autoconfig.docs.html

@@ -885,6 +885,16 @@
                                 <span class="tree-file-icon">📄</span>
                                 <span class="file">FEEDBACK.md</span>
                             </div>
+                            <div class="tree-item indent-2 folder-row hidden collapsed" data-info="hooks" data-folder="hooks" data-parent="claude-dir">
+                                <span class="tree-chevron">›</span>
+                                <span class="tree-folder-icon">📁</span>
+                                <span class="folder">hooks</span>
+                            </div>
+                            <div class="tree-item indent-3 hidden" data-info="format-hook" data-parent="hooks">
+                                <span class="tree-spacer"></span>
+                                <span class="tree-file-icon">📄</span>
+                                <span class="file">format.js</span>
+                            </div>
                             <div class="tree-item indent-2 folder-row hidden collapsed" data-info="docs" data-folder="docs-folder" data-parent="claude-dir">
                                 <span class="tree-chevron">›</span>
                                 <span class="tree-folder-icon">📁</span>
@@ -1208,6 +1218,15 @@
                 title: 'FEEDBACK.md',
                 desc: 'Starter template for team feedback. Add dated entries when Claude makes mistakes — include what went wrong and the correct approach. Claude reads this on every session.'
             },
+            'hooks': {
+                title: 'hooks/',
+                desc: 'Executable scripts that run in response to Claude Code events. Unlike commands (which are prompts you invoke), hooks trigger automatically based on tool usage patterns.'
+            },
+            'format-hook': {
+                title: 'format.js',
+                desc: 'Runs the project formatter after Write/Edit operations on source files. Filters by file extension and skips generated directories like node_modules.',
+                trigger: 'PostToolUse on Write|Edit (JS/TS projects only)'
+            },
             'autoconfig': {
                 title: 'autoconfig.md',
                 desc: 'The command you just ran. Analyzes your project and populates CLAUDE.md with real context. Re-run anytime your stack changes.',
@@ -1772,6 +1791,30 @@ Always use the v2 API for user endpoints.
 
 ## 2026-01-07: Test database naming
 Use \`test_\` prefix for test databases, not \`dev_\`.`
+            },
+            'hooks': {
+                filename: 'hooks/',
+                content: null,
+                empty: true,
+                emptyMessage: 'Contains executable hook scripts that trigger on Claude Code events.'
+            },
+            'format-hook': {
+                filename: 'format.js',
+                content: `/**
+ * @name Format Hook
+ * @description Runs project formatter after Write/Edit operations
+ * @trigger PostToolUse on Write|Edit
+ */
+
+// Reads hook input from stdin
+// Filters by file extension (.js, .ts, .json, .css, etc.)
+// Skips generated directories (node_modules, dist, build)
+// Runs: npm run format --silent
+
+// Key behavior:
+// - Only triggers for source files
+// - Silently runs formatter (errors are non-fatal)
+// - Customizable - add your own file filters or formatting logic`
             }
         };
 

package/.claude/feedback/FEEDBACK.md

@@ -5,24 +5,36 @@
 Add corrections and guidance here when Claude does something wrong.
 Claude reads this directory and learns for next time.
 
-<!-- ╔══════════════════════════════════════════════════════════════════╗
-     ║                                                                  ║
-     ║   TEMPLATE BELOW — DELETE THIS BLOCK WHEN ADDING REAL FEEDBACK  ║
-     ║                                                                  ║
-     ╠══════════════════════════════════════════════════════════════════╣
-     ║                                                                  ║
-     ║   ## YYYY-MM-DD: Brief title                                     ║
-     ║                                                                  ║
-     ║   Describe what Claude did wrong and what to do instead.         ║
-     ║   Keep entries brief and actionable.                             ║
-     ║                                                                  ║
-     ║   Example:                                                       ║
-     ║                                                                  ║
-     ║   ## 2026-01-06: Don't use deprecated API                        ║
-     ║   Claude used `oldFunction()` instead of `newFunction()`.        ║
-     ║   Always use the v2 API for user endpoints.                      ║
-     ║                                                                  ║
-     ║   ## 2026-01-07: Test database naming                            ║
-     ║   Use `test_` prefix for test databases, not `dev_`.             ║
-     ║                                                                  ║
-     ╚══════════════════════════════════════════════════════════════════╝ -->
+---
+
+## Design Principles
+
+- Each file should have a single responsibility (one reason to change)
+- If a file exceeds 500 LOC, it likely lacks separation of concerns — look for decomposition opportunities
+- Keep cyclomatic complexity under 10 per function — extract helper functions or simplify branching if higher
+
+## Development Rules
+
+### Testing Requirements
+
+**CRITICAL: Before committing or outputting any changes to `bin/cli.js`, you MUST run tests and verify they pass:**
+
+```bash
+npm test
+```
+
+This runs tests which validate:
+1. All box-drawing lines have consistent visual width (accounting for ANSI escape codes)
+2. Box structure is valid (correct corner and border characters)
+3. CLI install files exist and are properly configured
+
+**DO NOT commit or present code changes if tests fail.** Fix the issues first.
+
+### Box Drawing Guidelines
+
+When modifying the "READY TO CONFIGURE" box in `bin/cli.js`:
+
+1. All lines must be exactly 46 visible characters wide (including the `║` borders)
+2. ANSI escape codes (`\x1b[...m`) don't count toward visible width
+3. Place color codes outside content spacing: `\x1b[33m║\x1b[0m` + 44 chars of content + `\x1b[33m║\x1b[0m`
+4. Always run `npm test` after any box modifications

package/.claude/hooks/format.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * @name Format Hook
+ * @description Runs project formatter after Write/Edit operations
+ * @trigger PostToolUse on Write|Edit
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+// Read hook input from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    handleHook(data);
+  } catch (err) {
+    // Silent exit if no valid input
+    process.exit(0);
+  }
+});
+
+function handleHook(data) {
+  const filePath = data?.tool_input?.file_path || '';
+
+  // Skip non-source files
+  if (!filePath.match(/\.(js|jsx|ts|tsx|json|css|scss|md|html)$/)) {
+    process.exit(0);
+  }
+
+  // Skip node_modules and other generated directories
+  if (filePath.includes('node_modules') || filePath.includes('dist/') || filePath.includes('build/')) {
+    process.exit(0);
+  }
+
+  try {
+    // Run formatter silently - errors are non-fatal
+    execSync('npm run format --silent 2>/dev/null || true', {
+      cwd: process.cwd(),
+      stdio: 'ignore'
+    });
+  } catch (err) {
+    // Formatting is best-effort, don't block on failure
+  }
+
+  process.exit(0);
+}

package/.claude/settings.local.json

@@ -15,7 +15,13 @@
       "Bash(node:*)",
       "Bash(npm version:*)",
       "Bash(git rm:*)",
-      "Bash(npm test)"
+      "Bash(npm test)",
+      "Bash(powershell -Command \"Get-ChildItem -Path ''.claude'' -Recurse -File | Where-Object { $_LastWriteTime.ToFileTimeUtc\\(\\) -gt 1768438268 } | Select-Object FullName, @{Name=''ModTime'';Expression={$_LastWriteTime.ToFileTimeUtc\\(\\)}}\")",
+      "Bash(powershell -Command:*)",
+      "Bash(git reset:*)",
+      "Bash(powershell Remove-Item -Recurse -Force \"test/.test-temp-user-edit-1768421956928\")",
+      "Bash(del \"C:\\\\CODE\\\\claude-code-autoconfig\\\\.claude\\\\hooks\\\\claude-md-guard.js\")",
+      "Bash(cmd /c del \"C:\\\\CODE\\\\claude-code-autoconfig\\\\test\\\\claude-md-guard.test.js\")"
     ]
   }
 }

package/CLAUDE.md

@@ -1,32 +1,39 @@
+<!-- AUTO-GENERATED BY /autoconfig at 2026-01-14 19:54:27 UTC — Do not edit. Use .claude/feedback/ for corrections. -->
+
 # claude-code-autoconfig
 
-CLI tool that auto-configures Claude Code for any project.
+CLI tool that auto-configures Claude Code for any project. One command analyzes your project, configures Claude, and shows you what it did.
 
-## Development Rules
+## Tech Stack
 
-### Testing Requirements
+- **Runtime:** Node.js (>=16.0.0)
+- **Type:** npm CLI package
+- **Entry:** `bin/cli.js`
 
-**CRITICAL: Before committing or outputting any changes to `bin/cli.js`, you MUST run tests and verify they pass:**
+## Commands
 
 ```bash
-npm test
+npm test          # Run all tests (box alignment + CLI install)
+npm run test:box  # Run box alignment tests only
+npm run test:install # Run CLI install tests only
 ```
 
-This runs `test/box-alignment.test.js` which validates:
-1. All box-drawing lines have consistent visual width (accounting for ANSI escape codes)
-2. Box structure is valid (correct corner and border characters)
+## Project Structure
 
-**DO NOT commit or present code changes if tests fail.** Fix the alignment issues first.
+- `bin/cli.js` — Main CLI entry point, handles bootstrap and /autoconfig launch
+- `.claude/commands/` — Slash command definitions (/autoconfig, /sync-claude-md, etc.)
+- `.claude/hooks/` — Hook scripts (format.js for JS/TS projects)
+- `.claude/feedback/` — Team feedback and corrections
+- `test/` — Test files
 
-### Box Drawing Guidelines
+## Publishing
 
-When modifying the "READY TO CONFIGURE" box in `bin/cli.js`:
+```bash
+npm version patch && npm publish
+```
 
-1. All lines must be exactly 46 visible characters wide (including the `║` borders)
-2. ANSI escape codes (`\x1b[...m`) don't count toward visible width
-3. Place color codes outside content spacing: `\x1b[33m║\x1b[0m` + 44 chars of content + `\x1b[33m║\x1b[0m`
-4. Always run `npm test` after any box modifications
+## Team Feedback
 
-## Commands
+See `.claude/feedback/` for corrections and guidance from the team.
 
-- `npm test` - Run box alignment tests
+<!-- END AUTO-GENERATED at 2026-01-14 19:54:27 UTC — Use .claude/feedback/ for corrections. -->

package/bin/cli.js

@@ -8,6 +8,19 @@ const { execSync, spawn } = require('child_process');
 const cwd = process.cwd();
 const packageDir = path.dirname(__dirname);
 
+// Cleanup any stray 'nul' file immediately on startup (Windows /dev/null artifact)
+function cleanupNulFile() {
+  const nulFile = path.join(cwd, 'nul');
+  if (fs.existsSync(nulFile)) {
+    try {
+      fs.unlinkSync(nulFile);
+    } catch (e) {
+      // Ignore - file might be locked
+    }
+  }
+}
+cleanupNulFile();
+
 // Reserved Windows device names - never create files with these names
 const WINDOWS_RESERVED = ['CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4',
   'COM5', 'COM6', 'COM7', 'COM8', 'COM9', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5',
@@ -190,11 +203,12 @@ cp .claude/migration/${timestamp}/settings.json .claude/settings.json
   }
 }
 
-// Step 3: Copy minimal bootstrap (commands/, docs/, agents/, feedback/)
+// Step 3: Copy minimal bootstrap (commands/, docs/, agents/, feedback/, hooks/)
 const commandsSrc = path.join(packageDir, '.claude', 'commands');
 const docsSrc = path.join(packageDir, '.claude', 'docs');
 const agentsSrc = path.join(packageDir, '.claude', 'agents');
 const feedbackSrc = path.join(packageDir, '.claude', 'feedback');
+const hooksSrc = path.join(packageDir, '.claude', 'hooks');
 
 function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
@@ -237,6 +251,18 @@ if (fs.existsSync(feedbackSrc)) {
   copyDir(feedbackSrc, path.join(claudeDest, 'feedback'));
 }
 
+// Copy hooks directory (scaffolding for custom hooks)
+if (fs.existsSync(hooksSrc)) {
+  copyDir(hooksSrc, path.join(claudeDest, 'hooks'));
+}
+
+// Copy settings.json (only if user doesn't have one - preserves existing config)
+const settingsSrc = path.join(packageDir, '.claude', 'settings.json');
+const settingsDest = path.join(claudeDest, 'settings.json');
+if (fs.existsSync(settingsSrc) && !fs.existsSync(settingsDest)) {
+  fs.copyFileSync(settingsSrc, settingsDest);
+}
+
 console.log('\x1b[32m%s\x1b[0m', '✅ Prepared /autoconfig command');
 
 // Step 4: Show "READY TO CONFIGURE" message
@@ -283,14 +309,6 @@ rl.question('\x1b[90mPress ENTER to continue...\x1b[0m', () => {
 
   // Cleanup when Claude exits
   claude.on('close', () => {
-    // Remove 'nul' file if accidentally created on Windows
-    const nulFile = path.join(cwd, 'nul');
-    if (fs.existsSync(nulFile)) {
-      try {
-        fs.unlinkSync(nulFile);
-      } catch (e) {
-        // Ignore errors - file might be locked or already gone
-      }
-    }
+    cleanupNulFile();
   });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-autoconfig",
-  "version": "1.0.74",
+  "version": "1.0.78",
   "description": "Intelligent, self-configuring setup for Claude Code. One command analyzes your project, configures Claude, and shows you what it did.",
   "author": "ADAC 1001 <info@adac1001.com>",
   "license": "MIT",
@@ -22,7 +22,9 @@
     "cli"
   ],
   "scripts": {
-    "test": "node test/box-alignment.test.js"
+    "test": "node test/box-alignment.test.js && node test/cli-install.test.js",
+    "test:box": "node test/box-alignment.test.js",
+    "test:install": "node test/cli-install.test.js"
   },
   "bin": {
     "claude-code-autoconfig": "./bin/cli.js"