# Conflicts: # packages/experimental/client-ui-forge/README.i18n.yaml # packages/experimental/worktree/README.i18n.yaml # packages/experimental/worktree/README.md # packages/experimental/worktree/README.zh.md
374 lines
19 KiB
TypeScript
374 lines
19 KiB
TypeScript
/** Creates a new Git branch and checkout, then changes the calling Session's working directory; restores a removed checkout. */
|
|
|
|
import { Context, Service, type Volatile } from '@deepseek-ai/cordis'
|
|
import z from '@deepseek-ai/schemastery'
|
|
import type { Agent } from '@deepseek-ai/dsh-agent'
|
|
import type {} from '@deepseek-ai/dsh-fs'
|
|
import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox'
|
|
import type {} from '@deepseek-ai/dsh-sandbox-policy'
|
|
import type {} from '@deepseek-ai/dsh-settings'
|
|
import { appendPluginRecord } from '@deepseek-ai/dsh-session'
|
|
import type { Session } from '@deepseek-ai/dsh-session'
|
|
import type { ProjectionHandle } from '@deepseek-ai/dsh-session-projection'
|
|
import type {} from '@deepseek-ai/dsh-working-directory'
|
|
import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
|
|
import { WorktreeReclamation } from './archive.ts'
|
|
import { PREPARE_DIRECTORY } from './directory.ts'
|
|
import { generatedWorktreeName } from './name.ts'
|
|
import { runCommand } from './process.ts'
|
|
import type { ProcessConfig } from './process.ts'
|
|
import { CREATED_RECORD, worktreeProjection } from './projection.ts'
|
|
import type { WorktreeProjectionState } from './projection.ts'
|
|
import { checkoutIdentity, registration, removeCheckout } from './removal.ts'
|
|
import type {
|
|
CreatedWorktree, CreateWorktreePhase, CreateWorktreeRequest, RestoredWorktree, RestoreWorktreeRequest, WorktreeCleanup,
|
|
} from './types.ts'
|
|
|
|
export type {
|
|
CreatedWorktree, CreateWorktreePhase, CreateWorktreeRequest, RestoredWorktree, RestoreWorktreeRequest, WorktreeCleanup, WorktreeCreation,
|
|
} from './types.ts'
|
|
export { generatedWorktreeName } from './name.ts'
|
|
export { CREATED_RECORD, createdWorktreeSchema, worktreeProjection } from './projection.ts'
|
|
export type { WorktreeProjectionState } from './projection.ts'
|
|
|
|
/** Worktree location, generated names, executables, subprocess resource limits, and the archive cleanup switch. */
|
|
export interface Config {
|
|
/** Keep every checkout when its Session is archived; editable live from the Plugins page. */
|
|
retainOnArchive: Volatile<boolean>
|
|
/** Relative checkout pool inside the source repository. */
|
|
directory?: string
|
|
/** Prefix for automatically generated branch and checkout names. */
|
|
namePrefix?: string
|
|
/** Executable name or absolute execution-world path of a Git release that honors `GIT_NO_LAZY_FETCH`. */
|
|
gitCommand?: string
|
|
/** Node executable used for sandboxed directory allocation. */
|
|
nodeCommand?: string
|
|
/** Deadline in milliseconds for one command. */
|
|
timeoutMs?: number
|
|
/** Subprocess termination grace in milliseconds. */
|
|
graceMs?: number
|
|
/** Maximum captured bytes per subprocess output stream. */
|
|
maxOutputBytes?: number
|
|
}
|
|
|
|
type ResolvedConfig = Required<Config> & ProcessConfig
|
|
|
|
interface WorktreeSpec {
|
|
branch: string
|
|
revision: string
|
|
}
|
|
|
|
/** Runs one confined Git command; output with an exit code outside `allowedExitCodes` throws. */
|
|
type GitRun = (directory: string, args: string[], allowedExitCodes?: number[], env?: NodeJS.ProcessEnv) => ReturnType<typeof runCommand>
|
|
|
|
declare module '@deepseek-ai/cordis' {
|
|
interface Context {
|
|
worktrees: WorktreeService
|
|
}
|
|
}
|
|
|
|
/** Reject path traversal independently of Git's branch-name grammar. */
|
|
function relativePath(value: string): boolean {
|
|
return value.length > 0 && !value.includes('\\') && !value.includes(':')
|
|
&& value.split('/').every(part => part.length > 0 && part !== '.' && part !== '..')
|
|
}
|
|
|
|
/**
|
|
* Creates retained Git worktrees under the mounted filesystem and sandbox
|
|
* providers, records each creation in the Session log, and reclaims a clean,
|
|
* unreferenced checkout when the Session that created it is archived.
|
|
*/
|
|
export class WorktreeService extends Service {
|
|
static inject = ['workingDirectory', 'fs', 'subprocess', 'sandbox', 'sandboxPolicy', 'sessionProjections']
|
|
|
|
static Config = z.object({
|
|
retainOnArchive: z.boolean().default(false).volatile(),
|
|
directory: z.string().default('.agents/worktrees'),
|
|
namePrefix: z.string().default('dsh-'),
|
|
gitCommand: z.string().default('git'),
|
|
nodeCommand: z.string().default('node'),
|
|
timeoutMs: z.number().default(300_000),
|
|
graceMs: z.number().default(3_000),
|
|
maxOutputBytes: z.number().default(65_536),
|
|
})
|
|
|
|
private readonly config: ResolvedConfig
|
|
private readonly lifetime = new AbortController()
|
|
private readonly pending = new Set<Promise<unknown>>()
|
|
private readonly checkouts = new Map<string, Promise<void>>()
|
|
private projection!: ProjectionHandle<WorktreeProjectionState>
|
|
private reclamation: WorktreeReclamation | undefined
|
|
|
|
constructor(ctx: Context, config: Config) {
|
|
super(ctx, 'worktrees')
|
|
this.config = config as ResolvedConfig
|
|
if (!relativePath(this.config.directory)) throw new Error('worktree: directory must be a relative directory without dot segments')
|
|
if (!relativePath(`${this.config.namePrefix}name`) || this.config.namePrefix.startsWith('-')) {
|
|
throw new Error('worktree: namePrefix must produce a relative branch name')
|
|
}
|
|
for (const key of ['gitCommand', 'nodeCommand'] as const) {
|
|
if (this.config[key].trim().length === 0) throw new Error(`worktree: ${key} must not be empty`)
|
|
}
|
|
for (const key of ['timeoutMs', 'graceMs', 'maxOutputBytes'] as const) {
|
|
const value = this.config[key]
|
|
if (!Number.isSafeInteger(value) || value <= 0 || value > MAX_TIMER_DELAY_MS) {
|
|
throw new Error(`worktree: ${key} must be a positive integer no greater than ${MAX_TIMER_DELAY_MS}`)
|
|
}
|
|
}
|
|
ctx.effect(() => async () => {
|
|
this.lifetime.abort(new Error('worktree service disposed'))
|
|
await Promise.allSettled(this.pending)
|
|
})
|
|
// The Forge panel draws the retain switch on this row's Plugins page.
|
|
ctx.inject(['settings'], (child) => { child.effect(() => child.settings.configure({ auto: false }, ctx.fiber)) })
|
|
}
|
|
|
|
protected async [Service.init](): Promise<void> {
|
|
this.projection = await this.ctx.sessionProjections.register(worktreeProjection)
|
|
// Reclamation needs the Workspace archive events and the Session corpus; without
|
|
// them the service only creates and restores, as a headless profile composes it.
|
|
this.ctx.inject(['workspaceRegistry', 'sessionQuery', 'sessions', 'workingDirectory', 'sandboxPolicy'], (scope) => {
|
|
const reclamation = new WorktreeReclamation(scope, {
|
|
retainOnArchive: () => this.config.retainOnArchive.get(),
|
|
exclusiveCheckout: (path, body) => this.exclusiveCheckout(path, body),
|
|
removeCheckout: (session, request, signal, admit) => this.removeCheckout(session, request, signal, admit),
|
|
}, this.projection)
|
|
this.reclamation = reclamation
|
|
scope.effect(() => () => { this.reclamation = undefined })
|
|
})
|
|
}
|
|
|
|
/**
|
|
* Create a fresh branch and checkout at a pinned local revision, then enter it.
|
|
* Existing branches or checkout paths fail. Uncommitted files stay in the source checkout.
|
|
* Checkout disables configured clean, smudge, and process filters without changing Git config.
|
|
* Repository-local replacement refs still apply; baseCommit reports the resolved object name.
|
|
* The new checkout becomes current only after Git setup succeeds. Failures may retain newly
|
|
* allocated Git/filesystem artifacts; no branch or checkout is removed automatically.
|
|
* @param agent - caller whose current directory selects the source repository and file policy.
|
|
* @param request - optional new name and local revision; defaults are generated name and HEAD.
|
|
* @param signal - cancellation of lookup, creation, and working-directory publication.
|
|
* @param onPhase - receives each stage before it begins; it must not throw.
|
|
* @returns canonical checkout path, branch name, pinned commit, and source repository root.
|
|
*/
|
|
async create(
|
|
agent: Agent,
|
|
request: CreateWorktreeRequest = {},
|
|
signal?: AbortSignal,
|
|
onPhase?: (phase: CreateWorktreePhase) => void,
|
|
): Promise<CreatedWorktree> {
|
|
const operationSignal = signal === undefined ? this.lifetime.signal : AbortSignal.any([this.lifetime.signal, signal])
|
|
operationSignal.throwIfAborted()
|
|
const operation = this.createCheckout(agent, this.resolve(agent, request), operationSignal, onPhase)
|
|
this.pending.add(operation)
|
|
try {
|
|
return await operation
|
|
} finally {
|
|
this.pending.delete(operation)
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Check out a removed worktree again at its recorded directory: its branch
|
|
* when the branch still exists, otherwise a new branch of the same name at
|
|
* `baseCommit`. Only the missing target's unlocked registration is removed, and an
|
|
* existing directory fails. Changes that were never committed are not
|
|
* recovered. Checkout disables configured clean, smudge, and process filters,
|
|
* as creation does. The calling Session's working directory does not change.
|
|
* Failures may retain newly allocated Git/filesystem artifacts.
|
|
* @param agent - caller whose sandbox policy confines the commands.
|
|
* @param request - recorded directory, branch, base commit, and source repository root.
|
|
* @param signal - cancellation of the restoration.
|
|
* @param onPhase - receives each stage before it begins; it must not throw.
|
|
* @returns the directory and whether the branch was created again.
|
|
*/
|
|
async restore(
|
|
agent: Agent,
|
|
request: RestoreWorktreeRequest,
|
|
signal?: AbortSignal,
|
|
onPhase?: (phase: CreateWorktreePhase) => void,
|
|
): Promise<RestoredWorktree> {
|
|
const operationSignal = signal === undefined ? this.lifetime.signal : AbortSignal.any([this.lifetime.signal, signal])
|
|
operationSignal.throwIfAborted()
|
|
const operation = this.exclusiveCheckout(request.path, () => this.restoreCheckout(agent, request, operationSignal, onPhase))
|
|
this.pending.add(operation)
|
|
try {
|
|
return await operation
|
|
} finally {
|
|
this.pending.delete(operation)
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Read the archive cleanup of a Session's created checkout; waiting never
|
|
* starts one. Absent without the Workspace and query providers.
|
|
* @param session - archived Session whose cleanup is read.
|
|
* @param revision - null reads at once; a matching revision waits for that attempt to settle.
|
|
* @returns the attempt state, or null when none exists, the revision was superseded, or the service is stopping.
|
|
*/
|
|
async cleanupOf(session: Session, revision: number | null): Promise<WorktreeCleanup | null> {
|
|
return await this.reclamation?.cleanupOf(session, revision) ?? null
|
|
}
|
|
|
|
/**
|
|
* Inspect a recorded checkout under the Session's policy and, when eligible
|
|
* and admitted, remove it and its registration without force or branch
|
|
* deletion. A rejection can leave a partial directory; the branch stays.
|
|
*/
|
|
private async removeCheckout(
|
|
session: Session, request: RestoreWorktreeRequest, signal: AbortSignal, admit: () => boolean,
|
|
): Promise<boolean> {
|
|
const control = AbortSignal.any([this.lifetime.signal, signal])
|
|
control.throwIfAborted()
|
|
const run = this.gitRunner(this.ctx.sandboxPolicy.resolve({ session }), control)
|
|
const operation = removeCheckout(this.ctx, this.config.directory, request, run, control, admit)
|
|
this.pending.add(operation)
|
|
try { return await operation } finally { this.pending.delete(operation) }
|
|
}
|
|
|
|
private exclusiveCheckout<T>(path: string, body: () => Promise<T>): Promise<T> {
|
|
const operation = (this.checkouts.get(path) ?? Promise.resolve()).then(body)
|
|
const tail = operation.then(() => {}, () => {})
|
|
this.checkouts.set(path, tail)
|
|
void tail.then(() => { if (this.checkouts.get(path) === tail) this.checkouts.delete(path) })
|
|
return operation
|
|
}
|
|
|
|
private resolve(agent: Agent, request: CreateWorktreeRequest): WorktreeSpec {
|
|
const branch = request.name ?? generatedWorktreeName(this.config.namePrefix, agent.session.id)
|
|
if (!relativePath(branch) || branch.startsWith('-')) throw new Error('worktree name must be a relative Git branch name')
|
|
const revision = request.from ?? 'HEAD'
|
|
if (revision.length === 0) throw new Error('worktree from must name a local commit, branch, or tag')
|
|
return { branch, revision }
|
|
}
|
|
|
|
private async createCheckout(
|
|
agent: Agent,
|
|
{ branch, revision }: WorktreeSpec,
|
|
signal: AbortSignal,
|
|
onPhase: ((phase: CreateWorktreePhase) => void) | undefined,
|
|
): Promise<CreatedWorktree> {
|
|
onPhase?.('prepare')
|
|
const cwd = await this.ctx.workingDirectory.ensure(agent, signal)
|
|
const policy = this.ctx.sandboxPolicy.resolve({ session: agent.session })
|
|
const run = this.gitRunner(policy, signal)
|
|
await run(cwd, ['check-ref-format', `refs/heads/${branch}`])
|
|
const rootOutput = await run(cwd, ['rev-parse', '--show-toplevel'])
|
|
const rootTarget = await this.ctx.fs.resolve(rootOutput.stdout.replace(/\r?\n$/, ''), { cwd, signal })
|
|
const repositoryRoot = this.ctx.fs.processPath(rootTarget)
|
|
const base = await run(repositoryRoot, ['rev-parse', '--verify', '--end-of-options', `${revision}^{commit}`])
|
|
const baseCommit = base.stdout.trim()
|
|
const existing = await run(repositoryRoot, ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], [0, 1])
|
|
if (existing.exitCode === 0) throw new Error(`worktree branch already exists: ${branch}`)
|
|
const pool = await this.ctx.fs.resolve(this.config.directory, { cwd: repositoryRoot, signal })
|
|
const poolPath = this.ctx.fs.processPath(pool)
|
|
const destination = await this.ctx.fs.resolve(branch, { cwd: poolPath, signal })
|
|
const path = this.ctx.fs.processPath(destination)
|
|
if (await this.ctx.fs.lstat(path, undefined, signal) !== undefined) throw new Error(`worktree path already exists: ${path}`)
|
|
try {
|
|
await this.prepareDirectory(policy, repositoryRoot, poolPath, path, signal)
|
|
await run(repositoryRoot, ['--work-tree', repositoryRoot, 'worktree', 'add', '--no-checkout', '-b', branch, '--', path, baseCommit])
|
|
const overrides = await filterOverrides(run, path)
|
|
onPhase?.('checkout')
|
|
await run(path, ['--work-tree', path, 'reset', '--hard', '--no-recurse-submodules', baseCommit], undefined, overrides)
|
|
const canonicalPath = await this.ctx.workingDirectory.set(agent, path, signal)
|
|
const created: CreatedWorktree = { path: canonicalPath, branch, baseCommit, repositoryRoot }
|
|
appendPluginRecord(agent.session, CREATED_RECORD, created)
|
|
return created
|
|
} catch (error) {
|
|
throw new Error(`Could not finish worktree ${branch} at ${path}. Any created checkout and branch are retained. ${error instanceof Error ? error.message : String(error)}`, { cause: error })
|
|
}
|
|
}
|
|
|
|
private async restoreCheckout(
|
|
agent: Agent,
|
|
{ path, branch, baseCommit, repositoryRoot }: RestoreWorktreeRequest,
|
|
signal: AbortSignal,
|
|
onPhase: ((phase: CreateWorktreePhase) => void) | undefined,
|
|
): Promise<RestoredWorktree> {
|
|
onPhase?.('prepare')
|
|
const policy = this.ctx.sandboxPolicy.resolve({ session: agent.session })
|
|
const run = this.gitRunner(policy, signal)
|
|
if (await this.ctx.fs.lstat(path, undefined, signal) !== undefined) throw new Error(`worktree path already exists: ${path}`)
|
|
if (!relativePath(branch) || branch.startsWith('-')) throw new Error('worktree branch must be a relative Git branch name')
|
|
if (!/^(?:[a-f\d]{40}|[a-f\d]{64})$/i.test(baseCommit)) throw new Error('worktree baseCommit must be a full commit object name')
|
|
const identity = await checkoutIdentity(this.ctx, this.config.directory, { path, branch, baseCommit, repositoryRoot }, run, signal)
|
|
if (identity === null) throw new Error('worktree restoration must use a canonical directory inside the configured pool of the source checkout root')
|
|
await run(repositoryRoot, ['check-ref-format', `refs/heads/${branch}`])
|
|
await run(repositoryRoot, ['rev-parse', '--verify', '--end-of-options', `${baseCommit}^{commit}`])
|
|
const fields = await registration(this.ctx, { path, branch, baseCommit, repositoryRoot }, identity.target, run, signal)
|
|
if (fields !== undefined) {
|
|
if (fields.some(field => field === 'locked' || field.startsWith('locked '))) throw new Error(`worktree is locked: ${path}`)
|
|
if (await this.ctx.fs.lstat(path, undefined, signal) !== undefined) throw new Error(`worktree path already exists: ${path}`)
|
|
await run(repositoryRoot, ['worktree', 'remove', '--', path])
|
|
}
|
|
const existing = await run(repositoryRoot, ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], [0, 1])
|
|
const branchRecreated = existing.exitCode !== 0
|
|
try {
|
|
const pool = await this.ctx.fs.resolve(this.config.directory, { cwd: repositoryRoot, signal })
|
|
await this.prepareDirectory(policy, repositoryRoot, this.ctx.fs.processPath(pool), path, signal)
|
|
await run(repositoryRoot, [
|
|
'--work-tree', repositoryRoot, 'worktree', 'add', '--no-checkout',
|
|
...branchRecreated ? ['-b', branch, '--', path, baseCommit] : ['--', path, branch],
|
|
])
|
|
const overrides = await filterOverrides(run, path)
|
|
onPhase?.('checkout')
|
|
await run(path, ['--work-tree', path, 'reset', '--hard', '--no-recurse-submodules', 'HEAD'], undefined, overrides)
|
|
return { path, branchRecreated }
|
|
} catch (error) {
|
|
throw new Error(`Could not restore worktree ${branch} at ${path}. Any created checkout and branch are retained. ${error instanceof Error ? error.message : String(error)}`, { cause: error })
|
|
}
|
|
}
|
|
|
|
/** Confine Git commands to the caller's sandbox policy, with hooks and the filesystem monitor disabled. */
|
|
private gitRunner(policy: SandboxExecutionPolicy, signal: AbortSignal): GitRun {
|
|
return (directory, args, allowedExitCodes, env) => runCommand(
|
|
this.ctx, this.config, policy, directory,
|
|
[this.config.gitCommand, '-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', ...args],
|
|
signal, allowedExitCodes, env,
|
|
)
|
|
}
|
|
|
|
/** Allocate the checkout directory exclusively inside the pool, creating a self-ignoring pool when it is new. */
|
|
private async prepareDirectory(
|
|
policy: SandboxExecutionPolicy,
|
|
repositoryRoot: string,
|
|
poolPath: string,
|
|
path: string,
|
|
signal: AbortSignal,
|
|
): Promise<void> {
|
|
await runCommand(this.ctx, this.config, policy, repositoryRoot,
|
|
[this.config.nodeCommand, '--input-type=module', '-e', PREPARE_DIRECTORY, poolPath, path], signal)
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Build the environment that disables every configured clean, smudge, and
|
|
* process filter of the checkout for one command, without changing Git config.
|
|
* @param run - confined Git runner.
|
|
* @param path - checkout directory.
|
|
* @returns `GIT_CONFIG_*` overrides.
|
|
*/
|
|
async function filterOverrides(run: GitRun, path: string): Promise<NodeJS.ProcessEnv> {
|
|
const configured = await run(path, ['config', '--null', '--name-only', '--get-regexp', '^filter\\.'], [0, 1])
|
|
const drivers = new Set<string>()
|
|
for (const key of configured.stdout.split('\0')) {
|
|
const separator = key.lastIndexOf('.')
|
|
if (separator > 'filter.'.length && ['clean', 'smudge', 'process', 'required'].includes(key.slice(separator + 1))) {
|
|
drivers.add(key.slice('filter.'.length, separator))
|
|
}
|
|
}
|
|
const overrides: NodeJS.ProcessEnv = { GIT_CONFIG_COUNT: String(drivers.size * 4) }
|
|
let index = 0
|
|
for (const driver of drivers) {
|
|
for (const attribute of ['clean', 'smudge', 'process', 'required']) {
|
|
overrides[`GIT_CONFIG_KEY_${index}`] = `filter.${driver}.${attribute}`
|
|
overrides[`GIT_CONFIG_VALUE_${index}`] = attribute === 'required' ? 'false' : ''
|
|
index++
|
|
}
|
|
}
|
|
return overrides
|
|
}
|
|
|
|
export default WorktreeService
|