feat: agent doctor cli for agent with --json flag

[Kinfe123]

• feat: agent doctor cli for agents
• chore: format

---

Summary by cubic

Adds JSON output to the docs doctor CLI for agent and site scoring so CI, scripts, and other agents can consume results. JSON prints to stdout; warnings stay off the payload; docs, help, and tests updated.

• New Features
  • docs doctor --agent --json and docs doctor --site --json emit structured JSON to stdout; warnings remain on stderr.
  • parseDoctorArgs, runDoctor, and CLI help (in doctor and top-level index) support --json; human mode serializes as "site" in JSON.
  • Added tests for --json parsing and output, and expanded docs with examples and a sample JSON shape.

^{Written for commit c74eaee. Summary will update on new commits. Review in cubic}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	Apr 27, 2026 8:37pm

[pkg-pr-new]

Open in StackBlitz

@farming-labs/astro

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/astro@136

@farming-labs/astro-theme

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/astro-theme@136

@farming-labs/docs

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/docs@136

@farming-labs/theme

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/theme@136

@farming-labs/next

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/next@136

@farming-labs/nuxt

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/nuxt@136

@farming-labs/nuxt-theme

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/nuxt-theme@136

@farming-labs/svelte

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/svelte@136

@farming-labs/svelte-theme

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/svelte-theme@136

@farming-labs/tanstack-start

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/tanstack-start@136

commit: c74eaee

[cubic-dev-ai]

No issues found across 6 files

[greptile-apps]

Greptile Summary

This PR adds a --json flag to docs doctor that routes the full readiness report to stdout as pretty-printed JSON instead of terminal-formatted text, renaming the internal "human" mode to "site" in the serialized output. The implementation is clean and well-tested, covering both parseDoctorArgs and runDoctor for agent and site modes.

One minor documentation inaccuracy worth noting: README, the website docs page, and SKILL.md all state "Warnings still go to stderr" but doctor.ts has no stderr writes — all check-level warn/fail statuses are embedded in the JSON payload on stdout.

Confidence Score: 5/5

Safe to merge; the only finding is a minor documentation inaccuracy, not a code defect.

All changed logic is correct and thoroughly tested. The single finding (stderr claim in docs) is P2 and does not affect runtime behaviour.

README.md, website/app/docs/cli/page.mdx, and skills/farming-labs/cli/SKILL.md contain the misleading stderr claim.

Important Files Changed

Filename	Overview
packages/docs/src/cli/doctor.ts	Adds --json flag support: parseDoctorArgs, printDoctorJsonReport, serializeDoctorJsonReport, and runDoctor branches are all clean; "human" mode is correctly renamed to "site" in serialized output.
packages/docs/src/cli/doctor.test.ts	Adds parseDoctorArgs JSON test and two runDoctor integration tests covering agent and site modes; assertions for both the raw return value (mode: "human") and serialized JSON (mode: "site") are correct.
packages/docs/src/cli/index.ts	Adds doctor --json entry to the help text; no logic changes.
README.md	Documents --json flag and claims "Warnings still go to stderr" — this is only incidentally true via config.ts's console.warn; the doctor itself emits nothing to stderr.
website/app/docs/cli/page.mdx	Adds --json section with sample JSON shape and repeats the "warnings go to stderr" claim; same minor inaccuracy as README.
skills/farming-labs/cli/SKILL.md	Adds --json usage example and a brief explanation to the skill guide; content is accurate.

Sequence Diagram

sequenceDiagram
    participant CLI as CLI (index.ts)
    participant Parser as parseDoctorArgs
    participant Doctor as runDoctor
    participant Inspector as inspectAgent/HumanReadiness
    participant Serializer as serializeDoctorJsonReport
    participant Stdout as stdout

    CLI->>Parser: argv (e.g. ["--agent","--json"])
    Parser-->>CLI: { mode: "agent", json: true }
    CLI->>Doctor: runDoctor({ mode, json })
    Doctor->>Inspector: inspectAgentReadiness / inspectHumanReadiness
    Inspector-->>Doctor: AgentDoctorReport { mode: "agent" } or HumanDoctorReport { mode: "human" }
    alt json: true
        Doctor->>Serializer: serializeDoctorJsonReport(report)
        note over Serializer: "human" to "site" rename
        Serializer-->>Doctor: serialized report
        Doctor->>Stdout: console.log(JSON.stringify(serialized, null, 2))
    else json: false (default)
        Doctor->>Stdout: printAgentDoctorReport / printHumanDoctorReport
    end
    Doctor-->>CLI: report (internal mode preserved)

Loading

_{Reviews (1): Last reviewed commit: "chore: format" | Re-trigger Greptile}

[greptile-apps]

"Warnings go to stderr" claim is not backed by the implementation

doctor.ts has no console.warn, console.error, or process.stderr writes of its own. All check results — including those with warn or fail status — are embedded in the JSON payload sent to stdout via console.log. The only stderr path is an incidental console.warn in config.ts that fires when config module evaluation falls back to static parsing, which is an unrelated infrastructure edge case.

The same claim appears in website/app/docs/cli/page.mdx ("Warnings still go to stderr, so stdout stays safe to parse") and skills/farming-labs/cli/SKILL.md ("JSON stays on stdout while warnings stay on stderr").

Consider either updating the copy to reflect actual behavior ("The full report, including any check warnings, is written as JSON to stdout") or adding a deliberate stderr path (e.g., process.stderr.write(...)) for operational messages such as config load failures before the JSON claim is made.