@pellux/goodvibes-sdk 0.36.0 → 0.37.1

package/dist/platform/workspace/checkpoint/manager.d.ts

@@ -0,0 +1,214 @@
+/**
+ * manager.ts
+ *
+ * WorkspaceCheckpointManager — the coarse, whole-workspace rewind layer.
+ *
+ * Complements (does not replace) FileUndoManager (../../state/file-undo.ts),
+ * which stays as the fine-grained, in-memory, per-file /undo layer. This
+ * manager persists across sessions, snapshots the ENTIRE workspace tree, and
+ * survives process restarts (backed by git objects + a JSON manifest on
+ * disk), which is the wrong shape for FileUndoManager but exactly the shape
+ * needed for "revert everything turn N did" or "restore the workspace to how
+ * it looked an hour ago".
+ *
+ * Storage layout (workspace-local, see side-git.ts for the git mechanics):
+ *   <workspaceRoot>/.goodvibes/checkpoints/git         — side GIT_DIR
+ *   <workspaceRoot>/.goodvibes/checkpoints/index.json  — manifest (JsonFileStore)
+ *
+ * Checkpoint refs live at refs/goodvibes/checkpoints/<id> inside the side
+ * repo, entirely separate from the user's real git refs and from compaction's
+ * `cpt_` boundary commits (which are conversation snapshots, not filesystem
+ * snapshots, and are not stored in git at all — see types.ts's header comment
+ * for the full disambiguation).
+ *
+ * Automatic snapshots subscribe to EXISTING runtime bus events
+ * (TURN_COMPLETED / TURN_ERROR / TURN_CANCEL / AGENT_COMPLETED) — no new
+ * event contract is introduced by this module.
+ */
+import type { RuntimeEventBus } from '../../runtime/events/index.js';
+import { type RetentionConfig, type RetentionClass, type PruneResult } from '../../runtime/retention/index.js';
+import type { WorkspaceCheckpoint, CheckpointKind, CheckpointDiff, RestoreResult } from './types.js';
+export interface CreateCheckpointOptions {
+    readonly kind: CheckpointKind;
+    readonly label?: string | undefined;
+    readonly retentionClass?: RetentionClass | undefined;
+    readonly turnId?: string | undefined;
+    readonly agentId?: string | undefined;
+    /** Scope the snapshot to these paths instead of sweeping the whole workspace. */
+    readonly paths?: string[] | undefined;
+}
+export interface RestoreOptions {
+    /** Restrict restore to these paths instead of the whole workspace. */
+    readonly paths?: string[] | undefined;
+    /** Take a safety checkpoint of the current state before restoring. Defaults to true. */
+    readonly safetyCheckpoint?: boolean | undefined;
+}
+export interface ListCheckpointsFilter {
+    readonly kind?: CheckpointKind | undefined;
+    readonly since?: number | undefined;
+    readonly limit?: number | undefined;
+}
+export interface WorkspaceCheckpointManagerOptions {
+    readonly workspaceRoot: string;
+    /** Override the side repo's GIT_DIR. Defaults to `<workspaceRoot>/.goodvibes/checkpoints/git`. */
+    readonly checkpointDir?: string | undefined;
+    /** When provided, the manager subscribes to TURN_COMPLETED/TURN_ERROR/TURN_CANCEL/AGENT_COMPLETED for automatic snapshots. */
+    readonly runtimeBus?: RuntimeEventBus | undefined;
+    readonly retention?: Partial<RetentionConfig> | undefined;
+    /** Clock override for deterministic tests. */
+    readonly now?: (() => number) | undefined;
+}
+/**
+ * WorkspaceCheckpointManager — create/list/diff/restore/gc for whole-workspace
+ * git-backed snapshots, plus automatic snapshotting on existing turn/agent
+ * lifecycle events.
+ */
+export declare class WorkspaceCheckpointManager {
+    readonly workspaceRoot: string;
+    private readonly checkpointRootDir;
+    private readonly sideGit;
+    private readonly manifestStore;
+    private readonly retentionPolicy;
+    private readonly now;
+    private readonly runtimeBus;
+    private readonly unsubscribers;
+    private checkpoints;
+    private initialized;
+    private initPromise;
+    /**
+     * Promise-chain mutex serializing every public operation that touches the
+     * side repo's shared index or shared object store: `create`, `restore`,
+     * `gc`, and `diff` (see each method's `*Internal` body below). Without
+     * this, an auto-snapshot `create()` firing on a bus event (TURN_COMPLETED,
+     * TURN_ERROR, TURN_CANCEL, or AGENT_COMPLETED) could run its `git add -A`
+     * in between `restore()`'s
+     * `read-tree --reset` and `checkout-index -a -f`, silently corrupting the
+     * restore; two concurrent `create()` calls share the same hazard on the
+     * index, and a same-tick `gc()` could treat a not-yet-ref'd loose commit
+     * from an in-flight `create()` as unreachable and prune it out from under
+     * it. `diff()` is included too: the single-argument `git diff <tree-ish>`
+     * form (diffing a checkpoint against the live working tree) refreshes the
+     * index's stat cache as a side effect, which is itself a write.
+     *
+     * Each public method below only does `await this.init()` (idempotent, safe
+     * to race) before calling `withLock`; the actual git-touching work lives in
+     * a same-named `*Internal` method. Internal callers that need another
+     * locked operation's behavior (e.g. `restore()`'s safety checkpoint) call
+     * the `*Internal` method directly — never the public wrapper — so a single
+     * logical operation never tries to re-enter its own lock.
+     */
+    private lockChain;
+    private withLock;
+    constructor(opts: WorkspaceCheckpointManagerOptions);
+    /**
+     * Idempotent setup: init the side repo, load the manifest (re-hydrating the
+     * in-memory RetentionPolicy so retention state survives process restarts),
+     * and subscribe to automatic-snapshot events if a runtime bus was provided.
+     * Safe to call multiple times; concurrent callers share one in-flight init.
+     */
+    init(): Promise<void>;
+    private _init;
+    /**
+     * Subscribes to the EXISTING turn/agent lifecycle events — no new event
+     * types are introduced. A snapshot is taken at the boundary AFTER each
+     * turn/agent-run finishes, meaning "revert everything turn N did" means
+     * restoring the checkpoint captured BEFORE turn N, i.e. checkpoint[N-1] in
+     * `list()`'s (newest-first) ordering — an intentional off-by-one, documented
+     * here rather than hidden: this module always snapshots "where things ended
+     * up", never "where things started".
+     *
+     * Listener bodies are wrapped so a failure NEVER throws back into the bus:
+     * `RuntimeEventBus.emit()` only catches synchronous throws from a listener,
+     * not rejections from a returned (but un-awaited) promise, so every
+     * auto-snapshot call here is deliberately `.catch()`-guarded.
+     */
+    private subscribeToAutomaticSnapshots;
+    /**
+     * Create a new checkpoint. Returns `null` (a cheap no-op) when the current
+     * workspace tree is identical to the parent checkpoint's tree — no commit,
+     * no ref, no manifest entry is created in that case.
+     *
+     * Serialized against every other index-touching operation on this manager
+     * — see `withLock`.
+     */
+    create(opts: CreateCheckpointOptions): Promise<WorkspaceCheckpoint | null>;
+    private createInternal;
+    /** List checkpoints, newest-first. `list()[0]` is always the most recent checkpoint. */
+    list(filter?: ListCheckpointsFilter): Promise<WorkspaceCheckpoint[]>;
+    /**
+     * Diff two checkpoints, or a checkpoint against the live working tree when
+     * `b` is omitted.
+     *
+     * Serialized against every other index-touching operation on this manager
+     * — see `withLock`. The single-argument form (`b` omitted, diffing against
+     * the live working tree) refreshes the side index's stat cache as a side
+     * effect, so it is not purely read-only.
+     */
+    diff(a: string, b?: string): Promise<CheckpointDiff>;
+    private diffInternal;
+    /**
+     * Restore the workspace to the state captured by checkpoint `id`.
+     *
+     * By default (`safetyCheckpoint: true`) takes a checkpoint of the CURRENT
+     * state first, so a restore is itself undoable via another restore.
+     *
+     * Whole-workspace restore (no `opts.paths`):
+     *   1. Snapshot the current tracked-file set (via the safety checkpoint, or
+     *      a transient write-tree when `safetyCheckpoint: false`) — this is the
+     *      "before" set.
+     *   2. Reset the side index to the target checkpoint's tree and check every
+     *      file in it out to disk (re-creates anything the checkpoint had that
+     *      is currently missing or modified).
+     *   3. Remove exactly the files that were in the "before" set but are NOT
+     *      in the target checkpoint's tree (files created/tracked after the
+     *      checkpoint). Anything NOT in the "before" set — i.e. any untracked
+     *      path outside what this engine has ever snapshotted — is never
+     *      touched, by construction: it never appears in either set.
+     *
+     * Scoped restore (`opts.paths` provided) only checks out those paths from
+     * the target tree; it never removes files outside the given paths.
+     *
+     * Serialized against every other index-touching operation on this manager
+     * — see `withLock`. Without this, an auto-snapshot `create()` firing on a
+     * bus event could run its `git add -A` in between the `read-tree --reset`
+     * and `checkout-index -a -f` calls below, silently corrupting the restore.
+     */
+    restore(id: string, opts?: RestoreOptions): Promise<RestoreResult>;
+    private restoreInternal;
+    /**
+     * Apply retention limits: `RetentionPolicy` selects prune candidates,
+     * `WorkspaceCheckpointPruner` deletes their refs, then (only if anything
+     * was actually deleted) a single `git gc --prune=now` reclaims the now-
+     * unreachable objects. This never touches compaction's boundary commits —
+     * they are tracked in an entirely separate `RetentionPolicy` instance
+     * (../../runtime/compaction) with no shared state.
+     *
+     * Reclamation only works because checkpoint commits are parentless (see
+     * `SideGitRunner.commitTree`): a pruned ref's commit has no descendant
+     * keeping it reachable via a git parent pointer, so once its ref is
+     * deleted it is genuinely unreachable and `--prune=now` frees it.
+     *
+     * Serialized against every other index/object-store-touching operation on
+     * this manager — see `withLock`. Without this, a `create()` racing this
+     * method could write a loose commit object that isn't ref'd yet at the
+     * moment `--prune=now` runs, and lose it.
+     */
+    gc(): Promise<PruneResult>;
+    private gcInternal;
+    /** Unsubscribe from the runtime bus. Does not touch anything on disk. */
+    dispose(): void;
+    private mostRecentCheckpoint;
+    private requireCheckpoint;
+    private defaultLabel;
+    /**
+     * Approximate incremental bytes introduced by a checkpoint: sum of on-disk
+     * sizes of the changed paths, read immediately after they were staged and
+     * committed (so they still reflect exactly the content just captured).
+     * Deleted paths (no longer on disk) contribute 0. This is deliberately not
+     * exact git object-store accounting — it exists for retention's `maxSizeBytes`
+     * bookkeeping, not for a byte-perfect audit.
+     */
+    private computeSizeBytes;
+    private persistManifest;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/platform/workspace/checkpoint/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../../src/platform/workspace/checkpoint/manager.ts"],"names":[],"mappings":"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"}