setup-generate · git:20260404.825e38f · 2026-04-04 · sha256 4497481f432c1555
setup-generate git:20260404.825e38fC
Immutable. This exact content is served forever at /api/v1/blob/4497481f432c1555.
# 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]"
## 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`.
### --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?
### Phase 2: Assemble Manifest
Build the manifest YAML following this priority order:
1. **platform block** — from `--platforms` or detected by project type
2. **params block** — standard params: `INSTALL_DIR`, `BRANCH` (default: `main`); add `CONFIG_DIR` if a config step is needed
3. **prerequisites block** — from project type (e.g., `node` for npm projects, `python3` for Python)
4. **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
5. **recovery_procedures block** — always include a `full-reset` fallback
### 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 projects**:
- `installer/scripts/check-ports.sh` — port availability check before deploy
- `installer/scripts/pull-models.sh` — Ollama model pull after deploy (when applicable)
### Phase 3: Script Assembly
For each script step:
1. Copy the relevant template from `agentic/code/addons/agentic-installer/scripts/templates/`
2. Place in `<project>/installer/scripts/`
3. Customize placeholders (package lists, config paths, etc.)
4. Record relative path in the manifest `script:` field
### Phase 4: Output
Write `setup.manifest.yaml` to the project root (or `installer/setup.manifest.yaml` if `installer/` dir exists).
Report:
```
Generated: setup.manifest.yaml
Platform: linux, macos
Params: INSTALL_DIR, BRANCH
Prerequisites: git, node (>=18)
Steps: clone, install-deps-ubuntu, install-deps-macos, configure, verify
Recovery: full-reset
Scripts: installer/scripts/ (3 files)
Validate with: aiwg setup-validate
Run with: aiwg setup-run
```
## Script-First Rule
Every step that can be scripted MUST be a `script` step. Only use `type: agentic` for:
- Steps that require real-time environment inspection that cannot be expressed in bash
- Recovery from unexpected failures where the script approach has been exhausted
## Example Output
```yaml
apiVersion: setup.aiwg.io/v1
kind: SetupManifest
metadata:
name: myapp
version: 1.0.0
description: Install myapp and configure default settings
platform:
os: [linux, macos]
distros: [ubuntu, debian, fedora]
arch: [x86_64, arm64]
shell: [bash, zsh]
params:
- name: INSTALL_DIR
type: path
required: true
description: Installation directory
- name: BRANCH
type: string
default: main
description: Git branch to clone
prerequisites:
- detect: "command -v git"
version_min: "2.30"
install_hint: "Install git: https://git-scm.com"
- detect: "command -v node"
version_min: "18.0"
install_hint: "Install Node.js: https://nodejs.org"
steps:
- id: clone
type: script
script: installer/scripts/clone.sh
verify: "test -d ${INSTALL_DIR}/.git"
- id: install-deps
type: platform-route
routes:
ubuntu: installer/scripts/install-deps-ubuntu.sh
debian: installer/scripts/install-deps-ubuntu.sh
fedora: installer/scripts/install-deps-fedora.sh
macos: installer/scripts/install-deps-macos.sh
depends_on: [clone]
- id: configure
type: script
script: installer/scripts/configure.sh
depends_on: [install-deps]
when: "test ! -f ${CONFIG_DIR}/config.conf"
- id: verify
type: script
script: installer/scripts/verify.sh
depends_on: [configure]
recovery_procedures:
- id: full-reset
description: Remove and re-clone the installation
triggers: [clone, configure]
script: installer/scripts/reset.sh
```
## References
- Schema: `agentic/code/addons/agentic-installer/schemas/v1/setup-manifest.schema.json`
- Templates: `agentic/code/addons/agentic-installer/scripts/templates/`
- Run skill: `agentic/code/addons/agentic-installer/skills/setup-run/SKILL.md`
- Validate skill: `agentic/code/addons/agentic-installer/skills/setup-validate/SKILL.md`