diff --git a/docs/codebase-summary.md b/docs/codebase-summary.md index 37049183..2f35dd80 100644 --- a/docs/codebase-summary.md +++ b/docs/codebase-summary.md @@ -1,8 +1,8 @@ # CCS Codebase Summary -Last Updated: 2026-03-18 +Last Updated: 2026-03-24 -Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure), v7.1 Remote CLIProxy feature, v7.2 Kiro + GitHub Copilot (ghcp) OAuth providers, v7.14 Hybrid Quota Management, v7.34 Image Analysis Hook, and account-context validation hardening. +Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure), v7.1 Remote CLIProxy feature, v7.2 Kiro + GitHub Copilot (ghcp) OAuth providers, v7.14 Hybrid Quota Management, v7.34 Image Analysis Hook, account-context validation hardening, and Official Claude Channels runtime support. ## Repository Structure @@ -84,6 +84,10 @@ src/ │ ├── unified-config-loader.ts # Central config loader (546 lines) │ └── migration-manager.ts # Config migration logic │ +├── channels/ # Official Claude channel integration +│ ├── official-channels-runtime.ts # Runtime gating, plugin specs, setup guidance +│ └── official-channels-store.ts # Claude channel token/env storage helpers +│ ├── cliproxy/ # CLIProxyAPI integration (heavily modularized) │ ├── index.ts # Barrel export (137 lines, extensive) │ ├── auth/ # OAuth handlers, token management @@ -174,6 +178,7 @@ src/ │ ├── index.ts │ ├── accounts-route.ts │ ├── auth-route.ts + │ ├── channels-routes.ts │ ├── cliproxy-route.ts │ ├── copilot-route.ts │ ├── doctor-route.ts @@ -229,6 +234,15 @@ src/ - `plugins/marketplaces/`, `plugins/cache/`, and `installed_plugins.json` stay shared through the `~/.ccs/shared/` topology. - `known_marketplaces.json` is now instance-local under `~/.ccs/instances//plugins/` so Claude Code validates `installLocation` against the active `CLAUDE_CONFIG_DIR` instead of a last-writer-wins shared file. +### Official Claude Channels + +- Runtime contract lives in `src/channels/official-channels-runtime.ts` and is consumed from `src/ccs.ts`, `src/commands/config-channels-command.ts`, and `src/web-server/routes/channels-routes.ts`. +- Canonical config lives under `channels.*` in `~/.ccs/config.yaml`; legacy `discord_channels.*` remains read-compatible only when canonical fields are absent. +- Telegram and Discord bot tokens are intentionally written into Claude-managed machine state under `~/.claude/channels//.env`, unless the official `*_STATE_DIR` environment override redirects that channel elsewhere. +- iMessage is tokenless, macOS-only, and still depends on Claude-side plugin install plus OS permissions. +- Auto-enable is gated on Bun availability, verified Claude Code v2.1.80+, verified `claude.ai` auth, native Claude `default/account` sessions, and per-channel setup readiness. +- The dashboard channels section surfaces Bun/version/auth/state-scope status from `/api/channels`, preserves token drafts when save-follow-up refresh fails, and keeps unsupported selected iMessage visible only so it can be turned off. + ### Target Adapter Module The targets module provides an extensible interface for dispatching profiles to different CLI implementations. @@ -420,6 +434,7 @@ ui/src/ │ │ ├── hooks/ │ │ │ ├── index.ts │ │ │ ├── context-hooks.ts +│ │ │ ├── use-official-channels-config.ts │ │ │ ├── use-settings-tab.ts │ │ │ ├── use-proxy-config.ts │ │ │ ├── use-websearch-config.ts @@ -429,6 +444,7 @@ ui/src/ │ │ │ ├── section-skeleton.tsx │ │ │ └── tab-navigation.tsx │ │ └── sections/ +│ │ ├── channels.tsx │ │ ├── globalenv-section.tsx │ │ ├── websearch/ │ │ │ ├── index.tsx diff --git a/docs/project-overview-pdr.md b/docs/project-overview-pdr.md index 9f698758..744de589 100644 --- a/docs/project-overview-pdr.md +++ b/docs/project-overview-pdr.md @@ -1,6 +1,6 @@ # CCS Product Development Requirements (PDR) -Last Updated: 2026-03-19 +Last Updated: 2026-03-24 ## Product Overview @@ -8,7 +8,7 @@ Last Updated: 2026-03-19 **Tagline**: The universal AI profile manager for Claude Code -**Description**: CLI wrapper enabling seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex, OpenRouter, Qwen, Kimi, DeepSeek) with a React-based dashboard for configuration management. Supports both local and remote CLIProxyAPI instances with hybrid quota management. +**Description**: CLI wrapper enabling seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex, OpenRouter, Qwen, Kimi, DeepSeek) with a React-based dashboard for configuration management. Supports both local and remote CLIProxyAPI instances, hybrid quota management, and official Claude channel runtime setup for Telegram, Discord, and iMessage. **Current Version**: v7.34.x (Image Analysis Hook + Performance Improvements) @@ -37,6 +37,7 @@ CCS provides: 5. **Visual Dashboard**: React SPA for configuration management 6. **Automatic WebSearch**: Real backend fallback chain for third-party providers 7. **Usage Analytics**: Token tracking, cost analysis, model breakdown +8. **Official Claude Channels**: Runtime auto-enable plus dashboard token/config flow for Telegram, Discord, and macOS-only iMessage --- @@ -129,6 +130,16 @@ CCS provides: - Security: single-quoted output, key sanitization, shell-specific escaping - Cross-platform compatibility (macOS, Linux, Windows) +### FR-012: Official Claude Channels +- Support Telegram, Discord, and iMessage selection via `ccs config channels` and the dashboard +- Auto-inject `--channels` only for native Claude `default` and `account` sessions +- Store Telegram/Discord bot tokens in Claude's own `~/.claude/channels//.env` state or the official `*_STATE_DIR` override path when one is configured +- Treat iMessage as macOS-only, tokenless, and dependent on Claude-side install plus OS permissions +- Require Bun, Claude Code v2.1.80+, and verified `claude.ai` auth before runtime auto-enable +- Keep `--dangerously-skip-permissions` optional and never add it when the user already made an explicit permission choice +- Surface platform/auth/version/setup blockers clearly in both CLI and dashboard flows +- Preserve dashboard token drafts when save/refresh fails, and let already-selected unsupported iMessage entries be turned off without allowing re-enable on unsupported platforms + --- ## Non-Functional Requirements @@ -172,11 +183,13 @@ CCS provides: - CLIProxyAPI binary (auto-managed) - Exa/Tavily/Brave API keys for higher-quality WebSearch - Gemini CLI for legacy WebSearch fallback +- Bun plus Claude Code v2.1.80+ with `claude.ai` auth for Official Channels auto-enable ### TR-003: Configuration - YAML-based config (`~/.ccs/config.yaml`) - JSON settings per profile - Environment variable overrides +- Official channel bot tokens stored in Claude-managed `~/.claude/channels//.env` --- diff --git a/docs/project-roadmap.md b/docs/project-roadmap.md index e93db791..47e4433a 100644 --- a/docs/project-roadmap.md +++ b/docs/project-roadmap.md @@ -1,6 +1,6 @@ # CCS Project Roadmap -Last Updated: 2026-03-23 +Last Updated: 2026-03-24 Forward-looking roadmap documenting current priorities, GitHub issues, and future feature plans. @@ -41,6 +41,7 @@ All major modularization work is complete. The codebase evolved from monolithic ### Recent Fixes +- **2026-03-24**: Official Claude Channels now follow Anthropic's actual runtime contract. CCS blocks auto-enable unless Bun is available, Claude Code is verified at v2.1.80+, and `claude.ai` auth is verified; treats `--allow-dangerously-skip-permissions` as an explicit override; keeps Telegram/Discord bot tokens in Claude's shared `~/.claude/channels/` state (or official `*_STATE_DIR` overrides); and upgrades the dashboard/CLI status flow with Bun/version/auth/state-scope guidance, safer token draft retention on refresh failures, and a non-macOS iMessage toggle that can still be turned off when already selected. - **2026-03-23**: CLIProxy providers that do not expose an email no longer require a user-supplied nickname on first auth. CCS now derives a stable internal account identifier for Kiro/Copilot-style flows, preserves later rename support, hardens account discovery/registry sync around that identifier, and updates AI Provider CRUD to use stable entry IDs instead of dashboard list indexes. - **2026-03-23**: Sensitive dashboard management routes now fail closed to localhost-only access whenever dashboard auth is disabled. Remote access remains available after `ccs config auth setup`, but AI Provider management, CLIProxy auth/status helpers, and other write-capable settings endpoints no longer trust unauthenticated non-loopback requests. - **2026-03-19**: **#649** CCS splits CLIProxy provider-key authoring into a dedicated `CLIProxy -> AI Providers` dashboard route. `/cliproxy` now stays focused on OAuth accounts and variants, `/cliproxy/ai-providers` owns Gemini/Codex/Claude/Vertex/OpenAI-compatible key management, and `/providers` stays reserved for CCS-native API Profiles.