@cleocode/cleo 2026.2.5

package/dist/cli/commands/docs.js

@@ -0,0 +1,167 @@
+/**
+ * CLI docs command - documentation management with drift detection and gap checking.
+ * Ported from scripts/docs.sh
+ * @task T4551
+ * @epic T4545
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { formatError } from '../../core/output.js';
+import { cliOutput } from '../renderers/index.js';
+import { CleoError } from '../../core/errors.js';
+import { readJson } from '../../store/json.js';
+import { getAgentOutputsAbsolute } from '../../core/paths.js';
+/**
+ * Get list of script files from scripts/ directory.
+ * @task T4551
+ */
+async function getScriptNames(projectRoot) {
+    const scriptsDir = join(projectRoot, 'scripts');
+    try {
+        const files = await readdir(scriptsDir);
+        return files
+            .filter((f) => f.endsWith('.sh'))
+            .map((f) => f.replace('.sh', ''))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get command names from COMMANDS-INDEX.json.
+ * @task T4551
+ */
+async function getIndexedCommands(projectRoot) {
+    const indexPath = join(projectRoot, 'docs', 'commands', 'COMMANDS-INDEX.json');
+    const index = await readJson(indexPath);
+    if (!index)
+        return [];
+    return index.commands.map((c) => c.name).sort();
+}
+/**
+ * Run drift detection between scripts and documentation index.
+ * @task T4551
+ */
+async function detectDrift(projectRoot) {
+    const scripts = await getScriptNames(projectRoot);
+    const indexed = await getIndexedCommands(projectRoot);
+    const scriptSet = new Set(scripts);
+    const indexSet = new Set(indexed);
+    const missingFromIndex = scripts.filter((s) => !indexSet.has(s));
+    const missingFromScripts = indexed.filter((i) => !scriptSet.has(i));
+    const warnings = [];
+    if (missingFromIndex.length > 0) {
+        warnings.push(`${missingFromIndex.length} scripts not in COMMANDS-INDEX.json`);
+    }
+    if (missingFromScripts.length > 0) {
+        warnings.push(`${missingFromScripts.length} index entries without scripts`);
+    }
+    let status = 'clean';
+    if (missingFromIndex.length > 0 || missingFromScripts.length > 0) {
+        status = missingFromIndex.length > 5 ? 'error' : 'warning';
+    }
+    return { status, missingFromIndex, missingFromScripts, warnings };
+}
+/**
+ * Run gap-check validation for review docs.
+ * @task T4551
+ */
+async function runGapCheck(_projectRoot, filterId) {
+    const reviewDir = getAgentOutputsAbsolute();
+    const results = [];
+    try {
+        const files = await readdir(reviewDir);
+        const reviewFiles = files.filter((f) => f.endsWith('.md'));
+        for (const file of reviewFiles) {
+            // Check filter
+            if (filterId && !file.includes(filterId))
+                continue;
+            const filePath = join(reviewDir, file);
+            const content = await readFile(filePath, 'utf-8');
+            // Extract task ID from filename (e.g., T2402-protocol-spec.md)
+            const taskMatch = file.match(/^(T\d+)/);
+            const taskId = taskMatch ? taskMatch[1] : 'UNKNOWN';
+            const gaps = [];
+            // Check for required sections
+            if (!content.includes('## Summary')) {
+                gaps.push('Missing ## Summary section');
+            }
+            if (!content.includes('**Task**:') && !content.includes('**Task:**')) {
+                gaps.push('Missing Task provenance header');
+            }
+            if (gaps.length > 0) {
+                results.push({ file, taskId, gaps });
+            }
+        }
+    }
+    catch {
+        // Review directory might not exist
+    }
+    return results;
+}
+/**
+ * Register the docs command.
+ * @task T4551
+ */
+export function registerDocsCommand(program) {
+    const docsCmd = program
+        .command('docs')
+        .description('Documentation management: drift detection and gap validation');
+    docsCmd
+        .command('sync')
+        .description('Run drift detection between scripts and docs index')
+        .option('--quick', 'Quick check (commands only)')
+        .option('--strict', 'Exit with error on any drift')
+        .action(async (opts) => {
+        try {
+            const projectRoot = process.cwd();
+            const result = await detectDrift(projectRoot);
+            cliOutput({
+                status: result.status,
+                missingFromIndex: result.missingFromIndex,
+                missingFromScripts: result.missingFromScripts,
+                warnings: result.warnings,
+            }, { command: 'docs', message: result.status === 'clean' ? 'Documentation is in sync' : `Drift detected: ${result.warnings.join('; ')}` });
+            if (opts['strict'] && result.status !== 'clean') {
+                process.exit(result.status === 'error' ? 2 : 1);
+            }
+        }
+        catch (err) {
+            if (err instanceof CleoError) {
+                console.error(formatError(err));
+                process.exit(err.code);
+            }
+            throw err;
+        }
+    });
+    docsCmd
+        .command('gap-check')
+        .description('Validate knowledge transfer from review docs to canonical docs')
+        .option('--epic <id>', 'Filter by epic ID')
+        .option('--task <id>', 'Filter by task ID')
+        .action(async (opts) => {
+        try {
+            const projectRoot = process.cwd();
+            const filterId = opts['epic'] ?? opts['task'];
+            const gaps = await runGapCheck(projectRoot, filterId);
+            if (gaps.length === 0) {
+                cliOutput({ gapCount: 0, results: [] }, { command: 'docs', message: 'No documentation gaps found' });
+            }
+            else {
+                cliOutput({
+                    gapCount: gaps.length,
+                    results: gaps,
+                }, { command: 'docs', message: `Found ${gaps.length} document(s) with gaps` });
+            }
+        }
+        catch (err) {
+            if (err instanceof CleoError) {
+                console.error(formatError(err));
+                process.exit(err.code);
+            }
+            throw err;
+        }
+    });
+}
+//# sourceMappingURL=docs.js.map

package/dist/cli/commands/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../../src/cli/commands/docs.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/doctor.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CLI doctor command - system diagnostics.
+ * @task T4454
+ */
+import { Command } from 'commander';
+export declare function registerDoctorCommand(program: Command): void;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/cli/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmDpC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuL5D"}

package/dist/cli/commands/doctor.js

@@ -0,0 +1,215 @@
+/**
+ * CLI doctor command - system diagnostics.
+ * @task T4454
+ */
+import { formatError } from '../../core/output.js';
+import { CleoError } from '../../core/errors.js';
+import { cliOutput } from '../renderers/index.js';
+import { ExitCode } from '../../types/exit-codes.js';
+import { getAccessor } from '../../store/data-accessor.js';
+import { getTaskPath, getConfigPath, getArchivePath, getLogPath, getCleoHome, getCleoDirAbsolute, getProjectRoot } from '../../core/paths.js';
+import { checkCleoGitignore, checkVitalFilesTracked, checkLegacyAgentOutputs } from '../../core/validation/doctor/checks.js';
+import { stat, access, readFile } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execAsync = promisify(execFile);
+async function fileExists(path) {
+    try {
+        await access(path, fsConstants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function fileSize(path) {
+    try {
+        const st = await stat(path);
+        return st.size;
+    }
+    catch {
+        return -1;
+    }
+}
+async function commandExists(cmd) {
+    try {
+        const { stdout } = await execAsync('which', [cmd]);
+        return stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function registerDoctorCommand(program) {
+    program
+        .command('doctor')
+        .description('Run system diagnostics and health checks')
+        .action(async () => {
+        try {
+            const checks = [];
+            // 1. Check dependencies
+            const jqPath = await commandExists('jq');
+            checks.push({
+                check: 'jq_installed',
+                status: jqPath ? 'ok' : 'error',
+                message: jqPath ? `jq found: ${jqPath}` : 'jq not found. Install: https://jqlang.github.io/jq/download/',
+            });
+            const gitPath = await commandExists('git');
+            checks.push({
+                check: 'git_installed',
+                status: gitPath ? 'ok' : 'warning',
+                message: gitPath ? `git found: ${gitPath}` : 'git not found (optional)',
+            });
+            // 2. Check CLEO directories
+            const cleoHome = getCleoHome();
+            const cleoDir = getCleoDirAbsolute();
+            const homeExists = await fileExists(cleoHome);
+            checks.push({
+                check: 'cleo_home',
+                status: homeExists ? 'ok' : 'warning',
+                message: homeExists ? `CLEO home: ${cleoHome}` : `CLEO home not found: ${cleoHome}`,
+            });
+            const dirExists = await fileExists(cleoDir);
+            checks.push({
+                check: 'project_dir',
+                status: dirExists ? 'ok' : 'error',
+                message: dirExists ? `Project dir: ${cleoDir}` : `Project dir not found: ${cleoDir}. Run: cleo init`,
+            });
+            // 3. Check data files
+            const todoPath = getTaskPath();
+            const todoExists = await fileExists(todoPath);
+            const todoSize = await fileSize(todoPath);
+            checks.push({
+                check: 'todo_file',
+                status: todoExists ? 'ok' : 'error',
+                message: todoExists
+                    ? `todo.json: ${todoSize} bytes`
+                    : `todo.json not found: ${todoPath}`,
+            });
+            if (todoExists) {
+                try {
+                    const accessor = await getAccessor();
+                    const data = await accessor.loadTaskFile();
+                    const taskCount = data.tasks?.length ?? 0;
+                    const schemaVersion = data._meta?.schemaVersion ?? 'unknown';
+                    checks.push({
+                        check: 'todo_data',
+                        status: 'ok',
+                        message: `${taskCount} tasks, schema v${schemaVersion}`,
+                        details: { taskCount, schemaVersion },
+                    });
+                }
+                catch {
+                    checks.push({
+                        check: 'todo_data',
+                        status: 'error',
+                        message: 'Failed to parse todo.json',
+                    });
+                }
+            }
+            const configPath = getConfigPath();
+            const configExists = await fileExists(configPath);
+            checks.push({
+                check: 'config_file',
+                status: configExists ? 'ok' : 'warning',
+                message: configExists ? 'config.json present' : 'config.json not found (using defaults)',
+            });
+            const archivePath = getArchivePath();
+            const archiveExists = await fileExists(archivePath);
+            checks.push({
+                check: 'archive_file',
+                status: 'ok',
+                message: archiveExists ? 'archive file present' : 'no archive file (normal for new projects)',
+            });
+            const logPath = getLogPath();
+            const logExists = await fileExists(logPath);
+            checks.push({
+                check: 'log_file',
+                status: logExists ? 'ok' : 'warning',
+                message: logExists ? 'log file present' : 'log file not found',
+            });
+            // 4. Check root .gitignore for .cleo/ blocking
+            const projRoot = getProjectRoot();
+            const rootGitignorePath = join(projRoot, '.gitignore');
+            if (await fileExists(rootGitignorePath)) {
+                try {
+                    const gitignoreContent = await readFile(rootGitignorePath, 'utf-8');
+                    const blockingLines = gitignoreContent.split('\n').filter(line => {
+                        const trimmed = line.trim();
+                        if (trimmed.startsWith('#') || trimmed === '')
+                            return false;
+                        return /^\/?\.cleo\/?(\*)?$/.test(trimmed);
+                    });
+                    checks.push({
+                        check: 'root_gitignore',
+                        status: blockingLines.length > 0 ? 'warning' : 'ok',
+                        message: blockingLines.length > 0
+                            ? `.cleo/ is ignored in root .gitignore. Run 'cleo init' to fix.`
+                            : 'Root .gitignore does not block .cleo/',
+                        ...(blockingLines.length > 0 ? { details: { blockingLines } } : {}),
+                    });
+                }
+                catch {
+                    // Ignore read errors for gitignore check
+                }
+            }
+            // 5. Gitignore integrity, vital files, legacy paths
+            const projRootChecks = getProjectRoot();
+            const gitignoreCheck = checkCleoGitignore(projRootChecks);
+            checks.push({
+                check: gitignoreCheck.id,
+                status: gitignoreCheck.status === 'passed' ? 'ok' : gitignoreCheck.status === 'warning' ? 'warning' : 'error',
+                message: gitignoreCheck.message,
+                ...(gitignoreCheck.fix ? { details: { fix: gitignoreCheck.fix } } : {}),
+            });
+            const vitalCheck = checkVitalFilesTracked(projRootChecks);
+            checks.push({
+                check: vitalCheck.id,
+                status: vitalCheck.status === 'passed' ? 'ok' : vitalCheck.status === 'info' ? 'ok' : 'warning',
+                message: vitalCheck.message,
+                ...(vitalCheck.fix ? { details: { fix: vitalCheck.fix } } : {}),
+            });
+            const legacyCheck = checkLegacyAgentOutputs(projRootChecks);
+            checks.push({
+                check: legacyCheck.id,
+                status: legacyCheck.status === 'passed' ? 'ok' : 'warning',
+                message: legacyCheck.message,
+                ...(legacyCheck.fix ? { details: { fix: legacyCheck.fix } } : {}),
+            });
+            // 6. Environment
+            checks.push({
+                check: 'node_version',
+                status: 'ok',
+                message: `Node.js ${process.version}`,
+            });
+            checks.push({
+                check: 'platform',
+                status: 'ok',
+                message: `${process.platform} ${process.arch}`,
+            });
+            // Summary
+            const errorCount = checks.filter((c) => c.status === 'error').length;
+            const warningCount = checks.filter((c) => c.status === 'warning').length;
+            const healthy = errorCount === 0;
+            cliOutput({
+                healthy,
+                errors: errorCount,
+                warnings: warningCount,
+                checks,
+            }, { command: 'doctor', operation: 'system.health' });
+            if (!healthy) {
+                process.exit(ExitCode.VALIDATION_ERROR);
+            }
+        }
+        catch (err) {
+            if (err instanceof CleoError) {
+                console.error(formatError(err));
+                process.exit(err.code);
+            }
+            throw err;
+        }
+    });
+}
+//# sourceMappingURL=doctor.js.map

package/dist/cli/commands/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/env.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CLI env command for environment/mode inspection.
+ * @task T4581
+ * @epic T4577
+ */
+import { Command } from 'commander';
+/**
+ * Register the env command group.
+ * @task T4581
+ */
+export declare function registerEnvCommand(program: Command): void;
+//# sourceMappingURL=env.d.ts.map

package/dist/cli/commands/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/env.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8JpC;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoBzD"}

package/dist/cli/commands/env.js

@@ -0,0 +1,167 @@
+/**
+ * CLI env command for environment/mode inspection.
+ * @task T4581
+ * @epic T4577
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { cliOutput } from '../renderers/index.js';
+/**
+ * Parse the ~/.cleo/VERSION file into structured data.
+ * Returns null if the file does not exist or is unreadable.
+ * @task T4581
+ */
+async function parseVersionFile() {
+    const versionPath = join(process.env['CLEO_HOME'] ?? join(homedir(), '.cleo'), 'VERSION');
+    let content;
+    try {
+        content = await readFile(versionPath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const lines = content.trim().split('\n');
+    const version = lines[0]?.trim() ?? 'unknown';
+    const kvPairs = {};
+    for (let i = 1; i < lines.length; i++) {
+        const eqIdx = lines[i].indexOf('=');
+        if (eqIdx > 0) {
+            const key = lines[i].slice(0, eqIdx).trim();
+            const val = lines[i].slice(eqIdx + 1).trim();
+            kvPairs[key] = val;
+        }
+    }
+    return {
+        version,
+        mode: kvPairs['mode'] ?? 'unknown',
+        source: kvPairs['source'] ?? 'unknown',
+        installed: kvPairs['installed'] ?? 'unknown',
+    };
+}
+/**
+ * Read the package.json version from the source directory (dev mode)
+ * or from the installed package location.
+ * @task T4581
+ */
+async function getPackageInfo(sourceDir) {
+    const candidates = [];
+    if (sourceDir && sourceDir !== 'unknown' && sourceDir !== 'npm') {
+        candidates.push(join(sourceDir, 'package.json'));
+    }
+    // Fallback: resolve relative to this file's module location
+    // In dev-ts mode, dist/cli/commands/env.js -> repo root
+    const moduleRoot = join(import.meta.dirname ?? '', '..', '..', '..');
+    candidates.push(join(moduleRoot, 'package.json'));
+    for (const candidate of candidates) {
+        try {
+            const raw = await readFile(candidate, 'utf-8');
+            const pkg = JSON.parse(raw);
+            return { name: pkg.name ?? 'unknown', version: pkg.version ?? 'unknown' };
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return null;
+}
+/**
+ * Build the env status response.
+ * @task T4581
+ */
+async function getEnvStatus() {
+    const versionInfo = await parseVersionFile();
+    const pkg = await getPackageInfo(versionInfo?.source);
+    return {
+        mode: versionInfo?.mode ?? 'unknown',
+        source: versionInfo?.source ?? 'unknown',
+        version: pkg?.version ?? versionInfo?.version ?? 'unknown',
+        installed: versionInfo?.installed ?? 'unknown',
+        node: process.version,
+        platform: process.platform,
+        arch: process.arch,
+    };
+}
+/**
+ * Resolve the real path of a binary, following symlinks.
+ * @task T4581
+ */
+async function resolveBinaryPath(name) {
+    const { execFile } = await import('node:child_process');
+    const { promisify } = await import('node:util');
+    const execFileAsync = promisify(execFile);
+    try {
+        const { stdout } = await execFileAsync('which', [name]);
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if the TypeScript source has been compiled (dist/ exists and is newer).
+ * @task T4581
+ */
+async function getCompilationStatus(sourceDir) {
+    const { stat } = await import('node:fs/promises');
+    try {
+        const distStat = await stat(join(sourceDir, 'dist', 'cli', 'index.js'));
+        return `compiled (${distStat.mtime.toISOString()})`;
+    }
+    catch {
+        return 'not compiled';
+    }
+}
+/**
+ * Build the detailed env info response.
+ * @task T4581
+ */
+async function getEnvInfo() {
+    const status = await getEnvStatus();
+    const versionInfo = await parseVersionFile();
+    const pkg = await getPackageInfo(versionInfo?.source);
+    const [cleoBin, cleoMcpBin] = await Promise.all([
+        resolveBinaryPath('cleo'),
+        resolveBinaryPath('cleo-mcp'),
+    ]);
+    const sourceDir = versionInfo?.source ?? 'unknown';
+    const compilationStatus = sourceDir !== 'unknown' && sourceDir !== 'npm'
+        ? await getCompilationStatus(sourceDir)
+        : 'n/a';
+    return {
+        ...status,
+        binaries: {
+            cleo: cleoBin ?? 'not found',
+            'cleo-mcp': cleoMcpBin ?? 'not found',
+        },
+        compilation: compilationStatus,
+        package: {
+            name: pkg?.name ?? 'unknown',
+            version: pkg?.version ?? 'unknown',
+        },
+    };
+}
+/**
+ * Register the env command group.
+ * @task T4581
+ */
+export function registerEnvCommand(program) {
+    const env = program
+        .command('env')
+        .description('Environment and mode inspection');
+    env
+        .command('status', { isDefault: true })
+        .description('Show current environment mode and runtime info')
+        .action(async () => {
+        const result = await getEnvStatus();
+        cliOutput(result, { command: 'env' });
+    });
+    env
+        .command('info')
+        .description('Show detailed environment info including binary paths and compilation status')
+        .action(async () => {
+        const result = await getEnvInfo();
+        cliOutput(result, { command: 'env' });
+    });
+}
+//# sourceMappingURL=env.js.map

package/dist/cli/commands/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../../src/cli/commands/env.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/exists.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CLI exists command - check if a task ID exists.
+ * @task T4454
+ */
+import { Command } from 'commander';
+export declare function registerExistsCommand(program: Command): void;
+//# sourceMappingURL=exists.d.ts.map

package/dist/cli/commands/exists.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exists.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/exists.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwBpC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqD5D"}