@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/server/workspace-reconciliation-service.d.ts

@@ -0,0 +1,103 @@
+import type pino from "pino";
+import type { ProjectRegistry, WorkspaceRegistry, PersistedProjectRecord } from "./workspace-registry.js";
+import type { WorkspaceGitService } from "./workspace-git-service.js";
+import { type MutableWorkspacePlacement } from "./workspace-registry-model.js";
+export type ProjectUpdate = {
+    kind: "upsert";
+    project: PersistedProjectRecord;
+} | {
+    kind: "remove";
+    projectId: string;
+};
+interface ProjectRootWatcher {
+    close(): void;
+}
+export interface ProjectRootWatch {
+    (rootPath: string, options: {
+        recursive: false;
+    }, onChange: (event: string, filename: string | Buffer | null) => void, onError: (error: Error) => void): ProjectRootWatcher;
+}
+export interface ReconciliationTimer {
+    unref?(): void;
+}
+export interface ReconciliationClock {
+    setTimeout(callback: () => void | Promise<void>, delayMs: number): ReconciliationTimer;
+    clearTimeout(timer: ReconciliationTimer): void;
+    setInterval(callback: () => void | Promise<void>, delayMs: number): ReconciliationTimer;
+    clearInterval(timer: ReconciliationTimer): void;
+}
+export type ReconciliationChange = {
+    kind: "workspace_archived";
+    workspaceId: string;
+    directory: string;
+    reason: string;
+} | {
+    kind: "project_updated";
+    projectId: string;
+    directory: string;
+    fields: Partial<Pick<PersistedProjectRecord, "kind" | "projectKey">>;
+} | {
+    kind: "workspace_updated";
+    workspaceId: string;
+    directory: string;
+    fields: Partial<MutableWorkspacePlacement>;
+};
+export interface ReconciliationResult {
+    changesApplied: ReconciliationChange[];
+    durationMs: number;
+}
+export interface WorkspaceReconciliationServiceOptions {
+    serverId?: string;
+    projectRegistry: ProjectRegistry;
+    workspaceRegistry: WorkspaceRegistry;
+    logger: pino.Logger;
+    onChanges?: (changes: ReconciliationChange[]) => void;
+    workspaceGitService?: Pick<WorkspaceGitService, "getCheckout">;
+    onProjectUpdate?: (update: ProjectUpdate) => void;
+    onWorkspaceArchived?: (workspaceId: string) => void | Promise<void>;
+    onWorkspacesChanged?: (workspaceIds: string[]) => Promise<void>;
+    watchProjectRoot?: ProjectRootWatch;
+    clock?: ReconciliationClock;
+    rescanIntervalMs?: number;
+    debounceMs?: number;
+}
+export declare class WorkspaceReconciliationService {
+    private readonly serverId;
+    private readonly projectRegistry;
+    private readonly workspaceRegistry;
+    private readonly logger;
+    private readonly onChanges;
+    private readonly workspaceGitService;
+    private readonly onProjectUpdate;
+    private readonly onWorkspaceArchived;
+    private readonly onWorkspacesChanged;
+    private readonly watchProjectRoot;
+    private readonly clock;
+    private readonly rescanIntervalMs;
+    private readonly debounceMs;
+    private readonly watchers;
+    private unsubscribeRegistry;
+    private rescanTimer;
+    private debounceTimer;
+    private disposed;
+    private started;
+    private reconciling;
+    private reconcileQueuedMode;
+    constructor(options: WorkspaceReconciliationServiceOptions);
+    start(): Promise<void>;
+    dispose(): void;
+    /** Reconciles mutable Git facts only; never archives missing records. */
+    reconcileGitMetadata(): Promise<ReconciliationResult>;
+    runOnce(): Promise<ReconciliationResult>;
+    /** Runs the boot-time availability-safe pass and publishes every affected workspace. */
+    reconcileNow(): Promise<void>;
+    private reconcileGitMetadataForProjects;
+    private reconcileProject;
+    private syncProjectRootWatches;
+    private scheduleObservedReconciliation;
+    private reconcileObservedGitMetadata;
+    private readCheckout;
+    private inspectDirectory;
+}
+export {};
+//# sourceMappingURL=workspace-reconciliation-service.d.ts.map

package/dist/server/server/workspace-reconciliation-service.js

@@ -0,0 +1,379 @@
+import { statSync, watch as watchPath } from "node:fs";
+import { areEquivalentPaths } from "../utils/path.js";
+import { deriveProjectKind, reconcileWorkspacePlacement, } from "./workspace-registry-model.js";
+import { workspaceIdsForProjects } from "./workspace-directory.js";
+import { deriveProjectKey } from "./project-key.js";
+const DEFAULT_RESCAN_INTERVAL_MS = 5 * 60000;
+const DEFAULT_DEBOUNCE_MS = 100;
+const systemClock = {
+    setTimeout: (callback, delayMs) => setTimeout(() => void callback(), delayMs),
+    clearTimeout: (timer) => clearTimeout(timer),
+    setInterval: (callback, delayMs) => setInterval(() => void callback(), delayMs),
+    clearInterval: (timer) => clearInterval(timer),
+};
+const watchProjectRoot = (rootPath, options, onChange, onError) => {
+    const watcher = watchPath(rootPath, options, onChange);
+    watcher.on("error", onError);
+    return watcher;
+};
+export class WorkspaceReconciliationService {
+    constructor(options) {
+        this.watchers = [];
+        this.unsubscribeRegistry = null;
+        this.rescanTimer = null;
+        this.debounceTimer = null;
+        this.disposed = false;
+        this.started = false;
+        this.reconciling = false;
+        this.reconcileQueuedMode = null;
+        this.serverId = options.serverId;
+        this.projectRegistry = options.projectRegistry;
+        this.workspaceRegistry = options.workspaceRegistry;
+        this.logger = options.logger.child({ module: "workspace-reconciliation" });
+        this.onChanges = options.onChanges ?? null;
+        this.workspaceGitService = options.workspaceGitService ?? null;
+        this.onProjectUpdate = options.onProjectUpdate ?? null;
+        this.onWorkspaceArchived = options.onWorkspaceArchived ?? null;
+        this.onWorkspacesChanged = options.onWorkspacesChanged ?? null;
+        this.watchProjectRoot = options.watchProjectRoot ?? watchProjectRoot;
+        this.clock = options.clock ?? systemClock;
+        this.rescanIntervalMs = options.rescanIntervalMs ?? DEFAULT_RESCAN_INTERVAL_MS;
+        this.debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.unsubscribeRegistry =
+            this.projectRegistry.subscribeToMutations?.(async (mutation) => {
+                try {
+                    // Project creation does not resolve until its root watch is installed,
+                    // closing the git-init race for newly added empty projects.
+                    await this.syncProjectRootWatches();
+                    if (this.disposed)
+                        return;
+                    if (mutation.kind === "upsert" && mutation.project && !mutation.project.archivedAt) {
+                        this.onProjectUpdate?.({ kind: "upsert", project: mutation.project });
+                    }
+                    else {
+                        this.onProjectUpdate?.({ kind: "remove", projectId: mutation.projectId });
+                    }
+                }
+                catch (error) {
+                    this.logger.warn({ err: error }, "Project reconciliation mutation handling failed");
+                }
+            }) ?? null;
+        await this.syncProjectRootWatches();
+        this.rescanTimer = this.clock.setInterval(() => this.reconcileObservedGitMetadata("full"), this.rescanIntervalMs);
+        this.rescanTimer.unref?.();
+    }
+    dispose() {
+        this.disposed = true;
+        this.unsubscribeRegistry?.();
+        this.unsubscribeRegistry = null;
+        if (this.rescanTimer)
+            this.clock.clearInterval(this.rescanTimer);
+        if (this.debounceTimer)
+            this.clock.clearTimeout(this.debounceTimer);
+        for (const { watcher } of this.watchers)
+            watcher.close();
+        this.watchers.length = 0;
+    }
+    /** Reconciles mutable Git facts only; never archives missing records. */
+    async reconcileGitMetadata() {
+        const start = Date.now();
+        const changes = [];
+        const [projects, workspaces] = await Promise.all([
+            this.projectRegistry.list(),
+            this.workspaceRegistry.list(),
+        ]);
+        const workspacesByProject = new Map();
+        for (const workspace of workspaces) {
+            if (workspace.archivedAt || this.inspectDirectory(workspace.cwd) !== "directory")
+                continue;
+            const siblings = workspacesByProject.get(workspace.projectId) ?? [];
+            siblings.push(workspace);
+            workspacesByProject.set(workspace.projectId, siblings);
+        }
+        await this.reconcileGitMetadataForProjects(projects.filter((project) => !project.archivedAt && this.inspectDirectory(project.rootPath) === "directory"), workspacesByProject, changes);
+        if (changes.length > 0)
+            this.onChanges?.(changes);
+        return { changesApplied: changes, durationMs: Date.now() - start };
+    }
+    async runOnce() {
+        const start = Date.now();
+        const changes = [];
+        const allProjects = await this.projectRegistry.list();
+        const allWorkspaces = await this.workspaceRegistry.list();
+        const activeProjects = allProjects.filter((p) => !p.archivedAt);
+        const activeWorkspaces = allWorkspaces.filter((w) => !w.archivedAt);
+        const workspaceDirectoryStates = activeWorkspaces.map((workspace) => ({
+            workspace,
+            state: this.inspectDirectory(workspace.cwd),
+        }));
+        const workspacesByProject = new Map();
+        for (const { workspace, state } of workspaceDirectoryStates) {
+            if (state !== "directory")
+                continue;
+            const list = workspacesByProject.get(workspace.projectId) ?? [];
+            list.push(workspace);
+            workspacesByProject.set(workspace.projectId, list);
+        }
+        // 1. Archive workspaces whose directories no longer exist
+        const missingWorkspaces = workspaceDirectoryStates
+            .filter(({ state }) => state === "missing")
+            .map(({ workspace }) => workspace);
+        await Promise.all(missingWorkspaces.map(async (workspace) => {
+            const timestamp = new Date().toISOString();
+            await this.workspaceRegistry.archive(workspace.workspaceId, timestamp);
+            await this.onWorkspaceArchived?.(workspace.workspaceId);
+            changes.push({
+                kind: "workspace_archived",
+                workspaceId: workspace.workspaceId,
+                directory: workspace.cwd,
+                reason: "directory_missing",
+            });
+            // Update the in-memory list for the project orphan check below
+            const siblings = workspacesByProject.get(workspace.projectId);
+            if (siblings) {
+                const updated = siblings.filter((w) => w.workspaceId !== workspace.workspaceId);
+                workspacesByProject.set(workspace.projectId, updated);
+            }
+        }));
+        // 2. Reconcile mutable git metadata without changing identity or membership.
+        //    Projects persist until explicitly removed, even when they currently have
+        //    zero active workspaces, so they still reconcile their own metadata.
+        await this.reconcileGitMetadataForProjects(activeProjects.filter((project) => this.inspectDirectory(project.rootPath) === "directory"), workspacesByProject, changes);
+        if (changes.length > 0 && this.onChanges) {
+            this.onChanges(changes);
+        }
+        const result = { changesApplied: changes, durationMs: Date.now() - start };
+        if (changes.length > 0) {
+            this.logger.info({ changeCount: changes.length, durationMs: result.durationMs, changes }, "Workspace reconciliation applied changes");
+        }
+        return result;
+    }
+    /** Runs the boot-time availability-safe pass and publishes every affected workspace. */
+    async reconcileNow() {
+        await this.reconcileObservedGitMetadata("metadata");
+    }
+    async reconcileGitMetadataForProjects(projectsToReconcile, workspacesByProject, changes) {
+        const checkoutReads = [];
+        const readCheckout = (cwd) => {
+            const existing = checkoutReads.find((read) => areEquivalentPaths(read.cwd, cwd));
+            if (existing)
+                return existing.checkout;
+            const checkout = this.readCheckout(cwd);
+            checkoutReads.push({ cwd, checkout });
+            return checkout;
+        };
+        const roots = [];
+        for (const project of projectsToReconcile) {
+            const root = roots.find((candidate) => areEquivalentPaths(candidate.rootPath, project.rootPath));
+            if (root)
+                root.projects.push(project);
+            else
+                roots.push({ rootPath: project.rootPath, projects: [project] });
+        }
+        await Promise.all(roots.map(async ({ rootPath, projects }) => {
+            try {
+                const rootGit = await readCheckout(rootPath);
+                await Promise.all(projects.map((project) => this.reconcileProject({
+                    project,
+                    siblings: workspacesByProject.get(project.projectId) ?? [],
+                    currentGit: rootGit,
+                    readCheckout,
+                    changes,
+                })));
+            }
+            catch (error) {
+                this.logger.warn({ err: error, rootPath }, "Skipped workspace reconciliation after Git read failed");
+            }
+        }));
+    }
+    async reconcileProject(input) {
+        const { project, siblings, currentGit, readCheckout, changes } = input;
+        const workspaceCheckouts = await Promise.all(siblings.map(async (workspace) => ({
+            workspace,
+            checkout: await readCheckout(workspace.cwd),
+        })));
+        const projectUpdates = {};
+        const mappedKind = deriveProjectKind(currentGit);
+        const projectKey = deriveProjectKey({
+            rootPath: project.rootPath,
+            remoteUrl: currentGit.remoteUrl,
+            worktreeRoot: currentGit.worktreeRoot,
+            mainRepoRoot: currentGit.mainRepoRoot,
+            serverId: this.serverId,
+        });
+        if (project.kind !== mappedKind) {
+            projectUpdates.kind = mappedKind;
+        }
+        if (project.projectKey !== projectKey) {
+            projectUpdates.projectKey = projectKey;
+        }
+        if (Object.keys(projectUpdates).length > 0) {
+            const timestamp = new Date().toISOString();
+            await this.projectRegistry.upsert({
+                ...project,
+                ...projectUpdates,
+                updatedAt: timestamp,
+            });
+            changes.push({
+                kind: "project_updated",
+                projectId: project.projectId,
+                directory: project.rootPath,
+                fields: projectUpdates,
+            });
+        }
+        await Promise.all(workspaceCheckouts.map(async ({ workspace, checkout: wsGit }) => {
+            const timestamp = new Date().toISOString();
+            const update = reconcileWorkspacePlacement({
+                workspace,
+                checkout: wsGit,
+                updatedAt: timestamp,
+            });
+            if (!update)
+                return;
+            const updated = await this.workspaceRegistry.update(workspace.workspaceId, (current) => ({
+                ...current,
+                ...update.fields,
+                updatedAt: timestamp,
+            }));
+            if (!updated)
+                return;
+            changes.push({
+                kind: "workspace_updated",
+                workspaceId: workspace.workspaceId,
+                directory: workspace.cwd,
+                fields: update.fields,
+            });
+        }));
+    }
+    async syncProjectRootWatches() {
+        if (this.disposed)
+            return;
+        const projects = await this.projectRegistry.list();
+        if (this.disposed)
+            return;
+        const activeProjects = projects.filter((project) => !project.archivedAt);
+        for (let index = this.watchers.length - 1; index >= 0; index -= 1) {
+            const target = this.watchers[index];
+            const stillActive = activeProjects.some((project) => areEquivalentPaths(project.rootPath, target.rootPath));
+            if (stillActive)
+                continue;
+            target.watcher.close();
+            this.watchers.splice(index, 1);
+        }
+        for (const project of activeProjects) {
+            const alreadyWatching = this.watchers.some((target) => areEquivalentPaths(target.rootPath, project.rootPath));
+            if (alreadyWatching)
+                continue;
+            try {
+                let watcher;
+                watcher = this.watchProjectRoot(project.rootPath, { recursive: false }, (_event, filename) => {
+                    if (filename === null || filename.toString() === ".git") {
+                        this.scheduleObservedReconciliation();
+                    }
+                }, (error) => {
+                    watcher.close();
+                    const index = this.watchers.findIndex((target) => target.watcher === watcher);
+                    if (index >= 0)
+                        this.watchers.splice(index, 1);
+                    this.logger.warn({ err: error, rootPath: project.rootPath }, "Project root watch failed");
+                });
+                this.watchers.push({ rootPath: project.rootPath, watcher });
+            }
+            catch (error) {
+                // The periodic reconciliation is the convergence path for roots that
+                // are temporarily missing or unwatchable.
+                this.logger.debug({ err: error, rootPath: project.rootPath }, "Project root is not watchable yet");
+            }
+        }
+    }
+    scheduleObservedReconciliation() {
+        if (this.disposed || this.debounceTimer)
+            return;
+        this.debounceTimer = this.clock.setTimeout(() => {
+            this.debounceTimer = null;
+            return this.reconcileObservedGitMetadata();
+        }, this.debounceMs);
+    }
+    async reconcileObservedGitMetadata(mode = "metadata") {
+        if (this.disposed)
+            return;
+        if (this.reconciling) {
+            if (mode === "full" || this.reconcileQueuedMode === null) {
+                this.reconcileQueuedMode = mode;
+            }
+            return;
+        }
+        this.reconciling = true;
+        try {
+            await this.syncProjectRootWatches();
+            const result = mode === "full" ? await this.runOnce() : await this.reconcileGitMetadata();
+            const workspaceIds = new Set();
+            const projectIds = new Set();
+            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.list();
+                for (const workspaceId of workspaceIdsForProjects(workspaces, projectIds)) {
+                    workspaceIds.add(workspaceId);
+                }
+            }
+            if (!this.disposed && workspaceIds.size > 0) {
+                await this.onWorkspacesChanged?.(Array.from(workspaceIds));
+            }
+        }
+        catch (error) {
+            if (!this.disposed) {
+                this.logger.warn({ err: error }, "Workspace reconciliation failed");
+            }
+        }
+        finally {
+            this.reconciling = false;
+            if (this.reconcileQueuedMode) {
+                const queuedMode = this.reconcileQueuedMode;
+                this.reconcileQueuedMode = null;
+                void this.reconcileObservedGitMetadata(queuedMode);
+            }
+        }
+    }
+    async readCheckout(cwd) {
+        if (!this.workspaceGitService) {
+            return {
+                cwd,
+                isGit: false,
+                currentBranch: null,
+                remoteUrl: null,
+                worktreeRoot: null,
+                isPaseoOwnedWorktree: false,
+                mainRepoRoot: null,
+            };
+        }
+        return this.workspaceGitService.getCheckout(cwd);
+    }
+    inspectDirectory(targetPath) {
+        try {
+            return statSync(targetPath).isDirectory() ? "directory" : "missing";
+        }
+        catch (error) {
+            if (isMissingPathError(error))
+                return "missing";
+            this.logger.warn({ err: error, targetPath }, "Skipped workspace reconciliation after directory inspection failed");
+            return "unreadable";
+        }
+    }
+}
+function isMissingPathError(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    return error.code === "ENOENT" || error.code === "ENOTDIR";
+}
+//# sourceMappingURL=workspace-reconciliation-service.js.map

package/dist/server/server/workspace-registry-bootstrap-legacy.d.ts

@@ -0,0 +1,21 @@
+import type { ProjectCheckoutLitePayload } from "@camerontaylor/paseo-protocol/messages";
+import { type PersistedProjectKind, type PersistedWorkspaceKind } from "./workspace-registry-model.js";
+interface DirectoryProjectMembership {
+    cwd: string;
+    checkout: ProjectCheckoutLitePayload;
+    workspaceDirectoryKey: string;
+    workspaceKind: PersistedWorkspaceKind;
+    workspaceDisplayName: string;
+    projectId: string;
+    projectKey: string;
+    projectName: string;
+    projectRootPath: string;
+    projectKind: PersistedProjectKind;
+}
+export declare function classifyDirectoryForProjectMembership(input: {
+    cwd: string;
+    checkout: ProjectCheckoutLitePayload;
+    serverId?: string;
+}): DirectoryProjectMembership;
+export {};
+//# sourceMappingURL=workspace-registry-bootstrap-legacy.d.ts.map

package/dist/server/server/workspace-registry-bootstrap-legacy.js

@@ -0,0 +1,57 @@
+import { resolve } from "node:path";
+import { parseGitRevParsePath } from "../utils/git-rev-parse-path.js";
+import { createRealpathAwarePathMatcher, getRealpathAwareRelativePath } from "../utils/path.js";
+import { deriveProjectKey, deriveProjectGroupingDisplayName } from "./project-key.js";
+import { deriveProjectKind, deriveWorkspaceDisplayName, deriveWorkspaceKind, } from "./workspace-registry-model.js";
+export function classifyDirectoryForProjectMembership(input) {
+    const cwd = resolve(input.cwd);
+    const checkout = { ...input.checkout, cwd };
+    const projectKey = deriveProjectKey({
+        rootPath: cwd,
+        remoteUrl: checkout.remoteUrl,
+        worktreeRoot: checkout.worktreeRoot,
+        mainRepoRoot: checkout.mainRepoRoot,
+        serverId: input.serverId,
+    });
+    const projectRootPath = deriveProjectRootPath({ cwd, checkout });
+    return {
+        cwd,
+        checkout,
+        workspaceDirectoryKey: deriveWorkspaceDirectoryKey(cwd, checkout),
+        workspaceKind: deriveWorkspaceKind(checkout),
+        workspaceDisplayName: deriveWorkspaceDisplayName({ cwd, checkout }),
+        // Legacy registry bootstrap historically used the grouping identity as the
+        // host-local project ID. Preserve that ID shape while keeping the new,
+        // canonical cross-host identity in projectKey.
+        projectId: projectKey.startsWith("remote:") ? projectKey : projectRootPath,
+        projectKey,
+        projectName: deriveProjectGroupingDisplayName({
+            rootPath: cwd,
+            remoteUrl: checkout.remoteUrl,
+            worktreeRoot: checkout.worktreeRoot,
+        }),
+        projectRootPath,
+        projectKind: deriveProjectKind(checkout),
+    };
+}
+function deriveWorkspaceDirectoryKey(cwd, checkout) {
+    const worktreeRoot = checkout.worktreeRoot ? parseGitRevParsePath(checkout.worktreeRoot) : null;
+    const selectedRoot = resolve(cwd);
+    return worktreeRoot && createRealpathAwarePathMatcher(worktreeRoot)(selectedRoot)
+        ? worktreeRoot
+        : selectedRoot;
+}
+function deriveProjectRootPath(input) {
+    if (!input.checkout.isGit || !input.checkout.mainRepoRoot)
+        return input.cwd;
+    const worktreeRoot = input.checkout.worktreeRoot
+        ? parseGitRevParsePath(input.checkout.worktreeRoot)
+        : null;
+    if (!worktreeRoot)
+        return input.checkout.mainRepoRoot;
+    const selectedPath = getRealpathAwareRelativePath(worktreeRoot, input.cwd);
+    return selectedPath
+        ? resolve(input.checkout.mainRepoRoot, selectedPath)
+        : input.checkout.mainRepoRoot;
+}
+//# sourceMappingURL=workspace-registry-bootstrap-legacy.js.map

package/dist/server/server/workspace-registry-bootstrap.d.ts

@@ -0,0 +1,14 @@
+import type { Logger } from "pino";
+import type { AgentStorage } from "./agent/agent-storage.js";
+import type { WorkspaceGitService } from "./workspace-git-service.js";
+import { type ProjectRegistry, type WorkspaceRegistry } from "./workspace-registry.js";
+export declare function bootstrapWorkspaceRegistries(options: {
+    serverId?: string;
+    paseoHome: string;
+    agentStorage: AgentStorage;
+    projectRegistry: ProjectRegistry;
+    workspaceRegistry: WorkspaceRegistry;
+    workspaceGitService: WorkspaceGitService;
+    logger: Logger;
+}): Promise<void>;
+//# sourceMappingURL=workspace-registry-bootstrap.d.ts.map