@m6d/cortex-cli 0.12.1 → 0.13.0

package/src/contracts/egress/index.ts

@@ -1,120 +0,0 @@
-import { lookup } from "node:dns/promises";
-import type { LookupFunction } from "node:net";
-import { Agent } from "undici";
-import { isEgressAllowedHost, isPrivateAddress, normalizeHost } from "./url";
-
-/*
- * The outbound network policy for URLs a tenant controls (tool endpoints,
- * per-agent JWKS URIs): private, loopback, link-local, and metadata ranges are
- * refused, and DNS is pinned so a rebind cannot slip a private address past
- * the check, and credentials an answer echoes back are redacted from it.
- * Shared by cc and the server, vendored like the rest of this package.
- */
-
-export { credentialForms, scrubCredentialStrings } from "./scrub";
-
-/**
- * Whether a host may be dialed at these addresses: any address when the
- * policy admits the host (`EGRESS_ALLOWED_HOSTS`), else only public ones.
- */
-function isDialable(hostname: string, addresses: string[]) {
-    return isEgressAllowedHost(hostname) || !addresses.some(isPrivateAddress);
-}
-
-export { canCarrySecret, egressAllowedHosts } from "./url";
-
-export function egressError() {
-    const error: NodeJS.ErrnoException = new Error("egress blocked");
-    error.code = "EGRESS_BLOCKED";
-    return error;
-}
-
-/** True when `error` or any of its causes is the egress refusal. */
-export function isEgressError(error: unknown) {
-    for (let current = error; current instanceof Error; current = current.cause) {
-        if ((current as NodeJS.ErrnoException).code === "EGRESS_BLOCKED") return true;
-    }
-    return false;
-}
-
-/**
- * Re-resolves the hostname and re-validates every candidate on every connection
- * attempt, handing the socket only vetted public addresses. The address dialed
- * is the exact one just checked, so a nameserver cannot return a public IP to
- * the check and a private one to the connect. Server name / Host header stay
- * the original hostname.
- */
-const pinnedLookup: LookupFunction = (hostname, options, callback) => {
-    lookup(hostname, { all: true, verbatim: true }).then(
-        (addresses) => {
-            const first = addresses[0];
-            if (
-                !first ||
-                !isDialable(
-                    hostname,
-                    addresses.map((address) => address.address),
-                )
-            ) {
-                callback(egressError(), "", 0);
-                return;
-            }
-            if (options.all) {
-                callback(
-                    null,
-                    addresses.map((address) => ({
-                        address: address.address,
-                        family: address.family,
-                    })),
-                );
-                return;
-            }
-            callback(null, first.address, first.family);
-        },
-        (error: unknown) =>
-            callback(error instanceof Error ? error : new Error("lookup failed"), "", 0),
-    );
-};
-
-/**
- * Checks a URL before any socket opens: http(s) only, no embedded credentials,
- * an optional per-call restriction to `allowedHostnames`, and the host dialable
- * (every resolved address public, or the host admitted by the policy). Returns
- * the bare hostname on success. `pinnedLookup` re-checks at connect time; this
- * is the cheap, clean refusal for a statically bad target.
- */
-export async function checkEgressTarget(target: URL, allowedHostnames?: string[]) {
-    // Resolved as written, root dot included, so an absolute name is never search-suffixed; normalized only to compare.
-    const hostname = target.hostname.replace(/^\[(.*)]$/, "$1");
-
-    if (!["http:", "https:"].includes(target.protocol) || target.username || target.password) {
-        return false;
-    }
-    if (
-        allowedHostnames &&
-        !allowedHostnames.map(normalizeHost).includes(normalizeHost(hostname))
-    ) {
-        return false;
-    }
-
-    const preflight = await lookup(hostname, { all: true, verbatim: true });
-    return (
-        preflight.length > 0 &&
-        isDialable(
-            hostname,
-            preflight.map((address) => address.address),
-        )
-    );
-}
-
-/**
- * An undici dispatcher whose every connection resolves through `pinnedLookup`.
- * Call the returned `release` once the response has been read; Bun's undici
- * Agent may lack `close`, so release tolerates its absence.
- */
-export function guardedDispatcher() {
-    const dispatcher = new Agent({ connect: { lookup: pinnedLookup } });
-    const release = () => {
-        if (typeof dispatcher.close === "function") void dispatcher.close().catch(() => undefined);
-    };
-    return { dispatcher, release };
-}

package/src/contracts/graph/clients/embed.ts

@@ -1,62 +0,0 @@
-/**
- * Embeddings, which both halves of the graph need: `@m6d/cortex-cli` embeds every
- * concept description as it seeds, `@m6d/cortex-server` embeds every prompt as it
- * resolves. Two embedders would mean two vector spaces, so there is one. A bare
- * `fetch` to the OpenAI-compatible `/embeddings` call keeps this package
- * dependency-free. Everything under `graph/` compiles into an Angular library
- * too, so it is written to the oldest target any consumer builds against.
- */
-
-/** Everything cortex needs to reach one OpenAI-compatible embeddings endpoint. */
-export type EmbeddingProviderConfig = {
-    baseURL: string;
-    apiKey: string;
-    modelName: string;
-};
-
-/** Turns a batch of strings into their vectors, in the order given. */
-export type EmbedFn = (values: string[]) => Promise<number[][]>;
-
-/**
- * The most inputs one embeddings request carries. Text Embeddings Inference
- * refuses more than 32 by default; providers that allow larger batches just
- * take more requests.
- */
-export const EMBEDDING_MAX_BATCH_SIZE = 32;
-
-export function createEmbedder(config: EmbeddingProviderConfig) {
-    const url = `${config.baseURL.replace(/\/+$/, "")}/embeddings`;
-
-    async function embedBatch(values: string[]) {
-        const response = await fetch(url, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${config.apiKey}`,
-            },
-            body: JSON.stringify({ model: config.modelName, input: values }),
-        });
-
-        if (!response.ok) {
-            throw new Error(
-                `Embedding request failed (${response.status}): ${await response.text()}`,
-            );
-        }
-
-        // The API is free to return entries out of order; `index` is authoritative.
-        const body = (await response.json()) as { data: { index: number; embedding: number[] }[] };
-        return [...body.data]
-            .sort((left, right) => left.index - right.index)
-            .map((entry) => entry.embedding);
-    }
-
-    return async function embed(values: string[]) {
-        const embeddings: number[][] = [];
-        for (let index = 0; index < values.length; index += EMBEDDING_MAX_BATCH_SIZE) {
-            embeddings.push(
-                ...(await embedBatch(values.slice(index, index + EMBEDDING_MAX_BATCH_SIZE))),
-            );
-        }
-        return embeddings;
-    };
-}

package/src/contracts/graph/clients/neo4j.ts

@@ -1,85 +0,0 @@
-/**
- * Neo4j over its HTTP transaction endpoint, shared by the graph's writer (the
- * CLI seeder) and its reader (the server resolver). Configuration is explicit
- * and the transport is `fetch`, so this package stays dependency-free.
- */
-
-import type { EmbedFn } from "./embed";
-
-export type Neo4jConfig = {
-    url: string;
-    user: string;
-    password: string;
-};
-
-export type Neo4jRow = Record<string, unknown>;
-
-export type Neo4jClient = {
-    /** Runs one statement and returns its rows as column-keyed objects. Throws `Neo4jQueryError` on any failure. */
-    query(cypher: string, parameters?: Record<string, unknown>): Promise<Neo4jRow[]>;
-};
-
-export class Neo4jQueryError extends Error {
-    public constructor(
-        message: string,
-        /** Neo4j's error code (`Neo.ClientError.…`), or the HTTP status when the request itself failed. */
-        public readonly code: string,
-    ) {
-        super(message);
-        this.name = "Neo4jQueryError";
-    }
-}
-
-/**
- * Parameters whose key starts with `#` are embedded before the statement runs:
- * `{ "#embedding": "text" }` becomes `{ embedding: number[] }`.
- */
-export function createNeo4jClient(config: Neo4jConfig, embed?: EmbedFn) {
-    async function query(cypher: string, parameters: Record<string, unknown> = {}) {
-        const embeddedKeys = Object.keys(parameters).filter((key) => key.startsWith("#"));
-        if (embeddedKeys.length) {
-            if (!embed) throw new Error("An embedder is required when using # parameters");
-            const embeddings = await embed(embeddedKeys.map((key) => parameters[key] as string));
-            embeddedKeys.forEach((key, index) => {
-                delete parameters[key];
-                parameters[key.slice(1)] = embeddings[index]!;
-            });
-        }
-
-        const response = await fetch(`${config.url}/db/neo4j/tx/commit`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Basic ${btoa(`${config.user}:${config.password}`)}`,
-            },
-            body: JSON.stringify({ statements: [{ statement: cypher, parameters }] }),
-        });
-        if (!response.ok) {
-            throw new Neo4jQueryError(
-                `Neo4j request failed with status ${response.status}`,
-                String(response.status),
-            );
-        }
-
-        const result = (await response.json()) as {
-            errors?: { code?: string; message: string }[];
-            results: { columns: string[]; data: { row: unknown[] }[] }[];
-        };
-        if (result.errors?.length) {
-            throw new Neo4jQueryError(
-                result.errors.map((error) => error.message).join("; "),
-                result.errors[0]!.code ?? "unknown",
-            );
-        }
-
-        const queryResult = result.results[0];
-        if (!queryResult) return [];
-        return queryResult.data.map((entry) =>
-            Object.fromEntries(
-                queryResult.columns.map((column, index) => [column, entry.row[index]]),
-            ),
-        );
-    }
-
-    return { query } satisfies Neo4jClient;
-}

package/src/contracts/graph/helpers.ts

@@ -1,55 +0,0 @@
-/**
- * Helper functions for building knowledge graph seed data. Projects author
- * domains with these; `@m6d/cortex-server` re-exports them so authoring needs
- * exactly one import path.
- */
-
-import type {
-    ConceptDef,
-    DomainDef,
-    EndpointDef,
-    EndpointInput,
-    RuleDef,
-    ServiceDef,
-} from "./types";
-
-export function defineConcept(def: Omit<ConceptDef, "__brand">) {
-    return { __brand: "concept" as const, ...def };
-}
-
-export function defineRule(def: Omit<RuleDef, "__brand">) {
-    return { __brand: "rule" as const, ...def };
-}
-
-export function defineService(def: Omit<ServiceDef, "__brand">) {
-    return { __brand: "service" as const, ...def };
-}
-
-export function defineDomain(def: Omit<DomainDef, "__brand">) {
-    return { __brand: "domain" as const, ...def };
-}
-
-export function defineEndpoint(input: EndpointInput) {
-    const generated = input.autoGenerated;
-
-    return {
-        __brand: "endpoint" as const,
-        name: input.name,
-        description: input.description ?? input.name,
-        path: input.path,
-        method: input.method,
-        propertiesDescriptions: input.propertiesDescriptions ?? {},
-        params: generated ? [...generated.params] : [],
-        body: generated ? [...generated.body] : [],
-        response: generated ? [...generated.response] : [],
-        successStatus: generated?.successStatus ?? 200,
-        errorStatuses: generated ? [...generated.errorStatuses] : [],
-        responseKind: generated?.responseKind ?? "object",
-        queries: input.queries,
-        mutates: input.mutates,
-        returns: input.returns,
-        dependsOn: input.dependsOn,
-        governedBy: input.governedBy,
-        metadata: input.metadata,
-    } satisfies EndpointDef;
-}

package/src/contracts/graph/index.ts

@@ -1,30 +0,0 @@
-/**
- * The graph contract — the knowledge-graph vocabulary, authoring types and
- * clients that `@m6d/cortex-cli` writes with and `@m6d/cortex-server` reads
- * with. `@m6d/cortex-server` re-exports all of it, so a project authoring
- * domains still has exactly one import path.
- */
-
-export type { GraphSchema } from "./schema";
-export { GRAPH_SCHEMA, GRAPH_SCHEMA_VERSION } from "./schema";
-
-export type {
-    EndpointScalarType,
-    EndpointProperty,
-    ResponseKind,
-    AutoGenerated,
-    ConceptDef,
-    EndpointDef,
-    EndpointInput,
-    ServiceDef,
-    RuleDef,
-    DomainDef,
-} from "./types";
-
-export { defineConcept, defineRule, defineService, defineDomain, defineEndpoint } from "./helpers";
-
-export type { Neo4jConfig, Neo4jClient, Neo4jRow } from "./clients/neo4j";
-export { createNeo4jClient, Neo4jQueryError } from "./clients/neo4j";
-
-export type { EmbedFn, EmbeddingProviderConfig } from "./clients/embed";
-export { createEmbedder, EMBEDDING_MAX_BATCH_SIZE } from "./clients/embed";

package/src/contracts/graph/schema.ts

@@ -1,65 +0,0 @@
-/**
- * The contract between the graph's writer and its reader.
- *
- * Seeding lives in `@m6d/cortex-cli` and resolution lives in `@m6d/cortex-server`,
- * two packages a project installs and upgrades separately. The labels, relationship
- * types, property names and index name they agree on are this module, here, so
- * neither side owns the vocabulary the other has to match.
- *
- * A mismatch between the two is invisible at runtime: the resolver's Cypher
- * matches nothing and retrieval comes back empty rather than failing. That is what
- * `GRAPH_SCHEMA_VERSION` is for — bump it on any change to the shape below. The
- * CLI stamps the version it wrote onto the graph and the server checks that stamp
- * on its first resolve, so skew surfaces as an error instead of as silence.
- */
-
-export const GRAPH_SCHEMA_VERSION = 1;
-
-export const GRAPH_SCHEMA = {
-    label: {
-        domain: "Domain",
-        concept: "Concept",
-        endpoint: "Endpoint",
-        service: "Service",
-        rule: "Rule",
-        /** Stamped with the version above, so a stale graph is detectable later. */
-        marker: "CortexGraph",
-    },
-    rel: {
-        belongsTo: "BELONGS_TO",
-        specializes: "SPECIALIZES",
-        queriedVia: "QUERIED_VIA",
-        mutatedVia: "MUTATED_VIA",
-        returns: "RETURNS",
-        dependsOn: "DEPENDS_ON",
-        governs: "GOVERNS",
-        requestedVia: "REQUESTED_VIA",
-    },
-    prop: {
-        name: "name",
-        description: "description",
-        aliases: "aliases",
-        metadata: "metadata",
-        path: "path",
-        method: "method",
-        params: "params",
-        body: "body",
-        response: "response",
-        propertiesDescriptions: "propertiesDescriptions",
-        successStatus: "successStatus",
-        errorStatuses: "errorStatuses",
-        builtInId: "builtInId",
-        embedding: "embedding",
-        /** On a RETURNS edge: which part of the response carries the concept. */
-        field: "field",
-        /** On a DEPENDS_ON edge. */
-        paramName: "paramName",
-        fromField: "fromField",
-        /** On the marker node. */
-        version: "version",
-    },
-    /** Created by the CLI's seeder, queried by name in the resolver's first hop. */
-    conceptEmbeddingsIndex: "concept_embeddings",
-} as const;
-
-export type GraphSchema = typeof GRAPH_SCHEMA;

package/src/contracts/graph/types.ts

@@ -1,125 +0,0 @@
-/**
- * Declarative types for knowledge graph seed data: endpoints carry
- * params/body/response property arrays, services are concept associations.
- */
-
-export type EndpointScalarType =
-    | "uuid"
-    | "number"
-    | "date"
-    | "datetime"
-    | "string"
-    | "boolean"
-    | "any"
-    | "object";
-
-export type EndpointProperty = {
-    readonly name: string;
-    readonly required: boolean;
-    // NonNullable<unknown> keeps the literal union visible to autocomplete.
-    readonly type: EndpointScalarType | (string & NonNullable<unknown>);
-    readonly isArray?: boolean;
-    readonly properties?: readonly EndpointProperty[];
-    readonly description?: string;
-};
-
-export type ResponseKind = "object" | "array" | "paginated" | "file" | "none";
-
-export type AutoGenerated = {
-    readonly params: readonly EndpointProperty[];
-    readonly body: readonly EndpointProperty[];
-    readonly response: readonly EndpointProperty[];
-    readonly successStatus: number;
-    readonly errorStatuses: readonly number[];
-    readonly responseKind?: ResponseKind;
-};
-
-export type ConceptDef = {
-    readonly __brand: "concept";
-    name: string;
-    description: string;
-    aliases?: string[];
-    parentConcept?: ConceptDef;
-    governedBy?: RuleDef[];
-    metadata?: Record<string, unknown>;
-};
-
-export type EndpointDef = {
-    readonly __brand: "endpoint";
-    name: string;
-    description: string;
-    path: string;
-    method: "GET" | "POST" | "PUT" | "DELETE";
-    propertiesDescriptions: Record<string, string>;
-
-    params: EndpointProperty[];
-    body: EndpointProperty[];
-    response: EndpointProperty[];
-    successStatus: number;
-    errorStatuses: number[];
-    responseKind: ResponseKind;
-
-    queries?: ConceptDef[];
-    mutates?: ConceptDef[];
-
-    returns?: { concept: ConceptDef; field?: string }[];
-    dependsOn?: {
-        endpoint: EndpointDef;
-        paramName: string;
-        fromField: string;
-    }[];
-
-    governedBy?: RuleDef[];
-    metadata?: Record<string, unknown>;
-};
-
-export type EndpointInput = {
-    name: string;
-    path: string;
-    method: "GET" | "POST" | "PUT" | "DELETE";
-    description?: string;
-    autoGenerated?: AutoGenerated;
-
-    propertiesDescriptions?: Record<string, string>;
-
-    queries?: ConceptDef[];
-    mutates?: ConceptDef[];
-
-    returns?: { concept: ConceptDef; field?: string }[];
-    dependsOn?: {
-        endpoint: EndpointDef;
-        paramName: string;
-        fromField: string;
-    }[];
-
-    governedBy?: RuleDef[];
-    metadata?: Record<string, unknown>;
-};
-
-export type ServiceDef = {
-    readonly __brand: "service";
-    name: string;
-    description: string;
-    builtInId: string;
-    belongsTo: ConceptDef;
-    governedBy?: RuleDef[];
-    metadata?: Record<string, unknown>;
-};
-
-export type RuleDef = {
-    readonly __brand: "rule";
-    name: string;
-    description: string;
-    metadata?: Record<string, unknown>;
-};
-
-export type DomainDef = {
-    readonly __brand: "domain";
-    name: string;
-    description: string;
-    concepts?: ConceptDef[];
-    endpoints?: EndpointDef[];
-    services?: ServiceDef[];
-    rules?: RuleDef[];
-    metadata?: Record<string, unknown>;
-};