# Homeport SDK Rebrand Runbook

> **Audience:** operators executing the `@nexartis/nexartis-nanda-node-sdk` → `@nexartis/homeport-sdk` rebrand. This checklist is written as **do not execute automatically**: every step below is a human-in-the-loop action, in order.

The rebrand ships as a single wave of PRs across `homeport` (main repo), this SDK, and its docs consumers. This runbook captures the operator-side steps that live outside the PR diff: GitHub rename, tag surgery, Cloudflare custom-domain rewiring, the publish gate, and the downstream doc update.

---

## (a) GitHub repository rename

Rename the repo on GitHub:

1. **Settings → General → Rename repository** on `Nexartis/nexartis-nanda-node-sdk` → new name **`homeport-sdk`**.
2. GitHub installs a permanent redirect from the old owner/name to the new one; existing PRs, issues, and clones continue to resolve.
3. Update local remotes on developer machines:

   ```bash
   git remote set-url origin git@github.com:Nexartis/homeport-sdk.git
   git remote -v   # verify
   ```

4. Confirm the rename lands cleanly by re-running the two release-critical workflows on `prod` after merge: `release-please.yml`, `publish.yml`.

## (b) Relocate legacy git tags v1.0.0–1.3.0 to a `legacy/*` namespace

The pre-rebrand tags collide with the fresh 1.0.0 Homeport release. Move them under `legacy/` locally, then push and delete the old refs on the remote:

```bash
# Fetch every tag first.
git fetch --tags

# Rename each tag locally to legacy/v<version>.
for v in 1.0.0 1.1.0 1.2.0 1.2.1 1.2.2 1.3.0; do
  if git rev-parse -q --verify "refs/tags/v$v" >/dev/null; then
    git tag "legacy/v$v" "v$v"
    git tag -d "v$v"
  fi
done

# Push the new legacy/* tags.
git push origin --tags

# Delete the old plain v* tags on the remote.
for v in 1.0.0 1.1.0 1.2.0 1.2.1 1.2.2 1.3.0; do
  git push origin ":refs/tags/v$v" || true
done
```

Then edit the associated GitHub Releases (`gh release list`) so their tag targets follow (`gh release edit v1.2.1 --tag legacy/v1.2.1`). Do **not** delete the releases — they document the historical `@nexartis/nexartis-nanda-node-sdk` line and are linked from `CHANGELOG.pre-homeport.md`.

## (c) Cloudflare custom-domain provisioning

Rewire the four hostnames in the Nexartis Cloudflare account:

1. **Provision new docs origins**
   - Add custom domain `homeport-sdk-dev.nexartis.com` bound to the `typedoc-site` Worker (`env.dev`).
   - Add custom domain `homeport-sdk.nexartis.com` bound to the `typedoc-site` Worker (`env.prod`).
2. **Rebind the legacy hostnames to the redirect worker**
   - Detach any existing custom-domain binding on `nnn-sdk-dev.nexartis.com` (previously bound to `typedoc-site` `env.dev`) if Cloudflare refuses to reassign it in-place.
   - Bind `nnn-sdk-dev.nexartis.com` to `homeport-sdk-legacy-redirect` (`env.dev`).
   - Repeat: detach `nnn-sdk.nexartis.com` from `typedoc-site` `env.prod`, then bind it to `homeport-sdk-legacy-redirect` (`env.prod`).
3. **Verify**

   ```bash
   curl -sI https://nnn-sdk.nexartis.com/           # expect 301 → https://homeport-sdk.nexartis.com/
   curl -sI https://homeport-sdk.nexartis.com/      # expect 200
   curl -sI https://homeport-sdk-dev.nexartis.com/  # expect 200
   ```

## (d) Publish gate

Before the first Homeport publish, run the workspace publish gate against a clean checkout:

```bash
pnpm install --frozen-lockfile
pnpm run validate
npm pack --dry-run                     # review file list
pnpm dlx publint
pnpm dlx @arethetypeswrong/cli --pack .
```

Also typecheck a consumer fixture that installs `@nexartis/homeport-sdk` from the tarball produced by `npm pack` and calls `HomeportClient`, `HomeportError`, `HomeportErrorCode`.

## (e) Merge dev → prod

With the wave PRs merged to `dev` and QA gate 1 green, promote `dev` → `prod`. That push triggers:

- `deploy-docs.yml` → builds and deploys `typedoc-site/` to `homeport-sdk.nexartis.com`.
- `deploy-redirect.yml` → deploys `redirect-worker/` (dev + prod).
- `release-please.yml` → opens the 1.0.0 release PR.

Approve and merge the release PR (human, per workspace policy). `publish.yml` then publishes `@nexartis/homeport-sdk@1.0.0` to npmjs with SLSA provenance via OIDC Trusted Publishing.

## (f) Verify the npm publish

```bash
npm view @nexartis/homeport-sdk version        # expect: 1.0.0
npm view @nexartis/homeport-sdk@1.0.0 --json | jq '.dist, .repository, .homepage'
npm audit signatures --package @nexartis/homeport-sdk@1.0.0
```

Expected values: `homepage` = `https://homeport-sdk.nexartis.com`, `repository.url` → `github.com/Nexartis/homeport-sdk`, provenance attestation present.

## (g) Deprecate the predecessor package

Once 1.0.0 is verified on npm, deprecate the old package with a pointer message. Run **exactly** this command:

```bash
npm deprecate @nexartis/nexartis-nanda-node-sdk "This package has been republished as @nexartis/homeport-sdk. Please migrate: https://homeport-sdk.nexartis.com"
```

Do not `npm unpublish` — the historical versions remain installable for consumers pinning the old identifier, they just surface the deprecation notice at install time.

## (h) Update Homeport main-repo docs

Open a follow-up PR on `Nexartis/homeport` updating both surfaces to the new SDK identity:

- `README.md` — replace any `@nexartis/nexartis-nanda-node-sdk` reference with `@nexartis/homeport-sdk`; link to `https://homeport-sdk.nexartis.com`.
- The SDK section of the docs site (`docs/sdk.md` or equivalent) — update install snippets, symbol names (`HomeportClient`, `HomeportError`, `HomeportErrorCode`), env vars (`HOMEPORT_API_KEY`), and log prefix.

**Amend the existing PR #3** on `Nexartis/homeport` with these edits rather than opening a new PR (per the wave plan: one PR per repo per workstream).

---

## Rollback

If the npm publish fails or a downstream issue surfaces before deprecation is announced:

1. Do not `npm unpublish` — npm's 72-hour unpublish window is fragile and permanently disables the version on re-publish attempts.
2. Instead, publish a `1.0.1` patch with the fix and skip the deprecate step in (g) until the fix ships.
3. Legacy hostnames continue to redirect — the deprecation window is defined by the redirect-worker binding, not by the deprecate command.