@peekdev/cli 0.1.0-alpha.8 → 0.1.0-alpha.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +90 -0
  2. package/package.json +2 -2
package/README.md ADDED
@@ -0,0 +1,90 @@
1
+ # @peekdev/cli
2
+
3
+ > Your real browser, exposed to your AI coding agent over MCP — capture once, query forever, never leaves your machine.
4
+
5
+ [![npm](https://img.shields.io/npm/v/@peekdev/cli.svg)](https://www.npmjs.com/package/@peekdev/cli)
6
+ [![downloads](https://img.shields.io/npm/dw/@peekdev/cli.svg)](https://www.npmjs.com/package/@peekdev/cli)
7
+ [![license](https://img.shields.io/npm/l/@peekdev/cli.svg)](https://github.com/Cubenest/rrweb-stack/blob/main/LICENSE)
8
+ [![CI](https://github.com/Cubenest/rrweb-stack/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Cubenest/rrweb-stack/actions/workflows/ci.yml)
9
+
10
+ <!-- Hero GIF lands in Week 3-4 per docs/PHASE_5_LAUNCH_PLAN.md — `npx peek init` → MCP visible in Claude Code → "what's in my latest session?" returning real data. See assets/README.md. -->
11
+
12
+ ```sh
13
+ npm install -g @peekdev/cli
14
+ peek init
15
+ ```
16
+
17
+ `peek init` is an interactive wizard. It:
18
+
19
+ 1. Installs the native messaging host for the **Peek** Chrome extension (writes `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.peekdev.peek.json` on macOS, equivalent on Linux + Windows).
20
+ 2. Detects your AI coding-agent client (Claude Code, Cursor, Cline, Windsurf, Continue, Zed) and adds the `peek-mcp` server to its MCP configuration.
21
+ 3. Prints a one-line "install the extension" link.
22
+
23
+ Then you install the [Peek Chrome extension](https://chromewebstore.google.com/) (CWS submission pending), open the side panel on the site you want to capture, and click **Enable on this site**. Your AI agent can now query the recording.
24
+
25
+ ## What this is NOT
26
+
27
+ - Not a session-replay product for production traffic. Peek is a **developer-side** tool — captures happen on your machine, in your browser, when you explicitly enable them per site.
28
+ - Not Sentry, LogRocket, or FullStory. There is no cloud, no upload, no telemetry, no signup. Captures live in `~/.peek/sessions.db` until you delete them.
29
+ - Not a screen recorder. Peek captures structured DOM/console/network via rrweb, not pixels. AI agents query JSON, not video frames.
30
+
31
+ ## Commands
32
+
33
+ ```sh
34
+ peek init # interactive install (see above)
35
+ peek status # health check — extension connected? DB writable?
36
+ peek sessions list [--json] # list recent recording sessions
37
+ peek sessions show <id> # show one session's metadata + counts
38
+ peek sessions export <id> --format <html|json|playwright> # export for sharing
39
+ peek sessions delete <id> # delete one session + its on-disk events
40
+ peek audit [--json] # show the destructive-action audit log
41
+ peek <cmd> --help # usage for any subcommand
42
+ ```
43
+
44
+ All commands operate read-only on `~/.peek/sessions.db` except `sessions delete` (and `peek init` which writes the install config). Nothing leaves your machine.
45
+
46
+ ## Querying from an AI agent
47
+
48
+ After `peek init`, the `peek-mcp` server is available to your AI client as an MCP toolset. Sample queries:
49
+
50
+ - "what's in my latest peek session?"
51
+ - "show me the console errors from session `abc123` between t=10s and t=15s"
52
+ - "find network requests with status >= 400 from the last 5 minutes of recording on `example.com`"
53
+ - "generate a Playwright reproduction script from session `abc123`"
54
+
55
+ The MCP server exposes ~20 tools — listing, querying, exporting, DOM reconstruction, console/network drill-down, and (with explicit per-action authorization) destructive actions like clicks/inputs/navigation. See [`@peekdev/mcp`](https://github.com/Cubenest/rrweb-stack/tree/main/packages/peek-mcp) for the tool reference.
56
+
57
+ ## Privacy
58
+
59
+ Peek is **local-first**. The CLI reads from `~/.peek/sessions.db` (SQLite); the extension records into it; the MCP server queries it. There is no network destination. There is no telemetry. There is no auto-update channel. The native host runs as your user, not as a daemon.
60
+
61
+ The extension uses per-origin host permissions — recording is **off** for every site by default. You enable it explicitly from the side panel for each origin you care about. The five-level permission model (read-only → read-with-confirmation → constrained-write → broad-write → destructive) is enforced server-side, not just in the UI.
62
+
63
+ Full data-handling policy: [`docs/peek/PRIVACY_POLICY.md`](https://github.com/Cubenest/rrweb-stack/blob/main/docs/peek/PRIVACY_POLICY.md). Chrome Web Store permission justifications: [`docs/peek/PERMISSION_JUSTIFICATION.md`](https://github.com/Cubenest/rrweb-stack/blob/main/docs/peek/PERMISSION_JUSTIFICATION.md).
64
+
65
+ ## Supported AI clients
66
+
67
+ `peek init` configures the MCP server into:
68
+
69
+ | Client | Detection |
70
+ |---|---|
71
+ | Claude Code (CLI) | `~/.claude/` |
72
+ | Cursor | `~/Library/Application Support/Cursor/User/` (macOS) |
73
+ | Cline (VS Code) | VS Code workspace settings |
74
+ | Continue (VS Code) | `~/.continue/` |
75
+ | Windsurf | `~/.codeium/windsurf/` |
76
+ | Zed | `~/.config/zed/` |
77
+
78
+ If your client isn't auto-detected, `peek init` prints the JSON config you can paste manually. The MCP server speaks the standard stdio protocol (spec 2025-11-25 + 2025-03-26 back-compat).
79
+
80
+ ## Versioning & compatibility
81
+
82
+ Semantic Versioning. Currently `0.1.0-alpha.x` — pre-release; the CLI surface is stable in spirit but flags may rename. See [SUPPORTED.md](https://github.com/Cubenest/rrweb-stack/blob/main/SUPPORTED.md) for the compatibility matrix.
83
+
84
+ `@peekdev/cli` depends on `@peekdev/mcp` as a workspace peer. Both are versioned and published together via Changesets + OIDC Trusted Publishing.
85
+
86
+ ## License
87
+
88
+ Apache 2.0. The bundled rrweb engine remains MIT-licensed; see `NOTICE`.
89
+
90
+ Contributions are accepted under the [Developer Certificate of Origin (DCO)](https://developercertificate.org/) — sign your commits with `git commit -s`. See [CONTRIBUTING.md](https://github.com/Cubenest/rrweb-stack/blob/main/CONTRIBUTING.md) + [SECURITY.md](https://github.com/Cubenest/rrweb-stack/blob/main/SECURITY.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@peekdev/cli",
3
- "version": "0.1.0-alpha.8",
3
+ "version": "0.1.0-alpha.9",
4
4
  "description": "peek command-line tool. A thin read-mostly client of the native host's ~/.peek/sessions.db (ADR-0007): status, sessions list/show/export/delete, the `peek init` MCP-client wizard, and `peek audit log`.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
@@ -22,7 +22,7 @@
22
22
  ],
23
23
  "dependencies": {
24
24
  "better-sqlite3": "^12.10.0",
25
- "@peekdev/mcp": "0.1.0-alpha.4"
25
+ "@peekdev/mcp": "0.1.0-alpha.5"
26
26
  },
27
27
  "devDependencies": {
28
28
  "@types/better-sqlite3": "^7.6.13",