om-memory-system 5.4.1 → 5.5.0

package/dist/services/memory-host-routes.js

@@ -1,6 +1,8 @@
 import { join } from "node:path";
 import { HostAppearanceError, createHostAppearance } from "./host-appearance.js";
 const instances = new Map();
+/** Host icons are global: a memory space switch must not hide them (ADR-041). */
+const globalFolder = (config) => config.skillStoragePath ?? config.storagePath;
 function appearanceFor(storagePath) {
     const directory = join(storagePath, "host-appearance");
     let appearance = instances.get(directory);
@@ -27,12 +29,12 @@ export async function routeMemoryHosts(path, method, url, readBody, config) {
         return { status: 200, body: await checkWriteHealth(url.searchParams.get("fresh") === "1") };
     }
     if (path === "/api/host-appearance" && method === "GET") {
-        return { status: 200, body: { hosts: await appearanceFor(config.storagePath).read() } };
+        return { status: 200, body: { hosts: await appearanceFor(globalFolder(config)).read() } };
     }
     const host = /^\/api\/host-appearance\/([^/]+)$/.exec(path)?.[1];
     if (!host)
         return undefined;
-    const appearance = appearanceFor(config.storagePath);
+    const appearance = appearanceFor(globalFolder(config));
     try {
         if (method === "PUT") {
             const body = await readBody();

package/dist/services/space-routes.d.ts

@@ -0,0 +1,16 @@
+import type { RouteResult } from "./chat/chat-routes.js";
+/**
+ * `/api/spaces` routes (design D10). The web app is the only surface that can delete, rename, back
+ * up or restore a space. Every change goes through the registry writer, then this process
+ * refreshes its config so the web app itself serves the new space on the next request.
+ */
+type Body = Record<string, unknown>;
+/** What the status call reports: the space this process uses now. */
+export declare function spaceStatus(directory: string): {
+    problem?: string | undefined;
+    id: string;
+    name: string;
+    customStoragePath: boolean;
+};
+export declare function routeSpaces(path: string, method: string, readBody: () => Promise<Body>, cwd: string): Promise<RouteResult | undefined>;
+export {};

package/dist/services/space-routes.js

@@ -0,0 +1,222 @@
+import { basename } from "node:path";
+import * as config from "../config.js";
+import { HostAppearanceError, createAppearance } from "./host-appearance.js";
+import { log } from "./logger.js";
+import { packageVersion } from "./package-version.js";
+import { backupSpace } from "./spaces/backup.js";
+import { deleteSpace } from "./spaces/delete.js";
+import { folderSize } from "./spaces/folder-size.js";
+import { DEFAULT_SPACE_ID, SpaceError, findSpace, listSpaces, isValidSpaceId, readRegistryFile, removeSpace, resolveSpaceFolder, } from "./spaces/registry.js";
+import { archiveStoredSpace, createStoredSpace, renameStoredSpace, spaceFiles, switchStoredSpace, unarchiveStoredSpace, } from "./spaces/registry-store.js";
+import { listBackups, restoreBackup } from "./spaces/restore.js";
+import { ommsHomeDir } from "./spaces/storage-resolution.js";
+const ok = (data) => ({ status: 200, body: { success: true, data } });
+const fail = (status, code, error) => ({
+    status,
+    body: { success: false, code, error },
+});
+const STATUS_BY_CODE = {
+    "invalid-name": 400,
+    "invalid-id": 400,
+    reserved: 400,
+    unknown: 404,
+    "name-taken": 409,
+    "id-taken": 409,
+    protected: 409,
+    active: 409,
+    archived: 409,
+    "not-archived": 409,
+    unreadable: 500,
+    "lock-timeout": 503,
+};
+/** What the status call reports: the space this process uses now. */
+export function spaceStatus(directory) {
+    config.refreshConfigIfChanged(directory);
+    const { id, name, customStoragePath, problem } = config.getActiveSpace();
+    return { id, name, customStoragePath, ...(problem ? { problem } : {}) };
+}
+/** Why an action is blocked for a space, as a code the page translates. Absent when allowed. */
+function disabledReasons(space, activeId) {
+    const isDefault = space.id === DEFAULT_SPACE_ID;
+    const isActive = space.id === activeId;
+    const reason = (blocked, code) => (blocked ? code : undefined);
+    const disabled = {
+        rename: reason(isDefault, "default"),
+        archive: isDefault ? "default" : reason(isActive, "active"),
+        delete: isDefault ? "default" : reason(isActive, "active"),
+        switch: space.archived ? "archived" : reason(isActive, "active"),
+    };
+    return Object.fromEntries(Object.entries(disabled).filter(([, code]) => code !== undefined));
+}
+/** The icon store of the spaces. A space id is checked first, so a path cannot leave the folder. */
+function appearanceOf(files) {
+    return createAppearance(files.appearanceRoot, isValidSpaceId, "Unknown space");
+}
+function describeSpaces(files, registry, globalFolder, looks) {
+    return listSpaces(registry).map((space) => ({
+        look: looks[space.id] ?? { kind: "default" },
+        id: space.id,
+        name: space.name,
+        createdAt: space.createdAt || null,
+        archived: space.archived,
+        archivedAt: space.archivedAt ?? null,
+        active: space.id === registry.activeSpaceId,
+        sizeBytes: folderSize(resolveSpaceFolder(space.id, {
+            globalStoragePath: globalFolder,
+            spacesRoot: files.spacesRoot,
+        })),
+        disabled: disabledReasons(space, registry.activeSpaceId),
+    }));
+}
+function describeBackup(path, summary) {
+    return {
+        folder: basename(path),
+        path,
+        spaceId: summary.spaceId,
+        spaceName: summary.spaceName,
+        createdAt: summary.createdAt,
+        sizeBytes: summary.sizeBytes,
+        fileCount: summary.fileCount,
+    };
+}
+async function snapshot(files, cwd) {
+    config.refreshConfigIfChanged(cwd);
+    const { registry, problem } = readRegistryFile(files.registryPath);
+    const { storagePath, skillStoragePath } = config.CONFIG;
+    // Default's folder is the global one, even while a space or a project folder is in use.
+    const globalFolder = skillStoragePath ?? storagePath;
+    const looks = await appearanceOf(files).read(listSpaces(registry).map((space) => space.id));
+    return {
+        activeSpaceId: registry.activeSpaceId,
+        current: spaceStatus(cwd),
+        spaces: describeSpaces(files, registry, globalFolder, looks),
+        backups: listBackups(files.backupsRoot).map((summary) => describeBackup(summary.path, summary)),
+        ...(problem ? { problem } : {}),
+    };
+}
+function nameOf(body) {
+    return typeof body.name === "string" ? body.name : "";
+}
+export async function routeSpaces(path, method, readBody, cwd) {
+    if (path !== "/api/spaces" && !path.startsWith("/api/spaces/"))
+        return undefined;
+    const files = spaceFiles(ommsHomeDir());
+    try {
+        return await dispatch(path, method, readBody, cwd, files);
+    }
+    catch (error) {
+        if (error instanceof SpaceError) {
+            return fail(STATUS_BY_CODE[error.code] ?? 400, error.code, error.message);
+        }
+        if (error instanceof HostAppearanceError)
+            return fail(error.status, "invalid", error.message);
+        log("spaces route: error", { method, name: error instanceof Error ? error.name : typeof error }, "error");
+        return fail(500, "error", error instanceof Error ? error.message : "Spaces request failed");
+    }
+}
+async function dispatch(path, method, readBody, cwd, files) {
+    if (path === "/api/spaces" && method === "GET")
+        return ok(await snapshot(files, cwd));
+    if (path === "/api/spaces" && method === "POST") {
+        const space = await createStoredSpace(files, nameOf(await readBody()));
+        return ok({ space: { id: space.id, name: space.name } });
+    }
+    if (path === "/api/spaces/backups/restore" && method === "POST") {
+        const wanted = (await readBody()).backup;
+        const backup = listBackups(files.backupsRoot).find((item) => typeof wanted === "string" && basename(item.path) === wanted);
+        if (!backup)
+            return fail(404, "unknown-backup", "That backup is not in the backups folder.");
+        const space = await restoreBackup(files, backup.path);
+        return ok({ space: { id: space.id, name: space.name } });
+    }
+    const icon = /^\/api\/spaces\/([^/]+)\/appearance$/.exec(path);
+    if (icon && (method === "PUT" || method === "DELETE")) {
+        const space = requireSpace(files, decodeURIComponent(icon[1]));
+        const appearance = appearanceOf(files);
+        if (method === "DELETE")
+            await appearance.reset(space.id);
+        else {
+            const body = await readBody();
+            if (body.kind === "icon")
+                await appearance.setIcon(space.id, body.icon);
+            else if (body.kind === "image")
+                await appearance.setImage(space.id, body.png);
+            else
+                return fail(400, "invalid", "kind must be icon or image");
+        }
+        return ok({ look: (await appearance.read([space.id]))[space.id] });
+    }
+    const match = /^\/api\/spaces\/([^/]+)(?:\/(switch|rename|archive|unarchive|backup))?$/.exec(path);
+    if (!match)
+        return undefined;
+    const id = decodeURIComponent(match[1]);
+    const action = match[2];
+    if (action && method === "POST") {
+        if (action === "switch")
+            await switchStoredSpace(files, id);
+        else if (action === "archive")
+            await archiveStoredSpace(files, id);
+        else if (action === "unarchive")
+            await unarchiveStoredSpace(files, id);
+        else if (action === "rename")
+            await renameStoredSpace(files, id, nameOf(await readBody()));
+        else
+            return ok(await backUp(files, id));
+        config.refreshConfigIfChanged(cwd);
+        return ok({ activeSpaceId: readRegistryFile(files.registryPath).registry.activeSpaceId });
+    }
+    if (!action && method === "DELETE")
+        return remove(files, id, await readBody());
+    return undefined;
+}
+function globalFolder() {
+    return config.CONFIG.skillStoragePath ?? config.CONFIG.storagePath;
+}
+async function backUp(files, id) {
+    const space = requireSpace(files, id);
+    const { backupPath, manifest } = await backupSpace({
+        space,
+        spaceFolder: resolveSpaceFolder(space.id, {
+            globalStoragePath: globalFolder(),
+            spacesRoot: files.spacesRoot,
+        }),
+        backupsRoot: files.backupsRoot,
+        ommsVersion: packageVersion(),
+    });
+    return {
+        backup: describeBackup(backupPath, {
+            path: backupPath,
+            spaceId: space.id,
+            spaceName: space.name,
+            createdAt: manifest.createdAt,
+            fileCount: manifest.fileCount,
+            sizeBytes: manifest.files.reduce((total, file) => total + file.size, 0),
+        }),
+    };
+}
+function requireSpace(files, id) {
+    const space = findSpace(readRegistryFile(files.registryPath).registry, id);
+    if (!space)
+        throw new SpaceError("unknown", `No space named "${id}".`);
+    return space;
+}
+async function remove(files, id, body) {
+    const space = requireSpace(files, id);
+    // Refuses Default and the active space before the typed name is compared.
+    removeSpace(readRegistryFile(files.registryPath).registry, space.id);
+    if (body.confirmName !== space.name) {
+        return fail(400, "confirm-mismatch", "Type the space name to confirm the delete.");
+    }
+    const result = await deleteSpace(files, space.id, { ommsVersion: packageVersion() });
+    // The icon belongs to the space. A failed clean-up leaves a harmless file.
+    await appearanceOf(files)
+        .reset(space.id)
+        .catch(() => undefined);
+    const summary = listBackups(files.backupsRoot).find((item) => item.path === result.backupPath);
+    return ok({
+        backup: summary
+            ? describeBackup(result.backupPath, summary)
+            : { folder: basename(result.backupPath), path: result.backupPath },
+        ...(result.leftoverFolder ? { leftoverFolder: result.leftoverFolder } : {}),
+    });
+}

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

@@ -0,0 +1,16 @@
+/** Which space the process uses, and the storage folder that choice gives. */
+export interface ActiveSpace {
+    id: string;
+    name: string;
+    /** The space folder. Unset when the Default space or a project folder applies. */
+    storagePath?: string;
+    /** A project config sets its own `storagePath`, which wins over the active space. */
+    customStoragePath: boolean;
+    /** Why OMMS used Default although the registry named another space. */
+    problem?: string;
+}
+/**
+ * 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 declare function resolveActiveSpace(ommsDir: string, globalStoragePath: string, projectSetsStoragePath: boolean): ActiveSpace;

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

@@ -0,0 +1,32 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+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 { registry, problem } = readRegistryFile(join(ommsDir, "spaces.json"));
+    if (problem)
+        return fallback(problem);
+    const space = findSpace(registry, registry.activeSpaceId);
+    if (!space || space.id === DEFAULT_SPACE_ID)
+        return fallback();
+    if (projectSetsStoragePath) {
+        return { id: space.id, name: space.name, customStoragePath: true };
+    }
+    const folder = resolveSpaceFolder(space.id, {
+        globalStoragePath,
+        spacesRoot: join(ommsDir, "spaces"),
+    });
+    if (!existsSync(folder)) {
+        return fallback(`The folder of space "${space.name}" is missing; using the Default space.`);
+    }
+    return { id: space.id, name: space.name, storagePath: folder, customStoragePath: false };
+}

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

@@ -0,0 +1,52 @@
+import { type BackupManifestEntry } from "../legacy-migration.js";
+/**
+ * Space backups (design D6). A backup is a folder `space-<id>-<timestamp>` under the backups
+ * root. It holds a copy of every store file of the space and a `manifest.json` with the SHA-256
+ * of each copy. SQLite files are copied with `VACUUM INTO`, which gives one consistent snapshot
+ * while other connections write. Other files are copied byte for byte.
+ */
+export declare const MANIFEST_FILE = "manifest.json";
+export declare const SPACE_BACKUP_KIND = "space-backup";
+export declare const SPACE_BACKUP_PREFIX = "space-";
+export interface BackupManifest {
+    createdAt: string;
+    kind: string;
+    fileCount: number;
+    files: BackupManifestEntry[];
+}
+export interface SpaceBackupManifest extends BackupManifest {
+    kind: typeof SPACE_BACKUP_KIND;
+    spaceId: string;
+    spaceName: string;
+    ommsVersion: string;
+}
+export interface BackupDeps {
+    /** Writes a consistent copy of the SQLite file `source` to `destination`. */
+    vacuumInto(source: string, destination: string): Promise<void>;
+    copyFile(source: string, destination: string): void;
+}
+/** Writes `manifest.json` in a backup folder. */
+export declare function writeBackupManifest(backupRoot: string, manifest: object): void;
+/** Reads `manifest.json` from a backup folder. Throws a plain message when it is missing or invalid. */
+export declare function readBackupManifest(backupRoot: string): SpaceBackupManifest;
+/** Checks every file of a backup against its manifest. The error names the first damaged file. */
+export declare function verifyBackup(backupRoot: string, manifest: BackupManifest): void;
+export interface BackupInput {
+    space: {
+        id: string;
+        name: string;
+    };
+    /** The folder of the space to copy. */
+    spaceFolder: string;
+    backupsRoot: string;
+    ommsVersion: string;
+    now?: Date;
+}
+/**
+ * Backs up one space and verifies the copy. On any failure the incomplete backup folder is
+ * removed and the error names the file that failed. The space folder is never changed.
+ */
+export declare function backupSpace(input: BackupInput, overrides?: Partial<BackupDeps>): Promise<{
+    backupPath: string;
+    manifest: SpaceBackupManifest;
+}>;

package/dist/services/spaces/backup.js

@@ -0,0 +1,125 @@
+import { createClient } from "@libsql/client";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { sha256File, timestampSlug, verifyManifest, walkTree, } from "../legacy-migration.js";
+/**
+ * Space backups (design D6). A backup is a folder `space-<id>-<timestamp>` under the backups
+ * root. It holds a copy of every store file of the space and a `manifest.json` with the SHA-256
+ * of each copy. SQLite files are copied with `VACUUM INTO`, which gives one consistent snapshot
+ * while other connections write. Other files are copied byte for byte.
+ */
+export const MANIFEST_FILE = "manifest.json";
+export const SPACE_BACKUP_KIND = "space-backup";
+export const SPACE_BACKUP_PREFIX = "space-";
+/** Folders that hold no memory data: the model cache is shared, and lock files are transient. */
+const SKIPPED_FOLDERS = [".cache", ".write-locks"];
+/** Files SQLite keeps next to a database while it is open. `VACUUM INTO` makes them unnecessary. */
+const SKIPPED_SUFFIXES = ["-journal", "-wal", "-shm"];
+async function vacuumInto(source, destination) {
+    const client = createClient({ url: `file:${source}` });
+    try {
+        await client.execute("PRAGMA busy_timeout = 5000");
+        await client.execute({ sql: "VACUUM INTO ?", args: [destination] });
+    }
+    finally {
+        client.close();
+    }
+}
+const defaultDeps = { vacuumInto, copyFile: copyFileSync };
+/** Writes `manifest.json` in a backup folder. */
+export function writeBackupManifest(backupRoot, manifest) {
+    writeFileSync(join(backupRoot, MANIFEST_FILE), JSON.stringify(manifest, null, 2), "utf-8");
+}
+/** Reads `manifest.json` from a backup folder. Throws a plain message when it is missing or invalid. */
+export function readBackupManifest(backupRoot) {
+    const path = join(backupRoot, MANIFEST_FILE);
+    if (!existsSync(path))
+        throw new Error(`The backup has no ${MANIFEST_FILE}.`);
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        throw new Error(`The backup ${MANIFEST_FILE} cannot be read.`);
+    }
+    if (manifest.kind !== SPACE_BACKUP_KIND ||
+        typeof manifest.spaceId !== "string" ||
+        typeof manifest.spaceName !== "string" ||
+        !Array.isArray(manifest.files)) {
+        throw new Error("The folder is not a space backup.");
+    }
+    return manifest;
+}
+/** Checks every file of a backup against its manifest. The error names the first damaged file. */
+export function verifyBackup(backupRoot, manifest) {
+    verifyManifest(backupRoot, manifest.files);
+}
+function isStoreFile(relPath) {
+    const parts = relPath.split("/");
+    if (parts.some((part) => SKIPPED_FOLDERS.includes(part)))
+        return false;
+    return !SKIPPED_SUFFIXES.some((suffix) => relPath.endsWith(suffix));
+}
+function uniqueBackupFolder(backupsRoot, id, now) {
+    const base = join(backupsRoot, `${SPACE_BACKUP_PREFIX}${id}-${timestampSlug(now)}`);
+    for (let n = 1;; n++) {
+        const candidate = n === 1 ? base : `${base}-${n}`;
+        if (!existsSync(candidate))
+            return candidate;
+    }
+}
+/** Copies one file and checks the copy against its source, once more if the source moved on. */
+function copyChecked(deps, source, destination) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        deps.copyFile(source, destination);
+        if (sha256File(destination) === sha256File(source))
+            return;
+    }
+    throw new Error("the copy does not match the original");
+}
+/**
+ * Backs up one space and verifies the copy. On any failure the incomplete backup folder is
+ * removed and the error names the file that failed. The space folder is never changed.
+ */
+export async function backupSpace(input, overrides = {}) {
+    const deps = { ...defaultDeps, ...overrides };
+    const now = input.now ?? new Date();
+    mkdirSync(input.backupsRoot, { recursive: true });
+    const backupPath = uniqueBackupFolder(input.backupsRoot, input.space.id, now);
+    mkdirSync(backupPath);
+    let current = "";
+    try {
+        const files = [];
+        for (const rel of walkTree(input.spaceFolder).files.filter(isStoreFile)) {
+            current = rel;
+            const source = join(input.spaceFolder, rel);
+            const destination = join(backupPath, rel);
+            mkdirSync(dirname(destination), { recursive: true });
+            if (rel.endsWith(".db"))
+                await deps.vacuumInto(source, destination);
+            else
+                copyChecked(deps, source, destination);
+            files.push({ path: rel, size: statSync(destination).size, sha256: sha256File(destination) });
+        }
+        current = "";
+        const manifest = {
+            createdAt: now.toISOString(),
+            kind: SPACE_BACKUP_KIND,
+            spaceId: input.space.id,
+            spaceName: input.space.name,
+            ommsVersion: input.ommsVersion,
+            fileCount: files.length,
+            files,
+        };
+        writeBackupManifest(backupPath, manifest);
+        verifyBackup(backupPath, manifest);
+        return { backupPath, manifest };
+    }
+    catch (error) {
+        rmSync(backupPath, { recursive: true, force: true });
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Backup failed${current ? ` at ${current}` : ""}: ${reason}`, {
+            cause: error,
+        });
+    }
+}

package/dist/services/spaces/context-line.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The line that names the active memory space in every memory context block (design D9).
+ * Pi, OpenCode V2 and Claude Code all build their block in `formatContextForPrompt`, so one
+ * line serves the three hosts. A space name is user text, so it is cut to one line and
+ * stripped of angle brackets before it enters a model prompt.
+ */
+export declare function activeSpaceLine(space: {
+    name: string;
+    customStoragePath: boolean;
+}): string;

package/dist/services/spaces/context-line.js

@@ -0,0 +1,13 @@
+/**
+ * The line that names the active memory space in every memory context block (design D9).
+ * Pi, OpenCode V2 and Claude Code all build their block in `formatContextForPrompt`, so one
+ * line serves the three hosts. A space name is user text, so it is cut to one line and
+ * stripped of angle brackets before it enters a model prompt.
+ */
+export function activeSpaceLine(space) {
+    if (space.customStoragePath) {
+        return "Active memory space: custom storage folder set by this project";
+    }
+    const name = space.name.replace(/[<>]/g, "").replace(/\s+/g, " ").trim();
+    return `Active memory space: ${name}`;
+}

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

@@ -0,0 +1,22 @@
+import { backupSpace } from "./backup.js";
+import { type SpaceEntry } from "./registry.js";
+import { type SpaceFiles } from "./registry-store.js";
+export interface DeleteDeps {
+    /** Replaced in tests only. */
+    backup: typeof backupSpace;
+    removeFolder(folder: string): void;
+}
+export interface DeleteResult {
+    backupPath: string;
+    space: SpaceEntry;
+    /** Set when the registry entry is gone but the folder could not be removed. OMMS does not retry. */
+    leftoverFolder?: string;
+}
+/**
+ * Deletes a space (design D8): a verified backup first, then the registry entry, then the folder.
+ * The Default space and the active space are refused before anything is copied. Only the web app
+ * calls this. The CLI and the `memory` tool have no delete.
+ */
+export declare function deleteSpace(files: SpaceFiles, idOrName: string, options: {
+    ommsVersion: string;
+}, overrides?: Partial<DeleteDeps>): Promise<DeleteResult>;

package/dist/services/spaces/delete.js

@@ -0,0 +1,40 @@
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { backupSpace } from "./backup.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 }),
+};
+/**
+ * Deletes a space (design D8): a verified backup first, then the registry entry, then the folder.
+ * The Default space and the active space are refused before anything is copied. Only the web app
+ * calls this. The CLI and the `memory` tool have no delete.
+ */
+export async function deleteSpace(files, idOrName, options, overrides = {}) {
+    const deps = { ...defaultDeps, ...overrides };
+    const { registry, problem } = readRegistryFile(files.registryPath);
+    if (problem)
+        throw new SpaceError("unreadable", problem);
+    const space = findSpace(registry, idOrName);
+    if (!space)
+        removeSpace(registry, idOrName); // throws "unknown" with the list of spaces
+    const checked = space;
+    removeSpace(registry, checked.id); // throws when the space is Default or active
+    const folder = join(files.spacesRoot, checked.id);
+    const { backupPath } = await deps.backup({
+        space: checked,
+        spaceFolder: folder,
+        backupsRoot: files.backupsRoot,
+        ommsVersion: options.ommsVersion,
+    });
+    await removeStoredSpace(files, checked.id);
+    try {
+        deps.removeFolder(folder);
+        return { backupPath, space: checked };
+    }
+    catch {
+        return { backupPath, space: checked, leftoverFolder: folder };
+    }
+}

package/dist/services/spaces/folder-size.d.ts

@@ -0,0 +1,2 @@
+/** The total size in bytes of the files in a folder. A missing folder counts as zero. */
+export declare function folderSize(folder: string): number;

package/dist/services/spaces/folder-size.js

@@ -0,0 +1,9 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { walkTree } from "../legacy-migration.js";
+/** The total size in bytes of the files in a folder. A missing folder counts as zero. */
+export function folderSize(folder) {
+    if (!existsSync(folder))
+        return 0;
+    return walkTree(folder).files.reduce((total, rel) => total + statSync(join(folder, rel)).size, 0);
+}

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

@@ -0,0 +1,26 @@
+import { type SpaceFiles } from "./registry-store.js";
+/**
+ * The space operations an agent or a terminal may run: list, status, create, archive, unarchive
+ * and use (switch). Delete, rename, backup and restore exist only in the web app (design D11),
+ * because a person must confirm them. The CLI `space` command, the `memory` tool `space` mode
+ * and the Claude Code plugin tool all call this one function, so the three hosts stay equal.
+ */
+export interface SpaceOperationArgs {
+    action?: string;
+    /** A space name or id. */
+    name?: string;
+}
+export interface SpaceOperationContext {
+    files: SpaceFiles;
+    /** The space this process uses now, from the last config load. */
+    current: {
+        id: string;
+        name: string;
+        customStoragePath: boolean;
+        problem?: string;
+    };
+}
+/** Actions that need a person at the web app, so the CLI and the `memory` tool refuse them. */
+export declare const WEB_ONLY_SPACE_ACTIONS: string[];
+export declare const SPACE_ACTIONS: string[];
+export declare function executeSpaceOperation(args: SpaceOperationArgs, context: SpaceOperationContext): Promise<Record<string, unknown>>;