@jackwener/opencli 1.8.0 → 1.8.1

package/clis/geogebra/utils.js

@@ -0,0 +1,271 @@
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+
+/**
+ * Shared utilities for GeoGebra adapters.
+ *
+ * GeoGebra Geometry exposes a `ggbApplet` JavaScript API on the page after
+ * the GWT-compiled app initializes. All adapters share the same pattern:
+ * navigate → wait for applet → call API via page.evaluate().
+ */
+
+const GEOGEBRA_URL = 'https://www.geogebra.org/geometry';
+const APPLET_WAIT_MS = 15_000;
+
+export function unwrapBridgeEnvelope(value) {
+  if (value && typeof value === 'object' && 'data' in value && 'session' in value) {
+    return value.data;
+  }
+  return value;
+}
+
+function isPlainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function normalizeLabel(value, label = 'label') {
+  const normalized = String(value ?? '').trim();
+  if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(normalized)) {
+    throw new ArgumentError(`${label} must be an ASCII GeoGebra label like A, B1, or poly_1`);
+  }
+  return normalized;
+}
+
+export function normalizeLabelList(value, label, min, max = Infinity) {
+  const parts = String(value ?? '').split(',').map(s => s.trim()).filter(Boolean);
+  if (parts.length < min || parts.length > max) {
+    throw new ArgumentError(`${label} must contain ${min === max ? min : `${min}-${max}`} comma-separated labels`);
+  }
+  return parts.map((part, idx) => normalizeLabel(part, `${label}[${idx + 1}]`));
+}
+
+export function normalizeNumber(value, label, { defaultValue, positive = false } = {}) {
+  const raw = value == null || value === '' ? defaultValue : value;
+  const number = Number(raw);
+  if (!Number.isFinite(number) || (positive && number <= 0)) {
+    throw new ArgumentError(`${label} must be a ${positive ? 'positive ' : ''}finite number`);
+  }
+  return number;
+}
+
+export function normalizeCoords(value) {
+  const parts = String(value ?? '').split(',').map(s => s.trim());
+  if (parts.length !== 2) {
+    throw new ArgumentError('coords must be in "x,y" format (e.g. "1,2")');
+  }
+  return parts.map((part, idx) => normalizeNumber(part, idx === 0 ? 'x' : 'y'));
+}
+
+export function requireGgbSuccess(result, message) {
+  if (!isPlainObject(result)) {
+    throw new CommandExecutionError(`${message}: malformed GeoGebra result`);
+  }
+  if (!result.ok) {
+    throw new CommandExecutionError(result.error || message);
+  }
+  return result;
+}
+
+/**
+ * Navigate to GeoGebra Geometry (if not already there) and wait for
+ * the ggbApplet API to become available.
+ */
+export async function ensureApplet(page) {
+  let currentUrl = '';
+  try {
+    currentUrl = await page.getCurrentUrl();
+  } catch {
+    currentUrl = '';
+  }
+  // If already on the geometry page, check if applet is ready without re-navigating
+  if (currentUrl?.includes('geogebra.org/geometry')) {
+    try {
+      const ready = unwrapBridgeEnvelope(await page.evaluate(`typeof ggbApplet !== 'undefined' && typeof ggbApplet.evalCommand === 'function'`));
+      if (ready) return;
+    } catch (err) {
+      throw new CommandExecutionError(`Failed to detect GeoGebra applet: ${err?.message || err}`);
+    }
+  }
+  // Navigate to GeoGebra Geometry
+  try {
+    await page.goto(GEOGEBRA_URL);
+  } catch (err) {
+    throw new CommandExecutionError(`Failed to load GeoGebra Geometry: ${err?.message || err}`);
+  }
+
+  let ready;
+  try {
+    ready = unwrapBridgeEnvelope(await page.evaluate(`
+      (async () => {
+        const deadline = Date.now() + ${APPLET_WAIT_MS};
+        while (Date.now() < deadline) {
+          if (typeof ggbApplet !== 'undefined' && typeof ggbApplet.evalCommand === 'function') {
+            return true;
+          }
+          await new Promise(r => setTimeout(r, 500));
+        }
+        return false;
+      })()
+    `));
+  } catch (err) {
+    throw new CommandExecutionError(`Failed to detect GeoGebra applet: ${err?.message || err}`);
+  }
+  if (ready !== true) {
+    throw new CommandExecutionError('ggbApplet not available after waiting. Make sure the GeoGebra Geometry page is fully loaded.');
+  }
+}
+
+/**
+ * Execute a GeoGebra command string via ggbApplet.evalCommandGetLabels.
+ * evalCommandGetLabels both executes the command and returns the created
+ * object label(s). We use it instead of evalCommand to avoid double-execution.
+ * Returns { ok, label } where label is the resulting object label(s).
+ */
+export async function ggbEval(page, cmd) {
+  let result;
+  try {
+    result = unwrapBridgeEnvelope(await page.evaluate(`
+      (cmd => {
+        if (typeof ggbApplet === 'undefined' || typeof ggbApplet.evalCommandGetLabels !== 'function') {
+          return { ok: false, label: '', beforeCount: 0, afterCount: 0, error: 'ggbApplet is not ready' };
+        }
+        const collectNames = () => {
+          let names = ggbApplet.getAllObjectNames();
+          if (typeof names === 'string') {
+            names = names.split(',').map(s => s.trim()).filter(Boolean);
+          }
+          return Array.isArray(names) ? names : [];
+        };
+        const beforeCount = collectNames().length;
+        const label = ggbApplet.evalCommandGetLabels(cmd);
+        const afterCount = collectNames().length;
+        const dialogText = [...document.querySelectorAll('[role="dialog"], .gwt-DialogBox')]
+          .map(node => node.textContent?.trim() || '')
+          .find(text => /error|unknown command|错误|未知的指令/i.test(text)) || '';
+        return {
+          ok: label !== '' || afterCount > beforeCount,
+          label,
+          beforeCount,
+          afterCount,
+          error: dialogText || null,
+        };
+      })(${JSON.stringify(cmd)})
+    `));
+  } catch (err) {
+    throw new CommandExecutionError(`Failed to execute GeoGebra command: ${err?.message || err}`);
+  }
+  if (!isPlainObject(result) || typeof result.ok !== 'boolean') {
+    throw new CommandExecutionError('GeoGebra command returned malformed result');
+  }
+  return result;
+}
+
+/**
+ * List all currently known GeoGebra objects, optionally filtered by type.
+ */
+export async function ggbListObjects(page, filterType) {
+  const normalizedFilter = filterType ? String(filterType).toLowerCase() : '';
+  let objects;
+  try {
+    objects = unwrapBridgeEnvelope(await page.evaluate(`
+      (filterType => {
+        const api = ggbApplet;
+        let names = api.getAllObjectNames();
+        if (typeof names === 'string') {
+          names = names.split(',').map(s => s.trim()).filter(Boolean);
+        }
+        if (!Array.isArray(names)) return { error: 'Object names are not an array' };
+        const result = [];
+        for (const name of names) {
+          try {
+            const type = api.getObjectType(name);
+            if (!type) return { error: 'Object has no type', name };
+            if (filterType && type.toLowerCase() !== filterType) continue;
+            result.push({
+              name,
+              type,
+              value: api.getValueString(name) || '',
+              visible: api.getVisible(name),
+            });
+          } catch (err) {
+            return { error: err?.message || String(err), name };
+          }
+        }
+        return result;
+      })(${JSON.stringify(normalizedFilter)})
+    `));
+  } catch (err) {
+    throw new CommandExecutionError(`Failed to list GeoGebra objects: ${err?.message || err}`);
+  }
+  if (objects && typeof objects === 'object' && !Array.isArray(objects) && objects.error) {
+    const nameSuffix = objects.name ? ` for ${objects.name}` : '';
+    throw new CommandExecutionError(`Failed to list GeoGebra objects${nameSuffix}: ${objects.error}`);
+  }
+  if (!Array.isArray(objects)) {
+    throw new CommandExecutionError('GeoGebra object list returned malformed result');
+  }
+  return objects;
+}
+
+/**
+ * Poll until the object count reaches the requested minimum.
+ */
+export async function ggbWaitForObjectCount(page, minCount, timeoutMs = 4_000) {
+  const normalizedMinCount = normalizeNumber(minCount, 'minCount', { positive: true });
+  const normalizedTimeoutMs = normalizeNumber(timeoutMs, 'timeoutMs', { positive: true });
+  let count;
+  try {
+    count = unwrapBridgeEnvelope(await page.evaluate(`
+      (async () => {
+        const deadline = Date.now() + ${normalizedTimeoutMs};
+        while (Date.now() < deadline) {
+          let names = ggbApplet.getAllObjectNames();
+          if (typeof names === 'string') {
+            names = names.split(',').map(s => s.trim()).filter(Boolean);
+          }
+          if (Array.isArray(names) && names.length >= ${normalizedMinCount}) {
+            return names.length;
+          }
+          await new Promise(resolve => setTimeout(resolve, 200));
+        }
+        let names = ggbApplet.getAllObjectNames();
+        if (typeof names === 'string') {
+          names = names.split(',').map(s => s.trim()).filter(Boolean);
+        }
+        return Array.isArray(names) ? names.length : 0;
+      })()
+    `));
+  } catch (err) {
+    throw new CommandExecutionError(`Failed waiting for GeoGebra object count: ${err?.message || err}`);
+  }
+  if (!Number.isFinite(Number(count))) {
+    throw new CommandExecutionError('GeoGebra object count returned malformed result');
+  }
+  return Number(count);
+}
+
+/**
+ * Read a property from a GeoGebra object.
+ */
+export async function ggbGetProperty(page, objName, property) {
+  try {
+    return unwrapBridgeEnvelope(await page.evaluate(`
+      (objName, property) => {
+        const api = ggbApplet;
+        switch (property) {
+          case 'type': return api.getObjectType(objName);
+          case 'value': return api.getValueString(objName);
+          case 'color': return api.getColor(objName);
+          case 'visible': return api.getVisible(objName);
+          case 'caption': return api.getCaption(objName) || '';
+          case 'xcoord': return api.getXcoord(objName);
+          case 'ycoord': return api.getYcoord(objName);
+          case 'definition': return api.getDefinitionString(objName);
+          case 'command': return api.getCommandString(objName);
+          default: return null;
+        }
+      }
+    `, objName, property));
+  } catch (err) {
+    throw new CommandExecutionError(`Failed to read GeoGebra object property: ${err?.message || err}`);
+  }
+}

package/clis/jira/attachments.js

@@ -0,0 +1,28 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { fetchIssue, jiraConfig, jiraRowsOrEmpty, normalizeAttachment, requireIssueKey } from './shared.js';
+import { requirePayloadArray } from '../_atlassian/shared.js';
+
+cli({
+    site: 'jira',
+    name: 'attachments',
+    access: 'read',
+    description: 'Jira issue attachment metadata',
+    domain: 'atlassian.net',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'key', positional: true, required: true, help: 'Jira issue key, e.g. PROJ-123' },
+    ],
+    columns: ['id', 'filename', 'mimeType', 'size', 'url'],
+    func: async (args) => {
+        const key = requireIssueKey(args.key);
+        const config = jiraConfig();
+        const issue = await fetchIssue(config, key, ['attachment']);
+        const attachments = requirePayloadArray(issue.fields?.attachment, `jira attachments ${key}`);
+        return jiraRowsOrEmpty(
+            attachments.map(normalizeAttachment),
+            `jira attachments ${key}`,
+            `Jira issue ${key} has no attachments.`,
+        );
+    },
+});

package/clis/jira/commands.test.js

@@ -0,0 +1,287 @@
+import { describe, expect, it, afterEach, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { __test__ as jiraSharedTest } from './shared.js';
+import './issue.js';
+import './search.js';
+import './comments.js';
+import './attachments.js';
+import './links.js';
+
+const ENV_KEYS = [
+    'ATLASSIAN_JIRA_BASE_URL',
+    'ATLASSIAN_DEPLOYMENT',
+    'ATLASSIAN_EMAIL',
+    'ATLASSIAN_API_TOKEN',
+    'ATLASSIAN_USERNAME',
+    'ATLASSIAN_PASSWORD',
+    'ATLASSIAN_PAT',
+];
+
+function clearEnv() {
+    for (const key of ENV_KEYS) delete process.env[key];
+}
+
+function setCloudEnv() {
+    clearEnv();
+    process.env.ATLASSIAN_JIRA_BASE_URL = 'https://team.atlassian.net';
+    process.env.ATLASSIAN_DEPLOYMENT = 'cloud';
+    process.env.ATLASSIAN_EMAIL = 'bot@example.com';
+    process.env.ATLASSIAN_API_TOKEN = 'secret';
+}
+
+function jsonResponse(body) {
+    return new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } });
+}
+
+afterEach(() => {
+    clearEnv();
+    vi.unstubAllGlobals();
+});
+
+describe('jira commands', () => {
+    it('registers non-browser REST commands', () => {
+        for (const name of ['issue', 'search', 'comments', 'attachments', 'links']) {
+            const cmd = getRegistry().get(`jira/${name}`);
+            expect(cmd).toBeDefined();
+            expect(cmd.browser).toBe(false);
+            expect(cmd.strategy).toBe('public');
+        }
+    });
+
+    it('normalizes a Cloud issue into agent-friendly context', async () => {
+        setCloudEnv();
+        vi.stubGlobal('fetch', vi.fn(async (url) => {
+            expect(String(url)).toContain('/rest/api/3/issue/PROJ-1?');
+            return jsonResponse({
+                id: '10001',
+                key: 'PROJ-1',
+                fields: {
+                    summary: 'Checkout fails',
+                    issuetype: { name: 'Bug' },
+                    status: { name: 'In Progress' },
+                    priority: { name: 'High' },
+                    labels: ['prod'],
+                    description: {
+                        type: 'doc',
+                        content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Payment fails' }] }],
+                    },
+                    comment: {
+                        total: 1,
+                        comments: [{
+                            id: 'c1',
+                            author: { displayName: 'Alice' },
+                            created: '2026-05-01T00:00:00.000+0000',
+                            body: { type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Needs RCA' }] }] },
+                        }],
+                    },
+                    attachment: [{ id: 'a1', filename: 'log.txt', mimeType: 'text/plain', size: 12, content: 'https://team.atlassian.net/secure/attachment/a1/log.txt' }],
+                    issuelinks: [{ type: { name: 'Blocks' }, outwardIssue: { key: 'PROJ-2' } }],
+                    fixVersions: [{ name: '1.2.3' }],
+                    created: '2026-05-01T00:00:00.000+0000',
+                    updated: '2026-05-02T00:00:00.000+0000',
+                },
+            });
+        }));
+        const cmd = getRegistry().get('jira/issue');
+        const rows = await cmd.func({ key: 'proj-1' });
+        expect(rows[0]).toMatchObject({
+            key: 'PROJ-1',
+            summary: 'Checkout fails',
+            issueType: 'Bug',
+            status: 'In Progress',
+            labels: ['prod'],
+            url: 'https://team.atlassian.net/browse/PROJ-1',
+        });
+        expect(rows[0].description.markdown).toBe('Payment fails');
+        expect(rows[0].comments[0].markdown).toBe('Needs RCA');
+        expect(rows[0].attachments[0].filename).toBe('log.txt');
+        expect(rows[0].linkedIssues[0]).toEqual({ key: 'PROJ-2', type: 'Blocks', direction: 'outward' });
+    });
+
+    it('fails typed when Jira issue payload is missing stable issue identity', async () => {
+        setCloudEnv();
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ fields: { summary: 'No key' } })));
+        const cmd = getRegistry().get('jira/issue');
+        await expect(cmd.func({ key: 'PROJ-1' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('fails typed when Jira issue nested collections have malformed shapes', async () => {
+        setCloudEnv();
+        const cmd = getRegistry().get('jira/issue');
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+            id: '10001',
+            key: 'PROJ-1',
+            fields: {
+                summary: 'Checkout fails',
+                labels: [],
+                comment: { total: 1, comments: { id: 'c1' } },
+                attachment: [],
+                issuelinks: [],
+            },
+        })));
+        await expect(cmd.func({ key: 'PROJ-1' })).rejects.toBeInstanceOf(CommandExecutionError);
+
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+            id: '10001',
+            key: 'PROJ-1',
+            fields: {
+                summary: 'Checkout fails',
+                labels: [],
+                comment: { total: 0, comments: [] },
+                attachment: { id: 'a1' },
+                issuelinks: [],
+            },
+        })));
+        await expect(cmd.func({ key: 'PROJ-1' })).rejects.toBeInstanceOf(CommandExecutionError);
+
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+            id: '10001',
+            key: 'PROJ-1',
+            fields: {
+                summary: 'Checkout fails',
+                labels: [],
+                comment: null,
+                attachment: [],
+                issuelinks: [],
+            },
+        })));
+        await expect(cmd.func({ key: 'PROJ-1' })).rejects.toBeInstanceOf(CommandExecutionError);
+
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+            id: '10001',
+            key: 'PROJ-1',
+            fields: {
+                summary: 'Checkout fails',
+                labels: [],
+                comment: { total: 0, comments: [] },
+                attachment: null,
+                issuelinks: [],
+            },
+        })));
+        await expect(cmd.func({ key: 'PROJ-1' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('rejects invalid Jira issue keys before remote requests', async () => {
+        expect(() => jiraSharedTest.requireIssueKey('notakey')).toThrow(/Invalid Jira issue key/);
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        const cmd = getRegistry().get('jira/issue');
+        await expect(cmd.func({ key: 'notakey' })).rejects.toMatchObject({ code: 'ARGUMENT' });
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('fetches full comments when issue inline comments are truncated', async () => {
+        setCloudEnv();
+        const fetchMock = vi.fn(async (url) => {
+            const href = String(url);
+            if (href.includes('/comment?')) {
+                return jsonResponse({
+                    comments: [
+                        { id: 'c1', author: { displayName: 'Alice' }, created: '2026-05-01', body: 'one' },
+                        { id: 'c2', author: { displayName: 'Bob' }, created: '2026-05-02', body: 'two' },
+                    ],
+                });
+            }
+            return jsonResponse({
+                id: '10001',
+                key: 'PROJ-1',
+                fields: {
+                    summary: 'Checkout fails',
+                    labels: [],
+                    comment: {
+                        total: 2,
+                        comments: [{ id: 'c1', author: { displayName: 'Alice' }, created: '2026-05-01', body: 'one' }],
+                    },
+                    attachment: [],
+                    issuelinks: [],
+                },
+            });
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const cmd = getRegistry().get('jira/issue');
+        const rows = await cmd.func({ key: 'PROJ-1', 'comments-limit': 10 });
+        expect(rows[0].comments.map((comment) => comment.id)).toEqual(['c1', 'c2']);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('uses Data Center search endpoint and payload', async () => {
+        clearEnv();
+        process.env.ATLASSIAN_JIRA_BASE_URL = 'https://jira.example.com';
+        process.env.ATLASSIAN_DEPLOYMENT = 'datacenter';
+        process.env.ATLASSIAN_USERNAME = 'bot';
+        process.env.ATLASSIAN_PASSWORD = 'secret';
+        const fetchMock = vi.fn(async (url, init) => {
+            expect(String(url)).toBe('https://jira.example.com/rest/api/2/search');
+            expect(init.method).toBe('POST');
+            expect(JSON.parse(init.body)).toMatchObject({
+                jql: 'project = PROJ',
+                startAt: 0,
+                maxResults: 5,
+            });
+            return jsonResponse({
+                issues: [{
+                    id: '1',
+                    key: 'PROJ-1',
+                    fields: {
+                        summary: 'Task',
+                        status: { name: 'Done' },
+                        updated: '2026-05-03T00:00:00.000+0000',
+                    },
+                }],
+            });
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const cmd = getRegistry().get('jira/search');
+        const rows = await cmd.func({ jql: 'project = PROJ', limit: 5 });
+        expect(rows).toEqual([
+            expect.objectContaining({ key: 'PROJ-1', summary: 'Task', status: 'Done' }),
+        ]);
+    });
+
+    it('separates Jira search empty results from malformed search payloads', async () => {
+        setCloudEnv();
+        const cmd = getRegistry().get('jira/search');
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ issues: [] })));
+        await expect(cmd.func({ jql: 'project = NONE' })).rejects.toBeInstanceOf(EmptyResultError);
+
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ values: [] })));
+        await expect(cmd.func({ jql: 'project = PROJ' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('maps rendered comments to Markdown', async () => {
+        setCloudEnv();
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+            comments: [{
+                id: 'c1',
+                author: { displayName: 'Bob' },
+                created: '2026-05-01',
+                renderedBody: '<p>Fixed<br/>Ready for QA</p>',
+            }],
+        })));
+        const cmd = getRegistry().get('jira/comments');
+        const rows = await cmd.func({ key: 'PROJ-1', limit: 1 });
+        expect(rows[0]).toMatchObject({ id: 'c1', author: 'Bob' });
+        expect(rows[0].markdown).toContain('Fixed');
+        expect(rows[0].markdown).toContain('Ready for QA');
+    });
+
+    it('fails typed when Jira comment rows lack stable comment ids', async () => {
+        setCloudEnv();
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({
+            comments: [{ author: { displayName: 'Bob' }, created: '2026-05-01', body: 'body' }],
+        })));
+        const cmd = getRegistry().get('jira/comments');
+        await expect(cmd.func({ key: 'PROJ-1', limit: 1 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('separates no Jira attachments from malformed attachment payloads', async () => {
+        setCloudEnv();
+        const cmd = getRegistry().get('jira/attachments');
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ id: '1', key: 'PROJ-1', fields: { attachment: [] } })));
+        await expect(cmd.func({ key: 'PROJ-1' })).rejects.toBeInstanceOf(EmptyResultError);
+
+        vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ id: '1', key: 'PROJ-1', fields: {} })));
+        await expect(cmd.func({ key: 'PROJ-1' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+});

package/clis/jira/comments.js

@@ -0,0 +1,28 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { fetchComments, jiraConfig, jiraRowsOrEmpty, normalizeComment, parseJiraLimit, requireIssueKey } from './shared.js';
+
+cli({
+    site: 'jira',
+    name: 'comments',
+    access: 'read',
+    description: 'Jira issue comments as Markdown',
+    domain: 'atlassian.net',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'key', positional: true, required: true, help: 'Jira issue key, e.g. PROJ-123' },
+        { name: 'limit', type: 'int', default: 50, help: 'Max comments to return (1-100)' },
+    ],
+    columns: ['id', 'author', 'created', 'updated', 'markdown'],
+    func: async (args) => {
+        const key = requireIssueKey(args.key);
+        const config = jiraConfig();
+        const limit = parseJiraLimit(args.limit, 50, 100);
+        const comments = await fetchComments(config, key, limit);
+        return jiraRowsOrEmpty(
+            comments.map(normalizeComment),
+            `jira comments ${key}`,
+            `Jira issue ${key} has no comments.`,
+        );
+    },
+});

package/clis/jira/issue.js

@@ -0,0 +1,28 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { fetchComments, fetchIssue, jiraConfig, normalizeJiraIssue, requireIssueKey } from './shared.js';
+
+cli({
+    site: 'jira',
+    name: 'issue',
+    access: 'read',
+    description: 'Jira issue detail normalized for agents (description, comments, attachments, links)',
+    domain: 'atlassian.net',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'key', positional: true, required: true, help: 'Jira issue key, e.g. PROJ-123' },
+        { name: 'comments-limit', type: 'int', default: 100, help: 'Max comments to include (1-100)' },
+    ],
+    columns: ['key', 'summary', 'issueType', 'status', 'priority', 'assignee', 'updated', 'url'],
+    func: async (args) => {
+        const key = requireIssueKey(args.key);
+        const config = jiraConfig();
+        const issue = await fetchIssue(config, key);
+        const inlineComments = issue?.fields?.comment?.comments;
+        const total = Number(issue?.fields?.comment?.total ?? inlineComments?.length ?? 0);
+        const comments = total > (inlineComments?.length ?? 0)
+            ? await fetchComments(config, key, args['comments-limit'])
+            : inlineComments;
+        return [normalizeJiraIssue(issue, config, { comments })];
+    },
+});

package/clis/jira/links.js

@@ -0,0 +1,28 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { fetchIssue, jiraConfig, jiraRowsOrEmpty, normalizeIssueLink, requireIssueKey } from './shared.js';
+import { requirePayloadArray } from '../_atlassian/shared.js';
+
+cli({
+    site: 'jira',
+    name: 'links',
+    access: 'read',
+    description: 'Jira issue links',
+    domain: 'atlassian.net',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'key', positional: true, required: true, help: 'Jira issue key, e.g. PROJ-123' },
+    ],
+    columns: ['key', 'type', 'direction'],
+    func: async (args) => {
+        const key = requireIssueKey(args.key);
+        const config = jiraConfig();
+        const issue = await fetchIssue(config, key, ['issuelinks']);
+        const links = requirePayloadArray(issue.fields?.issuelinks, `jira links ${key}`);
+        return jiraRowsOrEmpty(
+            links.map(normalizeIssueLink),
+            `jira links ${key}`,
+            `Jira issue ${key} has no linked issues.`,
+        );
+    },
+});