baton-issue-tracker 1.11.1 → 1.12.0

package/package.json

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

package/source/cli.js

@@ -27,6 +27,7 @@ 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 runUnclaim } from './commands/unclaim.js';
 import { run as runClaim } from './commands/claim.js';
 
 import { authenticateContext } from './services/authService.js';
@@ -47,6 +48,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
+  unclaim  Release a claimed issue back to Open
   claim    Claim an issue as the authenticated agent
   priority Set an issue's priority level
   update   Updates an issue's specified fields
@@ -77,6 +79,7 @@ Options:
   create --json                   Output as JSON (for AI agents)
   approve <id> [--json]
   submit <id> [--json]
+  unclaim <id> [--json]
   claim <id> [--json]
   reject <id> --reason <text>     Reject an issue with a given reason
   priority <id> <level> [--json]  low | medium | high
@@ -106,6 +109,7 @@ Examples:
   baton create --title "Refactor auth" --description "Clean up JWT logic" --token-limit 4000
   baton approve 5
   baton submit 14
+  baton unclaim 14
   baton claim 14
   baton priority 5 high
   baton priority 3 low
@@ -147,6 +151,7 @@ async function main() {
     delete: () => runDelete(args),
     log: () => runLog(args),
     submit: () => runSubmit(args),
+    unclaim: () => runUnclaim(args),
   };
 
   const handler = handlers[command];

package/source/commands/claim.js

@@ -3,7 +3,7 @@
 // Usage: baton claim <id> [--json]
 
 import { isTrackerReady, claimIssue } from '../services/issuesService.js';
-import { getCurrentActor } from '../services/authService.js';
+import { getCurrentActor } from '../services/context.js';
 import {
   hasFlag,
   renderOutput,

package/source/commands/unclaim.js

@@ -0,0 +1,104 @@
+// unclaim.js
+// Allows an agent to release an issue they have previously claimed, returning it to Open.
+// The command verifies the authenticated actor is of type 'agent' and is the current assignee.
+// Usage: baton unclaim <id> [--json]
+//
+// Options:
+//   --json                 Output as JSON (for AI agents)
+//   -h, --help             Show this help
+//
+// Examples:
+//   baton unclaim 14
+
+import { getIssue, unclaimIssue } from '../services/issuesService.js';
+import { getCurrentActor } from '../services/context.js';
+import { AgentType } from '../models/agents.js';
+import {
+  hasFlag,
+  renderOutput,
+  renderError,
+  serializeIssue,
+  wantsHelp,
+} from '../util.js';
+
+const HELP = `baton unclaim — Release a claimed issue back to Open
+
+Usage:
+  baton unclaim <id> [--json]
+
+Options:
+  --json                 Output as JSON (for AI agents)
+  -h, --help             Show this help
+
+Examples:
+  baton unclaim 14
+  > Success: Issue #14 released by agent "claude-dev" and returned to Open.
+`;
+
+/**
+ * Releases an issue back to Open status, clearing the assignee.
+ * @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 idArgs = args.filter((arg) => !arg.startsWith('-'));
+  if (idArgs.length === 0) {
+    renderError(isJson, 'Missing issue ID.\nUsage: baton unclaim <id>', 'MISSING_ID');
+    return 1;
+  }
+
+  const id = Number(idArgs[0]);
+  if (!Number.isInteger(id) || id <= 0) {
+    renderError(isJson, `Invalid ID "${idArgs[0]}". ID must be a positive integer.`, 'INVALID_ID');
+    return 1;
+  }
+
+  const actor = getCurrentActor();
+
+  if (!actor || actor.type !== AgentType.AGENT) {
+    renderError(isJson, 'Only agents can unclaim issues.', 'FORBIDDEN');
+    return 1;
+  }
+
+  let issue;
+  try {
+    issue = getIssue(id);
+  } catch (error) {
+    if (error.message.includes('not found')) {
+      renderError(isJson, error.message, 'NOT_FOUND');
+    } else {
+      renderError(isJson, error.message);
+    }
+    return 1;
+  }
+
+  if (issue.assigneeId !== actor.id) {
+    renderError(
+      isJson,
+      `Issue #${id} is not assigned to you. Only the current assignee can unclaim an issue.`,
+      'FORBIDDEN',
+    );
+    return 1;
+  }
+
+  try {
+    const updatedIssue = unclaimIssue(id);
+    const envelope = { status: 'success', issue: serializeIssue(updatedIssue) };
+
+    renderOutput(isJson, envelope, () => {
+      console.log(`Success: Issue #${id} released by agent "${actor.name}" and returned to Open.`);
+    });
+
+    return 0;
+  } catch (error) {
+    renderError(isJson, error.message);
+    return 1;
+  }
+}

package/source/services/agentsService.js

@@ -41,6 +41,22 @@ export function getAgentByName(name) {
   }
 }
 
+/**
+ * Retrieves an agent by their unique ID.
+ * @param {number} id
+ * @returns {Agent|null}
+ */
+export function getAgentById(id) {
+  const db = getDB();
+  const row = db.select().from(agentsTable).where(eq(agentsTable.id, id)).get();
+
+  if (row) {
+    return new Agent(row);
+  } else {
+    return null;
+  }
+}
+
 /**
  * Lists all registered agents and humans, ordered by id.
  * @returns {Agent[]}

package/source/services/authService.js

@@ -1,8 +1,8 @@
 import os from 'os';
 import { getAgentByName } from './agentsService.js';
-import { setActiveActor } from './issuesService.js';
+import { setCurrentActor, getCurrentActor } from './context.js';
 
-let currentActor = null;
+export { getCurrentActor };
 
 /**
  * Authenticates the current execution context.
@@ -12,17 +12,14 @@ let currentActor = null;
  * @param {string} command - The command being executed
  */
 export function authenticateContext(command) {
-  // Commands that don't require an active agent signed in
   const exemptCommands = ['init', 'register', 'help'];
   if (exemptCommands.includes(command)) {
     return;
   }
 
-  // Identify who is running the CLI
   const activeName = process.env.BATON_AGENT || os.userInfo().username;
-  
+
   try {
-    // Look them up in the database
     const agent = getAgentByName(activeName);
 
     if (!agent) {
@@ -31,25 +28,12 @@ export function authenticateContext(command) {
       process.exit(1);
     }
 
-    // Set the global state for the remainder of this command's lifecycle
-    currentActor = agent;
-    setActiveActor(agent.id);
+    setCurrentActor(agent);
   } catch (error) {
-    // Gracefully handle the scenario where the database hasn't been initialized yet
     if (error.message && error.message.includes('no such table: agents')) {
       console.error("Error: Tracker is not initialized. Please run 'baton init' first.");
       process.exit(1);
     }
-    
-    // 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/services/context.js

@@ -0,0 +1,25 @@
+let currentActor = null;
+
+/**
+ * Sets the active actor for this session.
+ * @param {object|null} actor - The authenticated agent/user object, or null to clear.
+ */
+export function setCurrentActor(actor) {
+  currentActor = actor;
+}
+
+/**
+ * Returns the full authenticated actor object for this session.
+ * @returns {object|null}
+ */
+export function getCurrentActor() {
+  return currentActor;
+}
+
+/**
+ * Returns the ID of the authenticated actor, or null if not set.
+ * @returns {number|null}
+ */
+export function getCurrentActorId() {
+  return currentActor?.id ?? null;
+}

package/source/services/issuesService.js

@@ -7,17 +7,7 @@ import {
   Priority,
 } from "../models/issue.js";
 import { ActivityLog, Action } from '../models/activityLog.js';
-
-// Internal variable to hold the active agent's ID for logging purposes. Set via setActiveActor() during authentication.
-let currentActorId = null;
-
-/**
- * Sets the active actor ID for logging purposes.
- * @param {number} id - The ID of the active actor.
- */
-export function setActiveActor(id) {
-    currentActorId = id;
-}
+import { getCurrentActorId } from './context.js';
 
 /**
  * Internal helper to log actions.
@@ -29,18 +19,10 @@ export function setActiveActor(id) {
  */
 function logActivity(db, issueId, action, details = null) {
   db.insert(activityTable)
-    .values({ issueId, action, details, actorId: currentActorId })
+    .values({ issueId, action, details, actorId: getCurrentActorId() })
     .run();
 }
 
-/**
- * Returns the active actor ID set during authentication.
- * @returns {number|null}
- */
-export function getActiveActor() {
-  return currentActorId;
-}
-
 /**
  * Convert a raw database row to an Issue instance.
  * @private
@@ -491,10 +473,10 @@ export function claimIssue(issueId) {
     logActivity(tx, issueId, Action.READ, `Agent accessed issue #${issueId}`);
     
     tx.update(issuesTable)
-      .set({ 
+      .set({
         status: Status.IN_PROGRESS,
-        assigneeId: currentActorId, 
-        attemptNum: sql`${issuesTable.attemptNum} + 1` 
+        assigneeId: getCurrentActorId(),
+        attemptNum: sql`${issuesTable.attemptNum} + 1`
       })
       .where(eq(issuesTable.id, issueId))
       .run();
@@ -517,6 +499,36 @@ export function claimIssue(issueId) {
   return findById(db, issueId);
 }
 
+/**
+ * Release an issue back to Open status, clearing the assignee.
+ * Logs a STATE_CHANGE activity entry.
+ * @param {number} issueId
+ * @returns {Issue}
+ * @throws {Error} If issueId is invalid or issue is not found
+ */
+export function unclaimIssue(issueId) {
+  if (!Number.isInteger(issueId)) {
+    throw new Error('issueId must be an integer');
+  }
+
+  const db = getDB();
+  findById(db, issueId);
+
+  db.update(issuesTable)
+    .set({ status: Status.OPEN, assigneeId: null })
+    .where(eq(issuesTable.id, issueId))
+    .run();
+
+  logActivity(
+    db,
+    issueId,
+    Action.STATE_CHANGE,
+    `Issue #${issueId} was released and returned to Open.`,
+  );
+
+  return getIssue(issueId);
+}
+
 /**
  * Remove all issues (`baton init --force`). Activity rows are kept for audit.
  */

package/source/util.js

@@ -199,25 +199,36 @@ function toJsonEnum(value) {
   return value?.toLowerCase().replace(/-/g, '_') ?? null;
 }
 
+/**
+ * Converts a camelCase string to snake_case.
+ * @param {string} str
+ * @returns {string}
+ */
+function camelToSnake(str) {
+  return str.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+
 /**
  * Normalizes a DB row or Issue instance into a stable JSON-friendly shape.
- * All commands should serialize through this before building their envelope.
+ * Dynamically built from issueSchema so the output always matches the schema.
  * @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,
-  };
+  const skip = new Set(['limit', 'offset']);
+  const result = {};
+
+  for (const [key, config] of Object.entries(issueSchema)) {
+    if (skip.has(key)) continue;
+    const snakeKey = camelToSnake(key);
+    const value = issue[key] ?? issue[snakeKey] ?? null;
+    result[snakeKey] = config.type === 'enum' ? toJsonEnum(value) : value;
+  }
+
+  result.created_at = issue.createdAt ?? issue.created_at ?? null;
+  result.last_updated = issue.lastUpdated ?? issue.last_updated ?? null;
+
+  return result;
 }
 
 /**