@aaronshaf/plane 0.1.2

package/src/commands/pages.ts

@@ -0,0 +1,63 @@
+import { Command, Args } from "@effect/cli"
+import { Console, Effect } from "effect"
+import { api, decodeOrFail } from "../api.js"
+import { PagesResponseSchema, PageSchema } from "../config.js"
+import { resolveProject } from "../resolve.js"
+
+const projectArg = Args.text({ name: "project" }).pipe(
+  Args.withDescription("Project identifier (e.g. PROJ, WEB, OPS)"),
+)
+
+// --- pages list ---
+
+export const pagesList = Command.make("list", { project: projectArg }, ({ project }) =>
+  Effect.gen(function* () {
+    const { id } = yield* resolveProject(project)
+    const raw = yield* api.get(`projects/${id}/pages/`)
+    const { results } = yield* decodeOrFail(PagesResponseSchema, raw)
+    if (results.length === 0) {
+      yield* Console.log("No pages")
+      return
+    }
+    const lines = results.map((p) => {
+      const updated = (p.updated_at ?? p.created_at).slice(0, 10)
+      return `${p.id}  ${updated}  ${p.name}`
+    })
+    yield* Console.log(lines.join("\n"))
+  }),
+).pipe(
+  Command.withDescription(
+    "List pages for a project. Shows page UUID, last updated date, and title.\n\nExample:\n  plane pages list PROJ",
+  ),
+)
+
+// --- pages get ---
+
+const pageIdArg = Args.text({ name: "page-id" }).pipe(
+  Args.withDescription("Page UUID (from 'plane pages list')"),
+)
+
+export const pagesGet = Command.make(
+  "get",
+  { project: projectArg, pageId: pageIdArg },
+  ({ project, pageId }) =>
+    Effect.gen(function* () {
+      const { id } = yield* resolveProject(project)
+      const raw = yield* api.get(`projects/${id}/pages/${pageId}/`)
+      const page = yield* decodeOrFail(PageSchema, raw)
+      yield* Console.log(JSON.stringify(page, null, 2))
+    }),
+).pipe(
+  Command.withDescription(
+    "Print full JSON for a page including description_html.\n\nExample:\n  plane pages get PROJ <page-id>",
+  ),
+)
+
+// --- pages (parent) ---
+
+export const pages = Command.make("pages").pipe(
+  Command.withDescription(
+    "Manage project pages (documentation). Subcommands: list, get\n\nExamples:\n  plane pages list PROJ\n  plane pages get PROJ <page-id>",
+  ),
+  Command.withSubcommands([pagesList, pagesGet]),
+)

package/src/commands/projects.ts

@@ -0,0 +1,24 @@
+import { Command } from "@effect/cli"
+import { Console, Effect } from "effect"
+import { api, decodeOrFail } from "../api.js"
+import { ProjectsResponseSchema } from "../config.js"
+
+export const projectsList = Command.make("list", {}, () =>
+  Effect.gen(function* () {
+    const raw = yield* api.get("projects/")
+    const { results } = yield* decodeOrFail(ProjectsResponseSchema, raw)
+    const lines = results.map(
+      (p) => `${p.identifier.padEnd(6)}  ${p.id}  ${p.name}`,
+    )
+    yield* Console.log(lines.join("\n"))
+  }),
+).pipe(
+  Command.withDescription(
+    "List all projects in the workspace. The IDENTIFIER column is what you pass to other commands (e.g. 'plane issues list PROJ').",
+  ),
+)
+
+export const projects = Command.make("projects").pipe(
+  Command.withDescription("Manage projects."),
+  Command.withSubcommands([projectsList]),
+)

package/src/commands/states.ts

@@ -0,0 +1,28 @@
+import { Command, Options, Args } from "@effect/cli"
+import { Console, Effect } from "effect"
+import { api, decodeOrFail } from "../api.js"
+import { StatesResponseSchema } from "../config.js"
+import { resolveProject } from "../resolve.js"
+
+const projectArg = Args.text({ name: "project" }).pipe(
+  Args.withDescription("Project identifier (e.g. PROJ, WEB, OPS)"),
+)
+
+export const statesList = Command.make(
+  "list",
+  { project: projectArg },
+  ({ project }) =>
+    Effect.gen(function* () {
+      const { id } = yield* resolveProject(project)
+      const raw = yield* api.get(`projects/${id}/states/`)
+      const { results } = yield* decodeOrFail(StatesResponseSchema, raw)
+      const lines = results.map(
+        (s) => `${s.id}  ${s.group.padEnd(12)}  ${s.name}`,
+      )
+      yield* Console.log(lines.join("\n"))
+    }),
+)
+
+export const states = Command.make("states").pipe(
+  Command.withSubcommands([statesList]),
+)

package/src/config.ts

@@ -0,0 +1,217 @@
+import { Schema } from "effect"
+
+// --- Schemas ---
+
+export const StateSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  group: Schema.String,
+  color: Schema.optional(Schema.String),
+})
+export type State = typeof StateSchema.Type
+
+export const IssueSchema = Schema.Struct({
+  id: Schema.String,
+  sequence_id: Schema.Number,
+  name: Schema.String,
+  priority: Schema.String,
+  state: Schema.Union(Schema.String, StateSchema),
+  description_html: Schema.optional(Schema.NullOr(Schema.String)),
+})
+export type Issue = typeof IssueSchema.Type
+
+export const StatesResponseSchema = Schema.Struct({
+  results: Schema.Array(StateSchema),
+})
+
+export const IssuesResponseSchema = Schema.Struct({
+  results: Schema.Array(IssueSchema),
+})
+
+export const LabelSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  color: Schema.optional(Schema.NullOr(Schema.String)),
+  parent: Schema.optional(Schema.NullOr(Schema.String)),
+})
+export type Label = typeof LabelSchema.Type
+
+export const LabelsResponseSchema = Schema.Struct({
+  results: Schema.Array(LabelSchema),
+})
+
+// Members endpoint returns a flat array (no results wrapper)
+export const MemberSchema = Schema.Struct({
+  id: Schema.String,
+  display_name: Schema.String,
+  email: Schema.optional(Schema.NullOr(Schema.String)),
+})
+export type Member = typeof MemberSchema.Type
+
+export const MembersResponseSchema = Schema.Array(MemberSchema)
+
+export const CycleSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  status: Schema.optional(Schema.String),
+  start_date: Schema.optional(Schema.NullOr(Schema.String)),
+  end_date: Schema.optional(Schema.NullOr(Schema.String)),
+})
+export type Cycle = typeof CycleSchema.Type
+
+export const CyclesResponseSchema = Schema.Struct({
+  results: Schema.Array(CycleSchema),
+})
+
+export const ProjectSchema = Schema.Struct({
+  id: Schema.String,
+  identifier: Schema.String,
+  name: Schema.String,
+  description: Schema.optional(Schema.NullOr(Schema.String)),
+})
+export type Project = typeof ProjectSchema.Type
+
+export const ProjectsResponseSchema = Schema.Struct({
+  results: Schema.Array(ProjectSchema),
+})
+
+export const ProjectsFlatResponseSchema = Schema.Array(ProjectSchema)
+
+export const ActivitySchema = Schema.Struct({
+  id: Schema.String,
+  actor_detail: Schema.optional(
+    Schema.Struct({
+      display_name: Schema.String,
+    }),
+  ),
+  field: Schema.optional(Schema.NullOr(Schema.String)),
+  old_value: Schema.optional(Schema.NullOr(Schema.String)),
+  new_value: Schema.optional(Schema.NullOr(Schema.String)),
+  verb: Schema.optional(Schema.String),
+  created_at: Schema.String,
+})
+export type Activity = typeof ActivitySchema.Type
+
+export const ActivitiesResponseSchema = Schema.Struct({
+  results: Schema.Array(ActivitySchema),
+})
+
+export const IssueLinkSchema = Schema.Struct({
+  id: Schema.String,
+  title: Schema.optional(Schema.NullOr(Schema.String)),
+  url: Schema.String,
+  created_at: Schema.String,
+})
+export type IssueLink = typeof IssueLinkSchema.Type
+
+export const IssueLinksResponseSchema = Schema.Struct({
+  results: Schema.Array(IssueLinkSchema),
+})
+
+export const ModuleSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  status: Schema.optional(Schema.String),
+  description: Schema.optional(Schema.NullOr(Schema.String)),
+})
+export type Module = typeof ModuleSchema.Type
+
+export const ModulesResponseSchema = Schema.Struct({
+  results: Schema.Array(ModuleSchema),
+})
+
+export const ModuleIssueSchema = Schema.Struct({
+  id: Schema.String,
+  issue: Schema.String,
+  issue_detail: Schema.optional(
+    Schema.Struct({
+      id: Schema.String,
+      sequence_id: Schema.Number,
+      name: Schema.String,
+    }),
+  ),
+})
+export type ModuleIssue = typeof ModuleIssueSchema.Type
+
+export const ModuleIssuesResponseSchema = Schema.Struct({
+  results: Schema.Array(ModuleIssueSchema),
+})
+
+export const WorklogSchema = Schema.Struct({
+  id: Schema.String,
+  description: Schema.optional(Schema.NullOr(Schema.String)),
+  duration: Schema.Number,
+  logged_by_detail: Schema.optional(
+    Schema.Struct({ display_name: Schema.String }),
+  ),
+  created_at: Schema.String,
+})
+export type Worklog = typeof WorklogSchema.Type
+
+export const WorklogsResponseSchema = Schema.Struct({
+  results: Schema.Array(WorklogSchema),
+})
+
+export const IntakeIssueSchema = Schema.Struct({
+  id: Schema.String,
+  issue: Schema.optional(Schema.String),
+  issue_detail: Schema.optional(
+    Schema.Struct({
+      id: Schema.String,
+      sequence_id: Schema.Number,
+      name: Schema.String,
+      priority: Schema.String,
+    }),
+  ),
+  status: Schema.optional(Schema.Number),
+  created_at: Schema.String,
+})
+export type IntakeIssue = typeof IntakeIssueSchema.Type
+
+export const IntakeIssuesResponseSchema = Schema.Struct({
+  results: Schema.Array(IntakeIssueSchema),
+})
+
+export const PageSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  description_html: Schema.optional(Schema.NullOr(Schema.String)),
+  created_at: Schema.String,
+  updated_at: Schema.optional(Schema.String),
+})
+export type Page = typeof PageSchema.Type
+
+export const PagesResponseSchema = Schema.Struct({
+  results: Schema.Array(PageSchema),
+})
+
+export const CommentSchema = Schema.Struct({
+  id: Schema.String,
+  comment_html: Schema.optional(Schema.String),
+  actor_detail: Schema.optional(
+    Schema.Struct({ display_name: Schema.String }),
+  ),
+  created_at: Schema.String,
+})
+export type Comment = typeof CommentSchema.Type
+
+export const CommentsResponseSchema = Schema.Struct({
+  results: Schema.Array(CommentSchema),
+})
+
+export const CycleIssueSchema = Schema.Struct({
+  id: Schema.String,
+  issue: Schema.String,
+  issue_detail: Schema.optional(
+    Schema.Struct({
+      id: Schema.String,
+      sequence_id: Schema.Number,
+      name: Schema.String,
+    }),
+  ),
+})
+export type CycleIssue = typeof CycleIssueSchema.Type
+
+export const CycleIssuesResponseSchema = Schema.Struct({
+  results: Schema.Array(CycleIssueSchema),
+})

package/src/format.ts

@@ -0,0 +1,11 @@
+import type { Issue, State } from "./config.js"
+
+export function formatIssue(issue: Issue, projKey: string): string {
+  const state = issue.state as State | string
+  const stateName = typeof state === "object" ? state.name : "?"
+  const stateGroup = typeof state === "object" ? state.group : "?"
+  const seqPad = String(issue.sequence_id).padStart(3, " ")
+  const groupPad = stateGroup.padEnd(10, " ")
+  const namePad = stateName.padEnd(12, " ")
+  return `${projKey}-${seqPad}  [${groupPad}]  ${namePad}  ${issue.name}`
+}

package/src/resolve.ts

@@ -0,0 +1,76 @@
+import { Effect } from "effect"
+import { api, decodeOrFail } from "./api.js"
+import { IssuesResponseSchema, StatesResponseSchema, ProjectsResponseSchema } from "./config.js"
+
+// Cache project list within a process invocation
+let _projectCache: Record<string, string> | null = null
+
+/** Clear the project cache — for use in tests only */
+export function _clearProjectCache() {
+  _projectCache = null
+}
+
+function getProjectMap(): Effect.Effect<Record<string, string>, Error> {
+  if (_projectCache) return Effect.succeed(_projectCache)
+  return Effect.gen(function* () {
+    const raw = yield* api.get("projects/")
+    const { results } = yield* decodeOrFail(ProjectsResponseSchema, raw)
+    _projectCache = Object.fromEntries(results.map((p) => [p.identifier.toUpperCase(), p.id]))
+    return _projectCache
+  })
+}
+
+export function resolveProject(
+  identifier: string,
+): Effect.Effect<{ key: string; id: string }, Error> {
+  const key = identifier.toUpperCase()
+  return getProjectMap().pipe(
+    Effect.flatMap((map) => {
+      const id = map[key]
+      if (!id) {
+        return Effect.fail(
+          new Error(`Unknown project: ${identifier}. Known: ${Object.keys(map).join(", ")}`),
+        )
+      }
+      return Effect.succeed({ key, id })
+    }),
+  )
+}
+
+export function parseIssueRef(
+  ref: string,
+): Effect.Effect<{ projectId: string; projKey: string; seq: number }, Error> {
+  const parts = ref.toUpperCase().split("-")
+  if (parts.length !== 2 || !/^\d+$/.test(parts[1])) {
+    return Effect.fail(
+      new Error(`Invalid issue ref: ${ref}. Expected format like PROJ-29`),
+    )
+  }
+  const [projKey, seqStr] = parts
+  return resolveProject(projKey).pipe(
+    Effect.map(({ id }) => ({ projectId: id, projKey, seq: parseInt(seqStr, 10) })),
+  )
+}
+
+export function findIssueBySeq(projectId: string, seq: number) {
+  return Effect.gen(function* () {
+    const raw = yield* api.get(`projects/${projectId}/issues/`)
+    const { results } = yield* decodeOrFail(IssuesResponseSchema, raw)
+    const issue = results.find((i) => i.sequence_id === seq)
+    if (!issue) return yield* Effect.fail(new Error(`Issue #${seq} not found`))
+    return issue
+  })
+}
+
+export function getStateId(projectId: string, nameOrGroup: string) {
+  return Effect.gen(function* () {
+    const raw = yield* api.get(`projects/${projectId}/states/`)
+    const { results } = yield* decodeOrFail(StatesResponseSchema, raw)
+    const lower = nameOrGroup.toLowerCase()
+    const state = results.find(
+      (s) => s.group === lower || s.name.toLowerCase() === lower,
+    )
+    if (!state) return yield* Effect.fail(new Error(`State not found: ${nameOrGroup}`))
+    return state.id
+  })
+}

package/tests/api.test.ts

@@ -0,0 +1,169 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "bun:test"
+import { Effect } from "effect"
+import { http, HttpResponse } from "msw"
+import { setupServer } from "msw/node"
+import { api, decodeOrFail } from "@/api"
+import { Schema } from "effect"
+
+const BASE = "http://api-test.local"
+const WS = "testws"
+
+const server = setupServer()
+
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }))
+afterAll(() => server.close())
+
+beforeEach(() => {
+  process.env["PLANE_HOST"] = BASE
+  process.env["PLANE_WORKSPACE"] = WS
+  process.env["PLANE_API_TOKEN"] = "test-token"
+})
+
+afterEach(() => {
+  server.resetHandlers()
+  delete process.env["PLANE_HOST"]
+  delete process.env["PLANE_WORKSPACE"]
+  delete process.env["PLANE_API_TOKEN"]
+})
+
+describe("api.get", () => {
+  it("makes a GET request and returns parsed JSON", async () => {
+    server.use(
+      http.get(`${BASE}/api/v1/workspaces/${WS}/projects/`, () =>
+        HttpResponse.json({ results: [{ id: "p1", identifier: "ACME", name: "InstUI" }] }),
+      ),
+    )
+    const result = await Effect.runPromise(api.get("projects/"))
+    expect((result as any).results).toHaveLength(1)
+  })
+
+  it("strips trailing slash from PLANE_HOST", async () => {
+    process.env["PLANE_HOST"] = `${BASE}/`
+    server.use(
+      http.get(`${BASE}/api/v1/workspaces/${WS}/projects/`, () =>
+        HttpResponse.json({ results: [] }),
+      ),
+    )
+    const result = await Effect.runPromise(api.get("projects/"))
+    expect((result as any).results).toHaveLength(0)
+  })
+
+  it("appends expand=state for issues/ paths", async () => {
+    let capturedUrl = ""
+    server.use(
+      http.get(`${BASE}/api/v1/workspaces/${WS}/projects/p1/issues/`, ({ request }) => {
+        capturedUrl = request.url
+        return HttpResponse.json({ results: [] })
+      }),
+    )
+    await Effect.runPromise(api.get("projects/p1/issues/"))
+    expect(capturedUrl).toContain("expand=state")
+  })
+
+  it("fails on HTTP 4xx response", async () => {
+    server.use(
+      http.get(`${BASE}/api/v1/workspaces/${WS}/projects/`, () =>
+        HttpResponse.json({ detail: "Not found" }, { status: 404 }),
+      ),
+    )
+    const result = await Effect.runPromise(Effect.either(api.get("projects/")))
+    expect(result._tag).toBe("Left")
+    if (result._tag === "Left") {
+      expect(result.left.message).toContain("HTTP 404")
+    }
+  })
+
+  it("fails on HTTP 401 response", async () => {
+    server.use(
+      http.get(`${BASE}/api/v1/workspaces/${WS}/projects/`, () =>
+        HttpResponse.text("Unauthorized", { status: 401 }),
+      ),
+    )
+    const result = await Effect.runPromise(Effect.either(api.get("projects/")))
+    expect(result._tag).toBe("Left")
+  })
+})
+
+describe("api.post", () => {
+  it("sends JSON body and returns parsed response", async () => {
+    server.use(
+      http.post(`${BASE}/api/v1/workspaces/${WS}/projects/p1/issues/`, async ({ request }) => {
+        const body = (await request.json()) as any
+        return HttpResponse.json({
+          id: "new-issue",
+          sequence_id: 99,
+          name: body.name,
+          priority: "none",
+          state: "s1",
+        })
+      }),
+    )
+    const result = (await Effect.runPromise(
+      api.post("projects/p1/issues/", { name: "New Issue" }),
+    )) as any
+    expect(result.sequence_id).toBe(99)
+    expect(result.name).toBe("New Issue")
+  })
+})
+
+describe("api.patch", () => {
+  it("sends a PATCH and returns updated resource", async () => {
+    server.use(
+      http.patch(
+        `${BASE}/api/v1/workspaces/${WS}/projects/p1/issues/i1/`,
+        async ({ request }) => {
+          const body = (await request.json()) as any
+          return HttpResponse.json({
+            id: "i1",
+            sequence_id: 1,
+            name: "Issue",
+            priority: body.priority ?? "low",
+            state: "s1",
+          })
+        },
+      ),
+    )
+    const result = (await Effect.runPromise(
+      api.patch("projects/p1/issues/i1/", { priority: "high" }),
+    )) as any
+    expect(result.priority).toBe("high")
+  })
+})
+
+describe("api.delete", () => {
+  it("sends a DELETE request", async () => {
+    let called = false
+    server.use(
+      http.delete(`${BASE}/api/v1/workspaces/${WS}/projects/p1/issues/i1/`, () => {
+        called = true
+        return new HttpResponse(null, { status: 204 })
+      }),
+    )
+    await Effect.runPromise(api.delete("projects/p1/issues/i1/"))
+    expect(called).toBe(true)
+  })
+})
+
+describe("decodeOrFail", () => {
+  const NameSchema = Schema.Struct({ name: Schema.String })
+
+  it("decodes valid data", async () => {
+    const result = await Effect.runPromise(decodeOrFail(NameSchema, { name: "hello" }))
+    expect(result.name).toBe("hello")
+  })
+
+  it("fails with Error for invalid data", async () => {
+    const result = await Effect.runPromise(
+      Effect.either(decodeOrFail(NameSchema, { name: 42 })),
+    )
+    expect(result._tag).toBe("Left")
+    if (result._tag === "Left") {
+      expect(result.left).toBeInstanceOf(Error)
+    }
+  })
+
+  it("fails for missing required field", async () => {
+    const result = await Effect.runPromise(Effect.either(decodeOrFail(NameSchema, {})))
+    expect(result._tag).toBe("Left")
+  })
+})