diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts index 20ed435d..3d559738 100644 --- a/packages/shared/src/index.ts +++ b/packages/shared/src/index.ts @@ -108,6 +108,8 @@ export type { AdapterEnvironmentTestResult, AssetImage, Project, + ProjectCodebase, + ProjectCodebaseOrigin, ProjectGoalRef, ProjectWorkspace, ExecutionWorkspace, diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts index 89b2e637..34753ec2 100644 --- a/packages/shared/src/types/index.ts +++ b/packages/shared/src/types/index.ts @@ -10,7 +10,7 @@ export type { AdapterEnvironmentTestResult, } from "./agent.js"; export type { AssetImage } from "./asset.js"; -export type { Project, ProjectGoalRef, ProjectWorkspace } from "./project.js"; +export type { Project, ProjectCodebase, ProjectCodebaseOrigin, ProjectGoalRef, ProjectWorkspace } from "./project.js"; export type { ExecutionWorkspace, WorkspaceRuntimeService, diff --git a/packages/shared/src/types/project.ts b/packages/shared/src/types/project.ts index 60d0d25f..db094609 100644 --- a/packages/shared/src/types/project.ts +++ b/packages/shared/src/types/project.ts @@ -32,6 +32,20 @@ export interface ProjectWorkspace { updatedAt: Date; } +export type ProjectCodebaseOrigin = "local_folder" | "managed_checkout"; + +export interface ProjectCodebase { + workspaceId: string | null; + repoUrl: string | null; + repoRef: string | null; + defaultRef: string | null; + repoName: string | null; + localFolder: string | null; + managedFolder: string; + effectiveLocalFolder: string; + origin: ProjectCodebaseOrigin; +} + export interface Project { id: string; companyId: string; @@ -47,6 +61,7 @@ export interface Project { targetDate: string | null; color: string | null; executionWorkspacePolicy: ProjectExecutionWorkspacePolicy | null; + codebase: ProjectCodebase; workspaces: ProjectWorkspace[]; primaryWorkspace: ProjectWorkspace | null; archivedAt: Date | null; diff --git a/server/src/home-paths.ts b/server/src/home-paths.ts index d2b7e53a..f1174bbb 100644 --- a/server/src/home-paths.ts +++ b/server/src/home-paths.ts @@ -4,6 +4,7 @@ import path from "node:path"; const DEFAULT_INSTANCE_ID = "default"; const INSTANCE_ID_RE = /^[a-zA-Z0-9_-]+$/; const PATH_SEGMENT_RE = /^[a-zA-Z0-9_-]+$/; +const FRIENDLY_PATH_SEGMENT_RE = /[^a-zA-Z0-9._-]+/g; function expandHomePrefix(value: string): string { if (value === "~") return os.homedir(); @@ -61,6 +62,34 @@ export function resolveDefaultAgentWorkspaceDir(agentId: string): string { return path.resolve(resolvePaperclipInstanceRoot(), "workspaces", trimmed); } +function sanitizeFriendlyPathSegment(value: string | null | undefined, fallback = "_default"): string { + const trimmed = value?.trim() ?? ""; + if (!trimmed) return fallback; + const sanitized = trimmed + .replace(FRIENDLY_PATH_SEGMENT_RE, "-") + .replace(/^-+|-+$/g, ""); + return sanitized || fallback; +} + +export function resolveManagedProjectWorkspaceDir(input: { + companyId: string; + projectId: string; + repoName?: string | null; +}): string { + const companyId = input.companyId.trim(); + const projectId = input.projectId.trim(); + if (!companyId || !projectId) { + throw new Error("Managed project workspace path requires companyId and projectId."); + } + return path.resolve( + resolvePaperclipInstanceRoot(), + "projects", + sanitizeFriendlyPathSegment(companyId, "company"), + sanitizeFriendlyPathSegment(projectId, "project"), + sanitizeFriendlyPathSegment(input.repoName, "_default"), + ); +} + export function resolveHomeAwarePath(value: string): string { return path.resolve(expandHomePrefix(value)); } diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.ts index fc4ebcfe..19277673 100644 --- a/server/src/services/heartbeat.ts +++ b/server/src/services/heartbeat.ts @@ -1,5 +1,7 @@ import fs from "node:fs/promises"; import path from "node:path"; +import { execFile as execFileCallback } from "node:child_process"; +import { promisify } from "node:util"; import { and, asc, desc, eq, gt, inArray, sql } from "drizzle-orm"; import type { Db } from "@paperclipai/db"; import { @@ -23,7 +25,7 @@ import { createLocalAgentJwt } from "../agent-auth-jwt.js"; import { parseObject, asBoolean, asNumber, appendWithCap, MAX_EXCERPT_BYTES } from "../adapters/utils.js"; import { costService } from "./costs.js"; import { secretService } from "./secrets.js"; -import { resolveDefaultAgentWorkspaceDir } from "../home-paths.js"; +import { resolveDefaultAgentWorkspaceDir, resolveManagedProjectWorkspaceDir } from "../home-paths.js"; import { summarizeHeartbeatRunResultJson } from "./heartbeat-run-summary.js"; import { buildWorkspaceReadyComment, @@ -48,6 +50,7 @@ const HEARTBEAT_MAX_CONCURRENT_RUNS_MAX = 10; const DEFERRED_WAKE_CONTEXT_KEY = "_paperclipWakeContext"; const startLocksByAgent = new Map>(); const REPO_ONLY_CWD_SENTINEL = "/__paperclip_repo_only__"; +const execFile = promisify(execFileCallback); const SESSIONED_LOCAL_ADAPTERS = new Set([ "claude_local", "codex_local", @@ -57,6 +60,69 @@ const SESSIONED_LOCAL_ADAPTERS = new Set([ "pi_local", ]); +function deriveRepoNameFromRepoUrl(repoUrl: string | null): string | null { + const trimmed = repoUrl?.trim() ?? ""; + if (!trimmed) return null; + try { + const parsed = new URL(trimmed); + const cleanedPath = parsed.pathname.replace(/\/+$/, ""); + const repoName = cleanedPath.split("/").filter(Boolean).pop()?.replace(/\.git$/i, "") ?? ""; + return repoName || null; + } catch { + return null; + } +} + +async function ensureManagedProjectWorkspace(input: { + companyId: string; + projectId: string; + repoUrl: string | null; +}): Promise<{ cwd: string; warning: string | null }> { + const cwd = resolveManagedProjectWorkspaceDir({ + companyId: input.companyId, + projectId: input.projectId, + repoName: deriveRepoNameFromRepoUrl(input.repoUrl), + }); + await fs.mkdir(path.dirname(cwd), { recursive: true }); + const stats = await fs.stat(cwd).catch(() => null); + + if (!input.repoUrl) { + if (!stats) { + await fs.mkdir(cwd, { recursive: true }); + } + return { cwd, warning: null }; + } + + const gitDirExists = await fs + .stat(path.resolve(cwd, ".git")) + .then((entry) => entry.isDirectory()) + .catch(() => false); + if (gitDirExists) { + return { cwd, warning: null }; + } + + if (stats) { + const entries = await fs.readdir(cwd).catch(() => []); + if (entries.length > 0) { + return { + cwd, + warning: `Managed workspace path "${cwd}" already exists but is not a git checkout. Using it as-is.`, + }; + } + await fs.rm(cwd, { recursive: true, force: true }); + } + + try { + await execFile("git", ["clone", input.repoUrl, cwd], { + env: process.env, + }); + return { cwd, warning: null }; + } catch (error) { + const reason = error instanceof Error ? error.message : String(error); + throw new Error(`Failed to prepare managed checkout for "${input.repoUrl}" at "${cwd}": ${reason}`); + } +} + const heartbeatRunListColumns = { id: heartbeatRuns.id, companyId: heartbeatRuns.companyId, @@ -876,12 +942,23 @@ export function heartbeatService(db: Db) { `Selected project workspace "${preferredProjectWorkspaceId}" is not available on this project.`; } for (const workspace of projectWorkspaceRows) { - const projectCwd = readNonEmptyString(workspace.cwd); + let projectCwd = readNonEmptyString(workspace.cwd); + let managedWorkspaceWarning: string | null = null; if (!projectCwd || projectCwd === REPO_ONLY_CWD_SENTINEL) { - if (preferredWorkspace?.id === workspace.id) { - preferredWorkspaceWarning = `Selected project workspace "${workspace.name}" has no local cwd configured.`; + try { + const managedWorkspace = await ensureManagedProjectWorkspace({ + companyId: agent.companyId, + projectId: workspaceProjectId ?? resolvedProjectId ?? workspace.projectId, + repoUrl: readNonEmptyString(workspace.repoUrl), + }); + projectCwd = managedWorkspace.cwd; + managedWorkspaceWarning = managedWorkspace.warning; + } catch (error) { + if (preferredWorkspace?.id === workspace.id) { + preferredWorkspaceWarning = error instanceof Error ? error.message : String(error); + } + continue; } - continue; } hasConfiguredProjectCwd = true; const projectCwdExists = await fs @@ -897,7 +974,9 @@ export function heartbeatService(db: Db) { repoUrl: workspace.repoUrl, repoRef: workspace.repoRef, workspaceHints, - warnings: preferredWorkspaceWarning ? [preferredWorkspaceWarning] : [], + warnings: [preferredWorkspaceWarning, managedWorkspaceWarning].filter( + (value): value is string => Boolean(value), + ), }; } if (preferredWorkspace?.id === workspace.id) { @@ -938,6 +1017,24 @@ export function heartbeatService(db: Db) { }; } + if (workspaceProjectId) { + const managedWorkspace = await ensureManagedProjectWorkspace({ + companyId: agent.companyId, + projectId: workspaceProjectId, + repoUrl: null, + }); + return { + cwd: managedWorkspace.cwd, + source: "project_primary" as const, + projectId: resolvedProjectId, + workspaceId: null, + repoUrl: null, + repoRef: null, + workspaceHints, + warnings: managedWorkspace.warning ? [managedWorkspace.warning] : [], + }; + } + const sessionCwd = readNonEmptyString(previousSessionParams?.cwd); if (sessionCwd) { const sessionCwdExists = await fs diff --git a/server/src/services/plugin-host-services.ts b/server/src/services/plugin-host-services.ts index 6be022e2..0f7ff985 100644 --- a/server/src/services/plugin-host-services.ts +++ b/server/src/services/plugin-host-services.ts @@ -704,17 +704,16 @@ export function buildHostServices( const project = await projects.getById(params.projectId); if (!inCompany(project, companyId)) return null; const row = project.primaryWorkspace; - if (!row) return null; - const path = sanitizeWorkspacePath(row.cwd); - const name = sanitizeWorkspaceName(row.name, path); + const path = sanitizeWorkspacePath(project.codebase.effectiveLocalFolder); + const name = sanitizeWorkspaceName(row?.name ?? project.name, path); return { - id: row.id, - projectId: row.projectId, + id: row?.id ?? `${project.id}:managed`, + projectId: project.id, name, path, - isPrimary: row.isPrimary, - createdAt: row.createdAt.toISOString(), - updatedAt: row.updatedAt.toISOString(), + isPrimary: true, + createdAt: (row?.createdAt ?? project.createdAt).toISOString(), + updatedAt: (row?.updatedAt ?? project.updatedAt).toISOString(), }; }, @@ -728,17 +727,16 @@ export function buildHostServices( const project = await projects.getById(projectId); if (!inCompany(project, companyId)) return null; const row = project.primaryWorkspace; - if (!row) return null; - const path = sanitizeWorkspacePath(row.cwd); - const name = sanitizeWorkspaceName(row.name, path); + const path = sanitizeWorkspacePath(project.codebase.effectiveLocalFolder); + const name = sanitizeWorkspaceName(row?.name ?? project.name, path); return { - id: row.id, - projectId: row.projectId, + id: row?.id ?? `${project.id}:managed`, + projectId: project.id, name, path, - isPrimary: row.isPrimary, - createdAt: row.createdAt.toISOString(), - updatedAt: row.updatedAt.toISOString(), + isPrimary: true, + createdAt: (row?.createdAt ?? project.createdAt).toISOString(), + updatedAt: (row?.updatedAt ?? project.updatedAt).toISOString(), }; }, }, diff --git a/server/src/services/projects.ts b/server/src/services/projects.ts index 62be240b..4f7d1eb2 100644 --- a/server/src/services/projects.ts +++ b/server/src/services/projects.ts @@ -6,6 +6,7 @@ import { deriveProjectUrlKey, isUuidLike, normalizeProjectUrlKey, + type ProjectCodebase, type ProjectExecutionWorkspacePolicy, type ProjectGoalRef, type ProjectWorkspace, @@ -13,6 +14,7 @@ import { } from "@paperclipai/shared"; import { listWorkspaceRuntimeServicesForProjectWorkspaces } from "./workspace-runtime.js"; import { parseProjectExecutionWorkspacePolicy } from "./execution-workspace-policy.js"; +import { resolveManagedProjectWorkspaceDir } from "../home-paths.js"; type ProjectRow = typeof projects.$inferSelect; type ProjectWorkspaceRow = typeof projectWorkspaces.$inferSelect; @@ -41,6 +43,7 @@ interface ProjectWithGoals extends Omit goalIds: string[]; goals: ProjectGoalRef[]; executionWorkspacePolicy: ProjectExecutionWorkspacePolicy | null; + codebase: ProjectCodebase; workspaces: ProjectWorkspace[]; primaryWorkspace: ProjectWorkspace | null; } @@ -135,7 +138,7 @@ function toWorkspace( projectId: row.projectId, name: row.name, sourceType: row.sourceType as ProjectWorkspace["sourceType"], - cwd: row.cwd, + cwd: normalizeWorkspaceCwd(row.cwd), repoUrl: row.repoUrl ?? null, repoRef: row.repoRef ?? null, defaultRef: row.defaultRef ?? row.repoRef ?? null, @@ -153,6 +156,48 @@ function toWorkspace( }; } +function deriveRepoNameFromRepoUrl(repoUrl: string | null): string | null { + const raw = readNonEmptyString(repoUrl); + if (!raw) return null; + try { + const parsed = new URL(raw); + const cleanedPath = parsed.pathname.replace(/\/+$/, ""); + const repoName = cleanedPath.split("/").filter(Boolean).pop()?.replace(/\.git$/i, "") ?? ""; + return repoName || null; + } catch { + return null; + } +} + +function deriveProjectCodebase(input: { + companyId: string; + projectId: string; + primaryWorkspace: ProjectWorkspace | null; + fallbackWorkspaces: ProjectWorkspace[]; +}): ProjectCodebase { + const primaryWorkspace = input.primaryWorkspace ?? input.fallbackWorkspaces[0] ?? null; + const repoUrl = primaryWorkspace?.repoUrl ?? null; + const repoName = deriveRepoNameFromRepoUrl(repoUrl); + const localFolder = primaryWorkspace?.cwd ?? null; + const managedFolder = resolveManagedProjectWorkspaceDir({ + companyId: input.companyId, + projectId: input.projectId, + repoName, + }); + + return { + workspaceId: primaryWorkspace?.id ?? null, + repoUrl, + repoRef: primaryWorkspace?.repoRef ?? null, + defaultRef: primaryWorkspace?.defaultRef ?? null, + repoName, + localFolder, + managedFolder, + effectiveLocalFolder: localFolder ?? managedFolder, + origin: localFolder ? "local_folder" : "managed_checkout", + }; +} + function pickPrimaryWorkspace( rows: ProjectWorkspaceRow[], runtimeServicesByWorkspaceId?: Map, @@ -203,10 +248,17 @@ async function attachWorkspaces(db: Db, rows: ProjectWithGoals[]): Promise

Where will work be done on this project?

-

Add local folder and/or GitHub repo workspace hints.

+

Add a repo and/or local folder for this project.

@@ -327,7 +325,7 @@ export function NewProjectDialog() { Both
-

Configure local + repo hints.

+

Configure both repo and local folder.

@@ -347,7 +345,7 @@ export function NewProjectDialog() { )} {(workspaceSetup === "repo" || workspaceSetup === "both") && (
- + !linkedGoalIds.includes(g.id)); const workspaces = project.workspaces ?? []; + const codebase = project.codebase; + const primaryCodebaseWorkspace = project.primaryWorkspace ?? null; + const hasAdditionalLegacyWorkspaces = workspaces.some((workspace) => workspace.id !== primaryCodebaseWorkspace?.id); const executionWorkspacePolicy = project.executionWorkspacePolicy ?? null; const executionWorkspacesEnabled = executionWorkspacePolicy?.enabled === true; const executionWorkspaceDefaultMode = @@ -268,37 +269,51 @@ export function ProjectProperties({ project, onUpdate, onFieldUpdate, getFieldSa } }; - const deriveWorkspaceNameFromPath = (value: string) => { - const normalized = value.trim().replace(/[\\/]+$/, ""); - const segments = normalized.split(/[\\/]/).filter(Boolean); - return segments[segments.length - 1] ?? "Local folder"; - }; - - const deriveWorkspaceNameFromRepo = (value: string) => { + const formatRepoUrl = (value: string) => { try { const parsed = new URL(value); const segments = parsed.pathname.split("/").filter(Boolean); - const repo = segments[segments.length - 1]?.replace(/\.git$/i, "") ?? ""; - return repo || "GitHub repo"; - } catch { - return "GitHub repo"; - } - }; - - const formatGitHubRepo = (value: string) => { - try { - const parsed = new URL(value); - const segments = parsed.pathname.split("/").filter(Boolean); - if (segments.length < 2) return value; + if (segments.length < 2) return parsed.host; const owner = segments[0]; const repo = segments[1]?.replace(/\.git$/i, ""); - if (!owner || !repo) return value; - return `${owner}/${repo}`; + if (!owner || !repo) return parsed.host; + return `${parsed.host}/${owner}/${repo}`; } catch { return value; } }; + const deriveSourceType = (cwd: string | null, repoUrl: string | null) => { + if (repoUrl) return "git_repo"; + if (cwd) return "local_path"; + return undefined; + }; + + const persistCodebase = (patch: { cwd?: string | null; repoUrl?: string | null }) => { + const nextCwd = patch.cwd !== undefined ? patch.cwd : codebase.localFolder; + const nextRepoUrl = patch.repoUrl !== undefined ? patch.repoUrl : codebase.repoUrl; + if (!nextCwd && !nextRepoUrl) { + if (primaryCodebaseWorkspace) { + removeWorkspace.mutate(primaryCodebaseWorkspace.id); + } + return; + } + + const data: Record = { + ...(patch.cwd !== undefined ? { cwd: patch.cwd } : {}), + ...(patch.repoUrl !== undefined ? { repoUrl: patch.repoUrl } : {}), + ...(deriveSourceType(nextCwd, nextRepoUrl) ? { sourceType: deriveSourceType(nextCwd, nextRepoUrl) } : {}), + isPrimary: true, + }; + + if (primaryCodebaseWorkspace) { + updateWorkspace.mutate({ workspaceId: primaryCodebaseWorkspace.id, data }); + return; + } + + createWorkspace.mutate(data); + }; + const submitLocalWorkspace = () => { const cwd = workspaceCwd.trim(); if (!isAbsolutePath(cwd)) { @@ -306,59 +321,45 @@ export function ProjectProperties({ project, onUpdate, onFieldUpdate, getFieldSa return; } setWorkspaceError(null); - createWorkspace.mutate({ - name: deriveWorkspaceNameFromPath(cwd), - cwd, - }); + persistCodebase({ cwd }); }; const submitRepoWorkspace = () => { const repoUrl = workspaceRepoUrl.trim(); if (!isGitHubRepoUrl(repoUrl)) { - setWorkspaceError("Repo workspace must use a valid GitHub repo URL."); + setWorkspaceError("Repo must use a valid GitHub repo URL."); return; } setWorkspaceError(null); - createWorkspace.mutate({ - name: deriveWorkspaceNameFromRepo(repoUrl), - cwd: REPO_ONLY_CWD_SENTINEL, - repoUrl, - }); + persistCodebase({ repoUrl }); }; - const clearLocalWorkspace = (workspace: Project["workspaces"][number]) => { + const clearLocalWorkspace = () => { const confirmed = window.confirm( - workspace.repoUrl + codebase.repoUrl ? "Clear local folder from this workspace?" : "Delete this workspace local folder?", ); if (!confirmed) return; - if (workspace.repoUrl) { - updateWorkspace.mutate({ - workspaceId: workspace.id, - data: { cwd: null }, - }); - return; - } - removeWorkspace.mutate(workspace.id); + persistCodebase({ cwd: null }); }; - const clearRepoWorkspace = (workspace: Project["workspaces"][number]) => { - const hasLocalFolder = Boolean(workspace.cwd && workspace.cwd !== REPO_ONLY_CWD_SENTINEL); + const clearRepoWorkspace = () => { + const hasLocalFolder = Boolean(codebase.localFolder); const confirmed = window.confirm( hasLocalFolder - ? "Clear GitHub repo from this workspace?" + ? "Clear repo from this workspace?" : "Delete this workspace repo?", ); if (!confirmed) return; - if (hasLocalFolder) { + if (primaryCodebaseWorkspace) { updateWorkspace.mutate({ - workspaceId: workspace.id, - data: { repoUrl: null, repoRef: null }, + workspaceId: primaryCodebaseWorkspace.id, + data: { repoUrl: null, repoRef: null, defaultRef: null, sourceType: deriveSourceType(codebase.localFolder, null) }, }); return; } - removeWorkspace.mutate(workspace.id); + persistCodebase({ repoUrl: null }); }; return ( @@ -494,114 +495,133 @@ export function ProjectProperties({ project, onUpdate, onFieldUpdate, getFieldSa
- Workspaces + Codebase - Workspaces give your agents hints about where the work is + Repo identifies the source of truth. Local folder is the default place agents write code.
- {workspaces.length === 0 ? ( -

- No workspace configured. -

- ) : ( +
- {workspaces.map((workspace) => ( -
- {workspace.cwd && workspace.cwd !== REPO_ONLY_CWD_SENTINEL ? ( -
- {workspace.cwd} - -
- ) : null} - {workspace.repoUrl ? ( -
- - - {formatGitHubRepo(workspace.repoUrl)} - - - -
- ) : null} - {workspace.runtimeServices && workspace.runtimeServices.length > 0 ? ( -
- {workspace.runtimeServices.map((service) => ( -
-
-
- {service.serviceName} - - {service.status} - -
-
- {service.url ? ( - - {service.url} - - ) : ( - service.command ?? "No URL" - )} -
-
-
- {service.lifecycle} -
-
- ))} -
- ) : null} +
Repo
+ {codebase.repoUrl ? ( + - ))} + ) : ( +
Not set.
+ )}
- )} + +
+
Local folder
+ {codebase.localFolder ? ( +
+ {codebase.localFolder} + +
+ ) : ( +
+
Not set.
+
Paperclip will use a managed checkout instead.
+
+ )} +
+ +
+
Effective working folder
+
{codebase.effectiveLocalFolder}
+
+ {codebase.origin === "local_folder" ? "Using your local folder." : "Paperclip-managed folder."} +
+
+ + {hasAdditionalLegacyWorkspaces && ( +
+ Additional legacy workspace records exist on this project. Paperclip is using the primary workspace as the codebase view. +
+ )} + + {primaryCodebaseWorkspace?.runtimeServices && primaryCodebaseWorkspace.runtimeServices.length > 0 ? ( +
+ {primaryCodebaseWorkspace.runtimeServices.map((service) => ( +
+
+
+ {service.serviceName} + + {service.status} + +
+
+ {service.url ? ( + + {service.url} + + ) : ( + service.command ?? "No URL" + )} +
+
+
+ {service.lifecycle} +
+
+ ))} +
+ ) : null} +
{workspaceMode === "local" && (