spectater 0.1.0 → 0.2.0
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.
- package/README.md +86 -33
- package/bin/spectater.js +346 -306
- package/package.json +18 -9
- package/skills/spectater/SKILL.md +13 -0
- package/src/agent.js +184 -0
- package/src/discovery.js +4 -4
- package/src/hooks.js +145 -0
- package/src/review.js +195 -140
- package/src/server.js +143 -57
- package/src/storage.js +56 -9
- package/web/app.js +51 -11
- package/web/index.html +15 -2
- package/web/style.css +12 -0
- package/SECURITY.md +0 -11
- package/docs/licenses/open-design.txt +0 -201
- package/docs/security-review.md +0 -33
- package/docs/verification.md +0 -41
- package/docs/workflow.md +0 -65
- package/integration/spectater/SKILL.md +0 -17
- package/src/control.js +0 -236
package/README.md
CHANGED
|
@@ -1,61 +1,114 @@
|
|
|
1
1
|
# SpecTater
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://github.com/morhaf-ko/spectater/actions/workflows/check.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/spectater)
|
|
5
|
+
[](LICENSE)
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
Review [OpenSpec](https://github.com/Fission-AI/OpenSpec) changes in your browser and send selected-text feedback straight to your coding agent.
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
Your agent drafts a proposal, design, specs and tasks. SpecTater opens them in a local reader where you select text, comment, and submit. The agent receives your comments as structured JSON, revises the Markdown, and replies. The page updates as the files change. Everything stays on your machine.
|
|
10
|
+
|
|
11
|
+
## Quick start
|
|
12
|
+
|
|
13
|
+
Install the skill for your agent:
|
|
8
14
|
|
|
9
15
|
```sh
|
|
10
|
-
|
|
11
|
-
bun run bin/spectater.js open --project /path/to/project --change change-id
|
|
16
|
+
npx skills add morhaf-ko/spectater
|
|
12
17
|
```
|
|
13
18
|
|
|
14
|
-
|
|
19
|
+
Then ask your agent to review a change, for example "review the add-dark-mode proposal with spectater". The skill tells the agent to run `npx -y spectater`, so there is nothing else to install.
|
|
15
20
|
|
|
16
|
-
|
|
21
|
+
Without the skill, tell the agent: "Run `npx -y spectater workflow` and follow it for the add-dark-mode change."
|
|
17
22
|
|
|
18
|
-
|
|
19
|
-
2. Save comments, then submit new or changed feedback. A listening agent receives the batch; otherwise it stays queued.
|
|
20
|
-
3. Before delivery, Edit queued pauses a batch for correction and explicit replacement. Cancel submission preserves its comments. After delivery, Send correction creates new feedback without recalling instructions.
|
|
21
|
-
4. Source saves update the reader automatically. Old comments become stale/orphaned; reattachment is explicit. What changed compares the latest source update with the previous one, including added/removed files.
|
|
22
|
-
5. End review preserves read-only history and tells a waiting agent to stop listening. Deliver or cancel queued batches first. Resume review or `open --reopen` explicitly resumes; a normal open does not silently restart an ended review.
|
|
23
|
+
Requirements: Node 22.12 or newer, OpenSpec 1.15 or newer, macOS or Linux. Git is optional; it powers the "What changed" diff.
|
|
23
24
|
|
|
24
|
-
|
|
25
|
+
## How it works
|
|
25
26
|
|
|
26
|
-
|
|
27
|
+
```
|
|
28
|
+
agent: spectater open add-dark-mode → server starts in the background, browser opens
|
|
29
|
+
you: select text, comment, Submit → feedback is saved and queued
|
|
30
|
+
agent: spectater wait add-dark-mode → receives the batch as JSON
|
|
31
|
+
agent: spectater reply … --status working, edits Markdown, spectater reply … --message-file result.md
|
|
32
|
+
you: see the update and the reply; comment again or click End review
|
|
33
|
+
```
|
|
27
34
|
|
|
28
|
-
|
|
35
|
+
Every agent command prints one JSON object with a `status` and a `next_step`, so the agent always knows what to do next:
|
|
29
36
|
|
|
30
|
-
|
|
37
|
+
| `status` | Meaning | Exit code |
|
|
38
|
+
| ------------------- | ---------------------------------------------- | --------- |
|
|
39
|
+
| `batch` | Feedback delivered in `batch` | 0 |
|
|
40
|
+
| `timeout` | No feedback within `--timeout` (default 540 s) | 0 |
|
|
41
|
+
| `ended` | You ended the review | 0 |
|
|
42
|
+
| `error` | The command failed; see `error` | 1 |
|
|
43
|
+
| `stopped` | The review server is not running | 3 |
|
|
44
|
+
| `listener_active` | Another `wait` is already listening | 4 |
|
|
45
|
+
| `listener_replaced` | Another `wait --takeover` replaced this one | 5 |
|
|
31
46
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
"openBrowser": false
|
|
36
|
-
}
|
|
37
|
-
```
|
|
47
|
+
Until the agent replies to a batch, `wait` returns that batch again, so feedback is never lost if the agent is interrupted.
|
|
48
|
+
|
|
49
|
+
Other commands report `ready` or `reused` (`open`), `recorded` (`reply`), `refreshed` (`refresh`), `ended` (`end`), `stopping` or `not_running` (`stop`), and `stopped` (exit 3) when no server is running. Any command can return `error` (exit 1).
|
|
38
50
|
|
|
39
|
-
|
|
51
|
+
## In the browser
|
|
40
52
|
|
|
41
|
-
|
|
53
|
+
- Select text in the rendered view or the Markdown source, then comment. Enter saves; Cmd/Ctrl+Enter saves and submits.
|
|
54
|
+
- Write a message to the agent that is not tied to a selection.
|
|
55
|
+
- Submit sends only new or changed comments. Until the agent picks a batch up you can edit or cancel it.
|
|
56
|
+
- **Send & End** submits and ends the review once the agent has received the final batch.
|
|
57
|
+
- Comments on text that later changes are marked stale (with a suggested re-anchor) or orphaned; nothing is silently moved.
|
|
58
|
+
- "What changed" diffs the latest source update against the previous one.
|
|
42
59
|
|
|
43
|
-
##
|
|
60
|
+
## Commands
|
|
44
61
|
|
|
45
|
-
|
|
62
|
+
| Command | Description |
|
|
63
|
+
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
64
|
+
| `spectater` | List open reviews and usage. |
|
|
65
|
+
| `spectater open <change>` | Start or reuse the review server and open the browser. `--no-open`, `--reopen`. |
|
|
66
|
+
| `spectater wait <change>` | Wait for feedback. `--timeout <seconds>`, `--takeover`, `--format markdown`. |
|
|
67
|
+
| `spectater reply <change>` | `--status working`, or post a result with `--message` / `--message-file`. `--batch <n>` targets an earlier batch. |
|
|
68
|
+
| `spectater feedback <change> --batch <n>` | Print a submitted batch without recording delivery. |
|
|
69
|
+
| `spectater refresh <change>` | Re-read the change from disk. |
|
|
70
|
+
| `spectater end <change>` | End the review. |
|
|
71
|
+
| `spectater stop <change>` | Stop the server. Saved feedback is kept. |
|
|
72
|
+
| `spectater workflow` | Print the agent review loop. |
|
|
73
|
+
| `spectater skill` | Print the agent skill. |
|
|
74
|
+
| `spectater setup hooks` | Add SessionStart hooks (see below). `--remove` undoes it. |
|
|
46
75
|
|
|
47
|
-
|
|
76
|
+
Run commands from the project directory, or pass `--project <dir>`. Use `--store <id>` for an OpenSpec store.
|
|
48
77
|
|
|
49
|
-
|
|
78
|
+
## Session hooks (optional)
|
|
50
79
|
|
|
51
|
-
|
|
80
|
+
To have new agent sessions see reviews that are already open, install SpecTater globally and add the hooks:
|
|
52
81
|
|
|
53
82
|
```sh
|
|
54
|
-
|
|
83
|
+
npm install -g spectater
|
|
84
|
+
spectater setup hooks
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
For each agent that is installed, this adds a SessionStart hook for Claude Code (`~/.claude/settings.json`), Codex (`~/.codex/hooks.json`; approve it once with `/hooks`), OpenCode (`~/.config/opencode/plugins/spectater.js`) and GitHub Copilot CLI (`~/.copilot/hooks/spectater.json`). The hook runs `spectater status --hook`, which prints open reviews for the current project and nothing otherwise. It never blocks or drives the agent. Restart your agent sessions afterwards.
|
|
88
|
+
|
|
89
|
+
## Configuration
|
|
90
|
+
|
|
91
|
+
No configuration is required. An optional `~/.config/spectater/config.json` (or `$XDG_CONFIG_HOME/spectater/config.json`, or `--config <file>`, or `SPECTATER_CONFIG`) accepts:
|
|
92
|
+
|
|
93
|
+
```json
|
|
94
|
+
{ "defaultView": "source", "openBrowser": false, "stateDirectory": "/absolute/path" }
|
|
55
95
|
```
|
|
56
96
|
|
|
57
|
-
|
|
97
|
+
| Variable | Effect |
|
|
98
|
+
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
99
|
+
| `SPECTATER_STATE_DIR` | Where reviews are stored. Default: `~/Library/Application Support/SpecTater` on macOS, `$XDG_STATE_HOME/spectater` on Linux. |
|
|
100
|
+
| `SPECTATER_IDLE_TIMEOUT` | Seconds before an unused server stops itself. Default 1800; `0` disables. |
|
|
101
|
+
|
|
102
|
+
Review state lives outside your repository and is never uploaded. Back it up separately if you need the history.
|
|
103
|
+
|
|
104
|
+
## Security and limits
|
|
105
|
+
|
|
106
|
+
The server listens on `127.0.0.1` only. The URL contains a private token; anyone with it can read and comment on the review, so do not share it. Markdown is rendered without raw HTML, scripts or remote images, and SpecTater never writes to your Markdown. Limits: 1 MiB per file, 128 artifacts, 10,000 characters per selection, comment or message. Windows is not supported. See [SECURITY.md](SECURITY.md) to report a vulnerability.
|
|
107
|
+
|
|
108
|
+
## Contributing
|
|
109
|
+
|
|
110
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md). Requirements live in [`openspec/specs`](openspec/specs) and in-flight changes in [`openspec/changes`](openspec/changes).
|
|
58
111
|
|
|
59
|
-
|
|
112
|
+
## License
|
|
60
113
|
|
|
61
|
-
|
|
114
|
+
[MIT](LICENSE). Interface tokens adapt the Apache-2.0 [Open Design](https://github.com/nexu-io/open-design) Clean system; see [docs/licenses/open-design.txt](docs/licenses/open-design.txt).
|