progga 1.0.2 → 1.0.5

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
+```bash
+npx progga@latest
+```
+
+This generates a file named:
 
-## ✨ Features
+```
+PROJECT_DOCUMENTATION.md
+```
 
-- 📁 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
+in the current directory.
 
-## 🚀 Installation
+### Run on a specific project
 
-### Using npx (Recommended - No Installation!)
 ```bash
-npx progga
+progga /path/to/project
 ```
 
-### Global Installation
+### Custom output file
+
 ```bash
-npm install -g progga
+progga . my-ai-context.md
 ```
 
-## 📖 Usage
+---
 
-### Basic Usage
+## How Progga Works (Short Example)
 
-Generate documentation for current directory:
-```bash
-npx progga
+Given a project like:
+
+```
+my-app/
+├── src/
+│   └── index.js
+├── package.json
+├── node_modules/
+└── build/
 ```
 
-This creates `PROJECT_DOCUMENTATION.md` in your current directory.
+Progga generates a single Markdown file containing:
 
-### Specify Project Path
-```bash
-npx progga /path/to/your/project
-```
+* A clean folder tree (excluding `node_modules`, `build`, etc.)
+* The contents of relevant source files
+* Proper code blocks with language hints
 
-### Custom Output File
-```bash
-npx progga . my-ai-context.md
-```
+Example output structure:
 
-### Full Example
-```bash
-npx progga ./my-app ./docs/ai-context.md
-```
+````markdown
+# Project Documentation: my-app
 
-## 💡 How to Use with AI Assistants
+## Folder Structure
+my-app/
+├── src/
+│   └── index.js
+├── package.json
 
-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!
+## File Contents
+### src/index.js
+```js
+// file content here
+````
 
-Example prompts after upload:
-- "Review my code architecture"
-- "Find potential bugs"
-- "Suggest improvements"
-- "Explain how this project works"
-- "Help me add a new feature"
+You can upload this file directly to an AI and ask questions about the project.
 
-## 🚫 What Gets Ignored
+## Project Presets
 
-Automatically excludes:
-- `node_modules/`, `.git/`
-- Build directories (`dist/`, `build/`, `.next/`)
-- Virtual environments (`venv/`, `env/`)
-- Cache directories
-- Lock files
-- Binary files (images, videos, fonts)
+Progga supports project-type presets that control what files are included.
 
-## 📊 Output Format
-```markdown
-# Project Documentation: your-project
+Currently supported:
+- `generic` (default)
+- `flutter` (Android, iOS, Web, Windows, macOS, Linux)
 
-## 📁 Folder Structure
-[Visual tree of all files and folders]
+If no preset is provided, Progga attempts to detect the project type and asks which preset to use.
 
-## 📄 File Contents
-[Complete contents of each file with syntax highlighting]
-```
+```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

@@ -7,65 +7,29 @@
 
 const fs = require('fs');
 const path = require('path');
-
-// Configure what to ignore
-const IGNORE_PATTERNS = new Set([
-  'node_modules',
-  '.git',
-  '__pycache__',
-  '.vscode',
-  'dist',
-  'build',
-  '.next',
-  'venv',
-  'env',
-  '.env',
-  'coverage',
-  '.pytest_cache',
-  '.DS_Store',
-  'package-lock.json',
-  'yarn.lock',
-  'pnpm-lock.yaml',
-]);
-
-// File extensions to exclude
-const IGNORE_EXTENSIONS = new Set([
-  '.pyc',
-  '.pyo',
-  '.so',
-  '.dylib',
-  '.exe',
-  '.dll',
-]);
-
-// Binary file extensions to skip
-const BINARY_EXTENSIONS = new Set([
-  '.png', '.jpg', '.jpeg', '.gif', '.ico', '.svg',
-  '.pdf', '.zip', '.tar', '.gz', '.rar',
-  '.mp4', '.mp3', '.wav',
-  '.woff', '.woff2', '.ttf', '.eot',
-]);
+const ProfileRegistry = require('./profiles/ProfileRegistry');
+const ProjectTypeDetector = require('./core/ProjectTypeDetector');
+const PresetSelector = require('./core/PresetSelector');
+const Spinner = require('./core/Spinner');
 
 /**
  * Check if path should be ignored
  */
-function shouldIgnore(filePath, basePath) {
+function shouldIgnore(filePath, basePath, profile) {
   const relativePath = path.relative(basePath, filePath);
   const parts = relativePath.split(path.sep);
-  
-  // Check each part of the path
+
   for (const part of parts) {
-    if (IGNORE_PATTERNS.has(part)) {
+    if (profile.ignorePaths().includes(part)) {
       return true;
     }
   }
-  
-  // Check file extension
+
   const ext = path.extname(filePath);
-  if (IGNORE_EXTENSIONS.has(ext)) {
+  if (profile.ignoreExtensions().includes(ext)) {
     return true;
   }
-  
+
   return false;
 }
 
@@ -88,43 +52,43 @@ function isDirectoryEmpty(directory, basePath) {
 /**
  * Generate tree structure recursively
  */
-function generateTree(directory, prefix = '', isLast = true, basePath = null) {
+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));
-    
+    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);
+          const subtree = generateTree(item.fullPath, prefix + extension, isLastItem, basePath, profile);
           treeLines.push(...subtree);
         }
       } else {
@@ -140,35 +104,32 @@ function generateTree(directory, prefix = '', isLast = true, basePath = null) {
   } catch (err) {
     // Permission error or other issues
   }
-  
+
   return treeLines;
 }
 
 /**
  * Check if file is binary
  */
-function isBinaryFile(filePath) {
+function isBinaryFile(filePath, profile) {
   const ext = path.extname(filePath);
-  if (BINARY_EXTENSIONS.has(ext)) {
+  if (profile.binaryExtensions().includes(ext)) {
     return true;
   }
-  
+
   try {
     const buffer = Buffer.alloc(1024);
     const fd = fs.openSync(filePath, 'r');
     const bytesRead = fs.readSync(fd, buffer, 0, 1024, 0);
     fs.closeSync(fd);
-    
-    // Check for null bytes
+
     for (let i = 0; i < bytesRead; i++) {
-      if (buffer[i] === 0) {
-        return true;
-      }
+      if (buffer[i] === 0) return true;
     }
-  } catch (err) {
+  } catch {
     return true;
   }
-  
+
   return false;
 }
 
@@ -181,7 +142,7 @@ function readFileContent(filePath) {
     if (stats.size === 0) {
       return '(empty file)';
     }
-    
+
     return fs.readFileSync(filePath, 'utf-8');
   } catch (err) {
     if (err.message.includes('invalid')) {
@@ -223,7 +184,7 @@ function getLanguageFromExtension(filePath) {
     '.rb': 'ruby',
     '.php': 'php',
   };
-  
+
   const ext = path.extname(filePath);
   return extMap[ext] || '';
 }
@@ -231,50 +192,46 @@ function getLanguageFromExtension(filePath) {
 /**
  * Collect all files recursively
  */
-function collectFiles(directory, basePath) {
+function collectFiles(directory, basePath, profile) {
   const files = [];
-  
+
   try {
     const items = fs.readdirSync(directory);
-    
+
     for (const item of items.sort()) {
       const fullPath = path.join(directory, item);
-      
-      if (shouldIgnore(fullPath, basePath)) {
-        continue;
-      }
-      
+
+      if (shouldIgnore(fullPath, basePath, profile)) continue;
+
       const stats = fs.statSync(fullPath);
-      
+
       if (stats.isFile()) {
-        if (!isBinaryFile(fullPath)) {
+        if (!isBinaryFile(fullPath, profile)) {
           files.push(fullPath);
         }
       } else if (stats.isDirectory()) {
-        files.push(...collectFiles(fullPath, basePath));
+        files.push(...collectFiles(fullPath, basePath, profile));
       }
     }
-  } catch (err) {
-    // Permission error or other issues
-  }
-  
+  } catch { }
+
   return files;
 }
 
 /**
  * Generate complete documentation markdown file
  */
-function generateDocumentation(projectPath, outputFile) {
+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 {
@@ -284,43 +241,48 @@ function generateDocumentation(projectPath, outputFile) {
       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 treeLines = generateTree(absProjectPath, '', true, absProjectPath);
+
+  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 files = collectFiles(absProjectPath, absProjectPath);
-  
+
+  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')) {
@@ -329,22 +291,59 @@ function generateDocumentation(projectPath, outputFile) {
     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() {
   const args = process.argv.slice(2);
-  
-  const projectPath = args[0] || '.';
-  const outputFile = args[1] || 'PROJECT_DOCUMENTATION.md';
-  
-  generateDocumentation(projectPath, outputFile);
+
+  let projectPath = '.';
+  let outputFile = 'PROJECT_DOCUMENTATION.md';
+  let projectType = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--project-type' || arg === '--preset') {
+      projectType = args[i + 1];
+      i++;
+    } else if (!projectPath) {
+      projectPath = arg;
+    } else if (!outputFile) {
+      outputFile = arg;
+    }
+  }
+
+  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');
+
+    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);
+  }
+
+  console.log(`Using profile: ${profile.name}`);
+  generateDocumentation(projectPath, outputFile, profile);
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "progga",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "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/GenericProfile.js

@@ -0,0 +1,52 @@
+const ProjectProfile = require('./ProjectProfile');
+
+class GenericProfile extends ProjectProfile {
+  get name() {
+    return 'generic';
+  }
+
+  ignorePaths() {
+    return [
+      'node_modules',
+      '.git',
+      '__pycache__',
+      '.vscode',
+      'dist',
+      'build',
+      '.next',
+      'venv',
+      'env',
+      '.env',
+      'coverage',
+      '.pytest_cache',
+      '.DS_Store',
+      'package-lock.json',
+      'yarn.lock',
+      'pnpm-lock.yaml',
+      'bun.lock',
+      '.turbo'
+    ];
+  }
+
+  ignoreExtensions() {
+    return [
+      '.pyc',
+      '.pyo',
+      '.so',
+      '.dylib',
+      '.exe',
+      '.dll',
+    ];
+  }
+
+  binaryExtensions() {
+    return [
+      '.png', '.jpg', '.jpeg', '.gif', '.ico', '.svg',
+      '.pdf', '.zip', '.tar', '.gz', '.rar',
+      '.mp4', '.mp3', '.wav',
+      '.woff', '.woff2', '.ttf', '.eot',
+    ];
+  }
+}
+
+module.exports = GenericProfile;

package/profiles/ProfileRegistry.js

@@ -0,0 +1,24 @@
+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);
+    }
+
+    return null;
+  }
+
+  static fallback(projectRoot) {
+    return new GenericProfile(projectRoot);
+  }
+}
+
+module.exports = ProfileRegistry;

package/profiles/ProjectProfile.js

@@ -0,0 +1,31 @@
+class ProjectProfile {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+  }
+
+  get name() {
+    return 'base';
+  }
+
+  /** Paths to fully ignore */
+  ignorePaths() {
+    return [];
+  }
+
+  /** Extensions to ignore */
+  ignoreExtensions() {
+    return [];
+  }
+
+  /** Binary extensions */
+  binaryExtensions() {
+    return [];
+  }
+
+  /** Should this profile auto-detect the project */
+  detect() {
+    return false;
+  }
+}
+
+module.exports = ProjectProfile;