feat(tools/discourse): read-only topic bridge audit #13

What should happen

Provide a stdlib-only magpie-discourse topic view <id|url> [--max-posts N]
command that reads a Discourse topic and its available post stream as structured JSON.
This fork issue tracks the first, read-only slice of apache/magpie#307 for human audit.

Why

Projects that discuss design and governance on Discourse need a way to read those
conversations without scraping rendered pages or treating forum text as agent instructions.
A normalized thread/message shape makes the data reusable by later Magpie integrations.
The upstream baseline has no Discourse bridge.

Which layer

Tool / bridge and Python package.

Boundary conditions

• Anonymous reads for public topics; optional Api-Key and Api-Username for authorized reads.
• HTTPS only, including subpath deployments; credentials stay on the configured origin and forum path; only GET is permitted.
• Fetch missing posts in batches of at most 20, preserving API post-stream order rather than promising chronological order. Reject duplicate stream IDs.
• Default maximum: 500 posts; truncated reports only that limit. It is not a response-byte or whole-command time budget.
• Missing requested posts fail immediately after their batch, before later requests. Malformed responses fail explicitly, with no successful JSON output.
• Every response post, including posts outside the output cap, requires a string cooked body. Preserve explicit empty strings, whitespace and HTML; reject missing/null/non-string bodies.
• Add boolean body_hidden from the optional boolean cooked_hidden marker, defaulting to false; it is separate from hidden and does not prove original text or public visibility.
• Preserve self-consistent empty results; missing collections/streams and non-empty topics with empty streams remain errors.
• Partial mail-archive-shaped output does not make this a complete/selectable archive backend.
• Mega topics without ordinary post ID streams are explicitly unsupported; no dedicated pagination or partial success.
• Output does not classify visibility; callers establish privacy approval before passing content to a model.
• ASCII API usernames, latin-1 API keys and valid base paths are required before requesting; errors do not echo credential values.
• Both raw and once-decoded URL paths must stay within the configured forum; encoded separators, literal-percent paths and nested escapes are refused. Normal UTF-8 slugs and share parameters remain supported.
• Configured base paths must percent-encode non-ASCII characters and spaces; reject raw Unicode/space paths before HTTP without automatically rewriting them.
• JSON escapes preserve Unicode on legacy stdout.

Reproduction and acceptance

The existing local prototype passed its original 35 tests but silently reported
complete results when a batch omitted a requested post, and raised unhandled
exceptions for malformed nested payloads and invalid URL ports.
New mocked regressions reproduce those cases before the fixes.

The fourth review additionally confirmed that missing/null bodies were silently
converted to empty strings, an incomplete batch did not stop later requests,
and duplicate stream IDs could consume the post limit. These now fail explicitly.
The revised package has 213 mocked tests; the linked PR records the full checks.

Acceptance requires package tests and static checks, the five repository integration
test suites, the full pre-commit gates, the Magpie pre-first-PR checklist, and one
anonymous GET-only forum check within a ten-request budget.
The linked draft PR records the exact verification results.

Out of scope

Topic listing/search, user activity, posting, complete mail-archive verbs,
skill integration, plain-text conversion, automatic retries and sandbox changes.

Upstream submission

The first implementation is submitted as apache/magpie#1755, targeting upstream main.
The linked fork draft retains the audit baseline and review history; the upstream PR records validation on its newer baseline.

References

• Fork audit pull request
• Upstream feature request
• Discourse API

AI disclosure

AI-generated text for the fork audit record. The author has completed review of the implementation.
Claude Code assisted the initial local prototype; Codex assisted its revision,
regression tests and verification.