spequi 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +290 -2
- package/bin/spequi.mjs +47 -0
- package/docs/agent-workflow.md +470 -0
- package/package.json +70 -4
- package/public/app.css +62 -0
- package/public/app.js +228 -0
- package/public/diff.css +217 -0
- package/public/fonts/README.md +22 -0
- package/public/fonts/dm-sans-OFL.txt +93 -0
- package/public/fonts/dm-sans-variable-latin-ext.woff2 +0 -0
- package/public/fonts/dm-sans-variable-latin.woff2 +0 -0
- package/public/fonts/ibm-plex-mono-400-cyrillic-ext.woff2 +0 -0
- package/public/fonts/ibm-plex-mono-400-cyrillic.woff2 +0 -0
- package/public/fonts/ibm-plex-mono-400-latin-ext.woff2 +0 -0
- package/public/fonts/ibm-plex-mono-400-latin.woff2 +0 -0
- package/public/fonts/ibm-plex-mono-400-vietnamese.woff2 +0 -0
- package/public/fonts/ibm-plex-mono-500-cyrillic-ext.woff2 +0 -0
- package/public/fonts/ibm-plex-mono-500-cyrillic.woff2 +0 -0
- package/public/fonts/ibm-plex-mono-500-latin-ext.woff2 +0 -0
- package/public/fonts/ibm-plex-mono-500-latin.woff2 +0 -0
- package/public/fonts/ibm-plex-mono-500-vietnamese.woff2 +0 -0
- package/public/fonts/ibm-plex-mono-OFL.txt +93 -0
- package/public/fonts.css +109 -0
- package/public/lifecycle.css +93 -0
- package/public/lifecycle.js +84 -0
- package/public/review.css +272 -0
- package/public/review.js +358 -0
- package/public/session.js +50 -0
- package/public/studio.css +161 -0
- package/public/studio.js +188 -0
- package/skills/spequi/SKILL.md +74 -0
- package/src/agent-session.mjs +32 -0
- package/src/commands.mjs +49 -0
- package/src/comment-controls.mjs +10 -0
- package/src/comment-view.mjs +51 -0
- package/src/creation-view.mjs +13 -0
- package/src/diff-comments.mjs +8 -0
- package/src/diff-view.mjs +70 -0
- package/src/diffs.mjs +88 -0
- package/src/direct-preview.mjs +168 -0
- package/src/document-view.mjs +75 -0
- package/src/feedback.mjs +86 -0
- package/src/files.mjs +50 -0
- package/src/highlighting.mjs +91 -0
- package/src/impact-view.mjs +30 -0
- package/src/impact.mjs +161 -0
- package/src/job-dialogue.mjs +41 -0
- package/src/jobs.mjs +174 -0
- package/src/lifecycle-view.mjs +58 -0
- package/src/lifecycle.mjs +119 -0
- package/src/openspec-cli.mjs +40 -0
- package/src/preview-view.mjs +83 -0
- package/src/previews.mjs +112 -0
- package/src/project.mjs +59 -0
- package/src/review-store.mjs +150 -0
- package/src/review-view.mjs +23 -0
- package/src/server.mjs +175 -0
- package/src/source-preview-view.mjs +14 -0
- package/src/spec-context-view.mjs +37 -0
- package/src/spec-context.mjs +147 -0
- package/src/spec-impact.mjs +145 -0
- package/src/specs.mjs +80 -0
- package/src/studio-documents.mjs +25 -0
- package/src/studio-plans.mjs +71 -0
- package/src/studio-view.mjs +93 -0
- package/src/views.mjs +101 -0
- package/templates/cli.mjs +38 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 openspec-ui contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,291 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# Spequi
|
|
4
|
+
|
|
5
|
+
**Plan with your agent. Review every change.**
|
|
6
|
+
|
|
7
|
+
A local workspace for planning, implementing, and reviewing [OpenSpec](https://openspec.dev/) changes with the coding agent you already use.
|
|
8
|
+
|
|
9
|
+
[](https://nodejs.org/)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
[](#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)
|
|
14
|
+
|
|
15
|
+
</div>
|
|
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:
|
|
20
|
+
|
|
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. |
|
|
25
|
+
|
|
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.
|
|
27
|
+
|
|
28
|
+

|
|
29
|
+
|
|
30
|
+
_Build: shape the spec beside your agent conversation._
|
|
31
|
+
|
|
32
|
+

|
|
33
|
+
|
|
34
|
+
_Review: inspect a saved implementation and leave feedback. Screenshots use a local example project._
|
|
35
|
+
|
|
36
|
+
<details>
|
|
37
|
+
<summary>See both modes in dark theme</summary>
|
|
38
|
+
|
|
39
|
+

|
|
40
|
+
|
|
41
|
+

|
|
42
|
+
|
|
43
|
+
</details>
|
|
44
|
+
|
|
45
|
+
## Features
|
|
46
|
+
|
|
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
|
|
59
|
+
|
|
60
|
+
Requires **Node.js 20+**, npm, and a target project containing OpenSpec files.
|
|
61
|
+
|
|
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.
|
|
63
|
+
|
|
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.
|
|
65
|
+
|
|
66
|
+
### Initialize with npx
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
cd /path/to/your-project
|
|
70
|
+
npx spequi@latest init
|
|
71
|
+
```
|
|
72
|
+
|
|
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
|
+
```
|
|
86
|
+
|
|
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
|
|
92
|
+
git clone https://github.com/rahulnjs/spequi.git
|
|
93
|
+
cd spequi
|
|
94
|
+
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
|
+
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
|
+
}
|
|
283
|
+
```
|
|
284
|
+
|
|
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.
|
|
286
|
+
|
|
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.
|
|
288
|
+
|
|
289
|
+
## License
|
|
290
|
+
|
|
291
|
+
[MIT](LICENSE)
|
package/bin/spequi.mjs
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import fs from 'node:fs/promises';
|
|
4
|
+
import { reportSession } from '../src/agent-session.mjs';
|
|
5
|
+
import { setTimeout as delay } from 'node:timers/promises';
|
|
6
|
+
import { initProject, installSkill, viewerVersion } from '../src/project.mjs';
|
|
7
|
+
import { startServer } from '../src/server.mjs';
|
|
8
|
+
import { claimNext, updateJob, listJobs } from '../src/jobs.mjs';
|
|
9
|
+
import { askJob, jobInput } from '../src/job-dialogue.mjs';
|
|
10
|
+
|
|
11
|
+
const argv = process.argv.slice(2);
|
|
12
|
+
function option(name, fallback) { const position = argv.indexOf(`--${name}`); return position >= 0 ? argv[position + 1] : fallback; }
|
|
13
|
+
function print(value) { process.stdout.write(JSON.stringify(value, null, 2) + '\n'); }
|
|
14
|
+
const root = path.resolve(option('root', process.cwd()));
|
|
15
|
+
try {
|
|
16
|
+
const [command, subcommand, id] = argv;
|
|
17
|
+
if (command === 'init') {
|
|
18
|
+
print(await initProject(root));
|
|
19
|
+
if (argv.includes('--start')) await startServer({ root, port: option('port') === undefined ? undefined : Number(option('port')) });
|
|
20
|
+
else process.stdout.write('\nReady. Run node .spequi/server.mjs, or invoke /spequi in your agent.\n');
|
|
21
|
+
} else if (command === 'start' || command === 'serve') await startServer({ root, port: option('port') === undefined ? undefined : Number(option('port')) });
|
|
22
|
+
else if (command === 'skill' && subcommand === 'install') print(await installSkill(root, argv.includes('--global')));
|
|
23
|
+
else if (command === 'agent') {
|
|
24
|
+
if (subcommand === 'report') {
|
|
25
|
+
const reportFile = option('file');
|
|
26
|
+
if (!reportFile || (await fs.stat(reportFile)).size > 32768) throw new Error('Use --file with a session report under 32 KiB');
|
|
27
|
+
const report = JSON.parse(await fs.readFile(reportFile, 'utf8'));
|
|
28
|
+
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');
|
|
45
|
+
} 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`);
|
|
47
|
+
} catch (error) { process.stderr.write(`spequi: ${error.message}\n`); process.exitCode = 1; }
|