@rpamis/comet 0.3.9 → 0.4.0-beta.10

package/dist/app/commands/doctor.js

@@ -0,0 +1,1115 @@
+import path from 'path';
+import os from 'os';
+import { promises as fs } from 'fs';
+import { copyFile, fileExists, readDir } from '../../platform/fs/file-system.js';
+import { sameFileObject } from '../../platform/fs/file-identity.js';
+import { getOpenSpecVersion, isCommandAvailable, isOpenSpecVersionCompatible, MINIMUM_OPENSPEC_VERSION, } from '../../domains/integrations/openspec.js';
+import { inspectCodegraphIndex, repairCodegraphIndex, resolveCodegraphCommand, } from '../../domains/integrations/codegraph.js';
+import { copyCometRulesForPlatform, readManifest, getAssetsDir, getManagedSkillPaths, getManagedSkillPathsForSelection, installCometHooksForPlatform, } from '../../domains/skill/platform-install.js';
+import { getPlatformRuleDestinations, getLegacyPlatformRuleDestinations, inspectCometHooksForPlatform, } from '../../domains/skill/platform-inspect.js';
+import { PLATFORMS, getPlatformSkillsDir, getPlatformSkillsDirs, } from '../../platform/install/platforms.js';
+import { resolveCanonicalSkillRootOwners } from '../../platform/install/skill-root-owner.js';
+import { inspectClassicChangeReadOnly } from '../../domains/comet-classic/classic-diagnostics.js';
+import { inspectClassicLayout, resolveClassicLayout, } from '../../domains/comet-classic/classic-layout.js';
+import { assertClassicOpenSpecRootHealthy } from '../../domains/comet-classic/classic-openspec-root.js';
+import { inspectClassicRootMove, repairClassicRootMove, } from '../../domains/comet-classic/classic-root-move.js';
+import { inspectClassicLayoutInitialization, repairClassicLayoutInitialization, } from '../../domains/comet-classic/classic-layout-initialization.js';
+import { getCurrentVersion } from '../../platform/version/version.js';
+import { repairCometCurrentSelection } from '../../domains/comet-entry/current-selection-repair.js';
+import { readWorkflowProjectConfig } from '../../domains/workflow-contract/project-config-reader.js';
+import { inspectProtectedProjectPath } from '../../domains/workflow-contract/protected-project-path.js';
+import { inspectWorkflowProjectConfigTransaction, repairWorkflowProjectConfigTransaction, } from '../../domains/workflow-contract/project-config-transaction.js';
+import { resolveHookWorkflowOwner } from '../../domains/comet-entry/hook-router.js';
+import { inspectGitWorktree } from '../../platform/paths/git-worktree.js';
+const SUPERPOWERS_SENTINELS = [
+    'using-superpowers/SKILL.md',
+    'test-driven-development/SKILL.md',
+    'writing-plans/SKILL.md',
+];
+const HOOK_ROUTER_RUNTIME = 'comet/scripts/comet-hook-router.mjs';
+const CLASSIC_PLATFORM_TOOL_SCAN_MAX_ENTRIES = 4096;
+const CLASSIC_PLATFORM_TOOL_SCAN_MAX_DEPTH = 8;
+const CLASSIC_PLATFORM_TOOL_SCAN_MAX_FINDINGS = 128;
+const CLASSIC_PLATFORM_TOOL_ROOTS = [
+    ...new Set([
+        ...PLATFORMS.flatMap((platform) => getPlatformSkillsDirs(platform, 'project')),
+        // OpenSpec commands for these platforms live outside their Skill roots.
+        '.agent',
+        '.clinerules',
+    ]),
+].sort();
+const OPEN_SPEC_COMMAND_CONTAINER_NAMES = new Set(['command', 'commands', 'prompts', 'workflows']);
+function configuredWorkflows(config) {
+    return config?.workflows ?? (config ? [config.default_workflow] : ['classic']);
+}
+function configuredSkillLanguage(config, workflows) {
+    if (!config)
+        return 'en';
+    const ordered = [
+        config.default_workflow,
+        ...workflows.filter((workflow) => workflow !== config.default_workflow),
+    ];
+    for (const workflow of ordered) {
+        if (!workflows.includes(workflow))
+            continue;
+        const language = workflow === 'native' ? config.native?.language : config.classic?.language;
+        if (language)
+            return language === 'zh-CN' ? 'zh' : 'en';
+    }
+    return 'en';
+}
+function hookRouterRuntimePaths(baseDir, platform, scope) {
+    return {
+        source: path.join(getAssetsDir(), 'skills', ...HOOK_ROUTER_RUNTIME.split('/')),
+        destination: path.join(baseDir, getPlatformSkillsDir(platform, scope), 'skills', ...HOOK_ROUTER_RUNTIME.split('/')),
+    };
+}
+function checkCometCli() {
+    return {
+        check: 'Comet CLI',
+        status: 'pass',
+        message: `installed (${getCurrentVersion()})`,
+    };
+}
+async function checkOpenSpecCli() {
+    if (!isCommandAvailable('openspec')) {
+        return {
+            check: 'openspec CLI',
+            status: 'warn',
+            message: 'not installed — install with: npm install -g @fission-ai/openspec@latest',
+        };
+    }
+    const version = getOpenSpecVersion();
+    if (!version || !isOpenSpecVersionCompatible(version)) {
+        return {
+            check: 'openspec CLI',
+            status: 'warn',
+            message: `installed (${version || 'version unknown'}), but Comet requires >= ${MINIMUM_OPENSPEC_VERSION} — run: npm install -g @fission-ai/openspec@latest`,
+        };
+    }
+    return { check: 'openspec CLI', status: 'pass', message: `installed (${version})` };
+}
+function checkEnvironment(projectPath, context) {
+    return {
+        check: 'Environment',
+        status: 'pass',
+        message: `node ${process.version}; platform ${process.platform}/${process.arch}; project ${projectPath}; global ${context.homeDir}`,
+    };
+}
+function checkScopeMode(projectPath, scope, context) {
+    if (scope !== 'auto')
+        return null;
+    const includesGlobal = path.resolve(projectPath) !== path.resolve(context.homeDir);
+    return {
+        check: 'Scope',
+        status: 'pass',
+        message: includesGlobal
+            ? 'auto checks project scope first, then global scope when it is different'
+            : 'auto checks project scope only because project path is the global home directory',
+    };
+}
+async function checkWorkingDirs(projectPath) {
+    let layout;
+    try {
+        layout = await resolveClassicLayout(projectPath);
+    }
+    catch (error) {
+        return {
+            check: 'working directories',
+            status: 'fail',
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const expected = [
+        layout.changesDir,
+        layout.archiveDir,
+        layout.specsDir,
+        layout.superpowersSpecsDir,
+        layout.superpowersPlansDir,
+        layout.superpowersReportsDir,
+    ];
+    let presence;
+    try {
+        const inspections = await Promise.all(expected.map((directory) => inspectProtectedProjectPath(projectPath, path.relative(projectPath, directory).replaceAll('\\', '/'), {
+            label: `Classic working directory ${path
+                .relative(projectPath, directory)
+                .replaceAll('\\', '/')}`,
+            expected: 'directory',
+        })));
+        presence = inspections.map((inspection) => inspection.exists);
+    }
+    catch (error) {
+        return {
+            check: 'working directories',
+            status: 'fail',
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const missing = expected
+        .filter((_, index) => !presence[index])
+        .map((directory) => path.relative(projectPath, directory).replaceAll('\\', '/'));
+    if (missing.length === 0) {
+        return {
+            check: 'working directories',
+            status: 'pass',
+            message: `present (${layout.artifactLayout})`,
+        };
+    }
+    if (missing.length === expected.length) {
+        return {
+            check: 'working directories',
+            status: 'warn',
+            message: 'project not initialized for Comet — run: comet init --scope project if this project should use Comet workflows',
+        };
+    }
+    return {
+        check: 'working directories',
+        status: 'warn',
+        message: `partial (missing: ${missing.join(', ')})`,
+    };
+}
+async function checkClassicLayout(projectPath) {
+    let transaction;
+    try {
+        transaction = await inspectClassicRootMove(projectPath);
+    }
+    catch (error) {
+        return {
+            check: 'Classic artifact layout',
+            status: 'fail',
+            message: `invalid root move journal; allowed strategies: none (${error instanceof Error ? error.message : String(error)})`,
+        };
+    }
+    if (transaction) {
+        const allowed = transaction.allowedStrategies.length > 0 ? transaction.allowedStrategies.join(', ') : 'none';
+        return {
+            check: 'Classic artifact layout',
+            status: 'fail',
+            message: `root move ${transaction.id} is incomplete at ${transaction.stage}; source ${transaction.source}; target ${transaction.target}; staging ${transaction.staging}; plan ${transaction.planId}; allowed strategies: ${allowed}${transaction.reason ? ` (${transaction.reason})` : ''}; run comet doctor --repair --strategy <strategy>`,
+        };
+    }
+    let inspection;
+    try {
+        inspection = await inspectClassicLayout(projectPath);
+    }
+    catch (error) {
+        return {
+            check: 'Classic artifact layout',
+            status: 'fail',
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (inspection.dualRoots) {
+        return {
+            check: 'Classic artifact layout',
+            status: 'fail',
+            message: 'both openspec/ and docs/openspec/ exist; Classic writes are blocked until the conflict is resolved',
+        };
+    }
+    const configuredRoot = path
+        .relative(projectPath, inspection.paths.openSpecRoot)
+        .replaceAll('\\', '/');
+    const alternateRoot = path.relative(projectPath, inspection.alternateRoot).replaceAll('\\', '/');
+    if (!inspection.configuredRootExists) {
+        return {
+            check: 'Classic artifact layout',
+            status: 'fail',
+            message: `${inspection.paths.artifactLayout}: configured ${configuredRoot}/ missing; alternate ${alternateRoot}/ ${inspection.alternateRootExists ? 'present' : 'missing'} — run: comet classic root show, then restore the configured root or use comet classic root move`,
+        };
+    }
+    return {
+        check: 'Classic artifact layout',
+        status: 'pass',
+        message: `${inspection.paths.artifactLayout}: configured ${configuredRoot}/ present; alternate ${alternateRoot}/ ${inspection.alternateRootExists ? 'present' : 'missing'}`,
+    };
+}
+async function checkClassicInitialization(projectPath) {
+    try {
+        const initialization = await inspectClassicLayoutInitialization(projectPath);
+        if (!initialization)
+            return null;
+        const location = initialization.quarantine ? `; preserved at ${initialization.quarantine}` : '';
+        return {
+            check: 'Classic initialization',
+            status: 'warn',
+            message: `${initialization.id} at ${initialization.stage}${location}; allowed strategies: ${initialization.allowedStrategies.join(', ')}`,
+        };
+    }
+    catch (error) {
+        return {
+            check: 'Classic initialization',
+            status: 'fail',
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function checkProjectConfigWriteTransaction(projectPath) {
+    try {
+        const transaction = await inspectWorkflowProjectConfigTransaction(projectPath);
+        if (!transaction)
+            return null;
+        return {
+            check: 'project config write transaction',
+            status: 'warn',
+            message: `${transaction.id} at ${transaction.stage}; repair with: comet doctor --repair`,
+        };
+    }
+    catch (error) {
+        return {
+            check: 'project config write transaction',
+            status: 'fail',
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function checkClassicOpenSpecRoot(projectPath) {
+    try {
+        const health = await assertClassicOpenSpecRootHealthy(projectPath);
+        return {
+            check: 'Classic OpenSpec root',
+            status: 'pass',
+            message: `${health.configPath} is valid (${health.schema})`,
+        };
+    }
+    catch (error) {
+        return {
+            check: 'Classic OpenSpec root',
+            status: 'fail',
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function doctorDirectoryIdentity(stat) {
+    return {
+        object: {
+            dev: stat.dev,
+            ino: stat.ino,
+            birthtime: stat.birthtimeNs,
+        },
+        ctimeNs: stat.ctimeNs,
+        mtimeNs: stat.mtimeNs,
+        size: stat.size,
+    };
+}
+function sameDoctorDirectory(left, right) {
+    return (sameFileObject(left.object, right.object) &&
+        left.ctimeNs === right.ctimeNs &&
+        left.mtimeNs === right.mtimeNs &&
+        left.size === right.size);
+}
+async function readDoctorPlatformDirectory(projectPath, relativeDirectory, maxEntries) {
+    const label = `Classic platform tool directory ${relativeDirectory}`;
+    const inspection = await inspectProtectedProjectPath(projectPath, relativeDirectory, {
+        label,
+        expected: 'directory',
+    });
+    if (!inspection.exists)
+        return null;
+    const beforeStat = await fs.lstat(inspection.target, { bigint: true });
+    if (!beforeStat.isDirectory() || beforeStat.isSymbolicLink()) {
+        throw new Error(`${label} must be a real directory`);
+    }
+    const before = doctorDirectoryIdentity(beforeStat);
+    const entries = [];
+    let readError;
+    const directory = await fs.opendir(inspection.target);
+    try {
+        for await (const entry of directory) {
+            entries.push(entry);
+            if (entries.length > maxEntries) {
+                throw new Error(`Classic platform tool scan exceeds ${CLASSIC_PLATFORM_TOOL_SCAN_MAX_ENTRIES} entries`);
+            }
+        }
+    }
+    catch (error) {
+        readError = error;
+    }
+    finally {
+        await directory.close().catch((error) => {
+            if (error.code !== 'ERR_DIR_CLOSED' && !readError) {
+                readError = error;
+            }
+        });
+    }
+    const afterInspection = await inspectProtectedProjectPath(projectPath, relativeDirectory, {
+        label,
+        expected: 'directory',
+    });
+    if (!afterInspection.exists) {
+        throw new Error(`${label} changed while being inspected`);
+    }
+    const afterStat = await fs.lstat(afterInspection.target, { bigint: true });
+    if (!afterStat.isDirectory() ||
+        afterStat.isSymbolicLink() ||
+        !sameDoctorDirectory(before, doctorDirectoryIdentity(afterStat))) {
+        throw new Error(`${label} changed while being inspected`);
+    }
+    if (readError)
+        throw readError;
+    return entries;
+}
+function isOpenSpecPlatformToolSentinel(relativePath, kind) {
+    const segments = relativePath.split('/');
+    const name = segments.at(-1) ?? '';
+    const parent = segments.at(-2) ?? '';
+    if (kind === 'directory' && parent === 'skills' && /^openspec-[a-z0-9-]+$/iu.test(name)) {
+        return true;
+    }
+    if (kind !== 'file')
+        return false;
+    const insideCommandContainer = segments.some((segment) => OPEN_SPEC_COMMAND_CONTAINER_NAMES.has(segment));
+    if (!insideCommandContainer)
+        return false;
+    return /^(?:opsx|openspec)-[a-z0-9-]+\.[a-z0-9.]+$/iu.test(name) || segments.includes('opsx');
+}
+async function findClassicArtifactPlatformTools(projectPath, artifactBaseRelative) {
+    const findings = new Set();
+    const queue = CLASSIC_PLATFORM_TOOL_ROOTS.map((platformRoot) => ({
+        relative: path.posix.join(artifactBaseRelative, platformRoot.replaceAll('\\', '/')),
+        depth: 0,
+    }));
+    let inspectedEntries = 0;
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const entries = await readDoctorPlatformDirectory(projectPath, current.relative, CLASSIC_PLATFORM_TOOL_SCAN_MAX_ENTRIES - inspectedEntries);
+        if (!entries)
+            continue;
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            inspectedEntries += 1;
+            if (inspectedEntries > CLASSIC_PLATFORM_TOOL_SCAN_MAX_ENTRIES) {
+                throw new Error(`Classic platform tool scan exceeds ${CLASSIC_PLATFORM_TOOL_SCAN_MAX_ENTRIES} entries`);
+            }
+            const relative = path.posix.join(current.relative, entry.name);
+            const inspection = await inspectProtectedProjectPath(projectPath, relative, {
+                label: `Classic platform tool candidate ${relative}`,
+                expected: 'any',
+            });
+            if (!inspection.exists) {
+                throw new Error(`Classic platform tool candidate ${relative} changed while being inspected`);
+            }
+            const kind = inspection.kind === 'directory' ? 'directory' : 'file';
+            if (isOpenSpecPlatformToolSentinel(relative, kind)) {
+                findings.add(relative);
+                if (findings.size > CLASSIC_PLATFORM_TOOL_SCAN_MAX_FINDINGS) {
+                    throw new Error(`Classic platform tool scan exceeds ${CLASSIC_PLATFORM_TOOL_SCAN_MAX_FINDINGS} findings`);
+                }
+                continue;
+            }
+            if (kind === 'directory') {
+                if (current.depth >= CLASSIC_PLATFORM_TOOL_SCAN_MAX_DEPTH) {
+                    throw new Error(`Classic platform tool scan exceeds depth ${CLASSIC_PLATFORM_TOOL_SCAN_MAX_DEPTH} at ${relative}`);
+                }
+                queue.push({ relative, depth: current.depth + 1 });
+            }
+        }
+    }
+    return [...findings].sort();
+}
+async function checkClassicPlatformToolAssets(projectPath) {
+    let layout;
+    try {
+        layout = await resolveClassicLayout(projectPath);
+    }
+    catch {
+        // The dedicated layout check already reports why the configured layout
+        // cannot be trusted. Do not guess whether the docs-only check applies.
+        return null;
+    }
+    if (layout.artifactLayout !== 'docs')
+        return null;
+    const artifactBaseRelative = path
+        .relative(projectPath, layout.openSpecBase)
+        .replaceAll('\\', '/');
+    try {
+        const findings = await findClassicArtifactPlatformTools(projectPath, artifactBaseRelative);
+        if (findings.length === 0) {
+            return {
+                check: 'Classic platform tool assets',
+                status: 'pass',
+                message: 'no OpenSpec platform tool assets under docs/',
+            };
+        }
+        return {
+            check: 'Classic platform tool assets',
+            status: 'fail',
+            message: `found OpenSpec platform tool assets under the docs artifact root: ${findings.join(', ')}; these assets belong in platform directories at the project root — run comet update to repair the platform installation. Doctor did not move any files.`,
+        };
+    }
+    catch (error) {
+        return {
+            check: 'Classic platform tool assets',
+            status: 'fail',
+            message: `could not safely inspect platform tool assets under docs/: ${error instanceof Error ? error.message : String(error)}; platform tool assets belong in platform directories at the project root — run comet update to repair the platform installation. Doctor did not move any files.`,
+        };
+    }
+}
+async function checkSuperpowers(projectPath, scope, context) {
+    const detected = [];
+    for (const base of getScopeBases(projectPath, scope, context)) {
+        for (const platform of PLATFORMS) {
+            for (const skillsDir of getPlatformSkillsDirs(platform, base.scope)) {
+                for (const sentinel of SUPERPOWERS_SENTINELS) {
+                    if (await fileExists(path.join(base.baseDir, skillsDir, 'skills', sentinel))) {
+                        detected.push(`${platform.name} ${base.scope}`);
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    const uniqueDetected = [...new Set(detected)];
+    if (uniqueDetected.length > 0) {
+        return {
+            check: 'Superpowers',
+            status: 'pass',
+            message: `detected (${uniqueDetected.join(', ')}; version not recorded by skills installer)`,
+        };
+    }
+    return {
+        check: 'Superpowers',
+        status: 'warn',
+        message: 'not detected — install with: npx skills add obra/superpowers -y --agent <platform>',
+    };
+}
+function getScopeBases(projectPath, scope, context) {
+    if (scope === 'project')
+        return [{ scope, baseDir: projectPath }];
+    if (scope === 'global')
+        return [{ scope, baseDir: context.homeDir }];
+    const bases = [
+        { scope: 'project', baseDir: projectPath },
+    ];
+    if (path.resolve(projectPath) !== path.resolve(context.homeDir)) {
+        bases.push({ scope: 'global', baseDir: context.homeDir });
+    }
+    return bases;
+}
+async function checkPlatformComponents(baseDir, platform, scope, workflowSelection) {
+    const results = [];
+    const ruleDestinations = await getPlatformRuleDestinations(baseDir, platform, scope, workflowSelection);
+    if (ruleDestinations.length > 0) {
+        let present = 0;
+        const inspectionErrors = [];
+        for (const destination of ruleDestinations) {
+            try {
+                if (await fileExists(destination))
+                    present++;
+            }
+            catch (error) {
+                inspectionErrors.push(`${destination}: ${error.message}`);
+            }
+        }
+        results.push({
+            check: `rules: ${platform.name} (${scope})`,
+            status: inspectionErrors.length === 0 && present === ruleDestinations.length ? 'pass' : 'warn',
+            message: inspectionErrors.length > 0
+                ? `unable to inspect managed Rule (${inspectionErrors.join('; ')}) — run: comet update --scope ${scope}`
+                : present === ruleDestinations.length
+                    ? `complete (${present} files)`
+                    : `partial (${present}/${ruleDestinations.length} files) — run: comet update --scope ${scope}`,
+        });
+        const legacyRuleDestinations = getLegacyPlatformRuleDestinations(baseDir, platform, scope);
+        let legacyRules = 0;
+        const legacyInspectionErrors = [];
+        for (const destination of legacyRuleDestinations) {
+            try {
+                if (await fileExists(destination))
+                    legacyRules++;
+            }
+            catch (error) {
+                legacyInspectionErrors.push(`${destination}: ${error.message}`);
+            }
+        }
+        if (legacyInspectionErrors.length > 0) {
+            results.push({
+                check: `legacy rules: ${platform.name} (${scope})`,
+                status: 'warn',
+                message: `unable to inspect legacy managed Rule (${legacyInspectionErrors.join('; ')})`,
+            });
+        }
+        if (legacyRules > 0) {
+            results.push({
+                check: `legacy rules: ${platform.name} (${scope})`,
+                status: 'warn',
+                message: `${legacyRules} legacy managed Rule file(s) remain — run: comet doctor --repair --scope ${scope}`,
+            });
+        }
+    }
+    if (platform.supportsHooks && platform.hookFormat) {
+        const runtime = hookRouterRuntimePaths(baseDir, platform, scope);
+        try {
+            const [expected, installed] = await Promise.all([
+                fs.readFile(runtime.source),
+                fs.readFile(runtime.destination),
+            ]);
+            results.push({
+                check: `hook runtime: ${platform.name} (${scope})`,
+                status: expected.equals(installed) ? 'pass' : 'warn',
+                message: expected.equals(installed)
+                    ? 'current'
+                    : `outdated — run: comet doctor --repair --scope ${scope}`,
+            });
+        }
+        catch (error) {
+            results.push({
+                check: `hook runtime: ${platform.name} (${scope})`,
+                status: 'warn',
+                message: `unable to verify current Router runtime (${error.message}) — run: comet doctor --repair --scope ${scope}`,
+            });
+        }
+        const inspection = await inspectCometHooksForPlatform(baseDir, platform, scope, workflowSelection);
+        results.push({
+            check: `hooks: ${platform.name} (${scope})`,
+            status: inspection.present && !inspection.legacyPresent && !inspection.duplicatePresent
+                ? 'pass'
+                : 'warn',
+            message: inspection.present && !inspection.legacyPresent && !inspection.duplicatePresent
+                ? 'exactly one managed Router Hook present'
+                : inspection.present && inspection.duplicatePresent
+                    ? `duplicate managed Router Hooks remain — run: comet doctor --repair --scope ${scope}`
+                    : inspection.present && inspection.legacyPresent
+                        ? `Router Hook and legacy managed Hook coexist — run: comet doctor --repair --scope ${scope}`
+                        : `${inspection.error ?? 'managed Hook missing'} — run: comet update --scope ${scope}`,
+        });
+    }
+    return results;
+}
+async function getPlatformsForSkillInspection(baseDir, scope, doctorScope) {
+    return (await resolveCanonicalSkillRootOwners(baseDir, scope, {
+        respectDetectionPaths: doctorScope === 'auto',
+    })).map(({ platform, hasOwnershipEvidence, sharedCanonicalRoot }) => ({
+        platform,
+        inspectComponents: !sharedCanonicalRoot || hasOwnershipEvidence,
+    }));
+}
+async function checkSkillCompleteness(projectPath, scope, context, workflowSelection) {
+    const results = [];
+    const manifest = await readManifest();
+    let anyCometInstall = false;
+    const scopeState = {
+        project: { hasInstall: false, hasComplete: false },
+        global: { hasInstall: false, hasComplete: false },
+    };
+    for (const base of getScopeBases(projectPath, scope, context)) {
+        const managedSkills = getManagedSkillPathsForSelection(manifest, base.scope === 'global' ? 'classic' : workflowSelection);
+        const total = managedSkills.length;
+        const platforms = await getPlatformsForSkillInspection(base.baseDir, base.scope, scope);
+        for (const { platform, inspectComponents } of platforms) {
+            const skillsDirs = getPlatformSkillsDirs(platform, base.scope);
+            const canonicalSkillsDir = skillsDirs[0];
+            let detectedSkillsDir;
+            let present = [];
+            let missing = [];
+            for (const skillsDir of skillsDirs) {
+                const candidatePresent = [];
+                const candidateMissing = [];
+                for (const relPath of managedSkills) {
+                    const fullPath = path.join(base.baseDir, skillsDir, 'skills', relPath);
+                    if (await fileExists(fullPath))
+                        candidatePresent.push(relPath);
+                    else
+                        candidateMissing.push(relPath);
+                }
+                if (candidatePresent.length === 0)
+                    continue;
+                detectedSkillsDir = skillsDir;
+                present = candidatePresent;
+                missing = candidateMissing;
+                break;
+            }
+            if (!detectedSkillsDir)
+                continue;
+            anyCometInstall = true;
+            scopeState[base.scope].hasInstall = true;
+            const isLegacy = detectedSkillsDir !== canonicalSkillsDir;
+            if (missing.length === 0 && !isLegacy) {
+                scopeState[base.scope].hasComplete = true;
+            }
+            results.push(isLegacy
+                ? {
+                    check: `skills: ${platform.name} (${base.scope})`,
+                    status: 'warn',
+                    message: `legacy installation (${present.length}/${total} files) — run: comet update --scope ${base.scope}`,
+                }
+                : missing.length === 0
+                    ? {
+                        check: `skills: ${platform.name} (${base.scope})`,
+                        status: 'pass',
+                        message: `complete (${total} files)`,
+                    }
+                    : {
+                        check: `skills: ${platform.name} (${base.scope})`,
+                        status: 'warn',
+                        message: `partial (${present.length}/${total} files; missing ${missing.length}) — run: comet update --scope ${base.scope}`,
+                    });
+            if (inspectComponents) {
+                results.push(...(await checkPlatformComponents(base.baseDir, platform, base.scope, base.scope === 'global' ? 'classic' : workflowSelection)));
+            }
+        }
+    }
+    if (scope === 'auto' && !scopeState.project.hasInstall && scopeState.global.hasComplete) {
+        results.push({
+            check: 'Project scope',
+            status: 'pass',
+            message: 'no project-local Comet skills installed; global scope is available — run: comet init --scope project only if this project needs its own copy',
+        });
+    }
+    if (!anyCometInstall) {
+        results.push({
+            check: 'Comet skills',
+            status: 'warn',
+            message: scope === 'auto'
+                ? 'not installed in project or global scope — run: comet init'
+                : `not installed in ${scope} scope — run: comet init --scope ${scope}`,
+        });
+    }
+    return results;
+}
+async function checkScriptsPresent() {
+    const assetsDir = getAssetsDir();
+    const scriptsDir = path.join(assetsDir, 'skills', 'comet', 'scripts');
+    if (!(await fileExists(scriptsDir))) {
+        return { check: 'scripts present', status: 'warn', message: 'scripts directory not found' };
+    }
+    const entries = await readDir(scriptsDir);
+    const scriptFiles = entries.filter((e) => e.endsWith('.mjs'));
+    return {
+        check: 'scripts present',
+        status: 'pass',
+        message: `OK (${scriptFiles.length} scripts)`,
+    };
+}
+function formatMissingEvidence(missingEvidence) {
+    return missingEvidence.join(', ');
+}
+function formatRuntimeEvalRecovery(nextCommand, missingEvidence) {
+    const missing = formatMissingEvidence(missingEvidence);
+    if (nextCommand) {
+        return `run ${nextCommand} or restore missing evidence (${missing}), then rerun comet doctor`;
+    }
+    return `restore missing evidence (${missing}) and rerun comet doctor`;
+}
+async function checkCometYamlValidity(projectPath) {
+    let changesDir;
+    try {
+        const inspection = await inspectClassicLayout(projectPath);
+        if (!inspection.configuredRootExists)
+            return [];
+        changesDir = inspection.paths.changesDir;
+        const changesInspection = await inspectProtectedProjectPath(projectPath, path.relative(projectPath, changesDir).replaceAll('\\', '/'), {
+            label: 'Classic changes directory',
+            expected: 'directory',
+        });
+        if (!changesInspection.exists)
+            return [];
+    }
+    catch {
+        // The layout check reports the concrete root/config problem. Do not follow
+        // an unsafe or unavailable configured root merely to enumerate state.
+        return [];
+    }
+    const entries = await readDir(changesDir);
+    const results = [];
+    for (const entry of entries) {
+        if (entry === 'archive')
+            continue;
+        const changeDir = path.join(changesDir, entry);
+        const yamlPath = path.join(changeDir, '.comet.yaml');
+        const runtimePath = path.join(changeDir, '.comet');
+        try {
+            const changeInspection = await inspectProtectedProjectPath(projectPath, path.relative(projectPath, changeDir).replaceAll('\\', '/'), {
+                label: `Classic change ${entry}`,
+                expected: 'directory',
+            });
+            if (!changeInspection.exists)
+                continue;
+            const yamlInspection = await inspectProtectedProjectPath(projectPath, path.relative(projectPath, yamlPath).replaceAll('\\', '/'), {
+                label: `Classic state ${entry}`,
+                expected: 'file',
+            });
+            if (!yamlInspection.exists)
+                continue;
+            await inspectProtectedProjectPath(projectPath, path.relative(projectPath, runtimePath).replaceAll('\\', '/'), {
+                label: `Classic runtime directory ${entry}`,
+                expected: 'directory',
+            });
+        }
+        catch (error) {
+            results.push({
+                check: `.comet.yaml: ${entry}`,
+                status: 'fail',
+                message: error instanceof Error ? error.message : String(error),
+            });
+            continue;
+        }
+        const diagnostic = await inspectClassicChangeReadOnly(changeDir, entry);
+        if (diagnostic.valid) {
+            const step = diagnostic.currentStep ??
+                (diagnostic.runtimeMode === 'legacy-state' ? `legacy:${diagnostic.phase}` : 'completed');
+            results.push({
+                check: `.comet.yaml: ${entry}`,
+                status: 'pass',
+                message: `valid (step: ${step}, mode: ${diagnostic.runtimeMode})`,
+            });
+            if (diagnostic.runtimeEval) {
+                const runtimeCheckMessage = diagnostic.runtimeEval.passed
+                    ? `pass (${diagnostic.runtimeEval.stepId})`
+                    : `fail (${diagnostic.runtimeEval.stepId}; missing: ${formatMissingEvidence(diagnostic.runtimeEval.missingEvidence)}; next: ${formatRuntimeEvalRecovery(diagnostic.nextCommand, diagnostic.runtimeEval.missingEvidence)})`;
+                results.push({
+                    check: `runtime_check: ${entry}`,
+                    status: diagnostic.runtimeEval.passed ? 'pass' : 'warn',
+                    message: runtimeCheckMessage,
+                });
+            }
+            continue;
+        }
+        results.push({
+            check: `.comet.yaml: ${entry}`,
+            status: 'fail',
+            message: diagnostic.error ?? 'invalid Classic state',
+        });
+        results.push({
+            check: `next: ${entry}`,
+            status: 'warn',
+            message: 'inspect .comet.yaml and rerun comet doctor',
+        });
+    }
+    return results;
+}
+function codegraphCheckResult(diagnostic) {
+    return {
+        check: diagnostic.status === 'cli_missing' ? 'CodeGraph CLI' : 'CodeGraph',
+        status: diagnostic.status === 'index_ready' || diagnostic.status === 'cli_ready' ? 'pass' : 'warn',
+        message: diagnostic.remediation
+            ? `${diagnostic.detail} — run: ${diagnostic.remediation}`
+            : diagnostic.detail,
+    };
+}
+async function inspectManagedInstallAvailability(baseDir, scope, workflowSelection) {
+    const manifest = await readManifest();
+    const managedSkills = getManagedSkillPathsForSelection(manifest, scope === 'global' ? 'classic' : workflowSelection);
+    let partial = false;
+    for (const platform of PLATFORMS) {
+        const skillsDirs = getPlatformSkillsDirs(platform, scope);
+        const canonicalSkillsDir = skillsDirs[0];
+        for (const skillsDir of skillsDirs) {
+            const presence = await Promise.all(managedSkills.map((relative) => fileExists(path.join(baseDir, skillsDir, 'skills', ...relative.split('/')))));
+            const present = presence.filter(Boolean).length;
+            if (present === managedSkills.length && skillsDir === canonicalSkillsDir)
+                return 'ready';
+            if (present > 0)
+                partial = true;
+        }
+    }
+    return partial ? 'partial' : 'missing';
+}
+async function inspectDoctorRuntime(projectPath, context, workflowSelection) {
+    const worktree = inspectGitWorktree(projectPath);
+    const currentProjectInstall = await inspectManagedInstallAvailability(projectPath, 'project', workflowSelection);
+    const primaryProjectInstall = worktree.isSecondaryWorktree && worktree.primaryWorktreeRoot
+        ? await inspectManagedInstallAvailability(worktree.primaryWorktreeRoot, 'project', workflowSelection)
+        : currentProjectInstall;
+    const globalFallbackReady = (await inspectManagedInstallAvailability(context.homeDir, 'global', 'classic')) === 'ready';
+    const effectiveScope = currentProjectInstall !== 'missing' ? 'project' : globalFallbackReady ? 'global' : 'none';
+    const remediation = effectiveScope !== 'none'
+        ? null
+        : worktree.isSecondaryWorktree && primaryProjectInstall === 'ready'
+            ? 'run comet init . --scope project in this worktree, or install a global fallback'
+            : 'run comet init . --scope project';
+    return {
+        isSecondaryWorktree: worktree.isSecondaryWorktree,
+        currentWorktreeRoot: worktree.currentWorktreeRoot,
+        primaryWorktreeRoot: worktree.primaryWorktreeRoot,
+        currentProjectInstall,
+        primaryProjectInstall,
+        globalFallbackReady,
+        effectiveScope,
+        remediation,
+    };
+}
+function worktreeRuntimeCheck(runtime) {
+    if (!runtime.isSecondaryWorktree)
+        return null;
+    if (runtime.currentProjectInstall === 'ready') {
+        return {
+            check: 'Worktree runtime',
+            status: 'pass',
+            message: 'secondary Git worktree has a complete project-scope Comet installation',
+        };
+    }
+    if (runtime.primaryProjectInstall === 'ready' && runtime.globalFallbackReady) {
+        return {
+            check: 'Worktree runtime',
+            status: 'pass',
+            message: 'project assets exist only in the primary worktree; this worktree uses a complete global fallback and does not execute primary-worktree files',
+        };
+    }
+    return {
+        check: 'Worktree runtime',
+        status: runtime.effectiveScope === 'none' ? 'fail' : 'warn',
+        message: runtime.primaryProjectInstall === 'ready'
+            ? `project assets exist only in the primary worktree and are not executed here; ${runtime.remediation}`
+            : `secondary worktree has no complete effective runtime; ${runtime.remediation}`,
+    };
+}
+async function collectResults(projectPath, scope) {
+    const context = { homeDir: os.homedir() };
+    return collectResultsWithContext(projectPath, scope, context);
+}
+async function collectResultsWithContext(projectPath, scope, context) {
+    const results = [];
+    if (scope !== 'global') {
+        const configTransaction = await checkProjectConfigWriteTransaction(projectPath);
+        if (configTransaction)
+            results.push(configTransaction);
+    }
+    let config = null;
+    let configError = null;
+    if (scope !== 'global') {
+        try {
+            config = await readWorkflowProjectConfig(projectPath);
+        }
+        catch (error) {
+            configError = error instanceof Error ? error.message : String(error);
+        }
+    }
+    const workflows = configError ? ['native', 'classic'] : configuredWorkflows(config);
+    const workflowSelection = workflows.includes('native') && workflows.includes('classic')
+        ? 'both'
+        : workflows.includes('native')
+            ? 'native'
+            : 'classic';
+    const classicEnabled = workflowSelection !== 'native';
+    const runtime = await inspectDoctorRuntime(projectPath, context, workflowSelection);
+    const worktreeCheck = worktreeRuntimeCheck(runtime);
+    if (worktreeCheck)
+        results.push(worktreeCheck);
+    if (configError) {
+        results.push({ check: 'project config', status: 'fail', message: configError });
+    }
+    const scopeMode = checkScopeMode(projectPath, scope, context);
+    if (scopeMode)
+        results.push(scopeMode);
+    results.push(checkEnvironment(projectPath, context));
+    results.push(checkCometCli());
+    if (scope !== 'global') {
+        const classicInitialization = await checkClassicInitialization(projectPath);
+        if (classicInitialization)
+            results.push(classicInitialization);
+    }
+    if (classicEnabled) {
+        results.push(await checkOpenSpecCli());
+        results.push(await checkSuperpowers(projectPath, scope === 'project' && runtime.isSecondaryWorktree && runtime.globalFallbackReady
+            ? 'auto'
+            : scope, context));
+        if (scope !== 'global') {
+            const classicLayout = await checkClassicLayout(projectPath);
+            results.push(classicLayout);
+            const platformToolAssets = await checkClassicPlatformToolAssets(projectPath);
+            if (platformToolAssets)
+                results.push(platformToolAssets);
+            results.push(await checkClassicOpenSpecRoot(projectPath));
+            results.push(await checkWorkingDirs(projectPath));
+        }
+    }
+    const skillResults = await checkSkillCompleteness(projectPath, scope, context, workflowSelection);
+    if (scope === 'project' &&
+        runtime.isSecondaryWorktree &&
+        runtime.primaryProjectInstall === 'ready' &&
+        runtime.currentProjectInstall === 'missing') {
+        const missing = skillResults.find((result) => result.check === 'Comet skills');
+        if (missing) {
+            missing.status = runtime.globalFallbackReady ? 'pass' : 'warn';
+            missing.message = runtime.globalFallbackReady
+                ? 'not copied into this secondary worktree; primary-worktree assets remain isolated and a complete global fallback is active'
+                : `not copied into this secondary worktree; primary-worktree assets are not executed here — ${runtime.remediation}`;
+        }
+    }
+    results.push(...skillResults);
+    results.push(await checkScriptsPresent());
+    const codegraph = scope === 'global'
+        ? resolveCodegraphCommand()
+            ? {
+                status: 'cli_ready',
+                repairable: false,
+                remediation: null,
+                detail: 'CodeGraph CLI is installed; project indexes are not part of global scope',
+            }
+            : {
+                status: 'cli_missing',
+                repairable: false,
+                remediation: 'npm install -g @colbymchenry/codegraph',
+                detail: 'CodeGraph CLI is not installed',
+            }
+        : inspectCodegraphIndex(projectPath);
+    results.push(codegraphCheckResult(codegraph));
+    if (classicEnabled && !configError && config && workflows.includes('classic')) {
+        results.push(...(await checkCometYamlValidity(projectPath)));
+    }
+    if (scope !== 'global') {
+        results.push(configError
+            ? {
+                check: 'current selection',
+                status: 'fail',
+                message: `unavailable because project config is invalid: ${configError}`,
+            }
+            : await checkCurrentSelection(projectPath));
+    }
+    return { results, runtime, codegraph };
+}
+async function checkCurrentSelection(projectPath) {
+    const resolution = await resolveHookWorkflowOwner(projectPath);
+    if (resolution.status === 'none') {
+        return { check: 'current selection', status: 'pass', message: 'no active Comet change' };
+    }
+    if (resolution.status === 'owned') {
+        return {
+            check: 'current selection',
+            status: 'pass',
+            message: `${resolution.owner.workflow}:${resolution.owner.name} (${resolution.owner.phase})`,
+        };
+    }
+    if (resolution.status === 'inferred') {
+        return {
+            check: 'current selection',
+            status: 'warn',
+            message: `missing; Router can infer ${resolution.owner.workflow}:${resolution.owner.name} read-only — select it explicitly before concurrent work`,
+        };
+    }
+    if (resolution.status === 'ambiguous') {
+        return {
+            check: 'current selection',
+            status: 'fail',
+            message: `missing with multiple active changes: ${resolution.candidates.map((candidate) => `${candidate.workflow}:${candidate.name}`).join(', ')}`,
+        };
+    }
+    if (resolution.status === 'stale') {
+        return { check: 'current selection', status: 'fail', message: resolution.reason };
+    }
+    return { check: 'current selection', status: 'fail', message: 'unknown selection state' };
+}
+async function hasManagedInstall(baseDir, platform, scope) {
+    const manifest = await readManifest();
+    const sentinel = getManagedSkillPaths(manifest)[0];
+    if (!sentinel)
+        return false;
+    return (await Promise.all(getPlatformSkillsDirs(platform, scope).map((skillsDir) => fileExists(path.join(baseDir, skillsDir, 'skills', ...sentinel.split('/')))))).some(Boolean);
+}
+async function repairDoctorState(projectPath, scope, context, strategy, repairCodegraph = false, quietCodegraph = false) {
+    const repaired = [];
+    let projectRouterReady = false;
+    if (scope !== 'global' && (await repairWorkflowProjectConfigTransaction(projectPath))) {
+        repaired.push('project config write transaction');
+    }
+    const config = scope === 'global' ? null : await readWorkflowProjectConfig(projectPath);
+    const workflows = configuredWorkflows(config);
+    const language = configuredSkillLanguage(config, workflows);
+    const workflowSelection = workflows.includes('native') && workflows.includes('classic')
+        ? 'both'
+        : workflows.includes('native')
+            ? 'native'
+            : 'classic';
+    const targets = [];
+    for (const base of getScopeBases(projectPath, scope, context)) {
+        const platforms = await getPlatformsForSkillInspection(base.baseDir, base.scope, scope);
+        for (const { platform, inspectComponents } of platforms) {
+            if (!inspectComponents || !(await hasManagedInstall(base.baseDir, platform, base.scope))) {
+                continue;
+            }
+            targets.push({ baseDir: base.baseDir, scope: base.scope, platform });
+        }
+    }
+    for (const target of targets) {
+        const { baseDir, scope: targetScope, platform } = target;
+        if (platform.supportsHooks && platform.hookFormat) {
+            const runtime = hookRouterRuntimePaths(baseDir, platform, targetScope);
+            await copyFile(runtime.source, runtime.destination);
+        }
+        const hookResult = await installCometHooksForPlatform(baseDir, platform, targetScope, workflowSelection);
+        if (hookResult.status === 'failed') {
+            throw new Error(`failed to repair Hook for ${platform.name} (${targetScope}): ${hookResult.reason}`);
+        }
+        if (targetScope === 'project' && hookResult.status === 'installed') {
+            projectRouterReady = true;
+        }
+    }
+    if (scope !== 'global' && projectRouterReady) {
+        const selectionRepair = await repairCometCurrentSelection(projectPath, {
+            migrateLegacyClassic: workflows.includes('classic'),
+        });
+        if (selectionRepair.migratedLegacyClassic)
+            repaired.push('Classic selection v1');
+        if (selectionRepair.clearedStaleSelection)
+            repaired.push('stale current selection');
+    }
+    if (scope !== 'global' && strategy) {
+        if (await repairClassicLayoutInitialization(projectPath, strategy)) {
+            repaired.push('Classic initialization');
+        }
+        else if (await repairClassicRootMove(projectPath, strategy)) {
+            repaired.push('Classic root move');
+        }
+    }
+    for (const target of targets) {
+        const { baseDir, scope: targetScope, platform } = target;
+        const ruleResult = await copyCometRulesForPlatform(baseDir, platform, true, language, targetScope, workflowSelection);
+        if (ruleResult.failed > 0) {
+            throw new Error(`failed to repair Rule for ${platform.name} (${targetScope})`);
+        }
+        repaired.push(`${platform.name} (${targetScope})`);
+    }
+    if (repairCodegraph && scope !== 'global') {
+        const diagnostic = inspectCodegraphIndex(projectPath);
+        if (diagnostic.status === 'project_not_initialized' ||
+            diagnostic.status === 'index_incomplete' ||
+            diagnostic.status === 'index_stale') {
+            repairCodegraphIndex(projectPath, diagnostic.remediation === 'codegraph init -i'
+                ? 'project_not_initialized'
+                : diagnostic.remediation === 'codegraph sync'
+                    ? 'index_stale'
+                    : 'index_incomplete', quietCodegraph);
+            repaired.push('CodeGraph project index');
+        }
+    }
+    return repaired;
+}
+function icon(status) {
+    if (status === 'pass')
+        return '✓';
+    if (status === 'warn')
+        return '⚠';
+    return '✗';
+}
+export async function doctorCommand(targetPath, options = {}) {
+    const projectPath = path.resolve(targetPath);
+    const scope = options.scope ?? 'auto';
+    const context = { homeDir: path.resolve(options.homeDir ?? os.homedir()) };
+    if (options.strategy && !options.repair) {
+        throw new Error('--strategy requires --repair');
+    }
+    if (options.yes && !options.repair) {
+        throw new Error('--yes requires --repair');
+    }
+    const repaired = options.repair
+        ? await repairDoctorState(projectPath, scope, context, options.strategy, options.yes === true, options.json === true)
+        : [];
+    const report = options.homeDir === undefined
+        ? await collectResults(projectPath, scope)
+        : await collectResultsWithContext(projectPath, scope, context);
+    const { results, runtime, codegraph } = report;
+    const healthy = results.every((result) => result.status !== 'fail');
+    const status = healthy ? 'passed' : 'failed';
+    if (options.json) {
+        console.log(JSON.stringify({ scope, status, healthy, repaired, runtime, codegraph, results }, null, 2));
+        return;
+    }
+    console.log(`Comet Doctor (scope: ${scope})\n`);
+    if (options.repair) {
+        console.log(`  Repaired: ${repaired.length > 0 ? repaired.join(', ') : 'nothing to change'}\n`);
+    }
+    for (const r of results) {
+        console.log(`  ${icon(r.status)} ${r.check}: ${r.message}`);
+    }
+    console.log();
+}
+//# sourceMappingURL=doctor.js.map