@ysicing/plane-cli 0.1.0

package/src/commands/me.js

@@ -0,0 +1,23 @@
+import { UserClient } from "../api/user-client.js";
+import { resolveRuntimeConfig } from "../core/config.js";
+import { CliError } from "../core/errors.js";
+import { PlaneClient } from "../core/http.js";
+import { printData } from "../core/output.js";
+
+export async function runMeCommand(args, context) {
+  if (args.includes("--help") || args.includes("help")) {
+    console.log("Usage:\n  plane me");
+    return;
+  }
+
+  if (args.length > 0) {
+    throw new CliError("`plane me` does not accept extra arguments.");
+  }
+
+  const config = await resolveRuntimeConfig();
+  const client = new PlaneClient(config);
+  const userClient = new UserClient(client);
+  const user = await userClient.me();
+
+  printData(user, context.output);
+}

package/src/commands/project.js

@@ -0,0 +1,135 @@
+import { ProjectClient } from "../api/project-client.js";
+import { resolveRuntimeConfig } from "../core/config.js";
+import { CliError } from "../core/errors.js";
+import { PlaneClient } from "../core/http.js";
+import { ensureValue, parseCommandArgs, pickDefined } from "../core/options.js";
+import { printData, printTable } from "../core/output.js";
+
+function createProjectRender(data) {
+  const rows = Array.isArray(data) ? data : data.results || [];
+  printTable(rows, [
+    { label: "ID", get: (row) => row.id },
+    { label: "Identifier", get: (row) => row.identifier },
+    { label: "Name", get: (row) => row.name },
+    { label: "Lead", get: (row) => row.project_lead || "" },
+    { label: "Archived", get: (row) => (row.archived_at ? "yes" : "no") },
+  ]);
+}
+
+export function buildProjectPayload(values) {
+  return pickDefined({
+    name: values.name,
+    identifier: values.identifier ? values.identifier.toUpperCase() : undefined,
+    description: values.description,
+    project_lead: values["project-lead"],
+    default_assignee: values["default-assignee"],
+  });
+}
+
+function printHelp() {
+  console.log(`Usage:
+  plane project ls [--limit <n>] [--cursor <cursor>] [--order-by <field>]
+  plane project get <project-id>
+  plane project create --name <name> --identifier <identifier> [--description <text>] [--project-lead <user-id>] [--default-assignee <user-id>]
+  plane project update <project-id> [--name <name>] [--identifier <identifier>] [--description <text>] [--project-lead <user-id>] [--default-assignee <user-id>]
+`);
+}
+
+export async function runProjectCommand(args, context) {
+  const [subcommand, ...rest] = args;
+
+  if (!subcommand || subcommand === "--help" || subcommand === "help") {
+    printHelp();
+    return;
+  }
+
+  const config = await resolveRuntimeConfig();
+  const projectClient = new ProjectClient(new PlaneClient(config));
+
+  if (subcommand === "ls") {
+    const parsed = parseCommandArgs(
+      rest,
+      {
+        limit: { type: "string" },
+        cursor: { type: "string" },
+        "order-by": { type: "string" },
+        fields: { type: "string" },
+        expand: { type: "string" },
+      },
+      false
+    );
+
+    const result = await projectClient.list(
+      pickDefined({
+        per_page: parsed.values.limit,
+        cursor: parsed.values.cursor,
+        order_by: parsed.values["order-by"],
+        fields: parsed.values.fields,
+        expand: parsed.values.expand,
+      })
+    );
+
+    printData(result, {
+      ...context.output,
+      render: createProjectRender,
+    });
+    return;
+  }
+
+  if (subcommand === "get") {
+    const [projectId] = rest;
+    ensureValue(projectId, "Project ID is required.");
+    const result = await projectClient.get(projectId);
+    printData(result, context.output);
+    return;
+  }
+
+  if (subcommand === "create") {
+    const parsed = parseCommandArgs(
+      rest,
+      {
+        name: { type: "string" },
+        identifier: { type: "string" },
+        description: { type: "string" },
+        "project-lead": { type: "string" },
+        "default-assignee": { type: "string" },
+      },
+      false
+    );
+
+    ensureValue(parsed.values.name, "Project name is required.");
+    ensureValue(parsed.values.identifier, "Project identifier is required.");
+
+    const result = await projectClient.create(buildProjectPayload(parsed.values));
+    printData(result, context.output);
+    return;
+  }
+
+  if (subcommand === "update") {
+    const [projectId, ...optionArgs] = rest;
+    ensureValue(projectId, "Project ID is required.");
+
+    const parsed = parseCommandArgs(
+      optionArgs,
+      {
+        name: { type: "string" },
+        identifier: { type: "string" },
+        description: { type: "string" },
+        "project-lead": { type: "string" },
+        "default-assignee": { type: "string" },
+      },
+      false
+    );
+
+    const payload = buildProjectPayload(parsed.values);
+    if (Object.keys(payload).length === 0) {
+      throw new CliError("At least one update field is required.");
+    }
+
+    const result = await projectClient.update(projectId, payload);
+    printData(result, context.output);
+    return;
+  }
+
+  throw new CliError(`Unknown project subcommand: ${subcommand}`);
+}

package/src/commands/workspace.js

@@ -0,0 +1,102 @@
+import { loadConfig, saveConfig } from "../core/config.js";
+import { CliError } from "../core/errors.js";
+import { parseCommandArgs } from "../core/options.js";
+import { printData, printTable } from "../core/output.js";
+
+function printHelp() {
+  console.log(`Usage:
+  plane workspace ls
+  plane workspace current
+  plane workspace use <slug> [--force]
+`);
+}
+
+function workspaceRows(config) {
+  const known = config.knownWorkspaces || [];
+  return known.map((slug) => ({
+    slug,
+    current: config.workspace === slug,
+  }));
+}
+
+export async function runWorkspaceCommand(args, context) {
+  const [subcommand = "ls", ...rest] = args;
+
+  if (subcommand === "--help" || subcommand === "help") {
+    printHelp();
+    return;
+  }
+
+  if (rest.includes("--help") || rest.includes("help")) {
+    printHelp();
+    return;
+  }
+
+  const config = await loadConfig();
+
+  if (subcommand === "ls") {
+    const rows = workspaceRows(config);
+    printData(rows, {
+      ...context.output,
+      render(data) {
+        printTable(data, [
+          { label: "Current", get: (row) => (row.current ? "*" : "") },
+          { label: "Workspace", get: (row) => row.slug },
+        ]);
+      },
+    });
+    return;
+  }
+
+  if (subcommand === "current") {
+    printData(
+      {
+        workspace: config.workspace || "",
+        knownWorkspaces: config.knownWorkspaces || [],
+      },
+      context.output
+    );
+    return;
+  }
+
+  if (subcommand === "use") {
+    const parsed = parseCommandArgs(
+      rest,
+      {
+        force: { type: "boolean" },
+      }
+    );
+
+    const [slug] = parsed.positionals;
+    if (!slug) {
+      throw new CliError("Workspace slug is required.");
+    }
+
+    const known = config.knownWorkspaces || [];
+    if (!parsed.values.force && known.length > 0 && !known.includes(slug)) {
+      throw new CliError(`Unknown workspace: ${slug}`, {
+        details: {
+          knownWorkspaces: known,
+          hint: "Run `plane auth login` again or use --force if you know the slug is valid.",
+        },
+      });
+    }
+
+    const nextKnown = known.includes(slug) ? known : [...known, slug];
+    const result = await saveConfig({
+      workspace: slug,
+      knownWorkspaces: nextKnown,
+    });
+
+    printData(
+      {
+        workspace: result.config.workspace,
+        knownWorkspaces: result.config.knownWorkspaces || [],
+      },
+      context.output
+    );
+    return;
+  }
+
+  throw new CliError(`Unknown workspace subcommand: ${subcommand}`);
+}

package/src/core/config.js

@@ -0,0 +1,103 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const CONFIG_KEYS = ["baseUrl", "apiKey", "workspace", "knownWorkspaces"];
+
+function normalizeBaseUrl(value) {
+  if (!value) return value;
+  return value.replace(/\/+$/, "").replace(/\/api\/v1$/, "").replace(/\/api$/, "");
+}
+
+function normalizeValue(key, value) {
+  if (key === "knownWorkspaces") {
+    if (!Array.isArray(value)) return undefined;
+    return value
+      .map((item) => (typeof item === "string" ? item.trim() : ""))
+      .filter(Boolean);
+  }
+
+  if (typeof value !== "string") return value;
+  const trimmed = value.trim();
+  if (trimmed === "") return undefined;
+  if (key === "baseUrl") return normalizeBaseUrl(trimmed);
+  return trimmed;
+}
+
+function sanitizeConfig(input) {
+  const next = {};
+
+  for (const key of CONFIG_KEYS) {
+    const normalized = normalizeValue(key, input[key]);
+    if (normalized !== undefined) {
+      next[key] = normalized;
+    }
+  }
+
+  return next;
+}
+
+export function resolveConfigPath() {
+  if (process.env.PLANE_CLI_CONFIG_PATH) {
+    return process.env.PLANE_CLI_CONFIG_PATH;
+  }
+
+  const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(configHome, "plane-cli", "config.json");
+}
+
+export async function loadConfig() {
+  const configPath = resolveConfigPath();
+
+  try {
+    const raw = await readFile(configPath, "utf8");
+    return sanitizeConfig(JSON.parse(raw));
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return {};
+    }
+    throw error;
+  }
+}
+
+export async function saveConfig(partial) {
+  const configPath = resolveConfigPath();
+  const current = await loadConfig();
+  const merged = { ...current };
+
+  for (const [key, value] of Object.entries(partial)) {
+    if (value === null) {
+      delete merged[key];
+      continue;
+    }
+    merged[key] = value;
+  }
+
+  const next = sanitizeConfig(merged);
+
+  await mkdir(dirname(configPath), { recursive: true });
+  await writeFile(configPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+
+  return { path: configPath, config: next };
+}
+
+export async function resolveRuntimeConfig(overrides = {}) {
+  const fileConfig = await loadConfig();
+  const envConfig = sanitizeConfig({
+    baseUrl: process.env.PLANE_BASE_URL,
+    apiKey: process.env.PLANE_API_KEY,
+    workspace: process.env.PLANE_WORKSPACE,
+  });
+
+  return sanitizeConfig({
+    ...fileConfig,
+    ...envConfig,
+    ...overrides,
+  });
+}
+
+export function maskApiKey(value) {
+  if (!value) return "";
+  if (value.length <= 8) return "*".repeat(value.length);
+  return `${value.slice(0, 4)}...${value.slice(-4)}`;
+}

package/src/core/errors.js

@@ -0,0 +1,8 @@
+export class CliError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = options.exitCode ?? 1;
+    this.details = options.details;
+  }
+}

package/src/core/http.js

@@ -0,0 +1,109 @@
+import { CliError } from "./errors.js";
+
+function normalizeBaseUrl(baseUrl) {
+  return baseUrl.replace(/\/+$/, "").replace(/\/api\/v1$/, "").replace(/\/api$/, "");
+}
+
+export function buildApiUrl(baseUrl, path, query = {}) {
+  const root = normalizeBaseUrl(baseUrl);
+  const url = new URL(`/api/v1${path}`, `${root}/`);
+
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null || value === "") continue;
+
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        url.searchParams.append(key, String(item));
+      }
+      continue;
+    }
+
+    url.searchParams.set(key, String(value));
+  }
+
+  return url;
+}
+
+export class PlaneClient {
+  constructor(config) {
+    this.baseUrl = config.baseUrl;
+    this.apiKey = config.apiKey;
+    this.workspace = config.workspace;
+    this.knownWorkspaces = config.knownWorkspaces || [];
+  }
+
+  workspacePath(resource = "") {
+    if (!this.workspace) {
+      const hasKnownWorkspaces = this.knownWorkspaces.length > 0;
+      throw new CliError(
+        hasKnownWorkspaces
+          ? "Workspace is not selected. Use `plane workspace current` to inspect state and `plane workspace use <slug>` to choose one."
+          : "Workspace is required. Use `plane auth login` or `plane config set --workspace <slug>` first.",
+        hasKnownWorkspaces
+          ? {
+              details: {
+                knownWorkspaces: this.knownWorkspaces,
+                hint: "Run `plane workspace ls` and then `plane workspace use <slug>`.",
+              },
+            }
+          : undefined
+      );
+    }
+
+    const suffix = resource.startsWith("/") ? resource : `/${resource}`;
+    return `/workspaces/${this.workspace}${resource ? suffix : ""}`;
+  }
+
+  async request(method, path, options = {}) {
+    if (!this.baseUrl) {
+      throw new CliError("Base URL is required. Use `plane config set --base-url <url>` first.");
+    }
+
+    if (!this.apiKey) {
+      throw new CliError("API key is required. Use `plane config set --api-key <key>` first.");
+    }
+
+    const url = buildApiUrl(this.baseUrl, path, options.query);
+    const headers = {
+      Accept: "application/json",
+      "X-Api-Key": this.apiKey,
+    };
+
+    const requestInit = {
+      method,
+      headers,
+    };
+
+    if (options.body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      requestInit.body = JSON.stringify(options.body);
+    }
+
+    const response = await fetch(url, requestInit);
+    const contentType = response.headers.get("content-type") || "";
+    const payload = contentType.includes("application/json")
+      ? await response.json()
+      : await response.text();
+
+    if (!response.ok) {
+      throw new CliError(`Plane API request failed: ${response.status} ${response.statusText}`, {
+        exitCode: 1,
+        details: payload,
+      });
+    }
+
+    return payload;
+  }
+
+  get(path, query) {
+    return this.request("GET", path, { query });
+  }
+
+  post(path, body) {
+    return this.request("POST", path, { body });
+  }
+
+  patch(path, body) {
+    return this.request("PATCH", path, { body });
+  }
+}

package/src/core/options.js

@@ -0,0 +1,33 @@
+import { parseArgs } from "node:util";
+import { CliError } from "./errors.js";
+
+export function parseCommandArgs(args, options, allowPositionals = true) {
+  try {
+    return parseArgs({
+      args,
+      options,
+      allowPositionals,
+      strict: true,
+    });
+  } catch (error) {
+    throw new CliError(error.message);
+  }
+}
+
+export function ensureValue(value, message) {
+  if (!value) {
+    throw new CliError(message);
+  }
+}
+
+export function splitCsv(value) {
+  if (!value) return undefined;
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function pickDefined(object) {
+  return Object.fromEntries(Object.entries(object).filter(([, value]) => value !== undefined));
+}

package/src/core/output.js

@@ -0,0 +1,51 @@
+function stringifyValue(value) {
+  if (value === undefined || value === null) return "";
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}
+
+export function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export function printTable(rows, columns) {
+  if (!rows.length) {
+    console.log("(empty)");
+    return;
+  }
+
+  const widths = columns.map((column) => {
+    const headerWidth = column.label.length;
+    const valueWidth = Math.max(...rows.map((row) => stringifyValue(column.get(row)).length));
+    return Math.max(headerWidth, valueWidth);
+  });
+
+  const header = columns
+    .map((column, index) => column.label.padEnd(widths[index], " "))
+    .join("  ");
+  const separator = widths.map((width) => "-".repeat(width)).join("  ");
+
+  console.log(header);
+  console.log(separator);
+
+  for (const row of rows) {
+    const line = columns
+      .map((column, index) => stringifyValue(column.get(row)).padEnd(widths[index], " "))
+      .join("  ");
+    console.log(line);
+  }
+}
+
+export function printData(data, options = {}) {
+  if (options.json) {
+    printJson(data);
+    return;
+  }
+
+  if (typeof options.render === "function") {
+    options.render(data);
+    return;
+  }
+
+  printJson(data);
+}