autobots-devtools-shared-lib 0.7.0__tar.gz → 0.8.0__tar.gz

{autobots_devtools_shared_lib-0.7.0 → autobots_devtools_shared_lib-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autobots-devtools-shared-lib
-Version: 0.7.0
+Version: 0.8.0
 Summary: Shared library functions to be used for all autobots projects
 License: MIT
 Author: Pralhad

{autobots_devtools_shared_lib-0.7.0 → autobots_devtools_shared_lib-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "autobots-devtools-shared-lib"
-version = "0.7.0"
+version = "0.8.0"
 description = "Shared library functions to be used for all autobots projects"
 readme = "README.md"
 authors = [

autobots_devtools_shared_lib-0.8.0/src/autobots_devtools_shared_lib/common/servers/noderedmanagerserver/README.md

@@ -0,0 +1,180 @@
+# Node-RED Instance Manager Server
+
+A FastAPI server that manages dynamic Node-RED instances. It launches instances on demand
+using pre-configured templates, assigns them ports from a per-template range, and kills
+them on request.
+
+## Overview
+
+Each Node-RED instance is launched as:
+```
+FLOW=<flows_json_path> node-red -u <template_path> --port <port>
+```
+
+Templates are directories containing a `settings.js` and `package.json`, and each template
+owns its own port range to avoid conflicts.
+
+## Setup
+
+**Prerequisites:**
+- `node-red` binary on `PATH` (or configure `node_red_executable` in the YAML)
+
+```bash
+npm install -g node-red
+```
+
+**Install the shared lib:**
+```bash
+pip install -e "autobots-devtools-shared-lib"
+```
+
+## Configuration
+
+Create a `node-red-config.yaml` file:
+
+```yaml
+# Path to the node-red binary (optional, defaults to "node-red")
+node_red_executable: /usr/local/bin/node-red
+
+# Host and port for the manager server itself.
+# server_host is also used to build instance URLs — set it to the VM IP or hostname
+# if this server runs remotely so callers get the correct URL back.
+server_host: 0.0.0.0   # optional, defaults to "0.0.0.0"
+server_port: 9003      # optional, defaults to 9003
+
+templates:
+  - name: compose-template
+    path: /path/to/compose-template
+    base_port: 1880
+    max_port: 1920
+
+  - name: basic-template
+    path: /path/to/basic-template
+    base_port: 1921
+    max_port: 1980
+```
+
+Point the server to the file via env var (defaults to `node-red-config.yaml` in cwd):
+
+```bash
+export NODE_RED_CONFIG_FILE=/path/to/node-red-config.yaml
+```
+
+### Template Directory Format
+
+Each template directory must contain at minimum:
+```
+my-template/
+├── settings.js     # Node-RED settings (required)
+└── package.json    # Node-RED package deps (required)
+```
+
+## Run
+
+```bash
+# From autobots-devtools-shared-lib (host/port taken from node-red-config.yaml)
+make node-red-server
+
+# Or directly
+python -m autobots_devtools_shared_lib.common.servers.noderedmanagerserver
+```
+
+## Environment Variables
+
+Only one env var remains — everything else is in the YAML:
+
+| Variable | Default | Description |
+|---|---|---|
+| `NODE_RED_CONFIG_FILE` | `node-red-config.yaml` | Path to the YAML config file |
+
+## API Endpoints
+
+### `GET /health`
+Returns server status, running instance count, and available template names.
+
+```bash
+curl http://localhost:9003/health
+```
+```json
+{
+  "status": "healthy",
+  "timestamp": "2026-04-30T10:00:00+00:00",
+  "running_instances": 2,
+  "available_templates": ["compose-template", "basic-template"]
+}
+```
+
+---
+
+### `POST /create-instance`
+Launch a new Node-RED instance.
+
+```bash
+curl -X POST http://localhost:9003/create-instance \
+  -H "Content-Type: application/json" \
+  -d '{"flows_json_path": "/projects/projectA/flows.json", "template_name": "compose-template"}'
+```
+
+**Response (201):**
+```json
+{
+  "id": "3f1a2b4c-...",
+  "url": "http://192.168.1.100:1880"
+}
+```
+
+**Errors:**
+- `400` — unknown `template_name` or `flows_json_path` does not exist
+- `503` — no ports available in the template's configured range
+
+---
+
+### `POST /kill-instance`
+Kill a running Node-RED instance by its id.
+
+```bash
+curl -X POST http://localhost:9003/kill-instance \
+  -H "Content-Type: application/json" \
+  -d '{"id": "3f1a2b4c-..."}'
+```
+
+**Response (200):**
+```json
+{"message": "Instance 3f1a2b4c-... killed successfully"}
+```
+
+**Errors:**
+- `404` — instance id not found
+
+---
+
+### `GET /instances`
+List all currently running instances.
+
+```bash
+curl http://localhost:9003/instances
+```
+```json
+{
+  "instances": [
+    {
+      "id": "3f1a2b4c-...",
+      "port": 1880,
+      "template_name": "compose-template",
+      "url": "http://localhost:1880",
+      "pid": 12345
+    }
+  ],
+  "count": 1
+}
+```
+
+---
+
+### `GET /docs`
+Interactive Swagger UI.
+
+## Shutdown Behaviour
+
+When the manager server stops, it sends `SIGTERM` to all tracked Node-RED instances
+(concurrently). Instances that do not exit within 5 seconds receive `SIGKILL`.

autobots_devtools_shared_lib-0.8.0/src/autobots_devtools_shared_lib/common/servers/noderedmanagerserver/__init__.py

@@ -0,0 +1,5 @@
+"""Node-RED instance manager server package."""
+
+from .app import app  # re-export for convenience
+
+__all__ = ["app"]

autobots_devtools_shared_lib-0.8.0/src/autobots_devtools_shared_lib/common/servers/noderedmanagerserver/__main__.py

@@ -0,0 +1,16 @@
+"""Entry point: reads host/port from node-red-config.yaml and starts the server."""
+
+import uvicorn
+
+from autobots_devtools_shared_lib.common.servers.noderedmanagerserver.config import (
+    NodeRedManagerServerConfig,
+)
+
+if __name__ == "__main__":
+    cfg = NodeRedManagerServerConfig()
+    uvicorn.run(
+        "autobots_devtools_shared_lib.common.servers.noderedmanagerserver.app:app",
+        host=cfg.node_red_manager_server_host,
+        port=cfg.node_red_manager_server_port,
+        reload=True,
+    )

autobots_devtools_shared_lib-0.8.0/src/autobots_devtools_shared_lib/common/servers/noderedmanagerserver/app.py

@@ -0,0 +1,325 @@
+"""
+Node-RED instance manager server.
+
+Manages dynamic Node-RED instances: launch on demand with a chosen template and flows file,
+track them in memory, and kill on request.
+
+Templates are configured in a YAML file (default: node-red-config.yaml in cwd):
+  NODE_RED_CONFIG_FILE=/path/to/node-red-config.yaml
+
+Run:
+  uvicorn autobots_devtools_shared_lib.common.servers.noderedmanagerserver.app:app \
+      --reload --host 0.0.0.0 --port 9003
+Or: make node-red-server (from autobots-devtools-shared-lib)
+"""
+
+import asyncio
+import contextlib
+import os
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, status
+
+from autobots_devtools_shared_lib.common.observability.logging_utils import get_logger
+from autobots_devtools_shared_lib.common.servers.noderedmanagerserver.config import (
+    NodeRedManagerServerConfig,
+    TemplateConfig,
+)
+from autobots_devtools_shared_lib.common.servers.noderedmanagerserver.models import (
+    CreateInstanceRequest,
+    CreateInstanceResponse,
+    InstanceInfo,
+    KillInstanceRequest,
+    KillInstanceResponse,
+)
+
+logger = get_logger(__name__)
+config = NodeRedManagerServerConfig()
+
+# In-memory registry: instance_id -> (InstanceInfo, subprocess handle)
+_registry: dict[str, tuple[InstanceInfo, asyncio.subprocess.Process]] = {}
+
+
+# ---------------------------------------------------------------------------
+# Port scanning
+# ---------------------------------------------------------------------------
+
+
+async def _is_port_available(port: int) -> bool:
+    """Return True if nothing is listening on the given TCP port."""
+    try:
+        _, writer = await asyncio.wait_for(asyncio.open_connection("127.0.0.1", port), timeout=0.1)
+    except (ConnectionRefusedError, OSError, TimeoutError):
+        return True  # refused / timeout → port is free
+    else:
+        writer.close()
+        await writer.wait_closed()
+        return False  # connected → port is in use
+
+
+async def _find_available_port(template: TemplateConfig) -> int:
+    """Scan sequentially within the template's port range; skip ports used by tracked instances."""
+    used_ports = {info.port for info, _ in _registry.values()}
+    for port in range(template.min_port, template.max_port + 1):
+        if port in used_ports:
+            continue
+        if await _is_port_available(port):
+            return port
+    raise RuntimeError(
+        f"No available ports in range [{template.min_port}, {template.max_port}] "
+        f"for environment '{template.name}'. All ports are occupied."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Process management
+# ---------------------------------------------------------------------------
+
+
+async def _launch_node_red(
+    template: TemplateConfig, flows_json_path: str, port: int, instance_id: str
+) -> asyncio.subprocess.Process:
+    """Launch node-red as an async subprocess.
+
+    INSTANCE_ID is passed as an env var so the environment's settings.js can set
+    httpAdminRoot and httpNodeRoot to '/<instance_id>' for URL isolation.
+    """
+    env = {**os.environ, "FLOW": flows_json_path, "INSTANCE_ID": instance_id}
+    return await asyncio.create_subprocess_exec(
+        config.node_red_executable,
+        "-u",
+        str(template.path),
+        "--port",
+        str(port),
+        env=env,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+
+async def _kill_instance(instance_id: str, process: asyncio.subprocess.Process) -> None:
+    """SIGTERM the process; escalate to SIGKILL after 5 seconds."""
+    try:
+        process.terminate()  # SIGTERM on Unix
+        await asyncio.wait_for(process.wait(), timeout=5.0)
+        logger.info("Instance %s terminated gracefully", instance_id)
+    except ProcessLookupError:
+        logger.info("Instance %s process already gone (pid=%s)", instance_id, process.pid)
+    except TimeoutError:
+        logger.warning("Instance %s did not terminate in 5s, sending SIGKILL", instance_id)
+        with contextlib.suppress(ProcessLookupError):
+            process.kill()
+        await process.wait()
+
+
+# ---------------------------------------------------------------------------
+# Lifespan
+# ---------------------------------------------------------------------------
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI):
+    """Startup: validate config and log. Shutdown: kill all tracked instances."""
+    logger.info(
+        "Node-RED server starting (host=%s, port=%s, base_path=%s, environments=%s)",
+        config.node_red_manager_server_host,
+        config.node_red_manager_server_port,
+        config.base_path,
+        [f"{t.name}[{t.min_port}-{t.max_port}]" for t in config.environments.values()],
+    )
+    try:
+        NodeRedManagerServerConfig.validate()
+    except ValueError:
+        logger.exception("Node-RED server config invalid")
+        raise
+
+    yield
+
+    logger.info("Node-RED server shutting down, terminating %d instance(s)", len(_registry))
+    tasks = [_kill_instance(iid, proc) for iid, (_, proc) in _registry.items()]
+    if tasks:
+        await asyncio.gather(*tasks, return_exceptions=True)
+    _registry.clear()
+    logger.info("Node-RED server shutdown complete")
+
+
+# ---------------------------------------------------------------------------
+# FastAPI app
+# ---------------------------------------------------------------------------
+
+app = FastAPI(
+    title="Node-RED Instance Manager API",
+    description=(
+        "Manages dynamic Node-RED instances: launch with a chosen template and flows file, "
+        "track in memory, and kill on request."
+    ),
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+    lifespan=lifespan,
+)
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+
+@app.get("/")
+def root() -> dict[str, Any]:
+    """Root endpoint with API information."""
+    return {
+        "name": "Node-RED Instance Manager API",
+        "version": "1.0.0",
+        "endpoints": {
+            "POST /create-instance": "Launch a Node-RED instance with a template and flows file",
+            "POST /kill-instance": "Kill a running Node-RED instance by id",
+            "GET /instances": "List all running instances",
+            "GET /health": "Health check",
+        },
+        "docs": "/docs",
+    }
+
+
+@app.get("/health")
+def health() -> dict[str, Any]:
+    """Health check; returns status, running instance count, and available templates."""
+    logger.info("health called")
+    return {
+        "status": "healthy",
+        "timestamp": datetime.now(UTC).isoformat(),
+        "running_instances": len(_registry),
+        "available_environments": list(config.environments.keys()),
+    }
+
+
+@app.get("/instances")
+def list_instances() -> dict[str, Any]:
+    """List all currently running Node-RED instances."""
+    instances = [
+        {
+            "id": info.id,
+            "port": info.port,
+            "environment_name": info.environment_name,
+            "url": info.url,
+            "pid": info.pid,
+        }
+        for info, _ in _registry.values()
+    ]
+    return {"instances": instances, "count": len(instances)}
+
+
+@app.post("/create-instance")
+async def create_instance(body: CreateInstanceRequest) -> CreateInstanceResponse:
+    """
+    Launch a new Node-RED instance.
+
+    Finds the next available port, launches node-red with the given template and flows file,
+    registers the instance, and returns its id and URL.
+    """
+    logger.info(
+        "create-instance called environment=%s flows=%s workspace=%s",
+        body.environment_name,
+        body.flows_json_path,
+        body.workspace_context,
+    )
+
+    # 1. Extract and validate workspace_base_path — used as the instance ID
+    workspace_base_path: str = (body.workspace_context.get("workspace_base_path") or "").strip()
+    if not workspace_base_path:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="workspace_context.workspace_base_path is required and cannot be empty.",
+        )
+    if ".." in workspace_base_path:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="workspace_base_path cannot contain '..'",
+        )
+    instance_id = workspace_base_path
+
+    # 2. Return existing instance if one is already running for this workspace
+    if instance_id in _registry:
+        existing_info, _ = _registry[instance_id]
+        logger.info(
+            "create-instance reusing existing id=%s url=%s", existing_info.id, existing_info.url
+        )
+        return CreateInstanceResponse(id=existing_info.id, url=existing_info.url)
+
+    # 3. Validate environment name
+    environment = config.environments.get(body.environment_name)
+    if environment is None:
+        logger.warning("create-instance unknown environment=%s", body.environment_name)
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=(
+                f"Unknown environment '{body.environment_name}'. "
+                f"Available: {list(config.environments.keys())}"
+            ),
+        )
+
+    # 4. Resolve full flows path: base_path / workspace_base_path / flows_json_path
+    flows_path = Path(config.base_path) / workspace_base_path / body.flows_json_path
+    if not flows_path.exists():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"flows.json not found at resolved path: {flows_path}",
+        )
+
+    # 5. Find next available port within this environment's port range
+    try:
+        port = await _find_available_port(environment)
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(e)) from e
+
+    # 6. Launch subprocess — INSTANCE_ID env var picked up by the environment's settings.js
+    try:
+        process = await _launch_node_red(environment, str(flows_path), port, instance_id)
+    except Exception as e:
+        logger.exception("create-instance failed to launch node-red")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to launch Node-RED: {e!s}",
+        ) from e
+
+    # 7. Register and return
+    url = f"http://{config.node_red_manager_server_host}:{port}/{instance_id}"
+    info = InstanceInfo(
+        id=instance_id,
+        port=port,
+        environment_name=body.environment_name,
+        url=url,
+        pid=process.pid or 0,
+    )
+    _registry[instance_id] = (info, process)
+    logger.info("create-instance success id=%s url=%s pid=%s", instance_id, url, process.pid)
+    return CreateInstanceResponse(id=instance_id, url=url)
+
+
+@app.post("/kill-instance")
+async def kill_instance(body: KillInstanceRequest) -> KillInstanceResponse:
+    """Kill a running Node-RED instance by workspace_base_path."""
+    instance_id: str = (body.workspace_context.get("workspace_base_path") or "").strip()
+    if not instance_id:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="workspace_context.workspace_base_path is required and cannot be empty.",
+        )
+    logger.info("kill-instance called id=%s", instance_id)
+
+    entry = _registry.get(instance_id)
+    if entry is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Instance '{instance_id}' not found",
+        )
+
+    _, process = entry
+    await _kill_instance(instance_id, process)
+    del _registry[instance_id]
+
+    logger.info("kill-instance success id=%s", instance_id)
+    return KillInstanceResponse(message=f"Instance {instance_id} killed successfully")

autobots_devtools_shared_lib-0.8.0/src/autobots_devtools_shared_lib/common/servers/noderedmanagerserver/config.py

@@ -0,0 +1,146 @@
+"""Configuration for the Node-RED instance manager server, loaded from a YAML file."""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+from dotenv import find_dotenv, load_dotenv
+
+load_dotenv(find_dotenv())
+
+
+@dataclass
+class TemplateConfig:
+    """Configuration for a single Node-RED environment/template."""
+
+    name: str
+    path: Path
+    min_port: int
+    max_port: int
+
+
+def _load_yaml_config(
+    config_file: Path,
+) -> tuple[str, str, str, int, dict[str, TemplateConfig]]:
+    """
+    Load node-red-config.yaml and return
+    (node_red_executable, base_path, manager_host, manager_port, environments_by_name).
+
+    Expected YAML structure::
+
+        node_red_executable: /usr/local/bin/node-red  # optional, defaults to "node-red"
+
+        # Root directory prepended to all workspace paths when resolving flows.json.
+        base_path: /data/workspaces
+
+        # Host and port for the manager server itself and for building instance URLs.
+        node_red_manager_server_host: 0.0.0.0   # optional, defaults to "0.0.0.0"
+        node_red_manager_server_port: 9003       # optional, defaults to 9003
+
+        environments:
+          - name: compose-engine-template
+            path: /path/to/compose-engine-template
+            min_port: 1880
+            max_port: 1920
+
+          - name: basic-template
+            path: /path/to/basic-template
+            min_port: 1921
+            max_port: 1980
+    """
+    if not config_file.exists():
+        raise FileNotFoundError(
+            f"Node-RED config file not found: {config_file}. "
+            "Set NODE_RED_CONFIG_FILE env var to point to your node-red-config.yaml."
+        )
+
+    with config_file.open() as f:
+        data = yaml.safe_load(f) or {}
+
+    node_red_executable: str = data.get("node_red_executable", "node-red") or "node-red"
+    base_path: str = data.get("base_path", "") or ""
+    manager_host: str = (
+        data.get("node_red_manager_server_host", "0.0.0.0") or "0.0.0.0"  # noqa: S104
+    )
+    manager_port: int = int(data.get("node_red_manager_server_port", 9003))
+
+    raw_environments: list[dict] = data.get("environments") or []
+    environments: dict[str, TemplateConfig] = {}
+    for entry in raw_environments:
+        name = str(entry.get("name", "")).strip()
+        raw_path = str(entry.get("path", "")).strip()
+        min_port = int(entry.get("min_port", 1880))
+        max_port = int(entry.get("max_port", 1980))
+        if not name:
+            raise ValueError("Each environment entry must have a non-empty 'name' field.")
+        if not raw_path:
+            raise ValueError(f"Environment '{name}' is missing the 'path' field.")
+        environments[name] = TemplateConfig(
+            name=name,
+            path=Path(raw_path).resolve(),
+            min_port=min_port,
+            max_port=max_port,
+        )
+
+    return node_red_executable, base_path, manager_host, manager_port, environments
+
+
+# Resolve config file path from env var; default to node-red-config.yaml in cwd.
+_config_file = Path(os.getenv("NODE_RED_CONFIG_FILE", "node-red-config.yaml"))
+
+# Load at module import time so config is available immediately.
+# If the file is absent the server will fail fast during lifespan startup (validate() call).
+try:
+    _node_red_executable, _base_path, _manager_host, _manager_port, _environments = (
+        _load_yaml_config(_config_file)
+    )
+except FileNotFoundError:
+    _node_red_executable = "node-red"
+    _base_path = ""
+    _manager_host = "0.0.0.0"  # noqa: S104
+    _manager_port = 9003
+    _environments = {}
+
+
+class NodeRedManagerServerConfig:
+    """Configuration for the Node-RED instance manager server."""
+
+    # All settings loaded from YAML
+    node_red_executable: str = _node_red_executable
+    base_path: str = _base_path
+    node_red_manager_server_host: str = _manager_host
+    node_red_manager_server_port: int = _manager_port
+    environments: dict[str, TemplateConfig] = _environments
+
+    @classmethod
+    def validate(cls) -> None:
+        """Fail fast on startup if configuration is unusable."""
+        if not _config_file.exists():
+            raise ValueError(
+                f"Node-RED config file not found: {_config_file}. "
+                "Set NODE_RED_CONFIG_FILE env var to point to your node-red-config.yaml."
+            )
+
+        if not cls.base_path:
+            raise ValueError(
+                "base_path is required in node-red-config.yaml. "
+                "Set it to the root directory for workspace paths."
+            )
+
+        if not cls.environments:
+            raise ValueError(
+                "No environments defined in node-red-config.yaml. "
+                "Add at least one entry under 'environments:'."
+            )
+
+        for name, tmpl in cls.environments.items():
+            if tmpl.min_port >= tmpl.max_port:
+                raise ValueError(
+                    f"Environment '{name}': min_port ({tmpl.min_port}) must be less than "
+                    f"max_port ({tmpl.max_port})."
+                )
+            if not tmpl.path.exists():
+                raise ValueError(f"Environment '{name}' path does not exist: {tmpl.path}")
+            if not (tmpl.path / "settings.js").exists():
+                raise ValueError(f"Environment '{name}' is missing settings.js at: {tmpl.path}")

autobots_devtools_shared_lib-0.8.0/src/autobots_devtools_shared_lib/common/servers/noderedmanagerserver/models.py

@@ -0,0 +1,63 @@
+"""Pydantic request/response models for the Node-RED instance manager API."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class CreateInstanceRequest(BaseModel):
+    workspace_context: dict[str, Any] = Field(
+        ...,
+        description=(
+            "Workspace scoping context. Must include `workspace_base_path` "
+            "(e.g. 'userName/repoName-jira'). Used as the instance ID and to resolve "
+            "the full flows.json path: base_path/workspace_base_path/flows_json_path."
+        ),
+        json_schema_extra={"examples": [{"workspace_base_path": "alice/my-project-JIRA-42"}]},
+    )
+    flows_json_path: str = Field(
+        ...,
+        description="Relative path to flows.json within the workspace directory.",
+    )
+    environment_name: str = Field(..., description="Name of the Node-RED environment to use.")
+
+    @field_validator("flows_json_path")
+    @classmethod
+    def validate_flows_json_path(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("flows_json_path cannot be empty")
+        if ".." in v:
+            raise ValueError("flows_json_path cannot contain '..'")
+        return v.strip()
+
+    @field_validator("environment_name")
+    @classmethod
+    def validate_environment_name(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("environment_name cannot be empty")
+        return v.strip()
+
+
+class CreateInstanceResponse(BaseModel):
+    id: str = Field(..., description="Instance ID (workspace_base_path).")
+    url: str = Field(..., description="URL to access the Node-RED instance (includes port).")
+
+
+class KillInstanceRequest(BaseModel):
+    workspace_context: dict[str, Any] = Field(
+        ...,
+        description="Workspace scoping context. Must include `workspace_base_path`.",
+        json_schema_extra={"examples": [{"workspace_base_path": "alice/my-project-JIRA-42"}]},
+    )
+
+
+class KillInstanceResponse(BaseModel):
+    message: str
+
+
+class InstanceInfo(BaseModel):
+    id: str
+    port: int
+    environment_name: str
+    url: str
+    pid: int