@shardflux/cli 0.15.2 → 0.16.0

package/dist/files-mirror.d.ts

@@ -0,0 +1,164 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import type { Conversation, LocalConversation } from './conversations.js';
+/**
+ * Files across conversations on the Mac (docs/progress/cross-conversation-files.md): a read-only folder per
+ * conversation, `~/Shardflux/<repository>/<base branch>/<conversation>/`, holding what that conversation committed
+ * relative to its fork point. Git (the project hub) is the only channel; the user's own checkouts are never written.
+ * Files above the per-file limit, or past the conversation's total, are placeholders until `shard files pull`.
+ */
+export declare const HUB_PATH = "/shardflux/project/git/hub.git";
+export declare const MANIFEST = ".shardflux-manifest.json";
+export declare const PLACEHOLDER = ".placeholder.txt";
+export declare const FILES_CONFIG = ".shardflux/files.yaml";
+export declare const DEFAULT_MAX_FILE: number;
+export declare const DEFAULT_MAX_CONVERSATION: number;
+export type MirrorConversation = Conversation & {
+    name?: string;
+    join_mode?: string | null;
+    base_branch?: string | null;
+    repo_remote?: string;
+    landed?: {
+        how: string;
+        ref?: string;
+        at?: string;
+    } | null;
+};
+export interface ManifestFile {
+    path: string;
+    oid: string;
+    size: number;
+    mode: string;
+    state: 'present' | 'placeholder' | 'submodule' | 'symlink';
+    reason?: 'file_limit' | 'conversation_limit';
+    fetched?: boolean;
+}
+export interface Manifest {
+    version: 1;
+    conversation_id: string;
+    project_id: string;
+    name: string;
+    title: string;
+    repository: string;
+    branch: string;
+    base_branch: string | null;
+    commit: string;
+    fork_point: string;
+    seed?: string;
+    max_file_bytes: number;
+    max_conversation_bytes: number;
+    files: ManifestFile[];
+    deleted: string[];
+    landed?: {
+        how: string;
+        ref: string;
+        at: string;
+        note: string;
+    };
+    updated_at: string;
+}
+export interface Limits {
+    maxFile: number;
+    maxConversation: number;
+}
+export interface Change {
+    status: string;
+    mode: string;
+    oid: string;
+    path: string;
+}
+export declare function filesRoot(env: Record<string, string | undefined>): string;
+/** A base branch as one path component: slashes and other separators become "-". */
+export declare function branchFolder(branch: string | null | undefined): string;
+/** A human name as one Finder path component. */
+export declare function humanFolder(text: string, fallback: string): string;
+export declare function repositoryName(identity: string): string;
+export declare function parseFilesConfig(text: string | undefined): Limits;
+export declare function parseDiffTree(bytes: Buffer): Change[];
+export declare function safeRelative(path: string): boolean;
+/** Smallest first while the conversation's total stays within its limit; fetched files stay while unchanged. */
+export declare function planFiles(files: ManifestFile[], limits: Limits, prev: Map<string, ManifestFile>): ManifestFile[];
+export declare function humanBytes(n: number): string;
+export declare function placeholderText(m: Manifest, f: ManifestFile): string;
+export interface GitResult {
+    code: number;
+    stdout: Buffer;
+    stderr: string;
+}
+/**
+ * Read-only git against the project hub. `blobs` delivers `git cat-file --batch` output for the given ids, any number
+ * of files at once. (The hub's upload-pack, reached through the platform Git bridge, serves advertised refs only, so a
+ * fetch of single blobs by id is refused; this needs no hub configuration.)
+ */
+export interface Hub {
+    git(args: string[], stdin?: string): Promise<GitResult>;
+    blobs(oids: string[], onData: (chunk: Uint8Array) => void): Promise<void>;
+    close(): void;
+}
+/** A hub on this machine (tests). */
+export declare function localHub(path: string): Hub;
+/** The project hub through a ready VM of the project: git runs there, file contents stream back over the same exec API. */
+export declare function cellHub(ws: Workspace, signal: AbortSignal): Hub;
+/** Copy files' contents from the hub into root, in one stream. */
+export declare function copyFromHub(hub: Hub, root: string, files: ManifestFile[]): Promise<void>;
+export interface PlaceholderEntry {
+    conversation_id: string;
+    conversation: string;
+    title: string;
+    folder: string;
+    path: string;
+    size: number;
+    local_path: string;
+}
+export declare class FilesMirrorState {
+    readonly revisions: Map<string, string>;
+    retryAt: number;
+    failures: number;
+    listedAt: number;
+    readonly reported: Set<string>;
+}
+/** The repository a conversation belongs to: its normalized remote; worktrees of an origin-less repository share its Git common directory. */
+export declare function repositoryIdentity(c: MirrorConversation, local?: LocalConversation): {
+    id: string;
+    name: string;
+};
+export declare class FilesMirror {
+    #private;
+    readonly root: string;
+    readonly ctx: Pick<Ctx, 'io' | 'store' | 'apiUrl' | 'signal'>;
+    readonly connect: (projectId: string, all: MirrorConversation[]) => Promise<Hub>;
+    constructor(ctx: Pick<Ctx, 'io' | 'store' | 'apiUrl' | 'signal'>, connect: (projectId: string, all: MirrorConversation[]) => Promise<Hub>, root?: string);
+    get stateFile(): string;
+    get indexFile(): string;
+    /** One pass: only conversations whose API record moved touch the hub. */
+    sync(all: MirrorConversation[], state?: FilesMirrorState): Promise<void>;
+    /** Find a mirrored conversation by id, name or folder name. */
+    find(ref: string): {
+        rel: string;
+        manifest: Manifest;
+    };
+    /** Download one listed file, whatever its size. */
+    pull(ref: string, path: string, all: () => Promise<MirrorConversation[]>): Promise<{
+        conversation: string;
+        path: string;
+        local_path: string;
+        bytes: number;
+        already: boolean;
+    }>;
+}
+/**
+ * The seed snapshot (sh; $1 repository, $2 conversation name, $3 hub): HEAD plus the working tree the conversation was
+ * seeded with, committed in the conversation's VM with a temporary index (never on this computer), kept per worktree
+ * as refs/worktree/shard/seed and in the hub as refs/shard/seed/<name>. Mirrors leave out what it already contains,
+ * so the user's own uncommitted edits never show as the conversation's change. Threads on one computer are worktrees
+ * of one repository (0.16.0+), so the seed is per worktree; the shared refs/shard/seed of earlier seeds is read, and
+ * still written, only in the repository's main worktree.
+ */
+export declare const SEED_SNAPSHOT = "set -eu\ncd \"$1\"\nmain=0; [ \"$(git rev-parse --absolute-git-dir)\" = \"$(git rev-parse --path-format=absolute --git-common-dir)\" ] && main=1\nif git rev-parse -q --verify refs/worktree/shard/seed >/dev/null; then seed=$(git rev-parse refs/worktree/shard/seed)\nelif [ \"$main\" = 1 ] && git rev-parse -q --verify refs/shard/seed >/dev/null; then seed=$(git rev-parse refs/shard/seed); else\nidx=$(mktemp); trap 'rm -f \"$idx\"' EXIT\ncp \"$(git rev-parse --path-format=absolute --git-path index)\" \"$idx\" 2>/dev/null || { rm -f \"$idx\"; GIT_INDEX_FILE=\"$idx\" git read-tree HEAD; }\nGIT_INDEX_FILE=\"$idx\" git add -A\ntree=$(GIT_INDEX_FILE=\"$idx\" git write-tree)\nif [ \"$tree\" = \"$(git rev-parse 'HEAD^{tree}')\" ]; then seed=$(git rev-parse HEAD); else\nseed=$(GIT_AUTHOR_NAME=Shardflux GIT_AUTHOR_EMAIL=seed@shardflux.dev GIT_COMMITTER_NAME=Shardflux GIT_COMMITTER_EMAIL=seed@shardflux.dev git commit-tree \"$tree\" -p HEAD -m \"Shardflux: the working tree this conversation started from\"); fi\ngit update-ref refs/worktree/shard/seed \"$seed\"\nif [ \"$main\" = 1 ]; then git update-ref refs/shard/seed \"$seed\"; fi\nfi\nif [ -d \"$3\" ]; then git -c core.hooksPath=/dev/null push -q \"$3\" \"+$seed:refs/shard/seed/$2\" >/dev/null 2>&1 || true; fi\nprintf '%s\n' \"$seed\"\n";
+/** Best effort: without a snapshot the folder also lists the start state's own edits. */
+export declare function recordSeedSnapshot(ws: Pick<Workspace, 'cell'>, c: Pick<Conversation, 'worktree_path' | 'branch'>, signal?: AbortSignal): Promise<string | null>;
+/** A ready VM of the project (never woken), else the project's space reader, woken when needed. */
+export declare function workspaceHub(ctx: Ctx): (projectId: string, all: MirrorConversation[]) => Promise<Hub>;
+export declare function listMirrorConversations(ctx: Ctx): Promise<MirrorConversation[]>;
+/** The device helper's pass: list every few seconds; touch the hub only for conversations whose record moved. */
+export declare function mirrorFilesOnce(ctx: Ctx, state: FilesMirrorState, intervalMs?: number): Promise<void>;