@paraharness/git 0.0.0-stage → 0.2.0

package/dist/executors/internal/file-digest-and-globs.js

@@ -0,0 +1,188 @@
+import { createHash } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import { chmod, copyFile, lstat, mkdir, readdir, readFile, readlink, rm, symlink, } from 'node:fs/promises';
+import path from 'node:path';
+import picomatch from 'picomatch';
+import { COMPILED_EXCLUDE_MATCHER_CACHE, IMPLICIT_REPO_EXCLUDE_GLOBS, } from './git-executor.constants.js';
+/**
+ * Computes the `${mode}:${sha256}` digest for a worktree path using `lstat(2)` and `readlink(2)` / `readFile(2)`.
+ *
+ * Returns `'DELETED'` when the path does not exist on disk (`ENOENT`), and hashes symlink target strings
+ * without dereferencing broken or external symlinks.
+ *
+ * @param {string} fullPath - Absolute filesystem path to inspect.
+ *
+ * @returns {Promise<string>} Formatted `${mode}:${sha256}` digest string or `'DELETED'`.
+ */
+export async function computePathModeAndSha256(fullPath) {
+    try {
+        const stat = await lstat(fullPath);
+        const hash = createHash('sha256');
+        if (stat.isSymbolicLink()) {
+            const target = await readlink(fullPath, 'utf8');
+            hash.update(target, 'utf8');
+            return `120000:${hash.digest('hex')}`;
+        }
+        if (stat.isDirectory())
+            return '040000:directory';
+        const content = await readFile(fullPath);
+        hash.update(content);
+        const gitMode = (stat.mode & 0o111) !== 0 ? '100755' : '100644';
+        return `${gitMode}:${hash.digest('hex')}`;
+    }
+    catch {
+        return 'DELETED';
+    }
+}
+/**
+ * Compiles a reusable predicate testing whether a repository-relative path should be excluded from checkpoints/clones.
+ *
+ * Always returns `false` for `.gitignore` and `**\/.gitignore` so gitignore tampering is never masked.
+ *
+ * @param {readonly string[] | undefined} excludeGlobs - Configured glob patterns to exclude.
+ *
+ * @returns {(relPath: string) => boolean} Synchronous path exclusion predicate.
+ */
+export function compileWorktreeExcludeMatcher(excludeGlobs) {
+    const allGlobs = [...IMPLICIT_REPO_EXCLUDE_GLOBS, ...(excludeGlobs ?? [])];
+    const cacheKey = allGlobs.join('\0');
+    const cached = COMPILED_EXCLUDE_MATCHER_CACHE.get(cacheKey);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const matchers = [];
+    for (const pattern of allGlobs) {
+        matchers.push(picomatch(pattern, { dot: true }));
+    }
+    const compiled = (relPath) => {
+        const normalized = relPath.replace(/\\/g, '/').replace(/\/+$/, '');
+        if (normalized === '.gitignore' || normalized.endsWith('/.gitignore'))
+            return false;
+        for (const isMatch of matchers) {
+            if (isMatch(normalized))
+                return true;
+        }
+        return false;
+    };
+    COMPILED_EXCLUDE_MATCHER_CACHE.set(cacheKey, compiled);
+    return compiled;
+}
+/**
+ * Checks whether a relative directory path inside `node_modules` is a transient bundler or test-runner cache directory.
+ *
+ * Matches both top-level and nested `.cache`, `.vite`, and `.vitest` directories.
+ *
+ * @param {string} relDir - Forward-slash relative directory path inside `node_modules`.
+ *
+ * @returns {boolean} `true` when `relDir` is a transient `.cache`, `.vite`, or `.vitest` directory.
+ */
+function isTransientNodeModulesCacheDir(relDir) {
+    return (relDir === '.cache' ||
+        relDir === '.vite' ||
+        relDir === '.vitest' ||
+        relDir.endsWith('/.cache') ||
+        relDir.endsWith('/.vite') ||
+        relDir.endsWith('/.vitest'));
+}
+/**
+ * Computes a structural SHA-256 digest of `<worktreePath>/node_modules`.
+ *
+ * Walks regular files and symlinks inside `node_modules` (excluding top-level and nested `.cache`, `.vite`, and `.vitest`)
+ * so `diffEffects` and `restoreCheckpoint` can detect `node_modules` tampering without performing backup I/O.
+ *
+ * @param {string} worktreePath - Worktree root directory path.
+ *
+ * @returns {Promise<string>} Hex SHA-256 digest of the `node_modules` tree, or `'ABSENT'` when not present.
+ */
+export async function computeNodeModulesDigest(worktreePath) {
+    const nmRoot = path.join(worktreePath, 'node_modules');
+    const rootStat = await lstat(nmRoot).catch(() => null);
+    if (rootStat === null)
+        return 'ABSENT';
+    const hash = createHash('sha256');
+    const stack = [''];
+    while (stack.length > 0) {
+        const relDir = stack.pop() ?? '';
+        if (isTransientNodeModulesCacheDir(relDir))
+            continue;
+        const entries = await readdir(path.join(nmRoot, relDir), { withFileTypes: true });
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            const childRel = relDir.length === 0 ? entry.name : `${relDir}/${entry.name}`;
+            if (entry.isDirectory())
+                stack.push(childRel);
+            else {
+                const digest = await computePathModeAndSha256(path.join(nmRoot, childRel));
+                hash.update(`${childRel}:${digest}\n`, 'utf8');
+            }
+        }
+    }
+    return hash.digest('hex');
+}
+/**
+ * Mirrors `<worktreePath>/node_modules` into `<backupRootDir>/<digest>` via Copy-on-Write if not already backed up.
+ *
+ * Skips transient `.cache`, `.vite`, and `.vitest` subdirectories and short-circuits when `digest === 'ABSENT'`
+ * or `<backupRootDir>/<digest>` already exists on disk.
+ *
+ * @param {string} worktreePath  - Worktree root directory path.
+ * @param {string} digest        - Precomputed structural SHA-256 digest of `node_modules`.
+ * @param {string} backupRootDir - `<gitdir>/harness-ckpt-nm` backup root directory.
+ *
+ * @returns {Promise<void>} Resolves once the content-addressed backup directory is populated.
+ */
+export async function snapshotNodeModulesForCheckpoint(worktreePath, digest, backupRootDir) {
+    if (digest === 'ABSENT')
+        return;
+    const nmRoot = path.join(worktreePath, 'node_modules');
+    const digestBackupDir = path.join(backupRootDir, digest);
+    const exists = await lstat(digestBackupDir).then(() => true, () => false);
+    if (exists)
+        return;
+    const stack = [''];
+    while (stack.length > 0) {
+        const relDir = stack.pop() ?? '';
+        if (isTransientNodeModulesCacheDir(relDir))
+            continue;
+        const entries = await readdir(path.join(nmRoot, relDir), { withFileTypes: true });
+        for (const entry of entries) {
+            const childRel = relDir.length === 0 ? entry.name : `${relDir}/${entry.name}`;
+            if (entry.isDirectory())
+                stack.push(childRel);
+            else {
+                await copyFileCowOrValue(path.join(nmRoot, childRel), path.join(digestBackupDir, childRel));
+            }
+        }
+    }
+}
+/**
+ * Copies a single file or symbolic link using Copy-on-Write (`COPYFILE_FICLONE`) when supported, falling back to value copy.
+ *
+ * Preserves symbolic links via `readlink` + `symlink` and applies POSIX file permission bits (`mode`) for regular files.
+ *
+ * @param {string} srcPath  - Source file or symlink path.
+ * @param {string} destPath - Destination file or symlink path.
+ * @param {number} [mode]   - Optional POSIX permission mode to apply.
+ *
+ * @returns {Promise<void>} Resolves once the file or symlink is copied.
+ */
+export async function copyFileCowOrValue(srcPath, destPath, mode) {
+    await mkdir(path.dirname(destPath), { recursive: true });
+    const stat = await lstat(srcPath);
+    if (stat.isSymbolicLink()) {
+        const linkTarget = await readlink(srcPath, 'utf8');
+        await rm(destPath, { force: true });
+        await symlink(linkTarget, destPath);
+        return;
+    }
+    try {
+        await copyFile(srcPath, destPath, fsConstants.COPYFILE_FICLONE);
+    }
+    catch {
+        await copyFile(srcPath, destPath);
+    }
+    if (mode !== undefined) {
+        await chmod(destPath, mode & 0o777);
+    }
+}
+//# sourceMappingURL=file-digest-and-globs.js.map

package/dist/executors/internal/file-digest-and-globs.js.map

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

package/dist/executors/internal/git-checkpoint-diff-effects.d.ts

@@ -0,0 +1,16 @@
+import type { GitCowWorktreeNode, GitWorktreeHandle, ToolEffect } from '@paraharness/core';
+/**
+ * Verifies worktree-local `.git` and `node_modules` integrity and diffs post-flight file effects against `fromCheckpointJson`.
+ *
+ * Immediately invokes `gitCheckpointRestore` and throws a non-leasable error if `.git` or `node_modules` was tampered with.
+ *
+ * @param {string}                                 fromCheckpointJson - Serialized `GitCheckpointPayload` string.
+ * @param {GitWorktreeHandle}                      handle             - Active worktree handle.
+ * @param {GitCowWorktreeNode['checkpointPolicy']} [policy]           - Optional checkpoint policy configuration.
+ *
+ * @returns {Promise<readonly ToolEffect[]>} Synthesized `FsToolEffect` list for the symmetric status difference.
+ *
+ * @throws {Error} If worktree-local `.git` metadata or `node_modules` was tampered with.
+ */
+export declare function gitCheckpointDiffEffects(fromCheckpointJson: string, handle: GitWorktreeHandle, policy?: GitCowWorktreeNode['checkpointPolicy']): Promise<readonly ToolEffect[]>;
+//# sourceMappingURL=git-checkpoint-diff-effects.d.ts.map

package/dist/executors/internal/git-checkpoint-diff-effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-checkpoint-diff-effects.d.ts","sourceRoot":"","sources":["../../../src/executors/internal/git-checkpoint-diff-effects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,UAAU,EACX,MAAM,mBAAmB,CAAC;AAa3B;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAC5C,kBAAkB,EAAE,MAAM,EAC1B,MAAM,EAAE,iBAAiB,EACzB,MAAM,CAAC,EAAE,kBAAkB,CAAC,kBAAkB,CAAC,GAC9C,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CA8BhC"}

package/dist/executors/internal/git-checkpoint-diff-effects.js

@@ -0,0 +1,38 @@
+import { computeSymmetricStatusDiff, verifyWorktreeLocalGitIntegrity, } from './checkpoint-staging-and-integrity.js';
+import { gitCheckpointRestore } from './git-checkpoint-restore.js';
+import { gitCheckpointStatusMap } from './git-checkpoint-status-map.js';
+import { buildFsDiffToolEffects, hasGitignoreChanged, } from './porcelain-v2-parser.js';
+/**
+ * Verifies worktree-local `.git` and `node_modules` integrity and diffs post-flight file effects against `fromCheckpointJson`.
+ *
+ * Immediately invokes `gitCheckpointRestore` and throws a non-leasable error if `.git` or `node_modules` was tampered with.
+ *
+ * @param {string}                                 fromCheckpointJson - Serialized `GitCheckpointPayload` string.
+ * @param {GitWorktreeHandle}                      handle             - Active worktree handle.
+ * @param {GitCowWorktreeNode['checkpointPolicy']} [policy]           - Optional checkpoint policy configuration.
+ *
+ * @returns {Promise<readonly ToolEffect[]>} Synthesized `FsToolEffect` list for the symmetric status difference.
+ *
+ * @throws {Error} If worktree-local `.git` metadata or `node_modules` was tampered with.
+ */
+export async function gitCheckpointDiffEffects(fromCheckpointJson, handle, policy) {
+    const fromCheckpoint = JSON.parse(fromCheckpointJson);
+    const integrity = await verifyWorktreeLocalGitIntegrity(handle, fromCheckpoint);
+    if (!integrity.intact) {
+        await gitCheckpointRestore(handle, fromCheckpointJson, policy);
+        throw new Error(`Non-leasable worktree integrity violation in '${handle.worktreePath}': ${integrity.reason ?? 'tampered metadata'}`);
+    }
+    const initialSnap = await gitCheckpointStatusMap(handle.worktreePath, {
+        excludeGlobs: policy?.excludeGlobs,
+    });
+    const finalSnap = hasGitignoreChanged(fromCheckpoint.statusMap, initialSnap.statusMap)
+        ? await gitCheckpointStatusMap(handle.worktreePath, {
+            excludeGlobs: policy?.excludeGlobs,
+            includeMatchingIgnored: true,
+            baselineIgnoredPaths: new Set(fromCheckpoint.ignoredPaths),
+        })
+        : initialSnap;
+    const symDiff = computeSymmetricStatusDiff(fromCheckpoint.statusMap, finalSnap.statusMap);
+    return buildFsDiffToolEffects(handle, symDiff);
+}
+//# sourceMappingURL=git-checkpoint-diff-effects.js.map

package/dist/executors/internal/git-checkpoint-diff-effects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-checkpoint-diff-effects.js","sourceRoot":"","sources":["../../../src/executors/internal/git-checkpoint-diff-effects.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,0BAA0B,EAC1B,+BAA+B,GAChC,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EACL,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,kBAA0B,EAC1B,MAAyB,EACzB,MAA+C;IAE/C,MAAM,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAyB,CAAC;IAC9E,MAAM,SAAS,GAAG,MAAM,+BAA+B,CACrD,MAAM,EACN,cAAc,CACf,CAAC;IACF,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;QACtB,MAAM,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,EAAE,MAAM,CAAC,CAAC;QAC/D,MAAM,IAAI,KAAK,CACb,iDAAiD,MAAM,CAAC,YAAY,MAAM,SAAS,CAAC,MAAM,IAAI,mBAAmB,EAAE,CACpH,CAAC;IACJ,CAAC;IACD,MAAM,WAAW,GAAG,MAAM,sBAAsB,CAAC,MAAM,CAAC,YAAY,EAAE;QACpE,YAAY,EAAE,MAAM,EAAE,YAAY;KACnC,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,mBAAmB,CACnC,cAAc,CAAC,SAAS,EACxB,WAAW,CAAC,SAAS,CACtB;QACC,CAAC,CAAC,MAAM,sBAAsB,CAAC,MAAM,CAAC,YAAY,EAAE;YAChD,YAAY,EAAE,MAAM,EAAE,YAAY;YAClC,sBAAsB,EAAE,IAAI;YAC5B,oBAAoB,EAAE,IAAI,GAAG,CAAC,cAAc,CAAC,YAAY,CAAC;SAC3D,CAAC;QACJ,CAAC,CAAC,WAAW,CAAC;IAChB,MAAM,OAAO,GAAG,0BAA0B,CACxC,cAAc,CAAC,SAAS,EACxB,SAAS,CAAC,SAAS,CACpB,CAAC;IACF,OAAO,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC"}

package/dist/executors/internal/git-checkpoint-restore.d.ts

@@ -0,0 +1,14 @@
+import type { GitCowWorktreeNode, GitWorktreeHandle } from '@paraharness/core';
+/**
+ * Restores `handle` to `fromCheckpointJson` using the deterministic 4-step Git-Index restoration protocol.
+ *
+ * Restores `.git` metadata and `.gitignore` rules, unlinks added/colliding paths, checks out `treeSha`, and restores spilled blobs.
+ *
+ * @param {GitWorktreeHandle}                      handle             - Active worktree handle to restore.
+ * @param {string}                                 fromCheckpointJson - Serialized `GitCheckpointPayload` string.
+ * @param {GitCowWorktreeNode['checkpointPolicy']} [policy]           - Optional checkpoint policy configuration.
+ *
+ * @returns {Promise<void>} Resolves once the worktree matches `fromCheckpointJson` bit-for-bit.
+ */
+export declare function gitCheckpointRestore(handle: GitWorktreeHandle, fromCheckpointJson: string, policy?: GitCowWorktreeNode['checkpointPolicy']): Promise<void>;
+//# sourceMappingURL=git-checkpoint-restore.d.ts.map

package/dist/executors/internal/git-checkpoint-restore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-checkpoint-restore.d.ts","sourceRoot":"","sources":["../../../src/executors/internal/git-checkpoint-restore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAe/E;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,iBAAiB,EACzB,kBAAkB,EAAE,MAAM,EAC1B,MAAM,CAAC,EAAE,kBAAkB,CAAC,kBAAkB,CAAC,GAC9C,OAAO,CAAC,IAAI,CAAC,CAkCf"}

package/dist/executors/internal/git-checkpoint-restore.js

@@ -0,0 +1,37 @@
+import { checkoutCheckpointTreeAndRestoreIndex, restoreGitdirMetadataAndGitignores, restoreOversizedUntrackedBlobs, unlinkAddedAndDirectoryCollisions, } from './checkpoint-restore-steps.js';
+import { computeSymmetricStatusDiff, listTreePaths, verifyWorktreeLocalGitIntegrity, } from './checkpoint-staging-and-integrity.js';
+import { gitCheckpointStatusMap } from './git-checkpoint-status-map.js';
+/**
+ * Restores `handle` to `fromCheckpointJson` using the deterministic 4-step Git-Index restoration protocol.
+ *
+ * Restores `.git` metadata and `.gitignore` rules, unlinks added/colliding paths, checks out `treeSha`, and restores spilled blobs.
+ *
+ * @param {GitWorktreeHandle}                      handle             - Active worktree handle to restore.
+ * @param {string}                                 fromCheckpointJson - Serialized `GitCheckpointPayload` string.
+ * @param {GitCowWorktreeNode['checkpointPolicy']} [policy]           - Optional checkpoint policy configuration.
+ *
+ * @returns {Promise<void>} Resolves once the worktree matches `fromCheckpointJson` bit-for-bit.
+ */
+export async function gitCheckpointRestore(handle, fromCheckpointJson, policy) {
+    const fromCheckpoint = JSON.parse(fromCheckpointJson);
+    const integrity = await verifyWorktreeLocalGitIntegrity(handle, fromCheckpoint);
+    const treePaths = await listTreePaths(handle.worktreePath, fromCheckpoint.treeSha);
+    await restoreGitdirMetadataAndGitignores(handle, fromCheckpoint, treePaths);
+    const currentSnap = await gitCheckpointStatusMap(handle.worktreePath, {
+        excludeGlobs: policy?.excludeGlobs,
+        includeMatchingIgnored: true,
+        baselineIgnoredPaths: new Set(fromCheckpoint.ignoredPaths),
+    });
+    const symDiff = computeSymmetricStatusDiff(fromCheckpoint.statusMap, currentSnap.statusMap);
+    const preservedPaths = new Set([
+        ...treePaths,
+        ...Object.keys(fromCheckpoint.oversizedUntrackedBlobs),
+    ]);
+    await unlinkAddedAndDirectoryCollisions(handle, symDiff, preservedPaths);
+    const pathsToCheckout = !integrity.intact
+        ? 'ALL'
+        : symDiff.filter((relPath) => treePaths.has(relPath));
+    await checkoutCheckpointTreeAndRestoreIndex(handle, fromCheckpoint, pathsToCheckout);
+    await restoreOversizedUntrackedBlobs(handle, fromCheckpoint);
+}
+//# sourceMappingURL=git-checkpoint-restore.js.map

package/dist/executors/internal/git-checkpoint-restore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-checkpoint-restore.js","sourceRoot":"","sources":["../../../src/executors/internal/git-checkpoint-restore.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,qCAAqC,EACrC,kCAAkC,EAClC,8BAA8B,EAC9B,iCAAiC,GAClC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,0BAA0B,EAC1B,aAAa,EACb,+BAA+B,GAChC,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAyB,EACzB,kBAA0B,EAC1B,MAA+C;IAE/C,MAAM,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAyB,CAAC;IAC9E,MAAM,SAAS,GAAG,MAAM,+BAA+B,CACrD,MAAM,EACN,cAAc,CACf,CAAC;IACF,MAAM,SAAS,GAAG,MAAM,aAAa,CACnC,MAAM,CAAC,YAAY,EACnB,cAAc,CAAC,OAAO,CACvB,CAAC;IACF,MAAM,kCAAkC,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC;IAC5E,MAAM,WAAW,GAAG,MAAM,sBAAsB,CAAC,MAAM,CAAC,YAAY,EAAE;QACpE,YAAY,EAAE,MAAM,EAAE,YAAY;QAClC,sBAAsB,EAAE,IAAI;QAC5B,oBAAoB,EAAE,IAAI,GAAG,CAAC,cAAc,CAAC,YAAY,CAAC;KAC3D,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,0BAA0B,CACxC,cAAc,CAAC,SAAS,EACxB,WAAW,CAAC,SAAS,CACtB,CAAC;IACF,MAAM,cAAc,GAAG,IAAI,GAAG,CAAS;QACrC,GAAG,SAAS;QACZ,GAAG,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,uBAAuB,CAAC;KACvD,CAAC,CAAC;IACH,MAAM,iCAAiC,CAAC,MAAM,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;IACzE,MAAM,eAAe,GAAG,CAAC,SAAS,CAAC,MAAM;QACvC,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACxD,MAAM,qCAAqC,CACzC,MAAM,EACN,cAAc,EACd,eAAe,CAChB,CAAC;IACF,MAAM,8BAA8B,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAC/D,CAAC"}

package/dist/executors/internal/git-checkpoint-serialize.d.ts

@@ -0,0 +1,13 @@
+import type { GitCowWorktreeNode, GitWorktreeHandle } from '@paraharness/core';
+/**
+ * Serializes a non-mutating Git-Index checkpoint for `handle` without advancing `HEAD` or touching `<gitdir>/index`.
+ *
+ * Captures worktree-local `.git` metadata, `statusMap`, temporary-index `treeSha`, and any spilled oversized untracked blobs.
+ *
+ * @param {GitWorktreeHandle}                      handle   - Active worktree handle to snapshot.
+ * @param {GitCowWorktreeNode['checkpointPolicy']} [policy] - Optional checkpoint policy from `GitCowWorktreeNode`.
+ *
+ * @returns {Promise<string>} JSON-serialized `GitCheckpointPayload` string.
+ */
+export declare function gitCheckpointSerialize(handle: GitWorktreeHandle, policy?: GitCowWorktreeNode['checkpointPolicy']): Promise<string>;
+//# sourceMappingURL=git-checkpoint-serialize.d.ts.map

package/dist/executors/internal/git-checkpoint-serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-checkpoint-serialize.d.ts","sourceRoot":"","sources":["../../../src/executors/internal/git-checkpoint-serialize.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAW/E;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,iBAAiB,EACzB,MAAM,CAAC,EAAE,kBAAkB,CAAC,kBAAkB,CAAC,GAC9C,OAAO,CAAC,MAAM,CAAC,CA4CjB"}

package/dist/executors/internal/git-checkpoint-serialize.js

@@ -0,0 +1,48 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { stageCheckpointTreeAndOversizedBlobs } from './checkpoint-staging-and-integrity.js';
+import { computeNodeModulesDigest, snapshotNodeModulesForCheckpoint, } from './file-digest-and-globs.js';
+import { gitCheckpointStatusMap } from './git-checkpoint-status-map.js';
+import { readHarnessMeta, runGitCommand } from './git-cli-runner.js';
+import { DEFAULT_MAX_UNTRACKED_FILE_SIZE_BYTES } from './git-executor.constants.js';
+/**
+ * Serializes a non-mutating Git-Index checkpoint for `handle` without advancing `HEAD` or touching `<gitdir>/index`.
+ *
+ * Captures worktree-local `.git` metadata, `statusMap`, temporary-index `treeSha`, and any spilled oversized untracked blobs.
+ *
+ * @param {GitWorktreeHandle}                      handle   - Active worktree handle to snapshot.
+ * @param {GitCowWorktreeNode['checkpointPolicy']} [policy] - Optional checkpoint policy from `GitCowWorktreeNode`.
+ *
+ * @returns {Promise<string>} JSON-serialized `GitCheckpointPayload` string.
+ */
+export async function gitCheckpointSerialize(handle, policy) {
+    const headRawContent = await readFile(path.join(handle.gitDirPath, 'HEAD'), 'utf8');
+    const indexTreeResult = await runGitCommand({
+        cwd: handle.worktreePath,
+        args: ['write-tree'],
+    });
+    const infoExcludeContent = await readFile(path.join(handle.gitDirPath, 'info', 'exclude'), 'utf8').catch(() => null);
+    const meta = await readHarnessMeta(handle.gitDirPath);
+    const snapshot = await gitCheckpointStatusMap(handle.worktreePath, {
+        excludeGlobs: policy?.excludeGlobs,
+        includeMatchingIgnored: true,
+    });
+    const maxBytes = policy?.maxUntrackedFileSizeBytes ?? DEFAULT_MAX_UNTRACKED_FILE_SIZE_BYTES;
+    const staged = await stageCheckpointTreeAndOversizedBlobs(handle, snapshot, maxBytes);
+    const nodeModulesDigest = await computeNodeModulesDigest(handle.worktreePath);
+    await snapshotNodeModulesForCheckpoint(handle.worktreePath, nodeModulesDigest, path.join(handle.gitDirPath, 'harness-ckpt-nm'));
+    const payload = Object.freeze({
+        headSha: staged.headSha,
+        headRawContent,
+        indexTreeSha: indexTreeResult.stdout.trim(),
+        infoExcludeContent,
+        meta,
+        statusMap: snapshot.statusMap,
+        ignoredPaths: snapshot.ignoredPaths,
+        nodeModulesDigest,
+        treeSha: staged.treeSha,
+        oversizedUntrackedBlobs: staged.oversizedUntrackedBlobs,
+    });
+    return JSON.stringify(payload);
+}
+//# sourceMappingURL=git-checkpoint-serialize.js.map

package/dist/executors/internal/git-checkpoint-serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-checkpoint-serialize.js","sourceRoot":"","sources":["../../../src/executors/internal/git-checkpoint-serialize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,OAAO,EAAE,oCAAoC,EAAE,MAAM,uCAAuC,CAAC;AAC7F,OAAO,EACL,wBAAwB,EACxB,gCAAgC,GACjC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,qCAAqC,EAAE,MAAM,6BAA6B,CAAC;AAEpF;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,MAAyB,EACzB,MAA+C;IAE/C,MAAM,cAAc,GAAG,MAAM,QAAQ,CACnC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,EACpC,MAAM,CACP,CAAC;IACF,MAAM,eAAe,GAAG,MAAM,aAAa,CAAC;QAC1C,GAAG,EAAE,MAAM,CAAC,YAAY;QACxB,IAAI,EAAE,CAAC,YAAY,CAAC;KACrB,CAAC,CAAC;IACH,MAAM,kBAAkB,GAAG,MAAM,QAAQ,CACvC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAC/C,MAAM,CACP,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IACpB,MAAM,IAAI,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,MAAM,sBAAsB,CAAC,MAAM,CAAC,YAAY,EAAE;QACjE,YAAY,EAAE,MAAM,EAAE,YAAY;QAClC,sBAAsB,EAAE,IAAI;KAC7B,CAAC,CAAC;IACH,MAAM,QAAQ,GACZ,MAAM,EAAE,yBAAyB,IAAI,qCAAqC,CAAC;IAC7E,MAAM,MAAM,GAAG,MAAM,oCAAoC,CACvD,MAAM,EACN,QAAQ,EACR,QAAQ,CACT,CAAC;IACF,MAAM,iBAAiB,GAAG,MAAM,wBAAwB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAC9E,MAAM,gCAAgC,CACpC,MAAM,CAAC,YAAY,EACnB,iBAAiB,EACjB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAChD,CAAC;IACF,MAAM,OAAO,GAAyB,MAAM,CAAC,MAAM,CAAC;QAClD,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,cAAc;QACd,YAAY,EAAE,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE;QAC3C,kBAAkB;QAClB,IAAI;QACJ,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,iBAAiB;QACjB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,uBAAuB,EAAE,MAAM,CAAC,uBAAuB;KACxD,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC"}

package/dist/executors/internal/git-checkpoint-status-map.d.ts

@@ -0,0 +1,14 @@
+import type { ComputeWorktreeStatusOptions } from './compute-worktree-status-options.js';
+import type { WorktreeStatusSnapshot } from './worktree-status-snapshot.js';
+/**
+ * Computes the porcelain v2 status snapshot for `worktreePath` (`git status --porcelain=v2 -z --no-renames --untracked-files=all`).
+ *
+ * Optionally enables `--ignored=matching` when scanning for files hidden behind a `.gitignore` mutation.
+ *
+ * @param {string}                       worktreePath - Worktree directory path to scan.
+ * @param {ComputeWorktreeStatusOptions} [options]    - Optional exclusion globs and ignored-matching flags.
+ *
+ * @returns {Promise<WorktreeStatusSnapshot>} Structured status map, untracked set, deleted set, and ignored paths.
+ */
+export declare function gitCheckpointStatusMap(worktreePath: string, options?: ComputeWorktreeStatusOptions): Promise<WorktreeStatusSnapshot>;
+//# sourceMappingURL=git-checkpoint-status-map.d.ts.map

package/dist/executors/internal/git-checkpoint-status-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-checkpoint-status-map.d.ts","sourceRoot":"","sources":["../../../src/executors/internal/git-checkpoint-status-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,sCAAsC,CAAC;AAGzF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAE5E;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,4BAA4B,GACrC,OAAO,CAAC,sBAAsB,CAAC,CAajC"}

package/dist/executors/internal/git-checkpoint-status-map.js

@@ -0,0 +1,27 @@
+import { runGitCommand } from './git-cli-runner.js';
+import { parsePorcelainV2Records } from './porcelain-v2-parser.js';
+/**
+ * Computes the porcelain v2 status snapshot for `worktreePath` (`git status --porcelain=v2 -z --no-renames --untracked-files=all`).
+ *
+ * Optionally enables `--ignored=matching` when scanning for files hidden behind a `.gitignore` mutation.
+ *
+ * @param {string}                       worktreePath - Worktree directory path to scan.
+ * @param {ComputeWorktreeStatusOptions} [options]    - Optional exclusion globs and ignored-matching flags.
+ *
+ * @returns {Promise<WorktreeStatusSnapshot>} Structured status map, untracked set, deleted set, and ignored paths.
+ */
+export async function gitCheckpointStatusMap(worktreePath, options) {
+    const args = [
+        'status',
+        '--porcelain=v2',
+        '-z',
+        '--no-renames',
+        '--untracked-files=all',
+    ];
+    if (options?.includeMatchingIgnored) {
+        args.push('--ignored=matching');
+    }
+    const statusResult = await runGitCommand({ cwd: worktreePath, args });
+    return parsePorcelainV2Records(worktreePath, statusResult.stdout, options);
+}
+//# sourceMappingURL=git-checkpoint-status-map.js.map

package/dist/executors/internal/git-checkpoint-status-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-checkpoint-status-map.js","sourceRoot":"","sources":["../../../src/executors/internal/git-checkpoint-status-map.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAGnE;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,YAAoB,EACpB,OAAsC;IAEtC,MAAM,IAAI,GAAG;QACX,QAAQ;QACR,gBAAgB;QAChB,IAAI;QACJ,cAAc;QACd,uBAAuB;KACxB,CAAC;IACF,IAAI,OAAO,EAAE,sBAAsB,EAAE,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IAClC,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,aAAa,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;IACtE,OAAO,uBAAuB,CAAC,YAAY,EAAE,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC7E,CAAC"}

package/dist/executors/internal/git-cli-command-options.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Execution options passed to `runGitCommand`.
+ *
+ * Configures the working directory, `git` CLI argument vector, optional `stdin` payload,
+ * isolated environment variables, and whether non-zero exit codes should be returned instead of thrown.
+ */
+export interface GitCliCommandOptions {
+    /** Working directory in which `git` is spawned. */
+    readonly cwd: string;
+    /** Argument vector passed to the `git` binary. */
+    readonly args: readonly string[];
+    /** Optional additional environment variables merged into the isolated worktree environment. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Optional standard input buffer or UTF-8 string piped to the subprocess. */
+    readonly stdin?: string | Buffer;
+    /** When `true`, resolves `GitCliCommandResult` on non-zero exit codes instead of throwing. */
+    readonly allowNonZeroExit?: boolean;
+    /** Optional `AbortSignal` to terminate the git subprocess early. */
+    readonly signal?: AbortSignal;
+}
+//# sourceMappingURL=git-cli-command-options.d.ts.map

package/dist/executors/internal/git-cli-command-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-cli-command-options.d.ts","sourceRoot":"","sources":["../../../src/executors/internal/git-cli-command-options.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,+FAA+F;IAC/F,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,8FAA8F;IAC9F,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B"}

package/dist/executors/internal/git-cli-command-options.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=git-cli-command-options.js.map

package/dist/executors/internal/git-cli-command-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-cli-command-options.js","sourceRoot":"","sources":["../../../src/executors/internal/git-cli-command-options.ts"],"names":[],"mappings":""}

package/dist/executors/internal/git-cli-command-result.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Result returned by `runGitCommand` after executing a `git` CLI subprocess.
+ *
+ * Contains the exit code, decoded UTF-8 `stdout` and `stderr` strings, and raw `stdoutBuffer` bytes.
+ */
+export interface GitCliCommandResult {
+    /** Numeric subprocess exit code (`0` on success). */
+    readonly exitCode: number;
+    /** UTF-8 decoded standard output. */
+    readonly stdout: string;
+    /** UTF-8 decoded standard error. */
+    readonly stderr: string;
+    /** Raw standard output buffer for NUL-delimited (`-z`) binary/path parsing. */
+    readonly stdoutBuffer: Buffer;
+}
+//# sourceMappingURL=git-cli-command-result.d.ts.map

package/dist/executors/internal/git-cli-command-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-cli-command-result.d.ts","sourceRoot":"","sources":["../../../src/executors/internal/git-cli-command-result.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B"}

package/dist/executors/internal/git-cli-command-result.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=git-cli-command-result.js.map

package/dist/executors/internal/git-cli-command-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-cli-command-result.js","sourceRoot":"","sources":["../../../src/executors/internal/git-cli-command-result.ts"],"names":[],"mappings":""}

package/dist/executors/internal/git-cli-runner.d.ts

@@ -0,0 +1,73 @@
+import type { GitWorktreeHandle } from '@paraharness/core';
+import { type HarnessMetaRecord } from '../../schemas/git-receipts.schema.js';
+import type { GitCliCommandOptions } from './git-cli-command-options.js';
+import type { GitCliCommandResult } from './git-cli-command-result.js';
+/**
+ * Constructs the isolated environment map for git and subprocess invocations inside a worktree.
+ *
+ * Sets `GIT_CEILING_DIRECTORIES=<dirname(worktreePath)>`, `GIT_CONFIG_NOSYSTEM=1`, `GIT_OPTIONAL_LOCKS=0`,
+ * disables GPG signing, and forces `core.hooksPath=/dev/null` per `SPEC.md` §4.4.
+ *
+ * @param {string}                                       worktreePath - Worktree directory path.
+ * @param {Readonly<Record<string, string | undefined>>} [extraEnv]   - Optional overrides merged on top.
+ *
+ * @returns {Readonly<Record<string, string>>} Frozen environment map for subprocess execution.
+ */
+export declare function buildIsolatedWorktreeGitEnv(worktreePath: string, extraEnv?: Readonly<Record<string, string | undefined>>): Readonly<Record<string, string>>;
+/**
+ * Spawns a `git` CLI command inside `options.cwd` with isolated worktree environment settings.
+ *
+ * Pipes optional `stdin`, captures `stdoutBuffer` and `stderr`, cleans up `AbortSignal` listeners,
+ * and throws an actionable diagnostic `Error` when `exitCode !== 0` unless `allowNonZeroExit` is set.
+ *
+ * @param {GitCliCommandOptions} options - Command execution options.
+ *
+ * @returns {Promise<GitCliCommandResult>} Resolved exit code, decoded output strings, and raw stdout buffer.
+ *
+ * @throws {Error} If the `git` process exits non-zero and `allowNonZeroExit` is not `true`.
+ */
+export declare function runGitCommand(options: GitCliCommandOptions): Promise<GitCliCommandResult>;
+/**
+ * Reads and validates `<gitDirPath>/harness-meta.json` using `HarnessMetaSchema`.
+ *
+ * Parses the persisted worktree lineage, unresolved conflict digests, and in-flight crash-recovery markers.
+ *
+ * @param {string} gitDirPath - Path to the worktree's isolated `<gitdir>` metadata directory.
+ *
+ * @returns {Promise<HarnessMetaRecord>} Validated `HarnessMetaRecord` object.
+ */
+export declare function readHarnessMeta(gitDirPath: string): Promise<HarnessMetaRecord>;
+/**
+ * Atomically writes and validates `<gitDirPath>/harness-meta.json` under a cross-process file lock.
+ *
+ * Acquires `<gitDirPath>/harness-meta.json.lock` via `withFileLock` and persists the validated JSON via `writeFileAtomic`.
+ *
+ * @param {string}            gitDirPath - Path to the worktree's isolated `<gitdir>` metadata directory.
+ * @param {HarnessMetaRecord} meta       - Metadata record to persist.
+ *
+ * @returns {Promise<void>} Resolves once `harness-meta.json` is durably updated.
+ */
+export declare function writeHarnessMeta(gitDirPath: string, meta: HarnessMetaRecord): Promise<void>;
+/**
+ * Updates mutable `GitWorktreeHandle` properties in place when the caller passed a non-frozen handle.
+ *
+ * Avoids throwing `TypeError` when a caller passes a frozen `GitWorktreeHandle` fixture without
+ * using empty `try / catch` blocks.
+ *
+ * @param {GitWorktreeHandle}          handle - Target worktree handle to update.
+ * @param {Partial<GitWorktreeHandle>} patch  - Partial property updates to assign onto `handle`.
+ */
+export declare function updateWorktreeHandleInPlace(handle: GitWorktreeHandle, patch: Partial<GitWorktreeHandle>): void;
+/**
+ * Executes a host-repository worktree administrative operation (`worktree prune`, `worktree add`, `worktree remove`)
+ * under `<commonGitDir>/harness-worktree.lock` to prevent concurrent `git worktree` administrative races.
+ *
+ * @template T Result type returned by `fn`.
+ *
+ * @param {string}          cwd - Working directory inside the host repository or an attached worktree.
+ * @param {() => Promise<T>} fn  - Async callback performing `git worktree` administrative commands.
+ *
+ * @returns {Promise<T>} Result produced by `fn`.
+ */
+export declare function withHostWorktreeLock<T>(cwd: string, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=git-cli-runner.d.ts.map

package/dist/executors/internal/git-cli-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-cli-runner.d.ts","sourceRoot":"","sources":["../../../src/executors/internal/git-cli-runner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG3D,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAGvE;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GACtD,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAsBlC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAgC9B;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAIpF;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAChC,IAAI,CAIN;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAQZ"}