@lincyaw/cli 1.0.0-rc.9 → 1.0.0-rc.90

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 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), from `@lincyaw/studio` installed in the project (`--port`, `--host`); installed globally, it is `presmium-studio` |
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.9",
3
+ "version": "1.0.0-rc.90",
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
- "@lincyaw/compiler": "1.0.0-rc.9",
40
- "@lincyaw/server": "1.0.0-rc.9",
41
- "@lincyaw/workspace": "1.0.0-rc.9",
42
- "@lincyaw/kernel": "1.0.0-rc.9",
43
- "@lincyaw/skills": "1.0.0-rc.9"
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.90",
46
+ "@lincyaw/kernel": "1.0.0-rc.90",
47
+ "@lincyaw/server": "1.0.0-rc.90",
48
+ "@lincyaw/skills": "1.0.0-rc.90",
49
+ "@lincyaw/workspace": "1.0.0-rc.90"
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, ffmpegInstallCommand, findFfmpeg, irRevision, lanAddresses } from '@lincyaw/kernel/node'
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,15 @@ 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'
26
+ import { mcpWorkspaceSession } from './mcp-workspace.ts'
21
27
 
22
28
  const BUNDLED = fileURLToPath(new URL('..', import.meta.url))
23
29
  const PRESMIUM_BIN = fileURLToPath(new URL('../bin/presmium.mjs', import.meta.url))
@@ -36,7 +42,7 @@ const OPTIONS = {
36
42
  'dev': ['to', 'out', 'server-port', 'allow'],
37
43
  'ir': ['out'],
38
44
  'check': ['json', 'update-lock', 'env', 'audience', 'external-links'],
39
- 'serve': ['port', 'host', 'operator-dir', 'preview-origin', 'public-url'],
45
+ 'serve': ['port', 'host', 'operator-dir', 'preview-origin', 'public-url', 'allow'],
40
46
  } as const
41
47
 
42
48
  type Name = keyof typeof OPTIONS
@@ -66,6 +72,11 @@ export async function main(argv: string[], options: MainOptions = {}): Promise<n
66
72
  if (argv[0] === 'new') return runNewCommand(argv.slice(1), bundled)
67
73
  if (argv[0] === 'skills') return (await import('@lincyaw/skills')).main(argv.slice(1))
68
74
  if (argv[0] === 'studio') return runStudioCommand(argv.slice(1), bundled, options.bin ?? PRESMIUM_BIN)
75
+ if (argv[0] === 'mcp') return runMcpCommand(argv.slice(1), bundled)
76
+ if (argv[0] === 'import') return runImportCommand(argv.slice(1))
77
+ if (argv[0] === 'voiceover') return runVoiceoverCommand(argv.slice(1), bundled)
78
+ if (argv[0] === 'speech') return runSpeechCommand(argv.slice(1))
79
+ if (argv[0] === 'script') return runScriptCommand(argv.slice(1))
69
80
  let command: Command | 'help'
70
81
  try {
71
82
  command = parseCommand(argv)
@@ -86,7 +97,7 @@ export async function main(argv: string[], options: MainOptions = {}): Promise<n
86
97
  case 'serve': return await runServeCommand(command, bundled)
87
98
  }
88
99
  } catch (error) {
89
- process.stderr.write(`presmium: ${errorMessage(error)}\n`)
100
+ process.stderr.write(`presmium: ${typeof error === 'object' && error !== null && 'code' in error && error.code === 'workspace-service-already-running' ? t.workspaceServiceBusy('url' in error && typeof error.url === 'string' ? error.url : undefined) : errorMessage(error)}\n`)
90
101
  return 2
91
102
  }
92
103
  }
@@ -289,12 +300,12 @@ async function runServeCommand(command: Command, bundled: string): Promise<numbe
289
300
  check: compilation => compilation.check(),
290
301
  previewOrigins: command.previewOrigins,
291
302
  ...command.publicUrl ? { publicUrl: command.publicUrl } : {},
303
+ allow: command.allow,
292
304
  })
293
305
  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
306
  if (command.listenAddress && !isLoopback(command.listenAddress)) {
295
307
  process.stderr.write(`${t.serveOpen(command.listenAddress, new URL(started.url).port)}\n`)
296
308
  }
297
- if (!findFfmpeg()) process.stderr.write(`${t.noFfmpeg(ffmpegInstallCommand())}\n`)
298
309
  await new Promise<void>((done) => {
299
310
  process.once('SIGINT', done)
300
311
  process.once('SIGTERM', done)
@@ -323,6 +334,185 @@ async function runNewCommand(argv: string[], bundled: string): Promise<number> {
323
334
  return createMain(argv)
324
335
  }
325
336
 
337
+ /** Markdown notes to documents; prints what it wrote, the links it could not resolve and the patterns that list them. */
338
+ function runImportCommand(argv: string[]): number {
339
+ let parsed
340
+ try {
341
+ parsed = parseArgs({ args: argv, allowPositionals: true, options: {
342
+ out: { type: 'string' }, exclude: { type: 'string', multiple: true }, lang: { type: 'string' }, group: { type: 'string' }, help: { type: 'boolean', short: 'h', default: false },
343
+ } })
344
+ } catch (error) {
345
+ process.stderr.write(`presmium: ${errorMessage(error)}\n\n${t.usage}\n`)
346
+ return 2
347
+ }
348
+ const { values, positionals } = parsed
349
+ if (values.help) {
350
+ process.stdout.write(`${t.usage}\n`)
351
+ return 0
352
+ }
353
+ const [input, ...extra] = positionals
354
+ if (!input) {
355
+ process.stderr.write(`presmium: ${t.importMissing}\n`)
356
+ return 2
357
+ }
358
+ if (extra.length > 0) {
359
+ process.stderr.write(`presmium: ${t.unexpectedArgument(extra[0]!)}\n`)
360
+ return 2
361
+ }
362
+ if (!existsSync(input)) {
363
+ process.stderr.write(`presmium: ${t.notFound(input)}\n`)
364
+ return 2
365
+ }
366
+ const group = values.group === undefined ? undefined : Number(values.group)
367
+ if (group !== undefined && !(Number.isInteger(group) && group >= 1)) {
368
+ process.stderr.write(`presmium: ${t.badGroup(values.group!)}\n`)
369
+ return 2
370
+ }
371
+ const out = resolve(values.out ?? '.')
372
+ const report = importMarkdown(input, { out, exclude: values.exclude, lang: values.lang, group })
373
+ for (const { note, link } of report.unresolved) process.stderr.write(`${t.importUnresolved(note, link)}\n`)
374
+ process.stdout.write(`${t.imported(report.documents.length, report.files, relative(process.cwd(), out) || '.')}\n`)
375
+ if (report.documents.length > 0) process.stdout.write(`${t.importPatterns(documentPatterns(report.documents))}\n`)
376
+ return 0
377
+ }
378
+
379
+ const HELP = { type: 'boolean', short: 'h', default: false } as const
380
+
381
+ function usageError(error: unknown): number {
382
+ process.stderr.write(`presmium: ${errorMessage(error)}\n\n${t.usage}\n`)
383
+ return 2
384
+ }
385
+
386
+ function fail(message: string, code: number): number {
387
+ process.stderr.write(`presmium: ${message}\n`)
388
+ return code
389
+ }
390
+
391
+ /** A path as typed from here: relative below the working directory, absolute elsewhere. */
392
+ function shownPath(path: string): string {
393
+ const shown = relative(process.cwd(), path)
394
+ return !shown ? '.' : shown.startsWith('..') ? path : shown
395
+ }
396
+
397
+ function documentFileMessage(error: DocumentFileError): string {
398
+ return error.code === 'document-changed' ? t.documentChanged : t.documentInvalid(error.detail)
399
+ }
400
+
401
+ /** The deck's entry, or a usage error already printed. */
402
+ function deckEntry(deck: string): string | undefined {
403
+ try {
404
+ const entry = resolveEntry(deck)
405
+ if (existsSync(entry)) return entry
406
+ fail(t.notFound(entry), 2)
407
+ } catch (error) {
408
+ fail(errorMessage(error), 2)
409
+ }
410
+ return undefined
411
+ }
412
+
413
+ async function runVoiceoverCommand(argv: string[], bundled: string): Promise<number> {
414
+ let parsed
415
+ try {
416
+ 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 } })
417
+ } catch (error) {
418
+ return usageError(error)
419
+ }
420
+ const { values, positionals } = parsed
421
+ if (values.help) {
422
+ process.stdout.write(`${t.usage}\n`)
423
+ return 0
424
+ }
425
+ const [deck = '.', ...extra] = positionals
426
+ if (extra.length > 0) return fail(t.unexpectedArgument(extra[0]!), 2)
427
+ let voice: SpeechVoice | undefined
428
+ if (values.voice !== undefined) {
429
+ const at = values.voice.indexOf(':'), engine = values.voice.slice(0, Math.max(at, 0)).trim(), id = values.voice.slice(at + 1).trim()
430
+ if (at < 0 || !engine || !id) return fail(t.badVoice(values.voice), 2)
431
+ voice = { engine, voice: id }
432
+ }
433
+ const entry = deckEntry(deck)
434
+ if (!entry) return 2
435
+ try {
436
+ return await runVoiceover({ entry, ...voice ? { voice } : {}, yes: values.yes, prune: values.prune, json: values.json, bundled }, t)
437
+ } catch (error) {
438
+ if (error instanceof VoiceoverFailure) return fail(error.message, 1)
439
+ if (error instanceof DocumentFileError) return fail(documentFileMessage(error), 1)
440
+ return fail(errorMessage(error), 2)
441
+ }
442
+ }
443
+
444
+ async function runSpeechCommand(argv: string[]): Promise<number> {
445
+ let parsed
446
+ try {
447
+ parsed = parseArgs({ args: argv, allowPositionals: true, options: { help: HELP } })
448
+ } catch (error) {
449
+ return usageError(error)
450
+ }
451
+ const { values, positionals } = parsed
452
+ if (values.help) {
453
+ process.stdout.write(`${t.usage}\n`)
454
+ return 0
455
+ }
456
+ const [group, action, dir = '.', ...extra] = positionals
457
+ if (group !== 'key' || (action !== 'set' && action !== 'clear' && action !== 'status')) return fail(t.speechUsage, 2)
458
+ if (extra.length > 0) return fail(t.unexpectedArgument(extra[0]!), 2)
459
+ if (!existsSync(dir) || !statSync(dir).isDirectory()) return fail(t.notFound(resolve(dir)), 2)
460
+ try {
461
+ return await runSpeechKey(action, resolve(dir), t)
462
+ } catch (error) {
463
+ return fail(errorMessage(error), error instanceof SpeechKeyFailure ? 1 : 2)
464
+ }
465
+ }
466
+
467
+ /** The narration as one Markdown file to polish (`export`), and the polished file back into lecture.json (`import`). */
468
+ async function runScriptCommand(argv: string[]): Promise<number> {
469
+ let parsed
470
+ try {
471
+ parsed = parseArgs({ args: argv, allowPositionals: true, options: { out: { type: 'string' }, help: HELP } })
472
+ } catch (error) {
473
+ return usageError(error)
474
+ }
475
+ const { values, positionals } = parsed
476
+ if (values.help) {
477
+ process.stdout.write(`${t.usage}\n`)
478
+ return 0
479
+ }
480
+ const [action, deck, file, ...extra] = positionals
481
+ if (action !== 'export' && action !== 'import') return fail(t.scriptUsage, 2)
482
+ if (!deck) return fail(t.scriptUsage, 2)
483
+ const unexpected = action === 'export' ? file ?? extra[0] : extra[0]
484
+ if (unexpected !== undefined) return fail(t.unexpectedArgument(unexpected), 2)
485
+ if (action === 'import' && values.out !== undefined) return fail(t.optionNotFor('out', 'script import'), 2)
486
+ const entry = deckEntry(deck)
487
+ if (!entry) return 2
488
+ const fallback = join(dirname(entry), 'dist', 'script.md')
489
+ try {
490
+ const source = readDocumentFile(entry)
491
+ if (action === 'export') {
492
+ const out = resolve(values.out ?? fallback)
493
+ const written = exportScript(source.document, CLI_MESSAGES[deckLocale(source.document.metadata.lang)].scriptInstructions)
494
+ await mkdir(dirname(out), { recursive: true })
495
+ await writeFile(out, written.text)
496
+ process.stdout.write(`${t.scriptExported(shownPath(out), written.narrations, written.steps)}\n`)
497
+ return 0
498
+ }
499
+ const input = resolve(file ?? fallback)
500
+ if (!existsSync(input)) return fail(t.notFound(input), 2)
501
+ const { document, changed } = importScript(source.document, await readFile(input, 'utf8'))
502
+ if (changed.length === 0) {
503
+ process.stdout.write(`${t.scriptUnchanged}\n`)
504
+ return 0
505
+ }
506
+ saveDocumentFile(source, document)
507
+ process.stdout.write(`${t.scriptImported(changed)}\n${t.scriptNext(shownPath(dirname(entry)))}\n`)
508
+ return 0
509
+ } catch (error) {
510
+ if (error instanceof ScriptError) return fail(t.scriptErrors[error.code](error.detail, error.line), 1)
511
+ if (error instanceof DocumentFileError) return fail(documentFileMessage(error), 1)
512
+ return fail(errorMessage(error), 2)
513
+ }
514
+ }
515
+
326
516
  async function runStudioCommand(argv: string[], bundled: string, presmiumBin: string): Promise<number> {
327
517
  const entry = resolveInstalled('@lincyaw/studio', bundled)
328
518
  if (!entry) {
@@ -333,6 +523,21 @@ async function runStudioCommand(argv: string[], bundled: string, presmiumBin: st
333
523
  return studioMain(argv, { presmium: presmiumBin })
334
524
  }
335
525
 
526
+ /** MCP on stdio, from the installed `@lincyaw/mcp`; stdout carries only its messages. */
527
+ async function runMcpCommand(argv: string[], bundled: string): Promise<number> {
528
+ const entry = resolveInstalled('@lincyaw/mcp/cli', bundled)
529
+ if (!entry) {
530
+ process.stderr.write(`${t.mcpMissing}\n`)
531
+ return 2
532
+ }
533
+ console.log = console.info = console.debug = console.error
534
+ const workspace = mcpWorkspaceSession(bundled)
535
+ const { main: mcpMain } = await createJiti(import.meta.url).import<{ main(argv: string[], options: { bundled: string, startWorkspace: typeof workspace.startWorkspace }): Promise<number | undefined> }>(entry)
536
+ try { return await mcpMain(argv, { bundled, startWorkspace: workspace.startWorkspace }) ?? 0 }
537
+ catch (error) { return fail(errorMessage(error), 2) }
538
+ finally { await workspace.close() }
539
+ }
540
+
336
541
  function networkLines(listenAddress: string | undefined, url: string): string {
337
542
  if (!listenAddress || isLoopback(listenAddress)) return ''
338
543
  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
+ }