@docyrus/cli 0.1.0

package/README.md

@@ -0,0 +1,249 @@
+# Docyrus CLI
+
+Official command-line interface for Docyrus - authentication, project scaffolding, and code generation tools.
+
+## Installation
+
+```bash
+npm install -g docyrus
+# or
+pnpm add -g docyrus
+```
+
+## Commands
+
+### Authentication
+
+#### `docyrus login`
+
+Log in to Docyrus using browser-based SSO (default).
+
+```bash
+docyrus login              # Opens browser for SSO authentication
+docyrus login --email      # Use email/password instead (prompts for credentials)
+docyrus login -e user@example.com  # Pre-fill email address
+```
+
+#### `docyrus logout`
+
+Log out from Docyrus and clear stored credentials.
+
+```bash
+docyrus logout
+```
+
+#### `docyrus whoami`
+
+Display the currently logged-in user.
+
+```bash
+docyrus whoami
+# Output: Email: user@example.com
+#         Name: John Doe
+```
+
+### Project Creation
+
+#### `docyrus create [name]`
+
+Create a new Docyrus project from a template.
+
+```bash
+docyrus create                           # Interactive mode - prompts for all options
+docyrus create my-app                    # Create project with specified name
+docyrus create my-app --nextjs           # Next.js + plain Tailwind
+docyrus create my-app --nextjs --shadcn  # Next.js + shadcn/ui
+docyrus create my-app --react --heroui   # React + HeroUI
+docyrus create my-app --vue --shadcn     # Vue + shadcn-vue
+docyrus create my-app --astro            # Astro + plain Tailwind
+docyrus create my-app --nextjs --shadcn --eslint --pnpm  # Full flags
+```
+
+**Framework Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--nextjs` | Use Next.js 15+ (App Router) |
+| `--react` | Use React 19+ with Vite |
+| `--astro` | Use Astro 5+ |
+| `--vue` | Use Vue 3.5+ with Vite |
+
+**UI Library Options (optional - defaults to plain Tailwind if not specified):**
+
+| Flag | Description |
+|------|-------------|
+| `--shadcn` | Use shadcn/ui (React/Next.js) or shadcn-vue (Vue) |
+| `--heroui` | Use HeroUI (React/Next.js only) |
+
+**Linter Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--eslint` | Use ESLint for linting |
+| `--biome` | Use Biome for linting |
+| `--no-linter` | Skip linter configuration |
+
+**Package Manager Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--pnpm` | Use pnpm (recommended) |
+| `--npm` | Use npm |
+| `--yarn` | Use yarn |
+| `--bun` | Use bun |
+
+**Other Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-p, --path <path>` | Target directory path |
+| `--alias <prefix>` | Custom import alias prefix (must start with @) |
+
+**Available Templates:**
+
+| Template | Description |
+|----------|-------------|
+| `nextjs` | Next.js 15+ + Tailwind CSS v4 |
+| `nextjs-shadcn` | Next.js 15+ + Tailwind CSS v4 + shadcn/ui |
+| `nextjs-heroui` | Next.js 15+ + Tailwind CSS v4 + HeroUI |
+| `react` | React 19+ + Vite + Tailwind CSS v4 |
+| `react-shadcn` | React 19+ + Vite + Tailwind CSS v4 + shadcn/ui |
+| `react-heroui` | React 19+ + Vite + Tailwind CSS v4 + HeroUI |
+| `astro` | Astro 5+ + Tailwind CSS v4 |
+| `vue` | Vue 3.5+ + Vite + Tailwind CSS v4 |
+| `vue-shadcn` | Vue 3.5+ + Vite + Tailwind CSS v4 + shadcn-vue |
+
+Each template includes:
+- Pre-configured OAuth2 authentication pages
+- Docyrus API client integration
+- Modern TypeScript setup
+- Linter configuration (ESLint or Biome)
+
+### Code Generation
+
+#### `docyrus generate db [spec]`
+
+Generate TanStack Query collections from an OpenAPI 3.1.0 specification.
+
+```bash
+docyrus generate db                           # Auto-detect openapi.json in current directory
+docyrus generate db ./api/openapi.json        # Specify spec file path
+docyrus generate db ./spec.json -o ./src/api  # Custom output directory
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <dir>` | Output directory (defaults to `src` in spec file folder) |
+| `-w, --watch` | Watch for changes in the spec file (coming soon) |
+
+### CLI Management
+
+#### `docyrus upgrade`
+
+Upgrade the CLI to the latest version. Automatically detects your package manager (npm, pnpm, yarn, bun).
+
+```bash
+docyrus upgrade
+```
+
+#### `docyrus completion <shell>`
+
+Generate shell completion script for tab completion support.
+
+```bash
+# Bash - add to ~/.bashrc
+eval "$(docyrus completion bash)"
+
+# Zsh - add to ~/.zshrc
+eval "$(docyrus completion zsh)"
+
+# Fish - save to completions directory
+docyrus completion fish > ~/.config/fish/completions/docyrus.fish
+```
+
+#### `docyrus info`
+
+Display CLI version, system information, and authentication status. Useful for debugging.
+
+```bash
+docyrus info
+# Output:
+# docyrus v0.0.1
+#
+# System:
+#   Node.js:  v20.10.0
+#   OS:       darwin 23.0.0 (arm64)
+#
+# Environment:
+#   API URL:  https://api.docyrus.com
+#   Config:   /Users/you/.docyrus
+#
+# Authentication:
+#   Status:   Logged in
+#   Email:    user@example.com
+```
+
+## Global Options
+
+### `--json`
+
+Output results in JSON format. Useful for scripting and CI/CD pipelines.
+
+```bash
+docyrus whoami --json
+# Output: {"user": {"email": "user@example.com", "firstname": "John", "lastname": "Doe"}}
+
+docyrus generate db ./spec.json --json
+# Output: {"spec": "./spec.json", "output": "./src", "success": true, "message": "..."}
+```
+
+### `-v, --version`
+
+Display the CLI version.
+
+```bash
+docyrus -v
+# Output: 0.0.1
+```
+
+### `-h, --help`
+
+Display help information.
+
+```bash
+docyrus --help
+docyrus login --help
+docyrus generate --help
+docyrus generate db --help
+```
+
+## Auto-Update Notifications
+
+The CLI automatically checks for updates and displays a notification when a new version is available:
+
+```
+┌────────────────────────────────────────────┐
+│  Update available! 0.0.1 → 0.1.0           │
+│  Run npm i -g docyrus to update            │
+└────────────────────────────────────────────┘
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `DOCYRUS_API_URL` | Override the API base URL |
+| `DOCYRUS_OAUTH_CLIENT_ID` | Override the OAuth2 client ID |
+| `DEBUG` | Enable debug output |
+
+## Token Storage
+
+Credentials are securely stored using:
+- **macOS/Linux**: System keychain (via `keytar`)
+- **Fallback**: Encrypted file in `~/.docyrus/`
+
+## License
+
+MIT