@lincyaw/cli 1.0.0-rc.5 → 1.0.0-rc.51

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,73 @@
1
+ import { join } from 'node:path'
2
+ import { findWorkspaceRoot, operatorDir } from '@lincyaw/compiler'
3
+ import { OperatorSpeechSettings, SpeechSettingsError } from '@lincyaw/kernel/node'
4
+ import type { CliMessages } from './messages.ts'
5
+
6
+ const KEY_VARIABLE = 'PRESMIUM_SPEECH_VOLCENGINE_KEY'
7
+
8
+ export class SpeechKeyFailure extends Error {}
9
+
10
+ /** A key typed at the terminal is not echoed; from a pipe or a file the whole input is the key. */
11
+ async function readKey(prompt: string, cancelled: string): Promise<string> {
12
+ const input = process.stdin
13
+ if (!input.isTTY) {
14
+ const chunks: Buffer[] = []
15
+ for await (const chunk of input) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)))
16
+ return Buffer.concat(chunks).toString('utf8').trim()
17
+ }
18
+ process.stderr.write(prompt)
19
+ input.setRawMode(true)
20
+ input.setEncoding('utf8')
21
+ input.resume()
22
+ return new Promise<string>((resolve, reject) => {
23
+ let value = ''
24
+ const finish = (error?: Error) => {
25
+ input.off('data', typed)
26
+ input.setRawMode(false)
27
+ input.pause()
28
+ process.stderr.write('\n')
29
+ if (error) reject(error)
30
+ else resolve(value.trim())
31
+ }
32
+ const typed = (text: string) => {
33
+ for (const char of text) {
34
+ if (char === '\r' || char === '\n' || char === '\u0004') return finish()
35
+ if (char === '\u0003') return finish(new SpeechKeyFailure(cancelled))
36
+ if (char === '\u007f' || char === '\b') value = value.slice(0, -1)
37
+ else if (char >= ' ') value += char
38
+ }
39
+ }
40
+ input.on('data', typed)
41
+ })
42
+ }
43
+
44
+ /** `presmium speech key set|clear|status [<workspace>]`, on the file the Studio's Settings → Voice Service writes. */
45
+ export async function runSpeechKey(action: 'set' | 'clear' | 'status', dir: string, t: CliMessages, env: NodeJS.ProcessEnv = process.env): Promise<number> {
46
+ const root = await findWorkspaceRoot(dir)
47
+ const operator = operatorDir(root, env.PRESMIUM_OPERATOR_DIR)
48
+ const file = join(operator, 'speech', 'credentials.json')
49
+ const settings = new OperatorSpeechSettings(operator, name => env[name])
50
+ const failure = (error: unknown) => error instanceof SpeechSettingsError ? new SpeechKeyFailure(t.speechKeyErrors[error.code](file)) : error
51
+ try {
52
+ process.stdout.write(`${t.speechKeyLabels.workspace} ${root}\n`)
53
+ if (action === 'status') {
54
+ const state = settings.read()
55
+ process.stdout.write(`${t.speechKeyLabels.key} ${state.source === 'saved' ? t.speechKeySaved(state.appIdConfigured === true) : state.source === 'environment' ? t.speechKeyEnvironment(KEY_VARIABLE) : t.speechKeyNone(KEY_VARIABLE)}\n`)
56
+ if (state.source === 'saved') process.stdout.write(`${t.speechKeyLabels.file} ${file}\n`)
57
+ return 0
58
+ }
59
+ if (action === 'set') {
60
+ const key = await readKey(t.speechKeyPrompt, t.speechKeyCancelled)
61
+ if (!key) throw new SpeechKeyFailure(t.speechKeyEmpty)
62
+ const saved = await settings.change({ action: 'save', revision: settings.read().revision, apiKey: key })
63
+ if (!saved.stored) throw new SpeechKeyFailure(t.speechKeyErrors['speech-settings-unavailable'](file))
64
+ process.stdout.write(`${t.speechKeyStored(file)}\n`)
65
+ return 0
66
+ }
67
+ const cleared = await settings.change({ action: 'clear', revision: settings.read().revision })
68
+ process.stdout.write(`${cleared.source === 'environment' ? t.speechKeyClearedEnvironment(KEY_VARIABLE) : t.speechKeyCleared}\n`)
69
+ return 0
70
+ } catch (error) {
71
+ throw failure(error)
72
+ }
73
+ }
@@ -0,0 +1,241 @@
1
+ import { randomBytes } from 'node:crypto'
2
+ import { relative } from 'node:path'
3
+ import { changeDocumentVoice, errorMessage, SPEECH, speechEngineId, speechFailureCode, VOICEOVER_EXECUTION } from '@lincyaw/kernel'
4
+ import type { SpeechCachePrune, SpeechEngineInfo, SpeechService, SpeechVoice, TeachingDocument, VoiceoverExecution, VoiceoverRunResult, VoiceoverSentence, VoiceoverSentences, VoiceScope } from '@lincyaw/kernel'
5
+ import { Compiler } from '@lincyaw/compiler'
6
+ import type { Compilation } from '@lincyaw/compiler'
7
+ import { readDocumentFile, saveDocumentFile } from './document-file.ts'
8
+ import type { CliMessages } from './messages.ts'
9
+
10
+ export interface VoiceoverOptions {
11
+ entry: string
12
+ /** Make this the document's default voice first. */
13
+ voice?: SpeechVoice
14
+ /** Consent to the paid generation and to the changes; without it the command only reports. */
15
+ yes: boolean
16
+ prune: boolean
17
+ json: boolean
18
+ bundled: string
19
+ }
20
+
21
+ /** A refusal or failure the author can act on: exit code 1, unlike a usage or internal error. */
22
+ export class VoiceoverFailure extends Error {}
23
+
24
+ /** Sentences that are not generated by design: their step is silent or uses a recording. */
25
+ const BY_DESIGN = new Set(['voice-none', 'recording-unavailable'])
26
+
27
+ interface Tally {
28
+ total: number
29
+ cached: number
30
+ missing: VoiceoverSentence[]
31
+ skipped: number
32
+ blocked: VoiceoverSentence[]
33
+ characters: number
34
+ }
35
+
36
+ function tally(sentences: VoiceoverSentence[]): Tally {
37
+ const missing = sentences.filter(sentence => !sentence.cached && !sentence.reason)
38
+ return {
39
+ total: sentences.length,
40
+ cached: sentences.filter(sentence => sentence.cached).length,
41
+ missing,
42
+ skipped: sentences.filter(sentence => sentence.reason && BY_DESIGN.has(sentence.reason)).length,
43
+ blocked: sentences.filter(sentence => !sentence.cached && sentence.reason && !BY_DESIGN.has(sentence.reason)),
44
+ characters: missing.reduce((sum, sentence) => sum + [...sentence.text].length, 0),
45
+ }
46
+ }
47
+
48
+ export function voiceLabel(voice: SpeechVoice): string {
49
+ return `${voice.engine ? `${voice.engine}:` : ''}${voice.voice}${voice.rate !== undefined && voice.rate !== 1 ? ` ×${voice.rate}` : ''}${voice.style ? ` (${voice.style})` : ''}`
50
+ }
51
+
52
+ const sameVoice = (a: SpeechVoice, b: SpeechVoice) => a.voice === b.voice && speechEngineId(a.engine ?? '') === speechEngineId(b.engine ?? '')
53
+
54
+ /** The document's default voice, or why it has none. */
55
+ function defaultVoice(document: TeachingDocument): SpeechVoice | 'none' | undefined {
56
+ const source = document.production.defaults.voiceSource
57
+ return source?.type === 'tts' ? source.voice : source?.type === 'none' ? 'none' : undefined
58
+ }
59
+
60
+ function services(compilation: Compilation, t: CliMessages): { execution: VoiceoverExecution & Required<Pick<VoiceoverExecution, 'sentences'>>, speech?: SpeechService } {
61
+ const execution = compilation.service(VOICEOVER_EXECUTION)
62
+ if (!execution?.sentences) throw new VoiceoverFailure(t.voiceoverUnavailable)
63
+ const speech = compilation.service(SPEECH)
64
+ return { execution: execution as VoiceoverExecution & Required<Pick<VoiceoverExecution, 'sentences'>>, ...speech ? { speech } : {} }
65
+ }
66
+
67
+ /** Where a sentence is, as the author numbers pages and steps. */
68
+ function place(compilation: Compilation, sentence: VoiceoverSentence, t: CliMessages): string {
69
+ const index = compilation.doc.sections.findIndex(section => section.id === sentence.section)
70
+ return t.voiceoverPlace(index + 1, sentence.step + 1)
71
+ }
72
+
73
+ function reasonText(reason: string, t: CliMessages): string {
74
+ const code = speechFailureCode(reason) ?? reason
75
+ return t.voiceoverReasons[code] ?? t.voiceoverReasonOther(reason.length > 80 ? `${reason.slice(0, 80)}…` : reason)
76
+ }
77
+
78
+ const megabytes = (bytes: number) => (bytes / 1048576).toFixed(1)
79
+
80
+ interface Engines { list: SpeechEngineInfo[], fallback?: string }
81
+
82
+ /** The voice services the sentences use, with whether each is configured and runs on this machine. */
83
+ function usedServices(sentences: VoiceoverSentence[], engines: Engines): { id: string, info?: SpeechEngineInfo }[] {
84
+ const ids = [...new Set(sentences.flatMap(sentence => sentence.request ? [speechEngineId(sentence.request.engine ?? engines.fallback ?? '')] : []))].filter(Boolean)
85
+ return ids.map(id => ({ id, ...engines.list.find(engine => engine.id === id) ? { info: engines.list.find(engine => engine.id === id)! } : {} }))
86
+ }
87
+
88
+ function voicesOf(sentences: VoiceoverSentence[], engines: Engines): string[] {
89
+ return [...new Set(sentences.flatMap(sentence => sentence.request ? [voiceLabel({ ...sentence.request, engine: sentence.request.engine ?? engines.fallback })] : []))]
90
+ }
91
+
92
+ /** On a terminal one line that updates; elsewhere a line at the start, at most every five seconds, and at the end. */
93
+ class Progress {
94
+ readonly #tty = Boolean(process.stderr.isTTY)
95
+ #last = ''
96
+ #at = 0
97
+ show(text: string, final = false): void {
98
+ if (text === this.#last) return
99
+ if (!this.#tty && this.#last && !final && Date.now() - this.#at < 5000) return
100
+ this.#last = text
101
+ this.#at = Date.now()
102
+ process.stderr.write(this.#tty ? `\r\x1b[2K${text}` : `${text}\n`)
103
+ }
104
+ end(): void {
105
+ if (this.#tty && this.#last) process.stderr.write('\n')
106
+ this.#last = ''
107
+ }
108
+ }
109
+
110
+ /**
111
+ * `presmium voiceover`: what generating the document's voiceover would do, and with consent doing it in this process
112
+ * through the plugins' voiceover execution, the one the workspace service runs for Presmium Studio.
113
+ */
114
+ export async function runVoiceover(options: VoiceoverOptions, t: CliMessages): Promise<number> {
115
+ const controller = new AbortController()
116
+ const interrupt = () => controller.abort()
117
+ process.once('SIGINT', interrupt)
118
+ try {
119
+ return await voiceover(options, t, controller.signal)
120
+ } finally {
121
+ process.off('SIGINT', interrupt)
122
+ }
123
+ }
124
+
125
+ async function voiceover(options: VoiceoverOptions, t: CliMessages, signal: AbortSignal): Promise<number> {
126
+ const say = (line: string) => { if (!options.json) process.stdout.write(`${line}\n`) }
127
+ const file = readDocumentFile(options.entry)
128
+ const compiler = new Compiler(options.entry, { bundled: options.bundled })
129
+ let compilation = await compiler.compile({ signal })
130
+ let { execution, speech } = services(compilation, t)
131
+ const engines: Engines = { list: await speech?.engines().catch(() => []) ?? [] }
132
+ const fallback = await speech?.defaultSynthesisEngine?.().catch(() => undefined)
133
+ if (fallback) engines.fallback = fallback
134
+
135
+ const before = defaultVoice(file.document)
136
+ const changesVoice = options.voice !== undefined && !(typeof before === 'object' && sameVoice(before, options.voice))
137
+ const planned = changesVoice ? changeDocumentVoice(file.document, { kind: 'document' }, { type: 'tts', voice: options.voice! }) : file.document
138
+ let listing: VoiceoverSentences = await execution.sentences(changesVoice ? { defaultVoice: options.voice! } : {}, signal)
139
+ let counts = tally(listing.sentences)
140
+
141
+ const json: Record<string, unknown> = { document: compilation.deckDir }
142
+ say(`${t.voiceoverLabels.document} ${relative(process.cwd(), compilation.deckDir) || '.'}`)
143
+ const now = defaultVoice(planned)
144
+ const shown = typeof now === 'object' ? voiceLabel(now) : now === 'none' ? t.voiceoverNoVoice : t.voiceoverUnset
145
+ say(`${t.voiceoverLabels.voice} ${changesVoice ? t.voiceoverVoiceChange(shown, typeof before === 'object' ? voiceLabel(before) : before === 'none' ? t.voiceoverNoVoice : t.voiceoverUnset) : t.voiceoverVoiceDefault(shown)}`)
146
+ json.voice = { default: typeof now === 'object' ? now : null, changed: changesVoice }
147
+ const used = usedServices(counts.missing.length ? counts.missing : listing.sentences, engines)
148
+ for (const { id, info } of used) say(`${t.voiceoverLabels.service} ${info ? t.voiceoverService(id, info.provider, info.local) : t.voiceoverServiceMissing(id)}`)
149
+ json.services = used.map(({ id, info }) => ({ id, configured: Boolean(info), ...info ? { provider: info.provider, local: info.local } : {} }))
150
+ say(`${t.voiceoverLabels.sentences} ${t.voiceoverCounts(counts.total, counts.cached, counts.missing.length, counts.skipped, counts.blocked.length)}`)
151
+ const sentencesJson = (value: Tally) => ({ total: value.total, cached: value.cached, missing: value.missing.length, characters: value.characters, skipped: value.skipped, blocked: value.blocked.map(sentence => ({ section: sentence.section, step: sentence.step, ...sentence.stepId ? { stepId: sentence.stepId } : {}, reason: sentence.reason })) })
152
+ json.sentences = sentencesJson(counts)
153
+ const cloud = used.filter(({ info }) => info && !info.local).map(({ info }) => info!.provider)
154
+ if (counts.missing.length) {
155
+ say(`${t.voiceoverLabels.missing} ${t.voiceoverMissing(counts.missing.length, counts.characters, voicesOf(counts.missing, engines))}`)
156
+ say(cloud.length ? t.voiceoverCharges([...new Set(cloud)]) : t.voiceoverLocal)
157
+ }
158
+ const reasons = new Map<string, VoiceoverSentence[]>()
159
+ for (const sentence of counts.blocked) reasons.set(sentence.reason!, [...reasons.get(sentence.reason!) ?? [], sentence])
160
+ for (const [reason, group] of reasons) say(`${t.voiceoverLabels.blocked} ${t.voiceoverBlocked(group.length, reasonText(reason, t), group.slice(0, 3).map(sentence => place(compilation, sentence, t)), group.length > 3)}`)
161
+
162
+ let prune: SpeechCachePrune | undefined
163
+ const pruneCache = async (value: VoiceoverSentences, remove: boolean) => {
164
+ if (compilation.doc.diagnostics.some(finding => finding.severity === 'error')) throw new VoiceoverFailure(t.voiceoverPruneErrors)
165
+ if (!speech?.pruneCache) throw new VoiceoverFailure(t.voiceoverPruneUnavailable)
166
+ try {
167
+ return await speech.pruneCache(value.sentences.flatMap(sentence => sentence.request ? [sentence.request] : []), { remove, signal })
168
+ } catch (error) {
169
+ if (errorMessage(error) === 'speech-prune-engine-unknown') throw new VoiceoverFailure(t.voiceoverPruneEngineUnknown)
170
+ throw error
171
+ }
172
+ }
173
+ if (options.prune) {
174
+ prune = await pruneCache(listing, false)
175
+ const bytes = prune.unused.reduce((sum, entry) => sum + entry.bytes, 0)
176
+ say(`${t.voiceoverLabels.prune} ${t.voiceoverPruneWould(prune.unused.length, megabytes(bytes), prune.kept)}`)
177
+ json.prune = { unused: prune.unused.length, bytes, kept: prune.kept, removed: false }
178
+ }
179
+
180
+ const work = counts.missing.length > 0 || changesVoice || Boolean(prune?.unused.length)
181
+ if (!options.yes) {
182
+ say(work ? t.voiceoverDryRun : counts.blocked.length ? t.voiceoverNothingElse : t.voiceoverNothing)
183
+ if (options.json) process.stdout.write(`${JSON.stringify({ ...json, yes: false }, null, 2)}\n`)
184
+ return 0
185
+ }
186
+
187
+ if (changesVoice) {
188
+ const refused = counts.blocked.find(sentence => sentence.request && sameVoice(sentence.request, options.voice!))
189
+ if (refused) throw new VoiceoverFailure(t.voiceoverVoiceRefused(voiceLabel(options.voice!), reasonText(refused.reason!, t)))
190
+ saveDocumentFile(file, planned)
191
+ say(t.voiceoverVoiceSaved(voiceLabel(options.voice!)))
192
+ compilation = await compiler.compile({ signal })
193
+ ;({ execution, speech } = services(compilation, t))
194
+ listing = await execution.sentences({}, signal)
195
+ counts = tally(listing.sentences)
196
+ }
197
+
198
+ let result: VoiceoverRunResult | undefined
199
+ let after = counts
200
+ if (counts.missing.length) {
201
+ const intent = randomBytes(18).toString('base64url')
202
+ // By step when every missing sentence has one, so that only the steps with missing audio are gone through.
203
+ const targets = [...new Map(counts.missing.flatMap(sentence => sentence.target ? [[JSON.stringify(sentence.target), sentence.target] as const] : [])).values()]
204
+ const scope: VoiceScope = counts.missing.every(sentence => sentence.target) ? { kind: 'steps', targets } : { kind: 'document' }
205
+ const prepared = await execution.prepare({ intent, source: listing.source, revision: listing.revision, scope }, signal)
206
+ const progress = new Progress()
207
+ try {
208
+ progress.show(t.voiceoverGenerating(0, prepared.total))
209
+ result = await prepared.run(signal, value => progress.show(t.voiceoverGenerating(value.completed + value.failed, prepared.total), value.completed + value.failed === prepared.total))
210
+ } finally {
211
+ progress.end()
212
+ prepared.dispose()
213
+ }
214
+ // Read the cache again, also after a cancel, to report what was really made; a changed document can't be read.
215
+ if (result.state !== 'stale') {
216
+ try {
217
+ listing = await execution.sentences({}, signal.aborted ? new AbortController().signal : signal)
218
+ after = tally(listing.sentences)
219
+ } catch (error) {
220
+ if (!signal.aborted) throw error
221
+ }
222
+ }
223
+ const generated = Math.max(0, after.cached - counts.cached)
224
+ say(result.state === 'cancelled' ? t.voiceoverCancelled(generated) : result.state === 'stale' ? t.voiceoverStale(generated) : t.voiceoverGenerated(generated))
225
+ if (result.error && result.state !== 'cancelled') say(t.voiceoverRunError(reasonText(result.error, t)))
226
+ json.generation = { state: result.state, generated, ...result.error ? { error: result.error } : {} }
227
+ }
228
+
229
+ if (options.prune && !signal.aborted && result?.state !== 'stale') {
230
+ prune = await pruneCache(listing, true)
231
+ const bytes = prune.unused.reduce((sum, entry) => sum + entry.bytes, 0)
232
+ say(t.voiceoverPruned(prune.unused.length, megabytes(bytes)))
233
+ json.prune = { unused: prune.unused.length, bytes, kept: prune.kept, removed: true }
234
+ }
235
+
236
+ const left = after.missing.length + after.blocked.length
237
+ if (left) say(t.voiceoverLeft(after.missing.length, after.blocked.length))
238
+ json.remaining = sentencesJson(after)
239
+ if (options.json) process.stdout.write(`${JSON.stringify({ ...json, yes: true }, null, 2)}\n`)
240
+ return left || (result && result.state !== 'done' && result.state !== 'failed') ? 1 : 0
241
+ }