@descix/frqtl-node 0.0.0-stage → 0.6.0-p0.1

package/dist/shim/storage/boot.js

@@ -0,0 +1,69 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/storage/boot.js — THE browser boot of the storage seam: install a LocalStorageProvider
+ * as the active provider, once, unless a host has already set one.
+ *
+ * Every browser surface that persists through lib/shim/storage calls this at its boot — FraqtlIde
+ * when it mounts, a framework-free page before it mounts a run-once card — and nothing else
+ * constructs a LocalStorageProvider (gated by test/boot.test.mjs). Plain ESM, no DOM beyond
+ * `window.localStorage`, shim-internal imports only.
+ *
+ *   bootLocalStorage() → { row, detail? }   (a row of STORAGE_BOOT_OUTCOMES)
+ *   recordStorageBoot(el, outcome)           (writes STORAGE_BOOT_ATTRS on the host's element)
+ *
+ * A browser without usable localStorage is a declared outcome, never a throw: persistence is a
+ * convenience for its consumers, each of which records its own unavailable state (the run-once
+ * card's `storage-unavailable-shown`). The reason the provider could not be built is the detail.
+ * A host never discards the outcome: it writes it with recordStorageBoot, the ONE writer of the
+ * boot record's attributes.
+ */
+
+import { peekProvider, setActiveProvider } from './index.js';
+import { LocalStorageProvider } from './local-storage-provider.js';
+
+/** The closed table of boot outcomes. */
+export const STORAGE_BOOT_OUTCOMES = Object.freeze([
+    { id: 'installed',      means: 'a LocalStorageProvider was constructed and is now the active provider' },
+    { id: 'already-active', means: 'a provider was already active (a host set its own, or boot ran before); left as is' },
+    { id: 'unavailable',    means: 'localStorage is absent or write-blocked: no provider is set; detail is the reason' },
+].map(Object.freeze));
+
+/**
+ * Install localStorage as the active storage provider unless one is already active.
+ * @returns {{row: 'installed'|'already-active'|'unavailable', detail?: string}}
+ */
+export function bootLocalStorage() {
+    if (peekProvider()) { return { row: 'already-active' }; }
+    let provider;
+    try {
+        provider = new LocalStorageProvider();
+    } catch (e) {
+        return { row: 'unavailable', detail: (e && e.message) ? String(e.message) : String(e) };
+    }
+    setActiveProvider(provider);
+    return { row: 'installed' };
+}
+
+/** The boot record's attribute names on a host element — the ONE vocabulary readers and the writer share. */
+export const STORAGE_BOOT_ATTRS = Object.freeze({ row: 'data-storage-boot', detail: 'data-storage-boot-detail' });
+
+const BOOT_ROWS = new Set(STORAGE_BOOT_OUTCOMES.map((r) => r.id));
+
+/**
+ * Write a bootLocalStorage() outcome onto `el` (STORAGE_BOOT_ATTRS). A row without a detail
+ * clears any previous detail. Refuses a row STORAGE_BOOT_OUTCOMES does not list.
+ * @param {{setAttribute: function, removeAttribute: function}} el
+ * @param {{row: string, detail?: string}} outcome
+ */
+export function recordStorageBoot(el, outcome) {
+    if (!el || typeof el.setAttribute !== 'function' || typeof el.removeAttribute !== 'function') {
+        throw new TypeError('storage boot: recordStorageBoot needs a DOM element');
+    }
+    if (!outcome || !BOOT_ROWS.has(outcome.row)) {
+        throw new Error('storage boot: ' + JSON.stringify(outcome && outcome.row) + ' is not a STORAGE_BOOT_OUTCOMES row');
+    }
+    el.setAttribute(STORAGE_BOOT_ATTRS.row, outcome.row);
+    if (outcome.detail === undefined) { el.removeAttribute(STORAGE_BOOT_ATTRS.detail); }
+    else { el.setAttribute(STORAGE_BOOT_ATTRS.detail, outcome.detail); }
+}

package/dist/shim/storage/index.js

@@ -0,0 +1,169 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/storage — THE StorageProvider seam.
+ *
+ * This module is the CONTRACT for all persistent storage used by the FraqtlIde
+ * author surface.  It defines the interface every provider must implement and
+ * exposes the active provider instance chosen at boot time.
+ *
+ * ── Why this exists ────────────────────────────────────────────────────────
+ *
+ * The IDE needs project persistence.  Today the active driver is browser
+ * localStorage (see local-storage-provider.js).  Tomorrow it may be a
+ * server-side REST backend (see lib/server/mounts.js §/api/storage).
+ *
+ * The seam lives here so the IDE and all tooling import only this module and
+ * never depend on localStorage or any backend directly.  Swapping the backend
+ * requires changing only which provider is passed to setActiveProvider() —
+ * ZERO changes to IDE or AuthorView code.
+ *
+ * ── The contract (every provider MUST implement) ────────────────────────────
+ *
+ *   get(namespace, key)            → value (any JSON-serialisable) | null
+ *   put(namespace, key, value)     → void
+ *   delete(namespace, key)         → void
+ *   list(namespace)                → Array<{ key: string, ...metadata }>
+ *
+ * Rules:
+ *   • namespace and key are non-empty strings.  "/" is reserved.
+ *   • value must be JSON-serialisable.  Providers are free to stringify it.
+ *   • list returns one entry per key in the namespace (order unspecified).
+ *     Each entry MUST contain at least { key: string }.  Providers may add
+ *     metadata (e.g. updatedAt).
+ *   • get on a missing key returns null — never throws.
+ *   • delete on a missing key is a no-op — never throws.
+ *   • All other contract violations (bad types, absent localStorage, etc.)
+ *     MUST throw a descriptive Error — FAIL-LOUD, never silent.
+ *
+ * ── Usage ──────────────────────────────────────────────────────────────────
+ *
+ *   // During browser app boot, wire the active driver once (the ONE installer):
+ *   import { bootLocalStorage } from 'lib/shim/storage/boot.js';
+ *   bootLocalStorage();   // → { row: 'installed' | 'already-active' | 'unavailable', detail? }
+ *
+ *   // Then anywhere in the IDE:
+ *   import { getProvider } from 'lib/shim/storage';
+ *   const storage = getProvider();
+ *   storage.put('projects', 'abc123', { name: 'My project' });
+ *   const saved = storage.get('projects', 'abc123');
+ *   const all   = storage.list('projects');
+ *   storage.delete('projects', 'abc123');
+ *
+ * ── Contract validation ─────────────────────────────────────────────────────
+ *
+ *   validateProvider(provider) — throws if provider does not implement the
+ *     contract.  Called by setActiveProvider; consumers may also call it.
+ *
+ * ── Server-side seam ───────────────────────────────────────────────────────
+ *
+ *   The matching server routes are defined in lib/server/mounts.js under
+ *   /api/storage/:namespace        (LIST)
+ *   /api/storage/:namespace/:key   (GET / PUT / DELETE)
+ *   They are documented as the future-backend seam: when a server-side driver
+ *   is ready, a RemoteStorageProvider that calls those routes will slot in here
+ *   with no IDE changes.
+ */
+
+'use strict';
+
+/** @type {StorageProvider|null} */
+var _activeProvider = null;
+
+// ── Contract typedefs ──────────────────────────────────────────────────────
+
+/**
+ * @typedef {object} StorageProvider
+ *   Every storage driver must implement this interface exactly.
+ *
+ * @property {function(string, string): any|null}   get
+ *   Retrieve a value. Returns null if not found; never throws on missing key.
+ *
+ * @property {function(string, string, any): void}  put
+ *   Write a JSON-serialisable value. Overwrites any existing value.
+ *
+ * @property {function(string, string): void}       delete
+ *   Remove a key. No-op if key does not exist; never throws.
+ *
+ * @property {function(string): Array<{key: string}>} list
+ *   Enumerate all keys in a namespace.  Each entry contains at least
+ *   { key: string } and may contain additional metadata fields.
+ */
+
+// ── Contract validation ────────────────────────────────────────────────────
+
+var _REQUIRED_METHODS = ['get', 'put', 'delete', 'list'];
+
+/**
+ * Assert that provider implements the StorageProvider contract.
+ * Throws a descriptive Error on the first violation found — FAIL-LOUD.
+ *
+ * @param {any} provider
+ * @throws {Error}
+ */
+export function validateProvider(provider) {
+  if (!provider || typeof provider !== 'object') {
+    throw new Error(
+      '[StorageProvider] provider must be a non-null object; got ' + typeof provider
+    );
+  }
+  for (var i = 0; i < _REQUIRED_METHODS.length; i++) {
+    var method = _REQUIRED_METHODS[i];
+    if (typeof provider[method] !== 'function') {
+      throw new Error(
+        '[StorageProvider] provider is missing required method "' + method + '"'
+      );
+    }
+  }
+}
+
+// ── Active provider management ─────────────────────────────────────────────
+
+/**
+ * Register the active storage driver.  Must be called once at boot before
+ * any call to getProvider().
+ *
+ * @param {StorageProvider} provider
+ * @throws {Error} if provider does not implement the contract.
+ */
+export function setActiveProvider(provider) {
+  validateProvider(provider);
+  _activeProvider = provider;
+}
+
+/**
+ * Retrieve the active storage driver.
+ * FAIL-LOUD: throws if no provider has been registered.
+ *
+ * @returns {StorageProvider}
+ * @throws {Error}
+ */
+export function getProvider() {
+  if (!_activeProvider) {
+    throw new Error(
+      '[StorageProvider] no active provider has been set. ' +
+      'Call bootLocalStorage() (lib/shim/storage/boot.js) during app boot, or setActiveProvider(<provider>) ' +
+      'for a non-browser driver.'
+    );
+  }
+  return _activeProvider;
+}
+
+/**
+ * Return the active provider, or null if none has been registered.
+ * Use this instead of getProvider() when a nil-safe check is appropriate
+ * (e.g. during test setup before a provider is wired).
+ *
+ * @returns {StorageProvider|null}
+ */
+export function peekProvider() {
+  return _activeProvider;
+}
+
+/**
+ * Reset the active provider to null.  For tests only — do not call in
+ * production code.
+ */
+export function resetProvider() {
+  _activeProvider = null;
+}

package/dist/shim/storage/local-storage-provider.js

@@ -0,0 +1,230 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * LocalStorageProvider — THE active storage driver (browser localStorage).
+ *
+ * Implements the StorageProvider contract defined in lib/shim/storage/index.js.
+ *
+ * ── Key format ─────────────────────────────────────────────────────────────
+ *
+ *   frqtl:<namespace>:<key>
+ *
+ *   e.g. "frqtl:projects:abc123"
+ *
+ * ── Serialisation ──────────────────────────────────────────────────────────
+ *
+ *   Values are stored as JSON strings.  Non-serialisable values (functions,
+ *   circular references, etc.) FAIL-LOUD — the error surfaces immediately so
+ *   the caller knows the write did not persist, rather than silently losing data.
+ *
+ * ── Namespace enumeration ──────────────────────────────────────────────────
+ *
+ *   list() iterates all localStorage keys, collects those with the prefix
+ *   "frqtl:<namespace>:", and parses the stored JSON to extract any metadata
+ *   fields that were stored alongside the value.
+ *
+ *   list() always returns plain-object entries of the form
+ *   { key: string, ...any metadata from the stored envelope }.
+ *   It never throws on individual malformed entries — those are skipped and
+ *   a console.warn is emitted so the problem is visible without crashing the
+ *   list view.
+ *
+ * ── Absent localStorage ─────────────────────────────────────────────────────
+ *
+ *   The constructor FAIL-LOUDs with a clear message if window.localStorage is
+ *   not available (e.g. in a sandboxed iframe with storage blocked, or in a
+ *   non-browser environment).  Use a different provider in those contexts.
+ *
+ * ── Usage ──────────────────────────────────────────────────────────────────
+ *
+ *   Constructed in ONE place: lib/shim/storage/boot.js bootLocalStorage(), which a browser
+ *   surface calls at boot (gated by test/boot.test.mjs). Never construct it elsewhere.
+ */
+
+'use strict';
+
+var _PREFIX = 'frqtl';
+
+/**
+ * Build the localStorage key for a given namespace + key pair — the ONE owner of the
+ * key format (exported so a harness that seeds storage never re-types it).
+ * @param {string} namespace
+ * @param {string} key
+ * @returns {string}
+ */
+export function storageKeyOf(namespace, key) {
+  return _PREFIX + ':' + namespace + ':' + key;
+}
+
+/**
+ * Build the namespace prefix used to enumerate all keys in a namespace.
+ * @param {string} namespace
+ * @returns {string}
+ */
+function _namespacePrefix(namespace) {
+  return _PREFIX + ':' + namespace + ':';
+}
+
+/**
+ * Assert that a string argument is a valid namespace or key.
+ * FAIL-LOUD.
+ *
+ * @param {string} value
+ * @param {string} argName  — used in the error message
+ */
+function _assertNonEmptyString(value, argName) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(
+      '[LocalStorageProvider] ' + argName + ' must be a non-empty string; got: ' + JSON.stringify(value)
+    );
+  }
+  if (value.indexOf('/') !== -1) {
+    throw new Error(
+      '[LocalStorageProvider] ' + argName + ' must not contain "/"; got: ' + JSON.stringify(value)
+    );
+  }
+}
+
+export class LocalStorageProvider {
+  /**
+   * @throws {Error} if window.localStorage is not available.
+   */
+  constructor() {
+    // FAIL-LOUD if localStorage is not available.
+    if (typeof window === 'undefined' || typeof window.localStorage === 'undefined' || window.localStorage === null) {
+      throw new Error(
+        '[LocalStorageProvider] window.localStorage is not available in this environment. ' +
+        'Use a different StorageProvider (e.g. a server-backed RemoteStorageProvider) ' +
+        'or ensure the page is served in a context where localStorage is permitted.'
+      );
+    }
+    // Probe with a write+delete to detect private/blocked storage.
+    try {
+      var _probe = '__frqtl_storage_probe__';
+      window.localStorage.setItem(_probe, '1');
+      window.localStorage.removeItem(_probe);
+    } catch (e) {
+      throw new Error(
+        '[LocalStorageProvider] window.localStorage is present but write-blocked (private ' +
+        'browsing with strict storage restrictions?). Error: ' + (e && e.message ? e.message : String(e))
+      );
+    }
+    /** @type {Storage} */
+    this._ls = window.localStorage;
+  }
+
+  /**
+   * Retrieve a stored value.
+   *
+   * @param {string} namespace
+   * @param {string} key
+   * @returns {any|null}  Parsed JSON value, or null if not found.
+   */
+  get(namespace, key) {
+    _assertNonEmptyString(namespace, 'namespace');
+    _assertNonEmptyString(key, 'key');
+    var raw = this._ls.getItem(storageKeyOf(namespace, key));
+    if (raw === null) { return null; }
+    try {
+      return JSON.parse(raw);
+    } catch (e) {
+      throw new Error(
+        '[LocalStorageProvider] stored value for "' + namespace + '/' + key +
+        '" is not valid JSON.  Storage may be corrupted. Error: ' +
+        (e && e.message ? e.message : String(e))
+      );
+    }
+  }
+
+  /**
+   * Write a value.  Overwrites any existing value.
+   *
+   * @param {string} namespace
+   * @param {string} key
+   * @param {any} value   Must be JSON-serialisable — FAIL-LOUD if not.
+   */
+  put(namespace, key, value) {
+    _assertNonEmptyString(namespace, 'namespace');
+    _assertNonEmptyString(key, 'key');
+    var serialised;
+    try {
+      serialised = JSON.stringify(value);
+    } catch (e) {
+      throw new Error(
+        '[LocalStorageProvider] value for "' + namespace + '/' + key +
+        '" is not JSON-serialisable: ' + (e && e.message ? e.message : String(e))
+      );
+    }
+    try {
+      this._ls.setItem(storageKeyOf(namespace, key), serialised);
+    } catch (e) {
+      throw new Error(
+        '[LocalStorageProvider] localStorage.setItem failed for "' + namespace + '/' + key +
+        '" — storage may be full (QuotaExceededError) or blocked. Error: ' +
+        (e && e.message ? e.message : String(e))
+      );
+    }
+  }
+
+  /**
+   * Remove a key.  No-op if key does not exist.
+   *
+   * @param {string} namespace
+   * @param {string} key
+   */
+  delete(namespace, key) {
+    _assertNonEmptyString(namespace, 'namespace');
+    _assertNonEmptyString(key, 'key');
+    this._ls.removeItem(storageKeyOf(namespace, key));
+  }
+
+  /**
+   * List all entries in a namespace.
+   *
+   * Each entry contains at minimum { key: string }.  If the stored value is
+   * an object with additional metadata fields (e.g. id, name, updatedAt),
+   * those are spread into the entry.
+   *
+   * Malformed entries (unparseable JSON, unexpected shapes) are skipped with a
+   * console.warn — the list call itself never throws.
+   *
+   * @param {string} namespace
+   * @returns {Array<{key: string}>}
+   */
+  list(namespace) {
+    _assertNonEmptyString(namespace, 'namespace');
+    var prefix = _namespacePrefix(namespace);
+    var results = [];
+    var ls = this._ls;
+    var len = ls.length;
+    for (var i = 0; i < len; i++) {
+      var storageKey = ls.key(i);
+      if (storageKey === null) { continue; }
+      if (storageKey.indexOf(prefix) !== 0) { continue; }
+      // Extract the user-facing key from the storage key.
+      var userKey = storageKey.slice(prefix.length);
+      var raw = ls.getItem(storageKey);
+      var parsed = null;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (e) {
+        console.warn(
+          '[LocalStorageProvider] skipping malformed entry "' + storageKey + '": ' +
+          (e && e.message ? e.message : String(e))
+        );
+        continue;
+      }
+      // If the stored value is an object, spread its fields as metadata.
+      var entry = { key: userKey };
+      if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        for (var field in parsed) {
+          if (Object.prototype.hasOwnProperty.call(parsed, field) && field !== 'key') {
+            entry[field] = parsed[field];
+          }
+        }
+      }
+      results.push(entry);
+    }
+    return results;
+  }
+}

package/dist/shim/storage/make-namespace-store.js

@@ -0,0 +1,132 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/storage/make-namespace-store.js — Generic namespace-CRUD factory.
+ *
+ * Factors out the byte-identical pattern shared by modules.js, projects.js,
+ * and lib/shim/notebook/store.js.  Each of those files is a thin config call
+ * over this factory; the public-API exports they expose are unchanged.
+ *
+ * ── Signature ──────────────────────────────────────────────────────────────
+ *
+ *   makeNamespaceStore(config) → { newId, save, load, list, delete: del }
+ *
+ * ── Config ─────────────────────────────────────────────────────────────────
+ *
+ *   namespace      {string}    — StorageProvider namespace key (e.g. 'files').
+ *   schemaVersion  {number}    — Current schema version integer (stamped on save
+ *                                by callers; used here only in the returned
+ *                                constant — actual stamping is the caller's job,
+ *                                as in the originals).
+ *   idPrefix       {string}    — Prefix for generated ids (e.g. 'mod_').
+ *   validate       {function}  — validate(record): throws on invalid envelope.
+ *   summaryFields  {function}  — summaryFields(record) → summary object, or
+ *                                returns null to silently skip the record.
+ *   migrate        {function?} — Optional. migrate(raw) → migrated record.
+ *                                Applied in load() and list() after provider.get().
+ *   listFilter     {function?} — Optional. listFilter(record, opts) → boolean.
+ *                                Applied after migration. When absent, all
+ *                                non-null summaryFields results are included.
+ *
+ * ── Returned surface ───────────────────────────────────────────────────────
+ *
+ *   newId()                 → string
+ *   save(provider, record)  → void         (FAIL-LOUD; validate then put)
+ *   load(provider, id)      → object|null  (migrate applied; FAIL-LOUD on bad id)
+ *   list(provider, opts?)   → Array        (skip-malformed; sort updatedAt desc)
+ *   del(provider, id)       → void         (no-op if absent; FAIL-LOUD on bad id)
+ *
+ * ── Arrows ─────────────────────────────────────────────────────────────────
+ *
+ *   lib/shim → lib/shim (legal).
+ *   lib/shim/notebook/store.js imports via ../storage/make-namespace-store.js.
+ */
+
+'use strict';
+
+/**
+ * @param {{
+ *   namespace:     string,
+ *   schemaVersion: number,
+ *   idPrefix:      string,
+ *   validate:      function,
+ *   summaryFields: function,
+ *   migrate?:      function,
+ *   listFilter?:   function,
+ * }} config
+ * @returns {{ newId: function, save: function, load: function, list: function, delete: function }}
+ */
+export function makeNamespaceStore(config) {
+  var namespace     = config.namespace;
+  var idPrefix      = config.idPrefix;
+  var validate      = config.validate;
+  var summaryFields = config.summaryFields;
+  var migrate       = config.migrate   || null;
+  var listFilter    = config.listFilter || null;
+
+  // ── newId ──────────────────────────────────────────────────────────────────
+
+  function newId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+      return idPrefix + crypto.randomUUID().replace(/-/g, '');
+    }
+    // Fallback: timestamp (base-36) + random bits (base-36)
+    var ts  = Date.now().toString(36);
+    var rnd = Math.random().toString(36).slice(2, 10);
+    return idPrefix + ts + rnd;
+  }
+
+  // ── save ───────────────────────────────────────────────────────────────────
+
+  function save(provider, record) {
+    validate(record);
+    provider.put(namespace, record.id, record);
+  }
+
+  // ── load ───────────────────────────────────────────────────────────────────
+
+  function load(provider, id) {
+    if (typeof id !== 'string' || id.length === 0) {
+      throw new Error('[' + namespace + '] load: id must be a non-empty string');
+    }
+    var raw = provider.get(namespace, id);
+    if (raw === null || raw === undefined) { return null; }
+    return migrate ? migrate(raw) : raw;
+  }
+
+  // ── list ───────────────────────────────────────────────────────────────────
+
+  function list(provider, opts) {
+    var entries   = provider.list(namespace);
+    var summaries = [];
+    for (var i = 0; i < entries.length; i++) {
+      var raw = provider.get(namespace, entries[i].key);
+      if (!raw || typeof raw.id !== 'string') {
+        continue; // silently skip malformed entries
+      }
+      var record = migrate ? migrate(raw) : raw;
+      if (listFilter && !listFilter(record, opts)) { continue; }
+      var summary = summaryFields(record);
+      if (summary === null || summary === undefined) { continue; }
+      summaries.push(summary);
+    }
+    // Sort most-recently-modified first.
+    summaries.sort(function (a, b) {
+      if (a.updatedAt < b.updatedAt) { return  1; }
+      if (a.updatedAt > b.updatedAt) { return -1; }
+      return 0;
+    });
+    return summaries;
+  }
+
+  // ── delete ─────────────────────────────────────────────────────────────────
+
+  function del(provider, id) {
+    if (typeof id !== 'string' || id.length === 0) {
+      throw new Error('[' + namespace + '] delete: id must be a non-empty string');
+    }
+    provider.delete(namespace, id);
+  }
+
+  return { newId: newId, save: save, load: load, list: list, 'delete': del };
+}