Merge remote-tracking branch 'origin/main' into feat/pro-174-version-command

# Conflicts:
#	docs/product/command-spec.md

Author: luanvdw

docs/product/command-principles.md

@@ -36,8 +36,9 @@ The long-term command surface grows through workflow groups such as:
 - `database`
 - `migrate`
 - `app`
+- `git`
 
-The preview implements only `auth`, `project`, `branch`, and `app`.
+The preview implements only `auth`, `project`, `git`, `branch`, and `app`.
 
 ## Stable Nouns
 

docs/product/command-spec.md

@@ -11,6 +11,7 @@ The preview package includes these command groups:
 
 - `auth`
 - `project` (includes `project env` subgroup)
+- `git`
 - `branch`
 - `app`
 
@@ -20,6 +21,9 @@ The preview package also includes one top-level utility command:
 
 `version` is intentionally outside the workflow groups: it reports CLI build and environment state, requires no auth, no project context, and no network, and is the canonical answer to "is this CLI installed and on the build I expect?"
 
+The Git repository connection slice uses the `git` group. It does not add a
+provider-specific `GitHub` group.
+
 Out of scope for the current preview:
 
 - `init`
@@ -173,7 +177,7 @@ Rules:
 - `cli.version` is the published package version.
 - `node.version` mirrors `process.version` exactly, including the leading `v`.
 - `os.platform` and `os.arch` mirror `process.platform` and `process.arch`.
-- `invocation` is best-effort and may be `null` when no signal is conclusive.
+- `invocation` is best-effort and falls back to `"unknown"` when no signal is conclusive.
 
 Examples:
 
@@ -308,6 +312,76 @@ prisma-cli project show --json
 prisma-cli project show --project proj_123 --json
 ```
 
+## `prisma-cli git connect [git-url]`
+
+Purpose:
+
+- connect the resolved Prisma project to a GitHub repository
+
+Behavior:
+
+- requires auth
+- resolves project context without creating projects
+- supports `--project <id-or-name>` for explicit project selection
+- if `[git-url]` is provided, parses it as a GitHub repository URL
+- if `[git-url]` is omitted, reads the local Git `origin` remote URL
+- accepts common GitHub URL forms such as:
+  - `https://github.com/prisma/prisma-cli`
+  - `https://github.com/prisma/prisma-cli.git`
+  - `git@github.com:prisma/prisma-cli.git`
+- rejects unsupported providers with `REPO_PROVIDER_UNSUPPORTED`
+- stores the repository connection server-side through the Management API
+- does not write repository data to `prisma.config.ts`
+- does not create branches synchronously
+- when the connection is active, enables platform webhook automation to map GitHub branch activity to Prisma Branch state
+
+Current backend contract:
+
+- the CLI lists GitHub App installations for the authenticated workspace through the Management API
+- if no installation exists, the CLI creates a GitHub App install intent and returns the install URL
+- in interactive mode, the CLI attempts to open the install URL in the browser and waits for the installation to become available
+- in non-interactive or `--json` mode, the CLI exits with `REPO_INSTALLATION_REQUIRED` and includes the install URL
+- the CLI lists repositories visible to the installation and finds the matching `owner/repo`
+- if the repository is not visible to any installation, the CLI creates a GitHub App install intent and exposes the install URL
+- if the repository still is not visible after the installation or repository-access step, the command fails with `REPO_NOT_ACCESSIBLE`
+- if the project is already connected to the same repository, the command returns the existing connection without creating a duplicate
+- if the project is already connected to a different repository, the command fails with `REPO_ALREADY_CONNECTED`
+- the CLI links the project to the repository with `POST /v1/source-repositories`
+- the link call sends `projectId`, `provider: "github"`, `providerRepositoryId`, and `installationId`
+
+Examples:
+
+```bash
+prisma-cli git connect
+prisma-cli git connect git@github.com:prisma/prisma-cli.git
+prisma-cli git connect --project proj_123
+prisma-cli git connect https://github.com/prisma/prisma-cli --project proj_123
+```
+
+## `prisma-cli git disconnect`
+
+Purpose:
+
+- disconnect the GitHub repository from the resolved Prisma project
+
+Behavior:
+
+- requires auth
+- resolves project context without creating projects
+- supports `--project <id-or-name>` for explicit project selection
+- removes the active server-side repository connection
+- stops future GitHub branch automation for that project
+- does not delete the resolved Prisma project
+- does not delete existing Branches synchronously; server-side retention rules own that behavior
+
+Examples:
+
+```bash
+prisma-cli git disconnect
+prisma-cli git disconnect --project proj_123
+prisma-cli git disconnect --json
+```
+
 ## `prisma-cli branch list`
 
 Purpose:

docs/product/error-conventions.md

@@ -160,6 +160,12 @@ These codes are the minimum stable set for the MVP:
 - `CONFIRMATION_REQUIRED`
 - `REMOVE_FAILED`
 - `FEATURE_UNAVAILABLE`
+- `REPO_PROVIDER_UNSUPPORTED`
+- `REPO_INSTALLATION_REQUIRED`
+- `REPO_NOT_ACCESSIBLE`
+- `REPO_NOT_CONNECTED`
+- `REPO_ALREADY_CONNECTED`
+- `REPO_CONNECTION_FAILED`
 - `BUILD_FAILED`
 - `RUN_FAILED`
 - `DEPLOY_FAILED`
@@ -182,6 +188,12 @@ Recommended meanings:
 - `CONFIRMATION_REQUIRED`: command cannot continue without confirmation in the current mode
 - `REMOVE_FAILED`: app removal could not complete remotely
 - `FEATURE_UNAVAILABLE`: the command exists in the CLI model, but the current preview cannot support it yet
+- `REPO_PROVIDER_UNSUPPORTED`: repository connection received a non-GitHub repository URL
+- `REPO_INSTALLATION_REQUIRED`: repository connection needs a GitHub App installation before the project can be linked
+- `REPO_NOT_ACCESSIBLE`: the connected GitHub App installations do not expose the requested repository
+- `REPO_NOT_CONNECTED`: a command expected a project repository connection, but none exists
+- `REPO_ALREADY_CONNECTED`: a project already has a different GitHub repository connected
+- `REPO_CONNECTION_FAILED`: the Management API repository connection operation failed
 - `BUILD_FAILED`: build failed before a healthy deployment existed
 - `RUN_FAILED`: local framework run command could not be started or exited unsuccessfully
 - `DEPLOY_FAILED`: deployment or post-build health failed

docs/product/output-conventions.md

@@ -68,6 +68,8 @@ Current MVP commands map to patterns like this:
 | `auth whoami` | `show` |
 | `project list` | `list` |
 | `project show` | `show` |
+| `git connect` | `mutate` |
+| `git disconnect` | `mutate` |
 | `branch list` | `list` |
 | `branch show` | `show` |
 | `branch use` | `mutate` |

packages/cli/src/adapters/git.ts

@@ -0,0 +1,73 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export interface GitHubRepositoryReference {
+  provider: "github";
+  owner: string;
+  name: string;
+  fullName: string;
+  url: string;
+}
+
+export async function readGitOriginRemote(cwd: string): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync("git", ["config", "--get", "remote.origin.url"], {
+      cwd,
+      timeout: 5_000,
+    });
+    const remote = stdout.trim();
+    return remote.length > 0 ? remote : null;
+  } catch {
+    return null;
+  }
+}
+
+export function parseGitHubRepositoryUrl(value: string): GitHubRepositoryReference | null {
+  const input = value.trim();
+  const shorthand = input.match(/^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?$/);
+
+  if (shorthand) {
+    return toGitHubRepositoryReference(shorthand[1], shorthand[2]);
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(input);
+  } catch {
+    return null;
+  }
+
+  if (parsed.hostname !== "github.com") {
+    return null;
+  }
+
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:" && parsed.protocol !== "ssh:") {
+    return null;
+  }
+
+  const parts = parsed.pathname.split("/").filter(Boolean);
+  if (parts.length !== 2) {
+    return null;
+  }
+
+  const [owner, rawName] = parts;
+  const name = rawName.endsWith(".git") ? rawName.slice(0, -4) : rawName;
+
+  return toGitHubRepositoryReference(owner, name);
+}
+
+function toGitHubRepositoryReference(owner: string | undefined, name: string | undefined): GitHubRepositoryReference | null {
+  if (!owner || !name || owner.includes("/") || name.includes("/")) {
+    return null;
+  }
+
+  return {
+    provider: "github",
+    owner,
+    name,
+    fullName: `${owner}/${name}`,
+    url: `https://github.com/${owner}/${name}`,
+  };
+}

packages/cli/src/adapters/local-state.ts

@@ -2,6 +2,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 
 import type { AuthProviderId } from "../types/auth";
+import type { GitRepositoryConnection } from "../types/project";
 
 export interface LocalState {
   auth: {
@@ -12,6 +13,7 @@ export interface LocalState {
   project: {
     rememberedByWorkspace: Record<string, RememberedProjectState>;
     lastResolved: RememberedProjectState | null;
+    repositoryConnectionsByProject: Record<string, GitRepositoryConnection>;
   };
   branch: {
     active: string;
@@ -38,6 +40,7 @@ const DEFAULT_STATE: LocalState = {
   project: {
     rememberedByWorkspace: {},
     lastResolved: null,
+    repositoryConnectionsByProject: {},
   },
   branch: {
     active: "preview",
@@ -70,6 +73,7 @@ export class LocalStateStore {
         project: {
           rememberedByWorkspace: parsed.project?.rememberedByWorkspace ?? {},
           lastResolved: parsed.project?.lastResolved ?? null,
+          repositoryConnectionsByProject: parsed.project?.repositoryConnectionsByProject ?? {},
         },
         branch: {
           active: parsed.branch?.active ?? DEFAULT_STATE.branch.active,
@@ -132,6 +136,28 @@ export class LocalStateStore {
     return state;
   }
 
+  async readRepositoryConnection(projectId: string): Promise<GitRepositoryConnection | null> {
+    const state = await this.read();
+    return state.project.repositoryConnectionsByProject[projectId] ?? null;
+  }
+
+  async setRepositoryConnection(
+    projectId: string,
+    connection: GitRepositoryConnection,
+  ): Promise<LocalState> {
+    const state = await this.read();
+    state.project.repositoryConnectionsByProject[projectId] = connection;
+    await this.write(state);
+    return state;
+  }
+
+  async clearRepositoryConnection(projectId: string): Promise<LocalState> {
+    const state = await this.read();
+    delete state.project.repositoryConnectionsByProject[projectId];
+    await this.write(state);
+    return state;
+  }
+
   async readSelectedApp(projectId: string): Promise<SelectedAppState | null> {
     const state = await this.read();
     return state.app.selectedByProject[projectId] ?? null;

packages/cli/src/cli.ts

@@ -5,7 +5,7 @@ import { Command, CommanderError, Option } from "commander";
 import { createAppCommand } from "./commands/app";
 import { createAuthCommand } from "./commands/auth";
 import { createBranchCommand } from "./commands/branch";
-
+import { createGitCommand } from "./commands/git";
 import { createProjectCommand } from "./commands/project";
 import { createVersionCommand } from "./commands/version";
 import { runVersion } from "./controllers/version";
@@ -67,8 +67,9 @@ export function createProgram(runtime: CliRuntime): Command {
 
   program.addCommand(createVersionCommand(runtime));
   program.addCommand(createAuthCommand(runtime));
-  program.addCommand(createBranchCommand(runtime));
   program.addCommand(createProjectCommand(runtime));
+  program.addCommand(createGitCommand(runtime));
+  program.addCommand(createBranchCommand(runtime));
   program.addCommand(createAppCommand(runtime));
 
   return program;

packages/cli/src/commands/git/index.ts

@@ -0,0 +1,67 @@
+import { Command } from "commander";
+
+import { runGitConnect, runGitDisconnect } from "../../controllers/project";
+import { renderGitConnect, renderGitDisconnect } from "../../presenters/project";
+import { runCommand } from "../../shell/command-runner";
+import { attachCommandDescriptor } from "../../shell/command-meta";
+import { addCompactGlobalFlags, addGlobalFlags } from "../../shell/global-flags";
+import { configureRuntimeCommand, type CliRuntime } from "../../shell/runtime";
+import type { ProjectRepositoryConnectionResult } from "../../types/project";
+
+export function createGitCommand(runtime: CliRuntime): Command {
+  const git = attachCommandDescriptor(configureRuntimeCommand(new Command("git"), runtime), "git");
+
+  addCompactGlobalFlags(git);
+
+  git.addCommand(createGitConnectCommand(runtime));
+  git.addCommand(createGitDisconnectCommand(runtime));
+
+  return git;
+}
+
+function createGitConnectCommand(runtime: CliRuntime): Command {
+  const command = attachCommandDescriptor(configureRuntimeCommand(new Command("connect"), runtime), "git.connect");
+
+  command.argument("[git-url]", "GitHub repository URL");
+  command.option("--project <id-or-name>", "Project id or name");
+  addGlobalFlags(command);
+
+  command.action(async (gitUrl: string | undefined, options) => {
+    await runCommand<ProjectRepositoryConnectionResult>(
+      runtime,
+      "git.connect",
+      options as Record<string, unknown>,
+      (context) => runGitConnect(context, gitUrl, {
+        project: typeof options.project === "string" ? options.project : undefined,
+      }),
+      {
+        renderHuman: (context, descriptor, result) => renderGitConnect(context, descriptor, result),
+      },
+    );
+  });
+
+  return command;
+}
+
+function createGitDisconnectCommand(runtime: CliRuntime): Command {
+  const command = attachCommandDescriptor(configureRuntimeCommand(new Command("disconnect"), runtime), "git.disconnect");
+
+  command.option("--project <id-or-name>", "Project id or name");
+  addGlobalFlags(command);
+
+  command.action(async (options) => {
+    await runCommand<ProjectRepositoryConnectionResult>(
+      runtime,
+      "git.disconnect",
+      options as Record<string, unknown>,
+      (context) => runGitDisconnect(context, {
+        project: typeof options.project === "string" ? options.project : undefined,
+      }),
+      {
+        renderHuman: (context, descriptor, result) => renderGitDisconnect(context, descriptor, result),
+      },
+    );
+  });
+
+  return command;
+}