@ -15,8 +15,12 @@ npm-workspaces monorepo with independently versioned, privately distributed pack
and composition roots.
The packages must be normal npm-format packages, but they must not be published to the public
npmjs.com registry. Configure them for a private registry (GitHub Packages is the assumed default;
substitute the actual internal registry if different).
npmjs.com registry. This repository is hosted on a self-hosted Gitea instance; use Gitea's built-in
package registry (npm support since Gitea 1.17) rather than provisioning a separate service. A Gitea
package belongs to an owner (a user or organization), not to a git repository — the owner does not
need to be the same account that hosts this source repo, though keeping them aligned is simpler to
reason about. A package needs no advance provisioning: Gitea creates it automatically on the first
`npm publish` under that owner.
This migration is about packaging, ownership, and build boundaries. Preserve existing runtime
behavior and wire protocols unless a change is specifically required to establish a package API.
@ -53,8 +57,12 @@ can be changed and tested together.
migration accidentally.
3. Record a green baseline with the existing `check` , unit-test, lint, and build commands. If the
baseline is not green, distinguish pre-existing failures from migration regressions.
4. Decide the private package scope, replacing every `@<scope>` placeholder below. Do not invent a
scope if the repository or organization configuration does not reveal it.
4. Decide the private package scope, replacing every `@<scope>` placeholder below, and decide the
Gitea host and owner (user or organization) the packages will publish under, replacing every
`<gitea-host>` /`< owner > ` placeholder below. The npm `@<scope>` string and the Gitea `<owner>` path
segment are independent and do not have to match, but keeping them identical avoids confusion. Do
not invent a scope, host, or owner if the repository or organization configuration does not reveal
it.
## Target repository structure
@ -183,7 +191,7 @@ Create curated index files and export only supported APIs. A starting manifest s
}
},
"publishConfig": {
"registry": "https://npm.pkg.github.com "
"registry": "https://< gitea-host > /api/packages/< owner > /npm/
}
}
```
@ -280,7 +288,7 @@ so the app owns the single compatible core installation:
}
},
"publishConfig": {
"registry": "https://npm.pkg.github.com "
"registry": "https://< gitea-host > /api/packages/< owner > /npm/
}
}
```
@ -406,14 +414,29 @@ silently into the app.
## Private publication and versioning
Assuming GitHub Packages, add this committed scope mapping without a token:
Use Gitea's built-in package registry at `https://<gitea-host>/api/packages/<owner>/npm/` . Add this
committed scope mapping without a token:
```ini
@< scope > :registry=https://npm.pkg.github.com
@< scope > :registry=https://< gitea-host > /api/packages/< owner > /npm/
```
Authentication is a separate, uncommitted line — a Gitea personal access token (or, in CI, a repo- or
org-level token) with `package` permission:
```ini
//< gitea-host > /api/packages/< owner > /npm/:_authToken=${GITEA_NPM_TOKEN}
```
Authentication belongs in developer and CI secrets. Never commit a package token.
Gitea does not require a package to be created ahead of time — it is created automatically on the
first `npm publish` under that owner and appears afterward on the owner's Packages tab. Publish access
to an org-owned package is restricted to org members with admin or write access to that org, so decide
who that is before the first release. Linking a published package back to this source repository (for
discoverability in the repo's own UI) is optional, is done from the package's settings page after
publishing, and has no effect on `npm install` /`npm ci`.
Version core and humanoid independently. Start both at `0.1.0` unless existing internal releases
require another baseline. During `0.x` development, document that minor releases may be breaking;
after `1.0.0` , use normal semantic-versioning expectations.
