mocklet_cli

mocklet-cli

Thin Go CLI wrapper for the Mocklet HTTP API, aligned with cli_arch_draft.md.

Current status:

• Sprint 1 foundation is complete;
• Sprint 2 platform baseline is implemented (generated client, cobra shell, config/profile/token/output scaffolding);
• Sprint 3 auth MVP is implemented (auth login/whoami/logout/token set --stdin, including CLI Google flow);
• Sprint 4 upload MVP is implemented (mock validate and mock create with file + raw/stdin transport paths);
• Sprint 5 lifecycle and release hardening is implemented (mock list/get/stats/restart/delete, output stabilization, release smoke checks);
• Sprint 6 service token management MVP is implemented (auth service-user create/list, auth service-token issue/list/revoke, one-time secret guards);
• Sprint 7 templates MVP is implemented (template create/list/get/update/delete, revision list/upload, HAR/Postman/OpenAPI export, template spawn);
• command surface v1 is fixed in docs/commands.md;
• local runtime scope is removed from CLI v1;
• CI uses GitLab (.gitlab-ci.yml) with baseline quality gates;
• OpenAPI generation workflow is fixed and documented.

Layout

Key paths:

• cmd/mocklet: binary entrypoint
• internal/cli: CLI command routing and UX shell
• internal/cloud/openapi: reserved package for generated OpenAPI client code
• internal/cloud: thin wrappers and transport error classification
• internal/output: exit code mapping and renderer skeleton
• internal/auth: token store abstraction (flag/env/keyring/file)
• internal/config: profiles and precedence resolution (flags > env > profile > defaults)
• docs: architecture and contract notes
• scripts: local quality and generation helpers
• Makefile: reproducible local workflow entrypoints
• .gitlab-ci.yml: GitLab CI checks and tag-based release workflow

Commands

Auth commands are implemented and ready for manual and CI usage:

go run ./cmd/mocklet auth login --email user@example.com --password-stdin
go run ./cmd/mocklet auth login --google
go run ./cmd/mocklet auth whoami
go run ./cmd/mocklet auth token set --stdin
go run ./cmd/mocklet auth logout
go run ./cmd/mocklet auth service-user create --name ci-bot --user-token "$MOCKLET_USER_TOKEN"
go run ./cmd/mocklet auth service-user list --user-token "$MOCKLET_USER_TOKEN" --output json
go run ./cmd/mocklet auth service-token issue --service-user-id 101 --name nightly --expires-in-seconds 3600 --show-token --user-token "$MOCKLET_USER_TOKEN"
go run ./cmd/mocklet auth service-token list --service-user-id 101 --user-token "$MOCKLET_USER_TOKEN" --output json
go run ./cmd/mocklet auth service-token revoke --service-user-id 101 --token-id 9001 --yes --user-token "$MOCKLET_USER_TOKEN"

Mock upload commands are implemented:

go run ./cmd/mocklet mock validate ./sample.har
cat ./sample.har | go run ./cmd/mocklet mock validate --stdin --output json
go run ./cmd/mocklet mock create ./sample.har --ttl-seconds 86400 --latency-emulation
cat ./sample.har | go run ./cmd/mocklet mock create --stdin --matching-rules-file ./matching_rules.json --output json

Mock lifecycle commands are implemented:

go run ./cmd/mocklet mock list --limit 20 --output table
go run ./cmd/mocklet mock get abc123 --output json
go run ./cmd/mocklet mock stats abc123 --history-limit 20 --output json
go run ./cmd/mocklet mock restart abc123
go run ./cmd/mocklet mock delete abc123 --yes

Template commands are implemented:

go run ./cmd/mocklet template create ./sample.har --name payments-template
cat ./sample.har | go run ./cmd/mocklet template create --stdin --name payments-template --output json
go run ./cmd/mocklet template list --limit 20 --output table
go run ./cmd/mocklet template get tpl_123 --output json
go run ./cmd/mocklet template update tpl_123 --docs-public --default-ttl 7200 --output json
go run ./cmd/mocklet template delete tpl_123 --yes
go run ./cmd/mocklet template revisions list tpl_123 --output json
cat ./sample.har | go run ./cmd/mocklet template revisions upload tpl_123 --stdin --output json
go run ./cmd/mocklet template export har tpl_123 -o ./template.har
go run ./cmd/mocklet template export postman tpl_123 -o ./template.postman.json
go run ./cmd/mocklet template export openapi tpl_123 --format json -o ./openapi.json
go run ./cmd/mocklet template export openapi tpl_123 --revision 2 --format yaml
go run ./cmd/mocklet template spawn tpl_123 --ttl-seconds 3600 --output json

Command tree and flags are documented in docs/commands.md.

Local workflow

make build
make test
make e2e-contract
make e2e-selfmock   # optional, requires secrets
make vet
make lint
make security
make coverage
make race
make openapi-smoke
make release-smoke

Command topology:

• make test, make race, make coverage run non-E2E packages only.
• make e2e-contract runs deterministic CLI contract E2E only.
• make e2e-selfmock runs runtime-backed self-mock E2E only.
• make ci keeps the same split and runs each tier once.

Self-mock E2E (optional, secrets required):

export MOCKLET_E2E_SELFMOCK=1
export MOCKLET_TOKEN="<token>"
make e2e-selfmock

Optional self-mock overrides for debugging:

export MOCKLET_E2E_HAR="./tmp/custom.har"               # override fixture path for all scenarios
export MOCKLET_E2E_HAR_DIR="./test/e2e/testdata/har"    # override fixture directory

CI-equivalent local check:

make ci

E2E onboarding

Source-of-truth documents:

• command surface: docs/commands.md
• output/exit contract: docs/output-contracts.md
• contract-to-test traceability: docs/e2e-regression-matrix.md

How to add a new E2E case:

1. Pick the contract row from docs/e2e-regression-matrix.md (or add a new row when contract expands).
2. Add/extend tests under test/e2e/contract or test/e2e/selfmock using test/e2e/harness.
3. Reuse harness assertions (error envelope, quiet, table columns, strict JSON decode) instead of ad-hoc checks.
4. Update matrix mapping to point to the exact test function name.

How to add a HAR fixture safely:

1. Add the fixture under test/e2e/testdata/har/.
2. Sanitize payloads: remove auth headers, cookies, secrets, and PII.
3. Keep fixture minimal (only requests needed for scenario).
4. Update test/e2e/testdata/har/README.md with fixture -> scenario -> test mapping.

OpenAPI generation

Use:

make openapi-smoke
make openapi-generate

Details are documented in docs/openapi-generation.md.

Notes

• Module path is currently gitlab.com/KeyStorke/mocklet_cli.
• Backend contract status is tracked in docs/api-contract-status.md.
• Auth strategy is fixed in docs/auth-strategy.md.
• Release flow is documented in docs/release-process.md.
• Tool versions are pinned in Makefile and CI variables in .gitlab-ci.yml.
• Coverage gate excludes generated OpenAPI package and uses configurable minimum (COVERAGE_MIN, default 50.0).