@telelabsai/ship 1.1.2 → 1.1.4

package/.claude/agents/reviewer.md

@@ -0,0 +1,47 @@
+---
+name: reviewer
+description: "Use this agent for code review, test analysis, and security scanning. Handles large diffs and verbose output in isolated context. Spawns for ship-review, ship-test, and ship-secure skills."
+model: sonnet
+tools: Bash, Read, Glob, Grep, Edit
+---
+
+You are a senior code reviewer, test analyst, and security auditor. You analyze codebases with precision and report findings concisely.
+
+Activate the relevant skill by reading its SKILL.md and references:
+- Code review: `.claude/skills/ship-review/SKILL.md`
+- Test analysis: `.claude/skills/ship-test/SKILL.md`
+- Security scan: `.claude/skills/ship-secure/SKILL.md`
+
+## Core Principles
+
+- Never report false positives. If unsure, mark as "Needs verification"
+- Always include file path and line number for every finding
+- Prioritize findings by impact, not alphabetically
+- Explain WHY something is a problem, not just WHAT
+- Suggest a fix for every finding
+- Respect the codebase's existing patterns before suggesting changes
+
+## Severity Levels
+
+| Level | Meaning | CI behavior |
+|-------|---------|-------------|
+| Critical | Must fix. Security holes, data loss, broken logic | Blocks merge |
+| Warning | Should fix. Performance, error handling, testing gaps | Warns |
+| Suggestion | Nice to have. Naming, style, minor improvements | Info only |
+
+## Output Format
+
+Always end with a structured summary:
+
+```
+Files reviewed: N
+Critical: N | Warning: N | Suggestion: N
+Verdict: PASS or FAIL (FAIL if any critical)
+```
+
+## CI Mode
+
+When `--ci` flag is present:
+- Output only the structured report (no conversational text)
+- Exit with status in verdict (PASS/FAIL)
+- Format output as markdown suitable for PR comments

package/.claude/hooks/git-safety.cjs

@@ -1,20 +1,25 @@
 /**
  * PreToolUse hook — blocks dangerous git operations before they execute.
+ * Reads secret patterns from shared/secret-patterns.json (single source of truth).
  *
  * Exit 0 = allow the tool call
  * Exit 2 = block the tool call (stdout = reason shown to Claude)
  */
 
 const fs = require('fs');
+const path = require('path');
 
 let input;
 try {
   input = JSON.parse(fs.readFileSync('/dev/stdin', 'utf8'));
 } catch {
-  process.exit(0); // can't parse → allow
+  process.exit(0);
 }
 
 const cmd = (input.tool_input && input.tool_input.command) || '';
+const patterns = JSON.parse(
+  fs.readFileSync(path.join(__dirname, '..', 'shared', 'secret-patterns.json'), 'utf8')
+);
 
 // --- Block force push ---
 if (/push\s+.*(-f|--force)(?!\S)/.test(cmd) && !cmd.includes('--force-with-lease')) {
@@ -22,36 +27,23 @@ if (/push\s+.*(-f|--force)(?!\S)/.test(cmd) && !cmd.includes('--force-with-lease
   process.exit(2);
 }
 
-// --- Block push to protected branches without confirmation ---
-const protectedPush = /push\s+.*\b(main|master|production|prod)\b/.test(cmd);
-if (protectedPush && !cmd.includes('--force-with-lease')) {
-  // Allow regular push to main, but block force variants
-  // The rule file handles the "ask user" part for regular pushes
-}
-
 // --- Block staging sensitive files ---
-const sensitivePatterns = [
-  /git\s+add\s+.*\.env(?!\.\w*example)/,
-  /git\s+add\s+.*credentials/,
-  /git\s+add\s+.*\.pem/,
-  /git\s+add\s+.*\.key/,
-  /git\s+add\s+.*secrets?\./,
-];
-
-for (const pattern of sensitivePatterns) {
-  if (pattern.test(cmd)) {
-    console.log('BLOCKED: Cannot stage sensitive files (.env, credentials, keys). Add to .gitignore instead.');
+for (const file of patterns.dangerousFiles) {
+  const escaped = file.replace(/\./g, '\\.').replace(/\*/g, '[^\\s]*');
+  const regex = new RegExp(`git\\s+add\\s+.*${escaped}`);
+  if (regex.test(cmd)) {
+    console.log(`BLOCKED: Cannot stage sensitive file matching "${file}". Add to .gitignore instead.`);
     process.exit(2);
   }
 }
 
-// --- Block git add -A / git add . (encourage specific staging) ---
+// --- Block git add -A / git add . ---
 if (/git\s+add\s+(-A|--all|\.)(\s|$)/.test(cmd)) {
-  console.log('BLOCKED: Use specific file names instead of "git add ." or "git add -A" to avoid staging secrets or unwanted files.');
+  console.log('BLOCKED: Use specific file names instead of "git add ." or "git add -A" to avoid staging secrets.');
   process.exit(2);
 }
 
-// --- Block destructive resets without warning ---
+// --- Block destructive resets ---
 if (/git\s+reset\s+--hard/.test(cmd)) {
   console.log('BLOCKED: "git reset --hard" discards all uncommitted changes. Ask the user to confirm first.');
   process.exit(2);

package/.claude/rules/code-quality.md

@@ -0,0 +1,15 @@
+# Code Quality
+
+Quick reminders (detailed checks in `.claude/skills/ship-review/references/review-categories.md`):
+
+- No N+1 queries, missing indexes, or unbounded queries
+- No race conditions in async code
+- No memory leaks (uncleaned listeners, intervals, subscriptions)
+- Validate error handling on all external calls (APIs, DB, file I/O)
+- Consistent API response format across endpoints
+- No nested loops over large datasets without justification
+- Use caching on repeated expensive operations
+- Validate input at system boundaries
+- Use idempotency keys on payment operations
+- Validate webhook signatures on incoming webhooks
+- Use circuit breakers and timeouts on third-party API calls

package/.claude/rules/security.md

@@ -0,0 +1,10 @@
+# Security
+
+- Never hardcode secrets, API keys, passwords, or tokens in source code
+- Never use string concatenation in SQL/NoSQL queries (use parameterized queries)
+- Never trust user input (validate and sanitize at all entry points)
+- Ensure all endpoints have authentication and authorization checks
+- Ensure sensitive data is not logged (passwords, tokens, PII)
+- Ensure cookies use httpOnly, secure, and sameSite flags
+- Ensure JWT tokens have expiration
+- Secret patterns defined in .claude/shared/secret-patterns.json

package/.claude/shared/secret-patterns.json

@@ -0,0 +1,62 @@
+{
+  "description": "Single source of truth for secret detection. Used by hooks, skills, and git hooks.",
+
+  "apiKeys": [
+    { "name": "AWS Access Key", "pattern": "AKIA[0-9A-Z]{16}", "severity": "critical" },
+    { "name": "OpenAI API Key", "pattern": "sk-[a-zA-Z0-9]{48}", "severity": "critical" },
+    { "name": "Anthropic API Key", "pattern": "sk-ant-[a-zA-Z0-9-]{90,}", "severity": "critical" },
+    { "name": "GitHub Token (PAT)", "pattern": "ghp_[a-zA-Z0-9]{36}", "severity": "critical" },
+    { "name": "GitHub OAuth Token", "pattern": "gho_[a-zA-Z0-9]{36}", "severity": "critical" },
+    { "name": "GitLab Token", "pattern": "glpat-[a-zA-Z0-9-]{20}", "severity": "critical" },
+    { "name": "Slack Bot Token", "pattern": "xoxb-[0-9]{10,}-[a-zA-Z0-9]{24}", "severity": "critical" },
+    { "name": "Slack User Token", "pattern": "xoxp-[0-9]{10,}-[a-zA-Z0-9]{24}", "severity": "critical" },
+    { "name": "SendGrid API Key", "pattern": "SG\\.[a-zA-Z0-9_-]{22}\\.[a-zA-Z0-9_-]{43}", "severity": "critical" },
+    { "name": "Stripe Secret Key", "pattern": "sk_live_[a-zA-Z0-9]{24,}", "severity": "critical" },
+    { "name": "Stripe Restricted Key", "pattern": "rk_live_[a-zA-Z0-9]{24,}", "severity": "critical" },
+    { "name": "Square Access Token", "pattern": "sq0atp-[a-zA-Z0-9_-]{22}", "severity": "critical" },
+    { "name": "Google API Key", "pattern": "AIza[0-9A-Za-z_-]{35}", "severity": "critical" },
+    { "name": "Twilio API Key", "pattern": "SK[a-f0-9]{32}", "severity": "critical" },
+    { "name": "Mailgun API Key", "pattern": "key-[a-zA-Z0-9]{32}", "severity": "critical" }
+  ],
+
+  "credentials": [
+    { "name": "Hardcoded password", "pattern": "password\\s*[:=]\\s*['\"][^'\"]{4,}['\"]", "severity": "critical" },
+    { "name": "Hardcoded secret", "pattern": "secret\\s*[:=]\\s*['\"][^'\"]{4,}['\"]", "severity": "critical" },
+    { "name": "Hardcoded API key", "pattern": "api[_-]?key\\s*[:=]\\s*['\"][^'\"]{4,}['\"]", "severity": "critical" },
+    { "name": "Hardcoded token", "pattern": "auth[_-]?token\\s*[:=]\\s*['\"][^'\"]{4,}['\"]", "severity": "critical" },
+    { "name": "OAuth client secret", "pattern": "client[_-]?secret\\s*[:=]\\s*['\"][^'\"]{4,}['\"]", "severity": "critical" }
+  ],
+
+  "databaseUrls": [
+    { "name": "MongoDB connection string", "pattern": "mongodb(\\+srv)?://[^/\\s]{8,}", "severity": "critical" },
+    { "name": "PostgreSQL connection string", "pattern": "postgres(ql)?://[^/\\s]{8,}", "severity": "critical" },
+    { "name": "MySQL connection string", "pattern": "mysql://[^/\\s]{8,}", "severity": "critical" },
+    { "name": "Redis connection string", "pattern": "redis://[^/\\s]{8,}", "severity": "critical" },
+    { "name": "RabbitMQ connection string", "pattern": "amqp://[^/\\s]{8,}", "severity": "critical" }
+  ],
+
+  "privateKeys": [
+    { "name": "RSA/EC/DSA Private Key", "pattern": "-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----", "severity": "critical" },
+    { "name": "PGP Private Key", "pattern": "-----BEGIN PGP PRIVATE KEY BLOCK-----", "severity": "critical" }
+  ],
+
+  "dangerousFiles": [
+    ".env", ".env.local", ".env.production", ".env.staging", ".env.development",
+    "*.pem", "*.key", "*.p12", "*.pfx",
+    "credentials.json", "secrets.json", "service-account.json",
+    "id_rsa", "id_ed25519", "id_ecdsa",
+    ".npmrc", ".netrc", ".htpasswd"
+  ],
+
+  "falsePositives": [
+    "process.env.",
+    "os.environ",
+    "ENV[",
+    "<PLACEHOLDER>",
+    "YOUR_KEY_HERE",
+    "xxx",
+    "changeme",
+    ".env.example",
+    ".env.template"
+  ]
+}

package/.claude/skills/ship-review/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ship-review
+description: "AI code review. Analyzes code changes for logic errors, performance issues, database problems, security flaws, API contract violations, and more. Works on PRs, uncommitted changes, or full codebase."
+argument-hint: "[--pr] [--full] [--focus CATEGORY] [--ci]"
+---
+
+# ship-review — AI Code Review
+
+## Usage
+
+```
+ship review                    # review uncommitted changes
+ship review --pr               # review current PR diff against main
+ship review --full             # review entire codebase
+ship review --focus security   # focus on one category
+ship review --focus perf       # focus on performance
+ship review --ci               # CI mode (structured output, exit code)
+```
+
+## Modes
+
+| Flag | Scope | Use when |
+|------|-------|----------|
+| (none) | Uncommitted changes | Before committing |
+| `--pr` | PR diff (main..HEAD) | Before merging |
+| `--full` | Entire codebase | Periodic audit |
+| `--focus X` | Single category | Deep dive |
+| `--ci` | Same as --pr, structured output | GitHub Actions |
+
+## Workflow
+
+### Step 1: Gather Changes
+
+Based on mode, collect the code to review:
+
+**Default (uncommitted):**
+```bash
+git diff --name-only
+git diff
+```
+
+**PR mode:**
+```bash
+git log main..HEAD --oneline
+git diff main..HEAD --name-only
+git diff main..HEAD
+```
+
+**Full mode:**
+```bash
+# Read all source files (exclude node_modules, .git, dist, build)
+```
+
+### Step 2: Analyze
+
+Read each changed file. For every file, check all categories from `references/review-categories.md`.
+
+Use the `reviewer` agent for large diffs to keep main context clean.
+
+### Step 3: Classify Findings
+
+Assign severity per `references/severity-levels.md`.
+
+### Step 4: Report
+
+Output per `references/output-format.md`.
+
+## Quick Reference
+
+| Reference | Content |
+|-----------|---------|
+| `references/review-categories.md` | All review categories and what to check |
+| `references/severity-levels.md` | How to classify findings |
+| `references/output-format.md` | Report structure |

package/.claude/skills/ship-review/references/output-format.md

@@ -0,0 +1,62 @@
+# Output Format
+
+## Standard Report
+
+```markdown
+## Ship Review
+
+### Critical
+- [category] file/path.ts:LINE — Description of the issue
+  Fix: How to fix it
+
+### Warning
+- [category] file/path.ts:LINE — Description of the issue
+  Fix: How to fix it
+
+### Suggestion
+- [category] file/path.ts:LINE — Description of the issue
+  Fix: How to fix it
+
+### Summary
+Files reviewed: N
+Critical: N | Warning: N | Suggestion: N
+Verdict: PASS or FAIL
+```
+
+## Rules
+
+- Group findings by severity (Critical first, then Warning, then Suggestion)
+- Within each severity, order by impact (most impactful first)
+- Include file path and line number for every finding
+- Include category tag in brackets: [logic], [security], [performance], [database], [api], [error], [types], [payments], [webhooks], [integrations], [naming]
+- Include a one-line fix suggestion for every finding
+- If no findings at a severity level, omit that section
+- Verdict is FAIL if any critical findings exist, PASS otherwise
+- Keep descriptions concise (one line per finding, fix on next line)
+- If same pattern appears in multiple files, group: "[performance] N+1 query pattern in 4 files: list..."
+
+## CI Mode
+
+Same format but:
+- No conversational text before or after the report
+- Just the markdown report
+- Suitable for posting as a PR comment via `gh pr comment`
+
+## Focus Mode
+
+When `--focus CATEGORY` is used:
+- Only report findings in that category
+- Still use same format and severity levels
+- Add a note at top: "Focused review: [category] only"
+
+## No Issues Found
+
+```markdown
+## Ship Review
+
+No issues found.
+
+Files reviewed: N
+Critical: 0 | Warning: 0 | Suggestion: 0
+Verdict: PASS
+```

package/.claude/skills/ship-review/references/review-categories.md

@@ -0,0 +1,169 @@
+# Review Categories
+
+## Logic
+
+Check for:
+- Off-by-one errors in loops and array access
+- Null/undefined paths not handled
+- Race conditions in async code (parallel mutations, shared state)
+- Infinite loops or unbounded recursion
+- Wrong comparison operators (== vs ===, > vs >=)
+- Inverted boolean logic (! in wrong place)
+- Dead code paths that can never execute
+- Missing return statements in branching logic
+- Incorrect type coercion
+- Switch/case without break or default
+
+## Performance
+
+Check for:
+- N+1 database queries (loop with individual queries)
+- Nested loops creating O(n^2) or worse complexity
+- Unnecessary re-renders in React/frontend frameworks
+- Memory leaks (event listeners not cleaned, intervals not cleared)
+- Blocking calls in async contexts (sync file I/O, CPU-heavy in event loop)
+- Missing pagination on large dataset queries
+- Large payloads without streaming or compression
+- Redundant computations that should be memoized or cached
+- Missing cache headers on API responses
+- No caching strategy for repeated expensive operations
+- Stale cache without invalidation
+- Loading entire collections when filtering would suffice
+- Missing debounce/throttle on frequent events
+- Unnecessary deep cloning of large objects
+
+## Database
+
+Check for:
+- Missing indexes on columns used in WHERE, JOIN, ORDER BY
+- SELECT * instead of specific columns
+- No LIMIT on queries that could return large result sets
+- Missing transactions on multi-step operations
+- Unsafe migrations (dropping columns with data, renaming without backfill)
+- No rollback/down migration defined
+- Raw SQL with string concatenation (SQL injection risk)
+- Missing connection pooling configuration
+- No timeout on database queries
+- Deadlock potential (acquiring locks in inconsistent order)
+- Missing unique constraints where data should be unique
+- No foreign key constraints on relationships
+- Schema changes without data migration plan
+- Missing created_at/updated_at timestamps
+- No soft delete strategy when data retention matters
+
+## Security
+
+Check for:
+- SQL injection (string interpolation in queries)
+- XSS (unescaped user input in HTML/templates)
+- Command injection (user input in shell commands)
+- Hardcoded secrets, API keys, passwords
+- Missing authentication on endpoints
+- Missing authorization checks (user can access others' data)
+- CSRF vulnerability (no token on state-changing requests)
+- Insecure direct object references (sequential IDs in URLs)
+- Path traversal (user input in file paths)
+- Missing input validation and sanitization
+- Passwords stored in plain text
+- Sensitive data in logs
+- Missing rate limiting on authentication endpoints
+- JWT without expiration
+- Insecure cookie settings (missing httpOnly, secure, sameSite)
+
+## API Contracts
+
+Check for:
+- Inconsistent response format across endpoints
+- Breaking changes to existing API (removed/renamed fields)
+- Missing input validation on request body/params
+- No error response standardization
+- Missing HTTP status codes (always 200, even on error)
+- Undocumented endpoints or parameters
+- Missing Content-Type headers
+- No request size limits
+- Exposing internal errors/stack traces to clients
+- Missing versioning strategy on breaking changes
+- Inconsistent naming (camelCase vs snake_case in responses)
+
+## Error Handling
+
+Check for:
+- Empty catch blocks (swallowed errors)
+- Catch-all without specific error handling
+- Unhandled promise rejections
+- Missing error boundaries in UI frameworks
+- Silent failures with no logging or user feedback
+- Rethrowing errors without context
+- Missing try/catch around external service calls
+- No fallback for failed network requests
+- Missing timeout handling on HTTP calls
+- Error messages exposing implementation details
+
+## Types
+
+Check for:
+- Type mismatches (string where number expected)
+- Unsafe type casting (as any, type assertions)
+- Missing null/undefined checks before property access
+- Implicit any in TypeScript
+- Wrong generic types
+- Missing discriminated union checks
+- Optional chaining hiding real bugs (?. masking null that shouldn't be null)
+
+## Payments and Financial Operations
+
+Check for:
+- Missing idempotency key on payment/charge operations (double charge risk)
+- Race condition on balance operations (concurrent debits can overdraw)
+- No transaction wrapping on money operations (partial updates corrupt state)
+- Trusting client-sent prices or amounts (price manipulation attack)
+- Negative amounts not blocked (reverse charge exploit)
+- Currency rounding errors (use integer cents, not floating point dollars)
+- Missing reconciliation between payment provider and local DB
+- No audit trail on financial operations (who charged what, when)
+- Missing refund limits or cooldown period
+- Balance check and debit not atomic (check-then-act race condition)
+- No queue/lock for sequential financial operations on same account
+- Missing retry handling with idempotency for failed payment calls
+
+## Webhooks
+
+Check for:
+- No signature validation on incoming webhooks (Stripe, PayPal, etc.)
+- Webhook secret hardcoded instead of environment variable
+- No replay protection (same event processed multiple times)
+- No idempotency on webhook handlers (duplicate events cause duplicate actions)
+- Missing event type validation (processing unknown event types)
+- No timeout on webhook processing (blocking the webhook provider)
+- Webhook endpoint exposed without IP allowlisting or signature check
+- Missing error handling that could lose webhook events
+- No dead letter queue for failed webhook processing
+- Returning 200 before processing completes (losing events on crash)
+
+## Integrations (Third-Party APIs)
+
+Check for:
+- No timeout on external HTTP calls (hangs indefinitely)
+- No circuit breaker (one failing service cascades to entire app)
+- No retry with exponential backoff on transient failures
+- Trusting external API response data without validation
+- Missing error handling when integration is down
+- No fallback or graceful degradation when dependency fails
+- Sensitive data sent to third parties unnecessarily
+- API keys for integrations hardcoded (use env vars)
+- No request/response logging for debugging integration issues
+- Missing rate limit handling on outbound API calls (429 responses)
+- No health check for critical integration dependencies
+
+## Naming and Readability
+
+Check for:
+- Single-letter variables outside loop counters
+- Misleading function/variable names
+- Inconsistent naming conventions within the file
+- Functions doing more than one thing (god functions)
+- Deep nesting (>3 levels)
+- Files over 300 lines
+- Magic numbers without named constants
+- Boolean parameters without named arguments
+- Commented-out code blocks

package/.claude/skills/ship-review/references/severity-levels.md

@@ -0,0 +1,49 @@
+# Severity Levels
+
+## Critical
+
+Blocks merge in CI. Must fix before shipping.
+
+Assign critical when:
+- Security vulnerability exploitable in production
+- Data loss or corruption possible
+- Logic error that produces wrong results
+- Breaking change to public API without migration
+- Authentication/authorization bypass
+- Race condition that causes data inconsistency
+- Migration that destroys existing data
+
+## Warning
+
+Should fix. Flagged but doesn't block merge.
+
+Assign warning when:
+- Performance issue that degrades user experience
+- Missing error handling that could cause silent failures
+- Database query without index on large table
+- Missing test coverage on critical path
+- N+1 query pattern
+- Missing input validation (non-security context)
+- Cache strategy missing on hot path
+- Inconsistent API response format
+
+## Suggestion
+
+Nice to have. Informational.
+
+Assign suggestion when:
+- Naming could be clearer
+- Code could be simplified
+- Minor style inconsistency
+- Opportunity to extract reusable function
+- Comment would help future readers
+- Test could cover additional edge case
+
+## Rules
+
+- When in doubt between two levels, pick the higher one
+- Never mark a security issue below Warning
+- Never mark data loss risk below Critical
+- If a finding is in dead/unreachable code, downgrade by one level
+- If a finding is in test code only, downgrade by one level
+- Group related findings (don't report same pattern 10 times)

package/.claude/skills/ship-secure/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: ship-secure
+description: "AI security scanner. Scans entire codebase for vulnerabilities, dependency CVEs, hardcoded secrets, exposed endpoints, webhook/payment security, and infrastructure misconfigurations."
+argument-hint: "[--deps] [--vulns] [--secrets] [--ci]"
+---
+
+# ship-secure — AI Security Scanner
+
+## Usage
+
+```
+ship secure                # full security scan
+ship secure --deps         # dependency vulnerabilities only
+ship secure --vulns        # vulnerability analysis only (OWASP, endpoints, webhooks, payments)
+ship secure --secrets      # secret detection only
+ship secure --ci           # CI mode (structured output, exit code)
+```
+
+## Difference from ship-review
+
+- **ship-review** checks your code CHANGES (PR diff) for security issues
+- **ship-secure** scans the ENTIRE CODEBASE regardless of what changed
+
+Run `ship-review` on every PR. Run `ship-secure` weekly or before releases.
+
+## Workflow
+
+### Step 1: Dependency Audit
+
+```bash
+npm audit 2>/dev/null || true
+```
+
+Also read `package.json` / `package-lock.json` / `requirements.txt` / `go.mod` and check for known vulnerable versions.
+
+Reference: `references/dependency-audit.md`
+
+### Step 2: Secret Detection
+
+Scan all source files for hardcoded secrets.
+
+Reference: `references/secret-patterns.md`
+
+### Step 3: Vulnerability Analysis
+
+Read source code and check for OWASP categories, exposed endpoints, webhook/payment security, and infrastructure misconfigurations.
+
+Reference: `references/owasp-checks.md`
+
+### Step 4: Report
+
+Output structured report with severity levels.
+
+## Quick Reference
+
+| Reference | Content |
+|-----------|---------|
+| `references/owasp-checks.md` | Vulnerability checks with code patterns |
+| `references/dependency-audit.md` | Dependency vulnerability detection |
+| `references/secret-patterns.md` | Secret and credential detection patterns |