@dimina-kit/fs-core 0.2.0-dev.20260710085051

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EchoTechFE and dimina-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @dimina-kit/fs-core
+
+浏览器端 OPFS WAL 文件系统内核：单写者权威（Web Locks 选主）、WAL-first 写序、checkpoint/restore 回滚、agent 写权 turn 门控，零运行时依赖。
+
+## 安装
+
+```bash
+npm i @dimina-kit/fs-core
+```
+
+## 入口
+
+| 子路径 | 用途 |
+| --- | --- |
+| `@dimina-kit/fs-core/client` | `ProjectFsClient.connect({ projectId })`：读写/快照/grep/glob、`mode`/`onModeChange`（多标签页单写者可见性）、turn API |
+| `@dimina-kit/fs-core/agent-tools` | fs_read/fs_write/fs_restore 等 agent 工具面（fs-core 侧 turn 执法） |
+| `@dimina-kit/fs-core/disk-mirror` | File System Access 目录镜像（防抖增量写盘，`pick(handle)` 可注入已授权句柄） |
+| `@dimina-kit/fs-core/sync` | 磁盘↔账本同步引擎（TruthPort 适配外部真相源） |
+| `@dimina-kit/fs-core/zip` | 快照打包为 ZIP |
+
+## 使用
+
+```js
+import { ProjectFsClient } from '@dimina-kit/fs-core/client'
+
+// 宿主需把 dist/fs-core.worker.js 与 dist/fs-query.worker.js 部署到可访问 URL
+// （默认约定 /ide/fs/ 下），client 以 module worker 加载它们。
+const fs = await ProjectFsClient.connect({
+  projectId: 'my-project',
+  coreUrl: '/ide/fs/fs-core.worker.js',
+  queryUrl: '/ide/fs/fs-query.worker.js',
+})
+await fs.write('app.json', '{}')
+const { content } = await fs.read('app.json')
+```
+
+## Worker 产物约束
+
+`dist/fs-core.worker.js` 与 `dist/fs-query.worker.js` 是单文件自包含 ESM（无 import 语句、零依赖），宿主按字面文件名从 `dist/` 拷贝/托管即可；以 module worker（`{ type: 'module' }`）加载。
+
+需要 OPFS（`navigator.storage.getDirectory`）与 `createSyncAccessHandle`（worker 内），即 Chromium ≥ 102 一类环境；不依赖 COI。
+
+## License
+
+MIT

package/dist/agent-tools.js

@@ -0,0 +1,52 @@
+export function createAgentTools(fs) {
+    let turnSeq = 0;
+    let activeTurn = null;
+    /** 铸造一轮写能力：fs-core 侧自动打 checkpoint 锚（返回 {cpId, expiresAt}）。 */
+    async function beginTurn(opts = {}) {
+        const turnId = 't-' + Date.now().toString(36) + '-' + ++turnSeq;
+        const r = await fs.turnBegin(turnId, opts);
+        activeTurn = turnId;
+        return { turnId, ...r };
+    }
+    /** 结束（撤销）当前 turn；之后任何 agent 写都会被 fs-core 拒绝（turn-closed）。 */
+    async function endTurn() {
+        if (!activeTurn)
+            return { closed: false };
+        const turnId = activeTurn;
+        activeTurn = null;
+        return fs.turnEnd(turnId);
+    }
+    const agentOpts = () => ({ actor: 'agent', turnId: activeTurn });
+    // E is inferred fresh per call from whatever concrete `execute` is passed
+    // (e.g. `({ path }: { path: string }) => …`) rather than checked against one
+    // fixed function type, so each tool below keeps its own narrow parameter
+    // shape; assigning it into the returned object's `execute` member is safe
+    // because AgentTool.execute is a method (bivariant), not an arrow-typed
+    // property.
+    function T(name, description, inputSchema, execute, extra) {
+        return { name, description, inputSchema, execute, ...extra };
+    }
+    const tools = [
+        // 读/查询（路由 fs-query，不占写路径）
+        T('fs_read', '读文件，返回完整内容与版本 rev（绝不截断）', { path: 'string' }, ({ path }) => fs.read(path)),
+        T('fs_ls', '列出项目全部文件路径', {}, () => fs.ls()),
+        T('fs_glob', '按 glob 模式匹配文件路径', { pattern: 'string' }, ({ pattern }) => fs.glob(pattern)),
+        T('fs_grep', '按正则搜索文件内容，返回 {path, lineNo, line} 命中行', { pattern: 'string', glob: 'string?', limit: 'number?' }, ({ pattern, ...o }) => fs.grep(pattern, o)),
+        // 写（fs-core 执法：必须在有效 turn 内）
+        T('fs_write', '写整文件；可带 ifMatch(rev) 做 CAS 前置校验', { path: 'string', content: 'string', ifMatch: 'number?' }, ({ path, content, ifMatch }) => fs.write(path, content, { ...agentOpts(), ifMatch })),
+        T('fs_edit', '精确替换：old 在文件中必须唯一匹配', { path: 'string', old: 'string', next: 'string' }, ({ path, old, next }) => fs.edit(path, old, next, agentOpts())),
+        T('fs_mv', '移动/重命名文件', { from: 'string', to: 'string' }, ({ from, to }) => fs.mv(from, to, agentOpts())),
+        T('fs_rm', '删除文件', { path: 'string' }, ({ path }) => fs.rm(path, agentOpts())),
+        // 回滚面
+        T('fs_checkpoint', '手动创建快照锚点（turn 开始时已自动有一个）', {}, () => fs.checkpoint(agentOpts())),
+        T('fs_restore', '回滚到指定 checkpoint（本身是一条可再撤销的写）；若 checkpoint 之后有人类编辑，默认拒绝并返回 restore-conflict{humanPaths}，需 force:true 确认覆盖', { cpId: 'string', force: 'boolean?' }, ({ cpId, force }) => fs.restore(cpId, { ...agentOpts(), force }), { dangerous: true }),
+        T('fs_diff', '列出某轮 turn 的全部改动（默认当前 turn）', { turnId: 'string?' }, ({ turnId } = {}) => fs.diff(turnId ?? activeTurn ?? undefined)),
+    ];
+    return {
+        tools,
+        byName: Object.fromEntries(tools.map((t) => [t.name, t])),
+        beginTurn,
+        endTurn,
+        get activeTurn() { return activeTurn; },
+    };
+}

package/dist/client.js

@@ -0,0 +1,234 @@
+/**
+ * ProjectFsClient — 主线程侧 ProjectFS 封装（P0，同 origin）。
+ * 起 fs-core / fs-query 两个 worker，牵好 core→query 的 diff 端口，
+ * 暴露 Promise API；写请求自动带 opId，超时重试幂等（同 opId 重发）。
+ */
+const WRITE_TIMEOUT_MS = 8000;
+export class ProjectFsClient {
+    projectId;
+    clientId;
+    core;
+    query;
+    pending;
+    qPending;
+    changeCbs;
+    modeCbs;
+    _mode;
+    seq;
+    welcome = null;
+    pingTimer;
+    lastPong;
+    _retried;
+    /** 测试用：抹掉一个项目的全部持久层（只能在无 core 运行时调用）。 */
+    static async wipe(projectId) {
+        const root = await navigator.storage.getDirectory();
+        try {
+            await root.removeEntry(projectId, { recursive: true });
+        }
+        catch { }
+    }
+    static async connect({ projectId, coreUrl = '/ide/fs/fs-core.worker.js', queryUrl = '/ide/fs/fs-query.worker.js', clientId = 'c-' + Math.random().toString(36).slice(2, 10), }) {
+        const c = new ProjectFsClient();
+        c.projectId = projectId;
+        c.clientId = clientId;
+        c.core = new Worker(coreUrl, { type: 'module' });
+        c.query = new Worker(queryUrl, { type: 'module' });
+        c.pending = new Map(); // id -> {resolve, reject, timer}
+        c.qPending = new Map();
+        c.changeCbs = new Set();
+        c.modeCbs = new Set();
+        c._mode = 'starting';
+        c.seq = 0;
+        c.welcome = null;
+        const chan = new MessageChannel();
+        const welcomed = new Promise((resolve, reject) => {
+            c.core.onmessage = (e) => c._onCoreMessage(e.data, resolve, reject);
+            c.core.onerror = (e) => reject(new Error('fs-core worker error: ' + e.message));
+        });
+        c.query.onmessage = (e) => c._onQueryMessage(e.data);
+        c.query.postMessage({ type: 'init', corePort: chan.port2 }, [chan.port2]);
+        c.core.postMessage({ type: 'HELLO', projectId, clientId, capabilityRequest: { mode: 'rw' }, queryPort: chan.port1 }, [chan.port1]);
+        c.welcome = await welcomed;
+        c._setMode(c.welcome.mode || (c.welcome.readonly ? 'readonly' : 'writer'));
+        c.pingTimer = setInterval(() => { try {
+            c.core.postMessage({ type: 'PING', t: Date.now() });
+        }
+        catch { } }, 10000);
+        c.lastPong = Date.now();
+        return c;
+    }
+    _onCoreMessage(msg, resolveWelcome, rejectWelcome) {
+        if (msg.type === 'WELCOME') {
+            this._handleWelcome(msg, resolveWelcome);
+            return;
+        }
+        if (msg.type === 'FATAL') {
+            this._handleFatal(msg, rejectWelcome);
+            return;
+        }
+        if (msg.type === 'PONG') {
+            this.lastPong = Date.now();
+            return;
+        }
+        if (msg.evt) {
+            this._handleEvt(msg);
+            return;
+        }
+        if (msg.id !== undefined)
+            this._handleRpcReply(msg);
+    }
+    _handleWelcome(msg, resolveWelcome) {
+        if (resolveWelcome)
+            resolveWelcome(msg);
+    }
+    _handleFatal(msg, rejectWelcome) {
+        this._setMode('dead');
+        const err = new Error('fs-core fatal: ' + msg.error);
+        if (rejectWelcome)
+            rejectWelcome(err);
+        for (const [, p] of this.pending)
+            p.reject(err);
+        this.pending.clear();
+    }
+    _handleEvt(msg) {
+        if (msg.evt === 'writer-granted')
+            this._setMode('writer');
+        else if (msg.evt === 'writer-lost')
+            this._setMode('readonly');
+        for (const cb of this.changeCbs) {
+            try {
+                cb(msg);
+            }
+            catch { }
+        }
+    }
+    _handleRpcReply(msg) {
+        const p = this.pending.get(msg.id);
+        if (!p)
+            return;
+        this.pending.delete(msg.id);
+        if (p.timer)
+            clearTimeout(p.timer);
+        if (msg.ok)
+            p.resolve(msg.result);
+        else
+            p.reject(Object.assign(new Error(msg.error), { code: msg.code, ...(msg.humanPaths !== undefined ? { humanPaths: msg.humanPaths } : {}), ...(msg.auditGap !== undefined ? { auditGap: msg.auditGap } : {}) }));
+    }
+    _onQueryMessage(msg) {
+        if (msg.id === undefined)
+            return;
+        const p = this.qPending.get(msg.id);
+        if (!p)
+            return;
+        this.qPending.delete(msg.id);
+        if (msg.ok)
+            p.resolve(msg.result);
+        else
+            p.reject(Object.assign(new Error(msg.error), { code: msg.code }));
+    }
+    _rpc(op, args, { opId, timeout } = {}) {
+        const id = ++this.seq;
+        return new Promise((resolve, reject) => {
+            const entryResolve = resolve;
+            const timer = timeout
+                ? setTimeout(() => {
+                    // 超时重试一次：同 opId 幂等（fs-core 对已知 opId 返回既有结果）
+                    if (opId && !this._retried) {
+                        const retryId = ++this.seq;
+                        this.pending.set(retryId, { resolve: entryResolve, reject, timer: setTimeout(() => { this.pending.delete(retryId); reject(new Error(op + ' timeout (after retry)')); }, timeout) });
+                        this.pending.delete(id);
+                        this.core.postMessage({ id: retryId, op, args, opId });
+                    }
+                    else {
+                        this.pending.delete(id);
+                        reject(new Error(op + ' timeout'));
+                    }
+                }, timeout)
+                : null;
+            this.pending.set(id, { resolve: entryResolve, reject, timer });
+            this.core.postMessage({ id, op, args, opId });
+        });
+    }
+    _qrpc(op, args) {
+        const id = ++this.seq;
+        return new Promise((resolve, reject) => {
+            this.qPending.set(id, { resolve: resolve, reject });
+            this.query.postMessage({ id, op, args });
+        });
+    }
+    _writeOp(op, args) {
+        return this._rpc(op, args, { opId: crypto.randomUUID(), timeout: WRITE_TIMEOUT_MS });
+    }
+    // ── 写 API（{actor:'human'|'agent', turnId, ifMatch} 透传）──
+    write(path, content, opts = {}) { return this._writeOp('write', { path, content, ...opts }); }
+    edit(path, old, next, opts = {}) { return this._writeOp('edit', { path, old, next, ...opts }); }
+    rm(path, opts = {}) { return this._writeOp('rm', { path, ...opts }); }
+    mv(from, to, opts = {}) { return this._writeOp('mv', { from, to, ...opts }); }
+    mkdir(path, opts = {}) { return this._writeOp('mkdir', { path, ...opts }); }
+    checkpoint(opts = {}) { return this._writeOp('checkpoint', { ...opts }); }
+    /** opts: {baseGen?, force?} 透传给 fs-core（§4.7 restore 冲突策略）；baseGen 缺省时
+     * fs-core 从 checkpoint 自身记录的 gen 推导。 */
+    restore(cpId, opts = {}) { return this._writeOp('restore', { cpId, ...opts }); }
+    compact() { return this._rpc('compact', {}, { timeout: 30000 }); }
+    // ── P4 turn 能力：铸造（附带 checkpoint 锚）→ agent 写执法 → 撤销 ──
+    turnBegin(turnId, opts = {}) { return this._writeOp('turnBegin', { turnId, ...opts }); }
+    turnEnd(turnId) { return this._writeOp('turnEnd', { turnId }); }
+    /** 该 turn 的改动清单（WAL actor/turnId 审计标注免费提供）。 */
+    diff(turnId) { return this._rpc('diff', { turnId }); }
+    /** W4 纵深加固令牌门（docs/k3-terminal-split-plan.md §6 替代方案 A / §8.3）：特权方法，只应
+     * 由内核（kernel.js createKernel）在 boot 早期调用一次，把只有内核持有的随机令牌交给 fs-core；
+     * 此后 actor:'agent' 的写类 op 必须在 opts 里携带匹配的 agentToken（fs-core 侧强制，见
+     * fs-core.worker.js checkTurn/armAgentToken）。无 opId/超时重试——一次性 admin 调用，非写路径
+     * 幂等本就由 fs-core 的 armAgentToken 自身保证（同令牌重放 ok，不同令牌拒绝）。 */
+    armAgentTokenGate(token) { return this._rpc('armAgentTokenGate', { token }); }
+    // ── 读 API：小读走 core（权威），查询/快照走 query（不占写路径）──
+    read(path) { return this._rpc('read', { path }); }
+    ls() { return this._rpc('ls', {}); }
+    status() { return this._rpc('status', {}); }
+    snapshot(opts = {}) { return this._qrpc('snapshot', opts); }
+    grep(pattern, opts = {}) { return this._qrpc('grep', { pattern, ...opts }); }
+    glob(pattern, opts = {}) { return this._qrpc('glob', { pattern, ...opts }); }
+    queryRead(path, opts = {}) { return this._qrpc('read', { path, ...opts }); }
+    /** 空项目时批量写入种子文件；非空则跳过。返回 {seeded, count}。 */
+    async seed(files) {
+        const { paths } = await this.ls();
+        if (paths.length)
+            return { seeded: false, count: paths.length };
+        const entries = Object.entries(files);
+        for (let i = 0; i < entries.length; i += 50) {
+            await Promise.all(entries.slice(i, i + 50).map(([p, c]) => this.write(p, c, { actor: 'human' })));
+        }
+        return { seeded: true, count: entries.length };
+    }
+    onChange(cb) {
+        this.changeCbs.add(cb);
+        return () => this.changeCbs.delete(cb);
+    }
+    /** 当前单写者状态：starting(HELLO 未回)|writer(持写者租约)|readonly(排队中或已交出)|
+     * draining(worker 侧过渡态，client 不会长时间观察到——见 fs-core.worker.js onBroadcast，
+     * 收敛为 readonly 再广播事件)|dead(FATAL，worker 已不可用)。由 WELCOME 与
+     * writer-granted/writer-lost 事件驱动，供宿主向用户呈现"另一个标签页持有写权"之类提示。 */
+    get mode() { return this._mode; }
+    _setMode(mode) {
+        if (this._mode === mode)
+            return;
+        this._mode = mode;
+        for (const cb of this.modeCbs) {
+            try {
+                cb(mode);
+            }
+            catch { }
+        }
+    }
+    /** 订阅 mode 变化（writer ⇄ readonly ⇄ dead）；返回退订函数。 */
+    onModeChange(cb) {
+        this.modeCbs.add(cb);
+        return () => this.modeCbs.delete(cb);
+    }
+    destroy() {
+        clearInterval(this.pingTimer);
+        this._setMode('dead');
+        this.core.terminate();
+        this.query.terminate();
+    }
+}

package/dist/disk-mirror.js

@@ -0,0 +1,97 @@
+/**
+ * 本地磁盘镜像（P5，Chromium only）—— showDirectoryPicker() 授权一个真实磁盘目录，
+ * 把项目树 write-through 镜像过去：用户在访达/资源管理器里能看到自己的项目。
+ * 这是"持久化到磁盘"的字面回答（架构文档 §4 出口 1）。
+ *
+ * 策略：fs-change 防抖 2s 全量比对同步（内容不变的文件跳过 —— 内容比对在内存，
+ * 磁盘只写变更）；删除按上次镜像记录清理。授权需要用户手势，无授权时静默不动。
+ */
+export function createDiskMirror(fs) {
+    let dir = null;
+    let last = new Map(); // path -> content（上次已镜像的内容）
+    let timer;
+    let syncing = false;
+    let pending = false; // syncAll 运行期间又发生了变更，结束后需要再镜像一轮
+    /** @param handle 已获取授权的目录句柄；传了就直接用（跳过
+     * showDirectoryPicker 弹窗），调用方自行负责获取授权（例如复用宿主已有的句柄）。 */
+    async function pick(handle) {
+        if (handle) {
+            dir = handle;
+        }
+        else {
+            if (!window.showDirectoryPicker)
+                throw new Error('showDirectoryPicker 不可用（需要 Chromium）');
+            dir = await window.showDirectoryPicker({ mode: 'readwrite' });
+        }
+        last = new Map();
+        const r = await syncAll();
+        return { name: dir.name, ...r };
+    }
+    /** 停用镜像：取消挂起的防抖定时器，清空目录句柄与镜像记账，使后续任何 syncAll
+     * 调用（包括仍在飞行中的定时器回调）在入口处天然短路。 */
+    function dispose() {
+        clearTimeout(timer);
+        dir = null;
+        last = new Map();
+    }
+    async function syncAll() {
+        if (!dir || syncing)
+            return null;
+        syncing = true;
+        try {
+            const snap = await fs.snapshot();
+            let written = 0;
+            for (const [p, content] of Object.entries(snap.files)) {
+                if (last.get(p) === content)
+                    continue;
+                const parts = p.split('/');
+                let d = dir;
+                for (const seg of parts.slice(0, -1))
+                    d = await d.getDirectoryHandle(seg, { create: true });
+                const fh = await d.getFileHandle(parts[parts.length - 1], { create: true });
+                const w = await fh.createWritable();
+                await w.write(content);
+                await w.close();
+                last.set(p, content);
+                written++;
+            }
+            let removed = 0;
+            for (const p of [...last.keys()]) {
+                if (p in snap.files)
+                    continue;
+                try {
+                    const parts = p.split('/');
+                    let d = dir;
+                    for (const seg of parts.slice(0, -1))
+                        d = await d.getDirectoryHandle(seg);
+                    await d.removeEntry?.(parts[parts.length - 1]);
+                }
+                catch { /* 目录已不在等：忽略 */ }
+                last.delete(p);
+                removed++;
+            }
+            return { written, removed, gen: snap.gen };
+        }
+        finally {
+            syncing = false;
+            if (pending && dir) {
+                pending = false;
+                schedule();
+            }
+        }
+    }
+    function schedule() {
+        if (!dir)
+            return;
+        if (syncing) {
+            // 一轮 syncAll 正在进行中：这次变更不能被这轮同步捕获（快照已在读取途中），
+            // 也不能立刻并发再跑一轮（syncAll 自身会在入口处丢弃）。记一个 pending，
+            // 交给上面 syncAll 的 finally 在这轮结束后重新排期，保证不丢更新。
+            pending = true;
+            return;
+        }
+        clearTimeout(timer);
+        timer = setTimeout(() => { syncAll().catch(() => { }); }, 2000);
+    }
+    return { pick, syncAll, schedule, dispose, get active() { return !!dir; } };
+}