@rome-os/node 0.1.2 → 0.1.4

package/README.md

@@ -60,6 +60,29 @@ rome-node device describe <device-id>
 rome-node device run <device-id> exec --args '{"command":"git","args":["status"],"cwd":"/workspace"}'
 ```
 
+Copy a file to or from a device:
+
+```sh
+rome-node cp ./video.mp4 <device-id>:/tmp/video.mp4
+rome-node cp <device-id>:/tmp/video.mp4 ./video.mp4
+```
+
+The caller daemon and `rome-node connect` read and write the files with Node
+streams. Each copy writes its own hidden part file next to the destination.
+The destination changes only after its size and SHA-256 checksum match and the
+data is flushed to disk. A replaced file keeps its permission bits.
+A failed copy leaves it unchanged and is safe to run again. To copy between two
+devices, copy to this computer first and then to the second device. Progress
+goes to stderr, and `{"bytes":...,"ms":...,"sha256":"..."}` goes to stdout. The
+device needs a rome-node version with file transfer support.
+
+To pass raw bytes to a program and read its raw stdout, add `--input` or `--output`
+to `device run`:
+
+```sh
+rome-node device run <device-id> exec --args '{"command":"gzip","args":["-c"]}' --input data.bin --output data.bin.gz
+```
+
 Use `rome-node <command> --help` or `-h` for command-specific help.
 Help includes action arguments, examples, output fields, and failure handling.
 It works offline without credentials and does not start the daemon.
@@ -76,10 +99,12 @@ After a connection loss it waits for the daemon and subscribes again; it does
 not restart a stopped daemon. Ctrl+C closes only the watcher. These events
 report the caller's Gateway connection, not remote device presence.
 
-Commands print JSON to stdout and diagnostics to stderr. Errors and nonzero
+Commands print JSON to stdout and diagnostics to stderr. With `--input` and no
+`--output <file>`, `device run` prints the program's raw stdout and moves the JSON
+response to stderr. Errors and nonzero
 remote exit codes produce a nonzero local exit status. Output is collected in memory
 and returned in full after program exit. Action message limits follow the WebSocket library and infrastructure.
-The local daemon disconnects event observers that exceed its send-buffer limit. A lost response reports
+The local daemon disconnects event observers that exceed its unsent event limit. A lost response reports
 `unknown_outcome`. Never automatically retry an unknown outcome.
 An authorized device is
 not necessarily online. Use `describe` to query its current platform and actions.
@@ -87,4 +112,4 @@ not necessarily online. Use `describe` to query its current platform and actions
 The CLI uses [`@rome-os/node-core`](../rome-node-core/README.md) for authorization,
 its shared caller daemon, and the computer host. The package also re-exports
 the Gateway client, socket adapter, and action response contract for compatibility. See [the device architecture and operating guide](../../docs/rome-node.md)
-for credential boundaries, file operations, output limits, and disconnection behavior.
+for credential boundaries, binary frames, file copies, output limits, and disconnection behavior.

package/dist/copy.d.ts

@@ -0,0 +1,7 @@
+import type { CopyRequest } from "@rome-os/node-core/client";
+export interface CopyLocation {
+    deviceId?: string;
+    path: string;
+}
+export declare function parseLocation(value: string): CopyLocation;
+export declare function copyRequest(source: string, destination: string, cwd: string): CopyRequest;

package/dist/copy.js

@@ -0,0 +1,43 @@
+import { resolve } from "node:path";
+import { isUuid } from "@rome-os/node-core";
+export function parseLocation(value) {
+    const separator = value.indexOf(":");
+    const prefix = value.slice(0, separator);
+    if (separator === 36 && isUuid(prefix)) {
+        if (separator === value.length - 1)
+            throw new Error("A path is required after <device-id>:.");
+        return { deviceId: prefix.toLowerCase(), path: value.slice(separator + 1) };
+    }
+    if (!value)
+        throw new Error("A path is required.");
+    return { path: value };
+}
+export function copyRequest(source, destination, cwd) {
+    const from = parseLocation(source);
+    const to = parseLocation(destination);
+    if (from.deviceId && to.deviceId)
+        throw new Error("Copy between two devices in two steps through this computer: " +
+            "rome-node cp <device-a>:<path> <local-file>, then rome-node cp <local-file> <device-b>:<path>.");
+    if (!from.deviceId && !to.deviceId)
+        throw new Error("One side must be a device path: <device-id>:<path>.");
+    let target = to.path;
+    if (/[\\/]$/.test(target)) {
+        const name = from.path.split(/[\\/]/).filter(Boolean).pop();
+        if (!name)
+            throw new Error("The source path has no file name.");
+        target += name;
+    }
+    return from.deviceId
+        ? {
+            direction: "pull",
+            deviceId: from.deviceId,
+            remotePath: from.path,
+            localPath: resolve(cwd, target),
+        }
+        : {
+            direction: "push",
+            deviceId: to.deviceId,
+            remotePath: target,
+            localPath: resolve(cwd, from.path),
+        };
+}

package/dist/entry.js

@@ -1,9 +1,42 @@
 import { parseArgs } from "node:util";
 import { join } from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
 import { isRecord, cloudOrigin, validId } from "@rome-os/node-core";
 import { authorizeServer, configureCaller } from "@rome-os/node-core/auth";
 import { createNodeClient, CallerConfigurationError, DeviceActionError, nodeConfigFromEnvironment, readOptionalCallerCredential, daemonStatus, startDaemon, stopDaemon, } from "@rome-os/node-core/client";
 import { commandHelp } from "./help.js";
+import { copyRequest } from "./copy.js";
+const failed = (response) => !response.ok ||
+    (isRecord(response.result) &&
+        Object.hasOwn(response.result, "exitCode") &&
+        response.result.exitCode !== 0);
+async function readInput(path) {
+    if (path !== "-")
+        return readFile(path);
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks);
+}
+function write(stream, data) {
+    return new Promise((resolve, reject) => stream.write(data, (error) => (error ? reject(error) : resolve())));
+}
+function progressPrinter() {
+    const started = Date.now();
+    let last = 0;
+    const mib = (bytes) => (bytes / 1024 / 1024).toFixed(1);
+    return (progress, final = false) => {
+        const now = Date.now();
+        if (!final && now - last < 1000 && progress.bytes !== progress.total)
+            return;
+        last = now;
+        const percent = progress.total ? Math.floor((progress.bytes / progress.total) * 100) : 100;
+        const ms = now - started;
+        const rate = ms ? mib((progress.bytes / ms) * 1000) : "0.0";
+        const line = `${mib(progress.bytes)} / ${mib(progress.total)} MiB (${percent}%) ${rate} MiB/s`;
+        process.stderr.write(process.stderr.isTTY ? `\r${line}\x1b[K${final ? "\n" : ""}` : `${line}\n`);
+    };
+}
 async function withShutdown(run) {
     const controller = new AbortController();
     const stop = () => controller.abort();
@@ -30,6 +63,8 @@ async function main() {
             cloud: { type: "string" },
             name: { type: "string" },
             args: { type: "string" },
+            input: { type: "string" },
+            output: { type: "string" },
             server: { type: "boolean" },
             "device-code": { type: "boolean" },
         },
@@ -44,6 +79,25 @@ async function main() {
         throw new Error("--server is only supported by rome-node auth.");
     if (values["device-code"] && !(positionals[0] === "connect" && positionals.length === 1))
         throw new Error("--device-code is only supported by rome-node connect.");
+    if ((values.input !== undefined || values.output !== undefined) &&
+        !(positionals[0] === "device" && positionals[1] === "run"))
+        throw new Error("--input and --output are only supported by rome-node device run.");
+    if (positionals[0] === "cp") {
+        if (positionals.length !== 3)
+            throw new Error("Usage: rome-node cp <src> <dst>");
+        const request = copyRequest(positionals[1], positionals[2], process.cwd());
+        const client = createNodeClient(config);
+        const print = progressPrinter();
+        try {
+            const summary = await client.copy(request, { onProgress: (progress) => print(progress) });
+            print({ bytes: summary.bytes, total: summary.bytes }, true);
+            process.stdout.write(`${JSON.stringify(summary)}\n`);
+        }
+        finally {
+            client.disconnect();
+        }
+        return;
+    }
     if (positionals[0] === "auth" && positionals[1] === "status" && positionals.length === 2) {
         const credential = await readOptionalCallerCredential(config);
         process.stdout.write(`${JSON.stringify(credential ? { configured: true, cloudUrl: credential.cloudUrl } : { configured: false })}\n`);
@@ -177,14 +231,24 @@ async function main() {
             process.stdout.write(`${JSON.stringify(await client.listDevices())}\n`);
             return;
         }
+        if (values.input !== undefined || values.output !== undefined) {
+            const output = values.output ?? "-";
+            const input = values.input === undefined ? undefined : await readInput(values.input);
+            const { response, body } = await client.runBinary(deviceId, action, args, input);
+            if (output === "-")
+                await write(process.stdout, body);
+            else if (response.ok)
+                await writeFile(output, body);
+            await write(output === "-" ? process.stderr : process.stdout, `${JSON.stringify(response)}\n`);
+            if (failed(response))
+                process.exitCode = 1;
+            return;
+        }
         const result = command === "describe"
             ? await client.describe(deviceId)
             : await client.run(deviceId, action, args);
         process.stdout.write(`${JSON.stringify(result)}\n`);
-        if (!result.ok ||
-            (isRecord(result.result) &&
-                Object.hasOwn(result.result, "exitCode") &&
-                result.result.exitCode !== 0))
+        if (failed(result))
             process.exitCode = 1;
     }
     finally {

package/dist/help.js

@@ -11,6 +11,7 @@ Commands:
   device           List authorized devices (they may be offline).
   device describe  Query a device's platform and supported actions.
   device run       Execute an action on a device.
+  cp               Copy a file to or from a device.
   watch            Stream caller connection snapshots and changes as JSON lines.
   daemon           Manage the caller's background connection.
 
@@ -95,7 +96,7 @@ The token is never printed.
     device: `Usage:
   rome-node device
   rome-node device describe <device-id>
-  rome-node device run <device-id> <action> [--args <json>]
+  rome-node device run <device-id> <action> [--args <json>] [--input <file|->] [--output <file|->]
 
 With no subcommand, list authorized devices as {"items":[...]}.
 Use an item's id for subsequent commands. Listed devices may be offline.
@@ -119,7 +120,9 @@ Example result:
 Failures return {"type":"response","ok":false,"error":{"code":"...","message":"..."}}.
 The local exit status is 0 on success or 1 on failure.
 `,
-    "device run": `Usage: rome-node device run <device-id> <action> [--args <json>]
+    "device run": `Usage:
+  rome-node device run <device-id> <action> [--args <json>]
+  rome-node device run <device-id> <action> [--args <json>] [--input <file|->] [--output <file|->]
 
 Use an ID from rome-node device. Run device describe first to discover actions.
 --args is a JSON object for the action (default: {}).
@@ -133,7 +136,7 @@ exec arguments:
   args         Optional array of string arguments (default: []).
   cwd          Optional working directory on the target (default: executor cwd).
 
-Programs receive no interactive stdin. No shell is added automatically.
+Programs receive no stdin unless --input is given. No shell is added automatically.
 Invoke a shell explicitly for pipelines, redirection, or shell builtins.
 Examples below use POSIX caller-shell quoting:
   rome-node device run <device-id> system.info
@@ -151,12 +154,66 @@ Check exec's exitCode even when ok is true. The local exit status is 1 for
 action failures, nonzero remote exit codes, or signal termination, otherwise 0.
 Local setup and argument errors print diagnostics to stderr and exit 1.
 Output is collected in memory and returned in full after program exit.
-The CLI does not truncate output or impose message or send-buffer size limits.
-Transport limits still apply. Connection loss returns unknown_outcome.
+In text mode, the CLI does not truncate output or impose message or send-buffer
+size limits. Transport limits still apply. Connection loss returns unknown_outcome.
+
+Raw bytes (--input or --output):
+  The request travels as a binary frame. Bytes are never JSON or base64 encoded.
+  --input <file|->   Send the file, or this command's stdin, as the program's stdin.
+                     The program then reads end of file. Without --input, stdin is empty.
+  --output <file|->  Write the program's stdout bytes to the file, or to stdout (default: -).
+                     The file is written only when ok is true.
+  The JSON response goes to stdout, or to stderr when the output is -.
+  exec result: {exitCode, signal, stderr, truncated}. stdout is the raw output.
+  Secrets in stdout are replaced by the same number of * bytes.
+  Each request and each response is one frame of at most 32 MiB. Larger input
+  fails with message_too_large before anything is sent. Larger output fails with
+  output_too_large after the program ran. Use rome-node cp for large files.
+  A target without binary frame support (no frameVersion in system.info) drops
+  the request, and the caller reports unknown_outcome after 60 seconds.
+  device run does not check frameVersion. rome-node cp checks transferVersion
+  first and fails at once with unsupported_device.
+  Example:
+    rome-node device run <device-id> exec --args '{"command":"gzip","args":["-c"]}' --input data.bin --output data.bin.gz
 
 The caller waits up to 60 seconds for a response. unknown_outcome means execution
 may have started or completed. A local timeout does not cancel the remote program.
 Never automatically retry an unknown outcome. Requests are never replayed.
+`,
+    cp: `Usage: rome-node cp <src> <dst>
+
+Copy one regular file between this computer and a device. Exactly one side is
+<device-id>:<path>, and the other is a local path. A device path that is not
+absolute starts from the working directory of rome-node connect on that device.
+A destination ending in / or \\ receives the source file name.
+
+  rome-node cp ./video.mp4 <device-id>:/tmp/video.mp4
+  rome-node cp <device-id>:/tmp/video.mp4 ./video.mp4
+  rome-node cp ./video.mp4 '<device-id>:C:/Users/me/'
+
+To copy between two devices, copy in two steps through this computer:
+  rome-node cp <device-a>:/data/video.mp4 ./video.mp4
+  rome-node cp ./video.mp4 <device-b>:/data/video.mp4
+
+The caller daemon reads or writes the local file, and rome-node connect reads
+or writes the device file. Programs and shells are not involved. The source
+must be a regular file. FIFOs, devices, and directories fail with not_a_file.
+
+Each copy writes its own .<name>.<uuid>.rome-part next to <dst>, created with
+mode 0600. It replaces <dst> only after the size and SHA-256 checksum match the
+source and the data is flushed to disk. A replaced file keeps its permission
+bits, and a new file gets the directory's default mode.
+
+A failed or interrupted copy (including Ctrl+C) leaves <dst> unchanged and
+deletes its part file. There is no resume or automatic retry. Run the copy
+again. A copy aborts after 60 seconds without progress. The device must run a
+rome-node version that reports transferVersion in system.info.
+
+Output:
+  Progress (bytes, percent, throughput) goes to stderr.
+  Success prints {"bytes":...,"ms":...,"sha256":"..."} to stdout and exits 0.
+  A copy failure prints {"type":"response","ok":false,"error":{...}} to stdout
+  and exits 1. Argument errors print to stderr and exit 1.
 `,
     daemon: `Usage: rome-node daemon [start|status|stop|serve]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rome-os/node",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Standalone CLI for Rome remote devices",
   "license": "MIT",
   "type": "module",
@@ -22,7 +22,7 @@
     }
   },
   "dependencies": {
-    "@rome-os/node-core": "^0.1.1"
+    "@rome-os/node-core": "^0.1.3"
   },
   "devDependencies": {
     "@rstest/core": "^0.11.11",