@lincyaw/cli 1.0.0-rc.1 → 1.0.0-rc.100

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.
@@ -0,0 +1,328 @@
1
+ // One Markdown note to one document (`presmium import`). Pure: the caller resolves links and copies files.
2
+ //
3
+ // Each level-1 or level-2 heading starts a page (the first page holds what comes before it, under the note's title);
4
+ // every page has one step that shows all its blocks. Paragraphs, headings, lists, quotes, code, math and tables become
5
+ // rich text; a Mermaid diagram becomes a code block of its own, which is what draws it; a paragraph holding only an
6
+ // image becomes an image block. What has no rich-text node (raw HTML, footnotes, rules, callouts) is kept as an mdast
7
+ // extension that the viewer renders. `[[target]]` and `[[target|label]]` wikilinks, relative links and images go through
8
+ // the caller's `links`. Node ids come from the content, so importing an unchanged paragraph again keeps its id.
9
+ import { fromMarkdown } from 'mdast-util-from-markdown'
10
+ import { gfmFromMarkdown } from 'mdast-util-gfm'
11
+ import { mathFromMarkdown } from 'mdast-util-math'
12
+ import { gfm } from 'micromark-extension-gfm'
13
+ import { math } from 'micromark-extension-math'
14
+ import { parse as parseYaml } from 'yaml'
15
+ import type { Asset, DocumentBlock, InlineNode, MdastNode, RichTextNode, Section, Step, TeachingDocument, TextMark } from '@lincyaw/kernel'
16
+
17
+ export interface Frontmatter {
18
+ title?: string
19
+ description?: string
20
+ lang?: string
21
+ tags: string[]
22
+ aliases: string[]
23
+ }
24
+
25
+ export interface MarkdownLinks {
26
+ /** A wikilink's target (without `#fragment`) to the href of the document it names; undefined when there is none. */
27
+ page(target: string, fragment: string | undefined): string | undefined
28
+ /** A relative URL of a link to its new href; undefined when it leads nowhere that is published. */
29
+ url(url: string): string | undefined
30
+ /** A relative URL of an image to the location of its copy, relative to the document. */
31
+ image(url: string): string | undefined
32
+ }
33
+
34
+ export interface ImportedMarkdown {
35
+ document: TeachingDocument
36
+ /** Wikilinks and relative links that `links` could not resolve, as written. */
37
+ unresolved: string[]
38
+ }
39
+
40
+ const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/
41
+ /** Stands in for the `|` of `[[target|label]]` while parsing, so a GFM table does not split the cell at it. */
42
+ const LABEL = '\uE000'
43
+ const WIKILINK = new RegExp(`\\[\\[([^\\]|${LABEL}\\n]+)(?:[|${LABEL}]([^\\]\\n]+))?\\]\\]`, 'g')
44
+ const HIGHLIGHT = /==(?=\S)([^=\n]*\S)==/g
45
+ const CALLOUT = /^\[!([A-Za-z]+)\][+-]?[ \t]*/
46
+ const SCHEME = /^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i
47
+ const MARKS: Record<string, TextMark['type']> = { strong: 'bold', emphasis: 'italic', delete: 'strike' }
48
+ const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/gu
49
+ const LETTER = /\p{L}/gu
50
+
51
+ export function splitFrontmatter(source: string): { frontmatter: Frontmatter, body: string } {
52
+ const match = FRONTMATTER.exec(source)
53
+ let data: unknown
54
+ if (match) {
55
+ try {
56
+ data = parseYaml(match[1]!)
57
+ } catch {
58
+ }
59
+ }
60
+ const record = data !== null && typeof data === 'object' && !Array.isArray(data) ? data as Record<string, unknown> : {}
61
+ const text = (key: string) => (typeof record[key] === 'string' && (record[key] as string).trim() ? (record[key] as string).trim() : undefined)
62
+ const list = (key: string) => {
63
+ const value = record[key]
64
+ return (Array.isArray(value) ? value : typeof value === 'string' ? value.split(',') : [])
65
+ .flatMap(item => (typeof item === 'string' || typeof item === 'number' ? [String(item).trim()] : [])).filter(Boolean)
66
+ }
67
+ return {
68
+ frontmatter: { title: text('title'), description: text('description'), lang: text('lang'), tags: list('tags'), aliases: list('aliases') },
69
+ body: match ? source.slice(match[0].length) : source,
70
+ }
71
+ }
72
+
73
+ /** The title of a note: its frontmatter title, else its first level-1 heading. */
74
+ export function noteTitle(source: string): string | undefined {
75
+ const { frontmatter, body } = splitFrontmatter(source)
76
+ return frontmatter.title ?? /^#[ \t]+(.+?)[ \t#]*$/m.exec(body)?.[1]?.trim()
77
+ }
78
+
79
+ /** The anchor of a heading, as GitHub writes it: lower case, punctuation dropped, spaces to hyphens. */
80
+ export function headingSlug(text: string): string {
81
+ return text.trim().toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, '').replace(/\s/g, '-')
82
+ }
83
+
84
+ function guessLang(text: string): string {
85
+ const letters = text.match(LETTER)?.length ?? 0
86
+ return letters > 0 && (text.match(CJK)?.length ?? 0) / letters > 0.3 ? 'zh-CN' : 'en'
87
+ }
88
+
89
+ function plain(node: MdastNode): string {
90
+ if (typeof node.value === 'string') return node.value
91
+ return (node.children ?? []).map(plain).join('')
92
+ }
93
+
94
+ function hash(text: string): string {
95
+ let h = 0x811c9dc5
96
+ for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 0x01000193)
97
+ return (h >>> 0).toString(36)
98
+ }
99
+
100
+ function withoutPositions(node: MdastNode): unknown {
101
+ const { position: _position, children, ...rest } = node
102
+ return children ? { ...rest, children: children.map(withoutPositions) } : rest
103
+ }
104
+
105
+ function restoreLabels(node: MdastNode): void {
106
+ if (typeof node.value === 'string') node.value = node.value.replaceAll(LABEL, '|')
107
+ node.children?.forEach(restoreLabels)
108
+ }
109
+
110
+ export function markdownDocument(source: string, options: { id: string, title: string, lang?: string, links: MarkdownLinks }): ImportedMarkdown {
111
+ const { frontmatter, body } = splitFrontmatter(source)
112
+ const protectedBody = body.replace(/\[\[([^\]|\n]+)\|([^\]\n]+)\]\]/g, (_, target: string, label: string) => `[[${target}${LABEL}${label}]]`)
113
+ const root = fromMarkdown(protectedBody, { extensions: [gfm(), math()], mdastExtensions: [gfmFromMarkdown(), mathFromMarkdown()] }) as unknown as MdastNode
114
+ const unresolved: string[] = []
115
+ const definitions = new Map<string, string>()
116
+ const collect = (node: MdastNode) => {
117
+ if (node.type === 'definition') definitions.set(String(node.identifier).toLowerCase(), String(node.url))
118
+ node.children?.forEach(collect)
119
+ }
120
+ collect(root)
121
+
122
+ // Links are rewritten in the mdast first, so callouts and other extensions carry the same hrefs as rich text.
123
+ const relink = (node: MdastNode): MdastNode[] => {
124
+ if (node.type === 'text' && typeof node.value === 'string' && node.value.includes('[[')) return wikilinks(node.value)
125
+ if ((node.type === 'link' || node.type === 'definition') && typeof node.url === 'string' && !SCHEME.test(node.url)) {
126
+ const href = options.links.url(node.url)
127
+ if (href === undefined) {
128
+ unresolved.push(node.url)
129
+ if (node.type === 'link') return (node.children ?? []).flatMap(relink)
130
+ }
131
+ node.url = href ?? node.url
132
+ }
133
+ if (node.type === 'linkReference') {
134
+ const url = definitions.get(String(node.identifier).toLowerCase())
135
+ if (url !== undefined) return relink({ type: 'link', url, children: node.children ?? [] })
136
+ }
137
+ if (node.children) node.children = node.children.flatMap(relink)
138
+ return [node]
139
+ }
140
+ const wikilinks = (value: string): MdastNode[] => {
141
+ const out: MdastNode[] = []
142
+ let cursor = 0
143
+ for (const match of value.matchAll(WIKILINK)) {
144
+ if (match.index > cursor) out.push({ type: 'text', value: value.slice(cursor, match.index) })
145
+ const written = match[1]!.trim()
146
+ const [target = '', ...fragment] = written.split('#')
147
+ const label = (match[2] ?? written).trim()
148
+ const href = options.links.page(target.trim(), fragment.length ? fragment.join('#') : undefined)
149
+ if (href === undefined) unresolved.push(`[[${written}]]`)
150
+ out.push(href === undefined ? { type: 'text', value: label } : { type: 'link', url: href, children: [{ type: 'text', value: label }] })
151
+ cursor = match.index + match[0].length
152
+ }
153
+ if (cursor < value.length) out.push({ type: 'text', value: value.slice(cursor) })
154
+ return out
155
+ }
156
+ root.children = (root.children ?? []).flatMap(relink)
157
+ restoreLabels(root)
158
+
159
+ const used = new Set<string>()
160
+ const unique = (base: string) => {
161
+ let id = base.slice(0, 180) || 'node'
162
+ for (let n = 2; used.has(id); n++) id = `${base.slice(0, 180)}-${n}`
163
+ used.add(id)
164
+ return id
165
+ }
166
+ const idOf = (prefix: string, node: MdastNode) => unique(`${prefix}-${hash(JSON.stringify(withoutPositions(node)))}`)
167
+ const extension = (node: MdastNode): RichTextNode => {
168
+ const text = plain(node).trim()
169
+ return { id: idOf(node.type, node), type: 'extension', kind: 'presmium.mdast', schemaVersion: 1, data: { node: withoutPositions(node) as never },
170
+ fallback: text ? [{ id: idOf('fallback', node), type: 'paragraph', children: [{ type: 'text', text }] }] : [] }
171
+ }
172
+
173
+ const inline = (nodes: MdastNode[], marks: TextMark[] = []): InlineNode[] => nodes.flatMap((node): InlineNode[] => {
174
+ const styled = (text: string, extra: TextMark[] = []): InlineNode => ({ type: 'text', text, ...marks.length + extra.length ? { marks: [...marks, ...extra] } : {} })
175
+ if (node.type === 'text') {
176
+ const value = String(node.value ?? '')
177
+ if (!value.includes('==')) return value ? [styled(value)] : []
178
+ const out: InlineNode[] = []
179
+ let cursor = 0
180
+ for (const match of value.matchAll(HIGHLIGHT)) {
181
+ if (match.index > cursor) out.push(styled(value.slice(cursor, match.index)))
182
+ out.push(styled(match[1]!, [{ type: 'background', value: 'warn' }]))
183
+ cursor = match.index + match[0].length
184
+ }
185
+ if (cursor < value.length) out.push(styled(value.slice(cursor)))
186
+ return out
187
+ }
188
+ if (node.type === 'break') return [{ type: 'break' }]
189
+ if (node.type === 'inlineMath') return [{ type: 'math', value: String(node.value ?? '') }]
190
+ if (node.type === 'inlineCode') return [styled(String(node.value ?? ''), [{ type: 'code' }])]
191
+ if (MARKS[node.type]) return inline(node.children ?? [], [...marks, { type: MARKS[node.type]! } as TextMark])
192
+ if (node.type === 'link') return [{ type: 'link', href: String(node.url), children: inline(node.children ?? [], marks) }]
193
+ if (node.type === 'image' && typeof node.url === 'string') {
194
+ const href = SCHEME.test(node.url) ? node.url : options.links.image(node.url)
195
+ return href ? [{ type: 'link', href, children: [styled(String(node.alt || node.url))] }] : [styled(String(node.alt ?? ''))]
196
+ }
197
+ return [{ type: 'extension', kind: 'presmium.mdast', schemaVersion: 1, data: { node: withoutPositions(node) as never }, fallback: plain(node) }]
198
+ })
199
+
200
+ const rich = (node: MdastNode): RichTextNode[] => {
201
+ const children = node.children ?? []
202
+ switch (node.type) {
203
+ case 'paragraph': {
204
+ const content = inline(children)
205
+ return content.length ? [{ id: idOf('p', node), type: 'paragraph', children: content }] : []
206
+ }
207
+ case 'heading':
208
+ return [{ id: unique(headingSlug(plain(node)) || `h-${hash(plain(node))}`), type: 'heading', level: Math.min(6, Math.max(1, Number(node.depth))) as 1, children: inline(children) }]
209
+ case 'blockquote': {
210
+ const callout = calloutOf(node)
211
+ return callout ? [extension(callout)] : [{ id: idOf('quote', node), type: 'blockquote', children: children.flatMap(rich) }]
212
+ }
213
+ case 'list':
214
+ return [{ id: idOf('list', node), type: 'list', ordered: Boolean(node.ordered), ...Number(node.start) >= 1 ? { start: Number(node.start) } : {},
215
+ children: children.map(item => ({ id: idOf('item', item), type: 'listItem', ...typeof item.checked === 'boolean' ? { checked: item.checked } : {}, children: (item.children ?? []).flatMap(rich) })) }]
216
+ case 'code':
217
+ return [{ id: idOf('code', node), type: 'code', language: String(node.lang ?? ''), value: String(node.value ?? '') }]
218
+ case 'math':
219
+ return [{ id: idOf('math', node), type: 'math', value: String(node.value ?? '') }]
220
+ case 'table': {
221
+ const align = Array.isArray(node.align) ? node.align as (string | null)[] : []
222
+ return [{ id: idOf('table', node), type: 'table', headerRows: 1, children: children.map(row => ({ id: idOf('row', row), type: 'tableRow',
223
+ children: (row.children ?? []).map((cell, c) => ({ id: idOf('cell', cell), type: 'tableCell', children: inline(cell.children ?? []),
224
+ ...align[c] ? { style: { alignment: align[c] as 'left' } } : {} })) })) }]
225
+ }
226
+ case 'definition':
227
+ return []
228
+ default:
229
+ return [extension(node)]
230
+ }
231
+ }
232
+
233
+ // Pages: a level-1 or level-2 heading starts one. The note's own title heading opens the first page and is not repeated.
234
+ const nodes = root.children ?? []
235
+ const title = frontmatter.title ?? (nodes[0]?.type === 'heading' && nodes[0].depth === 1 ? plain(nodes[0]).trim() : undefined) ?? options.title
236
+ const pages: { title: string, level: number, nodes: MdastNode[] }[] = [{ title, level: 1, nodes: [] }]
237
+ nodes.forEach((node, i) => {
238
+ const opensPage = node.type === 'heading' && Number(node.depth) <= 2
239
+ if (opensPage && i === 0 && node.depth === 1 && plain(node).trim() === title) return
240
+ if (opensPage) pages.push({ title: plain(node).trim() || title, level: Number(node.depth), nodes: [] })
241
+ else pages.at(-1)!.nodes.push(node)
242
+ })
243
+ if (pages.length > 1 && pages[0]!.nodes.length === 0 && pages[1]!.level === 1) pages.shift()
244
+
245
+ const sections: Record<string, Section> = {}, blocks: Record<string, DocumentBlock> = {}, steps: Record<string, Step> = {}, assets: Record<string, Asset> = {}
246
+ const sectionOrder: string[] = []
247
+ for (const page of pages) {
248
+ const sectionId = unique(headingSlug(page.title) || `page-${hash(page.title)}`)
249
+ const children: string[] = []
250
+ let text: RichTextNode[] = []
251
+ const flush = () => {
252
+ if (!text.length) return
253
+ const id = unique(`${sectionId}--text-${children.length}`)
254
+ blocks[id] = { id, type: 'text', content: text }
255
+ children.push(id)
256
+ text = []
257
+ }
258
+ for (const node of page.nodes) {
259
+ const image = node.type === 'paragraph' ? soleImage(node) : undefined
260
+ const location = image && typeof image.url === 'string' && !SCHEME.test(image.url) ? options.links.image(image.url) : undefined
261
+ if (node.type === 'code' && (node.lang === 'mermaid' || node.lang === 'mmd')) {
262
+ flush()
263
+ const id = unique(`${sectionId}--diagram-${children.length}`)
264
+ blocks[id] = { id, type: 'code', language: 'mermaid', value: String(node.value ?? '') }
265
+ children.push(id)
266
+ } else if (image && location) {
267
+ flush()
268
+ const id = unique(`${sectionId}--image-${children.length}`), assetId = unique(`asset-${hash(location)}`)
269
+ assets[assetId] = { id: assetId, kind: 'image', location, ...image.title ? { title: String(image.title) } : {} }
270
+ blocks[id] = { id, type: 'image', assetId, alt: String(image.alt ?? '') }
271
+ children.push(id)
272
+ } else {
273
+ if (image && !location && typeof image.url === 'string') unresolved.push(image.url)
274
+ text.push(...rich(node))
275
+ }
276
+ }
277
+ flush()
278
+ const stepId = unique(`${sectionId}--step`)
279
+ sections[sectionId] = { id: sectionId, title: page.title, level: Math.min(2, page.level) as 1, children, stepOrder: [stepId], layout: { type: 'stack' } }
280
+ steps[stepId] = { id: stepId, sectionId, visuals: children.map(blockId => ({ blockId, visible: true })), narrationIds: [] }
281
+ sectionOrder.push(sectionId)
282
+ }
283
+
284
+ return {
285
+ document: {
286
+ schemaVersion: 1,
287
+ id: options.id,
288
+ metadata: {
289
+ title,
290
+ lang: frontmatter.lang ?? options.lang ?? guessLang(body),
291
+ ...frontmatter.description ? { description: frontmatter.description } : {},
292
+ ...frontmatter.tags.length ? { tags: frontmatter.tags } : {},
293
+ plugins: [],
294
+ renderers: { web: {} },
295
+ },
296
+ sectionOrder, sections, blocks, steps, narrations: {}, assets, definitions: {},
297
+ production: { defaults: {}, stepOverrides: {}, mediaClips: [] },
298
+ } as TeachingDocument,
299
+ unresolved: [...new Set(unresolved)],
300
+ }
301
+ }
302
+
303
+ function soleImage(paragraph: MdastNode): MdastNode | undefined {
304
+ const content = (paragraph.children ?? []).filter(child => !(child.type === 'text' && !String(child.value ?? '').trim()))
305
+ return content.length === 1 && content[0]!.type === 'image' ? content[0] : undefined
306
+ }
307
+
308
+ /** `> [!note] Title` (as GitHub and Obsidian write callouts) as a MyST admonition, which the viewer draws as one. */
309
+ function calloutOf(quote: MdastNode): MdastNode | undefined {
310
+ const first = quote.children?.[0]
311
+ const lead = first?.type === 'paragraph' ? first.children?.[0] : undefined
312
+ const match = lead?.type === 'text' ? CALLOUT.exec(String(lead.value ?? '')) : null
313
+ if (!first || !lead || !match) return undefined
314
+ const rest = String(lead.value).slice(match[0].length)
315
+ const breakAt = rest.indexOf('\n')
316
+ const titleText = (breakAt < 0 ? rest : rest.slice(0, breakAt)).trim()
317
+ const bodyLead = breakAt < 0 ? '' : rest.slice(breakAt + 1)
318
+ const inlineRest = [...bodyLead ? [{ type: 'text', value: bodyLead }] : [], ...(first.children ?? []).slice(1)]
319
+ const kind = match[1]!.toLowerCase()
320
+ return {
321
+ type: 'admonition', kind,
322
+ children: [
323
+ { type: 'admonitionTitle', children: [{ type: 'text', value: titleText || kind.charAt(0).toUpperCase() + kind.slice(1) }] },
324
+ ...inlineRest.length ? [{ type: 'paragraph', children: inlineRest }] : [],
325
+ ...(quote.children ?? []).slice(1),
326
+ ],
327
+ }
328
+ }
@@ -0,0 +1,77 @@
1
+ import { existsSync, realpathSync } from 'node:fs'
2
+ import { join } from 'node:path'
3
+ import { setTimeout as delay } from 'node:timers/promises'
4
+ import { findWorkspaceRoot, WORKSPACE_CONFIG } from '@lincyaw/compiler'
5
+ import { findWorkspaceServiceState, readServiceState, serveStateDir, tryAcquireServiceHostLease } from '@lincyaw/kernel/node'
6
+ import type { ApprovalKind } from '@lincyaw/kernel'
7
+ import type { ServiceHostLease, ServiceState } from '@lincyaw/kernel/node'
8
+ import { serveWorkspace } from '@lincyaw/workspace'
9
+ import type { WorkspaceServer } from '@lincyaw/workspace'
10
+
11
+ interface WorkspaceTarget { mcp: string, token: string, pid: number }
12
+ export interface McpWorkspaceConnection { target: WorkspaceTarget, close(): Promise<void> }
13
+
14
+ /** One stdio session may own the shared host; every other session borrows its published endpoint. */
15
+ export function mcpWorkspaceSession(bundled: string) {
16
+ let root: Promise<string> | undefined, owned: { server: WorkspaceServer, lease: ServiceHostLease } | undefined
17
+ let closed = false, pending: Promise<McpWorkspaceConnection> | undefined, closing: Promise<void> | undefined
18
+ const closeOwned = async () => {
19
+ const current = owned
20
+ owned = undefined
21
+ await current?.server.close()
22
+ }
23
+ const close = (): Promise<void> => closing ??= Promise.resolve().then(async () => {
24
+ closed = true
25
+ await pending?.catch(() => undefined)
26
+ await closeOwned()
27
+ })
28
+ const target = (state: ServiceState): WorkspaceTarget => ({ mcp: state.mcp, token: state.token, pid: state.pid })
29
+ return {
30
+ startWorkspace(dir: string, allow: readonly ApprovalKind[], signal: AbortSignal): Promise<McpWorkspaceConnection> {
31
+ if (pending) return pending
32
+ const work = async () => {
33
+ signal.throwIfAborted()
34
+ if (closed) throw new Error('mcp-workspace-session-closed')
35
+ if (!root) {
36
+ const existing = findWorkspaceServiceState(dir)
37
+ root = existing ? Promise.resolve(existing.root) : findWorkspaceRoot(dir).then(found => realpathSync(existsSync(join(found, WORKSPACE_CONFIG)) ? found : dir))
38
+ }
39
+ const directory = await root, file = join(serveStateDir(directory), 'server.json')
40
+ const deadline = Date.now() + 30_000
41
+ for (;;) {
42
+ signal.throwIfAborted()
43
+ if (closed) throw new Error('mcp-workspace-session-closed')
44
+ if (owned?.lease.signal.aborted) await closeOwned()
45
+ const state = readServiceState(file)
46
+ if (state) return { target: target(state), close }
47
+ if (Date.now() >= deadline) throw new Error('mcp-workspace-start-timeout')
48
+ const lease = await tryAcquireServiceHostLease(directory)
49
+ if (!lease) { await delay(100, undefined, { signal }); continue }
50
+ // A previous host may have published while this process was waiting for its lease.
51
+ const appeared = readServiceState(file)
52
+ if (appeared) { await lease.release(); return { target: target(appeared), close } }
53
+ let server: WorkspaceServer | undefined
54
+ const startup = AbortSignal.any([signal, AbortSignal.timeout(Math.max(1, deadline - Date.now()))])
55
+ try {
56
+ signal.throwIfAborted()
57
+ server = await serveWorkspace({ dir: directory, bundled, port: 0, listenAddress: '127.0.0.1', allow: [...allow], hostLease: lease, signal: startup })
58
+ startup.throwIfAborted()
59
+ if (closed) throw new Error('mcp-workspace-session-closed')
60
+ const ready = readServiceState(file)
61
+ if (!ready || ready.pid !== process.pid || ready.mcp !== server.mcp.url) throw new Error('mcp-workspace-state-unavailable')
62
+ owned = { server, lease }
63
+ return { target: target(ready), close }
64
+ } catch (error) {
65
+ if (server) await server.close()
66
+ else await lease.release()
67
+ if (!signal.aborted && startup.aborted) throw new Error('mcp-workspace-start-timeout')
68
+ throw error
69
+ }
70
+ }
71
+ }
72
+ pending = work().finally(() => { pending = undefined })
73
+ return pending
74
+ },
75
+ close,
76
+ }
77
+ }