ship

Starter workspace to standardize npm package creation and migration with Changesets.

Documentation

• Complete API and usage guide: docs/ship-api.md
• PR orchestration deep dive: docs/pr-orchestration.md
• Release auth (GitHub App): docs/release-auth-github-app.md

What This Solves

• Standardized npm package DX with one scaffold/migration command.
• Built-in CI and release workflows based on Changesets.
• Managed repo docs and standards files for low-touch setup.
• Optional GitHub repository defaults/ruleset automation.

Architecture

• Root package @i-santos/ship: published CLI and reusable release orchestration engine.
• Adapter model: release runs on adapter capabilities (npm built-in, external via .ship.json + adapterModule).
• template/: managed scaffold baseline used by the CLI.

Role In Navy

Inside the navy monorepo, ship is the delivery layer, not the task orchestrator.

• admiral owns task creation, lifecycle, scheduler state, and runtime files.
• ship owns PR orchestration, release progression, publishing validation, and promotion flows.
• ship integrates with admiral tasks via --task-id.

Official flow:

admiral task create backend-auth --scope backend
admiral task plan backend-auth
admiral task tdd backend-auth
admiral task implement backend-auth
admiral task verify backend-auth
admiral task publish-ready backend-auth
ship release --phase code --task-id backend-auth --yes
ship release --task-id backend-auth --yes

Quickstart

npm install
npx @i-santos/ship --name @i-santos/hello-package

Published CLI:

npx @i-santos/ship --name @i-santos/swarm
npx @i-santos/ship init --dir ./existing-package
npx @i-santos/ship init --dir . --with-github --with-beta --with-npm --release-auth pat --yes
npx @i-santos/ship setup-github --repo i-santos/swarm --dry-run
npx @i-santos/ship setup-beta --dir . --beta-branch release/beta --release-auth pat
npx @i-santos/ship promote-stable --dir . --type patch --summary "Promote beta to stable"
npx @i-santos/ship setup-npm --dir ./existing-package --publish-first

Default Release Model

1. Add a changeset in your PR: npm run changeset.
2. Merge to main.
3. GitHub Actions opens/updates release PR (chore: release packages).
4. Merge release PR to publish.

Trusted Publishing Setup (npm)

If package does not exist on npm yet, first publish can be manual:

npm publish --access public

Then configure npm Trusted Publisher for the package:

• owner
• repository
• workflow file (.github/workflows/release.yml)
• branch (main)

After this, future releases should happen via Changesets release PR workflow.

Migration Guide (existing npm package)

One command:

npx @i-santos/ship init --dir .

Useful flags:

• --force to overwrite managed files and managed script/dependency keys
• --cleanup-legacy-release to remove legacy release script keys (release:beta*, release:stable*, release:promote*, release:rollback*, release:dist-tags)
• --default-branch <branch> to change base branch defaults
• --with-github --with-beta --with-npm to run integrated infra setup inside init
• --yes to skip confirmations in non-interactive contexts

GitHub Defaults Automation

Optional command:

npx @i-santos/ship setup-github --repo i-santos/firestack

Applies baseline repository settings and creates/updates a main branch ruleset. Use --dry-run to preview changes.

Beta Release Automation

Use a dedicated prerelease branch (for example release/beta) instead of main.

Bootstrap beta flow:

npx @i-santos/ship setup-beta --dir . --beta-branch release/beta

By default the command asks for confirmation before mutating GitHub settings/rulesets. Use --yes only for non-interactive/automation runs.

Promote beta to stable:

npx @i-santos/ship promote-stable --dir . --type patch --summary "Promote beta to stable"

This exits prerelease mode and creates an explicit promotion changeset before opening PR from beta branch to main. Keep npm Trusted Publisher configured for release.yml (single workflow), and run that workflow on both main and release/beta. setup-beta also aligns CI trigger branches and applies beta ruleset with required required-check status. setup-beta also provisions an auto-retarget workflow so PR bases follow this policy automatically: release/beta -> main, all other branches -> release/beta. setup-beta/init also support release auth strategy via --release-auth: pat, app, github-token, manual-trigger.

npm First Publish Bootstrap

Optional command:

npx @i-santos/ship setup-npm --dir .

setup-npm checks npm auth and package existence, and can run first publish when needed:

npx @i-santos/ship setup-npm --dir . --publish-first

Trusted Publisher setup on npm remains a manual step after first publish.

Branch & PR Policy

• Keep main protected.
• Require PR review + CI checks before merge.
• Use conventional commit prefixes.