@marver-design/marver 0.22.1 → 0.23.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.
Files changed (61) hide show
  1. package/CHANGELOG.md +84 -0
  2. package/README.md +13 -9
  3. package/dist/agent-BsieQGTD.mjs +99 -0
  4. package/dist/{bake-CvY8QR3L.mjs → bake-l6N12qgx.mjs} +1 -1
  5. package/dist/{board-status-CWGHIdo_.mjs → board-status-D_lHZZ09.mjs} +69 -610
  6. package/dist/{boards-BwKI0qWd.mjs → boards-CahYhF5B.mjs} +2 -1
  7. package/dist/boards-DbVJlbd5.mjs +612 -0
  8. package/dist/{build-B1kavcpc.mjs → build-CuRhHXcY.mjs} +10 -6
  9. package/dist/cli.mjs +20 -11
  10. package/dist/{comments-ClVgfQib.mjs → comments-0d3e274b.mjs} +71 -9
  11. package/dist/{config-DJxMRVD8.mjs → config-g-J8NrPn.mjs} +5 -97
  12. package/dist/{context-D4t59wDi.mjs → context-fAtQLHt2.mjs} +3 -2
  13. package/dist/{daemon-PmNqoOAk.mjs → daemon-DZ367fiM.mjs} +75 -17
  14. package/dist/{dev-Cf4wLGe2.mjs → dev-R6zvwbqX.mjs} +50 -10
  15. package/dist/{init-C_K-cjBQ.mjs → init-DAnBlt-V.mjs} +4 -3
  16. package/dist/{ledger-Bu0BjqIe.mjs → ledger-BNXW14Xw.mjs} +1 -6
  17. package/dist/link-CcfAfKY-.mjs +132 -0
  18. package/dist/{manifest-CcdWx7ud.mjs → manifest-BkjJ5OQk.mjs} +50 -5
  19. package/dist/{plugin-C5u07Yhv.mjs → plugin-C1avHL7g.mjs} +357 -31
  20. package/dist/{poster-BduzQBYz.mjs → poster-Bc4-3DlQ.mjs} +1 -1
  21. package/dist/{profile-BjAPAJSb.mjs → profile-CrZohD6g.mjs} +1 -1
  22. package/dist/{publish-bakes-b0jUwvM_.mjs → publish-bakes-DQWn14IY.mjs} +2 -2
  23. package/dist/{share--bdSc4G5.mjs → share-BD-wcDQq.mjs} +1 -1
  24. package/dist/{shot-BFEuYbaz.mjs → shot-C1YR_Sqx.mjs} +1 -1
  25. package/dist/{shot-BAR8hmU9.mjs → shot-CVOlQHUr.mjs} +2 -2
  26. package/dist/{sync-BZaCWqK-.mjs → sync-DoA1vf4u.mjs} +15 -1
  27. package/dist/{work-0YopuMt9.mjs → work-CJ8OIpBD.mjs} +9 -3
  28. package/dist/{work-CLrmY-vQ.mjs → work-CiUvBVa6.mjs} +72 -1
  29. package/docs/boards-and-folders.md +54 -6
  30. package/docs/context.md +10 -2
  31. package/docs/live-jam.md +11 -0
  32. package/package.json +1 -1
  33. package/src/client/content/diagram.tsx +7 -1
  34. package/src/client/content/img-lod.ts +12 -2
  35. package/src/client/content/index.tsx +69 -6
  36. package/src/client/frame-host/inspect.js +23 -0
  37. package/src/client/shell/App.tsx +19 -9
  38. package/src/client/shell/BoardList.tsx +21 -6
  39. package/src/client/shell/LockedApp.tsx +2 -2
  40. package/src/client/shell/Play.tsx +5 -1
  41. package/src/client/shell/StatusPicker.tsx +12 -5
  42. package/src/client/shell/Tip.tsx +25 -5
  43. package/src/client/shell/board-icons.tsx +15 -1
  44. package/src/client/shell/canvas/Canvas.tsx +42 -6
  45. package/src/client/shell/canvas/anchor.ts +41 -0
  46. package/src/client/shell/canvas/ctl.ts +6 -0
  47. package/src/client/shell/comments-store.ts +8 -5
  48. package/src/client/shell/goto.ts +52 -3
  49. package/src/client/shell/hash.ts +24 -3
  50. package/src/client/shell/store.ts +242 -28
  51. package/src/client/shell/styles.css +19 -2
  52. package/src/shared/board-types.ts +10 -6
  53. package/src/shared/status.ts +17 -8
  54. package/templates/AGENTS-embedded.md +43 -8
  55. package/templates/AGENTS-studio.md +43 -8
  56. package/templates/instructions/boards.md +13 -3
  57. package/templates/instructions/context.md +6 -2
  58. package/templates/instructions/iterate.md +29 -16
  59. package/templates/instructions/jam.md +9 -2
  60. package/templates/instructions/reference/deck-layouts.md +2 -1
  61. package/templates/instructions/reference/deck-story.md +2 -1
@@ -1,609 +1,6 @@
1
- import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
2
- import { join, sep } from "node:path";
3
- import { createHash } from "node:crypto";
4
- //#region src/server/hash.ts
5
- /** sha256 hex of a string - the CAS token for board files, the registry, the manifest. */
6
- const hash = (s) => createHash("sha256").update(s).digest("hex");
7
- //#endregion
8
- //#region src/shared/board-types.ts
9
- /**
10
- * Board types (spec 20) - what a board is FOR in the workspace, one vocabulary every canvas
11
- * shares so any sidebar reads at a glance. A board states its own `"type"`, or wears the type of
12
- * the nearest typed folder above it (its folder, then that folder's parent), else it is plain.
13
- * Moving a board changes an inherited type, never one the board states itself.
14
- *
15
- * Pure and shared: the dev API, the manifest, the build, the shell and the CLI all read types
16
- * through here, so a type means one thing everywhere.
17
- */
18
- const BOARD_TYPES = [
19
- "start",
20
- "feature",
21
- "surface",
22
- "project",
23
- "feedback",
24
- "context",
25
- "deck",
26
- "archive"
27
- ];
28
- /** The grammar a stored type keeps to. Any on-grammar word survives a write - a newer Marver's
29
- * type is never dropped by an older shell - while only the known ones are drawn. */
30
- const TYPE_GRAMMAR = /^[a-z][a-z-]{0,31}$/;
31
- /** A type off a file: the word when it is on-grammar, else absent. */
32
- const readType = (v) => typeof v === "string" && TYPE_GRAMMAR.test(v) ? v : void 0;
33
- /** A type this Marver draws. */
34
- const knownType = (v) => BOARD_TYPES.includes(v) ? v : void 0;
35
- /** A board's type: its own when it states one (an unknown word reads as plain - the board spoke
36
- * for itself), else its folder's, else that folder's parent's, else plain. */
37
- function resolveType(own, folder, parent) {
38
- if (readType(own)) return knownType(own) ?? "plain";
39
- return knownType(folder) ?? knownType(parent) ?? "plain";
40
- }
41
- /** The publish type a board's type proposes when its publish row names none - how a board
42
- * PRESENTS when published, a separate question from what it is for. */
43
- const PROPOSED_PUBLISH = {
44
- deck: "slides",
45
- context: "refs",
46
- project: "doc",
47
- feature: "mix",
48
- surface: "mix"
49
- };
50
- /** The types that carry a status (spec 20, open question 2: features and projects - the others
51
- * have no lifecycle of their own). */
52
- const HAS_STATUS = ["feature", "project"];
53
- /** The decisions a board may state by hand. `done` is never one: Done comes only from the shipped
54
- * record. `todo`, `backlog` and `in-progress` count only where there is no `context/`. */
55
- const DECISIONS = [
56
- "archived",
57
- "paused",
58
- "blocked"
59
- ];
60
- const BY_HAND = [
61
- "in-progress",
62
- "todo",
63
- "backlog"
64
- ];
65
- const STATUS_WORDS = [
66
- ...DECISIONS,
67
- ...BY_HAND,
68
- "done"
69
- ];
70
- const readStatusWord = (v) => STATUS_WORDS.includes(v) ? v : void 0;
71
- /** The statuses a person may set on a feature or project board, in the order a picker lists them:
72
- * the three decisions always; Backlog, To do and In progress only where there is no `context/`
73
- * (with it they are read from the evidence). Never Done - that is the shipped record's alone. */
74
- const settableStatuses = (contextPresent) => contextPresent ? [
75
- "blocked",
76
- "paused",
77
- "archived"
78
- ] : [
79
- "backlog",
80
- "todo",
81
- "in-progress",
82
- "blocked",
83
- "paused",
84
- "archived"
85
- ];
86
- /** A capability slug - the same grammar as a board name, so a feature board and its contract
87
- * share it. */
88
- const readCapability = (v) => typeof v === "string" && /^[a-z0-9][a-z0-9-]{0,63}$/.test(v) ? v : void 0;
89
- const readReason = (v) => {
90
- if (typeof v !== "string") return void 0;
91
- return v.trim().replace(/\s+/g, " ").slice(0, 300) || void 0;
92
- };
93
- /** The sidebar every canvas shares (spec 19, The canvas): folder modules, each typed, so a board
94
- * made inside one wears its type. `marver init --kind` creates a kind's set on a fresh canvas;
95
- * `marver folders add <module>` adds one later. Names are slugs; only Start here needs a title. */
96
- const FOLDER_MODULES = {
97
- start: {
98
- name: "start-here",
99
- title: "Start here",
100
- type: "start"
101
- },
102
- features: {
103
- name: "features",
104
- type: "feature"
105
- },
106
- surfaces: {
107
- name: "surfaces",
108
- type: "surface"
109
- },
110
- projects: {
111
- name: "projects",
112
- type: "project"
113
- },
114
- feedback: {
115
- name: "feedback",
116
- type: "feedback"
117
- },
118
- context: {
119
- name: "context",
120
- type: "context"
121
- },
122
- decks: {
123
- name: "decks",
124
- type: "deck"
125
- },
126
- archive: {
127
- name: "archive",
128
- type: "archive"
129
- }
130
- };
131
- /** A kind of work's folders, in sidebar order: the core (Start here, Feedback, Context, Archive)
132
- * around the kind's own modules. Decks are an add-on for either. */
133
- const KIND_FOLDERS = {
134
- product: [
135
- "start",
136
- "features",
137
- "surfaces",
138
- "feedback",
139
- "context",
140
- "archive"
141
- ],
142
- knowledge: [
143
- "start",
144
- "projects",
145
- "feedback",
146
- "context",
147
- "archive"
148
- ]
149
- };
150
- //#endregion
151
- //#region src/shared/board-tree.ts
152
- /**
153
- * Board folders - the pure tree shared by the sidebar, the dev API, the build and the
154
- * tests. Files are the truth: a board says which folder it sits in (`folder` on the
155
- * board file - one slug, the folder it sits in directly), ranked among its siblings by
156
- * `order`, and `design/boards/_folders.json` says which folders exist, where they rank, and
157
- * which folder holds which (`parent`). Two levels: a folder holds boards and folders, a
158
- * folder inside a folder (a sub-folder) holds boards only. `all-scenes` never enters the
159
- * tree - callers pin it last.
160
- */
161
- /** The on-disk name grammar shared by boards and folders (a board name is a filename). */
162
- const BOARD_NAME = /^[a-z0-9][a-z0-9-]*$/;
163
- const isBoardName = (n) => typeof n === "string" && n.length >= 1 && n.length <= 64 && BOARD_NAME.test(n);
164
- /** The folder registry beside the boards - underscore = infrastructure, never a board. */
165
- const FOLDERS_FILE = "_folders.json";
166
- /** Is this basename in design/boards/ a board file? `_folders.json`, temp files and any
167
- * off-grammar name are not - every lister (dev API, build, watcher) shares this rule. */
168
- const isBoardFile = (f) => f.endsWith(".json") && isBoardName(f.slice(0, -5));
169
- const readDescription = (v) => {
170
- if (typeof v !== "string") return void 0;
171
- return v.trim().replace(/\s+/g, " ").slice(0, 300) || void 0;
172
- };
173
- const readTitle = (v) => {
174
- if (typeof v !== "string") return void 0;
175
- return Array.from(v.replace(/[\u0000-\u001f\u007f]/g, " ").trim().replace(/\s+/g, " ")).slice(0, 120).join("").trim() || void 0;
176
- };
177
- /** Title Case off a slug - the display when no title is set ("old-stuff" → "Old Stuff"). */
178
- const humanize = (s) => s.replace(/-/g, " ").replace(/(^|\s)\S/g, (c) => c.toUpperCase());
179
- const rank = (o) => typeof o === "number" && Number.isFinite(o) ? o : Infinity;
180
- /** A folder's title, description and type, present only when set. */
181
- const folderExtras = (it) => ({
182
- ...it.title ? { title: it.title } : {},
183
- ...it.description ? { description: it.description } : {},
184
- ...readType(it.type) ? { type: it.type } : {}
185
- });
186
- /** The registry file's shape. Returns the rows, or a string naming what is wrong - a
187
- * malformed registry is an ERROR the human must fix (silently reading it as empty, or
188
- * flattening a broken nesting, would let the next drag overwrite their folders), while a
189
- * missing file is simply no folders. */
190
- function parseFolders(raw) {
191
- if (!raw || typeof raw !== "object" || Array.isArray(raw)) return "expected an object";
192
- const { version, folders } = raw;
193
- if (version !== void 0 && version !== 1 && version !== 2) return `unsupported version ${String(version)}`;
194
- if (!Array.isArray(folders)) return "expected a \"folders\" array";
195
- const out = [];
196
- const seen = /* @__PURE__ */ new Set();
197
- for (const f of folders) {
198
- const name = f?.name;
199
- if (!isBoardName(name)) return "a folder needs a name - lowercase letters, numbers and dashes";
200
- if (seen.has(name)) return `folder "${name}" is listed twice`;
201
- seen.add(name);
202
- const o = f.order;
203
- const p = f.parent;
204
- if (p !== void 0 && !isBoardName(p)) return `folder "${name}" has an invalid parent - a folder name`;
205
- const t = readTitle(f.title);
206
- const d = readDescription(f.description);
207
- const ty = readType(f.type);
208
- out.push({
209
- name,
210
- ...typeof o === "number" && Number.isFinite(o) ? { order: o } : {},
211
- ...p !== void 0 ? { parent: p } : {},
212
- ...t ? { title: t } : {},
213
- ...d ? { description: d } : {},
214
- ...ty ? { type: ty } : {}
215
- });
216
- }
217
- const byName = new Map(out.map((f) => [f.name, f]));
218
- for (const f of out) {
219
- if (f.parent === void 0) continue;
220
- if (version !== 2) return `folder "${f.name}" names a parent - nested folders need "version": 2`;
221
- if (f.parent === f.name) return `folder "${f.name}" cannot be its own parent`;
222
- const p = byName.get(f.parent);
223
- if (!p) return `folder "${f.name}" names an unknown parent "${f.parent}"`;
224
- if (p.parent !== void 0) return `folder "${f.name}" would sit three levels deep - folders nest one level only`;
225
- }
226
- return out;
227
- }
228
- /** Sidebar order from the files. At every level the boards and folders there share one
229
- * sequence, ranked by `order`, then kind (board before folder), then name; unranked sorts
230
- * after ranked. The root holds root boards and top-level folders (registered without a
231
- * parent, or implied by a board that names an unregistered folder); a top-level folder holds
232
- * its boards and its sub-folders; a sub-folder holds its boards. A folder's title and
233
- * description and type ride on its item (they live in the registry a tree write rewrites); a board's
234
- * title stays with its row - it lives in the board's own file. */
235
- function buildTree(boards, folders) {
236
- const reg = /* @__PURE__ */ new Map();
237
- for (const f of folders) if (isBoardName(f.name) && !reg.has(f.name)) reg.set(f.name, f);
238
- const parentOf = (n) => {
239
- const p = reg.get(n)?.parent;
240
- return p !== void 0 && p !== n && reg.has(p) && reg.get(p).parent === void 0 ? p : void 0;
241
- };
242
- const members = /* @__PURE__ */ new Map();
243
- const implied = [];
244
- const rootBoards = [];
245
- for (const b of boards) {
246
- if (!isBoardName(b.name) || b.name === "all-scenes") continue;
247
- const folder = isBoardName(b.folder) ? b.folder : void 0;
248
- if (!folder) {
249
- rootBoards.push(b);
250
- continue;
251
- }
252
- if (!reg.has(folder) && !implied.includes(folder)) implied.push(folder);
253
- const list = members.get(folder) ?? [];
254
- list.push(b);
255
- members.set(folder, list);
256
- }
257
- const sorted = (xs) => xs.sort((a, b) => rank(a.order) - rank(b.order) || (a.item.kind === b.item.kind ? 0 : a.item.kind === "board" ? -1 : 1) || a.item.name.localeCompare(b.item.name)).map((r) => r.item);
258
- const boardsHere = (name) => (name === null ? rootBoards : members.get(name) ?? []).map((b) => ({
259
- item: {
260
- kind: "board",
261
- name: b.name
262
- },
263
- order: b.order
264
- }));
265
- const folder = (name, kids) => ({
266
- item: {
267
- kind: "folder",
268
- name,
269
- items: sorted(kids),
270
- ...folderExtras(reg.get(name) ?? {})
271
- },
272
- order: reg.get(name)?.order
273
- });
274
- const subsOf = (top) => [...reg.keys()].filter((n) => parentOf(n) === top);
275
- const tops = [...[...reg.keys()].filter((n) => !parentOf(n)), ...implied];
276
- return sorted([...boardsHere(null), ...tops.map((t) => folder(t, [...boardsHere(t), ...subsOf(t).map((s) => folder(s, boardsHere(s)))]))]);
277
- }
278
- /** Every board in reading order, depth-first - the order the switchers and the landing pick use. */
279
- function flatten(tree) {
280
- const out = [];
281
- const walk = (items) => {
282
- for (const it of items) if (it.kind === "board") out.push(it.name);
283
- else walk(it.items);
284
- };
285
- walk(tree);
286
- return out;
287
- }
288
- const wireKids = (w) => w.items ?? w.boards ?? [];
289
- function validateWire(wire) {
290
- if (!Array.isArray(wire)) return "invalid tree";
291
- const boards = /* @__PURE__ */ new Set(), folders = /* @__PURE__ */ new Set();
292
- const board = (n) => {
293
- if (!isBoardName(n) || n === "all-scenes") return "invalid board name in tree";
294
- if (boards.has(n)) return `board "${n}" appears twice`;
295
- boards.add(n);
296
- return null;
297
- };
298
- const walk = (list, depth) => {
299
- for (const w of list) {
300
- if (typeof w === "string") {
301
- const e = board(w);
302
- if (e) return e;
303
- continue;
304
- }
305
- if (!w || typeof w !== "object" || Array.isArray(w)) return "invalid tree item";
306
- if (depth >= 2) return "folders nest one level only";
307
- const { folder, items, boards: legacy, title, description, type } = w;
308
- if (!isBoardName(folder)) return "invalid folder name in tree";
309
- if (title !== void 0 && (typeof title !== "string" || Array.from(title).length > 120)) return "invalid folder title";
310
- if (description !== void 0 && (typeof description !== "string" || description.length > 300)) return "invalid folder description";
311
- if (type !== void 0 && !readType(type)) return "invalid folder type";
312
- if (folders.has(folder)) return `folder "${folder}" appears twice`;
313
- folders.add(folder);
314
- const kids = items ?? legacy;
315
- if (!Array.isArray(kids)) return "invalid folder in tree";
316
- if (items === void 0 && kids.some((k) => typeof k !== "string")) return "invalid folder in tree";
317
- const e = walk(kids, depth + 1);
318
- if (e) return e;
319
- }
320
- return null;
321
- };
322
- const e = walk(wire, 0);
323
- if (e) return e;
324
- if (boards.size > 200 || folders.size > 50) return "tree too large";
325
- return null;
326
- }
327
- /** Every folder with the folder it sits in (null = the root), top-level folders first in
328
- * reading order, each followed by its sub-folders. */
329
- function folderEntries(t) {
330
- const out = [];
331
- for (const it of t) {
332
- if (it.kind !== "folder") continue;
333
- out.push({
334
- folder: it,
335
- parent: null
336
- });
337
- for (const k of it.items) if (k.kind === "folder") out.push({
338
- folder: k,
339
- parent: it.name
340
- });
341
- }
342
- return out;
343
- }
344
- /** Every board's folder, in one pass - for callers that ask for many boards (folderOf walks the tree). */
345
- function folderMap(t) {
346
- const out = /* @__PURE__ */ new Map();
347
- for (const { folder } of folderEntries(t)) for (const k of folder.items) if (k.kind === "board") out.set(k.name, folder.name);
348
- return out;
349
- }
350
- //#endregion
351
- //#region src/server/boards.ts
352
- /**
353
- * Reading design/boards/ safely - the one enumerator the dev API, the build and the tests
354
- * share. Only REGULAR files on the board-name grammar count as boards (a symlink, dangling or
355
- * live, could read or publish JSON from outside the project - it is skipped, and reported so
356
- * the build can fail closed). The folder registry is read the same way: absent = no folders,
357
- * malformed = an error the human must fix, never a silently empty registry.
358
- */
359
- /** Does realpath(dir) stay inside realpath(root)? A symlinked design/boards can't escape. */
360
- function underRoot(root, dir) {
361
- try {
362
- const rr = realpathSync(root);
363
- const rd = realpathSync(dir);
364
- return rd === rr || rd.startsWith(rr + sep);
365
- } catch {
366
- return false;
367
- }
368
- }
369
- /** Is design/boards a directory we may read and write? It must not be a symlink at all (a
370
- * link to the repo root would list package.json as a board and let a tree write rewrite
371
- * it; a link outside would publish foreign JSON) and must resolve inside the root. Absent
372
- * is fine (no boards yet). Returns the error, or null. */
373
- function checkBoardsDir(root, boardsDir) {
374
- return checkRealDirs(root, [[join(boardsDir, ".."), "design"], [boardsDir, "design/boards"]]);
375
- }
376
- /** Every EXISTING path in `dirs` (root-down order) must be a real directory inside the root -
377
- * a symlinked `design` with no boards dir yet would otherwise be followed by the mkdir that
378
- * creates it; a symlinked `design/scenes` would let a brief write land outside the project.
379
- * An absent one ends the walk (nothing beneath it exists either). Returns the error, or null. */
380
- function checkRealDirs(root, dirs) {
381
- for (const [p, label] of dirs) {
382
- try {
383
- if (lstatSync(p).isSymbolicLink()) return `${label} must be a real directory, not a symlink`;
384
- } catch {
385
- return null;
386
- }
387
- if (!underRoot(root, p)) return `${label} escapes the project`;
388
- }
389
- return null;
390
- }
391
- /** A regular file (lstat: a symlink is never followed, a dangling one is not "absent"). */
392
- const isRegularFile = (p) => {
393
- try {
394
- return lstatSync(p).isFile();
395
- } catch {
396
- return false;
397
- }
398
- };
399
- /** Is there ANY node at p (a dangling symlink counts)? */
400
- const nodeExists = (p) => {
401
- try {
402
- lstatSync(p);
403
- return true;
404
- } catch {
405
- return false;
406
- }
407
- };
408
- /** Every board file: name, raw content, hash, and its JSON (null when malformed). `skipped`
409
- * names the entries that looked like boards but were not regular files. */
410
- function listBoardFiles(boardsDir) {
411
- const boards = [], skipped = [];
412
- if (!existsSync(boardsDir)) return {
413
- boards,
414
- skipped
415
- };
416
- for (const f of readdirSync(boardsDir)) {
417
- if (!isBoardFile(f)) continue;
418
- const file = join(boardsDir, f);
419
- if (!isRegularFile(file)) {
420
- skipped.push(f);
421
- continue;
422
- }
423
- const content = readFileSync(file, "utf8");
424
- let json = null;
425
- try {
426
- json = JSON.parse(content);
427
- } catch {}
428
- boards.push({
429
- name: f.slice(0, -5),
430
- file,
431
- content,
432
- sha256: hash(content),
433
- json
434
- });
435
- }
436
- return {
437
- boards,
438
- skipped
439
- };
440
- }
441
- function boardFields(json, validName) {
442
- const o = json;
443
- const title = readTitle(o?.title);
444
- const description = readDescription(o?.description);
445
- const type = readType(o?.type), capability = readCapability(o?.capability), status = readStatusWord(o?.status), reason = readReason(o?.reason);
446
- return {
447
- ...typeof o?.order === "number" && Number.isFinite(o.order) ? { order: o.order } : {},
448
- ...validName(o?.folder) ? { folder: o.folder } : {},
449
- ...title ? { title } : {},
450
- ...description ? { description } : {},
451
- ...type ? { type } : {},
452
- ...capability ? { capability } : {},
453
- ...status ? { status } : {},
454
- ...reason ? { reason } : {}
455
- };
456
- }
457
- /** The fields a board's file owns that the shell's save shape never carries: an autosave keeps
458
- * each one from disk when the incoming board omits it (spec 20 - the fields survive every write). */
459
- const AUTHOR_FIELDS = [
460
- "order",
461
- "folder",
462
- "title",
463
- "description",
464
- "type",
465
- "capability",
466
- "status",
467
- "reason"
468
- ];
469
- /** The folder registry. `sha256` is the CAS token a tree write must echo (null = "there was
470
- * no file"), so a write can never silently replace a registry it never saw. */
471
- function readRegistry(boardsDir) {
472
- const p = join(boardsDir, FOLDERS_FILE);
473
- if (!nodeExists(p)) return {
474
- state: "absent",
475
- folders: [],
476
- sha256: null
477
- };
478
- if (!isRegularFile(p)) return {
479
- state: "malformed",
480
- error: `design/boards/${FOLDERS_FILE} must be a regular file, not a symlink`,
481
- sha256: null
482
- };
483
- const content = readFileSync(p, "utf8");
484
- let raw;
485
- try {
486
- raw = JSON.parse(content);
487
- } catch {
488
- return {
489
- state: "malformed",
490
- error: `design/boards/${FOLDERS_FILE} is not valid JSON - fix the file`,
491
- sha256: hash(content)
492
- };
493
- }
494
- const parsed = parseFolders(raw);
495
- if (typeof parsed === "string") return {
496
- state: "malformed",
497
- error: `design/boards/${FOLDERS_FILE}: ${parsed}`,
498
- sha256: hash(content)
499
- };
500
- return {
501
- state: "ok",
502
- folders: parsed,
503
- sha256: hash(content)
504
- };
505
- }
506
- /** The registry's write lock - one writer at a time across processes (the dev server's tree write,
507
- * `folders add`, `init --kind`), so a read-modify-write of `_folders.json` is atomic among Marver's
508
- * writers. A lock older than 10 s is a crashed writer's and is taken over. `wait` = how long to
509
- * try (the CLI waits; the dev server never blocks its event loop - it answers 409 instead). */
510
- const REGISTRY_LOCK = ".folders.lock";
511
- function withRegistryLock(dir, wait, fn) {
512
- const lock = join(dir, REGISTRY_LOCK);
513
- const t0 = Date.now();
514
- for (;;) try {
515
- writeFileSync(lock, `${process.pid} ${Date.now()}\n`, { flag: "wx" });
516
- break;
517
- } catch (e) {
518
- if (e.code !== "EEXIST") throw e;
519
- try {
520
- if (Date.now() - lstatSync(lock).mtimeMs > 1e4) {
521
- rmSync(lock, { force: true });
522
- continue;
523
- }
524
- } catch {
525
- continue;
526
- }
527
- if (Date.now() - t0 >= wait) return null;
528
- Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
529
- }
530
- try {
531
- return fn();
532
- } finally {
533
- rmSync(lock, { force: true });
534
- }
535
- }
536
- /** Append typed folders to the registry (spec 20: `init --kind`, `folders add`). Never renames,
537
- * moves or retypes a folder that exists - a name already registered is skipped and reported - and
538
- * never drops a field of an existing entry it does not manage. New folders rank after everything
539
- * already at the root. The write is compare-and-swap: the registry is re-read just before the
540
- * atomic rename, and a change since the first read (the shell's drag, another agent) starts the
541
- * append over from the new file. A malformed registry is an error, never overwritten. */
542
- function addFolders(root, folders) {
543
- const dir = join(root, "design", "boards");
544
- const de = checkBoardsDir(root, dir);
545
- if (de) throw new Error(de);
546
- mkdirSync(dir, { recursive: true });
547
- const file = join(dir, FOLDERS_FILE);
548
- const done = withRegistryLock(dir, 5e3, () => appendFolders(dir, file, folders));
549
- if (!done) throw new Error(`design/boards/${FOLDERS_FILE} is being written by another process - try again`);
550
- return done;
551
- }
552
- function appendFolders(dir, file, folders) {
553
- for (let attempt = 0; attempt < 5; attempt++) {
554
- const before = nodeExists(file) ? readFileSync(file, "utf8") : null;
555
- const reg = readRegistry(dir);
556
- if (reg.state === "malformed") throw new Error(reg.error);
557
- let raw = [];
558
- if (before !== null) {
559
- const j = JSON.parse(before);
560
- raw = Array.isArray(j.folders) ? j.folders : [];
561
- }
562
- const have = new Set(raw.map((f) => f.name));
563
- const rootRanks = [...raw.filter((f) => f.parent === void 0).map((f) => f.order), ...listBoardFiles(dir).boards.map((b) => {
564
- const o = b.json;
565
- return o?.folder ? void 0 : o?.order;
566
- })].filter((o) => typeof o === "number" && Number.isFinite(o));
567
- let next = rootRanks.length ? Math.max(...rootRanks) + 1 : 0;
568
- const added = [], existing = [];
569
- const rows = [...raw];
570
- for (const f of folders) {
571
- if (have.has(f.name)) {
572
- existing.push(f.name);
573
- continue;
574
- }
575
- rows.push({
576
- name: f.name,
577
- order: next++,
578
- ...f.title ? { title: f.title } : {},
579
- ...f.type ? { type: f.type } : {}
580
- });
581
- have.add(f.name);
582
- added.push(f.name);
583
- }
584
- if (!added.length) return {
585
- added,
586
- existing
587
- };
588
- const version = rows.some((f) => f.parent !== void 0) ? 2 : 1;
589
- const tmp = `${file}.${process.pid}.${Date.now()}.${attempt}.tmp`;
590
- writeFileSync(tmp, JSON.stringify({
591
- version,
592
- folders: rows
593
- }, null, 2) + "\n", { flag: "wx" });
594
- if ((nodeExists(file) ? readFileSync(file, "utf8") : null) !== before) {
595
- rmSync(tmp, { force: true });
596
- continue;
597
- }
598
- renameSync(tmp, file);
599
- return {
600
- added,
601
- existing
602
- };
603
- }
604
- throw new Error(`design/boards/${FOLDERS_FILE} kept changing while folders were added - try again`);
605
- }
606
- //#endregion
1
+ import { A as readCapability, E as HAS_STATUS, M as readStatusWord, P as resolveType, j as readReason, w as DECISIONS } from "./boards-DbVJlbd5.mjs";
2
+ import { lstatSync, readFileSync, readdirSync, statSync } from "node:fs";
3
+ import { join } from "node:path";
607
4
  //#region src/shared/context.ts
608
5
  const LEVEL = /`(confirmed|reported|unknown)`/g;
609
6
  /** What counts as a citation beside a level: a `path:line`, a run id, a cited file, or a link to a
@@ -920,13 +317,14 @@ const wordCount = (text) => frontMatter(text).body.split(/\s+/).filter(Boolean).
920
317
  *
921
318
  * 1-3 the board says archived, paused or blocked (with its reason) - a decision, by hand
922
319
  * 4 the evidence it needs cannot be read - Unknown, never a stale Done
923
- * 5 an open plan names the capability - In progress, filling by phase
320
+ * 5 an open plan names the capability - Building when it says `stage: build`,
321
+ * else In progress, filling by phase
924
322
  * 6 the shipped record shows it available, `confirmed` - Done
925
323
  * 7 ... `reported` only - Done, reported
926
324
  * 8 an accepted contract (`state: current`), no availability - To do
927
325
  * 9 anything else - Backlog
928
326
  *
929
- * Without `context/`, a board may also say in-progress, todo or backlog by hand. Done is never
327
+ * Without `context/`, a board may also say in-progress, building, todo or backlog by hand. Done is never
930
328
  * set by hand: `"status": "done"` is ignored here and reported by `marver context check`.
931
329
  */
932
330
  const STATUS_LABEL = {
@@ -935,6 +333,7 @@ const STATUS_LABEL = {
935
333
  blocked: "Blocked",
936
334
  unknown: "Unknown",
937
335
  "in-progress": "In progress",
336
+ building: "Building",
938
337
  done: "Done",
939
338
  "done-reported": "Done, reported",
940
339
  todo: "To do",
@@ -997,6 +396,7 @@ function resolveStatus(b, ctx) {
997
396
  const f = fillOf(capability, b.scenes);
998
397
  return out("in-progress", 5, [`design/boards/${b.name}.json: by hand`, ...f.evidence], strictest("publishable", ...f.audience), f.fill);
999
398
  }
399
+ if (b.status === "building") return out("building", 5, [`design/boards/${b.name}.json: by hand`], "publishable");
1000
400
  if (b.status === "todo") return out("todo", 8, [`design/boards/${b.name}.json: by hand`], "publishable");
1001
401
  return out("backlog", 9, [b.status === "backlog" ? `design/boards/${b.name}.json: by hand` : "no context/ - nothing records it"], "publishable");
1002
402
  }
@@ -1006,6 +406,12 @@ function resolveStatus(b, ctx) {
1006
406
  const live = row?.levels.includes("confirmed") ? "confirmed" : row?.levels.includes("reported") ? "reported" : null;
1007
407
  const plans = ctx.plans.get(capability);
1008
408
  if (plans?.length) {
409
+ const building = plans.filter((p) => p.stage === "build");
410
+ if (building.length) {
411
+ const ev = building.map((p) => `${p.where}: stage build`);
412
+ if (live && row) ev.push(`${row.where}: available, \`${live}\` - this is the next version`);
413
+ return out("building", 5, ev, strictest(...building.map((p) => p.audience), ...live && row ? [row.audience] : []));
414
+ }
1009
415
  const f = fillOf(capability, b.scenes);
1010
416
  const ev = [...plans.map((p) => `${p.where}: an open plan`), ...f.evidence];
1011
417
  if (live && row) ev.push(`${row.where}: available, \`${live}\` - this is the next version`);
@@ -1044,6 +450,7 @@ function publishableStatus(r) {
1044
450
  /** The statuses rows 5-9 produce - the only ones a published canvas may show. */
1045
451
  const PUBLISHABLE = /* @__PURE__ */ new Set([
1046
452
  "in-progress",
453
+ "building",
1047
454
  "done",
1048
455
  "done-reported",
1049
456
  "todo",
@@ -1197,9 +604,11 @@ function readFresh(dir) {
1197
604
  const list = (v) => Array.isArray(v) ? v : v === void 0 ? [] : [v];
1198
605
  const caps = [...list(fm.data.capability), ...list(fm.data.capabilities)].map(readCapability).filter((c) => !!c);
1199
606
  const audience = readAudience(fm.data.audience);
607
+ const stage = typeof fm.data.stage === "string" && /^build(ing)?$/i.test(fm.data.stage.trim()) ? "build" : void 0;
1200
608
  for (const c of caps) facts.plans.set(c, [...facts.plans.get(c) ?? [], {
1201
609
  where,
1202
- audience
610
+ audience,
611
+ ...stage ? { stage } : {}
1203
612
  }]);
1204
613
  } catch (e) {
1205
614
  facts.unreadable.set("*", `${where}: ${e.message}`);
@@ -1303,5 +712,55 @@ function annotateBoards(root, boards, folders, folderOf, facts = readContextFact
1303
712
  }
1304
713
  return out;
1305
714
  }
715
+ /**
716
+ * A plan with its `stage` set - `build` (Building), or none (back to In progress) - the one context/
717
+ * edit the sidebar makes, for the picker's Building and In progress. Only the `stage:` line of the
718
+ * front matter moves: every other byte - lines, their endings, the body - is kept as it was. An
719
+ * error (and nothing written) when there is no front matter to write into, or a `stage` this cannot
720
+ * edit as one line: written twice, or as a list or a map.
721
+ */
722
+ function planWithStage(raw, stage) {
723
+ const head = /^(\uFEFF?<!-- marver:managed [^\n]*-->\r?\n)?\uFEFF?---\r?\n/.exec(raw);
724
+ if (!head) return { error: "has no front matter" };
725
+ const from = head[0].length;
726
+ const close = /(^|\n)---[ \t]*(\r?\n|$)/g;
727
+ close.lastIndex = from - 1;
728
+ let end = -1;
729
+ for (let m = close.exec(raw); m; m = close.exec(raw)) if (m.index + m[1].length >= from) {
730
+ end = m.index + m[1].length;
731
+ break;
732
+ }
733
+ if (end === -1) return { error: "has front matter that never closes" };
734
+ const lines = [...raw.slice(from, end).matchAll(/[^\n]*\n|[^\n]+$/g)].map((m) => ({
735
+ at: from + m.index,
736
+ text: m[0]
737
+ }));
738
+ const stages = lines.filter((l) => /^stage\s*:/.test(l.text));
739
+ if (stages.length > 1) return { error: "says `stage` twice - keep one" };
740
+ const line = stages[0];
741
+ if (line) {
742
+ const value = line.text.replace(/^stage\s*:/, "").trim();
743
+ const after = lines.slice(lines.indexOf(line) + 1);
744
+ const nextField = after.findIndex((l) => /^[A-Za-z_][\w-]*\s*:/.test(l.text));
745
+ const continues = (nextField === -1 ? after : after.slice(0, nextField)).some((l) => /^[ \t]+[^\s#]/.test(l.text));
746
+ if (!value || /^[[{|>#]/.test(value) || continues) return { error: "has a `stage` that is not one word - write it as `stage: build`" };
747
+ }
748
+ const eol = (line?.text.match(/\r?\n$/) ?? lines[lines.length - 1]?.text.match(/\r?\n$/) ?? head[0].match(/\r?\n$/))[0];
749
+ const text = stage === null ? line ? raw.slice(0, line.at) + raw.slice(line.at + line.text.length) : raw : line ? raw.slice(0, line.at) + `stage: ${stage}` + (line.text.match(/\r?\n$/)?.[0] ?? "") + raw.slice(line.at + line.text.length) : raw.slice(0, end) + `stage: ${stage}${eol}` + raw.slice(end);
750
+ const before = frontMatter(raw).data ?? {}, after = frontMatter(text).data ?? {};
751
+ if ("stage" in before && typeof before.stage !== "string") return { error: "has a `stage` that is not one word - write it as `stage: build`" };
752
+ const rest = (d) => JSON.stringify(Object.entries(d).filter(([k]) => k !== "stage").sort(([a], [b]) => a.localeCompare(b)));
753
+ if (rest(before) !== rest(after) || (stage ? after.stage !== stage : "stage" in after)) return { error: "has a `stage` this cannot edit as one line - write it as `stage: build`" };
754
+ return { text };
755
+ }
756
+ /** Is this plan text open, and naming the capability? The check a write repeats on what it reads -
757
+ * a plan closed, or moved to another capability, since the evidence was gathered is not written. */
758
+ function planNames(raw, capability) {
759
+ const fm = frontMatter(raw);
760
+ if (fm.error || !fm.data) return false;
761
+ if (typeof fm.data.state === "string" && CLOSED_PLAN.has(fm.data.state)) return false;
762
+ const list = (v) => Array.isArray(v) ? v : v === void 0 ? [] : [v];
763
+ return [...list(fm.data.capability), ...list(fm.data.capabilities)].map(readCapability).includes(capability);
764
+ }
1306
765
  //#endregion
1307
- export { readCapability as $, isRegularFile as A, folderMap as B, tables as C, boardFields as D, addFolders as E, BOARD_NAME as F, validateWire as G, isBoardName as H, FOLDERS_FILE as I, FOLDER_MODULES as J, wireKids as K, buildTree as L, nodeExists as M, readRegistry as N, checkBoardsDir as O, withRegistryLock as P, knownType as Q, flatten as R, proseLines as S, AUTHOR_FIELDS as T, readDescription as U, humanize as V, readTitle as W, KIND_FOLDERS as X, HAS_STATUS as Y, PROPOSED_PUBLISH as Z, isRecordTable as _, STATUS_LABEL as a, hash as at, looseTables as b, CITED_FILE as c, LEVEL as d, readReason as et, availableLevels as f, hasGlob as g, globRe as h, PUBLISHABLE as i, settableStatuses as it, listBoardFiles as j, checkRealDirs as k, EVIDENCE_COLUMN as l, frontMatter as m, readContextFacts as n, readType as nt, publishableStatus as o, capabilityTable as p, BOARD_TYPES as q, PHASE_LABEL as r, resolveType as rt, CITATION as s, annotateBoards as t, readStatusWord as tt, GENERATED as u, levelsIn as v, wordCount as w, parseMap as x, lf as y, folderEntries as z };
766
+ export { parseMap as C, wordCount as E, looseTables as S, tables as T, globRe as _, PHASE_LABEL as a, levelsIn as b, publishableStatus as c, EVIDENCE_COLUMN as d, GENERATED as f, frontMatter as g, capabilityTable as h, readContextFacts as i, CITATION as l, availableLevels as m, planNames as n, PUBLISHABLE as o, LEVEL as p, planWithStage as r, STATUS_LABEL as s, annotateBoards as t, CITED_FILE as u, hasGlob as v, proseLines as w, lf as x, isRecordTable as y };