fix(docs): copy-pasteable CLI commands, no credential-less search bar, an env table that matches the launcher - #893
Draft
latekvo wants to merge 3 commits into
Draft
fix(docs): copy-pasteable CLI commands, no credential-less search bar, an env table that matches the launcher#893latekvo wants to merge 3 commits into
latekvo wants to merge 3 commits into
Conversation
Every `argent <subcommand>` cell in docs/reference/cli.mdx separated the two words with U+00A0 rather than a space, and the character survives into the built HTML and llms-full.txt. Copying `argent init` out of the page and running it gives "argent init: command not found". Replace the 19 occurrences with ordinary spaces, and add a Repo Hygiene step so the next one fails CI instead of shipping: the table grew three more of them between the page landing and today.
themeConfig.algolia fell back to the literal strings ARGENT_DOCSEARCH_APP_ID and ARGENT_DOCSEARCH_API_KEY, and docs-publish.yml sets no ALGOLIA_* variables, so those placeholders were baked into every published page. The CSS rule that was meant to hide the bar only hid the button: DocSearch still bound Cmd+K, the modal still opened, and its queries went to a host that does not resolve, so every search answered "No results found". The build also emitted a /search page listed in sitemap.xml and a preconnect to the same dead host. Build the algolia block only when ALGOLIA_APP_ID and ALGOLIA_API_KEY are both set. Without them the classic preset never loads the search theme, so there is no /search route and no preconnect, and the navbar is told not to mount the bar at all. The shared theme still pulls @docusaurus/theme-search-algolia/client into the bundle either way, so a small plugin supplies the one theme alias that module needs while the search theme is absent.
buildToolsServerEnv always overwrites ARGENT_PORT but only sets ARGENT_HOST when the caller asks for one, and the spawned child inherits the caller's environment. The auto-spawn path (MCP, `argent run`) never asked, so a developer with ARGENT_HOST exported got a server bound to that address while the handle it returned, the health check and the state file all named 127.0.0.1: every tool call then failed with ECONNREFUSED, and each run left the unreachable server behind. `argent server start` was unaffected because it always passes an explicit --host. Pass the host the auto-spawn path already records, and stop the env table promising that exporting ARGENT_PORT, ARGENT_HOST or ARGENT_IDLE_TIMEOUT_MINUTES reaches the tool-server: both launchers set all three, so the flags on `argent server start` are what actually move them.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three defects found while reviewing the docs site, each fixed in its own commit.
argent <subcommand>cannot be copied out of the CLI tableEvery command cell in
docs/reference/cli.mdxseparated the two words withU+00A0 instead of a space:
The character survives the build - 16
<code>argent\xa0...</code>in the builtHTML and 16 in
llms-full.txt- so a reader who copiesargent initand runsit gets
argent init: command not found, and so does an agent reading thellmsfiles.19 occurrences replaced with ordinary spaces; nothing else in the file changed
(
old.replace(' ', ' ') == new). ARepo Hygienestep now fails on thenext one, since the table grew three more between this page landing and today.
The pattern is spelled as bytes rather than
grep -P '\x{00a0}'so it does notdepend on git being built with PCRE; it was verified to exit 1 on the fixed tree
and 0 with a single NBSP restored.
The published site shipped a search bar wired to placeholder credentials
themeConfig.algoliafell back to the literal stringsARGENT_DOCSEARCH_APP_IDand
ARGENT_DOCSEARCH_API_KEY, anddocs-publish.ymlrunsnpm run buildwithno
env:block, so those placeholders were baked into every published page. ThenavbarSearchWrapperCSS rule hid the button only -useDocSearchKeyboardEventsstill bound Cmd+K, the modal still opened, its queries went to
https://argent_docsearch_app_id-dsn.algolia.net/(ERR_NAME_NOT_RESOLVED) andthe reader was told
No results found for "flow". The build also emitted a/searchpage (with<title>[object Object]</title>, from the shared theme),listed it in
sitemap.xml, and added apreconnectto the same dead host.The
algoliablock is now built only whenALGOLIA_APP_IDandALGOLIA_API_KEYare both set. Without them the classic preset never loads@docusaurus/theme-search-algolia(it keys off the block's presence), so thereis no
/searchroute, no preconnect and no placeholder anywhere inbuild/;the navbar is told not to mount the bar via the shared theme's own
isAlgoliaActiveprop, so Cmd+K is never bound. The shared theme's navbarimports
@docusaurus/theme-search-algolia/clientwhether search is on or not,and that module imports
@theme/SearchTranslations- normally owned by thesearch theme - so a small plugin supplies that one alias while the theme is
absent.
Verified by building both ways: without credentials the output has no
DocSearchmarkup, no preconnect, no/searchand nosearchentry in thesitemap; with
ALGOLIA_APP_ID=TESTAPPID ALGOLIA_API_KEY=testapikeythe bar,the
/searchpage andpreconnect href="https://TESTAPPID-dsn.algolia.net"all come back.
An exported
ARGENT_HOSTbroke every tool callbuildToolsServerEnvalways overwritesARGENT_PORTbut setsARGENT_HOSTonly when the caller passes one, and the spawned child inherits the caller's
environment. The auto-spawn path (MCP,
argent run) never passed one, whilerecording
host: "127.0.0.1"in the state file, health-checking127.0.0.1and returning
http://127.0.0.1:<port>:Every call failed, and each run left an unreachable server behind.
argent server startwas never affected - both its foreground and detachedpaths pass an explicit
--host, defaulting to127.0.0.1.The auto-spawn path now passes the host it already records. The new test drives
ensureToolsServerwithARGENT_HOST=::1exported and asserts the returned URLanswers; removing the one-line fix turns it red (
expected false to be trueonthe health check).
test/setup/clear-argent-env.tsdocumented this bug as thereason it exists, so its rationale is updated to the general one that remains.
The same asymmetry made three rows of the tool-server env table wrong: both
launchers always set
ARGENT_PORT,ARGENT_HOSTandARGENT_IDLE_TIMEOUT_MINUTES, so exporting any of them reaches nothing, and theauto-spawn path's idle timeout is 30 minutes rather than the documented
0. Therows now name the
argent server startflag that moves each value and what aserver started on demand uses instead.
Checks run
npx tsc --build,npm run lint,npx prettier --check .,npm run knip(exit 0),
packages/docsnpm run typecheck+npm run build(both with andwithout credentials), and the
@argent/tools-client(192) and@argent/cli(472) suites.
packages/argenthas one unrelated pre-existing flake,dispatcher > forwards SIGTERM to the child binary, which passes in isolation.