@shardflux/cli 0.20.0 → 0.23.0

package/dist/prepared-repository.d.ts

@@ -0,0 +1,204 @@
+import type { SyncCell } from './project-sync-transfer.js';
+import type { OutsideFile } from './large-media.js';
+/** One upload part. */
+export declare const PART_BYTES: number;
+/** Blobs of S from this size on leave the thin pack: stored when incompressible, compressed apart otherwise. */
+export declare const LARGE_BLOB_BYTES: number;
+/** Large media above this follow the first prompt when the caller allows it. */
+export declare const DEFER_BYTES: number;
+/** Parts in flight at once, and their bytes. */
+export declare const UPLOAD_WINDOW = 4;
+export declare const UPLOAD_BUDGET_BYTES: number;
+/** The history the laptop sends before the cache fetches it from origin instead. */
+export declare const ORIGIN_FIRST_BYTES: number;
+/** The history the laptop sends before the cache takes the VM's own fetch of the branch (its boot prefetch) instead. */
+export declare const PREFETCH_ADOPT_BYTES: number;
+/** The local spool of generated packs (for resuming), pruned past this or a day. */
+export declare const SPOOL_BYTES: number;
+export interface PreparedExtra {
+    path: string;
+    sha256: string;
+    size: number;
+    mode: number;
+    symlink: boolean;
+    link_target: string;
+}
+export interface PreparedFile {
+    path: string;
+    oid: string;
+    size: number;
+    mode: number;
+}
+export interface PreparedManifest {
+    version: 2;
+    format: 'sha1' | 'sha256';
+    head: string;
+    seed: string;
+    /** The user's branch and its upstream, recreated in the VM as on this computer. */
+    branch?: string;
+    upstream?: {
+        ref: string;
+        oid: string;
+    };
+    origin: string | null;
+    repository: string;
+    worktree: string;
+    deps_hash?: string;
+    /** What Git does not hold: .env files (never in a Git object) and files whose filters change their bytes. */
+    extras: PreparedExtra[];
+    extras_key?: string;
+    /** Large untracked media, outside S: Git blobs the VM writes as files its Git ignores. */
+    files: PreparedFile[];
+    /** Deleted files S still names (only when S is HEAD: the twin snapshot was off or paused). */
+    remove: string[];
+    /** A shallow clone's boundary commits: the cache and the worktree take the same boundary. */
+    shallow?: string[];
+}
+export interface PreparedSnapshot {
+    revision: string;
+    manifest: PreparedManifest;
+    directory: string;
+}
+export interface PreparedTransfer {
+    revision: string;
+    /** S, its archive and every media file are in the cache. Otherwise `pending` names the media still to send. */
+    complete: boolean;
+    pending: string[];
+    /** Bytes of the packs generated for this transfer: history and small files; large blobs; media; the archive. */
+    history_bytes: number;
+    large_bytes: number;
+    media_bytes: number;
+    extras_bytes: number;
+    /** Part bytes sent, and bytes the VM already held. */
+    uploaded_bytes: number;
+    reused_bytes: number;
+    puts: number;
+    execs: number;
+    max_in_flight_bytes: number;
+    origin_fetched: boolean;
+    /** Media that changed on this computer after the start captured them: they never arrive as captured. */
+    changed: string[];
+    timings: Record<string, number>;
+    /** The checkout the probe made (options.apply) when the cache already held the revision. */
+    applied?: PreparedApply;
+}
+export interface PreparedGitConfig {
+    origin_url?: string;
+    user?: {
+        name?: string;
+        email?: string;
+    };
+    tracking?: {
+        branch: string;
+        merge: string;
+    };
+    excludes?: string;
+}
+export interface PreparedApply {
+    revision: string;
+    mode: 'fresh' | 'inplace' | 'existing';
+    /** Media not in the cache yet, and media landing right after the reply (Git ignores both). */
+    pending: number;
+    landing: number;
+    dependencies: number;
+    timings: Record<string, number>;
+}
+export declare function preparedCachePath(remote: string): string;
+export declare const preparedDirectory: (stateDir: string, folder: string) => string;
+/** The manifest's identity bytes: sorted keys, no spaces, UTF-8 (prepared-repository.py `canonical`). */
+export declare function canonicalJson(value: unknown): string;
+export declare const manifestRevision: (m: PreparedManifest) => string;
+/** A refusal the VM half reports by reason (missing or corrupt parts, an owned worktree, ...). */
+export declare class PreparedRefusal extends Error {
+    readonly reason: string;
+    readonly chunks: string[];
+    constructor(reason: string, message: string, chunks?: string[]);
+}
+/**
+ * The prepared revision of a worktree's state: S (the twin seed, already made), its large media and its extras. S's
+ * objects stay in the local repository under refs/shard/prepared/<revision> until the start that uses it is done, so a
+ * start accepted before a deadline resumes later with exactly the state it began from, whatever the user edits.
+ */
+export declare function capturePreparedSnapshot(stateDir: string, folder: string, seed: {
+    commit: string;
+    outside?: OutsideFile[];
+}, origin: string | null, signal?: AbortSignal, options?: {
+    reachable?: (url: string) => boolean;
+    depsHash?: string;
+}): Promise<PreparedSnapshot>;
+/** The local pin of a revision's objects, once its start no longer needs them. */
+export declare function releaseLocalSnapshot(folder: string, revision: string): Promise<void>;
+export declare function readPreparedSnapshot(stateDir: string, folder: string, revision: string): Promise<PreparedSnapshot>;
+/** Where a conversation start's parts go: the VM's own disk, indexed there; the cache receives them after the reply. */
+export declare const PARTS_ROOT = "/home/user/.cache/shardflux/prepared-parts";
+/**
+ * Sends the revision, only what the project cache lacks. Without `apply` it goes into the cache (a preparation). With
+ * `apply` (a conversation start) it is checked out at that target: in the probe's own exec when the cache already
+ * holds the revision (a warm start is one exec), otherwise from parts uploaded to the VM's disk and indexed there, with
+ * no Git work on the shared cache before the reply; the cache receives them after it. With `defer`, media beyond
+ * DEFER_BYTES wait for a later call: the result names them in `pending`, and the worktree starts without them.
+ */
+export declare function transferPreparedSnapshot(cell: SyncCell, folder: string, cache: string, snapshot: PreparedSnapshot, options?: {
+    signal?: AbortSignal;
+    defer?: boolean;
+    pin?: string;
+    originFirstBytes?: number;
+    apply?: PreparedApplyTarget;
+    partsDir?: string;
+}): Promise<PreparedTransfer>;
+/** Git settings the VM repository copies from this one: origin, identity, the branch's upstream, exclude rules. */
+export declare function preparedGitConfig(folder: string, manifest: PreparedManifest, signal?: AbortSignal): Promise<PreparedGitConfig>;
+export interface PreparedApplyOptions {
+    signal?: AbortSignal;
+    git?: PreparedGitConfig;
+    preparation?: boolean;
+    replacePreparation?: boolean;
+    dependencySource?: string;
+    /** A new VM: files its image left at the worktree path (outside any repository) are checked out over. */
+    adopt?: boolean;
+    /** false keeps borrowing the cache's objects; 'now' copies them before returning (a template must not borrow). */
+    dissociate?: boolean | 'now';
+    background?: boolean;
+    releasePin?: string;
+    /** A shell script the VM runs, detached, once the worktree is ready (the seed's copy to the project hub). */
+    after?: {
+        script: string;
+        args: string[];
+    };
+    /** The conversation's setup intent (recordSetupIntent), written in the same exec before its repository appears. */
+    setupIntent?: {
+        conversation: string;
+        depsHash: string;
+    };
+    /** The VM's workspace: a checkout another VM's conversation made (and a template image brought) is taken over. */
+    workspace?: string;
+    /** Media already sent land before the reply, not after it (a client that compares the worktree's files at once). */
+    landNow?: boolean;
+}
+/** Where and how a revision is checked out: the VM half's apply request. */
+export interface PreparedApplyTarget {
+    root: string;
+    branch: string;
+    options?: PreparedApplyOptions;
+}
+/**
+ * Checks out the revision as `branch` at `root`, in one exec. Media not in the cache yet stay pending
+ * (landDeferredFiles). A root holding the same revision is left as it is; one holding another is refused, unless it is
+ * a project template's checkout or `replacePreparation`.
+ */
+export declare function applyPreparedSnapshot(cell: SyncCell, cache: string, revision: string, root: string, branch: string, options?: PreparedApplyOptions): Promise<PreparedApply>;
+/** Lands media that arrived after the start (where nothing is yet: the agent's own file stands); `drop` gives up on blobs that changed. */
+export declare function landDeferredFiles(cell: SyncCell, cache: string, revision: string, root: string, options?: {
+    signal?: AbortSignal;
+    drop?: string[];
+}): Promise<{
+    landed: number;
+    kept: number;
+    pending: number;
+}>;
+export declare function prunePreparedCache(cell: SyncCell, cache: string, signal?: AbortSignal): Promise<void>;
+/**
+ * The local spool stays bounded: a finished transfer's parts go at once; other parts and plans after a day or past
+ * the budget, oldest first; a revision's manifest and files archive (what a pending start resumes from) after a week.
+ */
+export declare function pruneLocalPrepared(stateDir: string, limit?: number, every?: number): Promise<void>;