pynect 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reggie Bowser and NodePyX contributors
+
+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.

package/README.md

@@ -1,3 +1,479 @@
-# Temporary Holding Version
+# Pynect
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pynect lets Node.js and Bun call Python modules in-process with generated TypeScript declarations and optional Python-side Pydantic validation. Python type hints remain the source of truth, so projects do not need a separately maintained controller interface or TypeScript validation schema.
+
+Python remains responsible for normalization and validation. If Pydantic 1 or 2 is importable, annotated arguments and return values are validated automatically. Pydantic is optional; Pynect does not install it.
+
+## Install
+
+```sh
+bun add --trust pynect
+```
+
+Declare application Python dependencies. Pynect's trusted postinstall creates the uv project and synchronizes the locked environment:
+
+```json
+{
+  "pynect": {
+    "schemaVersion": 1,
+    "requiresPython": ">=3.11,<3.13",
+    "requirements": ["pydantic>=2,<3"]
+  }
+}
+```
+
+When lifecycle scripts are disabled or Pynect is not trusted, run `bunx --bun pynect sync` explicitly.
+
+Current Bun releases and Node.js 22 or newer are supported. Bun-only systems do not need a `node` executable. A preinstalled Python or uv is also unnecessary: Pynect uses Pyfig to create `<project-root>/.venv`, installing its pinned uv and a managed GIL-enabled Python 3.12 when no compatible embeddable CPython exists. When a matching prebuilt addon is unavailable, the first `init()` or `importModule()` compiles it with the active JavaScript runtime from `process.execPath`; a C++ toolchain is still required for that fallback.
+
+## Quick start
+
+Add a typed Python module such as `calculator.py`:
+
+```python
+def add(left: int, right: int) -> int:
+    return left + right
+```
+
+Generate declarations for the project. With no module arguments, Pynect discovers Python files under conventional `src` or `python` source roots, falling back to the current directory. Public members are included by default; private modules, private members, and files ending in `_example.py` are skipped:
+
+```sh
+bunx --bun pynect codegen
+```
+
+`bunx --bun` makes Bun execute the package binary itself, so codegen does not require a separate Node.js installation.
+
+Code generation uses [Pacwich](https://github.com/smorsic/pacwich) to resolve the current package or monorepo workspace. By default it also adds the generated declarations to `tsconfig.json`, adds a `codegen` package script when one does not exist, and ignores the generated metadata directory in `.gitignore`.
+
+Use the generated module type directly:
+
+```ts
+import { importModule } from 'pynect';
+
+const calculator = await importModule('calculator');
+console.log(await calculator.add(2, 3));
+```
+
+`importModule()` initializes the shared runtime with defaults on first use and the runtime shuts down automatically when the process finishes. Call `init(config)` first only when custom runtime settings are needed. Call `shutdown()` explicitly only when the application needs to release Python before process exit.
+
+## Add Pydantic validation
+
+For Python-side normalization and validation, use Pydantic models in a module such as `users.py`:
+
+```python
+from pydantic import BaseModel
+
+class UserInput(BaseModel):
+    name: str
+    age: int
+
+class UserResult(BaseModel):
+    id: int
+    name: str
+
+def create_user(data: UserInput) -> UserResult:
+    return UserResult(id=1, name=data.name)
+```
+
+Regenerate the project declarations:
+
+```sh
+bunx --bun pynect codegen
+```
+
+Then restrict the dispatcher to fully typed members in that module:
+
+```ts
+import { init, importModule } from 'pynect';
+
+await init({
+  dispatcher: {
+    include: ['users.*'],
+    typedOnly: true,
+  },
+});
+
+const users = await importModule('users');
+const user = await users.create_user({ name: 'Alice', age: 30 });
+console.log(user.name);
+```
+
+When Pydantic is installed in the selected Python environment, the input object becomes a `UserInput` before the function runs. The returned `UserResult` is validated and converted to JSON-compatible Python values before it crosses back to JavaScript. Without Pydantic, the annotated Python call still works but Pydantic validation is skipped.
+
+## Why Pynect
+
+Pynect and [PyBridge](https://github.com/marcj/pybridge) connect TypeScript and Python with different execution models. Pynect may be a better fit when you want:
+
+- CPython embedded in the Node.js or Bun process instead of a Python subprocess connected over standard input and output.
+- TypeScript declarations generated by inspecting Python modules instead of a separately maintained TypeScript controller interface.
+- Direct proxy access to Python modules, classes, objects, and functions.
+- Optional Pydantic 1 or 2 validation and normalization in Python, including Python-defined validators and serializers.
+- Include, exclude, type-hint, and export policies enforced at the dispatcher boundary.
+- Automatic embeddable-Python discovery with a checksum-verified uv fallback when Python is unavailable or lacks development headers.
+
+PyBridge may be a better fit when every call must be process-isolated, or when RxJS generator streaming or Deepkit runtime serialization and reflection matter more than direct in-process access.
+
+The main tradeoff is isolation versus integration. Normal Pynect proxy calls avoid subprocess transport and duplicate controller definitions, while its optional JSON-only worker provides hard termination for selected calls. Installation still requires a local C++ build toolchain until prebuilt binaries are available.
+
+## Python and native build
+
+The package loads a matching local N-API addon first. Its build manifest must name the exact interpreter selected by Pyfig; a stale addon built for another Python is rebuilt. If no matching addon works, Pynect lazily builds one against the selected interpreter. The builder is launched with `process.execPath`, so Bun launches Bun and Node.js launches Node.js instead of assuming a `node` command exists. The same approach works with another Node-compatible runtime when it implements the child-process and N-API behavior Pynect needs.
+
+```mermaid
+graph TD;
+    A[First runtime initialization] --> B[Pyfig selects repository Python];
+    B --> C{Exact Python addon loads};
+    C -->|Yes| G[Initialize embedded CPython];
+    C -->|No| D[Launch builder with process execPath];
+    D --> E[Build against selected Python headers and library];
+    E --> F[Load newly built addon];
+    F --> G;
+```
+
+Pynect requires Python 3.10 or newer, `Python.h`, a linkable CPython library, and the standard GIL-enabled ABI. It rejects a runtime-only or free-threaded installation instead of compiling against unrelated `python3-config` output. When no compatible interpreter exists, Pyfig downloads the pinned uv archive from Astral's GitHub release, verifies its SHA-256 checksum, and installs managed Python 3.12.
+
+Builds, the embedded runtime, codegen, isolated workers, `pipSpawn`, and `uv pip` all use the same repository-root `.venv` interpreter. `virtualenv.path` is deprecated; when provided for compatibility, it must resolve to that root `.venv`.
+
+## Locked application environment
+
+One application owns one `.venv` and one `pynect.lock`. Reusable npm packages contribute requirements and exposed modules through their `package.json` without installing anything themselves:
+
+```json
+{
+  "name": "@acme/name-generator",
+  "dependencies": {
+    "pynect": "^0.2.0"
+  },
+  "pynect": {
+    "schemaVersion": 1,
+    "requiresPython": ">=3.11,<3.13",
+    "requirements": ["name-generator>=1,<2"],
+    "modules": {
+      "generator": {
+        "import": "name_generator",
+        "include": ["generate_name"]
+      }
+    }
+  }
+}
+```
+
+`pynect sync` walks the installed npm dependency graph and writes one minimal generated uv project at `.pynect/pyproject.toml`. uv performs dependency resolution, writes its native universal lock, and exactly synchronizes the root `.venv`; Pynect copies that native lock to the configured `pynect.lock` path for check-in. uv's shared cache avoids repeated downloads across environments. Pynect records the manifest hash, lock hash, Python ABI, platform, and contributing packages in `.venv/.pynect-state.json`.
+
+Pynect does not implement a Python package resolver. Conflicts and platform-specific selections are handled by uv, while Pynect adds the npm packages that contributed each top-level requirement to failure output. Dependency manifests may declare only `schemaVersion`, `requiresPython`, `requirements`, and `modules`; Python selection, installation policy, lockfile placement, indexes, and credentials remain application-owned.
+
+The root application may resolve a known conflict explicitly without changing a dependency package:
+
+```json
+{
+  "pynect": {
+    "overrides": {
+      "image-lib": ">=2,<3"
+    }
+  }
+}
+```
+
+Overrides are emitted as uv's native `tool.uv.override-dependencies` configuration and included in the manifest fingerprint. Configure private indexes with uv's application environment variables such as `UV_DEFAULT_INDEX`; keep credentials outside `package.json`.
+
+Exposed module ids are namespaced by npm package name:
+
+```ts
+import { importModule } from 'pynect';
+
+const generator = await importModule('@acme/name-generator:generator');
+console.log(await generator.generate_name());
+```
+
+The aggregated `modules.include` patterns are enforced by the runtime dispatcher. When `include` is omitted, that manifest exposes the module's public callables; application dispatcher includes are additive, and excludes always win.
+
+Normal runtime startup validates the lock and environment state without network access. Applications that want development-time repair may opt in with `"autoSync": "if-missing"`; the default is `"never"`. Production and CI should use an explicit frozen sync:
+
+```sh
+bunx --bun pynect sync --frozen
+```
+
+Pynect's postinstall runs the same sync automatically when a reachable npm package contributes a `pynect` manifest. Set `PYNECT_SKIP_POSTINSTALL=1` to opt out. npm users can also use `--ignore-scripts`; Bun users must explicitly trust `pynect` because Bun blocks dependency lifecycle scripts by default:
+
+```json
+{
+  "trustedDependencies": ["pynect"]
+}
+```
+
+An application may always keep installation side-effect free and run `pynect sync` explicitly instead.
+
+Configuration precedence is API or CLI, environment, root `package.json`, then default:
+
+| package.json / API | Environment | CLI | Default |
+| --- | --- | --- | --- |
+| `python` | `PYNECT_PYTHON` | `--python` | auto-detect |
+| `requiresPython` | `PYNECT_REQUIRES_PYTHON` | `--requires-python` | `>=3.10.0 <4.0.0` |
+| `managedPython` | `PYNECT_MANAGED_PYTHON` | `--managed-python` | `3.12` |
+| `uvVersion` | `PYNECT_UV_VERSION` | `--uv-version` | Pyfig's pinned release |
+| `installPython` | `PYNECT_INSTALL_PYTHON` | `--install-python` | `true` |
+| `installUv` | `PYNECT_INSTALL_UV` | `--install-uv` | `true` |
+| `createVirtualEnvironment` | `PYNECT_CREATE_VIRTUAL_ENVIRONMENT` | `--create-virtual-environment` | `true` |
+| `autoSync` | `PYNECT_AUTO_SYNC` | n/a | `never` |
+| `lockfile` | `PYNECT_LOCKFILE` | `--lockfile` | `pynect.lock` |
+
+`--offline` prohibits network access. `--frozen` passes uv's `--locked` check and refuses to rewrite an outdated lock. The deprecated `PYNECT_AUTO_INSTALL` and runtime `autoInstallPython` names remain compatibility aliases; new configuration should use the names above. Runtime `virtualenv.autoInstall` is no longer supported because independent startup installs cannot resolve the complete npm dependency graph safely.
+
+Pynect uses [loqkit](https://www.npmjs.com/package/loqkit) for JavaScript critical sections. Project sync and native builds use its default layered memory, worker-thread, and cross-process file locks. Runtime lifecycle and Python garbage collection use memory-scoped locks because those resources belong to one JavaScript process. Pynect does not maintain separate promise, module, inspection, or proxy memo caches; new memoized getters should use loqkit's `memoize` primitive.
+
+Pyfig's managed-tool provisioning uses its own check-lock-check sections:
+
+1. Check for an existing tool.
+2. Acquire a cross-process file lock.
+3. Check again.
+4. Install only if it is still absent.
+
+A C++ build toolchain is still required. On Windows, install Visual Studio Build Tools with the Desktop development with C++ workload. Set `PYNECT_AUTO_INSTALL=0` to prohibit managed Python downloads while still allowing `.venv` creation from a compatible setup-python or system interpreter. Set `PYNECT_INSTALL_UV=0` to prohibit uv installation, `PYNECT_CREATE_VIRTUAL_ENVIRONMENT=0` to require an existing root `.venv`, or `PYNECT_PYTHON` to check a specific interpreter first.
+
+## Codegen selection
+
+The simplest form discovers project modules and generates every public member:
+
+```sh
+bunx --bun pynect codegen
+```
+
+Pass module names when you only want specific modules:
+
+```sh
+bunx --bun pynect codegen users billing
+```
+
+Add repeatable include and exclude patterns when a project needs a narrower surface. Supplying `--include` restricts output to matching members. Supplying `--typed` restricts output to fully typed members. `--exclude` always excludes. Patterns match leaf or qualified names:
+
+```sh
+bunx --bun pynect codegen users billing \
+  --include 'users.*' \
+  --include 'billing.Invoice*' \
+  --exclude '*internal*' \
+  --typed
+```
+
+For reusable settings, put the same options in `pynect.config.json`:
+
+```json
+{
+  "src": ["./python"],
+  "outDir": "./generated",
+  "include": ["users.*", "billing.Invoice*"],
+  "exclude": ["*internal*"],
+  "typed": true,
+  "configure": true
+}
+```
+
+The CLI uses Commander. Configuration precedence is CLI, environment, JSON config, then defaults. Set `"configure": false` or pass `--no-configure` to prevent edits to `tsconfig.json`, `package.json`, and `.gitignore`. Use `--tsconfig` when the workspace uses a nonstandard config filename.
+
+Automatic discovery skips directories, packages, and modules whose names begin with `_`, common environment and build directories, and files ending in `_example.py`. The same private-package rule applies to explicitly requested module paths. Use repeatable `--src` options when Python lives somewhere else:
+
+```sh
+bunx --bun pynect codegen --src ./backend --src ./shared-python
+```
+
+Local source files are parsed with Python's AST and are not imported during generation. Explicit installed modules that cannot be resolved under a configured source root use live inspection so packages such as NumPy and pandas can still expose their runtime API.
+
+Use centralized overrides for opaque extension types or legacy untyped functions:
+
+```json
+{
+  "typeOverrides": {
+    "UUID": "string",
+    "Decimal": "number"
+  },
+  "signatureOverrides": {
+    "legacy.lookup": "(userId: string): Promise<User>",
+    "legacy.Client.fetch": "(limit?: number): Promise<User[]>"
+  }
+}
+```
+
+Type overrides map a Python annotation name wherever it appears. Signature overrides are keyed by the fully qualified function or method name and replace its generated TypeScript call signature.
+
+Other commands:
+
+```sh
+bunx pynect codegen --list
+bunx pynect codegen --all
+bunx pynect codegen --clear
+```
+
+`--all` means all modules tracked in generated metadata. Within each requested module, the default is all public members. Use `--exported` to require the `@export` marker or `--typed` to require complete parameter and return type hints.
+
+## Raw module imports
+
+Generated declarations are the normal application workflow. For exploration, third-party packages, or Python modules that do not need generated types, import a module directly:
+
+```ts
+import { importModule } from 'pynect';
+
+const math = await importModule('math');
+console.log(await math.sqrt(9));
+```
+
+Raw imports return a dynamic Python proxy. Run codegen when the module should provide TypeScript inference in application code.
+
+## Runtime policy
+
+```ts
+await init({
+  autoShutdown: true,
+  dispatcher: {
+    include: ['my_app.*'],
+    exclude: ['*.admin.*', '*._*'],
+    typedOnly: true,
+    exportedOnly: false,
+    validation: 'auto', // auto, required, or off
+  },
+  allowUnsafeCode: false,
+  allowPackageInstall: false,
+  includeTracebacks: false,
+});
+```
+
+`autoShutdown` defaults to `true` for both the embedded runtime and the optional isolated worker. Set it to `false` only when the host owns lifecycle and will call `shutdown()` explicitly.
+
+Defaults are intentionally conservative around dangerous bridge features:
+
+- Raw `eval`, `exec`, file execution, contexts, and native-addon access are disabled.
+- Runtime package installation is disabled.
+- Python tracebacks are hidden.
+- Private callables and modules are rejected.
+- Excludes override includes and decorators.
+- Pydantic validation is automatic only when Pydantic is already importable.
+
+Every normal proxy function, method, and constructor call passes through this policy and validation dispatcher.
+`typedOnly` and `exportedOnly` are independent: enabling both requires every callable to be explicitly exported and fully typed.
+
+The worker pool defaults to the larger of four workers or the host's available CPU count. This improves queue scheduling; the CPython GIL still prevents CPU-bound Python bytecode from running in parallel within one interpreter.
+
+## Cancellation and timeouts
+
+`callTimeout` limits time waiting in the native queue. `executionTimeout` separately cancels asynchronous Python execution:
+
+```ts
+await init({
+  callTimeout: 2_000,
+  executionTimeout: 10_000,
+});
+```
+
+Every generated function and method includes a typed `withOptions()` call:
+
+```ts
+import { importModule } from 'pynect';
+
+const jobs = await importModule('jobs');
+const controller = new AbortController();
+
+setTimeout(() => controller.abort(), 1_000);
+await jobs.run_job.withOptions(
+  { signal: controller.signal, executionTimeout: 5_000 },
+  { id: 42 },
+);
+```
+
+`withOptions` is a property on the callable, so it does not consume a sibling module name such as `run_jobWithOptions`. If a Python callable itself defines a `withOptions` attribute, use the exported `PYNECT_WITH_OPTIONS` symbol for the bridge operation:
+
+```ts
+import { PYNECT_WITH_OPTIONS } from 'pynect';
+
+await jobs.run_job[PYNECT_WITH_OPTIONS](
+  { executionTimeout: 5_000 },
+  { id: 42 },
+);
+```
+
+Queued calls are removed before execution when possible. Running async functions are cancelled on the persistent asyncio loop. Arbitrary synchronous CPython code cannot be interrupted safely inside the Node.js process.
+
+## Isolated calls
+
+Enable the optional worker when a call needs a hard timeout or when an ordinary Python interpreter crash should be contained outside the Node.js process:
+
+```ts
+import { callIsolated, init, shutdown } from 'pynect';
+
+await init({
+  isolation: {
+    enabled: true,
+    timeout: 30_000,
+  },
+  dispatcher: {
+    include: ['jobs.*'],
+  },
+});
+
+try {
+  const result = await callIsolated(
+    'jobs',
+    'run_job',
+    [{ id: 42 }],
+    { timeout: 5_000 },
+  );
+  console.log(result);
+} finally {
+  await shutdown();
+}
+```
+
+Isolated calls use a lazy persistent Python child process and JSON-compatible arguments and results. Calls through that worker are serialized. A timeout or abort terminates it, rejects its outstanding calls, and lets the next call start a fresh worker. The child process still has the operating-system permissions of the current user; use an OS sandbox or container for hostile code.
+
+## Pydantic modes
+
+- `auto`: validate every supported argument and return annotation when Pydantic 1 or 2 is available; otherwise preserve Python behavior. This is the default for all normal callable dispatches.
+- `required`: reject calls when Pydantic is missing or cannot build a validator for an annotation.
+- `off`: never ask Pydantic to validate.
+
+Pydantic models, aliases, defaults, nested models, enums, dates, UUIDs, and standard annotated containers use Pydantic's own validation and serialization behavior. Custom validators and serializers run in Python; Pynect does not attempt to reproduce them in TypeScript.
+
+Pydantic cannot infer a validation target for an unannotated value, and some extension callables do not expose an inspectable signature. Those calls still pass through the dispatcher and its access policy, but their untyped values retain normal Python behavior.
+
+## Current limits
+
+- Normal proxy calls are in-process. A native Python crash can terminate Node or Bun; use `callIsolated()` where a process boundary is required.
+- In-process execution timeouts and aborts are cooperative for async functions. Hard termination of synchronous code requires `callIsolated()`.
+- Async Python uses one persistent asyncio loop. CPU-bound work still needs Python multiprocessing or native extensions that release the GIL.
+- Local modules use safe AST inspection, but codegen for explicitly requested installed packages imports those packages and may run their import-time code.
+- The isolated worker is not an operating-system sandbox and supports only JSON-compatible calls, not Python object proxies.
+- GitHub Actions builds Python 3.12 native artifacts for Linux, macOS, and Windows on x64 and ARM64. Those artifacts are not yet attached to releases or downloaded during package installation.
+
+See [SECURITY.md](./SECURITY.md) before exposing imports or call patterns to untrusted input.
+
+## Development
+
+```sh
+bun install --frozen-lockfile
+bun run verify
+```
+
+`verify` type-checks, rebuilds the addon, and runs the shared-interpreter smoke test. `scripts/docker-zero-python.sh` is the clean-container reproduction: it starts from the official Bun image, asserts that Node.js, Python, and uv are absent, installs the registry-published Pyfig dependency plus only the C++ toolchain, then verifies Pyfig bootstrap, lazy native compilation through Bun, and the full Pynect native boundary. The separate `Native binaries` workflow runs for native or Python-boundary changes and can also be started manually.
+
+### Publishing
+
+Local publishing uses the package-scoped npm token at `~/.secrets/npm/pynect-publish-token`. The file contains only the raw token and must never be copied into the repository, an npm command-line argument, or a log. The token is limited to `pynect`, has package read/write access, has no organization access, bypasses publish-time 2FA, and expires January 30, 2027.
+
+Load the token only into the current PowerShell process, verify the npm identity, and publish from a clean `main` branch:
+
+```powershell
+$tokenPath = Join-Path $env:USERPROFILE '.secrets\npm\pynect-publish-token'
+$env:NPM_TOKEN = (Get-Content -Raw -LiteralPath $tokenPath).Trim()
+
+try {
+  npm whoami --registry=https://registry.npmjs.org/
+  npm publish
+} finally {
+  Remove-Item Env:NPM_TOKEN -ErrorAction SilentlyContinue
+}
+```
+
+npm plans to remove direct publishing with bypass-2FA granular tokens in January 2027. Replace this local flow with trusted publishing before that cutoff; until then, rotate the token at the same secret path without changing repository files.
+
+## Project history
+
+Pynect builds on [NodePyX](https://github.com/Brah-Timo/nodepyx) and retains its Git history and contributor attribution. Its public API, dispatcher policy, optional Pydantic integration, Python provisioning, codegen, and Windows build path have been revised for this project.
+
+MIT licensed.

package/SECURITY.md

@@ -0,0 +1,34 @@
+# Security
+
+Pynect embeds Python in the JavaScript process. Treat every imported module and callable as trusted code with the permissions of that process.
+
+## Safe defaults
+
+- Raw Python code execution and native-addon access require `allowUnsafeCode: true`.
+- Package installation requires `allowPackageInstall: true`.
+- Tracebacks are hidden unless `includeTracebacks: true`.
+- Dispatcher include, exclude, type-hint, and export policies are enforced inside the native call path.
+- Dependency manifests cannot select indexes, credentials, interpreters, or installation policy.
+- Postinstall synchronization runs only when lifecycle scripts are enabled (and, with Bun, Pynect is trusted); set `PYNECT_SKIP_POSTINSTALL=1` or disable lifecycle scripts to require explicit synchronization.
+- Normal runtime startup validates the checked lock and environment fingerprint without installing packages.
+- Local codegen discovery uses AST parsing and does not execute application modules.
+- Private module and callable names are rejected; explicit excludes always win.
+- Python package specifications and module identifiers are validated before subprocess use.
+- Pyfig pins uv, downloads only Astral's GitHub release archive, and verifies its SHA-256 checksum before extraction.
+- Pynect project sync and native builds use loqkit's layered memory, worker-thread, and cross-process file locks; process-owned runtime and garbage-collection sections use its memory lock.
+- Pyfig and uv retain ownership of their package and managed-tool synchronization.
+- uv owns Python dependency resolution and exact environment synchronization through the generated non-package `pyproject.toml`; Pynect does not implement a parallel resolver.
+
+## Deployment guidance
+
+Use a narrow dispatcher include list, run under a low-privilege operating-system account, and keep `allowUnsafeCode` and `allowPackageInstall` disabled for applications that process untrusted input. Do not let request data select module names, attribute paths, package specifications, Python code, or filesystem paths.
+
+Pydantic validates data shapes; it is not a sandbox. Validators and serializers are Python code and must be trusted.
+
+`callIsolated()` protects the Node.js process from a worker crash and allows hard termination on timeout. It does not reduce filesystem, network, environment, or operating-system permissions. Run hostile code in a separately secured account, container, virtual machine, or platform sandbox.
+
+Codegen for explicitly requested installed modules uses runtime inspection and imports the package. Only inspect third-party packages you trust.
+
+## Reporting
+
+Report vulnerabilities privately to the repository owner before opening a public issue. Include the affected commit, platform, Python version, JavaScript runtime and version, and a minimal reproduction without secrets.

package/binding.gyp

@@ -0,0 +1,60 @@
+{
+  "targets": [{
+    "target_name": "pynect_addon",
+    "sources": [
+      "src/native/pynect_addon.cpp",
+      "src/native/python_bridge.cpp",
+      "src/native/type_converter.cpp",
+      "src/native/thread_pool.cpp",
+      "src/native/gil_guard.cpp"
+    ],
+    "include_dirs": [
+      "<!@(node -p \"require('node-addon-api').include\")",
+      "<!(node -p \"process.env.PYNECT_PYTHON_INCLUDE_DIR || (() => { throw new Error('PYNECT_PYTHON_INCLUDE_DIR is required') })()\")"
+    ],
+    "libraries": [
+      "<!(node -p \"process.env.PYNECT_PYTHON_LIBRARY || (() => { throw new Error('PYNECT_PYTHON_LIBRARY is required') })()\")"
+    ],
+    "cflags_cc": [
+      "-std=c++17",
+      "-O2",
+      "-Wall",
+      "-Wextra",
+      "-Wno-unused-parameter"
+    ],
+    "cflags!": ["-fno-exceptions"],
+    "cflags_cc!": ["-fno-exceptions"],
+    "defines": [
+      "NAPI_CPP_EXCEPTIONS",
+      "NAPI_VERSION=8",
+      "PY_SSIZE_T_CLEAN"
+    ],
+    "conditions": [
+      ["OS=='linux'", {
+        "cflags_cc": ["-fvisibility=hidden"],
+        "libraries": ["-ldl"],
+        "ldflags": [
+          "-Wl,-rpath,<!(node -p \"process.env.PYNECT_PYTHON_LIBRARY_DIR || (() => { throw new Error('PYNECT_PYTHON_LIBRARY_DIR is required') })()\")"
+        ]
+      }],
+      ["OS=='mac'", {
+        "xcode_settings": {
+          "MACOSX_DEPLOYMENT_TARGET": "11.0",
+          "OTHER_CFLAGS": ["-std=c++17", "-stdlib=libc++"],
+          "LD_RUNPATH_SEARCH_PATHS": [
+            "<!(node -p \"process.env.PYNECT_PYTHON_LIBRARY_DIR || (() => { throw new Error('PYNECT_PYTHON_LIBRARY_DIR is required') })()\")"
+          ],
+          "GCC_ENABLE_CPP_EXCEPTIONS": "YES"
+        }
+      }],
+      ["OS=='win'", {
+        "msvs_settings": {
+          "VCCLCompilerTool": {
+            "ExceptionHandling": 1,
+            "AdditionalOptions": ["/std:c++17"]
+          }
+        }
+      }]
+    ]
+  }]
+}

package/dist/cli/codegen.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createCodegenCommand(name?: string): Command;
+//# sourceMappingURL=codegen.d.ts.map

package/dist/cli/codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/cli/codegen.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AA6G5C,wBAAgB,oBAAoB,CAAC,IAAI,SAAY,GAAG,OAAO,CAwB9D"}