@macpaw/cctk 1.0.0-beta.1

package/templates/claude/skills/frontend-development/resources/typescript-standards.md

@@ -0,0 +1,418 @@
+# TypeScript Standards
+
+TypeScript best practices for type safety and maintainability in React frontend code.
+
+---
+
+## Strict Mode
+
+### Configuration
+
+TypeScript strict mode is **enabled** in the project:
+
+```json
+// tsconfig.json
+{
+    "compilerOptions": {
+        "strict": true,
+        "noImplicitAny": true,
+        "strictNullChecks": true
+    }
+}
+```
+
+**This means:**
+- No implicit `any` types
+- Null/undefined must be handled explicitly
+- Type safety enforced
+
+---
+
+## No `any` Type
+
+### The Rule
+
+```typescript
+// ❌ NEVER use any
+function handleData(data: any) {
+    return data.something;
+}
+
+// ✅ Use specific types
+interface MyData {
+    something: string;
+}
+
+function handleData(data: MyData) {
+    return data.something;
+}
+
+// ✅ Or use unknown for truly unknown data
+function handleUnknown(data: unknown) {
+    if (typeof data === 'object' && data !== null && 'something' in data) {
+        return (data as MyData).something;
+    }
+}
+```
+
+**If you truly don't know the type:**
+- Use `unknown` (forces type checking)
+- Use type guards to narrow
+- Document why type is unknown
+
+---
+
+## Explicit Return Types
+
+### Function Return Types
+
+```typescript
+// ✅ CORRECT - Explicit return type
+function getUser(id: number): Promise<User> {
+    return apiClient.get(`/users/${id}`);
+}
+
+function calculateTotal(items: Item[]): number {
+    return items.reduce((sum, item) => sum + item.price, 0);
+}
+
+// ❌ AVOID - Implicit return type (less clear)
+function getUser(id: number) {
+    return apiClient.get(`/users/${id}`);
+}
+```
+
+### Component Return Types
+
+```typescript
+// React.FC already provides return type (ReactElement)
+export const MyComponent: React.FC<Props> = ({ prop }) => {
+    return <div>{prop}</div>;
+};
+
+// For custom hooks
+function useMyData(id: number): { data: Data; isLoading: boolean } {
+    const [data, setData] = useState<Data | null>(null);
+    const [isLoading, setIsLoading] = useState(true);
+
+    return { data: data!, isLoading };
+}
+```
+
+---
+
+## Type Imports
+
+### Use 'type' Keyword
+
+```typescript
+// ✅ CORRECT - Explicitly mark as type import
+import type { User } from '~types/user';
+import type { Post } from '~types/post';
+import type { SxProps, Theme } from '@mui/material';
+
+// ❌ AVOID - Mixed value and type imports
+import { User } from '~types/user';  // Unclear if type or value
+```
+
+**Benefits:**
+- Clearly separates types from values
+- Better tree-shaking
+- Prevents circular dependencies
+- TypeScript compiler optimization
+
+---
+
+## Component Prop Interfaces
+
+### Interface Pattern
+
+```typescript
+/**
+ * Props for MyComponent
+ */
+interface MyComponentProps {
+    /** The user ID to display */
+    userId: number;
+
+    /** Optional callback when action completes */
+    onComplete?: () => void;
+
+    /** Display mode for the component */
+    mode?: 'view' | 'edit';
+
+    /** Additional CSS classes */
+    className?: string;
+}
+
+export const MyComponent: React.FC<MyComponentProps> = ({
+    userId,
+    onComplete,
+    mode = 'view',  // Default value
+    className,
+}) => {
+    return <div>...</div>;
+};
+```
+
+**Key Points:**
+- Separate interface for props
+- JSDoc comments for each prop
+- Optional props use `?`
+- Provide defaults in destructuring
+
+### Props with Children
+
+```typescript
+interface ContainerProps {
+    children: React.ReactNode;
+    title: string;
+}
+
+// React.FC automatically includes children type, but be explicit
+export const Container: React.FC<ContainerProps> = ({ children, title }) => {
+    return (
+        <div>
+            <h2>{title}</h2>
+            {children}
+        </div>
+    );
+};
+```
+
+---
+
+## Utility Types
+
+### Partial<T>
+
+```typescript
+// Make all properties optional
+type UserUpdate = Partial<User>;
+
+function updateUser(id: number, updates: Partial<User>) {
+    // updates can have any subset of User properties
+}
+```
+
+### Pick<T, K>
+
+```typescript
+// Select specific properties
+type UserPreview = Pick<User, 'id' | 'name' | 'email'>;
+
+const preview: UserPreview = {
+    id: 1,
+    name: 'John',
+    email: 'john@example.com',
+    // Other User properties not allowed
+};
+```
+
+### Omit<T, K>
+
+```typescript
+// Exclude specific properties
+type UserWithoutPassword = Omit<User, 'password' | 'passwordHash'>;
+
+const publicUser: UserWithoutPassword = {
+    id: 1,
+    name: 'John',
+    email: 'john@example.com',
+    // password and passwordHash not allowed
+};
+```
+
+### Required<T>
+
+```typescript
+// Make all properties required
+type RequiredConfig = Required<Config>;  // All optional props become required
+```
+
+### Record<K, V>
+
+```typescript
+// Type-safe object/map
+const userMap: Record<string, User> = {
+    'user1': { id: 1, name: 'John' },
+    'user2': { id: 2, name: 'Jane' },
+};
+
+// For styles
+import type { SxProps, Theme } from '@mui/material';
+
+const styles: Record<string, SxProps<Theme>> = {
+    container: { p: 2 },
+    header: { mb: 1 },
+};
+```
+
+---
+
+## Type Guards
+
+### Basic Type Guards
+
+```typescript
+function isUser(data: unknown): data is User {
+    return (
+        typeof data === 'object' &&
+        data !== null &&
+        'id' in data &&
+        'name' in data
+    );
+}
+
+// Usage
+if (isUser(response)) {
+    console.log(response.name);  // TypeScript knows it's User
+}
+```
+
+### Discriminated Unions
+
+```typescript
+type LoadingState =
+    | { status: 'idle' }
+    | { status: 'loading' }
+    | { status: 'success'; data: Data }
+    | { status: 'error'; error: Error };
+
+function Component({ state }: { state: LoadingState }) {
+    // TypeScript narrows type based on status
+    if (state.status === 'success') {
+        return <Display data={state.data} />;  // data available here
+    }
+
+    if (state.status === 'error') {
+        return <Error error={state.error} />;  // error available here
+    }
+
+    return <Loading />;
+}
+```
+
+---
+
+## Generic Types
+
+### Generic Functions
+
+```typescript
+function getById<T>(items: T[], id: number): T | undefined {
+    return items.find(item => (item as any).id === id);
+}
+
+// Usage with type inference
+const users: User[] = [...];
+const user = getById(users, 123);  // Type: User | undefined
+```
+
+### Generic Components
+
+```typescript
+interface ListProps<T> {
+    items: T[];
+    renderItem: (item: T) => React.ReactNode;
+}
+
+export function List<T>({ items, renderItem }: ListProps<T>): React.ReactElement {
+    return (
+        <div>
+            {items.map((item, index) => (
+                <div key={index}>{renderItem(item)}</div>
+            ))}
+        </div>
+    );
+}
+
+// Usage
+<List<User>
+    items={users}
+    renderItem={(user) => <UserCard user={user} />}
+/>
+```
+
+---
+
+## Type Assertions (Use Sparingly)
+
+### When to Use
+
+```typescript
+// ✅ OK - When you know more than TypeScript
+const element = document.getElementById('my-element') as HTMLInputElement;
+const value = element.value;
+
+// ✅ OK - API response that you've validated
+const response = await api.getData();
+const user = response.data as User;  // You know the shape
+```
+
+### When NOT to Use
+
+```typescript
+// ❌ AVOID - Circumventing type safety
+const data = getData() as any;  // WRONG - defeats TypeScript
+
+// ❌ AVOID - Unsafe assertion
+const value = unknownValue as string;  // Might not actually be string
+```
+
+---
+
+## Null/Undefined Handling
+
+### Optional Chaining
+
+```typescript
+// ✅ CORRECT
+const name = user?.profile?.name;
+
+// Equivalent to:
+const name = user && user.profile && user.profile.name;
+```
+
+### Nullish Coalescing
+
+```typescript
+// ✅ CORRECT
+const displayName = user?.name ?? 'Anonymous';
+
+// Only uses default if null or undefined
+// (Different from || which triggers on '', 0, false)
+```
+
+### Non-Null Assertion (Use Carefully)
+
+```typescript
+// ✅ OK - When you're certain value exists
+const data = queryClient.getQueryData<Data>(['data'])!;
+
+// ⚠️ CAREFUL - Only use when you KNOW it's not null
+// Better to check explicitly:
+const data = queryClient.getQueryData<Data>(['data']);
+if (data) {
+    // Use data
+}
+```
+
+---
+
+## Summary
+
+**TypeScript Checklist:**
+- ✅ Strict mode enabled
+- ✅ No `any` type (use `unknown` if needed)
+- ✅ Explicit return types on functions
+- ✅ Use `import type` for type imports
+- ✅ JSDoc comments on prop interfaces
+- ✅ Utility types (Partial, Pick, Omit, Required, Record)
+- ✅ Type guards for narrowing
+- ✅ Optional chaining and nullish coalescing
+- ❌ Avoid type assertions unless necessary
+
+**See Also:**
+- [component-patterns.md](component-patterns.md) - Component typing
+- [data-fetching.md](data-fetching.md) - API typing

package/templates/claude/skills/markdown-novel-viewer/SKILL.md

@@ -0,0 +1,272 @@
+# markdown-novel-viewer
+
+Background HTTP server rendering markdown files with calm, book-like reading experience.
+
+## ⚠️ Installation Required
+
+**This skill requires npm dependencies.** Run one of the following:
+
+```bash
+cd .claude/skills/markdown-novel-viewer
+npm install
+```
+
+**Dependencies:** `marked`, `highlight.js`, `gray-matter`
+
+Without installation, you'll get **Error 500: Error rendering markdown**.
+
+## Purpose
+
+Universal viewer - pass ANY path and view it:
+- **Markdown files** → novel-reader UI with serif fonts, warm theme
+- **Directories** → file listing browser with clickable links
+
+## Quick Start
+
+```bash
+# View a markdown file
+node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
+  --file ./plans/my-plan/plan.md \
+  --open
+
+# Browse a directory
+node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
+  --dir ./plans \
+  --host 0.0.0.0 \
+  --open
+
+# Background mode
+node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
+  --file ./README.md \
+  --background
+
+# Stop all running servers
+node $HOME/.claude/skills/markdown-novel-viewer/scripts/server.cjs --stop
+```
+
+## Slash Command
+
+Use `/preview` for quick access:
+
+```bash
+/preview plans/my-plan/plan.md    # View markdown file
+/preview plans/                   # Browse directory
+/preview --stop                   # Stop server
+```
+
+## Features
+
+### Novel Theme
+- Warm cream background (light mode)
+- Dark mode with warm gold accents
+- Libre Baskerville serif headings
+- Inter body text, JetBrains Mono code
+- Maximum 720px content width
+
+### Mermaid.js Diagrams
+- Auto-renders `mermaid` code blocks as diagrams
+- Theme-aware (light/dark mode support)
+- Error display with source preview for debugging
+
+### Directory Browser
+- Clean file listing with emoji icons
+- Markdown files link to viewer
+- Folders link to sub-directories
+- Parent directory navigation (..)
+- Light/dark mode support
+
+### Plan Navigation
+- Auto-detects plan directory structure
+- Sidebar shows all phases with status indicators
+- Previous/Next navigation buttons
+- Keyboard shortcuts: Arrow Left/Right
+
+### Keyboard Shortcuts
+- `T` - Toggle theme
+- `S` - Toggle sidebar
+- `Left/Right` - Navigate phases
+- `Escape` - Close sidebar (mobile)
+
+## CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--file <path>` | Markdown file to view | - |
+| `--dir <path>` | Directory to browse | - |
+| `--port <number>` | Server port | 3456 |
+| `--host <addr>` | Host to bind (`0.0.0.0` for remote) | localhost |
+| `--open` | Auto-open browser | false |
+| `--background` | Run in background | false |
+| `--stop` | Stop all servers | - |
+
+## Architecture
+
+```
+scripts/
+├── server.cjs               # Main entry point
+└── lib/
+    ├── port-finder.cjs      # Dynamic port allocation
+    ├── process-mgr.cjs      # PID file management
+    ├── http-server.cjs      # Core HTTP routing (/view, /browse)
+    ├── markdown-renderer.cjs # MD→HTML conversion
+    └── plan-navigator.cjs   # Plan detection & nav
+
+assets/
+├── template.html            # Markdown viewer template
+├── novel-theme.css          # Combined light/dark theme
+├── reader.js                # Client-side interactivity
+├── directory-browser.css    # Directory browser styles
+```
+
+## HTTP Routes
+
+| Route | Description |
+|-------|-------------|
+| `/view?file=<path>` | Markdown file viewer |
+| `/browse?dir=<path>` | Directory browser |
+| `/assets/*` | Static assets |
+| `/file/*` | Local file serving (images) |
+
+## Dependencies
+
+- Node.js built-in: `http`, `fs`, `path`, `net`
+- npm: `marked`, `highlight.js`, `gray-matter` (installed via `npm install`)
+
+## Customization
+
+### Theme Colors (CSS Variables)
+
+Light mode variables in `assets/novel-theme.css`:
+```css
+--bg-primary: #faf8f3;      /* Warm cream */
+--accent: #8b4513;          /* Saddle brown */
+```
+
+Dark mode:
+```css
+--bg-primary: #1a1a1a;      /* Near black */
+--accent: #d4a574;          /* Warm gold */
+```
+
+### Content Width
+```css
+--content-width: 720px;
+```
+
+## Remote Access
+
+To access from another device on your network:
+
+```bash
+# Start with 0.0.0.0 to bind to all interfaces
+node server.cjs --file ./README.md --host 0.0.0.0 --port 3456
+```
+
+When using `--host 0.0.0.0`, the server auto-detects your local network IP and includes it in the output:
+
+```json
+{
+  "success": true,
+  "url": "http://localhost:3456/view?file=...",
+  "networkUrl": "http://192.168.2.75:3456/view?file=...",
+  "port": 3456
+}
+```
+
+Use `networkUrl` to access from other devices on the same network.
+
+## Troubleshooting
+
+**Port in use**: Server auto-increments to next available port (3456-3500)
+
+**Images not loading**: Ensure image paths are relative to markdown file
+
+**Server won't stop**: Check `/tmp/md-novel-viewer-*.pid` for stale PID files
+
+**Remote access denied**: Use `--host 0.0.0.0` to bind to all interfaces
+
+## Mermaid.js Diagrams
+
+### Usage
+
+Use fenced code blocks with `mermaid` language:
+
+````markdown
+```mermaid
+pie title Traffic Sources
+    "Organic" : 45
+    "Direct" : 30
+    "Referral" : 25
+```
+````
+
+### Supported Diagram Types
+
+| Type | Syntax | Use Case |
+|------|--------|----------|
+| Flowchart | `flowchart LR/TB/TD` | Process flows, decision trees |
+| Sequence | `sequenceDiagram` | API interactions, message flows |
+| Pie | `pie title "..."` | Distribution data |
+| Gantt | `gantt` | Project timelines |
+| XY Chart | `xychart-beta` | Bar/line charts |
+| Mindmap | `mindmap` | Idea hierarchies |
+| Quadrant | `quadrantChart` | 2x2 matrices |
+
+### Validating Mermaid Snippets
+
+**Quick validation**: Use the [Mermaid Live Editor](https://mermaid.live) to test syntax.
+
+**Common errors and fixes**:
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Parse error` | Invalid syntax | Check diagram type declaration |
+| `Unknown diagram type` | Typo in declaration | Use exact type: `flowchart`, not `flow` |
+| `Expecting token` | Missing quotes/brackets | Ensure balanced delimiters |
+| `UnknownDiagramError` | Empty or malformed block | Add valid diagram content |
+
+### Fixing Common Issues
+
+**1. Flowchart arrows**
+```mermaid
+%% Wrong: A -> B
+%% Correct:
+flowchart LR
+    A --> B
+```
+
+**2. Pie chart values**
+```mermaid
+%% Wrong: "Label": 50%
+%% Correct:
+pie title Sales
+    "Product A" : 50
+    "Product B" : 30
+```
+
+**3. XY Chart data format**
+```mermaid
+xychart-beta
+    title "Monthly Sales"
+    x-axis [Jan, Feb, Mar]
+    y-axis "Revenue" 0 --> 100
+    bar [30, 45, 60]
+```
+
+**4. Sequence diagram participants**
+```mermaid
+sequenceDiagram
+    participant A as Client
+    participant B as Server
+    A->>B: Request
+    B-->>A: Response
+```
+
+### Debug Mode
+
+When a diagram fails to render, the viewer shows:
+- Error message
+- Expandable source code preview
+- Line number where parsing failed (when available)
+
+Fix the syntax and refresh the page to re-render.