spequi 0.1.0 → 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.
@@ -3,12 +3,23 @@ import { previewResult } from './previews.mjs';
3
3
  import { renderFileDiff } from './diff-view.mjs';
4
4
  import { listComments } from './review-store.mjs';
5
5
  import { previewPlanChanged } from './lifecycle.mjs';
6
+ import { trackDiffFailure } from './analytics.mjs';
6
7
 
7
8
  export async function getPreviewContext(root, params, jobs, selected) {
8
9
  const matching = jobs.filter(job => job.action === 'preview' && (!selected || jobMatchesChange(job, selected)));
9
10
  const previews = matching.filter(job => job.status === 'completed');
10
11
  const job = previews.find(job => job.id === params.job) || previews[0];
11
- const result = job ? await previewResult(root, job.id) : null;
12
+ const diffRequested = params.view === 'preview' || params.view === 'studio' && params.stage === 'implement';
13
+ let result = null;
14
+ try { result = job ? await previewResult(root, job.id) : null; }
15
+ catch (error) {
16
+ if (job && diffRequested) trackDiffFailure(root, job.id, 'unreadable_result');
17
+ throw error;
18
+ }
19
+ if (job && diffRequested) {
20
+ const reason = !result ? 'missing_result' : !Array.isArray(result.changes) ? 'invalid_result' : !result.changes.length && result.unsupported?.length ? 'unsupported_files' : !result.changes.length && !changeState(selected).complete ? 'empty_result' : null;
21
+ if (reason) trackDiffFailure(root, job.id, reason);
22
+ }
12
23
  return {
13
24
  previews, job, result, comments: job && result ? await listComments(root, job.id) : [],
14
25
  file: result?.changes.find(change => change.file === params.file) || result?.changes[0],
@@ -62,13 +73,15 @@ export async function renderPreview({ root, params, selected, agent, context, co
62
73
  if (!job) {
63
74
  if (!pending && changeState(selected).complete) return completedEmpty(selected, { icon, link, empty }, false, failure) + '<div id="preview-feedback" role="status" aria-live="polite"></div>';
64
75
  const title = pending?.status === 'awaiting-input' ? 'Your agent needs your input.' : pending ? pending.origin ? 'Preparing proposed file changes.' : pending.status === 'running' ? 'Your agent is generating the file diff.' : 'File diff queued.' : 'No implementation diff yet.';
65
- const description = pending?.status === 'awaiting-input' ? 'Open Build to answer the current question and resume this preview.' : pending ? pending.origin ? 'The proposed edits are being staged in a separate project copy. Your project stays unchanged.' : pending.status === 'running' ? 'The agent is implementing this change in a separate project copy. The before-and-after file diff will appear here when it finishes.' : 'This request is waiting for an agent running the viewer skill. Attach your agent to continue.' : 'Open Build to analyze affected files, import a patch, generate with a model, or request an implementation from your attached agent.';
66
- const progress = pending ? `<div class="diff-generation-status"><span class="badge ${pending.status === 'running' ? 'blue' : ''}">${e(pending.status)}</span>${pending.logs.slice(-3).map(log => `<p>${e(log.message)}</p>`).join('')}</div>` : '';
67
- const attach = !agent.connected && selected && !selected.archived ? '<p class="diff-attach-hint">Attach your existing agent with <code>$spequi</code> in Codex or <code>/spequi</code> in Claude Code.</p>' : '';
76
+ const description = pending?.status === 'awaiting-input' ? 'Answer the question in Build to continue this preview.' : pending ? pending.origin ? 'Proposed changes are being prepared in a separate project copy.' : pending.status === 'running' ? 'The file comparison will appear here when the preview is ready.' : 'Your agent will pick up this request when available.' : selected?.archived ? 'No file preview was saved for this archived change.' : 'Generate an implementation preview, then review its proposed file changes here.';
77
+ const progress = pending ? `<div class="diff-generation-status" role="status"><span class="badge ${pending.status === 'running' ? 'blue' : ''}">${e({ queued: 'Queued', running: 'Working', 'awaiting-input': 'Answer needed' }[pending.status] || pending.status)}</span>${pending.logs.slice(-1).map(log => `<p>${e(log.message)}</p>`).join('')}</div>` : '';
78
+ const attach = !pending && !agent.connected && selected && !selected.archived ? '<p class="diff-agent-note">No agent connected. Preview requests will wait in the queue.</p>' : '';
68
79
  const error = failure ? `<p class="error-message">Previous attempt failed: ${e(failure.result || 'Retry with your agent attached.')}</p>` : '';
69
- return `<div class="diff-empty-state">${empty(title, description, 'git', `${selected ? link('Open Build', { change: selected.id, view: 'studio' }, 'button') : ''}${generateForm(selected, pending, icon)}<div id="preview-feedback" role="status" aria-live="polite"></div>${attach}${progress}${error}`)}</div>`;
80
+ const build = selected ? link(pending?.status === 'awaiting-input' ? 'Reply in Build' : pending ? 'View progress in Build' : 'Open Build', { change: selected.id, view: 'studio', stage: 'implement', ...(pending ? { pane: 'conversation' } : {}) }, `button ${pending || selected.archived ? 'primary' : ''}`) : '';
81
+ const actions = `<div class="diff-empty-actions">${pending ? '' : generateForm(selected, null, icon)}${build}</div>`;
82
+ return `<div class="diff-empty-state">${empty(title, description, 'git', `${actions}${attach}${progress}${error}<div id="preview-feedback" role="status" aria-live="polite"></div>`)}</div>`;
70
83
  }
71
- if (!result) return empty('Preview files unavailable', 'The retained result may have been removed. Generate a fresh preview.');
84
+ if (!result) return `<div class="diff-empty-state">${empty('Preview files unavailable', 'Open Build to generate a fresh implementation preview.', 'git', `<div class="diff-empty-actions">${selected ? link('Open Build', { change: selected.id, view: 'studio', stage: 'implement' }, 'button primary') : ''}</div>`)}</div>`;
72
85
  const fileDiff = file ? await renderFileDiff({ root, job, file, result, selected, params, compact, comments: context.comments }, { icon, link, badge }) : '';
73
86
  const additions = result.changes.reduce((total, change) => total + change.additions, 0);
74
87
  const deletions = result.changes.reduce((total, change) => total + change.deletions, 0);
@@ -77,7 +90,7 @@ export async function renderPreview({ root, params, selected, agent, context, co
77
90
  const stale = selected ? await previewPlanChanged(root, selected, job, result) : false;
78
91
  const blocked = selected?.archived || stale || context.workflowPending;
79
92
  const reason = selected?.archived ? 'This change is archived.' : stale ? 'The spec changed. Return to Build to generate a fresh code preview.' : context.workflowPending ? 'Wait for the current request to finish before applying.' : '';
80
- const provenance = `<div class="source-preview-status guided-file-actions"><span><strong>${job.origin === 'model' ? `Model proposal · ${e(job.model)}` : job.origin ? 'Imported patch' : result.applied ? 'Code changes applied' : 'Review your code changes'}</strong><small>${e(job.validation?.message || `${result.changes.length} changed files · ${result.applied ? 'Saved in your project' : 'Your project has not changed'}`)}</small></span><div class="preview-followup">${link(result.applied ? 'Continue' : 'Update spec', { change: selected?.id, view: 'studio', stage: result.applied ? 'finish' : 'shape' }, 'button')}${job.origin ? `<a class="button" href="/api/previews/${job.id}/patch" download="${e(job.change)}.patch">${icon('download')}Export patch</a>` : ''}${applyForm(job, result, icon, blocked)}</div>${reason ? `<p class="lc-blocker">${e(reason)}</p>` : ''}</div>`;
93
+ const provenance = `<div class="source-preview-status guided-file-actions"><span><strong>${job.origin === 'model' ? `Model proposal · ${e(job.model)}` : job.origin ? 'Imported patch' : result.applied ? 'Code changes applied' : 'Review your code changes'}</strong><small>${e(job.validation?.message || `${result.changes.length} changed files · ${result.applied ? 'Saved in your project' : 'Your project has not changed'}`)}</small></span><div class="preview-followup">${link(result.applied ? 'Continue' : 'Update spec', { change: selected?.id, view: 'studio', stage: result.applied ? 'finish' : 'shape' }, 'button')}${job.origin ? `<a class="button" href="/api/previews/${job.id}/patch" download="${e(job.change)}.patch">${icon('download')}Export patch</a>` : ''}${applyForm(job, result, icon, blocked)}</div>${reason ? `<p class="preview-blocker">${e(reason)}</p>` : ''}</div>`;
81
94
  if (compact) return `${provenance}<div class="compact-review-feedback"><div id="preview-feedback" role="status" aria-live="polite"></div><div id="apply-feedback" role="status"></div>${pending ? '<p class="muted diff-pending-note">A new diff is being generated. This completed preview stays available while you wait.</p>' : ''}${result.unsupported.length ? `<p class="error-message">Unsupported binary or oversized changes: ${e(result.unsupported.join(', '))}. Apply is disabled.</p>` : ''}</div><section class="diff-panel">${fileDiff || noChanges}</section>`;
82
95
  return `<div class="review-intro file-review-intro"><div class="file-review-title"><h2>File review ${badge(result.applied ? 'Applied' : 'Ready for review', 'success')}</h2>${versions}</div><div class="preview-actions"><span><strong>${result.changes.length}</strong> changed files <span class="diff-add">+${additions}</span> <span class="diff-remove">−${deletions}</span></span><a class="button" href="/api/previews/${job.id}/patch" download="${e(job.change || 'preview')}.patch">${icon('download')} Export patch</a>${generateForm(selected, pending, icon, 'Regenerate diff')}${applyForm(job, result, icon, selected?.archived)}</div><div id="preview-feedback" role="status" aria-live="polite"></div><div id="apply-feedback" role="status"></div>${pending ? '<p class="muted diff-pending-note">A new diff is being generated. This completed preview stays available while you wait.</p>' : ''}${result.unsupported.length ? `<p class="error-message">Unsupported binary or oversized changes: ${e(result.unsupported.join(', '))}. Apply is disabled.</p>` : ''}</div><section class="diff-panel">${fileDiff || noChanges}</section>`;
83
96
  }
package/src/previews.mjs CHANGED
@@ -5,6 +5,7 @@ import { createTwoFilesPatch } from 'diff';
5
5
  import { compareLines, lineEndingStyle } from './diffs.mjs';
6
6
  import { captureSpecLinks } from './spec-context.mjs';
7
7
  import { walk, within, runtime, safeID, exists, writeJSON, readJSON, withLock } from './files.mjs';
8
+ import { trackDiffFailure } from './analytics.mjs';
8
9
 
9
10
  const ignoredDirs = new Set(['.git', '.spequi', '.openspec-ui', '.change-viewer', 'node_modules', 'dist', 'build', '.next', '.nuxt', '.cache', '.turbo', 'coverage', '.venv', 'venv', '__pycache__', '.impeccable']);
10
11
  export function eligible(relative) {
@@ -58,9 +59,12 @@ export async function freezePreview(root, id) {
58
59
  export async function previewResult(root, id) { return readJSON(path.join(basePath(root, id), 'result.json')); }
59
60
  export async function previewContents(root, id, file) {
60
61
  const result = await previewResult(root, id);
61
- if (!result?.changes.some(change => change.file === file)) throw new Error('File is not part of this preview');
62
+ const change = result?.changes.find(change => change.file === file);
63
+ if (!change) throw new Error('File is not part of this preview');
62
64
  const dir = basePath(root, id);
63
- return { before: (await getBuffer(path.join(dir, 'baseline'), file))?.toString('utf8') || '', after: (await getBuffer(path.join(dir, 'proposed'), file))?.toString('utf8') || '' };
65
+ const before = await getBuffer(path.join(dir, 'baseline'), file), after = await getBuffer(path.join(dir, 'proposed'), file);
66
+ if (change.beforeHash && before === null || change.afterHash && after === null) trackDiffFailure(root, id, 'missing_snapshot');
67
+ return { before: before?.toString('utf8') || '', after: after?.toString('utf8') || '' };
64
68
  }
65
69
  export async function applyPreview(root, id) {
66
70
  return withLock(runtime(root, 'apply.lock'), async () => {
package/src/project.mjs CHANGED
@@ -3,6 +3,7 @@ import path from 'node:path';
3
3
  import os from 'node:os';
4
4
  import { fileURLToPath } from 'node:url';
5
5
  import { runtime, writeJSON, readJSON } from './files.mjs';
6
+ import { initializeAnalytics } from './analytics.mjs';
6
7
 
7
8
  const skillFile = fileURLToPath(new URL('../skills/spequi/SKILL.md', import.meta.url));
8
9
  const metadata = JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url), 'utf8'));
@@ -55,5 +56,6 @@ export async function initProject(root) {
55
56
  await writeGenerated(entry, `${generated} Start this project's pinned viewer runtime.\nprocess.argv.splice(2, 0, 'start');\nawait import('./cli.mjs');\n`);
56
57
  await updateGitignore(root);
57
58
  const skill = await installSkill(root);
59
+ await initializeAnalytics(root);
58
60
  return { root, workspace: runtime(root), ...skill };
59
61
  }
@@ -0,0 +1,80 @@
1
+ import fs from 'node:fs/promises';
2
+ import { runtime, safeID, withLock, readJSON, writeJSON } from './files.mjs';
3
+ import { listJobs, getJob, writeJob, enqueue, pendingStatuses } from './jobs.mjs';
4
+ import { retainDraftOrigin } from './drafts.mjs';
5
+
6
+ const groupKey = job => job.change ? `change:${job.change.replace(/^\d{4}-\d{2}-\d{2}-/, '')}` : `request:${job.id}`;
7
+ const updated = job => job.updatedAt || job.createdAt || '';
8
+ const newest = (a, b) => updated(b).localeCompare(updated(a)) || b.id.localeCompare(a.id);
9
+ export async function inboxState(root) { return (await readJSON(runtime(root, 'request-inbox.json')))?.dismissed || {}; }
10
+
11
+ export function requestPage(jobs, { status = 'inbox', page = 1 } = {}, { agent, dismissed = {} } = {}) {
12
+ if (status === 'inbox') {
13
+ const groups = new Map();
14
+ for (const job of jobs.filter(job => !job.hiddenAt)) {
15
+ const key = groupKey(job);
16
+ if (!groups.has(key)) groups.set(key, []);
17
+ groups.get(key).push(job);
18
+ }
19
+ const items = [], recent = [];
20
+ for (const [key, history] of groups) {
21
+ const retries = new Set(history.map(item => item.requestKey).filter(Boolean));
22
+ const eligible = history.filter(job => (pendingStatuses.includes(job.status) || updated(job) > (dismissed[key] || '')) && !(job.status === 'failed' && retries.has(`retry-${job.id}`)));
23
+ const stalled = job => job.status === 'running' && !job.origin && agent?.queue?.active?.id === job.id && !agent.queue.active.ownerConnected;
24
+ const priority = job => job.status === 'awaiting-input' ? 0 : stalled(job) ? 1 : job.status === 'failed' ? 2 : job.status === 'running' ? 3 : 4;
25
+ const ongoing = eligible.filter(job => pendingStatuses.includes(job.status) || job.status === 'failed').sort((a, b) => priority(a) - priority(b) || newest(a, b));
26
+ const completed = eligible.filter(job => job.status === 'completed').sort(newest);
27
+ const job = ongoing[0] || completed[0];
28
+ if (!job) continue;
29
+ const entry = { ...job, groupKey: key, groupCount: history.length, dismissThrough: history.reduce((latest, item) => updated(item) > latest ? updated(item) : latest, ''), stalled: Boolean(stalled(job)), needsAttention: ongoing.some(item => priority(item) <= 2) };
30
+ if (ongoing.length) items.push(entry); else recent.push(entry);
31
+ }
32
+ items.sort((a, b) => (a.status === 'awaiting-input' ? 0 : a.needsAttention ? 1 : a.status === 'running' ? 2 : 3) - (b.status === 'awaiting-input' ? 0 : b.needsAttention ? 1 : b.status === 'running' ? 2 : 3) || newest(a, b));
33
+ recent.sort(newest);
34
+ page = Math.min(Math.max(1, Math.ceil(items.length / 20)), Math.max(1, Math.floor(Number(page)) || 1));
35
+ return { items: items.slice((page - 1) * 20, page * 20), recent: page === 1 ? recent.slice(0, 5) : [], total: items.length, attention: items.filter(item => item.needsAttention).length, historyTotal: jobs.filter(job => !job.hiddenAt).length, page, pages: Math.max(1, Math.ceil(items.length / 20)) };
36
+ }
37
+ const visible = jobs.filter(job => !job.hiddenAt && (status === 'all' || (status === 'active' ? pendingStatuses.includes(job.status) : job.status === status)));
38
+ page = Math.min(Math.max(1, Math.ceil(visible.length / 20)), Math.max(1, Math.floor(Number(page)) || 1));
39
+ return { items: visible.slice((page - 1) * 20, page * 20), total: visible.length, page, pages: Math.max(1, Math.ceil(visible.length / 20)), active: jobs.filter(job => pendingStatuses.includes(job.status)).length };
40
+ }
41
+ export async function dismissRequest(root, id, { through } = {}) {
42
+ safeID(id);
43
+ return withLock(runtime(root, 'request-inbox.lock'), async () => {
44
+ const job = await getJob(root, id);
45
+ if (!['completed', 'failed', 'cancelled'].includes(job.status) || job.hiddenAt) throw new Error('Only a settled request can be dismissed. Finish or cancel active work first.');
46
+ const key = groupKey(job), history = (await listJobs(root)).filter(item => !item.hiddenAt && groupKey(item) === key);
47
+ through ||= updated(job);
48
+ if (typeof through !== 'string' || !Number.isFinite(Date.parse(through)) || !history.some(item => updated(item) === through)) throw new Error('The inbox changed. Refresh it before dismissing this entry.');
49
+ const dismissed = await inboxState(root);
50
+ dismissed[key] = [dismissed[key] || '', through].sort().at(-1);
51
+ await writeJSON(runtime(root, 'request-inbox.json'), { version: 1, dismissed });
52
+ return { dismissed: true };
53
+ });
54
+ }
55
+ export async function deleteRequest(root, id, { reviewData = true } = {}) {
56
+ safeID(id);
57
+ if (typeof reviewData !== 'boolean') throw new Error('Choose whether to delete the associated review data');
58
+ return withLock(runtime(root, 'review-requests.lock'), () => withLock(runtime(root, `job-${id}.lock`), async () => {
59
+ const job = await getJob(root, id);
60
+ if (pendingStatuses.includes(job.status)) throw new Error('Finish or cancel this request before deleting it.');
61
+ if (reviewData) {
62
+ const dependent = (await listJobs(root)).find(item => item.id !== id && !item.hiddenAt && item.reviewPreview === id);
63
+ if (dependent) throw new Error('Another retained request uses this preview. Remove that request first, or keep the review data.');
64
+ // Applying has its own lock. Never remove a snapshot while it is being applied.
65
+ await withLock(runtime(root, 'apply.lock'), async () => {
66
+ await retainDraftOrigin(root, job);
67
+ for (const folder of ['previews', 'reviews', 'analyses']) await fs.rm(runtime(root, folder, id), { recursive: true, force: true });
68
+ await fs.rm(runtime(root, 'impact', `${id}.md`), { force: true });
69
+ await fs.rm(runtime(root, 'jobs', `${id}.json`), { force: true });
70
+ });
71
+ } else await writeJob(root, { ...job, hiddenAt: new Date().toISOString() });
72
+ return { deleted: true };
73
+ }));
74
+ }
75
+ export async function retryRequest(root, id) {
76
+ const job = await getJob(root, id);
77
+ if (!['failed', 'cancelled'].includes(job.status)) throw new Error('Only failed or cancelled requests can be retried');
78
+ if (!['explore', 'preview', 'verify', 'impact'].includes(job.action)) throw new Error('Open the change and review its partial planning work before continuing.');
79
+ return enqueue(root, { action: job.action, change: job.change, message: job.message, reviewPreview: job.reviewPreview, reviewFile: job.reviewFile, requestKey: `retry-${job.id}` });
80
+ }
package/src/server.mjs CHANGED
@@ -6,9 +6,10 @@ import { randomBytes, timingSafeEqual } from 'node:crypto';
6
6
  import { createRequire } from 'node:module';
7
7
  import { WebSocketServer, WebSocket } from 'ws';
8
8
  import chokidar from 'chokidar';
9
- import { exists, readJSON, runtime, isPreviewSnapshotPath } from './files.mjs';
10
- import { inventory, readArtifact, escape } from './specs.mjs';
11
- import { listJobs, enqueue, updateJob, agentStatus, getJob, pendingStatuses } from './jobs.mjs';
9
+ import { setTimeout as delay } from 'node:timers/promises';
10
+ import { exists, readJSON, writeJSON, runtime, isPreviewSnapshotPath, acquireLock, cleanupTemporaryFiles } from './files.mjs';
11
+ import { inventory, readArtifact, escape, jobMatchesChange } from './specs.mjs';
12
+ import { listJobs, enqueue, updateJob, agentStatus, getJob, pendingStatuses, createJobReader, claimNext, heartbeat, stopPolling, queueStatus } from './jobs.mjs';
12
13
  import { applyPreview, previewResult } from './previews.mjs';
13
14
  import { workspace, shell } from './views.mjs';
14
15
  import { addComment, deleteComment, exportFeedback, feedbackExport } from './review-store.mjs';
@@ -16,7 +17,14 @@ import { analyzeChange } from './spec-impact.mjs';
16
17
  import { directPreview } from './direct-preview.mjs';
17
18
  import { requestLifecycle, previewPlanChanged } from './lifecycle.mjs';
18
19
  import { requestCommand } from './commands.mjs';
19
- import { answerJob } from './job-dialogue.mjs';
20
+ import { answerJob, askJob, jobInput } from './job-dialogue.mjs';
21
+ import { reportSession } from './agent-session.mjs';
22
+ import { createWorkspaceState } from './workspace-state.mjs';
23
+ import { listDrafts, saveDraft, deleteDraft, resumeDraft, finishDrafts } from './drafts.mjs';
24
+ import { requestPage, deleteRequest, retryRequest, dismissRequest, inboxState } from './requests.mjs';
25
+ import { viewerVersion } from './project.mjs';
26
+ import { conversation } from './studio-view.mjs';
27
+ import { initializeAnalytics, trackEvent } from './analytics.mjs';
20
28
 
21
29
  const require = createRequire(import.meta.url);
22
30
  const publicDir = fileURLToPath(new URL('../public/', import.meta.url));
@@ -27,13 +35,24 @@ async function body(request, limit = 100000) {
27
35
  const text = Buffer.concat(chunks).toString('utf8');
28
36
  return request.headers['content-type']?.includes('application/json') ? JSON.parse(text) : Object.fromEntries(new URLSearchParams(text));
29
37
  }
30
- export async function startServer({ root = process.cwd(), port, quiet = false } = {}) {
38
+ export async function startServer({ root = process.cwd(), port, quiet = false, readinessCheck } = {}) {
31
39
  root = await fs.realpath(root);
32
40
  if (!await exists(runtime(root, 'config.json'))) throw new Error('Run spequi init in this project first');
33
41
  const config = await readJSON(runtime(root, 'config.json'));
42
+ await initializeAnalytics(root);
34
43
  const selectedPort = port ?? config.port ?? 4310;
35
44
  if (!Number.isInteger(selectedPort) || selectedPort < 0 || selectedPort > 65535) throw new Error('Port must be an integer from 0 to 65535');
36
- const csrf = randomBytes(32).toString('hex');
45
+ const releaseServer = await acquireLock(runtime(root, 'server.lock'), { waitMs: 0 });
46
+ try { await cleanupTemporaryFiles(root); } catch (error) { await releaseServer(); throw error; }
47
+ const csrf = randomBytes(32).toString('hex'), agentToken = randomBytes(32).toString('hex');
48
+ const jobReader = createJobReader(root);
49
+ let broadcast = () => {}, closed = false;
50
+ const state = createWorkspaceState(root, { check: readinessCheck, changed: (change, readiness) => {
51
+ broadcast('readiness', { change });
52
+ if (readiness?.planningComplete) void jobReader.read().then(jobs => {
53
+ if (!jobs.some(job => job.change === change && pendingStatuses.includes(job.status))) return finishDrafts(root, change);
54
+ }).catch(error => { if (!quiet) process.stderr.write(`Draft readiness: ${error.message}\n`); });
55
+ } });
37
56
  let origin;
38
57
  const send = (response, status, content, type = 'text/html; charset=utf-8', headers = {}) => {
39
58
  response.writeHead(status, { 'Content-Type': type, 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'same-origin', ...headers }); response.end(content);
@@ -43,8 +62,53 @@ export async function startServer({ root = process.cwd(), port, quiet = false }
43
62
  const allowedHosts = [new URL(origin).host, `localhost:${server.address().port}`];
44
63
  if (!allowedHosts.includes(request.headers.host)) return send(response, 403, 'Invalid local host');
45
64
  const url = new URL(request.url, origin);
65
+ if (request.method === 'POST' && url.pathname.startsWith('/api/agent/')) {
66
+ if (request.headers.origin || !tokenMatches(request.headers.authorization, `Bearer ${agentToken}`)) return send(response, 403, JSON.stringify({ error: 'Project agent authentication failed' }), 'application/json');
67
+ const payload = await body(request), operation = url.pathname.slice('/api/agent/'.length);
68
+ const name = payload.name || 'Spequi Agent', sessionId = payload.sessionId;
69
+ if (typeof name !== 'string' || !name.trim() || name.length > 100) throw new Error('Invalid agent display name');
70
+ let result;
71
+ if (['next', 'wait'].includes(operation)) {
72
+ const seconds = Number(payload.wait ?? (operation === 'wait' ? 300 : 0));
73
+ if (!Number.isFinite(seconds) || seconds < 0 || seconds > 300) throw new Error('Wait must be between 0 and 300 seconds');
74
+ const deadline = Date.now() + seconds * 1000;
75
+ const pollId = randomBytes(16).toString('hex');
76
+ try {
77
+ do {
78
+ await heartbeat(root, name, sessionId, { polling: true, pollId });
79
+ const jobs = await jobReader.read(), queue = await queueStatus(root, jobs);
80
+ if (operation === 'wait' && queue.queued && !queue.active) { result = { available: true, queue }; break; }
81
+ if (operation === 'next' && queue.queued && !queue.active) {
82
+ const job = await claimNext(root, name, sessionId);
83
+ if (job) { result = { job }; break; }
84
+ }
85
+ if (queue.status === 'blocked') throw Object.assign(new Error(queue.message), { code: 'QUEUE_BLOCKED' });
86
+ if (Date.now() >= deadline || closed || response.destroyed) { result = operation === 'wait' ? { available: false, queue } : { job: null, queue }; break; }
87
+ await delay(250);
88
+ } while (true);
89
+ } finally { await stopPolling(root, name, sessionId, pollId); }
90
+ } else if (operation === 'report') result = await reportSession(root, { ...payload.report, agent: name });
91
+ else if (operation === 'ask') result = await askJob(root, payload.id, payload.token, payload);
92
+ else if (operation === 'input') {
93
+ const seconds = Number(payload.wait || 0);
94
+ if (!Number.isFinite(seconds) || seconds < 0 || seconds > 300) throw new Error('Wait must be between 0 and 300 seconds');
95
+ const deadline = Date.now() + seconds * 1000;
96
+ do { result = await jobInput(root, payload.id, payload.token); if (result.status !== 'awaiting-input' || Date.now() >= deadline || closed || response.destroyed) break; await delay(250); } while (true);
97
+ } else if (['log', 'finish', 'fail'].includes(operation)) {
98
+ result = await updateJob(root, payload.id, payload.token, operation, payload.message);
99
+ if (operation !== 'log') state.invalidate(result.change);
100
+ }
101
+ else if (operation === 'list') result = (await jobReader.read()).map(({ claimToken, instructions, ...job }) => job);
102
+ else throw new Error('Unknown agent operation');
103
+ if (!response.destroyed) return send(response, 200, JSON.stringify({ ...(['list'].includes(operation) ? { jobs: result } : result), root, protocol: 1 }), 'application/json');
104
+ return;
105
+ }
46
106
  if (request.method === 'GET') {
47
- if (['/assets/fonts.css', '/assets/app.css', '/assets/diff.css', '/assets/app.js', '/assets/review.css', '/assets/review.js', '/assets/lifecycle.css', '/assets/lifecycle.js', '/assets/studio.css', '/assets/studio.js', '/assets/session.js'].includes(url.pathname)) {
107
+ if (url.pathname === '/' && url.searchParams.get('view') === 'lifecycle') {
108
+ url.searchParams.set('view', 'studio');
109
+ return send(response, 302, '', undefined, { Location: url.pathname + url.search });
110
+ }
111
+ if (['/assets/fonts.css', '/assets/app.css', '/assets/diff.css', '/assets/app.js', '/assets/review.css', '/assets/review.js', '/assets/workflow.js', '/assets/studio.css', '/assets/studio.js', '/assets/session.js', '/assets/requests.js'].includes(url.pathname)) {
48
112
  const file = path.join(publicDir, path.basename(url.pathname));
49
113
  return send(response, 200, await fs.readFile(file), url.pathname.endsWith('.css') ? 'text/css' : 'text/javascript');
50
114
  }
@@ -57,10 +121,26 @@ export async function startServer({ root = process.cwd(), port, quiet = false }
57
121
  if (url.pathname === '/favicon.svg') return send(response, 200, '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="8" fill="#3f62b5"/><path d="m6 11 10-6 10 6-10 6-10-6Zm0 6 10 6 10-6m-20 6 10 6 10-6" fill="none" stroke="#f3f5fb" stroke-width="2"/></svg>', 'image/svg+xml');
58
122
  if (url.pathname === '/api/raw') return send(response, 200, await readArtifact(root, url.searchParams.get('file') || ''), 'text/plain; charset=utf-8');
59
123
  if (url.pathname === '/api/state') {
60
- const data = await inventory(root);
61
- return send(response, 200, JSON.stringify({ data, jobs: (await listJobs(root)).map(({ claimToken, instructions, ...job }) => job), agent: await agentStatus(root) }), 'application/json');
124
+ const [data, jobs] = await Promise.all([state.data(), jobReader.read()]);
125
+ return send(response, 200, JSON.stringify({ data, jobs: jobs.map(({ claimToken, instructions, ...job }) => job), agent: await agentStatus(root, { jobs }) }), 'application/json');
126
+ }
127
+ if (url.pathname === '/api/agent-status') return send(response, 200, JSON.stringify(await agentStatus(root, { jobs: await jobReader.read() })), 'application/json');
128
+ if (url.pathname === '/api/requests') {
129
+ const jobs = await jobReader.read(), agent = await agentStatus(root, { jobs });
130
+ const result = requestPage(jobs, Object.fromEntries(url.searchParams), { agent, dismissed: await inboxState(root) });
131
+ const expose = ({ claimToken, instructions, workflow, workingDirectory, ...job }) => job;
132
+ return send(response, 200, JSON.stringify({ ...result, items: result.items.map(expose), recent: result.recent?.map(expose) }), 'application/json');
133
+ }
134
+ if (url.pathname === '/api/activity') {
135
+ const [jobs, drafts] = await Promise.all([jobReader.read(), listDrafts(root)]);
136
+ const change = url.searchParams.get('change');
137
+ const validChange = typeof change === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,160}$/.test(change);
138
+ const agent = await agentStatus(root, { jobs }), selected = validChange ? { id: change, archived: /^\d{4}-\d{2}-\d{2}-/.test(change) && !await exists(path.join(root, 'openspec', 'changes', change)) } : null;
139
+ const relevant = jobs.filter(job => !job.hiddenAt && (selected && jobMatchesChange(job, selected) || job.id === url.searchParams.get('creation')));
140
+ const draftStates = await Promise.all(drafts.map(async draft => ({ id: draft.id, change: draft.change, creationId: draft.creationId, status: jobs.find(job => job.id === draft.creationId)?.status, hasPlan: Boolean(draft.creationId && /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(draft.change) && await exists(path.join(root, 'openspec', 'changes', draft.change))) })));
141
+ const inbox = requestPage(jobs, {}, { agent, dismissed: await inboxState(root) });
142
+ return send(response, 200, JSON.stringify({ agent, attention: inbox.attention, inboxCount: inbox.total, revision: JSON.stringify(relevant.map(job => [job.id, job.status])), thread: conversation(relevant, agent), drafts: draftStates, active: jobs.filter(job => pendingStatuses.includes(job.status)).map(job => ({ id: job.id, change: job.change, status: job.status })) }), 'application/json');
62
143
  }
63
- if (url.pathname === '/api/agent-status') return send(response, 200, JSON.stringify(await agentStatus(root)), 'application/json');
64
144
  const feedbackMatch = url.pathname.match(/^\/api\/reviews\/([a-zA-Z0-9_-]+)\/feedback\/([a-zA-Z0-9_-]+)$/);
65
145
  if (feedbackMatch) {
66
146
  const exported = await feedbackExport(root, feedbackMatch[1], feedbackMatch[2]);
@@ -73,8 +153,9 @@ export async function startServer({ root = process.cwd(), port, quiet = false }
73
153
  return send(response, 200, result.changes.map(change => change.patch).join('\n'), 'text/plain; charset=utf-8', { 'Content-Disposition': 'attachment; filename="preview.patch"' });
74
154
  }
75
155
  if (url.pathname !== '/') return send(response, 404, 'Page not found');
76
- const [data, jobs, agent] = await Promise.all([inventory(root), listJobs(root), agentStatus(root)]);
77
- const content = await workspace({ root, data, params: Object.fromEntries(url.searchParams), jobs, agent });
156
+ const [data, jobs, drafts] = await Promise.all([state.data(), jobReader.read(), listDrafts(root)]);
157
+ const agent = await agentStatus(root, { jobs });
158
+ const content = await workspace({ root, data, params: Object.fromEntries(url.searchParams), jobs, drafts, agent, getReadiness: (_root, change) => state.readiness(change) });
78
159
  return send(response, 200, request.headers['hx-request'] ? content : shell(content, data, csrf, Object.fromEntries(url.searchParams)), 'text/html; charset=utf-8', {
79
160
  'Content-Security-Policy': "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; font-src 'self'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'"
80
161
  });
@@ -82,8 +163,31 @@ export async function startServer({ root = process.cwd(), port, quiet = false }
82
163
  if (request.method !== 'POST') return send(response, 405, 'Method not allowed');
83
164
  if (![origin, `http://localhost:${server.address().port}`].includes(request.headers.origin) || !tokenMatches(request.headers['x-csrf-token'], csrf)) return send(response, 403, '<p class="error-message">Local session verification failed. Reload the viewer and retry.</p>');
84
165
  const payload = await body(request, url.pathname.startsWith('/api/source-preview/') ? 2 * 1024 * 1024 : 100000);
166
+ if (url.pathname === '/api/analytics') {
167
+ if (payload.event === 'project_used') trackEvent(root, 'project_used');
168
+ else if (payload.event === 'file_diff_viewed' && /^[a-zA-Z0-9_-]{1,100}$/.test(payload.preview_id || '') && Number.isInteger(payload.changed_file_count) && payload.changed_file_count > 0 && ['unified', 'split'].includes(payload.layout)) {
169
+ trackEvent(root, 'file_diff_viewed', { preview_id: payload.preview_id, changed_file_count: payload.changed_file_count, layout: payload.layout });
170
+ } else return send(response, 400, '', 'application/json');
171
+ return send(response, 204, '');
172
+ }
173
+ if (url.pathname === '/api/drafts') return send(response, 200, JSON.stringify({ draft: await saveDraft(root, payload) }), 'application/json');
174
+ const draftResume = url.pathname.match(/^\/api\/drafts\/([a-zA-Z0-9_-]+)\/resume$/);
175
+ if (draftResume) return send(response, 200, JSON.stringify(await resumeDraft(root, draftResume[1])), 'application/json');
176
+ const draftDelete = url.pathname.match(/^\/api\/drafts\/([a-zA-Z0-9_-]+)\/delete$/);
177
+ if (draftDelete) {
178
+ const result = await deleteDraft(root, draftDelete[1], payload); state.invalidate();
179
+ return send(response, 200, JSON.stringify(result), 'application/json');
180
+ }
181
+ const requestAction = url.pathname.match(/^\/api\/jobs\/([a-zA-Z0-9_-]+)\/(delete|retry|dismiss)$/);
182
+ if (requestAction) {
183
+ const result = requestAction[2] === 'dismiss' ? await dismissRequest(root, requestAction[1], payload) : requestAction[2] === 'delete' ? await deleteRequest(root, requestAction[1], payload) : { job: await retryRequest(root, requestAction[1]) };
184
+ jobReader.invalidate(requestAction[1]);
185
+ broadcast('requests');
186
+ return send(response, 200, JSON.stringify(result), 'application/json');
187
+ }
85
188
  if (['/api/lifecycle/actions', '/api/lifecycle/command'].includes(url.pathname)) {
86
189
  const { job, ...result } = await (url.pathname.endsWith('/command') ? requestCommand(root,payload) : requestLifecycle(root, payload));
190
+ if (result.refreshed) state.invalidate(payload.change);
87
191
  return send(response, job ? 201 : 200, JSON.stringify({ ...result, ...(job ? { job: { id: job.id, action: job.action, change: job.change, status: job.status } } : {}) }), 'application/json', { 'HX-Trigger': 'workspace-updated' });
88
192
  }
89
193
  const replyMatch = url.pathname.match(/^\/api\/lifecycle\/jobs\/([a-zA-Z0-9_-]+)\/reply$/);
@@ -108,12 +212,13 @@ export async function startServer({ root = process.cwd(), port, quiet = false }
108
212
  }
109
213
  if (action === 'impact') {
110
214
  await enqueue(root, { action: 'impact', reviewPreview: preview, reviewFile: payload.file });
111
- return send(response, 201, '<p class="success-message">Impact analysis queued for your attached agent.</p>', undefined, { 'HX-Trigger': 'workspace-updated' });
215
+ return send(response, 201, '', undefined, { 'HX-Trigger': JSON.stringify({ 'spequi-toast': { message: 'Impact analysis queued for your attached agent.' }, 'workspace-updated': true }) });
112
216
  }
113
217
  const exported = await exportFeedback(root, preview);
114
218
  const update = action === 'update-specs' ? await enqueue(root, { action: 'update-specs', reviewPreview: preview, feedbackId: exported.id }) : null;
115
219
  const downloadUrl = `/api/reviews/${preview}/feedback/${exported.id}`;
116
220
  if (request.headers.accept?.includes('application/json')) return send(response, 201, JSON.stringify({ exported: { ...exported, downloadUrl }, ...(update ? { update: { id: update.id, change: update.change, status: update.status, reviewPreview: update.reviewPreview, feedbackId: update.feedbackId } } : {}) }), 'application/json');
221
+ if (update) return send(response, 201, '', undefined, { 'HX-Trigger': JSON.stringify({ 'spequi-toast': { message: 'OpenSpec planning update queued using this feedback document.', downloadUrl }, 'workspace-updated': true }) });
117
222
  return send(response, 201, `<p class="success-message">${action === 'update-specs' ? 'OpenSpec planning update queued using this feedback document.' : 'Feedback document saved.'} <a href="${downloadUrl}" download="openspec-review-feedback.md">Download Markdown</a></p>`, undefined, { 'HX-Trigger': 'workspace-updated' });
118
223
  }
119
224
  const deleteMatch = url.pathname.match(/^\/api\/reviews\/([a-zA-Z0-9_-]+)\/comments\/([a-zA-Z0-9_-]+)\/delete$/);
@@ -124,7 +229,7 @@ export async function startServer({ root = process.cwd(), port, quiet = false }
124
229
  }
125
230
  if (url.pathname === '/api/jobs') {
126
231
  const job = await enqueue(root, payload);
127
- return send(response, 201, `<p class="success-message">${escape(job.action === 'preview' ? 'Preview' : 'Workflow')} queued. Your agent will pick it up.</p>`, undefined, { 'HX-Trigger': 'workspace-updated' });
232
+ return send(response, 201, '', undefined, { 'HX-Trigger': JSON.stringify({ 'spequi-toast': { message: `${job.action === 'preview' ? 'Preview' : 'Workflow'} queued. Your agent will pick it up.` }, 'workspace-updated': true }) });
128
233
  }
129
234
  const cancelMatch = url.pathname.match(/^\/api\/jobs\/([a-zA-Z0-9_-]+)\/cancel$/);
130
235
  if (cancelMatch) {
@@ -144,32 +249,57 @@ export async function startServer({ root = process.cwd(), port, quiet = false }
144
249
  return send(response, 404, 'Action not found');
145
250
  } catch (error) {
146
251
  if (!response.headersSent) {
147
- if (request.headers.accept?.includes('application/json')) send(response, 400, JSON.stringify({ error: error.message }), 'application/json');
252
+ if (request.headers.accept?.includes('application/json')) send(response, 400, JSON.stringify({ error: error.message, ...(error.code ? { code: error.code } : {}) }), 'application/json');
148
253
  else send(response, 400, `<p class="error-message">${escape(error.message)}</p>`);
149
254
  }
150
255
  else response.end();
151
256
  }
152
257
  });
153
258
  server.requestTimeout = 15000;
154
- await new Promise((resolve, reject) => { server.once('error', reject); server.listen(selectedPort, '127.0.0.1', resolve); });
259
+ try { await new Promise((resolve, reject) => { server.once('error', reject); server.listen(selectedPort, '127.0.0.1', resolve); }); }
260
+ catch (error) { state.close(); jobReader.close(); await releaseServer(); throw error; }
155
261
  origin = `http://127.0.0.1:${server.address().port}`;
262
+ try { await writeJSON(runtime(root, 'server.json'), { protocol: 1, origin, root, pid: process.pid, token: agentToken, version: viewerVersion }); }
263
+ catch (error) { state.close(); jobReader.close(); server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); await releaseServer(); throw error; }
156
264
  const wss = new WebSocketServer({ noServer: true, maxPayload: 1024 });
157
265
  server.on('upgrade', (request, socket, head) => {
158
266
  const allowedOrigins = [origin, `http://localhost:${server.address().port}`];
159
267
  if (request.url !== '/live' || !allowedOrigins.includes(request.headers.origin) || ![new URL(origin).host, `localhost:${server.address().port}`].includes(request.headers.host)) { socket.destroy(); return; }
160
268
  wss.handleUpgrade(request, socket, head, connection => { connection.on('error', () => {}); connection.send(JSON.stringify({ type: 'connected' })); });
161
269
  });
162
- const broadcast = type => { for (const client of wss.clients) if (client.readyState === WebSocket.OPEN) client.send(JSON.stringify({ type })); };
163
- let timer;
164
- const watcher = chokidar.watch([path.join(root, 'openspec'), runtime(root, 'jobs'), runtime(root, 'agent.json'), runtime(root, 'agent-session.json'), runtime(root, 'previews'), runtime(root, 'reviews'), runtime(root, 'analyses'), runtime(root, 'validation'), runtime(root, 'studio')], { ignoreInitial: true, ignored: file => isPreviewSnapshotPath(file) || file.startsWith(runtime(root, 'studio') + path.sep) && (file.endsWith('capture.lock') || file.endsWith('.tmp')), depth: 12, awaitWriteFinish: { stabilityThreshold: 120, pollInterval: 50 } });
270
+ broadcast = (type, detail = {}) => { for (const client of wss.clients) if (client.readyState === WebSocket.OPEN) client.send(JSON.stringify({ type, ...detail })); };
271
+ let timer, requestTimer, changeScope, globalChange = false;
272
+ const watcher = chokidar.watch([path.join(root, 'openspec'), runtime(root, 'jobs'), runtime(root, 'drafts'), runtime(root, 'agent.json'), runtime(root, 'agent-session.json'), runtime(root, 'previews'), runtime(root, 'reviews'), runtime(root, 'analyses'), runtime(root, 'validation'), runtime(root, 'studio')], { ignoreInitial: true, ignored: file => isPreviewSnapshotPath(file) || file.endsWith('.tmp') || file.endsWith('.lock') || file.endsWith('.recovery'), depth: 12, awaitWriteFinish: { stabilityThreshold: 120, pollInterval: 50 } });
165
273
  watcher.on('all', (_event, watched) => {
166
274
  if ([runtime(root, 'agent.json'), runtime(root, 'agent-session.json')].includes(watched)) { broadcast('agent'); return; }
167
- clearTimeout(timer); timer = setTimeout(() => broadcast('changed'), 200);
275
+ if (watched.startsWith(runtime(root, 'jobs') + path.sep)) {
276
+ const id = path.basename(watched).match(/^([a-zA-Z0-9_-]+)\.json$/)?.[1];
277
+ if (id) jobReader.invalidate(id);
278
+ clearTimeout(requestTimer); requestTimer = setTimeout(() => broadcast('requests'), 150); return;
279
+ }
280
+ if (watched === runtime(root, 'drafts') || watched.startsWith(runtime(root, 'drafts') + path.sep)) { broadcast('requests'); return; }
281
+ if (watched === runtime(root, 'studio') || watched.startsWith(runtime(root, 'studio') + path.sep)) return;
282
+ let scope;
283
+ if (watched.startsWith(path.join(root, 'openspec') + path.sep)) {
284
+ const relative = path.relative(path.join(root, 'openspec'), watched).split(path.sep);
285
+ scope = relative[0] === 'changes' && relative[1] !== 'archive' ? relative[1] : undefined;
286
+ state.invalidate(scope);
287
+ }
288
+ if (!scope || changeScope && changeScope !== scope) globalChange = true;
289
+ changeScope = scope;
290
+ clearTimeout(timer); timer = setTimeout(() => { broadcast('changed', globalChange ? {} : { change: changeScope }); changeScope = undefined; globalChange = false; }, 200);
168
291
  });
169
292
  watcher.on('error', error => { if (!quiet) process.stderr.write(`File watching: ${error.message}\n`); });
170
293
  const interval = setInterval(() => broadcast('heartbeat'), 15000);
171
294
  interval.unref();
172
295
  if (!quiet) process.stdout.write(`\n spequi\n ${origin}\n Project: ${root}\n\n Attach the spequi skill in your agent to handle workflows.\n Press Ctrl+C to stop.\n\n`);
173
- const close = async () => { clearInterval(interval); clearTimeout(timer); await watcher.close(); for (const client of wss.clients) client.terminate(); await new Promise(resolve => wss.close(resolve)); await new Promise(resolve => server.close(resolve)); };
296
+ const close = async () => {
297
+ if (closed) return;
298
+ closed = true; state.close(); jobReader.close(); clearInterval(interval); clearTimeout(timer); clearTimeout(requestTimer);
299
+ await watcher.close(); for (const client of wss.clients) client.terminate(); await new Promise(resolve => wss.close(resolve));
300
+ server.closeAllConnections(); await new Promise(resolve => server.close(resolve));
301
+ if ((await readJSON(runtime(root, 'server.json')))?.token === agentToken) await fs.rm(runtime(root, 'server.json'), { force: true });
302
+ await releaseServer();
303
+ };
174
304
  return { server, origin, close };
175
305
  }