@m6d/cortex-cli 0.12.1 → 0.14.0

package/src/commands/graph.ts

@@ -1,228 +0,0 @@
-import type { Command } from "@commander-js/extra-typings";
-import {
-    GRAPH_SCHEMA,
-    GRAPH_SCHEMA_VERSION,
-    createEmbedder,
-    createNeo4jClient,
-    type DomainDef,
-    type EmbeddingProviderConfig,
-    type Neo4jClient,
-    type Neo4jConfig,
-} from "@cortex/contracts/graph";
-import pc from "picocolors";
-
-import { configLabel, configOption, openProject } from "@/config/load";
-import { seedGraph } from "@/graph/seed";
-import * as report from "@/ui/report";
-
-const TITLE = "cortex graph seed";
-
-/** Domain names are longer than swagger's finding labels, so the body is wider. */
-const DOMAIN_COLUMN = 14;
-
-/** A failing statement is worth one line: enough to identify, not enough to drown. */
-const DETAIL_WIDTH = 60;
-
-/** Only the parts of a loaded config `graph seed` reads. */
-type ProjectConfig = {
-    neo4j?: Neo4jConfig;
-    embedding?: EmbeddingProviderConfig & { dimension: number };
-    knowledge?: { domains?: Record<string, DomainDef> };
-    agents?: Record<string, { knowledge?: { domains?: Record<string, DomainDef> } | null }>;
-};
-
-// Connection failures reach us as whatever `fetch` threw, so match on shape
-// rather than on a driver's error class.
-const UNREACHABLE =
-    /unable to connect|connection refused|econnrefused|failed to fetch|fetch failed|enotfound|getaddrinfo|timed out/i;
-
-export function registerGraph(program: Command) {
-    const graph = program
-        .command("graph")
-        .helpGroup("Resources:")
-        .summary("The Neo4j knowledge graph")
-        .description(
-            "The Neo4j knowledge graph.\n\nReads `knowledge.domains` and `neo4j` from your cortex.config.ts.",
-        )
-        .addOption(configOption())
-        .helpCommand(false);
-
-    // No flags. `--domain <name>` is flag-shaped design work, not a flag:
-    // `expandDomains` resolves cross-domain references and the node pass creates every
-    // node before any edge, so a subset seed risks dangling edges.
-    graph
-        .command("seed")
-        .description("Load concepts, endpoints, services, and rules into Neo4j")
-        .action(async function () {
-            await seed(graph);
-        });
-}
-
-async function seed(group: Command) {
-    const { config: loaded, configPath, verbose } = await openProject(group, TITLE);
-    const config = loaded as ProjectConfig;
-
-    // Inputs are reported as they resolve. With no domains there is nothing to
-    // seed; an absent neo4j or embedding section is `runSeed`'s error to throw.
-    if (config.neo4j?.url) report.input("Neo4j", config.neo4j.url);
-    const domains = collectDomains(config);
-    const names = Object.keys(domains);
-    if (!names.length) failMissingDomains(configPath);
-    report.input("Domains", `${names.length} — ${names.join(", ")}`);
-
-    const startedAt = Date.now();
-    const result = await runSeed(config, domains).catch(function (error: unknown): never {
-        return failSeed({ error, config, configPath, verbose });
-    });
-
-    // A domain is the unit the user edits, so it is the unit the report counts
-    // against: a wrong number next to `attendance` points at src/domains/attendance/.
-    report.blank();
-    for (const [name, domain] of Object.entries(result.domains)) {
-        const counts = [report.plural(domain.nodes, "node"), report.plural(domain.edges, "edge")];
-        if (domain.failed) counts.push(`${domain.failed} failed`);
-        report.row(name, counts.join(" · "), DOMAIN_COLUMN);
-
-        // The first failure only: enough to identify what broke, not enough to
-        // drown the run — the count above says how many followed it.
-        const failure = domain.failures[0];
-        if (failure) {
-            report.row("", `${pc.red("✗")} ${truncate(failure.error)}`, DOMAIN_COLUMN);
-            report.row("", `  ${truncate(oneLine(failure.statement))}`, DOMAIN_COLUMN);
-        }
-    }
-
-    // Embeddings are a second pass over the whole graph, so they get their own
-    // step rather than a row among the counts.
-    report.blank();
-    report.input(
-        "Embeddings",
-        `${report.plural(result.embeddings.concepts, "concept")}, dimension ${result.embeddings.dimension}`,
-    );
-    report.blank();
-
-    const counts = [report.plural(result.nodes, "node"), report.plural(result.edges, "edge")];
-    if (result.failed) counts.push(`${result.failed} failed`);
-    report.footer(`${counts.join(" · ")}  (${((Date.now() - startedAt) / 1000).toFixed(1)}s)`);
-
-    if (result.failed) {
-        report.note("The graph is partially seeded. Re-running is safe — seeding is MERGE-based.");
-        process.exit(1);
-    }
-}
-
-/** Cypher is generated multi-line and indented; a report row is neither. */
-function oneLine(statement: string) {
-    return statement.replace(/\s+/g, " ").trim();
-}
-
-function truncate(text: string) {
-    return text.length > DETAIL_WIDTH ? `${text.slice(0, DETAIL_WIDTH - 2)} …` : text;
-}
-
-/** Server level first, then per agent — an agent's domain of the same name wins. */
-function collectDomains(config: ProjectConfig) {
-    const all = { ...config.knowledge?.domains };
-
-    for (const agent of Object.values(config.agents ?? {})) {
-        Object.assign(all, agent.knowledge?.domains);
-    }
-
-    return all;
-}
-
-/**
- * The whole pipeline is the CLI's, built on the graph contract it depends on:
- * `@cortex/contracts/graph` is where the vocabulary, the Neo4j client and the embedder
- * come from, and the version it seeds at is the version of that dependency.
- */
-async function runSeed(config: ProjectConfig, domains: Record<string, DomainDef>) {
-    if (!config.neo4j) throw new Error("neo4j config is required for graph seed");
-    if (!config.embedding) throw new Error("embedding config is required for graph seed");
-
-    const embed = createEmbedder(config.embedding);
-    const neo4j = createNeo4jClient(config.neo4j, embed);
-
-    await warnOnRestamp(neo4j);
-
-    return await seedGraph(
-        {
-            neo4j,
-            embedding: { embed, dimension: config.embedding.dimension },
-            schema: GRAPH_SCHEMA,
-            schemaVersion: GRAPH_SCHEMA_VERSION,
-        },
-        domains,
-    );
-}
-
-/**
- * Seeding is MERGE-based, so a graph written under an older schema is not cleaned
- * up — its nodes stay, under labels nothing reads. Worth saying out loud; not
- * worth blocking on, since re-seeding is exactly how that graph gets fixed.
- */
-async function warnOnRestamp(neo4j: Neo4jClient) {
-    // An unreachable graph is the seed's to report, far better than a warning could.
-    const rows = await neo4j
-        .query(
-            `MATCH (g:${GRAPH_SCHEMA.label.marker}) RETURN g.${GRAPH_SCHEMA.prop.version} AS version`,
-        )
-        .catch(() => undefined);
-    if (!rows) return;
-
-    const stamped = (rows as { version?: number }[])[0]?.version;
-    if (stamped === undefined || stamped === GRAPH_SCHEMA_VERSION) return;
-
-    report.blank();
-    report.row(
-        "",
-        `${pc.yellow("!")} Graph was written with schema v${stamped}; restamping as v${GRAPH_SCHEMA_VERSION}.`,
-        DOMAIN_COLUMN,
-    );
-    report.row("", "  Nodes from the old schema are not removed.", DOMAIN_COLUMN);
-}
-
-function failMissingDomains(configPath: string): never {
-    report.fail({
-        what: `${configLabel(configPath)} has no knowledge.domains`,
-        blocks: [
-            "`graph seed` loads domain definitions into Neo4j. Add them:",
-            "  knowledge: { domains: { leaves: leavesDomain } }",
-            "See https://github.com/boring91/cortex/blob/main/packages/cortex-server/README.md#file-structure-convention",
-        ],
-    });
-}
-
-/**
- * The neo4j and embedding sections are `runSeed`'s to require — it throws
- * `"neo4j config is required for graph seed"`. This renders what it threw.
- */
-function failSeed(options: {
-    error: unknown;
-    config: ProjectConfig;
-    configPath: string;
-    verbose: boolean;
-}): never {
-    const { error, config, configPath, verbose } = options;
-    const label = configLabel(configPath);
-    const message = error instanceof Error ? error.message : String(error);
-    const url = config.neo4j?.url;
-    if (url !== undefined && UNREACHABLE.test(message)) {
-        report.fail({
-            what: `Cannot reach Neo4j at ${url}`,
-            error,
-            blocks: [
-                "Is it running?  docker compose up -d neo4j",
-                `Otherwise check neo4j.url / neo4j.user / neo4j.password in\n${label}.`,
-            ],
-            verbose,
-        });
-    }
-
-    report.fail({
-        what: "Could not seed the graph",
-        error,
-        blocks: [`Check neo4j, embedding, and knowledge.domains in ${label}.`],
-        verbose,
-    });
-}

package/src/commands/swagger.ts

@@ -1,247 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-
-import { type Command, Option } from "@commander-js/extra-typings";
-
-import { configLabel, configOption, openProject } from "@/config/load";
-import { declaredRoute, extractEndpoints } from "@/swagger/extract-endpoints";
-import * as report from "@/ui/report";
-
-/** A convention, not config: `KnowledgeConfig` has no `domainsDir`. */
-const DEFAULT_DOMAINS_DIR = "src/domains";
-
-/** Only the parts of a loaded config `swagger` reads to report its inputs. */
-type ProjectConfig = {
-    knowledge?: { swagger?: { url?: string } };
-    agents?: Record<string, { knowledge?: { swagger?: { url?: string } } | null } | undefined>;
-};
-
-export function registerSwagger(program: Command) {
-    const swagger = program
-        .command("swagger")
-        .helpGroup("Resources:")
-        .summary("Endpoint schemas, from your Swagger spec")
-        .description(
-            "Endpoint schemas, from your Swagger spec.\n\nReads `knowledge.swagger.url` from your cortex.config.ts and the .endpoint.ts\nfiles under src/domains.",
-        )
-        .addOption(configOption())
-        // Declared once, on the group: the two verbs read the same directory, and
-        // commander hands a verb's unknown options back to its parent, so
-        // `swagger -d x sync` and `swagger sync -d x` both land here.
-        .addOption(
-            new Option(
-                "-d, --domains-dir <path>",
-                "Domains root, relative to the config file",
-            ).default(DEFAULT_DOMAINS_DIR, DEFAULT_DOMAINS_DIR),
-        )
-        .helpCommand(false);
-
-    for (const verb of ["sync", "check"] as const) {
-        swagger
-            .command(verb)
-            .description(
-                verb === "sync"
-                    ? "Update .endpoint.ts files in place"
-                    : "Report drift without writing (exit 2 if stale)",
-            )
-            .action(async function () {
-                await run(swagger, verb, swagger.opts().domainsDir);
-            });
-    }
-}
-
-async function run(group: Command, verb: "sync" | "check", domainsDirOption: string) {
-    const title = `cortex swagger ${verb}`;
-    const { config: loaded, configPath, path, explicit, verbose } = await openProject(group, title);
-
-    // Relative to the config file, never to the cwd — the domains tree belongs to
-    // the project, and `--config ../other/cortex.config.ts` must still find it.
-    const domainsDir = resolve(dirname(configPath), domainsDirOption);
-    if (!existsSync(domainsDir)) failMissingDomainsDir(domainsDir, verb);
-
-    const urls = swaggerUrls(loaded);
-    if (!urls.length) failMissingSwaggerUrl(configPath, verb);
-    for (const url of urls) report.input("Swagger", url);
-
-    // Unlike `graph seed`, this needs nothing from the project's server — not
-    // even a version handshake. What it writes is `.endpoint.ts` source whose
-    // generated block has to satisfy that server's own `EndpointDef`, so a
-    // codegen that outran the installed server is a type error in the project's
-    // `bun run check`, loudly, rather than something to detect here.
-    const startedAt = Date.now();
-    const result = await extractEndpoints({
-        swaggerUrls: urls,
-        domainsDir,
-        write: verb === "sync",
-    }).catch(function (error: unknown): never {
-        return failExtract({ error, configPath, verbose });
-    });
-
-    // Reported once the run is over because that is when the count is known —
-    // the total is every file the walk considered, however it ended up.
-    const total =
-        result.matched + result.updated.length + result.drift.length + result.missing.length;
-    report.input(
-        "Domains",
-        `${configLabel(domainsDir)} — ${report.plural(total, "endpoint file")}`,
-    );
-    report.blank();
-
-    const elapsed = `(${((Date.now() - startedAt) / 1000).toFixed(1)}s)`;
-    if (verb === "sync") return renderSync(result, domainsDir, elapsed);
-    renderCheck(
-        result,
-        domainsDir,
-        elapsed,
-        syncCommand({ path, explicit, domainsDir: domainsDirOption }),
-    );
-}
-
-/**
- * The `sync` that fixes what `check` found has to act on the tree `check` read,
- * so it carries whatever flags got it there. Defaults stay off the line — a hint
- * is something to paste, not a transcript.
- */
-function syncCommand(options: { path: string; explicit: boolean; domainsDir: string }) {
-    return [
-        "cortex swagger sync",
-        ...(options.explicit ? [`--config ${options.path}`] : []),
-        ...(options.domainsDir === DEFAULT_DOMAINS_DIR
-            ? []
-            : [`--domains-dir ${options.domainsDir}`]),
-    ].join(" ");
-}
-
-type Report = {
-    matched: number;
-    missing: string[];
-    drift: string[];
-    updated: string[];
-};
-
-/**
- * `sync` says what it did. Only changed files are printed — at 37 files a
- * per-file log is 34 lines of `ok` — and `MISSING` goes last, because it is the
- * one thing left for a human. Writing is the job, so it still exits 0.
- */
-function renderSync(result: Report, domainsDir: string, elapsed: string) {
-    for (const file of result.updated) report.row("updated", file);
-    for (const file of result.missing) {
-        report.row("missing", file);
-        report.row("", `${routeOf(join(domainsDir, file))} — no match in the spec`);
-    }
-    if (result.updated.length || result.missing.length) report.blank();
-
-    const parts = [`${result.updated.length} updated`];
-    if (result.missing.length) parts.push(`${result.missing.length} missing`);
-    parts.push(`${result.matched} unchanged`);
-    if (result.updated.length) parts.push("formatted with prettier");
-    report.footer(`${parts.join(" · ")}  ${elapsed}`);
-
-    if (result.missing.length) {
-        report.note(
-            `${missingLead(result)} no match in the spec. Either the route moved, or the file is\nstale — \`cortex swagger check\` will keep failing until it is resolved.`,
-        );
-    }
-}
-
-/**
- * `check` says what is wrong, and writes nothing. `drift` and `MISSING` are both
- * findings — one is fixed by a tool, the other by a person — so either exits 2.
- */
-function renderCheck(result: Report, domainsDir: string, elapsed: string, sync: string) {
-    for (const file of result.drift) {
-        report.row("drift", file);
-        report.row("", `${routeOf(join(domainsDir, file))} — no longer matches the spec`);
-    }
-    for (const file of result.missing) {
-        report.row("missing", file);
-        report.row("", `${routeOf(join(domainsDir, file))} — no match in the spec`);
-    }
-    if (result.drift.length || result.missing.length) report.blank();
-
-    const parts: string[] = [];
-    if (result.drift.length) parts.push(`${result.drift.length} drifted`);
-    if (result.missing.length) parts.push(`${result.missing.length} missing`);
-    parts.push(`${result.matched} up to date`);
-    report.footer(`${parts.join(" · ")}  ${elapsed}`);
-
-    if (result.drift.length) {
-        report.note(
-            `Run \`${sync}\` to update the ${report.plural(result.drift.length, "drifted file")}.`,
-        );
-    }
-    if (result.missing.length) {
-        report.note(
-            `${missingLead(result)} no match in the spec. Either the route moved, or the file is\nstale — \`cortex swagger sync\` cannot fix it; it needs a human.`,
-        );
-    }
-    if (result.drift.length || result.missing.length) process.exit(2);
-}
-
-/**
- * The route a finding is about. The report is a list of paths; the route is
- * what the reader has to act on, and it lives in the file.
- */
-function routeOf(filePath: string) {
-    const { method = "?", path = "?" } = declaredRoute(readFileSync(filePath, "utf8"));
-    return `${method} ${path}`;
-}
-
-/** Server level, then per agent, deduped — per-agent docs override on a key clash. */
-function swaggerUrls(config: ProjectConfig) {
-    const urls = new Set<string>();
-    if (config.knowledge?.swagger?.url) urls.add(config.knowledge.swagger.url);
-
-    for (const agent of Object.values(config.agents ?? {})) {
-        if (agent?.knowledge?.swagger?.url) urls.add(agent.knowledge.swagger.url);
-    }
-
-    return [...urls];
-}
-
-/** `1 endpoint file has` / `3 endpoint files have` — both notes open with it. */
-function missingLead(result: Report) {
-    return `${report.plural(result.missing.length, "endpoint file")} ${result.missing.length === 1 ? "has" : "have"}`;
-}
-
-/**
- * An absent domains dir is *couldn't run*, not "nothing to do": `extractEndpoints`
- * walks a missing directory as an empty one and would report a clean 0 of 0.
- */
-function failMissingDomainsDir(domainsDir: string, verb: string): never {
-    report.fail({
-        what: `No domains directory at ${configLabel(domainsDir)}`,
-        blocks: [
-            `\`swagger ${verb}\` reads .endpoint.ts files under a domains root — ${DEFAULT_DOMAINS_DIR} by\ndefault — resolved relative to the config file. Point it somewhere else:`,
-            `  cortex swagger ${verb} --domains-dir ./lib/domains`,
-        ],
-    });
-}
-
-function failMissingSwaggerUrl(configPath: string, verb: string): never {
-    report.fail({
-        what: `${configLabel(configPath)} has no knowledge.swagger.url`,
-        blocks: [
-            `\`swagger ${verb}\` generates endpoint schemas from a Swagger spec. Add one:`,
-            '  knowledge: { swagger: { url: "https://api.example.com/swagger/v1/swagger.json" } }',
-            "See https://github.com/boring91/cortex/blob/main/packages/cortex-server/README.md#file-structure-convention",
-        ],
-    });
-}
-
-/**
- * The `◇ Swagger` lines above name every URL that was tried, so the error
- * states the failure and points at the key behind it.
- */
-function failExtract(options: { error: unknown; configPath: string; verbose: boolean }): never {
-    const { error, configPath, verbose } = options;
-    report.fail({
-        what: "Could not read the Swagger spec",
-        error,
-        blocks: [
-            `Is the API running? Otherwise check knowledge.swagger.url in\n${configLabel(configPath)}.`,
-        ],
-        verbose,
-    });
-}

package/src/config/load.ts

@@ -1,122 +0,0 @@
-/**
- * Config discovery and loading. 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 { Option } from "@commander-js/extra-typings";
-import type { Command } from "@commander-js/extra-typings";
-import { isRecord } from "@cortex/contracts/json";
-
-import { validateConfig } from "@/config/validate";
-import * as report from "@/ui/report";
-
-// Discovery is this exact name in the cwd, with no upward walk, so the flag's
-// default *is* the discovery rule.
-const DEFAULT_CONFIG = "./cortex.config.ts";
-
-/**
- * `-c, --config <path>` for a command group that reads the project: declared
- * on the group, so `cortex new` and `cortex cc` never show it. Commander hands
- * a verb's unknown options back to its parent, so `swagger -c x sync` and
- * `swagger sync -c x` both land on the group.
- */
-export function configOption() {
-    // The second argument is what help prints; without it commander would
-    // JSON.stringify the path and show quotes.
-    return new Option("-c, --config <path>", "Path to cortex.config.ts").default(
-        DEFAULT_CONFIG,
-        DEFAULT_CONFIG,
-    );
-}
-
-/** 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.
- */
-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`,
-        ],
-    });
-}
-
-/**
- * What every project command does before its own work: find the config from
- * its group's `--config`, open the report, load and validate it, and report
- * its path as the first input. Discovery runs before the report opens: with
- * no config there is no run to report on, only the reason there isn't one.
- */
-export async function openProject(group: Command, title: string) {
-    // The group and the root reach this file untyped: `Command` here is the
-    // parameter type, not cli.ts's inferred one.
-    const { config: path, verbose = false } = group.optsWithGlobals() as {
-        config: string;
-        verbose?: boolean;
-    };
-    const explicit = group.getOptionValueSource("config") !== "default";
-    const configPath = findConfig({ path, explicit, command: title });
-
-    report.header(title);
-    const config = await loadConfig(configPath, verbose);
-    validateConfig(config, configLabel(configPath));
-    report.input("Config", configLabel(configPath));
-
-    return { config, configPath, path, explicit, verbose };
-}
-
-/** The whole loader: one import, one default export, no unwrap branch. */
-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 (!isRecord(config)) throw new Error("The default export is not an object.");
-
-        return config;
-    } 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

@@ -1,46 +0,0 @@
-/**
- * One generic rule: 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 * as report from "@/ui/report";
-
-/** `label` is how the config file is named in the failure: the `./`-relative path the loader prints. */
-export function validateConfig(config: Record<string, unknown>, label: string) {
-    const paths = findUndefined(config, "", new WeakSet());
-    if (!paths.length) return;
-
-    report.fail({
-        what: `${label} has ${report.plural(paths.length, "undefined value")}`,
-        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(([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);
-    });
-}