mcp-ado-browser 1.2.1

package/dist/src/ado/schemas.js

@@ -0,0 +1,178 @@
+/**
+ * Declared OUTPUT schemas (zod). Every tool validates its normalized output here
+ * before returning. A missing/mistyped field => ValidationError => a failing gate
+ * (schema-drift detection, mission §7).
+ *
+ * Outputs are NORMALIZED shapes (not raw ADO blobs): tools map raw ADO JSON into
+ * these, keeping the full raw payload under `raw`/`rawFields` for completeness.
+ */
+import { z } from "zod";
+import { ValidationError } from "../errors.js";
+export const RelationSchema = z.object({
+    rel: z.string(),
+    url: z.string(),
+    attributes: z.record(z.unknown()).optional(),
+    /** Parsed PR reference when rel is an ArtifactLink to a Git pull request. */
+    pullRequest: z
+        .object({ projectId: z.string(), repositoryId: z.string(), pullRequestId: z.number() })
+        .optional(),
+    /** Linked work item id when the relation points at another work item. */
+    workItemId: z.number().optional(),
+});
+export const WorkItemSchema = z.object({
+    id: z.number(),
+    rev: z.number(),
+    url: z.string(),
+    type: z.string(), // System.WorkItemType
+    title: z.string(), // System.Title
+    state: z.string(), // System.State
+    fields: z.record(z.unknown()),
+    relations: z.array(RelationSchema),
+});
+export const WorkItemSummarySchema = z.object({
+    id: z.number(),
+    type: z.string().nullable(),
+    title: z.string().nullable(),
+    state: z.string().nullable(),
+    fields: z.record(z.unknown()).optional(),
+});
+export const WorkItemSearchResultSchema = z.object({
+    count: z.number(),
+    items: z.array(WorkItemSummarySchema),
+    /** "wiql" | "almsearch" — which backend served the result. */
+    backend: z.string(),
+});
+export const CommentSchema = z.object({
+    id: z.number(),
+    text: z.string(),
+    createdBy: z.string().nullable(),
+    createdDate: z.string().nullable(),
+    modifiedDate: z.string().nullable().optional(),
+});
+export const WorkItemCommentsSchema = z.object({
+    workItemId: z.number(),
+    totalCount: z.number(),
+    count: z.number(),
+    comments: z.array(CommentSchema),
+});
+export const AttachmentRefSchema = z.object({
+    guid: z.string(),
+    name: z.string(),
+    url: z.string(),
+    /** Where the reference came from: a work-item relation or a comment body. */
+    source: z.enum(["relation", "comment-body"]),
+});
+export const DownloadedAttachmentSchema = AttachmentRefSchema.extend({
+    size: z.number(),
+    contentLength: z.number().nullable(),
+    sha256: z.string(),
+    savedPath: z.string().nullable(),
+});
+export const CommentDetailsSchema = z.object({
+    workItemId: z.number(),
+    comment: CommentSchema.nullable(),
+    attachments: z.array(DownloadedAttachmentSchema),
+});
+export const PullRequestSummarySchema = z.object({
+    pullRequestId: z.number(),
+    title: z.string().nullable(),
+    status: z.string().nullable(),
+    createdBy: z.string().nullable(),
+    sourceRefName: z.string().nullable(),
+    targetRefName: z.string().nullable(),
+    repositoryId: z.string().nullable(),
+    repositoryName: z.string().nullable(),
+});
+export const PullRequestSearchResultSchema = z.object({
+    count: z.number(),
+    items: z.array(PullRequestSummarySchema),
+});
+export const PullRequestSchema = z.object({
+    pullRequestId: z.number(),
+    title: z.string().nullable(),
+    description: z.string().nullable(),
+    status: z.string().nullable(),
+    createdBy: z.string().nullable(),
+    sourceRefName: z.string().nullable(),
+    targetRefName: z.string().nullable(),
+    repositoryId: z.string().nullable(),
+    repositoryName: z.string().nullable(),
+    reviewers: z.array(z.object({ id: z.string().nullable(), displayName: z.string().nullable(), vote: z.number().nullable() })),
+    workItemRefs: z.array(z.object({ id: z.string(), url: z.string() })),
+    raw: z.record(z.unknown()),
+});
+export const ThreadCommentSchema = z.object({
+    id: z.number(),
+    content: z.string().nullable(),
+    author: z.string().nullable(),
+    commentType: z.string().nullable(),
+    publishedDate: z.string().nullable(),
+});
+export const PrThreadSchema = z.object({
+    id: z.number(),
+    kind: z.enum(["system", "human"]),
+    status: z.string().nullable(),
+    comments: z.array(ThreadCommentSchema),
+});
+export const PullRequestCommentsSchema = z.object({
+    pullRequestId: z.number(),
+    threadCount: z.number(),
+    systemThreadCount: z.number(),
+    humanThreadCount: z.number(),
+    threads: z.array(PrThreadSchema),
+});
+export const PackageVersionSchema = z.object({ id: z.string().nullable(), version: z.string(), isLatest: z.boolean().nullable() });
+export const PackageSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    protocolType: z.string().nullable(),
+    versions: z.array(PackageVersionSchema),
+});
+export const FeedSchema = z.object({ id: z.string(), name: z.string(), url: z.string().nullable() });
+export const FeedsBrowseSchema = z.object({
+    feeds: z.array(FeedSchema),
+    /** Present when a specific feedId was browsed for its packages. */
+    packages: z.array(PackageSchema).optional(),
+});
+export const ProjectSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    state: z.string().nullable(),
+    description: z.string().nullable(),
+    lastUpdateTime: z.string().nullable(),
+});
+export const ProjectsListSchema = z.object({ count: z.number(), items: z.array(ProjectSchema) });
+export const RepositorySchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    project: z.string().nullable(),
+    defaultBranch: z.string().nullable(),
+    webUrl: z.string().nullable(),
+    isDisabled: z.boolean().nullable(),
+});
+export const RepositoriesListSchema = z.object({ count: z.number(), items: z.array(RepositorySchema) });
+export const DownloadedArtifactSchema = z.object({
+    feedId: z.string(),
+    packageName: z.string(),
+    version: z.string(),
+    protocol: z.enum(["nuget", "npm"]),
+    size: z.number(),
+    contentLength: z.number().nullable(),
+    sha256: z.string(),
+    savedPath: z.string(),
+    archiveValid: z.boolean(),
+    archiveDetail: z.string(),
+});
+export const AuthResultSchema = z.object({
+    authenticated: z.boolean(),
+    identity: z.string().nullable(),
+    message: z.string(),
+});
+/** Validate `value` against `schema`, raising a ValidationError on drift. */
+export function validateOutput(schema, value, label) {
+    const r = schema.safeParse(value);
+    if (!r.success) {
+        throw new ValidationError(`${label} output failed schema validation`, r.error.issues);
+    }
+    return r.data;
+}

package/dist/src/ado/versions.js

@@ -0,0 +1,52 @@
+/**
+ * api-version handling. Mission rule: api-versions are NOT hardcoded across the
+ * codebase. They are either (a) supplied via ADO_API_VERSION, or (b) discovered,
+ * or (c) fall back to a SINGLE centralized default table living only here.
+ *
+ * `versions.ts` is the one and only place an api-version literal may appear, and
+ * the grep gate explicitly excludes this file from the "no hardcoded api-version"
+ * scan because here they are the documented, overridable fallback registry.
+ */
+/** Fallback defaults — used only when neither config override nor discovery applies. */
+const DEFAULT_VERSIONS = {
+    wit: "7.1",
+    "wit-comments": "7.1-preview.4",
+    git: "7.1",
+    "packaging-feeds": "7.1-preview.1",
+    "packaging-pkgs": "7.1-preview.1",
+    search: "7.1-preview.1",
+    analytics: "v4.0-preview",
+    // connectionData is a PREVIEW resource: a non-preview api-version returns HTTP 400
+    // (VssInvalidPreviewVersionException). Confirmed empirically against a live org.
+    core: "7.1-preview",
+};
+export class VersionRegistry {
+    override;
+    discovered = {};
+    constructor(override) {
+        this.override = override;
+    }
+    /** Resolve effective version for an area: explicit override > discovered > default. */
+    forArea(area) {
+        if (this.override)
+            return this.override;
+        return this.discovered[area] ?? DEFAULT_VERSIONS[area];
+    }
+    /** Record a version learned via discovery (e.g. OPTIONS / ResourceAreas). */
+    setDiscovered(area, version) {
+        this.discovered[area] = version;
+    }
+    snapshot() {
+        const out = {};
+        for (const area of Object.keys(DEFAULT_VERSIONS))
+            out[area] = this.forArea(area);
+        return out;
+    }
+}
+/** Append api-version to a URL, respecting an already-present query string. */
+export function withApiVersion(url, version) {
+    if (/[?&]api-version=/.test(url))
+        return url;
+    const sep = url.includes("?") ? "&" : "?";
+    return `${url}${sep}api-version=${encodeURIComponent(version)}`;
+}

package/dist/src/browser/auth-detect.js

@@ -0,0 +1,47 @@
+/**
+ * Login-detection logic, isolated from Playwright so it is deterministically
+ * testable against MockAdoServer (Gate 0). The interactive window is driven by
+ * BrowserSession; this module only decides "is this connectionData authenticated?"
+ * and runs the polling loop.
+ */
+import { AuthRequiredError } from "../errors.js";
+const ANON_ID = "00000000-0000-0000-0000-000000000000";
+/** Decide whether a connectionData payload represents a real, signed-in identity. */
+export function detectIdentity(connectionData) {
+    const u = connectionData?.authenticatedUser;
+    if (!u)
+        return null;
+    const provider = u.providerDisplayName ?? u.properties?.Account?.$value;
+    const isAnon = provider === "Anonymous" || u.id === ANON_ID;
+    if (isAnon)
+        return null;
+    if (!u.subjectDescriptor && !u.descriptor)
+        return null;
+    return { id: String(u.id), displayName: String(provider ?? u.id), descriptor: u.subjectDescriptor ?? u.descriptor };
+}
+/**
+ * Poll `fetchConnectionData` until it yields an authenticated identity or the
+ * deadline passes. `fetchConnectionData` should throw on 401 (dead session); we
+ * swallow that and keep waiting for the human to finish signing in.
+ */
+export async function pollUntilAuthenticated(fetchConnectionData, opts) {
+    const now = opts.now ?? (() => Date.now());
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const interval = opts.intervalMs ?? 2000;
+    const deadline = now() + opts.timeoutMs;
+    do {
+        try {
+            const data = await fetchConnectionData();
+            const id = detectIdentity(data);
+            if (id)
+                return id;
+        }
+        catch {
+            /* dead session / transient — keep polling until deadline */
+        }
+        if (now() >= deadline)
+            break;
+        await sleep(interval);
+    } while (now() < deadline);
+    throw new AuthRequiredError();
+}

package/dist/src/browser/session.js

@@ -0,0 +1,201 @@
+/**
+ * BrowserSession — owns a Playwright persistent context on an ISOLATED, dedicated
+ * profile (never the user's daily browser). Work runs headless; the window is only
+ * made visible during the interactive (re)authentication flow.
+ *
+ * Data access is done via `page.evaluate(fetch(...))` executed in the page's own
+ * origin so the session cookies attach automatically and JSON comes back. The DOM
+ * is touched ONLY for the interactive login.
+ *
+ * Uses playwright-core + channel:'chrome'|'msedge' => relies on an already-installed
+ * browser and NEVER downloads a Playwright Chromium (mission §2 / restricted env).
+ */
+import { chromium } from "playwright-core";
+import { AuthRequiredError, HttpError, NotFoundError } from "../errors.js";
+import { log } from "../logger.js";
+import { HostResolver } from "../ado/hosts.js";
+import { VersionRegistry, withApiVersion } from "../ado/versions.js";
+import { mandatoryHeaders } from "../transport/types.js";
+import { detectIdentity, pollUntilAuthenticated } from "./auth-detect.js";
+export class BrowserSession {
+    opts;
+    context;
+    page;
+    launchedHeadless;
+    hosts;
+    transport;
+    versions;
+    constructor(opts) {
+        this.opts = opts;
+        this.hosts = new HostResolver(opts.org);
+        this.transport = new BrowserTransport(this);
+        this.versions = opts.versions ?? new VersionRegistry(null);
+    }
+    connectionDataUrl() {
+        return withApiVersion(`${this.hosts.base("core")}/_apis/connectionData`, this.versions.forArea("core"));
+    }
+    async ensureLaunched(headless) {
+        if (this.context && this.launchedHeadless === headless)
+            return;
+        if (this.context)
+            await this.close();
+        log.info(`Launching ${this.opts.channel} (headless=${headless}) on isolated profile ${this.opts.userDataDir}`);
+        const args = ["--no-first-run", "--no-default-browser-check"];
+        // Visible (auth) window: open in Chrome "app" mode — a clean, chromeless window
+        // (no address bar, toolbar, tabs or bookmarks), pointed straight at the org URL.
+        // Opt out with ADO_APP_WINDOW=0.
+        if (!headless && process.env.ADO_APP_WINDOW !== "0") {
+            args.push(`--app=${this.hosts.base("core")}`, "--window-size=1100,820");
+        }
+        this.context = await chromium.launchPersistentContext(this.opts.userDataDir, {
+            headless,
+            channel: this.opts.channel,
+            viewport: null,
+            // Enable Chromium's sandbox for the VISIBLE auth window so it doesn't show the
+            // "--no-sandbox / security will suffer" banner (playwright-core defaults the
+            // sandbox OFF). Headless work runs keep the default (no banner is shown there
+            // anyway, and it avoids any sandbox-init issues in restricted environments).
+            // Force-disable everywhere with ADO_NO_SANDBOX=1.
+            chromiumSandbox: !headless && process.env.ADO_NO_SANDBOX !== "1",
+            args,
+        });
+        this.page = this.context.pages()[0] ?? (await this.context.newPage());
+        this.launchedHeadless = headless;
+    }
+    currentPage() {
+        if (!this.page)
+            throw new Error("BrowserSession not launched");
+        return this.page;
+    }
+    /**
+     * Interactive login. Opens a VISIBLE window, lets the human complete MFA, and
+     * detects success by polling an authenticated endpoint (connectionData) until it
+     * returns a real (non-anonymous) identity. Session is persisted in userDataDir.
+     */
+    async authenticate(timeoutMs = 300_000) {
+        await this.ensureLaunched(false);
+        const page = this.currentPage();
+        // Navigate to the ORG-scoped URL (not the bare origin): the bare dev.azure.com
+        // root redirects unauthenticated users to the marketing page, while the
+        // org-scoped URL triggers the AAD sign-in flow.
+        const orgUrl = this.hosts.base("core");
+        try {
+            await page.goto(orgUrl, { waitUntil: "domcontentloaded", timeout: 60_000 });
+        }
+        catch (e) {
+            log.debug(`authenticate initial nav note: ${String(e)}`);
+        }
+        log.info("Waiting for interactive sign-in (MFA). Complete the login in the open window.");
+        // Poll via context.request so we read connectionData using the SHARED session
+        // cookie jar without CORS and WITHOUT navigating the user's login tab away.
+        const id = await pollUntilAuthenticated(() => this.requestConnectionData(), { timeoutMs });
+        log.info(`Signed in as ${id.displayName}`);
+        return id;
+    }
+    /** Read connectionData via the context's cookie jar (used by auth polling + validate). */
+    async requestConnectionData() {
+        if (!this.context)
+            throw new Error("BrowserSession not launched");
+        const res = await this.context.request.get(this.connectionDataUrl(), { headers: mandatoryHeaders() });
+        if (res.status() === 401)
+            throw new AuthRequiredError(this.connectionDataUrl());
+        if (!res.ok())
+            throw new HttpError(res.status(), this.connectionDataUrl());
+        return res.json();
+    }
+    /**
+     * Cross-host data fetch via the context cookie jar. Used for hosts other than the
+     * core dev.azure.com origin (feeds/pkgs/search/analytics): navigating a real page
+     * to those hosts is unreliable (bare org paths 4xx, download URLs trigger file
+     * downloads), but context.request carries the SAME authenticated session cookies
+     * without CORS or page navigation. Still strictly the browser session — no PAT.
+     */
+    async contextFetchJson(url, init) {
+        const res = await this.context.request.fetch(url, { method: init?.method ?? "GET", headers: mandatoryHeaders(init?.headers), data: init?.body });
+        const headers = res.headers();
+        if (res.status() === 401 || res.status() === 403)
+            throw new AuthRequiredError(url);
+        if (res.status() === 404)
+            throw new NotFoundError("resource", url, url);
+        if (!res.ok())
+            throw new HttpError(res.status(), url, (await res.text()).slice(0, 500));
+        return { data: (await res.json()), headers };
+    }
+    async contextFetchBuffer(url, init) {
+        const res = await this.context.request.fetch(url, { method: init?.method ?? "GET", headers: mandatoryHeaders({ Accept: "application/octet-stream", ...(init?.headers ?? {}) }), data: init?.body });
+        const headers = res.headers();
+        if (res.status() === 401 || res.status() === 403)
+            throw new AuthRequiredError(url);
+        if (res.status() === 404)
+            throw new NotFoundError("resource", url, url);
+        if (!res.ok())
+            throw new HttpError(res.status(), url, (await res.text()).slice(0, 500));
+        const data = await res.body();
+        const cl = headers["content-length"];
+        return { data, contentLength: cl != null ? Number(cl) : null, contentType: headers["content-type"] ?? null, headers };
+    }
+    /** Who is the persisted session signed in as? Returns null if not authenticated. */
+    async whoami() {
+        try {
+            await this.ensureLaunched(true);
+            return detectIdentity(await this.requestConnectionData());
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Lightweight check: is the persisted session currently valid? */
+    async validate() {
+        return (await this.whoami()) !== null;
+    }
+    async close() {
+        try {
+            await this.context?.close();
+        }
+        catch {
+            /* ignore */
+        }
+        this.context = undefined;
+        this.page = undefined;
+        this.launchedHeadless = undefined;
+    }
+}
+/**
+ * AdoTransport over a live BrowserSession. Every request goes through the browser
+ * CONTEXT's cookie jar (Playwright APIRequestContext): it carries the SAME
+ * authenticated session cookies as the page, works same- AND cross-host, and returns
+ * clean HTTP status codes (401 -> AUTH_REQUIRED, 404 -> NOT_FOUND).
+ *
+ * Why not page.evaluate(fetch)? It proved unreliable in real headless runtimes:
+ * navigating to a JSON endpoint, SPA redirects, and corporate proxies (Chrome's
+ * renderer network stack vs Node's) surface as "TypeError: Failed to fetch". The
+ * cookie jar uses the same session but Node's network path — robust everywhere.
+ */
+export class BrowserTransport {
+    session;
+    kind = "browser";
+    calledUrls = [];
+    fetchCount = 0;
+    lastHeaders = {};
+    constructor(session) {
+        this.session = session;
+    }
+    resetCounters() {
+        this.calledUrls.length = 0;
+        this.fetchCount = 0;
+    }
+    async fetchJson(url, init) {
+        this.calledUrls.push(url);
+        this.fetchCount++;
+        const res = await this.session.contextFetchJson(url, init);
+        this.lastHeaders = res.headers;
+        return res;
+    }
+    async fetchBuffer(url, init) {
+        this.calledUrls.push(url);
+        this.fetchCount++;
+        const res = await this.session.contextFetchBuffer(url, init);
+        this.lastHeaders = res.headers;
+        return res;
+    }
+}

package/dist/src/cache/sqlite-cache.js

@@ -0,0 +1,66 @@
+/**
+ * SqliteCache — persistent query cache backed by node:sqlite (built into Node >=22.5).
+ *
+ * Why node:sqlite (mission §2): zero native build, nothing to compile, nothing that
+ * a restricted environment can block at install time. better-sqlite3 was rejected
+ * for its native build step. The DB file persists across process restarts (Gate 2).
+ *
+ * Logical cache identity is (kind, key, version): the row carries the resource
+ * version (work item Rev, etc.) so a freshness oracle can confirm the cached value
+ * is still current without a full re-fetch.
+ */
+import { DatabaseSync } from "node:sqlite";
+import * as fs from "node:fs";
+import * as path from "node:path";
+export class SqliteCache {
+    opts;
+    db;
+    constructor(opts) {
+        this.opts = opts;
+        if (opts.dbPath !== ":memory:")
+            fs.mkdirSync(path.dirname(opts.dbPath), { recursive: true });
+        this.db = new DatabaseSync(opts.dbPath);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS cache (
+        kind         TEXT NOT NULL,
+        key          TEXT NOT NULL,
+        version      TEXT NOT NULL,
+        value        TEXT NOT NULL,
+        stored_at    INTEGER NOT NULL,
+        validated_at INTEGER NOT NULL,
+        PRIMARY KEY (kind, key)
+      );
+    `);
+    }
+    get(kind, key) {
+        const row = this.db.prepare(`SELECT version, value, stored_at, validated_at FROM cache WHERE kind = ? AND key = ?`).get(kind, key);
+        if (!row)
+            return null;
+        return { value: JSON.parse(row.value), version: row.version, storedAt: row.stored_at, validatedAt: row.validated_at };
+    }
+    set(kind, key, value, version) {
+        const now = Date.now();
+        this.db
+            .prepare(`INSERT INTO cache (kind, key, version, value, stored_at, validated_at)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(kind, key) DO UPDATE SET version=excluded.version, value=excluded.value, stored_at=excluded.stored_at, validated_at=excluded.validated_at`)
+            .run(kind, key, version, JSON.stringify(value), now, now);
+    }
+    touch(kind, key) {
+        this.db.prepare(`UPDATE cache SET validated_at = ? WHERE kind = ? AND key = ?`).run(Date.now(), kind, key);
+    }
+    ttlFor(kind) {
+        const o = this.opts.ttlOverrides[kind];
+        return o !== undefined ? o : this.opts.defaultTtlSeconds;
+    }
+    clear() {
+        this.db.exec(`DELETE FROM cache`);
+    }
+    /** Test/diagnostic hook: artificially age an entry so the freshness path triggers. */
+    expire(kind, key) {
+        this.db.prepare(`UPDATE cache SET validated_at = 0, stored_at = 0 WHERE kind = ? AND key = ?`).run(kind, key);
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/src/cache/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/cli.js

@@ -0,0 +1,50 @@
+const FLAG_TO_ENV = {
+    org: "ADO_ORG",
+    project: "ADO_PROJECT",
+    channel: "ADO_BROWSER_CHANNEL",
+    "user-data-dir": "ADO_USER_DATA_DIR",
+    "cache-ttl": "ADO_CACHE_TTL_SECONDS",
+    "api-version": "ADO_API_VERSION",
+    "log-level": "ADO_LOG_LEVEL",
+};
+/** Boolean flags (presence => value). */
+const BOOL_FLAGS = {
+    "no-app-window": ["ADO_APP_WINDOW", "0"],
+    "no-sandbox": ["ADO_NO_SANDBOX", "1"],
+    headed: ["ADO_HEADLESS", "0"],
+};
+export function parseArgs(argv) {
+    const env = {};
+    let command = null;
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok.startsWith("--")) {
+            const body = tok.slice(2);
+            const eq = body.indexOf("=");
+            const name = eq === -1 ? body : body.slice(0, eq);
+            if (BOOL_FLAGS[name]) {
+                const [k, v] = BOOL_FLAGS[name];
+                env[k] = v;
+                continue;
+            }
+            const envKey = FLAG_TO_ENV[name];
+            if (!envKey)
+                continue; // unknown flag: ignore (help/-h handled by caller)
+            let value;
+            if (eq !== -1)
+                value = body.slice(eq + 1);
+            else
+                value = argv[++i] ?? "";
+            env[envKey] = value;
+        }
+        else if (command === null) {
+            command = tok;
+        }
+    }
+    return { command, env };
+}
+/** Apply parsed flag overrides onto process.env (CLI precedence over existing env). */
+export function applyArgs(parsed) {
+    for (const [k, v] of Object.entries(parsed.env))
+        process.env[k] = v;
+}

package/dist/src/config.js

@@ -0,0 +1,70 @@
+/**
+ * All runtime configuration is sourced from environment variables (mission §9).
+ * Nothing about a specific org/project/id/api-version is ever hardcoded — every
+ * such value flows through here or through dynamic discovery.
+ */
+import { z } from "zod";
+import * as os from "node:os";
+import * as path from "node:path";
+import { ConfigError } from "./errors.js";
+const intFromEnv = (def) => z
+    .string()
+    .optional()
+    .transform((v) => (v === undefined || v === "" ? def : Number(v)))
+    .pipe(z.number().int().nonnegative());
+/** Default persistent profile dir: an isolated, dedicated profile (NOT the user's daily browser). */
+function defaultUserDataDir() {
+    return path.join(os.homedir(), ".mcp-ado-browser", "profile");
+}
+const ChannelSchema = z.enum(["chrome", "msedge"]);
+/**
+ * Parse env. `requireConnection` enforces org/project presence (needed for live);
+ * mock-only runs can proceed without them.
+ */
+export function loadConfig(env = process.env) {
+    const channel = ChannelSchema.safeParse(env.ADO_BROWSER_CHANNEL ?? "chrome");
+    if (!channel.success)
+        throw new ConfigError(`ADO_BROWSER_CHANNEL must be 'chrome' or 'msedge'`);
+    const userDataDir = env.ADO_USER_DATA_DIR && env.ADO_USER_DATA_DIR.trim() !== "" ? env.ADO_USER_DATA_DIR : defaultUserDataDir();
+    const ttl = intFromEnv(900).parse(env.ADO_CACHE_TTL_SECONDS);
+    // Per-resource overrides: ADO_CACHE_TTL_<RESOURCE>=seconds (e.g. ADO_CACHE_TTL_WORKITEM=60)
+    const overrides = {};
+    for (const [k, v] of Object.entries(env)) {
+        const m = k.match(/^ADO_CACHE_TTL_([A-Z_]+)$/);
+        if (m && v != null && v !== "" && k !== "ADO_CACHE_TTL_SECONDS") {
+            const n = Number(v);
+            if (Number.isFinite(n) && n >= 0)
+                overrides[m[1].toLowerCase()] = n;
+        }
+    }
+    const dataRoot = path.join(userDataDir, "..");
+    const num = (v) => (v && v.trim() !== "" ? Number(v) : null);
+    const str = (v) => (v && v.trim() !== "" ? v.trim() : null);
+    return {
+        org: str(env.ADO_ORG),
+        project: str(env.ADO_PROJECT),
+        userDataDir,
+        browserChannel: channel.data,
+        cacheTtlSeconds: ttl,
+        cacheTtlOverrides: overrides,
+        apiVersionOverride: str(env.ADO_API_VERSION),
+        cacheDbPath: env.ADO_CACHE_DB && env.ADO_CACHE_DB.trim() !== "" ? env.ADO_CACHE_DB : path.join(dataRoot, "cache.sqlite"),
+        fixturesDir: env.ADO_FIXTURES_DIR && env.ADO_FIXTURES_DIR.trim() !== "" ? env.ADO_FIXTURES_DIR : path.join(process.cwd(), "fixtures"),
+        test: {
+            workItemId: num(env.ADO_TEST_WORKITEM_ID),
+            repoId: str(env.ADO_TEST_REPO_ID),
+            prId: num(env.ADO_TEST_PR),
+            feedId: str(env.ADO_TEST_FEED),
+        },
+        headless: env.ADO_HEADLESS === "0" ? false : true,
+    };
+}
+/**
+ * Only the ORGANIZATION is required. The project is optional: the server browses
+ * EVERY project, repo and feed the user can access. A configured project is only
+ * ever used as a default scope for tools that accept an optional `project` arg.
+ */
+export function requireConnection(cfg) {
+    if (!cfg.org)
+        throw new ConfigError("ADO_ORG is required");
+}