setup-generate

What this skill does

# setup-generate

Generate a `setup.manifest.yaml` file for a project using the `setup.aiwg.io/v1` SetupManifest language.

## Trigger Phrases

- "generate a setup manifest for [project]"
- "create installer for [project]"
- "scaffold setup manifest"
- "write a setup.manifest.yaml for [directory]"
- "generate install workflow for [project]"
- "generate dev installer for [project]"

## Parameters

### project-dir (positional, optional)
Path to the project root. Defaults to `.`.

### --from-readme (optional)
Extract requirements from `README.md` or `INSTALL.md` in the project dir.

### --from-existing (optional)
Update an existing `setup.manifest.yaml` rather than creating from scratch.

### --platforms (optional)
Comma-separated list of target platforms: `linux,macos,windows,wsl2`.
Default: `linux,macos`.

### --type (optional)
Install type to generate: `user`, `developer`, or `ci`.
Default: `user`.

- `user` — production/end-user deployment (default, behavior unchanged from previous versions)
- `developer` — local development environment standup with OS configuration
- `ci` — headless pipeline setup

When `--type developer`, output filename is `setup.dev.manifest.yaml`. When `--type user`, output is `setup.user.manifest.yaml` (or `setup.manifest.yaml` if no type is specified for backwards compatibility).

### --interactive (optional)
Ask clarifying questions before generating.

## Execution Flow

### Phase 1: Discovery

1. Read the project root to understand structure:
   - Check for `package.json`, `requirements.txt`, `Cargo.toml`, `go.mod`, `Makefile`, etc.
   - Check for `README.md`, `INSTALL.md`, `docs/install.md`
   - Check for existing `setup.manifest.yaml`
2. If `--from-readme`, parse installation instructions from readme
3. If `--interactive`, ask:
   - What OSes must be supported?
   - What are the hard prerequisites (git, node, python version)?
   - Is there a config directory that needs to be created?
   - Does the project chain sub-projects?

#### Developer Install Discovery (when `--type developer`)

Additional discovery steps for developer manifests:

1. Scan for dev-specific indicators: `.nvmrc`, `.tool-versions`, `mise.toml`, `pyproject.toml [dev]`, `Brewfile`, `.devcontainer/`
2. Detect Docker-in-dev usage patterns (bind mounts, live reload, `--watch` flags)
3. If `--interactive` or key information is absent, ask mandatory interactive questions:
   - "What OS(es) do developers use? (linux/macos/windows)"
   - "Is there a local domain for HTTPS development? (e.g., myapp.local)"
   - "Do developers need GPU access for local dev? (yes/no)"
   - "Is SSH key setup required as a project prerequisite? (yes/no)"
   - "Which IDE(s) are standard? (vscode/jetbrains/none)"
   - "Any kernel/OS parameters required? (inotify watches, vm.max_map_count, etc.)"
   - "Does the project use a local certificate authority for HTTPS dev?"

### Phase 2: Assemble Manifest

Build the manifest YAML following this priority order:

1. **metadata block** — include `install_type` matching `--type` flag (default: `user`)
2. **platform block** — from `--platforms` or detected by project type
3. **params block** — standard params: `INSTALL_DIR`, `BRANCH` (default: `main`); add `CONFIG_DIR` if a config step is needed
4. **prerequisites block** — from project type (e.g., `node` for npm projects, `python3` for Python)
5. **steps block** — construct from script templates:
   - Always start with a `clone` or `verify-existing` detect step
   - Add `install-deps-*` steps for each target platform
   - Add `configure` step if config files are needed
   - End with a `verify` step
6. **recovery_procedures block** — always include a `full-reset` fallback

#### Developer Manifest Assembly Rules (when `--type developer`)

When assembling developer manifests, apply these additional rules:

**os_config block** — emit entries based on detection:

| Condition | Entry |
|-----------|-------|
| Linux + Docker in project | `docker-group` (requires_relogin: true) |
| Linux + file watchers detected (webpack/jest/vite/nodemon) | `inotify-watches` |
| Linux + Elasticsearch/Weaviate/OpenSearch detected | `vm-mapcount` |
| macOS | `xcode-cli-tools` (interactive: true) |
| HTTPS dev + local domain | mkcert install step (not os_config, but a script step) |
| GPU dev | `nvidia-container-toolkit` os_config entry |

**params** — emit with `interactive_required: true` for:
- `LOCAL_DOMAIN` — when HTTPS dev or local domain detected
- `SSH_EMAIL` — when SSH key setup is required
- `GIT_USER_NAME`, `GIT_USER_EMAIL` — when git config step is included
- `GIT_GPG_KEY_ID` — when GPG signing is requested
- `IDE` — when IDE-specific extension installation is included

**steps** — emit os-config steps for each os_config entry:
```yaml
- id: apply-docker-group
  type: os-config
  config_id: docker-group
  depends_on: [install-docker]
  platform: linux
```

**dev-specific prerequisites** — add as detected:
- `nvm` or `mise` — when `.nvmrc` or `.tool-versions` found
- `mkcert` — when HTTPS dev requested
- `act` — when GitHub Actions local testing detected

### Docker-based Project Detection

When `docker-compose.yml` or `compose.yaml` is found during Phase 1 discovery, apply these additional behaviors:

**Platform** (#676):
- Include `macos` in the platform block alongside `linux` — Docker Desktop covers both.
- Any GPU or nvidia steps must add `when: "$(uname -s) = Linux"` so they are skipped on macOS.
- Update `install_hint` for docker prereqs to include macOS install links.

**Prerequisites** (#672, #674):
- Replace `command -v docker` with `docker version --format '{{.Server.Version}}' 2>/dev/null` to catch both "not installed" and "installed but no permission" cases.
- Expand the docker `install_hint` to mention `sudo usermod -aG docker $USER`.
- When Docker images or ML models are present, add disk space prereq (≥20GB free):
  ```yaml
  - name: disk-space
    detect: "df --output=avail -BG / | tail -1 | tr -d ' G'"
    version_min: "20"
    install_hint: "At least 20GB free disk space required for Docker images."
  ```
- When ML models are detected (Ollama, HuggingFace, etc.), add RAM prereq (≥8GB):
  ```yaml
  - name: ram
    detect: "awk '/MemTotal/ {printf \"%.0f\", $2/1024/1024}' /proc/meminfo"
    version_min: "8"
    install_hint: "At least 8GB RAM recommended. 16GB+ for GPU profiles."
  ```

**Params** (#671, #675):
- When a `DOMAIN` or `ISSUER_URL` param is emitted, also emit a `PROTOCOL` param with a smart default:
  ```yaml
  - name: PROTOCOL
    type: choice
    choices: [http, https]
    default: "$(echo ${DOMAIN} | grep -qE '^(localhost|127\\.0\\.0\\.1)' && echo http || echo https)"
    description: "Protocol for OAuth/API URLs. Defaults to http for localhost."
  ```
  Then reference `${PROTOCOL}://${DOMAIN}` in configure.sh instead of hardcoding `https://`.
- Default `DATA_DIR` to `${INSTALL_DIR}/data` (project-local, user-writable) rather than any system path like `/var/lib/<project>`. If the project explicitly requires a system path, emit a `check-data-dir` step (see steps below).

**Steps** (#673, #675, #677):
- Emit a `check-ports` step before `deploy` that validates all ports declared in the compose file are free:
  ```yaml
  - id: check-ports
    type: script
    script: installer/scripts/check-ports.sh
    depends_on: [configure]
  ```
- When the default `DATA_DIR` is a system path, emit a `check-data-dir` step before `configure`:
  ```yaml
  - id: check-data-dir
    type: script
    script: installer/scripts/check-data-dir.sh
    depends_on: [clone]
  ```
- When Ollama is detected in the compose file or `.env` template, emit a `pull-models` step after `deploy`:
  ```yaml
  - id: pull-models
    type: script
    description: Pull Ollama models (may take several minutes)
    script: installer/scripts/pull-models.sh
    depends_on: [deploy]
    verify: "docker exec $(docker compose ps -q ollama) ollama list | grep -q ${OLLAMA_GEN_MODEL%%:*}"
  ```

**Script templates used for Docker pr