Make Kitty remote commands dry-run testable

Kitty remote control needs argv-safe builders that tests can assert without a running Kitty daemon. This adds deterministic command construction for launch, focus, close, send-text, ls, and version probes while preserving the existing backend aliases.

Constraint: Tests must not require a live Kitty instance

Rejected: Build shell strings for send-text | stdin input keeps user text out of argv and avoids shell quoting

Confidence: high

Scope-risk: narrow

Directive: Keep Kitty builders pure; runtime execution belongs in createBackend

Tested: node --test test/terminal-kitty.test.js test/cockpit-terminal-backend.test.js

Tested: openspec validate --specs

Tested: git diff --check

Not-tested: npm test has existing baseline failures in agents launch/lifecycle/session tests

Author: NagyVikt

openspec/changes/agent-codex-dry-run-testable-kitty-command-builders-2026-04-30-14-10/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-30

openspec/changes/agent-codex-dry-run-testable-kitty-command-builders-2026-04-30-14-10/notes.md

@@ -0,0 +1,10 @@
+# agent-codex-dry-run-testable-kitty-command-builders-2026-04-30-14-10 (minimal / T1)
+
+- Add pure Kitty remote-control command builders in `src/terminal/kitty.js` for launch, focus, close, send-text, ls, and version probes.
+- Keep commands as `{ cmd, args }` argv arrays with optional stdin `input`; do not require a live Kitty instance to test construction.
+- Support cwd/title values with spaces, deterministic env ordering, command argv, id/title matches, control windows, and agent pane launches.
+- Verification:
+  - `node --test test/terminal-kitty.test.js test/cockpit-terminal-backend.test.js`
+  - `openspec validate --specs`
+  - `git diff --check`
+  - `npm test` ran 446 tests: 438 pass, 7 baseline failures, 1 skip. Failures are in `test/agents-launch.test.js`, `test/agents-lifecycle.test.js`, and `test/agents-sessions.test.js`.

src/terminal/kitty.js

@@ -29,8 +29,9 @@ function firstText(...values) {
   return '';
 }
 
-function kittyBin(config = {}) {
-  return text(config.kittyBin || process.env.GUARDEX_KITTY_BIN, DEFAULT_KITTY_BIN);
+function kittyBin(config = {}, options = {}) {
+  const envValue = options.allowEnv ? process.env.GUARDEX_KITTY_BIN : '';
+  return text(config.kittyBin || envValue, DEFAULT_KITTY_BIN);
 }
 
 function commandShape(args, config = {}) {
@@ -40,31 +41,128 @@ function commandShape(args, config = {}) {
   };
 }
 
-function appendShellCommand(args, command) {
-  const normalized = text(command);
-  if (normalized) {
-    args.push('--', 'sh', '-lc', normalized);
+function commandShapeWithEnv(args, config = {}) {
+  return {
+    cmd: kittyBin(config, { allowEnv: true }),
+    args,
+  };
+}
+
+function appendOption(args, flag, value) {
+  const normalized = text(value);
+  if (normalized) args.push(flag, normalized);
+  return args;
+}
+
+function normalizeEnvEntries(env = {}) {
+  if (!env) return [];
+  if (Array.isArray(env)) {
+    return env.map((entry) => {
+      if (Array.isArray(entry)) {
+        const key = requireText(entry[0], 'kitty env key');
+        const value = entry.length > 1 && entry[1] !== undefined && entry[1] !== null ? String(entry[1]) : '';
+        return `${key}=${value}`;
+      }
+      return requireText(entry, 'kitty env');
+    });
+  }
+  if (typeof env !== 'object') {
+    throw new TypeError('kitty env must be an object, array, or undefined');
+  }
+  return Object.keys(env)
+    .sort()
+    .map((key) => `${requireText(key, 'kitty env key')}=${env[key] === undefined || env[key] === null ? '' : String(env[key])}`);
+}
+
+function appendEnv(args, env) {
+  for (const entry of normalizeEnvEntries(env)) {
+    args.push('--env', entry);
   }
   return args;
 }
 
+function normalizeCommandArgv(options = {}) {
+  const commandArgv = options.argv || options.commandArgv || (Array.isArray(options.command) ? options.command : undefined);
+  if (commandArgv === undefined || commandArgv === null) return [];
+  if (!Array.isArray(commandArgv)) {
+    throw new TypeError('kitty command argv must be an array');
+  }
+  return commandArgv.map((arg) => {
+    if (arg === undefined || arg === null) {
+      throw new TypeError('kitty command argv values must be strings');
+    }
+    return String(arg);
+  });
+}
+
+function appendCommandArgv(args, options = {}) {
+  const commandArgv = normalizeCommandArgv(options);
+  if (commandArgv.length > 0) args.push('--', ...commandArgv);
+  return args;
+}
+
+function shellCommandArgv(command) {
+  const normalized = text(command);
+  return normalized ? ['sh', '-lc', normalized] : [];
+}
+
+function launchTitle(options = {}) {
+  const session = options.session && typeof options.session === 'object' ? options.session : {};
+  return firstText(
+    options.title,
+    options.control || options.role === 'control' ? DEFAULT_COCKPIT_TITLE : '',
+    options.agent || options.role === 'agent' || options.session ? agentTitle(session) : '',
+    options.terminal || options.role === 'terminal' ? DEFAULT_TERMINAL_TITLE : '',
+  );
+}
+
+function launchCwd(options = {}) {
+  const session = options.session && typeof options.session === 'object' ? options.session : {};
+  return firstText(options.cwd, options.repoRoot, options.worktree, session.worktreePath, session.path);
+}
+
+function buildKittyLaunchCommand(options = {}) {
+  const args = ['@', 'launch'];
+  const type = text(options.type, 'window');
+  const location = firstText(options.location, options.pane ? 'vsplit' : '');
+  const cwd = launchCwd(options);
+  const title = launchTitle(options);
+
+  if (type) args.push(`--type=${type}`);
+  if (location) args.push(`--location=${location}`);
+  appendOption(args, '--cwd', cwd);
+  appendOption(args, '--title', title);
+  appendEnv(args, options.env);
+  appendCommandArgv(args, options);
+
+  const shape = commandShape(args, options);
+  if (Object.prototype.hasOwnProperty.call(options, 'input')) {
+    shape.input = options.input === undefined || options.input === null ? '' : String(options.input);
+  }
+  return shape;
+}
+
+function buildKittyLsCommand(options = {}) {
+  return commandShape(['@', 'ls'], options);
+}
+
+function buildKittyVersionCommand(options = {}) {
+  return commandShape(['--version'], options);
+}
+
 function buildAvailabilityCommand(config = {}) {
-  return commandShape(['@', 'ls'], config);
+  return commandShapeWithEnv(buildKittyLsCommand().args, config);
 }
 
 function buildOpenCockpitLayoutCommand(options = {}, config = {}) {
   const repoRoot = requireText(options.repoRoot, 'kitty cockpit repoRoot');
-  const args = [
-    '@',
-    'launch',
-    '--type=window',
-    '--cwd',
-    repoRoot,
-    '--title',
-    text(options.title, DEFAULT_COCKPIT_TITLE),
-  ];
-  appendShellCommand(args, options.command);
-  return commandShape(args, config);
+  return buildKittyLaunchCommand({
+    role: 'control',
+    cwd: repoRoot,
+    title: text(options.title, DEFAULT_COCKPIT_TITLE),
+    argv: shellCommandArgv(options.command),
+    kittyBin: kittyBin(config, { allowEnv: true }),
+  });
 }
 
 function agentTitle(session = {}, title) {
@@ -82,57 +180,74 @@ function agentTitle(session = {}, title) {
 function buildLaunchAgentPaneCommand(options = {}, config = {}) {
   const session = options.session && typeof options.session === 'object' ? options.session : {};
   const cwd = requireText(firstText(options.worktree, session.worktreePath, session.path), 'kitty agent worktree');
-  const args = [
-    '@',
-    'launch',
-    '--type=window',
-    '--location=vsplit',
-    '--cwd',
+  return buildKittyLaunchCommand({
+    role: 'agent',
+    pane: true,
     cwd,
-    '--title',
-    agentTitle(session, options.title),
-  ];
-  appendShellCommand(args, options.command);
-  return commandShape(args, config);
+    title: agentTitle(session, options.title),
+    argv: shellCommandArgv(options.command),
+    kittyBin: kittyBin(config, { allowEnv: true }),
+  });
 }
 
 function buildLaunchTerminalPaneCommand(options = {}, config = {}) {
   const cwd = requireText(options.cwd, 'kitty terminal cwd');
-  const args = [
-    '@',
-    'launch',
-    '--type=window',
-    '--location=vsplit',
-    '--cwd',
+  return buildKittyLaunchCommand({
+    role: 'terminal',
+    pane: true,
     cwd,
-    '--title',
-    text(options.title, DEFAULT_TERMINAL_TITLE),
-  ];
-  appendShellCommand(args, options.command);
-  return commandShape(args, config);
+    title: text(options.title, DEFAULT_TERMINAL_TITLE),
+    argv: shellCommandArgv(options.command),
+    kittyBin: kittyBin(config, { allowEnv: true }),
+  });
 }
 
-function targetId(target) {
-  const raw = target && typeof target === 'object'
-    ? firstText(target.id, target.windowId, target.paneId, target.target)
-    : text(target);
-  return requireText(raw, 'kitty target id');
+function targetMatch(target) {
+  if (target && typeof target === 'object') {
+    const explicitMatch = firstText(target.match, target.kittyMatch);
+    if (explicitMatch) return explicitMatch;
+
+    const id = firstText(target.id, target.windowId, target.kittyWindowId, target.paneId, target.target);
+    if (id) return `id:${id}`;
+
+    const title = firstText(target.title, target.windowTitle, target.kittyTitle);
+    if (title) return `title:${title}`;
+  } else {
+    const id = text(target);
+    if (id) return `id:${id}`;
+  }
+  throw new TypeError('kitty target must include id, title, or match');
 }
 
-function targetMatch(target) {
-  return `id:${targetId(target)}`;
+function buildKittyFocusCommand(target, options = {}) {
+  return commandShape(['@', 'focus-window', '--match', targetMatch(target)], options);
+}
+
+function buildKittyCloseCommand(target, options = {}) {
+  return commandShape(['@', 'close-window', '--match', targetMatch(target)], options);
+}
+
+function buildKittySendTextCommand(target, options = {}) {
+  const shape = commandShape(['@', 'send-text', '--match', targetMatch(target), '--stdin'], options);
+  if (Object.prototype.hasOwnProperty.call(options, 'input') || Object.prototype.hasOwnProperty.call(options, 'text') || options.submit) {
+    shape.input = sendTextInput(
+      Object.prototype.hasOwnProperty.call(options, 'input') ? options.input : options.text,
+      { submit: options.submit },
+    );
+  }
+  return shape;
 }
 
 function buildFocusPaneCommand(target, config = {}) {
-  return commandShape(['@', 'focus-window', '--match', targetMatch(target)], config);
+  return buildKittyFocusCommand(target, { kittyBin: kittyBin(config, { allowEnv: true }) });
 }
 
 function buildClosePaneCommand(target, config = {}) {
-  return commandShape(['@', 'close-window', '--match', targetMatch(target)], config);
+  return buildKittyCloseCommand(target, { kittyBin: kittyBin(config, { allowEnv: true }) });
 }
 
 function buildSendTextCommand(target, config = {}) {
-  return commandShape(['@', 'send-text', '--match', targetMatch(target), '--stdin'], config);
+  return buildKittySendTextCommand(target, { kittyBin: kittyBin(config, { allowEnv: true }) });
 }
 
 function sendTextInput(value, options = {}) {
@@ -200,6 +315,12 @@ function createBackend(config = {}) {
 
 module.exports = {
   DEFAULT_KITTY_BIN,
+  buildKittyLaunchCommand,
+  buildKittyFocusCommand,
+  buildKittyCloseCommand,
+  buildKittySendTextCommand,
+  buildKittyLsCommand,
+  buildKittyVersionCommand,
   buildAvailabilityCommand,
   buildOpenCockpitLayoutCommand,
   buildLaunchAgentPaneCommand,