enonic-app-manager

What this skill does

# Enonic CLI & Local Dev Environment Helper

## Procedures

**Step 1: Detect Workspace Context**
1. Execute `node scripts/find-enonic-targets.mjs` from the skill root to scan the current workspace for Enonic project markers (`.enonic`, `build.gradle` with `com.enonic.xp` plugin, `gradle.properties` with `xpVersion`).
2. If markers are found, note the project name, linked sandbox, and XP version from the output. Use these values as defaults for subsequent commands.
3. If no markers are found, treat the request as a greenfield setup and proceed to sandbox creation or project scaffolding as appropriate.

**Step 2: Ensure CLI is Available**
1. Verify the Enonic CLI is installed by running `enonic --version`.
2. If the command fails, read `references/cli-reference.md` for installation instructions and guide through the appropriate method for the detected OS:
   - **npm (any OS):** `npm install -g @enonic/cli`
   - **macOS:** `brew tap enonic/cli && brew install --no-quarantine enonic`
   - **Linux:** `wget -qO- https://repo.enonic.com/public/com/enonic/cli/installer/cli-linux/1.0.0/cli-linux-1.0.0.sh | sh`
   - **Windows:** `scoop bucket add enonic https://github.com/enonic/cli-scoop.git && scoop install enonic`
3. After installation, verify with `enonic --version`.

**Step 3: Sandbox Management**
1. Read `references/cli-reference.md` for the full sandbox command catalog.
2. Match the request to the correct operation:
   - **Create:** `enonic sandbox create <name> [-v <version>] [-t <template>] [--skip-template] [-i <image>] [-f]`
   - **List:** `enonic sandbox ls`
   - **Start:** `enonic sandbox start <name> [--detach] [--prod] [--debug]`
   - **Stop:** `enonic sandbox stop`
   - **Upgrade:** `enonic sandbox upgrade <name> -v <version>`
   - **Delete:** `enonic sandbox delete <name> -f`
   - **Copy:** `enonic sandbox copy <source> <target>`
3. When creating a sandbox, prompt for the XP version if not specified. Use `-f` flag for non-interactive execution when the version and name are known. Note: with `-f`, the sandbox auto-starts after creation unless `--skip-start` is also provided.
4. If the request mentions templates, list available templates or use `-t <template>` flag. Use `--skip-template` to create a bare sandbox with no pre-installed apps.
5. If the request mentions Docker, use `-i <image>` (e.g., `enonic/xp:latest-sdk`) to back the sandbox with a Docker image instead of a downloaded XP distribution. Requires `docker` on `$PATH`.

**Step 4: Project Scaffolding**
1. For new project creation, use the simplified command: `enonic create <name> [-r <starter>] [-s <sandbox>] [-f]`
2. Common starters include `starter-vanilla`, `starter-headless`, and `starter-nextjs`. Read `references/cli-reference.md` for the full list of options.
3. To link an existing project to a different sandbox: `enonic project sandbox <name>`
4. Ensure the project folder contains `build.gradle` and `.enonic` configuration after creation.

**Step 5: Development Workflow**
1. Determine the appropriate development command:
   - **Dev mode (hot-reload):** `enonic dev` — starts the sandbox in detached mode and runs the app with file watching. Execute from the project root.
   - **Build only:** `enonic project build`
   - **Deploy to sandbox:** `enonic project deploy [sandbox-name] [-c]` — use `-c` for continuous deployment.
   - **Install to running XP:** `enonic project install`
   - **Run tests:** `enonic project test`
   - **Clean build artifacts:** `enonic project clean`
   - **Arbitrary Gradle task:** `enonic project gradle <tasks>`
2. If the sandbox is not running, start it first: `enonic sandbox start <name> -d`
3. To terminate dev mode, use `Ctrl-C`. The CLI will attempt to stop the detached sandbox automatically.

**Step 6: App Management on Running XP**
1. For managing applications on a running XP instance, read `references/cli-reference.md` for the XP app commands.
2. Match the operation:
   - **Install from URL:** `enonic app install --url <jar-url>`
   - **Install from file:** `enonic app install --file <path-to-jar>`
   - **Start app:** `enonic app start <app-key>`
   - **Stop app:** `enonic app stop <app-key>`
3. Authentication is required for XP commands. Use `--cred-file <path>` (XP 7.15+), `--client-key <path>` + `--client-cert <path>` for mTLS (XP 7.15+), or set `ENONIC_CLI_REMOTE_USER` and `ENONIC_CLI_REMOTE_PASS` environment variables.

**Step 7: CI/CD Pipeline Generation**
1. Read `assets/enonic-ci.template.yml` for the GitHub Actions workflow template.
2. Customize the template based on the project:
   - Set the correct XP version in the sandbox creation step.
   - Set the app name and Gradle build parameters.
   - Configure deployment targets (sandbox for staging, cloud for production).
3. Place the generated workflow file at `.github/workflows/enonic-ci.yml` in the project repository.

**Step 8: Troubleshooting**
1. If a sandbox fails to start or a deployment fails, read `references/troubleshooting.md` for common issues and resolutions.
2. Key diagnostic commands:
   - `enonic sandbox ls` — check sandbox status and XP version.
   - `enonic system info` — check running XP instance details.
   - Check port `8080` (HTTP) and `5005` (debug) availability.
3. Read `references/compatibility.md` for CLI-to-XP version compatibility if version mismatch errors occur.

## Error Handling
* If `scripts/find-enonic-targets.mjs` returns no results, proceed with greenfield setup instructions rather than failing.
* If `enonic --version` fails, guide through CLI installation per Step 2 before proceeding.
* If sandbox creation fails with a version error, read `references/compatibility.md` and suggest a compatible XP version.
* If port conflicts occur during sandbox start, read `references/troubleshooting.md` for resolution steps.
* If `enonic dev` fails, verify the project has a Gradle `dev` task (present in all official starters) and that the linked sandbox exists and is not already running in another terminal.