om-memory-system 5.5.0 → 5.7.0-next.218

package/dist/services/space-transfer-routes.js

@@ -0,0 +1,344 @@
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import * as config from "../config.js";
+import { log } from "./logger.js";
+import { packageVersion } from "./package-version.js";
+import { getUserTagInfo } from "./tags.js";
+import { STATUS_BY_CODE } from "./space-routes.js";
+import { exportSpace } from "./spaces/export-space.js";
+import { IMPORT_MAX_FILE_BYTES, importSpace, validateSpaceImportDocument, } from "./spaces/import-space.js";
+import { SpaceError, findSpace, readRegistryFile, resolveSpaceFolder, spaceLinks, } from "./spaces/registry.js";
+import { linkStoredSpace, spaceFiles, unlinkStoredSpace, } from "./spaces/registry-store.js";
+import { ommsHomeDir } from "./spaces/storage-resolution.js";
+import { applySpaceTransfer, previewSpaceTransfer, } from "./spaces/transfer-service.js";
+const ok = (data) => ({
+    status: 200,
+    body: { success: true, data },
+});
+const fail = (status, code, error) => ({
+    status,
+    body: { success: false, code, error },
+});
+/** A refusal the handler wants mapped to a status and code, like a bad date. */
+class RouteError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+/** The service refusals of `transfer-service.ts`, as HTTP statuses. */
+const STATUS_BY_REFUSAL = {
+    "unknown-space": 404,
+    "same-space": 400,
+    "archived-space": 409,
+    "registry-problem": 500,
+};
+/** The JSON envelope around the uploaded file (name, folder) may add this much. */
+const IMPORT_ENVELOPE_BYTES = 64 * 1024;
+/** The import cap of the spec, enforced on the raw request body. */
+const IMPORT_BODY_CAP = IMPORT_MAX_FILE_BYTES + IMPORT_ENVELOPE_BYTES;
+/** One transfer apply at a time per process (design D4); previews run freely. */
+let applyInFlight = false;
+function embeddingSettings() {
+    return {
+        model: config.CONFIG.embeddingModel,
+        dimensions: config.CONFIG.embeddingDimensions,
+    };
+}
+function transferContext(files, deps) {
+    const { storagePath, skillStoragePath, maxVectorsPerShard } = config.CONFIG;
+    return {
+        files,
+        paths: { globalStoragePath: skillStoragePath ?? storagePath, spacesRoot: files.spacesRoot },
+        embedding: embeddingSettings(),
+        maxVectorsPerShard,
+        ...(deps?.embed ? { embed: deps.embed } : {}),
+    };
+}
+function defaultEmbed(text) {
+    return import("./embedding.js").then(({ embeddingService }) => embeddingService.embedWithTimeout(text, { task: "document" }));
+}
+/** The importing user: user-scope memories take this user's container tag. */
+function importingUser(cwd) {
+    const info = getUserTagInfo(cwd);
+    return {
+        userTag: info.tag,
+        ...(info.displayName ? { displayName: info.displayName } : {}),
+        ...(info.userName ? { userName: info.userName } : {}),
+        ...(info.userEmail ? { userEmail: info.userEmail } : {}),
+    };
+}
+async function readJson(req) {
+    return (await req.json().catch(() => ({})));
+}
+/**
+ * Reads one import body under the spec's 100 MB cap. The only body limit the
+ * web server has lives here, scoped to the import routes.
+ */
+async function readCappedJson(req) {
+    const declared = Number(req.headers.get("content-length"));
+    if (declared > IMPORT_BODY_CAP) {
+        throw new RouteError(413, "file-too-large", `The upload is larger than the import limit of ${IMPORT_MAX_FILE_BYTES} bytes.`);
+    }
+    const text = await req.text();
+    if (Buffer.byteLength(text, "utf-8") > IMPORT_BODY_CAP) {
+        throw new RouteError(413, "file-too-large", `The upload is larger than the import limit of ${IMPORT_MAX_FILE_BYTES} bytes.`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new RouteError(400, "invalid-file", "The request body is not valid JSON.");
+    }
+}
+/** One date field: absent, epoch milliseconds, or an ISO 8601 string. */
+function dateMs(body, field) {
+    const value = body[field];
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    const parsed = typeof value === "number" ? value : Date.parse(String(value));
+    if (!Number.isFinite(parsed)) {
+        throw new RouteError(400, "invalid-date", `"${field}" must be a date or epoch milliseconds.`);
+    }
+    return parsed;
+}
+/** The transfer filter: the whole history by default, one project tag at most. */
+function filterFrom(body) {
+    const projects = body.projects;
+    let projectTag;
+    if (Array.isArray(projects)) {
+        if (projects.length > 1) {
+            throw new RouteError(400, "invalid", "Filter by one project or by none.");
+        }
+        projectTag = typeof projects[0] === "string" ? projects[0] : undefined;
+    }
+    else if (typeof projects === "string" && projects) {
+        projectTag = projects;
+    }
+    return {
+        since: dateMs(body, "since") ?? 0,
+        until: dateMs(body, "until") ?? Number.MAX_SAFE_INTEGER,
+        ...(projectTag ? { projectTag } : {}),
+    };
+}
+function endpoints(body) {
+    const from = body.from;
+    const to = body.to;
+    if (typeof from !== "string" || !from.trim() || typeof to !== "string" || !to.trim()) {
+        throw new RouteError(400, "invalid", '"from" and "to" must name two spaces.');
+    }
+    return { from: from.trim(), to: to.trim() };
+}
+function transferRefusal(code, error) {
+    return fail(STATUS_BY_REFUSAL[code], code, error);
+}
+/** The download file name of one export: `omms-space-export-<id>-<timestamp>.json`. */
+function exportFileName(spaceId) {
+    const stamp = new Date().toISOString().replaceAll(":", "-").replaceAll(".", "-");
+    return `omms-space-export-${spaceId}-${stamp}.json`;
+}
+async function handleExport(id, req) {
+    const files = spaceFiles(ommsHomeDir());
+    const read = readRegistryFile(files.registryPath);
+    const space = findSpace(read.registry, id);
+    if (!space)
+        return fail(404, "unknown", `No space named "${id}".`);
+    const body = await readJson(req);
+    const { storagePath, skillStoragePath } = config.CONFIG;
+    // One name for the file, the header and the clean-up, so all three agree.
+    const fileName = exportFileName(space.id);
+    const outPath = join(tmpdir(), fileName);
+    const since = dateMs(body, "since");
+    const until = dateMs(body, "until");
+    try {
+        const result = await exportSpace({
+            folder: resolveSpaceFolder(space.id, {
+                globalStoragePath: skillStoragePath ?? storagePath,
+                spacesRoot: files.spacesRoot,
+            }),
+            outPath,
+            ...(since !== undefined ? { since } : {}),
+            ...(until !== undefined ? { until } : {}),
+            includeProfile: body.includeProfile === true,
+            embeddingModel: config.CONFIG.embeddingModel,
+            embeddingDimensions: config.CONFIG.embeddingDimensions,
+            ommsVersion: packageVersion(),
+            homePath: homedir(),
+        });
+        if (!result.written)
+            return ok(result);
+        // The bytes the CLI would write go out unchanged, as an attachment.
+        const bytes = readFileSync(outPath);
+        return {
+            status: 200,
+            body: undefined,
+            response: new Response(new Uint8Array(bytes), {
+                headers: {
+                    "content-type": "application/json",
+                    "content-disposition": `attachment; filename="${fileName}"`,
+                    "x-omms-export-info": JSON.stringify({
+                        counts: result.counts,
+                        warnings: result.warnings,
+                    }),
+                },
+            }),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "The export failed.";
+        return fail(500, "export-failed", message);
+    }
+    finally {
+        if (existsSync(outPath))
+            unlinkSync(outPath);
+    }
+}
+async function handleImportCheck(req, cwd) {
+    const body = await readCappedJson(req);
+    if (body.document === undefined) {
+        return fail(400, "invalid-file", "No export document was given.");
+    }
+    const validated = validateSpaceImportDocument(body.document, embeddingSettings(), importingUser(cwd).userTag);
+    if (!validated.ok)
+        return fail(400, "invalid-file", validated.reason);
+    const projects = [];
+    for (const memory of validated.document.memories) {
+        if (memory.scope === "project" && memory.projectTag && !projects.includes(memory.projectTag)) {
+            projects.push(memory.projectTag);
+        }
+    }
+    return ok({
+        counts: validated.counts,
+        projects,
+        // Structured, so the dialog composes its localised warning (web spec: every
+        // string exists in en, zh and ar). `warning` stays for non-UI callers.
+        embedding: {
+            fileModel: validated.document.embedding.model,
+            fileDimensions: validated.document.embedding.dimensions,
+            currentModel: config.CONFIG.embeddingModel,
+            currentDimensions: config.CONFIG.embeddingDimensions,
+        },
+        ...(validated.warning ? { warning: validated.warning } : {}),
+    });
+}
+async function handleImport(req, cwd, deps) {
+    const files = spaceFiles(ommsHomeDir());
+    const body = await readCappedJson(req);
+    if (body.document === undefined) {
+        return fail(400, "invalid-file", "No export document was given.");
+    }
+    const name = typeof body.name === "string" ? body.name.trim() : "";
+    if (!name)
+        return fail(400, "invalid", "A name for the new space is required.");
+    // Precise refusals first, so no space is ever created for a bad request.
+    const validated = validateSpaceImportDocument(body.document, embeddingSettings(), importingUser(cwd).userTag);
+    if (!validated.ok)
+        return fail(400, "invalid-file", validated.reason);
+    if (findSpace(readRegistryFile(files.registryPath).registry, name)) {
+        return fail(409, "name-taken", `A space named "${name}" already exists.`);
+    }
+    const retagToProject = typeof body.retagToProject === "string" && body.retagToProject.trim()
+        ? body.retagToProject.trim()
+        : undefined;
+    if (retagToProject !== undefined && !existsSync(retagToProject)) {
+        return fail(400, "missing-folder", `The project folder "${retagToProject}" does not exist, so no space was created.`);
+    }
+    const result = await importSpace({
+        document: body.document,
+        spaceName: name,
+        files,
+        ...(retagToProject !== undefined ? { retagToProject } : {}),
+        embedding: embeddingSettings(),
+        embed: deps?.embed ?? defaultEmbed,
+        user: importingUser(cwd),
+    });
+    if (!result.ok)
+        return fail(400, "import-failed", result.reason ?? "The import failed.");
+    return ok(result);
+}
+async function handleLinks(id, req) {
+    const files = spaceFiles(ommsHomeDir());
+    const body = await readJson(req);
+    const add = typeof body.add === "string" && body.add.trim() ? body.add.trim() : undefined;
+    const remove = typeof body.remove === "string" && body.remove.trim() ? body.remove.trim() : undefined;
+    if ((add !== undefined) === (remove !== undefined)) {
+        return fail(400, "invalid", 'Give either "add" or "remove", naming one space.');
+    }
+    if (add)
+        await linkStoredSpace(files, id, add);
+    else
+        await unlinkStoredSpace(files, id, remove);
+    return ok({ links: spaceLinks(readRegistryFile(files.registryPath).registry, id) });
+}
+async function dispatch(path, req, cwd, deps) {
+    if (path === "/api/spaces/transfer/preview") {
+        const body = await readJson(req);
+        const { from, to } = endpoints(body);
+        const outcome = await previewSpaceTransfer({ from, to, filter: filterFrom(body) }, transferContext(spaceFiles(ommsHomeDir()), deps));
+        if (!outcome.ok)
+            return transferRefusal(outcome.code, outcome.error);
+        return ok({ preview: outcome.preview });
+    }
+    if (path === "/api/spaces/transfer") {
+        const body = await readJson(req);
+        const { from, to } = endpoints(body);
+        if (body.mode !== "copy" && body.mode !== "move") {
+            return fail(400, "invalid", '"mode" must be "copy" or "move".');
+        }
+        if (body.confirm !== true) {
+            return fail(400, "confirm-required", "Set confirm to true to run the transfer.");
+        }
+        if (applyInFlight) {
+            return fail(STATUS_BY_CODE["transfer-busy"], "transfer-busy", "Another transfer is running. Try again when it finishes.");
+        }
+        applyInFlight = true;
+        try {
+            const outcome = await applySpaceTransfer({
+                from,
+                to,
+                filter: filterFrom(body),
+                mode: body.mode,
+                ...(typeof body.previewMatched === "number"
+                    ? { previewMatched: body.previewMatched }
+                    : {}),
+            }, transferContext(spaceFiles(ommsHomeDir()), deps));
+            if (!outcome.ok)
+                return transferRefusal(outcome.code, outcome.error);
+            return ok({ result: outcome.result });
+        }
+        finally {
+            applyInFlight = false;
+        }
+    }
+    const exported = /^\/api\/spaces\/([^/]+)\/export$/.exec(path);
+    if (exported)
+        return handleExport(decodeURIComponent(exported[1]), req);
+    if (path === "/api/spaces/import/check")
+        return handleImportCheck(req, cwd);
+    if (path === "/api/spaces/import")
+        return handleImport(req, cwd, deps);
+    const links = /^\/api\/spaces\/([^/]+)\/links$/.exec(path);
+    if (links)
+        return handleLinks(decodeURIComponent(links[1]), req);
+    return undefined;
+}
+export async function routeSpaceTransfers(path, method, req, cwd, deps) {
+    if (method !== "POST" || !path.startsWith("/api/spaces/"))
+        return undefined;
+    try {
+        return await dispatch(path, req, cwd, deps);
+    }
+    catch (error) {
+        if (error instanceof RouteError)
+            return fail(error.status, error.code, error.message);
+        if (error instanceof SpaceError) {
+            return fail(STATUS_BY_CODE[error.code] ?? 400, error.code, error.message);
+        }
+        log("space transfer route: error", { path, name: error instanceof Error ? error.name : typeof error }, "error");
+        return fail(500, "error", error instanceof Error ? error.message : "Request failed");
+    }
+}

package/dist/services/spaces/active-space.js

@@ -1,23 +1,30 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { log } from "../logger.js";
 import { DEFAULT_SPACE_ID, DEFAULT_SPACE_NAME, findSpace, readRegistryFile, resolveSpaceFolder, } from "./registry.js";
 /**
  * Picks the active space for config loading (design D2). Reads paths from arguments
  * and never imports CONFIG. A problem always falls back to the Default space.
  */
 export function resolveActiveSpace(ommsDir, globalStoragePath, projectSetsStoragePath) {
-    const fallback = (problem) => ({
-        id: DEFAULT_SPACE_ID,
-        name: DEFAULT_SPACE_NAME,
-        customStoragePath: projectSetsStoragePath,
-        problem,
-    });
+    const fallback = (problem, name = DEFAULT_SPACE_NAME) => {
+        // The spec wants an unusable registry named in the log, not only in the web status.
+        if (problem)
+            log("Active space fallback to Default", { problem }, "warn");
+        return {
+            id: DEFAULT_SPACE_ID,
+            name,
+            customStoragePath: projectSetsStoragePath,
+            problem,
+        };
+    };
     const { registry, problem } = readRegistryFile(join(ommsDir, "spaces.json"));
     if (problem)
         return fallback(problem);
     const space = findSpace(registry, registry.activeSpaceId);
+    // Default may carry a custom registry name; an unreadable registry stays "Default" (D4).
     if (!space || space.id === DEFAULT_SPACE_ID)
-        return fallback();
+        return fallback(undefined, space?.name);
     if (projectSetsStoragePath) {
         return { id: space.id, name: space.name, customStoragePath: true };
     }

package/dist/services/spaces/delete.d.ts

@@ -5,6 +5,8 @@ export interface DeleteDeps {
     /** Replaced in tests only. */
     backup: typeof backupSpace;
     removeFolder(folder: string): void;
+    /** Releases the cached read store before the folder goes (design D2, Windows-safe). */
+    closeReadStore(folder: string): Promise<void>;
 }
 export interface DeleteResult {
     backupPath: string;

package/dist/services/spaces/delete.js

@@ -1,11 +1,13 @@
 import { rmSync } from "node:fs";
 import { join } from "node:path";
 import { backupSpace } from "./backup.js";
+import { closeCachedSpaceReadStore } from "./read-store-cache.js";
 import { SpaceError, findSpace, readRegistryFile, removeSpace, } from "./registry.js";
 import { removeStoredSpace } from "./registry-store.js";
 const defaultDeps = {
     backup: backupSpace,
     removeFolder: (folder) => rmSync(folder, { recursive: true, force: false }),
+    closeReadStore: (folder) => closeCachedSpaceReadStore(folder),
 };
 /**
  * Deletes a space (design D8): a verified backup first, then the registry entry, then the folder.
@@ -31,6 +33,8 @@ export async function deleteSpace(files, idOrName, options, overrides = {}) {
     });
     await removeStoredSpace(files, checked.id);
     try {
+        // A linked search may still hold the folder open through the cached read store.
+        await deps.closeReadStore(folder);
         deps.removeFolder(folder);
         return { backupPath, space: checked };
     }

package/dist/services/spaces/export-space.d.ts

@@ -0,0 +1,60 @@
+/** What the caller passes in; nothing is read from CONFIG here (pattern of live-model-choice.ts). */
+export interface ExportSpaceOptions {
+    /** The space folder to read. Read-only: the space is never changed. */
+    folder: string;
+    /** Where the JSON file is written, atomically. The caller picks the path. */
+    outPath: string;
+    /** Inclusive lower bound on the memory creation time, in epoch milliseconds. */
+    since?: number;
+    /** Inclusive upper bound on the memory creation time, in epoch milliseconds. */
+    until?: number;
+    /** Opt-in that adds the user-scope memories and the learned profile. */
+    includeProfile?: boolean;
+    /** Recorded in the file so an import can warn on a model mismatch. */
+    embeddingModel: string;
+    embeddingDimensions: number;
+    /** The OMMS version recorded in the file. */
+    ommsVersion: string;
+    /** The exporting user's home folder, checked by the final identifier scan. */
+    homePath: string;
+}
+/** Totals of one export, for the CLI and web dialogs to report. */
+export interface ExportSpaceCounts {
+    /** Project-scope memories written to the file. */
+    projectMemories: number;
+    /** User-scope memories written to the file (opt-in only). */
+    userMemories: number;
+    /** Memories left out because they are fully private. */
+    privateSkipped: number;
+    /** Profile items written to the file (opt-in only). */
+    profileItems: number;
+    /** Home-folder paths the scrubber rewrote, across the whole file. */
+    pathsReplaced: number;
+    /** Email addresses the scrubber rewrote, across the whole file. */
+    emailsReplaced: number;
+}
+export interface ExportSpaceResult {
+    /** False when the selection held no memory: no file was written. */
+    written: boolean;
+    /** Why nothing was written; set only when `written` is false. */
+    reason?: string;
+    /** Absolute path of the written file; set only when `written` is true. */
+    outputPath?: string;
+    counts: ExportSpaceCounts;
+    /** Human-facing notes, always including the free-text-names limit. */
+    warnings: string[];
+}
+/** The version of this OMMS build, read from package.json; "unknown" when unreadable. */
+export declare function getOmmsVersion(): string;
+/**
+ * The final safety scan (design D7): fail the export when a home-folder path
+ * or an email address survived the per-string scrubbing. System paths and
+ * URLs are deliberate non-matches, because memories often quote them.
+ */
+export declare function scanExportContent(serialised: string, homePath: string): void;
+/**
+ * Export one space to a JSON file (design D7). Reads the space through a
+ * read-only store, so the space is never changed. Throws when the final
+ * identifier scan fails; returns `written: false` for an empty selection.
+ */
+export declare function exportSpace(options: ExportSpaceOptions): Promise<ExportSpaceResult>;