Make Gimlet Configurable

[ERoydev]

Summary

Makes Gimlet configurable via .vscode/gimlet.json. Users can now override:

• tcpPort — debug session port (default 1212)
• stopOnEntry — pause at program entry (default true)
• platformToolsVersion — Solana platform-tools version (default 1.54)
• platformToolsDir — full override of the platform-tools root
• lldbLibraryPath — direct path to liblldb.{dylib,so} for non-standard layouts
• depsPath — where compiled programs live (default target/deploy/debug)
• sbfTraceDir — where SBF traces are written (default target/sbf/trace)

gimlet.json is auto-created on activation with current values and re-read on save. Invalid keys are reported in a single aggregated toast; unknown keys are logged and ignored. Deleting the file resets all overrides to defaults. LLDB library resolution is lazy and re-runs on relevant config changes.

Changes

• New .vscode/gimlet.json with schema-validated keys and a workspace-relative file watcher
• globalState is now the single source of truth for config; defaults restored when keys are absent
• Workspace containment check for path-style overrides (depsPath, sbfTraceDir)
• Diff-then-write to avoid spurious save events
• README updated with the options table

Test plan

• Set/clear each option in .vscode/gimlet.json and confirm the toast + state update
• Delete gimlet.json and confirm "using defaults" toast + behavior reverts
• Set platformToolsVersion to a missing version and confirm the LLDB error toast
• Set depsPath/sbfTraceDir outside the workspace and confirm rejection

[Copilot]

Pull request overview

This PR makes Gimlet’s debugger/session behavior configurable via a workspace .vscode/gimlet.json, including validation, persistence into globalState, and live reloads via a file watcher.

Changes:

• Add schema-based validation and default-reset behavior for Gimlet config values, with lazy LLDB library resolution.
• Add .vscode/gimlet.json creation + file watching to reload config on save/delete, plus workspace-containment checks for certain paths.
• Update debugger launch plumbing and UX messages (e.g., improved LLDB/platform-tools diagnostics; better deploy-dir scanning errors).

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/state/globalState.js	Adds schema validation, new override fields, and lazy/cached LLDB library path resolution.
src/config.js	Creates/merges gimlet.json, validates + applies config into globalState, adds watcher + containment checks.
src/managers/portManager.js	Moves LLDB config resolution inside try/catch so config errors are surfaced cleanly.
src/managers/debugConfigManager.js	Derives platform-tools paths from globalState overrides; updates missing-tools error messaging.
src/extension.js	Makes deploy-dir scanning resilient to null config; improves error when no .so files are present.
README.md	Documents new configuration options and guidance.
.gitignore	Ignores .claude.

Comments suppressed due to low confidence (1)

src/config.js:124

• ensureGimletConfig() only auto-writes tcpPort, platformToolsVersion, and stopOnEntry, but the PR description says gimlet.json is auto-created with the current values for additional configurable keys (depsPath, sbfTraceDir, platformToolsDir, lldbLibraryPath). If the intent is discoverability via the generated file, include these keys (likely as null when unset) so users can see the full set of supported overrides.

        const defaultConfig = {
            tcpPort: globalState.tcpPort,
            platformToolsVersion: globalState.platformToolsVersion,
            stopOnEntry: globalState.stopOnEntry,
        };

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

src/config.js:124

• ensureGimletConfig() only writes tcpPort, platformToolsVersion, and stopOnEntry into the auto-created .vscode/gimlet.json. That means users won’t see (or be able to easily discover) the newly supported options like artifactPath, sbfTracePath, platformToolsPath, and lldbLibraryPath in the generated file, despite the PR description/README advertising them. Consider including all supported keys in defaultConfig (with workspace-relative defaults or null where appropriate).

        const defaultConfig = {
            tcpPort: globalState.tcpPort,
            platformToolsVersion: globalState.platformToolsVersion,
            stopOnEntry: globalState.stopOnEntry,
        };

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[procdump]

Suggestions from a separate code review pass. Most are message-wording / cleanup; the inline ones are anchored on diff lines. Two more sit on lines that aren't part of this PR's diff, so I'm leaving them here as text — feel free to take or leave any of them.

---

src/extension.js:142 — await the config init so internal throws don't become unhandled rejections.

ensureGimletConfig() is async and contains synchronous fs calls (fs.mkdirSync, fs.writeFileSync) that can throw on permission errors. Without await, any throw becomes an unhandled promise rejection — the user sees nothing. Adding await routes errors through activateDebugger's existing outer try/catch.

-        gimletConfigManager.ensureGimletConfig();
+        await gimletConfigManager.ensureGimletConfig();
         gimletConfigManager.watchGimletConfig(context);

---

src/managers/debugConfigManager.js:103 — replace silent abort with a thrown error.

if (!session) return false; is the only remaining false-return path in loadProgramModules. portManager catches a thrown error and shows a toast, but a false return triggers stopDebugging() with no explanation. The race is rare (session cleanup vs. debug start) but when it happens the debug session vanishes mysteriously.

-        if (!session) return false;
+        if (!session) {
+            throw new Error(
+                'Gimlet debug session was cleared before program modules could load. ' +
+                    'This usually means the session was stopped concurrently — try debugging again.'
+            );
+        }

If you take this, loadProgramModules no longer needs return true at the bottom, and the matching if (!loaded) branch in portManager.js:143-146 becomes dead code — both can go.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[procdump]

nit: dead code - remove