# Ship

[![npm version](https://img.shields.io/npm/v/@telelabsai/ship.svg)](https://www.npmjs.com/package/@telelabsai/ship)
[![license](https://img.shields.io/npm/l/@telelabsai/ship.svg)](https://github.com/telelabs-ai/ship/blob/main/LICENSE)

**Ship helps you go from code to production.** A complete AI engineering toolkit with specialized agents that plan your architecture, design your interfaces, build your features, write and run your tests, audit security, review code quality, manage releases, and deploy to production. One CLI, every stage of the development lifecycle.

## Installation

```bash
npm install -g @telelabsai/ship
```

Requires [Node.js](https://nodejs.org) 18+ and [Claude Code](https://claude.ai/code).

## Quick Start

```bash
# Add Ship to any project
ship init

# Or start fresh
ship new my-app

# Start using it
ship version commit --ticket PROJ-42 "add user auth"
```

## Commands

### Project Setup

```bash
ship init                       # Add Ship to current directory
ship init --dir ./my-app        # Add Ship to specific directory
ship new <name>                 # Create new project with Ship config
ship update                     # Update to latest Ship version
ship update --force             # Update without asking
```

### Git Version Control

```bash
# Commit
ship version commit                              # auto-detect type + scope
ship version commit "add login page"             # custom message
ship version commit --type fix "null check"      # explicit type
ship version commit --ticket PROJ-42 "user auth" # with ticket ref

# Diff
ship version diff                                # working tree changes
ship version diff --staged                       # staged only
ship version diff --pr                           # preview PR diff
ship version diff v1.0.0..v2.0.0                # between tags

# Changelog
ship version changelog                           # auto-generate from tags
ship version changelog v1.0.0 v2.0.0            # specific range

# Push / PR / Branch
ship version push                                # push to remote safely
ship version pr --ticket PROJ-42 "Add auth"     # create pull request
ship version branch feature/user-auth            # create + switch
```

### Code Review

```bash
ship review                     # review uncommitted changes
ship review --pr                # review current PR diff
ship review --full              # review entire codebase
ship review --focus security    # focus on one category
ship review --ci                # CI mode (structured output, exit code)
```

Reviews 11 categories: logic, performance, database, security, API contracts, error handling, types, payments, webhooks, integrations, naming.

### Test Analysis

```bash
ship test                       # run tests + analyze results
ship test --coverage            # coverage report only
ship test --missing             # find untested code paths
ship test --ci                  # CI mode
```

Auto-detects your test framework (Jest, Vitest, Mocha, Pytest, Go, Rust). Analyzes failures, coverage gaps, weak assertions, and flaky patterns.

### Security Scanning

```bash
ship secure                     # full security scan
ship secure --deps              # dependency vulnerabilities only
ship secure --vulns             # vulnerability analysis only
ship secure --secrets           # secret detection only
ship secure --ci                # CI mode
```

Scans for OWASP vulnerabilities, dependency CVEs, hardcoded secrets (AWS, Stripe, OpenAI, GitHub, etc.), exposed endpoints, webhook/payment security, and infrastructure misconfigurations.

### Coming Soon

```bash
ship plan "add auth"            # Implementation planning
ship deploy staging             # Deployment workflows
ship fix "login bug"            # Structured bug fixing
ship docs                       # Documentation management
```

## Ticket Tracking

Works with any project management tool:

| Tool          | Example               |
| ------------- | --------------------- |
| Jira          | `--ticket PROJ-123`   |
| ClickUp       | `--ticket CU-abc123`  |
| Linear        | `--ticket ENG-123`    |
| GitHub Issues | `--ticket #42`        |
| Trello        | `--ticket #abc123`    |
| Shortcut      | `--ticket sc-12345`   |
| Asana         | `--ticket 1234567890` |
| Custom        | `--ticket ANYTHING`   |

Multiple tickets: `--ticket PROJ-42 --ticket #15`

## Commit Format

```
type(scope): description

[optional body]

Refs: TICKET-ID
```

Types: `feat` | `fix` | `refactor` | `test` | `docs` | `chore` | `perf` | `style` | `ci` | `build`

## Safety Guardrails

Four layers of protection, from coding to production:

| Layer | When | What it does |
|-------|------|-------------|
| **Rules** | Every Claude message | Reminds Claude to follow secure coding practices |
| **Claude hooks** | When Claude runs git commands | Blocks staging .env, force push, `git add .` |
| **Git pre-commit hook** | When anyone commits | Scans staged file contents for secrets (API keys, DB URLs, private keys) |
| **ship-secure skill** | On demand or CI | Full codebase security scan |

### Automatic blocks (can't be bypassed):

| Guardrail | What it prevents |
|-----------|-----------------|
| Secret content scan | Blocks committing files containing API keys, tokens, passwords, DB URLs, private keys |
| Sensitive file block | Blocks staging `.env`, `.pem`, `.key`, `credentials.json`, `id_rsa`, etc. |
| Force push block | Prevents `git push --force` |
| Blind staging block | Prevents `git add .` / `git add -A` |
| Hard reset block | Prevents `git reset --hard` without confirmation |
| Branch protection | Prevents deleting main/master/production |

Secret patterns are defined in one place (`.claude/shared/secret-patterns.json`). Add a new pattern once, all layers pick it up.

## How It Works

Ship is powered by [Claude Code](https://claude.ai/code). Every `ship <command>` delegates to an AI skill that understands your codebase.

```
ship <skill> [args]  →  claude -p "/ship-<skill> [args]"
```

You can also use skills directly inside Claude Code:

```bash
claude
/ship-version commit --ticket PROJ-42 "add auth"
/ship-review --pr
/ship-test --coverage
/ship-secure
```

### Architecture

| Component | Count | Purpose |
|-----------|-------|---------|
| **Skills** | 4 | Workflows (version, review, test, secure) |
| **Agents** | 2 | Isolated AI workers (git-ops, reviewer) |
| **Rules** | 3 | Always-on conventions (git, code quality, security) |
| **Hooks** | 1 | Claude Code guardrails (git-safety) |
| **Git hooks** | 1 | Pre-commit secret scanner |
| **Shared** | 1 | Secret patterns (single source of truth) |

### CI/CD Integration

```yaml
# .github/workflows/ship.yml
- name: Ship Review
  run: ship review --ci
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

- name: Ship Security
  run: ship secure --ci

- name: Ship Test
  run: ship test --ci
```

## Roadmap

| Status | Skill | Description |
|--------|-------|-------------|
| Available | `ship-version` | Git version control, conventional commits, ticket tracking |
| Available | `ship-review` | AI code review (11 categories including payments, webhooks, DB) |
| Available | `ship-test` | Test analysis with coverage, untested paths, quality assessment |
| Available | `ship-secure` | Security scan (OWASP, CVEs, secrets, endpoints, webhooks) |
| Planned | `ship-plan` | AI-powered implementation planning |
| Planned | `ship-deploy` | Deployment workflows |
| Planned | `ship-fix` | Structured bug fixing |
| Planned | `ship-docs` | Documentation management |

## Links

- **Website:** [telelabs.ai](https://telelabs.ai)
- **Email:** [tele@telelabs.ai](mailto:tele@telelabs.ai)
- **LinkedIn:** [linkedin.com/company/telelabsai](https://linkedin.com/company/telelabsai)
- **Issues:** [github.com/telelabs-ai/ship/issues](https://github.com/telelabs-ai/ship/issues)

## License

MIT — [TeleLabs AI](https://telelabs.ai)