@braingrid/cli 0.2.26 → 0.2.28

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.28] - 2025-01-28
+
+### Added
+
+- **Tag management CLI commands for requirements**
+  - `requirement tag list [id]` - List all tags for a requirement
+  - `requirement tag add [id] --name <name> --color <hex>` - Add a tag with name and hex color
+  - `requirement tag remove [id] --name <name>` - Remove a tag by name
+  - All commands support auto-detection of requirement ID from git branch
+  - Multiple output formats supported (table, json, xml, markdown)
+  - Hex color validation for #RGB and #RRGGBB formats
+
+## [0.2.27] - 2025-01-27
+
+### Added
+
+- **Requirement tagging support**
+  - New `--tags` option for `requirement create` and `specify` commands
+  - Accepts comma-separated tags (max 5 per requirement)
+  - Tags are validated, trimmed, and empty values filtered
+  - Tags displayed in all output formats (table, markdown, XML, JSON)
+
 ## [0.2.26] - 2025-01-20
 
 ### Added

package/dist/cli.js

@@ -25,7 +25,7 @@ import axios from "axios";
 
 // src/build-config.ts
 var BUILD_ENV = true ? "production" : process.env.NODE_ENV === "test" ? "development" : "production";
-var CLI_VERSION = true ? "0.2.26" : "0.0.0-test";
+var CLI_VERSION = true ? "0.2.28" : "0.0.0-test";
 var PRODUCTION_CONFIG = {
   apiUrl: "https://app.braingrid.ai",
   workosAuthUrl: "https://auth.braingrid.ai",
@@ -2744,6 +2744,11 @@ function formatRequirementOutput(requirement2, options) {
   }
   message += `${chalk5.bold("Status:")} ${requirement2.status}
 `;
+  if (requirement2.tags && requirement2.tags.length > 0) {
+    const tagNames = requirement2.tags.map((tag) => tag.name).join(", ");
+    message += `${chalk5.bold("Tags:")} ${tagNames}
+`;
+  }
   if (requirement2.assignee) {
     const assigneeName = requirement2.assignee.first_name || requirement2.assignee.last_name ? `${requirement2.assignee.first_name || ""} ${requirement2.assignee.last_name || ""}`.trim() : requirement2.assignee.email;
     message += `${chalk5.bold("Assigned to:")} ${assigneeName} (${requirement2.assignee.email})
@@ -2890,15 +2895,16 @@ function formatRequirementListMarkdown(requirements, pagination) {
     md += "_No requirements found._\n";
     return md;
   }
-  md += "| Short ID | Status | Name | Branch | Progress |\n";
-  md += "|----------|--------|------|--------|----------|\n";
+  md += "| Short ID | Status | Name | Branch | Tags | Progress |\n";
+  md += "|----------|--------|------|--------|------|----------|\n";
   for (const req of requirements) {
     const shortId = req.short_id || req.id.slice(0, 11);
     const status = req.status;
     const name = req.name;
     const branch = req.branch || "N/A";
+    const tags = req.tags && req.tags.length > 0 ? req.tags.map((t) => t.name).join(", ") : "-";
     const progress = req.task_progress ? `${req.task_progress.progress_percentage}%` : "N/A";
-    md += `| ${shortId} | ${status} | ${name} | ${branch} | ${progress} |
+    md += `| ${shortId} | ${status} | ${name} | ${branch} | ${tags} | ${progress} |
 `;
   }
   if (pagination) {
@@ -2971,6 +2977,15 @@ function formatRequirementListXml(requirements, pagination) {
 `;
       xml += "      </assignee>\n";
     }
+    if (req.tags && req.tags.length > 0) {
+      xml += `      <tags count="${req.tags.length}">
+`;
+      for (const tag of req.tags) {
+        xml += `        <tag>${escapeXml(tag.name)}</tag>
+`;
+      }
+      xml += "      </tags>\n";
+    }
     xml += `      <created_at>${escapeXml(req.created_at)}</created_at>
 `;
     xml += `      <updated_at>${escapeXml(req.updated_at)}</updated_at>
@@ -3087,6 +3102,12 @@ function formatRequirementBuildMarkdown(requirement2, options) {
   md += `**Status:** ${requirement2.status}
 
 `;
+  if (requirement2.tags && requirement2.tags.length > 0) {
+    const tagNames = requirement2.tags.map((tag) => tag.name).join(", ");
+    md += `**Tags:** ${tagNames}
+
+`;
+  }
   if (requirement2.assignee) {
     const assigneeName = requirement2.assignee.first_name || requirement2.assignee.last_name ? `${requirement2.assignee.first_name || ""} ${requirement2.assignee.last_name || ""}`.trim() : requirement2.assignee.email;
     md += `**Assigned to:** ${assigneeName} (${requirement2.assignee.email})
@@ -3223,6 +3244,15 @@ function formatRequirementBuildXml(requirement2) {
     xml += `  <branch>${escapeXml(requirement2.branch)}</branch>
 `;
   }
+  if (requirement2.tags && requirement2.tags.length > 0) {
+    xml += `  <tags count="${requirement2.tags.length}">
+`;
+    for (const tag of requirement2.tags) {
+      xml += `    <tag>${escapeXml(tag.name)}</tag>
+`;
+    }
+    xml += "  </tags>\n";
+  }
   if (requirement2.assignee) {
     xml += "  <assignee>\n";
     xml += `    <email>${escapeXml(requirement2.assignee.email)}</email>
@@ -3974,8 +4004,57 @@ var RequirementService = class {
       });
     });
   }
+  // Tag management methods
+  async listRequirementTags(projectId, requirementId) {
+    const url = `${this.baseUrl}/api/v1/projects/${projectId}/requirements/${requirementId}/tags`;
+    const headers = this.getHeaders();
+    const response = await this.axios.get(url, { headers });
+    return response.data;
+  }
+  async addRequirementTag(projectId, requirementId, tag) {
+    const url = `${this.baseUrl}/api/v1/projects/${projectId}/requirements/${requirementId}/tags`;
+    const headers = this.getHeaders();
+    const response = await this.axios.post(url, tag, { headers });
+    return response.data;
+  }
+  async removeRequirementTag(projectId, requirementId, tagName) {
+    const url = `${this.baseUrl}/api/v1/projects/${projectId}/requirements/${requirementId}/tags/${encodeURIComponent(tagName)}`;
+    const headers = this.getHeaders();
+    await this.axios.delete(url, { headers });
+  }
 };
 
+// src/utils/tag-validation.ts
+var MAX_TAGS = 5;
+function validateTags(tagsString) {
+  if (!tagsString || tagsString.trim().length === 0) {
+    return { valid: true, tags: [] };
+  }
+  const tags = tagsString.split(",").map((tag) => tag.trim()).filter((tag) => tag.length > 0);
+  if (tags.length > MAX_TAGS) {
+    return {
+      valid: false,
+      error: `Maximum ${MAX_TAGS} tags allowed`
+    };
+  }
+  return { valid: true, tags };
+}
+
+// src/utils/color-validation.ts
+function validateHexColor(color) {
+  if (!color || color.trim().length === 0) {
+    return { valid: false, error: "Color is required" };
+  }
+  const hexPattern = /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/;
+  if (!hexPattern.test(color)) {
+    return {
+      valid: false,
+      error: "Invalid hex color format. Use #RGB or #RRGGBB (e.g., #FF0000 or #F00)"
+    };
+  }
+  return { valid: true };
+}
+
 // src/handlers/requirement.handlers.ts
 function getServices2() {
   const config = getConfig();
@@ -4203,11 +4282,23 @@ async function handleRequirementCreate(opts) {
         };
       }
     }
+    let validatedTags;
+    if (opts.tags) {
+      const tagResult = validateTags(opts.tags);
+      if (!tagResult.valid) {
+        return {
+          success: false,
+          message: chalk7.red(`\u274C ${tagResult.error}`)
+        };
+      }
+      validatedTags = tagResult.tags;
+    }
     stopSpinner = showSpinner("Creating requirement", chalk7.gray);
     const requirement2 = await requirementService.createProjectRequirement(projectId, {
       name: opts.name,
       content: opts.content || null,
-      assigned_to: opts.assignedTo || null
+      assigned_to: opts.assignedTo || null,
+      tags: validatedTags
     });
     stopSpinner();
     stopSpinner = null;
@@ -4280,9 +4371,21 @@ async function handleRequirementSpecify(opts) {
         message: chalk7.red("\u274C Prompt must be no more than 5000 characters long")
       };
     }
+    let validatedTags;
+    if (opts.tags) {
+      const tagResult = validateTags(opts.tags);
+      if (!tagResult.valid) {
+        return {
+          success: false,
+          message: chalk7.red(`\u274C ${tagResult.error}`)
+        };
+      }
+      validatedTags = tagResult.tags;
+    }
     stopSpinner = showSpinner("Specifying requirement...");
     const requirement2 = await requirementService.specifyRequirement(projectId, {
-      prompt: opts.prompt
+      prompt: opts.prompt,
+      tags: validatedTags
     });
     stopSpinner();
     stopSpinner = null;
@@ -4794,6 +4897,286 @@ async function handleReviewAcceptance(opts) {
     };
   }
 }
+async function handleRequirementTagList(opts) {
+  let stopSpinner = null;
+  try {
+    const { requirementService, auth } = getServices2();
+    const isAuthenticated = await auth.isAuthenticated();
+    if (!isAuthenticated) {
+      return {
+        success: false,
+        message: chalk7.red("\u274C Not authenticated. Please run `braingrid login` first.")
+      };
+    }
+    const format = opts.format || "table";
+    if (!["table", "json", "xml", "markdown"].includes(format)) {
+      return {
+        success: false,
+        message: chalk7.red(
+          `\u274C Invalid format: ${format}. Supported formats: table, json, xml, markdown`
+        )
+      };
+    }
+    const requirementResult = await workspaceManager.getRequirement(opts.requirementId);
+    if (!requirementResult.success) {
+      return {
+        success: false,
+        message: requirementResult.error
+      };
+    }
+    const requirementId = requirementResult.requirementId;
+    const workspace = await workspaceManager.getProject(opts.project);
+    if (!workspace.success) {
+      return {
+        success: false,
+        message: workspace.error
+      };
+    }
+    const projectId = workspace.projectId;
+    const normalizedId = normalizeRequirementId(requirementId);
+    stopSpinner = showSpinner("Loading tags", chalk7.gray);
+    const tags = await requirementService.listRequirementTags(projectId, normalizedId);
+    stopSpinner();
+    stopSpinner = null;
+    let output;
+    switch (format) {
+      case "json": {
+        output = JSON.stringify(tags, null, 2);
+        break;
+      }
+      case "xml": {
+        output = '<?xml version="1.0" encoding="UTF-8"?>\n<tags>\n';
+        for (const tag of tags) {
+          output += `  <tag>
+`;
+          output += `    <name>${tag.name}</name>
+`;
+          output += `    <color>${tag.color || ""}</color>
+`;
+          output += `    <id>${tag.id}</id>
+`;
+          output += `  </tag>
+`;
+        }
+        output += "</tags>";
+        break;
+      }
+      case "markdown": {
+        output = `# Tags for ${normalizedId}
+
+`;
+        if (tags.length === 0) {
+          output += "_No tags found_\n";
+        } else {
+          output += "| Name | Color |\n";
+          output += "|------|-------|\n";
+          for (const tag of tags) {
+            output += `| ${tag.name} | ${tag.color || "N/A"} |
+`;
+          }
+        }
+        break;
+      }
+      case "table":
+      default: {
+        if (tags.length === 0) {
+          return {
+            success: true,
+            message: chalk7.yellow(`No tags found for ${normalizedId}.`),
+            data: tags
+          };
+        }
+        output = chalk7.bold(`\u{1F3F7}\uFE0F  Tags for ${normalizedId}
+
+`);
+        output += "Name                 Color\n";
+        output += "\u2500".repeat(40) + "\n";
+        for (const tag of tags) {
+          const name = tag.name.padEnd(19);
+          const color = tag.color || "N/A";
+          output += `${name}  ${color}
+`;
+        }
+        break;
+      }
+    }
+    return {
+      success: true,
+      message: output,
+      data: tags
+    };
+  } catch (error) {
+    if (stopSpinner) {
+      stopSpinner();
+    }
+    return {
+      success: false,
+      message: formatError(
+        error,
+        getResourceContext("requirement", opts.requirementId || "unknown")
+      )
+    };
+  }
+}
+async function handleRequirementTagAdd(opts) {
+  let stopSpinner = null;
+  try {
+    const { requirementService, auth } = getServices2();
+    const isAuthenticated = await auth.isAuthenticated();
+    if (!isAuthenticated) {
+      return {
+        success: false,
+        message: chalk7.red("\u274C Not authenticated. Please run `braingrid login` first.")
+      };
+    }
+    if (!opts.name || opts.name.trim().length === 0) {
+      return {
+        success: false,
+        message: chalk7.red("\u274C Tag name is required")
+      };
+    }
+    const colorResult = validateHexColor(opts.color);
+    if (!colorResult.valid) {
+      return {
+        success: false,
+        message: chalk7.red(`\u274C ${colorResult.error}`)
+      };
+    }
+    const requirementResult = await workspaceManager.getRequirement(opts.requirementId);
+    if (!requirementResult.success) {
+      return {
+        success: false,
+        message: requirementResult.error
+      };
+    }
+    const requirementId = requirementResult.requirementId;
+    const workspace = await workspaceManager.getProject(opts.project);
+    if (!workspace.success) {
+      return {
+        success: false,
+        message: workspace.error
+      };
+    }
+    const projectId = workspace.projectId;
+    const normalizedId = normalizeRequirementId(requirementId);
+    stopSpinner = showSpinner("Adding tag", chalk7.gray);
+    const response = await requirementService.addRequirementTag(projectId, normalizedId, {
+      name: opts.name.trim(),
+      color: opts.color
+    });
+    stopSpinner();
+    stopSpinner = null;
+    return {
+      success: true,
+      message: chalk7.green(
+        `\u2705 Added tag "${response.tag.name}" (${response.tag.color}) to ${normalizedId}`
+      ),
+      data: response
+    };
+  } catch (error) {
+    if (stopSpinner) {
+      stopSpinner();
+    }
+    if (error && typeof error === "object" && "response" in error) {
+      const axiosError = error;
+      if (axiosError.response?.status === 400) {
+        const errorData = axiosError.response.data;
+        if (errorData?.code === "MAX_TAGS_EXCEEDED") {
+          return {
+            success: false,
+            message: chalk7.red("\u274C Maximum 5 tags allowed per requirement")
+          };
+        }
+        if (errorData?.code === "TAG_ALREADY_ASSOCIATED") {
+          return {
+            success: false,
+            message: chalk7.red(`\u274C Tag "${opts.name}" is already associated with this requirement`)
+          };
+        }
+      }
+    }
+    return {
+      success: false,
+      message: formatError(
+        error,
+        getResourceContext("requirement", opts.requirementId || "unknown")
+      )
+    };
+  }
+}
+async function handleRequirementTagRemove(opts) {
+  let stopSpinner = null;
+  try {
+    const { requirementService, auth } = getServices2();
+    const isAuthenticated = await auth.isAuthenticated();
+    if (!isAuthenticated) {
+      return {
+        success: false,
+        message: chalk7.red("\u274C Not authenticated. Please run `braingrid login` first.")
+      };
+    }
+    if (!opts.name || opts.name.trim().length === 0) {
+      return {
+        success: false,
+        message: chalk7.red("\u274C Tag name is required")
+      };
+    }
+    const requirementResult = await workspaceManager.getRequirement(opts.requirementId);
+    if (!requirementResult.success) {
+      return {
+        success: false,
+        message: requirementResult.error
+      };
+    }
+    const requirementId = requirementResult.requirementId;
+    const workspace = await workspaceManager.getProject(opts.project);
+    if (!workspace.success) {
+      return {
+        success: false,
+        message: workspace.error
+      };
+    }
+    const projectId = workspace.projectId;
+    const normalizedId = normalizeRequirementId(requirementId);
+    stopSpinner = showSpinner("Removing tag", chalk7.gray);
+    await requirementService.removeRequirementTag(projectId, normalizedId, opts.name.trim());
+    stopSpinner();
+    stopSpinner = null;
+    return {
+      success: true,
+      message: chalk7.green(`\u2705 Removed tag "${opts.name}" from ${normalizedId}`)
+    };
+  } catch (error) {
+    if (stopSpinner) {
+      stopSpinner();
+    }
+    if (error && typeof error === "object" && "response" in error) {
+      const axiosError = error;
+      if (axiosError.response?.status === 404) {
+        const errorData = axiosError.response.data;
+        if (errorData?.code === "TAG_NOT_FOUND") {
+          return {
+            success: false,
+            message: chalk7.red(`\u274C Tag "${opts.name}" not found`)
+          };
+        }
+        if (errorData?.code === "ASSOCIATION_NOT_FOUND") {
+          return {
+            success: false,
+            message: chalk7.red(`\u274C Tag "${opts.name}" is not associated with this requirement`)
+          };
+        }
+      }
+    }
+    return {
+      success: false,
+      message: formatError(
+        error,
+        getResourceContext("requirement", opts.requirementId || "unknown")
+      )
+    };
+  }
+}
 
 // src/handlers/task.handlers.ts
 import chalk8 from "chalk";
@@ -7610,7 +7993,7 @@ program.command("update").description("Update BrainGrid CLI to the latest versio
 program.command("specify").description("Create AI-refined requirement from prompt").option(
   "-p, --project <id>",
   "project ID (auto-detects from .braingrid/project.json if not provided)"
-).requiredOption("--prompt <prompt>", "requirement description (10-5000 characters)").option("--format <format>", "output format (table, json, xml, markdown)", "table").action(async (opts) => {
+).requiredOption("--prompt <prompt>", "requirement description (10-5000 characters)").option("-t, --tags <tags>", "comma-separated tags (max 5)").option("--format <format>", "output format (table, json, xml, markdown)", "table").action(async (opts) => {
   const result = await handleRequirementSpecify(opts);
   console.log(result.message);
   if (!result.success) {
@@ -7695,7 +8078,7 @@ requirement.command("show [id]").description("Show requirement details (auto-det
 requirement.command("create").description("Create a new requirement").option(
   "-p, --project <id>",
   "project ID (auto-detects from .braingrid/project.json if not provided)"
-).requiredOption("-n, --name <name>", "requirement name").option("-c, --content <content>", "requirement content/description").option("-a, --assigned-to <uuid>", "user UUID to assign the requirement to").action(async (opts) => {
+).requiredOption("-n, --name <name>", "requirement name").option("-c, --content <content>", "requirement content/description").option("-a, --assigned-to <uuid>", "user UUID to assign the requirement to").option("-t, --tags <tags>", "comma-separated tags (max 5)").action(async (opts) => {
   const result = await handleRequirementCreate(opts);
   console.log(result.message);
   if (!result.success) {
@@ -7767,6 +8150,37 @@ requirement.command("review [id]").description("Run AI code review for a require
     process.exit(1);
   }
 });
+var requirementTag = requirement.command("tag").description("Manage requirement tags");
+requirementTag.command("list [id]").description("List tags for a requirement (auto-detects ID from git branch if not provided)").option(
+  "-p, --project <id>",
+  "project ID (auto-detects from .braingrid/project.json if not provided)"
+).option("--format <format>", "output format (table, json, xml, markdown)", "table").action(async (id, opts) => {
+  const result = await handleRequirementTagList({ ...opts, requirementId: id });
+  console.log(result.message);
+  if (!result.success) {
+    process.exit(1);
+  }
+});
+requirementTag.command("add [id]").description("Add a tag to a requirement (auto-detects ID from git branch if not provided)").option(
+  "-p, --project <id>",
+  "project ID (auto-detects from .braingrid/project.json if not provided)"
+).requiredOption("--name <name>", "tag name").requiredOption("--color <hex>", "hex color code (e.g., #FF0000)").action(async (id, opts) => {
+  const result = await handleRequirementTagAdd({ ...opts, requirementId: id });
+  console.log(result.message);
+  if (!result.success) {
+    process.exit(1);
+  }
+});
+requirementTag.command("remove [id]").description("Remove a tag from a requirement (auto-detects ID from git branch if not provided)").option(
+  "-p, --project <id>",
+  "project ID (auto-detects from .braingrid/project.json if not provided)"
+).requiredOption("--name <name>", "tag name to remove").action(async (id, opts) => {
+  const result = await handleRequirementTagRemove({ ...opts, requirementId: id });
+  console.log(result.message);
+  if (!result.success) {
+    process.exit(1);
+  }
+});
 var task = program.command("task").description("Manage tasks");
 task.command("list").description("List tasks for a requirement").option("-r, --requirement <id>", "requirement ID (REQ-456, auto-detects project if initialized)").option("-p, --project <id>", "project ID (PROJ-123, optional if project is initialized)").option("--format <format>", "output format (table, json, xml, markdown)", "markdown").option("--page <page>", "page number for pagination", "1").option("--limit <limit>", "number of tasks per page", "20").action(async (opts) => {
   const result = await handleTaskList(opts);