brainfile 0.20.0 → 0.21.1

package/dist/utils/board-sync.d.ts

@@ -0,0 +1,126 @@
+export declare const REMOTE_CONFIG_KEY = "brainfile.remote";
+/** Set once this machine has looked for (and moved) a board 0.21.0 pushed as a branch. */
+export declare const LEGACY_CHECKED_CONFIG_KEY = "brainfile.legacyBranchChecked";
+export declare const AUTOSYNC_CONFIG_KEY = "brainfile.autosync";
+/** Remote name used when `--set-remote` is given a URL instead of a name. */
+export declare const URL_REMOTE_NAME = "board";
+export declare const MERGE_DRIVER_NAME = "brainfile";
+export declare const DEFAULT_MERGE_DRIVER_COMMAND = "brainfile merge-driver %O %A %B";
+export declare const BOARD_GITATTRIBUTES: string[];
+export type AutosyncMode = 'off' | 'push' | 'full';
+export interface SyncOptions {
+    pull?: boolean;
+    push?: boolean;
+}
+export interface SyncResult {
+    /** True when every requested step succeeded (nothing to do also counts). */
+    ok: boolean;
+    /** Set when sync did not run at all. */
+    skipped?: 'not-tracked' | 'no-remote';
+    remote?: string;
+    /** Where the board lives on the remote, e.g. `refs/brainfile/board`. */
+    remoteRef?: string;
+    /** Commits brought in from the remote. */
+    pulled: number;
+    /** Commits sent to the remote. */
+    pushed: number;
+    /** Files left with conflict markers for a human. */
+    conflicts: string[];
+    /** One-line, technical explanation when `ok` is false. */
+    warning?: string;
+    /** Why it failed, for plain-language messages (see `syncMessage`). */
+    failure?: 'offline' | 'rejected' | 'conflict' | 'error';
+    /** Set when a board 0.21.0 had pushed as a branch was moved to `remoteRef`. */
+    movedFromBranch?: string;
+}
+export interface SyncState {
+    at: string;
+    remote: string;
+    remoteRef: string;
+    ok: boolean;
+    warning?: string;
+}
+export declare function boardRemote(dotDir: string): string | null;
+/**
+ * Name of the board on the remote (`refs/brainfile/<name>`). Defaults keep
+ * the "one private boards repo, one board per project" pattern from
+ * colliding: `board` for a board inside a code repository, the parent
+ * folder's basename for a standalone board, `home` for the global board.
+ */
+export declare function boardRemoteName(dotDir: string): string;
+/** Full ref of the board on the remote, e.g. `refs/brainfile/board`. */
+export declare function boardRemoteRef(dotDir: string): string;
+export declare function boardAutosync(dotDir: string): AutosyncMode;
+export declare function setBoardAutosync(dotDir: string, mode: AutosyncMode): boolean;
+/** True when `target` names a place rather than an existing git remote. */
+export declare function looksLikeRemoteUrl(target: string): boolean;
+export interface RemoteSetting {
+    remote: string;
+    url: string | null;
+    remoteRef: string;
+}
+/**
+ * Point the board at a remote: an existing remote name, or a URL/path that is
+ * registered as the `board` remote. Throws an Error naming an unknown remote.
+ * `cwd` may be the board directory or, when no board exists yet, the code
+ * repository the board will be materialized into.
+ */
+export declare function setBoardRemote(cwd: string, target: string, boardName?: string): RemoteSetting;
+/**
+ * Register the field-level merge driver in the board's git config.
+ *
+ * Without an explicit `command` this only fills in a missing driver: a
+ * driver someone configured on purpose (an absolute path to the CLI, or a
+ * test's built bundle) is never overwritten by the next sync.
+ */
+export declare function registerMergeDriver(cwd: string, command?: string): boolean;
+/**
+ * Make sure `.gitattributes` on the board declares the merge strategies.
+ * Returns true when the file was created or extended (caller commits).
+ */
+export declare function ensureBoardAttributes(dotDir: string): boolean;
+export declare function readSyncState(dotDir: string): SyncState | null;
+/**
+ * Complete-vs-edit: one side archived a task (deleted `board/<id>.md`, wrote
+ * `logs/<id>.md`) while the other edited it. Completion wins; the edit is
+ * appended to the archived file as a log entry. Returns the paths resolved.
+ */
+export declare function resolveCompleteVersusEdit(dotDir: string): string[];
+/**
+ * fetch → fast-forward or merge → push. Runs entirely inside the board
+ * directory. Never throws; network failures come back as `warning`.
+ *
+ * The first sync with a remote also looks for a board that 0.21.0 pushed as
+ * a branch: it is merged in, published under refs/brainfile/, and the old
+ * branch is deleted from the remote once nothing on it can be lost.
+ */
+export declare function syncBoard(dotDir: string, options?: SyncOptions): SyncResult;
+/** Seconds since the last recorded sync attempt, or null when there was none. */
+export declare function secondsSinceSync(dotDir: string, now?: number): number | null;
+/**
+ * Short status for a header: `synced 12s ago`, `local only` for a tracked
+ * board nobody else has, `not synced · saved locally` after a failure. Null
+ * for a plain board.
+ */
+export declare function syncStatusLabel(dotDir: string, now?: number): string | null;
+/**
+ * Commits on this machine the remote has not seen yet, judged against the
+ * last-known remote position (no network). Null when the board is not shared.
+ */
+export declare function pendingChanges(dotDir: string): number;
+/**
+ * A page where people can see the board on the web, for hosts that show refs
+ * outside branches: GitHub's commit history accepts a full ref name. Null for
+ * other hosts.
+ */
+export declare function boardWebUrl(remoteUrl: string | null, remoteRef: string): string | null;
+/**
+ * The one sentence a person needs after a sync: what moved, or why nothing
+ * did and that nothing was lost. `detail` is the technical cause, if any.
+ */
+export declare function syncMessage(result: SyncResult): {
+    text: string;
+    tone: 'ok' | 'warn';
+    detail?: string;
+};
+//# sourceMappingURL=board-sync.d.ts.map

package/dist/utils/board-sync.d.ts.map

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