baton-issue-tracker 1.13.2 → 1.13.3

package/README.md

@@ -1,14 +1,84 @@
-# Fantastic Four
+<p align="center">
+  <img src="./admin/branding/teamLogo.png" width="100">
+</p>
 
-## Documentation
-- [User Guide](docs/USER_GUIDE.md) — How to use Baton CLI.
-- [Developer Guide](docs/CONTRIBUTING.md) — Setting up the development environment.
+# Baton Issue Tracker (Baton)
 
-## Project Details: 
-TBD
+[![NPM Version](https://img.shields.io/npm/v/baton-issue-tracker)](https://www.npmjs.com/package/baton-issue-tracker)
 
-# Team Page
-[Click Here](/admin/team.md)
+**Baton** is a terminal-first issue tracker designed for the modern AI-augmented software engineering workflow. It provides a structured interface for human supervisors to manage, track, and approve tasks performed by autonomous AI agents.
 
-# Agile: Team Status Video
-[https://youtu.be/xToi68JAcwk](https://youtu.be/xToi68JAcwk)
+In an environment where AI does much of the heavy lifting, Baton ensures accountability, tracks token budgets, and maintains a rigorous audit trail of every change made to your project's backlog.
+
+**Baton** is developed and maintained by **Team Fantastic Four**.
+
+--- 
+
+## Quickstart
+
+Get up and running with Baton in seconds.
+
+### 1. Installation
+Install Baton globally via NPM:
+```bash
+npm install -g baton-issue-tracker
+```
+
+### 2. Initialization
+Initialize a new tracker in your project root. This creates a local SQLite database at `.baton/baton.db`.
+```bash
+baton init
+```
+
+### 3. Check Identity
+Verify your registration or add yourself to the project:
+```bash
+baton whoami
+# If not registered:
+baton register --name "your-name" --type human
+```
+
+### 4. Basic Workflow
+* **Create a task:** `baton create --title "Fix login bug" --priority high`
+* **Check status:** `baton status`
+* **Claim next task (for agents):** `baton claim`
+* **Submit work (for agents):** `baton submit <id>`
+* **Approve work (for humans):** `baton approve <id>`
+
+---
+
+## Features
+
+*   **AI-Native API:** All commands support a `--json` flag for easy integration with AI agent loops.
+*   **Human-in-the-Loop:** A strict state machine ensuring agents can only resolve issues with human approval.
+*   **Full Activity History:** Track every edit, status change, and assignment with `baton log`.
+*   **Token Management:** Assign token limits to specific issues to control agent costs.
+*   **Zero-Config Storage:** Fully local SQLite storage—no external servers required.
+
+---
+
+## Documentation Index
+
+Baton is extensively documented to help both humans and agents get the most out of the system:
+
+### **Guides**
+*   [**CLI Reference**](./docs/cli/README.md): Detailed documentation for every command and flag.
+*   [**Setup & Workflow**](./docs/cli/setup-commands.md): How to initialize and manage the agent work-loop.
+*   [**Issue Management**](./docs/cli/issue-commands.md): Deep dive into ticket CRUD and review processes.
+*   [**Contributing**](./CONTRIBUTING.md): Guidelines for developing and extending Baton.
+
+### **Specifications**
+*   [**Product Requirements**](./docs/specs/project-requirements.md): The functional goals of the project.
+*   [**Data Model**](./docs/specs/issue-data-model.md): Detailed schema for issues and activity logs.
+*   [**ADRs (Architecture Decisions)**](./docs/adr/): Why we built Baton the way we did.
+
+---
+
+## Team
+Baton is developed and maintained by **Team Fantastic Four** (CSE 110, SP26). 
+Meet the team on our [**Team Page**](./admin/team.md).
+
+---
+
+## License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/package.json

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

package/source/cli.js

@@ -136,7 +136,7 @@ async function main() {
   }
 
   // Authenticate the user and context before executing any command.
-  authenticateContext(command);
+  authenticateContext(command, args);
 
   const handlers = {
     init: () => runInit(args),

package/source/commands/log.js

@@ -22,8 +22,9 @@ function serializeLogEntry(entry) {
   return {
     log_id: entry.logId,
     issue_id: entry.issueId,
+    actor_id: entry.actorId,
     action: entry.action,
-    details: entry.details ?? null,
+    details: entry.details,
     created_at: entry.createdAt,
   };
 }

package/source/db/index.js

@@ -18,7 +18,8 @@ if (!fs.existsSync(dataDir)) {
 }
 
 // Initialize better-sqlite3 connection
-const sqliteConnection = new Database(dbPath);
+// Using let here so we can reassign it in tests with an in-memory database instance.
+let sqliteConnection = new Database(dbPath);
 
 // Initialize Drizzle ORM, passing in the schema for relational queries
 // Using let here so we can reassign it in tests with an in-memory database instance.
@@ -71,6 +72,7 @@ export function getSQLiteDB() {
 }
 
 // function for the test suite mocking
-export function setTestDB(testDbInstance) {
+export function setTestDB(testDbInstance, testSqliteConnection) {
   db = testDbInstance;
+  if (testSqliteConnection) sqliteConnection = testSqliteConnection;
 }

package/source/models/activityLog.js

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

package/source/services/agentRestrictions.js

@@ -0,0 +1,26 @@
+// agentRestrictions.js 
+
+const AGENT_RESTRICTED_COMMANDS = new Set(['init', 'approve', 'reject', 'delete', 'priority']);
+const AGENT_RESTRICTED_FLAGS = new Set(['--status', '--token-limit']);
+
+/**
+ * Validates whether an actor has permission to execute a given command and arguments.
+ * @param {string} command - The primary CLI command name.
+ * @throws {Error} If the agent entered a restricted command or flag
+ */
+export function authorizeAction(command, args = []) {
+  if (AGENT_RESTRICTED_COMMANDS.has(command)) {
+    throw new Error(`Command "${command}" is restricted to human users only.`);
+  }
+
+  if (command === 'update') {
+    const args = process.argv.slice(2); 
+    const usedRestricted = args.filter(arg => AGENT_RESTRICTED_FLAGS.has(arg));
+    if (usedRestricted.length > 0) {
+      throw new Error(
+        `Agents cannot update parameters: ${usedRestricted.join(', ')}. ` +
+        `Use 'baton claim', 'baton submit', or 'baton unclaim' for status changes.`
+      );
+    }
+  }
+}

package/source/services/authService.js

@@ -1,6 +1,8 @@
 import os from 'os';
 import { getAgentByName } from './agentsService.js';
 import { setCurrentActor, getCurrentActor } from './context.js';
+import { isTrackerReady } from './issuesService.js';
+import { authorizeAction } from './agentRestrictions.js';
 
 export { getCurrentActor };
 
@@ -11,29 +13,33 @@ export { getCurrentActor };
  * If not, it terminates the process with a helpful error message.
  * @param {string} command - The command being executed
  */
-export function authenticateContext(command) {
-  const exemptCommands = ['init', 'register', 'help'];
+export function authenticateContext(command, args = []) {
+  const exemptCommands = ['register', 'help'];
   if (exemptCommands.includes(command)) {
     return;
   }
 
-  const activeName = process.env.BATON_AGENT || os.userInfo().username;
-
-  try {
-    const agent = getAgentByName(activeName);
+  if (!isTrackerReady()) {
+    if (command === 'init') {
+      return;
+    }
+    console.error("Error: Tracker is not initialized. Please run 'baton init' first.");
+    process.exit(1);
+  }
 
-    if (!agent) {
+  const activeName = process.env.BATON_AGENT || os.userInfo().username;
+  const agent = getAgentByName(activeName);
+    
+  if (!agent) {
       console.error(`Error: Agent/User "${activeName}" is not registered in this Baton tracker.`);
       console.error(`Please run 'baton register --name "${activeName}" --type "human"' (or "agent") first.`);
       process.exit(1);
-    }
+  }
 
-    setCurrentActor(agent);
-  } catch (error) {
-    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);
-    }
-    throw error;
+  // Check if agent entered a restricted command
+  if (agent.type === 'agent') {
+    authorizeAction(command, args);
   }
+
+  setCurrentActor(agent);
 }

package/source/services/issuesService.js

@@ -384,7 +384,7 @@ export function deleteIssue(id) {
  */
 export function getActivityLog(issueId) {
   const db = getDB();
-  return db.select().from(activityTable).where(eq(activityTable.issueId, issueId)).all();
+  return db.select().from(activityTable).where(eq(activityTable.issueId, issueId)).all().map(rowToLog);
 }
 
 /**
@@ -394,7 +394,7 @@ export function getActivityLog(issueId) {
  */
 export function getRecentActivity({ limit = 20 } = {}) {
   const db = getDB();
-  return db.select().from(activityTable).orderBy(sql`${activityTable.logId} DESC`).limit(limit).all();
+  return db.select().from(activityTable).orderBy(sql`${activityTable.logId} DESC`).limit(limit).all().map(rowToLog);
 }
 // =============================================================================
 // Tracker operations (CLI: init / next / status / claim)