@kud/jira-ink 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erwann Mest
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @kud/jira-ink
+
+Controlled [Ink](https://github.com/vadimdemedes/ink) components for viewing
+Jira issues in the terminal — the issue detail screen, extracted from
+[`@kud/jira-cli`](https://github.com/kud/jira-cli)'s TUI so it can be shared
+with ambre's cockpit.
+
+Every component is **presentation-only**: props in, no data fetching, no
+app-level input. The consuming surface owns selection, navigation and loading,
+so the same components drop into a full-screen CLI or a single pane inside a
+larger dashboard. Data comes from [`@kud/jira`](https://github.com/kud/jira);
+markdown rendering comes from [`@kud/ink-markdown`](https://github.com/kud/ink-markdown);
+primitives and colour tokens come from [`@kud/ink-ui`](https://github.com/kud/ink-ui).
+
+```
+@kud/jira        headless core — client, types (framework-agnostic)
+└─ @kud/jira-ink  this package — Ink rendering
+```
+
+## Install
+
+```sh
+npm install @kud/jira-ink @kud/jira @kud/ink-ui ink react
+```
+
+`ink` and `react` are peer dependencies.
+
+## Usage
+
+A host with a client and a key mounts the self-fetching body — the shape a cockpit wants:
+
+```tsx
+import { createJiraClient, loadConfig } from "@kud/jira"
+import { IssueBody } from "@kud/jira-ink"
+
+const loaded = loadConfig()
+if ("missing" in loaded) throw new Error(loaded.missing.join(", "))
+const client = createJiraClient(loaded.config)
+
+<IssueBody
+  client={client}
+  baseUrl={loaded.config.baseUrl}
+  issueKey="SHOP-1234"
+  onExit={() => setScreen("list")}
+/>
+```
+
+A host that already holds an `IssueDetail` and owns the prompts behind the write verbs — jira-cli's own TUI — mounts the view directly. A verb whose handler is absent is neither hinted nor bound, so a read-only host gets the same screen minus the keys it cannot honour:
+
+```tsx
+import { IssueDetailView, issueDetailOf } from "@kud/jira-ink"
+
+const issue = await issueDetailOf(client, baseUrl, "SHOP-1234")
+
+<IssueDetailView
+  issue={issue}
+  width={80}
+  height={30}
+  onBack={back}
+  onTransition={transition}
+  onComment={comment}
+  onAssign={assign}
+  onOpenBrowser={open}
+/>
+```
+
+| Export            | What it is                                                               |
+| ----------------- | ------------------------------------------------------------------------ |
+| `IssueBody`       | Self-fetching issue screen: hand it a client and a key, read-only        |
+| `IssueDetailView` | The issue screen over an `IssueDetail`, with optional write verbs        |
+| `issueDetailOf`   | Fetches one issue through a `@kud/jira` client into the view-ready shape |
+| `transitionsOf`   | The issue's available status transitions, `{ id, name, to }`             |
+| `IssueDetail`     | The shape the view reads: strings throughout, ADF already Markdown       |
+## Development
+
+```sh
+npm install
+npm run typecheck
+npm test          # ink-testing-library
+npm run build     # tsup → dist/
+```
+
+## Licence
+
+MIT © Erwann Mest

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import * as react from 'react';
+import { LocatedAttachment, JiraClient } from '@kud/jira';
+
+/**
+ * One issue, as the detail screen reads it: every field already a string, ADF
+ * already Markdown, attachments already located. The view never touches a raw
+ * `JiraIssue`, so a host that fakes a `JiraClient` for a test or a screenshot
+ * gets a screen it can predict, and one that fetched the issue by some other
+ * route can build this shape by hand.
+ */
+type IssueDetail = {
+    key: string;
+    summary: string;
+    status: string;
+    type: string;
+    assignee: string;
+    reporter: string;
+    labels: string[];
+    parent?: {
+        key: string;
+        summary: string;
+    };
+    url: string;
+    description: string;
+    comments: {
+        id: string;
+        author: string;
+        created: string;
+        body: string;
+    }[];
+    attachments: LocatedAttachment[];
+};
+type Transition = {
+    id: string;
+    name: string;
+    to: string;
+};
+declare const issueDetailOf: (client: JiraClient, baseUrl: string, key: string) => Promise<IssueDetail>;
+declare const transitionsOf: (client: JiraClient, key: string) => Promise<Transition[]>;
+
+type IssueDetailViewProps = {
+    issue: IssueDetail;
+    height: number;
+    width: number;
+    onBack: () => void;
+    /**
+     * The write actions are optional, and a key whose handler is absent is
+     * neither bound nor hinted. A host that only READS — cockpit's ticket drill —
+     * mounts the same screen jira-cli's TUI does, minus the verbs it has no way
+     * to honour, rather than a hint row promising `t` and `c` that do nothing.
+     */
+    onTransition?: () => void;
+    onComment?: () => void;
+    onAssign?: () => void;
+    onOpenBrowser?: () => void;
+};
+declare const IssueDetailView: ({ issue, height, width, onBack, onTransition, onComment, onAssign, onOpenBrowser, }: IssueDetailViewProps) => react.JSX.Element;
+
+type IssueBodyProps = {
+    client: JiraClient;
+    /** Instance URL, as `loadConfig` resolves it; only used to build the browser link. */
+    baseUrl: string;
+    issueKey: string;
+    onExit: () => void;
+    /** Override the terminal-derived size when the host draws inside a frame. */
+    width?: number;
+    height?: number;
+};
+/**
+ * The issue screen as a host mounts it: hand it a client and a key, and it
+ * fetches, draws and reads its own keys until `onExit`. `JenkinsBody`'s shape,
+ * for the same reason — a cockpit mounting a ticket over its list should not
+ * have to know how an issue is fetched or what the loading states look like.
+ *
+ * Read-only by construction. The write verbs (`t`, `c`, `a`) exist on
+ * `IssueDetailView` for jira-cli's own TUI, which owns the prompts they need;
+ * here they are simply not wired, so the hint row does not offer them.
+ */
+declare const IssueBody: ({ client, baseUrl, issueKey, onExit, width, height, }: IssueBodyProps) => react.JSX.Element;
+
+export { IssueBody, type IssueBodyProps, type IssueDetail, IssueDetailView, type IssueDetailViewProps, type Transition, issueDetailOf, transitionsOf };

package/dist/index.js

@@ -0,0 +1,203 @@
+import { MarkdownViewport } from '@kud/ink-markdown';
+import { useTabs, KeyValue, Badge, Tabs, FooterHints, LoadingScreen, StatusMessage } from '@kud/ink-ui';
+import { useInput, Box, Text, useStdout } from 'ink';
+import { useState, useEffect } from 'react';
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { exec } from 'child_process';
+import { locateAttachments, adfToMarkdown } from '@kud/jira';
+
+// src/components/issue-detail-view.tsx
+var truncate = (s, max) => s.length <= max ? s : `${s.slice(0, Math.max(0, max - 1))}\u2026`;
+var originOf = (a) => a.origins.map(
+  (o) => o.kind === "comment" ? `comment by ${o.author ?? "unknown"}` : o.kind === "description" ? "description" : "issue"
+).join(", ");
+var humanSize = (bytes) => {
+  const units = ["B", "KB", "MB", "GB"];
+  const e = Math.min(
+    units.length - 1,
+    Math.floor(Math.log(Math.max(bytes, 1)) / Math.log(1024))
+  );
+  const value = bytes / 1024 ** e;
+  return `${e === 0 ? value : value.toFixed(1)}${units[e]}`;
+};
+var commentsAsMarkdown = (issue) => issue.comments.length === 0 ? "_No comments._" : issue.comments.map((c) => `**${c.author}** \xB7 ${c.created}
+
+${c.body}`).join("\n\n---\n\n");
+var attachmentsAsMarkdown = (issue) => issue.attachments.length === 0 ? "_No attachments._" : issue.attachments.map(
+  (a) => `- \`${a.filename}\` \u2014 ${a.mimeType}, ${humanSize(a.size)}
+  from ${originOf(a)}
+  \`jira attachment read ${issue.key} ${a.filename}\``
+).join("\n");
+var IssueDetailView = ({
+  issue,
+  height,
+  width,
+  onBack,
+  onTransition,
+  onComment,
+  onAssign,
+  onOpenBrowser
+}) => {
+  const tabs = [
+    { value: "description", label: "Description" },
+    { value: "comments", label: "Comments", count: issue.comments.length },
+    {
+      value: "attachments",
+      label: "Attachments",
+      count: issue.attachments.length
+    }
+  ];
+  const { active } = useTabs(tabs, { initial: "description" });
+  const [scroll, setScroll] = useState(0);
+  useInput((input, key) => {
+    if (key.escape || key.leftArrow) return onBack();
+    if (input === "t" && onTransition) return onTransition();
+    if (input === "c" && onComment) return onComment();
+    if (input === "a" && onAssign) return onAssign();
+    if (input === "o" && onOpenBrowser) return onOpenBrowser();
+    if (key.downArrow || input === "j") setScroll((s) => s + 1);
+    if (key.upArrow || input === "k") setScroll((s) => Math.max(0, s - 1));
+  });
+  const source = active === "comments" ? commentsAsMarkdown(issue) : active === "attachments" ? attachmentsAsMarkdown(issue) : issue.description || "_No description._";
+  const bodyHeight = Math.max(3, height - 12);
+  const hints = [
+    ["\u2190\u2192", "section"],
+    ["\u2191\u2193", "scroll"],
+    ...onTransition ? [["t", "transition"]] : [],
+    ...onComment ? [["c", "comment"]] : [],
+    ...onAssign ? [["a", "assign to me"]] : [],
+    ...onOpenBrowser ? [["o", "browser"]] : [],
+    ["esc", "back"]
+  ];
+  return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsxs(Text, { bold: true, children: [
+      issue.key,
+      " ",
+      issue.summary
+    ] }),
+    /* @__PURE__ */ jsxs(Box, { marginTop: 1, flexDirection: "column", children: [
+      issue.parent && /* @__PURE__ */ jsx(
+        KeyValue,
+        {
+          label: "parent",
+          value: `${issue.parent.key}  ${truncate(issue.parent.summary, 60)}`
+        }
+      ),
+      /* @__PURE__ */ jsx(KeyValue, { label: "status", value: /* @__PURE__ */ jsx(Badge, { children: issue.status }) }),
+      /* @__PURE__ */ jsx(KeyValue, { label: "type", value: issue.type }),
+      /* @__PURE__ */ jsx(KeyValue, { label: "assignee", value: issue.assignee }),
+      /* @__PURE__ */ jsx(KeyValue, { label: "reporter", value: issue.reporter }),
+      issue.labels.length > 0 && /* @__PURE__ */ jsx(KeyValue, { label: "labels", value: issue.labels.join(", ") })
+    ] }),
+    /* @__PURE__ */ jsx(Box, { marginTop: 1, children: /* @__PURE__ */ jsx(Tabs, { items: tabs, active: active ?? "description" }) }),
+    /* @__PURE__ */ jsx(Box, { marginTop: 1, children: /* @__PURE__ */ jsx(
+      MarkdownViewport,
+      {
+        source,
+        width: Math.max(20, width - 2),
+        height: bodyHeight,
+        scrollOffset: scroll
+      }
+    ) }),
+    /* @__PURE__ */ jsx(Box, { marginTop: 1, children: /* @__PURE__ */ jsx(FooterHints, { hints }) })
+  ] });
+};
+var issueDetailOf = async (client, baseUrl, key) => {
+  const issue = await client.getIssue(key);
+  const attachments = locateAttachments(issue);
+  const filenameOf = (id) => attachments.find((a) => a.id === id)?.filename;
+  const f = issue.fields;
+  return {
+    key: issue.key,
+    summary: f.summary ?? "",
+    status: f.status?.name ?? "\u2014",
+    type: f.issuetype?.name ?? "\u2014",
+    assignee: f.assignee?.displayName ?? "unassigned",
+    reporter: f.reporter?.displayName ?? "\u2014",
+    labels: f.labels ?? [],
+    parent: f.parent ? { key: f.parent.key, summary: f.parent.fields?.summary ?? "" } : void 0,
+    url: `${baseUrl}/browse/${issue.key}`,
+    description: adfToMarkdown(f.description, filenameOf),
+    comments: (f.comment?.comments ?? []).map((c) => ({
+      id: c.id,
+      author: c.author?.displayName ?? "unknown",
+      created: c.created?.slice(0, 10) ?? "",
+      body: adfToMarkdown(c.body, filenameOf)
+    })),
+    attachments
+  };
+};
+var transitionsOf = async (client, key) => (await client.getTransitions(key)).transitions.map((t) => ({
+  id: t.id,
+  name: t.name,
+  to: t.to?.name ?? t.name
+}));
+var useTermSize = () => {
+  const { stdout } = useStdout();
+  const [size, setSize] = useState({
+    cols: stdout.columns || 80,
+    rows: stdout.rows || 24
+  });
+  useEffect(() => {
+    const onResize = () => setSize({ cols: stdout.columns || 80, rows: stdout.rows || 24 });
+    stdout.on("resize", onResize);
+    return () => {
+      stdout.off("resize", onResize);
+    };
+  }, [stdout]);
+  return size;
+};
+var openInBrowser = (url) => {
+  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  exec(`${opener} "${url}"`);
+};
+var IssueBody = ({
+  client,
+  baseUrl,
+  issueKey,
+  onExit,
+  width,
+  height
+}) => {
+  const term = useTermSize();
+  const [state, setState] = useState({ phase: "loading" });
+  useEffect(() => {
+    let live = true;
+    setState({ phase: "loading" });
+    issueDetailOf(client, baseUrl, issueKey).then((issue) => live && setState({ phase: "ready", issue })).catch(
+      (e) => live && setState({
+        phase: "error",
+        message: e instanceof Error ? e.message : String(e)
+      })
+    );
+    return () => {
+      live = false;
+    };
+  }, [client, baseUrl, issueKey]);
+  useInput(
+    (_input, key) => {
+      if (key.escape) onExit();
+    },
+    { isActive: state.phase !== "ready" }
+  );
+  if (state.phase === "loading")
+    return /* @__PURE__ */ jsx(LoadingScreen, { label: `Loading ${issueKey}\u2026` });
+  if (state.phase === "error")
+    return /* @__PURE__ */ jsx(Box, { flexDirection: "column", children: /* @__PURE__ */ jsxs(StatusMessage, { variant: "error", children: [
+      issueKey,
+      ": ",
+      state.message
+    ] }) });
+  return /* @__PURE__ */ jsx(
+    IssueDetailView,
+    {
+      issue: state.issue,
+      width: width ?? term.cols,
+      height: height ?? term.rows,
+      onBack: onExit,
+      onOpenBrowser: () => openInBrowser(state.issue.url)
+    }
+  );
+};
+
+export { IssueBody, IssueDetailView, issueDetailOf, transitionsOf };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@kud/jira-ink",
+  "version": "0.1.0",
+  "description": "Ink components for viewing Jira issues: the issue detail screen, shared by jira-cli's TUI and cockpit",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "ink": ">=7",
+    "react": ">=19"
+  },
+  "dependencies": {
+    "@kud/ink-ui": "0.25.0",
+    "@kud/ink-markdown": "0.1.1",
+    "@kud/jira": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.5.0",
+    "@types/react": "19.2.18",
+    "ink": "7.1.1",
+    "ink-testing-library": "4.0.0",
+    "react": "19.2.8",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "5.0.0"
+  },
+  "keywords": [
+    "jira",
+    "ink",
+    "react",
+    "terminal",
+    "tui",
+    "components",
+    "kud"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kud/jira-ink"
+  }
+}