Skip to content

Add Windows support with CI/CD testing #3

@jobordu

Description

@jobordu

Summary

nForma currently only supports macOS and Linux. Windows is explicitly listed as unsupported in the README and compatibility table. This issue tracks adding first-class Windows support.

Current state

  • CI matrix: ubuntu-latest + macos-latest only (ci.yml, ci-install.yml, release.yml)
  • package.json engines: >=18.0.0, no os restriction
  • README: "Works on macOS and Linux." — Windows row says "No"
  • Codebase: No process.platform checks anywhere. Several bash scripts in scripts/ (release.sh, secret-audit.sh, publish.sh) assume Unix

Requirements

CI/CD (high priority)

  • Add windows-latest to ci.yml test matrix (Node 18, 20, 22)
  • Add windows-latest to ci-install.yml install test matrix
  • Add windows-latest to release.yml pre-release test job
  • Verify npm run test:ci passes on Windows
  • Verify npm run test:tui passes on Windows (blessed + node-pty compatibility)
  • Verify npm run test:install passes on Windows
  • Verify npm run test:formal passes on Windows (Java/TLA+/Alloy availability)

Codebase fixes (expected)

  • Audit all path.join() / path.resolve() usage for hardcoded / separators
  • Replace bash-specific scripts/ with cross-platform alternatives (or skip on Windows)
  • Test node-pty / blessed-xterm native addon rebuild on Windows
  • Verify keychain/secrets integration works on Windows (macOS security CLI won't exist)
  • Test MCP server spawning (child_process.spawn) with Windows paths
  • Verify hook installation paths work on Windows (~/.claude/%USERPROFILE%\.claude\)

Documentation

  • Update README compatibility table: Windows → "Yes"
  • Update "Works on macOS and Linux" → "Works on macOS, Linux, and Windows"
  • Document any Windows-specific prerequisites (e.g., Visual Studio Build Tools for node-pty)

Acceptance criteria

  • All three CI workflows pass on windows-latest with Node 18, 20, 22
  • npx @nforma.ai/nforma installs and runs the TUI on Windows
  • Sessions can spawn Claude Code inside the TUI on Windows
  • Quorum agent MCP servers start and respond to health checks on Windows

Notes

The biggest risk is node-pty (native addon for terminal emulation in the TUI Sessions module). It requires Visual Studio Build Tools on Windows. Consider whether to make Sessions an optional feature on Windows or bundle a prebuilt binary.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions