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

package/dist/modules/settings/setup.routes.js

@@ -1,10 +1,35 @@
 import express from 'express';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
+import { logger } from '../../shared/logging.js';
+const log = logger('setup');
 import { SettingsValidationError, validateHttpsRemote, } from './deployment-settings.service.js';
-import { configureBranchModel, isBranchModelConfigured, validateBranchModel, } from '@bevel-software/platform-shared';
+import { checkOidcConfiguration, checkOidcIssuer, normalizeIssuerUrl, } from './oidc-check.js';
+import { checkRepositoryConnection, } from './connection-check.js';
+import { configureBranchModel, configureKbLayout, isBranchModelConfigured, isDefaultKbLayout, validateBranchModel, validateKbLayout, } from '@bevel-software/platform-shared';
+import { failureOf } 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 = [
+    'knowledgeBaseDir',
+    'skillsDir',
+    'pluginsDir',
+    'agentsFile',
+    'agentsFileLink',
+];
+/** The branch model, as setting keys. */
+const BRANCH_KEYS = ['defaultBranch', 'protectedBranches'];
 /**
  * First-run setup — the deployment's own configuration, for the things that
  * used to be environment-only.
@@ -23,19 +48,46 @@ export function createSetupRoutes(settings, adminAccess,
  * (`isComplete`), so no session can be holding a working clone the phase
  * would race.
  */
-kbStartupRunner) {
+kbStartupRunner, 
+/**
+ * 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, 
+/**
+ * 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 = checkRepositoryConnection, 
+/** The root-folder listing Test connection reports. Injected for the same reason. */
+listFolders = 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 = checkOidcConfiguration, 
+/** The issuer-only half, for a test with no application id or secret yet. */
+checkIssuer = (url) => checkOidcIssuer(url)) {
     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 = null;
+    let kbInit = 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
@@ -46,8 +98,27 @@ kbStartupRunner) {
      * at a time, phase included, so no second run can start while one executes.
      */
     let kbInitInFlight = 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 = () => {
+        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 = async (req, res, next) => {
         if (!(await adminAccess.isAdmin(req.userEmail))) {
             res.status(403).json({ error: 'Admins only' });
@@ -83,7 +154,9 @@ kbStartupRunner) {
             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() } } : {}),
         });
     });
     /**
@@ -122,7 +195,24 @@ kbStartupRunner) {
             // 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.
@@ -142,8 +232,10 @@ kbStartupRunner) {
                     defaultBranch: settings.resolve('defaultBranch'),
                     protectedBranches: settings.resolve('protectedBranches'),
                 };
-                if (!validateBranchModel(model))
+                if (!validateBranchModel(model)) {
                     configureBranchModel(model);
+                    branchModelApplied = true;
+                }
             }
             /**
              * The save that COMPLETES setup is the KB startup phase's SECOND quiet
@@ -155,11 +247,29 @@ kbStartupRunner) {
              * 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 `??=`
@@ -170,20 +280,25 @@ kbStartupRunner) {
                     // 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;
                 }
@@ -193,10 +308,16 @@ kbStartupRunner) {
             }
             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) {
@@ -206,18 +327,223 @@ kbStartupRunner) {
             }
             // 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, wasComplete, res) {
+        const after = settings.resolveAfter(entries);
+        const now = {
+            url: settings.resolve('kbRepoUrl'),
+            token: settings.resolve('gitToken'),
+            username: settings.resolve('gitUsername') || DEFAULT_GIT_USERNAME,
+        };
+        const next = {
+            url: after('kbRepoUrl'),
+            token: after('gitToken'),
+            username: after('gitUsername') || DEFAULT_GIT_USERNAME,
+        };
+        const refuse = (problems) => {
+            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, res) {
+        const after = settings.resolveAfter(entries);
+        const now = settings.resolveOidcCredentials();
+        const next = {
+            issuerUrl: normalizeIssuerUrl(after('oidcIssuerUrl')),
+            clientId: after('oidcClientId'),
+            clientSecret: after('oidcClientSecret'),
+        };
+        const refuse = (problems) => {
+            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 ?? {});
+        const supplied = (key) => {
+            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 = { 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
@@ -254,10 +580,7 @@ kbStartupRunner) {
         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') : '');
@@ -277,54 +600,54 @@ kbStartupRunner) {
             res.status(400).json({ ok: false, error: 'The username contains unsupported characters.' });
             return;
         }
+        let check;
         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 && 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;
 }
@@ -371,27 +694,4 @@ export function isComplete(settings) {
 export function awaitingRestart(settings) {
     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, token) {
-    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);
-}
 //# sourceMappingURL=setup.routes.js.map