duet-mcp 0.6.1

package/lib/client-store.js

@@ -0,0 +1,147 @@
+import { parseRevision } from "./protocol.js";
+import { WAIT_MS } from "./wire.js";
+function snapshot(value) {
+    const s = value;
+    if (!s || !parseRevision(s.revision) || !("doc" in s) || typeof s.actor !== "string" ||
+        !s.activity || typeof s.activity !== "object")
+        throw new Error("snapshot の形ではない。GUI と daemon を同時に更新すること。");
+    return s;
+}
+/** ブラウザで一つ共有する購読。React に依存せず応答の順序を管理する。 */
+export class ClientStore {
+    request;
+    current = null;
+    listeners = new Set();
+    running = false;
+    ctrl = null;
+    polling = null;
+    generation = 0;
+    pollVersion = 0;
+    force = false;
+    received = 0;
+    refreshWaiters = [];
+    constructor(request = (...args) => fetch(...args)) {
+        this.request = request;
+    }
+    getSnapshot = () => this.current;
+    get receivedAt() { return this.received; }
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        this.running = true;
+        this.start();
+        return () => {
+            this.listeners.delete(listener);
+            if (!this.listeners.size) {
+                this.running = false;
+                this.pollVersion++;
+                this.ctrl?.abort();
+            }
+        };
+    };
+    refresh = () => {
+        const done = new Promise((resolve) => this.refreshWaiters.push(resolve));
+        this.force = true;
+        this.pollVersion++;
+        this.ctrl?.abort();
+        this.start();
+        return done;
+    };
+    emit() { for (const listener of this.listeners)
+        listener(); }
+    start() {
+        if (!this.running || this.polling)
+            return;
+        this.polling = this.loop().finally(() => {
+            this.polling = null;
+            if (this.running)
+                this.start();
+        });
+    }
+    accept(s, authoritative) {
+        const incoming = parseRevision(s.revision);
+        const old = this.current && parseRevision(this.current.revision);
+        if (old && incoming.epoch !== old.epoch) {
+            if (!authoritative) {
+                this.refresh();
+                return;
+            }
+            this.generation++;
+        }
+        else if (old && incoming.seq < old.seq) {
+            // この取得より新しい完全な snapshot を既に受信している。
+            if (authoritative)
+                for (const resolve of this.refreshWaiters.splice(0))
+                    resolve();
+            return;
+        }
+        this.received = Date.now();
+        const generation = this.generation;
+        this.current = {
+            ...s,
+            // 固定した snapshot の版を送る。送信時の current は使わない。
+            run: (name, args = {}) => this.run(s.revision, generation, name, args),
+        };
+        this.emit();
+        if (authoritative)
+            for (const resolve of this.refreshWaiters.splice(0))
+                resolve();
+    }
+    async run(revision, generation, name, args) {
+        let result;
+        try {
+            const res = await this.request(`/api/op/${encodeURIComponent(name)}`, {
+                method: "POST", headers: { "content-type": "application/json" },
+                body: JSON.stringify({ ...args, baseRevision: revision }),
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const raw = await res.json();
+            const s = snapshot(raw);
+            if (!("ok" in s) && !("rejected" in s) && !("conflict" in s))
+                throw new Error("操作応答の形ではない");
+            result = s;
+        }
+        catch {
+            this.refresh();
+            throw new Error("操作の結果を確認できない。自動再送していない。現在値を再取得して確認すること。");
+        }
+        if (generation !== this.generation) {
+            throw new Error("応答を待つ間に daemon が交代した。現在値を確認すること。");
+        }
+        this.accept(result, false);
+        return result;
+    }
+    async loop() {
+        while (this.running) {
+            this.ctrl = new AbortController();
+            const version = this.pollVersion;
+            const since = this.force ? undefined : this.current?.revision;
+            this.force = false;
+            try {
+                const q = since === undefined ? "" : `?since=${encodeURIComponent(since)}&timeout=${WAIT_MS}`;
+                const res = await this.request(`/api/doc${q}`, { signal: this.ctrl.signal });
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                const s = snapshot(await res.json());
+                if (!this.running || version !== this.pollVersion)
+                    continue;
+                this.accept(s, true);
+            }
+            catch {
+                if (!this.running)
+                    break;
+                if (version !== this.pollVersion)
+                    continue;
+                // 再接続待ちも abort できるようにする。
+                const signal = this.ctrl.signal;
+                await new Promise((resolve) => {
+                    const done = () => { clearTimeout(timer); signal.removeEventListener("abort", done); resolve(); };
+                    const timer = setTimeout(done, 500);
+                    signal.addEventListener("abort", done, { once: true });
+                    if (signal.aborted)
+                        done();
+                });
+            }
+        }
+    }
+}

package/lib/client.d.ts

@@ -0,0 +1,25 @@
+import { type Observed } from "./client-store.js";
+export type { Observed } from "./client-store.js";
+export type { Snapshot, RunResult, Revision, Change } from "./protocol.js";
+export declare const refreshDoc: () => Promise<void>;
+export declare function touch(): void;
+export declare const blobUrl: (id: string) => string;
+export declare function uploadBlob(file: Blob): Promise<{
+    id: string;
+    mime: string;
+    size: number;
+}>;
+export declare function useDoc<Doc>(): Observed<Doc> | null;
+export declare function useEdit<Value>(): {
+    begin: (base: Observed<unknown>, value: Value) => void;
+    restart: (base: Observed<unknown>, value: Value) => void;
+    setValue: (value: Value) => void;
+    cancel: () => void;
+    run: (name: string, args?: Record<string, unknown>) => Promise<import("./protocol.js").RunResult<unknown>>;
+    active: boolean;
+    value: Value | undefined;
+    pending: boolean;
+    result: import("./protocol.js").RunResult<unknown> | null;
+    error: string | null;
+};
+export { EditSession } from "./edit.js";

package/lib/client.js

@@ -0,0 +1,58 @@
+import { useEffect, useLayoutEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { ClientStore } from "./client-store.js";
+import { EditSession } from "./edit.js";
+const store = new ClientStore();
+export const refreshDoc = store.refresh;
+export function touch() { void fetch("/api/touch", { method: "POST" }).catch(() => { }); }
+export const blobUrl = (id) => `/blob/${id}`;
+export async function uploadBlob(file) {
+    const res = await fetch("/api/blob", {
+        method: "POST", headers: { "content-type": file.type || "application/octet-stream" }, body: file,
+    });
+    if (!res.ok)
+        throw new Error(`uploadBlob: HTTP ${res.status}`);
+    return res.json();
+}
+// useDoc が複数でも活動リスナは一組だけ。
+let activityUsers = 0;
+let lastTouch = 0;
+const onActivity = () => {
+    if (Date.now() - lastTouch < 1000)
+        return;
+    lastTouch = Date.now();
+    touch();
+};
+export function useDoc() {
+    const raw = useSyncExternalStore(store.subscribe, store.getSnapshot, () => null);
+    const [now, setNow] = useState(Date.now);
+    useEffect(() => {
+        const timer = setInterval(() => setNow(Date.now()), 1000);
+        if (activityUsers++ === 0) {
+            window.addEventListener("pointerdown", onActivity, { capture: true, passive: true });
+            window.addEventListener("keydown", onActivity, { capture: true, passive: true });
+        }
+        return () => {
+            clearInterval(timer);
+            if (--activityUsers === 0) {
+                window.removeEventListener("pointerdown", onActivity, true);
+                window.removeEventListener("keydown", onActivity, true);
+            }
+        };
+    }, []);
+    // 受信時ではなく、この snapshot を描いた DOM の commit 後に進める。
+    useLayoutEffect(() => {
+        if (raw)
+            document.documentElement.dataset.duetRevision = raw.revision;
+    }, [raw]);
+    return useMemo(() => raw && ({
+        ...raw,
+        activity: Object.fromEntries(Object.entries(raw.activity).map(([who, ms]) => [who, ms + Math.max(0, now - store.receivedAt)])),
+    }), [raw, now]);
+}
+export function useEdit() {
+    const [session] = useState(() => new EditSession());
+    const state = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);
+    return { ...state, begin: session.begin, restart: session.restart, setValue: session.setValue,
+        cancel: session.cancel, run: session.run };
+}
+export { EditSession } from "./edit.js";

package/lib/diff.d.ts

@@ -0,0 +1,27 @@
+/**
+ * doc の構造差分。
+ *
+ * 変更検知（差分が空か）と変更説明（どこを触ったか）を、この 1 箇所から得る。
+ * 文字列比較をやめたので、キーの並びが変わっただけで revision が進むことがない。
+ *
+ * パスは JSON Pointer（RFC 6901）。root は ""、以下は "/cards/3/title"。
+ * 標準の書式なので、そのまま LLM への応答に載せて読ませられる。
+ */
+/** doc に置ける値。開発者が明示したいときに使う（強制はしない）。 */
+export type Json = string | number | boolean | null | Json[] | {
+    [k: string]: Json;
+};
+/**
+ * JSON で表せない値を、書かれた瞬間に見つける。
+ *
+ * structuredClone は Map / Set / Date を保つが JSON.stringify は保たない。
+ * 検査しないと、Map を置いたアプリは「コミットしたのに何も起きない」あるいは
+ * 「毎回 revision が進む」という、原因の分からない壊れ方をする。
+ * 型で縛るより、実際に置かれた場所を名指しで言う方が短く終わる。
+ */
+export declare function assertJson(value: unknown, path?: string, seen?: Set<object>): void;
+/**
+ * before から after で変わった場所。空なら何も変わっていない。
+ * 深い方から葉のパスだけを返す（"/cards/3/title" は返るが "/cards" は返らない）。
+ */
+export declare function changes(before: unknown, after: unknown): string[];

package/lib/diff.js

@@ -0,0 +1,103 @@
+/**
+ * doc の構造差分。
+ *
+ * 変更検知（差分が空か）と変更説明（どこを触ったか）を、この 1 箇所から得る。
+ * 文字列比較をやめたので、キーの並びが変わっただけで revision が進むことがない。
+ *
+ * パスは JSON Pointer（RFC 6901）。root は ""、以下は "/cards/3/title"。
+ * 標準の書式なので、そのまま LLM への応答に載せて読ませられる。
+ */
+const isPlain = (v) => {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+};
+const seg = (key) => `/${String(key).replace(/~/g, "~0").replace(/\//g, "~1")}`;
+const at = (path) => path || "(root)";
+/**
+ * JSON で表せない値を、書かれた瞬間に見つける。
+ *
+ * structuredClone は Map / Set / Date を保つが JSON.stringify は保たない。
+ * 検査しないと、Map を置いたアプリは「コミットしたのに何も起きない」あるいは
+ * 「毎回 revision が進む」という、原因の分からない壊れ方をする。
+ * 型で縛るより、実際に置かれた場所を名指しで言う方が短く終わる。
+ */
+export function assertJson(value, path = "", seen = new Set()) {
+    if (value !== null && typeof value === "object") {
+        if (seen.has(value))
+            throw new Error(`JSON の ${at(path)} が循環参照。`);
+        seen.add(value);
+    }
+    if (value === null)
+        return;
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return;
+        case "number":
+            // NaN / Infinity は JSON では null になる。黙って値が変わるので弾く。
+            if (!Number.isFinite(value)) {
+                throw new Error(`doc の ${at(path)} が ${String(value)}。JSON では null になるので置けない。`);
+            }
+            return;
+        case "undefined":
+            throw new Error(`doc の ${at(path)} が undefined。JSON では消えるので、` +
+                `キーを消すなら delete、値を空にするなら null を使うこと。`);
+        default:
+            break;
+    }
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++)
+            assertJson(value[i], path + seg(i), seen);
+        seen.delete(value);
+        return;
+    }
+    if (isPlain(value)) {
+        for (const [k, v] of Object.entries(value))
+            assertJson(v, path + seg(k), seen);
+        seen.delete(value);
+        return;
+    }
+    const name = value.constructor?.name ?? typeof value;
+    throw new Error(`doc の ${at(path)} が ${name}。JSON で表せる値（object / array / string / number / boolean / null）だけ置けること。`);
+}
+/** union。before の並びを保ったまま、after で増えたキーを後ろに足す。 */
+function keysOf(a, b) {
+    const out = Object.keys(a);
+    for (const k of Object.keys(b))
+        if (!Object.hasOwn(a, k))
+            out.push(k);
+    return out;
+}
+function walk(a, b, path, out) {
+    if (a === b)
+        return;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        // 長さが違えば要素の対応が付かない。配列ごと触ったことにする。
+        // 変更説明では配列全体を指す。競合判定には使わない。
+        if (a.length !== b.length) {
+            out.push(path);
+            return;
+        }
+        for (let i = 0; i < a.length; i += 1)
+            walk(a[i], b[i], path + seg(i), out);
+        return;
+    }
+    if (isPlain(a) && isPlain(b)) {
+        for (const k of keysOf(a, b))
+            walk(a[k], b[k], path + seg(k), out);
+        return;
+    }
+    // プリミティブ、型が変わった、片方が null。ここが葉になる。
+    out.push(path);
+}
+/**
+ * before から after で変わった場所。空なら何も変わっていない。
+ * 深い方から葉のパスだけを返す（"/cards/3/title" は返るが "/cards" は返らない）。
+ */
+export function changes(before, after) {
+    const out = [];
+    walk(before, after, "", out);
+    return out;
+}

package/lib/doc.d.ts

@@ -0,0 +1,30 @@
+import { type Revision, type Snapshot, type RunResult, type WaitResult } from "./protocol.js";
+import type { Actor, AppDef } from "./types.js";
+export type { RunResult, WaitResult, Diff, Change } from "./protocol.js";
+/** snapshot が確定状態。ログは説明用であり、操作の可否に使わない。 */
+export declare class DocStore<Doc> {
+    private readonly app;
+    private readonly dataDir;
+    readonly file: string;
+    readonly logFile: string;
+    private readonly epoch;
+    private seq;
+    private oldest;
+    private state;
+    private readonly schemas;
+    private readonly waiters;
+    private readonly seen;
+    private log;
+    constructor(app: AppDef<Doc>, dataDir?: string);
+    get revision(): Revision;
+    private load;
+    private persist;
+    private appendLog;
+    touch(actor: Actor): void;
+    snapshot(actor: Actor): Snapshot<Doc>;
+    run(name: string, args: unknown, actor: Actor): RunResult<Doc>;
+    private position;
+    private collect;
+    private diff;
+    wait(since: Revision | undefined, until: string[] | undefined, timeoutMs: number, actor: Actor, signal?: AbortSignal): Promise<WaitResult<Doc>>;
+}

package/lib/doc.js

@@ -0,0 +1,221 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { assertJson, changes } from "./diff.js";
+import { inputShape } from "./op.js";
+import { dataDirFor } from "./paths.js";
+import { parseRevision } from "./protocol.js";
+const LOG_LIMIT = 1000;
+const CHANGE_LIMIT = 100;
+const CHANGE_BYTES = 32 * 1024;
+const LOG_FILE_MAX = 4 * 1024 * 1024;
+class Rejection extends Error {
+}
+/** snapshot が確定状態。ログは説明用であり、操作の可否に使わない。 */
+export class DocStore {
+    app;
+    dataDir;
+    file;
+    logFile;
+    epoch = randomUUID();
+    seq = 0;
+    oldest = 0;
+    state;
+    schemas = new Map();
+    waiters = new Set();
+    seen = new Map();
+    log = [];
+    constructor(app, dataDir = dataDirFor(app)) {
+        this.app = app;
+        this.dataDir = dataDir;
+        this.file = path.join(dataDir, `${app.id}.json`);
+        this.logFile = path.join(dataDir, `${app.id}.log`);
+        this.state = app.initialDoc();
+        assertJson(this.state);
+        this.load();
+        this.oldest = this.seq;
+        for (const op of app.ops) {
+            if (this.schemas.has(op.name))
+                throw new Error(`duplicate op: ${op.name}`);
+            this.schemas.set(op.name, z.object(inputShape(op)));
+        }
+    }
+    get revision() { return `${this.epoch}:${this.seq}`; }
+    load() {
+        if (!fs.existsSync(this.file))
+            return;
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(this.file, "utf8"));
+            if (!raw || !Number.isSafeInteger(raw.revision) || raw.revision < 0 || !("doc" in raw)) {
+                throw new Error("snapshot の形ではない");
+            }
+            assertJson(raw.doc);
+        }
+        catch (err) {
+            const stamp = Date.now();
+            // 退避できなければ起動を止める。元ファイルを初期値で潰さない。
+            fs.renameSync(this.file, `${this.file}.corrupt.${stamp}`);
+            if (fs.existsSync(this.logFile))
+                fs.renameSync(this.logFile, `${this.logFile}.corrupt.${stamp}`);
+            console.error("[duet] snapshot を退避した", err);
+            return;
+        }
+        if (raw.version !== undefined && raw.version !== this.app.version) {
+            const backup = `${this.file}.version.${Date.now()}.${randomUUID()}.bak`;
+            fs.copyFileSync(this.file, backup);
+            console.error(`[duet] version ${raw.version} → ${this.app.version}。移行が必要なら ${backup} を使う。`);
+        }
+        this.seq = raw.revision;
+        this.state = raw.doc;
+    }
+    persist(seq, doc) {
+        fs.mkdirSync(this.dataDir, { recursive: true });
+        const tmp = `${this.file}.${process.pid}.tmp`;
+        try {
+            fs.writeFileSync(tmp, JSON.stringify({ revision: seq, version: this.app.version, doc }));
+            fs.renameSync(tmp, this.file);
+        }
+        catch (err) {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { /* 保存前の失敗。元ファイルは残す。 */ }
+            throw err;
+        }
+    }
+    appendLog(event) {
+        try {
+            if (fs.existsSync(this.logFile) && fs.statSync(this.logFile).size > LOG_FILE_MAX) {
+                fs.renameSync(this.logFile, `${this.logFile}.1`);
+            }
+            fs.appendFileSync(this.logFile, `${JSON.stringify(event)}\n`);
+        }
+        catch (err) {
+            // snapshot は確定済み。ログの失敗を操作の失敗に変えない。
+            console.error("[duet] 操作は保存済み。補助ログを書けなかった。", err);
+        }
+    }
+    touch(actor) { this.seen.set(actor, Date.now()); }
+    snapshot(actor) {
+        const now = Date.now();
+        return {
+            revision: this.revision, actor, doc: structuredClone(this.state),
+            activity: Object.fromEntries([...this.seen].map(([who, time]) => [who, now - time])),
+        };
+    }
+    run(name, args, actor) {
+        const op = this.app.ops.find((o) => o.name === name);
+        if (!op)
+            throw new Error(`unknown op: ${name}`);
+        const parsed = this.schemas.get(name).safeParse(args ?? {});
+        if (!parsed.success)
+            return {
+                ...this.snapshot(actor), rejected: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", "),
+            };
+        const { baseRevision, ...rest } = parsed.data;
+        if (baseRevision !== this.revision)
+            return {
+                ...this.snapshot(actor), conflict: true, ...this.diff(baseRevision),
+            };
+        this.touch(actor);
+        const draft = structuredClone(this.state);
+        let result;
+        try {
+            result = op.handler({ doc: draft, actor, reject: (reason) => { throw new Rejection(reason); } }, rest);
+            if (result !== null && (typeof result === "object" || typeof result === "function") &&
+                typeof result.then === "function") {
+                void Promise.resolve(result).catch(() => { });
+                throw new Error(`op ${name}: handler は同期処理に限定する。Promise は返せない。`);
+            }
+        }
+        catch (err) {
+            if (err instanceof Rejection)
+                return { ...this.snapshot(actor), rejected: err.message };
+            throw err;
+        }
+        assertJson(draft);
+        if (result !== undefined)
+            assertJson(result, "/result");
+        const touched = changes(this.state, draft);
+        if (touched.length) {
+            const seq = this.seq + 1;
+            if (!Number.isSafeInteger(seq))
+                throw new Error("revision の連番が上限に達した。");
+            // ハンドラが参照を保持しても、後から確定状態を変更できない。
+            const committed = structuredClone(draft);
+            this.persist(seq, committed);
+            this.state = committed;
+            this.seq = seq;
+            const event = { seq, revision: this.revision, op: name, actor, args: rest, touched };
+            this.log.push(event);
+            if (this.log.length > LOG_LIMIT) {
+                this.log.shift();
+                this.oldest = this.log[0].seq - 1;
+            }
+            for (const wake of [...this.waiters])
+                wake();
+            this.appendLog(event);
+        }
+        return { ...this.snapshot(actor), ok: true, ...(result === undefined ? {} : { result: structuredClone(result) }) };
+    }
+    position(since) {
+        const parsed = parseRevision(since);
+        return parsed?.epoch === this.epoch && parsed.seq >= this.oldest && parsed.seq <= this.seq ? parsed.seq : null;
+    }
+    collect(since, until) {
+        return this.log.filter((e) => e.seq > since && (!until?.length || until.includes(e.op)));
+    }
+    diff(since, until) {
+        const pos = this.position(since);
+        if (pos === null)
+            return { changes: [], truncated: true };
+        const out = [];
+        for (const e of this.collect(pos, until)) {
+            const last = out.at(-1);
+            if (last?.op === e.op && last.actor === e.actor) {
+                last.revision = e.revision;
+                last.count++;
+                last.touched = [...new Set([...last.touched, ...e.touched])];
+            }
+            else
+                out.push({ revision: e.revision, op: e.op, actor: e.actor, count: 1, touched: [...e.touched] });
+            if (out.length > CHANGE_LIMIT || Buffer.byteLength(JSON.stringify(out)) > CHANGE_BYTES) {
+                return { changes: [], truncated: true };
+            }
+        }
+        return { changes: out, truncated: false };
+    }
+    wait(since, until, timeoutMs, actor, signal) {
+        const result = (timedOut) => ({
+            ...this.snapshot(actor), ...(since === undefined ? { changes: [], truncated: false } : this.diff(since, until)), timedOut,
+        });
+        const ready = () => {
+            if (since === undefined)
+                return true;
+            const pos = this.position(since);
+            return pos === null || this.collect(pos, until).length > 0;
+        };
+        if (ready() || signal?.aborted)
+            return Promise.resolve(result(!!signal?.aborted));
+        return new Promise((resolve) => {
+            let done = false;
+            const finish = (timedOut) => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                this.waiters.delete(wake);
+                signal?.removeEventListener("abort", abort);
+                resolve(result(timedOut));
+            };
+            const wake = () => { if (ready())
+                finish(false); };
+            const abort = () => finish(true);
+            const timer = setTimeout(() => finish(true), timeoutMs);
+            this.waiters.add(wake);
+            signal?.addEventListener("abort", abort, { once: true });
+        });
+    }
+}

package/lib/edit.d.ts

@@ -0,0 +1,25 @@
+import type { Observed } from "./client-store.js";
+import type { RunResult } from "./protocol.js";
+export type EditState<Value> = {
+    active: boolean;
+    value: Value | undefined;
+    pending: boolean;
+    result: RunResult<unknown> | null;
+    error: string | null;
+};
+/** 下書きと観測時の呼び口を一緒に保持する。行の外に置けば移動しても残る。 */
+export declare class EditSession<Value> {
+    private base;
+    private inflight;
+    private listeners;
+    private state;
+    getSnapshot: () => EditState<Value>;
+    subscribe: (listener: () => void) => (() => void);
+    private update;
+    private editable;
+    begin: (base: Observed<unknown>, value: Value) => void;
+    restart: (base: Observed<unknown>, value: Value) => void;
+    setValue: (value: Value) => void;
+    cancel: () => void;
+    run: (name: string, args?: Record<string, unknown>) => Promise<RunResult<unknown>>;
+}