soja-cli 1.4.0

package/dist/data/sync/engine.js

@@ -0,0 +1,459 @@
+import { randomUUID } from 'node:crypto';
+import { formatTaskRef, isProvisional, TASK_REF_PREFIX } from '../../domain/task.js';
+import { OfflineError } from '../remote/api-client.js';
+import { isChatOp } from './store.js';
+const BATCH = 100;
+const TASK_FIELDS = new Set(['title', 'description', 'projectId', 'type', 'priority', 'status', 'assigneeId', 'requester', 'branch', 'baseBranch', 'branchStart']);
+/** Server task view → stored task row (presentation fields are dropped by the store). */
+const toTask = (view) => view;
+const emptyReport = () => ({
+    online: true,
+    pushed: 0,
+    conflicts: 0,
+    rejected: 0,
+    chatRejected: 0,
+    deferred: 0,
+    pulledTasks: 0,
+    pulledMessages: 0,
+    changes: { taskRefs: [], projects: false, members: false, chatChannelIds: [], chatMessageChannelIds: [], chatReads: false },
+});
+function include(values, value) {
+    if (!values.includes(value))
+        values.push(value);
+}
+function taskIdOf(op) {
+    if (!op.taskId)
+        throw new Error(`Operation ${op.type} has no task.`);
+    return op.taskId;
+}
+/** `SOJA-?3` as written in text, not followed by more digits. */
+const provisionalRefPattern = (number) => new RegExp(`\\b${TASK_REF_PREFIX}-\\?${-number}(?!\\d)`, 'gi');
+/**
+ * A message that names a task created offline (`SOJA-?1`) waits until that
+ * task has its real number, so it reaches the server as `SOJA-7`. The batch
+ * stops before such a message when the task is created earlier in the batch.
+ */
+function sendable(batch) {
+    const provisional = new RegExp(`\\b${TASK_REF_PREFIX}-\\?\\d`, 'i');
+    let creates = false;
+    for (const [index, op] of batch.entries()) {
+        if (op.type === 'task.create')
+            creates = true;
+        else if (creates && isChatOp(op.type) && provisional.test(String(op.payload['body'] ?? '')))
+            return batch.slice(0, index);
+    }
+    return [...batch];
+}
+/**
+ * Keeps a workspace replica in step with the SOJA server (docs/SYNC.md in
+ * soja-backend): push the outbox, apply results, pull changes, re-apply
+ * what is still pending. One cycle at a time; failures leave the outbox
+ * intact for the next attempt.
+ */
+export class SyncEngine {
+    api;
+    store;
+    running = null;
+    queued = null;
+    online = null;
+    /** Called with null when a cycle starts and with its report when it ends. */
+    listeners = new Set();
+    constructor(api, store) {
+        this.api = api;
+        this.store = store;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    async status(workspaceId) {
+        const [pending, state] = await Promise.all([this.store.pending(workspaceId), this.store.state(workspaceId)]);
+        return { online: this.online, syncing: this.running !== null, pending: pending.length, lastSyncAt: state.lastSyncAt, lastError: state.lastError };
+    }
+    /** Downloads who you are and your workspaces. Needed before the first sync of a workspace. */
+    async refreshAccount() {
+        const me = await this.api.get('/v1/me');
+        await this.store.upsertUser(me.user);
+        for (const workspace of me.workspaces) {
+            await this.store.upsertWorkspace(workspace);
+            await this.store.upsertMember(workspace.id, { ...me.user, role: workspace.role });
+        }
+        this.online = true;
+        return me;
+    }
+    /**
+     * Runs one sync cycle. While one is running, a single follow-up cycle is
+     * queued (whatever was written meanwhile may have missed its push); every
+     * caller in between shares it. Never throws.
+     */
+    sync(workspaceId) {
+        if (this.running) {
+            this.queued ??= this.running.then(() => {
+                this.queued = null;
+                return this.sync(workspaceId);
+            });
+            return this.queued;
+        }
+        this.running = this.cycle(workspaceId).then((report) => {
+            this.running = null;
+            this.emit(report);
+            return report;
+        });
+        this.emit(null);
+        return this.running;
+    }
+    async cycle(workspaceId) {
+        const report = emptyReport();
+        let pushError = null;
+        try {
+            try {
+                await this.push(workspaceId, report);
+            }
+            catch (error) {
+                // Offline: nothing else will work either. A server error: still pull others' changes.
+                if (error instanceof OfflineError)
+                    throw error;
+                pushError = error;
+                await this.store.markAttempt(workspaceId, error instanceof Error ? error.message : String(error));
+            }
+            await this.pull(workspaceId, report);
+            await this.reapplyPending(workspaceId);
+            if (pushError)
+                throw pushError;
+            await this.store.saveState(workspaceId, { lastSyncAt: new Date(), lastError: null });
+            this.online = true;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.online = !(error instanceof OfflineError);
+            report.online = this.online;
+            report.error = message;
+            // Best effort: the replica may already be closed when a late cycle fails.
+            if (error !== pushError)
+                await this.store.markAttempt(workspaceId, message).catch(() => undefined);
+            await this.store.saveState(workspaceId, { lastError: message }).catch(() => undefined);
+            // Pending changes stay visible even when the pull could not run.
+            await this.reapplyPending(workspaceId).catch(() => undefined);
+        }
+        return report;
+    }
+    async push(workspaceId, report) {
+        for (;;) {
+            const batch = sendable((await this.store.pending(workspaceId)).slice(0, BATCH));
+            if (batch.length === 0)
+                return;
+            const { results } = await this.api.post(`/v1/workspaces/${workspaceId}/ops`, {
+                ops: batch.map((op) => ({
+                    opId: op.opId,
+                    type: op.type,
+                    ...(op.taskId ? { taskId: op.taskId } : {}),
+                    occurredAt: op.occurredAt.toISOString(),
+                    payload: op.payload,
+                    ...(op.base ? { base: op.base } : {}),
+                })),
+            });
+            const acknowledged = [];
+            const refresh = new Set();
+            let unanswered = 0;
+            for (const op of batch) {
+                const result = results.find((candidate) => candidate.opId === op.opId);
+                if (!result) {
+                    unanswered += 1;
+                    continue;
+                }
+                acknowledged.push(op.opId);
+                if (isChatOp(op.type)) {
+                    await this.chatResult(workspaceId, op, result, report);
+                    continue;
+                }
+                if (op.type === 'task.delete') {
+                    await this.deleteResult(workspaceId, op, result, report);
+                    continue;
+                }
+                if (result.status === 'applied' && result.task) {
+                    report.pushed += 1;
+                    include(report.changes.taskRefs, result.task.ref);
+                    const before = op.type === 'task.create' ? await this.store.findTask(taskIdOf(op)) : null;
+                    if (before)
+                        include(report.changes.taskRefs, formatTaskRef(before.number));
+                    await this.store.upsertTask(toTask(result.task));
+                    if (before && isProvisional(before.number) && !isProvisional(result.task.number)) {
+                        await this.renumberInChat(workspaceId, before.number, result.task.number, report);
+                    }
+                    for (const conflict of result.conflicts ?? []) {
+                        report.conflicts += 1;
+                        await this.store.addNotice(workspaceId, {
+                            id: randomUUID(),
+                            taskId: op.taskId,
+                            taskRef: result.task.ref,
+                            kind: 'conflict',
+                            field: conflict.field,
+                            overwritten: conflict.overwritten,
+                            message: `Your ${conflict.field} change on ${result.task.ref} replaced a newer value: ${describe(conflict.overwritten)}`,
+                        });
+                    }
+                }
+                else {
+                    report.rejected += 1;
+                    const task = await this.store.findTask(taskIdOf(op));
+                    await this.rejected(workspaceId, op, result, refresh);
+                    if (task)
+                        include(report.changes.taskRefs, formatTaskRef(task.number));
+                }
+            }
+            await this.store.acknowledge(acknowledged);
+            // Best effort: the rejection notice is already recorded; the next pull corrects the rest.
+            for (const taskId of refresh)
+                await this.refreshTask(workspaceId, taskId).catch(() => undefined);
+            // The server is pacing us (message rate limit): the rest waits for a later cycle.
+            if (unanswered > 0) {
+                report.deferred += unanswered;
+                return;
+            }
+        }
+    }
+    async chatResult(workspaceId, op, result, report) {
+        if (result.status === 'applied') {
+            if (result.message) {
+                await this.store.upsertMessage(result.message);
+                include(report.changes.chatMessageChannelIds, result.message.channelId);
+            }
+            if (result.read) {
+                await this.store.markRead(result.read.channelId, result.read.lastReadSeq);
+                report.changes.chatReads = true;
+                include(report.changes.chatChannelIds, result.read.channelId);
+            }
+            if (op.type !== 'channel.read')
+                report.pushed += 1;
+            return;
+        }
+        // A refused read mark changes nothing you can see.
+        if (op.type === 'channel.read')
+            return;
+        report.chatRejected += 1;
+        const messageId = String(op.payload['messageId'] ?? '');
+        const message = await this.store.findMessage(messageId);
+        const channel = message ? await this.store.findChannel(message.channelId) : null;
+        if (message)
+            include(report.changes.chatMessageChannelIds, message.channelId);
+        const where = channel ? `#${channel.name}` : 'the chat';
+        const reason = result.error?.message ?? 'rejected by the server';
+        const body = typeof op.payload['body'] === 'string' ? op.payload['body'] : null;
+        await this.store.addNotice(workspaceId, {
+            id: randomUUID(),
+            taskId: null,
+            taskRef: where,
+            kind: 'rejected',
+            field: 'chat',
+            // Your text, so the chat can give it back to you.
+            overwritten: body,
+            message: `${op.type === 'message.send' ? `Message to ${where} not sent` : `Change to a message in ${where} not applied`}: ${reason}`,
+        });
+        if (op.type === 'message.send')
+            await this.store.deleteMessage(messageId);
+        else if (message)
+            await this.refreshMessage(workspaceId, message).catch(() => undefined);
+    }
+    /** A refused delete (e.g. you are no longer an owner) brings the task back as the server has it. */
+    async deleteResult(workspaceId, op, result, report) {
+        const number = Number(op.payload['number']);
+        const ref = formatTaskRef(number);
+        if (result.status === 'applied') {
+            report.pushed += 1;
+            include(report.changes.taskRefs, ref);
+            return;
+        }
+        report.rejected += 1;
+        await this.store.addNotice(workspaceId, {
+            id: randomUUID(),
+            taskId: op.taskId,
+            taskRef: ref,
+            kind: 'rejected',
+            field: null,
+            overwritten: null,
+            message: `Could not delete ${ref}: ${result.error?.message ?? 'rejected by the server'}`,
+        });
+        if (!isProvisional(number)) {
+            await this.refreshTaskByRef(workspaceId, ref).catch(() => undefined);
+            include(report.changes.taskRefs, ref);
+        }
+    }
+    /** Reloads one message as the server has it (undoing a refused edit or delete). */
+    async refreshMessage(workspaceId, message) {
+        if (message.seq === null)
+            return;
+        const [server] = await this.api.get(`/v1/workspaces/${workspaceId}/channels/${message.channelId}/messages?before=${message.seq + 1}&limit=1`);
+        if (server?.id === message.id)
+            await this.store.upsertMessage(server);
+    }
+    /** Queued and unsent messages that named `SOJA-?n` now name the real task. */
+    async renumberInChat(workspaceId, provisional, number, report) {
+        const pattern = provisionalRefPattern(provisional);
+        const ref = formatTaskRef(number);
+        for (const op of await this.store.pending(workspaceId)) {
+            const body = op.payload['body'];
+            if (!isChatOp(op.type) || typeof body !== 'string' || !pattern.test(body))
+                continue;
+            pattern.lastIndex = 0;
+            await this.store.updateQueuedPayload(op.opId, { ...op.payload, body: body.replace(pattern, ref) });
+            const messageId = String(op.payload['messageId'] ?? '');
+            const message = await this.store.findMessage(messageId);
+            if (message && message.seq === null) {
+                await this.store.patchMessage(messageId, { body: body.replace(pattern, ref) });
+                include(report.changes.chatMessageChannelIds, message.channelId);
+            }
+        }
+    }
+    async rejected(workspaceId, op, result, refresh) {
+        const taskId = taskIdOf(op);
+        const task = await this.store.findTask(taskId);
+        const ref = task ? formatTaskRef(task.number) : 'a task';
+        await this.store.addNotice(workspaceId, {
+            id: randomUUID(),
+            taskId: op.type === 'task.create' ? null : taskId,
+            taskRef: ref,
+            kind: 'rejected',
+            field: null,
+            overwritten: null,
+            message: `${op.type === 'task.create' ? `Could not create ${ref}` : `A change to ${ref} was not applied`}: ${result.error?.message ?? 'rejected by the server'}`,
+        });
+        // A task the server never accepted must not linger; other rejections are undone by reloading the task.
+        if (op.type === 'task.create')
+            await this.store.deleteTask(taskId);
+        else
+            refresh.add(taskId);
+    }
+    async refreshTask(workspaceId, taskId) {
+        const task = await this.store.findTask(taskId);
+        if (!task || isProvisional(task.number))
+            return;
+        await this.refreshTaskByRef(workspaceId, formatTaskRef(task.number));
+    }
+    async refreshTaskByRef(workspaceId, ref) {
+        const details = await this.api.get(`/v1/workspaces/${workspaceId}/tasks/${ref}`);
+        await this.store.upsertTask(toTask(details.task));
+        for (const comment of details.comments)
+            await this.store.upsertComment(comment);
+        for (const activity of details.activity)
+            await this.store.upsertActivity(activity);
+    }
+    async pull(workspaceId, report) {
+        let { cursor } = await this.store.state(workspaceId);
+        for (;;) {
+            const batch = await this.api.get(`/v1/workspaces/${workspaceId}/changes?after=${cursor}&limit=500`);
+            for (const member of batch.members)
+                await this.store.upsertMember(workspaceId, member);
+            if (batch.members.length)
+                report.changes.members = true;
+            for (const project of batch.projects)
+                await this.store.upsertProject(project);
+            if (batch.projects.length)
+                report.changes.projects = true;
+            for (const task of batch.tasks) {
+                await this.store.upsertTask(toTask(task));
+                include(report.changes.taskRefs, task.ref);
+            }
+            for (const comment of batch.comments) {
+                await this.store.upsertComment(comment);
+                const task = await this.store.findTask(comment.taskId);
+                if (task)
+                    include(report.changes.taskRefs, formatTaskRef(task.number));
+            }
+            for (const activity of batch.activity) {
+                await this.store.upsertActivity(activity);
+                const task = await this.store.findTask(activity.taskId);
+                if (task)
+                    include(report.changes.taskRefs, formatTaskRef(task.number));
+            }
+            for (const channel of batch.channels ?? []) {
+                await this.store.upsertChannel(channel);
+                include(report.changes.chatChannelIds, channel.id);
+            }
+            for (const message of batch.messages ?? []) {
+                await this.store.upsertMessage(message);
+                include(report.changes.chatMessageChannelIds, message.channelId);
+            }
+            for (const read of batch.reads ?? []) {
+                await this.store.markRead(read.channelId, read.lastReadSeq);
+                report.changes.chatReads = true;
+                include(report.changes.chatChannelIds, read.channelId);
+            }
+            for (const taskId of batch.deletedTasks ?? []) {
+                const task = await this.store.findTask(taskId);
+                if (task)
+                    include(report.changes.taskRefs, formatTaskRef(task.number));
+                await this.store.deleteTask(taskId);
+            }
+            report.pulledTasks += batch.tasks.length;
+            report.pulledMessages += batch.messages?.length ?? 0;
+            cursor = batch.cursor;
+            await this.store.saveState(workspaceId, { cursor });
+            if (!batch.hasMore)
+                return;
+        }
+    }
+    /** Server rows may predate queued edits; put the queued field values back on top. */
+    async reapplyPending(workspaceId) {
+        for (const op of await this.store.pending(workspaceId)) {
+            const messageId = String(op.payload['messageId'] ?? '');
+            if (op.type === 'task.change') {
+                const fields = Object.fromEntries(Object.entries(op.payload).filter(([field]) => TASK_FIELDS.has(field)));
+                if (typeof op.payload['archived'] === 'boolean')
+                    fields.archivedAt = op.payload['archived'] ? op.occurredAt : null;
+                await this.store.patchTask(taskIdOf(op), fields);
+            }
+            else if (op.type === 'message.edit') {
+                await this.store.patchMessage(messageId, { body: String(op.payload['body'] ?? ''), editedAt: op.occurredAt });
+            }
+            else if (op.type === 'message.delete') {
+                await this.store.patchMessage(messageId, { body: '', deletedAt: op.occurredAt });
+            }
+        }
+    }
+    /**
+     * Applies a chat event from the live connection right away. Returns true
+     * when the caller should run a sync instead (the event only says "changed").
+     */
+    async receive(workspaceId, event) {
+        switch (event.type) {
+            case 'changes.available':
+                return true;
+            case 'message.created':
+            case 'message.updated':
+                if (event.message.workspaceId !== workspaceId)
+                    return false;
+                await this.store.upsertMessage(event.message);
+                break;
+            case 'channel.created':
+            case 'channel.updated':
+                if (event.channel.workspaceId !== workspaceId)
+                    return false;
+                await this.store.upsertChannel(event.channel);
+                break;
+        }
+        await this.reapplyPending(workspaceId);
+        this.online = true;
+        const report = { ...emptyReport(), live: true, pulledMessages: event.type.startsWith('message.') ? 1 : 0 };
+        switch (event.type) {
+            case 'message.created':
+            case 'message.updated':
+                include(report.changes.chatMessageChannelIds, event.message.channelId);
+                break;
+            case 'channel.created':
+            case 'channel.updated':
+                include(report.changes.chatChannelIds, event.channel.id);
+                break;
+        }
+        this.emit(report);
+        return false;
+    }
+    emit(report) {
+        for (const listener of this.listeners)
+            listener(report);
+    }
+}
+function describe(value) {
+    if (value === null || value === undefined || value === '')
+        return '(empty)';
+    return typeof value === 'string' ? `“${value}”` : JSON.stringify(value);
+}

package/dist/data/sync/importer.js

@@ -0,0 +1,156 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { openDatabase } from '../../database/client.js';
+import { runMigrations } from '../../database/migrate.js';
+import { NotFoundError, SojaError } from '../../domain/errors.js';
+import { OfflineError } from '../remote/api-client.js';
+import { createLocalRepositories } from '../local/index.js';
+/**
+ * Reads the local-mode database (`soja.db`) and sends its history to the
+ * SOJA server in one request (`POST /import`, soja-backend ≥ 1.0). The local
+ * database is only read, never changed.
+ */
+export class LocalImporter {
+    localFile;
+    config;
+    api;
+    store;
+    engine;
+    constructor(localFile, config, api, store, engine) {
+        this.localFile = localFile;
+        this.config = config;
+        this.api = api;
+        this.store = store;
+        this.engine = engine;
+    }
+    async preview(session, options = {}) {
+        return this.withLocal(async (repos) => {
+            const data = await this.collect(repos, options.from);
+            return {
+                from: { name: data.workspace.name, slug: data.workspace.slug },
+                projects: data.projects.length,
+                tasks: data.tasks.length,
+                comments: data.comments.length,
+                activity: data.activity.length,
+                developers: data.users.map((user) => user.username),
+                alreadyImported: await this.alreadyImported(session, data.workspace),
+            };
+        });
+    }
+    async run(session, options = {}) {
+        return this.withLocal(async (repos) => {
+            const data = await this.collect(repos, options.from);
+            let result;
+            try {
+                result = await this.api.post(`/v1/workspaces/${session.workspace.id}/import`, {
+                    importId: importId(data.workspace.id, session.workspace.id),
+                    users: data.users.map((user) => ({ localId: user.id, username: user.username })),
+                    projects: data.projects.map(({ id, name, key, description, repositoryUrl, createdAt, updatedAt }) => ({
+                        localId: id, name, key, description, repositoryUrl, createdAt, updatedAt,
+                    })),
+                    tasks: data.tasks.map((task) => ({
+                        localId: task.id, number: task.number, projectLocalId: task.projectId, title: task.title, description: task.description,
+                        type: task.type, priority: task.priority, status: task.status, assigneeLocalId: task.assigneeId, creatorLocalId: task.creatorId,
+                        requester: task.requester, branch: task.branch, baseBranch: task.baseBranch, branchStart: task.branchStart,
+                        createdAt: task.createdAt, updatedAt: task.updatedAt, startedAt: task.startedAt, completedAt: task.completedAt, archivedAt: task.archivedAt,
+                    })),
+                    comments: data.comments.map((comment) => ({
+                        taskLocalId: comment.taskId, userLocalId: comment.userId, body: comment.body, createdAt: comment.createdAt, updatedAt: comment.updatedAt,
+                    })),
+                    activity: data.activity.map((item) => ({
+                        taskLocalId: item.taskId, userLocalId: item.userId, type: item.type, metadata: item.metadata, createdAt: item.createdAt,
+                    })),
+                });
+            }
+            catch (error) {
+                if (error instanceof OfflineError) {
+                    throw new SojaError('Importing needs a connection to the SOJA server.', { hint: 'Nothing was sent; try again when you are online.', cause: error });
+                }
+                throw error;
+            }
+            const id = importId(data.workspace.id, session.workspace.id);
+            const current = this.config.load();
+            if (current?.remote) {
+                const imports = [...new Set([...(current.remote.imports ?? []), id])];
+                this.config.save({ ...current, remote: { ...current.remote, imports } });
+            }
+            await this.engine.sync(session.workspace.id);
+            // Folder links are per machine: carry this machine's over to the imported projects.
+            let linkedFolders = 0;
+            for (const project of data.projects) {
+                const serverId = result.projectIds[project.id];
+                if (!serverId || !project.repositoryPath)
+                    continue;
+                await this.store.setRepositoryPath(serverId, project.repositoryPath);
+                linkedFolders += 1;
+            }
+            return {
+                projects: result.projects,
+                tasks: result.tasks,
+                comments: result.comments,
+                activity: result.activity,
+                renumbered: result.renumbered,
+                unmatchedUsers: result.unmatchedUsers,
+                linkedFolders,
+            };
+        });
+    }
+    async collect(repos, from) {
+        const workspace = await this.localWorkspace(repos, from);
+        const [members, projects, tasks] = await Promise.all([
+            repos.workspaces.listMembers(workspace.id),
+            repos.projects.listByWorkspace(workspace.id),
+            repos.tasks.list({ workspaceId: workspace.id, archived: 'include' }),
+        ]);
+        const comments = (await Promise.all(tasks.map((task) => repos.comments.listByTask(task.id)))).flat();
+        const activity = (await Promise.all(tasks.map((task) => repos.activity.listByTask(task.id)))).flat();
+        // Creators or commenters who left the workspace still need a username to be matched.
+        const known = new Set(members.map((member) => member.id));
+        const others = new Set();
+        for (const task of tasks)
+            for (const id of [task.creatorId, task.assigneeId])
+                if (id && !known.has(id))
+                    others.add(id);
+        for (const comment of comments)
+            if (!known.has(comment.userId))
+                others.add(comment.userId);
+        const users = [...members, ...(await repos.users.findByIds([...others]))];
+        return { workspace, users, projects, tasks: tasks.filter((task) => task.number > 0), comments, activity };
+    }
+    async localWorkspace(repos, from) {
+        const config = this.config.load();
+        const workspace = from
+            ? ((await repos.workspaces.findBySlug(from)) ?? (await repos.workspaces.findById(from)))
+            : config?.workspaceId
+                ? await repos.workspaces.findById(config.workspaceId)
+                : null;
+        if (!workspace) {
+            throw new NotFoundError(from ? `There is no local workspace “${from}”.` : 'No local workspace to import.', {
+                hint: 'Name it with --from <slug>; `soja mode local` then `soja workspace list` shows them.',
+            });
+        }
+        return workspace;
+    }
+    async alreadyImported(session, workspace) {
+        // The server would answer a repeat with the first result anyway; this is only to warn before.
+        return (this.config.load()?.remote?.imports ?? []).includes(importId(workspace.id, session.workspace.id));
+    }
+    async withLocal(work) {
+        if (!existsSync(this.localFile)) {
+            throw new NotFoundError('There is no local SOJA data on this machine.', { hint: 'Nothing to import: local mode was never used here.' });
+        }
+        const handle = openDatabase(this.localFile);
+        try {
+            await runMigrations(handle);
+            return await work(createLocalRepositories(handle));
+        }
+        finally {
+            handle.close();
+        }
+    }
+}
+/** The same local workspace imported into the same server workspace always has the same id, so it never duplicates. */
+function importId(localWorkspaceId, serverWorkspaceId) {
+    const hex = createHash('sha256').update(`soja-import:${localWorkspaceId}:${serverWorkspaceId}`).digest('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}