@cat-factory/app 0.248.0 → 0.250.0

package/app/stores/github.spec.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, type Mock } from 'vitest'
 import { useGitHubStore } from '~/stores/github'
 import { useWorkspaceStore } from '~/stores/workspace'
-import type { GitHubConnection, VcsConnectOption } from '~/types/domain'
+import type { GitHubConnection, GitHubRepo, VcsConnectOption } from '~/types/domain'
 
 // The VCS connect surface of the (single, GitHub-shaped) repo store: which connect methods the
 // deployment offers, the per-workspace GitLab PAT connect, and the provider-routed disconnect.
@@ -16,6 +16,7 @@ function connection(overrides: Partial<GitHubConnection> = {}): GitHubConnection
     connectedAt: 1,
     provider: 'github',
     method: 'app',
+    webUrl: 'https://github.com',
     canCreateRepos: false,
     canManageWorkflows: true,
     ...overrides,
@@ -45,7 +46,9 @@ describe('github store — VCS connect capability', () => {
     stubApi({
       getGitHubConnection: vi.fn().mockResolvedValue({ connection: null }),
       listVcsConnectOptions: vi.fn().mockResolvedValue({
-        options: [{ provider: 'gitlab', method: 'pat' }] satisfies VcsConnectOption[],
+        options: [
+          { provider: 'gitlab', method: 'pat', webUrl: 'https://gitlab.acme.dev' },
+        ] satisfies VcsConnectOption[],
       }),
     })
     const github = storeWithWorkspace()
@@ -71,8 +74,8 @@ describe('github store — VCS connect capability', () => {
         .mockResolvedValue({ connection: connection({ provider: 'gitlab', method: 'pat' }) }),
       listVcsConnectOptions: vi.fn().mockResolvedValue({
         options: [
-          { provider: 'github', method: 'app' },
-          { provider: 'gitlab', method: 'pat' },
+          { provider: 'github', method: 'app', webUrl: 'https://github.com' },
+          { provider: 'gitlab', method: 'pat', webUrl: 'https://gitlab.acme.dev' },
         ] satisfies VcsConnectOption[],
       }),
     })
@@ -107,8 +110,8 @@ describe('github store — VCS connect capability', () => {
       getGitHubConnection: vi.fn().mockResolvedValue({ connection: null }),
       listVcsConnectOptions: vi.fn().mockResolvedValue({
         options: [
-          { provider: 'github', method: 'app' },
-          { provider: 'gitlab', method: 'pat' },
+          { provider: 'github', method: 'app', webUrl: 'https://github.com' },
+          { provider: 'gitlab', method: 'pat', webUrl: 'https://gitlab.acme.dev' },
         ] satisfies VcsConnectOption[],
       }),
     })
@@ -174,4 +177,111 @@ describe('github store — VCS connect capability', () => {
     expect(api.disconnectGitHub).toHaveBeenCalledWith('ws-1')
     expect(api.disconnectGitLab).not.toHaveBeenCalled()
   })
+
+  // The host a surface links to, before and after binding. `surfaceProvider` names the brand;
+  // this names the instance, and the two must come from the same place or the copy and the link
+  // disagree (the bootstrap modal renders both).
+  it('takes the host from the connect option before binding, and from the connection after', async () => {
+    stubApi({
+      getGitHubConnection: vi.fn().mockResolvedValue({ connection: null }),
+      listVcsConnectOptions: vi.fn().mockResolvedValue({
+        options: [
+          { provider: 'gitlab', method: 'pat', webUrl: 'https://gitlab.acme.dev' },
+        ] satisfies VcsConnectOption[],
+      }),
+      connectGitLab: vi
+        .fn()
+        .mockResolvedValue(
+          connection({ provider: 'gitlab', method: 'pat', webUrl: 'https://gitlab.acme.dev' }),
+        ),
+    })
+    const github = storeWithWorkspace()
+
+    await github.probe()
+    expect(github.surfaceWebUrl).toBe('https://gitlab.acme.dev')
+
+    await github.connectGitLab('glpat-secret')
+    expect(github.surfaceWebUrl).toBe('https://gitlab.acme.dev')
+  })
+
+  it('has no host to offer when several providers are connectable and none is bound', async () => {
+    stubApi({
+      getGitHubConnection: vi.fn().mockResolvedValue({ connection: null }),
+      listVcsConnectOptions: vi.fn().mockResolvedValue({
+        options: [
+          { provider: 'github', method: 'app', webUrl: 'https://github.com' },
+          { provider: 'gitlab', method: 'pat', webUrl: 'https://gitlab.acme.dev' },
+        ] satisfies VcsConnectOption[],
+      }),
+    })
+    const github = storeWithWorkspace()
+
+    await github.probe()
+
+    expect(github.surfaceWebUrl).toBeNull()
+  })
+})
+
+describe('github store — repo web links', () => {
+  const repo = (over: Partial<GitHubRepo> = {}): GitHubRepo => ({
+    githubId: 1,
+    installationId: 42,
+    owner: 'acme',
+    name: 'api',
+    defaultBranch: 'main',
+    private: false,
+    syncedAt: 0,
+    ...over,
+  })
+
+  async function storeWith(conn: GitHubConnection, repos: GitHubRepo[]) {
+    stubApi({
+      getGitHubConnection: vi.fn().mockResolvedValue({ connection: conn }),
+      listVcsConnectOptions: vi.fn().mockResolvedValue({ options: [] }),
+      listGitHubRepos: vi.fn().mockResolvedValue(repos),
+    })
+    const github = storeWithWorkspace()
+    await github.probe()
+    await github.load()
+    return github
+  }
+
+  // Every one of these used to be hand-built from `https://github.com`, which is right for
+  // exactly one deployment shape. The host now comes off the connection and the path shape off
+  // the repo row's own provider.
+  it('builds links on the connected instance, in the repo provider’s own shape', async () => {
+    const github = await storeWith(
+      connection({ provider: 'gitlab', method: 'pat', webUrl: 'https://gitlab.acme.dev' }),
+      [repo({ provider: 'gitlab', owner: 'acme/platform' })],
+    )
+
+    expect(github.repoUrl(1)).toBe('https://gitlab.acme.dev/acme/platform/api')
+    expect(github.pullUrl({ repoGithubId: 1, number: 7 } as never)).toBe(
+      'https://gitlab.acme.dev/acme/platform/api/-/merge_requests/7',
+    )
+    expect(github.issueUrl({ repoGithubId: 1, number: 3 } as never)).toBe(
+      'https://gitlab.acme.dev/acme/platform/api/-/issues/3',
+    )
+    expect(github.branchUrl(1, 'feat/sso')).toBe(
+      'https://gitlab.acme.dev/acme/platform/api/-/tree/feat/sso',
+    )
+  })
+
+  it('withholds every link when the deployment could not name its host', async () => {
+    const github = await storeWith(connection({ webUrl: null }), [repo()])
+
+    expect(github.repoUrl(1)).toBeNull()
+    expect(github.pullUrl({ repoGithubId: 1, number: 7 } as never)).toBeNull()
+    expect(github.branchUrl(1, 'main')).toBeNull()
+  })
+
+  // A row written before the discriminator existed is GitHub, so its links keep the GitHub shape
+  // rather than falling through to whatever the connection happens to say.
+  it('treats a repo row with no provider as GitHub', async () => {
+    const github = await storeWith(connection(), [repo()])
+
+    expect(github.pullUrl({ repoGithubId: 1, number: 7 } as never)).toBe(
+      'https://github.com/acme/api/pull/7',
+    )
+  })
 })

package/app/stores/github.ts

@@ -10,7 +10,9 @@ import type {
   GitHubRepo,
   RepoTreeEntry,
   VcsConnectOption,
+  VcsProvider,
 } from '~/types/domain'
+import { branchWebUrl, issueWebUrl, pullWebUrl, repoWebUrl } from '~/utils/vcs'
 import { useSingleFlightProbe } from '~/composables/useSingleFlightProbe'
 import { useUpsertList } from '~/composables/useUpsertList'
 import { useWorkspaceStore } from '~/stores/workspace'
@@ -94,18 +96,32 @@ export const useGitHubStore = defineStore('github', () => {
     return issues.value.filter((i) => i.repoGithubId === repoGithubId)
   }
 
-  /** Build the github.com URL for a repo / PR / issue from the projection row. */
+  // Web links for a repo / pull request / issue / branch, built from the connection's own host
+  // (`webUrl`) and the repo row's provider. Every one of these used to be a hand-built
+  // `https://github.com/…`, which is only right for a github.com deployment: a self-managed
+  // GitLab or GitHub Enterprise workspace was linked to whatever the public instance serves at
+  // that path. Null when the deployment could not name its host, so the caller withholds the
+  // link rather than pointing at an instance the repo does not live on.
   function repoUrl(repoGithubId: number): string | null {
     const r = repoFor(repoGithubId)
-    return r ? `https://github.com/${r.owner}/${r.name}` : null
+    return r ? repoWebUrl(connection.value?.webUrl, r) : null
+  }
+  /** The provider a projected row belongs to; a row predating the discriminator is GitHub. */
+  function providerOfRepo(repoGithubId: number): VcsProvider {
+    return repoFor(repoGithubId)?.provider ?? 'github'
   }
   function pullUrl(pr: GitHubPullRequest): string | null {
-    const base = repoUrl(pr.repoGithubId)
-    return base ? `${base}/pull/${pr.number}` : null
+    return pullWebUrl(providerOfRepo(pr.repoGithubId), repoUrl(pr.repoGithubId), pr.number)
   }
   function issueUrl(issue: GitHubIssue): string | null {
-    const base = repoUrl(issue.repoGithubId)
-    return base ? `${base}/issues/${issue.number}` : null
+    return issueWebUrl(
+      providerOfRepo(issue.repoGithubId),
+      repoUrl(issue.repoGithubId),
+      issue.number,
+    )
+  }
+  function branchUrl(repoGithubId: number, branch: string): string | null {
+    return branchWebUrl(providerOfRepo(repoGithubId), repoUrl(repoGithubId), branch)
   }
 
   /**
@@ -246,6 +262,7 @@ export const useGitHubStore = defineStore('github', () => {
     repoUrl,
     pullUrl,
     issueUrl,
+    branchUrl,
     probe,
     ensureProbed,
     load,

package/app/stores/ui/modals.ts

@@ -192,6 +192,11 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
   // opened standalone, and the modal offers every container on the board.
   const bugHunt = ref<{ source: TaskSourceKind | null; containerId: string | null } | null>(null)
 
+  // Start-from-design: paste a design link, and the resolved reference is staged onto a new task
+  // in `frameId`. `frameId` is always present — the affordance lives on a frame header, and the
+  // flow ends in the add-task form, which needs a container to create in.
+  const startFromDesign = ref<{ frameId: string } | null>(null)
+
   // Add-task modal: the container (service frame or module) a new task is being
   // added to, or null when closed. The user types the title + description; nothing
   // is launched until they explicitly start the created task.
@@ -266,6 +271,13 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
   function closeBugHunt() {
     bugHunt.value = null
   }
+  function openStartFromDesign(frameId: string) {
+    resetHubReturn()
+    startFromDesign.value = { frameId }
+  }
+  function closeStartFromDesign() {
+    startFromDesign.value = null
+  }
   function openAddTask(containerId: string, prefill: AddTaskPrefill | null = null) {
     addTaskPrefill.value = prefill
     addTaskContainerId.value = containerId
@@ -301,6 +313,7 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
     taskConnect,
     taskImport,
     bugHunt,
+    startFromDesign,
     addTaskContainerId,
     addTaskPrefill,
     reviewFrictionContext,
@@ -320,6 +333,8 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
     closeTaskImport,
     openBugHunt,
     closeBugHunt,
+    openStartFromDesign,
+    closeStartFromDesign,
     openAddTask,
     closeAddTask,
     openReviewFriction,

package/app/utils/vcs.spec.ts

@@ -1,18 +1,23 @@
 import { describe, it, expect } from 'vitest'
 import {
   appInstallationManageUrl,
+  branchWebUrl,
+  issueWebUrl,
   newRepoUrl,
+  pullWebUrl,
+  repoWebUrl,
   VCS_PROVIDER_ICONS,
   VCS_PROVIDER_LABELS,
-  VCS_PROVIDER_TOKEN_URLS,
+  vcsTokenCreateUrl,
 } from './vcs'
 import type { GitHubConnection, VcsProvider } from '~/types/domain'
 
 /**
- * The one place VCS presentation switches on the provider. What is pinned here is the pair of
+ * The one place VCS presentation switches on the provider. What is pinned here is the set of
  * decisions a component must never make for itself: which affordances belong to a GitHub-App
- * installation (and therefore vanish on a pasted token), and which host page a manual
- * repo-creation link may open, including the hosts it must refuse to guess at.
+ * installation (and therefore vanish on a pasted token), how each provider addresses a merge
+ * request / issue / branch, and which links may fall back to a provider's public instance when
+ * the deployment could not name its own host — one may, the rest must withhold.
  */
 const connection = (over: Partial<GitHubConnection> = {}): GitHubConnection => ({
   installationId: 42,
@@ -21,6 +26,7 @@ const connection = (over: Partial<GitHubConnection> = {}): GitHubConnection => (
   connectedAt: 0,
   provider: 'github',
   method: 'app',
+  webUrl: 'https://github.com',
   canCreateRepos: false,
   canManageWorkflows: true,
   ...over,
@@ -39,6 +45,14 @@ describe('appInstallationManageUrl', () => {
     )
   })
 
+  // A GitHub Enterprise Server installation's settings live on that server, and its installation
+  // id means nothing anywhere else.
+  it('links an Enterprise installation to its own host', () => {
+    expect(appInstallationManageUrl(connection({ webUrl: 'https://ghe.acme.dev' }))).toBe(
+      'https://ghe.acme.dev/settings/installations/42',
+    )
+  })
+
   // The whole point of the helper: a pasted token has no installation, so there is no page to
   // send the user to. Both modals used to build the github.com URL from the connection
   // unconditionally, which put a "Grant the App access" button that 404s in front of every
@@ -52,6 +66,10 @@ describe('appInstallationManageUrl', () => {
     ).toBeUndefined()
   })
 
+  it('has no URL when the deployment could not name the host', () => {
+    expect(appInstallationManageUrl(connection({ webUrl: null }))).toBeUndefined()
+  })
+
   it('has no URL when there is no connection', () => {
     expect(appInstallationManageUrl(null)).toBeUndefined()
   })
@@ -60,7 +78,8 @@ describe('appInstallationManageUrl', () => {
 describe('newRepoUrl', () => {
   it('prefills the GitHub new-repository form with everything the caller knows', () => {
     const url = new URL(
-      newRepoUrl('github', { owner: 'acme', name: 'api', private: true }) ?? 'about:blank',
+      newRepoUrl('github', 'https://github.com', { owner: 'acme', name: 'api', private: true }) ??
+        'about:blank',
     )
     expect(url.origin + url.pathname).toBe('https://github.com/new')
     expect(url.searchParams.get('owner')).toBe('acme')
@@ -69,22 +88,94 @@ describe('newRepoUrl', () => {
   })
 
   it('omits what the caller has not filled in yet, and marks a public repo public', () => {
-    const url = new URL(newRepoUrl('github', { name: '', private: false }) ?? 'about:blank')
+    const url = new URL(
+      newRepoUrl('github', 'https://github.com', { name: '', private: false }) ?? 'about:blank',
+    )
     expect(url.searchParams.has('owner')).toBe(false)
     expect(url.searchParams.has('name')).toBe(false)
     expect(url.searchParams.get('visibility')).toBe('public')
   })
 
-  // A deployment may be bound to any self-hosted GitLab and nothing on the wire names its web
-  // host yet, so there is no page this can honestly open. Withheld rather than guessed at:
-  // gitlab.com would look like it worked, and the user would create the project on a server
-  // the bootstrap run never pushes to.
-  it('withholds a page for GitLab, whose instance the SPA cannot name', () => {
-    expect(newRepoUrl('gitlab', { name: 'api', private: false })).toBeUndefined()
+  // Now that the connection states its host, a self-managed GitLab gets the button back — on its
+  // OWN instance. GitLab's form takes no prefill, so it is the bare page.
+  it('opens the new-project page on the GitLab instance the workspace is bound to', () => {
+    expect(newRepoUrl('gitlab', 'https://gitlab.acme.dev', { name: 'api', private: false })).toBe(
+      'https://gitlab.acme.dev/projects/new',
+    )
+  })
+
+  // Withheld rather than guessed at: the public instance would look like it worked, and the user
+  // would create the project on a server the bootstrap run never pushes to.
+  it('withholds a page when the deployment could not name a host', () => {
+    expect(newRepoUrl('gitlab', null, { name: 'api', private: false })).toBeUndefined()
   })
 
   it('withholds a page when no provider is resolved', () => {
-    expect(newRepoUrl(null, { name: 'api', private: false })).toBeUndefined()
+    expect(
+      newRepoUrl(null, 'https://gitlab.acme.dev', { name: 'api', private: false }),
+    ).toBeUndefined()
+  })
+})
+
+describe('repo / pull / issue / branch links', () => {
+  const repo = { owner: 'acme/platform', name: 'api' }
+
+  // The repo path itself is provider-neutral: `owner` already carries GitLab's full group path,
+  // nested groups included. Only what hangs off it differs.
+  it('builds a repo page under the connection’s own host', () => {
+    expect(repoWebUrl('https://gitlab.acme.dev', repo)).toBe(
+      'https://gitlab.acme.dev/acme/platform/api',
+    )
+    expect(repoWebUrl('https://github.com/', { owner: 'acme', name: 'api' })).toBe(
+      'https://github.com/acme/api',
+    )
+  })
+
+  it('addresses a pull request and a merge request the way each provider does', () => {
+    const base = 'https://gitlab.acme.dev/acme/api'
+    expect(pullWebUrl('gitlab', base, 7)).toBe(`${base}/-/merge_requests/7`)
+    expect(pullWebUrl('github', 'https://github.com/acme/api', 7)).toBe(
+      'https://github.com/acme/api/pull/7',
+    )
+  })
+
+  it('addresses an issue and a branch the way each provider does', () => {
+    const base = 'https://gitlab.acme.dev/acme/api'
+    expect(issueWebUrl('gitlab', base, 3)).toBe(`${base}/-/issues/3`)
+    expect(branchWebUrl('gitlab', base, 'feat/sso')).toBe(`${base}/-/tree/feat/sso`)
+    expect(issueWebUrl('github', 'https://github.com/acme/api', 3)).toBe(
+      'https://github.com/acme/api/issues/3',
+    )
+    expect(branchWebUrl('github', 'https://github.com/acme/api', 'feat/sso')).toBe(
+      'https://github.com/acme/api/tree/feat/sso',
+    )
+  })
+
+  // With no host there is no repo page, and everything built on one goes with it rather than
+  // being rendered against a guessed instance.
+  it('withholds every link when the host is unknown', () => {
+    expect(repoWebUrl(null, repo)).toBeNull()
+    expect(pullWebUrl('gitlab', null, 7)).toBeNull()
+    expect(issueWebUrl('gitlab', null, 3)).toBeNull()
+    expect(branchWebUrl('gitlab', null, 'main')).toBeNull()
+  })
+})
+
+describe('vcsTokenCreateUrl', () => {
+  it('points at the token page on the instance being connected', () => {
+    expect(vcsTokenCreateUrl('gitlab', 'https://gitlab.acme.dev')).toBe(
+      'https://gitlab.acme.dev/-/user_settings/personal_access_tokens',
+    )
+  })
+
+  // The one builder that may fall back: it renders during connect (and on the sign-in screen,
+  // where nothing is connected at all), and a settings page on the wrong instance costs a click
+  // rather than a run.
+  it('falls back to the provider’s public instance when no host is known', () => {
+    expect(vcsTokenCreateUrl('gitlab')).toBe(
+      'https://gitlab.com/-/user_settings/personal_access_tokens',
+    )
+    expect(vcsTokenCreateUrl('github', null)).toBe('https://github.com/settings/tokens/new')
   })
 })
 
@@ -96,6 +187,6 @@ describe('provider presentation maps', () => {
   it.each(providers)('has a label, icon and token URL for %s', (provider) => {
     expect(VCS_PROVIDER_LABELS[provider]).toBeTruthy()
     expect(VCS_PROVIDER_ICONS[provider]).toMatch(/^i-lucide-/)
-    expect(VCS_PROVIDER_TOKEN_URLS[provider]).toMatch(/^https:\/\//)
+    expect(vcsTokenCreateUrl(provider)).toMatch(/^https:\/\//)
   })
 })

package/app/utils/vcs.ts

@@ -11,6 +11,13 @@ import type { GitHubConnection, VcsProvider } from '~/types/domain'
 //
 // Each map is an exhaustive `Record<VcsProvider, …>`: adding a provider to the union fails
 // the typecheck here instead of silently rendering a GitHub icon for it.
+//
+// EVERY link builder here takes the connection's `webUrl` — the browser-facing host the
+// backend derived from the instance the workspace is actually bound to. The SPA used to
+// hand-build `https://github.com/…`, which is right for exactly one deployment shape and sends
+// a self-managed GitLab (or GitHub Enterprise) user to whatever lives at that path on the
+// public instance. A null host means the deployment could not name one, and a builder that
+// needs one answers `undefined` so its caller drops the affordance.
 // ---------------------------------------------------------------------------
 
 /** Brand name, as rendered in titles and buttons. */
@@ -24,30 +31,58 @@ export const VCS_PROVIDER_ICONS: Record<VcsProvider, string> = {
   gitlab: 'i-lucide-gitlab',
 }
 
-/** Where a user creates a personal access token for the provider (the PAT connect flow). */
-export const VCS_PROVIDER_TOKEN_URLS: Record<VcsProvider, string> = {
-  github: 'https://github.com/settings/tokens/new',
-  gitlab: 'https://gitlab.com/-/user_settings/personal_access_tokens',
+/**
+ * The public instance of each provider, used ONLY where no host is known and a wrong link costs
+ * nothing but a click: the token-creation page during connect (see {@link vcsTokenCreateUrl}).
+ * Never for a link to a repo, a project or a namespace, where the public instance may well
+ * serve somebody else's page under the same path.
+ */
+const VCS_PROVIDER_PUBLIC_WEB_URLS: Record<VcsProvider, string> = {
+  github: 'https://github.com',
+  gitlab: 'https://gitlab.com',
+}
+
+/** Where a user creates a personal access token, relative to the instance's web root. */
+const TOKEN_SETTINGS_PATHS: Record<VcsProvider, string> = {
+  github: '/settings/tokens/new',
+  gitlab: '/-/user_settings/personal_access_tokens',
+}
+
+/** Where a user creates a repository/project by hand, relative to the instance's web root. */
+const NEW_REPO_PATHS: Record<VcsProvider, string> = {
+  github: '/new',
+  gitlab: '/projects/new',
+}
+
+/** How each provider addresses a pull/merge request and an issue under a repo's web path. */
+const PULL_PATHS: Record<VcsProvider, (n: number) => string> = {
+  github: (n) => `/pull/${n}`,
+  gitlab: (n) => `/-/merge_requests/${n}`,
+}
+const ISSUE_PATHS: Record<VcsProvider, (n: number) => string> = {
+  github: (n) => `/issues/${n}`,
+  gitlab: (n) => `/-/issues/${n}`,
+}
+const BRANCH_PATHS: Record<VcsProvider, (branch: string) => string> = {
+  github: (branch) => `/tree/${branch}`,
+  gitlab: (branch) => `/-/tree/${branch}`,
+}
+
+/** Strip a trailing slash so a host and a path never join into a double slash. */
+function root(webUrl: string): string {
+  return webUrl.replace(/\/+$/, '')
 }
 
 /**
- * Where a user creates a repository by hand, for the flows that need one to exist before a run
- * can target it, or `null` where the SPA cannot name the instance the workspace is connected
- * to, in which case the affordance is WITHHELD rather than pointed somewhere plausible.
+ * Where a user creates a personal access token on the instance they are connecting.
  *
- * `gitlab` is null for that reason: a deployment may be bound to any self-hosted instance and
- * nothing on the wire carries its web host yet (the connection is the proposed carrier; see
- * the initiative tracker's slice 5). `https://gitlab.com/projects/new` would be a guess about
- * which server the user's projects live on, and the cost of being wrong is not a dead link: a
- * project created on the wrong instance looks like success until the bootstrap push cannot
- * find it. This is the same rule the callers already apply when no provider is resolved at
- * all, so the two cases collapse into {@link newRepoUrl} returning `undefined`.
- *
- * A `Record` rather than a switch so a provider joining the union has to state its answer.
+ * The one builder that FALLS BACK to the provider's public instance when no host is known,
+ * deliberately unlike its repo-facing siblings: this renders during connect, before anything is
+ * bound, and the cost of being wrong is a settings page that isn't theirs — a click, noticed
+ * immediately. A wrong REPOSITORY link is silent and can cost a run, so those withhold instead.
  */
-const NEW_REPO_PAGES: Record<VcsProvider, string | null> = {
-  github: 'https://github.com/new',
-  gitlab: null,
+export function vcsTokenCreateUrl(provider: VcsProvider, webUrl?: string | null): string {
+  return `${root(webUrl || VCS_PROVIDER_PUBLIC_WEB_URLS[provider])}${TOKEN_SETTINGS_PATHS[provider]}`
 }
 
 /**
@@ -58,20 +93,27 @@ const NEW_REPO_PAGES: Record<VcsProvider, string | null> = {
  * token's scope and the user's project membership on the host, so there is nothing to link
  * to and the callers drop the affordance rather than pointing at a URL that 404s. Keyed on the
  * connection's own `method` (see the contract) rather than on `provider`, and asked as
- * `=== 'app'` so anything that is not an App installation withholds the link.
+ * `=== 'app'` so anything that is not an App installation withholds the link — as does an
+ * installation whose host the deployment could not name, since an installation id means nothing
+ * on an instance other than its own.
  */
 export function appInstallationManageUrl(connection: GitHubConnection | null): string | undefined {
-  if (!connection || connection.method !== 'app') return undefined
+  if (!connection || connection.method !== 'app' || !connection.webUrl) return undefined
+  const base = root(connection.webUrl)
   return connection.targetType === 'Organization'
-    ? `https://github.com/organizations/${connection.accountLogin}/settings/installations/${connection.installationId}`
-    : `https://github.com/settings/installations/${connection.installationId}`
+    ? `${base}/organizations/${connection.accountLogin}/settings/installations/${connection.installationId}`
+    : `${base}/settings/installations/${connection.installationId}`
 }
 
 /**
- * The host's new-repository page for a manual create, or `undefined` where there is no page
- * this deployment can honestly send the user to (see {@link NEW_REPO_PAGES}), including a
- * null `provider`, which is what a surface rendering before anything is connected has when
- * the deployment offers several. A caller that gets `undefined` hides the affordance.
+ * The host's new-repository page for a manual create, or `undefined` when the deployment could
+ * not name the instance (a null/absent `webUrl`) or no provider is resolved at all, which is
+ * what a surface rendering before anything is connected has when the deployment offers several.
+ * A caller that gets `undefined` hides the affordance.
+ *
+ * Withholding is the whole point: a project created on the wrong instance looks like success
+ * until the bootstrap push cannot find it, which is a failed run rather than a dead link. Now
+ * that the host is on the wire, a GitLab deployment that HAS one gets the button back.
  *
  * GitHub's form is the only one that takes a prefill, so what the bootstrap flow already
  * knows is carried over and the user creates the right repo in one click. `visibility` is
@@ -79,10 +121,11 @@ export function appInstallationManageUrl(connection: GitHubConnection | null): s
  */
 export function newRepoUrl(
   provider: VcsProvider | null,
+  webUrl: string | null | undefined,
   prefill: { owner?: string; name?: string; description?: string; private: boolean },
 ): string | undefined {
-  const page = provider ? NEW_REPO_PAGES[provider] : null
-  if (page === null) return undefined
+  if (!provider || !webUrl) return undefined
+  const page = `${root(webUrl)}${NEW_REPO_PATHS[provider]}`
   if (provider !== 'github') return page
   const params = new URLSearchParams()
   if (prefill.owner) params.set('owner', prefill.owner)
@@ -91,3 +134,44 @@ export function newRepoUrl(
   params.set('visibility', prefill.private ? 'private' : 'public')
   return `${page}?${params.toString()}`
 }
+
+/**
+ * A repository's page on the instance it lives on, or null when no host is known.
+ *
+ * `owner` is the full namespace on both providers (GitHub's `owner`, GitLab's group path,
+ * nested groups included), so the repo path itself needs no provider switch — only what hangs
+ * off it does.
+ */
+export function repoWebUrl(
+  webUrl: string | null | undefined,
+  repo: { owner: string; name: string },
+): string | null {
+  return webUrl ? `${root(webUrl)}/${repo.owner}/${repo.name}` : null
+}
+
+/** A pull request (GitHub) / merge request (GitLab) under a repo's page. */
+export function pullWebUrl(
+  provider: VcsProvider,
+  repoUrl: string | null,
+  pullNumber: number,
+): string | null {
+  return repoUrl ? `${repoUrl}${PULL_PATHS[provider](pullNumber)}` : null
+}
+
+/** An issue under a repo's page. */
+export function issueWebUrl(
+  provider: VcsProvider,
+  repoUrl: string | null,
+  issueNumber: number,
+): string | null {
+  return repoUrl ? `${repoUrl}${ISSUE_PATHS[provider](issueNumber)}` : null
+}
+
+/** A branch's file listing under a repo's page. */
+export function branchWebUrl(
+  provider: VcsProvider,
+  repoUrl: string | null,
+  branch: string,
+): string | null {
+  return repoUrl ? `${repoUrl}${BRANCH_PATHS[provider](branch)}` : null
+}