@diagc/cli 1.1.5 → 1.1.7
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/dist/api/assets.d.ts +8 -0
- package/dist/api/assets.js +54 -0
- package/dist/api/diagrams.d.ts +27 -0
- package/dist/api/diagrams.js +269 -0
- package/dist/api/files.d.ts +7 -0
- package/dist/api/files.js +30 -0
- package/dist/api/handlers.d.ts +7 -62
- package/dist/api/handlers.js +10 -470
- package/dist/api/library.d.ts +5 -0
- package/dist/api/library.js +88 -0
- package/dist/api/result.d.ts +8 -0
- package/dist/api/result.js +5 -0
- package/dist/api/sidecars.d.ts +13 -0
- package/dist/api/sidecars.js +78 -0
- package/dist/cli/command.d.ts +26 -0
- package/dist/cli/command.js +1 -0
- package/dist/cli/io.d.ts +13 -0
- package/dist/cli/io.js +7 -0
- package/dist/cli/parse.d.ts +51 -0
- package/dist/cli/parse.js +109 -0
- package/dist/cli/run.d.ts +10 -0
- package/dist/cli/run.js +67 -0
- package/dist/cli.d.ts +1 -52
- package/dist/cli.js +13 -474
- package/dist/commands/compile.d.ts +3 -0
- package/dist/commands/compile.js +38 -0
- package/dist/commands/diff.d.ts +10 -0
- package/dist/commands/diff.js +96 -0
- package/dist/commands/eject.d.ts +3 -0
- package/dist/commands/eject.js +32 -0
- package/dist/commands/guide.d.ts +3 -0
- package/dist/commands/guide.js +13 -0
- package/dist/commands/init.d.ts +3 -0
- package/dist/commands/init.js +23 -0
- package/dist/commands/lint.d.ts +3 -0
- package/dist/commands/lint.js +27 -0
- package/dist/commands/publish.d.ts +11 -0
- package/dist/commands/publish.js +83 -0
- package/dist/commands/shared.d.ts +19 -0
- package/dist/commands/shared.js +34 -0
- package/dist/commands/studio.d.ts +3 -0
- package/dist/commands/studio.js +14 -0
- package/dist/commands/watch.d.ts +8 -0
- package/dist/commands/watch.js +45 -0
- package/dist/compile.d.ts +4 -1
- package/dist/compile.js +8 -13
- package/dist/diff/compare.d.ts +36 -0
- package/dist/diff/compare.js +36 -0
- package/dist/diff/describe.d.ts +8 -0
- package/dist/diff/describe.js +70 -0
- package/dist/diff/index.d.ts +4 -0
- package/dist/diff/index.js +6 -0
- package/dist/diff/load.d.ts +22 -0
- package/dist/diff/load.js +62 -0
- package/dist/diff/overview.d.ts +17 -0
- package/dist/diff/overview.js +86 -0
- package/dist/diff/pages.d.ts +27 -0
- package/dist/diff/pages.js +55 -0
- package/dist/diff/summary.d.ts +18 -0
- package/dist/diff/summary.js +26 -0
- package/dist/eject.js +2 -6
- package/dist/git-ref.js +21 -3
- package/dist/glob.d.ts +5 -0
- package/dist/glob.js +7 -0
- package/dist/init.d.ts +0 -3
- package/dist/init.js +14 -15
- package/dist/names.d.ts +3 -0
- package/dist/names.js +8 -0
- package/dist/paths.d.ts +29 -0
- package/dist/paths.js +25 -0
- package/dist/publish/discover.js +2 -1
- package/dist/publish/publish.d.ts +6 -4
- package/dist/publish/publish.js +11 -7
- package/dist/snapshots.d.ts +11 -0
- package/dist/snapshots.js +20 -3
- package/dist/studio.js +8 -8
- package/package.json +2 -2
- package/dist/command-args.d.ts +0 -9
- package/dist/command-args.js +0 -56
- package/dist/diff.d.ts +0 -61
- package/dist/diff.js +0 -244
package/dist/api/handlers.js
CHANGED
|
@@ -1,471 +1,11 @@
|
|
|
1
|
-
|
|
2
|
-
import
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
1
|
+
// The studio API's handlers, one module per subject. Hosts take this module whole:
|
|
2
|
+
// `typeof import('./handlers.js')` is the `Handlers` type `dispatch` passes around, and
|
|
3
|
+
// the Obsidian vault host imports the file by path. So each export is named, and a
|
|
4
|
+
// helper one subject module exports to another does not become part of that type.
|
|
5
|
+
export { MAX_ASSET_BYTES, readAsset, saveAsset } from './assets.js';
|
|
6
|
+
export { ejectDiagramSource, listDiagramModels, readComposedDiagram, readDiagram, renameDiagram, saveDiagram, } from './diagrams.js';
|
|
7
|
+
export { walkDiagramJson, walkFiles } from './files.js';
|
|
8
|
+
export { readLibrary, saveLibrary } from './library.js';
|
|
9
|
+
export { listDrawings, listLayouts, saveDrawings, saveLayout } from './sidecars.js';
|
|
10
10
|
// The name rule every route checks, for the hosts and tests that reach it here.
|
|
11
|
-
export { isSafeName };
|
|
12
|
-
// path.dirname(diagramsDir) is the .diagrams root when diagramsDir is
|
|
13
|
-
// .diagrams/src — the same rootDir a locked session uses elsewhere (eject.ts).
|
|
14
|
-
// 'locked' because the boot/refresh path must never fetch or vendor a remote
|
|
15
|
-
// include on a viewer's behalf — that only happens at `diagc compile`.
|
|
16
|
-
const lockedResolver = (diagramsDir) => snapshotSession(resolveInclude, path.dirname(diagramsDir), 'locked').resolver;
|
|
17
|
-
const hasIncludes = (m) => m !== null && Array.isArray(m.nodes) && m.nodes.some((n) => n.include !== undefined);
|
|
18
|
-
/** Recursively collect every file under `dir` whose name ends in `suffix`,
|
|
19
|
-
* posix-joined relative to `dir` with the suffix stripped. Missing dir → [].
|
|
20
|
-
* Shared by the diagram-source and layout-overlay walks. */
|
|
21
|
-
export async function walkFiles(dir, suffix) {
|
|
22
|
-
const names = [];
|
|
23
|
-
const walk = async (d, prefix) => {
|
|
24
|
-
let entries;
|
|
25
|
-
try {
|
|
26
|
-
entries = await readdir(d, { withFileTypes: true });
|
|
27
|
-
}
|
|
28
|
-
catch {
|
|
29
|
-
return;
|
|
30
|
-
}
|
|
31
|
-
for (const e of entries) {
|
|
32
|
-
if (e.isDirectory())
|
|
33
|
-
await walk(path.join(d, e.name), `${prefix}${e.name}/`);
|
|
34
|
-
else if (e.name.endsWith(suffix))
|
|
35
|
-
names.push(`${prefix}${e.name.slice(0, -suffix.length)}`);
|
|
36
|
-
}
|
|
37
|
-
};
|
|
38
|
-
await walk(dir, '');
|
|
39
|
-
return names;
|
|
40
|
-
}
|
|
41
|
-
/** Recursively collect `<name>` for every `*.diagram.json` under `dir`
|
|
42
|
-
* (posix-joined, suffix stripped). Missing dir → []. */
|
|
43
|
-
export async function walkDiagramJson(dir) {
|
|
44
|
-
return walkFiles(dir, '.diagram.json');
|
|
45
|
-
}
|
|
46
|
-
/** Render-ready models for the studio boot: JSON sources (editable) served from
|
|
47
|
-
* `diagramsDir`, compiled TS artifacts from `artifactsDir`. A source shadows its
|
|
48
|
-
* artifact so unsaved-compile staleness never shows. */
|
|
49
|
-
export async function listDiagramModels(diagramsDir, artifactsDir) {
|
|
50
|
-
const sourceNames = new Set(await walkDiagramJson(diagramsDir));
|
|
51
|
-
const artifactNames = await walkDiagramJson(artifactsDir);
|
|
52
|
-
const all = [...new Set([...sourceNames, ...artifactNames])].sort();
|
|
53
|
-
const diagrams = [];
|
|
54
|
-
for (const name of all) {
|
|
55
|
-
const isSource = sourceNames.has(name);
|
|
56
|
-
// Every read and save refuses a name isSafeName refuses, so such a source is shown but not offered for editing.
|
|
57
|
-
const editable = isSource && isSafeName(name);
|
|
58
|
-
const file = isSource
|
|
59
|
-
? path.join(diagramsDir, `${name}.diagram.json`)
|
|
60
|
-
: path.join(artifactsDir, `${name}.diagram.json`);
|
|
61
|
-
let model = null;
|
|
62
|
-
const issues = [];
|
|
63
|
-
if (isSource && !editable) {
|
|
64
|
-
issues.push({
|
|
65
|
-
message: `'${name}' is read-only here: the studio saves names of lowercase letters, digits, '-' and '/', none ending in /rename, /eject or /composed. Rename the file to edit it.`,
|
|
66
|
-
});
|
|
67
|
-
}
|
|
68
|
-
try {
|
|
69
|
-
model = JSON.parse(await readFile(file, 'utf8'));
|
|
70
|
-
}
|
|
71
|
-
catch {
|
|
72
|
-
issues.push({ message: `Could not read model for '${name}'` });
|
|
73
|
-
}
|
|
74
|
-
if (isSource && hasIncludes(model)) {
|
|
75
|
-
try {
|
|
76
|
-
const { model: composed, warnings } = await composeIncludes(model, path.resolve(file), lockedResolver(diagramsDir));
|
|
77
|
-
// compileFile refuses an invalid composed result outright, because the
|
|
78
|
-
// renderer assumes a validated model — an id collision
|
|
79
|
-
// between an umbrella-declared node and a namespaced include can pass
|
|
80
|
-
// composeIncludes (which only grafts) while still being invalid, so
|
|
81
|
-
// this must be checked here too, not just on compile.
|
|
82
|
-
const validationIssues = validate(composed);
|
|
83
|
-
if (validationIssues.length > 0) {
|
|
84
|
-
// fall back to the raw model (include nodes as placeholders); it
|
|
85
|
-
// still renders, unlike the unsound composed result
|
|
86
|
-
issues.push(...validationIssues);
|
|
87
|
-
}
|
|
88
|
-
else {
|
|
89
|
-
model = composed;
|
|
90
|
-
for (const w of warnings)
|
|
91
|
-
issues.push({ message: w });
|
|
92
|
-
}
|
|
93
|
-
}
|
|
94
|
-
catch (e) {
|
|
95
|
-
// the raw model still renders (include nodes as placeholders); say why
|
|
96
|
-
issues.push({ message: `Includes not expanded: ${errMessage(e)}` });
|
|
97
|
-
}
|
|
98
|
-
}
|
|
99
|
-
diagrams.push({ name, model, issues, editable });
|
|
100
|
-
}
|
|
101
|
-
return { status: 200, body: { diagrams } };
|
|
102
|
-
}
|
|
103
|
-
/** All layout overlays under `diagramsDir`, keyed by diagram name. Corrupt
|
|
104
|
-
* overlays are skipped, never fatal. */
|
|
105
|
-
export async function listLayouts(diagramsDir) {
|
|
106
|
-
const layouts = {};
|
|
107
|
-
for (const name of await walkFiles(diagramsDir, '.layout.json')) {
|
|
108
|
-
try {
|
|
109
|
-
layouts[name] = JSON.parse(await readFile(path.join(diagramsDir, `${name}.layout.json`), 'utf8'));
|
|
110
|
-
}
|
|
111
|
-
catch {
|
|
112
|
-
/* skip corrupt overlay */
|
|
113
|
-
}
|
|
114
|
-
}
|
|
115
|
-
return { status: 200, body: { layouts } };
|
|
116
|
-
}
|
|
117
|
-
/** All drawings sidecars under `diagramsDir`, keyed by diagram name. Corrupt
|
|
118
|
-
* files are skipped, never fatal — same contract as listLayouts. */
|
|
119
|
-
export async function listDrawings(diagramsDir) {
|
|
120
|
-
const drawings = {};
|
|
121
|
-
for (const name of await walkFiles(diagramsDir, '.drawings.json')) {
|
|
122
|
-
try {
|
|
123
|
-
drawings[name] = JSON.parse(await readFile(path.join(diagramsDir, `${name}.drawings.json`), 'utf8'));
|
|
124
|
-
}
|
|
125
|
-
catch {
|
|
126
|
-
/* skip corrupt sidecar */
|
|
127
|
-
}
|
|
128
|
-
}
|
|
129
|
-
return { status: 200, body: { drawings } };
|
|
130
|
-
}
|
|
131
|
-
/** the JSON source (+ sibling layout and drawings) of a designer-owned diagram — the studio
|
|
132
|
-
* reads these directly so it never depends on a compile watcher for its own files */
|
|
133
|
-
export async function readDiagram(diagramsDir, name) {
|
|
134
|
-
if (!isSafeName(name))
|
|
135
|
-
return { status: 400, body: { issues: [{ message: `Unsafe name '${name}'` }] } };
|
|
136
|
-
let model;
|
|
137
|
-
try {
|
|
138
|
-
model = JSON.parse(await readFile(path.join(diagramsDir, `${name}.diagram.json`), 'utf8'));
|
|
139
|
-
}
|
|
140
|
-
catch {
|
|
141
|
-
return { status: 404, body: { issues: [{ message: `No diagram source '${name}'` }] } };
|
|
142
|
-
}
|
|
143
|
-
let layout;
|
|
144
|
-
try {
|
|
145
|
-
layout = JSON.parse(await readFile(path.join(diagramsDir, `${name}.layout.json`), 'utf8'));
|
|
146
|
-
}
|
|
147
|
-
catch {
|
|
148
|
-
layout = undefined;
|
|
149
|
-
}
|
|
150
|
-
let drawings;
|
|
151
|
-
try {
|
|
152
|
-
drawings = JSON.parse(await readFile(path.join(diagramsDir, `${name}.drawings.json`), 'utf8'));
|
|
153
|
-
}
|
|
154
|
-
catch {
|
|
155
|
-
drawings = undefined;
|
|
156
|
-
}
|
|
157
|
-
return {
|
|
158
|
-
status: 200,
|
|
159
|
-
body: {
|
|
160
|
-
model,
|
|
161
|
-
...(layout !== undefined ? { layout } : {}),
|
|
162
|
-
...(drawings !== undefined ? { drawings } : {}),
|
|
163
|
-
},
|
|
164
|
-
};
|
|
165
|
-
}
|
|
166
|
-
/** Composed read of an editable source — the studio's view-refresh after a
|
|
167
|
-
* save. Sources without includes pass through untouched. */
|
|
168
|
-
export async function readComposedDiagram(diagramsDir, name) {
|
|
169
|
-
if (!isSafeName(name))
|
|
170
|
-
return { status: 400, body: { issues: [{ message: `Unsafe name '${name}'` }] } };
|
|
171
|
-
const file = path.join(diagramsDir, `${name}.diagram.json`);
|
|
172
|
-
let model;
|
|
173
|
-
try {
|
|
174
|
-
model = JSON.parse(await readFile(file, 'utf8'));
|
|
175
|
-
}
|
|
176
|
-
catch {
|
|
177
|
-
return { status: 404, body: { issues: [{ message: `No diagram source '${name}'` }] } };
|
|
178
|
-
}
|
|
179
|
-
if (!hasIncludes(model))
|
|
180
|
-
return { status: 200, body: { model } };
|
|
181
|
-
try {
|
|
182
|
-
const { model: composed, warnings } = await composeIncludes(model, path.resolve(file), lockedResolver(diagramsDir));
|
|
183
|
-
// Same soundness check as listDiagramModels: a composed model that fails
|
|
184
|
-
// validation must never reach the renderer, so refuse it like a failed
|
|
185
|
-
// compose instead of returning 200 with an unsound model.
|
|
186
|
-
const issues = validate(composed);
|
|
187
|
-
if (issues.length > 0)
|
|
188
|
-
return { status: 409, body: { issues } };
|
|
189
|
-
return { status: 200, body: { model: composed, ...(warnings.length > 0 ? { warnings } : {}) } };
|
|
190
|
-
}
|
|
191
|
-
catch (e) {
|
|
192
|
-
return { status: 409, body: { issues: [{ message: errMessage(e) }] } };
|
|
193
|
-
}
|
|
194
|
-
}
|
|
195
|
-
export async function saveDiagram(diagramsDir, name, payload) {
|
|
196
|
-
if (!isSafeName(name))
|
|
197
|
-
return { status: 400, body: { issues: [{ message: `Unsafe name '${name}'` }] } };
|
|
198
|
-
const p = payload;
|
|
199
|
-
const arraysOk = p !== null &&
|
|
200
|
-
p.version === 1 &&
|
|
201
|
-
Array.isArray(p.nodes) &&
|
|
202
|
-
Array.isArray(p.containment) &&
|
|
203
|
-
Array.isArray(p.relations) &&
|
|
204
|
-
Array.isArray(p.layers) &&
|
|
205
|
-
Array.isArray(p.planes);
|
|
206
|
-
if (!arraysOk) {
|
|
207
|
-
return { status: 400, body: { issues: [{ message: 'Not a version-1 diagram model' }] } };
|
|
208
|
-
}
|
|
209
|
-
const issues = validate(payload);
|
|
210
|
-
if (issues.length > 0)
|
|
211
|
-
return { status: 400, body: { issues } };
|
|
212
|
-
const target = path.join(diagramsDir, `${name}.diagram.json`);
|
|
213
|
-
await mkdir(path.dirname(target), { recursive: true });
|
|
214
|
-
await writeFileAtomic(target, `${JSON.stringify(payload, null, 2)}\n`);
|
|
215
|
-
return { status: 200, body: { ok: true } };
|
|
216
|
-
}
|
|
217
|
-
/** Move a designer-owned diagram (and its sibling layout, if any) to a new name,
|
|
218
|
-
* rewriting the model's id to match so the file stays self-consistent. */
|
|
219
|
-
export async function renameDiagram(diagramsDir, from, to) {
|
|
220
|
-
if (!isSafeName(from) || !isSafeName(to)) {
|
|
221
|
-
return { status: 400, body: { issues: [{ message: `Unsafe name '${isSafeName(from) ? to : from}'` }] } };
|
|
222
|
-
}
|
|
223
|
-
if (from === to)
|
|
224
|
-
return { status: 400, body: { issues: [{ message: 'New name is the same as the old' }] } };
|
|
225
|
-
const fromDiagram = path.join(diagramsDir, `${from}.diagram.json`);
|
|
226
|
-
const toDiagram = path.join(diagramsDir, `${to}.diagram.json`);
|
|
227
|
-
let raw;
|
|
228
|
-
try {
|
|
229
|
-
raw = await readFile(fromDiagram, 'utf8');
|
|
230
|
-
}
|
|
231
|
-
catch {
|
|
232
|
-
return { status: 404, body: { issues: [{ message: `No diagram source '${from}'` }] } };
|
|
233
|
-
}
|
|
234
|
-
try {
|
|
235
|
-
await access(toDiagram);
|
|
236
|
-
return { status: 409, body: { issues: [{ message: `A diagram named '${to}' already exists` }] } };
|
|
237
|
-
}
|
|
238
|
-
catch {
|
|
239
|
-
/* target free — proceed */
|
|
240
|
-
}
|
|
241
|
-
let model;
|
|
242
|
-
try {
|
|
243
|
-
model = JSON.parse(raw);
|
|
244
|
-
}
|
|
245
|
-
catch {
|
|
246
|
-
return { status: 400, body: { issues: [{ message: `Corrupt diagram source '${from}'` }] } };
|
|
247
|
-
}
|
|
248
|
-
// The id follows the file. The name is the diagram's title, so it follows only
|
|
249
|
-
// when it was the id, a title nobody set.
|
|
250
|
-
if (model['name'] === model['id'])
|
|
251
|
-
model['name'] = to;
|
|
252
|
-
model['id'] = to;
|
|
253
|
-
await mkdir(path.dirname(toDiagram), { recursive: true });
|
|
254
|
-
// Sidecars first, the source last, so the old name keeps its source until every
|
|
255
|
-
// other step has worked. A failure undoes the steps before it, in reverse, and
|
|
256
|
-
// the error answers 500.
|
|
257
|
-
const moved = [];
|
|
258
|
-
let written = false;
|
|
259
|
-
try {
|
|
260
|
-
for (const sidecar of ['layout', 'drawings']) {
|
|
261
|
-
const move = [
|
|
262
|
-
path.join(diagramsDir, `${from}.${sidecar}.json`),
|
|
263
|
-
path.join(diagramsDir, `${to}.${sidecar}.json`),
|
|
264
|
-
];
|
|
265
|
-
if (await moveIfPresent(...move))
|
|
266
|
-
moved.push(move);
|
|
267
|
-
}
|
|
268
|
-
await writeFileAtomic(toDiagram, `${JSON.stringify(model, null, 2)}\n`);
|
|
269
|
-
written = true;
|
|
270
|
-
await unlink(fromDiagram);
|
|
271
|
-
}
|
|
272
|
-
catch (e) {
|
|
273
|
-
if (written)
|
|
274
|
-
await unlink(toDiagram).catch(() => { });
|
|
275
|
-
for (const [src, dst] of moved.reverse())
|
|
276
|
-
await rename(dst, src).catch(() => { });
|
|
277
|
-
throw e;
|
|
278
|
-
}
|
|
279
|
-
return { status: 200, body: { ok: true } };
|
|
280
|
-
}
|
|
281
|
-
/** `rename(src, dst)`, false when there is no `src` to move: a diagram need not have
|
|
282
|
-
* a sidecar. Any other failure throws. */
|
|
283
|
-
async function moveIfPresent(src, dst) {
|
|
284
|
-
try {
|
|
285
|
-
await rename(src, dst);
|
|
286
|
-
return true;
|
|
287
|
-
}
|
|
288
|
-
catch (e) {
|
|
289
|
-
if (e.code === 'ENOENT')
|
|
290
|
-
return false;
|
|
291
|
-
throw e;
|
|
292
|
-
}
|
|
293
|
-
}
|
|
294
|
-
/** Promote a JSON-owned diagram to a generated `.diagram.ts`. See `ejectDiagram`
|
|
295
|
-
* for the round-trip guarantee; this just maps its failure codes to statuses. */
|
|
296
|
-
export async function ejectDiagramSource(diagramsDir, artifactsDir, name) {
|
|
297
|
-
if (!isSafeName(name))
|
|
298
|
-
return { status: 400, body: { issues: [{ message: `Unsafe name '${name}'` }] } };
|
|
299
|
-
try {
|
|
300
|
-
await ejectDiagram(diagramsDir, artifactsDir, name);
|
|
301
|
-
return { status: 200, body: { ok: true } };
|
|
302
|
-
}
|
|
303
|
-
catch (e) {
|
|
304
|
-
if (e instanceof EjectError) {
|
|
305
|
-
const status = e.code === 'not-found' ? 404 : e.code === 'invalid' ? 400 : 409;
|
|
306
|
-
return { status, body: { issues: [{ message: e.message }] } };
|
|
307
|
-
}
|
|
308
|
-
throw e;
|
|
309
|
-
}
|
|
310
|
-
}
|
|
311
|
-
export async function saveLayout(diagramsDir, name, payload) {
|
|
312
|
-
if (!isSafeName(name))
|
|
313
|
-
return { status: 400, body: { issues: [{ message: `Unsafe name '${name}'` }] } };
|
|
314
|
-
// Core's structural guard mirrors the old inline checks (version 1, nested
|
|
315
|
-
// numeric x/y planes, optional positive-finite sizes) — one source of truth
|
|
316
|
-
// shared with the client-side artifact loader.
|
|
317
|
-
if (!isLayoutOverlay(payload))
|
|
318
|
-
return { status: 400, body: { issues: [{ message: 'Not a version-1 layout overlay' }] } };
|
|
319
|
-
const target = path.join(diagramsDir, `${name}.layout.json`);
|
|
320
|
-
await mkdir(path.dirname(target), { recursive: true });
|
|
321
|
-
await writeFileAtomic(target, `${JSON.stringify(payload, null, 2)}\n`);
|
|
322
|
-
return { status: 200, body: { ok: true } };
|
|
323
|
-
}
|
|
324
|
-
/** Persist the drawings sidecar. An overlay in which no bucket holds a stroke
|
|
325
|
-
* DELETES the file instead of writing it: a diagram that never had drawings
|
|
326
|
-
* must never grow an empty `<name>.drawings.json`, and erasing the last stroke
|
|
327
|
-
* should leave the tree as it was. */
|
|
328
|
-
export async function saveDrawings(diagramsDir, name, payload) {
|
|
329
|
-
if (!isSafeName(name))
|
|
330
|
-
return { status: 400, body: { issues: [{ message: `Unsafe name '${name}'` }] } };
|
|
331
|
-
if (!isDrawings(payload))
|
|
332
|
-
return { status: 400, body: { issues: [{ message: 'Not a version-1 drawings overlay' }] } };
|
|
333
|
-
const target = path.join(diagramsDir, `${name}.drawings.json`);
|
|
334
|
-
const hasStrokes = Object.values(payload.planes).some((bucket) => bucket.length > 0);
|
|
335
|
-
if (!hasStrokes) {
|
|
336
|
-
try {
|
|
337
|
-
await unlink(target);
|
|
338
|
-
}
|
|
339
|
-
catch (e) {
|
|
340
|
-
// ENOENT only: there was nothing to delete, which is the ordinary case for
|
|
341
|
-
// a diagram that never had ink. Anything else (EACCES, EPERM, EISDIR) means
|
|
342
|
-
// the strokes are still on disk — rethrow so dispatch turns it into a 500
|
|
343
|
-
// and useEditor.save surfaces it, instead of answering `{ ok: true }` and
|
|
344
|
-
// letting the erased strokes resurrect on the next boot.
|
|
345
|
-
if (e.code !== 'ENOENT')
|
|
346
|
-
throw e;
|
|
347
|
-
}
|
|
348
|
-
return { status: 200, body: { ok: true } };
|
|
349
|
-
}
|
|
350
|
-
await mkdir(path.dirname(target), { recursive: true });
|
|
351
|
-
await writeFileAtomic(target, `${JSON.stringify(payload, null, 2)}\n`);
|
|
352
|
-
return { status: 200, body: { ok: true } };
|
|
353
|
-
}
|
|
354
|
-
export async function readLibrary(diagramsDir) {
|
|
355
|
-
try {
|
|
356
|
-
const raw = await readFile(path.join(diagramsDir, 'library.json'), 'utf8');
|
|
357
|
-
return { status: 200, body: JSON.parse(raw) };
|
|
358
|
-
}
|
|
359
|
-
catch {
|
|
360
|
-
return { status: 200, body: { categories: [], entries: [] } };
|
|
361
|
-
}
|
|
362
|
-
}
|
|
363
|
-
// Must cover every NodeTemplate presentation channel — 'shape' included, or a
|
|
364
|
-
// user library holding an imported silhouette is rejected on save.
|
|
365
|
-
const TEMPLATE_STRING_KEYS = new Set(['type', 'color', 'image', 'shape']);
|
|
366
|
-
const TEMPLATE_NUMBER_KEYS = new Set(['width', 'height']);
|
|
367
|
-
/** Persist the whole user library. Validates internal consistency only — bundled
|
|
368
|
-
* packs are merged client-side and never written here. */
|
|
369
|
-
export async function saveLibrary(diagramsDir, payload) {
|
|
370
|
-
const p = payload;
|
|
371
|
-
if (p === null || !Array.isArray(p.categories) || !Array.isArray(p.entries)) {
|
|
372
|
-
return { status: 400, body: { issues: [{ message: 'Not a library { categories, entries }' }] } };
|
|
373
|
-
}
|
|
374
|
-
const catIds = new Set();
|
|
375
|
-
for (const c of p.categories) {
|
|
376
|
-
const cat = c;
|
|
377
|
-
if (typeof cat.id !== 'string' || typeof cat.name !== 'string') {
|
|
378
|
-
return { status: 400, body: { issues: [{ message: 'Category needs string id and name' }] } };
|
|
379
|
-
}
|
|
380
|
-
if (catIds.has(cat.id))
|
|
381
|
-
return { status: 400, body: { issues: [{ message: `Duplicate category '${cat.id}'` }] } };
|
|
382
|
-
catIds.add(cat.id);
|
|
383
|
-
}
|
|
384
|
-
const entryIds = new Set();
|
|
385
|
-
for (const e of p.entries) {
|
|
386
|
-
const entry = e;
|
|
387
|
-
if (typeof entry.id !== 'string' || typeof entry.name !== 'string' || typeof entry.category !== 'string') {
|
|
388
|
-
return { status: 400, body: { issues: [{ message: 'Entry needs string id, name, category' }] } };
|
|
389
|
-
}
|
|
390
|
-
if (!catIds.has(entry.category)) {
|
|
391
|
-
return {
|
|
392
|
-
status: 400,
|
|
393
|
-
body: { issues: [{ message: `Entry '${entry.id}' references unknown category '${entry.category}'` }] },
|
|
394
|
-
};
|
|
395
|
-
}
|
|
396
|
-
if (entryIds.has(entry.id))
|
|
397
|
-
return { status: 400, body: { issues: [{ message: `Duplicate entry '${entry.id}'` }] } };
|
|
398
|
-
entryIds.add(entry.id);
|
|
399
|
-
const t = entry.template;
|
|
400
|
-
if (t === null || typeof t !== 'object' || Array.isArray(t)) {
|
|
401
|
-
return { status: 400, body: { issues: [{ message: `Entry '${entry.id}' missing template` }] } };
|
|
402
|
-
}
|
|
403
|
-
for (const [k, v] of Object.entries(t)) {
|
|
404
|
-
const ok = TEMPLATE_STRING_KEYS.has(k)
|
|
405
|
-
? typeof v === 'string'
|
|
406
|
-
: TEMPLATE_NUMBER_KEYS.has(k)
|
|
407
|
-
? typeof v === 'number'
|
|
408
|
-
: false;
|
|
409
|
-
if (!ok)
|
|
410
|
-
return {
|
|
411
|
-
status: 400,
|
|
412
|
-
body: { issues: [{ message: `Entry '${entry.id}' has invalid template field '${k}'` }] },
|
|
413
|
-
};
|
|
414
|
-
}
|
|
415
|
-
}
|
|
416
|
-
const target = path.join(diagramsDir, 'library.json');
|
|
417
|
-
await mkdir(path.dirname(target), { recursive: true });
|
|
418
|
-
await writeFileAtomic(target, `${JSON.stringify(payload, null, 2)}\n`);
|
|
419
|
-
return { status: 200, body: { ok: true } };
|
|
420
|
-
}
|
|
421
|
-
// Keys here must stay in sync with IMAGE_REF's extension group (@diagc/core) —
|
|
422
|
-
// an extension accepted by the regex but missing here would 404 on read.
|
|
423
|
-
const ASSET_EXT = {
|
|
424
|
-
'image/png': 'png',
|
|
425
|
-
'image/jpeg': 'jpg',
|
|
426
|
-
'image/svg+xml': 'svg',
|
|
427
|
-
'image/webp': 'webp',
|
|
428
|
-
'image/gif': 'gif',
|
|
429
|
-
};
|
|
430
|
-
const ASSET_TYPE = Object.fromEntries(Object.entries(ASSET_EXT).map(([t, e]) => [e, t]));
|
|
431
|
-
export const MAX_ASSET_BYTES = 5 * 1024 * 1024;
|
|
432
|
-
/** store image bytes under their content hash; identical drops dedupe to one file */
|
|
433
|
-
export async function saveAsset(diagramsDir, contentType, bytes) {
|
|
434
|
-
const ext = ASSET_EXT[contentType.split(';')[0]?.trim() ?? ''];
|
|
435
|
-
if (ext === undefined) {
|
|
436
|
-
return { status: 400, body: { issues: [{ message: `Unsupported image type '${contentType}'` }] } };
|
|
437
|
-
}
|
|
438
|
-
if (bytes.length === 0 || bytes.length > MAX_ASSET_BYTES) {
|
|
439
|
-
return {
|
|
440
|
-
status: 400,
|
|
441
|
-
body: { issues: [{ message: `Image must be 1 byte to ${MAX_ASSET_BYTES / 1024 / 1024} MB` }] },
|
|
442
|
-
};
|
|
443
|
-
}
|
|
444
|
-
const name = `${createHash('sha256').update(bytes).digest('hex').slice(0, 12)}.${ext}`;
|
|
445
|
-
const target = path.join(diagramsDir, 'assets', name);
|
|
446
|
-
await mkdir(path.dirname(target), { recursive: true });
|
|
447
|
-
try {
|
|
448
|
-
await access(target); // already stored — content hash guarantees same bytes
|
|
449
|
-
}
|
|
450
|
-
catch {
|
|
451
|
-
await writeFileAtomic(target, bytes);
|
|
452
|
-
}
|
|
453
|
-
return { status: 200, body: { name } };
|
|
454
|
-
}
|
|
455
|
-
export async function readAsset(diagramsDir, name) {
|
|
456
|
-
if (!IMAGE_REF.test(name))
|
|
457
|
-
return { status: 400, body: { issues: [{ message: `Unsafe asset name '${name}'` }] } };
|
|
458
|
-
try {
|
|
459
|
-
const bytes = await readFile(path.join(diagramsDir, 'assets', name));
|
|
460
|
-
const ext = name.split('.').at(-1) ?? '';
|
|
461
|
-
return {
|
|
462
|
-
status: 200,
|
|
463
|
-
body: null,
|
|
464
|
-
bytes,
|
|
465
|
-
contentType: ASSET_TYPE[ext === 'jpeg' ? 'jpg' : ext] ?? 'application/octet-stream',
|
|
466
|
-
};
|
|
467
|
-
}
|
|
468
|
-
catch {
|
|
469
|
-
return { status: 404, body: { issues: [{ message: `No asset '${name}'` }] } };
|
|
470
|
-
}
|
|
471
|
-
}
|
|
11
|
+
export { isSafeName } from '../names.js';
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import { type HandlerResult } from './result.js';
|
|
2
|
+
export declare function readLibrary(diagramsDir: string): Promise<HandlerResult>;
|
|
3
|
+
/** Persist the whole user library. Validates internal consistency only — bundled
|
|
4
|
+
* packs are merged client-side and never written here. */
|
|
5
|
+
export declare function saveLibrary(diagramsDir: string, payload: unknown): Promise<HandlerResult>;
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import { mkdir, readFile } from 'node:fs/promises';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { writeFileAtomic } from '../atomic-write.js';
|
|
4
|
+
import { refuse } from './result.js';
|
|
5
|
+
export async function readLibrary(diagramsDir) {
|
|
6
|
+
try {
|
|
7
|
+
const raw = await readFile(path.join(diagramsDir, 'library.json'), 'utf8');
|
|
8
|
+
return { status: 200, body: JSON.parse(raw) };
|
|
9
|
+
}
|
|
10
|
+
catch {
|
|
11
|
+
return { status: 200, body: { categories: [], entries: [] } };
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
// Must cover every NodeTemplate presentation channel — 'shape' included, or a
|
|
15
|
+
// user library holding an imported silhouette is rejected on save.
|
|
16
|
+
const TEMPLATE_STRING_KEYS = new Set(['type', 'color', 'image', 'shape']);
|
|
17
|
+
const TEMPLATE_NUMBER_KEYS = new Set(['width', 'height']);
|
|
18
|
+
/** The categories' ids, or why they cannot be saved: each needs a string id and
|
|
19
|
+
* name, and no id may come twice. */
|
|
20
|
+
function checkCategories(categories) {
|
|
21
|
+
const ids = new Set();
|
|
22
|
+
for (const c of categories) {
|
|
23
|
+
const cat = c;
|
|
24
|
+
if (typeof cat.id !== 'string' || typeof cat.name !== 'string') {
|
|
25
|
+
return { problem: 'Category needs string id and name' };
|
|
26
|
+
}
|
|
27
|
+
if (ids.has(cat.id))
|
|
28
|
+
return { problem: `Duplicate category '${cat.id}'` };
|
|
29
|
+
ids.add(cat.id);
|
|
30
|
+
}
|
|
31
|
+
return { ids };
|
|
32
|
+
}
|
|
33
|
+
/** Why the entries cannot be saved, or undefined. Each entry is checked whole before
|
|
34
|
+
* the next: its fields, its category, its id, then its template. */
|
|
35
|
+
function checkEntries(entries, categoryIds) {
|
|
36
|
+
const ids = new Set();
|
|
37
|
+
for (const e of entries) {
|
|
38
|
+
const entry = e;
|
|
39
|
+
if (typeof entry.id !== 'string' || typeof entry.name !== 'string' || typeof entry.category !== 'string') {
|
|
40
|
+
return 'Entry needs string id, name, category';
|
|
41
|
+
}
|
|
42
|
+
if (!categoryIds.has(entry.category)) {
|
|
43
|
+
return `Entry '${entry.id}' references unknown category '${entry.category}'`;
|
|
44
|
+
}
|
|
45
|
+
if (ids.has(entry.id))
|
|
46
|
+
return `Duplicate entry '${entry.id}'`;
|
|
47
|
+
ids.add(entry.id);
|
|
48
|
+
const problem = checkTemplate(entry.id, entry.template);
|
|
49
|
+
if (problem !== undefined)
|
|
50
|
+
return problem;
|
|
51
|
+
}
|
|
52
|
+
return undefined;
|
|
53
|
+
}
|
|
54
|
+
/** Why entry `id`'s template cannot be saved, or undefined: it is an object whose
|
|
55
|
+
* every field is a presentation channel of the right type. */
|
|
56
|
+
function checkTemplate(id, template) {
|
|
57
|
+
const t = template;
|
|
58
|
+
if (t === null || typeof t !== 'object' || Array.isArray(t))
|
|
59
|
+
return `Entry '${id}' missing template`;
|
|
60
|
+
for (const [k, v] of Object.entries(t)) {
|
|
61
|
+
const ok = TEMPLATE_STRING_KEYS.has(k)
|
|
62
|
+
? typeof v === 'string'
|
|
63
|
+
: TEMPLATE_NUMBER_KEYS.has(k)
|
|
64
|
+
? typeof v === 'number'
|
|
65
|
+
: false;
|
|
66
|
+
if (!ok)
|
|
67
|
+
return `Entry '${id}' has invalid template field '${k}'`;
|
|
68
|
+
}
|
|
69
|
+
return undefined;
|
|
70
|
+
}
|
|
71
|
+
/** Persist the whole user library. Validates internal consistency only — bundled
|
|
72
|
+
* packs are merged client-side and never written here. */
|
|
73
|
+
export async function saveLibrary(diagramsDir, payload) {
|
|
74
|
+
const p = payload;
|
|
75
|
+
if (p === null || !Array.isArray(p.categories) || !Array.isArray(p.entries)) {
|
|
76
|
+
return refuse(400, 'Not a library { categories, entries }');
|
|
77
|
+
}
|
|
78
|
+
const categories = checkCategories(p.categories);
|
|
79
|
+
if ('problem' in categories)
|
|
80
|
+
return refuse(400, categories.problem);
|
|
81
|
+
const problem = checkEntries(p.entries, categories.ids);
|
|
82
|
+
if (problem !== undefined)
|
|
83
|
+
return refuse(400, problem);
|
|
84
|
+
const target = path.join(diagramsDir, 'library.json');
|
|
85
|
+
await mkdir(path.dirname(target), { recursive: true });
|
|
86
|
+
await writeFileAtomic(target, `${JSON.stringify(payload, null, 2)}\n`);
|
|
87
|
+
return { status: 200, body: { ok: true } };
|
|
88
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/** A handler's answer: the status and the JSON body a host sends as it is. */
|
|
2
|
+
export interface HandlerResult {
|
|
3
|
+
status: number;
|
|
4
|
+
body: unknown;
|
|
5
|
+
}
|
|
6
|
+
/** The answer to a request a handler will not carry out: one issue saying why, the
|
|
7
|
+
* shape the studio reads every refusal in. */
|
|
8
|
+
export declare function refuse(status: number, message: string): HandlerResult;
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { type HandlerResult } from './result.js';
|
|
2
|
+
/** All layout overlays under `diagramsDir`, keyed by diagram name. Corrupt
|
|
3
|
+
* overlays are skipped, never fatal. */
|
|
4
|
+
export declare function listLayouts(diagramsDir: string): Promise<HandlerResult>;
|
|
5
|
+
/** All drawings sidecars under `diagramsDir`, keyed by diagram name. Corrupt
|
|
6
|
+
* files are skipped, never fatal — same contract as listLayouts. */
|
|
7
|
+
export declare function listDrawings(diagramsDir: string): Promise<HandlerResult>;
|
|
8
|
+
export declare function saveLayout(diagramsDir: string, name: string, payload: unknown): Promise<HandlerResult>;
|
|
9
|
+
/** Persist the drawings sidecar. An overlay in which no bucket holds a stroke
|
|
10
|
+
* DELETES the file instead of writing it: a diagram that never had drawings
|
|
11
|
+
* must never grow an empty `<name>.drawings.json`, and erasing the last stroke
|
|
12
|
+
* should leave the tree as it was. */
|
|
13
|
+
export declare function saveDrawings(diagramsDir: string, name: string, payload: unknown): Promise<HandlerResult>;
|