[ademboukabes]

Summary

Closes #48.

Extends the remote instancer control plane so all mctf instance subcommands (spawn, extend, flag, ps, alongside existing list and destroy) drive the dedicated remote instancer admin API when instancer.url is configured in mctf.config.yml. Falls back to the local on-disk store when unset.

What changed

1. Client Expansion (internal/instancer/apiclient.go):

   • Added AdminSpawnRequest and AdminExtendRequest structs.
   • Updated do() to handle optional JSON request bodies with Content-Type: application/json and validate c.adminKey.
   • Added Spawn(ctx, req) hitting POST /admin/api/instances/spawn.
   • Added Extend(ctx, id, durationMinutes) hitting POST /admin/api/instances/{id}/extend.
   • Added Flag(ctx, id) hitting GET /admin/api/instances/{id}/flag.
   • Enhanced security: validates that MCTF_INSTANCER_ADMIN_KEY is non-empty before making requests and returns clear error.
   • Added comprehensive tests in internal/instancer/apiclient_test.go using httptest servers.

2. CLI Wiring (cmd/instance.go):

   • Wired instanceSpawnCmd to dispatch to spawnRemoteInstance when remoteInstancerURL() is set.
   • Wired instanceExtendCmd to dispatch to extendRemoteInstance when remoteInstancerURL() is set.
   • Wired instanceFlagCmd to dispatch to flagRemoteInstance when remoteInstancerURL() is set.
   • Wired instancePsCmd to dispatch to psRemoteInstance when remoteInstancerURL() is set.
   • Centralized client construction with newRemoteClient helper.
   • Preserved fallback to local store and Docker Compose execution when instancer.url is unset.
   • Added end-to-end integration tests in cmd/instance_remote_test.go.

3. Documentation & Spec Updates (docs/commands.md, docs/spec/architecture.md, docs/BACKLOG.md, cmd/instancer.go):

   • Updated command reference table in docs/commands.md noting remote vs local capability.
   • Updated docs/spec/architecture.md detailing the unified remote instancer control plane.
   • Updated cmd/instancer.go command documentation.
   • Marked remote instancer control plane as shipped in docs/BACKLOG.md.

Verification

• make test-coverage: PASS (100% tests pass with race detector)
• make lint (go vet ./... + golangci-lint run ./...): PASS (0 issues)
• make build: PASS
• ./mctf -C examples/sample-event validate: PASS
• ./mctf -C examples/sample-event generate --check: PASS