@adhd/apigen-python-env 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @adhd/apigen-python-env
+
+Python host provisioning for apigen's `py-*` plugins.
+
+## The problem it solves
+
+`py-grpc` / `py-flask` spawn a Python process (`apigen_python.grpc_server` /
+`flask_server`). Those servers need `grpcio` + `grpcio-reflection` — deps that
+are **declared in `packages/apigen/python/pyproject.toml`** (the `grpc` extra),
+but that used to be expected on whatever `python3` happened to be on PATH.
+On any machine without them, `apigen run/serve --type py-grpc` died on import.
+
+This package makes the Python packaging the single source of truth: it
+provisions a **managed venv** by `pip install`-ing `apigen-python` (with the
+requested extras) from its own `pyproject.toml`, and hands back that venv's
+interpreter.
+
+## API
+
+```ts
+import { ensurePythonEnv, resolvePythonPkgDir } from '@adhd/apigen-python-env'
+
+const { python, venvDir, pythonPkgDir } = ensurePythonEnv({ extras: ['grpc'] })
+// spawn(python, ['-m', 'apigen_python.grpc_server', ...], { env: { PYTHONPATH: pythonPkgDir } })
+```
+
+- **`ensurePythonEnv({ extras })`** — returns the interpreter to spawn.
+  Resolution order:
+  1. `APIGEN_PYTHON` env var (explicit override — CI images, power users).
+  2. Managed venv at `~/.adhd/apigen/pyvenv` — created on first use, refreshed
+     automatically when `pyproject.toml` (or the requested extras) change
+     (content-hash stamp file). Creation is cross-process locked, so
+     concurrent `serve` children don't double-provision.
+- **`resolvePythonPkgDir()`** — locates the `apigen_python` sources (shared by
+  both py plugins; also exported for tools like the conformance gate).
+
+Environment knobs:
+
+| Var | Effect |
+| --- | ------ |
+| `APIGEN_PYTHON` | Skip the managed venv; use this interpreter as-is. |
+| `APIGEN_PYENV_HOME` | Relocate the managed-venv root (tests point it at `tmp/`). |
+
+## Failure mode
+
+Loud, never silent: if no Python ≥ 3.11 is on PATH or `pip install` fails, the
+error says exactly what to install. The plugins no longer fall back to a bare
+`python3` that may be missing its deps.
+
+## Consumers
+
+- `@adhd/apigen-plugin-py-grpc` — `ensurePythonEnv({ extras: ['grpc'] })`
+- `@adhd/apigen-plugin-py-flask` — `ensurePythonEnv()` (stdlib HTTP fallback needs no extras)
+- `apigen serve` — pre-provisions before spawning Python hosts so child ready
+  timeouts don't absorb a first-time venv build, and pins children via
+  `APIGEN_PYTHON`.

package/index.d.ts

@@ -0,0 +1,2 @@
+export { ensurePythonEnv, resolvePythonPkgDir } from './lib/python-env';
+export type { IPythonEnv, IEnsurePythonEnvOptions } from './lib/python-env';

package/index.js

@@ -0,0 +1,8 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const T=require("node:fs"),I=require("node:os"),q=require("node:path"),F=require("node:crypto"),h=require("node:child_process");function S(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=S(T),E=S(I),o=S(q);function k(t){const e=t??__dirname,r=o.resolve(e,"..","..","..","python");if(n.existsSync(o.join(r,"apigen_python")))return r;let i=e;for(let p=0;p<20;p++){const s=o.join(i,"packages","apigen","python");if(n.existsSync(o.join(s,"apigen_python")))return s;const u=o.dirname(i);if(u===i)break;i=u}return r}const N=["python3.13","python3.12","python3.11","python3"],d=[3,11];function M(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 Y(){for(const t of N){const e=M(t);if(e&&(e[0]>d[0]||e[0]===d[0]&&e[1]>=d[1]))return t}throw new Error(`apigen-python-env: no Python >= ${d.join(".")} found on PATH (tried: ${N.join(", ")}). Install Python ${d.join(".")}+ or set APIGEN_PYTHON to a provisioned interpreter.`)}function G(t){return process.platform==="win32"?o.join(t,"Scripts","python.exe"):o.join(t,"bin","python3")}function B(t){const e=n.readFileSync(o.join(t,"pyproject.toml"));return F.createHash("sha256").update(e).digest("hex")}function $(t){try{const e=JSON.parse(n.readFileSync(t,"utf8"));if(typeof e.pyprojectHash=="string"&&Array.isArray(e.extras))return e}catch{}}function V(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 J(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(),p=t.envHome??process.env.APIGEN_PYENV_HOME??o.join(E.homedir(),".adhd","apigen"),s=o.join(p,"pyvenv"),u=o.join(s,".apigen-stamp"),g=B(e),y=G(s),w=()=>{if(!n.existsSync(y))return!1;const c=$(u);return!c||c.pyprojectHash!==g?!1:i.every(f=>c.extras.includes(f))};if(w())return{python:y,venvDir:s,pythonPkgDir:e};n.mkdirSync(p,{recursive:!0});const H=o.join(p,"pyvenv.lock"),D=t.lockTimeoutMs??3e5;return V(H,D,()=>{if(w())return{python:y,venvDir:s,pythonPkgDir:e};const c=$(u),f=[...new Set([...(c==null?void 0:c.extras)??[],...i])].sort();n.rmSync(s,{recursive:!0,force:!0});const j=Y(),v=h.spawnSync(j,["-m","venv",s],{encoding:"utf8",timeout:12e4});if(v.status!==0)throw new Error(`apigen-python-env: "${j} -m venv" failed (exit ${v.status}):
+${v.stderr}`);const P=o.join(e,"build");n.existsSync(P)&&n.rmSync(P,{recursive:!0,force:!0});for(const a of n.readdirSync(e))a.endsWith(".egg-info")&&n.rmSync(o.join(e,a),{recursive:!0,force:!0});const l=n.mkdtempSync(o.join(E.tmpdir(),"apigen-python-wheel-"));try{const a=h.spawnSync(y,["-m","pip","wheel","--no-deps","--wheel-dir",l,e],{encoding:"utf8",timeout:6e5});if(a.status!==0)throw new Error(`apigen-python-env: pip wheel failed (exit ${a.status}):
+${a.stderr}
+stdout:
+${a.stdout}`);const _=n.readdirSync(l).filter(A=>A.endsWith(".whl"));if(_.length===0)throw new Error("apigen-python-env: pip wheel produced no .whl file");const b=o.join(l,_[0]),x=f.length?`${b}[${f.join(",")}]`:b,m=h.spawnSync(y,["-m","pip","install","--quiet","--disable-pip-version-check",x],{encoding:"utf8",timeout:6e5});if(m.status!==0)throw new Error(`apigen-python-env: pip install "${x}" failed (exit ${m.status}):
+${m.stderr}
+stdout:
+${m.stdout}`)}finally{n.rmSync(l,{recursive:!0,force:!0})}const O={pyprojectHash:g,extras:f};return n.writeFileSync(u,JSON.stringify(O)),{python:y,venvDir:s,pythonPkgDir:e}})}exports.ensurePythonEnv=J;exports.resolvePythonPkgDir=k;

package/index.mjs

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

package/lib/python-env.d.ts

@@ -0,0 +1,44 @@
+/** Result of {@link ensurePythonEnv}. */
+export interface IPythonEnv {
+    /** Absolute path to the interpreter the caller should spawn. */
+    python: string;
+    /** Absolute path to the managed venv dir ('' when APIGEN_PYTHON overrode it). */
+    venvDir: string;
+    /** Absolute path to the apigen-python package sources (PYTHONPATH target). */
+    pythonPkgDir: string;
+}
+export interface IEnsurePythonEnvOptions {
+    /**
+     * Extras from apigen-python's pyproject `[project.optional-dependencies]`
+     * to provision (e.g. `['grpc']`). Sorted + deduped into the stamp so the
+     * venv is refreshed when the requested extras change.
+     */
+    extras?: string[];
+    /**
+     * Override the managed-venv root (default `~/.adhd/apigen`). Tests point
+     * this at `tmp/` so they never touch the user's real environment.
+     * Honours the `APIGEN_PYENV_HOME` env var when the option is absent.
+     */
+    envHome?: string;
+    /** Bound (ms) on waiting for another process's in-flight bootstrap. */
+    lockTimeoutMs?: number;
+}
+/**
+ * Locate the directory containing the `apigen_python` package sources.
+ *
+ * Primary: `<this file>/../../../python` (source layout:
+ * packages/apigen/python-env/src/lib → packages/apigen/python).
+ * Fallback: 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.)
+ */
+export declare function resolvePythonPkgDir(fromDir?: string): string;
+/**
+ * Resolve the interpreter for apigen's Python hosts, provisioning the managed
+ * venv from `apigen-python`'s own pyproject.toml when needed.
+ *
+ * Synchronous by design — this is a startup-time path and its consumers
+ * (plugin `run()` bodies, serve pre-flight) need a settled interpreter before
+ * spawning children.
+ */
+export declare function ensurePythonEnv(opts?: IEnsurePythonEnvOptions): IPythonEnv;

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@adhd/apigen-python-env",
+  "version": "0.1.0",
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "types": "./index.d.ts",
+  "description": "apigen python host provisioning: resolves the interpreter for py-* plugins by bootstrapping a managed venv from apigen-python's own pyproject.toml extras",
+  "keywords": [
+    "apigen",
+    "python",
+    "venv",
+    "provisioning"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}