lore-ship

name: "lore-ship"

description: "Ship lore (the pi extension @waow.tech/lore and lore.waow.tech) from pi-extensions main: checks, the live two-PDS suite, site deploy, npm publish, each verified. Nate's only step is the npm one-time password."

createdAt: "2026-10-24T06:47:10.137897+00:00"

repoUrl: "https://skillz.supply/skills/did:plc:xbtmt2zjwlrfegqvch7fboei/skills.lore-ship/SKILL.md"

# lore ship

lore lives in `~/tangled.org/zzstoatzz.io/pi-extensions/extensions/lore`. a release
is three things that must agree: `main` pushed to tangled, `lore.waow.tech` built from
it, and `@waow.tech/lore` on npm at the version in `extensions/lore/package.json`.
`ship.sh` beside this file does all of it in order and stops at the first failure.

## before running

1. the change is committed on `main` and pushed. `ship.sh` refuses a dirty tree or a
   `main` that differs from `origin/main`.
2. the version in `extensions/lore/package.json` is bumped and `CHANGELOG.md` has a
   `## <version> — <date>` entry written for the person who hit the bug. the script
   refuses a version npm already has.
3. nate is logged in to npm on this machine. `npm whoami` must succeed. the login is a
   one-time browser flow (`npm login`) that nate runs himself; never ask for or paste a
   token.

## run it where nate can type

npm asks for a one-time password at publish. that is nate's single manual step, so
run the script in a terminal nate sees and can type into: in Claude Code the terminal
panel (`run_in_terminal`), in pi a Rex pane or the foreground. it takes several
minutes, most of it the live suite. tell nate the prompt is coming and what it is for.

```bash
~/tangled.org/zzstoatzz.io/skills/lore-ship/ship.sh
```

if the run cannot be interactive, ask nate for the current code and pass it:
`ship.sh --otp 123456`. the code expires in about thirty seconds, so run immediately.

## what the script does

- preflight: clean tree, on `main`, equal to `origin/main`, version not yet on npm,
  changelog entry present, npm login present.
- `npm run check`: typecheck, lint, unit tests.
- `source live/env.sh && npm run test:live`: two throwaway accounts on pds.zat.dev and
  the alpha host create, share, cross-host write, read, and delete a space; the website
  client reads 102 entries on both authorities. credentials come from the sops store
  and are never printed.
- site: `vite build`, `wrangler deploy`, then confirms lore.waow.tech serves the bundle
  it just built and the OAuth client metadata resolves.
- `npm publish -w @waow.tech/lore`, then confirms `npm view` reports the new version.

## when it stops

fix the cause on `main`, push, rerun. the site deploy and publish are idempotent to
rerun; a published version cannot be republished, so a failure after publish means
the site step already passed and only the verify step is left to repeat by hand
(`npm view @waow.tech/lore version`).

a live-suite failure is a real contract break between lore and a PDS, not flakiness;
read the XRPC error code before touching anything. the live suite needs both hosts up.

Lore Ship