@m6d/cortex-cli 0.1.0

package/src/contracts/graph/types.ts

@@ -0,0 +1,125 @@
+/**
+ * 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>;
+};

package/src/contracts/markdown/index.ts

@@ -0,0 +1,39 @@
+/*
+ * CommonMark fence tracking shared by the prompt rich-text pipeline and the
+ * widget's streamed-message segmenter.
+ */
+
+/**
+ * Line-by-line fence state, following CommonMark's fence rules: a fence line
+ * is indented at most three spaces; an opening backtick fence's info string
+ * may not contain backticks; and a fence closes only on the same marker
+ * character, with at least the opening run's length, followed by nothing but
+ * whitespace — so a `~~~` line, a shorter same-marker run, or a ```` ```js ````
+ * info line inside a backtick fence all stay code content.
+ */
+export function fenceTracker() {
+    let fence: { marker: string; length: number } | null = null;
+    return (line: string) => {
+        const match = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+        const delimiter = match?.[1];
+        const rest = match?.[2] ?? "";
+        if (delimiter) {
+            const marker = delimiter.charAt(0);
+            if (fence) {
+                if (
+                    marker === fence.marker &&
+                    delimiter.length >= fence.length &&
+                    rest.trim() === ""
+                ) {
+                    fence = null;
+                    return "close";
+                }
+                return "inside";
+            }
+            if (marker === "`" && rest.includes("`")) return "outside";
+            fence = { marker, length: delimiter.length };
+            return "open";
+        }
+        return fence ? "inside" : "outside";
+    };
+}

package/src/contracts/rich-text/index.ts

@@ -0,0 +1,220 @@
+/*
+ * The grammar and rendering pipeline for user-authored rich text that reaches
+ * the LLM (agent prompts, service descriptions, skill bodies). Both sides of
+ * the wire share it: the console edits and validates these strings, the
+ * console's runtime API pre-renders them (mentions + heading demotion), and
+ * `@m6d/cortex-server` applies per-request variable values. Three token
+ * grammars live here:
+ *
+ * - Tool mentions `@[name](uuid)` and skill mentions `/[name](uuid)` — the
+ *   uuid is authoritative; the inline name is only a display cache refreshed
+ *   on save ({@link normalizeMentions}) and resolved live when text is
+ *   rendered for the LLM ({@link renderMentions}).
+ * - Dataset mentions `#[name](name)` — a dataset's name is its identity, so
+ *   the token carries it twice and renders to it as is.
+ * - Variables `{{name}}` — validated against a known list at authoring time
+ *   ({@link analyzeVariables}) and substituted per request on the server
+ *   ({@link substituteVariables}).
+ */
+
+import { fenceTracker } from "../markdown";
+
+const UUID = String.raw`[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}`;
+
+/** One tool mention token, unanchored and flagless — the editor's tokenizer anchors it, the helpers below add `g`. */
+export const MENTION_PATTERN_SOURCE = String.raw`@\[([^\]\n]*)\]\((${UUID})\)`;
+/** One skill mention token; `/` is the slash-command convention skills already carry elsewhere. */
+export const SKILL_MENTION_PATTERN_SOURCE = String.raw`/\[([^\]\n]*)\]\((${UUID})\)`;
+
+/** One dataset mention token; the id is the dataset's name, which is already its identity. */
+export const DATASET_MENTION_PATTERN_SOURCE = String.raw`#\[([^\]\n]*)\]\(([a-zA-Z][a-zA-Z0-9_]{0,63})\)`;
+
+const MENTION_PATTERN = new RegExp(MENTION_PATTERN_SOURCE, "g");
+const SKILL_MENTION_PATTERN = new RegExp(SKILL_MENTION_PATTERN_SOURCE, "g");
+const DATASET_MENTION_PATTERN = new RegExp(DATASET_MENTION_PATTERN_SOURCE, "g");
+
+/** `{{name}}` or `{{/json/pointer}}` with inner whitespace tolerated: what substitution and analysis match. */
+export const VARIABLE_PATTERN_SOURCE = String.raw`{{\s*([^{}]*?)\s*}}`;
+/** The subset an editor turns into a chip: a non-empty, whitespace-free name. */
+export const VARIABLE_TOKEN_SOURCE = String.raw`{{\s*([^{}\s]+)\s*}}`;
+const VARIABLE_PATTERN = new RegExp(VARIABLE_PATTERN_SOURCE, "g");
+
+/** Entity names by id for the two mention grammars; a missing map leaves that grammar's cached names in place. */
+export type MentionNames = {
+    tools?: ReadonlyMap<string, string>;
+    skills?: ReadonlyMap<string, string>;
+};
+
+const NO_NAMES: ReadonlyMap<string, string> = new Map();
+
+function extractIds(text: string, pattern: RegExp) {
+    const ids: string[] = [];
+    for (const match of text.matchAll(pattern)) {
+        const id = match[2];
+        if (id && !ids.includes(id)) ids.push(id);
+    }
+    return ids;
+}
+
+export function extractMentionedToolIds(text: string) {
+    return extractIds(text, MENTION_PATTERN);
+}
+
+export function extractMentionedSkillIds(text: string) {
+    return extractIds(text, SKILL_MENTION_PATTERN);
+}
+
+/** The dataset names a text mentions, in order of first appearance. */
+export function extractMentionedDatasets(text: string) {
+    return extractIds(text, DATASET_MENTION_PATTERN);
+}
+
+/** Replaces each mention token with the entity's current name (falling back to the cached inline name). */
+export function renderMentions(text: string, names: MentionNames) {
+    const tools = names.tools ?? NO_NAMES;
+    const skills = names.skills ?? NO_NAMES;
+    return text
+        .replace(MENTION_PATTERN, (_, cached: string, id: string) => tools.get(id) ?? cached)
+        .replace(SKILL_MENTION_PATTERN, (_, cached: string, id: string) => skills.get(id) ?? cached)
+        .replace(DATASET_MENTION_PATTERN, (_, _cached: string, name: string) => name);
+}
+
+/** Refreshes stale display names inside stored text, keeping the tokens intact. */
+export function normalizeMentions(text: string, names: MentionNames) {
+    const tools = names.tools ?? NO_NAMES;
+    const skills = names.skills ?? NO_NAMES;
+    return text
+        .replace(MENTION_PATTERN, (token, _cached: string, id: string) => {
+            const name = tools.get(id);
+            return name === undefined ? token : `@[${name}](${id})`;
+        })
+        .replace(SKILL_MENTION_PATTERN, (token, _cached: string, id: string) => {
+            const name = skills.get(id);
+            return name === undefined ? token : `/[${name}](${id})`;
+        });
+}
+
+/** Splits the `{{variables}}` referenced in a text into known and unknown ones. */
+export function analyzeVariables<Variable extends string>(
+    text: string,
+    known: ReadonlyArray<Variable>,
+) {
+    const referenced = new Set(
+        Array.from(text.matchAll(VARIABLE_PATTERN), ([, name]) => name?.trim()),
+    );
+
+    return {
+        variables: known.filter((variable) => referenced.has(variable)),
+        unknownVariables: [...referenced].filter(
+            (variable): variable is string =>
+                variable !== undefined &&
+                !known.some((knownVariable) => knownVariable === variable),
+        ),
+    };
+}
+
+/** Fills `{{variables}}` with per-request values; unknown names stay verbatim. */
+export function substituteVariables(text: string, values: Record<string, string>) {
+    return text.replace(VARIABLE_PATTERN, (match, name: string) => values[name] ?? match);
+}
+
+/** ATX heading, CommonMark-style: up to three leading spaces, `#` run closed by space or line end. */
+const ATX_HEADING = /^( {0,3})(#{1,6})(?=[ \t]|$)/;
+
+/** Setext underline: a run of `=` or `-` alone on its line, up to three leading spaces. */
+const SETEXT_UNDERLINE = /^ {0,3}(=+|-+)[ \t]*$/;
+
+/** The skeleton owns `##` and `###`, so user headings start three levels below it. */
+function demotedHashes(level: number) {
+    return "#".repeat(Math.min(level + 3, 6));
+}
+
+/**
+ * Whether a line can be the text of a setext heading — i.e. it is an ordinary
+ * paragraph line, not a blank, a fence, another heading, or the start of a
+ * different block (quote/list), in which case the underline below it is a
+ * thematic break or list content rather than a heading marker.
+ */
+function isSetextText(line: string) {
+    return (
+        line.trim() !== "" &&
+        !ATX_HEADING.test(line) &&
+        !SETEXT_UNDERLINE.test(line) &&
+        !/^ {0,3}(`{3,}|~{3,})/.test(line) &&
+        !/^ {0,3}(>|[-*+][ \t]|\d+[.)][ \t])/.test(line)
+    );
+}
+
+/**
+ * Shifts user-authored headings down so they can never collide with the prompt
+ * skeleton, which owns `##` (sections) and `###` (card titles): `#` becomes
+ * `####`, deeper levels cap at `######`. Setext headings are rewritten as the
+ * equivalent demoted ATX heading, since two-level setext cannot express the
+ * shift. Fenced code is left alone.
+ */
+export function demoteHeadings(text: string) {
+    const lineState = fenceTracker();
+    const output: string[] = [];
+    for (const line of text.split("\n")) {
+        if (lineState(line) !== "outside") {
+            output.push(line);
+            continue;
+        }
+
+        const underline = SETEXT_UNDERLINE.exec(line)?.[1];
+        const previous = output[output.length - 1];
+        if (underline !== undefined && previous !== undefined && isSetextText(previous)) {
+            const level = underline.startsWith("=") ? 1 : 2;
+            output[output.length - 1] = `${demotedHashes(level)} ${previous.trim()}`;
+            continue;
+        }
+
+        output.push(
+            line.replace(ATX_HEADING, (_, indent: string, hashes: string) => {
+                return `${indent}${demotedHashes(hashes.length)}`;
+            }),
+        );
+    }
+    return output.join("\n");
+}
+
+/** The one render step for LLM-bound rich text: resolve mentions, then demote headings. */
+export function renderRichText(text: string, names: MentionNames) {
+    return demoteHeadings(renderMentions(text, names));
+}
+
+/**
+ * Reduces rich text to plain prose for embeddings: mentions become entity
+ * names (cached inline names when no map is given) and markdown syntax is
+ * dropped.
+ * A regex stripper, not a markdown parser: nested emphasis or exotic
+ * constructs may leave residue; swap in a real parser if retrieval quality
+ * ever shows it.
+ */
+export function stripToPlaintext(text: string, names: MentionNames = {}) {
+    const lineState = fenceTracker();
+    return renderMentions(text, names)
+        .split("\n")
+        .filter((line) => {
+            const state = lineState(line);
+            return state !== "open" && state !== "close";
+        })
+        .map((line) =>
+            line
+                .replace(/^ {0,3}#{1,6}[ \t]+/, "")
+                .replace(SETEXT_UNDERLINE, "")
+                .replace(/^\s{0,3}(>\s?)+/, "")
+                .replace(/^(\s*)([-*+]|\d+[.)])\s+/, "$1")
+                .replace(/^\s*([-*_]\s*){3,}$/, ""),
+        )
+        .join("\n")
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/(\*\*|__)([^*_]+)\1/g, "$2")
+        .replace(/(^|\W)[*_]([^*_]+)[*_](?=\W|$)/gm, "$1$2")
+        .replace(/~~([^~]+)~~/g, "$1")
+        .replace(/`([^`]*)`/g, "$1")
+        .replace(/\\([\\*_#[\]()>!`~+.-])/g, "$1")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}