# Publishing WrNexus to npm

All 26 `@wrnexus/*` packages are built and published to the **public npm registry**
(`registry.npmjs.org`), then installed on any machine with **Bun**.

## Prerequisites

The `@wrnexus/*` packages are **scoped**, so the `wrnexus` npm **organization** must
exist and you must be a member with publish rights (a username scope like
`@clintchiz` would work without an org, but the packages are named `@wrnexus/*`).

1. Create the org once at <https://www.npmjs.com/org/create> (name: `wrnexus`).
   - A **free** org can publish unlimited **public** packages.
   - To publish **private** (`restricted`) packages first and flip them public
     later, the org needs a paid **Teams** plan (private scoped packages require it).
2. `npm login` (registry `https://registry.npmjs.org/`).

The repo `.npmrc` points the scope at public npm:

```
@wrnexus:registry=https://registry.npmjs.org/
```

## Publish

The packages ship raw TypeScript in the repo (`main`/`exports` → `src/*.ts`), so
they are **built** for publishing. `scripts/publish-packages.ts` builds each
package with [tsup](https://tsup.egoist.dev) (bundled JS + a single `.d.ts`) and
**stages** a publishable copy under `.publish/<name>/` with a rewritten manifest:

- `main`/`module`/`types`/`exports`/`bin` point at `./dist/*`
- `workspace:*` deps → `^<version>`
- `private` removed; `license` → `MIT`; `publishConfig` → `{ registry, access }`
- runtime assets copied (`@wrnexus/ui` → `components/`, `ui.css`)

The dev `package.json` (pointing at `src/`) is **never modified**, so in-repo dev
and tests keep working.

### 1. Private-first (test before the world sees it)

By default the script stages packages as **`restricted`** (private). Requires the
`wrnexus` org on a paid Teams plan.

```bash
# Build + stage all packages (access: restricted)
bun run scripts/publish-packages.ts

# Publish (deps first). The script prints the exact order + --access flag; e.g.
npm publish .publish/core --access restricted
npm publish .publish/compiler --access restricted
# … through …
npm publish .publish/cli --access restricted
```

Test the private packages (see below). When satisfied, **flip every package to
public** (no republish needed):

```bash
npm access public @wrnexus/core
npm access public @wrnexus/compiler
# … the script prints the full list …
```

### 2. Public directly

To stage public manifests from the start (free org is enough):

```bash
WRNEXUS_NPM_ACCESS=public bun run scripts/publish-packages.ts
npm publish .publish/core --access public
# …
```

Bump `version` in each `packages/*/package.json` before republishing (npm rejects a
duplicate version).

## Consume on another machine (needs Bun)

```bash
mkdir my-wire-app && cd my-wire-app

# Scaffold via the CLI
npm i @wrnexus/cli
bunx wrnexus create app
cd app                       # scaffolds with @wrnexus/* deps declared
bun install                  # pulls @wrnexus/core, styles, validation, db, cli
bun run dev                  # or: bun run build && bun dist/server.js
```

While the packages are still **private**, the consuming machine must be logged in
to npm (`npm login`) as a user with read access to the `wrnexus` org. Once public,
no auth is needed.

`wrnexus create` scaffolds an app that already declares its `@wrnexus/*` runtime
dependencies and a dev-dependency on `@wrnexus/cli`, so `bun install` + `bun run dev`
works standalone.

> Everything runs under **Bun** (the framework uses `Bun.serve`, `bun:sqlite`,
> `Bun.password`, `Bun.build`, …). Node is not a supported runtime.