@aaronshaf/plane 0.1.2

package/src/api.ts

@@ -0,0 +1,81 @@
+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")
+
+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 ?? "",
+  }
+}
+
+function request(
+  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}`
+
+      // 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 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}`)
+      }
+
+      // 204 No Content
+      if (res.status === 204) return null
+
+      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),
+}
+
+export function decodeOrFail<A, I>(
+  schema: Schema.Schema<A, I>,
+  data: unknown,
+): Effect.Effect<A, Error> {
+  return Schema.decodeUnknown(schema)(data).pipe(
+    Effect.mapError((e) => new Error(String(e))),
+  )
+}

package/src/bin.ts

@@ -0,0 +1,72 @@
+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
+  - All list commands output one record per line, tab-separated
+  - 'plane issue get PROJ-N' outputs full JSON — pipe to jq for field extraction
+  - 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",
+})
+
+Effect.suspend(() => cli(process.argv)).pipe(
+  Effect.provide(Layer.mergeAll(NodeContext.layer)),
+  NodeRuntime.runMain,
+)

package/src/commands/cycles.ts

@@ -0,0 +1,108 @@
+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"
+
+const projectArg = Args.text({ name: "project" }).pipe(
+  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')"),
+)
+
+// --- 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 (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",
+  ),
+)
+
+// --- 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 (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>",
+  ),
+)
+
+// --- cycles issues add ---
+
+const issueRefArg = Args.text({ name: "ref" }).pipe(
+  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}`)
+    }),
+).pipe(
+  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]),
+)
+
+// --- 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]),
+)

package/src/commands/init.ts

@@ -0,0 +1,72 @@
+import { Command } from "@effect/cli"
+import { Console, Effect } from "effect"
+import * as readline from "node:readline"
+import * as fs from "node:fs"
+import * as path from "node:path"
+import * as os from "node:os"
+
+export const CONFIG_DIR = path.join(os.homedir(), ".config", "plane")
+export const CONFIG_FILE = path.join(CONFIG_DIR, "config.json")
+
+export interface PlaneConfig {
+  token: string
+  host: string
+  workspace: string
+}
+
+function prompt(rl: readline.Interface, question: string): Promise<string> {
+  return new Promise((resolve) => rl.question(question, resolve))
+}
+
+export const init = Command.make("init", {}, () =>
+  Effect.gen(function* () {
+    let existing: Partial<PlaneConfig> = {}
+    try {
+      existing = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"))
+    } catch {
+      // no existing config
+    }
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    })
+
+    const host = yield* Effect.promise(() =>
+      prompt(rl, `Plane host [${existing.host ?? "https://plane.so"}]: `),
+    )
+    const workspace = yield* Effect.promise(() =>
+      prompt(rl, `Workspace slug [${existing.workspace ?? ""}]: `),
+    )
+    const token = yield* Effect.promise(() =>
+      prompt(rl, `API token [${existing.token ? "***" : ""}]: `),
+    )
+
+    rl.close()
+
+    const config: PlaneConfig = {
+      host: host.trim() || existing.host || "https://plane.so",
+      workspace: workspace.trim() || existing.workspace || "",
+      token: token.trim() || existing.token || "",
+    }
+
+    if (!config.token) {
+      yield* Effect.fail(new Error("API token is required"))
+    }
+    if (!config.workspace) {
+      yield* Effect.fail(new Error("Workspace slug is required"))
+    }
+
+    fs.mkdirSync(CONFIG_DIR, { recursive: true })
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 })
+
+    yield* Console.log(`\nConfig saved to ${CONFIG_FILE}`)
+    yield* Console.log(`  Host:      ${config.host}`)
+    yield* Console.log(`  Workspace: ${config.workspace}`)
+    yield* Console.log(`  Token:     ***`)
+  }),
+).pipe(
+  Command.withDescription(
+    "Interactive setup. Prompts for host, workspace slug, and API token, then saves to ~/.config/plane/config.json (mode 0600). Safe to re-run — existing values shown as defaults.",
+  ),
+)

package/src/commands/intake.ts

@@ -0,0 +1,85 @@
+import { Command, Options, Args } from "@effect/cli"
+import { Console, Effect } from "effect"
+import { api, decodeOrFail } from "../api.js"
+import { IntakeIssuesResponseSchema } from "../config.js"
+import { resolveProject } from "../resolve.js"
+
+const projectArg = Args.text({ name: "project" }).pipe(
+  Args.withDescription("Project identifier (e.g. PROJ, WEB, OPS)"),
+)
+
+// Intake status codes: -2=rejected, -1=snoozed, 0=pending, 1=accepted, 2=duplicate
+const STATUS_LABELS: Record<number, string> = {
+  [-2]: "rejected",
+  [-1]: "snoozed",
+  [0]: "pending",
+  [1]: "accepted",
+  [2]: "duplicate",
+}
+
+// --- intake list ---
+
+export const intakeList = Command.make("list", { project: projectArg }, ({ project }) =>
+  Effect.gen(function* () {
+    const { id } = yield* resolveProject(project)
+    const raw = yield* api.get(`projects/${id}/intake-issues/`)
+    const { results } = yield* decodeOrFail(IntakeIssuesResponseSchema, raw)
+    if (results.length === 0) {
+      yield* Console.log("No intake issues")
+      return
+    }
+    const lines = results.map((i) => {
+      const status = STATUS_LABELS[i.status ?? 0] ?? String(i.status ?? "?")
+      const statusPad = status.padEnd(10)
+      if (i.issue_detail) {
+        const seq = String(i.issue_detail.sequence_id).padStart(3, " ")
+        return `${i.id}  [${statusPad}]  ${i.issue_detail.name}`
+      }
+      return `${i.id}  [${statusPad}]`
+    })
+    yield* Console.log(lines.join("\n"))
+  }),
+).pipe(
+  Command.withDescription(
+    "List intake (triage) issues for a project. Shows status: pending, accepted, rejected, snoozed, duplicate.\n\nExample:\n  plane intake list PROJ",
+  ),
+)
+
+// --- intake accept ---
+
+const intakeIdArg = Args.text({ name: "intake-id" }).pipe(
+  Args.withDescription("Intake issue ID (from 'plane intake list')"),
+)
+
+export const intakeAccept = Command.make(
+  "accept",
+  { project: projectArg, intakeId: intakeIdArg },
+  ({ project, intakeId }) =>
+    Effect.gen(function* () {
+      const { id } = yield* resolveProject(project)
+      yield* api.patch(`projects/${id}/intake-issues/${intakeId}/`, { status: 1 })
+      yield* Console.log(`Intake issue ${intakeId} accepted`)
+    }),
+).pipe(Command.withDescription("Accept an intake issue, creating it as a tracked work item."))
+
+// --- intake reject ---
+
+export const intakeReject = Command.make(
+  "reject",
+  { project: projectArg, intakeId: intakeIdArg },
+  ({ project, intakeId }) =>
+    Effect.gen(function* () {
+      const { id } = yield* resolveProject(project)
+      yield* api.patch(`projects/${id}/intake-issues/${intakeId}/`, { status: -2 })
+      yield* Console.log(`Intake issue ${intakeId} rejected`)
+    }),
+).pipe(Command.withDescription("Reject an intake issue."))
+
+// --- intake (parent) ---
+
+export const intake = Command.make("intake").pipe(
+  Command.withDescription(
+    "Manage intake (incoming request triage). Subcommands: list, accept, reject\n\nExamples:\n  plane intake list PROJ\n  plane intake accept PROJ <intake-id>\n  plane intake reject PROJ <intake-id>",
+  ),
+  Command.withSubcommands([intakeList, intakeAccept, intakeReject]),
+)