feat: basalt 0.0.1

README.md

@@ -1,2 +1,160 @@
-# keystone
+# Keystone
 
+A powerful CLI tool for bootstrapping Go API projects with best practices built-in. Keystone helps you quickly scaffold production-ready Go APIs with support for both HTTP (REST) and gRPC architectures.
+
+## Features
+
+- 🚀 **Quick Project Scaffolding** - Generate complete API projects with a single command
+- 🔄 **Multiple API Types** - Support for both HTTP (REST) and gRPC architectures
+- 📦 **Service Generation** - Easily create new services with proper structure
+- 🎯 **Handler Generation** - Generate HTTP or gRPC handlers on-demand
+- 🔐 **Cryptographic Key Generator** - Built-in secure key generation
+- 🛠️ **Pre-configured Tooling** - Automatic installation of essential Go tools
+- 📝 **Template-based** - Consistent code generation using embedded templates
+
+## Installation
+
+### From Source
+
+```bash
+git clone https://github.com/yourusername/keystone.git
+cd keystone
+make build
+```
+
+### Build for Different Platforms
+
+```bash
+# macOS (ARM64)
+make mac
+
+# Linux (AMD64)
+make linux
+
+# Windows (AMD64)
+make windows
+
+# Windows (ARM64)
+make win-arm
+```
+
+The compiled binary will be named `basalt` (or `basalt.exe` on Windows).
+
+## Usage
+
+### Create a New API Project
+
+```bash
+keystone new api
+```
+
+This interactive command will:
+1. Prompt you for a project name (module name)
+2. Ask you to select an API type (HTTP REST or gRPC)
+3. Scaffold the complete project structure
+4. Install required development tools
+5. Run `go mod tidy` to organize dependencies
+
+**Tools Automatically Installed:**
+- `air` - Live reload for Go apps
+- `golangci-lint` - Go linters aggregator
+- `mockgen` - Mock generation for testing
+- `sqlc` - SQL compiler for type-safe database code
+- `migrate` - Database migration tool
+- `swag` - Swagger documentation (HTTP only)
+- `protoc-gen-*` - Protocol Buffer generators (gRPC only)
+
+### Generate a New Service
+
+```bash
+keystone new service
+```
+
+Creates a new service file in `internal/service/` with:
+- Service interface definition
+- Service struct implementation
+- Compile-time interface checks
+
+### Generate a New Handler
+
+```bash
+keystone new handler
+```
+
+Creates a new handler in the appropriate directory:
+- HTTP handlers → `internal/handlers/http/`
+- gRPC handlers → `internal/handlers/grpc/`
+
+### Generate a Cryptographic Key
+
+```bash
+keystone new key
+```
+
+Generates a secure random key for use in your application (default: 32 characters).
+
+### Check Version
+
+```bash
+keystone version
+```
+
+## Project Structure
+
+When you create a new project, Keystone generates a structured Go API with:
+
+```
+your-project/
+├── cmd/
+│   └── api/
+│       └── main.go
+├── internal/
+│   ├── handlers/
+│   │   ├── http/    (if HTTP selected)
+│   │   └── grpc/    (if gRPC selected)
+│   └── service/
+├── proto/           (if gRPC selected)
+├── pb/              (if gRPC selected)
+└── go.mod
+```
+
+## Requirements
+
+- Go 1.25.5 or higher
+- Make (for building from source)
+
+## Dependencies
+
+- [Cobra](https://github.com/spf13/cobra) - CLI framework
+- [promptui](https://github.com/manifoldco/promptui) - Interactive prompts
+- [golang.org/x/text](https://golang.org/x/text) - Text processing utilities
+
+## Development
+
+### Build
+
+```bash
+make build
+```
+
+### Run with Version Flag
+
+```bash
+make version
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Author
+
+Built by LKResuts for internal usage to bootstrap Go APIs.
+
+---
+
+**Note:** The binary is compiled as `basalt`, but the CLI tool is referred to as `keystone` in documentation and usage.