@lincyaw/addon-exec-local 0.0.0-stage → 1.0.0-rc.1

package/src/node/messages.ts

@@ -0,0 +1,80 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { deckLocale } from '@lincyaw/kernel'
+
+const zhCN = {
+  codeChild: 'PmLocalEnv 必须有且只有一个 canonical 代码子块。',
+  noDefinition: '工作区没有 devcontainer 定义',
+  unreadableDefinition: '无法读取 devcontainer 定义，请确认 Docker 可用',
+  unsupportedLanguage: (lang: string) => `容器执行器不支持语言 ${lang}`,
+  buildFailed: (detail: string) => `devcontainer build 失败：${detail}`,
+  outsideWorkspace: (file: string) => `路径必须位于工作区内：${file}`,
+  notJson: '请求体必须是 JSON',
+  invalidJson: '请求体不是有效的 JSON',
+  notObject: '请求体必须是 JSON 对象',
+  missingField: (key: string) => `缺少字段 ${key}`,
+  notString: (key: string) => `字段 ${key} 必须是字符串`,
+  notStringTable: (key: string) => `字段 ${key} 必须是字符串表`,
+  runTitle: (lang: string) => `在本地环境的容器中运行一段 ${lang} 代码`,
+  notAllowed: '没有得到运行的许可',
+  readme: (file: string, run?: string) => [
+    '# Presmium 导出的运行环境',
+    '',
+    `本压缩包包含演示中的代码片段 \`${file}\` 与仓库的 devcontainer 定义。`,
+    '',
+    '用 Dev Containers CLI 打开并运行：',
+    '',
+    '```sh',
+    'devcontainer up --workspace-folder .',
+    `devcontainer exec --workspace-folder . ${run ?? `<运行 ${file} 的命令>`}`,
+    '```',
+    '',
+    '也可以在 VS Code 中打开本目录，选择“Reopen in Container”。',
+    '',
+  ].join('\n'),
+}
+
+export type ServerMessages = typeof zhCN
+
+const en: ServerMessages = {
+  codeChild: 'PmLocalEnv requires exactly one canonical code child.',
+  noDefinition: 'The workspace has no devcontainer definition',
+  unreadableDefinition: 'Cannot read the devcontainer definition; check that Docker is available',
+  unsupportedLanguage: lang => `The container executor does not run ${lang}`,
+  buildFailed: detail => `devcontainer build failed: ${detail}`,
+  outsideWorkspace: file => `The path must be inside the workspace: ${file}`,
+  notJson: 'The request body must be JSON',
+  invalidJson: 'The request body is not valid JSON',
+  notObject: 'The request body must be a JSON object',
+  missingField: key => `Missing field ${key}`,
+  notString: key => `Field ${key} must be a string`,
+  notStringTable: key => `Field ${key} must map names to strings`,
+  runTitle: lang => `Run ${lang} code in the local environment's container`,
+  notAllowed: 'The run was not allowed',
+  readme: (file, run) => [
+    '# Environment exported by Presmium',
+    '',
+    `This archive holds the snippet \`${file}\` from the presentation and the repository's devcontainer definition.`,
+    '',
+    'Open and run it with the Dev Containers CLI:',
+    '',
+    '```sh',
+    'devcontainer up --workspace-folder .',
+    `devcontainer exec --workspace-folder . ${run ?? `<command that runs ${file}>`}`,
+    '```',
+    '',
+    'You can also open this folder in VS Code and choose "Reopen in Container".',
+    '',
+  ].join('\n'),
+}
+
+const MESSAGES = { 'zh-CN': zhCN, en }
+
+const requested = new AsyncLocalStorage<ServerMessages>()
+
+export function inLanguage<T>(language: string | undefined, task: () => T): T {
+  return requested.run(MESSAGES[deckLocale(language?.trim())], task)
+}
+
+export function text(): ServerMessages {
+  return requested.getStore() ?? en
+}

package/src/node/presmium.ts

@@ -0,0 +1,53 @@
+import { createRequire } from 'node:module'
+import { resolve } from 'node:path'
+import { componentCode, environmentExecutor, jupyterKernelLanguage, languageId } from '@lincyaw/kernel'
+import type { EnvironmentProvider, EnvironmentSpec, PresmiumNodePlugin } from '@lincyaw/kernel'
+import { DEVCONTAINER_KIND, EXEC_LOCAL_ID } from '../domain/index.ts'
+import { createContainerExecutor } from './container.ts'
+import { findDefinition } from './devcontainer.ts'
+import { dockerAvailable } from './docker.ts'
+import { localEnvDirective, localEnvPass } from './local-env.ts'
+import { localEnvRoutes } from './server.ts'
+
+const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
+
+/** The plugin's executor, which each compile replaces with its deck's own (`localEnvPass`). */
+const container = createContainerExecutor()
+
+const definitionDir = (spec: EnvironmentSpec, deckDir: string, workspaceRoot: string) => typeof spec.path === 'string' && spec.path ? resolve(deckDir, spec.path) : workspaceRoot
+
+const devcontainer: EnvironmentProvider = {
+  create(name, spec, ctx) {
+    const executor = createContainerExecutor(environmentExecutor(name))
+    executor.bind(definitionDir(spec, ctx.deckDir, ctx.workspaceRoot))
+    return executor
+  },
+  async probe(_name, spec, ctx) {
+    const dir = definitionDir(spec, ctx.deckDir, ctx.workspaceRoot)
+    if (!findDefinition(dir)) return `no devcontainer definition (.devcontainer/devcontainer.json) in ${dir}`
+    return await dockerAvailable() ? undefined : 'Docker is not available'
+  },
+}
+
+const plugin: PresmiumNodePlugin = {
+  id: EXEC_LOCAL_ID,
+  version,
+  kernel: '^1.0.0',
+  directives: [localEnvDirective],
+  passes: [localEnvPass(container)],
+  executors: [container],
+  environments: { [DEVCONTAINER_KIND]: devcontainer },
+  server: localEnvRoutes,
+  rendererExtensions: {
+    notebook: {
+      components: {
+        PmLocalEnv(node, _block, ctx) {
+          const code = componentCode(node)
+          return code && languageId(code.lang) === jupyterKernelLanguage(ctx.config.kernel) ? { cell_type: 'code', source: code.value, outputs: [], execution_count: null } : undefined
+        },
+      },
+    },
+  },
+}
+
+export default plugin

package/src/node/process.ts

@@ -0,0 +1,68 @@
+import { spawn } from 'node:child_process'
+import { backgroundPriority, resourceEnvironment } from '@lincyaw/kernel/node'
+
+export interface ProcessResult {
+  code: number | null
+  stdout: string
+  stderr: string
+  timedOut: boolean
+}
+
+export interface ProcessOptions {
+  cwd?: string
+  env?: Record<string, string>
+  input?: string
+  timeoutMs?: number
+  signal?: AbortSignal
+  onStop?: () => void
+}
+
+const GRACE_MS = 5_000
+
+export function runProcess(command: string, args: string[], options: ProcessOptions = {}): Promise<ProcessResult> {
+  return new Promise((resolve) => {
+    const group = process.platform !== 'win32'
+    const child = spawn(command, args, { cwd: options.cwd, env: resourceEnvironment(options.env), stdio: 'pipe', detached: group })
+    backgroundPriority(child.pid)
+    const stdout: Buffer[] = []
+    const stderr: Buffer[] = []
+    let timedOut = false
+    let stopped = false
+    let kill: ReturnType<typeof setTimeout> | undefined
+    const send = (signal: NodeJS.Signals) => {
+      try {
+        if (group && child.pid) process.kill(-child.pid, signal)
+        else child.kill(signal)
+      }
+      catch {}
+    }
+    const stop = () => {
+      if (stopped) return
+      stopped = true
+      options.onStop?.()
+      send('SIGTERM')
+      kill = setTimeout(() => send('SIGKILL'), GRACE_MS)
+    }
+    const timer = options.timeoutMs === undefined
+      ? undefined
+      : setTimeout(() => {
+          timedOut = true
+          stop()
+        }, options.timeoutMs)
+    if (options.signal?.aborted) stop()
+    options.signal?.addEventListener('abort', stop, { once: true })
+    const finish = (code: number | null, error?: Error) => {
+      clearTimeout(timer)
+      clearTimeout(kill)
+      options.signal?.removeEventListener('abort', stop)
+      const err = Buffer.concat(stderr).toString('utf8')
+      resolve({ code, stdout: Buffer.concat(stdout).toString('utf8'), stderr: error ? `${err}${error.message}` : err, timedOut })
+    }
+    child.stdout.on('data', (chunk: Buffer) => stdout.push(chunk))
+    child.stderr.on('data', (chunk: Buffer) => stderr.push(chunk))
+    child.on('error', error => finish(null, error))
+    child.on('close', code => finish(code))
+    child.stdin.on('error', () => {})
+    child.stdin.end(options.input ?? '')
+  })
+}

package/src/node/replicate.ts

@@ -0,0 +1,30 @@
+import { readFileSync } from 'node:fs'
+import { relative, sep } from 'node:path'
+import { languageId } from '@lincyaw/kernel'
+import { strToU8, zipSync } from 'fflate'
+import { archiveName, workspacePath } from '../domain/index.ts'
+import type { ReplicateRequest } from '../domain/index.ts'
+import { definitionCommands, definitionFiles } from './devcontainer.ts'
+import { text } from './messages.ts'
+
+export class PathError extends Error {}
+
+export function requirePath(file: string): string {
+  try {
+    return workspacePath(file)
+  } catch {
+    throw new PathError(text().outsideWorkspace(file))
+  }
+}
+
+export function replicateArchive(workspace: string, configFile: string, request: ReplicateRequest): { name: string, zip: Uint8Array } {
+  const file = requirePath(request.file)
+  const entries: Record<string, Uint8Array> = {}
+  for (const path of definitionFiles(configFile)) {
+    entries[requirePath(relative(workspace, path).split(sep).join('/'))] = readFileSync(path)
+  }
+  entries[file] = strToU8(request.content)
+  const command = request.lang ? definitionCommands(configFile)[languageId(request.lang)] : undefined
+  entries[file === 'README.md' ? 'PRESMIUM.md' : 'README.md'] = strToU8(text().readme(file, command && `${command[0]} ${file}`))
+  return { name: archiveName(file), zip: zipSync(entries, { mtime: '2000-01-01T00:00:00Z' }) }
+}

package/src/node/server.ts

@@ -0,0 +1,116 @@
+import { relative, resolve, sep } from 'node:path'
+import { APPROVALS, errorMessage, isRecord, jsonResponse, problemResponse } from '@lincyaw/kernel'
+import type { Route, RunRequest, ServerContext, ServerContribution } from '@lincyaw/kernel'
+import { EXEC_LOCAL_ID, execLocalConfig, failedContainerRun } from '../domain/index.ts'
+import type { LocalEnvStatus } from '../domain/index.ts'
+import { runInContainer } from './container.ts'
+import { definitionCommands, findDefinition, readDevcontainer } from './devcontainer.ts'
+import { dockerAvailable } from './docker.ts'
+import { inLanguage, text } from './messages.ts'
+import { PathError, replicateArchive, requirePath } from './replicate.ts'
+
+class Refused extends Error {
+  readonly status: number
+
+  constructor(status: number, message: string) {
+    super(message)
+    this.status = status
+  }
+}
+
+async function body(request: Request): Promise<Record<string, unknown>> {
+  if (!request.headers.get('content-type')?.startsWith('application/json')) throw new Refused(415, text().notJson)
+  let value: unknown
+  try {
+    value = JSON.parse(await request.text() || '{}')
+  } catch {
+    throw new Refused(400, text().invalidJson)
+  }
+  if (!isRecord(value)) throw new Refused(400, text().notObject)
+  return value
+}
+
+function string(body: Record<string, unknown>, key: string, optional = false): string | undefined {
+  const value = body[key]
+  if (value === undefined && optional) return undefined
+  if (typeof value !== 'string') throw new Refused(400, optional ? text().notString(key) : text().missingField(key))
+  return value
+}
+
+function stringTable(body: Record<string, unknown>, key: string): Record<string, string> | undefined {
+  const value = body[key]
+  if (value === undefined) return undefined
+  if (!isRecord(value) || Object.values(value).some(v => typeof v !== 'string')) throw new Refused(400, text().notStringTable(key))
+  return value as Record<string, string>
+}
+
+function runRequest(body: Record<string, unknown>): RunRequest {
+  const files = stringTable(body, 'files')
+  for (const file of Object.keys(files ?? {})) requirePath(file)
+  return {
+    lang: string(body, 'lang')!,
+    code: string(body, 'code')!,
+    args: stringTable(body, 'args'),
+    stdin: string(body, 'stdin', true),
+    timeoutMs: typeof body.timeoutMs === 'number' ? body.timeoutMs : undefined,
+    files,
+  }
+}
+
+async function status(workspace: string): Promise<LocalEnvStatus> {
+  const definition = findDefinition(workspace)
+  const docker = await dockerAvailable()
+  return {
+    connected: true,
+    docker,
+    devcontainer: definition ? relative(workspace, definition).split(sep).join('/') : null,
+    languages: docker && definition ? Object.keys(definitionCommands(definition)) : [],
+  }
+}
+
+function route(handle: (request: Request, member: string) => Promise<Response>): Route {
+  return {
+    handle: (request, ctx) => inLanguage(request.headers.get('accept-language') ?? undefined, async () => {
+      try {
+        return await handle(request, ctx.member.id)
+      } catch (error) {
+        if (error instanceof Refused) return problemResponse(error.status, error.message)
+        return problemResponse(error instanceof PathError ? 400 : 500, errorMessage(error))
+      }
+    }),
+  }
+}
+
+export function localEnvRoutes(ctx: ServerContext): ServerContribution {
+  const { workspace: configured, buildTimeoutMs } = execLocalConfig(ctx.config)
+  const workspace = configured === undefined ? ctx.workspaceRoot : resolve(ctx.deckDir, configured)
+  return {
+    routes: {
+      status: route(async () => jsonResponse(await status(workspace))),
+      run: route(async (request, member) => {
+        const run = runRequest(await body(request))
+        const approvals = ctx.service(APPROVALS)
+        const allowed = await approvals?.request({ kind: 'operate', scope: 'content', title: text().runTitle(run.lang), detail: run.code, from: EXEC_LOCAL_ID, member }, request.signal)
+        if (!allowed) throw new Refused(403, text().notAllowed)
+        if (!findDefinition(workspace)) return jsonResponse(failedContainerRun(text().noDefinition))
+        const devcontainer = await readDevcontainer(workspace)
+        if (!devcontainer) return jsonResponse(failedContainerRun(text().unreadableDefinition))
+        return jsonResponse(await runInContainer({ workspace, devcontainer, request: run, build: { buildTimeoutMs }, signal: request.signal }))
+      }),
+      replicate: route(async (request) => {
+        const fields = await body(request)
+        const asked = { file: string(fields, 'file')!, content: string(fields, 'content')!, lang: string(fields, 'lang', true) }
+        const definition = findDefinition(workspace)
+        if (!definition) throw new Refused(404, text().noDefinition)
+        const { name, zip } = replicateArchive(workspace, definition, asked)
+        return new Response(new Uint8Array(zip), {
+          headers: {
+            'Content-Type': 'application/zip',
+            'Content-Disposition': `attachment; filename="${name.replace(/[^\w.-]/g, '_')}"; filename*=UTF-8''${encodeURIComponent(name)}`,
+            'Cache-Control': 'no-store',
+          },
+        })
+      }),
+    },
+  }
+}