From 87afad56c018b7cbae68e9911b1dbd72fef2f908 Mon Sep 17 00:00:00 2001 From: Callum Flack Date: Thu, 19 Feb 2026 08:13:21 +1000 Subject: [PATCH 01/13] archive old docs --- .../260203-grant-connect-flow-plan.md | 0 .../260203-grant-connect-flow.md | 0 .../260203-grant-connect-flow.png | Bin .../260204-auth-page-react-spec.md | 0 docs/{ => _archive}/260204-connect-flow.png | Bin docs/{ => _archive}/260205-app-id-design.md | 0 docs/{ => _archive}/260205-app-id.png | Bin .../260206-data-src-overview.png | Bin .../{ => _archive}/260206-grant-step3-plan.md | 0 .../{ => _archive}/260206-grant-step4-plan.md | 0 docs/plans/260219-pnpm-migration.md | 121 ++++++++++++++++++ 11 files changed, 121 insertions(+) rename docs/{ => _archive}/260203-grant-connect-flow-plan.md (100%) rename docs/{ => _archive}/260203-grant-connect-flow.md (100%) rename docs/{ => _archive}/260203-grant-connect-flow.png (100%) rename docs/{ => _archive}/260204-auth-page-react-spec.md (100%) rename docs/{ => _archive}/260204-connect-flow.png (100%) rename docs/{ => _archive}/260205-app-id-design.md (100%) rename docs/{ => _archive}/260205-app-id.png (100%) rename docs/{ => _archive}/260206-data-src-overview.png (100%) rename docs/{ => _archive}/260206-grant-step3-plan.md (100%) rename docs/{ => _archive}/260206-grant-step4-plan.md (100%) create mode 100644 docs/plans/260219-pnpm-migration.md diff --git a/docs/260203-grant-connect-flow-plan.md b/docs/_archive/260203-grant-connect-flow-plan.md similarity index 100% rename from docs/260203-grant-connect-flow-plan.md rename to docs/_archive/260203-grant-connect-flow-plan.md diff --git a/docs/260203-grant-connect-flow.md b/docs/_archive/260203-grant-connect-flow.md similarity index 100% rename from docs/260203-grant-connect-flow.md rename to docs/_archive/260203-grant-connect-flow.md diff --git a/docs/260203-grant-connect-flow.png b/docs/_archive/260203-grant-connect-flow.png similarity index 100% rename from docs/260203-grant-connect-flow.png rename to docs/_archive/260203-grant-connect-flow.png diff --git a/docs/260204-auth-page-react-spec.md b/docs/_archive/260204-auth-page-react-spec.md similarity index 100% rename from docs/260204-auth-page-react-spec.md rename to docs/_archive/260204-auth-page-react-spec.md diff --git a/docs/260204-connect-flow.png b/docs/_archive/260204-connect-flow.png similarity index 100% rename from docs/260204-connect-flow.png rename to docs/_archive/260204-connect-flow.png diff --git a/docs/260205-app-id-design.md b/docs/_archive/260205-app-id-design.md similarity index 100% rename from docs/260205-app-id-design.md rename to docs/_archive/260205-app-id-design.md diff --git a/docs/260205-app-id.png b/docs/_archive/260205-app-id.png similarity index 100% rename from docs/260205-app-id.png rename to docs/_archive/260205-app-id.png diff --git a/docs/260206-data-src-overview.png b/docs/_archive/260206-data-src-overview.png similarity index 100% rename from docs/260206-data-src-overview.png rename to docs/_archive/260206-data-src-overview.png diff --git a/docs/260206-grant-step3-plan.md b/docs/_archive/260206-grant-step3-plan.md similarity index 100% rename from docs/260206-grant-step3-plan.md rename to docs/_archive/260206-grant-step3-plan.md diff --git a/docs/260206-grant-step4-plan.md b/docs/_archive/260206-grant-step4-plan.md similarity index 100% rename from docs/260206-grant-step4-plan.md rename to docs/_archive/260206-grant-step4-plan.md diff --git a/docs/plans/260219-pnpm-migration.md b/docs/plans/260219-pnpm-migration.md new file mode 100644 index 0000000..a065c2d --- /dev/null +++ b/docs/plans/260219-pnpm-migration.md @@ -0,0 +1,121 @@ +# 260219-pnpm-migration + +## Goal + +Migrate DataConnect from npm to pnpm as the primary package manager with zero behavior regressions in local dev, Settings page runtime, and release packaging. + +## Constraints + +- Keep app behavior unchanged; this is a tooling migration, not a product refactor. +- Do not break sidecar packaging for `playwright-runner` and `personal-server`. +- Preserve current Node engine constraints (`>=20 <24`) and current release flow semantics. +- Support fresh-clone onboarding with deterministic install behavior. +- Existing npm warning (`Unknown project config "link-workspace-packages"`) appears environment-specific and should not be relied on as repo state. + +## Existing patterns + +- Root app + two sidecar Node packages: + - `package.json` + - `playwright-runner/package.json` + - `personal-server/package.json` +- npm is hardcoded in scripts/config: + - `scripts/build-prod.js` + - `scripts/ensure-playwright-runner.js` + - `scripts/ensure-personal-server.js` + - `src-tauri/tauri.conf.json` + - `.github/workflows/release.yml` +- Sidecar build relies on copied runtime deps (native modules) in: + - `personal-server/scripts/build.js` + +## Proposed approach + +### 1) Introduce pnpm workspace as source of truth + +- Add root `packageManager` field: + - `"packageManager": "pnpm@"` +- Add `pnpm-workspace.yaml` including: + - `.` + - `playwright-runner` + - `personal-server` +- Generate and commit `pnpm-lock.yaml`. +- Remove npm lockfiles: + - `package-lock.json` + - `playwright-runner/package-lock.json` + - `personal-server/package-lock.json` + +### 2) Convert command wiring from npm to pnpm + +- Root `package.json` scripts: + - Replace `npm run ...` chaining with `pnpm ...` equivalents. +- `src-tauri/tauri.conf.json`: + - `beforeDevCommand`: `pnpm auth:build && pnpm dev` + - `beforeBuildCommand`: `pnpm build` +- `scripts/build-prod.js`: + - Replace `npm install`/`npm run build` with pnpm commands. + - Replace `npx tauri ...` with `pnpm tauri ...` (or `pnpm exec tauri ...`). +- `scripts/ensure-playwright-runner.js` and `scripts/ensure-personal-server.js`: + - Replace `spawnSync("npm", ...)` with `spawnSync("pnpm", ...)`. + - Update stale-check lockfile references from `package-lock.json` to `pnpm-lock.yaml` (root/sidecar-aware). + +### 3) Harden sidecar build against pnpm symlink layout + +- In `personal-server/scripts/build.js`, ensure copied runtime modules are dereferenced to physical files when placed in `dist/node_modules`. +- Keep native module loading behavior unchanged (`better-sqlite3`, `bindings`, `file-uri-to-path`). +- Verify `playwright-runner` packaging remains compatible with pnpm-installed dependencies. + +### 4) Update CI/release workflow to pnpm + +- `.github/workflows/release.yml`: + - Switch Node cache from npm to pnpm. + - Install pnpm explicitly (setup action or corepack). + - Replace `npm ci` / `npm run ...` / `npx ...` usage with pnpm equivalents. +- Ensure matrix builds still produce and upload the same artifact set. + +### 5) Update developer docs + +- `README.md`: + - Replace install/run/build commands with pnpm equivalents. +- Any active operational docs referencing npm commands for local setup/release should be updated where they are treated as source-of-truth instructions. +- Historical/archive docs can remain unchanged unless they are still used operationally. + +## Edge cases + +- **Settings page inaccessible after migration** + - Likely caused by `personal-server` subprocess/runtime dependency resolution failure under pnpm symlinks. + - Mitigation: dereference copied runtime deps and verify personal-server starts in Tauri runtime. +- **Lockfile drift across three package roots** + - Mitigation: single workspace lockfile + remove per-package npm lockfiles. +- **Script invocation differences (`pnpm