+
+
+
- A JetBrains-grade Git experience for VS Code & Cursor — the whole workflow, not just one piece. + A free, open-source, JetBrains-grade Git suite for VS Code, Cursor, and desktop.
+
+ 
+ 
Logo & brand assets live in brand/.
+ --- +## Get GitStudio + +### VS Code / Cursor extension + +Install **GitStudio** from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=gitstudio.gitstudio) or [Open VSX](https://open-vsx.org/extension/gitstudio/gitstudio) (VSCodium, Gitpod, …), or from the command line: + +```bash +code --install-extension gitstudio.gitstudio # VS Code +cursor --install-extension gitstudio.gitstudio # Cursor +``` + +### Desktop app + +Download the installer for your platform from the [latest GitHub Release](https://github.com/GitStudioHQ/gitstudio/releases/latest) or from [gitstudio.dev](https://gitstudio.dev): + +| Platform | Installer | +|---|---| +| **macOS — Apple Silicon** | `GitStudio-` viewer (no more github.com).
+ */
+export async function jobLog(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ req: { jobId: number },
+): Promise {
+ const res = await fetchSignedRedirect(
+ bearer(client),
+ `/repos/${enc(owner)}/${enc(repo)}/actions/jobs/${req.jobId}/logs`,
+ );
+ return res.text();
+}
+
+/**
+ * Plain-text logs for a WHOLE run, assembled from its jobs. The native
+ * `…/runs/{id}/logs` endpoint returns a ZIP (heavy + needs unzip in-process);
+ * instead we fetch the run's jobs and concatenate each job's `jobLog` under a
+ * `=== job name ===` banner — the same text, streamable straight into the viewer.
+ * One job's failure is annotated inline rather than failing the whole aggregate.
+ */
+export async function runLog(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ req: { runId: number },
+): Promise {
+ const jobsRaw = await client.request<{ jobs?: RawJob[] }>(
+ "GET",
+ `/repos/${enc(owner)}/${enc(repo)}/actions/runs/${req.runId}/jobs?per_page=100`,
+ );
+ const jobs = jobsRaw.jobs ?? [];
+ if (jobs.length === 0) return "This run reported no jobs.";
+ const parts: string[] = [];
+ for (const j of jobs) {
+ const name = j.name ?? `job ${j.id}`;
+ parts.push(`=== ${name} ===`);
+ try {
+ parts.push((await jobLog(client, owner, repo, { jobId: j.id })).trimEnd());
+ } catch (err) {
+ parts.push(`[logs unavailable: ${err instanceof Error ? err.message : String(err)}]`);
+ }
+ parts.push(""); // blank line between jobs
+ }
+ return parts.join("\n");
+}
+
+/** Artifacts produced by a run (GET /actions/runs/{id}/artifacts). */
+export async function artifacts(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ runId: number,
+): Promise {
+ const raw = await client.request<{ artifacts?: RawArtifact[] }>(
+ "GET",
+ `/repos/${enc(owner)}/${enc(repo)}/actions/runs/${runId}/artifacts?per_page=100`,
+ );
+ return (raw.artifacts ?? []).map(mapArtifact);
+}
+
+/** All repo Actions secrets — names + updatedAt only (values are write-only). */
+export async function secrets(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+): Promise {
+ const raw = await client.request<{ secrets?: RawSecret[] }>(
+ "GET",
+ `/repos/${enc(owner)}/${enc(repo)}/actions/secrets?per_page=100`,
+ );
+ return (raw.secrets ?? []).map(mapSecret);
+}
+
+/** All repo Actions variables — name, value, updatedAt (values ARE readable). */
+export async function variables(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+): Promise {
+ const raw = await client.request<{ variables?: RawVariable[] }>(
+ "GET",
+ `/repos/${enc(owner)}/${enc(repo)}/actions/variables?per_page=100`,
+ );
+ return (raw.variables ?? []).map(mapVariable);
+}
+
+// ── Mutations (never throw — return CommitActionResult) ──────────────────────
+
+const ok = (msg?: string): CommitActionResult => ({ ok: true, changed: false, message: msg });
+const fail = (err: unknown): CommitActionResult => ({
+ ok: false,
+ changed: false,
+ message: err instanceof Error ? err.message : String(err),
+});
+
+/** Re-run every job in a run (POST /actions/runs/{id}/rerun). */
+export async function rerunRun(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ id: number,
+): Promise {
+ try {
+ await client.requestBody("POST", `/repos/${enc(owner)}/${enc(repo)}/actions/runs/${id}/rerun`, {});
+ return ok();
+ } catch (err) {
+ return fail(err);
+ }
+}
+
+/** Re-run only the failed jobs (POST /actions/runs/{id}/rerun-failed-jobs). */
+export async function rerunFailedJobs(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ id: number,
+): Promise {
+ try {
+ await client.requestBody(
+ "POST",
+ `/repos/${enc(owner)}/${enc(repo)}/actions/runs/${id}/rerun-failed-jobs`,
+ {},
+ );
+ return ok();
+ } catch (err) {
+ return fail(err);
+ }
+}
+
+/** Cancel an in-progress run (POST /actions/runs/{id}/cancel). */
+export async function cancelRun(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ id: number,
+): Promise {
+ try {
+ await client.requestBody("POST", `/repos/${enc(owner)}/${enc(repo)}/actions/runs/${id}/cancel`, {});
+ return ok();
+ } catch (err) {
+ return fail(err);
+ }
+}
+
+/**
+ * Manually trigger a `workflow_dispatch` (POST /actions/workflows/{id}/dispatches).
+ * GitHub requires every input value to be a STRING in the payload (even
+ * booleans/numbers); the renderer already collects strings and omits empties so
+ * the workflow's declared defaults apply server-side. Returns 204 No Content on
+ * success — `requestBody` treats any 2xx as success.
+ */
+export async function dispatchWorkflow(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ req: { workflowId: number; ref: string; inputs: Record },
+): Promise {
+ try {
+ const body: { ref: string; inputs?: Record } = { ref: req.ref };
+ if (req.inputs && Object.keys(req.inputs).length) body.inputs = req.inputs;
+ await client.requestBody(
+ "POST",
+ `/repos/${enc(owner)}/${enc(repo)}/actions/workflows/${req.workflowId}/dispatches`,
+ body,
+ );
+ return ok();
+ } catch (err) {
+ return fail(err);
+ }
+}
+
+/**
+ * Download a run artifact's ZIP to the user's Downloads folder
+ * (GET /actions/artifacts/{id}/zip → signed redirect → bytes → ~/Downloads).
+ * Returns ok with the saved absolute path so the renderer can toast it. The
+ * filename is sanitized and `.zip`-suffixed; we never overwrite blindly — a
+ * collision gets a `(1)`, `(2)`… suffix. Expired artifacts 410 → clean message.
+ */
+export async function downloadArtifact(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ req: { id: number; name: string },
+): Promise {
+ try {
+ const res = await fetchSignedRedirect(
+ bearer(client),
+ `/repos/${enc(owner)}/${enc(repo)}/actions/artifacts/${req.id}/zip`,
+ );
+ const bytes = Buffer.from(await res.arrayBuffer());
+ const dest = await uniqueDownloadPath(safeFileName(req.name) + ".zip");
+ await writeFile(dest, bytes);
+ return ok(`Saved to ${dest}`);
+ } catch (err) {
+ return fail(err);
+ }
+}
+
+/**
+ * Create or update a repo Actions secret. Encrypting the value needs a libsodium
+ * sealed box against the repo's public key — and this app bundles NO crypto
+ * dependency (no libsodium-wrappers / tweetnacl), so we cannot encrypt safely.
+ * Rather than ship a broken write, we return a clear, actionable message. Listing
+ * + delete (and ALL of variables) work without crypto and are fully implemented.
+ */
+export async function setSecret(
+ _client: GitHubClient,
+ _owner: string,
+ _repo: string,
+ _req: { name: string; value: string },
+): Promise {
+ return {
+ ok: false,
+ changed: false,
+ message:
+ "Creating or updating secrets needs the libsodium encryption library, which isn't bundled in this build. You can still delete secrets here; to add one, use github.com for now.",
+ };
+}
+
+/** Delete a repo Actions secret (DELETE /actions/secrets/{name}). */
+export async function deleteSecret(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ name: string,
+): Promise {
+ try {
+ await client.requestBody(
+ "DELETE",
+ `/repos/${enc(owner)}/${enc(repo)}/actions/secrets/${enc(name)}`,
+ {},
+ );
+ return ok();
+ } catch (err) {
+ return fail(err);
+ }
+}
+
+/**
+ * Create or update a repo Actions variable. Variables are plaintext (no crypto),
+ * so this works fully. GitHub has no upsert: PATCH the existing variable, and on
+ * a 404 (it doesn't exist yet) fall back to POST to create it.
+ */
+export async function setVariable(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ req: { name: string; value: string },
+): Promise {
+ const base = `/repos/${enc(owner)}/${enc(repo)}/actions/variables`;
+ try {
+ await client.requestBody("PATCH", `${base}/${enc(req.name)}`, {
+ name: req.name,
+ value: req.value,
+ });
+ return ok();
+ } catch (err) {
+ if (!isNotFound(err)) return fail(err);
+ // Doesn't exist yet → create it.
+ try {
+ await client.requestBody("POST", base, { name: req.name, value: req.value });
+ return ok();
+ } catch (createErr) {
+ return fail(createErr);
+ }
+ }
+}
+
+/** Delete a repo Actions variable (DELETE /actions/variables/{name}). */
+export async function deleteVariable(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ name: string,
+): Promise {
+ try {
+ await client.requestBody(
+ "DELETE",
+ `/repos/${enc(owner)}/${enc(repo)}/actions/variables/${enc(name)}`,
+ {},
+ );
+ return ok();
+ } catch (err) {
+ return fail(err);
+ }
+}
+
+// ── Download helpers ─────────────────────────────────────────────────────────
+
+/** The client's 404 maps to "Not found on GitHub." — detect it to drive the
+ * variable PATCH→POST upsert without a second HEAD round-trip. */
+function isNotFound(err: unknown): boolean {
+ return err instanceof Error && /not found on github/i.test(err.message);
+}
+
+/** Sanitize an artifact name into a single safe path segment (no separators,
+ * control chars, or leading dots), so the save path can't escape Downloads. */
+function safeFileName(name: string): string {
+ const cleaned = (name || "artifact")
+ .replace(/[/\\:*?"<>| -]+/g, "_")
+ .replace(/^\.+/, "")
+ .replace(/[. ]+$/, "")
+ .slice(0, 200)
+ .trim();
+ return cleaned || "artifact";
+}
+
+/** A non-clobbering path in ~/Downloads: "name.zip", then "name (1).zip", … */
+async function uniqueDownloadPath(fileName: string): Promise {
+ const dir = join(homedir(), "Downloads");
+ const dot = fileName.lastIndexOf(".");
+ const stem = dot > 0 ? fileName.slice(0, dot) : fileName;
+ const ext = dot > 0 ? fileName.slice(dot) : "";
+ for (let i = 0; i < 1000; i++) {
+ const candidate = join(dir, i === 0 ? fileName : `${stem} (${i})${ext}`);
+ if (!(await pathExists(candidate))) return candidate;
+ }
+ // Astronomically unlikely; fall back to a timestamped name.
+ return join(dir, `${stem}-${Date.now()}${ext}`);
+}
+
+/** True when a file/dir exists at `p` (no throw). */
+async function pathExists(p: string): Promise {
+ try {
+ await access(p);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+// ── Minimal YAML reader for `on.workflow_dispatch.inputs:` ────────────────────
+
+/**
+ * A deliberately small indent-walking parser — enough to drive the dispatch
+ * form, no external YAML dependency. Handles scalar inputs plus `required`,
+ * `default`, `description`, `type`, and `type: choice` with an `options:` list.
+ * Returns [] for the list form `on: [workflow_dispatch]` and when there are no
+ * inputs. Best-effort: if it yields nothing the form still shows the ref field,
+ * which is a valid dispatch (POST accepts `{ ref }` with no inputs).
+ */
+function parseDispatchInputs(yaml: string): WorkflowDispatchInput[] {
+ const lines = yaml.split(/\r?\n/);
+ const indentOf = (s: string): number => s.length - s.replace(/^\s+/, "").length;
+
+ // Find `workflow_dispatch:` then its `inputs:` child.
+ let i = lines.findIndex((l) => /^\s*workflow_dispatch\s*:/.test(l));
+ if (i < 0) return [];
+ const wdIndent = indentOf(lines[i]);
+ let inputsIndent = -1;
+ i += 1;
+ for (; i < lines.length; i++) {
+ const l = lines[i];
+ if (l.trim() === "" || l.trim().startsWith("#")) continue;
+ const ind = indentOf(l);
+ if (ind <= wdIndent) return []; // left the workflow_dispatch block — no inputs
+ if (/^\s*inputs\s*:/.test(l)) {
+ inputsIndent = ind;
+ i += 1;
+ break;
+ }
+ }
+ if (inputsIndent < 0) return [];
+
+ const out: WorkflowDispatchInput[] = [];
+ let cur: WorkflowDispatchInput | undefined;
+ let inOptions = false;
+ // The column of the first real input key; once locked, only keys at exactly
+ // this indent start a new input — so child props (options:, description:, …)
+ // at a deeper indent are never misread as inputs.
+ let keyIndent = -1;
+ for (; i < lines.length; i++) {
+ const rawLine = lines[i];
+ if (rawLine.trim() === "" || rawLine.trim().startsWith("#")) continue;
+ const ind = indentOf(rawLine);
+ if (ind <= inputsIndent) break; // dedented out of `inputs:`
+ const line = rawLine.trim();
+
+ // A new input key sits one level under `inputs:`.
+ const keyM = line.match(/^([A-Za-z0-9_.-]+)\s*:\s*$/);
+ const isNewKey =
+ !!keyM &&
+ !line.startsWith("-") &&
+ (keyIndent < 0 ? ind <= inputsIndent + 4 : ind === keyIndent);
+ if (isNewKey && keyM) {
+ if (keyIndent < 0) keyIndent = ind;
+ cur = { name: keyM[1], description: "", required: false, default: "", type: "string" };
+ out.push(cur);
+ inOptions = false;
+ continue;
+ }
+ if (!cur) continue;
+
+ if (inOptions) {
+ const optM = line.match(/^-\s*(.+)$/);
+ if (optM) {
+ (cur.options ??= []).push(stripYamlScalar(optM[1]));
+ continue;
+ }
+ inOptions = false;
+ }
+
+ const kv = line.match(/^(description|required|default|type|options)\s*:\s*(.*)$/);
+ if (!kv) continue;
+ const key = kv[1];
+ const value = kv[2].trim();
+ if (key === "options") {
+ inOptions = true;
+ cur.options = [];
+ } else if (key === "required") {
+ cur.required = /^true$/i.test(stripYamlScalar(value));
+ } else if (key === "type") {
+ cur.type = stripYamlScalar(value) || "string";
+ } else if (key === "default") {
+ cur.default = stripYamlScalar(value);
+ } else if (key === "description") {
+ cur.description = stripYamlScalar(value);
+ }
+ }
+ return out;
+}
+
+/** Strip surrounding single/double quotes from a YAML scalar. */
+function stripYamlScalar(s: string): string {
+ const t = s.trim();
+ if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+ return t.slice(1, -1);
+ }
+ return t;
+}
diff --git a/apps/desktop/src/main/github/gists.ts b/apps/desktop/src/main/github/gists.ts
new file mode 100644
index 0000000..aff2202
--- /dev/null
+++ b/apps/desktop/src/main/github/gists.ts
@@ -0,0 +1,150 @@
+// Gists — the user-scoped GitHub section (NOT repo-scoped). These standalone
+// functions are invoked from main.ts via `github.withClient((c) => gistX(c, …))`,
+// so they take only the client (no owner/repo). They hit `/gists` and
+// `/gists/{id}` directly, authed as the current user via the Bearer token.
+//
+// Convention (post-2026-06-27): read functions THROW on API error so the
+// renderer can show a real errorState + Retry; mutation functions never throw —
+// they return a CommitActionResult ({ ok, changed, message? }) so the view can
+// toast the message. `changed` is always false for gist ops (gists touch no
+// local git state); on create, `message` carries the new gist id so the caller
+// can select it after a refresh.
+
+import { GitHubClient, enc, mapUser, RawUser } from "../githubClient";
+import type {
+ CommitActionResult,
+ GistCreate,
+ GistFile,
+ GistInfo,
+ GistUpdate,
+} from "../../shared/ipc";
+
+// ── Raw API shapes (the JSON GitHub returns) ─────────────────────────────────
+
+interface RawGistFile {
+ filename?: string;
+ language?: string | null;
+ type?: string;
+ size?: number;
+ raw_url?: string;
+ content?: string;
+ truncated?: boolean;
+}
+
+interface RawGist {
+ id: string;
+ description: string | null;
+ public: boolean;
+ html_url: string;
+ owner?: RawUser | null;
+ created_at: string;
+ updated_at: string;
+ comments?: number;
+ files: Record;
+}
+
+// ── Mappers (raw → the typed ipc shapes the renderer consumes) ───────────────
+
+function mapGistFile(key: string, f: RawGistFile): GistFile {
+ return {
+ filename: f.filename ?? key,
+ language: f.language ?? "",
+ type: f.type ?? "",
+ size: f.size ?? 0,
+ rawUrl: f.raw_url ?? "",
+ content: f.content ?? "",
+ truncated: f.truncated ?? false,
+ };
+}
+
+function mapGist(g: RawGist): GistInfo {
+ const files: GistFile[] = Object.entries(g.files ?? {})
+ .filter((entry): entry is [string, RawGistFile] => entry[1] != null)
+ .map(([key, f]) => mapGistFile(key, f));
+ return {
+ id: g.id,
+ description: g.description ?? "",
+ public: g.public,
+ htmlUrl: g.html_url,
+ owner: mapUser(g.owner ?? null),
+ createdAt: g.created_at,
+ updatedAt: g.updated_at,
+ fileCount: files.length,
+ files,
+ comments: g.comments ?? 0,
+ };
+}
+
+function errMessage(err: unknown): string {
+ return err instanceof Error ? err.message : String(err);
+}
+
+// ── Reads (throw on error) ───────────────────────────────────────────────────
+
+/** The authenticated user's own gists, newest first (GitHub default: updated desc).
+ * The list payload carries file METADATA only — file `content` is null here, so
+ * the detail view re-fetches the full gist via `getGist`. */
+export async function listGists(client: GitHubClient): Promise {
+ const raw = await client.request("GET", "/gists?per_page=100");
+ return raw.map(mapGist);
+}
+
+/** A single gist with full file `content` (and `truncated` flags for big files). */
+export async function getGist(client: GitHubClient, id: string): Promise {
+ const raw = await client.request("GET", `/gists/${enc(id)}`);
+ return mapGist(raw);
+}
+
+// ── Mutations (return CommitActionResult; never throw) ───────────────────────
+
+/** Create a single-file gist. On success, `message` carries the new gist id. */
+export async function createGist(
+ client: GitHubClient,
+ input: GistCreate,
+): Promise {
+ try {
+ const created = await client.request("POST", "/gists", {
+ description: input.description,
+ public: input.public,
+ files: { [input.filename]: { content: input.content } },
+ });
+ return { ok: true, changed: false, message: created.id };
+ } catch (err) {
+ return { ok: false, changed: false, message: errMessage(err) };
+ }
+}
+
+/** Edit a gist's description and its (single) file. GitHub keys files by their
+ * CURRENT name; to rename, set `filename` on the value to the new name; to
+ * change content, set `content`. Keep the key = the existing filename. */
+export async function updateGist(
+ client: GitHubClient,
+ input: GistUpdate,
+): Promise {
+ try {
+ const file: { content: string; filename?: string } = { content: input.content };
+ if (input.newFilename && input.newFilename !== input.filename) {
+ file.filename = input.newFilename;
+ }
+ await client.request("PATCH", `/gists/${enc(input.id)}`, {
+ description: input.description,
+ files: { [input.filename]: file },
+ });
+ return { ok: true, changed: false };
+ } catch (err) {
+ return { ok: false, changed: false, message: errMessage(err) };
+ }
+}
+
+/** Permanently delete a gist (204 on success). */
+export async function deleteGist(
+ client: GitHubClient,
+ id: string,
+): Promise {
+ try {
+ await client.request("DELETE", `/gists/${enc(id)}`);
+ return { ok: true, changed: false };
+ } catch (err) {
+ return { ok: false, changed: false, message: errMessage(err) };
+ }
+}
diff --git a/apps/desktop/src/main/github/issues.ts b/apps/desktop/src/main/github/issues.ts
new file mode 100644
index 0000000..e71b231
--- /dev/null
+++ b/apps/desktop/src/main/github/issues.ts
@@ -0,0 +1,406 @@
+// Issues — the repo-scoped GitHub Issues surface for the desktop app.
+//
+// Standalone, self-contained functions over the shared `GitHubClient`
+// primitives. main.ts wires each channel through `github.withRepo((c, o, r) =>
+// …)`, so every function here takes `(client, owner, repo, …args)`.
+//
+// Convention (post-2026-06-27):
+// • READ functions THROW on error (the client primitives already throw via
+// `toError`) so the renderer can show a real error state.
+// • MUTATION functions never throw — they return a CommitActionResult-shaped
+// `{ ok, changed, message? }` so the renderer can toast cleanly.
+//
+// Everything here is REST (Issues live under the OAuth `repo` scope, same as
+// PRs); GraphQL is only needed for Projects v2, which lives elsewhere.
+
+import { GitHubClient, enc, mapUser, type RawUser } from "../githubClient";
+import type {
+ CommitActionResult,
+ GitHubUser,
+ IssueComment,
+ IssueDetail,
+ IssueInfo,
+ MilestoneInfo,
+ RepoLabel,
+} from "../../shared/ipc";
+
+// ── Raw GitHub payloads (only what we read) ──────────────────────────────────
+
+interface RawLabelRef {
+ name: string;
+ color: string;
+}
+interface RawIssue {
+ number: number;
+ title: string;
+ body: string | null;
+ state: string;
+ html_url: string;
+ user: RawUser | null;
+ created_at: string;
+ updated_at: string;
+ comments: number;
+ labels?: (RawLabelRef | string)[];
+ assignees?: RawUser[];
+ pull_request?: unknown;
+}
+interface RawIssueComment {
+ id: number;
+ user?: RawUser | null;
+ body?: string | null;
+ created_at: string;
+}
+interface RawRepoLabel {
+ name: string;
+ color: string;
+ description?: string | null;
+}
+interface RawMilestone {
+ number: number;
+ title: string;
+ state: string;
+ due_on?: string | null;
+ open_issues: number;
+ closed_issues: number;
+}
+
+// ── Mappers ──────────────────────────────────────────────────────────────────
+
+function mapIssue(i: RawIssue): IssueInfo {
+ return {
+ number: i.number,
+ title: i.title,
+ body: i.body,
+ state: i.state,
+ htmlUrl: i.html_url,
+ user: mapUser(i.user),
+ createdAt: i.created_at,
+ updatedAt: i.updated_at,
+ comments: i.comments,
+ labels: (i.labels ?? []).map((l) =>
+ typeof l === "string" ? { name: l, color: "888888" } : { name: l.name, color: l.color },
+ ),
+ assignees: (i.assignees ?? [])
+ .map(mapUser)
+ .filter((u): u is GitHubUser => u !== null),
+ };
+}
+
+function mapComment(c: RawIssueComment): IssueComment {
+ return {
+ id: c.id,
+ author: mapUser(c.user ?? null),
+ body: c.body ?? "",
+ createdAt: c.created_at,
+ };
+}
+
+function mapLabel(l: RawRepoLabel): RepoLabel {
+ return { name: l.name, color: l.color, description: l.description ?? null };
+}
+
+function mapMilestone(m: RawMilestone): MilestoneInfo {
+ return {
+ number: m.number,
+ title: m.title,
+ state: m.state === "closed" ? "closed" : "open",
+ dueOn: m.due_on ?? null,
+ openIssues: m.open_issues,
+ closedIssues: m.closed_issues,
+ };
+}
+
+/** Coerce any thrown value into a clean, user-facing message. */
+function errMessage(err: unknown): string {
+ return err instanceof Error ? err.message : String(err);
+}
+
+// ── Reads (THROW on error) ───────────────────────────────────────────────────
+
+/**
+ * Open (or closed/all) issues for the repo, newest-updated first. The `issues`
+ * endpoint also returns PRs, so we drop anything carrying a `pull_request` node.
+ */
+export async function listIssues(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ state: "open" | "closed" | "all" = "open",
+): Promise {
+ const raw = await client.request(
+ "GET",
+ `/repos/${enc(owner)}/${enc(repo)}/issues?state=${state}&sort=updated&direction=desc&per_page=50`,
+ );
+ return raw.filter((i) => !i.pull_request).map(mapIssue);
+}
+
+/**
+ * One issue plus its comment timeline (oldest → newest, GitHub's default order)
+ * and the current assignee logins. The issue read throws on error; the comments
+ * read is best-effort (a comment-fetch hiccup shouldn't blank the whole detail).
+ */
+export async function getIssueDetail(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ n: number,
+): Promise {
+ const issue = mapIssue(
+ await client.request("GET", `/repos/${enc(owner)}/${enc(repo)}/issues/${n}`),
+ );
+ const comments = await client
+ .request(
+ "GET",
+ `/repos/${enc(owner)}/${enc(repo)}/issues/${n}/comments?per_page=100`,
+ )
+ .then((raw) => raw.map(mapComment))
+ .catch(() => [] as IssueComment[]);
+ return { issue, comments, assignees: issue.assignees.map((a) => a.login) };
+}
+
+/** The repo's defined labels, for the label picker (GET …/labels). */
+export async function listLabels(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+): Promise {
+ const raw = await client.request(
+ "GET",
+ `/repos/${enc(owner)}/${enc(repo)}/labels?per_page=100`,
+ );
+ return raw.map(mapLabel);
+}
+
+/** Repo-level label CRUD (the maintainer's label management surface). */
+export async function createLabel(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ req: { name: string; color: string; description?: string },
+): Promise {
+ try {
+ await client.requestBody("POST", `/repos/${enc(owner)}/${enc(repo)}/labels`, {
+ name: req.name,
+ color: req.color.replace(/^#/, ""),
+ description: req.description ?? "",
+ });
+ return { ok: true, changed: true };
+ } catch (err) {
+ return { ok: false, changed: false, message: errMessage(err) };
+ }
+}
+
+export async function updateLabel(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ req: { name: string; newName?: string; color?: string; description?: string },
+): Promise {
+ try {
+ const body: Record = {};
+ if (req.newName) body.new_name = req.newName;
+ if (req.color) body.color = req.color.replace(/^#/, "");
+ if (req.description !== undefined) body.description = req.description;
+ await client.requestBody(
+ "PATCH",
+ `/repos/${enc(owner)}/${enc(repo)}/labels/${enc(req.name)}`,
+ body,
+ );
+ return { ok: true, changed: true };
+ } catch (err) {
+ return { ok: false, changed: false, message: errMessage(err) };
+ }
+}
+
+export async function deleteLabel(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ name: string,
+): Promise {
+ try {
+ await client.request("DELETE", `/repos/${enc(owner)}/${enc(repo)}/labels/${enc(name)}`);
+ return { ok: true, changed: true };
+ } catch (err) {
+ return { ok: false, changed: false, message: errMessage(err) };
+ }
+}
+
+/**
+ * Every milestone (open AND closed) for the repo, for the milestone filter and
+ * the per-issue milestone picker. `state=all` so closed milestones still show
+ * (an issue can carry a closed milestone). Newest-due first is GitHub's default.
+ */
+export async function milestones(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+): Promise {
+ const raw = await client.request(
+ "GET",
+ `/repos/${enc(owner)}/${enc(repo)}/milestones?state=all&per_page=100`,
+ );
+ return raw.map(mapMilestone);
+}
+
+// ── Mutations (never throw — return CommitActionResult) ──────────────────────
+
+/**
+ * Open a new issue. Returns the created issue's `number` so the caller can
+ * select it. This is its own result shape (carries `number`) per the channel.
+ */
+export async function createIssue(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ req: { title: string; body?: string },
+): Promise<{ ok: boolean; number?: number; message?: string }> {
+ const title = req.title.trim();
+ if (!title) {
+ return { ok: false, message: "An issue needs a title." };
+ }
+ try {
+ const created = await client.request(
+ "POST",
+ `/repos/${enc(owner)}/${enc(repo)}/issues`,
+ { title, body: req.body ?? "" },
+ );
+ return { ok: true, number: created.number };
+ } catch (err) {
+ return { ok: false, message: errMessage(err) };
+ }
+}
+
+/** Post a comment on an issue (POST …/issues/{n}/comments). */
+export async function commentIssue(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ req: { number: number; body: string },
+): Promise {
+ const body = req.body.trim();
+ if (!body) {
+ return { ok: false, changed: false, message: "Write a comment first." };
+ }
+ try {
+ await client.requestBody(
+ "POST",
+ `/repos/${enc(owner)}/${enc(repo)}/issues/${req.number}/comments`,
+ { body },
+ );
+ return { ok: true, changed: true };
+ } catch (err) {
+ return { ok: false, changed: false, message: errMessage(err) };
+ }
+}
+
+/** Close or reopen an issue (PATCH state). */
+export async function setIssueState(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ req: { number: number; state: "open" | "closed" },
+): Promise {
+ try {
+ await client.requestBody("PATCH", `/repos/${enc(owner)}/${enc(repo)}/issues/${req.number}`, {
+ state: req.state,
+ });
+ return { ok: true, changed: true };
+ } catch (err) {
+ return { ok: false, changed: false, message: errMessage(err) };
+ }
+}
+
+/** Edit an issue's title and/or body (PATCH). */
+export async function editIssue(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ req: { number: number; title?: string; body?: string },
+): Promise {
+ const fields: { title?: string; body?: string } = {};
+ if (typeof req.title === "string") fields.title = req.title.trim();
+ if (typeof req.body === "string") fields.body = req.body;
+ if (fields.title !== undefined && fields.title === "") {
+ return { ok: false, changed: false, message: "An issue needs a title." };
+ }
+ if (fields.title === undefined && fields.body === undefined) {
+ return { ok: false, changed: false, message: "Nothing to update." };
+ }
+ try {
+ await client.requestBody(
+ "PATCH",
+ `/repos/${enc(owner)}/${enc(repo)}/issues/${req.number}`,
+ fields,
+ );
+ return { ok: true, changed: true };
+ } catch (err) {
+ return { ok: false, changed: false, message: errMessage(err) };
+ }
+}
+
+/**
+ * Replace the issue's full label set (PUT …/issues/{n}/labels). PUT replaces
+ * the whole set, which is exactly what the label-toggle picker needs.
+ */
+export async function setIssueLabels(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ req: { number: number; labels: string[] },
+): Promise {
+ try {
+ await client.requestBody(
+ "PUT",
+ `/repos/${enc(owner)}/${enc(repo)}/issues/${req.number}/labels`,
+ { labels: req.labels },
+ );
+ return { ok: true, changed: true };
+ } catch (err) {
+ return { ok: false, changed: false, message: errMessage(err) };
+ }
+}
+
+/**
+ * Replace the issue's assignee set. GitHub has no single "replace assignees"
+ * call, but the `assignees` array on PATCH /issues/{n} replaces the set
+ * atomically. Non-collaborator logins are silently dropped by GitHub (no 422);
+ * the renderer re-fetches afterward to show the authoritative set.
+ */
+export async function setIssueAssignees(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ req: { number: number; assignees: string[] },
+): Promise {
+ try {
+ await client.requestBody("PATCH", `/repos/${enc(owner)}/${enc(repo)}/issues/${req.number}`, {
+ assignees: req.assignees,
+ });
+ return { ok: true, changed: true };
+ } catch (err) {
+ return { ok: false, changed: false, message: errMessage(err) };
+ }
+}
+
+/**
+ * Set or clear the issue's milestone (PATCH /issues/{n}). `milestone` is the
+ * milestone number to assign, or `null` to remove it — GitHub accepts a literal
+ * `null` on this field to clear it, which is exactly what the picker's "No
+ * milestone" choice sends.
+ */
+export async function setMilestone(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ req: { number: number; milestone: number | null },
+): Promise {
+ try {
+ await client.requestBody("PATCH", `/repos/${enc(owner)}/${enc(repo)}/issues/${req.number}`, {
+ milestone: req.milestone,
+ });
+ return { ok: true, changed: true };
+ } catch (err) {
+ return { ok: false, changed: false, message: errMessage(err) };
+ }
+}
diff --git a/apps/desktop/src/main/github/notifications.ts b/apps/desktop/src/main/github/notifications.ts
new file mode 100644
index 0000000..2369497
--- /dev/null
+++ b/apps/desktop/src/main/github/notifications.ts
@@ -0,0 +1,130 @@
+// The Notifications section's GitHub logic (the user's inbox). Runs in the
+// Electron MAIN process. Unlike the repo-scoped sections (PRs / Issues /
+// Releases), the GitHub Activity/Notifications API is ACCOUNT-scoped — the
+// /notifications endpoints take no owner/repo — so these functions take only
+// the client (+ args). main.ts invokes them via `github.withClient(...)`.
+//
+// All three endpoints are REST-only (the Activity API has no GraphQL form). The
+// OAuth token already carries the `notifications` scope GET /notifications,
+// PATCH /notifications/threads/{id}, and PUT /notifications require, so no new
+// scope is needed; the existing `request`/`requestBody` primitives set Bearer.
+
+import { GitHubClient, enc } from "../githubClient";
+import type { NotificationActionResult, NotificationThread } from "../../shared/ipc";
+
+/** Options for the inbox listing (mirrors the IPC request shape). */
+export interface ListNotificationsOptions {
+ /** Include already-read threads (GET /notifications?all=true). */
+ all?: boolean;
+ /** Restrict to threads the user is directly participating in. */
+ participating?: boolean;
+}
+
+/**
+ * The user's notification inbox across every watched repo. A READ method, so it
+ * THROWS on auth / rate-limit / network failure — the renderer surfaces a real
+ * error state + Retry rather than a misleading "inbox zero". Capped at 50 (no
+ * "load more" in v1, matching the other list views).
+ */
+export async function listNotifications(
+ client: GitHubClient,
+ opts: ListNotificationsOptions = {},
+): Promise {
+ const qs = new URLSearchParams();
+ if (opts.all) qs.set("all", "true");
+ if (opts.participating) qs.set("participating", "true");
+ qs.set("per_page", "50");
+ const raw = await client.request("GET", `/notifications?${qs.toString()}`);
+ return raw.map(mapNotification);
+}
+
+/**
+ * Mark a single thread as read (GitHub also stops surfacing it as unread). A
+ * MUTATION, so it returns the `{ ok, message }` result shape and never throws —
+ * the renderer toasts. PATCH .../threads/{id} returns 205 with no body; the
+ * client's `requestBody` only checks `res.ok`, which 2xx satisfies.
+ */
+export async function markNotificationRead(
+ client: GitHubClient,
+ id: string,
+): Promise {
+ try {
+ await client.requestBody("PATCH", `/notifications/threads/${enc(id)}`, {});
+ return { ok: true };
+ } catch (err) {
+ return { ok: false, message: err instanceof Error ? err.message : String(err) };
+ }
+}
+
+/**
+ * Mark EVERY notification in the user's inbox as read. PUT /notifications
+ * returns 202 (accepted; processed async on GitHub's side), so a re-list right
+ * after may briefly still show threads — the next refresh reconciles.
+ */
+export async function markAllNotificationsRead(
+ client: GitHubClient,
+): Promise {
+ try {
+ await client.requestBody("PUT", "/notifications", { read: true });
+ return { ok: true };
+ } catch (err) {
+ return { ok: false, message: err instanceof Error ? err.message : String(err) };
+ }
+}
+
+// ── Raw API shapes + mappers ─────────────────────────────────────────────────
+
+interface RawNotificationOwner {
+ avatar_url?: string | null;
+}
+interface RawNotificationSubject {
+ title: string;
+ type: string;
+ url: string | null;
+ latest_comment_url: string | null;
+}
+interface RawNotificationRepository {
+ full_name: string;
+ html_url: string;
+ owner?: RawNotificationOwner | null;
+}
+interface RawNotification {
+ id: string;
+ unread: boolean;
+ reason: string;
+ updated_at: string;
+ subject: RawNotificationSubject;
+ repository: RawNotificationRepository;
+}
+
+function mapNotification(n: RawNotification): NotificationThread {
+ return {
+ id: n.id,
+ title: n.subject?.title ?? "(untitled)",
+ type: n.subject?.type ?? "",
+ reason: n.reason ?? "",
+ repo: n.repository?.full_name ?? "",
+ repoAvatarUrl: n.repository?.owner?.avatar_url ?? null,
+ updatedAt: n.updated_at ?? "",
+ unread: n.unread ?? false,
+ htmlUrl: subjectHtmlUrl(n),
+ };
+}
+
+/**
+ * GitHub's notification subject `url` is an API url
+ * (api.github.com/repos/o/r/pulls/123) with no `html_url`. Rewrite pulls/issues
+ * to a github.com web url; Releases / Commits / Discussions lack a clean
+ * numbered subject url, so fall back to the repository's html_url.
+ */
+function subjectHtmlUrl(n: RawNotification): string {
+ const api = n.subject?.url ?? "";
+ if (api) {
+ const m = api.match(/repos\/([^/]+)\/([^/]+)\/(pulls|issues)\/(\d+)/);
+ if (m) {
+ const kind = m[3] === "pulls" ? "pull" : "issues";
+ return `https://github.com/${m[1]}/${m[2]}/${kind}/${m[4]}`;
+ }
+ }
+ return n.repository?.html_url ?? "";
+}
diff --git a/apps/desktop/src/main/github/orgs.ts b/apps/desktop/src/main/github/orgs.ts
new file mode 100644
index 0000000..c4b85d5
--- /dev/null
+++ b/apps/desktop/src/main/github/orgs.ts
@@ -0,0 +1,123 @@
+// The Organizations section's GitHub logic (main process). Four pure, read-only
+// REST list calls — orgs the signed-in user belongs to, plus each org's repos,
+// teams, and members. These are USER-scoped (not repo-scoped), so the functions
+// take only the client; main.ts invokes them via `github.withClient((c) => …)`.
+//
+// All four THROW on API error (the client's request() throws a clean Error via
+// toError(): 401 → token invalid, 403 → permissions/rate-limit, 404 → not found),
+// so the renderer paints an errorState + Retry rather than a misleading empty
+// list. There are no mutations here, so the {ok,changed,message} result shape is
+// not used anywhere in this module.
+
+import { GitHubClient, enc } from "../githubClient";
+import type { OrgInfo, OrgMember, OrgRepo, OrgTeam } from "../../shared/ipc";
+
+// ── Raw GitHub shapes (only the fields we map) ────────────────────────────────
+
+/** `/user/orgs` returns the SHORT org object: no `html_url`/`name`, so we
+ * synthesize the profile URL from the login in the mapper. */
+interface RawOrg {
+ login: string;
+ name?: string | null;
+ avatar_url?: string;
+ description?: string | null;
+}
+interface RawRepo {
+ name: string;
+ full_name: string;
+ html_url: string;
+ description?: string | null;
+ private?: boolean;
+ fork?: boolean;
+ archived?: boolean;
+ language?: string | null;
+ stargazers_count?: number;
+ pushed_at?: string;
+}
+interface RawTeam {
+ name: string;
+ slug: string;
+ description?: string | null;
+ privacy?: string;
+ html_url?: string;
+}
+interface RawMember {
+ login: string;
+ avatar_url?: string;
+ html_url?: string;
+}
+
+// ── Raw → public mappers ──────────────────────────────────────────────────────
+
+function mapOrg(o: RawOrg): OrgInfo {
+ return {
+ login: o.login,
+ name: o.name ?? null,
+ avatarUrl: o.avatar_url ?? null,
+ description: o.description ?? null,
+ htmlUrl: `https://github.com/${o.login}`,
+ };
+}
+function mapRepo(r: RawRepo): OrgRepo {
+ return {
+ name: r.name,
+ fullName: r.full_name,
+ htmlUrl: r.html_url,
+ description: r.description ?? null,
+ private: r.private ?? false,
+ fork: r.fork ?? false,
+ archived: r.archived ?? false,
+ language: r.language ?? null,
+ stargazersCount: r.stargazers_count ?? 0,
+ pushedAt: r.pushed_at ?? "",
+ };
+}
+function mapTeam(t: RawTeam): OrgTeam {
+ return {
+ name: t.name,
+ slug: t.slug,
+ description: t.description ?? null,
+ privacy: t.privacy ?? "",
+ htmlUrl: t.html_url ?? "",
+ };
+}
+function mapMember(m: RawMember): OrgMember {
+ return {
+ login: m.login,
+ avatarUrl: m.avatar_url ?? null,
+ htmlUrl: m.html_url ?? `https://github.com/${m.login}`,
+ };
+}
+
+// ── Read functions (user-scoped; throw on error) ─────────────────────────────
+
+/** Orgs the signed-in user has visible membership in. Orgs that hide the user's
+ * membership won't appear — expected GitHub behavior. */
+export async function listOrgs(client: GitHubClient): Promise {
+ const raw = await client.request("GET", `/user/orgs?per_page=100`);
+ return raw.map(mapOrg);
+}
+
+/** An org's repositories, most-recently-pushed first. Private repos appear when
+ * the OAuth token also carries `repo`; needs no extra scope of its own. */
+export async function listOrgRepos(client: GitHubClient, org: string): Promise {
+ const raw = await client.request(
+ "GET",
+ `/orgs/${enc(org)}/repos?sort=pushed&direction=desc&per_page=100`,
+ );
+ return raw.map(mapRepo);
+}
+
+/** An org's teams. Requires `read:org` + org membership; non-members get a 403
+ * that surfaces as the renderer's errorState + Retry. */
+export async function listOrgTeams(client: GitHubClient, org: string): Promise {
+ const raw = await client.request("GET", `/orgs/${enc(org)}/teams?per_page=100`);
+ return raw.map(mapTeam);
+}
+
+/** An org's members, per the org's visibility. A non-owner may only see public
+ * members → can be empty even for large orgs; a restricted list yields a 403. */
+export async function listOrgMembers(client: GitHubClient, org: string): Promise {
+ const raw = await client.request("GET", `/orgs/${enc(org)}/members?per_page=100`);
+ return raw.map(mapMember);
+}
diff --git a/apps/desktop/src/main/github/projects.ts b/apps/desktop/src/main/github/projects.ts
new file mode 100644
index 0000000..86bdad0
--- /dev/null
+++ b/apps/desktop/src/main/github/projects.ts
@@ -0,0 +1,238 @@
+// Projects v2 (the GitHub "Projects" board) for the desktop app's GitHub section.
+//
+// Projects v2 has NO REST API — everything here goes through the client's
+// `graphql()` primitive, which already throws (via toError) on HTTP failure
+// AND on `json.errors[0].message`. So the READ functions carry NO local
+// try/catch: scope / rate-limit / network errors propagate to the renderer's
+// errorState (the throw-on-read convention). The MUTATIONS stay wrapped and
+// return a CommitActionResult-shaped object ({ ok, changed, message }).
+//
+// Repo-scoped reads take (client, owner, repo); the board read + the two
+// mutations act on opaque GraphQL node ids, so they take (client, …ids). main.ts
+// drives all of them through `github.withRepo((c, o, r) => …)`, which already
+// guards the not-connected / not-on-github.com cases before we are reached.
+
+import { GitHubClient } from "../githubClient";
+import type { CommitActionResult, ProjectBoard, ProjectInfo } from "../../shared/ipc";
+
+// ── Raw GraphQL shapes (this module owns its own Raw* interfaces + mappers) ────
+
+interface RawProjectsData {
+ repository?: {
+ projectsV2?: {
+ nodes?: ({
+ id: string;
+ number: number;
+ title: string;
+ shortDescription?: string | null;
+ url: string;
+ closed: boolean;
+ updatedAt?: string | null;
+ items?: { totalCount: number } | null;
+ } | null)[];
+ } | null;
+ } | null;
+}
+
+interface RawBoardField {
+ id: string;
+ name: string;
+ options?: ({ id: string; name: string; color?: string | null } | null)[] | null;
+}
+
+interface RawBoardContent {
+ __typename?: string;
+ number?: number | null;
+ title?: string | null;
+ url?: string | null;
+ state?: string | null;
+ author?: { login?: string | null } | null;
+}
+
+interface RawBoardItem {
+ id: string;
+ updatedAt?: string | null;
+ type?: string | null;
+ fieldValueByName?: { optionId?: string | null; name?: string | null } | null;
+ content?: RawBoardContent | null;
+}
+
+interface RawBoardData {
+ node?: {
+ field?: RawBoardField | null;
+ items?: { nodes?: (RawBoardItem | null)[] | null } | null;
+ } | null;
+}
+
+// ── Reads (THROW on error) ────────────────────────────────────────────────────
+
+/**
+ * The repo's GitHub Projects (v2), newest-updated first. Capped at the 20 most
+ * recently touched — the same magnitude as the PR/issue lists. Errors propagate.
+ */
+export async function listProjects(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+): Promise {
+ const data = await client.graphql(
+ `query($owner:String!,$repo:String!){
+ repository(owner:$owner,name:$repo){
+ projectsV2(first:20,orderBy:{field:UPDATED_AT,direction:DESC}){
+ nodes{ id number title shortDescription url closed updatedAt items{totalCount} }
+ }
+ }
+ }`,
+ { owner, repo },
+ );
+ const nodes = data?.repository?.projectsV2?.nodes ?? [];
+ return nodes
+ .filter((p): p is NonNullable => !!p)
+ .map((p) => ({
+ id: p.id,
+ number: p.number,
+ title: p.title,
+ shortDescription: p.shortDescription ?? "",
+ url: p.url,
+ itemCount: p.items?.totalCount ?? 0,
+ closed: p.closed,
+ updatedAt: p.updatedAt ?? "",
+ }));
+}
+
+/**
+ * A project's board: its "Status" single-select field (the columns) plus every
+ * item (cards) with its content + current Status value. Items are paged to the
+ * first 100, ordered by board POSITION so columns read top-to-bottom as they do
+ * on github.com. Errors propagate.
+ *
+ * The board read acts on an opaque ProjectV2 node id, so it ignores owner/repo —
+ * they're accepted to keep the (client, owner, repo, …args) shape main.ts wires
+ * through `github.withRepo`.
+ */
+export async function getProjectBoard(
+ client: GitHubClient,
+ _owner: string,
+ _repo: string,
+ projectId: string,
+): Promise {
+ const data = await client.graphql(
+ `query($id:ID!){
+ node(id:$id){
+ ... on ProjectV2 {
+ field(name:"Status"){
+ ... on ProjectV2SingleSelectField {
+ id name options{ id name color }
+ }
+ }
+ items(first:100,orderBy:{field:POSITION,direction:ASC}){
+ nodes{
+ id updatedAt type
+ fieldValueByName(name:"Status"){
+ ... on ProjectV2ItemFieldSingleSelectValue { optionId name }
+ }
+ content{
+ __typename
+ ... on Issue { number title url state author{login} }
+ ... on PullRequest { number title url state author{login} }
+ ... on DraftIssue { title }
+ }
+ }
+ }
+ }
+ }
+ }`,
+ { id: projectId },
+ );
+ const proj = data?.node;
+ const rawField = proj?.field;
+ const field: ProjectBoard["field"] = rawField
+ ? {
+ id: rawField.id,
+ name: rawField.name,
+ options: (rawField.options ?? [])
+ .filter((o): o is NonNullable => !!o)
+ .map((o) => ({ id: o.id, name: o.name, color: o.color ?? "" })),
+ }
+ : null;
+ const items = (proj?.items?.nodes ?? [])
+ .filter((n): n is RawBoardItem => !!n && !!n.content)
+ .map((n) => {
+ const c = n.content as RawBoardContent;
+ return {
+ id: n.id,
+ type: n.type ?? "",
+ title: c.title ?? "(untitled)",
+ number: typeof c.number === "number" ? c.number : null,
+ state: c.state ?? "",
+ url: c.url ?? null,
+ author: c.author?.login ?? "",
+ statusOptionId: n.fieldValueByName?.optionId ?? null,
+ statusName: n.fieldValueByName?.name ?? "",
+ updatedAt: n.updatedAt ?? "",
+ };
+ });
+ return { field, items };
+}
+
+// ── Mutations (return { ok, changed, message }) ───────────────────────────────
+
+/**
+ * Move an item to a Status option, or clear its Status when `optionId` is null.
+ * Clearing uses a different mutation (clearProjectV2ItemFieldValue) than setting
+ * (updateProjectV2ItemFieldValue). Needs the WRITE `project` scope; without it
+ * GitHub returns a 403 whose message we surface verbatim (no crash).
+ */
+export async function moveProjectItem(
+ client: GitHubClient,
+ _owner: string,
+ _repo: string,
+ req: { projectId: string; itemId: string; fieldId: string; optionId: string | null },
+): Promise {
+ try {
+ if (req.optionId === null) {
+ await client.graphql<{ clearProjectV2ItemFieldValue?: { clientMutationId?: string | null } }>(
+ `mutation($p:ID!,$i:ID!,$f:ID!){
+ clearProjectV2ItemFieldValue(input:{projectId:$p,itemId:$i,fieldId:$f}){ clientMutationId }
+ }`,
+ { p: req.projectId, i: req.itemId, f: req.fieldId },
+ );
+ } else {
+ await client.graphql<{ updateProjectV2ItemFieldValue?: { projectV2Item?: { id: string } | null } }>(
+ `mutation($p:ID!,$i:ID!,$f:ID!,$o:String!){
+ updateProjectV2ItemFieldValue(input:{
+ projectId:$p,itemId:$i,fieldId:$f,value:{singleSelectOptionId:$o}
+ }){ projectV2Item{ id } }
+ }`,
+ { p: req.projectId, i: req.itemId, f: req.fieldId, o: req.optionId },
+ );
+ }
+ return { ok: true, changed: true };
+ } catch (err) {
+ return { ok: false, changed: false, message: err instanceof Error ? err.message : String(err) };
+ }
+}
+
+/**
+ * Add an existing issue/PR (by its content node id) to a project. v1.1 scaffold:
+ * fully wired end to end so a future "Add item" affordance only needs a content
+ * id. Needs the WRITE `project` scope.
+ */
+export async function addProjectItem(
+ client: GitHubClient,
+ _owner: string,
+ _repo: string,
+ req: { projectId: string; contentId: string },
+): Promise {
+ try {
+ await client.graphql<{ addProjectV2ItemById?: { item?: { id: string } | null } }>(
+ `mutation($p:ID!,$c:ID!){
+ addProjectV2ItemById(input:{projectId:$p,contentId:$c}){ item{ id } }
+ }`,
+ { p: req.projectId, c: req.contentId },
+ );
+ return { ok: true, changed: true };
+ } catch (err) {
+ return { ok: false, changed: false, message: err instanceof Error ? err.message : String(err) };
+ }
+}
diff --git a/apps/desktop/src/main/github/prs.ts b/apps/desktop/src/main/github/prs.ts
new file mode 100644
index 0000000..d39a700
--- /dev/null
+++ b/apps/desktop/src/main/github/prs.ts
@@ -0,0 +1,651 @@
+// GitHub pull-request write actions + the Create-PR support reads.
+//
+// These standalone functions are the section's GitHub logic. They are invoked
+// from main.ts through the bridge's `withRepo` helper, which supplies an
+// authenticated `GitHubClient` plus the resolved owner/repo. Following the
+// section convention:
+// • READ helpers (branches / reviewers) THROW on a real API error so the
+// renderer can surface an errorState; they only degrade to a benign empty
+// result for the "no collaborator access" sub-case, where a free-text
+// fallback is the right UX.
+// • MUTATIONS never throw: they return a CommitActionResult-shaped object
+// ({ ok, changed, message }). `changed` is ALWAYS false here — none of these
+// PR API writes touch the local working tree (unlike pr:checkout), so the
+// graph/sync widgets must NOT refresh off them.
+//
+// We reuse the client's PUBLIC primitives (request / requestBody / graphql) and
+// the shared `enc` / `mapUser` helpers; the Raw* shapes + mappers we need that
+// the client keeps private (RawPull/mapPull) are redefined locally so this
+// module is self-contained.
+
+import { GitHubClient, enc, mapUser, RawUser } from "../githubClient";
+import type {
+ BranchRef,
+ CommitActionResult,
+ CreatePrRequest,
+ FileDiff,
+ PrPrefill,
+ PrReviewComment,
+ PrReviewRequest,
+ PrReviewThread,
+ PullRequest,
+ RepoCollaborator,
+ RepoLabel,
+} from "../../shared/ipc";
+
+// ── Raw API shapes (snake_case, GitHub REST) ──────────────────────────────────
+
+interface RawRef {
+ ref: string;
+ sha: string;
+}
+interface RawPull {
+ number: number;
+ title: string;
+ body: string | null;
+ state: string;
+ draft?: boolean;
+ html_url: string;
+ user: RawUser | null;
+ created_at: string;
+ updated_at: string;
+ head: RawRef;
+ base: RawRef;
+ labels?: { name: string; color: string }[];
+ comments?: number;
+ additions?: number;
+ deletions?: number;
+ changed_files?: number;
+}
+interface RawBranch {
+ name: string;
+}
+interface RawRepoMeta {
+ default_branch?: string;
+}
+interface RawLabel {
+ name: string;
+ color: string;
+ description: string | null;
+}
+/** The base64 file-contents payload from GET /contents/{path}. */
+interface RawContents {
+ content?: string;
+ encoding?: string;
+ /** Bytes; present for blobs. GitHub stops inlining content for very large files. */
+ size?: number;
+}
+
+function mapPull(p: RawPull): PullRequest {
+ return {
+ number: p.number,
+ title: p.title,
+ body: p.body,
+ state: p.state,
+ draft: p.draft ?? false,
+ htmlUrl: p.html_url,
+ user: mapUser(p.user),
+ createdAt: p.created_at,
+ updatedAt: p.updated_at,
+ head: { ref: p.head.ref, sha: p.head.sha },
+ base: { ref: p.base.ref, sha: p.base.sha },
+ labels: (p.labels ?? []).map((l) => ({ name: l.name, color: l.color })),
+ comments: p.comments,
+ additions: p.additions,
+ deletions: p.deletions,
+ changedFiles: p.changed_files,
+ };
+}
+
+function errMessage(err: unknown): string {
+ return err instanceof Error ? err.message : String(err);
+}
+
+/** Resolve a PR's base + head commit SHAs (anchors for diffs + review comments). */
+async function prRefs(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ n: number,
+): Promise<{ baseSha: string; headSha: string }> {
+ const p = await client.request("GET", `/repos/${enc(owner)}/${enc(repo)}/pulls/${n}`);
+ return { baseSha: p.base.sha, headSha: p.head.sha };
+}
+
+/**
+ * The text of a file at a given ref via the Contents API, or "" when the path
+ * doesn't exist on that side (404 = added/removed) or can't be read as text.
+ *
+ * • 404 → "" (the file was added on head / deleted on base — that side is empty).
+ * • Over GitHub's ~1MB inline cap (no `content` returned) → a short placeholder
+ * so the diff degrades gracefully instead of throwing.
+ * • A real network / auth error still throws (the caller is a READ → surfaces an
+ * errorState).
+ */
+async function fileTextAt(
+ client: GitHubClient,
+ owner: string,
+ repo: string,
+ path: string,
+ ref: string,
+): Promise