feat(git-sync): one-way GitHub → Wiki sync

CLAUDE.md

@@ -10,6 +10,10 @@ Always load and user frappe-app-dev skills.
 
 Unless mentioned, the site is wiki.localhost with Administrator/admin credentials.
 
+## Planning / Spec-ing
+
+Use Tracer bullets comes from the Pragmatic Programmer. When building systems, you want to write code that gets you feedback as quickly as possible. Tracer bullets are small slices of functionality that go through all layers of the system, allowing you to test and validate your approach early. This helps in identifying potential issues and ensures that the overall architecture is sound before investing significant time in development.
+
 ## Implementation Guidelines
 
 * Create a new branch before working on a new feature/spec (branch name patterns: feat/, fix/, just like conventional commit pre-fixes)

e2e/helpers/frappe.ts

@@ -194,7 +194,9 @@ export async function getList<T = Record<string, unknown>>(
 	if (options.filters) {
 		params.set('filters', JSON.stringify(options.filters));
 	}
-	if (options.limit) {
+	if (options.limit !== undefined) {
+		// 0 means "no limit" in Frappe — without this, the REST default of 20
+		// silently truncates large result sets.
 		params.set('limit_page_length', options.limit.toString());
 	}
 	if (options.orderBy) {

e2e/helpers/wiki.ts

@@ -1,6 +1,32 @@
 import { APIRequestContext, type Page, expect } from '@playwright/test';
 import { createDoc, deleteDoc, getDoc, getList } from './frappe';
 
+/**
+ * Tear down every Wiki Space with the given (test-unique) route.
+ *
+ * `Wiki Space` cascades its documents, revisions and root group on delete (see
+ * its `on_trash`), so a single atomic `deleteDoc` removes the whole space —
+ * important for a git-synced space, which is read-only and otherwise lingers as
+ * the newest entry in the `/wiki` list (ordered by creation desc), trapping
+ * later specs whose helpers author into the first space (no "New Page" button).
+ *
+ * Resolving by route rather than the create response means a space the server
+ * created but whose response the client never saw — a `createDoc` that timed
+ * out, or a Playwright retry that created a second space — is still cleaned up.
+ */
+export async function cleanupWikiSpacesByRoute(
+	request: APIRequestContext,
+	route: string,
+): Promise<void> {
+	const found = await getList<{ name: string }>(request, 'Wiki Space', {
+		fields: ['name'],
+		filters: { route },
+		limit: 0,
+	}).catch(() => []);
+	for (const space of found)
+		await deleteDoc(request, 'Wiki Space', space.name).catch(() => {});
+}
+
 /**
  * Publish the change request currently open on the review page. The header
  * primary action is Approve-only; the combined "Approve & Merge" lives in the

e2e/tests/git-sync-edit-on-github.spec.ts

@@ -0,0 +1,94 @@
+import { expect, test } from '@playwright/test';
+import { createDoc } from '../helpers/frappe';
+import {
+	type WikiDocument,
+	type WikiSpace,
+	cleanupWikiSpacesByRoute,
+} from '../helpers/wiki';
+
+/**
+ * TB2 — "Edit on GitHub" on a synced page.
+ *
+ * A git-synced page carries a repo-relative source_path. Its three-dots menu
+ * should offer "Edit on GitHub", opening the source file in GitHub's web editor
+ * at https://github.com/{repo}/edit/{branch}/{source_path}. We seed the space +
+ * pages via the API (last_sync_time set so no real GitHub fetch fires) and stub
+ * window.open to assert the exact URL without leaving the app.
+ */
+test.describe('Git-synced space — Edit on GitHub (TB2)', () => {
+	const REPO = 'frappe/wiki';
+	const BRANCH = 'main';
+
+	let route: string;
+
+	test.afterEach(async ({ request }) => {
+		if (route) await cleanupWikiSpacesByRoute(request, route);
+		route = '';
+	});
+
+	test('menu item opens the source file in GitHub editor', async ({
+		page,
+		request,
+	}) => {
+		route = `git-sync-edit-${Date.now()}`;
+		const space = await createDoc<WikiSpace & { root_group: string }>(
+			request,
+			'Wiki Space',
+			{
+				route,
+				space_name: route,
+				is_published: true,
+				git_synced: 1,
+				repo_full_name: REPO,
+				branch: BRANCH,
+				last_sync_status: 'Success',
+				last_sync_time: '2026-01-01 00:00:00',
+			},
+		);
+
+		// A nested leaf page with a repo-relative source_path.
+		const leafSourcePath = 'docs/guides/setup.md';
+		const leafTitle = `Setup ${Date.now()}`;
+		await createDoc<WikiDocument>(request, 'Wiki Document', {
+			title: leafTitle,
+			route: `${route}/setup`,
+			content: '# Setup\n\nFrom the repo.',
+			wiki_space: space.name,
+			parent_wiki_document: space.root_group,
+			is_published: true,
+			source_path: leafSourcePath,
+		});
+
+		await page.goto(`/wiki/spaces/${space.name}`);
+		await page.waitForLoadState('networkidle');
+
+		// Open the synced page.
+		await page.locator('aside').getByText(leafTitle, { exact: true }).click();
+		await page.waitForURL(/\/page\//);
+		await expect(page.locator('.ProseMirror')).toBeVisible({ timeout: 10000 });
+
+		// Stub window.open so we can read the URL without navigating away.
+		await page.evaluate(() => {
+			// @ts-expect-error test-only hook
+			window.__openedUrl = null;
+			window.open = (url) => {
+				// @ts-expect-error test-only hook
+				window.__openedUrl = url;
+				return null;
+			};
+		});
+
+		await page.getByRole('button', { name: 'More actions' }).click();
+		const editItem = page.getByRole('menuitem', { name: 'Edit on GitHub' });
+		await expect(editItem).toBeVisible();
+		await editItem.click();
+
+		const opened = await page.evaluate(
+			// @ts-expect-error test-only hook
+			() => window.__openedUrl,
+		);
+		expect(opened).toBe(
+			`https://github.com/${REPO}/edit/${BRANCH}/${leafSourcePath}`,
+		);
+	});
+});

e2e/tests/git-sync-readonly.spec.ts

@@ -0,0 +1,86 @@
+import { expect, test } from '@playwright/test';
+import { createDoc } from '../helpers/frappe';
+import {
+	type WikiSpace,
+	cleanupWikiSpacesByRoute,
+	createTestWikiDocument,
+} from '../helpers/wiki';
+
+/**
+ * TB1b-ii — a git-synced Wiki Space renders read-only in the authoring SPA.
+ *
+ * We seed a synced space + a published page directly via the API (bypassing the
+ * GitHub fetch) and set last_sync_time so SpaceDetails does not auto-kick a real
+ * sync. The SPA should then show the "Synced from GitHub" banner, source the
+ * sidebar from the live tree, hide every mutation affordance, and open the page
+ * in a non-editable viewer.
+ */
+test.describe('Git-synced space (read-only)', () => {
+	const REPO = 'frappe/wiki';
+	const BRANCH = 'main';
+
+	let route: string;
+
+	test.afterEach(async ({ request }) => {
+		if (route) await cleanupWikiSpacesByRoute(request, route);
+		route = '';
+	});
+
+	test('renders read-only with no editing affordances', async ({
+		page,
+		request,
+	}) => {
+		route = `git-sync-ro-${Date.now()}`;
+		// last_sync_time is set so SpaceDetails treats the space as already
+		// synced and skips the auto initial-sync (which would hit GitHub).
+		const space = await createDoc<WikiSpace & { root_group: string }>(
+			request,
+			'Wiki Space',
+			{
+				route,
+				space_name: route,
+				is_published: true,
+				git_synced: 1,
+				repo_full_name: REPO,
+				branch: BRANCH,
+				last_sync_status: 'Success',
+				last_sync_time: '2026-01-01 00:00:00',
+			},
+		);
+
+		const pageTitle = `Synced Page ${Date.now()}`;
+		await createTestWikiDocument(request, {
+			title: pageTitle,
+			content: '# Synced Heading\n\nThis content comes from the repo.',
+			wiki_space: space.name,
+			parent_wiki_document: space.root_group,
+			is_published: true,
+		});
+
+		await page.goto(`/wiki/spaces/${space.name}`);
+		await page.waitForLoadState('networkidle');
+
+		// Synced banner: repo link (title) + "Synced from GitHub" subtitle + Sync now.
+		await expect(
+			page.locator(`a[href="https://github.com/${REPO}"]`),
+		).toBeVisible({ timeout: 10000 });
+		await expect(page.getByText('Synced from GitHub')).toBeVisible();
+		await expect(page.getByRole('button', { name: 'Sync now' })).toBeVisible();
+
+		// No create / mutation affordances in the sidebar.
+		await expect(page.locator('button[title="New Page"]')).toHaveCount(0);
+		await expect(page.locator('button[title="New Group"]')).toHaveCount(0);
+
+		// Open the synced page and confirm the viewer is non-editable.
+		await page.locator('aside').getByText(pageTitle, { exact: true }).click();
+		await page.waitForURL(/\/page\//);
+
+		const editor = page.locator('.ProseMirror');
+		await expect(editor).toBeVisible({ timeout: 10000 });
+		await expect(editor).toHaveAttribute('contenteditable', 'false');
+
+		// No Save button and no editor toolbar in read-only mode.
+		await expect(page.getByRole('button', { name: 'Save' })).toHaveCount(0);
+		await expect(page.locator('.wiki-editor-container button')).toHaveCount(0);
+	});
+});