vspdb 0.1.0__tar.gz

vspdb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaustubh Mhatre (^_^)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vspdb-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: vspdb
+Version: 0.1.0
+Summary: Run a Python script under the VS Code debugger from the terminal, halting on the first line.
+Author-email: Kaustubh <kmhatre14@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/kmhatre14/vspdb
+Project-URL: Repository, https://github.com/kmhatre14/vspdb
+Project-URL: Issues, https://github.com/kmhatre14/vspdb/issues
+Keywords: debugpy,vscode,debugger,pdb,debugging,cli,stopOnEntry
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: debugpy>=1.6
+Dynamic: license-file
+
+# vspdb — VS Code pdb for the terminal
+
+Debug any Python script (with arguments) in the VS Code debugger straight from
+the terminal — no hand-written `launch.json`, no `debug.py` wrapper.
+
+```bash
+python -m vspdb my_script.py arg1 arg2
+```
+
+vspdb starts a `debugpy` debug server, gets VS Code to attach, and **halts on the
+first line of your script** — just like `stopOnEntry`. It ships a small VS Code
+helper (installed automatically) so this works with **zero clicks**.
+
+---
+
+## Install — one package, that's it
+
+```bash
+pip install vspdb            # (or: pip install -e .  from this folder)
+```
+
+That's the only thing you install. vspdb ships a tiny VS Code helper extension
+**inside** the package and installs it into VS Code for you on first use. So:
+
+```bash
+python -m vspdb my_script.py 10      # explicit  (or: vspdb my_script.py 10)
+```
+
+The **first** run prints a one-time note that it installed the helper — **reload
+the VS Code window once** (`Ctrl+Shift+P` → "Developer: Reload Window"). After
+that it's fully automatic.
+
+> Tip: install into the same interpreter VS Code uses for the workspace
+> (`Ctrl+Shift+P` → "Python: Select Interpreter") so breakpoints line up. You can
+> also pre-install the helper without running a script: `python -m vspdb --setup`.
+
+---
+
+## How you use it: zero clicks
+
+Once the helper is active (after that one reload), just run scripts — each one
+attaches and halts on its first line, **no debug panel, no F5**:
+
+```bash
+python -m vspdb my_script.py 10
+python -m vspdb another.py --flag
+```
+
+The helper keeps a `debugpy` listener ready in VS Code (one per window, on a
+per-project port) and vspdb connects to the right window automatically.
+
+### Don't want the helper? (no-extension fallback)
+
+Run with `--no-ext` (or set `VSPDB_NO_AUTO_EXTENSION=1`). Then vspdb won't touch
+VS Code; instead it writes two configs to `.vscode/launch.json` and you attach
+manually:
+
+- **vspdb: Listen** — start it once per window (F5), then runs are zero-click.
+- **vspdb: Attach** — vspdb waits; press F5 once per run.
+
+---
+
+## Options
+
+```
+python -m vspdb [options] <script.py> [script args...]
+```
+
+Everything **after** the script name is passed to your script untouched (so your
+script can use `--port`, `--host`, etc. without clashing with vspdb).
+
+| Option | Description |
+| --- | --- |
+| `--port, -p PORT` | Debug port (default: `5678`). |
+| `--host HOST` | Debug host/interface (default: `127.0.0.1`). |
+| `--listen` | Force listen mode (open the port, wait for VS Code). |
+| `--connect` | Force connect mode (attach to a VS Code that is already listening). |
+| `--no-wait` | Don't wait for VS Code; run immediately (disables stop-on-entry). |
+| `--no-stop` | Attach, but don't halt on the first line. |
+| `--no-launch-json` | Don't create/update `.vscode/launch.json`. |
+| `--setup` | (Re)install the bundled VS Code helper extension and exit. |
+| `--no-ext` | Don't auto-install the VS Code helper on this run. |
+
+The `--port` default is read from `.vscode/vspdb.json` (written by the helper) if
+present, else `5678`. Disable auto-install globally with `VSPDB_NO_AUTO_EXTENSION=1`.
+
+Examples:
+
+```bash
+# Different port
+python -m vspdb --port 5690 my_script.py 10
+
+# Your script gets its own --port; vspdb does not consume it
+python -m vspdb server.py --port 8080 --debug
+
+# Run under the debugger but don't stop on entry (rely on your own breakpoints)
+python -m vspdb --no-stop my_script.py 10
+```
+
+---
+
+## How it works
+
+1. Parses `vspdb` options, then treats the first positional as the script and the
+   rest as the script's `argv`.
+2. Installs the bundled VS Code helper into VS Code if it isn't there yet (unless
+   `--no-ext`), and ensures `.vscode/launch.json` has the manual-fallback attach
+   configs (merging, never clobbering, any existing file).
+3. Resolves the port: if `--port` isn't given, it walks up from the script's
+   directory for `.vscode/vspdb.json` (written by the auto-listen extension) so it
+   attaches to the window that owns the script's project — important when several
+   VS Code windows are open. Then it **connects** if that port is being listened
+   on, otherwise **listens** and waits for VS Code.
+4. Once the client is attached, it runs your script as `__main__` with the right
+   `sys.argv`, having injected a `debugpy.breakpoint()` at the first executable
+   line so the debugger halts there. Original line numbers are preserved, so
+   tracebacks stay accurate.
+
+---
+
+## Requirements
+
+- Python 3.8+
+- `debugpy` (installed automatically)
+- VS Code with the Python / Python Debugger extension
+
+## Author
+
+Kaustubh — [kmhatre14@gmail.com](mailto:kmhatre14@gmail.com) · [github.com/kmhatre14](https://github.com/kmhatre14)
+
+## License
+
+[MIT](LICENSE). Built with assistance from Claude Opus 4.8.

vspdb-0.1.0/README.md

@@ -0,0 +1,133 @@
+# vspdb — VS Code pdb for the terminal
+
+Debug any Python script (with arguments) in the VS Code debugger straight from
+the terminal — no hand-written `launch.json`, no `debug.py` wrapper.
+
+```bash
+python -m vspdb my_script.py arg1 arg2
+```
+
+vspdb starts a `debugpy` debug server, gets VS Code to attach, and **halts on the
+first line of your script** — just like `stopOnEntry`. It ships a small VS Code
+helper (installed automatically) so this works with **zero clicks**.
+
+---
+
+## Install — one package, that's it
+
+```bash
+pip install vspdb            # (or: pip install -e .  from this folder)
+```
+
+That's the only thing you install. vspdb ships a tiny VS Code helper extension
+**inside** the package and installs it into VS Code for you on first use. So:
+
+```bash
+python -m vspdb my_script.py 10      # explicit  (or: vspdb my_script.py 10)
+```
+
+The **first** run prints a one-time note that it installed the helper — **reload
+the VS Code window once** (`Ctrl+Shift+P` → "Developer: Reload Window"). After
+that it's fully automatic.
+
+> Tip: install into the same interpreter VS Code uses for the workspace
+> (`Ctrl+Shift+P` → "Python: Select Interpreter") so breakpoints line up. You can
+> also pre-install the helper without running a script: `python -m vspdb --setup`.
+
+---
+
+## How you use it: zero clicks
+
+Once the helper is active (after that one reload), just run scripts — each one
+attaches and halts on its first line, **no debug panel, no F5**:
+
+```bash
+python -m vspdb my_script.py 10
+python -m vspdb another.py --flag
+```
+
+The helper keeps a `debugpy` listener ready in VS Code (one per window, on a
+per-project port) and vspdb connects to the right window automatically.
+
+### Don't want the helper? (no-extension fallback)
+
+Run with `--no-ext` (or set `VSPDB_NO_AUTO_EXTENSION=1`). Then vspdb won't touch
+VS Code; instead it writes two configs to `.vscode/launch.json` and you attach
+manually:
+
+- **vspdb: Listen** — start it once per window (F5), then runs are zero-click.
+- **vspdb: Attach** — vspdb waits; press F5 once per run.
+
+---
+
+## Options
+
+```
+python -m vspdb [options] <script.py> [script args...]
+```
+
+Everything **after** the script name is passed to your script untouched (so your
+script can use `--port`, `--host`, etc. without clashing with vspdb).
+
+| Option | Description |
+| --- | --- |
+| `--port, -p PORT` | Debug port (default: `5678`). |
+| `--host HOST` | Debug host/interface (default: `127.0.0.1`). |
+| `--listen` | Force listen mode (open the port, wait for VS Code). |
+| `--connect` | Force connect mode (attach to a VS Code that is already listening). |
+| `--no-wait` | Don't wait for VS Code; run immediately (disables stop-on-entry). |
+| `--no-stop` | Attach, but don't halt on the first line. |
+| `--no-launch-json` | Don't create/update `.vscode/launch.json`. |
+| `--setup` | (Re)install the bundled VS Code helper extension and exit. |
+| `--no-ext` | Don't auto-install the VS Code helper on this run. |
+
+The `--port` default is read from `.vscode/vspdb.json` (written by the helper) if
+present, else `5678`. Disable auto-install globally with `VSPDB_NO_AUTO_EXTENSION=1`.
+
+Examples:
+
+```bash
+# Different port
+python -m vspdb --port 5690 my_script.py 10
+
+# Your script gets its own --port; vspdb does not consume it
+python -m vspdb server.py --port 8080 --debug
+
+# Run under the debugger but don't stop on entry (rely on your own breakpoints)
+python -m vspdb --no-stop my_script.py 10
+```
+
+---
+
+## How it works
+
+1. Parses `vspdb` options, then treats the first positional as the script and the
+   rest as the script's `argv`.
+2. Installs the bundled VS Code helper into VS Code if it isn't there yet (unless
+   `--no-ext`), and ensures `.vscode/launch.json` has the manual-fallback attach
+   configs (merging, never clobbering, any existing file).
+3. Resolves the port: if `--port` isn't given, it walks up from the script's
+   directory for `.vscode/vspdb.json` (written by the auto-listen extension) so it
+   attaches to the window that owns the script's project — important when several
+   VS Code windows are open. Then it **connects** if that port is being listened
+   on, otherwise **listens** and waits for VS Code.
+4. Once the client is attached, it runs your script as `__main__` with the right
+   `sys.argv`, having injected a `debugpy.breakpoint()` at the first executable
+   line so the debugger halts there. Original line numbers are preserved, so
+   tracebacks stay accurate.
+
+---
+
+## Requirements
+
+- Python 3.8+
+- `debugpy` (installed automatically)
+- VS Code with the Python / Python Debugger extension
+
+## Author
+
+Kaustubh — [kmhatre14@gmail.com](mailto:kmhatre14@gmail.com) · [github.com/kmhatre14](https://github.com/kmhatre14)
+
+## License
+
+[MIT](LICENSE). Built with assistance from Claude Opus 4.8.

vspdb-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vspdb"
+version = "0.1.0"
+description = "Run a Python script under the VS Code debugger from the terminal, halting on the first line."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Kaustubh", email = "kmhatre14@gmail.com" }]
+keywords = ["debugpy", "vscode", "debugger", "pdb", "debugging", "cli", "stopOnEntry"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Debuggers",
+]
+dependencies = ["debugpy>=1.6"]
+
+[project.urls]
+Homepage = "https://github.com/kmhatre14/vspdb"
+Repository = "https://github.com/kmhatre14/vspdb"
+Issues = "https://github.com/kmhatre14/vspdb/issues"
+
+[project.scripts]
+vspdb = "vspdb.cli:main"
+
+[tool.setuptools]
+packages = ["vspdb"]
+
+# Ship the bundled VS Code helper extension inside the wheel so `python -m vspdb`
+# can install it into VS Code automatically.
+[tool.setuptools.package-data]
+vspdb = ["vscode_extension/*"]

vspdb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vspdb-0.1.0/vspdb/__init__.py

@@ -0,0 +1,11 @@
+"""vspdb — run a Python script under the VS Code debugger straight from the terminal.
+
+    python -m vspdb my_script.py arg1 arg2
+
+See :mod:`vspdb.cli` for the implementation.
+"""
+
+from vspdb.cli import main
+
+__all__ = ["main"]
+__version__ = "0.1.0"

vspdb-0.1.0/vspdb/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m vspdb``."""
+
+import sys
+
+from vspdb.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

vspdb-0.1.0/vspdb/cli.py

@@ -0,0 +1,469 @@
+"""vspdb — run a Python script under the VS Code debugger from the terminal.
+
+The goal: instead of hand-editing ``.vscode/launch.json`` every time you want to
+debug a script that takes arguments, you just run::
+
+    python -m vspdb my_script.py arg1 arg2
+
+vspdb starts a ``debugpy`` debug server, makes VS Code attach to it, and halts on
+the first line of *your* script — exactly as if you had set ``stopOnEntry``.
+
+It supports two flows (and picks the right one automatically):
+
+* **Listen flow (zero clicks per run).** Start the auto-generated
+  "vspdb: Listen" configuration in VS Code once. VS Code then listens on the
+  port; every ``python -m vspdb ...`` connects straight to it.
+* **Attach flow (one F5 per run).** If nothing is listening, vspdb opens the
+  port itself and waits. Press F5 and pick "vspdb: Attach" to attach.
+
+Either way the ``.vscode/launch.json`` entries are created for you on first run.
+"""
+
+import argparse
+import ast
+import json
+import os
+import re
+import shutil
+import socket
+import sys
+from pathlib import Path
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 5678
+
+ATTACH_CONFIG_NAME = "vspdb: Attach (connect to running script)"
+LISTEN_CONFIG_NAME = "vspdb: Listen (zero-click, start me first)"
+
+
+# --------------------------------------------------------------------------- #
+# Argument handling
+# --------------------------------------------------------------------------- #
+def _split_argv(argv):
+    """Split our own options from the target script and its arguments.
+
+    Everything up to the first positional token is treated as a vspdb option;
+    that first positional is the script, and everything after it belongs to the
+    script (so the script can freely use ``--port`` etc. without clashing).
+    """
+    value_flags = {"--port", "-p", "--host"}
+    opts = []
+    i = 0
+    while i < len(argv):
+        tok = argv[i]
+        if not tok.startswith("-"):
+            return opts, tok, argv[i + 1:]
+        opts.append(tok)
+        # consume the value of "--port 5678" style flags (but not "--port=5678")
+        if tok in value_flags and "=" not in tok:
+            if i + 1 < len(argv):
+                opts.append(argv[i + 1])
+                i += 2
+                continue
+        i += 1
+    return opts, None, []
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="python -m vspdb",
+        description="Run a Python script under the VS Code debugger, halting on the first line.",
+        usage="python -m vspdb [options] <script.py> [script args...]",
+    )
+    parser.add_argument("--port", "-p", type=int, default=None,
+                        help="Debug port. Default: read from .vscode/vspdb.json if the "
+                             f"auto-listen extension wrote one, else {DEFAULT_PORT}.")
+    parser.add_argument("--host", default=None,
+                        help=f"Debug host/interface (default: {DEFAULT_HOST}).")
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("--listen", action="store_true",
+                      help="Force listen mode: open the port and wait for VS Code to attach.")
+    mode.add_argument("--connect", action="store_true",
+                      help="Force connect mode: attach to a VS Code that is already listening.")
+    parser.add_argument("--no-wait", action="store_true",
+                        help="Don't block waiting for VS Code; run immediately (no stop-on-entry).")
+    parser.add_argument("--no-stop", action="store_true",
+                        help="Attach but do not halt on the first line.")
+    parser.add_argument("--no-launch-json", action="store_true",
+                        help="Do not create/update .vscode/launch.json.")
+    parser.add_argument("--setup", action="store_true",
+                        help="(Re)install the bundled VS Code helper extension and exit.")
+    parser.add_argument("--no-ext", action="store_true",
+                        help="Don't auto-install the VS Code helper extension on this run.")
+    return parser
+
+
+# --------------------------------------------------------------------------- #
+# .vscode/launch.json management
+# --------------------------------------------------------------------------- #
+def _vspdb_configs(host, port):
+    """The two attach configurations vspdb keeps in launch.json."""
+    return [
+        {
+            "name": ATTACH_CONFIG_NAME,
+            "type": "debugpy",
+            "request": "attach",
+            "connect": {"host": host, "port": port},
+            "justMyCode": False,
+        },
+        {
+            "name": LISTEN_CONFIG_NAME,
+            "type": "debugpy",
+            "request": "attach",
+            "listen": {"host": host, "port": port},
+            "justMyCode": False,
+        },
+    ]
+
+
+def _strip_jsonc(text):
+    """Best-effort strip of // and /* */ comments and trailing commas (JSONC)."""
+    out = []
+    i, n = 0, len(text)
+    in_str = False
+    quote = ""
+    while i < n:
+        c = text[i]
+        if in_str:
+            out.append(c)
+            if c == "\\" and i + 1 < n:
+                out.append(text[i + 1])
+                i += 2
+                continue
+            if c == quote:
+                in_str = False
+            i += 1
+            continue
+        if c in ('"', "'"):
+            in_str = True
+            quote = c
+            out.append(c)
+            i += 1
+            continue
+        if c == "/" and i + 1 < n and text[i + 1] == "/":
+            while i < n and text[i] != "\n":
+                i += 1
+            continue
+        if c == "/" and i + 1 < n and text[i + 1] == "*":
+            i += 2
+            while i + 1 < n and not (text[i] == "*" and text[i + 1] == "/"):
+                i += 1
+            i += 2
+            continue
+        out.append(c)
+        i += 1
+    result = "".join(out)
+    return re.sub(r",(\s*[}\]])", r"\1", result)
+
+
+def _load_launch_json(path):
+    raw = path.read_text()
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return json.loads(_strip_jsonc(raw))
+
+
+def ensure_launch_json(root, host, port):
+    """Create/merge vspdb's attach configs into ``<root>/.vscode/launch.json``.
+
+    Existing user configurations are preserved; we only add ours if a config of
+    the same name isn't present. If the file exists but can't be parsed, we leave
+    it untouched and print the configs so the user can add them manually.
+    """
+    vscode_dir = root / ".vscode"
+    path = vscode_dir / "launch.json"
+    data = {"version": "0.2.0", "configurations": []}
+
+    if path.exists():
+        try:
+            parsed = _load_launch_json(path)
+        except Exception:
+            print(f"vspdb: could not parse {path}; not modifying it. "
+                  "Add these configurations manually if needed:", file=sys.stderr)
+            print(json.dumps(_vspdb_configs(host, port), indent=4), file=sys.stderr)
+            return
+        if isinstance(parsed, dict):
+            data = parsed
+        data.setdefault("version", "0.2.0")
+        data.setdefault("configurations", [])
+
+    existing_names = {c.get("name") for c in data["configurations"] if isinstance(c, dict)}
+    added = False
+    for cfg in _vspdb_configs(host, port):
+        if cfg["name"] not in existing_names:
+            data["configurations"].append(cfg)
+            added = True
+
+    if added:
+        vscode_dir.mkdir(exist_ok=True)
+        path.write_text(json.dumps(data, indent=4) + "\n")
+        print(f"vspdb: wrote attach configs to {path}", file=sys.stderr)
+
+
+# --------------------------------------------------------------------------- #
+# Connection handling
+# --------------------------------------------------------------------------- #
+def _extension_source():
+    """Path to the bundled VS Code extension shipped inside the package."""
+    return Path(__file__).resolve().parent / "vscode_extension"
+
+
+def _vscode_extension_bases():
+    """Existing VS Code extensions directories (local + Remote/SSH server)."""
+    home = Path.home()
+    bases = []
+    for rel in (".vscode/extensions", ".vscode-server/extensions", ".vscode-remote/extensions"):
+        p = home / rel
+        if p.is_dir():
+            bases.append(p)
+    return bases
+
+
+def ensure_extension_installed(force=False):
+    """Install the bundled auto-listen extension into VS Code if not already there.
+
+    Returns (newly_installed, folder_name). Best-effort: never raises. Skips
+    cleanly when no VS Code extensions directory exists (e.g. VS Code not used).
+    """
+    src = _extension_source()
+    try:
+        pkg = json.loads((src / "package.json").read_text())
+    except Exception:
+        return False, None
+
+    folder = "{}.{}-{}".format(
+        pkg.get("publisher", "vspdb"), pkg.get("name", "vspdb-autolisten"),
+        pkg.get("version", "0.0.0"))
+    files = ["package.json", "extension.js", "README.md"]
+    newly = False
+
+    bases = _vscode_extension_bases()
+    for base in bases:
+        dest = base / folder
+        # Remove stale/older copies of this extension so VS Code doesn't load two
+        # listeners (e.g. an earlier manual install under a different publisher).
+        for old in base.glob("*vspdb-autolisten*"):
+            if old.resolve() != dest.resolve():
+                shutil.rmtree(old, ignore_errors=True)
+        if force or not dest.exists():
+            try:
+                shutil.rmtree(dest, ignore_errors=True)
+                dest.mkdir(parents=True, exist_ok=True)
+                for name in files:
+                    s = src / name
+                    if s.exists():
+                        shutil.copy2(s, dest / name)
+                newly = True
+            except Exception:
+                pass
+
+    return newly, (folder if bases else None)
+
+
+def discover_endpoint(start_dir, explicit_host, explicit_port):
+    """Resolve (host, port, source) for the debug connection.
+
+    An explicit ``--port`` always wins. Otherwise we walk up from ``start_dir``
+    (the script's directory) looking for ``.vscode/vspdb.json`` — written by the
+    auto-listen VS Code extension — so the run attaches to the window that owns
+    the script's project, not some other open window. Falls back to the defaults.
+    """
+    host, port, source = explicit_host, explicit_port, "default"
+
+    if explicit_port is not None:
+        source = "--port"
+    else:
+        d = start_dir
+        while True:
+            candidate = d / ".vscode" / "vspdb.json"
+            if candidate.is_file():
+                try:
+                    data = json.loads(candidate.read_text())
+                except Exception:
+                    data = {}
+                if data.get("port"):
+                    port = int(data["port"])
+                    if host is None:
+                        host = data.get("host")
+                    source = str(candidate)
+                    break
+            if d.parent == d:
+                break
+            d = d.parent
+
+    return host or DEFAULT_HOST, port if port is not None else DEFAULT_PORT, source
+
+
+def _is_listening(host, port):
+    """True if something is already accepting connections on host:port."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.settimeout(0.3)
+        return sock.connect_ex((host, port)) == 0
+
+
+def _decide_mode(ns, host, port):
+    if ns.listen:
+        return "listen"
+    if ns.connect:
+        return "connect"
+    # Auto: if VS Code is already listening (Listen config running), connect to it.
+    return "connect" if _is_listening(host, port) else "listen"
+
+
+# --------------------------------------------------------------------------- #
+# Running the target with stop-on-entry
+# --------------------------------------------------------------------------- #
+def _set_location(node, lineno, col):
+    for child in ast.walk(node):
+        child.lineno = lineno
+        child.col_offset = col
+        if hasattr(child, "end_lineno"):
+            child.end_lineno = lineno
+        if hasattr(child, "end_col_offset"):
+            child.end_col_offset = col + 1
+
+
+def _compile_with_entry_breakpoint(source, filename):
+    """Compile ``source`` with a ``debugpy.breakpoint()`` injected at the first
+    real statement, so the debugger halts on the first line of the user's code.
+
+    The injected call carries the line number of the first executable statement,
+    so VS Code shows the stop on that line. Original line numbers are preserved,
+    so tracebacks remain accurate.
+    """
+    tree = ast.parse(source, filename)
+    body = tree.body
+    insert_at = 0
+
+    # Skip a leading module docstring.
+    if (body and isinstance(body[0], ast.Expr)
+            and isinstance(getattr(body[0], "value", None), ast.Constant)
+            and isinstance(body[0].value.value, str)):
+        insert_at = 1
+    # Skip __future__ imports (which must remain first).
+    while (insert_at < len(body) and isinstance(body[insert_at], ast.ImportFrom)
+           and body[insert_at].module == "__future__"):
+        insert_at += 1
+
+    if insert_at >= len(body):
+        return compile(tree, filename, "exec")  # nothing to stop on
+
+    anchor = body[insert_at]
+    injected = ast.parse("__import__('debugpy').breakpoint()").body
+    for stmt in injected:
+        _set_location(stmt, anchor.lineno, anchor.col_offset)
+    body[insert_at:insert_at] = injected
+    ast.fix_missing_locations(tree)
+    return compile(tree, filename, "exec")
+
+
+def run_script(script_path, script_args, stop_on_entry):
+    """Execute ``script_path`` as ``__main__`` with ``script_args`` as argv."""
+    source = script_path.read_text()
+    if stop_on_entry:
+        try:
+            code = _compile_with_entry_breakpoint(source, str(script_path))
+        except SyntaxError:
+            code = compile(source, str(script_path), "exec")  # surface real error on exec
+    else:
+        code = compile(source, str(script_path), "exec")
+
+    sys.argv = [str(script_path)] + list(script_args)
+    sys.path.insert(0, str(script_path.parent))
+
+    namespace = {
+        "__name__": "__main__",
+        "__file__": str(script_path),
+        "__package__": None,
+        "__doc__": None,
+        "__loader__": None,
+        "__spec__": None,
+    }
+    exec(code, namespace)
+
+
+# --------------------------------------------------------------------------- #
+# Entry point
+# --------------------------------------------------------------------------- #
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    opts, script, script_args = _split_argv(argv)
+
+    parser = _build_parser()
+    ns = parser.parse_args(opts)
+
+    # `--setup`: just (re)install the VS Code helper and exit. No script needed.
+    if ns.setup:
+        _, folder = ensure_extension_installed(force=True)
+        if folder:
+            print(f"vspdb: installed VS Code helper '{folder}'.", file=sys.stderr)
+            print("vspdb: reload VS Code once (Ctrl+Shift+P -> 'Developer: Reload "
+                  "Window') to activate it.", file=sys.stderr)
+        else:
+            print("vspdb: no VS Code extensions directory found; nothing to install.",
+                  file=sys.stderr)
+        return 0
+
+    if script is None:
+        parser.print_help()
+        return 2
+
+    try:
+        import debugpy
+    except ImportError:
+        print("vspdb requires 'debugpy'. Install it with:\n    pip install debugpy",
+              file=sys.stderr)
+        return 1
+
+    script_path = Path(script).resolve()
+    if not script_path.exists():
+        print(f"vspdb: script not found: {script}", file=sys.stderr)
+        return 1
+
+    # Auto-install the bundled VS Code helper so a single `pip install vspdb` is
+    # all the user needs. Opt out with --no-ext or VSPDB_NO_AUTO_EXTENSION=1.
+    if not ns.no_ext and not os.environ.get("VSPDB_NO_AUTO_EXTENSION"):
+        newly, folder = ensure_extension_installed()
+        if newly and folder:
+            print(f"vspdb: installed its VS Code helper '{folder}'. Reload VS Code once "
+                  "(Ctrl+Shift+P -> 'Developer: Reload Window') to enable zero-click "
+                  "attach.", file=sys.stderr)
+
+    host, port, source = discover_endpoint(script_path.parent, ns.host, ns.port)
+    if source not in ("default", "--port"):
+        print(f"vspdb: using {host}:{port} from {source}", file=sys.stderr)
+
+    if not ns.no_launch_json:
+        ensure_launch_json(Path.cwd(), host, port)
+
+    mode = _decide_mode(ns, host, port)
+    client_attached = False
+
+    if mode == "connect":
+        print(f"vspdb: connecting to VS Code listener at {host}:{port} ...", file=sys.stderr)
+        try:
+            debugpy.connect((host, port))
+            client_attached = True
+            print("vspdb: attached to VS Code.", file=sys.stderr)
+        except Exception as exc:  # noqa: BLE001 - report and fall back to listen
+            print(f"vspdb: could not connect ({exc}); falling back to listen mode.",
+                  file=sys.stderr)
+            mode = "listen"
+
+    if mode == "listen":
+        debugpy.listen((host, port))
+        print(f"vspdb: debug server listening on {host}:{port}", file=sys.stderr)
+        if ns.no_wait:
+            print("vspdb: --no-wait set; running without waiting for VS Code.", file=sys.stderr)
+        else:
+            print(f"vspdb: in VS Code, press F5 and choose '{ATTACH_CONFIG_NAME}'.",
+                  file=sys.stderr)
+            print("vspdb: waiting for the debugger to attach ...", file=sys.stderr)
+            debugpy.wait_for_client()
+            client_attached = True
+            print("vspdb: attached. Running script.", file=sys.stderr)
+
+    stop_on_entry = client_attached and not ns.no_stop
+    run_script(script_path, script_args, stop_on_entry)
+    return 0

vspdb-0.1.0/vspdb/vscode_extension/README.md

@@ -0,0 +1,32 @@
+# vspdb auto-listen (VS Code extension)
+
+The in-editor helper for [vspdb](https://pypi.org/project/vspdb/). It keeps a
+`debugpy` listener running so:
+
+```bash
+python -m vspdb my_script.py 10
+```
+
+attaches the debugger and halts on the first line **with zero clicks**.
+
+> You normally don't install this yourself. The `vspdb` Python package bundles it
+> and installs it into VS Code automatically the first time you run
+> `python -m vspdb` (or `python -m vspdb --setup`). After that, reload the VS Code
+> window once to activate it.
+
+## What it does
+
+- On window open, starts a `debugpy` **attach + listen** session on a port unique
+  to that workspace, and records it in `<workspace>/.vscode/vspdb.json`.
+- Restarts the listener after each session ends, so every run attaches.
+- `python -m vspdb` reads `vspdb.json` and connects to the right window.
+
+## Settings
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `vspdb.host` | `127.0.0.1` | Must match `python -m vspdb --host`. |
+| `vspdb.port` | `5678` | Base port (each window offsets from here). |
+| `vspdb.autoStart` | `true` | Auto-start/restart the listener. |
+
+Command: `Ctrl+Shift+P` → **"vspdb: Start debug listener now"**.

vspdb-0.1.0/vspdb/vscode_extension/extension.js

@@ -0,0 +1,128 @@
+// vspdb auto-listen — keeps a debugpy listener alive so `python -m vspdb`
+// attaches and stops on entry with zero clicks.
+//
+// This extension is installed automatically by the `vspdb` Python package
+// (`python -m vspdb` copies it into VS Code on first run). You normally never
+// install it by hand.
+//
+// Multi-window safe: each VS Code window picks a port derived from its workspace
+// folder (so two projects don't fight over one port) and records the chosen
+// host/port in <workspace>/.vscode/vspdb.json. `python -m vspdb` reads that file
+// to connect to THIS project's window, not some other open window.
+
+const vscode = require("vscode");
+const net = require("net");
+const fs = require("fs");
+const path = require("path");
+
+const CONFIG_NAME = "vspdb auto-listen";
+let restarting = false;
+let currentPort = null;
+
+function settings() {
+  const cfg = vscode.workspace.getConfiguration("vspdb");
+  return {
+    host: cfg.get("host", "127.0.0.1"),
+    basePort: cfg.get("port", 5678),
+    autoStart: cfg.get("autoStart", true),
+  };
+}
+
+function workspaceFolder() {
+  const folders = vscode.workspace.workspaceFolders;
+  return folders && folders.length ? folders[0] : undefined;
+}
+
+// Stable per-workspace starting port so different windows don't all start at the
+// same number (which would race for one port).
+function startingPort(basePort, key) {
+  let h = 0;
+  for (let i = 0; i < key.length; i++) h = (h * 31 + key.charCodeAt(i)) >>> 0;
+  return basePort + (h % 200); // basePort .. basePort+199
+}
+
+function findFreePort(host, from) {
+  return new Promise((resolve) => {
+    let port = from;
+    const tryPort = () => {
+      const srv = net.createServer();
+      srv.once("error", () => {
+        port += 1;
+        if (port > from + 250) return resolve(from);
+        tryPort();
+      });
+      srv.once("listening", () => srv.close(() => resolve(port)));
+      srv.listen(port, host);
+    };
+    tryPort();
+  });
+}
+
+function writePortFile(folder, host, port) {
+  try {
+    const dir = path.join(folder.uri.fsPath, ".vscode");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, "vspdb.json"),
+      JSON.stringify({ host, port }, null, 2) + "\n"
+    );
+  } catch (e) {
+    /* ignore */
+  }
+}
+
+async function startListener(reusePort) {
+  const { host, basePort } = settings();
+  const folder = workspaceFolder();
+  const from = reusePort || startingPort(basePort, folder ? folder.uri.fsPath : "default");
+  const port = await findFreePort(host, from);
+  currentPort = port;
+  if (folder) writePortFile(folder, host, port);
+
+  const config = {
+    name: CONFIG_NAME,
+    type: "debugpy",
+    request: "attach",
+    listen: { host, port },
+    justMyCode: false,
+  };
+  vscode.debug.startDebugging(folder, config).then(
+    (ok) => {
+      if (ok) {
+        vscode.window.setStatusBarMessage(`vspdb: listening on ${host}:${port}`, 4000);
+      } else {
+        vscode.window.setStatusBarMessage(
+          `vspdb: could not start listener on ${host}:${port}`,
+          4000
+        );
+      }
+    },
+    () => {}
+  );
+}
+
+function activate(context) {
+  if (settings().autoStart) startListener();
+
+  context.subscriptions.push(
+    vscode.commands.registerCommand("vspdb.startListener", () => startListener())
+  );
+
+  // After a vspdb session ends (debuggee disconnected), bring the listener back
+  // on the same port so the next terminal run attaches with no clicks.
+  context.subscriptions.push(
+    vscode.debug.onDidTerminateDebugSession((session) => {
+      if (session.name === CONFIG_NAME && settings().autoStart && !restarting) {
+        restarting = true;
+        setTimeout(() => {
+          restarting = false;
+          startListener(currentPort);
+        }, 300);
+      }
+    })
+  );
+}
+
+function deactivate() {}
+
+module.exports = { activate, deactivate };

vspdb-0.1.0/vspdb/vscode_extension/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "vspdb-autolisten",
+  "displayName": "vspdb auto-listen",
+  "description": "Keeps a debugpy listener running so `python -m vspdb` attaches and stops on entry with zero clicks.",
+  "version": "0.1.0",
+  "publisher": "vspdb",
+  "license": "MIT",
+  "engines": {
+    "vscode": "^1.60.0"
+  },
+  "categories": [
+    "Debuggers",
+    "Other"
+  ],
+  "keywords": [
+    "vspdb",
+    "debugpy",
+    "debugger",
+    "attach",
+    "stopOnEntry"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kmhatre14/vspdb.git",
+    "directory": "vspdb/vscode_extension"
+  },
+  "homepage": "https://github.com/kmhatre14/vspdb",
+  "bugs": {
+    "url": "https://github.com/kmhatre14/vspdb/issues"
+  },
+  "activationEvents": [
+    "onStartupFinished"
+  ],
+  "main": "./extension.js",
+  "contributes": {
+    "commands": [
+      {
+        "command": "vspdb.startListener",
+        "title": "vspdb: Start debug listener now"
+      }
+    ],
+    "configuration": {
+      "title": "vspdb",
+      "properties": {
+        "vspdb.host": {
+          "type": "string",
+          "default": "127.0.0.1",
+          "description": "Host/interface the vspdb listener binds to (must match `python -m vspdb --host`)."
+        },
+        "vspdb.port": {
+          "type": "number",
+          "default": 5678,
+          "description": "Base port the vspdb listener uses (must match `python -m vspdb --port`)."
+        },
+        "vspdb.autoStart": {
+          "type": "boolean",
+          "default": true,
+          "description": "Automatically start the listener when a window opens, and restart it after each debug session ends."
+        }
+      }
+    }
+  }
+}

vspdb-0.1.0/vspdb.egg-info/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: vspdb
+Version: 0.1.0
+Summary: Run a Python script under the VS Code debugger from the terminal, halting on the first line.
+Author-email: Kaustubh <kmhatre14@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/kmhatre14/vspdb
+Project-URL: Repository, https://github.com/kmhatre14/vspdb
+Project-URL: Issues, https://github.com/kmhatre14/vspdb/issues
+Keywords: debugpy,vscode,debugger,pdb,debugging,cli,stopOnEntry
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: debugpy>=1.6
+Dynamic: license-file
+
+# vspdb — VS Code pdb for the terminal
+
+Debug any Python script (with arguments) in the VS Code debugger straight from
+the terminal — no hand-written `launch.json`, no `debug.py` wrapper.
+
+```bash
+python -m vspdb my_script.py arg1 arg2
+```
+
+vspdb starts a `debugpy` debug server, gets VS Code to attach, and **halts on the
+first line of your script** — just like `stopOnEntry`. It ships a small VS Code
+helper (installed automatically) so this works with **zero clicks**.
+
+---
+
+## Install — one package, that's it
+
+```bash
+pip install vspdb            # (or: pip install -e .  from this folder)
+```
+
+That's the only thing you install. vspdb ships a tiny VS Code helper extension
+**inside** the package and installs it into VS Code for you on first use. So:
+
+```bash
+python -m vspdb my_script.py 10      # explicit  (or: vspdb my_script.py 10)
+```
+
+The **first** run prints a one-time note that it installed the helper — **reload
+the VS Code window once** (`Ctrl+Shift+P` → "Developer: Reload Window"). After
+that it's fully automatic.
+
+> Tip: install into the same interpreter VS Code uses for the workspace
+> (`Ctrl+Shift+P` → "Python: Select Interpreter") so breakpoints line up. You can
+> also pre-install the helper without running a script: `python -m vspdb --setup`.
+
+---
+
+## How you use it: zero clicks
+
+Once the helper is active (after that one reload), just run scripts — each one
+attaches and halts on its first line, **no debug panel, no F5**:
+
+```bash
+python -m vspdb my_script.py 10
+python -m vspdb another.py --flag
+```
+
+The helper keeps a `debugpy` listener ready in VS Code (one per window, on a
+per-project port) and vspdb connects to the right window automatically.
+
+### Don't want the helper? (no-extension fallback)
+
+Run with `--no-ext` (or set `VSPDB_NO_AUTO_EXTENSION=1`). Then vspdb won't touch
+VS Code; instead it writes two configs to `.vscode/launch.json` and you attach
+manually:
+
+- **vspdb: Listen** — start it once per window (F5), then runs are zero-click.
+- **vspdb: Attach** — vspdb waits; press F5 once per run.
+
+---
+
+## Options
+
+```
+python -m vspdb [options] <script.py> [script args...]
+```
+
+Everything **after** the script name is passed to your script untouched (so your
+script can use `--port`, `--host`, etc. without clashing with vspdb).
+
+| Option | Description |
+| --- | --- |
+| `--port, -p PORT` | Debug port (default: `5678`). |
+| `--host HOST` | Debug host/interface (default: `127.0.0.1`). |
+| `--listen` | Force listen mode (open the port, wait for VS Code). |
+| `--connect` | Force connect mode (attach to a VS Code that is already listening). |
+| `--no-wait` | Don't wait for VS Code; run immediately (disables stop-on-entry). |
+| `--no-stop` | Attach, but don't halt on the first line. |
+| `--no-launch-json` | Don't create/update `.vscode/launch.json`. |
+| `--setup` | (Re)install the bundled VS Code helper extension and exit. |
+| `--no-ext` | Don't auto-install the VS Code helper on this run. |
+
+The `--port` default is read from `.vscode/vspdb.json` (written by the helper) if
+present, else `5678`. Disable auto-install globally with `VSPDB_NO_AUTO_EXTENSION=1`.
+
+Examples:
+
+```bash
+# Different port
+python -m vspdb --port 5690 my_script.py 10
+
+# Your script gets its own --port; vspdb does not consume it
+python -m vspdb server.py --port 8080 --debug
+
+# Run under the debugger but don't stop on entry (rely on your own breakpoints)
+python -m vspdb --no-stop my_script.py 10
+```
+
+---
+
+## How it works
+
+1. Parses `vspdb` options, then treats the first positional as the script and the
+   rest as the script's `argv`.
+2. Installs the bundled VS Code helper into VS Code if it isn't there yet (unless
+   `--no-ext`), and ensures `.vscode/launch.json` has the manual-fallback attach
+   configs (merging, never clobbering, any existing file).
+3. Resolves the port: if `--port` isn't given, it walks up from the script's
+   directory for `.vscode/vspdb.json` (written by the auto-listen extension) so it
+   attaches to the window that owns the script's project — important when several
+   VS Code windows are open. Then it **connects** if that port is being listened
+   on, otherwise **listens** and waits for VS Code.
+4. Once the client is attached, it runs your script as `__main__` with the right
+   `sys.argv`, having injected a `debugpy.breakpoint()` at the first executable
+   line so the debugger halts there. Original line numbers are preserved, so
+   tracebacks stay accurate.
+
+---
+
+## Requirements
+
+- Python 3.8+
+- `debugpy` (installed automatically)
+- VS Code with the Python / Python Debugger extension
+
+## Author
+
+Kaustubh — [kmhatre14@gmail.com](mailto:kmhatre14@gmail.com) · [github.com/kmhatre14](https://github.com/kmhatre14)
+
+## License
+
+[MIT](LICENSE). Built with assistance from Claude Opus 4.8.

vspdb-0.1.0/vspdb.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+vspdb/__init__.py
+vspdb/__main__.py
+vspdb/cli.py
+vspdb.egg-info/PKG-INFO
+vspdb.egg-info/SOURCES.txt
+vspdb.egg-info/dependency_links.txt
+vspdb.egg-info/entry_points.txt
+vspdb.egg-info/requires.txt
+vspdb.egg-info/top_level.txt
+vspdb/vscode_extension/README.md
+vspdb/vscode_extension/extension.js
+vspdb/vscode_extension/package.json

vspdb-0.1.0/vspdb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vspdb-0.1.0/vspdb.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vspdb = vspdb.cli:main

vspdb-0.1.0/vspdb.egg-info/requires.txt

@@ -0,0 +1 @@
+debugpy>=1.6

vspdb-0.1.0/vspdb.egg-info/top_level.txt

@@ -0,0 +1 @@
+vspdb