@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/src/modules/settings/setup.routes.ts

@@ -1,20 +1,78 @@
 import express from 'express';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
 import type { IAdminAccessService } from '../admin/admin.interface.js';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('setup');
 import {
   DeploymentSettingsService,
   SettingsValidationError,
   validateHttpsRemote,
+  type OidcCredentials,
 } from './deployment-settings.service.js';
+import {
+  checkOidcConfiguration,
+  checkOidcIssuer,
+  normalizeIssuerUrl,
+  type IssuerCheck,
+  type OidcCheck,
+  type OidcConfiguration,
+} from './oidc-check.js';
+import {
+  checkRepositoryConnection,
+  type ConnectionCheck,
+  type RepositoryConnection,
+} from './connection-check.js';
 import {
   configureBranchModel,
+  configureKbLayout,
   isBranchModelConfigured,
+  isDefaultKbLayout,
   validateBranchModel,
+  validateKbLayout,
 } from '@bevel-software/platform-shared';
+import { failureOf, type GitFailure } from '../../shared/git-failure.js';
+import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
+import { listRootFolders, pickListingBranch } from './git-root-folders.js';
 import '../auth/auth.middleware.js'; // Express Request augmentation
 
-const execFileAsync = promisify(execFile);
+/** Which name a host expects beside the token when none is configured. */
+const DEFAULT_GIT_USERNAME = 'x-access-token';
+
+/** The one rule, in the one wording, for a stored token and a repository it was not saved for. */
+const TOKEN_FOR_THAT_REPOSITORY =
+  'Enter the access token for that repository — the saved one is only used with the repository it was saved for.';
+
+/** The same rule for the application secret and a provider it was not saved for. */
+const SECRET_FOR_THAT_PROVIDER =
+  'Enter the application secret for that provider — the saved one is only sent to the provider it was saved for.';
+
+/**
+ * The knowledge-base layout as setting keys: the three renameable roots, the
+ * guide's file name, and the consent that rides with it — which the KB startup
+ * phase reads through a getter, so the completing save puts it in effect along
+ * with the names.
+ */
+const LAYOUT_KEYS: readonly string[] = [
+  'knowledgeBaseDir',
+  'skillsDir',
+  'pluginsDir',
+  'agentsFile',
+  'agentsFileLink',
+];
+/** The branch model, as setting keys. */
+const BRANCH_KEYS: readonly string[] = ['defaultBranch', 'protectedBranches'];
+
+/**
+ * The slice of a sync record the status endpoint publishes. Declared here
+ * rather than imported from `kb-sync` so this module stays free of that one;
+ * the composition root hands in something that satisfies it.
+ */
+export interface LastSyncStatus {
+  at: number;
+  by: string;
+  status: 'synced' | 'partial';
+  results: Array<{ branch: string; outcome: string; error?: string }>;
+}
 
 /**
  * First-run setup — the deployment's own configuration, for the things that
@@ -36,21 +94,62 @@ export function createSetupRoutes(
    * (`isComplete`), so no session can be holding a working clone the phase
    * would race.
    */
-  kbStartupRunner: { runAll(): Promise<void> },
+  kbStartupRunner: {
+    runAll(): Promise<void>;
+    /**
+     * Why the runner's most recent run failed, if it did — including a BOOT
+     * run that survived an unreachable remote. Optional so a minimal mount
+     * (tests, a distribution's own runner) reads as never having failed.
+     */
+    lastFailure?(): string | null;
+    /** That failure classified, for the setup screen; absent, the message is read instead. */
+    lastFailureKind?(): GitFailure | null;
+  },
+  /**
+   * The remote-sync facts the Deployment page shows beside the sync secret:
+   * the address a webhook or pipeline must call, and what the last call did.
+   * Optional so a minimal mount (tests, a distribution without the module)
+   * simply omits them from the status.
+   */
+  sync?: {
+    /** `<PUBLIC_BACKEND_URL>/api/sync` — the reader appends `/<branch>`. */
+    url: string;
+    lastSync(): LastSyncStatus | null;
+  },
+  /**
+   * The read+write connection check. Injected so route tests can answer for
+   * the remote; production passes the real one bound to the deployment's git
+   * runner (`repositoryConnectionCheck`), and the default is the same check on
+   * a runner with default settings.
+   */
+  checkConnection: (connection: RepositoryConnection) => Promise<ConnectionCheck> = checkRepositoryConnection,
+  /** The root-folder listing Test connection reports. Injected for the same reason. */
+  listFolders: typeof listRootFolders = listRootFolders,
+  /**
+   * `<PUBLIC_BACKEND_URL>/api/auth/oidc/callback` — the redirect URI the
+   * single sign-on check sends, as the real callback does.
+   */
+  oidcRedirectUri = '',
+  /** The single sign-on check. Injected so route tests can answer for the provider. */
+  checkOidc: (config: OidcConfiguration) => Promise<OidcCheck> = checkOidcConfiguration,
+  /** The issuer-only half, for a test with no application id or secret yet. */
+  checkIssuer: (issuerUrl: string) => Promise<IssuerCheck> = (url) => checkOidcIssuer(url),
 ): express.Router {
   const router = express.Router();
 
   /**
-   * Whether the last setup-time run of the KB startup phase FAILED. While
-   * true the deployment stays GATED: the settings are saved but the KB was
+   * Why the last setup-time run of the KB startup phase FAILED, or null. While
+   * set the deployment stays GATED: the settings are saved but the KB was
    * never initialized, and reporting setup complete would open the app over
-   * an unmaintained (possibly unseeded) knowledge base. Saving the setup
-   * form again retries the phase; a server restart retries it at boot; a
-   * success clears the flag. Per-process state, like the gate itself.
+   * an unmaintained (possibly unseeded) knowledge base. Any save — including
+   * an empty one, which is what "Retry initialization" sends — retries the
+   * phase; a server restart retries it at boot; a success clears it.
+   * Per-process state, like the gate itself.
+   *
+   * Classified, never raw: the admin gets a kind and a remediation sentence,
+   * and what git actually said stays in the server log.
    */
-  let kbInitFailed = false;
-  /** The failure's message, surfaced to the ADMIN on the status endpoint. */
-  let kbInitError: string | null = null;
+  let kbInit: GitFailure | null = null;
   /**
    * The setup-time run currently executing, if any. Its jobs: (a) keeping the
    * status gate SHUT while a run executes (the settings read complete the
@@ -61,8 +160,27 @@ export function createSetupRoutes(
    * at a time, phase included, so no second run can start while one executes.
    */
   let kbInitInFlight: Promise<void> | null = null;
-  /** The app-gate answer: settings complete AND the KB phase settled clean. */
-  const kbReady = () => isComplete(settings) && !kbInitFailed && kbInitInFlight === null;
+  /**
+   * Whether the folder names in effect were put there by a setup-time save
+   * rather than by boot. While that run stands failed the app is still gated
+   * shut, so a retrying save may apply names the admin corrected in between.
+   */
+  let layoutAppliedBySetup = false;
+  /**
+   * A failure the RUNNER itself is standing on — a boot that survived an
+   * unreachable remote. Read live, because the runner's own background retry
+   * clears it without any save passing through here.
+   */
+  const bootFailure = () => kbStartupRunner.lastFailure?.() ?? null;
+  /** The boot failure in the setup screen's terms: the runner's own reading, else one read from its message. */
+  const bootFailureKind = (): GitFailure | null => {
+    const message = bootFailure();
+    if (message === null) return null;
+    return kbStartupRunner.lastFailureKind?.() ?? failureOf(message);
+  };
+  /** The app-gate answer: settings complete AND the KB phase settled clean, whoever ran it. */
+  const kbReady = () =>
+    isComplete(settings) && kbInit === null && kbInitInFlight === null && bootFailure() === null;
 
   const requireAdmin: express.RequestHandler = async (req, res, next) => {
     if (!(await adminAccess.isAdmin(req.userEmail))) {
@@ -100,7 +218,9 @@ export function createSetupRoutes(
       awaitingRestart: awaitingRestart(settings),
       isAdmin: true,
       settings: settings.describe(),
-      ...(kbInitFailed ? { kbInitError } : {}),
+      oidcVerification: await settings.oidcVerification(),
+      ...(kbInit ? { kbInit } : bootFailure() !== null ? { kbInit: bootFailureKind() } : {}),
+      ...(sync ? { sync: { url: sync.url, last: sync.lastSync() } } : {}),
     });
   });
 
@@ -142,7 +262,22 @@ export function createSetupRoutes(
       // one that must run the KB startup phase, regardless of which save
       // configured the branch model.
       const wasComplete = isComplete(settings);
-      const { restartRequired } = await settings.save(entries, req.userId ?? null);
+      if (!(await connectionHoldsFor(entries, wasComplete, res))) return;
+      const oidc = await signInHoldsFor(entries, res);
+      if (!oidc) return;
+      // Recorded BEFORE the save: the record is keyed by the values it is
+      // about, so until the save puts them in effect it speaks for nothing —
+      // while a record written after a committed save could fail and leave
+      // those values unverified with no way back (the retry changes nothing,
+      // so it is not probed again).
+      if (oidc.record) {
+        await settings.recordOidcVerification(oidc.record.state, oidc.record.credentials);
+      }
+      const { restartRequired, restartKeys } = await settings.save(entries, req.userId ?? null);
+      /** Whether this save put the stored folder names into the running process. */
+      let layoutApplied = false;
+      /** Whether this save put the stored branch model into the running process. */
+      let branchModelApplied = false;
       /**
        * Apply the branch model to THIS process, so pressing Save finishes
        * setup instead of asking for a restart.
@@ -162,7 +297,10 @@ export function createSetupRoutes(
           defaultBranch: settings.resolve('defaultBranch'),
           protectedBranches: settings.resolve('protectedBranches'),
         };
-        if (!validateBranchModel(model)) configureBranchModel(model);
+        if (!validateBranchModel(model)) {
+          configureBranchModel(model);
+          branchModelApplied = true;
+        }
       }
       /**
        * The save that COMPLETES setup is the KB startup phase's SECOND quiet
@@ -174,11 +312,29 @@ export function createSetupRoutes(
        * Runs on the false→true completion transition — including when the
        * branch model was configured by an EARLIER save and the repository
        * URL arrives on a later one — and again on any save while a previous
-       * setup-time run stands failed (`kbInitFailed`), so saving the form is
-       * the retry. Never on a re-save of a complete, healthy setup: with the
-       * gate open, sessions may be live and that is no longer a quiet moment.
+       * setup-time run stands failed (`kbInit`), so a save is the retry. Never
+       * on a re-save of a complete, healthy setup: with the gate open,
+       * sessions may be live and that is no longer a quiet moment.
        */
-      if ((!wasComplete || kbInitFailed) && isComplete(settings)) {
+      if ((!wasComplete || kbInit !== null || bootFailure() !== null) && isComplete(settings)) {
+        /**
+         * The folder names, applied BEFORE the phase for the same reason as
+         * the branch model above: they are otherwise applied once at boot, so
+         * the phase would scaffold `Skills/` beside the `skills/` the admin
+         * just named, and the app would read the defaults until a restart.
+         * Only while the process still holds the defaults — a layout already
+         * in effect from the environment or the boot is left alone — or holds
+         * the names an earlier setup save applied before a run that failed:
+         * the gate never opened, so the retry initializes what is saved now.
+         */
+        if (isDefaultKbLayout() || (kbInit !== null && layoutAppliedBySetup)) {
+          const layout = settings.resolveKbLayout();
+          if (!validateKbLayout(layout)) {
+            configureKbLayout(layout);
+            layoutApplied = true;
+            layoutAppliedBySetup = true;
+          }
+        }
         try {
           // One run at a time. The save chain already serializes handlers
           // whole, so no second run can start while one executes; the `??=`
@@ -189,20 +345,24 @@ export function createSetupRoutes(
           // and opens the gate DELIBERATELY — booting unmaintained so the
           // operator can get in and fix things is exactly what the
           // break-glass is for.
-          kbInitFailed = false;
-          kbInitError = null;
+          kbInit = null;
         } catch (initErr) {
           // The settings ARE saved — only the KB initialization failed. The
           // deployment stays gated (see the status endpoint) until a retry
-          // succeeds. Logged in full, returned actionable.
-          const msg = initErr instanceof Error ? initErr.message : String(initErr);
-          console.error('[setup] KB initialization failed after setup completed:', msg);
-          kbInitFailed = true;
-          kbInitError = msg;
+          // succeeds. Logged in full (scrubbed of the token in effect, which
+          // may be the one this very save stored), returned classified — by
+          // the classification the runner's failure carries, read before any
+          // scrub rewrote git's words (`failureOf`).
+          const raw = initErr instanceof Error ? initErr.message : String(initErr);
+          const msg = redactSecret(raw, [
+            settings.resolve('gitToken'),
+            ...urlQuerySecrets(settings.resolve('kbRepoUrl')),
+          ]);
+          log.error(`KB initialization failed after setup completed: ${msg}`);
+          kbInit = failureOf(initErr);
           res.status(500).json({
-            error:
-              'Settings saved, but the knowledge base could not be initialized. ' +
-              'Saving the setup form again retries; restarting the server retries too.',
+            error: 'Settings saved, but the knowledge base could not be initialized.',
+            kbInit,
           });
           return;
         } finally {
@@ -211,10 +371,20 @@ export function createSetupRoutes(
       }
       res.json({
         ok: true,
-        restartRequired,
+        // Folder names and a branch model this save just applied are in
+        // effect; a restart is owed only for whatever else changed.
+        restartRequired:
+          layoutApplied || branchModelApplied
+            ? restartKeys.some(
+                (key) =>
+                  !(layoutApplied && LAYOUT_KEYS.includes(key)) &&
+                  !(branchModelApplied && BRANCH_KEYS.includes(key)),
+              )
+            : restartRequired,
         complete: kbReady(),
         awaitingRestart: awaitingRestart(settings),
         settings: settings.describe(),
+        oidcVerification: await settings.oidcVerification(),
       });
     } catch (err) {
       if (err instanceof SettingsValidationError) {
@@ -223,19 +393,243 @@ export function createSetupRoutes(
       }
       // Logged in full, returned generic: a driver message here would hand back
       // the schema or the connection string.
-      console.error('[setup] save failed:', err instanceof Error ? err.message : String(err));
+      log.error('save failed:', { err });
       res.status(500).json({ error: 'Could not save these settings.' });
     }
   }
 
+  /**
+   * A SAVED CONNECTION IS ONE THE HOST HAS ACCEPTED FOR READING AND WRITING.
+   *
+   * The completeness check asks only whether the answers are present, so
+   * without this a token the host rejects — or one that can read but not
+   * push — finishes setup as well as a working one, and the first news of it
+   * is every save anyone makes failing. The browser proves the connection too,
+   * but a browser is not the only client, and it is not the last word.
+   *
+   * Checked on the values the save WOULD put in effect, and only when the save
+   * matters to the connection: it changes the address, the token or the
+   * username, or it completes first-run setup. Anything else — single sign-on,
+   * say — is never probed, so an admin is not held hostage to a repository
+   * that is down while they edit something unrelated.
+   *
+   * Answers the refusal itself (400, per-field problems) and returns false;
+   * true means the save may go ahead. Validation problems in `entries` throw
+   * {@link SettingsValidationError} before any probe, exactly as the save would.
+   */
+  async function connectionHoldsFor(
+    entries: Record<string, string>,
+    wasComplete: boolean,
+    res: express.Response,
+  ): Promise<boolean> {
+    const after = settings.resolveAfter(entries);
+    const now: RepositoryConnection = {
+      url: settings.resolve('kbRepoUrl'),
+      token: settings.resolve('gitToken'),
+      username: settings.resolve('gitUsername') || DEFAULT_GIT_USERNAME,
+    };
+    const next: RepositoryConnection = {
+      url: after('kbRepoUrl'),
+      token: after('gitToken'),
+      username: after('gitUsername') || DEFAULT_GIT_USERNAME,
+    };
+    const refuse = (problems: Record<string, string>) => {
+      res.status(400).json({ error: Object.values(problems)[0], problems });
+      return false;
+    };
+
+    // THE CONFIGURED TOKEN ONLY EVER GOES TO THE CONFIGURED REPOSITORY — the
+    // same rule the connection test applies, for the same reason: probing a
+    // new address with the stored token would hand it to whoever runs that
+    // host. A new address brings its own token. Until an address is
+    // configured there is no repository the token was "set for": a first-run
+    // save that brings the address to a token already present (GIT_TOKEN in
+    // the environment, whose field the form cannot even edit) is that token's
+    // first and only pairing, not a change of it.
+    const tokenSupplied = Boolean(entries.gitToken?.trim());
+    if (now.url && next.url !== now.url && next.token && !tokenSupplied) {
+      return settings.sourceOf('gitToken') === 'env'
+        ? refuse({
+            kbRepoUrl:
+              'The access token is set by the GIT_TOKEN environment variable and is only used with the repository it was set for — change both there.',
+          })
+        : refuse({ gitToken: TOKEN_FOR_THAT_REPOSITORY });
+    }
+
+    // Nothing to prove without both halves: a first save of the address alone
+    // cannot finish setup, and the save that later brings the token is probed.
+    if (!next.url || !next.token) return true;
+
+    const changesConnection =
+      next.url !== now.url || next.token !== now.token || next.username !== now.username;
+    const completesSetup =
+      !wasComplete &&
+      validateBranchModel({
+        defaultBranch: after('defaultBranch'),
+        protectedBranches: after('protectedBranches'),
+      }) === null;
+    if (!changesConnection && !completesSetup) return true;
+
+    const check = await checkConnection(next);
+    if (check.outcome === 'connected') return true;
+    return refuse({ [check.field]: check.error });
+  }
+
+  /**
+   * A SAVED SIGN-IN CONFIGURATION IS ONE THE PROVIDER HAS NOT TURNED DOWN.
+   *
+   * Without this an issuer that is not one, or a secret with a typo, saves as
+   * well as a working configuration, and the first news of it is the sign-in
+   * button failing for someone else after the restart.
+   *
+   * The same gate rule as the repository connection: checked on the values
+   * the save WOULD put in effect, and only when the save changes the issuer,
+   * the application id or the secret. Scopes, the button label, the allowed
+   * domains and everything outside single sign-on are never probed.
+   *
+   * A definitive refusal answers 400 with the problem on its field and returns
+   * null. Otherwise it returns what the save should record — verified, or
+   * unverified when the provider's answer said nothing definite — or no record
+   * when nothing about the configuration was proven.
+   */
+  async function signInHoldsFor(
+    entries: Record<string, string>,
+    res: express.Response,
+  ): Promise<{
+    record?: { state: 'verified' | 'unverified'; credentials: OidcCredentials };
+  } | null> {
+    const after = settings.resolveAfter(entries);
+    const now = settings.resolveOidcCredentials();
+    const next: OidcCredentials = {
+      issuerUrl: normalizeIssuerUrl(after('oidcIssuerUrl')),
+      clientId: after('oidcClientId'),
+      clientSecret: after('oidcClientSecret'),
+    };
+    const refuse = (problems: Record<string, string>) => {
+      res.status(400).json({ error: Object.values(problems)[0], problems });
+      return null;
+    };
+    const changes =
+      next.issuerUrl !== now.issuerUrl ||
+      next.clientId !== now.clientId ||
+      next.clientSecret !== now.clientSecret;
+    if (!changes) return {};
+
+    // THE CONFIGURED SECRET ONLY EVER GOES TO THE CONFIGURED PROVIDER: probing
+    // a new issuer with it would hand it to whoever runs that one. Until an
+    // issuer is configured there is no provider it was set for — the save
+    // that first names one (beside an OIDC_CLIENT_SECRET the form cannot
+    // edit) pairs them.
+    const secretSupplied = Boolean(entries.oidcClientSecret?.trim());
+    if (now.issuerUrl && next.issuerUrl !== now.issuerUrl && next.clientSecret && !secretSupplied) {
+      return settings.sourceOf('oidcClientSecret') === 'env'
+        ? refuse({
+            oidcIssuerUrl:
+              'The application secret is set by the OIDC_CLIENT_SECRET environment variable and is only sent to the provider it was set for — change both there.',
+          })
+        : refuse({ oidcClientSecret: SECRET_FOR_THAT_PROVIDER });
+    }
+
+    // Nothing to prove until all three are there; the save that completes
+    // them is the one probed.
+    if (!next.issuerUrl || !next.clientId || !next.clientSecret) return {};
+
+    const check = await checkOidc({ ...next, redirectUri: oidcRedirectUri });
+    if (check.outcome === 'rejected') return refuse({ [check.field]: check.error });
+    return { record: { state: check.outcome, credentials: next } };
+  }
+
+  /**
+   * "Test sign-in configuration": the same check the save runs, BEFORE
+   * anything is saved, on the values typed — falling back to those in effect.
+   *
+   * Answers 200 with `outcome` whenever the check ran: `verified`,
+   * `unverified` (the issuer is fine, the credentials could not be judged),
+   * `issuer-verified` (no application id or secret to try yet) or `rejected`
+   * with the field it is about. A 400 is a request that never got as far as
+   * asking. Never returns or logs the secret.
+   */
+  router.post('/setup/test-oidc', requireAdmin, async (req, res) => {
+    const body = (req.body ?? {}) as Record<string, unknown>;
+    const supplied = (key: string): string | null => {
+      const value = body[key];
+      return typeof value === 'string' && value.trim() ? value.trim() : null;
+    };
+    const current = settings.resolveOidcCredentials();
+    const issuerUrl = normalizeIssuerUrl(supplied('oidcIssuerUrl') ?? current.issuerUrl);
+    if (!issuerUrl) {
+      res.status(400).json({ ok: false, error: 'Enter the provider address first.' });
+      return;
+    }
+    const issuerProblem = settings.definitions.find((d) => d.key === 'oidcIssuerUrl')?.validate?.(issuerUrl);
+    if (issuerProblem) {
+      res.status(400).json({ ok: false, outcome: 'rejected', field: 'oidcIssuerUrl', error: issuerProblem });
+      return;
+    }
+    const clientId = supplied('oidcClientId') ?? current.clientId;
+    const suppliedSecret = supplied('oidcClientSecret');
+    // The stored secret is sent only to the issuer it was saved for; testing
+    // another one brings its own. With no issuer configured yet it was set for
+    // none, so it may be tried with the first. Without a secret, only the
+    // issuer is checked.
+    const forAnotherIssuer = Boolean(current.issuerUrl) && issuerUrl !== current.issuerUrl;
+    const clientSecret = suppliedSecret ?? (forAnotherIssuer ? '' : current.clientSecret);
+    if (!suppliedSecret && forAnotherIssuer && current.clientSecret && clientId) {
+      res.status(400).json({
+        ok: false,
+        outcome: 'rejected',
+        field: 'oidcClientSecret',
+        error: SECRET_FOR_THAT_PROVIDER,
+      });
+      return;
+    }
+
+    try {
+      if (!clientId || !clientSecret) {
+        const issuer = await checkIssuer(issuerUrl);
+        if (issuer.outcome !== 'verified') {
+          res.json({ ok: false, outcome: 'rejected', field: issuer.field, error: issuer.error });
+          return;
+        }
+        res.json({ ok: true, outcome: 'issuer-verified' });
+        return;
+      }
+      const tested: OidcCredentials = { issuerUrl, clientId, clientSecret };
+      const check = await checkOidc({ ...tested, redirectUri: oidcRedirectUri });
+      if (check.outcome === 'rejected') {
+        res.json({ ok: false, outcome: check.outcome, field: check.field, error: check.error });
+        return;
+      }
+      // Proving the configuration in effect is as good as signing in with it.
+      // A save landing while this check ran is harmless: the record is keyed
+      // by the values tested, so it never speaks for the ones saved since.
+      const testsCurrent =
+        tested.issuerUrl === current.issuerUrl &&
+        tested.clientId === current.clientId &&
+        tested.clientSecret === current.clientSecret;
+      if (check.outcome === 'verified' && testsCurrent) {
+        await settings.recordOidcVerification('verified', tested);
+      }
+      res.json({
+        ok: check.outcome === 'verified',
+        outcome: check.outcome,
+        ...(check.outcome === 'unverified' ? { error: check.error } : {}),
+        oidcVerification: await settings.oidcVerification(),
+      });
+    } catch (err) {
+      log.error('sign-in check failed:', { err: err instanceof Error ? err.message : String(err) });
+      res.status(500).json({ ok: false, error: 'Could not run the sign-in check.' });
+    }
+  });
+
   /**
    * Try the credentials against the real remote, BEFORE anything is saved.
    *
    * This is the reason the screen is worth more than the environment variables
-   * it replaces. `ls-remote` is the cheapest operation that proves all three
-   * values at once — the URL resolves, the token authenticates, and the
-   * username is the one this host expects — and it answers in a second instead
-   * of surfacing as a failed clone at some later, unrelated moment.
+   * it replaces: it proves the URL resolves, the token authenticates, the
+   * username is the one this host expects, AND that the token may push — in a
+   * few seconds instead of as a failed clone or a failed save at some later,
+   * unrelated moment. It runs the same check the save does.
    *
    * Values are taken from the request when supplied so an admin can test what
    * they typed rather than what is stored, and fall back to what is in effect
@@ -275,10 +669,7 @@ export function createSetupRoutes(
     const suppliedToken = supplied('gitToken');
     const testingConfiguredRepo = url === settings.resolve('kbRepoUrl');
     if (!suppliedToken && !testingConfiguredRepo) {
-      res.status(400).json({
-        ok: false,
-        error: 'Enter the access token for that repository — the saved one is only used with the repository it was saved for.',
-      });
+      res.status(400).json({ ok: false, outcome: 'rejected', error: TOKEN_FOR_THAT_REPOSITORY });
       return;
     }
     const token = suppliedToken ?? (testingConfiguredRepo ? settings.resolve('gitToken') : '');
@@ -299,54 +690,57 @@ export function createSetupRoutes(
       return;
     }
 
+    let check: ConnectionCheck;
     try {
-      // The helper reads the token from the environment at call time, so it
-      // never appears in argv (and so never in a process listing or a crash
-      // dump). Same shape the real clone uses.
-      const args = ['-c', 'credential.helper=', ...(token
-        ? ['-c', `credential.helper=!f() { echo "username=${username}"; echo "password=$BEVEL_TEST_TOKEN"; }; f`]
-        : []),
-        // `--end-of-options` on top of the validation above: belt and braces,
-        // so nothing that arrives here can ever be read as a flag.
-        'ls-remote', '--heads', '--end-of-options', url];
-      const { stdout } = await execFileAsync('git', args, {
-        timeout: 20_000,
-        env: {
-          ...process.env,
-          BEVEL_TEST_TOKEN: token,
-          // Never let git stop for a prompt: without this a bad credential
-          // hangs the request until the timeout instead of failing.
-          GIT_TERMINAL_PROMPT: '0',
-          GIT_ASKPASS: 'echo',
-        },
-      });
-      const lines = stdout.split('\n');
-      // `<sha>\trefs/heads/<name>` — tag refs and the bare HEAD row are not
-      // branches, so they are filtered rather than sliced blindly.
-      const branches = lines
-        .filter((line) => !line.startsWith('ref:'))
-        .map((line) => line.split('\t')[1]?.trim())
-        .filter((ref): ref is string => !!ref && ref.startsWith('refs/heads/'))
-        .map((ref) => ref.slice('refs/heads/'.length));
-      // `ref: refs/heads/<name>\tHEAD` — what the remote calls its own trunk.
-      const defaultBranch =
-        lines
-          .find((line) => line.startsWith('ref:') && line.trimEnd().endsWith('HEAD'))
-          ?.slice('ref: refs/heads/'.length)
-          .split('\t')[0]
-          ?.trim() || null;
-      res.json({
-        ok: true,
-        // An EMPTY repository is a success, not a failure — seeding one is a
-        // supported path, and saying "no branches yet" beats an error that
-        // reads like the credentials are wrong.
-        empty: branches.length === 0,
-        branches,
-        defaultBranch,
-      });
+      check = await checkConnection({ url, token, username });
     } catch (err) {
-      res.status(200).json({ ok: false, error: explainGitFailure(err, token) });
+      // The check answers every refusal it can read as an outcome; a throw is
+      // the check itself breaking. Logged scrubbed — git failures have been
+      // known to quote the credential back — and returned generic.
+      const raw = err instanceof Error ? err.message : String(err);
+      log.error(`connection check failed: ${redactSecret(raw, [token, ...urlQuerySecrets(url)])}`);
+      res.status(500).json({ ok: false, error: 'Could not run the connection check.' });
+      return;
     }
+    if (check.outcome === 'rejected') {
+      // 200: the check RAN and the host said no. A 4xx is for a request that
+      // never got as far as asking.
+      res.json({ ok: false, outcome: check.outcome, field: check.field, error: check.error });
+      return;
+    }
+    /**
+     * The repository's top-level folders on the branch it serves, so the
+     * screen can say whether each configured root is there — and catch the
+     * `skills/` a `Skills` setting would silently scaffold a twin beside.
+     * Listed for a read-only token too: it reads, and the folder advice holds
+     * whatever permission it is granted next. An empty repository has no
+     * tree: an empty list, not a lookup. A listing that fails is null — never
+     * a failed connection.
+     */
+    const listingBranch = pickListingBranch(
+      check.defaultBranch,
+      supplied('defaultBranch') ?? (settings.resolve('defaultBranch') || null),
+      check.branches,
+    );
+    const rootFolders = check.empty
+      ? []
+      : listingBranch
+        ? await listFolders({ url, branch: listingBranch, username, token })
+        : null;
+    res.json({
+      // Only read AND write is "connected" — a read-only token is refused
+      // on save, so the button must not call it a success.
+      ok: check.outcome === 'connected',
+      outcome: check.outcome,
+      ...(check.outcome === 'read-only' ? { field: check.field, error: check.error } : {}),
+      // An EMPTY repository is a success, not a failure — seeding one is a
+      // supported path, and saying "no branches yet" beats an error that
+      // reads like the credentials are wrong.
+      empty: check.empty,
+      branches: check.branches,
+      defaultBranch: check.defaultBranch,
+      rootFolders,
+    });
   });
 
   return router;
@@ -398,27 +792,3 @@ export function isComplete(settings: DeploymentSettingsService): boolean {
 export function awaitingRestart(settings: DeploymentSettingsService): boolean {
   return settingsAnswered(settings) && !isBranchModelConfigured();
 }
-
-/**
- * Turn git's stderr into something an admin can act on. Deliberately narrow:
- * the raw text is echoed only when it matches nothing known, and the token is
- * scrubbed from it first — `ls-remote` failures have been known to quote the
- * credential back.
- */
-function explainGitFailure(err: unknown, token: string): string {
-  const raw = err instanceof Error ? `${err.message}` : String(err);
-  const text = token ? raw.replaceAll(token, '***') : raw;
-  if (/timed out|ETIMEDOUT/i.test(text)) {
-    return 'The host did not answer in time. Check the URL, and that this server can reach it.';
-  }
-  if (/Authentication failed|could not read Username|invalid credentials|403/i.test(text)) {
-    return 'The host rejected those credentials. Check the token, and that the username matches the host (GitHub x-access-token, GitLab oauth2, Bitbucket x-token-auth).';
-  }
-  if (/not found|repository .* does not exist|404/i.test(text)) {
-    return 'No repository at that URL — or the token cannot see it.';
-  }
-  if (/could not resolve host|unable to access|SSL|certificate/i.test(text)) {
-    return 'Could not reach that host from this server. Check the URL and any network egress rules.';
-  }
-  return text.split('\n').slice(0, 3).join(' ').slice(0, 400);
-}