@seeka-labs/cli-apps 3.8.10 → 3.9.2

package/README.md

@@ -0,0 +1,286 @@
+# @seeka-labs/cli-apps
+
+The official Seeka Apps CLI for scaffolding and managing Seeka applications.
+
+## Installation
+
+```bash
+# Using npm
+npm install -g @seeka-labs/cli-apps
+
+# Using yarn
+yarn global add @seeka-labs/cli-apps
+
+# Or run directly with npx
+npx @seeka-labs/cli-apps@latest
+```
+
+## Quick Start
+
+The fastest way to get started is to run the CLI without any arguments to enter **interactive mode**:
+
+```bash
+npx @seeka-labs/cli-apps@latest
+```
+
+This will guide you through the setup process with prompts for all required information.
+
+## Commands
+
+### `init` - Initialize a New Seeka App
+
+Creates a new Seeka app with the specified template and configuration.
+
+#### Usage
+
+```bash
+# Interactive mode (recommended for first-time users)
+npx @seeka-labs/cli-apps@latest
+
+# Using command-line arguments
+npx @seeka-labs/cli-apps@latest init <org> <name> [options]
+
+# Using a configuration file
+npx @seeka-labs/cli-apps@latest init <config-file.json>
+```
+
+#### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `<configFileOrOrg>` | Path to JSON config file, or name of your organization (alphanumeric and hyphens only) |
+| `[name]` | Name of your app (alphanumeric and hyphens only) |
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--template <template>` | App template: `azure-function`, `aws-lambda`, or `netlify-function` |
+| `--developer <developer>` | App developer name or company |
+| `--email <email>` | App developer email |
+| `--outName [outName]` | Directory name of the app (a new directory will be created with this name) |
+| `--outDir [outDir]` | Output directory to create the app in (defaults to current working directory) |
+| `--npmUsername [username]` | Private NPM registry username for browser plugin dependencies |
+| `--npmPassword [password]` | Private NPM registry password for browser plugin dependencies |
+| `--noDependencies` | Skip installing dependencies |
+| `--skipSubDir` | Use sub directory for app files instead of root folder |
+| `--force` | Force creation of app in non-empty directory |
+| `--env [env...]` | Set environment variables (format: `--env KEY1=VALUE1 KEY2=VALUE2`) |
+
+#### Examples
+
+```bash
+# Create a new Azure Function app
+npx @seeka-labs/cli-apps@latest init my-org my-app \
+  --template azure-function \
+  --developer "My Company" \
+  --email "dev@mycompany.com"
+
+# Create app with environment variables
+npx @seeka-labs/cli-apps@latest init my-org my-app \
+  --template azure-function \
+  --developer "My Company" \
+  --email "dev@mycompany.com" \
+  --env "SEEKA_APP_ID=your-app-id" "SEEKA_APP_SECRET=your-secret"
+
+# Create app without installing dependencies
+npx @seeka-labs/cli-apps@latest init my-org my-app \
+  --template azure-function \
+  --developer "My Company" \
+  --email "dev@mycompany.com" \
+  --noDependencies
+
+# Create app from a configuration file
+npx @seeka-labs/cli-apps@latest init ./my-app-config.json
+```
+
+---
+
+### `ai context` - Install AI Context Files
+
+Installs AI context files to help AI assistants understand your Seeka app structure and provide better assistance.
+
+#### Usage
+
+```bash
+# Install AI context to current directory
+npx @seeka-labs/cli-apps@latest ai context
+
+# Install AI context to a specific directory
+npx @seeka-labs/cli-apps@latest ai context --target /path/to/project
+```
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--target <directory>` | Target directory (defaults to current directory) |
+
+#### What It Does
+
+- Downloads the Seeka AI context package
+- Extracts it to `.seeka/ai/context/` in your project
+- Provides documentation, architecture guides, and reference materials for AI assistants
+- Replaces any existing AI context if present
+
+#### Output Structure
+
+```
+.seeka/
+└── ai/
+    └── context/
+        ├── README.md
+        ├── architecture/
+        │   └── overview.md
+        ├── guides/
+        │   ├── getting-started.md
+        │   ├── common-patterns.md
+        │   ├── data-flow.md
+        │   └── testing.md
+        ├── reference/
+        │   ├── cli-commands.md
+        │   ├── config-schema.md
+        │   └── sdk-api.md
+        └── meta.json
+```
+
+---
+
+## Interactive Mode
+
+When you run the CLI without any arguments, it enters interactive mode:
+
+```bash
+npx @seeka-labs/cli-apps@latest
+```
+
+### Available Actions
+
+1. **Initialize a new Seeka app** - Guides you through creating a new app with prompts for:
+   - Organization name
+   - App name
+   - Template selection (azure-function, aws-lambda, netlify-function)
+   - Seeka App ID and Secret
+   - Developer name and email
+   - Output directory options
+   - Dependency installation preferences
+   - NPM registry credentials (for browser plugin)
+   - Additional options (force, skipSubDir)
+
+2. **Install AI context files** - Downloads and installs AI context to help AI assistants understand your project
+
+---
+
+## Configuration File
+
+You can use a JSON configuration file instead of command-line arguments:
+
+```json
+{
+  "orgName": "my-org",
+  "appName": "my-app",
+  "template": "azure-function",
+  "developerName": "My Company",
+  "developerEmail": "dev@mycompany.com",
+  "outputDirectory": "./",
+  "installDependencies": true,
+  "force": false,
+  "skipSubDir": false,
+  "environmentVariables": {
+    "SEEKA_APP_ID": "your-app-id",
+    "SEEKA_APP_SECRET": "your-secret"
+  },
+  "npmUsername": "your-npm-username",
+  "npmPassword": "your-npm-password"
+}
+```
+
+Then run:
+
+```bash
+npx @seeka-labs/cli-apps@latest init ./my-config.json
+```
+
+---
+
+## Templates
+
+### Azure Function (`azure-function`)
+
+Creates a Seeka app designed to run on Azure Functions. Includes:
+- Azure Functions project structure
+- Server-side webhook handlers
+- Local development setup with Azurite
+- GitHub Actions deployment workflow
+- GitLab CI/CD pipeline
+
+### AWS Lambda (`aws-lambda`)
+
+Creates a Seeka app designed to run on AWS Lambda. *(Coming soon)*
+
+### Netlify Function (`netlify-function`)
+
+Creates a Seeka app designed to run on Netlify Functions. *(Coming soon)*
+
+---
+
+## Project Structure
+
+After running `init`, your project will have the following structure:
+
+```
+seeka-app-{name}/
+├── .seeka/
+│   ├── init.app.seeka.cli.config.json    # CLI configuration
+│   ├── init.app.secrets.seeka.cli.config.json  # Environment variables
+│   └── ai/
+│       └── context/                       # AI context files
+├── app/
+│   ├── lib/                               # Shared library code
+│   ├── server/                            # Server-side code (Azure Functions)
+│   ├── browser/                           # Browser plugin code (optional)
+│   └── ui/                                # UI components (optional)
+├── .github/
+│   └── workflows/                         # GitHub Actions workflows
+├── .gitlab-ci.yml                         # GitLab CI/CD pipeline
+├── package.json
+├── .yarnrc.yml
+└── README.md
+```
+
+---
+
+## Environment Variables
+
+The following environment variables are commonly used in Seeka apps:
+
+| Variable | Description |
+|----------|-------------|
+| `SEEKA_APP_ID` | Your Seeka App ID (from https://seeka.app/settings/developer/apps) |
+| `SEEKA_APP_SECRET` | Your Seeka App Secret |
+
+---
+
+## Requirements
+
+- Node.js 18 or later
+- npm, yarn, or pnpm
+
+---
+
+## Related Packages
+
+- [`@seeka-labs/cli-apps-azure`](https://www.npmjs.com/package/@seeka-labs/cli-apps-azure) - Azure-specific CLI for GitHub repository setup and environment management
+
+---
+
+## Support
+
+- [Seeka Developer Documentation](https://developers.seeka.co)
+- [Seeka Platform](https://seeka.app)
+
+---
+
+## License
+
+MIT