docs(workflows): add publish-outdated-packages-to-gitea-registry workflow

Windsurf workflow for the /publish-outdated-packages-to-gitea-registry slash command. Documents prerequisites (token scopes), step-by-step usage (dry-run, publish, commit bumps), detection algorithm, corp proxy handling, and troubleshooting.
2026-04-03 20:03:45 -07:00 · 2026-04-03 20:03:45 -07:00 · edc36dae00
commit edc36dae00
parent 755b7fedea
1 changed files with 139 additions and 0 deletions
--- a/.windsurf/workflows/publish-outdated-packages-to-gitea-registry.md
+++ b/.windsurf/workflows/publish-outdated-packages-to-gitea-registry.md
@ -0,0 +1,139 @@
+---
+description: Publish only outdated @bytelyst/* packages to the Gitea npm registry
+---
+
+# Publish Outdated Packages to Gitea Registry
+
+Detects which `@bytelyst/*` packages in `packages/` have local changes compared to what's published in the Gitea npm registry, and republishes only the outdated ones.
+
+**Registry (auto-detected via `NETWORK` env var):**
+
+- `NETWORK=corp` → `http://localhost:3300` (SSH tunnel to Azure VM)
+- `NETWORK=home` → `http://<azure-vm>:3300` (direct, from `~/.gitea_vm_host` or `gitea.bytelyst.com`)
+
+**Auth:** `GITEA_NPM_TOKEN` env var (auto-loaded from `~/.gitea_npm_token` by `switch-network.sh`)
+**Token scope required:** `read:package` + `write:package`
+
+---
+
+## Prerequisites
+
+The Gitea NPM token must have **both** `read:package` and `write:package` scopes.
+To create/update the token:
+
+1. Open Gitea token settings:
+   - **Corp network:** `http://localhost:3300/-/user/settings/applications`
+   - **Home network:** `http://<azure-vm>:3300/-/user/settings/applications`
+2. Create a new token with scopes: `read:package`, `write:package`
+3. Save it: `echo "<token>" > ~/.gitea_npm_token`
+4. Reload shell: `source ~/.zshrc`
+
+---
+
+## Steps
+
+### 1. Verify prerequisites
+
+// turbo
+
+```bash
+echo "Token: ${GITEA_NPM_TOKEN:0:5}..." && curl -s -o /dev/null -w "Gitea HTTP: %{http_code}\n" "http://${GITEA_NPM_HOST:-localhost}:3300/"
+```
+
+### 2. Dry-run: detect outdated packages
+
+Run the script in `--dry-run` mode first to see which packages need publishing without making any changes.
+
+// turbo
+
+```bash
+cd /Users/sd9235/code/mygh/learning_ai_common_plat && bash scripts/publish-outdated-gitea-packages.sh --dry-run
+```
+
+Review the output:
+
+- **UP-TO-DATE** — local content matches registry (no action needed)
+- **OUTDATED** — local content differs from registry (will bump patch version + publish)
+- **NOT FOUND** — version not in registry (will publish as-is)
+- **SKIP** — native SDKs or packages without dist/
+
+### 3. Publish outdated packages
+
+If the dry-run shows outdated packages, run the script without `--dry-run` to publish them.
+
+```bash
+cd /Users/sd9235/code/mygh/learning_ai_common_plat && bash scripts/publish-outdated-gitea-packages.sh
+```
+
+The script will:
+
+1. Build all packages (`pnpm build`)
+2. Compare each package's local content fingerprint against the registry's
+3. For outdated packages: auto-bump the patch version (e.g., 0.1.0 -> 0.1.1) and publish
+4. For not-found packages: publish as-is (current version)
+5. Print which `package.json` files were bumped so you can commit them
+
+### 4. Commit version bumps
+
+After publishing, the script reports which `package.json` files had their version bumped. Commit them:
+
+```bash
+cd /Users/sd9235/code/mygh/learning_ai_common_plat && git add packages/*/package.json && git commit -m "chore(packages): bump versions for Gitea registry publish"
+```
+
+### 5. (Optional) Publish a single package
+
+```bash
+cd /Users/sd9235/code/mygh/learning_ai_common_plat && bash scripts/publish-outdated-gitea-packages.sh --filter @bytelyst/errors
+```
+
+### 6. (Optional) Skip the build step
+
+If you already ran `pnpm build`:
+
+```bash
+cd /Users/sd9235/code/mygh/learning_ai_common_plat && bash scripts/publish-outdated-gitea-packages.sh --skip-build
+```
+
+---
+
+## How detection works
+
+For each package in `packages/`:
+
+1. `pnpm pack` creates a local tarball
+2. Downloads the same version's tarball from the registry
+3. Extracts both and computes SHA-256 fingerprints of all file contents
+4. If fingerprints differ (or version not in registry) -> marked for publish
+
+This is metadata-independent (ignores tar timestamps) and catches any source/dist change.
+
+## Corp proxy handling
+
+When `NETWORK=corp`, the script automatically:
+
+- Routes to `http://localhost:3300` (SSH tunnel) instead of the Azure VM
+- Unsets all `NPM_CONFIG_*` and `*_proxy` env vars for the `npm publish` command
+
+On both networks, the script:
+
+- Strips `publishConfig.registry` from tarballs (avoids hardcoded external domain)
+- Runs `npm publish` from `/tmp` (avoids repo `.npmrc` scoped registry override)
+
+---
+
+## Troubleshooting
+
+| Issue                         | Fix                                                                                                   |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `GITEA_NPM_TOKEN is required` | Run `source ~/.zshrc` or `export GITEA_NPM_TOKEN=$(cat ~/.gitea_npm_token)`                           |
+| Gitea unreachable             | Check if Gitea VM is running. Verify `GITEA_NPM_HOST` resolves                                        |
+| E401 on publish               | Token needs `write:package` scope. Regenerate at `http://localhost:3300/-/user/settings/applications` |
+| All packages show OUTDATED    | Normal after first run. Subsequent runs will show UP-TO-DATE for unchanged packages                   |
+| Package has no dist/          | Run `pnpm build` first or don't use `--skip-build`                                                    |
+
+## Script location
+
+`scripts/publish-outdated-gitea-packages.sh` in `learning_ai_common_plat`
+
+Run `bash scripts/publish-outdated-gitea-packages.sh --help` for usage.