@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/core/project-context.ts

@@ -0,0 +1,380 @@
+/**
+ * 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
+ */
+
+// Module interfaces
+interface Session {
+  getEffectiveProject: () => Project | null;
+}
+
+interface Auth {
+  isAuthenticated: () => boolean;
+}
+
+interface ApiClient {
+  listProjects: () => Promise<ProjectListResponse>;
+}
+
+interface Project {
+  id: string;
+  name?: string | undefined;
+  slug?: string | undefined;
+  role?: string | undefined;
+  source?: string | undefined;
+}
+
+interface ProjectListResponse {
+  owned?: Project[] | undefined;
+  shared?: Project[] | undefined;
+  projects?: Project[] | undefined;
+}
+
+interface ProjectContextError extends Error {
+  code?: string | undefined;
+  help?: string[] | undefined;
+}
+
+interface ValidationError {
+  code: string;
+  message: string;
+  help: string[];
+}
+
+interface ValidationResult {
+  valid: boolean;
+  exempt?: boolean | undefined;
+  project?: Project | undefined;
+  error?: ValidationError | undefined;
+  requiresAccessCheck?: boolean | undefined;
+  warning?: string | undefined;
+}
+
+interface ValidateOptions {
+  projectOverride?: string | undefined;
+}
+
+interface ParsedProjectFlag {
+  projectOverride: string | null;
+  cleanArgs: string[];
+}
+
+// Lazy-loaded modules
+let _session: Session | null = null;
+let _auth: Auth | null = null;
+let _api: ApiClient | null = null;
+
+function getSession(): Session {
+  if (!_session) {
+    _session = require('./session') as Session;
+  }
+  return _session;
+}
+
+function getAuth(): Auth {
+  if (!_auth) {
+    _auth = require('./auth') as Auth;
+  }
+  return _auth;
+}
+
+function getApi(): ApiClient {
+  if (!_api) {
+    _api = require('./api-client') as ApiClient;
+  }
+  return _api;
+}
+
+// Commands that don't require project context
+export 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
+ */
+export function requiresProjectContext(command: string, subcommand?: string): boolean {
+  // 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
+ */
+export function getProjectContext(): Project | null {
+  return getSession().getEffectiveProject();
+}
+
+/**
+ * Check if project context is set
+ */
+export function hasProjectContext(): boolean {
+  return !!getProjectContext();
+}
+
+/**
+ * Get project ID for API requests
+ */
+export function getProjectId(): string | null {
+  const project = getProjectContext();
+  return project?.id || null;
+}
+
+/**
+ * Get headers for API requests including project context
+ */
+export function getProjectHeaders(): Record<string, string> {
+  const projectId = getProjectId();
+  const headers: Record<string, string> = {};
+
+  if (projectId) {
+    headers['X-Project-Id'] = projectId;
+  }
+
+  return headers;
+}
+
+/**
+ * Require project context - throws if not set
+ */
+export function requireProject(): Project {
+  const project = getProjectContext();
+
+  if (!project) {
+    const error = new Error('No project context set') as ProjectContextError;
+    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
+ */
+export function validateForCommand(
+  command: string,
+  args: string[] = [],
+  options: ValidateOptions = {}
+): ValidationResult {
+  const subcommand = args[0];
+
+  // Check if command is exempt
+  if (!requiresProjectContext(command, subcommand)) {
+    return { valid: true, exempt: true };
+  }
+
+  // Check if user is authenticated
+  if (!getAuth().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
+ */
+export function formatError(error: ValidationError): string {
+  const lines: string[] = [];
+  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
+ */
+export function parseProjectFlag(args: string[]): ParsedProjectFlag {
+  const cleanArgs: string[] = [];
+  let projectOverride: string | null = 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) {
+        const nextArg = args[i + 1];
+        if (nextArg) {
+          projectOverride = nextArg;
+        }
+        i++; // Skip next arg
+      }
+    } else if (arg && arg.startsWith('--project=')) {
+      const value = arg.split('=')[1];
+      if (value) {
+        projectOverride = value;
+      }
+    } else if (arg) {
+      cleanArgs.push(arg);
+    }
+  }
+
+  return { projectOverride, cleanArgs };
+}
+
+/**
+ * Validate user has access to a project (async)
+ * Call this after validateForCommand when requiresAccessCheck is true
+ */
+export async function validateProjectAccessAsync(projectId: string): Promise<ValidationResult> {
+  try {
+    const projects = await getApi().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)'
+    };
+  }
+}