baton-issue-tracker 1.13.4 → 1.14.1

package/package.json

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

package/source/cli.js

@@ -31,6 +31,7 @@ import { run as runSubmit } from './commands/submit.js';
 import { run as runUnassign } from './commands/unassign.js';
 import { run as runUnclaim } from './commands/unclaim.js';
 import { run as runClaim } from './commands/claim.js';
+import { run as runAssign} from './commands/assign.js';
 
 import { authenticateContext } from './services/authService.js';
 
@@ -163,6 +164,7 @@ async function main() {
     submit: () => runSubmit(args),
     unassign: () => runUnassign(args),
     unclaim: () => runUnclaim(args),
+    assign: () => runAssign(args),
   };
 
   const handler = handlers[command];

package/source/commands/assign.js

@@ -0,0 +1,66 @@
+// commands/assign.js
+// assign command for the issue tracker
+// usage: baton assign <id> <agent-name> [--json]
+// AI was consulted for a portion of this file
+
+import { getAgentByName } from '../services/agentsService.js';
+import { assignIssue } from '../services/issuesService.js';
+import { getCurrentActor } from '../services/authService.js';
+import { hasFlag, renderOutput } from '../util.js';
+
+const DECIMAL_BASE = 10;
+
+/**
+ * Runs the assign command to associate an issue with a registered agent.
+ * Usage: baton assign <id> <agent-name> [--json]
+ * @param {string[]} args - The command line arguments
+ * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
+ */
+export async function run(args = []) {
+  // Check if the user requested JSON output formatting via the --json flag
+  const isJson = hasFlag(args, '--json');
+  
+  // Strip out any flags starting with '-' to isolate the raw [issueIdStr, agentName] positional arguments
+  const [issueIdStr, agentName] = args.filter(arg => !arg.startsWith('-'));
+
+  // Guard Clause: Ensure both the issue ID and the agent name were provided
+  if (!issueIdStr || !agentName) {
+    console.error('Usage Error: Missing arguments.\nUsage: baton assign <id> <agent-name> [--json]');
+    return 1;
+  }
+
+  // Convert the extracted issue ID string into a safe decimal integer
+  const issueId = parseInt(issueIdStr, DECIMAL_BASE);
+  
+  // Guard Clause: If parsing failed (e.g., the user typed letters instead of an ID), reject it
+  if (isNaN(issueId)) {
+    console.error(`Error: Invalid issue ID "${issueIdStr}". Must be an integer.`);
+    return 1;
+  }
+
+  try {
+    // Look up the current operator. If null, error
+    const actor = getCurrentActor() || Object.assign(new Error('No authenticated context found.'), { isAuthErr: true });
+    // If that identifier property exists, it means the lookup failed; error
+    if (actor.isAuthErr) throw actor;
+
+    // Look up the target assignee by name. If not found, error
+    const target = getAgentByName(agentName) || Object.assign(new Error(`Agent/User "${agentName}" is not registered.`), { isTargetErr: true });
+    // If the lookup failed, throw the target error
+    if (target.isTargetErr) throw target;
+
+    // Execute the assignment in the database layer, passing the parsed ID, assignee ID, and operator ID
+    const issue = assignIssue(issueId, target.id, actor.id);
+
+    // Render the final output payload. If --json is on, it prints raw data. Otherwise, executes callback.
+    renderOutput(isJson, { status: 'success', issueId: issue.id, assignee: { id: target.id, name: target.name, type: target.type } }, () => {
+      console.log(`Success: Issue #${issueId} assigned to "${agentName}"`);
+    });
+    
+    return 0; // Command completed successfully
+  } catch (error) {
+    // Intercepts any thrown operational error (or database crash) and outputs a clean message
+    console.error(`Error: ${error.message}`);
+    return 1; // Return error exit code
+  }
+}

package/source/commands/init.js

@@ -12,8 +12,11 @@
 //  baton init --specs C:\full\path\to\specs.md
 
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { initDB } from '../db/index.js';
+import os from 'node:os';
+import { registerAgent } from '../services/agentsService.js';
 import { Priority } from '../models/issue.js';
 import {
   createIssue,
@@ -156,7 +159,23 @@ export async function run(args = []) {
     clearAllIssues();
   }
 
-  const templatePath = join('docs', 'BATON_AGENT_RULES.md');
+  // auto-register default deployment human user
+  let autoRegisterMessage = '';
+  try {
+    const activeName = process.env.BATON_AGENT || os.userInfo().username;
+    registerAgent(activeName, 'human');
+    autoRegisterMessage = `Auto-registered default human user: "${activeName}"`;
+  } catch (error){
+    if (!error.message?.includes('UNIQUE constraint failed')) {
+      autoRegisterMessage = `Warning: Could not auto-register default user: ${error.message}`;
+    }
+  }
+
+  if (autoRegisterMessage && !isJson) {
+    console.log(autoRegisterMessage);
+  }
+
+  const templatePath = join(dirname(fileURLToPath(import.meta.url)), '..', 'templates', 'BATON_AGENT_RULES.md');
 
   let rulesContent = '';
   if (existsSync(templatePath)) {
@@ -164,13 +183,10 @@ export async function run(args = []) {
   }
 
   const outputPath = join(process.cwd(), 'BATON_AGENT_RULES.md');
-  if (existsSync(outputPath) && !flags.force) {
-    console.error('Error: BATON_AGENT_RULES.md already exists. Use --force to overwrite.');
-    return 1;
+  if (!existsSync(outputPath) || flags.force) {
+    writeFileSync(outputPath, rulesContent, 'utf8');
   }
 
-  writeFileSync(outputPath, rulesContent, 'utf8');
-
   const resolvedSpecsPath = resolvePath(flags.specs, DEFAULT_SPECS_PATH);
   const createdIssues = generateIssuesFromSpecs(flags.specs);
   const envelope = {

package/source/services/issuesService.js

@@ -232,6 +232,7 @@ export function updateIssue(id, oldIssue, { title, description, tokenLimit, stat
     updates.status = toUpdate || status;
   }
 
+
   // Normalize priority argument
   if (priority !== undefined) {
     const priorityValues = Object.values(Priority);
@@ -276,6 +277,30 @@ export function unassignIssue(issueId){
   return getIssue(issueId);
 }
 
+/**
+ * Assigns an issue to a specific registered agent or human.
+ * Logs an edit event.
+ * @param {number} issueId 
+ * @param {number} assigneeId 
+ * @returns {Issue} - the issue that matches the ID
+ */
+export function assignIssue(issueId, assigneeId) {
+  const db = getDB();
+  
+  // Verify the issue exists first (will throw if not found)
+  findById(db, issueId);
+  
+  db.update(issuesTable)
+    .set({ assigneeId: assigneeId })
+    .where(eq(issuesTable.id, issueId))
+    .run();
+
+  // Pass actorId directly instead of hacking the global module variable
+  logActivity(db, issueId, Action.EDIT, `Issue #${issueId} was assigned.`);
+  
+  return getIssue(issueId);
+}
+
 /**
  * Change the status of an issue from in-review to closed
  * Logs a closed event.

package/source/templates/BATON_AGENT_RULES.md

@@ -0,0 +1,47 @@
+# Baton Agent Rules & System Instructions
+
+This document defines the strict operational boundaries and workflows for all AI agents working within this repository. 
+
+## 1. Single Source of Truth
+**Baton is the absolute single source of truth for all tasks, issues, and progress.**
+* **BANNED:** Do not use markdown TODO lists, scratchpad memory files, inline comments for tracking, or any other alternative task management methods.
+* All state, priority, and assignment must be read from and written to the Baton CLI.
+
+## 2. Allowed Commands
+Agents must interface with Baton using the following commands. **You MUST use the `--json` flag** on all commands to ensure machine-readable output.
+
+| Action | Command | Purpose |
+| :--- | :--- | :--- |
+| **Check Identity** | `baton whoami --json` | Verify if you are registered and authorized to work. |
+| **Register Self** | `baton register --name <name> --type agent --json` | Register yourself if `whoami` returns an error or is not found. |
+| **Check Status** | `baton status --json` | View overall progress and issue counts. |
+| **List Issues** | `baton list --status open --json` | View available work (can filter by status/priority). |
+| **Search Issues** | `baton search "<query>" --json` | Search for existing issues to avoid creating duplicates. |
+| **View Issue** | `baton view <id> --json` | Read the full details and requirements of a specific ticket. |
+| **Claim Next Issue** | `baton claim --json` | Automatically claim the highest-priority open issue and mark it `In-Progress`. |
+| **Submit for Review** | `baton submit <id> --json` | Mark a completed task as ready for human approval. |
+| **Unclaim Issue** | `baton unclaim <id> --json` | Relinquish a task if you are stuck or hit the loop limit. |
+| **Update Issue** | `baton update <id> [options] --json` | Update specific fields (e.g., `--description`) if required. |
+| **Create Issue** | `baton create --title "<text>" --json` | Generate a new ticket (e.g., for reporting a bug). |
+| **View History** | `baton log <id> --json` | Check previous attempts, rejections, or actions on a ticket. |
+
+*Note: Commands like `init`, `loop`, `approve`, `reject`, `priority`, and `delete` are strictly reserved for human supervisors or system orchestration.*
+
+## 3. Standard Workflow
+You must strictly adhere to this step-by-step lifecycle for every task:
+
+1. **Authenticate:** Run `baton whoami --json`. If you are not registered, run `baton register --name <your_name> --type agent --json` before proceeding.
+2. **Orient:** Run `baton status --json` to understand the current project state.
+3. **Find Work:** Run `baton list --status open --json` or `baton search --json` to review available issues.
+4. **Claim:** Run `baton claim --json` to automatically assign yourself the highest-priority task. Note the `id` returned.
+5. **Research & Execute:** Read the issue details (`baton view <id> --json`). Perform the necessary research, code changes, and testing to fulfill the requirements.
+6. **Submit for Review:** Once the work is complete and verified locally, run `baton submit <id> --json`. Wait for human approval or rejection.
+
+## 4. Loop Mitigation (The Three-Strike Rule)
+To prevent infinite loops and wasted tokens, you must obey the **Three-Strike Rule**:
+
+* If you attempt a task and fail to resolve it **three consecutive times** (e.g., your tests keep failing, or the human rejects your work three times for the same reason), you MUST:
+  1. Halt execution on the task.
+  2. **Unclaim the issue:** Run `baton unclaim <id> --json` to move it back to `Open`.
+  3. Prepend the issue description with a clear explanation of the failure using `baton update <id> --description "FAILED 3 TIMES: [Your brief explanation] \n\n [Original Description]"`.
+  4. Stop and prompt the human supervisor for intervention and guidance.