baton-issue-tracker 1.10.0 → 1.11.1

package/README.md

@@ -1,7 +1,8 @@
 # Fantastic Four
 
-## Developer Guide
-[Contributing guide](CONTRIBUTING.md)
+## Documentation
+- [User Guide](docs/USER_GUIDE.md) — How to use Baton CLI.
+- [Developer Guide](docs/CONTRIBUTING.md) — Setting up the development environment.
 
 ## Project Details: 
 TBD

package/package.json

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

package/source/cli.js

@@ -5,8 +5,6 @@
 // usage: baton [command] [options]
 // commands:
 //   init: initialize the tracker
-//   next: work on the next issue
-//   loop: run the agent autonomously for multiple steps
 //   status: show issue counts and overall progress
 //
 // see each command's file for more detailed flags specifications.
@@ -14,8 +12,6 @@
  * Imports the run functions from each command.
  */
 import { run as runInit } from './commands/init.js';
-import { run as runNext } from './commands/next.js';
-import { run as runLoop } from './commands/loop.js';
 import { run as runStatus } from './commands/status.js';
 import { run as runApprove } from './commands/approve.js';
 import { run as runReject } from './commands/reject.js';
@@ -29,7 +25,9 @@ import { run as runDelete } from './commands/delete.js';
 import { run as runPriority } from './commands/priority.js';
 import { run as runLog } from './commands/log.js';
 import { run as runRegister } from './commands/register.js';
+import { run as runAgents } from './commands/agents.js';
 import { run as runSubmit } from './commands/submit.js';
+import { run as runClaim } from './commands/claim.js';
 
 import { authenticateContext } from './services/authService.js';
 
@@ -41,8 +39,7 @@ Usage:
 Commands:
   init     Initialize storage and seed issues from product specs
   register Register a new AI agent or human user
-  next     Work on the highest-priority open issue
-  loop     Run the agent autonomously for multiple steps
+  agents   List all registered agents and humans
   status   Show issue counts and overall progress
   view     View all issue fields for a given issue ID
   search   Search issues by title and description (case insensitive)
@@ -50,6 +47,7 @@ Commands:
   create   Creates an issue with specified fields
   approve  Move an issue from in-review to closed
   submit   Submit finished work for human review
+  claim    Claim an issue as the authenticated agent
   priority Set an issue's priority level
   update   Updates an issue's specified fields
   delete   Deletes an issue
@@ -63,10 +61,7 @@ Options:
   Default specs: docs/specs/project-requirements.md
   register --name <name>          Name of the agent or user
   register --type <type>          agent | human (default: agent)
-  loop --steps <n>                Number of autonomous steps (alias: -n)
-  loop -n <n>
-  loop --json                     Output as JSON (for AI agents)
-  next --json                     Output as JSON (for AI agents)
+  agents [--json]
   status --json                   Output as JSON (for AI agents)
   view <id> [--json]
   search <query> [--json]
@@ -82,6 +77,7 @@ Options:
   create --json                   Output as JSON (for AI agents)
   approve <id> [--json]
   submit <id> [--json]
+  claim <id> [--json]
   reject <id> --reason <text>     Reject an issue with a given reason
   priority <id> <level> [--json]  low | medium | high
   update --title <text>           New title
@@ -99,8 +95,7 @@ Examples:
   baton init ./my-specs.md
   baton init --force
   baton register --name claude-dev --type agent
-  baton next
-  baton loop --steps 5
+  baton agents
   baton status
   baton view 29
   baton search system
@@ -111,6 +106,7 @@ Examples:
   baton create --title "Refactor auth" --description "Clean up JWT logic" --token-limit 4000
   baton approve 5
   baton submit 14
+  baton claim 14
   baton priority 5 high
   baton priority 3 low
   baton update 3 --title "Revised title"
@@ -125,7 +121,7 @@ Examples:
 async function main() {
   const [, , command, ...args] = process.argv;
 
-  if (!command || command === 'help' || wantsHelp(args) || command === '--help') {
+  if (!command || command === 'help' || command === '--help') {
     console.log(HELP);
     process.exit(command ? 0 : 1);
     return;
@@ -137,14 +133,14 @@ async function main() {
   const handlers = {
     init: () => runInit(args),
     register: () => runRegister(args),
-    next: () => runNext(args),
-    loop: () => runLoop(args),
+    agents: () => runAgents(args),
     status: () => runStatus(args),
     view: () => runView(args),
     search: () => runSearch(args),
     list: () => runList(args),
     approve: () => runApprove(args),
     reject: () => runReject(args),
+    claim: () => runClaim(args),
     priority: () => runPriority(args),
     create: () => runCreate(args),
     update: () => runUpdate(args),

package/source/commands/agents.js

@@ -0,0 +1,78 @@
+// agents.js
+// Lists all registered agents and humans in the tracker.
+// Usage: baton agents [--json]
+//
+// Options:
+//   --json                 Output as JSON (for AI agents)
+//   -h, --help             Show this help
+//
+// Examples:
+//   baton agents
+
+import { listAgents } from '../services/agentsService.js';
+import { hasFlag, renderOutput } from '../util.js';
+
+const VALID_FLAGS = ['--json'];
+
+const COL = { id: 4, name: 14, type: 5 };
+
+/**
+ * @param {Agent} agent
+ * @returns {{ id: number, name: string, type: string }}
+ */
+function serializeAgent(agent) {
+  return {
+    id: agent.id,
+    name: agent.name,
+    type: agent.type,
+  };
+}
+
+/**
+ * @param {Agent[]} agents
+ */
+function printAgentsTable(agents) {
+  console.log(
+    `${'ID'.padEnd(COL.id)} | ${'Name'.padEnd(COL.name)} | Type`,
+  );
+  for (const agent of agents) {
+    console.log(
+      `${String(agent.id).padEnd(COL.id)} | ${agent.name.padEnd(COL.name)} | ${agent.type}`,
+    );
+  }
+}
+
+/**
+ * Lists all registered agents and humans.
+ * @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');
+
+  for (const arg of args) {
+    if (arg.startsWith('--') && !VALID_FLAGS.includes(arg)) {
+      throw new Error(`Unknown flag provided: ${arg}.\nFlags: --json`);
+    }
+  }
+
+  try {
+    const agents = listAgents();
+    const records = agents.map(serializeAgent);
+    const envelope = { status: 'success', count: records.length, agents: records };
+
+    renderOutput(isJson, envelope, (data) => {
+      if (data.count === 0) {
+        console.log('No registered agents or humans found.');
+        return;
+      }
+      printAgentsTable(agents);
+    });
+
+    return 0;
+  } catch (error) {
+    console.error('Error: Failed to list agents.');
+    console.error(error.message);
+    return 1;
+  }
+}

package/source/commands/claim.js

@@ -0,0 +1,71 @@
+// claim.js
+// Allows an agent to officially claim an issue to work on.
+// Usage: baton claim <id> [--json]
+
+import { isTrackerReady, claimIssue } from '../services/issuesService.js';
+import { getCurrentActor } from '../services/authService.js';
+import {
+  hasFlag,
+  renderOutput,
+  renderError,
+  getFirstPositionalArg,
+  serializeIssue,
+  reportTrackerNotReady,
+} from '../util.js';
+
+/**
+ * Claims an issue for the authenticated agent.
+ * @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');
+
+  if (hasFlag(args, '-h') || hasFlag(args, '--help')) {
+    console.log(`Usage: baton claim <id> [--json]\n\nOptions:\n  --json                 Output as JSON (for AI agents)\n  -h, --help             Show this help\n\nExamples:\n  baton claim 14`);
+    return 0;
+  }
+
+  const idArg = getFirstPositionalArg(args, { ignoreFlags: ['--json'] });
+
+  if (!idArg) {
+    renderError(isJson, 'Missing issue ID.\nUsage: baton claim <id>', 'MISSING_ID');
+    return 1;
+  }
+
+  const id = Number(idArg);
+  if (!Number.isInteger(id)) {
+    renderError(isJson, `Invalid ID "${idArg}". ID must be an integer.`, 'INVALID_ID');
+    return 1;
+  }
+
+  if (!isTrackerReady()) {
+    reportTrackerNotReady();
+    return 1;
+  }
+
+  const actor = getCurrentActor();
+  if (!actor) {
+    renderError(isJson, 'No authenticated actor found. Please sign in with a registered agent.', 'UNAUTHORIZED');
+    return 1;
+  }
+
+  if (actor.type !== 'agent') {
+    renderError(isJson, 'Only an agent may claim an issue.', 'UNAUTHORIZED');
+    return 1;
+  }
+
+  try {
+    const updatedIssue = claimIssue(id);
+    const envelope = { status: 'success', issue: serializeIssue(updatedIssue) };
+
+    renderOutput(isJson, envelope, () => {
+      console.log(`Success: Issue #${updatedIssue.id} claimed by agent "${actor.name}" and moved to ${updatedIssue.status}.`);
+    });
+
+    return 0;
+  } catch (error) {
+    renderError(isJson, error.message);
+    return 1;
+  }
+}

package/source/commands/init.js

@@ -176,7 +176,7 @@ export async function run(args = []) {
         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.');
   });
 
   return 0;

package/source/services/agentsService.js

@@ -39,4 +39,14 @@ export function getAgentByName(name) {
   } else {
     return null;
   }
+}
+
+/**
+ * Lists all registered agents and humans, ordered by id.
+ * @returns {Agent[]}
+ */
+export function listAgents() {
+  const db = getDB();
+  const rows = db.select().from(agentsTable).orderBy(agentsTable.id).all();
+  return rows.map((row) => new Agent(row));
 }

package/source/services/authService.js

@@ -2,6 +2,8 @@ import os from 'os';
 import { getAgentByName } from './agentsService.js';
 import { setActiveActor } from './issuesService.js';
 
+let currentActor = null;
+
 /**
  * Authenticates the current execution context.
  * Looks for BATON_AGENT in the environment, falling back to the OS username.
@@ -30,6 +32,7 @@ export function authenticateContext(command) {
     }
 
     // Set the global state for the remainder of this command's lifecycle
+    currentActor = agent;
     setActiveActor(agent.id);
   } catch (error) {
     // Gracefully handle the scenario where the database hasn't been initialized yet
@@ -41,4 +44,12 @@ export function authenticateContext(command) {
     // Rethrow if it's a completely different error
     throw error;
   }
+}
+
+/**
+ * Returns the authenticated actor object for this session.
+ * @returns {object|null}
+ */
+export function getCurrentActor() {
+  return currentActor;
 }

package/source/commands/loop.js

@@ -1,67 +0,0 @@
-// loop.js
-// AI was consulted for some portions of this file.
-// loop command for the tracker which allows the AI agent to work autonomously for multiple steps.
-// usage: baton loop [options]
-// options:
-//   --steps <n>: number of steps to run (default: 1)
-//   -n <n>: alias for --steps <n>
-//   <n>: same as --steps <n>
-// examples usage of steps flag:
-//  baton loop --steps 5
-//  baton loop -n 5
-
-import { isTrackerReady } from '../services/issuesService.js';
-import { getNumericFlag, hasFlag, renderOutput, reportTrackerNotReady } from '../util.js';
-import { run as runNext } from './next.js';
-
-/**
- * Parses the flags in the command line argument
- * @param {string[]} args - The command line arguments
- * @returns {{ steps: number }}
- */
-function parseLoopFlags(args) {
-  const stepsFlag = getNumericFlag(args, '--steps') ?? getNumericFlag(args, '-n');
-  return { steps: stepsFlag ?? 1 };
-}
-
-/**
- * Runs the loop command
- * @param {string[]} args
- * @returns {Promise<number>}
- */
-export async function run(args = []) {
-  const isJson = hasFlag(args, '--json');
-  const loopArgs = args.filter((arg) => arg !== '--json');
-  const { steps } = parseLoopFlags(loopArgs);
-
-  if (!isTrackerReady()) {
-    reportTrackerNotReady();
-    return 1;
-  }
-
-  if (!Number.isInteger(steps) || steps < 1) {
-    console.error('Error: --steps must be a positive integer.');
-    console.error('Usage: baton loop --steps <n>');
-    return 1;
-  }
-
-  console.log(`Running baton for ${steps} step(s)...\n`);
-
-  let completed = 0;
-  for (let step = 1; step <= steps; step += 1) {
-    console.log(`--- Step ${step}/${steps} ---`);
-    const code = await runNext();
-    if (code !== 0) {
-      return code;
-    }
-    completed += 1;
-    if (step < steps) {
-      console.log('');
-    }
-  }
-
-  renderOutput(isJson, { status: 'success', steps, completed }, () => {
-    console.log(`\nCompleted ${completed} autonomous step(s).`);
-  });
-  return 0;
-}

package/source/commands/next.js

@@ -1,53 +0,0 @@
-// next.js
-// AI was consulted for some portions of this file.
-// next command for the issue tracker which allows the user to manually move the AI from issue to issue.
-// usage: baton next
-
-import {
-  isTrackerReady,
-  selectNextIssue,
-  claimIssue,
-} from '../services/issuesService.js';
-import { formatTimestamp, hasFlag, renderOutput, reportTrackerNotReady, serializeIssue } from '../util.js';
-
-/**
- * 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 claimIssue function from init.js.
- * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
- */
-export async function run(args = []) {
-  const isJson = hasFlag(args, '--json');
-
-  if (!isTrackerReady()) {
-    reportTrackerNotReady();
-    return 1;
-  }
-
-  const issue = selectNextIssue();
-  if (!issue) {
-    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 = claimIssue(issue.id);
-  const envelope = { status: 'success', issue: serializeIssue(updated) };
-
-  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;
-}