cadwork-python-runner README

cadwork-python-runner is a Visual Studio Code extension designed to facilitate running Python scripts within the cadwork environment. This extension allows users to execute Python scripts directly from VS Code and integrates with cadwork's API for automation and custom scripting.

Features

• Seamless Integration: Run Python scripts within the cadwork environment from VS Code (command / status bar / keybinding).
• Live run stream: After sending a script, the extension reads a NDJSON event stream on the same TCP connection until a finished or failed trailer.
• Idle timeout: Configurable silence timeout (cadwork-python-runner.idleTimeoutMs, default 90s) — not a short total-run cap. Connect timeout is separate (connectTimeoutMs, default 10s).
• Concurrent runs: Each run opens its own connection so a second fire can enter the listener FIFO without a false “Already sending…” lock.

Wire protocol (v1)

Client → listener:

1. Connect to host:port (default localhost:9999).
2. Write the raw UTF-8 script body.
3. Half-close the write side (socket.end() / TCP FIN) — do not destroy before reading.
4. Read NDJSON lines (\n-terminated) until a trailer event.

Event type values: queued, started, stdout, stderr, log, heartbeat, finished, failed.
Exactly one of finished | failed ends the stream. Unknown non-trailer types are shown as log text (forward-compatible).

PowerShell one-shot sketch (half-close + read remaining):

$client = New-Object System.Net.Sockets.TcpClient('127.0.0.1', 9999)
$stream = $client.GetStream()
$bytes = [System.Text.Encoding]::UTF8.GetBytes("print('hello')`n")
$stream.Write($bytes, 0, $bytes.Length)
$client.Client.Shutdown([System.Net.Sockets.SocketShutdown]::Send)
$reader = New-Object System.IO.StreamReader($stream)
while ($null -ne ($line = $reader.ReadLine())) { $line }
$client.Close()

Requirements

Before using this extension, ensure that you have:

• cadwork installed and properly configured.

• VS Code installed with this extension enabled.

• Code listener plugin available in cadwork 3d Code Listener Plugin

Install from a VSIX

1. Download the latest .vsix from GitHub Releases.
2. In VS Code: Extensions → … → Install from VSIX… and pick the file.

CI also uploads a VSIX artifact on every push/PR (Actions → latest workflow run → Artifacts).

Versioning & releasing

This extension uses Semantic Versioning in package.json.

Change type	Command	Example
Bug fix / small fix	npm version patch	0.0.2 → 0.0.3
New feature (compatible)	npm version minor	0.0.2 → 0.1.0
Breaking change	npm version major	0.0.2 → 1.0.0

Release flow:

1. Merge your work to main.

2. Update the [Unreleased] section in CHANGELOG.md with user-facing notes.

3. Bump version and create a git tag (also syncs the changelog header):

   npm version patch   # or minor / major
   git push origin main --follow-tags

4. The Release GitHub Action packages the extension and publishes a GitHub Release with the .vsix attached. The tag must be vX.Y.Z and match package.json (e.g. v0.0.3).

Local package (no release):

npm run package
# → cadwork-python-runner-<version>.vsix

Release Notes

See CHANGELOG.md for the full history.

0.0.2

Stable code-listener stream protocol, idle timeout, concurrent runs, and automated VSIX builds.

0.0.1

Initial release.

---