Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
9.0 KB
Raw Blame
/**
 * `o2b search schema export|check` — the committed, versioned JSON Schema
 * artifact for the search query language (t_50c81d5c, Task E4).
 *
 * The artifact is DERIVED, never hand-edited: {@link
 * buildSearchQueryArtifact} projects the search-options descriptor (the
 * same table that derives the served `SEARCH_INPUT_SCHEMA` and the CLI
 * flag table) into `schemas/brain/search-query.schema.json`, and adds the
 * `brain.search_query_document.v1` sibling grammar for the line-oriented
 * query_document program as a `$defs` entry. Regeneration is a human
 * action (`o2b search schema export`); `check` re-derives and diffs, so a
 * descriptor change that outgrew the committed file is named in CI and by
 * any operator who runs it.
 *
 * Deliberately NOT `o2b brain schema ...`: that verb group is the VAULT
 * schema pack (`_brain.yaml`), a wholly unrelated "schema". This artifact
 * describes the search language, so it lives under the search verb group.
 *
 * The artifact documents the per-surface asymmetries the descriptor
 * records (the MCP-side `limit` maximum of MCP_LIMIT_MAX, the
 * `maxLength` on `query` that only the MCP surface enforces) instead of
 * silently flattening them; the CLI keeps its own bounds at its read
 * site.
 */

import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";

import { readFileSync, writeFileSync } from "node:fs";
import { deriveSearchInputSchema } from "../../../core/search/search-options-descriptor.ts";
import type { QueryIntent } from "../../../core/search/types.ts";
import { info } from "../../output.ts";
import { CliError, parseFlags } from "../helpers.ts";

/** The committed artifact path, from the repo root this module ships in. */
export const SEARCH_QUERY_SCHEMA_PATH = resolve(
  dirname(fileURLToPath(import.meta.url)),
  "..",
  "..",
  "..",
  "..",
  "schemas",
  "brain",
  "search-query.schema.json",
);

const DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema";

/**
 * The intent vocabulary, kept complete against the `QueryIntent` union:
 * a new intent is a tsc error here until the grammar names it - the same
 * probe pattern the descriptor's runtime anchor uses for `SearchOptions`.
 */
const QUERY_INTENT_COVERAGE: Record<QueryIntent, true> = {
  neutral: true,
  exact: true,
  entity: true,
  broad: true,
};
const QUERY_INTENT_NAMES: ReadonlyArray<QueryIntent> = Object.keys(
  QUERY_INTENT_COVERAGE,
) as ReadonlyArray<QueryIntent>;

/**
 * The line-oriented query_document grammar, as the artifact describes it.
 * The parser is hand-rolled (`parseStructuredRecallQueryDocument`); this
 * block is a faithful DESCRIPTION of it, held to the documented example
 * by the doc-example tests - not an enforcement engine.
 */
function queryDocumentGrammar() {
  return {
    $id: "brain.search_query_document.v1",
    title: "Brain Search Query Document v1",
    description:
      "Line-oriented query program steering each retrieval layer separately. One '<lane>: <value>' line per lane; blank lines and #-comments are ignored. At least one lane is required; the intent lane may appear at most once.",
    type: "object",
    required: [],
    additionalProperties: false,
    properties: {
      intent: {
        type: "string",
        enum: [...QUERY_INTENT_NAMES],
        description:
          "Retrieval posture: neutral (default ranking), exact (verbatim phrase preference), entity (tightly scoped subject), broad (recall-favouring). At most one intent line.",
      },
      lex: {
        type: "string",
        description:
          "Keyword-lane tokens, space separated; quote a multi-word token. A leading '-' excludes the token. Repeatable: later lex lines add tokens.",
      },
      vec: {
        type: "string",
        description: "Embedding-lane query text. Repeatable: later vec lines add queries.",
      },
      hyde: {
        type: "string",
        description:
          "Hypothetical passage the answer would look like. Repeatable: later hyde lines add passages.",
      },
    },
  };
}

/** The artifact's full shape: the served input schema plus the grammar block. */
export type SearchQueryArtifact = {
  readonly $schema: string;
  readonly $id: string;
  readonly title: string;
  readonly description: string;
  readonly type: "object";
  readonly required: string[];
  readonly additionalProperties: false;
  readonly properties: Record<string, unknown>;
  readonly $defs: Record<string, unknown>;
};

/**
 * The committed artifact, derived from the descriptor. The property set
 * IS `deriveSearchInputSchema()`'s - the served brain_search language -
 * re-anchored under a versioned `$id`, with the query-document grammar
 * beside it. Any descriptor row change flows here and is caught by the
 * generator check until `export` re-commits it.
 */
export function buildSearchQueryArtifact(): SearchQueryArtifact {
  const served = deriveSearchInputSchema();
  return {
    $schema: DRAFT_2020_12,
    $id: "brain.search_query.v1",
    title: "Brain Search Query v1",
    description:
      "The brain_search query language: every argument the MCP tool accepts, published as a versioned JSON Schema (draft 2020-12). The same table derives the served tools/list inputSchema and the o2b search CLI flags; see $defs.search_query_document for the line-oriented query_document grammar.",
    type: "object",
    required: [...served.required],
    additionalProperties: false,
    properties: JSON.parse(JSON.stringify(served.properties)),
    $defs: { search_query_document: queryDocumentGrammar() },
  };
}

/** The artifact serialized exactly the way `export` writes it. */
export function renderSearchQueryArtifact(): string {
  return `${JSON.stringify(buildSearchQueryArtifact(), null, 2)}\n`;
}

function usageError(message: string): CliError {
  return new CliError(
    `search schema: ${message} (usage: o2b search schema export [--stdout] | check)`,
  );
}

/** The property-name list of a schema object, for a one-line drift reason. */
function propertySetOf(schema: unknown): string {
  const properties =
    typeof schema === "object" && schema !== null && "properties" in schema
      ? (schema as { properties: Record<string, unknown> }).properties
      : {};
  return Object.keys(properties).toSorted().join(",");
}

/**
 * `o2b search schema export [--stdout]` - write the derived artifact to
 * the committed path (default) or, with `--stdout`, print exactly the
 * rendered bytes and touch nothing (the dry-run/CI preview the usage
 * string and cli-reference promise). `o2b search schema check` -
 * re-derive and compare with the committed file: exit 0 clean, exit 2 on
 * drift, so CI and operators share one named verdict. The comparison is
 * JSON equality, not byte equality: the committed file carries the repo
 * formatter's layout, so `export` writing raw builder bytes must never
 * read as drift - only content can drift. `--json` is `check`'s output
 * mode and is refused on export by name - `parseFlags` injects it into
 * every schema, and a flag the verb parses and ignores is the defect
 * `--stdout` once was.
 */
export async function cmdSearchSchema(argv: ReadonlyArray<string>): Promise<number> {
  const sub = argv[0];
  if (sub === "export") {
    const { flags } = parseFlags(argv.slice(1), {
      stdout: { type: "boolean" },
      json: { type: "boolean" },
    });
    if (flags["json"] === true) {
      throw usageError("--json is check's output mode; export takes only --stdout");
    }
    if (flags["stdout"] === true) {
      process.stdout.write(renderSearchQueryArtifact());
      return 0;
    }
    writeFileSync(SEARCH_QUERY_SCHEMA_PATH, renderSearchQueryArtifact(), "utf8");
    info(`search schema: wrote ${SEARCH_QUERY_SCHEMA_PATH}`);
    return 0;
  }
  if (sub === "check") {
    const { flags } = parseFlags(argv.slice(1), { json: { type: "boolean" } });
    const asJson = flags["json"] === true;
    let committed: unknown;
    try {
      committed = JSON.parse(readFileSync(SEARCH_QUERY_SCHEMA_PATH, "utf8"));
    } catch (cause) {
      const reason = cause instanceof Error ? cause.message : String(cause);
      process.stderr.write(
        `error: search schema: ${SEARCH_QUERY_SCHEMA_PATH} is missing or unreadable (${reason}) - run 'o2b search schema export'\n`,
      );
      return 2;
    }
    const derived: unknown = JSON.parse(JSON.stringify(buildSearchQueryArtifact()));
    if (JSON.stringify(committed) === JSON.stringify(derived)) {
      if (asJson) {
        process.stdout.write(`${JSON.stringify({ ok: true, $id: "brain.search_query.v1" })}\n`);
      } else {
        info(`search schema: ${SEARCH_QUERY_SCHEMA_PATH} matches the descriptor`);
      }
      return 0;
    }
    const fileSet = propertySetOf(committed);
    const derivedSet = propertySetOf(derived);
    const detail =
      fileSet !== derivedSet
        ? `property set drifted (file: ${fileSet}; descriptor: ${derivedSet})`
        : "content drifted from the descriptor derivation";
    process.stderr.write(
      `error: search schema: ${SEARCH_QUERY_SCHEMA_PATH} ${detail} - run 'o2b search schema export' and commit the result\n`,
    );
    return 2;
  }
  throw usageError(`unknown subcommand '${sub ?? ""}'`);
}