molecule-cli/known-issues.md

Known Issues — molecule-cli

Issues identified in source but not yet filed as GitHub issues (GH_TOKEN unavailable in automated agent contexts). Each entry has: location, symptom, impact, suggested fix.

Format per entry:

## KI-N — Short title

**File:** `<path>:<line>`
**Status:** TODO comment / identified / partially fixed
**Severity:** Critical / High / Medium / Low

### Symptom
...

### Impact
...

### Suggested fix
...
---

---

KI-001 — No entry point yet (cmd/molecule/main.go does not exist)

File: cmd/molecule/main.go Status: ✅ Resolved Resolved in: feat/cli-full-command-tree branch, commit "feat: implement full CLI command tree"

Symptom

cmd/molecule/main.go exists and calls cmd.Execute(). Root command is wired with global flags (--verbose, --output, --config, --api-url). All subcommand groups registered: workspace (7 commands), agent (4 commands), platform (2 commands), config (5 commands). Binary builds to bin/mol.

Impact

The CLI is not runnable. No workspace management, agent inspection, or any other CLI command exists. The repo is a stub.

Suggested fix

Implement cmd/molecule/main.go with a root cobra.Command that registers subcommands. Wire up global flags (--verbose, --output, --config). Wire MOLECULE_API_URL env var as the default for the API base URL. See the stub checklist in CLAUDE.md Section 8.

---

KI-002 — No API client; all commands will make raw HTTP calls

File: cmd/molecule/ (no API client package yet) Status: ✅ Partially resolved Resolved in: internal/client/platform.go exists with workspace and agent operations; runHTTP helper in internal/cmd/http.go used by agent send and workspace delegate. Remaining: workspace runtime client (dev/proxy mode).

Symptom

There is no internal/client/ or pkg/api/ package. Any subcommand implementation will need to import the platform SDK (molecule-sdk-python) via a Go FFI wrapper, make raw net/http calls directly, or wait for a Go SDK to be built. Neither exists yet.

Impact

Subcommand implementations will either duplicate HTTP client logic or require architecting a clean API client interface before the first command can be meaningfully built.

Suggested fix

Before implementing subcommands, define internal/api/client.go with a Client struct wrapping *http.Client. Implement methods for workspace and agent operations. Add a ClientOption functional options pattern for configuring base URL and auth. Document the API endpoints in docs/ as they are implemented.

---

KI-003 — go.sum may contain entries from non-release toolchains

File: go.sum Status: ✅ Resolved Resolved in: go mod tidy run on feat/cli-full-command-tree; go.sum regenerated clean. Dependencies: cobra v1.10.2, viper v1.21.0, their transitive deps.

Symptom

The go.sum file was generated during initial module setup. It may contain checksum entries for transitive dependencies pulled from toolchains or platforms not intended for the release build (e.g. linux/arm64 on an amd64 host). GoReleaser targets specific platforms and any spurious go.sum entries may cause CI divergence or checksum mismatches.

Impact

go mod verify in CI may fail if go.sum has extra entries not in the lock file. Additionally, if the module path (github.com/Molecule-AI/molecule-cli) is referenced via replace directives from other repos, those references may persist stale entries.

Suggested fix

Run go mod tidy on a clean checkout from main and commit only the resulting go.sum. Add go mod verify to CI as a lint step. Ensure .goreleaser.yaml specifies exact Go version matching CI.

---

KI-004 — GoReleaser config may not be aligned with go.mod module path

File: .goreleaser.yaml Status: ✅ Resolved — .goreleaser.yaml added Resolved in: main (commit 47b2804 + this branch) Severity: Medium

Symptom

The GoReleaser workflow was wired up but had no .goreleaser.yaml config. A v* tag push could produce an empty release or a binary with the wrong name if builds[].dir or builds[].main were misconfigured.

Resolution

Added .goreleaser.yaml with:

• dir: . — repo root
• main: ./cmd/molecule — main package path
• binary: molecule — output binary name
• All 6 targets: linux/darwin × amd64/arm64 + windows × amd64
• CGO_ENABLED=0 for static binaries
• Checksum files generated for all archives

release.yml still uses plain go build per matrix target (GoReleaser is configured but not wired into CI yet — the plain build is sufficient for v0.1.0). Wire GoReleaser into CI when Homebrew formula + checksum verification are needed.

---

KI-005 — No integration test for the full CLI lifecycle

File: tests/ (does not exist) Status: ✅ Resolved Resolved in: cmd/molecule/molecule_test.go — 24 table-driven tests using httptest mock server. Severity: Medium

Symptom

There were no tests at all (per go test ./... — no packages match). As subcommands were built, there was no test harness for end-to-end CLI testing (e.g. molecule workspace create --name test --output json → verify JSON output).

Impact

Each subcommand was shipped without regression protection. Manual testing was required for every release.

Suggested fix

Add tests/ with:

• cmd/molecule/molecule_test.go — table-driven tests for each subcommand using exec.Command("molecule", ...) against a built binary
• Use a httptest mock server for offline testing
• Add go test ./... to CI; require >0 test packages before merge

✅ Done: 24 integration tests covering all 18 subcommands, error paths, and structured output. go test ./... passes, CI job added to release.yml.