@seeka-labs/cli-apps-azure 3.7.0 → 3.8.1

package/README.md

@@ -0,0 +1,307 @@
+# @seeka-labs/cli-apps-azure
+
+Azure-specific CLI tools for Seeka Apps. This package provides commands for setting up GitHub repositories and managing deployment environments for Seeka apps running on Azure Functions.
+
+## Installation
+
+```bash
+# Using npm
+npm install -g @seeka-labs/cli-apps-azure
+
+# Using yarn
+yarn global add @seeka-labs/cli-apps-azure
+
+# Or run directly with npx
+npx @seeka-labs/cli-apps-azure
+```
+
+## Prerequisites
+
+- A Seeka app created with [`@seeka-labs/cli-apps`](https://www.npmjs.com/package/@seeka-labs/cli-apps)
+- A GitHub account with permissions to create repositories
+- Node.js 18 or later
+
+## Quick Start
+
+Run the CLI from your Seeka app directory:
+
+```bash
+cd your-seeka-app
+npx @seeka-labs/cli-apps-azure
+```
+
+The CLI will automatically detect your app configuration from `.seeka/init.app.seeka.cli.config.json`.
+
+## Commands
+
+The CLI operates in **interactive mode** and presents a menu of available actions:
+
+### 1. Initialize GitHub Repository
+
+Creates a new GitHub repository for your Seeka app with all the necessary configuration for Azure Functions deployment.
+
+#### What It Does
+
+1. **Prompts for VITE_BASE_URL** - The base URL path for your app (default: `/{appName}/app/`)
+2. **Authenticates with GitHub** - Uses OAuth Device Flow (opens browser for authorization)
+3. **Selects repository owner** - Choose between your personal account or an organization
+4. **Creates private repository** - Named `seeka-app-{appName}`
+5. **Sets repository variables**:
+   - `AZURE_FUNC_RESOURCE_NAME` - Azure Function resource name
+6. **Creates `prod` environment** with variables:
+   - `VITE_BASE_URL` - Base URL for the app
+   - `HOSTING_ENV_NAME` - Set to `prod`
+
+#### Example Flow
+
+```
+$ npx @seeka-labs/cli-apps-azure
+
+🔐 Authenticating with GitHub...
+
+Please visit: https://github.com/login/device
+And enter code: ABCD-1234
+
+? Open browser automatically? Yes
+Waiting for authorization...
+
+✓ Successfully authenticated with GitHub!
+
+? Where do you want to create the repository?
+  > my-username (Personal Account)
+    my-organization - My Organization Description
+
+✅ GitHub repository initialized successfully!
+
+Repository: https://github.com/my-username/seeka-app-my-app
+Environment: prod
+```
+
+---
+
+### 2. Add Environment to Existing Repository
+
+Adds a new deployment environment (e.g., staging) to an existing GitHub repository.
+
+#### What It Does
+
+1. **Prompts for environment details**:
+   - Repository owner (username or organization)
+   - Repository name (default: `seeka-app-{appName}`)
+   - Environment name (default: `seeka-app-{appName}-stag`)
+   - Azure Function slot name (default: `staging`)
+   - Various URL configurations
+2. **Authenticates with GitHub**
+3. **Creates the environment**
+4. **Sets environment variables**:
+   - `AZURE_FUNC_SLOT_NAME` - Azure Function deployment slot
+   - `VITE_BASE_URL` - Base URL for the app
+   - `VITE_URLS_SEEKA_API_CORE` - Seeka API Core URL (optional)
+   - `VITE_URLS_SEEKA_APP_CORE_ORIGIN` - Seeka App Core Origin (optional)
+   - `HOSTING_ENV_NAME` - Environment name (e.g., `stag`)
+   - `SEEKA_APP_SETTINGS` - App settings JSON (default: `{}`)
+   - `SEEKA_APP_CFG_SEEKA_APP_SECRET` - Placeholder for app secret
+
+#### Example Flow
+
+```
+$ npx @seeka-labs/cli-apps-azure
+
+? What would you like to do? Add environment to existing GitHub repository
+
+? Enter GitHub repository owner: my-username
+? Enter GitHub repository name: seeka-app-my-app
+? Enter environment name: stag
+? Enter AZURE_FUNC_SLOT_NAME: staging
+? Enter VITE_BASE_URL: /my-app/app/
+? Enter VITE_URLS_SEEKA_API_CORE (optional):
+? Enter VITE_URLS_SEEKA_APP_CORE_ORIGIN (optional):
+? Enter HOSTING_ENV_NAME: stag
+
+🔐 Authenticating with GitHub...
+...
+
+✅ Environment added successfully!
+
+Repository: https://github.com/my-username/seeka-app-my-app
+Environment: stag
+```
+
+---
+
+### 3. Update Environment Variables and Secrets
+
+Updates all environment variables and secrets for an existing environment, with confirmation prompts before overwriting existing values.
+
+#### What It Does
+
+1. **Prompts for environment details**:
+   - Repository owner (username or organization)
+   - Repository name (default: `seeka-app-{appName}`)
+   - Environment name (default: `seeka-app-{appName}-stag`)
+2. **Authenticates with GitHub**
+3. **Fetches existing variables and secrets**
+4. **For each variable/secret to update**:
+   - If it exists, prompts for confirmation before overwriting
+   - For plain text variables: shows old and new values in the confirmation
+   - For secrets: only shows the name (value hidden for security)
+5. **Sets environment variables and secrets** based on configuration
+
+#### Example Flow
+
+```
+$ npx @seeka-labs/cli-apps-azure
+
+? What would you like to do? Update environment variables and secrets (overwrite existing)
+
+? Enter GitHub repository owner: my-username
+? Enter GitHub repository name: seeka-app-my-app
+? Enter environment name: stag
+
+🔐 Authenticating with GitHub...
+...
+
+🔐 Processing environment secrets...
+? Overwrite secret "SEEKA_APP_CFG_SEEKA_APP_SECRET"? (value hidden for security) Yes
+  ✓ Set environment secret: SEEKA_APP_CFG_SEEKA_APP_SECRET
+
+🔧 Processing environment variables...
+? Overwrite variable "VITE_BASE_URL"?
+  Old: /old-app/app/
+  New: /my-app/app/ Yes
+  ✓ Set environment variable: VITE_BASE_URL
+
+✅ Environment updated successfully!
+
+Repository: https://github.com/my-username/seeka-app-my-app
+Environment: stag
+```
+
+---
+
+## Configuration
+
+### Automatic Configuration Detection
+
+The CLI automatically looks for configuration in:
+
+```
+.seeka/init.app.seeka.cli.config.json
+```
+
+This file is created when you initialize a Seeka app with `@seeka-labs/cli-apps`.
+
+### Manual Configuration
+
+You can specify a custom configuration file:
+
+```bash
+npx @seeka-labs/cli-apps-azure --configFile ./path/to/config.json
+```
+
+#### Configuration File Format
+
+```json
+{
+  "orgName": "my-org",
+  "appName": "my-app"
+}
+```
+
+If no configuration file is found, the CLI will prompt you for the organization and app name.
+
+---
+
+## GitHub Authentication
+
+This CLI uses **OAuth Device Flow** for GitHub authentication:
+
+1. **Secure** - No client secret required (safe for public npm distribution)
+2. **Browser-based** - Opens your browser for authorization
+3. **Scoped** - Only requests `repo` scope for repository management
+4. **Session-only** - Access tokens are stored in-memory only and never persisted to disk
+
+### Required GitHub Permissions
+
+The authenticated user needs:
+- Permission to create repositories (personal or in the selected organization)
+- Permission to manage repository variables and environments
+
+---
+
+## Environment Variables Reference
+
+### Repository-Level Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AZURE_FUNC_RESOURCE_NAME` | Name of the Azure Function App resource |
+
+### Environment-Level Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AZURE_FUNC_SLOT_NAME` | Azure Function deployment slot name |
+| `VITE_BASE_URL` | Base URL path for the app |
+| `VITE_URLS_SEEKA_API_CORE` | Seeka API Core URL |
+| `VITE_URLS_SEEKA_APP_CORE_ORIGIN` | Seeka App Core Origin URL |
+| `HOSTING_ENV_NAME` | Environment name (e.g., `prod`, `stag`) |
+| `SEEKA_APP_SETTINGS` | JSON object for app-specific settings |
+| `SEEKA_APP_CFG_SEEKA_APP_SECRET` | Seeka App Secret (configure in GitHub) |
+
+---
+
+## Typical Workflow
+
+1. **Create your Seeka app**:
+   ```bash
+   npx @seeka-labs/cli-apps init my-org my-app --template azure-function
+   ```
+
+2. **Initialize GitHub repository**:
+   ```bash
+   cd seeka-app-my-app
+   npx @seeka-labs/cli-apps-azure
+   # Select "Initialize GitHub repository"
+   ```
+
+3. **Push your code**:
+   ```bash
+   git init
+   git add .
+   git commit -m "Initial commit"
+   git remote add origin https://github.com/your-username/seeka-app-my-app.git
+   git push -u origin main
+   ```
+
+4. **Add staging environment** (optional):
+   ```bash
+   npx @seeka-labs/cli-apps-azure
+   # Select "Add environment to existing GitHub repository"
+   ```
+
+5. **Configure Azure OIDC** in GitHub repository secrets:
+   - `AZURE_CLIENT_ID`
+   - `AZURE_TENANT_ID`
+   - `AZURE_SUBSCRIPTION_ID`
+
+6. **Deploy** - Push to `main` or `staging` branch to trigger GitHub Actions deployment
+
+---
+
+## Related Packages
+
+- [`@seeka-labs/cli-apps`](https://www.npmjs.com/package/@seeka-labs/cli-apps) - Main Seeka Apps CLI for scaffolding applications
+
+---
+
+## Support
+
+- [Seeka Developer Documentation](https://developers.seeka.co)
+- [Seeka Platform](https://seeka.app)
+
+---
+
+## License
+
+MIT