waku-memory 0.1.0 → 0.3.0

package/dist/cli.js

@@ -13,13 +13,17 @@
 // --help, and the found/wrote/error tri-state collapsing into one boolean
 // -- are pinned by plain assertions on return values, not by mocking
 // console.log.
-import { readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { createInterface } from 'node:readline';
-import { getHarnesses, getManualHarnesses, harnessConfigExists, mergeMcpConfig, } from "./harnesses.js";
-import { handleHookEvent } from "./hook.js";
-import { KEYS_PAGE_URL, disable, enable } from "./capture.js";
+import { fileURLToPath } from 'node:url';
+import { DEFAULT_WINDOW_DAYS } from "./bootstrap.js";
+import { getHarnesses, harnessConfigExists, mergeMcpConfig, profileFor, } from "./harnesses.js";
+import { SHIM_VERSION, handleHookEvent } from "./hook.js";
+import { DISCLOSURE, KEYS_PAGE_URL, disable, enable, status, urlPair, } from "./capture.js";
+import { login } from "./login.js";
 export const DEFAULT_URL = 'https://api.waku.one/mcp';
 export const DEFAULT_NAME = 'waku';
 // The ingest base capture.ts writes into config.json -- deliberately not
@@ -67,6 +71,12 @@ export function importNote() {
 export function parseArgs(argv) {
     let name = DEFAULT_NAME;
     let url = DEFAULT_URL;
+    let since;
+    let all = false;
+    let noBootstrap = false;
+    let harness;
+    let login = false;
+    let key;
     const positional = [];
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -76,6 +86,31 @@ export function parseArgs(argv) {
         else if (arg === '--url' && i + 1 < argv.length) {
             url = argv[++i];
         }
+        else if (arg === '--since' && i + 1 < argv.length) {
+            since = argv[++i];
+        }
+        else if (arg === '--harness' && i + 1 < argv.length) {
+            harness = argv[++i];
+        }
+        else if (arg === '--all') {
+            all = true;
+        }
+        else if (arg === '--no-bootstrap') {
+            noBootstrap = true;
+        }
+        else if (arg === '--login') {
+            login = true;
+        }
+        else if (arg === '--key') {
+            // Unlike --name/--url/--since/--harness above, a value starting with
+            // "--" is deliberately NOT consumed here -- "--key --url x" must
+            // leave --url for its own branch to see, not swallow it as the key's
+            // literal value. Left undefined (with the token itself still in argv,
+            // for dispatch()'s argv.includes('--key') check) either way: no next
+            // token at all, or the next token is itself a flag.
+            if (i + 1 < argv.length && !argv[i + 1].startsWith('--'))
+                key = argv[++i];
+        }
         else if (!arg.startsWith('--')) {
             positional.push(arg);
         }
@@ -83,21 +118,30 @@ export function parseArgs(argv) {
     // subcommand is only meaningful to the caller for "capture enable" /
     // "capture disable" -- setup and hook both ignore it, same as they always
     // ignored any positional beyond the first.
-    return { command: positional[0], subcommand: positional[1], name, url };
+    return { command: positional[0], subcommand: positional[1], name, url, since, all, noBootstrap, harness, login, key };
 }
 export function printUsage() {
+    console.log('Usage: waku-memory login [--url <ingest-base>]');
+    console.log('');
+    console.log('  Signs in through the browser and mints an API key, without you ever seeing');
+    console.log('  it -- the same flow "capture enable" offers as its first question, run on');
+    console.log('  its own. Shows the disclosure first; prints "Signed in as <email>" on');
+    console.log(`  success, and stores the key in ~/.waku-memory/config.json.`);
+    console.log('');
     console.log('Usage: npx waku-memory setup [--name <name>] [--url <url>]');
     console.log('');
     console.log(`  --name  key to add under mcpServers (default: "${DEFAULT_NAME}")`);
     console.log(`  --url   server URL to write (default: ${DEFAULT_URL})`);
     console.log('');
-    console.log('Usage: waku-memory hook');
+    console.log('Usage: waku-memory hook [--harness <claude_code|codex>]');
+    console.log('');
+    console.log('  Reads one hook event as JSON on stdin and reports it to the server named');
+    console.log('  in ~/.waku-memory/config.json. Invoked by the harness itself (see');
+    console.log('  "capture enable") -- not meant to be run by hand.');
     console.log('');
-    console.log('  Reads one Claude Code hook event as JSON on stdin and reports it to');
-    console.log('  the server named in ~/.waku-memory/config.json. Invoked by Claude Code');
-    console.log('  itself (see "capture enable") -- not meant to be run by hand.');
+    console.log('  --harness  which harness sent the event (default: "claude_code")');
     console.log('');
-    console.log('Usage: waku-memory capture enable [--url <ingest-base>]');
+    console.log('Usage: waku-memory capture enable [--url <ingest-base>] [--since <N>d] [--all] [--no-bootstrap] [--login] [--key <key>]');
     console.log('');
     console.log('  Turns on automatic capture: every turn of your Claude Code sessions is');
     console.log('  sent to our server and on to Anthropic for extraction. Shows that');
@@ -105,10 +149,42 @@ export function printUsage() {
     console.log(`  asks for an API key (mint one at ${KEYS_PAGE_URL})`);
     console.log('  and installs the hook into ~/.claude/settings.json.');
     console.log('');
+    console.log('  A third question then offers to import the memory and history Claude');
+    console.log('  Code already keeps on this machine -- its own memory files and session');
+    console.log('  transcripts -- asked only when it finds anything to offer.');
+    console.log('');
+    console.log(`  --since <N>d    only scan transcripts from the last N days (default: ${DEFAULT_WINDOW_DAYS}d)`);
+    console.log('  --all           scan full history instead, ignoring --since');
+    console.log('  --no-bootstrap  skip the scan and the third question entirely');
+    console.log('  --login         sign in in the browser without asking');
+    console.log('  --key <key>     use this key without asking');
+    console.log('');
     console.log('Usage: waku-memory capture disable');
     console.log('');
     console.log('  Removes exactly the hook entries "capture enable" added. Your saved key');
     console.log('  is left in place -- revoke it on the keys page if you want it gone too.');
+    console.log('');
+    console.log('Usage: waku-memory capture status');
+    console.log('');
+    console.log('  Prints whether capture is installed for Claude Code and for Codex, and');
+    console.log('  whether a key is saved. Reads only -- never writes.');
+}
+// The default third question: on, with the full DEFAULT_WINDOW_DAYS window
+// (spec 011 §8/§9, task 14). Used both as dispatch()'s no-flags-given result
+// and, for "capture disable", unconditionally -- disable() never reads
+// deps.bootstrap (see its own comment), so there is nothing to gain and a
+// real footgun to avoid in parsing --since/--all/--no-bootstrap for an
+// action that would silently ignore them.
+const DEFAULT_BOOTSTRAP = { windowDays: DEFAULT_WINDOW_DAYS, enabled: true };
+// Accepts a bare integer ("90") or an integer with a trailing "d" ("90d") --
+// the brief's two named shapes, spec 011 §9. Anything else (empty, signed,
+// fractional, trailing garbage after the "d") is null, which dispatch()
+// turns into a 'bad-flag' rather than a silent fallback to the default: a
+// person who typed --since clearly meant to change the window, so getting
+// no error and the default anyway would be the more confusing wrong answer.
+export function parseSinceDays(raw) {
+    const match = /^(\d+)d?$/.exec(raw);
+    return match ? Number(match[1]) : null;
 }
 export function dispatch(argv) {
     // Checked ahead of parseArgs deliberately: --help/-h are flags, so
@@ -118,21 +194,111 @@ export function dispatch(argv) {
     // existed to pin it. See cli.test.mjs's dispatch block.
     if (argv.includes('--help') || argv.includes('-h'))
         return { kind: 'help' };
-    const { command, subcommand, name, url } = parseArgs(argv);
+    const { command, subcommand, name, url, since, all, noBootstrap, harness, login: loginFlag, key } = parseArgs(argv);
     if (command === undefined)
         return { kind: 'no-command' };
-    if (command === 'hook')
-        return { kind: 'hook' };
+    if (command === 'login') {
+        // Same urlPair() rule "capture enable" uses -- see its own comment
+        // below: whatever shape --url was typed in, the ingest base is what
+        // realLoginDeps(d.url) (run()) and login.ts's own apiBase param need,
+        // never the "/mcp"-suffixed mcpUrl.
+        return { kind: 'login', url: urlPair(url).ingestUrl };
+    }
+    if (command === 'hook') {
+        // --harness with no value: parseArgs only consumes it when a next token
+        // exists, so a trailing "--harness" leaves `harness` undefined the same
+        // way a trailing "--since" does -- but unlike --since (which falls back
+        // to a default), a bare --harness is treated the same as an unknown id,
+        // per the brief: both are the caller trying to say something this shim
+        // does not understand.
+        if (argv.includes('--harness') && harness === undefined) {
+            return {
+                kind: 'bad-flag',
+                message: 'waku-memory hook: --harness requires a value (e.g. "codex") -- got none.',
+            };
+        }
+        const harnessId = harness ?? 'claude_code';
+        if (!profileFor(harnessId)) {
+            return {
+                kind: 'bad-flag',
+                message: `waku-memory hook: unknown harness "${harnessId}" -- expected one of: claude_code, codex.`,
+            };
+        }
+        return { kind: 'hook', harness: harnessId };
+    }
     if (command === 'capture') {
-        if (subcommand !== 'enable' && subcommand !== 'disable')
+        if (subcommand !== 'enable' && subcommand !== 'disable' && subcommand !== 'status') {
             return { kind: 'unknown', command: 'capture' };
-        // parseArgs's `url` defaults to DEFAULT_URL (setup's "/mcp" endpoint)
-        // whenever --url is absent -- the wrong default here. Checking argv
-        // directly for the flag, rather than trusting that default, is the
-        // cheapest way to tell "the user passed --url" apart from "parseArgs's
-        // unrelated default happened to apply" without giving parseArgs a
-        // second, command-dependent default of its own.
-        return { kind: 'capture', action: subcommand, url: argv.includes('--url') ? url : DEFAULT_INGEST_URL };
+        }
+        if (subcommand === 'status')
+            return { kind: 'capture', action: 'status' };
+        // parseArgs's `url` already defaults to DEFAULT_URL (the "/mcp" literal)
+        // whenever --url is absent, so no argv.includes('--url') check is needed
+        // here any more (fix round 1 had one, to avoid trusting parseArgs's
+        // setup-shaped default -- round 2 replaces the whole thing with
+        // urlPair(), which produces the right pair from DEFAULT_URL exactly the
+        // same way it does from any --url a person types).
+        //
+        // Fix round 2 (re-review finding #1, spec 012 §4.2): urlPair() (capture.ts)
+        // is the one place that decides "given this one URL, what is the ingest
+        // base and what is the MCP endpoint" -- round 1's own rule (strip a
+        // trailing "/mcp" from mcpUrl to get ingestUrl) only worked when the
+        // input was already MCP-shaped; an ingest-shaped --url (no "/mcp" to
+        // strip, exactly the shape cli.ts's own usage text documents:
+        // "capture enable [--url <ingest-base>]") left mcpUrl === ingestUrl,
+        // reproducing the original defect. urlPair always derives the ingest
+        // base first and always appends "/mcp" to build mcpUrl, so every shape
+        // (bare, trailing slash, "/mcp"-suffixed) converges on the same pair.
+        const { ingestUrl, mcpUrl } = urlPair(url);
+        if (subcommand === 'disable') {
+            return { kind: 'capture', action: 'disable', url: ingestUrl, mcpUrl, bootstrap: DEFAULT_BOOTSTRAP };
+        }
+        // --since is validated unconditionally (even alongside --all) so a typo
+        // is never silently swallowed by an --all that happened to be present
+        // too; --all is then applied on top, since "scan everything" is the
+        // least surprising way to read the two stacked together (untested by
+        // the brief -- there is no one obviously-right answer here, but this at
+        // least never hides a bad --since value).
+        let windowDays = DEFAULT_WINDOW_DAYS;
+        if (since !== undefined) {
+            const parsed = parseSinceDays(since);
+            if (parsed === null) {
+                return {
+                    kind: 'bad-flag',
+                    message: `waku-memory capture enable: invalid --since value "${since}" -- expected a number of days, e.g. "90d" or "90".`,
+                };
+            }
+            windowDays = parsed;
+        }
+        if (all)
+            windowDays = null;
+        // --login / --key <key> (task 13, spec 012 §7): the credential decision
+        // capture.ts's enable() now takes as its own parameter -- see
+        // Credential's own comment (capture.ts) for why it lives there and not
+        // on CaptureDeps. Both bad-flag checks run unconditionally, the same
+        // way --since's does above, so a scripted caller gets a loud, specific
+        // error instead of the question silently being asked anyway.
+        if (loginFlag && key !== undefined) {
+            return {
+                kind: 'bad-flag',
+                message: 'waku-memory capture enable: --login and --key cannot be used together -- pick one.',
+            };
+        }
+        if (argv.includes('--key') && key === undefined) {
+            return {
+                kind: 'bad-flag',
+                message: 'waku-memory capture enable: --key requires a value -- got none.',
+            };
+        }
+        const credential = key !== undefined ? { kind: 'key', key } : loginFlag ? { kind: 'login' } : { kind: 'ask' };
+        return {
+            kind: 'capture',
+            action: 'enable',
+            url: ingestUrl,
+            mcpUrl,
+            bootstrap: { windowDays, enabled: !noBootstrap },
+            credential,
+        };
     }
     if (command !== 'setup')
         return { kind: 'unknown', command };
@@ -146,12 +312,22 @@ export function dispatch(argv) {
 // a single byte back; a crash, a kill, or a full disk in that window
 // leaves a real, in-use config -- ~78 KB and ~80 keys, by measurement --
 // truncated or corrupted.
-export const atomicWriteJson = (configPath, data) => {
-    const dir = dirname(configPath);
-    const tmpPath = join(dir, `.${basename(configPath)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`);
+//
+// Shared by every writer below it (task 10, spec 012 §4.6): atomicWriteJson
+// (settings.json, config files), writeJsonFile (Codex's hooks.json and the
+// personal marketplace file) and writeCodexText (Codex's config.toml, whose
+// content is already a complete file, not a value to serialise). The
+// mkdirSync up front is new with those two Codex JSON writers -- neither
+// ~/.codex nor ~/.agents/plugins is guaranteed to exist yet the first time
+// capture enable runs on a Codex machine, unlike ~/.claude (whose presence
+// is what enable() already checked before writing anything under it).
+function atomicWrite(path, content) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const tmpPath = join(dir, `.${basename(path)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`);
     try {
-        writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf8');
-        renameSync(tmpPath, configPath);
+        writeFileSync(tmpPath, content, 'utf8');
+        renameSync(tmpPath, path);
     }
     catch (err) {
         try {
@@ -165,7 +341,21 @@ export const atomicWriteJson = (configPath, data) => {
         }
         throw err;
     }
-};
+}
+export const atomicWriteJson = (configPath, data) => atomicWrite(configPath, JSON.stringify(data, null, 2) + '\n');
+// capture.ts's CaptureDeps.writeJsonFile (task 10): the same atomic write as
+// atomicWriteJson above, generalised to `unknown` -- capture.ts has no more
+// opinion about CodexHooksFile vs MarketplaceFile than atomicWriteJson has
+// about McpConfig beyond JSON.stringify, which is exactly why a function
+// typed `(data: unknown) => void` is assignable wherever `WriteJson` is
+// expected (parameter types are contravariant) and the reverse is not worth
+// forcing through a cast.
+export const writeJsonFile = (path, data) => atomicWrite(path, JSON.stringify(data, null, 2) + '\n');
+// capture.ts's CaptureDeps.writeText (task 10): writes `text` exactly as
+// given, no JSON.stringify and no added newline -- mergeCodexToml
+// (codex-config.ts) already returns the complete file text, trailing
+// newline included when the original file had one.
+export const writeCodexText = (path, text) => atomicWrite(path, text);
 // Adds `name` -> `url` to one harness's config file. Never throws: every
 // fallible step -- read, parse, merge, write -- is caught right here, so a
 // bad harness cannot stop the others from being tried and cannot crash the
@@ -274,7 +464,13 @@ export function summarize(results) {
         hadError: results.some((r) => r.status === 'error'),
     };
 }
-export function setup(name, url, harnesses = getHarnesses(), manualHarnesses = getManualHarnesses()) {
+export function setup(name, url, harnesses = getHarnesses(), 
+// R20 (final review, spec 012): the real default, injected the same way
+// realCaptureDeps below builds it -- so cli.test.mjs can point this at a
+// temp path instead of the machine's actual ~/.codex/config.toml, the
+// same reason every other real path in this file is a parameter with a
+// real default rather than a bare homedir() call inline.
+codexConfigPath = join(homedir(), '.codex', 'config.toml')) {
     const results = runSetup(harnesses, name, url);
     for (const r of results) {
         if (r.status === 'error')
@@ -282,42 +478,40 @@ export function setup(name, url, harnesses = getHarnesses(), manualHarnesses = g
         else
             console.log(r.message);
     }
-    // Only the ones actually on this machine. A manual harness is reported
-    // as found -- it just cannot be written to -- so it counts toward
-    // "did we find anything at all" below, and specifically toward whether
-    // the import step is worth mentioning: someone who follows the
-    // instructions has a working server, same as an auto-configured one.
-    const manualPresent = manualHarnesses.filter(harnessConfigExists);
-    for (const h of manualPresent) {
-        console.log('');
-        console.log(h.note(name, url));
-    }
     console.log('');
-    const { foundAny: autoFound, wroteAny, hadError } = summarize(results);
-    const foundAny = autoFound || manualPresent.length > 0;
+    // Task 14 (spec 012 §9): setup() no longer has a manual-harness list to
+    // consult here -- Codex was its only member, and Codex now has a real,
+    // automatic route of its own ("capture enable", task 10), so there is
+    // nothing left this function can detect but not write. getHarnesses()
+    // still does not carry Codex (harnesses.ts's own comment has the fuller
+    // account), so a Codex-only machine still falls through to the plain "no
+    // supported harness config was found" branch below -- R20 below is what
+    // stops that from being a flatly false thing to print on such a machine.
+    const { foundAny, wroteAny, hadError } = summarize(results);
     if (wroteAny) {
         console.log('Next: open the harness and use a waku tool. The first call will get a 401, ' +
             'the harness will open your browser to sign in, and the call will then go ' +
             'through on retry -- that browser popup is expected, not an error.');
     }
-    else if (autoFound && !hadError) {
+    else if (foundAny && !hadError) {
         console.log('Already configured correctly -- nothing to change.');
     }
-    else if (autoFound && hadError) {
+    else if (foundAny && hadError) {
         console.log('Could not update every harness found -- see the messages above.');
     }
-    else if (manualPresent.length > 0) {
-        // Deliberately its own branch rather than falling into "already
-        // configured": a manual harness being *present* is not the same as it
-        // being *configured*, and telling someone nothing needs changing when
-        // they still have a TOML block to paste is the more expensive of the
-        // two possible wrong messages.
-        console.log('Nothing was written: the only harness found here is one this shim does not ' +
-            'configure automatically -- follow the instructions above to finish.');
-    }
     else {
         console.log('Nothing was added: no supported harness config was found on this machine.');
     }
+    // R20 (final review, spec 012): the regression this whole-branch review
+    // caught -- "no supported harness config was found" is false on a machine
+    // that has ~/.codex/config.toml. setup() still writes nothing for Codex
+    // (getHarnesses() does not carry it, above), so this is advice, not a
+    // result: it fires independently of the found/wrote/error branch above,
+    // including alongside a real Claude Code result on a machine with both.
+    if (existsSync(codexConfigPath)) {
+        console.log('');
+        console.log('Codex was found. Run "npx waku-memory capture enable" to configure it.');
+    }
     // Printed whenever a usable server exists on this machine -- which
     // includes the already-configured re-run, since a configured server with
     // nothing imported is exactly the state a re-runner is most likely to be
@@ -352,7 +546,7 @@ function readStdin() {
 // actual config dir, the real global fetch). Deliberately never awaited by
 // run() below -- see that call site's comment for why that is safe here
 // specifically, which is not the same as it being safe in general.
-async function runHookCommand() {
+async function runHookCommand(harness) {
     let raw;
     try {
         raw = await readStdin();
@@ -366,13 +560,99 @@ async function runHookCommand() {
         event = JSON.parse(raw);
     }
     catch (err) {
-        // Malformed input is a no-op, not a crash: some future Claude Code
-        // hook event this shim was not written against, or a hand test of
-        // `waku-memory hook` with no stdin piped in at all.
+        // Malformed input is a no-op, not a crash: some future hook event this
+        // shim was not written against, or a hand test of `waku-memory hook`
+        // with no stdin piped in at all.
         console.error(`waku-memory hook: stdin was not valid JSON -- ${errorMessage(err)}.`);
         return;
     }
-    await handleHookEvent(event, { configDir: join(homedir(), '.waku-memory'), fetchImpl: fetch });
+    await handleHookEvent(event, { configDir: join(homedir(), '.waku-memory'), fetchImpl: fetch, harness });
+}
+// The platform opener login.ts's LoginDeps.openBrowser needs (spec 012 §7):
+// spawned detached and unref'd so it never blocks -- or waits on -- this
+// process, and never throws: a failed spawn (no browser installed, no
+// `xdg-open` on a headless machine) is fine, because the authorize URL is
+// always printed first (login.ts's own login(), right before this runs).
+// The 'error' listener exists for the same reason as the try/catch: a spawn
+// failure can surface asynchronously (an ENOENT for a missing xdg-open,
+// say) rather than as a synchronous throw, and an unhandled 'error' event
+// on a ChildProcess crashes the process if nothing is listening for it.
+// The argv/options openBrowser (below) hands to child_process.spawn, kept
+// as a pure function of (platform, url) so a unit test can assert the exact
+// shape without spawning a real process or opening a real browser (fix
+// round 1, finding 1). The previous win32 shape --
+// `spawn('cmd', ['/c', 'start', '""', url])`, no shell, no verbatim-argument
+// flag -- was Critical-broken for any real authorize URL: Node's default
+// Windows argv quoting only wraps an argument in quotes when it contains
+// whitespace, so an `&`-separated OAuth URL passed through untouched, and
+// cmd.exe then read each `&` as its own command separator, truncating the
+// URL at the first `&` and failing on every parameter after it as an
+// unrecognized command.
+//
+// Chosen fix: shape (a) from the controller's ruling, not (b)
+// (`rundll32 url.dll,FileProtocolHandler`) -- `cmd /c start` is the
+// documented way to hand a URL to the OS's own default-handler resolution
+// (same as double-clicking a link), while rundll32's undocumented internal
+// entry point is a narrower target to keep behaving identically across
+// Windows versions.
+// `windowsVerbatimArguments: true` stops Node from re-quoting each argv
+// entry (the exact thing that let `""` and the URL arrive at cmd.exe
+// unquoted in the first place); wrapping the URL in its own literal double
+// quotes (`` `"${url}"` ``) is then what makes cmd.exe treat everything
+// between them -- `&` included -- as one argument instead of a command
+// separator. The leading `'""'` argument is unrelated to the URL: it is
+// `start`'s own window-title argument, required so `start` does not
+// mistake a quoted first argument (the URL, if it came first) for a title
+// instead of the command to run. Reproduced directly from Bash on this
+// machine, adapted from the reviewer's own repro (see cli.test.mjs's
+// nearby test and this task's report for the transcript): `cmd /c echo ""
+// "https://x/a?b=1&c=2"` under `windowsVerbatimArguments: true` prints the
+// URL whole, `&` and all -- `echo` standing in for `start` the same way the
+// reviewer's own reproduction used it.
+//
+// darwin/linux are untouched: `open`/`xdg-open` never go through a shell,
+// so Node's own (correct, non-Windows) argv handling was never the problem
+// there.
+export function buildBrowserOpener(platform, url) {
+    if (platform === 'win32') {
+        return {
+            command: 'cmd',
+            args: ['/c', 'start', '""', `"${url}"`],
+            options: { detached: true, stdio: 'ignore', windowsVerbatimArguments: true },
+        };
+    }
+    if (platform === 'darwin') {
+        return { command: 'open', args: [url], options: { detached: true, stdio: 'ignore' } };
+    }
+    return { command: 'xdg-open', args: [url], options: { detached: true, stdio: 'ignore' } };
+}
+function openBrowser(url) {
+    try {
+        const { command, args, options } = buildBrowserOpener(process.platform, url);
+        const child = spawn(command, args, options);
+        child.on('error', () => {
+            // Never throws -- the URL was already printed (login.ts's login()).
+        });
+        child.unref();
+    }
+    catch {
+        // Same reasoning as the 'error' listener above, for the rarer case
+        // where spawn() itself throws synchronously.
+    }
+}
+// login.ts's LoginDeps, built the one way this shim ever builds it -- both
+// `waku-memory login` (run()'s own 'login' case) and "capture enable"'s
+// login Credential (realCaptureDeps below) call this with the same
+// ingest-base `apiBase` dispatch() already computed.
+function realLoginDeps(apiBase) {
+    return {
+        apiBase,
+        configDir: join(homedir(), '.waku-memory'),
+        fetchImpl: fetch,
+        openBrowser,
+        stdout: (text) => console.log(text),
+        version: SHIM_VERSION,
+    };
 }
 // The real deps enable()/disable() run against outside a test: real paths
 // under the user's home directory, an injected prompt (built by the two
@@ -383,14 +663,62 @@ async function runHookCommand() {
 // JSON-shaped types meet. Safe in practice: atomicWriteJson only ever does
 // JSON.stringify(data) -- it has no opinion about McpConfig vs
 // ClaudeSettings beyond the type checker's.
-function realCaptureDeps(prompt) {
+//
+// hookSourceDir is this module's own directory, not a fixed constant: as
+// published, cli.ts compiles to dist/cli.js and runs from there, so
+// import.meta.url resolves to dist -- exactly the directory installHookCopy
+// needs (spec 011 §6, task 11). verifyHook actually runs the entry once
+// with a throwaway event before enable() trusts it, so a corrupted copy or
+// a Node too old for it is caught before settings.json is ever touched.
+//
+// fetchImpl is task 13's addition (spec 011 §8): the real global fetch, for
+// runBootstrap's own network calls. bootstrap is now a parameter rather than
+// a hardcoded default (task 14): dispatch() has already turned
+// --since/--all/--no-bootstrap (or their absence) into this same shape, so
+// this function's only job is to place it on the deps bag unchanged, the
+// same way `prompt` already arrives built by its own call site below.
+function realCaptureDeps(prompt, bootstrap, 
+// Fix round 1 (spec 012 §4.2): the MCP-shaped url (dispatch()'s mcpUrl,
+// computed from --url BEFORE it was stripped to the ingest base) --
+// passed alongside bootstrap the same way disable()'s and status()'s call
+// sites already pass a bootstrap they never use, so every caller builds
+// deps the same way regardless of whether its own action reads the field.
+mcpUrl, 
+// Task 13's addition (spec 012 §7): the ingest base (dispatch()'s
+// ingestUrl) realLoginDeps needs for deps.login below -- every call site
+// already has this value (it is enable()'s own `url` parameter, or
+// disable's/status's respective stand-ins), so, like bootstrap and mcpUrl
+// above, it is threaded through unconditionally rather than only for the
+// one action that can actually reach the credential question.
+ingestUrl) {
     const claudeDir = join(homedir(), '.claude');
+    const codexDir = join(homedir(), '.codex');
     return {
         claudeDir,
         settingsPath: join(claudeDir, 'settings.json'),
         configDir: join(homedir(), '.waku-memory'),
+        hookSourceDir: dirname(fileURLToPath(import.meta.url)),
+        version: SHIM_VERSION,
+        execPath: process.execPath,
+        verifyHook: (run) => spawnSync(run.command, run.args ?? [], { input: '{"hook_event_name":"Nope"}\n', timeout: 10_000 }).status === 0,
         prompt,
         writeSettingsJson: (path, data) => atomicWriteJson(path, data),
+        fetchImpl: fetch,
+        bootstrap,
+        // Codex (task 10, spec 012 §4.6): detected the same way claudeDir is --
+        // existence of the path is the evidence. codexPluginsCacheDir matches
+        // codexPluginPresent's own comment (codex-config.ts) on where Codex
+        // caches an installed plugin; marketplacePath is the personal
+        // marketplace every machine gets one of, regardless of which harnesses
+        // it has (~/.agents is not itself Codex-specific).
+        codexConfigPath: join(codexDir, 'config.toml'),
+        codexHooksPath: join(codexDir, 'hooks.json'),
+        codexPluginsCacheDir: join(codexDir, 'plugins', 'cache'),
+        marketplacePath: join(homedir(), '.agents', 'plugins', 'marketplace.json'),
+        mcpUrl,
+        writeText: writeCodexText,
+        writeJsonFile,
+        login: () => login(realLoginDeps(ingestUrl)),
     };
 }
 // Not awaited by run() below, for the same structural reason runHookCommand
@@ -401,14 +729,21 @@ function realCaptureDeps(prompt) {
 // safely touch) is the one outcome that should make a scripted caller
 // notice. 'declined' and the disable no-op are both a normal, successful
 // run that did exactly what was asked -- nothing.
-async function runCaptureCommand(action, url) {
+async function runCaptureCommand(action, url, mcpUrl, bootstrap, 
+// undefined for 'disable' (Dispatch's disable variant carries no
+// credential at all -- see its own comment); always one of the three
+// Credential kinds for 'enable', built by dispatch()'s capture-enable
+// branch from --login/--key or their absence.
+credential) {
     if (action === 'disable') {
         // disable() never prompts (see its own comment) -- no readline interface
         // is created at all, and this stub is a fail-loud guard against that
-        // ever silently stopping being true.
+        // ever silently stopping being true. bootstrap is dispatch()'s
+        // DEFAULT_BOOTSTRAP here regardless of what was on argv -- disable()
+        // itself never reads deps.bootstrap either.
         const deps = realCaptureDeps(() => {
             throw new Error('waku-memory capture disable: unexpectedly tried to prompt.');
-        });
+        }, bootstrap, mcpUrl, url);
         const result = await disable(deps);
         if (result === 'refused')
             process.exitCode = 1;
@@ -446,7 +781,7 @@ async function runCaptureCommand(action, url) {
             const { value, done } = await lines.next();
             return done ? '' : value; // stdin closed before an answer arrived -- treated as "declined"
         };
-        const result = await enable(url, realCaptureDeps(prompt));
+        const result = await enable(url, realCaptureDeps(prompt, bootstrap, mcpUrl, url), credential);
         if (result === 'refused')
             process.exitCode = 1;
     }
@@ -454,6 +789,17 @@ async function runCaptureCommand(action, url) {
         rl.close();
     }
 }
+// status() never prompts, never touches deps.bootstrap, and (ruling R8,
+// fix round 1) needs no url at all -- same as disable() -- see
+// runCaptureCommand's own stub above), so the prompt stub, DEFAULT_BOOTSTRAP
+// and DEFAULT_URL here exist only to satisfy realCaptureDeps's shape, the
+// same reason disable's call site needs them.
+async function runCaptureStatusCommand() {
+    const deps = realCaptureDeps(() => {
+        throw new Error('waku-memory capture status: unexpectedly tried to prompt.');
+    }, DEFAULT_BOOTSTRAP, DEFAULT_URL, DEFAULT_INGEST_URL);
+    await status(deps);
+}
 export function run(argv) {
     const d = dispatch(argv);
     switch (d.kind) {
@@ -470,9 +816,33 @@ export function run(argv) {
             printUsage();
             process.exitCode = 1;
             return;
+        case 'bad-flag':
+            console.error(d.message);
+            printUsage();
+            process.exitCode = 1;
+            return;
         case 'setup':
             setup(d.name, d.url);
             return;
+        case 'login':
+            // Ruling R15: the disclosure (and a blank line), no y/n gate -- unlike
+            // "capture enable", signing in on its own asks nothing about consent
+            // to *capture*, only about signing in, so there is no gate to hold it
+            // behind. Exit-code mapping mirrors "capture enable"'s own (see
+            // runCaptureCommand's own comment): 0 only on the fully successful
+            // 'signed-in', 1 for 'timeout' or 'refused' -- the one outcome
+            // distinction worth a nonzero exit for a scripted caller.
+            console.log(DISCLOSURE);
+            console.log('');
+            void login(realLoginDeps(d.url))
+                .then((result) => {
+                process.exitCode = result === 'signed-in' ? 0 : 1;
+            })
+                .catch((err) => {
+                console.error(`waku-memory login: unexpected failure -- ${errorMessage(err)}.`);
+                process.exitCode = 1;
+            });
+            return;
         case 'hook':
             // Exits 0 always, per the brief: set up front, not left to whatever
             // the default happens to be, and never touched again on any failure
@@ -483,12 +853,19 @@ export function run(argv) {
             // read and the JSON.parse that happen before it. The .catch() here is
             // a second backstop, not the mechanism this relies on.
             process.exitCode = 0;
-            void runHookCommand().catch((err) => {
+            void runHookCommand(d.harness).catch((err) => {
                 console.error(`waku-memory hook: unexpected failure -- ${errorMessage(err)}.`);
             });
             return;
         case 'capture':
-            void runCaptureCommand(d.action, d.url).catch((err) => {
+            if (d.action === 'status') {
+                void runCaptureStatusCommand().catch((err) => {
+                    console.error(`waku-memory capture: unexpected failure -- ${errorMessage(err)}.`);
+                    process.exitCode = 1;
+                });
+                return;
+            }
+            void runCaptureCommand(d.action, d.url, d.mcpUrl, d.bootstrap, d.action === 'enable' ? d.credential : undefined).catch((err) => {
                 console.error(`waku-memory capture: unexpected failure -- ${errorMessage(err)}.`);
                 process.exitCode = 1;
             });