@ultimat3/cli 29.4.0 → 30.1.0

package/src/cmd-deploy-verify.ts

@@ -0,0 +1,380 @@
+// `x deploy verify`: does production serve this build, does it hold, and does a worker of this build
+// claim every queue. HTTP and Postgres only (axiom 7): pods are SAMPLED through the load balancer,
+// never enumerated, and a GitOps roll that never ran `x deploy` is checked the same way.
+
+import type { Clock } from '@ultimat3/core';
+import {
+  BUILD_ID_HEADER,
+  renderCauseValue,
+  renderThrowable,
+  systemClock,
+  UltimateError,
+} from '@ultimat3/core';
+import { deadlineSignal } from '@ultimat3/core/outbound';
+import type { QueueDemand, WorkerRecord } from '@ultimat3/jobs';
+import { requireAppRoot } from './app-root';
+import type { CommandContext } from './command';
+import { failed, ok } from './command';
+import type { WaitOutcome } from './deploy-verify-findings';
+import {
+  queueReadFinding,
+  resultData,
+  sampleFinding,
+  unservedFinding,
+} from './deploy-verify-findings';
+import type { VerifyOptions } from './deploy-verify-flags';
+import { readBuild, readOptions, VERIFY_COMMAND } from './deploy-verify-flags';
+import type { QueueGrade } from './deploy-verify-grade';
+import {
+  emptyTally,
+  failureOf,
+  foldSample,
+  gradeQueues,
+  UNGRADED,
+  windowClosed,
+} from './deploy-verify-grade';
+import { BadFlagError } from './errors';
+import { msg } from './messages';
+import type { CommandResult, Finding } from './output';
+
+/** One sample's own limit: a pod that hangs is a bad sample, never the whole wait gone. */
+const SAMPLE_TIMEOUT_MS = 10_000;
+/**
+ * The least a sample gets, however little of the wait is left. The last sleep ends ON the deadline,
+ * and that sample cut to nothing tallied a healthy origin as `unreachable`, every run. So `--timeout`
+ * can overrun by this much, once.
+ */
+const SAMPLE_FLOOR_MS = 1_000;
+
+/** What the queue grade reads. `close` lets the short-lived pool go. */
+export interface QueueReader {
+  workers(): Promise<readonly WorkerRecord[]>;
+  /**
+   * `JobDriver.demand()`: running on a worker that still serves, plus due rows of unpaused queues.
+   * Never `ready + running`, which counts a retiring old worker's runs and a paused queue's rows as
+   * work an `--idle-ok` pool is missing.
+   */
+  demand(): Promise<readonly QueueDemand[]>;
+  close(): Promise<void>;
+}
+
+export interface ExpectedQueues {
+  readonly queues: readonly string[];
+  /** A module that would not import leaves the set partial, which grades nothing honestly. */
+  readonly findings: readonly Finding[];
+}
+
+export interface DeployVerifyDeps {
+  readonly clock: Clock;
+  sleep(ms: number): Promise<void>;
+  expectedQueues(root: string): Promise<ExpectedQueues>;
+  /**
+   * `env` is the one `DATABASE_URL` came from, so the pooler mode is read from it too.
+   * `statementTimeoutMs` is what is left of `--timeout`: the server cancels a read past it.
+   */
+  openQueue(
+    databaseUrl: string,
+    env: CommandContext['env'],
+    statementTimeoutMs: number,
+  ): Promise<QueueReader>;
+  /**
+   * Resolves once `ms` of real time pass: what a hung read is raced against. `signal` disarms it,
+   * aborted the moment the read settles, so no timer holds the process open past the verdict.
+   */
+  expire(ms: number, signal: AbortSignal): Promise<void>;
+}
+
+/**
+ * Resolves once `ms` of real time pass; `signal`'s abort disarms it. Core's `deadlineSignal`, the
+ * one undoable deadline: a timer left armed would hold the process open past the verdict.
+ */
+export function expireAfter(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const deadline = deadlineSignal(ms, signal);
+    deadline.signal.addEventListener(
+      'abort',
+      () => {
+        const fired = deadline.timedOut();
+        deadline[Symbol.dispose]();
+        if (fired) resolve();
+      },
+      { once: true },
+    );
+  });
+}
+
+/** Imported when asked: the verdict on the build alone never loads the app or a database driver. */
+const realDeps: DeployVerifyDeps = {
+  clock: systemClock,
+  sleep: (ms) => Bun.sleep(ms),
+  expectedQueues: async (root) => (await import('./deploy-verify-queues')).expectedQueues(root),
+  openQueue: async (url, env, statementTimeoutMs) =>
+    (await import('./deploy-verify-queues')).openQueue(url, env, statementTimeoutMs),
+  expire: expireAfter,
+};
+
+interface Answered {
+  readonly status: number | null;
+  readonly build: string | null;
+  readonly cached: boolean;
+  readonly failure?: string;
+}
+
+/**
+ * One `GET /readyz` on a connection of its own, so the load balancer chooses again: a kept-alive
+ * socket would ask one pod the same question for the whole window. A redirect is an answer to tally,
+ * never to follow: another host's `/readyz` says nothing about this origin.
+ */
+async function takeSample(origin: string, limitMs: number): Promise<Answered> {
+  try {
+    const response = await fetch(`${origin}/readyz`, {
+      keepalive: false,
+      redirect: 'manual',
+      // Past a CDN or a caching proxy: the question is the fleet, never a stored copy of it.
+      headers: { 'cache-control': 'no-cache', pragma: 'no-cache' },
+      signal: AbortSignal.timeout(limitMs),
+    });
+    await response.body?.cancel();
+    const header = response.headers.get(BUILD_ID_HEADER);
+    const age = Number(response.headers.get('age') ?? '0');
+    return {
+      status: response.status,
+      build: header === null || header === '' ? null : header,
+      cached: Number.isNaN(age) || age > 0,
+    };
+  } catch (error) {
+    return { status: null, build: null, cached: false, failure: renderThrowable(error) };
+  }
+}
+
+/** The least time a database read gets, and the floor of its server-side `statement_timeout`. */
+const READ_FLOOR_MS = 1_000;
+
+/** The queue half: the set to grade, and how to reach the rows. Absent: no `DATABASE_URL`. */
+interface QueuePlan {
+  readonly expected: readonly string[];
+  open(statementTimeoutMs: number): Promise<QueueReader>;
+}
+
+/** The last grade a read produced, and the last read that failed. No grade: none ever landed. */
+interface QueueRead {
+  readonly grade: QueueGrade | undefined;
+  readonly lastFailure: string | undefined;
+  /**
+   * The grade came from a read on THIS pass. A kept grade is detail for the report and never a
+   * pass: workers can go between a read that landed and the next that failed.
+   */
+  readonly current: boolean;
+}
+
+interface Verdict {
+  readonly wait: WaitOutcome;
+  /** `undefined`: no queue plan, or the window never closed so nothing was read. */
+  readonly read: QueueRead | undefined;
+}
+
+/** One read of both halves, bounded by `limitMs` of real time. A miss is a failed read. */
+async function readQueues(
+  reader: QueueReader,
+  input: {
+    readonly expected: readonly string[];
+    readonly build: string;
+    readonly idleOk: readonly string[];
+  },
+  limitMs: number,
+  deps: DeployVerifyDeps,
+): Promise<QueueGrade> {
+  const disarm = new AbortController();
+  const expired = deps.expire(limitMs, disarm.signal).then(() => {
+    throw new UltimateError({
+      code: 'X_DB_UNAVAILABLE',
+      cause: `a read of x_job_workers outlasted one --interval or what was left of --timeout (${limitMs} ms)`,
+      fix: 'x jobs list --json',
+    });
+  });
+  let rows: readonly [readonly WorkerRecord[], readonly QueueDemand[]];
+  try {
+    rows = await Promise.race([Promise.all([reader.workers(), reader.demand()]), expired]);
+  } finally {
+    disarm.abort();
+  }
+  const [workers, demand] = rows;
+  return gradeQueues({
+    ...input,
+    workers,
+    depth: new Map(demand.map((queue) => [queue.queue, queue.demand])),
+  });
+}
+
+/**
+ * Sample until the window holds AND, with a queue plan, every queue is served, both on the same
+ * pass: web rolling back while the workers still roll is red, never a window that closed earlier.
+ * The queues are read only once the window has closed, then on every pass; the web role and the
+ * workers roll independently, so one read right after the window would fail a healthy roll. A failed
+ * read keeps the last grade. `--timeout` ends the whole wait, reads included.
+ */
+async function awaitVerdict(
+  options: VerifyOptions,
+  build: string,
+  deadline: number,
+  deps: DeployVerifyDeps,
+  plan: QueuePlan | undefined,
+): Promise<Verdict> {
+  // One bad sample per window's worth of samples is the most a settled fleet is allowed.
+  const perWindow = Math.max(1, Math.ceil(options.windowMs / options.intervalMs));
+  let tally = emptyTally();
+  let lastFailure: string | undefined;
+  let reader: QueueReader | undefined;
+  let read: QueueRead | undefined;
+  const left = (): number => deadline - deps.clock.monotonic();
+  /** One `/readyz` sample, folded in; whether the window holds after it. */
+  const sample = async (): Promise<boolean> => {
+    const answered = await takeSample(
+      options.origin,
+      Math.max(SAMPLE_FLOOR_MS, Math.min(SAMPLE_TIMEOUT_MS, left())),
+    );
+    lastFailure = answered.failure ?? lastFailure;
+    tally = foldSample(
+      tally,
+      {
+        at: deps.clock.monotonic(),
+        status: answered.status,
+        build: answered.build,
+        cached: answered.cached,
+      },
+      build,
+    );
+    return windowClosed(tally, options.windowMs, perWindow);
+  };
+  try {
+    for (;;) {
+      // Every pass starts with nothing current: a grade from an earlier pass is history.
+      if (read !== undefined) read = { ...read, current: false };
+      let closed = await sample();
+      if (closed && plan !== undefined) {
+        // One --interval at most: the window's last sample is never older than that when the
+        // queues are judged, and the server stops the statement at the same bound.
+        const bound = Math.max(READ_FLOOR_MS, Math.min(options.intervalMs, left()));
+        reader ??= await plan.open(bound);
+        try {
+          const grade = await readQueues(
+            reader,
+            { expected: plan.expected, build, idleOk: options.idleOk },
+            bound,
+            deps,
+          );
+          read = { grade, lastFailure: read?.lastFailure, current: true };
+        } catch (error) {
+          // One reset connection is a read lost, never the verdict: the last grade stands.
+          read = { grade: read?.grade, lastFailure: renderThrowable(error), current: false };
+        }
+        // Served is judged against web as it answers NOW: a sample taken after the read landed,
+        // so a rollback during the read is red, never a green from the sample before it.
+        if (read.current && read.grade?.unserved.length === 0) closed = await sample();
+      }
+      // The one success rule: this pass's sample holds the window and, with a plan, this pass's
+      // read landed and serves every queue. Nothing kept from an earlier pass counts.
+      const served =
+        plan === undefined || (read?.current === true && read.grade?.unserved.length === 0);
+      const wait = { tally, closed, lastFailure };
+      if ((closed && served) || left() <= 0) return { wait, read };
+      await deps.sleep(Math.min(options.intervalMs, left()));
+    }
+  } finally {
+    await reader?.close();
+  }
+}
+
+/** The set first, so a typo or an app that will not load costs no wait. */
+async function readExpected(
+  root: string,
+  options: VerifyOptions,
+  deps: DeployVerifyDeps,
+): Promise<ExpectedQueues> {
+  const expected = await deps.expectedQueues(root);
+  if (expected.findings.length > 0) return expected;
+  const stray = options.idleOk.find((queue) => !expected.queues.includes(queue));
+  if (stray !== undefined) {
+    throw new BadFlagError({
+      flag: 'idle-ok',
+      command: VERIFY_COMMAND,
+      reason: `${renderCauseValue(stray)} is not a queue of this app (${expected.queues.map((queue) => renderCauseValue(queue)).join(', ')}), so it would exempt nothing`,
+      fix: 'x jobs list --json   # data.depth.queues names what each queue holds',
+    });
+  }
+  return expected;
+}
+
+export async function runDeployVerify(
+  ctx: CommandContext,
+  deps: DeployVerifyDeps = realDeps,
+): Promise<CommandResult> {
+  const root = requireAppRoot('deploy', ctx.cwd).dir;
+  const options = readOptions(ctx);
+  const build = await readBuild(ctx, root);
+  // Read off the env directly: `resolveServices` falls back to the embedded database and would grade
+  // an empty one, so a CI job with no credentials would "pass" having read nothing.
+  const raw = ctx.env['DATABASE_URL'];
+  const databaseUrl = raw === undefined || raw.trim() === '' ? undefined : raw;
+  const expected = databaseUrl === undefined ? undefined : await readExpected(root, options, deps);
+  if (expected !== undefined && expected.findings.length > 0) {
+    return failed(
+      'deploy',
+      msg('cli.deploy.unverified', { build, count: expected.findings.length }),
+      {
+        findings: expected.findings,
+      },
+    );
+  }
+
+  const deadline = deps.clock.monotonic() + options.timeoutMs;
+  const plan: QueuePlan | undefined =
+    databaseUrl === undefined || expected === undefined
+      ? undefined
+      : {
+          expected: expected.queues,
+          open: (statementTimeoutMs) => deps.openQueue(databaseUrl, ctx.env, statementTimeoutMs),
+        };
+  const { wait, read } = await awaitVerdict(options, build, deadline, deps, plan);
+  if (!wait.closed) {
+    return failed('deploy', msg('cli.deploy.unverified', { build, count: 1 }), {
+      findings: [sampleFinding(failureOf(wait.tally, build), wait, build, options)],
+      data: resultData(build, options.windowMs, wait.tally, read?.grade ?? UNGRADED),
+    });
+  }
+
+  const samples = wait.tally.total;
+  const held = { build, windowMs: options.windowMs, samples };
+  if (plan === undefined) {
+    return ok('deploy', msg('cli.deploy.verifiedUngraded', held), {
+      data: resultData(build, options.windowMs, wait.tally, UNGRADED),
+    });
+  }
+  const queues = read?.grade;
+  if (queues === undefined) {
+    return failed('deploy', msg('cli.deploy.unverified', { build, count: 1 }), {
+      findings: [queueReadFinding(read?.lastFailure)],
+      data: resultData(build, options.windowMs, wait.tally, UNGRADED),
+    });
+  }
+  const data = resultData(build, options.windowMs, wait.tally, queues);
+  // A kept grade that says served is not a pass: the read that would confirm it never landed.
+  if (queues.unserved.length === 0 && read?.current !== true) {
+    return failed('deploy', msg('cli.deploy.unverified', { build, count: 1 }), {
+      findings: [queueReadFinding(read?.lastFailure)],
+      data,
+    });
+  }
+  if (queues.unserved.length > 0) {
+    return failed(
+      'deploy',
+      msg('cli.deploy.unverified', { build, count: queues.unserved.length }),
+      {
+        findings: queues.unserved.map((unserved) => unservedFinding(unserved, options.origin)),
+        data,
+      },
+    );
+  }
+  const verified = { ...held, served: queues.served.length, idle: queues.idle.length };
+  return ok('deploy', msg('cli.deploy.verified', verified), { data });
+}

package/src/cmd-deploy.ts

@@ -4,8 +4,14 @@
 
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { loadEnvSchema } from './app-env';
 import { requireAppRoot } from './app-root';
-import { type ComposeStrategy, composeStrategies, readComposeFile } from './cmd-deploy-compose';
+import {
+  type ComposeStrategy,
+  composeStrategies,
+  DEFAULT_IMAGE,
+  readComposeFile,
+} from './cmd-deploy-compose';
 import { readHelmDrainOverrides } from './cmd-deploy-drain';
 import {
   type HelmTarget,
@@ -15,6 +21,7 @@ import {
   readReleaseName,
   readRollout,
 } from './cmd-deploy-helm';
+import { composeEnvPreflight, lastLine, roleLastLogLine } from './cmd-deploy-preflight';
 import { deploySpec } from './cmd-deploy-spec';
 import { runStartFirst, startFirstUp } from './cmd-deploy-start-first';
 import type { CliCommand, CommandContext } from './command';
@@ -344,8 +351,11 @@ const stepLine = (env: Readonly<Record<string, string>>, command: readonly strin
 export const deployCommand: CliCommand = {
   spec: deploySpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
+    if (ctx.args.subcommand === 'verify') {
+      return (await import('./cmd-deploy-verify')).runDeployVerify(ctx);
+    }
     const root = requireAppRoot('deploy', ctx.cwd).dir;
-    const image = flagString(ctx.args, 'image') ?? 'ultimate-app:dev';
+    const image = flagString(ctx.args, 'image') ?? DEFAULT_IMAGE;
     // No "is there a chart?" branch. It threw X_NOT_IMPLEMENTED — "this build does not implement
     // helm" — over a build that implements it completely (`planDeploy` above); what was missing was
     // a FILE, and its fix said to copy it from the framework repository, which `packages/cli`'s
@@ -356,15 +366,12 @@ export const deployCommand: CliCommand = {
     const request = await readDeployRequest(ctx, method, root);
     // Read before the plan, because the plan IS the rollout: which compose roles can start their
     // new container first is a fact of the app's compose file, and a dry run reports it too.
+    const composeText =
+      request.method === 'compose' ? await readComposeFile(composeFileOf(root)) : undefined;
     const plan =
       request.method === 'helm'
         ? planDeploy(image, 'helm', root, request)
-        : planDeploy(
-            image,
-            'compose',
-            root,
-            composeStrategies(await readComposeFile(composeFileOf(root))),
-          );
+        : planDeploy(image, 'compose', root, composeStrategies(composeText));
     // What the helm flags resolved to — the release above all, which is read off `app.config.ts`
     // and so is not something the operator typed. Absent on compose, which has no release.
     const target: { readonly [key: string]: JsonValue } =
@@ -405,11 +412,28 @@ export const deployCommand: CliCommand = {
         ),
       };
     }
+    // Before the first step: a compose step without its env file fails as `exited 1` and says no
+    // more, so the variables it lacks are named here, and nothing runs.
+    const preflight =
+      request.method === 'compose'
+        ? await composeEnvPreflight(root, composeText, ctx.env, await loadEnvSchema(root))
+        : undefined;
+    if (preflight !== undefined) {
+      return {
+        ok: false,
+        command: 'deploy',
+        summary: msg('cli.deploy.plan', { images: 1, roles }),
+        findings: [preflight],
+        data: planJson,
+      };
+    }
     // helm prints its release record (`--output json`), so the report carries helm's own verdict
     // and revision rather than an exit code standing in for one. Compose has no such record.
     let rollout: { readonly [key: string]: JsonValue } = {};
     for (const step of plan.steps) {
       const options = { cwd: root, env: plan.env };
+      // A one-shot's container output is its step's own; a serving role's is read off its log.
+      let output = '';
       // A start-first step is a sequence — list, scale up, wait, stop the old — and reports the
       // command of the sub-step that failed, so the fix line below is still the one to rerun.
       const outcome =
@@ -428,11 +452,20 @@ export const deployCommand: CliCommand = {
           : await ctx.runner(step.command, options).then((result) => {
               if (request.method === 'helm')
                 rollout = { rollout: { ...readRollout(request, result.stdout) } };
+              if (!result.ok) output = lastLine(result);
               return result.ok
                 ? { ok: true as const }
                 : { ok: false as const, code: result.code, command: step.command };
             });
       if (!outcome.ok) {
+        if (output === '' && request.method === 'compose' && !ONE_SHOT_ROLES.includes(step.role)) {
+          output = await roleLastLogLine({
+            base: composeBase(root),
+            role: step.role,
+            runner: ctx.runner,
+            options,
+          });
+        }
         return {
           ok: false,
           command: 'deploy',
@@ -440,7 +473,7 @@ export const deployCommand: CliCommand = {
           findings: [
             {
               code: 'X_DEPLOY_FAILED',
-              cause: `role "${step.role}" step exited ${outcome.code}${cleanupNote(outcome)}`,
+              cause: `role "${step.role}" step exited ${outcome.code}${output === '' ? '' : `: ${output}`}${cleanupNote(outcome)}`,
               fix: `${stepLine(plan.env, outcome.command)}   # run it directly to see the full output`,
               docs: ERROR_DOCS_URL,
             },

package/src/cmd-docs.ts

@@ -6,9 +6,11 @@
 
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { DocEntry, DocHit } from '@ultimat3/manifest';
-import { nearestTopics, scanInstalledDocs, searchDocs } from '@ultimat3/manifest';
+import { nearestTopics, searchDocs } from '@ultimat3/manifest';
 import { DEFAULT_LIMIT, docsSpec } from './cmd-docs-spec';
 import type { CliCommand, CommandContext } from './command';
+import { parseWikiTopic, sectionResult } from './docs-section';
+import { loadDocs, wikiSource } from './docs-sources';
 import { MissingPositionalError } from './errors';
 import { frameworkScopeDir } from './framework-scope';
 import { parseLimitFlag } from './jobs-report';
@@ -38,6 +40,19 @@ const asJson = (hit: DocHit): JsonValue => ({
   score: hit.score,
 });
 
+/**
+ * The tarball ships `wiki/` (its `prepack`), so an install without it is broken in the same way as
+ * one whose CLI cannot see `@ultimat3/core`: the answer is still given from the packages, and the
+ * finding says what is missing rather than leaving the wiki's absence to look like no answer.
+ */
+const noWikiFinding = (): Finding => ({
+  code: 'X_CLI_UNEXPECTED',
+  cause: '@ultimat3/cli ships no wiki/ directory, so no wiki page could be searched',
+  fix: 'bun install && x doctor --json',
+  docs: ERROR_DOCS_URL,
+  at: import.meta.dir,
+});
+
 /** The exact path an agent opens next — package-relative is ambiguous across 29 packages. */
 const locate = (entry: DocEntry): string => `${entry.package}/${entry.source}`;
 
@@ -96,7 +111,11 @@ function codeResult(code: string, query: string): CommandResult {
  * related at all, the honest fallback is the list of packages actually installed — the universe
  * the question could have been about — rather than five topics picked for sharing letters.
  */
-function missResult(query: string, entries: readonly DocEntry[]): CommandResult {
+function missResult(
+  query: string,
+  entries: readonly DocEntry[],
+  findings: readonly Finding[],
+): CommandResult {
   const suggestions = nearestTopics(entries, query);
   const packages = [...new Set(entries.map((entry) => entry.package))].sort();
   const next =
@@ -108,6 +127,7 @@ function missResult(query: string, entries: readonly DocEntry[]): CommandResult
     command: 'docs',
     summary: msg('cli.docs.none', { query }),
     lines: [...next, ...alsoTry()],
+    ...(findings.length > 0 ? { findings } : {}),
     data: { matches: [], suggestions: [...suggestions], packages, query },
   };
 }
@@ -131,6 +151,14 @@ export const docsCommand: CliCommand = {
     const code = CODE_QUERY.exec(query)?.[0];
     if (code !== undefined) return codeResult(code, query);
 
+    // A wiki topic is answered with its whole section, before any package is scanned.
+    const topic = parseWikiTopic(query);
+    if (topic !== undefined) {
+      const wiki = await wikiSource();
+      const section = wiki === undefined ? undefined : await sectionResult(wiki, topic, query);
+      if (section !== undefined) return section;
+    }
+
     const scope = frameworkScopeDir();
     if (scope === undefined) {
       const finding = unresolvedFinding();
@@ -143,20 +171,22 @@ export const docsCommand: CliCommand = {
       };
     }
 
-    const entries = await scanInstalledDocs(scope);
+    const { entries, wiki } = await loadDocs(scope);
+    const findings = wiki === undefined ? [noWikiFinding()] : [];
     // `x jobs list --limit`'s reader, and its `command` parameter exists for exactly this second
     // caller. A local `Number.parseInt` accepted `--limit 1e9` as 1 and answered with one match,
     // and fell silently through to the default for `abc`, `0` and `-3` — a bound other than the one
     // typed, from the same binary that refuses all four one command over.
     const limit = parseLimitFlag(flagString(ctx.args, 'limit'), 'docs') ?? DEFAULT_LIMIT;
     const hits = searchDocs(entries, query, limit);
-    if (hits.length === 0) return missResult(query, entries);
+    if (hits.length === 0) return missResult(query, entries, findings);
 
     return {
       ok: true,
       command: 'docs',
       summary: msg('cli.docs.found', { count: hits.length, query }),
       lines: [...humanLines(hits)],
+      ...(findings.length > 0 ? { findings } : {}),
       data: { matches: hits.map(asJson), suggestions: [], query },
     };
   },