@cleocode/cleo 2026.2.5

package/dist/core/validation/doctor/project-cache.js

@@ -0,0 +1,164 @@
+/**
+ * Project validation caching - ported from lib/validation/doctor-project-cache.sh
+ *
+ * Caches validation results per project with TTL-based invalidation
+ * and file hash comparison for cache freshness.
+ *
+ * @task T4525
+ * @epic T4454
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+// ============================================================================
+// Constants
+// ============================================================================
+export const CACHE_VERSION = '1.0.0';
+export const CACHE_TTL_SECONDS = 300; // 5 minutes
+const CACHE_FILE = 'doctor-project-cache.json';
+// ============================================================================
+// Cache Operations
+// ============================================================================
+/**
+ * Get cache file path.
+ * @task T4525
+ */
+export function getCacheFilePath(cleoHome) {
+    const home = cleoHome ?? join(homedir(), '.cleo');
+    return join(home, CACHE_FILE);
+}
+/**
+ * Initialize empty cache file.
+ * @task T4525
+ */
+export function initCacheFile(cacheFile) {
+    const cache = {
+        version: CACHE_VERSION,
+        lastUpdated: new Date().toISOString(),
+        projects: {},
+    };
+    const dir = dirname(cacheFile);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(cacheFile, JSON.stringify(cache, null, 2));
+    return cache;
+}
+/**
+ * Load cache file or return null if missing/invalid.
+ * @task T4525
+ */
+export function loadCache(cacheFile) {
+    if (!existsSync(cacheFile))
+        return null;
+    try {
+        const content = readFileSync(cacheFile, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get file hash for cache invalidation.
+ * @task T4525
+ */
+export function getFileHash(filePath) {
+    if (!existsSync(filePath))
+        return '';
+    try {
+        const content = readFileSync(filePath);
+        return createHash('sha256').update(content).digest('hex');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Check if project validation is cached and valid.
+ * Returns the cache entry if valid, null if cache miss.
+ * @task T4525
+ */
+export function getCachedValidation(projectHash, projectPath, cacheFile) {
+    const cachePath = cacheFile ?? getCacheFilePath();
+    const cache = loadCache(cachePath);
+    if (!cache)
+        return null;
+    const entry = cache.projects[projectHash];
+    if (!entry)
+        return null;
+    // Verify path matches
+    if (entry.path !== projectPath)
+        return null;
+    // Check TTL
+    const lastValidated = new Date(entry.lastValidated).getTime();
+    const now = Date.now();
+    const age = (now - lastValidated) / 1000;
+    if (age > (entry.ttl || CACHE_TTL_SECONDS))
+        return null;
+    // Check file hashes for invalidation
+    const currentTodoHash = getFileHash(join(projectPath, '.cleo', 'todo.json'));
+    const currentConfigHash = getFileHash(join(projectPath, '.cleo', 'config.json'));
+    if (currentTodoHash !== (entry.fileHashes['todo.json'] ?? ''))
+        return null;
+    if (currentConfigHash !== (entry.fileHashes['config.json'] ?? ''))
+        return null;
+    return entry;
+}
+/**
+ * Cache project validation results.
+ * @task T4525
+ */
+export function cacheValidationResult(projectHash, projectPath, validationStatus, issues = [], schemaVersions = {}, cacheFile) {
+    const cachePath = cacheFile ?? getCacheFilePath();
+    let cache = loadCache(cachePath);
+    if (!cache) {
+        cache = initCacheFile(cachePath);
+    }
+    const todoHash = getFileHash(join(projectPath, '.cleo', 'todo.json'));
+    const configHash = getFileHash(join(projectPath, '.cleo', 'config.json'));
+    const archiveHash = getFileHash(join(projectPath, '.cleo', 'todo-archive.json'));
+    const logHash = getFileHash(join(projectPath, '.cleo', 'todo-log.jsonl'));
+    const timestamp = new Date().toISOString();
+    cache.projects[projectHash] = {
+        path: projectPath,
+        lastValidated: timestamp,
+        validationStatus,
+        schemaVersions,
+        fileHashes: {
+            'todo.json': todoHash,
+            'config.json': configHash,
+            'todo-archive.json': archiveHash,
+            'todo-log.jsonl': logHash,
+        },
+        issues,
+        ttl: CACHE_TTL_SECONDS,
+    };
+    cache.lastUpdated = timestamp;
+    writeFileSync(cachePath, JSON.stringify(cache, null, 2));
+}
+/**
+ * Clear cache for a specific project.
+ * @task T4525
+ */
+export function clearProjectCache(projectHash, cacheFile) {
+    const cachePath = cacheFile ?? getCacheFilePath();
+    const cache = loadCache(cachePath);
+    if (!cache)
+        return;
+    delete cache.projects[projectHash];
+    writeFileSync(cachePath, JSON.stringify(cache, null, 2));
+}
+/**
+ * Clear entire cache.
+ * @task T4525
+ */
+export function clearEntireCache(cacheFile) {
+    const cachePath = cacheFile ?? getCacheFilePath();
+    if (existsSync(cachePath)) {
+        unlinkSync(cachePath);
+    }
+    initCacheFile(cachePath);
+}
+//# sourceMappingURL=project-cache.js.map

package/dist/core/validation/doctor/project-cache.js.map

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

package/dist/core/validation/doctor/utils.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Doctor utility functions - ported from lib/validation/doctor-utils.sh
+ *
+ * Functions for project categorization, health summaries, journey stage
+ * detection, and guidance generation.
+ *
+ * @task T4525
+ * @epic T4454
+ */
+export interface ProjectDetail {
+    name: string;
+    path: string;
+    status: 'healthy' | 'warning' | 'failed' | 'orphaned';
+    issues?: string[];
+    isTemp: boolean;
+    isOrphaned?: boolean;
+    reason?: string;
+}
+export interface CategorizedProjects {
+    active: ProjectDetail[];
+    temp: ProjectDetail[];
+    orphaned: ProjectDetail[];
+}
+export type UserJourneyStage = 'new-user' | 'cleanup-needed' | 'setup-agents-needed' | 'maintenance-mode';
+/**
+ * Check if a project path is a temporary/test directory.
+ * @task T4525
+ */
+export declare function isTempProject(path: string): boolean;
+/**
+ * Filter projects into categories: active, temp, orphaned.
+ * @task T4525
+ */
+export declare function categorizeProjects(projects: ProjectDetail[]): CategorizedProjects;
+/**
+ * Get human-readable project category name.
+ * @task T4525
+ */
+export declare function getProjectCategoryName(category: 'active' | 'temp' | 'orphaned'): string;
+export interface HealthSummary {
+    total: number;
+    healthy: number;
+    warnings: number;
+    failed: number;
+    orphaned: number;
+    temp: number;
+}
+/**
+ * Format project health summary for display.
+ * @task T4525
+ */
+export declare function formatProjectHealthSummary(summary: HealthSummary): string;
+/**
+ * Get actionable guidance for project issues.
+ * @task T4525
+ */
+export declare function getProjectGuidance(activeFailed: number, activeWarnings: number, tempCount: number, orphanedCount: number): string[];
+/**
+ * Check user journey stage based on system state.
+ * @task T4525
+ */
+export declare function getUserJourneyStage(hasProjects: boolean, tempProjectCount: number, agentConfigsOk: boolean): UserJourneyStage;
+/**
+ * Get journey-specific guidance text.
+ * @task T4525
+ */
+export declare function getJourneyGuidance(stage: UserJourneyStage): string[];
+//# sourceMappingURL=utils.d.ts.map

package/dist/core/validation/doctor/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../src/core/validation/doctor/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;IACtD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,gBAAgB,GAChB,qBAAqB,GACrB,kBAAkB,CAAC;AAevB;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGnD;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,mBAAmB,CAgBjF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,UAAU,GACvC,MAAM,CAMR;AAMD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAqBzE;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,MAAM,EAAE,CAwBV;AAMD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,OAAO,EACpB,gBAAgB,EAAE,MAAM,EACxB,cAAc,EAAE,OAAO,GACtB,gBAAgB,CAKlB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,EAAE,CA2BpE"}

package/dist/core/validation/doctor/utils.js

@@ -0,0 +1,162 @@
+/**
+ * Doctor utility functions - ported from lib/validation/doctor-utils.sh
+ *
+ * Functions for project categorization, health summaries, journey stage
+ * detection, and guidance generation.
+ *
+ * @task T4525
+ * @epic T4454
+ */
+// ============================================================================
+// Temp Project Detection
+// ============================================================================
+const TEMP_PATTERNS = [
+    '/.temp/',
+    '/tmp/',
+    '/bats-run-',
+    '/.tmp/',
+    '/tmp.',
+    '/bats.',
+];
+/**
+ * Check if a project path is a temporary/test directory.
+ * @task T4525
+ */
+export function isTempProject(path) {
+    return TEMP_PATTERNS.some(pattern => path.includes(pattern)) ||
+        (path.includes('/test/') && (path.includes('bats-run-') || path.includes('test-')));
+}
+// ============================================================================
+// Project Categorization
+// ============================================================================
+/**
+ * Filter projects into categories: active, temp, orphaned.
+ * @task T4525
+ */
+export function categorizeProjects(projects) {
+    const active = [];
+    const temp = [];
+    const orphaned = [];
+    for (const project of projects) {
+        if (project.status === 'orphaned' || project.isOrphaned) {
+            orphaned.push(project);
+        }
+        else if (isTempProject(project.path)) {
+            temp.push(project);
+        }
+        else {
+            active.push(project);
+        }
+    }
+    return { active, temp, orphaned };
+}
+/**
+ * Get human-readable project category name.
+ * @task T4525
+ */
+export function getProjectCategoryName(category) {
+    switch (category) {
+        case 'active': return 'Active Projects';
+        case 'temp': return 'Temporary/Test Projects';
+        case 'orphaned': return 'Orphaned Projects';
+    }
+}
+/**
+ * Format project health summary for display.
+ * @task T4525
+ */
+export function formatProjectHealthSummary(summary) {
+    const lines = ['Project Health Summary:'];
+    lines.push(`  Total Projects: ${summary.total}`);
+    if (summary.healthy > 0) {
+        lines.push(`  Healthy Projects: ${summary.healthy}`);
+    }
+    if (summary.warnings > 0) {
+        lines.push(`  Projects with Warnings: ${summary.warnings}`);
+    }
+    if (summary.failed > 0) {
+        lines.push(`  Failed Projects: ${summary.failed}`);
+    }
+    if (summary.temp > 0) {
+        lines.push(`  Temporary Projects: ${summary.temp} (test artifacts)`);
+    }
+    if (summary.orphaned > 0) {
+        lines.push(`  Orphaned Projects: ${summary.orphaned} (directories missing)`);
+    }
+    return lines.join('\n');
+}
+// ============================================================================
+// Guidance
+// ============================================================================
+/**
+ * Get actionable guidance for project issues.
+ * @task T4525
+ */
+export function getProjectGuidance(activeFailed, activeWarnings, tempCount, orphanedCount) {
+    const guidance = [];
+    if (activeFailed > 0) {
+        guidance.push(`${activeFailed} active project(s) failed validation - run 'cleo upgrade' in affected projects`);
+    }
+    if (activeWarnings > 0) {
+        guidance.push(`${activeWarnings} active project(s) have warnings - consider updating schemas`);
+    }
+    if (tempCount > 10) {
+        guidance.push(`Many temporary projects detected - run 'cleo doctor --clean-temp' to clean up`);
+    }
+    if (orphanedCount > 5) {
+        guidance.push(`${orphanedCount} orphaned projects - run 'cleo doctor --prune' to remove`);
+    }
+    if (guidance.length === 0) {
+        guidance.push('All active projects are healthy');
+    }
+    return guidance;
+}
+// ============================================================================
+// User Journey
+// ============================================================================
+/**
+ * Check user journey stage based on system state.
+ * @task T4525
+ */
+export function getUserJourneyStage(hasProjects, tempProjectCount, agentConfigsOk) {
+    if (!hasProjects)
+        return 'new-user';
+    if (tempProjectCount > 10)
+        return 'cleanup-needed';
+    if (!agentConfigsOk)
+        return 'setup-agents-needed';
+    return 'maintenance-mode';
+}
+/**
+ * Get journey-specific guidance text.
+ * @task T4525
+ */
+export function getJourneyGuidance(stage) {
+    switch (stage) {
+        case 'new-user':
+            return [
+                'NEW USER SETUP:',
+                '  1. Create your first project: cleo init my-project',
+                '  2. Add tasks: cleo add "Setup development environment"',
+                '  3. Configure AI assistants: cleo setup-agents',
+            ];
+        case 'cleanup-needed':
+            return [
+                'CLEANUP NEEDED:',
+                '  You have many temporary projects from testing',
+                "  Run 'cleo doctor --clean-temp' to clean up",
+            ];
+        case 'setup-agents-needed':
+            return [
+                'AI ASSISTANT SETUP:',
+                '  Your AI assistants need CLEO configuration',
+                "  Run 'cleo setup-agents' to inject task management docs",
+            ];
+        case 'maintenance-mode':
+            return [
+                'MAINTENANCE MODE:',
+                '  System is healthy - check individual project issues above',
+            ];
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/core/validation/doctor/utils.js.map

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

package/dist/core/validation/engine.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Core validation engine - ported from lib/validation/validation.sh
+ *
+ * Provides schema validation, task field validation, status transitions,
+ * timestamp sanity checks, ID uniqueness, phase validation, circular
+ * dependency detection, and comprehensive file validation.
+ *
+ * @task T4523
+ * @epic T4454
+ */
+export declare const VALID_STATUSES: readonly ["pending", "active", "done", "blocked", "cancelled"];
+export type TaskStatus = typeof VALID_STATUSES[number];
+export declare const VALID_OPERATIONS: readonly ["create", "update", "complete", "archive", "restore", "delete", "validate", "backup"];
+export declare const VALID_PHASE_STATUSES: readonly ["pending", "active", "completed"];
+/** Field length limits matching the Bash implementation. */
+export declare const FIELD_LIMITS: {
+    readonly MAX_TITLE_LENGTH: 120;
+    readonly MAX_DESCRIPTION_LENGTH: 2000;
+    readonly MAX_NOTE_LENGTH: 5000;
+    readonly MAX_BLOCKED_BY_LENGTH: 300;
+    readonly MAX_SESSION_NOTE_LENGTH: 2500;
+    readonly MIN_CANCEL_REASON_LENGTH: 5;
+    readonly MAX_CANCEL_REASON_LENGTH: 300;
+};
+/** Validation result exit codes. */
+export declare const VAL_SUCCESS = 0;
+export declare const VAL_SCHEMA_ERROR = 1;
+export declare const VAL_SEMANTIC_ERROR = 2;
+export declare const VAL_BOTH_ERRORS = 3;
+export interface ValidationError {
+    field?: string;
+    message: string;
+    severity: 'error' | 'warning';
+    fix?: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+}
+/**
+ * Sanitize a file path for safe shell usage.
+ * Prevents command injection via malicious file names.
+ * @task T4523
+ */
+export declare function sanitizeFilePath(path: string): string;
+/**
+ * Validate a task title.
+ * Checks for emptiness, newlines, invisible characters, control chars, and length.
+ * @task T4523
+ */
+export declare function validateTitle(title: string): ValidationResult;
+/** @task T4523 */
+export declare function validateDescription(desc: string): ValidationResult;
+/** @task T4523 */
+export declare function validateNote(note: string): ValidationResult;
+/** @task T4523 */
+export declare function validateBlockedBy(reason: string): ValidationResult;
+/** @task T4523 */
+export declare function validateSessionNote(note: string): ValidationResult;
+/**
+ * Validate a cancellation reason.
+ * @task T4523
+ */
+export declare function validateCancelReason(reason: string): ValidationResult;
+/**
+ * Validate that a status transition is allowed.
+ * @task T4523
+ */
+export declare function validateStatusTransition(oldStatus: TaskStatus, newStatus: TaskStatus): ValidationResult;
+/**
+ * Check if a status string is valid.
+ * @task T4523
+ */
+export declare function isValidStatus(status: string): status is TaskStatus;
+/**
+ * Check timestamp format and sanity.
+ * @task T4523
+ */
+export declare function checkTimestampSanity(createdAt: string, completedAt?: string): ValidationResult;
+/**
+ * Check if an update contains only metadata fields (safe for done tasks).
+ * @task T4523
+ */
+export declare function isMetadataOnlyUpdate(fields: string[]): boolean;
+/**
+ * Deduplicate and normalize labels.
+ * @task T4523
+ */
+export declare function normalizeLabels(labels: string): string;
+export interface Task {
+    id?: string;
+    content?: string;
+    title?: string;
+    status?: string;
+    activeForm?: string;
+    created_at?: string;
+    completed_at?: string;
+    parentId?: string | null;
+    type?: string;
+    depends?: string[];
+    cancelledAt?: string;
+    cancellationReason?: string;
+    [key: string]: unknown;
+}
+export interface TodoFile {
+    tasks: Task[];
+    project?: {
+        currentPhase?: string;
+        phases?: Record<string, {
+            status?: string;
+            startedAt?: string;
+            completedAt?: string;
+        }>;
+    };
+    [key: string]: unknown;
+}
+export interface ArchiveFile {
+    archived_tasks: Task[];
+    [key: string]: unknown;
+}
+/**
+ * Check ID uniqueness within and across files.
+ * @task T4523
+ */
+export declare function checkIdUniqueness(todoFile: TodoFile, archiveFile?: ArchiveFile): ValidationResult;
+/**
+ * Validate a single task object.
+ * @task T4523
+ */
+export declare function validateTask(task: Task): ValidationResult;
+/**
+ * Check for circular dependencies using DFS.
+ * @task T4523
+ */
+export declare function validateNoCircularDeps(tasks: Task[], taskId: string, newDeps: string[]): ValidationResult;
+/**
+ * Validate only one phase is active.
+ * @task T4523
+ */
+export declare function validateSingleActivePhase(todoFile: TodoFile): ValidationResult;
+/**
+ * Validate currentPhase matches an active phase.
+ * @task T4523
+ */
+export declare function validateCurrentPhaseConsistency(todoFile: TodoFile): ValidationResult;
+/**
+ * Validate phase timestamp ordering.
+ * @task T4523
+ */
+export declare function validatePhaseTimestamps(todoFile: TodoFile): ValidationResult;
+/**
+ * Validate phase status requirements (e.g., active phases must have startedAt).
+ * @task T4523
+ */
+export declare function validatePhaseStatusRequirements(todoFile: TodoFile): ValidationResult;
+export interface ComprehensiveValidationResult {
+    schemaErrors: number;
+    semanticErrors: number;
+    exitCode: number;
+    checks: Array<{
+        name: string;
+        passed: boolean;
+        message: string;
+    }>;
+}
+/**
+ * Run all validation checks on a TodoFile.
+ * @task T4523
+ */
+export declare function validateAll(todoFile: TodoFile, archiveFile?: ArchiveFile): ComprehensiveValidationResult;
+//# sourceMappingURL=engine.d.ts.map

package/dist/core/validation/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/core/validation/engine.ts"],"names":[],"mappings":"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"}