BOHICA-LABS / BOHICA-LABS/vsdd-factory

bug(observability): onboard-observability skill returns success without verifying Docker is installed

Open
#238 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
2
Forks
1
Avg merge
6h 43m
Merged PRs (30d)
29

Description

## Summary

`skills/onboard-observability/SKILL.md` is the first-run skill for wiring a factory project into the observability stack. Its "Prerequisites (check + abort if missing)" section validates only two things:

1. The nearest `.factory/` ancestor exists
2. The `factory-obs` binary is present at `${CLAUDE_PLUGIN_ROOT}/bin/factory-obs`

It does **not** verify that Docker (or a `docker compose`–compatible runtime) is installed or running, yet `factory-obs up` — the very next step the skill instructs the user to run — hard-fails without one. `bin/factory-obs:121` correctly aborts with `factory-obs: docker compose not found. Install Docker Desktop or the docker-compose v2 plugin.`, but by that point the user has already received a success signal from onboarding.

## Repro

On a clean macOS machine with no Docker runtime installed:

```bash
# Inside a project containing .factory/
/vsdd-factory:onboard-observability
# → "✓ Observability onboarding complete."
# → Restart Claude Code (as instructed)

/vsdd-factory:factory-obs up
# → factory-obs: docker compose not found. Install Docker Desktop or the docker-compose v2 plugin.
```

The user has now:
- Restarted their Claude session (per the skill's "Next steps")
- Written 5 OTEL_* env vars into `.claude/settings.local.json` that point to a non-existent endpoint
- Received no indication during onboarding that the runtime is missing

## Suggested fix

Add a Docker preflight to the skill's Prerequisites section, before Step 1:

```bash
if ! { command -v docker >/dev/null 2>&1 && docker compose version >/dev/null 2>&1; } \
&& ! command -v docker-compose >/dev/null 2>&1; then
cat >&2 < These tests deliberately do NOT run docker. ... End-to-end validation (actually starting containers) requires docker and is performed manually per tools/observability/README.md.

There is no test asserting:
- The "docker compose not found" error path exits non-zero
- The error message text is stable (so users / docs can rely on it)
- The install hint mentions every supported runtime

A bats test that runs `factory-obs up` with `PATH=/usr/bin:/bin` (no docker) and asserts the message + exit code would pin the contract.

## Acceptance criteria

- [ ] `onboard-observability` aborts with a clear install-hint message if no Docker runtime is detected
- [ ] Hint mentions Docker Desktop, OrbStack, and Colima
- [ ] Idempotency preserved — re-running after install succeeds
- [ ] (Optional) `factory-obs.bats` gets a test pinning the docker-missing error contract

## Environment

- Plugin version: vsdd-factory 1.0.0-rc.21
- Discovered on: macOS arm64, fresh machine, no prior Docker install

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.