baton-issue-tracker 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baton-issue-tracker",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "A CLI issue tracker for AI agents",
   "type": "module",
   "bin": {
@@ -37,6 +37,7 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
+    "@inquirer/prompts": "^8.5.1",
     "better-sqlite3": "^12.10.0",
     "drizzle-orm": "^0.45.2"
   }

package/source/cli.js

@@ -23,7 +23,9 @@ import { run as runView} from './commands/view.js';
 import { run as runSearch } from './commands/search.js';
 import { run as runList } from './commands/list.js';
 import { run as runCreate } from './commands/create.js'
-import { run as runUpdate } from './commands/update.js'
+import { run as runUpdate } from './commands/update.js';
+import { run as runPriority } from './commands/priority.js';
+import { run as runLog } from './commands/log.js';
 
 const HELP = `baton — AI agent issue tracker CLI
 
@@ -40,32 +42,42 @@ Commands:
   list     Lists issues filtered by status and priority
   create   Creates an issue with specified fields
   approve  Move an issue from in-review to closed
-  update   Updates an issue's specified fields 
+  priority Set an issue's priority level
+  update   Updates an issue's specified fields
+  log      Show activity history for an issue
 
 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]
+  priority <id> <level> [--json]  low | medium | high
   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)
+  log <id> [--json]
 
 Examples:
   baton init
@@ -83,8 +95,11 @@ Examples:
   baton create --title "Fix login bug" --priority high
   baton create --title "Refactor auth" --description "Clean up JWT logic" --token-limit 4000
   baton approve 5
+  baton priority 5 high
+  baton priority 3 low
   baton update 3 --title "Revised title"
   baton update 7 --status closed --priority medium
+  baton log 5
 `;
 
 /**
@@ -94,12 +109,6 @@ Examples:
 async function main() {
   const [, , command, ...args] = process.argv;
 
-  if (!command || command === 'help' || wantsHelp(args) || command === '--help') {
-    console.log(HELP);
-    process.exit(command ? 0 : 1);
-    return;
-  }
-
   const handlers = {
     init: () => runInit(args),
     next: () => runNext(args),
@@ -109,12 +118,25 @@ async function main() {
     search: () => runSearch(args),
     list: () => runList(args),
     approve: () => runApprove(args),
+    priority: () => runPriority(args),
     create: () => runCreate(args),
-    update: () => runUpdate(args)
+    update: () => runUpdate(args),
+    log: () => runLog(args),
   };
-  
+
+  if (!command || command === 'help' || command === '--help') {
+    console.log(HELP);
+    process.exit(command ? 0 : 1);
+    return;
+  }
+
   const handler = handlers[command];
   if (!handler) {
+    if (wantsHelp(args)) {
+      console.log(HELP);
+      process.exit(0);
+      return;
+    }
     console.error(`Error: Unknown command "${command}".`);
     console.error('Run `baton --help` for usage.');
     process.exit(1);

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

@@ -1,48 +1,237 @@
 // create.js
 // AI was consulted for some portions of this file.
-// create command allows the user to create an issue 
+// create command allows the user to create an issue
 // Usage: baton create --title <text> --description <text> --priority <level> --token-limit <n>
-// 
+//        baton create                  (launches interactive prompt mode)
+//
 // Examples:
-// baton create --title "Fix login bug" --priority high
-//  baton create --title "Refactor auth" --description "Clean up JWT logic" --token-limit 4000
+//   baton create --title "Fix login bug" --priority high
+//   baton create --title "Refactor auth" --description "Clean up JWT logic" --token-limit 4000
+//   baton create                         # interactive mode
+//
 // Options:
-//  --title <text>         Issue title (defaults to "Issue #<id>" if omitted)
-//  --description <text>   Issue description
-//  --priority <level>     low | medium | high  (default: low)
-//  --token-limit <n>      Optional token budget for this issue
-//  -h, --help             Show this help
+//   --title <text>         Issue title (defaults to "Issue #<id>" if omitted)
+//   --description <text>   Issue description
+//   --priority <level>     low | medium | high  (default: low)
+//   --token-limit <n>      Optional token budget for this issue
+//   -h, --help             Show this help
 
 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";
+import { issueSchema } from "../models/schema.js";
+import { input, select, confirm, editor } from "@inquirer/prompts";
+import { spawnSync } from "child_process";
+import { writeFileSync, readFileSync, unlinkSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+const ALLOWED_CREATE_FIELDS = ['title', 'priority', 'tokenLimit', 'description'];
+
+const VALID_FLAGS = new Set([
+  ...ALLOWED_CREATE_FIELDS.map(key => issueSchema[key].flag),
+  "--json",
+]);
+
+// Build select choices from issueSchema.priority.values so the list stays in
+// sync with the Priority enum without any duplication.
+const PRIORITY_HINTS = {
+  Low: "routine work, no urgency",
+  Medium: "should be resolved this week",
+  High: "blocking or time-sensitive",
+};
+const PRIORITY_CHOICES = issueSchema.priority.values.map((v) => ({
+  name: `${v.padEnd(6)} -- ${PRIORITY_HINTS[v] ?? v}`,
+  value: v,
+}));
+const DEFAULT_PRIORITY = issueSchema.priority.values[0];
+
+const DESCRIPTION_PLACEHOLDER = [
+  "## What is the issue?",
+  "",
+  "## Steps to reproduce (if applicable)",
+  "",
+  "## Expected vs actual behaviour",
+  "",
+  "## Additional context",
+  "",
+].join("\n");
+
+/**
+ * Opens the user's $EDITOR with an optional seed template and returns the
+ * saved contents, or null if the user left it unchanged / empty.
+ *
+ * Falls back gracefully: if no $EDITOR is set the inquirer `editor` prompt is
+ * used instead (which has its own built-in text area).
+ *
+ * @param {string} template   Initial file content shown to the user.
+ * @returns {Promise<string|null>}
+ */
+async function openEditorForDescription(template = DESCRIPTION_PLACEHOLDER) {
+  const editorBin = process.env.EDITOR || process.env.VISUAL;
+
+  if (!editorBin) {
+    // If no $EDITOR set, then fall back to @inquirer/prompts built-in editor widget
+    const result = await editor({
+      message:
+        "Description (opens in-terminal editor -- save & quit when done):",
+      default: template,
+      waitForUseInput: false,
+    });
+    const cleaned = result.trim();
+    return cleaned && cleaned !== template.trim() ? cleaned : null;
+  }
+
+  // Write template to a temp file, open $EDITOR, read back the result
+  const tmpPath = join(tmpdir(), `baton-issue-${Date.now()}.md`);
+  writeFileSync(tmpPath, template, "utf8");
+
+  const result = spawnSync(editorBin, [tmpPath], { stdio: "inherit" });
+
+  if (result.error) {
+    unlinkSync(tmpPath);
+    throw new Error(
+      `Could not open $EDITOR (${editorBin}): ${result.error.message}`,
+    );
+  }
+
+  const saved = readFileSync(tmpPath, "utf8");
+  unlinkSync(tmpPath);
+
+  const cleaned = saved.trim();
+  // Return null if the user saved without changing anything
+  return cleaned && cleaned !== template.trim() ? cleaned : null;
+}
+
+/**
+ * Guides the user through issue creation with interactive prompts.
+ * @returns {Promise<object>} Options object ready to pass to createIssue()
+ */
+async function runInteractiveMode() {
+  console.log("\n  Baton -- interactive issue creation\n");
+
+  // Title
+  const title = await input({
+    message: "Title:",
+    required: true,
+    validate: (val) => val.trim().length > 0 || "Title cannot be empty.",
+  });
+
+  // Priority
+  const priority = await select({
+    message: "Priority:",
+    choices: PRIORITY_CHOICES,
+    default: DEFAULT_PRIORITY,
+  });
+
+  // Token limit
+  const wantsTokenLimit = await confirm({
+    message: "Set a token limit for this issue?",
+    default: false,
+  });
+
+  let tokenLimit = null;
+  if (wantsTokenLimit) {
+    const raw = await input({
+      message: "Token limit (positive integer):",
+      validate: (val) => {
+        const n = Number(val);
+        return (Number.isInteger(n) && n > 0) || "Must be a positive integer.";
+      },
+    });
+    tokenLimit = Number(raw);
+  }
+
+  // Description
+  const wantsDescription = await confirm({
+    message: "Add a description?",
+    default: true,
+  });
+
+  let description = null;
+  if (wantsDescription) {
+    const editorBin = process.env.EDITOR || process.env.VISUAL;
+    const hint = editorBin ? `opens ${editorBin}` : "in-terminal editor";
+    console.log(
+      `  ->  ${hint} -- fill in what's relevant, save and quit when done.\n`,
+    );
+    description = await openEditorForDescription();
+  }
+
+  // Preview & confirm
+  console.log("\n" + "-".repeat(48));
+  console.log(`  Title      : ${title}`);
+  console.log(`  Priority   : ${priority}`);
+  console.log(`  Token limit: ${tokenLimit ?? "(none)"}`);
+  if (description) {
+    const preview = description.split("\n").slice(0, 3).join(" ").slice(0, 72);
+    console.log(
+      `  Description: ${preview}${description.length > 72 ? "..." : ""}`,
+    );
+  } else {
+    console.log(`  Description: (none)`);
+  }
+  console.log("-".repeat(48) + "\n");
+
+  const confirmed = await confirm({
+    message: "Create this issue?",
+    default: true,
+  });
+  if (!confirmed) {
+    console.log("Aborted -- no issue created.");
+    process.exit(0);
+  }
+
+  return { title, priority, tokenLimit, description };
+}
 
 /**
  * Initializes a new issue in the database with the specified fields
+ * Drops into interactive mode when no flags are provided
+ *
  * @param {string[]} args - The command line arguments
- * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
+ * @returns {Promise<number>} The exit code: 0 is success, 1 is error
  */
 export async function run(args) {
-    const validFlags = ['--title', '--description', '--priority', '--token-limit'];
-    // 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: --title <text>, --description <text>, --priority <level>, --token-limit <n>`);
-            }
-        }
+  const isJson = hasFlag(args, "--json");
+
+  // Flag validation -- VALID_FLAGS is derived from issueSchema, so this stays
+  // current automatically when fields are added or renamed there
+  const providedFlags = args.filter((a) => a.startsWith("--"));
+  for (const flag of providedFlags) {
+    if (!VALID_FLAGS.has(flag)) {
+      const knownFlags = [...VALID_FLAGS].join(", ");
+      throw new Error(
+        `Unknown flag: ${flag}\nValid flags: ${knownFlags}\n` +
+          `Tip: run \`baton create\` with no flags to use interactive mode.`,
+      );
     }
+  }
+
+  try {
+    // Interactive mode: no flags provided (human at a keyboard)
+    // Flag mode:        at least one flag present (scripts, CI, power users)
+    const nonJsonFlags = providedFlags.filter((f) => f !== "--json");
+    const isInteractive = nonJsonFlags.length === 0;
+
+    const options = isInteractive
+      ? await runInteractiveMode()
+      : parseArgs(args);
 
-    try {
-        const options = parseArgs(args);
+    const issue = await createIssue(options);
+    const envelope = { status: "success", issue: serializeIssue(issue) };
 
-        const issue = await createIssue(options);
+    renderOutput(isJson, envelope, () => {
+      console.log(`\nCreated 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}`);
-        return 1;
+    return 0;
+  } catch (error) {
+    // when user hits Ctrl+C
+    if (error.name === "ExitPromptError") {
+      console.log("\nAborted.");
+      return 0;
     }
+    console.error(`Failed to create issue: ${error.message}`);
+    return 1;
+  }
 }

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/log.js

@@ -0,0 +1,85 @@
+// AI was consulted for some portions of this file.
+// log.js
+// log command which displays the full activity history for an issue
+// Usage: baton log <id>
+//
+// Options:
+//   -h, --help    Show this help
+//   --json        Output as JSON (for AI agents)
+//
+// Examples:
+//   baton log 5
+
+import { getActivityLog } from '../services/issuesService.js';
+import { formatTimestamp, hasFlag } from '../util.js';
+
+/**
+ * Serializes an activity log entry for JSON output.
+ * @param {object} entry
+ * @returns {object}
+ */
+function serializeLogEntry(entry) {
+  return {
+    log_id: entry.logId,
+    issue_id: entry.issueId,
+    action: entry.action,
+    details: entry.details ?? null,
+    created_at: entry.createdAt,
+  };
+}
+
+/**
+ * Displays the full activity history for a given issue ID.
+ * @param {string[]} args - The issue ID
+ * @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');
+
+  if (idArgs.length === 0) {
+    throw new Error('Invalid input: Missing Issue ID.\nUsage: baton log <id>');
+  }
+
+  const id = idArgs.join(' ');
+
+  if (isNaN(id)) {
+    throw new Error('Invalid input: ID must be a number.\nUsage: baton log <id>');
+  }
+
+  try {
+    const logs = getActivityLog(Number(id));
+    const entries = logs.map(serializeLogEntry);
+    const envelope = {
+      status: 'success',
+      issue_id: Number(id),
+      count: entries.length,
+      entries,
+    };
+
+    if (isJson) {
+      console.log(JSON.stringify(envelope, null, 2));
+      return 0;
+    }
+
+    if (entries.length === 0) {
+      console.log(`No activity history for issue #${id}.`);
+      return 0;
+    }
+
+    console.log(`Activity log for issue #${id}`);
+    console.log('──────────────────────────────────────────');
+    for (const entry of entries) {
+      const timestamp = formatTimestamp(entry.created_at);
+      const details = entry.details ?? '';
+      console.log(`${timestamp}  ${entry.action}  ${details}`);
+    }
+    console.log('');
+
+    return 0;
+  } catch (error) {
+    console.error('Error: Failed to retrieve activity log.');
+    console.error(error.message);
+    return 1;
+  }
+}