ship CLAUDE.md

CLAUDE.md

Claude Code instructions for the Ship SDK & CLI package.

@shipstatic/ship — universal SDK and CLI for ShipStatic. Clean resource.action() API, identical in Node.js and Browser. Maturity: Stable; semver applies — breaking changes require a major version bump.

Branches: main (production) + development (integration). The publish workflow runs on both — the guarded publish step publishes only when package.json holds a version not yet on the registry, with the dist-tag derived from the version (- suffix → beta, else latest). See root CLAUDE.md "Branch & CI Model".

Architecture

src/
├── shared/              # Cross-platform code (70% of codebase)
│   ├── api/http.ts      # The transport: headers, retries, timeout, events
│   ├── base-ship.ts     # Base Ship class (auth state, lazy /limits fetch, resources)
│   ├── resources.ts     # Resource factories — every endpoint, stated once
│   ├── types.ts         # Internal SDK types
│   ├── core/            # constants, credential schema, the deploy body + file pipeline
│   └── lib/             # Utilities (validation, junk filtering, MD5, SPA detection)
├── 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