@cat-factory/app 0.215.1 → 0.216.0

package/app/stores/github.ts

@@ -10,7 +10,6 @@ import type {
   GitHubRepo,
   RepoTreeEntry,
   VcsConnectOption,
-  VcsProvider,
 } from '~/types/domain'
 import { useSingleFlightProbe } from '~/composables/useSingleFlightProbe'
 import { useUpsertList } from '~/composables/useUpsertList'
@@ -19,7 +18,7 @@ import { useServicesStore } from '~/stores/services'
 import { pullKey, type GitHubStoreContext } from '~/stores/github/context'
 import { createGitHubConnectionActions } from '~/stores/github/connection'
 import { createGitHubRepoActions } from '~/stores/github/repoActions'
-import { createVcsConnectActions } from '~/stores/github/vcsConnect'
+import { createVcsConnectActions, createVcsProviderViews } from '~/stores/github/vcsConnect'
 
 /**
  * GitHub integration state: the workspace's App installation, the projected
@@ -63,26 +62,6 @@ export const useGitHubStore = defineStore('github', () => {
   const syncing = ref(false)
 
   const connected = computed(() => connection.value !== null)
-  /**
-   * The provider backing the current connection. Presentation (labels, icons, host/URL shapes)
-   * keys off this; a connection from a backend predating the discriminator is a GitHub App one.
-   */
-  const provider = computed<VcsProvider>(() => connection.value?.provider ?? 'github')
-  /** Whether the deployment can serve a GitHub App connect / a per-workspace GitLab PAT connect. */
-  const canConnectGitHubApp = computed(() =>
-    connectOptions.value.some((o) => o.provider === 'github' && o.method === 'app'),
-  )
-  const canConnectGitLabPat = computed(() =>
-    connectOptions.value.some((o) => o.provider === 'gitlab' && o.method === 'pat'),
-  )
-  /**
-   * The single provider this deployment can connect, or null when it offers several (or none) —
-   * what the connect copy keys off so a one-provider deployment never says "choose a provider".
-   */
-  const soleConnectProvider = computed<VcsProvider | null>(() => {
-    const providers = new Set(connectOptions.value.map((o) => o.provider))
-    return providers.size === 1 ? [...providers][0]! : null
-  })
   /** Whether cat-factory can create repos under the connected account itself. */
   const canCreateRepos = computed(() => connection.value?.canCreateRepos === true)
   /**
@@ -219,6 +198,9 @@ export const useGitHubStore = defineStore('github', () => {
   const connectionActions = createGitHubConnectionActions(context)
   const repoActions = createGitHubRepoActions(context)
   const vcsConnectActions = createVcsConnectActions(context)
+  // The derived "which provider" questions, beside the connect actions that populate what they
+  // read (see `createVcsProviderViews` for why `provider` and `surfaceProvider` differ).
+  const providerViews = createVcsProviderViews(context)
 
   /**
    * Drop the per-workspace projection + connection state (called on workspace switch)
@@ -254,10 +236,7 @@ export const useGitHubStore = defineStore('github', () => {
     loading,
     syncing,
     connected,
-    provider,
-    canConnectGitHubApp,
-    canConnectGitLabPat,
-    soleConnectProvider,
+    ...providerViews,
     canCreateRepos,
     missingWorkflowsPermission,
     repoFor,

package/app/stores/inputGate.ts

@@ -0,0 +1,58 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type { ResolveInputGateChoice, RunInputGate } from '@cat-factory/contracts'
+import { useApi } from '~/composables/useApi'
+import { useWorkspaceStore } from '~/stores/workspace'
+import { useExecutionStore } from '~/stores/execution'
+
+/**
+ * The PRE-TOKEN INPUT GATE's action surface. The verdict itself lives on the run
+ * (`instance.inputGate`) and is kept fresh by the execution stream, so this store only wraps the
+ * `resolve` action, tracks the in-flight state so the notice can disable its buttons, and
+ * reflects the returned verdict back so the UI updates before the stream echoes it.
+ *
+ * The echo goes through {@link ExecutionStore.echoAfter} rather than a bare assignment: a
+ * successful resolve WAKES THE DURABLE DRIVER, whose next emit routinely beats this HTTP
+ * response, so an unguarded write would put the released run back into `blocked` and, if the
+ * run then parks on something else, leave it there with nothing left to emit.
+ */
+export const useInputGateStore = defineStore('inputGate', () => {
+  const api = useApi()
+  const workspace = useWorkspaceStore()
+  const execution = useExecutionStore()
+
+  /** True while a resolve call is in flight (drives the buttons' spinner / disabled state). */
+  const resolving = ref(false)
+  /** The last error message from an action, surfaced inline; cleared on the next action. */
+  const error = ref<string | null>(null)
+
+  /**
+   * Resolve the parked gate. `recheck` re-evaluates the task as it now stands and releases the
+   * run only if the blocking gaps are genuinely gone. A still-blocked verdict comes back as an
+   * ordinary 200 with refreshed findings rather than an error, because nothing went wrong: the
+   * task is just not fixed yet. `proceed` waives the findings.
+   */
+  async function resolve(
+    executionId: string,
+    choice: ResolveInputGateChoice,
+  ): Promise<RunInputGate | null> {
+    error.value = null
+    resolving.value = true
+    try {
+      return await execution.echoAfter(
+        executionId,
+        () => api.resolveInputGate(workspace.requireId(), executionId, { choice }),
+        (gate, instance) => {
+          instance.inputGate = gate as RunInputGate
+        },
+      )
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to resolve'
+      throw e
+    } finally {
+      resolving.value = false
+    }
+  }
+
+  return { resolving, error, resolve }
+})

package/app/stores/ui/resultViews.ts

@@ -78,13 +78,21 @@ export function createUiResultViews() {
     // Likewise a coder parked on the implementation-fork choice or on undecided follow-up
     // items: those parks ride `step.approval` too, but the generic approve resolver refuses
     // them server-side, so the step must open the window that CAN resolve it.
+    const park = step ? dedicatedParkView(step, instance) : null
     const view = step?.consensus?.enabled
       ? 'consensus-session'
       : step?.prReview
         ? 'pr-review'
         : step
-          ? (dedicatedParkView(step) ?? agentKindMeta(step.agentKind).resultView)
+          ? (park ?? agentKindMeta(step.agentKind).resultView)
           : undefined
+    // The PRE-TOKEN INPUT GATE is the one dedicated park with no window of its own: it is
+    // answered by an inline notice, which the generic step detail renders. Routing to the
+    // step's usual result view instead would open a window about work that has not run.
+    if (park === 'input-gate') {
+      stepDetail.value = { instanceId, stepIndex }
+      return
+    }
     if (view && instance) {
       // The brainstorm window is shared by both stages; carry which one from the step's kind.
       const stage =

package/app/stores/workspaceSettings.ts

@@ -14,6 +14,7 @@ const DEFAULTS: WorkspaceSettings = {
   artifactRetentionDays: 14,
   kaizenEnabled: true,
   delegateAgentsToRunnerPool: false,
+  inputGateMode: 'standard',
   reviewFrictionMode: 'off',
   reviewFrictionWarnCount: 3,
   reviewFrictionBlockCount: null,

package/app/types/domain.ts

@@ -80,6 +80,7 @@ export type {
   WorkspaceAccess,
   WorkspaceMember,
   TaskLimitMode,
+  InputGateMode,
   ReviewFrictionMode,
   WorkspaceSettings,
   WorkspaceMetadata,

package/app/utils/inputGate.spec.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+import type { RunInputGate } from '@cat-factory/contracts'
+import type { ExecutionInstance } from '~/types/execution'
+import { inputGateNoticeFor } from './inputGate'
+
+const run = (inputGate?: Partial<RunInputGate>): ExecutionInstance =>
+  ({
+    id: 'exe_1',
+    steps: [],
+    ...(inputGate
+      ? { inputGate: { mode: 'standard', issues: [], checkedAt: 1, ...inputGate } }
+      : {}),
+  }) as unknown as ExecutionInstance
+
+const thin = [{ code: 'description_thin', severity: 'advisory' }] as RunInputGate['issues']
+const missing = [{ code: 'description_missing', severity: 'blocking' }] as RunInputGate['issues']
+
+describe('inputGateNoticeFor', () => {
+  it('shows the park, with the tone that carries the two ways out', () => {
+    expect(inputGateNoticeFor(run({ status: 'blocked', issues: missing }))?.tone).toBe('blocked')
+  })
+
+  it('keeps a waiver visible, because what was overruled explains the output', () => {
+    expect(inputGateNoticeFor(run({ status: 'overridden', issues: missing }))?.tone).toBe('waived')
+  })
+
+  // The regression this pins: advisory findings were recorded on the run and reported over the
+  // API while being invisible in the product, which left `advisory` MODE (whose entire purpose is
+  // "watch what the gate would have caught before turning it up") with nothing to watch.
+  it('shows advisory findings on a PASSED verdict, which is what advisory mode produces', () => {
+    const notice = inputGateNoticeFor(run({ status: 'passed', mode: 'advisory', issues: thin }))
+    expect(notice?.tone).toBe('advisory')
+    expect(notice?.gate.issues).toEqual(thin)
+  })
+
+  it('shows a standard-mode advisory too, which never parks but is still a finding', () => {
+    expect(inputGateNoticeFor(run({ status: 'passed', issues: thin }))?.tone).toBe('advisory')
+  })
+
+  it.each(['passed', 'off', 'not_applicable'] as const)(
+    'says nothing about a %s verdict with no findings',
+    (status) => {
+      expect(inputGateNoticeFor(run({ status, issues: [] }))).toBeNull()
+    },
+  )
+
+  it('says nothing when the gate has not evaluated the run yet, or there is no run', () => {
+    expect(inputGateNoticeFor(run())).toBeNull()
+    expect(inputGateNoticeFor(null)).toBeNull()
+    expect(inputGateNoticeFor(undefined)).toBeNull()
+  })
+})

package/app/utils/inputGate.ts

@@ -0,0 +1,44 @@
+// Which PRE-TOKEN INPUT GATE verdicts a run surfaces, and how they are presented.
+//
+// The gate records a verdict for EVERY disposition, including the ones where it did nothing, so
+// "has a verdict" is not the same question as "has something to tell a human". This is the one
+// place that answers the second one, because the run panel and the step-detail overlay both ask
+// it and a per-component `status === 'blocked'` check is how they drift.
+
+import type { ExecutionInstance } from '~/types/execution'
+import type { RunInputGate } from '@cat-factory/contracts'
+
+/**
+ * How a verdict reads to a human:
+ *
+ *  - `blocked`: the run is parked, and the notice carries the two ways out.
+ *  - `waived`: somebody read the blocking findings and ran anyway. Kept visible on the run that
+ *    carries it, because what was overruled is part of what explains the output.
+ *  - `advisory`: findings were recorded and nothing was parked. This is the whole point of
+ *    `advisory` MODE ("watch what the gate would have caught before turning it up"), and it is
+ *    also how `standard` mode reports a short description or a spike with no success criteria.
+ */
+export type InputGateTone = 'blocked' | 'waived' | 'advisory'
+
+/**
+ * The verdict a run should show, with the tone to show it in, or `null` when the gate has
+ * nothing to say.
+ *
+ * Nothing to say covers three real and different facts that happen to share a presentation:
+ * a verdict that has not been stamped yet, one the workspace turned `off`, and a clean `passed`.
+ * None of them is a message, so none of them earns a box on the panel. The distinction between
+ * them is preserved on the run and read by the API, not painted over here.
+ *
+ * Note what this deliberately does NOT gate on: a `passed` status. A `passed` verdict carrying
+ * advisories is exactly what advisory mode produces, and keying the notice off the status alone
+ * left every advisory finding recorded, reported over the API, and invisible in the product.
+ */
+export function inputGateNoticeFor(
+  instance: ExecutionInstance | null | undefined,
+): { gate: RunInputGate; tone: InputGateTone } | null {
+  const gate = instance?.inputGate
+  if (!gate) return null
+  if (gate.status === 'blocked') return { gate, tone: 'blocked' }
+  if (gate.status === 'overridden') return { gate, tone: 'waived' }
+  return gate.issues.length > 0 ? { gate, tone: 'advisory' } : null
+}

package/app/utils/pipelineRender.spec.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import type { PipelineStep } from '~/types/execution'
+import type { ExecutionInstance, PipelineStep } from '~/types/execution'
 import { dedicatedParkView } from './pipelineRender'
 
 /** A minimal coder step; the predicate only reads approval/followUps/forkDecision. */
@@ -11,6 +11,14 @@ const step = (over: Partial<PipelineStep>): PipelineStep =>
     ...over,
   }) as PipelineStep
 
+/**
+ * A run carrying no input-gate verdict: the ordinary case for every step-shaped park below.
+ * Passed explicitly because `dedicatedParkView` REQUIRES the run — the gate's park is a fact
+ * about the run rather than the step, so a call that omitted it would silently miss it.
+ */
+const run = (over: Partial<ExecutionInstance> = {}): ExecutionInstance =>
+  ({ id: 'exe_1', steps: [], ...over }) as unknown as ExecutionInstance
+
 const followUps = (statuses: string[]) => ({
   enabled: true,
   items: statuses.map((status, i) => ({
@@ -32,13 +40,13 @@ describe('dedicatedParkView', () => {
   // proceed" rail.
   it('owns a follow-up park (pending approval + undecided items)', () => {
     expect(
-      dedicatedParkView(step({ followUps: followUps(['pending', 'answered']) as never })),
+      dedicatedParkView(step({ followUps: followUps(['pending', 'answered']) as never }), run()),
     ).toBe('follow-ups')
   })
 
   it('does not claim a step whose follow-up items are all decided', () => {
     expect(
-      dedicatedParkView(step({ followUps: followUps(['answered', 'dismissed']) as never })),
+      dedicatedParkView(step({ followUps: followUps(['answered', 'dismissed']) as never }), run()),
     ).toBeNull()
   })
 
@@ -47,26 +55,56 @@ describe('dedicatedParkView', () => {
     expect(
       dedicatedParkView(
         step({ state: 'working', approval: null, followUps: followUps(['pending']) as never }),
+        run(),
       ),
     ).toBeNull()
   })
 
   it('owns the fork park while awaiting a choice, and while a chat reply is in flight', () => {
-    expect(dedicatedParkView(step({ forkDecision: { status: 'awaiting_choice' } as never }))).toBe(
-      'fork-decision',
-    )
-    expect(dedicatedParkView(step({ forkDecision: { status: 'answering' } as never }))).toBe(
+    expect(
+      dedicatedParkView(step({ forkDecision: { status: 'awaiting_choice' } as never }), run()),
+    ).toBe('fork-decision')
+    expect(dedicatedParkView(step({ forkDecision: { status: 'answering' } as never }), run())).toBe(
       'fork-decision',
     )
   })
 
   it('releases the step once the fork is resolved (chosen / single_path / skipped)', () => {
     for (const status of ['chosen', 'single_path', 'skipped', 'proposing']) {
-      expect(dedicatedParkView(step({ forkDecision: { status } as never }))).toBeNull()
+      expect(dedicatedParkView(step({ forkDecision: { status } as never }), run())).toBeNull()
     }
   })
 
   it('leaves a plain approval park to the generic rail', () => {
-    expect(dedicatedParkView(step({}))).toBeNull()
+    expect(dedicatedParkView(step({}), run())).toBeNull()
+  })
+
+  // The PRE-TOKEN INPUT GATE parks whatever step 0 happens to be and leaves nothing
+  // kind-specific on the step, so it is recognised off the RUN. The generic approve resolver
+  // refuses it server-side: approving it would mark the run's first working step done and skip
+  // the work the run exists to do.
+  it('owns a step whose park is the input gate, read off the run', () => {
+    const blocked = run({
+      inputGate: { status: 'blocked', mode: 'standard', issues: [], checkedAt: 1 },
+    } as never)
+    expect(dedicatedParkView(step({}), blocked)).toBe('input-gate')
+  })
+
+  it('releases the step once the gate is waived or passed', () => {
+    for (const status of ['overridden', 'passed', 'off', 'not_applicable']) {
+      const settled = run({
+        inputGate: { status, mode: 'standard', issues: [], checkedAt: 1 },
+      } as never)
+      expect(dedicatedParkView(step({}), settled)).toBeNull()
+    }
+  })
+
+  it('does not claim a step with no pending approval, whatever the gate says', () => {
+    // The gate's verdict alone must not turn an unparked step into a dedicated park: a run
+    // parked on the gate has exactly one step holding the approval.
+    const blocked = run({
+      inputGate: { status: 'blocked', mode: 'standard', issues: [], checkedAt: 1 },
+    } as never)
+    expect(dedicatedParkView(step({ approval: null, state: 'working' }), blocked)).toBeNull()
   })
 })

package/app/utils/pipelineRender.ts

@@ -2,7 +2,7 @@
 // TaskPipelineMini, AgentStepDetail), so the "is this step still live?" logic stays
 // in one place rather than being re-derived as inline ternaries per component.
 
-import type { AgentState, PipelineStep } from '~/types/execution'
+import type { AgentState, ExecutionInstance, PipelineStep } from '~/types/execution'
 
 /**
  * Visual state of a conditionally-run companion attached to a gate step (today the
@@ -141,8 +141,29 @@ export function isCompanionKind(kind: string): boolean {
  * server-side (`assertNotIterativeGate`), so every surface that offers a step's pending
  * approval must route these to their window instead of the generic "Approve & proceed"
  * rail — which would blink a 409 and resolve nothing.
+ *
+ * `input-gate` is the odd one out: it is resolved by an inline NOTICE rather than an overlay,
+ * because its remedy is to go and edit the task, which is a board action rather than something
+ * a modal could hold.
  */
-export function dedicatedParkView(step: PipelineStep): 'follow-ups' | 'fork-decision' | null {
+export function dedicatedParkView(
+  step: PipelineStep,
+  instance: ExecutionInstance | null | undefined,
+): 'follow-ups' | 'fork-decision' | 'input-gate' | null {
+  // The PRE-TOKEN INPUT GATE parks whatever step 0 happens to be, so it leaves nothing on the
+  // STEP to recognise it by: its verdict is a fact about the RUN. Checked first, and off the
+  // instance: approving it generically would mark the run's first working step done and skip
+  // the work the run exists to do.
+  //
+  // `instance` is REQUIRED, and nullable rather than optional on purpose. Every park surface has
+  // the run in hand, and an optional parameter is how one of them silently stops passing it: the
+  // function would go on returning `null` for a gate-parked step, which each caller reads as
+  // "the generic approve rail applies" — the exact 409-blinking rail this exists to prevent.
+  // It still ACCEPTS an absent run (a store lookup that has not resolved), because that is a real
+  // state a caller has to be able to express; what it does not accept is not being asked.
+  if (instance?.inputGate?.status === 'blocked' && step.approval?.status === 'pending') {
+    return 'input-gate'
+  }
   // The fork park sits BEFORE the coder's build dispatch; `answering` (a chat turn in
   // flight) still belongs to the fork window, which renders the pending reply.
   const fork = step.forkDecision?.status

package/app/utils/vcs.spec.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest'
+import {
+  appInstallationManageUrl,
+  newRepoUrl,
+  VCS_PROVIDER_ICONS,
+  VCS_PROVIDER_LABELS,
+  VCS_PROVIDER_TOKEN_URLS,
+} 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
+ * 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.
+ */
+const connection = (over: Partial<GitHubConnection> = {}): GitHubConnection => ({
+  installationId: 42,
+  accountLogin: 'acme',
+  targetType: 'User',
+  connectedAt: 0,
+  provider: 'github',
+  method: 'app',
+  canCreateRepos: false,
+  canManageWorkflows: true,
+  ...over,
+})
+
+describe('appInstallationManageUrl', () => {
+  it('links a personal App installation to the user settings page', () => {
+    expect(appInstallationManageUrl(connection())).toBe(
+      'https://github.com/settings/installations/42',
+    )
+  })
+
+  it('links an organization App installation to the org settings page', () => {
+    expect(appInstallationManageUrl(connection({ targetType: 'Organization' }))).toBe(
+      'https://github.com/organizations/acme/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
+  // GitLab-connected workspace.
+  it('has no URL for a PAT connection, whatever its provider', () => {
+    expect(
+      appInstallationManageUrl(connection({ provider: 'gitlab', method: 'pat' })),
+    ).toBeUndefined()
+    expect(
+      appInstallationManageUrl(connection({ provider: 'github', method: 'pat' })),
+    ).toBeUndefined()
+  })
+
+  it('has no URL when there is no connection', () => {
+    expect(appInstallationManageUrl(null)).toBeUndefined()
+  })
+})
+
+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',
+    )
+    expect(url.origin + url.pathname).toBe('https://github.com/new')
+    expect(url.searchParams.get('owner')).toBe('acme')
+    expect(url.searchParams.get('name')).toBe('api')
+    expect(url.searchParams.get('visibility')).toBe('private')
+  })
+
+  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')
+    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()
+  })
+
+  it('withholds a page when no provider is resolved', () => {
+    expect(newRepoUrl(null, { name: 'api', private: false })).toBeUndefined()
+  })
+})
+
+describe('provider presentation maps', () => {
+  const providers: VcsProvider[] = ['github', 'gitlab']
+
+  // Each map is an exhaustive Record, so this only guards against an entry left empty: the
+  // typecheck already fails when a provider joins the union with no row.
+  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:\/\//)
+  })
+})

package/app/utils/vcs.ts

@@ -1,4 +1,4 @@
-import type { VcsProvider } from '~/types/domain'
+import type { GitHubConnection, VcsProvider } from '~/types/domain'
 
 // ---------------------------------------------------------------------------
 // Shared VCS provider presentation. The platform's repo DATA is provider-neutral (one
@@ -29,3 +29,65 @@ 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',
 }
+
+/**
+ * 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.
+ *
+ * `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.
+ */
+const NEW_REPO_PAGES: Record<VcsProvider, string | null> = {
+  github: 'https://github.com/new',
+  gitlab: null,
+}
+
+/**
+ * The App installation's settings page, where a user grants it access to a repository it
+ * can't see yet — or `undefined` when the connection is not a GitHub-App one.
+ *
+ * A pasted PAT has no installation and no such page: what it can reach is decided by the
+ * 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.
+ */
+export function appInstallationManageUrl(connection: GitHubConnection | null): string | undefined {
+  if (!connection || connection.method !== 'app') return undefined
+  return connection.targetType === 'Organization'
+    ? `https://github.com/organizations/${connection.accountLogin}/settings/installations/${connection.installationId}`
+    : `https://github.com/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.
+ *
+ * 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
+ * always stated: the caller's toggle has an answer either way, unlike the text fields.
+ */
+export function newRepoUrl(
+  provider: VcsProvider | null,
+  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 !== 'github') return page
+  const params = new URLSearchParams()
+  if (prefill.owner) params.set('owner', prefill.owner)
+  if (prefill.name) params.set('name', prefill.name)
+  if (prefill.description) params.set('description', prefill.description)
+  params.set('visibility', prefill.private ? 'private' : 'public')
+  return `${page}?${params.toString()}`
+}