Previous README documented 3 subcommands and got the completion shape
wrong (`completion generate`). Code has 6 top-level commands plus init,
totalling 22 subcommands.
Add a full command reference covering every subcommand in cmd tree:
- workspace: list, create, inspect, delete, restart, audit, delegate
- agent: list, inspect, send, peers
- platform: audit, health
- config: list, get, set, init, view
- connect: bridge external workspace (existing Quick Start)
- init: scaffold molecule.yaml
- completion: bash | zsh | fish | powershell (was: completion generate)
Each entry has a one-line purpose, key flags where applicable, and an
example. Also calls out `connect --mode push` (M4, not yet wired) and
the canvas-origin reply TODO in internal/connect/connect.go so users
know what isn't ready yet.
README-only change. No Go code edits.
The README still described molecule-cli as a "TUI dashboard" and used
the old `molecli` binary name. After M1 (RFC #10), the primary entry
point is `molecule connect <workspace-id>` — the out-of-box bridge
between an external-runtime workspace and a local agent backend.
Rewritten to:
- lead with the connect quick-start (token + API URL + invocation)
- document the three built-in backends (claude-code, exec, mock)
with --backend-opt examples
- list the flags external-workspace operators actually need
(--mode, --interval-ms, --since-secs, --dry-run)
- note the state-file location (cursor resume across restarts)
- link RFC #10 for the full design
- fix the binary name (`molecule`, not `molecli`)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
After this PR the release pipeline produces a real out-of-box install
story for molecule-cli — multi-OS binaries with checksums, archived
with shell completions, plus a CI gate that catches races in the
new connect orchestrator.
What changed:
- `.github/workflows/release.yml`
* Vet now scans `./...` (was: three packages); silently let
regressions in internal/backends/ + internal/connect/ ship.
* Test now runs `-race -count=1 ./...` (was: just `cmd/molecule`
without race). The connect orchestrator runs heartbeat + poll
goroutines concurrently — a race here would corrupt cursor state.
* Release job switches from inline `go build` per matrix entry to
`goreleaser release --clean`. Same multi-OS output, plus
auto-generated changelog, checksum files, and one config file
that future channels (brew tap, scoop, choco) hook into without
new workflow steps.
* `goreleaser check` runs first so a broken .goreleaser.yaml fails
fast at validation, not partway through a build.
* Path filter expanded so .goreleaser.yaml edits trigger CI.
- `.goreleaser.yaml`
* Pre-generate shell completions in the before: hook so the archive
can include them. (`molecule completion <shell>` still works at
runtime — this just ships the files for users who prefer a
drop-in setup.)
* Update archive `formats:` (plural) for goreleaser v2 — `format:`
was deprecated.
* Drop the redundant per-archive checksum block; the top-level
`checksum:` covers it.
* Header comment rewritten to reflect that this is now the
canonical release path (was: "wire it up when ready").
Test plan:
- [x] yaml parses for both files
- [x] `go test -race -count=1 ./...` green
- [ ] CI on this PR exercises the new test job (vet ./..., -race ./...)
- [ ] First tag push (v0.1.0) exercises the release job
After merge, cutting v0.1.0 is:
git tag v0.1.0 && git push origin v0.1.0
# → Release artifacts auto-built and published to GitHub Releases
This is M1.4 of [RFC #10](https://github.com/Molecule-AI/molecule-cli/issues/10).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
After this PR `molecule connect <id>` actually does something useful:
the default `--backend claude-code` runs `claude -p` as a subprocess
per inbound message, capturing stdout as the reply. The general
`--backend exec --backend-opt cmd="..."` lets operators bridge to any
program that reads stdin and writes stdout (Ollama, custom Python,
shell pipelines).
What's in:
- `internal/backends/exec/exec.go` — generic exec backend.
- cmd (required): shell command, run via /bin/sh -c (or cmd /c).
- timeout (default 60s): per-message wall clock; subprocess is
killed on timeout and the dispatcher keeps the message queued.
- pass_meta (default false): when true, populates env with
MOLECULE_WORKSPACE_ID / CALLER_ID / MESSAGE_ID / TASK_ID / METHOD.
- Stdin = joined text parts; stdout = reply text.
- Stderr is captured + surfaced in error messages so operators can
see what their command printed.
- Honours ctx cancellation — SIGTERM kills the subprocess immediately.
- `internal/backends/claudecode/claudecode.go` — thin shorthand.
Translates {bin, args, timeout, pass_meta} into the equivalent exec
config. Defaults: bin=claude, timeout=5m, pass_meta=true.
Reusing exec means timeout/stdin/env handling stays in one place.
- `internal/cmd/connect.go` — registers both backends so `--help`
shows them and the default `--backend claude-code` works without
flag tuning.
Test plan:
- exec: cmd-required, bad-timeout, zero-timeout, echo-stdin-to-stdout,
text-only-part-concat, non-zero-exit-surfaces-stderr, timeout-kills-
runaway, pass_meta-injects-env, no-pass_meta-leaves-env-untouched,
parent-env-inherited-when-pass_meta-off, ctx-cancel-kills-command.
- claude-code: registered, bin/args translation produces "echo -p hello",
bad-timeout-surfaces, default-config-builds.
- All Unix tests gated on `requireUnix(t)` — Windows-shell semantics
diverge; cross-platform coverage is M3 work (brew/scoop/winget).
- Full suite green under -race.
UX after this PR:
# default — Claude Code on PATH
molecule connect ws_01HF... --token $T
# custom handler
molecule connect ws_01HF... --backend exec \
--backend-opt cmd="python myhandler.py"
# different model via Claude Code
molecule connect ws_01HF... \
--backend-opt args="--model claude-sonnet-4-6"
# CI smoke
molecule connect ws_01HF... --backend mock --backend-opt reply=ok
Out of scope (M1.4 + later):
- M1.4: GoReleaser tag-triggered release.yml workflow
- stdio backend (one persistent subprocess + line-delimited JSON-RPC)
— moved to M2 since exec covers the common case
- openai / mcp backends — M4 per RFC
RFC: https://github.com/Molecule-AI/molecule-cli/issues/10
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Implements the runtime side of `molecule connect <id>`. After this PR
the CLI can actually attach to an external workspace and round-trip
inter-agent messages through any registered backend.
What's in:
- `internal/connect/client.go` — platform-API client with bearer auth.
Endpoints: POST /registry/register (delivery_mode=poll, no URL),
POST /registry/heartbeat, GET /workspaces/:id/activity?type=a2a_receive,
POST /workspaces/:id/a2a (reply target).
Errors split into TransientError (network/5xx — retry with backoff)
and PermanentError (4xx — abort with clear message).
- `internal/connect/state.go` — atomic cursor persistence at
~/.config/molecule/state/<workspace-id>.json. Mode 0o600 (owner-only)
from day 1 because future state additions may include rotated tokens.
Atomic write-then-rename so a crash mid-write can never produce a
half-written cursor.
- `internal/connect/connect.go` — Run() orchestrator. Wires register-
with-bounded-retry, then heartbeat goroutine + poll goroutine.
Both respect ctx cancellation for clean SIGTERM.
Robustness contract per RFC #10:
* Cursor advances AFTER successful dispatch — crash mid-batch
re-delivers, never drops.
* 410 on cursor lookup → reset to "" and re-fetch (don't deadlock
on a pruned cursor).
* Heartbeat permanent error stops the heartbeat loop only; poll
loop keeps running so the operator sees "stopped" + reason in
logs and can SIGTERM.
* Backend dispatch is sequential within a batch (avoids out-of-
order replies for in-flight conversations).
* Inter-agent reply path: POST envelope to /workspaces/<source>/a2a.
* Canvas-origin reply (source_id == nil) logs + skips for now —
M1.3 wires that via the task_update activity convention.
- `internal/cmd/connect.go` — runConnect now actually calls
connect.Run() (was a placeholder ctx-wait in M1.1).
Test plan:
- httptest workspace-server stub covers register / heartbeat / activity
/ a2a reply endpoints.
- TestRun_RoundTrip_AgentReply: end-to-end ping → mock backend → pong
reply lands at source, cursor saved.
- TestRun_CanvasOriginMessageNotReplied: source_id=nil → backend fires
but no reply post; cursor still advances.
- TestRun_CursorPruned410ResetsAndContinues: server returns 410 once,
cursor resets to "", next poll dispatches the fresh row.
- TestRun_PermanentRegisterErrorAborts: 401 surfaces immediately.
- TestRun_TransientRegisterErrorRetries: 503 then 200 → register
succeeds on second attempt.
- TestRun_OptionsValidation: missing Backend / WorkspaceID surface
before any I/O.
- State: round-trip, file mode 0o600, atomic-rename leaves no .tmp
artifacts, corrupted file surfaces error.
- All tests green under -race.
Out of scope (next PRs in this stack):
- M1.3: claude-code backend (canvas-origin reply convention rides
with this)
- M1.4: GoReleaser tag-triggered release.yml workflow
- Push-mode (--mode push currently surfaces a clear "M4" error)
RFC: https://github.com/Molecule-AI/molecule-cli/issues/10
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
First step toward `molecule connect <id>` — the out-of-box external-
runtime workspace connector specified in RFC #10.
What's in this PR (foundational, ~300 LOC of code + matching tests):
- `internal/backends.Backend` — the seam every concrete handler
implements: HandleA2A(ctx, Request) → Response, Close(). Two methods,
no inheritance, no surprise side effects. Concurrency-safe by
contract (poll dispatch may parallelise).
- Request/Response/Part/Config types — lossless JSON-RPC mirror so
backends can re-issue downstream without re-parsing.
- Compile-time registry — `Register("name", factory)` from each
backend's init(); `Build(name, cfg)` selects at runtime. Panics
on duplicate registration so drift fails loudly at startup, not
on first message.
- `mock` backend — single-template echo for CI smoke + tests + demos.
`--backend-opt reply="<template>"` with `%s` for inbound text.
- `molecule connect <workspace-id>` cobra command — flag surface,
validation, --dry-run for smoke. Loops (heartbeat, activity poll,
dispatch) land in M1.2 in internal/connect/.
Coverage:
- Registry: duplicate-name panic, empty-name panic, nil-factory panic,
Build unknown-name error includes registered list.
- Mock: default template, custom template, text-part concatenation,
Final=true on terminal response.
- Connect: --backend-opt KEY=VALUE parser (incl. value with =),
flag validation (missing token, bad mode, bad opt, unknown
backend), --dry-run happy path.
All tests pass under -race.
Out of scope (subsequent M1 PRs):
- M1.2: heartbeat + activity poll loops in internal/connect/
- M1.3: claude-code backend (wraps molecule-mcp-claude-channel)
- M1.4: GoReleaser tag-triggered release.yml workflow
RFC: https://github.com/Molecule-AI/molecule-cli/issues/10
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The yaml-output-support refactor removed the combined json/yaml if-block
but left a dangling `}` that closed runPlatformHealth prematurely,
putting the tabwriter block outside the function body.
Removes the stray brace at line 137. CI vet was failing with:
platform.go:138:2: syntax error: non-declaration statement outside function body
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The `--output yaml` flag was accepted but aliased to JSON since
printYAML() was never defined. Add printYAML() using gopkg.in/yaml.v3
(already an indirect dep via viper) and split all output format
branches into explicit json/yaml/table paths.
Affected commands: workspace list/create/inspect/audit,
agent list/inspect/peers, platform audit/health.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Allows re-scaffolding an existing molecule.yaml without manual deletion.
Exit code 1 preserved for existing file without --force (usage error path).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Change rootCmd Use/Short/Long from 'mol' to 'molecule'
- Register initCmd in root so 'molecule init' works
- Update viper config name lookup from 'mol' to 'molecule'
- Fix config init/set to write molecule.yaml instead of mol.yaml
- Update all user-facing strings mol→molecule
Fixes TestCLI_Version, TestCLI_Init, TestCLI_ConfigInit, TestCLI_Completion_GeneratesScript
Go 1.25 resolves "./cmd/molecule" relative to cmd.Dir as an absolute path
under the CWD, producing the doubled "cmd/molecule/cmd/molecule" error.
Building the whole module from the root and relying on the binary name
from -o is the idiomatic Go approach and avoids path arithmetic entirely.
Also tightened error message to match the new command.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
os.Executable() in Go 1.x parallel tests resolves to <TempDir>/0/molecule.test
making path-based traversal from the binary back to the repo root unreliable.
Switch to os.Getwd() which always returns the repo checkout root in CI
(where `go test ./cmd/molecule/...` is invoked), and skip any path arithmetic.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
runtime.GOEXE is not available in Go 1.25 standard library.
Replace with the standard "go" binary name which is on PATH in CI.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
go vet reports: cmd/molecule/molecule_test.go:209:11: undefined: runtime
runtime.GOEXE is used in mol() to find the Go binary for building the
test binary. The runtime package was referenced but not imported.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
v.SafeWriteConfig() was called without a local viper instance.
Create a fresh viper scoped to the target config file, read any
existing values, set the new key, then atomically write via SafeWriteConfig.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
viper.Viper has no Marshal method in v1.21. Use SafeWriteConfig instead
which atomically writes only explicitly-set keys to the config file.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- workspace.go: remove no-op _ = workspaceID (workspaceID consumed in runHTTP call)
- molecule_test.go: replace hardcoded /workspace/repos/clone-cli path with
dynamic exe-based resolution so tests pass when built by CI
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Wires shell completion for all 4 shells via Cobra's built-in generators.
Covers the remaining item from the implementation status checklist.
Adds:
- internal/cmd/completion.go: cobra.GenXxxCompletion wrappers with
usage examples for each shell
- 5 new integration tests in cmd/molecule/molecule_test.go:
- TestCLI_Completion_Help (4 shells × help flag)
- TestCLI_Completion_GeneratesScript (4 shells × script output)
- TestCLI_Completion_InvalidShell (exit code 2 on bad shell)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
All test.Fatalf messages referenced "mol <subcommand>" but the binary
is now "molecule". Also fix configSet to use os.WriteFile atomic write
instead of viper.WriteConfig (avoids file-permission edge cases).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Update Section 2 build/test commands to reflect current state
- Rename Section 8 command tree from "mol" to "molecule" throughout
- Add --api-url flag to Global Flags table, remove --platform-url
- Update error examples to use "molecule" command name
- Replace Section 11 "Early / Stub" checklist with accurate status
- Mark all implemented commands and tests as done, keep remaining todos
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Rename all user-facing "mol" references to "molecule" to match the
published binary name (binary: molecule in .goreleaser.yaml):
- root.go: Use string, versionInfo, viper config name, flag descriptions
- init.go: section comment, Short, Long, cfgPath, scaffolded message
- config.go: Long description, Shorts, configFile, WriteFile, Stat check
- molecule_test.go: binary name, version output check, mol.yaml → molecule.yaml
Also fix test helper to use runtime.GOEXE instead of hardcoded /tmp/go/bin/go.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
rootCmd.Use was "mol" while .goreleaser.yaml sets binary: "molecule".
Align to "molecule" to match the published binary name, test
invocations, and docs. Also fix test helper to use runtime.GOEXE
instead of hardcoded /tmp/go/bin/go.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add `mol init` command (internal/cmd/init.go): scaffolds mol.yaml
in the current directory with commented config sections and
environment variable documentation. Exits with a clear "next steps"
message. Checks for existing mol.yaml before overwriting.
- Register initCmd in root.go alongside the other command groups.
- Add 2 integration tests: TestCLI_Init (scaffolding + output)
and TestCLI_Init_AlreadyExists (error path).
- Update CLAUDE.md command reference to list mol init and note it
is checked off the stub repo checklist.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The repo has no Go files at the root — go test ./... and go vet ./...
fail with "no Go files in ." in CI. Narrow the test job to the only
package with tests, and vet to the scoped package dirs.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add .goreleaser.yaml with the correct module root (dir: .) and main
package path (./cmd/molecule) so the first v* tag release produces
valid artifacts for all 6 targets. Mark KI-004 as resolved in
known-issues.md.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add 24 integration tests in cmd/molecule/molecule_test.go covering
all 18 subcommands (workspace, agent, platform, config) including
error paths for not-found and missing-arg cases
- Tests use httptest mock server; binary built per-test with correct
repo root for go build ./cmd/molecule
- Fix release.yml: correct binary name (molecule not molecli), correct
package path (./cmd/molecule not ./cmd/molecli)
- Add test job (go mod tidy + vet + test) to release.yml, runs on
every PR touching Go files
- Release job gated on test job; conditional on v* tag push
- Mark KI-005 resolved in known-issues.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds standard credential gitignore (.env / *.pem / .secrets/ / .auth_token).
Per-CEO directive 2026-04-16: every plugin and template repo should
gitignore credentials so self-hosters can't accidentally commit real
tokens to public repos.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
molecli — Go TUI dashboard for Molecule AI workspace monitoring.
Note: currently depends on platform Go packages; full API-only
decoupling tracked as follow-up.
