marketplaces/docs/PACKAGE-EXTRACTION.md

@marketplaces/auth & @marketplaces/payment — build, version, publish, consume

See ADR-0001 for why. This doc is the how — build, release, and infrastructure. For consuming the packages (install, providers, exported API), see PACKAGES-USAGE.md.

Current state

Live end to end. marketplaces has no local copy of either package — it installs @marketplaces/auth@0.1.0 from a private Verdaccio registry on the dev server. packages/ no longer exists in this repo.

1. Source repo

sources.vitanova.network/sdarbinyan/vitanovaPackages — single monorepo (npm workspaces), packages/auth + packages/payment, main branch. This is where the package source lives and where CI publishes from.

2. Registry

Verdaccio, running in Docker on the dev server (213.21.246.138, container verdaccio, config/storage at /srv/marketplaces/verdaccio/). Not publicly reachable — the server firewall only allows 80/443/SSH, and opening 4873 or loosening the registry's $authenticated access policy are both security-relevant changes that need an explicit decision, not something done silently. Reach it today via SSH tunnel:

ssh -L 4873:127.0.0.1:4873 seto@213.21.246.138

Follow-up decision needed before CI can publish/consume without a human at the keyboard: either (a) reverse-proxy /verdaccio/ or a subdomain through the existing nginx on 443 with TLS, or (b) open 4873 directly (not recommended — plain HTTP with credentials). Neither is done yet.

@marketplaces/* packages require an authenticated user to install (access: $authenticated in Verdaccio config) — deliberately not $all, since loosening that is itself a security-relevant config change. A registry user marketplaces-ci exists; get a token via npm login --registry=http://127.0.0.1:4873/ (through the tunnel) and set it locally as a user-level ~/.npmrc _authToken line, or export NPM_TOKEN and append it to .npmrc at CI runtime — never commit a token into this repo's .npmrc.

marketplaces/.npmrc maps the scope: @marketplaces:registry=http://127.0.0.1:4873/ — update this once the registry has a real public/internal address.

3. Versioning

Changesets — built for "many packages, one repo, independent versions." A PR that changes packages/auth adds a changeset file (npx changeset from the vitanovaPackages repo root, picks package + bump type + writes a short description) alongside the code change.

4. Publishing (CI)

Two workflows in the vitanovaPackages repo:

• ci.yml — on PRs and non-main pushes: install, build, test, and reject the PR if it has no changeset.
• release.yml — on push to main: install, build, test, then changesets/action opens/updates a version-bump PR; merging that PR publishes.

release.yml needs repo secrets NPM_REGISTRY_URL and NPM_TOKEN. Neither is set, because no CI runner can currently reach the registry (§2). The workflow fails loudly at the auth step rather than silently skipping the publish — that's deliberate, so a broken release is visible instead of looking green.

Until it's resolved, publish manually through the tunnel:

npm login --registry=http://127.0.0.1:4873/ --scope=@marketplaces
npm run build
cd packages/auth && npm publish --registry http://127.0.0.1:4873/

5. Consuming from marketplaces (and other projects)

npm install @marketplaces/auth

import { AuthService, AdminAuthService, adminAuthGuard, ... } from '@marketplaces/auth';

Pinned to an exact version ("0.1.0", no ^/~) per ADR-0001's consequence about registry-outage blast radius — bump deliberately, not automatically.

renovate.json at repo root opens a grouped PR whenever either package publishes a new version — review and merge it manually (automerge: false).

6. Migration cutover

Auth: done. @marketplaces/auth@0.1.0 holds the real implementation — two independent modules, telegram/ (live Telegram QR/session auth, customer + admin) and ed25519/ (future challenge/response admin auth, backend not shipped). Environment coupling was replaced with AUTH_API_URL/TELEGRAM_BOT_USERNAME injection tokens, provided from app.config.ts; environment.production became Angular's isDevMode(). AdminPermissionsService and requireAdminPermission stayed in marketplaces (core/admin-auth/) since they read this app's mock Users domain, not a portable auth concern. All ~30 call sites import @marketplaces/auth. npm run build, npm run arch:check:boundaries, and npm test (103/103) all pass against the registry-installed package.

Payment: not started. core/finance/core/pricing still live in marketplaces, same process as above once prioritized. @marketplaces/payment@0.1.0 is published (scaffold only) but not yet a marketplaces dependency.