baton-issue-tracker 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baton-issue-tracker",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "A CLI issue tracker for AI agents",
   "type": "module",
   "bin": {

package/source/cli.js

@@ -45,26 +45,33 @@ Commands:
 Options:
   init --force                    Re-initialize an existing tracker database
   init --specs <path>             Path to product specs file (overrides default)
+  init --json                     Output as JSON (for AI agents)
   init <path>                     Same as --specs <path> (positional)
   Default specs: docs/specs/project-requirements.md
   loop --steps <n>                Number of autonomous steps (alias: -n)
   loop -n <n>
-  view <id>  
-  search <query>
+  loop --json                     Output as JSON (for AI agents)
+  next --json                     Output as JSON (for AI agents)
+  status --json                   Output as JSON (for AI agents)
+  view <id> [--json]
+  search <query> [--json]
   list --status <s>               Filter by status: open | in-progress | closed
   list --priority <p>             Filter by priority: low | medium | high
   list --limit <n>                Max results (default: 50)
   list --offset <n>               Skip first n results (default: 0)
+  list --json                     Output as JSON (for AI agents)
   create --title <text>           Issue title (defaults to "Issue #<id>" if omitted)
   create --description <text>     Issue description
   create --priority <level>       low | medium | high  (default: low)
   create --token-limit <n>        Optional token budget for this issue
-  approve <id>
+  create --json                   Output as JSON (for AI agents)
+  approve <id> [--json]
   update --title <text>           New title
   update --description <text>     New description
   update --token-limit <n>        New token budget
   update --status <s>             open | in-progress | closed
-  update --priority <level>       low | medium | high  
+  update --priority <level>       low | medium | high
+  update --json                   Output as JSON (for AI agents)
  
 
 Examples:

package/source/commands/approve.js

@@ -4,6 +4,7 @@
 // Usage: baton approve <id>
 
 import { approveIssue } from '../services/issuesService.js';
+import { hasFlag, renderOutput, serializeIssue } from '../util.js';
 
 /**
  * Approves an issue and moves it to the closed state.
@@ -11,14 +12,17 @@ import { approveIssue } from '../services/issuesService.js';
  * @returns {Promise<number>} the exit code: 0 is success, 1 is error
  */
 export async function run(args) {
+    const isJson = hasFlag(args, '--json');
+    const idArgs = args.filter((arg) => arg !== '--json');
+
     //check if id argument is empty
-    if (args.length == 0) {
+    if (idArgs.length == 0) {
         throw new Error(
             'Invalid input: Missing issue ID.\nUsage: baton approve <id>'
         );
     }
 
-    const id = args.join(' ');
+    const id = idArgs.join(' ');
 
     //check if ID argument isn't a number
     if (isNaN(id)) {
@@ -30,9 +34,13 @@ export async function run(args) {
   //try to approve the issue
     try {
         const issue = await approveIssue(id);
-        console.log(
-            `Issue #${issue.id} approved and moved to ${issue.status}.`
-        );
+        const envelope = { status: 'success', issue: serializeIssue(issue) };
+
+        renderOutput(isJson, envelope, () => {
+            console.log(
+                `Issue #${issue.id} approved and moved to ${issue.status}.`
+            );
+        });
 
         return 0;
     } catch (error) {

package/source/commands/create.js

@@ -15,7 +15,7 @@
 
 import { createIssue } from "../services/issuesService.js";
 import { getFlagValue, getNumericFlag } from "../util.js";
-import { parseArgs } from '../util.js';
+import { hasFlag, parseArgs, renderOutput, serializeIssue } from '../util.js';
 
 /**
  * Initializes a new issue in the database with the specified fields
@@ -23,7 +23,8 @@ import { parseArgs } from '../util.js';
  * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
  */
 export async function run(args) {
-    const validFlags = ['--title', '--description', '--priority', '--token-limit'];
+    const isJson = hasFlag(args, '--json');
+    const validFlags = ['--title', '--description', '--priority', '--token-limit', '--json'];
     // Check if user misspelled a flag
     for (const arg of args) {
         if (arg.startsWith('--')) {
@@ -37,9 +38,12 @@ export async function run(args) {
         const options = parseArgs(args);
 
         const issue = await createIssue(options);
+        const envelope = { status: 'success', issue: serializeIssue(issue) };
+
+        renderOutput(isJson, envelope, () => {
+            console.log(`Successfully created issue #${issue.id}: "${issue.title}"`);
+        });
 
-        // program reaches this line if issue was successfully created
-        console.log(`Successfully created issue #${issue.id}: "${issue.title}"`);
         return 0;
     } catch (error) {
         console.error(`Failed to create issue: ${error.message}`);

package/source/commands/init.js

@@ -24,7 +24,9 @@ import {
   getFlagValue,
   getFirstPositionalArg,
   hasFlag,
+  renderOutput,
   resolvePath,
+  serializeIssue,
 } from '../util.js';
 
 /**
@@ -48,7 +50,7 @@ function parseInitFlags(args) {
   const specsFromFlag = getFlagValue(args, '--specs');
   const positionalSpecs = getFirstPositionalArg(args, {
     valueFlags: ['--specs'],
-    ignoreFlags: ['--force'],
+    ignoreFlags: ['--force', '--json'],
   });
 
   if (specsFromFlag && positionalSpecs) {
@@ -132,6 +134,7 @@ function generateIssuesFromSpecs(specsPath) {
  * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
  */
 export async function run(args = []) {
+  const isJson = hasFlag(args, '--json');
   let flags;
   try {
     flags = parseInitFlags(args);
@@ -155,17 +158,26 @@ export async function run(args = []) {
 
   const resolvedSpecsPath = resolvePath(flags.specs, DEFAULT_SPECS_PATH);
   const createdIssues = generateIssuesFromSpecs(flags.specs);
+  const envelope = {
+    status: 'success',
+    db_path: join(process.cwd(), 'data', 'issues.db'),
+    specs_path: resolvedSpecsPath,
+    count: createdIssues.length,
+    issues: createdIssues.map(serializeIssue),
+  };
 
-  console.log(`Tracker initialized at ${join(process.cwd(), 'data', 'issues.db')}`);
-  console.log(`Specs: ${resolvedSpecsPath}`);
-  console.log(`Created ${createdIssues.length} issue(s) from product specs.`);
-  if (createdIssues.length > 0) {
-    console.log('Issues:');
-    for (const issue of createdIssues) {
-      console.log(`  #${issue.id} [${issue.priority}] ${issue.title}`);
+  renderOutput(isJson, envelope, () => {
+    console.log(`Tracker initialized at ${join(process.cwd(), 'data', 'issues.db')}`);
+    console.log(`Specs: ${resolvedSpecsPath}`);
+    console.log(`Created ${createdIssues.length} issue(s) from product specs.`);
+    if (createdIssues.length > 0) {
+      console.log('Issues:');
+      for (const issue of createdIssues) {
+        console.log(`  #${issue.id} [${issue.priority}] ${issue.title}`);
+      }
     }
-  }
-  console.log('Run `baton status` to review progress or `baton next` to start work.');
+    console.log('Run `baton status` to review progress or `baton next` to start work.');
+  });
 
   return 0;
 }

package/source/commands/list.js

@@ -8,11 +8,20 @@
 //  --priority <p>    Filter by priority: low | medium | high
 //  --limit <n>       Max results (default: 50)
 //  --offset <n>      Skip first n results (default: 0)
+//  --json            Output as JSON (for AI agents)
 //  -h, --help        Show this help
 
 import { listIssues } from '../services/issuesService.js';
-import { getFlagValue, getNumericFlag } from '../util.js';
-import { parseArgs, printIssueTable, printTableHeader } from '../util.js';
+import {
+  getFlagValue,
+  getNumericFlag,
+  hasFlag,
+  parseArgs,
+  printIssueTable,
+  printTableHeader,
+  renderOutput,
+  serializeIssue,
+} from '../util.js';
 
 /**
  * Lists issues matching the filters and pagination settings 
@@ -21,12 +30,13 @@ import { parseArgs, printIssueTable, printTableHeader } from '../util.js';
  */
 
 export async function run(args) {
-    const validFlags = ['--status', '--priority', '--limit', '--offset'];
+    const isJson = hasFlag(args, '--json');
+    const validFlags = ['--status', '--priority', '--limit', '--offset', '--json'];
     // Check if user misspelled a flag
     for (const arg of args) {
         if (arg.startsWith('--')) {
             if (!validFlags.includes(arg)) {
-                throw new Error(`Unknown flag provided: ${arg}. \nFlags: --status <s>, --priority <p>, --limit <n>, --offset <n>`);
+                throw new Error(`Unknown flag provided: ${arg}. \nFlags: --status <s>, --priority <p>, --limit <n>, --offset <n>, --json`);
             }
         }
     }
@@ -35,25 +45,29 @@ export async function run(args) {
         const options = parseArgs(args);
 
         const result = await listIssues(options);
+        const issues = result.map(serializeIssue);
+        const envelope = { status: 'success', count: issues.length, issues };
+
+        renderOutput(isJson, envelope, (data) => {
+            if (data.count === 0) {
+                console.log('No issues matching those filters were found.');
+                return;
+            }
 
-        if (result.length == 0) {
-            console.log("No issues matching those filters were found.");
-            return 0;
-        } else {
-           //Logic for table formatting
             const activeFilters = Object.entries(options)
                 .map(([key, value]) => `${key}: ${value}`)
                 .join(', ');
 
-            const filterLog = activeFilters ? `matching filters: [${activeFilters}]` : "with no filters applied";
-            console.log(`\nFound ${result.length} issue(s) ${filterLog}.`);
-            console.log("");
+            const filterLog = activeFilters ? `matching filters: [${activeFilters}]` : 'with no filters applied';
+            console.log(`\nFound ${data.count} issue(s) ${filterLog}.`);
+            console.log('');
 
             printTableHeader();
-            result.forEach(issue => printIssueTable(issue));
-            console.log("");
-            return 0;
-        }
+            result.forEach((issue) => printIssueTable(issue));
+            console.log('');
+        });
+
+        return 0;
     } catch (error) {
         // Separate error message for missing value
         if (error.message.includes('Missing value')) {

package/source/commands/loop.js

@@ -11,7 +11,7 @@
 //  baton loop -n 5
 
 import { isTrackerReady } from '../services/issuesService.js';
-import { getNumericFlag, reportTrackerNotReady } from '../util.js';
+import { getNumericFlag, hasFlag, renderOutput, reportTrackerNotReady } from '../util.js';
 import { run as runNext } from './next.js';
 
 /**
@@ -30,7 +30,9 @@ function parseLoopFlags(args) {
  * @returns {Promise<number>}
  */
 export async function run(args = []) {
-  const { steps } = parseLoopFlags(args);
+  const isJson = hasFlag(args, '--json');
+  const loopArgs = args.filter((arg) => arg !== '--json');
+  const { steps } = parseLoopFlags(loopArgs);
 
   if (!isTrackerReady()) {
     reportTrackerNotReady();
@@ -58,6 +60,8 @@ export async function run(args = []) {
     }
   }
 
-  console.log(`\nCompleted ${completed} autonomous step(s).`);
+  renderOutput(isJson, { status: 'success', steps, completed }, () => {
+    console.log(`\nCompleted ${completed} autonomous step(s).`);
+  });
   return 0;
 }

package/source/commands/next.js

@@ -8,7 +8,7 @@ import {
   selectNextIssue,
   workOnIssue,
 } from '../services/issuesService.js';
-import { formatTimestamp, reportTrackerNotReady } from '../util.js';
+import { formatTimestamp, hasFlag, renderOutput, reportTrackerNotReady, serializeIssue } from '../util.js';
 
 /**
  * Moves the AI agent to work on the next issue. 
@@ -17,7 +17,9 @@ import { formatTimestamp, reportTrackerNotReady } from '../util.js';
  * Stats are updated on the issue through workOnIssue function from init.js.
  * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
  */
-export async function run() {
+export async function run(args = []) {
+  const isJson = hasFlag(args, '--json');
+
   if (!isTrackerReady()) {
     reportTrackerNotReady();
     return 1;
@@ -25,22 +27,27 @@ export async function run() {
 
   const issue = selectNextIssue();
   if (!issue) {
-    console.log('No open issues available. All work is complete or the backlog is empty.');
+    renderOutput(isJson, { status: 'success', issue: null }, () => {
+      console.log('No open issues available. All work is complete or the backlog is empty.');
+    });
     return 0;
   }
 
   const updated = workOnIssue(issue.id);
+  const envelope = { status: 'success', issue: serializeIssue(updated) };
 
-  console.log('Working on next issue:');
-  console.log(`  ID:          #${updated.id}`);
-  console.log(`  Title:       ${updated.title}`);
-  console.log(`  Priority:    ${updated.priority}`);
-  console.log(`  Status:      ${updated.status}`);
-  console.log(`  Attempts:    ${updated.attemptNum}`);
-  console.log(`  Created:     ${formatTimestamp(updated.createdAt)}`);
-  if (updated.description) {
-    console.log(`  Description: ${updated.description}`);
-  }
+  renderOutput(isJson, envelope, () => {
+    console.log('Working on next issue:');
+    console.log(`  ID:          #${updated.id}`);
+    console.log(`  Title:       ${updated.title}`);
+    console.log(`  Priority:    ${updated.priority}`);
+    console.log(`  Status:      ${updated.status}`);
+    console.log(`  Attempts:    ${updated.attemptNum}`);
+    console.log(`  Created:     ${formatTimestamp(updated.createdAt)}`);
+    if (updated.description) {
+      console.log(`  Description: ${updated.description}`);
+    }
+  });
 
   return 0;
 }

package/source/commands/search.js

@@ -4,7 +4,13 @@
 // Usage: baton search "login bug"
 
 import { searchIssues } from "../services/issuesService.js";
-import { printIssueTable, printTableHeader } from '../util.js';
+import {
+  hasFlag,
+  printIssueTable,
+  printTableHeader,
+  renderOutput,
+  serializeIssue,
+} from '../util.js';
 
 /**
  * Searches for a title or description matching the command line argument
@@ -12,27 +18,31 @@ import { printIssueTable, printTableHeader } from '../util.js';
  * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
  */
 export async function run(args) {
-    if (args.length === 0 || args === '') {
+    const isJson = hasFlag(args, '--json');
+    const queryArgs = args.filter((arg) => arg !== '--json');
+
+    if (queryArgs.length === 0 || queryArgs === '') {
         throw new Error("Invalid input: No search term entered.\nUsage: baton search <query>");
     }
 
     try {
-        const query = args.join(' ');
+        const query = queryArgs.join(' ');
         const result = await searchIssues(query);
+        const issues = result.map(serializeIssue);
+        const envelope = { status: 'success', count: issues.length, issues };
 
-        // If no issues with matching title or desc was found
-        if (result.length == 0) {
-            console.log(`No issues containing "${query}" were found.`);
-            return 0;
-        }
-
-        console.log(`\nFound ${result.length} issue(s) containing "${query}":\n`);
+        renderOutput(isJson, envelope, (data) => {
+            if (data.count === 0) {
+                console.log(`No issues containing "${query}" were found.`);
+                return;
+            }
 
-        // Logic for table formatting 
-        printTableHeader();
-        result.forEach(issue => printIssueTable(issue));
+            console.log(`\nFound ${data.count} issue(s) containing "${query}":\n`);
+            printTableHeader();
+            result.forEach((issue) => printIssueTable(issue));
+            console.log('');
+        });
 
-        console.log("");
         return 0;
     } catch (error) {
         // Failed to query database

package/source/commands/status.js

@@ -8,13 +8,15 @@ import {
   getIssueStats,
   getAllIssues,
 } from '../services/issuesService.js';
-import { reportTrackerNotReady } from '../util.js';
+import { hasFlag, renderOutput, reportTrackerNotReady } from '../util.js';
 
 /**
  * Main function that runs the status command.
  * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
  */
-export async function run() {
+export async function run(args = []) {
+  const isJson = hasFlag(args, '--json');
+
   if (!isTrackerReady()) {
     reportTrackerNotReady();
     return 1;
@@ -29,27 +31,55 @@ export async function run() {
     progress = Math.round((stats.closed / stats.total) * 100);
   }
 
-  console.log('Issue Tracker Status');
-  console.log('──────────────────────────────────────────');
-  console.log(`Total issues:     ${stats.total}`);
-  console.log(`Open:             ${stats.open}`);
-  console.log(`In progress:      ${stats.inProgress}`);
-  console.log(`In review:        ${stats.inReview}`);
-  console.log(`Closed:           ${stats.closed}`);
-  console.log(`Overall progress: ${progress}% complete`);
-
-  if (issues.length > 0) {
-    console.log('\nOpen issues by priority:');
-    const byPriority = { High: 0, Medium: 0, Low: 0 };
+  const byPriority = { High: 0, Medium: 0, Low: 0 };
+  if (isJson) {
     for (const issue of issues) {
       if (issue.status === 'Open') {
         byPriority[issue.priority] += 1;
       }
     }
-    console.log(`  High:   ${byPriority.High}`);
-    console.log(`  Medium: ${byPriority.Medium}`);
-    console.log(`  Low:    ${byPriority.Low}`);
   }
 
+  const envelope = {
+    status: 'success',
+    stats: {
+      total: stats.total,
+      open: stats.open,
+      in_progress: stats.inProgress,
+      in_review: stats.inReview,
+      closed: stats.closed,
+      progress_percent: progress,
+    },
+    open_by_priority: {
+      high: byPriority.High,
+      medium: byPriority.Medium,
+      low: byPriority.Low,
+    },
+  };
+
+  renderOutput(isJson, envelope, () => {
+    console.log('Issue Tracker Status');
+    console.log('──────────────────────────────────────────');
+    console.log(`Total issues:     ${stats.total}`);
+    console.log(`Open:             ${stats.open}`);
+    console.log(`In progress:      ${stats.inProgress}`);
+    console.log(`In review:        ${stats.inReview}`);
+    console.log(`Closed:           ${stats.closed}`);
+    console.log(`Overall progress: ${progress}% complete`);
+
+    if (issues.length > 0) {
+      console.log('\nOpen issues by priority:');
+      const byPriority = { High: 0, Medium: 0, Low: 0 };
+      for (const issue of issues) {
+        if (issue.status === 'Open') {
+          byPriority[issue.priority] += 1;
+        }
+      }
+      console.log(`  High:   ${byPriority.High}`);
+      console.log(`  Medium: ${byPriority.Medium}`);
+      console.log(`  Low:    ${byPriority.Low}`);
+    }
+  });
+
   return 0;
 }

package/source/commands/update.js

@@ -16,7 +16,7 @@
 // baton update 7 --status closed --priority medium
 
 import { updateIssue, getIssue } from "../services/issuesService.js";
-import { parseArgs } from '../util.js';
+import { hasFlag, parseArgs, renderOutput, serializeIssue } from '../util.js';
 
 
 /**
@@ -25,20 +25,23 @@ import { parseArgs } from '../util.js';
  * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
  */
 export async function run(args) {
-    if (args.length === 0 || args === '') {
+    const isJson = hasFlag(args, '--json');
+    const cmdArgs = args.filter((arg) => arg !== '--json');
+
+    if (cmdArgs.length === 0 || cmdArgs === '') {
         throw new Error("Invalid input: No arguments entered.\nUsage: baton update <id> [options] \nOptions: --title <text>, --description <text>, --token-limit <n>, --status <s>, --priority <level>");
     } 
 
     // Convert id argument from string to base-10 integer
-    const id = parseInt(args[0], 10);
+    const id = parseInt(cmdArgs[0], 10);
 
     if (isNaN(id)) {
         throw new Error ("Invalid input: No ID entered. \nUsage: baton update <id> [options]\nOptions: --title <text>, --description <text>, --token-limit <n>, --status <s>, --priority <level>");
     }
 
-    const validFlags = ['--title', '--description', '--token-limit', '--status', '--priority'];
+    const validFlags = ['--title', '--description', '--token-limit', '--status', '--priority', '--json'];
     // Check if user misspelled a flag
-    for (const arg of args) {
+    for (const arg of cmdArgs) {
         if (arg.startsWith('--')) {
             if (!validFlags.includes(arg)) {
                 throw new Error(`Unknown flag provided: ${arg}. \nFlags: --title <text>, --description <text>, --token-limit <n>, --status <s>, --priority <level>`);
@@ -47,25 +50,29 @@ export async function run(args) {
     }
 
     try {
-        const options = parseArgs(args.slice(1));
+        const options = parseArgs(cmdArgs.slice(1));
 
         // Store the old issue fields for displaying purposes:
         const oldIssue = getIssue(id);
 
         const newIssue = await updateIssue(id, oldIssue, options);
+        const envelope = { status: 'success', issue: serializeIssue(newIssue) };
 
-        console.log("");
-        // Compare and print the changes:
-        console.log(`Successfully updated issue #${id}:`);
-        for (const key in options) {
-            if (oldIssue[key] !== newIssue[key]) {
-                console.log(`  ${key}: "${oldIssue[key]}" -> "${newIssue[key]}"`);
-            } else {
-                // If the entered argument matches the old data
-                console.log(`  ${key}: No change (already set to "${newIssue[key]}")`);
+        renderOutput(isJson, envelope, () => {
+            console.log('');
+            // Compare and print the changes:
+            console.log(`Successfully updated issue #${id}:`);
+            for (const key in options) {
+                if (oldIssue[key] !== newIssue[key]) {
+                    console.log(`  ${key}: "${oldIssue[key]}" -> "${newIssue[key]}"`);
+                } else {
+                    // If the entered argument matches the old data
+                    console.log(`  ${key}: No change (already set to "${newIssue[key]}")`);
+                }
             }
-        }
-        console.log("");
+            console.log('');
+        });
+
         return 0;
     } catch (error) {
         console.error(`Failed to update issue: ${error.message}`);

package/source/commands/view.js

@@ -1,9 +1,10 @@
 // list.js
 // AI was consulted for some portions of this file.
 // view command which allows user to view all data fields for an issue 
-// Usage: baton view <id>>
+// Usage: baton view <id> [--json]
 
 import { getIssue } from '../services/issuesService.js';
+import { hasFlag, renderOutput, serializeIssue } from '../util.js';
 
 /**
  * Displays all issue fields for a given id #
@@ -11,12 +12,15 @@ import { getIssue } from '../services/issuesService.js';
  * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
  */
 export async function run(args) {
+    const isJson = hasFlag(args, '--json');
+    const idArgs = args.filter((arg) => arg !== '--json');
+
     // checks if id # argument is empty
-    if (args.length == 0) {
+    if (idArgs.length == 0) {
         throw new Error(`Invalid input: Missing Issue ID.\nUsage: baton view <id>`);
     }
 
-    const id = args.join(' ');
+    const id = idArgs.join(' ');
 
     // checks if ID # argument isn't a number
     if (isNaN(id)) {
@@ -25,18 +29,24 @@ export async function run(args) {
 
     try {
         const issue = await getIssue(id);
-
-        if (!issue) {
-            console.log(`No issue with ID #"${issue}" was found.`);
-            return 0;
-        }
-
-        console.log("");
-        Object.entries(issue).forEach(([key, value]) => {
-            console.log(`${key}: ${value}`);
+        const envelope = {
+            status: 'success',
+            issue: issue ? serializeIssue(issue) : null,
+        };
+
+        renderOutput(isJson, envelope, () => {
+            if (!issue) {
+                console.log(`No issue with ID #"${issue}" was found.`);
+                return;
+            }
+
+            console.log('');
+            Object.entries(issue).forEach(([key, value]) => {
+                console.log(`${key}: ${value}`);
+            });
+            console.log('');
         });
 
-        console.log("");
         return 0;
     } catch (error) {
         console.error("Error: Failed to retrieve data.");

package/source/util.js

@@ -189,6 +189,67 @@ export function reportTrackerNotReady() {
   console.error('Run `baton init` first.');
 }
 
+/**
+ * Converts DB-style enum values to lowercase snake_case for JSON output.
+ * e.g. "In-Progress" → "in_progress"
+ * @param {string | null | undefined} value
+ * @returns {string | null}
+ */
+function toJsonEnum(value) {
+  return value?.toLowerCase().replace(/-/g, '_') ?? null;
+}
+
+/**
+ * Normalizes a DB row or Issue instance into a stable JSON-friendly shape.
+ * All commands should serialize through this before building their envelope.
+ * @param {object} issue
+ * @returns {object}
+ */
+export function serializeIssue(issue) {
+  return {
+    id: issue.id,
+    title: issue.title,
+    status: toJsonEnum(issue.status),
+    priority: toJsonEnum(issue.priority),
+    description: issue.description ?? null,
+    token_limit: issue.tokenLimit ?? issue.token_limit ?? null,
+    attempt_num: issue.attemptNum ?? issue.attempt_num ?? 0,
+    created_at: issue.createdAt ?? issue.created_at ?? null,
+    last_updated: issue.lastUpdated ?? issue.last_updated ?? null,
+    assignees: issue.assignees ?? null,
+  };
+}
+
+/**
+ * Centralized output renderer.
+ * If isJson is true, outputs the envelope as JSON.
+ * Otherwise, runs the human-readable callback.
+ * @param {boolean} isJson - Whether the user passed the --json flag
+ * @param {object} envelope - Structured response payload (e.g. { status, issues })
+ * @param {Function} humanOutput - Callback for human terminal styling
+ */
+export function renderOutput(isJson, envelope, humanOutput) {
+  if (isJson) {
+    console.log(JSON.stringify(envelope, null, 2));
+    return;
+  }
+  humanOutput(envelope);
+}
+
+/**
+ * Prints an error in JSON or plain text depending on output mode.
+ * @param {boolean} isJson
+ * @param {string} message
+ * @param {string} [code='ERROR']
+ */
+export function renderError(isJson, message, code = 'ERROR') {
+  if (isJson) {
+    console.error(JSON.stringify({ status: 'error', code, message }));
+    return;
+  }
+  console.error(`Error: ${message}`);
+}
+
 /**
  * Configuration for table column widths.
  */