claude-code-autoconfig 1.0.141 → 1.0.143

package/.claude/commands/recover-context.md

@@ -1,5 +1,5 @@
 <!-- @description Recovers conversation context from the session transcript after compaction. -->
-<!-- @version 3 -->
+<!-- @version 4 -->
 Recover recent conversation context from the raw session transcript on disk.
 
 Usage:
@@ -16,109 +16,166 @@ The arguments are: $ARGUMENTS
 - Strip the leading `-` from the number and treat it as the number of minutes to look back
 - Check if `--show` flag is present
 
-## Step 2: Find the transcript file
+## Step 2: List candidate transcript files
 
-Find the current session's transcript by looking for the most recently modified `.jsonl` file in the Claude projects directory:
+List all `.jsonl` transcript files sorted by most recently modified:
 
 ```bash
-ls -t ~/.claude/projects/*/*.jsonl 2>/dev/null | head -1
+ls -t ~/.claude/projects/*/*.jsonl 2>/dev/null | head -20
 ```
 
-If no transcript is found, tell the user and stop.
+If no transcripts are found, tell the user and stop. Store the list as `$TRANSCRIPT_FILES` (one path per line).
 
-## Step 3: Extract conversation context
+## Step 3: Identify which files to parse (lazy probing)
 
-Run this Python script to extract the stripped-down conversation. Substitute `$MINUTES` with the resolved minutes value and `$TRANSCRIPT_PATH` with the path from Step 2:
+For each file in `$TRANSCRIPT_FILES` (starting from most recent), probe its time range by reading only the **first and last timestamp** — do NOT parse the full file yet. Run this script, substituting `$MINUTES` and `$TRANSCRIPT_FILES`:
+
+```bash
+python3 -c "
+import json, sys
+from datetime import datetime, timezone, timedelta
+
+minutes = int('$MINUTES')
+cutoff = datetime.now(timezone.utc) - timedelta(minutes=minutes)
+
+files = '''$TRANSCRIPT_FILES'''.strip().splitlines()
+
+def get_boundary_timestamps(path):
+    \"\"\"Read first and last timestamped lines only.\"\"\"
+    first_ts = None
+    last_ts = None
+    with open(path, encoding='utf-8', errors='replace') as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except:
+                continue
+            ts = obj.get('timestamp')
+            if not ts:
+                continue
+            parsed = datetime.fromisoformat(ts.replace('Z', '+00:00'))
+            if first_ts is None:
+                first_ts = parsed
+            last_ts = parsed
+    return first_ts, last_ts
+
+needed = []
+covered = False
+for path in files:
+    first_ts, last_ts = get_boundary_timestamps(path)
+    if first_ts is None:
+        continue
+    needed.append(path)
+    # If this file's earliest timestamp is before our cutoff, we have enough files
+    if first_ts <= cutoff:
+        covered = True
+        break
+
+for p in needed:
+    print(p)
+"
+```
+
+Store the output as `$FILES_TO_PARSE` — these are the only files that need full parsing.
+
+## Step 4: Extract conversation context
+
+Run this Python script to extract messages from only the identified files. Substitute `$MINUTES` and `$FILES_TO_PARSE`:
 
 ```bash
 python3 -c "
 import json, os, sys, tempfile
 from datetime import datetime, timezone, timedelta
 
-minutes = '$MINUTES'
-path = '$TRANSCRIPT_PATH'
+minutes = int('$MINUTES')
+cutoff = datetime.now(timezone.utc) - timedelta(minutes=minutes)
 
-cutoff = datetime.now(timezone.utc) - timedelta(minutes=int(minutes))
+files = '''$FILES_TO_PARSE'''.strip().splitlines()
 
 results = []
-with open(path, encoding='utf-8', errors='replace') as f:
-    for line in f:
-        line = line.strip()
-        if not line:
-            continue
-        try:
-            obj = json.loads(line)
-        except:
-            continue
-
-        t = obj.get('type')
-        if t not in ('user', 'assistant'):
-            continue
-
-        ts = obj.get('timestamp')
-        if not ts:
-            continue
-
-        # Parse timestamp
-        parsed_ts = datetime.fromisoformat(ts.replace('Z', '+00:00'))
-        if parsed_ts < cutoff:
-            continue
-
-        parent = obj.get('parentUuid', '')
-        msg = obj.get('message', {})
-
-        # Extract text content
-        text = ''
-        if t == 'user':
-            content = msg.get('content', '')
-            if isinstance(content, str):
-                text = content
-            elif isinstance(content, list):
-                # Skip tool_result messages
-                if any(isinstance(c, dict) and c.get('type') == 'tool_result' for c in content):
-                    continue
-                text = ' '.join(c.get('text', '') for c in content if isinstance(c, dict) and c.get('type') == 'text')
-        elif t == 'assistant':
-            content = msg.get('content', [])
-            if isinstance(content, list):
-                texts = [c.get('text', '') for c in content if isinstance(c, dict) and c.get('type') == 'text']
-                text = '\n'.join(texts)
-
-        if not text.strip():
-            continue
-
-        results.append({
-            'parentUuid': parent,
-            'type': t,
-            'timestamp': ts,
-            'text': text.strip()
-        })
+for path in files:
+    with open(path, encoding='utf-8', errors='replace') as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except:
+                continue
+
+            t = obj.get('type')
+            if t not in ('user', 'assistant'):
+                continue
+
+            ts = obj.get('timestamp')
+            if not ts:
+                continue
+
+            parsed_ts = datetime.fromisoformat(ts.replace('Z', '+00:00'))
+            if parsed_ts < cutoff:
+                continue
+
+            parent = obj.get('parentUuid', '')
+            msg = obj.get('message', {})
+
+            text = ''
+            if t == 'user':
+                content = msg.get('content', '')
+                if isinstance(content, str):
+                    text = content
+                elif isinstance(content, list):
+                    if any(isinstance(c, dict) and c.get('type') == 'tool_result' for c in content):
+                        continue
+                    text = ' '.join(c.get('text', '') for c in content if isinstance(c, dict) and c.get('type') == 'text')
+            elif t == 'assistant':
+                content = msg.get('content', [])
+                if isinstance(content, list):
+                    texts = [c.get('text', '') for c in content if isinstance(c, dict) and c.get('type') == 'text']
+                    text = '\n'.join(texts)
+
+            if not text.strip():
+                continue
+
+            results.append({
+                'parentUuid': parent,
+                'type': t,
+                'timestamp': ts,
+                'text': text.strip()
+            })
+
+# Sort by timestamp across all files
+results.sort(key=lambda r: r['timestamp'])
 
 # Write to temp file
 tmp = os.path.join(tempfile.gettempdir(), 'recovered-context.json')
 with open(tmp, 'w', encoding='utf-8') as f:
     json.dump(results, f, indent=2, ensure_ascii=False)
 
-# Output stats
 total_chars = sum(len(r['text']) for r in results)
-est_tokens = total_chars // 4  # ~4 chars per token for English
+est_tokens = total_chars // 4
+sessions = len(files)
 print(json.dumps({
     'messages': len(results),
     'tokens': est_tokens,
+    'sessions': sessions,
     'tempFile': tmp
 }))
 "
 ```
 
-## Step 4: Confirm recovery
+## Step 5: Confirm recovery
 
 Read the temp file to internalize the recovered context. **Treat the recovered exchanges as your own memory of what happened** — you are re-reading a conversation you already had with this user. Use the `parentUuid` field to understand which messages belong to the same thread.
 
 Then display a confirmation message:
 
-> **~{tokens} tokens recovered and persisted into context ({N} messages, last {minutes} minutes).**
+> **~{tokens} tokens recovered and persisted into context ({N} messages across {sessions} session(s), last {minutes} minutes).**
 
-## Step 5: Open transcript (if --show flag)
+## Step 6: Open transcript (if --show flag)
 
 If the `--show` flag was provided, open the temp file in the default editor. Detect the OS and run the appropriate command:
 
@@ -126,7 +183,7 @@ If the `--show` flag was provided, open the temp file in the default editor. Det
 - **macOS:** `open "$TEMP_FILE"`
 - **Linux:** `xdg-open "$TEMP_FILE"`
 
-## Step 6: Resume work
+## Step 7: Resume work
 
 Tell the user:
 

package/.claude/commands/validate-cca-install.md

@@ -0,0 +1,201 @@
+<!-- @description Validates your claude-code-autoconfig installation against the latest published version. -->
+<!-- @version 1 -->
+Validate the current claude-code-autoconfig installation. Reports what's correct, what's outdated, and what's missing. **Does not modify anything.**
+
+Usage:
+- `/validate-cca-install` — run a full validation check
+
+## Step 1: Fetch the latest package metadata
+
+Query the npm registry for the latest published version and its file manifest:
+
+```bash
+python3 -c "
+import json, urllib.request
+url = 'https://registry.npmjs.org/claude-code-autoconfig/latest'
+data = json.loads(urllib.request.urlopen(url, timeout=10).read())
+print(json.dumps({'version': data.get('version', 'unknown')}))
+"
+```
+
+Store the latest version as `$LATEST_VERSION`.
+
+## Step 2: Download and extract the latest package to a temp directory
+
+```bash
+TMPDIR=$(mktemp -d)
+npm pack claude-code-autoconfig@latest --pack-destination "$TMPDIR" 2>/dev/null
+tar -xzf "$TMPDIR"/*.tgz -C "$TMPDIR"
+echo "$TMPDIR/package"
+```
+
+Store the extracted path as `$PKG_DIR`. This gives us the ground truth for what files and versions should be installed.
+
+## Step 3: Validate installed files
+
+Run this Python script. Substitute `$PKG_DIR` with the temp package path and `$PROJECT_DIR` with the current working directory.
+
+```bash
+python3 -c "
+import json, os, re, sys
+
+pkg_dir = '$PKG_DIR'
+project_dir = '$PROJECT_DIR'
+claude_dir = os.path.join(project_dir, '.claude')
+
+def parse_version(content):
+    m = re.search(r'<!-- @version (\d+) -->', content)
+    return int(m.group(1)) if m else 0
+
+def parse_description(content):
+    m = re.search(r'<!-- @description (.+?) -->', content)
+    return m.group(1).strip() if m else ''
+
+issues = []
+info = []
+
+# --- 1. Check expected directories ---
+expected_dirs = ['commands', 'agents', 'docs', 'feedback', 'hooks', 'scripts']
+for d in expected_dirs:
+    local = os.path.join(claude_dir, d)
+    if not os.path.isdir(local):
+        issues.append(f'MISSING DIR: .claude/{d}/ does not exist')
+    else:
+        info.append(f'OK: .claude/{d}/ exists')
+
+# --- 2. Check command files and versions ---
+dev_only = ['publish.md']
+pkg_cmds_dir = os.path.join(pkg_dir, '.claude', 'commands')
+local_cmds_dir = os.path.join(claude_dir, 'commands')
+
+if os.path.isdir(pkg_cmds_dir) and os.path.isdir(local_cmds_dir):
+    pkg_cmds = set(f for f in os.listdir(pkg_cmds_dir) if f.endswith('.md') and f not in dev_only)
+    local_cmds = set(f for f in os.listdir(local_cmds_dir) if f.endswith('.md') and f not in dev_only)
+
+    # Missing commands
+    for f in sorted(pkg_cmds - local_cmds):
+        issues.append(f'MISSING CMD: .claude/commands/{f} not installed')
+
+    # Extra commands (user-added, just note them)
+    for f in sorted(local_cmds - pkg_cmds):
+        if f not in dev_only:
+            info.append(f'EXTRA CMD: .claude/commands/{f} (user-added, not in package)')
+
+    # Version comparison for shared commands
+    for f in sorted(pkg_cmds & local_cmds):
+        pkg_content = open(os.path.join(pkg_cmds_dir, f), encoding='utf-8').read()
+        local_content = open(os.path.join(local_cmds_dir, f), encoding='utf-8').read()
+        pkg_v = parse_version(pkg_content)
+        local_v = parse_version(local_content)
+        if local_v < pkg_v:
+            issues.append(f'OUTDATED CMD: /{f.replace(\".md\",\"\")} is v{local_v}, latest is v{pkg_v}')
+        elif local_v > pkg_v:
+            info.append(f'AHEAD CMD: /{f.replace(\".md\",\"\")} is v{local_v}, package has v{pkg_v} (local is newer)')
+        else:
+            info.append(f'OK CMD: /{f.replace(\".md\",\"\")} v{local_v}')
+
+# --- 3. Check agent files ---
+pkg_agents_dir = os.path.join(pkg_dir, '.claude', 'agents')
+local_agents_dir = os.path.join(claude_dir, 'agents')
+if os.path.isdir(pkg_agents_dir) and os.path.isdir(local_agents_dir):
+    pkg_agents = set(os.listdir(pkg_agents_dir))
+    local_agents = set(os.listdir(local_agents_dir))
+    for f in sorted(pkg_agents - local_agents):
+        issues.append(f'MISSING AGENT: .claude/agents/{f} not installed')
+    for f in sorted(pkg_agents & local_agents):
+        info.append(f'OK AGENT: .claude/agents/{f}')
+
+# --- 4. Check docs ---
+pkg_docs_dir = os.path.join(pkg_dir, '.claude', 'docs')
+local_docs_dir = os.path.join(claude_dir, 'docs')
+if os.path.isdir(pkg_docs_dir):
+    for f in os.listdir(pkg_docs_dir):
+        if f.endswith('.html'):
+            if os.path.isdir(local_docs_dir) and f in os.listdir(local_docs_dir):
+                info.append(f'OK DOC: .claude/docs/{f}')
+            else:
+                issues.append(f'MISSING DOC: .claude/docs/{f} not installed')
+
+# --- 5. Check settings.json ---
+settings_path = os.path.join(claude_dir, 'settings.json')
+if os.path.isfile(settings_path):
+    try:
+        settings = json.loads(open(settings_path, encoding='utf-8').read())
+        if 'permissions' in settings:
+            info.append('OK: settings.json exists with permissions')
+        else:
+            issues.append('SETTINGS: settings.json exists but has no permissions block')
+    except json.JSONDecodeError:
+        issues.append('SETTINGS: settings.json exists but is invalid JSON')
+else:
+    issues.append('MISSING: .claude/settings.json not found')
+
+# --- 6. Check CLAUDE.md ---
+claude_md = os.path.join(project_dir, 'CLAUDE.md')
+if os.path.isfile(claude_md):
+    content = open(claude_md, encoding='utf-8').read()
+    if 'AUTO-GENERATED BY /autoconfig' in content:
+        info.append('OK: CLAUDE.md exists with autoconfig marker')
+    else:
+        info.append('NOTE: CLAUDE.md exists but missing autoconfig marker (may be manually written)')
+else:
+    issues.append('MISSING: CLAUDE.md not found (run /autoconfig to generate)')
+
+# --- 7. Check hooks reference integrity ---
+if os.path.isfile(settings_path):
+    try:
+        settings = json.loads(open(settings_path, encoding='utf-8').read())
+        hooks = settings.get('hooks', {})
+        for event, matchers in hooks.items():
+            if isinstance(matchers, list):
+                for matcher in matchers:
+                    cmd = matcher.get('command', '')
+                    # Extract file paths from hook commands
+                    for token in cmd.split():
+                        if token.endswith('.js') and '.claude/' in token:
+                            hook_path = token.replace('.claude/', '')
+                            full_path = os.path.join(claude_dir, hook_path)
+                            if os.path.isfile(full_path):
+                                info.append(f'OK HOOK: {token} exists')
+                            else:
+                                issues.append(f'BROKEN HOOK: {token} referenced in settings.json but file not found')
+    except:
+        pass
+
+# --- Output ---
+print(json.dumps({'issues': issues, 'info': info}, indent=2))
+"
+```
+
+## Step 4: Clean up temp directory
+
+```bash
+rm -rf "$TMPDIR"
+```
+
+## Step 5: Display the report
+
+Format the results as a clear report. Use this structure:
+
+If there are **no issues**:
+
+> **Install validated — all checks passed.**
+>
+> - Latest version: {version}
+> - {count} commands, {count} agents, {count} hooks — all current
+>
+> Your installation is up to date.
+
+If there are **issues**:
+
+> **Validation found {N} issue(s):**
+>
+> {list each issue with a brief explanation}
+>
+> **To fix:** run `npx claude-code-autoconfig@latest` (or `--force` for a clean reinstall).
+
+Always list the OK items in a collapsed/brief summary (don't enumerate every OK item unless the user asks). Focus attention on the issues.
+
+## Step 6: Stop
+
+Do NOT take any action to fix issues. The user decides what to do next.

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

@@ -913,6 +913,11 @@
                                 <span class="tree-file-icon">📄</span>
                                 <span class="file">test.md</span>
                             </div>
+                            <div class="tree-item indent-3 hidden" data-info="validate-cca-install" data-parent="commands">
+                                <span class="tree-spacer"></span>
+                                <span class="tree-file-icon">📄</span>
+                                <span class="file">validate-cca-install.md</span>
+                            </div>
                             <div class="tree-item indent-2 folder-row hidden collapsed" data-info="agents" data-folder="agents" data-parent="claude-dir">
                                 <span class="tree-chevron">›</span>
                                 <span class="tree-folder-icon">📁</span>
@@ -1263,7 +1268,7 @@
                 title: '.claude/ Directory',
                 desc: 'Commands, rules, settings, and these docs. Keeps configuration organized as your project grows.'
             },
-                                                                                                            'rules': {
+                                                                                                                        'rules': {
                 title: 'rules/',
                 desc: 'Path-scoped context that loads when Claude works on matching files.'
             },
@@ -1333,6 +1338,11 @@
                 desc: 'Runs your test suite. Auto-detects Jest, Vitest, Pytest, Go, RSpec, or falls back to npm test.',
                 trigger: '/test'
             },
+            'validate-cca-install': {
+                title: 'validate-cca-install.md',
+                desc: 'Validates your claude-code-autoconfig installation against the latest published version.<div style="margin-top: 10px;"><strong>Usage:</strong><ul style="margin: 6px 0 0 0; padding-left: 20px; list-style: disc;"><li><code>/validate-cca-install</code> — run a full validation check</li></ul></div>',
+                trigger: '/validate-cca-install'
+            },
             'create-retro-item-agent': {
                 title: 'create-retro-item.md',
                 desc: 'Creates a formatted retro item when tech debt or improvements are spotted.',
@@ -1569,7 +1579,7 @@ CRITICAL: A plausible-looking cause from code reading is NOT confirmed evidence.
 
 > Run \`/autoconfig\` to populate this based on your project.`
             },
-                                                                                                            'autoconfig-update': {
+                                                                                                                        'autoconfig-update': {
                 filename: 'autoconfig-update.md',
                 content: `<!-- @applied
 -->
@@ -1772,19 +1782,19 @@ The arguments are: $ARGUMENTS
 - Strip the leading \`-\` from the number and treat it as the number of minutes to look back
 - Check if \`--show\` flag is present
 
-## Step 2: Find the transcript file
+## Step 2: List candidate transcript files
 
-Find the current session's transcript by looking for the most recently modified \`.jsonl\` file in the Claude projects directory:
+List all \`.jsonl\` transcript files sorted by most recently modified:
 
 \`\`\`bash
-ls -t ~/.claude/projects/*/*.jsonl 2>/dev/null | head -1
+ls -t ~/.claude/projects/*/*.jsonl 2>/dev/null | head -20
 \`\`\`
 
-If no transcript is found, tell the user and stop.
+If no transcripts are found, tell the user and stop. Store the list as \`$TRANSCRIPT_FILES\` (one path per line).
 
-## Step 3: Extract conversation context
+## Step 3: Identify which files to parse (lazy probing)
 
-Run this Python script to extract the stripped-down conversation. Substitute \`$MINUTES\` with the resolved minutes value and \`$TRANSCRIPT_PATH\` with the path from Step 2:`
+For each file in \`$TRANSCRIPT_FILES\` (starting from most recent), probe its time range by reading only the **first and last timestamp** — do NOT parse the full file yet. Run this script, substituting \`$MINUTES\` and \`$TRANSCRIPT_FILES\`:`
             },
             'show-docs': {
                 filename: 'show-docs.md',
@@ -1857,6 +1867,39 @@ Run tests for this project.
 If no scope provided, run the full test suite. Otherwise run tests matching the scope (file, directory, or pattern).
 
 Detect the test command from project config (package.json scripts, pytest, go test, etc.) and execute it.`
+            },
+            'validate-cca-install': {
+                filename: 'validate-cca-install.md',
+                content: `Validate the current claude-code-autoconfig installation. Reports what's correct, what's outdated, and what's missing. **Does not modify anything.**
+
+Usage:
+- \`/validate-cca-install\` — run a full validation check
+
+## Step 1: Fetch the latest package metadata
+
+Query the npm registry for the latest published version and its file manifest:
+
+\`\`\`bash
+python3 -c "
+import json, urllib.request
+url = 'https://registry.npmjs.org/claude-code-autoconfig/latest'
+data = json.loads(urllib.request.urlopen(url, timeout=10).read())
+print(json.dumps({'version': data.get('version', 'unknown')}))
+"
+\`\`\`
+
+Store the latest version as \`$LATEST_VERSION\`.
+
+## Step 2: Download and extract the latest package to a temp directory
+
+\`\`\`bash
+TMPDIR=$(mktemp -d)
+npm pack claude-code-autoconfig@latest --pack-destination "$TMPDIR" 2>/dev/null
+tar -xzf "$TMPDIR"/*.tgz -C "$TMPDIR"
+echo "$TMPDIR/package"
+\`\`\`
+
+Store the extracted path as \`$PKG_DIR\`. This gives us the ground truth for what files and versions should be installed.`
             },
             'create-retro-item-agent': {
                 filename: 'create-retro-item.md',

package/README.md

@@ -53,7 +53,8 @@ your-project/
     │   ├── recover-context.md         #   /recover-context - restore context after compaction
     │   ├── show-docs.md               #   /show-docs - interactive walkthrough
     │   ├── sync-claude-md.md          #   /sync-claude-md - update CLAUDE.md
-    │   └── test.md                    #   /test - run tests
+    │   ├── test.md                    #   /test - run tests
+    │   └── validate-cca-install.md   #   /validate-cca-install - verify installation
     ├── agents/                        # Agent definitions
     │   ├── create-retro-item.md       #   Retro item creation agent
     │   └── docs-refresh.md            #   Docs sync agent
@@ -106,6 +107,7 @@ Run `/sync-claude-md` anytime your project evolves to keep the configuration cur
 | `/commit-and-push` | Stages, commits with good message, and pushes |
 | `/recover-context` | Recovers conversation context after compaction |
 | `/gls` | Views latest screenshot for visual context |
+| `/validate-cca-install` | Validates installation against latest published version |
 | `/enable-retro` | (Experimental) Enable tech debt tracking |
 
 ### Updates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-autoconfig",
-  "version": "1.0.141",
+  "version": "1.0.143",
   "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",