5e5ec063bf
* docs: add CLAUDE.md for agent onboarding Inherits platform conventions from molecule-core: - Cron discipline and triage rules - Build/test commands (go build, go test) - Go module conventions (go mod tidy, go.sum hygiene) - Release process (GoReleaser tag workflow) - CLI design conventions (kubectl/gh patterns, stderr errors, exit codes) - Stub repo status checklist Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: add CLAUDE.md known-issues ref, known-issues.md, .claude/settings.json - CLAUDE.md: add known-issues.md reference in Known Issues section - known-issues.md: 5 entries (KI-001 main.go, KI-002 API client, KI-003 go.sum, KI-004 goreleaser, KI-005 no tests) - .claude/settings.json: permissions for go/goreleaser tools, PreToolUse Bash hook, cleanupPeriodDays 30 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Molecule AI SDK-Dev <sdk-dev@agents.moleculesai.app> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
150 lines
5.0 KiB
Markdown
150 lines
5.0 KiB
Markdown
# 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:** Not yet implemented
|
|
**Severity:** Critical
|
|
|
|
### Symptom
|
|
The repo is initialized as a Go module but has no `cmd/molecule/main.go`. Running
|
|
`go build ./cmd/molecule` or `go run ./cmd/molecule` fails with
|
|
"package cmd/molecule: cannot find module" or "build failed".
|
|
|
|
### 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:** Not yet implemented
|
|
**Severity:** High
|
|
|
|
### 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:** Identified
|
|
**Severity:** Low
|
|
|
|
### 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:** `.github/workflows/release.yml`
|
|
**Status:** Not verified
|
|
**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:** `tests/` (does not exist)
|
|
**Status:** Not yet implemented
|
|
**Severity:** Medium
|
|
|
|
### Symptom
|
|
There are no tests at all (per `go test ./...` — no packages match).
|
|
As subcommands are built, there is no test harness for end-to-end CLI testing
|
|
(e.g. `molecule workspace create --name test --output json` → verify JSON output).
|
|
|
|
### Impact
|
|
Each subcommand will be shipped without regression protection. Manual testing
|
|
is required for every release. The absence of a `tests/` directory also means
|
|
there is no fixture for CLI integration testing with recorded API responses.
|
|
|
|
### 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 `molecule-sdk-python` fixture server or recorded API responses for
|
|
offline testing
|
|
- Add `go test ./...` to CI; require >0 test packages before merge
|