@raftlabs/raftstack 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/.claude/skills/backend/SKILL.md +802 -0
  2. package/.claude/skills/code-quality/SKILL.md +318 -0
  3. package/.claude/skills/database/SKILL.md +465 -0
  4. package/.claude/skills/react/SKILL.md +418 -0
  5. package/.claude/skills/seo/SKILL.md +446 -0
  6. package/LICENSE +21 -0
  7. package/README.md +291 -0
  8. package/dist/cli.d.ts +2 -0
  9. package/dist/cli.js +2009 -0
  10. package/dist/cli.js.map +1 -0
  11. package/package.json +69 -0
package/README.md ADDED
@@ -0,0 +1,291 @@
1
+ # RaftStack
2
+
3
+ A CLI tool for setting up Git hooks, commit conventions, and GitHub integration in your projects.
4
+
5
+ RaftStack automates the setup of development best practices including:
6
+ - **Git hooks** with Husky (pre-commit, commit-msg, pre-push)
7
+ - **Commit conventions** with Commitlint and cz-git
8
+ - **Code formatting** with lint-staged and Prettier
9
+ - **Branch naming** validation
10
+ - **GitHub workflows** for PR checks
11
+ - **CODEOWNERS** for automatic reviewer assignment
12
+ - **AI code review** integration (CodeRabbit, GitHub Copilot)
13
+
14
+ ## Installation
15
+
16
+ ```bash
17
+ # Using pnpm (recommended)
18
+ pnpm dlx @raftlabs/raftstack init
19
+
20
+ # Using npx
21
+ npx @raftlabs/raftstack init
22
+
23
+ # Or install globally
24
+ pnpm add -g @raftlabs/raftstack
25
+ raftstack init
26
+ ```
27
+
28
+ ## Quick Start
29
+
30
+ Run the interactive setup wizard in your project directory:
31
+
32
+ ```bash
33
+ raftstack init
34
+ ```
35
+
36
+ The wizard will:
37
+ 1. Detect your project type (NX, Turborepo, pnpm workspace, or single package)
38
+ 2. Ask about Asana task linking preferences
39
+ 3. Configure AI code review tools (optional)
40
+ 4. Set up CODEOWNERS for automatic PR reviewers
41
+ 5. Generate all configuration files
42
+
43
+ ## What Gets Generated
44
+
45
+ ### Git Hooks (via Husky)
46
+
47
+ | Hook | Purpose |
48
+ |------|---------|
49
+ | `pre-commit` | Runs lint-staged to format and lint staged files |
50
+ | `commit-msg` | Validates commit messages with Commitlint |
51
+ | `pre-push` | Validates branch naming conventions |
52
+
53
+ ### Configuration Files
54
+
55
+ | File | Purpose |
56
+ |------|---------|
57
+ | `.husky/*` | Git hooks |
58
+ | `commitlint.config.js` | Commit message validation rules |
59
+ | `.czrc` + `cz.config.js` | Interactive commit wizard configuration |
60
+ | `.lintstagedrc.js` | Pre-commit file processing rules |
61
+ | `.prettierrc` | Code formatting rules (if not already configured) |
62
+ | `.prettierignore` | Files to exclude from formatting |
63
+
64
+ ### GitHub Integration
65
+
66
+ | File | Purpose |
67
+ |------|---------|
68
+ | `.github/PULL_REQUEST_TEMPLATE.md` | PR template with checklist |
69
+ | `.github/workflows/pr-checks.yml` | CI workflow for PR validation |
70
+ | `.github/CODEOWNERS` | Automatic reviewer assignment |
71
+ | `.github/BRANCH_PROTECTION_SETUP.md` | Branch protection setup guide |
72
+
73
+ ### Documentation
74
+
75
+ | File | Purpose |
76
+ |------|---------|
77
+ | `CONTRIBUTING.md` | Developer contribution guide |
78
+
79
+ ## Commands
80
+
81
+ ### `raftstack init`
82
+
83
+ Interactive setup wizard that configures all tools.
84
+
85
+ ```bash
86
+ raftstack init
87
+ ```
88
+
89
+ ### `raftstack setup-protection`
90
+
91
+ Configure GitHub branch protection rules via the GitHub API.
92
+
93
+ ```bash
94
+ raftstack setup-protection
95
+ ```
96
+
97
+ **Requirements:**
98
+ - GitHub CLI (`gh`) installed and authenticated
99
+ - Admin access to the repository
100
+
101
+ ## After Setup
102
+
103
+ 1. **Install dependencies:**
104
+ ```bash
105
+ pnpm install
106
+ ```
107
+
108
+ 2. **Make commits using the interactive wizard:**
109
+ ```bash
110
+ pnpm commit
111
+ ```
112
+
113
+ 3. **Review the generated configuration** and customize as needed.
114
+
115
+ 4. **Set up branch protection** on GitHub (see `.github/BRANCH_PROTECTION_SETUP.md`).
116
+
117
+ ## Commit Convention
118
+
119
+ RaftStack enforces [Conventional Commits](https://www.conventionalcommits.org/):
120
+
121
+ ```
122
+ <type>(<scope>): <subject>
123
+
124
+ <body>
125
+
126
+ <footer>
127
+ ```
128
+
129
+ ### Commit Types
130
+
131
+ | Type | Description |
132
+ |------|-------------|
133
+ | `feat` | New feature |
134
+ | `fix` | Bug fix |
135
+ | `docs` | Documentation changes |
136
+ | `style` | Code style changes (formatting) |
137
+ | `refactor` | Code refactoring |
138
+ | `perf` | Performance improvements |
139
+ | `test` | Adding or updating tests |
140
+ | `build` | Build system changes |
141
+ | `ci` | CI configuration changes |
142
+ | `chore` | Other changes |
143
+ | `revert` | Reverting changes |
144
+
145
+ ### Example Commits
146
+
147
+ ```bash
148
+ # Feature
149
+ feat(auth): add social login support
150
+
151
+ # Bug fix
152
+ fix(api): handle null response from server
153
+
154
+ # With Asana link (if configured)
155
+ feat(dashboard): add usage analytics widget
156
+
157
+ Implements real-time usage tracking for the dashboard.
158
+
159
+ Asana: https://app.asana.com/0/workspace/task-id
160
+ ```
161
+
162
+ ## Branch Naming Convention
163
+
164
+ RaftStack validates branch names on push:
165
+
166
+ | Pattern | Example |
167
+ |---------|---------|
168
+ | `feature/*` | `feature/user-authentication` |
169
+ | `fix/*` | `fix/login-validation` |
170
+ | `hotfix/*` | `hotfix/security-patch` |
171
+ | `bugfix/*` | `bugfix/form-submission` |
172
+ | `release/*` | `release/v1.2.0` |
173
+ | `chore/*` | `chore/update-dependencies` |
174
+ | `docs/*` | `docs/api-reference` |
175
+ | `refactor/*` | `refactor/auth-module` |
176
+ | `test/*` | `test/user-service` |
177
+ | `ci/*` | `ci/github-actions` |
178
+
179
+ Protected branches: `main`, `master`, `develop`, `staging`, `production`
180
+
181
+ ## Project Type Detection
182
+
183
+ RaftStack automatically detects your project structure:
184
+
185
+ | Type | Detection |
186
+ |------|-----------|
187
+ | NX Monorepo | `nx.json` present |
188
+ | Turborepo | `turbo.json` present |
189
+ | pnpm Workspace | `pnpm-workspace.yaml` present |
190
+ | Single Package | Default when no monorepo config found |
191
+
192
+ ## Asana Integration
193
+
194
+ If you enable Asana integration, RaftStack will:
195
+ - Add Asana task link prompts to the commit wizard
196
+ - Include an Asana section in the PR template
197
+ - Show warnings (not errors) for commits without task links
198
+
199
+ **Note:** Task link validation is set to warning level by default. To make it required, edit `commitlint.config.js` and change the rule level from `1` to `2`.
200
+
201
+ ## AI Code Review
202
+
203
+ RaftStack supports optional AI code review integration:
204
+
205
+ - **CodeRabbit**: Generates `.coderabbit.yaml` configuration
206
+ - **GitHub Copilot**: Adds workflow for Copilot code review
207
+
208
+ ## Claude Code Skills
209
+
210
+ RaftStack bundles AI-assisted development skills for Claude Code. When initialized, these skills are copied to `.claude/skills/`:
211
+
212
+ | Skill | Purpose |
213
+ |-------|---------|
214
+ | `react` | React 19+ patterns, SOLID components, performance optimization |
215
+ | `backend` | Clean architecture for serverless/Hono/Express backends |
216
+ | `database` | PostgreSQL/Drizzle ORM schema design and indexing |
217
+ | `seo` | Technical SEO for Next.js/React applications |
218
+ | `code-quality` | Universal readability rules (30-line functions, naming, etc.) |
219
+
220
+ These skills automatically apply best practices when using Claude Code for development.
221
+
222
+ ## ESLint Configuration (Optional)
223
+
224
+ RaftStack can generate ESLint 9 flat config for projects without existing ESLint setup:
225
+
226
+ - **TypeScript support** with `typescript-eslint`
227
+ - **React support** auto-detected and configured
228
+ - **Modern flat config** format (ESLint 9+)
229
+ - **Skips** if ESLint is already configured
230
+
231
+ To add ESLint to the init flow, the generator automatically detects if ESLint is needed.
232
+
233
+ ## Requirements
234
+
235
+ - Node.js >= 18
236
+ - Git repository initialized
237
+ - Package manager: pnpm, npm, or yarn
238
+
239
+ ## Troubleshooting
240
+
241
+ ### Husky hooks not running
242
+
243
+ ```bash
244
+ # Reinstall husky
245
+ pnpm exec husky
246
+
247
+ # Make hooks executable
248
+ chmod +x .husky/*
249
+ ```
250
+
251
+ ### Commit validation failing
252
+
253
+ Check your commit message format:
254
+ ```bash
255
+ # Use the interactive wizard
256
+ pnpm commit
257
+
258
+ # Or ensure format: type(scope): subject
259
+ git commit -m "feat(auth): add login page"
260
+ ```
261
+
262
+ ### Branch name validation failing
263
+
264
+ Ensure your branch follows the naming convention:
265
+ ```bash
266
+ # Correct
267
+ git checkout -b feature/my-feature
268
+
269
+ # Incorrect
270
+ git checkout -b my-feature # Missing prefix
271
+ ```
272
+
273
+ ### Permission denied on hooks
274
+
275
+ ```bash
276
+ chmod +x .husky/pre-commit
277
+ chmod +x .husky/commit-msg
278
+ chmod +x .husky/pre-push
279
+ ```
280
+
281
+ ### Files not being formatted
282
+
283
+ Check your `.lintstagedrc.js` configuration and ensure the file patterns match your project structure.
284
+
285
+ ## Contributing
286
+
287
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
288
+
289
+ ## License
290
+
291
+ MIT
package/dist/cli.d.ts ADDED
@@ -0,0 +1,2 @@
1
+
2
+ export { }