claude-toolkit 0.16.0 → 0.17.0

package/docs/stacks/protobuf-contracts.md

@@ -1,85 +0,0 @@
-# Protobuf Contracts
-
-> Protocol Buffer definitions and code generation for frontend/backend contracts.
-
-**Type:** Stack Skill (requires `protobuf` stack)
-**Source:** [`stacks/protobuf/skills/ct-protobuf-contracts/SKILL.md`](../stacks/protobuf/skills/ct-protobuf-contracts/SKILL.md)
-**Directory Mappings:** `proto/`
-**File Extensions:** `.proto`
-
-## Overview
-
-Protocol Buffers (proto3) define the API contract between frontend and backend. Protobuf provides compact binary serialization, type safety across languages, and backward-compatible schema evolution.
-
-## Proto3 Conventions
-
-- Use **PascalCase** for message names, **snake_case** for field names
-- Fields 1-15 use 1 byte (reserve for frequent fields), 16-2047 use 2 bytes
-- **Never reuse** a field number after removing a field
-- When removing fields, reserve the number AND name
-- Enums must always start with `UNSPECIFIED = 0`
-
-## Message Patterns
-
-### Request/Response Pairs
-```protobuf
-message GetUserRequest { string user_id = 1; }
-message GetUserResponse { UserProfile user = 1; }
-```
-
-### Lists with Pagination
-```protobuf
-message ListEventsRequest {
-  int32 page_size = 1;
-  string page_token = 2;
-}
-message ListEventsResponse {
-  repeated Event events = 1;
-  string next_page_token = 2;
-  int32 total_count = 3;
-}
-```
-
-### Service Definitions
-```protobuf
-service UserService {
-  rpc GetUser(GetUserRequest) returns (GetUserResponse);
-  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
-  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
-}
-```
-
-## Code Generation
-
-| Target | Tool | Command |
-|---|---|---|
-| Frontend (TypeScript) | protoc-gen-ts | `buf generate --template buf.gen.ts.yaml` |
-| Backend (Rust) | prost-build | Via `build.rs` with `prost_build::Config` |
-
-## Buf CLI Commands
-
-| Command | Purpose |
-|---|---|
-| `buf lint` | Lint proto files |
-| `buf format -w` | Format in place |
-| `buf breaking --against .git#branch=main` | Check for breaking changes |
-| `buf generate` | Run code generation |
-
-## Versioning Rules
-
-1. **Never remove or renumber fields** -- use `reserved` instead
-2. **Never change a field type** -- add a new field with the correct type
-3. **Enum values are forever** -- 0 must always be UNSPECIFIED
-4. **Adding fields is safe** -- new fields get default values in old clients
-5. **Run `buf breaking` before merging** -- catch breaking changes in CI
-
-## Anti-patterns
-
-| Anti-pattern | Why it's wrong |
-|---|---|
-| **Reusing field numbers** | Causes data corruption. Always reserve removed field numbers. |
-| **Overly nested messages** | Deep nesting hurts readability and evolution. Flatten where practical. |
-| **Missing UNSPECIFIED enum** | Proto3 requires 0 as default. Without UNSPECIFIED, 0 maps to a real value. |
-| **Using proto2 syntax** | Always use proto3 for new projects. |
-| **Skipping buf lint** | Inconsistent naming compounds over time. |
-| **Large messages** | Protobuf is not designed for multi-MB payloads. Use streaming or chunking. |

package/docs/stacks/rust-wasm-patterns.md

@@ -1,106 +0,0 @@
-# Rust WASM Patterns
-
-> Rust WASM patterns for Cloudflare Workers with worker-rs.
-
-**Type:** Stack Skill (requires `rust-wasm` stack)
-**Source:** [`stacks/rust-wasm/skills/ct-rust-wasm-patterns/SKILL.md`](../stacks/rust-wasm/skills/ct-rust-wasm-patterns/SKILL.md)
-**Directory Mappings:** `worker/`, `worker/src/`
-**File Extensions:** `.rs`, `.toml`
-
-## Overview
-
-Cloudflare Workers can run Rust compiled to WebAssembly via the `worker` crate (worker-rs). The target is `wasm32-unknown-unknown`. Workers handle HTTP requests at the edge with low latency.
-
-## Project Structure
-
-```
-worker/
-  Cargo.toml
-  src/
-    lib.rs          # Entry point with main router
-    routes/
-    models/
-    error.rs        # Custom error types
-  wrangler.toml     # Cloudflare config
-```
-
-## Key Patterns
-
-### Request Routing
-
-```rust
-#[event(fetch)]
-async fn fetch(req: Request, env: Env, _ctx: Context) -> Result<Response> {
-    Router::new()
-        .get_async("/api/users/:id", get_user)
-        .post_async("/api/users", create_user)
-        .run(req, env)
-        .await
-}
-```
-
-### Handler Pattern
-
-```rust
-async fn get_user(req: Request, ctx: RouteContext<()>) -> Result<Response> {
-    let id = ctx.param("id")
-        .ok_or_else(|| Error::RustError("Missing id parameter".into()))?;
-    let db = ctx.env.d1("DB")?;
-    // ...
-}
-```
-
-### Error Handling
-
-Define a custom `AppError` enum that converts to `worker::Error`:
-
-```rust
-pub enum AppError {
-    NotFound(String),
-    BadRequest(String),
-    Internal(String),
-    Unauthorized,
-}
-
-impl From<AppError> for WorkerError { ... }
-```
-
-### Env Bindings
-
-Access Cloudflare services through the `Env` object:
-
-| Binding | Access |
-|---|---|
-| D1 Database | `env.d1("DB")?` |
-| KV Namespace | `env.kv("MY_KV")?` |
-| R2 Bucket | `env.bucket("MY_BUCKET")?` |
-| Secrets | `env.secret("API_KEY")?.to_string()` |
-| Variables | `env.var("CONFIG_VAR")?.to_string()` |
-
-### Serde for JSON
-
-Use `#[derive(Serialize, Deserialize)]` for request/response types. Parse request bodies with `req.json().await?` and respond with `Response::from_json(&data)`.
-
-## Cargo.toml Essentials
-
-```toml
-[lib]
-crate-type = ["cdylib"]
-
-[dependencies]
-worker = "0.5"
-serde = { version = "1", features = ["derive"] }
-serde_json = "1"
-console_error_panic_hook = "0.1"
-```
-
-## Anti-patterns
-
-| Anti-pattern | Why it's wrong |
-|---|---|
-| **Panics in production** | Always use `Result`. `unwrap()` and `expect()` crash the worker. |
-| **Blocking operations** | WASM is single-threaded. All I/O must be `async`. |
-| **Large binary sizes** | Keep dependencies minimal. Target under 1MB compressed. |
-| **Ignoring memory limits** | Workers have 128MB memory. Stream large files, don't buffer. |
-| **Raw SQL string concatenation** | Always use prepared statements with `bind()`. |
-| **Missing CORS headers** | Workers serving APIs must handle OPTIONS preflight requests. |

package/docs/stacks/solidjs-patterns.md

@@ -1,110 +0,0 @@
-# SolidJS Patterns
-
-> SolidJS reactivity, signals, effects, and component patterns.
-
-**Type:** Stack Skill (requires `solidjs` stack)
-**Source:** [`stacks/solidjs/skills/ct-solidjs-patterns/SKILL.md`](../stacks/solidjs/skills/ct-solidjs-patterns/SKILL.md)
-**Directory Mappings:** `src/components/`, `src/hooks/`, `src/pages/`
-**File Extensions:** `.tsx`, `.jsx`
-
-## Overview
-
-SolidJS uses **fine-grained reactivity** with no virtual DOM. Components run once; only the reactive expressions inside them re-execute when dependencies change. This is fundamentally different from React.
-
-## Core Primitives
-
-### createSignal
-```tsx
-const [count, setCount] = createSignal(0);
-// Read: count() -- always call as function
-// Write: setCount(1) or setCount(prev => prev + 1)
-```
-
-### createEffect
-Runs side effects when tracked dependencies change. Automatically tracks any signal read inside it.
-```tsx
-createEffect(() => {
-  console.log("Count changed:", count());
-});
-```
-
-### createMemo
-Derived computation that caches its result. Only recalculates when dependencies change.
-```tsx
-const doubled = createMemo(() => count() * 2);
-```
-
-### createResource
-Async data fetching tied to a signal source. Returns a resource with loading/error states.
-```tsx
-const [data] = createResource(userId, fetchUser);
-// data(), data.loading, data.error
-```
-
-## Component Patterns
-
-| Component | Purpose | Example |
-|---|---|---|
-| `<Show>` | Conditional rendering | `<Show when={isLoggedIn()} fallback={<Login />}>` |
-| `<For>` | List rendering (keyed by reference) | `<For each={items()}>{(item) => ...}</For>` |
-| `<Switch>/<Match>` | Multi-branch conditional | `<Match when={state() === "loading"}>` |
-| `<ErrorBoundary>` | Error catching | `<ErrorBoundary fallback={(err) => ...}>` |
-| `<Suspense>` | Async loading states | `<Suspense fallback={<Loading />}>` |
-
-## Props Handling
-
-**CRITICAL: Never destructure props.** Destructuring breaks reactivity.
-
-```tsx
-// WRONG -- kills reactivity
-const MyComponent = ({ name, count }) => { ... };
-
-// CORRECT -- preserves reactivity
-const MyComponent = (props) => {
-  return <div>{props.name}: {props.count}</div>;
-};
-```
-
-- Use `mergeProps` for defaults: `const merged = mergeProps({ color: "blue" }, props)`
-- Use `splitProps` to separate prop groups: `const [local, others] = splitProps(props, ["class", "style"])`
-
-## Store Patterns
-
-`createStore` provides deep reactivity for complex nested state with path-based updates:
-
-```tsx
-const [state, setState] = createStore({
-  user: { name: "Alice", settings: { theme: "dark" } }
-});
-
-// Granular updates
-setState("user", "settings", "theme", "light");
-```
-
-## Anti-patterns
-
-| Anti-pattern | Why it's wrong |
-|---|---|
-| **Destructuring props** | Breaks reactivity. Always use `props.x`. |
-| **Unnecessary createEffect** | If you just need a derived value, use `createMemo`. |
-| **Treating it like React** | Components do NOT re-run. Only reactive expressions update. |
-| **Array index as key in For** | `<For>` is keyed by reference automatically. |
-| **Reading signals outside reactive context** | Captures the value once at component top level. |
-| **Forgetting to call signals** | `count` is a getter function, `count()` is the value. |
-
-## Best Practices Reference
-
-For deeper guidance on SolidJS patterns (sourced from official docs and Ryan Carniato):
-
-| Topic | Guide |
-|---|---|
-| How fine-grained reactivity works internally | [Reactivity Model](../best-practices/solidjs/reactivity-model.md) |
-| Signal vs memo, derived values, when to use what | [Signals & State](../best-practices/solidjs/signals-and-state.md) |
-| `produce`, `reconcile`, path syntax for nested state | [Stores & Nested State](../best-practices/solidjs/stores-and-nested-state.md) |
-| `mergeProps`, `splitProps`, `children` helper | [Props Patterns](../best-practices/solidjs/props-patterns.md) |
-| When NOT to use effects, `onMount`, `onCleanup` | [Effects & Lifecycle](../best-practices/solidjs/effects-and-lifecycle.md) |
-| `Show`, `For`, `Switch`/`Match`, `Suspense` details | [Control Flow](../best-practices/solidjs/control-flow.md) |
-| `createResource`, `createAsync`, optimistic updates | [Data Fetching](../best-practices/solidjs/data-fetching.md) |
-| Full catalog of common SolidJS mistakes | [Anti-Patterns](../best-practices/solidjs/anti-patterns.md) |
-
-See the full collection: [SolidJS Best Practices](../best-practices/solidjs/README.md)

package/docs/stacks/storybook-patterns.md

@@ -1,177 +0,0 @@
-# Storybook Patterns
-
-> Storybook interaction testing, CSF 3 stories, play functions, a11y, and visual regression for SolidJS components.
-
-**Type:** Stack Skill (requires `storybook` stack)
-**Source:** [`stacks/storybook/skills/ct-storybook-patterns/SKILL.md`](../../stacks/storybook/skills/ct-storybook-patterns/SKILL.md)
-**Directory Mappings:** `.storybook/`, `src/**/*.stories.tsx`
-**File Extensions:** `.stories.tsx`, `.stories.ts`
-
-## Overview
-
-Storybook is the middle layer of the testing pyramid: component interaction testing, visual regression, and accessibility auditing in a real browser.
-
-## SolidJS Integration
-
-Uses community packages: `storybook-solidjs` (renderer) + `storybook-solidjs-vite` (builder).
-
-**Critical:** Always use `createJSXDecorator` for JSX decorators. Standard decorators cause duplicate DOM elements with SolidJS.
-
-```tsx
-import { createJSXDecorator } from "storybook-solidjs";
-
-const ThemeDecorator = createJSXDecorator((Story) => (
-  <ThemeProvider><Story /></ThemeProvider>
-));
-```
-
-## CSF 3 Stories
-
-Use CSF 3 (not CSF Factories -- React-only as of Storybook 10.3).
-
-```tsx
-import type { Meta, StoryObj } from "storybook-solidjs";
-
-const meta = {
-  title: "Components/Button",
-  component: Button,
-  tags: ["autodocs"],
-} satisfies Meta<typeof Button>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Primary: Story = {
-  args: { variant: "primary", children: "Click me" },
-};
-```
-
-### Coverage Checklist
-
-Every component needs stories for: all visual states (default, hover, focus, active, disabled, loading, error, empty), viewport sizes where layout differs, theme variants, edge cases (long text, missing data).
-
-## Interaction Testing
-
-Import everything from `@storybook/test` (instrumented versions). Never import from `@testing-library/dom` directly.
-
-```tsx
-import { expect, fn, userEvent, within } from "@storybook/test";
-
-export const SubmitForm: Story = {
-  args: { onSubmit: fn() },
-  play: async ({ canvasElement, args, step }) => {
-    const canvas = within(canvasElement);
-    await step("Fill form", async () => {
-      await userEvent.type(canvas.getByLabelText("Email"), "user@example.com");
-    });
-    await step("Submit", async () => {
-      await userEvent.click(canvas.getByRole("button", { name: "Sign in" }));
-    });
-    await expect(args.onSubmit).toHaveBeenCalledOnce();
-  },
-};
-```
-
-**Key rules:**
-1. Always `await` expect calls (enables Interactions panel logging).
-2. Use `step()` to organize complex interactions.
-3. Use `fn()` for spying (auto-restored between stories).
-
-## Running in CI (Vitest Addon)
-
-Use `@storybook/addon-vitest` (replaces old test-runner). No running Storybook instance needed.
-
-Required dependencies: `@storybook/addon-vitest`, `@vitest/browser`, `@vitest/browser-playwright`, `@vitest/coverage-v8`.
-
-Add as an inline project in your main Vite config using `test.projects`:
-
-```typescript
-// vite.config.ts
-import { storybookTest } from "@storybook/addon-vitest/vitest-plugin";
-import { playwright } from "@vitest/browser-playwright";
-
-export default defineConfig({
-  plugins: [/* ...app plugins */],
-  test: {
-    projects: [
-      {
-        extends: true,
-        test: { name: "unit", environment: "jsdom", setupFiles: ["./tests/setup.ts"] },
-      },
-      {
-        extends: true,
-        plugins: [storybookTest({ configDir: ".storybook" })],
-        test: {
-          name: "storybook",
-          browser: { enabled: true, headless: true, provider: playwright(), instances: [{ browser: "chromium" }] },
-          setupFiles: [".storybook/vitest.setup.ts"],
-        },
-      },
-    ],
-  },
-});
-```
-
-## Accessibility
-
-Built on axe-core. Set globally in `.storybook/preview.ts`:
-
-```typescript
-export default {
-  parameters: { a11y: { test: "error" } }, // "error" | "todo" | "off"
-  tags: ["a11y-test"],
-};
-```
-
-## MSW for API Components
-
-```typescript
-// .storybook/preview.ts
-import { initialize, mswLoader } from "msw-storybook-addon";
-initialize();
-export default { loaders: [mswLoader] };
-```
-
-Per-story handlers via `parameters.msw.handlers`. Keep success handlers in shared `mocks/handlers.ts`, override with error/edge-case at story level.
-
-## Module Mocking (Storybook 10)
-
-`sb.mock` for internal module replacement. Register in `.storybook/preview.ts` only:
-
-```typescript
-import { sb } from "@storybook/test";
-sb.mock("../src/api/client", () => ({ fetchUser: async () => ({ name: "Mock" }) }));
-```
-
-MSW for network-level; `sb.mock` for internal modules.
-
-## Portable Stories
-
-Reuse stories in Vitest with `composeStories`:
-
-```tsx
-import { composeStories } from "storybook-solidjs";
-import * as stories from "./Button.stories";
-const { Primary } = composeStories(stories);
-
-test("renders primary", () => {
-  const { getByRole } = render(() => <Primary />);
-  expect(getByRole("button")).toBeInTheDocument();
-});
-```
-
-## Anti-Patterns
-
-1. **Destructuring SolidJS props in stories** -- Pass props via `args`; use `createJSXDecorator` for decorators.
-2. **Importing from `@testing-library/dom`** -- Use `@storybook/test` for instrumented versions.
-3. **Not awaiting `expect()` in play functions** -- Always `await expect(...)`.
-4. **Skipping error/edge-case stories** -- Always include loading, error, empty, boundary states.
-5. **Using `@storybook/test-runner`** -- Use `@storybook/addon-vitest` instead.
-6. **Registering `sb.mock` in story files** -- Register in `.storybook/preview.ts` only.
-
-## See Also
-
-- [ct-testing-patterns](../skills/testing-patterns.md) -- Framework-agnostic TDD practices
-- [Storybook Interaction Best Practices](../best-practices/testing/storybook-interaction.md) -- SolidJS-specific Storybook patterns
-- [ct-vite-vitest-patterns](vite-vitest-patterns.md) -- Unit testing layer
-- [ct-playwright-patterns](playwright-patterns.md) -- E2E testing layer

package/docs/stacks/vanilla-extract-patterns.md

@@ -1,115 +0,0 @@
-# Vanilla Extract Patterns
-
-> Type-safe CSS with vanilla-extract, sprinkles, and recipes.
-
-**Type:** Stack Skill (requires `vanilla-extract` stack)
-**Source:** [`stacks/vanilla-extract/skills/ct-vanilla-extract-patterns/SKILL.md`](../stacks/vanilla-extract/skills/ct-vanilla-extract-patterns/SKILL.md)
-**Directory Mappings:** `src/styles/`, `src/theme/`
-**File Extensions:** `.css.ts`
-
-## Overview
-
-vanilla-extract provides zero-runtime, type-safe CSS written in TypeScript. All styles are authored in `*.css.ts` files and extracted to static CSS at build time.
-
-**Important:** All vanilla-extract files MUST use the `*.css.ts` extension. The build plugin only processes these files.
-
-## Core API
-
-### style() -- Single Class Styles
-
-Creates a single scoped class name with type-checked CSS properties.
-
-```ts
-import { style } from '@vanilla-extract/css';
-
-export const button = style({
-  padding: '8px 16px',
-  borderRadius: '4px',
-  ':hover': { opacity: 0.9 },
-});
-```
-
-Compose styles by passing an array:
-
-```ts
-export const primaryButton = style([button, { background: 'blue', color: 'white' }]);
-```
-
-### styleVariants() -- Variant Maps
-
-Creates a map of related style variants from a single definition.
-
-```ts
-export const colorVariant = styleVariants({
-  primary: { background: 'blue', color: 'white' },
-  secondary: { background: 'gray', color: 'black' },
-  danger: { background: 'red', color: 'white' },
-});
-```
-
-### recipe() -- Component Variants
-
-Creates multi-variant styles with `defaultVariants` and compound variants. Requires `@vanilla-extract/recipes`.
-
-```ts
-export const buttonRecipe = recipe({
-  base: { padding: '8px 16px', borderRadius: '4px' },
-  variants: {
-    color: {
-      primary: { background: 'blue', color: 'white' },
-      secondary: { background: 'gray', color: 'black' },
-    },
-    size: {
-      small: { fontSize: '12px' },
-      medium: { fontSize: '14px' },
-      large: { fontSize: '16px' },
-    },
-  },
-  defaultVariants: { color: 'primary', size: 'medium' },
-});
-```
-
-### globalStyle() -- Use Sparingly
-
-For CSS resets, body defaults, or third-party element overrides only.
-
-## Theming
-
-### Contract-first theming (recommended)
-
-```ts
-import { createThemeContract, createTheme } from '@vanilla-extract/css';
-
-export const vars = createThemeContract({
-  color: { brand: null, text: null, background: null },
-  space: { small: null, medium: null, large: null },
-});
-
-export const lightTheme = createTheme(vars, {
-  color: { brand: '#0066ff', text: '#1a1a1a', background: '#ffffff' },
-  space: { small: '4px', medium: '8px', large: '16px' },
-});
-```
-
-Use `vars` for type-safe token references: `style({ color: vars.color.brand })`
-
-### Sprinkles -- Atomic Utility Classes
-
-Requires `@vanilla-extract/sprinkles`. Creates constrained atomic CSS classes with responsive conditions.
-
-## Anti-patterns
-
-| Anti-pattern                  | Why it's wrong                                                   |
-| ----------------------------- | ---------------------------------------------------------------- |
-| **Inline styles**             | Defeats the purpose. Use `style()` or `sprinkles()`.             |
-| **Runtime CSS**               | vanilla-extract is build-time only.                              |
-| **Overusing globalStyle**     | Prefer scoped `style()`. Global styles create implicit coupling. |
-| **Non-`.css.ts` files**       | Style definitions in `.ts` files will not be processed.          |
-| **String-based theme values** | Use the `vars` object for type-safe references.                  |
-
-## Best Practices Reference
-
-| Topic                                     | Guide                                                                        |
-| ----------------------------------------- | ---------------------------------------------------------------------------- |
-| `type` vs `interface` for theme contracts | [Type vs Interface](../best-practices/typescript/type-vs-interface.md)       |
-| `satisfies` for config validation         | [The satisfies Operator](../best-practices/typescript/satisfies-operator.md) |