Community help wanted: make Windows/WSL support work and testable

[IgorWarzocha]

Goal

Make Windows/WSL support possible for community contributors who have access to a Windows machine and can test the edge cases directly.

This is intentionally up for grabs. I do not have a Windows machine available, so implementing and validating this well from my environment would be hard, especially for the path, terminal, and Git/runtime behavior that only fails in real Windows + WSL setups.

Current behavior

The app has native platform handling, but no explicit WSL mode:

• The npm launcher selects builds by process.platform/process.arch.
  • Native Windows gets the Windows build.
  • Running from inside WSL looks like Linux and gets the Linux build.
• The embedded terminal is platform-native.
  • Windows uses COMSPEC/PowerShell/cmd style behavior.
  • Linux/macOS use $SHELL or /bin/bash.
• Project IDs, session paths, Git operations, attachments, and file stats assume the app runtime and project filesystem are on the same OS.
• There is no WSL detection, no wsl.exe integration, and no wslpath conversion.

Relevant starting points:

• packages/howcode/lib/howcode.js — platform-specific launcher/download target selection.
• desktop/terminal/terminal-command.helpers.ts — terminal command resolution.
• desktop/terminal/node-pty.cts and desktop/terminal/manager.cts — embedded PTY/session lifecycle.
• desktop/pi-threads/composer-attachment-payload.ts — local path normalization/stat handling.
• desktop/system-open-path.cts — platform-specific open-in-system behavior.
• desktop/pi-threads/shell-state.cts and project/thread DB paths — project cwd/session assumptions.

Possible approaches

This issue does not prescribe one solution. A contributor with Windows/WSL access should validate the smallest useful path.

Possible minimal path:

• Document that WSL users should run howcode from inside WSL/Linux so Pi, Git, shell, files, and paths all share one Linux environment.
• Add warnings or guardrails for unsupported native-Windows + WSL-project combinations.

Possible native Windows + WSL path:

• Add WSL detection and/or a setting like “Use WSL for this project”.
• Launch terminal sessions through wsl.exe on Windows when that mode is enabled.
• Convert paths using wslpath where needed.
• Decide whether Pi sessions should run as Windows pi.cmd or Linux pi inside WSL per project/runtime.
• Route enough Git/file/open-path behavior through the same runtime so the feature does not only work in the terminal.

A more robust shape may be a project runtime concept, for example:

type ProjectRuntime = "host" | "wsl";

Then terminal, Pi, Git, file stats, path opening, attachments, and session paths can make consistent decisions per project.

Scope

• Investigate and propose/implement a coherent WSL support path for Windows users.
• Prefer the smallest shippable slice that can be tested on a real Windows + WSL machine.
• Include docs if the initial answer is “supported only when running howcode from inside WSL”.
• Add tests for path/command resolution helpers where practical.

Acceptance criteria

• The issue/PR clearly states which WSL usage mode is supported:
  • running the Linux app from inside WSL, and/or
  • native Windows app controlling WSL projects.
• The chosen mode is tested on a real Windows + WSL setup and notes the tested Windows version, WSL distro, and install/run path.
• Terminal launch behavior is predictable for WSL projects.
• Project paths/session paths do not silently mix Windows and WSL formats in a way that breaks Git, Pi, attachments, or open-path behavior.
• Unsupported combinations show useful documentation or UI/console guidance instead of failing mysteriously.

Notes

This is marked for community help because it needs real Windows + WSL validation. Maintainer review can help with architecture and repo fit, but the implementation needs someone who can reproduce the environment.

[snakefood3232]

I see the need for WSL detection and integration to make Howcode work seamlessly on Windows/WSL setups. I'd handle this by improving path normalization and terminal handling, ensuring compatibility with both Windows native and WSL environments. I can have a pull request up within 3 days. I've built cross-platform terminal applications with WSL support before.

[IgorWarzocha]

Have at it my dude, please work on dev branch! Keep me posted here. I do have someone who can look at Windows stuff for me, but they don't use WSL and don't have too much time.

Although I suppose @JosXa could have a look once it's ready to fire. That being said... Do you even have WSL on that Windows machine of yours Joscha? ;)

[Chris79OG]

I ran a focused Windows/WSL validation pass against current dev (01a55210749f71478afebb0d5535771d2ad0e20f) from a Windows 11 + WSL 2 machine.

Environment:

• Windows 11 Pro 10.0.26200 x64
• WSL: Ubuntu 24.04.4 LTS, WSL 2
• Windows Node: v24.15.0
• Windows bun: 1.3.10
• WSL Node: v22.22.2

Results:

• Clean clone of dev: passed.
• Native Windows bun install --frozen-lockfile: failed while rebuilding node-pty via electron-builder install-app-deps.
• better-sqlite3 rebuilt successfully; node-pty failed in MSBuild with MSB8040, requiring Visual Studio Build Tools Spectre-mitigated libraries for the active toolset/architecture.
• WSL is present and running, but this WSL environment does not currently have bun installed, so I did not claim a full Linux/WSL app build.

Static findings from the issue's likely WSL surfaces:

• The npm launcher currently chooses the app artifact from host process.platform/process.arch. Native Windows gets the Windows app; running from inside WSL gets the Linux app.
• Terminal resolution is host-platform based: Windows uses COMSPEC/PowerShell fallback and Linux uses $SHELL//bin/bash. I did not find a project-level WSL runtime mode or wsl.exe terminal path yet.
• Attachment path normalization accepts Windows drive paths and POSIX absolute paths, but does not convert between Windows and WSL path forms.
• Open-path behavior is host-platform based (rundll32.exe on Windows, xdg-open on Linux), so native Windows controlling WSL project files still needs an explicit runtime/path decision.

My read: the smallest shippable support statement is probably "WSL projects are supported when running howcode from inside WSL/Linux" unless a separate host vs wsl project runtime is added. For native Windows controlling WSL projects, terminal launch, Pi command selection, Git/filesystem paths, attachments, and open-path behavior need to share the same runtime choice or the feature will work only in the terminal.

[IgorWarzocha]

@Chris79OG Thank you kindly for this investigation. I'll have a look into it, this is very good info.

From what I see this seems perfectly doable!

[Chris79OG]

I turned the WSL-terminal slice into a focused branch after your reply: #264

The repo's vouch gate auto-closed the PR, but the patch is available here if useful: https://github.com/Chris79OG/howcode/tree/luminaflow/howcode-wsl-terminal-cwd

Scope kept narrow:

• Detect \wsl$\Distro\... and \wsl.localhost\Distro\... project cwd values on Windows.
• Launch the embedded terminal through wsl.exe -d --cd instead of the normal Windows shell for those paths.
• Leave native Windows project terminals unchanged.

Verified locally with the focused terminal-command test, touched-file Biome, desktop typecheck, and git diff --check.

[IgorWarzocha]

I turned the WSL-terminal slice into a focused branch after your reply: #264

The repo's vouch gate auto-closed the PR, but the patch is available here if useful: https://github.com/Chris79OG/howcode/tree/luminaflow/howcode-wsl-terminal-cwd

Scope kept narrow:

• Detect \wsl$\Distro... and \wsl.localhost\Distro... project cwd values on Windows.
• Launch the embedded terminal through wsl.exe -d --cd instead of the normal Windows shell for those paths.
• Leave native Windows project terminals unchanged.

Verified locally with the focused terminal-command test, touched-file Biome, desktop typecheck, and git diff --check.

vouch @Chris79OG WSL work