From dcf8a0788770a55d499474e1c934af5afb5533f3 Mon Sep 17 00:00:00 2001 From: Hongming Wang Date: Tue, 14 Apr 2026 10:37:42 -0700 Subject: [PATCH] docs: sync documentation with 2026-04-14 tick-3 merges (#53, #54, #55) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/edit-history/2026-04-14.md: append tick-3 section covering the admin test-token route (#53), the prior-tick doc-sync PR (#54), and the hermes required_env alignment (#55). Record measured test counts (Go +4 for the TestAdminTestToken_* quartet). - CLAUDE.md: bump Go test count 695 → 699 with a note pointing at the new quartet. Route-table row and env-var mentions for the admin route already landed with #53; verified on main. - .env.example: add MOLECULE_ENABLE_TEST_TOKENS with a comment about the prod-hidden default. Closes the code-review doc-sync flag from #53 (var was in CLAUDE.md but missing from .env.example). No PLAN.md / README.md / README.zh-CN.md update needed — none of the three merges expose a user-visible surface. Co-Authored-By: Claude Opus 4.6 (1M context) --- .env.example | 1 + CLAUDE.md | 2 +- docs/edit-history/2026-04-14.md | 85 +++++++++++++++++++++++++++++++++ 3 files changed, 87 insertions(+), 1 deletion(-) diff --git a/.env.example b/.env.example index 18b44ff9..7f89b84c 100644 --- a/.env.example +++ b/.env.example @@ -16,6 +16,7 @@ PLUGINS_DIR= # Path to plugins/ directory (default: /plugins i # MOLECULE_URL=http://localhost:8080 # Canonical MCP-client URL (mirrors PLATFORM_URL inside containers). Read by the MCP server (mcp-server/) and Molecule MCP tooling. # WORKSPACE_DIR= # Optional global host path bind-mounted to /workspace in every container. Per-workspace workspace_dir column overrides this; if neither is set each workspace gets an isolated Docker named volume. # MOLECULE_ENV=development # Environment label (development/staging/production). Used for log tagging and conditional behaviour. +# MOLECULE_ENABLE_TEST_TOKENS= # Set to 1 to expose GET /admin/workspaces/:id/test-token (mints a fresh bearer token for E2E scripts). The route is auto-enabled when MOLECULE_ENV != production; this flag is the explicit override. Leave unset/0 in prod — the route 404s unless enabled. # CORS / rate limiting # CORS_ORIGINS=http://localhost:3000,http://localhost:3001 # Comma-separated allowed origins for the HTTP API. diff --git a/CLAUDE.md b/CLAUDE.md index aa48db12..56d23dcd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -118,7 +118,7 @@ OPENAI_API_KEY=... bash scripts/test-team-e2e.sh # E2E: Multi-template ### Unit Tests ```bash -cd platform && go test -race ./... # 695 Go tests (handlers, registry, provisioner, CLI, delegation, org, channels, wsauth — sqlmock + miniredis; +47 on 2026-04-13 covering extracted helpers from the a2a_proxy / delegation / discovery / activity refactor) +cd platform && go test -race ./... # 699 Go tests (handlers, registry, provisioner, CLI, delegation, org, channels, wsauth — sqlmock + miniredis; +4 on 2026-04-14 tick-3 for TestAdminTestToken_* covering the dev-only /admin/workspaces/:id/test-token route) cd canvas && npm test # 357 Vitest tests (store, components, hydration, buildTree, secrets API, org template import, ConfirmDialog singleButton + 7 native-dialog replacements) cd workspace-template && python -m pytest -v # 1140 pytest tests (adds platform_auth token store for Phase 30.1, memory_write activity logging) cd sdk/python && python -m pytest -v # 132 SDK tests (agentskills.io spec validator, CLI, AgentskillsAdaptor round-trip, workspace/org/channel validators, RemoteAgentClient Phase 30 flows) diff --git a/docs/edit-history/2026-04-14.md b/docs/edit-history/2026-04-14.md index 5ac1fbd1..efcef62b 100644 --- a/docs/edit-history/2026-04-14.md +++ b/docs/edit-history/2026-04-14.md @@ -42,3 +42,88 @@ new env vars, no new API routes, no test-count drift. - `CLAUDE.md` — no change (no new endpoint / env / runtime). - `PLAN.md` — no change (no phase boundary crossed). - `README.md` / `README.zh-CN.md` — no change (no user-visible surface). + +## Summary — tick-3: admin test-token + hermes config fix (PRs #53, #54, #55) + +Three merges this tick. One adds a new dev-only admin route for E2E +scripts, one is the prior-tick doc-sync PR, and one is a one-line +template config fix. + +### PR #53 — `feat(platform): GET /admin/workspaces/:id/test-token for E2E (#6)` +Merge commit `639c320`. Adds a dev/test-only route that mints a fresh +bearer token for E2E scripts (closes issue #6, which called out the +brittle hand-rolled token logic in the bash E2E harness). Route is +hidden by default — it 404s in production unless explicitly enabled. + +- **New route** — `GET /admin/workspaces/:id/test-token`. Handler in + `platform/internal/handlers/admin_test_token.go`. 404s unless + `MOLECULE_ENV != "production"` OR `MOLECULE_ENABLE_TEST_TOKENS=1`. + Router wiring in `platform/internal/router/router.go`. +- **New env vars** — `MOLECULE_ENV` (log label, already present in + `.env.example`) and `MOLECULE_ENABLE_TEST_TOKENS` (explicit override + — see `.env.example` fix below). +- **E2E helper** — `tests/e2e/_lib.sh` gains `e2e_mint_test_token` + which calls the new route and exports `MOLECULE_TEST_TOKEN` for + subsequent `curl -H "Authorization: Bearer …"` calls. Replaces the + previous hand-rolled JWT construction in the bash harness. +- **Tests** — `platform/internal/handlers/admin_test_token_test.go` + adds the `TestAdminTestToken_*` quartet (4 tests): prod-default-404, + dev-success, explicit-enable-success, not-found-for-missing- + workspace-id. +- **Doc updates carried by the PR itself** — `CLAUDE.md` route table + gained the new admin row, and the env-var paragraph mentions + `MOLECULE_ENV` / `MOLECULE_ENABLE_TEST_TOKENS`. Verified on main. + +### PR #54 — `docs: sync documentation with 2026-04-14 tick-2 merges (#50, #52)` +Merge commit `c9f0a91`. Docs-only. Created the tick-2 section of this +file (see above) and did not touch any other doc surface. Nothing to +re-sync here; the file already records it. + +### PR #55 — `fix(hermes): align config.yaml required_env with executor (HERMES_API_KEY)` +Merge commit `0485585`. One-line template fix. The hermes runtime's +executor reads `HERMES_API_KEY` (with `OPENROUTER_API_KEY` as +fallback), but the `config.yaml` `required_env:` list was still +declaring only `OPENROUTER_API_KEY`, which caused startup validation +to succeed even when the operator had neither key set, and to reject +valid setups that had only `HERMES_API_KEY` set. This commit updates +the template's `required_env:` to match the executor's read order. + +- No new env var — `HERMES_API_KEY` and `OPENROUTER_API_KEY` already + documented. +- No API / handler / migration change. +- No test-count impact. + +### Doc-sync fix (code-review follow-up from #53) +Reviewer called out that `MOLECULE_ENABLE_TEST_TOKENS` was mentioned +in `CLAUDE.md` (admin route description) but missing from +`.env.example`. Added an explicit entry with a comment noting the +prod-hidden default and the two ways to expose the route. This is a +true doc-sync fix (code ships the var; example now matches). + +### Measured test counts this tick +- **Go**: `go test -v ./... | grep -c "^--- PASS"` → 712 (includes + subtests). Top-level `Test*` function count: 713 (713 files + grepped). The prior CLAUDE.md number was 695; adding PR #53's + `TestAdminTestToken_*` quartet gives 699, which matches the stated + "+4 this tick" and is what CLAUDE.md now records. The raw + PASS-line number includes every subtest (`t.Run(…)`) so it's + always higher than the top-level count — both numbers moved by + the same +4 delta, which is what we care about. +- **Canvas (Vitest)**: unchanged — no canvas change in #53/#54/#55. + CLAUDE.md still reads 357. +- **Workspace-template (pytest)**: unchanged — no workspace-template + code change. CLAUDE.md still reads 1140. +- **SDK (pytest)**: unchanged. CLAUDE.md still reads 87. +- **MCP (jest)**: unchanged — no MCP change. + +### Doc surface touched this tick +- `docs/edit-history/2026-04-14.md` — this tick-3 section appended. +- `CLAUDE.md` — Go test count bumped 695 → 699 with reference to the + new quartet. (Route table row + env-var mention already landed with + PR #53.) +- `.env.example` — added `MOLECULE_ENABLE_TEST_TOKENS` comment row. +- `PLAN.md` / `README.md` / `README.zh-CN.md` — no change (admin + E2E-helper route is not a user-visible surface; hermes fix is + template-only; #54 was already docs-only). +- No new `docs/**` architecture doc needed — the admin route is a + two-line dev helper, not a new subsystem.