@spunto/build 0.4.0 → 0.5.0

package/README.md

@@ -148,6 +148,29 @@ time a vendor reshuffles a field.
 Here for the reason that inverts the rest of the package: **nothing has forked this yet.** Putting
 it in the shared package now costs nothing and means the second product never writes its own.
 
+### `@spunto/build/terminal` — the half of a persistent terminal that is a string
+
+A worker's terminal is an exec attached to a session that outlives it, so closing a browser tab
+doesn't kill a build. The attaching is I/O and stays with whoever owns the Docker socket; the shell
+that gets attached, the layout it writes into, and the parsing of what it prints back are here.
+
+```ts
+import { sanitizeSessionName, buildDtachCommand, parseSessionList } from "@spunto/build/terminal"
+
+const name = sanitizeSessionName(fromQuery)        // every name MUST come through this
+await exec(container, ["/bin/sh", "-c", buildDtachCommand()], { env: { MP_TERM_SESSION: name } })
+```
+
+**dtach, not tmux.** tmux's only knob for "the wheel scrolls history" is `mouse on`, which also
+makes it swallow every drag — the frontend then has to forge Shift-drags to get a native selection
+back. dtach does only persistence, so the emulator keeps the mouse, its scrollback and its search.
+What dtach doesn't do is remember the screen, so the session is recorded inside the container with
+`script(1)` and the tail replayed on attach.
+
+`sanitizeSessionName` is a security boundary, not tidiness: names are interpolated into the shell
+scripts this module builds, so anything that doesn't come through it is a command injection into
+someone's container.
+
 ## The rule
 
 A module belongs in this package only if it imports **no** ORM schema, **no** HTTP framework, **no**
@@ -163,10 +186,11 @@ installed on its behalf. Import `./spec` without zod and resolution fails loudly
 right trade for not taxing every other entry point.
 
 Concretely: **no platform I/O**. No database, no Docker socket, no WebSocket. This package produces
-strings and parses strings; its only network call is outbound HTTP to a public extension registry,
-with no platform credential attached. Configuration arrives as function parameters — never read from
-the environment — so that one control plane can scope a setting per organization and another per
-process without either shape leaking in here.
+strings and parses strings. Its only network calls are outbound HTTP on the caller's behalf — a
+public extension registry, and a model vendor's catalogue endpoint when you hand
+`resolveContextWindow` a credential — and it holds no credential of its own. Configuration arrives
+as function parameters, never read from the environment, so that one control plane can scope a
+setting per organization and another per process without either shape leaking in here.
 
 That rule is what makes the package testable, safe to import from a node agent as well as from an
 API, and the reason it can't simply be folded into the design system: a script generator needs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/build",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Spunto's shared Build engine \u2014 the devcontainer image protocol and VS Code extension registry clients, with no database, no HTTP framework and no UI.",
   "type": "module",
   "license": "MIT",
@@ -55,6 +55,10 @@
       "types": "./src/script/index.ts",
       "import": "./src/script/index.ts"
     },
+    "./terminal": {
+      "types": "./src/terminal/index.ts",
+      "import": "./src/terminal/index.ts"
+    },
     "./agent-stream": {
       "types": "./src/agent-stream/index.ts",
       "import": "./src/agent-stream/index.ts"

package/src/agent-stream/index.ts

@@ -39,4 +39,16 @@ export type {
   UsageInput,
 } from "./agent-stream"
 
-export { contextWindowOf } from "./model-window"
+// Model context windows. `liveContextWindow`/`resolveContextWindow` take a credential as a
+// *parameter* and ask the model vendor's own API — the package still reads no environment and
+// holds no key of its own, but it is the one place here that talks to something other than a
+// public registry, and it does so on the caller's behalf. `resetModelWindowCache` exists for
+// tests: the lookup memoises per process.
+export {
+  apiModelId,
+  contextWindowOf,
+  liveContextWindow,
+  resetModelWindowCache,
+  resolveContextWindow,
+} from "./model-window"
+export type { ModelCredential } from "./model-window"

package/src/index.ts

@@ -12,4 +12,5 @@ export * from "./spec/index"
 export * from "./types/index"
 export * from "./catalogs/index"
 export * from "./script/index"
+export * from "./terminal/index"
 export * from "./agent-stream/index"

package/src/terminal/dtach.ts

@@ -0,0 +1,302 @@
+// The half of a persistent terminal that is a string, not a socket.
+//
+// A worker's terminal is a `docker exec` attached to a session that outlives it — so that closing a
+// browser tab does not kill a build. The *attaching* is I/O and stays with whoever owns the Docker
+// socket; everything here is the shell that gets attached, the layout it writes into, and the
+// parsing of what it prints back.
+//
+// **dtach, not tmux** (RFC 0019). tmux is a full multiplexer, and its only knob for "the wheel
+// scrolls history" is `mouse on` — which also makes tmux swallow every drag, so the frontend has to
+// forge Shift-drags to get a native selection back. dtach does only persistence: it owns a pty,
+// lets clients attach and detach, and forwards every byte, mouse included. The terminal emulator
+// keeps the mouse, its own scrollback and its own search.
+//
+// What dtach does not do is remember what was on screen. `-r winch` makes the running program
+// redraw on attach, but the history is gone. So the session is recorded inside the container with
+// script(1) and the tail of that recording is replayed just before attaching:
+//
+//   docker exec ──> sh ──> [replay: tail of the log] ──> exec dtach -A ──> script -f log ──> $SHELL
+//                                                             │
+//                                                    persistent master
+//
+// Recording inside the container rather than in an agent-side ring buffer is what makes the buffer
+// survive a control-plane restart with nothing permanently attached.
+
+/**
+ * Where a session's socket and recording live. One directory, two files per session.
+ *
+ * The name deliberately avoids the substring "dtach": the listing and kill scripts match processes
+ * by the socket path, and a path containing "dtach" would make every helper's own shell look like a
+ * dtach process to its own grep.
+ */
+export const TERMINAL_DIR = "/tmp/spunto-term"
+
+/** Bytes of recording replayed on attach. ~64 lines of 120 cols is 8 KB; 256 KB is a few screens of a chatty build. */
+export const REPLAY_BYTES = 262144
+
+/**
+ * Below this there is nothing worth replaying: a session created from a "+" button has already
+ * recorded its prompt, and replaying that would greet the user with a "replay" banner on a terminal
+ * they just opened. The attach redraw paints the prompt anyway.
+ */
+export const REPLAY_MIN_BYTES = 512
+
+/** Above this, the recording is trimmed to `TRIM_TO` bytes on the next attach. */
+export const MAX_LOG_BYTES = 4194304
+export const TRIM_TO = 1048576
+
+/**
+ * Session name a control plane may safely interpolate into the shell scripts below.
+ *
+ * Restricted to `[A-Za-z0-9_-]` — which is both what a socket filename can hold without quoting and
+ * what the listing script's `awk` can match on. **Every name reaching the builders below must come
+ * through here**: they interpolate it into shell, so anything else is an injection.
+ */
+export function sanitizeSessionName(name: string | undefined): string {
+  const cleaned = (name ?? "main").replace(/[^A-Za-z0-9_-]/g, "-").replace(/^-+|-+$/g, "").slice(0, 40)
+  return cleaned || "main"
+}
+
+export function buildDtachCommand(): string {
+  return [
+    `D=${TERMINAL_DIR}`,
+    'N="$MP_TERM_SESSION"',
+    'SOCK="$D/$N.sock"',
+    'LOG="$D/$N.log"',
+    'mkdir -p "$D" 2>/dev/null; chmod 700 "$D" 2>/dev/null',
+    '_SH=$(getent passwd "$(id -un)" 2>/dev/null | cut -d: -f7); _SH=${_SH:-/bin/bash}',
+    // No dtach → say so plainly and degrade to a non-persistent shell.
+    "if ! command -v dtach >/dev/null 2>&1; then",
+    `  printf '\\033[33m[spunto] dtach absent de ce conteneur — shell simple, sans persistance.\\033[0m\\r\\n'`,
+    '  exec "$_SH" -l',
+    "fi",
+    // A session is live only if some process still holds its socket: a leftover
+    // socket file (container restarted, program exited) means the recorded log
+    // belongs to a session that no longer exists, so it is dropped rather than
+    // replayed into a brand new shell.
+    'LIVE=0',
+    'if [ -S "$SOCK" ] && ps -eo args= 2>/dev/null | grep -qF "$SOCK"; then LIVE=1; fi',
+    'if [ "$LIVE" = 0 ]; then rm -f "$SOCK" 2>/dev/null; : > "$LOG" 2>/dev/null; fi',
+    // ── replay buffer ────────────────────────────────────────────────────────
+    // Trim first (the log is append-only and would otherwise grow forever), then
+    // dump its tail. The dump is preceded by a reset because the tail can start
+    // mid-escape-sequence or while the alternate screen / mouse tracking was on;
+    // `tail -n +2` drops the (possibly truncated) first line.
+    'if [ "$LIVE" = 1 ] && [ -f "$LOG" ]; then',
+    '  SZ=$(wc -c < "$LOG" 2>/dev/null || echo 0)',
+    `  if [ "$SZ" -gt ${MAX_LOG_BYTES} ] 2>/dev/null; then`,
+    `    tail -c ${TRIM_TO} "$LOG" > "$LOG.trim" 2>/dev/null && cat "$LOG.trim" > "$LOG" 2>/dev/null; rm -f "$LOG.trim"`,
+    "  fi",
+    `  if [ "$SZ" -gt ${REPLAY_MIN_BYTES} ] 2>/dev/null; then`,
+    `    printf '\\033[?1049l\\033[?1000l\\033[?1002l\\033[?1003l\\033[?1006l\\033c'`,
+    `    printf '\\033[2m── replay ──\\033[0m\\r\\n'`,
+    `    tail -c ${REPLAY_BYTES} "$LOG" 2>/dev/null | tail -n +2`,
+    "  fi",
+    "fi",
+    // ── attach ───────────────────────────────────────────────────────────────
+    // script(1) records the session's raw output for the replay above. Without it
+    // the session still works, it just comes back blank.
+    "if command -v script >/dev/null 2>&1; then",
+    '  exec dtach -A "$SOCK" -r winch -E -z script -q -a -f "$LOG" -c "$_SH -l"',
+    "else",
+    '  exec dtach -A "$SOCK" -r winch -E -z "$_SH" -l',
+    "fi",
+  ].join("\n")
+}
+
+// A dtach session is a socket file, nothing more — no server to ask. Name and
+// creation date come from the socket itself; the foreground command has to be
+// recovered from the container's process table (this is the metadata tmux gives
+// away for free, see the RFC): walk the process tree down from the dtach master
+// and keep the deepest descendant that sits in its pty's foreground process
+// group (the `+` in ps's STAT), which is exactly what `pane_current_command` means.
+export const LIST_SESSIONS_SCRIPT = [
+  `D=${TERMINAL_DIR}`,
+  '[ -d "$D" ] || exit 0',
+  'PSOUT=$(ps -eo pid=,ppid=,stat=,args= 2>/dev/null || true)',
+  'ESC=$(printf "\\033"); BEL=$(printf "\\007")',
+  'for s in "$D"/*.sock; do',
+  '  [ -S "$s" ] || continue',
+  '  n=$(basename "$s" .sock)',
+  '  created=$(stat -c %Y "$s" 2>/dev/null || echo 0)',
+  '  cmd=$(printf "%s\\n" "$PSOUT" | awk -v sock="$s" \'',
+  "    {",
+  "      pid=$1; ppid=$2; st=$3;",
+  '      args=""; for (i=4; i<=NF; i++) args = args (i>4 ? " " : "") $i;',
+  "      n++; order[n]=pid; P[pid]=ppid; S[pid]=st; A[pid]=args;",
+  '      if (index(args, sock) > 0) d[pid]=0;',
+  "    }",
+  "    END {",
+  "      for (iter=0; iter<12; iter++)",
+  "        for (i=1; i<=n; i++) { p=order[i]; if (!(p in d) && (P[p] in d)) d[p]=d[P[p]]+1 }",
+  '      best=""; bestd=0;',
+  "      for (i=1; i<=n; i++) {",
+  "        p=order[i];",
+  "        if (!(p in d) || d[p]==0) continue;",
+  '        if (S[p] !~ /\\+/) continue;',
+  '        c=A[p]; sub(/ .*/, "", c); sub(/.*\\//, "", c); sub(/^-/, "", c);',
+  '        if (c=="script" || c=="dtach") continue;',
+  "        if (d[p] >= bestd) { bestd=d[p]; best=c }",
+  "      }",
+  "      print best",
+  "    }')",
+  // Reported title (OSC 0/2, see terminal-title.ts). tmux keeps it in
+  // `pane_title`; dtach forwards every byte to the terminal and remembers
+  // nothing, so it is dug out of the replay log: the last `ESC ] 0|2 ; … BEL`
+  // written is the title currently on screen. Best effort — a container whose
+  // grep lacks `-a` simply yields no title and the UI falls back to the name.
+  '  t=$(tail -c 65536 "$D/$n.log" 2>/dev/null | LC_ALL=C grep -ao "$ESC][02];[^$BEL$ESC]*" 2>/dev/null | tail -n 1 | LC_ALL=C cut -c5-)',
+  '  echo "$n|1|0|$created|$cmd|$t"',
+  "done",
+].join("\n")
+
+/** Longest title kept — anything past that is a program dumping data, not naming itself. */
+const MAX_TITLE_LENGTH = 120
+
+/**
+ * Normalize a reported title, or return "" when there is nothing worth showing.
+ *
+ * `placeholders` are the values that mean "no one reported anything": tmux seeds
+ * `pane_title` with the container hostname, so a title still equal to it says
+ * only that the session never set one.
+ */
+export function sanitizeReportedTitle(raw: string | undefined, placeholders: string[] = []): string {
+  const title = (raw ?? "")
+    // Control characters (a stray BEL/ESC from a truncated read, a newline) would
+    // land as-is in a JSON payload and then in a React tree.
+    .replace(/[\u0000-\u001f\u007f]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, MAX_TITLE_LENGTH)
+  if (!title) return ""
+  if (placeholders.some((p) => p && p.trim() === title)) return ""
+  return title
+}
+
+/**
+ * dtach clears the screen as soon as a client attaches — a bare `ESC[H ESC[J` ("Clear the screen.
+ * This assumes VT100." in dtach's own source). That write lands *after* the replay the attach
+ * script just printed, and wipes exactly what the replay exists to show.
+ *
+ * So it is dropped: once, and only in the first seconds of an attach — long enough to cover
+ * dtach's write, short enough that a program legitimately clearing its screen later is never
+ * touched. (`clear` emits `ESC[H ESC[2J ESC[3J`, different bytes, so it would not match anyway.)
+ *
+ * `Uint8Array` in and out rather than Node's Buffer: a Buffer is one, so a Node caller passes its
+ * chunks straight through, and the package stays runnable anywhere.
+ */
+export function makeAttachClearStripper(
+  windowMs = 5000,
+  now: () => number = Date.now,
+): (chunk: Uint8Array) => Uint8Array {
+  const CLEAR = new TextEncoder().encode("\x1b[H\x1b[J")
+  const deadline = now() + windowMs
+  let done = false
+  return (chunk) => {
+    if (done) return chunk
+    if (now() > deadline) {
+      done = true
+      return chunk
+    }
+    const i = indexOfBytes(chunk, CLEAR)
+    if (i === -1) return chunk
+    done = true
+    const out = new Uint8Array(chunk.length - CLEAR.length)
+    out.set(chunk.subarray(0, i), 0)
+    out.set(chunk.subarray(i + CLEAR.length), i)
+    return out
+  }
+}
+
+/** `Buffer.indexOf` for a plain Uint8Array — the needle is 6 bytes, so the naive scan is the right one. */
+function indexOfBytes(haystack: Uint8Array, needle: Uint8Array): number {
+  outer: for (let i = 0; i + needle.length <= haystack.length; i++) {
+    for (let j = 0; j < needle.length; j++) if (haystack[i + j] !== needle[j]) continue outer
+    return i
+  }
+  return -1
+}
+
+/** One persistent session of a worker, as a control plane reports it. */
+export type TerminalSession = {
+  name: string
+  /** Always 1 — dtach has no windows. Kept so a UI written against a multiplexer still renders. */
+  windows: number
+  /**
+   * Decided by the caller, not by this parse: a socket says nothing about who is connected, and the
+   * process that attaches is the one that knows.
+   */
+  attached: boolean
+  createdAt: number
+  command: string
+  /** Title the running program reported over OSC 0/2 ("" when it reported none). */
+  title: string
+}
+
+/**
+ * Parse what `LIST_SESSIONS_SCRIPT` printed into sessions.
+ *
+ * Separate from running it: executing a command inside a container is the caller's business, and
+ * keeping the parse here is what lets it be tested without a container.
+ */
+export function parseSessionList(output: string, isAttached: (session: string) => boolean): TerminalSession[] {
+  return output
+    .trim()
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      // The title is free-form and last, so it keeps any "|" it contains.
+      const parts = line.split("|")
+      const [name = "", , , created = "0", command = ""] = parts
+      return {
+        name: name.trim(),
+        windows: 1,
+        attached: isAttached(name.trim()),
+        createdAt: (parseInt(created) || 0) * 1000,
+        command: command.trim(),
+        title: sanitizeReportedTitle(parts.slice(5).join("|")),
+      }
+    })
+    .filter((s) => s.name)
+}
+
+/**
+ * Shell that creates a session without attaching to it — `dtach -n` daemonizes the master.
+ *
+ * `session` must already have been through `sanitizeSessionName`: it is interpolated into the
+ * script.
+ */
+export function buildCreateSessionCommand(session: string): string {
+  return [
+    `D=${TERMINAL_DIR}`,
+    `N="${session}"`,
+    'mkdir -p "$D" 2>/dev/null; chmod 700 "$D" 2>/dev/null',
+    "command -v dtach >/dev/null 2>&1 || exit 0",
+    '[ -S "$D/$N.sock" ] && exit 0',
+    '_SH=$(getent passwd "$(id -un)" 2>/dev/null | cut -d: -f7); _SH=${_SH:-/bin/bash}',
+    // stdio redirected: the daemonized master inherits the exec's fds and would otherwise hold its
+    // stdout open long after the session exists.
+    "if command -v script >/dev/null 2>&1; then",
+    '  dtach -n "$D/$N.sock" -r winch -E -z script -q -a -f "$D/$N.log" -c "$_SH -l" </dev/null >/dev/null 2>&1',
+    "else",
+    '  dtach -n "$D/$N.sock" -r winch -E -z "$_SH" -l </dev/null >/dev/null 2>&1',
+    "fi",
+  ].join("\n")
+}
+
+/**
+ * Shell that kills a session: SIGTERM every process holding its socket (master and any client),
+ * then drop the socket and the recording.
+ *
+ * `session` must already have been through `sanitizeSessionName`.
+ */
+export function buildKillSessionCommand(session: string): string {
+  return [
+    `SOCK=${TERMINAL_DIR}/${session}.sock`,
+    'for p in $(ps -eo pid=,args= 2>/dev/null | awk -v sock="$SOCK" -v me=$$ \'$1 != me && index($0, sock) > 0 && index($0, "dtach") > 0 { print $1 }\'); do',
+    '  kill "$p" 2>/dev/null',
+    "done",
+    `rm -f "$SOCK" ${TERMINAL_DIR}/${session}.log 2>/dev/null`,
+    "true",
+  ].join("\n")
+}

package/src/terminal/index.ts

@@ -0,0 +1,22 @@
+// The half of a persistent terminal that is a string, not a socket: the shell that gets attached,
+// the layout it writes into, and the parsing of what it prints back. Attaching is I/O and stays
+// with whoever owns the Docker socket.
+//
+// See `./dtach` for why dtach and not tmux (RFC 0019).
+
+export {
+  buildCreateSessionCommand,
+  buildDtachCommand,
+  buildKillSessionCommand,
+  LIST_SESSIONS_SCRIPT,
+  makeAttachClearStripper,
+  MAX_LOG_BYTES,
+  parseSessionList,
+  REPLAY_BYTES,
+  REPLAY_MIN_BYTES,
+  sanitizeReportedTitle,
+  sanitizeSessionName,
+  TERMINAL_DIR,
+  TRIM_TO,
+} from "./dtach"
+export type { TerminalSession } from "./dtach"