project-roadmap-tracking 0.2.6 → 0.2.7

package/README.md

@@ -160,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
@@ -170,7 +174,7 @@ $ npm install -g project-roadmap-tracking
 $ prt COMMAND
 running command...
 $ prt (--version)
-project-roadmap-tracking/0.2.6 linux-x64 node-v25.4.0
+project-roadmap-tracking/0.2.7 linux-x64 node-v25.4.0
 $ prt --help [COMMAND]
 USAGE
   $ prt COMMAND
@@ -232,7 +236,7 @@ EXAMPLES
   $ prt add
 ```
 
-_See code: [src/commands/add.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.6/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`
 
@@ -257,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.6/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]`
 
@@ -304,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.6/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`
 
@@ -333,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.6/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`
 
@@ -357,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.6/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`
 
@@ -672,7 +676,7 @@ EXAMPLES
   $ prt show F-001
 ```
 
-_See code: [src/commands/show.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.6/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`
 
@@ -708,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.6/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`
 
@@ -729,7 +733,7 @@ EXAMPLES
   $ prt validate
 ```
 
-_See code: [src/commands/validate.ts](https://github.com/ZacharyEggert/project-roadmap-tracking/blob/v0.2.6/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
@@ -814,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/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/oclif.manifest.json

@@ -552,5 +552,5 @@
       ]
     }
   },
-  "version": "0.2.6"
+  "version": "0.2.7"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "project-roadmap-tracking",
   "description": "CLI based project task tracking",
-  "version": "0.2.6",
+  "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"