create-bunspace 0.1.1 → 0.2.0

package/templates/fumadocs/MUST-FOLLOW-GUIDELINES.md

@@ -0,0 +1,269 @@
+# MUST-FOLLOW-GUIDELINES.md
+
+> **IMPORTANTE**: Este documento es la fuente de verdad para todas las reglas de desarrollo en este proyecto.
+> **El incumplimiento de estas reglas sera motivo de correccion obligatoria en code review.**
+
+---
+
+## Stack Definitivo
+
+| Herramienta | Version/Configuracion | Uso |
+|-------------|----------------------|-----|
+| **Runtime** | Bun v1.1.43+ | Package manager + runtime |
+| **Bundling** | Rolldown v1.0.0-beta.58 | Build de packages |
+| **Type Checking** | TSGO v7.0.0-dev (@typescript/native-preview) | TypeScript compiler |
+| **Linting** | Oxlint v0.11.1 | Linting rapido (OxC-based) |
+| **Formatting** | Prettier v3.4.2 + organize-imports | Formato de codigo |
+| **Validation** | Arktype | Validacion de esquemas |
+| **Versioning** | Changesets v2.27.11 | Versionado de packages |
+| **Logging** | @mks2508/better-logger v4.0.0 | Logging estructurado |
+| **Error Handling** | @mks2508/no-throw v0.1.0 | Result pattern |
+
+---
+
+## Estructura de Carpetas Obligatoria
+
+### Root del Monorepo
+```
+mks-fumadocs-template/
+├── docs/                    # Documentacion del proyecto
+├── tools/                   # Scripts y herramientas de desarrollo
+├── core/
+│   └── packages/
+│       ├── main/
+│       └── utils/
+└── apps/
+    └── example/
+```
+
+### Estructura de un Package
+```
+core/packages/main/
+├── src/
+│   ├── utils/               # Utilidades locales del package
+│   │   └── index.ts         # Barrel export
+│   ├── types/               # Tipos del dominio del package
+│   │   ├── *.types.ts       # Tipos especificos
+│   │   ├── constants.ts     # Constantes del package
+│   │   └── index.ts         # Barrel export
+│   ├── *.ts                 # Codigo fuente principal
+│   └── index.ts             # Export principal
+├── dist/                    # Build output
+├── package.json
+├── rolldown.config.ts
+└── tsconfig.json
+```
+
+---
+
+## REGLA 1: JSDoc Completo Profesional
+
+### Requerimientos Obligatorios
+
+TODA funcion, clase, metodo, interface, type, y constante exportada DEBE tener JSDoc completo:
+
+```typescript
+/**
+ * Descripcion clara y concisa de que hace y por que.
+ *
+ * @example
+ * ```typescript
+ * // Codigo ejecutable que demuestra uso tipico
+ * const result = await myFunction('example');
+ * if (result.isErr()) {
+ *   log.error('Failed', result.error);
+ *   return;
+ * }
+ * console.log(result.value);
+ * ```
+ *
+ * @param paramName - Descripcion del parametro
+ * @returns Result<T, E> Descripcion del valor de retorno
+ * @throws {AppError} Cuando y por que se lanza este error
+ * @see {@link IOptions} Referencias a tipos relacionados
+ */
+export async function myFunction(
+  param: string,
+  options?: IOptions
+): Promise<Result<string, AppError>> {
+  // ...
+}
+```
+
+### Tags Obligatorios
+
+| Tag | Cuando usar | Formato |
+|-----|-------------|---------|
+| `@description` | Siempre | Primera linea (implicita) |
+| `@param` | Cada parametro | `@param name - Description` |
+| `@returns` | Siempre | `@returns Type - Description` |
+| `@example` | Funciones publicas | Codigo TypeScript ejecutable |
+| `@throws` | Si puede lanzar | `@throws {ErrorType} Cuando` |
+| `@see` | Referencias | `@see {@link ISomething}` |
+
+---
+
+## REGLA 2: Logging - NUNCA console.log
+
+### Obligatorio
+
+```typescript
+import { createLogger } from 'mks-fumadocs-template/utils/logger';
+
+const log = createLogger('MyComponent');
+
+// CORRECTO
+log.info('Started');
+log.success('Completed');
+log.warn('High memory usage');
+log.error('Failed to connect', { error });
+log.critical('System failure');
+```
+
+### Prohibido
+
+```typescript
+// INCORRECTO
+console.log('Started');
+console.error('Failed');
+console.info('Info');
+console.warn('Warning');
+```
+
+---
+
+## REGLA 3: Result Pattern - SIEMPRE
+
+### Obligatorio
+
+TODA operacion que pueda fallar DEBE usar `Result<T, E>` del package `mks-fumadocs-template/utils/result`:
+
+```typescript
+import {
+  ok,
+  tryCatch,
+  type Result
+} from 'mks-fumadocs-template/utils/result';
+import {
+  createAppError,
+  AppErrorCode
+} from 'mks-fumadocs-template/utils/result';
+
+async function fetchData(
+  url: string
+): Promise<Result<string, AppError>> {
+  const result = await tryCatch(
+    async () => {
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+      return await response.text();
+    },
+    AppErrorCode.NetworkError
+  );
+
+  if (result.isErr()) {
+    return createAppError(
+      AppErrorCode.NetworkError,
+      `Failed to fetch from ${url}`,
+      result.error
+    );
+  }
+
+  return ok(result.value);
+}
+```
+
+---
+
+## REGLA 4: Nomenclatura - Prefijo I
+
+### Interfaces
+
+```typescript
+// CORRECTO - Prefijo I
+export interface IOptions {
+  url: string;
+  timeout?: number;
+}
+
+export interface ICallback {
+  onSuccess: () => void;
+  onError: (error: Error) => void;
+}
+```
+
+### Types (sin prefijo)
+
+```typescript
+// CORRECTO - Sin prefijo
+export type Options = {
+  url: string;
+  timeout?: number;
+};
+
+export type ErrorCode =
+  | 'NETWORK_ERROR'
+  | 'NOT_FOUND'
+  | 'PERMISSION_DENIED';
+```
+
+---
+
+## REGLA 5: Barrel Exports - SIEMPRE
+
+TODA carpeta con multiples archivos DEBE tener un `index.ts` que exporte todo:
+
+```typescript
+// src/types/index.ts
+export * from './main.types';
+export * from './constants';
+```
+
+---
+
+## REGLA 6: Async/Await - Preferencia
+
+```typescript
+// CORRECTO - Async/await
+async function processFile(path: string): Promise<void> {
+  const content = await readFile(path);
+  const processed = await transform(content);
+  await writeFile(path, processed);
+}
+
+// INCORRECTO - Promise chaining
+function processFile(path: string) {
+  return readFile(path)
+    .then(content => transform(content))
+    .then(processed => writeFile(path, processed));
+}
+```
+
+---
+
+## Checklist Pre-Commit
+
+Antes de hacer commit de codigo, verificar:
+
+- [ ] Todo codigo nuevo tiene JSDoc completo
+- [ ] No hay `console.log/debug/error/info/warn`
+- [ ] Todo lo que puede fallar usa `Result<T, E>`
+- [ ] Interfaces tienen prefijo `I`
+- [ ] Barrel exports en todas las carpetas
+- [ ] Async/await en lugar de Promise chaining
+- [ ] `bun run typecheck` pasa
+- [ ] `bun run lint` pasa
+- [ ] `bun run format` aplicado
+
+---
+
+## Fuentes de Referencia
+
+- **CLAUDE.md** - Guia de arquitectura del monorepo
+- **@mks2508/better-logger** - Documentacion del logger
+- **@mks2508/no-throw** - Documentacion del Result pattern
+- **Arktype** - https://arktype.io/
+- **Rolldown** - https://rollup.rs/
+- **Oxlint** - https://oxlint.com/

package/templates/fumadocs/README.md

@@ -0,0 +1,319 @@
+# {{PROJECT_NAME}} - Documentation Template
+
+> {{DESCRIPTION}}
+
+## 🚀 Quick Start
+
+Este es un template de documentación basado en **Fumadocs** (Next.js + MDX) listo para usar con:
+
+- ✅ Soporte bilingüe (Español/Inglés)
+- ✅ Búsqueda integrada
+- ✅ Tema oscuro/claro automático
+- ✅ GitHub Pages ready
+- ✅ MDX con componentes de React
+- ✅ Pipeline de CI/CD configurado
+
+## 📋 Requisitos Previos
+
+- **Bun** v1.1.43+ (recomendado) o Node.js v20+
+- **GitHub** (para despliegue)
+
+## 🔧 Instalación
+
+### Opción 1: Usando mks-scaffolder (Recomendado)
+
+```bash
+bunx mks-scaffolder create mi-proyecto --template fumadocs
+```
+
+Sigue las instrucciones interactivas para configurar tu proyecto.
+
+### Opción 2: Manual
+
+```bash
+git clone https://github.com/{{GITHUB_REPO}}.git mi-proyecto
+cd mi-proyecto
+bun install
+```
+
+## ⚙️ Configuración
+
+### 1. Variables de Entorno
+
+Crea `.env.local` en la raíz:
+
+```bash
+# Copia el template
+cp .env.example .env.local
+
+# Edita con tus valores
+PROJECT_NAME=Mi Proyecto
+DESCRIPTION=Descripción de mi proyecto
+AUTHOR=Tu Nombre
+BASE_PATH=/mi-proyecto
+```
+
+### 2. Contenido Placeholder
+
+El template incluye contenido de ejemplo en `content-template/`:
+
+```
+content-template/
+├── docs/
+│   ├── index.mdx                    # Página principal (ES)
+│   └── getting-started/
+│       ├── index.mdx
+│       ├── installation.mdx
+│       └── quick-start.mdx
+└── en/docs/                         # Versión en inglés
+    └── (misma estructura)
+```
+
+**Para usarlo:**
+
+```bash
+# Opción A: Copiar todo el contenido
+cp -r content-template/* content/
+
+# Opción B: Copiar solo lo que necesitas
+# Los archivos usan variables {{PLACEHOLDER}} que debes reemplazar
+```
+
+### 3. Reemplazar Placeholders
+
+Los archivos de contenido usan **placeholders** que debes reemplazar:
+
+- `{{PROJECT_NAME}}` - Nombre de tu proyecto
+- `{{DESCRIPTION}}` - Descripción del proyecto
+- `{{AUTHOR}}` - Tu nombre
+- `{{GITHUB_REPO}}` - `usuario/repo`
+- `{{BASE_PATH}}` - Path para GitHub Pages
+
+**Ejemplo de búsqueda y reemplazo:**
+
+```bash
+# Con sed (Linux/macOS)
+find content/ -type f -name "*.mdx" -exec sed -i '' 's/{{PROJECT_NAME}}/Mi Proyecto/g' {} +
+find content/ -type f -name "*.mdx" -exec sed -i '' 's/{{DESCRIPTION}}/Mi descripción/g' {} +
+
+# O edita manualmente cada archivo
+```
+
+## 🏃 Desarrollo
+
+```bash
+# Instalar dependencias
+bun install
+
+# Servidor de desarrollo
+bun run dev
+
+# Build para producción
+bun run build
+
+# Previsualizar build
+bun run start
+```
+
+Abre [http://localhost:3000](http://localhost:3000).
+
+## 🚀 Deploy a GitHub Pages
+
+### Pipeline Automático
+
+El template incluye un workflow de GitHub Actions en `.github/workflows/deploy.yml` que:
+
+1. ✅ Se ejecuta en cada push a `main`
+2. ✅ Build del sitio con `bun run build`
+3. ✅ Deploy automático a GitHub Pages
+4. ✅ Soporte para rutas con `basePath`
+
+### Configuración del Repositorio
+
+1. **Activa GitHub Pages:**
+   - Ve a `Settings` > `Pages`
+   - Source: `GitHub Actions`
+
+2. **Configura `BASE_PATH`:**
+   - Si tu repo es `usuario/mi-proyecto`, usa `/mi-proyecto`
+   - Si usas dominio custom, usa `/`
+
+3. **Push a main:**
+   ```bash
+   git add .
+   git commit -m "feat: initial docs"
+   git push origin main
+   ```
+
+4. **Espera el workflow:**
+   - Ve a la pestaña `Actions`
+   - Espera a que el workflow termine
+   - Tu documentación estará en `https://usuario.github.io/mi-proyecto/`
+
+## 📁 Estructura del Proyecto
+
+```
+.
+├── content/                  # Tu documentación (MDX)
+│   ├── docs/                # Versión en español
+│   └── en/docs/             # Versión en inglés
+├── content-template/        # Contenido placeholder (ejemplos)
+├── messages/                # Traducciones de la UI
+│   ├── es.json
+│   └── en.json
+├── src/
+│   ├── app/                # Next.js app directory
+│   ├── components/         # Componentes React reutilizables
+│   ├── config/             # Configuración centralizada
+│   │   └── site.config.ts  # Configuración del sitio
+│   └── lib/                # Utilidades y configuración
+├── public/                 # Archivos estáticos
+├── .github/workflows/      # Workflows de CI/CD
+│   └── deploy.yml         # Deploy automático a GH Pages
+├── .env.example            # Template de variables de entorno
+├── next.config.mjs         # Configuración de Next.js
+└── package.json
+```
+
+## 🎨 Personalización
+
+### Configuración del Sitio
+
+Edita `src/config/site.config.ts` o usa variables de entorno:
+
+```typescript
+// src/config/site.config.ts
+export const siteConfig = {
+  name: process.env.PROJECT_NAME || 'Mi Documentación',
+  description: process.env.DESCRIPTION || 'Descripción',
+  author: process.env.AUTHOR || 'Autor',
+  // ...
+};
+```
+
+### Logo
+
+Opción 1: SVG en `.env.local`:
+
+```bash
+LOGO_SVG='<svg viewBox="0 0 24 24">...</svg>'
+```
+
+Opción 2: Texto:
+
+```bash
+LOGO_TEXT="Mi Proyecto"
+```
+
+Opción 3: Editar `src/lib/layout.shared.tsx` directamente.
+
+### Colores
+
+Edita `src/app/global.css`:
+
+```css
+:root {
+  --color-primary: #0088cc;  /* Tu color primario */
+  --color-dark: #0f172a;
+  --color-light: #ffffff;
+}
+```
+
+## 📝 Escribir Contenido
+
+### Formato MDX
+
+Los archivos usan **frontmatter** obligatorio:
+
+```mdx
+---
+title: Título de la Página
+description: Descripción para SEO
+---
+
+# Contenido aquí
+
+Puedes usar **markdown** estándar y componentes de React.
+```
+
+### Componentes Disponibles
+
+```mdx
+import { Callout, Steps, Tabs } from 'fumadocs-ui/components';
+
+<Callout type="info">
+  Información importante
+</Callout>
+
+<Steps>
+### Paso 1
+### Paso 2
+</Steps>
+
+<Tabs items={['Tab 1', 'Tab 2']}>
+  <Tab>Contenido 1</Tab>
+  <Tab>Contenido 2</Tab>
+</Tabs>
+```
+
+## 🌍 i18n (Internacionalización)
+
+### Agregar idiomas
+
+1. Agrega el archivo de traducción en `messages/`:
+
+```json
+// messages/fr.json
+{
+  "nav": {
+    "gettingStarted": "Pour Commencer"
+  }
+}
+```
+
+2. Actualiza `.env.local`:
+
+```bash
+NEXT_PUBLIC_SUPPORTED_LOCALES=es,en,fr
+```
+
+### Traducir contenido
+
+Crea la estructura equivalente en `content/fr/docs/`.
+
+## 📚 Recursos
+
+- [Fumadocs Documentation](https://fumadocs.vercel.app/)
+- [Fumadocs UI Components](https://fumadocs.vercel.app/ui)
+- [Next.js Documentation](https://nextjs.org/docs)
+- [MDX Documentation](https://mdxjs.com/)
+
+## 🐛 Troubleshooting
+
+### Build falla
+
+```bash
+# Limpia cache
+rm -rf .next out node_modules bun.lockb
+bun install
+bun run build
+```
+
+### GitHub Pages retorna 404
+
+- Verifica que `BASE_PATH` en `.env.local` coincida con tu repo name
+- Activa GitHub Pages desde `GitHub Actions` (no desde `Deploy from a branch`)
+- Espera unos minutos después del deploy
+
+### Buscador no funciona
+
+- Verifica que `src/app/api/search/route.ts` existe
+- Rebuild después de agregar contenido nuevo
+
+## 📄 Licencia
+
+MIT
+
+---
+
+**Generado con [mks-fumadocs-template](https://github.com/mks2508/mks-fumadocs-template)**

package/templates/fumadocs/biome.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": [
+      "**",
+      "!node_modules",
+      "!.next",
+      "!dist",
+      "!build",
+      "!.source"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    },
+    "domains": {
+      "next": "recommended",
+      "react": "recommended"
+    }
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}