@pennyfarthing/core 10.0.5 → 10.2.0

package/packages/core/dist/cli/commands/doctor.js

@@ -10,14 +10,15 @@ import { pathExists, isDirectory, isSymlink, fileMatchesHash } from '../utils/fi
 import { getPackageVersion } from '../utils/version.js';
 import { findNodeModulesPath } from '../utils/node-modules.js';
 import { ALL_SYMLINKS, CORE_AGENTS } from '../utils/constants.js';
+import { getPfVersion, installPfCli } from '../utils/python.js';
 export async function doctorCommand(options) {
     const projectRoot = process.cwd();
-    // Handle dogfooding mode - run the dogfood script instead
+    // Handle dogfood mode - run checks for framework/orchestrator development
     if (options.dogfood) {
         const dogfoodScript = join(projectRoot, 'pennyfarthing-dist/scripts/misc/doctor-dogfood.sh');
         if (!existsSync(dogfoodScript)) {
-            logger.error('Dogfood mode requires the pennyfarthing repo (pennyfarthing-dist/ not found)');
-            logger.info('This flag is for developers working on pennyfarthing itself.');
+            logger.error('Dogfood mode requires pennyfarthing-dist/ (framework repo or orchestrator with inlined pennyfarthing/)');
+            logger.info('This flag is for framework development and orchestrator repos.');
             process.exit(1);
         }
         const args = options.fix ? ['--fix'] : [];
@@ -41,16 +42,20 @@ export async function doctorCommand(options) {
     logger.info(`Version: ${installedVersion} (installed) / ${packageVersion} (package)`);
     logger.info(`Mode: ${installationType}${installationType === 'symlink' ? ' (node_modules)' : ' (file copies)'}`);
     logger.newline();
+    // Resolve node_modules path for checks that need it
+    const nodeModulesPath = findNodeModulesPath(projectRoot);
     // Run checks
     results.push(...checkInstallation(projectRoot, manifest));
     results.push(...checkCoreFiles(projectRoot, manifest));
     results.push(...checkUserFiles(projectRoot));
     results.push(...checkDirectories(projectRoot));
     results.push(...checkHooks(projectRoot));
+    results.push(...checkGitHooks(projectRoot, nodeModulesPath));
     results.push(...checkFileLayout(projectRoot));
     results.push(...checkLegacyFiles(projectRoot));
     results.push(checkLegacyStatuslinePath(projectRoot));
     results.push(...checkCyclist(projectRoot));
+    results.push(checkPfCli(nodeModulesPath));
     // Output results
     if (options.json) {
         console.log(JSON.stringify(results, null, 2));
@@ -63,9 +68,11 @@ export async function doctorCommand(options) {
         { name: 'User Files', filter: (r) => r.name.startsWith('project/') || r.name.startsWith('persona') || r.name.startsWith('settings') },
         { name: 'Directories', filter: (r) => r.name.startsWith('dir/') },
         { name: 'Hooks', filter: (r) => r.name.startsWith('hook/') },
+        { name: 'Git Hooks', filter: (r) => r.name.startsWith('git-hook/') },
         { name: 'File Layout', filter: (r) => r.name.startsWith('layout/') },
         { name: 'Legacy Files', filter: (r) => r.name.startsWith('legacy/') },
-        { name: 'Cyclist', filter: (r) => r.name.startsWith('cyclist/') }
+        { name: 'Cyclist', filter: (r) => r.name.startsWith('cyclist/') },
+        { name: 'Tools', filter: (r) => r.name.startsWith('tools/') }
     ];
     for (const category of categories) {
         const categoryResults = results.filter(category.filter);
@@ -314,6 +321,9 @@ function checkUserFiles(projectRoot) {
         // Check SessionStart hooks are configured (critical for PROJECT_ROOT)
         const hookCheck = checkSessionStartHooks(projectRoot, installationType);
         results.push(hookCheck);
+        // Check auto-load-sm hook is configured (auto-invokes /sm on new sessions)
+        const autoLoadSmCheck = checkAutoLoadSmHook(projectRoot);
+        results.push(autoLoadSmCheck);
         // Check Stop hook is configured (question reflector enforcement)
         const stopHookCheck = checkStopHook(projectRoot, installationType);
         results.push(stopHookCheck);
@@ -393,7 +403,8 @@ function addBenchmarkPermissions(projectRoot) {
             settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
         }
         catch {
-            // Start fresh if parse fails
+            logger.warning(`Cannot parse ${settingsPath} — fix JSON syntax and re-run doctor --fix`);
+            return;
         }
     }
     if (!settings.permissions) {
@@ -462,6 +473,133 @@ function checkSessionStartHooks(projectRoot, installationType) {
         };
     }
 }
+/**
+ * Check that auto-load-sm hook is configured in SessionStart
+ * This auto-invokes /sm agent on new session start
+ */
+function checkAutoLoadSmHook(projectRoot) {
+    const settingsPath = join(projectRoot, '.claude/settings.local.json');
+    try {
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        if (!settings.hooks?.SessionStart) {
+            return {
+                name: 'settings/auto-load-sm',
+                status: 'warn',
+                detail: 'Missing SessionStart hooks - auto-load-sm not configured',
+                fix: () => {
+                    addAutoLoadSmHook(projectRoot);
+                }
+            };
+        }
+        const hasAutoLoadSm = settings.hooks.SessionStart.some((entry) => {
+            if (typeof entry === 'object' && entry !== null) {
+                const hookEntry = entry;
+                return hookEntry.hooks?.some(h => h.command?.includes('auto-load-sm'));
+            }
+            return false;
+        });
+        if (!hasAutoLoadSm) {
+            return {
+                name: 'settings/auto-load-sm',
+                status: 'warn',
+                detail: 'auto-load-sm not configured - /sm will not auto-invoke on startup',
+                fix: () => {
+                    addAutoLoadSmHook(projectRoot);
+                }
+            };
+        }
+        // Also check that the hook script file exists
+        const hookScript = join(projectRoot, '.pennyfarthing/project/hooks/auto-load-sm.sh');
+        if (!pathExists(hookScript)) {
+            return {
+                name: 'settings/auto-load-sm',
+                status: 'warn',
+                detail: 'Hook registered but script missing at .pennyfarthing/project/hooks/auto-load-sm.sh',
+                fix: () => {
+                    ensureDirSync(dirname(hookScript));
+                    writeFileSync(hookScript, `#!/usr/bin/env bash
+# Auto-load /sm agent on new session start
+set -euo pipefail
+
+cat <<'HOOKEOF'
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "IMPORTANT: Auto-invoke the /sm agent immediately. Run the Skill tool with skill: \\"sm\\" as your first action. Do not greet the user or do anything else first."
+  }
+}
+HOOKEOF
+`, { mode: 0o755 });
+                }
+            };
+        }
+        return {
+            name: 'settings/auto-load-sm',
+            status: 'pass',
+            detail: undefined
+        };
+    }
+    catch {
+        return {
+            name: 'settings/auto-load-sm',
+            status: 'warn',
+            detail: 'Could not parse settings.local.json'
+        };
+    }
+}
+/**
+ * Fix function: Add auto-load-sm hook to SessionStart in settings.local.json
+ */
+function addAutoLoadSmHook(projectRoot) {
+    const settingsPath = join(projectRoot, '.claude/settings.local.json');
+    const requiredHook = {
+        matcher: 'startup',
+        hooks: [
+            {
+                type: 'command',
+                command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/project/hooks/auto-load-sm.sh'
+            }
+        ]
+    };
+    let settings = {};
+    if (pathExists(settingsPath)) {
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        }
+        catch {
+            // Start fresh if parse fails
+        }
+    }
+    if (!settings.hooks) {
+        settings.hooks = {};
+    }
+    const hooks = settings.hooks;
+    if (!hooks.SessionStart) {
+        hooks.SessionStart = [requiredHook];
+    }
+    else if (Array.isArray(hooks.SessionStart)) {
+        hooks.SessionStart = [...hooks.SessionStart, requiredHook];
+    }
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
+    // Also ensure the hook script exists
+    const hookScript = join(projectRoot, '.pennyfarthing/project/hooks/auto-load-sm.sh');
+    if (!pathExists(hookScript)) {
+        ensureDirSync(dirname(hookScript));
+        writeFileSync(hookScript, `#!/usr/bin/env bash
+# Auto-load /sm agent on new session start
+set -euo pipefail
+
+cat <<'HOOKEOF'
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "IMPORTANT: Auto-invoke the /sm agent immediately. Run the Skill tool with skill: \\"sm\\" as your first action. Do not greet the user or do anything else first."
+  }
+}
+HOOKEOF
+`, { mode: 0o755 });
+    }
+}
 /**
  * Check that Stop hook is properly configured in settings.local.json
  * This is needed for question reflector enforcement in Cyclist
@@ -585,7 +723,8 @@ function addContextCircuitBreaker(projectRoot, installationType) {
             settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
         }
         catch {
-            // Start fresh if parse fails
+            logger.warning(`Cannot parse ${settingsPath} — fix JSON syntax and re-run doctor --fix`);
+            return;
         }
     }
     if (!settings.hooks) {
@@ -673,7 +812,8 @@ function addSchemaValidationHook(projectRoot, installationType) {
             settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
         }
         catch {
-            // Start fresh if parse fails
+            logger.warning(`Cannot parse ${settingsPath} — fix JSON syntax and re-run doctor --fix`);
+            return;
         }
     }
     if (!settings.hooks) {
@@ -762,7 +902,8 @@ function addPostToolUseHook(projectRoot, installationType) {
             settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
         }
         catch {
-            // Start fresh if parse fails
+            logger.warning(`Cannot parse ${settingsPath} — fix JSON syntax and re-run doctor --fix`);
+            return;
         }
     }
     if (!settings.hooks) {
@@ -851,7 +992,8 @@ function addSprintYamlValidationHook(projectRoot, installationType) {
             settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
         }
         catch {
-            // Start fresh if parse fails
+            logger.warning(`Cannot parse ${settingsPath} — fix JSON syntax and re-run doctor --fix`);
+            return;
         }
     }
     if (!settings.hooks) {
@@ -888,7 +1030,8 @@ function addStopHook(projectRoot, installationType) {
             settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
         }
         catch {
-            // Start fresh if parse fails
+            logger.warning(`Cannot parse ${settingsPath} — fix JSON syntax and re-run doctor --fix`);
+            return;
         }
     }
     if (!settings.hooks) {
@@ -936,6 +1079,15 @@ function addSessionStartHooks(projectRoot, installationType) {
                     command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/project/hooks/setup-env.sh'
                 }
             ]
+        },
+        {
+            matcher: 'startup',
+            hooks: [
+                {
+                    type: 'command',
+                    command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/project/hooks/auto-load-sm.sh'
+                }
+            ]
         }
     ];
     let settings = {};
@@ -944,7 +1096,8 @@ function addSessionStartHooks(projectRoot, installationType) {
             settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
         }
         catch {
-            // Start fresh if parse fails
+            logger.warning(`Cannot parse ${settingsPath} — fix JSON syntax and re-run doctor --fix`);
+            return;
         }
     }
     if (!settings.hooks) {
@@ -1021,6 +1174,15 @@ function createSettingsLocalJson(projectRoot, installationType) {
                             command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/project/hooks/setup-env.sh'
                         }
                     ]
+                },
+                {
+                    matcher: 'startup',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/project/hooks/auto-load-sm.sh'
+                        }
+                    ]
                 }
             ],
             PostToolUse: [
@@ -1158,6 +1320,153 @@ function checkHooks(projectRoot) {
     }
     return results;
 }
+/**
+ * Check git hooks in .git/hooks/ are up-to-date with package source.
+ * Detects stale copies that were installed by `pennyfarthing init` but never refreshed.
+ * For framework/orchestrator repos (has pennyfarthing-dist/), checks that hooks are
+ * symlinked rather than copied, since symlinks stay current automatically.
+ * Provides --fix to refresh stale hooks or replace copies with symlinks.
+ */
+function checkGitHooks(projectRoot, nodeModulesPath) {
+    const results = [];
+    // Use git rev-parse to find the actual git dir (handles worktrees where .git is a file)
+    const gitDirResult = spawnSync('git', ['rev-parse', '--git-dir'], { cwd: projectRoot, encoding: 'utf8' });
+    const gitDir = gitDirResult.status === 0
+        ? (gitDirResult.stdout.trim().startsWith('/') ? gitDirResult.stdout.trim() : join(projectRoot, gitDirResult.stdout.trim()))
+        : join(projectRoot, '.git');
+    const gitHooksDir = join(gitDir, 'hooks');
+    if (!pathExists(gitHooksDir)) {
+        return results;
+    }
+    // Detect framework/orchestrator repo (has pennyfarthing-dist/ at project root)
+    const isFrameworkRepo = pathExists(join(projectRoot, 'pennyfarthing-dist'));
+    const frameworkHooksDir = isFrameworkRepo
+        ? join(projectRoot, 'pennyfarthing-dist/scripts/hooks')
+        : null;
+    // Need either node_modules or framework source to compare against
+    if (!nodeModulesPath && !frameworkHooksDir) {
+        return results;
+    }
+    const hooks = [
+        { source: 'pre-commit.sh', dest: 'pre-commit', marker: 'pennyfarthing' },
+        { source: 'pre-push.sh', dest: 'pre-push', marker: 'pennyfarthing' },
+        { source: 'post-merge.sh', dest: 'post-merge', marker: 'pennyfarthing' },
+    ];
+    for (const hook of hooks) {
+        // Prefer framework source (pennyfarthing-dist/) over node_modules
+        const sourcePath = frameworkHooksDir
+            ? join(frameworkHooksDir, hook.source)
+            : join(nodeModulesPath, 'scripts/hooks', hook.source);
+        const destPath = join(gitHooksDir, hook.dest);
+        if (!pathExists(sourcePath)) {
+            continue;
+        }
+        if (!pathExists(destPath)) {
+            results.push({
+                name: `git-hook/${hook.dest}`,
+                status: 'warn',
+                detail: 'Not installed',
+                fix: () => {
+                    if (isFrameworkRepo) {
+                        // Framework repos: create symlink (relative from hooks dir to source)
+                        const absSource = join(projectRoot, 'pennyfarthing-dist/scripts/hooks', hook.source);
+                        const relTarget = relative(gitHooksDir, absSource);
+                        symlinkSync(relTarget, destPath);
+                    }
+                    else {
+                        // End-user repos: copy content
+                        const content = readFileSync(sourcePath, 'utf8');
+                        writeFileSync(destPath, content, { mode: 0o755 });
+                    }
+                }
+            });
+            continue;
+        }
+        // Check if hook is a symlink (framework repos should use symlinks)
+        const hookIsSymlink = isSymlink(destPath);
+        if (isFrameworkRepo && !hookIsSymlink) {
+            // Framework repo has a copied hook instead of a symlink — it will go stale
+            results.push({
+                name: `git-hook/${hook.dest}`,
+                status: 'warn',
+                detail: 'Copy instead of symlink (will go stale)',
+                fix: () => {
+                    // Backup existing, replace with symlink
+                    const absSource = join(projectRoot, 'pennyfarthing-dist/scripts/hooks', hook.source);
+                    const relTarget = relative(gitHooksDir, absSource);
+                    renameSync(destPath, `${destPath}.backup`);
+                    symlinkSync(relTarget, destPath);
+                }
+            });
+            continue;
+        }
+        if (hookIsSymlink) {
+            // Symlinked hook — verify target exists
+            try {
+                const target = readlinkSync(destPath);
+                const resolvedTarget = join(gitHooksDir, target);
+                if (pathExists(resolvedTarget)) {
+                    results.push({
+                        name: `git-hook/${hook.dest}`,
+                        status: 'pass',
+                        detail: 'Symlinked'
+                    });
+                }
+                else {
+                    results.push({
+                        name: `git-hook/${hook.dest}`,
+                        status: 'warn',
+                        detail: `Broken symlink → ${target}`,
+                        fix: () => {
+                            unlinkSync(destPath);
+                            const absSource = join(projectRoot, 'pennyfarthing-dist/scripts/hooks', hook.source);
+                            const relTarget = relative(gitHooksDir, absSource);
+                            symlinkSync(relTarget, destPath);
+                        }
+                    });
+                }
+            }
+            catch {
+                results.push({
+                    name: `git-hook/${hook.dest}`,
+                    status: 'warn',
+                    detail: 'Cannot read symlink'
+                });
+            }
+            continue;
+        }
+        // Copied hook — check content freshness
+        const existingContent = readFileSync(destPath, 'utf8');
+        // Only check hooks that are ours (contain the marker)
+        if (!existingContent.includes(hook.marker)) {
+            results.push({
+                name: `git-hook/${hook.dest}`,
+                status: 'pass',
+                detail: 'Custom (non-pennyfarthing)'
+            });
+            continue;
+        }
+        const sourceContent = readFileSync(sourcePath, 'utf8');
+        if (existingContent === sourceContent) {
+            results.push({
+                name: `git-hook/${hook.dest}`,
+                status: 'pass',
+                detail: undefined
+            });
+        }
+        else {
+            results.push({
+                name: `git-hook/${hook.dest}`,
+                status: 'warn',
+                detail: 'Stale — content differs from package',
+                fix: () => {
+                    writeFileSync(destPath, sourceContent, { mode: 0o755 });
+                }
+            });
+        }
+    }
+    return results;
+}
 /**
  * Check Cyclist installation health (if installed as a workspace package)
  * Detects node-pty spawn-helper permission issues that cause posix_spawnp failures
@@ -1260,6 +1569,30 @@ function checkCyclist(projectRoot) {
     }
     return results;
 }
+/**
+ * Check if the pf CLI is installed and working.
+ * The pf CLI is required for agent commands (e.g., `pf agent start "dev"`).
+ */
+function checkPfCli(nodeModulesPath) {
+    const version = getPfVersion();
+    if (version) {
+        return {
+            name: 'tools/pf-cli',
+            status: 'pass',
+            detail: version
+        };
+    }
+    return {
+        name: 'tools/pf-cli',
+        status: 'warn',
+        detail: 'pf CLI not found — agent commands will not work',
+        fix: () => {
+            if (!installPfCli(nodeModulesPath)) {
+                throw new Error('Neither uv nor pipx available. Install manually: uv tool install pennyfarthing-scripts');
+            }
+        }
+    };
+}
 /**
  * Known legacy statusline paths from various Pennyfarthing versions.
  * These should be detected and cleaned up when proper statusline exists.
@@ -1337,11 +1670,11 @@ export function checkLegacyFiles(projectRoot) {
                             writeFileSync(properThemeConfig, YAML.stringify(config), 'utf8');
                         }
                     }
+                    unlinkSync(legacyPersonaConfig);
                 }
                 catch {
-                    // If we can't read/parse legacy, just remove it
+                    logger.warning(`Cannot parse ${legacyPersonaConfig} — fix YAML syntax and re-run doctor --fix`);
                 }
-                unlinkSync(legacyPersonaConfig);
             }
         });
     }