@deckbuilderkit/terminal 0.0.0-stage → 0.1.1

package/src/server/integration/pwsh.ps1

@@ -0,0 +1,40 @@
+# DeckBuilder shell integration for PowerShell and pwsh, run after the user's profile.
+# Wraps the existing prompt with OSC 133 marks and OSC 7; PSReadLine's ReadLine gets the C mark.
+if (-not $global:__dbSi) {
+  $global:__dbSi = $true
+  $global:__dbFirst = $true
+  $global:__dbUserPrompt = $function:prompt
+  function global:prompt {
+    $ok = $?
+    $code = $global:LASTEXITCODE
+    $e = [char]27
+    $a = [char]7
+    $out = ''
+    if (-not $global:__dbFirst) {
+      $ec = if ($ok) { 0 } elseif ($code -is [int] -and $code -ne 0) { $code } else { 1 }
+      $out += "$e]133;D;$ec$a"
+    }
+    $global:__dbFirst = $false
+    $loc = $executionContext.SessionState.Path.CurrentLocation
+    if ($loc.Provider.Name -eq 'FileSystem') {
+      $p = $loc.ProviderPath -replace '\', '/'
+      if ($p -match '^[A-Za-z]:') { $p = '/' + $p }
+      if ($p -match '^/[^/]') {
+        $hostName = if ($env:COMPUTERNAME) { $env:COMPUTERNAME } else { 'localhost' }
+        $out += "$e]7;file://$hostName$($p.Replace('%', '%25'))$a"
+      }
+    }
+    $out += "$e]133;A$a"
+    $inner = if ($global:__dbUserPrompt) { & $global:__dbUserPrompt } else { "PS $loc$('>' * ($nestedPromptLevel + 1)) " }
+    $global:LASTEXITCODE = $code
+    "$out$inner$e]133;B$a"
+  }
+  if (Get-Command PSConsoleHostReadLine -ErrorAction SilentlyContinue) {
+    $global:__dbUserReadLine = $function:PSConsoleHostReadLine
+    function global:PSConsoleHostReadLine {
+      $line = & $global:__dbUserReadLine
+      [Console]::Write("$([char]27)]133;C$([char]7)")
+      $line
+    }
+  }
+}

package/src/server/integration/scripts.d.ts

@@ -0,0 +1,16 @@
+declare module '*.sh' {
+  const text: string;
+  export default text;
+}
+declare module '*.zsh' {
+  const text: string;
+  export default text;
+}
+declare module '*.fish' {
+  const text: string;
+  export default text;
+}
+declare module '*.ps1' {
+  const text: string;
+  export default text;
+}

package/src/server/integration/zsh-forward.zsh

@@ -0,0 +1,7 @@
+# DeckBuilder shell integration for zsh: forwards __DB_FILE__ to the user's ZDOTDIR.
+__db_ours=$ZDOTDIR
+ZDOTDIR=${DECKBUILDER_USER_ZDOTDIR:-$HOME}
+[[ -r $ZDOTDIR/__DB_FILE__ ]] && source $ZDOTDIR/__DB_FILE__
+DECKBUILDER_USER_ZDOTDIR=$ZDOTDIR
+[[ __DB_FILE__ != .zlogin ]] && ZDOTDIR=$__db_ours
+unset __db_ours

package/src/server/integration/zshrc.zsh

@@ -0,0 +1,22 @@
+# DeckBuilder shell integration for zsh: the .zshrc in the integration ZDOTDIR.
+# Sources the user's .zshrc, then adds precmd/preexec hooks for OSC 133 marks and OSC 7.
+__db_ours=$ZDOTDIR
+ZDOTDIR=${DECKBUILDER_USER_ZDOTDIR:-$HOME}
+[[ -r $ZDOTDIR/.zshrc ]] && source $ZDOTDIR/.zshrc
+DECKBUILDER_USER_ZDOTDIR=$ZDOTDIR
+# A login shell still reads .zlogin from here; that one restores the user's ZDOTDIR.
+[[ -o login ]] && ZDOTDIR=$__db_ours
+unset __db_ours
+
+__db_first=1
+__db_ec=0
+__db_status() { __db_ec=$? }
+__db_precmd() {
+  [[ -z $__db_first ]] && printf '\e]133;D;%s\a' $__db_ec
+  __db_first=
+  printf '\e]7;file://%s%s\a' ${HOST:-localhost} ${PWD//\%/%25}
+  [[ $PS1 == *'133;B'* ]] || PS1=$'%{\e]133;A\a%}'$PS1$'%{\e]133;B\a%}'
+}
+__db_preexec() { printf '\e]133;C\a' }
+precmd_functions=(__db_status $precmd_functions __db_precmd)
+preexec_functions=($preexec_functions __db_preexec)

package/src/server/integration.ts

@@ -0,0 +1,107 @@
+/// <reference path="./integration/scripts.d.ts" />
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ShellId } from '../protocol.ts';
+// Text imports: `bun build --compile` inlines them, so the exe carries the scripts and writes them out at runtime.
+import bashScript from './integration/bash.sh' with { type: 'text' };
+import fishScript from './integration/fish.fish' with { type: 'text' };
+import pwshScript from './integration/pwsh.ps1' with { type: 'text' };
+import zshForward from './integration/zsh-forward.zsh' with { type: 'text' };
+import zshrcScript from './integration/zshrc.zsh' with { type: 'text' };
+
+/** Shells that get an integration script. */
+export type IntegratedShell = 'bash' | 'git-bash' | 'zsh' | 'fish' | 'powershell' | 'pwsh' | 'cmd';
+
+const lf = (s: string) => s.replace(/\r\n/g, '\n');
+
+/** Files written under the integration dir: relative path → content. */
+export function integrationFiles(): Record<string, string> {
+  const files: Record<string, string> = {
+    'bash.sh': lf(bashScript),
+    'fish.fish': lf(fishScript),
+    'pwsh.ps1': pwshScript.replace(/\r?\n/g, '\r\n'),
+    'zsh/.zshrc': lf(zshrcScript),
+  };
+  for (const name of ['.zshenv', '.zprofile', '.zlogin']) files[`zsh/${name}`] = lf(zshForward).replaceAll('__DB_FILE__', name);
+  return files;
+}
+
+const written = new Set<string>();
+
+/** Writes the scripts to `dir` once per process (rewriting any that differ). */
+export function ensureIntegrationFiles(dir: string): void {
+  if (written.has(dir)) return;
+  for (const [rel, content] of Object.entries(integrationFiles())) {
+    const path = join(dir, rel);
+    let current: string | null = null;
+    try {
+      current = readFileSync(path, 'utf8');
+    } catch {}
+    if (current === content) continue;
+    mkdirSync(join(path, '..'), { recursive: true });
+    writeFileSync(path, content);
+  }
+  written.add(dir);
+}
+
+/** The integrated shell an argv runs: the profile's shell id, or for `auto` the executable's name. */
+export function integratedShell(id: ShellId | 'custom', argv: string[]): IntegratedShell | null {
+  let kind: string = id;
+  if (id === 'auto') {
+    const exe = argv[0] ?? '';
+    kind = exe
+      .slice(Math.max(exe.lastIndexOf('/'), exe.lastIndexOf('\\')) + 1)
+      .toLowerCase()
+      .replace(/\.exe$/, '');
+  }
+  switch (kind) {
+    case 'bash':
+    case 'git-bash':
+    case 'zsh':
+    case 'fish':
+    case 'powershell':
+    case 'pwsh':
+    case 'cmd':
+      return kind;
+    default:
+      return null;
+  }
+}
+
+/** Forward slashes: Windows shells and Git Bash accept them, and they need no escaping. */
+const slashes = (p: string) => p.replace(/\\/g, '/');
+
+const LOGIN_FLAGS = new Set(['-l', '--login', '-i']);
+
+/**
+ * Argv and env that load the integration script for `shell` (files already in `dir`).
+ * `env` is the env the session would get otherwise; the result merges into it.
+ */
+export function withIntegration(
+  shell: IntegratedShell,
+  argv: string[],
+  dir: string,
+  env: Record<string, string | undefined>,
+): { argv: string[]; env: Record<string, string> } {
+  const [exe = '', ...args] = argv;
+  switch (shell) {
+    case 'bash':
+    case 'git-bash':
+      // --rcfile is ignored by login shells; the script sources the login files itself.
+      return { argv: [exe, '--rcfile', slashes(join(dir, 'bash.sh')), ...args.filter((a) => !LOGIN_FLAGS.has(a)), '-i'], env: {} };
+    case 'zsh':
+      return { argv, env: { ZDOTDIR: join(dir, 'zsh'), DECKBUILDER_USER_ZDOTDIR: env.ZDOTDIR ?? '' } };
+    case 'fish':
+      return { argv: [...argv, '--init-command', `source '${join(dir, 'fish.fish').replace(/[\\']/g, '\\$&')}'`], env: {} };
+    case 'powershell':
+    case 'pwsh': {
+      // A script block from the file text: dot-sourcing the file itself would fail under the Restricted policy.
+      const path = join(dir, 'pwsh.ps1').replace(/'/g, "''");
+      return { argv: [...argv, '-NoExit', '-Command', `. ([scriptblock]::Create([IO.File]::ReadAllText('${path}')))`], env: {} };
+    }
+    case 'cmd': {
+      const user = env.PROMPT || '$P$G';
+      return { argv, env: { PROMPT: `$E]133;D$E\\$E]7;file://localhost/$P$E\\$E]133;A$E\\${user}$E]133;B$E\\` } };
+    }
+  }
+}

package/src/server/launchers.ts

@@ -0,0 +1,70 @@
+export const LAUNCHER_ID = /^[a-z][a-z0-9-]{0,31}$/;
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export const isUuid = (x: unknown): x is string => typeof x === 'string' && UUID.test(x);
+
+export const isLauncherId = (x: unknown): x is string => typeof x === 'string' && LAUNCHER_ID.test(x);
+
+/**
+ * A program other than the shell that the client may start by id. The client never sends a program:
+ * it sends a launcher id plus args, and only `command` builds the argv.
+ *
+ * `parse` is the security boundary. Accept only values with a fixed shape (ids, enums, UUIDs) and
+ * return null for anything else; never pass free text through, since it could end up as a flag.
+ */
+export interface Launcher<A> {
+  label: string;
+  /** Validates untrusted client args; null = invalid. Accept only fixed-shape values, never free text. */
+  parse(args: unknown): A | null;
+  command(args: A, ctx: { shell: string[] }): string[];
+  env?(args: A): Record<string, string>;
+  meta?(args: A): Record<string, unknown>;
+  available?(): boolean;
+}
+
+export interface ResolvedLaunch {
+  cmd: string[];
+  env: Record<string, string>;
+  label: string;
+  meta: Record<string, unknown>;
+  launcher: string;
+}
+
+export interface Launchers {
+  resolve(id: unknown, args: unknown, ctx: { shell: string[] }): ResolvedLaunch | null;
+  list(): Array<{ id: string; label: string }>;
+}
+
+const isArgv = (x: unknown): x is string[] => Array.isArray(x) && x.length > 0 && x.every((s) => typeof s === 'string');
+
+export function launchers(map: Record<string, Launcher<any>>): Launchers {
+  const registry = new Map<string, Launcher<any>>();
+  for (const id of Object.keys(map)) {
+    if (!isLauncherId(id)) throw new Error(`Invalid launcher id: ${JSON.stringify(id)}`);
+    registry.set(id, map[id]!);
+  }
+  const isAvailable = (l: Launcher<unknown>): boolean => l.available?.() !== false;
+
+  return {
+    resolve(id, args, ctx) {
+      if (!isLauncherId(id)) return null;
+      const launcher = registry.get(id);
+      if (!launcher || !isAvailable(launcher)) return null;
+      const parsed = launcher.parse(args);
+      if (parsed === null) return null;
+      const cmd: unknown = launcher.command(parsed, ctx);
+      if (!isArgv(cmd)) return null;
+      return {
+        cmd: [...cmd],
+        env: launcher.env?.(parsed) ?? {},
+        label: launcher.label,
+        meta: launcher.meta?.(parsed) ?? {},
+        launcher: id,
+      };
+    },
+    list() {
+      return [...registry].filter(([, l]) => isAvailable(l)).map(([id, l]) => ({ id, label: l.label }));
+    },
+  };
+}

package/src/server/profiles.ts

@@ -0,0 +1,40 @@
+import { posix, win32 } from 'node:path';
+import { isShellId, SHELL_ICONS, SHELL_IDS, SHELL_NAMES, type TerminalProfile, type TerminalProfileInfo } from '../protocol.ts';
+import { resolveShell, type ShellLookup } from './shells.ts';
+
+/** Fields a saved entry with a built-in id may override. */
+const OVERRIDABLE = ['name', 'icon', 'args', 'env', 'cwd', 'hidden', 'shellIntegration', 'appearance'] as const;
+
+/** Argv a profile runs on this machine; null when its shell or command is missing. */
+export function profileArgv(p: TerminalProfile, lookup: ShellLookup): string[] | null {
+  const args = p.args ?? [];
+  if (p.shell === 'custom') {
+    const abs = lookup.platform === 'win32' ? win32.isAbsolute : posix.isAbsolute;
+    if (!p.command || !abs(p.command) || !lookup.exists(p.command)) return null;
+    return [p.command, ...args];
+  }
+  if (!isShellId(p.shell)) return null;
+  const base = resolveShell(p.shell, lookup);
+  return base ? [...base, ...args] : null;
+}
+
+/**
+ * Built-in profiles (installed shells, with saved overrides applied), then the saved custom ones.
+ * Overrides of a shell not installed here are left out; custom profiles always appear, with `available`.
+ */
+export function mergeProfiles(saved: TerminalProfile[], lookup: ShellLookup): TerminalProfileInfo[] {
+  const byId = new Map(saved.map((p) => [p.id, p]));
+  const out: TerminalProfileInfo[] = [];
+  for (const id of SHELL_IDS) {
+    if (id === 'auto' || !resolveShell(id, lookup)) continue;
+    const p: TerminalProfileInfo = { id, name: SHELL_NAMES[id], shell: id, icon: SHELL_ICONS[id], available: true };
+    const o = byId.get(id);
+    if (o) for (const k of OVERRIDABLE) if (o[k] !== undefined) (p as unknown as Record<string, unknown>)[k] = o[k];
+    out.push(p);
+  }
+  for (const p of saved) {
+    if (isShellId(p.id)) continue;
+    out.push({ ...p, available: profileArgv(p, lookup) !== null });
+  }
+  return out;
+}

package/src/server/pty.ts

@@ -0,0 +1,75 @@
+import { killTree } from '@deckbuilderkit/platform';
+
+export interface Pty {
+  write(data: string | Uint8Array): void;
+  resize(cols: number, rows: number): void;
+  kill(): void;
+  onData(cb: (data: Uint8Array) => void): void;
+  onExit(cb: (code: number | null) => void): void;
+}
+
+/** One backend for every platform: Bun's built-in terminal (a PTY, ConPTY on Windows). */
+export function spawnPty(
+  cmd: string[],
+  cwd: string,
+  cols: number,
+  rows: number,
+  env?: Record<string, string>,
+): Pty {
+  const dataCbs: Array<(data: Uint8Array) => void> = [];
+  const exitCbs: Array<(code: number | null) => void> = [];
+  // Output that arrives before the owner subscribes (the shell's first prompt) is kept.
+  let pending: Uint8Array[] | null = [];
+  let exitCode: number | null | undefined;
+
+  const proc = Bun.spawn(cmd, {
+    cwd,
+    env: { ...process.env, ...env, TERM: 'xterm-256color', COLORTERM: 'truecolor' },
+    windowsHide: true,
+    terminal: {
+      cols,
+      rows,
+      data(_terminal, data) {
+        if (pending) pending.push(data);
+        else for (const cb of dataCbs) cb(data);
+      },
+    },
+  });
+
+  proc.exited.then(
+    (code) => finish(code),
+    () => finish(null),
+  );
+
+  function finish(code: number | null): void {
+    if (exitCode !== undefined) return;
+    exitCode = code;
+    for (const cb of exitCbs) cb(code);
+  }
+
+  return {
+    write(data) {
+      if (!proc.terminal?.closed) proc.terminal?.write(data);
+    },
+    resize(c, r) {
+      if (!proc.terminal?.closed) proc.terminal?.resize(c, r);
+    },
+    kill() {
+      if (exitCode === undefined) killTree(proc.pid);
+      // A plain kill leaves `claude.cmd`'s node holding the PTY; closing it releases the pipe.
+      if (!proc.terminal?.closed) proc.terminal?.close();
+    },
+    onData(cb) {
+      dataCbs.push(cb);
+      if (pending) {
+        const queued = pending;
+        pending = null;
+        for (const chunk of queued) for (const c of dataCbs) c(chunk);
+      }
+    },
+    onExit(cb) {
+      exitCbs.push(cb);
+      if (exitCode !== undefined) cb(exitCode);
+    },
+  };
+}

package/src/server/routes.ts

@@ -0,0 +1,232 @@
+import { AppError, invalid, isRecord, notFound, socketTickets, type Routes, type SocketData, type SocketRoutes } from '@deckbuilderkit/server-core';
+import type { ServerWebSocket } from 'bun';
+import { existsSync, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join, posix, win32 } from 'node:path';
+import { decodeClientMessage, MAX_COLS, MAX_ROWS, TERMINAL_SOCKET_PATH, type TerminalProfile, type TerminalProfileInfo } from '../protocol.ts';
+import { ensureIntegrationFiles, integratedShell, withIntegration } from './integration.ts';
+import type { Launchers } from './launchers.ts';
+import { mergeProfiles, profileArgv } from './profiles.ts';
+import { availableShells, isShellId, resolveShell, type ShellId, type ShellLookup } from './shells.ts';
+import type { Sink, TerminalSessions, ViewKind } from './sessions.ts';
+
+/** Sockets with more than this queued are closed with BACKPRESSURE_CLOSE instead of buffering without bound. */
+export const MAX_BUFFERED = 1024 * 1024;
+export const BACKPRESSURE_CLOSE = 4001;
+
+export interface TerminalRoutesOptions {
+  sessions: TerminalSessions;
+  /** The configured shell id (the `terminal.shell` setting); anything but a known id means `auto`. */
+  shell: () => Promise<string>;
+  /** Resolves a project root id and relative path to an existing directory, or throws. Required for `root`. */
+  resolveCwd?: (root: string, path: string) => Promise<string>;
+  launchers?: Launchers;
+  /** The saved `terminal.profiles` (overrides of built-ins and custom profiles). */
+  profiles?: () => Promise<TerminalProfile[]>;
+  /** Profile id used when `open` names none; '' or unknown falls back to `shell`. */
+  defaultProfile?: () => Promise<string>;
+  /** Start directory when neither the request nor the profile gives one (`~` = home). */
+  defaultCwd?: () => Promise<string>;
+  /** The `terminal.shellIntegration` setting; integration is on unless this resolves false. */
+  shellIntegration?: () => Promise<boolean>;
+  /** Where the integration scripts are written (default: a folder in the temp dir). */
+  integrationDir?: string;
+  /** Where shells are looked up; tests replace it. */
+  lookup?: ShellLookup;
+  /** Directory check for cwd candidates; tests replace it. */
+  isDir?: (path: string) => boolean;
+}
+
+interface Ticket {
+  session: string;
+  view: ViewKind;
+}
+
+const badRequest = () => invalid('badRequest', 'Invalid request.');
+
+function size(v: unknown, max: number): number {
+  if (typeof v !== 'number' || !Number.isInteger(v) || v < 1 || v > max) throw badRequest();
+  return v;
+}
+
+function sessionId(b: Record<string, unknown>): string {
+  if (typeof b.session !== 'string' || !b.session) throw badRequest();
+  return b.session;
+}
+
+export function terminalRoutes(opts: TerminalRoutesOptions): { routes: Routes; sockets: SocketRoutes } {
+  const { sessions } = opts;
+  const lookup: ShellLookup = opts.lookup ?? { platform: process.platform, env: process.env, exists: existsSync };
+  const tickets = socketTickets<Ticket>();
+
+  const isDir = opts.isDir ?? ((p: string) => {
+    try {
+      return statSync(p).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+  const abs = lookup.platform === 'win32' ? win32.isAbsolute : posix.isAbsolute;
+  const integrationDir = opts.integrationDir ?? join(tmpdir(), 'deckbuilder-shell-integration');
+
+  async function pickShell(): Promise<{ id: ShellId; argv: string[] }> {
+    const configured = await opts.shell();
+    const id = isShellId(configured) ? configured : 'auto';
+    const argv = resolveShell(id, lookup);
+    if (argv) return { id, argv };
+    const fallback = resolveShell('auto', lookup);
+    if (!fallback) throw invalid('terminalNoShell', 'No shell found on this machine.');
+    return { id: 'auto', argv: fallback };
+  }
+
+  const listProfiles = async () => mergeProfiles((await opts.profiles?.()) ?? [], lookup);
+
+  /** The requested profile, else the default profile, else the `shell` setting (no profile). */
+  async function pickProfile(requested: string | undefined): Promise<{ id: ShellId | 'custom'; argv: string[]; profile?: TerminalProfileInfo }> {
+    const all = requested !== undefined || opts.defaultProfile ? await listProfiles() : [];
+    if (requested !== undefined) {
+      const profile = all.find((p) => p.id === requested);
+      if (!profile) throw invalid('terminalProfile', 'Unknown terminal profile.');
+      const argv = profileArgv(profile, lookup);
+      if (!argv) throw invalid('terminalNoShell', 'The profile shell is not on this machine.');
+      return { id: profile.shell, argv, profile };
+    }
+    const fallbackId = await opts.defaultProfile?.();
+    const profile = fallbackId ? all.find((p) => p.id === fallbackId) : undefined;
+    const argv = profile && profileArgv(profile, lookup);
+    if (profile && argv) return { id: profile.shell, argv, profile };
+    return pickShell();
+  }
+
+  /** An absolute existing directory from `p` (`~` = home), or null. */
+  function dirOf(p: string | undefined): string | null {
+    if (!p) return null;
+    const expanded = p === '~' || p.startsWith('~/') || p.startsWith('~\\') ? homedir() + p.slice(1) : p;
+    return abs(expanded) && isDir(expanded) ? expanded : null;
+  }
+
+  /** root/path > dir > profile cwd > defaultCwd > home. */
+  async function cwdOf(b: Record<string, unknown>, profile: TerminalProfileInfo | undefined): Promise<string> {
+    const { root, path } = b;
+    if (root !== undefined) {
+      if (typeof root !== 'string' || (path !== undefined && typeof path !== 'string')) throw badRequest();
+      if (!opts.resolveCwd) throw invalid('notADirectory', 'Working directories are not available.');
+      return opts.resolveCwd(root, path ?? '');
+    }
+    return dirOf(b.dir as string | undefined) ?? dirOf(profile?.cwd) ?? dirOf(await opts.defaultCwd?.()) ?? homedir();
+  }
+
+  const routes: Routes = {
+    'POST /api/terminal/open': async ({ json }) => {
+      const b = await json<Record<string, unknown>>();
+      const cols = size(b.cols, MAX_COLS);
+      const rows = size(b.rows, MAX_ROWS);
+      if (b.launch !== undefined && (!isRecord(b.launch) || typeof b.launch.id !== 'string')) throw badRequest();
+      if (b.profile !== undefined && typeof b.profile !== 'string') throw badRequest();
+      if (b.dir !== undefined && typeof b.dir !== 'string') throw badRequest();
+      const shell = await pickProfile(b.profile as string | undefined);
+      const profile = shell.profile;
+      let cmd = shell.argv;
+      let label: string = profile?.name ?? (shell.id === 'auto' ? 'shell' : shell.id);
+      let env: Record<string, string> | undefined = profile?.env;
+      let launcher: string | undefined;
+      let meta: Record<string, unknown> | undefined;
+      let shellId: string | undefined = shell.id;
+      if (b.launch !== undefined) {
+        const resolved = opts.launchers?.resolve((b.launch as Record<string, unknown>).id, (b.launch as Record<string, unknown>).args, {
+          shell: shell.argv,
+        });
+        if (!resolved) throw invalid('terminalLauncher', 'Unknown or invalid launcher.');
+        ({ cmd, env, label, meta, launcher } = resolved);
+        shellId = undefined;
+      } else {
+        const kind = shell.id === 'custom' ? null : integratedShell(shell.id, cmd);
+        if (kind && profile?.shellIntegration !== false && (await opts.shellIntegration?.()) !== false) {
+          ensureIntegrationFiles(integrationDir);
+          const injected = withIntegration(kind, cmd, integrationDir, { ...lookup.env, ...env });
+          cmd = injected.argv;
+          env = { ...env, ...injected.env };
+        }
+      }
+      const cwd = await cwdOf(b, launcher ? undefined : profile);
+      const session = sessions.create({ cmd, cwd, cols, rows, env, label, launcher, meta, profile: launcher ? undefined : profile?.id, shell: shellId });
+      return { session: session.id, ticket: tickets.issue({ session: session.id, view: 'interactive' }) };
+    },
+
+    'POST /api/terminal/attach': async ({ json }) => {
+      const b = await json<Record<string, unknown>>();
+      const id = sessionId(b);
+      if (b.view !== undefined && b.view !== 'interactive' && b.view !== 'preview') throw badRequest();
+      if (!sessions.get(id)) throw notFound('terminalSession', 'No such terminal session');
+      return { session: id, ticket: tickets.issue({ session: id, view: b.view ?? 'interactive' }) };
+    },
+
+    'POST /api/terminal/close': async ({ json }) => {
+      sessions.close(sessionId(await json<Record<string, unknown>>()));
+      return { ok: true };
+    },
+
+    'POST /api/terminal/label': async ({ json }) => {
+      const b = await json<Record<string, unknown>>();
+      if (typeof b.label !== 'string') throw badRequest();
+      sessions.setLabel(sessionId(b), b.label);
+      return { ok: true };
+    },
+
+    'GET /api/terminal/sessions': () => sessions.list(),
+    'GET /api/terminal/shells': () => availableShells(lookup),
+    'GET /api/terminal/profiles': () => listProfiles(),
+    'GET /api/terminal/launchers': () => opts.launchers?.list() ?? [],
+  };
+
+  const sinks = new WeakMap<ServerWebSocket<SocketData>, { session: string; sink: Sink }>();
+
+  const sockets: SocketRoutes = {
+    [TERMINAL_SOCKET_PATH]: {
+      tickets,
+      open(ws, { session, view }: Ticket) {
+        const sink: Sink = {
+          send(frame) {
+            if (ws.getBufferedAmount() > MAX_BUFFERED) {
+              sessions.detach(session, sink);
+              ws.close(BACKPRESSURE_CLOSE, 'backpressure');
+              return;
+            }
+            ws.send(frame);
+          },
+          close: () => ws.close(),
+        };
+        sinks.set(ws, { session, sink });
+        try {
+          sessions.attach(session, sink, view);
+        } catch (e) {
+          sinks.delete(ws);
+          if (!(e instanceof AppError) || e.code !== 'terminalSession') {
+            console.error('terminal attach failed', e);
+            ws.close(1011, 'error');
+            return;
+          }
+          ws.close(1008, 'noSession');
+        }
+      },
+      message(ws, msg) {
+        const attached = sinks.get(ws);
+        if (!attached) return;
+        const decoded = decodeClientMessage(msg);
+        if (!decoded) return;
+        if (decoded.kind === 'input') sessions.write(attached.session, attached.sink, decoded.data);
+        else if (decoded.msg.type === 'resize') sessions.resize(attached.session, attached.sink, decoded.msg.cols, decoded.msg.rows);
+        else if (decoded.msg.type === 'clear') sessions.clear(attached.session, attached.sink);
+        else sessions.close(attached.session, attached.sink);
+      },
+      close(ws) {
+        const attached = sinks.get(ws);
+        if (!attached) return;
+        sinks.delete(ws);
+        sessions.detach(attached.session, attached.sink);
+      },
+    },
+  };
+
+  return { routes, sockets };
+}