create-bunspace 0.1.0

package/dist/templates/monorepo/CLAUDE.md

@@ -0,0 +1,164 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## CRITICAL: Development Guidelines
+
+**ALL development MUST follow the rules in `MUST-FOLLOW-GUIDELINES.md`**
+
+Before making ANY code changes, read and understand:
+- `/MUST-FOLLOW-GUIDELINES.md` - Source of truth for coding standards
+
+**Key Rules Overview:**
+- JSDoc completo profesional obligatorio
+- Result pattern siempre ({{SCOPE}}/utils/result)
+- Logging via {{SCOPE}}/utils/logger (NUNCA console.log)
+- Validacion con Arktype
+- Nomenclatura: prefijo I para interfaces
+- Estructura: src/types/ y src/utils/ con barrel exports
+- Async/await preferido sobre Promise chaining
+
+## Monorepo Stack
+
+This is a Bun-based monorepo for npm packages.
+
+**Core Stack:**
+- **Runtime**: Bun (package manager & runtime)
+- **Workspaces**: Bun workspaces (`workspace:*` protocol)
+- **Bundling**: Rolldown (`rolldown` v1.0.0-beta.58)
+- **Linting**: Oxlint (OxC-based linter)
+- **Formatting**: Prettier with `prettier-plugin-organize-imports`
+- **Type Checking**: TSGO (@typescript/native-preview v7.0.0-dev)
+- **Validation**: Arktype (schema validation)
+- **Versioning**: Changesets
+
+## Commands
+
+```bash
+# Development - all workspaces
+bun run dev          # Start dev mode for all packages
+
+# Build - all workspaces
+bun run build        # Build all packages
+
+# Type checking
+bun run typecheck    # Type check all packages
+
+# Linting (Oxlint only - no ESLint)
+bun run lint         # Run oxlint
+bun run lint:fix     # Auto-fix oxlint issues
+
+# Formatting (Prettier)
+bun run format       # Format all files
+bun run format:check # Check formatting
+
+# Clean everything
+bun run clean        # Remove node_modules, dist, .turbo
+
+# Changesets (versioning)
+bun run changeset              # Create a changeset
+bun run changeset:version      # Apply changesets and bump versions
+bun run changeset:publish      # Publish packages to npm
+```
+
+## Monorepo Structure
+
+```
+├── core/
+│   └── packages/
+│       ├── utils/              # Shared utilities package
+│       │   ├── src/
+│       │   │   ├── logger.ts   # Logging wrapper (@mks2508/better-logger)
+│       │   │   ├── result.ts   # Result wrapper (@mks2508/no-throw)
+│       │   │   └── index.ts    # Barrel export
+│       │   ├── rolldown.config.ts
+│       │   └── package.json
+│       └── main/               # Main library package
+│           ├── src/
+│           └── package.json    # Depends on utils via workspace:*
+└── apps/
+    └── example/                # Example app
+        └── package.json        # Depends on utils via workspace:*
+```
+
+**Workspace Pattern:**
+- Packages in `core/packages/*` and `apps/*` are auto-discovered
+- Internal dependencies use `"{{SCOPE}}/package": "workspace:*"`
+- Root `package.json` defines shared devDependencies
+
+## Shared Utilities Pattern
+
+The `{{SCOPE}}/utils` package provides shared wrappers:
+
+### Logger (`{{SCOPE}}/utils/logger`)
+
+Wrapper around `@mks2508/better-logger` with preset configured:
+```typescript
+import { createLogger } from '{{SCOPE}}/utils/logger';
+
+const log = createLogger('ComponentName');
+log.info('Message');
+log.success('Success!');
+```
+
+### Result (`{{SCOPE}}/utils/result`)
+
+Wrapper around `@mks2508/no-throw` with domain-specific error codes:
+```typescript
+import { ok, tryCatch, createAppError, type Result } from '{{SCOPE}}/utils/result';
+
+const result: Result<string> = ok('success');
+const error = createAppError('NetworkError', 'Failed to fetch');
+```
+
+## Tool Configuration Files
+
+### Root TypeScript/TSGO (`tsconfig.json`)
+- Target: ES2022, Module: ESNext
+- Strict mode enabled
+- `moduleResolution: "bundler"`
+- Key options: `verbatimModuleSyntax: true`, `declaration: true`
+- Compiler: TSGO (@typescript/native-preview) for faster type checking
+
+### Validation (Arktype)
+Schema validation using Arktype for performance:
+```typescript
+import { type } from 'arktype';
+
+export const OptionsSchema = type({
+  url: 'string',
+  timeout: 'number.optional',
+});
+
+const result = OptionsSchema(options);
+if (result instanceof type.errors) {
+  return err(result.summary());
+}
+```
+
+### Oxlint (`oxlint.json`)
+- Categories: `correctness`, `suspicious`, `perf`, `style` -> "warn"
+- `restriction` -> "off"
+- Env: `node`, `es2021`
+
+### Prettier (`.prettierrc`)
+- 100 char width, 2 spaces, single quotes
+- Plugin: `prettier-plugin-organize-imports`
+- Trailing commas: es5
+
+## Workspace Dependencies
+
+When adding a new package dependency:
+
+1. **For shared packages**: Add to appropriate `core/packages/*/package.json`
+2. **For workspace deps**: Use `"{{SCOPE}}/name": "workspace:*"`
+3. **For external deps**: Add to root `package.json` devDependencies if used across multiple packages
+
+```bash
+bun install              # Install/resolves workspace dependencies
+```
+
+## Build Output Patterns
+
+- **Rolldown**: Generates JS + sourcemaps, separate `tsc --emitDeclarationOnly` for types
+- Always ESM-first, CJS as optional compatibility layer

package/dist/templates/monorepo/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) {{YEAR}} {{AUTHOR}}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/templates/monorepo/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
+```
+{{NAME}}/
+├── 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 '{{SCOPE}}/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 `{{SCOPE}}/utils/result`:
+
+```typescript
+import {
+  ok,
+  tryCatch,
+  type Result
+} from '{{SCOPE}}/utils/result';
+import {
+  createAppError,
+  AppErrorCode
+} from '{{SCOPE}}/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/dist/templates/monorepo/README.md

@@ -0,0 +1,74 @@
+# mks-bun-monorepo
+
+[![Use this template](https://img.shields.io/badge/Use_this_template-📦-blue?logo=github)](https://github.com/MKS2508/mks-bun-monorepo/generate)
+
+> Modern Bun monorepo template for npm packages with TypeScript, workspaces, and best practices.
+
+## Quick Start
+
+Click "Use this template" to create a new repository, or use via CLI:
+
+```bash
+bun create bun-mono my-lib --template monorepo
+```
+
+## Features
+
+- **Bun Workspaces**: Fast package management with native workspaces
+- **TypeScript**: Strict mode with tsgo for lightning-fast type checking
+- **Code Quality**: Prettier + Oxlint for consistent formatting and linting
+- **Version Management**: Changesets for automated versioning and publishing
+- **Modern Tooling**: Better Logger, no-throw, arktype
+
+## Template Structure
+
+```
+my-monorepo/
+├── core/
+│   └── packages/          # Main packages (e.g., core library)
+├── apps/                  # Applications (examples, docs)
+└── package.json           # Workspace root
+```
+
+## Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `bun run dev` | Start all packages in dev mode |
+| `bun run build` | Build all packages |
+| `bun run typecheck` | Type-check with tsgo |
+| `bun run lint` | Lint with Oxlint |
+| `bun run format` | Format with Prettier |
+| `bun run changeset` | Create a changeset |
+| `bun run changeset:version` | Apply changesets and bump versions |
+| `bun run changeset:publish` | Publish packages to npm |
+
+## Placeholder Variables
+
+This template uses the following placeholders (auto-replaced by CLI):
+
+- `{{NAME}}` - Project name (e.g., "my-lib")
+- `{{SCOPE}}` - npm scope without @ (e.g., "my-org")
+- `{{DESCRIPTION}}` - Project description
+- `{{AUTHOR}}` - Author name
+- `{{YEAR}}` - Current year
+
+## Tech Stack
+
+| Tool | Version | Purpose |
+| ------ | ------- | ------- |
+| **Bun** | 1.3+ | Runtime & package manager |
+| **TypeScript** | 5.9+ | Language |
+| **tsgo** | native-preview | Type checking |
+| **Oxlint** | latest | Linting |
+| **Prettier** | 3.4+ | Formatting |
+| **Changesets** | latest | Version management |
+
+## Documentation
+
+- [CLAUDE.md](./CLAUDE.md) - Project documentation
+- [MUST-FOLLOW-GUIDELINES.md](./MUST-FOLLOW-GUIDELINES.md) - Development guidelines
+
+## License
+
+MIT

package/dist/templates/monorepo/SYNC_VERIFICATION.md

@@ -0,0 +1 @@
+# SYNC TEST 1767746400

package/dist/templates/monorepo/apps/example/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "{{SCOPE}}/example-app",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch src/index.ts",
+    "build": "bun build src/index.ts --outdir ./dist",
+    "typecheck": "tsgo --noEmit",
+    "start": "bun run dist/index.js"
+  },
+  "dependencies": {
+    "{{SCOPE}}/core": "workspace:*",
+    "{{SCOPE}}/utils": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5"
+  }
+}

package/dist/templates/monorepo/apps/example/src/index.ts

@@ -0,0 +1,23 @@
+import { greet, createGreeter } from '{{SCOPE}}/core';
+import { createLogger } from '{{SCOPE}}/utils/logger';
+
+const log = createLogger('Example');
+
+log.info('Starting example app...');
+
+// Simple greeting
+const result = greet('World');
+
+if (result.isOk()) {
+  log.success(result.value);
+}
+
+// Custom greeter
+const spanishGreeter = createGreeter({ prefix: 'Hola' });
+const spanishResult = spanishGreeter('Mundo');
+
+if (spanishResult.isOk()) {
+  log.success(spanishResult.value);
+}
+
+log.info('Example completed!');

package/dist/templates/monorepo/apps/example/src/types/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Tipos del ejemplo.
+ *
+ * @module
+ */
+
+export {};

package/dist/templates/monorepo/apps/example/src/utils/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Utilidades del ejemplo.
+ *
+ * @module
+ */
+
+export {};

package/dist/templates/monorepo/core/packages/main/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "{{SCOPE}}/core",
+  "version": "0.0.1",
+  "description": "{{DESCRIPTION}}",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "dev": "bun --watch src/index.ts",
+    "build": "rolldown --config rolldown.config.ts && tsgo --emitDeclarationOnly",
+    "typecheck": "tsgo --noEmit",
+    "lint": "oxlint",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "{{SCOPE}}/utils": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "rolldown": "^1.0.0-beta.58"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/dist/templates/monorepo/core/packages/main/rolldown.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from 'rolldown';
+
+export default defineConfig([
+  {
+    input: './src/index.ts',
+    output: {
+      dir: './dist',
+      format: 'esm',
+      exports: 'named',
+      sourcemap: true,
+    },
+    external: ['{{SCOPE}}/utils'],
+  },
+  {
+    input: './src/index.ts',
+    output: {
+      file: './dist/index.cjs',
+      format: 'cjs',
+      exports: 'named',
+      sourcemap: true,
+    },
+    external: ['{{SCOPE}}/utils'],
+  },
+]);