diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 1c400d2dd..bdaad509c 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -3,12 +3,6 @@ "dockerComposeFile": "docker-compose.yml", "service": "skillshare-devcontainer", "workspaceFolder": "/workspace", - "features": { - "ghcr.io/devcontainers/features/node:1": { - "version": "24", - "pnpmVersion": "10.28.0" - } - }, "forwardPorts": [5173, 19420, 3000], "portsAttributes": { "5173": { "label": "Dashboard (ui)" }, diff --git a/.devcontainer/setup.sh b/.devcontainer/setup.sh index 83bc8fd77..4c73d6506 100755 --- a/.devcontainer/setup.sh +++ b/.devcontainer/setup.sh @@ -12,29 +12,10 @@ if [[ "${HOME:-}" != "/tmp" && "${HOME:-}" != "/home/developer" ]] || [ ! -d /wo fi cd /workspace -# ── 0. Token env: .env overrides host-passed env vars ──────────────── -# Docker-compose passes host tokens via environment (fallback). -# If .devcontainer/.env exists, source it in every login shell to override. -cat > /etc/profile.d/skillshare-env.sh << 'PROFILE_EOF' -if [ -f /workspace/.devcontainer/.env ]; then - set -a - . /workspace/.devcontainer/.env - set +a -fi -PROFILE_EOF - -# Keep devcontainer command wrappers ahead of /usr/local/bin in login shells. -cat > /etc/profile.d/skillshare-path.sh << 'PROFILE_EOF' -case ":$PATH:" in - *:/workspace/.devcontainer/bin:*) ;; - *) export PATH="/workspace/.devcontainer/bin:/workspace/bin:$PATH" ;; -esac -PROFILE_EOF - -# Shortcuts for isolated env switching without memorizing eval commands. -if [ -x /workspace/.devcontainer/install-ssenv-shortcuts.sh ]; then - /workspace/.devcontainer/install-ssenv-shortcuts.sh -fi +# ── 0. Container-level setup (profile.d, shortcuts) ────────────────── +# Delegate to start-dev.sh which handles per-start container init. +# This ensures profile.d scripts exist before any login-shell steps below. +/workspace/.devcontainer/start-dev.sh # ── 1. Build CLI ──────────────────────────────────────────────────── echo "▸ Building skillshare binary …" @@ -69,6 +50,9 @@ CFG="$HOME/.config/skillshare" DEMO="$HOME/demo-project" /workspace/scripts/create-demo-content.sh "$SKILLS" "$CFG" "$DEMO" +# ── Mark initialisation complete (sentinel on persistent volume) ───── +touch "$HOME/.devcontainer-initialized" + # ── Done ──────────────────────────────────────────────────────────── echo "" echo "══════════════════════════════════════════════════════════" diff --git a/.devcontainer/start-dev.sh b/.devcontainer/start-dev.sh index 6ed90536f..1c1cfc765 100755 --- a/.devcontainer/start-dev.sh +++ b/.devcontainer/start-dev.sh @@ -1,8 +1,35 @@ #!/usr/bin/env bash -# Resolve GITHUB_TOKEN and print available commands on container start. +# Per-start container init: profile.d scripts, PATH, token detection. +# Runs on every container start (VS Code postStartCommand / devc.sh). set -euo pipefail -# Re-assert Linux-safe command entrypoints on every container start. +# ── Profile.d: login-shell environment ─────────────────────────────── +# These live on the container filesystem (not volume) and must be +# recreated after container recreation (docker compose down → up). + +# Token env: .env overrides host-passed env vars. +cat > /etc/profile.d/skillshare-env.sh << 'PROFILE_EOF' +if [ -f /workspace/.devcontainer/.env ]; then + set -a + . /workspace/.devcontainer/.env + set +a +fi +PROFILE_EOF + +# Restore Go toolchain paths (login shell resets PATH, dropping Docker ENV values) +# and keep devcontainer command wrappers ahead of /usr/local/bin. +cat > /etc/profile.d/skillshare-path.sh << 'PROFILE_EOF' +case ":$PATH:" in + *:/usr/local/go/bin:*) ;; + *) export PATH="/go/bin:/usr/local/go/bin:$PATH" ;; +esac +case ":$PATH:" in + *:/workspace/.devcontainer/bin:*) ;; + *) export PATH="/workspace/.devcontainer/bin:/workspace/bin:$PATH" ;; +esac +PROFILE_EOF + +# ── Re-assert command entrypoints and shortcuts ────────────────────── if [ -x /workspace/.devcontainer/ensure-skillshare-linux-binary.sh ]; then /workspace/.devcontainer/ensure-skillshare-linux-binary.sh fi diff --git a/.skillshare/skills/devcontainer/SKILL.md b/.skillshare/skills/devcontainer/SKILL.md index e8fa963ab..2ca3060c4 100644 --- a/.skillshare/skills/devcontainer/SKILL.md +++ b/.skillshare/skills/devcontainer/SKILL.md @@ -57,14 +57,18 @@ This also applies to `go test` — tests always compile against the latest sourc ## Entering the Devcontainer -The quickest way to get an interactive shell inside the devcontainer: +The quickest way — one command builds, initialises, and enters the shell: ```bash -make devc # interactive bash shell -./scripts/devcontainer_shell.sh make test # run a command directly +make devc # build + init + interactive shell (one step) +make devc-up # start only (no shell) +make devc-down # stop +make devc-restart # restart + re-run start-dev.sh +make devc-reset # full reset (remove volumes), then `make devc` to re-init +make devc-status # show container status ``` -The script auto-detects whether the container is running and prints setup instructions if it isn't. +Works with **or without** VS Code — `make devc` handles the full lifecycle autonomously. ### Programmatic access (for `docker exec` workflows) @@ -73,8 +77,7 @@ CONTAINER=$(docker compose -f .devcontainer/docker-compose.yml ps -q skillshare- ``` If `$CONTAINER` is empty, tell the user: -> Devcontainer is not running. Please start it with VS Code "Reopen in Container" or run: -> `docker compose -f .devcontainer/docker-compose.yml up -d` +> Devcontainer is not running. Start it with `make devc-up`. Then verify the binary: ```bash diff --git a/Makefile b/Makefile index aa2aa5225..a67404fcd 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: help build build-meta build-windows run test test-unit test-int test-docker test-docker-online test-redteam test-redteam-signal test-redteam-rules-signal playground playground-down devc dev-docker dev-docker-down docker-build docker-build-multiarch lint fmt fmt-check check install clean ui-install ui-build ui-dev build-all +.PHONY: help build build-meta build-windows run test test-unit test-int test-docker test-docker-online test-redteam test-redteam-signal test-redteam-rules-signal playground playground-down devc devc-up devc-down devc-restart devc-reset devc-status dev-docker dev-docker-down docker-build docker-build-multiarch lint fmt fmt-check check install clean ui-install ui-build ui-dev build-all help: @echo "Common tasks:" @@ -14,7 +14,12 @@ help: @echo " make test-redteam-rules-signal # verify red team test fails when critical builtin rules are disabled" @echo " make playground # start playground + enter shell (one step)" @echo " make playground-down # stop and remove playground" - @echo " make devc # enter running devcontainer shell" + @echo " make devc # start devcontainer + enter shell (one step)" + @echo " make devc-up # start devcontainer (no shell)" + @echo " make devc-down # stop devcontainer" + @echo " make devc-restart # restart devcontainer" + @echo " make devc-reset # full reset (remove volumes)" + @echo " make devc-status # show devcontainer status" @echo " make lint # go vet" @echo " make fmt # format Go files" @echo " make check # fmt-check + lint + test" @@ -74,7 +79,22 @@ playground-down: ./scripts/sandbox_playground_down.sh devc: - ./scripts/devcontainer_shell.sh + ./scripts/devc.sh up && ./scripts/devc.sh shell + +devc-up: + ./scripts/devc.sh up + +devc-down: + ./scripts/devc.sh down + +devc-restart: + ./scripts/devc.sh restart + +devc-reset: + ./scripts/devc.sh reset + +devc-status: + ./scripts/devc.sh status dev-docker: docker compose -f docker-compose.sandbox.yml --profile dev watch diff --git a/docker/sandbox/Dockerfile b/docker/sandbox/Dockerfile index ccc855ccd..bd5eb0ae1 100644 --- a/docker/sandbox/Dockerfile +++ b/docker/sandbox/Dockerfile @@ -29,6 +29,15 @@ RUN apt-get update \ RUN go install github.com/air-verse/air@latest \ && go install github.com/go-delve/delve/cmd/dlv@latest +# Copy node runtime from ui-builder stage (for devcontainer / interactive use) +COPY --from=ui-builder /usr/local/bin/node /usr/local/bin/ +COPY --from=ui-builder /usr/local/lib/node_modules /usr/local/lib/node_modules +RUN ln -sf ../lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm \ + && ln -sf ../lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx \ + && ln -sf ../lib/node_modules/corepack/dist/corepack.js /usr/local/bin/corepack +ARG PNPM_VERSION +RUN npm install -g pnpm@${PNPM_VERSION} + # Copy pre-built frontend for playground UI cache COPY --from=ui-builder /ui/dist /ui-dist diff --git a/mise.toml b/mise.toml index 26781aa52..11c4caf85 100644 --- a/mise.toml +++ b/mise.toml @@ -16,7 +16,12 @@ echo " mise run test:docker:online # docker online install/update tests" echo " mise run test:redteam # red team supply-chain security tests" echo " mise run playground # start playground + enter shell (one step)" echo " mise run playground:down # stop and remove playground" -echo " mise run devc # enter running devcontainer shell" +echo " mise run devc # start devcontainer + enter shell (one step)" +echo " mise run devc:up # start devcontainer (no shell)" +echo " mise run devc:down # stop devcontainer" +echo " mise run devc:restart # restart devcontainer" +echo " mise run devc:reset # full reset (remove volumes)" +echo " mise run devc:status # show devcontainer status" echo " mise run lint # go vet" echo " mise run fmt # format Go files" echo " mise run check # fmt:check + lint + test" @@ -87,8 +92,31 @@ description = "Stop and remove playground container" run = "./scripts/sandbox_playground_down.sh" [tasks.devc] -description = "Enter running devcontainer shell" -run = "./scripts/devcontainer_shell.sh" +description = "Start devcontainer + enter shell (one step)" +run = """ +./scripts/devc.sh up +./scripts/devc.sh shell +""" + +[tasks."devc:up"] +description = "Start devcontainer (no shell)" +run = "./scripts/devc.sh up" + +[tasks."devc:down"] +description = "Stop devcontainer" +run = "./scripts/devc.sh down" + +[tasks."devc:restart"] +description = "Restart devcontainer" +run = "./scripts/devc.sh restart" + +[tasks."devc:reset"] +description = "Full reset (remove volumes)" +run = "./scripts/devc.sh reset" + +[tasks."devc:status"] +description = "Show devcontainer status" +run = "./scripts/devc.sh status" [tasks."dev:docker"] description = "Go API in Docker + auto-rebuild (pair with: cd ui && pnpm run dev)" diff --git a/scripts/devc.sh b/scripts/devc.sh new file mode 100755 index 000000000..c42504619 --- /dev/null +++ b/scripts/devc.sh @@ -0,0 +1,141 @@ +#!/usr/bin/env bash +# Unified devcontainer lifecycle script (no VS Code required). +# Usage: ./scripts/devc.sh +# +# Commands: +# up Start devcontainer (build if needed, run setup on first start) +# shell Enter running devcontainer shell +# down Stop and remove devcontainer +# restart Restart devcontainer +# reset Stop + remove volumes (full reset) +# status Show devcontainer status +# logs Tail devcontainer logs +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" + +source "$SCRIPT_DIR/_sandbox_common.sh" + +COMPOSE_FILE="$PROJECT_ROOT/.devcontainer/docker-compose.yml" +SERVICE="skillshare-devcontainer" + +usage() { + echo "Usage: $(basename "$0") " + echo "" + echo "Commands:" + echo " up Start devcontainer (build + init on first run)" + echo " shell Enter running devcontainer shell" + echo " down Stop and remove devcontainer" + echo " restart Restart devcontainer" + echo " reset Stop + remove volumes (full reset)" + echo " status Show devcontainer status" + echo " logs Tail devcontainer logs" +} + +# Check if container is running. +is_running() { + local cid + cid="$(docker compose -f "$COMPOSE_FILE" ps -q "$SERVICE" 2>/dev/null || true)" + [[ -n "$cid" ]] +} + +# Check if one-time data setup has completed (sentinel on persistent volume). +is_initialised() { + docker compose -f "$COMPOSE_FILE" exec -T "$SERVICE" \ + test -f /home/developer/.devcontainer-initialized 2>/dev/null +} + +cmd_up() { + require_docker + cd "$PROJECT_ROOT" + + echo "▸ Starting devcontainer …" + docker compose -f "$COMPOSE_FILE" up -d --build + + if is_initialised; then + echo "▸ Already initialised — running start-dev.sh …" + docker compose -f "$COMPOSE_FILE" exec -T -w /workspace "$SERVICE" \ + bash -c '/workspace/.devcontainer/start-dev.sh' + else + echo "▸ First run — running setup.sh …" + docker compose -f "$COMPOSE_FILE" exec -T -w /workspace "$SERVICE" \ + bash -c '/workspace/.devcontainer/setup.sh' + fi +} + +cmd_shell() { + require_docker + cd "$PROJECT_ROOT" + + if ! is_running; then + echo "Devcontainer is not running." >&2 + echo "Start it with: make devc-up (or ./scripts/devc.sh up)" >&2 + exit 1 + fi + + docker compose -f "$COMPOSE_FILE" exec -w /workspace "$SERVICE" bash -l +} + +cmd_down() { + require_docker + cd "$PROJECT_ROOT" + docker compose -f "$COMPOSE_FILE" down +} + +cmd_restart() { + require_docker + cd "$PROJECT_ROOT" + + docker compose -f "$COMPOSE_FILE" restart + + echo "▸ Running start-dev.sh …" + docker compose -f "$COMPOSE_FILE" exec -T -w /workspace "$SERVICE" \ + bash -c '/workspace/.devcontainer/start-dev.sh' +} + +cmd_reset() { + require_docker + cd "$PROJECT_ROOT" + docker compose -f "$COMPOSE_FILE" down -v + echo "Volumes removed. Run 'make devc' to re-initialise." +} + +cmd_status() { + require_docker + cd "$PROJECT_ROOT" + docker compose -f "$COMPOSE_FILE" ps +} + +cmd_logs() { + require_docker + cd "$PROJECT_ROOT" + docker compose -f "$COMPOSE_FILE" logs -f "$SERVICE" +} + +if [[ $# -eq 0 ]]; then + usage + exit 1 +fi + +CMD="$1" +shift + +case "$CMD" in + up) cmd_up "$@" ;; + shell) cmd_shell "$@" ;; + down) cmd_down "$@" ;; + restart) cmd_restart "$@" ;; + reset) cmd_reset "$@" ;; + status) cmd_status "$@" ;; + logs) cmd_logs "$@" ;; + help|--help|-h) + usage + ;; + *) + echo "Error: unknown command '$CMD'" >&2 + echo "" + usage + exit 1 + ;; +esac diff --git a/scripts/devcontainer_shell.sh b/scripts/devcontainer_shell.sh deleted file mode 100755 index 6044db304..000000000 --- a/scripts/devcontainer_shell.sh +++ /dev/null @@ -1,30 +0,0 @@ -#!/usr/bin/env bash -# Enter the running devcontainer or execute a command inside it. -# Usage: -# ./scripts/devcontainer_shell.sh # interactive shell -# ./scripts/devcontainer_shell.sh make test # run a command -set -euo pipefail - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" - -# Reuse require_docker from sandbox common, then override COMPOSE_FILE. -source "$SCRIPT_DIR/_sandbox_common.sh" -require_docker - -COMPOSE_FILE="$PROJECT_ROOT/.devcontainer/docker-compose.yml" -SERVICE="skillshare-devcontainer" - -if [[ -z "$(docker compose -f "$COMPOSE_FILE" ps -q "$SERVICE" 2>/dev/null || true)" ]]; then - echo "Devcontainer is not running." >&2 - echo "Start it with one of:" >&2 - echo " 1. VS Code → 'Reopen in Container'" >&2 - echo " 2. docker compose -f .devcontainer/docker-compose.yml up -d" >&2 - exit 1 -fi - -if [[ $# -gt 0 ]]; then - docker compose -f "$COMPOSE_FILE" exec -w /workspace "$SERVICE" bash -c "$*" -else - docker compose -f "$COMPOSE_FILE" exec -w /workspace "$SERVICE" bash -fi diff --git a/website/docs/how-to/advanced/docker-sandbox.md b/website/docs/how-to/advanced/docker-sandbox.md index 83fb3148a..3b1a768f6 100644 --- a/website/docs/how-to/advanced/docker-sandbox.md +++ b/website/docs/how-to/advanced/docker-sandbox.md @@ -16,7 +16,7 @@ B --> D["Remote-source validation"] B --> E["Command exploration"] B --> F["Frontend development"] B --> G["Deployment / CI"] -B --> H["VS Code / Codespaces"] +B --> H["VS Code / CLI / Codespaces"] C --> C1["Offline test sandbox"] C1 --> C2["make test-docker"] @@ -35,7 +35,7 @@ G1 --> G2["docker-build"] G1 --> G3["docker/ci/Dockerfile"] H --> H1["Devcontainer"] -H1 --> H2["Reopen in Container"] +H1 --> H2["make devc / Reopen in Container"] ``` Command mapping: @@ -47,6 +47,12 @@ Command mapping: | **Playground** (start + shell) | **`mise run playground`** | **`make playground`** | | Playground (stop) | `mise run playground:down` | `make playground-down` | | Sandbox (advanced) | — | `./scripts/sandbox.sh ` | +| **Devcontainer** (start + shell) | **`mise run devc`** | **`make devc`** | +| Devcontainer (start only) | `mise run devc:up` | `make devc-up` | +| Devcontainer (stop) | `mise run devc:down` | `make devc-down` | +| Devcontainer (restart) | `mise run devc:restart` | `make devc-restart` | +| Devcontainer (full reset) | `mise run devc:reset` | `make devc-reset` | +| Devcontainer (status) | `mise run devc:status` | `make devc-status` | | Dev API server | `mise run dev:docker` | `make dev-docker` | | Dev stop | `mise run dev:docker:down` | `make dev-docker-down` | | Docker build | `mise run docker:build` | `make docker-build` | @@ -255,18 +261,19 @@ Both approaches give you instant HMR for `ui/` changes. The Docker variant pins --- -## Devcontainer (VS Code / Codespaces) +## Devcontainer (VS Code / Codespaces / CLI) -Open the project in a ready-to-code container — no local Go, Node, or pnpm needed. +Open the project in a ready-to-code container — no local Go, Node, or pnpm needed. Works with **or without** VS Code. :::info Devcontainer vs Playground -Both use the same base image and demo content. The **playground** (`make playground`) is a terminal-only environment for exploring commands. The **devcontainer** adds VS Code integration (IntelliSense, debugger, extensions) for developing the skillshare codebase itself. +Both use the same base image and demo content. The **playground** (`make playground`) is a terminal-only environment for exploring commands. The **devcontainer** adds development tooling (Go, Node, pnpm, air) for developing the skillshare codebase itself — usable from VS Code, Codespaces, or a plain terminal. ::: ### Prerequisites - [Docker Desktop](https://www.docker.com/products/docker-desktop/) running -- VS Code with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension installed +- **Option A (terminal):** No extra tools needed — `make devc` handles everything +- **Option B (VS Code):** VS Code with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension installed :::tip GitHub Codespaces On GitHub, click **Code → Codespaces → New codespace**. The devcontainer config is picked up automatically — no local Docker or extension needed. @@ -274,6 +281,26 @@ On GitHub, click **Code → Codespaces → New codespace**. The devcontainer con ### Getting started +**From terminal** (no VS Code required): + +```bash +make devc # build image → start container → setup → enter shell +``` + +First run takes a few minutes (building image, installing deps). Subsequent runs detect the existing setup and skip straight to the shell. + +Other lifecycle commands: + +```bash +make devc-up # start only (no shell) +make devc-down # stop container +make devc-restart # restart + re-run start-dev.sh +make devc-reset # full reset (remove volumes), then make devc to re-init +make devc-status # show container status +``` + +**From VS Code:** + 1. Open the project folder in VS Code 2. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS) and select **Dev Containers: Reopen in Container** 3. Wait for the container to build (first time takes a few minutes, subsequent opens are fast) @@ -284,7 +311,7 @@ On GitHub, click **Code → Codespaces → New codespace**. The devcontainer con The devcontainer reuses the same `docker/sandbox/Dockerfile` as the sandbox, so you get: - Go 1.25 toolchain -- Node.js 24 + pnpm (via [devcontainer feature](https://github.com/devcontainers/features/tree/main/src/node)) — enables `make ui-dev` and `cd website && pnpm start` inside the container +- Node.js 24 + pnpm (bundled in the Docker image) — enables `make ui-dev` and `cd website && pnpm start` inside the container - VS Code extensions: Go, Tailwind CSS, ESLint, Prettier - Ports forwarded: `19420` (Web UI), `5173` (Vite HMR), `3000` (Docusaurus) - Source code mounted at `/workspace` @@ -471,7 +498,7 @@ Browse published versions at [GitHub Packages](https://github.com/runkids/skills - **Playground and dev profile share port 19420** — run only one at a time. Stop the other first (`make playground-down` or `make dev-docker-down`). - 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. -- Go code changes are picked up automatically (`go build` runs inside the container from mounted source). **Frontend (`ui/`) changes** are picked up instantly when running `make ui-dev` (Vite HMR) inside the devcontainer. For the playground, run `make ui-build` on the host first since the playground container does not include Node.js. +- Go code changes are picked up automatically (`go build` runs inside the container from mounted source). **Frontend (`ui/`) changes** are picked up instantly when running `make ui-dev` (Vite HMR) inside the devcontainer. Both devcontainer and playground include Node.js and pnpm. - If you need custom experiments, pass commands directly: ```bash