feat: add pr create and comment (task 0010)

`pr create` takes --title (required), --body/--body-file, --base, --head,
--assignee, --reviewer, repeatable name-resolved --label, and --milestone.
An omitted --head defaults to the current local branch; an omitted --base to
the repository's default branch. Before creating, an existing open PR for the
same base/head pair short-circuits to `pull_request: { number, url, already:
true }` rather than opening a duplicate; only an open PR does, since a closed
one's branches are free to be proposed again.

`pr comment <n>` posts through the shared issue-comment endpoint and returns
the created comment as `comment: { number, author, created, body }` (ADR 0008),
reporting a 404 as PR_NOT_FOUND since the caller asked about a pull request.

That comment block is now built in one place (src/comment.ts) for both issue
and pr comment, as ADR 0008 requires them to stay identical.

test/e2e/mutations.test.ts

@@ -3,16 +3,20 @@ import { runCliTest } from "../harness.js";
 import {
   fetchComments,
   fetchIssue,
+  fetchOpenPulls,
   provisionInstance,
+  seedBranch,
   type E2EInstance,
 } from "./provision.js";
 
 /**
- * The end-to-end tier for the issue mutations. These commands lean on behavior
- * the fixture server cannot attest to — above all that Gitea's label and
- * milestone name lookups really are case-insensitive, and that `CreateIssueOption`
- * really takes label *ids* rather than names. Both are asserted here against a
- * live instance by passing names in a different case than they were seeded in.
+ * The end-to-end tier for the issue and pull request mutations. These commands
+ * lean on behavior the fixture server cannot attest to — that Gitea's label and
+ * milestone name lookups really are case-insensitive, that `CreateIssueOption`
+ * really takes label *ids* rather than names, and that the by-base-head pull
+ * lookup behind `pr create`'s idempotency check really answers a 404 when no
+ * pull request exists for the pair and the open one when it does. Each is
+ * asserted here against a live instance rather than a recorded shape.
  */
 const E2E_URL = process.env.GITEA_AXI_E2E_URL;
 
@@ -23,19 +27,34 @@ function renderedNumber(stdout: string): number {
   return Number(match![1]);
 }
 
+/**
+ * One provisioned instance for every suite in this file: the suites run
+ * sequentially within the file, and sharing the instance keeps the bootstrap
+ * (which registers the site administrator) to a single run.
+ */
+let provisioned: Promise<E2EInstance> | undefined;
+function instanceOnce(): Promise<E2EInstance> {
+  provisioned ??= provisionInstance(E2E_URL!);
+  return provisioned;
+}
+
+function envFor(instance: E2EInstance): Record<string, string> {
+  return {
+    GITEA_AXI_API_URL: instance.baseUrl,
+    GITEA_AXI_TOKEN: instance.token,
+    GITEA_AXI_REPO: `${instance.owner}/${instance.repo}`,
+  };
+}
+
 describe.skipIf(!E2E_URL)("end-to-end: issue mutations", () => {
   let instance: E2EInstance;
 
   function env(): Record<string, string> {
-    return {
-      GITEA_AXI_API_URL: instance.baseUrl,
-      GITEA_AXI_TOKEN: instance.token,
-      GITEA_AXI_REPO: `${instance.owner}/${instance.repo}`,
-    };
+    return envFor(instance);
   }
 
   beforeAll(async () => {
-    instance = await provisionInstance(E2E_URL!);
+    instance = await instanceOnce();
   }, 150_000);
 
   it("creates an issue and reports the live number, state, and url", async () => {
@@ -119,3 +138,81 @@ describe.skipIf(!E2E_URL)("end-to-end: issue mutations", () => {
     expect(comments[0]!.body).toBe("A comment from the e2e tier.");
   });
 });
+
+describe.skipIf(!E2E_URL)("end-to-end: pull request mutations", () => {
+  let instance: E2EInstance;
+  const branch = "e2e-pr-branch";
+
+  function env(): Record<string, string> {
+    return envFor(instance);
+  }
+
+  beforeAll(async () => {
+    instance = await instanceOnce();
+    // The head branch has to exist, with a diff to propose, before a pull
+    // request can be opened from it.
+    await seedBranch(instance, branch);
+  }, 150_000);
+
+  it("creates a pull request, defaulting the base to the live repo's default branch", async () => {
+    const { stdout, exitCode } = await runCliTest(
+      ["pr", "create", "--title", "E2E created PR", "--head", branch, "--body", "From the e2e tier."],
+      { env: env() },
+    );
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("created:");
+    expect(stdout).toContain(`${instance.owner}/${instance.repo}/pulls/`);
+
+    const pulls = await fetchOpenPulls(instance);
+    expect(pulls).toHaveLength(1);
+    const created = pulls[0]!;
+    expect(created.number).toBe(renderedNumber(stdout));
+    expect(created.title).toBe("E2E created PR");
+    // The base was never passed: it came from the repository's own default branch.
+    expect((created.base as { ref?: string }).ref).toBe("main");
+    expect((created.head as { ref?: string }).ref).toBe(branch);
+  });
+
+  it("short-circuits a second create for the same branch pair, creating no duplicate", async () => {
+    // Whether Gitea's by-base-head lookup really finds the pull request opened
+    // above is the assumption the whole idempotency check rests on; fixtures can
+    // only assert the shape of an answer they were told to give.
+    const { stdout, exitCode } = await runCliTest(
+      ["pr", "create", "--title", "E2E duplicate PR", "--head", branch],
+      { env: env() },
+    );
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("pull_request:");
+    expect(stdout).toContain("already: true");
+    expect(stdout).not.toContain("created:");
+
+    const pulls = await fetchOpenPulls(instance);
+    expect(pulls).toHaveLength(1);
+    // The existing pull request is reported untouched — not retitled, not replaced.
+    expect(pulls[0]!.title).toBe("E2E created PR");
+  });
+
+  it("posts a comment on a live pull request and echoes it back", async () => {
+    const pulls = await fetchOpenPulls(instance);
+    const number = pulls[0]!.number as number;
+
+    const { stdout, exitCode } = await runCliTest(
+      ["pr", "comment", String(number), "--body", "A PR comment from the e2e tier."],
+      { env: env() },
+    );
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("comment:");
+    expect(stdout).toContain(`number: ${number}`);
+    expect(stdout).toContain(`author: ${instance.owner}`);
+    expect(stdout).toContain("body: A PR comment from the e2e tier.");
+
+    // Pull requests really do share the issue comment endpoint, so the comment
+    // is readable back through it.
+    const comments = await fetchComments(instance, number);
+    expect(comments).toHaveLength(1);
+    expect(comments[0]!.body).toBe("A PR comment from the e2e tier.");
+  });
+});

test/e2e/provision.ts

@@ -219,6 +219,37 @@ export async function provisionInstance(baseUrl: string): Promise<E2EInstance> {
   };
 }
 
+/**
+ * Create `branch` off the default branch, carrying one new file, so that a pull
+ * request opened from it has a real diff to propose.
+ */
+export async function seedBranch(instance: E2EInstance, branch: string): Promise<void> {
+  await apiRequest(
+    instance.baseUrl,
+    "POST",
+    `/repos/${instance.owner}/${instance.repo}/contents/${branch}.txt`,
+    instance.token,
+    {
+      content: Buffer.from(`Seeded on ${branch}.\n`).toString("base64"),
+      message: `Seed ${branch}`,
+      new_branch: branch,
+    },
+  );
+}
+
+/** Fetch the repository's open pull requests as Gitea returns them. */
+export async function fetchOpenPulls(
+  instance: E2EInstance,
+): Promise<Record<string, unknown>[]> {
+  const res = await apiRequest(
+    instance.baseUrl,
+    "GET",
+    `/repos/${instance.owner}/${instance.repo}/pulls?state=open`,
+    instance.token,
+  );
+  return (await res.json()) as Record<string, unknown>[];
+}
+
 /** Fetch a single issue as Gitea returns it, for verifying what a mutation wrote. */
 export async function fetchIssue(
   instance: E2EInstance,

test/help.test.ts

@@ -29,6 +29,23 @@ describe("--help", () => {
     expect(stdout).toContain("list");
   });
 
+  it("prints the pr group help and exits 0", async () => {
+    const { stdout, exitCode } = await runCliTest(["pr", "--help"]);
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("usage: gitea-axi pr");
+    expect(stdout).toContain("create");
+    expect(stdout).toContain("comment");
+  });
+
+  it("rejects an unknown pr subcommand with exit code 2", async () => {
+    const { stdout, exitCode } = await runCliTest(["pr", "frobnicate"]);
+
+    expect(exitCode).toBe(2);
+    expect(stdout).toContain("code: VALIDATION_ERROR");
+    expect(stdout).toContain("frobnicate");
+  });
+
   it("prints the version for --version", async () => {
     const { stdout, exitCode } = await runCliTest(["--version"]);
 

test/pr-comment.test.ts

@@ -0,0 +1,145 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { startFixtureServer, type FixtureServer } from "./fixture-server.js";
+import { postedBody, runCliTest, tempFiles, testModeEnv } from "./harness.js";
+
+// Pull request comments go through the shared issue-comment endpoint.
+const COMMENTS_PATH = "/api/v1/repos/testowner/testrepo/issues/12/comments";
+
+let server: FixtureServer;
+const files = tempFiles();
+
+afterEach(async () => {
+  await server.close();
+  files.cleanup();
+});
+
+function createdComment(fields: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: 900,
+    user: { login: "alexion" },
+    created_at: "2026-07-01T00:00:00Z",
+    body: "Looks good to me.",
+    pull_request_url: "http://127.0.0.1/testowner/testrepo/pulls/12",
+    ...fields,
+  };
+}
+
+function postedComment(): Record<string, unknown> {
+  return postedBody(server, COMMENTS_PATH);
+}
+
+describe("pr comment", () => {
+  it("posts the comment and renders number, author, created, and body", async () => {
+    server = await startFixtureServer([
+      { method: "POST", path: COMMENTS_PATH, status: 201, body: createdComment() },
+    ]);
+    const { stdout, exitCode } = await runCliTest(
+      ["pr", "comment", "12", "--body", "Looks good to me."],
+      { env: testModeEnv(server.url) },
+    );
+
+    expect(exitCode).toBe(0);
+    // The same `comment` block name as `issue comment`, per ADR 0008.
+    expect(stdout).toContain("comment:");
+    // `number` is the PR commented on, not the comment's own id.
+    expect(stdout).toContain("number: 12");
+    expect(stdout).toContain("author: alexion");
+    expect(stdout).toContain("body: Looks good to me.");
+    expect(stdout).not.toContain("900");
+    expect(postedComment()).toEqual({ body: "Looks good to me." });
+  });
+
+  it("reads the body from --body-file", async () => {
+    const path = files.write("comment.md", "From a file.");
+    server = await startFixtureServer([
+      { method: "POST", path: COMMENTS_PATH, status: 201, body: createdComment() },
+    ]);
+    const { exitCode } = await runCliTest(["pr", "comment", "12", "--body-file", path], {
+      env: testModeEnv(server.url),
+    });
+
+    expect(exitCode).toBe(0);
+    expect(postedComment()).toEqual({ body: "From a file." });
+  });
+
+  it("truncates a body over 800 chars in the output, with the inline hint", async () => {
+    const body = "z".repeat(1000);
+    server = await startFixtureServer([
+      { method: "POST", path: COMMENTS_PATH, status: 201, body: createdComment({ body }) },
+    ]);
+    const { stdout, exitCode } = await runCliTest(["pr", "comment", "12", "--body", body], {
+      env: testModeEnv(server.url),
+    });
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain(
+      `... (truncated, ${body.length} chars total - use --full to see complete body)`,
+    );
+    // The posted body itself is never truncated — only its echo in the output.
+    expect(postedComment()).toEqual({ body });
+  });
+
+  it("echoes the untruncated body with --full", async () => {
+    const body = "z".repeat(1000);
+    server = await startFixtureServer([
+      { method: "POST", path: COMMENTS_PATH, status: 201, body: createdComment({ body }) },
+    ]);
+    const { stdout, exitCode } = await runCliTest(
+      ["pr", "comment", "12", "--body", body, "--full"],
+      { env: testModeEnv(server.url) },
+    );
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain(body);
+    expect(stdout).not.toContain("truncated");
+  });
+
+  it("rejects a missing body before calling the API", async () => {
+    server = await startFixtureServer([]);
+    const { stdout, exitCode } = await runCliTest(["pr", "comment", "12"], {
+      env: testModeEnv(server.url),
+    });
+
+    expect(exitCode).toBe(2);
+    expect(stdout).toContain("code: VALIDATION_ERROR");
+    expect(stdout).toContain("--body");
+    expect(server.requests).toHaveLength(0);
+  });
+
+  it("rejects a missing pull request number before calling the API", async () => {
+    server = await startFixtureServer([]);
+    const { stdout, exitCode } = await runCliTest(["pr", "comment", "--body", "hi"], {
+      env: testModeEnv(server.url),
+    });
+
+    expect(exitCode).toBe(2);
+    expect(stdout).toContain("code: VALIDATION_ERROR");
+    expect(stdout).toContain("pull request number");
+    expect(server.requests).toHaveLength(0);
+  });
+
+  it("reports a nonexistent pull request as PR_NOT_FOUND, not ISSUE_NOT_FOUND", async () => {
+    server = await startFixtureServer([
+      { method: "POST", path: COMMENTS_PATH, status: 404, body: { message: "Not Found" } },
+    ]);
+    const { stdout, exitCode } = await runCliTest(["pr", "comment", "12", "--body", "hi"], {
+      env: testModeEnv(server.url),
+    });
+
+    expect(exitCode).toBe(1);
+    // The shared endpoint lives under /issues/, but the caller asked about a PR.
+    expect(stdout).toContain("code: PR_NOT_FOUND");
+    expect(stdout).toContain("Pull request #12");
+  });
+
+  it("prints help with --help without calling the API", async () => {
+    server = await startFixtureServer([]);
+    const { stdout, exitCode } = await runCliTest(["pr", "comment", "--help"], {
+      env: testModeEnv(server.url),
+    });
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("usage: gitea-axi pr comment <number>");
+    expect(server.requests).toHaveLength(0);
+  });
+});

test/pr-create.test.ts

@@ -0,0 +1,370 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, describe, expect, it } from "vitest";
+import { startFixtureServer, type FixtureServer } from "./fixture-server.js";
+import { postedBody, runCliTest, tempFiles, testModeEnv } from "./harness.js";
+
+const REPO_PATH = "/api/v1/repos/testowner/testrepo";
+const PULLS_PATH = `${REPO_PATH}/pulls`;
+const LABELS_PATH = `${REPO_PATH}/labels`;
+const MILESTONES_PATH = `${REPO_PATH}/milestones`;
+/** The by-base-head lookup Gitea exposes for the idempotency check. */
+const BASE_HEAD_PATH = `${PULLS_PATH}/main/feature-x`;
+
+const root = mkdtempSync(join(tmpdir(), "gitea-axi-pr-"));
+let repoCounter = 0;
+
+let server: FixtureServer;
+const files = tempFiles();
+
+afterEach(async () => {
+  await server.close();
+  files.cleanup();
+});
+
+afterAll(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+/**
+ * A real git repository checked out on `branch`, for the tests that exercise
+ * the `--head` default. It needs a commit: `git rev-parse --abbrev-ref HEAD`
+ * has no revision to resolve on an unborn branch.
+ */
+function repoOnBranch(branch: string): string {
+  const dir = mkdtempSync(join(root, `repo-${repoCounter++}-`));
+  execFileSync("git", ["init", "--quiet", "-b", branch], { cwd: dir });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "--quiet",
+    "--allow-empty", "-m", "seed"], { cwd: dir });
+  return dir;
+}
+
+/** Test-mode env plus the PATH the git subprocess needs to be found on. */
+function gitEnv(url: string): Record<string, string | undefined> {
+  return { ...testModeEnv(url), PATH: process.env.PATH };
+}
+
+function createdPull(fields: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    number: 12,
+    title: "Add the thing",
+    state: "open",
+    html_url: "http://127.0.0.1/testowner/testrepo/pulls/12",
+    ...fields,
+  };
+}
+
+/** No PR exists for the branch pair — Gitea answers the by-base-head lookup with a 404. */
+const NO_EXISTING_PR = {
+  method: "GET",
+  path: BASE_HEAD_PATH,
+  status: 404,
+  body: { message: "Not Found" },
+} as const;
+
+const DEFAULT_BRANCH = {
+  method: "GET",
+  path: REPO_PATH,
+  body: { default_branch: "main" },
+} as const;
+
+function postedPull(): Record<string, unknown> {
+  return postedBody(server, PULLS_PATH);
+}
+
+function posted(): boolean {
+  return server.requests.some((request) => request.method === "POST");
+}
+
+describe("pr create", () => {
+  it("creates a pull request and renders the created action block", async () => {
+    server = await startFixtureServer([
+      NO_EXISTING_PR,
+      { method: "POST", path: PULLS_PATH, status: 201, body: createdPull() },
+    ]);
+    const { stdout, exitCode } = await runCliTest(
+      ["pr", "create", "--title", "Add the thing", "--base", "main", "--head", "feature-x"],
+      { env: testModeEnv(server.url) },
+    );
+
+    expect(exitCode).toBe(0);
+    // The mutation ran, so the block is named for the action, not the entity.
+    expect(stdout).toContain("created:");
+    expect(stdout).not.toContain("pull_request:");
+    expect(stdout).toContain("number: 12");
+    expect(stdout).toContain('url: "http://127.0.0.1/testowner/testrepo/pulls/12"');
+    expect(postedPull()).toEqual({
+      title: "Add the thing",
+      base: "main",
+      head: "feature-x",
+    });
+  });
+
+  it("defaults --head to the current branch and --base to the repo's default branch", async () => {
+    server = await startFixtureServer([
+      DEFAULT_BRANCH,
+      NO_EXISTING_PR,
+      { method: "POST", path: PULLS_PATH, status: 201, body: createdPull() },
+    ]);
+    const { exitCode } = await runCliTest(["pr", "create", "--title", "T"], {
+      env: gitEnv(server.url),
+      cwd: repoOnBranch("feature-x"),
+    });
+
+    expect(exitCode).toBe(0);
+    expect(postedPull()).toEqual({ title: "T", base: "main", head: "feature-x" });
+  });
+
+  it("short-circuits to the existing open pull request without creating a duplicate", async () => {
+    server = await startFixtureServer([
+      { method: "GET", path: BASE_HEAD_PATH, body: createdPull() },
+    ]);
+    const { stdout, exitCode } = await runCliTest(
+      ["pr", "create", "--title", "Add the thing", "--base", "main", "--head", "feature-x"],
+      { env: testModeEnv(server.url) },
+    );
+
+    expect(exitCode).toBe(0);
+    // A no-op reports the entity, not the action.
+    expect(stdout).toContain("pull_request:");
+    expect(stdout).not.toContain("created:");
+    expect(stdout).toContain("number: 12");
+    expect(stdout).toContain('url: "http://127.0.0.1/testowner/testrepo/pulls/12"');
+    expect(stdout).toContain("already: true");
+    expect(posted()).toBe(false);
+  });
+
+  it("creates a fresh pull request when the only match for the branch pair is closed", async () => {
+    server = await startFixtureServer([
+      {
+        method: "GET",
+        path: BASE_HEAD_PATH,
+        body: createdPull({ number: 3, state: "closed" }),
+      },
+      { method: "POST", path: PULLS_PATH, status: 201, body: createdPull() },
+    ]);
+    const { stdout, exitCode } = await runCliTest(
+      ["pr", "create", "--title", "Add the thing", "--base", "main", "--head", "feature-x"],
+      { env: testModeEnv(server.url) },
+    );
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("created:");
+    expect(stdout).toContain("number: 12");
+    expect(posted()).toBe(true);
+  });
+
+  it("resolves --label and --milestone names and passes --assignee and --reviewer through", async () => {
+    server = await startFixtureServer([
+      {
+        method: "GET",
+        path: LABELS_PATH,
+        body: [
+          { id: 11, name: "bug" },
+          { id: 22, name: "Priority: High" },
+        ],
+      },
+      {
+        method: "GET",
+        path: MILESTONES_PATH,
+        query: { name: "v1.0" },
+        body: [{ id: 5, title: "V1.0" }],
+      },
+      NO_EXISTING_PR,
+      { method: "POST", path: PULLS_PATH, status: 201, body: createdPull() },
+    ]);
+    const { exitCode } = await runCliTest(
+      [
+        "pr", "create",
+        "--title", "T",
+        "--base", "main",
+        "--head", "feature-x",
+        "--label", "BUG",
+        "--label", "priority: high",
+        "--milestone", "v1.0",
+        "--assignee", "alexion",
+        "--reviewer", "reviewer-one",
+      ],
+      { env: testModeEnv(server.url) },
+    );
+
+    expect(exitCode).toBe(0);
+    expect(postedPull()).toEqual({
+      title: "T",
+      base: "main",
+      head: "feature-x",
+      labels: [11, 22],
+      milestone: 5,
+      assignees: ["alexion"],
+      reviewers: ["reviewer-one"],
+    });
+  });
+
+  it("rejects an unknown --label name with VALIDATION_ERROR and creates nothing", async () => {
+    server = await startFixtureServer([
+      { method: "GET", path: LABELS_PATH, body: [{ id: 11, name: "bug" }] },
+      NO_EXISTING_PR,
+    ]);
+    const { stdout, exitCode } = await runCliTest(
+      ["pr", "create", "--title", "T", "--base", "main", "--head", "feature-x", "--label", "nope"],
+      { env: testModeEnv(server.url) },
+    );
+
+    expect(exitCode).toBe(2);
+    expect(stdout).toContain("code: VALIDATION_ERROR");
+    expect(stdout).toContain("nope");
+    expect(posted()).toBe(false);
+  });
+
+  it("rejects an unknown --milestone name with VALIDATION_ERROR and creates nothing", async () => {
+    server = await startFixtureServer([
+      { method: "GET", path: MILESTONES_PATH, body: [] },
+      NO_EXISTING_PR,
+    ]);
+    const { stdout, exitCode } = await runCliTest(
+      ["pr", "create", "--title", "T", "--base", "main", "--head", "feature-x", "--milestone", "ghost"],
+      { env: testModeEnv(server.url) },
+    );
+
+    expect(exitCode).toBe(2);
+    expect(stdout).toContain("code: VALIDATION_ERROR");
+    expect(stdout).toContain("ghost");
+    expect(posted()).toBe(false);
+  });
+
+  it("reads the body from --body-file", async () => {
+    const path = files.write("body.md", "From a file.\n");
+    server = await startFixtureServer([
+      NO_EXISTING_PR,
+      { method: "POST", path: PULLS_PATH, status: 201, body: createdPull() },
+    ]);
+    const { exitCode } = await runCliTest(
+      ["pr", "create", "--title", "T", "--base", "main", "--head", "feature-x", "--body-file", path],
+      { env: testModeEnv(server.url) },
+    );
+
+    expect(exitCode).toBe(0);
+    expect(postedPull()).toEqual({
+      title: "T",
+      base: "main",
+      head: "feature-x",
+      body: "From a file.\n",
+    });
+  });
+
+  it("rejects a missing --title before calling the API", async () => {
+    server = await startFixtureServer([]);
+    const { stdout, exitCode } = await runCliTest(["pr", "create", "--base", "main", "--head", "x"], {
+      env: testModeEnv(server.url),
+    });
+
+    expect(exitCode).toBe(2);
+    expect(stdout).toContain("code: VALIDATION_ERROR");
+    expect(stdout).toContain("--title");
+    expect(server.requests).toHaveLength(0);
+  });
+
+  it("rejects an unresolvable current branch with VALIDATION_ERROR, before calling the API", async () => {
+    // Not a git repository, so the head branch cannot be read from git and the
+    // caller must name it themselves.
+    const cwd = mkdtempSync(join(root, "bare-"));
+    server = await startFixtureServer([]);
+    const { stdout, exitCode } = await runCliTest(["pr", "create", "--title", "T"], {
+      env: gitEnv(server.url),
+      cwd,
+    });
+
+    expect(exitCode).toBe(2);
+    expect(stdout).toContain("code: VALIDATION_ERROR");
+    expect(stdout).toContain("--head");
+    expect(server.requests).toHaveLength(0);
+  });
+
+  it("surfaces a failure to fetch the default branch", async () => {
+    server = await startFixtureServer([
+      { method: "GET", path: REPO_PATH, status: 403, body: { message: "forbidden" } },
+    ]);
+    const { stdout, exitCode } = await runCliTest(
+      ["pr", "create", "--title", "T", "--head", "feature-x"],
+      { env: gitEnv(server.url) },
+    );
+
+    expect(exitCode).toBe(1);
+    expect(stdout).toContain("code: FORBIDDEN");
+    expect(posted()).toBe(false);
+  });
+
+  it("surfaces a server-side rejection of the create", async () => {
+    server = await startFixtureServer([
+      NO_EXISTING_PR,
+      {
+        method: "POST",
+        path: PULLS_PATH,
+        status: 422,
+        body: { message: "head branch does not exist" },
+      },
+    ]);
+    const { stdout, exitCode } = await runCliTest(
+      ["pr", "create", "--title", "T", "--base", "main", "--head", "feature-x"],
+      { env: testModeEnv(server.url) },
+    );
+
+    expect(exitCode).toBe(2);
+    expect(stdout).toContain("code: VALIDATION_ERROR");
+    expect(stdout).toContain("head branch does not exist");
+  });
+
+  it("rejects an unexpected positional argument before calling the API", async () => {
+    server = await startFixtureServer([]);
+    const { stdout, exitCode } = await runCliTest(["pr", "create", "12", "--title", "T"], {
+      env: testModeEnv(server.url),
+    });
+
+    expect(exitCode).toBe(2);
+    expect(stdout).toContain("code: VALIDATION_ERROR");
+    expect(stdout).toContain("12");
+    expect(server.requests).toHaveLength(0);
+  });
+
+  it("surfaces a failure of the existing-pull-request check that is not a 404", async () => {
+    // Only a 404 means "no such pull request"; anything else is a real failure
+    // and must not be mistaken for a clear runway to create one.
+    server = await startFixtureServer([
+      { method: "GET", path: BASE_HEAD_PATH, status: 403, body: { message: "forbidden" } },
+    ]);
+    const { stdout, exitCode } = await runCliTest(
+      ["pr", "create", "--title", "T", "--base", "main", "--head", "feature-x"],
+      { env: testModeEnv(server.url) },
+    );
+
+    expect(exitCode).toBe(1);
+    expect(stdout).toContain("code: FORBIDDEN");
+    expect(posted()).toBe(false);
+  });
+
+  it("asks for --base when the repository reports no default branch", async () => {
+    server = await startFixtureServer([{ method: "GET", path: REPO_PATH, body: {} }]);
+    const { stdout, exitCode } = await runCliTest(
+      ["pr", "create", "--title", "T", "--head", "feature-x"],
+      { env: testModeEnv(server.url) },
+    );
+
+    expect(exitCode).toBe(2);
+    expect(stdout).toContain("code: VALIDATION_ERROR");
+    expect(stdout).toContain("--base");
+    expect(posted()).toBe(false);
+  });
+
+  it("prints help with --help without calling the API", async () => {
+    server = await startFixtureServer([]);
+    const { stdout, exitCode } = await runCliTest(["pr", "create", "--help"], {
+      env: testModeEnv(server.url),
+    });
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("usage: gitea-axi pr create");
+    expect(server.requests).toHaveLength(0);
+  });
+});