@listen1954/board 0.1.0

package/lib/service.js

@@ -0,0 +1,417 @@
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { spawn } from 'node:child_process';
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { applyMutate, assertSessionId, BoardNotFoundError, BoardOpError, BoardRevisionError, fireDueReminders, newId, summarizeBoard, } from './domain.js';
+/** Store-backed board API. Tests construct this directly (no Cordis). */
+export class BoardModel {
+    store;
+    wakeOnGlobalReminder;
+    now;
+    createId;
+    emitChange;
+    openFile;
+    mutationChain = Promise.resolve();
+    migrationPromise = null;
+    migrationChecked = false;
+    constructor(store, options = {}) {
+        this.store = store;
+        this.wakeOnGlobalReminder = options.wakeOnGlobalReminder ?? false;
+        this.now = options.now ?? (() => new Date());
+        this.createId = options.newId ?? newId;
+        this.emitChange = options.emit ?? (() => undefined);
+        this.openFile = options.openFile ?? openWithSystem;
+    }
+    async list(callerSessionId) {
+        const global = await this.loadUnifiedGlobal();
+        const session = projectSessionBoard(global, callerSessionId);
+        return [summarizeBoard(global), summarizeBoard(session)];
+    }
+    async getBoard(callerSessionId, scope, defaultColumns) {
+        const global = await this.loadUnifiedGlobal(defaultColumns);
+        return scope === 'global' ? global : projectSessionBoard(global, callerSessionId);
+    }
+    async getCard(callerSessionId, scope, cardId) {
+        const board = await this.getBoard(callerSessionId, scope);
+        const card = board.cards.find((item) => item.id === cardId);
+        if (card === undefined)
+            throw new BoardNotFoundError();
+        return card;
+    }
+    async mutate(callerSessionId, scope, op, revision) {
+        return this.enqueueMutation(async () => {
+            const currentGlobal = await this.loadUnifiedGlobal();
+            const currentView = scope === 'global' ? currentGlobal : projectSessionBoard(currentGlobal, callerSessionId);
+            if (revision !== undefined && currentView.revision !== revision) {
+                throw new BoardRevisionError(revision, currentView.revision);
+            }
+            const nextGlobal = scope === 'global'
+                ? applyMutate(currentGlobal, op, this.now(), this.createId)
+                : applySessionMutation(currentGlobal, callerSessionId, op, this.now(), this.createId);
+            await this.store.write(nextGlobal);
+            await this.removeDeletedAttachments(currentGlobal, nextGlobal);
+            this.emitBoard(nextGlobal);
+            return scope === 'global' ? nextGlobal : projectSessionBoard(nextGlobal, callerSessionId);
+        });
+    }
+    async addLog(callerSessionId, scope, cardId, text, attachments, revision) {
+        return this.enqueueMutation(async () => {
+            const currentGlobal = await this.loadUnifiedGlobal();
+            const currentView = scope === 'global' ? currentGlobal : projectSessionBoard(currentGlobal, callerSessionId);
+            if (currentView.revision !== revision)
+                throw new BoardRevisionError(revision, currentView.revision);
+            const files = prepareAttachments(attachments, this.createId);
+            const op = { type: 'addLog', cardId, text, attachments: files.map((file) => file.meta) };
+            const nextGlobal = scope === 'global'
+                ? applyMutate(currentGlobal, op, this.now(), this.createId)
+                : applySessionMutation(currentGlobal, callerSessionId, op, this.now(), this.createId);
+            const written = [];
+            try {
+                for (const file of files) {
+                    await this.store.writeAttachment(file.meta.id, file.data);
+                    written.push(file.meta.id);
+                }
+                await this.store.write(nextGlobal);
+            }
+            catch (error) {
+                for (const id of written)
+                    await this.store.removeAttachment(id);
+                throw error;
+            }
+            this.emitBoard(nextGlobal);
+            return scope === 'global' ? nextGlobal : projectSessionBoard(nextGlobal, callerSessionId);
+        });
+    }
+    async getAttachment(callerSessionId, scope, cardId, attachmentId) {
+        const card = await this.getCard(callerSessionId, scope, cardId);
+        const attachment = card.logs.flatMap((log) => log.attachments).find((item) => item.id === attachmentId);
+        if (attachment === undefined)
+            throw new BoardNotFoundError();
+        const data = await this.store.readAttachment(attachment.id);
+        return { name: attachment.name, type: attachment.type, data: data.toString('base64') };
+    }
+    async openAttachment(callerSessionId, scope, cardId, attachmentId) {
+        const card = await this.getCard(callerSessionId, scope, cardId);
+        const attachment = card.logs.flatMap((log) => log.attachments).find((item) => item.id === attachmentId);
+        if (attachment === undefined)
+            throw new BoardNotFoundError();
+        const path = await this.store.materializeAttachment(attachment.id, attachment.name);
+        await this.openFile(path);
+        return { opened: true };
+    }
+    async fireDue() {
+        return this.enqueueMutation(async () => {
+            const events = [];
+            if (!await this.store.exists('global'))
+                return events;
+            const current = await this.loadUnifiedGlobal();
+            const result = fireDueReminders(current, this.now());
+            if (result.fired.length === 0)
+                return events;
+            await this.store.write(result.board);
+            this.emitBoard(result.board);
+            events.push({ scope: 'global', board: result.board, fired: result.fired });
+            return events;
+        });
+    }
+    async loadUnifiedGlobal(defaultColumns) {
+        await this.ensureLegacyMigration(defaultColumns);
+        const board = await this.store.read('global', undefined, defaultColumns);
+        if (board.scope !== 'global')
+            throw new BoardNotFoundError();
+        return board;
+    }
+    async ensureLegacyMigration(defaultColumns) {
+        if (this.migrationChecked)
+            return;
+        if (this.migrationPromise === null) {
+            this.migrationPromise = this.migrateLegacySessionBoards(defaultColumns).finally(() => { this.migrationPromise = null; });
+        }
+        await this.migrationPromise;
+    }
+    async migrateLegacySessionBoards(defaultColumns) {
+        const boards = await this.store.readAll(defaultColumns);
+        const global = boards.find((board) => board.scope === 'global');
+        if (global === undefined)
+            throw new BoardNotFoundError();
+        if (global.sessionColumnsMigrated === true) {
+            this.migrationChecked = true;
+            return;
+        }
+        const legacy = boards.filter((board) => board.scope === 'session' && board.sessionId !== undefined);
+        if (legacy.length === 0) {
+            this.migrationChecked = true;
+            return;
+        }
+        const migrated = mergeLegacySessionBoards(global, legacy, this.now(), this.createId);
+        await this.store.write(migrated);
+        this.emitBoard(migrated);
+        this.migrationChecked = true;
+    }
+    emitBoard(board) {
+        this.emitChange({
+            scope: board.scope,
+            ...(board.sessionId === undefined ? {} : { sessionId: board.sessionId }),
+            board,
+        });
+    }
+    async removeDeletedAttachments(previous, next) {
+        const remaining = new Set(next.cards.flatMap((card) => card.logs.flatMap((log) => log.attachments.map((attachment) => attachment.id))));
+        const removed = previous.cards.flatMap((card) => card.logs.flatMap((log) => log.attachments)).filter((attachment) => !remaining.has(attachment.id));
+        for (const attachment of removed)
+            await this.store.removeAttachment(attachment.id, attachment.name);
+    }
+    enqueueMutation(work) {
+        const run = this.mutationChain.then(work, work);
+        this.mutationChain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+}
+function projectSessionBoard(global, sessionId) {
+    assertSessionId(sessionId);
+    const column = global.columns.find((item) => item.sessionId === sessionId);
+    return {
+        schemaVersion: 1,
+        id: `session:${sessionId}`,
+        scope: 'session',
+        sessionId,
+        title: 'Session',
+        columns: column === undefined ? [] : [{ ...structuredClone(column), order: 0 }],
+        cards: column === undefined ? [] : global.cards.filter((card) => card.columnId === column.id).map((card) => structuredClone(card)),
+        revision: global.revision,
+        updatedAt: global.updatedAt,
+        sessionColumnsMigrated: true,
+    };
+}
+function applySessionMutation(global, sessionId, op, now, createId) {
+    const ownedColumn = global.columns.find((column) => column.sessionId === sessionId);
+    if (op.type === 'addColumn') {
+        if (ownedColumn !== undefined)
+            throw new BoardOpError('this session already has its task column');
+        const existing = new Set(global.columns.map((column) => column.id));
+        const next = applyMutate(global, op, now, createId);
+        const created = next.columns.find((column) => !existing.has(column.id));
+        if (created === undefined)
+            throw new BoardOpError('failed to create session task column');
+        created.sessionId = sessionId;
+        return next;
+    }
+    if (ownedColumn === undefined)
+        throw new BoardOpError('this session has no task column; addColumn first');
+    const ownColumn = (columnId) => {
+        if (columnId !== ownedColumn.id)
+            throw new BoardOpError('session operations can only target this session task column');
+    };
+    const ownCard = (cardId) => {
+        const card = global.cards.find((item) => item.id === cardId);
+        if (card === undefined || card.columnId !== ownedColumn.id)
+            throw new BoardNotFoundError();
+    };
+    switch (op.type) {
+        case 'renameColumn':
+            ownColumn(op.columnId);
+            break;
+        case 'deleteColumn':
+            ownColumn(op.columnId);
+            break;
+        case 'reorderColumns': throw new BoardOpError('a session board has one fixed task column');
+        case 'addCard':
+            ownColumn(op.columnId);
+            break;
+        case 'updateCard':
+            ownCard(op.cardId);
+            break;
+        case 'addLog':
+            ownCard(op.cardId);
+            break;
+        case 'moveCard':
+            ownCard(op.cardId);
+            ownColumn(op.columnId);
+            break;
+        case 'archiveCard':
+            ownCard(op.cardId);
+            break;
+        case 'restoreCard':
+            ownCard(op.cardId);
+            ownColumn(op.columnId);
+            break;
+        case 'restoreCards':
+            for (const item of op.cards) {
+                ownCard(item.cardId);
+                ownColumn(item.columnId);
+            }
+            break;
+        case 'deleteCard':
+            ownCard(op.cardId);
+            break;
+        case 'deleteCards':
+            for (const cardId of op.cardIds)
+                ownCard(cardId);
+            break;
+        case 'setReminder':
+            ownCard(op.cardId);
+            break;
+        case 'clearReminder':
+            ownCard(op.cardId);
+            break;
+    }
+    return applyMutate(global, op, now, createId);
+}
+function mergeLegacySessionBoards(global, legacy, now, createId) {
+    const next = structuredClone(global);
+    const columnIds = new Set(next.columns.map((column) => column.id));
+    const cardIds = new Set(next.cards.map((card) => card.id));
+    const importedSessions = new Set(next.columns.flatMap((column) => column.sessionId === undefined ? [] : [column.sessionId]));
+    for (const session of [...legacy].sort((a, b) => a.sessionId.localeCompare(b.sessionId))) {
+        if (importedSessions.has(session.sessionId))
+            continue;
+        const columnId = nextUniqueId('col', columnIds, createId);
+        next.columns.push({ id: columnId, title: sessionColumnTitle(session.sessionId), order: next.columns.length, sessionId: session.sessionId });
+        importedSessions.add(session.sessionId);
+        const columnOrder = new Map(session.columns.map((column) => [column.id, column.order]));
+        const cards = [...session.cards].sort((a, b) => (columnOrder.get(a.columnId) ?? 0) - (columnOrder.get(b.columnId) ?? 0) || a.order - b.order);
+        cards.forEach((card, index) => {
+            const copy = structuredClone(card);
+            copy.id = nextUniqueId('card', cardIds, createId, copy.id);
+            copy.columnId = columnId;
+            copy.order = index;
+            next.cards.push(copy);
+        });
+    }
+    next.sessionColumnsMigrated = true;
+    next.revision += 1;
+    next.updatedAt = now.toISOString();
+    return next;
+}
+function nextUniqueId(kind, used, createId, preferred) {
+    let candidate = preferred ?? createId(kind);
+    if (used.has(candidate)) {
+        const base = createId(kind);
+        candidate = base;
+        let suffix = 2;
+        while (used.has(candidate))
+            candidate = `${base}_${String(suffix++)}`;
+    }
+    used.add(candidate);
+    return candidate;
+}
+function sessionColumnTitle(sessionId) {
+    const compact = sessionId.replace(/^session-/, '').slice(0, 8);
+    return `Session · ${compact}`;
+}
+/** Host service: `ctx.board` plus Typert SRC Remote (`board/getBoard`, `board/mutate`). */
+let BoardService = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _getBoard_decorators;
+    let _mutate_decorators;
+    return class BoardService extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _getBoard_decorators = [Remote];
+            _mutate_decorators = [Remote];
+            __esDecorate(this, null, _getBoard_decorators, { kind: "method", name: "getBoard", static: false, private: false, access: { has: obj => "getBoard" in obj, get: obj => obj.getBoard }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _mutate_decorators, { kind: "method", name: "mutate", static: false, private: false, access: { has: obj => "mutate" in obj, get: obj => obj.mutate }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        model = __runInitializers(this, _instanceExtraInitializers);
+        constructor(ctx, store, options = {}) {
+            super(ctx, 'board');
+            this.model = new BoardModel(store, {
+                ...options,
+                emit: (event) => {
+                    ctx.emit('board/changed', event);
+                    options.emit?.(event);
+                },
+            });
+        }
+        get wakeOnGlobalReminder() {
+            return this.model.wakeOnGlobalReminder;
+        }
+        list(callerSessionId) {
+            return this.model.list(callerSessionId);
+        }
+        getBoard(sessionId, scope, defaultColumns) {
+            return this.model.getBoard(sessionId, scope, defaultColumns);
+        }
+        getCard(sessionId, scope, cardId) {
+            return this.model.getCard(sessionId, scope, cardId);
+        }
+        mutate(sessionId, scope, op, revision) {
+            return this.model.mutate(sessionId, scope, op, revision);
+        }
+        addLog(sessionId, scope, cardId, text, attachments, revision) {
+            return this.model.addLog(sessionId, scope, cardId, text, attachments, revision);
+        }
+        getAttachment(sessionId, scope, cardId, attachmentId) {
+            return this.model.getAttachment(sessionId, scope, cardId, attachmentId);
+        }
+        openAttachment(sessionId, scope, cardId, attachmentId) {
+            return this.model.openAttachment(sessionId, scope, cardId, attachmentId);
+        }
+        fireDue() {
+            return this.model.fireDue();
+        }
+    };
+})();
+export { BoardService };
+function prepareAttachments(uploads, createId) {
+    if (uploads.length > 10)
+        throw new BoardOpError('a log supports at most 10 attachments');
+    return uploads.map((upload) => {
+        const name = upload.name.trim();
+        if (name.length === 0 || name.length > 255)
+            throw new BoardOpError('invalid attachment name');
+        if (typeof upload.type !== 'string' || typeof upload.data !== 'string')
+            throw new BoardOpError('invalid attachment');
+        const data = Buffer.from(upload.data, 'base64');
+        if (data.length > 50 * 1024 * 1024)
+            throw new BoardOpError('each attachment must be 50 MB or smaller');
+        if (upload.preview !== undefined && (!/^data:image\/(?:jpeg|png|webp);base64,/.test(upload.preview) || Buffer.byteLength(upload.preview, 'utf8') > 350 * 1024))
+            throw new BoardOpError('invalid attachment preview');
+        return { meta: { id: createId('attachment'), name, type: upload.type, size: data.length, ...(upload.preview === undefined ? {} : { preview: upload.preview }) }, data };
+    });
+}
+async function openWithSystem(path) {
+    const command = process.platform === 'win32' ? 'explorer.exe' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, [path], { detached: true, stdio: 'ignore' });
+        child.once('error', reject);
+        child.once('spawn', () => { child.unref(); resolve(); });
+    });
+}
+export function createBoardService(ctx, store, options = {}) {
+    return new BoardService(ctx, store, options);
+}

package/lib/store.d.ts

@@ -0,0 +1,22 @@
+import type { Board, BoardScope } from './domain.js';
+export declare function resolveDshHome(home?: string | undefined): string;
+export declare function resolveBoardRoot(home?: string | undefined): string;
+export declare class BoardStore {
+    readonly root: string;
+    private readonly chains;
+    private initialGlobalPromise;
+    constructor(root: string);
+    pathFor(scope: BoardScope, sessionId?: string): string;
+    read(scope: BoardScope, sessionId?: string, defaultColumns?: string[]): Promise<Board>;
+    writeAttachment(id: string, data: Buffer): Promise<void>;
+    readAttachment(id: string): Promise<Buffer>;
+    removeAttachment(id: string, name?: string): Promise<void>;
+    materializeAttachment(id: string, name: string): Promise<string>;
+    private attachmentPath;
+    private openAttachmentPath;
+    exists(scope: BoardScope, sessionId?: string): Promise<boolean>;
+    private initializeGlobal;
+    write(board: Board): Promise<void>;
+    readAll(defaultColumns?: string[]): Promise<Board[]>;
+    private enqueue;
+}

package/lib/store.js

@@ -0,0 +1,178 @@
+import { access, copyFile, mkdir, open, readFile, readdir, rename, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, extname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { assertSessionId, defaultGlobalBoard, emptyBoard, parseBoard } from './domain.js';
+export function resolveDshHome(home = process.env.DSH_HOME) {
+    if (home !== undefined && home.length > 0)
+        return home;
+    return join(homedir(), '.dsh');
+}
+export function resolveBoardRoot(home = process.env.DSH_HOME) {
+    return join(resolveDshHome(home), 'storages', 'board');
+}
+export class BoardStore {
+    root;
+    chains = new Map();
+    initialGlobalPromise = null;
+    constructor(root) {
+        this.root = root;
+    }
+    pathFor(scope, sessionId) {
+        if (scope === 'global')
+            return join(this.root, 'global.json');
+        if (sessionId === undefined)
+            throw new Error('session board path requires a session id');
+        assertSessionId(sessionId);
+        return join(this.root, 'sessions', `${sessionId}.json`);
+    }
+    async read(scope, sessionId, defaultColumns) {
+        const path = this.pathFor(scope, sessionId);
+        let text;
+        try {
+            text = await readFile(path, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                if (scope === 'global')
+                    return this.initializeGlobal(defaultColumns);
+                return emptyBoard(scope, sessionId);
+            }
+            throw error;
+        }
+        return parseBoard(JSON.parse(text));
+    }
+    async writeAttachment(id, data) {
+        const path = this.attachmentPath(id);
+        await this.enqueue(path, async () => {
+            await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+            await writeAtomic(path, data);
+        });
+    }
+    async readAttachment(id) {
+        return readFile(this.attachmentPath(id));
+    }
+    async removeAttachment(id, name) {
+        await rm(this.attachmentPath(id), { force: true });
+        if (name !== undefined)
+            await rm(this.openAttachmentPath(id, name), { force: true });
+    }
+    async materializeAttachment(id, name) {
+        const path = this.openAttachmentPath(id, name);
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        await copyFile(this.attachmentPath(id), path);
+        return path;
+    }
+    attachmentPath(id) {
+        if (!/^attachment_[A-Za-z0-9_-]+$/.test(id))
+            throw new Error('invalid attachment id');
+        return join(this.root, 'attachments', id);
+    }
+    openAttachmentPath(id, name) {
+        this.attachmentPath(id);
+        const extension = /^\.[A-Za-z0-9]{1,12}$/.test(extname(name)) ? extname(name) : '';
+        return join(this.root, 'open', `${id}${extension}`);
+    }
+    async exists(scope, sessionId) {
+        try {
+            await access(this.pathFor(scope, sessionId));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    initializeGlobal(defaultColumns) {
+        if (this.initialGlobalPromise === null) {
+            this.initialGlobalPromise = (async () => {
+                const board = defaultGlobalBoard(new Date(), undefined, defaultColumns);
+                await this.write(board);
+                return board;
+            })().finally(() => { this.initialGlobalPromise = null; });
+        }
+        return this.initialGlobalPromise;
+    }
+    async write(board) {
+        const path = this.pathFor(board.scope, board.sessionId);
+        await this.enqueue(path, async () => {
+            await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+            await chmodBestEffort(dirname(path), 0o700);
+            if (board.scope === 'session') {
+                await chmodBestEffort(this.root, 0o700);
+            }
+            await writeAtomic(path, `${JSON.stringify(board, null, 2)}\n`);
+        });
+    }
+    async readAll(defaultColumns) {
+        const boards = [await this.read('global', undefined, defaultColumns)];
+        let entries;
+        try {
+            entries = await readdir(join(this.root, 'sessions'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return boards;
+            throw error;
+        }
+        const sessionIds = entries.filter((name) => name.endsWith('.json')).map((name) => name.slice(0, -5));
+        for (const sessionId of sessionIds) {
+            try {
+                assertSessionId(sessionId);
+                boards.push(await this.read('session', sessionId));
+            }
+            catch {
+                // Ignore unrelated or invalid files in the private storage directory.
+            }
+        }
+        return boards;
+    }
+    enqueue(key, work) {
+        const previous = this.chains.get(key) ?? Promise.resolve();
+        const next = previous.then(work, work);
+        this.chains.set(key, next.catch(() => undefined));
+        return next;
+    }
+}
+async function writeAtomic(path, data) {
+    const tmp = join(dirname(path), `.${randomUUID()}.tmp`);
+    try {
+        const handle = await open(tmp, 'wx', 0o600);
+        try {
+            if (typeof data === 'string')
+                await handle.writeFile(data, 'utf8');
+            else
+                await handle.writeFile(data);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(tmp, path);
+        await chmodBestEffort(path, 0o600);
+        await fsyncDirectory(dirname(path));
+    }
+    catch (error) {
+        await rm(tmp, { force: true });
+        throw error;
+    }
+}
+async function fsyncDirectory(path) {
+    if (process.platform === 'win32')
+        return;
+    const handle = await open(path, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function chmodBestEffort(path, mode) {
+    try {
+        const { chmod } = await import('node:fs/promises');
+        await chmod(path, mode);
+    }
+    catch {
+        // Windows and some filesystems ignore POSIX modes.
+    }
+}

package/lib/tools.d.ts

@@ -0,0 +1,23 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+import type { Board } from './domain.js';
+export declare function registerBoardTools(ctx: Context): void;
+type SearchStatus = 'all' | 'active' | 'archived';
+type MatchField = 'title' | 'body' | 'log' | 'attachment' | 'column';
+export declare function searchBoard(board: Board, rawQuery: string, status?: SearchStatus, limit?: number): {
+    query: string;
+    total: number;
+    results: {
+        status: "active" | "archived";
+        archivedAt: string | null;
+        matchedIn: MatchField[];
+        preview: string;
+        sessionId?: string | undefined;
+        cardId: string;
+        title: string;
+        columnId: string;
+        columnTitle: string;
+    }[];
+};
+export declare function requireCallerSession(exec: ToolRunContext): string;
+export {};