@p10i/create-nestbox 0.1.2 → 0.3.0

package/docker-compose.yaml

@@ -37,6 +37,9 @@ services:
   # Executes super-document HTTP and CLI directions. Trusted pages may update
   # page state and intentionally operate on the mounted workspace.
   php-fpm:
+    depends_on:
+      control:
+        condition: service_healthy
     build:
       context: .
       dockerfile: ./docker/php-fpm/Dockerfile
@@ -56,6 +59,12 @@ services:
         target: /workspace
         bind:
           create_host_path: false
+      - type: bind
+        source: ${WORKSPACE_PATH:-.}/package.json
+        target: /workspace/package.json
+        read_only: true
+        bind:
+          create_host_path: false
     environment:
       # Event publication and OpenCode automation stay inside Compose.
       - NESTBOX_BUS_PUBLISH_URL=http://nginx:8080/_nestbox/publish
@@ -64,6 +73,11 @@ services:
       - NESTBOX_OPENCODE_PUBLIC_URL=${NESTBOX_OPENCODE_PUBLIC_URL:-}
       - OPENCODE_SERVER_USERNAME=${OPENCODE_SERVER_USERNAME:-opencode}
       - OPENCODE_SERVER_PASSWORD=${OPENCODE_SERVER_PASSWORD:-}
+      - NESTBOX_CONTROL_URL=http://control:4088
+    labels:
+      - nestbox.exec.allow-target=true
+      - nestbox.exec.allow-source=true
+      - nestbox.exec.targets=php-fpm
     restart: unless-stopped
 
   # Watches shared browser source and refreshes tracked bundle baselines.
@@ -88,11 +102,56 @@ services:
           create_host_path: false
       # Keep dependencies out of the host page tree.
       - rollup-node-modules:/sources/rollup/node_modules
+    labels:
+      - nestbox.exec.allow-target=true
+    restart: unless-stopped
+
+  # Private, label-gated bridge for container exec and native host npm jobs.
+  # This is the only Nestbox service with access to the host Docker socket.
+  control:
+    build:
+      context: .
+      dockerfile: ./docker/control/Dockerfile
+    expose:
+      - "4088"
+    ports:
+      # Authenticated native runner transport; never bind beyond loopback.
+      - "127.0.0.1:${NESTBOX_CONTROL_HOST_PORT:-4089}:4089"
+    volumes:
+      - ${DOCKER_SOCKET_PATH:-/var/run/docker.sock}:/var/run/docker.sock
+      - type: bind
+        source: ${WORKSPACE_PATH:-.}
+        target: /workspace
+        read_only: true
+        bind:
+          create_host_path: false
+      - type: bind
+        source: ${NESTBOX_HOST_TOKEN_FILE:?NESTBOX_HOST_TOKEN_FILE must be configured}
+        target: /run/secrets/nestbox-host-token
+        read_only: true
+        bind:
+          create_host_path: false
+    environment:
+      - COMPOSE_PROJECT_NAME=${COMPOSE_PROJECT_NAME}
+      - NESTBOX_CONTROL_SERVICE=control
+      - NESTBOX_CONTROL_HOST_PORT=4089
+      - NESTBOX_HOST_TOKEN_FILE=/run/secrets/nestbox-host-token
+      - NESTBOX_CONTROL_LOG_OUTPUT=${NESTBOX_CONTROL_LOG_OUTPUT:-text}
+      - NESTBOX_CONTROL_LOG_MAX_BYTES=${NESTBOX_CONTROL_LOG_MAX_BYTES:-262144}
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:4088/health"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+      start_period: 5s
     restart: unless-stopped
 
   # Internal implementation agent. It can edit Nestbox and the workspace but
   # deliberately receives no Docker socket or direct host control.
   opencode:
+    depends_on:
+      control:
+        condition: service_healthy
     build:
       context: .
       dockerfile: ./docker/opencode/Dockerfile
@@ -125,11 +184,22 @@ services:
         target: /workspace
         bind:
           create_host_path: false
+      - type: bind
+        source: ${WORKSPACE_PATH:-.}/package.json
+        target: /workspace/package.json
+        read_only: true
+        bind:
+          create_host_path: false
       # The entrypoint fixes this volume's ownership before dropping privileges.
       - opencode-data:/home/nestbox/.local/share/opencode
     working_dir: /workspace
     environment:
       - NESTBOX_BUS_PUBLISH_URL=http://nginx:8080/_nestbox/publish
+      - NESTBOX_CONTROL_URL=http://control:4088
+    labels:
+      - nestbox.exec.allow-source=true
+      - nestbox.exec.targets=php-fpm,rollup
+      - nestbox.npm.allow=true
     restart: unless-stopped
 
 volumes:

package/home/code/__includes/functions.php

@@ -192,6 +192,74 @@ function nestbox_opencode_request(string $method, string $path, array $body, str
     return json_decode($response, true, flags: JSON_THROW_ON_ERROR);
 }
 
+/** Send a bounded JSON request to the private, label-gated control service. */
+function nestbox_control_request(string $method, string $path, array $body = []): mixed
+{
+    $baseUrl = rtrim((string) getenv('NESTBOX_CONTROL_URL'), '/');
+    if ($baseUrl === '') {
+        throw new RuntimeException('NESTBOX_CONTROL_URL is not configured.');
+    }
+    if (!str_starts_with($path, '/') || preg_match('/[\0\r\n]/', $path)) {
+        throw new InvalidArgumentException('Invalid control request path.');
+    }
+
+    $payload = json_encode($body, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
+    $context = stream_context_create([
+        'http' => [
+            'method' => strtoupper($method),
+            'header' => implode("\r\n", [
+                'Accept: application/json',
+                'Content-Type: application/json',
+                'Content-Length: ' . strlen($payload),
+            ]),
+            'content' => $payload,
+            'ignore_errors' => true,
+            'timeout' => 30,
+        ],
+    ]);
+    $response = @file_get_contents($baseUrl . $path, false, $context, 0, 1024 * 1024);
+    $statusLine = $http_response_header[0] ?? '';
+    preg_match('#^HTTP/\S+\s+(\d{3})#', $statusLine, $matches);
+    $status = isset($matches[1]) ? (int) $matches[1] : 0;
+    if ($response === false || $status < 200 || $status >= 300) {
+        throw new RuntimeException("Control request failed with HTTP status $status.");
+    }
+    return $response === '' ? null : json_decode($response, true, flags: JSON_THROW_ON_ERROR);
+}
+
+/** Execute one explicit argument array in an allowed Compose service. */
+function nestbox_control_exec(
+    string $service,
+    string $workdir,
+    array $command,
+    bool $detach = false,
+    string $user = '',
+): array {
+    if (!preg_match('/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/', $service)) {
+        throw new InvalidArgumentException('Invalid control target service.');
+    }
+    if (!str_starts_with($workdir, '/') || str_contains($workdir, "\0")) {
+        throw new InvalidArgumentException('Control workdir must be an absolute container path.');
+    }
+    if ($command === [] || count($command) > 256) {
+        throw new InvalidArgumentException('Control command must be a non-empty bounded argument array.');
+    }
+    foreach ($command as $part) {
+        if (!is_string($part) || str_contains($part, "\0")) {
+            throw new InvalidArgumentException('Every control command argument must be a string.');
+        }
+    }
+    $body = ['command' => array_values($command), 'workdir' => $workdir, 'detach' => $detach];
+    if ($user !== '') {
+        $body['user'] = $user;
+    }
+    $result = nestbox_control_request('POST', '/containers/' . rawurlencode($service) . '/exec', $body);
+    if (!is_array($result) || !isset($result['runId']) || !is_string($result['runId'])) {
+        throw new RuntimeException('Control service returned an invalid exec response.');
+    }
+    return $result;
+}
+
 /** Create an OpenCode session synchronously so its ID is available immediately. */
 function nestbox_opencode_create_session(string $title, string $directory = '/workspace'): array
 {

package/home/configs/opencode/control-mcp.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+'use strict';
+
+const baseUrl = (process.env.NESTBOX_CONTROL_URL || 'http://control:4088').replace(/\/$/, '');
+const timeoutMs = Number(process.env.NESTBOX_CONTROL_TIMEOUT_MS || '30000');
+const tools = [
+  { name: 'docker_exec', description: 'Run a command in an allowed Compose service.', inputSchema: { type: 'object', properties: { machine: { type: 'string' }, workdir: { type: 'string' }, command: { type: 'array', items: { type: 'string' } }, user: { type: 'string' }, detach: { type: 'boolean' } }, required: ['machine', 'workdir', 'command'], additionalProperties: false } },
+  { name: 'npm_scripts', description: 'List host npm scripts from /workspace/package.json.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+  { name: 'npm_run', description: 'Run an allowed npm script through the active host bridge.', inputSchema: { type: 'object', properties: { script: { type: 'string' }, args: { type: 'array', items: { type: 'string' } }, detach: { type: 'boolean' } }, required: ['script'], additionalProperties: false } },
+  { name: 'npm_script_change_request', description: 'Request an add, edit, or delete of an npm script. The confirmation code is displayed only by the host runner.', inputSchema: { type: 'object', properties: { operation: { type: 'string', enum: ['add', 'edit', 'delete'] }, name: { type: 'string' }, command: { type: 'string' } }, required: ['operation', 'name'], additionalProperties: false } },
+  { name: 'npm_script_change_confirm', description: 'Confirm a pending npm script change with the host-visible code.', inputSchema: { type: 'object', properties: { requestId: { type: 'string' }, code: { type: 'string' } }, required: ['requestId', 'code'], additionalProperties: false } },
+];
+
+function request(method, path, body) {
+  const url = new URL(baseUrl + path);
+  const transport = require(url.protocol === 'https:' ? 'https' : 'http');
+  const payload = body === undefined ? undefined : JSON.stringify(body);
+  return new Promise((resolve, reject) => {
+    const headers = { accept: 'application/json' };
+    if (payload !== undefined) Object.assign(headers, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) });
+    const client = transport.request({ method, hostname: url.hostname, port: url.port || undefined, path: url.pathname + url.search, headers }, response => {
+      const chunks = [];
+      response.setEncoding('utf8');
+      response.on('data', chunk => chunks.push(chunk));
+      response.on('end', () => {
+        const text = chunks.join('');
+        let value = null;
+        try { value = text ? JSON.parse(text) : null; } catch { value = text; }
+        if (response.statusCode >= 400) reject(new Error(`Control API ${method} ${path} returned ${response.statusCode}: ${JSON.stringify(value)}`));
+        else resolve(value);
+      });
+    });
+    client.setTimeout(timeoutMs, () => client.destroy(new Error('Control API request timed out')));
+    client.on('error', reject);
+    if (payload !== undefined) client.write(payload);
+    client.end();
+  });
+}
+
+function object(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Tool arguments must be an object.');
+  return value;
+}
+
+async function call(name, raw) {
+  const args = object(raw || {});
+  if (name === 'docker_exec') {
+    if (typeof args.machine !== 'string' || !args.machine) throw new Error('machine must be a non-empty string.');
+    if (typeof args.workdir !== 'string' || !args.workdir.startsWith('/')) throw new Error('workdir must be an absolute path.');
+    if (!Array.isArray(args.command) || !args.command.length || !args.command.every(value => typeof value === 'string')) throw new Error('command must be a non-empty string array.');
+    const body = { command: args.command, workdir: args.workdir };
+    if (args.user) body.user = String(args.user);
+    if (args.detach !== undefined) body.detach = Boolean(args.detach);
+    return { machine: args.machine, workdir: args.workdir, command: args.command, result: await request('POST', `/containers/${encodeURIComponent(args.machine)}/exec`, body) };
+  }
+  if (name === 'npm_scripts') return request('GET', '/npm/scripts');
+  if (name === 'npm_run') {
+    if (typeof args.script !== 'string' || !args.script) throw new Error('script must be a non-empty string.');
+    if (args.args !== undefined && (!Array.isArray(args.args) || !args.args.every(value => typeof value === 'string'))) throw new Error('args must be a string array.');
+    return request('POST', '/npm/run', { script: args.script, ...(args.args === undefined ? {} : { args: args.args }), ...(args.detach === undefined ? {} : { detach: Boolean(args.detach) }) });
+  }
+  if (name === 'npm_script_change_request') {
+    if (!['add', 'edit', 'delete'].includes(args.operation) || typeof args.name !== 'string' || !args.name) throw new Error('operation and name are required.');
+    if (args.operation !== 'delete' && (typeof args.command !== 'string' || !args.command)) throw new Error('command is required for add and edit.');
+    if (args.operation === 'delete' && args.command !== undefined) throw new Error('command must be omitted for delete.');
+    return request('POST', '/npm/scripts/request', { operation: args.operation, name: args.name, ...(args.command === undefined ? {} : { command: args.command }) });
+  }
+  if (name === 'npm_script_change_confirm') {
+    if (typeof args.requestId !== 'string' || typeof args.code !== 'string') throw new Error('requestId and code are required.');
+    return request('POST', '/npm/scripts/confirm', { requestId: args.requestId, code: args.code });
+  }
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+function emit(value) { process.stdout.write(`${JSON.stringify(value)}\n`); }
+async function handle(message) {
+  if (message.method === 'initialize') return emit({ jsonrpc: '2.0', id: message.id, result: { protocolVersion: '2024-11-05', capabilities: { tools: { listChanged: false } }, serverInfo: { name: 'nestbox-control-mcp', version: '0.3.0' } } });
+  if (message.method === 'initialized') return;
+  if (message.method === 'tools/list') return emit({ jsonrpc: '2.0', id: message.id, result: { tools } });
+  if (message.method === 'tools/call') {
+    try {
+      const output = await call(message.params?.name, message.params?.arguments);
+      emit({ jsonrpc: '2.0', id: message.id, result: { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] } });
+    } catch (error) {
+      emit({ jsonrpc: '2.0', id: message.id, error: { code: -32603, message: error.message || 'Tool execution failed.' } });
+    }
+    return;
+  }
+  if (message.id !== undefined) emit({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: `Method not supported: ${message.method}` } });
+}
+
+let input = '';
+process.stdin.on('data', chunk => {
+  input += chunk.toString('utf8');
+  let boundary;
+  while ((boundary = input.indexOf('\n')) >= 0) {
+    const line = input.slice(0, boundary).replace(/\r$/, ''); input = input.slice(boundary + 1);
+    if (!line) continue;
+    try { Promise.resolve(handle(JSON.parse(line))).catch(error => emit({ jsonrpc: '2.0', id: null, error: { code: -32603, message: error.message } })); }
+    catch (error) { emit({ jsonrpc: '2.0', id: null, error: { code: -32700, message: error.message } }); }
+  }
+});

package/home/configs/opencode/instructions.md

@@ -168,11 +168,25 @@ The interactive 404 page demonstrates the intended flow: create a session scoped
 
 Use API-created sessions only for explicit page workflows. The shared header's Open Chat link remains the normal entry point for conversation.
 
+## Container Control API
+
+OpenCode has no Docker socket. Use the control MCP as the only path for commands in other containers or on the native host:
+
+- `docker_exec` accepts an allowed Compose `machine`, absolute `workdir`, positional `command` array, and optional `user` or `detach` value.
+- `npm_scripts` lists scripts from `/workspace/package.json`.
+- `npm_run` executes one declared script through the active native host runner. Prefer `detach: true` for work expected to exceed the MCP request timeout.
+- `npm_script_change_request` requests an add, edit, or delete. The confirmation code appears only in the host runner terminal.
+- `npm_script_change_confirm` applies the pending change after the user explicitly supplies that code.
+
+Do not call the control HTTP API directly from OpenCode, impersonate the native runner, invoke Docker or SSH as a substitute, or work around a missing MCP capability. PHP cannot invoke MCP, so trusted super-documents may use `nestbox_control_exec()`; default labels restrict PHP-FPM to self-exec. Only OpenCode has `nestbox.npm.allow=true` by default. Root exec requires an explicit target label.
+
+The control log is the audit source of truth and requires no observability service. The native runner uses an authenticated, loopback-only long-poll endpoint; no host listener or filesystem queue exists. Commands still operate in trusted containers and a trusted writable workspace; Docker socket access and editable host-script source mean this is a controlled capability, not a security sandbox.
+
 ## Git And Commit Policy
 
 - Resolve the owning Git root before staging any path.
 - Read the separately loaded `instance.md` before committing Nestbox work. It records the installation layout, repository roots, and commit policy without exposing `.env`.
-- Treat the repository as installation history. Do not assume an upstream remote or upstream commit ancestry exists; use the recorded source revision when reasoning about upgrades.
+- Treat the repository as installation history. Do not assume an upstream remote or upstream commit ancestry exists.
 - The policy may allow logical commits after verification, require confirmation before each commit, or require leaving changes uncommitted.
 - Reasonable Nestbox commits include super-documents, Compose, Dockerfiles, configurations, integrations, and dependency files.
 - Keep commits within one Git root. When one feature spans repositories, create separate commits and report their relationship.
@@ -182,12 +196,13 @@ Use API-created sessions only for explicit page workflows. The shared header's O
 
 ## Container Architecture
 
-The default Compose application has four services:
+The default Compose application has five services:
 
 - `nginx`: the only host-published gateway. It serves static page files, routes super-documents to PHP-FPM, proxies the OpenCode virtual host, and hosts Nchan.
 - `php-fpm`: executes HTTP and CLI directions. It mounts the page tree and workspace writable because trusted pages may intentionally modify them.
 - `rollup`: watches `scripts.js` and browser dependencies and writes local JS/CSS bundles into the page tree.
 - `opencode`: runs this agent, mounts the engine and workspace, and edits the page tree through `/nestbox/home/code`.
+- `control`: owns the Docker socket and privately brokers label-gated container exec and host-runner jobs.
 
 The default host port is `4180` after installer confirmation. Nginx container port `80` serves both Nestbox and OpenCode through host-based routing. Nginx container port `8080` is only the internal Nchan publisher.
 
@@ -214,6 +229,7 @@ The engine's untracked `/nestbox/.env` controls runtime paths, exposure, authent
 - `APP_UID` and `APP_GID`: PHP-FPM ownership for writable bind mounts.
 - `NESTBOX_URL_PREFIX`: public path prefix when an outer proxy strips that prefix before forwarding.
 - `NESTBOX_OPENCODE_PUBLIC_URL`: explicit public OpenCode origin when `agent.<nestbox-host>` cannot be derived.
+- `NESTBOX_CONTROL_URL`: internal control API URL, normally `http://control:4088`.
 - `OPENCODE_SERVER_USERNAME` and `OPENCODE_SERVER_PASSWORD`: OpenCode HTTP authentication shared with PHP's internal API client.
 
 Nginx publishes one host port and distinguishes two browser origins:
@@ -271,13 +287,13 @@ Mount every directory needed by both PHP and OpenCode at the same container path
 
 ## Container Boundary And Host Handoff
 
-This OpenCode container deliberately has no Docker socket and may not be able to run Docker CLI commands. Never claim to build, pull, start, stop, restart, recreate, inspect, or remove host containers from this session.
+This OpenCode container deliberately has no Docker socket. Use control MCP only for its declared, label-gated operations. Never claim a broader Docker or operating-system capability.
 
 You may edit Compose files, Dockerfiles, Nginx configuration, PHP configuration, dependency files, mount definitions, and OpenCode configuration. After an infrastructure edit:
 
 1. Validate every part that can be checked inside this container.
 2. Identify the exact affected services.
-3. Give the user the narrowest host-side command to run from the engine directory.
+3. Use a declared host npm script through MCP when one exists; otherwise give the user the narrowest host-side command.
 4. State that activation and host health checks remain pending.
 5. Tell the user to reconnect if OpenCode itself must restart.
 

package/home/configs/opencode/opencode.json

@@ -5,6 +5,17 @@
     "port": 4096
   },
   "instructions": ["instructions.md", "instance.md"],
+  "mcp": {
+    "control": {
+      "type": "local",
+      "command": ["node", "/etc/opencode/control-mcp.js"],
+      "enabled": true,
+      "environment": {
+        "NESTBOX_CONTROL_URL": "{env:NESTBOX_CONTROL_URL}",
+        "NESTBOX_CONTROL_TIMEOUT_MS": "30000"
+      }
+    }
+  },
   "permission": {
     "external_directory": {
       "*": "ask",

package/home/configs/rollup/package-lock.json

@@ -1088,16 +1088,15 @@
             "license": "CC0-1.0"
         },
         "node_modules/nanoid": {
-            "version": "3.3.12",
-            "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
-            "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
+            "version": "3.3.18",
+            "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz",
+            "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==",
             "funding": [
                 {
                     "type": "github",
                     "url": "https://github.com/sponsors/ai"
                 }
             ],
-            "license": "MIT",
             "peer": true,
             "bin": {
                 "nanoid": "bin/nanoid.cjs"
@@ -1210,9 +1209,9 @@
             }
         },
         "node_modules/postcss": {
-            "version": "8.5.14",
-            "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.14.tgz",
-            "integrity": "sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==",
+            "version": "8.5.26",
+            "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz",
+            "integrity": "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==",
             "funding": [
                 {
                     "type": "opencollective",
@@ -1227,10 +1226,9 @@
                     "url": "https://github.com/sponsors/ai"
                 }
             ],
-            "license": "MIT",
             "peer": true,
             "dependencies": {
-                "nanoid": "^3.3.11",
+                "nanoid": "^3.3.17",
                 "picocolors": "^1.1.1",
                 "source-map-js": "^1.2.1"
             },
@@ -2020,10 +2018,9 @@
             }
         },
         "node_modules/svgo": {
-            "version": "2.8.2",
-            "resolved": "https://registry.npmjs.org/svgo/-/svgo-2.8.2.tgz",
-            "integrity": "sha512-TyzE4NVGLUFy+H/Uy4N6c3G0HEeprsVfge6Lmq+0FdQQ/zqoVYB62IsBZORsiL+o96s6ff/V6/3UQo/C0cgCAA==",
-            "license": "MIT",
+            "version": "2.8.3",
+            "resolved": "https://registry.npmjs.org/svgo/-/svgo-2.8.3.tgz",
+            "integrity": "sha512-5EZD0pafXX6PphdwOGCiVLDSaV1xyuQao2blHajHLsPxr07q4mmEjdtXEWgG07ae2mIz8Ex2CDXNCTiXhy3Khw==",
             "dependencies": {
                 "commander": "^7.2.0",
                 "css-select": "^4.1.3",