@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/lib/wiki/mirror.server.ts

@@ -0,0 +1,251 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The wiki mirror: one bare, shallow git clone per wiki, read with `ls-tree`
+ * and `show`.
+ *
+ * Reading a wiki over git rather than over an API is what makes one
+ * implementation cover GitHub, GitLab and a self-hosted GitLab: all three
+ * publish the same `.wiki.git` repository, so the fetch is the checkout's own
+ * remote with a suffix and nothing else differs. See `./remote`.
+ *
+ * Five properties of this module are deliberate:
+ *
+ *   - **One ref, not a working tree.** `HEAD:refs/wiki/latest` is fetched
+ *     directly into a bare repository, so there is no checkout to keep in sync
+ *     and no second copy of the pages on disk. Verified against
+ *     `github.com/jgraph/drawio.wiki.git` (19 paths, 1.2 MB, ~1.9 s cold) and
+ *     `git-rbi.jatismobile.com/jns6_5/drrealhandler.wiki.git` (7 paths, 0.7 s).
+ *   - **Shallow.** `--depth 1` keeps a wiki's whole history — which for a
+ *     changelog wiki is the bulk of it — out of the cache. A re-fetch costs
+ *     ~1.1 s and is TTL'd, so the panel's poll is not a fetch loop.
+ *   - **No credential on disk.** `--no-write-fetch-head` keeps the fetch from
+ *     writing `FETCH_HEAD`, and a refspec (rather than a named remote) keeps the
+ *     credential-carrying URL out of `.git/config` entirely — verified: neither
+ *     file mentions the remote the fetch used.
+ *   - **A missing wiki is an answer, not an error.** Git answers "Repository not
+ *     found" / "Authentication failed" for a wiki that does not exist and one
+ *     Kabmo cannot read, and both mean the same thing to a reader: there
+ *     is nothing to show. They map to `no-wiki` so the panel can say so instead
+ *     of reporting a failure.
+ *   - **A page is read at the ref, never off a path.** `git show <ref>:<path>`
+ *     can only name a blob in the wiki's own tree, so a crafted path cannot
+ *     reach outside it.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { getDataDir } from '@/server/lib/lifecycle/paths';
+import { firstLine, gitRun, type GitRun } from '@/server/lib/wiki/git';
+import type { WikiUnavailableReason } from '@/shared/types/wiki';
+import { childEnv } from '@/server/lib/fs/child-env';
+
+/** How long a mirror is trusted before a read re-fetches it. */
+const MIRROR_TTL_MS = 60_000;
+/** Hard budget for one fetch; a wiki that cannot answer within it is unreachable. */
+const FETCH_TIMEOUT_MS = 20_000;
+/** Hard budget for the local reads (`ls-tree`, `show`). */
+const READ_TIMEOUT_MS = 5_000;
+/**
+ * A page longer than this is cut, in characters. A wiki page past two million
+ * characters is pathological, and the panel renders it synchronously.
+ */
+export const MAX_WIKI_PAGE_CHARS = 2_000_000;
+/** An asset larger than this is refused rather than loaded into the response. */
+const MAX_WIKI_ASSET_BYTES = 8 * 1024 * 1024;
+
+const REF = 'refs/wiki/latest';
+
+export interface WikiMirror {
+  /** Bare repository holding the wiki. */
+  repoDir: string;
+  /** Commit the mirror is at. */
+  revision: string;
+  /** ISO timestamp of that commit. */
+  updatedAt: string;
+}
+
+export type WikiMirrorResult =
+  | { ok: true; mirror: WikiMirror }
+  | { ok: false; reason: WikiUnavailableReason; detail: string };
+
+interface CacheEntry {
+  fetchedAt: number;
+  mirror: WikiMirror | null;
+  /** Fetch in flight, so concurrent readers share one. */
+  inFlight: Promise<WikiMirrorResult> | null;
+}
+
+/**
+ * The cache lives on `globalThis` for the same reason the database handle does:
+ * `bun run --hot` re-evaluates this module on every edit, and a module-level map
+ * would be dropped while its on-disk mirrors stayed.
+ */
+interface WikiCacheHost {
+  entries: Map<string, CacheEntry>;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __kabmoWikiCache: WikiCacheHost | undefined;
+}
+
+function cache(): Map<string, CacheEntry> {
+  globalThis.__kabmoWikiCache ??= { entries: new Map() };
+  return globalThis.__kabmoWikiCache.entries;
+}
+
+/**
+ * Directory for one wiki, derived from host and slug rather than from the remote
+ * URL: a token in that URL would otherwise land in a path name, and two
+ * spellings of the same remote (`https` and `ssh`) must share one mirror.
+ */
+function mirrorDir(host: string, slug: string): string {
+  const safe = (value: string) => value.replace(/[^A-Za-z0-9._-]+/g, '__').replace(/^_+|_+$/g, '');
+  return path.join(getDataDir(), 'wiki', `${safe(host)}__${safe(slug)}`);
+}
+
+/**
+ * Git's own wording for "there is nothing here to show".
+ *
+ * Three shapes, all meaning the same thing to a reader: the repository does not
+ * exist ("Repository not found"), it exists but is not readable without a
+ * credential ("Authentication failed", "could not read Username"), or it exists
+ * and is EMPTY — `couldn't find remote ref HEAD`, which is what a GitLab project
+ * with a wiki that has never had a page answers (verified against
+ * `git-rbi.jatismobile.com/jns6_6/drrealhandler.wiki.git`).
+ */
+const MISSING_WIKI_RE = /(repository not found|authentication failed|could not read username|access denied|terminal prompts disabled|invalid username or|couldn't find remote ref)/i;
+
+function classifyFetchFailure(result: GitRun): { reason: WikiUnavailableReason; detail: string } {
+  const detail = firstLine(result.stderr || result.stdout);
+  if (result.failed) return { reason: 'unreachable', detail: detail || 'The wiki fetch timed out' };
+  if (MISSING_WIKI_RE.test(detail)) return { reason: 'no-wiki', detail };
+  return { reason: 'unreachable', detail: detail || 'The wiki could not be read' };
+}
+
+async function readRevision(repoDir: string): Promise<WikiMirror | null> {
+  const out = await gitRun(['--git-dir', repoDir, 'log', '-1', '--format=%H%n%cI', REF], { timeoutMs: READ_TIMEOUT_MS });
+  if (out.exitCode !== 0) return null;
+  const [revision, updatedAt] = out.stdout.trim().split('\n');
+  if (!revision) return null;
+  return { repoDir, revision, updatedAt: updatedAt ?? '' };
+}
+
+async function fetchWiki(host: string, slug: string, remote: string): Promise<WikiMirrorResult> {
+  const repoDir = mirrorDir(host, slug);
+  try {
+    await fs.promises.mkdir(repoDir, { recursive: true });
+    // `init` only when there is nothing there: re-initialising a live mirror
+    // would drop the ref the previous fetch wrote.
+    if (!fs.existsSync(path.join(repoDir, 'HEAD'))) {
+      const init = await gitRun(['init', '--bare', '--quiet', repoDir], { timeoutMs: READ_TIMEOUT_MS });
+      if (init.exitCode !== 0) {
+        return { ok: false, reason: 'unreachable', detail: firstLine(init.stderr) || 'Could not prepare the wiki cache' };
+      }
+    }
+
+    const fetched = await gitRun(
+      ['--git-dir', repoDir, 'fetch', '--no-write-fetch-head', '--depth', '1', '--force', '--quiet', remote, `HEAD:${REF}`],
+      { timeoutMs: FETCH_TIMEOUT_MS },
+    );
+    if (fetched.exitCode !== 0) return { ok: false, ...classifyFetchFailure(fetched) };
+
+    const mirror = await readRevision(repoDir);
+    if (!mirror) return { ok: false, reason: 'no-wiki', detail: 'The wiki repository holds no pages' };
+    return { ok: true, mirror };
+  } catch (error) {
+    return { ok: false, reason: 'unreachable', detail: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/**
+ * The mirror for one wiki, re-fetching it when the cached one is older than the
+ * TTL. Concurrent callers share a single fetch.
+ */
+export async function ensureWikiMirror(
+  host: string,
+  slug: string,
+  remote: string,
+  force = false,
+): Promise<WikiMirrorResult> {
+  const key = `${host}\u0000${slug}`;
+  const entries = cache();
+  const entry = entries.get(key);
+
+  if (!force && entry?.mirror && Date.now() - entry.fetchedAt < MIRROR_TTL_MS) {
+    return { ok: true, mirror: entry.mirror };
+  }
+  if (entry?.inFlight) return entry.inFlight;
+
+  const inFlight = fetchWiki(host, slug, remote).then((result) => {
+    const current = entries.get(key);
+    if (current) {
+      current.inFlight = null;
+      if (result.ok) {
+        current.mirror = result.mirror;
+        current.fetchedAt = Date.now();
+      }
+    }
+    return result;
+  });
+
+  entries.set(key, { fetchedAt: entry?.fetchedAt ?? 0, mirror: entry?.mirror ?? null, inFlight });
+  return inFlight;
+}
+
+/**
+ * Every path in the mirror's tree, verbatim (`Home.md`, `images/x.png`).
+ *
+ * `-z` because a wiki path is author-chosen and does hold spaces — the repo this
+ * feature was built against carries
+ * `Setting-up-a-OneDrive-project-to-use-with-diagrams.net.md`.
+ */
+export async function listWikiPaths(repoDir: string): Promise<string[]> {
+  const out = await gitRun(['--git-dir', repoDir, 'ls-tree', '-r', '--name-only', '-z', REF], { timeoutMs: READ_TIMEOUT_MS });
+  if (out.exitCode !== 0) return [];
+  return out.stdout.split('\0').filter(Boolean);
+}
+
+export type WikiBlobResult =
+  | { ok: true; text: string; truncated: boolean }
+  | { ok: false; error: string };
+
+/** One page's markdown source, cut at {@link MAX_WIKI_PAGE_CHARS}. */
+export async function readWikiPage(repoDir: string, pagePath: string): Promise<WikiBlobResult> {
+  const out = await gitRun(['--git-dir', repoDir, 'show', `${REF}:${pagePath}`], { timeoutMs: READ_TIMEOUT_MS });
+  if (out.exitCode !== 0) return { ok: false, error: `Page not found: ${pagePath}` };
+  const truncated = out.stdout.length > MAX_WIKI_PAGE_CHARS;
+  return { ok: true, text: truncated ? out.stdout.slice(0, MAX_WIKI_PAGE_CHARS) : out.stdout, truncated };
+}
+
+/**
+ * One asset's bytes, for a page's own `![](images/schema.png)`.
+ *
+ * Read as bytes rather than through the text runner: decoding stdout as UTF-8
+ * turns a PNG into replacement characters. An oversized blob is refused rather
+ * than returned — git cannot be asked for the size and the bytes in one spawn,
+ * and the panel is a reader, not a file server.
+ */
+export async function readWikiAsset(repoDir: string, assetPath: string): Promise<Uint8Array | null> {
+  let proc: Bun.Subprocess<'ignore', 'pipe', 'ignore'>;
+  try {
+    proc = Bun.spawn({
+      env: childEnv(),
+      cmd: ['git', '--git-dir', repoDir, 'show', `${REF}:${assetPath}`],
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'ignore',
+      timeout: READ_TIMEOUT_MS,
+    });
+  } catch {
+    return null;
+  }
+  const bytes = new Uint8Array(await new Response(proc.stdout).arrayBuffer());
+  const exitCode = await proc.exited;
+  if (exitCode !== 0 || bytes.byteLength === 0 || bytes.byteLength > MAX_WIKI_ASSET_BYTES) return null;
+  return bytes;
+}

package/src/server/lib/wiki/payload.server.ts

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * One wiki's tree, as the panel renders it.
+ *
+ * Extracted from `routes/wiki/repo.ts` so the HTTP route and the realtime
+ * `wiki:` topic share one implementation: the mirror TTL, the provider probe
+ * and the sidebar merge are the details two copies would drift on.
+ */
+
+import { isMockMode } from '@/server/mock.server';
+import { scopeToRepo } from '@/server/lib/fs/repo-scope';
+import { firstLine, gitRun } from '@/server/lib/wiki/git';
+import { ensureWikiMirror, listWikiPaths, readWikiPage } from '@/server/lib/wiki/mirror.server';
+import { detectWikiProvider } from '@/server/lib/wiki/provider.server';
+import { parseWikiRemote, redactRemoteUrl, wikiWebUrl } from '@/server/lib/wiki/remote';
+import { buildWikiEntries } from '@/shared/lib/wiki/pages';
+import { findWikiSidebarPath, parseWikiSidebar, withRemainingPages } from '@/shared/lib/wiki/sidebar';
+import type { WikiNavSection, WikiRepoPayload } from '@/shared/types/wiki';
+
+/** The checkout's `origin`; null when there is none to read. */
+async function readOriginRemote(dir: string): Promise<{ remote: string | null; error: string }> {
+  const out = await gitRun(['-C', dir, 'remote', 'get-url', 'origin'], { timeoutMs: 5_000 });
+  if (out.exitCode !== 0) return { remote: null, error: firstLine(out.stderr) };
+  return { remote: out.stdout.trim() || null, error: '' };
+}
+
+/** MOCK=true: a deterministic wiki so the panel renders its full range offline. */
+function mockPayload(): WikiRepoPayload {
+  const entries = buildWikiEntries([
+    'Home.md',
+    'Getting-Started.md',
+    'guides/Deployment.md',
+    'guides/Troubleshooting.md',
+    'change_logs/v1.0.0.md',
+    'images/diagram.svg',
+    '_Sidebar.md',
+    '.gitlab/redirects.yml',
+  ]);
+  return {
+    repo: {
+      provider: 'github',
+      host: 'github.com',
+      slug: 'kabmo/demo',
+      remote: 'https://github.com/kabmo/demo',
+      webUrl: 'https://github.com/kabmo/demo/wiki',
+      revision: '0000000000000000000000000000000000000000',
+      updatedAt: new Date().toISOString(),
+    },
+    entries,
+    sidebar: null,
+    generatedAt: new Date().toISOString(),
+    isMock: true,
+  };
+}
+
+export async function buildWikiRepoPayload(
+  rootDir: string,
+  repo: string,
+  options: { refresh?: boolean } = {},
+): Promise<WikiRepoPayload> {
+  const generatedAt = new Date().toISOString();
+
+  if (isMockMode()) return mockPayload();
+
+  const targetDir = await scopeToRepo(rootDir, repo);
+
+  const { remote, error } = await readOriginRemote(targetDir);
+  if (!remote) {
+    const payload: WikiRepoPayload = {
+      repo: null,
+      entries: [],
+      reason: 'no-remote',
+      detail: error || 'This repository has no origin remote',
+      generatedAt,
+      isMock: false,
+    };
+    return payload;
+  }
+
+  const parsed = parseWikiRemote(remote);
+  if (!parsed) {
+    const payload: WikiRepoPayload = {
+      repo: null,
+      entries: [],
+      reason: 'unsupported-remote',
+      detail: `No wiki can be derived from ${redactRemoteUrl(remote)}`,
+      generatedAt,
+      isMock: false,
+    };
+    return payload;
+  }
+
+  const mirror = await ensureWikiMirror(parsed.host, parsed.slug, parsed.wikiRemote, options.refresh === true);
+  if (!mirror.ok) {
+    const payload: WikiRepoPayload = {
+      repo: null,
+      entries: [],
+      reason: mirror.reason,
+      detail: mirror.detail,
+      generatedAt,
+      isMock: false,
+    };
+    return payload;
+  }
+
+  // Probed only now, when the host is known to be reachable and a wiki exists.
+  const provider = await detectWikiProvider(parsed.host);
+  const paths = await listWikiPaths(mirror.mirror.repoDir);
+  const entries = buildWikiEntries(paths);
+
+  // The wiki's own navigation, when the author wrote one: the panel renders its
+  // grouping and labels instead of re-deriving a tree from the file layout. Any
+  // page it does not mention is appended, so nothing becomes unreachable.
+  const sidebarPath = findWikiSidebarPath(paths);
+  let sidebar: WikiNavSection[] | null = null;
+  if (sidebarPath) {
+    const file = await readWikiPage(mirror.mirror.repoDir, sidebarPath);
+    if (file.ok) sidebar = withRemainingPages(parseWikiSidebar(file.text, sidebarPath, entries), entries);
+  }
+
+  const payload: WikiRepoPayload = {
+    repo: {
+      provider,
+      host: parsed.host,
+      slug: parsed.slug,
+      remote: redactRemoteUrl(remote),
+      webUrl: wikiWebUrl(provider, parsed.host, parsed.slug),
+      revision: mirror.mirror.revision,
+      updatedAt: mirror.mirror.updatedAt,
+    },
+    entries,
+    sidebar,
+    generatedAt,
+    isMock: false,
+  };
+  return payload;
+}

package/src/server/lib/wiki/provider.server.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Which wiki host is in front of us.
+ *
+ * The content read needs no provider at all — GitHub and GitLab publish the
+ * same `.wiki.git` — but two things the reader shows do: the label in the header
+ * and the "open in browser" URL, and the two hosts spell a wiki page
+ * differently (`/wiki/Page` against `/-/wikis/Page`).
+ *
+ * `github.com` and `gitlab.com` are decided by name, with no request. Anything
+ * else is probed once per host: a GitLab instance answers `/api/v4/version` with
+ * JSON (401 unauthenticated, 200 with a token), and the self-hosted GitLab this
+ * feature was built against does exactly that. The probe runs only AFTER a wiki
+ * fetch has succeeded, so it never delays the common failure path, and its
+ * verdict — including "not GitLab" — is cached for the life of the process.
+ */
+
+import type { WikiProvider } from '@/shared/types/wiki';
+
+const HOST_PROBE_TIMEOUT_MS = 3_000;
+
+interface HostVerdict {
+  provider: WikiProvider;
+  at: number;
+}
+
+/** One day: a host does not change product between two panel reads. */
+const VERDICT_TTL_MS = 24 * 60 * 60 * 1000;
+
+interface ProviderCacheHost {
+  hosts: Map<string, HostVerdict>;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __kabmoWikiProviders: ProviderCacheHost | undefined;
+}
+
+function cache(): Map<string, HostVerdict> {
+  globalThis.__kabmoWikiProviders ??= { hosts: new Map() };
+  return globalThis.__kabmoWikiProviders.hosts;
+}
+
+function byName(host: string): WikiProvider | null {
+  const lower = host.toLowerCase();
+  if (lower === 'github.com' || lower.endsWith('.github.com')) return 'github';
+  if (lower === 'gitlab.com' || lower.endsWith('.gitlab.com')) return 'gitlab';
+  // A self-hosted instance named after the product (`gitlab.example.com`).
+  if (/(^|[.-])gitlab([.-]|$)/.test(lower)) return 'gitlab';
+  return null;
+}
+
+/** True when the host answers GitLab's version endpoint the way GitLab does. */
+async function answersAsGitlab(host: string): Promise<boolean> {
+  try {
+    const response = await fetch(`https://${host}/api/v4/version`, {
+      method: 'GET',
+      signal: AbortSignal.timeout(HOST_PROBE_TIMEOUT_MS),
+      headers: { accept: 'application/json' },
+    });
+    // 401 is the unauthenticated answer and is as good a signal as 200.
+    if (response.status !== 200 && response.status !== 401) return false;
+    return (response.headers.get('content-type') ?? '').includes('json');
+  } catch {
+    return false;
+  }
+}
+
+export async function detectWikiProvider(host: string): Promise<WikiProvider> {
+  const known = byName(host);
+  if (known) return known;
+
+  const verdicts = cache();
+  const cached = verdicts.get(host);
+  if (cached && Date.now() - cached.at < VERDICT_TTL_MS) return cached.provider;
+
+  const provider: WikiProvider = (await answersAsGitlab(host)) ? 'gitlab' : 'other';
+  verdicts.set(host, { provider, at: Date.now() });
+  return provider;
+}

package/src/server/lib/wiki/remote.test.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The remote → wiki URL mapping.
+ *
+ * Both hosts publish a wiki at `<origin>.wiki.git`, which is the whole reason
+ * one implementation covers them; the cases here are the shapes a real
+ * workspace holds — the public HTTPS remote, the self-hosted GitLab remote that
+ * carries its own basic-auth user, and an SSH remote — plus the ones that must
+ * be refused rather than fetched (a local path, an empty value).
+ *
+ * The credential case is the load-bearing one: the URL that authenticates the
+ * fetch is the URL that must never reach the page.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { parseWikiRemote, redactRemoteUrl, wikiWebUrl } from '@/server/lib/wiki/remote';
+
+describe('parseWikiRemote', () => {
+  test('appends the wiki suffix to an https remote', () => {
+    const parsed = parseWikiRemote('https://github.com/jgraph/drawio.git');
+    expect(parsed).toMatchObject({
+      host: 'github.com',
+      slug: 'jgraph/drawio',
+      projectUrl: 'https://github.com/jgraph/drawio',
+      wikiRemote: 'https://github.com/jgraph/drawio.wiki.git',
+    });
+  });
+
+  test('works on a remote with no .git suffix', () => {
+    expect(parseWikiRemote('https://github.com/rajebdev/outline-cli')?.wikiRemote)
+      .toBe('https://github.com/rajebdev/outline-cli.wiki.git');
+  });
+
+  test('keeps a self-hosted remote’s own credentials on the fetch URL', () => {
+    const parsed = parseWikiRemote('https://user:token@git-rbi.jatismobile.com/jns6_5/drrealhandler.git');
+    expect(parsed?.host).toBe('git-rbi.jatismobile.com');
+    expect(parsed?.slug).toBe('jns6_5/drrealhandler');
+    // The fetch URL authenticates the way the checkout does …
+    expect(parsed?.wikiRemote).toBe('https://user:token@git-rbi.jatismobile.com/jns6_5/drrealhandler.wiki.git');
+    // … and the project URL that leaves the server does not.
+    expect(parsed?.projectUrl).toBe('https://git-rbi.jatismobile.com/jns6_5/drrealhandler');
+  });
+
+  test('keeps a GitLab subgroup in the slug', () => {
+    const parsed = parseWikiRemote('ssh://git@gitlab.com/group/sub/proj.git');
+    expect(parsed?.slug).toBe('group/sub/proj');
+    // The fetch URL keeps the remote's own user, exactly as `git fetch` needs it.
+    expect(parsed?.wikiRemote).toBe('ssh://git@gitlab.com/group/sub/proj.wiki.git');
+  });
+
+  test('accepts an scp-style remote', () => {
+    const parsed = parseWikiRemote('git@github.com:owner/name.git');
+    expect(parsed).toMatchObject({ host: 'github.com', slug: 'owner/name', wikiRemote: 'git@github.com:owner/name.wiki.git' });
+  });
+
+  test('refuses anything a wiki cannot hang off', () => {
+    for (const remote of ['', '   ', '/local/bare/path.git', 'https://github.com/onlyowner', 'not a url']) {
+      expect(parseWikiRemote(remote)).toBe(null);
+    }
+  });
+});
+
+describe('redactRemoteUrl', () => {
+  test('strips the credential and nothing else', () => {
+    expect(redactRemoteUrl('https://user:token@host/o/n.git')).toBe('https://host/o/n.git');
+    expect(redactRemoteUrl('https://host/o/n.git')).toBe('https://host/o/n.git');
+    expect(redactRemoteUrl('git@host:o/n.git')).toBe('git@host:o/n.git');
+  });
+});
+
+describe('wikiWebUrl', () => {
+  test('uses each host’s own wiki path', () => {
+    expect(wikiWebUrl('github', 'github.com', 'jgraph/drawio')).toBe('https://github.com/jgraph/drawio/wiki');
+    expect(wikiWebUrl('gitlab', 'gitlab.com', 'gitlab-org/cli')).toBe('https://gitlab.com/gitlab-org/cli/-/wikis/home');
+  });
+
+  test('says nothing for a host it cannot address', () => {
+    expect(wikiWebUrl('other', 'git.example.test', 'o/n')).toBe(null);
+  });
+});

package/src/server/lib/wiki/remote.ts

@@ -0,0 +1,104 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The git remote → the wiki repository behind it.
+ *
+ * Both GitHub and GitLab publish a project's wiki as a SEPARATE git repository
+ * whose URL is the project's own with `.wiki.git` on the end, so Kabmo
+ * needs no provider API, no token scope and no per-host branch: it appends the
+ * suffix to whatever `origin` already is. That is also why a self-hosted GitLab
+ * (`git-rbi.jatismobile.com/jns6_5/drrealhandler`) works with no code of its own
+ * — verified against the real host, whose `drrealhandler.wiki.git` clones the
+ * same pages its web UI shows.
+ *
+ * The suffix is appended to the remote VERBATIM, credentials and scheme
+ * included, because the fetch has to authenticate the way the checkout does: a
+ * self-hosted GitLab URL in this workspace carries its own basic-auth user, and
+ * an SSH remote has to stay SSH. What travels back to the page is a separate,
+ * credential-free URL — see `redactRemoteUrl`.
+ */
+
+/** A remote, split into what the fetch needs and what the reader may see. */
+export interface ParsedWikiRemote {
+  /** Host of the remote, port included when it has one (`github.com`). */
+  host: string;
+  /** `owner/name`, subgroups included, without `.git`. */
+  slug: string;
+  /** Credential-free `https://host/owner/name` of the PROJECT. */
+  projectUrl: string;
+  /** The wiki repository, in the remote's own scheme and with its own credentials. */
+  wikiRemote: string;
+}
+
+/** `git@github.com:owner/name.git` — a scheme-less scp-style remote. */
+const SCP_LIKE_RE = /^(?:[^@/]+@)?([^:/]+):(.+)$/;
+
+function stripGitSuffix(value: string): string {
+  return value.replace(/\/+$/, '').replace(/\.git$/i, '');
+}
+
+/**
+ * Parse one git remote URL into its wiki parts, or null when it is not a URL a
+ * wiki can hang off (a local path, an empty value, a bare host).
+ *
+ * Accepts the three shapes git itself accepts: `https://host/o/n.git`,
+ * `ssh://git@host/o/n.git`, and `git@host:o/n.git`.
+ */
+export function parseWikiRemote(rawRemote: string | null | undefined): ParsedWikiRemote | null {
+  const raw = (rawRemote ?? '').trim();
+  if (!raw || raw.includes('://') === false && !SCP_LIKE_RE.test(raw)) return null;
+
+  let host: string;
+  let pathPart: string;
+  let scheme = 'https';
+
+  const scp = raw.includes('://') ? null : raw.match(SCP_LIKE_RE);
+  if (scp) {
+    host = scp[1];
+    pathPart = scp[2];
+  } else {
+    let url: URL;
+    try {
+      url = new URL(raw);
+    } catch {
+      return null;
+    }
+    // `new URL` lower-cases the host and drops the default port, so the same
+    // remote spelled two ways keys one cache entry.
+    host = url.host;
+    scheme = url.protocol === 'http:' ? 'http' : 'https';
+    pathPart = url.pathname;
+  }
+
+  const slug = stripGitSuffix(pathPart.replace(/^\/+/, ''));
+  // A wiki needs an owner and a project; a local path or a bare host is not one.
+  if (!host || slug.split('/').filter(Boolean).length < 2) return null;
+
+  return {
+    host,
+    slug,
+    projectUrl: `${scheme}://${host}/${slug}`,
+    wikiRemote: `${stripGitSuffix(raw)}.wiki.git`,
+  };
+}
+
+/**
+ * The credential-free form of a remote, for anything that leaves the server.
+ *
+ * `https://user:token@host/o/n.git` is how a self-hosted GitLab authenticates
+ * from this workspace, and echoing it back would put a secret in the DOM, the
+ * devtools network tab and any screenshot of the panel.
+ */
+export function redactRemoteUrl(rawRemote: string): string {
+  return rawRemote.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^@/]*@/i, '$1');
+}
+
+/** The wiki's web page, per provider. Null when the host is not recognised. */
+export function wikiWebUrl(provider: 'github' | 'gitlab' | 'other', host: string, slug: string): string | null {
+  if (provider === 'github') return `https://${host}/${slug}/wiki`;
+  if (provider === 'gitlab') return `https://${host}/${slug}/-/wikis/home`;
+  return null;
+}