fix(video2code): resolve Python across platforms

[yu-xin-c]

Summary

Make video2code's Python entrypoints portable without requiring a command named python3 on Windows.

• Add a bundled Node launcher: try py -3, python, then python3 on Windows; python3, then python on macOS/Linux. Probe Python >= 3.10 before running a script. Do not retry a script after it fails.
• Route all five Hook commands and both MCP servers through the launcher. Preserve arguments, stdio, and exit status; default child stdio to UTF-8 without overriding caller settings.
• Start the deployment HTTP server with sys.executable.
• Keep dependency repair on the selected interpreter. Use the virtualenv's own site-packages inside a venv, user installation otherwise, and --break-system-packages only for an externally managed base interpreter. Refresh user-site visibility before rechecking newly installed packages.
• Update agent-facing commands and both READMEs; bump both manifests and the marketplace entry to 0.6.1.

Current head: 8cbb7a779d1a0eec4b85d1d5efc2b6bfb6e2b508, based on the latest fetched upstream main c94279c9a449235fd5991f7903a6c7e4fdc3ab7e (2026-09-29).

Contribution Scope

The earlier changes to maintainer-owned tests/test_video2code_plugin.py have been dropped. The PR now changes only plugins/video2code/ and its entry in marketplace.json. New regression tests live under the plugin directory. No .github/, root tests/, or scripts/ changes are included.

Real Windows Validation

Successful Windows runtime smoke checks out the exact current PR head. The workflow exists only on a separate fork validation branch, not in this PR.

• Windows Server 2025: py -3 resolves to Python 3.14.7; python resolves to Python 3.12.10.
• Three launcher tests pass when started directly with Python, including a real Python child receiving Unicode/spaced arguments and returning exit code 7.
• All 20 plugin tests pass when run through the actual Node launcher, including a real virtualenv/pip subprocess regression test.
• All five Hook scripts run through the launcher from a plugin path containing spaces.
• The inherited sys.executable HTTP server returns the expected body over localhost and is terminated cleanly.
• Validation of 26 plugins and distribution packaging pass.

The first Windows attempt to run the entire plugin suite with bare python -m unittest had seven failures in the existing closeout-hook tests. Those tests spawn Python directly and bypass the launcher's UTF-8 defaults. The successful run retains the direct launcher tests, then starts the full suite via node .../run_python.mjs -m unittest ..., matching the plugin entrypoint environment. Bare-Python Windows execution is not being claimed as passing.

Real ZCode Desktop Validation

Completed on macOS arm64 with ZCode 3.14.4, using a separate smoke workspace, a local marketplace, and generated test media. This is an actual desktop session, not only a JSON manifest check or a standalone MCP client.

1. Added the local marketplace in the desktop GUI and installed video2code 0.6.1. The UI recognized 2 MCP servers, 6 skills, 4 commands, and 4 Hook events.
2. Confirmed both MCP servers connected: runtime exposes 1 tool, video exposes 4 tools. The GUI-selected interpreter is Python 3.14.7, distinct from the terminal's selected Python 3.12.13. Installed the required packages for that interpreter before testing.
3. Through desktop tool calls, ingest_video, still_crops, and clip_video succeeded. Two 320x180 stills and a clip contact sheet were written and inspected.
4. deploy_website served the test static page. The desktop's curl and an independent localhost curl returned HTTP 200 and the expected video2code runtime smoke body. The server response identified Python 3.14.7.
5. The desktop Hook panel recorded SessionStart, both UserPromptSubmit hooks, and Stop execution. PreToolUse was exercised separately in the Windows smoke test; no desktop file-edit path is claimed.
6. The initial four-tool GUI run used 6be786e. After the environment-repair fix in 8cbb7a7, refreshed the installed plugin using ZCode's bundled plugin-update CLI, verified its source files matched the current checkout (excluding Python bytecode), and restarted the app. The launcher and MCP server implementation were unchanged between these heads.
7. On the refreshed installation, ingest_video processed a new filename with no existing ingest output and created a fresh 14,791-byte contact sheet. The installed env_doctor.py --cheap --json, run via the launcher from the desktop session, returned missing: []. No --fix was used during this check.

The smoke test does not cover full website replication, Browser Use recording, optional webapp-cache bootstrapping, or a Windows ZCode GUI session.

Local Checks and Remaining Test Mismatch

• node plugins/video2code/hooks/run_python.mjs -m unittest discover -s plugins/video2code/tests -v: 20 tests passed.
• python scripts/validate.py: 26 plugins validated.
• python scripts/build_dist.py: passed; video2code 0.6.1 includes the launcher.
• git diff --check: clean.
• The unchanged maintainer-owned root suite (python -m unittest discover -s tests) ran 115 tests and reported 3 failures, 19 skipped. The failures are the two MCP-server subtests asserting command == "python3" and the manifest test asserting version == "0.6.0". These assertions need maintainer-side updates for the intentional launcher/version changes. This PR does not claim the root suite is green.

Dependencies and Side Effects

No new third-party dependency is introduced. Node and the existing Python/video dependencies remain prerequisites. Launcher execution only probes and spawns local Python processes. Existing file writes, package installation on explicit --fix, network behavior, and local HTTP-port binding remain documented in the READMEs.

[yu-xin-c]

Added real Windows runtime verification after the initial submission.

The first windows-latest run exposed an additional cp1252 failure when env_check.py printed Chinese output through py -3. Commit 951ed73 now defaults child stdio to UTF-8 while respecting caller overrides.

The follow-up run is green: https://github.com/yu-xin-c/zcode-plugins/actions/runs/36301530991

It exercises the launcher with Chinese and spaced arguments, all five Hooks from a plugin path containing spaces, the inherited sys.executable HTTP server with a real localhost fetch, validation, and packaging.

[panda920]

Thanks for the contribution! This PR changes files that are maintained by the ZCode team and cannot be taken from external contributions: tests/test_video2code_plugin.py. Please drop those changes (plugin content, marketplace.json and docs are welcome) and push again; it will be picked up automatically.

🤖 Copy this prompt into Claude Code / Codex to fix it

You are updating my pull request #47 to github.com/zai-org/zcode-plugins (the ZCode plugin marketplace).
The maintainers' automated intake reported: the PR touches maintainer-owned files

Remove my changes to: tests/test_video2code_plugin.py

Fix it in this repository:
- Only change files under plugins/<my-plugin>/ and my plugin's entry in marketplace.json;
  never modify .github/, scripts/, tests/, .gitignore, .gitattributes or AGENTS.md.
- Follow CONTRIBUTING.md and AGENTS.md: the manifest lives at plugins/<name>/.zcode-plugin/plugin.json,
  its name/version must match marketplace.json, names are kebab-case, keep the required i18n fields.
- Fetch the latest main of zai-org/zcode-plugins and rebase onto it; if marketplace.json conflicts,
  keep every existing entry and re-add mine.
- Run `python scripts/validate.py` until it passes, then force-push my PR branch.

[panda920]

Thanks for the contribution! This PR changes files that are maintained by the ZCode team and cannot be taken from external contributions: tests/test_video2code_plugin.py. Please drop those changes (plugin content, marketplace.json and docs are welcome) and push again; it will be picked up automatically.

🤖 Copy this prompt into Claude Code / Codex to fix it

You are updating my pull request #47 to github.com/zai-org/zcode-plugins (the ZCode plugin marketplace).
The maintainers' automated intake reported: the PR touches maintainer-owned files

Remove my changes to: tests/test_video2code_plugin.py

Fix it in this repository:
- Only change files under plugins/<my-plugin>/ and my plugin's entry in marketplace.json;
  never modify .github/, scripts/, tests/, .gitignore, .gitattributes or AGENTS.md.
- Follow CONTRIBUTING.md and AGENTS.md: the manifest lives at plugins/<name>/.zcode-plugin/plugin.json,
  its name/version must match marketplace.json, names are kebab-case, keep the required i18n fields.
- Fetch the latest main of zai-org/zcode-plugins and rebase onto it; if marketplace.json conflicts,
  keep every existing entry and re-add mine.
- Run `python scripts/validate.py` until it passes, then force-push my PR branch.

[panda920]

✅ Internal validation passed. A ZCode maintainer will review the change next; once merged it is published to the marketplace and this PR is closed automatically.

[panda920]

✅ Internal validation passed. A ZCode maintainer will review the change next; once merged it is published to the marketplace and this PR is closed automatically.

[panda920]

✅ Internal validation passed. A ZCode maintainer will review the change next; once merged it is published to the marketplace and this PR is closed automatically.