Isolate Kitty runtime control behind argv helpers (#509)

The cockpit needs a lower-level Kitty surface before UI code can share dmux-style control paths. This adds command and runtime helpers that build argv-shaped Kitty remote-control commands, support dry-run planning, and keep tests independent from a local Kitty install.

Constraint: User requested no cockpit behavior changes and only four files edited

Rejected: Wire cockpit to the new adapter now | requested low-level layer only

Confidence: high

Scope-risk: narrow

Directive: Keep cockpit UI wiring separate from this low-level adapter until the behavior layer is ready to migrate

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

Tested: git diff --check

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>
Co-authored-by: OmX <omx@oh-my-codex.dev>

Author: 3 people

src/kitty/command.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const cp = require('node:child_process');
+
+const DEFAULT_KITTY_BIN = 'kitty';
+
+function text(value, fallback = '') {
+  if (typeof value === 'string') return value.trim() || fallback;
+  if (value === null || value === undefined) return fallback;
+  return String(value).trim() || fallback;
+}
+
+function resolveKittyBin(options = {}) {
+  return text(options.kittyBin || options.bin || process.env.GUARDEX_KITTY_BIN, DEFAULT_KITTY_BIN);
+}
+
+function assertArgs(args) {
+  if (!Array.isArray(args)) {
+    throw new TypeError('kitty args must be an array');
+  }
+  for (const arg of args) {
+    if (typeof arg !== 'string') {
+      throw new TypeError('kitty args must contain only strings');
+    }
+  }
+}
+
+function commandShape(cmd, args, options = {}) {
+  const command = {
+    cmd,
+    args: [...args],
+  };
+  if (Object.prototype.hasOwnProperty.call(options, 'input')) {
+    command.input = options.input === undefined || options.input === null ? '' : String(options.input);
+  }
+  return command;
+}
+
+function runnerOptions(options = {}) {
+  return {
+    cwd: options.cwd,
+    env: options.env ? { ...process.env, ...options.env } : process.env,
+    encoding: 'utf8',
+    input: options.input,
+    stdio: options.stdio || 'pipe',
+    timeout: options.timeout,
+  };
+}
+
+function defaultRunner(cmd, args, options = {}) {
+  return cp.spawnSync(cmd, args, runnerOptions(options));
+}
+
+function runnerFor(options = {}) {
+  if (typeof options.runner === 'function') return options.runner;
+  if (options.runtime && typeof options.runtime.run === 'function') return options.runtime.run;
+  return defaultRunner;
+}
+
+function dryRunOptions(options = {}) {
+  const result = {};
+  for (const key of ['cwd', 'env', 'input', 'stdio', 'timeout']) {
+    if (Object.prototype.hasOwnProperty.call(options, key) && options[key] !== undefined) {
+      result[key] = options[key];
+    }
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function runKitty(args, options = {}) {
+  assertArgs(args);
+  const cmd = resolveKittyBin(options);
+  const command = commandShape(cmd, args, options);
+
+  if (options.dryRun) {
+    const result = {
+      dryRun: true,
+      commands: [command],
+    };
+    const optionsForReport = dryRunOptions(options);
+    if (optionsForReport) result.options = optionsForReport;
+    return result;
+  }
+
+  return runnerFor(options)(cmd, [...args], runnerOptions(options));
+}
+
+function isKittyAvailable(options = {}) {
+  const result = runKitty(['@', 'ls'], {
+    ...options,
+    stdio: 'pipe',
+  });
+  if (result && result.dryRun) return result;
+  return Boolean(result && result.status === 0 && !result.error);
+}
+
+module.exports = {
+  isKittyAvailable,
+  runKitty,
+  resolveKittyBin,
+};

src/kitty/runtime.js

@@ -0,0 +1,187 @@
+'use strict';
+
+const {
+  isKittyAvailable,
+  resolveKittyBin,
+  runKitty,
+} = require('./command');
+
+function text(value, fallback = '') {
+  if (typeof value === 'string') return value.trim() || fallback;
+  if (value === null || value === undefined) return fallback;
+  return String(value).trim() || fallback;
+}
+
+function requireText(value, name) {
+  const normalized = text(value);
+  if (!normalized) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+  return normalized;
+}
+
+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 = {}) {
+  if (options.argv === undefined && options.commandArgv === undefined && Object.prototype.hasOwnProperty.call(options, 'command') && !Array.isArray(options.command)) {
+    throw new TypeError('kitty command argv must be an array');
+  }
+  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 commandShape(args, options = {}) {
+  const command = {
+    cmd: resolveKittyBin(options),
+    args,
+  };
+  if (Object.prototype.hasOwnProperty.call(options, 'input')) {
+    command.input = options.input === undefined || options.input === null ? '' : String(options.input);
+  }
+  return command;
+}
+
+function buildKittyLaunchCommand(options = {}) {
+  const args = ['@', 'launch'];
+  appendOption(args, '--type', text(options.type, 'window'));
+  appendOption(args, '--location', options.location);
+  appendOption(args, '--cwd', options.cwd);
+  appendOption(args, '--title', options.title);
+  appendEnv(args, options.env);
+  appendCommandArgv(args, options);
+  return commandShape(args, options);
+}
+
+function runCommand(command, action, options = {}) {
+  const runOptions = {
+    ...options,
+    kittyBin: command.cmd,
+    action,
+  };
+  if (Object.prototype.hasOwnProperty.call(command, 'input')) {
+    runOptions.input = command.input;
+  } else if (Object.prototype.hasOwnProperty.call(options, 'input')) {
+    runOptions.input = options.input;
+  }
+  return runKitty(command.args, runOptions);
+}
+
+function launchKittyWindow(options = {}) {
+  return runCommand(
+    buildKittyLaunchCommand({
+      ...options,
+      type: text(options.type, 'window'),
+    }),
+    'launch-window',
+    options,
+  );
+}
+
+function launchKittyTab(options = {}) {
+  return runCommand(
+    buildKittyLaunchCommand({
+      ...options,
+      type: 'tab',
+    }),
+    'launch-tab',
+    options,
+  );
+}
+
+function launchKittyPane(options = {}) {
+  return runCommand(
+    buildKittyLaunchCommand({
+      ...options,
+      type: 'window',
+      location: text(options.location, 'vsplit'),
+    }),
+    'launch-pane',
+    options,
+  );
+}
+
+function targetMatch(target) {
+  if (target && typeof target === 'object') {
+    const explicit = text(target.match || target.kittyMatch);
+    if (explicit) return explicit;
+
+    const id = text(target.id || target.windowId || target.kittyWindowId || target.paneId || target.target);
+    if (id) return `id:${id}`;
+
+    const title = text(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 sendTextToKitty(target, value, options = {}) {
+  return runKitty(['@', 'send-text', '--match', targetMatch(target), '--stdin'], {
+    ...options,
+    input: value === undefined || value === null ? '' : String(value),
+    stdio: options.stdio || 'pipe',
+  });
+}
+
+function setKittyWindowTitle(target, title, options = {}) {
+  return runKitty(['@', 'set-window-title', '--match', targetMatch(target), requireText(title, 'kitty window title')], options);
+}
+
+module.exports = {
+  isKittyAvailable,
+  runKitty,
+  buildKittyLaunchCommand,
+  launchKittyWindow,
+  launchKittyTab,
+  launchKittyPane,
+  sendTextToKitty,
+  setKittyWindowTitle,
+};