# NPM Split Package Release Process

Ce document décrit le nouveau flux de publication "installer + packages binaires par plateforme" pour `@mindflight/ghostcrab-personal-mcp`.

## Objectif

Avant:

- un seul package npm contenait `prebuilds/`
- le tarball principal pesait environ `11.5 MB`
- chaque installation téléchargeait les binaires de toutes les plateformes

Maintenant:

- le package principal est un installeur léger
- 6 packages npm contiennent chacun un seul binaire natif
- le package principal déclare ces packages en `optionalDependencies`
- le runtime résout automatiquement le package binaire installé pour la plateforme courante

## Packages produits

Le split actuel produit 7 tarballs:

- `@mindflight/ghostcrab-personal-mcp`
- `@mindflight/ghostcrab-personal-mcp-linux-x64`
- `@mindflight/ghostcrab-personal-mcp-linux-arm64`
- `@mindflight/ghostcrab-personal-mcp-darwin-x64`
- `@mindflight/ghostcrab-personal-mcp-darwin-arm64`
- `@mindflight/ghostcrab-personal-mcp-win32-x64`
- `@mindflight/ghostcrab-personal-mcp-win32-arm64`

Le package principal ne contient plus `prebuilds/`.

## Fichiers et scripts impliqués

Packaging:

- [package.json](../../package.json)
- [pnpm-workspace.yaml](../../pnpm-workspace.yaml)
- [scripts/stage-platform-packages.mjs](../../scripts/stage-platform-packages.mjs)
- [scripts/pack-local.mjs](../../scripts/pack-local.mjs)
- [scripts/make-beta-bundle.mjs](../../scripts/make-beta-bundle.mjs)
- [scripts/publish-npm-split.mjs](../../scripts/publish-npm-split.mjs) — publication registry dans l’ordre : 6 paquets plateforme, puis racine (aligné sur `pack:local`)

**Canal zip bêta (séparé)** — `pnpm run beta:bundle` reste maintenu en parallèle de npm : zip avec `install-beta.mjs`, Makefile optionnel, `SHA256SUMS.txt`, README testeurs. Ce n’est pas fusionné dans le flux `npm publish` ; les testeurs hors-registry ou hors ligne gardent ce chemin.

Runtime:

- [bin/lib/prebuild-permissions.mjs](../../bin/lib/prebuild-permissions.mjs)
- [bin/commands/serve.mjs](../../bin/commands/serve.mjs)
- [bin/commands/authorize.mjs](../../bin/commands/authorize.mjs)

Validation:

- [scripts/verify-pack.mjs](../../scripts/verify-pack.mjs)
- [scripts/verify-local-install.mjs](../../scripts/verify-local-install.mjs)
- [scripts/smoke-beta-install.mjs](../../scripts/smoke-beta-install.mjs)

## Résolution du binaire au runtime

Ordre de résolution:

1. package binaire plateforme installé via `optionalDependencies`
2. fallback local vers `prebuilds/<platform-key>/...` pour le développement

Exemple sur Linux x64:

1. recherche de `@mindflight/ghostcrab-personal-mcp-linux-x64`
2. lecture de `bin/ghostcrab-backend` dans ce package
3. si absent, fallback vers `prebuilds/linux-x64/ghostcrab-backend`

## Flux local mainteneur

### 1. Construire les prébuilds

```bash
pnpm run prebuild:all
```

Remarque:

- cette étape dépend de Zig et de l’état du vendor
- dans ce checkout, `prebuild:all` est actuellement bloqué par une incompatibilité Zig dans `cmd/backend/http_server.zig`

### 2. Construire la partie TypeScript

```bash
pnpm run build
```

Remarque:

- dans ce checkout, `build` est actuellement bloqué par un fichier vendor SQL manquant utilisé par `scripts/copy-sql.mjs`

### 3. Vérifier le contenu du package principal

```bash
pnpm run verify:pack
```

Attendu:

- le tarball principal contient `bin/`, `dist/`, `docs/`, `ghostcrab-skills/`, `examples/`
- il ne contient pas `prebuilds/`

### 4. Générer les 6 tarballs locaux

```bash
pnpm run pack:local
```

Sortie:

- `dist-pack/*.tgz`
- `dist-pack/pack-manifest.json`

Si les `prebuilds/` sont déjà présents et que vous voulez éviter de relancer le cross-build:

```bash
pnpm run pack:local:reuse-prebuilds
```

Ce chemin est utile quand:

- vous validez uniquement le packaging npm
- vous réutilisez des binaires déjà produits
- le cross-build complet est momentanément bloqué sur une toolchain ou un target spécifique

### 5. Générer un zip bêta prêt à envoyer

```bash
pnpm run beta:bundle
```

Sortie:

- `dist-pack/ghostcrab-beta-<version>.zip`
- `dist-pack/beta-bundle/`

## Flux de test local avant publication

### Smoke test mainteneur

Ce test simule une installation du package principal + du package binaire de la machine courante dans un dossier temporaire.

```bash
pnpm run beta:smoke
```

Ce script:

1. lit `dist-pack/pack-manifest.json`
2. détecte la plateforme courante
3. crée un dossier temporaire
4. fait `npm install` du package principal
5. fait `npm install` du package plateforme courant
6. exécute `gcp --help`
7. exécute `gcp authorize`

Pré-requis:

- `dist-pack/` doit déjà exister
- la machine doit avoir accès au registry npm pour installer les dépendances JS du package principal

## Flux bêta testeurs

Le zip bêta contient:

- le package principal
- les 6 packages plateforme
- `pack-manifest.json`
- un README court pour les testeurs
- un fichier `SHA256SUMS.txt`

Le testeur:

1. dézippe l’archive
2. choisit le package plateforme correspondant à son OS
3. installe le package principal
4. installe le package plateforme
5. exécute `gcp --help`
6. exécute `gcp authorize`
7. configure son client MCP avec `gcp brain up`

## Publication npm

### Où est hébergé le dépôt ? (GitLab aujourd’hui, GitHub plus tard)

- **Actuellement** le dépôt source est sur **GitLab**. Le fichier [`.github/workflows/publish.yml`](../../.github/workflows/publish.yml) ne s’exécute **pas** tant qu’il n’y a pas de dépôt (ou **miroir**) **GitHub** qui reçoit les tags et lance Actions.
- **Jusqu’à la migration** : automatiser la publication avec **GitLab CI** (variable CI masquée `NPM_TOKEN`, job déclenché sur tag `v*`), ou publication **manuelle** depuis une machine de release en reprenant les mêmes étapes (build Zig 0.16 → `prebuilds/`, `npm ci`, `npm run build`, puis ordre des paquets ci‑dessous).
- **Après migration publique vers GitHub** : faire tourner `publish.yml` sur le dépôt GitHub ; vous pourrez activer **npm Trusted Publishing (OIDC)** liée à GitHub pour limiter les tokens longue durée.
- **`npm publish --provenance`** : l’intégration OIDC documentée par npm est surtout pensée pour **GitHub Actions**. Sur **GitLab CI**, utiliser en général `NODE_AUTH_TOKEN` / `NPM_TOKEN` (sans provenance OIDC), ou attendre la migration GitHub pour `--provenance`.

### Ordre des paquets sur le registry

Ordre recommandé :

1. publier les 6 packages plateforme
2. vérifier qu’ils sont bien disponibles sur le registry
3. publier le package principal

Pourquoi :

- le package principal référence immédiatement les packages plateforme via `optionalDependencies`
- si le package principal sort avant les packages plateforme, certaines installations vont retomber sur le fallback ou échouer selon le contexte

Exemple minimal **GitLab CI** (à adapter : image, cache npm, règles de tag) :

```yaml
# .gitlab-ci.yml (extrait — à fusionner avec votre pipeline)
publish_npm:
  stage: deploy
  image: node:20-bookworm
  rules:
    - if: $CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+/
  script:
    - apt-get update -qq && apt-get install -y -qq wget xz-utils
    # 1) Installer Zig 0.16.x, scripts/ensure-vendor.sh, download-sqlite3.sh, cross-build-all.sh
    # 2) npm ci && npm run build
    # 3) node scripts/publish-npm-split.mjs  (6 paquets sous packages/prebuild-* puis racine)
    - echo "Remplacer par la chaîne réelle (p.ex. node scripts/publish-npm-split.mjs)"
  variables:
    NODE_AUTH_TOKEN: $NPM_TOKEN
```

## Checklist bêta avant publication

- [ ] `pnpm run verify:pack`
- [ ] `pnpm run pack:local`
- [ ] `pnpm run beta:bundle`
- [ ] `pnpm run beta:smoke`
- [ ] test réel sur au moins 2 OS
- [ ] validation de `gcp authorize`
- [ ] validation de `gcp brain up`

## Checklist publication publique

- [ ] licence finale décidée et appliquée partout
- [ ] `package.json` et sous-packages alignés sur la licence
- [ ] README public revu
- [ ] docs internes non destinées au public retirées du package ou du repo public
- [ ] historique GitHub nettoyé si nécessaire avant ouverture du repo
- [ ] nom du package et URLs repo/homepage/bugs finalisés
- [ ] CI de build cross-platform stabilisée
- [ ] smoke test post-publish sur `npm`, `npx` et `pnpm dlx`

## Nettoyage repo avant GitHub public

Points à vérifier avant ouverture publique:

- présence de documents internes sous `docs/dev/`
- présence de notes marketing ou plans internes
- présence de références à des stacks, URLs, workflows ou clients non publics
- cohérence des noms `GhostCrab` / `MindBrain`
- présence de fichiers vendored qui ne doivent pas être republiés tels quels

Un nettoyage raisonnable consiste à:

1. décider ce qui doit rester public
2. déplacer le reste dans un dépôt privé ou une archive interne
3. réduire le package npm aux fichiers réellement utiles à l’utilisateur final

## Limitations connues dans ce checkout

- `pnpm run build` échoue actuellement sur un fichier SQL vendor absent
- `pnpm run prebuild:all` échoue actuellement sur Zig
- ces problèmes ne changent pas le design du split package, mais ils bloquent une validation CI complète tant qu’ils ne sont pas corrigés
