@starhui/huly-cli 0.1.0

package/.env.example

@@ -0,0 +1,12 @@
+HULY_URL=https://huly.app
+HULY_WORKSPACE=your-workspace
+
+# Prefer token auth when available.
+HULY_TOKEN=your-huly-token
+
+# Or use email/password auth instead of HULY_TOKEN.
+# HULY_EMAIL=your@email.com
+# HULY_PASSWORD=your-password
+
+# Optional.
+# HULY_CONNECTION_TIMEOUT=30000

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 starhui-dev
+
+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,110 @@
+# huly-cli
+
+基于 [`@firfi/huly-mcp`](https://github.com/dearlordylord/huly-mcp) 的
+[Huly](https://huly.io/) 命令行客户端。
+
+## 使用方式
+
+无需安装，直接通过 `npx` 运行：
+
+```bash
+npx -y @starhui/huly-cli@latest --help
+```
+
+也可以全局安装后使用：
+
+```bash
+npm install -g @starhui/huly-cli
+huly --help
+```
+
+## 配置
+
+可以通过环境变量配置 Huly，也可以用 `--config` 指定 dotenv 格式的配置文件。
+
+```bash
+cp .env.example .env
+```
+
+必填配置：
+
+- `HULY_URL`
+- `HULY_WORKSPACE`
+- `HULY_TOKEN`，或 `HULY_EMAIL` 加 `HULY_PASSWORD`
+
+可选配置：
+
+- `HULY_DEFAULT_PROJECT`：`issue` 命令未传 `--project` 时使用的默认项目。
+- `HULY_CONNECTION_TIMEOUT`：透传给 `@firfi/huly-mcp` 的连接超时时间。
+
+下面这些诊断命令不需要 Huly 凭据：
+
+```bash
+npx -y @starhui/huly-cli@latest context --json
+npx -y @starhui/huly-cli@latest tools --filter issue --json
+```
+
+## 示例
+
+```bash
+npx -y @starhui/huly-cli@latest --config .env project list --json
+npx -y @starhui/huly-cli@latest --config .env project statuses HULY --json
+npx -y @starhui/huly-cli@latest --config .env issue list --project HULY --status-category active --limit 20 --json
+npx -y @starhui/huly-cli@latest --config .env issue get HULY-123 --project HULY --json
+npx -y @starhui/huly-cli@latest --config .env issue create --project HULY --title "Fix login redirect"
+npx -y @starhui/huly-cli@latest --config .env issue update HULY-123 --project HULY --status Done
+npx -y @starhui/huly-cli@latest --config .env search "login redirect" --json
+```
+
+对于没有封装成一级命令的能力，可以直接调用上游 MCP 工具：
+
+```bash
+npx -y @starhui/huly-cli@latest --config .env call list_projects --data '{"limit":10}' --json
+npx -y @starhui/huly-cli@latest --config .env call get_issue --field project=HULY --field identifier=HULY-123 --json
+```
+
+## 命令
+
+- `context`：输出脱敏后的 MCP/Huly 运行上下文。
+- `version-remote`：输出底层 `@firfi/huly-mcp` 版本信息。
+- `tools`：列出上游 MCP 暴露的工具。
+- `project list|get|statuses|create|update|delete`：项目相关操作。
+- `issue list|get|create|update|delete|label|unlabel|move`：常用 Issue 操作。
+- `search`：全文搜索。
+- `call`：直接调用 `@firfi/huly-mcp` 暴露的任意工具。
+
+删除、更新等破坏性命令默认会要求确认；传入 `--yes` 后跳过确认。
+
+## Agent Skill
+
+这个包内置 Codex/OpenAI skill，路径为 `skills/huly-cli/SKILL.md`。
+skill 示例使用 `npx -y @starhui/huly-cli@latest`，方便 agent 在没有本地安装 CLI 的情况下直接运行。
+
+使用 `skills` CLI 全局安装：
+
+```bash
+npx -y skills add starhui-dev/huly-cli --skill huly-cli --global
+```
+
+安装到当前项目时去掉 `--global`：
+
+```bash
+npx -y skills add starhui-dev/huly-cli --skill huly-cli
+```
+
+安装前查看仓库中可用的 skills：
+
+```bash
+npx -y skills add starhui-dev/huly-cli --list --full-depth
+```
+
+## 开发
+
+```bash
+pnpm install
+pnpm check
+pnpm pack --dry-run
+```
+
+`pnpm check` 会依次运行类型检查、单元测试、构建、本地 CLI 冒烟测试和上游 MCP 启动冒烟测试。
+真实的 Huly 读写操作需要有效的 Huly 凭据和网络连接。

package/dist/index.js

@@ -0,0 +1,644 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/config.ts
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+var ENV_KEYS = /* @__PURE__ */ new Set([
+  "HULY_URL",
+  "HULY_EMAIL",
+  "HULY_PASSWORD",
+  "HULY_TOKEN",
+  "HULY_WORKSPACE",
+  "HULY_CONNECTION_TIMEOUT"
+]);
+var parseEnvFile = (content) => {
+  const parsed = {};
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const normalized = line.startsWith("export ") ? line.slice("export ".length).trim() : line;
+    const separatorIndex = normalized.indexOf("=");
+    if (separatorIndex <= 0) continue;
+    const key = normalized.slice(0, separatorIndex).trim();
+    if (!ENV_KEYS.has(key)) continue;
+    parsed[key] = parseEnvValue(normalized.slice(separatorIndex + 1).trim());
+  }
+  return parsed;
+};
+var parseEnvValue = (value) => {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if (first === '"' && last === '"' || first === "'" && last === "'") {
+      return value.slice(1, -1);
+    }
+  }
+  const hashIndex = value.indexOf(" #");
+  return hashIndex === -1 ? value : value.slice(0, hashIndex).trimEnd();
+};
+var loadConfig = (options) => {
+  const configPath = options.config === void 0 ? void 0 : resolve(options.config);
+  const envFromFile = configPath === void 0 ? {} : existsSync(configPath) ? parseEnvFile(readFileSync(configPath, "utf8")) : fail(`Config file not found: ${configPath}`);
+  return {
+    env: {
+      ...process.env,
+      ...envFromFile
+    },
+    ...configPath === void 0 ? {} : { configPath }
+  };
+};
+var validateConfig = (config) => {
+  const env = config.env;
+  const missing = [];
+  if (!hasText(env.HULY_URL)) missing.push("HULY_URL");
+  if (!hasText(env.HULY_WORKSPACE)) missing.push("HULY_WORKSPACE");
+  const hasToken = hasText(env.HULY_TOKEN);
+  const hasPasswordAuth = hasText(env.HULY_EMAIL) && hasText(env.HULY_PASSWORD);
+  if (!hasToken && !hasPasswordAuth) {
+    missing.push("HULY_TOKEN or HULY_EMAIL+HULY_PASSWORD");
+  }
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing Huly configuration: ${missing.join(", ")}. Set environment variables or pass --config .env.`
+    );
+  }
+};
+var hasText = (value) => value !== void 0 && value.trim() !== "";
+var fail = (message) => {
+  throw new Error(message);
+};
+
+// src/mcp-client.ts
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+
+// src/json.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+var parseJsonObject = (value, label) => {
+  const parsed = parseJson(value, label);
+  if (!isRecord(parsed)) {
+    throw new Error(`${label} must be a JSON object`);
+  }
+  return parsed;
+};
+var parseJson = (value, label) => {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw new Error(`${label} is not valid JSON: ${String(error)}`);
+  }
+};
+var readJsonObjectFile = (path) => parseJsonObject(readFileSync2(path, "utf8"), path);
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+
+// src/mcp-client.ts
+var require2 = createRequire(import.meta.url);
+var createHulyMcpClient = async (config) => {
+  const serverPath = config.env.HULY_CLI_MCP_SERVER_PATH ?? require2.resolve("@firfi/huly-mcp");
+  const transport = new JsonRpcStdioClient(
+    process.execPath,
+    [serverPath],
+    {
+      ...sanitizeEnv(config.env),
+      LAZY_ENVS: "true",
+      MCP_TRANSPORT: "stdio"
+    }
+  );
+  await transport.start();
+  await transport.request("initialize", {
+    protocolVersion: "2025-06-18",
+    capabilities: {},
+    clientInfo: {
+      name: "huly-cli",
+      version: "0.1.0"
+    }
+  });
+  await transport.notify("notifications/initialized", {});
+  return {
+    callTool: async (name, args) => {
+      const response = await transport.request("tools/call", { name, arguments: args });
+      return extractToolResult(response);
+    },
+    listTools: async () => {
+      const response = await transport.request("tools/list", {});
+      return extractTools(response);
+    },
+    close: async () => {
+      await transport.close();
+    }
+  };
+};
+var JsonRpcStdioClient = class {
+  constructor(command, args, env) {
+    this.command = command;
+    this.args = args;
+    this.env = env;
+  }
+  command;
+  args;
+  env;
+  child;
+  nextId = 1;
+  buffer = "";
+  pending = /* @__PURE__ */ new Map();
+  start() {
+    this.child = spawn(this.command, [...this.args], {
+      env: {
+        ...safeInheritedEnv(),
+        ...this.env
+      },
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true
+    });
+    this.child.stdout.setEncoding("utf8");
+    this.child.stdout.on("data", (chunk) => {
+      this.buffer += chunk;
+      this.drainBuffer();
+    });
+    this.child.stderr.setEncoding("utf8");
+    this.child.stderr.on("data", () => {
+    });
+    this.child.on("error", (error) => {
+      this.rejectAll(error);
+    });
+    this.child.on("close", (code) => {
+      if (this.pending.size > 0) {
+        this.rejectAll(new Error(`Huly MCP server exited with code ${code ?? "unknown"}`));
+      }
+    });
+    return Promise.resolve();
+  }
+  async request(method, params) {
+    const id = this.nextId++;
+    const message = {
+      jsonrpc: "2.0",
+      id,
+      method,
+      params
+    };
+    const response = new Promise((resolve2, reject) => {
+      this.pending.set(id, { resolve: resolve2, reject });
+    });
+    await this.write(message);
+    return response;
+  }
+  async notify(method, params) {
+    await this.write({
+      jsonrpc: "2.0",
+      method,
+      params
+    });
+  }
+  async close() {
+    if (this.child === void 0) return;
+    const child = this.child;
+    this.child = void 0;
+    const closed = new Promise((resolve2) => {
+      child.once("close", () => resolve2());
+    });
+    child.stdin.end();
+    await Promise.race([closed, delay(500)]);
+    if (child.exitCode === null) child.kill("SIGTERM");
+    await Promise.race([closed, delay(500)]);
+    if (child.exitCode === null) child.kill("SIGKILL");
+  }
+  write(message) {
+    if (this.child === void 0) throw new Error("Huly MCP server is not running");
+    return new Promise((resolve2, reject) => {
+      this.child?.stdin.write(`${JSON.stringify(message)}
+`, (error) => {
+        if (error !== null && error !== void 0) {
+          reject(error);
+        } else {
+          resolve2();
+        }
+      });
+    });
+  }
+  drainBuffer() {
+    while (true) {
+      const newline = this.buffer.indexOf("\n");
+      if (newline === -1) return;
+      const rawLine = this.buffer.slice(0, newline).replace(/\r$/, "");
+      this.buffer = this.buffer.slice(newline + 1);
+      if (rawLine.trim() === "") continue;
+      this.handleMessage(parseJsonRpcLine(rawLine));
+    }
+  }
+  handleMessage(message) {
+    if (!isRecord(message) || typeof message.id !== "number") return;
+    const pending = this.pending.get(message.id);
+    if (pending === void 0) return;
+    this.pending.delete(message.id);
+    if (isJsonRpcFailure(message)) {
+      const code = typeof message.error.code === "number" ? message.error.code : "";
+      const fallback = `JSON-RPC error ${code}`.trim();
+      pending.reject(new Error(typeof message.error.message === "string" ? message.error.message : fallback));
+      return;
+    }
+    if (isJsonRpcSuccess(message)) {
+      pending.resolve(message.result);
+      return;
+    }
+    pending.reject(new Error("Invalid JSON-RPC response from Huly MCP server"));
+  }
+  rejectAll(error) {
+    for (const pending of this.pending.values()) {
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+};
+var extractToolResult = (response) => {
+  if (isRecord(response) && response.isError === true) {
+    throw new Error(extractTextContent(response) ?? "Huly MCP tool failed");
+  }
+  if (isRecord(response) && isRecord(response.structuredContent) && "result" in response.structuredContent) {
+    return response.structuredContent.result;
+  }
+  const text = isRecord(response) ? extractTextContent(response) : void 0;
+  if (text === void 0) return response;
+  if (text.trim() === "") return response;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+};
+var extractTools = (response) => {
+  if (!isRecord(response) || !Array.isArray(response.tools)) {
+    throw new Error("Invalid tools/list response from Huly MCP server");
+  }
+  return response.tools.filter(isRecord).map((tool) => ({
+    name: String(tool.name),
+    ...typeof tool.description === "string" ? { description: tool.description } : {}
+  }));
+};
+var extractTextContent = (response) => {
+  const content = response.content;
+  if (!Array.isArray(content)) return void 0;
+  return content.filter(isRecord).filter((item) => item.type === "text" && typeof item.text === "string").map((item) => item.text).join("\n");
+};
+var sanitizeEnv = (env) => {
+  const result = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== void 0) result[key] = value;
+  }
+  return result;
+};
+var safeInheritedEnv = () => {
+  const keys = process.platform === "win32" ? [
+    "APPDATA",
+    "HOMEDRIVE",
+    "HOMEPATH",
+    "LOCALAPPDATA",
+    "PATH",
+    "PROCESSOR_ARCHITECTURE",
+    "SYSTEMDRIVE",
+    "SYSTEMROOT",
+    "TEMP",
+    "USERNAME",
+    "USERPROFILE",
+    "PROGRAMFILES"
+  ] : ["HOME", "LOGNAME", "PATH", "SHELL", "TERM", "USER"];
+  const env = {};
+  for (const key of keys) {
+    const value = process.env[key];
+    if (value !== void 0 && !value.startsWith("()")) env[key] = value;
+  }
+  return env;
+};
+var parseJsonRpcLine = (line) => {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return void 0;
+  }
+};
+var isJsonRpcSuccess = (message) => message.jsonrpc === "2.0" && typeof message.id === "number" && "result" in message;
+var isJsonRpcFailure = (message) => message.jsonrpc === "2.0" && typeof message.id === "number" && isRecord(message.error);
+var delay = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+
+// src/options.ts
+var collectKeyValue = (value, previous) => {
+  const separatorIndex = value.indexOf("=");
+  if (separatorIndex <= 0) {
+    throw new Error(`Expected key=value, got "${value}"`);
+  }
+  const key = value.slice(0, separatorIndex);
+  const raw = value.slice(separatorIndex + 1);
+  return {
+    ...previous,
+    [key]: coerceScalar(raw)
+  };
+};
+var coerceScalar = (value) => {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null") return null;
+  if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
+  return value;
+};
+
+// src/output.ts
+var printResult = (value, options) => {
+  if (options.format === "json") {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(`${formatPretty(value)}
+`);
+};
+var formatPretty = (value) => {
+  if (Array.isArray(value)) return value.map(formatPretty).join("\n");
+  if (isRecord2(value)) {
+    if (Array.isArray(value.projects)) return formatTable(value.projects);
+    if (Array.isArray(value.issues)) return formatTable(value.issues);
+    if (Array.isArray(value.statuses)) return formatTable(value.statuses);
+    if (Array.isArray(value.items)) return formatTable(value.items);
+    return formatObject(value);
+  }
+  return String(value);
+};
+var formatObject = (record) => {
+  const lines = [];
+  for (const [key, value] of Object.entries(record)) {
+    if (Array.isArray(value)) {
+      lines.push(`${key}:`);
+      lines.push(value.map((item) => `  ${formatInline(item)}`).join("\n"));
+    } else if (isRecord2(value)) {
+      lines.push(`${key}: ${JSON.stringify(value, null, 2)}`);
+    } else {
+      lines.push(`${key}: ${formatInline(value)}`);
+    }
+  }
+  return lines.join("\n");
+};
+var formatTable = (rows) => {
+  if (rows.length === 0) return "(no results)";
+  if (!rows.every(isRecord2)) return rows.map(formatInline).join("\n");
+  const records = rows;
+  const columns = selectColumns(records);
+  const widths = columns.map(
+    (column) => Math.max(column.length, ...records.map((row) => formatInline(row[column]).length))
+  );
+  const header = columns.map((column, index) => column.padEnd(widths[index] ?? column.length)).join("  ");
+  const divider = widths.map((width) => "-".repeat(width)).join("  ");
+  const body = records.map(
+    (row) => columns.map((column, index) => formatInline(row[column]).padEnd(widths[index] ?? column.length)).join("  ")
+  );
+  return [header, divider, ...body].join("\n");
+};
+var selectColumns = (rows) => {
+  const preferred = [
+    "identifier",
+    "project",
+    "title",
+    "name",
+    "status",
+    "category",
+    "priority",
+    "assignee",
+    "archived",
+    "modifiedOn",
+    "id",
+    "class",
+    "score"
+  ];
+  const available = new Set(rows.flatMap((row) => Object.keys(row)));
+  const selected = preferred.filter((column) => available.has(column));
+  return selected.length > 0 ? selected : Object.keys(rows[0] ?? {});
+};
+var formatInline = (value) => {
+  if (value === void 0 || value === null) return "";
+  if (typeof value === "string") return value.replace(/\s+/g, " ").trim();
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return JSON.stringify(value);
+};
+var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+
+// src/prompts.ts
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+var confirmDestructiveAction = async (prompt, options) => {
+  if (options.yes === true) return;
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = await rl.question(`${prompt} Type "yes" to continue: `);
+    if (answer !== "yes") {
+      throw new Error("Aborted");
+    }
+  } finally {
+    rl.close();
+  }
+};
+
+// src/commands.ts
+var registerCommands = (program2) => {
+  program2.command("context").description("Print sanitized Huly MCP runtime context").action(async (_options, command) => {
+    await callAndPrint("get_huly_context", {}, normalizeOptions(command), { validate: false });
+  });
+  program2.command("version-remote").description("Print the underlying huly-mcp version information").action(async (_options, command) => {
+    await callAndPrint("get_version", {}, normalizeOptions(command), { validate: false });
+  });
+  program2.command("tools").description("List available Huly MCP tools").option("--filter <text>", "Filter by tool name or description").action(async (options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    const client = await createClient(mergedOptions, { validate: false });
+    try {
+      const tools = await client.listTools();
+      const filter = mergedOptions.filter?.toLowerCase();
+      const visible = filter === void 0 ? tools : tools.filter(
+        (tool) => tool.name.toLowerCase().includes(filter) || tool.description?.toLowerCase().includes(filter) === true
+      );
+      printResult(visible, { format: outputFormat(mergedOptions) });
+    } finally {
+      await client.close();
+    }
+  });
+  const projects = program2.command("project").description("Manage Huly projects");
+  projects.command("list").description("List projects").option("--archived", "Include archived projects").option("--limit <number>", "Maximum number of projects").action(async (options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    await callAndPrint("list_projects", compact({
+      includeArchived: mergedOptions.archived,
+      limit: parseOptionalNumber(mergedOptions.limit, "limit")
+    }), mergedOptions);
+  });
+  projects.command("get <project>").description("Get project details").action(async (project, _options, command) => {
+    await callAndPrint("get_project", { project }, normalizeOptions(command));
+  });
+  projects.command("statuses <project>").description("List issue statuses for a project").action(async (project, _options, command) => {
+    await callAndPrint("list_statuses", { project }, normalizeOptions(command));
+  });
+  projects.command("create").description("Create a tracker project").requiredOption("--name <name>", "Project name").requiredOption("--identifier <identifier>", "Project identifier, e.g. HULY").option("--description <text>", "Project description").option("--private", "Create private project").action(async (options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    await callAndPrint("create_project", compact({
+      name: mergedOptions.name,
+      identifier: mergedOptions.identifier,
+      description: mergedOptions.description,
+      private: mergedOptions.private
+    }), mergedOptions);
+  });
+  projects.command("update <project>").description("Update a project").option("--name <name>", "New project name").option("--description <text>", "New project description").option("--clear-description", "Clear project description").action(async (project, options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    await callAndPrint("update_project", compact({
+      project,
+      name: mergedOptions.name,
+      description: mergedOptions.clearDescription === true ? null : mergedOptions.description
+    }), mergedOptions);
+  });
+  projects.command("delete <project>").description("Delete a project").option("-y, --yes", "Skip confirmation").action(async (project, options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    await confirmDestructiveAction(`Delete project ${project}?`, mergedOptions);
+    await callAndPrint("delete_project", { project }, mergedOptions);
+  });
+  const issues = program2.command("issue").description("Manage Huly issues");
+  issues.command("list").description("List issues").option("-p, --project <project>", "Project identifier; defaults to HULY_DEFAULT_PROJECT").option("--status <status>", "Exact workflow status").option("--status-category <category>", "Status category").option("--assignee <person>", "Assignee email or display name").option("--component <component>", "Component id or label").option("--parent-issue <issue>", "List children of an issue").option("--title <text>", "Case-insensitive title search").option("--description <text>", "Description fulltext search").option("--top-level", "Only top-level issues").option("--limit <number>", "Maximum number of issues").action(async (options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    await callAndPrint("list_issues", compact({
+      project: requireProject(mergedOptions),
+      status: mergedOptions.status,
+      statusCategory: mergedOptions.statusCategory,
+      assignee: mergedOptions.assignee,
+      component: mergedOptions.component,
+      parentIssue: mergedOptions.parentIssue,
+      titleSearch: mergedOptions.title,
+      descriptionSearch: mergedOptions.description,
+      isTopLevel: mergedOptions.topLevel,
+      limit: parseOptionalNumber(mergedOptions.limit, "limit")
+    }), mergedOptions);
+  });
+  issues.command("get <identifier>").description("Get issue details").option("-p, --project <project>", "Project identifier; defaults to HULY_DEFAULT_PROJECT").action(async (identifier, options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    await callAndPrint("get_issue", { project: requireProject(mergedOptions), identifier }, mergedOptions);
+  });
+  issues.command("create").description("Create an issue").option("-p, --project <project>", "Project identifier; defaults to HULY_DEFAULT_PROJECT").requiredOption("--title <title>", "Issue title").option("--description <markdown>", "Issue description").option("--priority <priority>", "urgent, high, medium, low, no-priority").option("--assignee <person>", "Assignee email or display name").option("--status <status>", "Initial status").option("--task-type <taskType>", "Task type id or display name").option("--parent-issue <issue>", "Create as sub-issue").option("--due-date <timestamp>", "Due date as Unix timestamp in milliseconds").option("--estimation <minutes>", "Time estimation in minutes").action(async (options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    await callAndPrint("create_issue", compact({
+      project: requireProject(mergedOptions),
+      title: mergedOptions.title,
+      description: mergedOptions.description,
+      priority: mergedOptions.priority,
+      assignee: mergedOptions.assignee,
+      status: mergedOptions.status,
+      taskType: mergedOptions.taskType,
+      parentIssue: mergedOptions.parentIssue,
+      dueDate: parseOptionalNumber(mergedOptions.dueDate, "due-date"),
+      estimation: parseOptionalNumber(mergedOptions.estimation, "estimation")
+    }), mergedOptions);
+  });
+  issues.command("update <identifier>").description("Update an issue").option("-p, --project <project>", "Project identifier; defaults to HULY_DEFAULT_PROJECT").option("--title <title>", "New title").option("--description <markdown>", "New description").option("--priority <priority>", "New priority").option("--assignee <person>", "New assignee").option("--unassign", "Clear assignee").option("--status <status>", "New status").option("--task-type <taskType>", "New task type").option("--due-date <timestamp>", "Due date as Unix timestamp in milliseconds").option("--clear-due-date", "Clear due date").option("--estimation <minutes>", "Time estimation in minutes").option("--clear-estimation", "Clear estimation").action(async (identifier, options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    await callAndPrint("update_issue", compact({
+      project: requireProject(mergedOptions),
+      identifier,
+      title: mergedOptions.title,
+      description: mergedOptions.description,
+      priority: mergedOptions.priority,
+      assignee: mergedOptions.unassign === true ? null : mergedOptions.assignee,
+      status: mergedOptions.status,
+      taskType: mergedOptions.taskType,
+      dueDate: mergedOptions.clearDueDate === true ? null : parseOptionalNumber(mergedOptions.dueDate, "due-date"),
+      estimation: mergedOptions.clearEstimation === true ? null : parseOptionalNumber(mergedOptions.estimation, "estimation")
+    }), mergedOptions);
+  });
+  issues.command("delete <identifier>").description("Delete an issue").option("-p, --project <project>", "Project identifier; defaults to HULY_DEFAULT_PROJECT").option("-y, --yes", "Skip confirmation").action(async (identifier, options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    const project = requireProject(mergedOptions);
+    await confirmDestructiveAction(`Delete issue ${identifier} in ${project}?`, mergedOptions);
+    await callAndPrint("delete_issue", { project, identifier }, mergedOptions);
+  });
+  issues.command("label <identifier> <label>").description("Add a label to an issue").option("-p, --project <project>", "Project identifier; defaults to HULY_DEFAULT_PROJECT").option("--color <index>", "Huly color index").action(async (identifier, label, options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    await callAndPrint("add_issue_label", compact({
+      project: requireProject(mergedOptions),
+      identifier,
+      label,
+      color: parseOptionalNumber(mergedOptions.color, "color")
+    }), mergedOptions);
+  });
+  issues.command("unlabel <identifier> <label>").description("Remove a label from an issue").option("-p, --project <project>", "Project identifier; defaults to HULY_DEFAULT_PROJECT").action(async (identifier, label, options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    await callAndPrint("remove_issue_label", {
+      project: requireProject(mergedOptions),
+      identifier,
+      label
+    }, mergedOptions);
+  });
+  issues.command("move <identifier>").description("Move an issue under a new parent or to top-level").option("-p, --project <project>", "Project identifier; defaults to HULY_DEFAULT_PROJECT").option("--parent <identifier>", "New parent issue").option("--top-level", "Move to top-level").action(async (identifier, options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    await callAndPrint("move_issue", {
+      project: requireProject(mergedOptions),
+      identifier,
+      newParent: mergedOptions.topLevel === true ? null : mergedOptions.parent
+    }, mergedOptions);
+  });
+  program2.command("search <query>").description("Run Huly fulltext search").option("--limit <number>", "Maximum number of results").action(async (query, options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    await callAndPrint("fulltext_search", compact({
+      query,
+      limit: parseOptionalNumber(mergedOptions.limit, "limit")
+    }), mergedOptions);
+  });
+  program2.command("call <tool>").description("Call any raw huly-mcp tool by name").option("--data <json>", "JSON object arguments").option("--file <path>", "JSON file containing arguments").option("--field <key=value>", "Add a scalar argument; can be repeated", collectKeyValue, {}).action(async (tool, options, command) => {
+    const mergedOptions = normalizeOptions(command, options);
+    const args = mergeRawArgs(mergedOptions);
+    await callAndPrint(tool, args, mergedOptions);
+  });
+};
+var callAndPrint = async (toolName, args, options, clientOptions = {}) => {
+  const client = await createClient(options, clientOptions);
+  try {
+    const result = await client.callTool(toolName, args);
+    printResult(result, { format: outputFormat(options) });
+  } finally {
+    await client.close();
+  }
+};
+var createClient = async (options, clientOptions = {}) => {
+  const config = loadConfig(options);
+  if (clientOptions.validate !== false) validateConfig(config);
+  return createHulyMcpClient(config);
+};
+var mergeRawArgs = (options) => {
+  const fromData = options.data === void 0 ? {} : parseJsonObject(options.data, "--data");
+  const fromFile = options.file === void 0 ? {} : readJsonObjectFile(options.file);
+  return {
+    ...fromFile,
+    ...fromData,
+    ...options.field
+  };
+};
+var compact = (record) => Object.fromEntries(Object.entries(record).filter(([, value]) => value !== void 0));
+var outputFormat = (options) => options.json === true ? "json" : "pretty";
+var normalizeOptions = (command, options) => ({
+  ...command.optsWithGlobals(),
+  ...options
+});
+var requireProject = (options) => {
+  const project = options.project ?? process.env.HULY_DEFAULT_PROJECT;
+  if (project === void 0 || project.trim() === "") {
+    throw new Error("Project is required. Pass --project or set HULY_DEFAULT_PROJECT.");
+  }
+  return project;
+};
+var parseOptionalNumber = (value, label) => {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) throw new Error(`${label} must be a number`);
+  return parsed;
+};
+
+// src/index.ts
+var program = new Command();
+program.name("huly").description("Huly command-line client powered by @firfi/huly-mcp").version("0.1.0").option("--config <path>", "Load Huly env vars from a dotenv-style file").option("--json", "Print JSON output").showHelpAfterError();
+registerCommands(program);
+program.parseAsync(process.argv).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`Error: ${message}
+`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@starhui/huly-cli",
+  "version": "0.1.0",
+  "description": "Command-line client for Huly built on top of huly-mcp.",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "huly": "./dist/index.js",
+    "huly-cli": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills/huly-cli",
+    "README.md",
+    ".env.example"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "huly",
+    "cli",
+    "mcp",
+    "issue-tracker",
+    "project-management"
+  ],
+  "homepage": "https://github.com/starhui-dev/huly-cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/starhui-dev/huly-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/starhui-dev/huly-cli/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@firfi/huly-mcp": "0.29.0",
+    "commander": "15.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.1.0",
+    "esbuild": "0.28.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.8"
+  },
+  "scripts": {
+    "build": "pnpm typecheck && rm -rf dist && esbuild src/index.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/index.js",
+    "test": "vitest run",
+    "smoke": "node scripts/smoke-cli.mjs",
+    "smoke:upstream": "node scripts/smoke-upstream.mjs",
+    "pack:dry": "pnpm pack --dry-run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check": "pnpm typecheck && pnpm test && pnpm build && pnpm smoke && pnpm smoke:upstream"
+  }
+}

package/skills/huly-cli/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: huly-cli
+description: Use this skill when the user wants to inspect or change Huly data from the terminal using huly-cli through npx, including projects, issues, statuses, labels, fulltext search, or raw huly-mcp tool calls. Use for Huly task triage, issue updates, project lookup, and agent-safe Huly automation.
+---
+
+# Huly CLI
+
+Use `npx -y @starhui/huly-cli@latest` to work with Huly through `@firfi/huly-mcp`.
+
+For local development inside this repository, `huly` is also acceptable after `pnpm build && pnpm link --global`.
+
+## Quick Checks
+
+1. Confirm the CLI is available:
+   ```bash
+   npx -y @starhui/huly-cli@latest --version
+   ```
+2. Prefer explicit config:
+   ```bash
+   npx -y @starhui/huly-cli@latest --config .env context
+   ```
+3. If project is omitted for issue commands, set `HULY_DEFAULT_PROJECT` or pass `--project`.
+
+Never print real tokens, passwords, or full `.env` contents. `npx -y @starhui/huly-cli@latest context` is safe because it returns sanitized config.
+
+## Common Commands
+
+List projects:
+```bash
+npx -y @starhui/huly-cli@latest --config .env project list --json
+```
+
+Discover statuses before creating or updating issues:
+```bash
+npx -y @starhui/huly-cli@latest --config .env project statuses HULY --json
+```
+
+List issues:
+```bash
+npx -y @starhui/huly-cli@latest --config .env issue list --project HULY --status-category active --limit 20 --json
+```
+
+Get an issue:
+```bash
+npx -y @starhui/huly-cli@latest --config .env issue get HULY-123 --project HULY --json
+```
+
+Create an issue:
+```bash
+npx -y @starhui/huly-cli@latest --config .env issue create --project HULY --title "Short imperative title" --description "Markdown body"
+```
+
+Update an issue:
+```bash
+npx -y @starhui/huly-cli@latest --config .env issue update HULY-123 --project HULY --status Done
+```
+
+Search:
+```bash
+npx -y @starhui/huly-cli@latest --config .env search "query text" --limit 10 --json
+```
+
+## Raw Tool Access
+
+Use raw calls when the first-class CLI does not expose an upstream MCP tool:
+
+```bash
+npx -y @starhui/huly-cli@latest --config .env tools --filter document
+npx -y @starhui/huly-cli@latest --config .env call get_issue --field project=HULY --field identifier=HULY-123 --json
+npx -y @starhui/huly-cli@latest --config .env call list_projects --data '{"limit":10}' --json
+```
+
+`--field key=value` coerces `true`, `false`, `null`, and numbers. Use `--data` or `--file` for nested JSON.
+
+## Safety
+
+- Use `--json` for agent parsing.
+- Read before write: inspect the project/status/issue before mutating it unless the user gave exact values.
+- Destructive commands require confirmation; only pass `--yes` when the user explicitly requested deletion.
+- Prefer status names from `project statuses`; do not invent workflow statuses.
+- If a command fails due to auth/config, report the missing sanitized fields from `npx -y @starhui/huly-cli@latest --config .env context`; do not expose secrets.
+
+## Useful Mapping
+
+- Projects: `project list`, `project get`, `project statuses`, `project create`, `project update`, `project delete`.
+- Issues: `issue list`, `issue get`, `issue create`, `issue update`, `issue delete`, `issue label`, `issue unlabel`, `issue move`.
+- Global search: `search`.
+- All upstream MCP tools: `tools` and `call`.

package/skills/huly-cli/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Huly CLI"
+  short_description: "Operate Huly projects and issues via npx"
+  default_prompt: "Use $huly-cli with npx to inspect and update Huly issues safely from the terminal."
+policy:
+  allow_implicit_invocation: true