threadlines 0.2.7 → 0.2.9

package/dist/api/client.js

@@ -16,23 +16,8 @@ class ReviewAPIClient {
         });
     }
     async review(request) {
-        try {
-            const response = await this.client.post('/api/threadline-check', request);
-            return response.data;
-        }
-        catch (error) {
-            if (error && typeof error === 'object' && 'response' in error) {
-                const axiosError = error;
-                throw new Error(`API error: ${axiosError.response.status} - ${axiosError.response.data?.message || axiosError.message || 'Unknown error'}`);
-            }
-            else if (error && typeof error === 'object' && 'request' in error) {
-                throw new Error(`Network error: Could not reach Threadline server at ${this.client.defaults.baseURL}`);
-            }
-            else {
-                const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-                throw new Error(`Request error: ${errorMessage}`);
-            }
-        }
+        const response = await this.client.post('/api/threadline-check', request);
+        return response.data;
     }
 }
 exports.ReviewAPIClient = ReviewAPIClient;

package/dist/commands/check.js

@@ -48,6 +48,8 @@ const bitbucket_1 = require("../git/bitbucket");
 const vercel_1 = require("../git/vercel");
 const local_1 = require("../git/local");
 const diff_1 = require("../git/diff");
+const config_file_1 = require("../utils/config-file");
+const logger_1 = require("../utils/logger");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const chalk_1 = __importDefault(require("chalk"));
@@ -77,6 +79,8 @@ const CLI_VERSION = packageJson.version;
 async function checkCommand(options) {
     const cwd = process.cwd();
     const repoRoot = cwd; // Keep for backward compatibility with rest of function
+    // Load configuration
+    const config = await (0, config_file_1.loadConfig)(cwd);
     console.log(chalk_1.default.blue(`🔍 Threadline CLI v${CLI_VERSION}: Checking code against your threadlines...\n`));
     // Get git root for consistent file paths across monorepo
     const git = (0, simple_git_1.default)(cwd);
@@ -84,13 +88,13 @@ async function checkCommand(options) {
     try {
         const isRepo = await git.checkIsRepo();
         if (!isRepo) {
-            console.error(chalk_1.default.red('❌ Error: Not a git repository. Threadline requires a git repository.'));
+            logger_1.logger.error('Not a git repository. Threadline requires a git repository.');
             process.exit(1);
         }
         gitRoot = (await git.revparse(['--show-toplevel'])).trim();
     }
     catch {
-        console.error(chalk_1.default.red('❌ Error: Failed to get git root. Make sure you are in a git repository.'));
+        logger_1.logger.error('Failed to get git root. Make sure you are in a git repository.');
         process.exit(1);
     }
     // Pre-flight check: Validate ALL required environment variables at once
@@ -103,9 +107,9 @@ async function checkCommand(options) {
     if (!account || account.startsWith('$'))
         missingVars.push('THREADLINE_ACCOUNT');
     if (missingVars.length > 0) {
-        console.error(chalk_1.default.red('❌ Error: Missing required environment variables:'));
+        logger_1.logger.error('Missing required environment variables:');
         for (const varName of missingVars) {
-            console.error(chalk_1.default.red(`   • ${varName}`));
+            logger_1.logger.error(`   • ${varName}`);
         }
         console.log('');
         console.log(chalk_1.default.yellow('To fix this:'));
@@ -132,7 +136,7 @@ async function checkCommand(options) {
     }
     try {
         // 1. Find and validate threadlines
-        console.log(chalk_1.default.gray('📋 Finding threadlines...'));
+        logger_1.logger.info('Finding threadlines...');
         const threadlines = await (0, experts_1.findThreadlines)(cwd, gitRoot);
         console.log(chalk_1.default.green(`✓ Found ${threadlines.length} threadline(s)\n`));
         if (threadlines.length === 0) {
@@ -150,7 +154,7 @@ async function checkCommand(options) {
         const explicitFlags = [options.commit, options.file, options.folder, options.files].filter(Boolean);
         // Validate mutually exclusive flags
         if (explicitFlags.length > 1) {
-            console.error(chalk_1.default.red('❌ Error: Only one review option can be specified at a time'));
+            logger_1.logger.error('Only one review option can be specified at a time');
             console.log(chalk_1.default.gray('   Options: --commit, --file, --folder, --files'));
             process.exit(1);
         }
@@ -162,7 +166,7 @@ async function checkCommand(options) {
                 const flagName = options.commit ? '--commit' :
                     options.file ? '--file' :
                         options.folder ? '--folder' : '--files';
-                console.log(chalk_1.default.yellow(`⚠️  Warning: ${flagName} flag ignored in CI environment. Using auto-detection.\n`));
+                logger_1.logger.warn(`${flagName} flag ignored in CI environment. Using auto-detection.`);
             }
             // CI auto-detect: use environment-specific context
             const envNames = {
@@ -171,7 +175,7 @@ async function checkCommand(options) {
                 gitlab: 'GitLab CI',
                 bitbucket: 'Bitbucket Pipelines'
             };
-            console.log(chalk_1.default.gray(`📝 Collecting git context for ${envNames[environment]}...`));
+            logger_1.logger.info(`Collecting git context for ${envNames[environment]}...`);
             const envContext = await getContextForEnvironment(environment, repoRoot);
             gitDiff = envContext.diff;
             repoName = envContext.repoName;
@@ -187,19 +191,19 @@ async function checkCommand(options) {
         else {
             // Local environment: support all flags
             if (options.file) {
-                console.log(chalk_1.default.gray(`📝 Reading file: ${options.file}...`));
+                logger_1.logger.info(`Reading file: ${options.file}...`);
                 gitDiff = await (0, file_1.getFileContent)(repoRoot, options.file);
             }
             else if (options.folder) {
-                console.log(chalk_1.default.gray(`📝 Reading folder: ${options.folder}...`));
+                logger_1.logger.info(`Reading folder: ${options.folder}...`);
                 gitDiff = await (0, file_1.getFolderContent)(repoRoot, options.folder);
             }
             else if (options.files && options.files.length > 0) {
-                console.log(chalk_1.default.gray(`📝 Reading ${options.files.length} file(s)...`));
+                logger_1.logger.info(`Reading ${options.files.length} file(s)...`);
                 gitDiff = await (0, file_1.getMultipleFilesContent)(repoRoot, options.files);
             }
             else if (options.commit) {
-                console.log(chalk_1.default.gray(`📝 Collecting git changes for commit: ${options.commit}...`));
+                logger_1.logger.info(`Collecting git changes for commit: ${options.commit}...`);
                 gitDiff = await (0, diff_1.getCommitDiff)(repoRoot, options.commit);
                 // Use local context for metadata, passing commit SHA for author lookup
                 const localContext = await (0, local_1.getLocalContext)(repoRoot, options.commit);
@@ -214,7 +218,7 @@ async function checkCommand(options) {
             }
             else {
                 // Local auto-detect: staged/unstaged changes
-                console.log(chalk_1.default.gray('📝 Collecting git context for Local...'));
+                logger_1.logger.info('Collecting git context for Local...');
                 const localContext = await (0, local_1.getLocalContext)(repoRoot);
                 gitDiff = localContext.diff;
                 repoName = localContext.repoName;
@@ -264,13 +268,9 @@ async function checkCommand(options) {
                 contextContent
             };
         });
-        // 5. Get API URL
-        const apiUrl = options.apiUrl ||
-            process.env.THREADLINE_API_URL ||
-            'https://devthreadline.com';
-        // 6. Call review API
-        console.log(chalk_1.default.gray('🤖 Running threadline checks...'));
-        const client = new client_1.ReviewAPIClient(apiUrl);
+        // 5. Call review API
+        logger_1.logger.info('Running threadline checks...');
+        const client = new client_1.ReviewAPIClient(config.api_url);
         const response = await client.review({
             threadlines: threadlinesWithContext,
             diff: gitDiff.diff,
@@ -295,7 +295,7 @@ async function checkCommand(options) {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        console.error(chalk_1.default.red(`\n❌ Error: ${errorMessage}`));
+        logger_1.logger.error(errorMessage);
         process.exit(1);
     }
 }

package/dist/commands/init.js

@@ -40,6 +40,8 @@ exports.initCommand = initCommand;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const chalk_1 = __importDefault(require("chalk"));
+const logger_1 = require("../utils/logger");
+const config_file_1 = require("../utils/config-file");
 const TEMPLATE = `---
 id: example-threadline
 version: 1.0.0
@@ -75,12 +77,19 @@ async function initCommand() {
     const repoRoot = process.cwd();
     const threadlinesDir = path.join(repoRoot, 'threadlines');
     const exampleFile = path.join(threadlinesDir, 'example.md');
+    const configFile = path.join(repoRoot, '.threadlinerc');
     try {
         // Create threadlines directory if it doesn't exist
         if (!fs.existsSync(threadlinesDir)) {
             fs.mkdirSync(threadlinesDir, { recursive: true });
             console.log(chalk_1.default.green(`✓ Created /threadlines directory`));
         }
+        // Create .threadlinerc if it doesn't exist
+        if (!fs.existsSync(configFile)) {
+            const configContent = JSON.stringify(config_file_1.DEFAULT_CONFIG, null, 2);
+            fs.writeFileSync(configFile, configContent, 'utf-8');
+            console.log(chalk_1.default.green(`✓ Created .threadlinerc`));
+        }
         // Check if example file already exists
         if (fs.existsSync(exampleFile)) {
             console.log(chalk_1.default.yellow(`⚠️  ${exampleFile} already exists`));
@@ -109,7 +118,7 @@ async function initCommand() {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        console.error(chalk_1.default.red(`\n❌ Error: ${errorMessage}`));
+        logger_1.logger.error(errorMessage);
         process.exit(1);
     }
 }

package/dist/git/bitbucket.js

@@ -25,6 +25,7 @@ exports.getBitbucketContext = getBitbucketContext;
 const simple_git_1 = __importDefault(require("simple-git"));
 const child_process_1 = require("child_process");
 const diff_1 = require("./diff");
+const logger_1 = require("../utils/logger");
 /**
  * Gets all Bitbucket context in one call
  */
@@ -66,22 +67,26 @@ async function getBitbucketContext(repoRoot) {
  * Get diff for Bitbucket Pipelines environment
  *
  * Strategy:
- * - PR context: Compare source branch vs target branch (full PR diff)
+ * - PR context: Fetch destination branch on-demand, compare source vs target (full PR diff)
  * - Any push (main or feature branch): Compare last commit only (HEAD~1...HEAD)
  *
- * Note: Bitbucket Pipelines with depth: full has full git history available.
+ * Note: We fetch the destination branch on-demand so this works with shallow clones.
+ * Users don't need `depth: full` in their bitbucket-pipelines.yml.
  */
 async function getDiff(repoRoot) {
     const git = (0, simple_git_1.default)(repoRoot);
     const prId = process.env.BITBUCKET_PR_ID;
     const prDestinationBranch = process.env.BITBUCKET_PR_DESTINATION_BRANCH;
-    // PR Context: Compare source vs target branch
+    // PR Context: Fetch destination branch and compare
     if (prId) {
         if (!prDestinationBranch) {
             throw new Error('Bitbucket PR context detected but BITBUCKET_PR_DESTINATION_BRANCH is not set. ' +
                 'This should be automatically provided by Bitbucket Pipelines.');
         }
-        console.log(`  [Bitbucket] PR #${prId}, using origin/${prDestinationBranch}...HEAD`);
+        // Fetch destination branch on-demand (works with shallow clones)
+        logger_1.logger.debug(`Fetching destination branch: origin/${prDestinationBranch}`);
+        await git.fetch(['origin', `${prDestinationBranch}:refs/remotes/origin/${prDestinationBranch}`, '--depth=1']);
+        logger_1.logger.debug(`PR #${prId}, using origin/${prDestinationBranch}...HEAD`);
         const diff = await git.diff([`origin/${prDestinationBranch}...HEAD`, '-U200']);
         const diffSummary = await git.diffSummary([`origin/${prDestinationBranch}...HEAD`]);
         const changedFiles = diffSummary.files.map(f => f.file);

package/dist/git/file.js

@@ -39,6 +39,7 @@ exports.getMultipleFilesContent = getMultipleFilesContent;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const glob_1 = require("glob");
+const logger_1 = require("../utils/logger");
 /**
  * Read content of a single file and create artificial diff (all lines as additions)
  */
@@ -116,7 +117,7 @@ async function getFolderContent(repoRoot, folderPath) {
         catch (error) {
             // Skip files that can't be read (permissions, etc.)
             const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            console.warn(`Warning: Could not read file '${filePath}': ${errorMessage}`);
+            logger_1.logger.warn(`Could not read file '${filePath}': ${errorMessage}`);
         }
     }
     return {

package/dist/git/github.js

@@ -98,6 +98,12 @@ async function getGitHubContext(repoRoot) {
  * Strategy:
  * - PR context: Compare source branch vs target branch (full PR diff)
  * - Any push (main or feature branch): Compare last commit only (HEAD~1...HEAD)
+ *
+ * Note: Unlike GitLab/Bitbucket, we don't need to fetch branches on-demand here.
+ * GitHub Actions' `actions/checkout` automatically fetches both base and head refs
+ * for pull_request events, even with the default shallow clone (fetch-depth: 1).
+ * The refs `origin/${GITHUB_BASE_REF}` and `origin/${GITHUB_HEAD_REF}` are available
+ * immediately after checkout.
  */
 async function getDiff(repoRoot) {
     const git = (0, simple_git_1.default)(repoRoot);
@@ -105,6 +111,7 @@ async function getDiff(repoRoot) {
     const baseRef = process.env.GITHUB_BASE_REF;
     const headRef = process.env.GITHUB_HEAD_REF;
     // PR Context: Compare source vs target branch
+    // No fetch needed - GitHub Actions provides both refs automatically
     if (eventName === 'pull_request') {
         if (!baseRef || !headRef) {
             throw new Error('GitHub PR context detected but GITHUB_BASE_REF or GITHUB_HEAD_REF is missing. ' +

package/dist/git/gitlab.js

@@ -19,6 +19,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getGitLabContext = getGitLabContext;
 const simple_git_1 = __importDefault(require("simple-git"));
 const diff_1 = require("./diff");
+const logger_1 = require("../utils/logger");
 /**
  * Gets all GitLab context
  */
@@ -80,7 +81,7 @@ async function getDiff(repoRoot) {
                 'CI_MERGE_REQUEST_SOURCE_BRANCH_NAME is missing. ' +
                 'This should be automatically provided by GitLab CI.');
         }
-        console.log(`  [GitLab] Fetching target branch: origin/${targetBranch}`);
+        logger_1.logger.debug(`Fetching target branch: origin/${targetBranch}`);
         await git.fetch(['origin', `${targetBranch}:refs/remotes/origin/${targetBranch}`, '--depth=1']);
         const diff = await git.diff([`origin/${targetBranch}...origin/${sourceBranch}`, '-U200']);
         const diffSummary = await git.diffSummary([`origin/${targetBranch}...origin/${sourceBranch}`]);

package/dist/index.js

@@ -49,6 +49,7 @@ if (fs.existsSync(envLocalPath)) {
 const commander_1 = require("commander");
 const check_1 = require("./commands/check");
 const init_1 = require("./commands/init");
+const logger_1 = require("./utils/logger");
 const program = new commander_1.Command();
 program
     .name('threadlines')
@@ -57,27 +58,39 @@ program
 program
     .command('init')
     .description('Create a template threadline file to get started')
-    .action(init_1.initCommand);
+    .option('--debug', 'Enable debug logging (verbose output)')
+    .action((options) => {
+    if (options.debug) {
+        (0, logger_1.enableDebug)();
+    }
+    (0, init_1.initCommand)();
+});
 program
     .command('check')
     .description('Check code against your threadlines')
-    .option('--api-url <url>', 'Threadline server URL', process.env.THREADLINE_API_URL || 'https://devthreadline.com')
     .option('--full', 'Show all results (compliant, attention, not_relevant). Default: only attention items')
     .option('--commit <ref>', 'Review specific commit. Accepts commit SHA or git reference (e.g., HEAD, HEAD~1, abc123). Example: --commit HEAD')
     .option('--file <path>', 'Review entire file (all lines as additions)')
     .option('--folder <path>', 'Review all files in folder recursively')
     .option('--files <paths...>', 'Review multiple specified files')
+    .option('--debug', 'Enable debug logging (verbose output)')
     .addHelpText('after', `
 Examples:
   $ threadlines check                    # Check staged/unstaged changes (local dev)
   $ threadlines check --commit HEAD      # Check latest commit locally
   $ threadlines check --file src/api.ts  # Check entire file
   $ threadlines check --full             # Show all results (not just attention items)
+  $ threadlines check --debug            # Enable verbose debug output
 
 Auto-detection in CI:
   - PR/MR context → reviews all changes in the PR/MR
   - Push to any branch → reviews the commit being pushed
   - Local development → reviews staged/unstaged changes
 `)
-    .action(check_1.checkCommand);
+    .action((options) => {
+    if (options.debug) {
+        (0, logger_1.enableDebug)();
+    }
+    (0, check_1.checkCommand)(options);
+});
 program.parse();

package/dist/utils/config-file.js

@@ -0,0 +1,118 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG = void 0;
+exports.loadConfig = loadConfig;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const simple_git_1 = __importDefault(require("simple-git"));
+exports.DEFAULT_CONFIG = {
+    mode: 'online',
+    api_url: 'https://devthreadline.com',
+    openai_model: 'gpt-5.2',
+    openai_service_tier: 'Flex',
+    diff_context_lines: 10,
+};
+/**
+ * Finds the git root directory by walking up from startDir.
+ * Returns startDir if not in a git repository.
+ */
+async function findGitRoot(startDir) {
+    try {
+        const git = (0, simple_git_1.default)(startDir);
+        const isRepo = await git.checkIsRepo();
+        if (isRepo) {
+            return (await git.revparse(['--show-toplevel'])).trim();
+        }
+    }
+    catch {
+        // Not a git repo or error - return startDir
+    }
+    return startDir;
+}
+/**
+ * Loads configuration from .threadlinerc file.
+ *
+ * Priority:
+ * 1. Built-in defaults
+ * 2. .threadlinerc file (if exists) - merged with defaults
+ *
+ * Searches for .threadlinerc starting from startDir, walking up to git root.
+ * If no file found, returns defaults.
+ */
+async function loadConfig(startDir) {
+    // Start with defaults
+    const config = { ...exports.DEFAULT_CONFIG };
+    // Find git root to limit search scope
+    const gitRoot = await findGitRoot(startDir);
+    // Look for .threadlinerc starting from startDir, up to git root
+    let currentDir = startDir;
+    let configPath = null;
+    while (true) {
+        const candidatePath = path.join(currentDir, '.threadlinerc');
+        if (fs.existsSync(candidatePath)) {
+            configPath = candidatePath;
+            break;
+        }
+        // Stop at git root
+        if (path.resolve(currentDir) === path.resolve(gitRoot)) {
+            break;
+        }
+        // Move up one directory
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            // Reached filesystem root
+            break;
+        }
+        currentDir = parentDir;
+    }
+    // If config file found, parse and merge
+    if (configPath) {
+        try {
+            const configContent = fs.readFileSync(configPath, 'utf-8');
+            const fileConfig = JSON.parse(configContent);
+            // Merge file config into defaults (file overrides defaults)
+            Object.assign(config, fileConfig);
+        }
+        catch (error) {
+            // If file exists but can't be parsed, log warning but continue with defaults
+            console.warn(`Warning: Failed to parse .threadlinerc at ${configPath}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    return config;
+}

package/dist/utils/config.js

@@ -1,74 +1,115 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getThreadlineApiKey = getThreadlineApiKey;
 exports.getThreadlineAccount = getThreadlineAccount;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-const dotenv_1 = __importDefault(require("dotenv"));
-/**
- * Loads environment variables from .env.local file in the project root
- * (where the user runs the command, not the CLI package directory)
- */
-function loadEnvLocal() {
-    const projectRoot = process.cwd();
-    const envLocalPath = path.join(projectRoot, '.env.local');
-    if (fs.existsSync(envLocalPath)) {
-        dotenv_1.default.config({ path: envLocalPath });
-    }
-}
+exports.getOpenAIConfig = getOpenAIConfig;
+exports.logOpenAIConfig = logOpenAIConfig;
+exports.isDirectModeAvailable = isDirectModeAvailable;
+const chalk_1 = __importDefault(require("chalk"));
+const logger_1 = require("./logger");
+// Default values for OpenAI configuration
+const OPENAI_MODEL_DEFAULT = 'gpt-5.2';
+const OPENAI_SERVICE_TIER_DEFAULT = 'Flex';
 /**
  * Gets THREADLINE_API_KEY from environment.
- * Priority: process.env.THREADLINE_API_KEY → .env.local file
+ *
+ * Note: .env.local is automatically loaded at CLI startup (see index.ts).
+ * In CI/CD, environment variables are injected directly into process.env.
  */
 function getThreadlineApiKey() {
-    // Load .env.local if it exists (doesn't override existing env vars)
-    loadEnvLocal();
-    // Check environment variable (from shell or CI/CD)
-    return process.env.THREADLINE_API_KEY;
+    const apiKey = process.env.THREADLINE_API_KEY;
+    if (apiKey) {
+        logger_1.logger.debug('THREADLINE_API_KEY: found (value hidden for security)');
+    }
+    else {
+        logger_1.logger.debug('THREADLINE_API_KEY: not set');
+    }
+    return apiKey;
 }
 /**
  * Gets THREADLINE_ACCOUNT from environment.
- * Priority: process.env.THREADLINE_ACCOUNT → .env.local file
+ *
+ * Note: .env.local is automatically loaded at CLI startup (see index.ts).
+ * In CI/CD, environment variables are injected directly into process.env.
  */
 function getThreadlineAccount() {
-    // Load .env.local if it exists (doesn't override existing env vars)
-    loadEnvLocal();
-    // Check environment variable (from shell or CI/CD)
-    return process.env.THREADLINE_ACCOUNT;
+    const account = process.env.THREADLINE_ACCOUNT;
+    if (account) {
+        logger_1.logger.debug(`THREADLINE_ACCOUNT: ${account}`);
+    }
+    else {
+        logger_1.logger.debug('THREADLINE_ACCOUNT: not set');
+    }
+    return account;
+}
+/**
+ * Gets OpenAI configuration from environment variables.
+ *
+ * Required:
+ * - OPENAI_API_KEY: Your OpenAI API key
+ *
+ * Optional (with defaults):
+ * - OPENAI_MODEL: Model to use (default: gpt-5.2)
+ * - OPENAI_SERVICE_TIER: Service tier (default: Flex)
+ *
+ * Returns undefined if OPENAI_API_KEY is not set.
+ *
+ * Note: .env.local is automatically loaded at CLI startup (see index.ts).
+ * In CI/CD, environment variables are injected directly into process.env.
+ */
+function getOpenAIConfig() {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+        logger_1.logger.debug('OPENAI_API_KEY: not set (direct mode unavailable)');
+        return undefined;
+    }
+    logger_1.logger.debug('OPENAI_API_KEY: found (value hidden for security)');
+    const model = process.env.OPENAI_MODEL || OPENAI_MODEL_DEFAULT;
+    const serviceTier = process.env.OPENAI_SERVICE_TIER || OPENAI_SERVICE_TIER_DEFAULT;
+    if (process.env.OPENAI_MODEL) {
+        logger_1.logger.debug(`OPENAI_MODEL: ${model} (from environment)`);
+    }
+    else {
+        logger_1.logger.debug(`OPENAI_MODEL: ${model} (using default)`);
+    }
+    if (process.env.OPENAI_SERVICE_TIER) {
+        logger_1.logger.debug(`OPENAI_SERVICE_TIER: ${serviceTier} (from environment)`);
+    }
+    else {
+        logger_1.logger.debug(`OPENAI_SERVICE_TIER: ${serviceTier} (using default)`);
+    }
+    return {
+        apiKey,
+        model,
+        serviceTier
+    };
+}
+/**
+ * Logs the OpenAI configuration being used.
+ * Call this when starting direct LLM mode to inform the user.
+ */
+function logOpenAIConfig(config) {
+    console.log(chalk_1.default.blue('OpenAI Direct Mode:'));
+    console.log(chalk_1.default.gray(`  Model: ${config.model}${config.model === OPENAI_MODEL_DEFAULT ? ' (default)' : ''}`));
+    console.log(chalk_1.default.gray(`  Service Tier: ${config.serviceTier}${config.serviceTier === OPENAI_SERVICE_TIER_DEFAULT ? ' (default)' : ''}`));
+    console.log('');
+}
+/**
+ * Checks if direct OpenAI mode is available (OPENAI_API_KEY is set).
+ *
+ * Note: .env.local is automatically loaded at CLI startup (see index.ts).
+ * In CI/CD, environment variables are injected directly into process.env.
+ */
+function isDirectModeAvailable() {
+    const available = !!process.env.OPENAI_API_KEY;
+    if (available) {
+        logger_1.logger.debug('Direct OpenAI mode: available (OPENAI_API_KEY found)');
+    }
+    else {
+        logger_1.logger.debug('Direct OpenAI mode: unavailable (OPENAI_API_KEY not set)');
+    }
+    return available;
 }

package/dist/utils/logger.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+exports.enableDebug = enableDebug;
+exports.isDebugEnabled = isDebugEnabled;
+const chalk_1 = __importDefault(require("chalk"));
+/**
+ * Global debug flag - set when --debug is passed to CLI
+ */
+let debugEnabled = false;
+/**
+ * Enable debug logging (called when --debug flag is set)
+ */
+function enableDebug() {
+    debugEnabled = true;
+}
+/**
+ * Check if debug logging is enabled
+ */
+function isDebugEnabled() {
+    return debugEnabled;
+}
+/**
+ * Logger utility for CLI output
+ *
+ * - debug/info: Only shown when --debug flag is set
+ * - warn/error: Always shown (critical information)
+ */
+exports.logger = {
+    /**
+     * Debug-level log (technical details, internal state)
+     * Only shown with --debug flag
+     */
+    debug: (message) => {
+        if (debugEnabled) {
+            console.log(chalk_1.default.gray(`[DEBUG] ${message}`));
+        }
+    },
+    /**
+     * Info-level log (what's happening, progress updates)
+     * Only shown with --debug flag
+     */
+    info: (message) => {
+        if (debugEnabled) {
+            console.log(chalk_1.default.blue(`[INFO] ${message}`));
+        }
+    },
+    /**
+     * Warning (non-fatal issues, recommendations)
+     * Always shown
+     */
+    warn: (message) => {
+        console.log(chalk_1.default.yellow(`⚠️  ${message}`));
+    },
+    /**
+     * Error (failures, problems)
+     * Always shown
+     */
+    error: (message) => {
+        console.error(chalk_1.default.red(`❌ ${message}`));
+    }
+};

package/dist/validators/experts.js

@@ -38,6 +38,7 @@ exports.validateThreadline = validateThreadline;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const yaml = __importStar(require("js-yaml"));
+const logger_1 = require("../utils/logger");
 const REQUIRED_FIELDS = ['id', 'version', 'patterns'];
 /**
  * Find and validate all threadlines in the threadlines folder.
@@ -61,7 +62,7 @@ async function findThreadlines(searchRoot, gitRoot) {
             threadlines.push(result.threadline);
         }
         else {
-            console.warn(`⚠️  Skipping ${file}: ${result.errors?.join(', ')}`);
+            logger_1.logger.warn(`Skipping ${file}: ${result.errors?.join(', ')}`);
         }
     }
     return threadlines;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadlines",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Threadlines CLI - AI-powered linter based on your natural language documentation",
   "main": "dist/index.js",
   "bin": {