baton-issue-tracker 1.3.1

package/source/commands/init.js

@@ -0,0 +1,171 @@
+// init.js
+// AI was consulted for large portions of this file.
+// init command for the issue tracker
+// usage: baton init [options] [<specs-path>]
+// options:
+//   --force: force initialization even if the tracker is already initialized
+//   --specs <path>: path to the specs file (default: docs/specs/project-requirements.md)
+//   <specs-path>: optional positional path to specs (same as --specs)
+//
+// examples usage of specs flag:
+//  baton init --specs ./path/to/my-specs.md
+//  baton init --specs C:\full\path\to\specs.md
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { initDB } from '../db/index.js';
+import { Priority } from '../models/issue.js';
+import {
+  createIssue,
+  isTrackerReady,
+  clearAllIssues,
+} from '../services/issuesService.js';
+import {
+  getFlagValue,
+  getFirstPositionalArg,
+  hasFlag,
+  resolvePath,
+} from '../util.js';
+
+/**
+ * Default path to the specs file
+ */
+const DEFAULT_SPECS_PATH = join('docs', 'specs', 'project-requirements.md');
+
+/**
+ * Represents the parsed command-line flags for initialization.
+ * @typedef {Object} InitFlags
+ * @property {boolean} force - Whether to force initialization even if already initialized.
+ * @property {string | null} specs - The resolved path to the specifications file.
+ */
+
+/**
+ * Parses the initialization flags.
+ * @param {string[]} args
+ * @returns {InitFlags}
+ */
+function parseInitFlags(args) {
+  const specsFromFlag = getFlagValue(args, '--specs');
+  const positionalSpecs = getFirstPositionalArg(args, {
+    valueFlags: ['--specs'],
+    ignoreFlags: ['--force'],
+  });
+
+  if (specsFromFlag && positionalSpecs) {
+    throw new Error('Pass specs path with either --specs <path> or a positional path, not both.');
+  }
+
+  return {
+    force: hasFlag(args, '--force'),
+    specs: specsFromFlag ?? positionalSpecs,
+  };
+}
+
+/**
+ * Represents a discrete requirement parsed from the markdown specs.
+ * @typedef {Object} Requirement
+ * @property {string} title - The title or ID of the requirement (e.g., FR-1).
+ * @property {string} description - The detailed breakdown of the requirement.
+ * @property {string} priority - The assigned urgency level.
+ */
+
+/**
+ * Parses the must requirements from the markdown file.
+ * Likely to be changed in future iterations when AI implementation is added.
+ * @param {string} markdown
+ * @returns {Requirement[]}
+ */
+function parseMustRequirements(markdown) {
+  const issues = [];
+  const lines = markdown.split('\n');
+
+  for (const line of lines) {
+    if (!line.includes('| Must |')) {
+      continue;
+    }
+    const cells = line.split('|').map((cell) => cell.trim()).filter(Boolean);
+    if (cells.length < 3) {
+      continue;
+    }
+    const id = cells[0];
+    const requirement = cells[2];
+    if (!/^FR-/.test(id) || !requirement) {
+      continue;
+    }
+    issues.push({
+      title: id,
+      description: requirement,
+      priority: Priority.MEDIUM,
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * Generates issues from the specs file.
+ * @param {string | null} specsPath
+ * @returns {Issue[]}
+ */
+function generateIssuesFromSpecs(specsPath) {
+  const resolvedPath = resolvePath(specsPath, DEFAULT_SPECS_PATH);
+
+  if (!existsSync(resolvedPath)) {
+    throw new Error(
+      `Specs file not found at ${resolvedPath}. Pass --specs <path> or provide a positional path.`,
+    );
+  }
+
+  const markdown = readFileSync(resolvedPath, 'utf8');
+  const requirements = parseMustRequirements(markdown);
+
+  if (requirements.length === 0) {
+    return [];
+  }
+
+  return requirements.map((req) => createIssue(req));
+}
+
+/**
+ * Runs the init command
+ * @param {string[]} args - The command line arguments
+ * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
+ */
+export async function run(args = []) {
+  let flags;
+  try {
+    flags = parseInitFlags(args);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    console.error('Usage: baton init [--force] [--specs <path>] [<specs-path>]');
+    return 1;
+  }
+
+  if (isTrackerReady() && !flags.force) {
+    console.error('Error: Tracker already initialized in this directory.');
+    console.error('Run `baton init --force` to re-initialize.');
+    return 1;
+  }
+
+  initDB();
+
+  if (flags.force) {
+    clearAllIssues();
+  }
+
+  const resolvedSpecsPath = resolvePath(flags.specs, DEFAULT_SPECS_PATH);
+  const createdIssues = generateIssuesFromSpecs(flags.specs);
+
+  console.log(`Tracker initialized at ${join(process.cwd(), 'data', 'issues.db')}`);
+  console.log(`Specs: ${resolvedSpecsPath}`);
+  console.log(`Created ${createdIssues.length} issue(s) from product specs.`);
+  if (createdIssues.length > 0) {
+    console.log('Issues:');
+    for (const issue of createdIssues) {
+      console.log(`  #${issue.id} [${issue.priority}] ${issue.title}`);
+    }
+  }
+  console.log('Run `baton status` to review progress or `baton next` to start work.');
+
+  return 0;
+}

package/source/commands/list.js

@@ -0,0 +1,67 @@
+// list.js
+// AI was consulted for some portions of this file.
+// list command which allows the user to view a list of issues matching the filter flags
+// Usage: baton list [--status <s>] [--priority <p>] [--limit <n>] [--offset <n>]
+//
+// Options:
+//  --status <s>      Filter by status: open | in-progress | closed
+//  --priority <p>    Filter by priority: low | medium | high
+//  --limit <n>       Max results (default: 50)
+//  --offset <n>      Skip first n results (default: 0)
+//  -h, --help        Show this help
+
+import { listIssues } from '../services/issuesService.js';
+import { getFlagValue, getNumericFlag } from '../util.js';
+import { parseArgs, printIssueTable, printTableHeader } from '../util.js';
+
+/**
+ * Lists issues matching the filters and pagination settings 
+ * @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 validFlags = ['--status', '--priority', '--limit', '--offset'];
+    // 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: --status <s>, --priority <p>, --limit <n>, --offset <n>`);
+            }
+        }
+    }
+
+    try {
+        const options = parseArgs(args);
+
+        const result = await listIssues(options);
+
+        if (result.length == 0) {
+            console.log("No issues matching those filters were found.");
+            return 0;
+        } else {
+           //Logic for table formatting
+            const activeFilters = Object.entries(options)
+                .map(([key, value]) => `${key}: ${value}`)
+                .join(', ');
+
+            const filterLog = activeFilters ? `matching filters: [${activeFilters}]` : "with no filters applied";
+            console.log(`\nFound ${result.length} issue(s) ${filterLog}.`);
+            console.log("");
+
+            printTableHeader();
+            result.forEach(issue => printIssueTable(issue));
+            console.log("");
+            return 0;
+        }
+    } catch (error) {
+        // Separate error message for missing value
+        if (error.message.includes('Missing value')) {
+            console.error(`Usage Error: ${error.message}`);
+        } else {
+            console.error("Error: Failed to retrieve data.");
+            console.error(error.message);
+        }
+        return 1;
+    }
+}

package/source/commands/loop.js

@@ -0,0 +1,63 @@
+// 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, 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 { steps } = parseLoopFlags(args);
+
+  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('');
+    }
+  }
+
+  console.log(`\nCompleted ${completed} autonomous step(s).`);
+  return 0;
+}

package/source/commands/next.js

@@ -0,0 +1,46 @@
+// 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,
+  workOnIssue,
+} from '../services/issuesService.js';
+import { formatTimestamp, reportTrackerNotReady } 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 workOnIssue function from init.js.
+ * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
+ */
+export async function run() {
+  if (!isTrackerReady()) {
+    reportTrackerNotReady();
+    return 1;
+  }
+
+  const issue = selectNextIssue();
+  if (!issue) {
+    console.log('No open issues available. All work is complete or the backlog is empty.');
+    return 0;
+  }
+
+  const updated = workOnIssue(issue.id);
+
+  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;
+}

package/source/commands/search.js

@@ -0,0 +1,44 @@
+// search.js
+// AI was consulted for some portions of this file.
+// search command which allows the user to search for issues by keywords (case insensitive).
+// Usage: baton search "login bug"
+
+import { searchIssues } from "../services/issuesService.js";
+import { printIssueTable, printTableHeader } from '../util.js';
+
+/**
+ * Searches for a title or description matching the command line argument
+ * @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 (args.length === 0 || args === '') {
+        throw new Error("Invalid input: No search term entered.\nUsage: baton search <query>");
+    }
+
+    try {
+        const query = args.join(' ');
+        const result = await searchIssues(query);
+
+        // If no issues with matching title or desc was found
+        if (result.length == 0) {
+            console.log(`No issues containing "${query}" were found.`);
+            return 0;
+        }
+
+        console.log(`\nFound ${result.length} issue(s) containing "${query}":\n`);
+
+        // Logic for table formatting 
+        printTableHeader();
+        result.forEach(issue => printIssueTable(issue));
+
+        console.log("");
+        return 0;
+    } catch (error) {
+        // Failed to query database
+        console.error("Error: Failed to retrieve data.");
+        console.error(error.message);
+        return 1;
+    }
+} 
+

package/source/commands/status.js

@@ -0,0 +1,55 @@
+// status.js
+// AI was consulted for some portions of this file.
+// status command for the issue tracker which allows the user to see the status of the tracker.
+// usage: baton status
+
+import {
+  isTrackerReady,
+  getIssueStats,
+  getAllIssues,
+} from '../services/issuesService.js';
+import { reportTrackerNotReady } from '../util.js';
+
+/**
+ * Main function that runs the status command.
+ * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
+ */
+export async function run() {
+  if (!isTrackerReady()) {
+    reportTrackerNotReady();
+    return 1;
+  }
+
+  const stats = getIssueStats();
+  const issues = getAllIssues();
+  let progress;
+  if (stats.total === 0) {
+    progress = 0;
+  } else {
+    progress = Math.round((stats.closed / stats.total) * 100);
+  }
+
+  console.log('Issue Tracker Status');
+  console.log('──────────────────────────────────────────');
+  console.log(`Total issues:     ${stats.total}`);
+  console.log(`Open:             ${stats.open}`);
+  console.log(`In progress:      ${stats.inProgress}`);
+  console.log(`In review:        ${stats.inReview}`);
+  console.log(`Closed:           ${stats.closed}`);
+  console.log(`Overall progress: ${progress}% complete`);
+
+  if (issues.length > 0) {
+    console.log('\nOpen issues by priority:');
+    const byPriority = { High: 0, Medium: 0, Low: 0 };
+    for (const issue of issues) {
+      if (issue.status === 'Open') {
+        byPriority[issue.priority] += 1;
+      }
+    }
+    console.log(`  High:   ${byPriority.High}`);
+    console.log(`  Medium: ${byPriority.Medium}`);
+    console.log(`  Low:    ${byPriority.Low}`);
+  }
+
+  return 0;
+}

package/source/commands/update.js

@@ -0,0 +1,74 @@
+// update.js
+// AI was consulted for some portions of this file.
+// update command allows the user to update data fields for an issue 
+// Usage: baton update <id> [options]
+//
+// Options:
+//  --title <text>         New title
+//  --description <text>   New description
+//  --token-limit <n>      New token budget
+//  --status <s>           open | in-progress | closed
+//  --priority <p>         low | medium | high
+//  -h, --help             Show this help
+//
+// Examples:
+// baton update 3 --title "Revised title"
+// baton update 7 --status closed --priority medium
+
+import { updateIssue, getIssue } from "../services/issuesService.js";
+import { parseArgs } from '../util.js';
+
+
+/**
+ * Updates the specified fields for a given issue ID 
+ * @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 (args.length === 0 || args === '') {
+        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>");
+    } 
+
+    // Convert id argument from string to base-10 integer
+    const id = parseInt(args[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>");
+    }
+
+    const validFlags = ['--title', '--description', '--token-limit', '--status', '--priority'];
+    // 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: --title <text>, --description <text>, --token-limit <n>, --status <s>, --priority <level>`);
+            }
+        }
+    }
+
+    try {
+        const options = parseArgs(args.slice(1));
+
+        // Store the old issue fields for displaying purposes:
+        const oldIssue = getIssue(id);
+
+        const newIssue = await updateIssue(id, oldIssue, options);
+
+        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;
+    }
+}

package/source/commands/view.js

@@ -0,0 +1,46 @@
+// list.js
+// AI was consulted for some portions of this file.
+// view command which allows user to view all data fields for an issue 
+// Usage: baton view <id>>
+
+import { getIssue } from '../services/issuesService.js';
+
+/**
+ * Displays all issue fields for a given id #
+ * @param {string[]} args - The issue ID #
+ * @returns {Promise<number>} The exit code: 0 is success, 1 is error.
+ */
+export async function run(args) {
+    // checks if id # argument is empty
+    if (args.length == 0) {
+        throw new Error(`Invalid input: Missing Issue ID.\nUsage: baton view <id>`);
+    }
+
+    const id = args.join(' ');
+
+    // checks if ID # argument isn't a number
+    if (isNaN(id)) {
+        throw new Error(`Invalid input: ID must be a number.\nUsage: baton view <id>`);
+    }
+
+    try {
+        const issue = await getIssue(id);
+
+        if (!issue) {
+            console.log(`No issue with ID #"${issue}" was found.`);
+            return 0;
+        }
+
+        console.log("");
+        Object.entries(issue).forEach(([key, value]) => {
+            console.log(`${key}: ${value}`);
+        });
+
+        console.log("");
+        return 0;
+    } catch (error) {
+        console.error("Error: Failed to retrieve data.");
+        console.error(error.message);
+        return 1;
+    }
+}

package/source/db/index.js

@@ -0,0 +1,72 @@
+import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import { migrate } from "drizzle-orm/better-sqlite3/migrator";
+import fs from "fs";
+import path from "path";
+
+import * as schema from "../models/schema.js"; 
+
+const dataDir = path.join(process.cwd(), ".baton");
+const dbPath = path.join(dataDir, "baton.db");
+
+if (!fs.existsSync(dataDir)) {
+  fs.mkdirSync(dataDir);
+}
+
+// Initialize better-sqlite3 connection
+const 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.
+let db = drizzle(sqliteConnection, { schema });
+
+export function initDB() {
+  // Apply Migrations dynamically on CLI startup
+  // This looks for a folder named "drizzle" in your project root
+  const migrationsFolder = path.join(process.cwd(), "drizzle");
+  
+  if (fs.existsSync(migrationsFolder)) {
+    migrate(db, { migrationsFolder });
+  } else {
+    console.warn("No migrations folder found. Tables may not be created.");
+  }
+
+  // Execute custom SQLite logic (Triggers)
+  // Drizzle does not manage triggers in its schema file, so we keep this raw.
+  sqliteConnection.exec(`
+    CREATE TRIGGER IF NOT EXISTS set_default_issue_title
+    AFTER INSERT ON issues
+    FOR EACH ROW
+    WHEN NEW.title = 'PENDING' OR NEW.title IS NULL
+    BEGIN
+      UPDATE issues
+      SET title = 'Issue #' || NEW.id
+      WHERE id = NEW.id;
+    END;
+  `);
+
+  sqliteConnection.exec(`
+   CREATE TRIGGER IF NOT EXISTS update_last_updated
+   AFTER UPDATE ON issues
+   FOR EACH ROW
+   WHEN NEW.last_updated IS OLD.last_updated
+   BEGIN
+    UPDATE issues
+    SET last_updated = CURRENT_TIMESTAMP
+    WHERE id = OLD.id;
+  END;
+  `);
+}
+
+export function getDB() {
+  return db;
+}
+
+export function getSQLiteDB() {
+  return sqliteConnection;
+}
+
+// function for the test suite mocking
+export function setTestDB(testDbInstance) {
+  db = testDbInstance;
+}

package/source/index.js

@@ -0,0 +1 @@
+// temp file for linter to pass

package/source/models/activityLog.js

@@ -0,0 +1,23 @@
+export const Action = Object.freeze({
+  STATE_CHANGE:    "state_change",
+  PRIORITY_CHANGE: "priority_change",
+  EDIT:            "edit",
+  READ:            "read",
+  CREATION:        "creation",
+  DELETION:        "deletion",
+  REJECT:          "rejection", 
+});
+
+export class ActivityLog {
+  constructor({
+    logId     = null,
+    issueId,
+    action,
+    createdAt = new Date().toISOString(),
+  } = {}) {
+    this.logId     = logId;
+    this.issueId   = issueId;
+    this.action    = action;
+    this.createdAt = createdAt;
+  }
+}