pynect 0.0.0 → 0.2.1

package/scripts/build-native.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { ensurePynectPython } = require('./pyfig');
+
+const ROOT = path.resolve(__dirname, '..');
+
+async function main() {
+  const projectRoot = process.env.PYNECT_PROJECT_ROOT || process.env.INIT_CWD || ROOT;
+  const { python } = await ensurePynectPython({
+    projectRoot,
+    pythonPath: process.env.PYNECT_PYTHON,
+  });
+  const embedding = python.embedding;
+  const nodeGyp = require.resolve('node-gyp/bin/node-gyp.js');
+  const mode = process.argv.includes('--debug') ? '--debug' : '--release';
+  const args = [nodeGyp, 'rebuild', mode];
+  if (process.argv.includes('--verbose')) args.push('--verbose');
+  console.log(`[pynect build] Python ${python.version}: ${python.executable}`);
+  const env = {
+    ...process.env,
+    npm_config_python: python.executable,
+    PYTHON: python.executable,
+    PYNECT_PYTHON_INCLUDE_DIR: embedding.includeDirectory,
+    PYNECT_PYTHON_LIBRARY: embedding.libraryPath,
+    PYNECT_PYTHON_LIBRARY_DIR: embedding.libraryDirectory,
+    PATH: [embedding.libraryDirectory, path.dirname(python.executable), process.env.PATH || '']
+      .filter(Boolean)
+      .join(path.delimiter),
+  };
+  const result = spawnSync(process.execPath, args, { cwd: ROOT, env, stdio: 'inherit', windowsHide: true });
+  if (result.status !== 0) throw new Error(`node-gyp failed with exit code ${result.status}`);
+  const target = path.join(ROOT, 'build', mode === '--debug' ? 'Debug' : 'Release', 'pynect_addon.node');
+  if (!fs.existsSync(target)) throw new Error(`Native addon was not created at ${target}`);
+  fs.writeFileSync(
+    path.join(ROOT, 'build', 'pynect-python.json'),
+    `${JSON.stringify({
+      schemaVersion: 1,
+      pythonExecutable: path.resolve(python.executable),
+      pythonVersion: python.version,
+      pythonLibrary: path.resolve(embedding.libraryPath),
+      buildType: mode === '--debug' ? 'Debug' : 'Release',
+    }, null, 2)}\n`,
+  );
+  console.log(`[pynect build] Built ${path.relative(ROOT, target)}`);
+}
+
+main().catch(error => { console.error(`[pynect build] ${error.message}`); process.exitCode = 1; });

package/scripts/cli.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+'use strict';
+
+const { Command } = require('commander');
+const packageJson = require('../package.json');
+const { createCodegenCommand } = require('../dist/cli/codegen');
+const { createSyncCommand } = require('../dist/cli/sync');
+
+const program = new Command()
+  .name('pynect')
+  .description('Generate types and manage Pynect projects.')
+  .version(packageJson.version)
+  .showHelpAfterError();
+
+program.addCommand(createCodegenCommand());
+program.addCommand(createSyncCommand());
+
+program.parseAsync(process.argv).catch(error => {
+  console.error(`pynect: ${error.message}`);
+  process.exitCode = 1;
+});

package/scripts/ensure-native.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const BUILD_DIRECTORY = path.join(ROOT, 'build');
+const METADATA = path.join(BUILD_DIRECTORY, 'pynect-python.json');
+
+function normalize(value) {
+  const resolved = path.resolve(value);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function matchingAddonPath() {
+  const selected = process.env.PYNECT_PYTHON;
+  if (!selected || !fs.existsSync(METADATA)) return null;
+  try {
+    const metadata = JSON.parse(fs.readFileSync(METADATA, 'utf8'));
+    if (
+      metadata.schemaVersion !== 1 ||
+      normalize(metadata.pythonExecutable) !== normalize(selected)
+    ) return null;
+    return path.join(
+      BUILD_DIRECTORY,
+      metadata.buildType === 'Debug' ? 'Debug' : 'Release',
+      'pynect_addon.node',
+    );
+  } catch {
+    return null;
+  }
+}
+
+function loads() {
+  const addon = matchingAddonPath();
+  if (!addon || !fs.existsSync(addon)) return false;
+  try {
+    require(addon);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function build() {
+  console.log(`[pynect native] Building with active runtime ${process.execPath}`);
+  const result = spawnSync(process.execPath, [path.join(__dirname, 'build-native.js')], {
+    cwd: ROOT,
+    env: process.env,
+    stdio: 'inherit',
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`Native addon build failed with exit code ${result.status}.`);
+  }
+  if (!loads()) throw new Error('Native addon did not load after it was built.');
+}
+
+async function main() {
+  const force = process.env.PYNECT_FORCE_BUILD === '1';
+  if (!force && loads()) return;
+  if (process.env.PYNECT_SKIP_BUILD === '1') {
+    throw new Error('Native addon is unavailable and building is disabled by PYNECT_SKIP_BUILD=1.');
+  }
+
+  fs.mkdirSync(BUILD_DIRECTORY, { recursive: true });
+  const { withLock } = await import('loqkit');
+  await withLock(
+    { buildDirectory: BUILD_DIRECTORY },
+    async () => build(),
+    async () => force || !loads(),
+    {
+      key: `pynect-native:${normalize(BUILD_DIRECTORY)}`,
+      name: 'Pynect native build',
+      namespace: 'pynect',
+    },
+  );
+}
+
+main().catch(error => {
+  console.error(`[pynect native] ${error.message}`);
+  process.exitCode = 1;
+});

package/scripts/postinstall.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function disabled(value) {
+  return value !== undefined && /^(1|true|yes|on)$/i.test(value);
+}
+
+async function main() {
+  if (disabled(process.env.PYNECT_SKIP_POSTINSTALL)) return;
+
+  const projectRoot = path.resolve(
+    process.env.INIT_CWD || process.env.npm_config_local_prefix || process.cwd(),
+  );
+  const environmentModule = path.join(__dirname, '..', 'dist', 'env', 'project-environment.js');
+
+  // Published packages contain dist. A source checkout may install dependencies
+  // before its first TypeScript build, so its normal verify/build flow owns setup.
+  if (!fs.existsSync(environmentModule)) return;
+
+  const {
+    createProjectPlan,
+    requiresProjectSync,
+    syncProject,
+  } = require(environmentModule);
+  const plan = createProjectPlan({ projectRoot });
+  if (!requiresProjectSync(plan)) return;
+
+  const result = await syncProject({ projectRoot });
+  console.log(
+    `[pynect] Synchronized ${result.plan.requirements.length} Python requirement(s) ` +
+    `with uv in ${path.dirname(result.plan.stateFile)}.`,
+  );
+}
+
+main().catch(error => {
+  console.error(`[pynect] Postinstall synchronization failed: ${error.message}`);
+  process.exitCode = 1;
+});

package/scripts/pyfig.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const REQUIRED_PYFIG_FUNCTIONS = [
+  'createPyfig',
+];
+
+function loadPyfig() {
+  const configured = process.env.PYNECT_PYFIG_PATH;
+  if (configured) {
+    return requireCompatiblePyfig(path.resolve(configured), 'PYNECT_PYFIG_PATH');
+  }
+  let packageError;
+  try {
+    return requireCompatiblePyfig('pyfig', 'installed pyfig package');
+  } catch (error) {
+    packageError = error;
+  }
+
+  // During coordinated source development, a published but older package can
+  // resolve successfully. Prefer the sibling build when its API is compatible.
+  const sibling = path.resolve(__dirname, '..', '..', 'pyfig', 'dist', 'cjs', 'index.js');
+  if (fs.existsSync(sibling)) {
+    return requireCompatiblePyfig(sibling, 'sibling pyfig build');
+  }
+
+  const detail = packageError instanceof Error ? ` ${packageError.message}` : '';
+  throw new Error(
+    `Pynect requires a Pyfig release with the venv and spawn API.${detail}`,
+    { cause: packageError },
+  );
+}
+
+function requireCompatiblePyfig(specifier, label) {
+  const candidate = require(specifier);
+  const missing = REQUIRED_PYFIG_FUNCTIONS.filter(name => typeof candidate[name] !== 'function');
+  if (missing.length > 0) {
+    throw new Error(`${label} is missing required exports: ${missing.join(', ')}.`);
+  }
+  return candidate;
+}
+
+function parseBoolean(value, fallback) {
+  if (value === undefined) return fallback;
+  if (/^(1|true|yes|on)$/i.test(value)) return true;
+  if (/^(0|false|no|off)$/i.test(value)) return false;
+  throw new TypeError(`Invalid boolean value: ${value}`);
+}
+
+function projectRoot(explicit) {
+  const hint = explicit || process.env.PYNECT_PROJECT_ROOT || process.env.INIT_CWD;
+  return hint ? path.resolve(hint) : loadPyfig().resolveProjectRoot(process.cwd());
+}
+
+function pynectPyfigOptions(options = {}) {
+  const pyfig = loadPyfig();
+  const installPython = options.autoInstallPython ?? parseBoolean(
+    process.env.PYNECT_INSTALL_PYTHON ?? process.env.PYNECT_AUTO_INSTALL,
+    true,
+  );
+  return {
+    projectRoot: projectRoot(options.projectRoot),
+    python: options.pythonPath || process.env.PYNECT_PYTHON || '',
+    pythonRange: options.pythonRange || process.env.PYNECT_REQUIRES_PYTHON ||
+      pyfig.DEFAULT_PYTHON_RANGE,
+    managedPython: options.managedPython || process.env.PYNECT_MANAGED_PYTHON ||
+      process.env.PYNECT_PYTHON_VERSION || pyfig.DEFAULT_MANAGED_PYTHON,
+    uvVersion: options.uvVersion || process.env.PYNECT_UV_VERSION || pyfig.DEFAULT_UV_VERSION,
+    requireEmbedding: true,
+    requireGil: true,
+    installPython,
+    installUv: options.autoInstallUv ?? parseBoolean(process.env.PYNECT_INSTALL_UV, true),
+    createVirtualEnvironment: options.autoCreateVirtualEnvironment ??
+      parseBoolean(process.env.PYNECT_CREATE_VIRTUAL_ENVIRONMENT, true),
+    env: options.env ? { ...process.env, ...options.env } : process.env,
+  };
+}
+
+function assertEmbeddable(python) {
+  if (!python.embedding) {
+    throw new Error(
+      `Python ${python.version} at ${python.executable} is missing Python.h or its CPython ` +
+      'embedding library.',
+    );
+  }
+  return python;
+}
+
+function createPynectPyfig(options = {}) {
+  const client = loadPyfig().createPyfig(pynectPyfigOptions(options));
+  return {
+    ...client,
+    python(args = [], spawnOptions = {}) {
+      return client.uv(['run', '--', 'python', ...args], spawnOptions);
+    },
+    pythonSync(args = [], spawnOptions = {}) {
+      return client.uvSync(['run', '--', 'python', ...args], spawnOptions);
+    },
+    pip(args = [], spawnOptions = {}) {
+      return client.uv(['pip', ...args], spawnOptions);
+    },
+    pipSync(args = [], spawnOptions = {}) {
+      return client.uvSync(['pip', ...args], spawnOptions);
+    },
+  };
+}
+
+async function ensurePynectPython(options = {}) {
+  const client = createPynectPyfig(options);
+  const python = assertEmbeddable(await client.pythonInfo());
+  return { client, python };
+}
+
+async function ensurePynectEnvironment(options = {}) {
+  const client = createPynectPyfig(options);
+  const environment = await client.prepare();
+  assertEmbeddable(environment.python);
+  return { client, environment };
+}
+
+module.exports = {
+  createPynectPyfig,
+  ensurePynectEnvironment,
+  ensurePynectPython,
+  projectRoot,
+};

package/scripts/python-provisioner.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const { ensurePynectPython } = require('./pyfig');
+
+async function ensurePython(options = {}) {
+  const { python } = await ensurePynectPython({
+    autoInstallPython: options.autoInstall,
+    managedPython: options.version,
+    pythonPath: options.pythonPath,
+    projectRoot: options.projectRoot,
+  });
+  return python;
+}
+
+async function detectPython(explicit) {
+  try {
+    return await ensurePython({ autoInstall: false, pythonPath: explicit });
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { detectPython, ensurePython };

package/scripts/smoke-python-boundary.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const path = require('path');
+const { ensurePynectEnvironment } = require('./pyfig');
+
+const ROOT = path.resolve(__dirname, '..');
+
+async function main() {
+  const { client, environment } = await ensurePynectEnvironment({ projectRoot: ROOT });
+  const { python } = environment;
+  const expected = normalize(python.executable);
+  const pynect = require('../dist');
+
+  const detector = new pynect.PythonDetector({ projectRoot: ROOT });
+  const detected = await detector.detect();
+  assertSamePython(detected.executable, expected, 'PythonDetector');
+  const probed = detector.probe(detected.executable);
+  if (!probed) throw new Error('PythonDetector could not probe the selected repository Python.');
+  assertSamePython(probed.executable, expected, 'PythonDetector.probe');
+
+  const selected = client.pythonSync(
+    ['-c', 'import sys; print(sys.executable)'],
+    { encoding: 'utf8' },
+  );
+  assertSuccess(selected, 'PyfigClient.pythonSync');
+  assertSamePython(selected.stdout.trim(), expected, 'PyfigClient.pythonSync');
+
+  const pip = client.pipSync(['list', '--format', 'json'], { encoding: 'utf8' });
+  assertSuccess(pip, 'PyfigClient.pipSync');
+
+  const uvPip = client.uvSync(
+    ['pip', 'list', '--format', 'json'],
+    { encoding: 'utf8' },
+  );
+  assertSuccess(uvPip, 'PyfigClient.uvSync pip');
+
+  const inspector = client.pythonSync(
+    [path.join(ROOT, 'python', 'type_inspector.py'), 'json'],
+    { encoding: 'utf8' },
+  );
+  assertSuccess(inspector, 'codegen inspector');
+  JSON.parse(inspector.stdout);
+
+  const worker = client.pythonSync(
+    [path.join(ROOT, 'python', 'isolated_worker.py')],
+    {
+      encoding: 'utf8',
+      input: `${JSON.stringify({
+        id: 1,
+        module: 'os',
+        function: 'getenv',
+        args: ['VIRTUAL_ENV'],
+        kwargs: {},
+      })}\n`,
+      env: {
+        ...process.env,
+        PYTHONPATH: path.join(ROOT, 'python'),
+        PYNECT_DISPATCHER_CONFIG: '{}',
+      },
+    },
+  );
+  assertSuccess(worker, 'isolated worker');
+  const workerResult = JSON.parse(worker.stdout.trim());
+  if (!workerResult.ok || normalize(workerResult.result) !== normalize(python.virtualEnvironment)) {
+    throw new Error('The isolated worker did not use the Pyfig virtual environment.');
+  }
+
+  await pynect.init({
+    projectRoot: ROOT,
+    allowUnsafeCode: true,
+    logLevel: 'error',
+  });
+  try {
+    const embedded = await pynect.py.eval('__import__("sys").executable');
+    assertSamePython(embedded, expected, 'embedded CPython');
+  } finally {
+    await pynect.shutdown();
+  }
+
+  console.log(`Python boundary verified: ${python.executable}`);
+}
+
+function assertSuccess(result, label) {
+  if (result.status !== 0 || result.error) {
+    throw new Error(`${label} failed: ${String(result.stderr || result.error?.message || result.status)}`);
+  }
+}
+
+function assertSamePython(actual, expected, label) {
+  if (normalize(actual) !== expected) {
+    throw new Error(`${label} used ${actual}; expected ${expected}.`);
+  }
+}
+
+function normalize(value) {
+  const resolved = path.resolve(String(value || ''));
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+main().catch(error => {
+  console.error(`[pynect smoke] ${error.message}`);
+  process.exitCode = 1;
+});

package/src/native/gil_guard.cpp

@@ -0,0 +1,25 @@
+/**
+ * pynect - GIL Guard Implementation
+ * The GIL guard is header-only; this file provides explicit template
+ * instantiations and any platform-specific workarounds.
+ */
+
+#include "gil_guard.h"
+
+// All implementation is in the header file (RAII classes are trivial inline).
+// This .cpp exists to satisfy the build system and future non-inline additions.
+
+namespace pynect {
+
+// Verify at compile time that our RAII types are not accidentally copied
+static_assert(!std::is_copy_constructible<GILAcquire>::value,
+              "GILAcquire must not be copy-constructible");
+static_assert(!std::is_copy_constructible<GILRelease>::value,
+              "GILRelease must not be copy-constructible");
+static_assert(!std::is_copy_constructible<PyRef>::value,
+              "PyRef must not be copy-constructible");
+
+static_assert(std::is_move_constructible<PyRef>::value,
+              "PyRef must be move-constructible");
+
+} // namespace pynect

package/src/native/gil_guard.h

@@ -0,0 +1,174 @@
+/**
+ * pynect - GIL Guard Header
+ * RAII wrappers for the Python Global Interpreter Lock (GIL).
+ *
+ * The GIL ensures only one thread executes Python bytecode at a time.
+ * These guards make GIL management safe via RAII idiom.
+ */
+
+#pragma once
+
+#include <Python.h>
+#include <stdexcept>
+
+namespace pynect {
+
+/**
+ * GILAcquire - RAII guard that acquires the GIL on construction
+ * and releases it on destruction.
+ *
+ * Use when Python code needs to run in a non-Python thread (e.g. a worker thread).
+ * The calling thread must NOT already hold the GIL.
+ *
+ * @example
+ * ```cpp
+ * void worker_thread_func() {
+ * GILAcquire gil;  // GIL acquired
+ * PyObject* result = PyEval_EvalCode(...);
+ * // GIL released when gil goes out of scope
+ * }
+ * ```
+ */
+class GILAcquire {
+public:
+  GILAcquire() noexcept : _state(PyGILState_Ensure()) {}
+  ~GILAcquire() noexcept { PyGILState_Release(_state); }
+
+  // Non-copyable, non-movable
+  GILAcquire(const GILAcquire&) = delete;
+  GILAcquire& operator=(const GILAcquire&) = delete;
+  GILAcquire(GILAcquire&&) = delete;
+  GILAcquire& operator=(GILAcquire&&) = delete;
+
+private:
+  PyGILState_STATE _state;
+};
+
+/**
+ * GILRelease - RAII guard that releases the GIL on construction
+ * and re-acquires it on destruction.
+ *
+ * Use to temporarily release the GIL while performing blocking I/O or
+ * other operations that don't need Python, allowing other Python threads to run.
+ * The calling thread MUST already hold the GIL.
+ *
+ * @example
+ * ```cpp
+ * // Inside Python-holding code:
+ * {
+ * GILRelease release;  // GIL released - other Python threads can run
+ * perform_blocking_io();
+ * }  // GIL re-acquired here
+ * ```
+ */
+class GILRelease {
+public:
+  GILRelease() noexcept : _state(PyEval_SaveThread()) {}
+  ~GILRelease() noexcept { PyEval_RestoreThread(_state); }
+
+  // Non-copyable, non-movable
+  GILRelease(const GILRelease&) = delete;
+  GILRelease& operator=(const GILRelease&) = delete;
+  GILRelease(GILRelease&&) = delete;
+  GILRelease& operator=(GILRelease&&) = delete;
+
+private:
+  PyThreadState* _state;
+};
+
+/**
+ * PyRef - RAII wrapper for PyObject* reference counting.
+ *
+ * Automatically calls Py_XDECREF on destruction.
+ * Use steal() for objects returned from Python C API with new references.
+ * Use borrow() for borrowed references (won't decref).
+ */
+class PyRef {
+public:
+  PyRef() noexcept : _obj(nullptr), _owned(false) {}
+
+  ~PyRef() noexcept {
+    reset();
+  }
+
+  /** Take ownership of an object (new reference from Python API) */
+  static PyRef steal(PyObject* obj) noexcept {
+    PyRef ref;
+    ref._obj = obj;
+    ref._owned = true;
+    return ref;
+  }
+
+  /** Borrow a reference (will Py_INCREF and Py_DECREF) */
+  static PyRef borrow(PyObject* obj) noexcept {
+    PyRef ref;
+    ref._obj = obj;
+    ref._owned = false;
+    if (obj) {
+      Py_INCREF(obj);
+      ref._owned = true;
+    }
+    return ref;
+  }
+
+  /** Increment reference count and get raw pointer */
+  PyObject* incref() const noexcept {
+    Py_XINCREF(_obj);
+    return _obj;
+  }
+
+  /** Get raw pointer without changing reference count */
+  PyObject* get() const noexcept { return _obj; }
+
+  /** Release ownership without decrementing ref count */
+  PyObject* release() noexcept {
+    PyObject* obj = _obj;
+    _obj = nullptr;
+    _owned = false;
+    return obj;
+  }
+
+  /** Reset - decrements ref count if owned */
+  void reset() noexcept {
+    if (_owned && _obj) {
+      Py_DECREF(_obj);
+    }
+    _obj = nullptr;
+    _owned = false;
+  }
+
+  /** Check if the object is valid (non-null) */
+  explicit operator bool() const noexcept { return _obj != nullptr; }
+
+  /** Check for Python exception state */
+  bool hasException() const noexcept {
+    return _obj == nullptr && PyErr_Occurred() != nullptr;
+  }
+
+  // Non-copyable
+  PyRef(const PyRef&) = delete;
+  PyRef& operator=(const PyRef&) = delete;
+
+  // Movable
+  PyRef(PyRef&& other) noexcept : _obj(other._obj), _owned(other._owned) {
+    other._obj = nullptr;
+    other._owned = false;
+  }
+
+  PyRef& operator=(PyRef&& other) noexcept {
+    if (this != &other) {
+      reset();
+      _obj = other._obj;
+      _owned = other._owned;
+      other._obj = nullptr;
+      other._owned = false;
+    }
+    return *this;
+  }
+
+private:
+  PyObject* _obj;
+  bool _owned;
+};
+
+} // namespace pynect