pipe-kan 0.29.2 → 0.30.1

package/dist/pipe-kan.js

@@ -268,6 +268,14 @@ function issuesToBoard(raw, opts = {}) {
   const byStatus = new Map;
   const epics = [];
   const epicByKey = new Map;
+  for (const status of opts.statuses ?? []) {
+    const title = status.trim();
+    if (!title || byStatus.has(title))
+      continue;
+    const column = { id: title, title, cards: [] };
+    byStatus.set(title, column);
+    columns.push(column);
+  }
   function rememberEpic(epic) {
     const existing = epicByKey.get(epic.key);
     if (!existing) {
@@ -352,12 +360,24 @@ function parseFlags(flags) {
   let type = "";
   let raw = "";
   let projectsValue = "";
+  let plane = false;
+  let workspace = "";
   const statusEq = [];
   const statusNeq = [];
   for (let i = 0;i < list.length; i++) {
     const token = list[i];
     if (token === "--raw")
       continue;
+    if (token === "--plane") {
+      plane = true;
+      continue;
+    }
+    if (token === "--workspace" || token.startsWith("--workspace=")) {
+      const [value, next] = takeValue(list, i, "--workspace");
+      workspace = value.startsWith("=") ? value.slice(1) : value;
+      i = next;
+      continue;
+    }
     if (token.startsWith("-a")) {
       [assignee, i] = takeValue(list, i, "-a");
       continue;
@@ -392,8 +412,9 @@ function parseFlags(flags) {
     }
   }
   const projects = projectsValue.split(",").map((p) => p.trim().toUpperCase()).filter(Boolean);
+  const workspaceSlug = workspace.trim() || undefined;
   if (raw) {
-    return { jql: raw, projects };
+    return { jql: raw, projects, plane, workspace: workspaceSlug };
   }
   const projectClause = projects.length ? `project in (${projects.map((p) => `"${p}"`).join(", ")})` : "";
   const clauses = [];
@@ -409,7 +430,10 @@ function parseFlags(flags) {
     clauses.push(`status="${status}"`);
   for (const status of statusNeq)
     clauses.push(`status!="${status}"`);
-  return { jql: clauses.join(" AND "), projects };
+  return { jql: clauses.join(" AND "), projects, plane, workspace: workspaceSlug };
+}
+function wantsPlane(flags) {
+  return parseFlags(flags).plane;
 }
 function flagsToJql(flags) {
   return parseFlags(flags).jql;
@@ -1207,9 +1231,12 @@ function createApp(opts) {
   let childrenRaw = [];
   let hasChildrenCache = false;
   let childrenError;
+  let refreshError;
+  let live = false;
   let targetEndFieldId = readTargetEndFieldMap(fieldMapPath).targetEnd ?? targetEndFieldIdFromJiraConfig(safeRead(jiraConfigPath) ?? "");
+  let workflowStates;
   function boardOpts() {
-    return { targetEndFieldId };
+    return { targetEndFieldId, ...workflowStates?.length ? { statuses: workflowStates } : {} };
   }
   function toBoard(raw) {
     return issuesToBoard(raw, boardOpts());
@@ -1305,11 +1332,13 @@ function createApp(opts) {
       childrenRaw = mergeSelectedChildren(childrenRaw, hydrated, keys);
       hasChildrenCache = true;
       childrenError = undefined;
+      refreshError = undefined;
       return app.board();
     } catch (err) {
       const message = err instanceof Error ? err.message : "Refresh failed";
+      refreshError = message;
       console.error("Refresh failed", message);
-      return { ...app.board(), error: message };
+      return app.board();
     }
   }
   async function tryMove(key, status) {
@@ -1325,12 +1354,21 @@ function createApp(opts) {
       return flags;
     },
     board() {
+      const error = refreshError ?? childrenError;
+      if (!live && (refreshError || opts.liveBackend)) {
+        const empty = toBoard([]);
+        return {
+          columns: empty.columns,
+          epics: [],
+          ...error ? { error } : {}
+        };
+      }
       const board = toBoard(payload);
       return {
         columns: board.columns,
         epics: mergeEpics(toBoard(epicsPayload).epics, board.epics),
         ...hasChildrenCache ? { children: columnsOf(childrenRaw, targetEndFieldId) } : {},
-        ...childrenError ? { error: childrenError } : {}
+        ...error ? { error } : {}
       };
     },
     hydrate(raw, hydrateOpts) {
@@ -1339,6 +1377,8 @@ function createApp(opts) {
       childrenRaw = [];
       hasChildrenCache = false;
       childrenError = undefined;
+      refreshError = undefined;
+      live = false;
       if (hydrateOpts?.fromStore)
         cacheFromStore();
       rememberTargetEndId([...payload, ...epicsPayload, ...childrenRaw]);
@@ -1352,6 +1392,14 @@ function createApp(opts) {
         flags = next;
       console.log("Refresh");
       try {
+        if (cli.states) {
+          try {
+            workflowStates = await cli.states(flags);
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.log(`Refresh states failed; ${message}`);
+          }
+        }
         const issues = await cli.list(flags);
         const epics = await cli.listEpics(flags);
         const listedPayload = JSON.parse(issues);
@@ -1384,11 +1432,14 @@ function createApp(opts) {
         childrenRaw = nextHasCache ? await hydrateRaw(nextChildren) : nextChildren;
         hasChildrenCache = nextHasCache;
         childrenError = nextError;
+        refreshError = undefined;
+        live = true;
         return app.board();
       } catch (err) {
         const message = err instanceof Error ? err.message : "Refresh failed";
+        refreshError = message;
         console.error("Refresh failed", message);
-        return { ...app.board(), error: message };
+        return app.board();
       }
     },
     async children(epic) {
@@ -1458,13 +1509,703 @@ function createApp(opts) {
   return app;
 }
 
+// src/plane.ts
+var DEFAULT_PLANE_HOST = "https://plane.tail48fe8.ts.net";
+var DEFAULT_PLANE_WORKSPACE = "personal";
+var STATE_GROUPS = ["backlog", "unstarted", "started", "completed", "cancelled"];
+function planeHost(env = process.env) {
+  return (env.PLANE_HOST ?? DEFAULT_PLANE_HOST).replace(/\/$/, "");
+}
+function planeWorkspace(flags = "", env = process.env) {
+  return parseFlags(flags).workspace || env.PLANE_WORKSPACE || DEFAULT_PLANE_WORKSPACE;
+}
+function planeApiBase(host) {
+  const trimmed = host.replace(/\/$/, "");
+  if (trimmed.endsWith("/api/v1"))
+    return trimmed;
+  if (trimmed.endsWith("/api"))
+    return `${trimmed}/v1`;
+  return `${trimmed}/api/v1`;
+}
+function planeModuleKey(identifier, moduleId) {
+  const hex = moduleId.replace(/-/g, "").slice(-8);
+  const n = Number.parseInt(hex, 16);
+  return `${identifier.toUpperCase()}M-${Number.isFinite(n) ? n : 0}`;
+}
+function planeWorkItemKey(identifier, sequenceId) {
+  return `${identifier.toUpperCase()}-${sequenceId}`;
+}
+function titleCasePriority(value) {
+  if (!value || value.toLowerCase() === "none")
+    return;
+  return value.charAt(0).toUpperCase() + value.slice(1).toLowerCase();
+}
+function moduleStatusName(status) {
+  switch ((status ?? "").toLowerCase()) {
+    case "backlog":
+      return "Backlog";
+    case "unstarted":
+    case "planned":
+      return "Todo";
+    case "started":
+    case "in_progress":
+      return "In Progress";
+    case "paused":
+      return "Paused";
+    case "completed":
+      return "Done";
+    case "cancelled":
+    case "canceled":
+      return "Cancelled";
+    default:
+      return status?.trim() || "Todo";
+  }
+}
+function orderStateNames(states) {
+  const seen = new Set;
+  const names = [];
+  const sorted = [...states].sort((a, b) => {
+    const groupA = STATE_GROUPS.indexOf((a.group ?? "").toLowerCase());
+    const groupB = STATE_GROUPS.indexOf((b.group ?? "").toLowerCase());
+    const group = (groupA === -1 ? 99 : groupA) - (groupB === -1 ? 99 : groupB);
+    if (group)
+      return group;
+    return (a.sequence ?? 0) - (b.sequence ?? 0);
+  });
+  for (const state of sorted) {
+    const name = state.name.trim();
+    if (!name || seen.has(name))
+      continue;
+    seen.add(name);
+    names.push(name);
+  }
+  return names;
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function asString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function asId(value) {
+  if (typeof value === "string" && value.trim())
+    return value.trim();
+  const row = asRecord(value);
+  return asString(row?.id);
+}
+function named(value) {
+  const row = asRecord(value);
+  return asString(row?.name) ?? asString(row?.display_name) ?? asString(row?.displayName);
+}
+function stateNameOf(item, states) {
+  const expanded = named(item.state);
+  if (expanded)
+    return expanded;
+  const id = asId(item.state);
+  if (id && states.get(id)?.name)
+    return states.get(id).name;
+  return;
+}
+function labelNamesOf(item, labels) {
+  const raw = [
+    ...Array.isArray(item.label_details) ? item.label_details : [],
+    ...Array.isArray(item.labels) ? item.labels : []
+  ];
+  const names = new Set;
+  for (const entry of raw) {
+    const fromName = named(entry) ?? asString(entry);
+    if (fromName && !labels.has(fromName)) {
+      names.add(fromName);
+      continue;
+    }
+    const id = asId(entry);
+    const mapped = id ? labels.get(id)?.name : undefined;
+    if (mapped)
+      names.add(mapped);
+  }
+  return [...names];
+}
+function assigneeOf(item) {
+  const raw = Array.isArray(item.assignee_details) ? item.assignee_details : Array.isArray(item.assignees) ? item.assignees : [];
+  for (const entry of raw) {
+    const name = named(entry) ?? asString(asRecord(entry)?.email) ?? asString(asRecord(entry)?.first_name);
+    if (name)
+      return name;
+  }
+  return;
+}
+function moduleIdsOf(item) {
+  const ids = new Set;
+  for (const entry of [
+    ...Array.isArray(item.module_ids) ? item.module_ids : [],
+    ...Array.isArray(item.modules) ? item.modules : [],
+    item.module
+  ]) {
+    const id = asId(entry);
+    if (id)
+      ids.add(id);
+  }
+  return [...ids];
+}
+function descriptionOf(item) {
+  return asString(item.description_stripped) ?? asString(item.description) ?? (asString(item.description_html) ? asString(item.description_html).replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim() : undefined);
+}
+function workItemToIssue(item, project, opts) {
+  if (item.archived_at || item.is_draft)
+    return;
+  const sequence = Number(item.sequence_id);
+  if (!Number.isFinite(sequence))
+    return;
+  const status = stateNameOf(item, opts.states);
+  if (!status)
+    return;
+  const key = planeWorkItemKey(project.identifier, sequence);
+  const priority = titleCasePriority(item.priority);
+  const assignee = assigneeOf(item);
+  const labels = labelNamesOf(item, opts.labels);
+  const description = descriptionOf(item);
+  const target = asString(item.target_date);
+  return {
+    key,
+    fields: {
+      summary: asString(item.name) ?? "",
+      status: { name: status },
+      ...priority ? { priority: { name: priority } } : {},
+      ...assignee ? { assignee: { displayName: assignee } } : {},
+      ...target ? { duedate: target, "Target End Date": target } : {},
+      issuetype: { name: "Story" },
+      issueType: { name: "Story" },
+      ...opts.moduleKey ? { parent: { key: opts.moduleKey } } : {},
+      ...labels.length ? { labels } : {},
+      ...asString(item.created_at) ? { created: item.created_at } : {},
+      ...description ? { description } : {}
+    }
+  };
+}
+function moduleToIssue(module, project) {
+  const target = asString(module.target_date);
+  return {
+    key: planeModuleKey(project.identifier, module.id),
+    fields: {
+      summary: asString(module.name) ?? module.id,
+      status: { name: moduleStatusName(module.status) },
+      issuetype: { name: "Epic" },
+      issueType: { name: "Epic" },
+      ...target ? { duedate: target, "Target End Date": target } : {},
+      ...asString(module.created_at) ? { created: module.created_at } : {}
+    }
+  };
+}
+function joinUrl(base, path) {
+  if (path.startsWith("http://") || path.startsWith("https://"))
+    return path;
+  const suffix = path.startsWith("/") ? path : `/${path}`;
+  return `${base}${suffix}`;
+}
+function queryPath(path, query) {
+  const params = new URLSearchParams;
+  for (const [key, value] of Object.entries(query)) {
+    if (value)
+      params.set(key, value);
+  }
+  const encoded = params.toString();
+  if (!encoded)
+    return path;
+  return `${path}${path.includes("?") ? "&" : "?"}${encoded}`;
+}
+function rateLimitWaitMs(headers, nowMs, on429) {
+  const retryAfter = headers.get("Retry-After");
+  if (retryAfter) {
+    const seconds = Number(retryAfter.trim());
+    if (Number.isFinite(seconds) && seconds >= 0)
+      return seconds * 1000;
+    const parsed = Date.parse(retryAfter);
+    if (!Number.isNaN(parsed))
+      return Math.max(0, parsed - nowMs);
+  }
+  const reset = headers.get("X-RateLimit-Reset");
+  if (reset) {
+    const n = Number(reset.trim());
+    if (Number.isFinite(n)) {
+      const resetMs = n < 1000000000000 ? n * 1000 : n;
+      return Math.max(0, resetMs - nowMs);
+    }
+  }
+  if (on429)
+    return 60000;
+  if (headers.get("X-RateLimit-Remaining")?.trim() === "0")
+    return 60000;
+  return 0;
+}
+function errorMessage(status, body) {
+  try {
+    const parsed = JSON.parse(body);
+    const detail = asString(parsed.detail) ?? asString(parsed.error) ?? asString(parsed.message) ?? (Array.isArray(parsed.non_field_errors) ? asString(parsed.non_field_errors[0]) : undefined);
+    if (detail)
+      return `Plane ${status}: ${detail}`;
+  } catch {}
+  const snippet = body.replace(/\s+/g, " ").trim().slice(0, 240);
+  return snippet ? `Plane ${status}: ${snippet}` : `Plane ${status}`;
+}
+function htmlParagraph(text) {
+  const escaped = text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return `<p>${escaped}</p>`;
+}
+function createPlaneCli(opts) {
+  if (!opts.apiKey.trim()) {
+    throw new Error("Plane mode needs PLANE_API_KEY");
+  }
+  const host = (opts.host ?? DEFAULT_PLANE_HOST).replace(/\/$/, "");
+  const apiBase = planeApiBase(host);
+  const defaultFlags = opts.flags ?? DEFAULT_FLAGS;
+  const fetchFn = opts.fetch ?? fetch;
+  const nowFn = opts.now ?? Date.now;
+  const sleepFn = opts.sleep ?? ((ms) => ms <= 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, ms)));
+  let lastFlags = defaultFlags;
+  let workItemResource = "work-items";
+  let catalog;
+  function workspaceOf(flags) {
+    return planeWorkspace(flags || defaultFlags);
+  }
+  let notBefore = 0;
+  let gate = Promise.resolve();
+  function locked(fn) {
+    const run = gate.then(fn, fn);
+    gate = run.then(() => {
+      return;
+    }, () => {
+      return;
+    });
+    return run;
+  }
+  function fail(status, body) {
+    const error = new Error(errorMessage(status, body));
+    error.status = status;
+    throw error;
+  }
+  function noteHeaders(headers, status) {
+    const remaining = headers.get("X-RateLimit-Remaining")?.trim();
+    if (status !== 429 && remaining !== "0")
+      return;
+    const wait = rateLimitWaitMs(headers, nowFn(), status === 429);
+    notBefore = Math.max(notBefore, nowFn() + wait);
+  }
+  async function request(path, init = {}) {
+    return locked(async () => {
+      let retried = false;
+      while (true) {
+        const headers = new Headers(init.headers);
+        headers.set("X-API-Key", opts.apiKey);
+        if (init.body && !headers.has("content-type")) {
+          headers.set("content-type", "application/json");
+        }
+        const delay = notBefore - nowFn();
+        if (delay > 0)
+          await sleepFn(delay);
+        const response = await fetchFn(joinUrl(apiBase, path), { ...init, headers });
+        const body = await response.text();
+        noteHeaders(response.headers, response.status);
+        if (response.status === 429) {
+          if (retried)
+            fail(response.status, body);
+          retried = true;
+          continue;
+        }
+        if (!response.ok)
+          fail(response.status, body);
+        return { status: response.status, body };
+      }
+    });
+  }
+  async function requestJson(path, init) {
+    const { body } = await request(path, init);
+    if (!body.trim())
+      return null;
+    return JSON.parse(body);
+  }
+  function asPages(raw) {
+    if (Array.isArray(raw))
+      return raw;
+    const row = asRecord(raw);
+    return Array.isArray(row?.results) ? row.results : [];
+  }
+  async function paginate(path) {
+    const items = [];
+    let cursor;
+    for (let page = 0;page < 50; page++) {
+      const url = queryPath(path, { per_page: "100", ...cursor ? { cursor } : {} });
+      const raw = await requestJson(url);
+      if (Array.isArray(raw) && page === 0 && !asRecord(raw)) {
+        return raw;
+      }
+      const row = asRecord(raw);
+      const chunk = asPages(raw);
+      items.push(...chunk);
+      if (!row?.next_page_results)
+        break;
+      const next = asString(row.next_cursor);
+      if (!next || next === cursor)
+        break;
+      cursor = next;
+    }
+    return items;
+  }
+  async function withResource(run) {
+    try {
+      return await run(workItemResource);
+    } catch (err) {
+      const status = err.status;
+      if (workItemResource === "work-items" && status === 404) {
+        workItemResource = "issues";
+        return run(workItemResource);
+      }
+      throw err;
+    }
+  }
+  function scopedProjects(all, flags) {
+    const { projects } = parseFlags(flags || defaultFlags);
+    if (!projects.length)
+      return all;
+    const wanted = new Set(projects);
+    return all.filter((project) => wanted.has(project.identifier.toUpperCase()));
+  }
+  function parseProject(raw) {
+    const row = asRecord(raw);
+    const id = asString(row?.id);
+    const identifier = asString(row?.identifier)?.toUpperCase();
+    if (!id || !identifier)
+      return;
+    return { id, identifier, name: asString(row?.name) ?? identifier };
+  }
+  function parseState(raw) {
+    const row = asRecord(raw);
+    const id = asString(row?.id);
+    const name = asString(row?.name);
+    if (!id || !name)
+      return;
+    return {
+      id,
+      name,
+      group: asString(row?.group),
+      sequence: typeof row?.sequence === "number" ? row.sequence : undefined
+    };
+  }
+  function parseLabel(raw) {
+    const row = asRecord(raw);
+    const id = asString(row?.id);
+    const name = asString(row?.name);
+    if (!id || !name)
+      return;
+    return { id, name };
+  }
+  function parseModule(raw) {
+    const row = asRecord(raw);
+    const id = asString(row?.id);
+    if (!id)
+      return;
+    return {
+      id,
+      name: asString(row?.name) ?? id,
+      status: asString(row?.status),
+      created_at: asString(row?.created_at),
+      target_date: asString(row?.target_date),
+      start_date: asString(row?.start_date)
+    };
+  }
+  async function loadCatalog(flags) {
+    lastFlags = flags || defaultFlags;
+    const workspace = workspaceOf(lastFlags);
+    if (catalog && catalog.flags === lastFlags && catalog.workspace === workspace)
+      return catalog;
+    const projects = scopedProjects((await paginate(`/workspaces/${workspace}/projects/`)).map(parseProject).filter((row) => !!row), lastFlags);
+    const states = new Map;
+    const labels = new Map;
+    const works = new Map;
+    const modules = new Map;
+    const columnStates = [];
+    for (const project of projects) {
+      const stateRows = await paginate(`/workspaces/${workspace}/projects/${project.id}/states/`);
+      const labelRows = await paginate(`/workspaces/${workspace}/projects/${project.id}/labels/`);
+      const moduleRows = await paginate(`/workspaces/${workspace}/projects/${project.id}/modules/`);
+      const workRows = await withResource((resource) => paginate(queryPath(`/workspaces/${workspace}/projects/${project.id}/${resource}/`, {
+        expand: "assignees,labels,state,module"
+      })));
+      const stateById = new Map;
+      for (const row of stateRows) {
+        const state = parseState(row);
+        if (!state)
+          continue;
+        stateById.set(state.id, state);
+        columnStates.push(state);
+      }
+      const labelById = new Map;
+      for (const row of labelRows) {
+        const label = parseLabel(row);
+        if (label)
+          labelById.set(label.id, label);
+      }
+      const moduleById = new Map;
+      for (const row of moduleRows) {
+        const module = parseModule(row);
+        if (!module)
+          continue;
+        const issue = moduleToIssue(module, project);
+        const cached = { issue, module, project };
+        moduleById.set(module.id, cached);
+        modules.set(String(issue.key), cached);
+      }
+      states.set(project.id, stateById);
+      labels.set(project.id, labelById);
+      const workItems = workRows;
+      const missingModules = moduleById.size > 0 && workItems.some((item) => item.module_ids == null && item.modules == null && item.module == null);
+      const issueByModule = new Map;
+      if (missingModules && moduleById.size) {
+        for (const moduleId of moduleById.keys()) {
+          const rows = await paginate(`/workspaces/${workspace}/projects/${project.id}/modules/${moduleId}/module-issues/`);
+          const ids = rows.map((row) => asId(asRecord(row)?.issue) ?? asId(row)).filter((id) => !!id);
+          issueByModule.set(moduleId, ids);
+        }
+      }
+      for (const raw of workItems) {
+        const item = raw;
+        const fromItem = moduleIdsOf(item)[0];
+        const fromJoin = [...issueByModule.entries()].find(([, ids]) => ids.includes(item.id))?.[0];
+        const moduleId = fromItem ?? fromJoin;
+        const moduleKey = moduleId ? moduleById.get(moduleId)?.issue.key : undefined;
+        const issue = workItemToIssue(item, project, {
+          states: stateById,
+          labels: labelById,
+          moduleKey: typeof moduleKey === "string" ? moduleKey : undefined
+        });
+        const issueKey = typeof issue?.key === "string" ? issue.key : undefined;
+        if (!issue || !issueKey)
+          continue;
+        works.set(issueKey, {
+          issue,
+          item,
+          project,
+          ...typeof moduleKey === "string" ? { moduleKey } : {}
+        });
+      }
+    }
+    catalog = {
+      flags: lastFlags,
+      workspace,
+      projects,
+      states,
+      labels,
+      works,
+      modules,
+      columns: orderStateNames(columnStates)
+    };
+    return catalog;
+  }
+  function filterWorks(flags, works) {
+    const parsed = parseFlags(flags || defaultFlags);
+    return works.filter(({ issue }) => {
+      const status = typeof issue.fields?.status?.name === "string" ? issue.fields.status.name : "";
+      const type = typeof issue.fields?.issuetype?.name === "string" ? issue.fields.issuetype.name : "";
+      const parent = asString(asRecord(issue.fields?.parent)?.key);
+      const assignee = asString(asRecord(issue.fields?.assignee)?.displayName);
+      if (parsed.jql.includes("type=") && !parsed.jql.includes('type="Epic"')) {
+        const wanted = /type="([^"]+)"/.exec(parsed.jql)?.[1];
+        if (wanted && wanted.toLowerCase() !== type.toLowerCase())
+          return false;
+      }
+      const statusEq = [...parsed.jql.matchAll(/status="([^"]+)"/g)].map((match) => match[1]);
+      const statusNeq = [...parsed.jql.matchAll(/status!="([^"]+)"/g)].map((match) => match[1]);
+      if (statusEq.length && !statusEq.some((name) => name.toLowerCase() === status.toLowerCase())) {
+        return false;
+      }
+      if (statusNeq.some((name) => name.toLowerCase() === status.toLowerCase()))
+        return false;
+      const assigneeWanted = /assignee="([^"]+)"/.exec(parsed.jql)?.[1];
+      if (assigneeWanted && assigneeWanted.toLowerCase() !== (assignee ?? "").toLowerCase()) {
+        return false;
+      }
+      const parentWanted = /parent="([^"]+)"/.exec(parsed.jql)?.[1];
+      if (parentWanted && parentWanted !== parent)
+        return false;
+      return true;
+    });
+  }
+  async function lookupByKey(key, flags) {
+    const loaded = await loadCatalog(flags);
+    const cached = loaded.works.get(key);
+    if (cached)
+      return cached;
+    if (loaded.modules.has(key))
+      return;
+    const raw = await withResource((resource) => requestJson(`/workspaces/${loaded.workspace}/${resource}/${key}/`));
+    const row = asRecord(raw);
+    if (!row)
+      return;
+    const project = loaded.projects.find((item) => item.id === asString(row.project)) ?? loaded.projects.find((item) => key.toUpperCase().startsWith(`${item.identifier}-`));
+    if (!project)
+      return;
+    const stateById = loaded.states.get(project.id) ?? new Map;
+    const labelById = loaded.labels.get(project.id) ?? new Map;
+    const item = raw;
+    const issue = workItemToIssue(item, project, { states: stateById, labels: labelById });
+    const issueKey = typeof issue?.key === "string" ? issue.key : undefined;
+    if (!issue || !issueKey)
+      return;
+    const next = { issue, item, project };
+    loaded.works.set(issueKey, next);
+    return next;
+  }
+  async function resolveLabelIds(project, names, flags) {
+    if (!names?.length)
+      return [];
+    const loaded = await loadCatalog(flags);
+    const byName = new Map([...loaded.labels.get(project.id)?.values() ?? []].map((label) => [label.name.toLowerCase(), label.id]));
+    return names.map((name) => byName.get(name.toLowerCase())).filter((id) => !!id);
+  }
+  async function resolveStateId(project, status, flags) {
+    const loaded = await loadCatalog(flags);
+    const states = [...loaded.states.get(project.id)?.values() ?? []];
+    return states.find((state) => state.name.toLowerCase() === status.toLowerCase())?.id;
+  }
+  return {
+    async list(flags) {
+      const query = flags || defaultFlags;
+      const loaded = await loadCatalog(query);
+      const issues = filterWorks(query, [...loaded.works.values()]).map((row) => row.issue);
+      return JSON.stringify(issues);
+    },
+    async listEpics(queryFlags = defaultFlags) {
+      const loaded = await loadCatalog(queryFlags || defaultFlags);
+      return JSON.stringify([...loaded.modules.values()].map((row) => row.issue));
+    },
+    async listEpic(key, queryFlags = defaultFlags) {
+      const loaded = await loadCatalog(queryFlags || defaultFlags);
+      const issues = [...loaded.works.values()].filter((row) => row.moduleKey === key).map((row) => row.issue);
+      return JSON.stringify(issues);
+    },
+    async listChildren(keys) {
+      const loaded = await loadCatalog(lastFlags);
+      const wanted = new Set(keys);
+      const issues = [...loaded.works.values()].filter((row) => row.moduleKey && wanted.has(row.moduleKey)).map((row) => row.issue);
+      return JSON.stringify(issues);
+    },
+    async states(flags) {
+      const loaded = await loadCatalog(flags || defaultFlags);
+      return loaded.columns;
+    },
+    async move(key, status) {
+      try {
+        const module = (await loadCatalog(lastFlags)).modules.get(key);
+        if (module) {
+          const mapped = Object.entries({
+            backlog: "backlog",
+            todo: "planned",
+            "to do": "planned",
+            "in progress": "in_progress",
+            paused: "paused",
+            done: "completed",
+            completed: "completed",
+            cancelled: "cancelled",
+            canceled: "cancelled"
+          }).find(([name]) => name === status.toLowerCase())?.[1];
+          if (!mapped)
+            return { ok: false, error: `Unknown Plane module status "${status}"` };
+          await request(`/workspaces/${workspaceOf(lastFlags)}/projects/${module.project.id}/modules/${module.module.id}/`, { method: "PATCH", body: JSON.stringify({ status: mapped }) });
+          catalog = undefined;
+          return { ok: true };
+        }
+        const work = await lookupByKey(key, lastFlags);
+        if (!work)
+          return { ok: false, error: `Work item ${key} not found` };
+        const state = await resolveStateId(work.project, status, lastFlags);
+        if (!state)
+          return { ok: false, error: `Unknown Plane state "${status}" for ${key}` };
+        await withResource((resource) => request(`/workspaces/${workspaceOf(lastFlags)}/projects/${work.project.id}/${resource}/${work.item.id}/`, { method: "PATCH", body: JSON.stringify({ state }) }));
+        catalog = undefined;
+        return { ok: true };
+      } catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+    async create(input) {
+      try {
+        const loaded = await loadCatalog(lastFlags);
+        const parent = input.parent ? loaded.modules.get(input.parent) : undefined;
+        const project = parent?.project ?? loaded.projects[0];
+        if (!project)
+          return { ok: false, error: "No Plane project in Scope" };
+        const state = input.status?.trim() ? await resolveStateId(project, input.status.trim(), lastFlags) : undefined;
+        const labels = await resolveLabelIds(project, input.labels, lastFlags);
+        const body = { name: input.summary };
+        if (input.description)
+          body.description_html = htmlParagraph(input.description);
+        if (state)
+          body.state = state;
+        if (labels.length)
+          body.labels = labels;
+        const created = asRecord(await withResource((resource) => requestJson(`/workspaces/${workspaceOf(lastFlags)}/projects/${project.id}/${resource}/`, {
+          method: "POST",
+          body: JSON.stringify(body)
+        })));
+        const sequence = Number(created?.sequence_id);
+        const key = Number.isFinite(sequence) && sequence > 0 ? planeWorkItemKey(project.identifier, sequence) : undefined;
+        if (parent && created?.id) {
+          await request(`/workspaces/${workspaceOf(lastFlags)}/projects/${project.id}/modules/${parent.module.id}/module-issues/`, { method: "POST", body: JSON.stringify({ issues: [created.id] }) });
+        }
+        catalog = undefined;
+        return key ? { ok: true, key } : { ok: true };
+      } catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+    async edit(key, input) {
+      try {
+        const work = await lookupByKey(key, lastFlags);
+        if (!work)
+          return { ok: false, error: `Work item ${key} not found` };
+        const body = {};
+        if (input.summary !== undefined)
+          body.name = input.summary;
+        if (input.description !== undefined)
+          body.description_html = htmlParagraph(input.description);
+        if (input.labels)
+          body.labels = await resolveLabelIds(work.project, input.labels, lastFlags);
+        await withResource((resource) => request(`/workspaces/${workspaceOf(lastFlags)}/projects/${work.project.id}/${resource}/${work.item.id}/`, { method: "PATCH", body: JSON.stringify(body) }));
+        catalog = undefined;
+        return { ok: true };
+      } catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+    async open(key) {
+      return `${host}/${workspaceOf(lastFlags)}/browse/${key}`;
+    },
+    async view(key) {
+      const loaded = await loadCatalog(lastFlags);
+      const module = loaded.modules.get(key);
+      if (module)
+        return JSON.stringify(module.issue);
+      const work = await lookupByKey(key, lastFlags);
+      if (work)
+        return JSON.stringify(work.issue);
+      throw new Error(`Work item ${key} not found`);
+    }
+  };
+}
+
 // src/boot.ts
 async function createBoardApp(opts) {
   const env = opts.env ?? process.env;
   const flags = opts.flags ?? "";
   const store = IssueStore.fromRaw(opts.raw);
+  const plane = wantsPlane(flags);
   const bin = resolveJiraBin(env.JIRA_BIN ?? "jira", env.PATH ?? "");
-  const cli = bin ? createJiraCli({
+  const cli = plane ? createPlaneCli({
+    host: planeHost(env),
+    apiKey: env.PLANE_API_KEY ?? "",
+    workspace: planeWorkspace(flags, env),
+    flags,
+    fetch: opts.fetch
+  }) : bin ? createJiraCli({
     bin,
     configPath: env.JIRA_CONFIG_FILE,
     token: env.JIRA_API_TOKEN,
@@ -1474,7 +2215,8 @@ async function createBoardApp(opts) {
     store,
     cli,
     flags,
-    jiraConfigPath: jiraCliConfigPath(env)
+    jiraConfigPath: jiraCliConfigPath(env),
+    liveBackend: plane
   });
   if (opts.piped) {
     app.hydrate(opts.raw);
@@ -1482,10 +2224,12 @@ async function createBoardApp(opts) {
     const local = createStoreCli(store, flags);
     app.hydrate(JSON.parse(await local.list(app.flags)), { fromStore: true });
   }
-  return { app, store, kind: bin ? "jira" : "store" };
+  return { app, store, kind: plane ? "plane" : bin ? "jira" : "store" };
 }
 async function refreshFromJira(app, kind, opts = {}) {
-  if (kind !== "jira" || opts.piped)
+  if (opts.piped)
+    return;
+  if (kind !== "jira" && kind !== "plane")
     return;
   await app.refresh();
 }
@@ -12563,7 +13307,11 @@ function handleFakeJira(req, res, store) {
 
 // src/http.ts
 function handleRequest(req, res, ctx) {
-  return handleAppApi(req, res, ctx.app) || handleAgentApi(req, res, ctx.app) || handleFakeJira(req, res, ctx.store);
+  if (handleAppApi(req, res, ctx.app) || handleAgentApi(req, res, ctx.app))
+    return true;
+  if (ctx.kind === "plane")
+    return false;
+  return handleFakeJira(req, res, ctx.store);
 }
 
 // src/jira-config.ts
@@ -12682,7 +13430,7 @@ async function runServer(opts) {
     flags
   });
   const server = createServer((req, res) => {
-    if (handleRequest(req, res, { app, store }))
+    if (handleRequest(req, res, { app, store, kind }))
       return;
     if (opts.fallback) {
       opts.fallback(req, res);
@@ -12693,19 +13441,34 @@ async function runServer(opts) {
       res.end("pipe-kan UI is missing. Run bun run build.");
     }
   });
+  if (kind === "plane") {
+    try {
+      await refreshFromJira(app, kind, { piped: Boolean(piped) });
+    } catch (err) {
+      console.error(`${kind} Refresh failed`, err);
+    }
+    const error = app.board().error;
+    if (error)
+      console.error(`${kind} Refresh failed; keeping last live Board`, error);
+  }
   const { host, port } = resolveListen();
   await bindListen(server, host, port);
   const origin = `http://127.0.0.1:${port}`;
-  const fakeConfig = writeJiraConfig(join10(tmpdir3(), "pipe-kan"), origin);
   announce(`pipe-kan http://${host}:${port}`);
-  announce(`cli ${kind === "jira" ? resolveJiraBin() : "store"}`);
-  announce(`Fake Jira ${origin}/rest/api/2/search`);
-  announce(`Fake Jira config ${fakeConfig}`);
+  if (kind === "plane") {
+    announce(`cli plane ${planeHost()} ${planeWorkspace(flags)}`);
+    announce(`Plane host default ${DEFAULT_PLANE_HOST}`);
+  } else {
+    const fakeConfig = writeJiraConfig(join10(tmpdir3(), "pipe-kan"), origin);
+    announce(`cli ${kind === "jira" ? resolveJiraBin() : "store"}`);
+    announce(`Fake Jira ${origin}/rest/api/2/search`);
+    announce(`Fake Jira config ${fakeConfig}`);
+  }
   if (kind === "jira") {
     try {
       await refreshFromJira(app, kind, { piped: Boolean(piped) });
     } catch (err) {
-      console.error("jira Refresh failed; keeping Fixture Board");
+      console.error(`${kind} Refresh failed; keeping Fixture Board`);
       console.error(err);
     }
   }