@treeseed/dsh-chapters 0.1.0

package/lib/sync.d.ts

@@ -0,0 +1,183 @@
+import { type ProviderKind, type SyncProvider } from './provider.ts';
+import { type VocabOpts } from './vocabulary.ts';
+/** A linked knowledge project (record §2.1, §8): one record per linked
+ * workspace cwd; deepest-cwd match resolves the active project. */
+export interface ProjectRecord {
+    projectKey: string;
+    slug: string;
+    remote: string;
+    harnessId: string;
+    linkedAt: string;
+    /** Workspace cwd this record was linked from (deepest-prefix match, record §8). */
+    cwd: string;
+    /** Transport kind (§15 amendment); absent = 'git' (pre-provider records). */
+    kind?: ProviderKind;
+    /** TreeDX: the server-assigned repository id (resolved at link time). */
+    repoId?: string | undefined;
+}
+export interface SyncResult {
+    ok: boolean;
+    /** What actually happened, for the status command and tests. */
+    steps: string[];
+    detail: string;
+    /** 'synced' only when the remote accepted the push; 'local-only' when the
+     * mirror is current but the remote did not take it (record §5.3). */
+    mode: 'synced' | 'local-only';
+}
+/**
+ * Per-project credentials — stored under the DSH HOME, never the workspace
+ * (user directive 2026-09-18: the project tree is the agent's reading room;
+ * the plugin is the only accessor). 0600 file per projectKey. Note honestly:
+ * same-uid files are a hygiene boundary, not a cryptographic one — the real
+ * guarantee is that the plugin never echoes the token anywhere an agent sees.
+ */
+export declare const tokenPath: (projectKey: string) => string;
+export declare function readToken(cwd: string, storeRoot: string, projectKey: string): string | undefined;
+export declare function writeToken(projectKey: string, token: string): void;
+export interface SyncOpts {
+    /** Workspace root — the store and the mirror both live under it. */
+    cwd: string;
+    /** Store root relative to cwd (`.dsh-chapters`). */
+    storeRoot: string;
+    /** Mirror directory relative to cwd (`.dsh-knowledge`). */
+    cloneDir: string;
+    project: ProjectRecord;
+    /** Per-harness token for this project (record §2.1); undefined for file remotes. */
+    token?: string;
+    /** Collection files to (re)publish: one JSONL file per session's signatures. */
+    collections?: {
+        sessionId: string;
+        lines: string[];
+    }[];
+    /** P2 §6.3 vocabulary pass over the mirror's chapters (undefined = off). */
+    vocab?: VocabPassOpts;
+    /** Force a run even when the lock is held (tests). Default false. */
+    force?: boolean;
+    /** Transport provider (tests inject a fake; default resolves from the
+     * project record's kind via src/provider.ts — 'git' when absent). */
+    provider?: SyncProvider;
+}
+/**
+ * Deepest-cwd match (record §8): the active knowledge project for a
+ * workspace path. Shared by the notice line, the scheduler, and the commands.
+ */
+export declare function projectForCwd(records: Iterable<[string, ProjectRecord]>, cwd: string): ProjectRecord | undefined;
+/** The mirror directory, relative to the workspace (record §3.1). */
+export declare const DEFAULT_CLONE_DIR = ".dsh-knowledge";
+/**
+ * File lock around store transactions and clone ops (§5.2): the host-plane
+ * plugin and the realm engine may be different module instances in the same
+ * process, so an in-process mutex is not safe — a file is the honest lock.
+ * Stale locks (>10 min) are stolen; live ones make runSync skip, not block.
+ */
+export declare function syncLockPath(storeDir: string): string;
+/**
+ * Map workspace-store files to repo paths (record §2.2):
+ *   <storeRoot>/<rootSession>/chapters/x.md  → chapters/<projectKey>/<rootSession>/x.md
+ *   <storeRoot>/<rootSession>/artifacts/ab/ab….txt → artifacts/<projectKey>/ab/ab….txt
+ * Artifacts are content-addressed and shared across sessions, so their
+ * per-session prefix is dropped; chapters keep it.
+ */
+export declare function planStoreToRepo(storeDir: string, projectKey: string): {
+    abs: string;
+    rel: string;
+}[];
+export declare const statusFilePath: (cwd: string, storeRoot: string) => string;
+/**
+ * Build the Layer-2 index inside the clone (record §10.2): entries from every
+ * chapter/rule file (frontmatter), curation facts from every harness's
+ * curation.jsonl, the manifest from the clone's index/manifest.json. Returns
+ * true when shards or the manifest changed (the commit step then ships them).
+ * Deterministic: the index is a pure function of the clone's corpus, so any
+ * machine can rebuild it identically (the recovery path, record §10.2).
+ */
+export declare function buildIndexInClone(cloneDir: string): boolean;
+export interface VocabPassOpts extends VocabOpts {
+    /** write applied aliases? false (shadow) = report only — the default */
+    apply: boolean;
+}
+/**
+ * One sync pass (record §5): lock → ensure clone (offline init fallback) →
+ * publish → commit → pull → push. Failure semantics §5.3: EVERY remote-path
+ * failure (clone, pull, push) degrades to local-only mode — the mirror stays
+ * current for search and the status file says so with detail; only a local
+ * commit failure or lock loss returns without a current mirror. A diverged
+ * pull rebuilds the mirror from the remote (safe: the mirror is transport,
+ * the store is truth, §3.1). ok=true means the remote accepted the push.
+ */
+export declare function runSync(opts: SyncOpts): Promise<SyncResult>;
+/**
+ * Pull-only pass for the pre-fork refresh point (record §5.1): ensure the
+ * mirror exists (clone, offline-init fallback) and ff-pull it. Never throws,
+ * never pushes, never commits — a read-side refresh.
+ */
+export declare function runPull(opts: Omit<SyncOpts, 'force'>): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+/**
+ * A workspace-scoped collections reader for the scheduler (§5): only session
+ * trees whose store directory lives in THIS workspace publish. Shared by the
+ * host plugin and the realm engine (the two schedulers are the same code over
+ * different module copies — the file lock keeps them honest).
+ */
+export declare function makeCollectionsReader(sessions: () => IterableIterator<[string, import('./registry.ts').SessionState]>, storeRoot: string): (cwd: string) => {
+    sessionId: string;
+    lines: string[];
+}[];
+/**
+ * The debounced scheduler (§5.2: "consecutive archive events within the
+ * configured window coalesce into one push"). Pure wiring — the plane that
+ * owns it (host plugin or realm engine) injects how to find the project, the
+ * token, and the collection files. Never throws; a failed pass lands in the
+ * status file like any other.
+ */
+export interface SyncSchedulerDeps {
+    storeRoot: string;
+    cloneDir?: string;
+    debounceMs: number;
+    resolveProject(cwd: string): ProjectRecord | undefined;
+    tokenFor(cwd: string, projectKey: string): string | undefined;
+    /** Collection JSONL lines per session, read from the registry (may be empty). */
+    collectionsFor(cwd: string): {
+        sessionId: string;
+        lines: string[];
+    }[];
+    /** P2 §6.3 vocabulary pass options for every scheduled pass (undefined = off). */
+    vocab?: VocabPassOpts;
+    /** Injectable timer (tests). Defaults to setTimeout/clearTimeout. */
+    setTimer?: (fn: () => void, ms: number) => {
+        cancel(): void;
+    };
+    provider?: SyncProvider;
+    /** P2: fired after a REAL sync pass completes (success or degraded) — the
+     * enrichment queue's natural idle point. Not fired for 'no project
+     * linked' early-outs (nothing was published, nothing to enrich). */
+    onSyncDone?: (cwd: string, ok: boolean) => void;
+}
+export interface SyncScheduler {
+    /** Debounced push after an archive event (compaction/fork). */
+    schedule(cwd: string, why: string): void;
+    /** Immediate pass (a link, an explicit sync). An explicit project wins
+     * over the cwd lookup — a re-link must sync the NEW record, not whichever
+     * record the cwd tie-break happens to pick. */
+    run(cwd: string, why: string, project?: ProjectRecord): Promise<SyncResult>;
+    /** Pre-fork refresh (§5.1): pull-only, bounded, never blocks long. */
+    pullFor(cwd: string): Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+    hasPending(cwd: string): boolean;
+    /** Await any in-flight/scheduled pass (tests + shutdown). */
+    drain(): Promise<void>;
+}
+export declare function createSyncScheduler(deps: SyncSchedulerDeps): SyncScheduler;
+/** Read the last sync status (for /chapters-status). Null when never run. */
+export declare function readSyncStatus(cwd: string, storeRoot: string): {
+    at: string;
+    projectKey: string;
+    lastOk: boolean;
+    mode?: string;
+    detail: string;
+    steps: string[];
+} | null;