jiradc-cli 1.0.43 → 1.0.44

package/README.md

@@ -31,27 +31,68 @@ All commands output JSON. Add `--pretty` to pretty-print.
 
 ### issue
 
-| Command                               | Description                                                                                                                                           |
-| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `jiradc issue get <key>`              | One issue. `--fields` selects fields by id or name, `--all-fields` returns everything Jira holds, `--expand` adds changelog/names                     |
-| `jiradc issue search <jql>`           | Issues matching a JQL query. `--all` collects every match (capped at 1,000); `description` and `comment` are excluded unless asked for via `--fields` |
-| `jiradc issue create`                 | The new issue's key and id. Requires `--project`, `--type`, `--summary`; `--fields <json>` sets anything else                                         |
-| `jiradc issue update <key>`           | Applies field changes. Shortcuts for `--summary`/`--description`/`--priority`/`--assignee`, list flags for `--labels`/`--components`/`--fix-versions` |
-| `jiradc issue delete <key>`           | Deletes the issue. `--delete-subtasks` to take its subtasks with it                                                                                   |
-| `jiradc issue assign <key>`           | Sets the assignee. `--assignee` takes a username, `me`, or `none` to unassign                                                                         |
-| `jiradc issue transition <key>`       | Moves the issue. `--to` accepts a transition id, a transition name, or the target status name; `--fields` supplies screen fields, `--comment` a note  |
-| `jiradc issue transitions <key>`      | The transitions available from the current status, each with the screen fields it requires                                                            |
-| `jiradc issue createmeta`             | The fields a new issue accepts and the values they allow. Requires `--project` and `--type`                                                           |
-| `jiradc issue editmeta <key>`         | The fields this issue's edit screen accepts, with their allowed values                                                                                |
-| `jiradc issue link`                   | Links two issues. Requires `--from`, `--to` and `--type` (a link type name)                                                                           |
-| `jiradc issue unlink <id>`            | Removes one issue link by its link id                                                                                                                 |
-| `jiradc issue link-types`             | The link type names this instance accepts, for `issue link --type`                                                                                    |
-| `jiradc issue link-epic <keys...>`    | Links one or more issues to `--epic <epicKey>`; reports a `failed` array if any link is rejected                                                      |
-| `jiradc issue changelog <key>`        | The issue's change history                                                                                                                            |
-| `jiradc issue batch-changelog <keys>` | Change history for several issues at once, from a comma-separated key list                                                                            |
-| `jiradc issue clone <key>`            | Creates a duplicate. `--include-links`, `--include-attachments`, `--summary` and `--project` control what carries over                                |
-| `jiradc issue batch-create`           | Creates many issues from `--issues <json>` (an array of field objects)                                                                                |
-| `jiradc issue dev-status <key>`       | Branches, pull requests, commits and builds linked to the issue. `--detail` for the full records                                                      |
+| Command                               | Description                                                                                                                                                                        |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `jiradc issue get <key>`              | One issue, with every dimension hanging off it (see below). `--fields` selects fields by id or name, `--all-fields` returns everything Jira holds, `--expand` adds changelog/names |
+| `jiradc issue search <jql>`           | Issues matching a JQL query. `--all` collects every match (capped at 1,000); `description` and `comment` are excluded unless asked for via `--fields`                              |
+| `jiradc issue create`                 | The new issue's key and id. Requires `--project`, `--type`, `--summary`; `--fields <json>` sets anything else                                                                      |
+| `jiradc issue update <key>`           | Applies field changes. Shortcuts for `--summary`/`--description`/`--priority`/`--assignee`, list flags for `--labels`/`--components`/`--fix-versions`                              |
+| `jiradc issue delete <key>`           | Deletes the issue. `--delete-subtasks` to take its subtasks with it                                                                                                                |
+| `jiradc issue assign <key>`           | Sets the assignee. `--assignee` takes a username, `me`, or `none` to unassign                                                                                                      |
+| `jiradc issue transition <key>`       | Moves the issue. `--to` accepts a transition id, a transition name, or the target status name; `--fields` supplies screen fields, `--comment` a note                               |
+| `jiradc issue transitions <key>`      | The transitions available from the current status, each with the screen fields it requires                                                                                         |
+| `jiradc issue createmeta`             | The fields a new issue accepts and the values they allow. Requires `--project` and `--type`                                                                                        |
+| `jiradc issue editmeta <key>`         | The fields this issue's edit screen accepts, with their allowed values                                                                                                             |
+| `jiradc issue link`                   | Links two issues. Requires `--from`, `--to` and `--type` (a link type name)                                                                                                        |
+| `jiradc issue unlink <id>`            | Removes one issue link by its link id                                                                                                                                              |
+| `jiradc issue link-types`             | The link type names this instance accepts, for `issue link --type`                                                                                                                 |
+| `jiradc issue link-epic <keys...>`    | Links one or more issues to `--epic <epicKey>`; reports a `failed` array if any link is rejected                                                                                   |
+| `jiradc issue changelog <key>`        | The issue's change history                                                                                                                                                         |
+| `jiradc issue batch-changelog <keys>` | Change history for several issues at once, from a comma-separated key list                                                                                                         |
+| `jiradc issue clone <key>`            | Creates a duplicate. `--include-links`, `--include-attachments`, `--summary` and `--project` control what carries over                                                             |
+| `jiradc issue batch-create`           | Creates many issues from `--issues <json>` (an array of field objects)                                                                                                             |
+| `jiradc issue dev-status <key>`       | Branches, pull requests, commits and builds linked to the issue. `--detail` for the full records                                                                                   |
+
+#### What a bare `issue get` returns
+
+With no `--fields`, one issue comes back with every dimension that hangs off it, out of the
+single request the command already makes:
+
+| Default field                                                   | What arrives                                             |
+| --------------------------------------------------------------- | -------------------------------------------------------- |
+| `summary` `status` `issuetype` `priority` `labels` `components` | The issue itself                                         |
+| `assignee` `reporter` `created` `updated`                       | Who and when                                             |
+| `description`                                                   | In full — it is the issue, not a dimension of it         |
+| `issuelinks`                                                    | `{ id, type, key, summary, status, issuetype }` per link |
+| `epic`                                                          | The key of the epic this issue sits under, if any        |
+| `parent` `subtasks`                                             | `{ key, summary, status, issuetype }` each               |
+| `attachment`                                                    | `{ files: [{ id, filename, size }], use }`               |
+| `comment`                                                       | `{ count, use }` — the thread is named, not carried      |
+
+The rule: **the default names every dimension, and carries it only when carrying it is
+complete.** A link stub is the whole link, so links arrive whole and point at no command. An
+attachment's bytes and a comment's body are not something to inline, so those arrive as an
+inventory plus the command that reads them — the same `use` convention `project get` uses for
+components and versions. A field with nothing in it is absent altogether, pointer included:
+no `attachment` key means there are no attachments, which is readable only because the field
+was asked for.
+
+`type` on a link is the phrase true **from this issue's side** — `blocks`, `is blocked by`,
+`relates to` — so the direction needs no decoding and there is no nested `inwardIssue` /
+`outwardIssue`. The link's own id is `linkId`, not `id`, because `id` beside `key` reads as the
+linked issue's id. `--fields issuelinks` returns the same flat shape.
+
+Every row above is a `--fields` selector except `epic`, which is an output key: the Epic Link is
+a custom field, so select it by name with `--fields "Epic Link"`.
+
+Naming `attachment` or `comment` in `--fields`, or passing `--all-fields`, returns that field
+in full instead. `worklog` and `watches` are not requested at all; ask for them by name.
+
+Nothing here costs a second request. Development activity and the change history are separate
+endpoints and stay behind `issue dev-status` and `issue changelog`.
+
+`issue search` deliberately keeps none of this — what is one link list on one issue is fifty of
+them on a page of results.
 
 #### issue comment
 

package/dist/index.js

@@ -187,6 +187,31 @@ function transformSprint(s) {
   };
 }
 
+// src/utils/constants.ts
+var SEARCH_DEFAULT_FIELDS = [
+  "summary",
+  "status",
+  "assignee",
+  "reporter",
+  "labels",
+  "priority",
+  "created",
+  "updated",
+  "issuetype",
+  "components"
+];
+var EPIC_LINK_FIELD_ID = "customfield_10100";
+var DEFAULT_FIELDS = [
+  ...SEARCH_DEFAULT_FIELDS,
+  "description",
+  "comment",
+  "issuelinks",
+  EPIC_LINK_FIELD_ID,
+  "parent",
+  "subtasks",
+  "attachment"
+];
+
 // src/utils/transformers/issue.ts
 function issueBrowseUrl(key) {
   return `${jiraBaseUrl()}/browse/${key}`;
@@ -248,28 +273,24 @@ function transformAttachment(a) {
     ...author ? { author: transformUser(author) } : {}
   };
 }
-function transformIssueBasic(b) {
-  const { self: _self, fields, ...rest } = b;
+function transformIssueStub(b) {
+  const fields = b.fields;
   return {
-    ...rest,
-    url: issueBrowseUrl(b.key),
-    ...fields ? {
-      fields: {
-        ...fields.summary !== void 0 ? { summary: fields.summary } : {},
-        ...fields.status ? { status: transformStatus(fields.status) } : {},
-        ...fields.priority ? { priority: transformPriority(fields.priority) } : {},
-        ...fields.issuetype ? { issuetype: transformIssueType(fields.issuetype) } : {}
-      }
-    } : {}
+    key: b.key,
+    ...fields?.summary !== void 0 ? { summary: fields.summary } : {},
+    ...fields?.status ? { status: fields.status.name } : {},
+    ...fields?.issuetype ? { issuetype: fields.issuetype.name } : {}
   };
 }
 function transformIssueLink(l) {
-  const { self: _self, type, inwardIssue, outwardIssue, ...rest } = l;
+  const other = l.outwardIssue ?? l.inwardIssue;
   return {
-    ...rest,
-    type: transformIssueLinkType(type),
-    ...inwardIssue ? { inwardIssue: transformIssueBasic(inwardIssue) } : {},
-    ...outwardIssue ? { outwardIssue: transformIssueBasic(outwardIssue) } : {}
+    linkId: l.id,
+    // A link with an issue on neither end is not something Jira sends. If it
+    // ever does, the type's name is the honest answer — a direction phrase with
+    // nothing on the far end of it would not be.
+    type: other ? l.outwardIssue ? l.type.outward : l.type.inward : l.type.name,
+    ...other ? transformIssueStub(other) : {}
   };
 }
 function customFieldNames(names, fields) {
@@ -279,9 +300,9 @@ function customFieldNames(names, fields) {
   );
   return kept.length > 0 ? Object.fromEntries(kept) : void 0;
 }
-function transformIssue(issue) {
+function transformIssue(issue, opts = {}) {
   const { self: _self, expand: _expand, names, schema: _schema, fields, ...rest } = issue;
-  const transformed = transformIssueFields(fields, issue.key);
+  const transformed = transformIssueFields(fields, issue.key, opts);
   const fieldNames = customFieldNames(names, transformed);
   return {
     ...rest,
@@ -323,6 +344,12 @@ function pruneSentinels(fields) {
   if (watches && watches.watchCount === 0) delete out.watches;
   return out;
 }
+function nameEpicLink(fields) {
+  const value = fields[EPIC_LINK_FIELD_ID];
+  if (typeof value !== "string" || !ISSUE_KEY_PATTERN.test(value)) return fields;
+  const { [EPIC_LINK_FIELD_ID]: _epicLink, ...rest } = fields;
+  return { ...rest, epic: value };
+}
 var DEV_STATUS_DUMP = /com\.atlassian\.jira\.plugin\.devstatus/;
 function collapseDevStatus(fields, key) {
   const out = { ...fields };
@@ -360,7 +387,7 @@ function collapseIssueRefs(fields) {
   }
   return out;
 }
-function transformIssueFields(fields, key) {
+function transformIssueFields(fields, key, opts) {
   if (!fields) return {};
   const {
     // shaped sub-entities (recursed individually)
@@ -387,7 +414,7 @@ function transformIssueFields(fields, key) {
     // everything else: optional scalars, customfield_*, etc. — gets compacted
     ...rest
   } = fields;
-  const compacted = collapseDevStatus(collapseIssueRefs(pruneSentinels(compactRecord(rest))), key);
+  const compacted = collapseDevStatus(collapseIssueRefs(nameEpicLink(pruneSentinels(compactRecord(rest)))), key);
   const components = compacted.components;
   return {
     ...compacted,
@@ -406,13 +433,21 @@ function transformIssueFields(fields, key) {
     ...fixVersions && fixVersions.length > 0 ? { fixVersions: fixVersions.map(transformVersion) } : {},
     ...versions2 && versions2.length > 0 ? { versions: versions2.map(transformVersion) } : {},
     ...issuelinks && issuelinks.length > 0 ? { issuelinks: issuelinks.map(transformIssueLink) } : {},
-    ...subtasks && subtasks.length > 0 ? { subtasks: subtasks.map(transformIssueBasic) } : {},
-    ...parent ? { parent: transformIssueBasic(parent) } : {},
+    ...subtasks && subtasks.length > 0 ? { subtasks: subtasks.map(transformIssueStub) } : {},
+    ...parent ? { parent: transformIssueStub(parent) } : {},
     // Drop empty comment / worklog containers entirely. The default Jira
     // search response includes both wrappers on every issue regardless of
     // count; on a 25-issue page that's 25 × 2 empty objects of pure noise.
-    ...comment && comment.comments.length > 0 ? {
-      comment: {
+    // The thread is named, not carried — see `JiraCommentSummaryOutput`.
+    //
+    // The compact branch gates on `total`, not on the array, because `total` is
+    // the only thing it reads. A deployment that caps embedded comments answers
+    // with a populated total and an empty `comments`; gating on the array there
+    // would drop the key, and a missing key is documented to mean "there are
+    // none" — reporting a long thread as no thread, in the one direction the
+    // caller was told to trust.
+    ...comment && (opts.compact ? comment.total > 0 : comment.comments.length > 0) ? {
+      comment: opts.compact ? { count: comment.total, use: `jiradc issue comment list ${key}` } : {
         comments: comment.comments.map(transformComment),
         maxResults: comment.maxResults,
         total: comment.total,
@@ -427,7 +462,19 @@ function transformIssueFields(fields, key) {
         startAt: worklog.startAt
       }
     } : {},
-    ...attachment && attachment.length > 0 ? { attachment: attachment.map(transformAttachment) } : {}
+    // `attachment` is in the default field set to say that files are attached —
+    // not to carry their records. An empty list yields no key at all rather
+    // than a pointer to nothing: the absence is the answer, and it is readable
+    // as one only because the field was asked for.
+    ...attachment && attachment.length > 0 ? {
+      attachment: opts.compact ? {
+        files: attachment.map(({ id, filename, size }) => ({ id, filename, size })),
+        // Both commands spelled in full. Abbreviating the second to
+        // `download …` saved 24 characters and invited a caller to run
+        // exactly that, which is not a command.
+        use: `jiradc issue attachment download-all ${key} --output <dir> (one file: jiradc issue attachment download ${key} --attachment-id <id> --output <path>)`
+      } : attachment.map(transformAttachment)
+    } : {}
   };
 }
 
@@ -1437,21 +1484,6 @@ function editmeta(parent) {
   });
 }
 
-// src/utils/constants.ts
-var SEARCH_DEFAULT_FIELDS = [
-  "summary",
-  "status",
-  "assignee",
-  "reporter",
-  "labels",
-  "priority",
-  "created",
-  "updated",
-  "issuetype",
-  "components"
-];
-var DEFAULT_FIELDS = [...SEARCH_DEFAULT_FIELDS, "description", "comment"];
-
 // src/utils/field-selectors.ts
 var WILDCARD = "*";
 var NEGATION = "-";
@@ -1555,10 +1587,13 @@ async function loadFieldNameIndex(client) {
 }
 async function selectFields(client, opts, defaults) {
   if (opts.allFields === true) return void 0;
-  if (opts.fields === void 0) return defaults;
-  const tokens = parseFieldSelectors(opts.fields);
-  if (tokens.length === 0) return defaults;
-  return resolveFieldSelectors(tokens, await loadFieldNameIndex(client));
+  if (usesDefaultFields(opts)) return defaults;
+  return resolveFieldSelectors(parseFieldSelectors(opts.fields), await loadFieldNameIndex(client));
+}
+function usesDefaultFields(opts) {
+  if (opts.allFields === true) return false;
+  if (opts.fields === void 0) return true;
+  return parseFieldSelectors(opts.fields).length === 0;
 }
 
 // src/commands/issue/get.ts
@@ -1578,7 +1613,7 @@ function get4(parent) {
       fields,
       expand: opts.expand
     });
-    output(transformIssue(result));
+    output(transformIssue(result, { compact: usesDefaultFields(opts) }));
   });
 }
 
@@ -1590,7 +1625,7 @@ function linkEpic(parent) {
     const client = getClient();
     const results = await Promise.allSettled(
       keys.map(
-        (key) => client.issues.update({ issueKeyOrId: key, fields: { customfield_10100: opts.epic } }).then(() => key)
+        (key) => client.issues.update({ issueKeyOrId: key, fields: { [EPIC_LINK_FIELD_ID]: opts.epic } }).then(() => key)
       )
     );
     const linked = [];
@@ -1711,7 +1746,7 @@ function search2(parent) {
         return;
       }
       const every = await fetchEveryPage(page, { pageSize: plan.pageSize, start: plan.start });
-      output({ ...every, issues: every.issues.map(transformIssue) });
+      output({ ...every, issues: every.issues.map((i) => transformIssue(i)) });
     }
   );
 }
@@ -2757,7 +2792,7 @@ function search3(parent) {
         total: res.total,
         startAt: res.startAt,
         count: res.issues?.length ?? 0,
-        issues: (res.issues ?? []).map(transformIssue)
+        issues: (res.issues ?? []).map((i) => transformIssue(i))
       });
     }
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jiradc-cli",
-  "version": "1.0.43",
+  "version": "1.0.44",
   "publish": true,
   "type": "module",
   "main": "dist/index.js",
@@ -23,9 +23,9 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^4.0.16",
-    "cli-utils": "1.0.0",
     "config-eslint": "0.0.0",
-    "config-typescript": "0.0.0"
+    "config-typescript": "0.0.0",
+    "cli-utils": "1.0.0"
   },
   "engines": {
     "node": ">=22.0.0"