@lincyaw/cli 1.0.0-rc.6 → 1.0.0-rc.60
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/README.md +2 -2
- package/package.json +12 -6
- package/src/cli.ts +207 -6
- package/src/document-file.ts +59 -0
- package/src/import.ts +169 -0
- package/src/markdown.ts +328 -0
- package/src/messages.ts +350 -9
- package/src/script.ts +152 -0
- package/src/speech-key.ts +73 -0
- package/src/voiceover.ts +241 -0
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@ Part of [Presmium](https://github.com/Lincyaw/presmium), which turns structured
|
|
|
6
6
|
|
|
7
7
|
## Install
|
|
8
8
|
|
|
9
|
-
Most people install the `presmium` package, which brings this command with the renderers and the official plugins:
|
|
9
|
+
Most people install the `presmium` package, which brings this command with Studio, the renderers and the official plugins:
|
|
10
10
|
|
|
11
11
|
```sh
|
|
12
12
|
pnpm add -g @lincyaw/presmium
|
|
@@ -28,7 +28,7 @@ pnpm add -D @lincyaw/cli @lincyaw/web @lincyaw/render-slides @lincyaw/render-not
|
|
|
28
28
|
| `presmium dev [deck]` | Dev servers that update on save (`--to`, `--out`, `--server-port`, `--allow`) |
|
|
29
29
|
| `presmium new [dir]` | A new lecture, workspace or plugin project (`--type`, `--title`, `--name`, `--no-git`); from `create-presmium`, which the `presmium` package brings |
|
|
30
30
|
| `presmium serve [dir]` | The workspace service, on this machine: the documents and their sites, compiled on demand (`--port`, `--host`, `--operator-dir`, `--preview-origin`) |
|
|
31
|
-
| `presmium studio [dir]` | The workbench (experimental),
|
|
31
|
+
| `presmium studio [dir]` | The workbench (experimental), included with Presmium (`--port`, `--host`); uses the running command's bundled version |
|
|
32
32
|
|
|
33
33
|
`[deck]` is a directory with `lecture.json` or an entry file, by default the current directory. Exit codes: 0 no errors, 1 error findings, 2 usage or internal error. `presmium --help` lists every option.
|
|
34
34
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lincyaw/cli",
|
|
3
|
-
"version": "1.0.0-rc.
|
|
3
|
+
"version": "1.0.0-rc.60",
|
|
4
4
|
"description": "The presmium command: build, dev, ir, check and serve for Presmium documents",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -36,10 +36,16 @@
|
|
|
36
36
|
],
|
|
37
37
|
"dependencies": {
|
|
38
38
|
"jiti": "^2.7.0",
|
|
39
|
-
"
|
|
40
|
-
"
|
|
41
|
-
"
|
|
42
|
-
"
|
|
43
|
-
"
|
|
39
|
+
"mdast-util-from-markdown": "2.1.0",
|
|
40
|
+
"mdast-util-gfm": "3.1.0",
|
|
41
|
+
"mdast-util-math": "3.0.0",
|
|
42
|
+
"micromark-extension-gfm": "3.0.0",
|
|
43
|
+
"micromark-extension-math": "3.1.0",
|
|
44
|
+
"yaml": "^2.9.1",
|
|
45
|
+
"@lincyaw/compiler": "1.0.0-rc.60",
|
|
46
|
+
"@lincyaw/kernel": "1.0.0-rc.60",
|
|
47
|
+
"@lincyaw/server": "1.0.0-rc.60",
|
|
48
|
+
"@lincyaw/skills": "1.0.0-rc.60",
|
|
49
|
+
"@lincyaw/workspace": "1.0.0-rc.60"
|
|
44
50
|
}
|
|
45
51
|
}
|
package/src/cli.ts
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
import { existsSync, statSync } from 'node:fs'
|
|
2
|
-
import { mkdir, writeFile } from 'node:fs/promises'
|
|
2
|
+
import { mkdir, readFile, writeFile } from 'node:fs/promises'
|
|
3
3
|
import { createRequire } from 'node:module'
|
|
4
4
|
import { dirname, join, relative, resolve } from 'node:path'
|
|
5
5
|
import { fileURLToPath, pathToFileURL } from 'node:url'
|
|
6
6
|
import { parseArgs } from 'node:util'
|
|
7
7
|
import { createJiti } from 'jiti'
|
|
8
|
-
import { APPROVAL_KINDS, errorMessage } from '@lincyaw/kernel'
|
|
9
|
-
import { bracketIPv6,
|
|
10
|
-
import type { ApprovalKind, Finding, Severity } from '@lincyaw/kernel'
|
|
8
|
+
import { APPROVAL_KINDS, deckLocale, errorMessage } from '@lincyaw/kernel'
|
|
9
|
+
import { bracketIPv6, irRevision, lanAddresses } from '@lincyaw/kernel/node'
|
|
10
|
+
import type { ApprovalKind, Finding, Severity, SpeechVoice } from '@lincyaw/kernel'
|
|
11
11
|
import { build, Compiler, dev, resolveEntry } from '@lincyaw/compiler'
|
|
12
12
|
import type { BuildReport, Compilation, RunStats } from '@lincyaw/compiler'
|
|
13
13
|
import { isAnyAddress, isLoopback, serverConfigKey, servedDocument, startServer } from '@lincyaw/server'
|
|
@@ -15,9 +15,14 @@ import type { ApprovalPolicy } from '@lincyaw/server'
|
|
|
15
15
|
import { buildWorkspace, isWorkspaceRoot, serveWorkspace } from '@lincyaw/workspace'
|
|
16
16
|
import type { WorkspaceBuild } from '@lincyaw/workspace'
|
|
17
17
|
import { runCheck } from './check.ts'
|
|
18
|
+
import { documentPatterns, importMarkdown } from './import.ts'
|
|
18
19
|
import type { CheckResult } from './check.ts'
|
|
19
20
|
import { devHost } from './dev-host.ts'
|
|
21
|
+
import { DocumentFileError, readDocumentFile, saveDocumentFile } from './document-file.ts'
|
|
20
22
|
import { CLI_MESSAGES, systemLocale } from './messages.ts'
|
|
23
|
+
import { exportScript, importScript, ScriptError } from './script.ts'
|
|
24
|
+
import { runSpeechKey, SpeechKeyFailure } from './speech-key.ts'
|
|
25
|
+
import { runVoiceover, VoiceoverFailure } from './voiceover.ts'
|
|
21
26
|
|
|
22
27
|
const BUNDLED = fileURLToPath(new URL('..', import.meta.url))
|
|
23
28
|
const PRESMIUM_BIN = fileURLToPath(new URL('../bin/presmium.mjs', import.meta.url))
|
|
@@ -36,7 +41,7 @@ const OPTIONS = {
|
|
|
36
41
|
'dev': ['to', 'out', 'server-port', 'allow'],
|
|
37
42
|
'ir': ['out'],
|
|
38
43
|
'check': ['json', 'update-lock', 'env', 'audience', 'external-links'],
|
|
39
|
-
'serve': ['port', 'host', 'operator-dir', 'preview-origin', 'public-url'],
|
|
44
|
+
'serve': ['port', 'host', 'operator-dir', 'preview-origin', 'public-url', 'allow'],
|
|
40
45
|
} as const
|
|
41
46
|
|
|
42
47
|
type Name = keyof typeof OPTIONS
|
|
@@ -66,6 +71,11 @@ export async function main(argv: string[], options: MainOptions = {}): Promise<n
|
|
|
66
71
|
if (argv[0] === 'new') return runNewCommand(argv.slice(1), bundled)
|
|
67
72
|
if (argv[0] === 'skills') return (await import('@lincyaw/skills')).main(argv.slice(1))
|
|
68
73
|
if (argv[0] === 'studio') return runStudioCommand(argv.slice(1), bundled, options.bin ?? PRESMIUM_BIN)
|
|
74
|
+
if (argv[0] === 'mcp') return runMcpCommand(argv.slice(1), bundled)
|
|
75
|
+
if (argv[0] === 'import') return runImportCommand(argv.slice(1))
|
|
76
|
+
if (argv[0] === 'voiceover') return runVoiceoverCommand(argv.slice(1), bundled)
|
|
77
|
+
if (argv[0] === 'speech') return runSpeechCommand(argv.slice(1))
|
|
78
|
+
if (argv[0] === 'script') return runScriptCommand(argv.slice(1))
|
|
69
79
|
let command: Command | 'help'
|
|
70
80
|
try {
|
|
71
81
|
command = parseCommand(argv)
|
|
@@ -289,12 +299,12 @@ async function runServeCommand(command: Command, bundled: string): Promise<numbe
|
|
|
289
299
|
check: compilation => compilation.check(),
|
|
290
300
|
previewOrigins: command.previewOrigins,
|
|
291
301
|
...command.publicUrl ? { publicUrl: command.publicUrl } : {},
|
|
302
|
+
allow: command.allow,
|
|
292
303
|
})
|
|
293
304
|
process.stdout.write(`serve ${started.url}\n${networkLines(command.listenAddress, started.url)}workspace ${started.root}\nmcp ${started.mcp.url}${t.token(started.mcp.stateFile)}\n`)
|
|
294
305
|
if (command.listenAddress && !isLoopback(command.listenAddress)) {
|
|
295
306
|
process.stderr.write(`${t.serveOpen(command.listenAddress, new URL(started.url).port)}\n`)
|
|
296
307
|
}
|
|
297
|
-
if (!findFfmpeg()) process.stderr.write(`${t.noFfmpeg(ffmpegInstallCommand())}\n`)
|
|
298
308
|
await new Promise<void>((done) => {
|
|
299
309
|
process.once('SIGINT', done)
|
|
300
310
|
process.once('SIGTERM', done)
|
|
@@ -323,6 +333,185 @@ async function runNewCommand(argv: string[], bundled: string): Promise<number> {
|
|
|
323
333
|
return createMain(argv)
|
|
324
334
|
}
|
|
325
335
|
|
|
336
|
+
/** Markdown notes to documents; prints what it wrote, the links it could not resolve and the patterns that list them. */
|
|
337
|
+
function runImportCommand(argv: string[]): number {
|
|
338
|
+
let parsed
|
|
339
|
+
try {
|
|
340
|
+
parsed = parseArgs({ args: argv, allowPositionals: true, options: {
|
|
341
|
+
out: { type: 'string' }, exclude: { type: 'string', multiple: true }, lang: { type: 'string' }, group: { type: 'string' }, help: { type: 'boolean', short: 'h', default: false },
|
|
342
|
+
} })
|
|
343
|
+
} catch (error) {
|
|
344
|
+
process.stderr.write(`presmium: ${errorMessage(error)}\n\n${t.usage}\n`)
|
|
345
|
+
return 2
|
|
346
|
+
}
|
|
347
|
+
const { values, positionals } = parsed
|
|
348
|
+
if (values.help) {
|
|
349
|
+
process.stdout.write(`${t.usage}\n`)
|
|
350
|
+
return 0
|
|
351
|
+
}
|
|
352
|
+
const [input, ...extra] = positionals
|
|
353
|
+
if (!input) {
|
|
354
|
+
process.stderr.write(`presmium: ${t.importMissing}\n`)
|
|
355
|
+
return 2
|
|
356
|
+
}
|
|
357
|
+
if (extra.length > 0) {
|
|
358
|
+
process.stderr.write(`presmium: ${t.unexpectedArgument(extra[0]!)}\n`)
|
|
359
|
+
return 2
|
|
360
|
+
}
|
|
361
|
+
if (!existsSync(input)) {
|
|
362
|
+
process.stderr.write(`presmium: ${t.notFound(input)}\n`)
|
|
363
|
+
return 2
|
|
364
|
+
}
|
|
365
|
+
const group = values.group === undefined ? undefined : Number(values.group)
|
|
366
|
+
if (group !== undefined && !(Number.isInteger(group) && group >= 1)) {
|
|
367
|
+
process.stderr.write(`presmium: ${t.badGroup(values.group!)}\n`)
|
|
368
|
+
return 2
|
|
369
|
+
}
|
|
370
|
+
const out = resolve(values.out ?? '.')
|
|
371
|
+
const report = importMarkdown(input, { out, exclude: values.exclude, lang: values.lang, group })
|
|
372
|
+
for (const { note, link } of report.unresolved) process.stderr.write(`${t.importUnresolved(note, link)}\n`)
|
|
373
|
+
process.stdout.write(`${t.imported(report.documents.length, report.files, relative(process.cwd(), out) || '.')}\n`)
|
|
374
|
+
if (report.documents.length > 0) process.stdout.write(`${t.importPatterns(documentPatterns(report.documents))}\n`)
|
|
375
|
+
return 0
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
const HELP = { type: 'boolean', short: 'h', default: false } as const
|
|
379
|
+
|
|
380
|
+
function usageError(error: unknown): number {
|
|
381
|
+
process.stderr.write(`presmium: ${errorMessage(error)}\n\n${t.usage}\n`)
|
|
382
|
+
return 2
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
function fail(message: string, code: number): number {
|
|
386
|
+
process.stderr.write(`presmium: ${message}\n`)
|
|
387
|
+
return code
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
/** A path as typed from here: relative below the working directory, absolute elsewhere. */
|
|
391
|
+
function shownPath(path: string): string {
|
|
392
|
+
const shown = relative(process.cwd(), path)
|
|
393
|
+
return !shown ? '.' : shown.startsWith('..') ? path : shown
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
function documentFileMessage(error: DocumentFileError): string {
|
|
397
|
+
return error.code === 'document-changed' ? t.documentChanged : t.documentInvalid(error.detail)
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
/** The deck's entry, or a usage error already printed. */
|
|
401
|
+
function deckEntry(deck: string): string | undefined {
|
|
402
|
+
try {
|
|
403
|
+
const entry = resolveEntry(deck)
|
|
404
|
+
if (existsSync(entry)) return entry
|
|
405
|
+
fail(t.notFound(entry), 2)
|
|
406
|
+
} catch (error) {
|
|
407
|
+
fail(errorMessage(error), 2)
|
|
408
|
+
}
|
|
409
|
+
return undefined
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
async function runVoiceoverCommand(argv: string[], bundled: string): Promise<number> {
|
|
413
|
+
let parsed
|
|
414
|
+
try {
|
|
415
|
+
parsed = parseArgs({ args: argv, allowPositionals: true, options: { voice: { type: 'string' }, yes: { type: 'boolean', default: false }, prune: { type: 'boolean', default: false }, json: { type: 'boolean', default: false }, help: HELP } })
|
|
416
|
+
} catch (error) {
|
|
417
|
+
return usageError(error)
|
|
418
|
+
}
|
|
419
|
+
const { values, positionals } = parsed
|
|
420
|
+
if (values.help) {
|
|
421
|
+
process.stdout.write(`${t.usage}\n`)
|
|
422
|
+
return 0
|
|
423
|
+
}
|
|
424
|
+
const [deck = '.', ...extra] = positionals
|
|
425
|
+
if (extra.length > 0) return fail(t.unexpectedArgument(extra[0]!), 2)
|
|
426
|
+
let voice: SpeechVoice | undefined
|
|
427
|
+
if (values.voice !== undefined) {
|
|
428
|
+
const at = values.voice.indexOf(':'), engine = values.voice.slice(0, Math.max(at, 0)).trim(), id = values.voice.slice(at + 1).trim()
|
|
429
|
+
if (at < 0 || !engine || !id) return fail(t.badVoice(values.voice), 2)
|
|
430
|
+
voice = { engine, voice: id }
|
|
431
|
+
}
|
|
432
|
+
const entry = deckEntry(deck)
|
|
433
|
+
if (!entry) return 2
|
|
434
|
+
try {
|
|
435
|
+
return await runVoiceover({ entry, ...voice ? { voice } : {}, yes: values.yes, prune: values.prune, json: values.json, bundled }, t)
|
|
436
|
+
} catch (error) {
|
|
437
|
+
if (error instanceof VoiceoverFailure) return fail(error.message, 1)
|
|
438
|
+
if (error instanceof DocumentFileError) return fail(documentFileMessage(error), 1)
|
|
439
|
+
return fail(errorMessage(error), 2)
|
|
440
|
+
}
|
|
441
|
+
}
|
|
442
|
+
|
|
443
|
+
async function runSpeechCommand(argv: string[]): Promise<number> {
|
|
444
|
+
let parsed
|
|
445
|
+
try {
|
|
446
|
+
parsed = parseArgs({ args: argv, allowPositionals: true, options: { help: HELP } })
|
|
447
|
+
} catch (error) {
|
|
448
|
+
return usageError(error)
|
|
449
|
+
}
|
|
450
|
+
const { values, positionals } = parsed
|
|
451
|
+
if (values.help) {
|
|
452
|
+
process.stdout.write(`${t.usage}\n`)
|
|
453
|
+
return 0
|
|
454
|
+
}
|
|
455
|
+
const [group, action, dir = '.', ...extra] = positionals
|
|
456
|
+
if (group !== 'key' || (action !== 'set' && action !== 'clear' && action !== 'status')) return fail(t.speechUsage, 2)
|
|
457
|
+
if (extra.length > 0) return fail(t.unexpectedArgument(extra[0]!), 2)
|
|
458
|
+
if (!existsSync(dir) || !statSync(dir).isDirectory()) return fail(t.notFound(resolve(dir)), 2)
|
|
459
|
+
try {
|
|
460
|
+
return await runSpeechKey(action, resolve(dir), t)
|
|
461
|
+
} catch (error) {
|
|
462
|
+
return fail(errorMessage(error), error instanceof SpeechKeyFailure ? 1 : 2)
|
|
463
|
+
}
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
/** The narration as one Markdown file to polish (`export`), and the polished file back into lecture.json (`import`). */
|
|
467
|
+
async function runScriptCommand(argv: string[]): Promise<number> {
|
|
468
|
+
let parsed
|
|
469
|
+
try {
|
|
470
|
+
parsed = parseArgs({ args: argv, allowPositionals: true, options: { out: { type: 'string' }, help: HELP } })
|
|
471
|
+
} catch (error) {
|
|
472
|
+
return usageError(error)
|
|
473
|
+
}
|
|
474
|
+
const { values, positionals } = parsed
|
|
475
|
+
if (values.help) {
|
|
476
|
+
process.stdout.write(`${t.usage}\n`)
|
|
477
|
+
return 0
|
|
478
|
+
}
|
|
479
|
+
const [action, deck, file, ...extra] = positionals
|
|
480
|
+
if (action !== 'export' && action !== 'import') return fail(t.scriptUsage, 2)
|
|
481
|
+
if (!deck) return fail(t.scriptUsage, 2)
|
|
482
|
+
const unexpected = action === 'export' ? file ?? extra[0] : extra[0]
|
|
483
|
+
if (unexpected !== undefined) return fail(t.unexpectedArgument(unexpected), 2)
|
|
484
|
+
if (action === 'import' && values.out !== undefined) return fail(t.optionNotFor('out', 'script import'), 2)
|
|
485
|
+
const entry = deckEntry(deck)
|
|
486
|
+
if (!entry) return 2
|
|
487
|
+
const fallback = join(dirname(entry), 'dist', 'script.md')
|
|
488
|
+
try {
|
|
489
|
+
const source = readDocumentFile(entry)
|
|
490
|
+
if (action === 'export') {
|
|
491
|
+
const out = resolve(values.out ?? fallback)
|
|
492
|
+
const written = exportScript(source.document, CLI_MESSAGES[deckLocale(source.document.metadata.lang)].scriptInstructions)
|
|
493
|
+
await mkdir(dirname(out), { recursive: true })
|
|
494
|
+
await writeFile(out, written.text)
|
|
495
|
+
process.stdout.write(`${t.scriptExported(shownPath(out), written.narrations, written.steps)}\n`)
|
|
496
|
+
return 0
|
|
497
|
+
}
|
|
498
|
+
const input = resolve(file ?? fallback)
|
|
499
|
+
if (!existsSync(input)) return fail(t.notFound(input), 2)
|
|
500
|
+
const { document, changed } = importScript(source.document, await readFile(input, 'utf8'))
|
|
501
|
+
if (changed.length === 0) {
|
|
502
|
+
process.stdout.write(`${t.scriptUnchanged}\n`)
|
|
503
|
+
return 0
|
|
504
|
+
}
|
|
505
|
+
saveDocumentFile(source, document)
|
|
506
|
+
process.stdout.write(`${t.scriptImported(changed)}\n${t.scriptNext(shownPath(dirname(entry)))}\n`)
|
|
507
|
+
return 0
|
|
508
|
+
} catch (error) {
|
|
509
|
+
if (error instanceof ScriptError) return fail(t.scriptErrors[error.code](error.detail, error.line), 1)
|
|
510
|
+
if (error instanceof DocumentFileError) return fail(documentFileMessage(error), 1)
|
|
511
|
+
return fail(errorMessage(error), 2)
|
|
512
|
+
}
|
|
513
|
+
}
|
|
514
|
+
|
|
326
515
|
async function runStudioCommand(argv: string[], bundled: string, presmiumBin: string): Promise<number> {
|
|
327
516
|
const entry = resolveInstalled('@lincyaw/studio', bundled)
|
|
328
517
|
if (!entry) {
|
|
@@ -333,6 +522,18 @@ async function runStudioCommand(argv: string[], bundled: string, presmiumBin: st
|
|
|
333
522
|
return studioMain(argv, { presmium: presmiumBin })
|
|
334
523
|
}
|
|
335
524
|
|
|
525
|
+
/** MCP on stdio, from the installed `@lincyaw/mcp`; stdout carries only its messages. */
|
|
526
|
+
async function runMcpCommand(argv: string[], bundled: string): Promise<number> {
|
|
527
|
+
const entry = resolveInstalled('@lincyaw/mcp/cli', bundled)
|
|
528
|
+
if (!entry) {
|
|
529
|
+
process.stderr.write(`${t.mcpMissing}\n`)
|
|
530
|
+
return 2
|
|
531
|
+
}
|
|
532
|
+
console.log = console.info = console.debug = console.error
|
|
533
|
+
const { main: mcpMain } = await createJiti(import.meta.url).import<{ main(argv: string[], options: { bundled: string }): Promise<number | undefined> }>(entry)
|
|
534
|
+
return await mcpMain(argv, { bundled }) ?? 0
|
|
535
|
+
}
|
|
536
|
+
|
|
336
537
|
function networkLines(listenAddress: string | undefined, url: string): string {
|
|
337
538
|
if (!listenAddress || isLoopback(listenAddress)) return ''
|
|
338
539
|
const { port } = new URL(url)
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { randomBytes } from 'node:crypto'
|
|
2
|
+
import { readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
|
|
3
|
+
import { validateDocument } from '@lincyaw/kernel'
|
|
4
|
+
import type { TeachingDocument } from '@lincyaw/kernel'
|
|
5
|
+
|
|
6
|
+
/** `lecture.json` as it was read: its exact text, to save a change in the same formatting and only if it is unchanged. */
|
|
7
|
+
export interface DocumentFile {
|
|
8
|
+
entry: string
|
|
9
|
+
text: string
|
|
10
|
+
document: TeachingDocument
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
export class DocumentFileError extends Error {
|
|
14
|
+
readonly code: 'document-invalid' | 'document-changed'
|
|
15
|
+
readonly detail: string
|
|
16
|
+
constructor(code: DocumentFileError['code'], detail = '') {
|
|
17
|
+
super(code)
|
|
18
|
+
this.code = code
|
|
19
|
+
this.detail = detail
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
const BOM = String.fromCharCode(0xfeff)
|
|
24
|
+
const issuesOf = (checked: ReturnType<typeof validateDocument>) => checked.issues.slice(0, 3).map(issue => `${issue.path || '/'}: ${issue.message}`).join('; ')
|
|
25
|
+
|
|
26
|
+
export function readDocumentFile(entry: string): DocumentFile {
|
|
27
|
+
const text = readFileSync(entry, 'utf8')
|
|
28
|
+
let value: unknown
|
|
29
|
+
try { value = JSON.parse(text.startsWith(BOM) ? text.slice(1) : text) }
|
|
30
|
+
catch (error) { throw new DocumentFileError('document-invalid', error instanceof Error ? error.message : String(error)) }
|
|
31
|
+
const checked = validateDocument(value)
|
|
32
|
+
if (!checked.document) throw new DocumentFileError('document-invalid', issuesOf(checked))
|
|
33
|
+
return { entry, text, document: checked.document }
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Validates the changed document as the workspace does before saving, then replaces the file atomically in its own
|
|
38
|
+
* indentation, line endings and byte order mark, so that the change is the only difference. Refuses when the file
|
|
39
|
+
* changed since it was read (another editor saved it).
|
|
40
|
+
*/
|
|
41
|
+
export function saveDocumentFile(file: DocumentFile, document: TeachingDocument): void {
|
|
42
|
+
const checked = validateDocument(document)
|
|
43
|
+
if (!checked.document) throw new DocumentFileError('document-invalid', issuesOf(checked))
|
|
44
|
+
const body = file.text.startsWith(BOM) ? file.text.slice(1) : file.text
|
|
45
|
+
const indent = /^\{\r?\n([ \t]+)"/.exec(body)?.[1] ?? ' '
|
|
46
|
+
const newline = body.includes('\r\n') ? '\r\n' : '\n'
|
|
47
|
+
let text = JSON.stringify(checked.document, null, indent)
|
|
48
|
+
if (newline !== '\n') text = text.replaceAll('\n', newline)
|
|
49
|
+
if (body.endsWith('\n')) text += newline
|
|
50
|
+
if (body !== file.text) text = BOM + text
|
|
51
|
+
if (readFileSync(file.entry, 'utf8') !== file.text) throw new DocumentFileError('document-changed')
|
|
52
|
+
const temporary = `${file.entry}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`
|
|
53
|
+
try {
|
|
54
|
+
writeFileSync(temporary, text, { flag: 'wx', mode: statSync(file.entry).mode & 0o777 })
|
|
55
|
+
renameSync(temporary, file.entry)
|
|
56
|
+
} finally {
|
|
57
|
+
rmSync(temporary, { force: true })
|
|
58
|
+
}
|
|
59
|
+
}
|
package/src/import.ts
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
// `presmium import`: a folder of Markdown notes (or one note) to documents, one `lecture.json` per note.
|
|
2
|
+
//
|
|
3
|
+
// `a/b/note.md` becomes `<out>/a/b/note/lecture.json`. Wikilinks resolve as note-taking apps resolve them: by path,
|
|
4
|
+
// then by file name or alias (case-insensitive), the nearest note winning when several share a name; a folder's
|
|
5
|
+
// `index` or `README` note also answers to the folder's name. A local file a note links to is copied into its
|
|
6
|
+
// document's `attachments/`, since a document publishes only files inside the workspace; an excluded folder (`raw`,
|
|
7
|
+
// say) is neither imported nor copied from.
|
|
8
|
+
import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs'
|
|
9
|
+
import { basename, dirname, extname, join, posix, relative, resolve, sep } from 'node:path'
|
|
10
|
+
import { DOCUMENT_ENTRY } from '@lincyaw/kernel'
|
|
11
|
+
import { headingSlug, markdownDocument, noteTitle, splitFrontmatter } from './markdown.ts'
|
|
12
|
+
|
|
13
|
+
export interface ImportOptions {
|
|
14
|
+
out: string
|
|
15
|
+
/** Names (with `*`) of folders and files to leave out, matched against each part of a path. */
|
|
16
|
+
exclude?: string[]
|
|
17
|
+
lang?: string
|
|
18
|
+
/** The note's folder at this depth becomes the document's first tag, by which the site's sidebar groups documents. */
|
|
19
|
+
group?: number
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export interface ImportReport {
|
|
23
|
+
/** The written documents' folders, relative to `out`. */
|
|
24
|
+
documents: string[]
|
|
25
|
+
files: number
|
|
26
|
+
unresolved: { note: string, link: string }[]
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
interface Note { file: string, path: string, dir: string, title: string, aliases: string[] }
|
|
30
|
+
|
|
31
|
+
const MARKDOWN = new Set(['.md', '.markdown'])
|
|
32
|
+
const SKIPPED = new Set(['node_modules'])
|
|
33
|
+
const RESERVED = new Set(['dist', 'templates', 'node_modules'])
|
|
34
|
+
const FOLDER_NOTES = new Set(['index', 'readme'])
|
|
35
|
+
const ATTACHMENTS = 'attachments'
|
|
36
|
+
|
|
37
|
+
const glob = (pattern: string) => new RegExp(`^${pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.')}$`, 'i')
|
|
38
|
+
const toPosix = (path: string) => path.split(sep).join('/')
|
|
39
|
+
const key = (target: string) => target.trim().replace(/^\/+/, '').replace(/\.(?:md|markdown)$/i, '').toLowerCase()
|
|
40
|
+
/** A document folder's part: letters, digits, `.`, `_` and `-`, not starting with `.`. */
|
|
41
|
+
const part = (name: string) => name.replace(/[^\p{L}\p{N}._-]+/gu, '-').replace(/^[.-]+/, '') || 'note'
|
|
42
|
+
|
|
43
|
+
export function importMarkdown(input: string, options: ImportOptions): ImportReport {
|
|
44
|
+
const source = resolve(input)
|
|
45
|
+
const out = resolve(options.out)
|
|
46
|
+
const excluded = (options.exclude ?? []).map(glob)
|
|
47
|
+
const isExcluded = (path: string) => path.split('/').some(name => excluded.some(pattern => pattern.test(name)))
|
|
48
|
+
const single = statSync(source).isFile()
|
|
49
|
+
const root = single ? dirname(source) : source
|
|
50
|
+
|
|
51
|
+
const files: string[] = []
|
|
52
|
+
const seen = new Set<string>()
|
|
53
|
+
const walk = (dir: string) => {
|
|
54
|
+
const real = realpathSync(dir)
|
|
55
|
+
if (seen.has(real)) return
|
|
56
|
+
seen.add(real)
|
|
57
|
+
for (const name of readdirSync(dir).sort()) {
|
|
58
|
+
const file = join(dir, name)
|
|
59
|
+
if (name.startsWith('.') || SKIPPED.has(name) || isExcluded(toPosix(relative(root, file)))) continue
|
|
60
|
+
const stat = statSync(file, { throwIfNoEntry: false })
|
|
61
|
+
if (stat?.isDirectory()) walk(file)
|
|
62
|
+
else if (stat?.isFile() && MARKDOWN.has(extname(name).toLowerCase())) files.push(file)
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
if (single) files.push(source)
|
|
66
|
+
else walk(source)
|
|
67
|
+
|
|
68
|
+
const taken = new Set<string>()
|
|
69
|
+
const notes: Note[] = files.map((file) => {
|
|
70
|
+
const path = toPosix(relative(root, file))
|
|
71
|
+
const parts = path.replace(/\.(?:md|markdown)$/i, '').split('/').map(part)
|
|
72
|
+
if (RESERVED.has(parts[0]!)) parts[0] = `${parts[0]}-notes`
|
|
73
|
+
let dir = parts.join('/')
|
|
74
|
+
for (let n = 2; taken.has(dir.toLowerCase()); n++) dir = `${parts.join('/')}-${n}`
|
|
75
|
+
taken.add(dir.toLowerCase())
|
|
76
|
+
const text = readFileSync(file, 'utf8')
|
|
77
|
+
return { file, path, dir, title: noteTitle(text) ?? basename(file, extname(file)), aliases: splitFrontmatter(text).frontmatter.aliases }
|
|
78
|
+
})
|
|
79
|
+
|
|
80
|
+
const byPath = new Map(notes.map(note => [key(note.path), note]))
|
|
81
|
+
const byName = new Map<string, Note[]>()
|
|
82
|
+
const register = (name: string, note: Note) => {
|
|
83
|
+
const k = key(name)
|
|
84
|
+
if (k && !byName.get(k)?.includes(note)) byName.set(k, [...byName.get(k) ?? [], note])
|
|
85
|
+
}
|
|
86
|
+
for (const note of notes) {
|
|
87
|
+
const stem = posix.basename(note.path).replace(/\.(?:md|markdown)$/i, '')
|
|
88
|
+
register(stem, note)
|
|
89
|
+
note.aliases.forEach(alias => register(alias, note))
|
|
90
|
+
if (FOLDER_NOTES.has(stem.toLowerCase()) && posix.dirname(note.path) !== '.') register(posix.basename(posix.dirname(note.path)), note)
|
|
91
|
+
}
|
|
92
|
+
/** The note nearest to `from` among `candidates`: the one sharing the longest folder path, if only one does. */
|
|
93
|
+
const nearest = (from: Note, candidates: Note[]) => {
|
|
94
|
+
const shared = (note: Note) => {
|
|
95
|
+
const a = posix.dirname(from.path).split('/'), b = posix.dirname(note.path).split('/')
|
|
96
|
+
let n = 0
|
|
97
|
+
while (n < a.length && a[n] === b[n]) n++
|
|
98
|
+
return n
|
|
99
|
+
}
|
|
100
|
+
const best = Math.max(...candidates.map(shared))
|
|
101
|
+
const winners = candidates.filter(note => shared(note) === best)
|
|
102
|
+
return winners.length === 1 ? winners[0] : undefined
|
|
103
|
+
}
|
|
104
|
+
const href = (from: Note, to: Note, fragment?: string) => {
|
|
105
|
+
const path = posix.relative(from.dir, to.dir)
|
|
106
|
+
return `${path ? `${path}/` : ''}${DOCUMENT_ENTRY}${fragment ? `#${headingSlug(fragment)}` : ''}`
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
const report: ImportReport = { documents: [], files: 0, unresolved: [] }
|
|
110
|
+
const copied = new Map<string, string>()
|
|
111
|
+
for (const note of notes) {
|
|
112
|
+
const docDir = join(out, note.dir)
|
|
113
|
+
const names = new Map<string, string>()
|
|
114
|
+
/** A file inside the imported folder to its copy in the document's attachments; undefined for anything else. */
|
|
115
|
+
const attach = (url: string) => {
|
|
116
|
+
const [path = '', ...fragment] = url.split('#')
|
|
117
|
+
let name = path
|
|
118
|
+
try {
|
|
119
|
+
name = decodeURIComponent(path)
|
|
120
|
+
} catch {
|
|
121
|
+
}
|
|
122
|
+
const file = resolve(dirname(note.file), name)
|
|
123
|
+
const rel = toPosix(relative(root, file))
|
|
124
|
+
if (!name || rel.startsWith('../') || isExcluded(rel) || !statSync(file, { throwIfNoEntry: false })?.isFile()) return undefined
|
|
125
|
+
const target = byPath.get(key(rel))
|
|
126
|
+
if (target) return href(note, target, fragment.length ? fragment.join('#') : undefined)
|
|
127
|
+
let copy = names.get(file)
|
|
128
|
+
if (!copy) {
|
|
129
|
+
const base = basename(file)
|
|
130
|
+
copy = [...names.values()].includes(`${ATTACHMENTS}/${base}`) ? `${ATTACHMENTS}/${names.size}-${base}` : `${ATTACHMENTS}/${base}`
|
|
131
|
+
names.set(file, copy)
|
|
132
|
+
}
|
|
133
|
+
copied.set(join(docDir, copy), file)
|
|
134
|
+
return `${encodeURI(copy)}${fragment.length ? `#${fragment.join('#')}` : ''}`
|
|
135
|
+
}
|
|
136
|
+
const { document, unresolved } = markdownDocument(readFileSync(note.file, 'utf8'), {
|
|
137
|
+
id: note.dir.replace(/\//g, '--'),
|
|
138
|
+
title: note.title,
|
|
139
|
+
lang: options.lang,
|
|
140
|
+
links: {
|
|
141
|
+
page: (target, fragment) => {
|
|
142
|
+
const direct = byPath.get(key(target)) ?? byPath.get(key(posix.join(posix.dirname(note.path), target)))
|
|
143
|
+
const candidates = byName.get(key(target)) ?? []
|
|
144
|
+
const found = direct ?? (candidates.length === 1 ? candidates[0] : candidates.length > 1 ? nearest(note, candidates) : undefined)
|
|
145
|
+
return found && href(note, found, fragment)
|
|
146
|
+
},
|
|
147
|
+
url: attach,
|
|
148
|
+
image: attach,
|
|
149
|
+
},
|
|
150
|
+
})
|
|
151
|
+
const folder = options.group ? posix.dirname(note.path).split('/').slice(0, options.group).at(-1) : undefined
|
|
152
|
+
if (folder && folder !== '.') document.metadata.tags = [folder, ...(document.metadata.tags ?? []).filter(tag => tag !== folder)]
|
|
153
|
+
mkdirSync(docDir, { recursive: true })
|
|
154
|
+
writeFileSync(join(docDir, DOCUMENT_ENTRY), `${JSON.stringify(document, null, 2)}\n`)
|
|
155
|
+
report.documents.push(note.dir)
|
|
156
|
+
report.unresolved.push(...unresolved.map(link => ({ note: note.path, link })))
|
|
157
|
+
}
|
|
158
|
+
for (const [copy, file] of copied) {
|
|
159
|
+
mkdirSync(dirname(copy), { recursive: true })
|
|
160
|
+
if (!existsSync(copy) || statSync(copy).mtimeMs < statSync(file).mtimeMs || statSync(copy).size !== statSync(file).size) copyFileSync(file, copy)
|
|
161
|
+
}
|
|
162
|
+
report.files = copied.size
|
|
163
|
+
return report
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
/** The `documents` patterns that cover these folders: one per depth, as workspace patterns do not cross folders. */
|
|
167
|
+
export function documentPatterns(dirs: string[]): string[] {
|
|
168
|
+
return [...new Set(dirs.map(dir => dir.split('/').length))].sort((a, b) => a - b).map(depth => `${'*/'.repeat(depth)}${DOCUMENT_ENTRY}`)
|
|
169
|
+
}
|