@m6d/cortex-cli 1.0.0

package/src/config/load.ts

@@ -0,0 +1,76 @@
+/**
+ * Config discovery and loading (design spec §6.2). Env needs no step of its own:
+ * discovery is cwd-only and Bun's `.env` auto-load is cwd-relative, so the two
+ * are always colocated and `process.env` is populated before the config
+ * evaluates.
+ */
+
+import { existsSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import * as report from "@/ui/report";
+
+/** How a config path is printed once found: relative to the cwd, `./`-prefixed. */
+export function configLabel(path: string) {
+    const relativePath = relative(process.cwd(), path);
+    return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+}
+
+/**
+ * `./cortex.config.ts` in the cwd, that exact name — no upward walk and no
+ * extension fallback, so a run from the wrong directory fails loudly instead of
+ * silently picking up an ancestor's config. `--config` replaces the path
+ * outright and accepts anything Bun can import.
+ */
+export function findConfig(options: { path: string; explicit: boolean; command: string }) {
+    const { path, explicit, command } = options;
+    const absolute = resolve(process.cwd(), path);
+    if (existsSync(absolute)) return absolute;
+
+    if (explicit) {
+        report.fail({
+            what: `No config file at ${path}`,
+            blocks: [
+                "--config takes a path to a file Bun can import, resolved from the\ndirectory you run in.",
+            ],
+        });
+    }
+
+    report.fail({
+        what: `No cortex.config.ts in ${process.cwd()}`,
+        blocks: [
+            "The CLI looks for exactly ./cortex.config.ts in the directory you run in.\nIt does not search parent directories.",
+            "Run it from the project root, or point at the file:",
+            `  ${command} --config ./server/cortex.config.ts`,
+        ],
+    });
+}
+
+/** The whole loader: one import, one default export, no unwrap branch. */
+export async function loadConfig(path: string, verbose: boolean) {
+    try {
+        const module = (await import(pathToFileURL(path).href)) as { default?: unknown };
+        const config = module.default;
+
+        if (config === undefined) throw new Error("The module has no default export.");
+        if (typeof config !== "object" || config === null || Array.isArray(config)) {
+            throw new Error("The default export is not an object.");
+        }
+
+        return config as Record<string, unknown>;
+    } catch (error) {
+        report.fail({
+            what: `Could not load ${configLabel(path)}`,
+            error,
+            blocks: [
+                // The line above this one is the underlying error, and for the most
+                // common failure it reads `Cannot find package '@m6d/cortex-server'` —
+                // the config imports the server for `defineAgent`. So the install is
+                // named here rather than left to be inferred.
+                "Importing the file has to run cleanly on its own: it default-exports a\nplain CortexConfig object and nothing else, and every package it imports\nhas to be installed — `bun add @m6d/cortex-server` if that is what is\nmissing above.",
+            ],
+            verbose,
+        });
+    }
+}

package/src/config/validate.ts

@@ -0,0 +1,46 @@
+/**
+ * One generic rule (design spec §6.3): a key present with an `undefined` value
+ * is a failure, listed by full path. It is essentially always the
+ * `process.env["X"]!` pattern, where `!` silences the type error and `undefined`
+ * flows on to fail far from its cause. Absent keys are fine — that is how
+ * optional sections are expressed.
+ *
+ * The error names config paths only. Annotating each with the env var behind it
+ * is not implementable: the CLI imports an already-evaluated object, so the name
+ * is gone. Point at `.env` and stop.
+ */
+
+import { configLabel } from "@/config/load";
+import * as report from "@/ui/report";
+
+export function validateConfig(config: Record<string, unknown>, path: string) {
+    const paths = findUndefined(config, "", new WeakSet());
+    if (!paths.length) return;
+
+    report.fail({
+        what: `${configLabel(path)} has ${paths.length} undefined value${paths.length === 1 ? "" : "s"}`,
+        blocks: [
+            paths.map((entry) => `  ${entry}`).join("\n"),
+            "These keys are present but evaluate to undefined — usually a missing\nenvironment variable. Bun loads .env from the directory you run in; check\nthat ./.env exists and is complete.",
+        ],
+    });
+}
+
+// `seen` guards the domain graph, where concepts and endpoints reference each
+// other in cycles.
+function findUndefined(value: object, prefix: string, seen: WeakSet<object>): string[] {
+    if (seen.has(value)) return [];
+    seen.add(value);
+
+    return (Object.entries(value) as [string, unknown][]).flatMap(function ([key, child]) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (child === undefined) return [path];
+        if (typeof child !== "object" || child === null) return [];
+        // Domain data is built by the server's `define*` helpers, which write
+        // every optional key whether or not it was passed. `undefined` under a
+        // `__brand` means "this endpoint mutates nothing", never a missing env
+        // var, so the rule stops at the seed data it would otherwise drown in.
+        if ("__brand" in child) return [];
+        return findUndefined(child, path, seen);
+    });
+}

package/src/contracts/README.md

@@ -0,0 +1,23 @@
+# @cortex/contracts
+
+The shapes both sides of a cortex boundary must agree on. Private on purpose —
+it never publishes; each publishable package carries its own copy:
+
+- `@m6d/cortex-server` and `@m6d/cortex-cli` publish raw source, so their
+  `prepack` vendors a copy of this directory into the tarball (`contracts/` and
+  `src/contracts/` respectively), resolved there by their shipped tsconfig paths.
+- `@m6d/cortex-angular` and `@m6d/cortex-react` compile the parts they import
+  into their build artifacts.
+
+Three boundaries, one subpath each:
+
+| import                      | boundary                                                      |
+| --------------------------- | ------------------------------------------------------------- |
+| `@cortex/contracts/wire`    | chat client ↔ server (HTTP/WebSocket types)                   |
+| `@cortex/contracts/runtime` | cortex-cc console ↔ server runtime API (zod schemas)          |
+| `@cortex/contracts/graph`   | graph authoring (cli) ↔ server (vocabulary, helpers, clients) |
+
+Everything is consumed as TypeScript source — no build, no dist. Nothing here
+has a runtime dependency beyond zod (for `/runtime`), and nothing here may grow
+one: these files are compiled into an Angular library, a React library, a CLI
+and a Bun server alike.

package/src/contracts/graph/embed.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ *
+ * TanStack AI removed embeddings, and the graph only ever needed the plain
+ * OpenAI-compatible `/embeddings` call cortex is already configured for — so this
+ * is a bare `fetch`, and this package keeps its zero dependencies.
+ *
+ * Everything under `./graph` is written to the oldest target any consumer builds
+ * against — an Angular library compiles these sources directly — and imports
+ * siblings by their `.js` specifier so one emit serves both `dist` and source.
+ */
+
+/** 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[][]>;
+
+export function createEmbedder(config: EmbeddingProviderConfig) {
+    const url = `${config.baseURL.replace(/\/+$/, "")}/embeddings`;
+
+    return async function embed(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);
+    };
+}

package/src/contracts/graph/helpers.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 propertiesDescriptions = Object.fromEntries(
+        Object.entries({
+            ...(input.propertiesDescriptions ?? {}),
+            ...(input.paramDescriptions ?? {}),
+            ...(input.responseDescriptions ?? {}),
+        }).filter(([, value]) => value != null),
+    ) as Record<string, string>;
+
+    const normalized = input.autoGenerated;
+
+    return {
+        __brand: "endpoint" as const,
+        name: input.name,
+        description: input.description ?? input.name,
+        path: input.path,
+        method: input.method,
+        propertiesDescriptions,
+        params: normalized ? [...normalized.params] : [],
+        body: normalized ? [...normalized.body] : [],
+        response: normalized ? [...normalized.response] : [],
+        successStatus: normalized?.successStatus ?? 200,
+        errorStatuses: normalized ? [...normalized.errorStatuses] : [],
+        responseKind: normalized?.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/neo4j.ts

@@ -0,0 +1,97 @@
+/**
+ * Configurable Neo4j HTTP client, shared by the graph's writer and its reader.
+ *
+ * All configuration is passed explicitly — no environment variables are read —
+ * 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 Neo4jClient = {
+    query(cypher: string, parameters?: Record<string, unknown>): Promise<string>;
+};
+
+export function createNeo4jClient(config: Neo4jConfig, embed?: EmbedFn) {
+    async function query(cypher: string, parameters?: Record<string, unknown>) {
+        // Auto-embed parameters whose keys start with '#'
+        const embeddedParams = Object.keys(parameters ?? {}).filter((x) => x.startsWith("#"));
+
+        if (embeddedParams.length) {
+            if (!embed) {
+                throw new Error("An embedder is required when using # parameters");
+            }
+
+            const embeddings = await embed(embeddedParams.map((k) => parameters![k] as string));
+
+            embeddedParams.forEach((k, idx) => {
+                delete parameters![k];
+                parameters![k.slice(1)] = embeddings[idx]!;
+            });
+        }
+
+        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: parameters ?? {},
+                    },
+                ],
+            }),
+        });
+
+        if (!response.ok) {
+            return JSON.stringify({
+                error: true,
+                status: response.status,
+                message: `Neo4j request failed with status ${response.status}`,
+            });
+        }
+
+        const result = (await response.json()) as {
+            errors?: { code?: string; message: string }[];
+            results: { columns: string[]; data: { row: unknown[] }[] }[];
+        };
+
+        if (result.errors && result.errors.length > 0) {
+            // `code` rides alongside the message rather than inside it: it is the
+            // one-line identifier a report shows, and existing readers of
+            // `message` keep seeing exactly what they saw before.
+            return JSON.stringify({
+                error: true,
+                code: result.errors[0]!.code,
+                message: result.errors.map((e) => e.message).join("; "),
+            });
+        }
+
+        // Transform Neo4j response into a clean array of objects
+        const queryResult = result.results[0];
+        if (!queryResult) {
+            return JSON.stringify([]);
+        }
+
+        const { columns, data } = queryResult;
+        const rows = data.map((entry) => {
+            const obj: Record<string, unknown> = {};
+            columns.forEach((col, i) => {
+                obj[col] = entry.row[i];
+            });
+            return obj;
+        });
+
+        return JSON.stringify(rows);
+    }
+
+    return { query } satisfies Neo4jClient;
+}

package/src/contracts/graph/schema.ts

@@ -0,0 +1,65 @@
+/**
+ * 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

@@ -0,0 +1,131 @@
+/**
+ * Declarative types for knowledge graph seed data.
+ *
+ * This is the v2 schema:
+ * - Endpoints use params/body/response EndpointProperty arrays.
+ * - Source/default mappings are intentionally removed.
+ * - Services are concept associations (no hardcoded endpoint steps).
+ */
+
+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[];
+    paramDescriptions?: Partial<Record<string, string>>;
+    responseDescriptions?: Partial<Record<string, string>>;
+
+    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>;
+};

package/src/contracts/graph.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 "./graph/schema";
+export { GRAPH_SCHEMA, GRAPH_SCHEMA_VERSION } from "./graph/schema";
+
+export type {
+    EndpointScalarType,
+    EndpointProperty,
+    ResponseKind,
+    AutoGenerated,
+    ConceptDef,
+    EndpointDef,
+    EndpointInput,
+    ServiceDef,
+    RuleDef,
+    DomainDef,
+} from "./graph/types";
+
+export {
+    defineConcept,
+    defineRule,
+    defineService,
+    defineDomain,
+    defineEndpoint,
+} from "./graph/helpers";
+
+export type { Neo4jConfig, Neo4jClient } from "./graph/neo4j";
+export { createNeo4jClient } from "./graph/neo4j";
+
+export type { EmbedFn, EmbeddingProviderConfig } from "./graph/embed";
+export { createEmbedder } from "./graph/embed";