@1agh/maude 0.29.0 → 0.31.0

package/apps/studio/git/watch.ts

@@ -0,0 +1,97 @@
+// Phase 27 (epic E2) Task 5 — live dirty-state.
+//
+// Event-driven, NOT polled: piggyback on the existing fs-watch bus (`fs:any`,
+// already debounced 50 ms per-path and already filtered to drop `_server.json` /
+// `_active.json` / `_sync.json` / `_history/`). On a versionable change we
+// recompute `gitStatus` once (trailing-debounced ~300 ms, since git status is
+// heavier than a CSS reload) and emit a `git-status` bus event. ws.ts forwards it
+// to the inspector clients (the shell), which update the Changes-panel count
+// badge + the per-row M/A/D tree badges reactively. No client polling, no extra
+// fs.watch — one recompute per burst of saves.
+
+import type { Context } from '../context.ts';
+import { type GitStatusResult, gitStatus } from './service.ts';
+
+export interface GitWatch {
+  /** Force a recompute + broadcast now (e.g. right after a commit lands). */
+  refresh(): void;
+  stop(): void;
+}
+
+const DEBOUNCE_MS = 300;
+
+/** Recompute git-status only for changes to versionable design content — the
+ *  plan's explicit allowlist (.tsx / .css / .meta.json / annotation SVG / comment
+ *  + annotation dirs). Skips the noise fs-watch lets through (e.g. an `.html`
+ *  fixture or a stray editor temp) so we don't fork git for a non-tracked save.
+ *  `gitStatus` itself still drops Maude runtime state, so this is just an
+ *  optimization, not a correctness gate. */
+function isVersionable(rel: string): boolean {
+  const p = rel.replace(/\\/g, '/');
+  if (p.includes('/_comments/') || p.startsWith('_comments/')) return true;
+  if (p.includes('/_annotations/') || p.startsWith('_annotations/')) return true;
+  return /\.(tsx|css|meta\.json|svg)$/.test(p) || p.endsWith('.annotations.svg');
+}
+
+export function createGitWatch(ctx: Context): GitWatch {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let running = false;
+  let pending = false;
+  let stopped = false;
+
+  async function recompute() {
+    if (stopped) return;
+    if (running) {
+      // A change landed mid-flight — run once more when the current pass finishes
+      // so the final state always reflects the last save.
+      pending = true;
+      return;
+    }
+    running = true;
+    try {
+      const status: GitStatusResult = await gitStatus(ctx.paths.repoRoot, {
+        designPrefix: ctx.paths.designRel,
+      });
+      if (!stopped) ctx.bus.emit('git-status', status);
+    } catch (err) {
+      console.warn('[git-watch] status failed:', err instanceof Error ? err.message : err);
+    } finally {
+      running = false;
+      if (pending && !stopped) {
+        pending = false;
+        schedule();
+      }
+    }
+  }
+
+  function schedule() {
+    if (stopped) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void recompute();
+    }, DEBOUNCE_MS);
+  }
+
+  const unsub = ctx.bus.on('fs:any', (rel: string) => {
+    if (typeof rel === 'string' && isVersionable(rel)) schedule();
+  });
+
+  return {
+    refresh() {
+      // Immediate (still single-flight guarded) — used right after a commit so the
+      // panel clears without waiting for the next file save.
+      void recompute();
+    },
+    stop() {
+      stopped = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      unsub();
+    },
+  };
+}
+
+export const __testing = { isVersionable, DEBOUNCE_MS };

package/apps/studio/github/endpoints.ts

@@ -0,0 +1,358 @@
+// github/endpoints.ts — `/_api/github/*` orchestration (Phase 28 / epic E3).
+//
+// Pure-ish handlers behind the GitHub routes: validate inputs, resolve the token
+// from the loopback bridge (token.ts), call the service, and shape a
+// `{ status, json }` result. NO HTTP/Request dependency — http.ts owns the gating
+// (method · main-origin CSRF · loopback Host) and this module owns orchestration,
+// mirroring git/endpoints.ts.
+//
+// SECURITY: every route is main-origin-only by omission from CANVAS_SAFE_API +
+// startCanvasServer's `routes` map (the dual-allowlist rule). The token is fetched
+// per-request from the keychain bridge, used once for the GitHub call, and never
+// logged, echoed, or returned to the client. Inputs (repo name, username) are
+// validated at this boundary before they reach the GitHub API.
+
+import fs, { existsSync, mkdirSync, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+
+import git from 'isomorphic-git';
+import type { Context } from '../context.ts';
+import { gitClone } from '../git/service.ts';
+import { hasDesign, scaffoldDesign } from '../scaffold-design.ts';
+import {
+  createRepo,
+  GitHubApiError,
+  getIdentity,
+  inviteCollaborator,
+  listUserRepos,
+  setRemote,
+} from './service.ts';
+import { getGithubToken } from './token.ts';
+
+// A repo/folder NAME safe to join onto a user-chosen parent dir — alphanumeric
+// start, then [A-Za-z0-9._-], no separators or leading dot ⇒ no traversal.
+const SAFE_DIR_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+
+export interface GitHubEndpointResult {
+  status: number;
+  json: unknown;
+}
+
+// A GitHub username: 1–39 chars, alphanumeric or single hyphens, no leading/
+// trailing/consecutive hyphen. Anchored — never reaches the API path unvalidated.
+const USERNAME_RE = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/;
+
+/** Turn a human project name into a valid GitHub repo slug, or null if nothing
+ *  usable survives. GitHub repo names allow [A-Za-z0-9._-]; we lowercase, map
+ *  spaces/invalid runs to single hyphens, trim hyphens, and cap at 100. */
+export function slugifyRepoName(raw: unknown): string | null {
+  if (typeof raw !== 'string') return null;
+  const slug = raw
+    .normalize('NFKD')
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[-.]+|[-.]+$/g, '')
+    .slice(0, 100)
+    .toLowerCase();
+  return slug.length > 0 ? slug : null;
+}
+
+/** Parse `owner/repo` out of a GitHub remote URL (https or ssh form).
+ *
+ *  SECURITY (phase-28 audit D-1/F-2, HIGH): the host MUST be anchored to exactly
+ *  `github.com`. The original `url.match(/github\.com[:/]+…/)` matched the substring
+ *  ANYWHERE, so `https://evil.com/github.com/o/r.git` parsed as owner=`o` repo=`r`
+ *  and the raw URL then flowed to `git.clone`'s host-agnostic `onAuth` → the keychain
+ *  PAT was offered as Basic auth to the attacker host (token exfiltration). We parse
+ *  the https form with the WHATWG URL parser and assert `hostname === 'github.com'`;
+ *  callers MUST clone from the canonical URL rebuilt from the returned owner/repo,
+ *  never the raw input. */
+export function parseGitHubRemote(url: string): { owner: string; repo: string } | null {
+  const trimmed = String(url).trim();
+  let owner: string | undefined;
+  let repo: string | undefined;
+  // ssh form: git@github.com:owner/repo(.git) — host is literal here.
+  const ssh = trimmed.match(/^git@github\.com:([^/]+)\/(.+?)(?:\.git)?\/?$/i);
+  if (ssh) {
+    owner = ssh[1];
+    repo = ssh[2];
+  } else {
+    let u: URL;
+    try {
+      u = new URL(trimmed);
+    } catch {
+      return null;
+    }
+    if (u.protocol !== 'https:') return null; // no http downgrade, no ssh:// smuggling
+    if (u.hostname.toLowerCase() !== 'github.com') return null; // ANCHORED host
+    const parts = u.pathname.replace(/^\/+/, '').split('/');
+    if (parts.length < 2) return null;
+    owner = parts[0];
+    repo = parts[1].replace(/\.git$/i, '');
+  }
+  if (!owner || !repo) return null;
+  if (!USERNAME_RE.test(owner) || !/^[A-Za-z0-9._-]+$/.test(repo)) return null;
+  return { owner, repo };
+}
+
+/** Canonical HTTPS clone URL for a validated owner/repo — the ONLY URL a caller
+ *  should hand to git.clone (never raw user input; see parseGitHubRemote security). */
+export function canonicalGitHubCloneUrl(owner: string, repo: string): string {
+  return `https://github.com/${owner}/${repo}.git`;
+}
+
+export interface GitHubEndpoints {
+  identity(): Promise<GitHubEndpointResult>;
+  repos(): Promise<GitHubEndpointResult>;
+  createRepo(body: unknown): Promise<GitHubEndpointResult>;
+  createProject(body: unknown): Promise<GitHubEndpointResult>;
+  invite(body: unknown): Promise<GitHubEndpointResult>;
+  clone(body: unknown): Promise<GitHubEndpointResult>;
+  initDesign(body: unknown): Promise<GitHubEndpointResult>;
+}
+
+/** Validate a user-chosen parent dir (from the native folder picker). */
+function validParentDir(v: unknown): v is string {
+  return typeof v === 'string' && isAbsolute(v) && existsSync(v) && statSync(v).isDirectory();
+}
+
+export function createGitHubEndpoints(ctx: Context): GitHubEndpoints {
+  const repoDir = ctx.paths.repoRoot;
+
+  function bad(error: string): GitHubEndpointResult {
+    return { status: 400, json: { ok: false, error } };
+  }
+
+  /** Resolve the token, run `fn`, and map any GitHubApiError to a JSON result. */
+  async function withToken(
+    fn: (token: string) => Promise<GitHubEndpointResult>
+  ): Promise<GitHubEndpointResult> {
+    const token = await getGithubToken();
+    if (!token) {
+      return {
+        status: 401,
+        json: { ok: false, signedIn: false, error: 'Sign in with GitHub in the Maude app first.' },
+      };
+    }
+    try {
+      return await fn(token);
+    } catch (e) {
+      if (e instanceof GitHubApiError) {
+        // status 0 = network → 502; otherwise pass GitHub's status through.
+        return { status: e.status === 0 ? 502 : e.status, json: { ok: false, error: e.message } };
+      }
+      return { status: 502, json: { ok: false, error: 'GitHub request failed. Try again.' } };
+    }
+  }
+
+  async function identity(): Promise<GitHubEndpointResult> {
+    return withToken(async (token) => ({
+      status: 200,
+      json: { ok: true, ...(await getIdentity(token)) },
+    }));
+  }
+
+  async function repos(): Promise<GitHubEndpointResult> {
+    return withToken(async (token) => ({
+      status: 200,
+      json: { ok: true, repos: await listUserRepos(token) },
+    }));
+  }
+
+  async function createRepoHandler(body: unknown): Promise<GitHubEndpointResult> {
+    const b = (body ?? {}) as { name?: unknown; private?: unknown; description?: unknown };
+    const name = slugifyRepoName(b.name);
+    if (!name) return bad('Enter a project name (letters, numbers, hyphens).');
+    if (b.private != null && typeof b.private !== 'boolean') return bad('Invalid visibility.');
+    const isPrivate = b.private !== false; // default PRIVATE for non-technical safety
+    let description: string | undefined;
+    if (b.description != null) {
+      if (typeof b.description !== 'string' || b.description.length > 350)
+        return bad('Description is too long.');
+      description = b.description;
+    }
+    return withToken(async (token) => {
+      const repo = await createRepo(token, { name, private: isPrivate, description });
+      // Point the local project's origin at the new repo so the next Publish pushes
+      // to it. iso-git, no network. Failure here is non-fatal to repo creation.
+      let remoteSet = true;
+      try {
+        await setRemote(repoDir, repo.clone_url);
+      } catch {
+        remoteSet = false;
+      }
+      return { status: 200, json: { ok: true, repo, remoteSet } };
+    });
+  }
+
+  async function invite(body: unknown): Promise<GitHubEndpointResult> {
+    const b = (body ?? {}) as { username?: unknown };
+    if (typeof b.username !== 'string') return bad('Enter a GitHub username.');
+    const username = b.username.trim().replace(/^@/, '');
+    if (!USERNAME_RE.test(username)) return bad('That doesn’t look like a GitHub username.');
+
+    // owner/repo come from the CURRENT project's origin remote — the client never
+    // supplies them, so you can only ever invite to the project you have open.
+    const remotes = await git.listRemotes({ fs, dir: repoDir }).catch(() => []);
+    const origin = remotes.find((r) => r.remote === 'origin');
+    if (!origin) {
+      return {
+        status: 409,
+        json: {
+          ok: false,
+          error: 'This project isn’t on GitHub yet — create or open it on GitHub first.',
+        },
+      };
+    }
+    const parsed = parseGitHubRemote(origin.url);
+    if (!parsed)
+      return { status: 409, json: { ok: false, error: 'This project isn’t a GitHub project.' } };
+
+    return withToken(async (token) => {
+      const res = await inviteCollaborator(token, parsed.owner, parsed.repo, username);
+      return { status: 200, json: { ok: true, invited: res.invited, username } };
+    });
+  }
+
+  // "Pull a local copy": clone a GitHub project into a user-chosen folder. The
+  // parentDir comes from the NATIVE folder picker (a Tauri command), and every
+  // input is validated before it reaches the filesystem / iso-git.
+  async function clone(body: unknown): Promise<GitHubEndpointResult> {
+    const b = (body ?? {}) as { cloneUrl?: unknown; parentDir?: unknown; name?: unknown };
+    const parsed = typeof b.cloneUrl === 'string' ? parseGitHubRemote(b.cloneUrl) : null;
+    if (!parsed) {
+      return bad('That isn’t a GitHub project link.');
+    }
+    // SECURITY (audit D-1/F-2): clone from the CANONICAL github.com URL rebuilt from
+    // the validated owner/repo — NEVER the raw user string. Even if a crafted link
+    // slipped past the parser, the token can only ever be offered to github.com.
+    const cloneUrl = canonicalGitHubCloneUrl(parsed.owner, parsed.repo);
+    if (typeof b.name !== 'string' || !SAFE_DIR_NAME.test(b.name))
+      return bad('Invalid project name.');
+    if (
+      typeof b.parentDir !== 'string' ||
+      !isAbsolute(b.parentDir) ||
+      !existsSync(b.parentDir) ||
+      !statSync(b.parentDir).isDirectory()
+    ) {
+      return bad('Pick a folder on your computer to save the project in.');
+    }
+    const target = join(b.parentDir, b.name);
+    if (existsSync(target)) {
+      return {
+        status: 409,
+        json: { ok: false, error: `A folder named “${b.name}” already exists there.` },
+      };
+    }
+    // Token OPTIONAL — public repos clone tokenless; private repos surface
+    // authRequired from the service if no token is available.
+    const token = (await getGithubToken()) ?? undefined;
+    const res = await gitClone(cloneUrl, target, token);
+    if (res.ok) {
+      // Tell the client whether the pulled repo is actually a Maude project. If not,
+      // the client must NOT switch to it (the dev-server can't serve a project with
+      // no .design/ — it fails loud) — it shows a "set it up" message instead.
+      return { status: 200, json: { ok: true, path: target, hasDesign: hasDesign(target) } };
+    }
+    if (res.authRequired) {
+      return { status: 401, json: { ok: false, authRequired: true, error: res.error } };
+    }
+    return {
+      status: 502,
+      json: { ok: false, error: res.error ?? 'Could not download the project.' },
+    };
+  }
+
+  // "New project" — create a GitHub repo AND a ready-to-design local project:
+  // create repo → make <parentDir>/<slug> → git init → scaffold a bootable .design/
+  // → point origin at the repo. No push here — the user Publishes (pushes) when
+  // ready, exactly like every other change. Returns the path to open.
+  async function createProject(body: unknown): Promise<GitHubEndpointResult> {
+    const b = (body ?? {}) as {
+      name?: unknown;
+      private?: unknown;
+      description?: unknown;
+      parentDir?: unknown;
+    };
+    const slug = slugifyRepoName(b.name);
+    if (!slug) return bad('Enter a project name (letters, numbers, hyphens).');
+    if (b.private != null && typeof b.private !== 'boolean') return bad('Invalid visibility.');
+    if (!validParentDir(b.parentDir))
+      return bad('Pick a folder on your computer to save the project in.');
+    let description: string | undefined;
+    if (b.description != null) {
+      if (typeof b.description !== 'string' || b.description.length > 350)
+        return bad('Description is too long.');
+      description = b.description;
+    }
+    const target = join(b.parentDir, slug);
+    if (existsSync(target)) {
+      return {
+        status: 409,
+        json: { ok: false, error: `A folder named “${slug}” already exists there.` },
+      };
+    }
+    const humanName = typeof b.name === 'string' ? b.name.trim() : slug;
+    return withToken(async (token) => {
+      const repo = await createRepo(token, {
+        name: slug,
+        private: b.private !== false,
+        description,
+      });
+      try {
+        mkdirSync(target, { recursive: true });
+        await git.init({ fs, dir: target, defaultBranch: 'main' });
+        const s = scaffoldDesign(target, humanName);
+        if (!s.ok)
+          return {
+            status: 500,
+            json: { ok: false, error: s.error ?? 'Could not set up the project.' },
+          };
+        await setRemote(target, repo.clone_url);
+      } catch (e) {
+        return {
+          status: 500,
+          json: {
+            ok: false,
+            error: e instanceof Error ? e.message : 'Could not set up the project.',
+          },
+        };
+      }
+      return { status: 200, json: { ok: true, path: target, repo } };
+    });
+  }
+
+  // Fallback for "open a folder/repo that isn't a Maude project yet" — scaffold a
+  // bootable .design/ into an existing folder so it can open (no GitHub, no token).
+  async function initDesign(body: unknown): Promise<GitHubEndpointResult> {
+    const b = (body ?? {}) as { dir?: unknown };
+    if (!validParentDir(b.dir)) return bad('That folder doesn’t exist.');
+    if (hasDesign(b.dir as string)) {
+      return { status: 200, json: { ok: true, alreadyDesign: true } };
+    }
+    const s = scaffoldDesign(b.dir as string);
+    if (!s.ok)
+      return {
+        status: 500,
+        json: { ok: false, error: s.error ?? 'Could not set up the project.' },
+      };
+    return { status: 200, json: { ok: true } };
+  }
+
+  return {
+    identity,
+    repos,
+    createRepo: createRepoHandler,
+    createProject,
+    invite,
+    clone,
+    initDesign,
+  };
+}
+
+export const __testing = {
+  slugifyRepoName,
+  parseGitHubRemote,
+  canonicalGitHubCloneUrl,
+  USERNAME_RE,
+};

package/apps/studio/github/service.ts

@@ -0,0 +1,231 @@
+// github/service.ts — the GitHub REST + git-remote operations behind /_api/github/*
+// (Phase 28 / epic E3 / DDR-108).
+//
+// DELIBERATE DEVIATION from the plan's "@octokit/rest": these are four simple REST
+// calls (identity · create-repo · invite · list-repos) plus one local iso-git
+// remote write. A hand-rolled `fetch` client keeps the bun --compile sidecar lean
+// (no large mixed-module dep to bundle), gives full control over the non-technical
+// error copy, and reuses the isomorphic-git engine already shipped in phase-27 for
+// `setRemote`. Recorded in DDR-114. Bun provides global `fetch` + AbortSignal.
+//
+// SECURITY: the token is passed in (resolved by the endpoint layer from the
+// loopback bridge — token.ts), used only as the `Authorization: Bearer` header /
+// the iso-git `onAuth` username, and never logged or echoed. GitHub error bodies
+// are mapped to friendly messages so raw API noise never reaches the UI.
+
+import fs from 'node:fs';
+
+import git from 'isomorphic-git';
+
+const API = 'https://api.github.com';
+const UA = 'maude-desktop';
+const API_VERSION = '2022-11-28';
+
+export interface GitHubIdentity {
+  login: string;
+  name: string | null;
+  avatar_url: string;
+}
+
+export interface CreatedRepo {
+  full_name: string;
+  clone_url: string;
+  html_url: string;
+  default_branch: string;
+  owner: string;
+}
+
+export interface RepoSummary {
+  name: string;
+  full_name: string;
+  owner: string;
+  private: boolean;
+  html_url: string;
+  clone_url: string;
+  updated_at: string;
+}
+
+export interface InviteResult {
+  /** true = a brand-new invitation was created; false = already had access. */
+  invited: boolean;
+}
+
+/** A GitHub API failure carrying a status + a message safe to show a non-technical user. */
+export class GitHubApiError extends Error {
+  status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = 'GitHubApiError';
+    this.status = status;
+  }
+}
+
+/** Map a failed GitHub response to a friendly, non-technical message. */
+function friendly(status: number, gh: { message?: string } | null, fallback: string): string {
+  if (status === 401) return 'Your GitHub sign-in expired. Sign in again to continue.';
+  if (status === 403) {
+    const m = gh?.message ?? '';
+    if (/rate limit/i.test(m))
+      return 'GitHub is rate-limiting requests. Try again in a few minutes.';
+    return "GitHub didn't allow that — you may not have permission.";
+  }
+  if (status === 404) return "GitHub couldn't find that — it may be private or renamed.";
+  return fallback;
+}
+
+interface ApiOpts {
+  method?: string;
+  body?: unknown;
+  /** Status codes (besides 2xx) to treat as success and return the response for. */
+  okStatuses?: number[];
+}
+
+async function api(token: string, path: string, opts: ApiOpts = {}): Promise<Response> {
+  const { method = 'GET', body, okStatuses = [] } = opts;
+  let res: Response;
+  try {
+    res = await fetch(`${API}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': API_VERSION,
+        'User-Agent': UA,
+        ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+      },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(20_000),
+    });
+  } catch {
+    throw new GitHubApiError(
+      0,
+      'Could not reach GitHub. Check your internet connection and try again.'
+    );
+  }
+  if (res.ok || okStatuses.includes(res.status)) return res;
+
+  let gh: { message?: string } | null = null;
+  try {
+    gh = (await res.clone().json()) as { message?: string };
+  } catch {
+    gh = null;
+  }
+  throw new GitHubApiError(
+    res.status,
+    friendly(res.status, gh, 'GitHub request failed. Try again.')
+  );
+}
+
+/** The signed-in user's public profile (login + name + avatar). */
+export async function getIdentity(token: string): Promise<GitHubIdentity> {
+  const res = await api(token, '/user');
+  const u = (await res.json()) as { login: string; name: string | null; avatar_url: string };
+  return { login: u.login, name: u.name ?? null, avatar_url: u.avatar_url };
+}
+
+export interface CreateRepoInput {
+  name: string;
+  private: boolean;
+  description?: string;
+  /** Seed an initial commit (README) so the new repo is immediately clonable. */
+  autoInit?: boolean;
+}
+
+/** Create a repo under the authenticated user. */
+export async function createRepo(token: string, input: CreateRepoInput): Promise<CreatedRepo> {
+  const res = await api(token, '/user/repos', {
+    method: 'POST',
+    body: {
+      name: input.name,
+      private: input.private,
+      description: input.description ?? '',
+      auto_init: input.autoInit ?? false,
+    },
+  }).catch((e: unknown) => {
+    // 422 = name already taken / invalid — give the precise non-technical reason.
+    if (e instanceof GitHubApiError && e.status === 422) {
+      throw new GitHubApiError(422, 'You already have a project with that name — pick another.');
+    }
+    throw e;
+  });
+  const r = (await res.json()) as {
+    full_name: string;
+    clone_url: string;
+    html_url: string;
+    default_branch: string;
+    owner: { login: string };
+  };
+  return {
+    full_name: r.full_name,
+    clone_url: r.clone_url,
+    html_url: r.html_url,
+    default_branch: r.default_branch,
+    owner: r.owner.login,
+  };
+}
+
+/**
+ * Point the local project's `origin` at `remoteUrl` (iso-git, no network). Replaces
+ * any existing remote of the same name so re-running "create project" is idempotent.
+ */
+export async function setRemote(
+  repoDir: string,
+  remoteUrl: string,
+  remote = 'origin'
+): Promise<void> {
+  await git.deleteRemote({ fs, dir: repoDir, remote }).catch(() => {
+    /* no existing remote — fine */
+  });
+  await git.addRemote({ fs, dir: repoDir, remote, url: remoteUrl });
+}
+
+/** Invite a collaborator by GitHub username (default: push/can-edit access). */
+export async function inviteCollaborator(
+  token: string,
+  owner: string,
+  repo: string,
+  username: string,
+  permission: 'pull' | 'push' | 'admin' = 'push'
+): Promise<InviteResult> {
+  const res = await api(
+    token,
+    `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/collaborators/${encodeURIComponent(username)}`,
+    { method: 'PUT', body: { permission }, okStatuses: [204] }
+  ).catch((e: unknown) => {
+    if (e instanceof GitHubApiError && e.status === 404) {
+      throw new GitHubApiError(404, `No GitHub user named "${username}". Check the spelling.`);
+    }
+    if (e instanceof GitHubApiError && e.status === 422) {
+      throw new GitHubApiError(422, `Couldn't invite "${username}" — they may already be invited.`);
+    }
+    throw e;
+  });
+  // 201 = invitation created; 204 = already a collaborator (no new invite).
+  return { invited: res.status === 201 };
+}
+
+/** Repos the user owns or collaborates on, most-recently-updated first. */
+export async function listUserRepos(token: string): Promise<RepoSummary[]> {
+  const res = await api(
+    token,
+    '/user/repos?per_page=100&sort=updated&affiliation=owner,collaborator'
+  );
+  const repos = (await res.json()) as Array<{
+    name: string;
+    full_name: string;
+    owner: { login: string };
+    private: boolean;
+    html_url: string;
+    clone_url: string;
+    updated_at: string;
+  }>;
+  return repos.map((r) => ({
+    name: r.name,
+    full_name: r.full_name,
+    owner: r.owner.login,
+    private: r.private,
+    html_url: r.html_url,
+    clone_url: r.clone_url,
+    updated_at: r.updated_at,
+  }));
+}