@senad-d/branchme 0.1.3 → 0.1.5

package/src/github.ts

@@ -5,12 +5,26 @@ import { redactSecrets } from "./redaction.ts";
 import {
   GITHUB_API_BASE_URL,
   GITHUB_API_VERSION,
+  GITHUB_RELATED_PR_TIMEOUT_MS,
   GITHUB_RESPONSE_BODY_LIMIT_BYTES,
   GITHUB_USER_AGENT,
+  GIT_CONTEXT_VALUE_LIMIT_CHARS,
   MAX_SUMMARY_OUTPUT_CHARS,
 } from "./constants.ts";
-import { getGitRoot, getOriginUrl, validateBranchNameInput, type GitCommandContext } from "./git.ts";
-import type { GitHubRepository, PullRequestDetails, PullRequestInput } from "./types.ts";
+import {
+  getCurrentBranch,
+  getGitRoot,
+  getOriginUrl,
+  validateBranchNameInput,
+  type GitCommandContext,
+} from "./git.ts";
+import type {
+  GitHubRepository,
+  PullRequestDetails,
+  PullRequestInput,
+  RelatedPullRequest,
+  RelatedPullRequestDetails,
+} from "./types.ts";
 
 type TokenEnvironmentKey = "GITHUB_TOKEN" | "GH_TOKEN";
 
@@ -33,6 +47,11 @@ export interface PullRequestFetchOptions {
   signal?: AbortSignal;
 }
 
+export interface RelatedPullRequestLookupOptions extends PullRequestFetchOptions {
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+}
+
 export interface GitHubBranchDetails {
   name: string;
   commitSha: string;
@@ -484,6 +503,11 @@ function requireGitHubResponseObject(payload: unknown, responseContext: string):
   return payload;
 }
 
+function requireGitHubResponseArray(payload: unknown, responseContext: string): unknown[] {
+  if (!Array.isArray(payload)) throw new Error(`${responseContext} was not an array.`);
+  return payload;
+}
+
 async function readGitHubJsonObject(
   response: Response,
   signal: AbortSignal | undefined,
@@ -496,6 +520,18 @@ async function readGitHubJsonObject(
   return requireGitHubResponseObject(parseGitHubJson(body.text, responseContext, token), responseContext);
 }
 
+async function readGitHubJsonArray(
+  response: Response,
+  signal: AbortSignal | undefined,
+  token: string,
+  responseContext: string,
+  readFailurePrefix: string,
+): Promise<unknown[]> {
+  const body = await readGitHubResponseBody(response, signal, readFailurePrefix, token);
+  if (body.truncated) throw new Error(`${responseContext} exceeded the ${GITHUB_RESPONSE_BODY_LIMIT_BYTES} byte limit.`);
+  return requireGitHubResponseArray(parseGitHubJson(body.text, responseContext, token), responseContext);
+}
+
 function parseGitHubBranchDetails(payload: Record<string, unknown>, branchName: string): GitHubBranchDetails {
   const commit = isRecord(payload.commit) ? stringField(payload.commit.sha, "commit.sha") : "";
   if (!/^[0-9a-f]{40,64}$/iu.test(commit)) throw new Error("GitHub branch preflight response is missing commit.sha.");
@@ -604,6 +640,273 @@ function pullRequestDetailsFromPayload(
   };
 }
 
+function escapeRelatedPullRequestControlCharacter(character: string): string {
+  const codePoint = character.codePointAt(0);
+  return codePoint === undefined ? "" : String.raw`\u${codePoint.toString(16).padStart(4, "0")}`;
+}
+
+function boundedRelatedPullRequestValue(value: string): string {
+  const safeValue = redactSecrets(value).replace(
+    /[\p{Cc}\p{Cf}\u2028\u2029]/gu,
+    escapeRelatedPullRequestControlCharacter,
+  );
+  if (safeValue.length <= GIT_CONTEXT_VALUE_LIMIT_CHARS) return safeValue;
+
+  let end = GIT_CONTEXT_VALUE_LIMIT_CHARS - 1;
+  const lastCodePoint = safeValue.codePointAt(end - 1);
+  if (lastCodePoint !== undefined && lastCodePoint > 0xffff) end -= 1;
+  return `${safeValue.slice(0, end)}…`;
+}
+
+function requireRelatedPullRequestString(value: unknown, field: string): string {
+  const text = stringField(value, field);
+  if (text.trim().length === 0) throw new Error(`GitHub response ${field} cannot be blank.`);
+  return text;
+}
+
+function requireRelatedPullRequestUrl(
+  value: unknown,
+  repository: GitHubRepository,
+  number: number,
+): string {
+  const rawUrl = requireRelatedPullRequestString(value, "html_url");
+  if (rawUrl.length > GIT_CONTEXT_VALUE_LIMIT_CHARS || /[\p{Cc}\p{Cf}\s]/u.test(rawUrl)) {
+    throw new Error("GitHub response html_url was invalid.");
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    throw new Error("GitHub response html_url was invalid.");
+  }
+
+  const expectedPath = `/${repository.owner}/${repository.repo}/pull/${number}`.toLowerCase();
+  if (
+    parsed.protocol !== "https:" ||
+    parsed.hostname.toLowerCase() !== "github.com" ||
+    parsed.port !== "" ||
+    parsed.username !== "" ||
+    parsed.password !== "" ||
+    parsed.search !== "" ||
+    parsed.hash !== "" ||
+    parsed.pathname.toLowerCase() !== expectedPath
+  ) {
+    throw new Error("GitHub response html_url did not match the resolved repository and pull request number.");
+  }
+
+  return rawUrl;
+}
+
+function requireRelatedPullRequestRepository(
+  value: unknown,
+  repository: GitHubRepository,
+): void {
+  const headRepository = requireGitHubResponseObject(value, "GitHub related pull request head.repo");
+  const fullName = requireRelatedPullRequestString(headRepository.full_name, "head.repo.full_name");
+  if (fullName.toLowerCase() !== repositoryLabel(repository).toLowerCase()) {
+    throw new Error("GitHub related pull request head repository did not match the resolved repository.");
+  }
+}
+
+function relatedPullRequestDetailsFromPayload(
+  repository: GitHubRepository,
+  currentBranch: string,
+  payload: unknown,
+): RelatedPullRequestDetails {
+  const response = requireGitHubResponseObject(payload, "GitHub related pull request response item");
+  const number = pullRequestNumberField(response.number);
+  const state = requireRelatedPullRequestString(response.state, "state");
+  if (state !== "open") throw new Error("GitHub related pull request response state was not open.");
+  if (typeof response.draft !== "boolean") throw new Error("GitHub response draft must be a boolean.");
+
+  const head = requireGitHubResponseObject(response.head, "GitHub related pull request head");
+  const headRef = requireRelatedPullRequestString(head.ref, "head.ref");
+  if (headRef !== currentBranch) {
+    throw new Error("GitHub related pull request head did not match the current branch.");
+  }
+  requireRelatedPullRequestRepository(head.repo, repository);
+
+  const base = requireGitHubResponseObject(response.base, "GitHub related pull request base");
+  const baseRef = requireRelatedPullRequestString(base.ref, "base.ref");
+  const title = requireRelatedPullRequestString(response.title, "title");
+
+  return {
+    repository: {
+      owner: boundedRelatedPullRequestValue(repository.owner),
+      repo: boundedRelatedPullRequestValue(repository.repo),
+    },
+    number,
+    url: requireRelatedPullRequestUrl(response.html_url, repository, number),
+    title: boundedRelatedPullRequestValue(title),
+    state,
+    draft: response.draft,
+    head: boundedRelatedPullRequestValue(headRef),
+    base: boundedRelatedPullRequestValue(baseRef),
+  };
+}
+
+function unavailableRelatedPullRequest(reason: string): RelatedPullRequest {
+  return { status: "unavailable", reason };
+}
+
+function abortedRelatedPullRequest(
+  callerSignal: AbortSignal | undefined,
+  timeoutSignal: AbortSignal,
+): RelatedPullRequest | null {
+  if (callerSignal?.aborted) return unavailableRelatedPullRequest("Related pull request lookup was cancelled.");
+  if (timeoutSignal.aborted) return unavailableRelatedPullRequest("Related pull request lookup timed out.");
+  return null;
+}
+
+function validateRelatedPullRequestLookupBounds(repository: GitHubRepository, branch: string): void {
+  if (
+    repository.owner.length > GIT_CONTEXT_VALUE_LIMIT_CHARS ||
+    repository.repo.length > GIT_CONTEXT_VALUE_LIMIT_CHARS ||
+    branch.length > GIT_CONTEXT_VALUE_LIMIT_CHARS
+  ) {
+    throw new Error("GitHub related pull request lookup metadata exceeded its value limit.");
+  }
+}
+
+function relatedPullRequestLookupUrl(repository: GitHubRepository, currentBranch: string): string {
+  const query = new URLSearchParams({
+    state: "open",
+    head: `${repository.owner}:${currentBranch}`,
+    per_page: "1",
+  });
+  return `${GITHUB_API_BASE_URL}/repos/${encodePathSegment(repository.owner)}/${encodePathSegment(repository.repo)}/pulls?${query.toString()}`;
+}
+
+async function lookupRelatedPullRequestWithSignal(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  options: RelatedPullRequestLookupOptions,
+  signal: AbortSignal,
+  timeoutSignal: AbortSignal,
+): Promise<RelatedPullRequest> {
+  const initialAbort = abortedRelatedPullRequest(options.signal, timeoutSignal);
+  if (initialAbort) return initialAbort;
+
+  let repoRoot: string;
+  let currentBranch: string;
+  let repository: GitHubRepository;
+  try {
+    repoRoot = await getGitRoot(pi, ctx, signal);
+    const rootCtx = { cwd: repoRoot };
+    const branch = await getCurrentBranch(pi, rootCtx, signal);
+    if (branch.detached || !branch.currentBranch) {
+      return unavailableRelatedPullRequest("Related pull request lookup is unavailable for detached HEAD.");
+    }
+    currentBranch = branch.currentBranch;
+    validatePullRequestBranchRef(currentBranch, "headBranch");
+    repository = await resolveGitHubRepository(pi, rootCtx, signal, options.env ?? process.env);
+    validateRelatedPullRequestLookupBounds(repository, currentBranch);
+  } catch {
+    return (
+      abortedRelatedPullRequest(options.signal, timeoutSignal) ??
+      unavailableRelatedPullRequest("The current GitHub repository or branch could not be resolved.")
+    );
+  }
+
+  let token: string;
+  try {
+    token = (await resolveGitHubToken(options.env ?? process.env, { cwd: repoRoot, signal })).token;
+  } catch {
+    return (
+      abortedRelatedPullRequest(options.signal, timeoutSignal) ??
+      unavailableRelatedPullRequest("GitHub authentication is unavailable.")
+    );
+  }
+
+  let response: Response;
+  try {
+    const fetchImpl = requireFetchImplementation(options.fetchImpl ?? globalThis.fetch);
+    response = await fetchGitHubResponse(
+      fetchImpl,
+      relatedPullRequestLookupUrl(repository, currentBranch),
+      { method: "GET", headers: gitHubJsonHeaders(token), signal },
+      "GitHub related pull request request failed",
+      token,
+    );
+  } catch {
+    return (
+      abortedRelatedPullRequest(options.signal, timeoutSignal) ??
+      unavailableRelatedPullRequest("The GitHub related pull request request failed.")
+    );
+  }
+
+  if (!response.ok) {
+    try {
+      await readGitHubResponseBody(
+        response,
+        signal,
+        `GitHub related pull request request failed with HTTP ${response.status}: unable to read error response`,
+        token,
+      );
+    } catch {
+      return (
+        abortedRelatedPullRequest(options.signal, timeoutSignal) ??
+        unavailableRelatedPullRequest("The GitHub related pull request response could not be read.")
+      );
+    }
+    return unavailableRelatedPullRequest(`GitHub related pull request lookup returned HTTP ${response.status}.`);
+  }
+
+  let payload: unknown[];
+  try {
+    payload = await readGitHubJsonArray(
+      response,
+      signal,
+      token,
+      "GitHub related pull request response",
+      "GitHub related pull request response could not be read",
+    );
+  } catch {
+    return (
+      abortedRelatedPullRequest(options.signal, timeoutSignal) ??
+      unavailableRelatedPullRequest("The GitHub related pull request response was invalid.")
+    );
+  }
+
+  if (payload.length === 0) return { status: "none" };
+
+  try {
+    return {
+      status: "found",
+      pullRequest: relatedPullRequestDetailsFromPayload(repository, currentBranch, payload[0]),
+    };
+  } catch {
+    return unavailableRelatedPullRequest("The GitHub related pull request response was invalid.");
+  }
+}
+
+export async function lookupRelatedPullRequest(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  options: RelatedPullRequestLookupOptions = {},
+): Promise<RelatedPullRequest> {
+  const timeoutMs = options.timeoutMs ?? GITHUB_RELATED_PR_TIMEOUT_MS;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+    return unavailableRelatedPullRequest("Related pull request lookup timeout is invalid.");
+  }
+  if (options.signal?.aborted) {
+    return unavailableRelatedPullRequest("Related pull request lookup was cancelled.");
+  }
+
+  // AbortSignal.timeout() uses an unref'ed timer, which can let Node exit while fetch is still pending.
+  const timeoutController = new AbortController();
+  const timeoutHandle = setTimeout(timeoutController.abort.bind(timeoutController), timeoutMs);
+  const timeoutSignal = timeoutController.signal;
+  const signal = options.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal;
+
+  try {
+    return await lookupRelatedPullRequestWithSignal(pi, ctx, options, signal, timeoutSignal);
+  } finally {
+    clearTimeout(timeoutHandle);
+  }
+}
+
 export async function ensureGitHubBranchExists(
   repository: GitHubRepository,
   branchName: string,

package/src/tools/branchme-tools.ts

@@ -4,20 +4,22 @@ import {
   BRANCH_STATUS_TOOL_NAME,
   CHANGE_BRANCH_TOOL_NAME,
   CREATE_BRANCH_TOOL_NAME,
+  PULL_BRANCH_TOOL_NAME,
   PULL_REQUEST_TOOL_NAME,
   PUSH_BRANCH_TOOL_NAME,
 } from "../constants.ts";
 import {
   changeExistingLocalBranch,
   createLocalBranch,
-  getBranchStatus,
   getGitRoot,
   getLocalBranchCommit,
   localBranchExists,
+  pullCurrentBranch,
   pushCurrentBranch,
   validateBranchName,
   withRepositoryMutationQueue,
 } from "../git.ts";
+import { collectGitContext, formatGitContext } from "../git-context.ts";
 import {
   createGitHubPullRequest,
   ensureGitHubBranchExists,
@@ -27,7 +29,7 @@ import {
   resolveGitHubToken,
   validatePullRequestBranchRef,
 } from "../github.ts";
-import type { BranchStatusDetails, ChangeBranchDetails, PullRequestDetails } from "../types.ts";
+import type { ChangeBranchDetails, GitContextDetails, PullRequestDetails } from "../types.ts";
 
 const EmptyParametersSchema = Type.Object({}, { additionalProperties: false });
 
@@ -62,17 +64,8 @@ export interface BranchMeToolOptions {
   fetchImpl?: typeof fetch;
 }
 
-function repositoryText(details: BranchStatusDetails): string {
-  return details.githubRepository ? repositoryLabel(details.githubRepository) : "not resolved";
-}
-
-export function formatBranchStatus(details: BranchStatusDetails): string {
-  const branch = details.detached ? "detached HEAD" : details.currentBranch ?? "unknown branch";
-  const tree = details.hasChanges ? "dirty" : "clean";
-  const upstream = details.upstream ? `upstream ${details.upstream}` : "no upstream";
-  const counts = details.ahead === null || details.behind === null ? "ahead/behind unavailable" : `ahead ${details.ahead}, behind ${details.behind}`;
-  const warning = details.warnings?.length ? `; warning: ${details.warnings.join("; ")}` : "";
-  return `BranchMe status: ${branch}; ${tree}; ${upstream}; ${counts}; GitHub ${repositoryText(details)}${warning}.`;
+export function formatBranchStatus(details: GitContextDetails): string {
+  return formatGitContext(details, "refresh");
 }
 
 export function formatChangeBranch(details: ChangeBranchDetails): string {
@@ -134,20 +127,25 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
   pi.registerTool({
     name: BRANCH_STATUS_TOOL_NAME,
     label: "Branch Status",
-    description: "branch_status inspects the current git repository, branch, upstream, dirty state, ahead/behind counts, and GitHub repository if available. branch_status is read-only.",
-    promptSnippet: "branch_status: inspect current-repository git branch status without mutating files or git state",
+    description: "branch_status explicitly refreshes the current Git repository snapshot, including branch, working tree, unstaged changes, related pull request, and recent commits. branch_status is read-only and never mutates files, Git state, or GitHub state.",
+    promptSnippet: "branch_status: explicitly refresh current-repository branch, working tree, changes, related PR, and recent commits without mutation",
     promptGuidelines: [
-      "Use branch_status before change_branch, create_branch, push_branch, or pull_request when the user asks about the current branch state.",
-      "Use branch_status only for read-only inspection; branch_status never creates branches, pushes, commits, stages, or edits files.",
+      "Use the automatic Git context for start-of-run questions; call branch_status only for an explicit refresh or after Git state changes during the current run.",
+      "Use branch_status as a read-only refresh; branch_status never mutates files, Git state, or GitHub state.",
     ],
     parameters: EmptyParametersSchema,
     async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
-      const details = await getBranchStatus(pi, ctx, signal);
+      const details = await collectGitContext(pi, ctx, {
+        signal,
+        env: options.env,
+        fetchImpl: options.fetchImpl,
+      });
 
       try {
-        details.githubRepository = await resolveGitHubRepository(pi, ctx, signal, options.env);
-      } catch {
-        // Repository resolution is optional for branch_status; mutation tools fail closed.
+        details.githubRepository ??= await resolveGitHubRepository(pi, ctx, signal, options.env);
+      } catch (error) {
+        if (signal?.aborted) throw error;
+        // Repository resolution is optional compatibility metadata; context collection is authoritative.
       }
 
       return {
@@ -201,6 +199,26 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
     },
   });
 
+  pi.registerTool({
+    name: PULL_BRANCH_TOOL_NAME,
+    label: "Pull Branch",
+    description: "pull_branch updates the current branch from its configured upstream with git pull --ff-only --no-rebase --no-autostash. pull_branch requires a clean working tree and never rebases, creates merge commits, force-updates, stashes, stages, or commits.",
+    promptSnippet: "pull_branch: fast-forward the clean current branch from its configured upstream without rebasing",
+    promptGuidelines: [
+      "Use pull_branch only when the user explicitly wants to update the current branch from its configured upstream.",
+      "Use pull_branch only on a clean working tree with an upstream; pull_branch has no branchName, remote, force, or rebase parameters.",
+      "Do not call pull_branch in the same tool batch as change_branch or create_branch; call pull_branch after change_branch completes, then call create_branch after pull_branch completes.",
+    ],
+    parameters: EmptyParametersSchema,
+    async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
+      const details = await pullCurrentBranch(pi, ctx, signal);
+      return {
+        content: [{ type: "text", text: `Pulled current branch ${details.currentBranch} with fast-forward-only semantics.` }],
+        details,
+      };
+    },
+  });
+
   pi.registerTool({
     name: PUSH_BRANCH_TOOL_NAME,
     label: "Push Branch",

package/src/types.ts

@@ -13,6 +13,47 @@ export interface AheadBehindCount {
   behind: number | null;
 }
 
+export interface WorkingTreeDetails {
+  state: "clean" | "dirty";
+  staged: number;
+  unstaged: number;
+  untracked: number;
+}
+
+export interface GitFileChange {
+  status: string;
+  path: string;
+  originalPath?: string;
+}
+
+export interface GitFileChangeSummary {
+  entries: GitFileChange[];
+  omitted: number;
+}
+
+export interface RecentCommit {
+  hash: string;
+  shortHash: string;
+  date: string;
+  subject: string;
+}
+
+export interface RelatedPullRequestDetails {
+  repository: GitHubRepository;
+  number: number;
+  url: string;
+  title: string;
+  state: string;
+  draft: boolean;
+  head: string;
+  base: string;
+}
+
+export type RelatedPullRequest =
+  | { status: "found"; pullRequest: RelatedPullRequestDetails }
+  | { status: "none" }
+  | { status: "unavailable"; reason: string };
+
 export interface BranchStatusDetails {
   repoRoot: string;
   currentBranch: string | null;
@@ -25,6 +66,13 @@ export interface BranchStatusDetails {
   githubRepository?: GitHubRepository;
 }
 
+export interface GitContextDetails extends BranchStatusDetails {
+  workingTree: WorkingTreeDetails;
+  unstagedChanges: GitFileChangeSummary;
+  relatedPullRequest: RelatedPullRequest;
+  recentCommits: RecentCommit[];
+}
+
 export interface CreateBranchDetails {
   repoRoot: string;
   previousBranch: string;
@@ -39,6 +87,15 @@ export interface ChangeBranchDetails {
   hasChangesBeforeSwitch: false;
 }
 
+export interface PullBranchDetails {
+  repoRoot: string;
+  currentBranch: string;
+  upstream: string;
+  remote: string;
+  remoteRef: string;
+  output: string;
+}
+
 export interface PushBranchDetails {
   repoRoot: string;
   currentBranch: string;

package/src/ui/branchme-panel.ts

@@ -177,7 +177,7 @@ function sectionFooter(section: BranchMePanelSection, data: BranchMePanelData):
     case "status":
       return "status • current repository only • tools perform actions";
     case "workflow":
-      return "workflow • inspect → change/create → push → PR";
+      return "workflow • inspect → change → pull → create → push → PR";
   }
 }
 
@@ -197,6 +197,7 @@ function sectionRows(section: BranchMePanelSection, data: BranchMePanelData): Pa
         heading("WORKFLOW"),
         workflowDetailRow("branch_status", "inspect"),
         workflowDetailRow("change_branch", "existing local"),
+        workflowDetailRow("pull_branch", "fast-forward"),
         workflowDetailRow("create_branch", "from HEAD"),
         workflowDetailRow("push_branch", "current branch"),
         workflowDetailRow("pull_request", "after push"),