@myagentroam/marctl 0.9.120

package/src/i18n/en-US.mjs

@@ -0,0 +1,220 @@
+const configurationHelp = `Configuration:
+  MAR-launched terminals and Workspace Agent Runs use the current user's Node permissions;
+  scheduled runs use the task owner. No management key is needed in these contexts.
+  Outside MAR, use ~/.marctl/default.env (%HOME%\\.marctl\\default.env on Windows;
+  the system home directory is used when HOME is unset), or select a file with --env-file.
+  The file must contain MAR_CTL_SERVER_URL and MAR_CTL_KEY. Never pass a key as an argument.`;
+
+export default Object.freeze({
+  help: `marctl — MyAgentRoam command-line interface
+
+Usage:
+  marctl [options] <command> [arguments]
+  marctl help [command]
+
+Commands:
+  nodes    List accessible Nodes and their connection status.
+  ssh      Open a Node terminal or execute a remote command.
+  scp      Copy a regular file between this machine and Nodes, or between Nodes.
+  version  Print the installed CLI package version.
+  help     Show help for the CLI or a command.
+
+Options:
+  --env-file PATH  Use the specified management configuration file.
+  -h, --help       Show help and exit.
+  -V, --version    Print the CLI package version and exit.
+
+Examples:
+  marctl nodes
+  marctl ssh <node> uname -a
+  marctl scp ./artifact.bin <node>:///tmp/artifact.bin
+  marctl --version
+  marctl help ssh
+
+Aliases:
+  marnodes  Equivalent to the nodes command.
+  marssh    Equivalent to the ssh command.
+  marscp    Equivalent to the scp command.
+
+${configurationHelp}
+
+Notes:
+  Help and version work offline without configuration or authorization.
+  Put local help/version options before a Node or file endpoint; --env-file may also follow a command.
+  Each alias shows only its own command help. Use marctl help <command> for details.
+  Remote access uses authorized Node Terminal transport, not system SSH or SCP.`,
+  commandHelp: Object.freeze({
+    nodes: `{program} — List accessible Nodes
+
+Usage:
+  {program} [--env-file PATH] [options]
+
+Options:
+  --env-file PATH  Use the specified management configuration file.
+  -h, --help       Show help and exit.
+  -V, --version    Print the CLI package version and exit.
+
+Examples:
+  {program}
+  {program} --env-file ~/.marctl/production.env
+
+Output:
+  Tab-separated columns: ID, NAME, STATUS, PLATFORM.
+  Includes offline Nodes for which the current user has terminal permission.
+
+${configurationHelp}`,
+    ssh: `{program} — Open a terminal or execute a remote command
+
+Usage:
+  {program} [--env-file PATH] [options] <node> [command [arg...]]
+
+Arguments:
+  <node>          An authorized Node ID or an exact, unique Node name.
+  [command ...]   A command for the remote shell; omit it for an interactive shell.
+
+Options (before <node>):
+  --env-file PATH  Use the specified management configuration file.
+  -h, --help       Show help and exit.
+  -V, --version    Print the CLI package version and exit.
+
+Examples:
+  {program} ubuntu-develop
+  {program} ubuntu-develop uname -a
+  {program} ubuntu-develop "echo hello && whoami"
+
+Notes:
+  Names must be unique across accessible Nodes, including offline Nodes; use an ID on conflict.
+  Remote arguments are joined with spaces. Quote shell expressions for your local shell.
+  Remote --help, -h, and --version are not local options. The remote exit code is preserved.
+  Commands run as the Node service account; login accounts, privilege escalation, and SSH
+  connection options such as -t, -p, and -i are unsupported. No SSH port is required.
+  Connection setup has a timeout, but attached commands have no runtime or output-idle timeout.
+  Commands are not retried. Exit or unrecoverable disconnection closes the terminal;
+  this is not a background-job service.
+
+${configurationHelp}`,
+    scp: `{program} — Copy a regular file
+
+Usage:
+  {program} [--env-file PATH] [options] <source> <destination>
+
+Arguments:
+  <source>        A local file or an authorized Node file endpoint.
+  <destination>   A local file/directory or an authorized Node endpoint.
+  Node endpoints: <node>://<absolute-path> or <node>:<absolute-path>.
+  <node> is an ID or an exact, unique name, including offline Nodes.
+  At least one endpoint must be a Node. Linux and Windows paths are supported.
+
+Options:
+  -p              Preserve source permissions and access/modification times.
+  -q              Suppress progress output (already the default).
+  --env-file PATH  Use the specified management configuration file.
+  -h, --help       Show help and exit; place before the first endpoint.
+  -V, --version    Print the CLI package version and exit; place before the first endpoint.
+  --              Treat remaining arguments as literal paths.
+
+Examples:
+  {program} ./artifact.bin ubuntu-develop:///tmp/artifact.bin
+  {program} ubuntu-develop:///tmp/artifact.bin ./
+  {program} -p linux:///tmp/artifact.bin "windows://C:/Artifacts/"
+
+Notes:
+  Existing directories receive the source filename; directory paths must already exist.
+  Existing regular files are overwritten, retaining their permissions unless -p is used.
+  Directory sources, symlinks, invalid destination filenames, and directory final targets
+  are rejected. Recursive -r, multiple sources, and SSH connection options are unsupported.
+  Both Server and Node must support binary Terminal pipes; this is not system SCP.
+  File access uses the Node service account's permissions. Checksums are verified before
+  atomic publication; failed transfers leave the original unchanged. Forced termination
+  may leave a temporary file. Transfers are not retried.
+
+${configurationHelp}`,
+    version: `marctl — MyAgentRoam CLI version
+
+Usage:
+  {program} [options]
+  marctl --version
+  marctl -V
+
+Options:
+  -h, --help       Show help and exit.
+  -V, --version    Print the CLI package version and exit.
+
+Examples:
+  {program}
+  marctl --version
+
+Output:
+  marctl <version>
+
+Prints one line from the installed @myagentroam/marctl package, followed by a newline.
+The version is independent of Node and Server. No configuration, authorization,
+or Server connection is required.`
+  }),
+  nodesHeader: 'ID\tNAME\tSTATUS\tPLATFORM',
+  connected: 'connected',
+  disconnected: 'disconnected',
+  errors: Object.freeze({
+    userContextUnavailable: 'This Node session has no valid marctl user authorization.',
+    configServerUrlMissing: 'MAR_CTL_SERVER_URL is not configured.',
+    configKeyMissing: 'MAR_CTL_KEY is not configured.',
+    configKeyInvalid: 'MAR_CTL_KEY contains invalid characters.',
+    serverUrlInvalid: 'MAR_CTL_SERVER_URL is invalid.',
+    serverUrlTransport: 'MAR_CTL_SERVER_URL must use HTTPS or loopback HTTP.',
+    serverUrlOrigin: 'MAR_CTL_SERVER_URL must be an origin without credentials or query data.',
+    envFileMissing: 'The requested environment file was not found.',
+    envFileRead: 'The environment file could not be read.',
+    envFileSymlink: 'The environment file must not be a symbolic link. Use chmod 600.',
+    envFileType: 'The environment file must be a regular file. Use chmod 600.',
+    envFilePermissions:
+      'The environment file must be owned by the current user and have mode 0600 or 0400. Use chmod 600.',
+    envFileEntry: 'Invalid environment entry.',
+    envFileUnsupported: 'Unsupported environment variable.',
+    envFileQuoted: 'Invalid quoted environment value.',
+    fetchUnavailable: 'Fetch is unavailable in this Node.js runtime.',
+    serverInvalidNodes: 'The server returned an invalid node list.',
+    serverInvalidManifest: 'The server returned an invalid node manifest.',
+    terminalCommandInvalid: 'The terminal command is invalid.',
+    terminalSequenceInvalid: 'The terminal sequence is invalid.',
+    terminalTicketInvalid: 'The terminal ticket is invalid.',
+    terminalIdInvalid: 'The terminal identifier is invalid.',
+    nodeIdInvalid: 'The node identifier is invalid.',
+    nodeNameAmbiguous: 'Multiple accessible nodes share that name; use a node ID.',
+    nodeNotFound: 'No accessible node matches this ID or name.',
+    terminalSizeInvalid: 'The terminal size is invalid.',
+    serverInvalidTerminalId: 'The server returned an invalid terminal identifier.',
+    serverInvalidTicket: 'The server returned an invalid terminal ticket.',
+    serverInvalidJson: 'The server returned invalid JSON.',
+    serverTimeout: 'The marctl server did not respond before the control request timeout.',
+    serverUnreachable: 'The marctl server could not be reached.',
+    serverRejected: 'The marctl server rejected the request.',
+    terminalConnectionStart: 'The terminal connection could not be started.',
+    terminalConnectionOpen: 'The terminal connection could not be opened.',
+    terminalAttachTimeout: 'The terminal did not attach before the connection setup timeout.',
+    terminalAttachConnection: 'The terminal connection failed during attachment.',
+    terminalAttachLost: 'The terminal connection was lost during attachment.',
+    terminalRemoteError: 'The remote terminal reported an error.',
+    terminalClosedBeforeAttach: 'The remote terminal closed before attachment.',
+    terminalFrameInvalid: 'The terminal frame was invalid.',
+    terminalInvalidJson: 'The terminal sent invalid JSON.',
+    terminalBinaryFrame: 'The terminal sent an invalid binary frame.',
+    terminalBinaryUnavailable:
+      'Binary copy requires a Server and Node that support pipe terminals.',
+    terminalConnectionFailed: 'The terminal connection failed.',
+    terminalConnectionLost: 'The terminal connection was lost.',
+    terminalUnexpectedFrame: 'The remote terminal sent an unexpected frame.',
+    terminalInputFailed: 'The terminal input could not be sent.',
+    terminalResizeFailed: 'The terminal resize could not be sent.',
+    terminalInteractiveRequired: 'An interactive terminal is required.',
+    terminalInteractiveInit: 'The interactive terminal could not be initialized.',
+    terminalCloseFailed: 'The remote terminal could not be closed.',
+    terminalSessionFailed: 'The terminal session failed.',
+    terminalDirectUnsafeFallback:
+      'Direct terminal setup could not be safely canceled after OPEN; relay fallback was skipped.',
+    invalidArguments: 'Invalid command arguments.',
+    envFileValueRequired: 'A value is required for --env-file.',
+    sshOptionsUnsupported: 'SSH options are not supported; use marssh <host>.',
+    scpOptionsUnsupported: 'This SCP option is not supported by the Node Terminal transport.',
+    commandFailed: 'The command failed.'
+  })
+});

package/src/i18n/index.mjs

@@ -0,0 +1,20 @@
+import enUS from './en-US.mjs';
+import zhCN from './zh-CN.mjs';
+
+export function localeFromEnv(env = process.env) {
+  const value = String(env.LC_ALL || env.LANG || '').toLowerCase();
+  return value.startsWith('zh_') || value.startsWith('zh-') || value === 'zh' ? 'zh-CN' : 'en-US';
+}
+
+export function createTranslator(env = process.env) {
+  const locale = localeFromEnv(env);
+  const resource = locale === 'zh-CN' ? zhCN : enUS;
+  const translate = (key, params = {}) => {
+    const value = key.split('.').reduce((current, part) => current?.[part], resource);
+    if (typeof value === 'function') return value(params);
+    if (typeof value !== 'string') return key;
+    return value.replace(/\{(\w+)\}/gu, (_match, name) => String(params[name] ?? ''));
+  };
+  translate.locale = locale;
+  return translate;
+}

package/src/i18n/zh-CN.mjs

@@ -0,0 +1,212 @@
+const configurationHelp = `配置：
+  MAR 打开的终端和普通 Workspace Agent Run 使用当前用户的节点权限，定时任务使用任务 owner 的权限；
+  这些上下文无需管理密钥。
+  独立使用时读取 ~/.marctl/default.env（Windows 为 %HOME%\\.marctl\\default.env，
+  HOME 未设置时使用系统主目录），也可用 --env-file 指定文件。
+  文件须包含 MAR_CTL_SERVER_URL 和 MAR_CTL_KEY。不要通过命令参数传递密钥。`;
+
+export default Object.freeze({
+  help: `marctl — MyAgentRoam 命令行工具
+
+用法：
+  marctl [选项] <子命令> [参数]
+  marctl help [子命令]
+
+子命令：
+  nodes    列出有权限的节点及连接状态。
+  ssh      打开节点终端或执行远程命令。
+  scp      在当前机器与节点之间、节点之间复制普通文件。
+  version  显示已安装的 CLI 包版本。
+  help     显示工具或指定子命令的帮助。
+
+选项：
+  --env-file PATH  使用指定的管理配置文件。
+  -h, --help       显示帮助后退出。
+  -V, --version    显示 CLI 包版本后退出。
+
+示例：
+  marctl nodes
+  marctl ssh <节点> uname -a
+  marctl scp ./artifact.bin <节点>:///tmp/artifact.bin
+  marctl --version
+  marctl help ssh
+
+快捷命令：
+  marnodes  等价于 nodes 子命令。
+  marssh    等价于 ssh 子命令。
+  marscp    等价于 scp 子命令。
+
+${configurationHelp}
+
+说明：
+  帮助和版本查询离线可用，无需配置或授权。
+  本机帮助、版本选项须放在节点或文件端点前；--env-file 也可放在子命令后。
+  快捷命令仅显示对应操作的帮助。用 marctl help <子命令> 查看详细说明。
+  远程访问使用授权的 Node Terminal 传输，不是系统 SSH 或 SCP 协议。`,
+  commandHelp: Object.freeze({
+    nodes: `{program} — 列出有权限的节点
+
+用法：
+  {program} [--env-file PATH] [选项]
+
+选项：
+  --env-file PATH  使用指定的管理配置文件。
+  -h, --help       显示帮助后退出。
+  -V, --version    显示 CLI 包版本后退出。
+
+示例：
+  {program}
+  {program} --env-file ~/.marctl/production.env
+
+输出：
+  以制表符分隔的节点 ID、名称、状态、平台列。
+  包含当前用户有终端使用权的离线节点。
+
+${configurationHelp}`,
+    ssh: `{program} — 打开终端或执行远程命令
+
+用法：
+  {program} [--env-file PATH] [选项] <节点> [command [arg...]]
+
+参数：
+  <节点>          有权限的节点 ID，或精确、唯一的节点名称。
+  [command ...]   交给远端 Shell 的命令；省略时打开交互 Shell。
+
+选项（放在节点前）：
+  --env-file PATH  使用指定的管理配置文件。
+  -h, --help       显示帮助后退出。
+  -V, --version    显示 CLI 包版本后退出。
+
+示例：
+  {program} ubuntu-develop
+  {program} ubuntu-develop uname -a
+  {program} ubuntu-develop "echo hello && whoami"
+
+说明：
+  名称须在可访问节点中唯一（包括离线节点），重名时使用 ID。
+  远程参数以空格拼接；Shell 表达式须按本机 Shell 语法引用。
+  远端 --help、-h、--version 不作为本机选项处理；保留远程命令的真实退出码。
+  命令以 Node 服务账号运行，不支持登录账号、提权及 -t、-p、-i 等 SSH 连接选项；无需 SSH 端口。
+  建连有超时，附着后的命令没有运行时长或输出空闲超时。命令不自动重试。
+  退出或连接无法恢复时关闭终端，不提供后台任务托管。
+
+${configurationHelp}`,
+    scp: `{program} — 复制普通文件
+
+用法：
+  {program} [--env-file PATH] [选项] <源> <目标>
+
+参数：
+  <源>            本机文件或有权限的节点文件端点。
+  <目标>          本机文件、目录或有权限的节点端点。
+  节点端点：<节点>://<绝对路径> 或 <节点>:<绝对路径>。
+  节点须使用 ID 或精确、唯一的名称（包括离线节点）。
+  至少一端必须为节点，支持 Linux 和 Windows 路径。
+
+选项：
+  -p              保留源文件权限及访问、修改时间。
+  -q              不显示进度（默认已不显示）。
+  --env-file PATH  使用指定的管理配置文件。
+  -h, --help       显示帮助后退出，须放在第一个文件端点前。
+  -V, --version    显示 CLI 包版本后退出，须放在第一个文件端点前。
+  --              后续参数按字面路径处理。
+
+示例：
+  {program} ./artifact.bin ubuntu-develop:///tmp/artifact.bin
+  {program} ubuntu-develop:///tmp/artifact.bin ./
+  {program} -p linux:///tmp/artifact.bin "windows://C:/Artifacts/"
+
+说明：
+  已有目标目录自动追加源文件名；目录路径必须已存在。
+  已有普通文件默认覆盖，未使用 -p 时保留其权限。
+  拒绝源目录、符号链接、接收平台不合法的文件名及最终目标目录；不支持递归 -r、多源及 SSH 连接选项。
+  Server 和 Node 均须支持二进制 Terminal pipe；这不是系统 SCP。
+  文件访问遵循 Node 服务账号权限。完整校验后原子发布，失败不替换原文件；
+  强制终止可能留下临时文件，传输不自动重试。
+
+${configurationHelp}`,
+    version: `marctl — MyAgentRoam CLI 版本
+
+用法：
+  {program} [选项]
+  marctl --version
+  marctl -V
+
+选项：
+  -h, --help       显示帮助后退出。
+  -V, --version    显示 CLI 包版本后退出。
+
+示例：
+  {program}
+  marctl --version
+
+输出：
+  marctl <version>
+
+读取已安装的 @myagentroam/marctl 包版本，输出单行并以换行符结尾。
+该版本独立于 Node 和 Server；无需配置、授权或连接 Server。`
+  }),
+  nodesHeader: '节点 ID\t名称\t状态\t平台',
+  connected: '在线',
+  disconnected: '离线',
+  errors: Object.freeze({
+    userContextUnavailable: '此 Node 会话没有有效的 marctl 用户授权。',
+    configServerUrlMissing: '未配置 MAR_CTL_SERVER_URL。',
+    configKeyMissing: '未配置 MAR_CTL_KEY。',
+    configKeyInvalid: 'MAR_CTL_KEY 包含无效字符。',
+    serverUrlInvalid: 'MAR_CTL_SERVER_URL 无效。',
+    serverUrlTransport: 'MAR_CTL_SERVER_URL 必须使用 HTTPS 或回环 HTTP。',
+    serverUrlOrigin: 'MAR_CTL_SERVER_URL 必须是不含凭据或查询参数的 Origin。',
+    envFileMissing: '指定的环境文件不存在。',
+    envFileRead: '无法读取环境文件。',
+    envFileSymlink: '环境文件不能是符号链接。请使用 chmod 600。',
+    envFileType: '环境文件必须是普通文件。请使用 chmod 600。',
+    envFilePermissions: '环境文件必须归当前用户所有，权限必须为 0600 或 0400。请使用 chmod 600。',
+    envFileEntry: '环境文件条目无效。',
+    envFileUnsupported: '环境变量不受支持。',
+    envFileQuoted: '带引号的环境变量值无效。',
+    fetchUnavailable: '当前 Node.js 运行时没有 Fetch。',
+    serverInvalidNodes: 'Server 返回的节点列表无效。',
+    serverInvalidManifest: 'Server 返回的节点清单无效。',
+    terminalCommandInvalid: '终端命令无效。',
+    terminalSequenceInvalid: '终端序列无效。',
+    terminalTicketInvalid: '终端票据无效。',
+    terminalIdInvalid: '终端标识无效。',
+    nodeIdInvalid: '节点标识无效。',
+    nodeNameAmbiguous: '多个可访问节点同名，请使用节点 ID。',
+    nodeNotFound: '没有与该 ID 或名称匹配的可访问节点。',
+    terminalSizeInvalid: '终端尺寸无效。',
+    serverInvalidTerminalId: 'Server 返回的终端标识无效。',
+    serverInvalidTicket: 'Server 返回的终端票据无效。',
+    serverInvalidJson: 'Server 返回的 JSON 无效。',
+    serverTimeout: 'marctl Server 未能在控制面请求超时前响应。',
+    serverUnreachable: '无法连接 marctl Server。',
+    serverRejected: 'marctl Server 拒绝了请求。',
+    terminalConnectionStart: '无法启动终端连接。',
+    terminalConnectionOpen: '无法打开终端连接。',
+    terminalAttachTimeout: '终端未能在连接建立超时前完成附着。',
+    terminalAttachConnection: '终端附着期间连接失败。',
+    terminalAttachLost: '终端附着期间连接断开。',
+    terminalRemoteError: '远程终端返回错误。',
+    terminalClosedBeforeAttach: '远程终端在附着前关闭。',
+    terminalFrameInvalid: '终端帧无效。',
+    terminalInvalidJson: '终端返回了无效 JSON。',
+    terminalBinaryFrame: '终端返回了无效二进制帧。',
+    terminalConnectionFailed: '终端连接失败。',
+    terminalConnectionLost: '终端连接断开。',
+    terminalUnexpectedFrame: '远程终端返回了意外帧。',
+    terminalInputFailed: '无法发送终端输入。',
+    terminalResizeFailed: '无法发送终端尺寸。',
+    terminalInteractiveRequired: '需要交互式终端。',
+    terminalInteractiveInit: '无法初始化交互式终端。',
+    terminalCloseFailed: '无法关闭远程终端。',
+    terminalSessionFailed: '终端会话失败。',
+    terminalDirectUnsafeFallback: 'OPEN 后无法安全取消直连终端，已跳过 relay 回退。',
+    invalidArguments: '命令参数无效。',
+    envFileValueRequired: '--env-file 必须提供值。',
+    sshOptionsUnsupported: '不支持 SSH 选项，请使用 marssh <节点>。',
+    scpOptionsUnsupported: 'Node Terminal 传输不支持此 SCP 选项。',
+    terminalBinaryUnavailable: '二进制复制需要支持 pipe 终端的 Server 与 Node。',
+    commandFailed: '命令执行失败。'
+  })
+});