Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
/**
* The run node: VS Code's "Run Without Debugging" for any `.vscode/launch.json` configuration, as
* a canvas terminal. A terminal node carrying `data.runConfig` (NOT a new NodeKind): the run lives
* in the node's tmux session, so it inherits everything a terminal already has.
*
* launch.json does not run anything by itself — each `type` belongs to a VS Code extension (a
* debug adapter) that turns the configuration into a process. This module is the table of what
* those extensions would run, type by type (`planLaunch`), for the `"request": "launch"` form:
*
* dart flutter run / flutter test / dart run / dart test (Flutter: hot reload + devices)
* node, pwa-node, node-terminal node / runtimeExecutable / command
* python, debugpy python program | -m module
* go go run / go test / the built binary
* php php program
* coreclr dotnet program.dll | program
* lldb, cppdbg the program itself
* chrome, msedge, pwa-chrome, pwa-msedge open `url` in a browser node
*
* What it deliberately does NOT do, and says so instead of guessing: debugging (breakpoints are a
* debug-adapter protocol, not a command line), `"request": "attach"` (there is nothing to start),
* unknown types, and the variables that need an editor or an extension (`${file}`, `${input:…}`,
* `${command:…}` beyond the Python interpreter one, `${config:…}`).
*
* Every value here comes from files in a repository (launch.json, tasks.json, and the git-shared
* `.nodeterm/project.json` that stores the node's choice), so none of it is ever pasted into a
* shell: the host writes a launcher script whose every token is single-quoted (`buildLauncher`),
* and only `sh '<that script>'` is typed into the node's terminal. Environment values (including an
* `envFile`'s secrets) therefore never land in the user's shell history or scrollback.
*/
import { shellSingleQuote, shellSplit } from './shell-quote'
import { isRecord } from './is-record'
// ─── The node's persisted choice ─────────────────────────────────────────────────────────────
/** Persisted on a terminal node as `data.runConfig`. */
export interface RunNodeConfig {
/** Absolute path of the workspace folder (the one holding `.vscode/`). Defaults to the project's. */
projectDir: string
/** Name of a configuration or compound in `<projectDir>/.vscode/launch.json`. Absent = default. */
launchConfig?: string
/** Flutter: `-d <id>`. Ignored when the configuration pins its own device. */
deviceId?: string
/** The device's display name when picked, so the bar can label it before devices load. */
deviceName?: string
/** Extra arguments appended to the program's arguments, shell-split and quoted per token. */
extraArgs?: string
/** Flutter: hot reload when a `.dart` file under `lib/` changes. Default on. */
reloadOnSave: boolean
/** Whether the node shows its terminal (and the extra-arguments field). Default hidden. */
showTerminal?: boolean
/** Flutter web runs (Chrome / Edge): `true` = show the app INSIDE the run node (Flutter's web
* server serves it to the node's browser panel). Absent = Flutter's own Chrome window, what a
* Chrome run has always done. Opt-in, so an existing configuration runs exactly as before. */
embedBrowser?: boolean
}
/** Whether a Flutter browser-device run is moved onto Flutter's web server and shown inside the
* node. Opt-in: only an explicit `embedBrowser: true` — the one rule for the host and the bar. */
export function embedsFlutterWeb(config: Pick<RunNodeConfig, 'embedBrowser'>): boolean {
return config.embedBrowser === true
}
const MAX_PATH = 4096
const MAX_EXTRA_ARGS = 2000
const MAX_NAME = 200
/** Device ids are simulator UDIDs, `macos`, `chrome`, emulator ids, physical UDIDs — never shell. */
const DEVICE_ID = /^[A-Za-z0-9._:-]{1,128}$/
/** Node ids become launcher/pid file names; the charset tmux session names are held to. */
export const RUN_NODE_ID = /^[A-Za-z0-9._-]{1,128}$/
export const SIMULATOR_UDID = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/
// eslint-disable-next-line no-control-regex
const CONTROL = /[\u0000-\u001f\u007f]/
/** An absolute POSIX or Windows path with no control characters. */
export function isSafeRunDir(dir: unknown): dir is string {
if (typeof dir !== 'string' || dir.length === 0 || dir.length > MAX_PATH) return false
if (CONTROL.test(dir)) return false
return dir.startsWith('/') || /^[A-Za-z]:[\\/]/.test(dir)
}
export function isSafeDeviceId(id: unknown): id is string {
return typeof id === 'string' && DEVICE_ID.test(id)
}
function oneLine(v: unknown, max: number): string | undefined {
if (typeof v !== 'string') return undefined
const s = v.trim()
if (!s || s.length > max || CONTROL.test(s)) return undefined
return s
}
/**
* Re-validate a persisted run config (git-shared, hand-editable). `undefined` = not a run node (or
* too broken to describe one), which degrades the node to a plain terminal rather than failing.
*/
export function normalizeRunConfig(raw: unknown): RunNodeConfig | undefined {
if (!raw || typeof raw !== 'object') return undefined
const r = raw as Record<string, unknown>
if (!isSafeRunDir(r.projectDir)) return undefined
const out: RunNodeConfig = { projectDir: r.projectDir, reloadOnSave: r.reloadOnSave !== false }
const launchConfig = oneLine(r.launchConfig, MAX_NAME)
if (launchConfig) out.launchConfig = launchConfig
if (isSafeDeviceId(r.deviceId)) {
out.deviceId = r.deviceId
const deviceName = oneLine(r.deviceName, MAX_NAME)
if (deviceName) out.deviceName = deviceName
}
const extraArgs = oneLine(r.extraArgs, MAX_EXTRA_ARGS)
if (extraArgs) out.extraArgs = extraArgs
if (r.showTerminal === true) out.showTerminal = true
if (r.embedBrowser === true) out.embedBrowser = true
return out
}
// ─── JSONC + the two files ───────────────────────────────────────────────────────────────────
/**
* VS Code's launch.json / tasks.json are JSONC: `//` and `/* *\/` comments and trailing commas.
* Strip them outside strings, then JSON.parse. Throws on anything else.
*/
export function parseJsonc(text: string): unknown {
let out = ''
let i = 0
let inString = false
while (i < text.length) {
const c = text[i]
if (inString) {
out += c
if (c === '\\' && i + 1 < text.length) {
out += text[i + 1]
i += 2
continue
}
if (c === '"') inString = false
i++
continue
}
if (c === '"') {
inString = true
out += c
i++
} else if (c === '/' && text[i + 1] === '/') {
while (i < text.length && text[i] !== '\n') i++
} else if (c === '/' && text[i + 1] === '*') {
const end = text.indexOf('*/', i + 2)
i = end < 0 ? text.length : end + 2
} else {
out += c
i++
}
}
let cleaned = ''
inString = false
for (let j = 0; j < out.length; j++) {
const c = out[j]
if (inString) {
cleaned += c
if (c === '\\' && j + 1 < out.length) cleaned += out[++j]
else if (c === '"') inString = false
continue
}
if (c === '"') {
inString = true
cleaned += c
continue
}
if (c === ',') {
let k = j + 1
while (k < out.length && /\s/.test(out[k])) k++
if (out[k] === ']' || out[k] === '}') continue
}
cleaned += c
}
return JSON.parse(cleaned)
}
export type OsKey = 'osx' | 'linux' | 'windows'
export function osKeyFor(platform: string): OsKey {
return platform === 'darwin' ? 'osx' : platform === 'win32' ? 'windows' : 'linux'
}
/** A configuration as written, with its `osx`/`linux`/`windows` block merged over it. */
export interface LaunchConfig {
name: string
type: string
request: string
raw: Record<string, unknown>
}
export interface LaunchCompound {
name: string
configurations: string[]
}
export interface LaunchFile {
configs: LaunchConfig[]
compounds: LaunchCompound[]
}
function withOsOverride(raw: Record<string, unknown>, os: OsKey): Record<string, unknown> {
const o = raw[os]
return isRecord(o) ? { ...raw, ...o } : raw
}
/** Configurations and compounds, in file order. Throws on unparseable JSONC. */
export function parseLaunchFile(text: string, os: OsKey = 'osx'): LaunchFile {
const doc = parseJsonc(text) as { configurations?: unknown; compounds?: unknown }
const configs: LaunchConfig[] = []
const seen = new Set<string>()
for (const item of Array.isArray(doc?.configurations) ? doc.configurations : []) {
if (!isRecord(item)) continue
const raw = withOsOverride(item, os)
const name = oneLine(raw.name, MAX_NAME)
const type = oneLine(raw.type, MAX_NAME)
if (!name || !type || seen.has(name)) continue
seen.add(name)
configs.push({ name, type, request: typeof raw.request === 'string' ? raw.request : 'launch', raw })
}
const compounds: LaunchCompound[] = []
for (const item of Array.isArray(doc?.compounds) ? doc.compounds : []) {
if (!isRecord(item)) continue
const name = oneLine(item.name, MAX_NAME)
if (!name || seen.has(name)) continue
seen.add(name)
const members = (Array.isArray(item.configurations) ? item.configurations : [])
.map((m) => (typeof m === 'string' ? m : isRecord(m) && typeof m.name === 'string' ? m.name : null))
.filter((m): m is string => !!m)
compounds.push({ name, configurations: members })
}
return { configs, compounds }
}
/** A task from tasks.json, with its OS block merged over it. */
export interface TaskDef {
label: string
raw: Record<string, unknown>
}
/** Tasks in file order, keyed by `label` (or VS Code's derived `npm: <script>`). Throws on bad JSONC. */
export function parseTasksFile(text: string, os: OsKey = 'osx'): TaskDef[] {
const doc = parseJsonc(text) as { tasks?: unknown }
const out: TaskDef[] = []
for (const item of Array.isArray(doc?.tasks) ? doc.tasks : []) {
if (!isRecord(item)) continue
const raw = withOsOverride(item, os)
const label =
oneLine(raw.label, MAX_NAME) ??
(raw.type === 'npm' && typeof raw.script === 'string' ? `npm: ${raw.script}` : undefined) ??
(typeof raw.type === 'string' && typeof raw.command === 'string' ? `${raw.type}: ${raw.command}` : undefined)
if (label) out.push({ label, raw })
}
return out
}
// ─── Describing a configuration (cheap, no environment) ──────────────────────────────────────
/** What the bar needs to know about an entry before anything runs. */
export interface LaunchEntry {
name: string
kind: 'config' | 'compound'
/** The VS Code `type` ('' for compounds). */
type: string
/** "Flutter", "Node.js", "Python", … — shown beside the name. */
typeLabel: string
/** False when this configuration cannot be run here; `reason` says why. */
supported: boolean
reason?: string
/** Flutter runs: pick a device (unless `pinnedDevice`). */
usesDevice: boolean
/** Flutter `flutter run`: hot reload / hot restart / reload on save. */
hotReload: boolean
/** The device a Flutter configuration names itself. */
pinnedDevice?: string
/** Opens a URL in a browser node instead of running a process. */
browser: boolean
/** Compounds: the member configuration names. */
members?: string[]
/** The configuration's `preLaunchTask`, if any. */
preLaunchTask?: string
/** Flutter: the `--flavor` the configuration builds with. */
flavor?: string
/** A `"request": "attach"` configuration (Flutter: `flutter attach` to a running debug app). */
attach?: boolean
}
const TYPE_LABEL: Record<string, string> = {
dart: 'Dart',
node: 'Node.js',
'pwa-node': 'Node.js',
'node-terminal': 'Node.js',
python: 'Python',
debugpy: 'Python',
go: 'Go',
php: 'PHP',
coreclr: '.NET',
lldb: 'Native',
cppdbg: 'Native',
chrome: 'Browser',
msedge: 'Browser',
'pwa-chrome': 'Browser',
'pwa-msedge': 'Browser'
}
export const SUPPORTED_TYPES = Object.keys(TYPE_LABEL)
const BROWSER_TYPES = new Set(['chrome', 'msedge', 'pwa-chrome', 'pwa-msedge'])
export function typeLabel(type: string, isFlutterProject: boolean): string {
if (type === 'dart') return isFlutterProject ? 'Flutter' : 'Dart'
return TYPE_LABEL[type] ?? type
}
function strArray(v: unknown): string[] {
if (typeof v === 'string') return shellSplit(v)
return Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : []
}
function str(v: unknown): string | undefined {
return typeof v === 'string' && v.trim() ? v : undefined
}
/** Flutter's browser devices open a Chrome window of their own; its web server serves the same app
* to any browser and prints the address. Every other device is itself. */
export function webServerDevice(d: string): string {
return d === 'chrome' || d === 'edge' ? 'web-server' : d
}
/** Whether a configuration names its device in its own args (as opposed to the `deviceId` field). */
function pinnedInArgs(raw: Record<string, unknown>): boolean {
return [...strArray(raw.args), ...strArray(raw.toolArgs)].some(
(t) => t === '-d' || t === '--device-id' || t.startsWith('-d=') || t.startsWith('--device-id=')
)
}
/** The device a Dart configuration pins (`-d x`, `--device-id x`, `-d=x`, or `deviceId`). */
export function pinnedDevice(raw: Record<string, unknown>): string | undefined {
const a = [...strArray(raw.args), ...strArray(raw.toolArgs)]
for (let i = 0; i < a.length; i++) {
const t = a[i]
if ((t === '-d' || t === '--device-id') && a[i + 1]) return a[i + 1]
if (t.startsWith('-d=')) return t.slice(3)
if (t.startsWith('--device-id=')) return t.slice('--device-id='.length)
}
return isSafeDeviceId(raw.deviceId) ? raw.deviceId : undefined
}
/** A Dart VM service URL as the engine prints it: loopback http, a port, the auth-code path. */
export function isVmServiceUrl(s: string): boolean {
return /^http:\/\/127\.0\.0\.1:\d{1,5}\/[A-Za-z0-9_=+-]*\/?$/.test(s)
}
/**
* The VM service URLs a Flutter app announced in an iOS simulator's log, newest last, with the pid
* of the process that announced each. The engine logs `The Dart VM service is listening on <url>`
* at startup; `log show --style compact` prefixes `<process>[<pid>:<tid>]`.
*
* Needed because `flutter attach` cannot find an ALREADY-running app on the iOS simulator — it
* relies on mDNS, which the simulator barely supports. MEASURED (Flutter 3.47, iOS 27.1 sim): attach
* printed "The Dart VM Service was not discovered after 30 seconds … use the Dart VM service URL
* … with flutter attach --debug-url" and never connected; with the URL from this log line it
* connected in 26 s. The URL `flutter run` itself printed is useless here: it is the tool's DDS
* proxy, which closes when that tool detaches.
*/
export function parseVmServiceLog(text: string): Array<{ url: string; pid: string }> {
const out: Array<{ url: string; pid: string }> = []
for (const line of text.split('\n')) {
if (!line.includes('Dart VM service is listening on')) continue
const url = /listening on (http:\/\/127\.0\.0\.1:\d+\/[A-Za-z0-9_=+-]*\/?)/.exec(line)?.[1]
const pid = /\[(\d+):/.exec(line)?.[1]
if (url && pid && isVmServiceUrl(url)) out.push({ url: url.endsWith('/') ? url : `${url}/`, pid })
}
return out
}
/** The `--flavor` in a Flutter argv (`--flavor x` or `--flavor=x`). */
export function flavorOf(args: readonly string[]): string | undefined {
for (let i = 0; i < args.length; i++) {
if (args[i] === '--flavor' && args[i + 1]) return args[i + 1]
if (args[i].startsWith('--flavor=')) return args[i].slice('--flavor='.length)
}
return undefined
}
/**
* The `flutter run` arguments `flutter attach` also understands, and the ones it would reject.
* MEASURED against `flutter attach --help` (Flutter 3.47): attach takes the target, dart-defines,
* the app id / VM service URL and device options — and NOT `--flavor`, `--web-port`, build modes or
* anything else that shapes a build, because attach builds nothing. An unknown option is a hard
* error ("Could not find an option named …"), so passing a run argv through would kill the attach.
* `-d` is left out on purpose: the device is always the node's own.
*/
const ATTACH_VALUE_FLAGS = new Set([
'-t', '--target', '-D', '--dart-define', '--dart-define-from-file', '--app-id', '--debug-url',
'--device-timeout', '--device-user', '--dds-port', '--device-vmservice-port', '--host-vmservice-port'
])
const ATTACH_BOOL_FLAGS = new Set(['--track-widget-creation', '--no-track-widget-creation', '--dds', '--no-dds'])
export function attachArgs(args: readonly string[]): { kept: string[]; dropped: string[] } {
const kept: string[] = []
const dropped: string[] = []
for (let i = 0; i < args.length; i++) {
const a = args[i]
const eq = a.indexOf('=')
const flag = a.startsWith('-') && eq > 0 ? a.slice(0, eq) : a
if (ATTACH_VALUE_FLAGS.has(flag)) {
if (eq > 0) kept.push(a)
else if (i + 1 < args.length) kept.push(a, args[++i])
} else if (ATTACH_BOOL_FLAGS.has(a)) {
kept.push(a)
} else if (a.startsWith('-')) {
// A flag attach does not know; drop its value too when it has one (`--flavor dev`).
dropped.push(a)
if (eq < 0 && i + 1 < args.length && !args[i + 1].startsWith('-') && RUN_VALUE_FLAGS.has(a)) dropped.push(args[++i])
} else {
dropped.push(a)
}
}
return { kept, dropped }
}
/** `flutter run` flags that take a value, so `attachArgs` drops the value with the flag. */
const RUN_VALUE_FLAGS = new Set([
'--flavor', '-d', '--device-id', '--web-port', '--web-hostname', '--web-browser-flag', '--web-renderer',
'--route', '--dart-entrypoint-args', '-a', '--target-platform', '--build-name', '--build-number',
'--split-debug-info', '--obfuscation-map', '--web-launch-url', '--web-header', '--web-tls-cert-path',
'--web-tls-cert-key-path', '--device-connection'
])
/** What a running Flutter run was started from — enough to tell whether a switch can keep it. */
export interface RunSnapshot {
projectDir: string
deviceId?: string
flavor?: string
hotReload: boolean
}
/**
* Can the node switch a running Flutter app to `to` WITHOUT rebuilding it — detach the tool, attach
* a new one from the new checkout, hot restart? Only when the running app is the one `to` would
* build: same device, same flavor, a Flutter run (not a test) on both sides. Anything native that
* differs between the checkouts (plugins, ios/, Info.plist) is not something this can know, which
* is why Rebuild stays offered beside it.
*/
export function canHotSwitch(from: RunSnapshot | null, to: { config: RunNodeConfig; entry: LaunchEntry | undefined }): boolean {
const e = to.entry
if (!from || !from.hotReload || !e || !e.supported || e.kind !== 'config' || !e.hotReload) return false
if (e.pinnedDevice) return false // a pinned device is web/desktop/explicit — attach is for the node's device
if (!from.deviceId || from.deviceId !== to.config.deviceId) return false
if ((from.flavor ?? '') !== (e.flavor ?? '')) return false
return true
}
/** Has `flutter attach` connected? It prints its key-command help once it has. `attachLine` is the
* launcher's own `▶ flutter attach …` line: the help must come AFTER it (an earlier run's help may
* still be on screen). When that line has scrolled away, everything on screen is newer than it. */
export function attachConnected(screen: string): boolean {
const ready = Math.max(screen.lastIndexOf('Flutter run key commands'), screen.lastIndexOf('To hot restart changes'))
if (ready < 0) return false
return ready > screen.lastIndexOf('▶ flutter attach')
}
/** Dart-Code runs a `program` under test/ or integration_test/ (or a *_test.dart) as a TEST. */
export function isDartTestProgram(program: string | undefined): boolean {
if (!program) return false
const p = program.replace(/\\/g, '/')
return /(^|\/)(test|integration_test)\//.test(p) || p.endsWith('_test.dart')
}
const UNSUPPORTED_VAR = /\$\{(file|fileBasename|fileBasenameNoExtension|fileDirname|fileExtname|fileWorkspaceFolder|relativeFile|relativeFileDirname|lineNumber|selectedText|execPath|input:[^}]*|config:[^}]*|command:[^}]*|workspaceFolder:[^}]*)\}/
/** The first variable in `raw` that needs an editor or an extension to resolve, if any. */
export function unsupportedVariable(raw: unknown): string | undefined {
const text = JSON.stringify(raw)
const re = new RegExp(UNSUPPORTED_VAR.source, 'g')
for (let m = re.exec(text); m; m = re.exec(text)) {
// The Python extension's interpreter is the one `${command:…}` we can answer ourselves.
if (m[1] === 'command:python.interpreterPath') continue
return m[0]
}
return undefined
}
export function describeConfig(cfg: LaunchConfig, isFlutterProject: boolean): LaunchEntry {
const base: LaunchEntry = {
name: cfg.name,
kind: 'config',
type: cfg.type,
typeLabel: typeLabel(cfg.type, isFlutterProject),
supported: true,
usesDevice: false,
hotReload: false,
browser: BROWSER_TYPES.has(cfg.type),
...(str(cfg.raw.preLaunchTask) ? { preLaunchTask: str(cfg.raw.preLaunchTask) } : {})
}
const refuse = (reason: string): LaunchEntry => ({ ...base, supported: false, reason })
const flutter = cfg.type === 'dart' && (isFlutterProject || cfg.raw.flutterMode !== undefined)
// A Flutter attach is `flutter attach`: it connects to an app already running in debug mode.
// Every other attach (a debugger to a process, Xdebug, …) has nothing for us to start.
if (cfg.request !== 'launch' && !(cfg.request === 'attach' && flutter)) {
return refuse(`“${cfg.name}” attaches to a process that is already running — there is nothing to start.`)
}
if (!(cfg.type in TYPE_LABEL)) return refuse(`“${cfg.type}” configurations are not supported yet.`)
const v = unsupportedVariable(cfg.raw)
if (v) return refuse(`${v} needs VS Code to resolve — it cannot run here.`)
if (cfg.type === 'dart') {
const program = str(cfg.raw.program)
const isTest = isDartTestProgram(program)
if (flutter) {
const pinned = pinnedDevice(cfg.raw)
const flavor = flavorOf([...strArray(cfg.raw.toolArgs), ...strArray(cfg.raw.args)])
const attach = cfg.request === 'attach'
if (attach && isTest) return refuse(`“${cfg.name}” attaches to a test — tests cannot be attached to.`)
// A widget test runs headless; an integration test runs on a device, like the app.
const onDevice = !isTest || /(^|\/)integration_test\//.test((program ?? '').replace(/\\/g, '/'))
return {
...base,
typeLabel: 'Flutter',
usesDevice: onDevice,
hotReload: !isTest,
...(pinned ? { pinnedDevice: pinned } : {}),
...(flavor ? { flavor } : {}),
...(attach ? { attach: true } : {})
}
}
if (!program) return refuse(`“${cfg.name}” has no program to run.`)
return base
}
if (cfg.type === 'php' && !str(cfg.raw.program)) {
return refuse(`“${cfg.name}” listens for Xdebug — there is nothing to start. Run the app separately.`)
}
if (base.browser && !str(cfg.raw.url)) return refuse(`“${cfg.name}” has no url to open.`)
return base
}
export function describeLaunchFile(file: LaunchFile, isFlutterProject: boolean): LaunchEntry[] {
const configs = file.configs.map((c) => describeConfig(c, isFlutterProject))
const names = new Set(file.configs.map((c) => c.name))
const compounds = file.compounds.map((c): LaunchEntry => {
const missing = c.configurations.filter((m) => !names.has(m))
return {
name: c.name,
kind: 'compound',
type: '',
typeLabel: 'Compound',
supported: missing.length === 0 && c.configurations.length > 0,
...(missing.length
? { reason: `“${c.name}” names configurations that are not in launch.json: ${missing.join(', ')}.` }
: c.configurations.length === 0
? { reason: `“${c.name}” lists no configurations.` }
: {}),
usesDevice: false,
hotReload: false,
browser: false,
members: c.configurations
}
})
return [...configs, ...compounds]
}
/** Why a process run is refused on a Windows core (the launcher is a POSIX `sh` script, stopped and
* hot-reloaded by POSIX signals). One sentence, shared by the core's refusal and the entry gate. */
export const RUN_WINDOWS_REASON = 'Run configurations that launch a process are not supported on Windows yet.'
/**
* Gate entries for the core's platform, so a Windows core says "cannot run here" BEFORE Start
* instead of failing on click. Off win32 this is the identity (same array, untouched entries).
* On win32 a browser configuration still works (it opens a browser node, no process), and so does a
* compound whose every member is one; anything that would launch a process is refused with
* `RUN_WINDOWS_REASON`.
*/
export function gateEntriesForPlatform(entries: LaunchEntry[], platform: string): LaunchEntry[] {
if (platform !== 'win32') return entries
const byName = new Map(entries.filter((e) => e.kind === 'config').map((e) => [e.name, e]))
return entries.map((e) => {
if (!e.supported) return e
const launches = e.kind === 'config' ? !e.browser : (e.members ?? []).some((m) => !byName.get(m)?.browser)
return launches ? { ...e, supported: false, reason: RUN_WINDOWS_REASON } : e
})
}
/** The synthetic entry a Flutter checkout with no launch.json gets: plain `flutter run`. */
export const DEFAULT_FLUTTER_ENTRY = 'flutter run (lib/main.dart)'
/** Which entry a node runs: its named one, else the first supported configuration that leaves
* the device to the picker (VS Code's "Current device" style), else the first supported one. */
export function resolveEntry(entries: readonly LaunchEntry[], name: string | undefined): LaunchEntry | undefined {
if (name) {
const hit = entries.find((e) => e.name === name)
if (hit) return hit
}
const runnable = entries.filter((e) => e.supported && e.kind === 'config')
return runnable.find((e) => e.usesDevice && !e.pinnedDevice) ?? runnable[0] ?? entries[0]
}
// ─── Planning a run ──────────────────────────────────────────────────────────────────────────
export interface PlanContext {
/** `${workspaceFolder}` — the node's projectDir. */
workspace: string
/** `${userHome}`. */
home: string
/** `${env:NAME}`, pre-resolved by the host from the user's login environment. */
env: Readonly<Record<string, string>>
isFlutterProject: boolean
/** The interpreter the Python extension would pick: a workspace venv, else `python3`. */
pythonPath: string
/** The node's device, for Flutter runs. */
deviceId?: string
/** The node's extra arguments, appended to the program's own. */
extraArgs?: string
/** Run a Flutter browser device (chrome / edge) on Flutter's web server instead, so the app is
* served to the run node's browser panel rather than to a Chrome window of Flutter's own. */
webServer?: boolean
/** Where `flutter run` writes its pid (for hot reload / restart signals). */
flutterPidFile: string
tasks: readonly TaskDef[]
}
/** One preLaunchTask step: a process argv, or a shell command line (`sh -c`). */
export interface TaskStep {
label: string
cwd: string
env: Record<string, string>
argv?: string[]
shell?: string
}
export interface ProcessPlan {
kind: 'process'
name: string
cwd: string
env: Record<string, string>
/** Absolute path of an `envFile` to load before `env` (which wins), when the config names one. */
envFile?: string
/** A program argv — or, for `node-terminal`'s free-form `command`, a shell line. */
argv?: string[]
shell?: string
preTasks: TaskStep[]
/** `flutter run` (hot reload by signal), anything else is plain stop/restart. */
hotReload: boolean
}
export interface BrowserPlan {
kind: 'browser'
name: string
url: string
}
export type PlanResult = { ok: true; plan: ProcessPlan | BrowserPlan } | { ok: false; error: string }
/** Expand the variables we can answer. Throws `Error(<variable>)` on one we cannot. */
export function expandVars(s: string, ctx: PlanContext): string {
return s.replace(/\$\{([^}]+)\}/g, (whole, name: string) => {
if (name === 'workspaceFolder' || name === 'workspaceRoot' || name === 'cwd') return ctx.workspace
if (name === 'workspaceFolderBasename') return ctx.workspace.replace(/[\\/]+$/, '').split(/[\\/]/).pop() ?? ''
if (name === 'userHome') return ctx.home
if (name === 'pathSeparator' || name === '/') return '/'
if (name === 'command:python.interpreterPath') return ctx.pythonPath
if (name.startsWith('env:')) return ctx.env[name.slice(4)] ?? ''
throw new Error(whole)
})
}
function joinPath(base: string, rel: string): string {
if (rel.startsWith('/') || /^[A-Za-z]:[\\/]/.test(rel)) return rel
return `${base.replace(/\/+$/, '')}/${rel.replace(/^\.\//, '')}`
}
function envRecord(v: unknown, ctx: PlanContext): Record<string, string> {
const out: Record<string, string> = {}
if (isRecord(v)) {
for (const [k, val] of Object.entries(v)) {
if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) continue
if (typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean') {
out[k] = expandVars(String(val), ctx)
}
}
} else if (Array.isArray(v)) {
// cppdbg: `environment: [{ name, value }]`
for (const e of v) {
if (isRecord(e) && typeof e.name === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(e.name)) {
out[e.name] = expandVars(String(e.value ?? ''), ctx)
}
}
}
return out
}
const MAX_TASK_DEPTH = 8
/** The steps a `preLaunchTask` (and its `dependsOn`) runs, in order. Throws Error(reason). */
export function planTask(label: string, ctx: PlanContext, depth = 0, seen = new Set<string>()): TaskStep[] {
if (depth > MAX_TASK_DEPTH || seen.has(label)) throw new Error(`Task “${label}” depends on itself.`)
seen.add(label)
const task =
label === '${defaultBuildTask}'
? ctx.tasks.find((t) => {
const g = t.raw.group
return isRecord(g) && g.kind === 'build' && g.isDefault === true
})
: ctx.tasks.find((t) => t.label === label)
if (!task) throw new Error(`Task “${label}” is not in .vscode/tasks.json.`)
const t = task.raw
const steps: TaskStep[] = []
const deps = typeof t.dependsOn === 'string' ? [t.dependsOn] : strArray(t.dependsOn)
for (const d of deps) steps.push(...planTask(d, ctx, depth + 1, seen))
if (t.isBackground === true) {
throw new Error(`Task “${task.label}” runs in the background (a watcher) — start it separately, then run.`)
}
const options = isRecord(t.options) ? t.options : {}
const cwd = joinPath(ctx.workspace, expandVars(str(options.cwd) ?? ctx.workspace, ctx))
const env = envRecord(options.env, ctx)
const type = typeof t.type === 'string' ? t.type : 'process'
const command = str(t.command) ? expandVars(t.command as string, ctx) : undefined
const args = strArray(t.args).map((a) => expandVars(a, ctx))
const step = (s: Omit<TaskStep, 'label' | 'cwd' | 'env'>): TaskStep => ({ label: task.label, cwd, env, ...s })
// A task that only gathers others (`dependsOn` and nothing to run) contributes just those.
if (deps.length && !command && type !== 'npm' && type !== 'typescript') return steps
switch (type) {
case 'shell':
if (!command) throw new Error(`Task “${task.label}” has no command.`)
steps.push(step({ shell: [command, ...args.map(shellSingleQuote)].join(' ') }))
break
case 'process':
case 'dart':
case 'flutter':
// Dart-Code's tasks carry the tool as `command` ('dart' / 'flutter'), like a process task.
steps.push(step({ argv: [command ?? type, ...args] }))
break
case 'npm': {
const script = str(t.script)
if (!script) throw new Error(`Task “${task.label}” has no npm script.`)
const at = str(t.path) ? joinPath(ctx.workspace, expandVars(t.path as string, ctx)) : cwd
steps.push({ label: task.label, cwd: at, env, argv: ['npm', 'run', script, ...args] })
break
}
case 'typescript': {
if (t.option === 'watch') throw new Error(`Task “${task.label}” is a tsc watch — start it separately, then run.`)
steps.push(step({ argv: ['npx', 'tsc', '-p', expandVars(str(t.tsconfig) ?? 'tsconfig.json', ctx)] }))
break
}
case 'cargo':
steps.push(step({ argv: ['cargo', command ?? 'build', ...args] }))
break
default:
throw new Error(`Task “${task.label}” is a “${type}” task, which is not supported yet.`)
}
return steps
}
/** Turn one launch configuration into what the host runs. Pure; every refusal is a sentence. */
export function planLaunch(
cfg: LaunchConfig,
ctx: PlanContext,
opts: { attach?: boolean; debugUrl?: string } = {}
): PlanResult {
const entry = describeConfig(cfg, ctx.isFlutterProject)
if (!entry.supported) return { ok: false, error: entry.reason ?? 'Not supported.' }
try {
const raw = cfg.raw
const x = (s: string) => expandVars(s, ctx)
if (entry.browser) return { ok: true, plan: { kind: 'browser', name: cfg.name, url: x(str(raw.url) as string) } }
const cwd = joinPath(ctx.workspace, x(str(raw.cwd) ?? ctx.workspace))
const env = envRecord(raw.env ?? raw.environment, ctx)
const envFile = str(raw.envFile) ? joinPath(ctx.workspace, x(raw.envFile as string)) : undefined
const args = strArray(raw.args).map(x)
const extra = ctx.extraArgs ? shellSplit(ctx.extraArgs) : []
// A switch-attach runs nothing first: the app is already built and running.
const preTasks = str(raw.preLaunchTask) && !opts.attach ? planTask(x(raw.preLaunchTask as string), ctx) : []
const proc = (argv: string[], hotReload = false): PlanResult => ({
ok: true,
plan: {
kind: 'process',
name: cfg.name,
cwd,
env,
...(envFile ? { envFile } : {}),
argv,
preTasks,
hotReload
}
})
switch (cfg.type) {
case 'dart': {
const program = str(raw.program) ? x(raw.program as string) : undefined
const toolArgs = strArray(raw.toolArgs).map(x)
const isTest = isDartTestProgram(program)
if (entry.typeLabel === 'Flutter') {
// Dart-Code passes a Flutter config's `args` to `flutter run` too (the legacy behavior a
// config like `"args": ["--flavor", "dev"]` relies on), after `toolArgs`.
// The device: the node's pick, or the one the configuration names — in its args (rewritten
// in place) or as Dart-Code's `deviceId` field, which Dart-Code passes as `-d`.
const web = (d: string) => (ctx.webServer ? webServerDevice(d) : d)
let device: string[] = []
if (!entry.pinnedDevice && entry.usesDevice && ctx.deviceId) device = ['-d', web(ctx.deviceId)]
else if (entry.pinnedDevice && !pinnedInArgs(raw)) device = ['-d', web(entry.pinnedDevice)]
if (ctx.webServer) {
for (const list of [args, toolArgs]) {
for (let i = 0; i < list.length; i++) {
const t = list[i]
if ((t === '-d' || t === '--device-id') && list[i + 1]) list[i + 1] = web(list[i + 1])
else if (t.startsWith('-d=')) list[i] = `-d=${web(t.slice(3))}`
else if (t.startsWith('--device-id=')) list[i] = `--device-id=${web(t.slice('--device-id='.length))}`
}
}
}
const mode = raw.flutterMode === 'profile' ? ['--profile'] : raw.flutterMode === 'release' ? ['--release'] : []
if (isTest) return proc(['flutter', 'test', ...toolArgs, ...args, ...device, ...(program ? [program] : []), ...extra])
if (opts.attach || entry.attach) {
// `flutter attach` to the app already running on the node's device. Only the arguments
// attach understands survive (attachArgs); dart-defines do, so constants match.
// The host's discovered URL wins (an iOS simulator's app cannot be found by mDNS).
const vm = (opts.debugUrl && isVmServiceUrl(opts.debugUrl) ? opts.debugUrl : undefined) ?? str(raw.vmServiceUri) ?? str(raw.observatoryUri)
const attachDevice = entry.pinnedDevice ? ['-d', entry.pinnedDevice] : ctx.deviceId ? ['-d', ctx.deviceId] : []
return proc(
[
'flutter', 'attach',
...(program ? ['-t', program] : []),
...attachArgs([...toolArgs, ...args, ...extra]).kept,
...(vm ? ['--debug-url', x(vm)] : []),
...attachDevice,
'--pid-file', ctx.flutterPidFile
],
true
)
}
return proc(
[
'flutter', 'run',
...(program ? ['-t', program] : []),
...toolArgs, ...args, ...mode, ...device,
'--pid-file', ctx.flutterPidFile,
...extra
],
true
)
}
if (isTest) return proc(['dart', 'test', ...toolArgs, program as string, ...args, ...extra])
return proc(['dart', 'run', ...toolArgs, program as string, ...args, ...extra])
}
case 'node':
case 'pwa-node': {
const runtime = str(raw.runtimeExecutable) ? x(raw.runtimeExecutable as string) : 'node'
const runtimeArgs = strArray(raw.runtimeArgs).map(x)
const program = str(raw.program) ? x(raw.program as string) : undefined
if (!program && runtime === 'node' && runtimeArgs.length === 0) {
return { ok: false, error: `“${cfg.name}” has neither a program nor a runtime command.` }
}
return proc([runtime, ...runtimeArgs, ...(program ? [program] : []), ...args, ...extra])
}
case 'node-terminal': {
const command = str(raw.command)
if (!command) return { ok: false, error: `“${cfg.name}” has no command.` }
// A free-form command line the user wrote for a shell — it runs in one (sh -c), like VS Code.
const line = [x(command), ...extra.map(shellSingleQuote)].join(' ')
return { ok: true, plan: { kind: 'process', name: cfg.name, cwd, env, ...(envFile ? { envFile } : {}), shell: line, preTasks, hotReload: false } }
}
case 'python':
case 'debugpy': {
const python = str(raw.python) ? x(raw.python as string) : str(raw.pythonPath) ? x(raw.pythonPath as string) : ctx.pythonPath
const pythonArgs = strArray(raw.pythonArgs).map(x)
if (str(raw.module)) return proc([python, ...pythonArgs, '-m', x(raw.module as string), ...args, ...extra])
if (str(raw.program)) return proc([python, ...pythonArgs, x(raw.program as string), ...args, ...extra])
return { ok: false, error: `“${cfg.name}” has neither a program nor a module.` }
}
case 'go': {
const program = str(raw.program) ? x(raw.program as string) : ctx.workspace
const buildFlags = strArray(raw.buildFlags).map(x)
if (raw.mode === 'test') return proc(['go', 'test', ...buildFlags, program, ...args, ...extra])
if (raw.mode === 'exec') return proc([program, ...args, ...extra])
return proc(['go', 'run', ...buildFlags, program, ...args, ...extra])
}
case 'php': {
const runtime = str(raw.runtimeExecutable) ? x(raw.runtimeExecutable as string) : 'php'
return proc([runtime, ...strArray(raw.runtimeArgs).map(x), x(raw.program as string), ...args, ...extra])
}
case 'coreclr': {
const program = str(raw.program) ? x(raw.program as string) : undefined
if (!program) return { ok: false, error: `“${cfg.name}” has no program.` }
return proc(program.endsWith('.dll') ? ['dotnet', program, ...args, ...extra] : [program, ...args, ...extra])
}
case 'lldb':
case 'cppdbg': {
const program = str(raw.program) ? x(raw.program as string) : undefined
if (!program) return { ok: false, error: `“${cfg.name}” has no program.` }
return proc([program, ...args, ...extra])
}
default:
return { ok: false, error: `“${cfg.type}” configurations are not supported yet.` }
}
} catch (e) {
const msg = (e as Error).message
return { ok: false, error: msg.startsWith('${') ? `${msg} needs VS Code to resolve — it cannot run here.` : msg }
}
}
/** The plan for a Flutter checkout with no launch.json: `flutter run` on the chosen device. */
export function defaultFlutterConfig(): LaunchConfig {
return { name: DEFAULT_FLUTTER_ENTRY, type: 'dart', request: 'launch', raw: { name: DEFAULT_FLUTTER_ENTRY, type: 'dart' } }
}
// ─── The launcher script ─────────────────────────────────────────────────────────────────────
/** Parse a dotenv file: `KEY=value`, `export KEY=value`, quotes, `#` comments. */
export function parseEnvFile(text: string): Record<string, string> {
const out: Record<string, string> = {}
for (const line of text.replace(/\r\n/g, '\n').split('\n')) {
const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)?\s*$/.exec(line)
if (!m) continue
let v = (m[2] ?? '').trim()
if ((v.startsWith('"') && v.endsWith('"') && v.length >= 2) || (v.startsWith("'") && v.endsWith("'") && v.length >= 2)) {
const dq = v.startsWith('"')
v = v.slice(1, -1)
if (dq) v = v.replace(/\\n/g, '\n').replace(/\\"/g, '"')
} else {
v = v.replace(/\s+#.*$/, '')
}
out[m[1]] = v
}
return out
}
export interface LauncherPaths {
/** Written with the launcher's own pid while it runs; removed when it ends. */
pidFile: string
/** Written with the exit status when the run ends. */
exitFile: string
}
function exports(env: Record<string, string>): string[] {
return Object.entries(env).map(([k, v]) => `export ${k}=${shellSingleQuote(v)}`)
}
function cmdLine(argv: string[] | undefined, shell: string | undefined): string {
return argv ? argv.map(shellSingleQuote).join(' ') : `sh -c ${shellSingleQuote(shell ?? '')}`
}
/** What the launcher prints before it runs, so the terminal says what it is doing. Env values are
* never printed (an envFile is often where the secrets live). */
export function displayCommand(plan: ProcessPlan): string {
return plan.argv ? plan.argv.map((a) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(a) ? a : shellSingleQuote(a))).join(' ') : (plan.shell ?? '')
}
/**
* The POSIX sh launcher the node's terminal runs (`sh '<path>'`). Every value is single-quoted.
*
* - It records its own pid (the run's status), and its exit status when the run ends.
* - It traps INT/TERM with a no-op HANDLER (never `''`, which children would inherit as "ignore"):
* Ctrl+C / Stop interrupts the program, and the launcher survives to record the status.
* - preLaunchTask steps run first, each in a subshell with its own cwd/env; a failing task stops
* the run, like VS Code.
*/
export function buildLauncher(plan: ProcessPlan, envFileVars: Record<string, string>, paths: LauncherPaths): string {
const q = shellSingleQuote
const lines: string[] = [
'#!/bin/sh',
`# nodeterm run configuration: ${plan.name.replace(/[\r\n]/g, ' ')}`,
`echo $$ > ${q(paths.pidFile)}`,
`rm -f ${q(paths.exitFile)}`,
"trap ':' INT TERM",
`nt_end() { rm -f ${q(paths.pidFile)}; echo "$1" > ${q(paths.exitFile)}; exit "$1"; }`
]
for (const t of plan.preTasks) {
lines.push(
`printf '\\033[2m▶ task: %s\\033[0m\\n' ${q(t.label)}`,
`( cd ${q(t.cwd)} || exit 1`,
...exports(t.env).map((l) => ` ${l}`),
` ${cmdLine(t.argv, t.shell)}`,
')',
'nt_rc=$?',
`if [ "$nt_rc" -ne 0 ]; then printf '\\033[31mTask %s failed (exit %s).\\033[0m\\n' ${q(t.label)} "$nt_rc"; nt_end "$nt_rc"; fi`
)
}
lines.push(
`cd ${q(plan.cwd)} || nt_end 1`,
...exports({ ...envFileVars, ...plan.env }),
`printf '\\033[2m▶ %s\\033[0m\\n' ${q(displayCommand(plan))}`,
cmdLine(plan.argv, plan.shell),
'nt_end $?'
)
return lines.join('\n') + '\n'
}
// ─── Presentation ────────────────────────────────────────────────────────────────────────────
/** Last path segment, for titles and the folder picker. */
export function runDirLabel(dir: string): string {
const parts = dir.replace(/[\\/]+$/, '').split(/[\\/]/)
const last = parts[parts.length - 1] || dir
const parent = parts[parts.length - 2]
return parent && parent.endsWith('.worktrees') ? `${parent.replace(/\.worktrees$/, '')} · ${last}` : last
}
/** The node title while it is still ours to set (`titleAuto`). */
export function runNodeTitle(dir: string, configName?: string): string {
return configName ? `${configName} · ${runDirLabel(dir)}` : `Run · ${runDirLabel(dir)}`
}
/** Which other run nodes already use `deviceId` — for the "already in use" warning. */
export function deviceClaims(
nodes: ReadonlyArray<{ id: string; title?: string; runConfig?: Pick<RunNodeConfig, 'deviceId'> }>,
selfId: string,
deviceId: string | undefined
): string[] {
if (!deviceId) return []
return nodes.filter((n) => n.id !== selfId && n.runConfig?.deviceId === deviceId).map((n) => n.title || n.id)
}
// ─── Host API ────────────────────────────────────────────────────────────────────────────────
export type RunDeviceKind = 'simulator' | 'emulator' | 'device' | 'desktop' | 'web'
export interface RunDevice {
id: string
name: string
kind: RunDeviceKind
/** iOS simulators only. */
state?: 'booted' | 'shutdown'
/** "iOS 27.1" for a simulator, the target platform otherwise. */
platform?: string
}
export interface RunDevicesResult {
devices: RunDevice[]
error?: string
}
export interface RunEntriesResult {
/** Whether the folder has a readable `.vscode/launch.json`. */
found: boolean
entries: LaunchEntry[]
/** Set when launch.json exists but could not be parsed. */
error?: string
isFlutterProject: boolean
}
export type RunStartResult =
| { ok: true; kind: 'process'; command: string; hotReload: boolean }
| { ok: true; kind: 'browser'; url: string }
| { ok: true; kind: 'compound'; members: string[] }
| { ok: false; error: string }
export interface RunStatus {
running: boolean
/** The last run's exit status, when it ended (null while running / unknown). */
exitCode: number | null
}
export interface RunConfigApi {
/** The configurations (and compounds) in `<dir>/.vscode/launch.json`, described. */
entries(dir: string): Promise<RunEntriesResult>
/** iOS simulators plus `flutter devices`. `refresh` bypasses the short cache. */
devices(refresh?: boolean): Promise<RunDevicesResult>
/** Boot an iOS simulator (no-op when already booted) and open Simulator.app. */
bootDevice(udid: string): Promise<boolean>
/** Folders near `dir` that have a launch.json or are Flutter checkouts. */
discoverProjects(dir: string): Promise<string[]>
/** Prepare a run: write the launcher and return the line to type (or a URL / compound members).
* `attach`: `flutter attach` to the app already running on the node's device instead (the
* no-rebuild folder switch). */
start(nodeId: string, config: RunNodeConfig, opts?: { attach?: boolean }): Promise<RunStartResult>
status(nodeId: string): Promise<RunStatus>
/** Interrupt the run (SIGINT, or SIGTERM when `force`). False when nothing is running. */
stop(nodeId: string, force?: boolean): Promise<boolean>
/** Flutter: hot reload (SIGUSR1) / hot restart (SIGUSR2). */
signal(nodeId: string, kind: 'reload' | 'restart'): Promise<boolean>
/** Flutter: start (dir) or stop (null) reload-on-save. */
watch(nodeId: string, dir: string | null): Promise<void>
}