@mcptoolshop/shipcheck 1.0.0

package/contracts/error-contract.md

@@ -0,0 +1,234 @@
+# Error Contract
+
+Structured errors across all MCP Tool Shop products.
+
+Two tiers: the **shape** is mandatory everywhere, the **base type** is optional for larger projects.
+
+---
+
+## Tier 1: Structured Error Shape (mandatory)
+
+Every user-facing error — whether thrown, returned, or printed — must carry these fields:
+
+| Field | Type | Required | Purpose |
+|-------|------|----------|---------|
+| `code` | string | yes | Machine-readable, namespaced (see registry rules below) |
+| `message` | string | yes | What went wrong |
+| `hint` | string | yes | What the user should do about it |
+| `cause` | string/error | no | Original error, for chaining |
+| `retryable` | boolean | no | Can the caller safely retry? |
+
+**Simple scripts** don't need a class. Just emit the shape:
+
+```json
+{
+  "code": "IO_READ_FAILED",
+  "message": "Could not read config.json",
+  "hint": "Check file permissions or run with --debug",
+  "retryable": false
+}
+```
+
+```python
+# Minimal: return a dict
+{"code": "IO_READ_FAILED", "message": str(e), "hint": "Check file permissions"}
+```
+
+The contract is the shape, not the implementation.
+
+---
+
+## Tier 2: Base Error Type + Exit Codes (CLI / MCP / Desktop)
+
+For repos with a CLI, MCP server, or desktop UI — formalize the shape into a typed error class with two output modes.
+
+### Output modes
+
+| Mode | Audience | Stack traces? | When |
+|------|----------|---------------|------|
+| **safe** | End users, LLMs, MCP | Never | Default |
+| **debug** | Developers | Yes, if available | `--debug` flag |
+
+### Exit codes (CLI only)
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | User error (bad input, missing args, invalid config) |
+| 2 | Runtime error (crash, IO failure, dependency missing) |
+| 3 | Partial success (some items ok, some failed) |
+
+### TypeScript reference
+
+```typescript
+export class ProductError extends Error {
+  readonly code: string;
+  readonly hint: string;
+  readonly cause?: Error;
+  readonly retryable: boolean;
+
+  constructor(
+    code: string,
+    message: string,
+    hint: string,
+    opts?: { cause?: Error; retryable?: boolean },
+  ) {
+    super(message);
+    this.name = 'ProductError'; // rename per-product
+    this.code = code;
+    this.hint = hint;
+    this.cause = opts?.cause;
+    this.retryable = opts?.retryable ?? false;
+  }
+
+  /** Safe output — no stack traces. For MCP responses + UI. */
+  toSafeText(): string {
+    const lines = [
+      `Error [${this.code}]: ${this.message}`,
+      `Hint: ${this.hint}`,
+    ];
+    if (this.cause) lines.push(`Cause: ${this.cause.message}`);
+    return lines.join('\n');
+  }
+
+  /** Debug output — includes stack. For CLI --debug. */
+  toDebugText(): string {
+    const lines = [
+      `[${this.code}] ${this.message}`,
+      `  Hint: ${this.hint}`,
+    ];
+    if (this.cause) {
+      lines.push(`  Cause: ${this.cause.message}`);
+      if (this.cause.stack) lines.push(`  Stack: ${this.cause.stack}`);
+    }
+    return lines.join('\n');
+  }
+}
+
+export function wrapError(
+  err: unknown,
+  code: string,
+  hint: string,
+): ProductError {
+  if (err instanceof ProductError) return err;
+  const cause = err instanceof Error ? err : new Error(String(err));
+  return new ProductError(code, cause.message, hint, { cause });
+}
+```
+
+### Python reference
+
+```python
+class ProductError(Exception):
+    """Structured error with code, hint, and optional cause."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        hint: str,
+        *,
+        cause: Exception | None = None,
+        retryable: bool = False,
+    ):
+        super().__init__(message)
+        self.code = code
+        self.hint = hint
+        self.__cause__ = cause
+        self.retryable = retryable
+
+    def to_safe_text(self) -> str:
+        """Safe output — no stack traces. For MCP responses + UI."""
+        lines = [f"Error [{self.code}]: {self}", f"Hint: {self.hint}"]
+        if self.__cause__:
+            lines.append(f"Cause: {self.__cause__}")
+        return "\n".join(lines)
+
+    def to_debug_text(self) -> str:
+        """Debug output — includes stack. For CLI --debug."""
+        import traceback
+
+        lines = [f"[{self.code}] {self}", f"  Hint: {self.hint}"]
+        if self.__cause__:
+            lines.append(f"  Cause: {self.__cause__}")
+            lines.append(
+                "".join(traceback.format_exception(self.__cause__))
+            )
+        return "\n".join(lines)
+
+
+def wrap_error(err: Exception, code: str, hint: str) -> ProductError:
+    """Wrap any exception into a ProductError."""
+    if isinstance(err, ProductError):
+        return err
+    return ProductError(code, str(err), hint, cause=err)
+```
+
+### .NET pattern
+
+```csharp
+public class ProductException : Exception
+{
+    public string Code { get; }
+    public string Hint { get; }
+    public bool Retryable { get; }
+
+    public ProductException(
+        string code, string message, string hint,
+        Exception? cause = null, bool retryable = false)
+        : base(message, cause)
+    {
+        Code = code;
+        Hint = hint;
+        Retryable = retryable;
+    }
+
+    public string ToSafeText() =>
+        $"Error [{Code}]: {Message}\nHint: {Hint}"
+        + (InnerException != null ? $"\nCause: {InnerException.Message}" : "");
+}
+```
+
+### Naming convention
+
+Each product renames the class: `GuardianError`, `AttestiaError`, `SoundboardError`, etc.
+
+---
+
+## Error Code Registry Rules
+
+Three rules.
+
+### 1. Codes are namespaced
+
+Use a prefix from this table (extend as needed):
+
+| Prefix | Domain |
+|--------|--------|
+| `IO_` | File system, streams, paths |
+| `CONFIG_` | Configuration, settings, env vars |
+| `PERM_` | Permissions, access control |
+| `DEP_` | Dependencies, external services |
+| `RUNTIME_` | Unexpected failures, OOM, timeouts |
+| `PARTIAL_` | Some items succeeded, some failed |
+| `INPUT_` | Bad user input, validation failures |
+| `STATE_` | Corrupt or stale internal state |
+
+Examples: `IO_READ_FAILED`, `CONFIG_MISSING_KEY`, `STATE_CORRUPT`, `DEP_OLLAMA_UNREACHABLE`
+
+### 2. Codes are stable once released
+
+A code that appears in a shipped version is permanent. You can add new codes. You can deprecate old ones (map to a successor). You cannot change what an existing code means.
+
+### 3. Every code maps to an exit code + default hint
+
+Maintain a table in your repo (in the error file or a separate `ERROR_CODES.md`):
+
+```
+IO_READ_FAILED      → exit 2  → "Check file exists and permissions are correct"
+CONFIG_MISSING_KEY   → exit 1  → "Add the required key to your config file"
+STATE_CORRUPT        → exit 2  → "Run --reset to rebuild state"
+PARTIAL_BATCH        → exit 3  → "Check logs for individual failures"
+```
+
+This table is your error contract with users. Treat it like an API.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@mcptoolshop/shipcheck",
+  "version": "1.0.0",
+  "description": "Product standards for MCP Tool Shop — Ship Gate checklist, error contract, and adoption guides.",
+  "type": "module",
+  "bin": {
+    "shipcheck": "bin/shipcheck.mjs"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "contracts",
+    "ADOPTION.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "author": "mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mcp-tool-shop-org/shipcheck.git"
+  },
+  "homepage": "https://mcp-tool-shop-org.github.io/shipcheck/",
+  "keywords": [
+    "shipcheck",
+    "standards",
+    "ship-gate",
+    "error-contract",
+    "checklist",
+    "quality",
+    "mcp-tool-shop"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/templates/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+### Fixed
+
+### Changed
+
+<!-- ## [0.1.0] - YYYY-MM-DD -->
+<!-- ### Added -->
+<!-- - Initial release -->

package/templates/HANDBOOK.md

@@ -0,0 +1,71 @@
+# Handbook
+
+> Field manual for operating **<!-- product name -->**.
+> If it says WARN, do this. If CRITICAL, do this. No fluff.
+
+## What it does
+
+<!-- One paragraph. What problem it solves, for whom. -->
+
+## How it works
+
+<!-- Brief architecture: inputs → processing → outputs. Keep it to 3–5 sentences. -->
+
+## Daily operations
+
+### Starting up
+
+```bash
+# Replace with your actual startup command
+```
+
+### Normal output
+
+<!-- What does "healthy" look like? Example output or status. -->
+
+### Logging levels
+
+| Level | What you see | When to use |
+|-------|-------------|-------------|
+| silent | Nothing | Automation, scripts |
+| normal | Status + warnings | Default |
+| verbose | Above + progress | Troubleshooting |
+| debug | Everything + stack traces | Bug reports |
+
+## When things go wrong
+
+### WARN conditions
+
+<!-- List warning states and what to do about each. Example: -->
+
+| Signal | Meaning | Action |
+|--------|---------|--------|
+| <!-- e.g., "State file stale" --> | <!-- meaning --> | <!-- action --> |
+
+### CRITICAL conditions
+
+| Signal | Meaning | Action |
+|--------|---------|--------|
+| <!-- e.g., "State corrupt" --> | <!-- meaning --> | <!-- action --> |
+
+### Recovery
+
+<!-- Step-by-step recovery procedure for the worst case. -->
+
+1. <!-- Step 1 -->
+2. <!-- Step 2 -->
+3. <!-- Step 3 -->
+
+## Where things live
+
+| What | Path |
+|------|------|
+| Config | <!-- path --> |
+| Logs | <!-- path --> |
+| State | <!-- path --> |
+
+## Privacy
+
+- All data stays local
+- No telemetry, no network unless explicitly configured
+- Secrets are never logged or included in diagnostics

package/templates/SCORECARD.md

@@ -0,0 +1,49 @@
+# Scorecard
+
+> Score a repo before remediation. Fill this out first, then use SHIP_GATE.md to fix.
+
+**Repo:** <!-- repo name -->
+**Date:** <!-- YYYY-MM-DD -->
+**Type tags:** <!-- [npm] [mcp] [cli] etc. -->
+
+## Pre-Remediation Assessment
+
+| Category | Score | Notes |
+|----------|-------|-------|
+| A. Security | /10 | |
+| B. Error Handling | /10 | |
+| C. Operator Docs | /10 | |
+| D. Shipping Hygiene | /10 | |
+| E. Identity (soft) | /10 | |
+| **Overall** | **/50** | |
+
+## Key Gaps
+
+<!-- List the 3-5 most critical gaps that need fixing. Be specific. -->
+
+1.
+2.
+3.
+
+## Remediation Priority
+
+<!-- What to fix first, second, third. Informed by the gaps above. -->
+
+| Priority | Item | Estimated effort |
+|----------|------|-----------------|
+| 1 | | |
+| 2 | | |
+| 3 | | |
+
+## Post-Remediation
+
+<!-- Fill this out after applying SHIP_GATE.md -->
+
+| Category | Before | After |
+|----------|--------|-------|
+| A. Security | /10 | /10 |
+| B. Error Handling | /10 | /10 |
+| C. Operator Docs | /10 | /10 |
+| D. Shipping Hygiene | /10 | /10 |
+| E. Identity (soft) | /10 | /10 |
+| **Overall** | /50 | /50 |

package/templates/SECURITY.md

@@ -0,0 +1,37 @@
+# Security Policy
+
+## Supported Versions
+
+<!-- Replace with your version table -->
+
+| Version | Supported |
+|---------|-----------|
+| latest  | Yes       |
+
+## Reporting a Vulnerability
+
+Email: **64996768+mcp-tool-shop@users.noreply.github.com**
+
+Include:
+- Description of the vulnerability
+- Steps to reproduce
+- Version affected
+- Potential impact
+
+### Response timeline
+
+| Action | Target |
+|--------|--------|
+| Acknowledge report | 48 hours |
+| Assess severity | 7 days |
+| Release fix | 30 days |
+
+## Scope
+
+<!-- Customize per-product. Examples: -->
+
+This tool operates **locally only**.
+- **Data touched:** <!-- e.g., local log files, process metrics -->
+- **No network egress** unless explicitly configured
+- **No secrets handling** — does not read, store, or transmit credentials
+- **No telemetry** is collected or sent

package/templates/SHIP_GATE.md

@@ -0,0 +1,80 @@
+# Ship Gate
+
+> No repo is "done" until every applicable line is checked.
+> Copy this into your repo root. Check items off per-release.
+
+**Tags:** `[all]` every repo · `[npm]` `[pypi]` `[vsix]` `[desktop]` `[container]` published artifacts · `[mcp]` MCP servers · `[cli]` CLI tools
+
+---
+
+## A. Security Baseline
+
+- [ ] `[all]` SECURITY.md exists (report email, supported versions, response timeline)
+- [ ] `[all]` README includes threat model paragraph (data touched, data NOT touched, permissions required)
+- [ ] `[all]` No secrets, tokens, or credentials in source or diagnostics output
+- [ ] `[all]` No telemetry by default — state it explicitly even if obvious
+
+### Default safety posture
+
+- [ ] `[cli|mcp|desktop]` Dangerous actions (kill, delete, restart) require explicit `--allow-*` flag
+- [ ] `[cli|mcp|desktop]` File operations constrained to known directories
+- [ ] `[mcp]` Network egress off by default
+- [ ] `[mcp]` Stack traces never exposed — structured error results only
+
+## B. Error Handling
+
+- [ ] `[all]` Errors follow the Structured Error Shape: `code`, `message`, `hint`, `cause?`, `retryable?`
+- [ ] `[cli]` Exit codes: 0 ok · 1 user error · 2 runtime error · 3 partial success
+- [ ] `[cli]` No raw stack traces without `--debug`
+- [ ] `[mcp]` Tool errors return structured results — server never crashes on bad input
+- [ ] `[mcp]` State/config corruption degrades gracefully (stale data over crash)
+- [ ] `[desktop]` Errors shown as user-friendly messages — no raw exceptions in UI
+- [ ] `[vscode]` Errors surface via VS Code notification API — no silent failures
+
+## C. Operator Docs
+
+- [ ] `[all]` README is current: what it does, install, usage, supported platforms + runtime versions
+- [ ] `[all]` CHANGELOG.md (Keep a Changelog format)
+- [ ] `[all]` LICENSE file present and repo states support status
+- [ ] `[cli]` `--help` output accurate for all commands and flags
+- [ ] `[cli|mcp|desktop]` Logging levels defined: silent / normal / verbose / debug — secrets redacted at all levels
+- [ ] `[mcp]` All tools documented with description + parameters
+- [ ] `[complex]` HANDBOOK.md: daily ops, warn/critical response, recovery procedures
+
+## D. Shipping Hygiene
+
+- [ ] `[all]` `verify` script exists (test + build + smoke in one command)
+- [ ] `[all]` Version in manifest matches git tag
+- [ ] `[all]` Dependency scanning runs in CI (ecosystem-appropriate)
+- [ ] `[all]` Automated dependency update mechanism exists
+- [ ] `[npm]` `npm pack --dry-run` includes: dist/, README.md, CHANGELOG.md, LICENSE
+- [ ] `[npm]` `engines.node` set · `[pypi]` `python_requires` set
+- [ ] `[npm]` Lockfile committed · `[pypi]` Clean wheel + sdist build
+- [ ] `[vsix]` `vsce package` produces clean .vsix with correct metadata
+- [ ] `[desktop]` Installer/package builds and runs on stated platforms
+
+## E. Identity (soft gate — does not block ship)
+
+- [ ] `[all]` Logo in README header
+- [ ] `[all]` Translations (polyglot-mcp, 8 languages)
+- [ ] `[org]` Landing page (@mcptoolshop/site-theme)
+- [ ] `[all]` GitHub repo metadata: description, homepage, topics
+
+---
+
+## Gate Rules
+
+**Hard gate (A–D):** Must pass before any version is tagged or published.
+If a section doesn't apply, mark `SKIP:` with justification — don't leave it unchecked.
+
+**Soft gate (E):** Should be done. Product ships without it, but isn't "whole."
+
+**Checking off:**
+```
+- [x] `[all]` SECURITY.md exists (2026-02-27)
+```
+
+**Skipping:**
+```
+- [ ] `[pypi]` SKIP: not a Python project
+```