cokit-cli 1.0.8 → 1.2.0

package/skills/databases/stacks/sqlite.md

@@ -0,0 +1,244 @@
+# SQLite Rules
+
+Guidelines for designing schemas specific to SQLite.
+
+---
+
+## Data Types
+
+SQLite has **dynamic typing**, with only 5 storage classes:
+
+| Storage Class | Use case | Notes |
+|---------------|----------|-------|
+| `INTEGER` | PK, FK, counts, booleans | |
+| `REAL` | Floats, decimals | |
+| `TEXT` | Strings, dates, JSON, enums | |
+| `BLOB` | Binary data | |
+| `NULL` | Null values | |
+
+### Type affinity
+SQLite does not strictly enforce types. Type declaration is just a "hint":
+```sql
+-- All of these will be stored
+CREATE TABLE test (price REAL);
+INSERT INTO test VALUES (100);      -- Stored as INTEGER
+INSERT INTO test VALUES (99.99);    -- Stored as REAL
+INSERT INTO test VALUES ('free');   -- Stored as TEXT (!)
+```
+
+### Date/Time
+SQLite **does not have** DATE/TIME type. Store as TEXT with ISO format:
+```sql
+created_at TEXT DEFAULT (datetime('now'))
+-- Format: YYYY-MM-DD HH:MM:SS
+```
+
+---
+
+## Metadata Tables (REQUIRED)
+
+SQLite **does not support comments** on tables and columns. Need to create metadata tables:
+
+### Create metadata tables
+
+```sql
+CREATE TABLE IF NOT EXISTS metadata_tables (
+    table_name TEXT PRIMARY KEY,
+    description TEXT NOT NULL,
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS metadata_columns (
+    table_name TEXT NOT NULL,
+    column_name TEXT NOT NULL,
+    description TEXT NOT NULL,
+    data_type TEXT,
+    is_nullable INTEGER DEFAULT 1,  -- 0=NOT NULL, 1=NULL
+    default_value TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    PRIMARY KEY (table_name, column_name),
+    FOREIGN KEY (table_name) REFERENCES metadata_tables(table_name) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_metadata_columns_table ON metadata_columns(table_name);
+```
+
+### Insert metadata after creating table
+
+```sql
+-- Table metadata
+INSERT INTO metadata_tables (table_name, description)
+VALUES ('orders', 'Table storing customer order information');
+
+-- Column metadata
+INSERT INTO metadata_columns (table_name, column_name, description, data_type, is_nullable)
+VALUES
+    ('orders', 'id', 'Primary key, auto increment', 'INTEGER', 0),
+    ('orders', 'order_number', 'Unique order code', 'TEXT', 0),
+    ('orders', 'user_id', 'FK to users.id', 'INTEGER', 0),
+    ('orders', 'status', 'pending|confirmed|shipped|cancelled', 'TEXT', 0),
+    ('orders', 'total_amount', 'Total value', 'REAL', 0);
+```
+
+### Query metadata
+
+```sql
+-- View schema with descriptions
+SELECT
+    t.table_name,
+    t.description AS table_description,
+    c.column_name,
+    c.description AS column_description,
+    c.data_type
+FROM metadata_tables t
+LEFT JOIN metadata_columns c ON t.table_name = c.table_name
+ORDER BY t.table_name, c.column_name;
+```
+
+---
+
+## Auto Increment
+
+```sql
+-- Option 1: INTEGER PRIMARY KEY (recommended)
+-- SQLite auto-increments INTEGER PRIMARY KEY automatically
+CREATE TABLE users (
+    id INTEGER PRIMARY KEY,
+    name TEXT
+);
+
+-- Option 2: AUTOINCREMENT keyword
+-- Ensures deleted IDs are not reused (slower)
+CREATE TABLE users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT
+);
+```
+
+---
+
+## Foreign Keys
+
+**IMPORTANT**: FK is disabled by default in SQLite!
+
+```sql
+-- Enable FK for each connection
+PRAGMA foreign_keys = ON;
+
+-- Create table with FK
+CREATE TABLE order_items (
+    id INTEGER PRIMARY KEY,
+    order_id INTEGER NOT NULL,
+    product_id INTEGER NOT NULL,
+    FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE,
+    FOREIGN KEY (product_id) REFERENCES products(id) ON DELETE RESTRICT
+);
+
+-- Create index for FK
+CREATE INDEX idx_order_items_order ON order_items(order_id);
+CREATE INDEX idx_order_items_product ON order_items(product_id);
+```
+
+---
+
+## ENUM substitute
+
+SQLite does not have ENUM. Use CHECK constraint:
+
+```sql
+CREATE TABLE orders (
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'confirmed', 'shipped', 'cancelled'))
+);
+```
+
+---
+
+## Index Types
+
+SQLite only supports B-Tree indexes:
+
+```sql
+-- Standard index
+CREATE INDEX idx_orders_status ON orders(status);
+
+-- Composite index
+CREATE INDEX idx_orders_user_status ON orders(user_id, status);
+
+-- Unique index
+CREATE UNIQUE INDEX idx_orders_number ON orders(order_number);
+
+-- Partial index (SQLite 3.8.0+)
+CREATE INDEX idx_orders_active ON orders(user_id)
+    WHERE deleted_at IS NULL;
+```
+
+---
+
+## Limitations
+
+| Feature | Status | Workaround |
+|---------|--------|------------|
+| `ALTER COLUMN` | ❌ Not supported | Recreate table |
+| `DROP COLUMN` | ✅ SQLite 3.35+ | Recreate table (older) |
+| Comments | ❌ Not supported | Metadata tables |
+| ENUM | ❌ Not supported | CHECK constraint |
+| Stored procedures | ❌ Not supported | App logic |
+| Concurrent writes | ⚠️ Limited | Single writer |
+
+---
+
+## Example DDL
+
+```sql
+-- Enable foreign keys
+PRAGMA foreign_keys = ON;
+
+-- Create table
+CREATE TABLE orders (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    order_number TEXT NOT NULL,
+    user_id INTEGER NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'confirmed', 'shipped', 'cancelled')),
+    subtotal REAL NOT NULL DEFAULT 0,
+    discount_amount REAL NOT NULL DEFAULT 0,
+    total_amount REAL NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at TEXT,
+
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE RESTRICT
+);
+
+-- Indexes
+CREATE UNIQUE INDEX idx_orders_number ON orders(order_number);
+CREATE INDEX idx_orders_user ON orders(user_id);
+CREATE INDEX idx_orders_status ON orders(status);
+CREATE INDEX idx_orders_updated ON orders(updated_at);
+
+-- Metadata
+INSERT INTO metadata_tables (table_name, description)
+VALUES ('orders', 'Table storing order information');
+
+INSERT INTO metadata_columns (table_name, column_name, description, data_type, is_nullable)
+VALUES
+    ('orders', 'id', 'Primary key', 'INTEGER', 0),
+    ('orders', 'order_number', 'Unique order code', 'TEXT', 0),
+    ('orders', 'user_id', 'FK to users.id', 'INTEGER', 0),
+    ('orders', 'status', 'pending|confirmed|shipped|cancelled', 'TEXT', 0),
+    ('orders', 'total_amount', 'Total payment', 'REAL', 0);
+```
+
+---
+
+## Checklist
+
+- [ ] `PRAGMA foreign_keys = ON` at start of each connection
+- [ ] Metadata tables created
+- [ ] INSERT metadata after each CREATE TABLE
+- [ ] Use `TEXT` for dates (ISO format: YYYY-MM-DD HH:MM:SS)
+- [ ] CHECK constraint instead of ENUM
+- [ ] Index for FK columns
+- [ ] Update metadata when ALTER/DROP table

package/skills/databases/transactional.md

@@ -0,0 +1,176 @@
+# Transactional (OLTP) Rules
+
+> **Note:** Core naming conventions, workflow, and checklist are in `SKILL.md` or `db-design.md` (always loaded).
+
+Guidelines for designing schemas for day-to-day business operations.
+
+---
+
+## Normalization Principles
+
+### Prefer 3NF (Third Normal Form)
+
+- Each table represents one clear entity/relationship
+- No repeating information that can be referenced (use FK)
+- Clear separation:
+  - `orders` (header) vs `order_items` (line items)
+  - `products` vs `product_variants`, `product_prices`
+
+### Foreign Key Constraints
+
+Use FK with appropriate ON DELETE / ON UPDATE:
+
+```sql
+-- Cascade: delete order → delete order_items
+FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE
+
+-- Restrict: cannot delete user if orders exist
+FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE RESTRICT
+
+-- Set null: delete category → product.category_id = NULL
+FOREIGN KEY (category_id) REFERENCES categories(id) ON DELETE SET NULL
+```
+
+---
+
+## Indexing Rules
+
+### 1. Primary Key
+- Usually `BIGINT` auto-increment or UUID
+- Format: `PRIMARY KEY (id)`
+
+### 2. Foreign Key Indexes
+**IMPORTANT**: Create indexes for ALL foreign keys for efficient JOINs:
+```sql
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_order_items_order_id ON order_items(order_id);
+CREATE INDEX idx_order_items_product_id ON order_items(product_id);
+```
+
+### 3. Frequently Filtered Columns
+Index columns commonly used in WHERE:
+- `status`, `created_at`, `updated_at`
+- Code/reference columns: `order_number`, `sku`
+
+### 4. Composite Indexes
+Based on actual query patterns:
+```sql
+-- Query: WHERE user_id = ? AND status = ? ORDER BY created_at DESC
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
+
+-- Query: WHERE store_id = ? AND created_at BETWEEN ...
+CREATE INDEX idx_orders_store_created ON orders(store_id, created_at);
+```
+
+**Composite index rules:**
+- Put columns with **high selectivity** (fewer duplicate values) first
+- Avoid duplicate/redundant indexes
+- Index should cover WHERE + ORDER BY of query
+
+### 5. Unique Constraints
+```sql
+UNIQUE (order_number)
+UNIQUE (sku)
+UNIQUE (user_id, email)  -- compound unique
+```
+
+---
+
+## Soft Delete Pattern
+
+When you need to keep deleted data instead of permanently deleting:
+
+```sql
+-- Add deleted_at column
+deleted_at TIMESTAMP NULL
+
+-- Partial index for non-deleted records (PostgreSQL)
+CREATE INDEX idx_orders_active ON orders(user_id, status)
+    WHERE deleted_at IS NULL;
+
+-- Query only active records
+SELECT * FROM orders WHERE deleted_at IS NULL;
+```
+
+---
+
+## Anti-patterns to Avoid
+
+### Missing FK Index
+```sql
+-- ❌ BAD: FK without index → slow JOINs
+FOREIGN KEY (user_id) REFERENCES users(id)
+-- Forgot CREATE INDEX
+```
+
+### Over-indexing
+```sql
+-- ❌ BAD: Indexing each column separately
+CREATE INDEX idx_a ON orders(user_id);
+CREATE INDEX idx_b ON orders(status);
+CREATE INDEX idx_c ON orders(created_at);
+
+-- ✅ GOOD: Composite index based on query pattern
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
+```
+
+### Using TEXT instead of ENUM
+```sql
+-- ❌ BAD: Cannot validate values
+status TEXT
+
+-- ✅ GOOD: Use ENUM or CHECK
+status ENUM('pending', 'confirmed', 'shipped', 'cancelled')
+-- or
+status VARCHAR(32) CHECK (status IN ('pending', 'confirmed', 'shipped'))
+```
+
+### Missing Audit Columns
+```sql
+-- ❌ BAD
+CREATE TABLE products (id INT, name VARCHAR(255));
+
+-- ✅ GOOD
+CREATE TABLE products (
+    id INT,
+    name VARCHAR(255),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+```
+
+---
+
+## Example DDL
+
+```sql
+CREATE TABLE orders (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    order_number VARCHAR(50) NOT NULL,
+    user_id BIGINT NOT NULL,
+    status VARCHAR(32) NOT NULL DEFAULT 'pending',
+    subtotal DECIMAL(18,2) NOT NULL DEFAULT 0,
+    discount_amount DECIMAL(18,2) NOT NULL DEFAULT 0,
+    total_amount DECIMAL(18,2) NOT NULL DEFAULT 0,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+    UNIQUE (order_number),
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE RESTRICT
+);
+
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_orders_status ON orders(status);
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
+```
+
+---
+
+## Checklist
+
+- [ ] Audit columns: `created_at`, `updated_at`
+- [ ] All FKs have indexes
+- [ ] Unique constraints for business keys (`order_number`, `sku`, `email`)
+- [ ] ENUM or CHECK for status/type columns
+- [ ] Composite index based on main query patterns
+- [ ] Soft delete if needed: `deleted_at` + partial index

package/skills/debug/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: debug
+description: Debug systematically with root cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, call stack tracing, multi-layer validation.
+version: 3.1.0
+languages: all
+---
+
+# Debugging
+
+Comprehensive debugging framework combining systematic investigation, root cause tracing, defense-in-depth validation, and verification protocols.
+
+## Core Principle
+
+**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**
+
+Random fixes waste time and create new bugs. Find the root cause, fix at source, validate at every layer, verify before claiming success.
+
+## When to Use
+
+**Always use for:** Test failures, bugs, unexpected behavior, performance issues, build failures, integration problems, before claiming work complete
+
+**Especially when:** Under time pressure, "quick fix" seems obvious, tried multiple fixes, don't fully understand issue, about to claim success
+
+## The Four Techniques
+
+### 1. Systematic Debugging (`references/systematic-debugging.md`)
+
+Four-phase framework ensuring proper investigation:
+- Phase 1: Root Cause Investigation (read errors, reproduce, check changes, gather evidence)
+- Phase 2: Pattern Analysis (find working examples, compare, identify differences)
+- Phase 3: Hypothesis and Testing (form theory, test minimally, verify)
+- Phase 4: Implementation (create test, fix once, verify)
+
+**Key rule:** Complete each phase before proceeding. No fixes without Phase 1.
+
+**Load when:** Any bug/issue requiring investigation and fix
+
+### 2. Root Cause Tracing (`references/root-cause-tracing.md`)
+
+Trace bugs backward through call stack to find original trigger.
+
+**Technique:** When error appears deep in execution, trace backward level-by-level until finding source where invalid data originated. Fix at source, not at symptom.
+
+**Includes:** `scripts/find-polluter.sh` for bisecting test pollution
+
+**Load when:** Error deep in call stack, unclear where invalid data originated
+
+### 3. Defense-in-Depth (`references/defense-in-depth.md`)
+
+Validate at every layer data passes through. Make bugs impossible.
+
+**Four layers:** Entry validation → Business logic → Environment guards → Debug instrumentation
+
+**Load when:** After finding root cause, need to add comprehensive validation
+
+### 4. Verification (`references/verification.md`)
+
+Run verification commands and confirm output before claiming success.
+
+**Iron law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+
+Run the command. Read the output. Then claim the result.
+
+**Load when:** About to claim work complete, fixed, or passing
+
+## Quick Reference
+
+```
+Bug → systematic-debugging.md (Phase 1-4)
+  Error deep in stack? → root-cause-tracing.md (trace backward)
+  Found root cause? → defense-in-depth.md (add layers)
+  About to claim success? → verification.md (verify first)
+```
+
+## Red Flags
+
+Stop and follow process if thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "It's probably X, let me fix that"
+- "Should work now" / "Seems fixed"
+- "Tests pass, we're done"
+
+**All mean:** Return to systematic process.

package/skills/devops/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: devops
+description: Deploy to Cloudflare (Workers, R2, D1), Docker, GCP (Cloud Run, GKE), Azure (App Service, AKS), Kubernetes (kubectl, Helm). Use for serverless, containers, CI/CD, GitOps, security audit.
+license: MIT
+version: 2.0.0
+---
+
+# DevOps Skill
+
+Deploy and manage cloud infrastructure across Cloudflare, Docker, Google Cloud, and Kubernetes.
+
+## When to Use
+
+- Deploy serverless apps to Cloudflare Workers/Pages
+- Containerize apps with Docker, Docker Compose
+- Manage GCP with gcloud CLI (Cloud Run, GKE, Cloud SQL)
+- Kubernetes cluster management (kubectl, Helm)
+- GitOps workflows (Argo CD, Flux)
+- CI/CD pipelines, multi-region deployments
+- Security audits, RBAC, network policies
+
+## Platform Selection
+
+| Need | Choose |
+|------|--------|
+| Sub-50ms latency globally | Cloudflare Workers |
+| Large file storage (zero egress) | Cloudflare R2 |
+| SQL database (global reads) | Cloudflare D1 |
+| Containerized workloads | Docker + Cloud Run/GKE/Azure Container Apps |
+| Enterprise Kubernetes | GKE / AKS |
+| Managed relational DB | Cloud SQL / Azure SQL |
+| .NET workloads | Azure App Service / Container Apps |
+| Static site + API | Cloudflare Pages |
+| Container orchestration | Kubernetes |
+| Package management for K8s | Helm |
+
+## Quick Start
+
+```bash
+# Cloudflare Worker
+wrangler init my-worker && cd my-worker && wrangler deploy
+
+# Docker
+docker build -t myapp . && docker run -p 3000:3000 myapp
+
+# GCP Cloud Run
+gcloud run deploy my-service --image gcr.io/project/image --region us-central1
+
+# Azure App Service (.NET)
+az webapp up --name myapp --resource-group mygroup --runtime "DOTNET:8.0"
+
+# Azure Container Apps
+az containerapp up --name myapp --resource-group mygroup --image myregistry.azurecr.io/myapp:latest
+
+# Kubernetes
+kubectl apply -f manifests/ && kubectl get pods
+```
+
+## Reference Navigation
+
+### Cloudflare Platform
+- `cloudflare-platform.md` - Edge computing overview
+- `cloudflare-workers-basics.md` - Handler types, patterns
+- `cloudflare-workers-advanced.md` - Performance, optimization
+- `cloudflare-workers-apis.md` - Runtime APIs, bindings
+- `cloudflare-r2-storage.md` - Object storage, S3 compatibility
+- `cloudflare-d1-kv.md` - D1 SQLite, KV store
+- `browser-rendering.md` - Puppeteer automation
+
+### Docker
+- `docker-basics.md` - Dockerfile, images, containers
+- `docker-compose.md` - Multi-container apps
+
+### Google Cloud
+- `gcloud-platform.md` - gcloud CLI, authentication
+- `gcloud-services.md` - Compute Engine, GKE, Cloud Run
+
+### Kubernetes
+- `kubernetes-basics.md` - Core concepts, architecture, workloads
+- `kubernetes-kubectl.md` - Essential commands, debugging workflow
+- `kubernetes-helm.md` / `kubernetes-helm-advanced.md` - Helm charts, templates
+- `kubernetes-security.md` / `kubernetes-security-advanced.md` - RBAC, secrets
+- `kubernetes-workflows.md` / `kubernetes-workflows-advanced.md` - GitOps, CI/CD
+- `kubernetes-troubleshooting.md` / `kubernetes-troubleshooting-advanced.md` - Debug
+
+### Scripts
+- `scripts/cloudflare-deploy.py` - Automate Worker deployments
+- `scripts/docker-optimize.py` - Analyze Dockerfiles
+
+## Best Practices
+
+**Security:** Non-root containers, RBAC, secrets in env vars, image scanning
+**Performance:** Multi-stage builds, edge caching, resource limits
+**Cost:** R2 for large egress, caching, right-size resources
+**Development:** Docker Compose local dev, wrangler dev, version control IaC
+
+## Resources
+
+- Cloudflare: https://developers.cloudflare.com
+- Docker: https://docs.docker.com
+- GCP: https://cloud.google.com/docs
+- Azure: https://learn.microsoft.com/azure/
+- Kubernetes: https://kubernetes.io/docs
+- Helm: https://helm.sh/docs

package/skills/devops/references/kubernetes-basics.md

@@ -0,0 +1,99 @@
+# Kubernetes Core Concepts
+
+## Cluster Architecture
+
+```
+CONTROL PLANE                    WORKER NODES
+├── API Server (kubectl)         ├── Kubelet (node agent)
+├── Scheduler (pod placement)    ├── Kube-proxy (networking)
+├── Controller Manager           └── Container Runtime
+└── etcd (cluster state)
+```
+
+## Pod
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: myapp-pod
+spec:
+  containers:
+  - name: myapp
+    image: myapp:1.0
+    ports:
+    - containerPort: 8080
+    resources:
+      requests: { memory: "256Mi", cpu: "250m" }
+      limits: { memory: "512Mi", cpu: "500m" }
+```
+
+## Deployment
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: myapp
+spec:
+  replicas: 3
+  strategy:
+    type: RollingUpdate
+    rollingUpdate: { maxSurge: 1, maxUnavailable: 0 }
+  selector:
+    matchLabels: { app: myapp }
+  template:
+    metadata:
+      labels: { app: myapp }
+    spec:
+      containers:
+      - name: myapp
+        image: myapp:1.0
+```
+
+## Service
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: myapp-service
+spec:
+  type: ClusterIP  # ClusterIP, NodePort, LoadBalancer
+  selector: { app: myapp }
+  ports:
+  - port: 8080
+    targetPort: 8080
+```
+
+## ConfigMap & Secret
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: app-config
+data:
+  DATABASE_HOST: "postgres.svc.cluster.local"
+---
+apiVersion: v1
+kind: Secret
+type: Opaque
+stringData:
+  password: secretpassword
+```
+
+## Workload Types
+
+| Type | Use Case |
+|------|----------|
+| Deployment | Stateless apps |
+| StatefulSet | Databases |
+| DaemonSet | One per node |
+| Job | Batch tasks |
+| CronJob | Scheduled |
+
+## Labels
+```yaml
+labels:
+  app: myapp
+  version: v1.0.0
+  tier: frontend
+  environment: prod
+```