LeanCode — Deterministic Code Health Framework

A secure, npx-only CLI bootstrapper that prevents direct npm installation and keeps framework logic private.

🚀 Quick Start

npx leancode init
npx leancode sync
npx leancode review

That's it! LeanCode will:

1. ✔ Validate your project environment
2. ✔ Download the framework from remote source
3. ✔ Inject framework files into .leancode/
4. ✔ Cleanup temporary files
5. ✔ Output success message
6. ✔ Generate analysis reports for developers and managers

🔎 Manager Review Mode

LeanCode can review existing projects (including non-Node repositories) with deterministic checks and plain-language output for managers.

npx leancode review

Generated artifacts:

• LEANCODE_REVIEW.md (manager-friendly report)
• .leancode/review-report.json (machine-readable)
• .leancode/AI_CONTEXT.md (developer context, refreshed)

Review options:

npx leancode review --json
npx leancode review --fail-on-high-risk

🛡️ Security Features

✅ NPX-Only Distribution

• Works only via npx leancode init
• Direct npm install leancode is blocked
• Framework logic is not published to npm
• Published npm package contains only the CLI bootstrapper (bin/)

✅ Framework Privacy

Framework files are:

• Not included in the npm package
• Dynamically downloaded at runtime
• Extracted to .leancode/ in your project
• Temporary files cleaned up after initialization

✅ Zero Side-Effects

• No global installation required
• No configuration files in ~/.leancode/
• All artifacts isolated to project directory
• Easy to remove (just delete .leancode/ folder)

📦 What Gets Published to npm

Only the CLI bootstrapper:

leancode/
└── bin/
    └── cli.js          ← Single file, ~10KB

Not published:

• cli/ — command handlers
• engine/ — framework logic
• generators/ — code generators
• templates/ — context templates
• utils/ — helper functions

This ensures:

1. Small npm package (~15KB)
2. No framework accidentally exposed
3. Framework updates independent of npm releases
4. Security: prompts and logic remain private

🔒 How It Works

User runs: npx leancode init
           ↓
    [Fetch from npm]
           ↓
   [Validate npx execution]
           ↓
  [Download framework ZIP]
           ↓
  [Extract to .leancode/]
           ↓
[Run framework initialization]
           ↓
  [Cleanup temp files]
           ↓
[Done! Ready to use]

⚙️ Configuration

Set custom framework source via environment variables:

# Clone from private git repo
export LEANCODE_REPO_URL="https://github.com/myorg/leancode-core.git"
npx leancode init

# Or use HTTPS download
export LEANCODE_DOWNLOAD_URL="https://releases.example.com/leancode-framework.zip"
npx leancode init

📋 Environment Variables

| Variable | Purpose | Example | |----------|---------|---------| | LEANCODE_REPO_URL | Git repository for framework | https://github.com/org/repo.git | | LEANCODE_DOWNLOAD_URL | HTTPS download URL (fallback) | https://example.com/framework.zip |

🗂️ Project Structure After npx leancode init

your-project/
├── package.json
├── .leancode/                    ← Framework injected here
│   ├── engine/
│   ├── generators/
│   ├── templates/
│   ├── utils/
│   ├── AI_CONTEXT.md            ← Auto-generated
│   └── cli.js                    ← Runtime commands
├── src/
└── ...

🚫 Blocking npm install

If someone tries:

npm install leancode

They will see:

❌ LeanCode is not meant to be installed.

Use:
    npx leancode init

This works by:

1. Detecting execution context via npm_execpath environment variable
2. Checking npm_config_user_agent for npx marker
3. Exiting with error if not via npx

🎯 Use Cases

✅ Best for:

• One-time project initialization
• Framework bootstrapping
• Keeping framework logic private
• Maintaining small npm package size
• Independent framework updates

❌ Not suitable for:

• Runtime dependencies (use separate packages)
• Global CLI tools (use npm install -g for those)
• Multi-feature npm packages

🔧 Development

Clone repository

git clone https://github.com/yourusername/leancode.git
cd leancode

Test locally

# Install dependencies (if any)
npm install

# Test the CLI
node bin/cli.js init /path/to/test-project

Publish to npm

npm version patch
npm publish

# Users can then use:
npx leancode init

Update framework source

Framework is downloaded from (configure one):

1. Git: Default to LEANCODE_REPO_URL env var
2. HTTPS: Fallback to LEANCODE_DOWNLOAD_URL env var

📚 Architecture

Published Package (leancode)

• Role: CLI bootstrapper only
• Size: ~15KB
• Updates: Infrequent (only CLI changes)
• Dependency: Node.js only

Framework (leancode-core)

• Role: Application logic and generators
• Deployment: Git repo or release artifact
• Updates: Independent from npm package
• Privacy: Not exposed in npm tarball

🛠️ Troubleshooting

"❌ LeanCode is not meant to be installed"

Solution: Use npx instead:

npx leancode init

"Failed to download framework"

Cause: Network issue or invalid LEANCODE_REPO_URL

Solution:

# Check URL is accessible:
curl https://github.com/yourusername/leancode-core

# Set custom URL:
export LEANCODE_REPO_URL="https://your-repo-url.git"
npx leancode init

Permission denied on Windows

Solution: Ensure Node.js is properly installed and added to PATH

📄 License

MIT

🤝 Contributing

Pull requests welcome! Please ensure:

• CLI changes are in bin/cli.js
• Framework changes go in leancode-core repo
• Tests pass
• Code is readable

Questions? Open an issue on GitHub.