@hydraharness/harness-native-command 0.1.1-rc.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @hydraharness/harness-native-command
+
+A **zero-dependency no-shell `execFile` runner** shared by host-native OS integrations: one `runNativeCommand(command, args, signal)` call spawns the executable directly (never a shell string), captures utf8 stdout/stderr, propagates the caller's abort into child termination, and hides the transient console window on Windows. Failures reject with the exit `code` and both captured streams attached, so callers classify (missing tool, cancelled, real failure) without re-running anything.
+
+Its two consumers are the host-side native integrations: the [`directory-picker-native`](../../host/directory-picker-native/README.md) backend's OS chooser commands and the gateway's open-with-default-application hand-off ([`@hydraharness/harness-host-apiproxy`](../../host/apiproxy/README.md) `host.openPath`). The `NativeCommandRunner` type is their injectable command boundary.
+
+It is a **library, not a service or plugin**: no `ctx`, registers nothing, holds no state, emits no events.
+
+## Surface
+
+```ts
+import { runNativeCommand, type NativeCommandRunner } from '@hydraharness/harness-native-command'
+```
+
+## Model Experience
+
+None, as this is host-side subprocess plumbing; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **No output bounding** — both streams buffer unbounded in memory; every current caller invokes small native tools whose output is a path or an error line. Adopt `@hydraharness/harness-output-retention` bounding before pointing this at commands with meaningful output volume.

package/lib/index.js

@@ -0,0 +1,38 @@
+import { execFile } from "node:child_process";
+//#region lib/types/index.js
+/**
+* Shared no-shell `execFile` runner for host-native OS integrations (the
+* native directory chooser, the open-with-default-application hand-off):
+* utf8 stdio capture, abort propagation, Windows console hide. A library,
+* not a plugin — no ctx, no state, no events.
+* @module @hydraharness/harness-native-command
+*/
+/**
+* Run a host command with utf8 stdio, abort propagation, and Windows hide.
+* @param command - executable path or PATH name.
+* @param args - argv (never a shell string).
+* @param signal - caller/connection lifetime; abort terminates the child.
+* @returns captured stdout/stderr on exit 0.
+*/
+const runNativeCommand = (command, args, signal) => new Promise((resolve, reject) => {
+	execFile(command, [...args], {
+		encoding: "utf8",
+		signal,
+		windowsHide: true
+	}, (error, stdout, stderr) => {
+		if (error !== null) {
+			reject(Object.assign(new Error(error.message, { cause: error }), {
+				code: error.code,
+				stdout,
+				stderr
+			}));
+			return;
+		}
+		resolve({
+			stdout,
+			stderr
+		});
+	});
+});
+//#endregion
+export { runNativeCommand };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-native-command`.
+* @module @hydraharness/harness-native-command/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-native-command";
+/** Cordis companion plugin name. */
+const name = "native-command-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: each run is one stateless child-process round trip
+* with no owned event stream or mutable runtime data; behavior is enforced by
+* unit tests.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared no-shell `execFile` runner for host-native OS integrations (the
+ * native directory chooser, the open-with-default-application hand-off):
+ * utf8 stdio capture, abort propagation, Windows console hide. A library,
+ * not a plugin — no ctx, no state, no events.
+ * @module @hydraharness/harness-native-command
+ */
+/** Testable command boundary; native implementations never invoke a shell. */
+export type NativeCommandRunner = (command: string, args: readonly string[], signal: AbortSignal) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Run a host command with utf8 stdio, abort propagation, and Windows hide.
+ * @param command - executable path or PATH name.
+ * @param args - argv (never a shell string).
+ * @param signal - caller/connection lifetime; abort terminates the child.
+ * @returns captured stdout/stderr on exit 0.
+ */
+export declare const runNativeCommand: NativeCommandRunner;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-native-command`.
+ * @module @hydraharness/harness-native-command/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "native-command-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@hydraharness/harness-native-command",
+  "description": "Zero-dependency no-shell execFile runner for host-native OS integrations: utf8 stdio capture, abort propagation, Windows hide",
+  "version": "0.1.1-rc.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/util/native-command"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2"
+  }
+}