devsandbox CLAUDE.md

devsandbox

Coding practices

After completing the task always run:

• task test - to run tests
• task lint - to run lint

Always prefer reasonable defaults if that it possible. Reduce amount of work for the user to do when this is possible. All defaults must be secure by default, and not cause any security issues if used without modification. Never bind to all interfaces by default, and do not expose any ports by default.

Errors must always be handled and reported when present. Silent failures are not acceptable.

notice.Warn is for something the user has to act on: a setting that was ignored, a control that reaches less than it says, a cleanup that did not run. A tool reporting that it started, or that an optional integration is not attached, is notice.Info. The distinction is load-bearing, not cosmetic - every warning raised before the workload starts is collected and blocks the launch on a confirmation prompt, so an announcement emitted at warn level turns every launch into a question and trains the user to answer it without reading. notice.Alert is a warning that must reach the terminal even during the running phase.

A ToolWithSetup runs in PhaseRunning, so its warnings must be notice.Alert. main.go's SetRunning() precedes iso.Run → bwrap.go's AddTools(), and writeMessagePhase only reaches stderr when always || verbose || PhaseStartup || PhaseTeardown - so a notice.Warn raised from tool setup is diverted to the log file and misses the confirmWarningsStdio gate entirely. Setup also must not return an error for a condition the user should merely be told about: builder.go aborts the launch on a setup error while docker.go only warns, so the same condition would be fatal on one backend and cosmetic on the other.

Setup runs more than once per launch, so a Setup that records state must assign it, never append. tools.Register hands out singletons and internal/isolator/docker.go calls getToolBindings twice per launch, each of which calls Setup on that same struct - so appending emits every binding twice, which is a trackMount panic on bwrap and a "Duplicate mount point" error on Docker, i.e. every launch of that tool failing. Git.refBindings is the worked example: setupReadWriteRefs assigns it, and dedups against the static set rather than trusting the count. The mirror rule is that Bindings must stay pure - tools info and tools check call it on a registry singleton that Setup never touched, so anything subprocess-shaped belongs in Setup, and Bindings only appends what it left behind, degrading to exactly the static set when that is nil.