grokbox 0.0.1 → 0.1.0-alpha.0

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,232 @@
 # 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.
+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.
 
-## Requirements
+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.
 
-- Bun 1.3 or newer
-- A reachable Grok Bot host on the same machine or network
+> **Alpha:** current `main` is `0.1.0-alpha.0`. Prereleases publish on npm under
+> the `next` dist-tag after release checks and external acceptance. The existing
+> npm `0.0.1` is an earlier unsupported snapshot and does not represent current
+> `main`.
+
+## 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
+```
+
+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
+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
 ```
 
-For a one-off run:
+Home reads are a separate authority transition and are never implied by
+bootstrap:
 
 ```bash
-bunx grokbox --help
+grokbox init remote --peer <tailnet-peer> --bootstrap --admit-home-read --yes
 ```
 
-## Common commands
+Review the named filesystem roots and process allowlist before enabling host
+capabilities.
+
+## Common safe probes
 
 ```bash
-grok-bot doctor
-grok-bot agents list
-grok-bot send <agent> "status only"
-grok-bot history tail <agent>
-grok-bot skills list
+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>
 ```
 
-Run `grok-bot --help` or `grok-bot <command> --help` for the complete command reference.
+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 typecheck
+bun test
+bun run verify:package
+bun run release: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 the `next` dist-tag.
+
+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 and local issue
+files 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/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,
+      },
+    },
+  };
+}