feat: clone GitHub repo into a workspace (#1331)

* feat: clone GitHub repo into a workspace

Add an end-to-end "clone a GitHub repo and register it as a Paseo
workspace" flow: a new workspace.github.clone RPC, daemon handler,
client method, CLI `paseo clone` command, and a GitHub-repo mode in
the project picker modal. Gated behind the workspaceGithubClone
server capability flag.

- protocol: workspace.github.clone request/response schemas + feature flag
- server: handleWorkspaceGithubCloneRequest, normalizeCloneRepository
- client: DaemonClient.cloneGithubWorkspace
- cli: `paseo clone <repo> --dir <path> [--protocol https|ssh]`
- app: GitHub-repo mode, clone-protocol picker, error surfacing

Review fixes:
- CLI clone now checks the workspaceGithubClone capability and fails
  fast with a clear "update the host" error instead of hanging for the
  full request timeout against an older daemon.
- Replace the duplicated client-side URL-detection regex (app + CLI)
  with a shared isCompleteGitRemote() in @getpaseo/protocol/git-remote,
  backed by parseGitRemoteLocation so clients classify remotes
  identically to the daemon (fixes confusing errors for git://, ftp://,
  file:// inputs).
- Add git-remote.test.ts covering the shared classifier.

* Fix GitHub clone failure handling

---------

Co-authored-by: Mohamed Boudra <boudra.moha@gmail.com>

packages/app/src/hooks/open-project.ts

@@ -1,12 +1,18 @@
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
-import type { ProjectAddResponse } from "@getpaseo/protocol/messages";
+import type { ProjectAddResponse, WorkspaceGithubCloneProtocol } from "@getpaseo/protocol/messages";
 import {
   normalizeEmptyProjectDescriptor as normalizeProjectWithoutWorkspacesDescriptor,
+  normalizeWorkspaceDescriptor,
   type EmptyProjectDescriptor as ProjectWithoutWorkspacesDescriptor,
+  type WorkspaceDescriptor,
 } from "@/stores/session-store";
+import { buildWorkspaceTabPersistenceKey } from "@/stores/workspace-tabs-store";
 
 type OpenProjectPayload = ProjectAddResponse["payload"];
 type OpenProjectErrorCode = NonNullable<OpenProjectPayload["errorCode"]>;
+type WorkspaceOpenPayload =
+  | Awaited<ReturnType<DaemonClient["openProject"]>>
+  | Awaited<ReturnType<DaemonClient["cloneGithubWorkspace"]>>;
 
 export interface OpenProjectSuccess {
   ok: true;
@@ -20,6 +26,7 @@ export interface OpenProjectFailure {
 
 export type OpenProjectResult = OpenProjectSuccess | OpenProjectFailure;
 export type OpenProjectFailureReason = "directory_not_found" | "open_failed";
+export type { WorkspaceGithubCloneProtocol };
 
 export function getOpenProjectFailureReason(
   result: OpenProjectResult,
@@ -45,6 +52,22 @@ export interface OpenProjectDirectlyInput {
   setHasHydratedWorkspaces: (serverId: string, hydrated: boolean) => void;
 }
 
+interface WorkspaceOpenCallbacks {
+  serverId: string;
+  isConnected: boolean;
+  mergeWorkspaces: (serverId: string, workspaces: Iterable<WorkspaceDescriptor>) => void;
+  setHasHydratedWorkspaces: (serverId: string, hydrated: boolean) => void;
+  openDraftTab: (workspaceKey: string) => string | null;
+  navigateToWorkspace: (serverId: string, workspaceId: string) => void;
+}
+
+export interface OpenGithubRepoDirectlyInput extends WorkspaceOpenCallbacks {
+  repo: string;
+  targetDirectory: string;
+  cloneProtocol?: WorkspaceGithubCloneProtocol;
+  client: Pick<DaemonClient, "cloneGithubWorkspace"> | null;
+}
+
 export async function openProjectDirectly(
   input: OpenProjectDirectlyInput,
 ): Promise<OpenProjectResult> {
@@ -78,3 +101,50 @@ export async function openProjectDirectly(
   input.setHasHydratedWorkspaces(normalizedServerId, true);
   return { ok: true };
 }
+
+function finishWorkspaceOpen(
+  input: WorkspaceOpenCallbacks,
+  payload: WorkspaceOpenPayload,
+): boolean {
+  const normalizedServerId = input.serverId.trim();
+  if (!normalizedServerId || payload.error || !payload.workspace) {
+    return false;
+  }
+
+  const workspace = normalizeWorkspaceDescriptor(payload.workspace);
+  const workspaceKey = buildWorkspaceTabPersistenceKey({
+    serverId: normalizedServerId,
+    workspaceId: workspace.id,
+  });
+  if (!workspaceKey) {
+    return false;
+  }
+
+  input.mergeWorkspaces(normalizedServerId, [workspace]);
+  input.setHasHydratedWorkspaces(normalizedServerId, true);
+  input.openDraftTab(workspaceKey);
+  input.navigateToWorkspace(normalizedServerId, workspace.id);
+  return true;
+}
+
+export async function openGithubRepoDirectly(input: OpenGithubRepoDirectlyInput): Promise<boolean> {
+  const normalizedServerId = input.serverId.trim();
+  const trimmedRepo = input.repo.trim();
+  const trimmedTargetDirectory = input.targetDirectory.trim();
+  if (
+    !normalizedServerId ||
+    !trimmedRepo ||
+    !trimmedTargetDirectory ||
+    !input.client ||
+    !input.isConnected
+  ) {
+    return false;
+  }
+
+  const payload = await input.client.cloneGithubWorkspace({
+    repo: trimmedRepo,
+    targetDirectory: trimmedTargetDirectory,
+    ...(input.cloneProtocol ? { cloneProtocol: input.cloneProtocol } : {}),
+  });
+  return finishWorkspaceOpen(input, payload);
+}

packages/app/src/hooks/use-open-project.test.ts

@@ -1,6 +1,13 @@
 import { describe, expect, it } from "vitest";
-import { getOpenProjectFailureReason, openProjectDirectly } from "@/hooks/open-project";
-import type { EmptyProjectDescriptor as ProjectWithoutWorkspacesDescriptor } from "@/stores/session-store";
+import {
+  getOpenProjectFailureReason,
+  openGithubRepoDirectly,
+  openProjectDirectly,
+} from "@/hooks/open-project";
+import type {
+  EmptyProjectDescriptor as ProjectWithoutWorkspacesDescriptor,
+  WorkspaceDescriptor,
+} from "@/stores/session-store";
 
 const SERVER_ID = "server-1";
 const PROJECT_PATH = "/repo/project";
@@ -14,31 +21,113 @@ function buildProjectPayload() {
   };
 }
 
+function buildWorkspacePayload() {
+  return {
+    id: "1",
+    projectId: "1",
+    projectDisplayName: "project",
+    projectRootPath: PROJECT_PATH,
+    workspaceDirectory: PROJECT_PATH,
+    projectKind: "git" as const,
+    workspaceKind: "checkout" as const,
+    name: "project",
+    archivingAt: null,
+    status: "done" as const,
+    statusEnteredAt: null,
+    activityAt: null,
+    diffStat: null,
+    scripts: [],
+  };
+}
+
 interface RecordedProject {
   serverId: string;
   project: ProjectWithoutWorkspacesDescriptor;
 }
 
+interface RecordedMerge {
+  serverId: string;
+  workspaces: WorkspaceDescriptor[];
+}
+
 interface RecordedHydrated {
   serverId: string;
   hydrated: boolean;
 }
 
+interface RecordedOpenDraftTab {
+  workspaceKey: string;
+}
+
+interface RecordedNavigate {
+  serverId: string;
+  workspaceId: string;
+}
+
+interface RecordedClone {
+  repo: string;
+  targetDirectory: string;
+  cloneProtocol?: "https" | "ssh";
+}
+
 function createFakeSession() {
   const projects: RecordedProject[] = [];
+  const merges: RecordedMerge[] = [];
   const hydrated: RecordedHydrated[] = [];
   return {
     projects,
+    merges,
     hydrated,
     addEmptyProject: (serverId: string, project: ProjectWithoutWorkspacesDescriptor) => {
       projects.push({ serverId, project });
     },
+    mergeWorkspaces: (serverId: string, workspaces: Iterable<WorkspaceDescriptor>) => {
+      merges.push({ serverId, workspaces: Array.from(workspaces) });
+    },
     setHasHydratedWorkspaces: (serverId: string, value: boolean) => {
       hydrated.push({ serverId, hydrated: value });
     },
   };
 }
 
+function createFakeWorkspaceLayout() {
+  const openedTabs: RecordedOpenDraftTab[] = [];
+  return {
+    openedTabs,
+    openDraftTab: (workspaceKey: string) => {
+      openedTabs.push({ workspaceKey });
+      return "tab-1";
+    },
+  };
+}
+
+function createFakeNavigator() {
+  const navigations: RecordedNavigate[] = [];
+  return {
+    navigations,
+    navigateToWorkspace: (serverId: string, workspaceId: string) => {
+      navigations.push({ serverId, workspaceId });
+    },
+  };
+}
+
+function createFakeGithubCloneClient(workspace: ReturnType<typeof buildWorkspacePayload>) {
+  const clones: RecordedClone[] = [];
+  return {
+    clones,
+    cloneGithubWorkspace: async (input: RecordedClone) => {
+      clones.push(input);
+      return {
+        requestId: "request-3",
+        repo: "owner/project",
+        checkoutPath: PROJECT_PATH,
+        error: null,
+        workspace,
+      };
+    },
+  };
+}
+
 describe("openProjectDirectly", () => {
   it("adds the project and marks workspaces hydrated without opening a workspace", async () => {
     const session = createFakeSession();
@@ -73,6 +162,7 @@ describe("openProjectDirectly", () => {
         },
       },
     ]);
+    expect(session.merges).toEqual([]);
     expect(session.hydrated).toEqual([{ serverId: SERVER_ID, hydrated: true }]);
   });
 
@@ -133,6 +223,75 @@ describe("openProjectDirectly", () => {
   });
 });
 
+describe("openGithubRepoDirectly", () => {
+  it("opens a cloned GitHub workspace and seeds a draft tab", async () => {
+    const session = createFakeSession();
+    const layout = createFakeWorkspaceLayout();
+    const navigator = createFakeNavigator();
+    const workspacePayload = buildWorkspacePayload();
+    const github = createFakeGithubCloneClient(workspacePayload);
+
+    const result = await openGithubRepoDirectly({
+      serverId: SERVER_ID,
+      repo: "owner/project",
+      targetDirectory: "~/workspace",
+      cloneProtocol: "https",
+      isConnected: true,
+      client: github,
+      mergeWorkspaces: session.mergeWorkspaces,
+      setHasHydratedWorkspaces: session.setHasHydratedWorkspaces,
+      openDraftTab: layout.openDraftTab,
+      navigateToWorkspace: navigator.navigateToWorkspace,
+    });
+
+    expect(result).toBe(true);
+    expect(github.clones).toEqual([
+      {
+        repo: "owner/project",
+        targetDirectory: "~/workspace",
+        cloneProtocol: "https",
+      },
+    ]);
+    expect(session.merges).toHaveLength(1);
+    expect(session.merges[0]?.serverId).toBe(SERVER_ID);
+    expect(session.merges[0]?.workspaces[0]).toMatchObject({
+      id: "1",
+      projectId: "1",
+      projectRootPath: PROJECT_PATH,
+      workspaceDirectory: PROJECT_PATH,
+    });
+    expect(session.hydrated).toEqual([{ serverId: SERVER_ID, hydrated: true }]);
+    expect(layout.openedTabs).toEqual([{ workspaceKey: `${SERVER_ID}:1` }]);
+    expect(navigator.navigations).toEqual([{ serverId: SERVER_ID, workspaceId: "1" }]);
+  });
+
+  it("rejects a workspace without an identity before changing app state", async () => {
+    const session = createFakeSession();
+    const layout = createFakeWorkspaceLayout();
+    const navigator = createFakeNavigator();
+    const github = createFakeGithubCloneClient({ ...buildWorkspacePayload(), id: " " });
+
+    const result = await openGithubRepoDirectly({
+      serverId: SERVER_ID,
+      repo: "owner/project",
+      targetDirectory: "~/workspace",
+      cloneProtocol: "https",
+      isConnected: true,
+      client: github,
+      mergeWorkspaces: session.mergeWorkspaces,
+      setHasHydratedWorkspaces: session.setHasHydratedWorkspaces,
+      openDraftTab: layout.openDraftTab,
+      navigateToWorkspace: navigator.navigateToWorkspace,
+    });
+
+    expect(result).toBe(false);
+    expect(session.merges).toEqual([]);
+    expect(session.hydrated).toEqual([]);
+    expect(layout.openedTabs).toEqual([]);
+    expect(navigator.navigations).toEqual([]);
+  });
+});
+
 describe("getOpenProjectFailureReason", () => {
   it("keeps the known directory-not-found failure reason", () => {
     expect(

packages/app/src/hooks/use-open-project.ts

@@ -1,7 +1,15 @@
 import { useCallback } from "react";
 import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
 import { useSessionStore } from "@/stores/session-store";
-import { openProjectDirectly, type OpenProjectResult } from "@/hooks/open-project";
+import { useWorkspaceLayoutStore } from "@/stores/workspace-layout-store";
+import { generateDraftId } from "@/stores/draft-keys";
+import { navigateToWorkspace } from "@/stores/navigation-active-workspace-store";
+import {
+  openGithubRepoDirectly,
+  openProjectDirectly,
+  type OpenProjectResult,
+  type WorkspaceGithubCloneProtocol,
+} from "@/hooks/open-project";
 
 export function useOpenProject(
   serverId: string | null,
@@ -40,3 +48,48 @@ export function useOpenProject(
     ],
   );
 }
+
+export function useOpenGithubRepo(
+  serverId: string | null,
+): (
+  repo: string,
+  targetDirectory: string,
+  cloneProtocol?: WorkspaceGithubCloneProtocol,
+) => Promise<boolean> {
+  const normalizedServerId = serverId?.trim() ?? "";
+  const client = useHostRuntimeClient(normalizedServerId);
+  const isConnected = useHostRuntimeIsConnected(normalizedServerId);
+  const mergeWorkspaces = useSessionStore((state) => state.mergeWorkspaces);
+  const setHasHydratedWorkspaces = useSessionStore((state) => state.setHasHydratedWorkspaces);
+  const openDraftTab = useCallback((workspaceKey: string) => {
+    return useWorkspaceLayoutStore.getState().openTabFocused(workspaceKey, {
+      kind: "draft",
+      draftId: generateDraftId(),
+    });
+  }, []);
+
+  return useCallback(
+    async (repo: string, targetDirectory: string, cloneProtocol?: WorkspaceGithubCloneProtocol) => {
+      return openGithubRepoDirectly({
+        serverId: normalizedServerId,
+        repo,
+        targetDirectory,
+        ...(cloneProtocol ? { cloneProtocol } : {}),
+        isConnected,
+        client,
+        mergeWorkspaces,
+        setHasHydratedWorkspaces,
+        openDraftTab,
+        navigateToWorkspace,
+      });
+    },
+    [
+      client,
+      isConnected,
+      mergeWorkspaces,
+      normalizedServerId,
+      openDraftTab,
+      setHasHydratedWorkspaces,
+    ],
+  );
+}