@bretwardjames/ghp-core 0.8.0 → 0.10.0

package/README.md

@@ -105,6 +105,21 @@ const result = await withRetry(
 const result = await withRetry(() => api.getIssue(repo, 123), DEFAULT_RETRY_CONFIG);
 ```
 
+### Git Utilities
+
+```typescript
+import { listTags, resolveRef, createBranch } from '@bretwardjames/ghp-core';
+
+// List git tags sorted by version (newest first)
+const tags = await listTags();  // ['v1.2.0', 'v1.1.0', ...]
+
+// Validate and resolve a git ref (tag, commit, branch)
+const sha = await resolveRef('v1.2.0');  // 'abc123...' or null
+
+// Create a branch from a specific ref (for hotfixes)
+await createBranch('hotfix/fix-login', { startPoint: 'v1.2.0' });
+```
+
 ### Shell Utilities
 
 Safe shell command construction to prevent injection:
@@ -120,6 +135,11 @@ const num = validateNumericInput("123", "issue number");  // 123 or throws
 
 // Validate URLs
 validateUrl("https://github.com/...", "issue URL");  // throws if invalid
+
+// Validate git ref strings (rejects shell metacharacters)
+import { validateRefString } from '@bretwardjames/ghp-core';
+validateRefString('v1.2.0');  // ok
+validateRefString('v1; rm -rf /');  // throws Error
 ```
 
 ### Event Hooks

package/dist/index.cjs

@@ -125,6 +125,7 @@ __export(index_exports, {
   isGitRepository: () => isGitRepository,
   isTransientError: () => isTransientError,
   listAgents: () => listAgents,
+  listTags: () => listTags,
   listWorktrees: () => listWorktrees,
   loadEventHooksConfig: () => loadEventHooksConfig,
   loadHooksConfig: () => loadHooksConfig,
@@ -146,6 +147,7 @@ __export(index_exports, {
   removeWorktree: () => removeWorktree,
   removeWorktreeWorkflow: () => removeWorktreeWorkflow,
   resolveConflicts: () => resolveConflicts,
+  resolveRef: () => resolveRef,
   sanitizeForBranchName: () => sanitizeForBranchName,
   saveEventHooksConfig: () => saveEventHooksConfig,
   saveHooksConfig: () => saveHooksConfig,
@@ -335,6 +337,10 @@ var PROJECT_FIELDS_QUERY = `
                         ... on ProjectV2IterationField {
                             id
                             name
+                            configuration {
+                                iterations { id title }
+                                completedIterations { id title }
+                            }
                         }
                     }
                 }
@@ -1348,28 +1354,48 @@ var GitHubAPI = class {
   async getProjectFields(projectId) {
     if (!this.graphqlWithAuth) throw new Error("Not authenticated");
     const response = await this.graphqlWithRetry(PROJECT_FIELDS_QUERY, { projectId });
-    return response.node.fields.nodes.map((f) => ({
-      id: f.id,
-      name: f.name,
-      type: f.__typename.replace("ProjectV2", "").replace("Field", ""),
-      options: f.options
-    }));
+    return response.node.fields.nodes.map((f) => {
+      let options = f.options;
+      if (f.configuration) {
+        const all = [...f.configuration.iterations, ...f.configuration.completedIterations];
+        options = all.map((i) => ({ id: i.id, name: i.title }));
+      }
+      return {
+        id: f.id,
+        name: f.name,
+        type: f.__typename.replace("ProjectV2", "").replace("Field", ""),
+        options
+      };
+    });
   }
   /**
-   * Set a field value on a project item
+   * Set a field value on a project item.
+   * Routes SingleSelect fields through the inline mutation pattern
+   * (passing the option ID as a scalar variable) since GitHub's API
+   * does not reliably deserialize ProjectV2FieldValue input objects.
    */
   async setFieldValue(projectId, itemId, fieldId, value) {
     if (!this.graphqlWithAuth) throw new Error("Not authenticated");
     try {
-      await this.graphqlWithRetry(UPDATE_ITEM_FIELD_MUTATION, {
-        projectId,
-        itemId,
-        fieldId,
-        value
-      });
-      return true;
-    } catch {
-      return false;
+      if (value.singleSelectOptionId) {
+        await this.graphqlWithRetry(UPDATE_ITEM_STATUS_MUTATION, {
+          projectId,
+          itemId,
+          fieldId,
+          optionId: value.singleSelectOptionId
+        });
+      } else {
+        await this.graphqlWithRetry(UPDATE_ITEM_FIELD_MUTATION, {
+          projectId,
+          itemId,
+          fieldId,
+          value
+        });
+      }
+      return { success: true };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { success: false, error: message };
     }
   }
   /**
@@ -2333,6 +2359,15 @@ function buildOrgProjectUrl(org, projectNumber) {
 function sanitizeForPath(input) {
   return String(input).replace(/\.\./g, "_").replace(/[;&|`$(){}[\]<>!]/g, "").replace(/\s+/g, "-").replace(/[^a-zA-Z0-9_\-./]/g, "_");
 }
+function validateRefString(ref) {
+  if (!ref || ref.trim().length === 0) {
+    throw new Error("Ref cannot be empty");
+  }
+  const dangerousChars = /[`$\\!;|&<>(){}[\]'"]/;
+  if (dangerousChars.test(ref)) {
+    throw new Error(`Ref contains invalid characters: ${ref}`);
+  }
+}
 function validateBranchName(branch) {
   if (!branch || branch.trim().length === 0) {
     throw new Error("Branch name cannot be empty");
@@ -2393,7 +2428,11 @@ async function branchExists(branchName, options = {}) {
   }
 }
 async function createBranch(branchName, options = {}) {
-  await execGit(`git checkout -b "${branchName}"`, options);
+  if (options.startPoint) {
+    validateRefString(options.startPoint);
+  }
+  const cmd = options.startPoint ? `git checkout -b "${branchName}" "${options.startPoint}"` : `git checkout -b "${branchName}"`;
+  await execGit(cmd, options);
 }
 async function checkoutBranch(branchName, options = {}) {
   await execGit(`git checkout "${branchName}"`, options);
@@ -2465,6 +2504,23 @@ function extractIssueNumberFromBranch(branchName) {
   }
   return null;
 }
+async function listTags(options = {}) {
+  try {
+    const { stdout } = await execGit("git tag -l --sort=-version:refname", options);
+    return stdout.split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+async function resolveRef(ref, options = {}) {
+  validateRefString(ref);
+  try {
+    const { stdout } = await execGit(`git rev-parse --verify "${ref}"`, options);
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
 async function getLocalBranches(options = {}) {
   const { stdout } = await execGit('git branch --format="%(refname:short)"', options);
   return stdout.split("\n").map((b) => b.trim()).filter((b) => b.length > 0);
@@ -5924,6 +5980,7 @@ EOF
   isGitRepository,
   isTransientError,
   listAgents,
+  listTags,
   listWorktrees,
   loadEventHooksConfig,
   loadHooksConfig,
@@ -5945,6 +6002,7 @@ EOF
   removeWorktree,
   removeWorktreeWorkflow,
   resolveConflicts,
+  resolveRef,
   sanitizeForBranchName,
   saveEventHooksConfig,
   saveHooksConfig,

package/dist/index.d.cts

@@ -557,13 +557,21 @@ declare class GitHubAPI {
         }>;
     }>>;
     /**
-     * Set a field value on a project item
+     * Set a field value on a project item.
+     * Routes SingleSelect fields through the inline mutation pattern
+     * (passing the option ID as a scalar variable) since GitHub's API
+     * does not reliably deserialize ProjectV2FieldValue input objects.
      */
     setFieldValue(projectId: string, itemId: string, fieldId: string, value: {
         text?: string;
         number?: number;
         singleSelectOptionId?: string;
-    }): Promise<boolean>;
+        date?: string;
+        iterationId?: string;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
     /**
      * Create a new issue
      */
@@ -790,9 +798,13 @@ declare function hasUncommittedChanges(options?: GitOptions): Promise<boolean>;
 declare function branchExists(branchName: string, options?: GitOptions): Promise<boolean>;
 /**
  * Create and checkout a new branch.
+ * @param branchName - Name for the new branch
+ * @param options - Git options. Use `startPoint` to branch from a specific tag, commit, or ref.
  * @throws {GitError} If the branch cannot be created (e.g., already exists, invalid name)
  */
-declare function createBranch(branchName: string, options?: GitOptions): Promise<void>;
+declare function createBranch(branchName: string, options?: GitOptions & {
+    startPoint?: string;
+}): Promise<void>;
 /**
  * Checkout an existing branch.
  * @throws {GitError} If the branch cannot be checked out (e.g., doesn't exist, uncommitted changes)
@@ -852,6 +864,19 @@ declare function generateBranchName(pattern: string, vars: {
  * - ends with #123 or /123
  */
 declare function extractIssueNumberFromBranch(branchName: string): number | null;
+/**
+ * List git tags, sorted by version (highest version first, using semantic version ordering).
+ * @param options - Git options
+ * @returns Array of tag names, highest version first
+ */
+declare function listTags(options?: GitOptions): Promise<string[]>;
+/**
+ * Verify that a git ref (tag, commit, branch) exists and resolve it to a commit hash.
+ * @param ref - Tag name, commit hash, or branch name
+ * @param options - Git options
+ * @returns The resolved commit hash, or null if the ref doesn't exist
+ */
+declare function resolveRef(ref: string, options?: GitOptions): Promise<string | null>;
 /**
  * Get all local branches.
  * @throws {GitError} If the git command fails (e.g., not a git repo)
@@ -1162,7 +1187,7 @@ declare const PROJECT_ITEMS_QUERY = "\n    query($projectId: ID!, $cursor: Strin
 /**
  * Query to get project fields (including status options)
  */
-declare const PROJECT_FIELDS_QUERY = "\n    query($projectId: ID!) {\n        node(id: $projectId) {\n            ... on ProjectV2 {\n                fields(first: 30) {\n                    nodes {\n                        __typename\n                        ... on ProjectV2Field {\n                            id\n                            name\n                        }\n                        ... on ProjectV2SingleSelectField {\n                            id\n                            name\n                            options { id name }\n                        }\n                        ... on ProjectV2IterationField {\n                            id\n                            name\n                        }\n                    }\n                }\n            }\n        }\n    }\n";
+declare const PROJECT_FIELDS_QUERY = "\n    query($projectId: ID!) {\n        node(id: $projectId) {\n            ... on ProjectV2 {\n                fields(first: 30) {\n                    nodes {\n                        __typename\n                        ... on ProjectV2Field {\n                            id\n                            name\n                        }\n                        ... on ProjectV2SingleSelectField {\n                            id\n                            name\n                            options { id name }\n                        }\n                        ... on ProjectV2IterationField {\n                            id\n                            name\n                            configuration {\n                                iterations { id title }\n                                completedIterations { id title }\n                            }\n                        }\n                    }\n                }\n            }\n        }\n    }\n";
 /**
  * Query to get project views
  */
@@ -3334,4 +3359,4 @@ declare function shouldAbort(results: HookResult[]): boolean;
  */
 declare function hasHooksForEvent(event: EventType): boolean;
 
-export { type ActivityEvent, type AgentInstance, type AgentRegistry, type AgentSessionStatus, type AgentStatus, type AgentSummary, type ApiKeyProvider, type AssigneeInfo, type AuthError, type BaseEventPayload, type BlockingIssue, type BlockingRelationships, type BranchDashboardData, BranchLinker, CLI_TO_VSCODE_MAP, ClaudeClient, type ClaudeClientOptions, type ClaudeResult, type ClaudeTool, type Collaborator, type Commit, type ConflictChoices, type ConflictResolution, type ContentBlock, type CreateIssueOptions, type CreateIssueResult, type CreatePROptions, type CreatePRResult, type CreateWorktreeOptions, type CreateWorktreeResult, DEFAULT_RETRY_CONFIG, DEFAULT_VALUES, type DashboardHook, type DashboardOptions, type DateFieldValue, type DiffStats, type EventHook, type EventHookSettings, type EventHooksConfig, type EventPayload, type EventType, type ExpandIssueOptions, type ExpandedIssue, type FieldInfo, type FieldValue, type FieldValueConnection, type FileChange, type FormatStandupOptions, GHP_TOOLS, type GeneratePRDescriptionOptions, GitError, GitHubAPI, type GitHubAPIOptions, type GitOptions, type HookExecutionOptions, type HookExecutionResult, type HookExitCodes, type HookItem, type HookMode, type HookOutcome, type HookResponse, type HookResult, type HooksConfig, type IssueActivity, type IssueCreatedPayload, type IssueDetails, type IssueReference, type IssueRelationships, type IssueStartedPayload, type IterationFieldValue, type LabelInfo, type Message, type NumberFieldValue, type OnFailureBehavior, type PRInfo, type PermissionPrompt, type PlanEpicOptions, type PlanEpicResult, type PrCreatedPayload, type PrCreatingPayload, type PrMergedPayload, type PrePrPayload, type Project, type ProjectConfig, type ProjectConventions, type ProjectItem, type ProjectItemContent, type ProjectItemsQueryResponse, type ProjectV2, type ProjectV2Field, type ProjectV2Item, type ProjectV2View, type ProjectWithViews, type ProjectsQueryResponse, type RegisterAgentOptions, type RelatedIssue, type RemoveWorktreeOptions, type RemoveWorktreeResult, type RepoInfo, type ResolvedClaudeConfig, type ResolvedSettings, type RetryConfig, SETTING_DISPLAY_NAMES, SYNCABLE_KEYS, type SessionEvent, SessionWatcher, type SettingConflict, type SettingsDiff, type SettingsSource, type SingleSelectFieldValue, type StartIssueOptions, type StartIssueResult, type StatusField, type StreamCallbacks, type StreamErrorEvent, type StreamEvent, type StreamEventBase, type StreamMessageCompleteEvent, type StreamOptions, type StreamTextEvent, type StreamToolInputDeltaEvent, type StreamToolUseCompleteEvent, type StreamToolUseStartEvent, type SyncableSettingKey, type SyncableSettings, TOOL_NAMES, type TextFieldValue, type TokenProvider, type TokenUsage, type ToolContext, type ToolHandler, type ToolHandlers, type UpdateAgentOptions, VSCODE_TO_CLI_MAP, type IssueInfo as WorkflowIssueInfo, type WorkflowResult, type WorktreeInfo as WorkflowWorktreeInfo, type WorktreeCreatedPayload, type WorktreeInfo$1 as WorktreeInfo, type WorktreeRemovedPayload, addEventHook, addHook, branchExists, buildConventionsContext, buildIssueUrl, buildOrgProjectUrl, buildProjectUrl, buildPullRequestUrl, buildRepoUrl, calculateBackoffDelay, checkTmuxForPermission, checkoutBranch, index as claudePrompts, cleanupStaleAgents, computeSettingsDiff, createBranch, createIssueWorkflow, createPRWorkflow, createSessionWatcher, createWorktree, createWorktreeWorkflow, detectRepository, disableEventHook, disableHook, enableEventHook, enableHook, executeAllHooks, executeEventHook, executeHook, executeHooksForEvent, extractIssueNumberFromBranch, fetchOrigin, findSessionFile, formatAction, formatConflict, formatStandupText, gatherDashboardData, generateBranchName, generateWorktreePath, getAgent, getAgentByIssue, getAgentSummaries, getAllBranches, getChangedFiles, getCommitHistory, getCommitsAhead, getCommitsBehind, getCurrentBranch$1 as getCurrentBranch, getCurrentBranch as getDashboardCurrentBranch, getDefaultBaseBranch, getDefaultBranch, getDiffStats, getDiffSummary, getEnabledEventHooks, getEnabledHooks, getEventHook, getEventHooks, getEventHooksConfigPath, getEventSettings, getFullDiff, getGitHubRepo, getHook, getHooks, getHooksByCategory, getHooksConfigPath, getHooksForEvent, getIssueReferenceText, getLocalBranches, getRegistryPath, getRemoteBranches, getRepositoryRoot, getTools, getValidEventTypes, getValidModes, getValidOnFailureBehaviors, getWorktreeForBranch, hasDifferences, hasHooksForEvent, hasUncommittedChanges, isGitRepository, isTransientError, listAgents, listWorktrees, loadEventHooksConfig, loadHooksConfig, loadProjectConventions, loadRegistry, normalizeVSCodeSettings, parseBranchLink, parseGitHubUrl, parseIssueUrl, parseRateLimitDelay, parseSessionLine, parseSince, pullLatest, queries, registerAgent, removeBranchLinkFromBody, removeEventHook, removeHook, removeWorktree, removeWorktreeWorkflow, resolveConflicts, sanitizeForBranchName, saveEventHooksConfig, saveHooksConfig, saveRegistry, setBranchLinkInBody, shellEscape, shouldAbort, skip, startIssueWorkflow, substituteTemplateVariables, toVSCodeSettings, unregisterAgent, updateAgent, updateEventHook, updateHook, useCli, useCustom, useVSCode, validateNumericInput, validateSafeString, validateUrl, withRetry, worktreeExists, wrapWithRetry };
+export { type ActivityEvent, type AgentInstance, type AgentRegistry, type AgentSessionStatus, type AgentStatus, type AgentSummary, type ApiKeyProvider, type AssigneeInfo, type AuthError, type BaseEventPayload, type BlockingIssue, type BlockingRelationships, type BranchDashboardData, BranchLinker, CLI_TO_VSCODE_MAP, ClaudeClient, type ClaudeClientOptions, type ClaudeResult, type ClaudeTool, type Collaborator, type Commit, type ConflictChoices, type ConflictResolution, type ContentBlock, type CreateIssueOptions, type CreateIssueResult, type CreatePROptions, type CreatePRResult, type CreateWorktreeOptions, type CreateWorktreeResult, DEFAULT_RETRY_CONFIG, DEFAULT_VALUES, type DashboardHook, type DashboardOptions, type DateFieldValue, type DiffStats, type EventHook, type EventHookSettings, type EventHooksConfig, type EventPayload, type EventType, type ExpandIssueOptions, type ExpandedIssue, type FieldInfo, type FieldValue, type FieldValueConnection, type FileChange, type FormatStandupOptions, GHP_TOOLS, type GeneratePRDescriptionOptions, GitError, GitHubAPI, type GitHubAPIOptions, type GitOptions, type HookExecutionOptions, type HookExecutionResult, type HookExitCodes, type HookItem, type HookMode, type HookOutcome, type HookResponse, type HookResult, type HooksConfig, type IssueActivity, type IssueCreatedPayload, type IssueDetails, type IssueReference, type IssueRelationships, type IssueStartedPayload, type IterationFieldValue, type LabelInfo, type Message, type NumberFieldValue, type OnFailureBehavior, type PRInfo, type PermissionPrompt, type PlanEpicOptions, type PlanEpicResult, type PrCreatedPayload, type PrCreatingPayload, type PrMergedPayload, type PrePrPayload, type Project, type ProjectConfig, type ProjectConventions, type ProjectItem, type ProjectItemContent, type ProjectItemsQueryResponse, type ProjectV2, type ProjectV2Field, type ProjectV2Item, type ProjectV2View, type ProjectWithViews, type ProjectsQueryResponse, type RegisterAgentOptions, type RelatedIssue, type RemoveWorktreeOptions, type RemoveWorktreeResult, type RepoInfo, type ResolvedClaudeConfig, type ResolvedSettings, type RetryConfig, SETTING_DISPLAY_NAMES, SYNCABLE_KEYS, type SessionEvent, SessionWatcher, type SettingConflict, type SettingsDiff, type SettingsSource, type SingleSelectFieldValue, type StartIssueOptions, type StartIssueResult, type StatusField, type StreamCallbacks, type StreamErrorEvent, type StreamEvent, type StreamEventBase, type StreamMessageCompleteEvent, type StreamOptions, type StreamTextEvent, type StreamToolInputDeltaEvent, type StreamToolUseCompleteEvent, type StreamToolUseStartEvent, type SyncableSettingKey, type SyncableSettings, TOOL_NAMES, type TextFieldValue, type TokenProvider, type TokenUsage, type ToolContext, type ToolHandler, type ToolHandlers, type UpdateAgentOptions, VSCODE_TO_CLI_MAP, type IssueInfo as WorkflowIssueInfo, type WorkflowResult, type WorktreeInfo as WorkflowWorktreeInfo, type WorktreeCreatedPayload, type WorktreeInfo$1 as WorktreeInfo, type WorktreeRemovedPayload, addEventHook, addHook, branchExists, buildConventionsContext, buildIssueUrl, buildOrgProjectUrl, buildProjectUrl, buildPullRequestUrl, buildRepoUrl, calculateBackoffDelay, checkTmuxForPermission, checkoutBranch, index as claudePrompts, cleanupStaleAgents, computeSettingsDiff, createBranch, createIssueWorkflow, createPRWorkflow, createSessionWatcher, createWorktree, createWorktreeWorkflow, detectRepository, disableEventHook, disableHook, enableEventHook, enableHook, executeAllHooks, executeEventHook, executeHook, executeHooksForEvent, extractIssueNumberFromBranch, fetchOrigin, findSessionFile, formatAction, formatConflict, formatStandupText, gatherDashboardData, generateBranchName, generateWorktreePath, getAgent, getAgentByIssue, getAgentSummaries, getAllBranches, getChangedFiles, getCommitHistory, getCommitsAhead, getCommitsBehind, getCurrentBranch$1 as getCurrentBranch, getCurrentBranch as getDashboardCurrentBranch, getDefaultBaseBranch, getDefaultBranch, getDiffStats, getDiffSummary, getEnabledEventHooks, getEnabledHooks, getEventHook, getEventHooks, getEventHooksConfigPath, getEventSettings, getFullDiff, getGitHubRepo, getHook, getHooks, getHooksByCategory, getHooksConfigPath, getHooksForEvent, getIssueReferenceText, getLocalBranches, getRegistryPath, getRemoteBranches, getRepositoryRoot, getTools, getValidEventTypes, getValidModes, getValidOnFailureBehaviors, getWorktreeForBranch, hasDifferences, hasHooksForEvent, hasUncommittedChanges, isGitRepository, isTransientError, listAgents, listTags, listWorktrees, loadEventHooksConfig, loadHooksConfig, loadProjectConventions, loadRegistry, normalizeVSCodeSettings, parseBranchLink, parseGitHubUrl, parseIssueUrl, parseRateLimitDelay, parseSessionLine, parseSince, pullLatest, queries, registerAgent, removeBranchLinkFromBody, removeEventHook, removeHook, removeWorktree, removeWorktreeWorkflow, resolveConflicts, resolveRef, sanitizeForBranchName, saveEventHooksConfig, saveHooksConfig, saveRegistry, setBranchLinkInBody, shellEscape, shouldAbort, skip, startIssueWorkflow, substituteTemplateVariables, toVSCodeSettings, unregisterAgent, updateAgent, updateEventHook, updateHook, useCli, useCustom, useVSCode, validateNumericInput, validateSafeString, validateUrl, withRetry, worktreeExists, wrapWithRetry };

package/dist/index.d.ts

@@ -557,13 +557,21 @@ declare class GitHubAPI {
         }>;
     }>>;
     /**
-     * Set a field value on a project item
+     * Set a field value on a project item.
+     * Routes SingleSelect fields through the inline mutation pattern
+     * (passing the option ID as a scalar variable) since GitHub's API
+     * does not reliably deserialize ProjectV2FieldValue input objects.
      */
     setFieldValue(projectId: string, itemId: string, fieldId: string, value: {
         text?: string;
         number?: number;
         singleSelectOptionId?: string;
-    }): Promise<boolean>;
+        date?: string;
+        iterationId?: string;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
     /**
      * Create a new issue
      */
@@ -790,9 +798,13 @@ declare function hasUncommittedChanges(options?: GitOptions): Promise<boolean>;
 declare function branchExists(branchName: string, options?: GitOptions): Promise<boolean>;
 /**
  * Create and checkout a new branch.
+ * @param branchName - Name for the new branch
+ * @param options - Git options. Use `startPoint` to branch from a specific tag, commit, or ref.
  * @throws {GitError} If the branch cannot be created (e.g., already exists, invalid name)
  */
-declare function createBranch(branchName: string, options?: GitOptions): Promise<void>;
+declare function createBranch(branchName: string, options?: GitOptions & {
+    startPoint?: string;
+}): Promise<void>;
 /**
  * Checkout an existing branch.
  * @throws {GitError} If the branch cannot be checked out (e.g., doesn't exist, uncommitted changes)
@@ -852,6 +864,19 @@ declare function generateBranchName(pattern: string, vars: {
  * - ends with #123 or /123
  */
 declare function extractIssueNumberFromBranch(branchName: string): number | null;
+/**
+ * List git tags, sorted by version (highest version first, using semantic version ordering).
+ * @param options - Git options
+ * @returns Array of tag names, highest version first
+ */
+declare function listTags(options?: GitOptions): Promise<string[]>;
+/**
+ * Verify that a git ref (tag, commit, branch) exists and resolve it to a commit hash.
+ * @param ref - Tag name, commit hash, or branch name
+ * @param options - Git options
+ * @returns The resolved commit hash, or null if the ref doesn't exist
+ */
+declare function resolveRef(ref: string, options?: GitOptions): Promise<string | null>;
 /**
  * Get all local branches.
  * @throws {GitError} If the git command fails (e.g., not a git repo)
@@ -1162,7 +1187,7 @@ declare const PROJECT_ITEMS_QUERY = "\n    query($projectId: ID!, $cursor: Strin
 /**
  * Query to get project fields (including status options)
  */
-declare const PROJECT_FIELDS_QUERY = "\n    query($projectId: ID!) {\n        node(id: $projectId) {\n            ... on ProjectV2 {\n                fields(first: 30) {\n                    nodes {\n                        __typename\n                        ... on ProjectV2Field {\n                            id\n                            name\n                        }\n                        ... on ProjectV2SingleSelectField {\n                            id\n                            name\n                            options { id name }\n                        }\n                        ... on ProjectV2IterationField {\n                            id\n                            name\n                        }\n                    }\n                }\n            }\n        }\n    }\n";
+declare const PROJECT_FIELDS_QUERY = "\n    query($projectId: ID!) {\n        node(id: $projectId) {\n            ... on ProjectV2 {\n                fields(first: 30) {\n                    nodes {\n                        __typename\n                        ... on ProjectV2Field {\n                            id\n                            name\n                        }\n                        ... on ProjectV2SingleSelectField {\n                            id\n                            name\n                            options { id name }\n                        }\n                        ... on ProjectV2IterationField {\n                            id\n                            name\n                            configuration {\n                                iterations { id title }\n                                completedIterations { id title }\n                            }\n                        }\n                    }\n                }\n            }\n        }\n    }\n";
 /**
  * Query to get project views
  */
@@ -3334,4 +3359,4 @@ declare function shouldAbort(results: HookResult[]): boolean;
  */
 declare function hasHooksForEvent(event: EventType): boolean;
 
-export { type ActivityEvent, type AgentInstance, type AgentRegistry, type AgentSessionStatus, type AgentStatus, type AgentSummary, type ApiKeyProvider, type AssigneeInfo, type AuthError, type BaseEventPayload, type BlockingIssue, type BlockingRelationships, type BranchDashboardData, BranchLinker, CLI_TO_VSCODE_MAP, ClaudeClient, type ClaudeClientOptions, type ClaudeResult, type ClaudeTool, type Collaborator, type Commit, type ConflictChoices, type ConflictResolution, type ContentBlock, type CreateIssueOptions, type CreateIssueResult, type CreatePROptions, type CreatePRResult, type CreateWorktreeOptions, type CreateWorktreeResult, DEFAULT_RETRY_CONFIG, DEFAULT_VALUES, type DashboardHook, type DashboardOptions, type DateFieldValue, type DiffStats, type EventHook, type EventHookSettings, type EventHooksConfig, type EventPayload, type EventType, type ExpandIssueOptions, type ExpandedIssue, type FieldInfo, type FieldValue, type FieldValueConnection, type FileChange, type FormatStandupOptions, GHP_TOOLS, type GeneratePRDescriptionOptions, GitError, GitHubAPI, type GitHubAPIOptions, type GitOptions, type HookExecutionOptions, type HookExecutionResult, type HookExitCodes, type HookItem, type HookMode, type HookOutcome, type HookResponse, type HookResult, type HooksConfig, type IssueActivity, type IssueCreatedPayload, type IssueDetails, type IssueReference, type IssueRelationships, type IssueStartedPayload, type IterationFieldValue, type LabelInfo, type Message, type NumberFieldValue, type OnFailureBehavior, type PRInfo, type PermissionPrompt, type PlanEpicOptions, type PlanEpicResult, type PrCreatedPayload, type PrCreatingPayload, type PrMergedPayload, type PrePrPayload, type Project, type ProjectConfig, type ProjectConventions, type ProjectItem, type ProjectItemContent, type ProjectItemsQueryResponse, type ProjectV2, type ProjectV2Field, type ProjectV2Item, type ProjectV2View, type ProjectWithViews, type ProjectsQueryResponse, type RegisterAgentOptions, type RelatedIssue, type RemoveWorktreeOptions, type RemoveWorktreeResult, type RepoInfo, type ResolvedClaudeConfig, type ResolvedSettings, type RetryConfig, SETTING_DISPLAY_NAMES, SYNCABLE_KEYS, type SessionEvent, SessionWatcher, type SettingConflict, type SettingsDiff, type SettingsSource, type SingleSelectFieldValue, type StartIssueOptions, type StartIssueResult, type StatusField, type StreamCallbacks, type StreamErrorEvent, type StreamEvent, type StreamEventBase, type StreamMessageCompleteEvent, type StreamOptions, type StreamTextEvent, type StreamToolInputDeltaEvent, type StreamToolUseCompleteEvent, type StreamToolUseStartEvent, type SyncableSettingKey, type SyncableSettings, TOOL_NAMES, type TextFieldValue, type TokenProvider, type TokenUsage, type ToolContext, type ToolHandler, type ToolHandlers, type UpdateAgentOptions, VSCODE_TO_CLI_MAP, type IssueInfo as WorkflowIssueInfo, type WorkflowResult, type WorktreeInfo as WorkflowWorktreeInfo, type WorktreeCreatedPayload, type WorktreeInfo$1 as WorktreeInfo, type WorktreeRemovedPayload, addEventHook, addHook, branchExists, buildConventionsContext, buildIssueUrl, buildOrgProjectUrl, buildProjectUrl, buildPullRequestUrl, buildRepoUrl, calculateBackoffDelay, checkTmuxForPermission, checkoutBranch, index as claudePrompts, cleanupStaleAgents, computeSettingsDiff, createBranch, createIssueWorkflow, createPRWorkflow, createSessionWatcher, createWorktree, createWorktreeWorkflow, detectRepository, disableEventHook, disableHook, enableEventHook, enableHook, executeAllHooks, executeEventHook, executeHook, executeHooksForEvent, extractIssueNumberFromBranch, fetchOrigin, findSessionFile, formatAction, formatConflict, formatStandupText, gatherDashboardData, generateBranchName, generateWorktreePath, getAgent, getAgentByIssue, getAgentSummaries, getAllBranches, getChangedFiles, getCommitHistory, getCommitsAhead, getCommitsBehind, getCurrentBranch$1 as getCurrentBranch, getCurrentBranch as getDashboardCurrentBranch, getDefaultBaseBranch, getDefaultBranch, getDiffStats, getDiffSummary, getEnabledEventHooks, getEnabledHooks, getEventHook, getEventHooks, getEventHooksConfigPath, getEventSettings, getFullDiff, getGitHubRepo, getHook, getHooks, getHooksByCategory, getHooksConfigPath, getHooksForEvent, getIssueReferenceText, getLocalBranches, getRegistryPath, getRemoteBranches, getRepositoryRoot, getTools, getValidEventTypes, getValidModes, getValidOnFailureBehaviors, getWorktreeForBranch, hasDifferences, hasHooksForEvent, hasUncommittedChanges, isGitRepository, isTransientError, listAgents, listWorktrees, loadEventHooksConfig, loadHooksConfig, loadProjectConventions, loadRegistry, normalizeVSCodeSettings, parseBranchLink, parseGitHubUrl, parseIssueUrl, parseRateLimitDelay, parseSessionLine, parseSince, pullLatest, queries, registerAgent, removeBranchLinkFromBody, removeEventHook, removeHook, removeWorktree, removeWorktreeWorkflow, resolveConflicts, sanitizeForBranchName, saveEventHooksConfig, saveHooksConfig, saveRegistry, setBranchLinkInBody, shellEscape, shouldAbort, skip, startIssueWorkflow, substituteTemplateVariables, toVSCodeSettings, unregisterAgent, updateAgent, updateEventHook, updateHook, useCli, useCustom, useVSCode, validateNumericInput, validateSafeString, validateUrl, withRetry, worktreeExists, wrapWithRetry };
+export { type ActivityEvent, type AgentInstance, type AgentRegistry, type AgentSessionStatus, type AgentStatus, type AgentSummary, type ApiKeyProvider, type AssigneeInfo, type AuthError, type BaseEventPayload, type BlockingIssue, type BlockingRelationships, type BranchDashboardData, BranchLinker, CLI_TO_VSCODE_MAP, ClaudeClient, type ClaudeClientOptions, type ClaudeResult, type ClaudeTool, type Collaborator, type Commit, type ConflictChoices, type ConflictResolution, type ContentBlock, type CreateIssueOptions, type CreateIssueResult, type CreatePROptions, type CreatePRResult, type CreateWorktreeOptions, type CreateWorktreeResult, DEFAULT_RETRY_CONFIG, DEFAULT_VALUES, type DashboardHook, type DashboardOptions, type DateFieldValue, type DiffStats, type EventHook, type EventHookSettings, type EventHooksConfig, type EventPayload, type EventType, type ExpandIssueOptions, type ExpandedIssue, type FieldInfo, type FieldValue, type FieldValueConnection, type FileChange, type FormatStandupOptions, GHP_TOOLS, type GeneratePRDescriptionOptions, GitError, GitHubAPI, type GitHubAPIOptions, type GitOptions, type HookExecutionOptions, type HookExecutionResult, type HookExitCodes, type HookItem, type HookMode, type HookOutcome, type HookResponse, type HookResult, type HooksConfig, type IssueActivity, type IssueCreatedPayload, type IssueDetails, type IssueReference, type IssueRelationships, type IssueStartedPayload, type IterationFieldValue, type LabelInfo, type Message, type NumberFieldValue, type OnFailureBehavior, type PRInfo, type PermissionPrompt, type PlanEpicOptions, type PlanEpicResult, type PrCreatedPayload, type PrCreatingPayload, type PrMergedPayload, type PrePrPayload, type Project, type ProjectConfig, type ProjectConventions, type ProjectItem, type ProjectItemContent, type ProjectItemsQueryResponse, type ProjectV2, type ProjectV2Field, type ProjectV2Item, type ProjectV2View, type ProjectWithViews, type ProjectsQueryResponse, type RegisterAgentOptions, type RelatedIssue, type RemoveWorktreeOptions, type RemoveWorktreeResult, type RepoInfo, type ResolvedClaudeConfig, type ResolvedSettings, type RetryConfig, SETTING_DISPLAY_NAMES, SYNCABLE_KEYS, type SessionEvent, SessionWatcher, type SettingConflict, type SettingsDiff, type SettingsSource, type SingleSelectFieldValue, type StartIssueOptions, type StartIssueResult, type StatusField, type StreamCallbacks, type StreamErrorEvent, type StreamEvent, type StreamEventBase, type StreamMessageCompleteEvent, type StreamOptions, type StreamTextEvent, type StreamToolInputDeltaEvent, type StreamToolUseCompleteEvent, type StreamToolUseStartEvent, type SyncableSettingKey, type SyncableSettings, TOOL_NAMES, type TextFieldValue, type TokenProvider, type TokenUsage, type ToolContext, type ToolHandler, type ToolHandlers, type UpdateAgentOptions, VSCODE_TO_CLI_MAP, type IssueInfo as WorkflowIssueInfo, type WorkflowResult, type WorktreeInfo as WorkflowWorktreeInfo, type WorktreeCreatedPayload, type WorktreeInfo$1 as WorktreeInfo, type WorktreeRemovedPayload, addEventHook, addHook, branchExists, buildConventionsContext, buildIssueUrl, buildOrgProjectUrl, buildProjectUrl, buildPullRequestUrl, buildRepoUrl, calculateBackoffDelay, checkTmuxForPermission, checkoutBranch, index as claudePrompts, cleanupStaleAgents, computeSettingsDiff, createBranch, createIssueWorkflow, createPRWorkflow, createSessionWatcher, createWorktree, createWorktreeWorkflow, detectRepository, disableEventHook, disableHook, enableEventHook, enableHook, executeAllHooks, executeEventHook, executeHook, executeHooksForEvent, extractIssueNumberFromBranch, fetchOrigin, findSessionFile, formatAction, formatConflict, formatStandupText, gatherDashboardData, generateBranchName, generateWorktreePath, getAgent, getAgentByIssue, getAgentSummaries, getAllBranches, getChangedFiles, getCommitHistory, getCommitsAhead, getCommitsBehind, getCurrentBranch$1 as getCurrentBranch, getCurrentBranch as getDashboardCurrentBranch, getDefaultBaseBranch, getDefaultBranch, getDiffStats, getDiffSummary, getEnabledEventHooks, getEnabledHooks, getEventHook, getEventHooks, getEventHooksConfigPath, getEventSettings, getFullDiff, getGitHubRepo, getHook, getHooks, getHooksByCategory, getHooksConfigPath, getHooksForEvent, getIssueReferenceText, getLocalBranches, getRegistryPath, getRemoteBranches, getRepositoryRoot, getTools, getValidEventTypes, getValidModes, getValidOnFailureBehaviors, getWorktreeForBranch, hasDifferences, hasHooksForEvent, hasUncommittedChanges, isGitRepository, isTransientError, listAgents, listTags, listWorktrees, loadEventHooksConfig, loadHooksConfig, loadProjectConventions, loadRegistry, normalizeVSCodeSettings, parseBranchLink, parseGitHubUrl, parseIssueUrl, parseRateLimitDelay, parseSessionLine, parseSince, pullLatest, queries, registerAgent, removeBranchLinkFromBody, removeEventHook, removeHook, removeWorktree, removeWorktreeWorkflow, resolveConflicts, resolveRef, sanitizeForBranchName, saveEventHooksConfig, saveHooksConfig, saveRegistry, setBranchLinkInBody, shellEscape, shouldAbort, skip, startIssueWorkflow, substituteTemplateVariables, toVSCodeSettings, unregisterAgent, updateAgent, updateEventHook, updateHook, useCli, useCustom, useVSCode, validateNumericInput, validateSafeString, validateUrl, withRetry, worktreeExists, wrapWithRetry };

package/dist/index.js

@@ -166,6 +166,10 @@ var PROJECT_FIELDS_QUERY = `
                         ... on ProjectV2IterationField {
                             id
                             name
+                            configuration {
+                                iterations { id title }
+                                completedIterations { id title }
+                            }
                         }
                     }
                 }
@@ -1179,28 +1183,48 @@ var GitHubAPI = class {
   async getProjectFields(projectId) {
     if (!this.graphqlWithAuth) throw new Error("Not authenticated");
     const response = await this.graphqlWithRetry(PROJECT_FIELDS_QUERY, { projectId });
-    return response.node.fields.nodes.map((f) => ({
-      id: f.id,
-      name: f.name,
-      type: f.__typename.replace("ProjectV2", "").replace("Field", ""),
-      options: f.options
-    }));
+    return response.node.fields.nodes.map((f) => {
+      let options = f.options;
+      if (f.configuration) {
+        const all = [...f.configuration.iterations, ...f.configuration.completedIterations];
+        options = all.map((i) => ({ id: i.id, name: i.title }));
+      }
+      return {
+        id: f.id,
+        name: f.name,
+        type: f.__typename.replace("ProjectV2", "").replace("Field", ""),
+        options
+      };
+    });
   }
   /**
-   * Set a field value on a project item
+   * Set a field value on a project item.
+   * Routes SingleSelect fields through the inline mutation pattern
+   * (passing the option ID as a scalar variable) since GitHub's API
+   * does not reliably deserialize ProjectV2FieldValue input objects.
    */
   async setFieldValue(projectId, itemId, fieldId, value) {
     if (!this.graphqlWithAuth) throw new Error("Not authenticated");
     try {
-      await this.graphqlWithRetry(UPDATE_ITEM_FIELD_MUTATION, {
-        projectId,
-        itemId,
-        fieldId,
-        value
-      });
-      return true;
-    } catch {
-      return false;
+      if (value.singleSelectOptionId) {
+        await this.graphqlWithRetry(UPDATE_ITEM_STATUS_MUTATION, {
+          projectId,
+          itemId,
+          fieldId,
+          optionId: value.singleSelectOptionId
+        });
+      } else {
+        await this.graphqlWithRetry(UPDATE_ITEM_FIELD_MUTATION, {
+          projectId,
+          itemId,
+          fieldId,
+          value
+        });
+      }
+      return { success: true };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { success: false, error: message };
     }
   }
   /**
@@ -2164,6 +2188,15 @@ function buildOrgProjectUrl(org, projectNumber) {
 function sanitizeForPath(input) {
   return String(input).replace(/\.\./g, "_").replace(/[;&|`$(){}[\]<>!]/g, "").replace(/\s+/g, "-").replace(/[^a-zA-Z0-9_\-./]/g, "_");
 }
+function validateRefString(ref) {
+  if (!ref || ref.trim().length === 0) {
+    throw new Error("Ref cannot be empty");
+  }
+  const dangerousChars = /[`$\\!;|&<>(){}[\]'"]/;
+  if (dangerousChars.test(ref)) {
+    throw new Error(`Ref contains invalid characters: ${ref}`);
+  }
+}
 function validateBranchName(branch) {
   if (!branch || branch.trim().length === 0) {
     throw new Error("Branch name cannot be empty");
@@ -2224,7 +2257,11 @@ async function branchExists(branchName, options = {}) {
   }
 }
 async function createBranch(branchName, options = {}) {
-  await execGit(`git checkout -b "${branchName}"`, options);
+  if (options.startPoint) {
+    validateRefString(options.startPoint);
+  }
+  const cmd = options.startPoint ? `git checkout -b "${branchName}" "${options.startPoint}"` : `git checkout -b "${branchName}"`;
+  await execGit(cmd, options);
 }
 async function checkoutBranch(branchName, options = {}) {
   await execGit(`git checkout "${branchName}"`, options);
@@ -2296,6 +2333,23 @@ function extractIssueNumberFromBranch(branchName) {
   }
   return null;
 }
+async function listTags(options = {}) {
+  try {
+    const { stdout } = await execGit("git tag -l --sort=-version:refname", options);
+    return stdout.split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+async function resolveRef(ref, options = {}) {
+  validateRefString(ref);
+  try {
+    const { stdout } = await execGit(`git rev-parse --verify "${ref}"`, options);
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
 async function getLocalBranches(options = {}) {
   const { stdout } = await execGit('git branch --format="%(refname:short)"', options);
   return stdout.split("\n").map((b) => b.trim()).filter((b) => b.length > 0);
@@ -5754,6 +5808,7 @@ export {
   isGitRepository,
   isTransientError,
   listAgents,
+  listTags,
   listWorktrees,
   loadEventHooksConfig,
   loadHooksConfig,
@@ -5775,6 +5830,7 @@ export {
   removeWorktree,
   removeWorktreeWorkflow,
   resolveConflicts,
+  resolveRef,
   sanitizeForBranchName,
   saveEventHooksConfig,
   saveHooksConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bretwardjames/ghp-core",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Shared core library for GitHub Projects tools",
   "main": "dist/index.cjs",
   "module": "dist/index.js",