diff --git a/TEMPLATES.md b/TEMPLATES.md index 290d28f..72082d4 100644 --- a/TEMPLATES.md +++ b/TEMPLATES.md @@ -666,12 +666,76 @@ echo "Installation of ${CONTAINER_NAME} complete" 4. **Handle cleanup** properly in stop.sh and uninstall.sh using `docker compose down` 5. **Use named volumes** for persistent data that matches Dropshell conventions -## Testing Templates +## Validating Templates -After creating a template, validate it: +Dropshell includes a comprehensive template validation command that checks for common issues: ```bash -dropshell test-template /path/to/template +dropshell validate ``` -This checks all requirements and reports any issues. \ No newline at end of file +Aliases: `ds lint`, `ds check-template` + +### What Validate Checks + +1. **Structure Validation** + - Required files exist (`install.sh`, `uninstall.sh`, `config/service.env`, `config/.template_info.env`) + - Scripts are executable + - `TEMPLATE` variable matches directory name + +2. **Shell Script Linting (via Shellcheck)** + - Runs [shellcheck](https://www.shellcheck.net/) on all `.sh` files + - Catches common bash issues: quoting, syntax errors, unused variables, etc. + - Runs in a Docker container (`koalaman/shellcheck:stable`) - no host installation required + +3. **Dropshell-Specific Checks** + - Main scripts (`install.sh`, `uninstall.sh`, `start.sh`, `stop.sh`, `status.sh`) source `common.sh` + +### Example Output + +``` +$ ds validate my-template + +=== Structure Validation === + ✓ Template structure is valid + +=== Shellcheck Linting === + ✓ install.sh + ✓ uninstall.sh + ✓ start.sh + status.sh:14:33: warning: Double quote to prevent globbing. [SC2086] + +=== Dropshell: common.sh sourcing === + ✓ Sources common.sh: install.sh + ✓ Sources common.sh: uninstall.sh + ⚠ Missing 'source "${AGENT_PATH}/common.sh"' in start.sh + +Validation Summary: Template 'my-template' has 2 warning(s) +``` + +### Pre-Install Validation + +The `install` command automatically runs basic syntax checking (`bash -n`) on all template scripts before deploying. If any script has a syntax error, the install fails with a clear message: + +``` +[ERR] Template shell scripts have syntax errors. Run 'ds validate my-template' for details. +``` + +### Suppressing Shellcheck Warnings + +If shellcheck reports a false positive, you can suppress it with a comment: + +```bash +# shellcheck disable=SC2034 # Variable used by sourced script +MY_VAR="value" +``` + +Place the disable comment on the line before the flagged code. See [shellcheck wiki](https://github.com/koalaman/shellcheck/wiki/Ignore) for more options. + +### Best Practices + +1. **Run validate before publishing** - Ensure your template passes all checks +2. **Fix warnings, not just errors** - Warnings often indicate real issues +3. **Source common.sh in all main scripts** - Provides `_die`, `_check_docker_installed`, etc. +4. **Quote variables** - Especially in paths and test expressions +5. **Add error handling** - Use `|| _die "message"` after commands that can fail \ No newline at end of file diff --git a/source/src/commands/help.cpp b/source/src/commands/help.cpp index 4c8238d..b04b4e9 100644 --- a/source/src/commands/help.cpp +++ b/source/src/commands/help.cpp @@ -153,6 +153,9 @@ int help_handler(const CommandContext& ctx) { info << std::endl; show_command("create-server"); show_command("create-service"); + show_command("create-template"); + info << std::endl; + show_command("validate"); } return 0; }