progga 1.0.4 → 1.0.6

package/README.md

@@ -1,110 +1,124 @@
 # progga (প্রজ্ঞা)
 
-> *Progga* means "wisdom" or "insight" in Bengali
+**Progga** is a CLI tool that generates a single Markdown file representing the essential context of a software project.
+The output is optimized for uploading to AI assistants (ChatGPT, Claude, Gemini) so they can understand a project quickly and accurately.
 
-Generate comprehensive project documentation in a single markdown file - perfect for sharing your entire codebase context with AI assistants like ChatGPT, Claude, or Gemini.
+---
 
-## 🎯 Purpose
+## Getting Started
 
-Upload one file, understand the entire project. **progga** creates a complete project snapshot that AI assistants can instantly comprehend, making it easy to:
+### Run with npx (recommended)
 
-- 💬 Get AI help with your entire codebase
-- 📤 Share project context without multiple file uploads
-- 🤖 Enable ChatGPT/Claude/Gemini to understand your project structure
-- 📚 Create comprehensive documentation snapshots
-
-## ✨ Features
-
-- 📁 Visual folder tree structure
-- 📄 All file contents with syntax highlighting
-- 🚫 Automatically ignores dependencies and build artifacts
-- ⚡ One command, one file, complete context
-- 🎯 Optimized for AI consumption
-
-## 🚀 Installation
-
-### Using npx (Recommended - No Installation!)
 ```bash
 npx progga@latest
 ```
 
-### Global Installation
-```bash
-npm install -g progga
+This generates a file named:
+
+```
+PROJECT_DOCUMENTATION.md
 ```
 
-## 📖 Usage
+in the current directory.
 
-### Basic Usage
+### Run on a specific project
 
-Generate documentation for current directory:
 ```bash
-npx progga@latest
+progga /path/to/project
 ```
 
-This creates `PROJECT_DOCUMENTATION.md` in your current directory.
+### Custom output file
 
-### Specify Project Path
 ```bash
-npx progga@latest /path/to/your/project
+progga . my-ai-context.md
 ```
 
-### Custom Output File
-```bash
-npx progga@latest . my-ai-context.md
-```
+---
 
-### Full Example
-```bash
-npx progga@latest ./my-app ./docs/ai-context.md
+## How Progga Works (Short Example)
+
+Given a project like:
+
+```
+my-app/
+├── src/
+│   └── index.js
+├── package.json
+├── node_modules/
+└── build/
 ```
 
-## 💡 How to Use with AI Assistants
+Progga generates a single Markdown file containing:
 
-1. Run `npx progga` in your project directory
-2. Upload the generated `PROJECT_DOCUMENTATION.md` to ChatGPT, Claude, or Gemini
-3. Ask the AI anything about your project!
+* A clean folder tree (excluding `node_modules`, `build`, etc.)
+* The contents of relevant source files
+* Proper code blocks with language hints
 
-Example prompts after upload:
-- "Review my code architecture"
-- "Find potential bugs"
-- "Suggest improvements"
-- "Explain how this project works"
-- "Help me add a new feature"
+Example output structure:
 
-## 🚫 What Gets Ignored
+````markdown
+# Project Documentation: my-app
 
-Automatically excludes:
-- `node_modules/`, `.git/`
-- Build directories (`dist/`, `build/`, `.next/`)
-- Virtual environments (`venv/`, `env/`)
-- Cache directories
-- Lock files
-- Binary files (images, videos, fonts)
+## Folder Structure
+my-app/
+├── src/
+│   └── index.js
+├── package.json
 
-## 📊 Output Format
-```markdown
-# Project Documentation: your-project
+## File Contents
+### src/index.js
+```js
+// file content here
+````
 
-## 📁 Folder Structure
-[Visual tree of all files and folders]
+You can upload this file directly to an AI and ask questions about the project.
 
-## 📄 File Contents
-[Complete contents of each file with syntax highlighting]
-```
+## Project Presets
+
+Progga supports project-type presets that control what files are included.
+
+Currently supported:
+- `generic` (default)
+- `flutter` (Android, iOS, Web, Windows, macOS, Linux)
+
+If no preset is provided, Progga attempts to detect the project type and asks which preset to use.
+
+```bash
+progga --preset flutter
+````
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+Good areas to contribute:
+
+* New project presets (Node.js, Python, Go, etc.)
+* Improving Flutter include-only rules
+* Performance improvements
+* Better project auto-detection
+* Documentation and examples
+
+### How to contribute
+
+1. Fork the repository
+2. Create a feature branch
+3. Make focused changes
+4. Open a pull request with a clear description
 
-## 🌍 Requirements
+Opening an issue to discuss ideas is also encouraged.
 
-- Node.js >= 12.0.0
+---
 
-## 📝 License
+## Requirements
 
-MIT
+* Node.js 12 or newer (Node 18+ recommended)
 
-## 🤝 Contributing
+---
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+## License
 
-## 💖 Name Origin
+MIT License
 
-**Progga** (প্রজ্ঞা) is a Bengali word meaning "wisdom" or "insight" - representing the wisdom you share with AI assistants about your codebase.

package/core/PresetSelector.js

@@ -0,0 +1,23 @@
+const select = require('@inquirer/select').default;
+
+class PresetSelector {
+  static async choose(detectedType) {
+    const preset = await select({
+      message: 'Select how you want to proceed:',
+      choices: [
+        {
+          name: `Use ${detectedType} preset (recommended)`,
+          value: detectedType
+        },
+        {
+          name: 'Use generic preset',
+          value: 'generic'
+        }
+      ]
+    });
+
+    return preset;
+  }
+}
+
+module.exports = PresetSelector;

package/core/ProjectTypeDetector.js

@@ -0,0 +1,34 @@
+const fs = require('fs');
+const path = require('path');
+
+class ProjectTypeDetector {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+  }
+
+  detect() {
+    const signals = [];
+
+    if (this.isFlutterProject()) {
+      signals.push({
+        type: 'flutter',
+        confidence: 'high',
+        reason: 'pubspec.yaml found'
+      });
+    }
+
+    // future:
+    // if (this.isNodeProject()) ...
+    // if (this.isPythonProject()) ...
+
+    return signals;
+  }
+
+  isFlutterProject() {
+    return fs.existsSync(
+      path.join(this.projectRoot, 'pubspec.yaml')
+    );
+  }
+}
+
+module.exports = ProjectTypeDetector;

package/core/Spinner.js

@@ -0,0 +1,32 @@
+const ora = require('ora').default;
+
+class Spinner {
+  constructor(text) {
+    this.enabled = process.stdout.isTTY;
+    this.spinner = this.enabled ? ora(text).start() : null;
+  }
+
+  succeed(text) {
+    if (this.spinner) {
+      this.spinner.succeed(text);
+    } else {
+      console.log(`✓ ${text}`);
+    }
+  }
+
+  fail(text) {
+    if (this.spinner) {
+      this.spinner.fail(text);
+    } else {
+      console.error(`✗ ${text}`);
+    }
+  }
+
+  update(text) {
+    if (this.spinner) {
+      this.spinner.text = text;
+    }
+  }
+}
+
+module.exports = Spinner;

package/index.js

@@ -8,8 +8,14 @@
 const fs = require('fs');
 const path = require('path');
 const ProfileRegistry = require('./profiles/ProfileRegistry');
+const ProjectTypeDetector = require('./core/ProjectTypeDetector');
+const PresetSelector = require('./core/PresetSelector');
+const Spinner = require('./core/Spinner');
 
 
+const CLI_IGNORE_PATHS = new Set();
+const CLI_IGNORE_EXTENSIONS = new Set();
+
 /**
  * Check if path should be ignored
  */
@@ -18,13 +24,19 @@ function shouldIgnore(filePath, basePath, profile) {
   const parts = relativePath.split(path.sep);
 
   for (const part of parts) {
-    if (profile.ignorePaths().includes(part)) {
+    if (
+      profile.ignorePaths().includes(part) ||
+      CLI_IGNORE_PATHS.has(part)
+    ) {
       return true;
     }
   }
 
   const ext = path.extname(filePath);
-  if (profile.ignoreExtensions().includes(ext)) {
+  if (
+    profile.ignoreExtensions().includes(ext) ||
+    CLI_IGNORE_EXTENSIONS.has(ext)
+  ) {
     return true;
   }
 
@@ -50,43 +62,43 @@ function isDirectoryEmpty(directory, basePath) {
 /**
  * Generate tree structure recursively
  */
-function generateTree( directory, prefix = '', isLast = true, basePath = null, profile ) {
+function generateTree(directory, prefix = '', isLast = true, basePath = null, profile) {
   if (basePath === null) {
     basePath = directory;
   }
-  
+
   const treeLines = [];
-  
+
   try {
     let items = fs.readdirSync(directory).map(name => {
       const fullPath = path.join(directory, name);
       const stats = fs.statSync(fullPath);
       return { name, fullPath, isDir: stats.isDirectory() };
     });
-    
+
     // Filter ignored items
     items = items.filter(item => !shouldIgnore(item.fullPath, basePath, profile));
-    
+
     // Sort: directories first, then alphabetically
     items.sort((a, b) => {
       if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
       return a.name.toLowerCase().localeCompare(b.name.toLowerCase());
     });
-    
+
     for (let i = 0; i < items.length; i++) {
       const item = items[i];
       const isLastItem = i === items.length - 1;
-      
+
       // Tree characters
       const connector = isLastItem ? '└── ' : '├── ';
       const extension = isLastItem ? '    ' : '│   ';
-      
+
       if (item.isDir) {
         if (isDirectoryEmpty(item.fullPath, basePath)) {
           treeLines.push(`${prefix}${connector}${item.name}/ (empty)`);
         } else {
           treeLines.push(`${prefix}${connector}${item.name}/`);
-          const subtree = generateTree( item.fullPath, prefix + extension, isLastItem, basePath, profile );
+          const subtree = generateTree(item.fullPath, prefix + extension, isLastItem, basePath, profile);
           treeLines.push(...subtree);
         }
       } else {
@@ -102,7 +114,7 @@ function generateTree( directory, prefix = '', isLast = true, basePath = null, p
   } catch (err) {
     // Permission error or other issues
   }
-  
+
   return treeLines;
 }
 
@@ -140,7 +152,7 @@ function readFileContent(filePath) {
     if (stats.size === 0) {
       return '(empty file)';
     }
-    
+
     return fs.readFileSync(filePath, 'utf-8');
   } catch (err) {
     if (err.message.includes('invalid')) {
@@ -182,7 +194,7 @@ function getLanguageFromExtension(filePath) {
     '.rb': 'ruby',
     '.php': 'php',
   };
-  
+
   const ext = path.extname(filePath);
   return extMap[ext] || '';
 }
@@ -211,7 +223,7 @@ function collectFiles(directory, basePath, profile) {
         files.push(...collectFiles(fullPath, basePath, profile));
       }
     }
-  } catch {}
+  } catch { }
 
   return files;
 }
@@ -221,15 +233,15 @@ function collectFiles(directory, basePath, profile) {
  */
 function generateDocumentation(projectPath, outputFile, profile) {
   const absProjectPath = path.resolve(projectPath);
-  
+
   if (!fs.existsSync(absProjectPath)) {
     console.error(`Error: Path '${absProjectPath}' does not exist`);
     process.exit(1);
   }
-  
+
   console.log(`Generating documentation for: ${absProjectPath}`);
   console.log(`Output file: ${outputFile}`);
-  
+
   // Delete existing output file if it exists
   if (fs.existsSync(outputFile)) {
     try {
@@ -239,43 +251,48 @@ function generateDocumentation(projectPath, outputFile, profile) {
       console.warn(`Warning: Could not delete existing file: ${err.message}`);
     }
   }
-  
+
   const projectName = path.basename(absProjectPath);
   let output = '';
-  
+
   // Write header
   output += `# Project Documentation: ${projectName}\n\n`;
   output += `**Generated from:** \`${absProjectPath}\`\n\n`;
   output += '---\n\n';
-  
+
   // Write folder structure
   output += '## 📁 Folder Structure\n\n';
   output += '```\n';
   output += `${projectName}/\n`;
-  
+
+  const treeSpinner = new Spinner('Generating folder structure');
   const treeLines = generateTree(absProjectPath, '', true, absProjectPath, profile);
+  treeSpinner.succeed('Folder structure generated');
+
   for (const line of treeLines) {
     output += `${line}\n`;
   }
-  
+
   output += '```\n\n';
   output += '---\n\n';
-  
+
   // Write file contents
   output += '## 📄 File Contents\n\n';
-  
+
+  const fileSpinner = new Spinner('Collecting files');
   const files = collectFiles(absProjectPath, absProjectPath, profile);
-  
+  fileSpinner.succeed(`Collected ${files.length} files`);
+
   for (let i = 0; i < files.length; i++) {
     const filePath = files[i];
     const relPath = path.relative(absProjectPath, filePath);
     console.log(`Processing (${i + 1}/${files.length}): ${relPath}`);
-    
+
     output += `### \`${relPath}\`\n\n`;
-    
+
     const content = readFileContent(filePath);
     const language = getLanguageFromExtension(filePath);
-    
+
     output += `\`\`\`${language}\n`;
     output += content;
     if (!content.endsWith('\n')) {
@@ -284,27 +301,75 @@ function generateDocumentation(projectPath, outputFile, profile) {
     output += '```\n\n';
     output += '---\n\n';
   }
-  
+
   // Write to file
   fs.writeFileSync(outputFile, output, 'utf-8');
-  
+
   console.log(`\n✅ Documentation generated successfully: ${outputFile}`);
   console.log(`📊 Total files processed: ${files.length}`);
 }
 
 // Main execution
-function main() {
+async function main() {
+  let cliIgnores = [];
   const args = process.argv.slice(2);
 
-  const projectPath = args[0] || '.';
-  const outputFile = args[1] || 'PROJECT_DOCUMENTATION.md';
+  let projectPath = '.';
+  let outputFile = 'PROJECT_DOCUMENTATION.md';
+  let projectType = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--ignore' || arg === '-i') {
+      const value = args[i + 1];
+      if (value) {
+        value
+          .split(',')
+          .map(v => v.trim())
+          .filter(Boolean)
+          .forEach(item => {
+            if (item.startsWith('.')) {
+              CLI_IGNORE_EXTENSIONS.add(item);
+            } else {
+              CLI_IGNORE_PATHS.add(item);
+            }
+          });
+        i++;
+      }
+    }
+  }
+
+  let profile = ProfileRegistry.getByName(projectType, projectPath);
+
+  if (!profile) {
+    const detector = new ProjectTypeDetector(projectPath);
+    const detections = detector.detect();
+
+    const flutterSignal = detections.find(d => d.type === 'flutter');
 
-  // future: parse --project-type
-  const profile =
-    ProfileRegistry.getByName(null, projectPath) ||
-    ProfileRegistry.fallback(projectPath);
+    if (flutterSignal && process.stdin.isTTY) {
+      console.log('');
+      console.log(`Detected project type: ${flutterSignal.type}`);
+      console.log('');
+
+      const selectedPreset = await PresetSelector.choose(flutterSignal.type);
+      profile = ProfileRegistry.getByName(selectedPreset, projectPath);
+    }
+  }
 
+  if (!profile) {
+    profile = ProfileRegistry.fallback(projectPath);
+  }
+
+  if (cliIgnores.length) {
+    profile.applyCliIgnores(cliIgnores);
+    console.log(`🚫 CLI ignores applied: ${cliIgnores.join(', ')}`);
+  }
+
+  console.log(`Using profile: ${profile.name}`);
   generateDocumentation(projectPath, outputFile, profile);
+
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "progga",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Generate comprehensive project documentation for AI assistants - Share your entire codebase context in one markdown file",
   "main": "index.js",
   "bin": {
@@ -37,5 +37,10 @@
   "bugs": {
     "url": "https://github.com/Yousuf-Basir/progga/issues"
   },
-  "homepage": "https://github.com/Yousuf-Basir/progga#readme"
+  "homepage": "https://github.com/Yousuf-Basir/progga#readme",
+  "dependencies": {
+    "@inquirer/select": "^5.0.4",
+    "inquirer": "^13.2.0",
+    "ora": "^9.0.0"
+  }
 }

package/profiles/FlutterProfile.js

@@ -0,0 +1,65 @@
+const ProjectProfile = require('./ProjectProfile');
+
+class FlutterProfile extends ProjectProfile {
+  get name() {
+    return 'flutter';
+  }
+
+  ignorePaths() {
+    return [
+      // Dart / Flutter
+      '.dart_tool',
+      'build',
+      '.flutter-plugins',
+      '.flutter-plugins-dependencies',
+
+      // Android
+      'android/.gradle',
+      'android/build',
+      'android/app/build',
+
+      // iOS / macOS
+      'ios/Flutter/ephemeral',
+      'ios/Runner.xcodeproj',
+      'ios/Runner.xcworkspace',
+      'macos/Flutter/ephemeral',
+      'macos/Runner.xcodeproj',
+
+      // Web
+      'build/web',
+
+      // Windows
+      'windows/build',
+
+      // Linux
+      'linux/build',
+
+      // Common IDE noise
+      '.git',
+      '.idea',
+      '.vscode',
+      '.DS_Store',
+    ];
+  }
+
+  ignoreExtensions() {
+    return [
+      // Assets & binaries
+      '.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico',
+      '.mp4', '.mp3', '.wav',
+      '.ttf', '.otf', '.woff', '.woff2',
+
+      // Archives
+      '.zip', '.rar', '.tar', '.gz',
+
+      // Compiled outputs
+      '.exe', '.dll', '.so', '.dylib',
+    ];
+  }
+
+  binaryExtensions() {
+    return this.ignoreExtensions();
+  }
+}
+
+module.exports = FlutterProfile;

package/profiles/ProfileRegistry.js

@@ -1,9 +1,14 @@
 const GenericProfile = require('./GenericProfile');
+const FlutterProfile = require('./FlutterProfile');
 
 class ProfileRegistry {
   static getByName(name, projectRoot) {
     if (!name) return null;
 
+    if (name === 'flutter') {
+      return new FlutterProfile(projectRoot);
+    }
+
     if (name === 'generic') {
       return new GenericProfile(projectRoot);
     }

package/profiles/ProjectProfile.js

@@ -1,6 +1,18 @@
 class ProjectProfile {
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
+    this.cliIgnorePaths = [];
+    this.cliIgnoreExtensions = [];
+  }
+
+  applyCliIgnores(list) {
+    for (const item of list) {
+      if (item.startsWith('.')) {
+        this.cliIgnoreExtensions.push(item);
+      } else {
+        this.cliIgnorePaths.push(item);
+      }
+    }
   }
 
   get name() {
@@ -9,12 +21,12 @@ class ProjectProfile {
 
   /** Paths to fully ignore */
   ignorePaths() {
-    return [];
+    return this.cliIgnorePaths;
   }
 
   /** Extensions to ignore */
   ignoreExtensions() {
-    return [];
+    return this.cliIgnoreExtensions;
   }
 
   /** Binary extensions */