@bretwardjames/ghp-core 0.7.1 → 0.9.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,
@@ -1908,6 +1910,7 @@ var GitHubAPI = class {
    */
   async getRecentActivity(repo, since, options) {
     if (!this.graphqlWithAuth) throw new Error("Not authenticated");
+    const filterUser = options?.user || (options?.mine ? this.username : null);
     const projects = await this.getProjects(repo);
     if (projects.length === 0) return [];
     const allItems = [];
@@ -1921,9 +1924,9 @@ var GitHubAPI = class {
     let recentItems = allItems.filter(
       (item) => item.updatedAt && new Date(item.updatedAt).getTime() >= sinceMs
     );
-    if (options?.mine && this.username) {
+    if (filterUser) {
       recentItems = recentItems.filter(
-        (item) => item.assignees.includes(this.username)
+        (item) => item.assignees.includes(filterUser)
       );
     }
     const seen = /* @__PURE__ */ new Set();
@@ -1968,10 +1971,11 @@ var GitHubAPI = class {
       }
     }
     const activityNumbers = new Set(activities.map((a) => a.issue.number));
-    if (this.username) {
+    const prSearchUser = filterUser || this.username;
+    if (prSearchUser) {
       const reviewActivities = await this.fetchReviewedPRs(
         repo,
-        this.username,
+        prSearchUser,
         sinceDate,
         sinceMs,
         activityNumbers
@@ -1980,11 +1984,9 @@ var GitHubAPI = class {
         activityNumbers.add(a.issue.number);
         activities.push(a);
       }
-    }
-    if (this.username) {
       const authoredActivities = await this.fetchAuthoredPRs(
         repo,
-        this.username,
+        prSearchUser,
         sinceDate,
         sinceMs,
         activityNumbers
@@ -2333,6 +2335,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 +2404,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 +2480,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);
@@ -4244,6 +4276,12 @@ function validateUrl(url) {
 
 // src/standup.ts
 function formatStandupText(activities, options) {
+  if (options.timeline) {
+    return formatTimeline(activities, options);
+  }
+  return formatGrouped(activities, options);
+}
+function formatGrouped(activities, options) {
   const { since } = options;
   const lines = [];
   const sinceStr = formatRelativeDate(since);
@@ -4264,6 +4302,35 @@ function formatStandupText(activities, options) {
   }
   return lines.join("\n").trimEnd();
 }
+function formatTimeline(activities, options) {
+  const { since } = options;
+  const lines = [];
+  const allEvents = [];
+  for (const activity of activities) {
+    for (const event of activity.changes) {
+      allEvents.push({ event, issue: activity.issue });
+    }
+  }
+  allEvents.sort(
+    (a, b) => new Date(b.event.timestamp).getTime() - new Date(a.event.timestamp).getTime()
+  );
+  const sinceStr = formatRelativeDate(since);
+  const eventCount = allEvents.length;
+  const issueCount = activities.length;
+  lines.push(`Since ${sinceStr} \u2014 ${eventCount} event${eventCount !== 1 ? "s" : ""} across ${issueCount} issue${issueCount !== 1 ? "s" : ""}`);
+  lines.push("");
+  if (allEvents.length === 0) {
+    lines.push("No activity found in this time window.");
+    return lines.join("\n");
+  }
+  for (const { event, issue } of allEvents) {
+    const time = formatShortTimestamp(event.timestamp);
+    const desc = formatEventDescription(event);
+    const issueRef = `#${issue.number} ${truncate(issue.title, 50)}`;
+    lines.push(`${time}  ${desc}  (${issueRef})`);
+  }
+  return lines.join("\n").trimEnd();
+}
 function parseSince(input) {
   const isoDate = new Date(input);
   if (!isNaN(isoDate.getTime()) && input.includes("-")) {
@@ -4320,6 +4387,41 @@ function formatEventLine(event) {
       return `${arrow} ${event.type} by ${actor} (${timestamp})`;
   }
 }
+function formatEventDescription(event) {
+  const actor = event.actor;
+  switch (event.type) {
+    case "comment":
+      return `Comment by ${actor}${event.details ? ": " + event.details : ""}`;
+    case "labeled":
+      return `Labeled "${event.details}" by ${actor}`;
+    case "unlabeled":
+      return `Unlabeled "${event.details}" by ${actor}`;
+    case "assigned":
+      return `Assigned to ${event.details || actor}`;
+    case "unassigned":
+      return `Unassigned ${event.details || ""} by ${actor}`;
+    case "closed":
+      return `Closed by ${actor}`;
+    case "reopened":
+      return `Reopened by ${actor}`;
+    case "referenced":
+      return `${event.details} linked by ${actor}`;
+    case "review_submitted":
+      return `${event.details} by ${actor}`;
+    case "review_requested":
+      return `Review requested from ${event.details || "team"} by ${actor}`;
+    case "pr_created":
+      return `PR created by ${actor}`;
+    case "pr_merged":
+      return `PR merged by ${actor}`;
+    default:
+      return `${event.type} by ${actor}`;
+  }
+}
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 1) + "\u2026";
+}
 function formatRelativeDate(date) {
   const now = /* @__PURE__ */ new Date();
   const diffMs = now.getTime() - date.getTime();
@@ -5854,6 +5956,7 @@ EOF
   isGitRepository,
   isTransientError,
   listAgents,
+  listTags,
   listWorktrees,
   loadEventHooksConfig,
   loadHooksConfig,
@@ -5875,6 +5978,7 @@ EOF
   removeWorktree,
   removeWorktreeWorkflow,
   resolveConflicts,
+  resolveRef,
   sanitizeForBranchName,
   saveEventHooksConfig,
   saveHooksConfig,

package/dist/index.d.cts

@@ -691,6 +691,7 @@ declare class GitHubAPI {
      */
     getRecentActivity(repo: RepoInfo, since: Date, options?: {
         mine?: boolean;
+        user?: string;
     }): Promise<IssueActivity[]>;
     /**
      * Search for PRs the user reviewed that aren't already in the activity list.
@@ -789,9 +790,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)
@@ -851,6 +856,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)
@@ -2283,6 +2301,8 @@ declare function validateUrl(url: string): string;
 interface FormatStandupOptions {
     since: Date;
     colorize?: boolean;
+    /** If true, show a flat chronological timeline instead of grouping by issue */
+    timeline?: boolean;
 }
 /**
  * Format a standup summary as human-readable text.
@@ -3331,4 +3351,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

@@ -691,6 +691,7 @@ declare class GitHubAPI {
      */
     getRecentActivity(repo: RepoInfo, since: Date, options?: {
         mine?: boolean;
+        user?: string;
     }): Promise<IssueActivity[]>;
     /**
      * Search for PRs the user reviewed that aren't already in the activity list.
@@ -789,9 +790,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)
@@ -851,6 +856,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)
@@ -2283,6 +2301,8 @@ declare function validateUrl(url: string): string;
 interface FormatStandupOptions {
     since: Date;
     colorize?: boolean;
+    /** If true, show a flat chronological timeline instead of grouping by issue */
+    timeline?: boolean;
 }
 /**
  * Format a standup summary as human-readable text.
@@ -3331,4 +3351,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

@@ -1739,6 +1739,7 @@ var GitHubAPI = class {
    */
   async getRecentActivity(repo, since, options) {
     if (!this.graphqlWithAuth) throw new Error("Not authenticated");
+    const filterUser = options?.user || (options?.mine ? this.username : null);
     const projects = await this.getProjects(repo);
     if (projects.length === 0) return [];
     const allItems = [];
@@ -1752,9 +1753,9 @@ var GitHubAPI = class {
     let recentItems = allItems.filter(
       (item) => item.updatedAt && new Date(item.updatedAt).getTime() >= sinceMs
     );
-    if (options?.mine && this.username) {
+    if (filterUser) {
       recentItems = recentItems.filter(
-        (item) => item.assignees.includes(this.username)
+        (item) => item.assignees.includes(filterUser)
       );
     }
     const seen = /* @__PURE__ */ new Set();
@@ -1799,10 +1800,11 @@ var GitHubAPI = class {
       }
     }
     const activityNumbers = new Set(activities.map((a) => a.issue.number));
-    if (this.username) {
+    const prSearchUser = filterUser || this.username;
+    if (prSearchUser) {
       const reviewActivities = await this.fetchReviewedPRs(
         repo,
-        this.username,
+        prSearchUser,
         sinceDate,
         sinceMs,
         activityNumbers
@@ -1811,11 +1813,9 @@ var GitHubAPI = class {
         activityNumbers.add(a.issue.number);
         activities.push(a);
       }
-    }
-    if (this.username) {
       const authoredActivities = await this.fetchAuthoredPRs(
         repo,
-        this.username,
+        prSearchUser,
         sinceDate,
         sinceMs,
         activityNumbers
@@ -2164,6 +2164,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 +2233,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 +2309,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);
@@ -4075,6 +4105,12 @@ function validateUrl(url) {
 
 // src/standup.ts
 function formatStandupText(activities, options) {
+  if (options.timeline) {
+    return formatTimeline(activities, options);
+  }
+  return formatGrouped(activities, options);
+}
+function formatGrouped(activities, options) {
   const { since } = options;
   const lines = [];
   const sinceStr = formatRelativeDate(since);
@@ -4095,6 +4131,35 @@ function formatStandupText(activities, options) {
   }
   return lines.join("\n").trimEnd();
 }
+function formatTimeline(activities, options) {
+  const { since } = options;
+  const lines = [];
+  const allEvents = [];
+  for (const activity of activities) {
+    for (const event of activity.changes) {
+      allEvents.push({ event, issue: activity.issue });
+    }
+  }
+  allEvents.sort(
+    (a, b) => new Date(b.event.timestamp).getTime() - new Date(a.event.timestamp).getTime()
+  );
+  const sinceStr = formatRelativeDate(since);
+  const eventCount = allEvents.length;
+  const issueCount = activities.length;
+  lines.push(`Since ${sinceStr} \u2014 ${eventCount} event${eventCount !== 1 ? "s" : ""} across ${issueCount} issue${issueCount !== 1 ? "s" : ""}`);
+  lines.push("");
+  if (allEvents.length === 0) {
+    lines.push("No activity found in this time window.");
+    return lines.join("\n");
+  }
+  for (const { event, issue } of allEvents) {
+    const time = formatShortTimestamp(event.timestamp);
+    const desc = formatEventDescription(event);
+    const issueRef = `#${issue.number} ${truncate(issue.title, 50)}`;
+    lines.push(`${time}  ${desc}  (${issueRef})`);
+  }
+  return lines.join("\n").trimEnd();
+}
 function parseSince(input) {
   const isoDate = new Date(input);
   if (!isNaN(isoDate.getTime()) && input.includes("-")) {
@@ -4151,6 +4216,41 @@ function formatEventLine(event) {
       return `${arrow} ${event.type} by ${actor} (${timestamp})`;
   }
 }
+function formatEventDescription(event) {
+  const actor = event.actor;
+  switch (event.type) {
+    case "comment":
+      return `Comment by ${actor}${event.details ? ": " + event.details : ""}`;
+    case "labeled":
+      return `Labeled "${event.details}" by ${actor}`;
+    case "unlabeled":
+      return `Unlabeled "${event.details}" by ${actor}`;
+    case "assigned":
+      return `Assigned to ${event.details || actor}`;
+    case "unassigned":
+      return `Unassigned ${event.details || ""} by ${actor}`;
+    case "closed":
+      return `Closed by ${actor}`;
+    case "reopened":
+      return `Reopened by ${actor}`;
+    case "referenced":
+      return `${event.details} linked by ${actor}`;
+    case "review_submitted":
+      return `${event.details} by ${actor}`;
+    case "review_requested":
+      return `Review requested from ${event.details || "team"} by ${actor}`;
+    case "pr_created":
+      return `PR created by ${actor}`;
+    case "pr_merged":
+      return `PR merged by ${actor}`;
+    default:
+      return `${event.type} by ${actor}`;
+  }
+}
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 1) + "\u2026";
+}
 function formatRelativeDate(date) {
   const now = /* @__PURE__ */ new Date();
   const diffMs = now.getTime() - date.getTime();
@@ -5684,6 +5784,7 @@ export {
   isGitRepository,
   isTransientError,
   listAgents,
+  listTags,
   listWorktrees,
   loadEventHooksConfig,
   loadHooksConfig,
@@ -5705,6 +5806,7 @@ export {
   removeWorktree,
   removeWorktreeWorkflow,
   resolveConflicts,
+  resolveRef,
   sanitizeForBranchName,
   saveEventHooksConfig,
   saveHooksConfig,

package/package.json

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