refactor: convert repo to pnpm monorepo (packages/desktop) — Phase 1 recovery (#30)

* docs(spec): add Etherpad mobile (Android first, iOS-ready) design

Capacitor + React app sharing the desktop's renderer/state/i18n via a
new @etherpad/shell package in a pnpm monorepo restructure of this
repo. iframe-per-tab pad rendering, custom WebView permissions plugin
for ep_webrtc-style needs, F-Droid as the primary distribution channel.
Embedded local server and push notifications are v2.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(plan): add phase-1 workspace-conversion implementation plan

Phase 1 of the mobile rollout (spec §11.1): convert this repo into a
pnpm workspace with all current desktop source under packages/desktop/,
add a thin proxy root package.json, and update CI / release / snap /
release-please workflows for the new paths. Zero behavioural change to
the desktop app.

Subsequent phases (extract @etherpad/shell, bootstrap @etherpad/mobile,
PadIframeStack, permissions, deep links, responsiveness, F-Droid) will
get their own plans once this one lands.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(monorepo): bootstrap pnpm workspace skeleton

First step of monorepo conversion (spec §3 phase 1). Adds the empty
packages/ directory and pnpm-workspace.yaml. No file moves yet — the
existing single-package layout still works.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor(monorepo): move desktop into packages/desktop

Moves all source, tests, scripts, build dir, config files, and the
desktop-specific docs (AGENTS.md, CHANGELOG.md, README.md) into
packages/desktop/. Renames the package to @etherpad/desktop and adds a
thin root package.json that proxies every script via
`pnpm --filter @etherpad/desktop`.

The pnpm.onlyBuiltDependencies config is moved to the workspace root
(packages/desktop/ is not a workspace root, so the field had no effect
there per pnpm's rules).

The pnpm lockfile stays at the workspace root (canonical pnpm layout).
LICENSE, NOTICE, and CLAUDE.md remain at the repo root because they
apply to the whole repo.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(root): add monorepo README pointing at packages/desktop

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(claude): update CLAUDE.md paths for packages/desktop layout

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci(monorepo): point playwright + report paths at packages/desktop/

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci(release): prefix release artefact paths with packages/desktop/

electron-builder runs via `pnpm --filter @etherpad/desktop exec` so the
binary resolves against the desktop workspace; upload-artifact paths
reach into packages/desktop/release/ for the produced binaries.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci(snap): prefix snap artefact paths with packages/desktop/

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci(release-please): switch to monorepo manifest mode

Desktop is now the only managed package; manifest mode lets us add
mobile/shell later as additional components without further migration.
Tag format unchanged (v<version>) via include-component-in-tag: false +
include-v-in-tag: true, so release.yml and snap-publish.yml triggers
fire on the same shape.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: JohnMcLear

.github/workflows/ci.yml

@@ -36,7 +36,7 @@ jobs:
           node-version: 22
           cache: pnpm
       - run: pnpm install --frozen-lockfile
-      - run: pnpm exec playwright install --with-deps chromium
+      - run: pnpm --filter @etherpad/desktop exec playwright install --with-deps chromium
       - run: pnpm build
       - run: pnpm test:e2e
         env:
@@ -45,5 +45,5 @@ jobs:
         if: failure()
         with:
           name: playwright-report
-          path: playwright-report/
+          path: packages/desktop/playwright-report/
           retention-days: 7

.github/workflows/release-please.yml

@@ -35,9 +35,11 @@ jobs:
     steps:
       - uses: googleapis/release-please-action@v5
         with:
-          # `node` mode keeps package.json's version field as the source
-          # of truth and writes a top-level CHANGELOG.md.
-          release-type: node
-          # Use the default GitHub token; release-please opens PRs and
-          # creates tags on the same repo it runs in.
+          # Manifest mode for the monorepo. Configuration lives in
+          # release-please-config.json; current versions in
+          # .release-please-manifest.json. The desktop package is the
+          # only released package today; mobile/shell will be added
+          # as separate components in later phases.
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
           token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -26,16 +26,16 @@ jobs:
         # electron-builder reads the linux.target array in the YAML —
         # which includes snap — and tries to publish a snap to the Snap
         # Store from this job, which doesn't have the credentials.
-        run: pnpm exec electron-builder --linux AppImage deb --config build/electron-builder.yml --publish always
+        run: pnpm --filter @etherpad/desktop exec electron-builder --linux AppImage deb --config build/electron-builder.yml --publish always
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - uses: actions/upload-artifact@v7
         with:
           name: linux-artifacts
           path: |
-            release/*.AppImage
-            release/*.deb
-            release/latest-linux.yml
+            packages/desktop/release/*.AppImage
+            packages/desktop/release/*.deb
+            packages/desktop/release/latest-linux.yml
           retention-days: 14
 
   release-macos:
@@ -59,17 +59,17 @@ jobs:
         # --mac builds DMG + ZIP for both arm64 and x64. CSC_IDENTITY_AUTO_DISCOVERY=false
         # tells electron-builder NOT to sniff the keychain for a signing
         # identity (we don't have one for the beta).
-        run: pnpm exec electron-builder --mac --config build/electron-builder.yml --publish always
+        run: pnpm --filter @etherpad/desktop exec electron-builder --mac --config build/electron-builder.yml --publish always
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           CSC_IDENTITY_AUTO_DISCOVERY: 'false'
       - uses: actions/upload-artifact@v7
         with:
           name: macos-artifacts
           path: |
-            release/*.dmg
-            release/*-mac.zip
-            release/latest-mac.yml
+            packages/desktop/release/*.dmg
+            packages/desktop/release/*-mac.zip
+            packages/desktop/release/latest-mac.yml
           retention-days: 14
 
   release-windows:
@@ -92,13 +92,13 @@ jobs:
       - name: Build
         run: pnpm build
       - name: Package
-        run: pnpm exec electron-builder --win --config build/electron-builder.yml --publish always
+        run: pnpm --filter @etherpad/desktop exec electron-builder --win --config build/electron-builder.yml --publish always
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - uses: actions/upload-artifact@v7
         with:
           name: windows-artifacts
           path: |
-            release/*.exe
-            release/latest.yml
+            packages/desktop/release/*.exe
+            packages/desktop/release/latest.yml
           retention-days: 14

.github/workflows/snap-publish.yml

@@ -66,7 +66,7 @@ jobs:
         # SNAPCRAFT_STORE_CREDENTIALS is only available in the publish-*
         # jobs below. Disable implicit publish; the dedicated job uses
         # snapcore/action-publish with the credentials properly scoped.
-        run: pnpm exec electron-builder --linux snap --config build/electron-builder.yml --publish never
+        run: pnpm --filter @etherpad/desktop exec electron-builder --linux snap --config build/electron-builder.yml --publish never
 
       - name: Locate snap file
         id: find
@@ -77,14 +77,14 @@ jobs:
         # both the build job (after `cd release` is implicit) and the publish
         # job (after artifact download).
         run: |
-          file=$(ls release/*.snap | head -n1)
+          file=$(ls packages/desktop/release/*.snap | head -n1)
           echo "path=$(basename "$file")" >> "$GITHUB_OUTPUT"
 
       - name: Upload snap artifact
         uses: actions/upload-artifact@v7
         with:
           name: etherpad-desktop-snap
-          path: release/*.snap
+          path: packages/desktop/release/*.snap
           if-no-files-found: error
           retention-days: 7
 

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  "packages/desktop": "0.3.2"
+}

CLAUDE.md

@@ -1,11 +1,17 @@
 # Claude Code instructions
 
-**The canonical AI guide for this repo is `AGENTS.md`** — read it first. This file
+**The canonical AI guide for this repo is `packages/desktop/AGENTS.md`** — read it first. This file
 adds Claude-specific notes and project gotchas that other agents share too.
 
+## Monorepo layout (read this first)
+
+This repo is a pnpm workspace as of 2026-05. The desktop app lives in `packages/desktop`. Run every `pnpm` command from the repo root — the root `package.json` proxies every script via `pnpm --filter @etherpad/desktop`. Don't `cd` into `packages/desktop` for normal dev — it works but breaks IDE assumptions about where the workspace is.
+
+Mobile (`packages/mobile`) and shell (`packages/shell`) are coming in subsequent phases; today there is only `packages/desktop`.
+
 ## Read first
 
-- `AGENTS.md` — full project overview: stack, dev loop, IPC patterns, how
+- `packages/desktop/AGENTS.md` — full project overview: stack, dev loop, IPC patterns, how
   WebContentsViews are positioned, how tests are structured, and the
   house rules. Everything below assumes you've read it.
 - `docs/superpowers/specs/2026-05-03-etherpad-desktop-linux-mvp-design.md`
@@ -23,7 +29,7 @@ These bite people who don't know them. Don't relearn the hard way.
   Earlier code (and the v1 spec) assumed `npx etherpad-lite@latest`
   works; it 404s. The embedded-server flow is currently disabled in the
   UI for this reason. The E2E fixture is now an in-process mock
-  (`tests/e2e/fixtures/etherpad.ts`) that returns the JSON shape the
+  (`packages/desktop/tests/e2e/fixtures/etherpad.ts`) that returns the JSON shape the
   shell probes for.
 - **Never use the name "etherpad-lite" in new packaging, docs, or
   configs.** Legacy paths in code (`ep_etherpad-lite/...`) can stay
@@ -38,14 +44,14 @@ These bite people who don't know them. Don't relearn the hard way.
   the holding process; only `*.lock` files are safe to remove.
 - **WebContentsViews are painted above the renderer.** When the rail
   collapses we leave a gutter on the left (`COLLAPSED_LEFT_GUTTER` in
-  `src/main/windows/app-window.ts`) so the DOM-rendered expand handle
+  `packages/desktop/src/main/windows/app-window.ts`) so the DOM-rendered expand handle
   isn't covered by the native pad view. The CSS handle position and
   the gutter constant must agree — there's a regression test pinning
-  this in `tests/main/windows/app-window-layout.spec.ts`.
+  this in `packages/desktop/tests/main/windows/app-window-layout.spec.ts`.
 - **All user-facing strings go through i18n.** `t.<section>.<key>` from
-  `src/renderer/i18n/`. No hardcoded English in JSX, aria-labels, or
+  `packages/desktop/src/renderer/i18n/`. No hardcoded English in JSX, aria-labels, or
   titles — use `fmt()` for placeholder substitution. The shape contract
-  is pinned in `tests/renderer/i18n/i18n.spec.ts`.
+  is pinned in `packages/desktop/tests/renderer/i18n/i18n.spec.ts`.
 
 ## Working style for this repo