@akon-labs/nexus-cli 0.1.9 → 0.1.11-rc.2

package/dist/skills/mcp-scripting/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: mcp-scripting
+description: Write mcpScript JavaScript for discovering, inspecting, and calling MCP tools.
+---
+
+# MCP scripting
+
+For multi-call MCP work, write ordinary JavaScript with loops, filtering, chaining, fan-out, or other logic between calls. Run that source with `mcpScript`; it is the primary MCP orchestration surface. For a single MCP search, describe, status check, auth action, or tool call, use `mcp` instead.
+
+Write the source naturally, then pass it as `mcpScript`'s `code` argument:
+
+```js
+const { items } = await tools.search({ query: "search issues", server: "github" });
+const candidate = items[0];
+if (!candidate) return { error: "No matching tool" };
+
+const details = await tools.describe({ path: candidate.path });
+if (details.error) return details;
+
+const result = await tools.call(details.path, { query: "is:open label:bug" });
+if (!result.ok) return result;
+emit({ tool: details.path, completed: true });
+return result.data;
+```
+
+## Workflow
+
+1. Find candidate tools with `await tools.search({ query, server?, limit?, offset? })`.
+2. Inspect the exact returned path with `await tools.describe({ path })`.
+3. Call it with `tools.call(path, args)`.
+
+Calls resolve to `{ ok: true, data }` or `{ ok: false, error }`; handle failed calls instead of expecting them to stop the script. `emit(value)` adds user-visible output before the final `return` value. `console` output is captured too.
+
+`tools` is a non-enumerable proxy: `Object.keys(tools)` throws. Always use `tools.search` for discovery. When a known flat path is a valid identifier, direct calls such as `tools.github_search_issues(args)` are supported; use bracket syntax for hyphenated names: `tools["server_tool-name"](args)`. `search`, `call`, `describe`, and promise/serialization names (`then`, `catch`, `finally`, `toJSON`, `toString`, `valueOf`) are reserved on the proxy; if a flat path collides with one, call it via `tools.call("exact-path", args)`.
+
+`tools.search` and `tools.describe` are asynchronous and must be awaited. The default script timeout is 30 seconds; the worker is terminated at the deadline, including for infinite loops. Every invocation still uses normal lazy connection, authentication, output guarding, and approval gates. Result details contain a concise `calls` trace with every search, describe, and call operation; each entry includes its query or path, outcome, and duration.
+
+Use plain JavaScript loops and Promise utilities for composition. Fluent helpers such as `tools.find(...).one()`, `tools.parallel(...)`, and `tools.retry(...)` are not provided.

package/dist/utils/hidden-spawn.d.ts

@@ -0,0 +1,29 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+/**
+ * Windowless relauncher. See native/win32/src/hidden-spawn.c.
+ * The parent spawns this GUI-subsystem exe, which starts the real console
+ * binary with CREATE_NO_WINDOW and no SW_HIDE, so Windows never paints a console.
+ */
+export declare const HIDDEN_SPAWN_TARGET_ENV = "NEXUS_HIDDEN_SPAWN_TARGET";
+export declare const HIDDEN_SPAWN_SCRIPT_ENV = "NEXUS_HIDDEN_SPAWN_SCRIPT";
+export interface HiddenSpawnOptions {
+    platform?: NodeJS.Platform;
+    /** Explicit helper path. Pass an empty string to skip the helper. */
+    hiddenSpawn?: string;
+    execPath?: string;
+}
+/** Locate the built helper next to this package or next to a compiled CLI binary. */
+export declare function findHiddenSpawnBinary(moduleUrl?: string, execPath?: string, arch?: string): string | undefined;
+/**
+ * Point pi-subagents' child binary at the windowless helper.
+ * Returns true when the helper was installed into env.
+ * An explicit PI_SUBAGENT_PI_BINARY is left untouched by the caller.
+ */
+export declare function applyHiddenChildLaunch(env: NodeJS.ProcessEnv, resolved: string, binaryEnv: string, options?: HiddenSpawnOptions): boolean;
+/**
+ * Spawn a child without a console window on Windows.
+ * Uses the helper when it is built; otherwise windowsHide with detached forced off,
+ * because DETACHED_PROCESS makes Windows ignore CREATE_NO_WINDOW.
+ */
+export declare function spawnWithoutConsole(command: string, args: string[], options?: SpawnOptions): ChildProcess;
+//# sourceMappingURL=hidden-spawn.d.ts.map

package/dist/utils/hidden-spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hidden-spawn.d.ts","sourceRoot":"","sources":["../../src/utils/hidden-spawn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAS,MAAM,oBAAoB,CAAC;AAKjF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AACnE,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAEnE,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD,qFAAqF;AACrF,wBAAgB,qBAAqB,CACpC,SAAS,GAAE,MAAwB,EACnC,QAAQ,GAAE,MAAyB,EACnC,IAAI,GAAE,MAAqB,GACzB,MAAM,GAAG,SAAS,CAmBpB;AAMD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACrC,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,kBAAuB,GAC9B,OAAO,CAkBT;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,YAAiB,GAAG,YAAY,CAwB7G","sourcesContent":["import { type ChildProcess, type SpawnOptions, spawn } from \"node:child_process\";\nimport * as fs from \"node:fs\";\nimport * as path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\n/**\n * Windowless relauncher. See native/win32/src/hidden-spawn.c.\n * The parent spawns this GUI-subsystem exe, which starts the real console\n * binary with CREATE_NO_WINDOW and no SW_HIDE, so Windows never paints a console.\n */\nexport const HIDDEN_SPAWN_TARGET_ENV = \"NEXUS_HIDDEN_SPAWN_TARGET\";\nexport const HIDDEN_SPAWN_SCRIPT_ENV = \"NEXUS_HIDDEN_SPAWN_SCRIPT\";\n\nexport interface HiddenSpawnOptions {\n\tplatform?: NodeJS.Platform;\n\t/** Explicit helper path. Pass an empty string to skip the helper. */\n\thiddenSpawn?: string;\n\texecPath?: string;\n}\n\nfunction prebuildArch(arch: string): \"x64\" | \"arm64\" | undefined {\n\tif (arch === \"arm64\") return \"arm64\";\n\tif (arch === \"x64\") return \"x64\";\n\treturn undefined;\n}\n\n/** Locate the built helper next to this package or next to a compiled CLI binary. */\nexport function findHiddenSpawnBinary(\n\tmoduleUrl: string = import.meta.url,\n\texecPath: string = process.execPath,\n\tarch: string = process.arch,\n): string | undefined {\n\tconst folder = prebuildArch(arch);\n\tif (!folder) return undefined;\n\tconst relative = path.join(\"prebuilds\", `win32-${folder}`, \"hidden-spawn.exe\");\n\tconst here = path.dirname(fileURLToPath(moduleUrl));\n\tconst candidates = [\n\t\tpath.join(here, \"hidden-spawn.exe\"),\n\t\tpath.resolve(here, \"../native/win32\", relative),\n\t\tpath.resolve(here, \"../../native/win32\", relative),\n\t\tpath.resolve(here, \"../../../native/win32\", relative),\n\t\tpath.join(path.dirname(execPath), \"hidden-spawn.exe\"),\n\t];\n\treturn candidates.find((candidate) => {\n\t\ttry {\n\t\t\treturn fs.existsSync(candidate);\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t});\n}\n\nfunction isScriptPath(filePath: string): boolean {\n\treturn /\\.(?:mjs|cjs|js)$/i.test(filePath);\n}\n\n/**\n * Point pi-subagents' child binary at the windowless helper.\n * Returns true when the helper was installed into env.\n * An explicit PI_SUBAGENT_PI_BINARY is left untouched by the caller.\n */\nexport function applyHiddenChildLaunch(\n\tenv: NodeJS.ProcessEnv,\n\tresolved: string,\n\tbinaryEnv: string,\n\toptions: HiddenSpawnOptions = {},\n): boolean {\n\tconst platform = options.platform ?? process.platform;\n\tif (platform !== \"win32\") return false;\n\tconst helper =\n\t\toptions.hiddenSpawn !== undefined\n\t\t\t? options.hiddenSpawn.trim() || undefined\n\t\t\t: findHiddenSpawnBinary(import.meta.url, options.execPath ?? process.execPath);\n\tif (!helper) return false;\n\tconst execPath = options.execPath ?? process.execPath;\n\tenv[binaryEnv] = helper;\n\tif (isScriptPath(resolved)) {\n\t\tenv[HIDDEN_SPAWN_TARGET_ENV] = execPath;\n\t\tenv[HIDDEN_SPAWN_SCRIPT_ENV] = resolved;\n\t} else {\n\t\tenv[HIDDEN_SPAWN_TARGET_ENV] = resolved;\n\t\tdelete env[HIDDEN_SPAWN_SCRIPT_ENV];\n\t}\n\treturn true;\n}\n\n/**\n * Spawn a child without a console window on Windows.\n * Uses the helper when it is built; otherwise windowsHide with detached forced off,\n * because DETACHED_PROCESS makes Windows ignore CREATE_NO_WINDOW.\n */\nexport function spawnWithoutConsole(command: string, args: string[], options: SpawnOptions = {}): ChildProcess {\n\tif (process.platform !== \"win32\") {\n\t\treturn spawn(command, args, options);\n\t}\n\tconst helper = findHiddenSpawnBinary();\n\tconst env = { ...(options.env ?? process.env) };\n\tif (helper) {\n\t\tenv[HIDDEN_SPAWN_TARGET_ENV] = command;\n\t\tdelete env[HIDDEN_SPAWN_SCRIPT_ENV];\n\t\treturn spawn(helper, args, {\n\t\t\t...options,\n\t\t\tdetached: false,\n\t\t\tenv,\n\t\t\tshell: false,\n\t\t\twindowsHide: true,\n\t\t});\n\t}\n\treturn spawn(command, args, {\n\t\t...options,\n\t\tdetached: false,\n\t\tenv,\n\t\tshell: false,\n\t\twindowsHide: true,\n\t});\n}\n"]}

package/dist/utils/hidden-spawn.js

@@ -0,0 +1,101 @@
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Windowless relauncher. See native/win32/src/hidden-spawn.c.
+ * The parent spawns this GUI-subsystem exe, which starts the real console
+ * binary with CREATE_NO_WINDOW and no SW_HIDE, so Windows never paints a console.
+ */
+export const HIDDEN_SPAWN_TARGET_ENV = "NEXUS_HIDDEN_SPAWN_TARGET";
+export const HIDDEN_SPAWN_SCRIPT_ENV = "NEXUS_HIDDEN_SPAWN_SCRIPT";
+function prebuildArch(arch) {
+    if (arch === "arm64")
+        return "arm64";
+    if (arch === "x64")
+        return "x64";
+    return undefined;
+}
+/** Locate the built helper next to this package or next to a compiled CLI binary. */
+export function findHiddenSpawnBinary(moduleUrl = import.meta.url, execPath = process.execPath, arch = process.arch) {
+    const folder = prebuildArch(arch);
+    if (!folder)
+        return undefined;
+    const relative = path.join("prebuilds", `win32-${folder}`, "hidden-spawn.exe");
+    const here = path.dirname(fileURLToPath(moduleUrl));
+    const candidates = [
+        path.join(here, "hidden-spawn.exe"),
+        path.resolve(here, "../native/win32", relative),
+        path.resolve(here, "../../native/win32", relative),
+        path.resolve(here, "../../../native/win32", relative),
+        path.join(path.dirname(execPath), "hidden-spawn.exe"),
+    ];
+    return candidates.find((candidate) => {
+        try {
+            return fs.existsSync(candidate);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function isScriptPath(filePath) {
+    return /\.(?:mjs|cjs|js)$/i.test(filePath);
+}
+/**
+ * Point pi-subagents' child binary at the windowless helper.
+ * Returns true when the helper was installed into env.
+ * An explicit PI_SUBAGENT_PI_BINARY is left untouched by the caller.
+ */
+export function applyHiddenChildLaunch(env, resolved, binaryEnv, options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== "win32")
+        return false;
+    const helper = options.hiddenSpawn !== undefined
+        ? options.hiddenSpawn.trim() || undefined
+        : findHiddenSpawnBinary(import.meta.url, options.execPath ?? process.execPath);
+    if (!helper)
+        return false;
+    const execPath = options.execPath ?? process.execPath;
+    env[binaryEnv] = helper;
+    if (isScriptPath(resolved)) {
+        env[HIDDEN_SPAWN_TARGET_ENV] = execPath;
+        env[HIDDEN_SPAWN_SCRIPT_ENV] = resolved;
+    }
+    else {
+        env[HIDDEN_SPAWN_TARGET_ENV] = resolved;
+        delete env[HIDDEN_SPAWN_SCRIPT_ENV];
+    }
+    return true;
+}
+/**
+ * Spawn a child without a console window on Windows.
+ * Uses the helper when it is built; otherwise windowsHide with detached forced off,
+ * because DETACHED_PROCESS makes Windows ignore CREATE_NO_WINDOW.
+ */
+export function spawnWithoutConsole(command, args, options = {}) {
+    if (process.platform !== "win32") {
+        return spawn(command, args, options);
+    }
+    const helper = findHiddenSpawnBinary();
+    const env = { ...(options.env ?? process.env) };
+    if (helper) {
+        env[HIDDEN_SPAWN_TARGET_ENV] = command;
+        delete env[HIDDEN_SPAWN_SCRIPT_ENV];
+        return spawn(helper, args, {
+            ...options,
+            detached: false,
+            env,
+            shell: false,
+            windowsHide: true,
+        });
+    }
+    return spawn(command, args, {
+        ...options,
+        detached: false,
+        env,
+        shell: false,
+        windowsHide: true,
+    });
+}
+//# sourceMappingURL=hidden-spawn.js.map

package/dist/utils/hidden-spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hidden-spawn.js","sourceRoot":"","sources":["../../src/utils/hidden-spawn.ts"],"names":[],"mappings":"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","sourcesContent":["import { type ChildProcess, type SpawnOptions, spawn } from \"node:child_process\";\nimport * as fs from \"node:fs\";\nimport * as path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\n/**\n * Windowless relauncher. See native/win32/src/hidden-spawn.c.\n * The parent spawns this GUI-subsystem exe, which starts the real console\n * binary with CREATE_NO_WINDOW and no SW_HIDE, so Windows never paints a console.\n */\nexport const HIDDEN_SPAWN_TARGET_ENV = \"NEXUS_HIDDEN_SPAWN_TARGET\";\nexport const HIDDEN_SPAWN_SCRIPT_ENV = \"NEXUS_HIDDEN_SPAWN_SCRIPT\";\n\nexport interface HiddenSpawnOptions {\n\tplatform?: NodeJS.Platform;\n\t/** Explicit helper path. Pass an empty string to skip the helper. */\n\thiddenSpawn?: string;\n\texecPath?: string;\n}\n\nfunction prebuildArch(arch: string): \"x64\" | \"arm64\" | undefined {\n\tif (arch === \"arm64\") return \"arm64\";\n\tif (arch === \"x64\") return \"x64\";\n\treturn undefined;\n}\n\n/** Locate the built helper next to this package or next to a compiled CLI binary. */\nexport function findHiddenSpawnBinary(\n\tmoduleUrl: string = import.meta.url,\n\texecPath: string = process.execPath,\n\tarch: string = process.arch,\n): string | undefined {\n\tconst folder = prebuildArch(arch);\n\tif (!folder) return undefined;\n\tconst relative = path.join(\"prebuilds\", `win32-${folder}`, \"hidden-spawn.exe\");\n\tconst here = path.dirname(fileURLToPath(moduleUrl));\n\tconst candidates = [\n\t\tpath.join(here, \"hidden-spawn.exe\"),\n\t\tpath.resolve(here, \"../native/win32\", relative),\n\t\tpath.resolve(here, \"../../native/win32\", relative),\n\t\tpath.resolve(here, \"../../../native/win32\", relative),\n\t\tpath.join(path.dirname(execPath), \"hidden-spawn.exe\"),\n\t];\n\treturn candidates.find((candidate) => {\n\t\ttry {\n\t\t\treturn fs.existsSync(candidate);\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t});\n}\n\nfunction isScriptPath(filePath: string): boolean {\n\treturn /\\.(?:mjs|cjs|js)$/i.test(filePath);\n}\n\n/**\n * Point pi-subagents' child binary at the windowless helper.\n * Returns true when the helper was installed into env.\n * An explicit PI_SUBAGENT_PI_BINARY is left untouched by the caller.\n */\nexport function applyHiddenChildLaunch(\n\tenv: NodeJS.ProcessEnv,\n\tresolved: string,\n\tbinaryEnv: string,\n\toptions: HiddenSpawnOptions = {},\n): boolean {\n\tconst platform = options.platform ?? process.platform;\n\tif (platform !== \"win32\") return false;\n\tconst helper =\n\t\toptions.hiddenSpawn !== undefined\n\t\t\t? options.hiddenSpawn.trim() || undefined\n\t\t\t: findHiddenSpawnBinary(import.meta.url, options.execPath ?? process.execPath);\n\tif (!helper) return false;\n\tconst execPath = options.execPath ?? process.execPath;\n\tenv[binaryEnv] = helper;\n\tif (isScriptPath(resolved)) {\n\t\tenv[HIDDEN_SPAWN_TARGET_ENV] = execPath;\n\t\tenv[HIDDEN_SPAWN_SCRIPT_ENV] = resolved;\n\t} else {\n\t\tenv[HIDDEN_SPAWN_TARGET_ENV] = resolved;\n\t\tdelete env[HIDDEN_SPAWN_SCRIPT_ENV];\n\t}\n\treturn true;\n}\n\n/**\n * Spawn a child without a console window on Windows.\n * Uses the helper when it is built; otherwise windowsHide with detached forced off,\n * because DETACHED_PROCESS makes Windows ignore CREATE_NO_WINDOW.\n */\nexport function spawnWithoutConsole(command: string, args: string[], options: SpawnOptions = {}): ChildProcess {\n\tif (process.platform !== \"win32\") {\n\t\treturn spawn(command, args, options);\n\t}\n\tconst helper = findHiddenSpawnBinary();\n\tconst env = { ...(options.env ?? process.env) };\n\tif (helper) {\n\t\tenv[HIDDEN_SPAWN_TARGET_ENV] = command;\n\t\tdelete env[HIDDEN_SPAWN_SCRIPT_ENV];\n\t\treturn spawn(helper, args, {\n\t\t\t...options,\n\t\t\tdetached: false,\n\t\t\tenv,\n\t\t\tshell: false,\n\t\t\twindowsHide: true,\n\t\t});\n\t}\n\treturn spawn(command, args, {\n\t\t...options,\n\t\tdetached: false,\n\t\tenv,\n\t\tshell: false,\n\t\twindowsHide: true,\n\t});\n}\n"]}