quilltap 4.8.0-dev.191 → 4.8.0-dev.192

package/lib/__tests__/docker-mounts.test.js

@@ -0,0 +1,216 @@
+/**
+ * Bind planning for filesystem-backed document stores.
+ *
+ * The planner decides what a container is allowed to see, so its edges matter
+ * more than its happy path: a nested store that shadows its parent, a missing
+ * path that Docker would helpfully materialise as an empty directory, or a
+ * Windows host where the whole path-identical scheme cannot work.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const {
+  planStoreMounts,
+  toDockerArgs,
+  findMissingBinds,
+  normalisePath,
+} = require('../docker-mounts');
+
+/** Build a doc_mount_points-shaped row with sensible defaults. */
+function store(overrides = {}) {
+  return {
+    id: 'id-' + (overrides.name || 'x'),
+    name: 'Store',
+    mountType: 'filesystem',
+    storeType: 'documents',
+    basePath: '/vaults/one',
+    enabled: 1,
+    ...overrides,
+  };
+}
+
+/** A path probe that treats the given list as the only existing directories. */
+const existsIn = (paths) => (p) => paths.includes(p);
+
+const linux = (rows, exists) => planStoreMounts(rows, { platform: 'linux', exists });
+const macos = (rows, exists) => planStoreMounts(rows, { platform: 'darwin', exists });
+
+describe('planStoreMounts', () => {
+  it('binds an enabled filesystem store at its own host path', () => {
+    const plan = linux([store({ name: 'Church', basePath: '/vaults/church' })], existsIn(['/vaults/church']));
+
+    expect(plan.binds).toEqual([
+      { hostPath: '/vaults/church', containerPath: '/vaults/church', stores: ['Church'] },
+    ]);
+  });
+
+  it('treats obsidian stores as filesystem-backed', () => {
+    const plan = linux(
+      [store({ name: 'Malory', mountType: 'obsidian', basePath: '/vaults/malory' })],
+      existsIn(['/vaults/malory'])
+    );
+
+    expect(plan.binds.map((b) => b.hostPath)).toEqual(['/vaults/malory']);
+  });
+
+  it('ignores database-backed and disabled stores', () => {
+    const plan = linux(
+      [
+        store({ name: 'Vault', mountType: 'database', basePath: '' }),
+        store({ name: 'Off', basePath: '/vaults/off', enabled: 0 }),
+      ],
+      existsIn(['/vaults/off'])
+    );
+
+    expect(plan.binds).toEqual([]);
+  });
+
+  it('emits one bind for several stores sharing a path', () => {
+    const plan = linux(
+      [
+        store({ name: 'Church', basePath: '/vaults/shared' }),
+        store({ name: 'Small Group', basePath: '/vaults/shared/' }),
+      ],
+      existsIn(['/vaults/shared'])
+    );
+
+    expect(plan.binds).toHaveLength(1);
+    expect(plan.binds[0].stores).toEqual(['Church', 'Small Group']);
+  });
+
+  it('drops a store nested inside another bound store', () => {
+    // Binding both would mount the child independently and shadow the
+    // parent's view of that subdirectory.
+    const plan = linux(
+      [
+        store({ name: 'Vault', basePath: '/vaults/obsidian' }),
+        store({ name: 'Notes', basePath: '/vaults/obsidian/notes' }),
+      ],
+      existsIn(['/vaults/obsidian', '/vaults/obsidian/notes'])
+    );
+
+    expect(plan.binds.map((b) => b.hostPath)).toEqual(['/vaults/obsidian']);
+  });
+
+  it('does not treat a sibling with a shared prefix as nested', () => {
+    const plan = linux(
+      [
+        store({ name: 'A', basePath: '/vaults/notes' }),
+        store({ name: 'B', basePath: '/vaults/notes-archive' }),
+      ],
+      existsIn(['/vaults/notes', '/vaults/notes-archive'])
+    );
+
+    expect(plan.binds.map((b) => b.hostPath)).toEqual(['/vaults/notes', '/vaults/notes-archive']);
+  });
+
+  it('skips a missing path rather than letting Docker fabricate it', () => {
+    const plan = linux([store({ name: 'Gone', basePath: '/vaults/gone' })], existsIn([]));
+
+    expect(plan.binds).toEqual([]);
+    expect(plan.skipped).toEqual([
+      { hostPath: '/vaults/gone', stores: ['Gone'], reason: 'missing' },
+    ]);
+    expect(plan.warnings.join(' ')).toContain('does not exist');
+  });
+
+  it('rejects a relative base path', () => {
+    const plan = linux([store({ name: 'Rel', basePath: 'relative/path' })], existsIn(['relative/path']));
+
+    expect(plan.binds).toEqual([]);
+    expect(plan.warnings.join(' ')).toContain('not absolute');
+  });
+
+  it('refuses path-identical binds on Windows', () => {
+    const plan = planStoreMounts([store({ basePath: 'C:\\Users\\me\\Vault' })], {
+      platform: 'win32',
+      exists: () => true,
+    });
+
+    expect(plan.unsupported).toBe(true);
+    expect(plan.binds).toEqual([]);
+    expect(plan.warnings.join(' ')).toContain('not supported on Windows');
+  });
+
+  it('warns about macOS paths outside Docker Desktop default shares', () => {
+    const plan = macos([store({ name: 'Odd', basePath: '/data/vault' })], existsIn(['/data/vault']));
+
+    expect(plan.binds).toHaveLength(1);
+    expect(plan.warnings.join(' ')).toContain('File sharing');
+  });
+
+  it('does not warn for macOS paths under a shared prefix', () => {
+    const plan = macos([store({ name: 'Home', basePath: '/Users/me/Vault' })], existsIn(['/Users/me/Vault']));
+
+    expect(plan.warnings.join(' ')).not.toContain('File sharing');
+  });
+
+  it('warns about host ownership on Linux', () => {
+    const plan = linux([store({ basePath: '/vaults/one' })], existsIn(['/vaults/one']));
+
+    expect(plan.warnings.join(' ')).toContain('--user');
+  });
+});
+
+describe('toDockerArgs', () => {
+  it('renders each bind as a -v pair', () => {
+    const plan = linux(
+      [
+        store({ name: 'A', basePath: '/vaults/a' }),
+        store({ name: 'B', basePath: '/vaults/b' }),
+      ],
+      existsIn(['/vaults/a', '/vaults/b'])
+    );
+
+    expect(toDockerArgs(plan)).toEqual([
+      '-v', '/vaults/a:/vaults/a',
+      '-v', '/vaults/b:/vaults/b',
+    ]);
+  });
+
+  it('keeps a path containing spaces in a single argument', () => {
+    // The argv is handed to execFileSync, so a space must not split the pair.
+    const plan = linux([store({ basePath: '/vaults/Local Obsidian' })], existsIn(['/vaults/Local Obsidian']));
+
+    expect(toDockerArgs(plan)).toEqual([
+      '-v', '/vaults/Local Obsidian:/vaults/Local Obsidian',
+    ]);
+  });
+});
+
+describe('findMissingBinds', () => {
+  const plan = () =>
+    linux(
+      [
+        store({ name: 'A', basePath: '/vaults/a' }),
+        store({ name: 'B', basePath: '/vaults/b' }),
+      ],
+      existsIn(['/vaults/a', '/vaults/b'])
+    );
+
+  it('reports binds a container was not created with', () => {
+    expect(findMissingBinds(plan(), ['/vaults/a']).map((b) => b.hostPath)).toEqual(['/vaults/b']);
+  });
+
+  it('reports nothing when every bind is present', () => {
+    expect(findMissingBinds(plan(), ['/vaults/a', '/vaults/b', '/data'])).toEqual([]);
+  });
+
+  it('ignores a trailing separator when comparing', () => {
+    expect(findMissingBinds(plan(), ['/vaults/a/', '/vaults/b/'])).toEqual([]);
+  });
+});
+
+describe('normalisePath', () => {
+  it.each([
+    ['/a/b/', '/a/b'],
+    ['/a//b', '/a/b'],
+    ['/a/./b', '/a/b'],
+    ['/a/c/../b', '/a/b'],
+    ['/', '/'],
+  ])('normalises %s to %s', (input, expected) => {
+    expect(normalisePath(input)).toBe(expected);
+  });
+});

package/lib/completion/bash.template

@@ -126,7 +126,7 @@ _quilltap_complete() {
       fi
       ;;
     docs)
-      local docs_verbs="list show files ls dir tree read export scan write delete mkdir move copy link rmdir mvdir status find grep reindex embed"
+      local docs_verbs="list show files ls dir tree read export scan write delete mkdir move copy link rmdir mvdir status docker-mounts find grep reindex embed"
       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"

package/lib/completion/fish.template

@@ -136,6 +136,7 @@ complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'scan' -d 'Trig
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'find' -d 'Substring search'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'grep' -d 'Pattern search in text'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'status' -d 'Per-mount status'
+complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'docker-mounts' -d 'Binds needed under Docker'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'reindex' -d 'Re-extract and chunk'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'embed' -d 'Enqueue embeddings'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'write' -d 'Write a file'

package/lib/completion/zsh.template

@@ -168,6 +168,7 @@ _quilltap_docs() {
     'find:Substring search'
     'grep:Pattern search inside text'
     'status:Per-mount status'
+    'docker-mounts:Bind mounts needed under Docker'
     'reindex:Re-extract and re-chunk'
     'embed:Enqueue embedding jobs'
     'write:Write a file'

package/lib/docker-mounts.js

@@ -0,0 +1,201 @@
+'use strict';
+
+/**
+ * Docker Bind Planning for Filesystem Document Stores
+ *
+ * A container sees only the host paths handed to it at creation time. Database
+ * -backed stores live inside the data directory and ride along on the single
+ * bind every Quilltap container already has; filesystem and Obsidian stores
+ * point anywhere on the host and are, by default, simply absent inside the
+ * container — the store lists happily from the cached mount index while every
+ * read and write against the real bytes fails.
+ *
+ * This module turns "what stores does this instance have" into "what -v flags
+ * does the container need". It is deliberately pure: the caller supplies the
+ * store rows, the platform, and a path probe, so the planner can be tested
+ * without a database, a filesystem, or Docker.
+ *
+ * ## Why the binds are path-identical
+ *
+ * Each store is bound at its own host path (`-v /host/vault:/host/vault`) so
+ * the `basePath` recorded in the database resolves unchanged whether Quilltap
+ * runs natively or in a container. The alternative — mounting under some
+ * container-local prefix — would require a translation layer on every path in
+ * and out of the database, and would make the same instance directory
+ * unusable outside the container.
+ *
+ * Docker creates missing destination ancestors itself, as root and mode 0755,
+ * during mount setup — so binding `/Users/you/Vault` into an image that has no
+ * `/Users` works, and the unprivileged app user can still traverse in. Those
+ * ancestors are *not* writable by the app user, which is a feature: a store
+ * that was never bound stays structurally unwritable rather than quietly
+ * accumulating a fabricated directory tree.
+ *
+ * @module docker-mounts
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Prefixes Docker Desktop for macOS shares with the VM out of the box. A bind
+ * whose source falls outside these is accepted by `docker run` but arrives in
+ * the container as an empty directory, which is a uniquely confusing failure —
+ * so it earns a warning rather than silence.
+ */
+const MACOS_DEFAULT_SHARED_PREFIXES = ['/Users', '/Volumes', '/private', '/tmp', '/var/folders'];
+
+/** Store types whose bytes live on the host filesystem rather than in the database. */
+const FILESYSTEM_MOUNT_TYPES = new Set(['filesystem', 'obsidian']);
+
+/**
+ * Normalise a base path for comparison: resolve `.`/`..`, collapse separators,
+ * and drop any trailing separator so `/a/b` and `/a/b/` are one path.
+ */
+function normalisePath(basePath) {
+  const resolved = path.posix.normalize(String(basePath).trim());
+  if (resolved.length > 1 && resolved.endsWith('/')) {
+    return resolved.slice(0, -1);
+  }
+  return resolved;
+}
+
+/** True when `candidate` sits inside `ancestor` (and is not `ancestor` itself). */
+function isDescendantOf(candidate, ancestor) {
+  return candidate.startsWith(ancestor.endsWith('/') ? ancestor : ancestor + '/');
+}
+
+/**
+ * Plan the bind mounts an instance's filesystem-backed stores require.
+ *
+ * @param {Array<object>} rows - doc_mount_points rows (id, name, mountType, basePath, enabled)
+ * @param {object} [options]
+ * @param {string} [options.platform] - process.platform value; defaults to the current host
+ * @param {(p: string) => boolean} [options.exists] - path probe, injectable for tests
+ * @returns {{binds: Array<object>, skipped: Array<object>, warnings: Array<string>, unsupported: boolean}}
+ */
+function planStoreMounts(rows, options = {}) {
+  const platform = options.platform || process.platform;
+  const exists =
+    options.exists ||
+    ((p) => {
+      try {
+        return fs.statSync(p).isDirectory();
+      } catch {
+        return false;
+      }
+    });
+
+  const warnings = [];
+
+  // Windows host paths (C:\Users\…) have no in-container equivalent, so the
+  // path-identical scheme this module depends on cannot work there. Say so
+  // plainly rather than emitting binds that would silently misbehave.
+  if (platform === 'win32') {
+    return {
+      binds: [],
+      skipped: [],
+      warnings: [
+        'Automatic store binds are not supported on Windows: container paths cannot mirror ' +
+          'Windows host paths. Filesystem document stores must be bound manually.',
+      ],
+      unsupported: true,
+    };
+  }
+
+  const candidates = rows.filter(
+    (r) => FILESYSTEM_MOUNT_TYPES.has(r.mountType) && r.enabled && String(r.basePath || '').trim()
+  );
+
+  // Group stores by normalised path first — several stores commonly share one
+  // vault root, and they need exactly one bind between them.
+  const byPath = new Map();
+  for (const row of candidates) {
+    const normalised = normalisePath(row.basePath);
+    if (!path.posix.isAbsolute(normalised)) {
+      warnings.push(`Skipping store '${row.name}': base path '${row.basePath}' is not absolute.`);
+      continue;
+    }
+    if (!byPath.has(normalised)) {
+      byPath.set(normalised, []);
+    }
+    byPath.get(normalised).push(row.name);
+  }
+
+  const allPaths = [...byPath.keys()].sort();
+
+  const binds = [];
+  const skipped = [];
+
+  for (const hostPath of allPaths) {
+    const stores = byPath.get(hostPath);
+
+    // A path nested inside another selected path is already covered by that
+    // bind. Binding both is redundant, and Docker mounts them independently —
+    // which would shadow the parent's view of the child directory.
+    const ancestor = allPaths.find((other) => other !== hostPath && isDescendantOf(hostPath, other));
+    if (ancestor) {
+      continue;
+    }
+
+    if (!exists(hostPath)) {
+      // Never create the source. Docker would happily materialise a missing
+      // bind source as a root-owned empty directory, which presents an empty
+      // store as a healthy one — the exact failure this feature exists to end.
+      skipped.push({ hostPath, stores, reason: 'missing' });
+      continue;
+    }
+
+    if (platform === 'darwin' && !MACOS_DEFAULT_SHARED_PREFIXES.some((p) => hostPath === p || isDescendantOf(hostPath, p))) {
+      warnings.push(
+        `'${hostPath}' is outside Docker Desktop's default shared paths. Add it under ` +
+          'Settings → Resources → File sharing, or the store will appear empty in the container.'
+      );
+    }
+
+    binds.push({ hostPath, containerPath: hostPath, stores });
+  }
+
+  if (platform === 'linux' && binds.length > 0) {
+    warnings.push(
+      'On Linux, bind mounts preserve host ownership. If the container user cannot write to ' +
+        'these paths, start the container with --user "$(id -u):$(id -g)".'
+    );
+  }
+
+  for (const entry of skipped) {
+    warnings.push(
+      `Skipping '${entry.hostPath}' (${entry.stores.join(', ')}): the path does not exist on this host.`
+    );
+  }
+
+  return { binds, skipped, warnings, unsupported: false };
+}
+
+/** Render a plan as `docker run` arguments. */
+function toDockerArgs(plan) {
+  const args = [];
+  for (const bind of plan.binds) {
+    args.push('-v', `${bind.hostPath}:${bind.containerPath}`);
+  }
+  return args;
+}
+
+/**
+ * Compare a plan against the binds a container was actually created with.
+ * Returns the host paths a running container is missing, which is what tells
+ * an operator that a restart is owed.
+ */
+function findMissingBinds(plan, existingSources) {
+  const existing = new Set(existingSources.map(normalisePath));
+  return plan.binds.filter((b) => !existing.has(b.hostPath));
+}
+
+module.exports = {
+  planStoreMounts,
+  toDockerArgs,
+  findMissingBinds,
+  normalisePath,
+  FILESYSTEM_MOUNT_TYPES,
+  MACOS_DEFAULT_SHARED_PREFIXES,
+};

package/lib/docs-commands.js

@@ -71,6 +71,8 @@ Read subcommands:
   grep [--mount <name|id|all>] [--ignore-case] [-l] [--max N] [--context N] <pattern>
                                          Substring search inside extracted text
   status [--mount <name|id>] [--top N]   Per-mount extraction + embedding rollup
+  docker-mounts [--format args|json]     Bind mounts this instance's filesystem
+                                         stores need to be visible in Docker
 
 Server-required subcommands (background-job queue lives in the running server):
   grep --semantic [--mount <name|id|all>] [--top N] [--threshold 0..1] <query>
@@ -210,6 +212,8 @@ function parseFlags(args) {
     threshold: -1,
     // base64 read/write flag
     base64: false,
+    // docker-mounts output shape: table (human), args (docker run flags), json
+    format: '',
   };
   const positional = [];
   let i = 0;
@@ -229,6 +233,7 @@ function parseFlags(args) {
         break;
       }
       case '--json': flags.json = true; break;
+      case '--format': flags.format = args[++i]; break;
       case '--uri': flags.uri = true; break;
       case '--rendered': flags.rendered = true; break;
       case '--folder': flags.folder = args[++i]; break;
@@ -487,6 +492,95 @@ async function handleList(flags) {
   }
 }
 
+// ----------------------------------------------------------------------------
+// docker-mounts
+// ----------------------------------------------------------------------------
+
+/**
+ * Report the bind mounts this instance's filesystem-backed stores need in
+ * order to be reachable from inside a container.
+ *
+ * `--format args` prints only the flags, one per line, so a start script can
+ * splice them into a `docker run` argv without parsing prose. Everything
+ * advisory goes to stderr for exactly that reason: stdout stays machine-clean
+ * even when there are warnings worth a human's attention.
+ */
+async function handleDockerMounts(flags) {
+  const { planStoreMounts, toDockerArgs } = require('./docker-mounts');
+  const { db } = await openDb(flags);
+
+  let rows;
+  try {
+    rows = db.prepare(`
+      SELECT id, name, mountType, storeType, basePath, enabled
+      FROM doc_mount_points
+      WHERE mountType != 'database'
+      ORDER BY name COLLATE NOCASE
+    `).all();
+  } finally {
+    db.close();
+  }
+
+  const plan = planStoreMounts(rows);
+  const format = flags.format || (flags.json ? 'json' : 'table');
+
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify(plan, null, 2) + '\n');
+    return;
+  }
+
+  if (format === 'args') {
+    for (const arg of toDockerArgs(plan)) {
+      process.stdout.write(arg + '\n');
+    }
+    for (const warning of plan.warnings) {
+      process.stderr.write(`warning: ${warning}\n`);
+    }
+    return;
+  }
+
+  if (plan.unsupported) {
+    for (const warning of plan.warnings) {
+      console.log(`${YELLOW}${warning}${RESET}`);
+    }
+    return;
+  }
+
+  if (plan.binds.length === 0 && plan.skipped.length === 0) {
+    console.log('(no filesystem-backed document stores — nothing to bind)');
+    return;
+  }
+
+  if (plan.binds.length > 0) {
+    console.log(`${BOLD}Bind mounts required:${RESET}`);
+    console.table(
+      plan.binds.map((b) => ({
+        'host path': b.hostPath,
+        stores: b.stores.join(', '),
+      }))
+    );
+  }
+
+  if (plan.skipped.length > 0) {
+    console.log(`${BOLD}Skipped:${RESET}`);
+    console.table(
+      plan.skipped.map((s) => ({
+        'host path': s.hostPath,
+        stores: s.stores.join(', '),
+        reason: s.reason,
+      }))
+    );
+  }
+
+  for (const warning of plan.warnings) {
+    console.log(`${YELLOW}warning:${RESET} ${warning}`);
+  }
+
+  console.log('');
+  console.log(`${DIM}Binds are applied when a container is created. Re-run the start script`);
+  console.log(`with --recreate to rebuild the container with these stores included.${RESET}`);
+}
+
 // ----------------------------------------------------------------------------
 // show
 // ----------------------------------------------------------------------------
@@ -3033,6 +3127,9 @@ async function docsCommand(args) {
       case 'status':
         await handleStatus(flags);
         break;
+      case 'docker-mounts':
+        await handleDockerMounts(flags);
+        break;
       case 'find':
         await handleFind(flags, positional);
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quilltap",
-  "version": "4.8.0-dev.191",
+  "version": "4.8.0-dev.192",
   "description": "Self-hosted AI workspace for writers, worldbuilders, and roleplayers. Run with npx quilltap.",
   "author": {
     "name": "Charles Sebold",