spequi 0.0.0-stage → 0.1.1

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 (73) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/LICENSE +21 -0
  3. package/README.md +292 -2
  4. package/bin/spequi.mjs +80 -0
  5. package/docs/agent-workflow.md +459 -0
  6. package/package.json +79 -4
  7. package/public/app.css +171 -0
  8. package/public/app.js +328 -0
  9. package/public/diff.css +217 -0
  10. package/public/fonts/README.md +22 -0
  11. package/public/fonts/dm-sans-OFL.txt +93 -0
  12. package/public/fonts/dm-sans-variable-latin-ext.woff2 +0 -0
  13. package/public/fonts/dm-sans-variable-latin.woff2 +0 -0
  14. package/public/fonts/ibm-plex-mono-400-cyrillic-ext.woff2 +0 -0
  15. package/public/fonts/ibm-plex-mono-400-cyrillic.woff2 +0 -0
  16. package/public/fonts/ibm-plex-mono-400-latin-ext.woff2 +0 -0
  17. package/public/fonts/ibm-plex-mono-400-latin.woff2 +0 -0
  18. package/public/fonts/ibm-plex-mono-400-vietnamese.woff2 +0 -0
  19. package/public/fonts/ibm-plex-mono-500-cyrillic-ext.woff2 +0 -0
  20. package/public/fonts/ibm-plex-mono-500-cyrillic.woff2 +0 -0
  21. package/public/fonts/ibm-plex-mono-500-latin-ext.woff2 +0 -0
  22. package/public/fonts/ibm-plex-mono-500-latin.woff2 +0 -0
  23. package/public/fonts/ibm-plex-mono-500-vietnamese.woff2 +0 -0
  24. package/public/fonts/ibm-plex-mono-OFL.txt +93 -0
  25. package/public/fonts.css +109 -0
  26. package/public/requests.js +328 -0
  27. package/public/review.css +286 -0
  28. package/public/review.js +361 -0
  29. package/public/session.js +161 -0
  30. package/public/studio.css +259 -0
  31. package/public/studio.js +179 -0
  32. package/public/workflow.js +105 -0
  33. package/skills/spequi/SKILL.md +79 -0
  34. package/src/agent-client.mjs +17 -0
  35. package/src/agent-session.mjs +33 -0
  36. package/src/analytics.mjs +63 -0
  37. package/src/commands.mjs +73 -0
  38. package/src/comment-controls.mjs +10 -0
  39. package/src/comment-view.mjs +52 -0
  40. package/src/creation-view.mjs +13 -0
  41. package/src/diff-comments.mjs +8 -0
  42. package/src/diff-view.mjs +79 -0
  43. package/src/diffs.mjs +88 -0
  44. package/src/direct-preview.mjs +169 -0
  45. package/src/document-view.mjs +75 -0
  46. package/src/drafts.mjs +83 -0
  47. package/src/feedback.mjs +86 -0
  48. package/src/files.mjs +123 -0
  49. package/src/highlighting.mjs +91 -0
  50. package/src/impact-view.mjs +30 -0
  51. package/src/impact.mjs +161 -0
  52. package/src/job-dialogue.mjs +41 -0
  53. package/src/jobs.mjs +269 -0
  54. package/src/lifecycle.mjs +114 -0
  55. package/src/openspec-cli.mjs +40 -0
  56. package/src/preview-view.mjs +96 -0
  57. package/src/previews.mjs +116 -0
  58. package/src/project.mjs +61 -0
  59. package/src/requests.mjs +80 -0
  60. package/src/review-store.mjs +150 -0
  61. package/src/review-view.mjs +23 -0
  62. package/src/server.mjs +305 -0
  63. package/src/source-preview-view.mjs +14 -0
  64. package/src/spec-context-view.mjs +37 -0
  65. package/src/spec-context.mjs +147 -0
  66. package/src/spec-impact.mjs +145 -0
  67. package/src/specs.mjs +80 -0
  68. package/src/studio-documents.mjs +25 -0
  69. package/src/studio-plans.mjs +71 -0
  70. package/src/studio-view.mjs +108 -0
  71. package/src/views.mjs +117 -0
  72. package/src/workspace-state.mjs +48 -0
  73. package/templates/cli.mjs +38 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,8 @@
1
+ # Changelog
2
+
3
+ ## 0.1.1 — 2026-11-14
4
+
5
+ - Group requests by spec, prioritize unresolved work, and mark pending inbox items in the header.
6
+ - Refine agent and MCP connection panels, contextual commands, and planning document selection.
7
+ - Simplify review comments and file preview states; add GitHub contribution links and creator credit.
8
+ - 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/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,293 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ [![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-43853d?logo=node.js&logoColor=white)](https://nodejs.org/)
10
+ [![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) · [Planning and review](#planning-and-review) · [Features](#features) · [How it works](#how-it-works) · [Agent setup](#attach-your-agent)
14
+
15
+ </div>
16
+
17
+ ## Planning and review
18
+
19
+ Start with **New spec** to shape an idea with your agent. Ideas save automatically under **Drafts** in the left panel; return there to resume unfinished planning or delete a draft. Draft deletion can also remove its generated planning files after confirmation.
20
+
21
+ Select an existing change to read documents, inspect proposed code, and leave feedback. The planning workspace provides spec refinement, implementation preview, validation, and archive. New specs and existing changes use the same planning workspace, retained previews, and conversation. Applying reviewed files always requires explicit confirmation.
22
+
23
+ Open **Requests** in the header for an inbox grouped by spec. Questions, failures, and stalled work appear first, followed by running and queued work. The badge counts specs needing attention. A collapsed **Recent** section holds the latest five completed specs; cancelled and older work stays in **All history**, with status filters and pagination. **Dismiss** clears settled items from the inbox while preserving requests, previews, and comments. Cancel and supported retry actions remain available; destructive deletion is confined to history. Active work stays visible while you browse another spec. Partially edited planning work must be reviewed before continuing.
24
+
25
+ ![An unfinished spec in Drafts, with its planning document beside the retained conversation.](https://raw.githubusercontent.com/rahulnjs/spequi/master/docs/screenshots/build-light.png)
26
+
27
+ _New spec: shape the plan beside your agent conversation and resume it from Drafts._
28
+
29
+ ![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)
30
+
31
+ _Review: inspect a saved implementation and leave feedback. Screenshots use a local example project._
32
+
33
+ <details>
34
+ <summary>See planning and review in dark theme</summary>
35
+
36
+ ![The draft planning flow in dark theme.](https://raw.githubusercontent.com/rahulnjs/spequi/master/docs/screenshots/build-dark.png)
37
+
38
+ ![The same OpenSpec review workspace in dark mode.](https://raw.githubusercontent.com/rahulnjs/spequi/master/docs/screenshots/file-review-dark.png)
39
+
40
+ </details>
41
+
42
+ ## Features
43
+
44
+ | | What you can do |
45
+ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
46
+ | **Run the lifecycle** | Create and resume drafts, or open an existing change’s Build workspace to refine the spec, preview and apply code, then validate and archive. Answer agent questions in the app. |
47
+ | **Read the plan** | Browse Proposal, Design, Tasks, active changes, archived changes, and specifications. Switch between rendered Markdown and source. |
48
+ | **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. |
49
+ | **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. |
50
+ | **Understand impact** | Inspect direct and downstream dependencies, related tests, and export changes, with explicit static-analysis limitations. |
51
+ | **Leave precise feedback** | Add file notes or inline comments on code, Markdown passages, and source ranges. Keep the exact reviewed source context. |
52
+ | **Refine the specification** | Export an immutable Markdown review brief or queue a planning update for your agent to reconcile with OpenSpec. |
53
+ | **Stay in your workflow** | Use a local Node server and your current skill-capable agent. Switch between light and dark mode. |
54
+
55
+ ## Get started
56
+
57
+ Requires **Node.js 20+**, npm, and a target project containing OpenSpec files.
58
+
59
+ For agent-driven planning and implementation, 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.
60
+
61
+ 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.
62
+
63
+ ### Initialize with npx
64
+
65
+ ```sh
66
+ cd /path/to/your-project
67
+ npx spequi@latest init
68
+ ```
69
+
70
+ Then invoke the registered viewer skill in your agent, or start the server directly:
71
+
72
+ ```sh
73
+ node .spequi/server.mjs
74
+ ```
75
+
76
+ A global installation is also supported:
77
+
78
+ ```sh
79
+ npm install -g spequi
80
+ spequi init
81
+ spequi start
82
+ ```
83
+
84
+ Automatic browser opening is not implemented; open the printed URL or use your agent's browser capabilities.
85
+
86
+ ### Run from source
87
+
88
+ ```sh
89
+ git clone https://github.com/rahulnjs/spequi.git
90
+ cd spequi
91
+ npm ci
92
+
93
+ node bin/spequi.mjs init --root "/path/to/your-project"
94
+ node bin/spequi.mjs start --root "/path/to/your-project"
95
+ ```
96
+
97
+ Open the printed URL, normally **http://127.0.0.1:4310**. To choose another port, add `--port 4311` to the start command.
98
+
99
+ 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.
100
+
101
+ ## Attach your agent
102
+
103
+ GigaCode uses monitored Shell calls with `is_background: true` for the server and five-minute `agent wait` calls. Waiting does not claim a job; the agent claims it in the foreground after receiving the result. Background completion must resume the host session for unattended idle attachment to work. The skill includes a check and a foreground fallback. Closing the coding agent pauses consumption and leaves requests saved.
104
+
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
+ ## Planning 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 its draft planning workspace when the request completes. Partial plans offer the next schema-ready artifact; planning never automatically starts implementation.
167
+
168
+ The **Commands** picker in the planning workspace 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
+ Planning versions are retained 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
+ New specs and unfinished drafts keep **Shape spec**, **Implement**, and **Validate & archive** in their header, with the plan beside its retained conversation. Select an existing change in the left panel for document and code review; open **Build** to refine it or run the remaining lifecycle steps. The project panel keeps the same layout in both flows.
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 for the selected preview. Previous/next file controls, the selected file and diff tools stay above the independently scrolling code. Selecting a file keeps the same preview and planning workspace. 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; old lifecycle URLs redirect to the shared planning workspace.
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 300` 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 the shared Implement stage; generated source remains reviewable in 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
+ Spequi sends usage and failure events to `https://sber.eval.best/spequi/event`. These include a persistent identifier shared across projects on the same machine account, the project folder name, Git `user.name` when configured, timestamps, and event-specific identifiers, counts, and failure categories. Source files, prompts, and review comments are excluded. Delivery is best effort, with no retries. See [release notes](CHANGELOG.md).
236
+
237
+ - The server binds to `127.0.0.1`; mutations require local Host/Origin checks and a session token.
238
+ - `.spequi/` contains local configuration, requests, previews, feedback, and backups. Keep it out of Git.
239
+ - 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.
240
+ - A preview copy is not an OS security sandbox. The agent must honor its assigned working directory.
241
+ - Static impact evidence does not establish complete runtime behavior, dynamic references, aliases, or external-package effects. Scan limitations remain visible.
242
+ - 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.
243
+
244
+ ## Development and packaging
245
+
246
+ ```sh
247
+ npm ci
248
+ npm run check
249
+ npm pack --dry-run
250
+ npm publish --dry-run
251
+ ```
252
+
253
+ 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.
254
+
255
+ ## Naming and project data
256
+
257
+ 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.
258
+
259
+ 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`.
260
+
261
+ Spequi starts fresh in `.spequi/`. Initialization does not import, move, rename, or delete data from earlier tools.
262
+
263
+ ## Agent liveness and MCP reports
264
+
265
+ For the code-level attachment, skill routing, question and completion flow, see [How the agent workflow works](docs/agent-workflow.md).
266
+
267
+ 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.
268
+
269
+ The agent can write a credential-free report under `.spequi`, then run:
270
+
271
+ ```sh
272
+ node .spequi/cli.mjs agent report --file .spequi/session-report.json --name "Spequi Agent"
273
+ ```
274
+
275
+ For example, when the host provides authoritative connection status:
276
+
277
+ ```json
278
+ {
279
+ "sessionId": "a-stable-random-id-for-this-attachment",
280
+ "mcps": {
281
+ "supported": true,
282
+ "connections": [{ "name": "Filesystem", "status": "connected" }]
283
+ }
284
+ }
285
+ ```
286
+
287
+ 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.
288
+
289
+ 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.
290
+
291
+ ## License
292
+
293
+ [MIT](LICENSE)
package/bin/spequi.mjs ADDED
@@ -0,0 +1,80 @@
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, heartbeat, stopPolling, queueStatus } from '../src/jobs.mjs';
9
+ import { askJob, jobInput } from '../src/job-dialogue.mjs';
10
+ import { agentRequest } from '../src/agent-client.mjs';
11
+
12
+ const argv = process.argv.slice(2);
13
+ function option(name, fallback) { const position = argv.indexOf(`--${name}`); return position >= 0 ? argv[position + 1] : fallback; }
14
+ function print(value) { process.stdout.write(JSON.stringify(value, null, 2) + '\n'); }
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
+ }
27
+ try {
28
+ const [command, subcommand, id] = argv;
29
+ if (command === 'init') {
30
+ print(await initProject(root));
31
+ if (argv.includes('--start')) await startServer({ root, port: option('port') === undefined ? undefined : Number(option('port')) });
32
+ else process.stdout.write('\nReady. Run node .spequi/server.mjs, or invoke /spequi in your agent.\n');
33
+ } else if (command === 'start' || command === 'serve') await startServer({ root, port: option('port') === undefined ? undefined : Number(option('port')) });
34
+ else if (command === 'skill' && subcommand === 'install') print(await installSkill(root, argv.includes('--global')));
35
+ else if (command === 'agent') {
36
+ if (subcommand === 'report') {
37
+ const reportFile = option('file');
38
+ if (!reportFile || (await fs.stat(reportFile)).size > 32768) throw new Error('Use --file with a session report under 32 KiB');
39
+ const report = JSON.parse(await fs.readFile(reportFile, 'utf8'));
40
+ if (!report || Object.keys(report).some(key => !['sessionId', 'mcps'].includes(key))) throw new Error('Session reports accept sessionId and mcps only');
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');
78
+ } else if (command === '--version' || command === '-v') process.stdout.write(viewerVersion + '\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`);
80
+ } catch (error) { process.stderr.write(`spequi: ${error.message}\n`); process.exitCode = 1; }