<p align="center">
  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/shipcheck/readme.jpg" alt="Shipcheck" width="400">
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
  <a href="https://mcp-tool-shop-org.github.io/shipcheck/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
</p>

<p align="center">
  Product standards for MCP Tool Shop.<br>
  Templates, contracts, and adoption guides that define what "done" means before anything ships.
</p>

---

## Why

"Done" used to mean the code works. That's not enough. A product is code + safety + error handling + docs + identity + shipping hygiene. Shipcheck defines the bar.

## What's in here

| Standard | What it covers |
|----------|----------------|
| [Ship Gate](templates/SHIP_GATE.md) | 31 hard-gate + 4 soft-gate pre-release checklist |
| [Error Contract](contracts/error-contract.md) | 2-tier structured error standard with code registry |
| [Security Baseline](templates/SECURITY.md) | Report email, response timeline, threat scope |
| [Handbook](templates/HANDBOOK.md) | Operational field manual for complex tools |
| [Scorecard](templates/SCORECARD.md) | Pre/post remediation scoring |
| [Adoption Guide](ADOPTION.md) | Apply shipcheck to any repo in <30 minutes |

## CLI usage

```bash
npx @mcptoolshop/shipcheck init        # Copy templates into current repo
npx @mcptoolshop/shipcheck audit       # Check SHIP_GATE.md progress
npx @mcptoolshop/shipcheck dogfood     # Check dogfood freshness (Gate F)
npx @mcptoolshop/shipcheck front-door  # Verify the AI-native front door (Gate G)
npx @mcptoolshop/shipcheck help        # Show help
npx @mcptoolshop/shipcheck --version   # Show version
```

Set `SHIPCHECK_JSON=1` to get structured JSON error output instead of coloured text.

## Quick start

1. Read [ADOPTION.md](ADOPTION.md)
2. Run `npx @mcptoolshop/shipcheck init` in your repo root
3. Check off applicable items in `SHIP_GATE.md`, mark non-applicable with `SKIP:`
4. Run `npx @mcptoolshop/shipcheck audit` — exits 0 when all hard gates pass
5. Ship when audit passes

## How it works

**Hard gates** (A-D) block release:

- **A. Security Baseline** — SECURITY.md, threat model, no secrets, no telemetry, default safety posture
- **B. Error Handling** — structured error shape (code/message/hint/retryable), safe output, graceful degradation
- **C. Operator Docs** — README, CHANGELOG, LICENSE, tool documentation
- **D. Shipping Hygiene** — verify script, version alignment, dependency scanning, lockfile

**Soft gate** (E) doesn't block but defines "whole":

- **E. Identity** — logo, translations, landing page, repo metadata

**Gate F — Dogfood Freshness** (optional, requires dogfood-labs):

- Checks for a fresh, verified, passing dogfood record
- Supports enforcement modes: `required`, `warn-only`, `exempt`
- Configurable freshness window (default: 30 days)

**Gate G — AI-native front door** (optional, requires `@mcptoolshop/site-theme` >=2.0.0):

- Verifies that the repo's AI-native front door (README / AGENTS.md / llms.txt) tells the truth — the machine-readable complement to the Operator Docs (C) and Identity (E) gates
- Delegates to site-theme's [`front-door`](https://github.com/mcp-tool-shop-org/site-theme) verifier (`verify({ root })`), which routes documented claims to evidence channels and returns a risk-ordered scorecard
- Surfaces counts by severity (contradicted · unbacked · stale · bloat · hygiene · style) plus the gate verdict; **fails (exit 1) on contradicted / unbacked / stale claims**
- site-theme is an **optional peer dependency** (a hard dep would pull astro into this zero-dep CLI). When it isn't installed, the gate **skips gracefully** (exit 0) — it never crashes the audit

### Executed gates — `audit` counts boxes; these read the artifact

`shipcheck audit` only tallies the checkboxes in `SHIP_GATE.md` — a box can be green while the fact is false. The gates below **execute** the check against the real artifact and exit 1 on the real defect. Each converts a specific Ship Gate line from a human attestation into a machine verification, and each ships with a RED meta-test that mutates the protected thing and proves the gate fires.

- **Gate H — publish surface** (`shipcheck pack`, D5): runs `npm pack --dry-run` on every publishable workspace package; fails if any tarball lacks README/LICENSE, a `files[]` entry doesn't resolve, or `license` is unset.
- **Gate I — secrets** (`shipcheck secrets`, A3): scans every publishable package's tarball surface for high-signal credentials (provider-prefixed keys, tokens, private-key blocks); matches are **redacted**; `shipcheck-allow-secret` whitelists a documented example.
- **Gate J — manifest** (`shipcheck manifest`, D2/D6/D7): every publishable package sets `engines`/`requires-python` (D6); a lockfile is committed (D7); the manifest version is not behind the newest released git tag (D2, `--expect <ver>` for a strict release match).
- **Gate K — security-docs** (`shipcheck security-docs`, A1/A2): SECURITY.md exists with a reporting contact (not an empty stub), and the README states a trust/threat model with a substantive body. Verifies *presence + contact*, not threat-model quality.
- **Gate L — ci** (`shipcheck ci`, provenance + dependency-scan *config*): reads `.github/workflows` — every `npm publish` workflow uses OIDC (`id-token: write`) **and** `--provenance`, and a recognized scanner is configured in CI (or dependabot is present). `--registry <pkg>[@<ver>]` also confirms the published tarball carries a provenance attestation on npm (intent **and** outcome).
- **Gate M — deps** (`shipcheck deps`, the dependency-security *outcome*): runs `npm audit` in **every** lockfile'd tree (root **and** subtrees — a scanner configured only for the root misses the rest), fails on vulnerabilities at/above `--level` (default high), and checks whether GitHub Dependabot **alerts are even enabled**. `ci` proves a scanner is configured; `deps` proves there are no known vulnerabilities — a repo can pass the first and fail the second.

Every gate's `--json` output is pure JSON (no header line), so it pipes cleanly into other tools.

The gate says **what** must be true, not **how** to implement it. Applicability tags (`[all]`, `[npm]`, `[mcp]`, `[cli]`, `[desktop]`, `[vsix]`, `[container]`) prevent checkbox shame on repos where items don't apply.

## Error contract at a glance

**Tier 1 — Shape (mandatory everywhere):**

```json
{
  "code": "INPUT_TEXT_EMPTY",
  "message": "Text must not be empty",
  "hint": "Provide at least one character of text",
  "retryable": false
}
```

**Tier 2 — Base type + exit codes (CLI/MCP/desktop):**

| Exit code | Meaning |
|-----------|---------|
| 0 | OK |
| 1 | User error (bad input, missing config) |
| 2 | Runtime error (crash, backend failure) |
| 3 | Partial success (some items succeeded) |

Error codes use namespaced prefixes: `IO_`, `CONFIG_`, `PERM_`, `DEP_`, `RUNTIME_`, `PARTIAL_`, `INPUT_`, `STATE_`. Codes are stable once released.

## Trust model

**Data touched:** reads `package.json`, `pyproject.toml`, and `SHIP_GATE.md` in the current working directory. Writes template files (`SHIP_GATE.md`, `SECURITY.md`, `CHANGELOG.md`, `SCORECARD.md`) to the current directory only.
**No network requests.** All operations are local file reads and writes.
**No secrets handling.** Does not read, store, or transmit credentials.
**No telemetry** collected or sent.

## Reference implementation

[mcp-voice-soundboard](https://github.com/mcp-tool-shop-org/mcp-voice-soundboard) was the first repo to pass Ship Gate — scoring **46/50** after remediation.

## Scorecard

| Category | Score | Notes |
|----------|-------|-------|
| A. Security | 6/8 | SECURITY.md, trust model, no secrets/telemetry. MCP items skipped (not an MCP server) |
| B. Error Handling | 3/7 | Structured error shape + exit codes + no raw stacks. MCP/desktop/vscode skipped |
| C. Operator Docs | 4/7 | README, CHANGELOG, LICENSE, --help. Logging/MCP/complex skipped |
| D. Shipping Hygiene | 6/9 | verify script, version=tag, npm audit in CI, engines.node, lockfile. Zero deps = no update mechanism |
| E. Identity | 4/4 | Logo, translations, landing page, metadata |
| **Total** | **23/31** | 14 items skipped with justification · `shipcheck audit` passes 100% |

## License

[MIT](LICENSE)

---

<p align="center">
  Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
</p>