Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

11.7 KB
Raw Blame
/**
 * Die /api-Routen des Servers, so weit dieses Chrome sie braucht.
 *
 * Zwei Wege fuehren zum Server und sie sind nicht dasselbe: `/rpc` traegt die
 * MCP-Werkzeuge (src/provider/rpc-client.ts), `/api` traegt die fertig
 * gerechneten Atlas-Antworten. Der Datei-Baum ist eine davon, und er kommt
 * ausdruecklich aus dem Graphen und nicht vom Dateisystem: was hier nicht
 * steht, hat der Index nicht gesehen.
 *
 * Same-origin ist der Normalfall. Der Server nimmt `/api` nur an, wenn der
 * Host-Kopf genau seine eigene Loopback-Adresse nennt und der Origin-Kopf
 * entweder fehlt oder dieselbe Adresse nennt. Ein
 * `base` ist darum nur fuer Node-Aufrufer da, die keinen Origin senden.
 */

import { hasErrorObservers, reportError } from '../provider/error-observer';
import { readConfigSnapshot, type ConfigSnapshot } from '../settings/config-model';
import { readTreeLevel } from './tree-model';
import type { TreeLevel } from './tree-model';
import {
    readFlowDetail,
    readFlowSummaries,
    readTraceAnswer,
} from '../traces/trace-schemas';
import type { FlowDetail, FlowSummary, TraceAnswer } from '../traces/trace-schemas';
import {
    readAdr,
    readBrowse,
    readHealth,
    readIndexJobs,
    readIndexStarted,
    readLogs,
    readProcesses,
    readUiLogTail,
} from '../projects/projects-model';
import type {
    AdrRecord,
    BrowseLevel,
    IndexJob,
    IndexStarted,
    LogTail,
    ProcessReport,
    ProjectHealth,
    UiLogTail,
} from '../projects/projects-model';

export interface AtlasApiOptions {
    /** Ursprung des Servers, ohne Schraegstrich am Ende. Leer heisst same-origin. */
    base?: string;
    /** Ersetzbares fetch, damit Tests ohne Netz laufen. */
    fetch?: typeof globalThis.fetch;
    /** Abbruchsignal fuer jeden Aufruf: das Projektfenster bricht so beim Wechsel ab (K24). */
    signal?: AbortSignal;
}

/** Was `/api/repo-info` ueber ein Projekt weiss. Leere Felder heissen "unbekannt". */
export interface RepoInfo {
    rootPath: string;
    branch: string;
    remoteUrl: string;
}

/** Ein Fehler einer /api-Route, mit dem Status, den sie geliefert hat. */
export class AtlasApiError extends Error {
    constructor(
        readonly route: string,
        readonly status: number,
        message: string,
    ) {
        super(message);
        this.name = 'AtlasApiError';
    }
}

function isRecord(value: unknown): value is Record<string, unknown> {
    return typeof value === 'object' && value !== null && !Array.isArray(value);
}

/**
 * Announce a failed /api call before it is thrown (provider/error-observer.ts),
 * so the frontend log holds it even though the panel catches it and shows a
 * sentence instead. A 4xx is the server saying no to this request (warn);
 * no answer, a 5xx or an unreadable body is a failure (error).
 */
function announce(error: AtlasApiError, detail?: string): AtlasApiError {
    if (hasErrorObservers()) {
        const refused = error.status >= 400 && error.status < 500;
        reportError({
            source: 'api',
            project: new URL(error.route, 'http://127.0.0.1').searchParams.get('project') ?? '',
            level: refused ? 'warn' : 'error',
            message: error.message,
            detail,
        });
    }
    return error;
}

const text = (value: unknown): string => (typeof value === 'string' ? value : '');

export class AtlasApi {

    constructor(private readonly options: AtlasApiOptions = {}) { }

    async configuration(): Promise<ConfigSnapshot> {
        return readConfigSnapshot(await this.getJson('/api/config'));
    }

    async saveConfiguration(revision: string, changes: Record<string, string | null>): Promise<ConfigSnapshot> {
        return readConfigSnapshot(await this.request('POST', '/api/config', { revision, changes }));
    }

    private getJson(route: string): Promise<unknown> {
        return this.request('GET', route);
    }

    /**
     * One request, any method. The writing routes of the projects panel
     * (POST /api/index, POST /api/adr, DELETE /api/project) go through here
     * with a JSON body; the error carries the status so a caller can tell
     * "busy, try later" (423) from "refused" (403) from "not there" (404).
     */
    private async request(method: 'GET' | 'POST' | 'DELETE', route: string, payload?: unknown): Promise<unknown> {
        const url = `${this.options.base ?? ''}${route}`;
        const doFetch = this.options.fetch ?? globalThis.fetch;
        let response: Response;
        try {
            const init: RequestInit = { method, headers: { Accept: 'application/json' } };
            if (payload !== undefined) {
                init.headers = { Accept: 'application/json', 'Content-Type': 'application/json' };
                init.body = JSON.stringify(payload);
            }
            if (this.options.signal !== undefined) init.signal = this.options.signal;
            response = await doFetch(url, init);
        } catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            const failure = new AtlasApiError(route, 0, `${route} war nicht erreichbar: ${message}`);
            // Ein abgebrochener Aufruf ist die Sache des Aufrufers und kein Fehler des Servers.
            if (this.options.signal?.aborted) throw failure;
            throw announce(failure);
        }
        const body = await response.text();
        if (!response.ok) {
            throw announce(
                new AtlasApiError(route, response.status, `${route} antwortete mit HTTP ${response.status}: ${body.slice(0, 200)}`),
                body.slice(0, 400),
            );
        }
        try {
            return JSON.parse(body) as unknown;
        } catch {
            throw announce(
                new AtlasApiError(route, response.status, `${route} lieferte kein JSON: ${body.slice(0, 200)}`),
                body.slice(0, 400),
            );
        }
    }

    /**
     * Eine Ebene des Datei-Baums. `path` leer heisst Projektwurzel.
     *
     * Der Server antwortet je Anfrage mit genau einer Ebene. Der Explorer
     * fragt darum je aufgeklapptem Ordner einmal nach, statt einen ganzen Baum
     * zu erwarten, den es auf dieser Route nicht gibt.
     */
    async tree(project: string, path = ''): Promise<TreeLevel> {
        const query = new URLSearchParams({ project });
        if (path.length > 0) {
            query.set('path', path);
        }
        return readTreeLevel(await this.getJson(`/api/tree?${query.toString()}`));
    }

    /**
     * Der kuerzeste Weg, den der Index von `from` nach `to` kennt, mit dem, was
     * davon beobachtet wurde.
     *
     * `mode` bleibt `calls`: `data` laeuft ueber DATA_FLOWS-Kanten, und die
     * schreibt die Analyse fuer TypeScript nicht. Die genaue Bedeutung jeder
     * Antwortform steht in src/traces/bug-paths.ts, wo sie gelesen wird.
     */
    async trace(project: string, from: string, to: string): Promise<TraceAnswer> {
        const query = new URLSearchParams({ project, from, to, mode: 'calls' });
        return readTraceAnswer(await this.getJson(`${TRACE_ROUTE}?${query.toString()}`));
    }

    /** Die gereihten Ablaeufe des Projekts, ohne ihre Schritte. */
    async flows(project: string): Promise<FlowSummary[]> {
        const query = new URLSearchParams({ project });
        return readFlowSummaries(await this.getJson(`${FLOWS_ROUTE}?${query.toString()}`));
    }

    /** Die Schritte eines Ablaufs, mit dem, was davon beobachtet wurde. */
    async flow(project: string, id: number): Promise<FlowDetail> {
        const query = new URLSearchParams({ project, id: String(id) });
        return readFlowDetail(await this.getJson(`${FLOW_ROUTE}?${query.toString()}`));
    }

    // ------------------------------------------------ the projects panel --

    /** The folders under `path`; the server's own roots when `path` is empty. */
    async browse(path = ''): Promise<BrowseLevel> {
        const query = new URLSearchParams();
        if (path.length > 0) {
            query.set('path', path);
        }
        const suffix = path.length > 0 ? `?${query.toString()}` : '';
        return readBrowse(await this.getJson(`/api/browse${suffix}`));
    }

    /** Ask the server to index `rootPath` under `projectName`, in the background. */
    async startIndex(rootPath: string, projectName: string): Promise<IndexStarted> {
        return readIndexStarted(
            await this.request('POST', '/api/index', { root_path: rootPath, project_name: projectName }),
        );
    }

    /** Every index job the server has run since it started, with its state. */
    async indexJobs(): Promise<IndexJob[]> {
        return readIndexJobs(await this.getJson('/api/index-status'));
    }

    /** Remove the index file of a project. The repository itself is not touched. */
    async deleteProject(name: string): Promise<void> {
        await this.request('DELETE', `/api/project?${new URLSearchParams({ name }).toString()}`);
    }

    /** Does the index file open, and what does it hold. */
    async projectHealth(name: string): Promise<ProjectHealth> {
        return readHealth(await this.getJson(`/api/project-health?${new URLSearchParams({ name }).toString()}`));
    }

    /** The decision record the server keeps for a project. */
    async adr(project: string): Promise<AdrRecord> {
        return readAdr(await this.getJson(`/api/adr?${new URLSearchParams({ project }).toString()}`));
    }

    /** Store the decision record of a project. */
    async saveAdr(project: string, content: string): Promise<void> {
        await this.request('POST', '/api/adr', { project, content });
    }

    /** The last `lines` lines of the server log. */
    async logs(lines: number, minLevel?: 'debug' | 'info' | 'warn' | 'error', project?: string, filters?: { scope?: 'unattributed'; query?: string }): Promise<LogTail> {
        const query = new URLSearchParams({ lines: String(lines) });
        if (minLevel) query.set('min_level', minLevel);
        if (project !== undefined) query.set('project', project);
        if (filters?.scope) query.set('scope', filters.scope);
        if (filters?.query?.trim()) query.set('q', filters.query.trim());
        return readLogs(await this.getJson(`/api/logs?${query.toString()}`));
    }

    /** The codebase-memory-mcp processes on this machine, as the server sees them. */
    async processes(): Promise<ProcessReport> {
        return readProcesses(await this.getJson('/api/processes'));
    }

    /**
     * The tail of the frontend's own log file on the server, the one this
     * page writes through POST /api/ui-log (app/ui-log.ts). The answer names
     * the file, so the panel can tell a reader what to attach to a report.
     */
    async uiLogTail(lines: number): Promise<UiLogTail> {
        return readUiLogTail(await this.getJson(`/api/ui-log?${new URLSearchParams({ lines: String(lines) }).toString()}`));
    }

    /** Wurzelpfad, Branch und Remote eines Projekts. Leere Felder bleiben leer. */
    async repoInfo(project: string): Promise<RepoInfo> {
        const raw = await this.getJson(`/api/repo-info?${new URLSearchParams({ project }).toString()}`);
        const record = isRecord(raw) ? raw : {};
        return {
            rootPath: text(record['root_path']),
            branch: text(record['branch']),
            remoteUrl: text(record['remote_url']),
        };
    }
}

/** Der Name der Route, aus der der Baum kommt. Der Beweislauf schreibt ihn mit. */
export const TREE_ROUTE = '/api/tree';

/**
 * Die drei Routen, ueber die Beobachtetes lesbar ist.
 *
 * Es gibt keine vierte: `observed_calls` wird ausschliesslich von
 * `cbm_atlas_attach_observed` an eine Trace- oder Flow-Antwort geheftet
 * (cbm/src/ui/http_server.c). Was das fuer den BUG-Assistenten bedeutet, steht
 * im Kopf von src/traces/bug-paths.ts.
 */
export const TRACE_ROUTE = '/api/trace';
export const FLOWS_ROUTE = '/api/flows';
export const FLOW_ROUTE = '/api/flow';