Skip to content

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
mainfrom
fix/docs-high-severity
Draft

fix(docs): copy-pasteable CLI commands, no credential-less search bar, an env table that matches the launcher#893
latekvo wants to merge 3 commits into
mainfrom
fix/docs-high-severity

Conversation

@latekvo

@latekvo latekvo commented Aug 21, 2026

Copy link
Copy Markdown
Member

Three defects found while reviewing the docs site, each fixed in its own commit.

argent <subcommand> cannot be copied out of the CLI table

Every command cell in docs/reference/cli.mdx separated the two words with
U+00A0 instead of a space:

$ sed -n '11p' packages/docs/docs/reference/cli.mdx | head -c 40 | od -An -tx1 -c
  7c  20  60  61  72  67  65  6e  74  c2  a0  69  6e  69  74  60
   |       `   a   r   g   e   n   t      **   i   n   i   t   `

The character survives the build - 16 <code>argent\xa0...</code> in the built
HTML and 16 in llms-full.txt - so a reader who copies argent init and runs
it gets argent init: command not found, and so does an agent reading the
llms files.

19 occurrences replaced with ordinary spaces; nothing else in the file changed
(old.replace(' ', ' ') == new). A Repo Hygiene step now fails on the
next 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 not
depend 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.algolia fell back to the literal strings ARGENT_DOCSEARCH_APP_ID
and ARGENT_DOCSEARCH_API_KEY, and docs-publish.yml runs npm run build with
no env: block, so those placeholders were baked into every published page. The
navbarSearchWrapper CSS rule hid the button only - useDocSearchKeyboardEvents
still bound Cmd+K, the modal still opened, its queries went to
https://argent_docsearch_app_id-dsn.algolia.net/ (ERR_NAME_NOT_RESOLVED) and
the reader was told No results found for "flow". The build also emitted a
/search page (with <title>[object Object]</title>, from the shared theme),
listed it in sitemap.xml, and added a preconnect to the same dead host.

The algolia block is now built only when ALGOLIA_APP_ID and
ALGOLIA_API_KEY are both set. Without them the classic preset never loads
@docusaurus/theme-search-algolia (it keys off the block's presence), so there
is no /search route, no preconnect and no placeholder anywhere in build/;
the navbar is told not to mount the bar via the shared theme's own
isAlgoliaActive prop, so Cmd+K is never bound. The shared theme's navbar
imports @docusaurus/theme-search-algolia/client whether search is on or not,
and that module imports @theme/SearchTranslations - normally owned by the
search 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
DocSearch markup, no preconnect, no /search and no search entry in the
sitemap; with ALGOLIA_APP_ID=TESTAPPID ALGOLIA_API_KEY=testapikey the bar,
the /search page and preconnect href="https://TESTAPPID-dsn.algolia.net"
all come back.

An exported ARGENT_HOST broke every tool call

buildToolsServerEnv always overwrites ARGENT_PORT but sets ARGENT_HOST
only when the caller passes one, and the spawned child inherits the caller's
environment. The auto-spawn path (MCP, argent run) never passed one, while
recording host: "127.0.0.1" in the state file, health-checking 127.0.0.1
and returning http://127.0.0.1:<port>:

$ HOME=$SB/home2 ARGENT_HOST=::1 argent tools
connect ECONNREFUSED 127.0.0.1:50333
# state file: "host": "127.0.0.1"
# server log: GET http://[::1]:50333/tools

Every call failed, and each run left an unreachable server behind.
argent server start was never affected - both its foreground and detached
paths pass an explicit --host, defaulting to 127.0.0.1.

The auto-spawn path now passes the host it already records. The new test drives
ensureToolsServer with ARGENT_HOST=::1 exported and asserts the returned URL
answers; removing the one-line fix turns it red (expected false to be true on
the health check). test/setup/clear-argent-env.ts documented this bug as the
reason 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_HOST and
ARGENT_IDLE_TIMEOUT_MINUTES, so exporting any of them reaches nothing, and the
auto-spawn path's idle timeout is 30 minutes rather than the documented 0. The
rows now name the argent server start flag that moves each value and what a
server started on demand uses instead.

Checks run

npx tsc --build, npm run lint, npx prettier --check ., npm run knip
(exit 0), packages/docs npm run typecheck + npm run build (both with and
without credentials), and the @argent/tools-client (192) and @argent/cli
(472) suites. packages/argent has one unrelated pre-existing flake,
dispatcher > forwards SIGTERM to the child binary, which passes in isolation.

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant