Skip to content

feat(distribution): install Open Canvas on Windows - #95

Merged
utpalsinghdev merged 7 commits into
mainfrom
feat/windows-package
Nov 19, 2026
Merged

utpalsinghdev merged 7 commits into
mainfrom
feat/windows-package

Conversation

@utpalsinghdev

Copy link
Copy Markdown
Owner

Summary

The downloadable local app only installed on macOS and Linux. Windows users had no way to install it, even though the bundled Node.js, esbuild, sharp and the native canvas library all ship Windows builds. This adds a Windows package and a PowerShell installer with the same behavior as install.sh: latest or pinned release, HTTPS-only download, SHA-256 check, staged extraction, a smoke run before switching, and no overwriting of files the installer did not create. It needs no administrator rights.

Three things stopped the existing package from working on Windows, beyond the missing launcher and installer:

  • The workspace service checked POSIX mode bits (0700 and 0600) on its state directory and files. Windows reports fixed bits, so the service refused to start. It also tried to open a directory to fsync it, which Windows does not allow, so every save would have ended in the "publication uncertain" error.
  • pnpm links workspace packages with junctions on Windows, and junctions store absolute paths, so an extracted archive would point back at the build machine. Windows archives now use a flat node_modules and ship copies of the three shared workspace packages.
  • open-canvas mcp-config printed a .cmd path, which most MCP clients cannot launch directly. On Windows it now prints a cmd /c entry.

What users will see

On Windows, in PowerShell:

irm https://raw.githubusercontent.com/utpalsinghdev/open-canvas/main/scripts/install.ps1 | iex
open-canvas

The command lives in %USERPROFILE%\.open-canvas\install\bin, which is added to the user PATH. Releases are stored under %USERPROFILE%\.open-canvas\install\releases. open-canvas update, open-canvas changelog and open-canvas mcp-config work with that layout. -Version vX.Y.Z and -Archive mirror the shell installer options. On macOS and Linux nothing changes.

A release needs open-canvas-win32-x64.tar.gz and open-canvas-win32-arm64.tar.gz with their .sha256 files attached before the install command works. The manual archive workflow now builds these two beside the four existing archives.

Affected areas

  • Editor UI, navigation, or keyboard controls
  • Document schema, migration, assets, or native backup format
  • Commands, rendering, layout, or undo/redo
  • MCP tools, targets, revisions, or capabilities (generated mcp-config entry on Windows only; no tools changed)
  • Saving, recovery, or concurrent editing (Windows skips the POSIX mode checks and the directory fsync; behavior on other platforms is unchanged)
  • Import, export, fonts, or visual fidelity
  • Runtime, release, dependencies, or default access behavior
  • Contributor tooling or documentation

Acceptance criteria

  • Windows x64 archive with node.exe, bin/open-canvas.cmd, checksum file: built on a real Windows runner, observed.
  • PowerShell installer with latest, version, local archive, HTTPS-only, checksum, staged extract, per-user install, PATH shim, no foreign overwrite, no admin: implemented. Local-archive, bad-checksum, reinstall and PATH paths observed in CI. The latest and version download paths were run only through a helper test on Linux, because no release has Windows assets yet. The foreign-file refusal was not run on Windows.
  • update, changelog, mcp-config with the Windows layout: changelog and mcp-config observed in CI, and the installed-shim detection that update depends on was exercised. A real update to a newer release is unverified.
  • Windows arm64: included, because windows-11-arm runners are available. It passed the same checks as x64.
  • Workflow matrix entries with a PowerShell smoke test: added and passing; existing targets unchanged.

Verification

Local, Linux x64 (Node 24.22.1, pnpm 12.21.0):

  • corepack pnpm run check: passed.
  • corepack pnpm run build: passed.
  • corepack pnpm run changeset:status --since=origin/main: passed, minor bump for @open-cavas/web.
  • git diff --check origin/main: clean.
  • corepack pnpm run package:local <dir>, then bash scripts/install.sh --archive <archive> into a temporary HOME: installed, open-canvas --version printed 0.7.1, runtime.json and the session POST returned 200, mcp-config unchanged.
  • install.ps1 parsed under PowerShell 7 on Linux, and its download helper was run against a real GitHub redirect, a 404 and an HTTP URL. The installer itself cannot run on Linux.

CI: manual workflow package-local.yml on feat/windows-package, run https://github.com/utpalsinghdev/open-canvas/actions/runs/44585766032, all six jobs passed: linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64 (windows-2025), win32-arm64 (windows-11-arm). An earlier run (44585318147) failed on both Windows targets at the reinstall step, where File.Replace rejected a PowerShell null backup path; the fix is in this PR.

The Windows jobs, using Windows PowerShell 5.1 and a temporary USERPROFILE: installed the built archive, confirmed the user PATH entry, printed --version, rejected a wrong checksum and kept the working command, reinstalled the same archive, ran the installed bundle's managed-install check, printed the changelog, started open-canvas.cmd --no-open, fetched runtime.json, posted the browser session request, and started the exact mcp-config entry and received an initialize response.

Not run: a real update to a newer published release, the published irm | iex URL, browser launch without --no-open, Ctrl+C handling, force-kill recovery, paths with spaces or non-ASCII characters, Windows 10, a machine without the Microsoft Visual C++ Redistributable, antivirus or SmartScreen prompts, and a real MCP client application.

Docs and limits

Updated README, install, runtime, local workspaces and verification. Added .changeset/windows-package.md (minor).

Limits:

  • Windows private state relies on the per-user profile ACL, not 0700 and 0600 checks. Symlinks and non-regular files are still refused.
  • Windows cannot flush a directory, so the last durability step of a save is the fsynced file plus the NTFS journal.
  • Ending only the launcher process leaves its children running; Ctrl+C or taskkill /T ends them. Command Prompt may ask "Terminate batch job (Y/N)?" on Ctrl+C.
  • Windows archives are built on Windows. Release assets must be attached by hand, as for the other platforms.
  • Uninstalling also means removing the bin entry from the user PATH by hand.

🤖 Generated with Claude Code

Windows reports fixed POSIX mode bits and cannot open a directory to
fsync it, so the 0700 checks and directory flush made the workspace
service refuse to start. Skip those POSIX-only steps on win32 and refuse
symlinks explicitly where O_NOFOLLOW does not exist.
install.ps1 mirrors install.sh for Windows: latest, -Version vX.Y.Z or a
local -Archive, HTTPS-only downloads with manual redirect checks, SHA-256
verification, staged extraction, a smoke run of the bundle before it is
stored, a path-relative command shim in ~/.open-canvas/install/bin that
is added to the user PATH, and no overwriting of foreign files. It needs
no administrator rights. .gitattributes pins line endings for shell
scripts and Windows batch files.
package:local now builds open-canvas-win32-<arch>.tar.gz with node.exe,
a bin/open-canvas.cmd launcher and install.ps1. Windows archives use a
flat node_modules and replace pnpm's absolute workspace junctions with
copies so the tree can be extracted anywhere. The archive keeps the
.tar.gz name used by the updater and is written with the system bsdtar.
open-canvas update recognizes the Windows shim layout and runs
install.ps1 through Windows PowerShell. mcp-config prints a cmd.exe
entry because MCP clients cannot launch a .cmd file directly.
Add win32-x64 and win32-arm64 targets to the manual archive workflow.
Windows installs the built archive into a temporary profile with Windows
PowerShell 5.1, checks the user PATH entry, rejects a bad checksum,
starts the editor with --no-open, requests runtime.json and the browser
session, and starts the MCP entry printed by mcp-config. Existing
targets keep their steps.
File.Replace received an empty backup path from a PowerShell null and
rejected it, so reinstalling over an existing command failed.
Describe the PowerShell installer, Windows layout, MCP entry, update and
uninstall steps, and the Windows runtime differences. Record the CI run
that exercised both Windows architectures and list what remains
unverified. Add the minor changeset.
@utpalsinghdev
utpalsinghdev merged commit e111c44 into main Nov 19, 2026
1 check passed
@utpalsinghdev utpalsinghdev mentioned this pull request Nov 19, 2026
2 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant