feat: bundle reqstool with extension via managed venv

[jimisola]

Summary

Currently users must manually install reqstool before the extension works:

pipx install "reqstool[lsp]"

This means the extension fails silently on first install for most users.

Proposed Solution

On activation, automatically install reqstool[lsp] from PyPI into a managed virtual environment stored in VS Code's globalStorageUri. This follows the same pattern used by Microsoft's Python tool extensions (vscode-pylint, vscode-black-formatter, vscode-mypy).

Resolution priority:

1. If reqstool.serverCommand is explicitly user-configured → use it (no change)
2. Otherwise → use managed venv (globalStorageUri/env/bin/reqstool lsp)
3. If venv setup fails → fall back to PATH

Behaviour:

• First activation: show progress notification while pip-installing reqstool[lsp]
• Subsequent activations: venv already exists, starts immediately
• Extension version upgrade: old venv is invalidated and recreated
• Power users: set reqstool.serverCommand to any command to bypass the managed venv entirely

Implementation

• ensureManagedVenv(context) in src/extension.ts: creates venv, runs pip install reqstool[lsp]
• findPython(): tries python3 then python to locate a system interpreter
• resolveServerCommand(managedBin?): respects explicit user config, falls back to managed venv, then PATH
• No bundled wheels — always fetches from PyPI

References

• vscode-pylint — reference implementation of this pattern
• VS Code Python Tools Extension Template

Signed-off-by: jimisola jimisola@users.noreply.github.com

[jimisola]

Plan: Bundle reqstool with the Extension via Managed Venv

Context

Currently users must manually install reqstool before the extension works (pipx install "reqstool[lsp]").
The goal is to ship reqstool inside the .vsix so the extension is self-contained and works
out-of-the-box, while still letting users override the server with reqstool.serverCommand.

The approach follows the Microsoft Python Tools Extension Template pattern (used by vscode-pylint,
vscode-black-formatter, vscode-mypy etc.):

• At activation, create a managed venv in context.globalStorageUri and pip install reqstool[lsp] from PyPI
• Use the managed venv's reqstool as the default server command
• If serverCommand is explicitly user-configured, use that instead (full override)
• No bundled wheels — always fetch from PyPI

---

Architecture

Priority order for server command resolution

1. User-configured serverCommand (via VS Code settings) → use as-is
2. Managed venv (globalStorageUri/env/bin/reqstool lsp) → installed from bundled wheels
3. PATH fallback (reqstool lsp) → if venv creation/install fails

Managed venv lifecycle

• Created once in context.globalStorageUri/env/ using the system Python (python3 / python)
• Invalidated and recreated when extension version changes (stored in context.globalState)
• Installation runs pip install reqstool[lsp] from PyPI on first use
• Shown to user via progress notification during first-time setup

---

Files to Add / Modify

1. package.json — no script changes needed

The build script stays as-is. No bundled wheels, no download step.

6. src/extension.ts — core changes

a) New ensureManagedVenv() function:

async function ensureManagedVenv(
    context: vscode.ExtensionContext
): Promise<string | undefined> {
    const envDir = path.join(context.globalStorageUri.fsPath, 'env')
    const bin    = process.platform === 'win32' ? 'Scripts' : 'bin'
    const exe    = process.platform === 'win32' ? 'reqstool.exe' : 'reqstool'
    const reqstoolBin = path.join(envDir, bin, exe)
    // Invalidate venv on extension version upgrade
    const storedVersion = context.globalState.get<string>('envVersion')
    const currentVersion = context.extension.packageJSON.version as string
    if (storedVersion !== currentVersion && fs.existsSync(envDir)) {
        await fs.promises.rm(envDir, { recursive: true })
    }

    if (!fs.existsSync(reqstoolBin)) {
        // Find a Python interpreter
        const python = await findPython()
        if (!python) { return undefined }

        await vscode.window.withProgress(
            { location: vscode.ProgressLocation.Notification, title: 'reqstool: setting up…' },
            async () => {
                const { execFile } = await import('node:child_process')
                const run = (cmd: string, args: string[]) =>
                    new Promise<void>((res, rej) =>
                        execFile(cmd, args, err => err ? rej(err) : res()))
                // Create venv
                await run(python, ['-m', 'venv', envDir])
                // Install from bundled wheels (offline)
                const pip = path.join(envDir, bin, process.platform === 'win32' ? 'pip.exe' : 'pip')
                await run(pip, ['install', 'reqstool[lsp]'])
            }
        )
        await context.globalState.update('envVersion', currentVersion)
    }

    return fs.existsSync(reqstoolBin) ? reqstoolBin : undefined
}

b) New findPython() helper:

async function findPython(): Promise<string | undefined> {
    const { execFile } = await import('node:child_process')
    for (const candidate of ['python3', 'python']) {
        const found = await new Promise<boolean>(resolve =>
            execFile(candidate, ['--version'], { timeout: 3000 }, err => resolve(!err)))
        if (found) { return candidate }
    }
    return undefined
}

c) Update resolveServerCommand() to accept managed venv path:

function resolveServerCommand(managedBin?: string): [string, string[]] {
    const cfg = vscode.workspace.getConfiguration('reqstool')

    // If user explicitly configured serverCommand, always use it
    const insp = cfg.inspect<string[]>('serverCommand')
    const isUserConfigured = !!(insp?.globalValue || insp?.workspaceValue || insp?.workspaceFolderValue)
    if (isUserConfigured) {
        const cmd = cfg.get<string[]>('serverCommand', ['reqstool', 'lsp']).filter(s => s.trim())
        const [command, ...args] = cmd.length > 0 ? cmd : ['reqstool', 'lsp']
        return [command, args]
    }

    // Use managed venv if available
    if (managedBin) { return [managedBin, ['lsp']] }

    // PATH fallback
    return ['reqstool', ['lsp']]
}

d) Update activate() to wire it together:

export async function activate(context: vscode.ExtensionContext) {
    const cfg = vscode.workspace.getConfiguration('reqstool')

    // Setup managed venv (skipped if user has explicit serverCommand)
    const insp = cfg.inspect<string[]>('serverCommand')
    const isUserConfigured = !!(insp?.globalValue || insp?.workspaceValue || insp?.workspaceFolderValue)
    const managedBin = isUserConfigured ? undefined : await ensureManagedVenv(context)

    const [executable, serverArgs] = resolveServerCommand(managedBin)

    if (!await checkServerInstalled(executable, cfg.get<number>('startupTimeout', 5000))) {
        ...
    }
    ...
}

---

Critical Files

File	Change
src/extension.ts	Add ensureManagedVenv, findPython, update resolveServerCommand + activate

---

Open Questions Before Implementation

1. [lsp] extra: confirm the correct pip extra name — reqstool[lsp] vs something else.
   → Check pyproject.toml / setup.cfg in the reqstool Python package.

---

Verification

1. Fresh VS Code (no reqstool on PATH): open a workspace → progress notification appears → reqstool installed → LSP starts
2. After venv created: check context.globalStorageUri/env/bin/reqstool exists
3. Set reqstool.serverCommand explicitly → managed venv skipped, user command used
4. Extension upgrade (bump version): old venv deleted and recreated on next activation