@ricsam/r5d-worker 0.0.96 → 0.0.99

package/dist/types/working-tree-mirror.d.ts

@@ -20,7 +20,14 @@ export type TreeEntry = {
  * every portable alias must be remediated before the old tree is retired.
  */
 export declare function assertWorkingTreeHasNoPortableGitMetadataAliases(root: string): void;
-export declare function inspectWorkingTree(root: string, mode: WorkingTreeSourceMode): Map<string, TreeEntry>;
+export declare function inspectWorkingTree(root: string, mode: WorkingTreeSourceMode, options?: {
+    /**
+     * Leave an uninitialized submodule (index gitlink whose directory is
+     * empty) out of a Git-mode inspection. Its empty directory is what keeps
+     * `git status` clean, so a deletion set must never remove it.
+     */
+    omitUnpopulatedGitlinks?: boolean;
+}): Map<string, TreeEntry>;
 export declare function mirrorWorkingTree(input: {
     sourceRoot: string;
     targetRoot: string;
@@ -35,3 +42,75 @@ export declare function mirrorWorkingTree(input: {
 }): {
     paths: string[];
 };
+/** Canonical relative form used by mirror plans and scopes, or null when the value is unsafe. */
+export declare function normalizeWorkingTreeRelativePath(value: string): string | null;
+export type WorkingTreeMirrorPlan = {
+    /** Every target path the mirror creates, rewrites, or verifies, ancestor directories included. */
+    desired: Map<string, TreeEntry>;
+    /**
+     * Target entries the mirror removes or overwrites, as they are before it
+     * runs. A directory entry means the whole subtree goes, ignored files
+     * included; entries beneath it are folded into it.
+     */
+    replaced: Map<string, TreeEntry>;
+    /** Desired paths that have no target entry yet. */
+    absent: string[];
+};
+/**
+ * Compute exactly which target entries `mirrorWorkingTree` would remove,
+ * overwrite, or create for the same input, without changing anything. The
+ * removal set is the target's deletion-mode file set minus the desired paths.
+ * A desired path replaces its target entry when the kinds differ, a symlink
+ * points elsewhere, or a file's bytes or mode differ; an equal entry is left
+ * alone, so the plan covers only what the mirror actually touches. A Git
+ * target's ignored trees appear only where a desired path lands on them.
+ */
+export declare function planWorkingTreeMirror(input: {
+    sourceRoot: string;
+    targetRoot: string;
+    sourceMode: WorkingTreeSourceMode;
+    deletionMode: WorkingTreeDeletionMode;
+}): WorkingTreeMirrorPlan;
+export type WorkingTreeMirrorScope = {
+    /** Desired paths that did not exist before the mirror ran; a restore removes them. */
+    absent: string[];
+    /** Directories captured whole; a restore makes them identical to the snapshot again. */
+    trees: string[];
+};
+/**
+ * Copy the entries a mirror plan replaces into `snapshotRoot` at their
+ * target-relative paths, so that `restoreWorkingTreeMirrorScope` can undo the
+ * mirror. Files and symlinks are copied individually and a replaced directory
+ * is copied whole; ancestor directories appear only as containers. Returns
+ * the scope that must be kept beside the snapshot.
+ */
+export declare function captureWorkingTreeMirrorPlan(input: {
+    plan: WorkingTreeMirrorPlan;
+    targetRoot: string;
+    snapshotRoot: string;
+    durability?: WorkingTreeMirrorDurability;
+}): WorkingTreeMirrorScope;
+/**
+ * Undo a mirror whose plan was captured with `captureWorkingTreeMirrorPlan`:
+ * remove everything the mirror may have created, sweep its interrupted
+ * temporary files, and put every captured entry back. Entries the plan did
+ * not cover (a Git target's ignored files, for instance) are never read or
+ * written. Safe to repeat after a partial run. Returns the target-relative
+ * paths it removed or restored, for the caller's durability barrier.
+ */
+export declare function restoreWorkingTreeMirrorScope(input: {
+    snapshotRoot: string;
+    targetRoot: string;
+    scope: WorkingTreeMirrorScope;
+}): {
+    paths: string[];
+};
+/**
+ * Make the listed target-relative entries durable together with the directory
+ * entries that name them: every listed regular file and real directory is
+ * fsynced, and so is each listed path's parent directory and the root.
+ * Symlinks and missing paths contribute only their parent, which is what
+ * records their creation or removal. Ancestors are never followed through
+ * symlinks. Nothing outside the listed paths is read.
+ */
+export declare function fsyncWorkingTreePaths(root: string, relativePaths: Iterable<string>): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.96",
+  "version": "0.0.99",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",