@p10i/create-nestbox 0.1.1 → 0.2.0

package/.dockerignore

@@ -15,6 +15,9 @@
 # npm / Composer caches that may live in the working tree
 node_modules
 vendor
+.runtime
+**/__pycache__
+*.pyc
 
 # Page state is local by default and must not leak into image layers. A page
 # that deliberately ships durable data must explicitly revise this policy.

package/.env.example

@@ -8,6 +8,13 @@ COMPOSE_PROJECT_NAME=nestbox-change-me
 # directory, or .. when this installation is <workspace>/.nestbox.
 WORKSPACE_PATH=.
 
+# Absolute host-state directory shared only by the native runner and control.
+# The creator generates this value outside the mounted workspace.
+NESTBOX_HOST_QUEUE_PATH=
+
+# Override for rootless or nonstandard Docker Engine installations.
+DOCKER_SOCKET_PATH=/var/run/docker.sock
+
 # Use 127.0.0.1 for local access only or 0.0.0.0 for all interfaces.
 BIND_ADDRESS=127.0.0.1
 
@@ -26,6 +33,11 @@ NESTBOX_OPENCODE_PUBLIC_URL=
 APP_UID=1000
 APP_GID=1000
 
+# Control logs use standard container output and require no collector. Use text
+# for bounded command output, metadata for lifecycle events only, or off.
+NESTBOX_CONTROL_LOG_OUTPUT=text
+NESTBOX_CONTROL_LOG_MAX_BYTES=262144
+
 # Secrets
 # OpenCode receives every variable in this file. Keep unrelated secrets out.
 # Leave the server password empty to disable HTTP basic authentication.

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.2.0
+
+- Add a private, label-gated container control service and OpenCode MCP adapter.
+- Add native host npm execution through a filesystem bridge with no network listener.
+- Add host-confirmed npm script creation, editing, and deletion.
+- Add reusable PHP control helpers and restrict PHP to self-exec by default.
+- Support both `.nestbox` and direct creator layouts with safe workspace manifest merging.
+- Add bounded structured control logs without introducing an observability dependency.

package/INSTALL.md

@@ -12,7 +12,7 @@ npm create @p10i/nestbox@latest
 
 The published npm package is `@p10i/create-nestbox`; npm maps `npm create @p10i/nestbox` to that package. The creator explains and previews one of the two default layouts before writing files. The recommended layout installs at `<workspace>/.nestbox` so Nestbox stays separate from project files. The direct layout writes Nestbox files into an empty selected directory. The creator copies `.env.example` to `.env`, copies `home/configs/opencode/instance.example.md` to `instance.md`, records npm package provenance in the instance policy, and initializes fresh installation Git history when Git is available.
 
-The creator does not start Docker or collect secrets. After it finishes, edit `.env`, then run from the installation directory:
+The creator does not start Docker, start the host bridge, or collect secrets. Node.js and npm are required for the bridge. After it finishes, edit `.env`, run `npm run host --` from the workspace in a separate terminal, then run from the installation directory:
 
 ```sh
 docker compose config --quiet
@@ -54,7 +54,7 @@ docker version
 docker compose version
 ```
 
-Nestbox requires Git, a running Docker Engine, and Docker Compose v2. If something is missing, explain the platform-specific requirement and pause. Do not install system software without approval.
+Nestbox requires Git, Node.js with npm, a running Docker Engine, and Docker Compose v2. If something is missing, explain the platform-specific requirement and pause. Do not install system software without approval.
 
 Inspect Git status for the selected directory and installation target before changing files. Preserve unrelated changes. The fresh Nestbox repository remains independent in both default layouts, including when `.nestbox` is nested inside another Git workspace.
 
@@ -94,6 +94,15 @@ Copy `.env.example` to `.env` and `home/configs/opencode/instance.example.md` to
 
 Relative bind paths resolve from the installation directory. The page tree is mounted as `/home/code` in runtime services and as the writable `/nestbox/home/code` agent path. `WORKSPACE_PATH` is mounted as `/workspace` in PHP and OpenCode. `NESTBOX_PAGE_PATH` remains an optional advanced override for a user-requested external page tree.
 
+Configure the host bridge in the workspace root before Compose starts:
+
+- For `.nestbox` layout, create `package.json` from `.nestbox/package.host.json` when absent, or merge only its `host` and `test:host` scripts into the existing manifest.
+- For direct layout, use `node host-runner.mjs` and `node tests/host-runner.mjs` for those scripts. A source clone's publisher-oriented `package.json` may be replaced by this installation manifest after preserving any intentional project metadata.
+- Never overwrite a conflicting script. Stop and ask for a different script name or an explicit migration.
+- Create a private host-state queue outside the workspace, record it in the ignored installation `.runtime/host-runner.json`, and set its absolute path as `NESTBOX_HOST_QUEUE_PATH` in `.env`. The npm creator performs this automatically.
+- Start `npm run host --` before Compose so the queue and heartbeat exist. The runner rejects queue locations inside the mounted workspace.
+- The workspace manifest is mounted read-only in runtime containers. Confirmed changes are written only by the native host runner.
+
 Update the new `home/configs/opencode/instance.md` with:
 
 - the communication language;
@@ -143,6 +152,12 @@ docker compose ps
 docker compose port nginx 80
 ```
 
+In a separate terminal, keep the bridge running from the workspace root:
+
+```sh
+npm run host --
+```
+
 Verify:
 
 - `/` retains HTTP 404 and renders the OpenCode implementation form;
@@ -150,6 +165,7 @@ Verify:
 - `php /sources/php/cli.php __templates/super-document` is rejected;
 - `/Agent` redirects to OpenCode on the same published port;
 - the actual OpenCode URL works in the user's client;
+- `npm run test:host` passes and control health reports the host runner as available;
 - a provider and model are available for agent work, without printing credentials or sending a billable prompt unless the user approves it;
 - `/_nestbox/health` returns HTTP 200;
 - a transient PHP event reaches an EventSource subscriber through Nchan;
@@ -227,7 +243,7 @@ Send this work to the internal OpenCode agent. A useful prompt is:
 Extend this Nestbox installation for the following requirement: <request>. Inspect /workspace and /nestbox, follow the internal Nestbox manual, implement and verify all file changes you can, and report the exact host-side activation command for any container or infrastructure change.
 ```
 
-The internal agent edits pages and infrastructure definitions. It has no Docker socket and must not claim host activation. The external maintainer resumes only to inspect the proposed infrastructure files, run `docker compose config`, apply the narrowest build or recreate operation, and verify health.
+The internal agent edits pages and infrastructure definitions. It has no Docker socket. It may use only the label-gated control MCP for approved container commands and declared host npm scripts; broader activation remains an external-maintainer task.
 
 ## 10. Git And Generated State
 

package/README.md

@@ -6,7 +6,15 @@ Nestbox is an agent-guided workspace for building focused interfaces around proj
 
 Its core design is the **super-document**: one cohesive PHP and Markdown document can provide server logic, command-line behavior, forms, HTML, and browser JavaScript. The internal OpenCode agent creates and extends these documents, integrates project runtimes, and prepares infrastructure changes.
 
-Nestbox runs with Docker Compose using Nginx, PHP-FPM, Rollup, and OpenCode. A fresh installation opens with a prompt for creating its first screen instead of shipping a predefined application.
+Nestbox runs with Docker Compose using Nginx, PHP-FPM, Rollup, OpenCode, and a private control service. A fresh installation opens with a prompt for creating its first screen instead of shipping a predefined application.
+
+## Container And Host Control
+
+The `control` service is the only container with `/var/run/docker.sock`. Its internal-only API permits exec only when caller, target, project, and root-user labels allow it. OpenCode reaches the API through the bundled control MCP and can target PHP-FPM and Rollup by default. Trusted PHP pages can use `nestbox_control_exec()` and are restricted to PHP-FPM self-exec.
+
+Native host commands are limited to scripts already declared in the workspace `package.json`. Keep `npm run host --` running from the workspace when host scripts are needed. The bridge exchanges typed files through creator-generated host state outside the container-mounted workspace; it opens no network listener. MCP can request script additions, edits, or deletions, but the host runner applies them only after the user supplies a short-lived code displayed exclusively in the host terminal.
+
+Control emits bounded structured events to ordinary container logs. Use `docker compose logs control`; no telemetry collector, database, or observability dependency is installed. Docker socket access is root-equivalent on the host, and host scripts execute in the trusted writable workspace, so neither mechanism is a sandbox.
 
 ## Learn More
 
@@ -24,7 +32,7 @@ Create a new Nestbox project with npm:
 npm create @p10i/nestbox@latest
 ```
 
-The creator previews the exact paths before it writes files. The recommended layout installs Nestbox at `<workspace>/.nestbox` so Nestbox stays separate from your project files. You can also choose a direct install into an empty directory. After creation, edit `.env`, then run the Docker Compose validation and startup commands printed by the creator.
+The creator previews the exact paths before it writes files. The recommended layout installs Nestbox at `<workspace>/.nestbox` so Nestbox stays separate from your project files. You can also choose a direct install into an empty directory. It creates a minimal workspace `package.json` when absent or safely merges non-conflicting `host` and `test:host` scripts into an existing manifest. After creation, edit `.env`, start `npm run host --`, then run the Docker Compose validation and startup commands printed by the creator.
 
 For agent-guided installation or repair work, copy and send this to an agent with filesystem, Git, Docker, and terminal access:
 

package/bin/create-nestbox.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { dirname, join, resolve } from 'node:path';
@@ -14,12 +16,15 @@ const copyEntries = [
   'docker',
   'home',
   'tests',
+  'host-runner.mjs',
+  'package.host.json',
   'docker-compose.yaml',
   '.dockerignore',
   '.env.example',
   '.gitattributes',
   'INSTALL.md',
   'README.md',
+  'CHANGELOG.md',
   'LICENSE'
 ];
 
@@ -140,6 +145,10 @@ async function configureInstance(installDir, workspaceDir, layout) {
     errorOnExist: true,
     force: false
   });
+  const envPath = join(installDir, '.env');
+  const workspaceValue = layout === 'nestbox' ? '..' : '.';
+  const configuredEnv = (await readFile(envPath, 'utf8')).replace(/^WORKSPACE_PATH=.*$/m, `WORKSPACE_PATH=${workspaceValue}`);
+  await writeFile(envPath, configuredEnv, 'utf8');
 
   const instanceExample = join(installDir, 'home', 'configs', 'opencode', 'instance.example.md');
   const instancePath = join(installDir, 'home', 'configs', 'opencode', 'instance.md');
@@ -164,6 +173,70 @@ async function configureInstance(installDir, workspaceDir, layout) {
   await writeFile(instancePath, instance, 'utf8');
 }
 
+function hostScripts(layout) {
+  const prefix = layout === 'nestbox' ? '.nestbox/' : '';
+  return {
+    host: `node ${prefix}host-runner.mjs`,
+    'test:host': `node ${prefix}tests/host-runner.mjs`
+  };
+}
+
+async function readWorkspacePackage(workspaceDir) {
+  const path = join(workspaceDir, 'package.json');
+  if (!(await pathExists(path))) return null;
+  let document;
+  try {
+    document = JSON.parse(await readFile(path, 'utf8'));
+  } catch (error) {
+    throw new Error(`Cannot use workspace package.json: ${error.message}`);
+  }
+  if (!document || typeof document !== 'object' || Array.isArray(document)) {
+    throw new Error('Workspace package.json must contain a JSON object.');
+  }
+  if (document.scripts !== undefined && (!document.scripts || typeof document.scripts !== 'object' || Array.isArray(document.scripts))) {
+    throw new Error('Workspace package.json scripts must be an object.');
+  }
+  return document;
+}
+
+async function preflightHostPackage(workspaceDir, layout) {
+  const document = await readWorkspacePackage(workspaceDir);
+  if (!document) return;
+  for (const [name, command] of Object.entries(hostScripts(layout))) {
+    if (document.scripts?.[name] !== undefined && document.scripts[name] !== command) {
+      throw new Error(`Refusing to overwrite existing workspace npm script: ${name}`);
+    }
+  }
+}
+
+async function configureHostPackage(installDir, workspaceDir, layout) {
+  const scripts = hostScripts(layout);
+  const document = await readWorkspacePackage(workspaceDir) || {
+    name: 'nestbox-workspace',
+    private: true
+  };
+  document.scripts = { ...(document.scripts || {}), ...scripts };
+  await writeFile(join(workspaceDir, 'package.json'), `${JSON.stringify(document, null, 2)}\n`, 'utf8');
+  await writeFile(join(installDir, 'package.host.json'), `${JSON.stringify({
+    name: 'nestbox-workspace',
+    private: true,
+    scripts
+  }, null, 2)}\n`, 'utf8');
+  const stateBase = process.env.NESTBOX_CREATOR_STATE_ROOT
+    || process.env.LOCALAPPDATA
+    || process.env.XDG_STATE_HOME
+    || (process.platform === 'darwin' ? join(homedir(), 'Library', 'Application Support') : join(homedir(), '.local', 'state'));
+  const queue = join(stateBase, 'nestbox', 'host-runner', randomUUID());
+  await mkdir(queue, { recursive: true });
+  const runtime = join(installDir, '.runtime');
+  await mkdir(runtime, { recursive: true });
+  await writeFile(join(runtime, 'host-runner.json'), `${JSON.stringify({ queue }, null, 2)}\n`, 'utf8');
+  const envPath = join(installDir, '.env');
+  const composeQueue = queue.replaceAll('\\', '/');
+  const configuredEnv = (await readFile(envPath, 'utf8')).replace(/^NESTBOX_HOST_QUEUE_PATH=.*$/m, () => `NESTBOX_HOST_QUEUE_PATH=${composeQueue}`);
+  await writeFile(envPath, configuredEnv, 'utf8');
+}
+
 function commandExists(command) {
   const result = spawnSync(command, ['--version'], { stdio: 'ignore' });
   return result.status === 0;
@@ -200,9 +273,12 @@ async function main() {
       throw new Error(`Refusing to overwrite non-empty installation target: ${installDir}`);
     }
 
+    await preflightHostPackage(workspaceDir, layoutInput);
+
     await mkdir(installDir, { recursive: true });
     await copyTemplate(installDir);
     await configureInstance(installDir, workspaceDir, layoutInput);
+    await configureHostPackage(installDir, workspaceDir, layoutInput);
     const gitInitialized = options.git ? initGit(installDir) : false;
 
     console.log('\nNestbox project created.');
@@ -210,6 +286,8 @@ async function main() {
     console.log(`Workspace: ${workspaceDir}`);
     console.log(`Git initialized: ${gitInitialized ? 'yes' : 'no'}`);
     console.log('\nNext steps:');
+    console.log(`  cd ${workspaceDir}`);
+    console.log('  npm run host --');
     console.log(`  cd ${installDir}`);
     console.log('  Edit .env and set COMPOSE_PROJECT_NAME, WEB_PORT, OpenCode credentials, and provider keys.');
     console.log('  docker compose config --quiet');

package/docker/control/Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.12-alpine
+
+COPY ./docker/control/server.py /usr/local/bin/nestbox-control
+
+RUN python -m py_compile /usr/local/bin/nestbox-control && \
+    chmod 0755 /usr/local/bin/nestbox-control
+
+WORKDIR /workspace
+
+EXPOSE 4088
+
+CMD ["/usr/local/bin/nestbox-control"]