@braingrid/cli 0.2.25 → 0.2.26

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.26] - 2025-01-20
+
+### Added
+
+- **BRAINGRID_API_TOKEN environment variable support**
+  - Enables authentication via JWT token for sandbox/CI environments
+  - Allows CLI usage without interactive OAuth login flow
+  - Useful for automated pipelines and testing scenarios
+
+### Changed
+
+- **README documentation updates**
+  - Added `requirement create-branch` and `requirement review` commands to docs
+  - Updated shell completion subcommands list
+
 ## [0.2.25] - 2025-12-22
 
 ### Added

package/README.md

@@ -213,6 +213,8 @@ braingrid requirement update [id] [--status IDEA|PLANNED|IN_PROGRESS|REVIEW|COMP
 braingrid requirement delete [id] [--force]
 braingrid requirement breakdown [id]
 braingrid requirement build [id] [--format markdown|json|xml]
+braingrid requirement create-branch [id] [--name <branch-name>] [--base <branch>]
+braingrid requirement review [id] [--pr <number>]
 
 # Working with a different project:
 braingrid requirement list -p PROJ-456 [--status PLANNED]
@@ -226,6 +228,10 @@ braingrid requirement create -p PROJ-456 --name "Description"
 > **Note:** The `-r`/`--requirement` parameter is optional and accepts formats like `REQ-456`, `req-456`, or `456`. The CLI will automatically detect the requirement ID from your git branch name (e.g., `feature/REQ-123-description` or `REQ-123-fix-bug`) if it is not provided.
 >
 > **Note:** The `requirement list` command displays requirements with their status, name, branch (if assigned), and progress percentage.
+>
+> **Note:** The `create-branch` command creates a GitHub branch for a requirement. It auto-generates a branch name in the format `{username}/REQ-123-slug` if not provided.
+>
+> **Note:** The `review` command runs an AI-powered acceptance review on a pull request, validating it against the requirement's acceptance criteria. It auto-detects the PR number from the current branch if not provided.
 
 ### Task Commands
 
@@ -309,7 +315,7 @@ eval "$(braingrid completion zsh)"
 ### What Gets Completed
 
 - **Commands**: `login`, `logout`, `project`, `requirement`, `task`, etc.
-- **Subcommands**: `list`, `show`, `create`, `update`, `delete`, `breakdown`, `build`
+- **Subcommands**: `list`, `show`, `create`, `update`, `delete`, `breakdown`, `build`, `create-branch`, `review`
 - **Options**: `--help`, `--format`, `--status`, `--project`, `--requirement`
 - **Values**: Status values (`IDEA`, `PLANNED`, `IN_PROGRESS`, etc.), format options (`table`, `json`, `xml`, `markdown`)
 

package/dist/cli.js

@@ -23,6 +23,81 @@ import chalk6 from "chalk";
 // src/utils/axios-with-auth.ts
 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 PRODUCTION_CONFIG = {
+  apiUrl: "https://app.braingrid.ai",
+  workosAuthUrl: "https://auth.braingrid.ai",
+  workosClientId: "client_01K6H010C9K69HSDPM9CQM85S7"
+};
+var DEVELOPMENT_CONFIG = {
+  apiUrl: "https://app.dev.braingrid.ai",
+  workosAuthUrl: "https://balanced-celebration-78-staging.authkit.app",
+  workosClientId: "client_01K6H04GF21T4JXNS3JDQM3YNE"
+};
+
+// src/utils/config.ts
+var BRAINGRID_API_TOKEN = process.env.BRAINGRID_API_TOKEN;
+function getConfig() {
+  const baseConfig = BUILD_ENV === "production" ? PRODUCTION_CONFIG : DEVELOPMENT_CONFIG;
+  let apiUrl = baseConfig.apiUrl;
+  if (BUILD_ENV === "development") {
+    if (process.env.NODE_ENV === "local" || process.env.NODE_ENV === "test") {
+      apiUrl = "http://localhost:3377";
+    } else if (process.env.NODE_ENV === "development") {
+      apiUrl = DEVELOPMENT_CONFIG.apiUrl;
+    }
+  }
+  const getWorkOSAuthUrl = () => {
+    if (process.env.WORKOS_AUTH_URL) {
+      return process.env.WORKOS_AUTH_URL;
+    }
+    if (BUILD_ENV === "production") {
+      return PRODUCTION_CONFIG.workosAuthUrl;
+    }
+    const env = process.env.NODE_ENV || "development";
+    if (env === "local" || env === "test" || env === "development" || env === "staging") {
+      return DEVELOPMENT_CONFIG.workosAuthUrl;
+    }
+    return PRODUCTION_CONFIG.workosAuthUrl;
+  };
+  const getOAuthClientId = () => {
+    if (process.env.WORKOS_CLIENT_ID) {
+      return process.env.WORKOS_CLIENT_ID;
+    }
+    if (BUILD_ENV === "production") {
+      return PRODUCTION_CONFIG.workosClientId;
+    }
+    const env = process.env.NODE_ENV || "development";
+    if (env === "local" || env === "test" || env === "development" || env === "staging") {
+      return DEVELOPMENT_CONFIG.workosClientId;
+    }
+    return PRODUCTION_CONFIG.workosClientId;
+  };
+  const getWebAppUrl = () => {
+    if (process.env.BRAINGRID_WEB_URL) {
+      return process.env.BRAINGRID_WEB_URL;
+    }
+    if (BUILD_ENV === "production") {
+      return PRODUCTION_CONFIG.apiUrl;
+    }
+    const env = process.env.NODE_ENV || "development";
+    if (env === "local" || env === "test") {
+      return "http://localhost:3377";
+    }
+    return DEVELOPMENT_CONFIG.apiUrl;
+  };
+  return {
+    apiUrl: process.env.BRAINGRID_API_URL || apiUrl,
+    organizationId: process.env.BRAINGRID_ORG_ID,
+    clientId: process.env.BRAINGRID_CLIENT_ID || "braingrid-cli",
+    oauthClientId: getOAuthClientId(),
+    getWorkOSAuthUrl,
+    getWebAppUrl
+  };
+}
+
 // src/utils/logger.ts
 import fs from "fs";
 import path from "path";
@@ -211,6 +286,10 @@ function createAuthenticatedAxios(auth) {
   });
   instance.interceptors.request.use(
     async (config) => {
+      if (BRAINGRID_API_TOKEN) {
+        config.headers.Authorization = `Bearer ${BRAINGRID_API_TOKEN}`;
+        return config;
+      }
       const session = await auth.getStoredSession();
       if (session) {
         config.headers.Authorization = `Bearer ${session.sealed_session}`;
@@ -251,6 +330,11 @@ function createAuthenticatedAxios(auth) {
       const isRedirectToAuth = isAuthRedirect(error);
       if ((is401 || isRedirectToAuth) && !originalRequest._retry) {
         originalRequest._retry = true;
+        if (BRAINGRID_API_TOKEN) {
+          logger.warn("[AUTH] Sandbox token expired or invalid");
+          const sandboxError = new Error(auth.getSandboxExpiredMessage());
+          return Promise.reject(sandboxError);
+        }
         if (isRedirectToAuth) {
           logger.debug("[AUTH] Received redirect to auth endpoint - token likely expired");
         } else {
@@ -422,82 +506,6 @@ import { createHash, randomBytes } from "crypto";
 import { createServer } from "http";
 import open from "open";
 import axios3, { AxiosError as AxiosError2 } from "axios";
-
-// src/build-config.ts
-var BUILD_ENV = true ? "production" : process.env.NODE_ENV === "test" ? "development" : "production";
-var CLI_VERSION = true ? "0.2.25" : "0.0.0-test";
-var PRODUCTION_CONFIG = {
-  apiUrl: "https://app.braingrid.ai",
-  workosAuthUrl: "https://auth.braingrid.ai",
-  workosClientId: "client_01K6H010C9K69HSDPM9CQM85S7"
-};
-var DEVELOPMENT_CONFIG = {
-  apiUrl: "https://app.dev.braingrid.ai",
-  workosAuthUrl: "https://balanced-celebration-78-staging.authkit.app",
-  workosClientId: "client_01K6H04GF21T4JXNS3JDQM3YNE"
-};
-
-// src/utils/config.ts
-function getConfig() {
-  const baseConfig = BUILD_ENV === "production" ? PRODUCTION_CONFIG : DEVELOPMENT_CONFIG;
-  let apiUrl = baseConfig.apiUrl;
-  if (BUILD_ENV === "development") {
-    if (process.env.NODE_ENV === "local" || process.env.NODE_ENV === "test") {
-      apiUrl = "http://localhost:3377";
-    } else if (process.env.NODE_ENV === "development") {
-      apiUrl = DEVELOPMENT_CONFIG.apiUrl;
-    }
-  }
-  const getWorkOSAuthUrl = () => {
-    if (process.env.WORKOS_AUTH_URL) {
-      return process.env.WORKOS_AUTH_URL;
-    }
-    if (BUILD_ENV === "production") {
-      return PRODUCTION_CONFIG.workosAuthUrl;
-    }
-    const env = process.env.NODE_ENV || "development";
-    if (env === "local" || env === "test" || env === "development" || env === "staging") {
-      return DEVELOPMENT_CONFIG.workosAuthUrl;
-    }
-    return PRODUCTION_CONFIG.workosAuthUrl;
-  };
-  const getOAuthClientId = () => {
-    if (process.env.WORKOS_CLIENT_ID) {
-      return process.env.WORKOS_CLIENT_ID;
-    }
-    if (BUILD_ENV === "production") {
-      return PRODUCTION_CONFIG.workosClientId;
-    }
-    const env = process.env.NODE_ENV || "development";
-    if (env === "local" || env === "test" || env === "development" || env === "staging") {
-      return DEVELOPMENT_CONFIG.workosClientId;
-    }
-    return PRODUCTION_CONFIG.workosClientId;
-  };
-  const getWebAppUrl = () => {
-    if (process.env.BRAINGRID_WEB_URL) {
-      return process.env.BRAINGRID_WEB_URL;
-    }
-    if (BUILD_ENV === "production") {
-      return PRODUCTION_CONFIG.apiUrl;
-    }
-    const env = process.env.NODE_ENV || "development";
-    if (env === "local" || env === "test") {
-      return "http://localhost:3377";
-    }
-    return DEVELOPMENT_CONFIG.apiUrl;
-  };
-  return {
-    apiUrl: process.env.BRAINGRID_API_URL || apiUrl,
-    organizationId: process.env.BRAINGRID_ORG_ID,
-    clientId: process.env.BRAINGRID_CLIENT_ID || "braingrid-cli",
-    oauthClientId: getOAuthClientId(),
-    getWorkOSAuthUrl,
-    getWebAppUrl
-  };
-}
-
-// src/services/oauth2-auth.ts
 var logger2 = getLogger();
 var OAuth2Handler = class {
   /**
@@ -1000,6 +1008,7 @@ var KEYCHAIN_SERVICE = "braingrid-cli";
 var KEYCHAIN_ACCOUNT = "session";
 var GITHUB_KEYCHAIN_ACCOUNT = "github-token";
 var BraingridAuth = class {
+  // Cached session from env token
   constructor(baseUrl) {
     this.lastValidationTime = 0;
     this.lastValidationResult = false;
@@ -1011,11 +1020,103 @@ var BraingridAuth = class {
     this.oauthHandler = null;
     // Store refresh token separately
     this.logger = getLogger();
+    this.envTokenSession = null;
     const config = getConfig();
     this.baseUrl = baseUrl || config.apiUrl || "https://app.braingrid.ai";
   }
+  /**
+   * Check if CLI is using BRAINGRID_API_TOKEN environment variable
+   * This is used in sandbox environments where tokens are injected
+   */
+  isUsingEnvToken() {
+    return Boolean(BRAINGRID_API_TOKEN);
+  }
+  /**
+   * Get the env token value (for use in axios interceptor)
+   */
+  getEnvToken() {
+    return BRAINGRID_API_TOKEN;
+  }
+  /**
+   * Fetch user profile from server using the env token
+   * This is used to populate session data when using BRAINGRID_API_TOKEN
+   */
+  async fetchProfileFromServer() {
+    if (!BRAINGRID_API_TOKEN) {
+      return null;
+    }
+    try {
+      this.logger.debug("[AUTH] Fetching profile using BRAINGRID_API_TOKEN");
+      const response = await axiosWithRetry(
+        {
+          url: `${this.baseUrl}/api/v1/profile`,
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${BRAINGRID_API_TOKEN}`
+          },
+          maxRedirects: 0,
+          validateStatus: (status) => status < 500
+        },
+        {
+          maxRetries: 2,
+          initialDelay: 500
+        }
+      );
+      if (response.status !== 200) {
+        this.logger.warn(`[AUTH] Profile fetch failed with status ${response.status}`);
+        return null;
+      }
+      const profileData = response.data;
+      if (profileData.error || !profileData.user || !profileData.organization) {
+        this.logger.warn("[AUTH] Profile response missing user or organization data");
+        return null;
+      }
+      const user = {
+        object: "user",
+        id: profileData.user.id,
+        email: profileData.user.email,
+        emailVerified: true,
+        firstName: profileData.user.firstName || "",
+        lastName: profileData.user.lastName || "",
+        profilePictureUrl: profileData.user.avatar || "",
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        lastSignInAt: (/* @__PURE__ */ new Date()).toISOString(),
+        externalId: null,
+        metadata: {
+          username: profileData.user.username,
+          organizationId: profileData.organization.id,
+          organizationName: profileData.organization.name
+        }
+      };
+      const session = {
+        user,
+        sealed_session: BRAINGRID_API_TOKEN,
+        organization_id: profileData.organization.id,
+        created_at: /* @__PURE__ */ new Date(),
+        updated_at: /* @__PURE__ */ new Date(),
+        login_time: /* @__PURE__ */ new Date()
+      };
+      this.envTokenSession = session;
+      this.logger.debug("[AUTH] Successfully fetched profile from env token");
+      return session;
+    } catch (error) {
+      this.logger.error("[AUTH] Error fetching profile with env token:", { error });
+      return null;
+    }
+  }
   async isAuthenticated(forceValidation = false) {
     try {
+      if (BRAINGRID_API_TOKEN) {
+        this.logger.debug("[AUTH] Using BRAINGRID_API_TOKEN (sandbox mode)");
+        if (isJWTExpired(BRAINGRID_API_TOKEN)) {
+          this.logger.warn("[AUTH] Sandbox session expired");
+          return false;
+        }
+        const session2 = await this.getStoredSession();
+        return session2 !== null;
+      }
       const session = await this.getStoredSession();
       if (!session) {
         this.logger.debug("[AUTH] No stored session found");
@@ -1149,6 +1250,12 @@ var BraingridAuth = class {
     }
   }
   async getStoredSession() {
+    if (BRAINGRID_API_TOKEN) {
+      if (this.envTokenSession) {
+        return this.envTokenSession;
+      }
+      return await this.fetchProfileFromServer();
+    }
     try {
       const sessionData = await credentialStore.getPassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
       if (!sessionData) return null;
@@ -1177,12 +1284,23 @@ var BraingridAuth = class {
     this.loginTime = nowMs;
   }
   async clearSession() {
+    if (BRAINGRID_API_TOKEN) {
+      this.logger.debug("[AUTH] Session managed by sandbox environment - clear is no-op");
+      this.envTokenSession = null;
+      return;
+    }
     await credentialStore.deletePassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
     await credentialStore.deletePassword(KEYCHAIN_SERVICE, "refresh-token");
     this.refreshTokenValue = void 0;
     this.lastValidationTime = 0;
     this.lastValidationResult = false;
   }
+  /**
+   * Get sandbox-specific error message for expired/invalid tokens
+   */
+  getSandboxExpiredMessage() {
+    return "Sandbox session expired. Your sandbox environment has a 5-hour limit.\nPlease create a new sandbox to continue.";
+  }
   async handleAuthenticationError() {
     this.lastValidationTime = 0;
     this.lastValidationResult = false;
@@ -5317,6 +5435,14 @@ function getAuth() {
 async function handleLogin() {
   try {
     const auth = getAuth();
+    if (BRAINGRID_API_TOKEN) {
+      return {
+        success: true,
+        message: chalk9.blue(
+          "\u2139\uFE0F  Using BRAINGRID_API_TOKEN - already authenticated via sandbox environment."
+        )
+      };
+    }
     console.log(chalk9.blue("\u{1F510} Starting OAuth2 authentication flow..."));
     console.log(chalk9.dim("Your browser will open to complete authentication.\n"));
     const gitUser = await getGitUser();
@@ -5350,6 +5476,12 @@ async function handleLogin() {
 async function handleLogout() {
   try {
     const auth = getAuth();
+    if (BRAINGRID_API_TOKEN) {
+      return {
+        success: true,
+        message: chalk9.blue("\u2139\uFE0F  Session managed by sandbox environment - logout not required.")
+      };
+    }
     await auth.clearSession();
     return {
       success: true,
@@ -5367,6 +5499,12 @@ async function handleWhoami() {
     const auth = getAuth();
     const isAuthenticated = await auth.isAuthenticated();
     if (!isAuthenticated) {
+      if (BRAINGRID_API_TOKEN) {
+        return {
+          success: false,
+          message: chalk9.red(auth.getSandboxExpiredMessage())
+        };
+      }
       return {
         success: false,
         message: chalk9.yellow("\u26A0\uFE0F  Not logged in. Run `braingrid login` to authenticate.")
@@ -5389,8 +5527,13 @@ async function handleWhoami() {
 `;
     output += `${chalk9.bold("Org ID:")}       ${session.organization_id}
 `;
-    output += `${chalk9.bold("Session:")}      ${new Date(session.created_at).toLocaleString()}
+    if (BRAINGRID_API_TOKEN) {
+      output += `${chalk9.bold("Auth:")}         ${chalk9.cyan("Sandbox API Token")}
 `;
+    } else {
+      output += `${chalk9.bold("Session:")}      ${new Date(session.created_at).toLocaleString()}
+`;
+    }
     return {
       success: true,
       message: output,