76f37d928f
Migrates go.mod + 22 Go imports + README + comments + generated config templates off the dead github.com/Molecule-AI/ identity onto the vanity host go.moleculesai.app, owned by us. Surfaces touched: - go.mod module declaration: github.com/Molecule-AI/molecule-cli -> go.moleculesai.app/cli - Every Go import statement under cmd/ + internal/ - README install section: rewritten to lead with the vanity install command (the previous text was migration-in-progress hedging) - Comment URLs in internal/backends/backend.go + internal/cmd/connect.go (https://github.com/Molecule-AI/molecule-cli/issues/10) -> point at git.moleculesai.app/molecule-ai/molecule-cli - Generated config templates in internal/cmd/init.go + internal/cmd/config.go: header URL updated so new users land on the live SCM - Adds internal/lint/import_path_lint_test.go — structural test that walks every *.go / *.mod / Dockerfile / *.md / *.sh / *.yml in the module and rejects future references to github.com/Molecule-AI/ or Molecule-AI/molecule-monorepo. Mutation-tested before commit. Test plan - go build ./... clean - go test ./... green (cmd/molecule + 5 internal packages + new lint gate, all pass) - TestNoLegacyGitHubImportPaths fails on injected canary, passes on clean tree (no tautology) Open dependency - go.moleculesai.app responder must be deployed before 'go install go.moleculesai.app/cli/cmd/molecule@latest' works externally. Internal builds + 'go build ./cmd/molecule' from a fresh clone work today (self-referential module path). - Responder code prepared (worker.js, vendor-portable for CF Workers / Vercel Edge); deploy tracked separately under internal#71 phase 1. Pairs with parallel migrations of plugin-gh-identity (#3) + molecule-controlplane + molecule-core under the same internal#71 sweep. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
151 lines
6.4 KiB
Markdown
151 lines
6.4 KiB
Markdown
# molecule-cli
|
|
|
|
Go CLI for the Molecule AI agent platform. Wraps the platform's workspace runtime and control plane APIs, providing a unified command-line interface for managing agents, workspaces, and deployments.
|
|
|
|
**Users:** Platform operators and developers integrating with the Molecule AI platform.
|
|
|
|
**Repo state (2026-04-16):** Thin/stub. Go module is initialized; core CLI commands are not yet implemented. CI (Go binary release via GoReleaser + GitHub Actions) is wired up.
|
|
|
|
---
|
|
|
|
## 1. Project Overview
|
|
|
|
This CLI is the primary user-facing tool for interacting with the Molecule AI platform. Typical responsibilities:
|
|
|
|
- Workspace lifecycle management (create, destroy, inspect)
|
|
- Control plane interaction (agents, deployments, config)
|
|
- Local development proxy / dev mode against the workspace runtime
|
|
- Configuration management (env vars, config files, workspace templates)
|
|
|
|
## 2. Build, Test, and Local Run
|
|
|
|
```bash
|
|
# Build the binary to ./bin/molecule (or $GOBIN/molecule)
|
|
go build -o bin/molecule ./cmd/molecule
|
|
|
|
# Run tests (none yet; add as commands are implemented)
|
|
go test ./...
|
|
|
|
# Run the CLI locally (requires platform env vars — see Section 5)
|
|
./bin/molecule --help
|
|
```
|
|
|
|
There is no `main.go` or `cmd/molecule/main.go` yet. Creating it is the first implementation task. The module path will be auto-detected from `go.mod`.
|
|
|
|
## 3. Go Module Conventions
|
|
|
|
**Module path:** `go.moleculesai.app/cli` (from `go.mod`)
|
|
|
|
**Dependency management:**
|
|
- Use `go mod tidy` after adding or removing dependencies.
|
|
- Pin transitive dependencies if platform compatibility is a concern; document why in a comment.
|
|
- Do not commit generated lock files beyond `go.sum`. `go.sum` is the lock.
|
|
- Before upgrading a major dependency (especially the platform SDK), check whether the platform enforces API compatibility constraints (`docs/development/constraints-and-rules.md`).
|
|
|
|
**go.sum hygiene:** Run `go mod tidy` and `go mod verify` in CI. A dirty `go.sum` (extra entries, missing checksums) is a CI failure.
|
|
|
|
## 4. Release Process
|
|
|
|
Releases are fully automated via GoReleaser + GitHub Actions. You do not need to run GoReleaser locally.
|
|
|
|
**To cut a release:**
|
|
|
|
```bash
|
|
# 1. Pull and ensure you're on main with a clean history
|
|
git checkout main && git pull
|
|
|
|
# 2. Tag with a semantic v prefix; push the tag
|
|
git tag v0.1.0
|
|
git push origin v0.1.0
|
|
```
|
|
|
|
The GitHub Actions workflow (`.github/workflows/release.yml`) triggers on tags matching `v*`. GoReleaser builds the binary for the configured targets and creates a GitHub Release automatically.
|
|
|
|
**Rules:**
|
|
- Tags must match `v*` (e.g., `v0.1.0`, not `0.1.0`).
|
|
- Do not push release tags from branches; always from a clean main.
|
|
- If the release build fails, fix forward: do not delete remote tags. Create a corrected tag (e.g., `v0.1.1`) and push it.
|
|
- Changelog is generated by GoReleaser from conventional commits. Use conventional commit messages on merged PRs.
|
|
|
|
## 5. Platform Integration Notes
|
|
|
|
The CLI will interact with the Molecule AI platform via two interfaces:
|
|
|
|
**Control plane API:** REST/HTTP endpoints for agent management, workspace lifecycle, and deployment config. Endpoint base URL is configured via environment variable.
|
|
|
|
**Workspace runtime:** The local or hosted runtime that executes agent workloads. The CLI proxies or delegates to this runtime in dev mode.
|
|
|
|
**Required environment variables:**
|
|
|
|
| Variable | Description | Required |
|
|
|---|---|---|
|
|
| `MOLECULE_API_URL` | Control plane API base URL | Yes |
|
|
| `MOLECULE_RUNTIME_URL` | Workspace runtime URL | For dev/proxy mode |
|
|
| `MOLECULE_API_TOKEN` | API authentication token | Not yet; MVP has no auth per platform rules |
|
|
|
|
> **Note:** Per platform constraints (`docs/development/constraints-and-rules.md`), this is an MVP repo with no auth. The CLI should not emit or accept bearer tokens unless the platform constraints doc is updated.
|
|
|
|
**Platform docs to read before touching auth or secrets:**
|
|
- `docs/development/constraints-and-rules.md`
|
|
- `docs/runbooks/saas-secrets.md` (before rotating any secrets)
|
|
|
|
## 6. CLI Design Conventions
|
|
|
|
**Command structure:** Follow `kubectl` / `gh` patterns. Structure is:
|
|
|
|
```
|
|
molecule <resource> <verb> [flags]
|
|
```
|
|
|
|
Examples:
|
|
```
|
|
molecule workspace create
|
|
molecule workspace list
|
|
molecule agent inspect <agent-id>
|
|
```
|
|
|
|
**Error output style:**
|
|
- Errors go to stderr. Always.
|
|
- Format: `[resource] [verb]: [specific error]` — not a stack trace.
|
|
- Exit code 1 for errors; 0 for success; 2 for usage/flag errors.
|
|
- Wrap platform API errors with the CLI context so they are actionable.
|
|
|
|
**Flag conventions:**
|
|
- Global flags ( `--output`, `--verbose`, `--config`) come before subcommands.
|
|
- Boolean flags use `--flag` / `--no-flag` inversion where appropriate.
|
|
- Environment variable overrides: prefer it. Flag → env var → default.
|
|
- No single-letter flags unless they are universally understood (`-h`, `-v`, `-o`, `-f`).
|
|
|
|
## 7. Known Issues
|
|
|
|
See `known-issues.md` at the repo root for the full tracked list.
|
|
|
|
**Policy:** File a GitHub issue before patching silently. Do not merge a workaround without a linked issue.
|
|
|
|
## 8. Implemented
|
|
|
|
- [x] `cmd/molecule/main.go` — entry point with root command
|
|
- [x] Root command and global flags (`--verbose`, `--output`, `--config`)
|
|
- [x] `workspace create`, `workspace list`, `workspace delete` subcommands
|
|
- [x] `agent inspect`, `agent list` subcommands
|
|
- [x] Control plane API client (initialized with `MOLECULE_API_URL`)
|
|
- [ ] Workspace runtime client (for dev/proxy mode)
|
|
- [ ] Configuration file (e.g., `~/.config/molecule/cli.yaml`) — workspace template per platform rules
|
|
- [ ] Unit tests for core command logic
|
|
- [ ] `molecule init` (bootstrap local workspace config)
|
|
|
|
**Platform constraint reminders (from `constraints-and-rules.md`):**
|
|
- Postgres is the source of truth. CLI commands that mutate state ultimately write to Postgres via the control plane.
|
|
- Bundles must never contain secrets. Any config templating must enforce this.
|
|
- Workspace templates are generic by default. Platform-provided templates are used; do not bake environment-specific values into templates.
|
|
|
|
---
|
|
|
|
## Platform Conventions (Inherited)
|
|
|
|
These apply to all platform repos including this one:
|
|
|
|
- **Cron discipline:** Read `cron-learnings` before reviewing PRs. After each triage cycle, write a 1-line reflection to `.claude/per-tick-reflections.md`.
|
|
- **CLAUDE.md / PLAN.md sync:** PRs that touch `CLAUDE.md` or `PLAN.md` are always noteworthy — review them carefully.
|
|
- **Secrets rotation:** Before rotating any secrets, read `docs/runbooks/saas-secrets.md`.
|