@girardmedia/bootspring 1.1.0

package/core/context.js

@@ -0,0 +1,329 @@
+/**
+ * Bootspring Context Manager
+ * Handles project context for AI assistants
+ *
+ * @package bootspring
+ * @module core/context
+ */
+
+const fs = require('fs');
+const path = require('path');
+const config = require('./config');
+const utils = require('./utils');
+
+/**
+ * Get current project context
+ * @param {object} [options] - Options
+ * @returns {object} Context object
+ */
+function get(options = {}) {
+  const cfg = options.config || config.load();
+  const projectRoot = cfg._projectRoot;
+
+  const context = {
+    project: cfg.project,
+    stack: cfg.stack,
+    plugins: getEnabledPlugins(cfg),
+    files: getProjectFiles(projectRoot),
+    git: getGitInfo(projectRoot),
+    state: getProjectState(projectRoot, cfg),
+    timestamp: new Date().toISOString()
+  };
+
+  return context;
+}
+
+/**
+ * Get enabled plugins from config
+ * @param {object} cfg - Configuration
+ * @returns {object} Enabled plugins
+ */
+function getEnabledPlugins(cfg) {
+  const enabled = {};
+
+  for (const [name, plugin] of Object.entries(cfg.plugins || {})) {
+    if (plugin.enabled !== false) {
+      enabled[name] = {
+        provider: plugin.provider || 'default',
+        features: plugin.features || []
+      };
+    }
+  }
+
+  return enabled;
+}
+
+/**
+ * Get project file structure summary
+ * @param {string} projectRoot - Project root
+ * @returns {object} File info
+ */
+function getProjectFiles(projectRoot) {
+  const files = {
+    hasPackageJson: utils.fileExists(path.join(projectRoot, 'package.json')),
+    hasTsConfig: utils.fileExists(path.join(projectRoot, 'tsconfig.json')),
+    hasClaudeMd: utils.fileExists(path.join(projectRoot, 'CLAUDE.md')),
+    hasBootspringConfig: utils.fileExists(path.join(projectRoot, 'bootspring.config.js')),
+    hasTodoMd: utils.fileExists(path.join(projectRoot, 'todo.md')),
+    hasGit: utils.fileExists(path.join(projectRoot, '.git')),
+    hasSrcDir: utils.fileExists(path.join(projectRoot, 'src')),
+    hasAppDir: utils.fileExists(path.join(projectRoot, 'app')),
+    hasPagesDir: utils.fileExists(path.join(projectRoot, 'pages'))
+  };
+
+  // Detect framework structure
+  if (files.hasAppDir) {
+    files.structure = 'app-router';
+  } else if (files.hasPagesDir) {
+    files.structure = 'pages-router';
+  } else if (files.hasSrcDir) {
+    files.structure = 'src-based';
+  } else {
+    files.structure = 'flat';
+  }
+
+  return files;
+}
+
+/**
+ * Get git information
+ * @param {string} projectRoot - Project root
+ * @returns {object} Git info
+ */
+function getGitInfo(projectRoot) {
+  const gitDir = path.join(projectRoot, '.git');
+
+  if (!utils.fileExists(gitDir)) {
+    return { initialized: false };
+  }
+
+  const info = { initialized: true };
+
+  // Get current branch
+  const headPath = path.join(gitDir, 'HEAD');
+  if (utils.fileExists(headPath)) {
+    const head = utils.readFile(headPath).trim();
+    if (head.startsWith('ref: refs/heads/')) {
+      info.branch = head.replace('ref: refs/heads/', '');
+    }
+  }
+
+  // Check for remote
+  const configPath = path.join(gitDir, 'config');
+  if (utils.fileExists(configPath)) {
+    const gitConfig = utils.readFile(configPath);
+    info.hasRemote = gitConfig.includes('[remote "origin"]');
+  }
+
+  return info;
+}
+
+/**
+ * Get project state
+ * @param {string} projectRoot - Project root
+ * @param {object} cfg - Configuration
+ * @returns {object} State info
+ */
+function getProjectState(projectRoot, cfg) {
+  const state = {
+    phase: 'unknown',
+    health: 'unknown',
+    todos: 0,
+    lastGenerated: null
+  };
+
+  // Count todos
+  const todoPath = path.join(projectRoot, cfg.paths?.todo || 'todo.md');
+  if (utils.fileExists(todoPath)) {
+    const content = utils.readFile(todoPath);
+    const todoMatches = content.match(/- \[ \]/g);
+    state.todos = todoMatches ? todoMatches.length : 0;
+  }
+
+  // Check CLAUDE.md generation time
+  const claudePath = path.join(projectRoot, cfg.paths?.context || 'CLAUDE.md');
+  if (utils.fileExists(claudePath)) {
+    state.lastGenerated = utils.getFileTime(claudePath);
+  }
+
+  // Determine phase
+  if (!cfg._configPath) {
+    state.phase = 'uninitialized';
+  } else if (!state.lastGenerated) {
+    state.phase = 'initialized';
+  } else {
+    state.phase = 'active';
+  }
+
+  // Determine health
+  const issues = [];
+  if (!utils.fileExists(path.join(projectRoot, 'package.json'))) {
+    issues.push('missing-package-json');
+  }
+  if (!cfg._configPath) {
+    issues.push('missing-config');
+  }
+  if (!state.lastGenerated) {
+    issues.push('missing-context');
+  }
+
+  if (issues.length === 0) {
+    state.health = 'good';
+  } else if (issues.length <= 2) {
+    state.health = 'fair';
+  } else {
+    state.health = 'needs-attention';
+  }
+
+  state.issues = issues;
+
+  return state;
+}
+
+/**
+ * Validate project context
+ * @param {object} [options] - Options
+ * @returns {object} Validation result
+ */
+function validate(options = {}) {
+  const cfg = options.config || config.load();
+  const projectRoot = cfg._projectRoot;
+
+  const checks = [];
+  let score = 0;
+  const maxScore = 10;
+
+  // Check 1: Config exists
+  if (cfg._configPath) {
+    checks.push({ name: 'Configuration', status: 'pass', message: 'bootspring.config.js found' });
+    score += 2;
+  } else {
+    checks.push({ name: 'Configuration', status: 'fail', message: 'bootspring.config.js missing' });
+  }
+
+  // Check 2: CLAUDE.md exists
+  const claudePath = path.join(projectRoot, cfg.paths?.context || 'CLAUDE.md');
+  if (utils.fileExists(claudePath)) {
+    checks.push({ name: 'AI Context', status: 'pass', message: 'CLAUDE.md exists' });
+    score += 2;
+  } else {
+    checks.push({ name: 'AI Context', status: 'fail', message: 'CLAUDE.md missing - run bootspring generate' });
+  }
+
+  // Check 3: package.json exists
+  if (utils.fileExists(path.join(projectRoot, 'package.json'))) {
+    checks.push({ name: 'Package', status: 'pass', message: 'package.json found' });
+    score += 1;
+  } else {
+    checks.push({ name: 'Package', status: 'warn', message: 'package.json missing' });
+  }
+
+  // Check 4: Git initialized
+  if (utils.fileExists(path.join(projectRoot, '.git'))) {
+    checks.push({ name: 'Git', status: 'pass', message: 'Git repository initialized' });
+    score += 1;
+  } else {
+    checks.push({ name: 'Git', status: 'warn', message: 'Git not initialized' });
+  }
+
+  // Check 5: TypeScript config (if using TS)
+  if (cfg.stack?.language === 'typescript') {
+    if (utils.fileExists(path.join(projectRoot, 'tsconfig.json'))) {
+      checks.push({ name: 'TypeScript', status: 'pass', message: 'tsconfig.json found' });
+      score += 1;
+    } else {
+      checks.push({ name: 'TypeScript', status: 'fail', message: 'tsconfig.json missing for TypeScript project' });
+    }
+  } else {
+    score += 1;
+  }
+
+  // Check 6: Config validation
+  const configValidation = config.validate(cfg);
+  if (configValidation.valid) {
+    checks.push({ name: 'Config Validation', status: 'pass', message: 'Configuration is valid' });
+    score += 2;
+  } else {
+    checks.push({ name: 'Config Validation', status: 'fail', message: configValidation.errors.join(', ') });
+  }
+
+  // Check 7: Todo file
+  if (utils.fileExists(path.join(projectRoot, cfg.paths?.todo || 'todo.md'))) {
+    checks.push({ name: 'Todo Tracking', status: 'pass', message: 'todo.md exists' });
+    score += 1;
+  } else {
+    checks.push({ name: 'Todo Tracking', status: 'info', message: 'todo.md not found - optional' });
+    score += 0.5;
+  }
+
+  return {
+    valid: score >= maxScore * 0.6,
+    score,
+    maxScore,
+    percentage: Math.round((score / maxScore) * 100),
+    checks
+  };
+}
+
+/**
+ * Generate context summary for AI
+ * @param {object} [options] - Options
+ * @returns {string} Context summary markdown
+ */
+function generateSummary(options = {}) {
+  const ctx = get(options);
+
+  const lines = [
+    `# Project Context`,
+    ``,
+    `**Project**: ${ctx.project.name}`,
+    `**Generated**: ${ctx.timestamp}`,
+    ``,
+    `## Stack`,
+    `- Framework: ${ctx.stack.framework}`,
+    `- Language: ${ctx.stack.language}`,
+    `- Database: ${ctx.stack.database}`,
+    `- Hosting: ${ctx.stack.hosting}`,
+    ``
+  ];
+
+  // Plugins
+  const enabledPlugins = Object.keys(ctx.plugins);
+  if (enabledPlugins.length > 0) {
+    lines.push(`## Enabled Plugins`);
+    for (const [name, plugin] of Object.entries(ctx.plugins)) {
+      lines.push(`- **${name}**: ${plugin.provider}`);
+    }
+    lines.push(``);
+  }
+
+  // State
+  lines.push(`## Project State`);
+  lines.push(`- Phase: ${ctx.state.phase}`);
+  lines.push(`- Health: ${ctx.state.health}`);
+  lines.push(`- Open Todos: ${ctx.state.todos}`);
+  if (ctx.state.lastGenerated) {
+    lines.push(`- Context Last Generated: ${utils.formatRelativeTime(ctx.state.lastGenerated)}`);
+  }
+  lines.push(``);
+
+  // Git
+  if (ctx.git.initialized) {
+    lines.push(`## Git`);
+    lines.push(`- Branch: ${ctx.git.branch || 'unknown'}`);
+    lines.push(`- Remote: ${ctx.git.hasRemote ? 'configured' : 'not configured'}`);
+    lines.push(``);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  get,
+  validate,
+  generateSummary,
+  getEnabledPlugins,
+  getProjectFiles,
+  getGitInfo,
+  getProjectState
+};

package/core/entitlements.js

@@ -0,0 +1,209 @@
+/**
+ * Bootspring Entitlements
+ * Shared access policy for gated capabilities.
+ */
+
+const LOCAL_MODE = 'local';
+const SERVER_MODE = 'server';
+const PRO_TIERS = new Set(['pro', 'team', 'enterprise']);
+const policies = require('./policies');
+
+function parseBoolean(value) {
+  if (typeof value === 'boolean') return value;
+  if (value === null || value === undefined) return false;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
+}
+
+function normalizeMode(value) {
+  const mode = String(value || '').trim().toLowerCase();
+  if (mode === SERVER_MODE) {
+    return SERVER_MODE;
+  }
+  return LOCAL_MODE;
+}
+
+function resolveAccessContext(options = {}) {
+  const envMode = process.env.BOOTSPRING_SKILL_ACCESS_MODE;
+  const envTier = process.env.BOOTSPRING_USER_TIER;
+  const envEntitled = process.env.BOOTSPRING_SKILLS_ENTITLED;
+
+  return {
+    mode: normalizeMode(options.mode || envMode),
+    tier: String(options.tier || envTier || 'free').trim().toLowerCase(),
+    entitled: parseBoolean(options.entitled ?? envEntitled),
+    policyProfile: policies.resolvePolicyProfile(options)
+  };
+}
+
+function resolveWorkflowAccessContext(options = {}) {
+  const envMode = process.env.BOOTSPRING_WORKFLOW_ACCESS_MODE || process.env.BOOTSPRING_SKILL_ACCESS_MODE;
+  const envTier = process.env.BOOTSPRING_USER_TIER;
+  const envEntitled = process.env.BOOTSPRING_WORKFLOWS_ENTITLED ?? process.env.BOOTSPRING_SKILLS_ENTITLED;
+
+  return {
+    mode: normalizeMode(options.mode || envMode),
+    tier: String(options.tier || envTier || 'free').trim().toLowerCase(),
+    entitled: parseBoolean(options.entitled ?? envEntitled),
+    policyProfile: policies.resolvePolicyProfile(options)
+  };
+}
+
+function isExternalSkill(skillId) {
+  return String(skillId || '').startsWith('external/');
+}
+
+function checkSkillAccess(skillId, options = {}) {
+  const context = resolveAccessContext(options);
+
+  if (!isExternalSkill(skillId)) {
+    return {
+      allowed: true,
+      code: 'built_in',
+      reason: 'Built-in skills are always available.',
+      context
+    };
+  }
+
+  const policy = policies.getPolicyProfile(context.policyProfile, options);
+  if (!policy.allowExternalSkills) {
+    return {
+      allowed: false,
+      code: 'external_policy_blocked',
+      reason: `External skills are blocked by ${policy.id} policy profile.`,
+      context
+    };
+  }
+
+  if (context.mode !== SERVER_MODE) {
+    return {
+      allowed: true,
+      code: 'external_local_mode',
+      reason: 'External skills are enabled in local mode.',
+      context
+    };
+  }
+
+  if (context.entitled || PRO_TIERS.has(context.tier)) {
+    return {
+      allowed: true,
+      code: 'external_entitled',
+      reason: 'External skill access granted.',
+      context
+    };
+  }
+
+  return {
+    allowed: false,
+    code: 'external_subscription_required',
+    reason: 'External skills require entitlement in server mode. Set BOOTSPRING_SKILLS_ENTITLED=true or use tier=pro/team/enterprise.',
+    context
+  };
+}
+
+function filterAccessibleSkills(skillIds, options = {}) {
+  const allowed = [];
+  const denied = [];
+
+  for (const skillId of skillIds || []) {
+    const decision = checkSkillAccess(skillId, options);
+    if (decision.allowed) {
+      allowed.push(skillId);
+    } else {
+      denied.push({
+        skillId,
+        code: decision.code,
+        reason: decision.reason
+      });
+    }
+  }
+
+  return { allowed, denied };
+}
+
+function isPremiumWorkflow(workflow) {
+  const tier = String(workflow?.tier || 'free').toLowerCase();
+  return tier !== 'free';
+}
+
+function checkWorkflowAccess(workflow, options = {}) {
+  const context = resolveWorkflowAccessContext(options);
+  const policy = policies.getPolicyProfile(context.policyProfile, options);
+
+  if (policies.isWorkflowBlocked(workflow, policy)) {
+    return {
+      allowed: false,
+      code: 'workflow_policy_blocked',
+      reason: `Workflow ${workflow?.key || workflow?.name || 'unknown'} is blocked by ${policy.id} policy profile.`,
+      context
+    };
+  }
+
+  if (!isPremiumWorkflow(workflow)) {
+    return {
+      allowed: true,
+      code: 'workflow_free',
+      reason: 'Workflow is available on free tier.',
+      context
+    };
+  }
+
+  if (context.mode !== SERVER_MODE) {
+    return {
+      allowed: true,
+      code: 'workflow_local_mode',
+      reason: 'Premium workflows are enabled in local mode.',
+      context
+    };
+  }
+
+  if (context.entitled || PRO_TIERS.has(context.tier)) {
+    return {
+      allowed: true,
+      code: 'workflow_entitled',
+      reason: 'Premium workflow access granted.',
+      context
+    };
+  }
+
+  return {
+    allowed: false,
+    code: 'workflow_subscription_required',
+    reason: 'Premium workflows require entitlement in server mode. Set BOOTSPRING_WORKFLOWS_ENTITLED=true or use tier=pro/team/enterprise.',
+    context
+  };
+}
+
+function filterAccessibleWorkflows(workflows, options = {}) {
+  const allowed = [];
+  const denied = [];
+
+  for (const workflow of workflows || []) {
+    const decision = checkWorkflowAccess(workflow, options);
+    if (decision.allowed) {
+      allowed.push(workflow);
+    } else {
+      denied.push({
+        key: workflow?.key,
+        name: workflow?.name,
+        code: decision.code,
+        reason: decision.reason
+      });
+    }
+  }
+
+  return { allowed, denied };
+}
+
+module.exports = {
+  LOCAL_MODE,
+  SERVER_MODE,
+  resolveAccessContext,
+  resolveWorkflowAccessContext,
+  isExternalSkill,
+  checkSkillAccess,
+  filterAccessibleSkills,
+  isPremiumWorkflow,
+  checkWorkflowAccess,
+  filterAccessibleWorkflows
+};

package/core/index.js

@@ -0,0 +1,43 @@
+/**
+ * Bootspring Core
+ * Main exports for the Bootspring package
+ *
+ * @package bootspring
+ * @module core
+ */
+
+const config = require('./config');
+const context = require('./context');
+const utils = require('./utils');
+const policies = require('./policies');
+const entitlements = require('./entitlements');
+const telemetry = require('./telemetry');
+const packageJson = require('../package.json');
+
+module.exports = {
+  // Version
+  VERSION: packageJson.version,
+
+  // Core modules
+  config,
+  context,
+  utils,
+  policies,
+  entitlements,
+  telemetry,
+
+  // Convenience exports
+  loadConfig: config.load,
+  getContext: context.get,
+  validateContext: context.validate,
+  checkSkillAccess: entitlements.checkSkillAccess,
+  checkWorkflowAccess: entitlements.checkWorkflowAccess,
+
+  // Brand info
+  BRAND: {
+    name: 'Bootspring',
+    tagline: 'Development scaffolding with intelligence',
+    website: 'https://bootspring.com',
+    docs: 'https://bootspring.com/docs'
+  }
+};

package/core/policies.js

@@ -0,0 +1,68 @@
+/**
+ * Bootspring policy profiles
+ * Team-level controls for capability gating.
+ */
+
+const DEFAULT_POLICY_PROFILE = 'startup';
+
+const POLICY_PROFILES = {
+  startup: {
+    id: 'startup',
+    name: 'Startup',
+    allowExternalSkills: true,
+    blockedWorkflows: []
+  },
+  regulated: {
+    id: 'regulated',
+    name: 'Regulated',
+    allowExternalSkills: false,
+    blockedWorkflows: ['growth-pack']
+  },
+  enterprise: {
+    id: 'enterprise',
+    name: 'Enterprise',
+    allowExternalSkills: true,
+    blockedWorkflows: []
+  }
+};
+
+function normalizeProfile(profile) {
+  const key = String(profile || DEFAULT_POLICY_PROFILE).trim().toLowerCase();
+  return POLICY_PROFILES[key] ? key : DEFAULT_POLICY_PROFILE;
+}
+
+function parseCsvList(value) {
+  if (!value) return [];
+  return String(value)
+    .split(',')
+    .map(item => item.trim())
+    .filter(Boolean);
+}
+
+function resolvePolicyProfile(options = {}) {
+  return normalizeProfile(options.policyProfile || process.env.BOOTSPRING_POLICY_PROFILE);
+}
+
+function getPolicyProfile(profile, options = {}) {
+  const key = normalizeProfile(profile);
+  const base = POLICY_PROFILES[key];
+  const blockedFromEnv = parseCsvList(options.blockedWorkflows || process.env.BOOTSPRING_POLICY_BLOCKED_WORKFLOWS);
+  return {
+    ...base,
+    blockedWorkflows: Array.from(new Set([...(base.blockedWorkflows || []), ...blockedFromEnv]))
+  };
+}
+
+function isWorkflowBlocked(workflow, profile) {
+  const workflowKey = String(workflow?.key || '').trim();
+  if (!workflowKey) return false;
+  return (profile.blockedWorkflows || []).includes(workflowKey);
+}
+
+module.exports = {
+  DEFAULT_POLICY_PROFILE,
+  POLICY_PROFILES,
+  resolvePolicyProfile,
+  getPolicyProfile,
+  isWorkflowBlocked
+};