specbox 6.29.1 → 6.30.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -3
- package/bin/specbox.mjs +38 -2
- package/hooks/app-docs-sync-guard.mjs +326 -0
- package/hooks/branch-guard.mjs +79 -0
- package/hooks/checkpoint-freshness-guard.mjs +56 -0
- package/hooks/commit-spec-guard.mjs +61 -0
- package/hooks/context-budget-guard.mjs +130 -0
- package/hooks/design-gate.mjs +144 -0
- package/hooks/design-review-gate.mjs +102 -0
- package/hooks/design-system-gate.mjs +134 -0
- package/hooks/e2e-gate.mjs +86 -0
- package/hooks/file-ownership-guard.mjs +163 -0
- package/hooks/freeform-fragment.mjs +160 -0
- package/hooks/freeform-path-guard.mjs +172 -0
- package/hooks/healing-budget-guard.mjs +83 -0
- package/hooks/hooks-history.json +176 -0
- package/hooks/hooks-manifest.json +51 -0
- package/hooks/implement-checkpoint.mjs +46 -0
- package/hooks/implement-healing.mjs +38 -0
- package/hooks/lib/autopilot.mjs +240 -0
- package/hooks/lib/config.mjs +117 -0
- package/hooks/lib/decisiones.mjs +58 -0
- package/hooks/lib/design-gaps.mjs +272 -0
- package/hooks/lib/execution-context.mjs +69 -0
- package/hooks/lib/freeform-fragment.mjs +379 -0
- package/hooks/lib/freeform-path.mjs +115 -0
- package/hooks/lib/handoff-builder.mjs +388 -0
- package/hooks/lib/heartbeat-send.mjs +91 -0
- package/hooks/lib/heartbeat.mjs +110 -0
- package/hooks/lib/mcp-client-io.mjs +210 -0
- package/hooks/lib/mcp-client.mjs +91 -0
- package/hooks/lib/native-reservation-revalidate.mjs +80 -0
- package/hooks/lib/output.mjs +70 -0
- package/hooks/lib/ownership-map.mjs +162 -0
- package/hooks/lib/token-counter.mjs +81 -0
- package/hooks/lib/utils.mjs +235 -0
- package/hooks/no-bypass-guard.mjs +57 -0
- package/hooks/on-session-end.mjs +163 -0
- package/hooks/pipeline-phase-guard.mjs +140 -0
- package/hooks/post-implement-validate.mjs +61 -0
- package/hooks/pre-commit-lint.mjs +76 -0
- package/hooks/pre-prd-discovery-check.mjs +242 -0
- package/hooks/pre-read-budget-guard.mjs +83 -0
- package/hooks/quality-first-guard.mjs +85 -0
- package/hooks/read-tracker.mjs +33 -0
- package/hooks/session-heartbeat.mjs +113 -0
- package/hooks/session-start.mjs +159 -0
- package/hooks/settings-hooks.json +363 -0
- package/hooks/spec-guard.mjs +152 -0
- package/hooks/stripe-safety-guard.mjs +262 -0
- package/hooks/uc-lifecycle-guard.mjs +87 -0
- package/lib/hooks.mjs +156 -0
- package/lib/install.mjs +9 -0
- package/lib/internal.mjs +26 -3
- package/lib/mcp-headers.mjs +31 -3
- package/lib/messages.mjs +41 -0
- package/package.json +5 -3
|
@@ -0,0 +1,379 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/freeform-fragment.mjs — FreeForm with the remote MCP, in fragments (UC-11103, UC-11102).
|
|
3
|
+
*
|
|
4
|
+
* In content mode every SpecBox tool used to travel with the whole
|
|
5
|
+
* doc/tracking/items.json, written by the model and returned whole: ~103 KB
|
|
6
|
+
* per call on a 134-item board. The freeform-fragment hook sends instead the
|
|
7
|
+
* items the tool needs plus the highest US/UC/EP number of the whole board
|
|
8
|
+
* (`specbox-freeform-fragment/1`), and merges what comes back into items.json.
|
|
9
|
+
*
|
|
10
|
+
* Pure functions (tested with node:test) plus a tiny file lock. A tool enters
|
|
11
|
+
* FRAGMENT_TOOLS only with its equivalence test (tests/test_freeform_fragment_equivalence.py):
|
|
12
|
+
* same answer and same board as with the whole items.json.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
|
|
16
|
+
import { dirname, join } from 'node:path';
|
|
17
|
+
|
|
18
|
+
export const FRAGMENT_FORMAT = 'specbox-freeform-fragment/1';
|
|
19
|
+
|
|
20
|
+
/** The SpecBox tools that take the FreeForm board as `items_content` (server registry, checked by a test). */
|
|
21
|
+
export const CONTENT_TOOLS = new Set([
|
|
22
|
+
'add_ac', 'add_epic', 'add_uc', 'attach_evidence', 'bulk_update_hours_from_description', 'complete_uc',
|
|
23
|
+
'delete_ac', 'delete_epic', 'delete_uc', 'estimate_from_ac', 'find_next_uc', 'get_ac_status',
|
|
24
|
+
'get_board_status', 'get_cross_repo_dependencies', 'get_delivery_report', 'get_epic', 'get_evidence',
|
|
25
|
+
'get_satellite_queue', 'get_sprint_status', 'get_uc', 'get_us', 'get_us_progress', 'import_spec',
|
|
26
|
+
'link_uc_parent', 'list_epics', 'list_uc', 'list_us', 'mark_ac', 'mark_ac_batch', 'move_uc', 'move_us',
|
|
27
|
+
'set_ac_internal', 'set_ac_metadata', 'set_auth_token_placeholder', 'set_uc_satellite', 'set_us_epic',
|
|
28
|
+
'setup_board', 'start_uc', 'sync_multirepo_state', 'update_ac', 'update_ac_batch', 'update_epic',
|
|
29
|
+
'update_uc', 'update_uc_batch', 'update_us', 'validate_ac_quality',
|
|
30
|
+
].filter((t) => t !== 'set_auth_token_placeholder'));
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* What each tool needs. `uc`: the UC, its criteria and, as context, its story;
|
|
34
|
+
* `uc+siblings`: also the story's other UCs as context (a story's state is
|
|
35
|
+
* derived from all of them); `story`: the story, its UCs and their criteria;
|
|
36
|
+
* `parent-story`: only the story, as context; `epics`: every epic; `spec`: what
|
|
37
|
+
* an import_spec names. Any other tool gets the whole board, as before.
|
|
38
|
+
*/
|
|
39
|
+
export const FRAGMENT_TOOLS = {
|
|
40
|
+
add_uc: 'parent-story',
|
|
41
|
+
add_ac: 'uc',
|
|
42
|
+
update_ac: 'uc',
|
|
43
|
+
delete_ac: 'uc',
|
|
44
|
+
set_ac_metadata: 'uc',
|
|
45
|
+
set_ac_internal: 'uc',
|
|
46
|
+
get_ac_status: 'uc',
|
|
47
|
+
get_uc: 'uc+siblings',
|
|
48
|
+
start_uc: 'uc+siblings',
|
|
49
|
+
mark_ac: 'uc+siblings',
|
|
50
|
+
mark_ac_batch: 'uc+siblings',
|
|
51
|
+
update_uc: 'uc+siblings',
|
|
52
|
+
set_uc_satellite: 'uc+siblings',
|
|
53
|
+
move_uc: 'uc+siblings',
|
|
54
|
+
complete_uc: 'uc+siblings',
|
|
55
|
+
get_us: 'story',
|
|
56
|
+
move_us: 'story',
|
|
57
|
+
update_us: 'story',
|
|
58
|
+
import_spec: 'spec',
|
|
59
|
+
add_epic: 'epics',
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
/** Calls that take the next number of a kind: an in-flight one reserves it (parallel calls). */
|
|
63
|
+
const RESERVES = { add_uc: 'UC', add_epic: 'EP' };
|
|
64
|
+
|
|
65
|
+
const KINDS = ['US', 'UC', 'EP'];
|
|
66
|
+
const CONTEXT_META_KEYS = ['context', 'comments', 'attachments'];
|
|
67
|
+
const PENDING_TTL_MS = 60 * 60 * 1000;
|
|
68
|
+
|
|
69
|
+
// ── Reading items ──────────────────────────────────────────────────────
|
|
70
|
+
|
|
71
|
+
export function parseToolName(name) {
|
|
72
|
+
const m = /^mcp__(.+?)__([a-z_]+)$/.exec(name || '');
|
|
73
|
+
if (!m || !/specbox/i.test(m[1])) return null;
|
|
74
|
+
return { server: m[1], tool: m[2] };
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function has(item, label) {
|
|
78
|
+
return Array.isArray(item?.labels) && item.labels.includes(label);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** The US-/UC-/AC-/EP- id of an item, or null. */
|
|
82
|
+
export function logicalId(item, kind) {
|
|
83
|
+
if (!has(item, kind)) return null;
|
|
84
|
+
if (kind === 'EP') return typeof item.id === 'string' ? item.id : null;
|
|
85
|
+
const fromMeta = item.meta?.[`${kind.toLowerCase()}_id`];
|
|
86
|
+
if (typeof fromMeta === 'string' && fromMeta) return fromMeta;
|
|
87
|
+
const m = new RegExp(`^\\[?(${kind}-\\d+[a-z]?)`).exec(item.name || '');
|
|
88
|
+
return m ? m[1] : null;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function idNumber(id, kind) {
|
|
92
|
+
const m = new RegExp(`^${kind}-(\\d+)`).exec(id || '');
|
|
93
|
+
return m ? Number(m[1]) : 0;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** Highest US/UC/EP number on a board. */
|
|
97
|
+
export function maxIds(items) {
|
|
98
|
+
const out = { US: 0, UC: 0, EP: 0 };
|
|
99
|
+
for (const item of items) {
|
|
100
|
+
for (const kind of KINDS) out[kind] = Math.max(out[kind], idNumber(logicalId(item, kind), kind));
|
|
101
|
+
}
|
|
102
|
+
return out;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
// ── Choosing the fragment ──────────────────────────────────────────────
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* `{full, context}` (sets of item ids) for a tool call, or null when the tool
|
|
109
|
+
* gets the whole board.
|
|
110
|
+
*/
|
|
111
|
+
export function selectFragment(tool, args, items) {
|
|
112
|
+
const shape = FRAGMENT_TOOLS[tool];
|
|
113
|
+
if (!shape) return null;
|
|
114
|
+
const full = new Set();
|
|
115
|
+
const context = new Set();
|
|
116
|
+
const byId = new Map(items.map((i) => [i.id, i]));
|
|
117
|
+
const withId = (kind, id) => items.filter((i) => logicalId(i, kind) === id);
|
|
118
|
+
const children = (parentId, label) => items.filter((i) => i.parent_id === parentId && has(i, label));
|
|
119
|
+
const addUc = (uc) => {
|
|
120
|
+
full.add(uc.id);
|
|
121
|
+
for (const ac of children(uc.id, 'AC')) full.add(ac.id);
|
|
122
|
+
};
|
|
123
|
+
const addStory = (us) => {
|
|
124
|
+
full.add(us.id);
|
|
125
|
+
for (const uc of children(us.id, 'UC')) addUc(uc);
|
|
126
|
+
};
|
|
127
|
+
|
|
128
|
+
if (shape === 'parent-story') {
|
|
129
|
+
for (const us of withId('US', args.us_id)) context.add(us.id);
|
|
130
|
+
} else if (shape === 'uc' || shape === 'uc+siblings') {
|
|
131
|
+
for (const uc of withId('UC', args.uc_id)) {
|
|
132
|
+
addUc(uc);
|
|
133
|
+
const story = byId.get(uc.parent_id);
|
|
134
|
+
if (!story) continue;
|
|
135
|
+
context.add(story.id);
|
|
136
|
+
if (shape === 'uc+siblings') for (const sibling of children(story.id, 'UC')) context.add(sibling.id);
|
|
137
|
+
}
|
|
138
|
+
} else if (shape === 'story') {
|
|
139
|
+
for (const us of withId('US', args.us_id)) addStory(us);
|
|
140
|
+
} else if (shape === 'epics') {
|
|
141
|
+
for (const ep of items.filter((i) => has(i, 'EP'))) full.add(ep.id);
|
|
142
|
+
} else if (shape === 'spec') {
|
|
143
|
+
const spec = typeof args.spec === 'string' ? safeJson(args.spec) : args.spec;
|
|
144
|
+
for (const us of spec?.user_stories ?? []) {
|
|
145
|
+
for (const item of withId('US', us?.us_id)) addStory(item);
|
|
146
|
+
for (const uc of us?.use_cases ?? []) {
|
|
147
|
+
for (const item of withId('UC', uc?.uc_id)) {
|
|
148
|
+
addUc(item);
|
|
149
|
+
const story = byId.get(item.parent_id);
|
|
150
|
+
if (story) addStory(story);
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
for (const ep of items.filter((i) => has(i, 'EP'))) full.add(ep.id);
|
|
155
|
+
}
|
|
156
|
+
for (const id of full) context.delete(id);
|
|
157
|
+
return { full, context };
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
function safeJson(text) {
|
|
161
|
+
try {
|
|
162
|
+
return JSON.parse(text);
|
|
163
|
+
} catch {
|
|
164
|
+
return null;
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/** A context item travels without what no fragment tool reads (description, long meta). */
|
|
169
|
+
export function asContext(item) {
|
|
170
|
+
const { description: _description, ...rest } = item;
|
|
171
|
+
if (rest.meta && typeof rest.meta === 'object') {
|
|
172
|
+
const meta = { ...rest.meta };
|
|
173
|
+
for (const key of CONTEXT_META_KEYS) delete meta[key];
|
|
174
|
+
rest.meta = meta;
|
|
175
|
+
}
|
|
176
|
+
return rest;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* The `items_content` to send and what to remember for the merge.
|
|
181
|
+
* `reserved`: the numbers in-flight calls already took ({UC: [..], EP: [..]}).
|
|
182
|
+
*/
|
|
183
|
+
export function buildItemsContent({ tool, args, items, raw, reserved = {} }) {
|
|
184
|
+
const selection = selectFragment(tool, args, items);
|
|
185
|
+
if (!selection) return { itemsContent: raw, sent: items, whole: true, reserves: {} };
|
|
186
|
+
const sent = items
|
|
187
|
+
.filter((i) => selection.full.has(i.id) || selection.context.has(i.id))
|
|
188
|
+
.map((i) => (selection.full.has(i.id) ? i : asContext(i)));
|
|
189
|
+
const max = maxIds(items);
|
|
190
|
+
for (const kind of KINDS) for (const n of reserved[kind] ?? []) max[kind] = Math.max(max[kind], n);
|
|
191
|
+
const reserves = RESERVES[tool] ? { [RESERVES[tool]]: max[RESERVES[tool]] + 1 } : {};
|
|
192
|
+
const itemsContent = JSON.stringify({ format: FRAGMENT_FORMAT, max_ids: max, items: sent });
|
|
193
|
+
return { itemsContent, sent, whole: false, reserves };
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
// ── Merging what comes back ────────────────────────────────────────────
|
|
197
|
+
|
|
198
|
+
function canonical(value) {
|
|
199
|
+
if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
|
|
200
|
+
if (value && typeof value === 'object') {
|
|
201
|
+
return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
|
|
202
|
+
}
|
|
203
|
+
return JSON.stringify(value);
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
function same(a, b) {
|
|
207
|
+
return canonical(a) === canonical(b);
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
function applyChanges(local, before, after) {
|
|
211
|
+
const result = { ...local };
|
|
212
|
+
for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
|
|
213
|
+
if (key === 'meta') continue;
|
|
214
|
+
if (!(key in after)) delete result[key];
|
|
215
|
+
else if (!(key in before) || !same(before[key], after[key])) result[key] = after[key];
|
|
216
|
+
}
|
|
217
|
+
if ('meta' in before || 'meta' in after) {
|
|
218
|
+
const b = before.meta ?? {};
|
|
219
|
+
const a = after.meta ?? {};
|
|
220
|
+
const meta = { ...(local.meta ?? {}) };
|
|
221
|
+
for (const key of new Set([...Object.keys(b), ...Object.keys(a)])) {
|
|
222
|
+
if (!(key in a)) delete meta[key];
|
|
223
|
+
else if (!(key in b) || !same(b[key], a[key])) meta[key] = a[key];
|
|
224
|
+
}
|
|
225
|
+
result.meta = meta;
|
|
226
|
+
}
|
|
227
|
+
return result;
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
/**
|
|
231
|
+
* The local board after a call: each field the tool changed (compared with
|
|
232
|
+
* what was sent) is written, items the tool removed are removed, new items are
|
|
233
|
+
* added at the end. Fields that did not travel (a context item's description)
|
|
234
|
+
* and items that did not travel stay as they are locally.
|
|
235
|
+
*/
|
|
236
|
+
export function mergeFragment(local, sent, returned) {
|
|
237
|
+
const sentById = new Map(sent.map((i) => [i.id, i]));
|
|
238
|
+
const returnedById = new Map(returned.map((i) => [i.id, i]));
|
|
239
|
+
const localIds = new Set();
|
|
240
|
+
const out = [];
|
|
241
|
+
for (const item of local) {
|
|
242
|
+
localIds.add(item.id);
|
|
243
|
+
if (!sentById.has(item.id)) {
|
|
244
|
+
out.push(item);
|
|
245
|
+
continue;
|
|
246
|
+
}
|
|
247
|
+
const after = returnedById.get(item.id);
|
|
248
|
+
if (after) out.push(applyChanges(item, sentById.get(item.id), after));
|
|
249
|
+
}
|
|
250
|
+
for (const item of returned) {
|
|
251
|
+
if (!sentById.has(item.id) && !localIds.has(item.id)) out.push(item);
|
|
252
|
+
}
|
|
253
|
+
return out;
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
// ── The tool's answer ──────────────────────────────────────────────────
|
|
257
|
+
|
|
258
|
+
/** The `items_content` string inside an MCP tool response, whatever its shape. */
|
|
259
|
+
export function extractItemsContent(response, depth = 0) {
|
|
260
|
+
if (depth > 6 || response == null) return null;
|
|
261
|
+
if (typeof response === 'string') {
|
|
262
|
+
const text = response.trim();
|
|
263
|
+
return text.startsWith('{') ? extractItemsContent(safeJson(text), depth + 1) : null;
|
|
264
|
+
}
|
|
265
|
+
if (Array.isArray(response)) {
|
|
266
|
+
for (const part of response) {
|
|
267
|
+
const found = extractItemsContent(part, depth + 1);
|
|
268
|
+
if (found != null) return found;
|
|
269
|
+
}
|
|
270
|
+
return null;
|
|
271
|
+
}
|
|
272
|
+
if (typeof response === 'object') {
|
|
273
|
+
if (typeof response.items_content === 'string') return response.items_content;
|
|
274
|
+
for (const value of Object.values(response)) {
|
|
275
|
+
const found = extractItemsContent(value, depth + 1);
|
|
276
|
+
if (found != null) return found;
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
return null;
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/** The same response without any `items_content` (what the model needs to see). */
|
|
283
|
+
export function withoutItemsContent(response, depth = 0) {
|
|
284
|
+
if (depth > 6 || response == null) return response;
|
|
285
|
+
if (typeof response === 'string') {
|
|
286
|
+
const text = response.trim();
|
|
287
|
+
if (!text.startsWith('{')) return response;
|
|
288
|
+
const parsed = safeJson(text);
|
|
289
|
+
if (parsed == null || extractItemsContent(parsed) == null) return response;
|
|
290
|
+
return JSON.stringify(withoutItemsContent(parsed, depth + 1));
|
|
291
|
+
}
|
|
292
|
+
if (Array.isArray(response)) return response.map((part) => withoutItemsContent(part, depth + 1));
|
|
293
|
+
if (typeof response === 'object') {
|
|
294
|
+
const out = {};
|
|
295
|
+
for (const [key, value] of Object.entries(response)) {
|
|
296
|
+
if (key === 'items_content') continue;
|
|
297
|
+
out[key] = withoutItemsContent(value, depth + 1);
|
|
298
|
+
}
|
|
299
|
+
return out;
|
|
300
|
+
}
|
|
301
|
+
return response;
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
// ── Files: pending calls, the lock and atomic writes ───────────────────
|
|
305
|
+
|
|
306
|
+
function sleep(ms) {
|
|
307
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
/** Run `fn` holding `<dir>/.lock` (a directory: mkdir is atomic). A lock older than 30 s is stale. */
|
|
311
|
+
export function withLock(dir, fn, { timeoutMs = 10_000, staleMs = 30_000 } = {}) {
|
|
312
|
+
mkdirSync(dir, { recursive: true });
|
|
313
|
+
const lock = join(dir, '.lock');
|
|
314
|
+
const deadline = Date.now() + timeoutMs;
|
|
315
|
+
for (;;) {
|
|
316
|
+
try {
|
|
317
|
+
mkdirSync(lock);
|
|
318
|
+
break;
|
|
319
|
+
} catch (err) {
|
|
320
|
+
if (err.code !== 'EEXIST') throw err;
|
|
321
|
+
try {
|
|
322
|
+
if (Date.now() - statSync(lock).mtimeMs > staleMs) rmSync(lock, { recursive: true, force: true });
|
|
323
|
+
} catch {
|
|
324
|
+
// gone in between: try again
|
|
325
|
+
}
|
|
326
|
+
if (Date.now() > deadline) throw new Error(`freeform-fragment: could not take ${lock}`);
|
|
327
|
+
sleep(25);
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
try {
|
|
331
|
+
return fn();
|
|
332
|
+
} finally {
|
|
333
|
+
rmSync(lock, { recursive: true, force: true });
|
|
334
|
+
}
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
export function writeAtomic(path, content) {
|
|
338
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
339
|
+
const tmp = `${path}.${process.pid}.tmp`;
|
|
340
|
+
writeFileSync(tmp, content, 'utf-8');
|
|
341
|
+
renameSync(tmp, path);
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
export function pendingPath(dir, toolUseId) {
|
|
345
|
+
return join(dir, `${String(toolUseId).replace(/[^A-Za-z0-9_-]/g, '_')}.json`);
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
/** The numbers reserved by calls still in flight; drops pending files older than an hour. */
|
|
349
|
+
export function reservedNumbers(dir, now = Date.now()) {
|
|
350
|
+
const reserved = { UC: [], EP: [] };
|
|
351
|
+
let names = [];
|
|
352
|
+
try {
|
|
353
|
+
names = readdirSync(dir).filter((n) => n.endsWith('.json'));
|
|
354
|
+
} catch {
|
|
355
|
+
return reserved;
|
|
356
|
+
}
|
|
357
|
+
for (const name of names) {
|
|
358
|
+
const path = join(dir, name);
|
|
359
|
+
const pending = safeJson(readOrNull(path));
|
|
360
|
+
if (!pending || now - Date.parse(pending.created_at || 0) > PENDING_TTL_MS) {
|
|
361
|
+
try {
|
|
362
|
+
unlinkSync(path);
|
|
363
|
+
} catch {
|
|
364
|
+
// already gone
|
|
365
|
+
}
|
|
366
|
+
continue;
|
|
367
|
+
}
|
|
368
|
+
for (const [kind, n] of Object.entries(pending.reserves ?? {})) reserved[kind]?.push(n);
|
|
369
|
+
}
|
|
370
|
+
return reserved;
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
function readOrNull(path) {
|
|
374
|
+
try {
|
|
375
|
+
return readFileSync(path, 'utf-8');
|
|
376
|
+
} catch {
|
|
377
|
+
return null;
|
|
378
|
+
}
|
|
379
|
+
}
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/freeform-path.mjs — Resolve FreeForm root paths client-side.
|
|
3
|
+
*
|
|
4
|
+
* The MCP server may be remote (an http entry or an mcp-remote bridge in the
|
|
5
|
+
* Claude Code config, or env SPECBOX_ENGINE_MCP_URL set), in which case it has
|
|
6
|
+
* no access to the client's files and the board travels as items_content. With
|
|
7
|
+
* a local server, this helper builds an absolute path from the git toplevel of
|
|
8
|
+
* the calling client, so set_auth_token always receives a path the MCP can
|
|
9
|
+
* write to deterministically.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import { isAbsolute, join } from 'path';
|
|
13
|
+
import { execSync } from 'child_process';
|
|
14
|
+
import { readFileSync } from 'fs';
|
|
15
|
+
import { homedir } from 'os';
|
|
16
|
+
|
|
17
|
+
/** The server name the hooks match on (`mcp__SpecBox-MCP__…`). */
|
|
18
|
+
export const SPECBOX_SERVER = 'SpecBox-MCP';
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Resolve a FreeForm root path to an absolute path on the client filesystem.
|
|
22
|
+
*
|
|
23
|
+
* @param {string} relativeOrAbsolute - Path string. If already absolute,
|
|
24
|
+
* returned unchanged. If relative, joined onto the git toplevel of the CWD.
|
|
25
|
+
* @param {object} [opts]
|
|
26
|
+
* @param {string} [opts.cwd] - Override CWD (default: process.cwd()). Useful
|
|
27
|
+
* for tests; production callers don't pass this.
|
|
28
|
+
* @returns {string} Absolute path safe to pass to set_auth_token.
|
|
29
|
+
* @throws {Error} If relative and no git repo is detected at CWD.
|
|
30
|
+
*/
|
|
31
|
+
export function resolveFreeformPath(relativeOrAbsolute, opts = {}) {
|
|
32
|
+
if (typeof relativeOrAbsolute !== 'string' || relativeOrAbsolute.length === 0) {
|
|
33
|
+
throw new Error('resolveFreeformPath: input must be a non-empty string');
|
|
34
|
+
}
|
|
35
|
+
if (isAbsolute(relativeOrAbsolute)) {
|
|
36
|
+
return relativeOrAbsolute;
|
|
37
|
+
}
|
|
38
|
+
const cwd = opts.cwd || process.cwd();
|
|
39
|
+
let toplevel;
|
|
40
|
+
try {
|
|
41
|
+
toplevel = execSync('git rev-parse --show-toplevel', {
|
|
42
|
+
cwd,
|
|
43
|
+
encoding: 'utf-8',
|
|
44
|
+
stdio: ['ignore', 'pipe', 'ignore'],
|
|
45
|
+
}).trim();
|
|
46
|
+
} catch {
|
|
47
|
+
throw new Error(
|
|
48
|
+
`resolveFreeformPath: cannot resolve relative path ${JSON.stringify(relativeOrAbsolute)} `
|
|
49
|
+
+ 'because no git repository was found at the CWD. Pass an absolute '
|
|
50
|
+
+ 'path or invoke from inside a git repo.'
|
|
51
|
+
);
|
|
52
|
+
}
|
|
53
|
+
return join(toplevel, relativeOrAbsolute);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function readJson(path) {
|
|
57
|
+
try {
|
|
58
|
+
return JSON.parse(readFileSync(path, 'utf-8'));
|
|
59
|
+
} catch {
|
|
60
|
+
return null;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function gitToplevel(cwd) {
|
|
65
|
+
try {
|
|
66
|
+
return execSync('git rev-parse --show-toplevel', {
|
|
67
|
+
cwd,
|
|
68
|
+
encoding: 'utf-8',
|
|
69
|
+
stdio: ['ignore', 'pipe', 'ignore'],
|
|
70
|
+
}).trim();
|
|
71
|
+
} catch {
|
|
72
|
+
return null;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* The SpecBox-MCP entry Claude Code uses for this project, with its precedence:
|
|
78
|
+
* local scope (~/.claude.json → projects[<root>]), then project scope (<root>/.mcp.json),
|
|
79
|
+
* then user scope (~/.claude.json). null when none declares it.
|
|
80
|
+
*/
|
|
81
|
+
export function specboxServerEntry({ cwd = process.cwd(), home = homedir() } = {}) {
|
|
82
|
+
const root = gitToplevel(cwd) || cwd;
|
|
83
|
+
const claude = readJson(join(home, '.claude.json')) || {};
|
|
84
|
+
const candidates = [
|
|
85
|
+
claude.projects?.[root]?.mcpServers,
|
|
86
|
+
readJson(join(root, '.mcp.json'))?.mcpServers,
|
|
87
|
+
claude.mcpServers,
|
|
88
|
+
];
|
|
89
|
+
for (const servers of candidates) {
|
|
90
|
+
if (servers?.[SPECBOX_SERVER]) return servers[SPECBOX_SERVER];
|
|
91
|
+
}
|
|
92
|
+
return null;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** An MCP entry that reaches a server over the network: http/sse, or a bridge such as mcp-remote. */
|
|
96
|
+
export function isRemoteEntry(entry) {
|
|
97
|
+
if (!entry || typeof entry !== 'object') return false;
|
|
98
|
+
if (['http', 'sse', 'streamable-http'].includes(entry.type) || entry.url) return true;
|
|
99
|
+
const args = Array.isArray(entry.args) ? entry.args.map(String) : [];
|
|
100
|
+
return args.includes('mcp-remote') || args.some((a) => /^https?:\/\//.test(a));
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Whether the current Claude Code session is talking to a remote MCP server.
|
|
105
|
+
* Hooks and skills use this to decide whether set_auth_token may carry a
|
|
106
|
+
* FreeForm directory at all (a remote server has no access to it).
|
|
107
|
+
*
|
|
108
|
+
* UC-11101: SPECBOX_ENGINE_MCP_URL is only written by the VSCode extension, so
|
|
109
|
+
* a project onboarded any other way also looks at how Claude Code reaches the
|
|
110
|
+
* SpecBox-MCP server.
|
|
111
|
+
*/
|
|
112
|
+
export function isRemoteMcp({ env = process.env, cwd = process.cwd(), home = homedir() } = {}) {
|
|
113
|
+
if ((env.SPECBOX_ENGINE_MCP_URL || '').trim()) return true;
|
|
114
|
+
return isRemoteEntry(specboxServerEntry({ cwd, home }));
|
|
115
|
+
}
|