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

package/src/client/plugin.ts

@@ -0,0 +1,39 @@
+import { environmentExecutor, EXECUTOR } from '@lincyaw/kernel'
+import type { Executor, PluginDefinition, Unsubscribe } from '@lincyaw/kernel'
+import { version } from '../../package.json'
+import { DEVCONTAINER_KIND, EXEC_LOCAL_ID, execLocalConfig, LOCAL_ENV } from '../domain/index.ts'
+import { createLocalEnvClient } from './local-env.ts'
+
+let unregister: Unsubscribe[] = []
+
+export const execLocalPlugin: PluginDefinition = {
+  manifest: {
+    id: EXEC_LOCAL_ID,
+    name: { 'zh-CN': '本机容器运行', en: 'Local Container Runner' },
+    version,
+    kernel: '^1.0.0',
+    provides: [LOCAL_ENV],
+    requires: [{ token: EXECUTOR, optional: true }],
+    capabilities: ['exec', 'fs'],
+  },
+  setup(ctx) {
+    const env = createLocalEnvClient()
+    ctx.provide(LOCAL_ENV, env)
+    const router = ctx.tryGet(EXECUTOR)
+    if (router) {
+      unregister = [router.register(env.executor, execLocalConfig(ctx.config).priority)]
+      for (const [name, spec] of Object.entries(ctx.environments ?? {})) {
+        if (spec.kind !== DEVCONTAINER_KIND) continue
+        const named: Executor = { id: environmentExecutor(name), supports: lang => env.executor.supports(lang), run: (request, signal) => env.executor.run(request, signal) }
+        unregister.push(router.register(named))
+      }
+    }
+    void env.status()
+  },
+  dispose() {
+    unregister.forEach(off => off())
+    unregister = []
+  },
+}
+
+export default execLocalPlugin

package/src/domain/config.ts

@@ -0,0 +1,25 @@
+import { isRecord } from '@lincyaw/kernel'
+
+export const EXEC_LOCAL_ID = 'presmium.execLocal'
+
+export const DEVCONTAINER_KIND = 'devcontainer'
+
+export interface ExecLocalConfig {
+  workspace?: string
+  priority: number
+  buildTimeoutMs: number
+}
+
+export const DEFAULT_PRIORITY = 10
+
+export const DEFAULT_BUILD_TIMEOUT_MS = 600_000
+
+export function execLocalConfig(options: unknown): ExecLocalConfig {
+  const config = isRecord(options) ? options : {}
+  const buildTimeoutMs = config.buildTimeoutMs
+  return {
+    workspace: typeof config.workspace === 'string' ? config.workspace : undefined,
+    priority: typeof config.priority === 'number' ? config.priority : DEFAULT_PRIORITY,
+    buildTimeoutMs: typeof buildTimeoutMs === 'number' && buildTimeoutMs > 0 ? buildTimeoutMs : DEFAULT_BUILD_TIMEOUT_MS,
+  }
+}

package/src/domain/index.ts

@@ -0,0 +1,6 @@
+export { DEFAULT_BUILD_TIMEOUT_MS, DEFAULT_PRIORITY, DEVCONTAINER_KIND, EXEC_LOCAL_ID, execLocalConfig } from './config.ts'
+export type { ExecLocalConfig } from './config.ts'
+export { CONTAINER_EXECUTOR_ID, disconnected, failedContainerRun, LOCAL_ENV } from './service.ts'
+export type { DisconnectedReason, LocalEnvService, LocalEnvStatus, ReplicateRequest } from './service.ts'
+export { archiveName, DEFAULT_LANGUAGE_COMMANDS, languageCommandsFrom, workspacePath } from './workspace.ts'
+export type { LanguageCommands } from './workspace.ts'

package/src/domain/service.ts

@@ -0,0 +1,36 @@
+import { defineService, failedRun } from '@lincyaw/kernel'
+import type { RunRequest, RunResult } from '@lincyaw/kernel'
+
+export const CONTAINER_EXECUTOR_ID = 'presmium.container'
+
+export type DisconnectedReason = 'devServerOnly' | 'noEndpoints' | 'notAllowed' | 'unreachable' | 'pluginOff'
+
+export interface LocalEnvStatus {
+  connected: boolean
+  docker: boolean
+  devcontainer: string | null
+  languages: string[]
+  reason?: DisconnectedReason
+}
+
+export interface ReplicateRequest {
+  file: string
+  content: string
+  lang?: string
+}
+
+export interface LocalEnvService {
+  status(): Promise<LocalEnvStatus>
+  run(request: RunRequest, signal?: AbortSignal): Promise<RunResult>
+  replicate(request: ReplicateRequest): Promise<Blob>
+}
+
+export const LOCAL_ENV = defineService<LocalEnvService>('presmium.localEnv')
+
+export function disconnected(reason: DisconnectedReason): LocalEnvStatus {
+  return { connected: false, docker: false, devcontainer: null, languages: [], reason }
+}
+
+export function failedContainerRun(message: string, executorId = CONTAINER_EXECUTOR_ID): RunResult {
+  return failedRun(executorId, message)
+}

package/src/domain/workspace.ts

@@ -0,0 +1,32 @@
+import { isRecord, languageId } from '@lincyaw/kernel'
+
+/** The command that runs code of each language in the container; the code follows as its last argument. */
+export type LanguageCommands = Record<string, string[]>
+
+export const DEFAULT_LANGUAGE_COMMANDS: LanguageCommands = { python: ['python3', '-c'] }
+
+/** The commands of the devcontainer definition (`customizations.presmium.runners`) over the default ones. */
+export function languageCommandsFrom(customizations: unknown): LanguageCommands {
+  const presmium = isRecord(customizations) ? customizations.presmium : undefined
+  const custom = isRecord(presmium) && isRecord(presmium.runners) ? presmium.runners : {}
+  const commands: LanguageCommands = { ...DEFAULT_LANGUAGE_COMMANDS }
+  for (const [lang, command] of Object.entries(custom)) {
+    if (Array.isArray(command) && command.length > 0 && command.every(part => typeof part === 'string')) {
+      commands[languageId(lang)] = command
+    }
+  }
+  return commands
+}
+
+export function workspacePath(file: string): string {
+  const parts = file.replaceAll('\\', '/').split('/').filter(part => part !== '' && part !== '.')
+  if (!file || /^([a-z]:)?[\\/]/i.test(file) || parts.length === 0 || parts.includes('..') || parts[0] === '.git') {
+    throw new Error(`not a path inside the workspace: ${file}`)
+  }
+  return parts.join('/')
+}
+
+export function archiveName(file: string): string {
+  const name = file.split('/').pop() ?? file
+  return `presmium-env-${name.replace(/\.[^.]*$/, '') || 'snippet'}.zip`
+}

package/src/node/container.ts

@@ -0,0 +1,163 @@
+import { randomUUID } from 'node:crypto'
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { errorMessage, languageId } from '@lincyaw/kernel'
+import type { Executor, RunContext, RunOutput, RunRequest, RunResult } from '@lincyaw/kernel'
+import { RUN_REQUEST_FILE, runResultFile } from '@lincyaw/kernel/node'
+import { CONTAINER_EXECUTOR_ID, failedContainerRun, workspacePath } from '../domain/index.ts'
+import type { BuildOptions, Devcontainer } from './devcontainer.ts'
+import { definitionCommands, definitionHash, devcontainerImage, findDefinition, readDevcontainer } from './devcontainer.ts'
+import { dockerAvailable, dockerEnv, isDockerAvailableSync } from './docker.ts'
+import { text } from './messages.ts'
+import { runProcess } from './process.ts'
+
+const DEFAULT_TIMEOUT_MS = 30_000
+const RUN_DIR = '/presmium-run'
+const PYTHON_RUNNER = `${readFileSync(createRequire(import.meta.url).resolve('@lincyaw/kernel/runner.py'), 'utf8')}\n_pm_main()\n`
+const HOST_PATHS = new Set(['PATH', 'HOME', 'TMPDIR'])
+
+export interface ContainerExecutor extends Executor {
+  bind(workspace: string, options?: BuildOptions): void
+}
+
+/** Runs code in a new container of the image of the bound workspace's devcontainer definition. */
+export function createContainerExecutor(id = CONTAINER_EXECUTOR_ID): ContainerExecutor {
+  let workspace: string | undefined
+  let build: BuildOptions = {}
+  const definition = () => (workspace === undefined ? undefined : findDefinition(workspace))
+  const command = (configFile: string, lang: string) => definitionCommands(configFile)[languageId(lang)]
+  return {
+    id,
+    bind(dir, options = {}) {
+      workspace = dir
+      build = options
+    },
+    supports(lang) {
+      const configFile = definition()
+      return configFile !== undefined && command(configFile, lang) !== undefined && isDockerAvailableSync()
+    },
+    fingerprint(lang) {
+      const configFile = definition()
+      return configFile ? `${definitionHash(configFile)}:${JSON.stringify(command(configFile, lang) ?? null)}` : ''
+    },
+    async run(request, signal, ctx) {
+      const dir = workspace
+      if (dir === undefined || !definition()) throw new Error('the workspace has no devcontainer definition')
+      if (!await dockerAvailable()) throw new Error('Docker is not available')
+      const devcontainer = await readDevcontainer(dir, dockerEnv(ctx))
+      if (!devcontainer) throw new Error('cannot read the devcontainer definition')
+      const result = await runInContainer({ workspace: dir, devcontainer, request, build, signal, ctx, executorId: id })
+      if (result.exitCode === null && !result.timedOut) throw new Error(result.stderr)
+      return result
+    },
+  }
+}
+
+function runDirectory(files: Record<string, string> | undefined, runnerRequest?: unknown): { parent: string, dir: string } {
+  const parent = mkdtempSync(join(tmpdir(), 'presmium-container-'))
+  chmodSync(parent, 0o700)
+  const dir = join(parent, 'run')
+  try {
+    mkdirSync(join(dir, '.presmium'), { recursive: true })
+    chmodSync(dir, 0o777)
+    chmodSync(join(dir, '.presmium'), 0o777)
+    for (const [name, content] of Object.entries(files ?? {})) {
+      const file = join(dir, workspacePath(name))
+      mkdirSync(dirname(file), { recursive: true, mode: 0o777 })
+      writeFileSync(file, content, { mode: 0o666, flag: 'wx' })
+    }
+    if (runnerRequest !== undefined) writeFileSync(join(dir, RUN_REQUEST_FILE), JSON.stringify(runnerRequest), { mode: 0o666, flag: 'wx' })
+  } catch (error) {
+    rmSync(parent, { recursive: true, force: true })
+    throw error
+  }
+  return { parent, dir }
+}
+
+function pythonResult(dir: string): { stdout: string, stderr: string, exitCode: number, outputs?: RunOutput[] } | undefined {
+  try {
+    return JSON.parse(readFileSync(join(dir, runResultFile(0)), 'utf8'))
+  }
+  catch {
+    return undefined
+  }
+}
+
+export interface ContainerRun {
+  workspace: string
+  devcontainer: Devcontainer
+  request: RunRequest
+  build?: BuildOptions
+  signal?: AbortSignal
+  ctx?: RunContext
+  executorId?: string
+}
+
+/** Runs the request with `docker run` in a new container of the definition's image, without network; the workspace is mounted read-only. */
+export async function runInContainer(run: ContainerRun): Promise<RunResult> {
+  const { workspace, devcontainer, request, signal, ctx, executorId = CONTAINER_EXECUTOR_ID } = run
+  const lang = languageId(request.lang)
+  const command = devcontainer.commands[lang]
+  if (!command) return failedContainerRun(text().unsupportedLanguage(request.lang), executorId)
+  const commandEnv = dockerEnv(ctx)
+  let image: string
+  try {
+    image = await devcontainerImage(workspace, devcontainer, run.build, signal, commandEnv)
+  }
+  catch (error) {
+    return failedContainerRun(text().buildFailed(errorMessage(error)), executorId)
+  }
+  const python = lang === 'python'
+  let directory: { parent: string, dir: string }
+  try {
+    directory = runDirectory(request.files, python ? { runs: [{ code: request.code, args: request.args ?? {}, stdin: request.stdin ?? '' }], path: [devcontainer.workspaceFolder] } : undefined)
+  }
+  catch (error) {
+    return failedContainerRun(errorMessage(error), executorId)
+  }
+  const { parent, dir } = directory
+  const started = Date.now()
+  const name = `presmium-run-${randomUUID()}`
+  const passed = Object.fromEntries(Object.entries(ctx?.env ?? {}).filter(([key]) => !HOST_PATHS.has(key)))
+  const env = { ...passed, ...devcontainer.env, ...python ? {} : request.args }
+  try {
+    const result = await runProcess('docker', [
+      'run', '--rm', '-i', '--init', '--network', 'none', '--name', name,
+      '--mount', `${devcontainer.workspaceMount},readonly`,
+      '--mount', `type=bind,source=${dir},target=${RUN_DIR}`,
+      '--workdir', RUN_DIR,
+      ...(devcontainer.user ? ['--user', devcontainer.user] : []),
+      ...Object.entries(env).flatMap(([key, value]) => ['--env', `${key}=${value}`]),
+      image,
+      ...command,
+      python ? PYTHON_RUNNER : request.code,
+    ], {
+      input: python ? '' : request.stdin,
+      env: commandEnv,
+      timeoutMs: request.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      signal,
+      onStop: () => void runProcess('docker', ['kill', name], { env: commandEnv }),
+    })
+    const output = python && !result.timedOut ? pythonResult(dir) : undefined
+    const exitCode = result.timedOut ? null : output ? output.exitCode : result.code
+    return {
+      ok: exitCode === 0,
+      stdout: output ? output.stdout : result.stdout,
+      stderr: output ? output.stderr : result.stderr,
+      exitCode,
+      durationMs: Date.now() - started,
+      timedOut: result.timedOut,
+      source: 'live',
+      executorId,
+      ...output?.outputs ? { outputs: output.outputs } : {},
+    }
+  }
+  finally {
+    try {
+      rmSync(parent, { recursive: true, force: true })
+    }
+    catch {}
+  }
+}

package/src/node/devcontainer.ts

@@ -0,0 +1,165 @@
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { basename, dirname, join, relative, resolve } from 'node:path'
+import { parse } from 'jsonc-parser'
+import { DEFAULT_BUILD_TIMEOUT_MS, languageCommandsFrom } from '../domain/index.ts'
+import type { LanguageCommands } from '../domain/index.ts'
+import { dockerEnv } from './docker.ts'
+import { runProcess } from './process.ts'
+
+const CLI = createRequire(import.meta.url).resolve('@devcontainers/cli/devcontainer.js')
+const READ_TIMEOUT_MS = 60_000
+
+export interface Devcontainer {
+  configFile: string
+  workspaceMount: string
+  workspaceFolder: string
+  commands: LanguageCommands
+  user?: string
+  env: Record<string, string>
+}
+
+export interface BuildOptions {
+  buildTimeoutMs?: number
+}
+
+function devcontainerCli(args: string[], timeoutMs: number, signal?: AbortSignal, env = dockerEnv()) {
+  return runProcess(process.execPath, [CLI, ...args], { timeoutMs, signal, env })
+}
+
+interface CliOutput {
+  outcome?: string
+  message?: string
+  description?: string
+  configuration?: {
+    configFilePath?: { fsPath?: string }
+    customizations?: unknown
+    remoteUser?: string
+    containerUser?: string
+    containerEnv?: Record<string, string>
+  }
+  workspace?: { workspaceFolder?: string, workspaceMount?: string }
+}
+
+function lastJson(stdout: string): CliOutput | undefined {
+  const line = stdout.trim().split('\n').pop()
+  try {
+    return line ? JSON.parse(line) : undefined
+  }
+  catch {
+    return undefined
+  }
+}
+
+export function findDefinition(workspace: string): string | undefined {
+  return ['.devcontainer/devcontainer.json', '.devcontainer.json'].map(file => join(workspace, file)).find(existsSync)
+}
+
+export function definitionFiles(configFile: string): string[] {
+  const dir = dirname(configFile)
+  const files = new Set(basename(configFile) === '.devcontainer.json' ? [configFile]
+    : readdirSync(dir, { recursive: true, encoding: 'utf8' }).map(name => join(dir, name)).filter(path => statSync(path).isFile()))
+  const config = parse(readFileSync(configFile, 'utf8'), [], { allowTrailingComma: true }) as {
+    dockerFile?: string, build?: { dockerfile?: string, context?: string }, dockerComposeFile?: string | string[]
+  } | undefined
+  const dockerfile = config?.build?.dockerfile ?? config?.dockerFile
+  const references = [dockerfile, ...typeof config?.dockerComposeFile === 'string' ? [config.dockerComposeFile] : config?.dockerComposeFile ?? []]
+  if (dockerfile) references.push(join(config?.build?.context ?? '.', '.dockerignore'))
+  for (const reference of references) {
+    if (!reference) continue
+    const path = resolve(dir, reference)
+    if (statSync(path, { throwIfNoEntry: false })?.isFile()) files.add(path)
+  }
+  return [...files].sort()
+}
+
+function definitionStamp(configFile: string): string {
+  return JSON.stringify([configFile, definitionFiles(configFile).map(path => {
+    const { size, mtimeMs, ctimeMs } = statSync(path)
+    return [path, size, mtimeMs, ctimeMs]
+  })])
+}
+
+function perVersion<T>(compute: (configFile: string) => T): (configFile: string) => T {
+  const values = new Map<string, T>()
+  return (configFile) => {
+    const stamp = definitionStamp(configFile)
+    if (!values.has(stamp)) values.set(stamp, compute(configFile))
+    return values.get(stamp)!
+  }
+}
+
+/** The language commands of the devcontainer definition, read again when its inputs change. */
+export const definitionCommands = perVersion((configFile): LanguageCommands => {
+  const config = parse(readFileSync(configFile, 'utf8'), [], { allowTrailingComma: true }) as { customizations?: unknown } | undefined
+  return languageCommandsFrom(config?.customizations)
+})
+
+export const definitionHash = perVersion((configFile): string => {
+  const dir = dirname(configFile)
+  const hash = createHash('sha256')
+  for (const path of definitionFiles(configFile)) {
+    hash.update(`${relative(dir, path)}\0`).update(readFileSync(path)).update('\0')
+  }
+  return hash.digest('hex')
+})
+
+const configurations = new Map<string, Promise<Devcontainer | undefined>>()
+
+export function readDevcontainer(workspace: string, env?: Record<string, string>): Promise<Devcontainer | undefined> {
+  const configFile = findDefinition(workspace)
+  if (!configFile) return Promise.resolve(undefined)
+  const key = `${workspace}\0${definitionStamp(configFile)}`
+  let read = configurations.get(key)
+  if (!read) {
+    read = readConfiguration(workspace, env)
+    configurations.set(key, read)
+    void read.then(found => found || configurations.delete(key))
+  }
+  return read
+}
+
+async function readConfiguration(workspace: string, env?: Record<string, string>): Promise<Devcontainer | undefined> {
+  const result = await devcontainerCli(['read-configuration', '--workspace-folder', workspace], READ_TIMEOUT_MS, undefined, env)
+  const output = lastJson(result.stdout)
+  const config = output?.configuration
+  const configFile = config?.configFilePath?.fsPath
+  if (result.code !== 0 || !config || !configFile) return undefined
+  const workspaceFolder = output?.workspace?.workspaceFolder ?? `/workspaces/${basename(workspace)}`
+  return {
+    configFile,
+    workspaceMount: output?.workspace?.workspaceMount ?? `type=bind,source=${workspace},target=${workspaceFolder}`,
+    workspaceFolder,
+    commands: languageCommandsFrom(config.customizations),
+    user: config.remoteUser ?? config.containerUser,
+    env: { ...config.containerEnv },
+  }
+}
+
+const images = new Map<string, Promise<string>>()
+
+export function imageName(workspace: string): string {
+  return `presmium-devcontainer-${createHash('sha256').update(workspace).digest('hex').slice(0, 12)}`
+}
+
+export function devcontainerImage(workspace: string, devcontainer: Devcontainer, options: BuildOptions = {}, signal?: AbortSignal, env?: Record<string, string>): Promise<string> {
+  const key = definitionStamp(devcontainer.configFile)
+  let image = images.get(key)
+  if (!image) {
+    const name = imageName(workspace)
+    const timeoutMs = options.buildTimeoutMs ?? DEFAULT_BUILD_TIMEOUT_MS
+    image = devcontainerCli(['build', '--workspace-folder', workspace, '--image-name', name], timeoutMs, signal, env).then((result) => {
+      if (result.timedOut) throw new Error(`stopped after ${timeoutMs} ms`)
+      const output = lastJson(result.stdout)
+      if (output?.outcome !== 'success') {
+        const detail = [output?.message, output?.description].filter(Boolean).join('\n') || result.stderr.trim().slice(-2000)
+        throw new Error(detail)
+      }
+      return name
+    })
+    image.catch(() => images.delete(key))
+    images.set(key, image)
+  }
+  return image
+}

package/src/node/docker.ts

@@ -0,0 +1,36 @@
+import { spawnSync } from 'node:child_process'
+import type { RunContext } from '@lincyaw/kernel'
+import { minimalRunEnv } from '@lincyaw/kernel/node'
+import { runProcess } from './process.ts'
+
+const DOCKER_CLIENT = ['DOCKER_HOST', 'DOCKER_CONTEXT', 'DOCKER_CONFIG', 'DOCKER_CERT_PATH', 'DOCKER_TLS_VERIFY', 'XDG_RUNTIME_DIR', 'HOME']
+
+/** The run's environment with the variables the Docker client needs to reach the daemon. */
+export function dockerEnv(ctx?: RunContext): Record<string, string> {
+  const env: Record<string, string> = { ...ctx?.env ?? minimalRunEnv() }
+  for (const name of DOCKER_CLIENT) {
+    const value = process.env[name]
+    if (value !== undefined) env[name] = value
+  }
+  return env
+}
+
+let docker: Promise<boolean> | undefined
+
+export function dockerAvailable(): Promise<boolean> {
+  if (!docker) {
+    const probe = runProcess('docker', ['version', '--format', '{{.Server.Version}}'], { timeoutMs: 10_000, env: dockerEnv() }).then(result => result.code === 0)
+    docker = probe
+    void probe.then((answers) => {
+      if (!answers && docker === probe) docker = undefined
+    })
+  }
+  return docker
+}
+
+let dockerSync: boolean | undefined
+
+export function isDockerAvailableSync(): boolean {
+  dockerSync ??= spawnSync('docker', ['version', '--format', '{{.Server.Version}}'], { stdio: 'ignore', timeout: 10_000, env: dockerEnv() }).status === 0
+  return dockerSync
+}

package/src/node/local-env.ts

@@ -0,0 +1,112 @@
+import { dirname, relative, resolve, sep } from 'node:path'
+import { componentCode, docBlocks } from '@lincyaw/kernel'
+import type { CodeNode, ComponentNode, DirectiveSpec, Executor, IRBlock, IRPass } from '@lincyaw/kernel'
+import { EXEC_LOCAL_ID, execLocalConfig, workspacePath } from '../domain/index.ts'
+import type { ContainerExecutor } from './container.ts'
+import { createContainerExecutor } from './container.ts'
+import { findDefinition } from './devcontainer.ts'
+import { inLanguage, text } from './messages.ts'
+import { replicateArchive } from './replicate.ts'
+
+/** The `:workspace:` each {local-env} names, resolved, for the workspace pass of the same compile. */
+const requestedWorkspaces = new WeakMap<ComponentNode, string>()
+
+export const localEnvDirective: DirectiveSpec = {
+  name: 'local-env',
+  arg: true,
+  body: true,
+  options: { file: 'string', workspace: 'string' },
+  toIR(input, ctx) {
+    const lang = input.arg?.trim() || 'python'
+    let file: string
+    try {
+      file = workspacePath(String(input.options.file ?? ''))
+    }
+    catch {
+      const message = '{local-env} needs :file:, the path of the snippet inside the workspace'
+      ctx.report({ checkId: 'presmium.execLocal.syntax', severity: 'error', message })
+      return { node: { type: 'markdown', mdast: ctx.parse(`> ${message}`) } }
+    }
+    const code: CodeNode = { type: 'code', lang, value: input.body.replace(/\n+$/, '') }
+    const node: ComponentNode = {
+      type: 'component',
+      plugin: EXEC_LOCAL_ID,
+      name: 'PmLocalEnv',
+      props: { file, lang, code: code.value },
+      children: [{ id: 'source', role: 'visual', at: 0, source: ctx.source, node: code }],
+      fallback: { type: 'root', children: [{ type: 'code', lang, value: code.value }] },
+    }
+    if (typeof input.options.workspace === 'string') requestedWorkspaces.set(node, resolve(dirname(ctx.file), input.options.workspace))
+    return { node }
+  },
+}
+
+const deckContainers = new Map<string, ContainerExecutor>()
+
+/** Each deck runs in its own workspace: the deck's container executor takes the place of the plugin's in the executors of this compile. */
+function bindDeckContainer(deckDir: string, executors: Executor[], pluginContainer: Executor): ContainerExecutor {
+  let container = deckContainers.get(deckDir)
+  if (!container) deckContainers.set(deckDir, container = createContainerExecutor(pluginContainer.id))
+  const at = executors.indexOf(pluginContainer)
+  if (at >= 0) executors[at] = container
+  return container
+}
+
+export function localEnvPass(pluginContainer: Executor): IRPass {
+  return {
+    name: 'presmium.execLocal.workspace',
+    run(doc, ctx) {
+      const envs = [...docBlocks(doc)].map(({ block }) => block)
+        .filter((block): block is IRBlock & { node: ComponentNode } => block.node.type === 'component' && block.node.plugin === EXEC_LOCAL_ID && block.node.name === 'PmLocalEnv')
+      const config = execLocalConfig(ctx.config)
+      const workspace = config.workspace !== undefined
+        ? resolve(ctx.deckDir, config.workspace)
+        : envs.map(env => requestedWorkspaces.get(env.node)).find(dir => dir !== undefined) ?? ctx.workspaceRoot
+      bindDeckContainer(ctx.deckDir, ctx.executors, pluginContainer).bind(workspace, config)
+      const shared = relative(ctx.deckDir, workspace).split(sep).join('/') || '.'
+      doc.config.presmium = { ...doc.config.presmium, [EXEC_LOCAL_ID]: { ...ctx.config, workspace: shared } }
+      const named = (dir: string) => relative(ctx.deckDir, dir).split(sep).join('/') || '.'
+
+      for (const { node, source, stepStates } of envs) {
+        const dir = requestedWorkspaces.get(node) ?? workspace
+        const at = { file: source.file, line: source.line }
+        const code = componentCode(node)
+        if (!code || node.children?.filter(child => child.node.type === 'code').length !== 1) {
+          ctx.report({ checkId: EXEC_LOCAL_ID, severity: 'error', message: inLanguage(ctx.lang, () => text().codeChild), source })
+          continue
+        }
+        node.props.code = code.value
+        node.props.lang = code.lang
+        delete node.props.archive
+        delete node.props.devcontainer
+        for (const state of stepStates ?? []) if (state.parameters) {
+          for (const key of ['code', 'lang', 'archive', 'devcontainer']) delete state.parameters[key]
+        }
+        if (dir !== workspace) {
+          ctx.report({
+            checkId: 'presmium.execLocal.workspace',
+            severity: 'error',
+            message: `{local-env} names the workspace ${named(dir)}, but the deck's workspace is ${named(workspace)}: the snippet would run in ${named(workspace)}`,
+            hint: 'give every {local-env} of the deck the same :workspace:, or set presmium.execLocal.workspace',
+            source: at,
+          })
+        }
+        const definition = findDefinition(dir)
+        if (!definition) {
+          ctx.report({
+            checkId: 'presmium.execLocal.devcontainer',
+            severity: 'warning',
+            message: `no devcontainer definition in ${named(dir)}; the snippet cannot be run in a container or exported`,
+            source: at,
+          })
+          continue
+        }
+        const file = String(node.props.file)
+        const request = { file, content: `${code.value}\n`, lang: String(node.props.lang) }
+        const { zip } = inLanguage(ctx.lang, () => replicateArchive(dir, definition, request))
+        node.props.devcontainer = relative(dir, definition).split(sep).join('/')
+        node.props.archive = Buffer.from(zip).toString('base64')
+      }
+    },
+  }
+}