@slingr/cli 0.0.3 → 0.0.4

package/README.md

@@ -1,320 +1,491 @@
-# Slingr CLI
-
-A command-line tool for creating and managing Slingr applications.
-
-## Getting Started
-
-### Quick Installation (Recommended)
-
-For application developers who want to start using Slingr CLI immediately:
-
-#### macOS and Linux
-
-```bash
-# Download and run the installation script
-curl -fsSL https://raw.githubusercontent.com/slingr-stack/framework/main/scripts/install.sh | bash
-```
-
-Or download and run manually:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/slingr-stack/framework/main/scripts/install.sh -o install.sh
-chmod +x install.sh
-./install.sh
-```
-
-#### Windows (PowerShell)
-
-```powershell
-# Download and run the installation script
-irm https://raw.githubusercontent.com/slingr-stack/framework/main/scripts/install.ps1 | iex
-```
-
-Or download and run manually:
-
-```powershell
-# Run PowerShell as Administrator
-Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
-Invoke-WebRequest -Uri https://raw.githubusercontent.com/slingr-stack/framework/main/scripts/install.ps1 -OutFile install.ps1
-.\install.ps1
-```
-
-The installation script will:
-
-- Validate Node.js 18+, npm, and TypeScript 5+
-- Check Docker and Docker Compose (optional but recommended)
-- Guide you through CLI installation
-
-### Manual Installation
-
-If you prefer to install the CLI manually or are contributing to the framework:
-
-```bash
-# Clone the repository
-git clone https://github.com/slingr-stack/framework.git
-cd framework/cli
-
-# Install dependencies
-npm install
-
-# Build the CLI
-npm run build
-
-# Link globally to use the 'slingr' command
-npm link
-```
-
-You can also build from the repository root:
-
-```bash
-npm run build:cli
-```
-
-## Documentation
-
-For detailed setup instructions, troubleshooting, and more information:
-
-| Document                                                          | Description                           |
-| ----------------------------------------------------------------- | ------------------------------------- |
-| [Repository Overview](../README.md)                               | Main repository setup and overview    |
-| [Setup Guide](../docs/setup-guide.md)                             | Detailed installation and setup guide |
-| [Framework Documentation](../framework/README.md)                 | Core framework usage and examples     |
-| [VS Code Extension Documentation](../vs-code-extension/README.md) | IDE extension features and setup      |
-
-See the [framework documentation](../framework/docs) for detailed guides on data models, actions, and database configuration.
-
-## Testing the CLI
-
-To test the CLI commands:
-
-```bash
-# Display help
-slingr --help
-
-# Run tests (from repository root)
-npm run test:cli
-```
-
-## CLI Development (For Contributors)
-
-If you're contributing to the CLI itself:
-
-```bash
-# Rebuild the CLI tool
-slingr cli-build
-
-# Or from repository root
-npm run build:cli
-```
-
-For more information on contributing to the Slingr Framework, see the [Repository Overview](../README.md) and [Setup Guide](../docs/setup-guide.md).
-
-## Usage
-
-### Create a new application
-
-```bash
-slingr create-app my-app
-```
-
-This command will:
-
-1. Ask you questions about your application type and requirements
-2. Create a project directory with the specified name
-3. Set up a complete TypeScript project structure with database configuration
-4. Generate sample files and configurations
-5. Configure VS Code settings and recommended extensions
-6. Set up Docker infrastructure files for database management
-
-#### Create-app flags
-
-You can skip the interactive prompts by using command flags.
-
-Available flags:
-
-- `--type, -t`: Type of application (e.g., CRM, task manager, ERP)
-- `--backend, -b`: Include backend for the application (default: true)
-- `--frontend, -f`: Include frontend for the application (default: true)
-- `--database, -d`: Database to use (postgres or mysql)
-- `--description, -D`: Description of what the application needs to do
-- `--templates, -T`: Include data models and sample data (default: `false`)
-- `--skip-infra, -i`: Skip infrastructure setup and checks
-
-For example:
-
-```bash
-# Create app with all flags
-slingr create-app my-crm --type="CRM" --backend --frontend --database=postgres --description="A CRM system for managing customers"
-
-# Create app without frontend
-slingr create-app my-api --type="API" --backend --no-frontend --database=mysql --description="A REST API for data management"
-
-# Create app with sample data models and datasets
-slingr create-app my-erp --type="ERP" --backend --frontend --database=postgres --description="An ERP system for business management" --templates
-```
-
-### Run your application
-
-```bash
-slingr run
-```
-
-This command will:
-
-1. Build the slingr-framework if needed
-2. Compile your TypeScript code
-3. Check and start Docker infrastructure services
-4. Run your application with hot reload
-
-### Manage datasets
-
-```bash
-# Load default dataset for a datasource
-slingr ds postgres load
-
-# Load specific dataset
-slingr ds postgres load custom-dataset
-
-# Load dataset for MySQL datasource
-slingr ds mysql load default
-
-# Reset datasource infrastructure (clears container and volume data)
-slingr ds postgres reset
-```
-
-These commands help you load JSONL datasets into your database and reset datasource infrastructure for a clean state when testing and development require it.
-
-### Infrastructure management
-
-```bash
-# Update infrastructure for all datasources
-slingr infra update --all
-
-# Update infrastructure for specific datasource
-slingr infra update --file postgres.ts
-
-# Start infrastructure services
-slingr infra up
-
-# Stop infrastructure services
-slingr infra down
-```
-
-Infrastructure commands help you manage Docker containers for your databases.
-
-## Generated Project Structure
-
-When you create a new app with the `--templates` flag, the following structure is generated:
-
-```
-your-app/
-├── .vscode/
-│   ├── extensions.json      # Recommended VS Code extensions
-│   └── settings.json        # VS Code settings for optimal development
-├── docs/
-│   └── app-description.md   # Generated app documentation
-├── src/
-│   ├── index.ts            # Main application entry point
-│   ├── data/              # Data models (generated with --templates flag)
-│   │   ├── App.ts         # Application model
-│   │   ├── Address.ts     # Address model (shared composition example)
-│   │   ├── Company.ts     # Company model example
-│   │   ├── Person.ts      # Person model example
-│   │   ├── Models.test.ts # Comprehensive integration tests
-│   │   └── Person.test.ts # Person model unit tests
-│   ├── dataSources/       # Database configurations
-│   │   ├── postgres.ts    # PostgreSQL datasource config
-│   │   └── mysql.ts       # MySQL datasource config (if selected)
-│   └── datasets/          # Sample data for development (generated with --templates flag)
-│       ├── postgres-default/
-│       │   ├── App.jsonl
-│       │   ├── Company.jsonl
-│       │   └── Person.jsonl
-│       └── mysql-default/ # If MySQL was selected
-│           ├── App.jsonl
-│           ├── Company.jsonl
-│           └── Person.jsonl
-├── docker-compose.yml      # Database infrastructure (generated on first run)
-├── jest.config.ts         # Jest configuration for testing
-├── jest.setup.ts          # Jest setup file
-├── package.json            # Project configuration with slingr-framework dependency
-└── tsconfig.json          # TypeScript configuration
-```
-
-**Note**: Sample data models and tests are only generated when using the `--templates` flag. Without it, you get a minimal project structure with just the basic setup.
-
-## Features
-
-### Core Development Features
-
-- **TypeScript Setup**: Pre-configured TypeScript with strict settings
-- **Testing**: Jest test framework with comprehensive sample tests (when using `--templates`)
-- **Linting**: ESLint with TypeScript support
-- **VS Code Integration**: Optimized settings and extension recommendations
-- **Sample Code**: Working model examples with validation and relationships (with `--templates` flag)
-
-### Database & Infrastructure
-
-- **Multi-Database Support**: PostgreSQL and MySQL with automatic Docker setup
-- **Infrastructure as Code**: Automatic Docker Compose generation for databases
-- **Dataset Management**: Load JSONL datasets into your databases for testing
-- **Port Conflict Detection**: Automatic detection and resolution of port conflicts
-- **Health Checks**: Built-in database health monitoring
-
-### Development Workflow
-
-- **Hot Reload**: Automatic application restart on code changes
-- **Docker Integration**: Seamless database container management
-- **Framework Building**: Automatic slingr-framework compilation when needed
-- **Dependency Management**: Smart dependency installation based on database choice
-
-## Database Support
-
-The CLI supports the following databases with automatic infrastructure setup:
-
-### PostgreSQL
-
-- **Default Port**: 5433
-- **Docker Image**: postgres:15-alpine
-- **Health Checks**: Built-in pg_isready monitoring
-- **Data Persistence**: Automatic volume management
-
-### MySQL
-
-- **Default Port**: 3306
-- **Docker Image**: mysql:8.0
-- **Health Checks**: Built-in mysqladmin ping monitoring
-- **Data Persistence**: Automatic volume management
-
-## Dataset Management
-
-The CLI includes a powerful dataset management system:
-
-### JSONL Format
-
-Datasets are stored in JSONL (JSON Lines) format, with one JSON object per line:
-
-```jsonl
-{"id": 1, "name": "John Doe", "email": "john@example.com"}
-{"id": 2, "name": "Jane Smith", "email": "jane@example.com"}
-```
-
-### Loading Datasets
-
-```bash
-# Load default dataset for PostgreSQL
-slingr ds postgres load
-
-# Load specific dataset
-slingr ds postgres load my-custom-dataset
-```
-
-### Dataset Structure
-
-Datasets are organized by datasource and dataset name:
-
-```
-src/datasets/
-├── postgres-default/     # Default PostgreSQL dataset
-└── mysql-custom/         # Custom MySQL dataset
+# Slingr CLI
+
+A command-line tool for creating and managing Slingr applications.
+
+## Getting Started
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/slingr-stack/framework.git
+cd framework/cli
+
+# Install dependencies
+npm install
+
+# Build the CLI
+npm run build
+
+# Link globally to use the 'slingr' command
+npm link
+```
+
+You can also build from the repository root:
+
+```bash
+npm run build:cli
+```
+
+## Documentation
+
+For detailed CLI documentation and guides:
+
+| Document                                                          | Description                           |
+| ----------------------------------------------------------------- | ------------------------------------- |
+| [CLI Introduction](../docs/cli/intro.md)                          | Getting started with the CLI          |
+| [CLI Architecture](../docs/cli/architecture.md)                   | CLI design and architecture           |
+| [Run Command Guide](../docs/cli/run-command.md)                   | Using the run command                 |
+| [Repository Overview](../README.md)                               | Main repository setup and overview    |
+| [Setup Guide](../docs/framework/setup-guide.md)                   | Detailed installation and setup guide |
+| [Framework Documentation](../framework/README.md)                 | Core framework usage and examples     |
+| [VS Code Extension Documentation](../vs-code-extension/README.md) | IDE extension features and setup      |
+
+See the [framework documentation](../docs/framework/) for detailed guides on data models, actions, and database configuration.
+
+## Testing the CLI
+
+To test the CLI commands:
+
+```bash
+# Display help
+slingr --help
+
+# Run tests (from repository root)
+npm run test:cli
+```
+
+## CLI Development (For Contributors)
+
+If you're contributing to the CLI itself:
+
+```bash
+# Rebuild the CLI tool
+slingr cli-build
+
+# Or from repository root
+npm run build:cli
+```
+
+For more information on contributing to the Slingr Framework, see the [Repository Overview](../README.md) and [Setup Guide](../docs/framework/setup-guide.md).
+
+## Usage
+
+### Create a new application
+
+```bash
+slingr create-app my-app
+```
+
+This command will:
+
+1. Ask you questions about your application type and requirements
+2. Create a project directory with the specified name
+3. Set up a complete TypeScript project structure with database configuration
+4. Generate sample files and configurations
+5. Configure VS Code settings and recommended extensions
+6. Set up Docker infrastructure files for database management
+
+After creating your app, you can set it up with:
+
+```bash
+cd my-app
+npm run setup
+```
+
+This will install dependencies, generate the GraphQL schema, and generate the TypeScript SDK. Alternatively, you can run each step manually:
+
+```bash
+cd my-app
+npm install
+npx slingr gql generate-schema
+npx slingr gql generate-sdk
+```
+
+#### Create-app flags
+
+You can skip the interactive prompts by using command flags.
+
+Available flags:
+
+- `--type, -t`: Type of application (e.g., CRM, task manager, ERP)
+- `--backend, -b`: Include backend for the application (default: true)
+- `--frontend, -f`: Include frontend for the application (default: true)
+- `--database, -d`: Database to use (postgres or mysql)
+- `--description, -D`: Description of what the application needs to do
+- `--templates, -T`: Include data models and sample data (default: `false`)
+- `--skip-infra, -i`: Skip infrastructure setup and checks
+
+For example:
+
+```bash
+# Create app with all flags
+slingr create-app my-crm --type="CRM" --backend --frontend --database=postgres --description="A CRM system for managing customers"
+
+# Create app without frontend
+slingr create-app my-api --type="API" --backend --no-frontend --database=mysql --description="A REST API for data management"
+
+# Create app with sample data models and datasets
+slingr create-app my-erp --type="ERP" --backend --frontend --database=postgres --description="An ERP system for business management" --templates
+```
+
+### Run your application
+
+```bash
+slingr run
+```
+
+This command will:
+
+1. Build the @slingr-framework if needed
+2. Build the UI (if present) with Vite
+3. Compile your TypeScript code
+4. Check and start Docker infrastructure services
+5. Run your application with hot reload
+6. Serve the UI and GraphQL API on the same port (default: 3000)
+
+Access your application:
+
+- Frontend UI: `http://localhost:3000/`
+- GraphQL API: `http://localhost:3000/graphql`
+
+### Debug your application
+
+```bash
+slingr debug
+```
+
+This command runs your application with Node.js debugging enabled, allowing you to attach a debugger for troubleshooting and development. The command performs the same setup as `slingr run` but starts the application with the Node.js inspector enabled. The UI is also built and served alongside the backend.
+
+#### Debug command options
+
+- `--inspect-port, -p`: Port for Node.js debugger (default: 9229)
+- `--inspect-brk, -b`: Break before user code starts (useful for debugging startup issues)
+- `--skip-infra, -i`: Skip infrastructure setup and checks
+
+#### Examples
+
+```bash
+# Run with default debug port (9229)
+slingr debug
+
+# Run with custom debug port
+slingr debug --inspect-port 9230
+
+# Break before user code starts (useful for debugging initialization)
+slingr debug --inspect-brk
+
+# Run without starting infrastructure services
+slingr debug --skip-infra
+```
+
+#### Attaching a debugger
+
+Once the application is running in debug mode, you can attach a debugger:
+
+**VS Code:**
+
+1. Create a debug configuration in `.vscode/launch.json`:
+
+```json
+{
+  "type": "node",
+  "request": "attach",
+  "name": "Attach to Slingr",
+  "port": 9229,
+  "skipFiles": ["<node_internals>/**"]
+}
+```
+
+2. Press F5 or use the "Run and Debug" panel to attach
+
+**Chrome DevTools:**
+
+1. Open Chrome and navigate to `chrome://inspect`
+2. Click "Open dedicated DevTools for Node"
+3. Your application should appear in the list of inspectable targets
+
+### Manage datasets
+
+```bash
+# Load default dataset for a datasource
+slingr ds postgres load
+
+# Load specific dataset
+slingr ds postgres load custom-dataset
+
+# Load dataset for MySQL datasource
+slingr ds mysql load default
+
+# Reset datasource infrastructure (clears container and volume data)
+slingr ds postgres reset
+```
+
+These commands help you load JSONL datasets into your database and reset datasource infrastructure for a clean state when testing and development require it.
+
+### User Management
+
+Every new Slingr application comes with built-in authentication and user management. A default System user is created automatically when you load the initial dataset.
+
+#### List Users
+
+```bash
+slingr users list
+```
+
+Displays all users in the application with their status and roles.
+
+#### Create User
+
+```bash
+# Interactive mode
+slingr users create
+
+# With flags
+slingr users create \
+  --email john@example.com \
+  --first-name John \
+  --last-name Doe \
+  --password secret123 \
+  --roles "Admin,User"
+```
+
+Creates a new user in the application. Passwords are automatically hashed using bcrypt.
+
+#### Manage Passwords
+
+```bash
+# Set a new password (interactive)
+slingr users set-password john@example.com
+
+# Set a new password (with flag)
+slingr users set-password john@example.com --new-password newpass123
+
+# Reset password (generates random password)
+slingr users reset-password john@example.com
+```
+
+The reset-password command generates a secure random password and displays it once.
+
+#### Activate/Deactivate Users
+
+```bash
+# Activate a user
+slingr users activate john@example.com
+
+# Deactivate a user
+slingr users deactivate john@example.com
+```
+
+Deactivated users cannot log in to the application.
+
+#### Delete User
+
+```bash
+# Delete with confirmation
+slingr users delete john@example.com
+
+# Delete without confirmation
+slingr users delete john@example.com --force
+```
+
+**Note**: System users cannot be deleted for security reasons.
+
+#### User Management Options
+
+- `--datasource, -d`: Specify datasource name (auto-discovered from User model if not specified)
+- `--force, -f`: Skip confirmation prompts
+- `--help, -h`: Show command help
+
+**Note**: All user commands automatically discover the datasource configured in your User model, so you typically don't need to specify the `--datasource` flag.
+
+#### Default System User
+
+When you create a new app and load the initial dataset, a System user is created with:
+
+- **Email**: sys@app.com
+- **Password**: 12345678 (change this in production!)
+- **Role**: System (full access)
+
+To change the System user password:
+
+```bash
+slingr users set-password sys@app.com
+```
+
+### Infrastructure management
+
+```bash
+# Update infrastructure for all datasources
+slingr infra update --all
+
+# Update infrastructure for specific datasource
+slingr infra update --file postgres.ts
+
+# Start infrastructure services
+slingr infra up
+
+# Stop infrastructure services
+slingr infra down
+```
+
+Infrastructure commands help you manage Docker containers for your databases.
+
+### GraphQL API
+
+The Slingr Framework includes built-in GraphQL API support powered by Apollo Server. These commands help you generate GraphQL schemas and SDKs.
+
+#### Generate GraphQL schema
+
+```bash
+# Generate schema in generated/gql/schema.graphql
+slingr gql generate-schema
+
+# Keep Apollo Server running after generating schema
+slingr gql generate-schema --no-exit
+```
+
+This command generates the GraphQL schema file from your application's actions and models.
+
+#### Generate GraphQL SDK
+
+```bash
+# Generate type-safe SDK (automatically generates schema if needed)
+slingr gql generate-sdk
+```
+
+This command generates a type-safe GraphQL SDK in `generated/gql/sdk.ts` that you can use to interact with your API. Use it in your code with:
+
+```typescript
+import gql from '@gql';
+
+const result = await gql.yourQuery();
+```
+
+### CLI development
+
+```bash
+# Rebuild the CLI tool itself (for CLI developers)
+slingr cli-build
+```
+
+## Generated Project Structure
+
+When you create a new app with the `--templates` flag, the following structure is generated:
+
+```
+your-app/
+├── .vscode/
+│   ├── extensions.json      # Recommended VS Code extensions
+│   └── settings.json        # VS Code settings for optimal development
+├── docs/
+│   └── app-description.md   # Generated app documentation
+├── src/
+│   ├── index.ts            # Main application entry point
+│   ├── data/              # Data models
+│   │   ├── User.ts        # User model with authentication (always generated)
+│   │   ├── App.ts         # Application model (with --templates)
+│   │   ├── Address.ts     # Address model (with --templates)
+│   │   ├── Company.ts     # Company model (with --templates)
+│   │   ├── Person.ts      # Person model (with --templates)
+│   │   ├── Models.test.ts # Integration tests (with --templates)
+│   │   └── Person.test.ts # Unit tests (with --templates)
+│   ├── auth/              # Authentication and permissions (always generated)
+│   │   └── permissions.ts # Permission definitions
+│   ├── dataSources/       # Database configurations
+│   │   ├── postgres.ts    # PostgreSQL datasource config
+│   │   └── mysql.ts       # MySQL datasource config (if selected)
+│   └── datasets/          # Sample data for development
+│       ├── postgres-default/
+│       │   ├── User.jsonl     # System user (always generated)
+│       │   ├── App.jsonl      # (with --templates)
+│       │   ├── Company.jsonl  # (with --templates)
+│       │   └── Person.jsonl   # (with --templates)
+│       └── mysql-default/ # If MySQL was selected
+│           ├── User.jsonl
+│           └── ... (same structure)
+├── .env.example           # Environment variables template
+├── docker-compose.yml     # Database infrastructure (generated on first run)
+├── jest.config.ts         # Jest configuration for testing
+├── jest.setup.ts          # Jest setup file
+├── package.json           # Project configuration with @slingr-framework dependency
+└── tsconfig.json         # TypeScript configuration
+```
+
+**Note**: Sample data models and tests are only generated when using the `--templates` flag. Without it, you get a minimal project structure with just the basic setup.
+
+## Features
+
+### Core Development Features
+
+- **TypeScript Setup**: Pre-configured TypeScript with strict settings
+- **Testing**: Jest test framework with comprehensive sample tests (when using `--templates`)
+- **Linting**: ESLint with TypeScript support
+- **VS Code Integration**: Optimized settings and extension recommendations
+- **Sample Code**: Working model examples with validation and relationships (with `--templates` flag)
+
+### Database & Infrastructure
+
+- **Multi-Database Support**: PostgreSQL and MySQL with automatic Docker setup
+- **Infrastructure as Code**: Automatic Docker Compose generation for databases
+- **Dataset Management**: Load JSONL datasets into your databases for testing
+- **Port Conflict Detection**: Automatic detection and resolution of port conflicts
+- **Health Checks**: Built-in database health monitoring
+
+### Development Workflow
+
+- **Hot Reload**: Automatic application restart on code changes
+- **Docker Integration**: Seamless database container management
+- **Framework Building**: Automatic @slingr-framework compilation when needed
+- **Dependency Management**: Smart dependency installation based on database choice
+
+## Database Support
+
+The CLI supports the following databases with automatic infrastructure setup:
+
+### PostgreSQL
+
+- **Default Port**: 5433
+- **Docker Image**: postgres:15-alpine
+- **Health Checks**: Built-in pg_isready monitoring
+- **Data Persistence**: Automatic volume management
+
+### MySQL
+
+- **Default Port**: 3306
+- **Docker Image**: mysql:8.0
+- **Health Checks**: Built-in mysqladmin ping monitoring
+- **Data Persistence**: Automatic volume management
+
+## Dataset Management
+
+The CLI includes a powerful dataset management system:
+
+### JSONL Format
+
+Datasets are stored in JSONL (JSON Lines) format, with one JSON object per line:
+
+```jsonl
+{"id": 1, "name": "John Doe", "email": "john@example.com"}
+{"id": 2, "name": "Jane Smith", "email": "jane@example.com"}
+```
+
+### Loading Datasets
+
+```bash
+# Load default dataset for PostgreSQL
+slingr ds postgres load
+
+# Load specific dataset
+slingr ds postgres load my-custom-dataset
+```
+
+### Dataset Structure
+
+Datasets are organized by datasource and dataset name:
+
+```
+src/datasets/
+├── postgres-default/     # Default PostgreSQL dataset
+└── mysql-custom/         # Custom MySQL dataset
 ```