@tomradex/files 0.23.1 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,7 @@
1
1
  import type { FileDescription, FileReference, Item } from "@tomradex/domain";
2
2
  import type { AttachmentInput, ConflictChoice, ConnectionState, FileConflict, FileContent, FileEntry, FileVersion, FilesAgentPolicy, FilesBackendView, FilesInfo, FilesStatus, FilesSyncPolicy, ListMode, SaveResult, SyncMode } from "./types.js";
3
3
  import type { AgentIndex } from "./agent-index.js";
4
+ import type { SyncProgress } from "@tomradex/git";
4
5
  declare module "@tomradex/ipc" {
5
6
  interface Channels {
6
7
  "files.backends": () => FilesBackendView[];
@@ -85,6 +86,8 @@ declare module "@tomradex/ipc" {
85
86
  interface Broadcasts {
86
87
  /** This project's files or their sync state moved. `paths` names the files that changed when the writer knows them; without it, refetch everything keyed by the project. */
87
88
  "files.changed": (projectId: string, paths?: string[]) => void;
89
+ /** A sync with the remote moved on a step or along its transfer; null once it ended, and `files.changed` follows. */
90
+ "files.progress": (projectId: string, progress: SyncProgress | null) => void;
88
91
  }
89
92
  }
90
93
  //# sourceMappingURL=channels.d.ts.map
@@ -1,5 +1,5 @@
1
1
  import type { FileReference } from "@tomradex/domain";
2
- import { type Git } from "@tomradex/git";
2
+ import { type Git, type SyncProgress } from "@tomradex/git";
3
3
  import { type ConflictChoice, type FileConflict, type FileContent, type FileEntry, type FileStore, type FileVersion, type FileSearchInput, type FileSearchResult, type FilesAgentPolicy, type FilesStatus, type FilesSyncPolicy, type ListMode, type ProjectRepository, type SyncMode, type WriteEntry, type WriteOptions } from "./types.js";
4
4
  export declare const IDS_DIR = ".tomrade-files";
5
5
  export declare const IDS_FILE = ".tomrade-files/ids.jsonl";
@@ -26,6 +26,8 @@ export interface GitStoreOptions {
26
26
  location: string | null;
27
27
  warn(message: string): void;
28
28
  onChange(paths?: string[]): void;
29
+ /** A sync with the remote moved on a step, or its transfer did; null once it ended. Paced, never a flood. */
30
+ onProgress?(progress: SyncProgress | null): void;
29
31
  watch?: boolean;
30
32
  /** Outside edits are saved this long after the last one. */
31
33
  settleMs?: number;
@@ -67,6 +69,11 @@ export declare class GitFileStore implements FileStore {
67
69
  private syncQueue;
68
70
  private lastSyncAt;
69
71
  private problem;
72
+ private recorder;
73
+ /** The last exchange with the remote, kept until the next one. */
74
+ private trace;
75
+ /** The trees the last push replaced and published, and how many syncs in a row found the remote back at the replaced one. */
76
+ private flip;
70
77
  private ensured;
71
78
  private closed;
72
79
  private chain;
@@ -191,6 +198,14 @@ export declare class GitFileStore implements FileStore {
191
198
  * them, so a local commit landing beside either is safe.
192
199
  */
193
200
  private doSync;
201
+ /** Only a remote out of reach is offline; every refusal goes to the log with what git said. */
202
+ private failed;
203
+ /**
204
+ * Publishing the same tree over the same tree again and again means another
205
+ * machine keeps putting back what this one replaced: neither will settle, and
206
+ * each round is a commit on a branch people share.
207
+ */
208
+ private undoing;
194
209
  /**
195
210
  * Merge both policy dimensions before looking at bytes. Sharing fails closed
196
211
  * on a concurrent edit to the same rule — bytes are at stake. Listing is only
@@ -1,4 +1,5 @@
1
- import { GitFolder, type Git } from "@tomradex/git";
1
+ import { GitFolder, SyncRecorder, type Git } from "@tomradex/git";
2
+ import { type ExchangeFailure } from "./sync-failure.js";
2
3
  import type { FileListPreference, FilesAgentPolicy, FilesSyncPolicy, PathPolicy, PathPreference, ProjectRepository } from "./types.js";
3
4
  /** A version made portable: the pair a ticket pins, and where the file was then. Its bytes travel beside the record. */
4
5
  export interface VersionRecord {
@@ -64,6 +65,12 @@ interface IndexEntry {
64
65
  mode: string;
65
66
  oid: string;
66
67
  }
68
+ /**
69
+ * One exchange at a time per transport folder, across stores: a store
70
+ * reopened while its predecessor still fetches would otherwise run git beside
71
+ * it in the same folder and fail on its locks.
72
+ */
73
+ export declare function exclusiveTransport<T>(dir: string, run: () => Promise<T>): Promise<T>;
67
74
  export declare class GitProjection {
68
75
  private git;
69
76
  private binary;
@@ -83,8 +90,16 @@ export declare class GitProjection {
83
90
  directory?: string;
84
91
  });
85
92
  private run;
86
- /** Bring the index to the remote's tip. False when the remote cannot be reached. */
87
- fetch(): Promise<boolean>;
93
+ /**
94
+ * What a git killed mid-exchange leaves behind — the app quit during a
95
+ * fetch, say — would fail every later one. Called inside exclusiveTransport,
96
+ * and one Tomrade owns a data folder, so no live git holds these.
97
+ */
98
+ private clearInterrupted;
99
+ /** Bring the index to the remote's tip; null once there, else the step git refused and why. */
100
+ fetch(recorder?: SyncRecorder): Promise<ExchangeFailure | null>;
101
+ /** The scope's blobs a filtered fetch left out, in one request rather than one per read. */
102
+ private fetchScopeBlobs;
88
103
  /** Every path in scope, relative to it, with what git has there. */
89
104
  listing(): Map<string, IndexEntry>;
90
105
  paths(): string[];
@@ -93,8 +108,14 @@ export declare class GitProjection {
93
108
  read(rel: string): Promise<Buffer | null>;
94
109
  /** Put bytes at a path, or remove it with null. Bytes the remote already has there cost nothing. */
95
110
  write(rel: string, bytes: Buffer | null): Promise<void>;
96
- /** Commit what changed on top of the fetched tip and push, never forced. */
97
- push(): Promise<boolean>;
111
+ /** The tree the fetched tip holds (null on an empty remote) and the one a push would publish. */
112
+ trees(): Promise<{
113
+ theirs: string | null;
114
+ ours: string;
115
+ }>;
116
+ /** Commit what changed on top of the fetched tip and push, never forced; null once it landed, else why not. */
117
+ push(recorder?: SyncRecorder): Promise<ExchangeFailure | null>;
118
+ private refused;
98
119
  }
99
120
  export {};
100
121
  //# sourceMappingURL=git-sync.d.ts.map
package/dist/index.d.ts CHANGED
@@ -1,11 +1,12 @@
1
1
  export { Files, FilesConfig, LOCAL_BACKEND, folderName } from "./service.js";
2
+ export type { SyncProgress, SyncStep, SyncStepRecord, SyncTrace, SyncTransfer } from "@tomradex/git";
2
3
  export { BINARY_LIMIT, GitFileStore, IDS_DIR, IDS_FILE, normalizeRel, parseLedger, type GitRemoteTarget, type GitStoreOptions, type Ledger } from "./git-store.js";
3
4
  export { createGitBackend, type GitBackendOptions } from "./git-backend.js";
4
5
  export { buildAgentIndex, estimateTokens, formatSize, shortDate, type AgentIndex, type AgentIndexInput } from "./agent-index.js";
5
6
  export { DEFAULT_AGENT_POLICY, DEFAULT_SYNC_POLICY, listingAt, policyAt, readStoredPolicy, validPolicy, type StoredPolicy } from "./git-sync.js";
6
7
  export { isTextMime, looksBinary, mimeOf } from "./mime.js";
7
8
  export { MIGRATIONS, OpsStore, RemoteStore, TABLES, type FileOpKind, type FileOpRow, type RemoteRow } from "./store.js";
8
- export { FileChangedError, FileMovedOnError, FilesUnavailableError, InvalidPathError, ProjectRepositoryError, UnknownBackendError, type AttachmentInput, type ConflictChoice, type ConnectionState, type FileChange, type FileConflict, type FileContent, type FileEntry, type FileStore, type FileVersion, type FilesBackend, type FilesBackendView, type FilesConnection, type FilesInfo, type FilesStatus, type FilesSyncState, type FilesSyncPolicy, type FileSyncPreference, type FilesAgentPolicy, type FileListPreference, type FileSearchInput, type FileSearchHit, type FileSearchResult, type ListMode, type PathPolicy, type PathPreference, type SyncMode, type OpenStoreOptions, type ProjectRepository, type StoreEnv, type SaveResult, type WriteEntry, type WriteOptions } from "./types.js";
9
+ export { FileChangedError, FileMovedOnError, FilesUnavailableError, InvalidPathError, ProjectRepositoryError, UnknownBackendError, type AttachmentInput, type ConflictChoice, type ConnectionState, type FileChange, type FileConflict, type FileContent, type FileEntry, type FileStore, type FileVersion, type FilesBackend, type FilesBackendView, type FilesConnection, type FilesInfo, type FilesStatus, type FilesSyncState, type FilesSyncFailure, type FilesSyncPolicy, type FileSyncPreference, type FilesAgentPolicy, type FileListPreference, type FileSearchInput, type FileSearchHit, type FileSearchResult, type ListMode, type PathPolicy, type PathPreference, type SyncMode, type OpenStoreOptions, type ProjectRepository, type StoreEnv, type SaveResult, type WriteEntry, type WriteOptions } from "./types.js";
9
10
  export type {} from "./channels.js";
10
11
  export { Files as default } from "./service.js";
11
12
  //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,14 @@
1
+ import type { FilesSyncFailure } from "./types.js";
2
+ /** The step of an exchange with the remote that git refused. */
3
+ export type ExchangeStep = "reach" | "fetch" | "push";
4
+ export interface ExchangeFailure {
5
+ step: ExchangeStep;
6
+ failure: FilesSyncFailure;
7
+ /** The line of git's output that says why, credentials removed; empty when git said nothing. */
8
+ said: string;
9
+ }
10
+ export declare function classifyFailure(step: ExchangeStep, stderr: string): FilesSyncFailure;
11
+ /** The helper's own line, else git's first fatal or the remote's own words, else its last line: hints never say why. */
12
+ export declare function failureLine(stderr: string): string;
13
+ export declare const exchangeFailure: (step: ExchangeStep, stderr: string) => ExchangeFailure;
14
+ //# sourceMappingURL=sync-failure.d.ts.map
package/dist/types.d.ts CHANGED
@@ -1,13 +1,25 @@
1
1
  import type { z } from "zod";
2
2
  import type { FileReference } from "@tomradex/domain";
3
3
  import type { ProviderConnection as FilesConnection } from "@tomradex/storage";
4
+ import type { SyncProgress, SyncTrace } from "@tomradex/git";
4
5
  /** Where a project's files stand against what they are shared through. `local` means nothing beyond this machine to be in step with. */
5
6
  export type FilesSyncState = "local" | "synced" | "ahead" | "behind" | "diverged" | "conflicted" | "syncing" | "offline" | "error" | "unavailable";
7
+ /**
8
+ * Why an exchange with the remote failed, each with its own remedy. Only
9
+ * `network` is offline: the others reach the remote, or never got to try.
10
+ */
11
+ export type FilesSyncFailure = "network" | "interrupted" | "locked" | "credentials" | "helper" | "moved" | "other";
6
12
  export interface FilesStatus {
7
13
  state: FilesSyncState;
8
14
  /** Non-secret: "github.com/acme/docs · main", or the folder. */
9
15
  location: string | null;
10
16
  detail?: string;
17
+ /** Set when git refused a step of the exchange; `detail` then holds what it said. */
18
+ failure?: FilesSyncFailure;
19
+ /** Where a running sync is; `files.progress` tells of it as it moves. */
20
+ progress?: SyncProgress;
21
+ /** What the last exchange with the remote did, for the person to read. */
22
+ trace?: SyncTrace;
11
23
  lastSyncAt: number | null;
12
24
  conflicts: number;
13
25
  ahead: number;
@@ -228,6 +240,8 @@ export interface OpenStoreOptions<C> {
228
240
  warn(message: string): void;
229
241
  /** The store's files changed underneath the app: a sync, an outside edit. `paths` when the store knows which. */
230
242
  onChange(paths?: string[]): void;
243
+ /** A sync with the remote moved on; null once it ended. */
244
+ onProgress?(progress: SyncProgress | null): void;
231
245
  /** What the service was configured with; a backend takes what applies to it. */
232
246
  env: StoreEnv;
233
247
  /** The project's own repository, asked on every sync; a backend sharing through git keeps out of its root and the store's folder. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tomradex/files",
3
- "version": "0.23.1",
3
+ "version": "0.25.0",
4
4
  "type": "module",
5
5
  "author": "Haoyuan Tang",
6
6
  "engines": {
@@ -27,21 +27,21 @@
27
27
  "dist"
28
28
  ],
29
29
  "dependencies": {
30
- "@tomradex/agent": "0.23.1",
31
- "@tomradex/boards": "0.23.1",
32
- "@tomradex/contracts": "0.23.1",
33
- "@tomradex/contributions": "0.23.1",
34
- "@tomradex/db": "0.23.1",
30
+ "@tomradex/agent": "0.25.0",
31
+ "@tomradex/boards": "0.25.0",
32
+ "@tomradex/contracts": "0.25.0",
33
+ "@tomradex/contributions": "0.25.0",
34
+ "@tomradex/db": "0.25.0",
35
35
  "@tomradex/domain": "0.2.30",
36
- "@tomradex/git": "0.23.1",
37
- "@tomradex/hub": "0.23.1",
38
- "@tomradex/ipc": "0.23.1",
39
- "@tomradex/items": "0.23.1",
40
- "@tomradex/oplog": "0.23.1",
41
- "@tomradex/settings": "0.23.1",
42
- "@tomradex/storage": "0.23.1",
43
- "@tomradex/tools": "0.23.1",
44
- "@tomradex/write": "0.23.1",
36
+ "@tomradex/git": "0.25.0",
37
+ "@tomradex/hub": "0.25.0",
38
+ "@tomradex/ipc": "0.25.0",
39
+ "@tomradex/items": "0.25.0",
40
+ "@tomradex/oplog": "0.25.0",
41
+ "@tomradex/settings": "0.25.0",
42
+ "@tomradex/storage": "0.25.0",
43
+ "@tomradex/tools": "0.25.0",
44
+ "@tomradex/write": "0.25.0",
45
45
  "cordis": "4.0.0-rc.8",
46
46
  "zod": "^4.4.3"
47
47
  }