Improve

Author: dbpolito

commands/run_test.go

@@ -1,6 +1,7 @@
 package commands
 
 import (
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
@@ -745,3 +746,50 @@ func TestNewRunCommandWithTypoErrorCancelled(t *testing.T) {
 		t.Errorf("expecting warning '%s', got '%s'", expected, output)
 	}
 }
+
+func TestNewRunCommandJsonOutput(t *testing.T) {
+	f := newFakeKoolRun(nil, nil)
+	f.parser.(*parser.FakeParser).MockScriptDetails = []parser.ScriptDetail{
+		{
+			Name:     "setup",
+			Comments: []string{"Sets up dependencies"},
+			Commands: []string{"kool run composer install"},
+		},
+		{
+			Name:     "lint",
+			Comments: []string{},
+			Commands: []string{"kool run go:linux fmt ./..."},
+		},
+	}
+
+	cmd := NewRunCommand(f)
+	cmd.SetArgs([]string{"--json"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Errorf("unexpected error executing run command with --json; error: %v", err)
+	}
+
+	if !f.parser.(*parser.FakeParser).CalledParseAvailableDetails {
+		t.Error("did not call ParseAvailableScriptsDetails")
+	}
+
+	fakeShell := f.shell.(*shell.FakeShell)
+
+	if len(fakeShell.OutLines) == 0 {
+		t.Error("expected JSON output")
+		return
+	}
+
+	var output []parser.ScriptDetail
+	if err := json.Unmarshal([]byte(fakeShell.OutLines[0]), &output); err != nil {
+		t.Fatalf("failed to parse json output: %v", err)
+	}
+
+	if len(output) != 2 {
+		t.Fatalf("expected 2 script entries, got %d", len(output))
+	}
+
+	if output[0].Name != "lint" || output[1].Name != "setup" {
+		t.Errorf("unexpected scripts order or names: %v", output)
+	}
+}

skills/kool/SKILL.md

@@ -1,39 +1,106 @@
 ---
 name: kool
-description: Discovers and runs project scripts with the kool CLI. Use when the user wants to list custom commands from kool.yml, understand project tasks, or run kool scripts. Use --json flag for machine-readable output.
+description: Docker development environment CLI. Use for managing containers (start/stop/restart), executing commands in services, viewing logs, and running project scripts from kool.yml.
 ---
 
 # Kool CLI
 
-Use kool to discover and run project scripts defined in `kool.yml`.
+Kool simplifies Docker-based development with commands for container lifecycle, service execution, and custom scripts.
 
-## Quick Start
+## Quick Reference
 
 ```bash
-kool run --json        # List scripts as JSON
-kool run <script>      # Run a script
+kool start                    # Start all services from docker-compose.yml
+kool stop                     # Stop all services
+kool restart --rebuild        # Restart and rebuild images
+kool status                   # Show running containers
+kool exec <service> <cmd>     # Run command in service container
+kool logs -f <service>        # Follow service logs
+kool run --json               # List available scripts as JSON
+kool run <script>             # Run a script from kool.yml
 ```
 
-## Core Workflow
+## Service Lifecycle
 
-1. Work from the project root (has `kool.yml`) or use `-w` to point to it.
-2. Discover scripts:
+Services are defined in `docker-compose.yml`. Kool wraps docker-compose with simpler commands.
 
 ```bash
-kool run --json   # Preferred: returns [{name, comments, commands}]
-kool run          # Human-readable list
+kool start                    # Start all services
+kool start app database       # Start specific services
+kool start --rebuild          # Rebuild images before starting
+kool start --foreground       # Run in foreground (see logs)
+kool start --profile worker   # Enable a docker-compose profile
+
+kool stop                     # Stop all services
+kool stop app                 # Stop specific service
+kool stop --purge             # Stop and remove volumes (destructive)
+
+kool restart                  # Restart all services
+kool restart --rebuild        # Rebuild images on restart
+kool restart --purge          # Purge volumes on restart
+
+kool status                   # Show status of all containers
+```
+
+## Executing Commands in Containers
+
+Use `exec` to run commands inside running service containers (like SSH).
+
+```bash
+kool exec <service> <command>
+kool exec app bash                      # Interactive shell
+kool exec app php artisan migrate       # Run Laravel migration
+kool exec app npm install               # Install npm packages
+kool exec -e VAR=value app env          # With environment variable
 ```
 
-3. Run scripts:
+## One-off Docker Containers
+
+Use `docker` to run commands in temporary containers (not services).
+
+```bash
+kool docker <image> <command>
+kool docker node npm init                           # Run npm in node container
+kool docker --volume=$PWD:/app golang go build      # Mount current dir
+kool docker --env=DEBUG=1 python python script.py  # With env var
+kool docker --publish=3000:3000 node npm start      # Expose port
+```
+
+## Viewing Logs
+
+```bash
+kool logs                     # Last 25 lines from all services
+kool logs app                 # Logs from specific service
+kool logs -f                  # Follow logs (live)
+kool logs -f app worker       # Follow multiple services
+kool logs --tail 100          # Last 100 lines
+kool logs --tail 0            # All logs
+```
+
+## Project Scripts
+
+Scripts are defined in `kool.yml` and provide project-specific commands.
+
+```bash
+kool run --json               # List scripts as JSON [{name, comments, commands}]
+kool run                      # List scripts (human-readable)
+kool run <script>             # Run a script
+kool run <script> -- <args>   # Pass args (single-line scripts only)
+kool run -e VAR=1 <script>    # Run with environment variable
+```
+
+## Global Options
+
+All commands support:
 
 ```bash
-kool run <script>
-kool run <script> -- <args>
+-w, --working_dir <path>      # Run from different directory
+--verbose                     # Increase output verbosity
 ```
 
 ## Important Rules
 
-- **ALWAYS** run commands from the project root or use `-w/--working_dir`.
-- **ONLY** pass extra args to single-line scripts; multi-line scripts reject extra args.
-- **REMEMBER** `kool.yml` scripts are not full bash (no pipes/conditionals); use `kool docker <image> bash -c "..."` for complex shell logic.
-- **CHECK** `kool.yml` or `kool.yaml` in the project root and `~/kool` for shared scripts.
+- **ALWAYS** run from project root (has `docker-compose.yml` and `kool.yml`) or use `-w`.
+- **Service names** come from `docker-compose.yml` service definitions.
+- **Script args** only work with single-line scripts; multi-line scripts reject extra args.
+- **Scripts** in `kool.yml` are not full bash - use `kool docker <image> bash -c "..."` for pipes/conditionals.