om-memory-system 5.5.0-next.212 → 5.5.0

package/dist/services/spaces/operations.js

@@ -0,0 +1,82 @@
+import { listSpaces, SpaceError, readRegistryFile } from "./registry.js";
+import { archiveStoredSpace, createStoredSpace, switchStoredSpace, unarchiveStoredSpace, } from "./registry-store.js";
+/** Actions that need a person at the web app, so the CLI and the `memory` tool refuse them. */
+export const WEB_ONLY_SPACE_ACTIONS = ["delete", "rename", "backup", "restore"];
+export const SPACE_ACTIONS = ["list", "status", "create", "archive", "unarchive", "use"];
+const WEB_ONLY = WEB_ONLY_SPACE_ACTIONS;
+const ACTIONS = SPACE_ACTIONS;
+function summary(registry) {
+    return listSpaces(registry).map((space) => ({
+        id: space.id,
+        name: space.name,
+        active: space.id === registry.activeSpaceId,
+        archived: space.archived,
+        createdAt: space.createdAt || undefined,
+    }));
+}
+function activeOf(registry) {
+    const active = listSpaces(registry).find((space) => space.id === registry.activeSpaceId);
+    return { id: active.id, name: active.name };
+}
+export async function executeSpaceOperation(args, context) {
+    const action = (args.action ?? "list").toLowerCase();
+    if (WEB_ONLY.includes(action)) {
+        return { success: false, error: `Only the web app can ${action} a space.` };
+    }
+    if (!ACTIONS.includes(action)) {
+        return {
+            success: false,
+            error: `Unknown space action "${args.action}". Actions: ${ACTIONS.join(", ")}.`,
+        };
+    }
+    const name = args.name?.trim();
+    if (["create", "archive", "unarchive", "use"].includes(action) && !name) {
+        return { success: false, error: `The ${action} action needs a space name.` };
+    }
+    try {
+        const read = readRegistryFile(context.files.registryPath);
+        if (action === "list") {
+            return {
+                success: true,
+                activeSpace: activeOf(read.registry),
+                spaces: summary(read.registry),
+                ...(read.problem ? { problem: read.problem } : {}),
+            };
+        }
+        if (action === "status") {
+            return {
+                success: true,
+                activeSpace: context.current,
+                registryActiveSpace: activeOf(read.registry),
+                ...(context.current.problem ? { problem: context.current.problem } : {}),
+            };
+        }
+        if (action === "create") {
+            const space = await createStoredSpace(context.files, name);
+            return {
+                success: true,
+                space: { id: space.id, name: space.name },
+                message: `Created space "${space.name}". Use the "use" action to make it active.`,
+            };
+        }
+        const change = {
+            archive: archiveStoredSpace,
+            unarchive: unarchiveStoredSpace,
+            use: switchStoredSpace,
+        }[action];
+        const registry = await change(context.files, name);
+        const active = activeOf(registry);
+        return {
+            success: true,
+            activeSpace: active,
+            message: action === "use"
+                ? `Active space is now "${active.name}". It applies from the next turn.`
+                : `Space "${name}" is now ${action === "archive" ? "archived" : "not archived"}.`,
+        };
+    }
+    catch (error) {
+        if (error instanceof SpaceError)
+            return { success: false, error: error.message };
+        throw error;
+    }
+}

package/dist/services/spaces/registry-store.d.ts

@@ -0,0 +1,32 @@
+import { type SpaceEntry, type SpaceRegistry } from "./registry.js";
+export interface SpaceFiles {
+    /** `<omms folder>/spaces.json` */
+    registryPath: string;
+    lockPath: string;
+    /** `<omms folder>/spaces`: one folder per extra space. */
+    spacesRoot: string;
+    /** `<omms folder>/backups` */
+    backupsRoot: string;
+    /** `<omms folder>/space-appearance`: the icon of each space. It is outside every space folder. */
+    appearanceRoot: string;
+}
+/** Locations of the registry and space folders under the OMMS folder (normally `~/.omms`). */
+export declare function spaceFiles(ommsDir: string): SpaceFiles;
+/**
+ * Applies `change` to the registry under the lock and writes the result.
+ * A registry file that cannot be read is never overwritten: the caller must fix it first.
+ * When `change` throws, the file is left as it was.
+ */
+export declare function updateRegistry<T>(files: SpaceFiles, change: (registry: SpaceRegistry) => {
+    registry: SpaceRegistry;
+    result: T;
+}): Promise<{
+    registry: SpaceRegistry;
+    result: T;
+}>;
+export declare function createStoredSpace(files: SpaceFiles, name: string): Promise<SpaceEntry>;
+export declare const archiveStoredSpace: (files: SpaceFiles, idOrName: string) => Promise<SpaceRegistry>;
+export declare const unarchiveStoredSpace: (files: SpaceFiles, idOrName: string) => Promise<SpaceRegistry>;
+export declare const switchStoredSpace: (files: SpaceFiles, idOrName: string) => Promise<SpaceRegistry>;
+export declare const removeStoredSpace: (files: SpaceFiles, idOrName: string) => Promise<SpaceRegistry>;
+export declare function renameStoredSpace(files: SpaceFiles, idOrName: string, name: string): Promise<SpaceRegistry>;

package/dist/services/spaces/registry-store.js

@@ -0,0 +1,134 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { SpaceError, archiveSpace, createSpace, readRegistryFile, removeSpace, renameSpace, switchSpace, unarchiveSpace, } from "./registry.js";
+/**
+ * The one write path for `spaces.json` (design D5). The web server, the CLI and the
+ * `memory` tool all change the registry through `updateRegistry`. Readers never lock.
+ *
+ * A change runs as: take the lock file, read the file, apply the change, write a
+ * temporary file, rename it over `spaces.json`, release the lock. A reader sees
+ * the old file or the new file, never a part of one.
+ */
+const LOCK_TIMEOUT_MS = 5000;
+const LOCK_POLL_MS = 15;
+/** A lock file with no readable owner is stale only after this long, so a lock still being written is kept. */
+const UNREADABLE_LOCK_GRACE_MS = 2000;
+/** Locations of the registry and space folders under the OMMS folder (normally `~/.omms`). */
+export function spaceFiles(ommsDir) {
+    return {
+        registryPath: join(ommsDir, "spaces.json"),
+        lockPath: join(ommsDir, "spaces.json.lock"),
+        spacesRoot: join(ommsDir, "spaces"),
+        backupsRoot: join(ommsDir, "backups"),
+        appearanceRoot: join(ommsDir, "space-appearance"),
+    };
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** True when the lock file exists but its owner is gone, so the next writer may remove it. */
+function lockIsStale(lockPath) {
+    try {
+        const state = JSON.parse(readFileSync(lockPath, "utf-8"));
+        return typeof state.pid === "number" && state.pid > 0 && !isProcessAlive(state.pid);
+    }
+    catch {
+        try {
+            return Date.now() - statSync(lockPath).mtimeMs > UNREADABLE_LOCK_GRACE_MS;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+async function acquireLock(lockPath) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            writeFileSync(lockPath, JSON.stringify({ pid: process.pid, at: Date.now() }), { flag: "wx" });
+            return;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        if (lockIsStale(lockPath)) {
+            try {
+                unlinkSync(lockPath);
+            }
+            catch {
+                // Another writer removed it first. Try to take it again.
+            }
+            continue;
+        }
+        if (Date.now() > deadline) {
+            throw new SpaceError("lock-timeout", "Another OMMS process is changing the space list. Try again in a moment.");
+        }
+        await sleep(LOCK_POLL_MS);
+    }
+}
+/**
+ * Applies `change` to the registry under the lock and writes the result.
+ * A registry file that cannot be read is never overwritten: the caller must fix it first.
+ * When `change` throws, the file is left as it was.
+ */
+export async function updateRegistry(files, change) {
+    await acquireLock(files.lockPath);
+    try {
+        const current = readRegistryFile(files.registryPath);
+        if (current.problem) {
+            throw new SpaceError("unreadable", `${current.problem} Fix or remove ${files.registryPath} before changing spaces.`);
+        }
+        const next = change(current.registry);
+        const temporary = `${files.registryPath}.${process.pid}.tmp`;
+        try {
+            writeFileSync(temporary, `${JSON.stringify(next.registry, null, 2)}\n`);
+            renameSync(temporary, files.registryPath);
+        }
+        catch (error) {
+            if (existsSync(temporary))
+                unlinkSync(temporary);
+            throw error;
+        }
+        return next;
+    }
+    finally {
+        try {
+            unlinkSync(files.lockPath);
+        }
+        catch {
+            // The lock is already gone.
+        }
+    }
+}
+export async function createStoredSpace(files, name) {
+    const { result } = await updateRegistry(files, (registry) => {
+        const created = createSpace(registry, name, new Date().toISOString());
+        // The folder comes first, so the registry never names a space that has no folder.
+        mkdirSync(join(files.spacesRoot, created.space.id), { recursive: true });
+        return { registry: created.registry, result: created.space };
+    });
+    return result;
+}
+const simple = (apply) => async (files, idOrName) => (await updateRegistry(files, (registry) => ({
+    registry: apply(registry, idOrName),
+    result: 0,
+}))).registry;
+export const archiveStoredSpace = simple(archiveSpace);
+export const unarchiveStoredSpace = simple(unarchiveSpace);
+export const switchStoredSpace = simple(switchSpace);
+export const removeStoredSpace = simple(removeSpace);
+export async function renameStoredSpace(files, idOrName, name) {
+    return (await updateRegistry(files, (registry) => ({
+        registry: renameSpace(registry, idOrName, name),
+        result: 0,
+    }))).registry;
+}

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

@@ -0,0 +1,70 @@
+/**
+ * Memory space registry (ADR-041). Pure logic: it reads paths from arguments and
+ * never imports CONFIG, so tests that stub `src/config.js` keep working.
+ *
+ * `spaces.json` holds the spaces the user created plus the active space id.
+ * The Default space is not stored. It always exists and uses the global storage path.
+ */
+export declare const DEFAULT_SPACE_ID = "default";
+export declare const DEFAULT_SPACE_NAME = "Default";
+export declare const MAX_SPACE_ID_LENGTH = 40;
+export declare const MAX_SPACE_NAME_LENGTH = 60;
+export interface SpaceEntry {
+    id: string;
+    name: string;
+    /** ISO 8601 time. */
+    createdAt: string;
+    archived: boolean;
+    /** ISO 8601 time of the archive. Absent for a space archived before OMMS recorded it. */
+    archivedAt?: string;
+}
+export interface SpaceRegistry {
+    version: number;
+    activeSpaceId: string;
+    /** User-created spaces only. Default is added by `listSpaces`. */
+    spaces: SpaceEntry[];
+}
+export type SpaceErrorCode = "invalid-name" | "name-taken" | "id-taken" | "reserved" | "protected" | "active" | "archived" | "not-archived" | "unknown" | "invalid-id" | "unreadable" | "lock-timeout";
+/** A refused space operation. The message is safe to show to the user. */
+export declare class SpaceError extends Error {
+    readonly code: SpaceErrorCode;
+    constructor(code: SpaceErrorCode, message: string);
+}
+export interface SpacePaths {
+    /** The global store folder, normally `~/.omms/data`. The Default space uses it. */
+    globalStoragePath: string;
+    /** The folder that holds one folder per extra space, normally `~/.omms/spaces`. */
+    spacesRoot: string;
+}
+export declare function emptyRegistry(): SpaceRegistry;
+/** Every space in display order: Default first, then user spaces in creation order. */
+export declare function listSpaces(registry: SpaceRegistry): SpaceEntry[];
+/** Lowercase letters, digits and single hyphens, at most 40 characters. Empty when the name has none. */
+export declare function spaceIdFromName(name: string): string;
+/** True for a space id that is safe to use in a path: lowercase letters, digits and single hyphens. */
+export declare function isValidSpaceId(id: string): boolean;
+/** Finds a space by id, or by display name without regard to case. */
+export declare function findSpace(registry: SpaceRegistry, idOrName: string): SpaceEntry | undefined;
+/** Adds a space. Returns the new registry and the new entry. The active space does not change. */
+export declare function createSpace(registry: SpaceRegistry, name: string, now: string): {
+    registry: SpaceRegistry;
+    space: SpaceEntry;
+};
+export declare function renameSpace(registry: SpaceRegistry, idOrName: string, name: string): SpaceRegistry;
+export declare function archiveSpace(registry: SpaceRegistry, idOrName: string, now?: string): SpaceRegistry;
+export declare function unarchiveSpace(registry: SpaceRegistry, idOrName: string): SpaceRegistry;
+export declare function switchSpace(registry: SpaceRegistry, idOrName: string): SpaceRegistry;
+/** Removes an entry. The caller checks backup and folder removal (D8). */
+export declare function removeSpace(registry: SpaceRegistry, idOrName: string): SpaceRegistry;
+/** The folder of a space. Refuses an id that is not safe, so a path cannot leave the spaces root. */
+export declare function resolveSpaceFolder(id: string, paths: SpacePaths): string;
+export interface RegistryReadResult {
+    registry: SpaceRegistry;
+    /** Set when the file exists but cannot be used. The registry is then Default only. */
+    problem?: string;
+}
+/**
+ * Reads `spaces.json`. A missing file means Default only. An unreadable or invalid
+ * file also gives Default only, leaves the file alone, and sets `problem`.
+ */
+export declare function readRegistryFile(path: string): RegistryReadResult;

package/dist/services/spaces/registry.js

@@ -0,0 +1,227 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+/**
+ * Memory space registry (ADR-041). Pure logic: it reads paths from arguments and
+ * never imports CONFIG, so tests that stub `src/config.js` keep working.
+ *
+ * `spaces.json` holds the spaces the user created plus the active space id.
+ * The Default space is not stored. It always exists and uses the global storage path.
+ */
+export const DEFAULT_SPACE_ID = "default";
+export const DEFAULT_SPACE_NAME = "Default";
+export const MAX_SPACE_ID_LENGTH = 40;
+export const MAX_SPACE_NAME_LENGTH = 60;
+const REGISTRY_VERSION = 1;
+/** A refused space operation. The message is safe to show to the user. */
+export class SpaceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SpaceError";
+    }
+}
+export function emptyRegistry() {
+    return { version: REGISTRY_VERSION, activeSpaceId: DEFAULT_SPACE_ID, spaces: [] };
+}
+function defaultEntry() {
+    return { id: DEFAULT_SPACE_ID, name: DEFAULT_SPACE_NAME, createdAt: "", archived: false };
+}
+/** Every space in display order: Default first, then user spaces in creation order. */
+export function listSpaces(registry) {
+    return [defaultEntry(), ...registry.spaces];
+}
+/** Lowercase letters, digits and single hyphens, at most 40 characters. Empty when the name has none. */
+export function spaceIdFromName(name) {
+    const id = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return id.slice(0, MAX_SPACE_ID_LENGTH).replace(/-+$/, "");
+}
+const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** True for a space id that is safe to use in a path: lowercase letters, digits and single hyphens. */
+export function isValidSpaceId(id) {
+    return id.length >= 1 && id.length <= MAX_SPACE_ID_LENGTH && ID_PATTERN.test(id);
+}
+function findByName(registry, name) {
+    const wanted = name.trim().toLowerCase();
+    return listSpaces(registry).find((space) => space.name.toLowerCase() === wanted);
+}
+/** Finds a space by id, or by display name without regard to case. */
+export function findSpace(registry, idOrName) {
+    const wanted = idOrName.trim().toLowerCase();
+    const all = listSpaces(registry);
+    return (all.find((space) => space.id === wanted) ?? all.find((s) => s.name.toLowerCase() === wanted));
+}
+function requireSpace(registry, idOrName) {
+    const space = findSpace(registry, idOrName);
+    if (!space) {
+        throw new SpaceError("unknown", `No space named "${idOrName}". ${validTargets(registry)}`);
+    }
+    return space;
+}
+function validTargets(registry) {
+    const names = listSpaces(registry)
+        .filter((space) => !space.archived)
+        .map((space) => space.id);
+    return `Spaces that can become active: ${names.join(", ")}.`;
+}
+function checkedName(name) {
+    const trimmed = name.trim();
+    if (trimmed.length < 1 || trimmed.length > MAX_SPACE_NAME_LENGTH) {
+        throw new SpaceError("invalid-name", `A space name needs 1 to ${MAX_SPACE_NAME_LENGTH} characters.`);
+    }
+    return trimmed;
+}
+/** Adds a space. Returns the new registry and the new entry. The active space does not change. */
+export function createSpace(registry, name, now) {
+    const display = checkedName(name);
+    const existing = findByName(registry, display);
+    if (existing) {
+        throw new SpaceError("name-taken", `A space named "${existing.name}" already exists.`);
+    }
+    const id = spaceIdFromName(display);
+    if (id === "") {
+        throw new SpaceError("invalid-name", "A space name needs at least one letter or digit.");
+    }
+    if (id === DEFAULT_SPACE_ID) {
+        throw new SpaceError("reserved", `The id "${DEFAULT_SPACE_ID}" belongs to the Default space.`);
+    }
+    const clash = registry.spaces.find((space) => space.id === id);
+    if (clash) {
+        throw new SpaceError("id-taken", `The name "${display}" gives the same folder id as "${clash.name}". Choose another name.`);
+    }
+    const space = { id, name: display, createdAt: now, archived: false };
+    return { registry: { ...registry, spaces: [...registry.spaces, space] }, space };
+}
+function updateSpace(registry, id, change) {
+    return {
+        ...registry,
+        spaces: registry.spaces.map((space) => (space.id === id ? { ...space, ...change } : space)),
+    };
+}
+export function renameSpace(registry, idOrName, name) {
+    const space = requireSpace(registry, idOrName);
+    if (space.id === DEFAULT_SPACE_ID) {
+        throw new SpaceError("protected", "The Default space cannot be renamed.");
+    }
+    const display = checkedName(name);
+    const clash = findByName(registry, display);
+    if (clash && clash.id !== space.id) {
+        throw new SpaceError("name-taken", `A space named "${clash.name}" already exists.`);
+    }
+    return updateSpace(registry, space.id, { name: display });
+}
+export function archiveSpace(registry, idOrName, now = new Date().toISOString()) {
+    const space = requireSpace(registry, idOrName);
+    if (space.id === DEFAULT_SPACE_ID) {
+        throw new SpaceError("protected", "The Default space cannot be archived.");
+    }
+    if (space.id === registry.activeSpaceId) {
+        throw new SpaceError("active", `"${space.name}" is the active space. Switch to another space first.`);
+    }
+    return updateSpace(registry, space.id, { archived: true, archivedAt: now });
+}
+export function unarchiveSpace(registry, idOrName) {
+    const space = requireSpace(registry, idOrName);
+    if (!space.archived) {
+        throw new SpaceError("not-archived", `"${space.name}" is not archived.`);
+    }
+    return updateSpace(registry, space.id, { archived: false, archivedAt: undefined });
+}
+export function switchSpace(registry, idOrName) {
+    const space = requireSpace(registry, idOrName);
+    if (space.archived) {
+        throw new SpaceError("archived", `"${space.name}" is archived. Unarchive it first. ${validTargets(registry)}`);
+    }
+    return { ...registry, activeSpaceId: space.id };
+}
+/** Removes an entry. The caller checks backup and folder removal (D8). */
+export function removeSpace(registry, idOrName) {
+    const space = requireSpace(registry, idOrName);
+    if (space.id === DEFAULT_SPACE_ID) {
+        throw new SpaceError("protected", "The Default space cannot be deleted.");
+    }
+    if (space.id === registry.activeSpaceId) {
+        throw new SpaceError("active", `"${space.name}" is the active space. Switch to another space first.`);
+    }
+    return { ...registry, spaces: registry.spaces.filter((s) => s.id !== space.id) };
+}
+/** The folder of a space. Refuses an id that is not safe, so a path cannot leave the spaces root. */
+export function resolveSpaceFolder(id, paths) {
+    if (id === DEFAULT_SPACE_ID)
+        return paths.globalStoragePath;
+    if (!isValidSpaceId(id)) {
+        throw new SpaceError("invalid-id", `"${id}" is not a valid space id.`);
+    }
+    const root = resolve(paths.spacesRoot);
+    const folder = resolve(root, id);
+    if (!folder.startsWith(root + sep)) {
+        throw new SpaceError("invalid-id", `"${id}" is not a valid space id.`);
+    }
+    return join(paths.spacesRoot, id);
+}
+function parseEntry(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const entry = raw;
+    if (typeof entry.id !== "string" ||
+        !isValidSpaceId(entry.id) ||
+        entry.id === DEFAULT_SPACE_ID ||
+        typeof entry.name !== "string" ||
+        entry.name.trim() === "" ||
+        typeof entry.createdAt !== "string" ||
+        typeof entry.archived !== "boolean" ||
+        (entry.archivedAt !== undefined && typeof entry.archivedAt !== "string")) {
+        return undefined;
+    }
+    return {
+        id: entry.id,
+        name: entry.name,
+        createdAt: entry.createdAt,
+        archived: entry.archived,
+        ...(typeof entry.archivedAt === "string" ? { archivedAt: entry.archivedAt } : {}),
+    };
+}
+/**
+ * Reads `spaces.json`. A missing file means Default only. An unreadable or invalid
+ * file also gives Default only, leaves the file alone, and sets `problem`.
+ */
+export function readRegistryFile(path) {
+    if (!existsSync(path))
+        return { registry: emptyRegistry() };
+    const unusable = (reason) => ({
+        registry: emptyRegistry(),
+        problem: `spaces.json is not usable (${reason}); using the Default space.`,
+    });
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return unusable("cannot be read as JSON");
+    }
+    if (typeof raw !== "object" || raw === null)
+        return unusable("wrong shape");
+    const file = raw;
+    if (typeof file.activeSpaceId !== "string" || !Array.isArray(file.spaces)) {
+        return unusable("wrong shape");
+    }
+    const spaces = [];
+    for (const item of file.spaces) {
+        const entry = parseEntry(item);
+        if (!entry || spaces.some((space) => space.id === entry.id))
+            return unusable("bad entry");
+        spaces.push(entry);
+    }
+    const registry = {
+        version: typeof file.version === "number" ? file.version : REGISTRY_VERSION,
+        activeSpaceId: file.activeSpaceId,
+        spaces,
+    };
+    if (!listSpaces(registry).some((space) => space.id === registry.activeSpaceId)) {
+        return unusable(`active space "${registry.activeSpaceId}" is not in the list`);
+    }
+    return { registry };
+}

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

@@ -0,0 +1,20 @@
+import { type SpaceEntry } from "./registry.js";
+import { type SpaceFiles } from "./registry-store.js";
+export interface BackupSummary {
+    /** The full path of the backup folder. */
+    path: string;
+    spaceId: string;
+    spaceName: string;
+    createdAt: string;
+    fileCount: number;
+    /** The total size of the backed-up files. */
+    sizeBytes: number;
+}
+/** The space backups in the backups folder, newest first. A folder that is not a valid backup is left out. */
+export declare function listBackups(backupsRoot: string): BackupSummary[];
+/**
+ * Restores a backup into a new space (design D7). It checks every file against the manifest
+ * first and creates nothing when one is damaged. It never replaces an existing space and never
+ * changes the active space.
+ */
+export declare function restoreBackup(files: SpaceFiles, backupPath: string, now?: Date): Promise<SpaceEntry>;

package/dist/services/spaces/restore.js

@@ -0,0 +1,80 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { SPACE_BACKUP_PREFIX, readBackupManifest, verifyBackup, } from "./backup.js";
+import { MAX_SPACE_NAME_LENGTH, SpaceError } from "./registry.js";
+import { createStoredSpace, removeStoredSpace } from "./registry-store.js";
+/** The space backups in the backups folder, newest first. A folder that is not a valid backup is left out. */
+export function listBackups(backupsRoot) {
+    if (!existsSync(backupsRoot))
+        return [];
+    const summaries = [];
+    for (const entry of readdirSync(backupsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !entry.name.startsWith(SPACE_BACKUP_PREFIX))
+            continue;
+        const path = join(backupsRoot, entry.name);
+        let manifest;
+        try {
+            manifest = readBackupManifest(path);
+        }
+        catch {
+            continue;
+        }
+        summaries.push({
+            path,
+            spaceId: manifest.spaceId,
+            spaceName: manifest.spaceName,
+            createdAt: manifest.createdAt,
+            fileCount: manifest.files.length,
+            sizeBytes: manifest.files.reduce((total, file) => total + file.size, 0),
+        });
+    }
+    return summaries.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+/** `<name> (restored <date>)`, with the name cut so the whole display name fits the limit. */
+function restoredName(name, date, attempt) {
+    const suffix = ` (restored ${date.toISOString().slice(0, 10)})${attempt > 1 ? ` ${attempt}` : ""}`;
+    return `${name.slice(0, MAX_SPACE_NAME_LENGTH - suffix.length).trimEnd()}${suffix}`;
+}
+/**
+ * Restores a backup into a new space (design D7). It checks every file against the manifest
+ * first and creates nothing when one is damaged. It never replaces an existing space and never
+ * changes the active space.
+ */
+export async function restoreBackup(files, backupPath, now = new Date()) {
+    const manifest = readBackupManifest(backupPath);
+    try {
+        verifyBackup(backupPath, manifest);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Restore refused, the backup is damaged: ${reason}`, { cause: error });
+    }
+    const space = await createWithFreeName(files, manifest.spaceName, now);
+    const folder = join(files.spacesRoot, space.id);
+    try {
+        for (const rel of manifest.files.map((file) => file.path)) {
+            mkdirSync(dirname(join(folder, rel)), { recursive: true });
+            copyFileSync(join(backupPath, rel), join(folder, rel));
+        }
+        verifyBackup(folder, manifest);
+    }
+    catch (error) {
+        await removeStoredSpace(files, space.id);
+        rmSync(folder, { recursive: true, force: true });
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Restore failed: ${reason}`, { cause: error });
+    }
+    return space;
+}
+async function createWithFreeName(files, name, now) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await createStoredSpace(files, restoredName(name, now, attempt));
+        }
+        catch (error) {
+            const taken = error instanceof SpaceError && ["name-taken", "id-taken"].includes(error.code);
+            if (!taken || attempt >= 50)
+                throw error;
+        }
+    }
+}

package/dist/services/spaces/storage-resolution.d.ts

@@ -0,0 +1,17 @@
+/** The OMMS folder, normally `~/.omms`. It holds `spaces.json`, `spaces/` and `backups/`. */
+export declare function ommsHomeDir(): string;
+/** Expands a leading `~` to the home folder. */
+export declare function expandPath(path: string): string;
+/** The global store folder: the config's `storagePath`, or the default `~/.omms/data`. */
+export declare function storagePathFrom(fileConfig: {
+    storagePath?: string;
+}): string;
+/**
+ * Keeps skills.db and the embedding model cache in the global storage path when a
+ * project config or the active space moves `storagePath` (ADR-036, ADR-041).
+ */
+export declare function withSkillStorage<T extends {
+    storagePath: string;
+}>(config: T, global: {
+    storagePath?: string;
+}): T;