@everywheredev/cli 0.0.1-5.1

package/README.md

@@ -0,0 +1,135 @@
+# @everywheredev/cli
+
+A **Claude-Code-style TypeScript terminal client** for the PocketDev host. It is a *thin client to the
+Go host* — it never owns the filesystem, git, PTY, or AI agent. It browses/edits the project, streams
+the terminal and activity feed, drives the HTTP proxy, and runs AI prompts, working **identically**
+against a **LOCAL** host (loopback + Personal Access Token over Tailscale) or a **FULL-REMOTE** host
+(cloud + Ory Hydra OAuth2), selected by a per-host **connection profile**.
+
+> Full design: [`docs/architecture/cli.md`](../docs/architecture/cli.md).
+
+## Install
+
+```sh
+npm i -g @everywheredev/cli  # provides the `pocketdev` binary
+```
+
+Standalone single-file builds (Bun / Node SEA / pkg) for macOS/Linux are planned so it runs without a
+Node toolchain, including over SSH.
+
+### Local development install
+
+To put the `pocketdev` command on your PATH from this working copy (no registry, no publish) — needs
+**Node ≥ 20**:
+
+```sh
+make cli-link            # from repo root: npm install + npm link (auto-builds via `prepare`)
+# or, from cli/:  npm link
+```
+
+`npm link` symlinks this package globally, so `pocketdev` points at your source. After editing,
+rebuild and the linked command picks it up — keep a watcher running for a tight loop:
+
+```sh
+npm run build:watch      # rebuild dist/ on every save (run in a spare terminal)
+```
+
+Validate the **published** shape (the eventual `npm i -g @everywheredev/cli` experience) without touching
+the registry — `npm pack` builds the exact tarball `files` would ship (`bin/`, `dist/`, `README.md`):
+
+```sh
+npm pack                                  # → everywheredev-cli-0.1.0.tgz
+npm i -g ./everywheredev-cli-0.1.0.tgz    # install it like a real user would
+npm rm -g @everywheredev/cli              # ...then remove and re-link for dev
+```
+
+Remove the dev link with `make cli-unlink` (or `npm unlink -g @everywheredev/cli`).
+
+## Quick start
+
+```sh
+# LOCAL-ONLY (free): point at the host on 127.0.0.1:4317 with a Personal Access Token.
+export POCKETDEV_MODE=local
+export POCKETDEV_TOKEN=<pat>
+pocketdev tree
+pocketdev open src/index.ts
+pocketdev agent "refactor the parser and run tests"
+
+# FULL-REMOTE (premium): device-grant login against Ory Hydra, then the same commands.
+pocketdev --profile cloud login
+pocketdev --profile cloud agents
+```
+
+## Architecture (foundation)
+
+The pipeline mirrors Claude Code: **entry binary → DI composition root → command/router →
+agent + tool loop (approval gate) → transport → renderer**, with a session/transcript model and
+layered settings underneath.
+
+Every external dependency is an injected **interface (port)**; concretes are wired **once** at the DI
+composition root (`src/di/container.ts`, [tsyringe](https://github.com/microsoft/tsyringe)). That root
+is the *only* place that branches on `POCKETDEV_MODE` (`local` | `remote`) — nothing downstream
+branches on mode, so the command/tool/agent layer is byte-identical across both.
+
+| Seam (port) | LOCAL concrete | REMOTE concrete |
+| --- | --- | --- |
+| `AuthProvider` | `SharedTokenAuthProvider` (PAT / `POCKETDEV_TOKEN`) | `HydraOAuthAuthProvider` (device grant + PKCE) |
+| `HttpPort` | `HttpTransport` → `http://127.0.0.1:4317` | `HttpTransport` → `https://…` |
+| `StreamPort` | `WsStreamTransport` → `ws://…/ws` | `WsStreamTransport` → `wss://…/ws` |
+| `TerminalPort` | `TerminalTransport` over the stream | same |
+| `SessionStore` | `FileSessionStore` (JSONL + `/api/sessions`) | same |
+
+### Layout
+
+```
+cli/
+├─ bin/pocketdev.js              # shebang shim → dist/index.js
+└─ src/
+   ├─ index.ts                   # bootstrap: reflect-metadata, buildContainer, route
+   ├─ di/{container,tokens}.ts    # composition root (ONLY local/remote wiring) + injection tokens
+   ├─ core/{app,command-router,errors}.ts
+   ├─ config/{ports,config-store,profile,defaults}.ts   # precedence flags>env>project>user>defaults
+   ├─ transport/{ports,http-transport,ws-stream-transport,terminal-transport,composite-transport,reconnect}.ts
+   ├─ auth/{ports,shared-token-auth-provider,hydra-oauth-auth-provider,device-flow,pkce,keychain}.ts
+   ├─ session/{ports,file-session-store}.ts
+   └─ contract/index.ts          # thin re-export of @pocketdev/contract types (no drift)
+```
+
+## Configuration & precedence
+
+Highest wins:
+
+```
+1. CLI flags        --host, --mode, --profile, --token, --print/-p, --json, --no-tty
+2. Environment      POCKETDEV_MODE, POCKETDEV_HOST, POCKETDEV_PORT (4317), POCKETDEV_TOKEN,
+                    POCKETDEV_PROJECT_ROOT, POCKETDEV_MAX_FILE_BYTES,
+                    KRATOS_PUBLIC_URL, HYDRA_PUBLIC_URL, OIDC_ISSUER
+3. Project config   ./.pocketdev/config.json
+4. User config      ~/.pocketdev/config.json
+5. Built-in defaults
+```
+
+Server-only variables (`DATABASE_URL`, `REDIS_URL`, `CASBIN_WATCHER_CHANNEL`, `STRIPE_*`,
+`*_ADMIN_URL`) are **not** consumed by the CLI — they belong to the host.
+
+## Authentication
+
+- **LOCAL** — `Authorization: Bearer $POCKETDEV_TOKEN`; the host validates with a constant-time
+  compare. `pocketdev login` is a verify round-trip. No keychain, no browser.
+- **REMOTE** — OAuth2 **Device Authorization Grant + PKCE** (RFC 8628 + 7636) against Ory Hydra;
+  access JWT used as the same Bearer header for REST and the WS handshake; tokens stored in the OS
+  keychain with a chmod-0600 file fallback for headless/CI.
+
+## Scripts
+
+```sh
+npm run build       # tsc --noEmit (typecheck) → esbuild bundle+minify to a single dist/index.js
+npm run build:watch # tsc --watch → rebuild dist/ on save (pairs with `npm link`)
+npm run dev         # run from source via tsx
+npm test            # vitest
+npm run typecheck   # tsc --noEmit
+```
+
+## License
+
+Proprietary — internal PocketDev component.

package/bin/pocketdev.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// PocketDev CLI entry shim.
+//
+// This is the published `pocketdev` binary (see package.json "bin"). It is a thin loader whose
+// only job is to hand control to the compiled bootstrap in dist/index.js. Keeping the shim tiny
+// means the real wiring (DI composition root, mode selection, routing) lives in TypeScript and is
+// fully testable — the shim itself has nothing to test.
+//
+// `reflect-metadata` is imported first (before any decorated class loads) because tsyringe relies
+// on emitted design-time type metadata for constructor injection.
+import "reflect-metadata";
+import { main } from "../dist/index.js";
+
+main(process.argv.slice(2)).catch((err) => {
+  // Last-resort guard: the bootstrap maps known failures to CliError with friendly hints; anything
+  // reaching here is unexpected. Print and exit non-zero so CI/pipes observe the failure.
+  process.stderr.write(`${err?.stack ?? err}\n`);
+  process.exit(1);
+});