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 (go.moleculesai.app/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: .github/workflows/release.yml Status: ⚠️ Unverified — needs real tag to confirm Severity: Medium

Symptom

The GoReleaser workflow is wired up but has not been tested with a real tag. The gomod.alphaSettings or builds[].dir settings in .goreleaser.yaml (if it exists) may not correctly resolve the module root. A real v* tag push could produce an empty release or a binary with the wrong name.

Impact

The first release may silently fail or produce a malformed artifact that is not usable by platform operators.

Suggested fix

Before the first release, test goreleaser locally with goreleaser check and goreleaser snapshot --clean. Verify the binary name, module path, and target OS/arch match expectations. Ensure goreleaser.yaml builds[].dir is set to . (repo root) since the main package is at cmd/molecule.

---

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

File: cmd/molecule/molecule_test.go, internal/
Status: ✅ Resolved
Severity: Medium

Resolution

cmd/molecule/molecule_test.go contains 32 table-driven integration tests covering the full CLI command surface. Each test:

• Starts a httptest.Server that mirrors the platform REST API (workspace CRUD, agent inspection, delegation, health, audit, config, completion scripts).
• Builds the molecule binary via go build -o <tempdir>/molecule .
• Executes it with exec.Command and validates stdout/stderr output.

Test coverage includes:

• Root help, workspace/agent/platform/config help
• workspace list, workspace inspect, workspace create, workspace delete, workspace restart, workspace audit, workspace delegate
• agent list, agent inspect, agent send, agent peers
• platform health, platform audit
• config init, config list
• init, init --force
• completion bash/zsh/fish/powershell
• Error paths: missing workspace, missing agent, unknown subcommand, missing required args, duplicate init

Run go test ./... from the repo root to execute. No live platform required — all tests use httptest.Server fixtures.