cawdev-cli 1.0.8-beta → 1.0.9-beta

package/README.md

@@ -5,4 +5,9 @@ and spawning processes are Node's home turf, and a file with no dependencies is
 one you can read before running it against your repositories.
 visit https://cawdev.com to learn more
 
-https://github.com/4dali/cawdev-cli
+https://github.com/4dali/cawdev-cli
+## jira/
+
+`jira/import.mjs` brings a Jira Cloud project's issues, epics, sprints and
+comments into a cawdev project, once and again without duplicates (R337). Run from a checkout; see
+"Leaving Jira" in GUIDE.md. Its tests: `node --test "tools/jira/*.test.mjs"`.

package/lib/roadmap-format.mjs

@@ -232,6 +232,32 @@ export function parseRoadmap(text) {
         }
         continue;
       }
+      // R351. The date shape is checked here, where the line is read: a
+      // `Due:` that is not a date is a hand edit, and --live would otherwise
+      // report it as drift from a database that never held it.
+      const due = /^Due:\s*(.+)$/.exec(line.trim());
+      if (due) {
+        entry.due = due[1].trim();
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.due) || Number.isNaN(Date.parse(entry.due))) {
+          problems.push(`${block.heading}: Due "${due[1].trim()}" is not a date written 2026-11-01.`);
+        }
+        continue;
+      }
+      // R358. The version the card means to ship in; a free string, as `Version:` is.
+      const target = /^Target:\s*(.+)$/.exec(line.trim());
+      if (target) {
+        entry.targetVersion = target[1].trim();
+        continue;
+      }
+      const estimate = /^Estimate:\s*(.+)$/.exec(line.trim());
+      if (estimate) {
+        const n = Number(estimate[1].trim());
+        entry.estimate = n;
+        if (!Number.isInteger(n) || n <= 0) {
+          problems.push(`${block.heading}: Estimate "${estimate[1].trim()}" is not a positive whole number.`);
+        }
+        continue;
+      }
       const development = /^Development:\s*(.+)$/.exec(line.trim());
       if (development) {
         entry.development = statusFromDisplay(development[1].trim());
@@ -262,6 +288,16 @@ export function parseRoadmap(text) {
         entry.afterRefs = tokens.map(({ ref }) => ref);
         continue;
       }
+      const parent = /^Parent:\s*(\S+)\s*$/.exec(line.trim());
+      if (parent) {
+        // R336. One ref, always written in full (R300, i12). A token that is
+        // not a card is left as ordinary body text rather than eaten.
+        const token = parseRefToken(parent[1]);
+        if (token) {
+          entry.parentRef = token.ref;
+          continue;
+        }
+      }
       const tags = /^Tags:\s*(.+)$/.exec(line.trim());
       if (tags) {
         // R315. Already normalised by the server (lowercase, no `#`) by the
@@ -356,6 +392,45 @@ function* splitBlocks(text) {
   if (entry) yield entry;
 }
 
+/** The ref of the card this one sits under, from either shape — R336. */
+function parentRefOf(entry) {
+  const ref = entry.parent?.ref ?? entry.parentRef;
+  return ref ? (parseRefToken(ref)?.ref ?? null) : null;
+}
+
+/**
+ * Files each child directly after its parent, within one section — R336.
+ *
+ * Pure. A child keeps its place among its siblings (they stay in the order
+ * given), and a child whose parent is in some other section stays exactly
+ * where it was: the file groups by section first, and an epic spread over
+ * phases is still one epic by its `Parent:` lines.
+ */
+export function nestUnderParents(list) {
+  const refs = new Map(list.map((entry) => [entryRef(entry), entry]));
+  const nestedUnder = (entry) => {
+    const parent = parentRefOf(entry);
+    const card = parent && refs.get(parent);
+    // A parent that is itself a child is bad data; leave the child where it is
+    // rather than lose it behind a card that is not a root.
+    return card && !parentRefOf(card) ? parent : null;
+  };
+  const children = new Map();
+  for (const entry of list) {
+    const parent = nestedUnder(entry);
+    if (parent) {
+      if (!children.has(parent)) children.set(parent, []);
+      children.get(parent).push(entry);
+    }
+  }
+  const out = [];
+  for (const entry of list) {
+    if (nestedUnder(entry)) continue;
+    out.push(entry, ...(children.get(entryRef(entry)) ?? []));
+  }
+  return out;
+}
+
 /**
  * Writes entries as ROADMAP.md's entry sections.
  *
@@ -385,7 +460,7 @@ export function renderRoadmap(entries, { preamble, sectionOrder = [] }) {
   const parts = [preamble.trimEnd(), ''];
   for (const section of ordered) {
     parts.push('---', '', `## ${section}`, '');
-    for (const entry of bySection.get(section)) {
+    for (const entry of nestUnderParents(bySection.get(section))) {
       parts.push(renderEntry(entry), '');
     }
   }
@@ -443,6 +518,19 @@ function renderEntry(entry) {
     lines.push(`Priority: ${entry.priority}`);
   }
 
+  // R351. Two facts, written only when the card carries them, after the
+  // priority: when, then how big.
+  if (entry.due) {
+    lines.push(`Due: ${entry.due}`);
+  }
+  if (entry.estimate != null && entry.estimate > 0) {
+    lines.push(`Estimate: ${entry.estimate}`);
+  }
+  // R358. Where it means to ship; dropped once it has, because `Version:` then says.
+  if (entry.targetVersion && !entry.version) {
+    lines.push(`Target: ${entry.targetVersion}`);
+  }
+
   // Each status writes only what it currently claims. A MERGED entry keeps its
   // branch in the database as history, but the file must not print it: the
   // branch is expected to be deleted, and `--live` would then be reading a claim
@@ -492,6 +580,13 @@ function renderEntry(entry) {
       .map(({ ref }) => ref);
     lines.push(`After: ${written.join(', ')}`);
   }
+  {
+    // R336. The API gives `parent` as {number, ref, title}; the parser gives
+    // `parentRef`. Always the full ref, and no line at all without a parent, so
+    // no existing card's text changes.
+    const parent = parentRefOf(entry);
+    if (parent) lines.push(`Parent: ${parent}`);
+  }
   if (entry.tags?.length) {
     // R315. Sorted, so the export does not churn on the set's own order.
     lines.push(`Tags: ${[...entry.tags].sort().join(', ')}`);

package/mcp/README.md

@@ -163,7 +163,7 @@ what you are allowed to do.
 | `roadmap_list` | Entries, optionally by status. `brief` omits bodies — use it to survey. |
 | `roadmap_get` | One entry in full: its body, **the plan agreed for it**, and the discussion on it. |
 | `roadmap_create` | Create an entry; the platform allocates its permanent number. |
-| `roadmap_update` | Title, body, section, related ids, the cards it starts coding after (`after` — R181), and who it is assigned to (`assignee` — R331: a username, `""` clears; `roadmap_list`/`issue_list` take `assignee` too, and `me` means the token's owner). |
+| `roadmap_update` | Title, body, section, related ids, the cards it starts coding after (`after` — R181), when it is due and how big it is (`due` — R351: an ISO date, `""` clears; `estimate`: a positive number, `0` clears), the version it is meant for (`targetVersion` — R358, `""` clears; since R362 it must be one the project defined under Project settings → Versions, and any other name is refused), and who it is assigned to (`assignee` — R331: a username, `""` clears; `roadmap_list`/`issue_list` take `assignee` too, and `me` means the token's owner). |
 | `roadmap_comment` | Say something *beside* an entry rather than inside it. |
 | `roadmap_set_status` | Move an entry, carrying whatever the status requires. |
 | `roadmap_decline` | Decline with a reason. The only exit. |

package/mcp/server.mjs

@@ -692,6 +692,26 @@ const TOOLS = [
           description:
             'How much it matters; it does not reorder the board. Leave out for MEDIUM.',
         },
+        due: {
+          type: 'string',
+          description: 'When it is due, written 2026-11-01. A fact on the card; it moves nothing. Leave out for none.',
+        },
+        estimate: {
+          type: 'integer',
+          minimum: 1,
+          description: "How big it is, in the team's own unit (points, days — the platform does not say). Leave out for none.",
+        },
+        targetVersion: {
+          type: 'string',
+          description: 'The version it is meant to ship in — one the project DEFINED under Project settings → Versions (R362); any other name is refused. The release corrects it if it lands elsewhere. Leave out for none.',
+        },
+        parent: {
+          type: 'string',
+          description:
+            'The card this one sits under (an epic), e.g. "R300". One level only: the parent ' +
+            'must be the same kind and have no parent itself, and this card must have no ' +
+            'children. An open card cannot be filed under a SHIPPED or DECLINED one.',
+        },
       },
       required: ['title'],
     },
@@ -701,7 +721,7 @@ const TOOLS = [
         method: 'POST',
         body: pick(args, [
           'title', 'body', 'status', 'branch', 'merge', 'version', 'reason', 'section', 'related',
-          'after', 'sprint', 'tags', 'assignee', 'priority',
+          'after', 'sprint', 'tags', 'assignee', 'priority', 'due', 'estimate', 'targetVersion', 'parent',
         ]),
       });
       return `Created ${refOf(entry)} in ${slug}.\n\n${formatEntry(entry, {})}`;
@@ -830,8 +850,8 @@ const TOOLS = [
   {
     name: 'roadmap_update',
     description:
-      'Edit an entry\'s title, body, section, sprint, tags, related refs or the cards it starts ' +
-      'after. Use roadmap_set_status to move it.',
+      'Edit an entry\'s title, body, section, sprint, tags, parent, related refs or the cards it ' +
+      'starts after. Use roadmap_set_status to move it.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -882,6 +902,25 @@ const TOOLS = [
           description:
             'How much it matters; it does not reorder the board. Leave out for MEDIUM (leave out to leave it alone).',
         },
+        due: {
+          type: 'string',
+          description: 'When it is due, written 2026-11-01. Leave out to leave it alone; "" clears it.',
+        },
+        estimate: {
+          type: 'integer',
+          minimum: 0,
+          description: "How big it is, in the team's own unit. Leave out to leave it alone; 0 clears it.",
+        },
+        targetVersion: {
+          type: 'string',
+          description: 'The version it is meant to ship in — one the project defined (R362); any other name is refused. Leave out to leave it alone; "" clears it.',
+        },
+        parent: {
+          type: 'string',
+          description:
+            'The card this one sits under (an epic), e.g. "R300". "" takes the card out of its ' +
+            'parent; leave out to leave it alone. Same rules as roadmap_create.',
+        },
       },
       required: ['number'],
     },
@@ -890,7 +929,10 @@ const TOOLS = [
       const entry = await api(config, `/api/projects/${slug}/roadmap/${args.number}`, {
         method: 'PATCH',
         // pick keeps a present 0, which is how a card leaves its sprint.
-        body: pick(args, ['title', 'body', 'section', 'related', 'after', 'sprint', 'tags', 'assignee', 'priority']),
+        body: pick(args, [
+          'title', 'body', 'section', 'related', 'after', 'sprint', 'tags', 'assignee', 'priority',
+          'due', 'estimate', 'targetVersion', 'parent',
+        ]),
       });
       return `Updated ${refOf(entry)}.\n\n${formatEntry(entry, {})}`;
     },
@@ -1154,8 +1196,22 @@ const TOOLS = [
         `run:     ${run.state}${run.runnerName ? ` on ${run.runnerName}` : ''}`,
         `started by ${run.startedByEmail}`,
         '',
-        formatEntry(entry, { comments, plan: plans?.[0] ?? null }),
       );
+      // R336. The epic this card was cut from, so a session sees the context.
+      // Its own try, like the history above: a parent that cannot be read (a
+      // 404, no grant) costs the paragraph and never the call.
+      if (entry.parent) {
+        const epic = await api(config, `/api/projects/${project}/roadmap/${entry.parent.ref}`)
+          .catch(() => null);
+        if (epic) {
+          lines.push(
+            `This card is part of ${entry.parent.ref} — ${epic.title}:`,
+            epicExcerpt(epic.body),
+            '',
+          );
+        }
+      }
+      lines.push(formatEntry(entry, { comments, plan: plans?.[0] ?? null }));
 
       // What happened the other times. A session is told the entry and the
       // branch but not that two previous runs on this card failed, which is
@@ -2173,6 +2229,15 @@ function originWord(origin) {
   }
 }
 
+/** The first 600 characters of an epic's body, cut at a word — R336. */
+function epicExcerpt(body) {
+  const text = (body ?? '').trim();
+  if (text.length <= 600) return text;
+  const cut = text.slice(0, 600);
+  const space = cut.lastIndexOf(' ');
+  return `${(space > 0 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+
 function formatEntry(entry, { brief, comments, plan }) {
   const lines = [`${refOf(entry)} — ${entry.title}`, `  status: ${entry.statusDisplay}`];
   if (entry.branch) lines.push(`  branch: ${entry.branch}`);
@@ -2189,6 +2254,11 @@ function formatEntry(entry, { brief, comments, plan }) {
   if (entry.priority && entry.priority !== 'MEDIUM') {
     lines.push(`  priority: ${entry.priority}`);
   }
+  // R351. Both printed only when the card carries them, as the export does.
+  if (entry.due) lines.push(`  due: ${entry.due}`);
+  if (entry.estimate) lines.push(`  estimate: ${entry.estimate}`);
+  // R358. Printed until the card ships; `version` says where it did.
+  if (entry.targetVersion && !entry.version) lines.push(`  target: ${entry.targetVersion}`);
   // R257. Always printed when the card has one, so a reader's shape does not
   // depend on which tool printed the card; a closed sprint says so.
   if (entry.sprint) {
@@ -2214,6 +2284,14 @@ function formatEntry(entry, { brief, comments, plan }) {
         .join(', ')}`,
     );
   }
+  // R336. The epic this card sits under, and the cards under this one.
+  if (entry.parent) lines.push(`  parent: ${entry.parent.ref} — ${entry.parent.title}`);
+  if (entry.children?.length) {
+    const progress = entry.progress ? `${entry.progress.done} of ${entry.progress.total} done — ` : '';
+    lines.push(
+      `  children: ${progress}${entry.children.map((c) => `${c.ref} (${c.status})`).join(', ')}`,
+    );
+  }
   // Said in a survey, where the comments themselves are not fetched: an entry
   // with an argument attached should be visibly different from one without,
   // even in a list. Omitted at zero rather than written as "comments: 0".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cawdev-cli",
-  "version": "1.0.8-beta",
+  "version": "1.0.9-beta",
   "description": "cawdev's terminal client and runner daemon — zero dependencies, on purpose",
   "type": "module",
   "bin": {