@m6d/cortex-cli 0.12.1 → 0.14.0

package/src/contracts/credentials/index.ts

@@ -1,183 +0,0 @@
-import { z } from "zod";
-import { canCarrySecret } from "../egress/url";
-
-export { canCarrySecret };
-
-/*
- * A credential is a value Cortex presents to an upstream: one it holds
- * (`static`) or one it acquires (`oauth2-client-credentials`, RFC 6749 §4.4).
- * The definition is the same on both sides; the Control Center stores it,
- * a code config declares it, and each side resolves it to a bearer through
- * the helper and cache below with its own egress-guarded fetch.
- */
-
-export const CREDENTIAL_KINDS = ["static", "oauth2-client-credentials"] as const;
-export type CredentialKind = (typeof CREDENTIAL_KINDS)[number];
-
-export const credentialDefinitionSchema = z.discriminatedUnion("kind", [
-    z.object({
-        kind: z.literal("static"),
-        value: z.string().min(1),
-    }),
-    z.object({
-        kind: z.literal("oauth2-client-credentials"),
-        /** The token endpoint; a client secret travels over TLS, to loopback, or to a host the egress policy admits. */
-        tokenUrl: z
-            .url()
-            .refine(
-                (url) => canCarrySecret(url),
-                "token URL must be https, or http to loopback or to a host the egress policy admits",
-            ),
-        clientId: z.string().min(1),
-        clientSecret: z.string().min(1),
-        scope: z.string().min(1).optional(),
-    }),
-]);
-export type CredentialDefinition = z.infer<typeof credentialDefinitionSchema>;
-export type OAuth2ClientCredentials = Extract<
-    CredentialDefinition,
-    { kind: "oauth2-client-credentials" }
->;
-
-/** One POST to the token endpoint through the caller's guarded fetch; `null` when the transport failed. */
-export type TokenPost = (
-    url: string,
-    init: { headers: Record<string, string>; body: string },
-) => Promise<{ status: number; body: string } | null>;
-
-/** A bearer and when it stops being one; `null` when the issuer did not say. */
-export type AcquiredToken = { token: string; expiresAt: number | null };
-
-export type AcquireResult =
-    | { ok: true; value: AcquiredToken }
-    | {
-          ok: false;
-          error:
-              | "token_url_insecure"
-              | "token_request_failed"
-              | "token_rejected"
-              | "token_response_invalid";
-      };
-
-const tokenResponseSchema = z.object({
-    access_token: z.string().min(1),
-    token_type: z.string().optional(),
-    // Some issuers (Azure AD v1 among them) send the lifetime as a string.
-    expires_in: z
-        .union([z.number(), z.string().regex(/^\d+$/).transform(Number)])
-        .pipe(z.number().nonnegative())
-        .optional(),
-});
-
-/**
- * The client credentials grant: a form-encoded POST with the client
- * authenticated by `client_secret_basic` (RFC 6749 §2.3.1, each half
- * form-encoded before base64). The endpoint's body never leaves this
- * function: a failure is one of three literals, since the body may echo
- * the client secret or carry the issuer's own error detail.
- */
-export async function acquireOAuth2ClientCredentials(
-    definition: OAuth2ClientCredentials,
-    post: TokenPost,
-) {
-    // Judged again here, not only when the definition was saved: the policy
-    // may have tightened since, and a secret never travels where it may not.
-    if (!canCarrySecret(definition.tokenUrl)) {
-        return { ok: false, error: "token_url_insecure" } satisfies AcquireResult;
-    }
-    const basic = Buffer.from(
-        `${encodeURIComponent(definition.clientId)}:${encodeURIComponent(definition.clientSecret)}`,
-    ).toString("base64");
-    const answer = await post(definition.tokenUrl, {
-        headers: {
-            Authorization: `Basic ${basic}`,
-            "Content-Type": "application/x-www-form-urlencoded",
-            Accept: "application/json",
-        },
-        body: new URLSearchParams({
-            grant_type: "client_credentials",
-            ...(definition.scope ? { scope: definition.scope } : {}),
-        }).toString(),
-    });
-    if (!answer) return { ok: false, error: "token_request_failed" } satisfies AcquireResult;
-    if (answer.status < 200 || answer.status >= 300) {
-        return { ok: false, error: "token_rejected" } satisfies AcquireResult;
-    }
-    let parsed: z.ZodSafeParseResult<z.infer<typeof tokenResponseSchema>>;
-    try {
-        parsed = tokenResponseSchema.safeParse(JSON.parse(answer.body));
-    } catch {
-        return { ok: false, error: "token_response_invalid" } satisfies AcquireResult;
-    }
-    if (!parsed.success || (parsed.data.token_type ?? "bearer").toLowerCase() !== "bearer") {
-        return { ok: false, error: "token_response_invalid" } satisfies AcquireResult;
-    }
-    const issuedAt = Date.now();
-    return {
-        ok: true as const,
-        value: {
-            token: parsed.data.access_token,
-            expiresAt:
-                parsed.data.expires_in === undefined
-                    ? null
-                    : issuedAt + parsed.data.expires_in * 1000,
-        },
-    } satisfies AcquireResult;
-}
-
-/** A token is not reused inside this margin of its expiry: the call it is presented on still has to complete. */
-const EXPIRY_MARGIN_MS = 30_000;
-
-/** Equal definitions share one key; a rotated secret is another definition and another token. Kept in memory only, like the definitions themselves. */
-function keyOf(definition: CredentialDefinition) {
-    return JSON.stringify(definition);
-}
-
-/**
- * Acquired tokens by definition, reused until their expiry margin. Concurrent
- * acquisitions of one definition share a single request; a token the issuer
- * gave no expiry for is answered but not kept, since nothing says when it
- * stops working. `invalidate` is for the caller that saw a 401: the next
- * resolve acquires again. Pure, so the console's client bundle may import
- * the schemas beside it.
- */
-export function createCredentialCache(now: () => number = Date.now) {
-    const tokens = new Map<string, AcquiredToken>();
-    const inFlight = new Map<string, Promise<AcquireResult>>();
-
-    return {
-        async get(definition: CredentialDefinition, acquire: () => Promise<AcquireResult>) {
-            const key = keyOf(definition);
-            const cached = tokens.get(key);
-            if (
-                cached &&
-                cached.expiresAt !== null &&
-                cached.expiresAt - EXPIRY_MARGIN_MS > now()
-            ) {
-                return { ok: true, value: cached } satisfies AcquireResult;
-            }
-            tokens.delete(key);
-            const pending = inFlight.get(key);
-            if (pending) return pending;
-            const acquiring = acquire()
-                .then((result) => {
-                    if (
-                        result.ok &&
-                        result.value.expiresAt !== null &&
-                        result.value.expiresAt - EXPIRY_MARGIN_MS > now()
-                    ) {
-                        tokens.set(key, result.value);
-                    }
-                    return result;
-                })
-                .finally(() => inFlight.delete(key));
-            inFlight.set(key, acquiring);
-            return acquiring;
-        },
-        invalidate(definition: CredentialDefinition) {
-            tokens.delete(keyOf(definition));
-        },
-    };
-}
-
-export type CredentialCache = ReturnType<typeof createCredentialCache>;

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;