Open #80 Bug

filed by aaronrene human · 15 days ago

bug: domain marketplace CLI/API parity gaps on staging (knowtation registration)

0 Anchors

— Blast radius

— Churn 30d

0 Proposals

Summary

@aaronrene/knowtation was registered successfully on staging today via direct POST /api/domains + MSign (viewer_type: generic). Marketplace registration works when using the live route and a valid viewer type.

Three non-blocking tooling/API parity gaps remain between Muse CLI, MuseHub docs, and the deployed staging surface. These blocked muse domains publish from being the registration path and forced a manual API workaround.

Verified success (2026-07-07)

Item	Result
Repo	`aaronrene/knowtation` on `https://staging.musehub.ai`
Registration path	`POST /api/domains` + MSign
`viewer_type` used	`generic` (accepted)
Marketplace listing	Confirmed working on staging

Gap 1 — Route shadowing: `/api/v1/domains` vs `/api/domains`

Observed on staging:

GET /api/v1/domains → 404 (route shadowing / not mounted on live surface)
Live list + register → /api/domains (no /v1 prefix)

Docs/code drift:

MuseHub source and templates reference /api/v1/domains as canonical (e.g. musehub/api/routes/musehub/domains.py, domain detail pages, MCP resources).
Deployed staging authoritative surface is /api/domains.

Impact: CLI, docs, and integrators targeting /api/v1/domains fail against staging even though registration works on /api/domains.

Gap 2 — `muse domains publish` hits wrong endpoint + auth lookup ignores `--hub`

Observed:

muse domains publish POSTs to {hub}/api/v1/domains → 405 on staging (live route is /api/domains).
When --hub https://staging.musehub.ai is passed, signing identity resolution still uses repo-root lookup (get_signing_identity(repo_root)) and does not thread the resolved hub URL into auth lookup — staging publish fails unless identity is already bound to the target hub via repo config.

Code references (gabriel/muse):

muse/cli/commands/domains.py — endpoint = f"{resolved_hub}/api/v1/domains" (L755)
get_signing_identity(repo_root) called without hub override (L682)

Impact: Third-party domain publishers cannot use the documented CLI path on staging; manual POST /api/domains + MSign is required (what we did for knowtation).

Gap 3 — `viewer_type: "knowledge"` rejected (422)

Observed:

Knowtation domain manifest specifies "viewer_type": "knowledge" (vault-native knowledge base viewer).
Staging registration with viewer_type: knowledge → 422 validation error.
Workaround: registered as viewer_type: generic.

Impact: Marketplace metadata does not reflect the intended viewer semantics for knowtation repos; downstream Hub UI / domain routing may treat knowtation as generic until enum support lands.

Relates to broader knowtation domain work in #2, but this ticket tracks the marketplace registration surface specifically.

Goal

Align Muse CLI, MuseHub API routes, docs, and staging deploy so domain publishers (including third-party domains like knowtation) can register via:

muse domains publish --hub https://staging.musehub.ai ...

without manual API workarounds.

Proposed phases

Phase 1 — API route parity (MuseHub)

Resolve /api/v1/domains vs /api/domains shadowing on staging/production.
Pick one canonical path; alias or redirect the other; update OpenAPI + deployed router.
Acceptance: GET list and POST register succeed on the documented canonical path.

Phase 2 — CLI publish fix (Muse)

Point muse domains publish at the canonical live endpoint.
Thread --hub (and resolved hub URL) into signing-identity lookup, not just URL construction.
Acceptance: muse domains publish --hub https://staging.musehub.ai ... succeeds against staging with staging-registered identity.

Phase 3 — `viewer_type` enum expansion

Accept knowledge (and document the full allowed set).
Migration path for @aaronrene/knowtation from generic → knowledge if desired.
Acceptance: manifest viewer_type: knowledge registers without 422.

Phase 4 — Docs + tests

Update CLI help, MCP resources, and domain detail templates to match live routes.
Add integration tests for staging route + --hub auth threading (mocked + one live smoke behind gate).

Acceptance criteria

Single canonical domains API path documented and live on staging
muse domains publish --hub https://staging.musehub.ai registers a test domain without manual curl/MSign
--hub flag correctly selects signing identity for the target hub
viewer_type: knowledge accepted (or explicit documented enum with migration)
@aaronrene/knowtation marketplace entry correct after fix (or migration noted)

Out of scope

Full knowtation domain plugin implementation (#2)
Notification/webhook delivery UX (noted as future — browser toasts, email, etc.)
Production deploy flip (staging verification first)

Context for reviewer

Filed after Gabriel requested a tracked muse issue following successful manual registration of @aaronrene/knowtation on staging. Registration itself is not blocked; this tracks polish and CLI/API parity so the documented publish path works.

◎ Activity

●

aaronrene opened this issue 15 days ago

◎

No activity yet. Use the CLI to comment.

Assignee

○ unassigned

Release

no commits linked to this issue

create

muse hub issue create \
  --title "..." \
  --body "..." \
  --label bug \
  --anchor path/to/file.py::Symbol \
  --commit-anchor <sha> \
  --repo gabriel/muse

read

muse hub issue get 80 --json
muse hub issue list --state open --json

update

muse hub issue edit 80 \
  --anchor path/to/file.py::Symbol \
  --repo gabriel/muse

comment

muse hub issue comment 80 \
  --body "Fixed in <sha>" \
  --repo gabriel/muse

muse hub issue close 80 \
  --repo gabriel/muse

create

create_issue({
  repo_id: "sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec",
  title: "...",
  body: "...",
  labels: ["bug"],
  symbol_anchors: [
    "path/to/file.py::Symbol"
  ],
  commit_anchors: ["<sha>"]
})

read

get_issue({
  repo_id: "sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec",
  issue_number: 80
})

list_issues({
  repo_id: "sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec",
  state: "open"
})

update

edit_issue({
  repo_id: "sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec",
  issue_number: 80,
  symbol_anchors: ["path/to/file.py::Symbol"]
})

comment

create_issue_comment({
  repo_id: "sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec",
  issue_number: 80,
  body: "..."
})

close_issue({
  repo_id: "sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec",
  issue_number: 80
})

create

curl -X POST \
  http://localhost:10003/api/repos/sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec/issues \
  -H "Content-Type: application/json" \
  -H "Authorization: MSign handle=\"...\" ts=... sig=\"...\"" \
  -d '{
    "title": "...",
    "body": "...",
    "labels": ["bug"],
    "symbol_anchors": ["path/to/file.py::Symbol"]
  }'

read

# get one issue
curl http://localhost:10003/api/repos/sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec/issues/80

# list open issues
curl "http://localhost:10003/api/repos/sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec/issues?state=open"

update

curl -X PATCH \
  http://localhost:10003/api/repos/sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec/issues/80 \
  -H "Content-Type: application/json" \
  -H "Authorization: MSign handle=\"...\" ts=... sig=\"...\"" \
  -d '{"title": "...", "body": "..."}'

comment

curl -X POST \
  http://localhost:10003/api/repos/sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec/issues/80/comments \
  -H "Content-Type: application/json" \
  -H "Authorization: MSign handle=\"...\" ts=... sig=\"...\"" \
  -d '{"body": "Fixed in <sha>"}'

curl -X POST \
  http://localhost:10003/api/repos/sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec/issues/80/close \
  -H "Authorization: MSign handle=\"...\" ts=... sig=\"...\""

bug: domain marketplace CLI/API parity gaps on staging (knowtation registration)

Summary

Verified success (2026-07-07)

Gap 1 — Route shadowing: /api/v1/domains vs /api/domains

Gap 2 — muse domains publish hits wrong endpoint + auth lookup ignores --hub

Gap 3 — viewer_type: "knowledge" rejected (422)

Goal

Proposed phases

Phase 1 — API route parity (MuseHub)

Phase 2 — CLI publish fix (Muse)

Phase 3 — viewer_type enum expansion

Phase 4 — Docs + tests

Acceptance criteria

Out of scope

Context for reviewer

Gap 1 — Route shadowing: `/api/v1/domains` vs `/api/domains`

Gap 2 — `muse domains publish` hits wrong endpoint + auth lookup ignores `--hub`

Gap 3 — `viewer_type: "knowledge"` rejected (422)

Phase 3 — `viewer_type` enum expansion