pynect 0.0.0-stage → 0.2.0

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', 'ProjectEnvironment.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,113 @@
+'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 = {}) {
+  return loadPyfig().createPyfig(pynectPyfigOptions(options));
+}
+
+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/NativeAddonLoader.ts

@@ -0,0 +1,98 @@
+import path from 'path';
+import fs from 'fs';
+import { spawnSync } from 'child_process';
+import type { NativeAddon } from '../types/addon';
+
+export interface NativeAddonBuildOptions {
+  projectRoot: string;
+  pythonExecutable: string;
+}
+
+/**
+ * Load an addon built for the selected Python, compiling it through the active
+ * JavaScript runtime when no exact match exists.
+ */
+export function loadOrBuildNativeAddon(options: NativeAddonBuildOptions): NativeAddon {
+  let initialError: unknown = new Error('Native rebuild explicitly requested.');
+  if (process.env['PYNECT_FORCE_BUILD'] !== '1') {
+    try {
+      return loadMatchingLocalAddon(options);
+    } catch (error) {
+      initialError = error;
+    }
+  }
+
+  const packageRoot = path.resolve(__dirname, '..', '..');
+  const script = path.join(packageRoot, 'scripts', 'ensure-native.js');
+  const result = spawnSync(process.execPath, [script], {
+    cwd: packageRoot,
+    env: {
+      ...process.env,
+      PYNECT_PROJECT_ROOT: options.projectRoot,
+      PYNECT_PYTHON: options.pythonExecutable,
+    },
+    stdio: 'inherit',
+    windowsHide: true,
+  });
+  if (result.error) {
+    throw new Error(
+      `Could not launch the native builder with ${process.execPath}: ${result.error.message}`,
+      { cause: initialError },
+    );
+  }
+  if (result.status !== 0) {
+    throw new Error(
+      `Pynect could not load or build its native addon with ${process.execPath}. ` +
+      'Install a C++ toolchain or provide a compatible prebuilt addon.',
+      { cause: initialError },
+    );
+  }
+
+  try {
+    return loadMatchingLocalAddon(options);
+  } catch (error) {
+    throw new Error('Pynect built the native addon, but the active runtime could not load it.', {
+      cause: error,
+    });
+  }
+}
+
+interface NativeBuildMetadata {
+  schemaVersion: number;
+  pythonExecutable: string;
+  buildType: 'Debug' | 'Release';
+}
+
+function loadMatchingLocalAddon(options: NativeAddonBuildOptions): NativeAddon {
+  const packageRoot = path.resolve(__dirname, '..', '..');
+  const metadataPath = path.join(packageRoot, 'build', 'pynect-python.json');
+  let metadata: NativeBuildMetadata;
+  try {
+    metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8')) as NativeBuildMetadata;
+  } catch (error) {
+    throw new Error(`Native build metadata is unavailable at ${metadataPath}.`, { cause: error });
+  }
+  if (
+    metadata.schemaVersion !== 1 ||
+    normalizePath(metadata.pythonExecutable) !== normalizePath(options.pythonExecutable)
+  ) {
+    throw new Error(
+      `Native addon Python ${metadata.pythonExecutable} does not match selected Python ` +
+      `${options.pythonExecutable}.`,
+    );
+  }
+
+  const addonPath = path.join(
+    packageRoot,
+    'build',
+    metadata.buildType === 'Debug' ? 'Debug' : 'Release',
+    'pynect_addon.node',
+  );
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  return require(addonPath) as NativeAddon;
+}
+
+function normalizePath(value: string): string {
+  const resolved = path.resolve(value);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}

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