@skrr-ai/cli 0.1.87 → 0.1.89

package/dist/lib/computer-files.d.ts

@@ -0,0 +1,239 @@
+import type { ComputerFileArchiveChunkResult, ComputerFileArchivePrepareResult, ComputerFileArchiveReleaseResult, ComputerFileEntityTag, ComputerFileEntry, ComputerFileGitStatusResult, ComputerFileListResult, ComputerFileMutationResult, ComputerFileSearchHit, ComputerFileSearchResult, ComputerFileStatResult } from '@skrr-ai/data-provider';
+import { type DedicatedRuntimeScope } from './dedicated-machines';
+/** The generation a command's file calls present; see the header. */
+export interface ComputerFileGeneration {
+    generation: number;
+}
+/**
+ * The lease could not say which generation is running — a server that does not
+ * publish it yet, or a lease with none. File calls cannot be fenced without
+ * one, and the server refuses them unfenced, so the command stops here.
+ */
+export declare class DedicatedFileGenerationUnavailableError extends Error {
+    readonly code = "DEDICATED_RUNTIME_GENERATION_UNAVAILABLE";
+    constructor(leaseId: string);
+}
+/**
+ * Read the lease once and return the generation every file call of this
+ * command presents. Resolved at the START of a command and never again: a
+ * second read mid-command would follow a replacement, which is exactly what
+ * the fence exists to refuse.
+ */
+export declare function resolveDedicatedFileGeneration(leaseId: string, scope?: DedicatedRuntimeScope): Promise<number>;
+/**
+ * List one directory on the machine, one page. `cursor` continues an earlier
+ * page's `nextCursor`; a withheld entry comes back with `withheld.reason`
+ * rather than silently absent (§18).
+ */
+export declare function listComputerFiles(leaseId: string, input: {
+    path: string;
+    cursor?: string;
+    limit?: number;
+} & ComputerFileGeneration, scope?: DedicatedRuntimeScope): Promise<ComputerFileListResult>;
+/**
+ * Stat one path — the entry, and its optimistic-concurrency `tag`. With
+ * `contents` a folder's tag also carries `contents` (a digest of everything
+ * inside it, at any depth) and the answer its total `entries`: the tag a
+ * fenced recursive delete presents. Needs `computer_files_fenced_v1`.
+ */
+export declare function statComputerFile(leaseId: string, input: {
+    path: string;
+    contents?: boolean;
+} & ComputerFileGeneration, scope?: DedicatedRuntimeScope): Promise<ComputerFileStatResult>;
+/**
+ * Search under a folder by file name or (`content`) by text. The answer carries
+ * its own `state` and the bounds that applied — see `computerFileSearchLines`
+ * for saying them. Defaults (ignore rules honoured, the machine's limit and
+ * time bound) are the machine's, so only what the caller set is sent.
+ */
+export declare function searchComputerFiles(leaseId: string, input: {
+    path: string;
+    query: string;
+    content?: boolean;
+    respectIgnore?: boolean;
+    caseSensitive?: boolean;
+    limit?: number;
+    budgetMs?: number;
+} & ComputerFileGeneration, scope?: DedicatedRuntimeScope): Promise<ComputerFileSearchResult>;
+/** The git marks of one folder's entries (`modified`, `untracked`, …). */
+export declare function gitStatusComputerFiles(leaseId: string, input: {
+    path: string;
+} & ComputerFileGeneration, scope?: DedicatedRuntimeScope): Promise<ComputerFileGitStatusResult>;
+/** Create a directory, including missing parents. */
+export declare function mkdirComputerFile(leaseId: string, input: {
+    path: string;
+} & ComputerFileGeneration, scope?: DedicatedRuntimeScope): Promise<ComputerFileMutationResult>;
+/**
+ * Rename or move one path. `tag` fences it: the move is refused `file_changed`
+ * when the source no longer matches the tag it was read with.
+ */
+export declare function moveComputerFile(leaseId: string, input: {
+    from: string;
+    to: string;
+    tag?: ComputerFileEntityTag;
+} & ComputerFileGeneration, scope?: DedicatedRuntimeScope): Promise<ComputerFileMutationResult>;
+/**
+ * Delete one path. A folder is refused `not_empty` unless `recursive` is asked
+ * for; `tag` fences the delete against a file that changed since it was read.
+ * A RECURSIVE delete with a tag must present the folder's contents tag
+ * (`statComputerFile({contents: true})`): anything changed inside it since is
+ * refused `file_changed`, and a tag without `contents` is refused
+ * `contents_tag_required`. A recursive delete without a tag is unfenced.
+ */
+export declare function deleteComputerFile(leaseId: string, input: {
+    path: string;
+    tag?: ComputerFileEntityTag;
+    recursive?: boolean;
+} & ComputerFileGeneration, scope?: DedicatedRuntimeScope): Promise<ComputerFileMutationResult>;
+/**
+ * Stage a folder's archive on the machine (`archive` prepare). The machine
+ * holds the staged bytes until `releaseComputerFileArchive` — or until its own
+ * stale-staging sweep — so callers always release.
+ */
+export declare function prepareComputerFileArchive(leaseId: string, input: {
+    path: string;
+} & ComputerFileGeneration, scope?: DedicatedRuntimeScope): Promise<ComputerFileArchivePrepareResult>;
+/** One chunk of a staged archive; `eof` ends the read. */
+export declare function readComputerFileArchiveChunk(leaseId: string, input: {
+    archiveId: string;
+    offset?: number;
+    length?: number;
+} & ComputerFileGeneration, scope?: DedicatedRuntimeScope): Promise<ComputerFileArchiveChunkResult>;
+/** Release a staged archive. Best-effort callers still call it. */
+export declare function releaseComputerFileArchive(leaseId: string, input: {
+    archiveId: string;
+} & ComputerFileGeneration, scope?: DedicatedRuntimeScope): Promise<ComputerFileArchiveReleaseResult>;
+export interface ComputerFileArchiveIo {
+    prepare: typeof prepareComputerFileArchive;
+    readChunk: typeof readComputerFileArchiveChunk;
+    release: typeof releaseComputerFileArchive;
+    /** Run `fn` if the process exits; returns the unregister. Injectable for tests. */
+    onProcessExit: (fn: () => void) => () => void;
+}
+export interface ComputerFileArchiveDownloadOptions extends Partial<ComputerFileArchiveIo> {
+    signal?: AbortSignal;
+    onProgress?: (received: number, total: number) => void;
+}
+export interface ComputerFileArchiveDownloadResult {
+    /** The folder on the machine that was archived. */
+    path: string;
+    /** The folder's name, as the machine named the archive. */
+    name: string;
+    format: string;
+    /** Entries the archive holds. */
+    entries: number;
+    /** The archive's byte size, as prepared. */
+    size: number;
+    /** Bytes written to the destination. */
+    bytes: number;
+    /** The local file written. */
+    destination: string;
+    /** False when release failed; the machine sweeps a stale archive itself. */
+    archiveReleased: boolean;
+}
+/**
+ * Where a folder download lands. A destination that names a directory — spelled
+ * with a trailing separator, or an existing one — receives `<name>.<format>`
+ * inside it, as `cp` already treats directories.
+ */
+export declare function computerFileArchiveDestination(localPath: string | undefined, name: string, format: string, 
+/** Whether `localPath` names an existing directory (caller's stat). */
+isDirectory: boolean): string;
+/**
+ * Download one folder as its staged archive, prepare → chunks → release. Every
+ * call — prepare, each chunk, the release — presents the one `generation` the
+ * command resolved, so a machine replaced mid-download refuses the rest.
+ *
+ * The local write is never half-visible: chunks land in a temporary file beside
+ * the destination and are renamed into place at the end; a failed or cancelled
+ * download removes the temporary and still releases the staged archive. The
+ * archive itself is one immutable staged file, so chunks always belong to the
+ * same tree snapshot — there is no mid-copy change to fence here.
+ */
+export declare function downloadComputerFileArchive(leaseId: string, remotePath: string, localPath: string | undefined, generation: number, scope?: DedicatedRuntimeScope, io?: ComputerFileArchiveDownloadOptions): Promise<ComputerFileArchiveDownloadResult>;
+/**
+ * The tag exactly as `--tag` takes it back: `inode:size:mtimeNs`, the triple
+ * `stat` prints and a `file_changed` refusal carries — and, for a folder read
+ * with `stat --contents`, a fourth part, `inode:size:mtimeNs:contents`, the
+ * digest a fenced recursive delete presents.
+ */
+export declare function computerFileTagString(tag: ComputerFileEntityTag): string;
+/**
+ * Parse a `--tag` value: the compact `inode:size:mtimeNs[:contents]` form, or
+ * the JSON object `--json` output prints. Throws a usage-shaped Error, never a
+ * half-tag.
+ */
+export declare function parseComputerFileTag(text: string): ComputerFileEntityTag;
+/** `drwxr-x---` — the entry's type char plus its permission bits. */
+export declare function computerFileModeString(type: string, mode: number): string;
+/** `1.2 MiB`, `3182 B` — sizes a person scans. */
+export declare function formatComputerFileSize(bytes: number): string;
+/**
+ * How one `ls` row names its entry: `name` (dirs marked `/`), a symlink's
+ * stored target (`a -> b`, never followed), and a withheld entry said as
+ * withheld with the reason — never rendered as an ordinary readable file.
+ */
+export declare function computerFileEntryName(entry: ComputerFileEntry): string;
+/** One search hit as a line: `path`, or `path:line: text` for a content match. */
+export declare function computerFileSearchHitLine(hit: ComputerFileSearchHit): string;
+/**
+ * The search read-out. The closing line says how it ended: a list cut at the
+ * limit or the time bound is never printed as if it were the whole answer, and
+ * "nothing found" is said only for a search that finished.
+ */
+export declare function computerFileSearchLines(result: ComputerFileSearchResult): string[];
+/** The git-status read-out; `timed_out` offers no marks and says so. */
+export declare function computerFileGitStatusLines(result: ComputerFileGitStatusResult): string[];
+/** The parsed refusal body of a thrown call, when the wire sent one. */
+export declare function computerFileRefusalBody(err: unknown): Record<string, unknown> | null;
+/**
+ * The refusal, or null when the failure is not a computer refusal at all (an
+ * edge page, a lease that does not resolve — `formatDedicatedRuntimeApiError`'s
+ * cases, which the caller then handles).
+ *
+ * Codes the route returns that are not in COMPUTER_REFUSAL_CODES — `internal`,
+ * `not_supported`, a middleware's own — are still the refusal: they carry the
+ * same `{error, code, message}` envelope and there is no second reader to hand
+ * them to.
+ */
+export declare function computerFileRefusalInfo(err: unknown): {
+    code: string;
+    message: string;
+    status?: number;
+    currentTag?: ComputerFileEntityTag;
+    details?: Record<string, unknown>;
+    missingCapability?: string;
+    operation?: string;
+    body: Record<string, unknown>;
+} | null;
+export interface ComputerFileFailure {
+    message: string;
+    code: string;
+    status?: number;
+    retryable: boolean;
+    /** The refusal body verbatim, for the `--json` envelope's `error.details`. */
+    details?: Record<string, unknown>;
+    requestId?: string;
+}
+/**
+ * One refusal → the sentence the command prints: the server's own message, then
+ * what to do about it. A refusal that names its fix in the message already
+ * (`too_large` ends "Push it through Git or object storage instead.") is not
+ * given a second one.
+ */
+export declare function describeComputerFileRefusal(refusal: NonNullable<ReturnType<typeof computerFileRefusalInfo>>, ctx: {
+    bin: string;
+    leaseId?: string;
+    takesTag?: boolean;
+}): string;
+/**
+ * Everything a command needs to print a failure — the computer refusal
+ * sentence when the wire sent one, or the dedicated-runtime reading otherwise
+ * (edge page, lease not found). Null means neither had anything to say, and
+ * the caller falls back to `handleApiError`.
+ */
+export declare function describeComputerFileFailure(err: unknown, ctx: {
+    bin: string;
+    leaseId?: string;
+    takesTag?: boolean;
+}): ComputerFileFailure | null;