pipe-kan 0.30.0 → 0.31.0

package/README.md

@@ -12,7 +12,7 @@ npx pipe-kan
 
 Opens `http://127.0.0.1:5173`. No clone, no `bun install`. `bunx` / `npx` installs the published package into a cache and runs it.
 
-First paint is the Fixture. If `jira` is on PATH, the process then Refresh-es from your existing `jira init`. If not, Refresh, Move, Create, and Edit use the in-process store.
+If `--plane` is set, first paint is live Refresh. A failed live Refresh stays in Plane mode and keeps the last live Board, with the error on the Board. If live Refresh never succeeded, the Fixture is not shown. If `jira` is on PATH and `--plane` is off, first paint is the Fixture, then Refresh from your existing `jira init`. If `jira` is missing and `--plane` is off, first paint is the Fixture and Refresh, Move, Create, and Edit use the in-process store.
 
 The published CLI is on npm. From a clone: `bun run build && bun dist/pipe-kan.js`.
 
@@ -57,7 +57,7 @@ bunx pipe-kan --plane --projects APH,PULSE,PKAN,PUI,DEC
 | `PLANE_API_KEY` | (required in Plane mode) | personal access token (`X-API-Key`) |
 | `PLANE_HOST` | `https://plane.tail48fe8.ts.net` | Plane origin; API is `{host}/api/v1` |
 
-Same `--projects` style as Jira: comma-separated, trimmed, uppercased. The header **Scope flags** field accepts the same string, then **Refresh**.
+Same `--projects` style as Jira: comma-separated, trimmed, uppercased. The header **Scope flags** field accepts the same string, then **Refresh**. In Plane mode a header **Workspace** pill (beside the project-identifier chip) types a slug, writes `--workspace` into Scope flags, and Refresh-confirms all Epics. Jira omits the pill. Next launch still uses argv `--workspace`, else `PLANE_WORKSPACE`, else `personal`.
 
 On Refresh:
 
@@ -68,6 +68,8 @@ On Refresh:
 
 Create and Edit use Plane REST when `--plane` is set. Pulse, Plane Pro, scraping, and SQL workspace moves are out of scope.
 
+A Plane `429 RATE_LIMIT_EXCEEDED` does not fall back to Fake Jira. Plane waits the rate-limit window, then continues.
+
 ## Multiple projects
 
 Default Scope is one Project — jira-cli's `jira init` project. To list more than one Project key:

package/dist/pipe-kan.js

@@ -1231,6 +1231,8 @@ 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() {
@@ -1330,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) {
@@ -1350,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) {
@@ -1364,6 +1377,8 @@ function createApp(opts) {
       childrenRaw = [];
       hasChildrenCache = false;
       childrenError = undefined;
+      refreshError = undefined;
+      live = false;
       if (hydrateOpts?.fromStore)
         cacheFromStore();
       rememberTargetEndId([...payload, ...epicsPayload, ...childrenRaw]);
@@ -1417,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) {
@@ -1486,6 +1504,12 @@ function createApp(opts) {
           error: err instanceof Error ? err.message : "jira issue view failed"
         };
       }
+    },
+    async listWorkspaces() {
+      return cli.listWorkspaces?.() ?? [];
+    },
+    async listProjectIdentifiers(workspace) {
+      return cli.listProjectIdentifiers?.(workspace) ?? [];
     }
   };
   return app;
@@ -1495,7 +1519,6 @@ function createApp(opts) {
 var DEFAULT_PLANE_HOST = "https://plane.tail48fe8.ts.net";
 var DEFAULT_PLANE_WORKSPACE = "personal";
 var STATE_GROUPS = ["backlog", "unstarted", "started", "completed", "cancelled"];
-var RETRY_LIMIT2 = 4;
 function planeHost(env = process.env) {
   return (env.PLANE_HOST ?? DEFAULT_PLANE_HOST).replace(/\/$/, "");
 }
@@ -1696,6 +1719,30 @@ function queryPath(path, query) {
     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);
@@ -1718,33 +1765,63 @@ function createPlaneCli(opts) {
   const apiBase = planeApiBase(host);
   const defaultFlags = opts.flags ?? DEFAULT_FLAGS;
   const fetchFn = opts.fetch ?? fetch;
-  const retryDelayMs = opts.retryDelayMs ?? 1000;
+  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);
   }
-  async function request(path, init = {}, attempt = 0) {
-    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 response = await fetchFn(joinUrl(apiBase, path), { ...init, headers });
-    const body = await response.text();
-    if (response.status === 429 && attempt < RETRY_LIMIT2) {
-      const delay = retryDelayMs * 2 ** attempt;
-      if (retryDelayMs)
-        await new Promise((resolve) => setTimeout(resolve, delay));
-      return request(path, init, attempt + 1);
-    }
-    if (!response.ok) {
-      const error = new Error(errorMessage(response.status, body));
-      error.status = response.status;
-      throw error;
-    }
-    return { status: response.status, body };
+  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);
@@ -1806,6 +1883,19 @@ function createPlaneCli(opts) {
       return;
     return { id, identifier, name: asString(row?.name) ?? identifier };
   }
+  function parseWorkspace(raw) {
+    const row = asRecord(raw);
+    const slug = asString(row?.slug);
+    if (!slug)
+      return;
+    return { id: asString(row?.id) ?? slug, name: asString(row?.name) ?? slug, slug };
+  }
+  function parseWorkspaceList(raw) {
+    const rows = Array.isArray(raw) ? raw : asRecord(raw)?.results;
+    if (!Array.isArray(rows))
+      return;
+    return rows.map(parseWorkspace).filter((row) => !!row);
+  }
   function parseState(raw) {
     const row = asRecord(raw);
     const id = asString(row?.id);
@@ -1853,14 +1943,12 @@ function createPlaneCli(opts) {
     const modules = new Map;
     const columnStates = [];
     for (const project of projects) {
-      const [stateRows, labelRows, moduleRows, workRows] = await Promise.all([
-        paginate(`/workspaces/${workspace}/projects/${project.id}/states/`),
-        paginate(`/workspaces/${workspace}/projects/${project.id}/labels/`),
-        paginate(`/workspaces/${workspace}/projects/${project.id}/modules/`),
-        withResource((resource) => paginate(queryPath(`/workspaces/${workspace}/projects/${project.id}/${resource}/`, {
-          expand: "assignees,labels,state,module"
-        })))
-      ]);
+      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);
@@ -1891,11 +1979,11 @@ function createPlaneCli(opts) {
       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) {
-        await Promise.all([...moduleById.keys()].map(async (moduleId) => {
+        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;
@@ -2023,6 +2111,25 @@ function createPlaneCli(opts) {
       const loaded = await loadCatalog(flags || defaultFlags);
       return loaded.columns;
     },
+    async listWorkspaces() {
+      for (const path of ["/users/me/workspaces/", "/workspaces/"]) {
+        try {
+          return parseWorkspaceList(await requestJson(path)) ?? [];
+        } catch (err) {
+          const status = err.status;
+          if (status === 404 && path === "/users/me/workspaces/")
+            continue;
+          return [];
+        }
+      }
+      return [];
+    },
+    async listProjectIdentifiers(workspace) {
+      const slug = workspace.trim();
+      if (!slug)
+        return [];
+      return (await paginate(`/workspaces/${slug}/projects/`)).map(parseProject).filter((row) => !!row).map((row) => row.identifier);
+    },
     async move(key, status) {
       try {
         const module = (await loadCatalog(lastFlags)).modules.get(key);
@@ -2146,7 +2253,8 @@ async function createBoardApp(opts) {
     store,
     cli,
     flags,
-    jiraConfigPath: jiraCliConfigPath(env)
+    jiraConfigPath: jiraCliConfigPath(env),
+    liveBackend: plane
   });
   if (opts.piped) {
     app.hydrate(opts.raw);
@@ -2189,11 +2297,46 @@ function reply(req, res, work) {
       json(res, 500, { error: message });
   });
 }
-function handleAppApi(req, res, app) {
+async function boardEnvelope(body, kind, flags, env, app) {
+  if (kind !== "plane")
+    return { ...body, kind };
+  const envelope = { ...body, kind, workspace: planeWorkspace(flags, env) };
+  try {
+    const workspaces = await app.listWorkspaces?.();
+    if (workspaces && workspaces.length)
+      return { ...envelope, workspaces };
+  } catch {}
+  return envelope;
+}
+function handleAppApi(req, res, app, opts = {}) {
+  const kind = opts.kind ?? "store";
+  const env = opts.env ?? process.env;
   const url = pathOf(req);
   const method = (req.method ?? "GET").toUpperCase();
   if (url.pathname === "/api/board" && method === "GET") {
-    json(res, 200, { ...app.board(), flags: app.flags });
+    reply(req, res, async () => {
+      json(res, 200, await boardEnvelope({ ...app.board(), flags: app.flags }, kind, app.flags, env, app));
+    });
+    return true;
+  }
+  if (url.pathname === "/api/projects" && method === "GET") {
+    reply(req, res, async () => {
+      if (kind !== "plane") {
+        json(res, 404, { error: "not plane" });
+        return;
+      }
+      const workspace = (url.searchParams.get("workspace") ?? "").trim();
+      if (!workspace) {
+        json(res, 400, { error: "workspace required" });
+        return;
+      }
+      try {
+        json(res, 200, { projects: await app.listProjectIdentifiers?.(workspace) ?? [] });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "catalog failed";
+        json(res, 409, { error: message });
+      }
+    });
     return true;
   }
   if (url.pathname === "/api/refresh" && method === "POST") {
@@ -2205,10 +2348,10 @@ function handleAppApi(req, res, app) {
           json(res, 400, { error: "selected Refresh requires epicKeys" });
           return;
         }
-        json(res, 200, await app.refresh(undefined, { scope: "selected", epicKeys }));
+        json(res, 200, await boardEnvelope(await app.refresh(undefined, { scope: "selected", epicKeys }), kind, app.flags, env, app));
         return;
       }
-      json(res, 200, await app.refresh(body.flags));
+      json(res, 200, await boardEnvelope(await app.refresh(body.flags), kind, app.flags, env, app));
     });
     return true;
   }
@@ -13237,7 +13380,12 @@ 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, { kind: ctx.kind }) || handleAgentApi(req, res, ctx.app)) {
+    return true;
+  }
+  if (ctx.kind === "plane")
+    return false;
+  return handleFakeJira(req, res, ctx.store);
 }
 
 // src/jira-config.ts
@@ -13356,7 +13504,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);
@@ -13367,20 +13515,30 @@ 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}`);
   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" || kind === "plane") {
+  if (kind === "jira") {
     try {
       await refreshFromJira(app, kind, { piped: Boolean(piped) });
     } catch (err) {