feat(scripts): macOS/Linux port — doctor.sh + maintain.sh

[abdout]

Summary

macOS/Linux port of the two most-used commands. Same architecture as the PowerShell versions, translated to bash idioms. Closes the "macOS/Linux equivalents follow-up" item from spec #28.

# Audit health
bash ~/.claude/scripts/doctor.sh

# Arm daily heartbeat
bash ~/.claude/scripts/maintain.sh --install

What's in the PR

• ~/.claude/scripts/doctor.sh (340 lines) — single-file bash equivalent of doctor.ps1
• ~/.claude/scripts/maintain.sh (180 lines) — launchd-based daily heartbeat
• ~/.claude/scripts/health.sh — demoted to a 1-line back-compat shim → doctor.sh
• ~/.claude/scripts/install.sh — fixed $PROFILE bug + recursive lib/ copy

Cross-platform parity

Concern	Windows (doctor.ps1)	macOS/Linux (doctor.sh)
Check categories	7 (Core, Shell, Identity, Repos, Updates, Scheduled, IDE)	Identical
Exit codes	0/1/2/3 (errors > warnings > updates)	Identical
Flags	-Report -Fix -Update -Json -Quiet -Deep	--report --fix --update --json --quiet --deep
Shell rc	$PROFILE.CurrentUserAllHosts	~/.zshrc or ~/.bashrc (auto-detect)
Scheduled task	schtasks / Get-ScheduledTask	launchctl + ~/Library/LaunchAgents/com.databayt.kun-maintain.plist
Toast	BurntToast PowerShell module	osascript -e 'display notification'
WebStorm config	%APPDATA%\JetBrains\WebStorm*	~/Library/Application Support/JetBrains/WebStorm*
Update check	Invoke-RestMethod + Compare-Semver	curl + bash semver function
repositories.json	Reads via PowerShell $ExecutionContext.InvokeCommand.ExpandString	Reads via embedded Python json (already a soft dep)

install.sh fixes (matching the install.ps1 fix from #32)

Before (the existing bug):

if ! grep -q "claude" "$SHELL_RC" 2>/dev/null; then
    echo "" >> "$SHELL_RC"
    echo "# Claude Code (Kun Engine)" >> "$SHELL_RC"
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$SHELL_RC"
fi

The shell rc got export PATH=$HOME/.local/bin:$PATH (wrong path — .local/bin not .claude/bin) and no c/cc aliases.

After:

alias c='claude --dangerously-skip-permissions'
alias cc='claude'
if [ -f "$HOME/.claude/.env" ]; then
    set -a; . "$HOME/.claude/.env"; set +a
fi
export PATH="$HOME/.claude/bin:$PATH"

install.sh and doctor.sh --fix now produce identical shell rc output.

Verified locally

Both scripts smoke-tested under Git Bash on Windows (which uses the same bash interpreter):

• bash -n syntax-check: all 4 files clean
• doctor.sh --quiet: all 7 check categories render correctly, exit code matches state (1 errors on this machine)
• doctor.sh correctly detected claude CLI 2.1.140 → 2.1.143 update via the GitHub releases API
• maintain.sh --status correctly reports "not loaded"
• maintain.sh --run --dry-run walks the 5-step flow and writes the log
• health.sh --quiet correctly forwards to doctor.sh

Test plan (needs a Mac)

• bash ~/.claude/scripts/doctor.sh runs cleanly on macOS 14+
• bash maintain.sh --install writes plist and launchctl list | grep com.databayt.kun-maintain shows it
• Re-running --install doesn't duplicate
• maintain.sh --uninstall removes plist and unloads — idempotent
• Scheduled task fires at the configured hour, runs doctor --quiet, notifies via osascript when non-green
• Slack notification via SLACK_WEBHOOK_URL in ~/.claude/.env
• doctor --fix correctly identifies and writes to ~/.zshrc (most Macs default to zsh)

Linux compatibility

The scripts auto-detect ~/.bashrc when ~/.zshrc is absent, and use find -mtime and other POSIX-compatible flags. WebStorm/launchd checks degrade gracefully on Linux (just show "paused" / "not installed"). No hard macOS-only dependencies.

Dependencies

Stacks on feat/polish (PR #32). Merge order:

#29 → #30 → #31 → #32 → this PR

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
kun	Building	Preview	May 16, 2026 4:14pm