diff --git a/cmd/skillshare/check.go b/cmd/skillshare/check.go
index 394ee5230..8aac1a288 100644
--- a/cmd/skillshare/check.go
+++ b/cmd/skillshare/check.go
@@ -208,9 +208,9 @@ func cmdCheck(args []string) error {
logCheckOp(cfgPath, 0, 0, 0, 0, scope, start, err)
return err
}
- renderAgentCheck(projectCfg.EffectiveAgentsSource(cwd), opts.groups, opts.json)
- logCheckOp(cfgPath, 0, 0, 0, 0, scope, start, nil)
- return nil
+ cmdErr := renderAgentCheck(projectCfg.EffectiveAgentsSource(cwd), opts.groups, opts.json)
+ logCheckOp(cfgPath, 0, 0, 0, 0, scope, start, cmdErr)
+ return cmdErr
}
cmdErr := cmdCheckProject(cwd, opts)
logCheckOp(cfgPath, 0, 0, 0, 0, scope, start, cmdErr)
@@ -225,9 +225,9 @@ func cmdCheck(args []string) error {
// Agent-only check: scan agents source directory and skip repo checks.
if kind == kindAgents {
agentsDir := cfg.EffectiveAgentsSource()
- renderAgentCheck(agentsDir, opts.groups, opts.json)
- logCheckOp(cfgPath, 0, 0, 0, 0, scope, start, nil)
- return nil
+ cmdErr := renderAgentCheck(agentsDir, opts.groups, opts.json)
+ logCheckOp(cfgPath, 0, 0, 0, 0, scope, start, cmdErr)
+ return cmdErr
}
// No names and no groups → check all (existing behavior)
@@ -349,9 +349,7 @@ func runCheck(sourceDir, projectRoot string, jsonOutput bool, extraTargetNames [
if output.Skills == nil {
output.Skills = []checkSkillResult{}
}
- out, _ := json.MarshalIndent(output, "", " ")
- fmt.Println(string(out))
- return nil
+ return writeJSONResult(output, checkResultsError(repoResults, skillResults))
}
// Display results + summary, with unknown target names in skill-level
@@ -359,7 +357,7 @@ func runCheck(sourceDir, projectRoot string, jsonOutput bool, extraTargetNames [
warnings := unknownSkillTargetWarnings(sourceDir, extraTargetNames, walk)
renderCheckResults(repoResults, skillResults, false, warnings, start)
- return nil
+ return checkResultsError(repoResults, skillResults)
}
// renderCheckResults lists the repos and skills that need attention, then
@@ -663,9 +661,7 @@ func runCheckFiltered(sourceDir, projectRoot string, opts *checkOptions, walks .
if output.Skills == nil {
output.Skills = []checkSkillResult{}
}
- out, _ := json.MarshalIndent(output, "", " ")
- fmt.Println(string(out))
- return nil
+ return writeJSONResult(output, checkResultsError(repoResults, skillResults))
}
// Single target: one row, like update
@@ -675,12 +671,34 @@ func runCheckFiltered(sourceDir, projectRoot string, opts *checkOptions, walks .
if r.next != "" {
ui.Next(r.next, r.why)
}
- return nil
+ return checkResultsError(repoResults, skillResults)
}
// Display results + summary (filtered: show local skills individually)
renderCheckResults(repoResults, skillResults, true, nil, start)
+ return checkResultsError(repoResults, skillResults)
+}
+
+func checkResultsError(repos []checkRepoResult, skills []checkSkillResult) error {
+ failed := 0
+ for _, r := range repos {
+ if r.Status == "error" {
+ failed++
+ }
+ }
+ for _, s := range skills {
+ if s.Status == "error" {
+ failed++
+ }
+ }
+ return checkFailureError(failed)
+}
+
+func checkFailureError(failed int) error {
+ if failed > 0 {
+ return fmt.Errorf("%s failed to check", plural(failed, "item"))
+ }
return nil
}
@@ -762,18 +780,16 @@ func formatSourceShort(source string) string {
// renderAgentCheck runs CheckAgents and displays results (text or JSON).
// If groups is non-empty, only agents in those group subdirectories are shown.
-func renderAgentCheck(agentsDir string, groups []string, jsonMode bool) {
+func renderAgentCheck(agentsDir string, groups []string, jsonMode bool) error {
agentResults := check.CheckAgents(agentsDir)
if len(groups) > 0 {
filtered, err := filterAgentResultsByGroups(agentResults, groups, agentsDir)
if err != nil {
if jsonMode {
- writeJSONError(err) //nolint:errcheck
- return
+ return writeJSONError(err)
}
- ui.Error("%v", err)
- return
+ return err
}
agentResults = filtered
}
@@ -799,14 +815,18 @@ func renderAgentCheck(agentsDir string, groups []string, jsonMode bool) {
}
}
+ failed := 0
+ for _, r := range agentResults {
+ if r.Status == "error" {
+ failed++
+ }
+ }
if jsonMode {
- out, _ := json.MarshalIndent(agentResults, "", " ")
- fmt.Println(string(out))
- return
+ return writeJSONResult(agentResults, checkFailureError(failed))
}
if len(agentResults) == 0 {
ui.Done(ui.MarkNone, "No agents found", 0)
- return
+ return nil
}
names := make([]string, len(agentResults))
for i, r := range agentResults {
@@ -844,6 +864,7 @@ func renderAgentCheck(agentsDir string, groups []string, jsonMode bool) {
default:
ui.Done(ui.MarkNone, "No tracked agents to compare", 0)
}
+ return checkFailureError(failed)
}
func printCheckHelp() {
diff --git a/cmd/skillshare/check_test.go b/cmd/skillshare/check_test.go
index da05a6b2f..3ad1720a1 100644
--- a/cmd/skillshare/check_test.go
+++ b/cmd/skillshare/check_test.go
@@ -144,8 +144,10 @@ func TestCheck_ResolvesEveryStatus(t *testing.T) {
runJSON := func(t *testing.T, args ...string) checkOutput {
t.Helper()
output := captureStdoutStderr(t, func() {
- if err := cmdCheck(append([]string{"-g", "--json"}, args...)); err != nil {
- t.Errorf("check: %v", err)
+ err := cmdCheck(append([]string{"-g", "--json"}, args...))
+ wantError := len(args) == 0 || (len(args) == 1 && args[0] == "broken")
+ if (err != nil) != wantError {
+ t.Errorf("check error = %v, want error: %t", err, wantError)
}
})
var result checkOutput
@@ -177,10 +179,17 @@ func TestCheck_ResolvesEveryStatus(t *testing.T) {
}
})
+ t.Run("failed filtered", func(t *testing.T) {
+ result := runJSON(t, "broken")
+ if len(result.Skills) != 1 || result.Skills[0].Status != "error" {
+ t.Fatalf("expected failed skill, got %+v", result.Skills)
+ }
+ })
+
t.Run("text", func(t *testing.T) {
output := captureStdoutStderr(t, func() {
- if err := cmdCheck([]string{"-g"}); err != nil {
- t.Errorf("check: %v", err)
+ if err := cmdCheck([]string{"-g"}); err == nil {
+ t.Error("check must fail when a remote cannot be checked")
}
})
const summary = "Updates available for 2 skills, 3 up to date, 1 local skipped, 1 stale, 1 failed to check"
diff --git a/internal/check/agent_check.go b/internal/check/agent_check.go
index 482a388b3..94fc3c063 100644
--- a/internal/check/agent_check.go
+++ b/internal/check/agent_check.go
@@ -171,6 +171,10 @@ func EnrichAgentResultsWithRemote(results []AgentCheckResult, onDone func()) {
for i, out := range outputs {
ref := refs[i]
if out.Err != nil {
+ for _, idx := range ref.indices {
+ results[idx].Status = "error"
+ results[idx].Message = out.Err.Error()
+ }
continue
}
if out.RemoteHash != "" && out.RemoteHash != ref.version {
diff --git a/internal/check/agent_check_test.go b/internal/check/agent_check_test.go
index 6ddf34c49..aca986882 100644
--- a/internal/check/agent_check_test.go
+++ b/internal/check/agent_check_test.go
@@ -10,6 +10,20 @@ import (
"skillshare/internal/utils"
)
+func TestEnrichAgentResultsWithRemote_Failure(t *testing.T) {
+ missingRepo := filepath.Join(t.TempDir(), "missing.git")
+ results := []AgentCheckResult{
+ {Name: "current", RepoURL: missingRepo, Version: "abc", Status: "up_to_date"},
+ {Name: "edited", RepoURL: missingRepo, Version: "abc", Status: "drifted"},
+ }
+ EnrichAgentResultsWithRemote(results, nil)
+ for _, r := range results {
+ if r.Status != "error" || r.Message == "" {
+ t.Errorf("remote failure must be reported: %+v", r)
+ }
+ }
+}
+
func TestCheckAgents_NoAgents(t *testing.T) {
dir := t.TempDir()
results := CheckAgents(dir)
diff --git a/tests/integration/check_test.go b/tests/integration/check_test.go
index 2d8294b4e..22cc644f9 100644
--- a/tests/integration/check_test.go
+++ b/tests/integration/check_test.go
@@ -268,8 +268,23 @@ func TestCheck_LocalSource_Missing(t *testing.T) {
os.RemoveAll(external)
result := sb.RunCLI("check", "gone-skill")
- result.AssertSuccess(t)
+ result.AssertExitCode(t, 1)
result.AssertAnyOutputContains(t, "local source not found")
+
+ for _, args := range [][]string{{"check", "--json"}, {"check", "gone-skill", "--json"}} {
+ result := sb.RunCLI(args...)
+ result.AssertExitCode(t, 1)
+ if result.Stderr != "" {
+ t.Errorf("JSON failure wrote to stderr: %s", result.Stderr)
+ }
+ var output checkOutput
+ if err := json.Unmarshal([]byte(result.Stdout), &output); err != nil {
+ t.Fatalf("invalid JSON: %v: %s", err, result.Stdout)
+ }
+ if len(output.Skills) != 1 || output.Skills[0].Status != "error" {
+ t.Fatalf("expected failed skill in JSON: %s", result.Stdout)
+ }
+ }
}
// ── Filtered check tests (multi-name + --group) ──────────
diff --git a/ui/src/lib/updateCheckSummary.test.ts b/ui/src/lib/updateCheckSummary.test.ts
new file mode 100644
index 000000000..02d57c78b
--- /dev/null
+++ b/ui/src/lib/updateCheckSummary.test.ts
@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { updateCheckTitle } from './updateCheckSummary';
+
+describe('updateCheckTitle', () => {
+ it.each([
+ [true, true, 0, 'update.check.error'],
+ [true, true, 2, 'update.check.error'],
+ [true, false, 0, 'update.check.error'],
+ [false, false, 0, 'update.tab.notChecked'],
+ [false, true, 2, 'update.hero.available'],
+ [false, true, 0, 'update.hero.allCurrent'],
+ ] as const)('failed=%s checked=%s available=%s', (failed, checked, available, expected) => {
+ expect(updateCheckTitle(failed, checked, available)).toBe(expected);
+ });
+});
diff --git a/ui/src/lib/updateCheckSummary.ts b/ui/src/lib/updateCheckSummary.ts
new file mode 100644
index 000000000..ec2f29c4d
--- /dev/null
+++ b/ui/src/lib/updateCheckSummary.ts
@@ -0,0 +1,5 @@
+export function updateCheckTitle(failed: boolean, checked: boolean, available: number) {
+ if (failed) return 'update.check.error';
+ if (!checked) return 'update.tab.notChecked';
+ return available > 0 ? 'update.hero.available' : 'update.hero.allCurrent';
+}
diff --git a/ui/src/pages/UpdatePage.tsx b/ui/src/pages/UpdatePage.tsx
index d53a77c38..71b1e20ef 100644
--- a/ui/src/pages/UpdatePage.tsx
+++ b/ui/src/pages/UpdatePage.tsx
@@ -20,6 +20,7 @@ import { useToast } from '../components/Toast';
import { useDiffQuery, useSkillsQuery } from '../hooks/useSharedQueries';
import { countChanges, resourceGroups } from '../components/sync/syncView';
import { invalidate } from '../lib/queryEvents';
+import { updateCheckTitle } from '../lib/updateCheckSummary';
import { useInstallFromConfig } from '../hooks/useInstallFromConfig';
/* -- Types ---------------------------------------- */
@@ -529,11 +530,12 @@ export default function UpdatePage({ kind }: { kind: Kind }) {
};
} else {
const summary = lastChecked ? t('update.check.checkedAt', { time: formatRelativeTime(lastChecked, locale) }) : '';
+ const checkFailed = units.some((u) => unitCheck(statuses, u).status === 'error');
hero = {
- icon: ,
- tone: '',
- title: !lastChecked ? t('update.tab.notChecked') : available > 0 ? t('update.hero.available', { count: available }) : t('update.hero.allCurrent'),
- sub: `${summary} ${t('update.tab.audited')}`.trim(),
+ icon: checkFailed ? : ,
+ tone: checkFailed ? 'warn' : '',
+ title: t(updateCheckTitle(checkFailed, !!lastChecked, available), { count: available }),
+ sub: `${checkFailed && available > 0 ? t('update.hero.available', { count: available }) + '. ' : ''}${summary} ${t('update.tab.audited')}`.trim(),
};
}
diff --git a/website/docs/reference/commands/check.md b/website/docs/reference/commands/check.md
index 954f01713..268479c83 100644
--- a/website/docs/reference/commands/check.md
+++ b/website/docs/reference/commands/check.md
@@ -37,6 +37,10 @@ result=$(skillshare check --json)
# Parse JSON to detect outdated skills
```
+## Exit Status
+
+`check` exits with code `1` if any checked item has status `error` (for example, an unreachable remote or a missing local source). Available updates, stale items, and local modifications alone do not cause failure. With `--json`, stdout still contains the complete results; inspect each item's `status` and `message` for details.
+
## What It Does
`check` inspects your source directory and reports update status for:
diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/check.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/check.md
index dddf5b7a0..b4ad37a18 100644
--- a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/check.md
+++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/check.md
@@ -37,6 +37,10 @@ result=$(skillshare check --json)
# JSON をパースして古い Skill を検出する
```
+## 終了ステータス
+
+確認した項目のいずれかが `error` の場合(リモートに接続できない、ローカルのソースが存在しないなど)、`check` はコード `1` で終了します。更新あり、Stale、ローカルの変更だけでは失敗になりません。`--json` 使用時も stdout にすべての結果を出力します。各項目の `status` と `message` を確認してください。
+
## 実行内容
`check` は Source ディレクトリを調べ、以下について更新状況を報告します。
diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/check.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/check.md
index fc47f30a5..8b183e547 100644
--- a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/check.md
+++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/check.md
@@ -37,6 +37,10 @@ result=$(skillshare check --json)
# Parse JSON to detect outdated skills
```
+## 종료 상태
+
+검사한 항목 중 하나라도 상태가 `error`이면(예: 원격 저장소에 연결할 수 없거나 로컬 소스가 없음) `check`는 코드 `1`로 종료합니다. 사용 가능한 업데이트, 오래된 항목, 로컬 수정만으로는 실패하지 않습니다. `--json`을 사용해도 stdout에 전체 결과가 출력됩니다. 각 항목의 `status`와 `message`를 확인하세요.
+
## 동작 내용
`check`는 source 디렉터리를 검사하여 다음 항목의 업데이트 상태를 보고합니다.
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/check.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/check.md
index 2a0c9cb7c..584e08f1a 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/check.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/check.md
@@ -37,6 +37,10 @@ result=$(skillshare check --json)
# 解析 JSON 以检测过时的 skills
```
+## 退出状态
+
+只要任一检查项的状态为 `error`(例如无法连接远程仓库或本地来源不存在),`check` 就会以代码 `1` 退出。仅有可用更新、过时项目或本地修改不会导致失败。使用 `--json` 时,stdout 仍包含完整结果;请查看各项的 `status` 和 `message`。
+
## 它做了什么
`check` 会检查你的 source 目录,并报告以下内容的更新状态:
diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/check.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/check.md
index 9f80253cf..f6067386a 100644
--- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/check.md
+++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/check.md
@@ -37,6 +37,10 @@ result=$(skillshare check --json)
# 解析 JSON 以偵測過期的 skills
```
+## 結束狀態
+
+只要任一受檢項目的狀態為 `error`(例如無法連線遠端或本機來源不存在),`check` 就會以代碼 `1` 結束。僅有可用更新、過期項目或本機修改不會造成失敗。使用 `--json` 時,stdout 仍會包含完整結果;請查看各項目的 `status` 與 `message`。
+
## 執行內容
`check` 會檢查你的 source 目錄,並回報以下項目的更新狀態: