@p10i/create-nestbox 0.4.0 → 0.6.0

package/.dockerignore

@@ -1,17 +1,17 @@
-# Build context hygiene — keep image builds small and reproducible.
-
-# VCS / IDE
+# Build context hygiene — keep image builds small and reproducible.
+
+# VCS / IDE
 .git
 **/.git
-.gitignore
-.vscode
-.idea
-
-# Local environment
+.gitignore
+.vscode
+.idea
+
+# Local environment
 .env
 .env.*
 !.env.example
-
+
 # npm / Composer caches that may live in the working tree
 node_modules
 vendor
@@ -22,15 +22,15 @@ vendor
 # 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.
 home/code/**/__data/**
-
-# OS junk
-.DS_Store
-Thumbs.db
-
-# Bundles are produced inside the build, not pulled from the host.
-home/code/scripts-bundle.js
-home/code/scripts-bundle.css
-
+
+# OS junk
+.DS_Store
+Thumbs.db
+
+# Bundles are produced inside the build, not pulled from the host.
+home/code/scripts-bundle.js
+home/code/scripts-bundle.css
+
 # Docs and metadata not needed at build time
 README.md
 LICENSE

package/.env.example

@@ -8,10 +8,6 @@ COMPOSE_PROJECT_NAME=nestbox-change-me
 # directory, or .. when this installation is <workspace>/.nestbox.
 WORKSPACE_PATH=.
 
-# The native runner uses the shared WEB_PORT gateway. The creator generates a
-# private token file outside the workspace and mounts it only into control.
-NESTBOX_HOST_TOKEN_FILE=
-
 # Override for rootless or nonstandard Docker Engine installations.
 DOCKER_SOCKET_PATH=/var/run/docker.sock
 

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.6.0
+
+- Consistently track latest-stable runtime images, dynamically select Alpine's newest PHP CLI branch, and document fresh builds with `--pull --no-cache`.
+- Remove native host npm execution, npm script confirmation tools, the host runner, its stdio bridge, and the loopback job API. Keep label-gated container execution and structured control logs.
+- Stop creating or modifying workspace package manifests during installation. Remove package.json-specific bind mounts and the control service's workspace mount.
+- Run the installed runtime entirely in Docker; host Node.js is needed only when using the npm creator.
+- Load OpenCode instructions and instance policy by absolute `/etc/opencode` paths, incorporating Gitea fix `4d53e89`.
+- See `INSTALL.md` for existing-installation cleanup and activation steps.
+
+## 0.5.0
+
+- Replace the public token-authenticated host API with a persistent `docker compose exec -T control` stdio bridge.
+- Bind the bridge API to container loopback and add reconnect-safe runner sessions with idempotent result replay.
+- Remove host tokens, the Nginx host proxy, and all `4089` exposure while retaining one Nginx-published host port.
+- Existing `0.3.x` and `0.4.x` installations may remove `NESTBOX_HOST_TOKEN_FILE` and its referenced token file after upgrading.
+
 ## 0.4.0
 
 - Route the authenticated host runner through `/_nestbox/host/` on the existing Nginx gateway.

package/INSTALL.md

@@ -12,15 +12,14 @@ 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, 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:
+The creator does not start Docker or collect secrets. Node.js and npm are needed only to run the creator, not the installed runtime. After it finishes, edit `.env`, then run from the installation directory:
 
 ```sh
 docker compose config --quiet
-docker compose up -d --build
+docker compose build --pull --no-cache
+docker compose up -d
 ```
 
-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
@@ -56,7 +55,7 @@ docker version
 docker compose version
 ```
 
-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.
+Nestbox requires Git, a running Docker Engine, and Docker Compose v2. The npm creator additionally requires Node.js with npm; installation from Git does not. 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.
 
@@ -96,14 +95,7 @@ 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.
-- Start `npm run host --` after `control` is healthy. The runner authenticates through `/_nestbox/host/` on the existing `WEB_PORT`, long-polls for work, sends heartbeats, and posts results without opening a host listener, publishing a second port, or sharing queue files.
-- The workspace manifest is mounted read-only in runtime containers. Confirmed changes are written only by the native host runner.
+The runtime does not require a workspace `package.json`. Project manifests are accessed through the ordinary workspace mounts in PHP-FPM and OpenCode. The control service mounts only the Docker socket and provides label-gated container execution.
 
 Update the new `home/configs/opencode/instance.md` with:
 
@@ -126,7 +118,7 @@ Then ask about:
 - Linux UID and GID when bind-mount ownership matters;
 - additional directories required by PHP and OpenCode;
 - an optional reverse-proxy URL prefix;
-- rolling or pinned container images;
+- the default latest-stable image policy, with pinning only as an explicitly requested adaptation;
 - `NESTBOX_OPENCODE_PUBLIC_URL` when `agent.<nestbox-host>` cannot be derived.
 
 Open `.env` in a local editor for runtime settings and secrets. Never ask the user to paste provider keys into chat or print the completed file.
@@ -135,7 +127,9 @@ Before startup, query existing Docker containers with the proposed Compose proje
 
 For additional directories, mount the same host path at the same container path in PHP and OpenCode. Extend OpenCode's `external_directory` permission when unattended access is intended. Prefer read-only mounts unless writing is required.
 
-Keep PHP-FPM and OpenCode's PHP CLI on the same PHP version. For a path-prefixed reverse proxy, the outer proxy removes the prefix before forwarding and configures `NESTBOX_URL_PREFIX`. Set `NESTBOX_OPENCODE_PUBLIC_URL` explicitly whenever the public OpenCode scheme or host differs from direct Nestbox access.
+Nestbox defaults to rolling latest-stable image tags and the latest system packages available in their configured repositories. OpenCode selects the newest PHP branch available from Alpine; PHP-FPM follows the official rolling PHP image. Verify both runtime versions after each build because Alpine packaging can lag upstream PHP. Resolve any incompatible branch mismatch before handoff. Use `docker compose build --pull --no-cache` to refresh base images and cached package-install layers. Application library lockfiles remain authoritative and are updated separately.
+
+For a path-prefixed reverse proxy, the outer proxy removes the prefix before forwarding and configures `NESTBOX_URL_PREFIX`. Set `NESTBOX_OPENCODE_PUBLIC_URL` explicitly whenever the public OpenCode scheme or host differs from direct Nestbox access.
 
 ## 6. Keep The Public Page Tree Empty
 
@@ -149,17 +143,12 @@ Run from the installation directory:
 
 ```sh
 docker compose config --quiet
-docker compose up -d --build
+docker compose build --pull --no-cache
+docker compose up -d
 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;
@@ -167,7 +156,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;
+- `control` is healthy and its API is not published on the host;
 - 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;
@@ -245,7 +234,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. 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.
+The internal agent edits pages and infrastructure definitions. It has no Docker socket. It uses the label-gated control MCP for approved container commands; host-side activation remains an external-maintainer task.
 
 ## 10. Git And Generated State
 
@@ -274,3 +263,22 @@ 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 consequences and obtain explicit confirmation before creating them. They must not obscure the two default installation paths.
+
+## Upgrading From Host-Runner Versions
+
+Host npm execution and npm script confirmation tools have been removed. Container execution through `docker_exec` and `nestbox_control_exec()` remains available.
+
+1. Stop the old `npm run host --` terminal or any service configured to launch it.
+2. Apply the source update while preserving installation-specific Compose overrides, `.env`, pages, and `instance.md`. Remove obsolete `host-runner.mjs`, `package.host.json`, `docker/control/host_bridge.py`, and `tests/host-runner.mjs` if the update mechanism leaves deleted files behind.
+3. Remove only the Nestbox-generated `host` and `test:host` scripts from the workspace `package.json`, after checking that they still point to the removed runner and test. Preserve project scripts and metadata. If the manifest was generated solely for the runner, it may be removed after confirming nothing else uses it.
+4. Remove `nestbox.npm.allow`, package.json-specific read-only mounts, and the control service's workspace mount from any local overrides. Keep the ordinary workspace mounts in PHP-FPM and OpenCode. Older installations may also remove obsolete host-token settings and mounts described in the changelog.
+5. From the installation directory, validate and activate the affected services:
+
+```sh
+docker compose config --quiet
+docker compose build --pull --no-cache control opencode
+docker compose up -d control php-fpm opencode
+bash tests/nestbox.sh
+```
+
+On Windows, run `.\tests\nestbox.ps1` instead of the Bash test. Reconnect to OpenCode after recreation so it loads the updated MCP tools and instructions. Inspect `docker compose ps` and `docker compose logs control` to confirm health. Project workloads formerly executed on the host must use an appropriate project container or be run manually by the host maintainer.

package/README.md

@@ -8,13 +8,29 @@ Its core design is the **super-document**: one cohesive PHP and Markdown documen
 
 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
+## Container 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 `/_nestbox/host/` through the shared Nginx gateway port, and posts results; no host server, second published port, 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.
+Project commands run inside the appropriate container through `docker_exec`. Host-side Docker Compose activation is performed by the user or external maintainer. Nestbox needs no background process on the host and no workspace `package.json`.
 
-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.
+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, so this is a controlled capability, not a sandbox.
+
+## Runtime Versions And Updates
+
+Nestbox tracks the latest stable container images by default: OpenCode and Composer use `latest`, Alpine uses `latest`, and Node, Python, and PHP use their rolling Alpine variants. Alpine-installed tools use the newest packages available in the base image's configured repositories; OpenCode's PHP CLI selects the newest available PHP branch. These repositories can lag upstream releases, so verify the resulting PHP CLI and FPM versions after a refresh.
+
+Refresh images and installed system packages from the installation directory:
+
+```sh
+docker compose config --quiet
+docker compose build --pull --no-cache
+docker compose up -d
+docker compose exec -T php-fpm php --version
+docker compose exec -T opencode php --version
+```
+
+Reconnect to OpenCode after recreation, then run `bash tests/nestbox.sh` or `.\tests\nestbox.ps1`. Existing containers do not update automatically. JavaScript and PHP library dependencies continue to use their committed lockfiles; runtime refreshes do not rewrite those dependencies.
 
 ## Learn More
 
@@ -32,7 +48,9 @@ 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. 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.
+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. The workspace's package manifest is left untouched. After creation, edit `.env`, then run the Docker Compose validation and startup commands printed by the creator. Node.js and npm are needed only to use the creator; the installed runtime runs entirely in Docker.
+
+For upgrades from versions with host npm execution, see the migration notes in [INSTALL.md](INSTALL.md#upgrading-from-host-runner-versions).
 
 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,28 +1,19 @@
 #!/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, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { cp, mkdir, readdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
+import { cp, mkdir, readdir, readFile, 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',
@@ -178,73 +169,6 @@ 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;
@@ -281,12 +205,9 @@ 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.');
@@ -297,10 +218,8 @@ async function main() {
     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');
-    console.log('  docker compose up -d --build');
-    console.log(`  cd ${workspaceDir}`);
-    console.log('  npm run host --');
-    console.log(`  cd ${installDir}`);
+    console.log('  docker compose build --pull --no-cache');
+    console.log('  docker compose up -d');
     console.log(process.platform === 'win32' ? '  .\\tests\\nestbox.ps1' : '  bash tests/nestbox.sh');
   } finally {
     rl.close();

package/docker/control/Dockerfile

@@ -1,11 +1,11 @@
-FROM python:3.12-alpine
+FROM python: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
+WORKDIR /
 
 EXPOSE 4088