grokbox 0.0.1 → 0.1.0-alpha.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 grokbox 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

@@ -1,34 +1,235 @@
 # grokbox
 
-Unofficial local CLI for inspecting and messaging a running Grok Bot host.
-It is not affiliated with or endorsed by Anysphere, Cursor, or xAI.
+[English](./README.md) | [中文](./README.zh-CN.md)
 
-## Requirements
+Unofficial CLI and control plane for operating Grok Bot cloud computers from
+inside or outside the box. The canonical command is `grokbox`; `gbox` is an
+exact alias.
 
-- Bun 1.3 or newer
-- A reachable Grok Bot host on the same machine or network
+This project is not affiliated with or endorsed by Anysphere, Cursor, xAI, or
+Grok Bot. Grok Bot, Cursor, and related names identify compatible products and
+remain the property of their respective owners.
+
+> **Alpha:** current source is `0.1.0-alpha.5` and has not been published yet.
+> npm's `next` dist-tag currently points to `0.1.0-alpha.0`; `0.0.1` is an
+> earlier unsupported snapshot. `v0.1.0-alpha.1` through `v0.1.0-alpha.4` exist
+> as Git tags only. Prereleases publish only after release checks and explicitly
+> scoped external acceptance.
+
+## What it does
+
+```text
+Profile -> local daemon -> local Grok Bot Gateway
+        -> remote daemon over private Tailscale Serve
+        -> explicit direct-local or Gateway compatibility path
+        -> explicit Cursor Sandbox or quota compatibility adapter
+```
+
+Implemented command families:
+
+```text
+init  skills  profile  daemon  doctor  recover  box  quota
+agents  groups  send  history  memory  events  is
+fs  exec  jobs  desktop
+```
+
+Highlights:
+
+- strict local and remote Profiles with separate credential authorities;
+- finite Unix-socket/loopback daemon and private Tailscale Serve mapping;
+- agent/group management, send, transcript, Memory, and bounded events;
+- named-root governed file reads and mutations;
+- literal structured execution with durable Jobs and bounded logs;
+- layered read-only diagnosis and explicit recovery;
+- opt-in Sandbox lifecycle, quota, and desktop compatibility adapters.
+
+The daemon does not provide a generic raw RPC or shell. Gateway-only Profiles
+never gain host filesystem or process authority.
+
+## Prerequisites and platform support
+
+- Node.js 20+ for the published-style CLI runtime.
+- Bun 1.3.14 for source development and the pre-release source shim.
+- An existing Grok Bot cloud computer that you own or are authorized to use.
+- Tailscale plus BatchMode SSH for remote bootstrap/recovery; bootstrap also
+  needs npm or Bun locally to repack the installed runtime for transfer.
+
+| Role | Supported or tested |
+| --- | --- |
+| Source development | Linux and macOS |
+| Node CLI | Linux and macOS |
+| Box daemon, files, Jobs, desktop | Linux |
+| Keychain secret references | macOS |
+| Windows | Not currently supported or tested |
+
+## Five-minute source quick start
+
+```bash
+git clone https://github.com/yoyooyooo/grokbox.git
+cd grokbox
+bun install --frozen-lockfile
+bun run typecheck
+bun run grokbox -- --help
+bun run grokbox -- doctor
+```
+
+`doctor` is read-only. It reports each configured boundary separately and does
+not wake a Sandbox, alter Tailscale Serve, start a daemon, or rotate a
+credential.
+
+Inside a running Grok Bot box, the no-file `default` Profile discovers the
+loopback Gateway from `/home/box/sand-data/gateway.json`. If no local Gateway or
+configured Profile is available, commands fail closed.
 
 ## Install
 
 ```bash
-bun add --global grokbox
-grok-bot --help
+npm install --global grokbox@next
+grokbox --version
+gbox --help
+```
+
+Node.js 20 or newer is required. Bun is not required by the published package.
+
+## Source-backed global shim
+
+To test an unpublished checkout, install `grokbox` and `gbox` into
+`~/.local/bin` while executing its TypeScript entry directly through Bun:
+
+```bash
+bun run shim:install
+grokbox --version
+gbox --help
+grokbox doctor
 ```
 
-For a one-off run:
+The installer is idempotent, writes both aliases atomically, refuses to replace
+an unrelated command, and verifies each installed command from outside the
+repository. It records the absolute checkout and Bun paths, so rerun it after
+moving the repository or Bun executable. This is a local-real source harness;
+it does not replace the separate Node tarball verification.
+
+## Remote initialization
+
+Start with discovery and diagnosis. Bootstrap is an explicit privileged step:
 
 ```bash
-bunx grokbox --help
+grokbox init remote --peer <tailnet-peer>
+grokbox doctor --profile remote
+
+# Installs/replaces the grokbox daemon, rotates its credential, and applies only
+# the recorded private Serve mapping. Requires BatchMode SSH and confirmation.
+grokbox init remote --peer <tailnet-peer> --bootstrap --yes
 ```
 
-## Common commands
+Home reads are a separate authority transition and are never implied by
+bootstrap:
 
 ```bash
-grok-bot doctor
-grok-bot agents list
-grok-bot send <agent> "status only"
-grok-bot history tail <agent>
-grok-bot skills list
+grokbox init remote --peer <tailnet-peer> --bootstrap --admit-home-read --yes
 ```
 
-Run `grok-bot --help` or `grok-bot <command> --help` for the complete command reference.
+Review the named filesystem roots and process allowlist before enabling host
+capabilities.
+
+## Common safe probes
+
+```bash
+grokbox profile list --table
+grokbox doctor
+grokbox daemon status
+grokbox agents list --table
+grokbox groups list --table
+grokbox history tail <target> --limit 20
+grokbox memory list <agent>
+grokbox fs stat workspace:/artifact.txt
+grokbox jobs list --table
+grokbox desktop status --table
+```
+
+Mutating commands require explicit capability and, where destructive, explicit
+confirmation. `desktop prune run` defaults to dry-run; `--yes` invokes the
+upstream stop-window path and deletes that fork's Chrome profile.
+
+## Credentials
+
+Never pass Gateway, daemon, Sandbox, quota, SSH, or tailnet credentials on
+argv, in issues, fixtures, snapshots, or ordinary logs.
+
+Secret references are purpose-specific:
+
+```text
+env:<NAME>
+file:<absolute-path>
+keychain:<service>/<account>
+```
+
+A `file:` reference must resolve to a regular file owned by the current POSIX
+user with no group or other permission bits; symbolic links are rejected.
+Profiles never store inline tokens. Gateway, daemon, Sandbox, and quota
+credentials are separate capabilities and are never substituted for one
+another.
+
+## Experimental compatibility surfaces
+
+Grok Bot Gateway methods, Cursor Sandbox RPCs, the Cursor web quota endpoint,
+and Grok Bot desktop layout are not documented upstream public APIs. Their
+implementation may break without notice and does not imply provider
+endorsement or authorization.
+
+In particular:
+
+- official Cursor OAuth has been observed to read Sandbox state but receive 401
+  from `EnsureSandBox`;
+- App-free wake and 24–72 hour keeper behavior are not stable claims;
+- quota requires an explicit independent source and has source-local account
+  binding;
+- desktop prune is Linux/layout-specific and destructive when confirmed.
+
+See [Compatibility and upstream boundary](docs/compatibility.md) before using
+these surfaces. Users are responsible for the terms and policies applying to
+their accounts and environments.
+
+## Development and verification
+
+```bash
+bun install --frozen-lockfile
+bun run check
+```
+
+The package test builds and packs locally, installs into an isolated system
+Trash fixture, verifies both aliases under Node, checks the exact package
+allowlist, and confirms project and third-party licenses are present. The
+release-candidate workflow builds a downloadable artifact only. Exact version
+tags publish through the separate OIDC Trusted Publishing workflow with npm
+provenance; prereleases use `next`, stable versions use `latest`, and a GitHub
+Release is created only after registry readback succeeds. See the
+[release runbook](docs/maintainers/release.md); local release commands only
+precheck and push an immutable tag, never publish from the maintainer machine.
+
+Real external validation is intentionally separate and requires explicitly
+injected authorized targets. Set `GROKBOX_EXTERNAL_PACKAGE` to an exact registry
+version to test what users install rather than a locally packed tarball.
+Fake-provider or local results do not prove provider authorization, long-lived
+lease behavior, or destructive recovery.
+
+## Documentation
+
+- [Documentation map](https://github.com/yoyooyooo/grokbox/blob/main/docs/README.md)
+- [Product contract](https://github.com/yoyooyooo/grokbox/blob/main/docs/product-contract.md)
+- [Architecture](https://github.com/yoyooyooo/grokbox/blob/main/docs/architecture.md)
+- [Compatibility boundary](https://github.com/yoyooyooo/grokbox/blob/main/docs/compatibility.md)
+- [Upstream integration facts](https://github.com/yoyooyooo/grokbox/blob/main/docs/upstream-integration.md)
+- [Security policy](SECURITY.md)
+- [Support](SUPPORT.md)
+- [Contributing](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+
+Current behavior is owned by source and executable tests. Product and
+architecture documents may describe accepted targets; roadmap entries and
+GitHub issues do not prove delivery.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE). The published bundle's third-party attributions
+are in [`THIRD_PARTY_NOTICES`](THIRD_PARTY_NOTICES).

package/README.zh-CN.md

@@ -0,0 +1,187 @@
+# grokbox
+
+[English](./README.md) | [中文](./README.zh-CN.md)
+
+`grokbox` 是一个非官方 CLI 与控制面，用于从 Grok Bot 云电脑内部或外部进行操作。规范命令是 `grokbox`，`gbox` 是完全等价的别名。
+
+本项目与 Anysphere、Cursor、xAI 或 Grok Bot 没有隶属或背书关系。Grok Bot、Cursor 及相关名称仅用于标识兼容产品，其权利归各自所有者。
+
+> **Alpha：** 当前源码版本是 `0.1.0-alpha.5`，尚未发布。npm 的 `next` dist-tag 目前指向 `0.1.0-alpha.0`；`0.0.1` 是更早且不再支持的快照。`v0.1.0-alpha.1` 到 `v0.1.0-alpha.4` 只存在于 Git tag。只有通过发布检查及明确范围的外部验收后，才会发布新的预发布版本。
+
+## 它能做什么
+
+```text
+Profile -> 本机 daemon -> 本机 Grok Bot Gateway
+        -> 通过私有 Tailscale Serve 连接远端 daemon
+        -> 显式 direct-local 或 Gateway 兼容路径
+        -> 显式 Cursor Sandbox 或 quota 兼容适配器
+```
+
+已实现的命令族：
+
+```text
+init  skills  profile  daemon  doctor  recover  box  quota
+agents  groups  send  history  memory  events  is
+fs  exec  jobs  desktop
+```
+
+主要能力：
+
+- 严格区分本机与远端 Profile，并分离不同凭据权威；
+- 有限的 Unix socket/loopback daemon 与私有 Tailscale Serve 映射；
+- Agent/Group 管理、消息发送、Transcript、Memory 和有界事件读取；
+- 通过命名根目录治理文件读取与变更；
+- 字面量结构化执行、持久 Job 和有界日志；
+- 分层只读诊断与显式恢复；
+- 可选的 Sandbox 生命周期、quota 与桌面兼容适配器。
+
+Daemon 不提供通用 raw RPC 或任意 shell。仅有 Gateway 权限的 Profile 不会获得 host 文件系统或进程权限。
+
+## 前置条件与平台支持
+
+- 发布版 CLI 运行时需要 Node.js 20+。
+- 源码开发与发布前源码 shim 需要 Bun 1.3.14。
+- 需要一个你拥有或获准使用的 Grok Bot 云电脑。
+- 远程 bootstrap/recovery 需要 Tailscale 与 BatchMode SSH；bootstrap 还需要本机 npm 或 Bun，以便重新打包已安装运行时并传输。
+
+| 角色 | 支持或已测试平台 |
+| --- | --- |
+| 源码开发 | Linux 与 macOS |
+| Node CLI | Linux 与 macOS |
+| Box daemon、文件、Jobs、desktop | Linux |
+| Keychain secret reference | macOS |
+| Windows | 当前不支持，也未测试 |
+
+## 五分钟源码快速开始
+
+```bash
+git clone https://github.com/yoyooyooo/grokbox.git
+cd grokbox
+bun install --frozen-lockfile
+bun run typecheck
+bun run grokbox -- --help
+bun run grokbox -- doctor
+```
+
+`doctor` 是只读命令。它会分别报告各项边界，不会唤醒 Sandbox、修改 Tailscale Serve、启动 daemon 或轮换凭据。
+
+在运行中的 Grok Bot box 内，没有 Profile 文件时，`default` Profile 会从 `/home/box/sand-data/gateway.json` 发现 loopback Gateway。若既没有本机 Gateway，也没有已配置 Profile，命令会安全失败。
+
+## 安装
+
+```bash
+npm install --global grokbox@next
+grokbox --version
+gbox --help
+```
+
+需要 Node.js 20 或更高版本。发布后的 package 不需要 Bun。
+
+## 源码驱动的全局 shim
+
+若要验证尚未发布的 checkout，可把 `grokbox` 和 `gbox` 安装到 `~/.local/bin`，并让它们通过 Bun 直接执行 TypeScript 入口：
+
+```bash
+bun run shim:install
+grokbox --version
+gbox --help
+grokbox doctor
+```
+
+安装器可幂等运行，以原子方式写入两个别名，拒绝覆盖无关命令，并从仓库外验证每个命令。它记录 checkout 与 Bun 的绝对路径，因此仓库或 Bun 可执行文件移动后需要重新运行。该路径用于验证本机真实源码，不替代 Node tarball 验证。
+
+## 远程初始化
+
+先发现和诊断，再显式执行特权 bootstrap：
+
+```bash
+grokbox init remote --peer <tailnet-peer>
+grokbox doctor --profile remote
+
+# 安装或替换 grokbox daemon、轮换 daemon 凭据，并且只应用被记录的
+# 私有 Serve 映射。需要 BatchMode SSH 与明确确认。
+grokbox init remote --peer <tailnet-peer> --bootstrap --yes
+```
+
+读取 home 是单独的权限变化，不会由 bootstrap 隐式开启：
+
+```bash
+grokbox init remote --peer <tailnet-peer> --bootstrap --admit-home-read --yes
+```
+
+启用 host 能力前，请审阅命名文件系统根目录和进程 allowlist。
+
+## 常用安全探针
+
+```bash
+grokbox profile list --table
+grokbox doctor
+grokbox daemon status
+grokbox agents list --table
+grokbox groups list --table
+grokbox history tail <target> --limit 20
+grokbox memory list <agent>
+grokbox fs stat workspace:/artifact.txt
+grokbox jobs list --table
+grokbox desktop status --table
+```
+
+变更命令需要显式 capability；破坏性操作还需要显式确认。`desktop prune run` 默认 dry-run；传入 `--yes` 后会调用上游 stop-window 路径，并删除该 fork 的 Chrome profile。
+
+## 凭据
+
+不要把 Gateway、daemon、Sandbox、quota、SSH 或 tailnet 凭据放进 argv、Issue、fixture、snapshot 或普通日志。
+
+Secret reference 按用途区分：
+
+```text
+env:<NAME>
+file:<absolute-path>
+keychain:<service>/<account>
+```
+
+`file:` 必须指向当前 POSIX 用户拥有、group/other 无权限位的普通文件；拒绝符号链接。Profile 不保存 inline token。Gateway、daemon、Sandbox 与 quota 凭据是分离的 capability，不能互相替代。
+
+## 实验性兼容表面
+
+Grok Bot Gateway method、Cursor Sandbox RPC、Cursor Web quota endpoint 和 Grok Bot desktop 布局都不是上游公开 API，可能无预警失效，也不表示 provider 背书或授权。
+
+尤其需要注意：
+
+- 已观察到官方 Cursor OAuth 可读取 Sandbox 状态，但调用 `EnsureSandBox` 会收到 401；
+- 无 App 唤醒及 24–72 小时 keeper 行为不是稳定承诺；
+- quota 需要显式独立来源，并受来源本地账号绑定；
+- desktop prune 依赖 Linux/布局，确认执行时具有破坏性。
+
+使用这些表面前，请阅读[兼容性与上游边界](docs/compatibility.md)。用户需要自行遵守其账号和环境适用的条款与政策。
+
+## 开发与验证
+
+```bash
+bun install --frozen-lockfile
+bun run check
+```
+
+Package 测试会在本机构建和打包，把产物安装到隔离的系统 Trash fixture，用 Node 验证两个别名，核对精确 package allowlist，并确认项目与第三方许可证存在。`Release candidate artifact` workflow 只生成可下载产物，不会发布。
+
+只有精确版本 tag 才会触发独立的 OIDC Trusted Publishing workflow：预发布版本进入 npm `next`，稳定版本进入 `latest`；registry 版本、channel 与 provenance 回读成功后才创建 GitHub Release。详见[发布手册](docs/maintainers/release.md)。本机 release 命令只做预检与推送不可变 tag，不会从维护者机器发布 npm。
+
+真实外部验证保持独立，并要求显式注入获授权的目标。设置 `GROKBOX_EXTERNAL_PACKAGE=grokbox@<version>`，可验证用户实际安装的精确 registry 版本，而不是本机 tarball。Fake-provider 或 local-real 结果不能证明 provider 授权、长期 lease 行为或破坏性恢复能力。
+
+## 文档
+
+- [文档地图](docs/README.md)
+- [产品契约](docs/product-contract.md)
+- [架构](docs/architecture.md)
+- [兼容性边界](docs/compatibility.md)
+- [上游集成事实](docs/upstream-integration.md)
+- [安全策略](SECURITY.md)
+- [支持](SUPPORT.md)
+- [贡献指南](CONTRIBUTING.md)
+- [变更日志](CHANGELOG.md)
+
+当前行为由源码和可执行测试决定。产品与架构文档可能描述已接受目标；roadmap 和 GitHub Issue 不能证明功能已经交付。
+
+## 许可证
+
+MIT，见 [`LICENSE`](LICENSE)。发布包中的第三方归属见 [`THIRD_PARTY_NOTICES`](THIRD_PARTY_NOTICES)。

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,29 @@
+Third-Party Notices
+===================
+
+grokbox's published JavaScript bundle includes the following third-party
+software. This notice is distributed with every grokbox package artifact.
+
+Commander.js
+------------
+
+Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
+
+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/bin/grokbox

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import {
+  RUNTIME_UNSUPPORTED_EXIT_CODE,
+  runtimeUnsupportedEnvelope,
+  supportsNodeRuntime,
+} from "./runtime.js";
+
+if (!supportsNodeRuntime(process.versions.node)) {
+  process.stderr.write(`${JSON.stringify(runtimeUnsupportedEnvelope(process.versions.node))}\n`);
+  process.exitCode = RUNTIME_UNSUPPORTED_EXIT_CODE;
+} else {
+  await import("../dist/index.js");
+}

package/bin/runtime.d.ts

@@ -0,0 +1,13 @@
+export const MINIMUM_NODE_MAJOR: number;
+export const RUNTIME_UNSUPPORTED_EXIT_CODE: number;
+export function nodeMajor(version: unknown): number | null;
+export function supportsNodeRuntime(version: unknown): boolean;
+export function runtimeUnsupportedEnvelope(version: unknown): {
+  ok: false;
+  error: {
+    code: "runtime_unsupported";
+    message: string;
+    retryable: false;
+    runtime: { nodeMajor: number | null; minimumNodeMajor: number };
+  };
+};

package/bin/runtime.js

@@ -0,0 +1,27 @@
+export const MINIMUM_NODE_MAJOR = 20;
+export const RUNTIME_UNSUPPORTED_EXIT_CODE = 59;
+
+export function nodeMajor(version) {
+  const major = Number.parseInt(String(version).split(".", 1)[0] ?? "", 10);
+  return Number.isSafeInteger(major) ? major : null;
+}
+
+export function supportsNodeRuntime(version) {
+  const major = nodeMajor(version);
+  return major !== null && major >= MINIMUM_NODE_MAJOR;
+}
+
+export function runtimeUnsupportedEnvelope(version) {
+  return {
+    ok: false,
+    error: {
+      code: "runtime_unsupported",
+      message: `grokbox requires Node.js ${MINIMUM_NODE_MAJOR} or newer.`,
+      retryable: false,
+      runtime: {
+        nodeMajor: nodeMajor(version),
+        minimumNodeMajor: MINIMUM_NODE_MAJOR,
+      },
+    },
+  };
+}