feat: default env file creation for mcp bundles + mcp server lifecycle logging (#691) - #692

Description

Implements both parts of #691:

1. Default env file creation (--env.file create-if-absent). envfile.EnsureExists() creates the nominated path at startup as an empty commented dotenv file when (and only when) it does not exist — parent directories included, 0600 on unix (O_CREATE|O_EXCL, so no race with a concurrent writer). An existing file is never touched, so a Claude Desktop extension update (which replaces the bundle directory) cannot wipe populated credentials. Wired into initConfig so it applies to every entrypoint (exec, shell, srv, mcp), consistent with --env.file being a root flag. Creation failure is a non-fatal stderr warning, since a missing file is already tolerated by Source.

2. MCP server lifecycle logging. The mcp entrypoint now writes timestamped diagnostics straight to stderr (bypassing the configured log level, which defaults to fatal), because stdio MCP hosts such as Claude Desktop capture stderr and these lines are the only forensic trail for unexpected termination:

• startup line with version, platform, pid, transport and the full process args (as requested in the issue);
• panic recovery on the server goroutine logging the panic value plus stack before exiting non-zero (panics on other goroutines already reach stderr via the Go runtime);
• signal handler logging externally-delivered SIGINT/SIGTERM before exiting with the conventional 128+signum status, distinguishing external termination from a crash;
• a line when the server run ends, distinguishing clean transport closure from a transport error.

No secret values flow through any of these lines. Docs updated in docs/mcp.md; --env.file flag help text updated.

Type of change

• Bug fix (non-breaking change to fix a bug).
• Feature (non-breaking change to add functionality).
• Breaking change.
• Other (eg: documentation change). Please explain.

Issues referenced.

• [FEATURE] MCP bundles should include default env file plus additional server logging #691

Evidence

• New robot scenario Env File Flag Creates Default Empty File When Absent And Never Touches Existing (in stackql_mocked_from_cmd_line.robot): first run against an absent path creates the commented file; the file is then populated and a second run resolves credentials from it and leaves the content byte-identical. Passing locally alongside the pre-existing [FEATURE] Support credential (re)sourcing at any point in the MCP server lifecycle #688 scenario.
• Full mcp.robot suite: 47/47 passing locally against the mock servers (confirms the new stderr diagnostics do not disturb the stdio JSON-RPC protocol tests, including CRLF tolerance and mid-session credential reload).
• Unit tests: new EnsureExists coverage (creation with header + perms, existing file untouched, empty path no-op); full go test --tags "sqlite_stackql" ./... passing locally.
• Manual smoke: stdio server logs starting: version=... pid=... transport=stdio args=[...], received signal "terminated"; terminating (exit 143) on SIGTERM, and server run ended cleanly (transport closed) on stdin EOF.

Checklist:

• A full round of testing has been completed, and there are no test failures as a result of these changes.
• The changes are covered with functional and/or integration robot testing.
• The changes work on all supported platforms.
• Unit tests pass locally, as per the developer guide.
• Robot tests pass locally, as per the developer guide.
• Linter passes locally, as per the developer guide.

Variations

• "All supported platforms" verified by construction rather than execution: file creation uses portable os primitives (the 0600 mode is a unix concern; Windows ignores it), and syscall.SIGTERM/os.Interrupt are defined on Windows in the Go syscall package. CI matrix provides the cross-platform execution evidence.
• Full args are logged verbatim as the issue requests; args can in principle carry sensitive flag values (eg proxy passwords), which is accepted here because the log destination is the host-local stderr capture. Flagging for reviewer sign-off.

Tech Debt

Zero technical debt asserted: no new globals, no new config surface, the diagnostics helper is file-local to the mcp command, and EnsureExists lives beside the existing Source in the envfile package.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ert3uJCBqRc6e1Bm5VBpjq

Generated by Claude Code