@girardmedia/bootspring 1.2.0 → 2.0.3

package/core/project-context.js

@@ -0,0 +1,325 @@
+/**
+ * Bootspring Project Context Enforcement
+ *
+ * Ensures CLI commands run within a project context.
+ * All activity should be tracked to a project for:
+ * - Usage billing
+ * - Memory/learning isolation
+ * - Team collaboration
+ * - Audit trails
+ *
+ * @package bootspring
+ * @module core/project-context
+ */
+
+const session = require('./session');
+const auth = require('./auth');
+const api = require('./api-client');
+
+// Commands that don't require project context
+const EXEMPT_COMMANDS = [
+  'auth',
+  'switch',
+  'project',
+  'help',
+  'init',
+  'doctor',
+  'update',
+  'version',
+  '--version',
+  '-v',
+  '--help',
+  '-h',
+  'cloud-sync',
+  'skill',    // Skills accessible in local mode without project
+  'agent',    // Agent list accessible without project
+  'billing',  // Billing status/info accessible without project
+  'preseed',  // Preseed works locally, auth enhances features
+  'seed',     // Seed works locally for scaffolding
+];
+
+// Sub-commands of auth that are exempt
+const EXEMPT_AUTH_SUBCOMMANDS = [
+  'login',
+  'logout',
+  'register',
+  'signup',
+  'status',
+  'whoami',
+  'switch'  // auth switch is also exempt
+];
+
+/**
+ * Check if a command requires project context
+ * @param {string} command - Main command
+ * @param {string} [subcommand] - Sub-command if any
+ * @returns {boolean} Whether project context is required
+ */
+function requiresProjectContext(command, subcommand) {
+  // Check if main command is exempt
+  if (EXEMPT_COMMANDS.includes(command)) {
+    return false;
+  }
+
+  // Check exempt auth subcommands
+  if (command === 'auth' && subcommand && EXEMPT_AUTH_SUBCOMMANDS.includes(subcommand)) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Get the current project context
+ * Returns null if no project is set
+ * @returns {object|null} Project context
+ */
+function getProjectContext() {
+  return session.getEffectiveProject();
+}
+
+/**
+ * Check if project context is set
+ * @returns {boolean}
+ */
+function hasProjectContext() {
+  return !!getProjectContext();
+}
+
+/**
+ * Get project ID for API requests
+ * @returns {string|null} Project ID or null
+ */
+function getProjectId() {
+  const project = getProjectContext();
+  return project?.id || null;
+}
+
+/**
+ * Get headers for API requests including project context
+ * @returns {object} Headers object
+ */
+function getProjectHeaders() {
+  const projectId = getProjectId();
+  const headers = {};
+
+  if (projectId) {
+    headers['X-Project-Id'] = projectId;
+  }
+
+  return headers;
+}
+
+/**
+ * Require project context - throws if not set
+ * @throws {ProjectContextError} If no project context is set
+ * @returns {object} Project context
+ */
+function requireProject() {
+  const project = getProjectContext();
+
+  if (!project) {
+    const error = new Error('No project context set');
+    error.code = 'NO_PROJECT_CONTEXT';
+    error.help = [
+      'All Bootspring commands require a project context.',
+      '',
+      'To set a project:',
+      '  bootspring switch              # List and select a project',
+      '  bootspring switch <name>       # Switch to a specific project',
+      '',
+      'Or use the --project flag:',
+      '  bootspring --project myapp <command>',
+      '',
+      'Create a project at: https://bootspring.com/dashboard/projects'
+    ];
+    throw error;
+  }
+
+  return project;
+}
+
+/**
+ * Validate project context before running a command
+ * @param {string} command - Command being run
+ * @param {string[]} args - Command arguments
+ * @param {object} options - Options including project override
+ * @returns {object} Validation result { valid, project, error }
+ */
+function validateForCommand(command, args = [], options = {}) {
+  const subcommand = args[0];
+
+  // Check if command is exempt
+  if (!requiresProjectContext(command, subcommand)) {
+    return { valid: true, exempt: true };
+  }
+
+  // Check if user is authenticated
+  if (!auth.isAuthenticated()) {
+    return {
+      valid: false,
+      error: {
+        code: 'NOT_AUTHENTICATED',
+        message: 'Authentication required',
+        help: ['Run: bootspring auth login']
+      }
+    };
+  }
+
+  // Check for project override flag
+  if (options.projectOverride) {
+    // Validation happens async in validateProjectAccessAsync if needed
+    return {
+      valid: true,
+      project: { id: options.projectOverride, source: 'flag' },
+      requiresAccessCheck: true
+    };
+  }
+
+  // Check for project context
+  const project = getProjectContext();
+  if (!project) {
+    return {
+      valid: false,
+      error: {
+        code: 'NO_PROJECT_CONTEXT',
+        message: 'No project context set',
+        help: [
+          'Run: bootspring switch',
+          'Or use: bootspring --project <name> ' + command
+        ]
+      }
+    };
+  }
+
+  return { valid: true, project };
+}
+
+/**
+ * Format error message for display
+ * @param {object} error - Error object with code, message, help
+ * @returns {string} Formatted error message
+ */
+function formatError(error) {
+  const lines = [];
+  const RED = '\x1b[31m';
+  const YELLOW = '\x1b[33m';
+  const DIM = '\x1b[2m';
+  const RESET = '\x1b[0m';
+
+  lines.push(`${RED}Error: ${error.message}${RESET}`);
+  lines.push('');
+
+  if (error.help && error.help.length > 0) {
+    for (const line of error.help) {
+      if (line.startsWith('  ')) {
+        lines.push(`${YELLOW}${line}${RESET}`);
+      } else {
+        lines.push(`${DIM}${line}${RESET}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Parse --project flag from args
+ * @param {string[]} args - Command line arguments
+ * @returns {{ projectOverride: string|null, cleanArgs: string[] }}
+ */
+function parseProjectFlag(args) {
+  const cleanArgs = [];
+  let projectOverride = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--project' || arg === '-p') {
+      // Next arg is the project name/id
+      if (i + 1 < args.length) {
+        projectOverride = args[i + 1];
+        i++; // Skip next arg
+      }
+    } else if (arg.startsWith('--project=')) {
+      projectOverride = arg.split('=')[1];
+    } else {
+      cleanArgs.push(arg);
+    }
+  }
+
+  return { projectOverride, cleanArgs };
+}
+
+/**
+ * Validate user has access to a project (async)
+ * Call this after validateForCommand when requiresAccessCheck is true
+ * @param {string} projectId - Project ID or name to validate
+ * @returns {Promise<{valid: boolean, project?: object, error?: object}>}
+ */
+async function validateProjectAccessAsync(projectId) {
+  try {
+    const projects = await api.listProjects();
+
+    // Check both owned and shared projects
+    const allProjects = [
+      ...(projects.owned || []),
+      ...(projects.shared || []),
+      ...(projects.projects || []) // fallback for flat list
+    ];
+
+    // Find project by id, slug, or name (case-insensitive)
+    const project = allProjects.find(p =>
+      p.id === projectId ||
+      p.slug === projectId ||
+      p.name?.toLowerCase() === projectId.toLowerCase()
+    );
+
+    if (!project) {
+      return {
+        valid: false,
+        error: {
+          code: 'PROJECT_NOT_FOUND',
+          message: `Project '${projectId}' not found or you don't have access`,
+          help: [
+            'Check the project name/id is correct',
+            'Run: bootspring project list',
+            'Or request access from the project owner'
+          ]
+        }
+      };
+    }
+
+    return {
+      valid: true,
+      project: {
+        id: project.id,
+        name: project.name,
+        slug: project.slug,
+        role: project.role || 'owner',
+        source: 'flag'
+      }
+    };
+  } catch (_error) {
+    // If API call fails, allow access (fail open for offline mode)
+    return {
+      valid: true,
+      project: { id: projectId, source: 'flag' },
+      warning: 'Could not verify project access (offline mode)'
+    };
+  }
+}
+
+module.exports = {
+  EXEMPT_COMMANDS,
+  requiresProjectContext,
+  getProjectContext,
+  hasProjectContext,
+  getProjectId,
+  getProjectHeaders,
+  requireProject,
+  validateForCommand,
+  validateProjectAccessAsync,
+  formatError,
+  parseProjectFlag
+};