feat: add docker sandbox test/playground workflows and docs

This commit is contained in:
Willie
2026-02-07 21:55:20 +08:00
parent bf41422659
commit 080e29e0ff
21 changed files with 1971 additions and 28 deletions
+8
View File
@@ -0,0 +1,8 @@
.git
bin
dist
coverage.out
.claude
docs/plans
website/node_modules
video/node_modules
+77
View File
@@ -0,0 +1,77 @@
.PHONY: help build build-meta run test test-unit test-int test-cover test-install test-docker test-docker-online sandbox-up sandbox-shell sandbox-down lint fmt fmt-check check install clean
help:
@echo "Common tasks:"
@echo " make build # build binary"
@echo " make run # run local binary help"
@echo " make test # unit + integration tests"
@echo " make test-unit # unit tests only"
@echo " make test-int # integration tests only"
@echo " make test-cover # tests with coverage"
@echo " make test-install # install.sh sandbox tests"
@echo " make test-docker # docker offline sandbox (build + unit + integration)"
@echo " make test-docker-online # optional docker online install/update tests"
@echo " make sandbox-up # start persistent docker playground"
@echo " make sandbox-shell # enter docker playground shell"
@echo " make sandbox-down # stop and remove docker playground"
@echo " make lint # go vet"
@echo " make fmt # format Go files"
@echo " make fmt-check # verify formatting only"
@echo " make check # fmt-check + lint + test"
@echo " make clean # remove build artifacts"
build:
mkdir -p bin && go build -o bin/skillshare ./cmd/skillshare
build-meta:
./scripts/build.sh
run: build
./bin/skillshare --help
test:
./scripts/test.sh
test-unit:
./scripts/test.sh --unit
test-int:
./scripts/test.sh --int
test-cover:
./scripts/test.sh --cover
test-install:
./scripts/test_install.sh
test-docker:
./scripts/test_docker.sh
test-docker-online:
./scripts/test_docker_online.sh
sandbox-up:
./scripts/sandbox_playground_up.sh
sandbox-shell:
./scripts/sandbox_playground_shell.sh
sandbox-down:
./scripts/sandbox_playground_down.sh
lint:
go vet ./...
fmt:
gofmt -w ./cmd ./internal ./tests
fmt-check:
test -z "$$(gofmt -l ./cmd ./internal ./tests)"
check: fmt-check lint test
install:
go install ./cmd/skillshare
clean:
rm -rf bin coverage.out
+83
View File
@@ -153,6 +153,88 @@ Done. Your skills are now synced across all AI CLI tools.
| `doctor` | Diagnose issues |
| `upgrade` | Upgrade CLI and skill |
## Docker Sandbox Testing
Use Docker to run reproducible tests in an isolated environment.
Guide: [Docker Sandbox Guide](https://skillshare.runkids.cc/docs/guides/docker-sandbox)
With `mise`:
```bash
mise run test:docker
```
With `make`:
```bash
make test-docker
```
This offline sandbox runs Go `build + unit + integration` with `network_mode: none`.
It covers install/update flows based on local paths and `file://` git repositories.
Run optional network-dependent install/update checks separately:
With `mise`:
```bash
mise run test:docker:online
```
With `make`:
```bash
make test-docker-online
```
You can also pass custom commands:
```bash
./scripts/test_docker.sh --cmd "go test -v ./tests/integration/..."
./scripts/test_docker_online.sh --cmd "go test -v -tags online ./tests/integration/... -run TestInstall_Remote"
```
### Interactive Playground
Use a dedicated persistent container for manually exploring skillshare commands.
With `mise`:
```bash
mise run sandbox:up
mise run sandbox:shell
```
With `make`:
```bash
make sandbox-up
make sandbox-shell
```
Inside the container you can run directly (no manual build needed):
```bash
skillshare --help
ss --help
skillshare init --dry-run
```
Stop the playground when done:
With `mise`:
```bash
mise run sandbox:down
```
With `make`:
```bash
make sandbox-down
```
## Documentation
📖 **Full documentation at [skillshare.runkids.cc](https://skillshare.runkids.cc/docs/intro)**
@@ -164,6 +246,7 @@ Done. Your skills are now synced across all AI CLI tools.
| [Project Skills](https://skillshare.runkids.cc/docs/guides/project-setup) | Project-level skills setup |
| [Organization Skills](https://skillshare.runkids.cc/docs/guides/organization-sharing) | Organization-wide sharing with tracked repos |
| [Cross-machine](https://skillshare.runkids.cc/docs/guides/cross-machine-sync) | Multi-machine sync |
| [Docker Sandbox](https://skillshare.runkids.cc/docs/guides/docker-sandbox) | Test sandbox and interactive playground |
| [FAQ](https://skillshare.runkids.cc/docs/troubleshooting/faq) | FAQ & troubleshooting |
---
+60
View File
@@ -0,0 +1,60 @@
services:
sandbox-offline:
profiles:
- offline
build:
context: .
dockerfile: docker/sandbox/Dockerfile
working_dir: /workspace
command:
- ./scripts/test.sh
network_mode: none
environment:
HOME: /tmp
GOCACHE: /go/build-cache
volumes:
- .:/workspace
- go-mod-cache:/go/pkg/mod
- go-build-cache:/go/build-cache
sandbox-online:
profiles:
- online
build:
context: .
dockerfile: docker/sandbox/Dockerfile
working_dir: /workspace
command:
- ./scripts/test.sh
environment:
HOME: /tmp
GOCACHE: /go/build-cache
volumes:
- .:/workspace
- go-mod-cache:/go/pkg/mod
- go-build-cache:/go/build-cache
sandbox-playground:
profiles:
- playground
build:
context: .
dockerfile: docker/sandbox/Dockerfile
working_dir: /workspace
command:
- sleep
- infinity
environment:
HOME: /sandbox-home
GOCACHE: /go/build-cache
PATH: /sandbox-home/.local/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
volumes:
- .:/workspace
- go-mod-cache:/go/pkg/mod
- go-build-cache:/go/build-cache
- playground-home:/sandbox-home
volumes:
go-mod-cache:
go-build-cache:
playground-home:
+13
View File
@@ -0,0 +1,13 @@
FROM golang:1.25.5-bookworm
RUN apt-get update \
&& apt-get install -y --no-install-recommends bash git ca-certificates \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /workspace
COPY go.mod go.sum ./
RUN go mod download
RUN mkdir -p /go/build-cache /go/pkg/mod && chmod -R 0777 /go/build-cache /go/pkg/mod
CMD ["bash", "-c", "./scripts/test.sh"]
+25
View File
@@ -12,6 +12,11 @@ echo " mise run test:unit # unit tests only"
echo " mise run test:int # integration tests only"
echo " mise run test:cover # tests with coverage"
echo " mise run test:install # install.sh sandbox tests"
echo " mise run test:docker # docker offline sandbox (build + unit + integration)"
echo " mise run test:docker:online # optional docker online install/update tests"
echo " mise run sandbox:up # start persistent docker playground"
echo " mise run sandbox:shell # enter docker playground shell"
echo " mise run sandbox:down # stop and remove docker playground"
echo " mise run lint # go vet"
echo " mise run fmt # format Go files"
echo " mise run fmt:check # verify formatting only"
@@ -52,6 +57,26 @@ run = "./scripts/test.sh --cover"
description = "Run install.sh sandbox tests"
run = "./scripts/test_install.sh"
[tasks."test:docker"]
description = "Run tests in offline docker sandbox"
run = "./scripts/test_docker.sh"
[tasks."test:docker:online"]
description = "Run optional network-dependent tests in docker sandbox"
run = "./scripts/test_docker_online.sh"
[tasks."sandbox:up"]
description = "Start persistent docker playground container"
run = "./scripts/sandbox_playground_up.sh"
[tasks."sandbox:shell"]
description = "Enter persistent docker playground shell"
run = "./scripts/sandbox_playground_shell.sh"
[tasks."sandbox:down"]
description = "Stop and remove persistent docker playground container"
run = "./scripts/sandbox_playground_down.sh"
[tasks.lint]
description = "Run go vet"
run = "go vet ./..."
+21
View File
@@ -0,0 +1,21 @@
#!/usr/bin/env bash
# Stop and remove the Docker playground container.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
COMPOSE_FILE="$PROJECT_ROOT/docker-compose.sandbox.yml"
if ! command -v docker >/dev/null 2>&1; then
echo "Error: docker command not found" >&2
exit 1
fi
if ! docker compose version >/dev/null 2>&1; then
echo "Error: docker compose plugin not available" >&2
exit 1
fi
cd "$PROJECT_ROOT"
docker compose -f "$COMPOSE_FILE" --profile playground stop sandbox-playground
docker compose -f "$COMPOSE_FILE" --profile playground rm -f sandbox-playground
+32
View File
@@ -0,0 +1,32 @@
#!/usr/bin/env bash
# Enter the running Docker playground or execute a command inside it.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
COMPOSE_FILE="$PROJECT_ROOT/docker-compose.sandbox.yml"
SERVICE="sandbox-playground"
if ! command -v docker >/dev/null 2>&1; then
echo "Error: docker command not found" >&2
exit 1
fi
if ! docker compose version >/dev/null 2>&1; then
echo "Error: docker compose plugin not available" >&2
exit 1
fi
cd "$PROJECT_ROOT"
if [[ -z "$(docker compose -f "$COMPOSE_FILE" --profile playground ps -q "$SERVICE")" ]]; then
echo "Playground is not running. Start it first:"
echo " ./scripts/sandbox_playground_up.sh"
exit 1
fi
if [[ $# -gt 0 ]]; then
docker compose -f "$COMPOSE_FILE" --profile playground exec --user "$(id -u):$(id -g)" "$SERVICE" bash -c "$*"
else
docker compose -f "$COMPOSE_FILE" --profile playground exec --user "$(id -u):$(id -g)" "$SERVICE" bash
fi
+36
View File
@@ -0,0 +1,36 @@
#!/usr/bin/env bash
# Start a persistent Docker playground for interactive skillshare usage.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
COMPOSE_FILE="$PROJECT_ROOT/docker-compose.sandbox.yml"
SERVICE="sandbox-playground"
if ! command -v docker >/dev/null 2>&1; then
echo "Error: docker command not found" >&2
exit 1
fi
if ! docker compose version >/dev/null 2>&1; then
echo "Error: docker compose plugin not available" >&2
exit 1
fi
cd "$PROJECT_ROOT"
docker compose -f "$COMPOSE_FILE" --profile playground build "$SERVICE"
# Prepare shared volumes for host UID/GID access.
docker compose -f "$COMPOSE_FILE" --profile playground run --rm --user "0:0" "$SERVICE" \
bash -c "mkdir -p /go/pkg/mod /go/build-cache /sandbox-home /tmp && chmod -R 0777 /go/pkg/mod /go/build-cache /sandbox-home /tmp"
docker compose -f "$COMPOSE_FILE" --profile playground up -d "$SERVICE"
# Build skillshare binary into playground PATH and configure ss alias.
docker compose -f "$COMPOSE_FILE" --profile playground exec --user "$(id -u):$(id -g)" "$SERVICE" \
bash -c "mkdir -p /sandbox-home/.local/bin && go build -o /sandbox-home/.local/bin/skillshare ./cmd/skillshare && ln -sf /sandbox-home/.local/bin/skillshare /sandbox-home/.local/bin/ss && touch /sandbox-home/.bashrc && { grep -qxF \"alias ss='skillshare'\" /sandbox-home/.bashrc || echo \"alias ss='skillshare'\" >> /sandbox-home/.bashrc; }"
echo "Playground is running."
echo "Enter it with: ./scripts/sandbox_playground_shell.sh"
echo "Inside playground you can directly run: skillshare (and alias: ss)"
+1 -1
View File
@@ -71,7 +71,7 @@ while [[ $# -gt 0 ]]; do
done
# Get project root
PROJECT_ROOT="$(cd "$(dirname "$0")" && pwd)"
PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
cd "$PROJECT_ROOT"
# Build binary for integration tests
+77
View File
@@ -0,0 +1,77 @@
#!/usr/bin/env bash
# Run Go test pipeline inside the offline Docker sandbox.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
COMPOSE_FILE="$PROJECT_ROOT/docker-compose.sandbox.yml"
SERVICE="sandbox-offline"
SKIP_BUILD=false
CUSTOM_CMD=""
usage() {
cat <<'EOF'
Usage: ./scripts/test_docker.sh [options]
Options:
--skip-build Skip docker compose build
--cmd "<command>" Override default service command
-h, --help Show this help
EOF
}
while [[ $# -gt 0 ]]; do
case "$1" in
--skip-build)
SKIP_BUILD=true
shift
;;
--cmd)
if [[ $# -lt 2 ]]; then
echo "Error: --cmd requires a value" >&2
exit 1
fi
CUSTOM_CMD="$2"
shift 2
;;
--cmd=*)
CUSTOM_CMD="${1#--cmd=}"
shift
;;
-h|--help)
usage
exit 0
;;
*)
echo "Error: unknown option '$1'" >&2
usage
exit 1
;;
esac
done
if ! command -v docker >/dev/null 2>&1; then
echo "Error: docker command not found" >&2
exit 1
fi
if ! docker compose version >/dev/null 2>&1; then
echo "Error: docker compose plugin not available" >&2
exit 1
fi
cd "$PROJECT_ROOT"
if [[ "$SKIP_BUILD" != "true" ]]; then
docker compose -f "$COMPOSE_FILE" --profile offline build "$SERVICE"
fi
# Ensure named cache volumes are writable when running as host UID/GID.
docker compose -f "$COMPOSE_FILE" --profile offline run --rm --user "0:0" "$SERVICE" bash -c "mkdir -p /go/pkg/mod /go/build-cache && chmod -R 0777 /go/pkg/mod /go/build-cache /tmp"
if [[ -n "$CUSTOM_CMD" ]]; then
docker compose -f "$COMPOSE_FILE" --profile offline run --rm --user "$(id -u):$(id -g)" "$SERVICE" bash -c "$CUSTOM_CMD"
else
docker compose -f "$COMPOSE_FILE" --profile offline run --rm --user "$(id -u):$(id -g)" "$SERVICE"
fi
+78
View File
@@ -0,0 +1,78 @@
#!/usr/bin/env bash
# Run optional network-dependent install/update tests inside Docker.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
COMPOSE_FILE="$PROJECT_ROOT/docker-compose.sandbox.yml"
SERVICE="sandbox-online"
SKIP_BUILD=false
CUSTOM_CMD=""
DEFAULT_ONLINE_CMD="mkdir -p bin && go build -o bin/skillshare ./cmd/skillshare && SKILLSHARE_TEST_BINARY=/workspace/bin/skillshare go test -v -tags online ./tests/integration/... -run 'TestInstall_Remote'"
usage() {
cat <<'EOF'
Usage: ./scripts/test_docker_online.sh [options]
Options:
--skip-build Skip docker compose build
--cmd "<command>" Override default online test command
-h, --help Show this help
EOF
}
while [[ $# -gt 0 ]]; do
case "$1" in
--skip-build)
SKIP_BUILD=true
shift
;;
--cmd)
if [[ $# -lt 2 ]]; then
echo "Error: --cmd requires a value" >&2
exit 1
fi
CUSTOM_CMD="$2"
shift 2
;;
--cmd=*)
CUSTOM_CMD="${1#--cmd=}"
shift
;;
-h|--help)
usage
exit 0
;;
*)
echo "Error: unknown option '$1'" >&2
usage
exit 1
;;
esac
done
if ! command -v docker >/dev/null 2>&1; then
echo "Error: docker command not found" >&2
exit 1
fi
if ! docker compose version >/dev/null 2>&1; then
echo "Error: docker compose plugin not available" >&2
exit 1
fi
cd "$PROJECT_ROOT"
if [[ "$SKIP_BUILD" != "true" ]]; then
docker compose -f "$COMPOSE_FILE" --profile online build "$SERVICE"
fi
# Ensure named cache volumes are writable when running as host UID/GID.
docker compose -f "$COMPOSE_FILE" --profile online run --rm --user "0:0" "$SERVICE" bash -c "mkdir -p /go/pkg/mod /go/build-cache && chmod -R 0777 /go/pkg/mod /go/build-cache /tmp"
if [[ -n "$CUSTOM_CMD" ]]; then
docker compose -f "$COMPOSE_FILE" --profile online run --rm --user "$(id -u):$(id -g)" "$SERVICE" bash -c "$CUSTOM_CMD"
else
docker compose -f "$COMPOSE_FILE" --profile online run --rm --user "$(id -u):$(id -g)" "$SERVICE" bash -c "$DEFAULT_ONLINE_CMD"
fi
+25
View File
@@ -0,0 +1,25 @@
//go:build online
package integration
import (
"testing"
"skillshare/internal/testutil"
)
// TestInstall_RemoteGitHubSubdir_DryRun validates a network-backed install path.
// This test is excluded from default runs and only enabled with -tags online.
func TestInstall_RemoteGitHubSubdir_DryRun(t *testing.T) {
sb := testutil.NewSandbox(t)
defer sb.Cleanup()
sb.WriteConfig(`source: ` + sb.SourcePath + `
targets: {}
`)
result := sb.RunCLI("install", "runkids/skillshare/skills/skillshare", "--dry-run")
result.AssertSuccess(t)
result.AssertAnyOutputContains(t, "dry-run")
}
@@ -55,6 +55,16 @@ Command cheat sheet for skillshare.
| Command | Description |
|---------|-------------|
| `doctor` | Diagnose issues |
| `mise run test:docker` | Run offline Docker sandbox tests |
| `mise run test:docker:online` | Run optional online Docker tests |
| `mise run sandbox:up` | Start persistent playground container |
| `mise run sandbox:shell` | Enter playground shell |
| `mise run sandbox:down` | Stop playground container |
| `make test-docker` | Run offline Docker sandbox tests |
| `make test-docker-online` | Run optional online Docker tests |
| `make sandbox-up` | Start persistent playground container |
| `make sandbox-shell` | Enter playground shell |
| `make sandbox-down` | Stop playground container |
---
@@ -92,6 +102,23 @@ skillshare update --all
skillshare sync
```
### Sandbox playground session
```bash
mise run sandbox:up
mise run sandbox:shell
skillshare --help
ss status
mise run sandbox:down
```
```bash
make sandbox-up
make sandbox-shell
skillshare --help
ss status
make sandbox-down
```
---
## Key Paths
+125
View File
@@ -0,0 +1,125 @@
---
sidebar_position: 8
---
# Docker Sandbox: Test and Playground
Use Docker sandbox when you want repeatable verification and a safe place to try commands without touching your host setup.
## Mode Selection Diagram
```mermaid
%%{init: {'flowchart': {'htmlLabels': false}}}%%
flowchart TD
A["Need Docker sandbox"] --> B{"Primary goal"}
B --> C["Stable local regression checks"]
B --> D["Validate remote-source behavior"]
B --> E["Hands-on command exploration"]
C --> C1["Offline test sandbox"]
C1 --> C2["Run test-docker"]
D --> D1["Online test sandbox"]
D1 --> D2["Run test-docker-online"]
E --> E1["Persistent playground"]
E1 --> E2["sandbox-up -> sandbox-shell -> sandbox-down"]
```
Command mapping:
| Shortcut | `mise` | `make` |
|---|---|---|
| `test-docker` | `mise run test:docker` | `make test-docker` |
| `test-docker-online` | `mise run test:docker:online` | `make test-docker-online` |
| `sandbox-up` | `mise run sandbox:up` | `make sandbox-up` |
| `sandbox-shell` | `mise run sandbox:shell` | `make sandbox-shell` |
| `sandbox-down` | `mise run sandbox:down` | `make sandbox-down` |
## What You Can Use It For
| Mode | Best for | Network | Lifecycle |
|------|----------|---------|-----------|
| Offline test sandbox | Stable regression checks (`build + unit + integration`) | Disabled | One-shot |
| Online test sandbox | Optional remote install/update checks | Enabled | One-shot |
| Interactive playground | Manual command exploration and demos | Enabled | Persistent |
---
## Common Scenarios
### 1. Verify local install/update logic deterministically
Use this when you are changing `install` / `update` behavior and want a CI-like local gate.
```bash
mise run test:docker
make test-docker
```
This validates local-path and `file://` workflows in isolation.
### 2. Run optional remote-source checks
Use this for GitHub/remote-source validation that depends on network access.
```bash
mise run test:docker:online
make test-docker-online
```
### 3. Open a dedicated playground and explore all commands
```bash
mise run sandbox:up
mise run sandbox:shell
make sandbox-up
make sandbox-shell
```
Inside the playground, `skillshare` and `ss` are ready:
```bash
skillshare --help
ss status
skillshare init --dry-run
```
When finished:
```bash
mise run sandbox:down
make sandbox-down
```
---
## Why This Is Useful
- **Reproducible**: same base image, same toolchain, fewer machine-specific surprises.
- **Safe isolation**: test and experiment without polluting host-level paths.
- **Fast iteration**: separate offline/online modes let you keep default checks stable.
- **Team onboarding**: a shared command set (`mise run ...`) avoids setup drift.
- **Tooling flexibility**: use either `mise` or `make`, depending on team preference.
---
## Practical Benefits by Role
- **Maintainers**: faster confidence for command-level changes.
- **Contributors**: one command to run the expected test gate.
- **Power users**: a disposable environment for trying risky workflows.
- **Demo/training**: predictable environment for live walkthroughs.
---
## Limits and Expectations
- Offline sandbox cannot validate network-dependent features (for example remote `install` from GitHub).
- Playground uses container-local `HOME`, so it does not directly modify your real host home config.
- If you need custom experiments, pass commands directly:
```bash
./scripts/test_docker.sh --cmd "go test -v ./tests/integration/..."
./scripts/sandbox_playground_shell.sh "skillshare list"
```
+5
View File
@@ -16,6 +16,7 @@ In-depth guides for specific use cases.
| [Cross-Machine Sync](./cross-machine-sync) | Sync skills across computers |
| [Migration](./migration) | Migrate from other tools |
| [Best Practices](./best-practices) | Naming, organization, and versioning |
| [Docker Sandbox](./docker-sandbox) | Isolated test sandbox and interactive playground |
---
@@ -35,3 +36,7 @@ In-depth guides for specific use cases.
### For Migration
- [Migration](./migration) — Coming from other tools
### For Verification and Experimentation
- [Docker Sandbox](./docker-sandbox) — Repeatable test gate + persistent playground
+1
View File
@@ -88,4 +88,5 @@ Edit in source → all targets update. Edit in target → changes go to source (
**Learn more:**
- [Core Concepts](/docs/concepts) — Source, targets, sync modes
- [Commands Reference](/docs/commands) — All available commands
- [Docker Sandbox Guide](/docs/guides/docker-sandbox) — Isolated testing and playground
- [FAQ](/docs/troubleshooting/faq) — Common questions
+6
View File
@@ -24,6 +24,12 @@ const config: Config = {
locales: ['en'],
},
markdown: {
mermaid: true,
},
themes: ['@docusaurus/theme-mermaid'],
presets: [
[
'classic',
+1269 -27
View File
File diff suppressed because it is too large Load Diff
+1
View File
@@ -17,6 +17,7 @@
"dependencies": {
"@docusaurus/core": "3.9.2",
"@docusaurus/preset-classic": "3.9.2",
"@docusaurus/theme-mermaid": "^3.9.2",
"@mdx-js/react": "^3.0.0",
"clsx": "^2.0.0",
"lucide-react": "^0.563.0",
+1
View File
@@ -49,6 +49,7 @@ const sidebars: SidebarsConfig = {
'guides/migration',
'guides/best-practices',
'guides/project-setup',
'guides/docker-sandbox',
],
},
{