@ricsam/r5d-worker 0.0.78 → 0.0.80

package/dist/mjs/managed-paths.mjs

@@ -4,6 +4,104 @@ const BRANCH_NAME_MAX_LENGTH = 45;
 const BRANCH_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*$/;
 const PROJECT_SEGMENT_PATTERN = /^[a-z0-9._-]+$/;
 const WINDOWS_RESERVED_PATH_SEGMENT = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+const INTERNAL_PROJECT_PATH_SEGMENTS = /* @__PURE__ */ new Set([".r5d-retired-checkouts"]);
+function lstatIfExists(targetPath) {
+  try {
+    return fs.lstatSync(targetPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+function fsyncDirectory(directoryPath) {
+  const descriptor = fs.openSync(directoryPath, "r");
+  try {
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+function fsyncCreatedDirectoryChain(directoryPath, preexistingAncestorPath) {
+  let current = path.resolve(directoryPath);
+  const ancestor = path.resolve(preexistingAncestorPath);
+  const relative = path.relative(ancestor, current);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`Managed root escaped its durability ancestor: ${current}`);
+  }
+  while (true) {
+    fsyncDirectory(current);
+    if (current === ancestor) return;
+    current = path.dirname(current);
+  }
+}
+function canonicalizeManagedRoot(root) {
+  const resolvedRoot = path.resolve(root.rootPath);
+  let preexistingAncestor = resolvedRoot;
+  while (!lstatIfExists(preexistingAncestor)) {
+    const parent = path.dirname(preexistingAncestor);
+    if (parent === preexistingAncestor) {
+      throw new Error(`Could not find an existing ancestor for ${root.label} (${resolvedRoot})`);
+    }
+    preexistingAncestor = parent;
+  }
+  let canonicalPreexistingAncestor;
+  try {
+    canonicalPreexistingAncestor = fs.realpathSync(preexistingAncestor);
+    if (!fs.statSync(canonicalPreexistingAncestor).isDirectory()) {
+      throw new Error("the nearest existing ancestor is not a directory");
+    }
+  } catch (error) {
+    throw new Error(`Could not validate the existing ancestor of ${root.label} (${resolvedRoot})`, { cause: error });
+  }
+  try {
+    fs.mkdirSync(resolvedRoot, { recursive: true });
+  } catch (error) {
+    throw new Error(`Could not prepare ${root.label} (${resolvedRoot}) for overlap validation`, { cause: error });
+  }
+  const rootStats = fs.statSync(resolvedRoot, { bigint: true });
+  if (!rootStats.isDirectory()) {
+    throw new Error(`Managed root is not a directory: ${root.label} (${resolvedRoot})`);
+  }
+  const canonicalRoot = fs.realpathSync(resolvedRoot);
+  fsyncCreatedDirectoryChain(canonicalRoot, canonicalPreexistingAncestor);
+  return {
+    ...root,
+    rootPath: canonicalRoot,
+    identity: { device: rootStats.dev, inode: rootStats.ino }
+  };
+}
+function pathContains(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative);
+}
+function identitiesMatch(left, right) {
+  return left.device === right.device && left.inode === right.inode;
+}
+function pathOrFilesystemContains(root, candidate) {
+  if (pathContains(root.rootPath, candidate.rootPath) || identitiesMatch(root.identity, candidate.identity)) {
+    return true;
+  }
+  let ancestor = path.dirname(candidate.rootPath);
+  while (true) {
+    const stats = fs.statSync(ancestor, { bigint: true });
+    if (identitiesMatch(root.identity, { device: stats.dev, inode: stats.ino })) return true;
+    const parent = path.dirname(ancestor);
+    if (parent === ancestor) return false;
+    ancestor = parent;
+  }
+}
+function assertDisjointManagedRoots(roots) {
+  const canonical = roots.map(canonicalizeManagedRoot);
+  for (let leftIndex = 0; leftIndex < canonical.length; leftIndex += 1) {
+    const left = canonical[leftIndex];
+    for (let rightIndex = leftIndex + 1; rightIndex < canonical.length; rightIndex += 1) {
+      const right = canonical[rightIndex];
+      if (pathOrFilesystemContains(left, right) || pathOrFilesystemContains(right, left)) {
+        throw new Error(`Managed roots overlap: ${left.label} (${left.rootPath}) and ${right.label} (${right.rootPath}) must be disjoint`);
+      }
+    }
+  }
+}
 function validateManagedBranchName(branchName) {
   if (typeof branchName !== "string" || branchName.length === 0) {
     throw new Error("Branch name is required");
@@ -25,7 +123,7 @@ function validateCheckoutPathSegments(value) {
   }
   const segments = value;
   for (const segment of segments) {
-    if (typeof segment !== "string" || !PROJECT_SEGMENT_PATTERN.test(segment) || segment !== segment.toLowerCase() || segment === "." || segment === ".." || segment === ".git" || segment.endsWith(".") || WINDOWS_RESERVED_PATH_SEGMENT.test(segment)) {
+    if (typeof segment !== "string" || !PROJECT_SEGMENT_PATTERN.test(segment) || segment !== segment.toLowerCase() || segment === "." || segment === ".." || segment === ".git" || INTERNAL_PROJECT_PATH_SEGMENTS.has(segment) || segment.endsWith(".") || WINDOWS_RESERVED_PATH_SEGMENT.test(segment)) {
       throw new Error(`Invalid checkout path segment from server: ${String(segment)}`);
     }
   }
@@ -67,6 +165,7 @@ function managedBranchPath(projectsRoot, checkoutPathSegments, branchName) {
 export {
   BRANCH_NAME_MAX_LENGTH,
   BRANCH_NAME_PATTERN,
+  assertDisjointManagedRoots,
   assertPathInside,
   managedBranchPath,
   managedProjectRoot,

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.78",
+  "version": "0.0.80",
   "type": "module"
 }

package/dist/mjs/project-workspace-state.mjs

@@ -11,10 +11,39 @@ const PROJECT_WORKSPACE_STATE_FILE = "project-workspace-state.json";
 const PROJECT_WORKSPACE_STATE_VERSION = 1;
 const PROJECT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const GIT_OBJECT_ID_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+class ProjectWorkspacePendingBranchPathChangeError extends Error {
+  projectId;
+  branchName;
+  currentCheckoutPathSegments;
+  incomingCheckoutPathSegments;
+  constructor(input) {
+    super(`Cannot move project ${input.projectId} while creator-local branch ${input.branchName} is pending publication`);
+    this.name = "ProjectWorkspacePendingBranchPathChangeError";
+    this.projectId = input.projectId;
+    this.branchName = input.branchName;
+    this.currentCheckoutPathSegments = [...input.currentCheckoutPathSegments];
+    this.incomingCheckoutPathSegments = [...input.incomingCheckoutPathSegments];
+  }
+}
+class ProjectWorkspaceCheckoutPathCollisionError extends Error {
+  projectId;
+  occupyingProjectId;
+  checkoutPathSegments;
+  constructor(input) {
+    super(
+      `Cannot assign checkout path ${input.checkoutPathSegments.join("/")} to project ${input.projectId} while project ${input.occupyingProjectId} still owns a durable checkout or deletion tombstone there`
+    );
+    this.name = "ProjectWorkspaceCheckoutPathCollisionError";
+    this.projectId = input.projectId;
+    this.occupyingProjectId = input.occupyingProjectId;
+    this.checkoutPathSegments = [...input.checkoutPathSegments];
+  }
+}
 const EMPTY_STATE = {
   version: PROJECT_WORKSPACE_STATE_VERSION,
   desiredProjects: [],
   locallyPendingCreatedBranches: [],
+  enabledRepositoryTransitions: [],
   tombstones: []
 };
 function isRecord(value) {
@@ -85,12 +114,36 @@ function normalizePendingCreatedBranches(value) {
     }
     const projectId = validateProjectId(entry.projectId);
     validateManagedBranchName(entry.branchName);
-    return { projectId, branchName: entry.branchName };
+    if (entry.branchId !== void 0 && (typeof entry.branchId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(entry.branchId))) {
+      throw new Error("Invalid durable locally pending project branch id");
+    }
+    return { ...entry.branchId ? { branchId: entry.branchId } : {}, projectId, branchName: entry.branchName };
   });
   const keys = pending.map(({ projectId, branchName }) => `${projectId}\0${branchName}`);
   if (new Set(keys).size !== keys.length) throw new Error("Duplicate durable locally pending project branch");
   return pending.sort((left, right) => left.projectId.localeCompare(right.projectId) || left.branchName.localeCompare(right.branchName));
 }
+function normalizePreserveOnlyBranches(value) {
+  const normalized = normalizePendingCreatedBranches(value);
+  if (normalized.some(({ branchId }) => !branchId)) throw new Error("Preserve-only branch is missing its durable branch id");
+  return normalized;
+}
+function normalizeEnabledRepositoryTransitions(value) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value)) throw new Error("Invalid durable enabled repository transitions");
+  const transitions = value.map((entry) => {
+    if (!isRecord(entry)) throw new Error("Invalid durable enabled repository transition");
+    const projectId = validateProjectId(entry.projectId);
+    if (entry.transitionId !== null && (typeof entry.transitionId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(entry.transitionId))) {
+      throw new Error("Invalid durable enabled repository transition id");
+    }
+    return { projectId, transitionId: entry.transitionId };
+  });
+  if (new Set(transitions.map(({ projectId }) => projectId)).size !== transitions.length) {
+    throw new Error("Duplicate durable enabled repository transition project");
+  }
+  return transitions.sort((left, right) => left.projectId.localeCompare(right.projectId));
+}
 function tombstoneBranchNames(tombstone) {
   return tombstone.kind === "branch" ? [tombstone.branchName] : tombstone.branchNames;
 }
@@ -164,6 +217,7 @@ function normalizeState(value) {
   }
   const desiredProjects = normalizeDesiredProjects(value.desiredProjects);
   const locallyPendingCreatedBranches = normalizePendingCreatedBranches(value.locallyPendingCreatedBranches);
+  const enabledRepositoryTransitions = normalizeEnabledRepositoryTransitions(value.enabledRepositoryTransitions);
   const desiredById = new Map(desiredProjects.map((project) => [project.projectId, project]));
   for (const pending of locallyPendingCreatedBranches) {
     const project = desiredById.get(pending.projectId);
@@ -179,6 +233,7 @@ function normalizeState(value) {
     version: PROJECT_WORKSPACE_STATE_VERSION,
     desiredProjects,
     locallyPendingCreatedBranches,
+    enabledRepositoryTransitions,
     tombstones: tombstones.sort((left, right) => left.id.localeCompare(right.id))
   };
 }
@@ -217,8 +272,41 @@ function fsyncDirectory(directory) {
     if (descriptor !== void 0) fs.closeSync(descriptor);
   }
 }
-function writeStateAtomically(stateRoot, statePath, state) {
-  fs.mkdirSync(stateRoot, { recursive: true, mode: 448 });
+function lstatIfExists(targetPath) {
+  try {
+    return fs.lstatSync(targetPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+function ensureDurableStateRoot(stateRoot) {
+  const resolvedStateRoot = path.resolve(stateRoot);
+  let existingAncestor = resolvedStateRoot;
+  while (!lstatIfExists(existingAncestor)) {
+    const parent = path.dirname(existingAncestor);
+    if (parent === existingAncestor) throw new Error(`Project workspace state has no existing ancestor: ${resolvedStateRoot}`);
+    existingAncestor = parent;
+  }
+  const ancestorStat = lstatIfExists(existingAncestor);
+  if (!ancestorStat || ancestorStat.isSymbolicLink() || !ancestorStat.isDirectory()) {
+    throw new Error(`Project workspace state must descend from a real directory: ${resolvedStateRoot}`);
+  }
+  fs.mkdirSync(resolvedStateRoot, { recursive: true, mode: 448 });
+  let current = resolvedStateRoot;
+  while (true) {
+    const stat = lstatIfExists(current);
+    if (!stat || stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error(`Project workspace state path must be a real directory: ${current}`);
+    }
+    fsyncDirectory(current);
+    if (current === existingAncestor) break;
+    current = path.dirname(current);
+  }
+}
+function writeStateAtomically(stateRoot, statePath, state, afterStateRootFsync) {
+  ensureDurableStateRoot(stateRoot);
+  afterStateRootFsync?.();
   const temporaryPath = path.join(stateRoot, `.${PROJECT_WORKSPACE_STATE_FILE}.${process.pid}.${randomUUID()}.tmp`);
   let descriptor;
   try {
@@ -326,7 +414,12 @@ function mergePendingCreatedBranches(...groups) {
   const byKey = /* @__PURE__ */ new Map();
   for (const pending of groups.flat()) {
     const normalized = normalizePendingCreatedBranches([pending])[0];
-    byKey.set(pendingCreatedBranchKey(normalized), normalized);
+    const key = pendingCreatedBranchKey(normalized);
+    const existing = byKey.get(key);
+    if (existing?.branchId && normalized.branchId && existing.branchId !== normalized.branchId) {
+      throw new Error(`Pending local branch ${normalized.projectId}/${normalized.branchName} changed durable branch id`);
+    }
+    byKey.set(key, normalized.branchId ? normalized : existing ?? normalized);
   }
   return [...byKey.values()].sort(
     (left, right) => left.projectId.localeCompare(right.projectId) || left.branchName.localeCompare(right.branchName)
@@ -431,6 +524,7 @@ function stateView(projectsRoot, state) {
     desiredProjects: cloneDesiredProjects(state.desiredProjects),
     effectiveDesiredProjects: effectiveProjects,
     locallyPendingCreatedBranches: state.locallyPendingCreatedBranches.map((pending) => ({ ...pending })),
+    enabledRepositoryTransitions: state.enabledRepositoryTransitions.map((transition) => ({ ...transition })),
     tombstones: cloneTombstones(state.tombstones),
     pendingTreeDeletions,
     pendingMirrorRefDeletions
@@ -605,14 +699,51 @@ class ProjectWorkspaceStateStore {
   reconcile(input) {
     const previous = readState(this.statePath);
     const authoritativeDesiredProjects = normalizeDesiredProjects(input.desiredProjects);
+    for (const project of authoritativeDesiredProjects) {
+      const occupyingProjectId = previous.desiredProjects.find(
+        (candidate) => candidate.projectId !== project.projectId && samePathSegments(candidate.checkoutPathSegments, project.checkoutPathSegments)
+      )?.projectId ?? previous.tombstones.find(
+        (candidate) => candidate.projectId !== project.projectId && samePathSegments(candidate.checkoutPathSegments, project.checkoutPathSegments)
+      )?.projectId;
+      if (occupyingProjectId) {
+        throw new ProjectWorkspaceCheckoutPathCollisionError({
+          projectId: project.projectId,
+          occupyingProjectId,
+          checkoutPathSegments: project.checkoutPathSegments
+        });
+      }
+    }
     const authoritativeProjectIds = new Set(authoritativeDesiredProjects.map(({ projectId }) => projectId));
+    const preserveOnlyBranches = normalizePreserveOnlyBranches(input.preserveOnlyBranches ?? []);
+    for (const preserved of preserveOnlyBranches) {
+      const project = authoritativeDesiredProjects.find(({ projectId }) => projectId === preserved.projectId);
+      if (!project) {
+        throw new Error(`Preserve-only branch ${preserved.projectId}/${preserved.branchName} has no desired project`);
+      }
+      if (project.branches.some(({ branchName }) => branchName === preserved.branchName)) {
+        throw new Error(`Preserve-only branch ${preserved.projectId}/${preserved.branchName} is already active`);
+      }
+    }
     const locallyPendingCreatedBranches = mergePendingCreatedBranches(
       previous.locallyPendingCreatedBranches,
       input.locallyPendingCreatedBranches ?? []
     ).filter(
       (pending) => authoritativeProjectIds.has(pending.projectId) && !desiredProjectHasBranch(authoritativeDesiredProjects, pending)
     );
+    for (const pending of locallyPendingCreatedBranches) {
+      const currentProject = previous.desiredProjects.find(({ projectId }) => projectId === pending.projectId);
+      const incomingProject = authoritativeDesiredProjects.find(({ projectId }) => projectId === pending.projectId);
+      if (currentProject && incomingProject && !samePathSegments(currentProject.checkoutPathSegments, incomingProject.checkoutPathSegments)) {
+        throw new ProjectWorkspacePendingBranchPathChangeError({
+          projectId: pending.projectId,
+          branchName: pending.branchName,
+          currentCheckoutPathSegments: currentProject.checkoutPathSegments,
+          incomingCheckoutPathSegments: incomingProject.checkoutPathSegments
+        });
+      }
+    }
     const desiredProjects = cloneDesiredProjects(authoritativeDesiredProjects);
+    applyPendingCreatedBranches(desiredProjects, preserveOnlyBranches);
     applyPendingCreatedBranches(desiredProjects, locallyPendingCreatedBranches);
     const desiredById = new Map(desiredProjects.map((project) => [project.projectId, project]));
     const tombstones = cloneTombstones(previous.tombstones);
@@ -638,16 +769,36 @@ class ProjectWorkspaceStateStore {
       version: PROJECT_WORKSPACE_STATE_VERSION,
       desiredProjects,
       locallyPendingCreatedBranches,
+      enabledRepositoryTransitions: previous.enabledRepositoryTransitions.filter(({ projectId }) => authoritativeProjectIds.has(projectId)),
       tombstones
     });
     writeStateAtomically(this.stateRoot, this.statePath, nextState);
     return stateView(this.projectsRoot, nextState);
   }
+  /** Record a successful enabled reseed without letting disabled config consume it. */
+  recordEnabledRepositoryTransition(input) {
+    const [transition] = normalizeEnabledRepositoryTransitions([input]);
+    const state = readState(this.statePath);
+    if (!state.desiredProjects.some(({ projectId }) => projectId === transition.projectId)) {
+      throw new Error(`Cannot record an enabled repository transition for missing project ${transition.projectId}`);
+    }
+    state.enabledRepositoryTransitions = state.enabledRepositoryTransitions.filter(({ projectId }) => projectId !== transition.projectId);
+    state.enabledRepositoryTransitions.push(transition);
+    state.enabledRepositoryTransitions.sort((left, right) => left.projectId.localeCompare(right.projectId));
+    writeStateAtomically(this.stateRoot, this.statePath, state);
+    return stateView(this.projectsRoot, state);
+  }
   /** Persist the create intent before invoking Git so a crash cannot orphan an untracked worktree. */
   recordPendingCreatedBranch(input) {
     const [pending] = normalizePendingCreatedBranches([input]);
     const state = readState(this.statePath);
-    if (state.locallyPendingCreatedBranches.some((candidate) => pendingCreatedBranchKey(candidate) === pendingCreatedBranchKey(pending))) {
+    const existingPending = state.locallyPendingCreatedBranches.find(
+      (candidate) => pendingCreatedBranchKey(candidate) === pendingCreatedBranchKey(pending)
+    );
+    if (existingPending) {
+      if (existingPending.branchId !== pending.branchId) {
+        throw new Error(`Pending project branch ${pending.branchName} belongs to another durable branch incarnation`);
+      }
       return stateView(this.projectsRoot, state);
     }
     const project = state.desiredProjects.find(({ projectId }) => projectId === pending.projectId);
@@ -664,6 +815,23 @@ class ProjectWorkspaceStateStore {
     writeStateAtomically(this.stateRoot, this.statePath, state);
     return stateView(this.projectsRoot, state);
   }
+  /** Roll back an intent only when Git failed before creating its branch. */
+  rollbackPendingCreatedBranch(input) {
+    const [pending] = normalizePendingCreatedBranches([input]);
+    const state = readState(this.statePath);
+    const key = pendingCreatedBranchKey(pending);
+    const existing = state.locallyPendingCreatedBranches.find((candidate) => pendingCreatedBranchKey(candidate) === key);
+    if (!existing || pending.branchId && existing.branchId !== pending.branchId) {
+      return stateView(this.projectsRoot, state);
+    }
+    state.locallyPendingCreatedBranches = state.locallyPendingCreatedBranches.filter(
+      (candidate) => pendingCreatedBranchKey(candidate) !== key
+    );
+    const project = state.desiredProjects.find(({ projectId }) => projectId === pending.projectId);
+    if (project) project.branches = project.branches.filter(({ branchName }) => branchName !== pending.branchName);
+    writeStateAtomically(this.stateRoot, this.statePath, state);
+    return stateView(this.projectsRoot, state);
+  }
   /** Clear a create intent after an authoritative desired config contains it. */
   clearPendingCreatedBranch(input) {
     const [pending] = normalizePendingCreatedBranches([input]);
@@ -737,9 +905,17 @@ class ProjectWorkspaceStateStore {
     return stateView(this.projectsRoot, state);
   }
 }
+const projectWorkspaceStateTestHarness = {
+  writeEmptyStateAtDurableRootBoundary(stateRoot, afterStateRootFsync) {
+    writeStateAtomically(stateRoot, path.join(stateRoot, PROJECT_WORKSPACE_STATE_FILE), EMPTY_STATE, afterStateRootFsync);
+  }
+};
 export {
   PROJECT_WORKSPACE_STATE_FILE,
+  ProjectWorkspaceCheckoutPathCollisionError,
+  ProjectWorkspacePendingBranchPathChangeError,
   ProjectWorkspaceStateStore,
   discoverStaleOuterProjectWorkspaceEntries,
+  projectWorkspaceStateTestHarness,
   pruneAuthoritativelyDesiredBranchDeletions
 };