@p10i/create-nestbox 0.1.2 → 0.3.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,14 @@ COMPOSE_PROJECT_NAME=nestbox-change-me
 # directory, or .. when this installation is <workspace>/.nestbox.
 WORKSPACE_PATH=.
 
+# Loopback-only endpoint used by the native host runner. The creator generates
+# a private token; do not expose this port beyond the local host.
+NESTBOX_CONTROL_HOST_PORT=4089
+NESTBOX_HOST_TOKEN_FILE=
+
+# 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 +34,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,17 @@
+# Changelog
+
+## 0.3.0
+
+- Replace the filesystem host queue with authenticated HTTP long polling managed by `control`.
+- Publish only the dedicated host-runner endpoint on loopback; keep the container API internal.
+- Remove queue paths, bind mounts, polling files, and stale lock/result state.
+- Generate a per-installation runner token file unavailable to application containers and preserve existing MCP and PHP contracts.
+
+## 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,13 +12,15 @@ 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`, then run from the installation directory:
 
 ```sh
 docker compose config --quiet
 docker compose up -d --build
 ```
 
+After `control` is healthy, run `npm run host --` from the workspace in a separate terminal.
+
 Then run the host test suite documented in section 7.
 
 ## 1. Choose Language
@@ -42,7 +44,7 @@ Both defaults keep pages, Compose, Dockerfiles, configuration, dependencies, and
 
 Do not present vendoring, a parent-owned engine, a submodule, an external page tree, or another shared-repository arrangement as a default. These are optional adaptations discussed only when the user requests one.
 
-Never overwrite an existing installation. Inspect an existing target and ask whether to update, repair, reuse, or stop.
+Never overwrite an existing installation. Select a different target or stop.
 
 ## 3. Check Requirements And Git
 
@@ -54,7 +56,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 +96,16 @@ 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.
+- Set `NESTBOX_HOST_TOKEN_FILE` to a private file outside every container-mounted workspace. The npm creator writes a 64-character token there with owner-only permissions. Only `control` mounts the file; never paste the token into chat or expose it through a page.
+- Confirm that `NESTBOX_CONTROL_HOST_PORT`, normally `4089`, is available. Compose publishes this authenticated runner endpoint on host loopback only.
+- Start `npm run host --` after `control` is healthy. The runner authenticates, long-polls for work, sends heartbeats, and posts results without opening a host listener or sharing queue files.
+- 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;
@@ -109,6 +121,7 @@ Then ask about:
 
 - a unique lowercase `COMPOSE_PROJECT_NAME`;
 - whether to use default port `4180`; verify availability and ask before choosing another port;
+- whether host-runner port `4089` is available; keep it loopback-only;
 - loopback-only or network access;
 - OpenCode username and password;
 - AI providers;
@@ -143,6 +156,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 +169,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 +247,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
 
@@ -255,4 +275,4 @@ When a super-document intentionally changes files in `/workspace`, follow that w
 
 ## 11. Optional Adaptations
 
-Retaining upstream Git history, adding an upstream remote, external page trees, parent-owned engines, submodules, vendoring, shared repositories, alternate Compose layouts, and operating-system shortcuts are optional. Explain their ownership and update consequences and obtain explicit confirmation before creating them. They must not obscure the two default installation paths.
+Retaining upstream Git history, adding an upstream remote, external page trees, parent-owned engines, submodules, vendoring, shared repositories, alternate Compose layouts, and operating-system shortcuts are optional. Explain their ownership consequences and obtain explicit confirmation before creating them. They must not obscure the two default installation paths.

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 native runner authenticates with an external token file mounted only into `control`, long-polls a loopback-only endpoint, and posts results; no host server or shared filesystem queue is used. 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,18 +32,10 @@ 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:
 
 ```text
 Install Nestbox by following https://github.com/piontkovsk11andre1/nestbox/blob/main/INSTALL.md completely. Ask all required questions before making changes, preserve unrelated files and Git history, and do not expose secrets.
 ```
-
-## Update
-
-Run an update request from the workspace containing Nestbox, then copy and send this prompt to an agent with filesystem, Git, Docker, and terminal access:
-
-```text
-Update this Nestbox installation from https://github.com/piontkovsk11andre1/nestbox. Locate the installation, inspect its local Git history and configuration, read the current remote INSTALL.md and internal Nestbox instructions, preserve pages, instance policy, secrets, volumes, and unrelated changes, explain the proposed update, and ask before destructive or system-level operations. Validate Compose and run the Nestbox host tests after applying the update.
-```

package/bin/create-nestbox.js

@@ -1,25 +1,35 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
+import { randomBytes, 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';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { cp, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { cp, mkdir, readdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const packageJson = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
 
+function containsPath(root, target) {
+  const child = relative(resolve(root), resolve(target));
+  return child === '' || (!child.startsWith(`..${sep}`) && child !== '..' && !isAbsolute(child));
+}
+
 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 +150,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=.*\r?$/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 +178,73 @@ 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 envPath = join(installDir, '.env');
+  const token = randomBytes(32).toString('hex');
+  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 tokenDirectory = join(stateBase, 'nestbox', 'host-control');
+  await mkdir(tokenDirectory, { recursive: true });
+  const tokenPath = join(await realpath(tokenDirectory), `${randomUUID()}.token`);
+  const canonicalWorkspace = await realpath(workspaceDir);
+  const canonicalInstall = await realpath(installDir);
+  if (containsPath(canonicalWorkspace, tokenPath) || containsPath(canonicalInstall, tokenPath)) throw new Error('Host token state directory must be outside the workspace and Nestbox installation.');
+  await writeFile(tokenPath, `${token}\n`, { encoding: 'utf8', mode: 0o600 });
+  const composeTokenPath = tokenPath.replaceAll('\\', '/');
+  const configuredEnv = (await readFile(envPath, 'utf8')).replace(/^NESTBOX_HOST_TOKEN_FILE=.*\r?$/m, () => `NESTBOX_HOST_TOKEN_FILE=${composeTokenPath}`);
+  await writeFile(envPath, configuredEnv, 'utf8');
+}
+
 function commandExists(command) {
   const result = spawnSync(command, ['--version'], { stdio: 'ignore' });
   return result.status === 0;
@@ -200,9 +281,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.');
@@ -214,6 +298,9 @@ async function main() {
     console.log('  Edit .env and set COMPOSE_PROJECT_NAME, WEB_PORT, OpenCode credentials, and provider keys.');
     console.log('  docker compose config --quiet');
     console.log('  docker compose up -d --build');
+    console.log(`  cd ${workspaceDir}`);
+    console.log('  npm run host --');
+    console.log(`  cd ${installDir}`);
     console.log(process.platform === 'win32' ? '  .\\tests\\nestbox.ps1' : '  bash tests/nestbox.sh');
   } finally {
     rl.close();

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"]