quilltap 4.9.0-dev.121 → 4.9.0-dev.133

package/README.md

@@ -99,8 +99,11 @@ quilltap instances list                                  # Registered instances
 quilltap instances default Friday                        # Make it the fall-through for flag-free runs
 quilltap instances rename Friday Weekday                 # Rename, preserving the stored passphrase
 quilltap instances remove Friday                         # Unregister
+quilltap instances restore-key Friday                    # Rebuild a lost or passphrase-locked .dbkey
 ```
 
+If an instance's `quilltap.dbkey` goes missing — or its passphrase does — `instances restore-key` rebuilds it. The file only *wraps* the pepper; the pepper itself is the database key, so an operator who kept the one printed at first-run setup can get back in. The pepper is read from `ENCRYPTION_MASTER_PEPPER` or prompted for hidden, never passed as a flag, and it is proved against the encrypted databases on disk before anything is written. Run it with the server down — the command refuses while the instance lock is held. Flags: `--passphrase <pass>` / `--no-passphrase` (the new wrapping), `-d, --data-dir <path>`, `--force`, `-y, --yes`.
+
 Every subcommand then accepts `--instance <name>` in place of `--data-dir`. The registry lives at `<app-support>/Quilltap/instances.json` (mode 0600; e.g. `~/Library/Application Support/Quilltap/instances.json` on macOS). **Resolution precedence:** `--data-dir` > `--instance` > registered default > `QUILLTAP_DATA_DIR` > the OS platform default. Pass the **instance root** (e.g. `~/iCloud/Quilltap/Friday`), not its `data/` subdirectory.
 
 ## Database Tool

package/lib/__tests__/instances-default-json.test.js

@@ -0,0 +1,104 @@
+/**
+ * Bug 120 — `quilltap instances default --json`.
+ *
+ * `cmdDefault` takes BOTH an options object and a positional instance name, so
+ * the dispatcher has to strip `--json` as well as read it. Reading without
+ * stripping leaves `args.length === 1`, which sends control past the report
+ * branch and into the set branch, where the flag becomes the instance name to
+ * set. `cmdList`, whose shape this arm was copied from, has no positionals and
+ * so needs no filter — which is exactly why the missing step looked complete.
+ *
+ * Driven through the real binary so the arg parsing under test is the arg
+ * parsing that ships. HOME is redirected per-test, so the registry these cases
+ * read and write is a throwaway one and never the developer's own.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const BIN = path.join(__dirname, '..', '..', 'bin', 'quilltap.js');
+
+let home;
+
+function run(...args) {
+  return execFileSync(process.execPath, [BIN, 'instances', ...args], {
+    encoding: 'utf8',
+    input: '',
+    env: { ...process.env, HOME: home, USERPROFILE: home, APPDATA: path.join(home, 'AppData') },
+  }).trim();
+}
+
+/**
+ * `instances add` always prompts for a passphrase, so register through stdin.
+ * The directory is created first — otherwise a second "save anyway?" prompt
+ * consumes the answer meant for the passphrase question.
+ */
+function addInstance(name) {
+  const dir = path.join(home, name.toLowerCase());
+  fs.mkdirSync(dir, { recursive: true });
+  execFileSync(process.execPath, [BIN, 'instances', 'add', name, dir], {
+    encoding: 'utf8',
+    input: 'n\n',
+    env: { ...process.env, HOME: home, USERPROFILE: home, APPDATA: path.join(home, 'AppData') },
+  });
+  return dir;
+}
+
+beforeEach(() => {
+  home = fs.mkdtempSync(path.join(os.tmpdir(), 'qt-inst-'));
+});
+
+afterEach(() => {
+  fs.rmSync(home, { recursive: true, force: true });
+});
+
+describe('instances default --json', () => {
+  it('reports null on an empty registry instead of hunting for an instance named "--json"', () => {
+    const out = run('default', '--json');
+    expect(JSON.parse(out)).toEqual({ defaultInstance: null });
+    // The bug 120 failure mode, spelled out so a regression is unambiguous.
+    expect(out).not.toMatch(/Unknown instance/);
+  });
+
+  it('reports the registered default as JSON', () => {
+    addInstance('Friday');
+    run('default', 'Friday');
+    expect(JSON.parse(run('default', '--json'))).toEqual({ defaultInstance: 'Friday' });
+  });
+
+  it('leaves the set path alone — a name still sets, with or without the flag', () => {
+    addInstance('Friday');
+    expect(run('default', 'Friday')).toMatch(/Set default instance to "Friday"/);
+    expect(run('default')).toBe('Friday');
+    expect(run('default', 'Friday', '--json')).toMatch(/Set default instance to "Friday"/);
+  });
+
+  it('still prints the plain report with no flag', () => {
+    expect(run('default')).toBe('(none)');
+  });
+});
+
+describe('instances list --json', () => {
+  it('emits the registry as an array', () => {
+    expect(JSON.parse(run('list', '--json'))).toEqual([]);
+    addInstance('Friday');
+    const [entry] = JSON.parse(run('list', '--json'));
+    expect(entry).toMatchObject({ name: 'Friday', hasPassphrase: false });
+  });
+});
+
+describe('the flags the help text advertises actually parse', () => {
+  // The completion-coverage suite checks help -> templates. This checks the
+  // other direction for the two flags bug 120 was about: that a flag the help
+  // names is one the parser honours.
+  it('names --json on the list verb in `instances --help`', () => {
+    const help = execFileSync(process.execPath, [BIN, 'instances', '--help'], { encoding: 'utf8' });
+    expect(help).toMatch(/^\s*list \[--json\]/m);
+  });
+});

package/lib/completion/fish.template

@@ -234,6 +234,9 @@ for verb in show remove rm delete set-passphrase passphrase default rename resto
 end
 
 complete -c quilltap -n '__quilltap_using_subcommand instances' -l 'names-only' -d 'Print one name per line'
+for verb in list ls
+  complete -c quilltap -n "__quilltap_using_subverb instances $verb" -l 'json' -d 'JSON output'
+end
 complete -c quilltap -n '__quilltap_using_subverb instances default' -l 'clear' -d 'Clear default instance'
 for verb in restore-key rebuild-key
   complete -c quilltap -n "__quilltap_using_subverb instances $verb" -l 'passphrase' -d 'Passphrase for the rebuilt .dbkey'

package/lib/instances-commands.js

@@ -30,7 +30,7 @@ Quilltap Instance Registry
 Usage: quilltap instances <verb> [args]
 
 Verbs:
-  list                          List registered instances (default)
+  list [--json]                 List registered instances (default)
   show <name>                   Show one instance (passphrase status only)
   path                          Print the path to instances.json
   add <name> [<path>]           Register an instance (prompts for missing path / passphrase)
@@ -366,9 +366,15 @@ async function instancesCommand(args) {
       case 'passphrase':
         await cmdSetPassphrase(rest);
         return;
-      case 'default':
-        cmdDefault(rest);
+      case 'default': {
+        // `--json` has to be lifted out of the positionals as well as read:
+        // cmdDefault treats args[0] as the instance name to set, so leaving the
+        // flag in place made `instances default --json` try to set an instance
+        // literally named "--json" and left cmdDefault's json branch unreachable.
+        const json = rest.includes('--json');
+        cmdDefault(rest.filter((a) => a !== '--json'), { json });
         return;
+      }
       case 'rename':
         cmdRename(rest);
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quilltap",
-  "version": "4.9.0-dev.121",
+  "version": "4.9.0-dev.133",
   "description": "Self-hosted AI workspace for writers, worldbuilders, and roleplayers. Run with npx quilltap.",
   "author": {
     "name": "Charles Sebold",
@@ -39,7 +39,7 @@
     "@napi-rs/canvas": "^0.1.100",
     "better-sqlite3-multiple-ciphers": "^12.11.1",
     "node-pty": "^1.1.0",
-    "sharp": "^0.35.3",
+    "sharp": "^0.35.4",
     "tar": "^7.5.22",
     "yauzl": "^3.4.0"
   },