@aexol/spectral 0.0.1

package/dist/commands/login.js

@@ -0,0 +1,109 @@
+/**
+ * `spectral login` — interactive authentication against the Aexol MCP backend.
+ *
+ * Flow:
+ *   1. Prompt for API URL (default = SPECTRAL_MCP_URL env, else hard default).
+ *   2. Prompt for team API key (masked input). Verify the sk-aexol-team- prefix
+ *      locally so we don't send obviously-wrong credentials.
+ *   3. Verify reachability + auth by calling tools/list against the URL.
+ *   4. On success: persist to ~/.spectral/config.json (mode 0600).
+ *
+ * Exits non-zero on any failure so shell scripts can detect it.
+ *
+ * NOTE: pure logic lives in `performLogin` — the interactive `runLogin`
+ * wrapper delegates to it after collecting prompts. Tests target
+ * `performLogin` directly so we don't have to drive `@inquirer/prompts`.
+ */
+import { input, password } from "@inquirer/prompts";
+import pc from "picocolors";
+import { DEFAULT_API_URL, TEAM_API_KEY_PREFIX, getConfigFile, validateTeamApiKey, writeConfig, } from "../config.js";
+import { AexolMcpClient, AexolMcpError } from "../mcp-client.js";
+/**
+ * Pure login logic. Throws `Error` with one of these stable message prefixes:
+ *   - "Invalid API key prefix"  — local validation failed
+ *   - "Invalid token"           — server returned 401/403
+ *   - "Authentication failed"   — server rejected the request (other 4xx/5xx)
+ *   - "Could not reach"         — network error (DNS, refused connection, timeout)
+ *
+ * Tests assert on these substrings.
+ */
+export async function performLogin(opts) {
+    const apiUrl = opts.apiUrl?.trim() ?? "";
+    const teamApiKey = opts.teamApiKey?.trim() ?? "";
+    if (!apiUrl) {
+        throw new Error("API URL is required");
+    }
+    if (!validateTeamApiKey(teamApiKey)) {
+        throw new Error(`Invalid API key prefix: token must start with "${TEAM_API_KEY_PREFIX}"`);
+    }
+    const client = new AexolMcpClient(apiUrl, teamApiKey);
+    let toolCount;
+    try {
+        const tools = await client.listTools();
+        toolCount = tools.length;
+    }
+    catch (err) {
+        if (err instanceof AexolMcpError) {
+            if (err.status === 401 || err.status === 403) {
+                throw new Error(`Invalid token: Authentication failed (HTTP ${err.status}). Check that the key is correct and active.`);
+            }
+            if (err.status !== undefined) {
+                throw new Error(`Authentication failed: ${err.message}`);
+            }
+            throw new Error(`Could not reach ${apiUrl}: ${err.message}`);
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not reach ${apiUrl}: ${msg}`);
+    }
+    const cfg = { apiUrl, teamApiKey };
+    await writeConfig(cfg);
+    return { toolCount };
+}
+export async function runLogin() {
+    process.stdout.write(pc.bold("Spectral login\n"));
+    process.stdout.write(pc.dim("Authenticate against the Aexol MCP backend. Credentials are stored at ~/.spectral/config.json (chmod 600).\n\n"));
+    const defaultUrl = process.env.SPECTRAL_MCP_URL ?? DEFAULT_API_URL;
+    let apiUrl;
+    let teamApiKey;
+    try {
+        apiUrl = (await input({
+            message: "Aexol MCP URL",
+            default: defaultUrl,
+            validate: (v) => (v.trim().length > 0 ? true : "URL is required"),
+        })).trim();
+        teamApiKey = (await password({
+            message: `Team API key (starts with "${TEAM_API_KEY_PREFIX}")`,
+            mask: "*",
+            validate: (v) => {
+                const trimmed = v.trim();
+                if (trimmed.length === 0)
+                    return "Token is required";
+                if (!validateTeamApiKey(trimmed)) {
+                    return `Token must start with "${TEAM_API_KEY_PREFIX}"`;
+                }
+                return true;
+            },
+        })).trim();
+    }
+    catch (err) {
+        // @inquirer/prompts throws ExitPromptError on Ctrl+C; treat as cancellation.
+        const name = err?.name;
+        if (name === "ExitPromptError") {
+            process.stderr.write(pc.yellow("\nLogin cancelled.\n"));
+            process.exit(130);
+        }
+        throw err;
+    }
+    process.stdout.write(pc.dim(`\nVerifying credentials against ${apiUrl} ...\n`));
+    let result;
+    try {
+        result = await performLogin({ apiUrl, teamApiKey });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(pc.red(`✗ ${msg}\n`));
+        process.exit(1);
+    }
+    process.stdout.write(pc.green(`✓ Authenticated. Found ${result.toolCount} tools.\n`));
+    process.stdout.write(pc.dim(`Saved credentials to ${getConfigFile()}\n`));
+}

package/dist/commands/logout.js

@@ -0,0 +1,24 @@
+/**
+ * `spectral logout` — remove the persisted Aexol credentials.
+ *
+ * Idempotent: missing config is not an error. Always exits 0 unless the
+ * filesystem itself misbehaves (in which case we surface the OS error).
+ */
+import pc from "picocolors";
+import { CONFIG_FILE, deleteConfig } from "../config.js";
+export async function runLogout() {
+    try {
+        const removed = await deleteConfig();
+        if (removed) {
+            process.stdout.write(pc.green(`✓ Logged out. Removed ${CONFIG_FILE}\n`));
+        }
+        else {
+            process.stdout.write(pc.dim("Already logged out.\n"));
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(pc.red(`✗ Failed to remove ${CONFIG_FILE}: ${msg}\n`));
+        process.exit(1);
+    }
+}

package/dist/commands/serve.js

@@ -0,0 +1,374 @@
+/**
+ * `spectral serve` — relay orchestration entry point.
+ *
+ * Architecture (post-Batch 2 cutover):
+ *  1. Pre-flight: `requireLogin()` — same UX as the main spawn path.
+ *  2. Pre-flight: `preflightSqlite()` — fail fast on a broken native module.
+ *  3. Open the SQLite store and construct a `SessionStreamManager`.
+ *  4. Register this machine with the backend (`ensureMachineRegistered`),
+ *     which either reuses a fresh `machine.json` or POSTs to
+ *     `/api/machines/register` and persists the issued JWT.
+ *  5. Open a single long-lived `RelayClient` to `/agent-connection` carrying
+ *     the machine JWT. Reconnects forever with backoff.
+ *  6. Until Batch 3 ships, every inbound non-pong frame is acked back as
+ *     `{kind:"ack", echo:<frame>}`. This proves the WS is bidirectional
+ *     end-to-end and gives operators a smoke check before envelope routing.
+ *  7. SIGINT/SIGTERM trigger graceful shutdown: dispose the relay (close 1000),
+ *     dispose the manager (tear down pi streams), close the store.
+ *
+ * What this module is NOT (yet):
+ *  - It does NOT translate relay envelopes into REST handler calls or WS
+ *    event broadcasts. That dispatcher is Batch 3.
+ *  - It does NOT bind any local port. The local HTTP server is gone.
+ *
+ * Flag surface:
+ *  - `--machine-name <name>` — display name used at registration time.
+ *  - `--port <n>` / `-p <n>` / `SPECTRAL_PORT` — accepted but warned-and-ignored
+ *    so users updating from the pre-relay version don't get a hard error.
+ *
+ * The exported `runServe()` returns a handle so tests can drive the relay
+ * loop in-process without spawning a subprocess. Tests inject
+ * `relayUrlOverride` + `fetchImpl` + `webSocketImpl` to point at an
+ * in-process fake backend.
+ */
+import { readFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getConfigDir } from "../config.js";
+import { requireLogin } from "../preflight.js";
+import { RelayClient } from "../relay/client.js";
+import { detachAllSubscribers, handleClientMessage, handleRestRequest, handleSubscribe, } from "../relay/dispatcher.js";
+import { ensureMachineRegistered } from "../relay/registration.js";
+import { SessionStreamManager } from "../server/session-stream.js";
+import { gracefulShutdown } from "../server/shutdown.js";
+import { preflightSqlite, SessionStore } from "../server/storage.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Default backend base URL when neither env nor override is set. */
+const DEFAULT_BACKEND_URL = "http://localhost:4008";
+function readPackageVersion() {
+    // dist/commands/serve.js  →  ../../package.json
+    // src/commands/serve.ts → ../../package.json (tsx / vitest)
+    const pkgPath = resolve(__dirname, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return pkg.version;
+}
+/**
+ * Translate a backend HTTP(S) base URL to the relay WS(S) URL.
+ * `http://x:y` → `ws://x:y/agent-connection`
+ * `https://x` → `wss://x/agent-connection`
+ */
+export function deriveRelayUrl(backendUrl) {
+    const trimmed = backendUrl.replace(/\/$/, "");
+    if (trimmed.startsWith("https://")) {
+        return `wss://${trimmed.slice("https://".length)}/agent-connection`;
+    }
+    if (trimmed.startsWith("http://")) {
+        return `ws://${trimmed.slice("http://".length)}/agent-connection`;
+    }
+    // Already a ws[s] URL — assume the caller knows what they're doing.
+    if (trimmed.startsWith("ws://") || trimmed.startsWith("wss://")) {
+        return trimmed.endsWith("/agent-connection") ? trimmed : `${trimmed}/agent-connection`;
+    }
+    throw new Error(`Cannot derive relay URL from "${backendUrl}"`);
+}
+/**
+ * Parse the `serve` subcommand's flag surface. Manual parser, same style as
+ * `login`/`logout` (no CLI framework).
+ *
+ * Accepted:
+ *   --machine-name <name>
+ *   --machine-name=<name>
+ * Deprecated (warn, don't error):
+ *   --port <n>  /  -p <n>  /  --port=<n>
+ *
+ * Anything else throws so users notice typos.
+ */
+export function parseServeArgs(args) {
+    const out = { deprecatedPort: false };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--machine-name") {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error(`--machine-name requires a value`);
+            out.machineName = next;
+            i++;
+            continue;
+        }
+        if (a.startsWith("--machine-name=")) {
+            out.machineName = a.slice("--machine-name=".length);
+            continue;
+        }
+        // Deprecated port flag — warn-and-ignore so existing scripts don't crash.
+        if (a === "--port" || a === "-p") {
+            out.deprecatedPort = true;
+            // Swallow the value if present so we don't trip the unknown-arg branch.
+            if (args[i + 1] && !args[i + 1].startsWith("-"))
+                i++;
+            continue;
+        }
+        if (a.startsWith("--port=")) {
+            out.deprecatedPort = true;
+            continue;
+        }
+        throw new Error(`Unknown argument to "serve": ${a}`);
+    }
+    return out;
+}
+export async function runServe(opts = {}) {
+    const cfg = await requireLogin();
+    const cwd = opts.cwd ?? homedir();
+    const version = readPackageVersion();
+    const installSignalHandlers = opts.installSignalHandlers ?? true;
+    const silent = opts.silent ?? false;
+    const dbPath = opts.dbPath ?? join(getConfigDir(), "sessions.db");
+    // Pre-flight: native sqlite. Fail fast with a friendly hint BEFORE we
+    // start opening sockets — keeps the error close to the cause.
+    const preflight = preflightSqlite(dbPath);
+    if (!preflight.ok) {
+        process.stderr.write(`✗ ${preflight.error}\n`);
+        process.exit(1);
+    }
+    const store = new SessionStore(dbPath);
+    // Mutable holder for the meta-event publisher. Bound below once we
+    // have both `relay` (the send target) and `registration.record.machineId`
+    // (the canonical machineId the backend uses to fan out). The manager
+    // and dispatcher both close over a thin wrapper that defers to this
+    // ref, so a race where the title pipeline fires before the relay is
+    // up just no-ops (the deferred lookup sees `undefined`) instead of
+    // throwing or losing the rename.
+    let publishMetaEventRef;
+    const deferredPublishMetaEvent = (event) => {
+        publishMetaEventRef?.(event);
+    };
+    // Resolve URLs. Precedence: explicit option > env > default.
+    const backendUrl = opts.backendUrlOverride ?? process.env.SPECTRAL_BACKEND_URL ?? DEFAULT_BACKEND_URL;
+    const relayUrl = opts.relayUrlOverride ?? process.env.SPECTRAL_RELAY_URL ?? deriveRelayUrl(backendUrl);
+    // Register BEFORE constructing the SessionStreamManager. The manager
+    // (and every PiBridge it spawns) needs the machine JWT to authenticate
+    // backend-proxied inference calls, so registration must succeed first.
+    // Fail-fast on error — a clear message beats a hang.
+    let registration;
+    try {
+        registration = await ensureMachineRegistered({
+            backendUrl,
+            apiKey: cfg.teamApiKey,
+            machineNameOverride: opts.machineName,
+            version,
+            fetchImpl: opts.fetchImpl,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`✗ Could not register machine: ${msg}\n`);
+        // Tear down what we've already opened so tests don't see leaks.
+        try {
+            store.close();
+        }
+        catch {
+            // ignore
+        }
+        process.exit(1);
+    }
+    // Stream manager owns per-session pi processes. Batch 3 will subscribe
+    // it to relay frames; for now it's just here so the handles match the
+    // shape Batch 3 expects.
+    const manager = new SessionStreamManager({
+        store,
+        cwd,
+        backendUrl,
+        machineJwt: registration.record.machineJwt,
+        bridgeFactory: opts.bridgeFactory,
+        titleLlmCall: opts.titleLlmCall,
+        disableAutoTitle: opts.disableAutoTitle,
+        publishMetaEvent: deferredPublishMetaEvent,
+    });
+    if (!silent) {
+        const action = registration.reused ? "Reusing" : "Registered";
+        process.stdout.write(`${action} machine "${registration.record.machineName}" (${registration.record.machineId})\n`);
+        process.stdout.write(`Connecting to relay: ${relayUrl} (cwd: ${cwd}, host: ${hostname()})\n`);
+    }
+    const relay = new RelayClient({
+        relayUrl,
+        machineJwt: registration.record.machineJwt,
+        webSocketImpl: opts.webSocketImpl,
+        logger: silent ? { log: () => { }, warn: () => { }, error: () => { } } : console,
+    });
+    // Wire the meta publisher now that we have both the relay socket and
+    // the canonical machineId. The backend ignores the body's machineId
+    // field on `meta_event` (it stamps it from the connection identity),
+    // but we still send the right value for local debuggability and to
+    // avoid relying on backend behaviour that may evolve.
+    publishMetaEventRef = (event) => {
+        relay.send({
+            kind: "meta_event",
+            machineId: registration.record.machineId,
+            event,
+        });
+    };
+    // Per-session subscriber registry. The dispatcher attaches at most
+    // one subscriber per (sessionId) on the first `client_message`; we
+    // hand the same map back to it for every subsequent frame so attach
+    // is idempotent. On relay disconnect we detach all of them so the
+    // manager doesn't keep an unreachable subscriber pinned, but we
+    // KEEP the underlying streams alive — a browser reconnect should
+    // resume mid-turn.
+    const subscribers = new Map();
+    // Envelope dispatcher. We only act on `rest_request` and
+    // `client_message`; everything else (welcome, pong, error, etc.) is
+    // either handled by RelayClient itself or is informational.
+    //
+    // Frames arrive typed loosely from `RelayClient` (which is protocol-
+    // agnostic — it just forwards JSON). We re-narrow via the `kind`
+    // discriminator and cast to the strict envelope types from
+    // `@aexol/relay-protocol`. The protocol package's own `parseFrame()`
+    // already validated `kind` membership in RelayClient itself; here we
+    // additionally trust that the inner shape matches its discriminator
+    // (the backend is the only producer and is exercised by tests).
+    relay.on("frame", (frame) => {
+        if (frame.kind === "rest_request") {
+            const response = handleRestRequest(frame, {
+                store,
+                manager,
+                publishMetaEvent: deferredPublishMetaEvent,
+            });
+            relay.send(response);
+            return;
+        }
+        if (frame.kind === "client_message") {
+            handleClientMessage(frame, {
+                manager,
+                relay,
+                subscribers,
+            });
+            return;
+        }
+        if (frame.kind === "subscribe") {
+            handleSubscribe(frame, {
+                manager,
+                relay,
+                subscribers,
+            });
+            return;
+        }
+        // Other frames (error, machine_disconnected addressed to us, etc.)
+        // are ignored at this layer. Future batches may surface them in
+        // structured logs.
+    });
+    // On every relay close, drop the subscriber registry. The manager
+    // keeps streams alive (so `dispose` is the only place that tears
+    // them down), but the previous subscribers are pointing at a stale
+    // socket — let the next `client_message` attach a fresh one.
+    relay.on("close", () => {
+        detachAllSubscribers(manager, subscribers);
+    });
+    if (!silent) {
+        relay.on("welcome", () => process.stdout.write("✓ Relay connected\n"));
+        relay.on("close", ({ code, reason }) => {
+            process.stdout.write(`Relay closed (${code}${reason ? `: ${reason}` : ""}); will reconnect…\n`);
+        });
+        relay.on("reconnect-scheduled", ({ delayMs, attempt }) => {
+            process.stdout.write(`Reconnect attempt ${attempt} in ${delayMs}ms\n`);
+        });
+        relay.on("error", (err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`Relay error: ${msg}\n`);
+        });
+    }
+    relay.connect();
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        relay.dispose();
+        manager.dispose();
+        try {
+            store.close();
+        }
+        catch {
+            // ignore — best-effort
+        }
+        if (!silent)
+            process.stdout.write("Spectral relay stopped\n");
+    };
+    if (installSignalHandlers) {
+        // Top-level error nets. A daemon must NOT die from a transient
+        // unhandled rejection (e.g. a fetch promise that lost its `.catch`
+        // when the relay flapped) or a stray throw from a third-party
+        // library. Log loudly so we notice in operator logs, but keep the
+        // process alive — the relay client owns its own reconnect loop and
+        // the manager owns its own per-session error handling.
+        process.on("unhandledRejection", (reason) => {
+            const msg = reason instanceof Error
+                ? `${reason.message}\n${reason.stack ?? ""}`
+                : String(reason);
+            try {
+                process.stderr.write(`[serve] unhandledRejection (kept alive): ${msg}\n`);
+            }
+            catch {
+                // ignore — best-effort
+            }
+        });
+        process.on("uncaughtException", (err) => {
+            try {
+                process.stderr.write(`[serve] uncaughtException (kept alive): ${err.message}\n${err.stack ?? ""}\n`);
+            }
+            catch {
+                // ignore — best-effort
+            }
+        });
+        // Two-stage signal handling. The first SIGINT/SIGTERM kicks off the
+        // graceful sequence (flag the dispatcher, drain in-flight turns up
+        // to 5 s, close relay→manager→store, exit 0). A second signal during
+        // the grace window forces an immediate exit(1) — operators must always
+        // be able to kill the process with Ctrl-C twice.
+        //
+        // We use `on` (not `once`) so the second signal hits `gracefulShutdown`
+        // again, where the entry-counter handles the force path.
+        const onSignal = (_sig) => {
+            void gracefulShutdown({
+                inFlightCount: () => manager.activeTurnCount(),
+                closeRelay: () => {
+                    // Mirror our own `close()`: dispose the relay (sends close 1000).
+                    // We don't await here because RelayClient.dispose is sync and
+                    // the shutdown helper expects a void|Promise return.
+                    relay.dispose();
+                },
+                disposeManager: () => {
+                    manager.dispose();
+                },
+                closeStore: () => {
+                    store.close();
+                },
+                logger: silent
+                    ? { log: () => { }, warn: () => { }, error: () => { } }
+                    : console,
+            });
+        };
+        process.on("SIGINT", onSignal);
+        process.on("SIGTERM", onSignal);
+    }
+    return {
+        store,
+        manager,
+        relay,
+        machineId: registration.record.machineId,
+        close,
+    };
+}
+/**
+ * CLI entry point used by `cli.ts`. Surfaces the deprecation warning for
+ * `--port`/`SPECTRAL_PORT` once, then defers to `runServe`.
+ */
+export async function runServeCli(rawArgs) {
+    const parsed = parseServeArgs(rawArgs);
+    if (parsed.deprecatedPort || process.env.SPECTRAL_PORT) {
+        process.stderr.write(`warning: --port / SPECTRAL_PORT are no longer used. ` +
+            `spectral serve now connects outbound to the Aexol relay; there is no local port to bind.\n`);
+    }
+    return runServe({
+        machineName: parsed.machineName,
+    });
+}

package/dist/commands/unbind.js

@@ -0,0 +1,36 @@
+/**
+ * `spectral unbind` — remove the local Studio project binding.
+ *
+ * Reads `.aexol/aexol.jsonc`, reports what project was unbound, and deletes
+ * the file. Idempotent: missing binding is not an error.
+ */
+import pc from "picocolors";
+import { deleteStudioBinding, readStudioBinding, } from "../studio-binding.js";
+export async function runUnbind() {
+    // ---- Read existing -------------------------------------------------------
+    let existing;
+    try {
+        existing = await readStudioBinding();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(pc.red(`Failed to read binding: ${msg}\n`));
+        process.exit(1);
+    }
+    if (!existing) {
+        process.stdout.write(pc.dim("No Studio binding found in this directory.\n"));
+        return;
+    }
+    const displayName = existing.name ?? existing.projectId;
+    process.stderr.write(`Unbinding from project: ${existing.name ?? "(unnamed)"} (${existing.projectId})\n`);
+    // ---- Delete --------------------------------------------------------------
+    try {
+        await deleteStudioBinding();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(pc.red(`Failed to remove binding: ${msg}\n`));
+        process.exit(1);
+    }
+    process.stdout.write(pc.green(`✓ Unbound.\n`));
+}

package/dist/config.js

@@ -0,0 +1,92 @@
+/**
+ * Spectral configuration: persisted Aexol MCP credentials.
+ *
+ * Stored at ~/.spectral/config.json with mode 0600 (user read/write only).
+ * The directory is created with mode 0700.
+ *
+ * Keep this module zero-side-effect so it can be imported from both the
+ * CLI entry (pre-flight check) and the pi extension.
+ *
+ * `getConfigDir()` honors `SPECTRAL_CONFIG_DIR` so tests can redirect to a
+ * temporary directory without touching the real `~/.spectral`.
+ */
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const DEFAULT_API_URL = "https://api.aexol.ai/mcp";
+export const TEAM_API_KEY_PREFIX = "sk-aexol-team-";
+/**
+ * Resolve the directory used to store Spectral configuration.
+ *
+ * Honors `SPECTRAL_CONFIG_DIR` first (used by tests and CI), then falls back
+ * to `<HOMEDIR>/.spectral`. Computed lazily on every call so test-time env
+ * mutation works without re-importing the module.
+ */
+export function getConfigDir() {
+    return process.env.SPECTRAL_CONFIG_DIR ?? join(homedir(), ".spectral");
+}
+/** Path to the config JSON file. Computed lazily — see `getConfigDir`. */
+export function getConfigFile() {
+    return join(getConfigDir(), "config.json");
+}
+/**
+ * Backwards-compatible aliases for code that imported the old top-level
+ * constants. They eagerly resolve at import time, so they reflect the env
+ * state at startup. New code should call `getConfigDir()` / `getConfigFile()`
+ * directly so test-time env overrides take effect.
+ */
+export const CONFIG_DIR = getConfigDir();
+export const CONFIG_FILE = getConfigFile();
+/** Resolve the effective API URL: env wins, then stored value, then default. */
+export function getApiUrl(stored) {
+    return process.env.SPECTRAL_MCP_URL ?? stored ?? DEFAULT_API_URL;
+}
+/** Validate the team API key prefix. The full token check happens server-side. */
+export function validateTeamApiKey(key) {
+    return typeof key === "string" && key.startsWith(TEAM_API_KEY_PREFIX);
+}
+/** Read config; returns null if missing or malformed. Never throws. */
+export async function readConfig() {
+    let raw;
+    try {
+        raw = await readFile(getConfigFile(), "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.apiUrl === "string" &&
+            typeof parsed.teamApiKey === "string" &&
+            parsed.teamApiKey.length > 0) {
+            return { apiUrl: parsed.apiUrl, teamApiKey: parsed.teamApiKey };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist config with restrictive permissions (dir 0700, file 0600). */
+export async function writeConfig(cfg) {
+    const file = getConfigFile();
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    // Write atomically-ish: tsc target is Node 20 which has fs.writeFile mode option.
+    await writeFile(file, JSON.stringify(cfg, null, 2) + "\n", {
+        mode: 0o600,
+        encoding: "utf8",
+    });
+}
+/** Delete config; returns true if a file was removed, false if there was nothing to remove. */
+export async function deleteConfig() {
+    try {
+        await rm(getConfigFile(), { force: false });
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return false;
+        throw err;
+    }
+}