npm package: @resit/engineering-rules
Description: Corporate CLI tool to bootstrap projects and install engineering rules for AI-assisted development
Author: Resit Engineering Team
Latest version: 1.0.0

# Resit Engineering Rules CLI

A corporate CLI tool to bootstrap projects and install engineering rules for AI-assisted development tools like Windsurf, Cursor, Continue, and Claude Code.

## Features

- 🚀 **Easy Initialization**: Quickly set up engineering rules in any project
- 🔍 **Auto-Detection**: Automatically detects project type (Odoo, React, WordPress, Python, Ruby on Rails)
- 📦 **Modular Rules**: Combines base engineering rules with stack-specific guidelines
- 🔄 **Update Support**: Keep your rules up-to-date with the latest version
- 🏥 **Health Checks**: Verify your rules are properly configured
- 🎯 **Extensible**: Plugin-style architecture for adding new stacks and rules

## Installation

### Global Installation (Recommended)

```bash
npm install -g @resit/engineering-rules
```

### Local Installation

```bash
npm install --save-dev @resit/engineering-rules
```

## Usage

### Initialize Rules

Initialize engineering rules in your current project:

```bash
resit init
```

This command will:
1. Detect your project type (if possible)
2. Prompt you to select a stack if detection fails
3. If the stack has optional modules, prompt to select them (checkbox list)
4. Generate a `.windsurf` directory with:
   - `architecture.md` - Project architecture documentation
   - `prompts.md` - Helpful prompts for AI assistants
   - `rules/` - Folder containing:
     - `rules.md` - Combined engineering and stack-specific rules
     - Selected optional module folders/files (preserves folder structure)

### Check Rules Health

Verify that your engineering rules are properly configured:

```bash
resit doctor
```

This command checks for:
- Existence of `.windsurf` directory
- Presence of required files
- Unprocessed template variables
- Outdated rules

### Update Rules

Update your rules to the latest version:

```bash
resit update
```

This command will:
1. Detect your current stack from existing rules
2. Update all rule files to the latest version
3. Preserve your stack selection

### Show Version

Display the CLI version:

```bash
resit version
```

## Supported Stacks

- **Odoo** - Odoo ERP development
- **React** - React web applications
- **WordPress** - WordPress plugins and themes
- **Python** - Python applications
- **Ruby on Rails** - Ruby on Rails applications

## Project Structure

```
resit-engineering-rules/
├── src/
│   ├── cli.ts                 # Main CLI entry point
│   ├── commands/              # CLI commands
│   │   ├── init.ts
│   │   ├── doctor.ts
│   │   ├── update.ts
│   │   └── version.ts
│   ├── core/                  # Core modules
│   │   ├── ruleLoader.ts      # Loads and combines rules
│   │   ├── stackResolver.ts   # Detects and manages stacks
│   │   ├── templateEngine.ts  # Renders templates
│   │   └── types.ts           # TypeScript types
│   └── utils/                 # Utility modules
│       ├── logger.ts
│       └── fs.ts
├── rules/                     # Rule definitions
│   ├── base/                  # Base rules for all projects
│   │   ├── engineering.md
│   │   └── git.md
│   ├── stacks/                # Stack-specific rules
│   │   ├── odoo.md
│   │   ├── react.md
│   │   ├── wordpress.md
│   │   ├── python.md
│   │   └── ruby.md
│   └── modules/               # Optional modules (add your custom modules here)
│       ├── odoo-localization-chile/  # Directory module (multiple .md files)
│       │   ├── odoo-l10n-cl-overview.md
│       │   ├── odoo-l10n-cl-dte.md
│       │   └── odoo-l10n-cl-xml-templates.md
│       ├── odoo-pos.md        # Single file module
│       └── .gitkeep
├── templates/                 # Template files
│   └── windsurf/
│       ├── rules.md
│       ├── architecture.md
│       └── prompts.md
└── package.json
```

## Architecture

### Plugin-Style Design

The CLI uses a modular, plugin-style architecture that makes it easy to add new stacks and rules without modifying core code.

#### Adding a New Stack

1. Create a new rule file in `rules/stacks/`:

```bash
# Example: rules/stacks/nextjs.md
```

2. Add the stack to `StackResolver`:

```typescript
// src/core/stackResolver.ts
{
  id: 'nextjs',
  name: 'Next.js',
  description: 'Next.js applications',
  ruleFiles: ['nextjs.md'],
}
```

3. Add detection logic (optional):

```typescript
// src/core/stackResolver.ts
if (fs.existsSync(path.join(projectPath, 'next.config.js'))) {
  return 'nextjs';
}
```

#### Adding New Base Rules

Create a new markdown file in `rules/base/` and update `RuleLoader.loadBaseRules()` to include it.

#### Adding Optional Modules to a Stack

Optional modules allow you to add technology-specific rules that users can select during initialization. For example, Odoo projects can select modules for Chilean localization, POS, accounting, or government projects.

**Module formats supported:**

Modules can be either:
- **Single file**: `rules/modules/odoo-pos.md`
- **Directory with multiple files**: `rules/modules/odoo-localization-chile/` (containing multiple `.md` files)

**1. Create the module rules:**

**Option A - Single file module:**
```bash
# Simple module with all rules in one file
rules/modules/odoo-pos.md
```

**Option B - Directory module (recommended for complex modules):**
```bash
# Complex module with multiple organized files
rules/modules/odoo-localization-chile/
├── odoo-l10n-cl-overview.md
├── odoo-l10n-cl-dte.md
├── odoo-l10n-cl-xml-templates.md
└── odoo-l10n-cl-sii-integration.md
```

When using a directory, all `.md` files inside will be loaded and combined (sorted alphabetically).

**2. Add the module to the stack definition:**

```typescript
// src/core/stackResolver.ts
{
  id: 'odoo',
  name: 'Odoo',
  description: 'Odoo ERP development',
  ruleFiles: ['odoo.md'],
  optionalModules: [
    {
      id: 'odoo-localization-chile',
      name: 'Localización Chile',
      description: 'Reglas para localización chilena (facturación electrónica, DTE, etc.)',
      ruleFile: 'odoo-localization-chile.md',
    },
    {
      id: 'odoo-pos',
      name: 'Point of Sale (POS)',
      description: 'Reglas para desarrollo de módulos POS',
      ruleFile: 'odoo-pos.md',
    },
    // Add more modules as needed
  ],
}
```

**3. How it works:**

- During `resit init`, if a stack has optional modules, the CLI will prompt the user with a checkbox list
- Users can select one, multiple, or no optional modules
- Selected modules are loaded and appended to the generated rules
- The selection is tracked in the architecture.md file

**Example stacks with optional modules:**

- **Odoo**: Chilean localization, POS, Accounting, Government
- **Node.js/React**: Socket.IO, PostgreSQL, MongoDB
- **Python**: Django, FastAPI, Flask, SQLAlchemy

**Benefits:**

- Keep base stack rules clean and focused
- Allow project-specific customization
- Easy to extend without modifying core files
- Users only get the rules they need

### Core Modules

- **StackResolver**: Manages available stacks and auto-detects project types
- **RuleLoader**: Loads and combines base and stack-specific rules
- **TemplateEngine**: Renders templates with variables and generates output files

## Development

### Setup

```bash
# Clone the repository
git clone <repository-url>
cd resit-engineering-rules

# Install dependencies
npm install

# Build the project
npm run build

# Link for local testing
npm link
```

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run dev
```

### Testing Locally

After building and linking:

```bash
cd /path/to/test/project
resit init
```

## Publishing to npm

### Prerequisites

1. Create an npm account at https://www.npmjs.com
2. Login to npm:

```bash
npm login
```

### Publishing Steps

#### 1. Update Version

Update the version in `package.json`:

```bash
npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0
```

#### 2. Build the Project

```bash
npm run build
```

#### 3. Test the Package

```bash
# Test locally
npm link
cd /path/to/test/project
resit init

# Or test with npm pack
npm pack
npm install -g resit-engineering-rules-1.0.0.tgz
```

#### 4. Publish

```bash
# For scoped packages (recommended)
npm publish --access public

# For unscoped packages
npm publish
```

#### 5. Verify Publication

```bash
npm info @resit/engineering-rules
```

### Publishing Checklist

- [ ] All tests pass
- [ ] Version number updated
- [ ] CHANGELOG updated (if applicable)
- [ ] README is up-to-date
- [ ] Build succeeds without errors
- [ ] Package tested locally
- [ ] Git changes committed and pushed
- [ ] Published to npm
- [ ] Verified installation: `npm install -g @resit/engineering-rules`

## Continuous Deployment (Optional)

### Using GitHub Actions

Create `.github/workflows/publish.yml`:

```yaml
name: Publish to npm

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm run build
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

Add your npm token to GitHub Secrets as `NPM_TOKEN`.

## Maintenance

### Updating Rules

1. Edit rule files in `rules/base/` or `rules/stacks/`
2. Update version in `package.json`
3. Build and publish
4. Users can update with `resit update`

### Adding New Features

1. Create new command in `src/commands/`
2. Register command in `src/cli.ts`
3. Update README
4. Build and publish

## Contributing

### Adding New Stacks

We welcome contributions for new stack support! To add a new stack:

1. Create a rule file in `rules/stacks/[stack-name].md`
2. Follow the existing format and structure
3. Add detection logic to `StackResolver`
4. Update this README
5. Submit a pull request

### Improving Rules

To improve existing rules:

1. Edit the relevant markdown file
2. Ensure rules are clear and actionable
3. Test with AI assistants
4. Submit a pull request

## License

MIT

## Support

For issues, questions, or contributions, please visit the project repository.

## Roadmap

- [ ] Support for more stacks (Vue.js, Angular, Django, etc.)
- [ ] Custom rule templates
- [ ] Rule versioning and migration
- [ ] Integration with more AI tools
- [ ] Rule validation and linting
- [ ] Interactive rule customization
- [ ] Team-specific rule overrides