project-roadmap-tracking 0.2.5 → 0.2.7

package/README.md

@@ -49,6 +49,9 @@ prt list -p high
 # Show task details
 prt show F-001
 
+# Show task details with dependencies
+prt show F-001 -d
+
 # Update task status
 prt update F-001 --status=in-progress
 
@@ -137,6 +140,7 @@ IDs are auto-generated sequentially per task type.
 * [Add a new feature](#add-a-new-feature)
 * [List all high-priority tasks](#list-all-high-priority-tasks)
 * [Show task details](#show-task-details)
+* [Show task details with dependencies](#show-task-details-with-dependencies)
 * [Update task status](#update-task-status)
 * [Complete a task](#complete-a-task)
 * [Validate roadmap integrity](#validate-roadmap-integrity)
@@ -156,6 +160,10 @@ IDs are auto-generated sequentially per task type.
 * [Run a specific test file](#run-a-specific-test-file)
 * [Generate coverage report](#generate-coverage-report)
 * [View coverage summary](#view-coverage-summary)
+* [1. Update version](#1-update-version)
+* [2. Build and package](#2-build-and-package)
+* [3. Publish to npm](#3-publish-to-npm)
+* [4. Create GitHub release](#4-create-github-release)
 <!-- tocstop -->
 
 # Usage
@@ -166,7 +174,7 @@ $ npm install -g project-roadmap-tracking
 $ prt COMMAND
 running command...
 $ prt (--version)
-project-roadmap-tracking/0.2.5 linux-x64 node-v25.4.0
+project-roadmap-tracking/0.2.7 linux-x64 node-v25.4.0
 $ prt --help [COMMAND]
 USAGE
   $ prt COMMAND
@@ -228,7 +236,7 @@ EXAMPLES
   $ prt add
 ```
 
-_See code: [src/commands/add.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.5/src/commands/add.ts)_
+_See code: [src/commands/add.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.7/src/commands/add.ts)_
 
 ## `prt complete TASKID`
 
@@ -253,7 +261,7 @@ EXAMPLES
   $ prt complete F-001 --tests
 ```
 
-_See code: [src/commands/complete.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.5/src/commands/complete.ts)_
+_See code: [src/commands/complete.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.7/src/commands/complete.ts)_
 
 ## `prt help [COMMAND]`
 
@@ -300,7 +308,7 @@ EXAMPLES
   $ prt init [path/to/directory]
 ```
 
-_See code: [src/commands/init.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.5/src/commands/init.ts)_
+_See code: [src/commands/init.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.7/src/commands/init.ts)_
 
 ## `prt list`
 
@@ -329,7 +337,7 @@ EXAMPLES
   $ prt list -p=h --incomplete --sort=createdAt
 ```
 
-_See code: [src/commands/list.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.5/src/commands/list.ts)_
+_See code: [src/commands/list.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.7/src/commands/list.ts)_
 
 ## `prt pass-test TASKID`
 
@@ -353,7 +361,7 @@ EXAMPLES
   $ prt pass-test F-001
 ```
 
-_See code: [src/commands/pass-test.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.5/src/commands/pass-test.ts)_
+_See code: [src/commands/pass-test.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.7/src/commands/pass-test.ts)_
 
 ## `prt plugins`
 
@@ -651,14 +659,15 @@ show details of a specific task in the project roadmap
 
 ```
 USAGE
-  $ prt show TASK [--no-repo] [-v]
+  $ prt show TASK [--no-repo] [-d] [-v]
 
 ARGUMENTS
   TASK  task ID to show
 
 FLAGS
-  -v, --verbose  show detailed error information including stack traces
-      --no-repo  use legacy direct file I/O instead of repository pattern
+  -d, --show-dependencies  show task dependencies
+  -v, --verbose            show detailed error information including stack traces
+      --no-repo            use legacy direct file I/O instead of repository pattern
 
 DESCRIPTION
   show details of a specific task in the project roadmap
@@ -667,7 +676,7 @@ EXAMPLES
   $ prt show F-001
 ```
 
-_See code: [src/commands/show.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.5/src/commands/show.ts)_
+_See code: [src/commands/show.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.7/src/commands/show.ts)_
 
 ## `prt update TASKID`
 
@@ -703,7 +712,7 @@ EXAMPLES
   $ prt update F-002 --deps="F-001" --clear-notes
 ```
 
-_See code: [src/commands/update.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.5/src/commands/update.ts)_
+_See code: [src/commands/update.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.7/src/commands/update.ts)_
 
 ## `prt validate`
 
@@ -724,7 +733,7 @@ EXAMPLES
   $ prt validate
 ```
 
-_See code: [src/commands/validate.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.5/src/commands/validate.ts)_
+_See code: [src/commands/validate.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.7/src/commands/validate.ts)_
 <!-- commandsstop -->
 
 ## Development
@@ -809,11 +818,92 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
 
 ### Release Process
 
-1. Update version in `package.json`
-2. Run `yarn prepack` (generates manifest and updates README)
-3. Commit changes
-4. Run `yarn pack` to create tarball
-5. Run `npm publish` to publish to npm registry
+PRT uses a fully automated CI/CD pipeline powered by GitHub Actions. Releases are created automatically when code is pushed to the `master` branch.
+
+#### Automated Release (Standard Process)
+
+1. **Update version** in `package.json`:
+   ```bash
+   # Example: 0.2.6 → 0.2.7
+   npm version patch  # or minor, or major
+   ```
+
+2. **Commit and push** to `master`:
+   ```bash
+   git add package.json
+   git commit -m "chore: bump version to 0.2.7"
+   git push origin master
+   ```
+
+3. **GitHub Actions automatically**:
+   - ✅ Runs test suite (944 tests must pass)
+   - ✅ Validates build and linting
+   - ✅ Creates GitHub release (only if tests pass)
+   - ✅ Publishes to npm registry
+   - ⏱️ Total time: ~4-6 minutes
+
+**Quality Gate:** If tests fail, no release is created. Fix the issues and push again.
+
+#### Manual Release (Fallback)
+
+For emergency releases or when automation is unavailable:
+
+```bash
+# 1. Update version
+npm version patch
+
+# 2. Build and package
+yarn prepack  # generates manifest, updates README
+yarn pack     # creates tarball
+
+# 3. Publish to npm
+npm publish
+
+# 4. Create GitHub release
+gh release create v$(node -p "require('./package.json').version") --generate-notes
+```
+
+#### Required GitHub Secrets
+
+For automated releases, configure these secrets in your GitHub repository:
+
+| Secret | Purpose |
+|--------|---------|
+| `GH_TOKEN` | GitHub API access (repo + workflow scopes) |
+| `GH_EMAIL` | Git commit author email |
+| `GH_USERNAME` | Git commit author name |
+| `NPM_TOKEN` | npm authentication (optional with Trusted Publishing) |
+
+#### npm Authentication
+
+**Option A: Trusted Publishing (Recommended)**
+- More secure (OIDC-based, no long-lived tokens)
+- Configure at: https://www.npmjs.com/settings/project-roadmap-tracking/packages/project-roadmap-tracking/access
+- No `NPM_TOKEN` secret needed
+
+**Option B: Granular Access Token**
+- Generate at: https://www.npmjs.com/settings/~/tokens
+- Permissions: Read and write for `project-roadmap-tracking` package
+- Store as `NPM_TOKEN` GitHub secret
+
+#### CI/CD Workflows
+
+The project uses three GitHub Actions workflows:
+
+1. **`test.yml`** - Runs on feature branches
+   - Tests across Ubuntu/Windows
+   - Tests across Node LTS versions
+   - Fast feedback during development
+
+2. **`onPushToMaster.yml`** - Runs on master push
+   - Test job (build + tests + lint) ← **Quality gate**
+   - Release job (create GitHub release) ← **Only runs if tests pass**
+
+3. **`onRelease.yml`** - Runs when release created
+   - Builds package
+   - Publishes to npm with provenance
+
+For detailed CI/CD architecture, see [ARCHITECTURE.md - CI/CD Pipeline](ARCHITECTURE.md#cicd-pipeline)
 
 ## License
 

package/dist/commands/show.d.ts

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

package/dist/commands/show.js

@@ -16,6 +16,11 @@ export default class Show extends Command {
             default: false,
             description: 'use legacy direct file I/O instead of repository pattern',
         }),
+        'show-dependencies': Flags.boolean({
+            char: 'd',
+            default: false,
+            description: 'show task dependencies',
+        }),
         // flag with no value (-f, --force)
         // force: Flags.boolean({char: 'f'}),
         // flag with a value (-n, --name=VALUE)
@@ -43,6 +48,12 @@ export default class Show extends Command {
             for (const line of lines) {
                 console.log(line);
             }
+            if (flags['show-dependencies'] && task) {
+                const dependencyLines = displayService.formatTaskDependencies(task, roadmap);
+                for (const line of dependencyLines) {
+                    console.log(line);
+                }
+            }
         }
         catch (error) {
             const exitCode = errorHandlerService.handleError(error);

package/dist/repositories/roadmap.repository.js

@@ -1,5 +1,14 @@
 import { watch } from 'chokidar';
 import { readFile, stat, writeFile } from 'node:fs/promises';
+/**
+ * Detect if we're running in a test environment
+ */
+function isTestEnvironment() {
+    return (process.env.NODE_ENV === 'test' ||
+        process.env.MOCHA === 'true' ||
+        typeof globalThis.describe === 'function' ||
+        typeof globalThis.it === 'function');
+}
 /**
  * RoadmapRepository provides caching and file watching for roadmap data.
  * Features:
@@ -13,20 +22,24 @@ export class RoadmapRepository {
     config;
     watchers = new Map();
     constructor(config) {
+        // Disable file watching in test environments by default
+        const defaultWatchFiles = !isTestEnvironment();
         this.config = {
             cacheEnabled: config?.cacheEnabled ?? true,
             maxCacheSize: config?.maxCacheSize ?? 10,
-            watchFiles: config?.watchFiles ?? true,
+            watchFiles: config?.watchFiles ?? defaultWatchFiles,
         };
     }
     /**
      * Create a repository instance from a Config object
      */
     static fromConfig(config) {
+        // Respect explicit watchFiles setting in config, but default based on environment
+        const defaultWatchFiles = !isTestEnvironment();
         return new RoadmapRepository({
             cacheEnabled: config.cache?.enabled ?? true,
             maxCacheSize: config.cache?.maxSize ?? 10,
-            watchFiles: config.cache?.watchFiles ?? true,
+            watchFiles: config.cache?.watchFiles ?? defaultWatchFiles,
         });
     }
     /**
@@ -153,27 +166,46 @@ export class RoadmapRepository {
      * Set up file watcher for a path
      */
     setupWatcher(path) {
-        const watcher = watch(path, {
-            awaitWriteFinish: {
-                pollInterval: 100,
-                stabilityThreshold: 250,
-            },
-            persistent: false,
-        });
-        watcher.on('change', () => {
-            this.invalidate(path);
-        });
-        watcher.on('unlink', () => {
-            this.invalidate(path);
-            this.watchers
-                .get(path)
-                ?.close()
-                .catch(() => {
-                /* ignore close errors */
+        try {
+            const watcher = watch(path, {
+                awaitWriteFinish: {
+                    pollInterval: 100,
+                    stabilityThreshold: 250,
+                },
+                persistent: false,
             });
-            this.watchers.delete(path);
-        });
-        this.watchers.set(path, watcher);
+            watcher.on('change', () => {
+                this.invalidate(path);
+            });
+            watcher.on('unlink', () => {
+                this.invalidate(path);
+                this.watchers
+                    .get(path)
+                    ?.close()
+                    .catch(() => {
+                    /* ignore close errors */
+                });
+                this.watchers.delete(path);
+            });
+            watcher.on('error', (error) => {
+                // Log error but don't crash - especially important for Windows EPERM errors
+                if (process.env.NODE_ENV !== 'production') {
+                    console.warn(`File watcher error for ${path}:`, error.message);
+                }
+                // Clean up the watcher on error
+                this.watchers.get(path)?.close().catch(() => {
+                    /* ignore close errors */
+                });
+                this.watchers.delete(path);
+            });
+            this.watchers.set(path, watcher);
+        }
+        catch (error) {
+            // If watcher setup fails (e.g., permission issues), log and continue
+            if (process.env.NODE_ENV !== 'production') {
+                console.warn(`Failed to set up file watcher for ${path}:`, error.message);
+            }
+        }
     }
 }
 // Singleton instance with default configuration

package/dist/services/display.service.d.ts

@@ -1,4 +1,4 @@
-import { PRIORITY, STATUS, Task } from '../util/types.js';
+import { PRIORITY, Roadmap, STATUS, Task } from '../util/types.js';
 import { RoadmapStats } from './roadmap.service.js';
 import { DependencyValidationError } from './task-dependency.service.js';
 /**
@@ -80,6 +80,15 @@ export declare class DisplayService {
      * ```
      */
     formatStatusText(status: STATUS): string;
+    /**
+     * Formats the dependencies of a task for display.
+     *
+     *
+     * @param task - the task whose dependencies are to be formatted
+     * @param roadmap - the roadmap containing all tasks
+     * @returns Array of formatted dependency lines
+     */
+    formatTaskDependencies(task: Task, roadmap: Roadmap): string[];
     /**
      * Formats complete task details for show command.
      * Returns an array of lines to be output.

package/dist/services/display.service.js

@@ -124,6 +124,34 @@ export class DisplayService {
             .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
             .join(' ');
     }
+    /**
+     * Formats the dependencies of a task for display.
+     *
+     *
+     * @param task - the task whose dependencies are to be formatted
+     * @param roadmap - the roadmap containing all tasks
+     * @returns Array of formatted dependency lines
+     */
+    formatTaskDependencies(task, roadmap) {
+        const lines = [];
+        lines.push(`\nDependencies for Task: ${task.id}\n`);
+        if (task['depends-on'].length === 0) {
+            lines.push('This task has no dependencies.\n');
+            return lines;
+        }
+        for (const depId of task['depends-on']) {
+            const depTask = roadmap.tasks.find((t) => t.id === depId);
+            if (depTask) {
+                const statusSymbol = this.formatStatusSymbol(depTask.status);
+                const priorityLabel = this.formatPriorityLabel(depTask.priority);
+                lines.push(`  ${statusSymbol} [${priorityLabel}] [${depTask.id}] ${depTask.title}`, `  Details: ${depTask.details}\n`);
+            }
+            else {
+                lines.push(`❌ [Unknown Task] [${depId}] (Task not found in roadmap)`);
+            }
+        }
+        return lines;
+    }
     /**
      * Formats complete task details for show command.
      * Returns an array of lines to be output.

package/oclif.manifest.json

@@ -379,6 +379,13 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "show-dependencies": {
+          "char": "d",
+          "description": "show task dependencies",
+          "name": "show-dependencies",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "verbose": {
           "char": "v",
           "description": "show detailed error information including stack traces",
@@ -545,5 +552,5 @@
       ]
     }
   },
-  "version": "0.2.5"
+  "version": "0.2.7"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "project-roadmap-tracking",
   "description": "CLI based project task tracking",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "author": "ZacharyEggert",
   "bin": {
     "prt": "./bin/run.js"
@@ -23,6 +23,7 @@
     "@types/node": "^18",
     "c8": "^10.1.3",
     "chai": "^4",
+    "cross-env": "^10.1.0",
     "eslint": "^9",
     "eslint-config-oclif": "^6",
     "eslint-config-prettier": "^10",
@@ -45,14 +46,14 @@
   "homepage": "https://github.com/ZacharyEggert/project-roadmap-tracking",
   "keywords": [
     "oclif",
-		"cli",
-		"project",
-		"roadmap",
-		"tracking",
-		"tasks",
-		"productivity",
-		"management",
-		"prt"
+    "cli",
+    "project",
+    "roadmap",
+    "tracking",
+    "tasks",
+    "productivity",
+    "management",
+    "prt"
   ],
   "license": "MIT",
   "main": "dist/index.js",
@@ -81,7 +82,7 @@
     "postpack": "shx rm -f oclif.manifest.json",
     "posttest": "yarn lint",
     "prepack": "oclif manifest && oclif readme",
-    "test": "c8 mocha --loader=tsx/esm --forbid-only 'test/**/*.test.ts'",
+    "test": "cross-env NODE_ENV=test c8 mocha --loader=tsx/esm --forbid-only 'test/**/*.test.ts'",
     "test:coverage": "c8 report",
     "test:coverage:summary": "c8 report --reporter=text",
     "version": "oclif readme && git add README.md"