@etiennepasteur/jean-claude 0.1.0 → 0.2.0

package/README.md

@@ -92,23 +92,30 @@ cp ./captures/api.anthropic.com/api/claude_code/settings.GET.json \
 jean-claude run -- claude
 ```
 
-Add `-v` the first time, to see every request rather than only the ones a rule
+Claude Code keeps the terminal to itself: jean-claude's log goes to
+`~/.config/jean-claude/jean-claude.log` instead. Follow it from another terminal,
+with `-v` the first time to see every request rather than only the ones a rule
 touched:
 
+```bash
+tail -f ~/.config/jean-claude/jean-claude.log
+```
+
 ```
   GET   api.anthropic.com/api/claude_code/settings   200  → stub responses/settings.GET.json
   POST  api.anthropic.com/v1/messages                200
 ```
 
-A `→ stub` on the settings line means it worked. If you would rather keep the log
-out of Claude Code's output, run the proxy in its own terminal —
-see [Two terminals](#two-terminals-start--env).
+A `→ stub` on the settings line means it worked. See
+[Where jean-claude's own log goes](#where-jean-claudes-own-log-goes) to send it
+somewhere else, or back to the screen.
 
 ## Where everything lives
 
 ```
 ~/.config/jean-claude/          # $XDG_CONFIG_HOME/jean-claude if set
 ├── jean-claude.yaml
+├── jean-claude.log             # where `run` sends its log, see below
 ├── responses/
 ├── ca/  ca.pem  ca.key  bundle.pem
 └── session.json                # only while `start` is running
@@ -282,6 +289,11 @@ The bundle exists because `SSL_CERT_FILE` and `CURL_CA_BUNDLE` **replace** the
 trust store rather than adding to it — handing a target only our own CA would cut
 it off from every other authority.
 
+The system trust store is read through `tls.getCACertificates('system')`, so a CA
+your administrators installed machine-wide is picked up on **Windows and macOS**
+too, where the store is an OS API and not a file. jean-claude trusts the same set
+on its own outbound connections.
+
 `jean-claude run` points the child at the bundle, so **no root access and no
 system-wide trust change is needed**. If you do want the CA in the system store
 (for a GUI app, say), `jean-claude ca --install` prints the commands for you to
@@ -296,7 +308,23 @@ onto whatever it finds:
   your corporate proxy. Override with `upstream:` in the config (`auto`, `off`,
   or an explicit URL).
 - `NODE_EXTRA_CA_CERTS` → your corporate CA is trusted on outbound connections
-  _and_ folded into `bundle.pem` for the child.
+  _and_ folded into `bundle.pem` for the child. Only needed for a CA that is
+  **not** in the machine's trust store: that one is read anyway.
+
+### When jean-claude cannot verify the real server
+
+The interception can be perfect and the relay leg still fail, which shows up as
+a 502 the target never asked for:
+
+```
+  GET   api.example.com/v1/things   upstream  UNABLE_TO_GET_ISSUER_CERT_LOCALLY
+  ! jean-claude could not verify the real server's certificate. …
+```
+
+That means the authority signing the traffic — usually your network's TLS
+inspection appliance — is in neither the machine trust store nor
+`NODE_EXTRA_CA_CERTS`. Export it and point `NODE_EXTRA_CA_CERTS` at it before
+starting jean-claude.
 
 ### When a target refuses the CA
 
@@ -343,6 +371,47 @@ Known gaps worth knowing rather than fighting: Java uses its own keystore
 environment variable, and anything with pinned certificates needs
 `tlsPassthrough`.
 
+## Where jean-claude's own log goes
+
+`run` gives the terminal to the tool it spawns. A request line landing in the
+middle of a full-screen TUI — Claude Code's, for one — corrupts the display, so
+by default the log goes to a file instead, announced in the banner:
+
+```
+$ jean-claude run -- claude
+
+  proxy     http://127.0.0.1:8001
+  config    ~/.config/jean-claude/jean-claude.yaml  1 rule(s)
+  log       ~/.config/jean-claude/jean-claude.log  (tail -f to follow)
+  command   claude
+
+  … Claude Code owns the screen from here …
+
+  12 requests, 1 rule hit, 2 upstream errors  →  ~/.config/jean-claude/jean-claude.log
+```
+
+The banner is printed before the child starts, and the summary after it exits, so
+neither can clobber anything. The summary is what tells you a redirected run did
+something — errors are counted in red.
+
+Destination, first match wins:
+
+| Setting                   | Effect                                        |
+| ------------------------- | --------------------------------------------- |
+| `--log <path>`            | that file (relative to the current directory) |
+| `--log terminal`          | on screen, interleaved                        |
+| `logFile:` in the config  | that file (relative to the config file)       |
+| stdout is a terminal      | `<home>/jean-claude.log`                      |
+| anything else (pipes, CI) | on screen, unchanged                          |
+
+The file is appended to, never truncated, and each session opens with a header
+carrying the timestamp, pid and command — two concurrent runs cannot wipe each
+other. `-q/--quiet` still means "log nothing", wherever the log would have gone.
+
+`start` never redirects on its own and ignores `logFile:`: giving the log a
+terminal of its own is what it is for. Pass `--log <path>` if you want it in a
+file there too.
+
 ## Two terminals: `start` + `env`
 
 For a GUI app, a service that is already running, or simply to keep jean-claude's
@@ -382,7 +451,7 @@ jean-claude init               set up the jean-claude directory: config, stub, C
 ```
 
 Shared flags: `-c/--config`, `-p/--port`, `-r/--record`, `--home`,
-`-v/--verbose`, `-q/--quiet`, `--no-watch`.
+`--log <path|terminal>`, `-v/--verbose`, `-q/--quiet`, `--no-watch`.
 
 `init` takes `--home <dir>` and `--claude-code`.
 
@@ -396,7 +465,7 @@ one setting that needs a restart.
 
 ```bash
 npm install
-npm test           # 130 tests, including an end-to-end MITM suite
+npm test           # 155 tests, including an end-to-end MITM suite
 npm run typecheck
 npm run lint
 npm run build

package/dist/cli.mjs

@@ -10,11 +10,16 @@ import { YAMLParseError, parse } from "yaml";
 import { z } from "zod";
 import { match } from "path-to-regexp";
 import { execa } from "execa";
+import { createWriteStream } from "node:fs";
+import { stripVTControlCharacters } from "node:util";
 import { watch } from "chokidar";
 import { createHash } from "node:crypto";
 import { setTimeout } from "node:timers/promises";
 //#region src/ca/store.ts
-/** Candidate system trust stores, by distribution family. */
+/**
+* Candidate system trust stores, by distribution family. Only a fallback: see
+* `readSystemTrust` for why the OS API comes first.
+*/
 const SYSTEM_CA_BUNDLES = [
 	"/etc/ssl/certs/ca-certificates.crt",
 	"/etc/pki/tls/certs/ca-bundle.crt",
@@ -41,6 +46,37 @@ async function findSystemBundle() {
 	for (const candidate of SYSTEM_CA_BUNDLES) if (await exists(candidate)) return candidate;
 }
 /**
+* The machine's own trust store.
+*
+* `tls.getCACertificates('system')` is tried first because on Windows and macOS
+* the store is an OS API, not a file: the Unix paths above find nothing there,
+* and falling back to Node's bundled Mozilla roots silently drops every CA the
+* machine was given by its administrators. That is exactly the CA an
+* intercepting corporate proxy signs with, so losing it makes the relay leg fail
+* with `unable to get local issuer certificate` while the client side keeps
+* working - a failure that looks like a jean-claude bug and is not.
+*
+* The API landed in Node 22.15 / 24.0, hence the feature detection.
+*/
+async function readSystemTrust() {
+	if (typeof tls.getCACertificates === "function") try {
+		const certs = tls.getCACertificates("system");
+		if (certs.length > 0) return {
+			certs: certs.join("\n"),
+			source: `the OS trust store (${certs.length} certs)`
+		};
+	} catch {}
+	const bundlePath = await findSystemBundle();
+	if (bundlePath !== void 0) return {
+		certs: await readFile(bundlePath, "utf8"),
+		source: bundlePath
+	};
+	return {
+		certs: tls.rootCertificates.join("\n"),
+		source: "Node's built-in roots"
+	};
+}
+/**
 * Make sure the CA exists, and (re)generate the trust bundle.
 *
 * The bundle is rewritten on every call: the system store or the corporate CA
@@ -62,29 +98,34 @@ async function ensureCa({ dir, inheritedCa }) {
 		await writeFile(paths.keyPath, key, { mode: 384 });
 	}
 	const ourCert = await readFile(paths.certPath, "utf8");
-	const systemBundle = await findSystemBundle();
-	const systemCerts = systemBundle ? await readFile(systemBundle, "utf8") : tls.rootCertificates.join("\n");
+	const system = await readSystemTrust();
 	const inheritedCerts = inheritedCa && await exists(inheritedCa) ? await readFile(inheritedCa, "utf8") : "";
 	const resolvedInherited = inheritedCerts === "" ? void 0 : inheritedCa;
+	const inheritedSection = resolvedInherited ? [`# CA inherited from NODE_EXTRA_CA_CERTS (${resolvedInherited})`, inheritedCerts.trim()] : [];
+	const systemSection = [`# System trust store (${system.source})`, system.certs.trim()];
 	const bundle = [
 		"# Generated by jean-claude - do not edit by hand.",
 		"# jean-claude CA",
 		ourCert.trim(),
-		...resolvedInherited ? [`# CA inherited from NODE_EXTRA_CA_CERTS (${resolvedInherited})`, inheritedCerts.trim()] : [],
-		`# System trust store (${systemBundle ?? "Node's built-in roots"})`,
-		systemCerts.trim(),
+		...inheritedSection,
+		...systemSection,
 		""
 	].join("\n");
 	await writeFile(paths.bundlePath, bundle, { mode: 420 });
 	return {
 		...paths,
 		created,
-		systemBundle,
-		inheritedCa: resolvedInherited
+		systemTrust: system.source,
+		inheritedCa: resolvedInherited,
+		outboundTrust: [
+			...inheritedSection,
+			...systemSection,
+			""
+		].join("\n")
 	};
 }
 /**
-* Commands to install the CA into the system trust store, per distribution family.
+* Commands to install the CA into the system trust store, per platform.
 * Returned as text on purpose: jean-claude never runs `sudo` on its own.
 */
 function systemTrustInstructions(certPath) {
@@ -97,7 +138,14 @@ function systemTrustInstructions(certPath) {
 		`sudo cp ${certPath} /etc/pki/ca-trust/source/anchors/jean-claude.crt`,
 		"sudo update-ca-trust extract",
 		"",
-		"# To uninstall: delete the copied file, then re-run the matching update command."
+		"# Windows, current user only (PowerShell, no elevation needed)",
+		`certutil -user -addstore Root "${certPath}"`,
+		"",
+		"# Windows, machine-wide (PowerShell as administrator)",
+		`Import-Certificate -FilePath "${certPath}" -CertStoreLocation Cert:\\LocalMachine\\Root`,
+		"",
+		"# To uninstall: delete the copied file and re-run the matching update command,",
+		"# or on Windows remove the entry from the Root store (certmgr.msc)."
 	];
 }
 //#endregion
@@ -111,6 +159,7 @@ function systemTrustInstructions(certPath) {
 * and one path to remember beats XDG purity here. `--home` relocates the lot.
 *
 *   <home>/jean-claude.yaml
+*   <home>/jean-claude.log
 *   <home>/responses/
 *   <home>/ca/{ca.pem,ca.key,bundle.pem}
 *   <home>/session.json
@@ -126,6 +175,10 @@ function caDirIn(home) {
 function responsesDirIn(home) {
 	return path.join(home, "responses");
 }
+/** Where `run` sends its own log when a spawned tool owns the terminal. */
+function logFileIn(home) {
+	return path.join(home, "jean-claude.log");
+}
 //#endregion
 //#region src/env/upstream.ts
 function firstDefined(env, names) {
@@ -187,7 +240,7 @@ async function caCommand(options) {
 	console.log(`  ${pc.dim("cert    ")}${ca.certPath}${ca.created ? pc.dim("  (just generated)") : ""}`);
 	console.log(`  ${pc.dim("key     ")}${ca.keyPath}`);
 	console.log(`  ${pc.dim("bundle  ")}${ca.bundlePath}`);
-	console.log(`  ${pc.dim("system  ")}${ca.systemBundle ?? "Node's built-in roots"}`);
+	console.log(`  ${pc.dim("system  ")}${ca.systemTrust}`);
 	if (ca.inheritedCa !== void 0) console.log(`  ${pc.dim("corp    ")}${ca.inheritedCa}  ${pc.dim("(inherited from NODE_EXTRA_CA_CERTS)")}`);
 	if (options.install) {
 		console.log(`\n  ${pc.bold("Installing into the system trust store")} ${pc.dim("(run these yourself)")}\n`);
@@ -369,6 +422,11 @@ const configSchema = z.strictObject({
 	noProxy: z.array(z.string()).optional(),
 	/** Hosts tunnelled without interception, for clients that pin certificates. */
 	tlsPassthrough: z.array(z.string()).optional(),
+	/**
+	* Where `run` writes its own log, relative to this file. The literal
+	* `terminal` keeps it interleaved with the target's output.
+	*/
+	logFile: z.string().optional(),
 	rules: z.array(ruleSchema).default([])
 });
 //#endregion
@@ -449,6 +507,10 @@ async function loadConfig(explicitPath, options = {}) {
 	if (raw === null || raw === void 0) raw = {};
 	return compile(raw, path.dirname(filePath), filePath);
 }
+/** Resolve a path declared in the config, relative to the config file. */
+function resolveFromConfig(loaded, target) {
+	return path.resolve(loaded.baseDir, target);
+}
 //#endregion
 //#region src/commands/check.ts
 /** Describes what a rule does, in one word. */
@@ -677,6 +739,12 @@ host: api.example.com
 #   <url> an explicit proxy
 upstream: auto
 
+# Where jean-claude's own log goes while \`run\` has a child, so a full-screen
+# tool keeps the terminal to itself. A path relative to this file, or 'terminal'
+# to leave the log interleaved with your tool's output.
+# Default: <home>/jean-claude.log
+# logFile: jean-claude.log
+
 rules:
   # 1 - Replace the response with a file. The server is never contacted.
   - name: frozen todos
@@ -707,6 +775,12 @@ host: api.anthropic.com
 #   <url> an explicit proxy
 upstream: auto
 
+# Where jean-claude's own log goes while \`run\` has a child, so a full-screen
+# tool keeps the terminal to itself. A path relative to this file, or 'terminal'
+# to leave the log interleaved with your tool's output.
+# Default: <home>/jean-claude.log
+# logFile: jean-claude.log
+
 rules:
   # 1 - Freeze the settings Claude Code fetches at startup: it gets this file
   #     instead, and the server is never contacted for it. Edit the 'settings'
@@ -770,6 +844,42 @@ async function initCommand(options) {
 	return 0;
 }
 //#endregion
+//#region src/log/sink.ts
+function redirect(stream, sink) {
+	const original = stream.write;
+	stream.write = ((chunk, encoding, callback) => {
+		const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+		sink.write(stripVTControlCharacters(text));
+		const done = typeof encoding === "function" ? encoding : callback;
+		if (typeof done === "function") done();
+		return true;
+	});
+	return () => {
+		stream.write = original;
+	};
+}
+/**
+* Start capturing. `header` opens the session in the file: the log is appended
+* to, never truncated, so two concurrent runs cannot wipe each other's output.
+*/
+async function captureOutputTo(filePath, header) {
+	await mkdir(path.dirname(filePath), { recursive: true });
+	const sink = createWriteStream(filePath, { flags: "a" });
+	sink.write(`\n${header}\n`);
+	const restore = [redirect(process.stdout, sink), redirect(process.stderr, sink)];
+	return {
+		path: filePath,
+		close: async () => {
+			for (const undo of restore) undo();
+			await new Promise((resolve) => sink.end(resolve));
+		}
+	};
+}
+/** Opening line of a captured session, so a shared log stays readable. */
+function sessionHeader(command, now = /* @__PURE__ */ new Date()) {
+	return `=== jean-claude ${now.toISOString()} pid ${process.pid} - ${command} ===`;
+}
+//#endregion
 //#region src/config/watch.ts
 /**
 * Watches the config file and calls `onChange` after each save.
@@ -791,6 +901,19 @@ function watchConfig(filePath, onChange) {
 }
 //#endregion
 //#region src/log/reporter.ts
+/**
+* OpenSSL verification failures, as opposed to the dozens of other ways a relay
+* can die. They all mean the same thing operationally: jean-claude was not given
+* the authority that signed what it was talking to.
+*/
+const TRUST_ERROR_CODES = /* @__PURE__ */ new Set([
+	"UNABLE_TO_GET_ISSUER_CERT",
+	"UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+	"UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+	"SELF_SIGNED_CERT_IN_CHAIN",
+	"DEPTH_ZERO_SELF_SIGNED_CERT",
+	"CERT_UNTRUSTED"
+]);
 const KIND_LABELS = {
 	stub: "stub",
 	patch: "patched",
@@ -819,6 +942,9 @@ function pad(text, width) {
 function truncate(text, width) {
 	return text.length <= width ? text : `${text.slice(0, width - 1)}…`;
 }
+function plural(count, noun) {
+	return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
 /**
 * Console log. One line per request, emitted on response so that the status
 * actually delivered to the client can be shown.
@@ -826,6 +952,24 @@ function truncate(text, width) {
 var Reporter = class {
 	options;
 	entries = /* @__PURE__ */ new Map();
+	/** The trust hint is the same every time; once per run is enough. */
+	trustHintShown = false;
+	/**
+	* Counted even under `--quiet`, and even when the log went to a file: the
+	* summary is the only thing a redirected run says on the terminal.
+	*/
+	counts = {
+		requests: 0,
+		ruleHits: 0,
+		upstreamErrors: 0
+	};
+	/**
+	* Requests already reported as an upstream failure. mockttp still hands the
+	* client a synthetic 502 afterwards, which would otherwise show up as a second
+	* line - with no method and no URL, since the entry is already gone - and
+	* count the same request twice.
+	*/
+	failed = /* @__PURE__ */ new Set();
 	constructor(options) {
 		this.options = options;
 	}
@@ -843,6 +987,7 @@ var Reporter = class {
 		});
 	}
 	action(id, kind, label, detail) {
+		if (kind !== "passthrough") this.counts.ruleHits += 1;
 		this.upsert(id, {
 			kind,
 			label,
@@ -853,8 +998,10 @@ var Reporter = class {
 		this.upsert(id, { recorded: filePath });
 	}
 	response(id, statusCode) {
+		if (this.failed.delete(id)) return;
 		const entry = this.entries.get(id) ?? {};
 		this.entries.delete(id);
+		this.counts.requests += 1;
 		if (this.options.quiet) return;
 		if ((entry.kind ?? "passthrough") === "passthrough" && entry.recorded === void 0 && !this.options.verbose) return;
 		console.log(`  ${pad(entry.method ?? "???", 6)}${pad(truncate(shortTarget(entry.url), 52), 54)}${colorStatus(statusCode)}${this.describeAction(entry)}`);
@@ -871,11 +1018,31 @@ var Reporter = class {
 	aborted(id, reason) {
 		const entry = this.entries.get(id) ?? {};
 		this.entries.delete(id);
+		this.counts.requests += 1;
 		if (this.options.quiet) return;
 		const detail = reason !== void 0 ? ` ${pc.dim(`(${reason})`)}` : "";
 		console.log(`  ${pad(entry.method ?? "???", 6)}${pad(truncate(shortTarget(entry.url), 52), 54)}${pc.red("aborted")}${detail}`);
 	}
 	/**
+	* jean-claude reached the target but could not talk to the real server. Worth
+	* a line of its own: the client is handed a 502 it did not ask for, and the
+	* reason lives on the relay leg, which neither `response` nor `abort` covers.
+	*/
+	upstreamFailed(id, error) {
+		const entry = this.entries.get(id) ?? {};
+		this.entries.delete(id);
+		this.failed.add(id);
+		this.counts.requests += 1;
+		this.counts.upstreamErrors += 1;
+		if (this.options.quiet) return;
+		const reason = error.code ?? error.message ?? "unknown error";
+		console.log(`  ${pad(entry.method ?? "???", 6)}${pad(truncate(shortTarget(entry.url), 52), 54)}${pc.red("upstream")}  ${pc.dim(reason)}`);
+		if (TRUST_ERROR_CODES.has(error.code ?? "") && !this.trustHintShown) {
+			this.trustHintShown = true;
+			this.warn("jean-claude could not verify the real server's certificate. On the way out it trusts the OS certificate store plus NODE_EXTRA_CA_CERTS - if your network intercepts TLS with a CA that is in neither, export that CA and point NODE_EXTRA_CA_CERTS at it before running jean-claude.");
+		}
+	}
+	/**
 	* A client-side TLS failure almost always means the target pins its
 	* certificates. Say so, rather than leaving the user to guess.
 	*/
@@ -884,6 +1051,20 @@ var Reporter = class {
 		const where = hostname ?? "unknown host";
 		this.warn(`TLS handshake with ${where} failed - the target rejected jean-claude's CA (certificate pinning?). Add "tlsPassthrough: [${where}]" to the config to tunnel it untouched.`);
 	}
+	/**
+	* What happened, in one line, `undefined` when nothing did.
+	*
+	* This is what a run whose log went to a file gets to say on the terminal, so
+	* a redirect never reads as "jean-claude did nothing".
+	*/
+	summary() {
+		const { requests, ruleHits, upstreamErrors } = this.counts;
+		if (requests === 0) return void 0;
+		const parts = [plural(requests, "request")];
+		if (ruleHits > 0) parts.push(`${plural(ruleHits, "rule hit")}`);
+		if (upstreamErrors > 0) parts.push(pc.red(plural(upstreamErrors, "upstream error")));
+		return parts.join(", ");
+	}
 	banner(lines) {
 		if (this.options.quiet) return;
 		const width = Math.max(...lines.map(([key]) => key.length));
@@ -1338,14 +1519,20 @@ function makeBeforeResponse(compiled, ctx) {
 /**
 * Options shared by every passthrough: where to send relayed traffic, and which
 * extra authorities to trust on the way out.
+*
+* `additionalTrustedCAs` is not additive on the Node side: mockttp turns it into
+* an explicit `ca` list (its own bundled roots plus ours), and `ca` *replaces*
+* the default store. So this has to carry the OS trust store as well as the
+* corporate CA, or passing a corporate CA would narrow the trust set instead of
+* widening it.
 */
-function buildConnectionOptions({ upstream, inheritedCa }) {
+function buildConnectionOptions({ upstream, outboundTrust }) {
 	return {
 		...upstream !== void 0 ? { proxyConfig: {
 			proxyUrl: upstream.proxyUrl,
 			...upstream.noProxy !== void 0 ? { noProxy: upstream.noProxy } : {}
 		} } : {},
-		...inheritedCa !== void 0 ? { additionalTrustedCAs: [{ certPath: inheritedCa }] } : {}
+		...outboundTrust !== void 0 ? { additionalTrustedCAs: [{ cert: outboundTrust }] } : {}
 	};
 }
 async function startProxy(options) {
@@ -1367,6 +1554,10 @@ async function startProxy(options) {
 		await proxy.on("response", (response) => reporter.response(response.id, response.statusCode));
 		await proxy.on("abort", (request) => reporter.aborted(request.id, request.error?.message));
 		await proxy.on("tls-client-error", (failure) => reporter.tlsError(failure.tlsMetadata.sniHostname ?? failure.destination?.hostname));
+		await proxy.on("rule-event", (event) => {
+			if (event.eventType !== "passthrough-abort") return;
+			reporter.upstreamFailed(event.requestId, event.eventData.error);
+		});
 	}
 	async function registerRules() {
 		const ctx = {
@@ -1405,8 +1596,28 @@ async function startProxy(options) {
 		stop: () => proxy.stop()
 	};
 }
-//#endregion
-//#region src/commands/shared.ts
+/**
+* Where jean-claude's own output should go, `undefined` meaning the terminal.
+*
+* `--log` wins over the config, which wins over the default. The default is a
+* file only when a child is about to take the terminal over *and* that terminal
+* is interactive: piping `run` into something else, or running it in CI, keeps
+* the log on the stream where it is expected.
+*
+* `logFile:` is read only when a child is spawned. `start` exists precisely to
+* give the log a terminal of its own, so a global `logFile:` silently muting it
+* would be a trap - there, only an explicit `--log` redirects.
+*/
+function resolveLogDestination(session, options, cwd = process.cwd()) {
+	if (options.log === "terminal") return void 0;
+	if (options.log !== void 0) return path.resolve(cwd, options.log);
+	if (options.spawnsChild) {
+		const fromConfig = session.loaded.config.logFile;
+		if (fromConfig === "terminal") return void 0;
+		if (fromConfig !== void 0) return resolveFromConfig(session.loaded, fromConfig);
+		if (process.stdout.isTTY === true) return logFileIn(session.home);
+	}
+}
 /**
 * Brings up everything `run` and `start` need: config, CA, upstream detection,
 * the proxy itself, and optional config hot-reload.
@@ -1424,13 +1635,14 @@ async function openSession(options) {
 		dir: caDirIn(home),
 		inheritedCa
 	});
+	const recorder = options.record !== void 0 ? new Recorder(path.resolve(options.record)) : void 0;
 	const proxy = await startProxy({
 		loaded,
 		ca,
 		upstream,
-		inheritedCa,
+		outboundTrust: ca.outboundTrust,
 		reporter,
-		recorder: options.record !== void 0 ? new Recorder(path.resolve(options.record)) : void 0,
+		recorder,
 		port: options.port
 	});
 	const childEnvOptions = {
@@ -1492,10 +1704,15 @@ async function runCommand(command, options) {
 	const [file, ...args] = command;
 	if (file === void 0) throw new Error("nothing to run: pass the target command after `--`, e.g. `jean-claude run -- npx my-tool`.");
 	const session = await openSession(options);
-	printBanner(session, [["command", command.join(" ")]]);
+	const logFile = resolveLogDestination(session, {
+		log: options.log,
+		spawnsChild: true
+	});
+	printBanner(session, [...logFile !== void 0 ? [["log", `${logFile}  ${pc.dim("(tail -f to follow)")}`]] : [], ["command", command.join(" ")]]);
 	const swallow = () => {};
 	process.on("SIGINT", swallow);
 	process.on("SIGTERM", swallow);
+	const capture = logFile !== void 0 ? await captureOutputTo(logFile, sessionHeader(command.join(" "))) : void 0;
 	try {
 		return (await execa(file, args, {
 			env: buildChildEnv(process.env, {
@@ -1510,6 +1727,12 @@ async function runCommand(command, options) {
 		process.off("SIGINT", swallow);
 		process.off("SIGTERM", swallow);
 		await session.stop();
+		await capture?.close();
+		const summary = session.reporter.summary();
+		if (summary !== void 0 && !options.quiet) {
+			const where = capture !== void 0 ? `  ${pc.dim(`→ ${capture.path}`)}` : "";
+			console.log(`\n  ${summary}${where}\n`);
+		}
 	}
 }
 //#endregion
@@ -1517,6 +1740,10 @@ async function runCommand(command, options) {
 /** Runs the proxy in the foreground until interrupted, for targets we cannot spawn. */
 async function startCommand(options) {
 	const session = await openSession(options);
+	const logFile = resolveLogDestination(session, {
+		log: options.log,
+		spawnsChild: false
+	});
 	await writeSessionFile(session.home, {
 		proxy: session.proxy.url,
 		port: session.proxy.port,
@@ -1539,12 +1766,17 @@ async function startCommand(options) {
 		}, null, 2));
 		else if (options.export) console.log(formatShellExports(session.env, session.unset));
 		else {
-			printBanner(session);
+			printBanner(session, logFile !== void 0 ? [["log", logFile]] : []);
 			console.log(`  ${pc.dim("In the shell that runs your tool:")}\n`);
 			console.log(`    ${pc.bold("eval \"$(jean-claude env)\"")}\n`);
 			console.log(`  ${pc.dim("Ctrl-C to stop.")}\n`);
 		}
-		await waitForInterrupt();
+		const capture = logFile !== void 0 ? await captureOutputTo(logFile, sessionHeader("start")) : void 0;
+		try {
+			await waitForInterrupt();
+		} finally {
+			await capture?.close();
+		}
 	} finally {
 		await removeSessionFile(session.home);
 		await session.stop();
@@ -1577,6 +1809,7 @@ function toSessionOptions(flags) {
 		port: flags.port,
 		record: flags.record,
 		home: flags.home,
+		log: flags.log,
 		verbose: flags.verbose ?? false,
 		quiet: flags.quiet ?? false,
 		watch: flags.watch ?? true
@@ -1584,10 +1817,10 @@ function toSessionOptions(flags) {
 }
 /** Flags common to `run` and `start`. */
 function withSessionFlags(command) {
-	return command.option("-c, --config <path>", "path to the config file (default: nearest jean-claude.yaml, then the home one)").option("-p, --port <port>", "port to listen on (default: a free port)", parsePort).option("-r, --record <dir>", "write real responses to this directory, ready to reuse as stubs").option("--home <dir>", HOME_DESCRIPTION).option("-v, --verbose", "also log traffic that matches no rule").option("-q, --quiet", "suppress the per-request log").option("--no-watch", "do not reload the config when it changes");
+	return command.option("-c, --config <path>", "path to the config file (default: nearest jean-claude.yaml, then the home one)").option("-p, --port <port>", "port to listen on (default: a free port)", parsePort).option("-r, --record <dir>", "write real responses to this directory, ready to reuse as stubs").option("--home <dir>", HOME_DESCRIPTION).option("--log <path|terminal>", "where to write jean-claude's own log (default: a file while `run` has a child)").option("-v, --verbose", "also log traffic that matches no rule").option("-q, --quiet", "suppress the per-request log").option("--no-watch", "do not reload the config when it changes");
 }
 const program = new Command();
-program.name("jean-claude").description("MITM HTTPS proxy that rewrites another tool's API traffic, driven by a YAML file.").version("0.1.0");
+program.name("jean-claude").description("MITM HTTPS proxy that rewrites another tool's API traffic, driven by a YAML file.").version("0.2.0");
 withSessionFlags(program.command("run", { isDefault: true }).description("run a command with its HTTPS traffic intercepted").argument("<command...>", "the command to run, after `--`")).action(async (command, flags) => {
 	process.exitCode = await runCommand(command, toSessionOptions(flags));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@etiennepasteur/jean-claude",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A CLI MITM HTTPS proxy that intercepts and rewrites another tool's API traffic, driven by a YAML file.",
   "keywords": [
     "proxy",