11/**
2- * Executor module for interacting with shell processes on Cordova.
3- * Allows starting processes with real-time streaming, writing input,
4- * stopping processes, and traditional one-time execution.
5- *
62 * @module Executor
3+ * @description
4+ * This module provides an interface to run shell commands from a Cordova app.
5+ * It supports real-time process streaming, writing input to running processes,
6+ * stopping them, and executing one-time commands.
77 */
88
99const exec = require ( 'cordova/exec' ) ;
1010
1111const Executor = {
1212 /**
13- * Starts a shell process and sets up real-time streaming for stdout, stderr, and exit events .
13+ * Starts a shell process and enables real-time streaming of stdout, stderr, and exit status .
1414 *
15- * @param {string } command - The shell command to execute (e.g., `"sh"`, `"ls -al"`).
16- * @param {(type: 'stdout' | 'stderr' | 'exit', data: string) => void } onData - Callback to handle real-time output:
15+ * @param {string } command - The shell command to run (e.g., `"sh"`, `"ls -al"`).
16+ * @param {(type: 'stdout' | 'stderr' | 'exit', data: string) => void } onData - Callback that receives real-time output:
1717 * - `"stdout"`: Standard output line.
1818 * - `"stderr"`: Standard error line.
19- * - `"exit"`: Process exit code.
20- *
21- * @returns {Promise<string> } Resolves with the process ID (PID) .
19+ * - `"exit"`: Exit code of the process .
20+ * @param { boolean } alpine - Whether to run the command inside the Alpine sandbox environment (`true`) or on Android directly (`false`).
21+ * @returns {Promise<string> } Resolves with a unique process ID (UUID) used for future references like `write()` or `stop()` .
2222 *
2323 * @example
2424 * Executor.start('sh', (type, data) => {
@@ -28,30 +28,32 @@ const Executor = {
2828 * Executor.stop(uuid);
2929 * });
3030 */
31- start ( command , onData ) {
31+ start ( command , onData , alpine = false ) {
3232 return new Promise ( ( resolve , reject ) => {
3333 exec (
3434 ( message ) => {
35+ // Stream stdout, stderr, or exit notifications
3536 if ( message . startsWith ( "stdout:" ) ) return onData ( "stdout" , message . slice ( 7 ) ) ;
3637 if ( message . startsWith ( "stderr:" ) ) return onData ( "stderr" , message . slice ( 7 ) ) ;
3738 if ( message . startsWith ( "exit:" ) ) return onData ( "exit" , message . slice ( 5 ) ) ;
38- // First message is PID
39+
40+ // First message is always the process UUID
3941 resolve ( message ) ;
4042 } ,
4143 reject ,
4244 "Executor" ,
4345 "start" ,
44- [ command ]
46+ [ command , String ( alpine ) ]
4547 ) ;
4648 } ) ;
4749 } ,
4850
4951 /**
50- * Sends input to the stdin of a running process.
52+ * Sends input to a running process's stdin .
5153 *
5254 * @param {string } uuid - The process ID returned by {@link Executor.start}.
53- * @param {string } input - The input string to send to the process .
54- * @returns {Promise<string> } Resolves when the input is successfully written.
55+ * @param {string } input - Input string to send (e.g., shell commands) .
56+ * @returns {Promise<string> } Resolves once the input is written.
5557 *
5658 * @example
5759 * Executor.write(uuid, 'ls /data');
@@ -63,10 +65,10 @@ const Executor = {
6365 } ,
6466
6567 /**
66- * Stops a running process.
68+ * Terminates a running process.
6769 *
6870 * @param {string } uuid - The process ID returned by {@link Executor.start}.
69- * @returns {Promise<string> } Resolves when the process is terminated .
71+ * @returns {Promise<string> } Resolves when the process has been stopped .
7072 *
7173 * @example
7274 * Executor.stop(uuid);
@@ -76,37 +78,40 @@ const Executor = {
7678 exec ( resolve , reject , "Executor" , "stop" , [ uuid ] ) ;
7779 } ) ;
7880 } ,
81+
82+ /**
83+ * Checks if a process is still running.
84+ *
85+ * @param {string } uuid - The process ID returned by {@link Executor.start}.
86+ * @returns {Promise<boolean> } Resolves `true` if the process is running, `false` otherwise.
87+ *
88+ * @example
89+ * const isAlive = await Executor.isRunning(uuid);
90+ */
7991 isRunning ( uuid ) {
8092 return new Promise ( ( resolve , reject ) => {
81- exec ( ( result ) => {
82- if ( result === "running" ) {
83- resolve ( true )
84- } else if ( result === "exited" ) {
85- resolve ( false )
86- } else {
87- resolve ( false )
88- }
93+ exec ( ( result ) => {
94+ resolve ( result === "running" ) ;
8995 } , reject , "Executor" , "isRunning" , [ uuid ] ) ;
9096 } ) ;
9197 } ,
9298
9399 /**
94- * Executes a shell command and waits for it to finish.
95- * Unlike ` start()` , this is a one-time execution and does not stream real-time output.
100+ * Executes a shell command once and waits for it to finish.
101+ * Unlike { @link Executor. start} , this does not stream output.
96102 *
97- * @param {string } command - The command to execute.
98- * @returns {Promise<string> } Resolves with stdout if the command succeeds, rejects with stderr or error message if it fails.
103+ * @param {string } command - The shell command to execute.
104+ * @param {boolean } alpine - Whether to run the command in the Alpine sandbox (`true`) or Android environment (`false`).
105+ * @returns {Promise<string> } Resolves with standard output on success, rejects with an error or standard error on failure.
99106 *
100107 * @example
101- * Executor.execute('ls -l').then(output => {
102- * console.log(output);
103- * }).catch(error => {
104- * console.error(error);
105- * });
108+ * Executor.execute('ls -l')
109+ * .then(console.log)
110+ * .catch(console.error);
106111 */
107- execute ( command ) {
112+ execute ( command , alpine = false ) {
108113 return new Promise ( ( resolve , reject ) => {
109- exec ( resolve , reject , "Executor" , "exec" , [ command ] ) ;
114+ exec ( resolve , reject , "Executor" , "exec" , [ command , String ( alpine ) ] ) ;
110115 } ) ;
111116 }
112117} ;
0 commit comments