@gjsify/child_process 0.29.0 → 0.31.0

package/lib/types/commands.spec.d.ts

@@ -0,0 +1,111 @@
+/** `[file, args]`, ready to spread into `spawn(…)` / `execFile(…)`. */
+export type Command = readonly [file: string, args: string[]];
+/**
+ * The interpreter this suite is running on — `process.execPath`, whatever that
+ * is here. Exported because the argv0 specs assert the child's default `argv[0]`
+ * against it.
+ */
+export declare const INTERPRETER: string;
+/**
+ * Print the child's `argv[0]` — the portable stand-in for `sh -c 'echo "$0"'`.
+ *
+ * The argv0 specs used the SHELL's `$0` to read back what `options.argv0` set.
+ * Node exposes the same value as `process.argv0`; GJS exposes it as
+ * `imports.system.programInvocationName`, which under `-c` (no script to name)
+ * is argv[0] itself. `GLib.get_prgname()` is NOT usable here — it is the
+ * BASENAME, so it would silently pass the overridden-argv0 assertion and fail
+ * the default one.
+ */
+export declare function printArgv0(): Command;
+/**
+ * Print `text` and a newline to stdout, then exit 0 — `echo <text>`.
+ *
+ * The text travels as an ARGV entry rather than being interpolated into the
+ * source: the specs echo values containing spaces and quotes, and building a
+ * command STRING out of those is the injection-shaped mistake the repo's own
+ * rules call out ("pass an argv array, never an interpolated command line").
+ */
+export declare function echo(...text: string[]): Command;
+/** Print the same as `echo`, but to stderr. */
+export declare function echoErr(...text: string[]): Command;
+/** Print the process's working directory, no trailing newline — `pwd`. */
+export declare function pwd(): Command;
+/** Copy stdin to stdout until EOF — `cat`. */
+export declare function cat(): Command;
+/** Print one environment variable, or the empty string when it is unset. */
+export declare function printEnv(name: string): Command;
+/** Print the integers `from`..`to`, one per line — `seq`. */
+export declare function seq(from: number, to: number): Command;
+/**
+ * Stay alive for `ms` milliseconds, then exit 0 — `sleep`.
+ *
+ * GJS blocks in `g_usleep()` rather than arming a main loop: the sleeping child
+ * is a KILL TARGET in these specs (timeouts, `AbortSignal`, `SIGKILL`), and a
+ * blocked process is killed exactly like an idle one while needing no loop to
+ * be running for the signal to land.
+ */
+export declare function sleep(ms: number): Command;
+/** Exit 0 immediately — `true`. */
+export declare function exitOk(): Command;
+/** Exit with `code` — `false` is `exitWith(1)`. */
+export declare function exitWith(code: number): Command;
+/** Write `text` to stderr, then exit with `code`. */
+export declare function failWith(code: number, text: string): Command;
+/** Write `count` bytes to stdout — the `maxBuffer` specs' subject. */
+export declare function emitBytes(count: number): Command;
+/** Read all of stdin and print it upper-cased, trimmed — the pipeline specs' sink. */
+export declare function upperFromStdin(): Command;
+/**
+ * Expand a shell-style template against the environment and print the result —
+ * the portable stand-in for `sh -c 'echo "VAL=$VAL"'`.
+ *
+ * The env-coercion specs are the reason this exists. Their SUBJECT is what
+ * `spawn` does to an `env` object whose values are not strings (`undefined` is
+ * dropped, `null` becomes `"null"`, a number becomes its decimal string, an
+ * array is comma-joined, and prototype-chain keys still propagate because Node
+ * walks with `for…in`). Reading the result back needed a child that prints an
+ * environment variable, and `sh` was simply the shortest way to write one — so
+ * ten assertions about ENV ended up depending on a POSIX shell.
+ *
+ * Supports `$NAME` and POSIX `${NAME:-default}`, which substitutes when the
+ * variable is unset OR empty. That is the whole grammar those specs use.
+ */
+export declare function printEnvTemplate(template: string): Command;
+/**
+ * Print an environment variable and a newline, then copy stdin to stdout — the
+ * stand-in for `sh -c 'echo $VAR; cat'`, whose subject is that BOTH pipes are
+ * live when `env` carries an `undefined` value.
+ */
+export declare function printEnvThenCat(name: string): Command;
+/** Print an environment variable, then the working directory on the next line. */
+export declare function printEnvThenPwd(name: string): Command;
+/** Running under a `cmd.exe` shell rather than a POSIX one? */
+export declare const SHELL_IS_CMD: boolean;
+/**
+ * libuv's `ENOENT`, which is NOT the same number on every OS.
+ *
+ * libuv gives Windows its own errno space: `UV_ENOENT` is -4058 there against
+ * -2 on POSIX. `err.code` (`'ENOENT'`) is the portable half and is what a
+ * consumer should branch on; the number is asserted here because Node exposes
+ * it and a regression in it would be real.
+ */
+export declare const UV_ENOENT: number;
+/** The shell built-in that prints the working directory. */
+export declare const SHELL_PWD: string;
+/** Shell expansion of an environment variable, in the host shell's grammar. */
+export declare function shellVar(name: string): string;
+/**
+ * A shell COMMAND LINE that runs one of the commands above — for the cases
+ * where no built-in exists on both shells (`tr`, `printf`, `seq`, `cat`).
+ *
+ * DERIVED from the `Command`, never a third hand-written source: that is what
+ * keeps the shell path and the spawn path exercising the same program, and it
+ * is why `setTimeout(() => {}, 10000)` no longer appears five times in
+ * `parity.spec.ts`.
+ *
+ * Every token is double-quoted, which is what makes one command line valid
+ * under `/bin/sh` and `cmd.exe` alike, and it also covers an executable path
+ * containing spaces (`C:\Program Files\nodejs\node.exe`). The sources above are
+ * written with single quotes precisely so this wrapping is lossless.
+ */
+export declare function shellCmd([file, args]: Command): string;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/child_process",
-    "version": "0.29.0",
+    "version": "0.31.0",
     "description": "Node.js child_process module for Gjs",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -37,18 +37,18 @@
         "child_process"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.29.0",
-        "@gjsify/dom-elements": "^0.29.0",
-        "@gjsify/unit": "^0.29.0",
+        "@gjsify/cli": "^0.31.0",
+        "@gjsify/dom-elements": "^0.31.0",
+        "@gjsify/unit": "^0.31.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
     "dependencies": {
         "@girs/gio-2.0": "^4.1.0",
         "@girs/glib-2.0": "^4.1.0",
-        "@gjsify/buffer": "^0.29.0",
-        "@gjsify/events": "^0.29.0",
-        "@gjsify/utils": "^0.29.0"
+        "@gjsify/buffer": "^0.31.0",
+        "@gjsify/events": "^0.31.0",
+        "@gjsify/utils": "^0.31.0"
     },
     "gjsify": {
         "runtimes": {
@@ -57,7 +57,16 @@
             "browser": "none",
             "nativescript": "none"
         },
-        "tier": 1
+        "tier": 1,
+        "os": {
+            "linux": "supported",
+            "darwin": "partial",
+            "win32": "partial"
+        },
+        "osNotes": {
+            "darwin": "`detached: true` degrades. macOS ships no `setsid(1)` (it is a util-linux tool) and `setsid(2)` is unreachable from JS because `g_subprocess_launcher_set_child_setup()` is not introspectable, so `detachedPrefix()` returns `null` unless the user installed one. The child is still spawned and still outlives its parent, but it stays in the parent's process group, so terminal-generated SIGINT/SIGHUP still reach it — see `src/platform/darwin.ts`. Everything else in the package is exercised on darwin by `macos-suites.yml`, including the BSD signal table and the in-process `communicate.ts` timeout that replaced GNU `timeout(1)` for this platform.",
+            "win32": "A `src/platform/win32.ts` exists and is written against Node's documented Windows behaviour, but NOTHING RUNS IT. The package declares `runtimes.node: \"none\"`, so `test:node` exercises native Node rather than this implementation, and `test:gjs` — the leg that would measure it — cannot run on Windows at all because there is no GJS host there. The win32 module is therefore unexercised code, not a verified port. Promote to `supported` when a leg executes it."
+        }
     },
     "license": "MIT",
     "repository": {