workerssuper 5.0.4

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 (135) hide show
  1. package/.claude-plugin/marketplace.json +20 -0
  2. package/.claude-plugin/plugin.json +13 -0
  3. package/.codex/INSTALL.md +67 -0
  4. package/.cursor-plugin/plugin.json +18 -0
  5. package/.gitattributes +18 -0
  6. package/.github/FUNDING.yml +3 -0
  7. package/.github/ISSUE_TEMPLATE/bug_report.md +52 -0
  8. package/.github/ISSUE_TEMPLATE/config.yml +5 -0
  9. package/.github/ISSUE_TEMPLATE/feature_request.md +34 -0
  10. package/.github/ISSUE_TEMPLATE/platform_support.md +23 -0
  11. package/.github/PULL_REQUEST_TEMPLATE.md +87 -0
  12. package/.opencode/INSTALL.md +83 -0
  13. package/.opencode/plugins/superpowers.js +107 -0
  14. package/CHANGELOG.md +13 -0
  15. package/CODE_OF_CONDUCT.md +128 -0
  16. package/GEMINI.md +2 -0
  17. package/LICENSE +21 -0
  18. package/README.md +187 -0
  19. package/RELEASE-NOTES.md +1057 -0
  20. package/agents/code-reviewer.md +48 -0
  21. package/commands/brainstorm.md +5 -0
  22. package/commands/execute-plan.md +5 -0
  23. package/commands/write-plan.md +5 -0
  24. package/docs/README.codex.md +126 -0
  25. package/docs/README.opencode.md +130 -0
  26. package/docs/plans/2025-11-22-opencode-support-design.md +294 -0
  27. package/docs/plans/2025-11-22-opencode-support-implementation.md +1095 -0
  28. package/docs/plans/2025-11-28-skills-improvements-from-user-feedback.md +711 -0
  29. package/docs/plans/2026-01-17-visual-brainstorming.md +571 -0
  30. package/docs/superpowers/plans/2026-01-22-document-review-system.md +301 -0
  31. package/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md +523 -0
  32. package/docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md +479 -0
  33. package/docs/superpowers/specs/2026-01-22-document-review-system-design.md +136 -0
  34. package/docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md +162 -0
  35. package/docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md +118 -0
  36. package/docs/testing.md +303 -0
  37. package/docs/windows/polyglot-hooks.md +212 -0
  38. package/gemini-extension.json +6 -0
  39. package/hooks/hooks-cursor.json +10 -0
  40. package/hooks/hooks.json +16 -0
  41. package/hooks/run-hook.cmd +46 -0
  42. package/hooks/session-start +57 -0
  43. package/package.json +5 -0
  44. package/skills/brainstorming/SKILL.md +164 -0
  45. package/skills/brainstorming/scripts/frame-template.html +214 -0
  46. package/skills/brainstorming/scripts/helper.js +88 -0
  47. package/skills/brainstorming/scripts/server.cjs +338 -0
  48. package/skills/brainstorming/scripts/start-server.sh +153 -0
  49. package/skills/brainstorming/scripts/stop-server.sh +55 -0
  50. package/skills/brainstorming/spec-document-reviewer-prompt.md +49 -0
  51. package/skills/brainstorming/visual-companion.md +286 -0
  52. package/skills/dispatching-parallel-agents/SKILL.md +182 -0
  53. package/skills/executing-plans/SKILL.md +70 -0
  54. package/skills/finishing-a-development-branch/SKILL.md +200 -0
  55. package/skills/receiving-code-review/SKILL.md +213 -0
  56. package/skills/requesting-code-review/SKILL.md +105 -0
  57. package/skills/requesting-code-review/code-reviewer.md +146 -0
  58. package/skills/subagent-driven-development/SKILL.md +277 -0
  59. package/skills/subagent-driven-development/code-quality-reviewer-prompt.md +26 -0
  60. package/skills/subagent-driven-development/implementer-prompt.md +113 -0
  61. package/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
  62. package/skills/systematic-debugging/CREATION-LOG.md +119 -0
  63. package/skills/systematic-debugging/SKILL.md +296 -0
  64. package/skills/systematic-debugging/condition-based-waiting-example.ts +158 -0
  65. package/skills/systematic-debugging/condition-based-waiting.md +115 -0
  66. package/skills/systematic-debugging/defense-in-depth.md +122 -0
  67. package/skills/systematic-debugging/find-polluter.sh +63 -0
  68. package/skills/systematic-debugging/root-cause-tracing.md +169 -0
  69. package/skills/systematic-debugging/test-academic.md +14 -0
  70. package/skills/systematic-debugging/test-pressure-1.md +58 -0
  71. package/skills/systematic-debugging/test-pressure-2.md +68 -0
  72. package/skills/systematic-debugging/test-pressure-3.md +69 -0
  73. package/skills/test-driven-development/SKILL.md +371 -0
  74. package/skills/test-driven-development/testing-anti-patterns.md +299 -0
  75. package/skills/using-git-worktrees/SKILL.md +218 -0
  76. package/skills/using-superpowers/SKILL.md +115 -0
  77. package/skills/using-superpowers/references/codex-tools.md +25 -0
  78. package/skills/using-superpowers/references/gemini-tools.md +33 -0
  79. package/skills/verification-before-completion/SKILL.md +139 -0
  80. package/skills/writing-plans/SKILL.md +145 -0
  81. package/skills/writing-plans/plan-document-reviewer-prompt.md +49 -0
  82. package/skills/writing-skills/SKILL.md +655 -0
  83. package/skills/writing-skills/anthropic-best-practices.md +1150 -0
  84. package/skills/writing-skills/examples/CLAUDE_MD_TESTING.md +189 -0
  85. package/skills/writing-skills/graphviz-conventions.dot +172 -0
  86. package/skills/writing-skills/persuasion-principles.md +187 -0
  87. package/skills/writing-skills/render-graphs.js +168 -0
  88. package/skills/writing-skills/testing-skills-with-subagents.md +384 -0
  89. package/tests/brainstorm-server/package-lock.json +36 -0
  90. package/tests/brainstorm-server/package.json +10 -0
  91. package/tests/brainstorm-server/server.test.js +424 -0
  92. package/tests/brainstorm-server/windows-lifecycle.test.sh +351 -0
  93. package/tests/brainstorm-server/ws-protocol.test.js +392 -0
  94. package/tests/claude-code/README.md +158 -0
  95. package/tests/claude-code/analyze-token-usage.py +168 -0
  96. package/tests/claude-code/run-skill-tests.sh +187 -0
  97. package/tests/claude-code/test-document-review-system.sh +177 -0
  98. package/tests/claude-code/test-helpers.sh +202 -0
  99. package/tests/claude-code/test-subagent-driven-development-integration.sh +314 -0
  100. package/tests/claude-code/test-subagent-driven-development.sh +165 -0
  101. package/tests/explicit-skill-requests/prompts/action-oriented.txt +3 -0
  102. package/tests/explicit-skill-requests/prompts/after-planning-flow.txt +17 -0
  103. package/tests/explicit-skill-requests/prompts/claude-suggested-it.txt +11 -0
  104. package/tests/explicit-skill-requests/prompts/i-know-what-sdd-means.txt +8 -0
  105. package/tests/explicit-skill-requests/prompts/mid-conversation-execute-plan.txt +3 -0
  106. package/tests/explicit-skill-requests/prompts/please-use-brainstorming.txt +1 -0
  107. package/tests/explicit-skill-requests/prompts/skip-formalities.txt +3 -0
  108. package/tests/explicit-skill-requests/prompts/subagent-driven-development-please.txt +1 -0
  109. package/tests/explicit-skill-requests/prompts/use-systematic-debugging.txt +1 -0
  110. package/tests/explicit-skill-requests/run-all.sh +70 -0
  111. package/tests/explicit-skill-requests/run-claude-describes-sdd.sh +100 -0
  112. package/tests/explicit-skill-requests/run-extended-multiturn-test.sh +113 -0
  113. package/tests/explicit-skill-requests/run-haiku-test.sh +144 -0
  114. package/tests/explicit-skill-requests/run-multiturn-test.sh +143 -0
  115. package/tests/explicit-skill-requests/run-test.sh +136 -0
  116. package/tests/opencode/run-tests.sh +163 -0
  117. package/tests/opencode/setup.sh +73 -0
  118. package/tests/opencode/test-plugin-loading.sh +72 -0
  119. package/tests/opencode/test-priority.sh +198 -0
  120. package/tests/opencode/test-tools.sh +104 -0
  121. package/tests/skill-triggering/prompts/dispatching-parallel-agents.txt +8 -0
  122. package/tests/skill-triggering/prompts/executing-plans.txt +1 -0
  123. package/tests/skill-triggering/prompts/requesting-code-review.txt +3 -0
  124. package/tests/skill-triggering/prompts/systematic-debugging.txt +11 -0
  125. package/tests/skill-triggering/prompts/test-driven-development.txt +7 -0
  126. package/tests/skill-triggering/prompts/writing-plans.txt +10 -0
  127. package/tests/skill-triggering/run-all.sh +60 -0
  128. package/tests/skill-triggering/run-test.sh +88 -0
  129. package/tests/subagent-driven-dev/go-fractals/design.md +81 -0
  130. package/tests/subagent-driven-dev/go-fractals/plan.md +172 -0
  131. package/tests/subagent-driven-dev/go-fractals/scaffold.sh +45 -0
  132. package/tests/subagent-driven-dev/run-test.sh +106 -0
  133. package/tests/subagent-driven-dev/svelte-todo/design.md +70 -0
  134. package/tests/subagent-driven-dev/svelte-todo/plan.md +222 -0
  135. package/tests/subagent-driven-dev/svelte-todo/scaffold.sh +46 -0
package/skills/brainstorming/scripts/frame-template.html ADDED
@@ -0,0 +1,214 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Superpowers Brainstorming</title>
6
+ <style>
7
+ /*
8
+ * BRAINSTORM COMPANION FRAME TEMPLATE
9
+ *
10
+ * This template provides a consistent frame with:
11
+ * - OS-aware light/dark theming
12
+ * - Fixed header and selection indicator bar
13
+ * - Scrollable main content area
14
+ * - CSS helpers for common UI patterns
15
+ *
16
+ * Content is injected via placeholder comment in #claude-content.
17
+ */
18
+
19
+ * { box-sizing: border-box; margin: 0; padding: 0; }
20
+ html, body { height: 100%; overflow: hidden; }
21
+
22
+ /* ===== THEME VARIABLES ===== */
23
+ :root {
24
+ --bg-primary: #f5f5f7;
25
+ --bg-secondary: #ffffff;
26
+ --bg-tertiary: #e5e5e7;
27
+ --border: #d1d1d6;
28
+ --text-primary: #1d1d1f;
29
+ --text-secondary: #86868b;
30
+ --text-tertiary: #aeaeb2;
31
+ --accent: #0071e3;
32
+ --accent-hover: #0077ed;
33
+ --success: #34c759;
34
+ --warning: #ff9f0a;
35
+ --error: #ff3b30;
36
+ --selected-bg: #e8f4fd;
37
+ --selected-border: #0071e3;
38
+ }
39
+
40
+ @media (prefers-color-scheme: dark) {
41
+ :root {
42
+ --bg-primary: #1d1d1f;
43
+ --bg-secondary: #2d2d2f;
44
+ --bg-tertiary: #3d3d3f;
45
+ --border: #424245;
46
+ --text-primary: #f5f5f7;
47
+ --text-secondary: #86868b;
48
+ --text-tertiary: #636366;
49
+ --accent: #0a84ff;
50
+ --accent-hover: #409cff;
51
+ --selected-bg: rgba(10, 132, 255, 0.15);
52
+ --selected-border: #0a84ff;
53
+ }
54
+ }
55
+
56
+ body {
57
+ font-family: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
58
+ background: var(--bg-primary);
59
+ color: var(--text-primary);
60
+ display: flex;
61
+ flex-direction: column;
62
+ line-height: 1.5;
63
+ }
64
+
65
+ /* ===== FRAME STRUCTURE ===== */
66
+ .header {
67
+ background: var(--bg-secondary);
68
+ padding: 0.5rem 1.5rem;
69
+ display: flex;
70
+ justify-content: space-between;
71
+ align-items: center;
72
+ border-bottom: 1px solid var(--border);
73
+ flex-shrink: 0;
74
+ }
75
+ .header h1 { font-size: 0.85rem; font-weight: 500; color: var(--text-secondary); }
76
+ .header .status { font-size: 0.7rem; color: var(--success); display: flex; align-items: center; gap: 0.4rem; }
77
+ .header .status::before { content: ''; width: 6px; height: 6px; background: var(--success); border-radius: 50%; }
78
+
79
+ .main { flex: 1; overflow-y: auto; }
80
+ #claude-content { padding: 2rem; min-height: 100%; }
81
+
82
+ .indicator-bar {
83
+ background: var(--bg-secondary);
84
+ border-top: 1px solid var(--border);
85
+ padding: 0.5rem 1.5rem;
86
+ flex-shrink: 0;
87
+ text-align: center;
88
+ }
89
+ .indicator-bar span {
90
+ font-size: 0.75rem;
91
+ color: var(--text-secondary);
92
+ }
93
+ .indicator-bar .selected-text {
94
+ color: var(--accent);
95
+ font-weight: 500;
96
+ }
97
+
98
+ /* ===== TYPOGRAPHY ===== */
99
+ h2 { font-size: 1.5rem; font-weight: 600; margin-bottom: 0.5rem; }
100
+ h3 { font-size: 1.1rem; font-weight: 600; margin-bottom: 0.25rem; }
101
+ .subtitle { color: var(--text-secondary); margin-bottom: 1.5rem; }
102
+ .section { margin-bottom: 2rem; }
103
+ .label { font-size: 0.7rem; color: var(--text-secondary); text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 0.5rem; }
104
+
105
+ /* ===== OPTIONS (for A/B/C choices) ===== */
106
+ .options { display: flex; flex-direction: column; gap: 0.75rem; }
107
+ .option {
108
+ background: var(--bg-secondary);
109
+ border: 2px solid var(--border);
110
+ border-radius: 12px;
111
+ padding: 1rem 1.25rem;
112
+ cursor: pointer;
113
+ transition: all 0.15s ease;
114
+ display: flex;
115
+ align-items: flex-start;
116
+ gap: 1rem;
117
+ }
118
+ .option:hover { border-color: var(--accent); }
119
+ .option.selected { background: var(--selected-bg); border-color: var(--selected-border); }
120
+ .option .letter {
121
+ background: var(--bg-tertiary);
122
+ color: var(--text-secondary);
123
+ width: 1.75rem; height: 1.75rem;
124
+ border-radius: 6px;
125
+ display: flex; align-items: center; justify-content: center;
126
+ font-weight: 600; font-size: 0.85rem; flex-shrink: 0;
127
+ }
128
+ .option.selected .letter { background: var(--accent); color: white; }
129
+ .option .content { flex: 1; }
130
+ .option .content h3 { font-size: 0.95rem; margin-bottom: 0.15rem; }
131
+ .option .content p { color: var(--text-secondary); font-size: 0.85rem; margin: 0; }
132
+
133
+ /* ===== CARDS (for showing designs/mockups) ===== */
134
+ .cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1rem; }
135
+ .card {
136
+ background: var(--bg-secondary);
137
+ border: 1px solid var(--border);
138
+ border-radius: 12px;
139
+ overflow: hidden;
140
+ cursor: pointer;
141
+ transition: all 0.15s ease;
142
+ }
143
+ .card:hover { border-color: var(--accent); transform: translateY(-2px); box-shadow: 0 4px 12px rgba(0,0,0,0.1); }
144
+ .card.selected { border-color: var(--selected-border); border-width: 2px; }
145
+ .card-image { background: var(--bg-tertiary); aspect-ratio: 16/10; display: flex; align-items: center; justify-content: center; }
146
+ .card-body { padding: 1rem; }
147
+ .card-body h3 { margin-bottom: 0.25rem; }
148
+ .card-body p { color: var(--text-secondary); font-size: 0.85rem; }
149
+
150
+ /* ===== MOCKUP CONTAINER ===== */
151
+ .mockup {
152
+ background: var(--bg-secondary);
153
+ border: 1px solid var(--border);
154
+ border-radius: 12px;
155
+ overflow: hidden;
156
+ margin-bottom: 1.5rem;
157
+ }
158
+ .mockup-header {
159
+ background: var(--bg-tertiary);
160
+ padding: 0.5rem 1rem;
161
+ font-size: 0.75rem;
162
+ color: var(--text-secondary);
163
+ border-bottom: 1px solid var(--border);
164
+ }
165
+ .mockup-body { padding: 1.5rem; }
166
+
167
+ /* ===== SPLIT VIEW (side-by-side comparison) ===== */
168
+ .split { display: grid; grid-template-columns: 1fr 1fr; gap: 1.5rem; }
169
+ @media (max-width: 700px) { .split { grid-template-columns: 1fr; } }
170
+
171
+ /* ===== PROS/CONS ===== */
172
+ .pros-cons { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 1rem 0; }
173
+ .pros, .cons { background: var(--bg-secondary); border-radius: 8px; padding: 1rem; }
174
+ .pros h4 { color: var(--success); font-size: 0.85rem; margin-bottom: 0.5rem; }
175
+ .cons h4 { color: var(--error); font-size: 0.85rem; margin-bottom: 0.5rem; }
176
+ .pros ul, .cons ul { margin-left: 1.25rem; font-size: 0.85rem; color: var(--text-secondary); }
177
+ .pros li, .cons li { margin-bottom: 0.25rem; }
178
+
179
+ /* ===== PLACEHOLDER (for mockup areas) ===== */
180
+ .placeholder {
181
+ background: var(--bg-tertiary);
182
+ border: 2px dashed var(--border);
183
+ border-radius: 8px;
184
+ padding: 2rem;
185
+ text-align: center;
186
+ color: var(--text-tertiary);
187
+ }
188
+
189
+ /* ===== INLINE MOCKUP ELEMENTS ===== */
190
+ .mock-nav { background: var(--accent); color: white; padding: 0.75rem 1rem; display: flex; gap: 1.5rem; font-size: 0.9rem; }
191
+ .mock-sidebar { background: var(--bg-tertiary); padding: 1rem; min-width: 180px; }
192
+ .mock-content { padding: 1.5rem; flex: 1; }
193
+ .mock-button { background: var(--accent); color: white; border: none; padding: 0.5rem 1rem; border-radius: 6px; font-size: 0.85rem; }
194
+ .mock-input { background: var(--bg-primary); border: 1px solid var(--border); border-radius: 6px; padding: 0.5rem; width: 100%; }
195
+ </style>
196
+ </head>
197
+ <body>
198
+ <div class="header">
199
+ <h1><a href="https://github.com/obra/superpowers" style="color: inherit; text-decoration: none;">Superpowers Brainstorming</a></h1>
200
+ <div class="status">Connected</div>
201
+ </div>
202
+
203
+ <div class="main">
204
+ <div id="claude-content">
205
+ <!-- CONTENT -->
206
+ </div>
207
+ </div>
208
+
209
+ <div class="indicator-bar">
210
+ <span id="indicator-text">Click an option above, then return to the terminal</span>
211
+ </div>
212
+
213
+ </body>
214
+ </html>
package/skills/brainstorming/scripts/helper.js ADDED
@@ -0,0 +1,88 @@
1
+ (function() {
2
+ const WS_URL = 'ws://' + window.location.host;
3
+ let ws = null;
4
+ let eventQueue = [];
5
+
6
+ function connect() {
7
+ ws = new WebSocket(WS_URL);
8
+
9
+ ws.onopen = () => {
10
+ eventQueue.forEach(e => ws.send(JSON.stringify(e)));
11
+ eventQueue = [];
12
+ };
13
+
14
+ ws.onmessage = (msg) => {
15
+ const data = JSON.parse(msg.data);
16
+ if (data.type === 'reload') {
17
+ window.location.reload();
18
+ }
19
+ };
20
+
21
+ ws.onclose = () => {
22
+ setTimeout(connect, 1000);
23
+ };
24
+ }
25
+
26
+ function sendEvent(event) {
27
+ event.timestamp = Date.now();
28
+ if (ws && ws.readyState === WebSocket.OPEN) {
29
+ ws.send(JSON.stringify(event));
30
+ } else {
31
+ eventQueue.push(event);
32
+ }
33
+ }
34
+
35
+ // Capture clicks on choice elements
36
+ document.addEventListener('click', (e) => {
37
+ const target = e.target.closest('[data-choice]');
38
+ if (!target) return;
39
+
40
+ sendEvent({
41
+ type: 'click',
42
+ text: target.textContent.trim(),
43
+ choice: target.dataset.choice,
44
+ id: target.id || null
45
+ });
46
+
47
+ // Update indicator bar (defer so toggleSelect runs first)
48
+ setTimeout(() => {
49
+ const indicator = document.getElementById('indicator-text');
50
+ if (!indicator) return;
51
+ const container = target.closest('.options') || target.closest('.cards');
52
+ const selected = container ? container.querySelectorAll('.selected') : [];
53
+ if (selected.length === 0) {
54
+ indicator.textContent = 'Click an option above, then return to the terminal';
55
+ } else if (selected.length === 1) {
56
+ const label = selected[0].querySelector('h3, .content h3, .card-body h3')?.textContent?.trim() || selected[0].dataset.choice;
57
+ indicator.innerHTML = '<span class="selected-text">' + label + ' selected</span> — return to terminal to continue';
58
+ } else {
59
+ indicator.innerHTML = '<span class="selected-text">' + selected.length + ' selected</span> — return to terminal to continue';
60
+ }
61
+ }, 0);
62
+ });
63
+
64
+ // Frame UI: selection tracking
65
+ window.selectedChoice = null;
66
+
67
+ window.toggleSelect = function(el) {
68
+ const container = el.closest('.options') || el.closest('.cards');
69
+ const multi = container && container.dataset.multiselect !== undefined;
70
+ if (container && !multi) {
71
+ container.querySelectorAll('.option, .card').forEach(o => o.classList.remove('selected'));
72
+ }
73
+ if (multi) {
74
+ el.classList.toggle('selected');
75
+ } else {
76
+ el.classList.add('selected');
77
+ }
78
+ window.selectedChoice = el.dataset.choice;
79
+ };
80
+
81
+ // Expose API for explicit use
82
+ window.brainstorm = {
83
+ send: sendEvent,
84
+ choice: (value, metadata = {}) => sendEvent({ type: 'choice', value, ...metadata })
85
+ };
86
+
87
+ connect();
88
+ })();
package/skills/brainstorming/scripts/server.cjs ADDED
@@ -0,0 +1,338 @@
1
+ const crypto = require('crypto');
2
+ const http = require('http');
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+
6
+ // ========== WebSocket Protocol (RFC 6455) ==========
7
+
8
+ const OPCODES = { TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
9
+ const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
10
+
11
+ function computeAcceptKey(clientKey) {
12
+ return crypto.createHash('sha1').update(clientKey + WS_MAGIC).digest('base64');
13
+ }
14
+
15
+ function encodeFrame(opcode, payload) {
16
+ const fin = 0x80;
17
+ const len = payload.length;
18
+ let header;
19
+
20
+ if (len < 126) {
21
+ header = Buffer.alloc(2);
22
+ header[0] = fin | opcode;
23
+ header[1] = len;
24
+ } else if (len < 65536) {
25
+ header = Buffer.alloc(4);
26
+ header[0] = fin | opcode;
27
+ header[1] = 126;
28
+ header.writeUInt16BE(len, 2);
29
+ } else {
30
+ header = Buffer.alloc(10);
31
+ header[0] = fin | opcode;
32
+ header[1] = 127;
33
+ header.writeBigUInt64BE(BigInt(len), 2);
34
+ }
35
+
36
+ return Buffer.concat([header, payload]);
37
+ }
38
+
39
+ function decodeFrame(buffer) {
40
+ if (buffer.length < 2) return null;
41
+
42
+ const secondByte = buffer[1];
43
+ const opcode = buffer[0] & 0x0F;
44
+ const masked = (secondByte & 0x80) !== 0;
45
+ let payloadLen = secondByte & 0x7F;
46
+ let offset = 2;
47
+
48
+ if (!masked) throw new Error('Client frames must be masked');
49
+
50
+ if (payloadLen === 126) {
51
+ if (buffer.length < 4) return null;
52
+ payloadLen = buffer.readUInt16BE(2);
53
+ offset = 4;
54
+ } else if (payloadLen === 127) {
55
+ if (buffer.length < 10) return null;
56
+ payloadLen = Number(buffer.readBigUInt64BE(2));
57
+ offset = 10;
58
+ }
59
+
60
+ const maskOffset = offset;
61
+ const dataOffset = offset + 4;
62
+ const totalLen = dataOffset + payloadLen;
63
+ if (buffer.length < totalLen) return null;
64
+
65
+ const mask = buffer.slice(maskOffset, dataOffset);
66
+ const data = Buffer.alloc(payloadLen);
67
+ for (let i = 0; i < payloadLen; i++) {
68
+ data[i] = buffer[dataOffset + i] ^ mask[i % 4];
69
+ }
70
+
71
+ return { opcode, payload: data, bytesConsumed: totalLen };
72
+ }
73
+
74
+ // ========== Configuration ==========
75
+
76
+ const PORT = process.env.BRAINSTORM_PORT || (49152 + Math.floor(Math.random() * 16383));
77
+ const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
78
+ const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
79
+ const SCREEN_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
80
+ const OWNER_PID = process.env.BRAINSTORM_OWNER_PID ? Number(process.env.BRAINSTORM_OWNER_PID) : null;
81
+
82
+ const MIME_TYPES = {
83
+ '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
84
+ '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
85
+ '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml'
86
+ };
87
+
88
+ // ========== Templates and Constants ==========
89
+
90
+ const WAITING_PAGE = `<!DOCTYPE html>
91
+ <html>
92
+ <head><meta charset="utf-8"><title>Brainstorm Companion</title>
93
+ <style>body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
94
+ h1 { color: #333; } p { color: #666; }</style>
95
+ </head>
96
+ <body><h1>Brainstorm Companion</h1>
97
+ <p>Waiting for the agent to push a screen...</p></body></html>`;
98
+
99
+ const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
100
+ const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
101
+ const helperInjection = '<script>\n' + helperScript + '\n</script>';
102
+
103
+ // ========== Helper Functions ==========
104
+
105
+ function isFullDocument(html) {
106
+ const trimmed = html.trimStart().toLowerCase();
107
+ return trimmed.startsWith('<!doctype') || trimmed.startsWith('<html');
108
+ }
109
+
110
+ function wrapInFrame(content) {
111
+ return frameTemplate.replace('<!-- CONTENT -->', content);
112
+ }
113
+
114
+ function getNewestScreen() {
115
+ const files = fs.readdirSync(SCREEN_DIR)
116
+ .filter(f => f.endsWith('.html'))
117
+ .map(f => {
118
+ const fp = path.join(SCREEN_DIR, f);
119
+ return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
120
+ })
121
+ .sort((a, b) => b.mtime - a.mtime);
122
+ return files.length > 0 ? files[0].path : null;
123
+ }
124
+
125
+ // ========== HTTP Request Handler ==========
126
+
127
+ function handleRequest(req, res) {
128
+ touchActivity();
129
+ if (req.method === 'GET' && req.url === '/') {
130
+ const screenFile = getNewestScreen();
131
+ let html = screenFile
132
+ ? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8'))
133
+ : WAITING_PAGE;
134
+
135
+ if (html.includes('</body>')) {
136
+ html = html.replace('</body>', helperInjection + '\n</body>');
137
+ } else {
138
+ html += helperInjection;
139
+ }
140
+
141
+ res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
142
+ res.end(html);
143
+ } else if (req.method === 'GET' && req.url.startsWith('/files/')) {
144
+ const fileName = req.url.slice(7);
145
+ const filePath = path.join(SCREEN_DIR, path.basename(fileName));
146
+ if (!fs.existsSync(filePath)) {
147
+ res.writeHead(404);
148
+ res.end('Not found');
149
+ return;
150
+ }
151
+ const ext = path.extname(filePath).toLowerCase();
152
+ const contentType = MIME_TYPES[ext] || 'application/octet-stream';
153
+ res.writeHead(200, { 'Content-Type': contentType });
154
+ res.end(fs.readFileSync(filePath));
155
+ } else {
156
+ res.writeHead(404);
157
+ res.end('Not found');
158
+ }
159
+ }
160
+
161
+ // ========== WebSocket Connection Handling ==========
162
+
163
+ const clients = new Set();
164
+
165
+ function handleUpgrade(req, socket) {
166
+ const key = req.headers['sec-websocket-key'];
167
+ if (!key) { socket.destroy(); return; }
168
+
169
+ const accept = computeAcceptKey(key);
170
+ socket.write(
171
+ 'HTTP/1.1 101 Switching Protocols\r\n' +
172
+ 'Upgrade: websocket\r\n' +
173
+ 'Connection: Upgrade\r\n' +
174
+ 'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n'
175
+ );
176
+
177
+ let buffer = Buffer.alloc(0);
178
+ clients.add(socket);
179
+
180
+ socket.on('data', (chunk) => {
181
+ buffer = Buffer.concat([buffer, chunk]);
182
+ while (buffer.length > 0) {
183
+ let result;
184
+ try {
185
+ result = decodeFrame(buffer);
186
+ } catch (e) {
187
+ socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
188
+ clients.delete(socket);
189
+ return;
190
+ }
191
+ if (!result) break;
192
+ buffer = buffer.slice(result.bytesConsumed);
193
+
194
+ switch (result.opcode) {
195
+ case OPCODES.TEXT:
196
+ handleMessage(result.payload.toString());
197
+ break;
198
+ case OPCODES.CLOSE:
199
+ socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
200
+ clients.delete(socket);
201
+ return;
202
+ case OPCODES.PING:
203
+ socket.write(encodeFrame(OPCODES.PONG, result.payload));
204
+ break;
205
+ case OPCODES.PONG:
206
+ break;
207
+ default: {
208
+ const closeBuf = Buffer.alloc(2);
209
+ closeBuf.writeUInt16BE(1003);
210
+ socket.end(encodeFrame(OPCODES.CLOSE, closeBuf));
211
+ clients.delete(socket);
212
+ return;
213
+ }
214
+ }
215
+ }
216
+ });
217
+
218
+ socket.on('close', () => clients.delete(socket));
219
+ socket.on('error', () => clients.delete(socket));
220
+ }
221
+
222
+ function handleMessage(text) {
223
+ let event;
224
+ try {
225
+ event = JSON.parse(text);
226
+ } catch (e) {
227
+ console.error('Failed to parse WebSocket message:', e.message);
228
+ return;
229
+ }
230
+ touchActivity();
231
+ console.log(JSON.stringify({ source: 'user-event', ...event }));
232
+ if (event.choice) {
233
+ const eventsFile = path.join(SCREEN_DIR, '.events');
234
+ fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
235
+ }
236
+ }
237
+
238
+ function broadcast(msg) {
239
+ const frame = encodeFrame(OPCODES.TEXT, Buffer.from(JSON.stringify(msg)));
240
+ for (const socket of clients) {
241
+ try { socket.write(frame); } catch (e) { clients.delete(socket); }
242
+ }
243
+ }
244
+
245
+ // ========== Activity Tracking ==========
246
+
247
+ const IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
248
+ let lastActivity = Date.now();
249
+
250
+ function touchActivity() {
251
+ lastActivity = Date.now();
252
+ }
253
+
254
+ // ========== File Watching ==========
255
+
256
+ const debounceTimers = new Map();
257
+
258
+ // ========== Server Startup ==========
259
+
260
+ function startServer() {
261
+ if (!fs.existsSync(SCREEN_DIR)) fs.mkdirSync(SCREEN_DIR, { recursive: true });
262
+
263
+ // Track known files to distinguish new screens from updates.
264
+ // macOS fs.watch reports 'rename' for both new files and overwrites,
265
+ // so we can't rely on eventType alone.
266
+ const knownFiles = new Set(
267
+ fs.readdirSync(SCREEN_DIR).filter(f => f.endsWith('.html'))
268
+ );
269
+
270
+ const server = http.createServer(handleRequest);
271
+ server.on('upgrade', handleUpgrade);
272
+
273
+ const watcher = fs.watch(SCREEN_DIR, (eventType, filename) => {
274
+ if (!filename || !filename.endsWith('.html')) return;
275
+
276
+ if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename));
277
+ debounceTimers.set(filename, setTimeout(() => {
278
+ debounceTimers.delete(filename);
279
+ const filePath = path.join(SCREEN_DIR, filename);
280
+
281
+ if (!fs.existsSync(filePath)) return; // file was deleted
282
+ touchActivity();
283
+
284
+ if (!knownFiles.has(filename)) {
285
+ knownFiles.add(filename);
286
+ const eventsFile = path.join(SCREEN_DIR, '.events');
287
+ if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
288
+ console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
289
+ } else {
290
+ console.log(JSON.stringify({ type: 'screen-updated', file: filePath }));
291
+ }
292
+
293
+ broadcast({ type: 'reload' });
294
+ }, 100));
295
+ });
296
+ watcher.on('error', (err) => console.error('fs.watch error:', err.message));
297
+
298
+ function shutdown(reason) {
299
+ console.log(JSON.stringify({ type: 'server-stopped', reason }));
300
+ const infoFile = path.join(SCREEN_DIR, '.server-info');
301
+ if (fs.existsSync(infoFile)) fs.unlinkSync(infoFile);
302
+ fs.writeFileSync(
303
+ path.join(SCREEN_DIR, '.server-stopped'),
304
+ JSON.stringify({ reason, timestamp: Date.now() }) + '\n'
305
+ );
306
+ watcher.close();
307
+ clearInterval(lifecycleCheck);
308
+ server.close(() => process.exit(0));
309
+ }
310
+
311
+ function ownerAlive() {
312
+ if (!OWNER_PID) return true;
313
+ try { process.kill(OWNER_PID, 0); return true; } catch (e) { return false; }
314
+ }
315
+
316
+ // Check every 60s: exit if owner process died or idle for 30 minutes
317
+ const lifecycleCheck = setInterval(() => {
318
+ if (!ownerAlive()) shutdown('owner process exited');
319
+ else if (Date.now() - lastActivity > IDLE_TIMEOUT_MS) shutdown('idle timeout');
320
+ }, 60 * 1000);
321
+ lifecycleCheck.unref();
322
+
323
+ server.listen(PORT, HOST, () => {
324
+ const info = JSON.stringify({
325
+ type: 'server-started', port: Number(PORT), host: HOST,
326
+ url_host: URL_HOST, url: 'http://' + URL_HOST + ':' + PORT,
327
+ screen_dir: SCREEN_DIR
328
+ });
329
+ console.log(info);
330
+ fs.writeFileSync(path.join(SCREEN_DIR, '.server-info'), info + '\n');
331
+ });
332
+ }
333
+
334
+ if (require.main === module) {
335
+ startServer();
336
+ }
337
+
338
+ module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };