@gw-tools/gw 0.20.7 → 0.20.9-beta.1

package/README.md

@@ -36,36 +36,42 @@ A command-line tool for managing git worktrees, built with Deno.
       - [Arguments](#arguments-2)
       - [Examples](#examples-2)
       - [How It Works](#how-it-works-1)
-    - [update](#update)
+    - [pr](#pr)
+      - [Arguments](#arguments-3)
       - [Options](#options-1)
       - [Examples](#examples-3)
+      - [Requirements](#requirements)
       - [How It Works](#how-it-works-2)
-    - [install-shell](#install-shell)
+    - [update](#update)
       - [Options](#options-2)
       - [Examples](#examples-4)
-    - [root](#root)
-      - [Examples](#examples-5)
       - [How It Works](#how-it-works-3)
-    - [init](#init)
+    - [install-shell](#install-shell)
       - [Options](#options-3)
+      - [Examples](#examples-5)
+    - [root](#root)
+      - [Examples](#examples-6)
+      - [How It Works](#how-it-works-4)
+    - [init](#init)
+      - [Options](#options-4)
       - [Clone Examples](#clone-examples)
       - [Existing Repository Examples](#existing-repository-examples)
       - [Hook Variables](#hook-variables)
       - [Auto-Cleanup Configuration](#auto-cleanup-configuration)
       - [When to Use](#when-to-use)
     - [show-init](#show-init)
-      - [Options](#options-4)
-      - [Examples](#examples-6)
+      - [Options](#options-5)
+      - [Examples](#examples-7)
       - [Output Example](#output-example)
       - [When to Use](#when-to-use-1)
     - [sync](#sync)
-      - [Arguments](#arguments-3)
-      - [Options](#options-5)
-      - [Examples](#examples-7)
-    - [clean](#clean)
+      - [Arguments](#arguments-4)
       - [Options](#options-6)
       - [Examples](#examples-8)
-      - [How It Works](#how-it-works-4)
+    - [clean](#clean)
+      - [Options](#options-7)
+      - [Examples](#examples-9)
+      - [How It Works](#how-it-works-5)
     - [Git Worktree Proxy Commands](#git-worktree-proxy-commands)
       - [list (ls)](#list-ls)
       - [remove (rm)](#remove-rm)
@@ -137,14 +143,14 @@ npx skills add https://github.com/mthines/gw-tools --skill @gw-git-worktree-work
 ```
 
 ```bash
+# Autonomous feature development workflow
+npx skills add https://github.com/mthines/gw-tools --skill @gw-autonomous-workflow
+
 # Master Git worktrees and gw workflows
 npx skills add https://github.com/mthines/gw-tools --skill @gw-git-worktree-workflows
 
 # Configure gw for your project type (Next.js, monorepos, etc.)
 npx skills add https://github.com/mthines/gw-tools --skill @gw-config-management
-
-# Autonomous feature development workflow
-npx skills add https://github.com/mthines/gw-tools --skill @gw-autonomous-workflow
 ```
 
 Once installed, your AI agent can:
@@ -300,10 +306,11 @@ gw init --root /path/to/your/repo.git
 
 ### Example Configuration
 
-```json
+```jsonc
 {
   "root": "/Users/username/Workspace/my-project.git",
   "defaultBranch": "main",
+  // Auto-copy these files when creating new worktrees
   "autoCopyFiles": [".env", "components/agents/.env", "components/ui/.vercel/"],
   "hooks": {
     "add": {
@@ -314,10 +321,12 @@ gw init --root /path/to/your/repo.git
   "cleanThreshold": 7,
   "autoClean": true,
   "updateStrategy": "merge",
-  "lastAutoCleanTime": 1706371200000
+  "lastAutoCleanTime": 1706371200000,  // trailing comma OK
 }
 ```
 
+**JSONC Support**: Configuration files support JSONC (JSON with Comments) with `//` single-line comments, `/* */` multi-line comments, and trailing commas. When you run `gw init`, it generates a comprehensive self-documenting template with inline documentation for all available options. Active features are shown uncommented while inactive features appear as commented examples with usage patterns.
+
 **More Examples**: See the [examples/](./examples/) directory for configuration templates for various project types (Next.js, Node.js API, monorepos, CI/CD, etc.).
 
 ### Configuration Options
@@ -611,6 +620,75 @@ The `checkout` command intelligently handles four scenarios:
 
 **Use case:** When updating your feature branch with latest changes, you might instinctively try `git checkout main && git pull`. With worktrees, this fails because main is checked out elsewhere. Instead, use `gw update` to update your current branch with main, or use `gw checkout main` to navigate to the main worktree.
 
+### pr
+
+Check out a pull request into a new worktree. This command fetches a PR's branch and creates a worktree for it in one step, making it easy to review, test, or contribute to pull requests.
+
+```bash
+gw pr <pr-number|pr-url>
+```
+
+When you want to review or test a pull request, you typically need to:
+
+1. Find the PR's branch name
+2. Fetch the branch (especially for forks)
+3. Create a worktree for it
+4. Navigate to the worktree
+
+The `gw pr` command does all of this in a single step.
+
+#### Arguments
+
+- `<pr-number|pr-url>`: PR number (e.g., 42) or GitHub PR URL
+
+#### Options
+
+- `--name <name>`: Custom name for the worktree directory (defaults to PR's branch name)
+- `--no-cd`: Don't navigate to the new worktree after creation
+- `-h, --help`: Show help message
+
+#### Examples
+
+```bash
+# Check out PR #42
+gw pr 42
+
+# Check out PR by URL
+gw pr https://github.com/user/repo/pull/42
+
+# Use custom worktree name
+gw pr 42 --name review-feature
+
+# Check out without auto-navigation
+gw pr 42 --no-cd
+```
+
+#### Requirements
+
+- **GitHub CLI (gh)** must be installed and authenticated
+- Install from: https://cli.github.com/
+- After installation, authenticate with: `gh auth login`
+
+#### How It Works
+
+1. **Resolves PR info**: Uses `gh pr view` to get the PR's branch name and fork information
+2. **Validates URL** (if provided): Ensures the PR URL matches the current repository
+3. **Checks for existing worktree**: If the branch is already checked out, offers to navigate there
+4. **Fetches PR branch**: Uses `git fetch origin pull/<number>/head:<branch>` pattern which works for both same-repo and fork PRs
+5. **Creates worktree**: Creates a new worktree with the PR's branch
+6. **Copies files**: Auto-copies files from `autoCopyFiles` config (same as `gw add`)
+7. **Runs hooks**: Executes pre-add and post-add hooks (same as `gw add`)
+8. **Navigates**: Automatically navigates to the new worktree
+
+**Fork Handling:**
+The command automatically handles PRs from forks by using GitHub's `pull/<number>/head` ref pattern. This fetches the PR branch without needing to add the fork as a remote.
+
+**Error Handling:**
+
+- If `gh` is not installed, shows installation instructions
+- If PR is not found, shows helpful error with authentication hint
+- If PR URL is for a different repository, shows clear error message
+
 ### update
 
 Update your current worktree with the latest changes from the default branch (or specified branch) using either merge or rebase strategy. This is useful when you want to update your feature branch with the latest changes from main without having to switch worktrees.

package/install.js

@@ -5,14 +5,7 @@
  * Downloads the appropriate binary for the current platform
  */
 
-const {
-  existsSync,
-  mkdirSync,
-  chmodSync,
-  openSync,
-  fsyncSync,
-  closeSync,
-} = require('fs');
+const { existsSync, mkdirSync, chmodSync, openSync, fsyncSync, closeSync } = require('fs');
 const { join } = require('path');
 const { arch, platform } = require('os');
 const https = require('https');
@@ -46,7 +39,7 @@ function getBinaryName() {
   if (!os || !cpu) {
     console.error(
       `Unsupported platform: ${platform()}-${arch()}\n` +
-        'Supported platforms: macOS (x64, arm64), Linux (x64, arm64), Windows (x64, arm64)',
+        'Supported platforms: macOS (x64, arm64), Linux (x64, arm64), Windows (x64, arm64)'
     );
     process.exit(1);
   }
@@ -63,39 +56,29 @@ function download(url, dest) {
     const file = createWriteStream(dest);
 
     https
-      .get(
-        url,
-        { headers: { 'User-Agent': 'gw-npm-installer' } },
-        (response) => {
-          // Handle redirects
-          if (response.statusCode === 302 || response.statusCode === 301) {
-            return download(response.headers.location, dest)
-              .then(resolve)
-              .catch(reject);
-          }
-
-          if (response.statusCode !== 200) {
-            reject(
-              new Error(
-                `Failed to download: ${response.statusCode} ${response.statusMessage}`,
-              ),
-            );
-            return;
-          }
-
-          response.pipe(file);
-
-          file.on('finish', () => {
-            file.close((err) => {
-              if (err) {
-                reject(err);
-              } else {
-                resolve();
-              }
-            });
+      .get(url, { headers: { 'User-Agent': 'gw-npm-installer' } }, (response) => {
+        // Handle redirects
+        if (response.statusCode === 302 || response.statusCode === 301) {
+          return download(response.headers.location, dest).then(resolve).catch(reject);
+        }
+
+        if (response.statusCode !== 200) {
+          reject(new Error(`Failed to download: ${response.statusCode} ${response.statusMessage}`));
+          return;
+        }
+
+        response.pipe(file);
+
+        file.on('finish', () => {
+          file.close((err) => {
+            if (err) {
+              reject(err);
+            } else {
+              resolve();
+            }
           });
-        },
-      )
+        });
+      })
       .on('error', (err) => {
         reject(err);
       });
@@ -197,7 +180,7 @@ async function installShellIntegration(binaryPath, retries = 3) {
 
     try {
       child = spawn(binaryPath, ['install-shell'], {
-        stdio: ['inherit', 'inherit', 'pipe'],  // stdin, stdout, stderr
+        stdio: ['inherit', 'inherit', 'pipe'], // stdin, stdout, stderr
       });
     } catch (err) {
       // Catch synchronous spawn errors (e.g., ETXTBSY thrown immediately)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gw-tools/gw",
-  "version": "0.20.7",
+  "version": "0.20.9-beta.1",
   "description": "A command-line tool for managing git worktrees - copy files between worktrees with ease",
   "keywords": [
     "git",

package/uninstall.js

@@ -119,7 +119,7 @@ function uninstall() {
       const result = spawnSync(binaryPath, ['install-shell', '--remove'], {
         stdio: ['inherit', 'pipe', 'pipe'],
         timeout: 5000,
-        encoding: 'utf8'
+        encoding: 'utf8',
       });
 
       if (result.status === 0) {