wiggum-cli 0.1.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 (236) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +341 -0
  3. package/bin/ralph.js +8 -0
  4. package/dist/ai/enhancer.d.ts +100 -0
  5. package/dist/ai/enhancer.d.ts.map +1 -0
  6. package/dist/ai/enhancer.js +233 -0
  7. package/dist/ai/enhancer.js.map +1 -0
  8. package/dist/ai/index.d.ts +8 -0
  9. package/dist/ai/index.d.ts.map +1 -0
  10. package/dist/ai/index.js +11 -0
  11. package/dist/ai/index.js.map +1 -0
  12. package/dist/ai/prompts.d.ts +26 -0
  13. package/dist/ai/prompts.d.ts.map +1 -0
  14. package/dist/ai/prompts.js +201 -0
  15. package/dist/ai/prompts.js.map +1 -0
  16. package/dist/ai/providers.d.ts +35 -0
  17. package/dist/ai/providers.d.ts.map +1 -0
  18. package/dist/ai/providers.js +104 -0
  19. package/dist/ai/providers.js.map +1 -0
  20. package/dist/cli.d.ts +6 -0
  21. package/dist/cli.d.ts.map +1 -0
  22. package/dist/cli.js +196 -0
  23. package/dist/cli.js.map +1 -0
  24. package/dist/commands/init.d.ts +16 -0
  25. package/dist/commands/init.d.ts.map +1 -0
  26. package/dist/commands/init.js +124 -0
  27. package/dist/commands/init.js.map +1 -0
  28. package/dist/commands/monitor.d.ts +17 -0
  29. package/dist/commands/monitor.d.ts.map +1 -0
  30. package/dist/commands/monitor.js +342 -0
  31. package/dist/commands/monitor.js.map +1 -0
  32. package/dist/commands/new.d.ts +19 -0
  33. package/dist/commands/new.d.ts.map +1 -0
  34. package/dist/commands/new.js +272 -0
  35. package/dist/commands/new.js.map +1 -0
  36. package/dist/commands/run.d.ts +16 -0
  37. package/dist/commands/run.d.ts.map +1 -0
  38. package/dist/commands/run.js +175 -0
  39. package/dist/commands/run.js.map +1 -0
  40. package/dist/generator/config.d.ts +59 -0
  41. package/dist/generator/config.d.ts.map +1 -0
  42. package/dist/generator/config.js +68 -0
  43. package/dist/generator/config.js.map +1 -0
  44. package/dist/generator/index.d.ts +64 -0
  45. package/dist/generator/index.d.ts.map +1 -0
  46. package/dist/generator/index.js +147 -0
  47. package/dist/generator/index.js.map +1 -0
  48. package/dist/generator/templates.d.ts +70 -0
  49. package/dist/generator/templates.d.ts.map +1 -0
  50. package/dist/generator/templates.js +296 -0
  51. package/dist/generator/templates.js.map +1 -0
  52. package/dist/generator/writer.d.ts +93 -0
  53. package/dist/generator/writer.d.ts.map +1 -0
  54. package/dist/generator/writer.js +213 -0
  55. package/dist/generator/writer.js.map +1 -0
  56. package/dist/index.d.ts +12 -0
  57. package/dist/index.d.ts.map +1 -0
  58. package/dist/index.js +17 -0
  59. package/dist/index.js.map +1 -0
  60. package/dist/scanner/detectors/core/framework.d.ts +11 -0
  61. package/dist/scanner/detectors/core/framework.d.ts.map +1 -0
  62. package/dist/scanner/detectors/core/framework.js +275 -0
  63. package/dist/scanner/detectors/core/framework.js.map +1 -0
  64. package/dist/scanner/detectors/core/packageManager.d.ts +11 -0
  65. package/dist/scanner/detectors/core/packageManager.d.ts.map +1 -0
  66. package/dist/scanner/detectors/core/packageManager.js +74 -0
  67. package/dist/scanner/detectors/core/packageManager.js.map +1 -0
  68. package/dist/scanner/detectors/core/styling.d.ts +12 -0
  69. package/dist/scanner/detectors/core/styling.d.ts.map +1 -0
  70. package/dist/scanner/detectors/core/styling.js +230 -0
  71. package/dist/scanner/detectors/core/styling.js.map +1 -0
  72. package/dist/scanner/detectors/core/testing.d.ts +12 -0
  73. package/dist/scanner/detectors/core/testing.d.ts.map +1 -0
  74. package/dist/scanner/detectors/core/testing.js +190 -0
  75. package/dist/scanner/detectors/core/testing.js.map +1 -0
  76. package/dist/scanner/detectors/data/api.d.ts +12 -0
  77. package/dist/scanner/detectors/data/api.d.ts.map +1 -0
  78. package/dist/scanner/detectors/data/api.js +261 -0
  79. package/dist/scanner/detectors/data/api.js.map +1 -0
  80. package/dist/scanner/detectors/data/database.d.ts +12 -0
  81. package/dist/scanner/detectors/data/database.d.ts.map +1 -0
  82. package/dist/scanner/detectors/data/database.js +213 -0
  83. package/dist/scanner/detectors/data/database.js.map +1 -0
  84. package/dist/scanner/detectors/data/orm.d.ts +12 -0
  85. package/dist/scanner/detectors/data/orm.d.ts.map +1 -0
  86. package/dist/scanner/detectors/data/orm.js +160 -0
  87. package/dist/scanner/detectors/data/orm.js.map +1 -0
  88. package/dist/scanner/detectors/frontend/formHandling.d.ts +12 -0
  89. package/dist/scanner/detectors/frontend/formHandling.d.ts.map +1 -0
  90. package/dist/scanner/detectors/frontend/formHandling.js +211 -0
  91. package/dist/scanner/detectors/frontend/formHandling.js.map +1 -0
  92. package/dist/scanner/detectors/frontend/stateManagement.d.ts +12 -0
  93. package/dist/scanner/detectors/frontend/stateManagement.d.ts.map +1 -0
  94. package/dist/scanner/detectors/frontend/stateManagement.js +221 -0
  95. package/dist/scanner/detectors/frontend/stateManagement.js.map +1 -0
  96. package/dist/scanner/detectors/frontend/uiComponents.d.ts +12 -0
  97. package/dist/scanner/detectors/frontend/uiComponents.d.ts.map +1 -0
  98. package/dist/scanner/detectors/frontend/uiComponents.js +285 -0
  99. package/dist/scanner/detectors/frontend/uiComponents.js.map +1 -0
  100. package/dist/scanner/detectors/infra/deployment.d.ts +12 -0
  101. package/dist/scanner/detectors/infra/deployment.d.ts.map +1 -0
  102. package/dist/scanner/detectors/infra/deployment.js +301 -0
  103. package/dist/scanner/detectors/infra/deployment.js.map +1 -0
  104. package/dist/scanner/detectors/infra/monorepo.d.ts +12 -0
  105. package/dist/scanner/detectors/infra/monorepo.d.ts.map +1 -0
  106. package/dist/scanner/detectors/infra/monorepo.js +219 -0
  107. package/dist/scanner/detectors/infra/monorepo.js.map +1 -0
  108. package/dist/scanner/detectors/mcp/mcpProject.d.ts +12 -0
  109. package/dist/scanner/detectors/mcp/mcpProject.d.ts.map +1 -0
  110. package/dist/scanner/detectors/mcp/mcpProject.js +154 -0
  111. package/dist/scanner/detectors/mcp/mcpProject.js.map +1 -0
  112. package/dist/scanner/detectors/mcp/mcpServers.d.ts +17 -0
  113. package/dist/scanner/detectors/mcp/mcpServers.d.ts.map +1 -0
  114. package/dist/scanner/detectors/mcp/mcpServers.js +193 -0
  115. package/dist/scanner/detectors/mcp/mcpServers.js.map +1 -0
  116. package/dist/scanner/detectors/services/analytics.d.ts +12 -0
  117. package/dist/scanner/detectors/services/analytics.d.ts.map +1 -0
  118. package/dist/scanner/detectors/services/analytics.js +236 -0
  119. package/dist/scanner/detectors/services/analytics.js.map +1 -0
  120. package/dist/scanner/detectors/services/auth.d.ts +12 -0
  121. package/dist/scanner/detectors/services/auth.d.ts.map +1 -0
  122. package/dist/scanner/detectors/services/auth.js +217 -0
  123. package/dist/scanner/detectors/services/auth.js.map +1 -0
  124. package/dist/scanner/detectors/services/email.d.ts +12 -0
  125. package/dist/scanner/detectors/services/email.d.ts.map +1 -0
  126. package/dist/scanner/detectors/services/email.js +211 -0
  127. package/dist/scanner/detectors/services/email.js.map +1 -0
  128. package/dist/scanner/detectors/services/payments.d.ts +12 -0
  129. package/dist/scanner/detectors/services/payments.d.ts.map +1 -0
  130. package/dist/scanner/detectors/services/payments.js +185 -0
  131. package/dist/scanner/detectors/services/payments.js.map +1 -0
  132. package/dist/scanner/detectors/utils.d.ts +160 -0
  133. package/dist/scanner/detectors/utils.d.ts.map +1 -0
  134. package/dist/scanner/detectors/utils.js +222 -0
  135. package/dist/scanner/detectors/utils.js.map +1 -0
  136. package/dist/scanner/index.d.ts +42 -0
  137. package/dist/scanner/index.d.ts.map +1 -0
  138. package/dist/scanner/index.js +282 -0
  139. package/dist/scanner/index.js.map +1 -0
  140. package/dist/scanner/registry.d.ts +43 -0
  141. package/dist/scanner/registry.d.ts.map +1 -0
  142. package/dist/scanner/registry.js +243 -0
  143. package/dist/scanner/registry.js.map +1 -0
  144. package/dist/scanner/types.d.ts +112 -0
  145. package/dist/scanner/types.d.ts.map +1 -0
  146. package/dist/scanner/types.js +6 -0
  147. package/dist/scanner/types.js.map +1 -0
  148. package/dist/templates/config/ralph.config.js.tmpl +38 -0
  149. package/dist/templates/guides/AGENTS.md.tmpl +100 -0
  150. package/dist/templates/guides/FRONTEND.md.tmpl +523 -0
  151. package/dist/templates/guides/PERFORMANCE.md.tmpl +264 -0
  152. package/dist/templates/guides/SECURITY.md.tmpl +100 -0
  153. package/dist/templates/prompts/PROMPT.md.tmpl +77 -0
  154. package/dist/templates/prompts/PROMPT_e2e.md.tmpl +234 -0
  155. package/dist/templates/prompts/PROMPT_feature.md.tmpl +83 -0
  156. package/dist/templates/prompts/PROMPT_review.md.tmpl +167 -0
  157. package/dist/templates/prompts/PROMPT_verify.md.tmpl +72 -0
  158. package/dist/templates/root/.gitignore.tmpl +5 -0
  159. package/dist/templates/root/LEARNINGS.md.tmpl +24 -0
  160. package/dist/templates/root/README.md.tmpl +61 -0
  161. package/dist/templates/scripts/feature-loop.sh.tmpl +267 -0
  162. package/dist/templates/scripts/loop.sh.tmpl +59 -0
  163. package/dist/templates/scripts/ralph-monitor.sh.tmpl +244 -0
  164. package/dist/templates/specs/README.md.tmpl +57 -0
  165. package/dist/templates/specs/_example.md.tmpl +71 -0
  166. package/dist/utils/config.d.ts +95 -0
  167. package/dist/utils/config.d.ts.map +1 -0
  168. package/dist/utils/config.js +148 -0
  169. package/dist/utils/config.js.map +1 -0
  170. package/dist/utils/header.d.ts +5 -0
  171. package/dist/utils/header.d.ts.map +1 -0
  172. package/dist/utils/header.js +15 -0
  173. package/dist/utils/header.js.map +1 -0
  174. package/dist/utils/logger.d.ts +11 -0
  175. package/dist/utils/logger.d.ts.map +1 -0
  176. package/dist/utils/logger.js +24 -0
  177. package/dist/utils/logger.js.map +1 -0
  178. package/package.json +44 -0
  179. package/src/ai/enhancer.ts +350 -0
  180. package/src/ai/index.ts +38 -0
  181. package/src/ai/prompts.ts +217 -0
  182. package/src/ai/providers.ts +136 -0
  183. package/src/cli.ts +255 -0
  184. package/src/commands/init.ts +149 -0
  185. package/src/commands/monitor.ts +412 -0
  186. package/src/commands/new.ts +312 -0
  187. package/src/commands/run.ts +214 -0
  188. package/src/generator/config.ts +116 -0
  189. package/src/generator/index.ts +227 -0
  190. package/src/generator/templates.ts +412 -0
  191. package/src/generator/writer.ts +293 -0
  192. package/src/index.ts +41 -0
  193. package/src/scanner/detectors/core/framework.ts +332 -0
  194. package/src/scanner/detectors/core/packageManager.ts +91 -0
  195. package/src/scanner/detectors/core/styling.ts +261 -0
  196. package/src/scanner/detectors/core/testing.ts +221 -0
  197. package/src/scanner/detectors/data/api.ts +303 -0
  198. package/src/scanner/detectors/data/database.ts +245 -0
  199. package/src/scanner/detectors/data/orm.ts +180 -0
  200. package/src/scanner/detectors/frontend/formHandling.ts +244 -0
  201. package/src/scanner/detectors/frontend/stateManagement.ts +261 -0
  202. package/src/scanner/detectors/frontend/uiComponents.ts +328 -0
  203. package/src/scanner/detectors/infra/deployment.ts +343 -0
  204. package/src/scanner/detectors/infra/monorepo.ts +251 -0
  205. package/src/scanner/detectors/mcp/mcpProject.ts +176 -0
  206. package/src/scanner/detectors/mcp/mcpServers.ts +237 -0
  207. package/src/scanner/detectors/services/analytics.ts +273 -0
  208. package/src/scanner/detectors/services/auth.ts +254 -0
  209. package/src/scanner/detectors/services/email.ts +244 -0
  210. package/src/scanner/detectors/services/payments.ts +213 -0
  211. package/src/scanner/detectors/utils.ts +251 -0
  212. package/src/scanner/index.ts +354 -0
  213. package/src/scanner/registry.ts +301 -0
  214. package/src/scanner/types.ts +152 -0
  215. package/src/templates/config/ralph.config.js.tmpl +38 -0
  216. package/src/templates/guides/AGENTS.md.tmpl +100 -0
  217. package/src/templates/guides/FRONTEND.md.tmpl +523 -0
  218. package/src/templates/guides/PERFORMANCE.md.tmpl +264 -0
  219. package/src/templates/guides/SECURITY.md.tmpl +100 -0
  220. package/src/templates/prompts/PROMPT.md.tmpl +77 -0
  221. package/src/templates/prompts/PROMPT_e2e.md.tmpl +234 -0
  222. package/src/templates/prompts/PROMPT_feature.md.tmpl +83 -0
  223. package/src/templates/prompts/PROMPT_review.md.tmpl +167 -0
  224. package/src/templates/prompts/PROMPT_verify.md.tmpl +72 -0
  225. package/src/templates/root/.gitignore.tmpl +5 -0
  226. package/src/templates/root/LEARNINGS.md.tmpl +24 -0
  227. package/src/templates/root/README.md.tmpl +61 -0
  228. package/src/templates/scripts/feature-loop.sh.tmpl +267 -0
  229. package/src/templates/scripts/loop.sh.tmpl +59 -0
  230. package/src/templates/scripts/ralph-monitor.sh.tmpl +244 -0
  231. package/src/templates/specs/README.md.tmpl +57 -0
  232. package/src/templates/specs/_example.md.tmpl +71 -0
  233. package/src/utils/config.ts +221 -0
  234. package/src/utils/header.ts +15 -0
  235. package/src/utils/logger.ts +28 -0
  236. package/tsconfig.json +19 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Ralph CLI Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,341 @@
1
+ # ralph-cli
2
+
3
+ **AI-powered feature development loop CLI** - Auto-detect your tech stack and generate intelligent development environments.
4
+
5
+ ```
6
+ ██████╗ █████╗ ██╗ ██████╗ ██╗ ██╗
7
+ ██╔══██╗ ██╔══██╗ ██║ ██╔══██╗ ██║ ██║
8
+ ██████╔╝ ███████║ ██║ ██████╔╝ ███████║
9
+ ██╔══██╗ ██╔══██║ ██║ ██╔═══╝ ██╔══██║
10
+ ██║ ██║ ██║ ██║ ███████╗ ██║ ██║ ██║
11
+ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝ ╚═╝ ╚═╝ ╚═╝
12
+ ```
13
+ *Simpson Yellow (#FED90F) branding*
14
+
15
+ ## Installation
16
+
17
+ ```bash
18
+ # Initialize in your project (recommended)
19
+ npx ralph-cli init
20
+
21
+ # Or install globally
22
+ npm install -g ralph-cli
23
+ ```
24
+
25
+ ## Quick Start
26
+
27
+ ```bash
28
+ # 1. Initialize Ralph in your project
29
+ npx ralph-cli init
30
+
31
+ # 2. Create a new feature specification
32
+ ralph new my-feature
33
+
34
+ # 3. Edit the spec file (opens in your editor)
35
+ ralph new my-feature --edit
36
+
37
+ # 4. Run the feature development loop
38
+ ralph run my-feature
39
+
40
+ # 5. Monitor progress in real-time
41
+ ralph monitor my-feature
42
+ ```
43
+
44
+ ## Commands
45
+
46
+ ### `ralph init`
47
+
48
+ Initialize Ralph in the current project. Scans your codebase to detect the tech stack and generates configuration files.
49
+
50
+ ```bash
51
+ ralph init [options]
52
+ ```
53
+
54
+ **Options:**
55
+ | Flag | Description |
56
+ |------|-------------|
57
+ | `--ai` | Enable AI-enhanced analysis for deeper insights |
58
+ | `--provider <name>` | AI provider: `anthropic`, `openai`, or `openrouter` (default: `anthropic`) |
59
+ | `-y, --yes` | Accept defaults and skip confirmations |
60
+
61
+ **Examples:**
62
+ ```bash
63
+ # Basic initialization with interactive prompts
64
+ ralph init
65
+
66
+ # Initialize with AI enhancement using Anthropic
67
+ ralph init --ai
68
+
69
+ # Initialize with OpenAI provider, skip confirmations
70
+ ralph init --ai --provider openai --yes
71
+ ```
72
+
73
+ ---
74
+
75
+ ### `ralph run <feature>`
76
+
77
+ Run the feature development loop for a specific feature. Executes the AI-driven implementation workflow.
78
+
79
+ ```bash
80
+ ralph run <feature> [options]
81
+ ```
82
+
83
+ **Options:**
84
+ | Flag | Description |
85
+ |------|-------------|
86
+ | `--worktree` | Use git worktree for isolation (enables parallel execution) |
87
+ | `--resume` | Resume an interrupted loop (reuses existing branch/worktree) |
88
+ | `--model <model>` | Claude model to use (e.g., `opus`, `sonnet`) |
89
+ | `--max-iterations <n>` | Maximum implementation iterations (default: 50) |
90
+ | `--max-e2e-attempts <n>` | Maximum E2E test retry attempts (default: 3) |
91
+
92
+ **Examples:**
93
+ ```bash
94
+ # Run the feature loop
95
+ ralph run user-authentication
96
+
97
+ # Run with git worktree isolation
98
+ ralph run payment-flow --worktree
99
+
100
+ # Resume an interrupted session
101
+ ralph run payment-flow --resume
102
+
103
+ # Use specific model with iteration limits
104
+ ralph run my-feature --model opus --max-iterations 30
105
+ ```
106
+
107
+ ---
108
+
109
+ ### `ralph monitor <feature>`
110
+
111
+ Launch the monitoring dashboard to track feature development progress in real-time.
112
+
113
+ ```bash
114
+ ralph monitor <feature> [options]
115
+ ```
116
+
117
+ **Options:**
118
+ | Flag | Description |
119
+ |------|-------------|
120
+ | `--interval <seconds>` | Refresh interval in seconds (default: 5) |
121
+ | `--bash` | Use bash script monitor instead of built-in |
122
+ | `--python` | Use Python TUI monitor (if available) |
123
+
124
+ **Examples:**
125
+ ```bash
126
+ # Monitor with default settings
127
+ ralph monitor user-authentication
128
+
129
+ # Monitor with faster refresh rate
130
+ ralph monitor my-feature --interval 2
131
+
132
+ # Use bash monitor script
133
+ ralph monitor my-feature --bash
134
+ ```
135
+
136
+ ---
137
+
138
+ ### `ralph new <feature>`
139
+
140
+ Create a new feature specification from template.
141
+
142
+ ```bash
143
+ ralph new <feature> [options]
144
+ ```
145
+
146
+ **Options:**
147
+ | Flag | Description |
148
+ |------|-------------|
149
+ | `-e, --edit` | Open in editor after creation |
150
+ | `--editor <editor>` | Editor to use (defaults to `$EDITOR` or `code`) |
151
+ | `-y, --yes` | Skip confirmation prompts |
152
+ | `-f, --force` | Force overwrite if file exists |
153
+
154
+ **Examples:**
155
+ ```bash
156
+ # Create a new spec with interactive prompts
157
+ ralph new user-dashboard
158
+
159
+ # Create and open in VS Code
160
+ ralph new user-dashboard --edit
161
+
162
+ # Create with vim, skip confirmations
163
+ ralph new user-dashboard --edit --editor vim --yes
164
+
165
+ # Overwrite existing spec
166
+ ralph new user-dashboard --force
167
+ ```
168
+
169
+ ## Generated Files Structure
170
+
171
+ After running `ralph init`, the following structure is created:
172
+
173
+ ```
174
+ .ralph/
175
+ ├── ralph.config.js # Main configuration file
176
+ ├── prompts/ # AI prompt templates
177
+ │ ├── PROMPT.md # Implementation prompt
178
+ │ ├── PROMPT_feature.md # Feature planning prompt
179
+ │ ├── PROMPT_e2e.md # E2E testing prompt
180
+ │ ├── PROMPT_verify.md # Verification prompt
181
+ │ └── PROMPT_review.md # PR review prompt
182
+ ├── scripts/ # Automation scripts
183
+ │ ├── feature-loop.sh # Main development loop
184
+ │ └── ralph-monitor.sh # Monitoring script
185
+ ├── specs/ # Feature specifications
186
+ │ └── _example.md # Example spec template
187
+ └── CLAUDE.md # Project context for Claude
188
+ ```
189
+
190
+ ## Detection Capabilities
191
+
192
+ Ralph automatically detects and configures support for:
193
+
194
+ ### Core
195
+ - **Frameworks:** Next.js (App/Pages Router), React, Vue, Nuxt, Svelte, SvelteKit, Remix, Astro
196
+ - **Package Managers:** npm, yarn, pnpm, bun
197
+ - **Testing:** Jest, Vitest (unit), Playwright, Cypress (E2E)
198
+ - **Styling:** Tailwind CSS, CSS Modules, Styled Components, Emotion, Sass
199
+
200
+ ### Data Layer
201
+ - **Databases:** PostgreSQL, MySQL, SQLite, MongoDB, Redis
202
+ - **ORMs:** Prisma, Drizzle, TypeORM, Mongoose, Kysely
203
+ - **APIs:** REST, GraphQL, tRPC, OpenAPI
204
+
205
+ ### Frontend
206
+ - **State Management:** Zustand, Jotai, Redux, Pinia, Recoil, MobX, Valtio
207
+ - **UI Components:** shadcn/ui, Radix, Material UI, Chakra UI, Ant Design, Headless UI
208
+ - **Form Handling:** React Hook Form, Formik, Zod, Yup
209
+
210
+ ### Services
211
+ - **Authentication:** NextAuth.js, Clerk, Auth0, Supabase Auth, Lucia, Better Auth
212
+ - **Analytics:** PostHog, Mixpanel, Amplitude, Google Analytics, Plausible
213
+ - **Payments:** Stripe, Paddle, LemonSqueezy
214
+ - **Email:** Resend, SendGrid, Postmark, Mailgun
215
+
216
+ ### Infrastructure
217
+ - **Deployment:** Vercel, Netlify, Railway, Fly.io, Docker, AWS
218
+ - **Monorepos:** Turborepo, Nx, Lerna, pnpm workspaces
219
+
220
+ ### MCP (Model Context Protocol)
221
+ - Detects existing MCP server configurations
222
+ - Identifies if project is an MCP server/client
223
+ - Recommends relevant MCP servers based on stack
224
+
225
+ ## AI Enhancement
226
+
227
+ Ralph supports AI-enhanced analysis for deeper project insights:
228
+
229
+ ```bash
230
+ ralph init --ai --provider anthropic
231
+ ```
232
+
233
+ ### Supported Providers
234
+
235
+ | Provider | Environment Variable | Description |
236
+ |----------|---------------------|-------------|
237
+ | Anthropic | `ANTHROPIC_API_KEY` | Claude models (recommended) |
238
+ | OpenAI | `OPENAI_API_KEY` | GPT models |
239
+ | OpenRouter | `OPENROUTER_API_KEY` | Multiple model providers |
240
+
241
+ ### AI Analysis Features
242
+
243
+ When AI enhancement is enabled, Ralph provides:
244
+ - **Architecture Analysis:** Understanding of project structure and patterns
245
+ - **Code Quality Insights:** Best practices and potential improvements
246
+ - **Dependency Review:** Security and update recommendations
247
+ - **Custom Recommendations:** Tailored suggestions for your stack
248
+
249
+ ## Configuration
250
+
251
+ ### ralph.config.js
252
+
253
+ ```javascript
254
+ export default {
255
+ // Project paths
256
+ paths: {
257
+ root: '.ralph',
258
+ specs: '.ralph/specs',
259
+ prompts: '.ralph/prompts',
260
+ scripts: '.ralph/scripts',
261
+ },
262
+
263
+ // Feature loop settings
264
+ loop: {
265
+ maxIterations: 10,
266
+ maxE2eAttempts: 5,
267
+ defaultModel: 'sonnet',
268
+ },
269
+
270
+ // AI settings
271
+ ai: {
272
+ provider: 'anthropic',
273
+ enhance: false,
274
+ },
275
+
276
+ // Detected stack (auto-populated)
277
+ stack: {
278
+ framework: { name: 'Next.js', version: '14.0.0' },
279
+ testing: {
280
+ unit: { name: 'Vitest' },
281
+ e2e: { name: 'Playwright' },
282
+ },
283
+ // ... other detected technologies
284
+ },
285
+ };
286
+ ```
287
+
288
+ ## Requirements
289
+
290
+ - Node.js 18.0.0 or higher
291
+ - Git (for worktree features)
292
+ - Claude Code CLI (for running the development loop)
293
+
294
+ ## Environment Variables
295
+
296
+ | Variable | Required | Description |
297
+ |----------|----------|-------------|
298
+ | `ANTHROPIC_API_KEY` | For AI features | Anthropic API key |
299
+ | `OPENAI_API_KEY` | For OpenAI provider | OpenAI API key |
300
+ | `OPENROUTER_API_KEY` | For OpenRouter provider | OpenRouter API key |
301
+ | `EDITOR` | Optional | Default editor for `--edit` flag |
302
+ | `DEBUG` | Optional | Enable debug logging |
303
+
304
+ ## Contributing
305
+
306
+ Contributions are welcome! Please read our contributing guidelines before submitting a pull request.
307
+
308
+ ### Development Setup
309
+
310
+ ```bash
311
+ # Clone the repository
312
+ git clone https://github.com/your-org/ralph-cli.git
313
+ cd ralph-cli
314
+
315
+ # Install dependencies
316
+ npm install
317
+
318
+ # Build the project
319
+ npm run build
320
+
321
+ # Run locally
322
+ node bin/ralph.js init
323
+ ```
324
+
325
+ ### Running Tests
326
+
327
+ ```bash
328
+ # Type checking
329
+ npx tsc --noEmit
330
+
331
+ # Run tests (when available)
332
+ npm test
333
+ ```
334
+
335
+ ## License
336
+
337
+ MIT License - see [LICENSE](LICENSE) for details.
338
+
339
+ ---
340
+
341
+ Built with Simpson Yellow (#FED90F) by the Ralph team.
package/bin/ralph.js ADDED
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { main } from '../dist/index.js';
4
+
5
+ main().catch((error) => {
6
+ console.error(error);
7
+ process.exit(1);
8
+ });
@@ -0,0 +1,100 @@
1
+ /**
2
+ * AI Enhancer Module
3
+ * Uses AI to analyze the codebase for deeper insights
4
+ */
5
+ import type { ScanResult } from '../scanner/types.js';
6
+ import { type AIProvider } from './providers.js';
7
+ /**
8
+ * Framework insights from AI analysis
9
+ */
10
+ export interface FrameworkInsights {
11
+ variant?: string;
12
+ confidence: 'high' | 'medium' | 'low';
13
+ notes?: string;
14
+ }
15
+ /**
16
+ * Architectural pattern detected by AI
17
+ */
18
+ export interface ArchitecturalPattern {
19
+ pattern: string;
20
+ confidence: 'high' | 'medium' | 'low';
21
+ evidence: string;
22
+ }
23
+ /**
24
+ * Coding convention detected by AI
25
+ */
26
+ export interface CodingConvention {
27
+ convention: string;
28
+ suggestion: string;
29
+ }
30
+ /**
31
+ * MCP server recommendation
32
+ */
33
+ export interface McpRecommendation {
34
+ name: string;
35
+ reason: string;
36
+ }
37
+ /**
38
+ * Additional detection suggestions
39
+ */
40
+ export interface AdditionalDetections {
41
+ possibleMissed?: string[];
42
+ refinements?: string[];
43
+ }
44
+ /**
45
+ * AI analysis result
46
+ */
47
+ export interface AIAnalysisResult {
48
+ frameworkInsights?: FrameworkInsights;
49
+ architecturalPatterns?: ArchitecturalPattern[];
50
+ codingConventions?: CodingConvention[];
51
+ recommendedMcpServers?: McpRecommendation[];
52
+ customPromptSuggestions?: string[];
53
+ additionalDetections?: AdditionalDetections;
54
+ }
55
+ /**
56
+ * Enhanced scan result with AI insights
57
+ */
58
+ export interface EnhancedScanResult extends ScanResult {
59
+ aiAnalysis?: AIAnalysisResult;
60
+ aiEnhanced: boolean;
61
+ aiProvider?: AIProvider;
62
+ aiError?: string;
63
+ }
64
+ /**
65
+ * Options for the AI enhancer
66
+ */
67
+ export interface EnhancerOptions {
68
+ provider?: AIProvider;
69
+ verbose?: boolean;
70
+ }
71
+ /**
72
+ * AI Enhancer class
73
+ * Provides AI-powered analysis to enhance scan results
74
+ */
75
+ export declare class AIEnhancer {
76
+ private provider;
77
+ private verbose;
78
+ constructor(options?: EnhancerOptions);
79
+ /**
80
+ * Check if AI enhancement is available
81
+ */
82
+ isAvailable(): boolean;
83
+ /**
84
+ * Get the required environment variable for the current provider
85
+ */
86
+ getRequiredEnvVar(): string;
87
+ /**
88
+ * Enhance scan results with AI analysis
89
+ */
90
+ enhance(scanResult: ScanResult): Promise<EnhancedScanResult>;
91
+ }
92
+ /**
93
+ * Convenience function to enhance scan results with AI
94
+ */
95
+ export declare function enhanceWithAI(scanResult: ScanResult, options?: EnhancerOptions): Promise<EnhancedScanResult>;
96
+ /**
97
+ * Format AI analysis result for display
98
+ */
99
+ export declare function formatAIAnalysis(analysis: AIAnalysisResult): string;
100
+ //# sourceMappingURL=enhancer.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"enhancer.d.ts","sourceRoot":"","sources":["../../src/ai/enhancer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAkC,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAY,KAAK,UAAU,EAA8B,MAAM,gBAAgB,CAAC;AAIvF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,qBAAqB,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAC/C,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACvC,qBAAqB,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC5C,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAyED;;;GAGG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,OAAO,CAAU;gBAEb,OAAO,GAAE,eAAoB;IAKzC;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,iBAAiB,IAAI,MAAM;IAI3B;;OAEG;IACG,OAAO,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAiEnE;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,UAAU,EACtB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,kBAAkB,CAAC,CAG7B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAoFnE"}
@@ -0,0 +1,233 @@
1
+ /**
2
+ * AI Enhancer Module
3
+ * Uses AI to analyze the codebase for deeper insights
4
+ */
5
+ import { generateText } from 'ai';
6
+ import { getModel, hasApiKey, getApiKeyEnvVar } from './providers.js';
7
+ import { SYSTEM_PROMPT, createAnalysisPrompt } from './prompts.js';
8
+ import { logger } from '../utils/logger.js';
9
+ /**
10
+ * Parse AI response JSON safely
11
+ */
12
+ function parseAIResponse(text) {
13
+ try {
14
+ // Try to extract JSON from the response
15
+ // The AI might wrap it in markdown code blocks
16
+ let jsonText = text;
17
+ // Remove markdown code blocks if present
18
+ const jsonMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/);
19
+ if (jsonMatch) {
20
+ jsonText = jsonMatch[1];
21
+ }
22
+ // Try to find JSON object
23
+ const objectMatch = jsonText.match(/\{[\s\S]*\}/);
24
+ if (objectMatch) {
25
+ jsonText = objectMatch[0];
26
+ }
27
+ return JSON.parse(jsonText);
28
+ }
29
+ catch (error) {
30
+ logger.warn('Failed to parse AI response as JSON');
31
+ return null;
32
+ }
33
+ }
34
+ /**
35
+ * Apply AI insights to enhance the detected stack
36
+ */
37
+ function applyEnhancements(stack, analysis) {
38
+ const enhanced = { ...stack };
39
+ // Enhance framework detection with AI insights
40
+ if (analysis.frameworkInsights && enhanced.framework) {
41
+ // If AI detected a more specific variant with high confidence
42
+ if (analysis.frameworkInsights.variant &&
43
+ analysis.frameworkInsights.confidence === 'high') {
44
+ enhanced.framework = {
45
+ ...enhanced.framework,
46
+ variant: analysis.frameworkInsights.variant,
47
+ evidence: [
48
+ ...enhanced.framework.evidence,
49
+ `AI: ${analysis.frameworkInsights.notes || 'variant detected'}`,
50
+ ],
51
+ };
52
+ }
53
+ }
54
+ // Enhance MCP recommendations
55
+ if (analysis.recommendedMcpServers && analysis.recommendedMcpServers.length > 0) {
56
+ const aiRecommended = analysis.recommendedMcpServers.map(r => r.name);
57
+ enhanced.mcp = {
58
+ ...enhanced.mcp,
59
+ recommended: [
60
+ ...(enhanced.mcp?.recommended || []),
61
+ ...aiRecommended.filter(r => !enhanced.mcp?.recommended?.includes(r)),
62
+ ],
63
+ };
64
+ }
65
+ return enhanced;
66
+ }
67
+ /**
68
+ * AI Enhancer class
69
+ * Provides AI-powered analysis to enhance scan results
70
+ */
71
+ export class AIEnhancer {
72
+ provider;
73
+ verbose;
74
+ constructor(options = {}) {
75
+ this.provider = options.provider || 'anthropic';
76
+ this.verbose = options.verbose || false;
77
+ }
78
+ /**
79
+ * Check if AI enhancement is available
80
+ */
81
+ isAvailable() {
82
+ return hasApiKey(this.provider);
83
+ }
84
+ /**
85
+ * Get the required environment variable for the current provider
86
+ */
87
+ getRequiredEnvVar() {
88
+ return getApiKeyEnvVar(this.provider);
89
+ }
90
+ /**
91
+ * Enhance scan results with AI analysis
92
+ */
93
+ async enhance(scanResult) {
94
+ // Check if API key is available
95
+ if (!this.isAvailable()) {
96
+ const envVar = this.getRequiredEnvVar();
97
+ return {
98
+ ...scanResult,
99
+ aiEnhanced: false,
100
+ aiError: `API key not found. Set ${envVar} to enable AI enhancement.`,
101
+ };
102
+ }
103
+ try {
104
+ // Get the configured model
105
+ const { model, provider, modelId } = getModel(this.provider);
106
+ if (this.verbose) {
107
+ logger.info(`Using AI provider: ${provider} (${modelId})`);
108
+ }
109
+ // Create the analysis prompt
110
+ const prompt = createAnalysisPrompt(scanResult);
111
+ // Call the AI model
112
+ const { text } = await generateText({
113
+ model,
114
+ system: SYSTEM_PROMPT,
115
+ prompt,
116
+ maxOutputTokens: 2000,
117
+ temperature: 0.3, // Lower temperature for more consistent output
118
+ });
119
+ // Parse the response
120
+ const analysis = parseAIResponse(text);
121
+ if (!analysis) {
122
+ return {
123
+ ...scanResult,
124
+ aiEnhanced: false,
125
+ aiProvider: this.provider,
126
+ aiError: 'Failed to parse AI analysis response',
127
+ };
128
+ }
129
+ // Apply enhancements to the stack
130
+ const enhancedStack = applyEnhancements(scanResult.stack, analysis);
131
+ return {
132
+ ...scanResult,
133
+ stack: enhancedStack,
134
+ aiAnalysis: analysis,
135
+ aiEnhanced: true,
136
+ aiProvider: this.provider,
137
+ };
138
+ }
139
+ catch (error) {
140
+ const errorMessage = error instanceof Error ? error.message : String(error);
141
+ logger.error(`AI enhancement failed: ${errorMessage}`);
142
+ return {
143
+ ...scanResult,
144
+ aiEnhanced: false,
145
+ aiProvider: this.provider,
146
+ aiError: errorMessage,
147
+ };
148
+ }
149
+ }
150
+ }
151
+ /**
152
+ * Convenience function to enhance scan results with AI
153
+ */
154
+ export async function enhanceWithAI(scanResult, options) {
155
+ const enhancer = new AIEnhancer(options);
156
+ return enhancer.enhance(scanResult);
157
+ }
158
+ /**
159
+ * Format AI analysis result for display
160
+ */
161
+ export function formatAIAnalysis(analysis) {
162
+ const lines = [];
163
+ lines.push('=== AI Analysis ===');
164
+ lines.push('');
165
+ // Framework insights
166
+ if (analysis.frameworkInsights) {
167
+ lines.push('Framework Insights:');
168
+ if (analysis.frameworkInsights.variant) {
169
+ lines.push(` Variant: ${analysis.frameworkInsights.variant}`);
170
+ }
171
+ lines.push(` Confidence: ${analysis.frameworkInsights.confidence}`);
172
+ if (analysis.frameworkInsights.notes) {
173
+ lines.push(` Notes: ${analysis.frameworkInsights.notes}`);
174
+ }
175
+ lines.push('');
176
+ }
177
+ // Architectural patterns
178
+ if (analysis.architecturalPatterns && analysis.architecturalPatterns.length > 0) {
179
+ lines.push('Architectural Patterns:');
180
+ for (const pattern of analysis.architecturalPatterns) {
181
+ lines.push(` - ${pattern.pattern} [${pattern.confidence}]`);
182
+ lines.push(` Evidence: ${pattern.evidence}`);
183
+ }
184
+ lines.push('');
185
+ }
186
+ // Coding conventions
187
+ if (analysis.codingConventions && analysis.codingConventions.length > 0) {
188
+ lines.push('Coding Conventions:');
189
+ for (const convention of analysis.codingConventions) {
190
+ lines.push(` - ${convention.convention}`);
191
+ lines.push(` Suggestion: ${convention.suggestion}`);
192
+ }
193
+ lines.push('');
194
+ }
195
+ // MCP recommendations
196
+ if (analysis.recommendedMcpServers && analysis.recommendedMcpServers.length > 0) {
197
+ lines.push('Recommended MCP Servers:');
198
+ for (const server of analysis.recommendedMcpServers) {
199
+ lines.push(` - ${server.name}`);
200
+ lines.push(` Reason: ${server.reason}`);
201
+ }
202
+ lines.push('');
203
+ }
204
+ // Custom prompt suggestions
205
+ if (analysis.customPromptSuggestions && analysis.customPromptSuggestions.length > 0) {
206
+ lines.push('Custom Prompt Suggestions:');
207
+ for (const suggestion of analysis.customPromptSuggestions) {
208
+ lines.push(` - ${suggestion}`);
209
+ }
210
+ lines.push('');
211
+ }
212
+ // Additional detections
213
+ if (analysis.additionalDetections) {
214
+ if (analysis.additionalDetections.possibleMissed &&
215
+ analysis.additionalDetections.possibleMissed.length > 0) {
216
+ lines.push('Possibly Missed Technologies:');
217
+ for (const tech of analysis.additionalDetections.possibleMissed) {
218
+ lines.push(` - ${tech}`);
219
+ }
220
+ lines.push('');
221
+ }
222
+ if (analysis.additionalDetections.refinements &&
223
+ analysis.additionalDetections.refinements.length > 0) {
224
+ lines.push('Detection Refinements:');
225
+ for (const refinement of analysis.additionalDetections.refinements) {
226
+ lines.push(` - ${refinement}`);
227
+ }
228
+ lines.push('');
229
+ }
230
+ }
231
+ return lines.join('\n');
232
+ }
233
+ //# sourceMappingURL=enhancer.js.map