Add verify-shell-docs (+ unit tests), probe-shell-docs, probe-claude-quickstarts
(Playwright), and check-claude-quickstarts-runtime (extracts and runs the
documented commands/snippets) to gate the shell-docs build and quickstart
runtime. Includes CR hardening: drained server pipes, temp-dir cleanup,
SIGKILL escalation, a stack-trace-leak guard that matches SSE-escaped newlines,
and a fixed false-negative in the missing-import check.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Six fixes from CR Round 1 partition, all bucket (a):
- frontend_tools.py: docstring claimed the file was "Chat Customization
(CSS) demo" but langgraph.json wires it as the Frontend Tools demo
graph, and the new MDX setup snippets cite this exact file via the
freshly-added `# region: middleware` markers. Users following the
langgraph-python copilot-middleware setup would see CSS-demo wording
on a Frontend Tools page. Rewrote the docstring to match what the
cell actually demonstrates (mirroring the sibling
frontend_tools_async.py phrasing).
- page.tsx mergeFrameworkNav: when introNode was non-null AND the root
nav had no "Get Started" section, introNode was prepended to rootNav
shifting every existing index +1. The adjustment block only added +1
when getStartedIdx !== -1, so the splice-back position for the
framework section was off-by-one in the no-Get-Started branch — the
framework header rendered one slot too early in the sidebar.
- docs-page-view.tsx h2/h3 overrides: `{...rest}` was spread AFTER
`id={id}`, so an MDX-supplied `<h2 id="custom">` would override the
slugified id and silently break the TOC anchor + any inbound deep-
links keyed on the slug. Reordered the spread so rest comes first
and the slug-id always wins.
- probe-shell-docs.ts: terminated with bare `main();` while every
sibling script (audit-docs-porting, verify-shell-docs) wraps in
`.catch(e => { console.error(e); process.exit(1); })`. A rejected
main() would surface as an unhandled rejection on older Node
runtimes and exit 0 in CI, masking failure. Aligned with the
established pattern.
- verify-shell-docs.ts: all four regex checks (InlineDemo refs,
Snippet regions, internal links, alias imports) scanned page.body
raw without first stripping fenced code blocks. Any docs page that
showed example code containing `<InlineDemo demo="x" />`,
`[link](/path)`, or `import x from "@/..."` triggered a false-
positive validator failure. Mirrors audit-docs-porting.ts's
FENCED_CODE_RE approach. Adds a regression test that fails without
the strip.
- 3 new MDX content fixes:
* mcp-apps.mdx + open-generative-ui.mdx: removed duplicate `<Callout>`
"Free course" blocks (the same Callout appeared twice on each
page, separated only by the Key Benefits list).
* subagents.mdx: changed `[OnStateChanged, OnRunStatusChanged]` to
`[UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged]`
— the bare identifiers aren't exported (the reference doc
`useAgent.mdx` confirms the qualified form), so a user copying
the snippet would hit an import error.
Call-site enumeration:
- frontend_tools.py: only langgraph.json + the new setup MDX files
reference this file by name; both consume the region markers, not
the docstring. Docstring rewrite has zero call-site impact.
- mergeFrameworkNav: single caller (FrameworkScopedDocsPage at this
file's bottom). The new branch covers a strictly broader case;
the original splice/replace paths are unchanged.
- h2/h3: only used by the MDXRemote `components` map below. Spread
order is a local prop-precedence change; no upstream callers.
- probe-shell-docs main(): no external callers.
- verify-shell-docs check functions: 4 exported functions called
from runChecks() below + the test file. Strip is internal to each
function so signature is unchanged.
- UseAgentUpdate: confirmed exported from `@copilotkit/react-core/v2`
per reference doc useAgent.mdx; no implementation change needed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a verification script under showcase/scripts/ that enumerates
every URL each visible framework should serve, fetches each against
a running dev server, and flags 404s + soft render failures via
structural signals (`<main>` + `<h1>` present in the SSR HTML).
Coverage: 17 visible frameworks = 14 registered integrations
(filtering docs_mode: hidden) + 3 docs-only frameworks (a2a /
agent-spec / deepagents — root URL only, since their route handler
explicitly notFound()s scoped subpaths). 618 URLs in the current
tree. Used by the cutover to confirm every authored framework's
ported MDX, every generated framework's data-driven layout, and
every hidden framework's 404 + switcher absence all render as
intended.
Design notes:
- Text matches against runtime/MDX error strings false-positive
consistently in dev mode (Next.js bundles helper sources like
MDXRemote and the not-found component into every page's
serialized React tree, so "MDXRemote ... error" or
"page could not be found" appear in every successful page's
HTML). Structural signals are reliable; text patterns aren't.
- For docs-only frameworks, only the root URL is probed.
Enumerating their MDX tree would produce false-positive 404s
because the route handler intentionally restricts them to
`/<slug>`.
Usage: `cd showcase/scripts && PREVIEW_URL=http://localhost:3003 \
npx tsx probe-shell-docs.ts`. CONCURRENCY defaults to 8.
Tyler Slaton