@zenalexa/unicli 0.208.0 → 0.210.0

package/src/adapters/zhihu/trending.yaml

@@ -0,0 +1,36 @@
+site: zhihu
+name: trending
+description: Zhihu trending topics by category
+domain: www.zhihu.com
+type: web-api
+strategy: cookie
+auth_cookies: [z_c0]
+
+args:
+  category:
+    type: str
+    default: total
+    description: "Category: total, science, digital, sport, fashion, film, campus"
+  limit:
+    type: int
+    default: 20
+    description: Number of items
+
+pipeline:
+  - fetch:
+      url: https://www.zhihu.com/api/v3/feed/topstory/hot-lists/${{ args.category }}
+      params:
+        limit: "50"
+
+  - select: data
+
+  - map:
+      rank: ${{ index + 1 }}
+      title: ${{ item.target?.title || '' }}
+      heat: ${{ item.detail_text || '' }}
+      excerpt: ${{ (item.target?.excerpt || '') | strip_html | slice(0, 100) }}
+      url: ${{ 'https://www.zhihu.com/question/' + (item.target?.id || '') }}
+
+  - limit: ${{ args.limit }}
+
+columns: [rank, title, heat, excerpt, url]

package/src/adapters/zhihu/user.yaml

@@ -0,0 +1,30 @@
+site: zhihu
+name: user
+description: Get a Zhihu user profile by URL name
+domain: www.zhihu.com
+type: web-api
+strategy: cookie
+auth_cookies: [z_c0]
+
+args:
+  id:
+    required: true
+    positional: true
+    description: User URL token (e.g. zhang-san-12)
+
+pipeline:
+  - fetch:
+      url: https://www.zhihu.com/api/v4/members/${{ args.id }}
+      params:
+        include: "follower_count,following_count,voteup_count,answer_count,articles_count,headline"
+
+  - map:
+      name: ${{ item.name || '' }}
+      headline: ${{ item.headline || '' }}
+      followers: ${{ item.follower_count || 0 }}
+      following: ${{ item.following_count || 0 }}
+      voteup: ${{ item.voteup_count || 0 }}
+      answers: ${{ item.answer_count || 0 }}
+      articles: ${{ item.articles_count || 0 }}
+
+columns: [name, headline, followers, following, voteup, answers, articles]

package/src/adapters/zoom/join.yaml

@@ -0,0 +1,24 @@
+# Desktop adapter — join a Zoom meeting via URL scheme
+site: zoom
+name: join
+description: Join a Zoom meeting by meeting ID
+type: desktop
+binary: open
+detect: Darwin
+strategy: public
+
+args:
+  id:
+    type: str
+    required: true
+    positional: true
+    description: Zoom meeting ID or link
+
+pipeline:
+  - exec:
+      command: open
+      args:
+        - "zoommtg://zoom.us/join?confno=${{ args.id }}"
+      timeout: 5000
+
+columns: [output]

package/src/adapters/zoom/start.yaml

@@ -0,0 +1,17 @@
+# Desktop adapter — start a personal Zoom meeting
+site: zoom
+name: start
+description: Start your personal Zoom meeting
+type: desktop
+binary: open
+detect: Darwin
+strategy: public
+
+pipeline:
+  - exec:
+      command: open
+      args:
+        - "zoommtg://zoom.us/start?confno=personal"
+      timeout: 5000
+
+columns: [output]

package/src/hub/external-clis.yaml

@@ -0,0 +1,343 @@
+# External CLI Registry — declarative catalog of passthrough CLI tools.
+#
+# Each entry maps an external CLI binary so agents can discover and invoke
+# it via `unicli ext run <name> <args>`.  The registry is read at startup;
+# only CLIs whose binary is found on $PATH are registered as live commands.
+
+# ── Tier 0 — Chinese Office (highest value) ─────────────────────────────
+
+- name: lark-cli
+  binary: lark-cli
+  description: "Lark/Feishu — messages, documents, calendar, tasks, 200+ commands"
+  homepage: "https://github.com/larksuite/cli"
+  tags: [lark, feishu, collaboration, productivity]
+  json_flag: "--format json"
+  install:
+    mac: "npm install -g @larksuite/cli"
+    linux: "npm install -g @larksuite/cli"
+    default: "npm install -g @larksuite/cli"
+
+- name: wecom-cli
+  binary: wecom-cli
+  description: "WeCom/WeChat Work — contacts, messages, bots, 100+ commands"
+  homepage: "https://github.com/WecomTeam/wecom-cli"
+  tags: [wecom, wechat-work, enterprise, messaging]
+  json_flag: "--json"
+  install:
+    default: "npm install -g @wecom/cli"
+
+- name: dws
+  binary: dws
+  description: "DingTalk Workspace — messages, docs, calendar, contacts, 86 commands"
+  homepage: "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
+  tags: [dingtalk, workspace, collaboration]
+  install:
+    mac: "curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh"
+    linux: "curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh"
+    default: "npm install -g dingtalk-workspace-cli"
+
+# ── Tier 1 — AI Agent CLIs ──────────────────────────────────────────────
+
+- name: kimi-cli
+  binary: kimi
+  description: "Kimi Code — Moonshot AI coding agent CLI, 8K★"
+  homepage: "https://github.com/MoonshotAI/kimi-cli"
+  tags: [ai, agent, coding, moonshot]
+  json_flag: "--json"
+  install:
+    default: "pip install kimi-cli"
+
+- name: deepagents
+  binary: deepagents
+  description: "DeepAgents — LangChain agent harness CLI, 20K★"
+  homepage: "https://github.com/langchain-ai/deepagents"
+  tags: [ai, agent, langchain, harness]
+  json_flag: "--json"
+  install:
+    default: "pip install deepagents-cli"
+
+# ── Tier 1 — Essential ──────────────────────────────────────────────────
+
+- name: vercel
+  binary: vercel
+  description: "Vercel — deploy, domains, env vars, serverless functions"
+  homepage: "https://vercel.com/docs/cli"
+  tags: [vercel, deployment, serverless]
+  install:
+    default: "npm install -g vercel"
+
+- name: supabase
+  binary: supabase
+  description: "Supabase — Postgres, auth, storage, edge functions"
+  homepage: "https://supabase.com/docs/reference/cli"
+  tags: [supabase, postgres, backend]
+  json_flag: "--output json"
+  install:
+    mac: "brew install supabase/tap/supabase"
+    default: "npm install -g supabase"
+
+- name: stripe
+  binary: stripe
+  description: "Stripe — payments, subscriptions, invoices, webhooks"
+  homepage: "https://stripe.com/docs/stripe-cli"
+  tags: [stripe, payments, billing]
+  json_flag: "--json"
+  install:
+    mac: "brew install stripe/stripe-cli/stripe"
+    default: "brew install stripe/stripe-cli/stripe"
+
+- name: firebase
+  binary: firebase
+  description: "Firebase — hosting, firestore, auth, cloud functions"
+  homepage: "https://firebase.google.com/docs/cli"
+  tags: [firebase, google, backend, hosting]
+  json_flag: "--json"
+  install:
+    default: "npm install -g firebase-tools"
+
+- name: gws
+  binary: gws
+  description: "Google Workspace — Drive, Gmail, Calendar, Sheets, 100+ agent skills"
+  homepage: "https://github.com/googleworkspace/cli"
+  tags: [google, workspace, gmail, calendar, drive, productivity]
+  json_flag: "--format json"
+  install:
+    default: "npm install -g @googleworkspace/cli"
+
+- name: wrangler
+  binary: wrangler
+  description: "Cloudflare Workers — deploy, KV, R2, D1, queues"
+  homepage: "https://developers.cloudflare.com/workers/wrangler"
+  tags: [cloudflare, workers, edge, serverless]
+  json_flag: "--json"
+  install:
+    default: "npm install -g wrangler"
+
+- name: netlify
+  binary: netlify
+  description: "Netlify — deploy, functions, forms, identity"
+  homepage: "https://docs.netlify.com/cli/get-started"
+  tags: [netlify, deployment, jamstack]
+  json_flag: "--json"
+  install:
+    default: "npm install -g netlify-cli"
+
+- name: flyctl
+  binary: fly
+  description: "Fly.io — deploy containers, machines, volumes, secrets"
+  homepage: "https://fly.io/docs/flyctl"
+  tags: [fly, containers, deployment]
+  json_flag: "--json"
+  install:
+    mac: "brew install flyctl"
+    default: "brew install flyctl"
+
+- name: sentry-cli
+  binary: sentry-cli
+  description: "Sentry — releases, source maps, debug symbols"
+  homepage: "https://docs.sentry.io/cli"
+  tags: [sentry, monitoring, error-tracking]
+  install:
+    default: "npm install -g @sentry/cli"
+
+- name: railway
+  binary: railway
+  description: "Railway — deploy, databases, variables, logs"
+  homepage: "https://docs.railway.app/reference/cli-api"
+  tags: [railway, deployment, backend]
+  json_flag: "--json"
+  install:
+    mac: "brew install railway"
+    default: "brew install railway"
+
+- name: mmx-cli
+  binary: mmx
+  description: "MiniMax AI — text, vision, speech, video generation"
+  homepage: "https://www.minimaxi.com"
+  tags: [minimax, ai, generation]
+  install:
+    default: "npm install -g mmx-cli"
+
+# ── Tier 2 — High Value ─────────────────────────────────────────────────
+
+- name: aliyun
+  binary: aliyun
+  description: "Alibaba Cloud — ECS, OSS, RDS, 1000+ commands"
+  homepage: "https://github.com/aliyun/aliyun-cli"
+  tags: [alibaba, cloud, aliyun]
+  json_flag: "--output json"
+  install:
+    mac: "brew install aliyun-cli"
+    default: "brew install aliyun-cli"
+
+- name: tccli
+  binary: tccli
+  description: "Tencent Cloud — CVM, COS, TencentDB, 500+ commands"
+  homepage: "https://cloud.tencent.com/document/product/440"
+  tags: [tencent, cloud, tccli]
+  json_flag: "--output json"
+  install:
+    default: "pip install tccli"
+
+- name: doctl
+  binary: doctl
+  description: "DigitalOcean — droplets, databases, spaces, apps"
+  homepage: "https://docs.digitalocean.com/reference/doctl"
+  tags: [digitalocean, cloud, droplets]
+  json_flag: "--output json"
+  install:
+    mac: "brew install doctl"
+    default: "brew install doctl"
+
+- name: hcloud
+  binary: hcloud
+  description: "Hetzner Cloud — servers, volumes, networks, firewalls"
+  homepage: "https://github.com/hetznercloud/cli"
+  tags: [hetzner, cloud, servers]
+  json_flag: "--output json"
+  install:
+    mac: "brew install hcloud"
+    default: "brew install hcloud"
+
+- name: turso
+  binary: turso
+  description: "Turso — SQLite edge database, groups, replicas"
+  homepage: "https://docs.turso.tech/cli"
+  tags: [turso, sqlite, edge, database]
+  json_flag: "--json"
+  install:
+    default: "curl -sSfL https://get.tur.so/install.sh | bash"
+
+- name: pscale
+  binary: pscale
+  description: "PlanetScale — MySQL branches, deploy requests, backups"
+  homepage: "https://planetscale.com/docs/reference/planetscale-cli"
+  tags: [planetscale, mysql, database]
+  json_flag: "--format json"
+  install:
+    mac: "brew install planetscale/tap/pscale"
+    default: "brew install planetscale/tap/pscale"
+
+- name: neonctl
+  binary: neonctl
+  description: "Neon — serverless Postgres branches, endpoints, roles"
+  homepage: "https://neon.tech/docs/reference/neon-cli"
+  tags: [neon, postgres, serverless, database]
+  json_flag: "--output json"
+  install:
+    default: "npm install -g neonctl"
+
+- name: auth0
+  binary: auth0
+  description: "Auth0 — applications, APIs, users, roles, rules"
+  homepage: "https://auth0.github.io/auth0-cli"
+  tags: [auth0, authentication, identity]
+  json_flag: "--json"
+  install:
+    mac: "brew install auth0"
+    default: "brew install auth0"
+
+- name: algolia
+  binary: algolia
+  description: "Algolia — indices, search rules, API keys, analytics"
+  homepage: "https://www.algolia.com/doc/tools/cli"
+  tags: [algolia, search, indexing]
+  install:
+    mac: "brew install algolia/algolia-cli/algolia"
+    default: "brew install algolia/algolia-cli/algolia"
+
+- name: twilio
+  binary: twilio
+  description: "Twilio — SMS, voice, video, conversations"
+  homepage: "https://www.twilio.com/docs/twilio-cli"
+  tags: [twilio, sms, voice, communication]
+  json_flag: "--output-format json"
+  install:
+    default: "npm install -g twilio-cli"
+
+- name: resend
+  binary: resend
+  description: "Resend — transactional email, domains, API keys"
+  homepage: "https://resend.com/docs/cli"
+  tags: [resend, email, transactional]
+  install:
+    default: "npm install -g resend"
+
+- name: linear
+  binary: linear
+  description: "Linear — issues, projects, cycles, teams"
+  homepage: "https://linear.app/docs"
+  tags: [linear, project-management, issues]
+  install:
+    mac: "brew install linear"
+    default: "brew install linear"
+
+# ── Already have adapters — full passthrough ─────────────────────────────
+
+- name: gh
+  binary: gh
+  description: "GitHub — repos, PRs, issues, actions, releases"
+  homepage: "https://cli.github.com"
+  tags: [github, git, devops]
+  json_flag: "--json"
+  install:
+    mac: "brew install gh"
+    default: "brew install gh"
+
+- name: docker
+  binary: docker
+  description: "Docker — containers, images, volumes, networks"
+  homepage: "https://docs.docker.com/engine/reference/commandline/cli"
+  tags: [docker, containers, devops]
+  json_flag: "--format json"
+  install:
+    default: "https://docs.docker.com/get-docker/"
+
+- name: kubectl
+  binary: kubectl
+  description: "Kubernetes — pods, services, deployments, config"
+  homepage: "https://kubernetes.io/docs/reference/kubectl"
+  tags: [kubernetes, k8s, containers, orchestration]
+  json_flag: "-o json"
+  install:
+    mac: "brew install kubectl"
+    default: "brew install kubectl"
+
+- name: aws
+  binary: aws
+  description: "AWS CLI — EC2, S3, Lambda, 300+ services"
+  homepage: "https://aws.amazon.com/cli"
+  tags: [aws, cloud, amazon]
+  json_flag: "--output json"
+  install:
+    mac: "brew install awscli"
+    default: "brew install awscli"
+
+- name: gcloud
+  binary: gcloud
+  description: "Google Cloud — compute, storage, BigQuery, 200+ services"
+  homepage: "https://cloud.google.com/sdk/gcloud"
+  tags: [gcp, google, cloud]
+  json_flag: "--format json"
+  install:
+    default: "https://cloud.google.com/sdk/docs/install"
+
+- name: az
+  binary: az
+  description: "Azure CLI — VMs, storage, databases, 200+ services"
+  homepage: "https://learn.microsoft.com/cli/azure"
+  tags: [azure, microsoft, cloud]
+  json_flag: "--output json"
+  install:
+    mac: "brew install azure-cli"
+    default: "brew install azure-cli"
+
+- name: ollama
+  binary: ollama
+  description: "Ollama — local LLM runner, model management"
+  homepage: "https://ollama.ai"
+  tags: [ollama, llm, ai, local]
+  json_flag: "--format json"
+  install:
+    mac: "brew install ollama"
+    default: "brew install ollama"

package/src/hub/index.ts

@@ -0,0 +1,128 @@
+/**
+ * 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));
+
+// ── Types ───────────────────────────────────────────────────────────────
+
+export interface ExternalCli {
+  name: string;
+  binary: string;
+  description: string;
+  homepage?: string;
+  tags?: string[];
+  json_flag?: string;
+  install?: Record<string, string>;
+}
+
+// ── Cache ───────────────────────────────────────────────────────────────
+
+let _cache: ExternalCli[] | null = null;
+const _installedCache = new Map<string, boolean>();
+
+// ── 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(): string {
+  // 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(): ExternalCli[] {
+  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 as ExternalCli[];
+    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: string): boolean {
+  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(): Array<
+  ExternalCli & { installed: boolean }
+> {
+  return loadExternalClis().map((cli) => ({
+    ...cli,
+    installed: isInstalled(cli.binary),
+  }));
+}
+
+/**
+ * Look up a single external CLI by name.
+ */
+export function getExternalCli(name: string): ExternalCli | undefined {
+  return loadExternalClis().find((c) => c.name === name);
+}

package/src/hub/passthrough.ts

@@ -0,0 +1,85 @@
+/**
+ * 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";
+import type { ExternalCli } from "./index.js";
+
+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: ExternalCli, args: string[]): void {
+  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: unknown = 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: unknown) {
+    // 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: unknown = 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;
+  }
+}
+
+// ── Type guard ──────────────────────────────────────────────────────────
+
+interface ExecError {
+  status: number | null;
+  stdout: Buffer | null;
+  stderr: Buffer | null;
+}
+
+function isExecError(err: unknown): err is ExecError {
+  return typeof err === "object" && err !== null && "status" in err;
+}