Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.0 KB
Raw Blame
/**
 * Frontmatter equality filter (#7159): `where: { key: value | [values] }` on
 * search, query and list_pages (CLI `--where key=value`, repeatable). Keys
 * AND; a key's values OR. A value matches a page whose top-level frontmatter
 * field equals it, or whose field is a list containing it. A string that reads
 * as a number or a boolean also matches that JSON value, since the CLI only
 * sends strings (`--where cycle=2024` matches `cycle: 2024`).
 *
 * SQL: one `p.frontmatter @> $n::text::jsonb` containment per accepted JSON form,
 * so the GIN index on pages.frontmatter (idx_pages_frontmatter, jsonb_ops)
 * serves every key; values are always bound parameters, never SQL text, and
 * keys travel inside the bound JSON. Keys are still held to a plain
 * identifier charset so a typo or an injection attempt fails loudly.
 * The filter only narrows rows: every visibility, source and private-page
 * predicate a caller already gets still applies.
 */
import { joinFragments, sqlFragment, type SqlFragment } from '../engine-sql/fragment.ts';

export type FrontmatterValue = string | number | boolean;
/** Normalized: every key maps to a non-empty value list. */
export type FrontmatterWhere = Record<string, FrontmatterValue[]>;

export const FRONTMATTER_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
const MAX_KEYS = 8;
const MAX_VALUES = 32;
const MAX_VALUE_CHARS = 256;
export const WHERE_EXAMPLE = { status: 'active' };

export class FrontmatterWhereError extends Error {}

/** Validate a caller's `where`; undefined when absent or empty. Throws FrontmatterWhereError on a bad key or value. */
export function parseFrontmatterWhere(raw: unknown): FrontmatterWhere | undefined {
  if (raw === undefined || raw === null) return undefined;
  if (typeof raw !== 'object' || Array.isArray(raw)) {
    throw new FrontmatterWhereError('`where` must be an object of frontmatter keys to a value or a list of values.');
  }
  const entries = Object.entries(raw as Record<string, unknown>);
  if (entries.length > MAX_KEYS) throw new FrontmatterWhereError(`\`where\` takes at most ${MAX_KEYS} keys (got ${entries.length}).`);
  const out: FrontmatterWhere = {};
  for (const [key, value] of entries) {
    if (!FRONTMATTER_KEY_RE.test(key)) {
      throw new FrontmatterWhereError(`\`where\` key "${key.slice(0, 64)}" is not a frontmatter field name (letters, digits, _ and -, starting with a letter or _, at most 64 characters).`);
    }
    const values = Array.isArray(value) ? value : [value];
    if (values.length === 0 || values.length > MAX_VALUES) {
      throw new FrontmatterWhereError(`\`where.${key}\` needs 1 to ${MAX_VALUES} values (got ${values.length}).`);
    }
    for (const v of values) {
      const scalar = typeof v === 'string' || typeof v === 'boolean' || (typeof v === 'number' && Number.isFinite(v));
      if (!scalar || (typeof v === 'string' && v.length > MAX_VALUE_CHARS)) {
        throw new FrontmatterWhereError(`\`where.${key}\` values must be strings (at most ${MAX_VALUE_CHARS} characters), finite numbers or booleans.`);
      }
    }
    out[key] = [...new Set(values as FrontmatterValue[])];
  }
  return entries.length > 0 ? out : undefined;
}

/** The JSON documents one value matches by containment: itself, as a list member, and a numeric/boolean reading of a string. */
function containmentDocs(key: string, value: FrontmatterValue): string[] {
  const forms = new Set<FrontmatterValue>([value]);
  if (typeof value === 'string') {
    if (/^-?(0|[1-9]\d*)(\.\d+)?$/.test(value)) forms.add(Number(value));
    if (value === 'true' || value === 'false') forms.add(value === 'true');
  }
  return [...forms].flatMap(v => [JSON.stringify({ [key]: v }), JSON.stringify({ [key]: [v] })]);
}

/** One `AND (...)` clause per key, values bound through `bind` (which returns the placeholder). */
export function frontmatterWhereClauses(alias: string, where: FrontmatterWhere | undefined, bind: (json: string) => string): string[] {
  if (!where) return [];
  return Object.entries(where).map(([key, values]) =>
    `AND (${values.flatMap(v => containmentDocs(key, v)).map(doc => `${alias}.frontmatter @> ${bind(doc)}::text::jsonb`).join(' OR ')})`);
}

/** The same clauses as one string with a leading space each ('' without a filter). */
export function frontmatterWhereSql(alias: string, where: FrontmatterWhere | undefined, bind: (json: string) => string): string {
  return frontmatterWhereClauses(alias, where, bind).map(c => ` ${c}`).join('');
}

/** The same predicate as a composable engine-sql fragment, each clause with a leading space ('' without a filter). */
export function frontmatterWhereFragment(where: FrontmatterWhere | undefined): SqlFragment {
  if (!where) return sqlFragment``;
  return joinFragments(Object.entries(where).map(([key, values]) =>
    sqlFragment` AND (${joinFragments(values.flatMap(v => containmentDocs(key, v)).map(doc => sqlFragment`p.frontmatter @> ${doc}::text::jsonb`), ' OR ')})`), '');
}

/**
 * The authoritative check on finished rows: arms that do not run through the
 * filtered SQL legs (exact lookup, relational, alias fan-out, facts) can add
 * pages, so a filtered search keeps only rows whose page matches. One
 * indexed read over the result's page ids; a row with no page id is dropped.
 */
export async function keepFrontmatterMatches<T extends { page_id?: number | null }>(
  engine: { executeRaw<R>(sql: string, params?: unknown[]): Promise<R[]> },
  rows: T[],
  where: FrontmatterWhere | undefined,
): Promise<T[]> {
  if (!where || rows.length === 0) return rows;
  const ids = [...new Set(rows.flatMap(r => typeof r.page_id === 'number' && r.page_id > 0 ? [r.page_id] : []))];
  if (ids.length === 0) return [];
  const params: unknown[] = [ids];
  const clause = frontmatterWhereSql('p', where, json => `$${params.push(json)}`);
  const matched = await engine.executeRaw<{ id: number | string }>(`SELECT p.id FROM pages p WHERE p.id = ANY($1::bigint[])${clause}`, params);
  const keep = new Set(matched.map(r => Number(r.id)));
  return rows.filter(r => typeof r.page_id === 'number' && keep.has(r.page_id));
}