code-yeongyu / code-yeongyu/pi-cua-integration
Docs/Windows: clarify supported Python versions and executable configuration
- Dominant language
- TypeScript
- Stars
- 6
- Forks
- 3
- PR merge metrics
- No merged PRs in 30d
Description
## Scope clarification
The initial environment had the extension installed but did **not** yet have the required Python `cua` package, so it did not fully satisfy the README Quick start instructions. After installing the dependency with a supported interpreter and configuring its executable, the daemon started normally.
This issue is therefore limited to the documentation and diagnostics gaps found while completing the documented setup on Windows. It is not claiming that the extension should work without `pip install cua`.
## Documentation gap
The current Quick start says:
```bash
pi install npm:pi-cua-integration
pip install cua
```
The configuration reference documents `python.executable` with a default of `python3`, but it does not state:
- Current `cua==0.1.6` requires Python `>=3.12,<3.14`.
- On Python 3.11, pip can select the historical `cua==0.1.0` release, whose import surface does not match the daemon's `import cua`.
- Python 3.14 is outside the current supported range.
- On Windows, `python3` commonly resolves to the Microsoft Store execution alias or is unavailable, which can produce child-process exit code `9009`.
- Windows users may need to set `python.executable` to the full path of a Python 3.12 or 3.13 executable.
## Reproduction
### Missing/default executable
1. On Windows, install the extension and the Cua SDK.
2. Leave `python.executable` at its default.
3. If `python3` resolves to the Store alias, reload the extension.
4. Observe:
```text
Failed to start Python daemon: cua python daemon exited (code=9009)
```
### Unsupported interpreter
With Python 3.11:
```powershell
python -m pip install cua
python -c "import cua"
```
Pip can install the compatible historical release, but the expected `cua` module is unavailable.
## Expected documentation and diagnostics
A Windows user following Quick start should be able to identify:
1. the supported Python versions;
2. the interpreter into which `cua` must be installed;
3. the matching `python.executable` configuration;
4. a clear remediation when the executable cannot be launched.
## Suggested fix
1. Add prerequisites to Quick start:
```text
Python >=3.12,<3.14 (3.12 or 3.13)
```
2. Provide a Windows-specific installation example using one exact interpreter:
```powershell
C:\Path\To\Python313\python.exe -m pip install --upgrade cua
```
3. Show the matching global configuration:
```json
{
"python": {
"executable": "C:/Path/To/Python313/python.exe"
}
}
```
4. When daemon spawn fails with `ENOENT` or Windows exit code `9009`, include an actionable message pointing to `python.executable`.
5. After startup, report the configured interpreter version and distinguish:
- missing `cua`;
- incompatible historical distribution;
- unsupported Python version.
## Acceptance criteria
- Quick start explicitly documents Python `>=3.12,<3.14`.
- Windows setup shows installation and configuration using the same interpreter.
- Exit code `9009` produces an actionable `python.executable` remediation.
- The issue does not imply support for an environment where the required `cua` dependency was never installed.
Contributor guide
Research direction
Start with the Quick start and configuration reference, then locate the daemon startup diagnostic entry point. Document Python >=3.12,<3.14, a Windows installation command and matching python.executable setting, and make failures for ENOENT or exit code 9009 actionable. Done means the documented interpreter, dependency, configuration, and remediation are clear.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, typescript
- Domain
- developer-experience, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 70/100