dsh-git-worktree 0.1.0

package/lib/index.js

@@ -0,0 +1,93 @@
+/**
+ * dsh-git-worktree plugin entry. The session-checkout domain (state machine,
+ * apply engine, ports) is Domi-ported and host-agnostic; this file is the DSH
+ * plugin face: exports the domain error type and the module contract, builds
+ * the DSH adapters, mounts the state machine, and registers the model tools,
+ * `/worktree` command, and session context note.
+ * @module dsh-git-worktree
+ */
+/** Stable domain failure raised by the session-checkout state machine and its adapters. */
+export class SessionCheckoutError extends Error {
+    code;
+    /**
+     * @param code - stable error code from `SESSION_CHECKOUT_ERROR_CODES`.
+     * @param message - user-facing message, surfaced verbatim by tools.
+     */
+    constructor(code, message) {
+        super(message);
+        this.name = 'SessionCheckoutError';
+        this.code = code;
+    }
+}
+import { randomUUID } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { createDshGitPort } from './adapters/git.js';
+import { createNodeFilesPort } from './adapters/files.js';
+import { AtomicJsonCheckoutRegistry } from './adapters/registry.js';
+import { createDshLookupPort } from './adapters/lookup.js';
+import { createSessionCheckoutApplyEngine } from './session-checkout-apply.js';
+import { createSessionCheckoutModule } from './session-checkout-module.js';
+import { registerTools } from './tools.js';
+import { registerWorktreeCommand } from './commands.js';
+const name = 'git-worktree';
+const inject = ['tools', 'commands', 'subprocess'];
+const Config = z.object({
+    /**
+     * Plugin state directory (registry, disabled-hooks root). Defaults to
+     * `$DSH_HOME/plugins/dsh-git-worktree` (`~/.dsh` when `DSH_HOME` is unset).
+     * The property is optional by construction (schemastery object properties
+     * are optional inputs).
+     */
+    stateDir: z.string(),
+});
+function resolveStateDir(config) {
+    if (config.stateDir)
+        return resolve(config.stateDir);
+    const home = process.env.DSH_HOME?.trim() || join(homedir(), '.dsh');
+    return join(home, 'plugins', 'dsh-git-worktree');
+}
+const RETENTION_MAINTENANCE_INTERVAL_MS = 15 * 60 * 1000;
+/**
+ * Mount the plugin: DSH adapters, the session-checkout module, the seven
+ * worktree tools, the `/worktree` command, the once-per-session worktree
+ * context note, startup reconciliation, and the retention-expiry timer.
+ */
+export function apply(ctx, config = {}) {
+    const stateDir = resolveStateDir(config);
+    mkdirSync(stateDir, { recursive: true });
+    const hooksPath = join(stateDir, 'disabled-git-hooks');
+    mkdirSync(hooksPath, { recursive: true });
+    const module = createSessionCheckoutModule({
+        lookup: createDshLookupPort(ctx),
+        git: createDshGitPort(ctx, { hooksPath }),
+        files: createNodeFilesPort(),
+        registry: new AtomicJsonCheckoutRegistry(join(stateDir, 'managed-checkouts.json')),
+        applyEngine: createSessionCheckoutApplyEngine(),
+        managedCheckoutsRoot: stateDir,
+        createCheckoutId: randomUUID,
+    });
+    registerTools(ctx, module);
+    registerWorktreeCommand(ctx, module);
+    // Startup recovery plus periodic expiry of retained worktrees. cordis's
+    // typed Events map omits the runtime 'ready' event; the events service's
+    // loose runtime signature covers it.
+    const reconcileOnReady = ctx.events.on('ready', () => {
+        void module.reconcile().catch((error) => {
+            console.warn('[dsh-git-worktree] reconcile failed:', error);
+        });
+    });
+    const retentionTimer = setInterval(() => {
+        void module.cleanupExpiredRetained().catch((error) => {
+            console.warn('[dsh-git-worktree] retained worktree maintenance failed:', error);
+        });
+    }, RETENTION_MAINTENANCE_INTERVAL_MS);
+    retentionTimer.unref?.();
+    ctx.effect(() => () => {
+        reconcileOnReady();
+        clearInterval(retentionTimer);
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/managed-worktree-path.d.ts

@@ -0,0 +1,27 @@
+/** 将会话标题转换为跨平台安全、可读的单个目录名片段。 */
+export declare function sanitizeManagedWorktreeLabel(rawTitle: string | undefined): string;
+export declare function createManagedWorktreeDirectoryName(input: {
+    sessionId: string;
+    sessionTitle?: string;
+    checkoutId?: string;
+    iteration?: number;
+}): string;
+export interface ManagedWorktreePathCandidates {
+    siblingContainer: string;
+    siblingRoot: string;
+    fallbackRoot: string;
+}
+/**
+ * 只生成候选路径，不访问文件系统：
+ * - siblingRoot：Git 根目录同级的可读容器；
+ * - fallbackRoot：原 Domi 数据目录下、按 repository key 分组的安全回退。
+ */
+export declare function createManagedWorktreePathCandidates(input: {
+    localGitRoot: string;
+    managedCheckoutsRoot: string;
+    repositoryKey: string;
+    sessionId: string;
+    sessionTitle?: string;
+    checkoutId?: string;
+    iteration?: number;
+}): ManagedWorktreePathCandidates;

package/lib/managed-worktree-path.js

@@ -0,0 +1,53 @@
+import { basename, dirname, join } from 'node:path';
+const DEFAULT_SESSION_TITLES = new Set(['新 Agent 会话', '新会话']);
+const WINDOWS_INVALID_CHARACTERS = /[<>:"/\\|?*\u0000-\u001f]/g;
+const WINDOWS_RESERVED_NAME = /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/i;
+const DISPLAY_SUFFIX = /\s*\((?:worktree|fork)\)\s*$/i;
+const REPEATED_DASHES = /-{2,}/g;
+const MAX_LABEL_LENGTH = 40;
+function truncateCodePoints(value, maxLength) {
+    return Array.from(value).slice(0, maxLength).join('');
+}
+/** 将会话标题转换为跨平台安全、可读的单个目录名片段。 */
+export function sanitizeManagedWorktreeLabel(rawTitle) {
+    const withoutDisplaySuffix = (rawTitle ?? '').replace(DISPLAY_SUFFIX, '').trim();
+    const source = DEFAULT_SESSION_TITLES.has(withoutDisplaySuffix) ? '' : withoutDisplaySuffix;
+    let cleaned = source
+        .normalize('NFC')
+        .replace(WINDOWS_INVALID_CHARACTERS, '-')
+        .replace(/\s+/g, '-')
+        .replace(REPEATED_DASHES, '-')
+        .replace(/^[.\s-]+|[.\s-]+$/g, '');
+    cleaned = truncateCodePoints(cleaned, MAX_LABEL_LENGTH)
+        .replace(/[.\s-]+$/g, '');
+    if (!cleaned)
+        return 'worktree';
+    return WINDOWS_RESERVED_NAME.test(cleaned) ? `_${cleaned}` : cleaned;
+}
+function shortIdentity(value, fallback) {
+    return value.replace(/[^a-zA-Z0-9]/g, '').slice(0, 8) || fallback;
+}
+export function createManagedWorktreeDirectoryName(input) {
+    const sessionIdentity = shortIdentity(input.sessionId, 'session');
+    if (!input.checkoutId || !input.iteration) {
+        return `${sanitizeManagedWorktreeLabel(input.sessionTitle)}--${sessionIdentity}`;
+    }
+    const checkoutIdentity = shortIdentity(input.checkoutId, 'checkout');
+    return `${sanitizeManagedWorktreeLabel(input.sessionTitle)}--${sessionIdentity}--i${input.iteration}--${checkoutIdentity}`;
+}
+/**
+ * 只生成候选路径，不访问文件系统：
+ * - siblingRoot：Git 根目录同级的可读容器；
+ * - fallbackRoot：原 Domi 数据目录下、按 repository key 分组的安全回退。
+ */
+export function createManagedWorktreePathCandidates(input) {
+    const repositoryLabel = sanitizeManagedWorktreeLabel(basename(input.localGitRoot));
+    const directoryName = createManagedWorktreeDirectoryName(input);
+    const siblingContainer = join(dirname(input.localGitRoot), `${repositoryLabel}-worktrees`);
+    return {
+        siblingContainer,
+        siblingRoot: join(siblingContainer, directoryName),
+        fallbackRoot: join(input.managedCheckoutsRoot, input.repositoryKey, directoryName),
+    };
+}
+//# sourceMappingURL=managed-worktree-path.js.map

package/lib/managed-worktree-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-worktree-path.js","sourceRoot":"","sources":["../src/managed-worktree-path.ts"],"names":[],"mappings":"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"}

package/lib/ports.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Port interfaces for the session-checkout domain, ported from Domi's
+ * `session-checkout/ports.ts`. The domain logic depends only on these ports;
+ * the DSH adapters (subprocess-backed git, plugin-owned registry storage,
+ * session/workspace lookup) live behind them so the state machine and apply
+ * engine stay host-agnostic and testable with fakes.
+ * @module dsh-git-worktree/ports
+ */
+import type { ApplyBaseStrategy, SessionCheckoutPhase, SessionTargetRef, WorktreeValidationItem, WorktreeRetentionMode, WorktreeValidationStatus } from './types.js';
+import type { SessionCheckoutApplyEngine } from './session-checkout-apply.js';
+export interface SessionCheckoutSessionRecord {
+    id: string;
+    projectId?: string;
+    /** Only used for readable managed worktree directory names; never identity. */
+    title?: string;
+}
+export interface SessionCheckoutProjectRecord {
+    id: string;
+    name: string;
+    root: string;
+}
+export interface SessionCheckoutLookupPort {
+    getSession(sessionId: string): SessionCheckoutSessionRecord | undefined;
+    getProject(projectId: string): SessionCheckoutProjectRecord | undefined;
+}
+export interface GitCheckoutSnapshot {
+    root: string;
+    commonDir: string;
+    gitDir: string;
+    branch: string | null;
+    headOid: string;
+    headRef: string;
+}
+export interface SessionCheckoutGitPort {
+    inspect(root: string): Promise<GitCheckoutSnapshot | null>;
+    /** Top-level of the Git checkout containing the directory; does not require a HEAD. */
+    findContainingWorktreeRoot(root: string): Promise<string | null>;
+    status(root: string): Promise<{
+        dirty: boolean;
+    }>;
+    createDetachedWorktree(localRoot: string, managedRoot: string, baseOid: string): Promise<void>;
+    /** Deletion after the host verified checkout identity and the full fingerprint including untracked. */
+    removeWorktree(localRoot: string, managedRoot: string): Promise<void>;
+    retainApplyBase(localRoot: string, checkoutId: string, oid: string): Promise<void>;
+    releaseApplyBase(localRoot: string, checkoutId: string): Promise<void>;
+    retainInternalArtifact(localRoot: string, checkoutId: string, artifactName: string, oid: string): Promise<void>;
+    releaseInternalArtifacts(localRoot: string, checkoutId: string, artifactPrefix?: string): Promise<void>;
+    /** Read-only ancestry proof; only accepts host-verified checkout roots and OIDs. */
+    isAncestor(root: string, ancestorOid: string, descendantOid: string): Promise<boolean>;
+}
+export interface DirectoryIdentity {
+    device: string;
+    inode: string;
+    birthtimeNs: string;
+}
+export interface SessionCheckoutFilesPort {
+    exists(path: string): boolean;
+    canonicalize(path: string): Promise<string>;
+    inspectDirectoryIdentity(path: string): Promise<DirectoryIdentity | null>;
+    ensureDirectory(path: string): void;
+    /** Deletes only when the whole tree contains no files or symlinks; used to collect empty `git worktree add` residue. */
+    removeEmptyDirectoryTree(path: string): boolean;
+    /** Atomically moves residue whose file identity matches into the plugin quarantine. */
+    quarantineDirectoryTree(path: string, expectedIdentity: DirectoryIdentity, quarantinePath: string): Promise<void>;
+    /** Deletes a fully owned non-empty directory tree; the root must not be a file or symlink. */
+    removeDirectoryTree(path: string): Promise<void>;
+    /** Estimates real file usage; does not follow symlinks. */
+    measureDirectoryBytes(path: string): Promise<number>;
+}
+export interface SessionBindingRecord {
+    sessionId: string;
+    projectId: string;
+    projectName: string;
+    target: SessionTargetRef;
+    ownerSessionId: string;
+    inheritedFromSessionId?: string;
+    sourceRef: string;
+    sourceOid: string;
+    revision: number;
+}
+interface ManagedCheckoutJournalBase {
+    operationId: string;
+    startedAt: number;
+}
+export interface ManagedCheckoutCreateJournal extends ManagedCheckoutJournalBase {
+    operation: 'create';
+    step: 'creating_worktree';
+}
+export interface ManagedCheckoutMutationJournal extends ManagedCheckoutJournalBase {
+    operation: 'apply' | 'finish' | 'cleanup';
+    step: 'planning' | 'artifacts_retained' | 'writing_local' | 'updating_ref' | 'replacing_index' | 'removing_worktree';
+    baseOid?: string;
+    planRevision?: string;
+    reviewId?: string;
+    localFingerprint?: string;
+    isolatedFingerprint?: string;
+    effectiveBaseOid?: string;
+    baseStrategy?: ApplyBaseStrategy;
+    localHeadOid?: string;
+    isolatedHeadOid?: string;
+    commitOid?: string;
+    retention?: WorktreeRetentionMode;
+    changedFiles?: string[];
+    managedDirectoryIdentity?: DirectoryIdentity;
+    cleanupQuarantinePath?: string;
+}
+export type ManagedCheckoutJournal = ManagedCheckoutCreateJournal | ManagedCheckoutMutationJournal;
+export interface ManagedWorktreeReviewRecord {
+    reviewId: string;
+    iteration: number;
+    preparedAt: number;
+    detailsMarkdown?: string;
+    summary: string;
+    validationStatus: WorktreeValidationStatus;
+    validationSummary?: string;
+    tests: WorktreeValidationItem[];
+    changedFiles: string[];
+    suggestedCommitMessage: string;
+    isolatedFingerprint: string;
+    isolatedHeadOid: string;
+}
+export interface ManagedDeliveryProof {
+    localBranch: string | null;
+    localHeadBefore: string;
+    localHeadAfter: string;
+    changedFiles: string[];
+}
+export type ManagedCheckoutDelivery = {
+    state: 'working';
+    iteration: number;
+} | {
+    state: 'ready_for_review';
+    review: ManagedWorktreeReviewRecord;
+} | {
+    state: 'finalized';
+    review: ManagedWorktreeReviewRecord;
+    commitOid: string | null;
+    /** Newer delivery proof; historical registries may omit it. */
+    proof?: ManagedDeliveryProof;
+    /** The delivered isolated snapshot; cleanup retry must do fingerprint CAS. */
+    isolatedFingerprint: string;
+    finalizedAt: number;
+    cleanup: 'pending' | 'blocked';
+    cleanupMessage?: string;
+} | {
+    state: 'retained';
+    review: ManagedWorktreeReviewRecord;
+    commitOid: string | null;
+    proof?: ManagedDeliveryProof;
+    isolatedFingerprint: string;
+    retention: Exclude<WorktreeRetentionMode, 'cleanup'>;
+    retainedAt: number;
+    expiresAt: number | null;
+    cleanup: 'scheduled' | 'blocked';
+    cleanupMessage?: string;
+} | {
+    state: 'delivered';
+    iteration: number;
+    commitOid: string | null;
+    proof?: ManagedDeliveryProof;
+    deliveredAt: number;
+};
+export interface ManagedCheckoutRecord {
+    checkoutId: string;
+    projectId: string;
+    projectName: string;
+    ownerSessionId: string;
+    /** Canonical root of the project in the user's Local Checkout. */
+    localRoot: string;
+    /** Canonical root of the project in the managed worktree; also the lease cwd. */
+    managedRoot: string;
+    /** Repo top level of the managed Git worktree; the project root may be a subdirectory. */
+    managedGitRoot: string;
+    gitCommonDir: string;
+    gitDir: string;
+    baseOid: string;
+    /** Last successfully applied isolated snapshot; does not change the user-visible Session Base. */
+    applyBaseOid?: string;
+    sourceRef: string;
+    phase: SessionCheckoutPhase;
+    delivery: ManagedCheckoutDelivery;
+    journal: ManagedCheckoutJournal | null;
+    revision: number;
+}
+export interface ManagedCheckoutsRegistry {
+    version: 2;
+    revision: number;
+    sessionBindings: Record<string, SessionBindingRecord>;
+    managedCheckouts: Record<string, ManagedCheckoutRecord>;
+}
+export interface SessionCheckoutRegistryPort {
+    read(): ManagedCheckoutsRegistry;
+    write(registry: ManagedCheckoutsRegistry): void;
+}
+export interface SessionCheckoutDependencies {
+    lookup: SessionCheckoutLookupPort;
+    git: SessionCheckoutGitPort;
+    files: SessionCheckoutFilesPort;
+    registry: SessionCheckoutRegistryPort;
+    applyEngine: SessionCheckoutApplyEngine;
+    managedCheckoutsRoot: string;
+    createCheckoutId(): string;
+}
+export {};

package/lib/ports.js

@@ -0,0 +1,10 @@
+/**
+ * Port interfaces for the session-checkout domain, ported from Domi's
+ * `session-checkout/ports.ts`. The domain logic depends only on these ports;
+ * the DSH adapters (subprocess-backed git, plugin-owned registry storage,
+ * session/workspace lookup) live behind them so the state machine and apply
+ * engine stay host-agnostic and testable with fakes.
+ * @module dsh-git-worktree/ports
+ */
+export {};
+//# sourceMappingURL=ports.js.map

package/lib/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/lib/session-checkout-apply.d.ts

@@ -0,0 +1,110 @@
+import type { ApplyBaseStrategy } from './types.js';
+export interface ApplyPlanInput {
+    baseOid: string;
+    isolatedPath: string;
+    localPath: string;
+}
+export interface ApplyPlan {
+    revision: string;
+    localFingerprint: string;
+    isolatedFingerprint: string;
+    effectiveBaseOid: string;
+    baseStrategy: ApplyBaseStrategy;
+    localHeadOid: string;
+    /** null 表示 Local 当前为 detached HEAD；Apply 允许，Finish 会拒绝自动提交。 */
+    localHeadRef: string | null;
+    isolatedHeadOid: string;
+    changedFiles: string[];
+}
+export interface ReviewSnapshotResult {
+    status: 'ready';
+    isolatedFingerprint: string;
+    isolatedHeadOid: string;
+    changedFiles: string[];
+}
+export type InspectReviewResult = ReviewSnapshotResult | ApplyPlanErrorResult;
+export interface ApplyReadyPlanResult {
+    status: 'ready';
+    plan: ApplyPlan;
+}
+export interface ApplyConflictPlanResult {
+    status: 'conflict';
+    revision: string;
+    localFingerprint: string;
+    isolatedFingerprint: string;
+    effectiveBaseOid: string;
+    baseStrategy: ApplyBaseStrategy;
+    /** 冲突计算时的真实 Local HEAD，供 Isolated Agent 在当前 Worktree 内同步并解决冲突。 */
+    localHeadOid: string;
+    isolatedHeadOid: string;
+    conflictingFiles: string[];
+}
+export interface ApplyPlanErrorResult {
+    status: 'error';
+    error: ApplyError;
+}
+export type ApplyPlanResult = ApplyReadyPlanResult | ApplyConflictPlanResult | ApplyPlanErrorResult;
+export interface ApplySuccessResult {
+    status: 'applied';
+    changedFiles: string[];
+    /** 本次已整合的 Isolated 快照 commit；不创建 ref，仅供后续 Apply 作为内部基线。 */
+    nextBaseOid: string;
+}
+export interface ApplyErrorResult {
+    status: 'error';
+    error: ApplyError;
+}
+export type ApplyResult = ApplySuccessResult | ApplyErrorResult;
+export interface FinishSuccessResult {
+    status: 'finished';
+    changedFiles: string[];
+    /** null 表示 Worktree 与 Local 已一致，没有创建空提交。 */
+    commitOid: string | null;
+    /** 本次已整合的 Isolated 快照，供清理未完成时后续 Apply 去重。 */
+    nextBaseOid: string;
+}
+export type FinishResult = FinishSuccessResult | ApplyErrorResult;
+export interface InvalidInputApplyError {
+    code: 'invalid_input';
+    message: string;
+}
+export interface InvalidPlanApplyError {
+    code: 'invalid_plan';
+    message: string;
+}
+export interface StaleLocalApplyError {
+    code: 'stale_local';
+    message: string;
+}
+export interface StaleIsolatedApplyError {
+    code: 'stale_isolated';
+    message: string;
+}
+export interface GitApplyError {
+    code: 'git_error';
+    message: string;
+}
+export interface CommitIsolationApplyError {
+    code: 'commit_isolation_conflict';
+    message: string;
+}
+export interface OperationNotAllowedApplyError {
+    code: 'operation_not_allowed';
+    message: string;
+}
+export type ApplyError = InvalidInputApplyError | InvalidPlanApplyError | StaleLocalApplyError | StaleIsolatedApplyError | GitApplyError | CommitIsolationApplyError | OperationNotAllowedApplyError;
+export interface SessionCheckoutApplyEngine {
+    inspectReview(input: ApplyPlanInput): Promise<InspectReviewResult>;
+    /** 复用真实 Apply merge 计算，但不持久化可执行 plan，也不修改任一 checkout。 */
+    preflight(input: ApplyPlanInput): Promise<ApplyPlanResult>;
+    plan(input: ApplyPlanInput): Promise<ApplyPlanResult>;
+    apply(plan: ApplyPlan): Promise<ApplyResult>;
+    finish(plan: ApplyPlan, options: {
+        commitMessage: string;
+    }): Promise<FinishResult>;
+}
+export interface SessionCheckoutApplyEngineOptions {
+    /** 测试/宿主 seam：在最后一次 Local fingerprint 校验前执行。 */
+    beforeFinalLocalValidation?(): Promise<void> | void;
+}
+export declare function createSessionCheckoutApplyEngine(options?: SessionCheckoutApplyEngineOptions): SessionCheckoutApplyEngine;