ctxman 3.0.0 → 3.1.0

package/lib/utils/profile-manager.js

@@ -0,0 +1,380 @@
+/**
+ * Profile Manager
+ * Manages team configuration profiles for consistent context generation
+ * FEAT-004: Team Configuration Profiles
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { DEFAULT_TARGET_MODEL } from './llm-detector.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Built-in profiles defined in code for reliability
+ */
+const BUILTIN_PROFILES = {
+  'frontend-team': {
+    name: 'Frontend Team Profile',
+    description: 'Configuration for frontend developers',
+    createdBy: 'ctxman',
+    createdAt: new Date().toISOString(),
+    config: {
+      exclude: ['backend/**', 'server/**', 'api/**', '**/*.test.js', '**/*.spec.js'],
+      include: [
+        'src/**/*.js',
+        'src/**/*.jsx',
+        'src/**/*.ts',
+        'src/**/*.tsx',
+        'components/**',
+        'pages/**',
+      ],
+      targetModel: DEFAULT_TARGET_MODEL,
+      methodLevel: true,
+      methodInclude: ['*Component', '*Hook', '*Context', '*Provider'],
+    },
+  },
+  'backend-team': {
+    name: 'Backend Team Profile',
+    description: 'Configuration for backend developers',
+    createdBy: 'ctxman',
+    createdAt: new Date().toISOString(),
+    config: {
+      exclude: ['frontend/**', 'src/components/**', 'pages/**', '**/*.test.js', '**/*.spec.js'],
+      include: ['api/**', 'server/**', 'lib/**', 'db/**', 'services/**'],
+      targetModel: DEFAULT_TARGET_MODEL,
+      methodLevel: true,
+      methodInclude: ['*Controller', '*Service', '*Repository', '*Handler', '*Middleware'],
+    },
+  },
+  'devops-team': {
+    name: 'DevOps Team Profile',
+    description: 'Configuration for DevOps engineers',
+    createdBy: 'ctxman',
+    createdAt: new Date().toISOString(),
+    config: {
+      exclude: ['**/*.test.js', 'src/**/*.js', 'frontend/**'],
+      include: [
+        '**/*.yaml',
+        '**/*.yml',
+        '**/Dockerfile*',
+        '**/*.sh',
+        'scripts/**',
+        '.github/**',
+        'terraform/**',
+        'k8s/**',
+      ],
+      targetModel: DEFAULT_TARGET_MODEL,
+      methodLevel: false,
+    },
+  },
+  default: {
+    name: 'Default Profile',
+    description: 'Standard configuration for general development',
+    createdBy: 'ctxman',
+    createdAt: new Date().toISOString(),
+    config: {
+      exclude: ['**/*.test.js', '**/*.spec.js', 'node_modules/**', 'coverage/**'],
+      include: ['src/**', 'lib/**'],
+      targetModel: DEFAULT_TARGET_MODEL,
+      methodLevel: false,
+    },
+  },
+};
+
+class ProfileManager {
+  /**
+   * Create a ProfileManager instance
+   * @param {string} projectRoot - Project root directory
+   */
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this.profilesPath = path.join(projectRoot, '.ctxman', 'profiles');
+    this.builtinProfilesPath = path.join(__dirname, '..', '..', '.ctxman', 'profiles');
+  }
+
+  /**
+   * List all available profiles (built-in + custom)
+   * @returns {Array} Array of profile objects
+   */
+  list() {
+    const profiles = [];
+
+    // Add built-in profiles
+    for (const [id, profile] of Object.entries(BUILTIN_PROFILES)) {
+      profiles.push({
+        id,
+        ...profile,
+        source: 'builtin',
+      });
+    }
+
+    // Add custom profiles from project .ctxman/profiles/
+    const customProfiles = this.loadCustomProfiles();
+    profiles.push(...customProfiles);
+
+    return profiles;
+  }
+
+  /**
+   * Get a specific profile by ID
+   * @param {string} profileId - Profile identifier
+   * @returns {object|null} Profile object or null if not found
+   */
+  get(profileId) {
+    // Check built-in first
+    if (BUILTIN_PROFILES[profileId]) {
+      return {
+        id: profileId,
+        ...BUILTIN_PROFILES[profileId],
+        source: 'builtin',
+      };
+    }
+
+    // Check custom profiles
+    const customProfiles = this.loadCustomProfiles();
+    const custom = customProfiles.find((p) => p.id === profileId);
+    if (custom) {
+      return custom;
+    }
+
+    return null;
+  }
+
+  /**
+   * Load custom profiles from .ctxman/profiles/
+   * @returns {Array} Array of custom profile objects
+   */
+  loadCustomProfiles() {
+    const profiles = [];
+
+    try {
+      if (!fs.existsSync(this.profilesPath)) {
+        return profiles;
+      }
+
+      const files = fs.readdirSync(this.profilesPath);
+
+      for (const file of files) {
+        if (!file.endsWith('.json')) {
+          continue;
+        }
+
+        const filePath = path.join(this.profilesPath, file);
+
+        try {
+          const content = fs.readFileSync(filePath, 'utf-8');
+          const profile = JSON.parse(content);
+          const id = path.basename(file, '.json');
+
+          // Skip if already defined as built-in (built-ins take precedence)
+          if (BUILTIN_PROFILES[id]) {
+            continue;
+          }
+
+          profiles.push({
+            id,
+            ...profile,
+            source: 'custom',
+          });
+        } catch (parseError) {
+          console.error(`Warning: Failed to parse profile ${file}: ${parseError.message}`);
+        }
+      }
+    } catch (error) {
+      console.error(`Warning: Failed to load custom profiles: ${error.message}`);
+    }
+
+    return profiles;
+  }
+
+  /**
+   * Apply a profile and get configuration options
+   * @param {string} profileId - Profile identifier
+   * @param {object} options - Additional options to merge
+   * @returns {object} Merged configuration options
+   */
+  apply(profileId, options = {}) {
+    const profile = this.get(profileId);
+
+    if (!profile) {
+      throw new Error(`Profile '${profileId}' not found`);
+    }
+
+    // Build configuration from profile
+    const config = {
+      profileId,
+      profileName: profile.name,
+      profileDescription: profile.description,
+      profileSource: profile.source,
+      // Convert include/exclude patterns to ignore patterns for TokenAnalyzer
+      ignorePatterns: profile.config.exclude || [],
+      includePatterns: profile.config.include || [],
+      methodInclude: profile.config.methodInclude || [],
+      methodLevel: profile.config.methodLevel || false,
+      targetModel: profile.config.targetModel || options.targetModel,
+      ...options,
+    };
+
+    return config;
+  }
+
+  /**
+   * Create a custom profile
+   * @param {string} id - Profile identifier
+   * @param {object} profile - Profile configuration
+   * @returns {string} Path to created profile file
+   */
+  createCustom(id, profile) {
+    // Ensure .ctxman/profiles directory exists
+    if (!fs.existsSync(this.profilesPath)) {
+      fs.mkdirSync(this.profilesPath, { recursive: true });
+    }
+
+    const filePath = path.join(this.profilesPath, `${id}.json`);
+
+    // Validate profile structure
+    this.validateProfile(profile);
+
+    // Add metadata
+    const profileWithMeta = {
+      ...profile,
+      createdAt: new Date().toISOString(),
+    };
+
+    // Write profile file
+    try {
+      // 'wx' fails when the file exists, without a separate check that could go stale
+      fs.writeFileSync(filePath, JSON.stringify(profileWithMeta, null, 2), { flag: 'wx' });
+    } catch (error) {
+      if (error.code === 'EEXIST') throw new Error(`Profile '${id}' already exists`);
+      throw error;
+    }
+
+    return filePath;
+  }
+
+  /**
+   * Validate profile structure
+   * @param {object} profile - Profile to validate
+   * @throws {Error} If profile is invalid
+   */
+  validateProfile(profile) {
+    if (!profile.name || typeof profile.name !== 'string') {
+      throw new Error('Profile must have a "name" string property');
+    }
+
+    if (!profile.description || typeof profile.description !== 'string') {
+      throw new Error('Profile must have a "description" string property');
+    }
+
+    if (!profile.config || typeof profile.config !== 'object') {
+      throw new Error('Profile must have a "config" object property');
+    }
+
+    if (profile.config.exclude && !Array.isArray(profile.config.exclude)) {
+      throw new Error('Profile "config.exclude" must be an array');
+    }
+
+    if (profile.config.include && !Array.isArray(profile.config.include)) {
+      throw new Error('Profile "config.include" must be an array');
+    }
+
+    if (profile.config.methodInclude && !Array.isArray(profile.config.methodInclude)) {
+      throw new Error('Profile "config.methodInclude" must be an array');
+    }
+  }
+
+  /**
+   * Export a profile to JSON
+   * @param {string} profileId - Profile identifier
+   * @returns {object} Profile object ready for export
+   */
+  export(profileId) {
+    const profile = this.get(profileId);
+
+    if (!profile) {
+      throw new Error(`Profile '${profileId}' not found`);
+    }
+
+    // Return clean profile object without metadata
+    return {
+      name: profile.name,
+      description: profile.description,
+      createdBy: profile.createdBy || 'unknown',
+      createdAt: profile.createdAt || new Date().toISOString(),
+      config: profile.config,
+    };
+  }
+
+  /**
+   * Delete a custom profile
+   * @param {string} id - Profile identifier
+   * @returns {boolean} True if deleted, false if not found
+   */
+  deleteCustom(id) {
+    // Prevent deletion of built-in profiles
+    if (BUILTIN_PROFILES[id]) {
+      throw new Error('Cannot delete built-in profiles');
+    }
+
+    const filePath = path.join(this.profilesPath, `${id}.json`);
+
+    if (!fs.existsSync(filePath)) {
+      return false;
+    }
+
+    fs.unlinkSync(filePath);
+    return true;
+  }
+
+  /**
+   * Format profiles for display
+   * @returns {string} Formatted profile list
+   */
+  formatList() {
+    const profiles = this.list();
+    const lines = [];
+
+    lines.push('\n📋 Available Team Configuration Profiles:\n');
+    lines.push('═'.repeat(70));
+
+    // Group by source
+    const builtin = profiles.filter((p) => p.source === 'builtin');
+    const custom = profiles.filter((p) => p.source === 'custom');
+
+    if (builtin.length > 0) {
+      lines.push('\nBuilt-in Profiles:');
+      builtin.forEach((p) => {
+        lines.push(`  ${p.id.padEnd(15)} ${p.description}`);
+      });
+    }
+
+    if (custom.length > 0) {
+      lines.push('\nCustom Profiles:');
+      custom.forEach((p) => {
+        lines.push(`  ${p.id.padEnd(15)} ${p.description}`);
+      });
+    }
+
+    lines.push('\n' + '═'.repeat(70));
+    lines.push('\nUsage:');
+    lines.push('  ctxman --profile <profile-id>');
+    lines.push('  ctxman --profile frontend-team --cli');
+    lines.push('\nProfile Management:');
+    lines.push('  ctxman --list-profiles                List all profiles');
+    lines.push('  ctxman --create-profile <name>        Create a new profile');
+    lines.push('  ctxman --export-profile <name>        Export a profile to JSON');
+    lines.push('\nCustom Profiles:');
+    lines.push('  Add profiles to .ctxman/profiles/<name>.json');
+    lines.push('');
+
+    return lines.join('\n');
+  }
+}
+
+export default ProfileManager;
+export { BUILTIN_PROFILES };

package/lib/utils/safe-read.js

@@ -0,0 +1,61 @@
+/**
+ * Read a file through a single descriptor, so the type, size and location checks hold for
+ * the bytes that are read even when the path is replaced between the checks and the read
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const sameFile = (a, b) => a.ino === b.ino && a.dev === b.dev;
+
+const isInside = (root, target) => {
+  const relative = path.relative(root, target);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+};
+
+/**
+ * @param {string} filePath
+ * @param {Object} [options]
+ * @param {number} [options.maxBytes=Infinity] - Larger files are not read
+ * @param {boolean} [options.followLinks=true] - false: a symbolic link is not a file
+ * @param {string} [options.within] - Real path of a directory the file must resolve inside
+ * @returns {{status: 'ok', buffer: Buffer, stat: fs.Stats}
+ *   | {status: 'not-file' | 'too-large', stat: fs.Stats}
+ *   | {status: 'outside' | 'missing'}}
+ */
+export function readFileChecked(
+  filePath,
+  { maxBytes = Infinity, followLinks = true, within } = {}
+) {
+  let fd;
+  try {
+    // Checked before opening: opening a FIFO would block
+    const before = followLinks ? fs.statSync(filePath) : fs.lstatSync(filePath);
+    if (!before.isFile()) return { status: 'not-file', stat: before };
+
+    fd = fs.openSync(filePath, 'r');
+    const stat = fs.fstatSync(fd);
+    if (!sameFile(stat, before)) return { status: 'missing' };
+    if (within) {
+      const real = fs.realpathSync(filePath);
+      if (!isInside(within, real) || !sameFile(fs.statSync(real), stat)) {
+        return { status: 'outside' };
+      }
+    }
+    if (stat.size > maxBytes) return { status: 'too-large', stat };
+
+    // At most the size checked above, even if the file grows while it is read
+    const buffer = Buffer.alloc(stat.size);
+    let length = 0;
+    while (length < buffer.length) {
+      const read = fs.readSync(fd, buffer, length, buffer.length - length, length);
+      if (read === 0) break;
+      length += read;
+    }
+    return { status: 'ok', buffer: buffer.subarray(0, length), stat };
+  } catch (_error) {
+    return { status: 'missing' };
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}

package/lib/utils/secret-redactor.js

@@ -0,0 +1,61 @@
+/**
+ * Secret Redaction
+ * Masks credentials before file contents are exported for an LLM.
+ *
+ * Only high-precision patterns (fixed prefixes, documented formats): a false
+ * positive silently changes the code the model sees, so generic heuristics such
+ * as `password = "..."` or entropy checks are deliberately left out.
+ */
+
+const SECRET_PATTERNS = [
+  {
+    type: 'private-key',
+    regex:
+      /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?-----END (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----/g,
+  },
+  { type: 'aws-access-key-id', regex: /\b(?:AKIA|ASIA|ABIA|ACCA)[0-9A-Z]{16}\b/g },
+  {
+    type: 'github-token',
+    regex: /\b(?:gh[pousr]_[A-Za-z0-9]{36,255}|github_pat_[A-Za-z0-9_]{22,255})\b/g,
+  },
+  { type: 'gitlab-token', regex: /\bglpat-[A-Za-z0-9_-]{20,}/g },
+  { type: 'slack-token', regex: /\bxox[abposr]-[A-Za-z0-9-]{10,}/g },
+  { type: 'stripe-secret-key', regex: /\b[rs]k_live_[A-Za-z0-9]{20,}\b/g },
+  { type: 'google-api-key', regex: /\bAIza[0-9A-Za-z_-]{35}(?![0-9A-Za-z_-])/g },
+  { type: 'anthropic-api-key', regex: /\bsk-ant-[A-Za-z0-9_-]{20,}/g },
+  // OpenAI keys embed the base64 of "OpenAI" (T3BlbkFJ)
+  { type: 'openai-api-key', regex: /\bsk-[A-Za-z0-9_-]{20,}T3BlbkFJ[A-Za-z0-9_-]{20,}/g },
+  { type: 'npm-token', regex: /\bnpm_[A-Za-z0-9]{36}\b/g },
+];
+
+/**
+ * Replace known secret formats with `[REDACTED:<type>]`
+ * @param {string} text - Content to scan
+ * @returns {{text: string, findings: string[]}} Redacted text and one entry per match
+ */
+export function redactSecrets(text) {
+  const findings = [];
+  let redacted = text;
+
+  for (const { type, regex } of SECRET_PATTERNS) {
+    redacted = redacted.replace(regex, () => {
+      findings.push(type);
+      return `[REDACTED:${type}]`;
+    });
+  }
+
+  return { text: redacted, findings };
+}
+
+/**
+ * Format redaction counts for console output, e.g. "2 aws-access-key-id, 1 private-key"
+ * @param {Object<string, number>} counts - Matches per secret type
+ * @returns {string}
+ */
+export function formatRedactionSummary(counts) {
+  return Object.entries(counts)
+    .map(([type, count]) => `${count} ${type}`)
+    .join(', ');
+}
+
+export default { redactSecrets, formatRedactionSummary };