ship: Instructions file for Claude Code

CLAUDE.md

Claude Code instructions for the Ship SDK & CLI package.

@shipstatic/ship is the universal SDK and CLI for ShipStatic: a resource.action() API, identical in Node.js and the browser. Maturity: stable; semver applies, so a breaking change needs a major version. The pre-launch exception: until the platform has external consumers, a change to a published type rides a minor under the same exception @shipstatic/types records beside its additive-evolution law, and the release notes name it.

Releasing. Work on development. Bump version in package.json and push: a prerelease (- suffix) publishes to beta (from either branch, normally development), a stable version to latest from main. A version already on the registry is a no-op. A version relying on new API behaviour merges to main only once that API is on production. Keep ci.yml's filename: it is half of the npm trusted-publisher registration.

Architecture

src/
├── shared/              # Cross-platform code (most of the package)
│   ├── api/http.ts      # The transport: headers, retries, timeout, events
│   ├── base-ship.ts     # Base Ship class (credential slot, resources, top-level calls)
│   ├── resources.ts     # Resource factories: every endpoint, stated once
│   ├── types.ts         # Internal SDK types
│   ├── core/            # constants, credential schema, deploy body, request planner, file pipeline
│   └── lib/             # Utilities (validation, junk filtering, MD5)
├── browser/             # Browser Ship class + the `webkitRelativePath` read
└── node/
    ├── core/config.ts       # readEnvConfig: SHIP_* env-var resolution (no filesystem)
    ├── core/node-files.ts   # the filesystem walk (the pipeline itself is shared)
    └── cli/
        ├── bin.ts           # THE EXECUTABLE (dist/cli.cjs), the only file with side effects
        ├── index.ts         # Commander.js command tree + withErrorHandling + performDeploy
        ├── create-client.ts # Credential precedence (flag → env → file) → Ship instance
        ├── shiprc.ts        # ~/.shiprc + --config reader (strict JSON), CLI ONLY
        ├── config.ts        # Interactive `ship config` wizard
        ├── error-handling.ts # toShipError + getUserMessage (TEXT channel)
        ├── formatters.ts    # announce() + the render router
        ├── utils.ts         # Output primitives (success/error/info, table, details)
        ├── types.ts         # CLI option + result types
        ├── completions.ts   # Shell completion scripts, RENDERED from the tree
        └── completion.ts    # Shell completion install/uninstall