@marver-design/marver 0.22.1 → 0.23.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +117 -0
- package/README.md +14 -10
- package/dist/agent-BsieQGTD.mjs +99 -0
- package/dist/{bake-CvY8QR3L.mjs → bake-DQtnDB8-.mjs} +1 -1
- package/dist/{board-status-CWGHIdo_.mjs → board-status-BZSzc9Hp.mjs} +69 -610
- package/dist/boards-BRLnoTC3.mjs +620 -0
- package/dist/{boards-BwKI0qWd.mjs → boards-Dv-Ipd8G.mjs} +13 -5
- package/dist/{build-B1kavcpc.mjs → build-_ndp_dXn.mjs} +18 -10
- package/dist/cli.mjs +20 -11
- package/dist/{comments-ClVgfQib.mjs → comments-BlqyZh3D.mjs} +71 -9
- package/dist/{config-DJxMRVD8.mjs → config-BUKprFAp.mjs} +5 -97
- package/dist/{context-D4t59wDi.mjs → context-CdkNiKdJ.mjs} +3 -2
- package/dist/{daemon-PmNqoOAk.mjs → daemon-BvMPdQ3k.mjs} +78 -19
- package/dist/{dev-Cf4wLGe2.mjs → dev-Cf-4eqaC.mjs} +50 -10
- package/dist/{init-C_K-cjBQ.mjs → init-hfZV7TwY.mjs} +10 -4
- package/dist/{ledger-Bu0BjqIe.mjs → ledger-BNXW14Xw.mjs} +1 -6
- package/dist/link-BodAbIQz.mjs +132 -0
- package/dist/{manifest-CcdWx7ud.mjs → manifest-TpfDWldB.mjs} +56 -6
- package/dist/{plugin-C5u07Yhv.mjs → plugin-DoXql0ZZ.mjs} +400 -48
- package/dist/{poster-BduzQBYz.mjs → poster-XBmUvQiL.mjs} +1 -1
- package/dist/{profile-BjAPAJSb.mjs → profile-CrZohD6g.mjs} +1 -1
- package/dist/{publish-bakes-b0jUwvM_.mjs → publish-bakes-KKTHWqq3.mjs} +2 -2
- package/dist/{share--bdSc4G5.mjs → share-BD-wcDQq.mjs} +1 -1
- package/dist/{shot-BAR8hmU9.mjs → shot-DOD8v6fJ.mjs} +2 -2
- package/dist/{shot-BFEuYbaz.mjs → shot-Dh6fV1Lm.mjs} +1 -1
- package/dist/{sync-BZaCWqK-.mjs → sync-DoA1vf4u.mjs} +15 -1
- package/dist/{work-0YopuMt9.mjs → work-ClFFq0Qh.mjs} +9 -3
- package/dist/{work-CLrmY-vQ.mjs → work-ayuL_9Kk.mjs} +72 -1
- package/docs/boards-and-folders.md +60 -7
- package/docs/context.md +10 -2
- package/docs/live-jam.md +11 -0
- package/docs/sticky-notes.md +1 -1
- package/package.json +1 -1
- package/src/client/content/diagram.tsx +7 -1
- package/src/client/content/img-lod.ts +12 -2
- package/src/client/content/index.tsx +73 -6
- package/src/client/content/md.ts +3 -2
- package/src/client/frame-host/inspect.js +23 -0
- package/src/client/shell/App.tsx +21 -10
- package/src/client/shell/BoardList.tsx +26 -6
- package/src/client/shell/LockedApp.tsx +2 -2
- package/src/client/shell/Play.tsx +5 -1
- package/src/client/shell/StatusPicker.tsx +12 -5
- package/src/client/shell/Tip.tsx +25 -5
- package/src/client/shell/board-icons.tsx +15 -1
- package/src/client/shell/canvas/Canvas.tsx +42 -6
- package/src/client/shell/canvas/anchor.ts +41 -0
- package/src/client/shell/canvas/ctl.ts +6 -0
- package/src/client/shell/comments-store.ts +8 -5
- package/src/client/shell/goto.ts +52 -3
- package/src/client/shell/hash.ts +24 -3
- package/src/client/shell/store.ts +261 -36
- package/src/client/shell/styles.css +20 -2
- package/src/client/shell/tidy.ts +34 -3
- package/src/shared/board-types.ts +10 -6
- package/src/shared/frames.ts +3 -0
- package/src/shared/status.ts +17 -8
- package/templates/AGENTS-embedded.md +43 -8
- package/templates/AGENTS-studio.md +43 -8
- package/templates/instructions/boards.md +13 -3
- package/templates/instructions/context.md +6 -2
- package/templates/instructions/iterate.md +29 -16
- package/templates/instructions/jam.md +9 -2
- package/templates/instructions/reference/deck-layouts.md +2 -1
- package/templates/instructions/reference/deck-story.md +2 -1
|
@@ -0,0 +1,620 @@
|
|
|
1
|
+
import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, 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`, `in-progress` and `building` 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
|
+
"building",
|
|
63
|
+
"todo",
|
|
64
|
+
"backlog"
|
|
65
|
+
];
|
|
66
|
+
const STATUS_WORDS = [
|
|
67
|
+
...DECISIONS,
|
|
68
|
+
...BY_HAND,
|
|
69
|
+
"done"
|
|
70
|
+
];
|
|
71
|
+
const readStatusWord = (v) => STATUS_WORDS.includes(v) ? v : void 0;
|
|
72
|
+
/** The statuses a person may set on a feature or project board, in the order a picker lists them:
|
|
73
|
+
* the three decisions always; Backlog, To do, In progress and Building where there is no `context/`
|
|
74
|
+
* (with it they are read from the evidence). With it, In progress and Building where an open plan
|
|
75
|
+
* names the capability - choosing one writes that plan's `stage`, the evidence they are read from.
|
|
76
|
+
* Never Done - that is the shipped record's alone. */
|
|
77
|
+
const settableStatuses = (contextPresent, openPlan = false) => contextPresent ? [
|
|
78
|
+
...openPlan ? ["in-progress", "building"] : [],
|
|
79
|
+
"blocked",
|
|
80
|
+
"paused",
|
|
81
|
+
"archived"
|
|
82
|
+
] : [
|
|
83
|
+
"backlog",
|
|
84
|
+
"todo",
|
|
85
|
+
"in-progress",
|
|
86
|
+
"building",
|
|
87
|
+
"blocked",
|
|
88
|
+
"paused",
|
|
89
|
+
"archived"
|
|
90
|
+
];
|
|
91
|
+
/** A capability slug - the same grammar as a board name, so a feature board and its contract
|
|
92
|
+
* share it. */
|
|
93
|
+
const readCapability = (v) => typeof v === "string" && /^[a-z0-9][a-z0-9-]{0,63}$/.test(v) ? v : void 0;
|
|
94
|
+
const readReason = (v) => {
|
|
95
|
+
if (typeof v !== "string") return void 0;
|
|
96
|
+
return v.trim().replace(/\s+/g, " ").slice(0, 300) || void 0;
|
|
97
|
+
};
|
|
98
|
+
/** The sidebar every canvas shares (spec 19, The canvas): folder modules, each typed, so a board
|
|
99
|
+
* made inside one wears its type. `marver init --kind` creates a kind's set on a fresh canvas;
|
|
100
|
+
* `marver folders add <module>` adds one later. Names are slugs; only Start here needs a title. */
|
|
101
|
+
const FOLDER_MODULES = {
|
|
102
|
+
start: {
|
|
103
|
+
name: "start-here",
|
|
104
|
+
title: "Start here",
|
|
105
|
+
type: "start"
|
|
106
|
+
},
|
|
107
|
+
features: {
|
|
108
|
+
name: "features",
|
|
109
|
+
type: "feature"
|
|
110
|
+
},
|
|
111
|
+
surfaces: {
|
|
112
|
+
name: "surfaces",
|
|
113
|
+
type: "surface"
|
|
114
|
+
},
|
|
115
|
+
projects: {
|
|
116
|
+
name: "projects",
|
|
117
|
+
type: "project"
|
|
118
|
+
},
|
|
119
|
+
feedback: {
|
|
120
|
+
name: "feedback",
|
|
121
|
+
type: "feedback"
|
|
122
|
+
},
|
|
123
|
+
context: {
|
|
124
|
+
name: "context",
|
|
125
|
+
type: "context"
|
|
126
|
+
},
|
|
127
|
+
decks: {
|
|
128
|
+
name: "decks",
|
|
129
|
+
type: "deck"
|
|
130
|
+
},
|
|
131
|
+
archive: {
|
|
132
|
+
name: "archive",
|
|
133
|
+
type: "archive"
|
|
134
|
+
}
|
|
135
|
+
};
|
|
136
|
+
/** A kind of work's folders, in sidebar order: the core (Start here, Feedback, Context, Archive)
|
|
137
|
+
* around the kind's own modules. Decks are an add-on for either. */
|
|
138
|
+
const KIND_FOLDERS = {
|
|
139
|
+
product: [
|
|
140
|
+
"start",
|
|
141
|
+
"features",
|
|
142
|
+
"surfaces",
|
|
143
|
+
"feedback",
|
|
144
|
+
"context",
|
|
145
|
+
"archive"
|
|
146
|
+
],
|
|
147
|
+
knowledge: [
|
|
148
|
+
"start",
|
|
149
|
+
"projects",
|
|
150
|
+
"feedback",
|
|
151
|
+
"context",
|
|
152
|
+
"archive"
|
|
153
|
+
]
|
|
154
|
+
};
|
|
155
|
+
//#endregion
|
|
156
|
+
//#region src/shared/board-tree.ts
|
|
157
|
+
/**
|
|
158
|
+
* Board folders - the pure tree shared by the sidebar, the dev API, the build and the
|
|
159
|
+
* tests. Files are the truth: a board says which folder it sits in (`folder` on the
|
|
160
|
+
* board file - one slug, the folder it sits in directly), ranked among its siblings by
|
|
161
|
+
* `order`, and `design/boards/_folders.json` says which folders exist, where they rank, and
|
|
162
|
+
* which folder holds which (`parent`). Two levels: a folder holds boards and folders, a
|
|
163
|
+
* folder inside a folder (a sub-folder) holds boards only. `all-scenes` never enters the
|
|
164
|
+
* tree - callers pin it last.
|
|
165
|
+
*/
|
|
166
|
+
/** The on-disk name grammar shared by boards and folders (a board name is a filename). */
|
|
167
|
+
const BOARD_NAME = /^[a-z0-9][a-z0-9-]*$/;
|
|
168
|
+
const isBoardName = (n) => typeof n === "string" && n.length >= 1 && n.length <= 64 && BOARD_NAME.test(n);
|
|
169
|
+
/** The folder registry beside the boards - underscore = infrastructure, never a board. */
|
|
170
|
+
const FOLDERS_FILE = "_folders.json";
|
|
171
|
+
/** Is this basename in design/boards/ a board file? `_folders.json`, temp files and any
|
|
172
|
+
* off-grammar name are not - every lister (dev API, build, watcher) shares this rule. */
|
|
173
|
+
const isBoardFile = (f) => f.endsWith(".json") && isBoardName(f.slice(0, -5));
|
|
174
|
+
const readDescription = (v) => {
|
|
175
|
+
if (typeof v !== "string") return void 0;
|
|
176
|
+
return v.trim().replace(/\s+/g, " ").slice(0, 300) || void 0;
|
|
177
|
+
};
|
|
178
|
+
const readTitle = (v) => {
|
|
179
|
+
if (typeof v !== "string") return void 0;
|
|
180
|
+
return Array.from(v.replace(/[\u0000-\u001f\u007f]/g, " ").trim().replace(/\s+/g, " ")).slice(0, 120).join("").trim() || void 0;
|
|
181
|
+
};
|
|
182
|
+
/** Title Case off a slug - the display when no title is set ("old-stuff" → "Old Stuff"). */
|
|
183
|
+
const humanize = (s) => s.replace(/-/g, " ").replace(/(^|\s)\S/g, (c) => c.toUpperCase());
|
|
184
|
+
const rank = (o) => typeof o === "number" && Number.isFinite(o) ? o : Infinity;
|
|
185
|
+
/** A folder's title, description and type, present only when set. */
|
|
186
|
+
const folderExtras = (it) => ({
|
|
187
|
+
...it.title ? { title: it.title } : {},
|
|
188
|
+
...it.description ? { description: it.description } : {},
|
|
189
|
+
...readType(it.type) ? { type: it.type } : {}
|
|
190
|
+
});
|
|
191
|
+
/** The registry file's shape. Returns the rows, or a string naming what is wrong - a
|
|
192
|
+
* malformed registry is an ERROR the human must fix (silently reading it as empty, or
|
|
193
|
+
* flattening a broken nesting, would let the next drag overwrite their folders), while a
|
|
194
|
+
* missing file is simply no folders. */
|
|
195
|
+
function parseFolders(raw) {
|
|
196
|
+
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return "expected an object";
|
|
197
|
+
const { version, folders } = raw;
|
|
198
|
+
if (version !== void 0 && version !== 1 && version !== 2) return `unsupported version ${String(version)}`;
|
|
199
|
+
if (!Array.isArray(folders)) return "expected a \"folders\" array";
|
|
200
|
+
const out = [];
|
|
201
|
+
const seen = /* @__PURE__ */ new Set();
|
|
202
|
+
for (const f of folders) {
|
|
203
|
+
const name = f?.name;
|
|
204
|
+
if (!isBoardName(name)) return "a folder needs a name - lowercase letters, numbers and dashes";
|
|
205
|
+
if (seen.has(name)) return `folder "${name}" is listed twice`;
|
|
206
|
+
seen.add(name);
|
|
207
|
+
const o = f.order;
|
|
208
|
+
const p = f.parent;
|
|
209
|
+
if (p !== void 0 && !isBoardName(p)) return `folder "${name}" has an invalid parent - a folder name`;
|
|
210
|
+
const t = readTitle(f.title);
|
|
211
|
+
const d = readDescription(f.description);
|
|
212
|
+
const ty = readType(f.type);
|
|
213
|
+
out.push({
|
|
214
|
+
name,
|
|
215
|
+
...typeof o === "number" && Number.isFinite(o) ? { order: o } : {},
|
|
216
|
+
...p !== void 0 ? { parent: p } : {},
|
|
217
|
+
...t ? { title: t } : {},
|
|
218
|
+
...d ? { description: d } : {},
|
|
219
|
+
...ty ? { type: ty } : {}
|
|
220
|
+
});
|
|
221
|
+
}
|
|
222
|
+
const byName = new Map(out.map((f) => [f.name, f]));
|
|
223
|
+
for (const f of out) {
|
|
224
|
+
if (f.parent === void 0) continue;
|
|
225
|
+
if (version !== 2) return `folder "${f.name}" names a parent - nested folders need "version": 2`;
|
|
226
|
+
if (f.parent === f.name) return `folder "${f.name}" cannot be its own parent`;
|
|
227
|
+
const p = byName.get(f.parent);
|
|
228
|
+
if (!p) return `folder "${f.name}" names an unknown parent "${f.parent}"`;
|
|
229
|
+
if (p.parent !== void 0) return `folder "${f.name}" would sit three levels deep - folders nest one level only`;
|
|
230
|
+
}
|
|
231
|
+
return out;
|
|
232
|
+
}
|
|
233
|
+
/** Sidebar order from the files. At every level the boards and folders there share one
|
|
234
|
+
* sequence, ranked by `order`, then kind (board before folder), then name; unranked sorts
|
|
235
|
+
* after ranked. The root holds root boards and top-level folders (registered without a
|
|
236
|
+
* parent, or implied by a board that names an unregistered folder); a top-level folder holds
|
|
237
|
+
* its boards and its sub-folders; a sub-folder holds its boards. A folder's title and
|
|
238
|
+
* description and type ride on its item (they live in the registry a tree write rewrites); a board's
|
|
239
|
+
* title stays with its row - it lives in the board's own file. */
|
|
240
|
+
function buildTree(boards, folders) {
|
|
241
|
+
const reg = /* @__PURE__ */ new Map();
|
|
242
|
+
for (const f of folders) if (isBoardName(f.name) && !reg.has(f.name)) reg.set(f.name, f);
|
|
243
|
+
const parentOf = (n) => {
|
|
244
|
+
const p = reg.get(n)?.parent;
|
|
245
|
+
return p !== void 0 && p !== n && reg.has(p) && reg.get(p).parent === void 0 ? p : void 0;
|
|
246
|
+
};
|
|
247
|
+
const members = /* @__PURE__ */ new Map();
|
|
248
|
+
const implied = [];
|
|
249
|
+
const rootBoards = [];
|
|
250
|
+
for (const b of boards) {
|
|
251
|
+
if (!isBoardName(b.name) || b.name === "all-scenes") continue;
|
|
252
|
+
const folder = isBoardName(b.folder) ? b.folder : void 0;
|
|
253
|
+
if (!folder) {
|
|
254
|
+
rootBoards.push(b);
|
|
255
|
+
continue;
|
|
256
|
+
}
|
|
257
|
+
if (!reg.has(folder) && !implied.includes(folder)) implied.push(folder);
|
|
258
|
+
const list = members.get(folder) ?? [];
|
|
259
|
+
list.push(b);
|
|
260
|
+
members.set(folder, list);
|
|
261
|
+
}
|
|
262
|
+
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);
|
|
263
|
+
const boardsHere = (name) => (name === null ? rootBoards : members.get(name) ?? []).map((b) => ({
|
|
264
|
+
item: {
|
|
265
|
+
kind: "board",
|
|
266
|
+
name: b.name
|
|
267
|
+
},
|
|
268
|
+
order: b.order
|
|
269
|
+
}));
|
|
270
|
+
const folder = (name, kids) => ({
|
|
271
|
+
item: {
|
|
272
|
+
kind: "folder",
|
|
273
|
+
name,
|
|
274
|
+
items: sorted(kids),
|
|
275
|
+
...folderExtras(reg.get(name) ?? {})
|
|
276
|
+
},
|
|
277
|
+
order: reg.get(name)?.order
|
|
278
|
+
});
|
|
279
|
+
const subsOf = (top) => [...reg.keys()].filter((n) => parentOf(n) === top);
|
|
280
|
+
const tops = [...[...reg.keys()].filter((n) => !parentOf(n)), ...implied];
|
|
281
|
+
return sorted([...boardsHere(null), ...tops.map((t) => folder(t, [...boardsHere(t), ...subsOf(t).map((s) => folder(s, boardsHere(s)))]))]);
|
|
282
|
+
}
|
|
283
|
+
/** Every board in reading order, depth-first - the order the switchers and the landing pick use. */
|
|
284
|
+
function flatten(tree) {
|
|
285
|
+
const out = [];
|
|
286
|
+
const walk = (items) => {
|
|
287
|
+
for (const it of items) if (it.kind === "board") out.push(it.name);
|
|
288
|
+
else walk(it.items);
|
|
289
|
+
};
|
|
290
|
+
walk(tree);
|
|
291
|
+
return out;
|
|
292
|
+
}
|
|
293
|
+
const wireKids = (w) => w.items ?? w.boards ?? [];
|
|
294
|
+
function validateWire(wire) {
|
|
295
|
+
if (!Array.isArray(wire)) return "invalid tree";
|
|
296
|
+
const boards = /* @__PURE__ */ new Set(), folders = /* @__PURE__ */ new Set();
|
|
297
|
+
const board = (n) => {
|
|
298
|
+
if (!isBoardName(n) || n === "all-scenes") return "invalid board name in tree";
|
|
299
|
+
if (boards.has(n)) return `board "${n}" appears twice`;
|
|
300
|
+
boards.add(n);
|
|
301
|
+
return null;
|
|
302
|
+
};
|
|
303
|
+
const walk = (list, depth) => {
|
|
304
|
+
for (const w of list) {
|
|
305
|
+
if (typeof w === "string") {
|
|
306
|
+
const e = board(w);
|
|
307
|
+
if (e) return e;
|
|
308
|
+
continue;
|
|
309
|
+
}
|
|
310
|
+
if (!w || typeof w !== "object" || Array.isArray(w)) return "invalid tree item";
|
|
311
|
+
if (depth >= 2) return "folders nest one level only";
|
|
312
|
+
const { folder, items, boards: legacy, title, description, type } = w;
|
|
313
|
+
if (!isBoardName(folder)) return "invalid folder name in tree";
|
|
314
|
+
if (title !== void 0 && (typeof title !== "string" || Array.from(title).length > 120)) return "invalid folder title";
|
|
315
|
+
if (description !== void 0 && (typeof description !== "string" || description.length > 300)) return "invalid folder description";
|
|
316
|
+
if (type !== void 0 && !readType(type)) return "invalid folder type";
|
|
317
|
+
if (folders.has(folder)) return `folder "${folder}" appears twice`;
|
|
318
|
+
folders.add(folder);
|
|
319
|
+
const kids = items ?? legacy;
|
|
320
|
+
if (!Array.isArray(kids)) return "invalid folder in tree";
|
|
321
|
+
if (items === void 0 && kids.some((k) => typeof k !== "string")) return "invalid folder in tree";
|
|
322
|
+
const e = walk(kids, depth + 1);
|
|
323
|
+
if (e) return e;
|
|
324
|
+
}
|
|
325
|
+
return null;
|
|
326
|
+
};
|
|
327
|
+
const e = walk(wire, 0);
|
|
328
|
+
if (e) return e;
|
|
329
|
+
if (boards.size > 200 || folders.size > 50) return "tree too large";
|
|
330
|
+
return null;
|
|
331
|
+
}
|
|
332
|
+
/** Every folder with the folder it sits in (null = the root), top-level folders first in
|
|
333
|
+
* reading order, each followed by its sub-folders. */
|
|
334
|
+
function folderEntries(t) {
|
|
335
|
+
const out = [];
|
|
336
|
+
for (const it of t) {
|
|
337
|
+
if (it.kind !== "folder") continue;
|
|
338
|
+
out.push({
|
|
339
|
+
folder: it,
|
|
340
|
+
parent: null
|
|
341
|
+
});
|
|
342
|
+
for (const k of it.items) if (k.kind === "folder") out.push({
|
|
343
|
+
folder: k,
|
|
344
|
+
parent: it.name
|
|
345
|
+
});
|
|
346
|
+
}
|
|
347
|
+
return out;
|
|
348
|
+
}
|
|
349
|
+
/** Every board's folder, in one pass - for callers that ask for many boards (folderOf walks the tree). */
|
|
350
|
+
function folderMap(t) {
|
|
351
|
+
const out = /* @__PURE__ */ new Map();
|
|
352
|
+
for (const { folder } of folderEntries(t)) for (const k of folder.items) if (k.kind === "board") out.set(k.name, folder.name);
|
|
353
|
+
return out;
|
|
354
|
+
}
|
|
355
|
+
//#endregion
|
|
356
|
+
//#region src/server/boards.ts
|
|
357
|
+
/**
|
|
358
|
+
* Reading design/boards/ safely - the one enumerator the dev API, the build and the tests
|
|
359
|
+
* share. Only REGULAR files on the board-name grammar count as boards (a symlink, dangling or
|
|
360
|
+
* live, could read or publish JSON from outside the project - it is skipped, and reported so
|
|
361
|
+
* the build can fail closed). The folder registry is read the same way: absent = no folders,
|
|
362
|
+
* malformed = an error the human must fix, never a silently empty registry.
|
|
363
|
+
*/
|
|
364
|
+
/** Does realpath(dir) stay inside realpath(root)? A symlinked design/boards can't escape. */
|
|
365
|
+
function underRoot(root, dir) {
|
|
366
|
+
try {
|
|
367
|
+
const rr = realpathSync(root);
|
|
368
|
+
const rd = realpathSync(dir);
|
|
369
|
+
return rd === rr || rd.startsWith(rr + sep);
|
|
370
|
+
} catch {
|
|
371
|
+
return false;
|
|
372
|
+
}
|
|
373
|
+
}
|
|
374
|
+
/** Is design/boards a directory we may read and write? It must not be a symlink at all (a
|
|
375
|
+
* link to the repo root would list package.json as a board and let a tree write rewrite
|
|
376
|
+
* it; a link outside would publish foreign JSON) and must resolve inside the root. Absent
|
|
377
|
+
* is fine (no boards yet). Returns the error, or null. */
|
|
378
|
+
function checkBoardsDir(root, boardsDir) {
|
|
379
|
+
return checkRealDirs(root, [[join(boardsDir, ".."), "design"], [boardsDir, "design/boards"]]);
|
|
380
|
+
}
|
|
381
|
+
/** Every EXISTING path in `dirs` (root-down order) must be a real directory inside the root -
|
|
382
|
+
* a symlinked `design` with no boards dir yet would otherwise be followed by the mkdir that
|
|
383
|
+
* creates it; a symlinked `design/scenes` would let a brief write land outside the project.
|
|
384
|
+
* An absent one ends the walk (nothing beneath it exists either). Returns the error, or null. */
|
|
385
|
+
function checkRealDirs(root, dirs) {
|
|
386
|
+
for (const [p, label] of dirs) {
|
|
387
|
+
try {
|
|
388
|
+
if (lstatSync(p).isSymbolicLink()) return `${label} must be a real directory, not a symlink`;
|
|
389
|
+
} catch {
|
|
390
|
+
return null;
|
|
391
|
+
}
|
|
392
|
+
if (!underRoot(root, p)) return `${label} escapes the project`;
|
|
393
|
+
}
|
|
394
|
+
return null;
|
|
395
|
+
}
|
|
396
|
+
/** A regular file (lstat: a symlink is never followed, a dangling one is not "absent"). */
|
|
397
|
+
const isRegularFile = (p) => {
|
|
398
|
+
try {
|
|
399
|
+
return lstatSync(p).isFile();
|
|
400
|
+
} catch {
|
|
401
|
+
return false;
|
|
402
|
+
}
|
|
403
|
+
};
|
|
404
|
+
/** Is there ANY node at p (a dangling symlink counts)? */
|
|
405
|
+
const nodeExists = (p) => {
|
|
406
|
+
try {
|
|
407
|
+
lstatSync(p);
|
|
408
|
+
return true;
|
|
409
|
+
} catch {
|
|
410
|
+
return false;
|
|
411
|
+
}
|
|
412
|
+
};
|
|
413
|
+
/** A board file's JSON, or why it is not JSON - the parser's own words, naming the line and column (#6). */
|
|
414
|
+
function parseBoard(content) {
|
|
415
|
+
try {
|
|
416
|
+
return { json: JSON.parse(content) };
|
|
417
|
+
} catch (e) {
|
|
418
|
+
const msg = e.message, lines = content.split("\n");
|
|
419
|
+
return {
|
|
420
|
+
json: null,
|
|
421
|
+
error: /end of JSON input$/.test(msg) ? `${msg} (line ${lines.length} column ${lines[lines.length - 1].length + 1})` : msg
|
|
422
|
+
};
|
|
423
|
+
}
|
|
424
|
+
}
|
|
425
|
+
/** Every board file: name, raw content, hash, and its JSON (null when malformed). `skipped`
|
|
426
|
+
* names the entries that looked like boards but were not regular files. */
|
|
427
|
+
function listBoardFiles(boardsDir) {
|
|
428
|
+
const boards = [], skipped = [];
|
|
429
|
+
if (!existsSync(boardsDir)) return {
|
|
430
|
+
boards,
|
|
431
|
+
skipped
|
|
432
|
+
};
|
|
433
|
+
for (const f of readdirSync(boardsDir)) {
|
|
434
|
+
if (!isBoardFile(f)) continue;
|
|
435
|
+
const file = join(boardsDir, f);
|
|
436
|
+
if (!isRegularFile(file)) {
|
|
437
|
+
skipped.push(f);
|
|
438
|
+
continue;
|
|
439
|
+
}
|
|
440
|
+
const content = readFileSync(file, "utf8");
|
|
441
|
+
boards.push({
|
|
442
|
+
name: f.slice(0, -5),
|
|
443
|
+
file,
|
|
444
|
+
content,
|
|
445
|
+
sha256: hash(content),
|
|
446
|
+
...parseBoard(content)
|
|
447
|
+
});
|
|
448
|
+
}
|
|
449
|
+
return {
|
|
450
|
+
boards,
|
|
451
|
+
skipped
|
|
452
|
+
};
|
|
453
|
+
}
|
|
454
|
+
function boardFields(json, validName) {
|
|
455
|
+
const o = json;
|
|
456
|
+
const title = readTitle(o?.title);
|
|
457
|
+
const description = readDescription(o?.description);
|
|
458
|
+
const type = readType(o?.type), capability = readCapability(o?.capability), status = readStatusWord(o?.status), reason = readReason(o?.reason);
|
|
459
|
+
return {
|
|
460
|
+
...typeof o?.order === "number" && Number.isFinite(o.order) ? { order: o.order } : {},
|
|
461
|
+
...validName(o?.folder) ? { folder: o.folder } : {},
|
|
462
|
+
...title ? { title } : {},
|
|
463
|
+
...description ? { description } : {},
|
|
464
|
+
...type ? { type } : {},
|
|
465
|
+
...capability ? { capability } : {},
|
|
466
|
+
...status ? { status } : {},
|
|
467
|
+
...reason ? { reason } : {}
|
|
468
|
+
};
|
|
469
|
+
}
|
|
470
|
+
/** The fields a board's file owns that the shell's save shape never carries: an autosave keeps
|
|
471
|
+
* each one from disk when the incoming board omits it (spec 20 - the fields survive every write). */
|
|
472
|
+
const AUTHOR_FIELDS = [
|
|
473
|
+
"order",
|
|
474
|
+
"folder",
|
|
475
|
+
"title",
|
|
476
|
+
"description",
|
|
477
|
+
"type",
|
|
478
|
+
"capability",
|
|
479
|
+
"status",
|
|
480
|
+
"reason"
|
|
481
|
+
];
|
|
482
|
+
/** The folder registry. `sha256` is the CAS token a tree write must echo (null = "there was
|
|
483
|
+
* no file"), so a write can never silently replace a registry it never saw. */
|
|
484
|
+
function readRegistry(boardsDir) {
|
|
485
|
+
const p = join(boardsDir, FOLDERS_FILE);
|
|
486
|
+
if (!nodeExists(p)) return {
|
|
487
|
+
state: "absent",
|
|
488
|
+
folders: [],
|
|
489
|
+
sha256: null
|
|
490
|
+
};
|
|
491
|
+
if (!isRegularFile(p)) return {
|
|
492
|
+
state: "malformed",
|
|
493
|
+
error: `design/boards/${FOLDERS_FILE} must be a regular file, not a symlink`,
|
|
494
|
+
sha256: null
|
|
495
|
+
};
|
|
496
|
+
const content = readFileSync(p, "utf8");
|
|
497
|
+
let raw;
|
|
498
|
+
try {
|
|
499
|
+
raw = JSON.parse(content);
|
|
500
|
+
} catch {
|
|
501
|
+
return {
|
|
502
|
+
state: "malformed",
|
|
503
|
+
error: `design/boards/${FOLDERS_FILE} is not valid JSON - fix the file`,
|
|
504
|
+
sha256: hash(content)
|
|
505
|
+
};
|
|
506
|
+
}
|
|
507
|
+
const parsed = parseFolders(raw);
|
|
508
|
+
if (typeof parsed === "string") return {
|
|
509
|
+
state: "malformed",
|
|
510
|
+
error: `design/boards/${FOLDERS_FILE}: ${parsed}`,
|
|
511
|
+
sha256: hash(content)
|
|
512
|
+
};
|
|
513
|
+
return {
|
|
514
|
+
state: "ok",
|
|
515
|
+
folders: parsed,
|
|
516
|
+
sha256: hash(content)
|
|
517
|
+
};
|
|
518
|
+
}
|
|
519
|
+
/** The registry's write lock - one writer at a time across processes (the dev server's tree write,
|
|
520
|
+
* `folders add`, `init --kind`), so a read-modify-write of `_folders.json` is atomic among Marver's
|
|
521
|
+
* writers. A lock older than 10 s is a crashed writer's and is taken over. `wait` = how long to
|
|
522
|
+
* try (the CLI waits; the dev server never blocks its event loop - it answers 409 instead). */
|
|
523
|
+
const REGISTRY_LOCK = ".folders.lock";
|
|
524
|
+
function withRegistryLock(dir, wait, fn) {
|
|
525
|
+
const lock = join(dir, REGISTRY_LOCK);
|
|
526
|
+
const t0 = Date.now();
|
|
527
|
+
for (;;) try {
|
|
528
|
+
writeFileSync(lock, `${process.pid} ${Date.now()}\n`, { flag: "wx" });
|
|
529
|
+
break;
|
|
530
|
+
} catch (e) {
|
|
531
|
+
if (e.code !== "EEXIST") throw e;
|
|
532
|
+
try {
|
|
533
|
+
if (Date.now() - lstatSync(lock).mtimeMs > 1e4) {
|
|
534
|
+
rmSync(lock, { force: true });
|
|
535
|
+
continue;
|
|
536
|
+
}
|
|
537
|
+
} catch {
|
|
538
|
+
continue;
|
|
539
|
+
}
|
|
540
|
+
if (Date.now() - t0 >= wait) return null;
|
|
541
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
|
|
542
|
+
}
|
|
543
|
+
try {
|
|
544
|
+
return fn();
|
|
545
|
+
} finally {
|
|
546
|
+
rmSync(lock, { force: true });
|
|
547
|
+
}
|
|
548
|
+
}
|
|
549
|
+
/** Append typed folders to the registry (spec 20: `init --kind`, `folders add`). Never renames,
|
|
550
|
+
* moves or retypes a folder that exists - a name already registered is skipped and reported - and
|
|
551
|
+
* never drops a field of an existing entry it does not manage. New folders rank after everything
|
|
552
|
+
* already at the root. The write is compare-and-swap: the registry is re-read just before the
|
|
553
|
+
* atomic rename, and a change since the first read (the shell's drag, another agent) starts the
|
|
554
|
+
* append over from the new file. A malformed registry is an error, never overwritten. */
|
|
555
|
+
function addFolders(root, folders) {
|
|
556
|
+
const dir = join(root, "design", "boards");
|
|
557
|
+
const de = checkBoardsDir(root, dir);
|
|
558
|
+
if (de) throw new Error(de);
|
|
559
|
+
mkdirSync(dir, { recursive: true });
|
|
560
|
+
const file = join(dir, FOLDERS_FILE);
|
|
561
|
+
const done = withRegistryLock(dir, 5e3, () => appendFolders(dir, file, folders));
|
|
562
|
+
if (!done) throw new Error(`design/boards/${FOLDERS_FILE} is being written by another process - try again`);
|
|
563
|
+
return done;
|
|
564
|
+
}
|
|
565
|
+
function appendFolders(dir, file, folders) {
|
|
566
|
+
for (let attempt = 0; attempt < 5; attempt++) {
|
|
567
|
+
const before = nodeExists(file) ? readFileSync(file, "utf8") : null;
|
|
568
|
+
const reg = readRegistry(dir);
|
|
569
|
+
if (reg.state === "malformed") throw new Error(reg.error);
|
|
570
|
+
let raw = [];
|
|
571
|
+
if (before !== null) {
|
|
572
|
+
const j = JSON.parse(before);
|
|
573
|
+
raw = Array.isArray(j.folders) ? j.folders : [];
|
|
574
|
+
}
|
|
575
|
+
const have = new Set(raw.map((f) => f.name));
|
|
576
|
+
const rootRanks = [...raw.filter((f) => f.parent === void 0).map((f) => f.order), ...listBoardFiles(dir).boards.map((b) => {
|
|
577
|
+
const o = b.json;
|
|
578
|
+
return o?.folder ? void 0 : o?.order;
|
|
579
|
+
})].filter((o) => typeof o === "number" && Number.isFinite(o));
|
|
580
|
+
let next = rootRanks.length ? Math.max(...rootRanks) + 1 : 0;
|
|
581
|
+
const added = [], existing = [];
|
|
582
|
+
const rows = [...raw];
|
|
583
|
+
for (const f of folders) {
|
|
584
|
+
if (have.has(f.name)) {
|
|
585
|
+
existing.push(f.name);
|
|
586
|
+
continue;
|
|
587
|
+
}
|
|
588
|
+
rows.push({
|
|
589
|
+
name: f.name,
|
|
590
|
+
order: next++,
|
|
591
|
+
...f.title ? { title: f.title } : {},
|
|
592
|
+
...f.type ? { type: f.type } : {}
|
|
593
|
+
});
|
|
594
|
+
have.add(f.name);
|
|
595
|
+
added.push(f.name);
|
|
596
|
+
}
|
|
597
|
+
if (!added.length) return {
|
|
598
|
+
added,
|
|
599
|
+
existing
|
|
600
|
+
};
|
|
601
|
+
const version = rows.some((f) => f.parent !== void 0) ? 2 : 1;
|
|
602
|
+
const tmp = `${file}.${process.pid}.${Date.now()}.${attempt}.tmp`;
|
|
603
|
+
writeFileSync(tmp, JSON.stringify({
|
|
604
|
+
version,
|
|
605
|
+
folders: rows
|
|
606
|
+
}, null, 2) + "\n", { flag: "wx" });
|
|
607
|
+
if ((nodeExists(file) ? readFileSync(file, "utf8") : null) !== before) {
|
|
608
|
+
rmSync(tmp, { force: true });
|
|
609
|
+
continue;
|
|
610
|
+
}
|
|
611
|
+
renameSync(tmp, file);
|
|
612
|
+
return {
|
|
613
|
+
added,
|
|
614
|
+
existing
|
|
615
|
+
};
|
|
616
|
+
}
|
|
617
|
+
throw new Error(`design/boards/${FOLDERS_FILE} kept changing while folders were added - try again`);
|
|
618
|
+
}
|
|
619
|
+
//#endregion
|
|
620
|
+
export { knownType as A, wireKids as C, HAS_STATUS as D, FOLDER_MODULES as E, resolveType as F, settableStatuses as I, hash as L, readReason as M, readStatusWord as N, KIND_FOLDERS as O, readType as P, validateWire as S, DECISIONS as T, folderMap as _, checkRealDirs as a, readDescription as b, nodeExists as c, withRegistryLock as d, BOARD_NAME as f, folderEntries as g, flatten as h, checkBoardsDir as i, readCapability as j, PROPOSED_PUBLISH as k, parseBoard as l, buildTree as m, addFolders as n, isRegularFile as o, FOLDERS_FILE as p, boardFields as r, listBoardFiles as s, AUTHOR_FIELDS as t, readRegistry as u, humanize as v, BOARD_TYPES as w, readTitle as x, isBoardName as y };
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { r as NAME } from "./cli.mjs";
|
|
2
|
-
import {
|
|
2
|
+
import { A as knownType, E as FOLDER_MODULES, F as resolveType, _ as folderMap, a as checkRealDirs, h as flatten, i as checkBoardsDir, j as readCapability, m as buildTree, n as addFolders, r as boardFields, s as listBoardFiles, u as readRegistry, v as humanize, w as BOARD_TYPES, y as isBoardName } from "./boards-BRLnoTC3.mjs";
|
|
3
|
+
import { a as PHASE_LABEL, s as STATUS_LABEL, t as annotateBoards } from "./board-status-BZSzc9Hp.mjs";
|
|
3
4
|
import { existsSync, mkdirSync, writeFileSync } from "node:fs";
|
|
4
5
|
import { join } from "node:path";
|
|
5
6
|
//#region src/cli/boards.ts
|
|
@@ -18,7 +19,8 @@ function boardsCommand(root, opts) {
|
|
|
18
19
|
if (reg.state === "malformed") throw new Error(reg.error);
|
|
19
20
|
const rows = boards.map((b) => ({
|
|
20
21
|
name: b.name,
|
|
21
|
-
...boardFields(b.json, isBoardName)
|
|
22
|
+
...boardFields(b.json, isBoardName),
|
|
23
|
+
...b.error ? { error: b.error } : {}
|
|
22
24
|
}));
|
|
23
25
|
const tree = buildTree(rows, reg.folders);
|
|
24
26
|
const hasAll = boards.some((b) => b.name === "all-scenes");
|
|
@@ -29,11 +31,13 @@ function boardsCommand(root, opts) {
|
|
|
29
31
|
...r,
|
|
30
32
|
...notes.get(r.name) ?? {}
|
|
31
33
|
}));
|
|
34
|
+
const invalid = Object.fromEntries(boards.flatMap((b) => b.error ? [[b.name, b.error]] : []));
|
|
32
35
|
console.log(JSON.stringify({
|
|
33
36
|
tree,
|
|
34
37
|
boards: out,
|
|
35
38
|
landing: flatten(tree)[0] ?? (hasAll ? "all-scenes" : null),
|
|
36
|
-
registry: reg.state === "ok" ? "design/boards/_folders.json" : null
|
|
39
|
+
registry: reg.state === "ok" ? "design/boards/_folders.json" : null,
|
|
40
|
+
...Object.keys(invalid).length ? { invalid } : {}
|
|
37
41
|
}, null, 2));
|
|
38
42
|
return;
|
|
39
43
|
}
|
|
@@ -53,9 +57,13 @@ function boardsCommand(root, opts) {
|
|
|
53
57
|
const st = a.status ? ` · ${STATUS_LABEL[a.status.status]}${a.status.fill ? ` (${PHASE_LABEL[a.status.fill]})` : ""}${a.status.reason ? `: ${a.status.reason}` : ""}` : "";
|
|
54
58
|
return a.type === "plain" && !st ? "" : ` [${a.type}${st}]`;
|
|
55
59
|
};
|
|
60
|
+
const bad = (n) => {
|
|
61
|
+
const e = boards.find((b) => b.name === n)?.error;
|
|
62
|
+
return e ? ` (invalid JSON: ${e})` : "";
|
|
63
|
+
};
|
|
56
64
|
const boardLine = (n) => {
|
|
57
65
|
const r = rows.find((x) => x.name === n);
|
|
58
|
-
return `${n}${title(r?.title)}${kind(n)}${order(n)}${desc(r?.description)}`;
|
|
66
|
+
return `${n}${bad(n)}${title(r?.title)}${kind(n)}${order(n)}${desc(r?.description)}`;
|
|
59
67
|
};
|
|
60
68
|
const count = (f) => {
|
|
61
69
|
const boards = f.items.filter((k) => k.kind === "board").length, subs = f.items.length - boards;
|
|
@@ -75,7 +83,7 @@ function boardsCommand(root, opts) {
|
|
|
75
83
|
}
|
|
76
84
|
};
|
|
77
85
|
print(tree, "", null);
|
|
78
|
-
if (hasAll) console.log("all-scenes (auto, always last)
|
|
86
|
+
if (hasAll) console.log(`all-scenes${bad("all-scenes")} (auto, always last)`);
|
|
79
87
|
const landing = flatten(tree)[0];
|
|
80
88
|
if (landing) console.log(`\nlanding board: ${landing}`);
|
|
81
89
|
console.log(`registry: ${reg.state === "ok" ? "design/boards/_folders.json" : "none (no empty or ranked folders yet)"}`);
|