code-yeongyu / code-yeongyu/pi-cua-integration

Docs/Windows: clarify supported Python versions and executable configuration

Open
#30 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.