@ysicing/plane-cli 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# plane-cli
+
+基于 Plane 外部 API（`/api/v1`）的轻量命令行工具，使用 Node.js 原生能力实现，不依赖第三方包。
+
+## 安装
+
+```bash
+npm install -g @ysicing/plane-cli
+```
+
+或直接用 `npx`：
+
+```bash
+npx @ysicing/plane-cli --help
+```
+
+## 约束
+
+- 鉴权方式：`X-Api-Key`
+- 默认面向 `project` 与 `work-item`
+- 暂不提供危险删除命令
+
+## 要求
+
+- Node.js 22+
+
+## 初始化
+
+```bash
+node ./src/cli.js config set \
+  --base-url https://plane.example.com \
+  --api-key your-api-key \
+  --workspace your-workspace-slug
+```
+
+也支持环境变量覆盖：
+
+```bash
+export PLANE_BASE_URL=https://plane.example.com
+export PLANE_API_KEY=your-api-key
+export PLANE_WORKSPACE=your-workspace-slug
+```
+
+## 登录并自动生成 API Token
+
+普通账号密码登录：
+
+```bash
+node ./src/cli.js auth login \
+  --base-url https://plane.example.com \
+  --username you@example.com \
+  --password 'your-password'
+```
+
+LDAP 登录：
+
+```bash
+node ./src/cli.js auth login \
+  --base-url https://plane.example.com \
+  --ldap \
+  --username your-ldap-account \
+  --password 'your-password'
+```
+
+如果不想把密码放进命令行：
+
+```bash
+printf '%s' 'your-password' | node ./src/cli.js auth login \
+  --base-url https://plane.example.com \
+  --ldap \
+  --username your-ldap-account \
+  --password-stdin
+```
+
+如果账号下有多个 workspace，且没有显式传 `--workspace`，CLI 会保存登录态生成的 API token，但不会自动选中 workspace。此时请先查看并选择：
+
+```bash
+node ./src/cli.js workspace ls
+node ./src/cli.js workspace current
+node ./src/cli.js workspace use <slug>
+```
+
+## 示例
+
+```bash
+node ./src/cli.js me
+node ./src/cli.js project ls
+node ./src/cli.js project get <project-id>
+node ./src/cli.js project create --name Demo --identifier DEMO
+node ./src/cli.js issue ls --project <project-id>
+node ./src/cli.js issue get --project <project-id> <issue-id>
+node ./src/cli.js issue create --project <project-id> --name "First work item"
+node ./src/cli.js issue update --project <project-id> <issue-id> --priority high
+```
+
+`work-item` 是 `issue` 的别名：
+
+```bash
+node ./src/cli.js work-item ls --project <project-id>
+```
+
+## 发布
+
+当前包名使用 `@ysicing/plane-cli`，因为 `plane-cli` 已被 npm 占用。
+
+发布前检查：
+
+```bash
+npm test
+npm run pack:check
+```
+
+发布：
+
+```bash
+npm publish
+```
+
+如果本机还没登录 npm：
+
+```bash
+npm login
+```

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ysicing/plane-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Node.js CLI for managing Plane via the external API",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/ysicing/plane-cli.git"
+  },
+  "homepage": "https://github.com/ysicing/plane-cli#readme",
+  "bugs": {
+    "url": "https://github.com/ysicing/plane-cli/issues"
+  },
+  "keywords": [
+    "plane",
+    "cli",
+    "project-management",
+    "ldap",
+    "api"
+  ],
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "bin": {
+    "plane": "./src/cli.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "start": "node ./src/cli.js",
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm test && npm run pack:check"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/src/api/issue-client.js

@@ -0,0 +1,21 @@
+export class IssueClient {
+  constructor(client) {
+    this.client = client;
+  }
+
+  list(projectId, query = {}) {
+    return this.client.get(this.client.workspacePath(`/projects/${projectId}/work-items/`), query);
+  }
+
+  get(projectId, issueId) {
+    return this.client.get(this.client.workspacePath(`/projects/${projectId}/work-items/${issueId}/`));
+  }
+
+  create(projectId, body) {
+    return this.client.post(this.client.workspacePath(`/projects/${projectId}/work-items/`), body);
+  }
+
+  update(projectId, issueId, body) {
+    return this.client.patch(this.client.workspacePath(`/projects/${projectId}/work-items/${issueId}/`), body);
+  }
+}

package/src/api/project-client.js

@@ -0,0 +1,21 @@
+export class ProjectClient {
+  constructor(client) {
+    this.client = client;
+  }
+
+  list(query = {}) {
+    return this.client.get(this.client.workspacePath("/projects/"), query);
+  }
+
+  get(projectId) {
+    return this.client.get(this.client.workspacePath(`/projects/${projectId}/`));
+  }
+
+  create(body) {
+    return this.client.post(this.client.workspacePath("/projects/"), body);
+  }
+
+  update(projectId, body) {
+    return this.client.patch(this.client.workspacePath(`/projects/${projectId}/`), body);
+  }
+}

package/src/api/user-client.js

@@ -0,0 +1,9 @@
+export class UserClient {
+  constructor(client) {
+    this.client = client;
+  }
+
+  me() {
+    return this.client.get("/users/me/");
+  }
+}

package/src/cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import { runAuthCommand } from "./commands/auth.js";
+import { runConfigCommand } from "./commands/config.js";
+import { runIssueCommand } from "./commands/issue.js";
+import { runMeCommand } from "./commands/me.js";
+import { runProjectCommand } from "./commands/project.js";
+import { runWorkspaceCommand } from "./commands/workspace.js";
+import { CliError } from "./core/errors.js";
+
+function extractGlobalOptions(argv) {
+  const args = [];
+  const options = {
+    json: false,
+  };
+
+  for (const arg of argv) {
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+    args.push(arg);
+  }
+
+  return { args, options };
+}
+
+function printHelp() {
+  console.log(`plane-cli
+
+Usage:
+  plane <command> [options]
+
+Commands:
+  auth        Sign in and bootstrap API credentials
+  config      Manage local CLI config
+  me          Show current authenticated user
+  project     Manage projects
+  issue       Manage work items through issue commands
+  work-item   Alias of issue
+  workspace   Manage selected workspace
+
+Global options:
+  --json      Print raw JSON
+  --help      Show help
+`);
+}
+
+async function main() {
+  const { args, options } = extractGlobalOptions(process.argv.slice(2));
+  const [command, ...rest] = args;
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  const context = { output: options };
+
+  switch (command) {
+    case "auth":
+      await runAuthCommand(rest, context);
+      return;
+    case "config":
+      await runConfigCommand(rest, context);
+      return;
+    case "me":
+      await runMeCommand(rest, context);
+      return;
+    case "project":
+      await runProjectCommand(rest, context);
+      return;
+    case "workspace":
+      await runWorkspaceCommand(rest, context);
+      return;
+    case "issue":
+    case "work-item":
+      await runIssueCommand(rest, context);
+      return;
+    default:
+      throw new CliError(`Unknown command: ${command}`);
+  }
+}
+
+main().catch((error) => {
+  if (error instanceof CliError) {
+    console.error(`Error: ${error.message}`);
+    if (error.details) {
+      console.error(JSON.stringify(error.details, null, 2));
+    }
+    process.exit(error.exitCode);
+  }
+
+  console.error(error);
+  process.exit(1);
+});

package/src/commands/auth.js

@@ -0,0 +1,136 @@
+import { readFile } from "node:fs/promises";
+
+import { loadConfig, maskApiKey, saveConfig } from "../core/config.js";
+import { CliError } from "../core/errors.js";
+import { ensureValue, parseCommandArgs } from "../core/options.js";
+import { printData } from "../core/output.js";
+import { PlaneSessionClient } from "../core/session.js";
+
+function printHelp() {
+  console.log(`Usage:
+  plane auth login --base-url <plane-url> [--ldap] (--username <value> | --email <value>) [--password <value> | --password-stdin] [--workspace <slug>] [--token-label <label>]
+`);
+}
+
+function defaultTokenLabel() {
+  return `plane-cli-${new Date().toISOString()}`;
+}
+
+async function readPasswordFromStdin() {
+  const content = await readFile(0, "utf8");
+  return content.trim();
+}
+
+function resolveWorkspaceToSave({ explicitWorkspace, existingWorkspace, userWorkspaces }) {
+  const known = Array.isArray(userWorkspaces) ? userWorkspaces.map((item) => item.slug) : [];
+
+  if (explicitWorkspace) {
+    if (!known.includes(explicitWorkspace)) {
+      throw new CliError(`Workspace not found for this account: ${explicitWorkspace}`, {
+        details: {
+          knownWorkspaces: known,
+        },
+      });
+    }
+    return explicitWorkspace;
+  }
+
+  if (known.length === 1) {
+    return known[0];
+  }
+
+  if (known.length > 1) {
+    return null;
+  }
+
+  return existingWorkspace || null;
+}
+
+export async function runAuthCommand(args, context) {
+  const [subcommand, ...rest] = args;
+
+  if (!subcommand || subcommand === "--help" || subcommand === "help") {
+    printHelp();
+    return;
+  }
+
+  if (subcommand !== "login") {
+    throw new CliError(`Unknown auth subcommand: ${subcommand}`);
+  }
+
+  if (rest.includes("--help") || rest.includes("help")) {
+    printHelp();
+    return;
+  }
+
+  const parsed = parseCommandArgs(
+    rest,
+    {
+      "base-url": { type: "string" },
+      ldap: { type: "boolean" },
+      username: { type: "string" },
+      email: { type: "string" },
+      password: { type: "string" },
+      "password-stdin": { type: "boolean" },
+      workspace: { type: "string" },
+      "token-label": { type: "string" },
+    },
+    false
+  );
+
+  const existingConfig = await loadConfig();
+  const baseUrl = parsed.values["base-url"] || existingConfig.baseUrl;
+  ensureValue(baseUrl, "Base URL is required. Pass --base-url or set it with `plane config set --base-url ...`.");
+
+  const username = parsed.values.username || parsed.values.email;
+  ensureValue(username, "Username is required. Pass --username or --email.");
+
+  let password = parsed.values.password;
+  if (!password && parsed.values["password-stdin"]) {
+    password = await readPasswordFromStdin();
+  }
+  ensureValue(password, "Password is required. Pass --password or --password-stdin.");
+
+  const sessionClient = new PlaneSessionClient(baseUrl);
+  await sessionClient.login({
+    username,
+    password,
+    ldap: Boolean(parsed.values.ldap),
+  });
+
+  const tokenLabel = parsed.values["token-label"] || defaultTokenLabel();
+  const token = await sessionClient.createApiToken({
+    label: tokenLabel,
+    description: "Created by plane-cli auth login",
+  });
+  const workspaces = await sessionClient.listUserWorkspaces();
+  const knownWorkspaces = Array.isArray(workspaces) ? workspaces.map((item) => item.slug) : [];
+
+  const workspace = resolveWorkspaceToSave({
+    explicitWorkspace: parsed.values.workspace,
+    existingWorkspace: existingConfig.workspace,
+    userWorkspaces: workspaces,
+  });
+
+  const saved = await saveConfig({
+    baseUrl,
+    apiKey: token.token,
+    workspace,
+    knownWorkspaces,
+  });
+
+  printData(
+    {
+      path: saved.path,
+      baseUrl: saved.config.baseUrl,
+      workspace: saved.config.workspace || "",
+      apiKey: maskApiKey(saved.config.apiKey),
+      loginMode: parsed.values.ldap ? "ldap" : "password",
+      tokenId: token.id,
+      tokenLabel: token.label,
+      detectedWorkspaces: knownWorkspaces,
+      workspaceSelectionRequired: !saved.config.workspace && knownWorkspaces.length > 1,
+    },
+    context.output
+  );
+}

package/src/commands/config.js

@@ -0,0 +1,84 @@
+import { loadConfig, maskApiKey, resolveConfigPath, saveConfig } from "../core/config.js";
+import { CliError } from "../core/errors.js";
+import { parseCommandArgs } from "../core/options.js";
+import { printData } from "../core/output.js";
+
+function configSnapshot(config, path) {
+  return {
+    path,
+    baseUrl: config.baseUrl || "",
+    apiKey: maskApiKey(config.apiKey),
+    workspace: config.workspace || "",
+    knownWorkspaces: config.knownWorkspaces || [],
+  };
+}
+
+function printHelp() {
+  console.log(`Usage:
+  plane config list
+  plane config get [baseUrl|apiKey|workspace|knownWorkspaces]
+  plane config set [--base-url <url>] [--api-key <key>] [--workspace <slug>]
+`);
+}
+
+export async function runConfigCommand(args, context) {
+  const [subcommand = "list", ...rest] = args;
+  const path = resolveConfigPath();
+
+  if (subcommand === "--help" || subcommand === "help") {
+    printHelp();
+    return;
+  }
+
+  if (subcommand === "list") {
+    const config = await loadConfig();
+    printData(configSnapshot(config, path), context.output);
+    return;
+  }
+
+  if (subcommand === "get") {
+    const [key] = rest;
+    const config = await loadConfig();
+    const snapshot = configSnapshot(config, path);
+
+    if (!key) {
+      printData(snapshot, context.output);
+      return;
+    }
+
+    if (!(key in snapshot)) {
+      throw new CliError(`Unknown config key: ${key}`);
+    }
+
+    printData({ [key]: snapshot[key] }, context.output);
+    return;
+  }
+
+  if (subcommand === "set") {
+    const parsed = parseCommandArgs(
+      rest,
+      {
+        "base-url": { type: "string" },
+        "api-key": { type: "string" },
+        workspace: { type: "string" },
+      },
+      false
+    );
+
+    const update = {
+      baseUrl: parsed.values["base-url"],
+      apiKey: parsed.values["api-key"],
+      workspace: parsed.values.workspace,
+    };
+
+    if (!update.baseUrl && !update.apiKey && !update.workspace) {
+      throw new CliError("Nothing to update. Pass at least one of --base-url, --api-key, or --workspace.");
+    }
+
+    const result = await saveConfig(update);
+    printData(configSnapshot(result.config, result.path), context.output);
+    return;
+  }
+
+  throw new CliError(`Unknown config subcommand: ${subcommand}`);
+}

package/src/commands/issue.js

@@ -0,0 +1,171 @@
+import { IssueClient } from "../api/issue-client.js";
+import { resolveRuntimeConfig } from "../core/config.js";
+import { CliError } from "../core/errors.js";
+import { PlaneClient } from "../core/http.js";
+import { ensureValue, parseCommandArgs, pickDefined, splitCsv } from "../core/options.js";
+import { printData, printTable } from "../core/output.js";
+
+function renderIssueList(data) {
+  const rows = Array.isArray(data) ? data : data.results || [];
+  printTable(rows, [
+    { label: "ID", get: (row) => row.id },
+    { label: "Seq", get: (row) => row.sequence_id || "" },
+    { label: "Name", get: (row) => row.name },
+    { label: "Priority", get: (row) => row.priority || "" },
+    { label: "State", get: (row) => row.state || row.state_id || "" },
+  ]);
+}
+
+export function buildIssuePayload(values) {
+  return pickDefined({
+    name: values.name,
+    description_html: values["description-html"],
+    state: values.state,
+    priority: values.priority,
+    start_date: values["start-date"],
+    target_date: values["target-date"],
+    parent: values.parent,
+    type_id: values["type-id"],
+    assignees: splitCsv(values.assignees),
+    labels: splitCsv(values.labels),
+  });
+}
+
+function printHelp() {
+  console.log(`Usage:
+  plane issue ls --project <project-id> [--limit <n>] [--cursor <cursor>] [--order-by <field>] [--state <state-id>] [--priority <value>] [--assignees <id1,id2>] [--expand <field1,field2>]
+  plane issue get --project <project-id> <issue-id>
+  plane issue create --project <project-id> --name <name> [--description-html <html>] [--state <state-id>] [--priority <value>] [--assignees <id1,id2>] [--labels <id1,id2>]
+  plane issue update --project <project-id> <issue-id> [--name <name>] [--description-html <html>] [--state <state-id>] [--priority <value>] [--assignees <id1,id2>] [--labels <id1,id2>]
+`);
+}
+
+export async function runIssueCommand(args, context) {
+  const [subcommand, ...rest] = args;
+
+  if (!subcommand || subcommand === "--help" || subcommand === "help") {
+    printHelp();
+    return;
+  }
+
+  const config = await resolveRuntimeConfig();
+  const issueClient = new IssueClient(new PlaneClient(config));
+
+  if (subcommand === "ls") {
+    const parsed = parseCommandArgs(
+      rest,
+      {
+        project: { type: "string" },
+        limit: { type: "string" },
+        cursor: { type: "string" },
+        "order-by": { type: "string" },
+        state: { type: "string" },
+        priority: { type: "string" },
+        assignees: { type: "string" },
+        labels: { type: "string" },
+        expand: { type: "string" },
+        fields: { type: "string" },
+      },
+      false
+    );
+
+    ensureValue(parsed.values.project, "Project ID is required.");
+
+    const result = await issueClient.list(
+      parsed.values.project,
+      pickDefined({
+        per_page: parsed.values.limit,
+        cursor: parsed.values.cursor,
+        order_by: parsed.values["order-by"],
+        state: parsed.values.state,
+        priority: parsed.values.priority,
+        assignees: parsed.values.assignees,
+        labels: parsed.values.labels,
+        expand: parsed.values.expand,
+        fields: parsed.values.fields,
+      })
+    );
+
+    printData(result, {
+      ...context.output,
+      render: renderIssueList,
+    });
+    return;
+  }
+
+  if (subcommand === "get") {
+    const parsed = parseCommandArgs(
+      rest,
+      {
+        project: { type: "string" },
+      }
+    );
+
+    ensureValue(parsed.values.project, "Project ID is required.");
+    ensureValue(parsed.positionals[0], "Issue ID is required.");
+
+    const result = await issueClient.get(parsed.values.project, parsed.positionals[0]);
+    printData(result, context.output);
+    return;
+  }
+
+  if (subcommand === "create") {
+    const parsed = parseCommandArgs(
+      rest,
+      {
+        project: { type: "string" },
+        name: { type: "string" },
+        "description-html": { type: "string" },
+        state: { type: "string" },
+        priority: { type: "string" },
+        assignees: { type: "string" },
+        labels: { type: "string" },
+        "start-date": { type: "string" },
+        "target-date": { type: "string" },
+        parent: { type: "string" },
+        "type-id": { type: "string" },
+      },
+      false
+    );
+
+    ensureValue(parsed.values.project, "Project ID is required.");
+    ensureValue(parsed.values.name, "Issue name is required.");
+
+    const result = await issueClient.create(parsed.values.project, buildIssuePayload(parsed.values));
+    printData(result, context.output);
+    return;
+  }
+
+  if (subcommand === "update") {
+    const parsed = parseCommandArgs(
+      rest,
+      {
+        project: { type: "string" },
+        name: { type: "string" },
+        "description-html": { type: "string" },
+        state: { type: "string" },
+        priority: { type: "string" },
+        assignees: { type: "string" },
+        labels: { type: "string" },
+        "start-date": { type: "string" },
+        "target-date": { type: "string" },
+        parent: { type: "string" },
+        "type-id": { type: "string" },
+      }
+    );
+
+    ensureValue(parsed.values.project, "Project ID is required.");
+    ensureValue(parsed.positionals[0], "Issue ID is required.");
+
+    const payload = buildIssuePayload(parsed.values);
+    if (Object.keys(payload).length === 0) {
+      throw new CliError("At least one update field is required.");
+    }
+
+    const result = await issueClient.update(parsed.values.project, parsed.positionals[0], payload);
+    printData(result, context.output);
+    return;
+  }
+
+  throw new CliError(`Unknown issue subcommand: ${subcommand}`);
+}