feat(query): database query engine, scripts, and unified collection views

[kooksee]

Summary

• Add unified database.query engine (structured IR + SQL builders) for records, meta types, asset libraries, and system DBs (filter/sort/aggregate + DSL).
• Add Button field + sandboxed scripts (database.button.run, database.script.run) and action writes via collection.applyActions.
• Add Settings tools: Script Explorer and Query Explorer (Dataview-style DSL).
• Unify database collection views on SQL path via useDatabaseSqlCollectionQuery.
• Add Formula fields (computed at display time).
• Add Page Query Block (/query) — live DSL queries embedded in pages.
• Add Page Button Block (/button) — script actions with table result display for query returns.

Test plan

• packages/client tests: record-query, record-query-dsl, collection-actions, database-script, formula-expression
• apps/web tests (146 passing, including backup-service)
• packages/client, packages/core, apps/desktop lint
• Desktop package build (LOCAL_ONLY=true npm run package)
• Manual: Query Explorer, Script Explorer, Button field, Page Query/Button blocks
• @colanode/ui lint (pre-existing debt on main as well)

Follow-ups (post-merge)

• Markdown import for colanode-query / colanode-button blocks
• Page Button result persistence (in-memory lastRun today)
• DSL OR support; configurable result columns on blocks

[gemini-code-assist]

Code Review

This pull request introduces a unified local query engine and Query DSL parser for Colanode databases, alongside a sandboxed scripting environment for button fields and ad-hoc scripts. Key additions include the database.query handler, a sandbox runner, and the Query and Script Explorer UI components. While the implementation is comprehensive, several critical security and stability issues must be addressed. These include a SQL injection vulnerability via unsanitized aggregate aliases, a sandbox escape risk through unblocked global APIs, potential cache corruption from shallow-frozen row snapshots, and potential TypeError crashes in the collection action handler due to missing null guards on concurrent node updates.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The alias property in RecordQueryAggregate is inserted directly into the SQL query string without sanitization or escaping. Since this query can be constructed from user-controlled inputs (such as the Query DSL or client-side API calls), this presents a SQL injection vulnerability.

To prevent this, ensure that the alias is sanitized or escaped (for example, by doubling any double quotes inside the identifier to conform to SQLite's identifier escaping rules, or restricting it to alphanumeric characters and underscores).

const buildAggregateSqlExpression = (
  aggregate: RecordQueryAggregate,
  fields: Record<string, FieldAttributes>
): string | null => {
  const rawAlias = aggregate.alias ?? `${aggregate.fn}_${aggregate.fieldId}`;
  const alias = rawAlias.replace(/"/g, '""');

  if (aggregate.fn === 'count' && aggregate.fieldId === '*') {
    return `COUNT(*) as "${alias}"`;
  }

  const field = fields[aggregate.fieldId];
  if (!field) {
    return null;
  }

  const selector = buildFieldSqlSelector(field);
  const fn = aggregate.fn.toUpperCase();

  if (aggregate.fn === 'count') {
    return `COUNT(${selector}) as "${alias}"`;
  }

  return `${fn}(CAST(${selector} AS REAL)) as "${alias}"`;
};

[gemini-code-assist]

The sandbox implementation uses AsyncFunction directly in the client worker but does not restrict access to powerful global APIs like fetch, WebSocket, XMLHttpRequest, or indexedDB. A malicious script could easily exfiltrate sensitive database records to an external server.

To mitigate this, shadow these sensitive globals by declaring them as arguments to the AsyncFunction and passing undefined when invoking the runner.

Suggested change

	const wrappedScript = `"use strict";\n${script}`;
	let runner: (...args: unknown[]) => Promise<unknown>;
	try {
	runner = new AsyncFunction('ctx', wrappedScript);
	} catch (error) {
	throw new ScriptSandboxError(
	error instanceof Error ? error.message : 'Invalid script syntax.'
	);
	}
	const blockedGlobals = ['fetch', 'WebSocket', 'XMLHttpRequest', 'indexedDB', 'caches', 'self'];
	const wrappedScript = `"use strict";\n${script}`;
	let runner: (...args: unknown[]) => Promise<unknown>;
	try {
	runner = new AsyncFunction('ctx', ...blockedGlobals, wrappedScript);
	} catch (error) {
	throw new ScriptSandboxError(
	error instanceof Error ? error.message : 'Invalid script syntax.'
	);
	}

[gemini-code-assist]

The buildRowSnapshot function returns a direct reference to attributes.fields (which belongs to the live Yjs/TanStack DB node attributes). Since Object.freeze is shallow, a sandboxed script can directly mutate the nested fields of ctx.record or ctx.row (e.g., ctx.record.fields.status.value = 'mutated'), bypassing the mutation system and corrupting the client-side cache.

To ensure the sandbox is truly read-only, deep clone the fields and attributes before passing them to the context.

Suggested change

	const buildRowSnapshot = (
	id: string,
	attributes: RecordAttributes | PageAttributes
	): ScriptRowSnapshot => {
	const fields: Record<string, FieldValue> =
	attributes.type === 'page'
	? (attributes.fields ?? {})
	: attributes.fields;
	return {
	id,
	name: attributes.name,
	fields,
	nodeType: attributes.type,
	};
	};
	const buildRowSnapshot = (
	id: string,
	attributes: RecordAttributes | PageAttributes
	): ScriptRowSnapshot => {
	const fields: Record<string, FieldValue> =
	attributes.type === 'page'
	? (attributes.fields ?? {})
	: attributes.fields;
	return {
	id,
	name: attributes.name,
	fields: JSON.parse(JSON.stringify(fields)),
	nodeType: attributes.type,
	};
	};

[gemini-code-assist]

The updater function passed to updateNode does not check if current is null or undefined. If the node is concurrently deleted or not found, this will throw a TypeError when attempting to read or spread current.

Add a defensive guard to return early if current is not defined.

      const result = await workspace.nodes.updateNode<RecordAttributes>(
        input.nodeId,
        (current) => {
          if (!current) {
            return current;
          }

          return applyCollectionFieldActions(
            current,
            input.actions,
            database.fields ?? {}
          );
        }
      );

[gemini-code-assist]

The updater function passed to updateNode does not check if current is null or undefined. If the node is concurrently deleted or not found, attempting to spread current or access current.fields will throw a TypeError.

Add a defensive guard to return early if current is not defined.

      const result = await workspace.nodes.updateNode<PageAttributes>(
        input.nodeId,
        (current) => {
          if (!current) {
            return current;
          }

          const withFields = {
            ...current,
            fields: current.fields ?? {},
          };

          return applyCollectionFieldActions(
            withFields,
            input.actions,
            database.fields ?? {}
          );
        }
      );