@mnaoumov/obsidian-lib 10.3.0 → 10.4.1

package/dist/lib/esm/desktop-bulk-operation-git.d.mts

@@ -0,0 +1,196 @@
+/// <reference path="./library-references.d.mts" />
+/**
+ * @file
+ *
+ * The desktop half of bulk-operation git commits: drives the system `git` CLI to wrap a bulk operation in commits,
+ * guarded by a lease lock in the repo's git directory.
+ *
+ * The system CLI is used rather than a bundled implementation because it honors the repo's own config, hooks
+ * and clean/smudge filters, git-annex's among them, and because `git revert` is the whole undo story.
+ *
+ * Every command runs with the vault folder as its working directory and `.` as its pathspec, so when the vault is a
+ * subfolder of a larger repo only the vault's changes are committed.
+ *
+ * Desktop-only (`node:child_process`, `node:fs`, `node:os`), but inert to import on mobile: nothing here touches a
+ * Node builtin until a function is called.
+ */
+import type { BulkOperationCommit } from './bulk-operation.mjs';
+/**
+ * Constructor parameters for {@link BulkOperationGitRepo}.
+ */
+export interface BulkOperationGitRepoConstructorParams {
+    /**
+     * The absolute path of the repo's git directory, where the lease lock lives.
+     */
+    readonly gitDirectory: string;
+    /**
+     * How long to wait for another operation's lock before giving up.
+     *
+     * @default `600_000`
+     */
+    readonly lockWaitTimeoutInMilliseconds?: number;
+    /**
+     * The absolute path of the folder whose changes are committed: the vault root.
+     */
+    readonly workingDirectory: string;
+}
+/**
+ * Parameters for {@link BulkOperationGitRepo.runBulkOperation}.
+ *
+ * @typeParam T - The type of the operation's result.
+ */
+export interface BulkOperationGitRepoRunBulkOperationParams<T> {
+    /**
+     * Runs the bulk operation.
+     *
+     * @returns The operation's result.
+     */
+    readonly operation: () => Promise<T>;
+    /**
+     * The id of the plugin running the operation.
+     */
+    readonly pluginId: string;
+    /**
+     * Waits for the follow-ups the operation set off (rename handlers, link updates, the metadata cache) to finish, so
+     * their changes land in the operation's commit.
+     */
+    readonly settle: () => Promise<void>;
+    /**
+     * A one-line description of the operation, used in the commit subject.
+     */
+    readonly summary: string;
+}
+/**
+ * The result of {@link BulkOperationGitRepo.runBulkOperation}.
+ *
+ * @typeParam T - The type of the operation's result.
+ */
+export interface GitBulkOperationResult<T> {
+    /**
+     * The hash of the commit recording the operation, or `null` when the operation changed nothing.
+     */
+    readonly commitSha: null | string;
+    /**
+     * The operation id, such as `OP12`.
+     */
+    readonly operationId: string;
+    /**
+     * The operation's result.
+     */
+    readonly result: T;
+}
+/**
+ * The result of {@link BulkOperationGitRepo.revertBulkOperationCommit}.
+ */
+export interface GitRevertResult {
+    /**
+     * Whether the revert stopped on a conflict, leaving the repo mid-revert for the user to resolve.
+     */
+    readonly isConflict: boolean;
+    /**
+     * What git printed.
+     */
+    readonly output: string;
+}
+/**
+ * A git repo holding a vault, driven to wrap bulk operations in commits.
+ */
+export declare class BulkOperationGitRepo {
+    /**
+     * The absolute path of the repo's git directory.
+     */
+    readonly gitDirectory: string;
+    /**
+     * The absolute path of the folder whose changes are committed.
+     */
+    readonly workingDirectory: string;
+    private readonly lockFilePath;
+    private readonly lockWaitTimeoutInMilliseconds;
+    private ownLock;
+    /**
+     * Creates a new instance. Use {@link BulkOperationGitRepo.open} to find the repo of a folder.
+     *
+     * @param params - The constructor parameters.
+     */
+    constructor(params: BulkOperationGitRepoConstructorParams);
+    /**
+     * Finds the git repo a folder belongs to.
+     *
+     * @param workingDirectory - The folder, normally the vault root.
+     * @returns The repo, or `null` when the folder is not inside a git work tree or `git` cannot be run.
+     */
+    static open(workingDirectory: string): Promise<BulkOperationGitRepo | null>;
+    /**
+     * Refuses to go on when the repo routes files through git-annex but `git-annex` cannot be run, since a
+     * plain `git add` would then put the large files into git itself.
+     */
+    assertCanCommitLargeFiles(): Promise<void>;
+    /**
+     * Lists the bulk-operation commits a plugin made on the current branch, newest first.
+     *
+     * @param pluginId - The plugin id.
+     * @returns The commits.
+     */
+    listBulkOperationCommits(pluginId: string): Promise<BulkOperationCommit[]>;
+    /**
+     * Commits whatever a stale lock's operation left behind as `OP<n> interrupted` and removes the lock.
+     *
+     * @returns The id of the recovered operation, or `null` when there was no stale lock.
+     */
+    recoverStaleLock(): Promise<null | string>;
+    /**
+     * Reverts a bulk-operation commit with `git revert --no-edit`.
+     *
+     * Whatever is pending is committed first, so the revert starts from a clean tree. A conflict is NOT aborted: the
+     * repo is left mid-revert for the user to resolve.
+     *
+     * @param commit - The commit to revert.
+     * @returns Whether the revert stopped on a conflict, and what git printed.
+     */
+    revertBulkOperationCommit(commit: BulkOperationCommit): Promise<GitRevertResult>;
+    /**
+     * Runs a bulk operation between two commits.
+     *
+     * Takes the lease lock, commits whatever is pending as `chore: before OP<n>`, runs the operation, waits for its
+     * follow-ups to settle, commits the result as `OP<n>: <summary>` and releases the lock. An operation that throws
+     * still gets its partial changes committed, as `OP<n> interrupted`, before the error is rethrown.
+     *
+     * @typeParam T - The type of the operation's result.
+     * @param params - The parameters.
+     * @returns The operation's result, its id and the hash of its commit.
+     */
+    runBulkOperation<T>(params: BulkOperationGitRepoRunBulkOperationParams<T>): Promise<GitBulkOperationResult<T>>;
+    private acquireLock;
+    private allocateOperationId;
+    private commitOperation;
+    private commitPending;
+    private commitStaged;
+    private createThrottledHeartbeat;
+    private findNextOperationId;
+    private heartbeat;
+    private isOwnLock;
+    private isStale;
+    private readLock;
+    private recover;
+    private releaseLock;
+    private runGit;
+    private stageAll;
+    private tryCreateLock;
+    private writeLock;
+}
+/**
+ * An error thrown when a `git` command fails.
+ */
+export declare class GitCommandError extends Error {
+    readonly gitArguments: readonly string[];
+    readonly exitCode: number;
+    readonly stderr: string;
+    /**
+     * Creates a new instance.
+     *
+     * @param gitArguments - The arguments `git` was run with.
+     * @param exitCode - The exit code.
+     * @param stderr - What `git` printed to stderr.
+     */
+    constructor(gitArguments: readonly string[], exitCode: number, stderr: string);
+}