recallx 1.1.0 → 1.2.0

package/app/server/workspace-ops.js

@@ -0,0 +1,249 @@
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { AppError } from "./errors.js";
+const BACKUP_MANIFEST_FILE = "manifest.json";
+const SESSION_METADATA_FILE = "workspace-session.json";
+const LOCK_METADATA_FILE = "workspace.lock.json";
+const WORKSPACE_ACTIVITY_THRESHOLD_MS = 10 * 60 * 1000;
+function readJsonFile(filePath) {
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        return JSON.parse(readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeJsonFile(filePath, value) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+function sanitizeLabel(value, fallback) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return fallback;
+    }
+    return trimmed.replace(/[<>:"/\\|?*\x00-\x1f]+/g, "-").replace(/\s+/g, " ").trim() || fallback;
+}
+function sessionMetadataPath(paths) {
+    return path.join(paths.configDir, SESSION_METADATA_FILE);
+}
+function lockMetadataPath(paths) {
+    return path.join(paths.configDir, LOCK_METADATA_FILE);
+}
+function readSessionMetadata(paths) {
+    return readJsonFile(sessionMetadataPath(paths));
+}
+function readLockMetadata(paths) {
+    return readJsonFile(lockMetadataPath(paths));
+}
+function buildSafetyWarnings(previous, lock, machineId, sessionId) {
+    const warnings = [];
+    const isSameActiveSession = previous?.sessionId === sessionId &&
+        previous.machineId === machineId &&
+        lock?.sessionId === sessionId &&
+        lock.machineId === machineId;
+    if (lock && !isSameActiveSession) {
+        warnings.push({
+            code: "active_lock",
+            message: `Workspace lock marker is still present from ${lock.machineId}. Another session may still be active.`
+        });
+    }
+    if (previous &&
+        !isSameActiveSession &&
+        (!previous.lastCleanCloseAt || previous.lastCleanCloseAt < previous.lastOpenedAt)) {
+        warnings.push({
+            code: "unclean_shutdown",
+            message: "The previous session does not appear to have closed cleanly. Create a backup before heavy edits."
+        });
+    }
+    if (previous &&
+        previous.machineId !== machineId &&
+        Date.now() - Date.parse(previous.lastOpenedAt) <= WORKSPACE_ACTIVITY_THRESHOLD_MS) {
+        warnings.push({
+            code: "recent_other_machine",
+            message: `This workspace was opened recently on ${previous.machineId}. Treat multi-device access as single-writer only.`
+        });
+    }
+    return warnings;
+}
+export function beginWorkspaceSession(paths, params) {
+    const machineId = os.hostname() || "unknown-machine";
+    const previous = readSessionMetadata(paths);
+    const lock = readLockMetadata(paths);
+    const warnings = buildSafetyWarnings(previous, lock, machineId, params.sessionId);
+    const nextSession = {
+        machineId,
+        sessionId: params.sessionId,
+        appVersion: params.appVersion,
+        lastOpenedAt: params.now,
+        lastCleanCloseAt: previous?.lastCleanCloseAt ?? null
+    };
+    const nextLock = {
+        machineId,
+        sessionId: params.sessionId,
+        appVersion: params.appVersion,
+        lockUpdatedAt: params.now
+    };
+    writeJsonFile(sessionMetadataPath(paths), nextSession);
+    writeJsonFile(lockMetadataPath(paths), nextLock);
+    return {
+        machineId,
+        sessionId: params.sessionId,
+        lastOpenedAt: params.now,
+        lastCleanCloseAt: nextSession.lastCleanCloseAt,
+        lockPresent: true,
+        lockUpdatedAt: params.now,
+        activeSessionMachineId: machineId,
+        warnings
+    };
+}
+export function endWorkspaceSession(paths, params) {
+    const machineId = os.hostname() || "unknown-machine";
+    const previous = readSessionMetadata(paths);
+    const nextSession = {
+        machineId,
+        sessionId: params.sessionId,
+        appVersion: params.appVersion,
+        lastOpenedAt: previous?.lastOpenedAt ?? params.now,
+        lastCleanCloseAt: params.now
+    };
+    writeJsonFile(sessionMetadataPath(paths), nextSession);
+    const lock = readLockMetadata(paths);
+    if (lock?.sessionId === params.sessionId && existsSync(lockMetadataPath(paths))) {
+        unlinkSync(lockMetadataPath(paths));
+    }
+}
+function formatArtifactSize(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    }
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function copyWorkspaceSnapshot(sourcePaths, backupDir) {
+    mkdirSync(backupDir, { recursive: true });
+    if (existsSync(sourcePaths.dbPath)) {
+        copyFileSync(sourcePaths.dbPath, path.join(backupDir, "workspace.db"));
+    }
+    for (const [from, name] of [
+        [sourcePaths.artifactsDir, "artifacts"],
+        [sourcePaths.exportsDir, "exports"],
+    ]) {
+        if (existsSync(from)) {
+            cpSync(from, path.join(backupDir, name), { recursive: true });
+        }
+    }
+    if (existsSync(sourcePaths.configDir)) {
+        const targetConfigDir = path.join(backupDir, "config");
+        mkdirSync(targetConfigDir, { recursive: true });
+        for (const entry of readdirSync(sourcePaths.configDir, { withFileTypes: true })) {
+            if (entry.name === SESSION_METADATA_FILE || entry.name === LOCK_METADATA_FILE) {
+                continue;
+            }
+            const sourcePath = path.join(sourcePaths.configDir, entry.name);
+            const destinationPath = path.join(targetConfigDir, entry.name);
+            if (entry.isDirectory()) {
+                cpSync(sourcePath, destinationPath, { recursive: true });
+            }
+            else {
+                copyFileSync(sourcePath, destinationPath);
+            }
+        }
+    }
+}
+export function createWorkspaceBackup(paths, params) {
+    const id = `${params.now.replace(/[-:.TZ]/g, "").slice(0, 14)}-${sanitizeLabel(params.label, "snapshot").replace(/\s+/g, "-").toLowerCase()}`;
+    const backupDir = path.join(paths.backupsDir, id);
+    if (existsSync(backupDir)) {
+        throw new AppError(409, "BACKUP_EXISTS", `Backup already exists: ${id}`);
+    }
+    copyWorkspaceSnapshot(paths, backupDir);
+    const manifest = {
+        id,
+        label: sanitizeLabel(params.label, "Manual snapshot"),
+        createdAt: params.now,
+        backupPath: backupDir,
+        workspaceRoot: paths.root,
+        workspaceName: params.workspaceName,
+        appVersion: params.appVersion
+    };
+    writeJsonFile(path.join(backupDir, BACKUP_MANIFEST_FILE), manifest);
+    return manifest;
+}
+export function listWorkspaceBackups(paths) {
+    if (!existsSync(paths.backupsDir)) {
+        return [];
+    }
+    return readdirSync(paths.backupsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => readJsonFile(path.join(paths.backupsDir, entry.name, BACKUP_MANIFEST_FILE)))
+        .filter((entry) => Boolean(entry))
+        .sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+}
+export function restoreWorkspaceBackup(paths, params) {
+    const manifest = listWorkspaceBackups(paths).find((item) => item.id === params.backupId);
+    if (!manifest) {
+        throw new AppError(404, "BACKUP_NOT_FOUND", `Backup ${params.backupId} not found.`);
+    }
+    const targetRoot = path.resolve(params.targetRootPath);
+    if (targetRoot === path.resolve(paths.root)) {
+        throw new AppError(400, "INVALID_INPUT", "Restore target must be a different workspace root.");
+    }
+    if (existsSync(targetRoot)) {
+        const existingEntries = readdirSync(targetRoot);
+        if (existingEntries.length > 0) {
+            throw new AppError(409, "RESTORE_TARGET_NOT_EMPTY", "Restore target root must be empty or not exist.");
+        }
+    }
+    else {
+        mkdirSync(targetRoot, { recursive: true });
+    }
+    for (const entry of ["workspace.db", "artifacts", "exports", "config"]) {
+        const sourcePath = path.join(manifest.backupPath, entry);
+        const destinationPath = path.join(targetRoot, entry);
+        if (!existsSync(sourcePath)) {
+            continue;
+        }
+        if (entry === "workspace.db") {
+            copyFileSync(sourcePath, destinationPath);
+        }
+        else {
+            cpSync(sourcePath, destinationPath, { recursive: true });
+        }
+    }
+    return manifest;
+}
+export function exportWorkspaceSnapshot(paths, params) {
+    const id = `${params.now.replace(/[-:.TZ]/g, "").slice(0, 14)}-workspace-export`;
+    const extension = params.format === "json" ? "json" : "md";
+    const exportPath = path.join(paths.exportsDir, `${id}.${extension}`);
+    const body = params.format === "json" ? `${JSON.stringify(params.payload, null, 2)}\n` : `${params.markdown}\n`;
+    writeFileSync(exportPath, body, "utf8");
+    const manifest = {
+        id,
+        format: params.format,
+        createdAt: params.now,
+        exportPath,
+        workspaceRoot: paths.root,
+        workspaceName: params.workspaceName,
+        appVersion: params.appVersion
+    };
+    writeJsonFile(path.join(paths.exportsDir, `${id}.manifest.json`), manifest);
+    return manifest;
+}
+export function summarizeBackupRecord(record) {
+    const stats = existsSync(record.backupPath) ? statSync(record.backupPath) : null;
+    const sizeLabel = stats ? formatArtifactSize(stats.size) : "unknown";
+    return `${record.label} (${record.id}) at ${record.createdAt} -> ${record.backupPath} [${sizeLabel}]`;
+}
+export function removeWorkspaceDirectory(rootPath) {
+    if (existsSync(rootPath)) {
+        rmSync(rootPath, { recursive: true, force: true });
+    }
+}

package/app/server/workspace-session.js

@@ -1,10 +1,13 @@
 import { existsSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { workspaceInfo } from "./config.js";
 import { openDatabase } from "./db.js";
 import { AppError } from "./errors.js";
 import { bootstrapAutomaticGovernance } from "./governance.js";
 import { RecallXRepository } from "./repositories.js";
+import { beginWorkspaceSession, createWorkspaceBackup, endWorkspaceSession, exportWorkspaceSnapshot, listWorkspaceBackups, restoreWorkspaceBackup, } from "./workspace-ops.js";
+import { importIntoWorkspace, previewImportIntoWorkspace } from "./workspace-import.js";
 import { defaultWorkspaceName, ensureWorkspace } from "./workspace.js";
 import { RECALLX_VERSION } from "../shared/version.js";
 export class WorkspaceSessionManager {
@@ -12,6 +15,7 @@ export class WorkspaceSessionManager {
     authMode;
     currentState;
     history = new Map();
+    processSessionId = randomUUID();
     constructor(serverConfig, initialWorkspaceRoot, authMode) {
         this.serverConfig = serverConfig;
         this.authMode = authMode;
@@ -44,12 +48,97 @@ export class WorkspaceSessionManager {
             requireExistingRoot: true,
         });
     }
+    listBackups() {
+        return listWorkspaceBackups(this.currentState.paths);
+    }
+    createBackup(label) {
+        return createWorkspaceBackup(this.currentState.paths, {
+            workspaceName: this.currentState.workspaceInfo.workspaceName,
+            appVersion: RECALLX_VERSION,
+            label,
+            now: new Date().toISOString(),
+        });
+    }
+    exportWorkspace(format) {
+        const repository = this.currentState.repository;
+        const payload = {
+            workspace: this.currentState.workspaceInfo,
+            nodes: repository.listAllNodes(),
+            relations: repository.listAllRelations(),
+            activities: repository.listAllActivities(),
+            artifacts: repository.listAllArtifacts(),
+            integrations: repository.listIntegrations(),
+            settings: repository.getSettings(),
+        };
+        const markdown = [
+            `# ${this.currentState.workspaceInfo.workspaceName}`,
+            "",
+            `- exportedAt: ${new Date().toISOString()}`,
+            `- workspaceRoot: ${this.currentState.workspaceRoot}`,
+            `- nodes: ${payload.nodes.length}`,
+            `- relations: ${payload.relations.length}`,
+            `- activities: ${payload.activities.length}`,
+            `- artifacts: ${payload.artifacts.length}`,
+            `- integrations: ${payload.integrations.length}`,
+            "",
+            "## Recent Nodes",
+            ...payload.nodes.slice(0, 20).map((node) => `- ${node.title ?? node.id} (${node.type})`),
+        ].join("\n");
+        return exportWorkspaceSnapshot(this.currentState.paths, {
+            workspaceName: this.currentState.workspaceInfo.workspaceName,
+            appVersion: RECALLX_VERSION,
+            now: new Date().toISOString(),
+            format,
+            payload,
+            markdown,
+        });
+    }
+    previewImportWorkspace(format, sourcePath, label, options) {
+        return previewImportIntoWorkspace({
+            repository: this.currentState.repository,
+            format,
+            sourcePath,
+            label,
+            options,
+            now: new Date().toISOString(),
+        });
+    }
+    importWorkspace(format, sourcePath, label, options) {
+        const backup = this.createBackup(label ? `before-import ${label}` : "before-import");
+        return importIntoWorkspace({
+            repository: this.currentState.repository,
+            paths: this.currentState.paths,
+            format,
+            sourcePath,
+            label,
+            options,
+            now: new Date().toISOString(),
+            backup,
+        });
+    }
+    restoreBackup(backupId, targetRootPath, workspaceName) {
+        const autoBackup = this.createBackup(workspaceName ? `before-restore ${workspaceName}` : "before-restore");
+        const manifest = restoreWorkspaceBackup(this.currentState.paths, {
+            backupId,
+            targetRootPath,
+        });
+        return {
+            workspace: this.swapWorkspace(targetRootPath, {
+                workspaceName: workspaceName?.trim() || manifest.workspaceName,
+                requireExistingRoot: true,
+            }),
+            autoBackup,
+        };
+    }
+    shutdown() {
+        this.closeState(this.currentState);
+    }
     swapWorkspace(rootPath, options) {
         const nextState = this.loadWorkspace(rootPath, options);
         const previousState = this.currentState;
         this.currentState = nextState;
         this.remember(nextState);
-        previousState.db.close();
+        this.closeState(previousState);
         return this.getWorkspaceCatalogItem(nextState);
     }
     loadWorkspace(rootPath, options) {
@@ -61,9 +150,10 @@ export class WorkspaceSessionManager {
         const db = openDatabase(paths);
         const repository = new RecallXRepository(db, resolvedRoot);
         const storedSettings = repository.getSettings(["workspace.name"]);
-        const resolvedName = typeof storedSettings["workspace.name"] === "string" && storedSettings["workspace.name"].trim()
-            ? String(storedSettings["workspace.name"])
-            : options.workspaceName?.trim() || defaultWorkspaceName(resolvedRoot);
+        const resolvedName = options.workspaceName?.trim() ||
+            (typeof storedSettings["workspace.name"] === "string" && storedSettings["workspace.name"].trim()
+                ? String(storedSettings["workspace.name"])
+                : defaultWorkspaceName(resolvedRoot));
         repository.setSetting("workspace.name", resolvedName);
         repository.setSetting("workspace.version", RECALLX_VERSION);
         repository.setSetting("api.bind", `${this.serverConfig.bindAddress}:${this.serverConfig.port}`);
@@ -105,6 +195,12 @@ export class WorkspaceSessionManager {
         repository.ensureSearchTagIndex();
         repository.ensureActivitySearchIndex();
         bootstrapAutomaticGovernance(repository);
+        const now = new Date().toISOString();
+        const safety = beginWorkspaceSession(paths, {
+            sessionId: this.processSessionId,
+            appVersion: RECALLX_VERSION,
+            now,
+        });
         return {
             db,
             repository,
@@ -113,9 +209,25 @@ export class WorkspaceSessionManager {
             workspaceInfo: workspaceInfo(resolvedRoot, {
                 ...this.serverConfig,
                 workspaceName: resolvedName,
-            }, this.authMode),
+            }, this.authMode, {
+                dbPath: paths.dbPath,
+                artifactsDir: paths.artifactsDir,
+                exportsDir: paths.exportsDir,
+                importsDir: paths.importsDir,
+                backupsDir: paths.backupsDir,
+                configDir: paths.configDir,
+                cacheDir: paths.cacheDir,
+            }, safety),
         };
     }
+    closeState(state) {
+        endWorkspaceSession(state.paths, {
+            sessionId: this.processSessionId,
+            appVersion: RECALLX_VERSION,
+            now: new Date().toISOString(),
+        });
+        state.db.close();
+    }
     remember(state) {
         this.history.set(state.workspaceRoot, this.getWorkspaceCatalogItem(state));
     }
@@ -123,7 +235,7 @@ export class WorkspaceSessionManager {
         return {
             ...state.workspaceInfo,
             isCurrent: state.workspaceRoot === this.currentState?.workspaceRoot,
-            lastOpenedAt: new Date().toISOString(),
+            lastOpenedAt: state.workspaceInfo.safety?.lastOpenedAt ?? new Date().toISOString(),
         };
     }
 }

package/app/shared/contracts.js

@@ -43,6 +43,7 @@ export const searchFeedbackResultTypes = ["node", "activity"];
 export const searchFeedbackVerdicts = ["useful", "not_useful", "uncertain"];
 export const governanceEntityTypes = ["node", "relation"];
 export const governanceStates = ["healthy", "low_confidence", "contested"];
+export const governanceDecisionActions = ["promote", "contest", "archive", "accept", "reject"];
 export const governanceEventTypes = [
     "evaluated",
     "promoted",
@@ -165,6 +166,11 @@ export const governanceIssuesQuerySchema = z.object({
     states: z.array(z.enum(governanceStates)).optional(),
     limit: z.number().int().min(1).max(100).default(20)
 });
+export const governanceEventsQuerySchema = z.object({
+    entityTypes: z.array(z.enum(governanceEntityTypes)).optional(),
+    actions: z.array(z.enum(governanceDecisionActions)).optional(),
+    limit: z.number().int().min(1).max(100).default(12)
+});
 export const recomputeGovernanceSchema = z.object({
     entityType: z.enum(governanceEntityTypes).optional(),
     entityIds: z.array(z.string().min(1)).max(200).optional(),
@@ -192,6 +198,18 @@ export const updateNodeSchema = z.object({
     metadata: z.record(z.any()).optional(),
     status: z.enum(nodeStatuses).optional()
 });
+export const governanceNodeActionSchema = z.object({
+    action: z.enum(["promote", "contest", "archive"]),
+    note: z.string().max(280).optional(),
+    source: sourceSchema,
+    metadata: z.record(z.any()).default({})
+});
+export const governanceRelationActionSchema = z.object({
+    action: z.enum(["accept", "reject", "archive"]),
+    note: z.string().max(280).optional(),
+    source: sourceSchema,
+    metadata: z.record(z.any()).default({})
+});
 export const createRelationSchema = z.object({
     fromNodeId: z.string().min(1),
     toNodeId: z.string().min(1),
@@ -314,3 +332,26 @@ export const createWorkspaceSchema = z.object({
 export const openWorkspaceSchema = z.object({
     rootPath: z.string().min(1)
 });
+export const createWorkspaceBackupSchema = z.object({
+    label: z.string().min(1).max(80).optional()
+});
+export const exportWorkspaceSchema = z.object({
+    format: z.enum(["json", "markdown"]).default("json")
+});
+export const workspaceImportOptionsSchema = z.object({
+    normalizeTitleWhitespace: z.boolean().optional(),
+    trimBodyWhitespace: z.boolean().optional(),
+    duplicateMode: z.enum(["warn", "skip_exact"]).optional()
+});
+export const importWorkspacePreviewSchema = z.object({
+    format: z.enum(["recallx_json", "markdown"]),
+    sourcePath: z.string().min(1),
+    label: z.string().min(1).max(120).optional(),
+    options: workspaceImportOptionsSchema.optional()
+});
+export const importWorkspaceSchema = importWorkspacePreviewSchema;
+export const restoreWorkspaceBackupSchema = z.object({
+    backupId: z.string().min(1),
+    targetRootPath: z.string().min(1),
+    workspaceName: z.string().min(1).optional()
+});

package/app/shared/version.js

@@ -1 +1 @@
-export const RECALLX_VERSION = "1.1.0";
+export const RECALLX_VERSION = "1.2.0";