Compare commits

...
Author SHA1 Message Date
paseo-bot[bot] 2e4def4eb7 fix(server): reconcile projects nested under a changed Git root
Git initialization or removal changes the checkout for directories
beneath the watched root. Include nested projects and workspaces in
the event-driven pass, including workspaces attached to another project.
2026-11-22 03:25:34 +00:00
paseo-bot[bot]andVictor Dozal 9d64a5fc50 test(server): compare Git reconciliation paths across platforms
Use portable separators for relative checkout paths. Resolve the
expected repository root so a Windows short path does not fail the
checkout identity assertion.

Co-authored-by: Victor Dozal <v.dozal@live.com>
2026-11-22 03:13:33 +00:00
Victor Dozal ab8107757b Read a checkout's identity for reconciliation without scanning its working tree 2026-11-20 18:22:08 -06:00
Victor Dozal 3c4556c06e Re-read only the workspaces of the project whose .git changed 2026-11-20 18:09:27 -06:00
7 changed files with 376 additions and 33 deletions
@@ -134,6 +134,36 @@ test("a fresh checkout read makes a newly initialized repository available to ca
expect(realpathSync.native(repoRoot)).toBe(realpathSync.native(repo));
}, 30_000);
test("a checkout read for reconciliation never scans the working tree", async () => {
const root = realpathSync(mkdtempSync(path.join(tmpdir(), "paseo-checkout-read-")));
const repo = path.join(root, "repo");
mkdirSync(repo);
const git = (...args: string[]) =>
execFileSync("git", ["-c", "commit.gpgsign=false", ...args], { cwd: repo, stdio: "pipe" });
git("init", "-b", "main");
git("config", "user.email", "test@example.com");
git("config", "user.name", "Test");
writeFileSync(path.join(repo, "README.md"), "base\n");
git("add", ".");
git("commit", "-m", "base");
const service = new WorkspaceGitServiceImpl({
logger: pino({ enabled: false }),
paseoHome: path.join(root, "home"),
});
cleanup.push(async () => {
await service.dispose();
rmSync(root, { recursive: true, force: true });
});
startGitCommandMetrics();
const checkout = await service.getCheckout(repo, { priority: "background" });
const verbs = stopGitCommandMetrics().commands.map((command) => command.args[0]);
expect(checkout).toMatchObject({ isGit: true, currentBranch: "main" });
expect(verbs.length).toBeGreaterThan(0);
expect(verbs.filter((verb) => ["status", "ls-files", "rev-list"].includes(verb))).toEqual([]);
}, 30_000);
test("recursive observation updates tracked state and prunes ignored storms", async () => {
const tempDir = realpathSync(mkdtempSync(path.join(tmpdir(), "paseo-git-observation-")));
const repoDir = path.join(tempDir, "repo");
@@ -427,7 +427,7 @@ describe("WorkspaceGitServiceImpl primitive refresh entrypoint", () => {
test("getCheckout surfaces an unexpected Git read failure", async () => {
const service = createService({
getCheckoutStatus: vi.fn(async () => {
getCheckoutIdentity: vi.fn(async () => {
throw new Error("Git read failed");
}),
});
@@ -18,6 +18,7 @@ import {
getCheckoutRefDerivedState,
getCheckoutSnapshotFacts,
getCheckoutShortstat,
getCheckoutIdentity,
getCheckoutStatus,
getCheckoutWorktreeState,
getPullRequestStatus,
@@ -407,6 +408,7 @@ interface WorkspaceGitServiceDependencies {
subscribe: SubscribeToFileChanges;
getCheckoutSnapshotFacts: typeof getCheckoutSnapshotFacts;
getCheckoutRefDerivedState: typeof getCheckoutRefDerivedState;
getCheckoutIdentity: typeof getCheckoutIdentity;
getCheckoutStatus: typeof getCheckoutStatus;
getCheckoutShortstat: typeof getCheckoutShortstat;
getCheckoutWorktreeState: typeof getCheckoutWorktreeState;
@@ -624,6 +626,7 @@ function buildDefaultWorkspaceGitServiceDeps(
subscribe,
getCheckoutSnapshotFacts,
getCheckoutRefDerivedState,
getCheckoutIdentity,
getCheckoutStatus,
getCheckoutShortstat,
getCheckoutWorktreeState,
@@ -857,7 +860,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
): Promise<ProjectCheckoutLitePayload> {
this.assertNotDisposed();
const normalizedCwd = resolve(cwd);
const status = await this.deps.getCheckoutStatus(normalizedCwd, {
const identity = await this.deps.getCheckoutIdentity(normalizedCwd, {
paseoHome: this.paseoHome,
worktreesRoot: this.worktreesRoot,
logger: this.logger,
@@ -866,7 +869,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
: {}),
});
const cached = this.getCachedSnapshot(normalizedCwd);
if (cached && cached.git.isGit !== status.isGit) {
if (cached && cached.git.isGit !== identity.isGit) {
// A fresh checkout read discovered a repository transition. Keep the
// shared snapshot current before exposing the new project capability.
await this.getSnapshot(normalizedCwd, {
@@ -875,7 +878,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
reason: "checkout-classification-changed",
});
}
if (!status.isGit) {
if (!identity.isGit) {
return checkoutLiteFromGitSnapshot(normalizedCwd, {
isGit: false,
currentBranch: null,
@@ -887,11 +890,11 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
}
return checkoutLiteFromGitSnapshot(normalizedCwd, {
isGit: true,
currentBranch: status.currentBranch,
remoteUrl: status.remoteUrl,
repoRoot: status.repoRoot,
isPaseoOwnedWorktree: status.isPaseoOwnedWorktree,
mainRepoRoot: status.mainRepoRoot,
currentBranch: identity.currentBranch,
remoteUrl: identity.remoteUrl,
repoRoot: identity.repoRoot,
isPaseoOwnedWorktree: identity.isPaseoOwnedWorktree,
mainRepoRoot: identity.mainRepoRoot,
});
}
@@ -175,6 +175,7 @@ class ObservedPlacements {
private readonly service: WorkspaceReconciliationService;
private started = false;
private checkoutReadCount = 0;
private readonly checkoutReadCwds: string[] = [];
constructor(private readonly specs: ProjectSpec[]) {
cleanupPaths.push(this.home);
@@ -324,6 +325,11 @@ class ObservedPlacements {
return this.checkoutReadCount;
}
/** Home-relative directories read since the last call, with portable separators. */
takeCheckoutReads(): string[] {
return this.checkoutReadCwds.splice(0).sort();
}
get pendingTimers(): number {
return this.clock.pendingCount;
}
@@ -370,6 +376,7 @@ class ObservedPlacements {
private async readCheckout(cwd: string): Promise<ProjectCheckoutLitePayload> {
this.checkoutReadCount += 1;
this.checkoutReadCwds.push(path.relative(this.home, cwd).split(path.sep).join("/"));
const configured = [...this.checkoutByCwd.entries()].find(([root]) =>
areEquivalentPaths(root, cwd),
)?.[1];
@@ -398,6 +405,18 @@ class ObservedPlacements {
}
}
/** Projects `a`, `b` and `c`, each rooted at `repo-<name>` with its own worktrees. */
function threeProjects(worktreeCount: number): ProjectSpec[] {
return ["a", "b", "c"].map((name) => ({
id: `project-${name}`,
root: `repo-${name}`,
workspaces: Array.from({ length: worktreeCount }, (_, index) => ({
id: `${name}${index + 1}`,
cwd: `repo-${name}/worktree-${index + 1}`,
})),
}));
}
describe("observed workspace placement", () => {
test("installs and publishes a new project before add resolves without Git feedback", async () => {
const observed = new ObservedPlacements([]);
@@ -462,6 +481,118 @@ describe("observed workspace placement", () => {
observed.dispose();
});
test("reads only the workspaces of the project whose Git directory changed", async () => {
const observed = new ObservedPlacements(threeProjects(3));
await observed.start();
observed.change("repo-b", ".git");
await observed.advanceBy(DEBOUNCE_MS);
expect(observed.takeCheckoutReads()).toEqual([
"repo-b",
"repo-b/worktree-1",
"repo-b/worktree-2",
"repo-b/worktree-3",
]);
observed.dispose();
});
test("updates nested projects and workspaces when a parent directory becomes a Git repository", async () => {
const observed = new ObservedPlacements([
{ id: "parent", root: "repo", workspaces: [{ id: "parent-ws", cwd: "repo" }] },
{ id: "nested", root: "repo/sub", workspaces: [{ id: "nested-ws", cwd: "repo/sub" }] },
{ id: "outside", root: "outside", workspaces: [{ id: "attached-ws", cwd: "repo/sub" }] },
{ id: "unrelated", root: "repo-other" },
]);
await observed.start();
try {
observed.makeProjectGit("parent");
observed.makeProjectGit("nested");
observed.change("repo", ".git");
await observed.advanceBy(DEBOUNCE_MS);
expect(observed.projectUpdates).toContainEqual({
kind: "upsert",
project: expect.objectContaining({ projectId: "nested", kind: "git" }),
});
expect(await observed.placement("nested-ws")).toMatchObject({ kind: "local_checkout" });
expect(await observed.placement("attached-ws")).toMatchObject({ kind: "local_checkout" });
expect(observed.workspaceBatches.map((batch) => batch.sort())).toEqual([
["attached-ws", "nested-ws", "parent-ws"],
]);
expect(observed.takeCheckoutReads()).toEqual(["outside", "repo", "repo/sub"]);
} finally {
observed.dispose();
}
});
test("turns Git changes under several roots into one read per changed root", async () => {
const observed = new ObservedPlacements(threeProjects(1));
await observed.start();
for (const root of ["repo-a", "repo-c", "repo-a", "repo-c", "repo-a"]) {
observed.change(root, ".git");
}
await observed.advanceBy(DEBOUNCE_MS);
expect(observed.takeCheckoutReads()).toEqual([
"repo-a",
"repo-a/worktree-1",
"repo-c",
"repo-c/worktree-1",
]);
observed.dispose();
});
test("a change that lands during a pass queues a pass for only that root", async () => {
const observed = new ObservedPlacements(threeProjects(1));
await observed.start();
observed.makeProjectGit("project-a");
observed.makeProjectGit("project-b");
const firstPassRead = observed.holdNextReconciliation();
const firstBatch = observed.waitForWorkspaceBatch();
const secondBatch = firstBatch.then(() => observed.waitForWorkspaceBatch());
observed.change("repo-a", ".git");
const firstPass = observed.advanceBy(DEBOUNCE_MS);
await firstPassRead.started;
observed.change("repo-b", ".git");
observed.change("repo-b", ".git");
await observed.advanceBy(DEBOUNCE_MS);
firstPassRead.release();
await firstPass;
await secondBatch;
expect(observed.workspaceBatches).toEqual([["a1"], ["b1"]]);
expect(observed.takeCheckoutReads()).toEqual([
"repo-a",
"repo-a/worktree-1",
"repo-b",
"repo-b/worktree-1",
]);
observed.dispose();
});
test("keeps the changed roots of a failed pass for the next one", async () => {
const observed = new ObservedPlacements([
{ id: "project-a", root: "repo-a", workspaces: [{ id: "a1", cwd: "repo-a" }] },
{ id: "project-b", root: "repo-b", workspaces: [{ id: "b1", cwd: "repo-b" }] },
]);
await observed.start();
observed.makeProjectGit("project-a");
observed.failNextReconciliation(new Error("registry unavailable"));
observed.change("repo-a", ".git");
await observed.advanceBy(DEBOUNCE_MS);
observed.change("repo-b", ".git");
await observed.advanceBy(DEBOUNCE_MS);
expect(observed.takeCheckoutReads()).toEqual(["repo-a", "repo-b"]);
expect((await observed.placement("a1"))?.kind).toBe("local_checkout");
observed.dispose();
});
test("recovers errored and temporarily unavailable watchers on the periodic pass", async () => {
const observed = new ObservedPlacements([
{ id: "project-errored", root: "errored" },
@@ -11,7 +11,7 @@ import type {
PersistedWorkspaceRecord,
} from "./workspace-registry.js";
import type { WorkspaceGitService } from "./workspace-git-service.js";
import { areEquivalentPaths } from "../utils/path.js";
import { areEquivalentPaths, isPathInsideRoot } from "../utils/path.js";
import {
deriveProjectKind,
reconcileWorkspacePlacement,
@@ -151,6 +151,9 @@ export class WorkspaceReconciliationService {
private disposed = false;
private started = false;
private reconciling = false;
// Project roots whose `.git` changed since the last observed pass. A metadata
// pass reads only these; the periodic full pass covers everything else.
private readonly changedRoots = new Set<string>();
private reconcileQueuedMode: "metadata" | "full" | null = null;
constructor(options: WorkspaceReconciliationServiceOptions) {
@@ -211,17 +214,34 @@ export class WorkspaceReconciliationService {
this.watchers.length = 0;
}
/** Reconciles mutable Git facts only; never archives missing records. */
async reconcileGitMetadata(): Promise<ReconciliationResult> {
/**
* Reconciles mutable Git facts only; never archives missing records. With
* `rootPaths`, read projects and workspaces whose checkouts can change under those paths.
*/
async reconcileGitMetadata(options?: { rootPaths?: string[] }): Promise<ReconciliationResult> {
const start = Date.now();
const changes: ReconciliationChange[] = [];
const [projects, workspaces] = await Promise.all([
const [allProjects, workspaces] = await Promise.all([
this.projectRegistry.list(),
this.workspaceRegistry.listActive(),
]);
const rootPaths = options?.rootPaths;
const isAffectedDirectory = (cwd: string) =>
rootPaths?.some((rootPath) => isPathInsideRoot(rootPath, cwd)) ?? true;
// A nested project can gain or lose its Git checkout when a parent .git changes.
const affectedProjectIds = new Set(
allProjects
.filter((project) => !project.archivedAt && isAffectedDirectory(project.rootPath))
.map((project) => project.projectId),
);
// An explicitly chosen project can own a workspace outside its root.
const workspacesByProject = new Map<string, PersistedWorkspaceRecord[]>();
const workspaceStates = await mapBounded(
workspaces.filter((w) => !w.archivedAt),
workspaces.filter(
(workspace) =>
!workspace.archivedAt &&
(affectedProjectIds.has(workspace.projectId) || isAffectedDirectory(workspace.cwd)),
),
async (workspace) => ({ workspace, state: await this.inspectDirectory(workspace.cwd) }),
);
for (const { workspace, state } of workspaceStates) {
@@ -232,7 +252,11 @@ export class WorkspaceReconciliationService {
workspacesByProject.set(workspace.projectId, siblings);
}
const projectStates = await mapBounded(
projects.filter((p) => !p.archivedAt),
allProjects.filter(
(project) =>
!project.archivedAt &&
(affectedProjectIds.has(project.projectId) || workspacesByProject.has(project.projectId)),
),
async (project) => ({ project, state: await this.inspectDirectory(project.rootPath) }),
);
await this.reconcileGitMetadataForProjects(
@@ -496,6 +520,7 @@ export class WorkspaceReconciliationService {
{ recursive: false },
(_event, filename) => {
if (filename === null || filename.toString() === ".git") {
this.changedRoots.add(project.rootPath);
this.scheduleObservedReconciliation();
}
},
@@ -539,28 +564,20 @@ export class WorkspaceReconciliationService {
}
return;
}
// Take the roots that changed so far. Events arriving during this pass
// land in a fresh set and queue one more pass for just those roots.
const rootPaths = [...this.changedRoots];
this.changedRoots.clear();
if (mode === "metadata" && rootPaths.length === 0) return;
this.reconciling = true;
try {
await this.syncProjectRootWatches();
const result = mode === "full" ? await this.runOnce() : await this.reconcileGitMetadata();
const workspaceIds = new Set<string>();
const projectIds = new Set<string>();
for (const change of result.changesApplied) {
if (change.kind === "workspace_updated" || change.kind === "workspace_archived") {
workspaceIds.add(change.workspaceId);
}
if (change.kind === "project_updated") projectIds.add(change.projectId);
}
if (projectIds.size > 0) {
const workspaces = await this.workspaceRegistry.listActive();
for (const workspaceId of workspaceIdsForProjects(workspaces, projectIds)) {
workspaceIds.add(workspaceId);
}
}
if (!this.disposed && workspaceIds.size > 0) {
await this.onWorkspacesChanged?.(Array.from(workspaceIds));
}
const result =
mode === "full" ? await this.runOnce() : await this.reconcileGitMetadata({ rootPaths });
await this.publishChangedWorkspaces(result);
} catch (error) {
// A failed pass keeps its roots pending for the next pass.
for (const rootPath of rootPaths) this.changedRoots.add(rootPath);
if (!this.disposed) {
this.logger.warn({ err: error }, "Workspace reconciliation failed");
}
@@ -574,6 +591,26 @@ export class WorkspaceReconciliationService {
}
}
private async publishChangedWorkspaces(result: ReconciliationResult): Promise<void> {
const workspaceIds = new Set<string>();
const projectIds = new Set<string>();
for (const change of result.changesApplied) {
if (change.kind === "workspace_updated" || change.kind === "workspace_archived") {
workspaceIds.add(change.workspaceId);
}
if (change.kind === "project_updated") projectIds.add(change.projectId);
}
if (projectIds.size > 0) {
const workspaces = await this.workspaceRegistry.listActive();
for (const workspaceId of workspaceIdsForProjects(workspaces, projectIds)) {
workspaceIds.add(workspaceId);
}
}
if (!this.disposed && workspaceIds.size > 0) {
await this.onWorkspacesChanged?.(Array.from(workspaceIds));
}
}
private async readCheckout(cwd: string): Promise<ProjectCheckoutLitePayload> {
if (!this.workspaceGitService) {
return {
@@ -0,0 +1,88 @@
import { execFileSync } from "node:child_process";
import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
import { realpath } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { getCheckoutIdentity, getCheckoutStatus } from "./checkout-git.js";
import { createWorktree } from "./worktree.js";
import { startGitCommandMetrics, stopGitCommandMetrics } from "./run-git-command.js";
function git(cwd: string, ...args: string[]): void {
execFileSync("git", ["-c", "commit.gpgsign=false", ...args], { cwd, stdio: "ignore" });
}
describe("getCheckoutIdentity", () => {
let tempDir: string;
let paseoHome: string;
let repoDir: string;
let linkedDir: string;
let plainDir: string;
beforeEach(() => {
tempDir = realpathSync(mkdtempSync(join(tmpdir(), "checkout-identity-")));
paseoHome = join(tempDir, "paseo-home");
repoDir = join(tempDir, "repo");
linkedDir = join(tempDir, "linked");
plainDir = join(tempDir, "plain");
mkdirSync(paseoHome);
mkdirSync(repoDir);
mkdirSync(plainDir);
git(repoDir, "init", "-b", "main");
git(repoDir, "config", "user.email", "test@test.com");
git(repoDir, "config", "user.name", "Test");
writeFileSync(join(repoDir, "tracked.txt"), "tracked\n");
git(repoDir, "add", ".");
git(repoDir, "commit", "-m", "initial");
git(repoDir, "remote", "add", "origin", "https://github.com/acme/widgets.git");
git(repoDir, "worktree", "add", "-b", "feature", linkedDir);
});
afterEach(() => {
rmSync(tempDir, { recursive: true, force: true });
});
it("reports the same identity as the full status for a checkout, linked and Paseo worktrees and a plain folder", async () => {
const paseoWorktree = await createWorktree({
cwd: repoDir,
worktreeSlug: "alpha",
source: { kind: "branch-off", baseBranch: "main", branchName: "alpha" },
paseoHome,
});
for (const cwd of [repoDir, linkedDir, paseoWorktree.worktreePath]) {
const status = await getCheckoutStatus(cwd, { paseoHome });
const identity = await getCheckoutIdentity(cwd, { paseoHome });
if (!status.isGit) throw new Error(`${cwd} should be a git checkout`);
expect(identity).toEqual({
isGit: true,
repoRoot: status.repoRoot,
mainRepoRoot: status.mainRepoRoot,
currentBranch: status.currentBranch,
remoteUrl: status.remoteUrl,
isPaseoOwnedWorktree: status.isPaseoOwnedWorktree,
});
}
const mainRepoRoot = await realpath(repoDir);
expect(await getCheckoutIdentity(linkedDir, { paseoHome })).toMatchObject({
currentBranch: "feature",
mainRepoRoot,
});
expect(await getCheckoutIdentity(paseoWorktree.worktreePath, { paseoHome })).toMatchObject({
isPaseoOwnedWorktree: true,
mainRepoRoot,
});
expect(await getCheckoutIdentity(plainDir, { paseoHome })).toEqual({ isGit: false });
});
it("never scans the working tree or compares commits", async () => {
startGitCommandMetrics();
await getCheckoutIdentity(repoDir, { paseoHome });
await getCheckoutIdentity(linkedDir, { paseoHome });
const verbs = stopGitCommandMetrics().commands.map((command) => command.args[0]);
expect(verbs.length).toBeGreaterThan(0);
expect(
verbs.filter((verb) => ["status", "ls-files", "rev-list", "diff"].includes(verb)),
).toEqual([]);
});
});
+54
View File
@@ -2406,6 +2406,60 @@ async function getUntrackedDiffText(
};
}
export type CheckoutIdentity =
| { isGit: false }
| {
isGit: true;
repoRoot: string;
mainRepoRoot: string | null;
currentBranch: string | null;
remoteUrl: string | null;
isPaseoOwnedWorktree: boolean;
};
/**
* What a checkout is, without the state of its files. Reports the same identity fields as
* `getCheckoutStatus` but never scans the working tree (`status`), compares against a base, or
* counts commits, so reading many checkouts in the background stays cheap.
*/
export async function getCheckoutIdentity(
cwd: string,
context?: CheckoutContext,
): Promise<CheckoutIdentity> {
const inspected = await inspectCheckoutContext(cwd, context);
if (!inspected) {
return { isGit: false };
}
const { worktreeRoot, currentBranch, remoteUrl, paseoWorktree } = inspected;
const mainRepoRoot = await getMainRepoRootFromCommonDir(
cwd,
inspected.gitCommonDir,
context,
).catch(() => null);
// `getCheckoutStatus` reports a worktree as Paseo-owned only when it also resolves a base.
const isPaseoOwnedWorktree =
paseoWorktree.isPaseoOwnedWorktree &&
Boolean(
storedBaseRefFromMetadata(await readPaseoWorktreeMetadata(worktreeRoot)) ??
(await resolveBaseRef(cwd, context)),
);
const isLinkedCheckout = mainRepoRoot !== null && resolve(mainRepoRoot) !== resolve(worktreeRoot);
let reportedMainRepoRoot: string | null = null;
if (isPaseoOwnedWorktree) {
reportedMainRepoRoot = mainRepoRoot ?? worktreeRoot;
} else if (isLinkedCheckout) {
reportedMainRepoRoot = mainRepoRoot;
}
return {
isGit: true,
repoRoot: worktreeRoot,
mainRepoRoot: reportedMainRepoRoot,
currentBranch,
remoteUrl,
isPaseoOwnedWorktree,
};
}
export async function getCheckoutStatus(
cwd: string,
context?: CheckoutContext,