@caddis/cli 0.0.0 → 0.1.0

package/bundles/antigravity-plugin/skills/ci-cd-pipeline/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: ci-cd-pipeline
+context: fork
+description: CI/CD pipeline design and implementation for GitHub Actions, Azure DevOps, and general pipeline architecture. Use when creating build pipelines, deployment workflows, quality gates, environment promotion strategies, or automating release processes.
+---
+
+# CI/CD Pipeline Skill
+
+Automate the path from commit to production. Every merge should be deployable.
+
+## 1. When to Apply This Skill
+
+**Trigger conditions:**
+- Setting up CI/CD for a new project
+- "Create a build and deploy pipeline"
+- Adding quality gates to an existing pipeline
+- Designing environment promotion strategy
+- Troubleshooting pipeline failures or slow builds
+
+## 2. Pipeline Architecture
+
+### Standard Flow
+
+```
+Commit → Lint → Test → Build → [Quality Gate] → Deploy Staging → [Approval] → Deploy Production
+```
+
+### Pipeline Stages
+
+| Stage | Purpose | Fail = Block? |
+|-------|---------|--------------|
+| **Lint** | Code style, formatting | Yes |
+| **Type Check** | Static type errors | Yes |
+| **Unit Test** | Logic correctness | Yes |
+| **Integration Test** | Service interactions | Yes |
+| **Build** | Compile, bundle, containerise | Yes |
+| **Security Scan** | Vulnerabilities, secrets | Yes (critical), Warn (medium) |
+| **Deploy Staging** | Validate in staging env | Yes |
+| **Smoke Test** | Basic health check post-deploy | Yes |
+| **Deploy Production** | Ship to users | Manual approval required |
+
+## 3. GitHub Actions — Python Project
+
+```yaml
+name: CI
+context: fork
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[test]"
+      - run: pytest --cov=src --cov-report=xml -q
+      - uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: false
+          tags: app:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+```
+
+## 4. GitHub Actions — Node.js/TypeScript Project
+
+```yaml
+name: CI
+context: fork
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm typecheck
+      - run: pnpm test -- --coverage
+      - run: pnpm build
+```
+
+## 5. Quality Gates
+
+Define pass/fail criteria for each stage.
+
+```yaml
+# quality-gates.yml (reference document)
+gates:
+  lint:
+    ruff_errors: 0
+    format_diff: 0
+  test:
+    min_coverage: 80
+    max_test_duration_seconds: 120
+    allowed_failures: 0
+  security:
+    critical_vulnerabilities: 0
+    high_vulnerabilities: 0
+  build:
+    max_image_size_mb: 500
+    max_build_time_minutes: 10
+  deploy:
+    smoke_test_pass: true
+    health_check_pass: true
+    rollback_on_error_rate: 5  # percent
+```
+
+## 6. Environment Promotion Strategy
+
+```
+Feature Branch → PR Review → Main → Staging → Production
+                    │                   │           │
+                    │                   │           └── Manual approval
+                    │                   └── Auto-deploy on main merge
+                    └── CI runs on every PR
+```
+
+| Environment | Deploy Trigger | Approval | Data |
+|-------------|---------------|----------|------|
+| **Dev** | Every push to branch | None | Synthetic/mock |
+| **Staging** | Merge to main | Automatic | Production-like (anonymised) |
+| **Production** | Tag or manual | Required (2 reviewers) | Real |
+
+## 7. Secrets Management
+
+```yaml
+# ✅ GOOD: Use GitHub Actions secrets
+env:
+  DATABASE_URL: ${{ secrets.DATABASE_URL }}
+  API_KEY: ${{ secrets.API_KEY }}
+
+# ✅ GOOD: Use OIDC for cloud auth (no long-lived credentials)
+- uses: aws-actions/configure-aws-credentials@v4
+  with:
+    role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
+    aws-region: eu-west-1
+
+# ❌ BAD: Hardcoded secrets in workflow
+env:
+  API_KEY: "sk-abc123"  # NEVER DO THIS
+```
+
+**Rules:**
+- Never commit secrets to the repository
+- Use environment-scoped secrets (staging secrets ≠ production secrets)
+- Rotate secrets on a schedule (90 days max)
+- Use OIDC federation over long-lived credentials where possible
+
+## 8. Caching Strategy
+
+```yaml
+# Python pip cache
+- uses: actions/setup-python@v5
+  with:
+    cache: pip
+
+# Node.js pnpm cache
+- uses: actions/setup-node@v4
+  with:
+    cache: pnpm
+
+# Docker layer cache
+- uses: docker/build-push-action@v5
+  with:
+    cache-from: type=gha
+    cache-to: type=gha,mode=max
+
+# Custom cache (e.g., test fixtures)
+- uses: actions/cache@v4
+  with:
+    path: .test-cache
+    key: test-fixtures-${{ hashFiles('tests/fixtures/**') }}
+```
+
+## 9. Pipeline Performance
+
+Keep CI fast. Developers won't wait for slow pipelines.
+
+| Target | Goal |
+|--------|------|
+| Lint + type check | < 2 minutes |
+| Unit tests | < 5 minutes |
+| Full pipeline (PR) | < 15 minutes |
+| Deploy to staging | < 5 minutes |
+
+**Optimisation techniques:**
+- Run lint and test in parallel (separate jobs)
+- Cache dependencies aggressively
+- Use `concurrency` to cancel outdated runs
+- Split slow test suites with `pytest -x --dist=loadgroup`
+- Use Docker layer caching for builds
+
+## 10. Rollback Strategy
+
+| Approach | Speed | Complexity |
+|----------|-------|------------|
+| **Revert commit** | Fast (minutes) | Low — git revert + re-deploy |
+| **Blue-green deploy** | Instant (seconds) | Medium — swap traffic target |
+| **Canary rollback** | Instant | High — requires traffic splitting |
+| **Database rollback** | Slow, risky | High — only if migration is reversible |
+
+**Rule:** Always prefer forward-fix (deploy a fix) over rollback. Rollback is the escape hatch, not the default.
+
+## 11. Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| No CI on PRs | Bugs merge to main | Run full pipeline on every PR |
+| Deploy from local machine | "Works on my machine" | Deploy only from CI/CD |
+| Single mega-job | Slow, hard to debug | Split into parallel stages |
+| No caching | 10-min installs every run | Cache deps, Docker layers |
+| Manual production deploy | Human error, inconsistent | Automated with approval gate |
+| Secrets in code | Compromised on push | Use secrets manager + OIDC |
+| No rollback plan | Broken deploy = downtime | Blue-green or revert strategy |
+| Build passes but output is wrong | Config error baked into assets | Post-build output validation gate (§12) |
+
+## 12. Frontend Build Output Validation
+
+A successful build (exit code 0) does not guarantee correct output. Configuration errors — especially wrong asset path prefixes — produce valid bundles that break at runtime. Add a **post-build validation step** in CI:
+
+### 12.1 Subpath Base-Path Check
+
+When a frontend is deployed under a URL subpath (e.g. `/my-app/`), the built `index.html` must reference assets with that prefix. Vite's `base` config controls this, and it can be accidentally changed.
+
+```yaml
+# GitHub Actions / Gitea Actions example
+jobs:
+  frontend-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+        working-directory: frontend
+      # Build with production mode to activate conditional base path
+      - run: npx vite build --mode production
+        working-directory: frontend
+      - name: Validate production base path
+        working-directory: frontend
+        run: |
+          if ! grep -q '/my-app/assets/' dist/index.html; then
+            echo "FAIL: Built index.html does not reference /my-app/assets/"
+            echo "Check vite.config.ts base setting"
+            exit 1
+          fi
+          echo 'Base-path guard passed'
+```
+
+**Key points:**
+- Build with `--mode production` — without it, mode-conditional `base` stays as `"/"` and the guard always fails
+- This catches the exact scenario where someone changes `base: mode === "production" ? "/my-app/" : "/"` to `base: "/"`
+- The same check should also run in the deploy script as a belt-and-suspenders guard (abort before service restart)
+
+### 12.2 General Output Validation Patterns
+
+| Check | Command | When to use |
+|-------|---------|-------------|
+| Subpath prefix | `grep -q '/{subpath}/assets/' dist/index.html` | Subpath deployments |
+| Non-empty dist | `test -d dist/assets && ls dist/assets/*.js` | Always |
+| Bundle size budget | `du -sh dist/ \| awk '{print $1}'` | When size regressions matter |
+| No source maps in prod | `! ls dist/assets/*.map 2>/dev/null` | Production builds |

package/bundles/antigravity-plugin/skills/code-documentation/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: code-documentation
+description: Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.
+source: wshobson/agents
+license: MIT
+---
+
+# Code Documentation
+
+## Document Metadata
+
+For standalone Markdown docs such as README files, guides, ADRs, and API reference pages, apply `.github/instructions/document-frontmatter.instructions.md` before the first heading.
+
+- **New docs**: add `Original Author`, `Creation Date`, and `Creating Model`.
+- **Updated docs**: preserve the original fields and add or update `Last Author`, `Last Updated`, and `Last Model Used`.
+- Use full ISO 8601 UTC timestamps for `Creation Date` and `Last Updated` values.
+
+## README Structure
+
+### Standard README Template
+```markdown
+# Project Name
+
+Brief description of what this project does.
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+## Installation
+
+Detailed installation instructions...
+
+## Usage
+
+\`\`\`typescript
+import { something } from 'project';
+
+// Example usage
+const result = something.doThing();
+\`\`\`
+
+## API Reference
+
+### `functionName(param: Type): ReturnType`
+
+Description of what the function does.
+
+**Parameters:**
+- `param` - Description of parameter
+
+**Returns:** Description of return value
+
+**Example:**
+\`\`\`typescript
+const result = functionName('value');
+\`\`\`
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `option1` | `string` | `'default'` | What it does |
+
+## Contributing
+
+How to contribute...
+
+## License
+
+MIT
+```
+
+## API Documentation
+
+### JSDoc/TSDoc Style
+```typescript
+/**
+ * Creates a new user account.
+ *
+ * @param userData - The user data for account creation
+ * @param options - Optional configuration
+ * @returns The created user object
+ * @throws {ValidationError} If email is invalid
+ * @example
+ * ```ts
+ * const user = await createUser({
+ *   email: 'user@example.com',
+ *   name: 'John'
+ * });
+ * ```
+ */
+async function createUser(
+  userData: UserInput,
+  options?: CreateOptions
+): Promise<User> {
+  // Implementation
+}
+
+/**
+ * Configuration options for the API client.
+ */
+interface ClientConfig {
+  /** The API base URL */
+  baseUrl: string;
+  /** Request timeout in milliseconds @default 5000 */
+  timeout?: number;
+  /** Custom headers to include in requests */
+  headers?: Record<string, string>;
+}
+```
+
+### OpenAPI/Swagger
+```yaml
+openapi: 3.0.0
+info:
+  title: My API
+  version: 1.0.0
+
+paths:
+  /users:
+    post:
+      summary: Create a user
+      description: Creates a new user account
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserInput'
+      responses:
+        '201':
+          description: User created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        '400':
+          description: Invalid input
+
+components:
+  schemas:
+    UserInput:
+      type: object
+      required:
+        - email
+        - name
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+        name:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+```
+
+## Inline Comments
+
+### When to Comment
+```typescript
+// GOOD: Explain WHY, not WHAT
+
+// Use binary search because the list is always sorted and
+// can contain millions of items - O(log n) vs O(n)
+const index = binarySearch(items, target);
+
+// GOOD: Explain complex business logic
+// Users get 20% discount if they've been members for 2+ years
+// AND have made 10+ purchases (per marketing team decision Q4 2024)
+if (user.memberYears >= 2 && user.purchaseCount >= 10) {
+  applyDiscount(0.2);
+}
+
+// GOOD: Document workarounds
+// HACK: Safari doesn't support this API, fallback to polling
+// TODO: Remove when Safari adds support (tracking: webkit.org/b/12345)
+if (!window.IntersectionObserver) {
+  startPolling();
+}
+```
+
+### When NOT to Comment
+```typescript
+// BAD: Stating the obvious
+// Increment counter by 1
+counter++;
+
+// BAD: Explaining clear code
+// Check if user is admin
+if (user.role === 'admin') { ... }
+
+// BAD: Outdated comments (worse than no comment)
+// Returns the user's full name  <-- Actually returns email now!
+function getUserIdentifier(user) {
+  return user.email;
+}
+```
+
+## Architecture Documentation
+
+### ADR (Architecture Decision Record)
+```markdown
+# ADR-001: Use PostgreSQL for Primary Database
+
+## Status
+Accepted
+
+## Context
+We need a database for storing user data and transactions.
+Options considered: PostgreSQL, MySQL, MongoDB, DynamoDB.
+
+## Decision
+Use PostgreSQL with Supabase hosting.
+
+## Rationale
+- Strong ACID compliance needed for financial data
+- Team has PostgreSQL experience
+- Supabase provides auth and realtime features
+- pgvector extension for future AI features
+
+## Consequences
+- Need to manage schema migrations
+- May need read replicas for scale
+- Team needs to learn Supabase-specific features
+```
+
+### Component Documentation
+```markdown
+## Authentication Module
+
+### Overview
+Handles user authentication using JWT tokens with refresh rotation.
+
+### Flow
+1. User submits credentials to `/auth/login`
+2. Server validates and returns access + refresh tokens
+3. Access token used for API requests (15min expiry)
+4. Refresh token used to get new access token (7d expiry)
+
+### Dependencies
+- `jsonwebtoken` - Token generation/validation
+- `bcrypt` - Password hashing
+- `redis` - Refresh token storage
+
+### Configuration
+- `JWT_SECRET` - Secret for signing tokens
+- `ACCESS_TOKEN_EXPIRY` - Access token lifetime
+- `REFRESH_TOKEN_EXPIRY` - Refresh token lifetime
+```
+
+## Documentation Principles
+
+1. **Write for your audience** - New devs vs API consumers
+2. **Keep it close to code** - Docs in same repo, near relevant code
+3. **Update with code** - Stale docs are worse than none
+4. **Examples over explanations** - Show, don't just tell
+5. **Progressive disclosure** - Quick start first, details later

package/bundles/antigravity-plugin/skills/code-review/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: code-review
+context: fork
+description: Automated code review for pull requests using specialized review patterns. Analyzes code for quality, security, performance, and best practices. Use when reviewing code changes, PRs, or doing code audits.
+source: anthropics/claude-code
+license: Apache-2.0
+---
+
+# Code Review
+
+## Review Categories
+
+### 1. Security Review
+Check for:
+- SQL injection vulnerabilities
+- XSS (Cross-Site Scripting)
+- Command injection
+- Insecure deserialization
+- Hardcoded secrets/credentials
+- Improper authentication/authorization
+- Insecure direct object references
+
+### 2. Performance Review
+Check for:
+- N+1 queries
+- Missing database indexes
+- Unnecessary re-renders (React)
+- Memory leaks
+- Blocking operations in async code
+- Missing caching opportunities
+- Large bundle sizes
+
+### 3. Code Quality Review
+Check for:
+- Code duplication (DRY violations)
+- Functions doing too much (SRP violations)
+- Deep nesting / complex conditionals
+- Magic numbers/strings
+- Poor naming
+- Missing error handling
+- Incomplete type coverage
+
+### 4. Testing Review
+Check for:
+- Missing test coverage for new code
+- Tests that don't test behavior
+- Flaky test patterns
+- Missing edge cases
+- Mocked external dependencies
+
+## Review Output Format
+
+```markdown
+## Code Review Summary
+
+### 🔴 Critical (Must Fix)
+- **[File:Line]** [Issue description]
+  - **Why:** [Explanation]
+  - **Fix:** [Suggested fix]
+
+### 🟡 Suggestions (Should Consider)
+- **[File:Line]** [Issue description]
+  - **Why:** [Explanation]
+  - **Fix:** [Suggested fix]
+
+### 🟢 Nits (Optional)
+- **[File:Line]** [Minor suggestion]
+
+### ✅ What's Good
+- [Positive feedback on good patterns]
+```
+
+## Common Patterns to Flag
+
+### Security
+```javascript
+// BAD: SQL injection
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+
+// GOOD: Parameterized query
+const query = 'SELECT * FROM users WHERE id = $1';
+await db.query(query, [userId]);
+```
+
+### Performance
+```javascript
+// BAD: N+1 query
+users.forEach(async user => {
+  const posts = await getPosts(user.id);
+});
+
+// GOOD: Batch query
+const userIds = users.map(u => u.id);
+const posts = await getPostsForUsers(userIds);
+```
+
+### Error Handling
+```javascript
+// BAD: Swallowing errors
+try {
+  await riskyOperation();
+} catch (e) {}
+
+// GOOD: Handle or propagate
+try {
+  await riskyOperation();
+} catch (e) {
+  logger.error('Operation failed', { error: e });
+  throw new AppError('Operation failed', { cause: e });
+}
+```
+
+## Review Checklist
+
+- [ ] No hardcoded secrets
+- [ ] Input validation present
+- [ ] Error handling complete
+- [ ] Types/interfaces defined
+- [ ] Tests added for new code
+- [ ] No obvious performance issues
+- [ ] Code is readable and documented
+- [ ] Breaking changes documented