threadlines 0.1.7 → 0.1.9

package/README.md

@@ -24,16 +24,43 @@ Getting teams to follow consistent quality standards is **hard**. Really hard.
 
 ## Installation
 
+### Option 1: Global Installation (Recommended for Regular Use)
+
 ```bash
 npm install -g threadlines
 ```
 
-Or use with npx:
+Then use directly:
+```bash
+threadlines check
+```
+
+### Option 2: Use with npx (No Installation)
+
+```bash
+npx threadlines check
+```
+
+**For non-interactive environments** (CI/CD, AI assistants like Cursor):
+```bash
+npx --yes threadlines check
+```
+
+The `--yes` flag auto-confirms package installation, preventing prompts that block automation.
+
+### Option 3: Local Project Dependency (Recommended for Teams)
+
+```bash
+npm install --save-dev threadlines
+```
 
+Then use:
 ```bash
 npx threadlines check
 ```
 
+This ensures everyone on your team uses the same version.
+
 ## Quick Start
 
 ### 1. Initialize Your First Threadline
@@ -88,10 +115,50 @@ Creates a template threadline file to get you started. The command will:
 threadlines check
 ```
 
-Analyzes your git changes against all threadlines in the `/threadlines` directory.
+By default, analyzes your staged/unstaged git changes against all threadlines in the `/threadlines` directory.
+
+**Common Use Cases:**
+
+**Check latest commit locally:**
+```bash
+threadlines check --commit HEAD
+```
+
+**Check a specific commit:**
+```bash
+threadlines check --commit abc123def
+```
+
+**Check all commits in a branch:**
+```bash
+threadlines check --branch feature/new-feature
+```
+
+**Check entire file(s):**
+```bash
+threadlines check --file src/api/users.ts
+threadlines check --files src/api/users.ts src/api/posts.ts
+threadlines check --folder src/api
+```
+
+**Show all results (not just violations):**
+```bash
+threadlines check --full
+```
 
 **Options:**
 - `--api-url <url>` - Override the server URL (default: http://localhost:3000)
+- `--commit <ref>` - Review specific commit. Accepts commit SHA or git reference (e.g., `HEAD`, `HEAD~1`, `abc123`)
+- `--branch <name>` - Review all commits in branch vs base
+- `--file <path>` - Review entire file (all lines as additions)
+- `--folder <path>` - Review all files in folder recursively
+- `--files <paths...>` - Review multiple specified files
+- `--full` - Show all results (compliant, attention, not_relevant). Default: only attention items
+
+**Auto-detection in CI:**
+- CI with branch detected → reviews all commits in branch vs base
+- CI with commit SHA detected → reviews specific commit
+- Local development → reviews staged/unstaged changes
 
 ## Configuration
 

package/dist/commands/check.js

@@ -195,8 +195,11 @@ async function checkCommand(options) {
         // 4. Get repo name and branch name
         const repoName = await (0, repo_1.getRepoName)(repoRoot);
         const branchName = await (0, repo_1.getBranchName)(repoRoot);
-        // 5. Get API URL
-        const apiUrl = options.apiUrl || process.env.THREADLINE_API_URL || 'http://localhost:3000';
+        // 5. Get API URL (auto-detect Vercel if available)
+        const apiUrl = options.apiUrl ||
+            process.env.THREADLINE_API_URL ||
+            (process.env.VERCEL_URL ? `https://${process.env.VERCEL_URL}` : null) ||
+            'http://localhost:3000';
         // 6. Call review API
         console.log(chalk_1.default.gray('🤖 Running threadline checks...'));
         const client = new client_1.ReviewAPIClient(apiUrl);

package/dist/commands/init.js

@@ -105,6 +105,7 @@ async function initCommand() {
         console.log(chalk_1.default.white('   Make sure .env.local is in your .gitignore file!'));
         console.log('');
         console.log(chalk_1.default.gray('  3. Run: npx threadlines check'));
+        console.log(chalk_1.default.gray('     (Use npx --yes threadlines check in non-interactive environments)'));
     }
     catch (error) {
         console.error(chalk_1.default.red(`\n❌ Error: ${error.message}`));

package/dist/git/diff.js

@@ -63,6 +63,33 @@ async function getBranchDiff(repoRoot, branchName, baseBranch) {
         base = baseBranch;
     }
     else {
+        // Check if the branch itself is a base branch (main/master)
+        const baseBranchNames = ['main', 'master'];
+        const isBaseBranch = baseBranchNames.includes(branchName.toLowerCase());
+        if (isBaseBranch) {
+            // For main/master branch, compare against previous commit (HEAD~1)
+            // This checks what changed in the most recent commit
+            try {
+                const previousCommit = await git.revparse(['HEAD~1']).catch(() => null);
+                if (previousCommit) {
+                    // Use commit-based diff instead
+                    const diff = await git.diff([`${previousCommit}..HEAD`]);
+                    const diffSummary = await git.diffSummary([`${previousCommit}..HEAD`]);
+                    const changedFiles = diffSummary.files.map(f => f.file);
+                    return {
+                        diff: diff || '',
+                        changedFiles
+                    };
+                }
+            }
+            catch {
+                // If no previous commit, return empty (first commit)
+                return {
+                    diff: '',
+                    changedFiles: []
+                };
+            }
+        }
         // Try to detect base branch: upstream, default branch, or common names
         base = await detectBaseBranch(git, branchName);
     }
@@ -72,27 +99,39 @@ async function getBranchDiff(repoRoot, branchName, baseBranch) {
         const upstream = await git.revparse(['--abbrev-ref', '--symbolic-full-name', `${branchName}@{u}`]).catch(() => null);
         if (upstream) {
             // Extract base from upstream (e.g., "origin/main" -> "main")
-            return upstream.replace(/^origin\//, '');
+            const upstreamBranch = upstream.replace(/^origin\//, '');
+            // Don't use the branch itself as its base
+            if (upstreamBranch !== branchName) {
+                return upstreamBranch;
+            }
         }
         // Try default branch
         try {
             const defaultBranch = await git.revparse(['--abbrev-ref', 'refs/remotes/origin/HEAD']);
-            return defaultBranch.replace(/^origin\//, '');
+            const defaultBranchName = defaultBranch.replace(/^origin\//, '');
+            // Don't use the branch itself as its base
+            if (defaultBranchName !== branchName) {
+                return defaultBranchName;
+            }
         }
         catch {
-            // Fallback to common names
-            const commonBases = ['main', 'master', 'develop'];
-            for (const candidate of commonBases) {
-                try {
-                    await git.revparse([`origin/${candidate}`]);
-                    return candidate;
-                }
-                catch {
-                    // Try next
-                }
+            // Continue to fallback
+        }
+        // Fallback to common names (excluding the branch itself)
+        const commonBases = ['main', 'master', 'develop'];
+        for (const candidate of commonBases) {
+            if (candidate.toLowerCase() === branchName.toLowerCase()) {
+                continue; // Skip if it's the same branch
+            }
+            try {
+                await git.revparse([`origin/${candidate}`]);
+                return candidate;
+            }
+            catch {
+                // Try next
             }
-            throw new Error(`Could not determine base branch. Please specify with --base flag or set upstream tracking.`);
         }
+        throw new Error(`Could not determine base branch for '${branchName}'. Please specify with --base flag or set upstream tracking.`);
     }
     // Get diff between base and branch (cumulative diff of all commits)
     // Format: git diff base...branch (three-dot notation finds common ancestor)

package/dist/index.js

@@ -61,12 +61,25 @@ program
 program
     .command('check')
     .description('Check code against your threadlines')
-    .option('--api-url <url>', 'Threadline server URL', process.env.THREADLINE_API_URL || 'http://localhost:3000')
+    .option('--api-url <url>', 'Threadline server URL', process.env.THREADLINE_API_URL || (process.env.VERCEL_URL ? `https://${process.env.VERCEL_URL}` : 'http://localhost:3000'))
     .option('--full', 'Show all results (compliant, attention, not_relevant). Default: only attention items')
-    .option('--branch <name>', 'Review all commits in branch vs base')
-    .option('--commit <sha>', 'Review specific commit')
+    .option('--branch <name>', 'Review all commits in branch vs base (e.g., --branch feature/new-feature)')
+    .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')
+    .addHelpText('after', `
+Examples:
+  $ threadlines check                    # Check staged/unstaged changes (local dev)
+  $ threadlines check --commit HEAD      # Check latest commit locally
+  $ threadlines check --branch main      # Check all commits in branch vs base
+  $ threadlines check --file src/api.ts  # Check entire file
+  $ threadlines check --full             # Show all results (not just attention items)
+
+Auto-detection in CI:
+  - CI with branch detected → reviews all commits in branch vs base
+  - CI with commit SHA detected → reviews specific commit
+  - Local development → reviews staged/unstaged changes
+`)
     .action(check_1.checkCommand);
 program.parse();

package/package.json

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