spequi 0.1.0 → 0.1.2

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/CHANGELOG.md ADDED
@@ -0,0 +1,14 @@
1
+ # Changelog
2
+
3
+ ## 0.1.2 — 2026-11-14
4
+
5
+ - Sharpen the README opening, show existing screenshots, and move detailed guidance into dedicated docs.
6
+ - Make the Spequi skill the recommended startup path; clarify agent setup, upgrades, analytics, and preview boundaries.
7
+ - Fix the package audit to allow the published changelog.
8
+
9
+ ## 0.1.1 — 2026-11-14
10
+
11
+ - Group requests by spec, prioritize unresolved work, and mark pending inbox items in the header.
12
+ - Refine agent and MCP connection panels, contextual commands, and planning document selection.
13
+ - Simplify review comments and file preview states; add GitHub contribution links and creator credit.
14
+ - Add usage and failure analytics for project activity, spec creation, and file diffs. Events include project names, Git user names when available, and a persistent identifier shared across projects on the same machine account. Source files, prompts, and comments are excluded.
package/README.md CHANGED
@@ -2,289 +2,112 @@
2
2
 
3
3
  # Spequi
4
4
 
5
- **Plan with your agent. Review every change.**
5
+ **Understand the spec. Guide your agent. Review the implementation.**
6
6
 
7
- A local workspace for planning, implementing, and reviewing [OpenSpec](https://openspec.dev/) changes with the coding agent you already use.
7
+ Spequi brings [OpenSpec](https://openspec.dev/) documents, agent conversations, and code diffs into one local workspace.
8
+ Read the plan, give precise feedback, and review the implementation against requirements with the coding agent you already use.
8
9
 
10
+ [![npm](https://img.shields.io/npm/v/spequi?color=cb3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/spequi)
9
11
  [![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-43853d?logo=node.js&logoColor=white)](https://nodejs.org/)
10
12
  [![License: MIT](https://img.shields.io/badge/License-MIT-3f62b5)](LICENSE)
11
- [![No build step](https://img.shields.io/badge/Frontend-No_build_step-626f83)](#stack)
12
-
13
- [Get started](#get-started) · [Build and Review](#build-and-review) · [Features](#features) · [How it works](#how-it-works) · [Agent setup](#attach-your-agent)
13
+ [![No build step](https://img.shields.io/badge/Frontend-no%20build%20step-626f83)](docs/architecture.md)
14
14
 
15
15
  </div>
16
16
 
17
- ## Build and Review
18
-
19
- The switch beside the logo offers two ways to work on the same change. Each label includes a description so you can choose by what you want to do:
17
+ <table>
18
+ <tr>
19
+ <td><img src="docs/screenshots/build-light.png" alt="Planning a spec beside the agent conversation"></td>
20
+ <td><img src="docs/screenshots/file-review-light.png" alt="Reviewing a diff with spec context and inline comments"></td>
21
+ </tr>
22
+ <tr>
23
+ <td align="center"><sub>Plan beside your agent</sub></td>
24
+ <td align="center"><sub>Review the diff against the spec</sub></td>
25
+ </tr>
26
+ </table>
27
+
28
+ ## Quickstart
29
+
30
+ ```bash
31
+ cd /path/to/your-project # a project that contains OpenSpec files
32
+ npx spequi@latest init # sets up .spequi/ and registers the agent skill
33
+ ```
20
34
 
21
- | Mode | Use it to |
22
- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
23
- | **Build — Plan & implement** | Start a spec from an idea, revise the plan with your agent, preview and apply an implementation, then validate and archive. |
24
- | **Review — Inspect & comment** | Read planning documents, inspect actual code diffs and dependency impact, and leave precise feedback for the next revision. |
35
+ Then invoke the Spequi skill **inside your coding agent**, with the same project open:
25
36
 
26
- Start in **Build** to move an idea forward. Switch to **Review** when you want to inspect the plan or proposed files in detail. Both modes use the same saved changes, previews, and comments. Generating a preview never applies it automatically; applying reviewed files requires explicit confirmation.
37
+ | Agent | Run after `init` |
38
+ | --- | --- |
39
+ | GigaCode CLI | `/skills spequi` or `/spequi` |
40
+ | Claude Code | `/spequi` |
41
+ | Codex | `$spequi` |
42
+ | Other skill-capable agents | load `.agents/skills/spequi/SKILL.md` |
27
43
 
28
- ![Build mode showing a planning document beside the conversation, with Shape spec, Implement, and Validate & archive stages.](https://raw.githubusercontent.com/rahulnjs/spequi/master/docs/screenshots/build-light.png)
44
+ The skill starts the local server, shares its URL, and handles requests from the UI. Open the URL it provides, normally **http://127.0.0.1:4310**. Keep the agent session running while you work. Reload your agent if the new skill does not appear.
29
45
 
30
- _Build: shape the spec beside your agent conversation._
46
+ > **Requirements:** Node.js 20+ and npm. For agent-driven work you also need the OpenSpec CLI and its workflow skills
47
+ > (current OpenSpec needs Node.js 22.12+). See [Getting started](docs/getting-started.md).
31
48
 
32
- ![Spequi showing a highlighted implementation diff, an inline review comment, dependency impact, and review feedback.](https://raw.githubusercontent.com/rahulnjs/spequi/master/docs/screenshots/file-review-light.png)
49
+ ## Why Spequi?
33
50
 
34
- _Review: inspect a saved implementation and leave feedback. Screenshots use a local example project._
51
+ Coding agents are fast. Reading what they changed, and checking it against what you *asked for*, is the slow part.
52
+ A plain diff shows **what** changed, not **why**.
35
53
 
36
- <details>
37
- <summary>See both modes in dark theme</summary>
54
+ - **Spec-linked diffs.** Linked code blocks show the requirement or scenario behind them, with source path and line range. Link coverage depends on the preview; suggested file-level context is labelled separately.
55
+ - **Review implementation before applying.** Implementation previews use an isolated copy. Applying is a separate, explicit step with conflict checks and backups. Planning requests update specification files in your project.
56
+ - **Bring your own agent.** GigaCode, Claude Code, Codex, or any skill-capable agent. No extra model endpoint or provider API key to configure.
57
+ - **Local workspace.** The UI binds to `127.0.0.1`. Browsing and offline analysis do not upload source. Your attached agent may send source to its provider; optional model generation sends selected context to your configured endpoint.
38
58
 
39
- ![Build mode in dark theme.](https://raw.githubusercontent.com/rahulnjs/spequi/master/docs/screenshots/build-dark.png)
59
+ Spequi sends usage and failure analytics, including project folder names, Git user names when configured, and a persistent identifier shared across projects on the same machine account. Source files, prompts, and review comments are excluded. See [Security and limits](docs/security.md#analytics).
40
60
 
41
- ![The same OpenSpec review workspace in dark mode.](https://raw.githubusercontent.com/rahulnjs/spequi/master/docs/screenshots/file-review-dark.png)
61
+ ## How it works
42
62
 
43
- </details>
63
+ 1. **Plan.** Click **New spec**, describe an idea, and shape the plan beside your agent's conversation. Drafts save automatically.
64
+ 2. **Preview.** Open **Implement** and request a preview. The agent builds in a separate copy of your project.
65
+ 3. **Review.** Read Proposal, Design and Tasks, then inspect real diffs with available spec links, dependency impact, and inline comments.
66
+ 4. **Apply.** Confirm explicitly. Spequi checks hashes and baseline conflicts, writes the files, and keeps recoverable backups. Then validate and archive.
44
67
 
45
68
  ## Features
46
69
 
47
- | | What you can do |
48
- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
49
- | **Run the lifecycle** | Switch to Build to revise the spec beside its conversation, preview and apply code, then validate and archive. Answer agent questions in the app. |
50
- | **Read the plan** | Browse Proposal, Design, Tasks, active changes, archived changes, and specifications. Switch between rendered Markdown and source. |
51
- | **Review real code** | Compare the current project with an agent's isolated implementation. Use highlighted Unified or Split diffs, changed-word emphasis, context folding, and line wrapping. |
52
- | **Trace changes to the spec** | Read quoted requirements beside changed code blocks, with source lines from the preview’s saved plan. Agent links and suggested file context are labelled separately. |
53
- | **Understand impact** | Inspect direct and downstream dependencies, related tests, and export changes, with explicit static-analysis limitations. |
54
- | **Leave precise feedback** | Add file notes or inline comments on code, Markdown passages, and source ranges. Keep the exact reviewed source context. |
55
- | **Refine the specification** | Export an immutable Markdown review brief or queue a planning update for your agent to reconcile with OpenSpec. |
56
- | **Stay in your workflow** | Use a local Node server and your current skill-capable agent. Switch between light and dark mode. |
57
-
58
- ## Get started
70
+ - **Full lifecycle:** drafts, spec refinement, implementation preview, validate, archive
71
+ - **Unified and split diffs** with syntax highlighting, changed-word emphasis, folding and wrapping
72
+ - **Impact analysis:** direct and downstream dependencies, related tests, export changes
73
+ - **Precise feedback:** comments on files, code ranges and Markdown passages; export a review brief or queue a spec update
74
+ - **Requests inbox:** see questions, failures and running work across all specs
75
+ - **Works offline:** browsing, review, affected-file analysis and patch import need no agent
76
+ - **Light and dark themes**
59
77
 
60
- Requires **Node.js 20+**, npm, and a target project containing OpenSpec files.
78
+ ## Documentation
61
79
 
62
- For the full Build workflow, also install the OpenSpec CLI and make the required OpenSpec workflow skills available to your coding agent, then attach it with the `spequi` skill. Initializing this package installs the UI skill and command wrappers; OpenSpec setup and its workflow skills are separate. Browsing, review, offline affected-file analysis, and patch import work without an attached agent.
80
+ | | |
81
+ | --- | --- |
82
+ | [Getting started](docs/getting-started.md) | Install, initialize, attach an agent, what `init` creates |
83
+ | [Planning workflow](docs/planning.md) | New specs, drafts, slash commands, planning stages |
84
+ | [Review workflow](docs/review.md) | Diffs, spec context, comments, requests inbox |
85
+ | [Offline tools and model preview](docs/offline-and-model.md) | Affected-file analysis, patch import, optional model endpoint |
86
+ | [Agent workflow](docs/agent-workflow.md) | Queue, heartbeat, questions, MCP reports |
87
+ | [Security and limits](docs/security.md) | Local data, boundaries, known limitations |
88
+ | [Architecture](docs/architecture.md) | Stack, repo layout, development, packaging |
63
89
 
64
- The current OpenSpec CLI [requires Node.js 22.12+](https://github.com/Fission-AI/OpenSpec/blob/main/package.json), independently of this UI’s Node.js 20 minimum. Use Node.js 22.12+ for the complete setup with current OpenSpec.
90
+ ## Status
65
91
 
66
- ### Initialize with npx
92
+ Spequi is early. It is tested with Claude Code and Codex flows; continuous polling in a real GigaCode session and
93
+ native Windows execution are not yet verified. Static impact analysis can miss dynamic references and aliases.
94
+ See [Security and limits](docs/security.md) for the full list.
67
95
 
68
- ```sh
69
- cd /path/to/your-project
70
- npx spequi@latest init
71
- ```
96
+ Feedback and bug reports are welcome in [Issues](https://github.com/rahulnjs/spequi/issues).
72
97
 
73
- Then invoke the registered viewer skill in your agent, or start the server directly:
74
-
75
- ```sh
76
- node .spequi/server.mjs
77
- ```
78
-
79
- A global installation is also supported:
80
-
81
- ```sh
82
- npm install -g spequi
83
- spequi init
84
- spequi start
85
- ```
98
+ ## Contributing
86
99
 
87
- Automatic browser opening is not implemented; open the printed URL or use your agent's browser capabilities.
88
-
89
- ### Run from source
90
-
91
- ```sh
100
+ ```bash
92
101
  git clone https://github.com/rahulnjs/spequi.git
93
102
  cd spequi
94
103
  npm ci
95
-
96
- node bin/spequi.mjs init --root "/path/to/your-project"
97
- node bin/spequi.mjs start --root "/path/to/your-project"
98
- ```
99
-
100
- Open the printed URL, normally **http://127.0.0.1:4310**. To choose another port, add `--port 4311` to the start command.
101
-
102
- Point the viewer at your own project. This repository keeps its runtime source and README screenshots; it does not ship sample OpenSpec plans. An empty project shows setup guidance. Initialize OpenSpec separately when needed.
103
-
104
- ## Attach your agent
105
-
106
- The viewer uses **your existing coding agent**. It does not launch a model or require a separate provider API key.
107
-
108
- | Agent | Invoke after initialization |
109
- | -------------------------- | ---------------------------------------------------------------------- |
110
- | Claude Code | `/spequi`; use `/spequi init` for setup |
111
- | Codex | `$spequi`, or select the viewer skill |
112
- | Sber/GitVerse GigaCode CLI | `/skills spequi` or `/spequi` |
113
- | Other skill-capable agents | Load `.agents/skills/spequi/SKILL.md` using the tool's own convention |
114
-
115
- Reload your agent if newly generated commands or skills do not appear. Command discovery and slash syntax depend on the agent.
116
-
117
- The skill starts the local server and consumes queued requests. Without an attached agent, browsing, review, offline affected-file analysis, and patch import remain available. Agent implementation and planning requests wait in the queue; optional configured model generation can produce proposed edits directly.
118
-
119
- The attached session also runs the installed skills selected by each job: `openspec-apply-change` for preview implementation, `openspec-propose` for proposals, `openspec-update-change` for feedback, and `openspec-archive-change` for archive requests. Exploration and verification use their corresponding installed workflows when available, with read-only fallbacks; impact reports run directly. The agent loads the selected skill in the same session, reports the result, and resumes polling. No second agent process or model connection is started for this handoff. Required missing workflows produce a failed job with an explanation; they are not installed automatically. Preview workflow edits and task updates stay in the isolated copy; viewer log/finish/fail commands run from the original project. Refresh an initialized project's skill with `node .spequi/cli.mjs skill install` to receive these routing instructions.
120
-
121
- ## How it works
122
-
123
- 1. **Initialize and attach.** Create project-local launchers and connect your existing coding agent with the `spequi` skill.
124
- 2. **Plan in Build.** Choose **New spec** to describe an idea, or open an existing change. Create the next planning artifact or a full plan; answer your agent's questions in the conversation.
125
- 3. **Preview in Build.** Open **Implement** and request a preview. Your agent works in a separate project copy; finishing freezes the proposed files for inspection.
126
- 4. **Inspect in Review.** Read Proposal, Design, and Tasks, then inspect Files with actual diffs, quoted spec context at linked change blocks, dependency impact, and inline comments.
127
- 5. **Refine.** Export feedback or select **Update spec** to request a planning revision from that exact snapshot. Generate a fresh preview when the plan changes.
128
- 6. **Apply and finish in Build.** Explicitly apply the reviewed preview, validate the spec, verify implementation with your agent, then sync or archive when ready.
129
-
130
- Spec revisions and implementation previews are separate actions. Exporting feedback does not edit a specification or apply code. The underlying apply API checks retained hashes and baseline conflicts before writing reviewed files and keeping recoverable backups.
131
-
132
- ### Spec context in diffs
133
-
134
- In both modes, linked change blocks show the requirement, scenario, or planning decision behind the edit. Each quote includes its source path and line range from the preview’s retained baseline. Collapse a quote to focus on code; repeated links point back to the first quote.
135
-
136
- The attached agent records code-to-spec locations while implementing. Older previews and imported patches can show **Suggested · file-level** context when the saved plan mentions the file or a changed symbol. Suggestions need reviewer confirmation. Files without a supported match say so explicitly. Refresh an initialized project's skill with `node .spequi/cli.mjs skill install` to enable recorded links for new previews. See the [agent metadata format](docs/agent-workflow.md#spec-links-in-implementation-previews).
137
-
138
- ### What initialization creates
139
-
140
- ```text
141
- your-project/
142
- ├── .spequi/
143
- │ ├── config.json # Port and initialized viewer version
144
- │ ├── cli.mjs # Project command launcher
145
- │ ├── server.mjs # Server launcher
146
- │ ├── jobs/ # Queued agent requests
147
- │ ├── previews/ # Isolated baseline and proposed files
148
- │ └── backups/ # Recoverable applied-file backups
149
- ├── .agents/skills/spequi/SKILL.md
150
- ├── .claude/commands/spequi.md
151
- └── .gigacode/
152
- ├── skills/spequi/SKILL.md
153
- └── commands/spequi.md
154
- ```
155
-
156
- Feedback storage is created when needed. Initialization installs the `/spequi` command wrappers and adds `/.spequi/`, `/.agents/`, `/.claude/`, and `/.gigacode/` to the project's `.gitignore`. Existing ignore rules are preserved; files already tracked by Git remain tracked.
157
-
158
- GigaCode registration follows its documented [skill discovery](https://gitverse.ru/docs/ai/ai-assistant-gigacode/gigacode-cli/skills) and [custom command format](https://gitverse.ru/docs/ai/ai-assistant-gigacode/gigacode-cli/commands), including `{{args}}` for command arguments. `init` and `skill install` register the project; `skill install --global` writes registrations under the user's home directory. Existing initialized projects can refresh with `node .spequi/cli.mjs skill install` when their initialized runtime includes this change. Registration is tested; continuous polling in a real GigaCode session has not yet been verified. Required OpenSpec workflows must be installed separately and discoverable by GigaCode.
159
-
160
- Repeat initialization preserves Spequi configuration, comments, previews, application files, and custom launchers. An explicit reinitialization refreshes managed launchers and agent registration. If the original cached package disappears, the launcher can retrieve the initialized version through npm; registry access is needed for that recovery.
161
-
162
- ## Build workflow
163
-
164
- ### Start a spec from an idea
165
-
166
- Choose **New spec** in the left panel. Describe the idea and give it an unused lowercase change name. **Start with the next artifact** is the default; **Generate the full plan** requests all required planning artifacts. Continue queues one owned planning request for the attached agent. Its questions stay in the app, replies survive reloads, and the generated change opens in Build when the request completes. Partial plans offer the next schema-ready artifact; planning never automatically starts implementation.
167
-
168
- The **Commands** picker in Build and slash commands use the same guarded operations. Supported commands are `/new`, `/explore <question>`, `/continue`, `/propose`, `/update <revision>`, `/apply`, `/status`, `/validate`, `/verify`, `/sync`, and `/archive`. `/opsx:<name>` and `/opsx-<name>` aliases also work inside the app. These are app commands, independent of the host's slash-command installation. `/apply` generates an isolated implementation preview; writing reviewed files still requires the separate Apply confirmation. Status and validation use the installed local OpenSpec CLI. Other commands wait for the existing agent session.
169
-
170
- Build retains planning versions under `.spequi/studio/`. A revision stores exact Markdown before a planning request and after it completes; pending writes are not shown as completed revisions. The most recent 40 versions are retained, with at most 8 MiB of planning documents per version. This is local review evidence; the files under `openspec/` remain the source of truth.
171
-
172
- Switch between **Review** and **Build** using the switch beside the logo. Build keeps the project panel in place and puts **Shape spec**, **Implement**, and **Validate & archive** in its header. The document or evidence canvas sits beside one continuous conversation. On narrow screens, use **Document / Conversation**.
173
-
174
- In **Shape spec**, select a planning artifact tab and use **Revise spec** to request an update, or **Ask a question** for a read-only exploration. Changes appear as highlighted sections and a document summary. Capabilities with multiple documents show file tabs below their artifact tab. **Planning actions** offers the next artifact or full plan. Documents remain read-only.
175
-
176
- In **Implement**, generate an isolated preview and choose its version. Browse changed files directly beneath the selected change in the left panel; filenames show their folder and edit counts, with no file search field. The **Files** button brings that list into view or opens the project drawer on smaller screens. Previous/next file controls, the selected file and diff tools stay above the independently scrolling code. Selecting a file keeps the same preview and Build mode. Inspect the actual diff, then explicitly confirm **Apply reviewed preview**. A changed spec or source conflict prevents application. **Validate & archive** distinguishes local spec validation from agent implementation verification and exposes sync and archive with their normal prerequisites. Archive confirmations appear in the conversation. **New spec** starts the idea-to-plan flow; existing lifecycle URLs remain available for compatibility.
177
-
178
- Status, task readiness, and strict specification validation use the installed `openspec` CLI locally, with no agent required. Missing/incompatible CLI capabilities disable those actions with an explanation while documents and saved diffs remain readable. Spec validation checks requirements; checked task boxes alone do not prove implementation correctness. Setup and administration stay outside this UI.
179
-
180
- Reasoning and writing requests use the current session running the viewer skill. Refresh the project skill after upgrading with `node .spequi/cli.mjs skill install`. Required workflows must already be installed; the viewer never launches another agent for a skill handoff. The agent uses `agent ask <id> --token <token> --message "question" [--options '["Yes","No"]']`, then `agent input <id> --token <token> --wait 20` until the app replies. The existing job resumes with the same ownership token; queued and awaiting-input requests can be cancelled. A running request can be ended only after its owning session’s heartbeat expires; stop the old agent in your coding tool first, since ending a request does not terminate its process or undo edits. Keep the agent session attached to continue waiting work.
181
-
182
- Implementation previews still use isolated copies and apply only through an explicit, conflict-checked action. Offline affected-file analysis, optional model proposals, and patch import are available in Build’s Implement stage; generated source also remains reviewable in Review → Files.
183
-
184
- A saved preview becomes stale when its planning documents change. Generate a fresh preview before applying. Spec updates stay in the same page, with active questions and results shown in the main flow.
185
-
186
- ## Review workflow
187
-
188
- Choose **Review — Inspect & comment** to examine a change through **Proposal**, **Design**, **Tasks**, and **Files**. Documents support rendered Markdown and source. Files compares the current and proposed versions with Unified or Split diffs, syntax highlighting, changed-word emphasis, folding, and wrapping. The inspector follows the selected file with dependency impact and saved comments.
189
-
190
- Comment on a whole file, a code range, or a passage in Proposal or Design. Notes retain the exact reviewed version. **Export MD** downloads a feedback brief; **Update spec** queues a planning revision for the attached agent. Return to Build to continue the conversation, generate a new implementation preview, or apply reviewed code.
191
-
192
- ## Agent-free analysis and previews
193
-
194
- Under **Build → Implement → Offline analysis and preview tools**, **Analyze affected files** matches the selected change's planning documents to current source without an agent or network. It explains explicit paths, named symbols, related text, and local dependencies separately from actual changed files. Analysis scans at most 1,000 text files, 512 KB per file, and 8 MiB of source; planning documents are limited to 2 MiB total. Exclusions, skipped files, unresolved references, and stale inputs are disclosed. Dynamic references, aliases, external packages, and dependencies outside supported JS/TS, CSS, and HTML forms can be missed.
195
-
196
- **Import patch** stages a unified patch in a separate project copy without an agent. Patches can add, modify, and delete up to 30 eligible UTF-8 files, within a 1 MiB patch/proposed-content limit. Renames are represented as deletion and addition. Review the saved diff, export it, add comments, or explicitly apply it using the existing baseline conflict checks. A failed import does not publish a partially completed preview.
197
-
198
- For optional generation without an agent session, add `previewModel` to `.spequi/config.json` while preserving its other settings:
199
-
200
- ```json
201
- {
202
- "version": 1,
203
- "port": 4310,
204
- "previewModel": {
205
- "endpoint": "http://127.0.0.1:11434/v1/chat/completions",
206
- "model": "your-installed-model",
207
- "timeoutMs": 120000
208
- }
209
- }
210
- ```
211
-
212
- The endpoint must accept Chat Completions-compatible JSON and return text at `choices[0].message.content`; a compatible local runtime can keep generation offline. No model is installed or downloaded by the viewer. Hosted endpoints require HTTPS; plain HTTP is accepted only for loopback hosts. If authentication is required, set `"apiKeyEnv": "SPEQUI_PREVIEW_API_KEY"` and supply that environment variable to the viewer process. Credentials stay server-side; do not put an API key in the endpoint URL.
213
-
214
- Analyze first, select between 1 and 12 candidate files, and choose **Generate with model**. This action sends the change's planning documents and the selected files to the displayed destination. It sends no other source context. The combined input is limited to 256 KB; output is limited to 30 edits and 1 MiB of proposed source. Stale analyses require a new scan. Existing files outside the selected context, secrets, planning artifacts, agent configuration, and escaping paths cannot be edited. Eligible new source files can be added. The model returns file contents only: the viewer runs no tools, shell commands, installations, or implementation tests. Generated and imported previews show their origin and unrun-check status; review and test before applying.
215
-
216
- All UI styles, scripts (including HTMX), and fonts are served by the local viewer. DM Sans and IBM Plex Mono are bundled with their licenses, so the installed UI needs no CDN or internet access. Installation and package recovery through npm still require registry access unless the packages are already available locally.
217
-
218
- ## Stack
219
-
220
- **Node.js ES modules · server-rendered HTML · HTMX · WebSockets · plain CSS and JavaScript**
221
-
222
- No frontend compilation or hosted backend. Runtime dependencies handle watching, Markdown sanitization, syntax highlighting, diffs, and WebSocket transport.
223
-
224
- ```text
225
- bin/ Executable CLI
226
- src/ Server, project reader, previews, impact, and review implementation
227
- public/ Runtime styles and browser JavaScript
228
- skills/ Maintained portable agent skill
229
- templates/ Self-contained project launcher template
230
- docs/ README screenshots; excluded from the npm package
231
- ```
232
-
233
- ## Local data and boundaries
234
-
235
- - The server binds to `127.0.0.1`; mutations require local Host/Origin checks and a session token.
236
- - `.spequi/` contains local configuration, requests, previews, feedback, and backups. Keep it out of Git.
237
- - Browsing and offline analysis do not upload project source. Explicit model generation sends the planning documents and selected source to the configured endpoint. Your attached agent retains its own provider and permission settings.
238
- - A preview copy is not an OS security sandbox. The agent must honor its assigned working directory.
239
- - Static impact evidence does not establish complete runtime behavior, dynamic references, aliases, or external-package effects. Scan limitations remain visible.
240
- - LF and CRLF comparisons use normalized display lines; retained hashes, patches, and application preserve the exact reviewed bytes. Native Windows execution remains a release verification item.
241
-
242
- ## Development and packaging
243
-
244
- ```sh
245
- npm ci
246
104
  npm run check
247
- npm pack --dry-run
248
- npm publish --dry-run
249
- ```
250
-
251
- There is no build step. `package.json.files` limits the npm archive to runtime code/assets, the portable skill, launcher template, package metadata, README, and license. Screenshots and local development/sample data are excluded. Publication runs syntax checks first.
252
-
253
- ## Naming and project data
254
-
255
- The app is **Spequi**. Its npm package, shell command, and agent skill are **spequi**: use `$spequi` in Codex, or `/spequi` in tools that support those command wrappers. Reload your agent after registration if it has not discovered the new skill.
256
-
257
- Initialization creates `.spequi/` for local configuration, queued jobs, previews, comments, and backups. Run `spequi init` to refresh managed launchers and skill registrations; custom launchers are preserved. The agent command is `/spequi`.
258
-
259
- Spequi starts fresh in `.spequi/`. Initialization does not import, move, rename, or delete data from earlier tools.
260
-
261
- ## Agent liveness and MCP reports
262
-
263
- For the code-level attachment, skill routing, question and completion flow, see [How the agent workflow works](docs/agent-workflow.md).
264
-
265
- The header's agent indicator reflects a recent agent heartbeat, independently of the browser connection to the local server. It distinguishes live, working, awaiting an answer, not responding, and unattached. Connection details show the last heartbeat and MCP metadata reported by the current session. **Reconnect agent** opens instructions to resume the spequi skill in the same coding session, with a **Check connection** action. Requests and answers stay saved; the viewer does not restart an agent automatically.
266
-
267
- The agent can write a credential-free report under `.spequi`, then run:
268
-
269
- ```sh
270
- node .spequi/cli.mjs agent report --file .spequi/session-report.json --name "Skill agent"
271
- ```
272
-
273
- For example, when the host provides authoritative connection status:
274
-
275
- ```json
276
- {
277
- "sessionId": "a-stable-random-id-for-this-attachment",
278
- "mcps": {
279
- "supported": true,
280
- "connections": [{ "name": "Filesystem", "status": "connected" }]
281
- }
282
- }
105
+ node bin/spequi.mjs init --root /path/to/test-project
283
106
  ```
284
107
 
285
- Allowed MCP statuses are `connected`, `disconnected`, `unavailable`, and `unknown`. Only display names and statuses are accepted; omit credentials, server URLs, environment variables and transport configuration. When the agent host cannot enumerate connection status, report `{"mcps":{"supported":false,"connections":[]}}` instead. A tool catalog or configured server alone is insufficient evidence of a healthy connection. Retain the returned session ID for report refreshes, pass it as `agent next --session-id <id>` and use the same agent name when polling, and refresh at least every five minutes or when connections change. Missing, expired and disconnected-session reports display unknown rather than a fabricated count. Reporting does not replace serving the agent queue.
108
+ Open the test project in your coding agent and invoke the Spequi skill to start the workspace.
286
109
 
287
- The header uses **MCPs** when the current session has not supplied connection evidence; the details explain why. **0 MCPs** is shown only when a fresh supported report confirms zero connections. Build keeps the current conversation and document independently scrollable, compacts the composer and action footer, shows current progress without expanding Activity, and collapses older completed exchanges. New documents use normal prose; changed-section highlights begin with revisions to existing text.
110
+ See [Architecture](docs/architecture.md) for the repo layout.
288
111
 
289
112
  ## License
290
113
 
package/bin/spequi.mjs CHANGED
@@ -5,13 +5,25 @@ import { reportSession } from '../src/agent-session.mjs';
5
5
  import { setTimeout as delay } from 'node:timers/promises';
6
6
  import { initProject, installSkill, viewerVersion } from '../src/project.mjs';
7
7
  import { startServer } from '../src/server.mjs';
8
- import { claimNext, updateJob, listJobs } from '../src/jobs.mjs';
8
+ import { claimNext, updateJob, listJobs, heartbeat, stopPolling, queueStatus } from '../src/jobs.mjs';
9
9
  import { askJob, jobInput } from '../src/job-dialogue.mjs';
10
+ import { agentRequest } from '../src/agent-client.mjs';
10
11
 
11
12
  const argv = process.argv.slice(2);
12
13
  function option(name, fallback) { const position = argv.indexOf(`--${name}`); return position >= 0 ? argv[position + 1] : fallback; }
13
14
  function print(value) { process.stdout.write(JSON.stringify(value, null, 2) + '\n'); }
14
15
  const root = path.resolve(option('root', process.cwd()));
16
+ const agentName = () => option('name', 'Spequi Agent');
17
+ function waitSeconds(fallback = 0) {
18
+ const value = Number(option('wait', fallback));
19
+ if (!Number.isFinite(value) || value < 0 || value > 300) throw new Error('Wait must be between 0 and 300 seconds');
20
+ return value;
21
+ }
22
+ async function agentCall(operation, payload, fallback) {
23
+ const connection = await agentRequest(root, operation, { name: agentName(), sessionId: option('session-id'), ...payload });
24
+ if (connection.available) return operation === 'list' ? connection.result.jobs : connection.result;
25
+ return fallback();
26
+ }
15
27
  try {
16
28
  const [command, subcommand, id] = argv;
17
29
  if (command === 'init') {
@@ -26,22 +38,43 @@ try {
26
38
  if (!reportFile || (await fs.stat(reportFile)).size > 32768) throw new Error('Use --file with a session report under 32 KiB');
27
39
  const report = JSON.parse(await fs.readFile(reportFile, 'utf8'));
28
40
  if (!report || Object.keys(report).some(key => !['sessionId', 'mcps'].includes(key))) throw new Error('Session reports accept sessionId and mcps only');
29
- print(await reportSession(root, {...report, agent: option('name', 'Skill agent')}));
30
- } else if (subcommand === 'next') {
31
- const wait = Math.min(60, Math.max(0, Number(option('wait', 0)) || 0));
32
- const deadline = Date.now() + wait * 1000;
33
- let job;
34
- do { job = await claimNext(root, option('name', 'Skill agent'), option('session-id')); if (job || Date.now() >= deadline) break; await delay(1000); } while (true);
35
- print({ job });
36
- } else if (subcommand === 'ask') print(await askJob(root, id, option('token'), { message: option('message', ''), options: JSON.parse(option('options', '[]')) }));
37
- else if (subcommand === 'input') {
38
- const deadline = Date.now() + Math.min(60, Math.max(0, Number(option('wait', 0)) || 0)) * 1000;
39
- let result;
40
- do { result = await jobInput(root, id, option('token')); if (result.status !== 'awaiting-input' || Date.now() >= deadline) break; await delay(1000); } while (true);
41
- print(result);
42
- } else if (['log', 'finish', 'fail'].includes(subcommand)) print(await updateJob(root, id, option('token'), subcommand, option('message', '')));
43
- else if (subcommand === 'list') print((await listJobs(root)).map(({ claimToken, instructions, ...job }) => job));
44
- else throw new Error('Use agent report, next, ask, input, log, finish, fail, or list');
41
+ print(await agentCall('report', { report }, () => reportSession(root, { ...report, agent: agentName() })));
42
+ } else if (['next', 'wait'].includes(subcommand)) {
43
+ const wait = waitSeconds(subcommand === 'wait' ? 300 : 0);
44
+ print(await agentCall(subcommand, { wait }, async () => {
45
+ const deadline = Date.now() + wait * 1000;
46
+ const pollId = String(process.pid);
47
+ try {
48
+ do {
49
+ await heartbeat(root, agentName(), option('session-id'), { polling: true, pollId });
50
+ const queue = await queueStatus(root);
51
+ if (subcommand === 'wait' && queue.queued && !queue.active) return { available: true, queue };
52
+ if (subcommand === 'next') {
53
+ const job = await claimNext(root, agentName(), option('session-id'));
54
+ if (job) return { job };
55
+ }
56
+ if (queue.status === 'blocked') throw new Error(queue.message);
57
+ if (Date.now() >= deadline) return subcommand === 'wait' ? { available: false, queue } : { job: null, queue };
58
+ await delay(250);
59
+ } while (true);
60
+ } finally { await stopPolling(root, agentName(), option('session-id'), pollId); }
61
+ }));
62
+ } else if (subcommand === 'ask') {
63
+ const payload = { id, token: option('token'), message: option('message', ''), options: JSON.parse(option('options', '[]')) };
64
+ print(await agentCall('ask', payload, () => askJob(root, id, payload.token, payload)));
65
+ } else if (subcommand === 'input') {
66
+ const wait = waitSeconds();
67
+ print(await agentCall('input', { id, token: option('token'), wait }, async () => {
68
+ const deadline = Date.now() + wait * 1000;
69
+ let result;
70
+ do { result = await jobInput(root, id, option('token')); if (result.status !== 'awaiting-input' || Date.now() >= deadline) break; await delay(250); } while (true);
71
+ return result;
72
+ }));
73
+ } else if (['log', 'finish', 'fail'].includes(subcommand)) {
74
+ const payload = { id, token: option('token'), message: option('message', '') };
75
+ print(await agentCall(subcommand, payload, () => updateJob(root, id, payload.token, subcommand, payload.message)));
76
+ } else if (subcommand === 'list') print(await agentCall('list', {}, async () => (await listJobs(root)).map(({ claimToken, instructions, ...job }) => job)));
77
+ else throw new Error('Use agent report, wait, next, ask, input, log, finish, fail, or list');
45
78
  } else if (command === '--version' || command === '-v') process.stdout.write(viewerVersion + '\n');
46
- else process.stdout.write(`spequi\n\n spequi init [--start] Scaffold .spequi and install project skills\n spequi start [--port 4310] Open the local project workspace\n spequi skill install --global Install the skill for future projects\n spequi agent next --wait 20 Claim a browser request as the current agent\n spequi agent log|finish|fail <id> --token <token> --message "result"\n spequi agent ask <id> --token <token> --message "question" [--options '["Yes","No"]']\n spequi agent input <id> --token <token> --wait 20\n spequi agent report --file <session.json> [--name "Skill agent"]\n spequi agent list\n\nEvery command accepts --root <project>. No build step or agent API key required.\n`);
79
+ else process.stdout.write(`spequi\n\n spequi init [--start] Scaffold .spequi and install project skills\n spequi start [--port 4310] Open the local project workspace\n spequi skill install --global Install the skill for future projects\n spequi agent wait --wait 300 Wait for work without claiming it\n spequi agent next Claim when the current agent is ready\n spequi agent log|finish|fail <id> --token <token> --message "result"\n spequi agent ask <id> --token <token> --message "question" [--options '["Yes","No"]']\n spequi agent input <id> --token <token> --wait 300\n spequi agent report --file <session.json> [--name "Spequi Agent"]\n spequi agent list\n\nEvery command accepts --root <project>. No build step or agent API key required.\n`);
47
80
  } catch (error) { process.stderr.write(`spequi: ${error.message}\n`); process.exitCode = 1; }