@ngxtm/devkit 3.7.0 → 3.9.0

package/merged-commands/nodejs-best-practices.md

@@ -0,0 +1,333 @@
+---
+name: nodejs-best-practices
+description: Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Node.js Best Practices
+
+> Principles and decision-making for Node.js development in 2025.
+> **Learn to THINK, not memorize code patterns.**
+
+---
+
+## ⚠️ How to Use This Skill
+
+This skill teaches **decision-making principles**, not fixed code to copy.
+
+- ASK user for preferences when unclear
+- Choose framework/pattern based on CONTEXT
+- Don't default to same solution every time
+
+---
+
+## 1. Framework Selection (2025)
+
+### Decision Tree
+
+```
+What are you building?
+│
+├── Edge/Serverless (Cloudflare, Vercel)
+│   └── Hono (zero-dependency, ultra-fast cold starts)
+│
+├── High Performance API
+│   └── Fastify (2-3x faster than Express)
+│
+├── Enterprise/Team familiarity
+│   └── NestJS (structured, DI, decorators)
+│
+├── Legacy/Stable/Maximum ecosystem
+│   └── Express (mature, most middleware)
+│
+└── Full-stack with frontend
+    └── Next.js API Routes or tRPC
+```
+
+### Comparison Principles
+
+| Factor | Hono | Fastify | Express |
+|--------|------|---------|---------|
+| **Best for** | Edge, serverless | Performance | Legacy, learning |
+| **Cold start** | Fastest | Fast | Moderate |
+| **Ecosystem** | Growing | Good | Largest |
+| **TypeScript** | Native | Excellent | Good |
+| **Learning curve** | Low | Medium | Low |
+
+### Selection Questions to Ask:
+1. What's the deployment target?
+2. Is cold start time critical?
+3. Does team have existing experience?
+4. Is there legacy code to maintain?
+
+---
+
+## 2. Runtime Considerations (2025)
+
+### Native TypeScript
+
+```
+Node.js 22+: --experimental-strip-types
+├── Run .ts files directly
+├── No build step needed for simple projects
+└── Consider for: scripts, simple APIs
+```
+
+### Module System Decision
+
+```
+ESM (import/export)
+├── Modern standard
+├── Better tree-shaking
+├── Async module loading
+└── Use for: new projects
+
+CommonJS (require)
+├── Legacy compatibility
+├── More npm packages support
+└── Use for: existing codebases, some edge cases
+```
+
+### Runtime Selection
+
+| Runtime | Best For |
+|---------|----------|
+| **Node.js** | General purpose, largest ecosystem |
+| **Bun** | Performance, built-in bundler |
+| **Deno** | Security-first, built-in TypeScript |
+
+---
+
+## 3. Architecture Principles
+
+### Layered Structure Concept
+
+```
+Request Flow:
+│
+├── Controller/Route Layer
+│   ├── Handles HTTP specifics
+│   ├── Input validation at boundary
+│   └── Calls service layer
+│
+├── Service Layer
+│   ├── Business logic
+│   ├── Framework-agnostic
+│   └── Calls repository layer
+│
+└── Repository Layer
+    ├── Data access only
+    ├── Database queries
+    └── ORM interactions
+```
+
+### Why This Matters:
+- **Testability**: Mock layers independently
+- **Flexibility**: Swap database without touching business logic
+- **Clarity**: Each layer has single responsibility
+
+### When to Simplify:
+- Small scripts → Single file OK
+- Prototypes → Less structure acceptable
+- Always ask: "Will this grow?"
+
+---
+
+## 4. Error Handling Principles
+
+### Centralized Error Handling
+
+```
+Pattern:
+├── Create custom error classes
+├── Throw from any layer
+├── Catch at top level (middleware)
+└── Format consistent response
+```
+
+### Error Response Philosophy
+
+```
+Client gets:
+├── Appropriate HTTP status
+├── Error code for programmatic handling
+├── User-friendly message
+└── NO internal details (security!)
+
+Logs get:
+├── Full stack trace
+├── Request context
+├── User ID (if applicable)
+└── Timestamp
+```
+
+### Status Code Selection
+
+| Situation | Status | When |
+|-----------|--------|------|
+| Bad input | 400 | Client sent invalid data |
+| No auth | 401 | Missing or invalid credentials |
+| No permission | 403 | Valid auth, but not allowed |
+| Not found | 404 | Resource doesn't exist |
+| Conflict | 409 | Duplicate or state conflict |
+| Validation | 422 | Schema valid but business rules fail |
+| Server error | 500 | Our fault, log everything |
+
+---
+
+## 5. Async Patterns Principles
+
+### When to Use Each
+
+| Pattern | Use When |
+|---------|----------|
+| `async/await` | Sequential async operations |
+| `Promise.all` | Parallel independent operations |
+| `Promise.allSettled` | Parallel where some can fail |
+| `Promise.race` | Timeout or first response wins |
+
+### Event Loop Awareness
+
+```
+I/O-bound (async helps):
+├── Database queries
+├── HTTP requests
+├── File system
+└── Network operations
+
+CPU-bound (async doesn't help):
+├── Crypto operations
+├── Image processing
+├── Complex calculations
+└── → Use worker threads or offload
+```
+
+### Avoiding Event Loop Blocking
+
+- Never use sync methods in production (fs.readFileSync, etc.)
+- Offload CPU-intensive work
+- Use streaming for large data
+
+---
+
+## 6. Validation Principles
+
+### Validate at Boundaries
+
+```
+Where to validate:
+├── API entry point (request body/params)
+├── Before database operations
+├── External data (API responses, file uploads)
+└── Environment variables (startup)
+```
+
+### Validation Library Selection
+
+| Library | Best For |
+|---------|----------|
+| **Zod** | TypeScript first, inference |
+| **Valibot** | Smaller bundle (tree-shakeable) |
+| **ArkType** | Performance critical |
+| **Yup** | Existing React Form usage |
+
+### Validation Philosophy
+
+- Fail fast: Validate early
+- Be specific: Clear error messages
+- Don't trust: Even "internal" data
+
+---
+
+## 7. Security Principles
+
+### Security Checklist (Not Code)
+
+- [ ] **Input validation**: All inputs validated
+- [ ] **Parameterized queries**: No string concatenation for SQL
+- [ ] **Password hashing**: bcrypt or argon2
+- [ ] **JWT verification**: Always verify signature and expiry
+- [ ] **Rate limiting**: Protect from abuse
+- [ ] **Security headers**: Helmet.js or equivalent
+- [ ] **HTTPS**: Everywhere in production
+- [ ] **CORS**: Properly configured
+- [ ] **Secrets**: Environment variables only
+- [ ] **Dependencies**: Regularly audited
+
+### Security Mindset
+
+```
+Trust nothing:
+├── Query params → validate
+├── Request body → validate
+├── Headers → verify
+├── Cookies → validate
+├── File uploads → scan
+└── External APIs → validate response
+```
+
+---
+
+## 8. Testing Principles
+
+### Test Strategy Selection
+
+| Type | Purpose | Tools |
+|------|---------|-------|
+| **Unit** | Business logic | node:test, Vitest |
+| **Integration** | API endpoints | Supertest |
+| **E2E** | Full flows | Playwright |
+
+### What to Test (Priorities)
+
+1. **Critical paths**: Auth, payments, core business
+2. **Edge cases**: Empty inputs, boundaries
+3. **Error handling**: What happens when things fail?
+4. **Not worth testing**: Framework code, trivial getters
+
+### Built-in Test Runner (Node.js 22+)
+
+```
+node --test src/**/*.test.ts
+├── No external dependency
+├── Good coverage reporting
+└── Watch mode available
+```
+
+---
+
+## 10. Anti-Patterns to Avoid
+
+### ❌ DON'T:
+- Use Express for new edge projects (use Hono)
+- Use sync methods in production code
+- Put business logic in controllers
+- Skip input validation
+- Hardcode secrets
+- Trust external data without validation
+- Block event loop with CPU work
+
+### ✅ DO:
+- Choose framework based on context
+- Ask user for preferences when unclear
+- Use layered architecture for growing projects
+- Validate all inputs
+- Use environment variables for secrets
+- Profile before optimizing
+
+---
+
+## 11. Decision Checklist
+
+Before implementing:
+
+- [ ] **Asked user about stack preference?**
+- [ ] **Chosen framework for THIS context?** (not just default)
+- [ ] **Considered deployment target?**
+- [ ] **Planned error handling strategy?**
+- [ ] **Identified validation points?**
+- [ ] **Considered security requirements?**
+
+---
+
+> **Remember**: Node.js best practices are about decision-making, not memorizing patterns. Every project deserves fresh consideration based on its requirements.

package/merged-commands/nosql-expert.md

@@ -0,0 +1,111 @@
+---
+name: nosql-expert
+description: "Expert guidance for distributed NoSQL databases (Cassandra, DynamoDB). Focuses on mental models, query-first modeling, single-table design, and avoiding hot partitions in high-scale systems."
+---
+
+# NoSQL Expert Patterns (Cassandra & DynamoDB)
+
+## Overview
+
+This skill provides professional mental models and design patterns for **distributed wide-column and key-value stores** (specifically Apache Cassandra and Amazon DynamoDB).
+
+Unlike SQL (where you model data entities), or document stores (like MongoDB), these distributed systems require you to **model your queries first**.
+
+## When to Use
+
+- **Designing for Scale**: Moving beyond simple single-node databases to distributed clusters.
+- **Technology Selection**: Evaluating or using **Cassandra**, **ScyllaDB**, or **DynamoDB**.
+- **Performance Tuning**: Troubleshooting "hot partitions" or high latency in existing NoSQL systems.
+- **Microservices**: Implementing "database-per-service" patterns where highly optimized reads are required.
+
+## The Mental Shift: SQL vs. Distributed NoSQL
+
+| Feature | SQL (Relational) | Distributed NoSQL (Cassandra/DynamoDB) |
+| :--- | :--- | :--- |
+| **Data modeling** | Model Entities + Relationships | Model **Queries** (Access Patterns) |
+| **Joins** | CPU-intensive, at read time | **Pre-computed** (Denormalized) at write time |
+| **Storage cost** | Expensive (minimize duplication) | Cheap (duplicate data for read speed) |
+| **Consistency** | ACID (Strong) | **BASE (Eventual)** / Tunable |
+| **Scalability** | Vertical (Bigger machine) | **Horizontal** (More nodes/shards) |
+
+> **The Golden Rule:** In SQL, you design the data model to answer *any* query. In NoSQL, you design the data model to answer *specific* queries efficiently.
+
+## Core Design Patterns
+
+### 1. Query-First Modeling (Access Patterns)
+
+You typically cannot "add a query later" without migration or creating a new table/index.
+
+**Process:**
+1.  **List all Entities** (User, Order, Product).
+2.  **List all Access Patterns** ("Get User by Email", "Get Orders by User sorted by Date").
+3.  **Design Table(s)** specifically to serve those patterns with a single lookup.
+
+### 2. The Partition Key is King
+
+Data is distributed across physical nodes based on the **Partition Key (PK)**.
+-   **Goal:** Even distribution of data and traffic.
+-   **Anti-Pattern:** Using a low-cardinality PK (e.g., `status="active"` or `gender="m"`) creates **Hot Partitions**, limiting throughput to a single node's capacity.
+-   **Best Practice:** Use high-cardinality keys (User IDs, Device IDs, Composite Keys).
+
+### 3. Clustering / Sort Keys
+
+Within a partition, data is sorted on disk by the **Clustering Key (Cassandra)** or **Sort Key (DynamoDB)**.
+-   This allows for efficient **Range Queries** (e.g., `WHERE user_id=X AND date > Y`).
+-   It effectively pre-sorts your data for specific retrieval requirements.
+
+### 4. Single-Table Design (Adjacency Lists)
+
+*Primary use: DynamoDB (but concepts apply elsewhere)*
+
+Storing multiple entity types in one table to enable pre-joined reads.
+
+| PK (Partition) | SK (Sort) | Data Fields... |
+| :--- | :--- | :--- |
+| `USER#123` | `PROFILE` | `{ name: "Ian", email: "..." }` |
+| `USER#123` | `ORDER#998` | `{ total: 50.00, status: "shipped" }` |
+| `USER#123` | `ORDER#999` | `{ total: 12.00, status: "pending" }` |
+
+-   **Query:** `PK="USER#123"`
+-   **Result:** Fetches User Profile AND all Orders in **one network request**.
+
+### 5. Denormalization & Duplication
+
+Don't be afraid to store the same data in multiple tables to serve different query patterns.
+-   **Table A:** `users_by_id` (PK: uuid)
+-   **Table B:** `users_by_email` (PK: email)
+
+*Trade-off: You must manage data consistency across tables (often using eventual consistency or batch writes).*
+
+## Specific Guidance
+
+### Apache Cassandra / ScyllaDB
+
+-   **Primary Key Structure:** `((Partition Key), Clustering Columns)`
+-   **No Joins, No Aggregates:** Do not try to `JOIN` or `GROUP BY`. Pre-calculate aggregates in a separate counter table.
+-   **Avoid `ALLOW FILTERING`:** If you see this in production, your data model is wrong. It implies a full cluster scan.
+-   **Writes are Cheap:** Inserts and Updates are just appends to the LSM tree. Don't worry about write volume as much as read efficiency.
+-   **Tombstones:** Deletes are expensive markers. Avoid high-velocity delete patterns (like queues) in standard tables.
+
+### AWS DynamoDB
+
+-   **GSI (Global Secondary Index):** Use GSIs to create alternative views of your data (e.g., "Search Orders by Date" instead of by User).
+    -   *Note:* GSIs are eventually consistent.
+-   **LSI (Local Secondary Index):** Sorts data differently *within* the same partition. Must be created at table creation time.
+-   **WCU / RCU:** Understand capacity modes. Single-table design helps optimize consumed capacity units.
+-   **TTL:** Use Time-To-Live attributes to automatically expire old data (free delete) without creating tombstones.
+
+## Expert Checklist
+
+Before finalizing your NoSQL schema:
+
+-   [ ] **Access Pattern Coverage:** Does every query pattern map to a specific table or index?
+-   [ ] **Cardinality Check:** Does the Partition Key have enough unique values to spread traffic evenly?
+-   [ ] **Split Partition Risk:** For any single partition (e.g., a single user's orders), will it grow indefinitely? (If > 10GB, you need to "shard" the partition, e.g., `USER#123#2024-01`).
+-   [ ] **Consistency Requirement:** Can the application tolerate eventual consistency for this read pattern?
+
+## Common Anti-Patterns
+
+❌ **Scatter-Gather:** Querying *all* partitions to find one item (Scan).
+❌ **Hot Keys:** Putting all "Monday" data into one partition.
+❌ **Relational Modeling:** Creating `Author` and `Book` tables and trying to join them in code. (Instead, embed Book summaries in Author, or duplicate Author info in Books).

package/merged-commands/notebooklm-skill.md

@@ -0,0 +1,269 @@
+---
+name: notebooklm
+description: Use this skill to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini. Browser automation, library management, persistent auth. Drastically reduced hallucinations through document-only responses.
+---
+
+# NotebookLM Research Assistant Skill
+
+Interact with Google NotebookLM to query documentation with Gemini's source-grounded answers. Each question opens a fresh browser session, retrieves the answer exclusively from your uploaded documents, and closes.
+
+## When to Use This Skill
+
+Trigger when user:
+- Mentions NotebookLM explicitly
+- Shares NotebookLM URL (`https://notebooklm.google.com/notebook/...`)
+- Asks to query their notebooks/documentation
+- Wants to add documentation to NotebookLM library
+- Uses phrases like "ask my NotebookLM", "check my docs", "query my notebook"
+
+## ⚠️ CRITICAL: Add Command - Smart Discovery
+
+When user wants to add a notebook without providing details:
+
+**SMART ADD (Recommended)**: Query the notebook first to discover its content:
+```bash
+# Step 1: Query the notebook about its content
+python scripts/run.py ask_question.py --question "What is the content of this notebook? What topics are covered? Provide a complete overview briefly and concisely" --notebook-url "[URL]"
+
+# Step 2: Use the discovered information to add it
+python scripts/run.py notebook_manager.py add --url "[URL]" --name "[Based on content]" --description "[Based on content]" --topics "[Based on content]"
+```
+
+**MANUAL ADD**: If user provides all details:
+- `--url` - The NotebookLM URL
+- `--name` - A descriptive name
+- `--description` - What the notebook contains (REQUIRED!)
+- `--topics` - Comma-separated topics (REQUIRED!)
+
+NEVER guess or use generic descriptions! If details missing, use Smart Add to discover them.
+
+## Critical: Always Use run.py Wrapper
+
+**NEVER call scripts directly. ALWAYS use `python scripts/run.py [script]`:**
+
+```bash
+# ✅ CORRECT - Always use run.py:
+python scripts/run.py auth_manager.py status
+python scripts/run.py notebook_manager.py list
+python scripts/run.py ask_question.py --question "..."
+
+# ❌ WRONG - Never call directly:
+python scripts/auth_manager.py status  # Fails without venv!
+```
+
+The `run.py` wrapper automatically:
+1. Creates `.venv` if needed
+2. Installs all dependencies
+3. Activates environment
+4. Executes script properly
+
+## Core Workflow
+
+### Step 1: Check Authentication Status
+```bash
+python scripts/run.py auth_manager.py status
+```
+
+If not authenticated, proceed to setup.
+
+### Step 2: Authenticate (One-Time Setup)
+```bash
+# Browser MUST be visible for manual Google login
+python scripts/run.py auth_manager.py setup
+```
+
+**Important:**
+- Browser is VISIBLE for authentication
+- Browser window opens automatically
+- User must manually log in to Google
+- Tell user: "A browser window will open for Google login"
+
+### Step 3: Manage Notebook Library
+
+```bash
+# List all notebooks
+python scripts/run.py notebook_manager.py list
+
+# BEFORE ADDING: Ask user for metadata if unknown!
+# "What does this notebook contain?"
+# "What topics should I tag it with?"
+
+# Add notebook to library (ALL parameters are REQUIRED!)
+python scripts/run.py notebook_manager.py add \
+  --url "https://notebooklm.google.com/notebook/..." \
+  --name "Descriptive Name" \
+  --description "What this notebook contains" \  # REQUIRED - ASK USER IF UNKNOWN!
+  --topics "topic1,topic2,topic3"  # REQUIRED - ASK USER IF UNKNOWN!
+
+# Search notebooks by topic
+python scripts/run.py notebook_manager.py search --query "keyword"
+
+# Set active notebook
+python scripts/run.py notebook_manager.py activate --id notebook-id
+
+# Remove notebook
+python scripts/run.py notebook_manager.py remove --id notebook-id
+```
+
+### Quick Workflow
+1. Check library: `python scripts/run.py notebook_manager.py list`
+2. Ask question: `python scripts/run.py ask_question.py --question "..." --notebook-id ID`
+
+### Step 4: Ask Questions
+
+```bash
+# Basic query (uses active notebook if set)
+python scripts/run.py ask_question.py --question "Your question here"
+
+# Query specific notebook
+python scripts/run.py ask_question.py --question "..." --notebook-id notebook-id
+
+# Query with notebook URL directly
+python scripts/run.py ask_question.py --question "..." --notebook-url "https://..."
+
+# Show browser for debugging
+python scripts/run.py ask_question.py --question "..." --show-browser
+```
+
+## Follow-Up Mechanism (CRITICAL)
+
+Every NotebookLM answer ends with: **"EXTREMELY IMPORTANT: Is that ALL you need to know?"**
+
+**Required Claude Behavior:**
+1. **STOP** - Do not immediately respond to user
+2. **ANALYZE** - Compare answer to user's original request
+3. **IDENTIFY GAPS** - Determine if more information needed
+4. **ASK FOLLOW-UP** - If gaps exist, immediately ask:
+   ```bash
+   python scripts/run.py ask_question.py --question "Follow-up with context..."
+   ```
+5. **REPEAT** - Continue until information is complete
+6. **SYNTHESIZE** - Combine all answers before responding to user
+
+## Script Reference
+
+### Authentication Management (`auth_manager.py`)
+```bash
+python scripts/run.py auth_manager.py setup    # Initial setup (browser visible)
+python scripts/run.py auth_manager.py status   # Check authentication
+python scripts/run.py auth_manager.py reauth   # Re-authenticate (browser visible)
+python scripts/run.py auth_manager.py clear    # Clear authentication
+```
+
+### Notebook Management (`notebook_manager.py`)
+```bash
+python scripts/run.py notebook_manager.py add --url URL --name NAME --description DESC --topics TOPICS
+python scripts/run.py notebook_manager.py list
+python scripts/run.py notebook_manager.py search --query QUERY
+python scripts/run.py notebook_manager.py activate --id ID
+python scripts/run.py notebook_manager.py remove --id ID
+python scripts/run.py notebook_manager.py stats
+```
+
+### Question Interface (`ask_question.py`)
+```bash
+python scripts/run.py ask_question.py --question "..." [--notebook-id ID] [--notebook-url URL] [--show-browser]
+```
+
+### Data Cleanup (`cleanup_manager.py`)
+```bash
+python scripts/run.py cleanup_manager.py                    # Preview cleanup
+python scripts/run.py cleanup_manager.py --confirm          # Execute cleanup
+python scripts/run.py cleanup_manager.py --preserve-library # Keep notebooks
+```
+
+## Environment Management
+
+The virtual environment is automatically managed:
+- First run creates `.venv` automatically
+- Dependencies install automatically
+- Chromium browser installs automatically
+- Everything isolated in skill directory
+
+Manual setup (only if automatic fails):
+```bash
+python -m venv .venv
+source .venv/bin/activate  # Linux/Mac
+pip install -r requirements.txt
+python -m patchright install chromium
+```
+
+## Data Storage
+
+All data stored in `~/.claude/skills/notebooklm/data/`:
+- `library.json` - Notebook metadata
+- `auth_info.json` - Authentication status
+- `browser_state/` - Browser cookies and session
+
+**Security:** Protected by `.gitignore`, never commit to git.
+
+## Configuration
+
+Optional `.env` file in skill directory:
+```env
+HEADLESS=false           # Browser visibility
+SHOW_BROWSER=false       # Default browser display
+STEALTH_ENABLED=true     # Human-like behavior
+TYPING_WPM_MIN=160       # Typing speed
+TYPING_WPM_MAX=240
+DEFAULT_NOTEBOOK_ID=     # Default notebook
+```
+
+## Decision Flow
+
+```
+User mentions NotebookLM
+    ↓
+Check auth → python scripts/run.py auth_manager.py status
+    ↓
+If not authenticated → python scripts/run.py auth_manager.py setup
+    ↓
+Check/Add notebook → python scripts/run.py notebook_manager.py list/add (with --description)
+    ↓
+Activate notebook → python scripts/run.py notebook_manager.py activate --id ID
+    ↓
+Ask question → python scripts/run.py ask_question.py --question "..."
+    ↓
+See "Is that ALL you need?" → Ask follow-ups until complete
+    ↓
+Synthesize and respond to user
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| ModuleNotFoundError | Use `run.py` wrapper |
+| Authentication fails | Browser must be visible for setup! --show-browser |
+| Rate limit (50/day) | Wait or switch Google account |
+| Browser crashes | `python scripts/run.py cleanup_manager.py --preserve-library` |
+| Notebook not found | Check with `notebook_manager.py list` |
+
+## Best Practices
+
+1. **Always use run.py** - Handles environment automatically
+2. **Check auth first** - Before any operations
+3. **Follow-up questions** - Don't stop at first answer
+4. **Browser visible for auth** - Required for manual login
+5. **Include context** - Each question is independent
+6. **Synthesize answers** - Combine multiple responses
+
+## Limitations
+
+- No session persistence (each question = new browser)
+- Rate limits on free Google accounts (50 queries/day)
+- Manual upload required (user must add docs to NotebookLM)
+- Browser overhead (few seconds per question)
+
+## Resources (Skill Structure)
+
+**Important directories and files:**
+
+- `scripts/` - All automation scripts (ask_question.py, notebook_manager.py, etc.)
+- `data/` - Local storage for authentication and notebook library
+- `references/` - Extended documentation:
+  - `api_reference.md` - Detailed API documentation for all scripts
+  - `troubleshooting.md` - Common issues and solutions
+  - `usage_patterns.md` - Best practices and workflow examples
+- `.venv/` - Isolated Python environment (auto-created on first run)
+- `.gitignore` - Protects sensitive data from being committed