baton-issue-tracker 1.5.0 → 1.7.0

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;
+  }
+}

package/source/commands/next.js

@@ -6,7 +6,7 @@
 import {
   isTrackerReady,
   selectNextIssue,
-  workOnIssue,
+  claimIssue,
 } from '../services/issuesService.js';
 import { formatTimestamp, hasFlag, renderOutput, reportTrackerNotReady, serializeIssue } from '../util.js';
 
@@ -14,7 +14,7 @@ import { formatTimestamp, hasFlag, renderOutput, reportTrackerNotReady, serializ
  * Moves the AI agent to work on the next issue. 
  * Checks if the tracker is ready and if there are any open issues.
  * Prompts user to initialize the tracker if it is not ready.
- * Stats are updated on the issue through workOnIssue function from init.js.
+ * Stats are updated on the issue through claimIssue function from init.js.
  * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
  */
 export async function run(args = []) {
@@ -33,7 +33,7 @@ export async function run(args = []) {
     return 0;
   }
 
-  const updated = workOnIssue(issue.id);
+  const updated = claimIssue(issue.id);
   const envelope = { status: 'success', issue: serializeIssue(updated) };
 
   renderOutput(isJson, envelope, () => {

package/source/commands/priority.js

@@ -0,0 +1,102 @@
+// AI was consulted for some portions of this file.
+// priority.js
+// Sets the priority of an issue.
+// Usage: baton priority <id> <priority>
+//
+// Options:
+//  -h, --help             Show this help
+//  --json                 Output as JSON (for AI agents)
+//
+// Examples:
+//  baton priority 5 high
+//  baton priority 3 low
+
+import { Priority } from '../models/issue.js';
+import { setPriority } from '../services/issuesService.js';
+import { hasFlag, renderOutput, serializeIssue, wantsHelp } from '../util.js';
+
+const HELP = `Usage:
+  baton priority <id> <priority>
+
+Options:
+  -h, --help             Show this help
+  --json                 Output as JSON (for AI agents)
+
+Examples:
+  baton priority 5 high
+  baton priority 3 low
+`;
+
+/**
+ * Normalize CLI priority input to a canonical Priority enum value.
+ * @param {string} input
+ * @returns {string | null}
+ */
+function normalizePriority(input) {
+  const values = Object.values(Priority);
+  return values.find((v) => v.toLowerCase() === input.trim().toLowerCase()) ?? null;
+}
+
+/**
+ * Sets the priority of an issue.
+ * @param {string[]} args - The command line arguments.
+ * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
+ */
+export async function run(args) {
+  if (wantsHelp(args)) {
+    console.log(HELP);
+    return 0;
+  }
+
+  const isJson = hasFlag(args, '--json');
+  const cmdArgs = args.filter((arg) => arg !== '--json');
+
+  if (cmdArgs.length < 2) {
+    throw new Error(
+      'Invalid input: Missing issue ID or priority.\nUsage: baton priority <id> <priority>'
+    );
+  }
+
+  if (cmdArgs.length > 2) {
+    throw new Error(
+      'Invalid input: Too many arguments.\nUsage: baton priority <id> <priority>'
+    );
+  }
+
+  for (const arg of cmdArgs) {
+    if (arg.startsWith('--')) {
+      throw new Error(
+        'Unknown flag provided.\nUsage: baton priority <id> <priority>\nPriority: low | medium | high'
+      );
+    }
+  }
+
+  const id = parseInt(cmdArgs[0], 10);
+  if (Number.isNaN(id)) {
+    throw new Error(
+      'Invalid input: ID must be a number.\nUsage: baton priority <id> <priority>'
+    );
+  }
+
+  const priority = normalizePriority(cmdArgs[1]);
+  if (!priority) {
+    throw new Error(
+      `Invalid priority "${cmdArgs[1]}". Must be one of: low, medium, high.\nUsage: baton priority <id> <priority>`
+    );
+  }
+
+  try {
+    const issue = setPriority(id, priority);
+    const envelope = { status: 'success', issue: serializeIssue(issue) };
+
+    renderOutput(isJson, envelope, () => {
+      console.log(`Issue #${issue.id} priority set to ${issue.priority}.`);
+    });
+
+    return 0;
+  } catch (error) {
+    console.error('Error: Failed to set issue priority.');
+    console.error(error.message);
+    return 1;
+  }
+}

package/source/commands/register.js

@@ -0,0 +1,68 @@
+// register.js
+// AI was consulted for some portions of this file.
+// register command which allows the user to register a new AI agent or human
+// Usage: baton register --name <name> [--type <type>] [--json]
+//
+// Options:
+//  --name <n>        Name of the agent or human (required)
+//  --type <t>        Type: agent | human (default: agent)
+//  --json            Output as JSON (for AI agents)
+//  -h, --help        Show this help
+
+import { registerAgent } from '../services/agentsService.js';
+import {
+  getFlagValue,
+  hasFlag,
+  renderOutput,
+} from '../util.js';
+
+/**
+ * Registers a new agent or human user
+ * @param {string[]} args - The command line arguments
+ * @returns {Promise<number>} The exit code: 0 is success, 1 is error
+ */
+export async function run(args) {
+    const isJson = hasFlag(args, '--json');
+    const validFlags = ['--name', '--type', '--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: --name <n>, --type <t>, --json`);
+            }
+        }
+    }
+
+    try {
+        const name = getFlagValue(args, '--name');
+        const type = getFlagValue(args, '--type') || 'agent';
+
+        if (!name) {
+            throw new Error("Missing required flag: --name <name>");
+        }
+
+        if (type !== 'agent' && type !== 'human') {
+            throw new Error(`Invalid type "${type}". Must be 'agent' or 'human'.`);
+        }
+
+        const agent = registerAgent(name, type);
+        const envelope = { status: 'success', agent };
+
+        renderOutput(isJson, envelope, (data) => {
+            console.log(`\nSuccessfully registered ${data.agent.type}: "${data.agent.name}" (ID: ${data.agent.id})\n`);
+        });
+
+        return 0;
+    } catch (error) {
+        if (error.message.includes('UNIQUE constraint failed')) {
+            console.error(`Error: An agent or user with the name "${getFlagValue(args, '--name')}" is already registered.`);
+        } else if (error.message.includes('Missing required') || error.message.includes('Invalid type')) {
+            console.error(`Usage Error: ${error.message}`);
+        } else {
+            console.error("Error: Failed to register agent.");
+            console.error(error.message);
+        }
+        return 1;
+    }
+}

package/source/commands/update.js

@@ -1,7 +1,8 @@
 // update.js
 // AI was consulted for some portions of this file.
-// update command allows the user to update data fields for an issue 
+// update command allows the user to update data fields for an issue
 // Usage: baton update <id> [options]
+//        baton update <id>              (launches interactive mode pre-filled with current values)
 //
 // Options:
 //  --title <text>         New title
@@ -12,70 +13,252 @@
 //  -h, --help             Show this help
 //
 // Examples:
-// baton update 3 --title "Revised title"
-// baton update 7 --status closed --priority medium
+//  baton update 3                        # interactive mode
+//  baton update 3 --title "Revised title"
+//  baton update 7 --status closed --priority medium
 
 import { updateIssue, getIssue } from "../services/issuesService.js";
-import { hasFlag, parseArgs, renderOutput, serializeIssue } 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_UPDATE_FIELDS = ['title', 'status', 'priority', 'tokenLimit', 'description'];
+
+const VALID_FLAGS = new Set([
+  ...ALLOWED_UPDATE_FIELDS.map(key => issueSchema[key].flag),
+  "--json",
+]);
+const FLAGS_HINT = [...VALID_FLAGS].join(", ");
+const USAGE = "Usage: baton update <id> [options]";
+
+// Build select choices from issueSchema enums so they stay in sync automatically.
+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 STATUS_CHOICES = issueSchema.status.values.map((v) => ({
+  name: v,
+  value: v,
+}));
+
+/**
+ * Opens the user's $EDITOR pre-filled with existing content.
+ * Falls back to the inquirer built-in editor widget if $EDITOR is not set.
+ * Returns null if the user saves without making any changes.
+ *
+ * @param {string} existing  Current description to pre-fill.
+ * @returns {Promise<string|null>}
+ */
+async function openEditorForDescription(existing = "") {
+  const editorBin = process.env.EDITOR || process.env.VISUAL;
+
+  if (!editorBin) {
+    const result = await editor({
+      message: "Description (save & quit when done):",
+      default: existing,
+      waitForUseInput: false,
+    });
+    const cleaned = result.trim();
+    return cleaned !== existing.trim() ? cleaned : null;
+  }
+
+  const tmpPath = join(tmpdir(), `baton-issue-${Date.now()}.md`);
+  writeFileSync(tmpPath, existing, "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 cleaned !== existing.trim() ? cleaned : null;
+}
+
+/**
+ * Prompts the user to edit each field of an existing issue.
+ * Every prompt is pre-filled with the issue's current value so the user
+ * only needs to change what they care about.
+ *
+ * @param {object} issue  The current issue object from the database.
+ * @returns {Promise<object>} Partial options object containing only changed fields.
+ */
+async function runInteractiveMode(issue) {
+  console.log(`\n  Baton -- editing issue #${issue.id}: "${issue.title}"\n`);
+
+  // Collect all prompt results into one object keyed by schema field name.
+  // The diff at the end loops over this -- no field names hardcoded there.
+  const results = {};
+
+  // Title
+  results.title = await input({
+    message: "Title:",
+    default: issue.title,
+    validate: (val) => val.trim().length > 0 || "Title cannot be empty.",
+  });
+
+  // Status
+  results.status = await select({
+    message: "Status:",
+    choices: STATUS_CHOICES,
+    default: issue.status,
+  });
+
+  // Priority
+  results.priority = await select({
+    message: "Priority:",
+    choices: PRIORITY_CHOICES,
+    default: issue.priority,
+  });
+
+  // Token limit -- confirm-gated since it is optional
+  const currentLimit = issue.tokenLimit ?? null;
+  const wantsTokenLimit = await confirm({
+    message: `Set a token limit?${currentLimit ? ` (currently ${currentLimit})` : ""}`,
+    default: currentLimit !== null,
+  });
+  if (wantsTokenLimit) {
+    const raw = await input({
+      message: "Token limit (positive integer):",
+      default: currentLimit ? String(currentLimit) : undefined,
+      validate: (val) => {
+        const n = Number(val);
+        return (Number.isInteger(n) && n > 0) || "Must be a positive integer.";
+      },
+    });
+    results.tokenLimit = Number(raw);
+  }
+
+  // Description - $EDITOR flow, keep original if the user makes no changes
+  const wantsDescription = await confirm({
+    message: "Edit description?",
+    default: true,
+  });
+  if (wantsDescription) {
+    const editorBin = process.env.EDITOR || process.env.VISUAL;
+    const hint = editorBin ? `opens ${editorBin}` : "in-terminal editor";
+    console.log(
+      `  ->  ${hint} -- edit the description, save and quit when done.\n`,
+    );
+    const edited = await openEditorForDescription(issue.description ?? "");
+    // Only write to results if the user actually changed something
+    if (edited !== null) results.description = edited;
+  }
+
+  // Diff: loop over results and collect only what changed.
+  // Adding a new prompt above is all that is needed -- nothing to update here.
+  const pending = Object.fromEntries(
+    Object.entries(results).filter(([key, val]) => val !== issue[key]),
+  );
+
+  if (Object.keys(pending).length === 0) {
+    console.log("\nNo changes made.");
+    process.exit(0);
+  }
+
+  console.log("\n" + "-".repeat(48));
+  for (const [key, val] of Object.entries(pending)) {
+    const old = issue[key] ?? "(none)";
+    const preview = String(val).split("\n").slice(0, 2).join(" ").slice(0, 60);
+    console.log(
+      `  ${key}: "${old}" -> "${preview}${String(val).length > 60 ? "..." : ""}"`,
+    );
+  }
+  console.log("-".repeat(48) + "\n");
+
+  const confirmed = await confirm({ message: "Save changes?", default: true });
+  if (!confirmed) {
+    console.log("Aborted -- no changes saved.");
+    process.exit(0);
+  }
+
+  return pending;
+}
 
 /**
- * Updates the specified fields for a given issue ID 
+ * Updates the specified fields for a given issue ID.
+ * Drops into interactive mode when only an ID is provided and no field flags follow.
+ *
  * @param {string[]} args - The command line arguments
  * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
  */
 export async function run(args) {
-    const isJson = hasFlag(args, '--json');
-    const cmdArgs = args.filter((arg) => arg !== '--json');
+  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>");
-    } 
+  if (cmdArgs.length === 0 || cmdArgs === "") {
+    throw new Error(
+      `Invalid input: No arguments entered.\n${USAGE}\nOptions: ${FLAGS_HINT}`,
+    );
+  }
 
-    // Convert id argument from string to base-10 integer
-    const id = parseInt(cmdArgs[0], 10);
+  // Convert id argument from string to base-10 integer
+  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>");
+  if (isNaN(id)) {
+    throw new Error(
+      `Invalid input: No ID entered.\n${USAGE}\nOptions: ${FLAGS_HINT}`,
+    );
+  }
+
+  // Check if user misspelled a flag
+  for (const arg of cmdArgs) {
+    if (arg.startsWith("--") && !VALID_FLAGS.has(arg)) {
+      throw new Error(`Unknown flag: ${arg}\nValid flags: ${FLAGS_HINT}`);
     }
+  }
+
+  try {
+    const oldIssue = await getIssue(id);
 
-    const validFlags = ['--title', '--description', '--token-limit', '--status', '--priority', '--json'];
-    // Check if user misspelled a flag
-    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>`);
-            }
+    // Interactive mode: only the ID was passed, no field flags.
+    // Flag mode:        at least one flag follows the ID.
+    const providedFlags = cmdArgs.slice(1).filter((a) => a.startsWith("--"));
+    const isInteractive = providedFlags.length === 0;
+
+    const options = isInteractive
+      ? await runInteractiveMode(oldIssue)
+      : parseArgs(cmdArgs.slice(1));
+
+    const newIssue = await updateIssue(id, oldIssue, options);
+    const envelope = { status: "success", issue: serializeIssue(newIssue) };
+
+    renderOutput(isJson, envelope, () => {
+      console.log("");
+      console.log(`Successfully updated issue #${id}:`);
+      for (const key in options) {
+        if (oldIssue[key] !== newIssue[key]) {
+          console.log(`  ${key}: "${oldIssue[key]}" -> "${newIssue[key]}"`);
+        } else {
+          console.log(`  ${key}: No change (already set to "${newIssue[key]}")`);
         }
-    }
+      }
+      console.log("");
+    });
 
-    try {
-        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) };
-
-        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('');
-        });
-
-        return 0;
-    } catch (error) {
-        console.error(`Failed to update issue: ${error.message}`);
-        return 1;
+    return 0;
+  } catch (error) {
+    if (error.name === "ExitPromptError") {
+      console.log("\nAborted.");
+      return 0;
     }
+    console.error(`Failed to update issue: ${error.message}`);
+    return 1;
+  }
 }

package/source/models/activityLog.js

@@ -12,11 +12,13 @@ export class ActivityLog {
   constructor({
     logId     = null,
     issueId,
+    actorId   = null,
     action,
     createdAt = new Date().toISOString(),
   } = {}) {
     this.logId     = logId;
     this.issueId   = issueId;
+    this.actorId   = actorId;
     this.action    = action;
     this.createdAt = createdAt;
   }

package/source/models/agents.js

@@ -0,0 +1,37 @@
+export const AgentType = Object.freeze({
+  AGENT: "agent",
+  HUMAN: "human"
+});
+
+export class Agent {
+  constructor({
+    // User fields
+    name      = "Unnamed",
+    type      = AgentType.AGENT,
+    // Auto-generated fields
+    id        = 0,
+    createdAt = new Date().toISOString(),
+  } = {}) {
+    this.name      = name;
+    this.type      = type;
+    this.id        = id;
+  }
+
+  /**
+   * Validates the agent fields based on project business rules.
+   * @returns {{isValid: boolean, errors: string[]}} boolean and an array of errors
+   */
+  validate() {
+    const errors = [];
+
+    if (!this.name || typeof this.name !== "string" || this.name.trim() === "") {
+        errors.push("Name cannot be empty");
+    }
+
+    if (!Object.values(AgentType).includes(this.type)) {
+      errors.push(`Invalid type "${this.type}". Must be one of: ${Object.values(AgentType).join(", ")}`);
+    }
+
+    return { isValid: errors.length === 0, errors: errors };
+  }
+}

package/source/models/issue.js

@@ -20,7 +20,7 @@ export class Issue {
     tokenLimit  = null,
     description = null,
     lastUpdated = new Date().toISOString(),
-    assignees = null,
+    assigneeId  = null,
     // Auto-generated fields
     id          = 0,
     createdAt  = new Date().toISOString(),
@@ -32,7 +32,7 @@ export class Issue {
     this.tokenLimit  = tokenLimit;
     this.description = description;
     this.lastUpdated = lastUpdated;
-    this.assignees = assignees;
+    this.assigneeId  = assigneeId;
     this.id          = id;
     this.createdAt  = createdAt;
     this.attemptNum = attemptNum;
@@ -68,5 +68,3 @@ export class Issue {
     return {isValid: errors.length == 0, errors: errors}
   }
 }
-
-