@bretwardjames/ghp-core 0.1.7 → 0.2.0-beta.1

package/README.md

@@ -1,123 +1,37 @@
-# GHP Tools
+# @bretwardjames/ghp-core
 
-A suite of tools for managing GitHub Projects from your terminal and editor.
+Shared core library for GHP tools - provides GitHub Projects API interactions, types, and utilities.
 
-## What's Included
+Part of the [GHP monorepo](https://github.com/bretwardjames/ghp).
 
-| Package | Description |
-|---------|-------------|
-| **[@bretwardjames/ghp-cli](https://github.com/bretwardjames/ghp-cli)** | Command-line interface for GitHub Projects |
-| **[vscode-gh-projects](https://github.com/bretwardjames/vscode-gh-projects)** | VS Code / Cursor extension with visual boards |
-| **@bretwardjames/ghp-core** | Shared library (this package) |
+## Installation
 
-Both the CLI and extension share the same underlying library and are designed to work together.
-
-## Quick Install
-
-Install both the CLI and VS Code/Cursor extension with a single command:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/bretwardjames/ghp-core/main/install.sh | bash
-```
-
-This will:
-1. Install the `ghp` CLI globally via npm
-2. Install the VS Code/Cursor extension from the latest release
-
-### Manual Installation
-
-**CLI only:**
 ```bash
-npm install -g @bretwardjames/ghp-cli
+npm install @bretwardjames/ghp-core
 ```
 
-**Extension only:**
-Download the `.vsix` from [releases](https://github.com/bretwardjames/vscode-gh-projects/releases) and install:
-```bash
-code --install-extension gh-projects-*.vsix
-# or for Cursor:
-cursor --install-extension gh-projects-*.vsix
-```
-
-## Getting Started
-
-1. Authenticate with GitHub:
-   ```bash
-   ghp auth
-   ```
-
-2. View your assigned work:
-   ```bash
-   ghp work
-   ```
-
-3. Open VS Code/Cursor and find the GitHub Projects panel in the sidebar
-
-## Features
-
-### Shared Across Both Tools
+## Usage
 
-- **Branch Linking** - Link branches to issues, track which issues have active work
-- **Workflow Automation** - "Start Working" creates branches and updates status
-- **Project Board Views** - See your boards exactly as configured on GitHub
-- **Issue Templates** - Create issues using your repo's templates
+This package is primarily used internally by:
+- [@bretwardjames/ghp-cli](https://github.com/bretwardjames/ghp/tree/main/packages/cli) - Command-line tool
+- [gh-projects](https://github.com/bretwardjames/ghp/tree/main/apps/vscode) - VS Code extension
 
-### CLI-Specific
+## API
 
-- **Shortcuts** - Define named filter combinations (`ghp plan bugs`)
-- **Slice Filters** - Filter by any field (`--slice Priority=High`)
-- **Workspace Config** - Share settings with your team via `.ghp/config.json`
-- **Simple List Output** - Integration with fzf, rofi, and other pickers
+```typescript
+import { GitHubAPI, parseIssueUrl, BranchLinker } from '@bretwardjames/ghp-core';
 
-### Extension-Specific
+// Create API client
+const api = new GitHubAPI(token);
 
-- **Drag and Drop** - Move issues between columns visually
-- **Planning Board** - Full-screen kanban view
-- **Multi-Select** - Bulk operations on multiple items
-- **Real-Time Sync** - Stay in sync with GitHub
+// Parse issue URLs
+const { owner, repo, number } = parseIssueUrl('https://github.com/owner/repo/issues/123');
 
-## Configuration
-
-Both tools share the same configuration concepts. The CLI uses JSON files, the extension uses VS Code settings.
-
-### CLI Configuration (ghp-cli)
-
-```bash
-# View all settings with their sources
-ghp config --show
-
-# Edit user config (opens $EDITOR)
-ghp config
-
-# Edit workspace config (shared with team)
-ghp config -w
-
-# Set individual value
-ghp config mainBranch develop
+// Branch linking
+const linker = new BranchLinker(api);
+await linker.linkBranch(issueNumber, branchName);
 ```
 
-**Config files:**
-- User: `~/.config/ghp-cli/config.json` (personal overrides)
-- Workspace: `.ghp/config.json` (committed, shared with team)
-
-Merge order: defaults -> workspace -> user
-
-### Extension Configuration (VS Code)
-
-Settings are in VS Code's settings UI under "GitHub Projects", or in your workspace `.vscode/settings.json`.
-
-## Links
-
-- [ghp-cli Documentation](https://github.com/bretwardjames/ghp-cli)
-- [VS Code Extension Documentation](https://github.com/bretwardjames/vscode-gh-projects)
-- [Report Issues](https://github.com/bretwardjames/ghp-core/issues)
-
-## Requirements
-
-- Node.js >= 18
-- GitHub account with Projects access
-- VS Code 1.85+ or Cursor (for extension)
-
 ## License
 
 MIT

package/dist/index.cjs

@@ -36,10 +36,12 @@ __export(index_exports, {
   checkoutBranch: () => checkoutBranch,
   computeSettingsDiff: () => computeSettingsDiff,
   createBranch: () => createBranch,
+  createWorktree: () => createWorktree,
   detectRepository: () => detectRepository,
   fetchOrigin: () => fetchOrigin,
   formatConflict: () => formatConflict,
   generateBranchName: () => generateBranchName,
+  generateWorktreePath: () => generateWorktreePath,
   getAllBranches: () => getAllBranches,
   getCommitsAhead: () => getCommitsAhead,
   getCommitsBehind: () => getCommitsBehind,
@@ -49,9 +51,11 @@ __export(index_exports, {
   getLocalBranches: () => getLocalBranches,
   getRemoteBranches: () => getRemoteBranches,
   getRepositoryRoot: () => getRepositoryRoot,
+  getWorktreeForBranch: () => getWorktreeForBranch,
   hasDifferences: () => hasDifferences,
   hasUncommittedChanges: () => hasUncommittedChanges,
   isGitRepository: () => isGitRepository,
+  listWorktrees: () => listWorktrees,
   normalizeVSCodeSettings: () => normalizeVSCodeSettings,
   parseBranchLink: () => parseBranchLink,
   parseGitHubUrl: () => parseGitHubUrl,
@@ -59,6 +63,7 @@ __export(index_exports, {
   pullLatest: () => pullLatest,
   queries: () => queries_exports,
   removeBranchLinkFromBody: () => removeBranchLinkFromBody,
+  removeWorktree: () => removeWorktree,
   resolveConflicts: () => resolveConflicts,
   sanitizeForBranchName: () => sanitizeForBranchName,
   setBranchLinkInBody: () => setBranchLinkInBody,
@@ -66,7 +71,8 @@ __export(index_exports, {
   toVSCodeSettings: () => toVSCodeSettings,
   useCli: () => useCli,
   useCustom: () => useCustom,
-  useVSCode: () => useVSCode
+  useVSCode: () => useVSCode,
+  worktreeExists: () => worktreeExists
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -405,7 +411,7 @@ var REMOVE_LABELS_MUTATION = `
 var ISSUES_WITH_LABEL_QUERY = `
     query($owner: String!, $name: String!, $labels: [String!]) {
         repository(owner: $owner, name: $name) {
-            issues(first: 10, labels: $labels, states: [OPEN]) {
+            issues(first: 10, labels: $labels, states: [OPEN, CLOSED]) {
                 nodes {
                     number
                 }
@@ -556,8 +562,18 @@ var GitHubAPI = class {
         owner: repo.owner,
         name: repo.name
       });
+      if (!response.repository) {
+        throw new Error(`Repository not found: ${repo.owner}/${repo.name}`);
+      }
       return response.repository.projectsV2.nodes;
     } catch (error) {
+      if (error && typeof error === "object" && "errors" in error) {
+        const gqlError = error;
+        const notFound = gqlError.errors?.find((e) => e.type === "NOT_FOUND");
+        if (notFound) {
+          throw new Error(`Repository not found: ${repo.owner}/${repo.name}`);
+        }
+      }
       this.handleAuthError(error);
     }
   }
@@ -1148,6 +1164,7 @@ var BranchLinker = class {
 // src/git-utils.ts
 var import_child_process = require("child_process");
 var import_util = require("util");
+var import_os = require("os");
 
 // src/url-parser.ts
 function parseGitHubUrl(url) {
@@ -1200,6 +1217,28 @@ function buildOrgProjectUrl(org, projectNumber) {
 }
 
 // src/git-utils.ts
+function sanitizeForPath(input) {
+  return String(input).replace(/\.\./g, "_").replace(/[;&|`$(){}[\]<>!]/g, "").replace(/\s+/g, "-").replace(/[^a-zA-Z0-9_\-./]/g, "_");
+}
+function validateBranchName(branch) {
+  if (!branch || branch.trim().length === 0) {
+    throw new Error("Branch name cannot be empty");
+  }
+  const dangerousChars = /[`$\\!;|&<>(){}[\]'"]/;
+  if (dangerousChars.test(branch)) {
+    throw new Error(`Branch name contains invalid characters: ${branch}`);
+  }
+  const gitInvalidChars = /[\s~^:?*\[\\]/;
+  if (gitInvalidChars.test(branch)) {
+    throw new Error(`Branch name contains invalid git characters: ${branch}`);
+  }
+  if (branch.includes("..")) {
+    throw new Error(`Branch name cannot contain '..': ${branch}`);
+  }
+  if (/^[./]|[./]$/.test(branch)) {
+    throw new Error(`Branch name cannot start or end with '/' or '.': ${branch}`);
+  }
+}
 var execAsync = (0, import_util.promisify)(import_child_process.exec);
 async function execGit(command, options = {}) {
   const cwd = options.cwd || process.cwd();
@@ -1347,6 +1386,84 @@ async function getDefaultBranch(options = {}) {
   }
   return "master";
 }
+function validatePath(path) {
+  if (!path || path.trim().length === 0) {
+    throw new Error("Path cannot be empty");
+  }
+  const dangerousChars = /[`$;|&<>(){}[\]'"\n\r]/;
+  if (dangerousChars.test(path)) {
+    throw new Error(`Path contains invalid characters: ${path}`);
+  }
+}
+async function createWorktree(worktreePath, branch, options = {}) {
+  validateBranchName(branch);
+  validatePath(worktreePath);
+  const localExists = await branchExists(branch, options);
+  if (localExists) {
+    await execGit(`git worktree add "${worktreePath}" "${branch}"`, options);
+  } else {
+    try {
+      await execGit(`git worktree add "${worktreePath}" -b "${branch}" "origin/${branch}"`, options);
+    } catch {
+      await execGit(`git worktree add -b "${branch}" "${worktreePath}"`, options);
+    }
+  }
+}
+async function removeWorktree(worktreePath, options = {}, force = false) {
+  validatePath(worktreePath);
+  const forceFlag = force ? "--force" : "";
+  await execGit(`git worktree remove ${forceFlag} "${worktreePath}"`, options);
+}
+async function listWorktrees(options = {}) {
+  try {
+    const { stdout } = await execGit("git worktree list --porcelain", options);
+    const worktrees = [];
+    const entries = stdout.trim().split("\n\n");
+    for (const entry of entries) {
+      if (!entry.trim()) continue;
+      const lines = entry.split("\n");
+      const info = {
+        isMain: false,
+        branch: null
+      };
+      for (const line of lines) {
+        if (line.startsWith("worktree ")) {
+          info.path = line.substring(9);
+        } else if (line.startsWith("HEAD ")) {
+          info.head = line.substring(5);
+        } else if (line.startsWith("branch ")) {
+          info.branch = line.substring(7).replace(/^refs\/heads\//, "");
+        } else if (line === "bare") {
+          info.isMain = true;
+        }
+      }
+      if (worktrees.length === 0) {
+        info.isMain = true;
+      }
+      if (info.path && info.head) {
+        worktrees.push(info);
+      }
+    }
+    return worktrees;
+  } catch {
+    return [];
+  }
+}
+async function getWorktreeForBranch(branch, options = {}) {
+  const worktrees = await listWorktrees(options);
+  return worktrees.find((wt) => wt.branch === branch) || null;
+}
+async function worktreeExists(worktreePath, options = {}) {
+  const worktrees = await listWorktrees(options);
+  return worktrees.some((wt) => wt.path === worktreePath);
+}
+function generateWorktreePath(basePath, repoName, identifier) {
+  const safeRepoName = sanitizeForPath(repoName);
+  const safeIdentifier = sanitizeForPath(String(identifier));
+  const expandedBase = basePath.startsWith("~") ? basePath.replace("~", (0, import_os.homedir)()) : basePath;
+  const cleanBase = expandedBase.replace(/\/+$/, "");
+  return `${cleanBase}/${safeRepoName}/${safeIdentifier}`;
+}
 
 // src/sync.ts
 var SYNCABLE_KEYS = [
@@ -1527,10 +1644,12 @@ function getDiffSummary(diff) {
   checkoutBranch,
   computeSettingsDiff,
   createBranch,
+  createWorktree,
   detectRepository,
   fetchOrigin,
   formatConflict,
   generateBranchName,
+  generateWorktreePath,
   getAllBranches,
   getCommitsAhead,
   getCommitsBehind,
@@ -1540,9 +1659,11 @@ function getDiffSummary(diff) {
   getLocalBranches,
   getRemoteBranches,
   getRepositoryRoot,
+  getWorktreeForBranch,
   hasDifferences,
   hasUncommittedChanges,
   isGitRepository,
+  listWorktrees,
   normalizeVSCodeSettings,
   parseBranchLink,
   parseGitHubUrl,
@@ -1550,6 +1671,7 @@ function getDiffSummary(diff) {
   pullLatest,
   queries,
   removeBranchLinkFromBody,
+  removeWorktree,
   resolveConflicts,
   sanitizeForBranchName,
   setBranchLinkInBody,
@@ -1557,5 +1679,6 @@ function getDiffSummary(diff) {
   toVSCodeSettings,
   useCli,
   useCustom,
-  useVSCode
+  useVSCode,
+  worktreeExists
 });

package/dist/index.d.cts

@@ -645,6 +645,60 @@ declare function getAllBranches(options?: GitOptions): Promise<string[]>;
  * Get the default branch name (main or master)
  */
 declare function getDefaultBranch(options?: GitOptions): Promise<string>;
+/**
+ * Information about a git worktree
+ */
+interface WorktreeInfo {
+    /** Absolute path to the worktree directory */
+    path: string;
+    /** Commit SHA the worktree is at */
+    head: string;
+    /** Branch name (without refs/heads/ prefix), or null if detached */
+    branch: string | null;
+    /** Whether this is the main worktree (the original repo) */
+    isMain: boolean;
+}
+/**
+ * Create a new worktree for a branch
+ * @param worktreePath - Path where the worktree will be created
+ * @param branch - Branch to checkout in the worktree
+ * @param options - Git options (cwd determines the source repository)
+ */
+declare function createWorktree(worktreePath: string, branch: string, options?: GitOptions): Promise<void>;
+/**
+ * Remove a worktree
+ * @param worktreePath - Path to the worktree to remove
+ * @param options - Git options
+ * @param force - Force removal even if worktree has uncommitted changes
+ */
+declare function removeWorktree(worktreePath: string, options?: GitOptions, force?: boolean): Promise<void>;
+/**
+ * List all worktrees for the repository
+ * @param options - Git options
+ * @returns Array of worktree information
+ */
+declare function listWorktrees(options?: GitOptions): Promise<WorktreeInfo[]>;
+/**
+ * Get worktree for a specific branch
+ * @param branch - Branch name to find
+ * @param options - Git options
+ * @returns Worktree info if found, null otherwise
+ */
+declare function getWorktreeForBranch(branch: string, options?: GitOptions): Promise<WorktreeInfo | null>;
+/**
+ * Check if a worktree exists at the given path
+ * @param worktreePath - Path to check
+ * @param options - Git options
+ */
+declare function worktreeExists(worktreePath: string, options?: GitOptions): Promise<boolean>;
+/**
+ * Generate a worktree path based on repo and branch info
+ * @param basePath - Base directory for worktrees (e.g., ~/.ghp/worktrees)
+ * @param repoName - Repository name
+ * @param identifier - Issue number or branch name to use as identifier
+ * @returns Full path to the worktree directory
+ */
+declare function generateWorktreePath(basePath: string, repoName: string, identifier: string | number): string;
 
 /**
  * URL parsing utilities for GitHub repositories and issues.
@@ -937,7 +991,7 @@ declare const REMOVE_LABELS_MUTATION = "\n    mutation($issueId: ID!, $labelIds:
 /**
  * Query to find issues with a specific label
  */
-declare const ISSUES_WITH_LABEL_QUERY = "\n    query($owner: String!, $name: String!, $labels: [String!]) {\n        repository(owner: $owner, name: $name) {\n            issues(first: 10, labels: $labels, states: [OPEN]) {\n                nodes {\n                    number\n                }\n            }\n        }\n    }\n";
+declare const ISSUES_WITH_LABEL_QUERY = "\n    query($owner: String!, $name: String!, $labels: [String!]) {\n        repository(owner: $owner, name: $name) {\n            issues(first: 10, labels: $labels, states: [OPEN, CLOSED]) {\n                nodes {\n                    number\n                }\n            }\n        }\n    }\n";
 /**
  * Query to get available issue types for a repository
  */
@@ -988,4 +1042,4 @@ declare namespace queries {
   export { queries_ADD_COMMENT_MUTATION as ADD_COMMENT_MUTATION, queries_ADD_LABELS_MUTATION as ADD_LABELS_MUTATION, queries_ADD_TO_PROJECT_MUTATION as ADD_TO_PROJECT_MUTATION, queries_COLLABORATORS_QUERY as COLLABORATORS_QUERY, queries_CREATE_ISSUE_MUTATION as CREATE_ISSUE_MUTATION, queries_ISSUES_WITH_LABEL_QUERY as ISSUES_WITH_LABEL_QUERY, queries_ISSUE_AND_LABEL_QUERY as ISSUE_AND_LABEL_QUERY, queries_ISSUE_DETAILS_QUERY as ISSUE_DETAILS_QUERY, queries_ISSUE_FOR_UPDATE_QUERY as ISSUE_FOR_UPDATE_QUERY, queries_ISSUE_NODE_ID_QUERY as ISSUE_NODE_ID_QUERY, queries_ISSUE_TYPES_QUERY as ISSUE_TYPES_QUERY, queries_LABEL_EXISTS_QUERY as LABEL_EXISTS_QUERY, queries_PROJECT_FIELDS_QUERY as PROJECT_FIELDS_QUERY, queries_PROJECT_ITEMS_QUERY as PROJECT_ITEMS_QUERY, queries_PROJECT_VIEWS_QUERY as PROJECT_VIEWS_QUERY, queries_RECENT_ISSUES_QUERY as RECENT_ISSUES_QUERY, queries_REMOVE_LABELS_MUTATION as REMOVE_LABELS_MUTATION, queries_REPOSITORY_ID_QUERY as REPOSITORY_ID_QUERY, queries_REPOSITORY_PROJECTS_QUERY as REPOSITORY_PROJECTS_QUERY, queries_UPDATE_ISSUE_BODY_MUTATION as UPDATE_ISSUE_BODY_MUTATION, queries_UPDATE_ISSUE_MUTATION as UPDATE_ISSUE_MUTATION, queries_UPDATE_ISSUE_TYPE_MUTATION as UPDATE_ISSUE_TYPE_MUTATION, queries_UPDATE_ITEM_FIELD_MUTATION as UPDATE_ITEM_FIELD_MUTATION, queries_UPDATE_ITEM_STATUS_MUTATION as UPDATE_ITEM_STATUS_MUTATION, queries_VIEWER_QUERY as VIEWER_QUERY };
 }
 
-export { type AssigneeInfo, type AuthError, BranchLinker, CLI_TO_VSCODE_MAP, type Collaborator, type ConflictChoices, type ConflictResolution, DEFAULT_VALUES, type DateFieldValue, type FieldInfo, type FieldValue, type FieldValueConnection, GitHubAPI, type GitHubAPIOptions, type GitOptions, type IssueDetails, type IssueReference, type IterationFieldValue, type LabelInfo, type NumberFieldValue, type Project, type ProjectConfig, type ProjectItem, type ProjectItemContent, type ProjectItemsQueryResponse, type ProjectV2, type ProjectV2Field, type ProjectV2Item, type ProjectV2View, type ProjectWithViews, type ProjectsQueryResponse, type RepoInfo, type ResolvedSettings, SETTING_DISPLAY_NAMES, SYNCABLE_KEYS, type SettingConflict, type SettingsDiff, type SettingsSource, type SingleSelectFieldValue, type StatusField, type SyncableSettingKey, type SyncableSettings, type TextFieldValue, type TokenProvider, VSCODE_TO_CLI_MAP, branchExists, buildIssueUrl, buildOrgProjectUrl, buildProjectUrl, buildPullRequestUrl, buildRepoUrl, checkoutBranch, computeSettingsDiff, createBranch, detectRepository, fetchOrigin, formatConflict, generateBranchName, getAllBranches, getCommitsAhead, getCommitsBehind, getCurrentBranch, getDefaultBranch, getDiffSummary, getLocalBranches, getRemoteBranches, getRepositoryRoot, hasDifferences, hasUncommittedChanges, isGitRepository, normalizeVSCodeSettings, parseBranchLink, parseGitHubUrl, parseIssueUrl, pullLatest, queries, removeBranchLinkFromBody, resolveConflicts, sanitizeForBranchName, setBranchLinkInBody, skip, toVSCodeSettings, useCli, useCustom, useVSCode };
+export { type AssigneeInfo, type AuthError, BranchLinker, CLI_TO_VSCODE_MAP, type Collaborator, type ConflictChoices, type ConflictResolution, DEFAULT_VALUES, type DateFieldValue, type FieldInfo, type FieldValue, type FieldValueConnection, GitHubAPI, type GitHubAPIOptions, type GitOptions, type IssueDetails, type IssueReference, type IterationFieldValue, type LabelInfo, type NumberFieldValue, type Project, type ProjectConfig, type ProjectItem, type ProjectItemContent, type ProjectItemsQueryResponse, type ProjectV2, type ProjectV2Field, type ProjectV2Item, type ProjectV2View, type ProjectWithViews, type ProjectsQueryResponse, type RepoInfo, type ResolvedSettings, SETTING_DISPLAY_NAMES, SYNCABLE_KEYS, type SettingConflict, type SettingsDiff, type SettingsSource, type SingleSelectFieldValue, type StatusField, type SyncableSettingKey, type SyncableSettings, type TextFieldValue, type TokenProvider, VSCODE_TO_CLI_MAP, type WorktreeInfo, branchExists, buildIssueUrl, buildOrgProjectUrl, buildProjectUrl, buildPullRequestUrl, buildRepoUrl, checkoutBranch, computeSettingsDiff, createBranch, createWorktree, detectRepository, fetchOrigin, formatConflict, generateBranchName, generateWorktreePath, getAllBranches, getCommitsAhead, getCommitsBehind, getCurrentBranch, getDefaultBranch, getDiffSummary, getLocalBranches, getRemoteBranches, getRepositoryRoot, getWorktreeForBranch, hasDifferences, hasUncommittedChanges, isGitRepository, listWorktrees, normalizeVSCodeSettings, parseBranchLink, parseGitHubUrl, parseIssueUrl, pullLatest, queries, removeBranchLinkFromBody, removeWorktree, resolveConflicts, sanitizeForBranchName, setBranchLinkInBody, skip, toVSCodeSettings, useCli, useCustom, useVSCode, worktreeExists };

package/dist/index.d.ts

@@ -645,6 +645,60 @@ declare function getAllBranches(options?: GitOptions): Promise<string[]>;
  * Get the default branch name (main or master)
  */
 declare function getDefaultBranch(options?: GitOptions): Promise<string>;
+/**
+ * Information about a git worktree
+ */
+interface WorktreeInfo {
+    /** Absolute path to the worktree directory */
+    path: string;
+    /** Commit SHA the worktree is at */
+    head: string;
+    /** Branch name (without refs/heads/ prefix), or null if detached */
+    branch: string | null;
+    /** Whether this is the main worktree (the original repo) */
+    isMain: boolean;
+}
+/**
+ * Create a new worktree for a branch
+ * @param worktreePath - Path where the worktree will be created
+ * @param branch - Branch to checkout in the worktree
+ * @param options - Git options (cwd determines the source repository)
+ */
+declare function createWorktree(worktreePath: string, branch: string, options?: GitOptions): Promise<void>;
+/**
+ * Remove a worktree
+ * @param worktreePath - Path to the worktree to remove
+ * @param options - Git options
+ * @param force - Force removal even if worktree has uncommitted changes
+ */
+declare function removeWorktree(worktreePath: string, options?: GitOptions, force?: boolean): Promise<void>;
+/**
+ * List all worktrees for the repository
+ * @param options - Git options
+ * @returns Array of worktree information
+ */
+declare function listWorktrees(options?: GitOptions): Promise<WorktreeInfo[]>;
+/**
+ * Get worktree for a specific branch
+ * @param branch - Branch name to find
+ * @param options - Git options
+ * @returns Worktree info if found, null otherwise
+ */
+declare function getWorktreeForBranch(branch: string, options?: GitOptions): Promise<WorktreeInfo | null>;
+/**
+ * Check if a worktree exists at the given path
+ * @param worktreePath - Path to check
+ * @param options - Git options
+ */
+declare function worktreeExists(worktreePath: string, options?: GitOptions): Promise<boolean>;
+/**
+ * Generate a worktree path based on repo and branch info
+ * @param basePath - Base directory for worktrees (e.g., ~/.ghp/worktrees)
+ * @param repoName - Repository name
+ * @param identifier - Issue number or branch name to use as identifier
+ * @returns Full path to the worktree directory
+ */
+declare function generateWorktreePath(basePath: string, repoName: string, identifier: string | number): string;
 
 /**
  * URL parsing utilities for GitHub repositories and issues.
@@ -937,7 +991,7 @@ declare const REMOVE_LABELS_MUTATION = "\n    mutation($issueId: ID!, $labelIds:
 /**
  * Query to find issues with a specific label
  */
-declare const ISSUES_WITH_LABEL_QUERY = "\n    query($owner: String!, $name: String!, $labels: [String!]) {\n        repository(owner: $owner, name: $name) {\n            issues(first: 10, labels: $labels, states: [OPEN]) {\n                nodes {\n                    number\n                }\n            }\n        }\n    }\n";
+declare const ISSUES_WITH_LABEL_QUERY = "\n    query($owner: String!, $name: String!, $labels: [String!]) {\n        repository(owner: $owner, name: $name) {\n            issues(first: 10, labels: $labels, states: [OPEN, CLOSED]) {\n                nodes {\n                    number\n                }\n            }\n        }\n    }\n";
 /**
  * Query to get available issue types for a repository
  */
@@ -988,4 +1042,4 @@ declare namespace queries {
   export { queries_ADD_COMMENT_MUTATION as ADD_COMMENT_MUTATION, queries_ADD_LABELS_MUTATION as ADD_LABELS_MUTATION, queries_ADD_TO_PROJECT_MUTATION as ADD_TO_PROJECT_MUTATION, queries_COLLABORATORS_QUERY as COLLABORATORS_QUERY, queries_CREATE_ISSUE_MUTATION as CREATE_ISSUE_MUTATION, queries_ISSUES_WITH_LABEL_QUERY as ISSUES_WITH_LABEL_QUERY, queries_ISSUE_AND_LABEL_QUERY as ISSUE_AND_LABEL_QUERY, queries_ISSUE_DETAILS_QUERY as ISSUE_DETAILS_QUERY, queries_ISSUE_FOR_UPDATE_QUERY as ISSUE_FOR_UPDATE_QUERY, queries_ISSUE_NODE_ID_QUERY as ISSUE_NODE_ID_QUERY, queries_ISSUE_TYPES_QUERY as ISSUE_TYPES_QUERY, queries_LABEL_EXISTS_QUERY as LABEL_EXISTS_QUERY, queries_PROJECT_FIELDS_QUERY as PROJECT_FIELDS_QUERY, queries_PROJECT_ITEMS_QUERY as PROJECT_ITEMS_QUERY, queries_PROJECT_VIEWS_QUERY as PROJECT_VIEWS_QUERY, queries_RECENT_ISSUES_QUERY as RECENT_ISSUES_QUERY, queries_REMOVE_LABELS_MUTATION as REMOVE_LABELS_MUTATION, queries_REPOSITORY_ID_QUERY as REPOSITORY_ID_QUERY, queries_REPOSITORY_PROJECTS_QUERY as REPOSITORY_PROJECTS_QUERY, queries_UPDATE_ISSUE_BODY_MUTATION as UPDATE_ISSUE_BODY_MUTATION, queries_UPDATE_ISSUE_MUTATION as UPDATE_ISSUE_MUTATION, queries_UPDATE_ISSUE_TYPE_MUTATION as UPDATE_ISSUE_TYPE_MUTATION, queries_UPDATE_ITEM_FIELD_MUTATION as UPDATE_ITEM_FIELD_MUTATION, queries_UPDATE_ITEM_STATUS_MUTATION as UPDATE_ITEM_STATUS_MUTATION, queries_VIEWER_QUERY as VIEWER_QUERY };
 }
 
-export { type AssigneeInfo, type AuthError, BranchLinker, CLI_TO_VSCODE_MAP, type Collaborator, type ConflictChoices, type ConflictResolution, DEFAULT_VALUES, type DateFieldValue, type FieldInfo, type FieldValue, type FieldValueConnection, GitHubAPI, type GitHubAPIOptions, type GitOptions, type IssueDetails, type IssueReference, type IterationFieldValue, type LabelInfo, type NumberFieldValue, type Project, type ProjectConfig, type ProjectItem, type ProjectItemContent, type ProjectItemsQueryResponse, type ProjectV2, type ProjectV2Field, type ProjectV2Item, type ProjectV2View, type ProjectWithViews, type ProjectsQueryResponse, type RepoInfo, type ResolvedSettings, SETTING_DISPLAY_NAMES, SYNCABLE_KEYS, type SettingConflict, type SettingsDiff, type SettingsSource, type SingleSelectFieldValue, type StatusField, type SyncableSettingKey, type SyncableSettings, type TextFieldValue, type TokenProvider, VSCODE_TO_CLI_MAP, branchExists, buildIssueUrl, buildOrgProjectUrl, buildProjectUrl, buildPullRequestUrl, buildRepoUrl, checkoutBranch, computeSettingsDiff, createBranch, detectRepository, fetchOrigin, formatConflict, generateBranchName, getAllBranches, getCommitsAhead, getCommitsBehind, getCurrentBranch, getDefaultBranch, getDiffSummary, getLocalBranches, getRemoteBranches, getRepositoryRoot, hasDifferences, hasUncommittedChanges, isGitRepository, normalizeVSCodeSettings, parseBranchLink, parseGitHubUrl, parseIssueUrl, pullLatest, queries, removeBranchLinkFromBody, resolveConflicts, sanitizeForBranchName, setBranchLinkInBody, skip, toVSCodeSettings, useCli, useCustom, useVSCode };
+export { type AssigneeInfo, type AuthError, BranchLinker, CLI_TO_VSCODE_MAP, type Collaborator, type ConflictChoices, type ConflictResolution, DEFAULT_VALUES, type DateFieldValue, type FieldInfo, type FieldValue, type FieldValueConnection, GitHubAPI, type GitHubAPIOptions, type GitOptions, type IssueDetails, type IssueReference, type IterationFieldValue, type LabelInfo, type NumberFieldValue, type Project, type ProjectConfig, type ProjectItem, type ProjectItemContent, type ProjectItemsQueryResponse, type ProjectV2, type ProjectV2Field, type ProjectV2Item, type ProjectV2View, type ProjectWithViews, type ProjectsQueryResponse, type RepoInfo, type ResolvedSettings, SETTING_DISPLAY_NAMES, SYNCABLE_KEYS, type SettingConflict, type SettingsDiff, type SettingsSource, type SingleSelectFieldValue, type StatusField, type SyncableSettingKey, type SyncableSettings, type TextFieldValue, type TokenProvider, VSCODE_TO_CLI_MAP, type WorktreeInfo, branchExists, buildIssueUrl, buildOrgProjectUrl, buildProjectUrl, buildPullRequestUrl, buildRepoUrl, checkoutBranch, computeSettingsDiff, createBranch, createWorktree, detectRepository, fetchOrigin, formatConflict, generateBranchName, generateWorktreePath, getAllBranches, getCommitsAhead, getCommitsBehind, getCurrentBranch, getDefaultBranch, getDiffSummary, getLocalBranches, getRemoteBranches, getRepositoryRoot, getWorktreeForBranch, hasDifferences, hasUncommittedChanges, isGitRepository, listWorktrees, normalizeVSCodeSettings, parseBranchLink, parseGitHubUrl, parseIssueUrl, pullLatest, queries, removeBranchLinkFromBody, removeWorktree, resolveConflicts, sanitizeForBranchName, setBranchLinkInBody, skip, toVSCodeSettings, useCli, useCustom, useVSCode, worktreeExists };

package/dist/index.js

@@ -339,7 +339,7 @@ var REMOVE_LABELS_MUTATION = `
 var ISSUES_WITH_LABEL_QUERY = `
     query($owner: String!, $name: String!, $labels: [String!]) {
         repository(owner: $owner, name: $name) {
-            issues(first: 10, labels: $labels, states: [OPEN]) {
+            issues(first: 10, labels: $labels, states: [OPEN, CLOSED]) {
                 nodes {
                     number
                 }
@@ -490,8 +490,18 @@ var GitHubAPI = class {
         owner: repo.owner,
         name: repo.name
       });
+      if (!response.repository) {
+        throw new Error(`Repository not found: ${repo.owner}/${repo.name}`);
+      }
       return response.repository.projectsV2.nodes;
     } catch (error) {
+      if (error && typeof error === "object" && "errors" in error) {
+        const gqlError = error;
+        const notFound = gqlError.errors?.find((e) => e.type === "NOT_FOUND");
+        if (notFound) {
+          throw new Error(`Repository not found: ${repo.owner}/${repo.name}`);
+        }
+      }
       this.handleAuthError(error);
     }
   }
@@ -1082,6 +1092,7 @@ var BranchLinker = class {
 // src/git-utils.ts
 import { exec } from "child_process";
 import { promisify } from "util";
+import { homedir } from "os";
 
 // src/url-parser.ts
 function parseGitHubUrl(url) {
@@ -1134,6 +1145,28 @@ function buildOrgProjectUrl(org, projectNumber) {
 }
 
 // src/git-utils.ts
+function sanitizeForPath(input) {
+  return String(input).replace(/\.\./g, "_").replace(/[;&|`$(){}[\]<>!]/g, "").replace(/\s+/g, "-").replace(/[^a-zA-Z0-9_\-./]/g, "_");
+}
+function validateBranchName(branch) {
+  if (!branch || branch.trim().length === 0) {
+    throw new Error("Branch name cannot be empty");
+  }
+  const dangerousChars = /[`$\\!;|&<>(){}[\]'"]/;
+  if (dangerousChars.test(branch)) {
+    throw new Error(`Branch name contains invalid characters: ${branch}`);
+  }
+  const gitInvalidChars = /[\s~^:?*\[\\]/;
+  if (gitInvalidChars.test(branch)) {
+    throw new Error(`Branch name contains invalid git characters: ${branch}`);
+  }
+  if (branch.includes("..")) {
+    throw new Error(`Branch name cannot contain '..': ${branch}`);
+  }
+  if (/^[./]|[./]$/.test(branch)) {
+    throw new Error(`Branch name cannot start or end with '/' or '.': ${branch}`);
+  }
+}
 var execAsync = promisify(exec);
 async function execGit(command, options = {}) {
   const cwd = options.cwd || process.cwd();
@@ -1281,6 +1314,84 @@ async function getDefaultBranch(options = {}) {
   }
   return "master";
 }
+function validatePath(path) {
+  if (!path || path.trim().length === 0) {
+    throw new Error("Path cannot be empty");
+  }
+  const dangerousChars = /[`$;|&<>(){}[\]'"\n\r]/;
+  if (dangerousChars.test(path)) {
+    throw new Error(`Path contains invalid characters: ${path}`);
+  }
+}
+async function createWorktree(worktreePath, branch, options = {}) {
+  validateBranchName(branch);
+  validatePath(worktreePath);
+  const localExists = await branchExists(branch, options);
+  if (localExists) {
+    await execGit(`git worktree add "${worktreePath}" "${branch}"`, options);
+  } else {
+    try {
+      await execGit(`git worktree add "${worktreePath}" -b "${branch}" "origin/${branch}"`, options);
+    } catch {
+      await execGit(`git worktree add -b "${branch}" "${worktreePath}"`, options);
+    }
+  }
+}
+async function removeWorktree(worktreePath, options = {}, force = false) {
+  validatePath(worktreePath);
+  const forceFlag = force ? "--force" : "";
+  await execGit(`git worktree remove ${forceFlag} "${worktreePath}"`, options);
+}
+async function listWorktrees(options = {}) {
+  try {
+    const { stdout } = await execGit("git worktree list --porcelain", options);
+    const worktrees = [];
+    const entries = stdout.trim().split("\n\n");
+    for (const entry of entries) {
+      if (!entry.trim()) continue;
+      const lines = entry.split("\n");
+      const info = {
+        isMain: false,
+        branch: null
+      };
+      for (const line of lines) {
+        if (line.startsWith("worktree ")) {
+          info.path = line.substring(9);
+        } else if (line.startsWith("HEAD ")) {
+          info.head = line.substring(5);
+        } else if (line.startsWith("branch ")) {
+          info.branch = line.substring(7).replace(/^refs\/heads\//, "");
+        } else if (line === "bare") {
+          info.isMain = true;
+        }
+      }
+      if (worktrees.length === 0) {
+        info.isMain = true;
+      }
+      if (info.path && info.head) {
+        worktrees.push(info);
+      }
+    }
+    return worktrees;
+  } catch {
+    return [];
+  }
+}
+async function getWorktreeForBranch(branch, options = {}) {
+  const worktrees = await listWorktrees(options);
+  return worktrees.find((wt) => wt.branch === branch) || null;
+}
+async function worktreeExists(worktreePath, options = {}) {
+  const worktrees = await listWorktrees(options);
+  return worktrees.some((wt) => wt.path === worktreePath);
+}
+function generateWorktreePath(basePath, repoName, identifier) {
+  const safeRepoName = sanitizeForPath(repoName);
+  const safeIdentifier = sanitizeForPath(String(identifier));
+  const expandedBase = basePath.startsWith("~") ? basePath.replace("~", homedir()) : basePath;
+  const cleanBase = expandedBase.replace(/\/+$/, "");
+  return `${cleanBase}/${safeRepoName}/${safeIdentifier}`;
+}
 
 // src/sync.ts
 var SYNCABLE_KEYS = [
@@ -1460,10 +1571,12 @@ export {
   checkoutBranch,
   computeSettingsDiff,
   createBranch,
+  createWorktree,
   detectRepository,
   fetchOrigin,
   formatConflict,
   generateBranchName,
+  generateWorktreePath,
   getAllBranches,
   getCommitsAhead,
   getCommitsBehind,
@@ -1473,9 +1586,11 @@ export {
   getLocalBranches,
   getRemoteBranches,
   getRepositoryRoot,
+  getWorktreeForBranch,
   hasDifferences,
   hasUncommittedChanges,
   isGitRepository,
+  listWorktrees,
   normalizeVSCodeSettings,
   parseBranchLink,
   parseGitHubUrl,
@@ -1483,6 +1598,7 @@ export {
   pullLatest,
   queries_exports as queries,
   removeBranchLinkFromBody,
+  removeWorktree,
   resolveConflicts,
   sanitizeForBranchName,
   setBranchLinkInBody,
@@ -1490,5 +1606,6 @@ export {
   toVSCodeSettings,
   useCli,
   useCustom,
-  useVSCode
+  useVSCode,
+  worktreeExists
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bretwardjames/ghp-core",
-  "version": "0.1.7",
+  "version": "0.2.0-beta.1",
   "description": "Shared core library for GitHub Projects tools",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -16,12 +16,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
-  },
   "keywords": [
     "github",
     "projects",
@@ -44,5 +38,10 @@
     "@types/node": "^20.10.0",
     "tsup": "^8.0.0",
     "typescript": "^5.3.2"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit"
   }
-}
+}