dsh-git-worktree 0.1.2 → 0.3.0

package/lib/managed-worktree-path.js

@@ -1,18 +1,17 @@
+import { createHash } from 'node:crypto';
 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;
+const DEFAULT_IDENTITY_LENGTH = 8;
 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
+/** Convert a canonical repository basename into one safe, readable path segment. */
+export function sanitizeManagedWorktreeLabel(rawName) {
+    let cleaned = (rawName ?? '')
+        .trim()
         .normalize('NFC')
         .replace(WINDOWS_INVALID_CHARACTERS, '-')
         .replace(/\s+/g, '-')
@@ -21,33 +20,44 @@ export function sanitizeManagedWorktreeLabel(rawTitle) {
     cleaned = truncateCodePoints(cleaned, MAX_LABEL_LENGTH)
         .replace(/[.\s-]+$/g, '');
     if (!cleaned)
-        return 'worktree';
+        return 'repository';
     return WINDOWS_RESERVED_NAME.test(cleaned) ? `_${cleaned}` : cleaned;
 }
-function shortIdentity(value, fallback) {
-    return value.replace(/[^a-zA-Z0-9]/g, '').slice(0, 8) || fallback;
+function checkoutIdentity(value, length) {
+    const normalized = value.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+    if (!normalized)
+        return 'checkout';
+    return normalized.slice(0, Math.max(DEFAULT_IDENTITY_LENGTH, length));
 }
+/** Stable fallback partition that distinguishes repositories sharing one basename. */
+export function createManagedWorktreeRepositoryKey(canonicalGitRoot) {
+    return createHash('sha256').update(canonicalGitRoot).digest('hex').slice(0, 12);
+}
+/** Physical basename: repository identity + trusted checkout identity only. */
 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}`;
+    const repositoryLabel = sanitizeManagedWorktreeLabel(input.repositoryName);
+    const identity = checkoutIdentity(input.checkoutId, input.identityLength ?? DEFAULT_IDENTITY_LENGTH);
+    return `${repositoryLabel}--${identity}--worktree`;
 }
 /**
- * 只生成候选路径，不访问文件系统：
- * - siblingRoot：Git 根目录同级的可读容器；
- * - fallbackRoot：原 Domi 数据目录下、按 repository key 分组的安全回退。
+ * Generate one collision-length candidate without touching the filesystem.
+ * The caller probes 8/12/full checkout identities and chooses the first path
+ * that does not already exist.
  */
 export function createManagedWorktreePathCandidates(input) {
     const repositoryLabel = sanitizeManagedWorktreeLabel(basename(input.localGitRoot));
-    const directoryName = createManagedWorktreeDirectoryName(input);
-    const siblingContainer = join(dirname(input.localGitRoot), `${repositoryLabel}-worktrees`);
+    const directoryName = createManagedWorktreeDirectoryName({
+        repositoryName: repositoryLabel,
+        checkoutId: input.checkoutId,
+        ...(input.identityLength === undefined ? {} : { identityLength: input.identityLength }),
+    });
+    const siblingContainer = join(dirname(input.localGitRoot), `${repositoryLabel}--worktrees`);
+    const fallbackContainer = join(input.managedCheckoutsRoot, 'worktrees', input.repositoryKey);
     return {
         siblingContainer,
         siblingRoot: join(siblingContainer, directoryName),
-        fallbackRoot: join(input.managedCheckoutsRoot, input.repositoryKey, directoryName),
+        fallbackContainer,
+        fallbackRoot: join(fallbackContainer, directoryName),
     };
 }
 //# sourceMappingURL=managed-worktree-path.js.map

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

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

@@ -87,10 +87,11 @@ export interface ManagedCheckoutCreateJournal extends ManagedCheckoutJournalBase
     step: 'creating_worktree';
 }
 export interface ManagedCheckoutMutationJournal extends ManagedCheckoutJournalBase {
-    operation: 'apply' | 'finish' | 'cleanup';
+    operation: 'apply' | 'preview' | 'rollback_preview' | 'finish' | 'finalize_preview' | 'cleanup';
     step: 'planning' | 'artifacts_retained' | 'writing_local' | 'updating_ref' | 'replacing_index' | 'removing_worktree';
     baseOid?: string;
     planRevision?: string;
+    previewId?: string;
     reviewId?: string;
     localFingerprint?: string;
     isolatedFingerprint?: string;
@@ -100,6 +101,8 @@ export interface ManagedCheckoutMutationJournal extends ManagedCheckoutJournalBa
     isolatedHeadOid?: string;
     commitOid?: string;
     retention?: WorktreeRetentionMode;
+    /** rollback_preview crash recovery must preserve whether the review returns to working or ready_for_review. */
+    resumeRevision?: boolean;
     changedFiles?: string[];
     managedDirectoryIdentity?: DirectoryIdentity;
     cleanupQuarantinePath?: string;
@@ -119,6 +122,26 @@ export interface ManagedWorktreeReviewRecord {
     isolatedFingerprint: string;
     isolatedHeadOid: string;
 }
+export interface ManagedPreviewReceipt {
+    previewId: string;
+    reviewId: string;
+    iteration: number;
+    previewedAt: number;
+    configuredBaseOid: string;
+    effectiveBaseOid: string;
+    baseStrategy: ApplyBaseStrategy;
+    localHeadOid: string;
+    localHeadRef: string | null;
+    localFingerprintBefore: string;
+    localFingerprintPreview: string;
+    localWorkingTreeOid: string;
+    localIndexTreeOid: string;
+    previewWorkingTreeOid: string;
+    isolatedHeadOid: string;
+    isolatedFingerprint: string;
+    isolatedSnapshotOid: string;
+    changedFiles: string[];
+}
 export interface ManagedDeliveryProof {
     localBranch: string | null;
     localHeadBefore: string;
@@ -131,6 +154,17 @@ export type ManagedCheckoutDelivery = {
 } | {
     state: 'ready_for_review';
     review: ManagedWorktreeReviewRecord;
+} | {
+    state: 'preview_active';
+    review: ManagedWorktreeReviewRecord;
+    preview: ManagedPreviewReceipt;
+} | {
+    state: 'preview_detached';
+    review: ManagedWorktreeReviewRecord;
+    preview: ManagedPreviewReceipt;
+    detachedAt: number;
+    reason: 'stale_local' | 'preview_modified';
+    attemptedAction: 'rollback_preview' | 'finalize_preview' | 'discard';
 } | {
     state: 'finalized';
     review: ManagedWorktreeReviewRecord;
@@ -162,9 +196,13 @@ export type ManagedCheckoutDelivery = {
 };
 export interface ManagedCheckoutRecord {
     checkoutId: string;
+    /** Prior delivered checkout whose immutable Harness cwd path this iteration safely reuses. */
+    predecessorCheckoutId?: string;
     projectId: string;
     projectName: string;
     ownerSessionId: string;
+    /** Local session that created this target; historical records may omit it. */
+    sourceSessionId?: 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. */

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

@@ -64,6 +64,37 @@ export interface FinishSuccessResult {
     nextBaseOid: string;
 }
 export type FinishResult = FinishSuccessResult | ApplyErrorResult;
+export interface PreviewReceipt {
+    previewId: string;
+    reviewId: string;
+    iteration: number;
+    previewedAt: number;
+    configuredBaseOid: string;
+    effectiveBaseOid: string;
+    baseStrategy: ApplyBaseStrategy;
+    localHeadOid: string;
+    localHeadRef: string | null;
+    localFingerprintBefore: string;
+    localFingerprintPreview: string;
+    localWorkingTreeOid: string;
+    localIndexTreeOid: string;
+    previewWorkingTreeOid: string;
+    isolatedHeadOid: string;
+    isolatedFingerprint: string;
+    isolatedSnapshotOid: string;
+    changedFiles: string[];
+}
+export interface PreviewSuccessResult {
+    status: 'previewed';
+    receipt: PreviewReceipt;
+    changedFiles: string[];
+}
+export type PreviewResult = PreviewSuccessResult | ApplyErrorResult;
+export interface RollbackSuccessResult {
+    status: 'preview_rolled_back';
+    changedFiles: string[];
+}
+export type RollbackResult = RollbackSuccessResult | ApplyErrorResult;
 export interface InvalidInputApplyError {
     code: 'invalid_input';
     message: string;
@@ -92,7 +123,11 @@ export interface OperationNotAllowedApplyError {
     code: 'operation_not_allowed';
     message: string;
 }
-export type ApplyError = InvalidInputApplyError | InvalidPlanApplyError | StaleLocalApplyError | StaleIsolatedApplyError | GitApplyError | CommitIsolationApplyError | OperationNotAllowedApplyError;
+export interface PreviewModifiedApplyError {
+    code: 'preview_modified';
+    message: string;
+}
+export type ApplyError = InvalidInputApplyError | InvalidPlanApplyError | StaleLocalApplyError | StaleIsolatedApplyError | GitApplyError | CommitIsolationApplyError | OperationNotAllowedApplyError | PreviewModifiedApplyError;
 export interface SessionCheckoutApplyEngine {
     inspectReview(input: ApplyPlanInput): Promise<InspectReviewResult>;
     /** 复用真实 Apply merge 计算，但不持久化可执行 plan，也不修改任一 checkout。 */
@@ -102,6 +137,24 @@ export interface SessionCheckoutApplyEngine {
     finish(plan: ApplyPlan, options: {
         commitMessage: string;
     }): Promise<FinishResult>;
+    preview(plan: ApplyPlan, options: {
+        previewId: string;
+        reviewId: string;
+        iteration: number;
+        /** Local 写入前持久化 receipt artifacts/journal；失败时不得触碰 Local。 */
+        beforeWrite?(receipt: PreviewReceipt): Promise<void>;
+    }): Promise<PreviewResult>;
+    rollback(input: {
+        localPath: string;
+        receipt: PreviewReceipt;
+    }): Promise<RollbackResult>;
+    finalize(input: {
+        localPath: string;
+        receipt: PreviewReceipt;
+        commitMessage: string;
+        /** Commit object 已创建但 branch ref 尚未更新时持久化恢复信息。 */
+        beforeCommit?(commitOid: string): Promise<void>;
+    }): Promise<FinishResult>;
 }
 export interface SessionCheckoutApplyEngineOptions {
     /** 测试/宿主 seam：在最后一次 Local fingerprint 校验前执行。 */