datanotes 2.0.1 → 3.0.0

package/dist/api/local.cjs

@@ -30,8 +30,22 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/api/local.ts
 var local_exports = {};
 __export(local_exports, {
+  DEFAULT_DATABASE_FOLDER: () => DEFAULT_DATABASE_FOLDER,
+  LOCK_FILE: () => LOCK_FILE,
   LOCK_STALE_MS: () => LOCK_STALE_MS,
+  METASTORE: () => METASTORE,
+  REGISTRY_FILE: () => REGISTRY_FILE,
+  SETTINGS_FILE: () => SETTINGS_FILE,
+  STORE_RECORD_FILE: () => STORE_RECORD_FILE,
+  dataHome: () => dataHome,
+  databaseIdIn: () => databaseIdIn,
   localEngine: () => localEngine,
+  readDatabaseId: () => readDatabaseId,
+  readRegistry: () => readRegistry,
+  storeLocation: () => storeLocation,
+  vaultDatabaseFolder: () => vaultDatabaseFolder,
+  vaultKey: () => vaultKey,
+  vaultMetastores: () => vaultMetastores,
   vaultSettingsPath: () => vaultSettingsPath
 });
 module.exports = __toCommonJS(local_exports);
@@ -39,29 +53,127 @@ var import_node_fs = __toESM(require("node:fs"), 1);
 var import_node_os = __toESM(require("node:os"), 1);
 var import_node_path = __toESM(require("node:path"), 1);
 var LOCK_STALE_MS = 3e4;
-function vaultSettingsPath(vault) {
-  return import_node_path.default.join(vault, ".datanotes", "service.json");
+var SETTINGS_FILE = "settings.json";
+var LOCK_FILE = "engine.lock";
+var STORE_RECORD_FILE = "store.json";
+var REGISTRY_FILE = "vaults.json";
+var DEFAULT_DATABASE_FOLDER = "datanotes";
+var METASTORE = "metastore.yaml";
+function dataHome(env = process.env, platform = process.platform, home = import_node_os.default.homedir()) {
+  if (env.DATANOTES_DATA_HOME) return import_node_path.default.resolve(env.DATANOTES_DATA_HOME);
+  if (platform === "win32") return import_node_path.default.join(env.LOCALAPPDATA || import_node_path.default.join(home, "AppData", "Local"), "Datanotes");
+  if (platform === "darwin") return import_node_path.default.join(home, "Library", "Application Support", "Datanotes");
+  return import_node_path.default.join(env.XDG_DATA_HOME || import_node_path.default.join(home, ".local", "share"), "datanotes");
+}
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function readDatabaseId(text) {
+  const m = /^id:[ \t]*(.*)$/m.exec(text);
+  const value = m ? m[1].replace(/#.*$/, "").trim().replace(/^["']|["']$/g, "") : "";
+  return UUID.test(value) ? value.toLowerCase() : null;
+}
+function databaseIdIn(vault, database) {
+  try {
+    return readDatabaseId(import_node_fs.default.readFileSync(import_node_path.default.join(vault, ...database.split("/"), METASTORE), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function vaultMetastores(vault) {
+  const out = [];
+  const walk = (dir, rel) => {
+    let ents;
+    try {
+      ents = import_node_fs.default.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of ents) {
+      if (e.name.startsWith(".") || e.name === "node_modules") continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(import_node_path.default.join(dir, e.name), r);
+      else if (e.name === METASTORE) out.push(rel);
+    }
+  };
+  walk(vault, "");
+  return out.sort();
+}
+function vaultKey(vault, platform = process.platform) {
+  let real = import_node_path.default.resolve(vault);
+  try {
+    real = import_node_fs.default.realpathSync.native(real);
+  } catch {
+  }
+  return platform === "win32" ? real.toLowerCase() : real;
 }
 function readJson(file) {
   try {
-    return JSON.parse(import_node_fs.default.readFileSync(file, "utf8"));
+    const v = JSON.parse(import_node_fs.default.readFileSync(file, "utf8"));
+    return v && typeof v === "object" && !Array.isArray(v) ? v : null;
   } catch {
     return null;
   }
 }
+function readRegistry(home) {
+  const raw = readJson(import_node_path.default.join(home, REGISTRY_FILE)) ?? {};
+  const out = {};
+  for (const [k, v] of Object.entries(raw)) {
+    const r = v;
+    if (r && typeof r.id === "string" && UUID.test(r.id) && typeof r.database === "string") out[k] = { id: r.id, database: r.database };
+  }
+  return out;
+}
+function vaultDatabaseFolder(vault) {
+  const found = vaultMetastores(vault);
+  return found.length === 1 ? found[0] : DEFAULT_DATABASE_FOLDER;
+}
+function storeLocation(vault, opts = {}) {
+  const env = opts.env ?? process.env;
+  const explicit = opts.store ?? env.DATANOTES_STORE;
+  if (explicit) {
+    const store = import_node_path.default.resolve(explicit);
+    const rec = readJson(import_node_path.default.join(store, STORE_RECORD_FILE));
+    const database2 = typeof rec?.database === "string" ? rec.database : vaultDatabaseFolder(vault);
+    return { store, id: typeof rec?.id === "string" ? rec.id : databaseIdIn(vault, database2), database: database2 };
+  }
+  const home = dataHome(env);
+  const known = readRegistry(home)[vaultKey(vault)];
+  if (known) return { store: import_node_path.default.join(home, known.id), id: known.id, database: known.database };
+  const database = vaultDatabaseFolder(vault);
+  const id = databaseIdIn(vault, database);
+  return id ? { store: import_node_path.default.join(home, id), id, database } : null;
+}
+function vaultSettingsPath(vault, opts = {}) {
+  const loc = storeLocation(vault, opts);
+  return loc ? import_node_path.default.join(loc.store, SETTINGS_FILE) : null;
+}
 function localEngine(vault, opts = {}) {
-  const settings = readJson(opts.settingsFile ?? vaultSettingsPath(vault)) ?? {};
-  const store = typeof settings.storeFolder === "string" && settings.storeFolder ? settings.storeFolder : ".datanotes";
-  const lock = readJson(import_node_path.default.join(vault, store.replace(/\/+$/, ""), "engine.lock"));
+  const loc = storeLocation(vault, opts);
+  if (!loc) return null;
+  const lock = readJson(import_node_path.default.join(loc.store, LOCK_FILE));
   if (!lock || (opts.now ?? Date.now()) - Date.parse(lock.heartbeat) >= LOCK_STALE_MS) return null;
   if (lock.host !== import_node_os.default.hostname()) throw new Error(`the vault is held by an engine on ${lock.host}; connect to it by its address`);
+  const settings = readJson(opts.settingsFile ?? import_node_path.default.join(loc.store, SETTINGS_FILE)) ?? {};
   const token = typeof settings.httpServerToken === "string" ? settings.httpServerToken : "";
   if (!token) return null;
   return { url: `http://${opts.host ?? "127.0.0.1"}:${lock.port}`, token, lock };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_DATABASE_FOLDER,
+  LOCK_FILE,
   LOCK_STALE_MS,
+  METASTORE,
+  REGISTRY_FILE,
+  SETTINGS_FILE,
+  STORE_RECORD_FILE,
+  dataHome,
+  databaseIdIn,
   localEngine,
+  readDatabaseId,
+  readRegistry,
+  storeLocation,
+  vaultDatabaseFolder,
+  vaultKey,
+  vaultMetastores,
   vaultSettingsPath
 });

package/dist/api/local.d.cts

@@ -0,0 +1,95 @@
+/**
+ * Find the engine running on a vault of this machine (Node only): its address and the owner's
+ * token, read from the database's store, where the engine keeps its settings and the lock it holds
+ * while it runs.
+ *
+ * The store is outside the vault, in the operating system's per-user data folder:
+ * `<data home>/<database id>/`, the id being `id` in the database's `metastore.yaml`. The data home
+ * is `%LOCALAPPDATA%\Datanotes` on Windows, `~/Library/Application Support/Datanotes` on macOS and
+ * `$XDG_DATA_HOME/datanotes` (`~/.local/share/datanotes`) elsewhere. `DATANOTES_DATA_HOME` moves the
+ * data home, `DATANOTES_STORE` (or `--store`) names the store folder itself. The engine finds a
+ * vault's database again through `vaults.json` in the data home (vault → id and database folder).
+ */
+/** The lock an engine writes in its store (`<store>/engine.lock`). */
+export interface EngineLock {
+    kind: "service";
+    pid: number;
+    host: string;
+    port: number;
+    startedAt: string;
+    heartbeat: string;
+}
+/** A lock whose heartbeat is older than this belongs to an engine that stopped. */
+export declare const LOCK_STALE_MS = 30000;
+/** The engine's settings file, in the store. */
+export declare const SETTINGS_FILE = "settings.json";
+/** The lock, in the store. */
+export declare const LOCK_FILE = "engine.lock";
+/** The store's record of its database: id, vault, database folder. */
+export declare const STORE_RECORD_FILE = "store.json";
+/** In the data home: the vaults this machine's engines opened, with their database. */
+export declare const REGISTRY_FILE = "vaults.json";
+/** The database folder of a new database: a top-level folder of the vault. */
+export declare const DEFAULT_DATABASE_FOLDER = "datanotes";
+export declare const METASTORE = "metastore.yaml";
+type Env = Record<string, string | undefined>;
+/** The data home: the folder that holds the stores of this user's databases. */
+export declare function dataHome(env?: Env, platform?: string, home?: string): string;
+/** The database id of a `metastore.yaml` text (its top-level `id:`), or null. */
+export declare function readDatabaseId(text: string): string | null;
+/** The database id of a vault's database folder, or null (no metastore, or no id in it). */
+export declare function databaseIdIn(vault: string, database: string): string | null;
+/**
+ * The folders of a vault on disk that hold a `metastore.yaml` (vault-relative with `/`, sorted).
+  * A vault has exactly one database folder, anywhere ("" for the root: --database). Dot-folders and
+ * `node_modules` are left out.
+ */
+export declare function vaultMetastores(vault: string): string[];
+/** A vault as the registry names it: its real path (lowercase on Windows, whose paths ignore case). */
+export declare function vaultKey(vault: string, platform?: string): string;
+export interface VaultRecord {
+    /** The database id. */
+    id: string;
+    /** The database folder, vault-relative. */
+    database: string;
+}
+/** The registry of a data home: vault key → database id and folder. */
+export declare function readRegistry(home: string): Record<string, VaultRecord>;
+export interface StoreLocation {
+    /** The store folder. */
+    store: string;
+    /** The database id (null: a store named by DATANOTES_STORE whose record does not say it). */
+    id: string | null;
+    /** The database folder, vault-relative. */
+    database: string;
+}
+export interface LocateOptions {
+    env?: Env;
+    /** The store folder itself (`--store`; else DATANOTES_STORE). */
+    store?: string;
+}
+/** The vault's one folder with a `metastore.yaml`, else `datanotes`. */
+export declare function vaultDatabaseFolder(vault: string): string;
+/**
+ * Where the store of a vault's database is, as the engine finds it: the store named by `--store`
+ * or DATANOTES_STORE; else the database this machine last opened on the vault (`vaults.json`);
+ * else the id in the vault's one `metastore.yaml`. Null when none of them says.
+ */
+export declare function storeLocation(vault: string, opts?: LocateOptions): StoreLocation | null;
+export interface LocalEngine {
+    url: string;
+    token: string;
+    lock: EngineLock;
+}
+/** The settings file of a vault's engine, in its store; null while the vault has no store yet. */
+export declare function vaultSettingsPath(vault: string, opts?: LocateOptions): string | null;
+/**
+ * The engine holding `vault`, or null when none runs. Throws when the lock is fresh but held on
+ * another machine (a store on a shared folder): that engine is not reachable from here.
+ */
+export declare function localEngine(vault: string, opts?: LocateOptions & {
+    settingsFile?: string;
+    host?: string;
+    now?: number;
+}): LocalEngine | null;
+export {};

package/dist/api/local.d.ts

@@ -1,8 +1,16 @@
 /**
  * Find the engine running on a vault of this machine (Node only): its address and the owner's
- * token, read from the vault's settings and from the lock the engine holds while it runs.
+ * token, read from the database's store, where the engine keeps its settings and the lock it holds
+ * while it runs.
+ *
+ * The store is outside the vault, in the operating system's per-user data folder:
+ * `<data home>/<database id>/`, the id being `id` in the database's `metastore.yaml`. The data home
+ * is `%LOCALAPPDATA%\Datanotes` on Windows, `~/Library/Application Support/Datanotes` on macOS and
+ * `$XDG_DATA_HOME/datanotes` (`~/.local/share/datanotes`) elsewhere. `DATANOTES_DATA_HOME` moves the
+ * data home, `DATANOTES_STORE` (or `--store`) names the store folder itself. The engine finds a
+ * vault's database again through `vaults.json` in the data home (vault → id and database folder).
  */
-/** The lock an engine writes in its store folder (`<vault>/.datanotes/engine.lock`). */
+/** The lock an engine writes in its store (`<store>/engine.lock`). */
 export interface EngineLock {
     kind: "service";
     pid: number;
@@ -13,19 +21,75 @@ export interface EngineLock {
 }
 /** A lock whose heartbeat is older than this belongs to an engine that stopped. */
 export declare const LOCK_STALE_MS = 30000;
+/** The engine's settings file, in the store. */
+export declare const SETTINGS_FILE = "settings.json";
+/** The lock, in the store. */
+export declare const LOCK_FILE = "engine.lock";
+/** The store's record of its database: id, vault, database folder. */
+export declare const STORE_RECORD_FILE = "store.json";
+/** In the data home: the vaults this machine's engines opened, with their database. */
+export declare const REGISTRY_FILE = "vaults.json";
+/** The database folder of a new database: a top-level folder of the vault. */
+export declare const DEFAULT_DATABASE_FOLDER = "datanotes";
+export declare const METASTORE = "metastore.yaml";
+type Env = Record<string, string | undefined>;
+/** The data home: the folder that holds the stores of this user's databases. */
+export declare function dataHome(env?: Env, platform?: string, home?: string): string;
+/** The database id of a `metastore.yaml` text (its top-level `id:`), or null. */
+export declare function readDatabaseId(text: string): string | null;
+/** The database id of a vault's database folder, or null (no metastore, or no id in it). */
+export declare function databaseIdIn(vault: string, database: string): string | null;
+/**
+ * The folders of a vault on disk that hold a `metastore.yaml` (vault-relative with `/`, sorted).
+  * A vault has exactly one database folder, anywhere ("" for the root: --database). Dot-folders and
+ * `node_modules` are left out.
+ */
+export declare function vaultMetastores(vault: string): string[];
+/** A vault as the registry names it: its real path (lowercase on Windows, whose paths ignore case). */
+export declare function vaultKey(vault: string, platform?: string): string;
+export interface VaultRecord {
+    /** The database id. */
+    id: string;
+    /** The database folder, vault-relative. */
+    database: string;
+}
+/** The registry of a data home: vault key → database id and folder. */
+export declare function readRegistry(home: string): Record<string, VaultRecord>;
+export interface StoreLocation {
+    /** The store folder. */
+    store: string;
+    /** The database id (null: a store named by DATANOTES_STORE whose record does not say it). */
+    id: string | null;
+    /** The database folder, vault-relative. */
+    database: string;
+}
+export interface LocateOptions {
+    env?: Env;
+    /** The store folder itself (`--store`; else DATANOTES_STORE). */
+    store?: string;
+}
+/** The vault's one folder with a `metastore.yaml`, else `datanotes`. */
+export declare function vaultDatabaseFolder(vault: string): string;
+/**
+ * Where the store of a vault's database is, as the engine finds it: the store named by `--store`
+ * or DATANOTES_STORE; else the database this machine last opened on the vault (`vaults.json`);
+ * else the id in the vault's one `metastore.yaml`. Null when none of them says.
+ */
+export declare function storeLocation(vault: string, opts?: LocateOptions): StoreLocation | null;
 export interface LocalEngine {
     url: string;
     token: string;
     lock: EngineLock;
 }
-/** The settings file of a vault's engine. */
-export declare function vaultSettingsPath(vault: string): string;
+/** The settings file of a vault's engine, in its store; null while the vault has no store yet. */
+export declare function vaultSettingsPath(vault: string, opts?: LocateOptions): string | null;
 /**
  * The engine holding `vault`, or null when none runs. Throws when the lock is fresh but held on
- * another machine (a synced or shared folder): that engine is not reachable from here.
+ * another machine (a store on a shared folder): that engine is not reachable from here.
  */
-export declare function localEngine(vault: string, opts?: {
+export declare function localEngine(vault: string, opts?: LocateOptions & {
     settingsFile?: string;
     host?: string;
     now?: number;
 }): LocalEngine | null;
+export {};

package/dist/api/local.js

@@ -3,28 +3,126 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 var LOCK_STALE_MS = 3e4;
-function vaultSettingsPath(vault) {
-  return path.join(vault, ".datanotes", "service.json");
+var SETTINGS_FILE = "settings.json";
+var LOCK_FILE = "engine.lock";
+var STORE_RECORD_FILE = "store.json";
+var REGISTRY_FILE = "vaults.json";
+var DEFAULT_DATABASE_FOLDER = "datanotes";
+var METASTORE = "metastore.yaml";
+function dataHome(env = process.env, platform = process.platform, home = os.homedir()) {
+  if (env.DATANOTES_DATA_HOME) return path.resolve(env.DATANOTES_DATA_HOME);
+  if (platform === "win32") return path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "Datanotes");
+  if (platform === "darwin") return path.join(home, "Library", "Application Support", "Datanotes");
+  return path.join(env.XDG_DATA_HOME || path.join(home, ".local", "share"), "datanotes");
+}
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function readDatabaseId(text) {
+  const m = /^id:[ \t]*(.*)$/m.exec(text);
+  const value = m ? m[1].replace(/#.*$/, "").trim().replace(/^["']|["']$/g, "") : "";
+  return UUID.test(value) ? value.toLowerCase() : null;
+}
+function databaseIdIn(vault, database) {
+  try {
+    return readDatabaseId(fs.readFileSync(path.join(vault, ...database.split("/"), METASTORE), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function vaultMetastores(vault) {
+  const out = [];
+  const walk = (dir, rel) => {
+    let ents;
+    try {
+      ents = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of ents) {
+      if (e.name.startsWith(".") || e.name === "node_modules") continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(path.join(dir, e.name), r);
+      else if (e.name === METASTORE) out.push(rel);
+    }
+  };
+  walk(vault, "");
+  return out.sort();
+}
+function vaultKey(vault, platform = process.platform) {
+  let real = path.resolve(vault);
+  try {
+    real = fs.realpathSync.native(real);
+  } catch {
+  }
+  return platform === "win32" ? real.toLowerCase() : real;
 }
 function readJson(file) {
   try {
-    return JSON.parse(fs.readFileSync(file, "utf8"));
+    const v = JSON.parse(fs.readFileSync(file, "utf8"));
+    return v && typeof v === "object" && !Array.isArray(v) ? v : null;
   } catch {
     return null;
   }
 }
+function readRegistry(home) {
+  const raw = readJson(path.join(home, REGISTRY_FILE)) ?? {};
+  const out = {};
+  for (const [k, v] of Object.entries(raw)) {
+    const r = v;
+    if (r && typeof r.id === "string" && UUID.test(r.id) && typeof r.database === "string") out[k] = { id: r.id, database: r.database };
+  }
+  return out;
+}
+function vaultDatabaseFolder(vault) {
+  const found = vaultMetastores(vault);
+  return found.length === 1 ? found[0] : DEFAULT_DATABASE_FOLDER;
+}
+function storeLocation(vault, opts = {}) {
+  const env = opts.env ?? process.env;
+  const explicit = opts.store ?? env.DATANOTES_STORE;
+  if (explicit) {
+    const store = path.resolve(explicit);
+    const rec = readJson(path.join(store, STORE_RECORD_FILE));
+    const database2 = typeof rec?.database === "string" ? rec.database : vaultDatabaseFolder(vault);
+    return { store, id: typeof rec?.id === "string" ? rec.id : databaseIdIn(vault, database2), database: database2 };
+  }
+  const home = dataHome(env);
+  const known = readRegistry(home)[vaultKey(vault)];
+  if (known) return { store: path.join(home, known.id), id: known.id, database: known.database };
+  const database = vaultDatabaseFolder(vault);
+  const id = databaseIdIn(vault, database);
+  return id ? { store: path.join(home, id), id, database } : null;
+}
+function vaultSettingsPath(vault, opts = {}) {
+  const loc = storeLocation(vault, opts);
+  return loc ? path.join(loc.store, SETTINGS_FILE) : null;
+}
 function localEngine(vault, opts = {}) {
-  const settings = readJson(opts.settingsFile ?? vaultSettingsPath(vault)) ?? {};
-  const store = typeof settings.storeFolder === "string" && settings.storeFolder ? settings.storeFolder : ".datanotes";
-  const lock = readJson(path.join(vault, store.replace(/\/+$/, ""), "engine.lock"));
+  const loc = storeLocation(vault, opts);
+  if (!loc) return null;
+  const lock = readJson(path.join(loc.store, LOCK_FILE));
   if (!lock || (opts.now ?? Date.now()) - Date.parse(lock.heartbeat) >= LOCK_STALE_MS) return null;
   if (lock.host !== os.hostname()) throw new Error(`the vault is held by an engine on ${lock.host}; connect to it by its address`);
+  const settings = readJson(opts.settingsFile ?? path.join(loc.store, SETTINGS_FILE)) ?? {};
   const token = typeof settings.httpServerToken === "string" ? settings.httpServerToken : "";
   if (!token) return null;
   return { url: `http://${opts.host ?? "127.0.0.1"}:${lock.port}`, token, lock };
 }
 export {
+  DEFAULT_DATABASE_FOLDER,
+  LOCK_FILE,
   LOCK_STALE_MS,
+  METASTORE,
+  REGISTRY_FILE,
+  SETTINGS_FILE,
+  STORE_RECORD_FILE,
+  dataHome,
+  databaseIdIn,
   localEngine,
+  readDatabaseId,
+  readRegistry,
+  storeLocation,
+  vaultDatabaseFolder,
+  vaultKey,
+  vaultMetastores,
   vaultSettingsPath
 };