napbox 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,13 @@
+napbox
+Copyright 2026 The napbox Authors
+
+This product includes software developed by others. The npm package bundles
+compiled programs that contain:
+
+- Apple Containerization (Apache License 2.0) and the Swift packages it and
+  napbox depend on (SwiftNIO, gRPC Swift, Swift Protobuf, Swift Crypto, Yams,
+  zstd and others), in napbox and napboxd.
+- Go modules (google/nftables, mdlayher/netlink, mdlayher/socket, golang.org/x)
+  and the Go standard library, in napbox-guard.
+
+Their licenses and notices are in THIRD_PARTY_NOTICES.txt in the npm package.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# napbox
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[中文](README.zh-CN.md)
+
+Local dev environments for coding agents on Apple silicon Macs, without Docker.
+
+napbox reads a project's compose file and gives every git worktree its own isolated set of services (databases, object storage, backends). Host ports are assigned by napbox and stay fixed for that environment. Idle environments go to sleep and wake up on the next connection. Agents drive it through MCP tools; scripts use the `napbox` command.
+
+It is built on Apple's open-source [Containerization](https://github.com/apple/containerization) framework: one lightweight Linux VM per environment, with all its services in it.
+
+**Status: 0.1.1, early.** Used daily on one machine for several projects (PostgreSQL with PostGIS, Redis, MinIO, Go and Node backends, nginx front ends). Expect rough edges.
+
+## Requirements
+
+- macOS 26 or later, Apple silicon
+- Node.js 22.22 or later
+- Claude Code, for the plugin (the `napbox` command works without it)
+
+## Install
+
+In Claude Code:
+
+```
+/plugin marketplace add coffeecoproject/napbox
+/plugin install napbox@napbox
+```
+
+The first time an agent needs services, napbox reports that it is not set up and the agent calls the `setup` tool (Claude Code asks you first). Setup:
+
+- downloads the Kata Containers kernel package from GitHub (about 700 MB, checked against a fixed checksum) and runc (about 10 MB), and pulls the vminit image from ghcr.io;
+- asks macOS to install Rosetta if it is missing (for x86 programs inside the VM);
+- copies `napboxd` to `~/Library/Application Support/napbox/` and registers it as a login item (`~/Library/LaunchAgents/io.github.coffeecoproject.napbox.plist`).
+
+Without Claude Code: `npx napbox setup`.
+
+## How it works
+
+- **One environment per worktree.** Environments are named `<project>/<worktree>` (the main checkout is `<project>/main`). Two worktrees of the same project run side by side without port clashes.
+- **Ports.** In compose, write only the container port (`- "5432"`). napbox assigns a host port on `127.0.0.1` and keeps it for the environment across sleep, wake, `up` again, napboxd restarts and profile changes. It is released only on `down`. Other worktrees and temporary environments get other ports, so read them from `napbox env` instead of hard-coding them. When a service needs its own address on the host (for example to build links a browser opens), write `${NAPBOX_API_3100}` in `environment` or `env_file`; napbox replaces it with the address this environment was given (`127.0.0.1:41217`) when the service starts.
+- **Sleep.** After 30 minutes without connections an environment sleeps and its memory goes back to macOS. The next connection to one of its ports wakes it; the first connection waits about a second.
+- **Temporary environments.** `napbox up --temp <name>` starts a throwaway environment next to the dev one (an empty test database, for example), and `napbox down --temp <name>` deletes it. `napbox run <service>` starts a one-off environment, runs one service in the foreground and returns its exit code.
+- **Builds.** `build:` is built inside a dedicated VM with BuildKit; the build cache is shared by all environments.
+- **Network.** Environments cannot reach the host or the local network. `napbox egress none` also cuts off the internet, leaving only the services in the same environment.
+
+## Commands
+
+All commands print JSON (`napbox status --text` prints a table).
+
+| Command | What it does |
+|---|---|
+| `napbox up [-f compose] [--build] [--profile P]` | Create or wake the environment, wait until healthy, print ports and variables |
+| `napbox env` | Print `export NAPBOX_<SERVICE>_<PORT>=127.0.0.1:<port>` lines, ready for `eval "$(napbox env)"` |
+| `napbox status [--text]` | State and ports of napboxd and the environments |
+| `napbox logs <service> [--tail N] [-f]` | Service logs, without waking the environment |
+| `napbox exec <service> -- <command>` | Run a command in a service (not interactive) |
+| `napbox run <service> [-- <command>]` | Run one service once in a throwaway environment |
+| `napbox reset <volume>` | Empty a named volume (the old data is kept for 7 days) |
+| `napbox sleep` / `napbox down` | Sleep now / remove the environment (data kept for 7 days) |
+| `napbox egress <open\|none>` | Switch network access |
+| `napbox image import <image>` | Import an image from local Docker, for images no registry serves any more |
+
+`--temp <name>` works with `up`, `env`, `logs`, `exec`, `egress` and `down`.
+
+## Compose support
+
+napbox supports what local dev compose files commonly use, and rejects everything else with an error that says what and why, instead of ignoring it.
+
+Supported: `image`, `build` (`context`, `dockerfile`, `target`, `args`), `command`, `entrypoint`, `environment`, `env_file`, `working_dir`, `init`, `shm_size`, `tmpfs`, `pull_policy`, `stop_grace_period`, `ports` (container port only), `expose`, `volumes` (named volumes, directories and single files), `depends_on` with conditions, `healthcheck`, `restart`, `profiles`, `develop.watch`, `secrets` (file form), memory limits, the default network, variable substitution, multiple compose files and YAML merge keys.
+
+Not supported, among others: `read_only`, `cpus`, `pids_limit`, `security_opt`, `platform`, `privileged`, `cap_add: NET_ADMIN`, `network_mode`, more than one network, `configs`, and `build` options beyond the four above.
+
+## Differences from Docker
+
+- A single service cannot be restarted on its own. When a service restarts under its `restart` policy, the whole environment restarts. Put setup work (create databases, run migrations) in one-shot services that the backend waits for with `condition: service_completed_successfully`.
+- Environments cannot reach each other. Services inside one environment can, by service name.
+- `exec` has no interactive terminal.
+- Builds cannot use your Docker login or local Docker images: `FROM` must be pullable from a public registry.
+- napbox does not export images. Package release images with another tool, such as Apple's `container`.
+- Memory is returned to macOS only when an environment sleeps.
+
+## License
+
+[Apache License 2.0](LICENSE). The npm package bundles third-party code; see [NOTICE](NOTICE).

package/README.zh-CN.md

@@ -0,0 +1,83 @@
+# napbox
+
+[English](README.md)
+
+给 coding agent 用的 Mac 本地开发环境，不用 Docker，只支持 Apple 芯片。
+
+napbox 按项目的 compose 文件，给每个 git worktree 起一套隔离的服务（数据库、对象存储、后端）。宿主机端口由 napbox 分配，同一个环境的端口固定不变。闲置的环境自动休眠，下次有连接进来时自动唤醒。agent 通过 MCP 工具使用它，项目脚本用 `napbox` 命令。
+
+底层是苹果开源的 [Containerization](https://github.com/apple/containerization)：一个环境一台轻量的 Linux 虚拟机，环境里的服务都在这台虚拟机里。
+
+**状态：0.1.1，早期版本。** 已经在一台电脑上给好几个项目日常使用（带 PostGIS 的 PostgreSQL、Redis、MinIO、Go 和 Node 后端、nginx 前端），但还会有不顺手的地方。
+
+## 要求
+
+- macOS 26 或更新版本，Apple 芯片
+- Node.js 22.22 或更新版本
+- 用插件需要 Claude Code（`napbox` 命令不依赖它）
+
+## 安装
+
+在 Claude Code 里：
+
+```
+/plugin marketplace add coffeecoproject/napbox
+/plugin install napbox@napbox
+```
+
+agent 第一次要起服务时，napbox 会报还没准备好，agent 就去调用 `setup` 工具（Claude Code 会先问你）。setup 会：
+
+- 从 GitHub 下载 Kata Containers 的内核包（约 700MB，按固定的校验值核对）和 runc（约 10MB），从 ghcr.io 拉取 vminit 镜像；
+- 没装 Rosetta 时请 macOS 安装（虚拟机里运行 x86 的程序要用）；
+- 把 `napboxd` 放到 `~/Library/Application Support/napbox/`，注册成登录项（`~/Library/LaunchAgents/io.github.coffeecoproject.napbox.plist`）。
+
+不用 Claude Code 的话：`npx napbox setup`。
+
+## 怎么工作
+
+- **一个 worktree 一个环境。** 环境叫 `<项目>/<worktree>`，主工作区是 `<项目>/main`。同一个项目的两个 worktree 可以同时运行，端口不冲突。
+- **端口。** compose 里只写容器端口（`- "5432"`）。napbox 在 `127.0.0.1` 上分一个宿主机端口，这个环境一直用它：休眠、唤醒、再次 `up`、napboxd 重启、换 profile 都不变，`down` 了才释放。别的 worktree 和临时环境是别的端口，所以要从 `napbox env` 读，不要写死。环境里的服务要知道自己在宿主机上的地址时（比如服务端生成给浏览器打开的链接），在 `environment` 或 `env_file` 里写 `${NAPBOX_API_3100}`，起服务时换成这个环境分到的地址（`127.0.0.1:41217`）。
+- **休眠。** 30 分钟没有连接就休眠，内存还给 macOS。下次连它的端口就自动唤醒，第一条连接要等约 1 秒。
+- **临时环境。** `napbox up --temp <名字>` 在开发环境旁边另起一个用完就扔的环境（比如测试用的空库），`napbox down --temp <名字>` 删掉它。`napbox run <服务>` 临时起一个环境，在前台跑一个服务，返回它的退出码。
+- **构建。** 写了 `build:` 的服务在单独的虚拟机里用 BuildKit 构建，所有环境共用一份构建缓存。
+- **网络。** 环境访问不到宿主机和局域网。`napbox egress none` 还会断开外网，只剩同一个环境里的服务能互相访问。
+
+## 命令
+
+命令都输出 JSON（`napbox status --text` 输出表格）。
+
+| 命令 | 作用 |
+|---|---|
+| `napbox up [-f compose] [--build] [--profile P]` | 创建或唤醒环境，等服务都就绪，输出端口和变量 |
+| `napbox env` | 输出 `export NAPBOX_<服务>_<端口>=127.0.0.1:<端口>`，可以直接 `eval "$(napbox env)"` |
+| `napbox status [--text]` | napboxd 和各环境的状态、端口 |
+| `napbox logs <服务> [--tail N] [-f]` | 服务的日志，不唤醒环境 |
+| `napbox exec <服务> -- <命令>` | 在服务里执行命令（不支持交互） |
+| `napbox run <服务> [-- <命令>]` | 在临时环境里把一个服务跑一次 |
+| `napbox reset <数据卷>` | 清空一个命名卷（旧数据保留 7 天） |
+| `napbox sleep` / `napbox down` | 马上休眠 / 回收环境（数据保留 7 天） |
+| `napbox egress <open\|none>` | 切换能不能上外网 |
+| `napbox image import <镜像>` | 从本机 Docker 导入镜像，给仓库里已经拉不到的镜像用 |
+
+`up`、`env`、`logs`、`exec`、`egress`、`down` 可以加 `--temp <名字>`。
+
+## 支持的 compose 写法
+
+本地开发的 compose 常用的写法都支持。别的写法直接报错，说清楚是哪里、为什么，不会悄悄忽略。
+
+支持：`image`、`build`（`context`、`dockerfile`、`target`、`args`）、`command`、`entrypoint`、`environment`、`env_file`、`working_dir`、`init`、`shm_size`、`tmpfs`、`pull_policy`、`stop_grace_period`、`ports`（只取容器端口）、`expose`、`volumes`（命名卷、目录和单个文件）、带条件的 `depends_on`、`healthcheck`、`restart`、`profiles`、`develop.watch`、`secrets`（文件形式）、内存上限、默认网络、变量替换、多份 compose 合并、YAML 合并键。
+
+不支持的有：`read_only`、`cpus`、`pids_limit`、`security_opt`、`platform`、`privileged`、`cap_add: NET_ADMIN`、`network_mode`、多个网络、`configs`，以及上面四个以外的 `build` 选项。
+
+## 和 Docker 不一样的地方
+
+- 不能单独重启一个服务。一个服务按 `restart` 重启时，整个环境一起重启。建库、跑迁移这类准备工作写成一次性服务，后端用 `condition: service_completed_successfully` 等它跑完。
+- 环境之间互相访问不到。同一个环境里的服务可以用服务名互相访问。
+- `exec` 没有交互终端。
+- 构建时用不了本机 Docker 的登录信息和本地镜像：`FROM` 要能从公开仓库拉到。
+- napbox 不导出镜像，发布用的镜像要用别的工具打包，比如苹果的 `container`。
+- 内存只在环境休眠时才还给 macOS。
+
+## 许可证
+
+[Apache License 2.0](LICENSE)。npm 包里带了第三方代码，见 [NOTICE](NOTICE)。