sitevision-cli 1.0.0-beta.2 → 1.0.0-beta.21

package/dist/utils/project-detection.js

@@ -1,6 +1,27 @@
 import fs from 'fs';
 import path from 'path';
-import { getDeployPassword, setDeployPassword } from './keychain.js';
+import { getDeployPassword, setDeployPassword, getSessionCookie, } from './keychain.js';
+import { parseJsonc } from './jsonc.js';
+import { getLanguage } from './i18n.js';
+// =============================================================================
+// LOCALIZED TEXT
+// =============================================================================
+/**
+ * Resolve a manifest text field that may be a plain string or a localized
+ * object (e.g. `{sv: 'Namn', en: 'Name'}`) to a single display string.
+ *
+ * Preference order: Swedish, then English, then any available language. Returns
+ * an empty string for missing/empty values. This guards the UI from rendering a
+ * raw object as a React child, which Sitevision's localized manifests would
+ * otherwise trigger.
+ */
+export function localizedText(value, preferred = getLanguage()) {
+    if (!value)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    return value[preferred] ?? value['en'] ?? Object.values(value)[0] ?? '';
+}
 // =============================================================================
 // PATH UTILITIES
 // =============================================================================
@@ -41,6 +62,93 @@ export function findDevPropertiesPath(root) {
 export function getDefaultDevPropertiesPath(root) {
     return path.join(root, '.dev_properties.json');
 }
+/**
+ * Ancestor directories of `root` (outermost first) up to and including the
+ * nearest one containing `.git`, or the filesystem root. Each may carry a
+ * `.dev_properties.json` whose values the app inherits (nearest wins).
+ */
+function ancestorDirs(root) {
+    const dirs = [];
+    let dir = path.dirname(root);
+    while (true) {
+        dirs.unshift(dir);
+        if (fs.existsSync(path.join(dir, '.git')))
+            break;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return dirs;
+}
+/** A bare host: no scheme, no path, no stray spaces. */
+export function normalizeDomain(value) {
+    const host = value
+        .trim()
+        .replace(/^[a-z]+:\/\//i, '')
+        .replaceAll(/\s/g, '');
+    const slash = host.indexOf('/');
+    return slash === -1 ? host : host.slice(0, slash);
+}
+function readDevPropertiesFile(dir) {
+    const file = findDevPropertiesPath(dir);
+    if (!file)
+        return null;
+    try {
+        const dev = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        // ponytail: top level only; a hand-edited environment override keeps its
+        // scheme until it is saved from the config form.
+        dev.domain &&= normalizeDomain(dev.domain);
+        return dev;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The dev properties a workspace root defines (its own file merged over any
+ * ancestors'), with the deploy password resolved from the keychain like an
+ * app's would be. Used to edit shared config from the shell.
+ */
+export function readWorkspaceDevProperties(root) {
+    const merged = {
+        ...readInheritedDevProperties(root),
+        ...readDevPropertiesFile(root),
+    };
+    if (merged.domain && merged.username && !merged.password) {
+        merged.password =
+            process.env['SITEVISION_DEPLOY_PASSWORD'] ??
+                getDeployPassword(merged.domain, merged.username) ??
+                undefined;
+    }
+    return merged;
+}
+/** Ancestor directories' .dev_properties.json merged, nearest wins (no own file). */
+export function readAncestorDevProperties(root) {
+    let merged = {};
+    for (const dir of ancestorDirs(root)) {
+        merged = { ...merged, ...readDevPropertiesFile(dir) };
+    }
+    return merged;
+}
+/** Shared defaults from package.json: the workspace root's first, the app's on top. */
+export function readPackageDefaultsChain(root) {
+    let merged = {};
+    for (const dir of [...ancestorDirs(root), root]) {
+        merged = { ...merged, ...readPackageDefaults(dir) };
+    }
+    return merged;
+}
+/**
+ * Everything an app's own .dev_properties.json sits on top of: package.json
+ * defaults (root, then app), then ancestor .dev_properties.json files.
+ */
+export function readInheritedDevProperties(root) {
+    return {
+        ...readPackageDefaultsChain(root),
+        ...readAncestorDevProperties(root),
+    };
+}
 /**
  * Get app ID configuration from environment or defaults
  */
@@ -107,6 +215,11 @@ export function getApiEndpoints(appType) {
                 addon: 'headlesscustommodule',
                 import: 'restAppImport',
             };
+        case 'mcp':
+            return {
+                addon: 'mcpServerCustomModule',
+                import: 'mcpServerImport',
+            };
     }
 }
 /**
@@ -135,29 +248,56 @@ export function buildImportEndpointUrl(domain, siteName, addonName, appType, use
 // =============================================================================
 // PROJECT DETECTION
 // =============================================================================
+/**
+ * Thrown when a manifest.json is present but cannot be parsed. Kept distinct from
+ * a plain "no project here" (null) so the CLI can tell the user their manifest is
+ * malformed instead of the misleading "Not a Sitevision project".
+ */
+export class ManifestParseError extends Error {
+    constructor(manifestPath, cause) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        super(`${manifestPath} is not valid JSON: ${reason}`);
+        this.name = 'ManifestParseError';
+    }
+}
+/**
+ * Read manifest.json from its supported locations (root, static/, src/).
+ * Throws ManifestParseError on malformed JSON.
+ */
+export function readManifest(cwd) {
+    const manifestPaths = [
+        path.join(cwd, 'manifest.json'),
+        path.join(cwd, 'static', 'manifest.json'),
+        path.join(cwd, 'src', 'manifest.json'),
+    ];
+    for (const manifestPath of manifestPaths) {
+        if (!fs.existsSync(manifestPath)) {
+            continue;
+        }
+        // Manifests may contain comments (Sitevision's own docs show them), so
+        // parse as JSONC.
+        try {
+            return {
+                manifestPath,
+                manifest: parseJsonc(fs.readFileSync(manifestPath, 'utf-8')),
+            };
+        }
+        catch (error) {
+            throw new ManifestParseError(manifestPath, error);
+        }
+    }
+    return null;
+}
 /**
  * Detect if the current directory is a Sitevision project
  */
 export function detectProject(cwd = process.cwd()) {
     try {
-        // Look for manifest.json in multiple locations (current, static/, src/)
-        const manifestPaths = [
-            path.join(cwd, 'manifest.json'),
-            path.join(cwd, 'static', 'manifest.json'),
-            path.join(cwd, 'src', 'manifest.json'),
-        ];
-        let manifestPath = null;
-        let manifest = null;
-        for (const p of manifestPaths) {
-            if (fs.existsSync(p)) {
-                manifestPath = p;
-                manifest = JSON.parse(fs.readFileSync(p, 'utf-8'));
-                break;
-            }
-        }
-        if (!manifest || !manifestPath) {
+        const found = readManifest(cwd);
+        if (!found) {
             return null;
         }
+        const { manifestPath, manifest } = found;
         // Check for package.json
         const packageJsonPath = path.join(cwd, 'package.json');
         if (!fs.existsSync(packageJsonPath)) {
@@ -170,33 +310,23 @@ export function detectProject(cwd = process.cwd()) {
         // Check for node_modules
         const nodeModulesPath = path.join(cwd, 'node_modules');
         const hasNodeModules = fs.existsSync(nodeModulesPath);
-        // Check for dev properties
+        // Dev properties: ancestor files (workspace root) merged under the app's
+        // own file, so shared site/auth config lives once at the repo root.
         const devPropertiesPath = findDevPropertiesPath(cwd);
+        const inherited = readInheritedDevProperties(cwd);
+        const own = devPropertiesPath ? readDevPropertiesFile(cwd) : null;
+        const inheritedKeys = Object.keys(inherited).filter(key => !own || !Object.hasOwn(own, key));
         let devProperties;
-        let hasDevProperties = false;
+        const hasDevProperties = Boolean(own) || inheritedKeys.length > 0;
         let hasLegacyPassword = false;
-        if (devPropertiesPath) {
-            hasDevProperties = true;
+        if (hasDevProperties) {
             try {
-                const parsed = JSON.parse(fs.readFileSync(devPropertiesPath, 'utf-8'));
+                const parsed = { ...inherited, ...own };
                 hasLegacyPassword =
                     typeof parsed.password === 'string' && parsed.password.length > 0;
                 devProperties = parsed;
-                // Resolve deploy password: env var > keychain (file is legacy-only)
-                if (!hasLegacyPassword &&
-                    devProperties.domain &&
-                    devProperties.username) {
-                    const envPassword = process.env['SITEVISION_DEPLOY_PASSWORD'];
-                    if (envPassword) {
-                        devProperties.password = envPassword;
-                    }
-                    else {
-                        const stored = getDeployPassword(devProperties.domain, devProperties.username);
-                        if (stored) {
-                            devProperties.password = stored;
-                        }
-                    }
-                }
+                if (!hasLegacyPassword)
+                    resolveRuntimeSecrets(devProperties);
             }
             catch {
                 // Invalid dev properties file
@@ -213,16 +343,45 @@ export function detectProject(cwd = process.cwd()) {
             hasSigningProperties,
             hasLegacyPassword,
             devProperties,
+            inheritedKeys,
             packageJson,
             hasSitevisionScripts,
             hasNodeModules,
             paths,
         };
     }
-    catch {
+    catch (error) {
+        // A malformed manifest is a real error the user should see; everything else
+        // (missing files, unreadable optional config) just means "no project here".
+        if (error instanceof ManifestParseError) {
+            throw error;
+        }
         return null;
     }
 }
+/**
+ * Fill the runtime-only credential fields for the given domain/username:
+ * deploy password (env var > keychain), OAuth2 access token (env var), and
+ * session cookie (env var > keychain). Mutates and returns `dev`.
+ */
+export function resolveRuntimeSecrets(dev) {
+    if (dev.domain && dev.username) {
+        dev.password =
+            process.env['SITEVISION_DEPLOY_PASSWORD'] ??
+                getDeployPassword(dev.domain, dev.username) ??
+                undefined;
+    }
+    if (dev.authMethod === 'oauth2') {
+        dev.accessToken = process.env['SITEVISION_ACCESS_TOKEN'] ?? undefined;
+    }
+    if (dev.authMethod === 'cookie' && dev.domain) {
+        dev.sessionCookie =
+            process.env['SITEVISION_SESSION_COOKIE'] ??
+                getSessionCookie(dev.domain, dev.username) ??
+                undefined;
+    }
+    return dev;
+}
 /**
  * Validate that we're in a Sitevision project directory
  */
@@ -234,20 +393,31 @@ export function requireProject(cwd) {
     return project;
 }
 /**
- * Get the app type (web, widget, rest)
+ * The app type (web, widget, rest, mcp), or undefined for a manifest type
+ * this CLI does not know. Display code uses this so one odd app never takes
+ * the whole shell down.
  */
-export function getAppType(manifest) {
+export function appTypeOf(manifest) {
     const type = manifest.type.toLowerCase();
-    if (type.startsWith('web')) {
+    if (type.startsWith('web'))
         return 'web';
-    }
-    if (type.startsWith('widget')) {
+    if (type.startsWith('widget'))
         return 'widget';
-    }
-    if (type.startsWith('rest')) {
+    if (type.startsWith('rest'))
         return 'rest';
-    }
-    throw new Error(`Unknown app type: ${manifest.type}`);
+    if (type.startsWith('mcp'))
+        return 'mcp';
+    return undefined;
+}
+/**
+ * Get the app type (web, widget, rest, mcp). Throws for unknown types, since
+ * build and deploy cannot proceed without knowing the endpoints.
+ */
+export function getAppType(manifest) {
+    const type = appTypeOf(manifest);
+    if (!type)
+        throw new Error(`Unknown app type: ${manifest.type}`);
+    return type;
 }
 /**
  * Check if the app uses webpack bundling
@@ -271,14 +441,187 @@ export function readDevProperties(projectRoot) {
     }
 }
 /**
- * Write dev properties to file. The `password` field is never persisted —
- * it is held in the OS keychain instead.
+ * Write dev properties to file. Secrets are never persisted — `password`,
+ * `accessToken` and `sessionCookie` are held in the OS keychain / resolved at
+ * runtime instead.
  */
-export function writeDevProperties(projectRoot, properties) {
+export function writeDevProperties(projectRoot, properties, 
+// App mode: write every value, so plain sitevision-scripts finds them all.
+{ complete = false } = {}) {
     const devPropertiesPath = findDevPropertiesPath(projectRoot) ||
         getDefaultDevPropertiesPath(projectRoot);
-    const { password: _password, ...persisted } = properties;
-    fs.writeFileSync(devPropertiesPath, JSON.stringify(persisted, null, 2));
+    const { password: _password, accessToken: _accessToken, sessionCookie: _sessionCookie, environmentName: _environmentName, productionEnvironment: _productionEnvironment, ...persisted } = properties;
+    // Keep the app file minimal: values identical to the inherited ones stay
+    // at the workspace root instead of being copied into every app. An empty
+    // string means "unset", so it is dropped rather than written as an override
+    // that would shadow the inherited value.
+    const inherited = complete
+        ? {}
+        : readInheritedDevProperties(projectRoot);
+    const own = Object.fromEntries(Object.entries(persisted).filter(([key, value]) => value !== '' &&
+        (!Object.hasOwn(inherited, key) ||
+            JSON.stringify(inherited[key]) !== JSON.stringify(value))));
+    fs.writeFileSync(devPropertiesPath, JSON.stringify(own, null, 2));
+}
+export function readSvcConfig(projectRoot) {
+    try {
+        return parseJsonc(fs.readFileSync(path.join(projectRoot, '.svcconfig'), 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeSvcConfig(projectRoot, updates) {
+    const merged = { ...readSvcConfig(projectRoot), ...updates };
+    fs.writeFileSync(path.join(projectRoot, '.svcconfig'), JSON.stringify(merged, null, 2) + '\n');
+}
+// =============================================================================
+// PACKAGE.JSON SYNC
+// =============================================================================
+/**
+ * Values tied to the person running svc. They stay in .dev_properties.json and
+ * never go into package.json.
+ */
+export const USER_KEYS = ['username', 'signingUsername', 'certificateName'];
+// Shared values package.json can hold: three top-level fields, the rest under "svc".
+const PACKAGE_TOP_KEYS = {
+    domain: 'developmentDomain',
+    siteName: 'siteName',
+    addonName: 'addonName',
+};
+const PACKAGE_SVC_KEYS = [
+    'authMethod',
+    'oauth2',
+    'sessionLoginUrl',
+    'useHTTPForDevDeploy',
+    'baseEnvironment',
+    'production',
+    'environments',
+];
+function readPackageJson(projectRoot) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** The shared defaults one directory's package.json provides. */
+export function readPackageDefaults(dir) {
+    const packageJson = readPackageJson(dir);
+    if (!packageJson)
+        return {};
+    const defaults = {};
+    for (const [devKey, packageKey] of Object.entries(PACKAGE_TOP_KEYS)) {
+        const value = packageJson[packageKey];
+        if (typeof value === 'string' && value !== '')
+            defaults[devKey] = value;
+    }
+    const svc = packageJson['svc'];
+    for (const key of PACKAGE_SVC_KEYS) {
+        if (svc?.[key] !== undefined)
+            defaults[key] = svc[key];
+    }
+    if (typeof defaults['domain'] === 'string') {
+        defaults['domain'] = normalizeDomain(defaults['domain']);
+    }
+    return defaults;
+}
+/**
+ * Shared values in this directory's own .dev_properties.json that package.json
+ * does not already provide, here or further up. User values never qualify.
+ */
+function pendingSync(dir) {
+    const own = readDevPropertiesFile(dir);
+    if (!own)
+        return [];
+    const defaults = readPackageDefaultsChain(dir);
+    const pending = [];
+    for (const key of [...Object.keys(PACKAGE_TOP_KEYS), ...PACKAGE_SVC_KEYS]) {
+        let value = own[key];
+        if (key === 'environments' && value) {
+            value = Object.fromEntries(Object.entries(value).map(([name, override]) => [
+                name,
+                Object.fromEntries(Object.entries(override).filter(([field]) => !USER_KEYS.includes(field))),
+            ]));
+        }
+        if (value === undefined || value === '')
+            continue;
+        if (JSON.stringify(value) ===
+            JSON.stringify(defaults[key] ?? IMPLICIT_VALUES[key]))
+            continue;
+        pending.push({ key, value });
+    }
+    return pending;
+}
+/** What an unset field means, so spelling out the default is not a change. */
+export const IMPLICIT_VALUES = {
+    authMethod: 'basic',
+    useHTTPForDevDeploy: false,
+    production: false,
+};
+const packageLabel = (key) => PACKAGE_TOP_KEYS[key] ?? `svc.${key}`;
+const display = (value) => typeof value === 'string' ? value : JSON.stringify(value);
+/** What syncing this directory would change in its package.json. */
+export function getPackageJsonSyncChanges(dir) {
+    const current = readPackageDefaults(dir);
+    return pendingSync(dir).map(({ key, value }) => current[key] === undefined
+        ? { key: packageLabel(key), to: display(value) }
+        : {
+            key: packageLabel(key),
+            from: display(current[key]),
+            to: display(value),
+        });
+}
+export function hasPackageJson(dir) {
+    return fs.existsSync(path.join(dir, 'package.json'));
+}
+/**
+ * Copy the pending shared values from .dev_properties.json into package.json,
+ * creating package.json when the directory has none. Throws if it cannot be
+ * read or written.
+ */
+export function syncDevPropertiesToPackageJson(dir) {
+    const pending = pendingSync(dir);
+    if (pending.length === 0 && hasPackageJson(dir))
+        return false;
+    updatePackageJson(dir, packageJson => {
+        for (const { key, value } of pending) {
+            const topKey = PACKAGE_TOP_KEYS[key];
+            if (topKey) {
+                packageJson[topKey] = value;
+            }
+            else {
+                packageJson['svc'] = {
+                    ...packageJson['svc'],
+                    [key]: value,
+                };
+            }
+        }
+    });
+    return true;
+}
+/**
+ * Edit package.json in place, keeping its indentation and trailing newline. A
+ * missing file is created; an unreadable or invalid one throws, so the caller
+ * can warn instead of dropping the change silently.
+ */
+export function updatePackageJson(dir, mutate) {
+    const packageJsonPath = path.join(dir, 'package.json');
+    // A new file is private, so a workspace root is never published by accident.
+    let raw = '{\n\t"private": true\n}\n';
+    try {
+        if (hasPackageJson(dir))
+            raw = fs.readFileSync(packageJsonPath, 'utf-8');
+        const packageJson = JSON.parse(raw);
+        mutate(packageJson);
+        const indent = /^(?<indent>[\t ]+)/m.exec(raw)?.groups?.['indent'] ?? '\t';
+        const newline = raw.endsWith('\n') ? '\n' : '';
+        fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, indent) + newline);
+    }
+    catch (error) {
+        throw new Error(`Could not update ${packageJsonPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
 }
 /**
  * Move a plaintext password from .dev_properties.json into the OS keychain and
@@ -295,8 +638,22 @@ export function migrateLegacyPassword(project) {
         return false;
     if (!setDeployPassword(domain, username, password))
         return false;
-    // writeDevProperties strips `password` defensively; keep the in-memory value.
-    writeDevProperties(project.root, project.devProperties);
+    // Remove only the password, from whichever file holds it; every other value
+    // stays as written.
+    for (const dir of [project.root, ...ancestorDirs(project.root)]) {
+        const file = findDevPropertiesPath(dir);
+        if (!file)
+            continue;
+        try {
+            const { password: stored, ...rest } = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (stored !== undefined) {
+                fs.writeFileSync(file, JSON.stringify(rest, null, 2));
+            }
+        }
+        catch {
+            // Unreadable file: nothing to migrate there.
+        }
+    }
     project.hasLegacyPassword = false;
     return true;
 }

package/dist/utils/session-cookie-auth.d.ts

@@ -0,0 +1,35 @@
+import type { DevProperties } from '../types/index.js';
+interface RawCookie {
+    name: string;
+    value: string;
+    domain: string;
+}
+export interface CaptureResult {
+    cookie?: string;
+    note?: string;
+    error?: string;
+}
+export interface CookieLoginSession {
+    capture: () => Promise<CaptureResult>;
+    close: () => Promise<void>;
+    loginUrl: string;
+}
+/**
+ * Pick the session from a cookie jar: find JSESSIONID (preferring the deploy
+ * host), then return every cookie on that host as a `Cookie:` header. On miss,
+ * return diagnostics naming the domains actually seen. Pure — no keychain, no
+ * browser — so it's unit-testable.
+ */
+export declare function selectSessionCookie(all: RawCookie[], siteDomain: string): CaptureResult;
+/**
+ * Launch a real browser at the login URL for an interactive SAML/SSO login and
+ * return handles to capture the session and close the browser. UI-agnostic: the
+ * Ink login screen decides when to `capture()` (on the user's keypress) and
+ * `close()`. Returns null if the browser can't be launched.
+ *
+ * `capture()` reads the whole cookie jar via CDP (httponly and secure included),
+ * stores the session in the keychain on success, and otherwise returns
+ * diagnostics naming the cookie domains it actually saw.
+ */
+export declare function beginCookieLogin(dev: DevProperties): Promise<CookieLoginSession | null>;
+export {};

package/dist/utils/session-cookie-auth.js

@@ -0,0 +1,99 @@
+import { setSessionCookie } from './keychain.js';
+function bareDomain(domain) {
+    return domain.replace(/^\./, '');
+}
+/** Related if either host is the other or a subdomain of it (both directions). */
+function domainRelated(a, b) {
+    const x = bareDomain(a);
+    const y = bareDomain(b);
+    return x === y || x.endsWith(`.${y}`) || y.endsWith(`.${x}`);
+}
+/**
+ * Pick the session from a cookie jar: find JSESSIONID (preferring the deploy
+ * host), then return every cookie on that host as a `Cookie:` header. On miss,
+ * return diagnostics naming the domains actually seen. Pure — no keychain, no
+ * browser — so it's unit-testable.
+ */
+export function selectSessionCookie(all, siteDomain) {
+    const sessions = all.filter(c => c.name === 'JSESSIONID');
+    if (sessions.length === 0) {
+        const domains = [...new Set(all.map(c => bareDomain(c.domain)))];
+        return {
+            error: `No JSESSIONID among ${all.length} cookies. Domains seen: ${domains.join(', ') || 'none'}. If these are only your IdP, open a Sitevision page in the browser, then press Enter again.`,
+        };
+    }
+    const chosen = sessions.find(c => domainRelated(c.domain, siteDomain)) ?? sessions[0];
+    const cookies = all.filter(c => domainRelated(c.domain, chosen.domain));
+    return {
+        cookie: cookies.map(c => `${c.name}=${c.value}`).join('; '),
+        note: `Captured session on ${bareDomain(chosen.domain)} (${cookies.length} cookies).`,
+    };
+}
+/** Read every cookie in the browser jar (httponly and secure included). */
+async function readAllCookies(browser, page) {
+    // puppeteer >= 22 exposes the whole jar directly.
+    if (typeof browser.cookies === 'function') {
+        try {
+            return (await browser.cookies());
+        }
+        catch {
+            // Fall through to CDP.
+        }
+    }
+    const client = await page.createCDPSession();
+    const { cookies } = await client.send('Network.getAllCookies');
+    return cookies;
+}
+/**
+ * Launch a real browser at the login URL for an interactive SAML/SSO login and
+ * return handles to capture the session and close the browser. UI-agnostic: the
+ * Ink login screen decides when to `capture()` (on the user's keypress) and
+ * `close()`. Returns null if the browser can't be launched.
+ *
+ * `capture()` reads the whole cookie jar via CDP (httponly and secure included),
+ * stores the session in the keychain on success, and otherwise returns
+ * diagnostics naming the cookie domains it actually saw.
+ */
+export async function beginCookieLogin(dev) {
+    const { domain, username } = dev;
+    if (!domain)
+        return null;
+    let puppeteer;
+    try {
+        ({ default: puppeteer } = await import('puppeteer-core'));
+    }
+    catch {
+        return null;
+    }
+    let browser;
+    try {
+        browser = await puppeteer.launch({ headless: false, channel: 'chrome' });
+        const page = await browser.newPage();
+        const loginUrl = dev.sessionLoginUrl || `https://${domain}/`;
+        await page.goto(loginUrl, { waitUntil: 'domcontentloaded' }).catch(() => {
+            // A SAML redirect may abort the initial navigation — that's fine.
+        });
+        const capture = async () => {
+            const all = await readAllCookies(browser, page);
+            const result = selectSessionCookie(all, domain);
+            if (result.cookie) {
+                setSessionCookie(domain, username, result.cookie);
+            }
+            return result;
+        };
+        const close = async () => {
+            await browser.close().catch(() => {
+                // Best-effort close.
+            });
+        };
+        return { capture, close, loginUrl };
+    }
+    catch {
+        if (browser) {
+            await browser.close().catch(() => {
+                // Best-effort close.
+            });
+        }
+        return null;
+    }
+}