@jini-ai/platform 0.5.1 → 0.5.3

package/dist/fs/directory-user-config.d.ts

@@ -0,0 +1,79 @@
+import type { DurableJsonFile } from "./durable-json.js";
+import { type UserDirectoryOptions } from "./user-data-directories.js";
+export interface DirectoryUserConfig {
+    sitesHome: string;
+    siteRoots: string[];
+    databases: "inSite" | "appData";
+}
+export interface DirectoryUserConfigPolicy {
+    appName: string;
+    rootsEnvName: string;
+    sourceRoots?: readonly string[];
+    legacySettingsFile?: string;
+    legacyDefaultFolder?: string;
+    /** Nest new workspaces while retaining immediate old-level children for discovery. */
+    defaultSubfolder?: string;
+}
+/** One atomic settings owner for multiple processes. Existing DB files always win over preferences:
+ * changing placement controls new databases, never silently moves or abandons existing ones.
+ * @complexity O(n) canonicalizations for n roots; DB lookup probes three fixed locations.
+ */
+export declare function createDirectoryUserConfig({ homeDir, defaultFolder, envName, policy, fileAt, canonicalPath, exists, isDirectory, removeFile }: {
+    homeDir: string;
+    defaultFolder: string;
+    envName: string;
+    policy: DirectoryUserConfigPolicy;
+    fileAt: (file: string) => DurableJsonFile;
+    canonicalPath: (required: {
+        path: string;
+    }) => string;
+    exists: (file: string) => boolean;
+    isDirectory: (file: string) => boolean;
+    removeFile?: (required: {
+        filePath: string;
+    }) => void;
+}, { env, cwd, report, ...directoryOptions }?: UserDirectoryOptions & {
+    cwd?: string;
+    report?: (message: string) => void;
+}): {
+    legacyHomes: (_required: Record<string, never>, { includeMissing }?: {
+        includeMissing?: boolean;
+    }) => string[];
+    defaultRoots: (_required: Record<string, never>, _options?: {}) => string[];
+    extraRoots: (_required: Record<string, never>, _options?: {}) => string[];
+    roots: (_required: Record<string, never>, _options?: {}) => string[];
+    runningPath: ({ dir }: {
+        dir: string;
+    }, _options?: {}) => string;
+    syncWarning: (_required: Record<string, never>, _options?: {}) => {
+        provider: "OneDrive" | "Dropbox" | "Google Drive";
+        message: string;
+        localHome: string;
+    } | null;
+    appData: string;
+    documents: string;
+    read: (_required: Record<string, never>, _options?: {}) => DirectoryUserConfig;
+    update: ({ patch }: {
+        patch: Partial<DirectoryUserConfig>;
+    }, { transform }?: {
+        transform?: (current: DirectoryUserConfig, saved: Partial<DirectoryUserConfig>) => Partial<DirectoryUserConfig>;
+    }) => DirectoryUserConfig;
+    updateRoots: ({ add, remove }: {
+        add?: readonly string[];
+        remove?: readonly string[];
+    }, _options?: {}) => DirectoryUserConfig;
+    databasePath: ({ dir, id, filename, placement }: {
+        dir: string;
+        id: string;
+        filename: string;
+        placement?: DirectoryUserConfig["databases"];
+    }, _options?: {}) => string;
+    filePath: string;
+};
+/** Validate only the three public settings; reject arrays, unknown fields and invalid enums.
+ * @complexity O(n) root strings. No I/O or mutation.
+ */
+export declare function validateDirectoryUserConfig({ value }: {
+    value: unknown;
+}, _options?: {}): Partial<DirectoryUserConfig>;
+//# sourceMappingURL=directory-user-config.d.ts.map

package/dist/fs/directory-user-config.js

@@ -0,0 +1,183 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { resolveDirectoryHome } from "./directory-home.js";
+import { resolveUserDataDirectories } from "./user-data-directories.js";
+import { detectDirectorySync } from "./directory-sync.js";
+/** One atomic settings owner for multiple processes. Existing DB files always win over preferences:
+ * changing placement controls new databases, never silently moves or abandons existing ones.
+ * @complexity O(n) canonicalizations for n roots; DB lookup probes three fixed locations.
+ */
+export function createDirectoryUserConfig({ homeDir, defaultFolder, envName, policy, fileAt, canonicalPath, exists, isDirectory, removeFile }, { env = process.env, cwd = process.cwd(), report = console.warn, ...directoryOptions } = {}) {
+    const directories = resolveUserDataDirectories({ homeDir, appName: policy.appName }, { ...directoryOptions, env });
+    const paths = directoryOptions.platform === "win32" ? path.win32 : path;
+    const defaultHome = paths.join(directories.documents, defaultFolder, policy.defaultSubfolder ?? "");
+    const localHome = paths.join(homeDir, defaultFolder, policy.defaultSubfolder ?? "");
+    const legacyHomePaths = policy.defaultSubfolder ? [paths.join(directories.documents, defaultFolder), paths.join(homeDir, defaultFolder)] : [];
+    const filePath = paths.join(directories.appData, "config.json"), file = fileAt(filePath);
+    const expand = (value) => canonicalPath({ path: resolveDirectoryHome({ homeDir, defaultFolder, envName, env: {}, setting: value }, { cwd, ...(directoryOptions.platform ? { platform: directoryOptions.platform } : {}) }) });
+    const distinct = (values) => [...new Set(values.map(expand))];
+    const legacyHomes = distinct(legacyHomePaths);
+    function stored(locked = false) {
+        const result = file.read({});
+        if (result.state === "missing")
+            return {};
+        if (result.state === "ok") {
+            try {
+                return validateDirectoryUserConfig({ value: result.value });
+            }
+            catch { /* preserve invalid settings too */ }
+        }
+        // Bad settings must not stop boot, and read-only discovery/dry-run must not mutate settings.
+        // Preserve the original on reads; the next mutation quarantines it under the existing lock.
+        if (!locked) {
+            report(`User config is unreadable: ${filePath}. Using defaults; the original was left untouched.`);
+            return {};
+        }
+        if (!file.quarantine({ notice: { label: "user config", consequence: "Using default settings; existing databases keep their locations." } })) {
+            throw new Error(`User config is unreadable: ${filePath}. Nothing was overwritten.`);
+        }
+        return {};
+    }
+    const syncProvider = (sitesHome) => detectDirectorySync({ dir: sitesHome, homeDir, documents: directories.documents }, { ...directoryOptions, env, canonicalPath });
+    function read(_required, _options = {}) {
+        const saved = stored();
+        // Old default pointers follow the owner-selected nesting rule; arbitrary custom homes and
+        // explicit environment overrides keep their contracts. Reading never moves user folders.
+        const savedHome = saved.sitesHome === undefined ? defaultHome : expand(saved.sitesHome);
+        const nestedHome = legacyHomes.includes(savedHome) ? paths.join(savedHome, policy.defaultSubfolder) : savedHome;
+        const sitesHome = expand(env[envName] ?? nestedHome);
+        const sync = syncProvider(sitesHome);
+        return {
+            sitesHome,
+            siteRoots: distinct(env[policy.rootsEnvName] !== undefined ? env[policy.rootsEnvName].split(",").map((root) => root.trim()).filter(Boolean) : saved.siteRoots ?? policy.sourceRoots ?? []),
+            databases: saved.databases ?? (sync && sync !== "iCloud" ? "appData" : "inSite"),
+        };
+    }
+    function update({ patch }, { transform } = {}) {
+        // Compute incremental root changes inside the same lock as the write: a sibling process's
+        // added root must not disappear because this caller previously read an older array.
+        file.withLock({ critical: () => {
+                const previous = stored(true);
+                const checked = validateDirectoryUserConfig({ value: transform ? transform(read({}), previous) : patch });
+                // Prefer explicit settings, never coerce an existing regular file into a directory.
+                for (const directory of [checked.sitesHome, ...(checked.siteRoots ?? [])]) {
+                    if (directory === undefined)
+                        continue;
+                    const expanded = expand(directory);
+                    if (exists(expanded) && !isDirectory(expanded))
+                        throw new Error(`Sites folder is not a directory: ${directory}`);
+                }
+                if (checked.sitesHome !== undefined && env[envName] !== undefined)
+                    throw new Error(`${envName} overrides this setting. Unset it before changing the directory home.`);
+                if (checked.siteRoots !== undefined && env[policy.rootsEnvName] !== undefined)
+                    throw new Error(`${policy.rootsEnvName} overrides this setting. Unset it before changing site roots.`);
+                const next = { ...previous, ...checked,
+                    ...(checked.sitesHome !== undefined ? { sitesHome: expand(checked.sitesHome) } : {}),
+                    ...(checked.siteRoots !== undefined ? { siteRoots: distinct(checked.siteRoots) } : {}),
+                };
+                // Empty incremental extras restore implicit defaults instead of persisting those defaults.
+                if (transform && checked.siteRoots?.length === 0)
+                    delete next.siteRoots;
+                // With no other saved settings, removing the final extra also restores an absent config.
+                // The Node assembly supplies removal; non-Node adapters may retain the equivalent {}.
+                if (transform && Object.keys(next).length === 0 && removeFile)
+                    removeFile({ filePath });
+                else
+                    file.write({ value: next });
+            } });
+        return read({});
+    }
+    function updateRoots({ add = [], remove = [] }, _options = {}) {
+        return update({ patch: {} }, { transform: (current, saved) => {
+                const protectedRoots = new Set(distinct([current.sitesHome, ...(policy.sourceRoots ?? [])]));
+                const excluded = new Set(distinct(remove));
+                return { siteRoots: distinct([...(saved.siteRoots ?? []), ...add]).filter((root) => !excluded.has(root) && !protectedRoots.has(root)) };
+            } });
+    }
+    function databasePath({ dir, id, filename, placement }, _options = {}) {
+        if (path.basename(filename) !== filename || !filename.endsWith(".db"))
+            throw new Error("A database filename must be a .db basename.");
+        const inSite = path.join(dir, "data.nosync", filename), legacy = path.join(dir, filename);
+        if (!/^[a-zA-Z0-9_-]+$/.test(id)) {
+            if (!placement && exists(legacy))
+                return legacy;
+            throw new Error("A database directory requires a safe, stable site identity.");
+        }
+        const appData = path.join(directories.appData, "databases", id, filename);
+        if (placement)
+            return placement === "inSite" ? inSite : appData;
+        const candidates = [legacy, inSite, appData];
+        // A move journal is written before copying; the old name stays authoritative until verification
+        // retires it. Recovery never guesses from two DB sizes/timestamps or asks users to delete data.
+        for (const source of candidates) {
+            const markerPath = source + ".home2-relocation.json", marker = fileAt(markerPath).read({});
+            if (marker.state === "missing")
+                continue;
+            const target = marker.state === "ok" ? marker.value?.to : undefined;
+            if (typeof target !== "string" || !candidates.includes(target))
+                throw new Error(`Interrupted database move has an invalid recovery marker: ${markerPath}. Restore the pre-move backup before starting.`);
+            const namedBackup = marker.state === "ok" ? marker.value?.backup : undefined;
+            // Old markers use the fixed home2 name; new moves identify their unique backup. Admit
+            // only a sibling of this source so malformed metadata cannot supply unrelated evidence.
+            if (namedBackup !== undefined && (typeof namedBackup !== "string" || path.dirname(namedBackup) !== path.dirname(source) || !namedBackup.startsWith(source + ".relocation-") || !namedBackup.endsWith("-backup")))
+                throw new Error(`Interrupted database move has an invalid recovery marker: ${markerPath}. Restore the pre-move backup before starting.`);
+            const backup = typeof namedBackup === "string" ? namedBackup : source + ".home2-backup";
+            const authoritative = exists(source) ? source : exists(backup) && exists(target) ? target : undefined;
+            if (!authoritative)
+                throw new Error(`Interrupted database move needs recovery: ${markerPath}. Restore the pre-move backup before starting.`);
+            report(`Recovered interrupted database move using ${authoritative}. Keep the backup files (${backup}); finish the move before changing database placement.`);
+            return authoritative;
+        }
+        const present = candidates.filter(exists);
+        if (present.length > 1)
+            throw new Error(`Multiple copies of ${filename} exist for this site. Choose the authoritative database before starting it.`);
+        if (present[0])
+            return present[0];
+        // A missing chat DB follows an existing content DB even after the user changes preferences.
+        if (filename !== "content.db") {
+            const content = databasePath({ dir, id, filename: "content.db" });
+            return path.join(path.dirname(content), filename);
+        }
+        return read({}).databases === "inSite" ? inSite : appData;
+    }
+    return { read, update, updateRoots, databasePath, filePath, ...directories,
+        // Discovery/catalog callers list real old homes. Pointer normalization and creation admission
+        // may inspect the supported spellings even before their directories have been created.
+        legacyHomes: (_required, { includeMissing = false } = {}) => distinct(legacyHomes).filter((root) => includeMissing || (exists(root) && isDirectory(root))),
+        defaultRoots: (_required, _options = {}) => distinct(policy.sourceRoots ?? []),
+        extraRoots: (_required, _options = {}) => distinct(env[policy.rootsEnvName] !== undefined ? read({}).siteRoots : stored().siteRoots ?? []),
+        roots: (_required, _options = {}) => {
+            const config = read({}), parent = paths.dirname(config.sitesHome);
+            // Discover only the selected home's existing former level. Scanning another old home
+            // crosses the local/synced boundary and admits broad or absent roots at every boot.
+            const formerRoots = legacyHomes.includes(parent) && exists(parent) && isDirectory(parent) ? [parent] : [];
+            return distinct([config.sitesHome, ...formerRoots, ...(policy.sourceRoots ?? []), ...config.siteRoots]);
+        },
+        runningPath: ({ dir }, _options = {}) => path.join(directories.appData, "running", createHash("sha256").update(canonicalPath({ path: dir })).digest("hex") + ".json"),
+        syncWarning: (_required, _options = {}) => {
+            const config = read({});
+            const sync = syncProvider(config.sitesHome);
+            if (!sync || sync === "iCloud")
+                return null;
+            return { provider: sync, message: config.databases === "appData" ? `${sync} syncs the sites folder. New databases use OS app-data for safety. Site folders are not self-contained: include their app-data databases when transferring them.` : `${sync} syncs the sites folder. It does not honor data.nosync; syncing live SQLite databases can corrupt them. Use app-data databases or a local sites folder.`, localHome };
+        },
+    };
+}
+/** Validate only the three public settings; reject arrays, unknown fields and invalid enums.
+ * @complexity O(n) root strings. No I/O or mutation.
+ */
+export function validateDirectoryUserConfig({ value }, _options = {}) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("User config must be an object.");
+    const row = value;
+    if (Object.keys(row).some((key) => !["sitesHome", "siteRoots", "databases"].includes(key)))
+        throw new Error("Unknown user config setting.");
+    if (row.sitesHome !== undefined && (typeof row.sitesHome !== "string" || !row.sitesHome.trim()))
+        throw new Error("sitesHome must name a directory.");
+    if (row.siteRoots !== undefined && (!Array.isArray(row.siteRoots) || !row.siteRoots.every((root) => typeof root === "string" && root.trim())))
+        throw new Error("siteRoots must be an array of directory paths.");
+    if (row.databases !== undefined && row.databases !== "inSite" && row.databases !== "appData")
+        throw new Error('databases must be "inSite" or "appData".');
+    return row;
+}
+//# sourceMappingURL=directory-user-config.js.map

package/dist/fs/directory-workspace.d.ts

@@ -0,0 +1,132 @@
+import { type DurableJsonPorts, type DurableJsonChange } from "./durable-json.js";
+import { type DirectoryUserConfigPolicy, type DirectoryUserConfig } from "./directory-user-config.js";
+import type { UserDirectoryOptions } from "./user-data-directories.js";
+import { type DirectoryRegistry } from "./directory-registry.js";
+/** Node assembly only. Policy modules receive explicit filesystem, clock and process ports.
+ * Settings live outside the selected home so changing the setting never loses the pointer.
+ * Reading a missing home/catalog does not create it. Opt-in registry recovery may prune known
+ * pollution on load; read-only hosts omit that policy. Mutations use the durable JSON owner.
+ * @complexity O(n) registry records, O(1) settings/lease operations.
+ */
+export declare function createNodeDirectoryWorkspace({ homeDir, defaultFolder, envName, settingsFile, registryName, runningName, userConfig, registryRecovery }: {
+    homeDir: string;
+    defaultFolder: string;
+    envName: string;
+    settingsFile: string;
+    registryName: string;
+    runningName: string;
+    userConfig?: DirectoryUserConfigPolicy;
+    /** Opt-in host recovery of known test pollution; missing user directories alone never qualify. */
+    registryRecovery?: {
+        fixtureIdPattern: RegExp;
+        temporaryRoots?: readonly string[];
+    };
+}, { env, cwd, ports, canonicalPath, ...directoryOptions }?: UserDirectoryOptions & {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    ports?: DurableJsonPorts;
+    canonicalPath?: (required: {
+        path: string;
+    }) => string;
+}): {
+    homeDir: string;
+    config: (_required: Record<string, never>, _options?: {}) => {
+        defaultRoots: string[];
+        extraRoots: string[];
+        configPath: string;
+        appData: string;
+        warning: {
+            provider: "OneDrive" | "Dropbox" | "Google Drive";
+            message: string;
+            localHome: string;
+        } | null;
+        overrides: {
+            sitesHome: boolean;
+            siteRoots: boolean;
+        };
+        sitesHome: string;
+        siteRoots: string[];
+        databases: "inSite" | "appData";
+    };
+    updateConfig: (required: {
+        patch: Partial<DirectoryUserConfig>;
+    }, options?: {}) => {
+        defaultRoots: string[];
+        extraRoots: string[];
+        configPath: string;
+        appData: string;
+        warning: {
+            provider: "OneDrive" | "Dropbox" | "Google Drive";
+            message: string;
+            localHome: string;
+        } | null;
+        overrides: {
+            sitesHome: boolean;
+            siteRoots: boolean;
+        };
+        sitesHome: string;
+        siteRoots: string[];
+        databases: "inSite" | "appData";
+    };
+    updateRoots: (required: {
+        add?: readonly string[];
+        remove?: readonly string[];
+    }, options?: {}) => {
+        defaultRoots: string[];
+        extraRoots: string[];
+        configPath: string;
+        appData: string;
+        warning: {
+            provider: "OneDrive" | "Dropbox" | "Google Drive";
+            message: string;
+            localHome: string;
+        } | null;
+        overrides: {
+            sitesHome: boolean;
+            siteRoots: boolean;
+        };
+        sitesHome: string;
+        siteRoots: string[];
+        databases: "inSite" | "appData";
+    };
+    roots: (_required: Record<string, never>, _options?: {}) => string[];
+    databasePath: (required: {
+        dir: string;
+        id: string;
+        filename: string;
+        placement?: DirectoryUserConfig["databases"];
+    }, options?: {}) => string;
+    /** Only the implicit nested home may create its application parent below mounted Documents.
+     * Custom homes still require their immediate parent, so an absent volume is never fabricated.
+     */
+    homeAvailable: (_required: Record<string, never>, _options?: {}) => boolean;
+    legacyHomes: (_required: Record<string, never>, _options?: {}) => string[];
+    /** Commit a verified move's catalog and every injected path reference as one locked unit.
+     * Uses the registry owner to preserve identity/collision rules; settings retain env precedence.
+     * @complexity O(total catalog/reference bytes), with rollback snapshots in memory.
+     */
+    relocate({ from, to, entry, references }: {
+        from: string;
+        to: string;
+        entry: import("./directory-registry.js").DirectoryRecord;
+        references?: readonly DurableJsonChange[];
+    }, _options?: {}): void;
+    home: (_required: Record<string, never>, _options?: {}) => string;
+    setHome({ path: dir }: {
+        path: string;
+    }, _options?: {}): string;
+    registry: (_required: Record<string, never>, _options?: {}) => DirectoryRegistry;
+    running: ({ path: dir }: {
+        path: string;
+    }, _options?: {}) => import("./directory-running-lock.js").DirectoryRunningLock;
+    claim({ path: dir, app, port, scheme }: {
+        path: string;
+        app: string;
+        port?: number;
+        scheme?: "http" | "https";
+    }, _options?: {}): {
+        acquired: boolean;
+        record: import("./directory-running-lock.js").DirectoryRunningRecord;
+    };
+};
+//# sourceMappingURL=directory-workspace.d.ts.map