@parseme/cli 0.0.6 → 0.1.1

package/README.md

@@ -1,16 +1,43 @@
 # PARSEME
 
-AI Project Context Generator - Automated context generation for AI coding assistants.
+**Local code analysis and context generation to improve token efficiency of AI Coding agents
+Cross-project access via Cloud MCP**
 
 PARSEME analyzes your TypeScript/JavaScript projects and generates a PARSEME.md file—a README.md for AI agents. This file provides comprehensive context documentation that helps AI assistants understand your codebase structure, architecture, and patterns. By providing persistent, reusable context, PARSEME prevents AI agents from repeatedly analyzing your codebase from scratch—saving valuable tokens and improving efficiency for every interaction.
 
+## Table of Contents
+
+- [Development Status](#development-status)
+- [Features](#features)
+  - [What PARSEME Detects](#what-parseme-detects)
+  - [Language Support](#language-support)
+  - [Supported Projects](#supported-projects)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Automation Options](#automation-options)
+  - [Option 1: Manual Execution](#option-1-manual-execution)
+  - [Option 2: Automatic Local Generation](#option-2-automatic-local-generation)
+  - [Option 3: Automatic Local and Remote Generation (Advanced Git Hooks)](#option-3-automatic-local-and-remote-generation-advanced-git-hooks)
+  - [Option 4: GitHub Actions for Remote Generation paired with Local Generation](#option-4-github-actions-for-remote-generation-paired-with-local-generation)
+- [Configuration](#configuration)
+  - [Configuration File Formats & Priority](#configuration-file-formats--priority)
+  - [Configuration Priority](#configuration-priority)
+  - [Configuration Options](#configuration-options)
+  - [CLI Options](#cli-options)
+  - [Interactive Configuration](#interactive-configuration)
+- [CLI Commands](#cli-commands)
+- [Programmatic API](#programmatic-api)
+- [Output Format](#output-format)
+- [AI Agent Integration](#ai-agent-integration)
+- [Requirements](#requirements)
+- [License](#license)
+
 ## Development Status
 
-**This project is currently in active development and pre-alpha phase.**
+**This project is currently in active development.**
 
 The core functionality is working, but expect:
 
-- Breaking changes in configuration format
 - API modifications as the interface gets refined
 - Additional features being added regularly
 - Possible bugs and edge cases
@@ -88,10 +115,12 @@ PARSEME aims to automatically analyse any JavaScript or TypeScript project like:
 - **Desktop apps** - Main processes, renderers, IPC handlers
 - **Testing utilities** - Test functions, mocks, utilities, custom matchers
 
+**Note:** PARSEME provides specialized analysis for **Express.js**, **NestJS**, and **Fastify**, including route detection, middleware identification, and decorator analysis. All other frameworks benefit from universal AST-based analysis.
+
 ## Installation
 
 ```bash
-npm install --save-dev parseme
+npm install --save-dev @parseme/cli
 ```
 
 ## Quick Start
@@ -99,9 +128,9 @@ npm install --save-dev parseme
 1. **Initialize configuration**:
 
    ```bash
-   npx parseme init
+   npx @parseme/cli init
    # or use the alias
-   npx parseme i
+   npx @parseme/cli i
    ```
 
    You'll be prompted for:
@@ -114,30 +143,321 @@ npm install --save-dev parseme
    - How to add parseme script to package.json
    - How to integrate with git hooks
    - README section to help AI agents find context
+   - AI agent configuration files to reference PARSEME.md
 
-2. **Add to your package.json scripts** (optional, for easier execution):
-
-   ```json
-   {
-     "scripts": {
-       "parseme": "parseme generate"
-     }
-   }
-   ```
-
-3. **Generate context**:
+2. **Generate context**:
    ```bash
-   npm run parseme
-   # or
-   npx parseme generate
+   npx @parseme/cli generate
    # or use the alias
-   npx parseme g
+   npx @parseme/cli g
    ```
 
 This creates:
 
 - `PARSEME.md` - Main overview with links to context files
-- `parseme-context/` - Structured data files (AST, dependencies, routes, git info)
+- `parseme-context/` - Structured data files (file list, AST structure, routes, git diff)
+
+## Automation Options
+
+PARSEME can be integrated into your workflow in several ways, from manual execution to fully automated generation. Choose the approach that best fits your needs:
+
+### Option 1: Manual Execution
+
+Run parseme manually whenever you need updated context.
+
+**Setup:**
+
+Add to your `package.json` scripts (optional, for convenience):
+
+```json
+{
+  "scripts": {
+    "parseme": "parseme generate"
+  }
+}
+```
+
+**Usage:**
+
+```bash
+npm run parseme
+# or directly
+parseme generate
+```
+
+---
+
+### Option 2: Automatic Local Generation
+
+Automatically generate parseme files locally after every commit. Files are committed to the repository.
+
+**Setup with Husky:**
+
+```bash
+# Install Husky (if not already installed)
+npm install --save-dev husky
+npx husky init
+
+# Create post-commit hook
+cat > .husky/post-commit << 'EOF'
+#!/bin/sh
+
+# Generate PARSEME files locally after commit
+npx @parseme/cli generate
+EOF
+
+# Make hook executable
+chmod +x .husky/post-commit
+```
+
+**Setup with manual git hooks:**
+
+```bash
+cat > .git/hooks/post-commit << 'EOF'
+#!/bin/sh
+
+npx @parseme/cli generate
+EOF
+
+chmod +x .git/hooks/post-commit
+```
+
+**How it works:**
+
+- After each commit, parseme automatically generates context files with full git info
+- Files are ready to be staged and committed with your next commit
+- Simple setup with minimal configuration
+
+**Note:** If using a custom `contextDir`, ensure the path is consistent across your team's configuration.
+
+---
+
+### Option 3: Automatic Local and Remote Generation (Advanced Git Hooks)
+
+Automatically update parseme files locally and remotely with git hooks. Keeps the remote version clean (without git-specific info) while maintaining full context locally. Uses multiple git hooks to manage local vs remote state.
+
+**Setup with Husky:**
+
+```bash
+# Install Husky (if not already installed)
+npm install --save-dev husky
+npx husky init
+
+# Create post-commit hook
+cat > .husky/post-commit << 'EOF'
+#!/bin/sh
+
+npx @parseme/cli generate
+EOF
+
+# Create pre-push hook
+cat > .husky/pre-push << 'EOF'
+#!/bin/sh
+
+# Regenerate without git info for clean remote state
+npx @parseme/cli generate --no-git-info
+
+# Stage parseme files
+git add parseme-context/ PARSEME.md
+
+# Amend the commit with updated parseme files
+git commit --amend --no-edit --no-verify
+EOF
+
+# Create post-push hook
+cat > .husky/post-push << 'EOF'
+#!/bin/sh
+
+# Regenerate with git info for local development
+npx @parseme/cli generate
+EOF
+
+# Make hooks executable
+chmod +x .husky/post-commit .husky/pre-push .husky/post-push
+```
+
+**Setup with manual git hooks:**
+
+```bash
+# Post-commit: Generate context with git info after each commit
+cat > .git/hooks/post-commit << 'EOF'
+#!/bin/sh
+
+npx @parseme/cli generate
+EOF
+
+# Pre-push: Regenerate without git info and amend before pushing
+cat > .git/hooks/pre-push << 'EOF'
+#!/bin/sh
+
+# Regenerate without git info for clean remote state
+npx @parseme/cli generate --no-git-info
+
+# Stage parseme files
+git add parseme-context/ PARSEME.md
+
+# Amend the commit with updated parseme files
+git commit --amend --no-edit --no-verify
+EOF
+
+# Post-push: Restore git info locally after push completes
+cat > .git/hooks/post-push << 'EOF'
+#!/bin/sh
+
+# Regenerate with git info for local development
+npx @parseme/cli generate
+EOF
+
+# Make hooks executable
+chmod +x .git/hooks/post-commit .git/hooks/pre-push .git/hooks/post-push
+```
+
+**How it works:**
+
+1. **post-commit**: Generates context files with full git info locally
+2. **pre-push**: Regenerates without git info and amends the commit before pushing
+3. **post-push**: Restores full git info locally after push completes
+
+The `--no-verify` flag in pre-push prevents an infinite loop by skipping hook execution on the amend.
+
+**Note:** If using a custom `contextDir`, update the `git add` path in the pre-push hook (e.g., `git add docs/context/ PARSEME.md`).
+
+---
+
+### Option 4: GitHub Actions for Remote Generation paired with Local Generation
+
+Use GitHub Actions to automatically manage remote parseme files while keeping them updated locally with git hooks. This is the recommended approach for teams using GitHub.
+
+**Setup:**
+
+**1. Add parseme files to `.gitignore`:**
+
+```gitignore
+# Parseme documentation (generated locally and by CI)
+parseme-context/
+PARSEME.md
+```
+
+**2. Create `.github/workflows/parseme-update.yml`:**
+
+```yaml
+name: Update PARSEME Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  update-parseme:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
+
+    steps:
+      - name: Check if pusher is service account
+        id: check_pusher
+        run: |
+          if [ "${{ github.event.pusher.name }}" = "${{ secrets.GH_SERVICE_ACCOUNT_USERNAME }}" ]; then
+            echo "is_bot=true" >> $GITHUB_OUTPUT
+          else
+            echo "is_bot=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Checkout code
+        if: steps.check_pusher.outputs.is_bot == 'false'
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
+
+      - name: Setup Node.js
+        if: steps.check_pusher.outputs.is_bot == 'false'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Configure Git
+        if: steps.check_pusher.outputs.is_bot == 'false'
+        run: |
+          git config user.name "${{ secrets.GH_SERVICE_ACCOUNT_USERNAME }}"
+          git config user.email "${{ secrets.GH_SERVICE_ACCOUNT_USERNAME }}@users.noreply.github.com"
+
+      - name: Install dependencies
+        if: steps.check_pusher.outputs.is_bot == 'false'
+        run: npm ci
+
+      - name: Generate ParseMe documentation
+        if: steps.check_pusher.outputs.is_bot == 'false'
+        run: parseme generate --no-git-info
+
+      - name: Force add parseme files (ignored in .gitignore)
+        if: steps.check_pusher.outputs.is_bot == 'false'
+        run: git add -f parseme-context/ PARSEME.md
+
+      - name: Check for changes
+        if: steps.check_pusher.outputs.is_bot == 'false'
+        id: check_changes
+        run: |
+          if git diff --cached --quiet; then
+            echo "changes=false" >> $GITHUB_OUTPUT
+          else
+            echo "changes=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Commit and amend
+        if: steps.check_pusher.outputs.is_bot == 'false' && steps.check_changes.outputs.changes == 'true'
+        run: |
+          git commit --amend --no-edit --no-verify
+          git push --force-with-lease
+```
+
+**3. Configure GitHub secrets:**
+
+- `GH_SERVICE_ACCOUNT_TOKEN`: A GitHub personal access token with repo write permissions
+- `GH_SERVICE_ACCOUNT_USERNAME`: The username of your service account (to prevent infinite loops)
+
+**4. Setup local git hooks with Husky:**
+
+```bash
+# Install Husky (if not already installed)
+npm install --save-dev husky
+npx husky init
+
+# Create post-commit hook
+cat > .husky/post-commit << 'EOF'
+#!/bin/sh
+
+# Generate PARSEME files locally after commit
+npx @parseme/cli generate
+EOF
+
+# Create post-merge hook
+cat > .husky/post-merge << 'EOF'
+#!/bin/sh
+
+# Untrack parseme files after merge/pull to keep them gitignored locally
+git rm --cached -r parseme-context/ PARSEME.md 2>/dev/null || true
+EOF
+
+# Make hooks executable
+chmod +x .husky/post-commit .husky/post-merge
+```
+
+**How it works:**
+
+1. **Local development**: Parseme files are generated locally after each commit with full git info
+2. **Ignored by git**: Files are listed in `.gitignore` so they're not committed manually
+3. **Remote updates**: GitHub Actions automatically generates and commits parseme files (without git info) when pushing to main
+4. **After pull/merge**: The post-merge hook ensures parseme files stay untracked locally, preventing conflicts
+
+**Notes:**
+
+- The workflow only runs on the `main` branch (adjust as needed for your branching strategy)
+- If using a custom `contextDir`, update both the `.gitignore` entry, the workflow's `git add -f` path, and the post-merge hook's `git rm --cached -r` path accordingly
 
 ## Configuration
 
@@ -148,7 +468,7 @@ The `parseme init` command creates a minimal config with only your custom settin
 **Minimal config example** (created by `parseme init`):
 
 ```javascript
-/** @type {import('parseme').ParsemeConfigFile} */
+/** @type {import('@parseme/cli').ParsemeConfigFile} */
 const config = {
   contextDir: 'parseme-context',
   excludePatterns: ['node_modules/**', '.git/**'],
@@ -160,7 +480,7 @@ export default config;
 **Full config example** (all available options):
 
 ```javascript
-/** @type {import('parseme').ParsemeConfigFile} */
+/** @type {import('@parseme/cli').ParsemeConfigFile} */
 const config = {
   // Output settings
   outputPath: 'PARSEME.md',
@@ -223,7 +543,7 @@ PARSEME supports three configuration formats with the following priority:
 #### Example TypeScript Configuration
 
 ```typescript
-import type { ParsemeConfigFile } from 'parseme';
+import type { ParsemeConfigFile } from '@parseme/cli';
 
 const config: ParsemeConfigFile = {
   contextDir: 'parseme-context',
@@ -237,7 +557,7 @@ export default config;
 #### Example JavaScript Configuration
 
 ```javascript
-/** @type {import('parseme').ParsemeConfigFile} */
+/** @type {import('@parseme/cli').ParsemeConfigFile} */
 const config = {
   contextDir: 'parseme-context',
   excludePatterns: ['node_modules/**', 'dist/**', '.git/**'],
@@ -255,7 +575,7 @@ Configuration values are resolved in the following order (highest to lowest prio
 2. **Config file** - Based on file format priority above
 3. **Default values** - Built-in sensible defaults
 
-**Example**: `npx parseme --output custom.md` overrides `outputPath` from config file.
+**Example**: `parseme --output custom.md` overrides `outputPath` from config file.
 
 ### Configuration Options
 
@@ -298,63 +618,6 @@ Toggle which sections to include in the output (all default to `true`):
 
 - `limits.maxFilesPerContext` - Maximum number of files to analyze (default: `5000`)
 
-## Output Format
-
-PARSEME always generates the following output files:
-
-- `PARSEME.md` - Main overview with links to context files (Markdown)
-- Context directory (default: `parseme-context/`) with structured data files:
-  - `files.md` - Complete list of analyzed files (Markdown)
-  - `structure.json` - AST analysis with exports, imports, functions, and classes (JSON)
-  - `api-endpoints.json` - API routes with methods, paths, and handlers (JSON, only if routes detected)
-  - `dependencies.json` - Production dependencies with versions (JSON)
-  - `framework.json` - Framework details if detected (JSON, optional)
-  - `gitDiff.md` - Git diff statistics from generation time (Markdown, if git enabled)
-
-The context directory location can be customized via the `contextDir` configuration option.
-
-## CLI Commands
-
-```bash
-# Generate context (auto-detects config file)
-npx parseme generate
-npx parseme g  # alias
-
-# Initialize configuration (JSON by default)
-npx parseme init
-npx parseme i  # alias
-
-# Initialize with TypeScript format
-npx parseme init --format ts
-
-# Initialize with JavaScript format
-npx parseme init --format js
-
-# Use custom config file
-npx parseme generate --config custom.config.js
-
-# If added to package.json scripts, use npm run
-npm run parseme
-
-# Auto-generate context with git hooks (when configured)
-# Runs automatically after each commit
-
-# Override config with CLI flags
-npx parseme generate --output custom.md --context-dir docs/context --root ./src
-
-# Disable git info generation (keeps git for file discovery)
-npx parseme generate --no-git-info
-
-# Disable git for file discovery (keeps git info generation)
-npx parseme generate --no-git-files
-
-# Disable both git info and git file discovery
-npx parseme generate --no-git-info --no-git-files
-
-# Specify file types and exclude patterns
-npx parseme generate --file-types ts js --exclude "**/*.test.ts"
-```
-
 ### CLI Options
 
 #### Generate Command (`parseme generate` or `parseme g`)
@@ -386,35 +649,50 @@ After initialization, setup tips are displayed:
 - Package.json script suggestion
 - Git hook integration suggestion
 - README.md section suggestion for AI agents
+- AI agent configuration files to reference PARSEME.md
+
+## CLI Commands
 
-## Framework Support
+```bash
+# Generate context (auto-detects config file)
+parseme generate
+parseme g  # alias
+
+# Initialize configuration (JSON by default)
+parseme init
+parseme i  # alias
 
-PARSEME automatically detects and provides specialized analysis for:
+# Initialize with TypeScript format
+parseme init --format ts
+
+# Initialize with JavaScript format
+parseme init --format js
 
-### Express.js
+# Use custom config file
+parseme generate --config custom.config.js
 
-- Route detection (`app.get`, `router.post`, etc.)
-- Middleware identification
-- Request handler mapping
+# Override config with CLI flags
+parseme generate --output custom.md --context-dir docs/context --root ./src
 
-### NestJS
+# Disable git info generation (keeps git for file discovery)
+parseme generate --no-git-info
 
-- Controller and decorator analysis
-- Module structure detection w
-- Dependency injection mapping
+# Disable git for file discovery (keeps git info generation)
+parseme generate --no-git-files
 
-### Fastify
+# Disable both git info and git file discovery
+parseme generate --no-git-info --no-git-files
 
-- Route registration detection
-- Plugin identification
-- Hook analysis
+# Specify file types and exclude patterns
+parseme generate --file-types ts js --exclude "**/*.test.ts"
+```
 
 ## Programmatic API
 
 You can also use PARSEME programmatically:
 
 ```typescript
-import { ParsemeGenerator } from 'parseme';
+import { ParsemeGenerator } from '@parseme/cli';
 
 const generator = await ParsemeGenerator.fromConfig('./custom.config.js');
 const context = await generator.generate();
@@ -423,80 +701,54 @@ const context = await generator.generate();
 await generator.generateToFile('./output/PARSEME.md');
 ```
 
-## Git Hook Integration
-
-Keep your AI context automatically updated by integrating parseme with git hooks. The recommended setup uses three hooks to ensure context files always have git info locally but stay clean on remote:
-
-### Recommended Hook Setup
-
-#### Manual Setup
+## Output Format
 
-```bash
-# 1. Post-commit: Generate context with git info after each commit
-cat > .git/hooks/post-commit << 'EOF'
-#!/bin/sh
+PARSEME generates the following output files:
 
-npx parseme generate
-EOF
+- `PARSEME.md` - Main overview with links to context files and project summary (Markdown)
+- Context directory (default: `parseme-context/`) with structured data files:
+  - `files.md` - Complete list of all project files (Markdown)
+  - `structure.json` - AST analysis with exports, imports, functions, classes, and route references (JSON)
+  - `routes.json` - API routes with methods, paths, and handlers (JSON, only if routes detected)
+  - `gitDiff.md` - Git diff statistics from generation time (Markdown, only if git is enabled and changes exist)
 
-# 2. Pre-push: Regenerate without git info and amend before pushing
-cat > .git/hooks/pre-push << 'EOF'
-#!/bin/sh
+The context directory location can be customized via the `contextDir` configuration option.
 
-# Regenerate without git info for clean remote state
-npx parseme generate --no-git-info
+## AI Agent Integration
 
-# Stage parseme files (parseme-context/ may be different if configured)
-git add parseme-context/ PARSEME.md
+To help AI coding assistants efficiently understand your codebase structure and context, add instructions to your agent configuration files:
 
-# Amend the commit with updated parseme files
-git commit --amend --no-edit --no-verify
-EOF
+### Claude Code (`.claude/README.md` or `.claude/instructions.md`)
 
-# 3. Post-push: Restore git info locally after push completes
-cat > .git/hooks/post-push << 'EOF'
-#!/bin/sh
+```markdown
+Read PARSEME.md and parseme-context/ to understand the codebase structure and context.
+```
 
-# Regenerate with git info for local development
-npx parseme generate
-EOF
+### GitHub Copilot (`.github/copilot-instructions.md`)
 
-# Make hooks executable
-chmod +x .git/hooks/post-commit .git/hooks/pre-push .git/hooks/post-push
+```markdown
+Read PARSEME.md and parseme-context/ to understand the codebase structure and context.
 ```
 
-**Note:** If you've configured a custom `contextDir` (either in your config file or via the `--context-dir` CLI flag), update the `git add` path in the pre-push hook accordingly (e.g., `git add docs/context/ PARSEME.md`).
-
-### Using Husky
+### Cursor (`.cursorrules`)
 
-```json
-// package.json
-{
-  "husky": {
-    "hooks": {
-      "post-commit": "npx parseme generate",
-      "pre-push": "npx parseme generate --no-git-info && git add parseme-context/ PARSEME.md && git commit --amend --no-edit --no-verify",
-      "post-push": "npx parseme generate"
-    }
-  }
-}
+```
+Read PARSEME.md and parseme-context/ to understand the codebase structure and context.
 ```
 
-**Note:** If using a custom `contextDir`, update the `git add` path to match your configuration.
-
-### How It Works
+### ChatGPT / Custom GPT
 
-1. **post-commit**: After you commit, parseme generates context files with git info (current branch, recent commits, git diff) for local development
-2. **pre-push**: Before pushing, parseme regenerates without git info (`--no-git-info` flag) and amends the commit to keep remote clean
-3. **post-push**: After push completes, parseme regenerates with git info again so your local working copy maintains full context
+Add to project instructions or system prompt:
 
-The `--no-verify` flag in pre-push prevents an infinite loop by skipping hook execution on the amend.
+```
+Read PARSEME.md and parseme-context/ to understand the codebase structure and context.
+```
 
-This automatically keeps your AI context files synchronized with your code while maintaining clean context on remote and detailed context locally!
+This ensures AI assistants use your pre-generated context for efficient codebase understanding.
 
 ## Requirements
 
-- Node.js ≥20.19.5
+- Node.js ≥20.19.5 <21 || ≥22.21.1
 - npm ≥10.8.2
 
 ## License

package/dist/cli/cli.js

@@ -8,7 +8,7 @@ const program = new Command();
 async function promptForMissingConfig(config) {
     return { ...config };
 }
-program.name('parseme').description('AI Project Context Generator').version('0.1.0');
+program.name('parseme').description('AI Project Context Generator').version('0.1.1');
 // Generate command
 program
     .command('generate')
@@ -126,7 +126,13 @@ program
         console.log('## Instructions For AI Agents');
         console.log('This project includes AI-optimized documentation for efficient context providing:');
         console.log('- `PARSEME.md` - Project overview with links to detailed context files');
-        console.log('- `parseme-context/` - Structured data files (AST analysis, dependencies, routes, git info)');
+        console.log('- `parseme-context/` - Structured data files (file list, AST structure, routes, git diff)');
+        console.log('');
+        console.log('Tip: Add references to PARSEME.md in your AI agent config files for efficient context gathering:');
+        console.log('  - Claude Code: .claude/README.md or .claude/instructions.md');
+        console.log('  - GitHub Copilot: .github/copilot-instructions.md');
+        console.log('  - Cursor: .cursorrules');
+        console.log('  - Example instruction: "Read PARSEME.md and parseme-context/ to understand the codebase structure and context."');
         console.log('');
     }
     catch (error) {

package/dist/core/context-builder.js

@@ -38,11 +38,11 @@ export class ContextBuilder {
         });
         const hasRoutes = routes.length > 0;
         const mainContent = this.buildHeader(linkPath, hasRoutes) +
-            '\n\n\n' +
+            '\n\n' +
             this.buildProjectOverview(projectInfo) +
-            '\n\n\n' +
+            '\n\n' +
             this.buildSummarySection(linkPath, hasRoutes) +
-            '\n\n\n' +
+            '\n\n' +
             (gitInfo ? this.buildGitSection(gitInfo) : '');
         const contextFiles = {
             structure: '',
@@ -73,9 +73,11 @@ export class ContextBuilder {
             : `5. For git tracked projects, follow the instructions in the "Git Information" section of this file to validate the actuality of the provided information.
 6. Only dive deeper into specific files after reviewing this summary, that replaces the need for initial project exploration and significantly reduces token usage for project comprehension.`;
         return `## PARSEME - AI Agent Context
+
 Auto-generated project summary optimized for AI coding agents. This file provides complete project context without requiring full codebase traversal, designed for token efficiency.
 
 **Usage Instructions for AI Agents:**
+
 1. Read this PARSEME.md file completely first before accessing individual project files
 2. Basic project information, script availability and dependency information provides basic understanding of code base and tech stack without checking package.json
 3. Use the provided file list [${linkPath}/files.md](${linkPath}/files.md) to see all tracked files in the project
@@ -98,14 +100,14 @@ ${routesInstructions}`;
         // Add dependencies
         const deps = Object.keys(projectInfo.dependencies);
         if (deps.length > 0) {
-            content += '\n\n### Dependencies\n';
+            content += '\n### Dependencies\n\n';
             deps.forEach((dep) => {
                 content += `- ${dep}\n`;
             });
         }
         // Add available scripts
         if (projectInfo.scripts && Object.keys(projectInfo.scripts).length > 0) {
-            content += '\n### Available Scripts\n';
+            content += '\n### Available Scripts\n\n';
             Object.entries(projectInfo.scripts).forEach(([name, script]) => {
                 content += `- **${name}**: \`${script}\`\n`;
             });
@@ -130,33 +132,38 @@ ${routesInstructions}`;
 - **Branch:** ${gitInfo.branch}
 - **Commit:** ${gitInfo.lastCommit}${gitInfo.origin ? `\n- **Origin:** ${gitInfo.origin}` : ''}
 
-### Git Diff Statistics`;
+### Git Diff Statistics
+`;
         const info = gitInfo.diffStat && gitInfo.diffStat.length > 0
             ? `Git diff statistics from the time of generation are available at [parseme-context/gitDiff.md](parseme-context/gitDiff.md) (relative to the commit mentioned above).
 
 **AI Agent Command:** To check for changes since generation, run:
+
 \`\`\`bash
 git diff --stat
 \`\`\`
+
 Compare the output with the baseline in [parseme-context/gitDiff.md](parseme-context/gitDiff.md) to detect any modifications.`
             : `Git diff statistics showed no changes at the time of generation relative to the commit mentioned above.`;
-        return base + '\n\n' + info;
+        return base + '\n' + info;
     }
     buildSummarySection(linkPath, hasRoutes) {
         let content = `## Project Files
-A complete list of all git-tracked files in the project (excluding files matching additional exclude patterns) is available at [${linkPath}/files.md](${linkPath}/files.md). This provides a quick overview of the project structure.
 
+A complete list of all git-tracked files in the project (excluding files matching additional exclude patterns) is available at [${linkPath}/files.md](${linkPath}/files.md). This provides a quick overview of the project structure.
 
 ## Project Structure & AST
+
 Detailed structure and Abstract Syntax Tree data for all tracked files is available at [${linkPath}/structure.json](${linkPath}/structure.json). This includes file paths, types, imports, exports, functions, classes, interfaces, and routes for comprehensive code analysis without manual parsing.`;
         if (hasRoutes) {
-            content += `\n\n\n## API Routes
+            content += `\n\n## API Routes
+
 A comprehensive list of all discovered API routes is available at [${linkPath}/routes.json](${linkPath}/routes.json). This includes HTTP methods, paths, handler names, and source file locations for backend routes (Express, NestJS, and decorator-based routing).`;
         }
         return content;
     }
     buildFilesList(allFiles) {
-        let content = `# Project Files\n`;
+        let content = `# Project Files\n\n`;
         allFiles.forEach((file) => {
             content += `- ${file}\n`;
         });
@@ -218,6 +225,7 @@ A comprehensive list of all discovered API routes is available at [${linkPath}/r
     }
     buildDetailedGit(gitInfo) {
         let content = `# Git Diff Statistics
+
 `;
         content += gitInfo.diffStat;
         return content;

package/dist/core/generator.js

@@ -75,12 +75,16 @@ export class ParsemeGenerator {
         // Clear the directory if it exists, then recreate it
         await rm(parsemeDir, { recursive: true, force: true });
         await mkdir(parsemeDir, { recursive: true });
-        await writeFile(finalOutputPath, context.parseme);
+        const parsemeContent = context.parseme.endsWith('\n')
+            ? context.parseme
+            : context.parseme + '\n';
+        await writeFile(finalOutputPath, parsemeContent);
         if (context.context) {
             for (const [filename, content] of Object.entries(context.context)) {
                 // Use .md extension for markdown files, .json for others
                 const extension = filename === 'gitDiff' || filename === 'files' ? '.md' : '.json';
-                await writeFile(join(parsemeDir, `${filename}${extension}`), content);
+                const fileContent = content.endsWith('\n') ? content : content + '\n';
+                await writeFile(join(parsemeDir, `${filename}${extension}`), fileContent);
             }
         }
     }

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@parseme/cli",
-  "version": "0.0.6",
+  "version": "0.1.1",
   "description": "Adds a PARSEME.md file—a README.md for AI agents—to your project, providing context and structure for automated tools.",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "parseme": "dist/cli/cli.js"
   },
@@ -15,7 +20,7 @@
   ],
   "engines": {
     "npm": ">=10.8.2",
-    "node": ">=20.19.5"
+    "node": ">=20.19.5 <21 || >=22.21.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -53,7 +58,7 @@
   "bugs": {
     "url": "https://github.com/citrus551/parseme-modules/issues"
   },
-  "homepage": "https://github.com/citrus551/parseme-modules#readme",
+  "homepage": "https://parseme.ai",
   "dependencies": {
     "@babel/core": "^7.28.4",
     "@babel/parser": "^7.28.4",