@aaronshaf/plane 0.1.3 → 0.1.5

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "CLI for the Plane project management API",
   "keywords": [
     "plane",

package/scripts/check-coverage.ts

@@ -3,8 +3,8 @@
 import { execSync } from "child_process"
 
 const THRESHOLDS = {
-  lines: 98,
-  functions: 98,
+  lines: 95,
+  functions: 95,
 }
 
 console.log("Running tests with coverage...\n")

package/src/api.ts

@@ -1,81 +1,89 @@
-import { Effect, Schema } from "effect"
-import * as fs from "node:fs"
-import * as path from "node:path"
-import * as os from "node:os"
+import { Effect, Schema } from "effect";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
 
-const CONFIG_FILE = path.join(os.homedir(), ".config", "plane", "config.json")
+const CONFIG_FILE = path.join(os.homedir(), ".config", "plane", "config.json");
 
-function readConfigFile(): Partial<{ token: string; host: string; workspace: string }> {
-  try {
-    return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"))
-  } catch {
-    return {}
-  }
+function readConfigFile(): Partial<{
+	token: string;
+	host: string;
+	workspace: string;
+}> {
+	try {
+		return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+	} catch {
+		return {};
+	}
 }
 
 function getConfig() {
-  const file = readConfigFile()
-  return {
-    token: process.env["PLANE_API_TOKEN"] ?? file.token ?? "",
-    host: (process.env["PLANE_HOST"] ?? file.host ?? "https://plane.so").replace(/\/$/, ""),
-    workspace: process.env["PLANE_WORKSPACE"] ?? file.workspace ?? "",
-  }
+	const file = readConfigFile();
+	return {
+		token: process.env["PLANE_API_TOKEN"] ?? file.token ?? "",
+		host: (
+			process.env["PLANE_HOST"] ??
+			file.host ??
+			"https://plane.so"
+		).replace(/\/$/, ""),
+		workspace: process.env["PLANE_WORKSPACE"] ?? file.workspace ?? "",
+	};
 }
 
 function request(
-  method: string,
-  path: string,
-  body?: unknown,
+	method: string,
+	path: string,
+	body?: unknown,
 ): Effect.Effect<unknown, Error> {
-  return Effect.tryPromise({
-    try: async () => {
-      const { token, host, workspace } = getConfig()
-      let url = `${host}/api/v1/workspaces/${workspace}/${path}`
+	return Effect.tryPromise({
+		try: async () => {
+			const { token, host, workspace } = getConfig();
+			let url = `${host}/api/v1/workspaces/${workspace}/${path}`;
 
-      // Always expand state on issue list/get calls (not intake-issues/ or cycle-issues/)
-      if (method === "GET" && /(?:^|\/)(issues\/)/.test(path)) {
-        url += url.includes("?") ? "&expand=state" : "?expand=state"
-      }
+			// Always expand state on issue list/get calls (not intake-issues/ or cycle-issues/)
+			if (method === "GET" && /(?:^|\/)(issues\/)/.test(path)) {
+				url += url.includes("?") ? "&expand=state" : "?expand=state";
+			}
 
-      const headers: Record<string, string> = {
-        "X-Api-Key": token,
-      }
-      if (body !== undefined) {
-        headers["Content-Type"] = "application/json"
-      }
+			const headers: Record<string, string> = {
+				"X-Api-Key": token,
+			};
+			if (body !== undefined) {
+				headers["Content-Type"] = "application/json";
+			}
 
-      const res = await fetch(url, {
-        method,
-        headers,
-        body: body !== undefined ? JSON.stringify(body) : undefined,
-      })
+			const res = await fetch(url, {
+				method,
+				headers,
+				body: body !== undefined ? JSON.stringify(body) : undefined,
+			});
 
-      if (!res.ok) {
-        const text = await res.text()
-        throw new Error(`HTTP ${res.status}: ${text}`)
-      }
+			if (!res.ok) {
+				const text = await res.text();
+				throw new Error(`HTTP ${res.status}: ${text}`);
+			}
 
-      // 204 No Content
-      if (res.status === 204) return null
+			// 204 No Content
+			if (res.status === 204) return null;
 
-      return res.json()
-    },
-    catch: (e) => (e instanceof Error ? e : new Error(String(e))),
-  })
+			return res.json();
+		},
+		catch: (e) => (e instanceof Error ? e : new Error(String(e))),
+	});
 }
 
 export const api = {
-  get: (path: string) => request("GET", path),
-  post: (path: string, body: unknown) => request("POST", path, body),
-  patch: (path: string, body: unknown) => request("PATCH", path, body),
-  delete: (path: string) => request("DELETE", path),
-}
+	get: (path: string) => request("GET", path),
+	post: (path: string, body: unknown) => request("POST", path, body),
+	patch: (path: string, body: unknown) => request("PATCH", path, body),
+	delete: (path: string) => request("DELETE", path),
+};
 
 export function decodeOrFail<A, I>(
-  schema: Schema.Schema<A, I>,
-  data: unknown,
+	schema: Schema.Schema<A, I>,
+	data: unknown,
 ): Effect.Effect<A, Error> {
-  return Schema.decodeUnknown(schema)(data).pipe(
-    Effect.mapError((e) => new Error(String(e))),
-  )
+	return Schema.decodeUnknown(schema)(data).pipe(
+		Effect.mapError((e) => new Error(String(e))),
+	);
 }

package/src/app.ts

@@ -0,0 +1,78 @@
+import { Command } from "@effect/cli";
+import { issue } from "./commands/issue.js";
+import { issues } from "./commands/issues.js";
+import { states } from "./commands/states.js";
+import { labels } from "./commands/labels.js";
+import { members } from "./commands/members.js";
+import { cycles } from "./commands/cycles.js";
+import { modules } from "./commands/modules.js";
+import { intake } from "./commands/intake.js";
+import { pages } from "./commands/pages.js";
+import { projects } from "./commands/projects.js";
+import { init } from "./commands/init.js";
+
+const plane = Command.make("plane").pipe(
+	Command.withDescription(
+		`CLI for the Plane project management API. Useful for humans and AI agents/bots.
+
+CONFIGURATION
+  Config file:  ~/.config/plane/config.json  (written by 'plane init')
+  Env vars:     PLANE_API_TOKEN, PLANE_HOST, PLANE_WORKSPACE
+  Env vars take priority over the config file.
+
+QUICK START
+  plane init                          Interactive setup — saves host/workspace/token
+  plane projects list                 List projects and their identifiers
+  plane issues list PROJ              List issues for a project
+  plane issue get PROJ-29             Get full JSON for an issue
+  plane issue create PROJ "title"     Create an issue
+  plane issue update --state done PROJ-29
+  plane issue comment PROJ-29 "text"  Add a comment
+
+CONCEPTS
+  Project identifier  Short string shown by 'plane projects list' (e.g. ACME, WEB)
+  Issue ref           Identifier + sequence number (e.g. ACME-29, WEB-5)
+  State groups        backlog | unstarted | started | completed | cancelled
+  Priorities          urgent | high | medium | low | none
+
+ALL SUBCOMMANDS
+  init                Set up config interactively
+  projects list       List all projects
+  issues list         List issues (supports --state filter)
+  issue               get | create | update | delete | comment | activity |
+                      link | comments | worklogs
+  cycles              list | issues (list, add)
+  modules             list | issues (list, add, remove)
+  intake              list | accept | reject
+  pages               list | get
+  states list         List workflow states for a project
+  labels list         List labels for a project
+  members list        List members of a project
+
+FOR AI AGENTS / BOTS
+  - Add --json to any list command for JSON output (array of objects)
+  - Add --xml to any list command for XML output
+  - 'plane issue get PROJ-N' always outputs full JSON
+  - Use PLANE_API_TOKEN / PLANE_HOST / PLANE_WORKSPACE env vars to avoid 'plane init'
+  - Full Plane REST API reference (180+ endpoints):
+    https://developers.plane.so/api-reference/introduction`,
+	),
+	Command.withSubcommands([
+		init,
+		projects,
+		issues,
+		issue,
+		states,
+		labels,
+		members,
+		cycles,
+		modules,
+		intake,
+		pages,
+	]),
+);
+
+export const cli = Command.run(plane, {
+	name: "plane",
+	version: "0.1.0",
+});

package/src/bin.ts

@@ -1,73 +1,8 @@
-import { Command } from "@effect/cli"
-import { NodeContext, NodeRuntime } from "@effect/platform-node"
-import { Effect, Layer } from "effect"
-import { issue } from "./commands/issue.js"
-import { issues } from "./commands/issues.js"
-import { states } from "./commands/states.js"
-import { labels } from "./commands/labels.js"
-import { members } from "./commands/members.js"
-import { cycles } from "./commands/cycles.js"
-import { modules } from "./commands/modules.js"
-import { intake } from "./commands/intake.js"
-import { pages } from "./commands/pages.js"
-import { projects } from "./commands/projects.js"
-import { init } from "./commands/init.js"
-
-const plane = Command.make("plane").pipe(
-  Command.withDescription(
-    `CLI for the Plane project management API. Useful for humans and AI agents/bots.
-
-CONFIGURATION
-  Config file:  ~/.config/plane/config.json  (written by 'plane init')
-  Env vars:     PLANE_API_TOKEN, PLANE_HOST, PLANE_WORKSPACE
-  Env vars take priority over the config file.
-
-QUICK START
-  plane init                          Interactive setup — saves host/workspace/token
-  plane projects list                 List projects and their identifiers
-  plane issues list PROJ              List issues for a project
-  plane issue get PROJ-29             Get full JSON for an issue
-  plane issue create PROJ "title"     Create an issue
-  plane issue update --state done PROJ-29
-  plane issue comment PROJ-29 "text"  Add a comment
-
-CONCEPTS
-  Project identifier  Short string shown by 'plane projects list' (e.g. ACME, WEB)
-  Issue ref           Identifier + sequence number (e.g. ACME-29, WEB-5)
-  State groups        backlog | unstarted | started | completed | cancelled
-  Priorities          urgent | high | medium | low | none
-
-ALL SUBCOMMANDS
-  init                Set up config interactively
-  projects list       List all projects
-  issues list         List issues (supports --state filter)
-  issue               get | create | update | delete | comment | activity |
-                      link | comments | worklogs
-  cycles              list | issues (list, add)
-  modules             list | issues (list, add, remove)
-  intake              list | accept | reject
-  pages               list | get
-  states list         List workflow states for a project
-  labels list         List labels for a project
-  members list        List members of a project
-
-FOR AI AGENTS / BOTS
-  - Add --json to any list command for JSON output (array of objects)
-  - Add --xml to any list command for XML output
-  - 'plane issue get PROJ-N' always outputs full JSON
-  - Use PLANE_API_TOKEN / PLANE_HOST / PLANE_WORKSPACE env vars to avoid 'plane init'
-  - Full Plane REST API reference (180+ endpoints):
-    https://developers.plane.so/api-reference/introduction`,
-  ),
-  Command.withSubcommands([init, projects, issues, issue, states, labels, members, cycles, modules, intake, pages]),
-)
-
-const cli = Command.run(plane, {
-  name: "plane",
-  version: "0.1.0",
-})
+import { NodeContext, NodeRuntime } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+import { cli } from "./app.js";
 
 Effect.suspend(() => cli(process.argv)).pipe(
-  Effect.provide(Layer.mergeAll(NodeContext.layer)),
-  NodeRuntime.runMain,
-)
+	Effect.provide(Layer.mergeAll(NodeContext.layer)),
+	NodeRuntime.runMain,
+);

package/src/commands/cycles.ts

@@ -1,113 +1,132 @@
-import { Command, Args } from "@effect/cli"
-import { Console, Effect } from "effect"
-import { api, decodeOrFail } from "../api.js"
-import { CyclesResponseSchema, CycleIssuesResponseSchema } from "../config.js"
-import { resolveProject, parseIssueRef, findIssueBySeq } from "../resolve.js"
-import { jsonMode, xmlMode, toXml } from "../output.js"
+import { Command, Args } from "@effect/cli";
+import { Console, Effect } from "effect";
+import { api, decodeOrFail } from "../api.js";
+import { CyclesResponseSchema, CycleIssuesResponseSchema } from "../config.js";
+import { resolveProject, parseIssueRef, findIssueBySeq } from "../resolve.js";
+import { jsonMode, xmlMode, toXml } from "../output.js";
 
 const projectArg = Args.text({ name: "project" }).pipe(
-  Args.withDescription("Project identifier (e.g. PROJ, WEB, OPS)"),
-)
+	Args.withDescription("Project identifier (e.g. PROJ, WEB, OPS)"),
+);
 
 const cycleIdArg = Args.text({ name: "cycle-id" }).pipe(
-  Args.withDescription("Cycle UUID (from 'plane cycles list PROJECT')"),
-)
+	Args.withDescription("Cycle UUID (from 'plane cycles list PROJECT')"),
+);
 
 // --- cycles list ---
 
-export const cyclesList = Command.make("list", { project: projectArg }, ({ project }) =>
-  Effect.gen(function* () {
-    const { id } = yield* resolveProject(project)
-    const raw = yield* api.get(`projects/${id}/cycles/`)
-    const { results } = yield* decodeOrFail(CyclesResponseSchema, raw)
-    if (jsonMode) { yield* Console.log(JSON.stringify(results, null, 2)); return }
-    if (xmlMode) { yield* Console.log(toXml(results)); return }
-    if (results.length === 0) {
-      yield* Console.log("No cycles found")
-      return
-    }
-    const lines = results.map((c) => {
-      const start = c.start_date ?? "—"
-      const end = c.end_date ?? "—"
-      const status = (c.status ?? "?").padEnd(10)
-      return `${c.id}  ${status}  ${start} → ${end}  ${c.name}`
-    })
-    yield* Console.log(lines.join("\n"))
-  }),
+export const cyclesList = Command.make(
+	"list",
+	{ project: projectArg },
+	({ project }) =>
+		Effect.gen(function* () {
+			const { id } = yield* resolveProject(project);
+			const raw = yield* api.get(`projects/${id}/cycles/`);
+			const { results } = yield* decodeOrFail(CyclesResponseSchema, raw);
+			if (jsonMode) {
+				yield* Console.log(JSON.stringify(results, null, 2));
+				return;
+			}
+			if (xmlMode) {
+				yield* Console.log(toXml(results));
+				return;
+			}
+			if (results.length === 0) {
+				yield* Console.log("No cycles found");
+				return;
+			}
+			const lines = results.map((c) => {
+				const start = c.start_date ?? "—";
+				const end = c.end_date ?? "—";
+				const status = (c.status ?? "?").padEnd(10);
+				return `${c.id}  ${status}  ${start} → ${end}  ${c.name}`;
+			});
+			yield* Console.log(lines.join("\n"));
+		}),
 ).pipe(
-  Command.withDescription(
-    "List cycles for a project. Shows cycle UUID, status, date range, and name.\n\nExample:\n  plane cycles list PROJ",
-  ),
-)
+	Command.withDescription(
+		"List cycles for a project. Shows cycle UUID, status, date range, and name.\n\nExample:\n  plane cycles list PROJ",
+	),
+);
 
 // --- cycles issues list ---
 
 export const cycleIssuesList = Command.make(
-  "list",
-  { project: projectArg, cycleId: cycleIdArg },
-  ({ project, cycleId }) =>
-    Effect.gen(function* () {
-      const { key, id } = yield* resolveProject(project)
-      const raw = yield* api.get(`projects/${id}/cycles/${cycleId}/cycle-issues/`)
-      const { results } = yield* decodeOrFail(CycleIssuesResponseSchema, raw)
-      if (jsonMode) { yield* Console.log(JSON.stringify(results, null, 2)); return }
-      if (xmlMode) { yield* Console.log(toXml(results)); return }
-      if (results.length === 0) {
-        yield* Console.log("No issues in cycle")
-        return
-      }
-      const lines = results.map((ci) => {
-        if (ci.issue_detail) {
-          const seq = String(ci.issue_detail.sequence_id).padStart(3, " ")
-          return `${key}-${seq}  ${ci.issue_detail.name}  (${ci.id})`
-        }
-        return `${ci.issue}  (cycle-issue: ${ci.id})`
-      })
-      yield* Console.log(lines.join("\n"))
-    }),
+	"list",
+	{ project: projectArg, cycleId: cycleIdArg },
+	({ project, cycleId }) =>
+		Effect.gen(function* () {
+			const { key, id } = yield* resolveProject(project);
+			const raw = yield* api.get(
+				`projects/${id}/cycles/${cycleId}/cycle-issues/`,
+			);
+			const { results } = yield* decodeOrFail(CycleIssuesResponseSchema, raw);
+			if (jsonMode) {
+				yield* Console.log(JSON.stringify(results, null, 2));
+				return;
+			}
+			if (xmlMode) {
+				yield* Console.log(toXml(results));
+				return;
+			}
+			if (results.length === 0) {
+				yield* Console.log("No issues in cycle");
+				return;
+			}
+			const lines = results.map((ci) => {
+				if (ci.issue_detail) {
+					const seq = String(ci.issue_detail.sequence_id).padStart(3, " ");
+					return `${key}-${seq}  ${ci.issue_detail.name}  (${ci.id})`;
+				}
+				return `${ci.issue}  (cycle-issue: ${ci.id})`;
+			});
+			yield* Console.log(lines.join("\n"));
+		}),
 ).pipe(
-  Command.withDescription(
-    "List issues in a cycle.\n\nExample:\n  plane cycles issues list PROJ <cycle-id>",
-  ),
-)
+	Command.withDescription(
+		"List issues in a cycle.\n\nExample:\n  plane cycles issues list PROJ <cycle-id>",
+	),
+);
 
 // --- cycles issues add ---
 
 const issueRefArg = Args.text({ name: "ref" }).pipe(
-  Args.withDescription("Issue reference to add (e.g. PROJ-29)"),
-)
+	Args.withDescription("Issue reference to add (e.g. PROJ-29)"),
+);
 
 export const cycleIssuesAdd = Command.make(
-  "add",
-  { project: projectArg, cycleId: cycleIdArg, ref: issueRefArg },
-  ({ project, cycleId, ref }) =>
-    Effect.gen(function* () {
-      const { id: projectId } = yield* resolveProject(project)
-      const { seq } = yield* parseIssueRef(ref)
-      const issue = yield* findIssueBySeq(projectId, seq)
-      yield* api.post(`projects/${projectId}/cycles/${cycleId}/cycle-issues/`, {
-        issues: [issue.id],
-      })
-      yield* Console.log(`Added ${ref} to cycle ${cycleId}`)
-    }),
+	"add",
+	{ project: projectArg, cycleId: cycleIdArg, ref: issueRefArg },
+	({ project, cycleId, ref }) =>
+		Effect.gen(function* () {
+			const { id: projectId } = yield* resolveProject(project);
+			const { seq } = yield* parseIssueRef(ref);
+			const issue = yield* findIssueBySeq(projectId, seq);
+			yield* api.post(`projects/${projectId}/cycles/${cycleId}/cycle-issues/`, {
+				issues: [issue.id],
+			});
+			yield* Console.log(`Added ${ref} to cycle ${cycleId}`);
+		}),
 ).pipe(
-  Command.withDescription(
-    "Add an issue to a cycle.\n\nExample:\n  plane cycles issues add PROJ <cycle-id> PROJ-29",
-  ),
-)
+	Command.withDescription(
+		"Add an issue to a cycle.\n\nExample:\n  plane cycles issues add PROJ <cycle-id> PROJ-29",
+	),
+);
 
 // --- cycles issues (parent) ---
 
 export const cycleIssues = Command.make("issues").pipe(
-  Command.withDescription("Manage issues within a cycle. Subcommands: list, add"),
-  Command.withSubcommands([cycleIssuesList, cycleIssuesAdd]),
-)
+	Command.withDescription(
+		"Manage issues within a cycle. Subcommands: list, add",
+	),
+	Command.withSubcommands([cycleIssuesList, cycleIssuesAdd]),
+);
 
 // --- cycles (parent) ---
 
 export const cycles = Command.make("cycles").pipe(
-  Command.withDescription(
-    "Manage cycles (sprints). Subcommands: list, issues\n\nExamples:\n  plane cycles list PROJ\n  plane cycles issues list PROJ <cycle-id>\n  plane cycles issues add PROJ <cycle-id> PROJ-29",
-  ),
-  Command.withSubcommands([cyclesList, cycleIssues]),
-)
+	Command.withDescription(
+		"Manage cycles (sprints). Subcommands: list, issues\n\nExamples:\n  plane cycles list PROJ\n  plane cycles issues list PROJ <cycle-id>\n  plane cycles issues add PROJ <cycle-id> PROJ-29",
+	),
+	Command.withSubcommands([cyclesList, cycleIssues]),
+);