@literary-universe/sdk 0.1.0 → 0.3.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.
@@ -1,8 +1,10 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.MARKDOWN_LOSSY_TYPES = void 0;
3
4
  exports.readLocalProject = readLocalProject;
4
5
  exports.localProjectStatus = localProjectStatus;
5
6
  exports.pullLocalProject = pullLocalProject;
7
+ exports.refreshLocalProject = refreshLocalProject;
6
8
  exports.pushLocalProject = pushLocalProject;
7
9
  const node_crypto_1 = require("node:crypto");
8
10
  const node_fs_1 = require("node:fs");
@@ -14,6 +16,64 @@ const failure = (code, message) => {
14
16
  };
15
17
  const digest = (content) => (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(content)).digest('hex');
16
18
  const filename = (id, language) => `chapters/chapter-${id}.${language}.json`;
19
+ /**
20
+ * What the server's Markdown has no form for, so a `markdown` save is refused
21
+ * with MARKDOWN_UNSUPPORTED: node and mark types, plus the paragraph/heading
22
+ * attributes `textAlign` (other than left) and `initialLetter`.
23
+ */
24
+ exports.MARKDOWN_LOSSY_TYPES = [
25
+ 'ruby',
26
+ 'connection',
27
+ 'textStyle',
28
+ 'emoji',
29
+ 'video',
30
+ 'workCard',
31
+ 'textAlign',
32
+ 'initialLetter',
33
+ 'playSceneHeading',
34
+ 'playCharacter',
35
+ 'playParenthetical',
36
+ 'playDialogue',
37
+ 'playLyric',
38
+ 'playTransition',
39
+ 'playSynopsis',
40
+ 'playNote',
41
+ 'playBoneyard',
42
+ 'playDialogueBlock',
43
+ 'playDualDialogue',
44
+ ];
45
+ /** Lossy types found in a Tiptap document, in document order. */
46
+ function lossyTypes(node, found = new Set()) {
47
+ if (!node || typeof node !== 'object')
48
+ return found;
49
+ const { type, attrs } = node;
50
+ if (typeof type === 'string' && exports.MARKDOWN_LOSSY_TYPES.includes(type))
51
+ found.add(type);
52
+ const block = type === 'paragraph' || type === 'heading';
53
+ if (block && attrs?.textAlign != null && attrs.textAlign !== 'left')
54
+ found.add('textAlign');
55
+ if (block && attrs?.initialLetter)
56
+ found.add('initialLetter');
57
+ for (const value of Object.values(node))
58
+ lossyTypes(value, found);
59
+ return found;
60
+ }
61
+ const FRONTMATTER = /^---\n(?:[^\n]*\n)*?---\n/;
62
+ const MARKDOWN_NOTICE = /^# (?:This chapter has no Markdown form yet;[^\n]*|Edit chapters\/[^\n]* instead: this chapter contains [^\n]*)\n/;
63
+ /** Why the Markdown file must not be edited, or undefined when it may be. */
64
+ function markdownNotice(draft) {
65
+ if (draft.content == null || draft.markdown == null)
66
+ return '# This chapter has no Markdown form yet; open it once in the web editor to convert it, then run lu refresh';
67
+ const lossy = [...lossyTypes(draft.content)];
68
+ if (lossy.length)
69
+ return `# Edit ${filename(draft.id, draft.language)} instead: this chapter contains ${lossy.join(', ')}`;
70
+ }
71
+ function frontmatter(draft) {
72
+ const notice = markdownNotice(draft);
73
+ const fields = ['id', 'title', 'language', 'version'].map((key) => `${key}: ${JSON.stringify(draft[key])}`);
74
+ const header = ['---', ...fields, `editable: ${!notice}`, '---', ''];
75
+ return `${header.join('\n')}${notice ? `${notice}\n` : ''}\n`;
76
+ }
17
77
  const rootFor = (directory) => (0, node_fs_1.realpathSync)((0, node_path_1.resolve)(directory));
18
78
  function pathFor(root, file) {
19
79
  if (!/^(\.lu|chapters)\/[a-zA-Z0-9._-]+(?:\/[a-zA-Z0-9._-]+)?$/.test(file) ||
@@ -28,13 +88,10 @@ function pathFor(root, file) {
28
88
  }
29
89
  return path;
30
90
  }
31
- function writeJson(root, file, value) {
91
+ function writeText(root, file, text) {
32
92
  const path = pathFor(root, file);
33
93
  const temporary = `${path}.${(0, node_crypto_1.randomUUID)()}.tmp`;
34
- (0, node_fs_1.writeFileSync)(temporary, `${JSON.stringify(value, null, 2)}\n`, {
35
- mode: 0o600,
36
- flag: 'wx',
37
- });
94
+ (0, node_fs_1.writeFileSync)(temporary, text, { mode: 0o600, flag: 'wx' });
38
95
  try {
39
96
  (0, node_fs_1.renameSync)(temporary, path);
40
97
  }
@@ -42,17 +99,28 @@ function writeJson(root, file, value) {
42
99
  (0, node_fs_1.rmSync)(temporary, { force: true });
43
100
  }
44
101
  }
45
- function readJson(root, file) {
102
+ const writeJson = (root, file, value) => writeText(root, file, `${JSON.stringify(value, null, 2)}\n`);
103
+ const writeMarkdown = (root, file, draft) => writeText(root, file, frontmatter(draft) + (draft.markdown ?? ''));
104
+ function readText(root, file) {
46
105
  const path = pathFor(root, file);
47
106
  if ((0, node_fs_1.statSync)(path).size > 16 * 1024 * 1024)
48
107
  failure('PAYLOAD_TOO_LARGE', 'Project file exceeds the size limit');
108
+ return (0, node_fs_1.readFileSync)(path, 'utf8').replace(/^\uFEFF/, '');
109
+ }
110
+ function readJson(root, file) {
49
111
  try {
50
- return JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8').replace(/^\uFEFF/, ''));
112
+ return JSON.parse(readText(root, file));
51
113
  }
52
114
  catch {
53
115
  return failure('INVALID_PROJECT', 'Project file contains invalid JSON');
54
116
  }
55
117
  }
118
+ /** The Markdown body: the file without its frontmatter, with LF line ends. */
119
+ const readBody = (root, file) => readText(root, file)
120
+ .replaceAll('\r\n', '\n')
121
+ .replace(FRONTMATTER, '')
122
+ .replace(MARKDOWN_NOTICE, '')
123
+ .replace(/^\n/, '');
56
124
  function clearDeadLock(root) {
57
125
  const existing = readJson(root, '.lu/lock');
58
126
  if (existing.host !== (0, node_os_1.hostname)() ||
@@ -87,15 +155,27 @@ function readLocalProject(directory) {
87
155
  if (project?.version !== 1 ||
88
156
  typeof project.baseUrl !== 'string' ||
89
157
  !/^[a-zA-Z0-9_-]{1,100}$/.test(project.storyId) ||
158
+ (project.language !== undefined &&
159
+ !/^[a-zA-Z0-9-]{1,32}$/.test(project.language)) ||
90
160
  !Array.isArray(project.chapters))
91
161
  failure('INVALID_PROJECT', 'Invalid project manifest');
92
162
  const files = new Set();
93
163
  for (const chapter of project.chapters) {
94
164
  validateChapter(chapter, files);
95
165
  files.add(chapter.file.toLowerCase());
166
+ if (chapter.markdown)
167
+ validateMarkdown(chapter.markdown, files);
96
168
  }
97
169
  return project;
98
170
  }
171
+ function validateMarkdown(markdown, files) {
172
+ if (typeof markdown.file !== 'string' ||
173
+ !/^chapters\/[a-zA-Z0-9._-]+\.md$/.test(markdown.file) ||
174
+ typeof markdown.hash !== 'string' ||
175
+ files.has(markdown.file.toLowerCase()))
176
+ failure('INVALID_PROJECT', 'Invalid chapter manifest');
177
+ files.add(markdown.file.toLowerCase());
178
+ }
99
179
  function validateChapter(chapter, files) {
100
180
  if (!chapter ||
101
181
  typeof chapter.id !== 'string' ||
@@ -108,16 +188,29 @@ function validateChapter(chapter, files) {
108
188
  files.has(chapter.file.toLowerCase()))
109
189
  failure('INVALID_PROJECT', 'Invalid chapter manifest');
110
190
  }
191
+ /** Which local file differs from the manifest; `both` cannot be pushed. */
192
+ function inspect(root, chapter) {
193
+ const content = readJson(root, chapter.file);
194
+ const body = chapter.markdown ? readBody(root, chapter.markdown.file) : '';
195
+ const json = digest(content) !== chapter.hash;
196
+ const markdown = chapter.markdown !== undefined && digest(body) !== chapter.markdown.hash;
197
+ const source = json && markdown ? 'both' : json ? 'json' : markdown ? 'markdown' : 'none';
198
+ return { content, body, source };
199
+ }
111
200
  function localProjectStatus(directory) {
112
201
  const root = rootFor(directory);
113
- return readLocalProject(root).chapters.map((chapter) => ({
114
- id: chapter.id,
115
- language: chapter.language,
116
- file: chapter.file,
117
- version: chapter.version,
118
- changed: digest(readJson(root, chapter.file)) !== chapter.hash,
119
- pending: Boolean(chapter.pending),
120
- }));
202
+ return readLocalProject(root).chapters.map((chapter) => {
203
+ const { source } = inspect(root, chapter);
204
+ return {
205
+ id: chapter.id,
206
+ language: chapter.language,
207
+ file: chapter.file,
208
+ version: chapter.version,
209
+ changed: source !== 'none',
210
+ source,
211
+ pending: Boolean(chapter.pending),
212
+ };
213
+ });
121
214
  }
122
215
  function initializeProject(directory) {
123
216
  (0, node_fs_1.mkdirSync)(directory, { recursive: true });
@@ -140,6 +233,8 @@ async function pullPage(client, root, project, input, after) {
140
233
  language: input.language,
141
234
  });
142
235
  storePulledDraft(root, project, draft);
236
+ // A refresh stopped midway keeps a manifest that matches the files written so far.
237
+ writeJson(root, '.lu/project.json', project);
143
238
  }
144
239
  return page.pageInfo;
145
240
  }
@@ -147,10 +242,27 @@ function assertDistinctFile(project, file) {
147
242
  if (project.chapters.some((chapter) => chapter.file.toLowerCase() === file.toLowerCase()))
148
243
  failure('INVALID_PROJECT', 'Chapter filenames differ only by case; use individual draft files');
149
244
  }
245
+ /** `chapters/<seq>-<slug>.<lang>.md`, numbered on a collision. */
246
+ function markdownName(project, draft) {
247
+ const slug = draft.title
248
+ .toLowerCase()
249
+ .replace(/[^a-z0-9]+/g, '-')
250
+ .slice(0, 60)
251
+ .replace(/^-+|-+$/g, '') || 'chapter';
252
+ const base = `chapters/${String(draft.sequence).padStart(3, '0')}-${slug}`;
253
+ const taken = new Set(project.chapters.map((chapter) => chapter.markdown?.file.toLowerCase()));
254
+ for (let n = 1;; n++) {
255
+ const file = `${base}${n > 1 ? `-${n}` : ''}.${draft.language}.md`;
256
+ if (!taken.has(file.toLowerCase()))
257
+ return file;
258
+ }
259
+ }
150
260
  function storePulledDraft(root, project, draft) {
151
261
  const file = filename(draft.id, draft.language);
152
262
  assertDistinctFile(project, file);
263
+ const markdown = markdownName(project, draft);
153
264
  writeJson(root, file, draft.content);
265
+ writeMarkdown(root, markdown, draft);
154
266
  writeJson(root, `.lu/${file.split('/')[1]}`, draft);
155
267
  project.chapters.push({
156
268
  id: draft.id,
@@ -158,6 +270,7 @@ function storePulledDraft(root, project, draft) {
158
270
  file,
159
271
  version: draft.version,
160
272
  hash: digest(draft.content),
273
+ markdown: { file: markdown, hash: digest(draft.markdown ?? '') },
161
274
  });
162
275
  }
163
276
  async function pullPages(client, root, project, language) {
@@ -177,6 +290,8 @@ async function pullPages(client, root, project, language) {
177
290
  }
178
291
  /** Pulls into a new directory, preserving existing local files. */
179
292
  async function pullLocalProject(client, input) {
293
+ if (input.refresh)
294
+ return refreshLocalProject(client, input);
180
295
  const root = initializeProject(input.directory);
181
296
  const release = lock(root);
182
297
  try {
@@ -184,6 +299,7 @@ async function pullLocalProject(client, input) {
184
299
  version: 1,
185
300
  baseUrl: input.baseUrl,
186
301
  storyId: input.storyId,
302
+ ...(input.language ? { language: input.language } : {}),
187
303
  chapters: [],
188
304
  };
189
305
  await pullPages(client, root, project, input.language);
@@ -200,6 +316,84 @@ async function pullLocalProject(client, input) {
200
316
  release();
201
317
  }
202
318
  }
319
+ /** Deletes the files of chapters the server no longer has and reports the difference. */
320
+ function reconcile(root, previous, project) {
321
+ const current = new Set(project.chapters.map((chapter) => chapter.file));
322
+ const kept = new Set(project.chapters.flatMap((chapter) => [
323
+ chapter.file,
324
+ chapter.markdown?.file,
325
+ ]));
326
+ for (const chapter of previous) {
327
+ for (const file of [chapter.file, chapter.markdown?.file])
328
+ if (file && !kept.has(file))
329
+ (0, node_fs_1.rmSync)(pathFor(root, file), { force: true });
330
+ if (!current.has(chapter.file))
331
+ (0, node_fs_1.rmSync)(pathFor(root, `.lu/${chapter.file.split('/')[1]}`), {
332
+ force: true,
333
+ });
334
+ }
335
+ return difference(previous, project.chapters);
336
+ }
337
+ const sameState = (before, after) => before.version === after.version &&
338
+ before.hash === after.hash &&
339
+ before.markdown?.hash === after.markdown?.hash;
340
+ function difference(previous, chapters) {
341
+ const was = new Map(previous.map((chapter) => [chapter.file, chapter]));
342
+ const current = new Set(chapters.map((chapter) => chapter.file));
343
+ const ids = (list) => [...new Set(list.map((c) => c.id))];
344
+ return {
345
+ added: ids(chapters.filter((chapter) => !was.has(chapter.file))),
346
+ updated: ids(chapters.filter((chapter) => {
347
+ const before = was.get(chapter.file);
348
+ return before && !sameState(before, chapter);
349
+ })),
350
+ removed: ids(previous.filter((chapter) => !current.has(chapter.file))),
351
+ };
352
+ }
353
+ /** Re-pulls every chapter of an existing project; refuses while anything local is unpushed. */
354
+ async function refreshLocalProject(client, input) {
355
+ const root = rootFor(input.directory);
356
+ const release = lock(root);
357
+ try {
358
+ const project = openProject(root, input.baseUrl);
359
+ if (project.chapters.some((chapter) => chapter.pending || inspect(root, chapter).source !== 'none'))
360
+ failure('LOCAL_CHANGES', 'Push or revert local changes before refreshing');
361
+ const previous = project.chapters;
362
+ const staging = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)(root, '.lu-refresh-'));
363
+ try {
364
+ initializeProject(staging);
365
+ project.chapters = [];
366
+ await pullPages(client, staging, project, project.language);
367
+ // Editors do not share our lock. Check again after the network reads.
368
+ if (previous.some((chapter) => inspect(root, chapter).source !== 'none'))
369
+ failure('LOCAL_CHANGES', 'Local changes appeared while refreshing');
370
+ const managed = new Set(previous.flatMap((chapter) => [
371
+ chapter.file,
372
+ chapter.markdown?.file,
373
+ `.lu/${chapter.file.split('/')[1]}`,
374
+ ]));
375
+ const files = project.chapters.flatMap((chapter) => [
376
+ chapter.file,
377
+ ...(chapter.markdown ? [chapter.markdown.file] : []),
378
+ `.lu/${chapter.file.split('/')[1]}`,
379
+ ]);
380
+ for (const file of files) {
381
+ if ((0, node_fs_1.existsSync)(pathFor(root, file)) && !managed.has(file))
382
+ failure('LOCAL_CHANGES', 'Refresh would overwrite an unmanaged file');
383
+ }
384
+ for (const file of files)
385
+ writeText(root, file, readText(staging, file));
386
+ writeJson(root, '.lu/project.json', project);
387
+ return reconcile(root, previous, project);
388
+ }
389
+ finally {
390
+ (0, node_fs_1.rmSync)(staging, { recursive: true, force: true });
391
+ }
392
+ }
393
+ finally {
394
+ release();
395
+ }
396
+ }
203
397
  /** Saves each changed draft once; pending intents survive a lost response or stopped process. */
204
398
  async function pushLocalProject(client, input) {
205
399
  const root = rootFor(input.directory);
@@ -211,9 +405,18 @@ async function pushLocalProject(client, input) {
211
405
  release();
212
406
  }
213
407
  }
408
+ /** Rewrites both files from the server's draft unless they changed again meanwhile. */
214
409
  function savedLocally(root, project, chapter, result) {
215
- if (digest(readJson(root, chapter.file)) === chapter.pending?.hash)
410
+ const { pending, markdown } = chapter;
411
+ const sentMarkdown = pending?.markdown !== undefined;
412
+ const jsonBefore = sentMarkdown ? chapter.hash : pending?.hash;
413
+ if (digest(readJson(root, chapter.file)) === jsonBefore)
216
414
  writeJson(root, chapter.file, result.draft.content);
415
+ const file = markdown?.file ?? markdownName(project, result.draft);
416
+ const bodyBefore = sentMarkdown ? pending?.hash : markdown?.hash;
417
+ if (!markdown || digest(readBody(root, file)) === bodyBefore)
418
+ writeMarkdown(root, file, result.draft);
419
+ chapter.markdown = { file, hash: digest(result.draft.markdown ?? '') };
217
420
  chapter.hash = digest(result.draft.content);
218
421
  chapter.version = result.version;
219
422
  delete chapter.pending;
@@ -265,33 +468,59 @@ const saveInput = ({ chapter, pending }) => ({
265
468
  language: chapter.language,
266
469
  expectedVersion: pending.expectedVersion,
267
470
  operationId: pending.operationId,
268
- content: pending.content,
471
+ ...(pending.markdown === undefined
472
+ ? { content: pending.content }
473
+ : { markdown: pending.markdown }),
269
474
  });
475
+ /** The intent to send: an earlier pending one, else the changed file's; or why nothing can be sent. */
270
476
  function snapshot(root, chapter) {
271
- const content = chapter.pending?.content ?? readJson(root, chapter.file);
272
- const pending = chapter.pending ?? {
273
- operationId: (0, node_crypto_1.randomUUID)(),
477
+ if (chapter.pending)
478
+ return { chapter, pending: chapter.pending };
479
+ const { content, body, source } = inspect(root, chapter);
480
+ if (source === 'none')
481
+ return source;
482
+ if (source === 'both')
483
+ return 'AMBIGUOUS_CHANGE';
484
+ // The stored server draft shows a missing Markdown form, which the JSON file alone cannot.
485
+ const stored = readJson(root, `.lu/${chapter.file.split('/')[1]}`);
486
+ if (source === 'markdown' && markdownNotice(stored))
487
+ return 'MARKDOWN_UNSUPPORTED';
488
+ const sent = source === 'markdown' ? { markdown: body } : { content };
489
+ const hash = digest(source === 'markdown' ? body : content);
490
+ const operationId = (0, node_crypto_1.randomUUID)();
491
+ const pending = {
492
+ operationId,
274
493
  expectedVersion: chapter.version,
275
- hash: digest(content),
276
- content,
494
+ hash,
495
+ ...sent,
277
496
  };
278
497
  return { chapter, pending };
279
498
  }
280
- async function preflight(client, root, baseUrl) {
499
+ function openProject(root, baseUrl) {
281
500
  const project = readLocalProject(root);
282
501
  if (new URL(project.baseUrl).href !== new URL(baseUrl).href)
283
502
  failure('DEPLOYMENT_MISMATCH', 'The selected deployment does not match this project');
284
- const changes = project.chapters
285
- .map((chapter) => snapshot(root, chapter))
286
- .filter(({ chapter, pending }) => chapter.pending || pending.hash !== chapter.hash);
503
+ return project;
504
+ }
505
+ async function preflight(client, root, baseUrl) {
506
+ const project = openProject(root, baseUrl);
507
+ const changes = [];
508
+ const unsendable = [];
509
+ for (const chapter of project.chapters) {
510
+ const change = snapshot(root, chapter);
511
+ if (typeof change === 'object')
512
+ changes.push(change);
513
+ else if (change !== 'none')
514
+ unsendable.push({ id: chapter.id, status: 'failed', code: change });
515
+ }
287
516
  for (const change of changes.filter(({ chapter }) => !chapter.pending))
288
517
  await client.validateDraft(saveInput(change));
289
- return { project, changes };
518
+ return { project, changes, unsendable };
290
519
  }
291
520
  async function pushLocked(client, root, baseUrl) {
292
- const { project, changes } = await preflight(client, root, baseUrl);
521
+ const { project, changes, unsendable } = await preflight(client, root, baseUrl);
293
522
  // Chapters are independent: a failure keeps its pending intent and the rest still push.
294
- const results = [];
523
+ const results = [...unsendable];
295
524
  for (const change of changes)
296
525
  results.push(await pushChapter(client, root, project, change));
297
526
  return results;