@seeka-labs/cli-apps 3.7.0 → 3.8.2

package/dist/ai-context/common/reference/cli-commands.md

@@ -0,0 +1,231 @@
+# CLI Commands Reference
+
+This document provides a reference for all Seeka CLI commands.
+
+## Installation
+
+```bash
+# Install globally
+npm install -g @seeka-labs/cli-apps
+
+# Or use npx (recommended)
+npx @seeka-labs/cli-apps@latest <command>
+```
+
+## Commands
+
+### `init` - Initialize a New App
+
+Creates a new Seeka app from a template.
+
+#### Usage
+
+```bash
+# Using a config file
+npx @seeka-labs/cli-apps init <configFile>
+
+# Using command line arguments
+npx @seeka-labs/cli-apps init <org> <name> [options]
+```
+
+#### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `configFileOrOrg` | Path to JSON config file, or name of your org |
+| `name` | Name of your app (alphanumeric and hyphens only) |
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--template <template>` | App template: `azure-function`, `aws-lambda`, `netlify-function` | Required |
+| `--developer <developer>` | App developer name or company | Required |
+| `--email <email>` | App developer email | Required |
+| `--outName [outName]` | Directory name for the app | App name |
+| `--outDir [outDir]` | Output directory to create the app in | Current directory |
+| `--npmUsername [username]` | Private NPM registry username | - |
+| `--npmPassword [password]` | Private NPM registry password | - |
+| `--noDependencies` | Skip installing dependencies | false |
+| `--skipSubDir` | Use current directory instead of creating subdirectory | false |
+| `--force` | Force creation in non-empty directory | false |
+| `--env [env...]` | Set environment variables (KEY=VALUE format) | - |
+
+#### Examples
+
+```bash
+# Create app with command line arguments
+npx @seeka-labs/cli-apps init my-org my-app \
+  --template azure-function \
+  --developer "My Company" \
+  --email dev@mycompany.com \
+  --env SEEKA_APP_ID=app-123 SEEKA_APP_SECRET=secret-456
+
+# Create app from config file
+npx @seeka-labs/cli-apps init ./my-app.seeka.cli.config.json
+
+# Create app in specific directory
+npx @seeka-labs/cli-apps init my-org my-app \
+  --template azure-function \
+  --developer "My Company" \
+  --email dev@mycompany.com \
+  --outDir ./projects \
+  --outName my-custom-app-name
+```
+
+#### Config File Format
+
+```json
+{
+  "appName": "my-app",
+  "orgName": "my-org",
+  "template": "azure-function",
+  "developerName": "My Company",
+  "developerEmail": "dev@mycompany.com",
+  "outputDirectory": "./projects",
+  "directoryName": "my-custom-app-name",
+  "installDependencies": true,
+  "force": false,
+  "skipSubDir": false,
+  "environmentVariables": {
+    "SEEKA_APP_ID": "app-123",
+    "SEEKA_APP_SECRET": "secret-456"
+  },
+  "npmUsername": "npm-user",
+  "npmPassword": "npm-pass"
+}
+```
+
+### `ai context` - Manage AI Context
+
+Manages AI context files in your app repository.
+
+#### Usage
+
+```bash
+npx @seeka-labs/cli-apps ai context
+```
+
+#### Description
+
+This command copies the AI context files to `.seeka/ai/context/` in your app repository. The context includes:
+
+- Architecture documentation
+- Implementation guides
+- Example apps
+- Reference documentation
+
+The command will:
+1. Create `.seeka/ai/context/` directory if it doesn't exist
+2. Copy all AI context files
+3. Generate `meta.json` with SDK version information
+
+#### Output Structure
+
+```
+.seeka/
+└── ai/
+    └── context/
+        ├── meta.json
+        ├── README.md
+        ├── architecture/
+        ├── guides/
+        ├── reference/
+        └── examples/
+```
+
+## Interactive Mode
+
+Running the CLI without arguments starts interactive mode:
+
+```bash
+npx @seeka-labs/cli-apps
+```
+
+This will guide you through the app creation process with prompts.
+
+## Environment Variables
+
+The CLI respects these environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `SEEKA_CLI_CONFIG` | Default config file path |
+| `NPM_USERNAME` | Default NPM registry username |
+| `NPM_PASSWORD` | Default NPM registry password |
+
+## Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments |
+| 3 | Config file not found |
+| 4 | Template error |
+
+## Generated Files
+
+After running `init`, the following key files are created:
+
+### `.seeka/` Directory
+
+| File | Description |
+|------|-------------|
+| `init.app.seeka.cli.config.json` | Init configuration (committed) |
+| `init.app.secrets.seeka.cli.config.json` | Secrets (gitignored) |
+
+### Root Files
+
+| File | Description |
+|------|-------------|
+| `package.json` | Root package with workspaces |
+| `tsconfig.json` | TypeScript configuration |
+| `.yarnrc.yml` | Yarn configuration with NPM registry |
+| `README.md` | Project readme |
+
+### App Components
+
+| Directory | Description |
+|-----------|-------------|
+| `app/server/` | Server component (Azure Functions) |
+| `app/lib/` | Shared library |
+| `app/browser/` | Browser plugin (optional) |
+| `app/ui/` | Configuration UI (optional) |
+
+## Troubleshooting
+
+### Common Issues
+
+**"Directory is not empty"**
+```bash
+# Use --force to override
+npx @seeka-labs/cli-apps init my-org my-app --template azure-function --force ...
+```
+
+**"App name cannot start with seeka-app-"**
+```bash
+# Use a different name without the prefix
+npx @seeka-labs/cli-apps init my-org my-custom-app ...
+```
+
+**"Only azure-function template is supported"**
+```bash
+# Currently only azure-function is fully supported
+npx @seeka-labs/cli-apps init my-org my-app --template azure-function ...
+```
+
+**NPM authentication errors**
+```bash
+# Provide NPM credentials for browser plugin dependencies
+npx @seeka-labs/cli-apps init my-org my-app \
+  --npmUsername your-username \
+  --npmPassword your-password \
+  ...
+```
+
+## See Also
+
+- `../guides/getting-started.md` - Getting started guide
+- `../architecture/v3-structure.md` - Template structure
+- `config-schema.md` - Configuration file schemas

package/dist/ai-context/common/reference/config-schema.md

@@ -0,0 +1,345 @@
+# Configuration Schemas Reference
+
+This document describes the configuration file schemas used in Seeka apps.
+
+## CLI Configuration Files
+
+### init.app.seeka.cli.config.json
+
+Created by the CLI during app initialization. Stored in `.seeka/` directory.
+
+```json
+{
+  "appName": "my-app",
+  "orgName": "my-org",
+  "template": "azure-function",
+  "developerName": "My Company",
+  "developerEmail": "dev@mycompany.com",
+  "outputDirectory": "/path/to/output",
+  "directoryName": "my-app",
+  "installDependencies": true,
+  "force": false,
+  "skipSubDir": false,
+  "sdk": {
+    "version": "3.7.0"
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `appName` | string | Name of the app |
+| `orgName` | string | Organization name |
+| `template` | string | Template used: `azure-function`, `aws-lambda`, `netlify-function` |
+| `developerName` | string | Developer/company name |
+| `developerEmail` | string | Developer email |
+| `outputDirectory` | string | Directory where app was created |
+| `directoryName` | string | Name of the app directory |
+| `installDependencies` | boolean | Whether dependencies were installed |
+| `force` | boolean | Whether force flag was used |
+| `skipSubDir` | boolean | Whether skipSubDir flag was used |
+| `sdk.version` | string | SDK version used to create the app |
+
+### init.app.secrets.seeka.cli.config.json
+
+Stores sensitive configuration. **This file should be gitignored.**
+
+```json
+{
+  "environmentVariables": {
+    "SEEKA_APP_ID": "app-123",
+    "SEEKA_APP_SECRET": "secret-456",
+    "DATA_ENCRYPTION_KEY": "32-character-encryption-key"
+  }
+}
+```
+
+## Azure Functions Configuration
+
+### host.json
+
+Azure Functions host configuration.
+
+```json
+{
+  "version": "2.0",
+  "logging": {
+    "applicationInsights": {
+      "samplingSettings": {
+        "isEnabled": true,
+        "excludedTypes": "Request"
+      }
+    }
+  },
+  "extensionBundle": {
+    "id": "Microsoft.Azure.Functions.ExtensionBundle",
+    "version": "[4.*, 5.0.0)"
+  }
+}
+```
+
+### local.settings.json
+
+Local development settings. **This file should be gitignored.**
+
+```json
+{
+  "IsEncrypted": false,
+  "Values": {
+    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
+    "FUNCTIONS_WORKER_RUNTIME": "node",
+    "SEEKA_APP_ID": "your-app-id",
+    "SEEKA_APP_SECRET": "your-app-secret",
+    "DATA_ENCRYPTION_KEY": "your-32-character-encryption-key",
+    "SELF_HOST_BASEURL": "http://localhost:7071"
+  }
+}
+```
+
+| Variable | Description |
+|----------|-------------|
+| `AzureWebJobsStorage` | Azure Storage connection string |
+| `FUNCTIONS_WORKER_RUNTIME` | Runtime: `node` |
+| `SEEKA_APP_ID` | Your Seeka app ID |
+| `SEEKA_APP_SECRET` | Your Seeka app secret |
+| `DATA_ENCRYPTION_KEY` | 32-character encryption key |
+| `SELF_HOST_BASEURL` | Public URL of your app |
+
+### local.settings.template.json
+
+Template for local settings (committed to repo).
+
+```json
+{
+  "IsEncrypted": false,
+  "Values": {
+    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
+    "FUNCTIONS_WORKER_RUNTIME": "node",
+    "SEEKA_APP_ID": "",
+    "SEEKA_APP_SECRET": "",
+    "DATA_ENCRYPTION_KEY": "",
+    "SELF_HOST_BASEURL": "http://localhost:7071"
+  }
+}
+```
+
+## Package Configuration
+
+### Root package.json
+
+```json
+{
+  "name": "@my-org/my-app",
+  "version": "1.0.0",
+  "private": true,
+  "workspaces": [
+    "app/*"
+  ],
+  "scripts": {
+    "build": "yarn workspaces foreach -A run build",
+    "build:server": "yarn workspace @my-org/my-app-server run build",
+    "dev": "yarn workspace @my-org/my-app-server run dev",
+    "test": "yarn workspaces foreach -A run test"
+  }
+}
+```
+
+### Server package.json
+
+```json
+{
+  "name": "@my-org/my-app-server",
+  "version": "1.0.0",
+  "main": "dist/src/functions/*.js",
+  "scripts": {
+    "build": "tsc && yarn build:copy",
+    "build:copy": "node scripts/copy-assets.mjs",
+    "dev": "func start",
+    "test": "jest"
+  },
+  "dependencies": {
+    "@azure/functions": "^4.0.0",
+    "@seeka-labs/sdk-apps-server": "^3.0.0",
+    "@seeka-labs/sdk-apps-server-host": "^3.0.0",
+    "winston": "^3.0.0"
+  }
+}
+```
+
+## TypeScript Configuration
+
+### Root tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  }
+}
+```
+
+### Server tsconfig.json
+
+```json
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "."
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "references": [
+    { "path": "../lib" }
+  ]
+}
+```
+
+## AI Context Configuration
+
+### meta.json
+
+Generated in `.seeka/ai/context/` directory.
+
+```json
+{
+  "sdk": {
+    "version": "3.7.0"
+  }
+}
+```
+
+### exampleapps.context.json
+
+Configuration for importing example apps into AI context.
+
+```json
+[
+  {
+    "appDir": "/path/to/example-app",
+    "templateVersion": 3,
+    "name": "google-ads-push",
+    "template": "azurefunc",
+    "components": ["server"],
+    "description": "Pushes conversion data to Google Ads",
+    "tags": ["conversion-api", "ads-platform"]
+  },
+  {
+    "appDir": "../relative/path/app",
+    "templateVersion": 2,
+    "name": "meta-capi",
+    "template": "azurefunc",
+    "components": ["server", "browser"],
+    "description": "Meta Conversions API integration",
+    "tags": ["conversion-api", "ads-platform"]
+  }
+]
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `appDir` | string | Absolute or relative path to the app |
+| `templateVersion` | number | Template version: 1, 2, or 3 |
+| `name` | string | Name for the example in AI context |
+| `template` | string | Server template: `azurefunc`, `netlifyfunc`, `awslambda` |
+| `components` | string[] | Components: `server`, `browser`, `ui` |
+| `description` | string | Description of the app's functionality |
+| `tags` | string[] | Tags for categorization |
+
+## GitHub Actions Configuration
+
+### deploy-azurefunc.yml
+
+```yaml
+name: Deploy Azure Function
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+env:
+  AZURE_FUNCTIONAPP_NAME: 'my-app-func'
+  AZURE_FUNCTIONAPP_PACKAGE_PATH: 'app/server'
+  NODE_VERSION: '20.x'
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Install dependencies
+        run: yarn install
+
+      - name: Build
+        run: yarn build
+
+      - name: Deploy to Azure
+        uses: Azure/functions-action@v1
+        with:
+          app-name: ${{ env.AZURE_FUNCTIONAPP_NAME }}
+          package: ${{ env.AZURE_FUNCTIONAPP_PACKAGE_PATH }}
+          publish-profile: ${{ secrets.AZURE_FUNCTIONAPP_PUBLISH_PROFILE }}
+```
+
+## Yarn Configuration
+
+### .yarnrc.yml
+
+```yaml
+nodeLinker: node-modules
+
+npmScopes:
+  seeka-labs:
+    npmAuthIdent: "username:password"
+    npmAlwaysAuth: true
+    npmRegistryServer: "https://npm.packages.seeka.services"
+```
+
+## Environment Variables Reference
+
+### Required Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `SEEKA_APP_ID` | Unique app identifier | `app-abc123` |
+| `SEEKA_APP_SECRET` | Secret for webhook validation | `secret-xyz789` |
+| `DATA_ENCRYPTION_KEY` | 32-char key for encrypting data | `abcdef1234567890abcdef1234567890` |
+
+### Azure-Specific Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AzureWebJobsStorage` | Azure Storage connection string |
+| `FUNCTIONS_WORKER_RUNTIME` | Set to `node` |
+| `WEBSITE_NODE_DEFAULT_VERSION` | Node.js version |
+
+### Optional Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SELF_HOST_BASEURL` | Public URL of the app | - |
+| `LOG_LEVEL` | Logging level | `info` |
+
+## See Also
+
+- `cli-commands.md` - CLI command reference
+- `sdk-api.md` - SDK API reference
+- `../architecture/v3-structure.md` - Template structure