Skip to content

feat: add 'vf docs' — search and read the documentation in-band (COR-13588) - #10

Open
Bradenream wants to merge 3 commits into
braden/fix-local-build-gosum/COR-0from
braden/vf-docs-command/COR-0
Open

feat: add 'vf docs' — search and read the documentation in-band (COR-13588)#10
Bradenream wants to merge 3 commits into
braden/fix-local-build-gosum/COR-0from
braden/vf-docs-command/COR-0

Conversation

@Bradenream

@Bradenream Bradenream commented Aug 26, 2026

Copy link
Copy Markdown

Part of COR-13588 — shipping the vf CLI as an agent-era distribution channel.

What

vf docs search <query>   # full-text search via the public docs search endpoint
                         # --output-format json → {title, link, page, content}
vf docs get <page>       # print any docs page as markdown, by path or full URL

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 docs commands 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 in root.go — the same persisted-edit shape that carries the hooks registration. Base branch: #7.

Verification

  • 5/5 vitest tests (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 refusal
  • go vet clean; 15s timeout on every request; offline failure names the fix

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.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 docs command group under the root CLI command.
  • Implement vf docs search (docs search endpoint) and vf docs get (fetch markdown page) in internal/cli/docs.go.
  • Add Vitest coverage for docs search and docs get against 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.

Comment thread internal/cli/docs.go
Comment thread internal/cli/docs.go Outdated
Comment thread test/docs-command.test.ts
Comment thread test/docs-command.test.ts Outdated
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.
@Bradenream Bradenream changed the title feat: add 'vf docs' — search and read the documentation in-band feat: add 'vf docs' — search and read the documentation in-band (COR-13588) Aug 26, 2026
@linear-code

linear-code Bot commented Aug 26, 2026

Copy link
Copy Markdown

COR-13588

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.
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.

2 participants