quilltap 4.6.0-dev → 4.6.0-dev.106

package/bin/quilltap.js

@@ -13,6 +13,7 @@ const {
   loadDbKey,
 } = require('../lib/db-helpers');
 const { resolveInstance } = require('../lib/instances');
+const { resolveModuleDir, ensureNativeModules } = require('../lib/native-modules');
 
 const PACKAGE_DIR = path.resolve(__dirname, '..');
 
@@ -137,85 +138,6 @@ function openBrowser(url) {
   });
 }
 
-// Resolve a native module's directory, handling npm hoisting.
-// Returns the directory containing package.json, or null if not found.
-function resolveModuleDir(moduleName) {
-  try {
-    const pkgJson = require.resolve(moduleName + '/package.json');
-    return path.dirname(pkgJson);
-  } catch {
-    return null;
-  }
-}
-
-// Check if native modules are compiled for the current Node.js version.
-// This handles the case where npx caches the package but the user upgrades
-// Node.js — the cached native modules will have a stale NODE_MODULE_VERSION.
-function ensureNativeModules() {
-  const needsRebuild = [];
-
-  // 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');
-    }
-  }
-
-  // Check sharp: loads its native binding eagerly on require, but we use
-  // the same explicit-path approach for consistency and reliability.
-  try {
-    require('sharp');
-  } catch (err) {
-    if (err.message && err.message.includes('NODE_MODULE_VERSION')) {
-      needsRebuild.push('sharp');
-    } else if (err.code === 'MODULE_NOT_FOUND') {
-      needsRebuild.push('sharp');
-    }
-  }
-
-  // Check node-pty: backs the Ariel terminal feature. Loaded dynamically by
-  // pty-manager in the standalone server, so resolution must succeed and the
-  // native binding's NODE_MODULE_VERSION must match the runtime.
-  try {
-    require('node-pty');
-  } catch (err) {
-    if (err.message && err.message.includes('NODE_MODULE_VERSION')) {
-      needsRebuild.push('node-pty');
-    } else if (err.code === 'MODULE_NOT_FOUND') {
-      needsRebuild.push('node-pty');
-    }
-  }
-
-  if (needsRebuild.length === 0) return;
-
-  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('');
-  } 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('');
-  }
-}
-
 // Symlink native modules into the standalone directory's node_modules
 // so that standard Node.js resolution finds them without relying on NODE_PATH.
 function linkNativeModules(standaloneDir) {
@@ -266,25 +188,67 @@ function linkNativeModules(standaloneDir) {
                         || resolveModuleDir('better-sqlite3');
   linkModule('better-sqlite3', betterSqlite3Dir);
 
-  // Link node-pty — the standalone tarball strips it (platform-specific),
-  // and pty-manager loads it via a dynamic require, so it needs to resolve
-  // from standaloneDir/node_modules.
-  const nodePtyDir = resolveModuleDir('node-pty');
-  linkModule('node-pty', nodePtyDir);
-  if (nodePtyDir) {
-    // Some npm cache extractions strip the executable bit on spawn-helper,
-    // causing pty.spawn() to fail with `posix_spawnp failed`. Restore it.
-    const prebuildsDir = path.join(nodePtyDir, 'prebuilds');
-    if (fs.existsSync(prebuildsDir)) {
-      try {
-        for (const entry of fs.readdirSync(prebuildsDir, { withFileTypes: true })) {
-          if (!entry.isDirectory()) continue;
-          const helper = path.join(prebuildsDir, entry.name, 'spawn-helper');
-          if (fs.existsSync(helper)) {
-            try { fs.chmodSync(helper, 0o755); } catch { /* best-effort */ }
+  // Link node-pty — but only when we have to. The standalone tarball ships
+  // node-pty intact with cross-platform prebuilds (darwin-arm64, darwin-x64,
+  // win32-arm64, win32-x64). On those platforms the tarball-shipped copy is
+  // already correct, and we MUST NOT replace it with a symlink to the
+  // npm-installed copy: `sudo npm install -g quilltap` on macOS can strip the
+  // executable bit off `spawn-helper`, and we can't chmod a root-owned file
+  // back as a non-root runtime user — pty.spawn() then fails with
+  // `posix_spawnp failed`. Only Linux (which has no node-pty prebuild) and
+  // rebuild-failure cases need the symlink.
+  const standaloneNodePtyPath = path.join(standaloneNodeModules, 'node-pty');
+  const standaloneHasUsablePty = (() => {
+    try {
+      const stat = fs.lstatSync(standaloneNodePtyPath);
+      if (stat.isSymbolicLink()) return false; // prior broken-symlink state — replace it
+      if (!stat.isDirectory()) return false;
+    } catch {
+      return false;
+    }
+    const platformPrebuildDir = path.join(
+      standaloneNodePtyPath,
+      'prebuilds',
+      `${process.platform}-${process.arch}`,
+    );
+    return fs.existsSync(platformPrebuildDir);
+  })();
+
+  if (!standaloneHasUsablePty) {
+    const nodePtyDir = resolveModuleDir('node-pty');
+    linkModule('node-pty', nodePtyDir);
+    if (nodePtyDir) {
+      // Some npm cache extractions (notably `sudo npm install -g`) strip the
+      // executable bit on spawn-helper. Restore it where we can. If chmod
+      // fails because we don't own the file (typical when the CLI was
+      // installed with sudo and is run as a non-root user), warn loudly —
+      // silent failure here produces the `posix_spawnp failed` runtime error
+      // with no actionable hint.
+      const prebuildsDir = path.join(nodePtyDir, 'prebuilds');
+      if (fs.existsSync(prebuildsDir)) {
+        try {
+          for (const entry of fs.readdirSync(prebuildsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory()) continue;
+            const helper = path.join(prebuildsDir, entry.name, 'spawn-helper');
+            if (!fs.existsSync(helper)) continue;
+            try {
+              fs.chmodSync(helper, 0o755);
+            } catch (err) {
+              if (err && err.code === 'EPERM') {
+                console.error('');
+                console.error(`  Warning: Could not make node-pty spawn-helper executable:`);
+                console.error(`    ${helper}`);
+                console.error(`  The file is owned by another user (likely root from a sudo'd`);
+                console.error(`  global install). Terminal sessions will fail to spawn with`);
+                console.error(`  "posix_spawnp failed" until this is fixed. Run:`);
+                console.error(`    sudo chmod 755 "${helper}"`);
+                console.error('');
+              }
+              // Other errors are non-fatal — node-pty may still work if the bit was already set.
+            }
           }
-        }
-      } catch { /* best-effort */ }
+        } catch { /* best-effort */ }
+      }
     }
   }
 
@@ -740,6 +704,11 @@ Subcommands (high-level shortcuts; auto-pick the right database):
   log <id>                    Full request/response of a single LLM log
   memories --character <id>   Memories held by a character
                               (flags: --about <id|name> --source AUTO|MANUAL)
+  characters status           Per-character vault readiness report:
+                              flag value, vault present, single-file count,
+                              Prompts/ and Scenarios/ folder counts, and any
+                              divergence between DB columns and vault content.
+                              (flags: --id <id|name> --diverged --blocked --limit N)
   optimize [target...]        Run maintenance (VACUUM + ANALYZE + PRAGMA optimize)
                               on the named databases, or all of them if no
                               target is given. Targets: main, llm-logs,
@@ -762,6 +731,8 @@ Low-level options (legacy; still supported):
   --tables              List all tables in the active database
   --count <table>       Show row count for a table
   --repl                Interactive SQL prompt (extras: .cols, .find)
+  --json                Emit machine-readable JSON instead of a table
+                        (works with --tables, --count, and raw SQL)
   --llm-logs            Target the LLM logs database
   --mount-points        Target the document mount-index database
   --data-dir <path>     Override data directory (pass instance root)
@@ -869,6 +840,7 @@ async function dbCommand(args) {
   let lockStatus = false;
   let lockClean = false;
   let lockOverride = false;
+  let asJson = false;
 
   let i = 0;
   while (i < cleaned.length) {
@@ -878,6 +850,7 @@ async function dbCommand(args) {
       case '--tables': showTables = true; break;
       case '--count': countTable = cleaned[++i]; break;
       case '--repl': repl = true; break;
+      case '--json': asJson = true; break;
       case '--help': case '-h': showHelp = true; break;
       case '--lock-status': lockStatus = true; break;
       case '--lock-clean': lockClean = true; break;
@@ -971,22 +944,27 @@ async function dbCommand(args) {
   try {
     if (showTables) {
       const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name").all();
-      for (const t of tables) console.log(t.name);
+      if (asJson) console.log(JSON.stringify(tables.map(t => t.name), null, 2));
+      else for (const t of tables) console.log(t.name);
     } else if (countTable) {
       const row = db.prepare(`SELECT count(*) as count FROM "${countTable}"`).get();
-      console.log(row.count);
+      if (asJson) console.log(JSON.stringify({ table: countTable, count: row.count }, null, 2));
+      else console.log(row.count);
     } else if (sql) {
       const stmt = db.prepare(sql);
       if (stmt.reader) {
         const rows = stmt.all();
-        if (rows.length === 0) {
+        if (asJson) {
+          console.log(JSON.stringify(rows, null, 2));
+        } else if (rows.length === 0) {
           console.log('(no results)');
         } else {
           console.table(rows);
         }
       } else {
         const info = stmt.run();
-        console.log(`Changes: ${info.changes}`);
+        if (asJson) console.log(JSON.stringify({ changes: info.changes, lastInsertRowid: Number(info.lastInsertRowid) }, null, 2));
+        else console.log(`Changes: ${info.changes}`);
       }
     } else if (repl) {
       const readline = require('readline');

package/lib/completion/bash.template

@@ -12,15 +12,19 @@ _quilltap_complete() {
   cword=$COMP_CWORD
 
   # Global options that can appear before subcommands
-  local global_opts="-d --data-dir -i --instance -p --port -o --open -v --version -h --help --update"
+  local global_opts="-d --data-dir -i --instance -p --port -o --open -v --version -h --help --update --passphrase"
+
+  # Top-level subcommands
+  local top_cmds="db docs themes instances memories memory-diff logs migrations completion"
 
   # Get the subcommand (first non-option word after quilltap)
   local subcommand=""
+  local subverb=""
   local i=1
   while [[ $i -lt $cword ]]; do
     local word="${words[$i]}"
     case "$word" in
-      -d|--data-dir|-i|--instance|-p|--port)
+      -d|--data-dir|-i|--instance|-p|--port|--passphrase)
         # These take a value, skip the next word
         ((i += 2))
         ;;
@@ -33,22 +37,26 @@ _quilltap_complete() {
         ((i += 1))
         ;;
       *)
-        # This is the subcommand
-        subcommand="$word"
-        break
+        if [[ -z "$subcommand" ]]; then
+          subcommand="$word"
+        elif [[ -z "$subverb" ]]; then
+          subverb="$word"
+        fi
+        ((i += 1))
         ;;
     esac
   done
 
   # If we're completing a global flag value
-  if [[ "$prev" == "-d" ]] || [[ "$prev" == "--data-dir" ]] || \
-     [[ "$prev" == "-p" ]] || [[ "$prev" == "--port" ]]; then
-    # No completion for paths or ports
+  if [[ "$prev" == "-d" ]] || [[ "$prev" == "--data-dir" ]]; then
+    # Complete with directories
+    COMPREPLY=($(compgen -d -- "$cur"))
+    return
+  fi
+  if [[ "$prev" == "-p" ]] || [[ "$prev" == "--port" ]] || [[ "$prev" == "--passphrase" ]]; then
     return
   fi
-
   if [[ "$prev" == "-i" ]] || [[ "$prev" == "--instance" ]]; then
-    # Complete with instance names
     local instances=$(command quilltap instances list --names-only 2>/dev/null)
     COMPREPLY=($(compgen -W "$instances" -- "$cur"))
     return
@@ -59,53 +67,164 @@ _quilltap_complete() {
     if [[ "$cur" == -* ]]; then
       COMPREPLY=($(compgen -W "$global_opts" -- "$cur"))
     else
-      COMPREPLY=($(compgen -W "db docs themes instances memories memory-diff completion" -- "$cur"))
+      COMPREPLY=($(compgen -W "$top_cmds" -- "$cur"))
     fi
     return
   fi
 
+  # Shared flag-value completions for any subcommand
+  case "$prev" in
+    --mount)
+      local mounts=$(command quilltap docs list --names-only 2>/dev/null)
+      COMPREPLY=($(compgen -W "$mounts" -- "$cur"))
+      return
+      ;;
+    --character|--about)
+      # No live source; suggest common literals
+      COMPREPLY=($(compgen -W "all self none" -- "$cur"))
+      return
+      ;;
+    --source)
+      COMPREPLY=($(compgen -W "AUTO MANUAL" -- "$cur"))
+      return
+      ;;
+    --sort)
+      COMPREPLY=($(compgen -W "name path size modified created reinforced importance accessed reinforcement-count links" -- "$cur"))
+      return
+      ;;
+    --field)
+      COMPREPLY=($(compgen -W "request response both" -- "$cur"))
+      return
+      ;;
+    --type)
+      COMPREPLY=($(compgen -W "file folder" -- "$cur"))
+      return
+      ;;
+    --stream)
+      COMPREPLY=($(compgen -W "combined error stdout stderr startup" -- "$cur"))
+      return
+      ;;
+  esac
+
   # Subcommand-specific completion
-  local subcommand_opts=""
   case "$subcommand" in
     db)
-      subcommand_opts="schema find chats messages logs message log memories optimize backup integrity"
-      if [[ "$cur" == -* ]]; then
-        subcommand_opts="$subcommand_opts --instance --data-dir --json --help"
+      local db_verbs="schema find chats messages logs message log memories optimize backup integrity"
+      local db_flags="--instance --data-dir --passphrase --json --limit --grep \
+        --character --project --about --source --chat --message --rendered --field \
+        --tail --last --full --from --type --out --help \
+        --tables --count --repl --llm-logs --mount-points \
+        --lock-status --lock-clean --lock-override"
+      if [[ -z "$subverb" ]]; then
+        if [[ "$cur" == -* ]]; then
+          COMPREPLY=($(compgen -W "$db_flags" -- "$cur"))
+        else
+          COMPREPLY=($(compgen -W "$db_verbs" -- "$cur"))
+        fi
+      else
+        COMPREPLY=($(compgen -W "$db_flags" -- "$cur"))
       fi
-      COMPREPLY=($(compgen -W "$subcommand_opts" -- "$cur"))
       ;;
     docs)
       local docs_verbs="list show files ls dir read export scan write delete mkdir move copy status find grep reindex embed"
-      if [[ "$cur" == -* ]]; then
-        docs_verbs="$docs_verbs --mount --instance --data-dir --port --json --help --force --rendered --links"
+      local docs_flags="--mount --instance --data-dir --passphrase --port --json --help \
+        --force --rendered --links --folder --type --ext --limit --max --context --top --threshold \
+        --ignore-case -l --wait -R --recursive --sort -r --reverse --depth --max-nodes --long --semantic"
+      if [[ -z "$subverb" ]]; then
+        if [[ "$cur" == -* ]]; then
+          COMPREPLY=($(compgen -W "$docs_flags" -- "$cur"))
+        else
+          COMPREPLY=($(compgen -W "$docs_verbs" -- "$cur"))
+        fi
+      else
+        COMPREPLY=($(compgen -W "$docs_flags" -- "$cur"))
       fi
-      COMPREPLY=($(compgen -W "$docs_verbs" -- "$cur"))
       ;;
     themes)
-      subcommand_opts="list install uninstall validate export create search update registry"
-      if [[ "$cur" == -* ]]; then
-        subcommand_opts="$subcommand_opts --instance --data-dir --output --help"
+      local themes_verbs="list install uninstall validate export create search update registry"
+      local themes_flags="--instance --data-dir --output -o --help"
+      if [[ -z "$subverb" ]]; then
+        if [[ "$cur" == -* ]]; then
+          COMPREPLY=($(compgen -W "$themes_flags" -- "$cur"))
+        else
+          COMPREPLY=($(compgen -W "$themes_verbs" -- "$cur"))
+        fi
+      elif [[ "$subverb" == "registry" ]]; then
+        local registry_verbs="list add remove refresh keygen sign"
+        local registry_flags="--key -k --name -n --output -o --help"
+        if [[ "$cur" == -* ]]; then
+          COMPREPLY=($(compgen -W "$registry_flags" -- "$cur"))
+        else
+          COMPREPLY=($(compgen -W "$registry_verbs" -- "$cur"))
+        fi
+      else
+        COMPREPLY=($(compgen -W "$themes_flags" -- "$cur"))
       fi
-      COMPREPLY=($(compgen -W "$subcommand_opts" -- "$cur"))
       ;;
     instances)
-      subcommand_opts="list ls show path where add create remove rm delete set-passphrase passphrase"
-      if [[ "$cur" == -* ]]; then
-        subcommand_opts="$subcommand_opts --help"
+      local inst_verbs="list ls show path where add create remove rm delete set-passphrase passphrase default rename"
+      local inst_flags="--names-only --json --clear --help"
+      if [[ -z "$subverb" ]]; then
+        if [[ "$cur" == -* ]]; then
+          COMPREPLY=($(compgen -W "$inst_flags" -- "$cur"))
+        else
+          COMPREPLY=($(compgen -W "$inst_verbs" -- "$cur"))
+        fi
+      else
+        # Most instances verbs take a name as positional; offer registered names
+        case "$subverb" in
+          show|remove|rm|delete|set-passphrase|passphrase|default|rename)
+            local instances=$(command quilltap instances list --names-only 2>/dev/null)
+            if [[ "$cur" == -* ]]; then
+              COMPREPLY=($(compgen -W "$inst_flags" -- "$cur"))
+            else
+              COMPREPLY=($(compgen -W "$instances" -- "$cur"))
+            fi
+            ;;
+          *)
+            COMPREPLY=($(compgen -W "$inst_flags" -- "$cur"))
+            ;;
+        esac
       fi
-      COMPREPLY=($(compgen -W "$subcommand_opts" -- "$cur"))
       ;;
     memories)
       local mem_verbs="ls find grep show tree status validate"
-      if [[ "$cur" == -* ]]; then
-        mem_verbs="$mem_verbs --character --about --source --chat --project --since --until --min-importance --min-reinforced --has-embedding --no-embedding --sort --instance --data-dir --json --help"
+      local mem_flags="--character --about --source --chat --project --since --until \
+        --min-importance --min-reinforced --has-embedding --no-embedding \
+        --sort -r --reverse --limit --full-titles --in --no-related --list \
+        --ignore-case -i --paths-only -l --max --context --depth --max-nodes \
+        --semantic --top --threshold \
+        --instance --data-dir --passphrase --port --json --help"
+      if [[ -z "$subverb" ]]; then
+        if [[ "$cur" == -* ]]; then
+          COMPREPLY=($(compgen -W "$mem_flags" -- "$cur"))
+        else
+          COMPREPLY=($(compgen -W "$mem_verbs" -- "$cur"))
+        fi
+      else
+        COMPREPLY=($(compgen -W "$mem_flags" -- "$cur"))
       fi
-      COMPREPLY=($(compgen -W "$mem_verbs" -- "$cur"))
       ;;
     memory-diff)
-      if [[ "$cur" == -* ]]; then
-        subcommand_opts="--instance --data-dir --help"
-        COMPREPLY=($(compgen -W "$subcommand_opts" -- "$cur"))
+      local md_flags="--instance --data-dir --passphrase --port --concurrency --out --help"
+      COMPREPLY=($(compgen -W "$md_flags" -- "$cur"))
+      ;;
+    logs)
+      local logs_flags="--stream --tail -f --follow --grep \
+        --instance --data-dir --passphrase --help"
+      COMPREPLY=($(compgen -W "$logs_flags" -- "$cur"))
+      ;;
+    migrations)
+      local mig_verbs="status pending run"
+      local mig_flags="--dry-run --json --instance --data-dir --passphrase --help"
+      if [[ -z "$subverb" ]]; then
+        if [[ "$cur" == -* ]]; then
+          COMPREPLY=($(compgen -W "$mig_flags" -- "$cur"))
+        else
+          COMPREPLY=($(compgen -W "$mig_verbs" -- "$cur"))
+        fi
+      else
+        COMPREPLY=($(compgen -W "$mig_flags" -- "$cur"))
       fi
       ;;
     completion)