dsh-artifact-studio 0.8.0 → 0.13.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 (43) hide show
  1. package/README.md +72 -10
  2. package/THIRD_PARTY_NOTICES.md +57 -0
  3. package/assets/canvas.engine.js +72 -72
  4. package/assets/canvas.viewer.js +6415 -0
  5. package/client.canvas.js +1 -1
  6. package/client.doc.js +67 -79
  7. package/client.js +313 -291
  8. package/client.sheet.js +218 -0
  9. package/dist/contract.js +32 -5
  10. package/dist/host/lib/assets.js +12 -0
  11. package/dist/host/lib/brief.js +127 -0
  12. package/dist/host/lib/checks.js +62 -8
  13. package/dist/host/lib/design-catalog.js +149 -0
  14. package/dist/host/lib/design-render.js +37 -0
  15. package/dist/host/lib/design-system.js +1 -1
  16. package/dist/host/lib/export.js +123 -5
  17. package/dist/host/lib/fsutil.js +41 -0
  18. package/dist/host/lib/generation.js +36 -0
  19. package/dist/host/lib/guide.js +130 -0
  20. package/dist/host/lib/paths.js +2 -1
  21. package/dist/host/lib/recipes.js +224 -0
  22. package/dist/host/lib/rpc.js +20 -5
  23. package/dist/host/lib/service.js +253 -24
  24. package/dist/host/lib/skill.js +59 -18
  25. package/dist/host/lib/store.js +107 -25
  26. package/dist/host/lib/svg-model.js +85 -0
  27. package/dist/host/lib/svg-viewer.js +380 -0
  28. package/dist/host/lib/tools.js +346 -35
  29. package/dist/host/lib/validate.js +24 -0
  30. package/dist/host/lib/viewer.js +150 -0
  31. package/dist/host/lib/xlsx.js +314 -0
  32. package/dist/host/worker/design-worker.js +71 -5
  33. package/dist/host/worker/page-model.js +169 -0
  34. package/dist/html-tags.js +51 -0
  35. package/dist/kit.js +224 -0
  36. package/dist/render.js +10 -3
  37. package/dist/sheet/formula.js +475 -0
  38. package/dist/sheet/functions.js +463 -0
  39. package/dist/sheet/index.js +9 -0
  40. package/dist/sheet/model.js +695 -0
  41. package/dist/sheet/operations.js +384 -0
  42. package/dist/sheet/output.js +182 -0
  43. package/package.json +15 -3
@@ -1,9 +1,11 @@
1
1
  import { createHash, randomBytes } from 'node:crypto';
2
2
  import fs from 'node:fs/promises';
3
3
  import path from 'node:path';
4
- import { CONTENT_FILE, ID_PATTERN, MAX_LIST_LIMIT, MAX_TITLE, isArtifactType, isManifest, isVersionSource } from '../../contract.js';
4
+ import { CONTENT_FILE, ID_PATTERN, MAX_LIST_LIMIT, MAX_TITLE, isArtifactType, isManifest, isVersionSource, isGenerationSummary } from '../../contract.js';
5
5
  import { ArtifactError, errnoCode } from './errors.js';
6
- import { assertWithin, withLock, writeAtomic } from './fsutil.js';
6
+ import { assertWithin, assertPlainPath, withWriteLock, writeAtomic } from './fsutil.js';
7
+ import { generationText, generationHash, generationSummary, parseGeneration } from './generation.js';
8
+ import { declaredKit, getKit } from '../../kit.js';
7
9
  import { artifactDir, assertPlainFile } from './paths.js';
8
10
  export const DEFAULT_LIMITS = {
9
11
  maxContentBytes: 2 * 1024 * 1024,
@@ -63,7 +65,8 @@ function isVersionEntry(value) {
63
65
  typeof record.createdAt === 'string' &&
64
66
  typeof record.contentHash === 'string' &&
65
67
  typeof record.contentBytes === 'number' &&
66
- isVersionSource(record.source));
68
+ isVersionSource(record.source) &&
69
+ (record.generation === undefined || isGenerationSummary(record.generation)));
67
70
  }
68
71
  /**
69
72
  * Apply replace-once edits to a text.
@@ -181,10 +184,14 @@ export class ArtifactStore {
181
184
  * @param manifest the manifest of that version.
182
185
  * @param content its content.
183
186
  */
184
- async snapshot(root, dir, manifest, content) {
187
+ async snapshot(root, dir, manifest, content, generation) {
185
188
  const versionDir = path.join(dir, 'versions', String(manifest.version));
186
- await assertWithin(root, versionDir);
189
+ await assertPlainPath(root, path.join(versionDir, 'content', manifest.contentFile));
190
+ await assertPlainPath(root, path.join(versionDir, 'meta.json'));
191
+ await assertPlainPath(root, path.join(versionDir, 'generation.json'));
187
192
  await fs.mkdir(path.join(versionDir, 'content'), { recursive: true });
193
+ if (generation !== undefined)
194
+ await writeAtomic(path.join(versionDir, 'generation.json'), generationText(generation));
188
195
  await writeAtomic(path.join(versionDir, 'content', manifest.contentFile), content);
189
196
  const entry = {
190
197
  version: manifest.version,
@@ -192,6 +199,7 @@ export class ArtifactStore {
192
199
  contentHash: manifest.contentHash,
193
200
  contentBytes: manifest.contentBytes,
194
201
  source: manifest.source,
202
+ ...(manifest.generation === undefined ? {} : { generation: manifest.generation }),
195
203
  };
196
204
  await writeAtomic(path.join(versionDir, 'meta.json'), `${JSON.stringify(entry, null, 2)}\n`);
197
205
  }
@@ -202,19 +210,19 @@ export class ArtifactStore {
202
210
  * @param manifest the next manifest.
203
211
  * @param content the next content.
204
212
  */
205
- async commit(dir, manifest, content, root) {
213
+ async commit(dir, manifest, content, root, generation) {
206
214
  await assertWithin(root, dir);
207
215
  await assertPlainFile(path.join(dir, 'content', manifest.contentFile));
208
216
  await assertPlainFile(path.join(dir, MANIFEST));
209
- await this.snapshot(root, dir, manifest, content);
217
+ await this.snapshot(root, dir, manifest, content, generation);
210
218
  const contentFile = path.join(dir, 'content', manifest.contentFile);
211
219
  const manifestFile = path.join(dir, MANIFEST);
212
- await assertWithin(root, contentFile);
213
- await assertWithin(root, manifestFile);
220
+ await assertPlainPath(root, contentFile);
221
+ await assertPlainPath(root, manifestFile);
214
222
  await writeAtomic(contentFile, content);
215
223
  await writeAtomic(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`);
216
224
  try {
217
- await this.prune(dir, manifest.version);
225
+ await this.prune(root, dir, manifest.version);
218
226
  }
219
227
  catch (error) {
220
228
  // The version is saved; a prune failure must not make the caller retry a write that succeeded.
@@ -227,13 +235,13 @@ export class ArtifactStore {
227
235
  * @param dir the artifact directory.
228
236
  * @param current the current version.
229
237
  */
230
- async prune(dir, current) {
231
- const entries = await this.versionEntries(dir);
238
+ async prune(root, dir, current) {
239
+ const entries = await this.versionEntries(root, dir);
232
240
  const newestFirst = [...entries].sort((a, b) => b.version - a.version);
233
241
  let total = 0;
234
242
  const drop = [];
235
243
  newestFirst.forEach((entry, index) => {
236
- total += entry.contentBytes;
244
+ total += entry.contentBytes + (entry.generation?.bytes ?? 0);
237
245
  if (entry.version === current)
238
246
  return;
239
247
  // A snapshot newer than the manifest is a crash leftover, not history.
@@ -252,7 +260,7 @@ export class ArtifactStore {
252
260
  * @param dir the artifact directory.
253
261
  * @returns the entries, oldest first.
254
262
  */
255
- async versionEntries(dir) {
263
+ async versionEntries(root, dir) {
256
264
  let names;
257
265
  try {
258
266
  names = await fs.readdir(path.join(dir, 'versions'));
@@ -267,6 +275,7 @@ export class ArtifactStore {
267
275
  if (!/^[1-9][0-9]*$/.test(name))
268
276
  continue;
269
277
  const file = path.join(dir, 'versions', name, 'meta.json');
278
+ await assertPlainPath(root, file);
270
279
  try {
271
280
  if (!(await assertPlainFile(file)))
272
281
  continue;
@@ -313,11 +322,13 @@ export class ArtifactStore {
313
322
  contentBytes: bytes,
314
323
  contentHash: hashOf(input.content),
315
324
  source: input.source,
325
+ ...(input.recipe === undefined ? {} : { recipe: input.recipe }),
326
+ ...(input.generation === undefined ? {} : { generation: generationSummary(input.generation) }),
316
327
  };
317
328
  try {
318
329
  await assertWithin(root.root, dir);
319
330
  await fs.mkdir(path.join(dir, 'content'), { recursive: true });
320
- await this.commit(dir, manifest, input.content, root.root);
331
+ await this.commit(dir, manifest, input.content, root.root, input.generation);
321
332
  }
322
333
  catch (error) {
323
334
  await fs.rm(dir, { recursive: true, force: true });
@@ -338,6 +349,49 @@ export class ArtifactStore {
338
349
  async manifest(root, id) {
339
350
  return this.readManifest(await artifactDir(root, id));
340
351
  }
352
+ async versionMeta(root, dir, version) {
353
+ const file = path.join(dir, 'versions', String(version), 'meta.json');
354
+ await assertPlainPath(root.root, file);
355
+ if (!(await assertPlainFile(file)))
356
+ throw new ArtifactError('artifact/version-not-found', 'The saved version metadata is missing.', { version });
357
+ if ((await fs.stat(file)).size > MAX_MANIFEST_BYTES)
358
+ throw new ArtifactError('artifact/corrupt', 'Version metadata exceeds its size bound.');
359
+ const text = await fs.readFile(file, 'utf8');
360
+ let value;
361
+ try {
362
+ value = JSON.parse(text);
363
+ }
364
+ catch {
365
+ throw new ArtifactError('artifact/corrupt', 'Invalid version metadata JSON.');
366
+ }
367
+ if (!isVersionEntry(value) || value.version !== version)
368
+ throw new ArtifactError('artifact/corrupt', 'Invalid version metadata.');
369
+ return value;
370
+ }
371
+ async savedGeneration(root, dir, meta) {
372
+ if (meta.generation === undefined)
373
+ return undefined;
374
+ const file = path.join(dir, 'versions', String(meta.version), 'generation.json');
375
+ await assertPlainPath(root.root, file);
376
+ if (!(await assertPlainFile(file)))
377
+ throw new ArtifactError('artifact/corrupt', 'The pinned generation snapshot is missing.');
378
+ if ((await fs.stat(file)).size !== meta.generation.bytes)
379
+ throw new ArtifactError('artifact/corrupt', 'Generation snapshot size mismatch.');
380
+ const text = await fs.readFile(file, 'utf8');
381
+ if (generationHash(text) !== meta.generation.hash)
382
+ throw new ArtifactError('artifact/corrupt', 'Generation snapshot hash mismatch.');
383
+ try {
384
+ const generation = parseGeneration(JSON.parse(text));
385
+ if (JSON.stringify(generationSummary(generation)) !== JSON.stringify(meta.generation))
386
+ throw new ArtifactError('artifact/corrupt', 'Generation summary mismatch.');
387
+ return generation;
388
+ }
389
+ catch (error) {
390
+ if (error instanceof SyntaxError || error instanceof ArtifactError)
391
+ throw new ArtifactError('artifact/corrupt', 'The pinned generation snapshot is invalid.');
392
+ throw error;
393
+ }
394
+ }
341
395
  /**
342
396
  * Read the manifest and content of the current or an earlier version.
343
397
  * @param root the scope root.
@@ -354,8 +408,15 @@ export class ArtifactStore {
354
408
  current: manifest.version,
355
409
  });
356
410
  }
411
+ const selected = version ?? manifest.version;
412
+ const meta = selected === manifest.version ? manifest : await this.versionMeta(root, dir, selected);
413
+ await assertPlainPath(root.root, path.join(dir, 'versions', String(selected), 'content', manifest.contentFile));
414
+ await assertPlainPath(root.root, path.join(dir, 'content', manifest.contentFile));
357
415
  const content = await this.readContent(dir, manifest, version);
358
- return { manifest, content, version: version ?? manifest.version };
416
+ if (hashOf(content) !== meta.contentHash)
417
+ throw new ArtifactError('artifact/corrupt', 'The saved content does not match its hash.');
418
+ const generation = await this.savedGeneration(root, dir, meta);
419
+ return { manifest, content, version: selected, ...(generation === undefined ? {} : { generation }) };
359
420
  }
360
421
  /**
361
422
  * Accept a write only when it names the current version.
@@ -366,7 +427,7 @@ export class ArtifactStore {
366
427
  */
367
428
  async update(root, id, input) {
368
429
  const dir = await artifactDir(root, id);
369
- return withLock(dir, async () => {
430
+ return withWriteLock(root.root, dir, async () => {
370
431
  const current = await this.readManifest(dir);
371
432
  if (input.baseVersion !== current.version) {
372
433
  throw new ArtifactError('artifact/stale-version', `The artifact is at version ${current.version}, not ${input.baseVersion}. Read it again and reapply the change.`, { current: current.version, baseVersion: input.baseVersion });
@@ -383,7 +444,9 @@ export class ArtifactStore {
383
444
  const existing = await this.readContent(dir, current);
384
445
  content = input.edits === undefined ? existing : applyEdits(existing, input.edits);
385
446
  }
386
- return this.write(root.root, dir, current, content, title, input.source);
447
+ const base = input.recipe === undefined ? current : { ...current, recipe: input.recipe };
448
+ const generation = input.generation ?? await this.savedGeneration(root, dir, current);
449
+ return this.write(root.root, dir, base, content, title, input.source, generation);
387
450
  });
388
451
  }
389
452
  /**
@@ -395,9 +458,9 @@ export class ArtifactStore {
395
458
  * @param baseVersion the version the caller saw, if it checks.
396
459
  * @returns the new manifest.
397
460
  */
398
- async restore(root, id, version, source, baseVersion) {
461
+ async restore(root, id, version, source, baseVersion, legacyGeneration) {
399
462
  const dir = await artifactDir(root, id);
400
- return withLock(dir, async () => {
463
+ return withWriteLock(root.root, dir, async () => {
401
464
  const current = await this.readManifest(dir);
402
465
  if (baseVersion !== undefined && baseVersion !== current.version) {
403
466
  throw new ArtifactError('artifact/stale-version', `The artifact is at version ${current.version}, not ${baseVersion}.`, { current: current.version, baseVersion });
@@ -405,8 +468,19 @@ export class ArtifactStore {
405
468
  if (version < 1 || version >= current.version) {
406
469
  throw new ArtifactError('artifact/version-not-found', `Version ${version} cannot be restored.`, { version });
407
470
  }
471
+ const meta = await this.versionMeta(root, dir, version);
408
472
  const content = await this.readContent(dir, current, version);
409
- return this.write(root.root, dir, current, content, current.title, { ...source, action: 'restore', restoredFrom: version });
473
+ if (hashOf(content) !== meta.contentHash)
474
+ throw new ArtifactError('artifact/corrupt', 'The restored content does not match its hash.');
475
+ const generation = await this.savedGeneration(root, dir, meta) ?? legacyGeneration;
476
+ const base = { ...current };
477
+ if (generation) {
478
+ if (generation.recipe)
479
+ base.recipe = generation.recipe.id;
480
+ else
481
+ delete base.recipe;
482
+ }
483
+ return this.write(root.root, dir, base, content, current.title, { ...source, action: 'restore', restoredFrom: version }, generation);
410
484
  });
411
485
  }
412
486
  /**
@@ -418,8 +492,12 @@ export class ArtifactStore {
418
492
  * @param source who wrote it.
419
493
  * @returns the next manifest.
420
494
  */
421
- async write(root, dir, current, content, title, source) {
495
+ async write(root, dir, current, content, title, source, generation) {
422
496
  const bytes = this.checkSize(content);
497
+ const pinned = generation === undefined ? undefined : { ...generation, kit: current.type === 'page' ? declaredKit(content) ?? null : null };
498
+ if (pinned !== undefined && pinned.kit !== null && getKit(pinned.kit) === undefined) {
499
+ throw new ArtifactError('artifact/unsupported-kit', 'The page declares an installed-artifact kit release that is not available. Install it before saving.', { kit: pinned.kit });
500
+ }
423
501
  const next = {
424
502
  ...current,
425
503
  title,
@@ -428,9 +506,12 @@ export class ArtifactStore {
428
506
  contentBytes: bytes,
429
507
  contentHash: hashOf(content),
430
508
  source,
509
+ ...(pinned === undefined ? {} : { generation: generationSummary(pinned) }),
431
510
  };
511
+ if (!pinned)
512
+ delete next.generation;
432
513
  try {
433
- await this.commit(dir, next, content, root);
514
+ await this.commit(dir, next, content, root, pinned);
434
515
  }
435
516
  catch (error) {
436
517
  if (error instanceof ArtifactError)
@@ -450,7 +531,7 @@ export class ArtifactStore {
450
531
  async history(root, id) {
451
532
  const dir = await artifactDir(root, id);
452
533
  const manifest = await this.readManifest(dir);
453
- return (await this.versionEntries(dir))
534
+ return (await this.versionEntries(root.root, dir))
454
535
  .filter((entry) => entry.version <= manifest.version)
455
536
  .reverse();
456
537
  }
@@ -482,6 +563,7 @@ export class ArtifactStore {
482
563
  const query = input.query?.trim().toLowerCase() ?? '';
483
564
  const filtered = manifests
484
565
  .filter((item) => input.type === undefined || item.type === input.type)
566
+ .filter((item) => input.recipe === undefined || item.recipe === input.recipe)
485
567
  .filter((item) => query === '' || item.title.toLowerCase().includes(query))
486
568
  .sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : a.updatedAt > b.updatedAt ? -1 : 0));
487
569
  const offset = Math.max(0, Math.floor(input.offset ?? 0));
@@ -497,7 +579,7 @@ export class ArtifactStore {
497
579
  */
498
580
  async remove(root, id) {
499
581
  const dir = await artifactDir(root, id);
500
- return withLock(dir, async () => {
582
+ return withWriteLock(root.root, dir, async () => {
501
583
  await this.readManifest(dir);
502
584
  const trashRoot = path.join(root.root, TRASH);
503
585
  await assertWithin(root.root, trashRoot);
@@ -0,0 +1,85 @@
1
+ /** The page model a design export hands the SVG viewer, and its validator. */
2
+ const ALIGNS = new Set(['LEFT', 'CENTER', 'RIGHT', 'JUSTIFIED']);
3
+ const VERTICAL_ALIGNS = new Set(['TOP', 'CENTER', 'BOTTOM']);
4
+ const TEXT_CASES = new Set(['ORIGINAL', 'UPPER', 'LOWER', 'TITLE']);
5
+ /**
6
+ * Tell a field map from an unknown value.
7
+ * @param value the value.
8
+ * @returns its fields, or null.
9
+ */
10
+ function fieldsOf(value) {
11
+ if (value === null || typeof value !== 'object' || Array.isArray(value))
12
+ return null;
13
+ return { ...value };
14
+ }
15
+ /**
16
+ * Tell one run from an unknown value.
17
+ * @param value the value.
18
+ * @returns whether it is a run.
19
+ */
20
+ function isRun(value) {
21
+ const run = fieldsOf(value);
22
+ return (run !== null &&
23
+ typeof run['text'] === 'string' &&
24
+ typeof run['size'] === 'number' &&
25
+ typeof run['weight'] === 'number' &&
26
+ typeof run['italic'] === 'boolean' &&
27
+ typeof run['letterSpacing'] === 'number' &&
28
+ typeof run['color'] === 'string' &&
29
+ typeof run['alpha'] === 'number');
30
+ }
31
+ /**
32
+ * Tell one text box from an unknown value.
33
+ * @param value the value.
34
+ * @returns whether it is a text box.
35
+ */
36
+ function isTextBox(value) {
37
+ const box = fieldsOf(value);
38
+ if (box === null)
39
+ return false;
40
+ const numbers = ['width', 'height', 'size', 'weight', 'letterSpacing', 'alpha'];
41
+ if (!numbers.every((key) => typeof box[key] === 'number'))
42
+ return false;
43
+ const matrix = fieldsOf(box['matrix']);
44
+ if (matrix === null)
45
+ return false;
46
+ if (!['a', 'b', 'c', 'd', 'e', 'f'].every((key) => typeof matrix[key] === 'number'))
47
+ return false;
48
+ const strings = ['text', 'family', 'color'];
49
+ if (!strings.every((key) => typeof box[key] === 'string'))
50
+ return false;
51
+ if (typeof box['italic'] !== 'boolean')
52
+ return false;
53
+ if (box['lineHeight'] !== null && typeof box['lineHeight'] !== 'number')
54
+ return false;
55
+ if (typeof box['wrap'] !== 'boolean')
56
+ return false;
57
+ if (typeof box['textCase'] !== 'string' || !TEXT_CASES.has(box['textCase']))
58
+ return false;
59
+ if (typeof box['align'] !== 'string' || !ALIGNS.has(box['align']))
60
+ return false;
61
+ if (typeof box['verticalAlign'] !== 'string' || !VERTICAL_ALIGNS.has(box['verticalAlign']))
62
+ return false;
63
+ if (!Array.isArray(box['runs']) || !box['runs'].every(isRun))
64
+ return false;
65
+ return box['clip'] === null || fieldsOf(box['clip']) !== null;
66
+ }
67
+ /**
68
+ * Tell a page model from an unknown value read from the worker.
69
+ * @param value the parsed response.
70
+ * @returns whether it is a page model.
71
+ */
72
+ export function isSvgPageModel(value) {
73
+ const fields = fieldsOf(value);
74
+ if (fields === null)
75
+ return false;
76
+ if (typeof fields['width'] !== 'number' || typeof fields['height'] !== 'number')
77
+ return false;
78
+ if (typeof fields['svg'] !== 'string')
79
+ return false;
80
+ const texts = fields['texts'];
81
+ const families = fields['families'];
82
+ if (!Array.isArray(texts) || !texts.every(isTextBox))
83
+ return false;
84
+ return Array.isArray(families) && families.every((family) => typeof family === 'string');
85
+ }