mixdog 1.1.2 → 1.2.0

package/src/session-runtime/workspace/project-branches.mjs

@@ -0,0 +1,136 @@
+/**
+ * Session-less branch operations on a registered Project's folder (a New
+ * Task draft, the source-control dock): its branch menu, a guarded checkout
+ * and a guarded merge. They act only on a registered Project (a repository
+ * subfolder Project included) and hold the checkout (withProjectFolder) while
+ * git changes it.
+ */
+import { branchMenuEntries, projectWorkspace, worktreeError } from '../../runtime/shared/worktrees/contract.mjs';
+
+function requireText(value, name) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${name} must be a non-empty string.`);
+  return value.trim();
+}
+
+/**
+ * WORKTREE_UNSUPPORTED_REPO when the project folder has no checked-out branch
+ * to merge into; WORKTREE_TARGET_MISMATCH when the confirmed `target` (null:
+ * none confirmed) is no longer the checked-out branch.
+ */
+export function assertMergeTarget(currentBranch, target) {
+  if (!currentBranch) {
+    throw worktreeError('WORKTREE_UNSUPPORTED_REPO', 'The project folder has no checked-out branch to merge into.');
+  }
+  if (target !== null && target !== currentBranch) {
+    throw worktreeError(
+      'WORKTREE_TARGET_MISMATCH',
+      `The project folder is now on "${currentBranch}"; confirm the merge again.`,
+      { target, current: currentBranch }
+    );
+  }
+}
+
+/**
+ * @param {object} deps
+ * @param {() => Promise<any>} deps.backend The managed-worktree backend.
+ * @param {(path: string) => Promise<any>} deps.inspectProject
+ * @param {(path: string) => Promise<string|null>} deps.findRegisteredProject
+ * @param {<T>(sessionId: string|null, folder: string, fn: () => Promise<T>) => Promise<T>} deps.withProjectFolder
+ */
+export function createProjectBranchOps({ backend, inspectProject, findRegisteredProject, withProjectFolder }) {
+  /** WORKTREE_PROJECT_UNKNOWN unless `projectPath` is a registered Project. */
+  async function registeredProject(projectPath) {
+    const path = requireText(projectPath, 'projectPath');
+    const registered = await findRegisteredProject(path);
+    if (!registered) throw worktreeError('WORKTREE_PROJECT_UNKNOWN', undefined, { projectPath: path });
+    return registered;
+  }
+
+  /**
+   * A Project's branch menu with no session: the project folder's workspace
+   * and the real occupancy (current / session / external / free).
+   */
+  async function getProjectBranchMenu({ projectPath } = {}) {
+    const path = await registeredProject(projectPath);
+    const project = await inspectProject(path);
+    const menu = await (await backend()).listBranchOccupancy({ projectPath: path, sessionId: null });
+    return {
+      workspace: projectWorkspace({
+        projectPath: path,
+        repoCommonDir: project.repoCommonDir,
+        branch: project.currentBranch,
+      }),
+      branches: branchMenuEntries(menu.branches, menu.occupancy),
+      occupancy: menu.occupancy,
+      retainedWorktree: null,
+    };
+  }
+
+  /**
+   * Check out (or create) `branch` in a Project folder with no session: the
+   * same guarded path a session's branch change takes — refused while another
+   * session works in the checkout, which is held until the switch is done;
+   * the manager's repository lock, occupancy and no-carry (dirty) checks.
+   */
+  async function selectProjectBranch({
+    projectPath,
+    branch,
+    create = false,
+    remote = false,
+    startPoint = null,
+    detach = null,
+  } = {}) {
+    const path = await registeredProject(projectPath);
+    if (detach !== null) {
+      // A history entry checked out detached: the same guard, no branch.
+      if (branch !== undefined || create === true || remote === true || startPoint !== null) {
+        throw new TypeError('detach excludes branch, create, remote and startPoint.');
+      }
+      const commit = requireText(detach, 'detach');
+      const project = await inspectProject(path);
+      return withProjectFolder(null, project.topLevel || path, async () =>
+        (await backend()).checkoutProjectBranch({ projectPath: path, detach: commit })
+      );
+    }
+    const name = requireText(branch, 'branch');
+    if (create === true && remote === true) throw new TypeError('create and remote are exclusive.');
+    if (startPoint !== null && create !== true) throw new TypeError('startPoint needs create.');
+    const project = await inspectProject(path);
+    if (create !== true && remote !== true && project.currentBranch === name) return { branch: name, changed: false };
+    return withProjectFolder(null, project.topLevel || path, async () => {
+      const backendApi = await backend();
+      return backendApi.checkoutProjectBranch({
+        projectPath: path,
+        branch: name,
+        create: create === true,
+        remote: remote === true,
+        ...(startPoint !== null ? { startPoint: requireText(startPoint, 'startPoint') } : {}),
+      });
+    });
+  }
+
+  /**
+   * Merge a local branch into a Project folder's checked-out branch with no
+   * session: `target` is the branch the user confirmed and must still be
+   * checked out (WORKTREE_TARGET_MISMATCH); refused while another session
+   * works in that checkout, which is held (turn admission waits) until the
+   * merge is done.
+   */
+  async function mergeProjectBranch({ projectPath, branch, target } = {}) {
+    const path = await registeredProject(projectPath);
+    const source = requireText(branch, 'branch');
+    const confirmedTarget = requireText(target, 'target');
+    const project = await inspectProject(path);
+    assertMergeTarget(project.currentBranch, confirmedTarget);
+    return withProjectFolder(null, project.topLevel || path, async () =>
+      (await backend()).mergeBranchIntoProject({
+        projectPath: path,
+        source,
+        target: confirmedTarget,
+        confirmed: true,
+      })
+    );
+  }
+
+  return { getProjectBranchMenu, selectProjectBranch, mergeProjectBranch };
+}

package/src/session-runtime/workspace/transition-steps.mjs

@@ -0,0 +1,364 @@
+/**
+ * The steps of one Lead workspace transaction (transitions.mjs runs them
+ * serialized): commit a new workspace, enter the retained or a new worktree,
+ * move to a project-folder branch, remove the retained worktree. Every step
+ * pushes the exact undo of what it changed onto the transaction `journal`;
+ * the caller runs it (undoAll) when the transaction fails.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import {
+  isWorktreeBound,
+  isWorktreeError,
+  nextRevision,
+  normalizeSessionWorkspace,
+  worktreeError,
+} from '../../runtime/shared/worktrees/contract.mjs';
+import { throwIfAborted } from '../../runtime/shared/worktrees/git.mjs';
+import { checkoutFolder, projectSubdirOf, samePath } from '../../runtime/shared/worktrees/paths.mjs';
+import { setWorkspaceCwdLock, workspaceCwdLock } from './admission-gate.mjs';
+import { copyProjectIdentity } from './workspace-state.mjs';
+
+const PROMPT_FIELDS = ['bp3EnvironmentContext', 'bp3CoreContext', 'sessionStartMetaInjected'];
+
+/** Everything a prompt refresh rewrites on `target`, restorable exactly. */
+function snapshotPrompt(target) {
+  const fields = PROMPT_FIELDS.map((name) => [name, Object.hasOwn(target, name), target[name]]);
+  const messages = Array.isArray(target.messages) ? [...target.messages] : null;
+  return () => {
+    for (const [name, had, value] of fields) {
+      if (had) target[name] = value;
+      else delete target[name];
+    }
+    if (!messages) return;
+    if (Array.isArray(target.messages)) target.messages.splice(0, target.messages.length, ...messages);
+    else target.messages = messages;
+  };
+}
+
+/** Run a failed transaction's undo steps newest first; every step runs. */
+export async function undoAll(journal, error) {
+  const failures = [];
+  for (const undo of journal.reverse()) {
+    try {
+      await undo();
+    } catch (cause) {
+      failures.push(cause);
+    }
+  }
+  if (failures.length && error && typeof error === 'object') error.rollbackErrors = failures;
+}
+
+/**
+ * WORKTREE_PROJECT_MISMATCH unless the retained `entry` was created for the
+ * same repository and the same Project folder inside it (a Project switch may
+ * have left it behind).
+ */
+export function assertRetainedFits(entry, project, projectPath) {
+  const subdir = projectSubdirOf(project.topLevel, project.projectPath || projectPath);
+  if (samePath(entry.repoCommonDir, project.repoCommonDir) && (entry.projectSubdir || '') === subdir) return;
+  throw worktreeError('WORKTREE_PROJECT_MISMATCH', undefined, {
+    worktreeId: entry.id,
+    worktreeProject: entry.projectPath,
+    projectPath,
+  });
+}
+
+/**
+ * WORKTREE_REMOVAL_INCOMPLETE: the deletion started (the record stays
+ * `deleting`) but something in the folder is still held. The session keeps
+ * the project folder — never a cwd that may already be deleted — and
+ * removeWorktree again resumes the deletion.
+ */
+function incompleteRemoval(journal, entry, result, outcome) {
+  journal.length = 0;
+  return worktreeError('WORKTREE_REMOVAL_INCOMPLETE', undefined, {
+    entryId: entry.id,
+    path: entry.path,
+    retryable: outcome?.retryable !== false,
+    remaining: Array.isArray(outcome?.remaining) ? outcome.remaining : [],
+    ...(outcome?.reason ? { reason: outcome.reason } : {}),
+    revision: result.revision,
+  });
+}
+
+/**
+ * @param {object} deps The host hooks of createWorkspaceTransitions plus its
+ *   `backend()` loader, `workersOf(session)` and `withProjectFolder`.
+ */
+export function createTransitionSteps({
+  backend,
+  inspectProject,
+  runtimeToken,
+  getCurrentCwd,
+  applyResolvedCwd,
+  persistSession,
+  refreshWorkspaceContext,
+  invalidateCaches,
+  updateLeadWorkerCwd,
+  workersOf,
+  withProjectFolder,
+}) {
+  const owner = (sessionId) => ({ sessionId, runtimeToken, pid: process.pid });
+
+  /** Point this Lead's idle workers at the new root so a reused worker never keeps an old workspace. */
+  async function retargetWorkers(session, cwd, journal) {
+    for (const worker of workersOf(session)) {
+      if (samePath(worker.cwd || '', cwd)) continue;
+      const priorCwd = worker.cwd;
+      const restorePrompt = snapshotPrompt(worker);
+      journal.push(() => {
+        worker.cwd = priorCwd;
+        restorePrompt();
+        worker.updatedAt = Date.now();
+        persistSession(worker);
+      });
+      worker.cwd = cwd;
+      await refreshWorkspaceContext(worker, cwd);
+      worker.updatedAt = Date.now();
+      persistSession(worker);
+    }
+  }
+
+  /**
+   * Apply the new workspace: runtime cwd, record, worker lock, prompt context
+   * of the Lead and its idle workers, persistence. Journals the exact undo
+   * (cwd, record, lock, prompts, worker roots) for a transaction that fails
+   * after this point.
+   */
+  async function commit(session, previous, fields, journal) {
+    const moveLeadRow = (cwd) => {
+      try {
+        updateLeadWorkerCwd(session.id, cwd);
+      } catch {
+        /* the Lead pool must never break a transition */
+      }
+    };
+    const next = normalizeSessionWorkspace({
+      ...fields,
+      revision: nextRevision(previous),
+      transition: { state: 'idle', txId: null },
+    });
+    const prior = {
+      cwd: getCurrentCwd(),
+      sessionCwd: session.cwd,
+      workspace: session.workspace,
+      lock: workspaceCwdLock([session.id]),
+      prompt: snapshotPrompt(session),
+    };
+    journal.push(() => {
+      applyResolvedCwd(prior.cwd);
+      session.cwd = prior.sessionCwd;
+      session.workspace = prior.workspace;
+      setWorkspaceCwdLock(session.id, prior.lock);
+      prior.prompt();
+      session.updatedAt = Date.now();
+      persistSession(session);
+      moveLeadRow(prior.sessionCwd || prior.cwd);
+      invalidateCaches();
+    });
+    applyResolvedCwd(next.cwd);
+    session.cwd = next.cwd;
+    session.workspace = next;
+    moveLeadRow(next.cwd);
+    setWorkspaceCwdLock(session.id, isWorktreeBound(next) ? next.cwd : null);
+    await refreshWorkspaceContext(session, next.cwd);
+    await retargetWorkers(session, next.cwd, journal);
+    session.updatedAt = Date.now();
+    persistSession(session);
+    invalidateCaches();
+    return { revision: next.revision, workspace: next };
+  }
+
+  async function releaseOwner(backendApi, entryId, sessionId) {
+    try {
+      await backendApi.releaseWorktreeOwner(entryId, owner(sessionId));
+    } catch (error) {
+      // A worktree that vanished has no owner left to release.
+      if (!isWorktreeError(error, 'WORKTREE_MISSING')) throw error;
+    }
+  }
+
+  async function enterWorktree(session, previous, { name, nameHint, confirmLarge, signal, txId, journal }) {
+    const backendApi = await backend();
+    const projectPath = previous.projectPath;
+    const project = await inspectProject(projectPath, { signal });
+    let entry = await backendApi.getSessionWorktree(session.id);
+    if (entry) {
+      if (!existsSync(entry.path)) {
+        throw worktreeError('WORKTREE_MISSING', undefined, { worktreeId: entry.id, path: entry.path });
+      }
+      if (isWorktreeBound(previous) && previous.worktreeId === entry.id) {
+        return { revision: previous.revision, workspace: previous };
+      }
+      assertRetainedFits(entry, project, projectPath);
+      await backendApi.claimWorktreeOwner(entry.id, owner(session.id));
+      journal.push(() => releaseOwner(backendApi, entry.id, session.id));
+    } else {
+      // The backend resolves the base branch commit (from the project
+      // folder's checked-out branch), sizes and creates the checkout; the
+      // txId makes a retried or duplicate send return the same worktree.
+      entry = await backendApi.createManagedWorktree({
+        projectPath,
+        sessionId: session.id,
+        runtimeToken,
+        baseBranch: project.currentBranch,
+        nameHint: name ?? nameHint ?? '',
+        confirmLarge: confirmLarge === true,
+        txId,
+        signal,
+      });
+    }
+    // Cancelled after the worktree exists: it stays retained (same txId on
+    // retry), the session does not move.
+    throwIfAborted(signal);
+    // A Project registered below the repository root runs in the same
+    // subfolder of the worktree (and returns to its own folder on the way back).
+    const cwd = checkoutFolder(entry.path, projectSubdirOf(project.topLevel, project.projectPath || projectPath));
+    if (!existsSync(cwd)) mkdirSync(cwd, { recursive: true });
+    copyProjectIdentity(projectPath, cwd);
+    const entered = await commit(
+      session,
+      previous,
+      {
+        projectPath,
+        repoCommonDir: entry.repoCommonDir || project.repoCommonDir,
+        cwd,
+        worktreeId: entry.id,
+        branch: entry.branch,
+        baseCommit: entry.baseCommit,
+        mergeTarget: project.currentBranch,
+      },
+      journal
+    );
+    // Creation notes (submodules, include entries missing or already present).
+    return { ...entered, warnings: Array.isArray(entry.warnings) ? [...entry.warnings] : [] };
+  }
+
+  async function enterProjectBranch(session, previous, { branch, create, signal, journal }) {
+    const backendApi = await backend();
+    const projectPath = previous.projectPath;
+    const project = await inspectProject(projectPath, { signal });
+    const bound = isWorktreeBound(previous);
+    const finalize = async () => {
+      const result = await commit(
+        session,
+        previous,
+        { projectPath, repoCommonDir: project.repoCommonDir, cwd: projectPath, branch },
+        journal
+      );
+      if (bound) await releaseOwner(backendApi, previous.worktreeId, session.id);
+      return result;
+    };
+    if (create !== true && project.currentBranch === branch) {
+      if (!bound && previous.branch === branch && samePath(previous.cwd, projectPath)) {
+        return { revision: previous.revision, workspace: previous };
+      }
+      return finalize();
+    }
+    // The checkout stays held until the session is finalized on it, or put
+    // back: no other session's turn starts on a half-switched folder.
+    return withProjectFolder(session.id, project.topLevel || projectPath, async () => {
+      await backendApi.checkoutProjectBranch({ projectPath, branch, create: create === true });
+      try {
+        return await finalize();
+      } catch (error) {
+        await undoAll(journal, error);
+        journal.length = 0;
+        const context = { backendApi, projectPath, project, branch, bound, error };
+        throw await revertProjectCheckout(session, previous, context);
+      }
+    });
+  }
+
+  /**
+   * A branch switch whose finalization failed after git switched: switch the
+   * project folder back when that is safe (the manager refuses a dirty tree
+   * or a vanished branch) and rethrow the cause. Otherwise the session record
+   * is made to match the real checkout and the failure becomes
+   * WORKTREE_PARTIAL_TRANSITION naming the branch actually checked out.
+   */
+  async function revertProjectCheckout(session, previous, context) {
+    const { backendApi, projectPath, project, branch, bound, error } = context;
+    const previousBranch = project.currentBranch;
+    let revertError = null;
+    if (previousBranch) {
+      try {
+        await backendApi.checkoutProjectBranch({ projectPath, branch: previousBranch });
+        return error;
+      } catch (cause) {
+        revertError = cause;
+      }
+    }
+    if (!bound) {
+      // The session runs in the project folder, which is now on `branch`.
+      session.workspace = normalizeSessionWorkspace({
+        ...previous,
+        repoCommonDir: project.repoCommonDir,
+        branch,
+        revision: nextRevision(previous),
+        transition: { state: 'idle', txId: null },
+      });
+      session.updatedAt = Date.now();
+      persistSession(session);
+      invalidateCaches();
+    }
+    return worktreeError(
+      'WORKTREE_PARTIAL_TRANSITION',
+      `The branch change failed (${error?.message || error}) and the project folder could not be switched back` +
+        `${previousBranch ? ` to "${previousBranch}"` : ''}; it is now on "${branch}".`,
+      {
+        checkout: branch,
+        previousBranch: previousBranch ?? null,
+        reason: String(error?.message || error),
+        revertReason: revertError ? String(revertError.message || revertError) : 'detached',
+      }
+    );
+  }
+
+  /**
+   * Validate the removal first (a dirty or unmerged worktree without `force`
+   * refuses with the session untouched), then return the session to its
+   * project folder, release the live lease and remove. A removal that still
+   * fails puts the session back exactly (the transaction journal).
+   */
+  async function removeRetainedWorktree(session, previous, { force, signal, journal }) {
+    const backendApi = await backend();
+    const entry = await backendApi.getSessionWorktree(session.id);
+    if (entry) await backendApi.assertWorktreeRemovable({ entryId: entry.id, force: force === true });
+    let result = { revision: previous.revision, workspace: previous };
+    if (isWorktreeBound(previous)) {
+      const project = await inspectProject(previous.projectPath, { signal });
+      result = await commit(
+        session,
+        previous,
+        {
+          projectPath: previous.projectPath,
+          repoCommonDir: project.repoCommonDir,
+          cwd: previous.projectPath,
+          branch: project.currentBranch,
+        },
+        journal
+      );
+      if (entry) {
+        await releaseOwner(backendApi, entry.id, session.id);
+        journal.push(() => backendApi.claimWorktreeOwner(entry.id, owner(session.id)));
+      }
+    }
+    if (!entry) return { ...result, removed: null };
+    let removed;
+    try {
+      removed = await backendApi.removeManagedWorktree({ entryId: entry.id, force: force === true });
+    } catch (error) {
+      // Refused before anything was deleted: the journal puts the session back.
+      // Once the checkout may be (partly) gone, the session stays in the
+      // project folder and the removal is reported incomplete.
+      const now = await backendApi.getSessionWorktree(session.id).catch(() => entry);
+      if (now?.id === entry.id && now.state === 'ready' && existsSync(entry.path)) throw error;
+      throw incompleteRemoval(journal, entry, result, { reason: String(error?.message || error) });
+    }
+    if (removed?.removed !== true) throw incompleteRemoval(journal, entry, result, removed);
+    return { ...result, removed };
+  }
+
+  return { enterWorktree, enterProjectBranch, removeRetainedWorktree };
+}