quilltap 4.9.0-dev.73 → 4.9.0-dev.87

package/README.md

@@ -182,6 +182,7 @@ quilltap docs export <mount> <outputDir>        # Mount → directory
 quilltap docs find <pattern>                    # Substring match on file names (--mount, --ext, --type, --limit)
 quilltap docs grep <pattern>                    # Substring match on extracted text (--mount, --ignore-case, -l, --max, --context)
 quilltap docs status                            # Per-mount extraction + embedding rollup (--mount, --top)
+quilltap docs docker-mounts                     # Bind mounts filesystem stores need under Docker (--format args|json)
 
 # Server-required
 quilltap docs scan <mount>                                    # Trigger a rescan
@@ -391,8 +392,11 @@ Fish picks new completion files up automatically — no shell restart needed.
 
 - **Subcommands**: `quilltap d<TAB>` → `db docs`
 - **Sub-verbs per namespace**: `quilltap db s<TAB>` → `schema show`
+- **Flags per verb**: `quilltap docs docker-mounts --<TAB>` → the flags that verb accepts
 - **Instance names**: `quilltap --instance Fr<TAB>` → registered instances
-- **Mount names**: `quilltap docs ls --mount Qu<TAB>` → mount points in the active instance
+- **Mount names**: both `--mount` and the positional a verb takes — `quilltap docs ls Qu<TAB>`, and either end of `docs move`/`copy`/`link`
+
+Completions **parse the line rather than counting words**, so a flag typed anywhere the CLI itself accepts one does not derail them: `quilltap docs --instance Friday <TAB>` still offers the `docs` verbs. bash and zsh also reuse the `-i` / `-d` / `--passphrase` already on the line when looking store names up, so the names offered come from the instance you are addressing rather than the default one. fish completes `--mount` but not the positionals, and always reads the default instance.
 
 Dynamic completions shell out to `quilltap`'s own subcommands. If the active instance is encrypted and no passphrase is reachable, the completion silently returns nothing rather than prompting in the middle of a tab.
 

package/lib/__tests__/completion-coverage.test.js

@@ -94,3 +94,98 @@ describe('every subcommand has its own completion arm', () => {
     expect(noFlags).toEqual([]);
   });
 });
+
+/**
+ * The arm-per-subcommand check above is still too coarse: `docs docker-mounts`
+ * had its own arm in all three shells while `--format`, its only flag, was
+ * offered by none of them. A flag documented in a subcommand's own `--help` is
+ * the contract the user reads, so that text is the source of truth here —
+ * whatever `--help` advertises, the three templates must offer.
+ *
+ * Each entry names the single function whose template literal prints that
+ * subcommand's help.
+ */
+const HELP_SOURCES = {
+  db: ['bin/quilltap.js', 'printDbHelp'],
+  docs: ['lib/docs-commands.js', 'printDocsHelp'],
+  memories: ['lib/memories-commands.js', 'printMemoriesHelp'],
+  themes: ['lib/theme-commands.js', 'printHelp'],
+  instances: ['lib/instances-commands.js', 'printHelp'],
+  logs: ['lib/logs-commands.js', 'printLogsHelp'],
+  migrations: ['lib/migrations-commands.js', 'printHelp'],
+  maintenance: ['lib/maintenance-commands.js', 'printHelp'],
+  'file-verify': ['lib/file-verify-commands.js', 'printHelp'],
+  'memory-diff': ['lib/memory-diff-command.js', 'printMemoryDiffHelp'],
+  'recall-replay': ['lib/recall-replay-command.js', 'printRecallReplayHelp'],
+  completion: ['lib/completion-commands.js', 'printCompletionHelp'],
+};
+
+const PKG_ROOT = path.join(__dirname, '..', '..');
+
+/**
+ * Long flags named anywhere in one subcommand's help text. The declaration
+ * pattern tolerates arbitrary whitespace and an `async`/parameter list, so
+ * reformatting a help function does not fail a test about its content.
+ */
+function flagsInHelp(relPath, fnName) {
+  const src = fs.readFileSync(path.join(PKG_ROOT, relPath), 'utf8');
+  const decl = String.raw`(?:async\s+)?function\s+${fnName}\s*\([^)]*\)\s*\{`;
+  const body = src.match(new RegExp(`${decl}([\\s\\S]*?)\\n\\}`));
+  if (!body) throw new Error(`Could not locate ${fnName}() in ${relPath}`);
+  return [...new Set(body[1].match(/--[a-z0-9][a-z0-9-]+/g) || [])].sort();
+}
+
+/**
+ * `--max` is a prefix of `--max-nodes`, so a plain substring test passes for a
+ * flag that is not actually there. Require the match to end at a non-flag
+ * character.
+ */
+function mentionsFlag(haystack, flag) {
+  return new RegExp(`${flag}(?![a-z0-9-])`).test(haystack);
+}
+
+describe('completions offer every flag the help text advertises', () => {
+  it('covers every subcommand in the dispatch table', () => {
+    // A new subcommand needs a help source here, or its flags go unchecked.
+    expect(Object.keys(HELP_SOURCES).sort()).toEqual([...SUBCOMMANDS].sort());
+  });
+
+  const cases = Object.entries(HELP_SOURCES).flatMap(([sub, [file, fn]]) =>
+    ['bash', 'zsh', 'fish'].map((shell) => [sub, shell, file, fn])
+  );
+
+  it.each(cases)('%s: %s template offers every documented flag', (sub, shell, file, fn) => {
+    const tpl = fs.readFileSync(path.join(COMPLETION_DIR, `${shell}.template`), 'utf8');
+    // fish spells the flag `-l 'name'`, already an exact quoted token.
+    const present = (flag) =>
+      shell === 'fish' ? tpl.includes(`-l '${flag.slice(2)}'`) : mentionsFlag(tpl, flag);
+    const missing = flagsInHelp(file, fn).filter((flag) => !present(flag));
+    expect(missing).toEqual([]);
+  });
+});
+
+/**
+ * bash cannot infer which flags swallow the next word, so it carries explicit
+ * `vf_*` lists. A valued flag missing from its list makes the flag's value look
+ * like the subcommand's verb — the bug 101 failure mode. zsh and fish take the
+ * value from the flag's own spec, so only bash needs guarding.
+ */
+describe('bash knows which docs flags take a value', () => {
+  it('lists every valued docs flag in vf_docs', () => {
+    const tpl = fs.readFileSync(path.join(COMPLETION_DIR, 'bash.template'), 'utf8');
+    // The scanner reads `$vf_global$vf_docs`, so a flag in either list counts.
+    const vfGlobal = tpl.match(/local vf_global="([^"]*)"/);
+    const vfDocs = tpl.match(/local vf_docs="([^"]*)"/);
+    expect(vfGlobal).toBeTruthy();
+    expect(vfDocs).toBeTruthy();
+    const scanned = new Set(`${vfGlobal[1]} ${vfDocs[1]}`.trim().split(/\s+/));
+    // A docs flag zsh declares with a `:value:` spec is by definition valued.
+    const zsh = fs.readFileSync(path.join(COMPLETION_DIR, 'zsh.template'), 'utf8');
+    const docsOpts = zsh.match(/docs_opts=\(([\s\S]*?)\n  \)/);
+    expect(docsOpts).toBeTruthy();
+    const valued = [...docsOpts[1].matchAll(/'(--[a-z0-9-]+)\[[^\]]*\]:[^']*'/g)].map((m) => m[1]);
+    expect(valued.length).toBeGreaterThan(5);
+    const missing = valued.filter((flag) => !scanned.has(flag));
+    expect(missing).toEqual([]);
+  });
+});

package/lib/completion/bash.template

@@ -70,7 +70,7 @@ _quilltap_complete() {
   # `quilltap docs --limit 5 <TAB>` used to lose the verb list.
   local vf_global=" -d --data-dir -i --instance -p --port --passphrase "
   local vf_db=" --limit --grep --character --project --about --source --chat --message --field --tail --last --from --type --out --id --count "
-  local vf_docs=" --mount --folder --type --ext --limit --max --context --top --threshold --sort --depth --max-nodes "
+  local vf_docs=" --mount --folder --type --ext --limit --max --context --top --threshold --sort --depth --max-nodes --format "
   local vf_themes=" -o --output -k --key -n --name "
   local vf_memories=" -d --data-dir --instance --passphrase --port --character --about --source --chat --project --since --until --min-importance --min-reinforced --sort --limit --in --max --context --depth --max-nodes --top --threshold "
   local vf_logs=" --stream --tail --grep "
@@ -193,6 +193,10 @@ _quilltap_complete() {
       COMPREPLY=($(compgen -W "combined error stdout stderr startup" -- "$cur"))
       return
       ;;
+    --format)
+      COMPREPLY=($(compgen -W "args json" -- "$cur"))
+      return
+      ;;
   esac
 
   # Subcommand-specific completion
@@ -227,7 +231,8 @@ _quilltap_complete() {
       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 \
         --uri --base64 --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"
+        --ignore-case -l --wait -R --recursive --sort -r --reverse --depth --max-nodes --long --semantic \
+        --format"
       if [[ "$cur" == -* ]]; then
         COMPREPLY=($(compgen -W "$docs_flags" -- "$cur"))
       elif [[ -z "$subverb" ]]; then

package/lib/completion/fish.template

@@ -184,6 +184,9 @@ complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'depth' -d 'Maximu
 complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'max-nodes' -d 'Maximum graph nodes' -x
 complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'long' -d 'Long-form output'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'semantic' -d 'Semantic search'
+complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'uri' -d 'Show canonical qtap:// URIs'
+complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'base64' -d 'Base64 transfer for binary files'
+complete -c quilltap -n '__quilltap_using_subverb docs docker-mounts' -l 'format' -d 'Output shape' -x -a 'args json'
 
 # ---------- themes verbs ----------
 complete -c quilltap -n '__quilltap_using_subcommand themes' -f -a 'list' -d 'List themes'

package/lib/completion/zsh.template

@@ -293,6 +293,7 @@ _quilltap_docs() {
     '--max-nodes[Maximum nodes in graph]:n:'
     '--long[Long-form output]'
     '--semantic[Use semantic search]'
+    '--format[For docker-mounts: output shape]:format:(args json)'
     '(-h --help)'{-h,--help}'[Show help]'
   )
 

package/package.json

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