feat(cli): add --raw option to docs command and refactor upgrade skill#1442
Open
feat(cli): add --raw option to docs command and refactor upgrade skill#1442
Conversation
Add --raw flag to `docs` command that fetches llms.txt content directly instead of just outputting URLs. Supports deep paths for changelog queries (package-specific, version-specific) with fallback URL construction when docs index doesn't match. Refactor upgrade skill to compose CLI primitives (docs --raw + compat) instead of relying on monolithic upgrade command. Skill now handles version detection with decision tree: explicit version → proceed, project context → read package.json, unknown → ask user. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
💤 Files with no reviewable changes (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthrough
Changes
Sequence Diagram(s)sequenceDiagram
participant User as User
participant CLI as CLI/docsCommand
participant Index as DocsIndexResolver
participant Fetch as FetchUtil
participant Console as Stdout/Stderr
Note over CLI,User: Raw 모드 흐름 (간단)
User->>CLI: 실행 `docs --raw --query {q}`
CLI->>Index: fetchDocsIndex(baseUrl)
Index-->>CLI: DocsItem? (resolved or undefined)
alt resolved
CLI->>Fetch: fetchLlmsTxt(url = baseUrl + "/llms" + selectedItem.docUrl + ".txt")
Fetch-->>CLI: content
else not resolved
CLI->>Fetch: tryFetchLlmsTxt(baseUrl, query)
Fetch-->>CLI: content or error
end
CLI->>Console: console.log(content) / console.error(err)
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
…composition The upgrade CLI command is replaced by composing docs --raw (for changelog fetch) and compat (for version detection) at the skill layer. Remove upgrade.ts, its registration in index.ts, and the now-unused fetchChangelog/fetchLatestVersion utilities. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Paths with >3 segments (e.g., react/updates/changelog/react/1.2.9) were incorrectly matching a shallower index entry (changelog), returning the wrong content. Now skips index resolution and goes directly to fallback URL construction for deep paths. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…docs Add structured decision tree for when package/version is unclear, question principles, and document how to discover available packages from changelog. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Accept SKILL.md deletion (moved to skills/seed-design/) and copy updated upgrade.md to the new location. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
Alpha Preview (Stackflow SPA)
|
Contributor
Alpha Preview (Storybook)
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
packages/cli/src/commands/docs.ts (2)
268-282:⚠️ Potential issue | 🟠 Major
--rawfallback 전에 docs index fetch가 필수면 안 됩니다.지금 구조에서는 raw 모드도 먼저
__docs__/index.json을 받아와야 해서, 깊은 changelog 경로처럼 직접 URL로 해결 가능한 케이스도 index fetch 하나가 실패하면 바로 종료됩니다. raw 모드에서는 index를 best-effort로만 쓰고, 실패하면 곧바로 직접 URL fallback으로 내려가야 합니다.🔧 제안 방향
- const docsIndex = await (async () => { - if (raw) { - return await fetchDocsIndex({ baseUrl }); - } + const docsIndex = await (async () => { + if (raw) { + return await fetchDocsIndex({ baseUrl }).catch(() => undefined); + } const { start, stop } = p.spinner(); start("문서 목록을 가져오고 있어요..."); try { const index = await fetchDocsIndex({ baseUrl }); stop("문서 목록을 가져왔어요."); return index; } catch (error) { stop("문서 목록을 가져오지 못했어요."); throw error; } })(); - const { categories } = docsIndex; + const categories = docsIndex?.categories ?? [];🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/cli/src/commands/docs.ts` around lines 268 - 282, The current async IIFE forces fetchDocsIndex to succeed even in raw mode; change its logic so that when raw is true you attempt fetchDocsIndex({ baseUrl }) but catch any error and return null/undefined instead of throwing, so the rest of the flow can fall back to direct URL handling; keep the spinner usage and try/catch behavior only for the non-raw branch (the block that uses p.spinner(), start/stop, and throws on failure), and update any subsequent code that reads docsIndex to treat null/undefined as “index unavailable” and proceed with the direct-URL fallback.
301-340:⚠️ Potential issue | 🟠 Major
--raw경로에서 선택 프롬프트를 띄우지 마세요.이 분기들은 raw 모드에서도
selectItem/selectSection/p.select를 호출합니다. 그러면--raw를 파이프나 스크립트에서 쓸 때 대기 상태에 빠지거나 취소로 끝납니다. raw 모드에서는 정확히 1건으로 확정될 때만 반환하고, 그 외에는 direct URL fallback 또는 명시적인CliError로 처리해야 합니다.Also applies to: 383-400, 415-424
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/cli/src/commands/docs.ts` around lines 301 - 340, The branches that call selectItem/selectSection or p.select (e.g., the code handling matchedCategory/matchedSection and the matched.length cases around where selectItem is used) must not prompt in raw mode; wrap those interactive calls with a guard on options.raw (or equivalent) so that when options.raw is true you only return a result if there is exactly one deterministic match and otherwise either throw a CliError with a clear message or fall back to emitting the direct URL (no interactive prompt). Specifically: in the matchedSection/items flow (the block using matchedSection.items, matched.length checks, and calling selectItem), and any other branches that call selectItem/selectSection/p.select, replace the interactive call with a conditional: if options.raw and matched.length !== 1 then throw a CliError (or return direct URL fallback), else proceed to return the single match or call selectItem when not raw.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/cli/src/utils/fetch.ts`:
- Around line 156-166: The loop currently swallows all fetch errors and maps
every non-OK result to a "not found" CliError; change it so only 404 responses
are treated as "try next URL" and everything else propagates: call
fetchWithTimeout(url) without .catch(() => null) so network/timeouts throw,
inspect the returned Response — if response.ok return response.text(); if
response.status === 404 continue to the next url; otherwise throw a descriptive
error (e.g., a CliError that includes response.status and url or rethrow the
original error) instead of falling through to the final "llms.txt를 찾을 수 없어요"
message. Ensure references to fetchWithTimeout, the urls for-loop, and CliError
are used so the new logic is applied in the same block.
In `@skills/seed-design-cli/references/upgrade.md`:
- Around line 13-32: The Markdown fenced code blocks in upgrade.md (the large
example blocks shown, e.g., the "사용자 요청 분석" and the later "정보 부족 판단" block) lack
a language tag which triggers lint MD040; update both triple-backtick fences to
specify a language (use "text") so each block starts with ```text and ends with
``` to satisfy the linter and keep content unchanged.
- Around line 34-40: The docs incorrectly recommend using the CLI "compat --all"
to read current `@seed-design/`* versions even though
packages/cli/src/commands/compat.ts only checks compatibility and does not
reliably print versions; update the text in upgrade.md to make package.json the
definitive source of truth (e.g., "read package.json for current `@seed-design/`*
versions") and remove or qualify the "npx `@seed-design/cli`@latest compat --all"
step, or alternatively change the guidance to say "only use compat --all if the
CLI has been updated to print versions" and, if you prefer fixing code instead
of docs, modify the compat command implementation (compat.ts) to explicitly read
package.json from the target project and output the `@seed-design/`* versions when
run with --all.
---
Outside diff comments:
In `@packages/cli/src/commands/docs.ts`:
- Around line 268-282: The current async IIFE forces fetchDocsIndex to succeed
even in raw mode; change its logic so that when raw is true you attempt
fetchDocsIndex({ baseUrl }) but catch any error and return null/undefined
instead of throwing, so the rest of the flow can fall back to direct URL
handling; keep the spinner usage and try/catch behavior only for the non-raw
branch (the block that uses p.spinner(), start/stop, and throws on failure), and
update any subsequent code that reads docsIndex to treat null/undefined as
“index unavailable” and proceed with the direct-URL fallback.
- Around line 301-340: The branches that call selectItem/selectSection or
p.select (e.g., the code handling matchedCategory/matchedSection and the
matched.length cases around where selectItem is used) must not prompt in raw
mode; wrap those interactive calls with a guard on options.raw (or equivalent)
so that when options.raw is true you only return a result if there is exactly
one deterministic match and otherwise either throw a CliError with a clear
message or fall back to emitting the direct URL (no interactive prompt).
Specifically: in the matchedSection/items flow (the block using
matchedSection.items, matched.length checks, and calling selectItem), and any
other branches that call selectItem/selectSection/p.select, replace the
interactive call with a conditional: if options.raw and matched.length !== 1
then throw a CliError (or return direct URL fallback), else proceed to return
the single match or call selectItem when not raw.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 5d6d9b6e-6afe-44fc-be99-345b1da9ff43
📒 Files selected for processing (7)
packages/cli/src/commands/docs.tspackages/cli/src/commands/upgrade.tspackages/cli/src/index.tspackages/cli/src/utils/fetch.tsskills/seed-design-cli/SKILL.mdskills/seed-design-cli/references/upgrade.mdskills/seed-design-cli/references/usage.md
💤 Files with no reviewable changes (1)
- packages/cli/src/commands/upgrade.ts
Comment on lines
+34
to
+40
| **프로젝트 환경에서 버전 확인 방법:** | ||
|
|
||
| 1. `package.json`을 직접 읽어 `@seed-design/react`, `@seed-design/css` 등의 버전을 확인합니다. | ||
| 2. 또는 CLI의 `compat` 명령을 활용합니다: | ||
| ```bash | ||
| npx @seed-design/cli@latest compat --all | ||
| ``` |
Contributor
There was a problem hiding this comment.
compat --all을 버전 조회 수단으로 안내하면 Step 2를 진행할 수 없어요.
packages/cli/src/commands/compat.ts 구현은 프로젝트 버전을 내부적으로 읽어 호환성만 판단하고, 현재 @seed-design/* 버전을 안정적으로 출력하지 않습니다. 여기서는 {version}이 바로 필요하니 package.json을 source of truth로 고정하거나, 실제로 버전을 출력하는 다른 경로가 있을 때만 이 설명을 남기는 편이 맞습니다.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/seed-design-cli/references/upgrade.md` around lines 34 - 40, The docs
incorrectly recommend using the CLI "compat --all" to read current
`@seed-design/`* versions even though packages/cli/src/commands/compat.ts only
checks compatibility and does not reliably print versions; update the text in
upgrade.md to make package.json the definitive source of truth (e.g., "read
package.json for current `@seed-design/`* versions") and remove or qualify the
"npx `@seed-design/cli`@latest compat --all" step, or alternatively change the
guidance to say "only use compat --all if the CLI has been updated to print
versions" and, if you prefer fixing code instead of docs, modify the compat
command implementation (compat.ts) to explicitly read package.json from the
target project and output the `@seed-design/`* versions when run with --all.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/seed-design/references/upgrade.md`:
- Around line 13-32: Two fenced code blocks in the upgrade.md file are missing a
language tag (triggering markdownlint MD040); fix by adding a language
identifier (e.g., ```text) to each of the diagram/code fences that show the
user-request analysis and the "정보 부족 판단" section so the blocks become ```text
... ```; ensure both occurrences (the earlier user request analysis block and
the later information-insufficiency block) are updated to remove the lint
warning.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 5e314baa-573a-4a45-84c9-ee606aa1bc36
📒 Files selected for processing (2)
skills/seed-design/references/upgrade.mdskills/seed-design/references/usage.md
Contributor
Alpha Preview (Docs)
|
The upgrade command was removed in favor of skill composition (docs --raw + skill). Update AGENTS.md and TECH.md accordingly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/cli/TECH.md (1)
1-73:⚠️ Potential issue | 🟠 Major
docs/content/react/getting-started/cli/commands.mdx와configuration.mdx업데이트 필요이 PR은 CLI 동작을 변경합니다. 다음 문서 파일들을 함께 업데이트해주세요:
docs/content/react/getting-started/cli/commands.mdxdocs/content/react/getting-started/cli/configuration.mdx🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/cli/TECH.md` around lines 1 - 73, Update the two docs pages to reflect the CLI changes: in docs/content/react/getting-started/cli/commands.mdx, list the new commands (init, add, add-all, compat, docs), describe that init bootstraps seed-design.json internally (no execa re-run), note defaults (rsc=false, tsx=true, path="./seed-design", telemetry=true), and document telemetry as non-blocking plus the opt-out priority (DISABLE_TELEMETRY > SEED_DISABLE_TELEMETRY > seed-design.json.telemetry); in docs/content/react/getting-started/cli/configuration.mdx, add the new configuration defaults and telemetry key behavior, describe error handling responsibilities (utils throw, commands decide process.exit and verbose stack output), and update the package scripts/environment variables table to include NODE_ENV, POSTHOG_API_KEY, POSTHOG_HOST, DISABLE_TELEMETRY, SEED_DISABLE_TELEMETRY and the bun dev/build/lint:publish scripts so docs match the changes in `@seed-design/cli`.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@packages/cli/TECH.md`:
- Around line 1-73: Update the two docs pages to reflect the CLI changes: in
docs/content/react/getting-started/cli/commands.mdx, list the new commands
(init, add, add-all, compat, docs), describe that init bootstraps
seed-design.json internally (no execa re-run), note defaults (rsc=false,
tsx=true, path="./seed-design", telemetry=true), and document telemetry as
non-blocking plus the opt-out priority (DISABLE_TELEMETRY >
SEED_DISABLE_TELEMETRY > seed-design.json.telemetry); in
docs/content/react/getting-started/cli/configuration.mdx, add the new
configuration defaults and telemetry key behavior, describe error handling
responsibilities (utils throw, commands decide process.exit and verbose stack
output), and update the package scripts/environment variables table to include
NODE_ENV, POSTHOG_API_KEY, POSTHOG_HOST, DISABLE_TELEMETRY,
SEED_DISABLE_TELEMETRY and the bun dev/build/lint:publish scripts so docs match
the changes in `@seed-design/cli`.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 29f69f19-f591-4c09-9cdc-229547a55e57
📒 Files selected for processing (2)
packages/cli/AGENTS.mdpackages/cli/TECH.md
✅ Files skipped from review due to trivial changes (1)
- packages/cli/AGENTS.md
The upgrade command was removed in favor of the upgrade skill (docs --raw + skill composition). Remove its documentation section. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Distinguish 404 from other HTTP errors in tryFetchLlmsTxt instead of swallowing all failures as "not found" - Add language tags to fenced code blocks in upgrade.md (MD040) - Remove misleading compat --all reference; use package.json as source of truth for version detection Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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
1 participant
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.
Add --raw flag to
docscommand that fetches llms.txt content directly instead of just outputting URLs. Supports deep paths for changelog queries (package-specific, version-specific) with fallback URL construction when docs index doesn't match.Refactor upgrade skill to compose CLI primitives (docs --raw + compat) instead of relying on monolithic upgrade command. Skill now handles version detection with decision tree: explicit version → proceed, project context → read package.json, unknown → ask user.
Summary by CodeRabbit
새 기능
제거된 기능
변경