@p10i/create-nestbox 0.1.0

package/.dockerignore

@@ -0,0 +1,34 @@
+# Build context hygiene — keep image builds small and reproducible.
+
+# VCS / IDE
+.git
+**/.git
+.gitignore
+.vscode
+.idea
+
+# Local environment
+.env
+.env.*
+!.env.example
+
+# npm / Composer caches that may live in the working tree
+node_modules
+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
+
+# Docs and metadata not needed at build time
+README.md
+LICENSE
+tests

package/.env.example

@@ -0,0 +1,35 @@
+# Copy this file to .env next to docker-compose.yaml and adjust as needed.
+
+# Docker Compose
+# Set a unique slug for this project before starting Nestbox.
+COMPOSE_PROJECT_NAME=nestbox-change-me
+
+# Workspace exposed to PHP and OpenCode. Use . when Nestbox fills the selected
+# directory, or .. when this installation is <workspace>/.nestbox.
+WORKSPACE_PATH=.
+
+# Use 127.0.0.1 for local access only or 0.0.0.0 for all interfaces.
+BIND_ADDRESS=127.0.0.1
+
+# Published port shared by Nestbox and OpenCode. The installer confirms this
+# default is available and asks before selecting another port.
+WEB_PORT=4180
+
+# Optional public path when a reverse proxy strips this prefix before forwarding.
+NESTBOX_URL_PREFIX=
+
+# Optional absolute browser origin when the agent.* host cannot be derived from
+# the incoming Nestbox host, for example https://agent.project.example.
+NESTBOX_OPENCODE_PUBLIC_URL=
+
+# Runtime ownership
+APP_UID=1000
+APP_GID=1000
+
+# Secrets
+# OpenCode receives every variable in this file. Keep unrelated secrets out.
+# Leave the server password empty to disable HTTP basic authentication.
+OPENCODE_SERVER_USERNAME=opencode
+OPENCODE_SERVER_PASSWORD=
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=

package/.gitattributes

@@ -0,0 +1,10 @@
+* text=auto
+*.css text eol=lf
+*.js text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.php text eol=lf
+*.ps1 text eol=lf
+*.sh text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf

package/INSTALL.md

@@ -0,0 +1,258 @@
+# Agent Installation Guide
+
+Follow this protocol when installing Nestbox into a selected directory or at `<workspace>/.nestbox`.
+
+## Npm Creator
+
+For ordinary new projects, prefer the npm creator:
+
+```sh
+npm create @p10i/nestbox@latest
+```
+
+The published npm package is `@p10i/create-nestbox`; npm maps `npm create @p10i/nestbox` to that package. The creator scaffolds one of the two default layouts, 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:
+
+```sh
+docker compose config --quiet
+docker compose up -d --build
+```
+
+Then run the host test suite documented in section 7.
+
+## 1. Choose Language
+
+Before technical questions, ask which language to use for installation communication. Then distinguish three independent choices:
+
+- agent communication only in that language;
+- a translated Nestbox interface;
+- an extensible i18n setup for multiple interface languages.
+
+Record the communication and interface choices in `home/configs/opencode/instance.md`. Nestbox source is English by default. Translation and i18n are feature work for the internal OpenCode agent after basic startup, not a reason for the external installer to maintain a second implementation path.
+
+## 2. Choose One Default Layout
+
+Resolve and report the absolute selected directory. Offer exactly two defaults:
+
+1. **Current directory:** install Nestbox directly into the selected directory, then initialize fresh installation history at `<selected>/.git`.
+2. **`.nestbox`:** treat the selected directory as the workspace, install Nestbox at `<workspace>/.nestbox`, then initialize fresh installation history at `<workspace>/.nestbox/.git`.
+
+Both defaults keep pages, Compose, Dockerfiles, configuration, dependencies, and documentation in the same fresh installation repository. Pages remain under the installation's `home/code`. Upstream Nestbox commit history is not imported into the user's installation history.
+
+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.
+
+## 3. Check Requirements And Git
+
+Run:
+
+```sh
+git --version
+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.
+
+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.
+
+If the `.nestbox` target is inside another Git repository, ask whether to exclude `.nestbox/` through that repository's local `.git/info/exclude` or tracked `.gitignore`. Do not modify the parent repository without approval.
+
+## 4. Create The Installation
+
+For the current-directory layout, shallow-clone the source into the selected empty directory:
+
+```sh
+git clone --depth 1 https://github.com/piontkovsk11andre1/nestbox .
+```
+
+For the `.nestbox` layout, run from the confirmed workspace:
+
+```sh
+git clone --depth 1 https://github.com/piontkovsk11andre1/nestbox .nestbox
+```
+
+Immediately after cloning:
+
+1. Resolve and record the source revision with `git rev-parse HEAD` from the clone.
+2. Remove only the `.git` directory created by this new clone. Never remove Git metadata from a pre-existing path.
+3. Run `git init` in the installation directory.
+4. Continue configuration and verification before creating the installation baseline commit.
+
+The resulting `.git` contains only this installation's history. Keeping upstream history or adding an upstream remote is an optional adaptation, not a default.
+
+## 5. Configure The Instance
+
+Copy `.env.example` to `.env` and `home/configs/opencode/instance.example.md` to `home/configs/opencode/instance.md` in the installation directory. Both defaults use the installation's `./home/code` page tree. Configure the workspace mount as follows:
+
+| Layout | `WORKSPACE_PATH` |
+| --- | --- |
+| Current directory | `.` |
+| `<workspace>/.nestbox` | `..` |
+
+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.
+
+Update the new `home/configs/opencode/instance.md` with:
+
+- the communication language;
+- interface language or requested i18n direction;
+- installation and workspace paths;
+- the Nestbox Git root;
+- the recorded upstream source revision;
+- whether verified Nestbox changes are committed automatically, require per-commit confirmation, or remain uncommitted.
+
+This is agent guidance and belongs in `instance.md`, not `.env`.
+
+Then ask about:
+
+- a unique lowercase `COMPOSE_PROJECT_NAME`;
+- whether to use default port `4180`; verify availability and ask before choosing another port;
+- loopback-only or network access;
+- OpenCode username and password;
+- AI providers;
+- 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;
+- `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.
+
+Before startup, query existing Docker containers with the proposed Compose project label. Reject the name if an existing container belongs to another Compose working directory or uses a service not defined by this installation. Do not remove foreign containers or volumes automatically.
+
+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.
+
+## 6. Keep The Public Page Tree Empty
+
+The installation already contains Nestbox support files in `home/code`: `404.php`, protected includes and templates, browser sources, and generated asset baselines. Do not create `index.php` or another public project page.
+
+Opening `/` must retain HTTP 404 and render the form that starts an OpenCode session for the first screen. Any route segment beginning with `__` remains private over HTTP and through the CLI router.
+
+## 7. Start And Verify
+
+Run from the installation directory:
+
+```sh
+docker compose config --quiet
+docker compose up -d --build
+docker compose ps
+docker compose port nginx 80
+```
+
+Verify:
+
+- `/` retains HTTP 404 and renders the OpenCode implementation form;
+- `/__templates/super-document` returns 404;
+- `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;
+- 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;
+- every `__data` directory remains inaccessible over HTTP;
+- no service repeatedly restarts.
+
+Compare the resolved Compose bind sources with the running containers after startup. Recreate a service when its actual mounts do not match the current Compose model; do not claim a path change is active merely because `docker compose config` is valid.
+
+Run the host test suite:
+
+```sh
+bash tests/nestbox.sh
+```
+
+```powershell
+.\tests\nestbox.ps1
+```
+
+The scripts support both the fresh 404-first tree and later installations with `index.php`. `--start` for Bash and `-Start` for PowerShell may build and start application services first. Lifecycle mode never runs `down`, removes volumes, or starts an absent Rollup watcher that could rewrite bundles.
+
+Some clients resolve `.localhost` internally even when an operating-system DNS query does not. Test the actual OpenCode URL. If it fails to resolve, ask before adding this hosts-file entry:
+
+```text
+127.0.0.1 agent.localhost
+```
+
+For another device, configure explicit names for both Nestbox and OpenCode instead of relying on `agent.localhost`.
+
+## 8. Integrate The Host Agent
+
+Before handoff, register this Nestbox location with the external installation agent so future host-maintenance requests resolve the correct installation through the agent's own integration mechanism.
+
+Use the best integration mechanism supported by that agent, in this order:
+
+1. a project-local or user-local agent skill;
+2. an agent-native project command, workspace integration, plugin, or configuration entry;
+3. a small start/status/maintenance script that invokes the agent with the required context.
+
+The integration must record or supply:
+
+- the absolute installation, workspace, and Git-root paths;
+- the Nestbox and OpenCode URLs;
+- the selected communication language;
+- the path to this `INSTALL.md` and `home/configs/opencode/instructions.md`;
+- that page, feature, translation, package, service, and integration work belongs to the internal OpenCode agent;
+- that the external agent handles installation, repair, operating-system integration, and host-side Compose validation and activation;
+- the recorded commit behavior and repository boundary;
+- the normal host test command.
+
+Do not put `.env` contents, credentials, provider keys, or passwords into the integration. Prefer project-local scope. Ask before modifying global agent configuration, user-wide skills, shell profiles, or operating-system paths.
+
+Verify that the resulting skill, command, or script can identify this exact installation and state its maintenance boundary. Report what was created and where. If the current agent cannot persist an integration, provide the user with the exact reusable prompt or command needed to restore this context later.
+
+## 9. Handoff And Extension Request
+
+Report:
+
+- Nestbox and OpenCode URLs without credentials;
+- installation, workspace, and Git-root paths;
+- selected communication and interface language;
+- commit behavior;
+- remaining uncommitted changes.
+
+Ask the user to open OpenCode. Then ask what they want to change or extend in Nestbox. Typical requests include:
+
+- creating the first screen or another super-document;
+- translating the interface or adding i18n;
+- integrating a Python program, database, worker, native tool, or host service;
+- installing browser, PHP, system, or agent-toolchain packages;
+- adding mounts, networks, proxy routes, or persistent volumes.
+
+Send this work to the internal OpenCode agent. A useful prompt is:
+
+```text
+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.
+
+## 10. Git And Generated State
+
+The fresh Git root is the installation's `.git` in current-directory mode or `.nestbox/.git` in `.nestbox` mode. It owns reasonable Nestbox source changes, including:
+
+- super-documents and selected durable `__data` files explicitly opted into Git history;
+- reusable helpers and browser source;
+- generated browser bundle baselines, which keep the initial interface available before the watcher starts;
+- Compose files and Dockerfiles;
+- Nginx, PHP, Rollup, and OpenCode configuration;
+- portable integration definitions and dependency lockfiles;
+- documentation and translation resources.
+
+Follow the commit behavior recorded in `instance.md`:
+
+- automatic: create a focused commit after verification;
+- confirmation: show the exact paths and ask before each commit;
+- no-commit: leave changes uncommitted.
+
+After basic verification, create or offer one focused baseline commit containing the installed source and non-secret instance configuration. A concise default message is `Initialize Nestbox`. If the selected policy requires confirmation or forbids commits, leave the baseline pending and report that clearly.
+
+Stage exact intended files only. Preserve unrelated changes. Never commit `.env`, provider credentials, caches, incidental state, or unrelated project files. Never amend, change Git configuration, discard changes, or push without explicit approval.
+
+When a super-document intentionally changes files in `/workspace`, follow that workspace repository's own policy separately.
+
+## 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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nestbox contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# Nestbox
+
+## Introduction
+
+Nestbox is an agent-guided workspace for building focused interfaces around projects, tools, data, and containerized services.
+
+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.
+
+## Learn More
+
+Copy and send this to an agent with web access:
+
+```text
+Learn about Nestbox from https://github.com/piontkovsk11andre1/nestbox. Read its current documentation and explain its super-document design, agent workflow, container integration model, best use cases, and limitations. Do not install or modify anything.
+```
+
+## Installation
+
+Create a new Nestbox project with npm:
+
+```sh
+npm create @p10i/nestbox@latest
+```
+
+The creator offers the two default layouts: install directly into the selected directory or install at `<workspace>/.nestbox`. After creation, edit `.env`, 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

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+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'));
+
+const copyEntries = [
+  'docker',
+  'home',
+  'tests',
+  'docker-compose.yaml',
+  '.dockerignore',
+  '.env.example',
+  '.gitattributes',
+  'INSTALL.md',
+  'README.md',
+  'LICENSE'
+];
+
+function parseArgs(argv) {
+  const options = {
+    target: '',
+    layout: '',
+    yes: false,
+    git: true,
+    help: false
+  };
+
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--yes' || arg === '-y') options.yes = true;
+    else if (arg === '--no-git') options.git = false;
+    else if (arg === '--layout') options.layout = argv[++index] || '';
+    else if (arg.startsWith('--layout=')) options.layout = arg.slice('--layout='.length);
+    else if (arg === '--target') options.target = argv[++index] || '';
+    else if (arg.startsWith('--target=')) options.target = arg.slice('--target='.length);
+    else if (!arg.startsWith('-') && !options.target) options.target = arg;
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log(`Create a Nestbox project.\n\nUsage:\n  npm create @p10i/nestbox@latest [target] [options]\n  npx @p10i/create-nestbox [target] [options]\n\nOptions:\n  --layout current|nestbox  Install directly into target or into target/.nestbox\n  --target <path>          Target directory\n  --yes, -y                Use defaults for missing prompts\n  --no-git                 Do not initialize fresh installation Git history\n  --help, -h               Show this help\n`);
+}
+
+async function pathExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function isDirectoryEmpty(path) {
+  if (!(await pathExists(path))) return true;
+  const entries = await readdir(path);
+  return entries.length === 0;
+}
+
+function validateLayout(layout) {
+  if (layout !== 'current' && layout !== 'nestbox') {
+    throw new Error('Layout must be "current" or "nestbox".');
+  }
+}
+
+async function ask(question, defaultValue, rl, yes) {
+  if (yes) return defaultValue;
+  const suffix = defaultValue ? ` (${defaultValue})` : '';
+  const answer = (await rl.question(`${question}${suffix}: `)).trim();
+  return answer || defaultValue;
+}
+
+async function copyTemplate(installDir) {
+  for (const entry of copyEntries) {
+    await cp(join(packageRoot, entry), join(installDir, entry), {
+      recursive: true,
+      errorOnExist: true,
+      force: false,
+      mode: constants.COPYFILE_FICLONE
+    });
+  }
+
+  await cp(join(packageRoot, 'template.gitignore'), join(installDir, '.gitignore'), {
+    errorOnExist: true,
+    force: false
+  });
+}
+
+async function configureInstance(installDir, workspaceDir, layout) {
+  await cp(join(installDir, '.env.example'), join(installDir, '.env'), {
+    errorOnExist: true,
+    force: false
+  });
+
+  const instanceExample = join(installDir, 'home', 'configs', 'opencode', 'instance.example.md');
+  const instancePath = join(installDir, 'home', 'configs', 'opencode', 'instance.md');
+  let instance = await readFile(instanceExample, 'utf8');
+
+  const workspaceDescription = layout === 'nestbox'
+    ? 'the parent workspace directory'
+    : 'the installation directory';
+  const layoutDescription = layout === 'nestbox'
+    ? '.nestbox'
+    : 'current directory';
+
+  instance = instance
+    .replace('- Layout: current directory.', `- Layout: ${layoutDescription}.`)
+    .replace('- Workspace: `/workspace` maps to the installation directory.', `- Workspace: \`/workspace\` maps to ${workspaceDescription}.`)
+    .replace('- Upstream source revision: record during installation.', `- Upstream source revision: npm package ${packageJson.name}@${packageJson.version}.`)
+    .replace('- Commit policy: unconfigured; ask before any commit until the installer replaces this line with the user\'s automatic, per-commit confirmation, or no-commit choice.', '- Commit policy: per-commit confirmation; ask before each commit.')
+    .trimEnd();
+
+  instance += `\n\n- Host installation path: ${installDir}\n- Host workspace path: ${workspaceDir}\n`;
+
+  await writeFile(instancePath, instance, 'utf8');
+}
+
+function commandExists(command) {
+  const result = spawnSync(command, ['--version'], { stdio: 'ignore', shell: process.platform === 'win32' });
+  return result.status === 0;
+}
+
+function initGit(installDir) {
+  if (!commandExists('git')) return false;
+  const result = spawnSync('git', ['init'], { cwd: installDir, stdio: 'inherit', shell: process.platform === 'win32' });
+  if (result.status !== 0) throw new Error('git init failed.');
+  return true;
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const rl = createInterface({ input, output });
+  try {
+    const targetInput = options.target || await ask('Target directory', '.', rl, options.yes);
+    const layoutInput = options.layout || await ask('Layout: current or nestbox', 'nestbox', rl, options.yes);
+    validateLayout(layoutInput);
+
+    const workspaceDir = resolve(process.cwd(), targetInput);
+    const installDir = layoutInput === 'nestbox' ? join(workspaceDir, '.nestbox') : workspaceDir;
+
+    if (!(await isDirectoryEmpty(installDir))) {
+      throw new Error(`Refusing to overwrite non-empty installation target: ${installDir}`);
+    }
+
+    await mkdir(installDir, { recursive: true });
+    await copyTemplate(installDir);
+    await configureInstance(installDir, workspaceDir, layoutInput);
+    const gitInitialized = options.git ? initGit(installDir) : false;
+
+    console.log('\nNestbox project created.');
+    console.log(`Installation: ${installDir}`);
+    console.log(`Workspace: ${workspaceDir}`);
+    console.log(`Git initialized: ${gitInitialized ? 'yes' : 'no'}`);
+    console.log('\nNext steps:');
+    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(process.platform === 'win32' ? '  .\\tests\\nestbox.ps1' : '  bash tests/nestbox.sh');
+  } finally {
+    rl.close();
+  }
+}
+
+main().catch((error) => {
+  console.error(`create-nestbox: ${error.message}`);
+  process.exit(1);
+});

package/docker/nginx/Dockerfile

@@ -0,0 +1,31 @@
+# syntax=docker/dockerfile:1.7
+
+# ---- Stage 1: build the JS/CSS bundles with Rollup ----
+FROM node:alpine AS bundles
+
+WORKDIR /sources/rollup
+COPY ./home/configs/rollup/package.json ./package.json
+COPY ./home/configs/rollup/package-lock.json ./package-lock.json
+RUN npm ci --no-audit --no-fund
+
+COPY ./home/configs/rollup/rollup.config.js ./rollup.config.js
+COPY ./home/code /home/code
+RUN npx rollup -c
+
+# ---- Stage 2: runtime ----
+FROM alpine:3.23
+
+RUN apk add --no-cache nginx nginx-mod-http-nchan && \
+    mkdir -p /run/nginx /var/lib/nginx/tmp
+
+COPY ./home/configs/nginx/nginx.conf /etc/nginx/nginx.conf
+COPY ./home/code /var/www/html
+# Overwrite the source bundles with the freshly built ones from stage 1.
+COPY --from=bundles /home/code/scripts-bundle.js  /var/www/html/scripts-bundle.js
+COPY --from=bundles /home/code/scripts-bundle.css /var/www/html/scripts-bundle.css
+
+EXPOSE 80 8080
+
+STOPSIGNAL SIGQUIT
+
+CMD ["nginx", "-g", "daemon off;"]

package/docker/opencode/Dockerfile

@@ -0,0 +1,36 @@
+FROM composer:latest AS vendor
+
+WORKDIR /build
+COPY ./home/configs/php/composer.json ./composer.json
+COPY ./home/configs/php/composer.lock ./composer.lock
+RUN composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev
+
+FROM ghcr.io/anomalyco/opencode:latest
+
+ARG APP_UID=1000
+ARG APP_GID=1000
+
+RUN apk add --no-cache git php85 php85-dom php85-mbstring php85-openssl php85-phar php85-tokenizer php85-xml php85-xmlwriter su-exec && \
+    ln -s /usr/bin/php85 /usr/local/bin/php && \
+    addgroup -g "${APP_GID}" -S nestbox && \
+    adduser -u "${APP_UID}" -G nestbox -S -h /home/nestbox nestbox
+
+ENV OPENCODE_CONFIG=/etc/opencode/opencode.json
+ENV HOME=/home/nestbox
+
+COPY --from=vendor /build/vendor /vendor
+COPY ./home/configs/php /sources/php
+COPY ./home/configs/opencode /etc/opencode
+COPY ./home/code /home/code
+COPY ./docker/opencode/entrypoint.sh /usr/local/bin/nestbox-opencode-entrypoint
+
+RUN chmod 0755 /usr/local/bin/nestbox-opencode-entrypoint && \
+    mkdir -p /home/nestbox/.local/share/opencode && \
+    chown -R nestbox:nestbox /home/nestbox /home/code
+
+WORKDIR /workspace
+
+EXPOSE 4096
+
+ENTRYPOINT ["/usr/local/bin/nestbox-opencode-entrypoint"]
+CMD ["serve", "--hostname", "0.0.0.0", "--port", "4096"]

package/docker/opencode/entrypoint.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+set -eu
+
+# Named volumes retain ownership across image recreation. Repair only OpenCode's
+# private state volume before dropping privileges; never chown host bind mounts.
+mkdir -p "$HOME/.local/share/opencode"
+chown -R nestbox:nestbox "$HOME/.local/share/opencode"
+
+exec su-exec nestbox:nestbox opencode "$@"