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.
- package/.claude/skills/forge-build/SKILL.md +79 -0
- package/.claude/skills/forge-design/SKILL.md +64 -0
- package/.claude/skills/forge-discover/SKILL.md +139 -0
- package/.claude/skills/forge-generate/SKILL.md +77 -0
- package/.claude/skills/forge-preview/SKILL.md +26 -0
- package/.claude/skills/forge-research/SKILL.md +42 -0
- package/.claude/skills/forge-sync/SKILL.md +45 -0
- package/DESIGN.md +113 -0
- package/LICENSE +21 -0
- package/README.es.md +242 -0
- package/README.md +242 -0
- package/dist/adapters/astro.d.ts +8 -0
- package/dist/adapters/astro.js +24 -0
- package/dist/adapters/astro.js.map +1 -0
- package/dist/adapters/index.d.ts +3 -0
- package/dist/adapters/index.js +9 -0
- package/dist/adapters/index.js.map +1 -0
- package/dist/adapters/nextjs.d.ts +7 -0
- package/dist/adapters/nextjs.js +136 -0
- package/dist/adapters/nextjs.js.map +1 -0
- package/dist/adapters/static.d.ts +7 -0
- package/dist/adapters/static.js +43 -0
- package/dist/adapters/static.js.map +1 -0
- package/dist/adapters/types.d.ts +22 -0
- package/dist/adapters/types.js +6 -0
- package/dist/adapters/types.js.map +1 -0
- package/dist/commands/build.d.ts +7 -0
- package/dist/commands/build.js +98 -0
- package/dist/commands/build.js.map +1 -0
- package/dist/commands/design.d.ts +3 -0
- package/dist/commands/design.js +39 -0
- package/dist/commands/design.js.map +1 -0
- package/dist/commands/discover.d.ts +9 -0
- package/dist/commands/discover.js +91 -0
- package/dist/commands/discover.js.map +1 -0
- package/dist/commands/generate.d.ts +7 -0
- package/dist/commands/generate.js +105 -0
- package/dist/commands/generate.js.map +1 -0
- package/dist/commands/init.d.ts +1 -0
- package/dist/commands/init.js +99 -0
- package/dist/commands/init.js.map +1 -0
- package/dist/commands/preview.d.ts +5 -0
- package/dist/commands/preview.js +41 -0
- package/dist/commands/preview.js.map +1 -0
- package/dist/commands/research.d.ts +1 -0
- package/dist/commands/research.js +38 -0
- package/dist/commands/research.js.map +1 -0
- package/dist/commands/sync.d.ts +1 -0
- package/dist/commands/sync.js +53 -0
- package/dist/commands/sync.js.map +1 -0
- package/dist/commands/workflow.d.ts +1 -0
- package/dist/commands/workflow.js +38 -0
- package/dist/commands/workflow.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +113 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp/auth.d.ts +15 -0
- package/dist/mcp/auth.js +56 -0
- package/dist/mcp/auth.js.map +1 -0
- package/dist/mcp/client.d.ts +65 -0
- package/dist/mcp/client.js +302 -0
- package/dist/mcp/client.js.map +1 -0
- package/dist/mcp/tools.d.ts +26 -0
- package/dist/mcp/tools.js +46 -0
- package/dist/mcp/tools.js.map +1 -0
- package/dist/research/business-researcher.d.ts +41 -0
- package/dist/research/business-researcher.js +888 -0
- package/dist/research/business-researcher.js.map +1 -0
- package/dist/research/crawler.d.ts +11 -0
- package/dist/research/crawler.js +56 -0
- package/dist/research/crawler.js.map +1 -0
- package/dist/research/design-synthesizer.d.ts +46 -0
- package/dist/research/design-synthesizer.js +628 -0
- package/dist/research/design-synthesizer.js.map +1 -0
- package/dist/research/differ.d.ts +19 -0
- package/dist/research/differ.js +58 -0
- package/dist/research/differ.js.map +1 -0
- package/dist/research/known-state.json +68 -0
- package/dist/research/research-cache.d.ts +6 -0
- package/dist/research/research-cache.js +62 -0
- package/dist/research/research-cache.js.map +1 -0
- package/dist/research/types.d.ts +98 -0
- package/dist/research/types.js +6 -0
- package/dist/research/types.js.map +1 -0
- package/dist/research/updater.d.ts +5 -0
- package/dist/research/updater.js +43 -0
- package/dist/research/updater.js.map +1 -0
- package/dist/templates/design-md.d.ts +52 -0
- package/dist/templates/design-md.js +315 -0
- package/dist/templates/design-md.js.map +1 -0
- package/dist/templates/prompts.d.ts +31 -0
- package/dist/templates/prompts.js +39 -0
- package/dist/templates/prompts.js.map +1 -0
- package/dist/templates/workflows.d.ts +9 -0
- package/dist/templates/workflows.js +21 -0
- package/dist/templates/workflows.js.map +1 -0
- package/dist/tui/App.d.ts +1 -0
- package/dist/tui/App.js +87 -0
- package/dist/tui/App.js.map +1 -0
- package/dist/tui/Dashboard.d.ts +5 -0
- package/dist/tui/Dashboard.js +23 -0
- package/dist/tui/Dashboard.js.map +1 -0
- package/dist/tui/DesignEditor.d.ts +6 -0
- package/dist/tui/DesignEditor.js +76 -0
- package/dist/tui/DesignEditor.js.map +1 -0
- package/dist/tui/PromptBuilder.d.ts +5 -0
- package/dist/tui/PromptBuilder.js +102 -0
- package/dist/tui/PromptBuilder.js.map +1 -0
- package/dist/tui/components/QuotaMeter.d.ts +8 -0
- package/dist/tui/components/QuotaMeter.js +10 -0
- package/dist/tui/components/QuotaMeter.js.map +1 -0
- package/dist/tui/components/ScreenCard.d.ts +7 -0
- package/dist/tui/components/ScreenCard.js +6 -0
- package/dist/tui/components/ScreenCard.js.map +1 -0
- package/dist/tui/components/Spinner.d.ts +5 -0
- package/dist/tui/components/Spinner.js +7 -0
- package/dist/tui/components/Spinner.js.map +1 -0
- package/dist/tui/components/StatusBar.d.ts +7 -0
- package/dist/tui/components/StatusBar.js +6 -0
- package/dist/tui/components/StatusBar.js.map +1 -0
- package/dist/utils/config.d.ts +26 -0
- package/dist/utils/config.js +66 -0
- package/dist/utils/config.js.map +1 -0
- package/dist/utils/design-validator.d.ts +44 -0
- package/dist/utils/design-validator.js +396 -0
- package/dist/utils/design-validator.js.map +1 -0
- package/dist/utils/logger.d.ts +8 -0
- package/dist/utils/logger.js +10 -0
- package/dist/utils/logger.js.map +1 -0
- package/dist/utils/output-validator.d.ts +18 -0
- package/dist/utils/output-validator.js +194 -0
- package/dist/utils/output-validator.js.map +1 -0
- package/dist/utils/preview.d.ts +4 -0
- package/dist/utils/preview.js +49 -0
- package/dist/utils/preview.js.map +1 -0
- package/dist/utils/prompt-enhancer.d.ts +21 -0
- package/dist/utils/prompt-enhancer.js +104 -0
- package/dist/utils/prompt-enhancer.js.map +1 -0
- package/dist/utils/quota.d.ts +18 -0
- package/dist/utils/quota.js +49 -0
- package/dist/utils/quota.js.map +1 -0
- package/dist/utils/validators.d.ts +125 -0
- package/dist/utils/validators.js +110 -0
- package/dist/utils/validators.js.map +1 -0
- 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,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
|
+
}
|