@parseme/cli 0.1.0 → 0.1.2

package/README.md

@@ -120,7 +120,7 @@ PARSEME aims to automatically analyse any JavaScript or TypeScript project like:
 ## Installation
 
 ```bash
-npm install --save-dev parseme
+npm install --save-dev @parseme/cli
 ```
 
 ## Quick Start
@@ -128,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:
@@ -147,9 +147,9 @@ npm install --save-dev parseme
 
 2. **Generate context**:
    ```bash
-   npx parseme generate
+   npx @parseme/cli generate
    # or use the alias
-   npx parseme g
+   npx @parseme/cli g
    ```
 
 This creates:
@@ -182,11 +182,9 @@ Add to your `package.json` scripts (optional, for convenience):
 ```bash
 npm run parseme
 # or directly
-npx parseme generate
+parseme generate
 ```
 
-**Best for:** Small projects, occasional updates, or when you prefer full control over when context is generated.
-
 ---
 
 ### Option 2: Automatic Local Generation
@@ -204,8 +202,12 @@ npx husky init
 cat > .husky/post-commit << 'EOF'
 #!/bin/sh
 
+# Load nvm if available
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
 # Generate PARSEME files locally after commit
-npx parseme generate
+npx @parseme/cli generate
 EOF
 
 # Make hook executable
@@ -218,7 +220,7 @@ chmod +x .husky/post-commit
 cat > .git/hooks/post-commit << 'EOF'
 #!/bin/sh
 
-npx parseme generate
+npx @parseme/cli generate
 EOF
 
 chmod +x .git/hooks/post-commit
@@ -230,8 +232,6 @@ chmod +x .git/hooks/post-commit
 - Files are ready to be staged and committed with your next commit
 - Simple setup with minimal configuration
 
-**Best for:** Solo developers or small teams wanting automatic local updates with committed parseme files.
-
 **Note:** If using a custom `contextDir`, ensure the path is consistent across your team's configuration.
 
 ---
@@ -251,15 +251,23 @@ npx husky init
 cat > .husky/post-commit << 'EOF'
 #!/bin/sh
 
-npx parseme generate
+# Load nvm if available
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
+npx @parseme/cli generate
 EOF
 
 # Create pre-push hook
 cat > .husky/pre-push << 'EOF'
 #!/bin/sh
 
+# Load nvm if available
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
 # Regenerate without git info for clean remote state
-npx parseme generate --no-git-info
+npx @parseme/cli generate --no-git-info
 
 # Stage parseme files
 git add parseme-context/ PARSEME.md
@@ -272,8 +280,12 @@ EOF
 cat > .husky/post-push << 'EOF'
 #!/bin/sh
 
+# Load nvm if available
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
 # Regenerate with git info for local development
-npx parseme generate
+npx @parseme/cli generate
 EOF
 
 # Make hooks executable
@@ -287,7 +299,7 @@ chmod +x .husky/post-commit .husky/pre-push .husky/post-push
 cat > .git/hooks/post-commit << 'EOF'
 #!/bin/sh
 
-npx parseme generate
+npx @parseme/cli generate
 EOF
 
 # Pre-push: Regenerate without git info and amend before pushing
@@ -295,7 +307,7 @@ cat > .git/hooks/pre-push << 'EOF'
 #!/bin/sh
 
 # Regenerate without git info for clean remote state
-npx parseme generate --no-git-info
+npx @parseme/cli generate --no-git-info
 
 # Stage parseme files
 git add parseme-context/ PARSEME.md
@@ -309,7 +321,7 @@ cat > .git/hooks/post-push << 'EOF'
 #!/bin/sh
 
 # Regenerate with git info for local development
-npx parseme generate
+npx @parseme/cli generate
 EOF
 
 # Make hooks executable
@@ -324,27 +336,17 @@ chmod +x .git/hooks/post-commit .git/hooks/pre-push .git/hooks/post-push
 
 The `--no-verify` flag in pre-push prevents an infinite loop by skipping hook execution on the amend.
 
-**Best for:** Teams that want detailed local context for development while keeping clean, portable context in the repository.
-
 **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.
+Use GitHub Actions to automatically update PARSEME files on every push to main. 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`:**
+**1. Create `.github/workflows/parseme-update.yml`:**
 
 ```yaml
 name: Update PARSEME Documentation
@@ -352,7 +354,7 @@ name: Update PARSEME Documentation
 on:
   push:
     branches:
-      - main
+      - 'main'
 
 jobs:
   update-parseme:
@@ -363,49 +365,46 @@ jobs:
       GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
 
     steps:
-      - name: Check if pusher is service account
-        id: check_pusher
+      - name: Service Account Gate
         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
+            echo "::notice::Skipping workflow - push was made by service account"
+            exit 1
           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'
+          node-version: '24'
           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: Configure npm for GitHub Packages
+        run: |
+          npm config set @netgear:registry https://npm.pkg.github.com/
+          npm config set //npm.pkg.github.com/:_authToken "${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}"
+
       - 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'
+      - name: Generate PARSEME documentation
         run: npx 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: Stage changes
+        run: |
+          git add PARSEME.md parseme-context/
 
       - name: Check for changes
-        if: steps.check_pusher.outputs.is_bot == 'false'
         id: check_changes
         run: |
           if git diff --cached --quiet; then
@@ -414,58 +413,87 @@ jobs:
             echo "changes=true" >> $GITHUB_OUTPUT
           fi
 
-      - name: Commit and amend
-        if: steps.check_pusher.outputs.is_bot == 'false' && steps.check_changes.outputs.changes == 'true'
+      - name: Commit
+        if: steps.check_changes.outputs.changes == 'true'
         run: |
-          git commit --amend --no-edit --no-verify
-          git push --force-with-lease
+          git commit -m "chore: Update PARSEME AI Agent Context [skip ci]" --no-verify
+          git push
 ```
 
-**3. Configure GitHub secrets:**
+**2. 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)
+- `GH_SERVICE_ACCOUNT_USERNAME`: The username of your service account
 
-**4. Setup local git hooks with Husky:**
+**3. Setup local git hooks with Husky:**
 
 ```bash
 # Install Husky (if not already installed)
 npm install --save-dev husky
 npx husky init
 
+# Create pre-commit hook
+cat > .husky/pre-commit << 'EOF'
+#!/bin/sh
+
+# Pre-commit hook to reset PARSEME files to prevent them from being committed
+for file in $(git ls-files parseme-context/ PARSEME.md 2>/dev/null); do
+    git restore --staged "$file" 2>/dev/null
+done
+EOF
+
 # Create post-commit hook
 cat > .husky/post-commit << 'EOF'
 #!/bin/sh
 
-# Generate PARSEME files locally after commit
-npx parseme generate
+# Load nvm if available
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
+# Generate PARSEME files locally after commit for local AI agent usage
+npx @parseme/cli generate --no-git-info
 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
+# Load nvm if available
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
+# Generate PARSEME files locally after merge for local AI agent usage
+npx @parseme/cli generate --no-git-info
+EOF
+
+# Create post-checkout hook
+cat > .husky/post-checkout << 'EOF'
+#!/bin/sh
+
+# Load nvm if available
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
+# Generate PARSEME files locally after checkout for local AI agent usage
+npx @parseme/cli generate --no-git-info
 EOF
 
 # Make hooks executable
-chmod +x .husky/post-commit .husky/post-merge
+chmod +x .husky/pre-commit .husky/post-commit .husky/post-merge .husky/post-checkout
 ```
 
 **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
-
-**Best for:** Teams using GitHub that want automated CI-managed remote updates with local context for development.
+1. **On push to main**: GitHub Actions detects the push
+2. **Service account check**: Workflow exits early if the push was made by the service account
+3. **Generate and commit**: Generates PARSEME files with `--no-git-info` flag and creates a new commit with `[skip ci]` message
+4. **Push changes**: The new commit is pushed back to the repository
+5. **Local hooks**: Pre-commit hook prevents PARSEME files from being committed manually, while post-commit/merge/checkout hooks regenerate them locally for AI agent usage
 
 **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
+- If using a custom `contextDir`, update the paths in both the workflow and hooks accordingly
 
 ## Configuration
 
@@ -476,7 +504,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/**'],
@@ -488,7 +516,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',
@@ -551,7 +579,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',
@@ -565,7 +593,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/**'],
@@ -583,7 +611,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
 
@@ -663,42 +691,36 @@ After initialization, setup tips are displayed:
 
 ```bash
 # Generate context (auto-detects config file)
-npx parseme generate
-npx parseme g  # alias
+parseme generate
+parseme g  # alias
 
 # Initialize configuration (JSON by default)
-npx parseme init
-npx parseme i  # alias
+parseme init
+parseme i  # alias
 
 # Initialize with TypeScript format
-npx parseme init --format ts
+parseme init --format ts
 
 # Initialize with JavaScript format
-npx parseme init --format js
+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
+parseme generate --config custom.config.js
 
 # Override config with CLI flags
-npx parseme generate --output custom.md --context-dir docs/context --root ./src
+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
+parseme generate --no-git-info
 
 # Disable git for file discovery (keeps git info generation)
-npx parseme generate --no-git-files
+parseme generate --no-git-files
 
 # Disable both git info and git file discovery
-npx parseme generate --no-git-info --no-git-files
+parseme generate --no-git-info --no-git-files
 
 # Specify file types and exclude patterns
-npx parseme generate --file-types ts js --exclude "**/*.test.ts"
+parseme generate --file-types ts js --exclude "**/*.test.ts"
 ```
 
 ## Programmatic API
@@ -706,7 +728,7 @@ npx parseme generate --file-types ts js --exclude "**/*.test.ts"
 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();

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.2');
 // Generate command
 program
     .command('generate')

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,27 +132,32 @@ ${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;
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parseme/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Adds a PARSEME.md file—a README.md for AI agents—to your project, providing context and structure for automated tools.",
   "type": "module",
   "exports": {