feat: add 'vf docs' — search and read the documentation in-band (COR-13588) - #10
Open
Bradenream wants to merge 3 commits into
Open
feat: add 'vf docs' — search and read the documentation in-band (COR-13588)#10Bradenream wants to merge 3 commits into
Bradenream wants to merge 3 commits into
Conversation
vf docs search <query> - full-text search via the public docs search
endpoint; --output-format json for structured
{title, link, page, content} results
vf docs get <page> - print any docs page as markdown, by path or
full voiceflow.com/docs URL
Zero bundled content (no staleness, no binary growth), zero auth — it
works before any token is configured, so error hints and the quickstart
can point at runnable 'vf docs' commands even in environments where the
agent has no browser or web access.
Lives in a non-generated file (internal/cli/docs.go); the only touch on
generated code is the one-line registration in root.go, the same
persisted-edit shape that carries the hooks registration.
There was a problem hiding this comment.
Pull request overview
Adds a new vf docs command group to the CLI so users (and agent workflows) can search Voiceflow documentation and fetch docs pages as markdown directly from the terminal, without authentication.
Changes:
- Register a new
docscommand group under the root CLI command. - Implement
vf docs search(docs search endpoint) andvf docs get(fetch markdown page) ininternal/cli/docs.go. - Add Vitest coverage for
docs searchanddocs getagainst the live public docs site.
Reviewed changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
test/docs-command.test.ts |
Adds integration tests for vf docs search/get against the live docs site. |
internal/cli/root.go |
Registers the new docs command group on the root command. |
internal/cli/docs.go |
Implements vf docs command group (search + get), including HTTP request/response handling. |
Files not reviewed (1)
- internal/cli/root.go: Generated file
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The full-URL branch of 'vf docs get' guarded with
strings.Contains(page, "voiceflow.com/docs"), so a hostile URL carrying
that marker in its path, query, or fragment passed the check while the
request went to any host — arbitrary-host fetch / SSRF, and the marker in
a #fragment is never even sent on the wire. An agent fed a poisoned page
argument would ingest attacker markdown as trusted docs.
Now parse with net/url and validate the resolved components: https only,
no userinfo, host in {www.voiceflow.com, voiceflow.com}, cleaned path
under /docs; rebuild the URL from those components so nothing unvalidated
reaches the wire. Fixes the sibling bug too — appending .md after a
#fragment or ?query fetched HTML instead of markdown; .md now lands on
the cleaned path. Bare paths run through path.Clean, neutralizing
traversal. Also honor resolved output-format (config/env/agent-mode) via
output.WantsRawJSON instead of the raw flag.
Copilot review: two assertions coupled the suite to content that the docs team can change at any time — an exact H1 string, and results[0] existing without checking the array was non-empty. Assert the rendition is markdown rather than HTML, cap its size, and fail with a clear message when a staple query returns nothing.
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.
Part of COR-13588 — shipping the vf CLI as an agent-era distribution channel.
What
Zero bundled content (no staleness, no binary growth) and zero auth — it works before any token is configured, so error hints and the quickstart can point at runnable
vf docscommands even where the agent has no browser or web access. Search results include full endpoint contracts, so an agent learns an operation's schema from one CLI call.Lives in a non-generated file (
internal/cli/docs.go); the only touch on generated code is the one-line registration inroot.go— the same persisted-edit shape that carries the hooks registration. Base branch: #7.Verification
test/docs-command.test.ts) against the live docs site: search (pretty + json), get by path and by URL, 404 teaching error, non-voiceflow URL refusalgo vetclean; 15s timeout on every request; offline failure names the fix