@zenalexa/unicli 0.208.0 → 0.210.0

package/dist/hub/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * External CLI Hub — registry and auto-discovery for third-party CLIs.
+ *
+ * Reads `external-clis.yaml` at startup, checks which binaries are
+ * installed on $PATH, and exposes lookup helpers for the rest of the
+ * system (Commander registration, `unicli ext` subcommands, AGENTS.md).
+ */
+export interface ExternalCli {
+    name: string;
+    binary: string;
+    description: string;
+    homepage?: string;
+    tags?: string[];
+    json_flag?: string;
+    install?: Record<string, string>;
+}
+/**
+ * Load and parse the external CLI registry from YAML.
+ * Results are cached after the first call.
+ */
+export declare function loadExternalClis(): ExternalCli[];
+/**
+ * Check whether a binary is available on $PATH.
+ * Uses `which` (macOS/Linux) with a short timeout.  Results are cached.
+ */
+export declare function isInstalled(binary: string): boolean;
+/**
+ * Return every registered external CLI with its install status.
+ */
+export declare function listExternalClis(): Array<ExternalCli & {
+    installed: boolean;
+}>;
+/**
+ * Look up a single external CLI by name.
+ */
+export declare function getExternalCli(name: string): ExternalCli | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/hub/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hub/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAsCD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,EAAE,CAgBhD;AAID;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAgBnD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,KAAK,CACvC,WAAW,GAAG;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,CACrC,CAKA;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEpE"}

package/dist/hub/index.js

@@ -0,0 +1,98 @@
+/**
+ * External CLI Hub — registry and auto-discovery for third-party CLIs.
+ *
+ * Reads `external-clis.yaml` at startup, checks which binaries are
+ * installed on $PATH, and exposes lookup helpers for the rest of the
+ * system (Commander registration, `unicli ext` subcommands, AGENTS.md).
+ */
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+import yaml from "js-yaml";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// ── Cache ───────────────────────────────────────────────────────────────
+let _cache = null;
+const _installedCache = new Map();
+// ── Loader ──────────────────────────────────────────────────────────────
+/**
+ * Resolve the YAML registry path.
+ *
+ * The YAML file ships alongside the TypeScript source in `src/hub/`.
+ * At runtime we may be executing from `dist/hub/`, so we try the source
+ * sibling first (`../../src/hub/`) then fall back to the co-located path.
+ */
+function resolveYamlPath() {
+    // Running from dist/hub/index.js → ../../src/hub/external-clis.yaml
+    const fromDist = join(__dirname, "..", "..", "src", "hub", "external-clis.yaml");
+    // Running from src/hub/index.ts (dev via tsx)
+    const fromSrc = join(__dirname, "external-clis.yaml");
+    // Prefer the source copy (always present in both dev & installed package)
+    try {
+        readFileSync(fromSrc, "utf-8");
+        return fromSrc;
+    }
+    catch {
+        return fromDist;
+    }
+}
+/**
+ * Load and parse the external CLI registry from YAML.
+ * Results are cached after the first call.
+ */
+export function loadExternalClis() {
+    if (_cache)
+        return _cache;
+    try {
+        const raw = readFileSync(resolveYamlPath(), "utf-8");
+        const parsed = yaml.load(raw);
+        if (!Array.isArray(parsed)) {
+            _cache = [];
+            return _cache;
+        }
+        _cache = parsed;
+        return _cache;
+    }
+    catch {
+        _cache = [];
+        return _cache;
+    }
+}
+// ── Discovery ───────────────────────────────────────────────────────────
+/**
+ * Check whether a binary is available on $PATH.
+ * Uses `which` (macOS/Linux) with a short timeout.  Results are cached.
+ */
+export function isInstalled(binary) {
+    if (_installedCache.has(binary)) {
+        return _installedCache.get(binary);
+    }
+    try {
+        execFileSync("which", [binary], {
+            stdio: "pipe",
+            timeout: 3_000,
+        });
+        _installedCache.set(binary, true);
+        return true;
+    }
+    catch {
+        _installedCache.set(binary, false);
+        return false;
+    }
+}
+/**
+ * Return every registered external CLI with its install status.
+ */
+export function listExternalClis() {
+    return loadExternalClis().map((cli) => ({
+        ...cli,
+        installed: isInstalled(cli.binary),
+    }));
+}
+/**
+ * Look up a single external CLI by name.
+ */
+export function getExternalCli(name) {
+    return loadExternalClis().find((c) => c.name === name);
+}
+//# sourceMappingURL=index.js.map

package/dist/hub/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hub/index.ts"],"names":[],"mappings":"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"}

package/dist/hub/passthrough.d.ts

@@ -0,0 +1,21 @@
+/**
+ * External CLI passthrough — execute third-party CLIs with smart output wrapping.
+ *
+ * Security:
+ *   - Uses `execFileSync` (no shell) to prevent command injection.
+ *   - Binary name is looked up from the trusted YAML registry, never from user input.
+ *
+ * Output behavior:
+ *   - TTY stdout  → raw passthrough (human-readable)
+ *   - Piped stdout → attempt JSON parse; wrap as `{"text": "..."}` on failure
+ *   - stderr is always passed through
+ */
+import type { ExternalCli } from "./index.js";
+/**
+ * Execute an external CLI command with passthrough.
+ *
+ * When piped (non-TTY), attempt to parse JSON output or wrap as text.
+ * Exits the process with the child's exit code on failure.
+ */
+export declare function executeExternal(cli: ExternalCli, args: string[]): void;
+//# sourceMappingURL=passthrough.d.ts.map

package/dist/hub/passthrough.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passthrough.d.ts","sourceRoot":"","sources":["../../src/hub/passthrough.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAgDtE"}

package/dist/hub/passthrough.js

@@ -0,0 +1,71 @@
+/**
+ * External CLI passthrough — execute third-party CLIs with smart output wrapping.
+ *
+ * Security:
+ *   - Uses `execFileSync` (no shell) to prevent command injection.
+ *   - Binary name is looked up from the trusted YAML registry, never from user input.
+ *
+ * Output behavior:
+ *   - TTY stdout  → raw passthrough (human-readable)
+ *   - Piped stdout → attempt JSON parse; wrap as `{"text": "..."}` on failure
+ *   - stderr is always passed through
+ */
+import { execFileSync } from "node:child_process";
+const DEFAULT_TIMEOUT_MS = 120_000;
+/**
+ * Execute an external CLI command with passthrough.
+ *
+ * When piped (non-TTY), attempt to parse JSON output or wrap as text.
+ * Exits the process with the child's exit code on failure.
+ */
+export function executeExternal(cli, args) {
+    const isTTY = process.stdout.isTTY ?? false;
+    try {
+        const stdout = execFileSync(cli.binary, args, {
+            stdio: isTTY ? "inherit" : ["inherit", "pipe", "inherit"],
+            timeout: DEFAULT_TIMEOUT_MS,
+            maxBuffer: 50 * 1024 * 1024, // 50 MB
+        });
+        // In TTY mode execFileSync with stdio "inherit" returns null
+        if (!isTTY && stdout) {
+            const output = stdout.toString("utf-8");
+            // Try to parse as JSON and re-emit (validates + normalizes)
+            try {
+                const parsed = JSON.parse(output);
+                process.stdout.write(JSON.stringify(parsed, null, 2) + "\n");
+            }
+            catch {
+                // Not JSON — wrap as structured text object
+                const trimmed = output.trim();
+                if (trimmed.length > 0) {
+                    process.stdout.write(JSON.stringify({ text: trimmed }) + "\n");
+                }
+            }
+        }
+    }
+    catch (err) {
+        // execFileSync throws on non-zero exit — extract code and forward
+        if (isExecError(err)) {
+            // If there was stdout content in piped mode, it's in err.stdout
+            if (!isTTY && err.stdout && err.stdout.length > 0) {
+                const output = err.stdout.toString("utf-8").trim();
+                if (output.length > 0) {
+                    try {
+                        const parsed = JSON.parse(output);
+                        process.stdout.write(JSON.stringify(parsed, null, 2) + "\n");
+                    }
+                    catch {
+                        process.stdout.write(JSON.stringify({ text: output }) + "\n");
+                    }
+                }
+            }
+            process.exit(typeof err.status === "number" ? err.status : 1);
+        }
+        // Unknown error shape — re-throw
+        throw err;
+    }
+}
+function isExecError(err) {
+    return typeof err === "object" && err !== null && "status" in err;
+}
+//# sourceMappingURL=passthrough.js.map

package/dist/hub/passthrough.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passthrough.js","sourceRoot":"","sources":["../../src/hub/passthrough.ts"],"names":[],"mappings":"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"}