project-roadmap-tracking 0.1.0 → 0.2.1

package/dist/commands/update.js

@@ -1,7 +1,11 @@
 import { Args, Command, Flags } from '@oclif/core';
+import { getDefaultConfigRepository } from '../repositories/config.repository.js';
+import { RoadmapRepository } from '../repositories/roadmap.repository.js';
+import errorHandlerService from '../services/error-handler.service.js';
+import taskService from '../services/task.service.js';
 import { readConfigFile } from '../util/read-config.js';
 import { readRoadmapFile } from '../util/read-roadmap.js';
-import { STATUS } from '../util/types.js';
+import { STATUS, TASK_TYPE } from '../util/types.js';
 import { updateTaskInRoadmap } from '../util/update-task.js';
 import { validateTaskID } from '../util/validate-task-id.js';
 import { writeRoadmapFile } from '../util/write-roadmap.js';
@@ -20,6 +24,10 @@ export default class Update extends Command {
             char: 'd',
             description: 'update the dependencies of the task (comma-separated list of task IDs)',
         }),
+        'no-repo': Flags.boolean({
+            default: false,
+            description: 'use legacy direct file I/O instead of repository pattern',
+        }),
         notes: Flags.string({ char: 'n', description: 'append notes to the task' }),
         status: Flags.string({
             char: 's',
@@ -31,6 +39,15 @@ export default class Update extends Command {
             description: 'update whether the task passes tests',
             options: ['true', 'false'],
         }),
+        type: Flags.string({
+            description: 'update the task type (reassigns task ID and cascades to all references)',
+            options: [TASK_TYPE.Bug, TASK_TYPE.Feature, TASK_TYPE.Improvement, TASK_TYPE.Planning, TASK_TYPE.Research],
+        }),
+        verbose: Flags.boolean({
+            char: 'v',
+            default: false,
+            description: 'show detailed error information including stack traces',
+        }),
         // flag with no value (-f, --force)
         // force: Flags.boolean({char: 'f'}),
         // flag with a value (-n, --name=VALUE)
@@ -38,41 +55,69 @@ export default class Update extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(Update);
-        const config = await readConfigFile();
-        const roadmap = await readRoadmapFile(config.path);
-        const updateObject = {};
-        if (flags['clear-notes']) {
-            updateObject.notes = '';
-        }
-        if (flags.notes) {
-            let existingNotes = '';
-            if (!flags['clear-notes']) {
-                const existingTask = roadmap.tasks.find((task) => task.id === args.taskID);
-                existingNotes = existingTask?.notes ? existingTask.notes + '\n' : '';
+        try {
+            // Use repository pattern by default, unless --no-repo flag is set
+            const config = flags['no-repo'] ? await readConfigFile() : await getDefaultConfigRepository().load();
+            const roadmap = flags['no-repo']
+                ? await readRoadmapFile(config.path)
+                : await RoadmapRepository.fromConfig(config).load(config.path);
+            // Handle type update separately since it requires ID reassignment and cascading
+            if (flags.type) {
+                const newType = flags.type;
+                const oldTaskId = args.taskID;
+                const { newTaskId, roadmap: updatedRoadmap } = taskService.updateTaskType(roadmap, oldTaskId, newType);
+                await (flags['no-repo']
+                    ? writeRoadmapFile(config.path, updatedRoadmap)
+                    : RoadmapRepository.fromConfig(config).save(config.path, updatedRoadmap));
+                if (newTaskId === oldTaskId) {
+                    this.log(`Task ${oldTaskId} was already of type ${newType}. No changes made.`);
+                }
+                else {
+                    this.log(`Task ${oldTaskId} has been updated to type ${newType} with new ID ${newTaskId}.`);
+                    this.log(`All task references to ${oldTaskId} have been updated to ${newTaskId}.`);
+                }
+                return;
             }
-            updateObject.notes = existingNotes + flags.notes;
-        }
-        if (flags.status) {
-            updateObject.status = flags.status;
-        }
-        if (flags.tested) {
-            updateObject['passes-tests'] = flags.tested === 'true';
-        }
-        if (flags.deps) {
-            const depsArray = flags.deps.split(',').map((dep) => dep.trim());
-            // checking that each depArray item matches TaskID format
-            for (const dep of depsArray) {
-                try {
-                    validateTaskID(dep);
+            const updateObject = {};
+            if (flags['clear-notes']) {
+                updateObject.notes = '';
+            }
+            if (flags.notes) {
+                let existingNotes = '';
+                if (!flags['clear-notes']) {
+                    const existingTask = roadmap.tasks.find((task) => task.id === args.taskID);
+                    existingNotes = existingTask?.notes ? existingTask.notes + '\n' : '';
                 }
-                catch {
-                    this.error(`Invalid task ID in dependencies: ${dep}`);
+                updateObject.notes = existingNotes + flags.notes;
+            }
+            if (flags.status) {
+                updateObject.status = flags.status;
+            }
+            if (flags.tested) {
+                updateObject['passes-tests'] = flags.tested === 'true';
+            }
+            if (flags.deps) {
+                const depsArray = flags.deps.split(',').map((dep) => dep.trim());
+                // checking that each depArray item matches TaskID format
+                for (const dep of depsArray) {
+                    try {
+                        validateTaskID(dep);
+                    }
+                    catch {
+                        this.error(`Invalid task ID in dependencies: ${dep}`);
+                    }
                 }
+                updateObject['depends-on'] = depsArray;
             }
-            updateObject['depends-on'] = depsArray;
+            const updatedRoadmap = await updateTaskInRoadmap(roadmap, args.taskID, updateObject);
+            await (flags['no-repo']
+                ? writeRoadmapFile(config.path, updatedRoadmap)
+                : RoadmapRepository.fromConfig(config).save(config.path, updatedRoadmap));
+            this.log(`Task ${args.taskID} has been updated.`);
+        }
+        catch (error) {
+            const exitCode = errorHandlerService.handleError(error);
+            this.error(errorHandlerService.formatErrorMessage(error, flags.verbose), { exit: exitCode });
         }
-        const updatedRoadmap = await updateTaskInRoadmap(roadmap, args.taskID, updateObject);
-        await writeRoadmapFile(config.path, updatedRoadmap);
-        this.log(`Task ${args.taskID} updated.`);
     }
 }

package/dist/commands/validate.d.ts

@@ -3,6 +3,9 @@ export default class Validate extends Command {
     static args: {};
     static description: string;
     static examples: string[];
-    static flags: {};
+    static flags: {
+        'no-repo': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
     run(): Promise<void>;
 }

package/dist/commands/validate.js

@@ -1,49 +1,91 @@
-import { Command } from '@oclif/core';
+import { Command, Flags } from '@oclif/core';
 import { readFile } from 'node:fs/promises';
+import { getDefaultConfigRepository } from '../repositories/config.repository.js';
+import { RoadmapRepository } from '../repositories/roadmap.repository.js';
+import displayService from '../services/display.service.js';
+import errorHandlerService from '../services/error-handler.service.js';
+import taskDependencyService from '../services/task-dependency.service.js';
 import { readConfigFile } from '../util/read-config.js';
 import { validateTask } from '../util/validate-task.js';
 export default class Validate extends Command {
     static args = {
     // file: Args.string({description: 'file to read'}),
     };
-    static description = 'describe the command here';
+    static description = 'Validate roadmap structure, task data, and check for circular dependencies';
     static examples = ['<%= config.bin %> <%= command.id %>'];
     static flags = {
-    // flag with no value (-f, --force)
-    // force: Flags.boolean({char: 'f'}),
-    // flag with a value (-n, --name=VALUE)
-    // name: Flags.string({char: 'n', description: 'name to print'}),
+        'no-repo': Flags.boolean({
+            default: false,
+            description: 'use legacy direct file I/O instead of repository pattern',
+        }),
+        // flag with no value (-f, --force)
+        // force: Flags.boolean({char: 'f'}),
+        // flag with a value (-n, --name=VALUE)
+        // name: Flags.string({char: 'n', description: 'name to print'}),
+        verbose: Flags.boolean({
+            char: 'v',
+            default: false,
+            description: 'show detailed error information including stack traces',
+        }),
     };
     async run() {
-        await this.parse(Validate);
-        this.log(`validating roadmap...`);
-        const config = await readConfigFile().catch((error) => {
-            this.error(`failed to read config file: ${error ? error.message : String(error)}`);
-        });
-        const roadmapPath = config.path;
-        const roadmapData = await readFile(roadmapPath, 'utf8');
-        let roadmap;
+        const { flags } = await this.parse(Validate);
         try {
-            roadmap = JSON.parse(roadmapData);
-            this.log(`roadmap at ${roadmapPath} is valid JSON`);
-        }
-        catch (error) {
-            this.error(`roadmap at ${roadmapPath} is not valid JSON: ${error ? error.message : String(error)}`);
-        }
-        if (roadmap.tasks.length === 0) {
-            this.log('roadmap contains no tasks to validate');
-            this.log('roadmap validation complete');
-            return;
-        }
-        for (const task of roadmap.tasks) {
-            try {
-                validateTask(task);
+            this.log(`validating roadmap...`);
+            // Use repository pattern by default, unless --no-repo flag is set
+            const config = flags['no-repo'] ? await readConfigFile() : await getDefaultConfigRepository().load();
+            const roadmapPath = config.path;
+            let roadmap;
+            if (flags['no-repo']) {
+                const roadmapData = await readFile(roadmapPath, 'utf8');
+                try {
+                    roadmap = JSON.parse(roadmapData);
+                    this.log(`roadmap at ${roadmapPath} is valid JSON`);
+                }
+                catch (error) {
+                    this.error(`roadmap at ${roadmapPath} is not valid JSON: ${error ? error.message : String(error)}`);
+                }
+            }
+            else {
+                try {
+                    roadmap = await RoadmapRepository.fromConfig(config).load(roadmapPath);
+                    this.log(`roadmap at ${roadmapPath} is valid JSON`);
+                }
+                catch (error) {
+                    this.error(`roadmap at ${roadmapPath} is not valid JSON: ${error ? error.message : String(error)}`);
+                }
             }
-            catch (error) {
-                this.error(`task ID ${task.id} is invalid: ${error ? error.message : String(error)}`);
+            if (roadmap.tasks.length === 0) {
+                this.log('roadmap contains no tasks to validate');
+                this.log('roadmap validation complete');
+                return;
             }
+            for (const task of roadmap.tasks) {
+                try {
+                    validateTask(task);
+                }
+                catch (error) {
+                    this.error(`task ID ${task.id} is invalid: ${error ? error.message : String(error)}`);
+                }
+            }
+            // this.log(roadmap.tasks.length > 1 ? `all ${roadmap.tasks.length} tasks are valid` : `1 task is valid`)
+            // Validate dependencies (including circular dependency check)
+            this.log(`validating task dependencies...`);
+            const dependencyErrors = taskDependencyService.validateDependencies(roadmap);
+            if (dependencyErrors.length > 0) {
+                const errorLines = displayService.formatValidationErrors(dependencyErrors);
+                for (const line of errorLines) {
+                    this.log(line);
+                }
+                // Exit with error if any dependency errors found
+                this.error('Dependency validation failed');
+            }
+            this.log(`all task dependencies are valid`);
+            this.log(`roadmap validation complete`);
+        }
+        catch (error) {
+            const exitCode = errorHandlerService.handleError(error);
+            this.error(errorHandlerService.formatErrorMessage(error, flags.verbose), { exit: exitCode });
         }
-        this.log(roadmap.tasks.length > 1 ? `all ${roadmap.tasks.length} tasks are valid` : `1 task is valid`);
-        this.log(`roadmap validation complete`);
     }
 }

package/dist/errors/base.error.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Error codes for all PRT errors
+ */
+export declare enum PrtErrorCode {
+    PRT_FILE_CONFIG_NOT_FOUND = "PRT_FILE_CONFIG_NOT_FOUND",
+    PRT_FILE_ROADMAP_NOT_FOUND = "PRT_FILE_ROADMAP_NOT_FOUND",
+    PRT_TASK_ID_INVALID = "PRT_TASK_ID_INVALID",
+    PRT_TASK_INVALID = "PRT_TASK_INVALID",
+    PRT_TASK_NOT_FOUND = "PRT_TASK_NOT_FOUND",
+    PRT_UNKNOWN = "PRT_UNKNOWN",
+    PRT_VALIDATION_CIRCULAR_DEPENDENCY = "PRT_VALIDATION_CIRCULAR_DEPENDENCY",
+    PRT_VALIDATION_FAILED = "PRT_VALIDATION_FAILED"
+}
+/**
+ * Base error class for all PRT custom errors
+ */
+export declare class PrtError extends Error {
+    readonly code: PrtErrorCode;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, code?: PrtErrorCode, context?: Record<string, unknown>);
+}

package/dist/errors/base.error.js

@@ -0,0 +1,35 @@
+/**
+ * Error codes for all PRT errors
+ */
+export var PrtErrorCode;
+(function (PrtErrorCode) {
+    PrtErrorCode["PRT_FILE_CONFIG_NOT_FOUND"] = "PRT_FILE_CONFIG_NOT_FOUND";
+    // File errors
+    PrtErrorCode["PRT_FILE_ROADMAP_NOT_FOUND"] = "PRT_FILE_ROADMAP_NOT_FOUND";
+    PrtErrorCode["PRT_TASK_ID_INVALID"] = "PRT_TASK_ID_INVALID";
+    PrtErrorCode["PRT_TASK_INVALID"] = "PRT_TASK_INVALID";
+    // Task errors
+    PrtErrorCode["PRT_TASK_NOT_FOUND"] = "PRT_TASK_NOT_FOUND";
+    // Generic
+    PrtErrorCode["PRT_UNKNOWN"] = "PRT_UNKNOWN";
+    PrtErrorCode["PRT_VALIDATION_CIRCULAR_DEPENDENCY"] = "PRT_VALIDATION_CIRCULAR_DEPENDENCY";
+    // Validation errors
+    PrtErrorCode["PRT_VALIDATION_FAILED"] = "PRT_VALIDATION_FAILED";
+})(PrtErrorCode || (PrtErrorCode = {}));
+/**
+ * Base error class for all PRT custom errors
+ */
+export class PrtError extends Error {
+    code;
+    context;
+    constructor(message, code = PrtErrorCode.PRT_UNKNOWN, context) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.context = context;
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}

package/dist/errors/circular-dependency.error.d.ts

@@ -0,0 +1,8 @@
+import type { TaskID } from '../util/types.js';
+import { PrtError } from './base.error.js';
+/**
+ * Error thrown when circular dependencies are detected in tasks
+ */
+export declare class CircularDependencyError extends PrtError {
+    constructor(cycle: TaskID[], message?: string);
+}

package/dist/errors/circular-dependency.error.js

@@ -0,0 +1,13 @@
+import { PrtError, PrtErrorCode } from './base.error.js';
+/**
+ * Error thrown when circular dependencies are detected in tasks
+ */
+export class CircularDependencyError extends PrtError {
+    constructor(cycle, message) {
+        const defaultMessage = `Circular dependency detected: ${cycle.join(' -> ')} -> ${cycle[0]}`;
+        super(message || defaultMessage, PrtErrorCode.PRT_VALIDATION_CIRCULAR_DEPENDENCY, {
+            cycle,
+            cycleLength: cycle.length,
+        });
+    }
+}

package/dist/errors/config-not-found.error.d.ts

@@ -0,0 +1,7 @@
+import { PrtError } from './base.error.js';
+/**
+ * Error thrown when a config file (.prtrc.json) cannot be found
+ */
+export declare class ConfigNotFoundError extends PrtError {
+    constructor(filePath?: string, cause?: Error);
+}

package/dist/errors/config-not-found.error.js

@@ -0,0 +1,12 @@
+import { PrtError, PrtErrorCode } from './base.error.js';
+/**
+ * Error thrown when a config file (.prtrc.json) cannot be found
+ */
+export class ConfigNotFoundError extends PrtError {
+    constructor(filePath = '.prtrc.json', cause) {
+        super(`Config file not found: ${filePath}`, PrtErrorCode.PRT_FILE_CONFIG_NOT_FOUND, {
+            filePath,
+            ...(cause && { cause: cause.message }),
+        });
+    }
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,16 @@
+export { PrtError, PrtErrorCode } from './base.error.js';
+export { CircularDependencyError } from './circular-dependency.error.js';
+export { ConfigNotFoundError } from './config-not-found.error.js';
+export { InvalidTaskError } from './invalid-task.error.js';
+export { RoadmapNotFoundError } from './roadmap-not-found.error.js';
+export { TaskNotFoundError } from './task-not-found.error.js';
+export { ValidationError, type ValidationErrorDetail } from './validation.error.js';
+import { PrtError, PrtErrorCode } from './base.error.js';
+/**
+ * Type guard to check if an error is a PrtError
+ */
+export declare function isPrtError(error: unknown): error is PrtError;
+/**
+ * Get the error code from an error, or null if not a PrtError
+ */
+export declare function getErrorCode(error: unknown): null | PrtErrorCode;

package/dist/errors/index.js

@@ -0,0 +1,26 @@
+// Base error and error codes
+export { PrtError, PrtErrorCode } from './base.error.js';
+export { CircularDependencyError } from './circular-dependency.error.js';
+// Specific error classes
+export { ConfigNotFoundError } from './config-not-found.error.js';
+export { InvalidTaskError } from './invalid-task.error.js';
+export { RoadmapNotFoundError } from './roadmap-not-found.error.js';
+export { TaskNotFoundError } from './task-not-found.error.js';
+export { ValidationError } from './validation.error.js';
+// Import for type guards
+import { PrtError } from './base.error.js';
+/**
+ * Type guard to check if an error is a PrtError
+ */
+export function isPrtError(error) {
+    return error instanceof PrtError;
+}
+/**
+ * Get the error code from an error, or null if not a PrtError
+ */
+export function getErrorCode(error) {
+    if (isPrtError(error)) {
+        return error.code;
+    }
+    return null;
+}

package/dist/errors/invalid-task.error.d.ts

@@ -0,0 +1,7 @@
+import { PrtError } from './base.error.js';
+/**
+ * Error thrown when a task fails validation
+ */
+export declare class InvalidTaskError extends PrtError {
+    constructor(message: string, taskId?: string, validationField?: string);
+}

package/dist/errors/invalid-task.error.js

@@ -0,0 +1,12 @@
+import { PrtError, PrtErrorCode } from './base.error.js';
+/**
+ * Error thrown when a task fails validation
+ */
+export class InvalidTaskError extends PrtError {
+    constructor(message, taskId, validationField) {
+        super(message, PrtErrorCode.PRT_TASK_INVALID, {
+            ...(taskId && { taskId }),
+            ...(validationField && { validationField }),
+        });
+    }
+}

package/dist/errors/roadmap-not-found.error.d.ts

@@ -0,0 +1,7 @@
+import { PrtError } from './base.error.js';
+/**
+ * Error thrown when a roadmap file cannot be found
+ */
+export declare class RoadmapNotFoundError extends PrtError {
+    constructor(filePath: string, cause?: Error);
+}

package/dist/errors/roadmap-not-found.error.js

@@ -0,0 +1,12 @@
+import { PrtError, PrtErrorCode } from './base.error.js';
+/**
+ * Error thrown when a roadmap file cannot be found
+ */
+export class RoadmapNotFoundError extends PrtError {
+    constructor(filePath, cause) {
+        super(`Roadmap file not found: ${filePath}`, PrtErrorCode.PRT_FILE_ROADMAP_NOT_FOUND, {
+            filePath,
+            ...(cause && { cause: cause.message }),
+        });
+    }
+}

package/dist/errors/task-not-found.error.d.ts

@@ -0,0 +1,7 @@
+import { PrtError } from './base.error.js';
+/**
+ * Error thrown when a task cannot be found by its ID
+ */
+export declare class TaskNotFoundError extends PrtError {
+    constructor(taskId: string, roadmapPath?: string);
+}

package/dist/errors/task-not-found.error.js

@@ -0,0 +1,12 @@
+import { PrtError, PrtErrorCode } from './base.error.js';
+/**
+ * Error thrown when a task cannot be found by its ID
+ */
+export class TaskNotFoundError extends PrtError {
+    constructor(taskId, roadmapPath) {
+        super(`Task not found: ${taskId}`, PrtErrorCode.PRT_TASK_NOT_FOUND, {
+            taskId,
+            ...(roadmapPath && { roadmapPath }),
+        });
+    }
+}

package/dist/errors/validation.error.d.ts

@@ -0,0 +1,16 @@
+import { PrtError } from './base.error.js';
+/**
+ * Details about a single validation error
+ */
+export interface ValidationErrorDetail {
+    field?: string;
+    message: string;
+    taskId?: string;
+    type: 'circular-dependency' | 'duplicate-id' | 'invalid-reference' | 'invalid-value' | 'missing-field' | 'missing-task' | 'structure' | 'task';
+}
+/**
+ * Error thrown when validation fails with multiple issues
+ */
+export declare class ValidationError extends PrtError {
+    constructor(errors: ValidationErrorDetail[]);
+}

package/dist/errors/validation.error.js

@@ -0,0 +1,16 @@
+import { PrtError, PrtErrorCode } from './base.error.js';
+/**
+ * Error thrown when validation fails with multiple issues
+ */
+export class ValidationError extends PrtError {
+    constructor(errors) {
+        const errorCount = errors.length;
+        const errorTypes = [...new Set(errors.map((e) => e.type))];
+        const message = `Validation failed with ${errorCount} error${errorCount === 1 ? '' : 's'}`;
+        super(message, PrtErrorCode.PRT_VALIDATION_FAILED, {
+            errorCount,
+            errors,
+            errorTypes,
+        });
+    }
+}

package/dist/repositories/config.repository.d.ts

@@ -0,0 +1,76 @@
+import { Config } from '../util/types.js';
+/**
+ * Configuration for ConfigRepository
+ */
+export interface ConfigRepositoryConfig {
+    cacheEnabled?: boolean;
+    searchPaths?: string[];
+}
+/**
+ * ConfigRepository provides caching, validation, and inheritance for config files.
+ * Features:
+ * - In-memory cache with mtime-based invalidation
+ * - Multi-level config inheritance (project → user → global)
+ * - JSON schema validation using schemas/config/v1.1.json
+ * - Shallow merge strategy for inherited configs
+ */
+export declare class ConfigRepository {
+    private static configSchema;
+    private cache;
+    private config;
+    private validateSchema;
+    constructor(config?: ConfigRepositoryConfig);
+    /**
+     * Get the currently cached config (if any)
+     */
+    getCachedConfig(): Config | null;
+    /**
+     * Clear the in-memory cache
+     */
+    invalidateCache(): void;
+    /**
+     * Load config with caching and inheritance
+     * Searches for config files in order: project → user → global
+     * Merges configs with shallow merge (project overrides user overrides global)
+     */
+    load(): Promise<Config>;
+    /**
+     * Reload config from disk, bypassing cache
+     */
+    reload(): Promise<Config>;
+    /**
+     * Get default config file search paths
+     * Order: project → user → global
+     */
+    private getDefaultSearchPaths;
+    /**
+     * Check if cached config is still valid by comparing mtime
+     */
+    private isCacheValid;
+    /**
+     * Load all available configs from search paths
+     * Returns array in order of precedence (project first, global last)
+     */
+    private loadAllConfigs;
+    /**
+     * Load config from a specific path
+     */
+    private loadConfigFromPath;
+    /**
+     * Merge configs using shallow merge strategy
+     * Project-level config takes precedence over user-level over global-level
+     */
+    private mergeConfigs;
+    /**
+     * Validate config against JSON schema
+     */
+    private validateConfig;
+}
+/**
+ * Get the default config repository instance
+ */
+export declare function getDefaultConfigRepository(): ConfigRepository;
+/**
+ * Reset the default config repository instance (useful for testing)
+ */
+export declare function resetDefaultConfigRepository(): void;