@myagentroam/node 0.12.0 → 0.12.1

package/dist/code-navigation/symbol-maps.js

@@ -0,0 +1,257 @@
+/**
+ * Fixed source maps generated from `Universal Ctags ab95af1 --list-maps`.
+ * This remains pure metadata: Node owns the executable and index lifecycle.
+ */
+export const symbolNavigationMaps = [
+    { id: 'Abaqus', fileNamePatterns: ['*.inp'] },
+    { id: 'Abc', fileNamePatterns: ['*.abc', '*.abc'] },
+    { id: 'Ada', fileNamePatterns: ['*.adb', '*.ads', '*.Ada', '*.ada'] },
+    { id: 'Ant', fileNamePatterns: ['build.xml', '*.build.xml', '*.ant', '*.xml'] },
+    {
+        id: 'Asciidoc',
+        fileNamePatterns: ['*.asc', '*.adoc', '*.asciidoc', '*.asc', '*.adoc', '*.asciidoc']
+    },
+    {
+        id: 'Asm',
+        fileNamePatterns: [
+            '*.A51',
+            '*.29[kK]',
+            '*.[68][68][kKsSxX]',
+            '*.[xX][68][68]',
+            '*.asm',
+            '*.ASM',
+            '*.s',
+            '*.S'
+        ]
+    },
+    { id: 'Asp', fileNamePatterns: ['*.asp', '*.asa'] },
+    { id: 'Autoconf', fileNamePatterns: ['configure.in', '*.ac'] },
+    { id: 'AutoIt', fileNamePatterns: ['*.au3', '*.AU3', '*.aU3', '*.Au3'] },
+    { id: 'Automake', fileNamePatterns: ['Makefile.am', 'GNUmakefile.am', '*.am'] },
+    { id: 'Awk', fileNamePatterns: ['*.awk', '*.gawk', '*.mawk'] },
+    { id: 'Basic', fileNamePatterns: ['*.bas', '*.bi', '*.bm', '*.bb', '*.pb'] },
+    { id: 'Bats', fileNamePatterns: ['*.bats'] },
+    { id: 'BETA', fileNamePatterns: ['*.bet'] },
+    { id: 'BibTeX', fileNamePatterns: ['*.bib'] },
+    { id: 'Clojure', fileNamePatterns: ['*.clj', '*.cljs', '*.cljc'] },
+    { id: 'CMake', fileNamePatterns: ['CMakeLists.txt', '*.cmake'] },
+    { id: 'C', fileNamePatterns: ['*.c'] },
+    { id: 'Cargo', fileNamePatterns: ['Cargo.toml'] },
+    {
+        id: 'C++',
+        fileNamePatterns: [
+            '*.c++',
+            '*.cc',
+            '*.cp',
+            '*.cpp',
+            '*.cxx',
+            '*.h',
+            '*.h++',
+            '*.hh',
+            '*.hp',
+            '*.hpp',
+            '*.hxx',
+            '*.inl',
+            '*.C',
+            '*.H',
+            '*.CPP',
+            '*.CXX'
+        ]
+    },
+    { id: 'CSS', fileNamePatterns: ['*.css'] },
+    { id: 'C#', fileNamePatterns: ['*.cs'] },
+    { id: 'Ctags', fileNamePatterns: ['*.ctags'] },
+    { id: 'Cobol', fileNamePatterns: ['*.cbl', '*.cob', '*.CBL', '*.COB'] },
+    { id: 'CUDA', fileNamePatterns: ['*.cu', '*.cuh'] },
+    { id: 'D', fileNamePatterns: ['*.d', '*.di'] },
+    { id: 'DBusService', fileNamePatterns: ['*.service'] },
+    { id: 'Diff', fileNamePatterns: ['*.diff', '*.patch'] },
+    { id: 'DTD', fileNamePatterns: ['*.dtd', '*.mod'] },
+    { id: 'DTS', fileNamePatterns: ['*.dts', '*.dtsi'] },
+    { id: 'DosBatch', fileNamePatterns: ['*.bat', '*.cmd'] },
+    { id: 'Eiffel', fileNamePatterns: ['*.e'] },
+    { id: 'Elixir', fileNamePatterns: ['*.ex', '*.exs'] },
+    { id: 'EmacsLisp', fileNamePatterns: ['*.el'] },
+    { id: 'Erlang', fileNamePatterns: ['*.erl', '*.ERL', '*.hrl', '*.HRL'] },
+    { id: 'Falcon', fileNamePatterns: ['*.fal', '*.ftd'] },
+    { id: 'Flex', fileNamePatterns: ['*.as', '*.mxml'] },
+    { id: 'Forth', fileNamePatterns: ['*.fth', '*.forth', '*.fs', '*.4th', '*.f'] },
+    {
+        id: 'Fortran',
+        fileNamePatterns: [
+            '*.f',
+            '*.for',
+            '*.ftn',
+            '*.f77',
+            '*.f90',
+            '*.f95',
+            '*.f03',
+            '*.f08',
+            '*.f15',
+            '*.F',
+            '*.FOR',
+            '*.FTN',
+            '*.F77',
+            '*.F90',
+            '*.F95',
+            '*.F03',
+            '*.F08',
+            '*.F15'
+        ]
+    },
+    { id: 'Fypp', fileNamePatterns: ['*.fy'] },
+    { id: 'Gdbinit', fileNamePatterns: ['.gdbinit', '*.gdb'] },
+    { id: 'GDScript', fileNamePatterns: ['*.gd'] },
+    { id: 'GemSpec', fileNamePatterns: ['*.gemspec'] },
+    { id: 'Go', fileNamePatterns: ['*.go'] },
+    { id: 'GoMod', fileNamePatterns: ['go.mod'] },
+    { id: 'GPerf', fileNamePatterns: ['*.perf', '*.gperf'] },
+    { id: 'Haskell', fileNamePatterns: ['*.hs'] },
+    { id: 'Haxe', fileNamePatterns: ['*.hx'] },
+    { id: 'HTML', fileNamePatterns: ['*.htm', '*.html'] },
+    { id: 'Iniconf', fileNamePatterns: ['*.ini', '*.conf'] },
+    { id: 'Inko', fileNamePatterns: ['*.inko'] },
+    { id: 'ITcl', fileNamePatterns: ['*.itcl'] },
+    { id: 'Java', fileNamePatterns: ['*.java'] },
+    { id: 'JavaProperties', fileNamePatterns: ['*.properties'] },
+    { id: 'JavaScript', fileNamePatterns: ['*.js', '*.jsx', '*.mjs'] },
+    { id: 'JSON', fileNamePatterns: ['*.json'] },
+    { id: 'Julia', fileNamePatterns: ['*.jl'] },
+    { id: 'Kconfig', fileNamePatterns: ['Kconfig*'] },
+    {
+        id: 'LdScript',
+        fileNamePatterns: ['*.lds.S', '*.ld.S', 'ld.script', '*.lds', '*.scr', '*.ld', '*.ldi']
+    },
+    { id: 'LEX', fileNamePatterns: ['*.lex', '*.l'] },
+    { id: 'Lisp', fileNamePatterns: ['*.cl', '*.clisp', '*.l', '*.lisp', '*.lsp'] },
+    { id: 'LiterateHaskell', fileNamePatterns: ['*.lhs'] },
+    { id: 'Lua', fileNamePatterns: ['*.lua'] },
+    { id: 'M4', fileNamePatterns: ['*.m4', '*.spt'] },
+    {
+        id: 'Man',
+        fileNamePatterns: [
+            '*.man',
+            '*.1',
+            '*.2',
+            '*.3',
+            '*.4',
+            '*.5',
+            '*.6',
+            '*.7',
+            '*.8',
+            '*.9',
+            '*.3pm',
+            '*.3stap',
+            '*.7stap'
+        ]
+    },
+    { id: 'Make', fileNamePatterns: ['[Mm]akefile', 'GNUmakefile', '*.mak', '*.mk'] },
+    { id: 'Markdown', fileNamePatterns: ['*.md', '*.markdown'] },
+    { id: 'MatLab', fileNamePatterns: ['*.m'] },
+    { id: 'Meson', fileNamePatterns: ['meson.build'] },
+    { id: 'MesonOptions', fileNamePatterns: ['meson_options.txt'] },
+    { id: 'Myrddin', fileNamePatterns: ['*.myr'] },
+    { id: 'Nftables', fileNamePatterns: ['*.nft'] },
+    { id: 'NSIS', fileNamePatterns: ['*.nsi', '*.nsh'] },
+    { id: 'ObjectiveC', fileNamePatterns: ['*.mm', '*.m', '*.h'] },
+    { id: 'OCaml', fileNamePatterns: ['*.ml', '*.mli', '*.aug'] },
+    { id: 'Odin', fileNamePatterns: ['*.odin'] },
+    { id: 'Org', fileNamePatterns: ['*.org'] },
+    { id: 'Passwd', fileNamePatterns: ['passwd'] },
+    { id: 'Pascal', fileNamePatterns: ['*.p', '*.pas'] },
+    { id: 'Perl', fileNamePatterns: ['*.pl', '*.pm', '*.ph', '*.plx', '*.perl'] },
+    { id: 'Perl6', fileNamePatterns: ['*.p6', '*.pm6', '*.pm', '*.pl6', '*.t6'] },
+    { id: 'PHP', fileNamePatterns: ['*.php', '*.php3', '*.php4', '*.php5', '*.php7', '*.phtml'] },
+    { id: 'PkgConfig', fileNamePatterns: ['*.pc'] },
+    { id: 'Pod', fileNamePatterns: ['*.pod'] },
+    { id: 'PowerShell', fileNamePatterns: ['*.ps1', '*.psm1'] },
+    { id: 'Prolog', fileNamePatterns: ['*.pl', '*.pro'] },
+    { id: 'Protobuf', fileNamePatterns: ['*.proto'] },
+    { id: 'PuppetManifest', fileNamePatterns: ['*.pp'] },
+    {
+        id: 'Python',
+        fileNamePatterns: ['*.py', '*.pyw', '*.pyx', '*.pxd', '*.pxi', '*.scons', '*.wsgi']
+    },
+    { id: 'PythonEntryPoints', fileNamePatterns: ['entry_points.txt'] },
+    { id: 'QemuHX', fileNamePatterns: ['*.hx'] },
+    { id: 'Quarto', fileNamePatterns: ['*.qmd'] },
+    { id: 'RMarkdown', fileNamePatterns: ['*.rmd'] },
+    { id: 'R', fileNamePatterns: ['*.r', '*.R', '*.s', '*.q'] },
+    { id: 'Rake', fileNamePatterns: ['Rakefile', '*.rake'] },
+    { id: 'Raku', fileNamePatterns: ['*.raku', '*.rakumod', '*.rakutest', '*.rakudoc'] },
+    { id: 'REXX', fileNamePatterns: ['*.cmd', '*.rexx', '*.rx'] },
+    { id: 'Robot', fileNamePatterns: ['*.robot'] },
+    {
+        id: 'RpmMacros',
+        fileNamePatterns: ['%(.*/)?macros\\.d/macros\\.([^/]+)$%', '*.rpmmacros']
+    },
+    { id: 'RpmSpec', fileNamePatterns: ['*.spec'] },
+    { id: 'ReStructuredText', fileNamePatterns: ['*.rest', '*.reST', '*.rst'] },
+    { id: 'Ruby', fileNamePatterns: ['*.rb', '*.ruby'] },
+    { id: 'Rust', fileNamePatterns: ['*.rs'] },
+    {
+        id: 'Scheme',
+        fileNamePatterns: ['*.SCM', '*.SM', '*.sch', '*.scheme', '*.scm', '*.sm', '*.rkt']
+    },
+    { id: 'SCSS', fileNamePatterns: ['*.scss'] },
+    { id: 'SELinuxInterface', fileNamePatterns: ['*.if'] },
+    { id: 'SELinuxTypeEnforcement', fileNamePatterns: ['*.te'] },
+    { id: 'SINEX', fileNamePatterns: ['*.snx', '*.sinex'] },
+    { id: 'Sh', fileNamePatterns: ['*.sh', '*.SH', '*.bsh', '*.bash', '*.ksh', '*.ash'] },
+    { id: 'SLang', fileNamePatterns: ['*.sl'] },
+    { id: 'SML', fileNamePatterns: ['*.sml', '*.sig'] },
+    { id: 'Scdoc', fileNamePatterns: ['*.scd'] },
+    { id: 'SQL', fileNamePatterns: ['*.sql'] },
+    {
+        id: 'SystemdUnit',
+        fileNamePatterns: [
+            '*.service',
+            '*.socket',
+            '*.device',
+            '*.mount',
+            '*.automount',
+            '*.swap',
+            '*.target',
+            '*.path',
+            '*.timer',
+            '*.snapshot',
+            '*.slice'
+        ]
+    },
+    { id: 'SystemTap', fileNamePatterns: ['*.stp', '*.stpm'] },
+    { id: 'Tcl', fileNamePatterns: ['*.tcl', '*.tk', '*.wish', '*.exp'] },
+    { id: 'Terraform', fileNamePatterns: ['*.tf'] },
+    { id: 'TerraformVariables', fileNamePatterns: ['*.tfvars'] },
+    { id: 'Tex', fileNamePatterns: ['*.tex'] },
+    { id: 'TTCN', fileNamePatterns: ['*.ttcn', '*.ttcn3'] },
+    { id: 'Txt2tags', fileNamePatterns: ['*.t2t', '*.t2t'] },
+    { id: 'TypeScript', fileNamePatterns: ['*.ts'] },
+    { id: 'TypeSpec', fileNamePatterns: ['*.tsp'] },
+    { id: 'V', fileNamePatterns: ['*.v'] },
+    { id: 'Vera', fileNamePatterns: ['*.vr', '*.vri', '*.vrh'] },
+    { id: 'Verilog', fileNamePatterns: ['*.v', '*.vh'] },
+    { id: 'SystemVerilog', fileNamePatterns: ['*.sv', '*.svh', '*.svi'] },
+    { id: 'VHDL', fileNamePatterns: ['*.vhdl', '*.vhd'] },
+    { id: 'Vim', fileNamePatterns: ['vimrc', '[._]vimrc', 'gvimrc', '[._]gvimrc', '*.vim', '*.vba'] },
+    { id: 'WindRes', fileNamePatterns: ['*.rc'] },
+    { id: 'YACC', fileNamePatterns: ['*.y'] },
+    { id: 'YumRepo', fileNamePatterns: ['*.repo'] },
+    { id: 'Zephir', fileNamePatterns: ['*.zep'] },
+    { id: 'Zsh', fileNamePatterns: ['*.zsh'] },
+    { id: 'DBusIntrospect', fileNamePatterns: ['*.xml'] },
+    { id: 'Glade', fileNamePatterns: ['*.glade'] },
+    { id: 'Maven2', fileNamePatterns: ['pom.xml', '*.pom', '*.xml'] },
+    { id: 'PlistXML', fileNamePatterns: ['*.plist'] },
+    { id: 'RelaxNG', fileNamePatterns: ['*.rng'] },
+    { id: 'SVG', fileNamePatterns: ['*.svg'] },
+    { id: 'XRC', fileNamePatterns: ['*.xrc'] },
+    { id: 'XML', fileNamePatterns: ['*.xml'] },
+    { id: 'XSLT', fileNamePatterns: ['*.xsl', '*.xslt'] },
+    { id: 'Yaml', fileNamePatterns: ['*.yml', '*.yaml'] },
+    { id: 'OpenAPI', fileNamePatterns: ['openapi.yaml'] },
+    { id: 'Varlink', fileNamePatterns: ['*.varlink'] },
+    { id: 'Kotlin', fileNamePatterns: ['*.kt', '*.kts'] },
+    { id: 'Thrift', fileNamePatterns: ['*.thrift'] },
+    { id: 'Elm', fileNamePatterns: ['*.elm'] },
+    { id: 'TOML', fileNamePatterns: ['*.toml'] }
+];

package/dist/code-navigation/symbol-matcher.js

@@ -0,0 +1,48 @@
+import { symbolNavigationMaps } from './symbol-maps.js';
+let compiled;
+export function symbolNavigationLanguageForPath(path) {
+    const name = basename(path);
+    return compiledLanguages().find((entry) => entry.patterns.some((pattern) => pattern.test(name)))
+        ?.language;
+}
+export function supportsSymbolNavigationPath(path) {
+    const name = basename(path);
+    return compiledLanguages().some((entry) => entry.patterns.some((pattern) => pattern.test(name)));
+}
+export function symbolNavigationLanguages() {
+    return symbolNavigationMaps;
+}
+function compiledLanguages() {
+    return (compiled ??= symbolNavigationMaps.map((language) => ({
+        language,
+        patterns: language.fileNamePatterns.map((pattern) => globPattern(pattern))
+    })));
+}
+function globPattern(value) {
+    let expression = '';
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        if (character === '*') {
+            expression += '.*';
+            continue;
+        }
+        if (character === '?') {
+            expression += '.';
+            continue;
+        }
+        if (character === '[') {
+            const close = value.indexOf(']', index + 1);
+            if (close >= 0) {
+                expression += value.slice(index, close + 1);
+                index = close;
+                continue;
+            }
+        }
+        expression += character.replace(/[\\^$.*+?()[\]{}|]/gu, '\\$&');
+    }
+    return new RegExp(`^${expression}$`, 'iu');
+}
+function basename(path) {
+    const normalized = path.replaceAll('\\', '/');
+    return normalized.slice(normalized.lastIndexOf('/') + 1);
+}

package/dist/code-navigation/symbol-navigation.js

@@ -0,0 +1 @@
+export { supportsSymbolNavigationPath, symbolNavigationLanguageForPath, symbolNavigationLanguages } from './symbol-matcher.js';

package/dist/code-navigation/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ctags-binary.js

@@ -1,6 +1,6 @@
 import { chmod } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 export const BUNDLED_CTAGS_VERSION = '6.2.0-ab95af1';
 const TARGETS = {
     'linux-x64': ['linux-x64', 'ctags'],
@@ -11,8 +11,8 @@ const TARGETS = {
 };
 export function bundledCtagsDirectory(packageRoot) {
     return packageRoot === undefined
-        ? resolve(dirname(fileURLToPath(import.meta.url)), '..', 'vendor/ctags')
-        : resolve(packageRoot, 'mar-node/vendor/ctags');
+        ? resolve(dirname(createRequire(import.meta.url).resolve('@myagentroam/binaries/package.json')), 'vendor/ctags')
+        : resolve(packageRoot, 'packages/binaries/vendor/ctags');
 }
 export function bundledCtagsPath(platform = process.platform, architecture = process.arch, packageRoot) {
     const target = TARGETS[`${platform}-${architecture}`];

package/dist/marctl/bin/marctl.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { executableArgs, main } from '../src/cli.mjs';
+
+const exitCode = await main(executableArgs(process.argv[1], process.argv.slice(2)));
+if (exitCode !== 0) process.exitCode = exitCode;

package/dist/marctl/bin/marnodes.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { main } from '../src/cli.mjs';
+
+const exitCode = await main(['nodes', ...process.argv.slice(2)], { program: 'marnodes' });
+if (exitCode !== 0) process.exitCode = exitCode;

package/dist/marctl/bin/marscp.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { main } from '../src/cli.mjs';
+
+const exitCode = await main(['scp', ...process.argv.slice(2)], { program: 'marscp' });
+if (exitCode !== 0) process.exitCode = exitCode;

package/dist/marctl/bin/marssh.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { main } from '../src/cli.mjs';
+
+const exitCode = await main(['ssh', ...process.argv.slice(2)], { program: 'marssh' });
+if (exitCode !== 0) process.exitCode = exitCode;

package/dist/marctl/package.json

@@ -0,0 +1 @@
+{"type":"module","version":"0.12.1"}

package/dist/marctl/src/cli.mjs

@@ -0,0 +1,271 @@
+import { readFile } from 'node:fs/promises';
+import { MarctlClient } from './client.mjs';
+import { loadConfig } from './config.mjs';
+import { MarctlError } from './errors.mjs';
+import { createTranslator } from './i18n/index.mjs';
+import { runTerminalSession } from './terminal.mjs';
+import { runScp } from './scp.mjs';
+import { parseSessionArgs } from './session-args.mjs';
+import { runSessionCommand, sessionExitCode } from './sessions.mjs';
+
+async function withCommandSignals(run) {
+  const controller = new AbortController();
+  const onSigint = () => controller.abort('SIGINT');
+  const onSigterm = () => controller.abort('SIGTERM');
+  process.once('SIGINT', onSigint);
+  process.once('SIGTERM', onSigterm);
+  try {
+    return await run(controller.signal);
+  } finally {
+    process.off('SIGINT', onSigint);
+    process.off('SIGTERM', onSigterm);
+  }
+}
+
+export async function main(
+  argv = process.argv.slice(2),
+  {
+    env = process.env,
+    stdout = process.stdout,
+    stderr = process.stderr,
+    stdin = process.stdin,
+    program = 'marctl',
+    client,
+    WebSocketClass
+  } = {}
+) {
+  const translate = createTranslator(env);
+  let args;
+  try {
+    args = parseArgs(argv, translate);
+    if (args.help) {
+      writeLine(
+        stdout,
+        args.command === undefined
+          ? translate('help')
+          : translate(`commandHelp.${args.command}`, {
+              program: program === 'marctl' ? `marctl ${args.command}` : program
+            })
+      );
+      return 0;
+    }
+    if (args.version) {
+      const { version } = JSON.parse(
+        await readFile(new URL('../package.json', import.meta.url), 'utf8')
+      );
+      writeLine(stdout, `marctl ${version}`);
+      return 0;
+    }
+
+    const config = await loadConfig({ env, translate });
+    const marctlClient = client ?? new MarctlClient({ ...config, translate });
+    if (args.command === 'nodes') {
+      const nodes = await marctlClient.listNodes();
+      writeLine(stdout, translate('nodesHeader'));
+      for (const node of nodes) {
+        writeLine(
+          stdout,
+          [
+            node.id,
+            node.displayName ?? '',
+            node.connected ? translate('connected') : translate('disconnected'),
+            node.platform ?? ''
+          ].join('\t')
+        );
+      }
+      return 0;
+    }
+    if (args.command === 'agents') {
+      const execute = (signal) =>
+        runSessionCommand({
+          args,
+          client: marctlClient,
+          env,
+          stdin,
+          WebSocketClass,
+          translate,
+          signal
+        });
+      const result = args.action === 'wait' ? await withCommandSignals(execute) : await execute();
+      writeLine(stdout, JSON.stringify(result, null, args.json ? undefined : 2));
+      return 0;
+    }
+    if (args.command === 'scp') {
+      const socketClass = WebSocketClass ?? (await import('ws')).default;
+      return await withCommandSignals((signal) =>
+        runScp({
+          source: args.source,
+          destination: args.destination,
+          preserve: args.preserve,
+          client: marctlClient,
+          WebSocketClass: socketClass,
+          resolveNodeId: (reference) => resolveNodeId(marctlClient, reference, translate),
+          translate,
+          signal
+        })
+      );
+    }
+
+    const nodeId = await resolveNodeId(marctlClient, args.nodeId, translate);
+    const socketClass = WebSocketClass ?? (await import('ws')).default;
+    return await withCommandSignals((signal) =>
+      runTerminalSession({
+        client: marctlClient,
+        WebSocketClass: socketClass,
+        nodeId,
+        command: args.remoteCommand,
+        raceConnections: true,
+        stdout,
+        stderr,
+        translate,
+        signal
+      })
+    );
+  } catch (error) {
+    if (argv[0] === 'agents') {
+      const failure = {
+        code: error.code ?? 'MARCTL_COMMAND_FAILED',
+        message: error instanceof MarctlError ? error.message : translate('errors.commandFailed'),
+        ...(error.requestId === undefined ? {} : { requestId: error.requestId }),
+        ...(error.upstreamRequestId === undefined
+          ? {}
+          : { upstreamRequestId: error.upstreamRequestId }),
+        ...(error.details === undefined ? {} : { details: error.details }),
+        ...(error.sessionId === undefined ? {} : { sessionId: error.sessionId }),
+        ...(error.runId === undefined ? {} : { runId: error.runId }),
+        ...(error.stage === undefined ? {} : { stage: error.stage }),
+        ...(error.upstreamCode === undefined ? {} : { upstreamCode: error.upstreamCode }),
+        ...(error.progress === undefined ? {} : { progress: error.progress }),
+        ...(error.clientMessageId === undefined ? {} : { clientMessageId: error.clientMessageId })
+      };
+      if (args?.json === true || (args === undefined && argv.includes('--json')))
+        writeLine(stdout, JSON.stringify({ error: failure }));
+      else {
+        writeLine(stderr, program + ': ' + failure.message + ' [' + failure.code + ']');
+        if (failure.details !== undefined) writeLine(stderr, failure.details);
+        if (failure.progress !== undefined)
+          writeLine(stderr, JSON.stringify({ progress: failure.progress }, null, 2));
+      }
+      return sessionExitCode(error);
+    }
+    writeLine(
+      stderr,
+      `${program}: ${error instanceof MarctlError ? error.message : translate('errors.commandFailed')}`
+    );
+    return 1;
+  }
+}
+
+export async function resolveNodeId(client, reference, translate = createTranslator()) {
+  const nodes = await client.listNodes();
+  const byId = nodes.find((node) => node.id === reference);
+  if (byId) return byId.id;
+  const matches = nodes.filter((node) => node.displayName === reference);
+  if (matches.length > 1) throw new MarctlError(translate('errors.nodeNameAmbiguous'));
+  if (matches.length === 0) throw new MarctlError(translate('errors.nodeNotFound'));
+  return matches[0].id;
+}
+
+export function executableArgs(executable, args) {
+  const name = String(executable ?? '')
+    .split(/[\\/]/u)
+    .at(-1)
+    .replace(/\.(?:cmd|exe|ps1)$/iu, '');
+  const command = { marnodes: 'nodes', marssh: 'ssh', marscp: 'scp' }[name];
+  return command === undefined ? args : [command, ...args];
+}
+
+export function parseArgs(argv, translate = createTranslator()) {
+  if (argv[0] === 'agents') return parseSessionArgs(argv.slice(1), translate);
+  let command;
+  let nodeId;
+  const remoteArgs = [];
+  let separator = false;
+  let help = false;
+  let version = false;
+  let preserve = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (
+      !separator &&
+      nodeId === undefined &&
+      (argument === '--help' || argument === '-h' || (command === undefined && argument === 'help'))
+    ) {
+      help = true;
+      continue;
+    }
+    if (!separator && nodeId === undefined && (argument === '--version' || argument === '-V')) {
+      version = true;
+      continue;
+    }
+    if (!separator && argument === '--') {
+      separator = true;
+      continue;
+    }
+    if (command === undefined) {
+      if (
+        argument !== 'nodes' &&
+        argument !== 'ssh' &&
+        argument !== 'scp' &&
+        argument !== 'agents' &&
+        argument !== 'version'
+      )
+        throw unsupportedSshOption(argument, translate);
+      command = argument;
+      continue;
+    }
+    if (command === 'nodes' || command === 'version')
+      throw new MarctlError(translate('errors.invalidArguments'));
+    if (command === 'scp') {
+      if (!separator && argument.startsWith('-') && argument !== '-') {
+        if (!/^-[pq]+$/u.test(argument))
+          throw new MarctlError(translate('errors.scpOptionsUnsupported'));
+        if (argument.includes('p')) preserve = true;
+        continue;
+      }
+      if (nodeId === undefined) nodeId = argument;
+      else remoteArgs.push(argument);
+      continue;
+    }
+    if (nodeId === undefined) {
+      if (!separator && argument.startsWith('-'))
+        throw command === 'ssh'
+          ? unsupportedSshOption(argument, translate)
+          : new MarctlError(translate('errors.invalidArguments'));
+      nodeId = argument;
+      continue;
+    }
+    remoteArgs.push(argument);
+  }
+
+  if (help) return { help: true, ...(command === undefined ? {} : { command }) };
+  if (version || command === 'version') return { version: true };
+  if (command === 'nodes' && nodeId === undefined && remoteArgs.length === 0) return { command };
+  if (command === 'scp' && nodeId !== undefined && remoteArgs.length === 1)
+    return {
+      command,
+      source: nodeId,
+      destination: remoteArgs[0],
+      preserve
+    };
+  if (command === 'ssh' && nodeId !== undefined && nodeId !== '')
+    return {
+      command,
+      nodeId,
+      ...(remoteArgs.length === 0
+        ? {}
+        : { remoteCommand: remoteArgs.length === 1 ? remoteArgs[0] : remoteArgs.join(' ') })
+    };
+  throw new MarctlError(translate('errors.invalidArguments'));
+}
+
+function writeLine(stream, value) {
+  stream.write(`${value}\n`);
+}
+
+function unsupportedSshOption(argument, translate) {
+  if (typeof argument === 'string' && argument.startsWith('-'))
+    return new MarctlError(translate('errors.sshOptionsUnsupported'));
+  return new MarctlError(translate('errors.invalidArguments'));
+}