@lincyaw/addon-exec-jupyter 0.0.0-stage → 1.0.0-rc.2

package/src/client/jupyter-client.ts

@@ -0,0 +1,273 @@
+import { environmentExecutor, errorMessage, failedRun, isRecord } from '@lincyaw/kernel'
+import type { EnvironmentSpec, Executor, RunResult } from '@lincyaw/kernel'
+import { currentLocale, pluginRoutePath, serverClient } from '@lincyaw/host'
+import type { ServerConnection } from '@jupyterlab/services'
+import { authOf, baseUrl, cleanupPath, EXEC_JUPYTER_ID, jupyterKernelName, languagesOf, originOf, preparePath, proxyPath } from '../domain/index.ts'
+import type { JupyterTerminals, TerminalSession } from '../domain/index.ts'
+import { createJupyterKernels } from '../shared/kernels.ts'
+import type { JupyterKernels } from '../shared/kernels.ts'
+import { loadJupyterServices } from '../shared/load-services.ts'
+import { isRefused } from '../shared/refusal.ts'
+import { openTerminal } from '../shared/terminals.ts'
+import { failureText, messages } from './messages.ts'
+import { forgetJupyterToken, jupyterTokenFor } from './jupyter-token.ts'
+
+/** The browser's side of the deck's Jupyter environments: an executor for each, and their terminals. */
+export interface JupyterClient {
+  terminals: JupyterTerminals
+  executors: Executor[]
+  dispose(): Promise<void>
+}
+
+let documentName: Promise<string> | undefined
+function servedDocument(): Promise<string> {
+  documentName ??= serverClient().fetch('presmium.server', 'hello')
+    .then(response => (response.ok ? response.json() : {}))
+    .then((hello: unknown) => (isRecord(hello) && typeof hello.document === 'string' ? hello.document : ''))
+    .catch(() => '')
+  return documentName
+}
+
+async function hubUser(url: string, accessToken: string): Promise<string> {
+  const origin = originOf(url.replace('{user}', 'x'))!
+  const response = await fetch(`${origin}/hub/api/user`, { headers: { Authorization: `token ${accessToken}` } })
+  if (!response.ok) throw Object.assign(new Error(`${origin}/hub/api/user: ${response.status}`), { response })
+  const user: unknown = await response.json()
+  if (!isRecord(user) || typeof user.name !== 'string') throw new Error(`${origin}/hub/api/user: no name`)
+  return encodeURIComponent(user.name)
+}
+
+const IMAGES = ['image/png', 'image/jpeg', 'image/gif']
+const BASE64 = /^[A-Za-z0-9+/=\s]*$/
+const badImage = (data: Record<string, unknown>) => IMAGES.some(type => data[type] !== undefined && (typeof data[type] !== 'string' || !BASE64.test(data[type])))
+
+async function sanitized(result: RunResult): Promise<RunResult> {
+  if (!result.outputs?.some(output => 'data' in output && (typeof output.data['text/html'] === 'string' || typeof output.data['image/svg+xml'] === 'string' || badImage(output.data)))) return result
+  const { default: DOMPurify } = await import('dompurify')
+  return {
+    ...result,
+    outputs: result.outputs.map((output) => {
+      if (!('data' in output)) return output
+      const data = { ...output.data }
+      if (typeof data['text/html'] === 'string') data['text/html'] = DOMPurify.sanitize(data['text/html'])
+      if (typeof data['image/svg+xml'] === 'string') data['image/svg+xml'] = DOMPurify.sanitize(data['image/svg+xml'], { USE_PROFILES: { svg: true, svgFilters: true } })
+      for (const type of IMAGES) {
+        if (data[type] !== undefined && (typeof data[type] !== 'string' || !BASE64.test(data[type]))) delete data[type]
+      }
+      return { ...output, data }
+    }),
+  }
+}
+
+export function createJupyterClient(environments: Record<string, EnvironmentSpec>): JupyterClient {
+  const settings = new Map<string, Promise<ServerConnection.ISettings>>()
+  const proxyDocuments = new Map<string, string>()
+  const generations = new Map<string, string>()
+  let disposing: Promise<void> | undefined
+
+  const unavailable = (name: string): string | undefined => {
+    const t = messages()
+    const spec = environments[name]
+    if (!spec) return t.unknown(name)
+    const auth = authOf(spec)
+    if (auth === 'env') return t.envOnly(name)
+    if (auth === 'proxy' || auth === 'hub') return serverClient().available ? undefined : t.proxyStatic(name)
+    return originOf(typeof spec.url === 'string' ? spec.url.replace('{user}', 'x') : undefined) ? undefined : t.noUrl(name)
+  }
+
+  const connect = async (name: string): Promise<ServerConnection.ISettings> => {
+    const reason = unavailable(name)
+    if (reason) throw new Error(reason)
+    const spec = environments[name]!
+    const { ServerConnection } = await loadJupyterServices()
+    if (['proxy', 'hub'].includes(authOf(spec))) {
+      const document = await servedDocument()
+      proxyDocuments.set(name, document)
+      if (authOf(spec) === 'hub') {
+        let response: Response
+        try {
+          response = await serverClient().fetch(EXEC_JUPYTER_ID, preparePath(name), { method: 'POST' })
+        } catch {
+          throw Object.assign(new Error(messages().reasons['hub-unavailable']), { code: 'hub-unavailable' })
+        }
+        const answer: unknown = await response.json().catch(() => undefined)
+        if (!response.ok) {
+          const code = isRecord(answer) && typeof answer.error === 'string' ? answer.error : 'hub-unavailable'
+          throw Object.assign(new Error(messages().reasons[code] ?? messages().reasons['hub-unavailable']), { code })
+        }
+        generations.set(name, isRecord(answer) && typeof answer.generation === 'string' ? answer.generation : '')
+      }
+      const base = `${location.origin}${pluginRoutePath(serverClient(), EXEC_JUPYTER_ID)}${proxyPath(name)}/`
+      class DocumentSocket extends WebSocket {
+        constructor(url: string | URL, protocols?: string | string[]) {
+          const target = new URL(url)
+          target.searchParams.set('document', document)
+          super(target, protocols)
+        }
+      }
+      return ServerConnection.makeSettings({
+        baseUrl: base,
+        wsUrl: base.replace(/^http/, 'ws'),
+        token: '',
+        appendToken: false,
+        WebSocket: DocumentSocket,
+        fetch: (input: RequestInfo | URL, init?: RequestInit) => {
+          const request = new Request(input, init)
+          request.headers.set('Presmium-Document', encodeURIComponent(document))
+          if (!request.headers.has('Accept-Language')) request.headers.set('Accept-Language', currentLocale())
+          return fetch(request)
+        },
+      })
+    }
+    const url = String(spec.url)
+    if (authOf(spec) === 'none') return ServerConnection.makeSettings({ baseUrl: baseUrl(url), token: '' })
+    const accessToken = await jupyterTokenFor(name, originOf(url.replace('{user}', 'x'))!)
+    if (!accessToken) throw new Error(messages().noToken(name))
+    let resolved: string
+    try {
+      resolved = url.includes('{user}') ? url.replace('{user}', await hubUser(url, accessToken)) : url
+    } catch (error) {
+      forget(name)
+      throw error
+    }
+    return ServerConnection.makeSettings({
+      baseUrl: baseUrl(resolved), token: accessToken, appendToken: true,
+      fetch: (input: RequestInfo | URL, init?: RequestInit) => fetch(input, init).catch((error: unknown) => {
+        // Jupyter may omit CORS headers on auth failures, hiding the HTTP status.
+        // Let the next attempt ask again instead of retaining an unusable token.
+        forget(name)
+        throw error
+      }),
+    })
+  }
+
+  const settingsFor = (name: string) => {
+    let known = settings.get(name)
+    if (!known) {
+      known = connect(name)
+      settings.set(name, known)
+      known.catch(() => settings.delete(name))
+    }
+    return known
+  }
+
+  const forget = (name: string) => {
+    settings.delete(name)
+    forgetJupyterToken(name)
+  }
+
+  const terminals = new Set<TerminalSession>()
+  const kernelPools: JupyterKernels[] = []
+  const executors = Object.entries(environments).map(([name, spec]): Executor => {
+    const makeKernels = () => createJupyterKernels({
+      executorId: environmentExecutor(name),
+      kernelName: jupyterKernelName(spec),
+      languages: languagesOf(spec),
+      settings: () => settingsFor(name),
+      ...(['proxy', 'hub'].includes(authOf(spec)) ? {
+        shutdown: (kernel: string, directory: string) => {
+          const request = fetch(`${pluginRoutePath(serverClient(), EXEC_JUPYTER_ID)}${cleanupPath(name)}`, {
+            method: 'POST',
+            keepalive: true,
+            headers: { 'Content-Type': 'application/json', 'Presmium-Document': encodeURIComponent(proxyDocuments.get(name) ?? '') },
+            body: JSON.stringify({ kernel, directory }),
+          })
+          return request.then(async response => {
+            if (!response.ok) throw new Error(`Jupyter cleanup failed (${response.status}): ${await response.text()}`)
+          })
+        },
+      } : {}),
+      refused: () => forget(name),
+      text: {
+        unreachable: (error, code) => messages().unreachable(name, failureText(error, code)),
+        get refused() {
+          return messages().refused(name)
+        },
+        noKernel: (kernel, known) => messages().noKernel(name, kernel, known),
+        wrongLanguage: (kernel, language, lang) => messages().wrongLanguage(name, kernel, language, lang),
+        timedOut: seconds => messages().timedOut(seconds),
+      },
+    })
+    let kernels = makeKernels()
+    let generation: string | undefined
+    let preparing: Promise<void> | undefined
+    kernelPools.push(kernels)
+    return {
+      id: environmentExecutor(name),
+      supports: lang => kernels.supports(lang),
+      run: async (request, signal) => {
+        if (disposing || signal?.aborted) return failedRun(environmentExecutor(name), messages().cancelled)
+        if (authOf(spec) === 'hub') {
+          try {
+            if (!preparing) {
+              settings.delete(name)
+              preparing = settingsFor(name).then(async () => {
+                if (disposing) return
+                const next = generations.get(name)
+                if (generation !== undefined && generation !== next) {
+                  await kernels.dispose().catch(() => {})
+                  if (disposing) return
+                  kernels = makeKernels()
+                  kernelPools.push(kernels)
+                }
+                generation = next
+              }).finally(() => { preparing = undefined })
+            }
+            await preparing
+          } catch (error) {
+            return failedRun(environmentExecutor(name), errorMessage(error))
+          }
+        }
+        if (disposing || signal?.aborted) return failedRun(environmentExecutor(name), messages().cancelled)
+        return sanitized(await kernels.run(request, signal))
+      },
+      endSession: session => kernels.endSession(session),
+    }
+  })
+
+  const dispose = (): Promise<void> => {
+    if (disposing) return disposing
+    window.removeEventListener('pagehide', leave)
+    // These calls must run before the first await, independently of host disposal order.
+    const cleanup = kernelPools.map(kernels => kernels.dispose())
+    terminals.forEach(session => session.abandon())
+    terminals.clear()
+    settings.clear()
+    disposing = Promise.all(cleanup).then(() => undefined)
+    return disposing
+  }
+  const leave = () => void dispose().catch(error => console.error('[presmium] Jupyter cleanup failed', error))
+  window.addEventListener('pagehide', leave)
+
+  return {
+    executors,
+    terminals: {
+      unavailable,
+      async openTerminal(name, events) {
+        if (disposing) throw new Error(messages().cancelled)
+        if (authOf(environments[name] ?? { kind: 'jupyter' }) === 'hub') settings.delete(name)
+        const connection = await settingsFor(name)
+        if (disposing) throw new Error(messages().cancelled)
+        try {
+          const session = await openTerminal(connection, events)
+          if (disposing) { await session.close(); throw new Error(messages().cancelled) }
+          terminals.add(session)
+          return {
+            ...session,
+            close: () => {
+              terminals.delete(session)
+              return session.close()
+            },
+          }
+        } catch (error) {
+          if (isRefused(error)) {
+            forget(name)
+            throw new Error(messages().refused(name))
+          }
+          throw error
+        }
+      },
+    },
+    dispose,
+  }
+}

package/src/client/jupyter-token.ts

@@ -0,0 +1,87 @@
+import { messages } from './messages.ts'
+
+const key = (name: string) => `presmium.execJupyter.token:${name}`
+
+function storage(): Storage | undefined {
+  try {
+    return typeof sessionStorage === 'undefined' ? undefined : sessionStorage
+  } catch {
+    return undefined
+  }
+}
+
+function storedJupyterToken(name: string): string | undefined {
+  return storage()?.getItem(key(name)) ?? undefined
+}
+
+export function forgetJupyterToken(name: string): void {
+  storage()?.removeItem(key(name))
+}
+
+const asking = new Map<string, Promise<string | undefined>>()
+
+/** The Jupyter token of the environment: the one this tab stored, or else the one the person enters. */
+export function jupyterTokenFor(name: string, origin: string): Promise<string | undefined> {
+  const stored = storedJupyterToken(name)
+  if (stored) return Promise.resolve(stored)
+  let pending = asking.get(name)
+  if (!pending) {
+    pending = ask(name, origin).then((token) => {
+      if (token) storage()?.setItem(key(name), token)
+      return token
+    }).finally(() => asking.delete(name))
+    asking.set(name, pending)
+  }
+  return pending
+}
+
+function element<K extends keyof HTMLElementTagNameMap>(tag: K, className: string, text?: string): HTMLElementTagNameMap[K] {
+  const node = document.createElement(tag)
+  if (className) node.className = className
+  if (text !== undefined) node.textContent = text
+  return node
+}
+
+function ask(name: string, origin: string): Promise<string | undefined> {
+  const t = messages()
+  const dialog = element('dialog', 'pm-jupyter-token pm-ui')
+  dialog.setAttribute('aria-labelledby', 'pm-jupyter-token-title')
+  const header = element('div', 'pm-ui-dialog__header')
+  const title = element('h2', 'pm-ui-dialog__title', t.tokenTitle(name))
+  title.id = 'pm-jupyter-token-title'
+  header.append(title)
+  const form = element('form', 'pm-ui-dialog__body')
+  form.method = 'dialog'
+  const help = element('p', '', t.tokenHelp(origin))
+  const label = element('label', 'pm-ui-field')
+  const input = element('input', 'pm-ui-input')
+  input.type = 'password'
+  input.name = 'token'
+  input.autocomplete = 'off'
+  input.required = true
+  label.append(element('span', 'pm-ui-field__label', t.tokenLabel), input)
+  const buttons = element('div', '')
+  const cancel = element('button', 'pm-ui-button', t.tokenCancel)
+  cancel.type = 'button'
+  const connect = element('button', 'pm-ui-button pm-ui-button--primary', t.tokenConnect)
+  connect.type = 'submit'
+  connect.value = 'connect'
+  buttons.append(cancel, connect)
+  form.append(help, label, buttons)
+  dialog.append(header, form)
+  Object.assign(dialog.style, { width: 'min(28rem, calc(100vw - 2rem))', padding: '0', border: '1px solid var(--pm-color-line)', borderRadius: 'var(--pm-radius-panel)', background: 'var(--pm-color-surface)', boxShadow: 'var(--pm-shadow-float)' })
+  Object.assign(form.style, { display: 'grid', gap: 'var(--pm-space-3)' })
+  help.style.margin = '0'
+  Object.assign(buttons.style, { display: 'flex', gap: 'var(--pm-space-2)', justifyContent: 'flex-end' })
+  document.body.append(dialog)
+  return new Promise((resolve) => {
+    cancel.addEventListener('click', () => dialog.close(''))
+    dialog.addEventListener('close', () => {
+      const token = dialog.returnValue === 'connect' ? input.value.trim() : ''
+      dialog.remove()
+      resolve(token || undefined)
+    }, { once: true })
+    dialog.showModal()
+    input.focus()
+  })
+}

package/src/client/messages.ts

@@ -0,0 +1,90 @@
+import { currentLocale } from '@lincyaw/host'
+import type { Catalog } from '@lincyaw/host'
+
+const zhCN = {
+  unknown: (name: string) => `文稿没有声明 kind: jupyter 的环境 ${name}`,
+  envOnly: (name: string) => `环境 ${name} 的凭据方式是 env，只在导出时可用`,
+  cancelled: '已取消运行环境连接',
+  proxyStatic: (name: string) => `环境 ${name} 经 Presmium 服务端的代理连接，静态页面中不可用`,
+  noUrl: (name: string) => `环境 ${name} 没有可用的地址 url`,
+  noToken: (name: string) => `没有输入环境 ${name} 的访问令牌`,
+  refused: (name: string) => `环境 ${name} 拒绝了访问令牌。请重新运行并输入访问令牌。`,
+  unreachable: (name: string, reason: string) => `无法连接环境 ${name}。${reason}`,
+  reasons: {
+    'jupyter-no-answer': 'Jupyter 服务在 10 秒内没有响应，请稍后重新运行。',
+    'jupyter-closed': '与 Jupyter 服务的连接已断开，请重新运行。',
+    network: '无法连接 Jupyter 服务，请检查网络与服务地址后重新运行。',
+    'hub-not-configured': '此服务尚未配置 JupyterHub 环境。请联系运营者配置后重试。',
+    'hub-profile-unavailable': '此环境规格不可用。请在文稿中选择运营者提供的 profile 后重试。',
+    'hub-start-failed': '运行环境启动失败。请稍后重试，或联系运营者查看启动诊断。',
+    'hub-start-timeout': '运行环境未能及时启动。请稍后重新运行。',
+    'hub-unavailable': '暂时无法连接 JupyterHub。请稍后重新运行。',
+    'hub-profile-changed': '环境配置已变化，请重新打开当前版本的预览后运行。',
+  } as Record<string, string>,
+  noKernel: (name: string, kernel: string, known: string[]) => `环境 ${name} 中没有 ${kernel}（可用：${known.join('、') || '无'}）`,
+  wrongLanguage: (name: string, kernel: string, language: string, lang: string) => `环境 ${name} 中的 ${kernel} 运行 ${language}，不是 ${lang}`,
+  timedOut: (seconds: number) => `运行超过 ${seconds} 秒，已中断`,
+  tokenTitle: (name: string) => `环境 ${name} 的访问令牌`,
+  tokenHelp: (origin: string) => `粘贴你的 Jupyter 服务器的访问令牌。它只保存在本页的会话存储中（关闭标签页即清除），只发往 ${origin}。`,
+  tokenLabel: '访问令牌',
+  tokenConnect: '连接',
+  tokenCancel: '取消',
+  terminal: (name: string) => `环境 ${name} 的终端`,
+  terminalOpen: '打开终端',
+  terminalConnecting: '正在连接…',
+  terminalClosed: '终端已结束',
+  terminalReconnect: '重新打开',
+  terminalFailed: (reason: string) => `无法连接终端。${reason}`,
+}
+
+export type JupyterMessages = typeof zhCN
+
+const en: JupyterMessages = {
+  unknown: name => `The document declares no kind: jupyter environment ${name}`,
+  envOnly: name => `Environment ${name} authenticates with env, which works only when exporting`,
+  cancelled: 'The execution environment connection was canceled',
+  proxyStatic: name => `Environment ${name} connects through the Presmium server’s proxy, which a static page does not have`,
+  noUrl: name => `Environment ${name} has no usable url`,
+  noToken: name => `No access token was given for environment ${name}`,
+  refused: name => `Environment ${name} refused the access token. Run again and enter it.`,
+  unreachable: (name, reason) => `Couldn’t reach environment ${name}. ${reason}`,
+  reasons: {
+    'jupyter-no-answer': 'The Jupyter service didn’t answer within 10 seconds. Run again shortly.',
+    'jupyter-closed': 'The connection to the Jupyter service closed. Run again.',
+    network: 'Couldn’t reach the Jupyter service. Check the network and the service address, then run again.',
+    'hub-not-configured': 'JupyterHub environments are not configured on this service. Contact the operator, then try again.',
+    'hub-profile-unavailable': 'This environment profile is unavailable. Choose an operator-provided profile in the document, then try again.',
+    'hub-start-failed': 'The execution environment failed to start. Try again shortly, or ask the operator to check its startup diagnostics.',
+    'hub-start-timeout': 'The execution environment did not start in time. Run again shortly.',
+    'hub-unavailable': 'Couldn’t reach JupyterHub. Run again shortly.',
+    'hub-profile-changed': 'The environment configuration changed. Reopen the preview of the current version, then run again.',
+  },
+  noKernel: (name, kernel, known) => `Environment ${name} has no ${kernel} (available: ${known.join(', ') || 'none'})`,
+  wrongLanguage: (name, kernel, language, lang) => `${kernel} in environment ${name} runs ${language}, not ${lang}`,
+  timedOut: seconds => `Ran longer than ${seconds} s and was interrupted`,
+  tokenTitle: name => `Access Token for Environment ${name}`,
+  tokenHelp: origin => `Paste the access token of your Jupyter server. It stays in this page’s session storage (cleared when the tab closes) and goes to ${origin} only.`,
+  tokenLabel: 'Access token',
+  tokenConnect: 'Connect',
+  tokenCancel: 'Cancel',
+  terminal: name => `Terminal of environment ${name}`,
+  terminalOpen: 'Open Terminal',
+  terminalConnecting: 'Connecting…',
+  terminalClosed: 'The terminal ended',
+  terminalReconnect: 'Open Again',
+  terminalFailed: reason => `Couldn’t connect the terminal. ${reason}`,
+}
+
+export const MESSAGES: Catalog<JupyterMessages> = { 'zh-CN': zhCN, en }
+
+export function messages(): JupyterMessages {
+  return MESSAGES[currentLocale()]
+}
+
+/** A reader's sentence for why Jupyter could not be reached; the failure's own words go to the console only. */
+export function failureText(error: string, code?: string): string {
+  const t = messages()
+  if (code && code in t.reasons) return t.reasons[code]!
+  console.warn(`presmium: Jupyter: ${error}`)
+  return t.reasons.network!
+}

package/src/client/plugin.ts

@@ -0,0 +1,37 @@
+import { EXECUTOR } from '@lincyaw/kernel'
+import type { PluginDefinition, Unsubscribe } from '@lincyaw/kernel'
+import { version } from '../../package.json'
+import { EXEC_JUPYTER_ID, JUPYTER_TERMINALS, jupyterSpecs } from '../domain/index.ts'
+import { createJupyterClient } from './jupyter-client.ts'
+import type { JupyterClient } from './jupyter-client.ts'
+
+let client: JupyterClient | undefined
+let unregister: Unsubscribe[] = []
+
+export const execJupyterPlugin: PluginDefinition = {
+  manifest: {
+    id: EXEC_JUPYTER_ID,
+    name: { 'zh-CN': 'Jupyter 运行环境', en: 'Jupyter Environment' },
+    version,
+    kernel: '^1.0.0',
+    provides: [JUPYTER_TERMINALS],
+    requires: [{ token: EXECUTOR, optional: true }],
+    capabilities: ['exec', 'network'],
+  },
+  async setup(ctx) {
+    await client?.dispose()
+    client = createJupyterClient(jupyterSpecs(ctx.environments))
+    ctx.provide(JUPYTER_TERMINALS, client.terminals)
+    const router = ctx.tryGet(EXECUTOR)
+    if (router) unregister = client.executors.map(executor => router.register(executor))
+  },
+  dispose() {
+    unregister.forEach(off => off())
+    unregister = []
+    const cleanup = client?.dispose()
+    client = undefined
+    return cleanup
+  },
+}
+
+export default execJupyterPlugin

package/src/domain/args.ts

@@ -0,0 +1,22 @@
+import { languageId } from '@lincyaw/kernel'
+
+const PYTHON_ARG = `def _pm_arg(raw):
+    import ast, json
+    try:
+        return ast.literal_eval(raw)
+    except (ValueError, SyntaxError, TypeError, MemoryError, RecursionError):
+        pass
+    try:
+        return json.loads(raw)
+    except (ValueError, TypeError, RecursionError):
+        return raw`
+
+/** Code that assigns the run's arguments to variables before its code; in Python each value is read as a literal or as JSON when it is one. */
+export function argsPrelude(args: Record<string, string> | undefined, lang = ''): string | undefined {
+  const python = languageId(lang) === 'python'
+  const lines = Object.entries(args ?? {})
+    .filter(([name]) => /^[A-Za-z_]\w*$/.test(name))
+    .map(([name, value]) => `${name} = ${python ? `_pm_arg(${JSON.stringify(String(value))})` : JSON.stringify(String(value))}`)
+  if (lines.length === 0) return undefined
+  return python ? [PYTHON_ARG, ...lines, 'del _pm_arg'].join('\n') : lines.join('\n')
+}

package/src/domain/config.ts

@@ -0,0 +1,69 @@
+import { isRecord } from '@lincyaw/kernel'
+import type { EnvironmentAuth, EnvironmentSpec } from '@lincyaw/kernel'
+
+export const EXEC_JUPYTER_ID = 'presmium.execJupyter'
+
+export const JUPYTER_KIND = 'jupyter'
+
+export const DEFAULT_JUPYTER_KERNEL = 'python3'
+
+export const DEFAULT_TIMEOUT_MS = 60_000
+
+export const RUNS_DIR = 'presmium-runs'
+
+export const DEFAULT_TERMINAL_ROWS = 16
+
+export function envKey(name: string): string {
+  return name.toUpperCase().replace(/[^A-Z0-9]/g, '_')
+}
+
+export function operatorVariables(name: string): { url: string, token: string } {
+  const key = envKey(name)
+  return { url: `PRESMIUM_ENV_${key}_URL`, token: `PRESMIUM_ENV_${key}_TOKEN` }
+}
+
+export function proxyPath(name: string): string {
+  return `env/${envKey(name).toLowerCase()}`
+}
+
+export function cleanupPath(name: string): string {
+  return `cleanup/${envKey(name).toLowerCase()}`
+}
+
+export function preparePath(name: string): string {
+  return `prepare/${envKey(name).toLowerCase()}`
+}
+
+export function authOf(spec: EnvironmentSpec): EnvironmentAuth {
+  const auth = spec.auth
+  return auth === 'none' || auth === 'proxy' || auth === 'prompt' || auth === 'hub' ? auth : 'env'
+}
+
+/** The name of the Jupyter kernel the environment asks for (`kernel` of the headmatter). */
+export function jupyterKernelName(spec: EnvironmentSpec): string {
+  return typeof spec.kernel === 'string' && spec.kernel.trim() ? spec.kernel.trim() : DEFAULT_JUPYTER_KERNEL
+}
+
+export function languagesOf(spec: EnvironmentSpec): string[] | undefined {
+  return Array.isArray(spec.languages) ? spec.languages.filter((l): l is string => typeof l === 'string') : undefined
+}
+
+/** The `kind: jupyter` environments among those of the headmatter. */
+export function jupyterSpecs(environments: unknown): Record<string, EnvironmentSpec> {
+  if (!isRecord(environments)) return {}
+  return Object.fromEntries(Object.entries(environments).filter((entry): entry is [string, EnvironmentSpec] => isRecord(entry[1]) && entry[1].kind === JUPYTER_KIND))
+}
+
+export function originOf(url: string | undefined): string | undefined {
+  if (!url) return undefined
+  try {
+    const parsed = new URL(url)
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:' ? parsed.origin : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export function baseUrl(url: string): string {
+  return url.endsWith('/') ? url : `${url}/`
+}

package/src/domain/connection.ts

@@ -0,0 +1,37 @@
+import type { EnvironmentSpec } from '@lincyaw/kernel'
+import { authOf, baseUrl, operatorVariables, originOf } from './config.ts'
+
+export interface Connection {
+  url: string
+  headers: Record<string, string>
+}
+
+export type OperatorConnection =
+  | { connection: Connection }
+  | { unavailable: string }
+  | { mismatch: string }
+
+export interface OperatorSide {
+  secret(name: string): string | undefined
+}
+
+export function operatorConnection(name: string, spec: EnvironmentSpec, side: OperatorSide): OperatorConnection {
+  const auth = authOf(spec)
+  if (auth === 'hub') return { unavailable: 'auth: hub starts an operator-defined profile on explicit browser execution; it is not started by a build or an environment probe' }
+  if (auth === 'none') {
+    const url = typeof spec.url === 'string' ? spec.url : undefined
+    if (!originOf(url)) return { unavailable: 'auth: none connects to the deck\'s url, which is missing or not an http(s) address' }
+    return { connection: { url: baseUrl(url!), headers: {} } }
+  }
+  const variables = operatorVariables(name)
+  const url = side.secret(variables.url)
+  if (!url) return { unavailable: `${variables.url} is not set: the operator gives the environment's address there, and its token (${variables.token}) is sent to that address only` }
+  const origin = originOf(url)
+  if (!origin) return { unavailable: `${variables.url} is not an http(s) address` }
+  const deck = typeof spec.url === 'string' && spec.url ? spec.url : undefined
+  if (deck && originOf(deck) !== origin) {
+    return { mismatch: `the deck's url ${deck} is not the operator's address (${variables.url}, ${origin}); the operator's token goes to the operator's address only, so nothing connects. Leave the url out, or write the operator's` }
+  }
+  const token = side.secret(variables.token)
+  return { connection: { url: baseUrl(url), headers: token ? { Authorization: `token ${token}` } : {} } }
+}

package/src/domain/fallback-text.ts

@@ -0,0 +1,10 @@
+import { deckLocale } from '@lincyaw/kernel'
+
+const TERMINAL = {
+  'zh-CN': (name: string) => `环境 ${name} 的终端：请在网页或幻灯片中打开。`,
+  'en': (name: string) => `Terminal of environment ${name}: open it on the web page or in the slides.`,
+}
+
+export function terminalFallback(name: string, lang: string | undefined): string {
+  return TERMINAL[deckLocale(lang)](name)
+}

package/src/domain/index.ts

@@ -0,0 +1,26 @@
+export {
+  authOf,
+  baseUrl,
+  cleanupPath,
+  DEFAULT_JUPYTER_KERNEL,
+  DEFAULT_TERMINAL_ROWS,
+  DEFAULT_TIMEOUT_MS,
+  envKey,
+  EXEC_JUPYTER_ID,
+  JUPYTER_KIND,
+  jupyterKernelName,
+  jupyterSpecs,
+  languagesOf,
+  operatorVariables,
+  originOf,
+  proxyPath,
+  preparePath,
+  RUNS_DIR,
+} from './config.ts'
+export { argsPrelude } from './args.ts'
+export { operatorConnection } from './connection.ts'
+export type { Connection, OperatorConnection, OperatorSide } from './connection.ts'
+export { OutputCollector, stripAnsi } from './outputs.ts'
+export { JUPYTER_TERMINALS } from './terminal-service.ts'
+export type { JupyterTerminals, TerminalEvents, TerminalSession } from './terminal-service.ts'
+export { terminalFallback } from './fallback-text.ts'