quilltap 4.7.0-dev → 4.7.0-dev.117

package/lib/native-modules.js

@@ -21,6 +21,84 @@ function resolveModuleDir(moduleName) {
   }
 }
 
+// Locate the SQLCipher binding (better-sqlite3-multiple-ciphers, aliased as
+// better-sqlite3). Returns the absolute path to better_sqlite3.node, or null.
+function betterSqlite3BindingPath() {
+  const modDir = resolveModuleDir('better-sqlite3-multiple-ciphers')
+              || resolveModuleDir('better-sqlite3');
+  if (!modDir) return null;
+  return path.join(modDir, 'build', 'Release', 'better_sqlite3.node');
+}
+
+// Read the Node ABI (NODE_MODULE_VERSION) a node-gyp/NAN addon was compiled
+// against, by scanning for its `node_register_module_v<ABI>` export — a few-KB
+// byte read, no dlopen, no rebuild. Returns the ABI as a string, or null when
+// the symbol is absent (e.g. an N-API build, which is ABI-stable) or unreadable.
+function readCompiledAbi(bindingPath) {
+  try {
+    const buf = require('fs').readFileSync(bindingPath);
+    const m = /node_register_module_v(\d+)/.exec(buf.toString('latin1'));
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+// True when the SQLCipher binding is missing or was built for a different Node
+// ABI than the one we're running. Reads the compiled-for ABI straight from the
+// binary; only falls back to an actual load probe if the symbol can't be read.
+function betterSqlite3NeedsRebuild() {
+  const bindingPath = betterSqlite3BindingPath();
+  if (!bindingPath) return true; // unresolvable → needs (re)build
+  if (!require('fs').existsSync(bindingPath)) return true;
+  const compiledAbi = readCompiledAbi(bindingPath);
+  if (compiledAbi) return compiledAbi !== process.versions.modules;
+  // Symbol unreadable — fall back to the authoritative dlopen probe.
+  try {
+    require(bindingPath);
+    return false;
+  } catch (err) {
+    return !!(err.message && err.message.includes('NODE_MODULE_VERSION'));
+  }
+}
+
+// Rebuild the named native modules against the current Node ABI. Prints a
+// friendly notice rather than throwing; returns true on success, false on
+// failure. Backfills node-pty's spawn-helper afterward.
+function rebuildModules(moduleNames) {
+  console.log(`  Rebuilding native modules for Node.js ${process.version}...`);
+  try {
+    execSync(`npm rebuild ${moduleNames.join(' ')}`, {
+      cwd: PACKAGE_DIR,
+      stdio: 'inherit',
+    });
+    console.log('  Done.');
+    console.log('');
+    reconcileNodePtySpawnHelper();
+    return true;
+  } catch (err) {
+    console.error('');
+    console.error(`  Warning: Failed to rebuild native modules: ${err.message}`);
+    console.error('  Try running: npm rebuild --prefix ' + PACKAGE_DIR);
+    console.error('');
+    return false;
+  }
+}
+
+// Fast pre-flight for the ONE ABI-fragile native module every DB path needs:
+// better-sqlite3-multiple-ciphers (SQLCipher). sharp and node-pty are N-API and
+// ABI-stable, so they can't hit this failure. Detects an ABI mismatch from the
+// binary itself and rebuilds before anything tries to load it, so a Node upgrade
+// self-heals instead of throwing. Cheap no-op when already healthy. Never throws.
+function ensureDatabaseNativeModule() {
+  try {
+    if (!betterSqlite3NeedsRebuild()) return true;
+  } catch {
+    return true; // detection hiccup — let the real load be the source of truth
+  }
+  return rebuildModules(['better-sqlite3-multiple-ciphers']);
+}
+
 // node-pty needs a `spawn-helper` executable beside the pty.node it loads, or
 // pty.spawn() fails with `posix_spawnp failed`. An ABI rebuild lands a fresh
 // build/Release/pty.node (which node-pty's loader prefers over prebuilds/) but
@@ -74,19 +152,9 @@ function ensureNativeModules() {
   // Check better-sqlite3-multiple-ciphers (provides SQLCipher encryption support).
   // The main app depends on this via an npm alias as 'better-sqlite3', so we must
   // ensure the SQLCipher-capable version is available and link it as 'better-sqlite3'.
-  // We must load the native binding directly to detect NODE_MODULE_VERSION mismatches.
-  try {
-    const modDir = resolveModuleDir('better-sqlite3-multiple-ciphers')
-                || resolveModuleDir('better-sqlite3');
-    if (!modDir) throw Object.assign(new Error('not found'), { code: 'MODULE_NOT_FOUND' });
-    const bindingsPath = path.join(modDir, 'build', 'Release', 'better_sqlite3.node');
-    require(bindingsPath);
-  } catch (err) {
-    if (err.message && err.message.includes('NODE_MODULE_VERSION')) {
-      needsRebuild.push('better-sqlite3-multiple-ciphers');
-    } else if (err.code === 'MODULE_NOT_FOUND') {
-      needsRebuild.push('better-sqlite3-multiple-ciphers');
-    }
+  // This is the only ABI-fragile binding — detected straight from the binary.
+  if (betterSqlite3NeedsRebuild()) {
+    needsRebuild.push('better-sqlite3-multiple-ciphers');
   }
 
   // Check sharp: loads its native binding eagerly on require.
@@ -120,27 +188,18 @@ function ensureNativeModules() {
     return true;
   }
 
-  console.log(`  Rebuilding native modules for Node.js ${process.version}...`);
-
-  try {
-    execSync(`npm rebuild ${needsRebuild.join(' ')}`, {
-      cwd: PACKAGE_DIR,
-      stdio: 'inherit',
-    });
-    console.log('  Done.');
-    console.log('');
-    reconcileNodePtySpawnHelper();
-    return true;
-  } catch (err) {
-    console.error('');
-    console.error(`  Warning: Failed to rebuild native modules: ${err.message}`);
-    console.error('  Try running: npm rebuild --prefix ' + PACKAGE_DIR);
-    console.error('');
-    return false;
-  }
+  return rebuildModules(needsRebuild);
 }
 
-module.exports = { resolveModuleDir, ensureNativeModules, reconcileNodePtySpawnHelper, PACKAGE_DIR };
+module.exports = {
+  resolveModuleDir,
+  readCompiledAbi,
+  betterSqlite3NeedsRebuild,
+  ensureDatabaseNativeModule,
+  ensureNativeModules,
+  reconcileNodePtySpawnHelper,
+  PACKAGE_DIR,
+};
 
 // Allow this file to be invoked directly as a postinstall script:
 //   node lib/native-modules.js

package/lib/qtap-uri.js

@@ -0,0 +1,171 @@
+/**
+ * `qtap://` Document URI codec — CLI-local, dependency-free port.
+ *
+ * Mirrors the server codec at `lib/doc-edit/qtap-uri.ts` (same grammar, same
+ * encoding, same tests). Kept as its own small CommonJS module because the
+ * server module is not importable from the published CLI package. If the
+ * grammar changes, update BOTH and their tests.
+ *
+ *   qtap://authority/path[#fragment][?query]
+ *
+ * Authority → { scope, mountPoint }:
+ *   self    → document_store, mountPoint 'self'
+ *   project → project
+ *   general → general
+ *   else    → document_store, mountPoint = the decoded authority (name or UUID)
+ *
+ * @module qtap-uri (CLI)
+ */
+
+'use strict';
+
+const QTAP_URI_SCHEME = 'qtap://';
+const SELF_VAULT_TOKEN = 'self';
+
+class QtapUriError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'QtapUriError';
+    this.code = code;
+  }
+}
+
+/** True iff the value starts with the qtap:// scheme (case-insensitive). */
+function isQtapUri(s) {
+  return typeof s === 'string' && s.toLowerCase().startsWith(QTAP_URI_SCHEME);
+}
+
+function safeDecode(component) {
+  try {
+    return decodeURIComponent(component);
+  } catch {
+    throw new QtapUriError(`Malformed percent-encoding in qtap:// URI segment: "${component}"`, 'MALFORMED');
+  }
+}
+
+function parseFragment(fragment) {
+  if (fragment === '') return {};
+  const colonIdx = fragment.lastIndexOf(':');
+  if (colonIdx === -1) {
+    return { heading: safeDecode(fragment) };
+  }
+  const headingPart = fragment.slice(0, colonIdx);
+  const levelPart = fragment.slice(colonIdx + 1);
+  if (!/^[0-9]+$/.test(levelPart)) {
+    throw new QtapUriError(`Invalid heading level "${levelPart}" in qtap:// fragment; expected an integer 1–6.`, 'BAD_LEVEL');
+  }
+  const level = parseInt(levelPart, 10);
+  if (level < 1 || level > 6) {
+    throw new QtapUriError(`Heading level ${level} out of range in qtap:// fragment; expected 1–6.`, 'BAD_LEVEL');
+  }
+  return { heading: safeDecode(headingPart), level };
+}
+
+function parseQuery(query) {
+  if (query === '') return undefined;
+  const out = {};
+  for (const pair of query.split('&')) {
+    if (pair === '') continue;
+    const eq = pair.indexOf('=');
+    if (eq === -1) out[safeDecode(pair)] = '';
+    else out[safeDecode(pair.slice(0, eq))] = safeDecode(pair.slice(eq + 1));
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** Parse a qtap:// URI into { scope, mountPoint?, path, heading?, level?, query? }. */
+function parseQtapUri(uri) {
+  if (!isQtapUri(uri)) {
+    throw new QtapUriError(`Not a qtap:// URI: ${typeof uri === 'string' ? `"${uri}"` : typeof uri}`, 'NOT_A_QTAP_URI');
+  }
+  let rest = uri.slice(QTAP_URI_SCHEME.length);
+
+  let query;
+  const qIdx = rest.indexOf('?');
+  if (qIdx !== -1) {
+    query = parseQuery(rest.slice(qIdx + 1));
+    rest = rest.slice(0, qIdx);
+  }
+
+  let heading;
+  let level;
+  const hashIdx = rest.indexOf('#');
+  if (hashIdx !== -1) {
+    const frag = parseFragment(rest.slice(hashIdx + 1));
+    heading = frag.heading;
+    level = frag.level;
+    rest = rest.slice(0, hashIdx);
+  }
+
+  const slashIdx = rest.indexOf('/');
+  const rawAuthority = slashIdx === -1 ? rest : rest.slice(0, slashIdx);
+  const rawPath = slashIdx === -1 ? '' : rest.slice(slashIdx + 1);
+
+  const authority = safeDecode(rawAuthority);
+  if (authority === '') {
+    throw new QtapUriError('qtap:// URI has an empty authority.', 'EMPTY_AUTHORITY');
+  }
+
+  const path = rawPath === '' ? '' : rawPath.split('/').map((seg) => safeDecode(seg)).join('/');
+
+  const lower = authority.toLowerCase();
+  const parts = { scope: 'document_store', path };
+  if (lower === SELF_VAULT_TOKEN) {
+    parts.mountPoint = SELF_VAULT_TOKEN;
+  } else if (lower === 'project') {
+    parts.scope = 'project';
+  } else if (lower === 'general') {
+    parts.scope = 'general';
+  } else {
+    parts.mountPoint = authority;
+  }
+  if (heading !== undefined) parts.heading = heading;
+  if (level !== undefined) parts.level = level;
+  if (query !== undefined) parts.query = query;
+  return parts;
+}
+
+function encodeAuthority(parts) {
+  if (parts.scope === 'project') return 'project';
+  if (parts.scope === 'general') return 'general';
+  const mp = parts.mountPoint || '';
+  if (mp.toLowerCase() === SELF_VAULT_TOKEN) return 'self';
+  return encodeURIComponent(mp);
+}
+
+function encodePath(path) {
+  if (!path) return '';
+  return path.split('/').map((seg) => encodeURIComponent(seg)).join('/');
+}
+
+/** Inverse of parseQtapUri — always emits canonical encoded form (':' → %3A). */
+function formatQtapUri(parts) {
+  const authority = encodeAuthority(parts);
+  let out = `${QTAP_URI_SCHEME}${authority}/${encodePath(parts.path || '')}`;
+  if (parts.heading !== undefined && parts.heading !== '') {
+    out += `#${encodeURIComponent(parts.heading)}`;
+    if (parts.level !== undefined) out += `:${parts.level}`;
+  }
+  if (parts.query && Object.keys(parts.query).length > 0) {
+    const q = Object.entries(parts.query)
+      .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+      .join('&');
+    out += `?${q}`;
+  }
+  return out;
+}
+
+/** Build a document-store URI for a store name/UUID and relative path. */
+function formatDocStoreUri(authority, path) {
+  return formatQtapUri({ scope: 'document_store', mountPoint: authority, path: path || '' });
+}
+
+module.exports = {
+  QTAP_URI_SCHEME,
+  SELF_VAULT_TOKEN,
+  QtapUriError,
+  isQtapUri,
+  parseQtapUri,
+  formatQtapUri,
+  formatDocStoreUri,
+};

package/lib/theme-validation.js

@@ -36,6 +36,12 @@ const BLOCKED_EXTENSIONS = new Set([
 // Theme ID must be lowercase alphanumeric with hyphens
 const THEME_ID_REGEX = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
 
+// Icon override names: lowercase kebab-case (mirrors the app's IconName contract)
+const ICON_NAME_REGEX = /^[a-z][a-z0-9-]*$/;
+
+// Allowed file extensions for icon override assets
+const ICON_OVERRIDE_EXTENSIONS = ['.svg', '.webp'];
+
 // Required color keys in a palette
 const REQUIRED_COLOR_KEYS = [
   'background', 'foreground', 'primary', 'primaryForeground',
@@ -124,6 +130,35 @@ function validateManifest(manifest) {
     }
   }
 
+  // Icons validation (per-icon override map: name -> bundle-relative asset path).
+  // The canonical icon-name list lives in the app and cannot be imported here, so
+  // this is a soft check: structure, asset extension, and traversal safety only.
+  if (manifest.icons !== undefined) {
+    if (typeof manifest.icons !== 'object' || manifest.icons === null || Array.isArray(manifest.icons)) {
+      errors.push('icons must be an object mapping icon names to asset paths');
+    } else {
+      for (const [iconName, assetPath] of Object.entries(manifest.icons)) {
+        if (!ICON_NAME_REGEX.test(iconName)) {
+          // Soft warning: the app validates the actual name list, but a malformed
+          // name here is almost certainly a typo that will silently never match.
+          warnings.push(`icons.${iconName} is not a valid icon name (expected lowercase kebab-case)`);
+        }
+        if (typeof assetPath !== 'string' || assetPath.length === 0) {
+          errors.push(`icons.${iconName} must be a non-empty string asset path`);
+          continue;
+        }
+        if (assetPath.includes('..') || path.isAbsolute(assetPath)) {
+          errors.push(`icons.${iconName} has an unsafe asset path: ${assetPath}`);
+          continue;
+        }
+        const ext = path.extname(assetPath).toLowerCase();
+        if (!ICON_OVERRIDE_EXTENSIONS.includes(ext)) {
+          errors.push(`icons.${iconName} must point to a .svg or .webp file (got "${assetPath}")`);
+        }
+      }
+    }
+  }
+
   return { valid: errors.length === 0, errors, warnings };
 }
 
@@ -383,4 +418,6 @@ module.exports = {
   ALLOWED_EXTENSIONS,
   BLOCKED_EXTENSIONS,
   THEME_ID_REGEX,
+  ICON_NAME_REGEX,
+  ICON_OVERRIDE_EXTENSIONS,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quilltap",
-  "version": "4.7.0-dev",
+  "version": "4.7.0-dev.117",
   "description": "Self-hosted AI workspace for writers, worldbuilders, and roleplayers. Run with npx quilltap.",
   "author": {
     "name": "Charles Sebold",
@@ -37,11 +37,11 @@
   ],
   "dependencies": {
     "@napi-rs/canvas": "^0.1.100",
-    "better-sqlite3-multiple-ciphers": "^12.10.0",
+    "better-sqlite3-multiple-ciphers": "^12.11.1",
     "node-pty": "^1.1.0",
     "sharp": "^0.34.5",
     "tar": "^7.5.16",
-    "yauzl": "^3.3.2"
+    "yauzl": "^3.4.0"
   },
   "engines": {
     "node": ">=24.0.0"