@max-null/dsh-memory 0.21.0 → 0.22.0

package/dist/sync-import.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 同步导入层：把 `records/` 里的记录**规划**成一组待写入的操作。
+ *
+ * **这一层只出计划，不写任何东西。** 真正落库由调用方走引擎已有的写入路径完成，
+ * 理由：直接改 `memory.json` 会与内存缓存打架（引擎的写路径是「读—改—写全量覆盖」，
+ * 绕过它等于让两边各持一份真相）。分层之后，这一层是纯函数，可以在不碰数据的前提下
+ * 穷举冲突场景。
+ *
+ * 冲突策略见设计 §3.3：**同一条被两边改时不自动裁决**，两个版本都交出去让调用方写进
+ * `conflicts/`。记忆是长期资产，被静默覆盖的那份就没了。
+ *
+ * @module dsh-memory/sync-import
+ */
+import type { z } from 'zod';
+import type { blockSchema } from './schema.ts';
+/** 与存储层同构的一条记录。 */
+export type ImportedBlock = z.infer<typeof blockSchema>;
+/** 一条来自 `records/` 的记录及其归属。 */
+export interface IncomingRecord {
+    /** 记录 id（文件名去 `.json`）。 */
+    readonly id: string;
+    /** `global` 或 `project`。 */
+    readonly scope: 'global' | 'project';
+    /** `project` 作用域下的项目名；`global` 时缺省。 */
+    readonly projectName?: string;
+    /** 解析后的记录体。 */
+    readonly block: ImportedBlock;
+}
+/** 本地某一层现有的记录。 */
+export interface LocalLayer {
+    /** 该层现有的记录：id → block。 */
+    readonly blocks: Readonly<Record<string, ImportedBlock>>;
+}
+/** {@link planImport} 的入参。 */
+export interface ImportPlanOptions {
+    readonly incoming: readonly IncomingRecord[];
+    /** 本地 global 层。 */
+    readonly localGlobal: LocalLayer;
+    /** 本地的项目层：项目名（已小写）→ 该项目的记录。 */
+    readonly localProjects: Readonly<Record<string, LocalLayer>>;
+}
+/** 一条待写入的操作。 */
+export interface ImportUpsert {
+    readonly id: string;
+    readonly scope: 'global' | 'project';
+    readonly projectName?: string;
+    readonly block: ImportedBlock;
+}
+/** 一条需要人工裁决的冲突。 */
+export interface ImportConflict {
+    readonly id: string;
+    readonly scope: 'global' | 'project';
+    readonly projectName?: string;
+    /** 本地版本。 */
+    readonly mine: ImportedBlock;
+    /** 远端版本。 */
+    readonly theirs: ImportedBlock;
+    /** 判据：哪一边的 `updatedAt` 更新（仅作参考，决定写不写 `upserts`）。 */
+    readonly newer: 'mine' | 'theirs';
+}
+/** 一次导入规划的结果。 */
+export interface ImportPlan {
+    /** 需要新增或覆盖的条目。 */
+    readonly upserts: readonly ImportUpsert[];
+    /** 两边都改过、需要人裁决的条目。 */
+    readonly conflicts: readonly ImportConflict[];
+    /** 本地没有对应项目、无法落地的条目（留在远端等它出现）。 */
+    readonly orphaned: readonly string[];
+    /** 本地已一致、无需动作的条数。 */
+    readonly unchanged: number;
+}
+/**
+ * 规划一次导入。**不读写磁盘、不碰引擎状态。**
+ *
+ * 三种归属分别处理：
+ * - `global`：永远有落点。
+ * - `project` 且本地有同名项目：落到该项目。
+ * - `project` 但本地没有该项目 → 进 `orphaned`，**不丢**（留在远端等它出现）。
+ *
+ * @param options - 远端记录、本地各层、项目映射。
+ * @returns 计划：要写的、要裁决的、落不了的、不需要动的。
+ */
+export declare function planImport(options: ImportPlanOptions): ImportPlan;

package/dist/sync-import.js

@@ -0,0 +1,82 @@
+/**
+ * 同步导入层：把 `records/` 里的记录**规划**成一组待写入的操作。
+ *
+ * **这一层只出计划，不写任何东西。** 真正落库由调用方走引擎已有的写入路径完成，
+ * 理由：直接改 `memory.json` 会与内存缓存打架（引擎的写路径是「读—改—写全量覆盖」，
+ * 绕过它等于让两边各持一份真相）。分层之后，这一层是纯函数，可以在不碰数据的前提下
+ * 穷举冲突场景。
+ *
+ * 冲突策略见设计 §3.3：**同一条被两边改时不自动裁决**，两个版本都交出去让调用方写进
+ * `conflicts/`。记忆是长期资产，被静默覆盖的那份就没了。
+ *
+ * @module dsh-memory/sync-import
+ */
+/** 把一条记录投影成可比较的形状：只比内容，不比本地瞬态字段。 */
+function comparable(block) {
+    return JSON.stringify([
+        block.content,
+        block.keywords,
+        block.namespace,
+        block.status,
+        block.injected ?? null,
+        block.topic ?? null,
+        block.kind ?? null,
+        block.stale ?? null,
+        block.staleReason ?? null,
+        block.anchor ?? null,
+    ]);
+}
+/** 本地层里找一条。 */
+function findLocal(layer, id) {
+    return layer?.blocks[id];
+}
+/**
+ * 规划一次导入。**不读写磁盘、不碰引擎状态。**
+ *
+ * 三种归属分别处理：
+ * - `global`：永远有落点。
+ * - `project` 且本地有同名项目：落到该项目。
+ * - `project` 但本地没有该项目 → 进 `orphaned`，**不丢**（留在远端等它出现）。
+ *
+ * @param options - 远端记录、本地各层、项目映射。
+ * @returns 计划：要写的、要裁决的、落不了的、不需要动的。
+ */
+export function planImport(options) {
+    const upserts = [];
+    const conflicts = [];
+    const orphaned = [];
+    let unchanged = 0;
+    for (const record of options.incoming) {
+        const { id, scope, projectName, block } = record;
+        let localLayer;
+        if (scope === 'global') {
+            localLayer = options.localGlobal;
+        }
+        else {
+            const key = projectName?.toLowerCase() ?? '';
+            localLayer = key === '' ? undefined : options.localProjects[key];
+            if (localLayer === undefined) {
+                // 本机没有这个项目：记下来但不导入，也不报错。
+                orphaned.push(id);
+                continue;
+            }
+        }
+        const local = findLocal(localLayer, id);
+        if (local === undefined) {
+            upserts.push({ id, scope, ...projectName === undefined ? {} : { projectName }, block });
+            continue;
+        }
+        if (comparable(local) === comparable(block)) {
+            unchanged += 1;
+            continue;
+        }
+        // 两边内容不同：不自动裁决，两边都交出去。
+        const newer = (block.updatedAt ?? 0) > (local.updatedAt ?? 0) ? 'theirs' : 'mine';
+        conflicts.push({ id, scope, ...projectName === undefined ? {} : { projectName }, mine: local, theirs: block, newer });
+        // 远端更新的那份仍然写进去（否则用户看到的永远是旧内容），但冲突记录同时留下。
+        if (newer === 'theirs') {
+            upserts.push({ id, scope, ...projectName === undefined ? {} : { projectName }, block });
+        }
+    }
+    return { upserts, conflicts, orphaned, unchanged };
+}

package/dist/sync-remote.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 同步镜像的远端层：`push` / `pull` / 状态查询。
+ *
+ * **必须走 HTTP**：`isomorphic-git` 的 `push` 在没有 `http` 参数时直接抛
+ * `The function requires a "http" parameter but none was provided`（2026-11-11 实测，
+ * 想用本地 bare 仓库做离线测试也走不通）。所以本层天然依赖网络，与上一层的
+ * `sync-git.ts`（纯本地、可离线全测）分开。
+ *
+ * **认证用 PAT（https）而不是 SSH**：SSH key 在移动端的管理成本远高于 token，
+ * 而 dsh-go 那类环境正是目标场景之一。
+ *
+ * **token 不进 profile 配置**：由调用方从既有 credentials 机制取出后传入。本模块只
+ * 负责把它放进 http 请求，不负责存。
+ *
+ * @module dsh-memory/sync-remote
+ */
+/** 远端操作共用的参数。 */
+export interface RemoteOptions {
+    /** 镜像仓库目录。 */
+    readonly dir: string;
+    /** 远端地址（https）。 */
+    readonly url: string;
+    /** 分支名；缺省 `main`。 */
+    readonly branch?: string;
+    /** GitHub PAT；缺省时只尝试匿名（私有仓库会失败）。 */
+    readonly token?: string;
+}
+/** 一次远端操作的结果。 */
+export interface RemoteRun {
+    readonly ok: boolean;
+    /** 失败原因；成功时缺省。 */
+    readonly error?: string;
+    /**
+     * 失败分类——排查时最要紧的一件事：「认证错」和「连不上」的正确应对完全不同，
+     * 而它们的原始报错常常长得差不多。
+     */
+    readonly kind?: 'auth' | 'network' | 'unknown';
+}
+/**
+ * 确保镜像目录是一个**与远端有共同历史**的仓库。
+ *
+ * 首次同步时如果只 `git init`，本地与远端是两条无关的历史线——push 会被拒
+ * （`Push rejected because it was not a simple fast-forward`）。这是 2026-11-11
+ * 第一次用真实仓库跑时撞出来的：单元测试里没有真远端，所以永远发现不了。
+ *
+ * 因此首次必须 clone，而不是 init + push。
+ *
+ * @param options - 目录、远端地址、分支与 token。
+ * @returns 是否执行了 clone；失败时带分类。
+ */
+export declare function ensureMirrorRepo(options: RemoteOptions): Promise<MirrorRepoRun>;
+/** {@link ensureMirrorRepo} 的结果。 */
+export interface MirrorRepoRun {
+    readonly cloned: boolean;
+    readonly error?: string;
+    readonly kind?: 'auth' | 'network' | 'unknown';
+}
+/**
+ * 把本地提交推到远端。
+ *
+ * @param options - 目录、远端地址、分支与 token。
+ * @returns 成功与否；失败时带分类。
+ */
+export declare function pushMirror(options: RemoteOptions): Promise<RemoteRun>;
+/**
+ * 从远端拉取并快进本地。
+ *
+ * `fastForwardOnly: true`：合并策略不该由这一层决定。本地有分叉时宁可失败让人看见，
+ * 也不要让 isomorphic-git 悄悄造出一个 merge commit。
+ *
+ * @param options - 目录、远端地址、分支与 token。
+ * @returns 成功与否；失败时带分类。
+ */
+export declare function pullMirror(options: RemoteOptions): Promise<RemoteRun>;
+/**
+ * 确保 `origin` 指向给定地址。地址变化时重设（用户换了仓库）。
+ *
+ * @param dir - 镜像仓库目录。
+ * @param url - 期望的远端地址。
+ */
+export declare function ensureRemote(dir: string, url: string): Promise<void>;

package/dist/sync-remote.js

@@ -0,0 +1,157 @@
+/**
+ * 同步镜像的远端层：`push` / `pull` / 状态查询。
+ *
+ * **必须走 HTTP**：`isomorphic-git` 的 `push` 在没有 `http` 参数时直接抛
+ * `The function requires a "http" parameter but none was provided`（2026-11-11 实测，
+ * 想用本地 bare 仓库做离线测试也走不通）。所以本层天然依赖网络，与上一层的
+ * `sync-git.ts`（纯本地、可离线全测）分开。
+ *
+ * **认证用 PAT（https）而不是 SSH**：SSH key 在移动端的管理成本远高于 token，
+ * 而 dsh-go 那类环境正是目标场景之一。
+ *
+ * **token 不进 profile 配置**：由调用方从既有 credentials 机制取出后传入。本模块只
+ * 负责把它放进 http 请求，不负责存。
+ *
+ * @module dsh-memory/sync-remote
+ */
+import * as nodeFs from 'node:fs';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/** 默认分支。 */
+const DEFAULT_BRANCH = 'main';
+/** 动态载入 isomorphic-git 与它的 Node http 实现。 */
+async function loadGit() {
+    const [git, http] = await Promise.all([
+        import('isomorphic-git'),
+        import('isomorphic-git/http/node'),
+    ]);
+    return { git: git.default, http: http.default };
+}
+/** 把原始错误归到三类之一，便于调用方决定是改凭据还是重试。 */
+function classify(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    const text = raw.toLowerCase();
+    // 401/403、authentication failed、invalid credentials、权限不足
+    if (/401|403|auth|credential|permission|denied|token/u.test(text)) {
+        return { ok: false, error: raw, kind: 'auth' };
+    }
+    if (/enotfound|econnrefused|etimedout|timeout|network|dns|socket|offline/u.test(text)) {
+        return { ok: false, error: raw, kind: 'network' };
+    }
+    return { ok: false, error: raw, kind: 'unknown' };
+}
+/** 组装 isomorphic-git 的 onAuth 回调。 */
+function authFor(token) {
+    return () => (token === undefined || token === ''
+        ? { username: 'git' }
+        : { username: 'x-access-token', password: token });
+}
+/** 镜像目录是不是一个已初始化的仓库。 */
+function isRepo(dir) {
+    return existsSync(join(dir, '.git'));
+}
+/**
+ * 确保镜像目录是一个**与远端有共同历史**的仓库。
+ *
+ * 首次同步时如果只 `git init`，本地与远端是两条无关的历史线——push 会被拒
+ * （`Push rejected because it was not a simple fast-forward`）。这是 2026-11-11
+ * 第一次用真实仓库跑时撞出来的：单元测试里没有真远端，所以永远发现不了。
+ *
+ * 因此首次必须 clone，而不是 init + push。
+ *
+ * @param options - 目录、远端地址、分支与 token。
+ * @returns 是否执行了 clone；失败时带分类。
+ */
+export async function ensureMirrorRepo(options) {
+    if (isRepo(options.dir))
+        return { cloned: false };
+    const { git, http } = await loadGit();
+    try {
+        await git.clone({
+            fs: nodeFs,
+            http,
+            dir: options.dir,
+            url: options.url,
+            ref: options.branch ?? DEFAULT_BRANCH,
+            depth: 1,
+            onAuth: authFor(options.token),
+        });
+        return { cloned: true };
+    }
+    catch (error) {
+        return { cloned: false, ...classify(error) };
+    }
+}
+/**
+ * 把本地提交推到远端。
+ *
+ * @param options - 目录、远端地址、分支与 token。
+ * @returns 成功与否；失败时带分类。
+ */
+export async function pushMirror(options) {
+    if (!isRepo(options.dir)) {
+        return { ok: false, error: `not a git repository: ${options.dir}`, kind: 'unknown' };
+    }
+    const { git, http } = await loadGit();
+    try {
+        await git.push({
+            fs: nodeFs,
+            http,
+            dir: options.dir,
+            remote: 'origin',
+            ref: options.branch ?? DEFAULT_BRANCH,
+            onAuth: authFor(options.token),
+        });
+        return { ok: true };
+    }
+    catch (error) {
+        return classify(error);
+    }
+}
+/**
+ * 从远端拉取并快进本地。
+ *
+ * `fastForwardOnly: true`：合并策略不该由这一层决定。本地有分叉时宁可失败让人看见，
+ * 也不要让 isomorphic-git 悄悄造出一个 merge commit。
+ *
+ * @param options - 目录、远端地址、分支与 token。
+ * @returns 成功与否；失败时带分类。
+ */
+export async function pullMirror(options) {
+    if (!isRepo(options.dir)) {
+        return { ok: false, error: `not a git repository: ${options.dir}`, kind: 'unknown' };
+    }
+    const { git, http } = await loadGit();
+    try {
+        await git.pull({
+            fs: nodeFs,
+            http,
+            dir: options.dir,
+            remote: 'origin',
+            ref: options.branch ?? DEFAULT_BRANCH,
+            fastForwardOnly: true,
+            author: { name: 'dsh-memory', email: 'dsh-memory@localhost' },
+            onAuth: authFor(options.token),
+        });
+        return { ok: true };
+    }
+    catch (error) {
+        return classify(error);
+    }
+}
+/**
+ * 确保 `origin` 指向给定地址。地址变化时重设（用户换了仓库）。
+ *
+ * @param dir - 镜像仓库目录。
+ * @param url - 期望的远端地址。
+ */
+export async function ensureRemote(dir, url) {
+    if (!isRepo(dir))
+        return;
+    const { git } = await loadGit();
+    const remotes = await git.listRemotes({ fs: nodeFs, dir });
+    const origin = remotes.find(remote => remote.remote === 'origin');
+    if (origin?.url === url)
+        return;
+    await git.addRemote({ fs: nodeFs, dir, remote: 'origin', url, force: true });
+}

package/dist/sync-service.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 同步编排：把导出 / 写盘 / 墓碑 / git / 远端五层串成一次操作。
+ *
+ * 这一层没有自己的算法，只有**顺序**。顺序在这里是有意义的：
+ *
+ * push 时先写镜像与墓碑、再提交、最后推送——反过来的话，一次失败会留下
+ * 「远端已有、本地没有」的状态，下次 push 会把差异当成删除。
+ *
+ * pull 时先拉、再规划导入、最后逐条落地——导入是唯一会改本地记忆库的一步，
+ * 放在最后意味着前面任何一步失败都不会动数据。
+ *
+ * @module dsh-memory/sync-service
+ */
+import type { MemoryEngine } from './engine.ts';
+import type { SyncRecordFile } from './sync-export.ts';
+import type { ImportConflict } from './sync-import.ts';
+/** 同步配置。 */
+export interface SyncConfig {
+    /** 镜像仓库目录。 */
+    readonly mirrorDir: string;
+    /** 远端地址（https）；缺省时只做本地提交。 */
+    readonly remote?: string;
+    /** 分支名；缺省 `main`。 */
+    readonly branch?: string;
+    /** 环境短名，用于冲突留证与提交信息；缺省「本机」。 */
+    readonly envName?: string;
+    /**
+     * HTTPS token。**不从配置里读**——由调用方从环境变量或凭据机制取出后传入，
+     * 避免它落进 profile 配置或提交历史。
+     */
+    readonly token?: string;
+}
+/** 一次 push 的结果。 */
+export interface SyncPushRun {
+    readonly files: number;
+    readonly written: number;
+    readonly unchanged: number;
+    readonly removed: number;
+    readonly tombstones: number;
+    readonly committed: boolean;
+    readonly sha?: string;
+    readonly pushed: boolean;
+    readonly error?: string;
+    readonly errorKind?: 'auth' | 'network' | 'unknown';
+}
+/** 一次 pull 的结果。 */
+export interface SyncPullRun {
+    readonly pulled: boolean;
+    readonly imported: number;
+    readonly conflicts: number;
+    readonly orphaned: number;
+    readonly error?: string;
+    readonly errorKind?: 'auth' | 'network' | 'unknown';
+}
+/** 同步状态快照（给 `memory_sync status`）。 */
+export interface SyncStatus {
+    readonly mirrorDir: string;
+    readonly initialized: boolean;
+    readonly remote?: string;
+    readonly lastCommit?: {
+        sha: string;
+        message: string;
+        at: number;
+    };
+    readonly commits: number;
+    readonly conflicts: number;
+    readonly tombstones: number;
+}
+/**
+ * 收集当前记忆库应有的镜像文件。
+ *
+ * 空项目不产生目录——`records/project/<name>/` 里一个文件都没有时，那个目录本身
+ * 不该出现在仓库里（否则每加一个空项目就多一个空目录）。
+ *
+ * @param memory - 引擎实例。
+ * @returns 待写入的记录文件列表。
+ */
+export declare function collectMirror(memory: MemoryEngine): Promise<readonly SyncRecordFile[]>;
+/**
+ * 推一次：收集 → 写镜像 → 写墓碑 → 提交 → 推送。
+ *
+ * @param memory - 引擎实例。
+ * @param config - 同步配置。
+ * @param now - 时间注入点（测试用）。
+ * @returns 各阶段统计；远端失败时保留本地提交已完成的事实。
+ */
+export declare function syncPush(memory: MemoryEngine, config: SyncConfig, now?: number): Promise<SyncPushRun>;
+/**
+ * 拉一次：拉取 → 规划导入 → 逐条落地。
+ *
+ * 冲突不自动裁决：两边版本都写进 `conflicts/`，本地版本保留（§3.3）。
+ *
+ * @param memory - 引擎实例。
+ * @param config - 同步配置。
+ * @param now - 时间注入点。
+ * @returns 导入统计。
+ */
+export declare function syncPull(memory: MemoryEngine, config: SyncConfig, now?: number): Promise<SyncPullRun>;
+/**
+ * 查同步状态。
+ *
+ * @param config - 同步配置。
+ * @returns 镜像目录、最近提交、冲突与墓碑数量。
+ */
+export declare function syncStatus(config: SyncConfig): Promise<SyncStatus>;
+/** 便于测试：导出一份当前冲突的快照。 */
+export declare function conflictFiles(config: SyncConfig): string[];
+export type { ImportConflict };