soja-cli 1.4.0

package/dist/data/sync/index.js

@@ -0,0 +1,109 @@
+import { basename } from 'node:path';
+import { GitWorkflowService } from '../../application/services/git-workflow-service.js';
+import { FolderService } from '../../application/services/folder-service.js';
+import { ProjectService } from '../../application/services/project-service.js';
+import { TaskService } from '../../application/services/task-service.js';
+import { createLocalRepositories } from '../local/index.js';
+import { LiveConnection } from '../remote/live.js';
+import { ReplicaChatService } from './chat.js';
+import { LocalImporter } from './importer.js';
+import { SyncEngine } from './engine.js';
+import { ReplicaProjectService, ReplicaSessionService, ReplicaTaskService, ReplicaWorkspaceService } from './services.js';
+import { ReplicaStore } from './store.js';
+/** Replica file per server: `~/.local/share/soja/remote/<host>.db`. */
+export function replicaFile(dataDir, apiUrl) {
+    const host = new URL(apiUrl).host.replace(/[^a-z0-9.-]/gi, '_');
+    return `${dataDir}/remote/${basename(host)}.db`;
+}
+export function createReplicaServices(api, handle, config, git, gitConsole, WebSocketImpl, localDatabaseFile, backups) {
+    const repos = createLocalRepositories(handle);
+    const store = new ReplicaStore(handle.db);
+    const engine = new SyncEngine(api, store);
+    let timer = null;
+    let workspaceForTimer = null;
+    const scheduleSync = (workspaceId, delayMs = 800) => {
+        workspaceForTimer = workspaceId;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            if (workspaceForTimer)
+                void engine.sync(workspaceForTimer);
+        }, delayMs);
+        timer.unref(); // never keep a finished CLI command alive
+    };
+    const context = {
+        api,
+        store,
+        engine,
+        repos,
+        config,
+        onWrite: () => {
+            const workspaceId = config.load()?.remote?.workspaceId;
+            if (workspaceId)
+                scheduleSync(workspaceId);
+        },
+    };
+    const projects = new ReplicaProjectService(context, new ProjectService(repos, git));
+    const tasks = new ReplicaTaskService(context, new TaskService(repos));
+    // The server paced us (message rate limit): try the rest when its window has passed.
+    engine.subscribe((report) => {
+        const workspaceId = config.load()?.remote?.workspaceId;
+        if (report?.deferred && workspaceId)
+            scheduleSync(workspaceId, 10_000);
+    });
+    const connections = new Set();
+    const startLive = (workspaceId) => {
+        if (!api.token)
+            return () => undefined;
+        const live = new LiveConnection({
+            apiUrl: api.baseUrl,
+            token: api.token,
+            workspaceId,
+            ...(WebSocketImpl ? { WebSocket: WebSocketImpl } : {}),
+            onReady: () => void engine.sync(workspaceId),
+            onEvent: (event) => {
+                void engine.receive(workspaceId, event).then((needsSync) => {
+                    if (needsSync)
+                        scheduleSync(workspaceId, 150);
+                }, () => scheduleSync(workspaceId, 150));
+            },
+        });
+        connections.add(live);
+        live.start();
+        return () => {
+            connections.delete(live);
+            live.stop();
+        };
+    };
+    return {
+        session: new ReplicaSessionService(context),
+        workspaces: new ReplicaWorkspaceService(context),
+        projects,
+        tasks,
+        chat: new ReplicaChatService(context, tasks),
+        ...(localDatabaseFile ? { importer: new LocalImporter(localDatabaseFile, config, api, store, engine) } : {}),
+        git: new GitWorkflowService(tasks, projects, git),
+        folders: new FolderService(config),
+        gitConsole,
+        environment: { mode: 'remote', server: api.baseUrl },
+        backups,
+        sync: {
+            status: (workspaceId) => engine.status(workspaceId),
+            syncNow: (workspaceId) => engine.sync(workspaceId),
+            scheduleSync,
+            subscribe: (listener) => engine.subscribe(listener),
+            notices: (workspaceId, taskId) => store.notices(workspaceId, taskId),
+            dismissNotice: (id) => store.dismissNotice(id),
+            startLive,
+            stop: () => {
+                if (timer)
+                    clearTimeout(timer);
+                timer = null;
+                for (const live of connections)
+                    live.stop();
+                connections.clear();
+            },
+        },
+    };
+}

package/dist/data/sync/services.js

@@ -0,0 +1,263 @@
+import { randomUUID } from 'node:crypto';
+import { NotFoundError, SojaError, ValidationError } from '../../domain/errors.js';
+import { isClosed, formatTaskRef } from '../../domain/task.js';
+import { OfflineError } from '../remote/api-client.js';
+function settings(context) {
+    const remote = context.config.load()?.remote;
+    if (!remote)
+        throw new SojaError('No SOJA server configured.', { hint: 'Run `soja login --server <url>`.' });
+    return remote;
+}
+function saveSettings(context, patch) {
+    const current = context.config.load();
+    if (!current?.remote)
+        throw new SojaError('No SOJA server configured.', { hint: 'Run `soja login --server <url>`.' });
+    context.config.save({ ...current, remote: { ...current.remote, ...patch } });
+}
+/** Operations that change shared structure (projects, workspaces, members) need the server. */
+async function online(what, work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (error instanceof OfflineError) {
+            throw new SojaError(`${what} needs a connection to the SOJA server.`, {
+                hint: 'Tasks and comments work offline; projects, workspaces and members do not.',
+                cause: error,
+            });
+        }
+        throw error;
+    }
+}
+export class ReplicaSessionService {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    async user() {
+        const { userId } = settings(this.context);
+        const local = userId ? await this.context.repos.users.findById(userId) : null;
+        return local ?? (await this.context.engine.refreshAccount()).user;
+    }
+    /**
+     * The signed-in user and active workspace from the replica, so SOJA opens
+     * offline. The first run downloads them from the server.
+     */
+    async current() {
+        const remote = settings(this.context);
+        let user = remote.userId ? await this.context.repos.users.findById(remote.userId) : null;
+        let workspaces = user ? await this.context.repos.workspaces.listForUser(user.id) : [];
+        if (!user || workspaces.length === 0) {
+            const account = await this.context.engine.refreshAccount().catch((error) => {
+                if (error instanceof OfflineError) {
+                    throw new SojaError('SOJA needs to connect once to download your workspace.', {
+                        hint: 'Check your connection, or use `soja mode local`.',
+                        cause: error,
+                    });
+                }
+                throw error;
+            });
+            user = account.user;
+            workspaces = account.workspaces;
+            saveSettings(this.context, { userId: user.id });
+        }
+        const workspace = workspaces.find((candidate) => candidate.id === remote.workspaceId) ?? workspaces[0];
+        if (!workspace) {
+            throw new SojaError(`You have no workspaces on ${this.context.api.baseUrl} yet.`, {
+                hint: 'Create one with `soja workspace create "<name>"`, or ask an owner to add you.',
+            });
+        }
+        if (workspace.id !== remote.workspaceId)
+            saveSettings(this.context, { workspaceId: workspace.id });
+        return { user, workspace };
+    }
+    async setup() {
+        throw new SojaError('Remote mode has no local setup.', { hint: 'Sign in with `soja login --server <url>`.' });
+    }
+}
+export class ReplicaWorkspaceService {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    list(user) {
+        return this.context.repos.workspaces.listForUser(user.id);
+    }
+    async create(_owner, input) {
+        const workspace = await online('Creating a workspace', () => this.context.api.post('/v1/workspaces', input));
+        await this.context.engine.refreshAccount();
+        return workspace;
+    }
+    async switchTo(user, idOrSlug) {
+        let workspace = (await this.list(user)).find((candidate) => candidate.id === idOrSlug || candidate.slug === idOrSlug);
+        if (!workspace) {
+            const account = await online('Finding that workspace', () => this.context.engine.refreshAccount());
+            workspace = account.workspaces.find((candidate) => candidate.id === idOrSlug || candidate.slug === idOrSlug);
+        }
+        if (!workspace)
+            throw new NotFoundError(`You are not a member of a workspace called “${idOrSlug}”.`);
+        saveSettings(this.context, { workspaceId: workspace.id });
+        this.context.onWrite();
+        return { user, workspace };
+    }
+    async members(session) {
+        const members = await this.context.repos.workspaces.listMembers(session.workspace.id);
+        return members.map(({ id, username, displayName, role }) => ({ id, username, displayName, role }));
+    }
+    async findMember(session, username) {
+        const normalized = username.trim().replace(/^@/, '').toLowerCase();
+        const member = (await this.members(session)).find((candidate) => candidate.username === normalized);
+        if (!member)
+            throw new NotFoundError(`@${normalized} is not a member of ${session.workspace.name}.`);
+        return member;
+    }
+    async addMember(session, input) {
+        const member = await online('Adding a developer', () => this.context.api.post(`/v1/workspaces/${session.workspace.id}/members`, { username: input.username }));
+        await this.context.store.upsertMember(session.workspace.id, member);
+        return member;
+    }
+}
+export class ReplicaProjectService {
+    context;
+    local;
+    constructor(context, local) {
+        this.context = context;
+        this.local = local;
+    }
+    list(session) {
+        return this.local.list(session);
+    }
+    get(session, id) {
+        return this.local.get(session, id);
+    }
+    resolve(session, keyOrName) {
+        return this.local.resolve(session, keyOrName);
+    }
+    findByRepository(session, path) {
+        return this.local.findByRepository(session, path);
+    }
+    async create(session, input) {
+        const { repositoryPath, ...shared } = input;
+        const project = await online('Creating a project', () => this.context.api.post(`/v1/workspaces/${session.workspace.id}/projects`, shared));
+        await this.context.store.upsertProject(project);
+        const stored = await this.local.get(session, project.id);
+        return repositoryPath ? this.linkRepository(session, stored, repositoryPath) : stored;
+    }
+    /** The folder is stored in this machine's replica only; the origin URL is shared if the project had none. */
+    async linkRepository(session, project, path) {
+        const linked = await this.local.linkRepository(session, project, path);
+        if (!project.repositoryUrl && linked.repositoryUrl) {
+            await this.context.api
+                .patch(`/v1/workspaces/${session.workspace.id}/projects/${project.id}`, { repositoryUrl: linked.repositoryUrl })
+                .catch(() => undefined); // best effort: the URL is a convenience for teammates
+        }
+        return linked;
+    }
+    unlinkRepository(session, project) {
+        return this.local.unlinkRepository(session, project);
+    }
+    /** Shared with the team, so it needs the server (like creating one). */
+    async update(session, project, changes) {
+        const payload = Object.fromEntries(Object.entries(changes).filter(([, value]) => value !== undefined));
+        if (Object.keys(payload).length === 0)
+            return project;
+        const updated = await online('Editing a project', () => this.context.api.patch(`/v1/workspaces/${session.workspace.id}/projects/${project.id}`, payload));
+        await this.context.store.upsertProject(updated);
+        return this.local.get(session, project.id);
+    }
+}
+const CHANGE_FIELDS = ['title', 'description', 'projectId', 'type', 'priority', 'status', 'assigneeId', 'requester', 'branch', 'baseBranch', 'branchStart'];
+/**
+ * Tasks in remote mode: read and written in the local replica (instant, works
+ * offline), with every write queued as an operation for the server.
+ */
+export class ReplicaTaskService {
+    context;
+    local;
+    constructor(context, local) {
+        this.context = context;
+        this.local = local;
+    }
+    list(session, filter, options = {}) {
+        return this.local.list(session, filter, options);
+    }
+    search(session, text, limit) {
+        return this.local.search(session, text, limit);
+    }
+    get(session, target) {
+        return this.local.get(session, target);
+    }
+    knownRequesters(session) {
+        return this.local.knownRequesters(session);
+    }
+    async create(session, input) {
+        const id = randomUUID();
+        const number = await this.context.store.nextProvisionalNumber(session.workspace.id);
+        const task = await this.local.create(session, input, { id, number });
+        await this.enqueue(session, 'task.create', id, { ...input }, null);
+        return task;
+    }
+    async update(session, target, changes) {
+        const before = await this.find(session, target);
+        const payload = Object.fromEntries(Object.entries(changes).filter(([, value]) => value !== undefined));
+        const base = Object.fromEntries(CHANGE_FIELDS.filter((field) => field in payload).map((field) => [field, before[field]]));
+        return this.write(session, before, 'task.change', payload, base, () => this.local.update(session, before, changes));
+    }
+    start(session, target, extra = {}) {
+        return this.update(session, target, { assigneeId: session.user.id, status: 'in_progress', ...extra });
+    }
+    complete(session, target) {
+        return this.update(session, target, { status: 'done' });
+    }
+    archive(session, target) {
+        return this.update(session, target, { archived: true });
+    }
+    restore(session, target) {
+        return this.update(session, target, { archived: false });
+    }
+    /** Deletes here right away (owners only, checked on the replica and again on the server) and queues it. */
+    async remove(session, target) {
+        const removed = await this.local.remove(session, target);
+        await this.context.store.enqueue({ opId: randomUUID(), workspaceId: session.workspace.id, type: 'task.delete', taskId: removed.id, payload: { number: removed.number }, base: null, occurredAt: new Date() }, []);
+        this.context.onWrite();
+        return removed;
+    }
+    async reopen(session, target) {
+        const task = await this.find(session, target);
+        if (!isClosed(task.status))
+            throw new ValidationError(`${formatTaskRef(task.number)} is already open.`);
+        return this.update(session, task, { status: 'todo' });
+    }
+    async comment(session, target, body) {
+        const task = await this.find(session, target);
+        const commentId = randomUUID();
+        await this.write(session, task, 'task.comment', { commentId, body }, null, async () => {
+            await this.local.comment(session, task, body, { id: commentId });
+        });
+    }
+    async recordGitEvent(session, target, event, fields = {}) {
+        const task = await this.find(session, target);
+        return this.write(session, task, 'task.git_event', { event, fields }, null, () => this.local.recordGitEvent(session, task, event, fields));
+    }
+    /** Applies locally, remembers which activity rows were optimistic, then queues the operation. */
+    async write(session, task, type, payload, base, apply) {
+        const before = await this.context.store.activityIds(task.id);
+        const result = await apply();
+        const after = await this.context.store.activityIds(task.id);
+        const optimistic = [...after].filter((id) => !before.has(id));
+        // Nothing changed locally (e.g. same value again): nothing to tell the server.
+        if (type === 'task.change' && optimistic.length === 0)
+            return result;
+        await this.context.store.enqueue({ opId: randomUUID(), workspaceId: session.workspace.id, type, taskId: task.id, payload, base, occurredAt: new Date() }, optimistic);
+        this.context.onWrite();
+        return result;
+    }
+    async enqueue(session, type, taskId, payload, base) {
+        const optimistic = await this.context.store.activityIds(taskId);
+        await this.context.store.enqueue({ opId: randomUUID(), workspaceId: session.workspace.id, type, taskId, payload, base, occurredAt: new Date() }, optimistic);
+        this.context.onWrite();
+    }
+    async find(session, target) {
+        return this.local.get(session, target);
+    }
+}

package/dist/data/sync/store.js

@@ -0,0 +1,200 @@
+import { and, asc, eq, inArray, like } from 'drizzle-orm';
+import { chatChannels, chatMessages, chatReads, projects, syncNotices, syncOutbox, syncPendingActivity, syncState, taskActivity, taskComments, tasks, users, workspaceMembers, workspaces, } from '../../database/schema.js';
+export const isChatOp = (type) => !type.startsWith('task.');
+/** Task fields as stored; server views carry extra presentation fields we drop. */
+const TASK_COLUMNS = [
+    'id', 'number', 'workspaceId', 'projectId', 'title', 'description', 'type', 'priority', 'status', 'assigneeId',
+    'creatorId', 'requester', 'branch', 'baseBranch', 'branchStart', 'createdAt', 'updatedAt', 'startedAt', 'completedAt', 'archivedAt',
+];
+const pickTask = (task) => Object.fromEntries(TASK_COLUMNS.map((column) => [column, task[column]]));
+/**
+ * The remote-mode replica: server state mirrored into the same SQLite schema
+ * local mode uses, plus the outbox of operations not yet acknowledged.
+ */
+export class ReplicaStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    // ── Server state ─────────────────────────────────────────────────────────
+    async upsertUser(user) {
+        const now = new Date();
+        const row = { id: user.id, username: user.username, displayName: user.displayName, email: user.email ?? null, createdAt: user.createdAt ?? now, updatedAt: user.updatedAt ?? now };
+        await this.db.insert(users).values(row).onConflictDoUpdate({ target: users.id, set: { username: row.username, displayName: row.displayName } });
+    }
+    async upsertWorkspace(workspace) {
+        const row = { id: workspace.id, name: workspace.name, slug: workspace.slug, description: workspace.description, createdAt: workspace.createdAt, updatedAt: workspace.updatedAt };
+        await this.db.insert(workspaces).values(row).onConflictDoUpdate({ target: workspaces.id, set: { name: row.name, slug: row.slug, description: row.description, updatedAt: row.updatedAt } });
+    }
+    async upsertMember(workspaceId, member) {
+        await this.upsertUser(member);
+        await this.db
+            .insert(workspaceMembers)
+            .values({ workspaceId, userId: member.id, role: member.role })
+            .onConflictDoUpdate({ target: [workspaceMembers.workspaceId, workspaceMembers.userId], set: { role: member.role } });
+    }
+    /** Server projects have no local path; the one this machine linked is kept. */
+    async upsertProject(project) {
+        const shared = {
+            workspaceId: project.workspaceId, name: project.name, key: project.key, description: project.description,
+            repositoryUrl: project.repositoryUrl, createdAt: project.createdAt, updatedAt: project.updatedAt,
+        };
+        await this.db.insert(projects).values({ id: project.id, ...shared, repositoryPath: null }).onConflictDoUpdate({ target: projects.id, set: shared });
+    }
+    /** This machine's folder for a project (never sent to the server). */
+    async setRepositoryPath(projectId, path) {
+        await this.db.update(projects).set({ repositoryPath: path }).where(eq(projects.id, projectId));
+    }
+    async upsertTask(task) {
+        const row = pickTask(task);
+        // The server's number may belong to a provisional row we replaced; numbers are unique per workspace.
+        const clash = await this.db.select({ id: tasks.id }).from(tasks).where(and(eq(tasks.workspaceId, row.workspaceId), eq(tasks.number, row.number))).get();
+        if (clash && clash.id !== row.id)
+            await this.db.delete(tasks).where(eq(tasks.id, clash.id));
+        const { id: _id, ...rest } = row;
+        await this.db.insert(tasks).values(row).onConflictDoUpdate({ target: tasks.id, set: rest });
+    }
+    async upsertComment(comment) {
+        const { id: _id, ...rest } = comment;
+        await this.db.insert(taskComments).values(comment).onConflictDoUpdate({ target: taskComments.id, set: rest });
+    }
+    async upsertActivity(activity) {
+        await this.db
+            .insert(taskActivity)
+            .values({ id: activity.id, taskId: activity.taskId, userId: activity.userId, type: activity.type, metadata: activity.metadata, createdAt: activity.createdAt })
+            .onConflictDoNothing();
+    }
+    async patchTask(id, fields) {
+        if (Object.keys(fields).length === 0)
+            return;
+        await this.db.update(tasks).set(fields).where(eq(tasks.id, id));
+    }
+    async deleteTask(id) {
+        await this.db.delete(taskActivity).where(eq(taskActivity.taskId, id));
+        await this.db.delete(taskComments).where(eq(taskComments.taskId, id));
+        await this.db.delete(tasks).where(eq(tasks.id, id));
+    }
+    async findTask(id) {
+        return (await this.db.select().from(tasks).where(eq(tasks.id, id)).get()) ?? null;
+    }
+    async activityIds(taskId) {
+        const rows = await this.db.select({ id: taskActivity.id }).from(taskActivity).where(eq(taskActivity.taskId, taskId));
+        return new Set(rows.map((row) => row.id));
+    }
+    /** Next provisional number: -1, -2, … (shown as SOJA-?1, SOJA-?2). */
+    async nextProvisionalNumber(workspaceId) {
+        const rows = await this.db.select({ number: tasks.number }).from(tasks).where(eq(tasks.workspaceId, workspaceId));
+        return Math.min(0, ...rows.map((row) => row.number)) - 1;
+    }
+    // ── Outbox ───────────────────────────────────────────────────────────────
+    async enqueue(op, optimisticActivity) {
+        await this.db.insert(syncOutbox).values({ ...op, attempts: 0, lastError: null });
+        for (const activityId of optimisticActivity) {
+            await this.db.insert(syncPendingActivity).values({ activityId, opId: op.opId }).onConflictDoNothing();
+        }
+    }
+    async pending(workspaceId) {
+        const rows = await this.db.select().from(syncOutbox).where(eq(syncOutbox.workspaceId, workspaceId)).orderBy(asc(syncOutbox.seq));
+        return rows.map((row) => ({ ...row, type: row.type }));
+    }
+    /** Drops acknowledged operations and the optimistic activity they wrote (the server's arrives by pull). */
+    async acknowledge(opIds) {
+        if (opIds.length === 0)
+            return;
+        const optimistic = await this.db.select().from(syncPendingActivity).where(inArray(syncPendingActivity.opId, [...opIds]));
+        if (optimistic.length) {
+            await this.db.delete(taskActivity).where(inArray(taskActivity.id, optimistic.map((row) => row.activityId)));
+            await this.db.delete(syncPendingActivity).where(inArray(syncPendingActivity.opId, [...opIds]));
+        }
+        await this.db.delete(syncOutbox).where(inArray(syncOutbox.opId, [...opIds]));
+    }
+    async markAttempt(workspaceId, error) {
+        const rows = await this.pending(workspaceId);
+        for (const row of rows) {
+            await this.db.update(syncOutbox).set({ attempts: row.attempts + 1, lastError: error }).where(eq(syncOutbox.opId, row.opId));
+        }
+    }
+    // ── Cursor and notices ───────────────────────────────────────────────────
+    async state(workspaceId) {
+        const row = await this.db.select().from(syncState).where(eq(syncState.workspaceId, workspaceId)).get();
+        return { cursor: row?.cursor ?? 0, lastSyncAt: row?.lastSyncAt ?? null, lastError: row?.lastError ?? null };
+    }
+    async saveState(workspaceId, patch) {
+        const current = await this.state(workspaceId);
+        const row = { workspaceId, cursor: patch.cursor ?? current.cursor, lastSyncAt: patch.lastSyncAt ?? current.lastSyncAt, lastError: patch.lastError === undefined ? current.lastError : patch.lastError };
+        await this.db.insert(syncState).values(row).onConflictDoUpdate({ target: syncState.workspaceId, set: row });
+    }
+    async addNotice(workspaceId, notice) {
+        await this.db.insert(syncNotices).values({ ...notice, workspaceId, createdAt: new Date() }).onConflictDoNothing();
+    }
+    async notices(workspaceId, taskId) {
+        const rows = await this.db.select().from(syncNotices).where(eq(syncNotices.workspaceId, workspaceId)).orderBy(asc(syncNotices.createdAt));
+        return rows
+            .filter((row) => row.dismissedAt === null && (!taskId || row.taskId === taskId))
+            .map(({ workspaceId: _ws, dismissedAt: _dismissed, ...notice }) => notice);
+    }
+    async dismissNotice(id) {
+        await this.db.update(syncNotices).set({ dismissedAt: new Date() }).where(eq(syncNotices.id, id));
+    }
+    // ── Chat ─────────────────────────────────────────────────────────────────
+    async upsertChannel(channel) {
+        const row = pickChannel(channel);
+        const { id: _id, ...rest } = row;
+        await this.db.insert(chatChannels).values(row).onConflictDoUpdate({ target: chatChannels.id, set: rest });
+    }
+    async channels(workspaceId) {
+        return this.db.select().from(chatChannels).where(eq(chatChannels.workspaceId, workspaceId)).orderBy(asc(chatChannels.name));
+    }
+    async findChannel(id) {
+        return (await this.db.select().from(chatChannels).where(eq(chatChannels.id, id)).get()) ?? null;
+    }
+    async upsertMessage(message) {
+        const row = pickMessage(message);
+        const { id: _id, ...rest } = row;
+        await this.db.insert(chatMessages).values(row).onConflictDoUpdate({ target: chatMessages.id, set: rest });
+    }
+    async patchMessage(id, fields) {
+        await this.db.update(chatMessages).set(fields).where(eq(chatMessages.id, id));
+    }
+    async deleteMessage(id) {
+        await this.db.delete(chatMessages).where(eq(chatMessages.id, id));
+    }
+    async findMessage(id) {
+        return (await this.db.select().from(chatMessages).where(eq(chatMessages.id, id)).get()) ?? null;
+    }
+    async messagesIn(channelId) {
+        return this.db.select().from(chatMessages).where(eq(chatMessages.channelId, channelId));
+    }
+    /** Messages whose text contains `fragment` (a cheap prefilter; callers check the exact match). */
+    async messagesContaining(workspaceId, fragment) {
+        return this.db
+            .select()
+            .from(chatMessages)
+            .where(and(eq(chatMessages.workspaceId, workspaceId), like(chatMessages.body, `%${fragment.replace(/[%_]/g, '')}%`)));
+    }
+    async reads() {
+        const rows = await this.db.select().from(chatReads);
+        return new Map(rows.map((row) => [row.channelId, row.lastReadSeq]));
+    }
+    /** Read marks only move forward, as on the server. */
+    async markRead(channelId, lastReadSeq) {
+        const current = (await this.reads()).get(channelId) ?? 0;
+        if (lastReadSeq <= current)
+            return;
+        await this.db.insert(chatReads).values({ channelId, lastReadSeq }).onConflictDoUpdate({ target: chatReads.channelId, set: { lastReadSeq } });
+    }
+    /** Drops a queued operation that was never sent (e.g. an older read mark superseded by a newer one). */
+    async dropQueued(opId) {
+        await this.db.delete(syncOutbox).where(eq(syncOutbox.opId, opId));
+    }
+    async updateQueuedPayload(opId, payload) {
+        await this.db.update(syncOutbox).set({ payload }).where(eq(syncOutbox.opId, opId));
+    }
+}
+const CHANNEL_COLUMNS = ['id', 'workspaceId', 'name', 'topic', 'createdBy', 'createdAt', 'updatedAt', 'archivedAt'];
+const MESSAGE_COLUMNS = [
+    'id', 'seq', 'workspaceId', 'channelId', 'authorId', 'body', 'replyToId', 'createdAt', 'editedAt', 'deletedAt',
+];
+/** Server views may carry extra fields (e.g. `lastReadSeq` on channels). */
+const pickChannel = (channel) => Object.fromEntries(CHANNEL_COLUMNS.map((column) => [column, channel[column] ?? null]));
+const pickMessage = (message) => Object.fromEntries(MESSAGE_COLUMNS.map((column) => [column, message[column] ?? null]));

package/dist/database/client.js

@@ -0,0 +1,76 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { drizzle } from 'drizzle-orm/sqlite-proxy';
+import { StorageError } from '../domain/errors.js';
+import * as schema from './schema.js';
+/**
+ * Opens SQLite through Node's built-in `node:sqlite` and exposes it to
+ * Drizzle via the async proxy driver. Being async on the Drizzle side keeps
+ * repository signatures identical to a future HTTP-backed implementation.
+ */
+export function openDatabase(file, options = {}) {
+    let sqlite;
+    try {
+        if (file !== ':memory:')
+            mkdirSync(dirname(file), { recursive: true });
+        sqlite = new DatabaseSync(file);
+        // The remote-mode replica mirrors the server, which enforces integrity; rows may arrive in any order.
+        sqlite.exec(`PRAGMA foreign_keys = ${options.foreignKeys === false ? 'OFF' : 'ON'}; PRAGMA busy_timeout = 5000;`);
+        if (file !== ':memory:')
+            sqlite.exec('PRAGMA journal_mode = WAL;');
+    }
+    catch (error) {
+        throw new StorageError(`Could not open the database at ${file}.`, {
+            hint: 'Check that the directory exists and is writable.',
+            cause: error,
+        });
+    }
+    const statements = new Map();
+    const prepare = (sql) => {
+        let statement = statements.get(sql);
+        if (!statement) {
+            statement = sqlite.prepare(sql);
+            statements.set(sql, statement);
+        }
+        return statement;
+    };
+    const db = drizzle(async (sql, params, method) => {
+        try {
+            const statement = prepare(sql);
+            if (method === 'run') {
+                statement.run(...params);
+                return { rows: [] };
+            }
+            // Drizzle's proxy protocol expects positional rows (arrays), not objects.
+            statement.setReturnArrays(true);
+            if (method === 'get') {
+                // For `get`, `rows` is the single row itself, and "no row" must be
+                // `undefined` (an empty array would map to an all-undefined object).
+                // Drizzle's callback type does not model that, hence the casts.
+                const row = statement.get(...params);
+                return { rows: row };
+            }
+            return { rows: statement.all(...params) };
+        }
+        catch (error) {
+            throw new StorageError('The database rejected the operation.', { cause: error });
+        }
+    }, { schema });
+    return {
+        db,
+        exec: (sql) => sqlite.exec(sql),
+        backupTo: (file) => {
+            try {
+                sqlite.prepare('VACUUM INTO ?').run(file);
+            }
+            catch (error) {
+                throw new StorageError(`Could not write the backup to ${file}.`, { hint: 'Check that the folder is writable and has space.', cause: error });
+            }
+        },
+        close: () => {
+            if (sqlite.isOpen)
+                sqlite.close();
+        },
+    };
+}

package/dist/database/migrate.js

@@ -0,0 +1,27 @@
+import { fileURLToPath } from 'node:url';
+import { migrate } from 'drizzle-orm/sqlite-proxy/migrator';
+import { StorageError } from '../domain/errors.js';
+// Shipped next to this module in both src/ (tsx) and dist/ (copied at build).
+const MIGRATIONS_FOLDER = fileURLToPath(new URL('./migrations', import.meta.url));
+/** Applies pending migrations in a single transaction. Cheap when there is nothing to do. */
+export async function runMigrations(handle) {
+    try {
+        await migrate(handle.db, async (queries) => {
+            if (queries.length === 0)
+                return;
+            handle.exec('BEGIN');
+            try {
+                for (const query of queries)
+                    handle.exec(query);
+                handle.exec('COMMIT');
+            }
+            catch (error) {
+                handle.exec('ROLLBACK');
+                throw error;
+            }
+        }, { migrationsFolder: MIGRATIONS_FOLDER });
+    }
+    catch (error) {
+        throw new StorageError('Could not upgrade the database schema.', { cause: error });
+    }
+}