Statweave Runtime Detection

Statweave Runtime Detection provides shared Node.js helpers for detecting, launching, locating sockets for, and guiding the installation of the Python statweave-runtime package.

This package is primarily used by statweave-cli and statweave-web. It intentionally operates with zero runtime npm dependencies.

📖 Architecture & Topology

Detection Order

detectRuntime() resolves candidates in the following order to ensure the correct environment is selected:

1. statweave-runtime command
2. Available Python executable
3. Optional source checkout fallback (when sourceBackendRoot is provided)
4. python -m statweave_runtime version

Note: Python candidates are prioritized as: STATWEAVE_PYTHON > python3 > python. The source checkout fallback is intended for local repository development. Published packages should prefer the installed runtime command or Python module wrapper.

Concurrent Usage & Transport Topology

The Statweave ecosystem is designed for concurrent execution:

• statweave-cli communicates with the runtime via UNIX Sockets.
• statweave-web communicates with the runtime via the HTTP Transport.

Both clients can operate simultaneously without conflict, relying on the runtime daemon to orchestrate state.

Safety Policy

This package enforces strict safety rules during execution and installation:

• No automatic installation: Never runs pip install without explicit user confirmation.
• TTY Awareness: Non-TTY environments do not prompt; they print manual install guidance instead.
• Failsafes: If no Python executable is found, or if installation fails, manual recovery instructions are printed.
• System Scope: System package installation is explicitly out of scope. Installation expects a virtual environment (venv) or manual user intervention.

🚀 Installation & Requirements

Install the package via npm:

npm install statweave-runtime-detection

Requirements

• Node.js: >=20
• OS: Debian/Linux or another POSIX shell environment with sh and command -v.
  • ⚠️ Windows is explicitly out of scope and not supported.
• Python Runtime: A valid Python runtime install path. Candidates include:
  • statweave-runtime
  • python -m statweave_runtime
  • Optional source checkout fallback supplied by the caller
• Virtual Environment (Recommended): To avoid externally-managed-environment errors (PEP 668) on modern Linux distributions, it is highly recommended to run the Python runtime within a virtual environment (venv).

💻 Usage & Examples

Detecting the Runtime

Library code should prefer detectRuntime() when it only needs to inspect the environment.

import { detectRuntime } from "statweave-runtime-detection";

const runtime = detectRuntime();
if (!runtime) {
  console.error("statweave-runtime is not installed");
}

For local development, you can use a source checkout fallback:

const runtime = detectRuntime({
  sourceBackendRoot: "/workspace/statweave/subprojects/statweave-runtime/src",
});

The Runtime Shape

When a runtime is successfully detected, detectRuntime() returns an object reflecting its execution context (or null if unavailable):

• Command: { kind: "command", command: "statweave-runtime" }
• Module: { kind: "module", python: "python3", module: "statweave_runtime" }
• Source:

  {
    kind: "source",
    python: "python3",
    module: "statweave_runtime",
    pythonPath: "/workspace/statweave/subprojects/statweave-runtime/src"
  }

Launching the Runtime Daemon

Use the detected runtime shape to generate the correct startup commands and environment variables.

import { detectRuntime, runtimeStartCommand, runtimeEnv } from "statweave-runtime-detection";
import { spawn } from "node:child_process";
import os from "node:os";
import path from "node:path";

const runtime = detectRuntime();
// Defaults to the standard Statweave directory (~/.statweave/runtime.sock)
const defaultSocket = path.join(os.homedir(), ".statweave", "runtime.sock");
const command = runtimeStartCommand(runtime, { socket: defaultSocket });

// For `kind: "source"`, this automatically launches `python -m statweave_runtime start` 
// with PYTHONPATH set by `runtimeEnv(runtime)`.
spawn(command.command, command.args, {
  stdio: ["ignore", "ignore", "inherit"],
  env: runtimeEnv(runtime),
});

Resolving the Socket Path

import { runtimeSocketPath } from "statweave-runtime-detection";

const socketPath = runtimeSocketPath({
  socket: process.argvSocketOverride,
  env: process.env,
}); // Will resolve to ~/.statweave/runtime.sock if no overrides are provided.

Ensuring Installation (CLI Flows)

Use ensureRuntime() for CLI-style flows where prompting the user and optionally running pip install statweave-runtime is acceptable.

import { ensureRuntime } from "statweave-runtime-detection";

const runtime = await ensureRuntime();

(Manual runtime install command within an active venv: pip install statweave-runtime)

🔍 Exported API

The package exports the following utility functions:

• detectRuntime(options?) – Detects an existing runtime.
• ensureRuntime(options?) – Detects first, then may prompt before installing.
• commandExists(command, runner?)
• pythonCandidates(env?)
• firstPython(runner?, env?)
• moduleExists(python, moduleName?, runner?)
• runtimeStartCommand(runtime, options?)
• runtimeServerCommand(runtime)
• runtimeEnv(runtime, env?)
• runtimeDir(env?)
• runtimeSocketPath(options?)
• printManualInstall(stream?)
• confirmInstall(stdin?, stdout?)
• runDoctor(options?)

🛠 Development Guide

Setup & Local Development

Run the workspace script from the repository root:

cd /workspace/statweave
npm install
npm run check:runtime-detection

Run package-local scripts from this package directory:

cd subprojects/statweave-runtime-detection
npm run check
npm run pack:dry-run

Build & Publish

1. Prepare Dependencies:

Run the workspace script from the repository root first so dependencies are installed and linked:

cd /workspace/statweave
npm install
npm run check:runtime-detection

2. Publish:

Publish from this package directory:

cd subprojects/statweave-runtime-detection
npm run pack:dry-run
npm publish --access public

Pre-publish Checklist:

• Confirm version in package.json has been bumped when needed.
• Confirm npm whoami succeeds with the intended npm account.
• Confirm the dry-run tarball contains only LICENSE, index.js, README.md, and package.json.
• Package name must be statweave-runtime-detection.