stitch-forge 0.3.1

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 (145) hide show
  1. package/.claude/skills/forge-build/SKILL.md +79 -0
  2. package/.claude/skills/forge-design/SKILL.md +64 -0
  3. package/.claude/skills/forge-discover/SKILL.md +139 -0
  4. package/.claude/skills/forge-generate/SKILL.md +77 -0
  5. package/.claude/skills/forge-preview/SKILL.md +26 -0
  6. package/.claude/skills/forge-research/SKILL.md +42 -0
  7. package/.claude/skills/forge-sync/SKILL.md +45 -0
  8. package/DESIGN.md +113 -0
  9. package/LICENSE +21 -0
  10. package/README.es.md +242 -0
  11. package/README.md +242 -0
  12. package/dist/adapters/astro.d.ts +8 -0
  13. package/dist/adapters/astro.js +24 -0
  14. package/dist/adapters/astro.js.map +1 -0
  15. package/dist/adapters/index.d.ts +3 -0
  16. package/dist/adapters/index.js +9 -0
  17. package/dist/adapters/index.js.map +1 -0
  18. package/dist/adapters/nextjs.d.ts +7 -0
  19. package/dist/adapters/nextjs.js +136 -0
  20. package/dist/adapters/nextjs.js.map +1 -0
  21. package/dist/adapters/static.d.ts +7 -0
  22. package/dist/adapters/static.js +43 -0
  23. package/dist/adapters/static.js.map +1 -0
  24. package/dist/adapters/types.d.ts +22 -0
  25. package/dist/adapters/types.js +6 -0
  26. package/dist/adapters/types.js.map +1 -0
  27. package/dist/commands/build.d.ts +7 -0
  28. package/dist/commands/build.js +98 -0
  29. package/dist/commands/build.js.map +1 -0
  30. package/dist/commands/design.d.ts +3 -0
  31. package/dist/commands/design.js +39 -0
  32. package/dist/commands/design.js.map +1 -0
  33. package/dist/commands/discover.d.ts +9 -0
  34. package/dist/commands/discover.js +91 -0
  35. package/dist/commands/discover.js.map +1 -0
  36. package/dist/commands/generate.d.ts +7 -0
  37. package/dist/commands/generate.js +105 -0
  38. package/dist/commands/generate.js.map +1 -0
  39. package/dist/commands/init.d.ts +1 -0
  40. package/dist/commands/init.js +99 -0
  41. package/dist/commands/init.js.map +1 -0
  42. package/dist/commands/preview.d.ts +5 -0
  43. package/dist/commands/preview.js +41 -0
  44. package/dist/commands/preview.js.map +1 -0
  45. package/dist/commands/research.d.ts +1 -0
  46. package/dist/commands/research.js +38 -0
  47. package/dist/commands/research.js.map +1 -0
  48. package/dist/commands/sync.d.ts +1 -0
  49. package/dist/commands/sync.js +53 -0
  50. package/dist/commands/sync.js.map +1 -0
  51. package/dist/commands/workflow.d.ts +1 -0
  52. package/dist/commands/workflow.js +38 -0
  53. package/dist/commands/workflow.js.map +1 -0
  54. package/dist/index.d.ts +2 -0
  55. package/dist/index.js +113 -0
  56. package/dist/index.js.map +1 -0
  57. package/dist/mcp/auth.d.ts +15 -0
  58. package/dist/mcp/auth.js +56 -0
  59. package/dist/mcp/auth.js.map +1 -0
  60. package/dist/mcp/client.d.ts +65 -0
  61. package/dist/mcp/client.js +302 -0
  62. package/dist/mcp/client.js.map +1 -0
  63. package/dist/mcp/tools.d.ts +26 -0
  64. package/dist/mcp/tools.js +46 -0
  65. package/dist/mcp/tools.js.map +1 -0
  66. package/dist/research/business-researcher.d.ts +41 -0
  67. package/dist/research/business-researcher.js +888 -0
  68. package/dist/research/business-researcher.js.map +1 -0
  69. package/dist/research/crawler.d.ts +11 -0
  70. package/dist/research/crawler.js +56 -0
  71. package/dist/research/crawler.js.map +1 -0
  72. package/dist/research/design-synthesizer.d.ts +46 -0
  73. package/dist/research/design-synthesizer.js +628 -0
  74. package/dist/research/design-synthesizer.js.map +1 -0
  75. package/dist/research/differ.d.ts +19 -0
  76. package/dist/research/differ.js +58 -0
  77. package/dist/research/differ.js.map +1 -0
  78. package/dist/research/known-state.json +68 -0
  79. package/dist/research/research-cache.d.ts +6 -0
  80. package/dist/research/research-cache.js +62 -0
  81. package/dist/research/research-cache.js.map +1 -0
  82. package/dist/research/types.d.ts +98 -0
  83. package/dist/research/types.js +6 -0
  84. package/dist/research/types.js.map +1 -0
  85. package/dist/research/updater.d.ts +5 -0
  86. package/dist/research/updater.js +43 -0
  87. package/dist/research/updater.js.map +1 -0
  88. package/dist/templates/design-md.d.ts +52 -0
  89. package/dist/templates/design-md.js +315 -0
  90. package/dist/templates/design-md.js.map +1 -0
  91. package/dist/templates/prompts.d.ts +31 -0
  92. package/dist/templates/prompts.js +39 -0
  93. package/dist/templates/prompts.js.map +1 -0
  94. package/dist/templates/workflows.d.ts +9 -0
  95. package/dist/templates/workflows.js +21 -0
  96. package/dist/templates/workflows.js.map +1 -0
  97. package/dist/tui/App.d.ts +1 -0
  98. package/dist/tui/App.js +87 -0
  99. package/dist/tui/App.js.map +1 -0
  100. package/dist/tui/Dashboard.d.ts +5 -0
  101. package/dist/tui/Dashboard.js +23 -0
  102. package/dist/tui/Dashboard.js.map +1 -0
  103. package/dist/tui/DesignEditor.d.ts +6 -0
  104. package/dist/tui/DesignEditor.js +76 -0
  105. package/dist/tui/DesignEditor.js.map +1 -0
  106. package/dist/tui/PromptBuilder.d.ts +5 -0
  107. package/dist/tui/PromptBuilder.js +102 -0
  108. package/dist/tui/PromptBuilder.js.map +1 -0
  109. package/dist/tui/components/QuotaMeter.d.ts +8 -0
  110. package/dist/tui/components/QuotaMeter.js +10 -0
  111. package/dist/tui/components/QuotaMeter.js.map +1 -0
  112. package/dist/tui/components/ScreenCard.d.ts +7 -0
  113. package/dist/tui/components/ScreenCard.js +6 -0
  114. package/dist/tui/components/ScreenCard.js.map +1 -0
  115. package/dist/tui/components/Spinner.d.ts +5 -0
  116. package/dist/tui/components/Spinner.js +7 -0
  117. package/dist/tui/components/Spinner.js.map +1 -0
  118. package/dist/tui/components/StatusBar.d.ts +7 -0
  119. package/dist/tui/components/StatusBar.js +6 -0
  120. package/dist/tui/components/StatusBar.js.map +1 -0
  121. package/dist/utils/config.d.ts +26 -0
  122. package/dist/utils/config.js +66 -0
  123. package/dist/utils/config.js.map +1 -0
  124. package/dist/utils/design-validator.d.ts +44 -0
  125. package/dist/utils/design-validator.js +396 -0
  126. package/dist/utils/design-validator.js.map +1 -0
  127. package/dist/utils/logger.d.ts +8 -0
  128. package/dist/utils/logger.js +10 -0
  129. package/dist/utils/logger.js.map +1 -0
  130. package/dist/utils/output-validator.d.ts +18 -0
  131. package/dist/utils/output-validator.js +194 -0
  132. package/dist/utils/output-validator.js.map +1 -0
  133. package/dist/utils/preview.d.ts +4 -0
  134. package/dist/utils/preview.js +49 -0
  135. package/dist/utils/preview.js.map +1 -0
  136. package/dist/utils/prompt-enhancer.d.ts +21 -0
  137. package/dist/utils/prompt-enhancer.js +104 -0
  138. package/dist/utils/prompt-enhancer.js.map +1 -0
  139. package/dist/utils/quota.d.ts +18 -0
  140. package/dist/utils/quota.js +49 -0
  141. package/dist/utils/quota.js.map +1 -0
  142. package/dist/utils/validators.d.ts +125 -0
  143. package/dist/utils/validators.js +110 -0
  144. package/dist/utils/validators.js.map +1 -0
  145. package/package.json +77 -0
package/README.es.md ADDED
@@ -0,0 +1,242 @@
1
+ # Stitch Forge
2
+
3
+ [English](README.md) | [Español](README.es.md)
4
+
5
+ <p align="center">
6
+ <strong>Diseña sitios web con IA. Publicalos con un comando.</strong>
7
+ </p>
8
+
9
+ <p align="center">
10
+ <em>Stitch Forge convierte Google Stitch en un pipeline completo de diseño a deploy.<br>
11
+ Genera pantallas, construye sistemas de diseño y exporta a tu framework favorito — todo desde la terminal.</em>
12
+ </p>
13
+
14
+ <p align="center">
15
+ <img src="https://img.shields.io/badge/Claude_Code-000?style=flat&logo=anthropic&logoColor=white" alt="Claude Code">
16
+ <img src="https://img.shields.io/badge/Google_Stitch-4285F4?style=flat&logo=google&logoColor=white" alt="Google Stitch">
17
+ <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white" alt="TypeScript">
18
+ <img src="https://img.shields.io/badge/Node.js-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js">
19
+ <img src="https://img.shields.io/badge/Ink-FF4154?style=flat&logo=react&logoColor=white" alt="Ink">
20
+ <img src="https://img.shields.io/badge/Vitest-6E9F18?style=flat&logo=vitest&logoColor=white" alt="Vitest">
21
+ <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT">
22
+ </p>
23
+
24
+ ---
25
+
26
+ <p align="center">
27
+ <img src=".github/assets/hero-banner.jpg" alt="Stitch Forge — Landing page generada con IA" width="800">
28
+ </p>
29
+
30
+ <p align="center"><em>Esta landing page fue generada por Stitch Forge usando el pipeline completo. <a href="https://freptar0.github.io/stitch-forge/">Demo en vivo</a></em></p>
31
+
32
+ ---
33
+
34
+ ## Que es esto
35
+
36
+ Stitch Forge envuelve la API MCP de Google Stitch en un framework CLI que maneja el ciclo completo de diseño web generado por IA:
37
+
38
+ - **Investiga tu negocio** y genera un sistema de diseño a medida — el Agente de Inteligencia de Diseño entiende tu modelo de negocio antes de diseñar
39
+ - **Crea pantallas** con prompts guiados, validacion anti-slop y guardrails integrados
40
+ - **Previsualizacion instantanea** en tu navegador o directamente en Claude Code
41
+ - **Compila y exporta** a HTML estatico, Astro o Next.js
42
+ - **Rastrea tu cuota** y mantente dentro de los limites mensuales de Stitch
43
+ - **Auto-investigacion** de actualizaciones de Stitch para que tus herramientas nunca se queden obsoletas
44
+
45
+ > **Hecho para Claude Code.** Stitch Forge incluye 7 skills que convierten a Claude en tu copiloto de diseño. Genera un sitio web completo sin salir de la conversacion.
46
+
47
+ ## Funcionalidades
48
+
49
+ | Funcionalidad | Descripcion |
50
+ |---------------|-------------|
51
+ | **Agente de Inteligencia de Diseño** | Investiga tu negocio, analiza competidores, entiende tu audiencia y genera un DESIGN.md a medida — no boilerplate |
52
+ | **Conciencia de Modelo de Negocio** | Detecta si eres retail fisico, e-commerce, SaaS o servicio — previene generar patrones de pagina incorrectos |
53
+ | **Generador de DESIGN.md** | Especificacion de 8 secciones con validacion estricta (colores hex, tamaños rem, patrones, reglas anti-slop) |
54
+ | **Constructor de Prompts** | Framework zoom-out-zoom-in con guardrails: longitud, una pantalla, deteccion de vaguedad, alineacion de negocio |
55
+ | **Validacion Anti-Slop** | Puntua HTML generado 0-100, detecta fuentes AI-default, gradientes purple-blue, jerarquia de headings |
56
+ | **Build Multi-Framework** | Exporta a HTML estatico, Astro (via Stitch MCP) o Next.js App Router — con firma de Stitch Forge |
57
+ | **Preview en Vivo** | Abre pantallas en el navegador desde CLI, TUI, o visualiza inline en Claude Code |
58
+ | **TUI Interactiva** | Dashboard, compositor de prompts y editor de diseño — todo en la terminal |
59
+ | **Rastreo de Cuota** | Medidor visual para Flash (350/mes) y Pro (200/mes) |
60
+ | **Auto-Investigacion** | Rastrea docs, blog y foros de Stitch — compara contra estado conocido, actualiza base de conocimiento |
61
+ | **Resiliencia del Cliente MCP** | Reintentos con backoff exponencial, timeouts 30s/120s, mensajes de error amigables |
62
+
63
+ ## Inicio Rapido
64
+
65
+ ```bash
66
+ # Instalar globalmente
67
+ npm i -g stitch-forge
68
+
69
+ # O usar sin instalar
70
+ npx stitch-forge init
71
+
72
+ # Configurar
73
+ # Agrega tu STITCH_API_KEY de stitch.withgoogle.com > Settings > API Key
74
+
75
+ # Inicializar proyecto
76
+ forge init
77
+
78
+ # Investigar tu negocio y generar un sistema de diseño a medida
79
+ forge discover "Tu Empresa, industria, audiencia, estetica" --url https://tusitio.com
80
+
81
+ # Generar tu primera pantalla
82
+ forge generate "Landing page con hero, features y CTA"
83
+
84
+ # Previsualizarla
85
+ forge preview
86
+
87
+ # Compilar el sitio
88
+ forge build --framework static --auto
89
+ ```
90
+
91
+ ### Desde el Codigo Fuente
92
+
93
+ ```bash
94
+ git clone https://github.com/FReptar0/stitch-forge.git
95
+ cd stitch-forge && npm install
96
+ cp .env.example .env # Agrega tu STITCH_API_KEY
97
+ npm run build
98
+ npm link # Hace disponible el comando `forge` globalmente
99
+ ```
100
+
101
+ ## Como Funciona
102
+
103
+ ```
104
+ Nombre del negocio o brief
105
+
106
+
107
+ ┌──────────────────────┐
108
+ │ Agente de │ Investiga modelo de negocio, analiza sitio,
109
+ │ Inteligencia │ estudia competidores, entiende audiencia
110
+ └────────┬─────────────┘
111
+
112
+ ┌────────▼─────────────┐
113
+ │ DESIGN.md │ Sistema de diseño de 8 secciones + contexto de negocio
114
+ │ (con contexto biz) │ "NO es e-commerce — genera trafico a tiendas"
115
+ └────────┬─────────────┘
116
+
117
+ ┌────────▼─────────────┐
118
+ │ Constructor de │ Guardrails: longitud, una pantalla,
119
+ │ Prompts + MCP │ deteccion vaga, alineacion de negocio
120
+ └────────┬─────────────┘
121
+
122
+ ┌────┼────┐
123
+ ▼ ▼ ▼
124
+ Pantalla Preview Cuota
125
+ .html navegador tracker
126
+
127
+ ┌───▼──────────────────┐
128
+ │ Build Framework │ --framework static | astro | nextjs
129
+ │ + Firma Forge │ <!-- Built with Stitch Forge -->
130
+ └──────────────────────┘
131
+ ```
132
+
133
+ ## Uso
134
+
135
+ ### Comandos CLI
136
+
137
+ ```
138
+ forge init Configurar proyecto, auth y MCP
139
+ forge discover "brief..." [--url URL] Investigar negocio + generar DESIGN.md
140
+ forge design "brief..." Generar DESIGN.md desde brief (modo preset)
141
+ forge generate "descripcion..." Generar pantalla via Stitch
142
+ forge preview [nombre-pantalla] Abrir pantalla en navegador (--all para todas)
143
+ forge build --framework static Compilar sitio (static | astro | nextjs)
144
+ forge sync [project-id] Sincronizar pantallas desde Stitch
145
+ forge research Verificar actualizaciones de la API de Stitch
146
+ forge workflow [redesign|new-app] Mostrar workflow guiado paso a paso
147
+ forge quota Mostrar uso de cuota de generacion
148
+ forge tui Lanzar interfaz interactiva de terminal
149
+ ```
150
+
151
+ ### Skills para Claude Code
152
+
153
+ ```
154
+ /forge-discover → Investigar negocio + generar DESIGN.md a medida (recomendado)
155
+ /forge-design → Generar DESIGN.md desde un brief (modo preset)
156
+ /forge-generate → Generar pantallas con prompts guiados + guardrails
157
+ /forge-build → Compilar y exportar al framework elegido
158
+ /forge-preview → Previsualizar pantallas inline (imagen base64 via MCP)
159
+ /forge-research → Verificar actualizaciones de Stitch
160
+ /forge-sync → Sincronizar desde un proyecto de Stitch
161
+ ```
162
+
163
+ ## Configuracion MCP
164
+
165
+ Stitch Forge se conecta a Google Stitch via MCP. Agrega esto a tu `.mcp.json`:
166
+
167
+ ```json
168
+ {
169
+ "mcpServers": {
170
+ "stitch": {
171
+ "command": "npx",
172
+ "args": ["@_davideast/stitch-mcp", "proxy"],
173
+ "env": { "STITCH_API_KEY": "${STITCH_API_KEY}" }
174
+ }
175
+ }
176
+ }
177
+ ```
178
+
179
+ O conecta directamente a la API de Stitch:
180
+
181
+ ```json
182
+ {
183
+ "mcpServers": {
184
+ "stitch": {
185
+ "type": "http",
186
+ "url": "https://stitch.googleapis.com/mcp",
187
+ "headers": { "X-Goog-Api-Key": "${STITCH_API_KEY}" }
188
+ }
189
+ }
190
+ }
191
+ ```
192
+
193
+ > `forge init` crea este archivo automaticamente.
194
+
195
+ ## Estructura del Proyecto
196
+
197
+ ```
198
+ stitch-forge/
199
+ ├── src/
200
+ │ ├── index.ts # Entrada CLI (commander)
201
+ │ ├── commands/ # init, discover, design, generate, build, sync, research, preview
202
+ │ ├── adapters/ # Adaptadores de framework (static, astro, nextjs) + firma forge
203
+ │ ├── tui/ # Terminal UI con Ink (Dashboard, PromptBuilder, DesignEditor)
204
+ │ ├── mcp/ # Cliente MCP con retry, timeout, parsing de respuesta
205
+ │ ├── research/ # Investigador de negocios, sintetizador de diseño, crawler, cache
206
+ │ ├── templates/ # DESIGN.md (14 industrias × 6 esteticas), prompts, workflows
207
+ │ └── utils/ # Config, validadores, prompt enhancer, output validator, cuota
208
+ ├── tests/ # 121 tests — unitarios + integracion con fixtures
209
+ ├── .claude/skills/ # 7 skills para Claude Code (discover, design, generate, build, preview, research, sync)
210
+ ├── docs/ # Guia de diseño, guia de prompts, estado conocido
211
+ └── .github/workflows/ # CI (typecheck + tests)
212
+ ```
213
+
214
+ ## Desarrollo
215
+
216
+ ```bash
217
+ npm install # Instalar dependencias
218
+ npm run dev # Lanzar TUI en modo desarrollo
219
+ npm test # Ejecutar tests (modo watch)
220
+ npm run test:run # Ejecutar tests una vez (121 tests)
221
+ npm run typecheck # Verificar tipos sin compilar
222
+ npm run build # Compilar TypeScript a dist/
223
+ ```
224
+
225
+ ## Contribuir
226
+
227
+ Consulta [CONTRIBUTING.md](./CONTRIBUTING.md) para instrucciones de configuracion y lineamientos.
228
+
229
+ ## Licencia
230
+
231
+ [MIT](./LICENSE)
232
+
233
+ ## Autor
234
+
235
+ Creado por [Fernando Rodriguez Memije](https://fernandomemije.dev).
236
+
237
+ <p align="center">
238
+ <a href="https://fernandomemije.dev"><img src="https://img.shields.io/badge/fernandomemije.dev-000?style=for-the-badge&logo=safari&logoColor=white" alt="Sitio Web"></a>
239
+ <a href="https://www.linkedin.com/in/fernando-rm/"><img src="https://img.shields.io/badge/LinkedIn-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white" alt="LinkedIn"></a>
240
+ <a href="https://github.com/FReptar0"><img src="https://img.shields.io/badge/GitHub-000?style=for-the-badge&logo=github&logoColor=white" alt="GitHub"></a>
241
+ <a href="mailto:hi@fernandomemije.dev"><img src="https://img.shields.io/badge/Email-EA4335?style=for-the-badge&logo=gmail&logoColor=white" alt="Email"></a>
242
+ </p>
package/README.md ADDED
@@ -0,0 +1,242 @@
1
+ # Stitch Forge
2
+
3
+ [English](README.md) | [Español](README.es.md)
4
+
5
+ <p align="center">
6
+ <strong>Design websites with AI. Ship them with one command.</strong>
7
+ </p>
8
+
9
+ <p align="center">
10
+ <em>Stitch Forge turns Google Stitch into a full design-to-deploy pipeline.<br>
11
+ Generate screens, build design systems, and export to your favorite framework — all from the terminal.</em>
12
+ </p>
13
+
14
+ <p align="center">
15
+ <img src="https://img.shields.io/badge/Claude_Code-000?style=flat&logo=anthropic&logoColor=white" alt="Claude Code">
16
+ <img src="https://img.shields.io/badge/Google_Stitch-4285F4?style=flat&logo=google&logoColor=white" alt="Google Stitch">
17
+ <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white" alt="TypeScript">
18
+ <img src="https://img.shields.io/badge/Node.js-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js">
19
+ <img src="https://img.shields.io/badge/Ink-FF4154?style=flat&logo=react&logoColor=white" alt="Ink">
20
+ <img src="https://img.shields.io/badge/Vitest-6E9F18?style=flat&logo=vitest&logoColor=white" alt="Vitest">
21
+ <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT">
22
+ </p>
23
+
24
+ ---
25
+
26
+ <p align="center">
27
+ <img src=".github/assets/hero-banner.jpg" alt="Stitch Forge — AI-generated landing page" width="800">
28
+ </p>
29
+
30
+ <p align="center"><em>This landing page was generated by Stitch Forge using the full pipeline. <a href="https://freptar0.github.io/stitch-forge/">Live demo</a></em></p>
31
+
32
+ ---
33
+
34
+ ## What Is This
35
+
36
+ Stitch Forge wraps Google Stitch's MCP API into a CLI framework that handles the full lifecycle of AI-generated web design:
37
+
38
+ - **Research a business** and generate a tailored design system — the Design Intelligence Agent understands your business model before designing
39
+ - **Generate screens** with guided prompts, anti-slop validation, and built-in guardrails
40
+ - **Preview instantly** in your browser or inline in Claude Code
41
+ - **Build and export** to Static HTML, Astro, or Next.js
42
+ - **Track quota** and stay within Stitch's monthly generation limits
43
+ - **Auto-research** Stitch updates so your tooling never goes stale
44
+
45
+ > **Built for Claude Code.** Stitch Forge ships with 7 skills that turn Claude into your design co-pilot. Generate a full website without leaving the conversation.
46
+
47
+ ## Features
48
+
49
+ | Feature | Description |
50
+ |---------|-------------|
51
+ | **Design Intelligence Agent** | Researches your business, analyzes competitors, understands your audience, and generates a tailored DESIGN.md — not boilerplate |
52
+ | **Business Model Awareness** | Detects if you're physical retail, e-commerce, SaaS, or service — prevents generating the wrong page patterns |
53
+ | **DESIGN.md Generator** | 8-section design system with strict validation (hex colors, rem sizes, component patterns, anti-slop rules) |
54
+ | **Prompt Builder** | Zoom-out-zoom-in framework with guardrails: max length, single-screen, vague detection, business alignment |
55
+ | **Anti-Slop Validation** | Scores generated HTML 0-100, catches AI-default fonts, purple-blue gradients, heading hierarchy issues |
56
+ | **Multi-Framework Build** | Export to Static HTML, Astro (via Stitch MCP), or Next.js App Router — with Stitch Forge signature |
57
+ | **Live Preview** | Open screens in browser from CLI, TUI, or view inline via Claude Code |
58
+ | **Interactive TUI** | Dashboard, prompt composer, and design editor — all in the terminal |
59
+ | **Quota Tracking** | Visual meter for Flash (350/mo) and Pro (200/mo) generation limits |
60
+ | **Auto-Research** | Crawls Stitch docs, blog, and forums — diffs against known state, updates knowledge base |
61
+ | **MCP Client Resilience** | Retry with exponential backoff, 30s/120s timeouts, user-friendly error messages |
62
+
63
+ ## Quick Start
64
+
65
+ ```bash
66
+ # Install globally
67
+ npm i -g stitch-forge
68
+
69
+ # Or use without installing
70
+ npx stitch-forge init
71
+
72
+ # Configure
73
+ # Add your STITCH_API_KEY from stitch.withgoogle.com > Settings > API Key
74
+
75
+ # Initialize project
76
+ forge init
77
+
78
+ # Research your business and generate a tailored design system
79
+ forge discover "Your Company, industry, audience, aesthetic" --url https://yoursite.com
80
+
81
+ # Generate your first screen
82
+ forge generate "A landing page with hero, features, and CTA"
83
+
84
+ # Preview it
85
+ forge preview
86
+
87
+ # Build the site
88
+ forge build --framework static --auto
89
+ ```
90
+
91
+ ### From Source
92
+
93
+ ```bash
94
+ git clone https://github.com/FReptar0/stitch-forge.git
95
+ cd stitch-forge && npm install
96
+ cp .env.example .env # Add your STITCH_API_KEY
97
+ npm run build
98
+ npm link # Makes `forge` command available globally
99
+ ```
100
+
101
+ ## How It Works
102
+
103
+ ```
104
+ Business name or brief
105
+
106
+
107
+ ┌──────────────────────┐
108
+ │ Design Intelligence │ Research business model, analyze site,
109
+ │ Agent │ study competitors, understand audience
110
+ └────────┬─────────────┘
111
+
112
+ ┌────────▼─────────────┐
113
+ │ DESIGN.md │ 8-section design system + business context
114
+ │ (with biz context) │ "NOT e-commerce — drive foot traffic"
115
+ └────────┬─────────────┘
116
+
117
+ ┌────────▼─────────────┐
118
+ │ Prompt Builder │ Guardrails: length, single-screen,
119
+ │ + Stitch MCP │ vague detection, business alignment
120
+ └────────┬─────────────┘
121
+
122
+ ┌────┼────┐
123
+ ▼ ▼ ▼
124
+ Screen Preview Quota
125
+ .html browser tracker
126
+
127
+ ┌───▼──────────────────┐
128
+ │ Framework Build │ --framework static | astro | nextjs
129
+ │ + Forge Signature │ <!-- Built with Stitch Forge -->
130
+ └──────────────────────┘
131
+ ```
132
+
133
+ ## Usage
134
+
135
+ ### CLI Commands
136
+
137
+ ```
138
+ forge init Setup project, auth, and MCP config
139
+ forge discover "brief..." [--url URL] Research business + generate DESIGN.md
140
+ forge design "brief..." Generate DESIGN.md from brand brief (preset mode)
141
+ forge generate "description..." Generate a screen via Stitch
142
+ forge preview [screen-name] Open screen in browser (--all for all)
143
+ forge build --framework static Build site (static | astro | nextjs)
144
+ forge sync [project-id] Pull screens from Stitch project
145
+ forge research Check for Stitch API updates
146
+ forge workflow [redesign|new-app] Show guided step-by-step workflow
147
+ forge quota Show generation quota usage
148
+ forge tui Launch interactive terminal UI
149
+ ```
150
+
151
+ ### Claude Code Skills
152
+
153
+ ```
154
+ /forge-discover → Research business + generate tailored DESIGN.md (recommended)
155
+ /forge-design → Generate DESIGN.md from a brand brief (preset mode)
156
+ /forge-generate → Generate screens with guided prompts + guardrails
157
+ /forge-build → Build and export to your chosen framework
158
+ /forge-preview → Preview screens inline (base64 image via MCP)
159
+ /forge-research → Check for Stitch updates
160
+ /forge-sync → Pull latest from a Stitch project
161
+ ```
162
+
163
+ ## MCP Setup
164
+
165
+ Stitch Forge connects to Google Stitch via MCP. Add this to your `.mcp.json`:
166
+
167
+ ```json
168
+ {
169
+ "mcpServers": {
170
+ "stitch": {
171
+ "command": "npx",
172
+ "args": ["@_davideast/stitch-mcp", "proxy"],
173
+ "env": { "STITCH_API_KEY": "${STITCH_API_KEY}" }
174
+ }
175
+ }
176
+ }
177
+ ```
178
+
179
+ Or connect directly to the Stitch API:
180
+
181
+ ```json
182
+ {
183
+ "mcpServers": {
184
+ "stitch": {
185
+ "type": "http",
186
+ "url": "https://stitch.googleapis.com/mcp",
187
+ "headers": { "X-Goog-Api-Key": "${STITCH_API_KEY}" }
188
+ }
189
+ }
190
+ }
191
+ ```
192
+
193
+ > `forge init` creates this file automatically.
194
+
195
+ ## Project Structure
196
+
197
+ ```
198
+ stitch-forge/
199
+ ├── src/
200
+ │ ├── index.ts # CLI entry (commander)
201
+ │ ├── commands/ # init, discover, design, generate, build, sync, research, preview
202
+ │ ├── adapters/ # Framework adapters (static, astro, nextjs) + forge signature
203
+ │ ├── tui/ # Ink terminal UI (Dashboard, PromptBuilder, DesignEditor)
204
+ │ ├── mcp/ # MCP client with retry, timeout, response parsing
205
+ │ ├── research/ # Business researcher, design synthesizer, crawler, cache
206
+ │ ├── templates/ # DESIGN.md (14 industries × 6 aesthetics), prompts, workflows
207
+ │ └── utils/ # Config, validators, prompt enhancer, output validator, quota
208
+ ├── tests/ # 121 tests — unit + integration with fixtures
209
+ ├── .claude/skills/ # 7 Claude Code skills (discover, design, generate, build, preview, research, sync)
210
+ ├── docs/ # Design guide, prompting guide, known state
211
+ └── .github/workflows/ # CI (typecheck + tests)
212
+ ```
213
+
214
+ ## Development
215
+
216
+ ```bash
217
+ npm install # Install dependencies
218
+ npm run dev # Launch TUI in dev mode
219
+ npm test # Run tests (watch mode)
220
+ npm run test:run # Run tests once (121 tests)
221
+ npm run typecheck # Type-check without emitting
222
+ npm run build # Compile TypeScript to dist/
223
+ ```
224
+
225
+ ## Contributing
226
+
227
+ See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions and guidelines.
228
+
229
+ ## License
230
+
231
+ [MIT](./LICENSE)
232
+
233
+ ## Author
234
+
235
+ Built by [Fernando Rodriguez Memije](https://fernandomemije.dev).
236
+
237
+ <p align="center">
238
+ <a href="https://fernandomemije.dev"><img src="https://img.shields.io/badge/fernandomemije.dev-000?style=for-the-badge&logo=safari&logoColor=white" alt="Website"></a>
239
+ <a href="https://www.linkedin.com/in/fernando-rm/"><img src="https://img.shields.io/badge/LinkedIn-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white" alt="LinkedIn"></a>
240
+ <a href="https://github.com/FReptar0"><img src="https://img.shields.io/badge/GitHub-000?style=for-the-badge&logo=github&logoColor=white" alt="GitHub"></a>
241
+ <a href="mailto:hi@fernandomemije.dev"><img src="https://img.shields.io/badge/Email-EA4335?style=for-the-badge&logo=gmail&logoColor=white" alt="Email"></a>
242
+ </p>
@@ -0,0 +1,8 @@
1
+ import type { Framework, FrameworkAdapter, BuildContext, BuildResult } from './types.js';
2
+ import type { StitchMcpClient } from '../mcp/client.js';
3
+ export declare class AstroAdapter implements FrameworkAdapter {
4
+ readonly name: Framework;
5
+ private client;
6
+ constructor(client: StitchMcpClient);
7
+ build(context: BuildContext): Promise<BuildResult>;
8
+ }
@@ -0,0 +1,24 @@
1
+ export class AstroAdapter {
2
+ name = 'astro';
3
+ client;
4
+ constructor(client) {
5
+ this.client = client;
6
+ }
7
+ async build(context) {
8
+ const { projectId, screens } = context;
9
+ const routes = screens.map((screen) => ({
10
+ screenId: screen.screenId,
11
+ route: screen.route,
12
+ }));
13
+ const result = await this.client.buildSite(projectId, routes);
14
+ const files = result.pages.map((page) => page.route);
15
+ return {
16
+ files,
17
+ instructions: [
18
+ 'Your Astro site has been generated by Stitch.',
19
+ 'Follow the Stitch build output instructions to preview and deploy.',
20
+ ],
21
+ };
22
+ }
23
+ }
24
+ //# sourceMappingURL=astro.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"astro.js","sourceRoot":"","sources":["../../src/adapters/astro.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,YAAY;IACd,IAAI,GAAc,OAAO,CAAC;IAC3B,MAAM,CAAkB;IAEhC,YAAY,MAAuB;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,OAAqB;QAC/B,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAEvC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACtC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC,CAAC,CAAC;QAEJ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAE9D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAErD,OAAO;YACL,KAAK;YACL,YAAY,EAAE;gBACZ,+CAA+C;gBAC/C,oEAAoE;aACrE;SACF,CAAC;IACJ,CAAC;CACF"}
@@ -0,0 +1,3 @@
1
+ import type { Framework, FrameworkAdapter } from './types.js';
2
+ export declare function getAdapter(framework: Exclude<Framework, 'astro'>): FrameworkAdapter;
3
+ export type { Framework, FrameworkAdapter, ScreenData, BuildContext, BuildResult } from './types.js';
@@ -0,0 +1,9 @@
1
+ import { StaticAdapter } from './static.js';
2
+ import { NextjsAdapter } from './nextjs.js';
3
+ export function getAdapter(framework) {
4
+ switch (framework) {
5
+ case 'static': return new StaticAdapter();
6
+ case 'nextjs': return new NextjsAdapter();
7
+ }
8
+ }
9
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,UAAU,UAAU,CAAC,SAAsC;IAC/D,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,QAAQ,CAAC,CAAC,OAAO,IAAI,aAAa,EAAE,CAAC;QAC1C,KAAK,QAAQ,CAAC,CAAC,OAAO,IAAI,aAAa,EAAE,CAAC;IAC5C,CAAC;AACH,CAAC"}
@@ -0,0 +1,7 @@
1
+ import { type Framework, type FrameworkAdapter, type BuildContext, type BuildResult } from './types.js';
2
+ export declare class NextjsAdapter implements FrameworkAdapter {
3
+ readonly name: Framework;
4
+ build(context: BuildContext): Promise<BuildResult>;
5
+ private routeToPagePath;
6
+ private escapeTemplateLiteral;
7
+ }