@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/azdo/src/azdo-pr.ts

@@ -0,0 +1,289 @@
+// Azure DevOps pull request tool logic. Exported for direct, in-process use
+// by mcp-server.ts — there is no CLI entry point here (nothing else in the
+// repo invoked this file as a CLI; see mcp-server.ts's runTool() history).
+import {
+  validatePullRequestDescription,
+  validatePullRequestMetadata,
+  validatePullRequestTitle,
+} from './lib/validate-pr-metadata.ts'
+import { AdoClient, PR_TARGET_BRANCH, adoProjectUrl, currentBranch, resolveRepository } from './lib/client.ts';
+
+let client: AdoClient | undefined
+
+async function getClient(): Promise<AdoClient> {
+  client ??= new AdoClient()
+  return client
+}
+
+/** Test seam: forget the cached client — see azdo-wit.ts's resetClientForTests() for why. */
+export function resetClientForTests(): void {
+  client = undefined
+}
+
+/** The human-facing PR link, built from the same org/project root the API call uses. */
+export function pullRequestWebUrl(repository: string, pullRequestId: number | string): string {
+  return `${adoProjectUrl()}/_git/${repository}/pullrequest/${pullRequestId}`;
+}
+
+/**
+ * The PATCH body that actually arms a pull request.
+ *
+ * Azure DevOps has no `autoComplete` boolean on this endpoint: arming a PR
+ * means naming the identity that set it, via `autoCompleteSetBy`. The previous
+ * body sent `{ autoComplete: true }`, which the API accepts and ignores — so
+ * the call succeeded, the tool reported success, and the PR stayed unarmed.
+ * That silent no-op is why this is a named function with its own test rather
+ * than an object literal at the call site.
+ */
+export function autoCompleteBody(identityId: string): {
+  autoCompleteSetBy: { id: string }
+  completionOptions: { mergeStrategy: string; deleteSourceBranch: boolean }
+} {
+  if (!identityId) {
+    throw new Error('cannot arm auto-complete: no identity to attribute it to')
+  }
+  return {
+    autoCompleteSetBy: { id: identityId },
+    completionOptions: { mergeStrategy: 'squash', deleteSourceBranch: true },
+  }
+}
+
+/** Shared with azdo-pr-review.ts (comments/votes hang off the same PR resource). */
+export const pullRequestsPath = (repository: string, id?: string | number): string =>
+  `/git/repositories/${repository}/pullRequests${id === undefined ? '' : `/${id}`}`;
+
+const diffsCommitsPath = (repository: string): string => `/git/repositories/${repository}/diffs/commits`;
+
+/**
+ * The exact refusal for a source branch that is behind the target (two-branch
+ * standard, docs/specs/two-branch-standard-2026-09-27.md §1). Deliberately a
+ * merge instruction, never rebase (Tarun, 2026-09-27: "no rebasing, anywhere").
+ */
+export function behindTargetMessage(source: string, target: string, behindCount: number): string {
+  return `branch ${source} is ${behindCount} commits behind ${target}: git fetch origin && git merge origin/${target}, resolve conflicts, run the tests, push, then create the PR again`;
+}
+
+/** The refusal for a source branch that carries no commits the target lacks. */
+export function nothingToMergeMessage(source: string, target: string): string {
+  return `nothing to merge: ${source} has no commits ahead of ${target}`;
+}
+
+/**
+ * Ancestry check run before every PR create (§1: "parallel-agent conflicts —
+ * handled at PR creation, not in CI"). Asks Azure DevOps how far `source` is
+ * behind and ahead of `target` via the Diffs — Get REST API:
+ *
+ *   GET .../diffs/commits?baseVersion=<target>&baseVersionType=branch
+ *                        &targetVersion=<source>&targetVersionType=branch&api-version=7.1
+ *
+ * (https://learn.microsoft.com/en-us/rest/api/azure/devops/git/diffs/get) —
+ * `baseVersion` is the reference branch, so with `target` as base and
+ * `source` as target-of-the-diff, `behindCount` is exactly "how many commits
+ * does `target` have that `source` lacks" and `aheadCount` is "how many
+ * commits does `source` have that `target` lacks". No PR is created when
+ * either check fails.
+ */
+export async function assertBranchReadyForPr(
+  c: AdoClient,
+  repository: string,
+  source: string,
+  target: string,
+): Promise<void> {
+  const diff = await c.get<{ aheadCount?: number; behindCount?: number }>(
+    diffsCommitsPath(repository),
+    {
+      'api-version': '7.1',
+      baseVersion: target,
+      baseVersionType: 'branch',
+      targetVersion: source,
+      targetVersionType: 'branch',
+    },
+  );
+  const behindCount = diff.behindCount ?? 0;
+  const aheadCount = diff.aheadCount ?? 0;
+  if (behindCount > 0) throw new Error(behindTargetMessage(source, target, behindCount));
+  if (aheadCount === 0) throw new Error(nothingToMergeMessage(source, target));
+}
+
+export type PrListOrGetArgs = {
+  id?: string;
+  status?: string;
+  /** Overrides `AZURE_DEVOPS_REPO` for this call. */
+  repository?: string;
+};
+
+export async function prListOrGet(args: PrListOrGetArgs): Promise<string> {
+  const c = await getClient()
+  const repository = resolveRepository(args.repository);
+
+  if (args.id) {
+    const pr = await c.get<any>(
+      pullRequestsPath(repository, args.id),
+      { 'api-version': '7.1' }
+    );
+    return JSON.stringify(pr, null, 2);
+  }
+
+  const status = args.status ?? 'active';
+
+  const result = await c.get<any>(
+    pullRequestsPath(repository),
+    {
+      'api-version': '7.1',
+      'searchCriteria.status': status,
+      '$top': '10',
+    }
+  );
+
+  const prs = result.value.map((pr: any) => ({
+    id: pr.pullRequestId,
+    title: pr.title,
+    status: pr.status,
+    author: pr.createdBy?.displayName,
+    createdDate: pr.creationDate,
+    url: pullRequestWebUrl(repository, pr.pullRequestId),
+  }));
+
+  return JSON.stringify(prs, null, 2);
+}
+
+function assertValidCreateMetadata(title: string, description: string) {
+  const metadataErrors = validatePullRequestMetadata(title, description)
+  if (metadataErrors.length === 0) return
+  throw new Error(metadataErrors.map((error) => `pr-policy: FAIL — ${error}`).join('\n'))
+}
+
+function assertValidUpdateMetadata(title: string | undefined, description: string | undefined) {
+  const metadataErrors = [
+    ...(title === undefined ? [] : validatePullRequestTitle(title)),
+    ...(description === undefined ? [] : validatePullRequestDescription(description)),
+  ]
+  if (metadataErrors.length === 0) return
+  throw new Error(metadataErrors.map((error) => `pr-policy: FAIL — ${error}`).join('\n'))
+}
+
+export type PrCreateOrUpdateArgs = {
+  id?: string;
+  title?: string;
+  description?: string;
+  autoComplete?: boolean;
+  mergeStrategy?: string;
+  deleteSourceBranch?: boolean;
+  /** Overrides `AZURE_DEVOPS_REPO` for this call. */
+  repository?: string;
+  /** Rejected removed routing input; PRs always use the checked-out branch. */
+  sourceBranch?: never;
+  /** Rejected removed routing input; PRs always target integration. */
+  targetBranch?: never;
+};
+
+export function assertPrSourceBranch(source: string | undefined): asserts source is string {
+  if (!source) throw new Error('could not determine the current branch; run from the repository checkout');
+  if (source === 'HEAD') throw new Error('this checkout is in detached HEAD state; check out a branch first');
+  if (source === PR_TARGET_BRANCH) throw new Error(`already on ${PR_TARGET_BRANCH}; create a feature branch first`);
+  if (source === 'main') throw new Error(`a pull request is never opened from main; open a branch into ${PR_TARGET_BRANCH}`);
+}
+
+/** The exact next steps returned after PR creation, including live-stage failure polling. */
+export function prCreateResult(repository: string, pullRequestId: number, title: string, status: string, autoComplete: boolean): Record<string, unknown> {
+  const prRef = `refs/pull/${pullRequestId}/merge`;
+  return {
+    id: pullRequestId,
+    title,
+    status,
+    url: pullRequestWebUrl(repository, pullRequestId),
+    autoComplete,
+    summary: 'Creating this pull request started a validation build.',
+    poll: [
+      `1. build_list_or_get({ branch: '${prRef}' }) — take builds[0].id.`,
+      '2. build_list_or_get({ buildId }) — repeat while progress.settled is false AND progress.failureSeen is false.',
+      '3. Stop as soon as either is true; failureSeen identifies the first failed stage while later stages run.',
+      '4. On failure: build_list_or_get({ buildId, tail: 25 }) — inspect the failing task log.',
+    ],
+  };
+}
+
+export async function prCreateOrUpdate(args: PrCreateOrUpdateArgs): Promise<string> {
+  if (args.sourceBranch !== undefined) throw new Error('sourceBranch is not supported; PRs always use the current branch');
+  if (args.targetBranch !== undefined) throw new Error('targetBranch is not supported; PRs always target integration');
+  const repository = resolveRepository(args.repository);
+
+  if (args.id) {
+    const { id, title, description, autoComplete, mergeStrategy, deleteSourceBranch } = args;
+
+    assertValidUpdateMetadata(title, description)
+
+    const body: any = {};
+    if (title) body.title = title;
+    if (description) body.description = description;
+    if (mergeStrategy || deleteSourceBranch) {
+      body.completionOptions = {
+        ...(mergeStrategy ? { mergeStrategy: mergeStrategy.toLowerCase() } : {}),
+        ...(deleteSourceBranch ? { deleteSourceBranch: true } : {}),
+      };
+    }
+
+    const c = await getClient()
+
+    if (autoComplete) {
+      // Arming needs an identity to attribute it to, which the PR itself
+      // carries as `createdBy`. Read it rather than sending a boolean the API
+      // silently ignores -- see autoCompleteBody(). If the PR was raised by a
+      // different identity than the one calling, Azure DevOps refuses loudly,
+      // which is the correct outcome rather than a quiet no-op.
+      const existing = await c.get<any>(pullRequestsPath(repository, id), { 'api-version': '7.1' })
+      Object.assign(body, autoCompleteBody(existing.createdBy?.id ?? ''))
+    }
+
+    if (Object.keys(body).length === 0) {
+      throw new Error('update requires title, description, or completion options');
+    }
+
+    const pr = await c.patch<any>(
+      pullRequestsPath(repository, id),
+      body,
+      { 'api-version': '7.1' }
+    );
+    return JSON.stringify(pr, null, 2);
+  }
+
+  // Armed unless explicitly opted out (owner decision 2026-09-15: every PR is
+  // auto-complete). The caller must not need a second call to get this.
+  const { title } = args;
+  const arm = args.autoComplete !== false;
+  const source = currentBranch();
+  const target = PR_TARGET_BRANCH;
+  const description = args.description ?? '';
+
+  assertPrSourceBranch(source);
+  if (!title) throw new Error('title is required for create');
+
+  assertValidCreateMetadata(title, description)
+
+  const c = await getClient()
+  await assertBranchReadyForPr(c, repository, source, target)
+  const body: any = {
+    sourceRefName: `refs/heads/${source}`,
+    targetRefName: `refs/heads/${target}`,
+    title,
+    description,
+  };
+
+  const pr = await c.post<any>(
+    pullRequestsPath(repository),
+    body,
+    { 'api-version': '7.1' }
+  );
+
+  if (arm) {
+    // The PR we just created was created BY us, so its `createdBy` is the
+    // authenticated identity — no extra lookup needed to attribute the arming.
+    await c.patch<any>(
+      pullRequestsPath(repository, pr.pullRequestId),
+      autoCompleteBody(pr.createdBy?.id ?? ''),
+      { 'api-version': '7.1' }
+    );
+  }
+
+  return JSON.stringify(prCreateResult(repository, pr.pullRequestId, pr.title, pr.status, arm), null, 2);
+}