winter-super-cli 2026.6.21 → 2026.6.23

package/CLAUDE.md

@@ -0,0 +1,118 @@
+# ❄️ WINTER CLAUDE.md
+
+Behavioral guidelines for Winter CLI. These principles should be followed in every interaction.
+
+## The Four Principles
+
+### 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+### 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked
+- No abstractions for single-use code
+- No "flexibility" or "configurability" that wasn't requested
+- No error handling for impossible scenarios
+- If you write 200 lines and it could be 50, rewrite it
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+### 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting
+- Don't refactor things that aren't broken
+- Match existing style, even if you'd do it differently
+- If you notice unrelated dead code, mention it — don't delete it
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused
+- Don't remove pre-existing dead code unless asked
+
+**The test:** Every changed line should trace directly to the user's request.
+
+### 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+## Session Management
+
+### Session Commands
+- `/session new` - Create new session
+- `/session save` - Save current session
+- `/session list` - List sessions
+- `/remember <text>` - Add to memory
+
+### Memory System
+- Working Memory - Current task context
+- Project Memory - Project-specific knowledge
+- Long-term Memory - Cross-project learnings
+
+## AI Provider Integration
+
+### Supported Providers
+- **Anthropic** - claude-3-5-sonnet, claude-3-opus (default)
+- **OpenAI** - gpt-4, gpt-4-turbo, gpt-3.5-turbo
+- **Ollama** - llama3, mistral, codellama (local)
+- **Groq** - llama-3.1-70b, mixtral-8x7b
+
+### Usage
+```bash
+winter chat "Your message" --provider anthropic
+winter call "Analyze this"  # Call all providers
+```
+
+## Skills System
+
+Built-in skills:
+- `coding` - Code analysis, generation, review
+- `design` - Design system integration
+- `debug` - Debugging assistance
+- `refactor` - Code refactoring
+- `test` - Test generation
+
+Custom skills via `winter skill create <name>`.
+
+## Design Integration
+
+Access brand design guidelines from awesome-design-md:
+```bash
+winter design search <brand>
+winter design add <brand>
+winter design preview <brand>
+```
+
+## Key Insight
+
+> "LLMs are exceptionally good at looping until they meet specific goals... Don't tell it what to do, give it success criteria and watch it go."
+
+Transform imperative instructions into declarative goals with verification loops.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

package/design.md

@@ -0,0 +1,66 @@
+# Design Guidance
+
+File này không phải danh bạ trang trí. Đây là checklist bắt buộc khi Winter xử lý UI, brand, landing page, dashboard, hoặc component.
+
+## Resource Status
+- Source: `resources\local\awesome-design-md\README.md`
+- Corpus: `resources\local\awesome-design-md\design-md`
+- Manifest: 142 files, 1.8 MB
+- Status: Corpus local sẵn sàng tại `resources\local\awesome-design-md\design-md`.
+
+## How Winter Must Use This
+1. Khi task liên quan UI/design/brand, tìm brand hoặc style gần nhất trong `awesome-design-md/design-md` trước khi viết code.
+2. Nếu user nêu brand cụ thể, ưu tiên đúng brand đó; nếu không có, chọn brand gần nhất theo domain và nói rõ giả định.
+3. Không tự bịa palette, spacing, typography, tone khi local design guide có dữ liệu phù hợp.
+4. Với app/work tool, ưu tiên layout rõ, dense, dễ scan; không dùng hero marketing nếu user đang cần tool thật.
+5. Sau khi sửa UI, kiểm tra responsive và text overflow nếu có thể chạy app.
+
+## Available Brand Samples (40+)
+- airbnb
+- airtable
+- apple
+- binance
+- bmw
+- bmw-m
+- bugatti
+- cal
+- claude
+- clay
+- clickhouse
+- cohere
+- coinbase
+- composio
+- cursor
+- elevenlabs
+- expo
+- ferrari
+- figma
+- framer
+- hashicorp
+- ibm
+- intercom
+- kraken
+- lamborghini
+- linear.app
+- lovable
+- mastercard
+- meta
+- minimax
+- mintlify
+- miro
+- mistral.ai
+- mongodb
+- nike
+- notion
+- nvidia
+- ollama
+- opencode.ai
+- pinterest
+
+## Useful Commands
+- `/designs` để liệt kê hoặc tìm design systems.
+- `/read resources/local/awesome-design-md/README.md` để đọc overview.
+- `/grep <brand> resources/local/awesome-design-md/design-md` để tìm brand/style guide.
+
+---
+*File này được tự động tạo bởi Winter CLI.*

package/docs/architecture.md

@@ -0,0 +1,133 @@
+# Architecture
+
+This document gives a high-level map of Winter for contributors and GitHub readers.
+
+## Runtime Flow
+
+```text
+bin/winter.js
+  -> CLI / REPL
+  -> AIProviderManager
+  -> provider adapter
+  -> tool executor / provider HTTP call
+  -> normalized response or stream chunks
+```
+
+## Major Areas
+
+### `src/ai/`
+
+AI orchestration lives here.
+
+Important files:
+
+- `providers.js` — provider manager, routing, request execution, streaming, tool-chat loop
+- `provider-adapters.js` — universal provider request/response/stream adapters
+- `model-capabilities.js` — model tier and capability classification
+- `reasoning.js` — reasoning level and complexity helpers
+- `prompts/` — system prompts, task classification, success criteria
+
+### `src/cli/`
+
+Interactive terminal experience.
+
+Important files:
+
+- `repl.js` — interactive REPL loop
+- `slash-commands.js` — command registry
+- `config.js` — config loading and redaction helpers
+- `terminal-ui.js` — terminal rendering helpers
+
+### `src/tools/`
+
+Tool execution surface.
+
+Examples:
+
+- file reading/writing/editing
+- shell command execution
+- glob/grep search
+- browser debugging
+- web fetch/search/archive
+- notebook editing
+- scheduler and task tools
+- sub-agent execution
+
+### `src/context/`
+
+Context assembly and routing.
+
+Examples:
+
+- selecting execution profile
+- loading relevant local resources
+- compressing conversation history
+
+### `resources/local/`
+
+Bundled local resources used to improve AI behavior and documentation quality.
+
+Examples:
+
+- Karpathy coding principles
+- agent workflow references
+- page-agent docs
+- design system corpus
+- embedded context corpus
+
+## Provider Abstraction Boundary
+
+`AIProviderManager` does not hand-build every native provider request. It delegates to:
+
+- `buildProviderRequest()`
+- `normalizeProviderResponse()`
+- `normalizeProviderStreamChunk()`
+- `getProviderPreset()`
+
+This keeps provider-specific details out of the main manager.
+
+See [Provider Abstraction](provider-abstraction.md) for details.
+
+## Testing
+
+Winter uses Node's built-in test runner.
+
+```bash
+npm test
+```
+
+For provider work, start with:
+
+```bash
+node --test src/ai/providers.test.js
+```
+
+For syntax-only verification:
+
+```bash
+node --check src/ai/providers.js
+node --check src/ai/provider-adapters.js
+```
+
+## Contribution Guidelines
+
+Keep changes small and verifiable:
+
+1. inspect the runtime path before editing
+2. make the narrowest change that solves the issue
+3. add or update tests close to the changed behavior
+4. run the nearest verification command
+5. avoid dependency changes unless required
+
+## Release Checklist
+
+Before publishing or pushing a release branch:
+
+```bash
+npm test
+npm run prepublish:gate
+npm run pack:audit
+npm run smoke:package
+```
+
+If a command is platform-specific or unavailable, document the reason in the PR or release notes.

package/docs/provider-abstraction.md

@@ -0,0 +1,208 @@
+# Provider Abstraction
+
+Winter routes every model call through a small provider adapter layer in `src/ai/provider-adapters.js`.
+
+The goal is simple: the rest of Winter can speak one internal message shape while each provider gets the request format it expects.
+
+## Supported API Formats
+
+| `apiFormat` | Request style | Typical providers |
+|---|---|---|
+| `openai` | OpenAI-compatible `/chat/completions` | OpenAI, Groq, Ollama, Qwen DashScope, Kimi/Moonshot, MiniMax, OpenRouter, DeepSeek, Mistral, Fireworks, Together, SiliconFlow |
+| `anthropic` | Anthropic native `/messages` | Anthropic Claude or compatible native endpoints |
+| `gemini` | Gemini native `models/{model}:generateContent` | Google Gemini or compatible native endpoints |
+
+## Preset Providers
+
+Winter ships with presets for common providers. A preset can provide:
+
+- display name
+- API format
+- base URL
+- default model
+
+Current presets include:
+
+- `openai`
+- `azure`
+- `groq`
+- `ollama`
+- `openrouter`
+- `together`
+- `fireworks`
+- `deepseek`
+- `mistral`
+- `xai`
+- `perplexity`
+- `cerebras`
+- `siliconflow`
+- `zhipu`
+- `baichuan`
+- `01ai`
+- `qwen`
+- `dashscope`
+- `kimi`
+- `moonshot`
+- `minimax`
+- `anthropic`
+- `claude`
+- `gemini`
+
+## Custom Provider
+
+`custom` is the escape hatch for any provider or gateway.
+
+By default, `custom` is OpenAI-compatible:
+
+```json
+{
+  "defaultProvider": "custom",
+  "custom": {
+    "baseURL": "http://localhost:4000/v1",
+    "apiKey": "your-key",
+    "model": "gpt-4o-mini"
+  }
+}
+```
+
+You can switch it to Anthropic native:
+
+```json
+{
+  "defaultProvider": "custom",
+  "custom": {
+    "apiFormat": "anthropic",
+    "apiKey": "your-key",
+    "model": "claude-3-5-sonnet-latest"
+  }
+}
+```
+
+You can switch it to Gemini native:
+
+```json
+{
+  "defaultProvider": "custom",
+  "custom": {
+    "apiFormat": "gemini",
+    "apiKey": "your-key",
+    "model": "gemini-1.5-pro"
+  }
+}
+```
+
+## Named Provider Sections
+
+Any non-reserved config section can become a provider if it has provider-like fields or a known preset.
+
+Example:
+
+```json
+{
+  "defaultProvider": "qwen",
+  "qwen": {
+    "apiKey": "dashscope-key"
+  },
+  "kimi": {
+    "apiKey": "moonshot-key"
+  },
+  "minimax": {
+    "apiKey": "minimax-key"
+  }
+}
+```
+
+Because these names have presets, Winter can fill in the base URL and default model automatically.
+
+## How Requests Are Built
+
+Internal call sites pass:
+
+- provider config
+- OpenAI-style messages
+- options such as model, stream, tools, and reasoning
+
+The adapter returns:
+
+```js
+{
+  url,
+  headers,
+  body
+}
+```
+
+Then `AIProviderManager` performs the fetch.
+
+## Response Normalization
+
+Provider responses are normalized back toward an OpenAI-style shape:
+
+```js
+{
+  choices: [
+    {
+      message: {
+        role: 'assistant',
+        content: '...'
+      },
+      finish_reason: '...'
+    }
+  ],
+  usage,
+  raw
+}
+```
+
+This keeps the rest of the CLI independent from each provider's native response format.
+
+## Streaming
+
+Streaming chunks are normalized with `normalizeProviderStreamChunk()`.
+
+The normalized stream chunk shape is:
+
+```js
+{
+  content,
+  usage,
+  raw
+}
+```
+
+OpenAI-compatible, Anthropic native, and Gemini native chunks are handled separately.
+
+## Tool Calling Notes
+
+Winter can include tool definitions in provider requests. The adapter converts tool schema where needed:
+
+- OpenAI-compatible: passes tools through
+- Anthropic: converts to `input_schema`
+- Gemini: converts to `functionDeclarations`
+
+Provider-native tool response semantics can still vary. When integrating a new native provider, test both simple chat and tool-call loops.
+
+## Adding a New Provider Preset
+
+Edit `PROVIDER_PRESETS` in `src/ai/provider-adapters.js`:
+
+```js
+export const PROVIDER_PRESETS = {
+  myprovider: {
+    name: 'My Provider',
+    apiFormat: 'openai',
+    baseURL: 'https://api.myprovider.example/v1',
+    model: 'my-default-model'
+  }
+};
+```
+
+Then add or update tests near `src/ai/providers.test.js`.
+
+Recommended test cases:
+
+1. provider config without `baseURL` resolves the preset URL
+2. request URL is correct
+3. auth headers are correct
+4. response is normalized
+5. streaming chunks are normalized if the provider supports streaming

package/extensions/vscode/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "winter-cli-vscode",
+  "displayName": "Winter CLI",
+  "description": "❄️ Winter AI CLI integration for VS Code — code with AI inline in your editor",
+  "version": "0.1.0",
+  "publisher": "winter-cli",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/user/winter"
+  },
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "categories": [
+    "Programming Languages",
+    "Machine Learning",
+    "Other"
+  ],
+  "keywords": [
+    "ai",
+    "coding",
+    "winter",
+    "cli",
+    "assistant"
+  ],
+  "activationEvents": [
+    "onStartupFinished"
+  ],
+  "main": "./src/extension.js",
+  "contributes": {
+    "commands": [
+      {
+        "command": "winter.startChat",
+        "title": "Winter: Start AI Chat"
+      },
+      {
+        "command": "winter.inlineCompletion",
+        "title": "Winter: Trigger Inline Completion"
+      },
+      {
+        "command": "winter.explainCode",
+        "title": "Winter: Explain Selected Code"
+      },
+      {
+        "command": "winter.refactorCode",
+        "title": "Winter: Refactor Selected Code"
+      },
+      {
+        "command": "winter.fixCode",
+        "title": "Winter: Fix Selected Code"
+      },
+      {
+        "command": "winter.generateTests",
+        "title": "Winter: Generate Tests for File"
+      },
+      {
+        "command": "winter.openTerminal",
+        "title": "Winter: Open CLI Terminal"
+      },
+      {
+        "command": "winter.codeReview",
+        "title": "Winter: Review Current File"
+      }
+    ],
+    "keybindings": [
+      {
+        "command": "winter.inlineCompletion",
+        "key": "ctrl+shift+space",
+        "when": "editorTextFocus"
+      },
+      {
+        "command": "winter.startChat",
+        "key": "ctrl+shift+i",
+        "when": "editorTextFocus"
+      }
+    ],
+    "menus": {
+      "editor/context": [
+        {
+          "command": "winter.explainCode",
+          "group": "winter@1",
+          "when": "editorHasSelection"
+        },
+        {
+          "command": "winter.refactorCode",
+          "group": "winter@2",
+          "when": "editorHasSelection"
+        },
+        {
+          "command": "winter.fixCode",
+          "group": "winter@3",
+          "when": "editorHasSelection"
+        }
+      ],
+      "explorer/context": [
+        {
+          "command": "winter.generateTests",
+          "group": "winter@1"
+        }
+      ]
+    }
+  },
+  "scripts": {
+    "vscode:prepublish": "npm run build",
+    "build": "echo 'No build step required'",
+    "lint": "echo 'No linter configured'"
+  },
+  "devDependencies": {
+    "@types/vscode": "^1.85.0"
+  }
+}