@adhd/apigen-python-env 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+## 0.2.4 (2026-08-08)
+
+
+### 🩹 Fixes
+
+- **apigen-python-env:** probe monorepo-live python source before co-located dist copy (DEBT-APIGEN-010)
+
+
+### ❤️  Thank You
+
+- pseudosky
+
+## 0.2.3 (2026-08-07)
+
+
+### 🩹 Fixes
+
+- **apigen-cli:** restore 2768 files mass-deleted by 0117eb22 (BUG-APIGEN-052)
+
+- **apigen-python:** parent-death watchdog so Python hosts cannot outlive their spawning process (BUG-APIGEN-053)
+
+
+### ❤️  Thank You
+
+- parity-harness-self-test
+- pseudosky
+
 ## 0.2.2 (2026-07-30)
 
 

package/index.js

@@ -1,10 +1,10 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const D=require("node:fs"),I=require("node:os"),q=require("node:path"),F=require("node:crypto"),h=require("node:child_process");function P(t){const e=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(t){for(const r in t)if(r!=="default"){const i=Object.getOwnPropertyDescriptor(t,r);Object.defineProperty(e,r,i.get?i:{enumerable:!0,get:()=>t[r]})}}return e.default=t,Object.freeze(e)}const n=P(D),b=P(I),o=P(q);function k(t){const e=t??__dirname,r=o.join(e,"python");if(n.existsSync(o.join(r,"apigen_python")))return r;const i=o.resolve(e,"..","..","..","python");if(n.existsSync(o.join(i,"apigen_python")))return i;let a=e;for(let c=0;c<20;c++){const p=o.join(a,"packages","apigen","python");if(n.existsSync(o.join(p,"apigen_python")))return p;const u=o.dirname(a);if(u===a)break;a=u}return i}const H=["python3.13","python3.12","python3.11","python3"],m=[3,11];function J(t){const e=h.spawnSync(t,["-c",'import sys; print(f"{sys.version_info[0]}.{sys.version_info[1]}")'],{encoding:"utf8",timeout:15e3});if(e.status!==0||!e.stdout)return;const[r,i]=e.stdout.trim().split(".").map(Number);if(!(!Number.isFinite(r)||!Number.isFinite(i)))return[r,i]}function M(){for(const t of H){const e=J(t);if(e&&(e[0]>m[0]||e[0]===m[0]&&e[1]>=m[1]))return t}throw new Error(`apigen-python-env: no Python >= ${m.join(".")} found on PATH (tried: ${H.join(", ")}). Install Python ${m.join(".")}+ or set APIGEN_PYTHON to a provisioned interpreter.`)}function Y(t){return process.platform==="win32"?o.join(t,"Scripts","python.exe"):o.join(t,"bin","python3")}function G(t){const e=n.readFileSync(o.join(t,"pyproject.toml"));return F.createHash("sha256").update(e).digest("hex")}function O(t){try{const e=JSON.parse(n.readFileSync(t,"utf8"));if(typeof e.pyprojectHash=="string"&&Array.isArray(e.extras))return e}catch{}}function B(t,e,r){const i=Date.now()+e;for(;;)try{n.mkdirSync(t,{recursive:!1});break}catch{if(Date.now()>i){try{n.rmdirSync(t)}catch{}continue}h.spawnSync(process.execPath,["-e","setTimeout(()=>{}, 250)"],{timeout:5e3})}try{return r()}finally{try{n.rmdirSync(t)}catch{}}}function V(t={}){const e=k(),r=process.env.APIGEN_PYTHON;if(r){if(!n.existsSync(r))throw new Error(`apigen-python-env: APIGEN_PYTHON points to a missing file: ${r}`);return{python:r,venvDir:"",pythonPkgDir:e}}const i=[...new Set(t.extras??[])].sort(),a=t.envHome??process.env.APIGEN_PYENV_HOME??o.join(b.homedir(),".adhd","apigen"),c=o.join(a,"pyvenv"),p=o.join(c,".apigen-stamp"),u=G(e),y=Y(c),l=()=>{if(!n.existsSync(y))return!1;const s=O(p);return!s||s.pyprojectHash!==u?!1:i.every(d=>s.extras.includes(d))};if(l())return{python:y,venvDir:c,pythonPkgDir:e};n.mkdirSync(a,{recursive:!0});const v=o.join(a,"pyvenv.lock"),w=t.lockTimeoutMs??3e5;return B(v,w,()=>{if(l())return{python:y,venvDir:c,pythonPkgDir:e};const s=O(p),d=[...new Set([...(s==null?void 0:s.extras)??[],...i])].sort();n.rmSync(c,{recursive:!0,force:!0});const _=M(),j=h.spawnSync(_,["-m","venv",c],{encoding:"utf8",timeout:12e4});if(j.status!==0)throw new Error(`apigen-python-env: "${_} -m venv" failed (exit ${j.status}):
-${j.stderr}`);const x=o.join(e,"build");n.existsSync(x)&&n.rmSync(x,{recursive:!0,force:!0});for(const f of n.readdirSync(e))f.endsWith(".egg-info")&&n.rmSync(o.join(e,f),{recursive:!0,force:!0});const S=n.mkdtempSync(o.join(b.tmpdir(),"apigen-python-wheel-"));try{const f=h.spawnSync(y,["-m","pip","wheel","--no-deps","--wheel-dir",S,e],{encoding:"utf8",timeout:6e5});if(f.status!==0)throw new Error(`apigen-python-env: pip wheel failed (exit ${f.status}):
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const D=require("node:fs"),I=require("node:os"),q=require("node:path"),F=require("node:crypto"),h=require("node:child_process");function P(t){const e=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(t){for(const n in t)if(n!=="default"){const i=Object.getOwnPropertyDescriptor(t,n);Object.defineProperty(e,n,i.get?i:{enumerable:!0,get:()=>t[n]})}}return e.default=t,Object.freeze(e)}const r=P(D),b=P(I),o=P(q);function k(t){const e=t??__dirname,n=o.resolve(e,"..","..","..","python");if(r.existsSync(o.join(n,"apigen_python")))return n;const i=o.join(e,"python");if(r.existsSync(o.join(i,"apigen_python")))return i;let a=e;for(let c=0;c<20;c++){const p=o.join(a,"packages","apigen","python");if(r.existsSync(o.join(p,"apigen_python")))return p;const u=o.dirname(a);if(u===a)break;a=u}return n}const H=["python3.13","python3.12","python3.11","python3"],m=[3,11];function J(t){const e=h.spawnSync(t,["-c",'import sys; print(f"{sys.version_info[0]}.{sys.version_info[1]}")'],{encoding:"utf8",timeout:15e3});if(e.status!==0||!e.stdout)return;const[n,i]=e.stdout.trim().split(".").map(Number);if(!(!Number.isFinite(n)||!Number.isFinite(i)))return[n,i]}function M(){for(const t of H){const e=J(t);if(e&&(e[0]>m[0]||e[0]===m[0]&&e[1]>=m[1]))return t}throw new Error(`apigen-python-env: no Python >= ${m.join(".")} found on PATH (tried: ${H.join(", ")}). Install Python ${m.join(".")}+ or set APIGEN_PYTHON to a provisioned interpreter.`)}function Y(t){return process.platform==="win32"?o.join(t,"Scripts","python.exe"):o.join(t,"bin","python3")}function G(t){const e=r.readFileSync(o.join(t,"pyproject.toml"));return F.createHash("sha256").update(e).digest("hex")}function O(t){try{const e=JSON.parse(r.readFileSync(t,"utf8"));if(typeof e.pyprojectHash=="string"&&Array.isArray(e.extras))return e}catch{}}function B(t,e,n){const i=Date.now()+e;for(;;)try{r.mkdirSync(t,{recursive:!1});break}catch{if(Date.now()>i){try{r.rmdirSync(t)}catch{}continue}h.spawnSync(process.execPath,["-e","setTimeout(()=>{}, 250)"],{timeout:5e3})}try{return n()}finally{try{r.rmdirSync(t)}catch{}}}function V(t={}){const e=k(),n=process.env.APIGEN_PYTHON;if(n){if(!r.existsSync(n))throw new Error(`apigen-python-env: APIGEN_PYTHON points to a missing file: ${n}`);return{python:n,venvDir:"",pythonPkgDir:e}}const i=[...new Set(t.extras??[])].sort(),a=t.envHome??process.env.APIGEN_PYENV_HOME??o.join(b.homedir(),".adhd","apigen"),c=o.join(a,"pyvenv"),p=o.join(c,".apigen-stamp"),u=G(e),y=Y(c),l=()=>{if(!r.existsSync(y))return!1;const s=O(p);return!s||s.pyprojectHash!==u?!1:i.every(d=>s.extras.includes(d))};if(l())return{python:y,venvDir:c,pythonPkgDir:e};r.mkdirSync(a,{recursive:!0});const v=o.join(a,"pyvenv.lock"),w=t.lockTimeoutMs??3e5;return B(v,w,()=>{if(l())return{python:y,venvDir:c,pythonPkgDir:e};const s=O(p),d=[...new Set([...(s==null?void 0:s.extras)??[],...i])].sort();r.rmSync(c,{recursive:!0,force:!0});const _=M(),j=h.spawnSync(_,["-m","venv",c],{encoding:"utf8",timeout:12e4});if(j.status!==0)throw new Error(`apigen-python-env: "${_} -m venv" failed (exit ${j.status}):
+${j.stderr}`);const x=o.join(e,"build");r.existsSync(x)&&r.rmSync(x,{recursive:!0,force:!0});for(const f of r.readdirSync(e))f.endsWith(".egg-info")&&r.rmSync(o.join(e,f),{recursive:!0,force:!0});const S=r.mkdtempSync(o.join(b.tmpdir(),"apigen-python-wheel-"));try{const f=h.spawnSync(y,["-m","pip","wheel","--no-deps","--wheel-dir",S,e],{encoding:"utf8",timeout:6e5});if(f.status!==0)throw new Error(`apigen-python-env: pip wheel failed (exit ${f.status}):
 ${f.stderr}
 stdout:
-${f.stdout}`);const E=n.readdirSync(S).filter(A=>A.endsWith(".whl"));if(E.length===0)throw new Error("apigen-python-env: pip wheel produced no .whl file");const $=o.join(S,E[0]),N=d.length?`${$}[${d.join(",")}]`:$,g=h.spawnSync(y,["-m","pip","install","--quiet","--disable-pip-version-check",N],{encoding:"utf8",timeout:6e5});if(g.status!==0)throw new Error(`apigen-python-env: pip install "${N}" failed (exit ${g.status}):
+${f.stdout}`);const E=r.readdirSync(S).filter(A=>A.endsWith(".whl"));if(E.length===0)throw new Error("apigen-python-env: pip wheel produced no .whl file");const $=o.join(S,E[0]),N=d.length?`${$}[${d.join(",")}]`:$,g=h.spawnSync(y,["-m","pip","install","--quiet","--disable-pip-version-check",N],{encoding:"utf8",timeout:6e5});if(g.status!==0)throw new Error(`apigen-python-env: pip install "${N}" failed (exit ${g.status}):
 ${g.stderr}
 stdout:
-${g.stdout}`)}finally{n.rmSync(S,{recursive:!0,force:!0})}const T={pyprojectHash:u,extras:d};return n.writeFileSync(p,JSON.stringify(T)),{python:y,venvDir:c,pythonPkgDir:e}})}function L(t,e,r,i,a){return new Promise((c,p)=>{var v,w;const u=h.spawn(t,["-m","apigen_python.extractor",r,"--namespace",i,"--emit-json"],{cwd:e,env:{...process.env,PYTHONPATH:e},stdio:["ignore","pipe","pipe"]});let y="",l="";(v=u.stdout)==null||v.on("data",s=>{y+=s.toString("utf8")}),(w=u.stderr)==null||w.on("data",s=>{l+=s.toString("utf8")}),u.on("error",p),u.on("exit",s=>{if(s!==0){p(new Error(`${a}: extractor --emit-json exited with code ${s}:
+${g.stdout}`)}finally{r.rmSync(S,{recursive:!0,force:!0})}const T={pyprojectHash:u,extras:d};return r.writeFileSync(p,JSON.stringify(T)),{python:y,venvDir:c,pythonPkgDir:e}})}function L(t,e,n,i,a){return new Promise((c,p)=>{var v,w;const u=h.spawn(t,["-m","apigen_python.extractor",n,"--namespace",i,"--emit-json"],{cwd:e,env:{...process.env,PYTHONPATH:e},stdio:["ignore","pipe","pipe"]});let y="",l="";(v=u.stdout)==null||v.on("data",s=>{y+=s.toString("utf8")}),(w=u.stderr)==null||w.on("data",s=>{l+=s.toString("utf8")}),u.on("error",p),u.on("exit",s=>{if(s!==0){p(new Error(`${a}: extractor --emit-json exited with code ${s}:
 ${l}`));return}try{c(JSON.parse(y))}catch(d){p(new Error(`${a}: extractor --emit-json produced invalid JSON (${d.message}):
 ${y}`))}})})}exports.ensurePythonEnv=V;exports.resolvePythonPkgDir=k;exports.runExtractorEmitJson=L;

package/index.mjs

@@ -4,10 +4,10 @@ import * as r from "node:path";
 import { createHash as T } from "node:crypto";
 import { spawnSync as l, spawn as I } from "node:child_process";
 function O(e) {
-  const t = e ?? __dirname, o = r.join(t, "python");
+  const t = e ?? __dirname, o = r.resolve(t, "..", "..", "..", "python");
   if (n.existsSync(r.join(o, "apigen_python")))
     return o;
-  const s = r.resolve(t, "..", "..", "..", "python");
+  const s = r.join(t, "python");
   if (n.existsSync(r.join(s, "apigen_python")))
     return s;
   let a = t;
@@ -20,7 +20,7 @@ function O(e) {
       break;
     a = u;
   }
-  return s;
+  return o;
 }
 const _ = ["python3.13", "python3.12", "python3.11", "python3"], m = [3, 11];
 function D(e) {

package/lib/python-env.d.ts

@@ -27,17 +27,27 @@ export interface IEnsurePythonEnvOptions {
  * Locate the directory containing the `apigen_python` package sources.
  *
  * Probed in order:
- *   1. Co-located (SHIPPED) copy: `<this file's dir>/python`. This package's
- *      build copies `packages/apigen/python/apigen_python/**` into its own
- *      `dist/python/apigen_python/`, so for a consumer installed from npm
- *      OUTSIDE the monorepo (where __dirname is `node_modules/@adhd/
- *      apigen-python-env/dist`), the sources are bundled right next to the
- *      compiled code. This MUST be probed first so published consumers never
- *      fall through to a monorepo-only path that doesn't exist for them.
- *   2. Monorepo source (dev-time fallback): `<this file>/../../../python`
- *      (source layout: packages/apigen/python-env/src/lib → packages/apigen/
- *      python). Keeps vitest/ts-node runs resolving the LIVE source instead
- *      of the copied snapshot.
+ *   1. Monorepo source (LIVE, preferred when present): `<this file>/../../
+ *      ../python` (source layout: packages/apigen/python-env/src/lib →
+ *      packages/apigen/python; from a build, `dist/lib` → `packages/apigen/
+ *      python` by the same three-levels-up relationship). When both this
+ *      AND the co-located dist copy below exist — i.e. running inside the
+ *      monorepo, built or not — this MUST win. `dist/python` is a
+ *      point-in-time copy made by this package's build (vite.config.ts
+ *      `copyPythonPackagePlugin`); it goes stale the moment someone edits
+ *      `packages/apigen/python` without rebuilding, and code run outside
+ *      Nx's task graph (`npx vitest run` directly, bypassing the `test`
+ *      target's `dependsOn: ["build"]`) has no mechanism to refresh it. Prior
+ *      ordering probed the dist copy FIRST, so any monorepo dev/test
+ *      invocation that happened to have a `dist/python` lying around from a
+ *      previous build silently exercised stale Python source with no
+ *      indication the live edit was never observed — see
+ *      DEBT-APIGEN-010. Source must win whenever it's reachable.
+ *   2. Co-located (SHIPPED) copy: `<this file's dir>/python`. For a
+ *      consumer installed from npm OUTSIDE the monorepo (where __dirname is
+ *      `node_modules/@adhd/apigen-python-env/dist`), step 1's monorepo-
+ *      relative path doesn't exist, so this bundled-alongside-the-compiled-
+ *      code copy is the only candidate and is used.
  *   3. Walk up from __dirname looking for `packages/apigen/python` (covers
  *      the vite-bundled CLI, where __dirname is the bundle output dir).
  * (Shared by py-grpc / py-flask — previously duplicated in each plugin.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhd/apigen-python-env",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "main": "./index.js",
   "module": "./index.mjs",
   "types": "./index.d.ts",
@@ -12,7 +12,7 @@
     "provisioning"
   ],
   "dependencies": {
-    "@adhd/apigen-core-client": "^0.2.2"
+    "@adhd/apigen-core-client": "^0.3.0"
   },
   "publishConfig": {
     "access": "public"

package/python/apigen_python/flask_server.py

@@ -93,6 +93,7 @@ if str(_THIS_DIR) not in sys.path:
     sys.path.insert(0, str(_THIS_DIR))
 
 from apigen_python.errors import ApiError, HTTP_STATUS  # noqa: E402
+from apigen_python.parent_watchdog import start_parent_death_watchdog  # noqa: E402
 from apigen_python.runtime import HostRequest, Runtime  # noqa: E402
 from apigen_python.validator import validate, ValidationError  # noqa: E402
 
@@ -946,6 +947,10 @@ class ApigenFlaskServer:
         self.start()
         # §13.1 readiness signal — TS launcher polls for this line on stdout
         print(json.dumps({"ready": True, "port": self._port}), flush=True)
+        # BUG-APIGEN-053: self-terminate if the TS parent process dies
+        # outright (SIGKILL/OOM-kill/crash) without ever sending a signal —
+        # see apigen_python.parent_watchdog's module docstring.
+        start_parent_death_watchdog()
         try:
             # Block main thread while the daemon thread serves
             if self._thread is not None:

package/python/apigen_python/grpc_server.py

@@ -119,6 +119,7 @@ if str(_THIS_DIR) not in sys.path:
     sys.path.insert(0, str(_THIS_DIR))
 
 from apigen_python.errors import ApiError, GRPC_CODE  # noqa: E402
+from apigen_python.parent_watchdog import start_parent_death_watchdog  # noqa: E402
 from apigen_python.runtime import HostRequest, Runtime  # noqa: E402
 from apigen_python.validator import validate, ValidationError  # noqa: E402
 
@@ -842,6 +843,11 @@ class ApigenGrpcServer:
         _signal.signal(_signal.SIGTERM, _sig_handler)
         _signal.signal(_signal.SIGINT, _sig_handler)
 
+        # BUG-APIGEN-053: self-terminate if the TS parent process dies
+        # outright (SIGKILL/OOM-kill/crash) without ever sending a signal —
+        # see apigen_python.parent_watchdog's module docstring.
+        start_parent_death_watchdog()
+
         try:
             stop_event.wait()
         except KeyboardInterrupt:

package/python/apigen_python/parent_watchdog.py

@@ -0,0 +1,79 @@
+"""Parent-death watchdog (BUG-APIGEN-053).
+
+Both of apigen_python's long-running servers (flask_server.py, grpc_server.py)
+are spawned by a TS parent (apigen-plugin-py-flask/-py-grpc's `run()`) with
+stdio `['pipe', 'pipe', 'pipe']`. The only teardown path either plugin wires
+is `input.signal`'s 'abort' handler, which sends SIGTERM to the child -- but
+that requires the TS parent process to still be alive to fire it. When the
+parent instead dies outright (SIGKILL, OOM-kill, CI job cancellation, an
+uncaught crash before its abort handler runs), no signal is ever sent,
+`serve_forever()`'s wait/join call never wakes up, and the process reparents
+to launchd (ppid=1), holding its listening socket forever -- this is
+BUG-APIGEN-053's exact, measured failure mode (132 orphaned processes / 137
+listening sockets, ~23h old).
+
+Neither Python's default SIGTERM disposition (fires only when someone SENDS
+SIGTERM) nor a PR_SET_PDEATHSIG-style mechanism (Linux-only; unavailable on
+macOS, where this failure was measured) closes this gap. The portable fix:
+the child's stdin is a pipe whose write end is owned by the parent process.
+The OS closes that write end the INSTANT the parent dies, for ANY reason,
+including SIGKILL -- no cooperation from the dying parent required. A
+background thread blocked reading stdin sees EOF at exactly that moment.
+"""
+from __future__ import annotations
+
+import os
+import threading
+from typing import Callable, Optional
+
+
+def start_parent_death_watchdog(
+    on_parent_death: Optional[Callable[[], None]] = None,
+) -> threading.Thread:
+    """Starts a daemon thread blocked reading stdin (fd 0) via a raw
+    `os.read()` -- see the in-loop comment for why not `sys.stdin`. On EOF
+    (the parent's write end of the stdin pipe closed -- i.e. the parent
+    died, for ANY reason including SIGKILL), calls `on_parent_death`.
+
+    Default `on_parent_death` is `os._exit(0)` -- an immediate hard process
+    exit. That is deliberate and safe here: there is no client left to serve
+    a graceful response to (the process that spawned this server is gone),
+    and the OS reclaims the listening socket on process exit regardless of
+    whether `Server.stop()`/`shutdown()` ran first.
+
+    Returns the started (daemon=True) Thread so a caller/test can join it.
+    """
+    callback = on_parent_death or (lambda: os._exit(0))
+
+    def _watch() -> None:
+        try:
+            while True:
+                # Deliberately `os.read(0, ...)` (a raw fd read via the
+                # syscall wrapper), NOT `sys.stdin.buffer.read(...)`: the
+                # buffered form takes CPython's internal BufferedReader lock
+                # for the duration of the blocking read. `grpc_server.py`
+                # handles SIGTERM/SIGINT gracefully (its own handler sets an
+                # Event and `_main()` returns normally, reaching an ORDERLY
+                # `Py_Finalize()`) -- and finalization tries to flush/close
+                # `sys.stdin`, which cannot acquire that same lock while this
+                # daemon thread still holds it, producing a real, reproduced
+                # `Fatal Python error: _enter_buffered_busy: could not
+                # acquire lock ... at interpreter shutdown` on every single
+                # graceful teardown. A raw `os.read()` never touches that
+                # lock, so it can be safely abandoned mid-call when the
+                # interpreter exits either gracefully or via `os._exit()`.
+                chunk = os.read(0, 4096)
+                if not chunk:
+                    break
+        except OSError:
+            # stdin fd already closed/invalid (e.g. a harness that doesn't
+            # wire a pipe, or redirects fd 0 elsewhere) -- nothing to watch;
+            # exit the thread quietly.
+            return
+        callback()
+
+    thread = threading.Thread(
+        target=_watch, name="apigen-parent-death-watchdog", daemon=True
+    )
+    thread.start()
+    return thread