Skip to content

Commit a3e646f

Browse files
feat(web): clone repositories in the background instead of holding the palette open
Cloning a repository from Add Project kept the command palette open until git finished, which on large repositories is minutes of a modal spinner, and the server killed the clone after a hard 120s timeout. The server now creates the project immediately against the empty destination and runs `git clone --progress` in a tracked background fiber (ProjectCloneTracker), streaming stage/percent/transfer rate over `subscribeProjectClones`. The palette closes as soon as the clone starts and opens the project's draft, where the user can write their prompt while a composer banner shows progress; sending stays blocked until the clone lands, and the server refuses thread.create / bootstrap turn starts for a project mid-clone so other clients cannot start on an empty tree. A toast carries the same progress everywhere else, with Cancel while running and Retry / Remove project after a failure. Failures keep git's own explanation. Removing the project mid-clone stops it and clears the partial checkout. Older servers fall back to the previous blocking clone via the `projectCloneTracking` capability. Co-Authored-By: Claude Fable 5 <[email protected]>
1 parent cba7dd7 commit a3e646f

23 files changed

Lines changed: 1760 additions & 21 deletions

‎apps/server/src/auth/RpcAuthorization.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,10 @@ export const RPC_REQUIRED_SCOPES = {
9797
[WS_METHODS.sourceControlLookupRepository]: AuthOrchestrationReadScope,
9898
[WS_METHODS.sourceControlCloneRepository]: AuthOrchestrationOperateScope,
9999
[WS_METHODS.sourceControlPublishRepository]: AuthOrchestrationOperateScope,
100+
[WS_METHODS.projectCloneStart]: AuthOrchestrationOperateScope,
101+
[WS_METHODS.projectCloneCancel]: AuthOrchestrationOperateScope,
102+
[WS_METHODS.projectCloneRetry]: AuthOrchestrationOperateScope,
103+
[WS_METHODS.subscribeProjectClones]: AuthOrchestrationReadScope,
100104
[WS_METHODS.projectsListEntries]: AuthOrchestrationReadScope,
101105
[WS_METHODS.projectsReadFile]: AuthOrchestrationReadScope,
102106
[WS_METHODS.projectsSearchContents]: AuthOrchestrationReadScope,

‎apps/server/src/environment/ServerEnvironment.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -236,6 +236,7 @@ export const make = Effect.gen(function* () {
236236
pullRequestStackActions: true,
237237
threadPullRequestLinking: true,
238238
environmentIcon: true,
239+
projectCloneTracking: true,
239240
...(serverSelfUpdate === null ? {} : { serverSelfUpdate }),
240241
...(serverSelfUpdate === "boot-service" || desktopAppUpdate
241242
? {
Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
import { describe, expect, it } from "@effect/vitest";
2+
import { ProjectId, SourceControlRepositoryError } from "@t3tools/contracts";
3+
import * as Deferred from "effect/Deferred";
4+
import * as Effect from "effect/Effect";
5+
import * as Fiber from "effect/Fiber";
6+
import * as Layer from "effect/Layer";
7+
import * as Stream from "effect/Stream";
8+
import * as TestClock from "effect/testing/TestClock";
9+
10+
import * as SourceControlRepositoryService from "../sourceControl/SourceControlRepositoryService.ts";
11+
import * as ProjectCloneTracker from "./ProjectCloneTracker.ts";
12+
import { parseGitCloneProgressLine } from "./gitCloneProgress.ts";
13+
14+
const projectId = ProjectId.make("project-1");
15+
const startInput = {
16+
projectId,
17+
title: "t3code",
18+
createdAt: "2026-01-01T00:00:00.000Z",
19+
remoteUrl: "[email protected]:octocat/t3code.git",
20+
destinationPath: "/workspace/t3code",
21+
};
22+
23+
function makeHarness(options?: {
24+
readonly clone?: SourceControlRepositoryService.SourceControlRepositoryService["Service"]["cloneRepository"];
25+
}) {
26+
const created: Array<{ projectId: ProjectId; workspaceRoot: string }> = [];
27+
const cloned: Array<ProjectId> = [];
28+
const discarded: Array<string> = [];
29+
const hooks: ProjectCloneTracker.ProjectCloneHooks = {
30+
createProject: (input) =>
31+
Effect.sync(() => {
32+
created.push({ projectId: input.projectId, workspaceRoot: input.workspaceRoot });
33+
}),
34+
onCloned: (input) => Effect.sync(() => void cloned.push(input.projectId)),
35+
};
36+
const layer = ProjectCloneTracker.layer.pipe(
37+
Layer.provide(
38+
Layer.mock(SourceControlRepositoryService.SourceControlRepositoryService)({
39+
prepareClone: (input) =>
40+
Effect.succeed({
41+
destinationPath: input.destinationPath,
42+
remoteUrl: input.remoteUrl ?? "",
43+
repository: null,
44+
}),
45+
cloneRepository:
46+
options?.clone ??
47+
((input) =>
48+
Effect.succeed({
49+
cwd: input.destinationPath,
50+
remoteUrl: input.remoteUrl ?? "",
51+
repository: null,
52+
})),
53+
discardClone: (destination) => Effect.sync(() => void discarded.push(destination)),
54+
}),
55+
),
56+
);
57+
return { layer, hooks, created, cloned, discarded };
58+
}
59+
60+
describe("ProjectCloneTracker", () => {
61+
it.effect("creates the project first and reports the clone through the stream", () => {
62+
const release = Deferred.makeUnsafe<void>();
63+
const harness = makeHarness({
64+
clone: (input, options) =>
65+
Effect.gen(function* () {
66+
yield* (
67+
options?.onProgress?.({ stage: "receiving", percent: 40, detail: "1 MiB" }) ??
68+
Effect.void
69+
);
70+
yield* Deferred.await(release);
71+
return { cwd: input.destinationPath, remoteUrl: input.remoteUrl ?? "", repository: null };
72+
}),
73+
});
74+
return Effect.gen(function* () {
75+
const tracker = yield* ProjectCloneTracker.ProjectCloneTracker;
76+
const collected = yield* tracker.stream.pipe(
77+
Stream.takeUntil((clones) => clones[0]?.phase === "done"),
78+
Stream.runCollect,
79+
Effect.forkChild,
80+
);
81+
yield* Effect.yieldNow;
82+
83+
const result = yield* tracker.start(startInput, harness.hooks);
84+
expect(result.cwd).toBe("/workspace/t3code");
85+
// The project exists before git runs so the draft can open immediately.
86+
expect(harness.created).toEqual([{ projectId, workspaceRoot: "/workspace/t3code" }]);
87+
88+
yield* Effect.yieldNow;
89+
const running = yield* tracker.get(projectId);
90+
expect(running).toMatchObject({ phase: "running", stage: "receiving", percent: 40 });
91+
92+
yield* Deferred.succeed(release, undefined);
93+
const lists = yield* Fiber.join(collected);
94+
const final = lists.at(-1)?.[0];
95+
expect(final).toMatchObject({ phase: "done", percent: 100 });
96+
expect(harness.cloned).toEqual([projectId]);
97+
98+
// Done clones drop out after the grace window so the toast can settle.
99+
yield* TestClock.adjust("31 seconds");
100+
expect(yield* tracker.get(projectId)).toBeNull();
101+
}).pipe(Effect.provide(harness.layer));
102+
});
103+
104+
it.effect("keeps a failed clone with git's own explanation and retries it", () => {
105+
let attempts = 0;
106+
const harness = makeHarness({
107+
clone: (input) =>
108+
Effect.suspend(() => {
109+
attempts += 1;
110+
return attempts === 1
111+
? Effect.fail(
112+
new SourceControlRepositoryError({
113+
operation: "cloneRepository",
114+
provider: "unknown",
115+
detail: "fatal: repository not found",
116+
}),
117+
)
118+
: Effect.succeed({
119+
cwd: input.destinationPath,
120+
remoteUrl: input.remoteUrl ?? "",
121+
repository: null,
122+
});
123+
}),
124+
});
125+
return Effect.gen(function* () {
126+
const tracker = yield* ProjectCloneTracker.ProjectCloneTracker;
127+
yield* tracker.start(startInput, harness.hooks);
128+
yield* Effect.yieldNow;
129+
const failed = yield* tracker.get(projectId);
130+
expect(failed).toMatchObject({ phase: "failed", error: "fatal: repository not found" });
131+
132+
expect(yield* tracker.retry(projectId)).toBe(true);
133+
// The partial checkout is cleared so git sees an empty destination.
134+
expect(harness.discarded).toEqual(["/workspace/t3code"]);
135+
yield* Effect.yieldNow;
136+
expect((yield* tracker.get(projectId))?.phase).toBe("done");
137+
expect(attempts).toBe(2);
138+
}).pipe(Effect.provide(harness.layer));
139+
});
140+
141+
it.effect("cancel interrupts the clone and removes the partial checkout", () => {
142+
const harness = makeHarness({ clone: () => Effect.never });
143+
return Effect.gen(function* () {
144+
const tracker = yield* ProjectCloneTracker.ProjectCloneTracker;
145+
yield* tracker.start(startInput, harness.hooks);
146+
yield* Effect.yieldNow;
147+
148+
expect(yield* tracker.cancel(projectId)).toBe(true);
149+
expect((yield* tracker.get(projectId))?.phase).toBe("cancelled");
150+
expect(harness.discarded).toEqual(["/workspace/t3code"]);
151+
// Nothing left to cancel; retry is what brings it back.
152+
expect(yield* tracker.cancel(projectId)).toBe(false);
153+
expect(yield* tracker.retry(projectId)).toBe(true);
154+
}).pipe(Effect.provide(harness.layer));
155+
});
156+
157+
it.effect("a cancel that lands after git finished keeps the checkout", () => {
158+
const gate = Deferred.makeUnsafe<void>();
159+
const harness = makeHarness();
160+
// The clone itself completes instantly; the post-clone hook is what hangs.
161+
const hooks: ProjectCloneTracker.ProjectCloneHooks = {
162+
...harness.hooks,
163+
onCloned: () => Deferred.await(gate),
164+
};
165+
return Effect.gen(function* () {
166+
const tracker = yield* ProjectCloneTracker.ProjectCloneTracker;
167+
yield* tracker.start(startInput, hooks);
168+
yield* Effect.yieldNow;
169+
expect((yield* tracker.get(projectId))?.phase).toBe("done");
170+
expect(yield* tracker.cancel(projectId)).toBe(false);
171+
expect(harness.discarded).toEqual([]);
172+
yield* Deferred.succeed(gate, undefined);
173+
}).pipe(Effect.provide(harness.layer));
174+
});
175+
176+
it.effect("discard forgets a project's clone when the project is deleted", () => {
177+
const harness = makeHarness({ clone: () => Effect.never });
178+
return Effect.gen(function* () {
179+
const tracker = yield* ProjectCloneTracker.ProjectCloneTracker;
180+
yield* tracker.start(startInput, harness.hooks);
181+
yield* Effect.yieldNow;
182+
yield* tracker.discard(projectId);
183+
expect(yield* tracker.get(projectId)).toBeNull();
184+
expect(harness.discarded).toEqual(["/workspace/t3code"]);
185+
}).pipe(Effect.provide(harness.layer));
186+
});
187+
188+
it.effect("does not create a project when the clone cannot be prepared", () => {
189+
const harness = makeHarness();
190+
const layer = ProjectCloneTracker.layer.pipe(
191+
Layer.provide(
192+
Layer.mock(SourceControlRepositoryService.SourceControlRepositoryService)({
193+
prepareClone: () =>
194+
Effect.fail(
195+
new SourceControlRepositoryError({
196+
operation: "cloneRepository",
197+
provider: "unknown",
198+
detail: "Destination path already exists and is not empty.",
199+
}),
200+
),
201+
}),
202+
),
203+
);
204+
return Effect.gen(function* () {
205+
const tracker = yield* ProjectCloneTracker.ProjectCloneTracker;
206+
const error = yield* Effect.flip(tracker.start(startInput, harness.hooks));
207+
expect(error.message).toContain("not empty");
208+
expect(harness.created).toEqual([]);
209+
expect(yield* tracker.get(projectId)).toBeNull();
210+
}).pipe(Effect.provide(layer));
211+
});
212+
});
213+
214+
describe("parseGitCloneProgressLine", () => {
215+
it("parses git's transfer counters and ignores other output", () => {
216+
expect(
217+
parseGitCloneProgressLine("Receiving objects: 45% (4500/10000), 12.30 MiB | 5.00 MiB/s"),
218+
).toEqual({ stage: "receiving", percent: 45, detail: "12.30 MiB | 5.00 MiB/s" });
219+
expect(parseGitCloneProgressLine("Resolving deltas: 100% (700/700), done.")).toEqual({
220+
stage: "resolving",
221+
percent: 100,
222+
detail: null,
223+
});
224+
expect(parseGitCloneProgressLine("remote: Compressing objects: 12% (3/25)")).toEqual({
225+
stage: "counting",
226+
percent: 12,
227+
detail: null,
228+
});
229+
expect(parseGitCloneProgressLine("Updating files: 78% (2104/2700)")).toEqual({
230+
stage: "checkout",
231+
percent: 78,
232+
detail: null,
233+
});
234+
expect(parseGitCloneProgressLine("remote: Enumerating objects: 10, done.")).toEqual({
235+
stage: "counting",
236+
percent: null,
237+
detail: null,
238+
});
239+
expect(parseGitCloneProgressLine("Cloning into 't3code'...")).toBeNull();
240+
expect(parseGitCloneProgressLine("fatal: repository not found")).toBeNull();
241+
});
242+
});

0 commit comments

Comments
 (0)