@robodev-ai/runtime 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robodev-ai/runtime",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Robodev project runtime — deploy-file classification, esbuild compile, module loading, schema push, route matching, OpenAPI, handler invocation, Robodev Auth, the socket engine, local file storage, and the offline PDF hop client. Shared by hosted Starbase and `robodev dev`.",
   "type": "module",
   "license": "MIT",

package/src/db-browse.test.ts

@@ -0,0 +1,210 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  BrowseError,
+  asStringArray,
+  attachForeignKeys,
+  buildRowWhere,
+  escapeIlikePattern,
+  isSecretColumn,
+  isTextLikeType,
+  quoteIdent,
+  quoteTable,
+} from "./db-browse.js";
+
+function expectBrowse(fn: () => unknown, status: number, message: RegExp) {
+  assert.throws(fn, (error: unknown) => {
+    assert.ok(error instanceof BrowseError);
+    assert.equal(error.statusCode, status);
+    assert.match(error.message, message);
+    return true;
+  });
+}
+
+test("quoteIdent rejects invalid identifiers and quotes safe names", () => {
+  assert.equal(quoteIdent("users"), '"users"');
+  assert.equal(quoteIdent("user_id"), '"user_id"');
+  expectBrowse(() => quoteIdent("users;drop"), 400, /Invalid identifier/);
+  expectBrowse(() => quoteIdent("foo.bar"), 400, /Invalid identifier/);
+  expectBrowse(() => quoteIdent('foo"bar'), 400, /Invalid identifier/);
+  expectBrowse(() => quoteIdent("1users"), 400, /Invalid identifier/);
+  expectBrowse(() => quoteIdent(""), 400, /Invalid identifier/);
+  expectBrowse(() => quoteTable("public", "items;x"), 400, /Invalid identifier/);
+});
+
+test("secret columns are excluded from search and rejected as filters", () => {
+  for (const name of ["password_hash", "password", "secret", "access_token", "refresh_token"]) {
+    assert.equal(isSecretColumn(name), true);
+    assert.equal(isSecretColumn(name.toUpperCase()), true);
+  }
+  assert.equal(isSecretColumn("email"), false);
+
+  const columns = [
+    { name: "email", type: "text" },
+    { name: "password_hash", type: "text" },
+    { name: "secret", type: "text" },
+  ];
+  const { sql, params } = buildRowWhere(columns, { q: "abc" });
+  assert.match(sql, /"email"::text ILIKE \$1 ESCAPE/);
+  assert.doesNotMatch(sql, /password/i);
+  assert.doesNotMatch(sql, /secret/i);
+  assert.deepEqual(params, ["%abc%"]);
+
+  expectBrowse(
+    () => buildRowWhere(columns, { filters: [{ column: "password_hash", op: "eq", value: "x" }] }),
+    400,
+    /secret column/,
+  );
+  expectBrowse(
+    () =>
+      buildRowWhere(columns, { filters: [{ column: "access_token", op: "contains", value: "x" }] }),
+    400,
+    /secret column/,
+  );
+});
+
+test("buildRowWhere binds values and never concatenates unsanitized identifiers", () => {
+  const columns = [
+    { name: "name", type: "varchar" },
+    { name: "age", type: "int4" },
+    { name: "bio", type: "text" },
+  ];
+
+  const injected = "a'; DROP TABLE users; --";
+  const eq = buildRowWhere(columns, { filters: [{ column: "name", op: "eq", value: injected }] });
+  assert.equal(eq.sql, '"name" = $1');
+  assert.deepEqual(eq.params, [injected]);
+  assert.doesNotMatch(eq.sql, /DROP/i);
+  assert.doesNotMatch(eq.sql, /;/);
+
+  const contains = buildRowWhere(columns, {
+    filters: [{ column: "bio", op: "contains", value: "100%" }],
+  });
+  assert.equal(contains.sql, `"bio"::text ILIKE $1 ESCAPE '\\'`);
+  assert.deepEqual(contains.params, [`%${escapeIlikePattern("100%")}%`]);
+  assert.equal(contains.params[0], "%100\\%%");
+
+  const nulls = buildRowWhere(columns, {
+    filters: [
+      { column: "name", op: "is_null" },
+      { column: "age", op: "is_not_null" },
+    ],
+  });
+  assert.equal(nulls.sql, '"name" IS NULL AND "age" IS NOT NULL');
+  assert.deepEqual(nulls.params, []);
+
+  const combined = buildRowWhere(columns, {
+    q: "rob",
+    filters: [{ column: "age", op: "eq", value: "3" }],
+  });
+  assert.match(combined.sql, /"name"::text ILIKE \$1/);
+  assert.match(combined.sql, /"bio"::text ILIKE \$1/);
+  assert.match(combined.sql, / AND "age" = \$2$/);
+  assert.deepEqual(combined.params, ["%rob%", "3"]);
+
+  expectBrowse(
+    () => buildRowWhere(columns, { filters: [{ column: "name;drop", op: "eq", value: "x" }] }),
+    400,
+    /Invalid identifier/,
+  );
+  expectBrowse(
+    () => buildRowWhere(columns, { filters: [{ column: "missing", op: "eq", value: "x" }] }),
+    400,
+    /Unknown column/,
+  );
+  expectBrowse(
+    () => buildRowWhere(columns, { filters: [{ column: "age", op: "contains", value: "1" }] }),
+    400,
+    /contains is only valid on text columns/,
+  );
+});
+
+test("search skips non-text types and escapes ILIKE wildcards", () => {
+  assert.equal(isTextLikeType("text"), true);
+  assert.equal(isTextLikeType("varchar"), true);
+  assert.equal(isTextLikeType("uuid"), true);
+  assert.equal(isTextLikeType("int4"), false);
+  assert.equal(isTextLikeType("jsonb"), false);
+  assert.equal(isTextLikeType("bytea"), false);
+  assert.equal(isTextLikeType("bool"), false);
+  assert.equal(isTextLikeType("numeric"), false);
+  assert.equal(isTextLikeType("timestamptz"), false);
+
+  const { sql, params } = buildRowWhere(
+    [
+      { name: "name", type: "text" },
+      { name: "meta", type: "jsonb" },
+      { name: "age", type: "int4" },
+      { name: "active", type: "bool" },
+    ],
+    { q: "50%_off" },
+  );
+  assert.match(sql, /"name"::text ILIKE \$1 ESCAPE/);
+  assert.doesNotMatch(sql, /meta|age|active/);
+  assert.equal(params[0], `%${escapeIlikePattern("50%_off")}%`);
+  assert.equal(params[0], "%50\\%\\_off%");
+});
+
+test("attachForeignKeys maps outgoing, composite, cross-schema, and self-ref FKs", () => {
+  const tables = [
+    { schema: "public", name: "users", rowCount: 0, columns: [] },
+    { schema: "public", name: "posts", rowCount: 0, columns: [] },
+    { schema: "billing", name: "invoices", rowCount: 0, columns: [] },
+    { schema: "public", name: "tags", rowCount: 0, columns: [] },
+  ];
+  const attached = attachForeignKeys(tables, [
+    {
+      name: "posts_author_fkey",
+      schema: "public",
+      table: "posts",
+      columns: ["author_id"],
+      referencedSchema: "public",
+      referencedTable: "users",
+      referencedColumns: ["id"],
+    },
+    {
+      name: "invoices_user_fkey",
+      schema: "billing",
+      table: "invoices",
+      columns: ["org_id", "user_id"],
+      referencedSchema: "public",
+      referencedTable: "users",
+      referencedColumns: ["org_id", "id"],
+    },
+    {
+      name: "users_parent_fkey",
+      schema: "public",
+      table: "users",
+      columns: ["parent_id"],
+      referencedSchema: "public",
+      referencedTable: "users",
+      referencedColumns: ["id"],
+    },
+  ]);
+
+  const users = attached.find((table) => table.name === "users");
+  const posts = attached.find((table) => table.name === "posts");
+  const invoices = attached.find((table) => table.schema === "billing");
+  const tags = attached.find((table) => table.name === "tags");
+  assert.ok(users && posts && invoices && tags);
+  assert.equal(users.foreignKeys.length, 1);
+  assert.equal(users.foreignKeys[0]?.name, "users_parent_fkey");
+  assert.deepEqual(posts.foreignKeys[0]?.columns, ["author_id"]);
+  assert.equal(invoices.foreignKeys[0]?.referencedSchema, "public");
+  assert.deepEqual(invoices.foreignKeys[0]?.columns, ["org_id", "user_id"]);
+  assert.deepEqual(tags.foreignKeys, []);
+});
+
+test("asStringArray keeps arrays and parses pg / quoted list leftovers", () => {
+  assert.deepEqual(asStringArray(["org_id", "user_id"]), ["org_id", "user_id"]);
+  assert.deepEqual(asStringArray("{a,b}"), ["a", "b"]);
+  assert.deepEqual(asStringArray("{id}"), ["id"]);
+  assert.deepEqual(asStringArray('"a,b"'), ["a", "b"]);
+  assert.deepEqual(asStringArray('{"org_id","user_id"}'), ["org_id", "user_id"]);
+  assert.deepEqual(asStringArray(""), []);
+  assert.deepEqual(asStringArray("plain"), []);
+  assert.deepEqual(asStringArray(null), []);
+  assert.deepEqual(asStringArray(undefined), []);
+  assert.deepEqual(asStringArray(1), []);
+  assert.deepEqual(asStringArray({ a: 1 }), []);
+});

package/src/db-browse.ts

@@ -0,0 +1,411 @@
+/** Shared read-only Postgres browse for Starbase Databases and `robodev dev` inspect. */
+
+export const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const MAX_LIMIT = 100;
+export const MAX_SEARCH = 200;
+export const SECRET_COLUMNS = new Set([
+  "password_hash",
+  "password",
+  "secret",
+  "access_token",
+  "refresh_token",
+]);
+const TEXT_LIKE_TYPES = new Set([
+  "text",
+  "varchar",
+  "citext",
+  "name",
+  "char",
+  "bpchar",
+  "uuid",
+  "character",
+  "character varying",
+]);
+
+/** Anything with a `pg`-shaped `query`. Keeps this module off a Pool type. */
+export type BrowseQueryable = {
+  query: <R extends Record<string, unknown> = Record<string, unknown>>(
+    sql: string,
+    values?: unknown[],
+  ) => Promise<{ rows: R[]; fields?: Array<{ name: string }> }>;
+};
+
+export class BrowseError extends Error {
+  readonly statusCode: number;
+
+  constructor(statusCode: number, message: string) {
+    super(message);
+    this.name = "BrowseError";
+    this.statusCode = statusCode;
+  }
+}
+
+export type BrowseColumn = {
+  name: string;
+  type: string;
+  notNull: boolean;
+  primaryKey: boolean;
+};
+
+export type BrowseForeignKey = {
+  name: string;
+  schema: string;
+  table: string;
+  columns: string[];
+  referencedSchema: string;
+  referencedTable: string;
+  referencedColumns: string[];
+};
+
+export type BrowseTable = {
+  schema: string;
+  name: string;
+  rowCount: number;
+  columns: BrowseColumn[];
+  foreignKeys: BrowseForeignKey[];
+};
+
+export type BrowseRowFilterOp = "eq" | "contains" | "is_null" | "is_not_null";
+
+export type BrowseRowFilter = {
+  column: string;
+  op: BrowseRowFilterOp;
+  value?: string;
+};
+
+export type BrowseRowsOptions = {
+  q?: string;
+  filters?: BrowseRowFilter[];
+};
+
+export type ResolvedColumn = {
+  name: string;
+  type: string;
+};
+
+export type BrowseRowsResult = {
+  columns: string[];
+  rows: Record<string, unknown>[];
+  total: number;
+};
+
+export function quoteIdent(name: string): string {
+  if (!IDENT.test(name)) {
+    throw new BrowseError(400, `Invalid identifier: ${name}`);
+  }
+  return `"${name.replaceAll('"', '""')}"`;
+}
+
+export function quoteTable(schema: string, table: string): string {
+  return `${quoteIdent(schema)}.${quoteIdent(table)}`;
+}
+
+export function isSecretColumn(name: string): boolean {
+  return SECRET_COLUMNS.has(name.toLowerCase());
+}
+
+export function isTextLikeType(type: string): boolean {
+  const normalized = type.trim().toLowerCase();
+  if (TEXT_LIKE_TYPES.has(normalized)) return true;
+  const base = normalized.split("(")[0]?.trim() ?? normalized;
+  return TEXT_LIKE_TYPES.has(base);
+}
+
+export function escapeIlikePattern(value: string): string {
+  return value.replaceAll("\\", "\\\\").replaceAll("%", "\\%").replaceAll("_", "\\_");
+}
+
+/** Normalize pg array / text-array leftovers to `string[]`. */
+export function asStringArray(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item));
+  }
+  if (typeof value !== "string") return [];
+  const trimmed = value.trim();
+  if (!trimmed) return [];
+  const wrapped =
+    (trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+    (trimmed.startsWith('"') && trimmed.endsWith('"'));
+  if (!wrapped) return [];
+  const inner = trimmed.slice(1, -1);
+  if (!inner) return [];
+  return inner
+    .split(",")
+    .map((part) => part.trim().replace(/^"|"$/g, ""))
+    .filter((part) => part.length > 0);
+}
+
+function schemaRank(schema: string): number {
+  if (schema === "public") return 0;
+  if (schema === "robodev_auth") return 1;
+  return 2;
+}
+
+function serializeValue(value: unknown): unknown {
+  if (value === null || value === undefined) return null;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "bigint") return value.toString();
+  if (Buffer.isBuffer(value)) return value.toString("base64");
+  return value;
+}
+
+function tableKey(schema: string, table: string): string {
+  return `${schema}.${table}`;
+}
+
+export function attachForeignKeys(
+  tables: Array<Omit<BrowseTable, "foreignKeys">>,
+  foreignKeys: BrowseForeignKey[],
+): BrowseTable[] {
+  const byTable = new Map<string, BrowseForeignKey[]>();
+  for (const fk of foreignKeys) {
+    const key = tableKey(fk.schema, fk.table);
+    const list = byTable.get(key) ?? [];
+    list.push(fk);
+    byTable.set(key, list);
+  }
+  return tables.map((table) => ({
+    ...table,
+    foreignKeys: byTable.get(tableKey(table.schema, table.name)) ?? [],
+  }));
+}
+
+export function buildRowWhere(
+  columns: ResolvedColumn[],
+  options: BrowseRowsOptions = {},
+): { sql: string; params: unknown[] } {
+  const params: unknown[] = [];
+  const clauses: string[] = [];
+  const byName = new Map(columns.map((column) => [column.name, column]));
+
+  const q = options.q?.trim().slice(0, MAX_SEARCH) ?? "";
+  if (q) {
+    const searchable = columns.filter(
+      (column) => !isSecretColumn(column.name) && isTextLikeType(column.type),
+    );
+    if (searchable.length === 0) {
+      clauses.push("FALSE");
+    } else {
+      params.push(`%${escapeIlikePattern(q)}%`);
+      const placeholder = `$${params.length}`;
+      const ors = searchable.map(
+        (column) => `${quoteIdent(column.name)}::text ILIKE ${placeholder} ESCAPE '\\'`,
+      );
+      clauses.push(`(${ors.join(" OR ")})`);
+    }
+  }
+
+  for (const filter of options.filters ?? []) {
+    if (!IDENT.test(filter.column)) {
+      throw new BrowseError(400, `Invalid identifier: ${filter.column}`);
+    }
+    if (isSecretColumn(filter.column)) {
+      throw new BrowseError(400, `Cannot filter secret column: ${filter.column}`);
+    }
+    const column = byName.get(filter.column);
+    if (!column) {
+      throw new BrowseError(400, `Unknown column: ${filter.column}`);
+    }
+    const ident = quoteIdent(column.name);
+    if (filter.op === "is_null") {
+      clauses.push(`${ident} IS NULL`);
+      continue;
+    }
+    if (filter.op === "is_not_null") {
+      clauses.push(`${ident} IS NOT NULL`);
+      continue;
+    }
+    if (filter.op === "contains") {
+      if (!isTextLikeType(column.type)) {
+        throw new BrowseError(400, "contains is only valid on text columns");
+      }
+      params.push(`%${escapeIlikePattern(filter.value ?? "")}%`);
+      clauses.push(`${ident}::text ILIKE $${params.length} ESCAPE '\\'`);
+      continue;
+    }
+    if (filter.op === "eq") {
+      params.push(filter.value ?? "");
+      clauses.push(`${ident} = $${params.length}`);
+      continue;
+    }
+    throw new BrowseError(400, `Invalid filter operator: ${String(filter.op)}`);
+  }
+
+  return { sql: clauses.join(" AND "), params };
+}
+
+async function listForeignKeys(db: BrowseQueryable): Promise<BrowseForeignKey[]> {
+  const result = await db.query<{
+    name: string;
+    schema: string;
+    table: string;
+    columns: unknown;
+    referenced_schema: string;
+    referenced_table: string;
+    referenced_columns: unknown;
+  }>(
+    `SELECT
+       con.conname AS name,
+       n.nspname AS schema,
+       c.relname AS table,
+       ARRAY(
+         SELECT a.attname
+         FROM unnest(con.conkey) WITH ORDINALITY AS u(attnum, ord)
+         JOIN pg_attribute a ON a.attrelid = con.conrelid AND a.attnum = u.attnum
+         ORDER BY u.ord
+       )::text[] AS columns,
+       nf.nspname AS referenced_schema,
+       cf.relname AS referenced_table,
+       ARRAY(
+         SELECT a.attname
+         FROM unnest(con.confkey) WITH ORDINALITY AS u(attnum, ord)
+         JOIN pg_attribute a ON a.attrelid = con.confrelid AND a.attnum = u.attnum
+         ORDER BY u.ord
+       )::text[] AS referenced_columns
+     FROM pg_constraint con
+     JOIN pg_class c ON c.oid = con.conrelid
+     JOIN pg_namespace n ON n.oid = c.relnamespace
+     JOIN pg_class cf ON cf.oid = con.confrelid
+     JOIN pg_namespace nf ON nf.oid = cf.relnamespace
+     WHERE con.contype = 'f'
+       AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+       AND n.nspname NOT LIKE 'pg_toast%'
+       AND n.nspname NOT LIKE 'pg_temp%'`,
+  );
+  return result.rows.map((row) => ({
+    name: row.name,
+    schema: row.schema,
+    table: row.table,
+    columns: asStringArray(row.columns),
+    referencedSchema: row.referenced_schema,
+    referencedTable: row.referenced_table,
+    referencedColumns: asStringArray(row.referenced_columns),
+  }));
+}
+
+export async function browseSchema(db: BrowseQueryable): Promise<BrowseTable[]> {
+  const tables = await db.query<{ schemaname: string; tablename: string }>(
+    `SELECT schemaname, tablename
+     FROM pg_catalog.pg_tables
+     WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+       AND schemaname NOT LIKE 'pg_toast%'
+       AND schemaname NOT LIKE 'pg_temp%'`,
+  );
+
+  const listed = [...tables.rows].sort((a, b) => {
+    const rank = schemaRank(a.schemaname) - schemaRank(b.schemaname);
+    if (rank !== 0) return rank;
+    const schemaCmp = a.schemaname.localeCompare(b.schemaname);
+    if (schemaCmp !== 0) return schemaCmp;
+    return a.tablename.localeCompare(b.tablename);
+  });
+
+  const result: Array<Omit<BrowseTable, "foreignKeys">> = [];
+  for (const { schemaname, tablename } of listed) {
+    const cols = await db.query<{
+      column_name: string;
+      data_type: string;
+      udt_name: string;
+      is_nullable: string;
+    }>(
+      `SELECT column_name, data_type, udt_name, is_nullable
+       FROM information_schema.columns
+       WHERE table_schema = $1 AND table_name = $2
+       ORDER BY ordinal_position`,
+      [schemaname, tablename],
+    );
+    const pks = await db.query<{ column_name: string }>(
+      `SELECT a.attname AS column_name
+       FROM pg_index i
+       JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY(i.indkey)
+       JOIN pg_class c ON c.oid = i.indrelid
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE i.indisprimary AND n.nspname = $1 AND c.relname = $2`,
+      [schemaname, tablename],
+    );
+    const pkSet = new Set(pks.rows.map((row) => row.column_name));
+    const count = await db.query<{ count: string }>(
+      `SELECT COUNT(*)::text AS count FROM ${quoteTable(schemaname, tablename)}`,
+    );
+    result.push({
+      schema: schemaname,
+      name: tablename,
+      rowCount: Number(count.rows[0]?.count ?? 0),
+      columns: cols.rows.map((col) => ({
+        name: col.column_name,
+        type: col.udt_name || col.data_type,
+        notNull: col.is_nullable === "NO",
+        primaryKey: pkSet.has(col.column_name),
+      })),
+    });
+  }
+
+  const foreignKeys = await listForeignKeys(db);
+  return attachForeignKeys(result, foreignKeys);
+}
+
+export async function browseRows(
+  db: BrowseQueryable,
+  schema: string,
+  table: string,
+  limit: number,
+  offset: number,
+  options: BrowseRowsOptions = {},
+): Promise<BrowseRowsResult> {
+  if (!IDENT.test(schema)) {
+    throw new BrowseError(400, "Invalid schema name");
+  }
+  if (!IDENT.test(table)) {
+    throw new BrowseError(400, "Invalid table name");
+  }
+  const take = Math.min(Math.max(limit, 1), MAX_LIMIT);
+  const skip = Math.max(offset, 0);
+
+  const exists = await db.query<{ tablename: string }>(
+    `SELECT tablename FROM pg_catalog.pg_tables WHERE schemaname = $1 AND tablename = $2`,
+    [schema, table],
+  );
+  if (!exists.rows[0]) {
+    throw new BrowseError(404, `table "${schema}"."${table}" not found`);
+  }
+
+  const cols = await db.query<{ column_name: string; data_type: string; udt_name: string }>(
+    `SELECT column_name, data_type, udt_name
+     FROM information_schema.columns
+     WHERE table_schema = $1 AND table_name = $2
+     ORDER BY ordinal_position`,
+    [schema, table],
+  );
+  const resolved = cols.rows.map((col) => ({
+    name: col.column_name,
+    type: col.udt_name || col.data_type,
+  }));
+  const where = buildRowWhere(resolved, options);
+  const whereSql = where.sql ? `WHERE ${where.sql}` : "";
+  const quoted = quoteTable(schema, table);
+  const total = await db.query<{ count: string }>(
+    `SELECT COUNT(*)::text AS count FROM ${quoted} ${whereSql}`,
+    where.params,
+  );
+  const limitIndex = where.params.length + 1;
+  const offsetIndex = where.params.length + 2;
+  const data = await db.query(
+    `SELECT * FROM ${quoted} ${whereSql} LIMIT $${limitIndex} OFFSET $${offsetIndex}`,
+    [...where.params, take, skip],
+  );
+  const columns = data.fields?.map((field) => field.name) ?? resolved.map((column) => column.name);
+  return {
+    columns,
+    rows: data.rows.map((row) => {
+      const out: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(row)) {
+        out[key] = serializeValue(value);
+        if (isSecretColumn(key)) {
+          out[key] = "***";
+        }
+      }
+      return out;
+    }),
+    total: Number(total.rows[0]?.count ?? 0),
+  };
+}

package/src/deploy-files.test.ts

@@ -8,6 +8,8 @@ import {
   backendRootFromFiles,
   isAllowedWorkspacePath,
   isDeniedPath,
+  isWorkspaceFrontendSourcePath,
+  validateFrontendSourceFiles,
   mapWorkspaceToDeployFiles,
   apiCompilePaths,
   isAllowedDeployPath,
@@ -73,6 +75,47 @@ test("workspace allowlist persists Tiny paths and still denies .env", () => {
   assert.equal(isDeniedPath("apps/fe/src/main.tsx"), true);
 });
 
+test("isWorkspaceFrontendSourcePath allows Tiny and root FE only", () => {
+  assert.equal(isWorkspaceFrontendSourcePath("apps/fe/package.json"), true);
+  assert.equal(isWorkspaceFrontendSourcePath("apps/fe/src/main.tsx"), true);
+  assert.equal(isWorkspaceFrontendSourcePath("apps/fe/index.html"), true);
+  assert.equal(isWorkspaceFrontendSourcePath("index.html"), true);
+  assert.equal(isWorkspaceFrontendSourcePath("src/main.tsx"), true);
+  assert.equal(isWorkspaceFrontendSourcePath("package.json"), true);
+  assert.equal(isWorkspaceFrontendSourcePath("vite.config.ts"), true);
+  assert.equal(isWorkspaceFrontendSourcePath("tsconfig.app.json"), true);
+  assert.equal(isWorkspaceFrontendSourcePath("packages/be/database.ts"), false);
+  assert.equal(isWorkspaceFrontendSourcePath(".rulesync/rules/overview.md"), false);
+  assert.equal(isWorkspaceFrontendSourcePath("database.ts"), false);
+  assert.equal(isWorkspaceFrontendSourcePath("api/health.ts"), false);
+  assert.equal(isWorkspaceFrontendSourcePath(".env"), false);
+  assert.equal(isWorkspaceFrontendSourcePath("apps/fe/.env"), false);
+  assert.equal(isWorkspaceFrontendSourcePath("apps/fe/node_modules/x.js"), false);
+  assert.equal(isWorkspaceFrontendSourcePath("apps/fe/dist/index.html"), false);
+});
+
+test("validateFrontendSourceFiles has its own 400-file budget and rejects backend", () => {
+  const files = validateFrontendSourceFiles([
+    { path: "apps/fe/package.json", content: "{}" },
+    { path: "apps/fe/src/main.tsx", content: "export {}" },
+  ]);
+  assert.equal(files.length, 2);
+  assert.throws(
+    () => validateFrontendSourceFiles([{ path: "packages/be/database.ts", content: "export {}" }]),
+    (err: { code?: string }) => err.code === "invalid_file",
+  );
+  assert.throws(
+    () =>
+      validateFrontendSourceFiles(
+        Array.from({ length: MAX_FILE_COUNT + 1 }, (_, i) => ({
+          path: `apps/fe/src/f${i}.ts`,
+          content: "export {}",
+        })),
+      ),
+    (err: { code?: string }) => err.code === "too_many_files",
+  );
+});
+
 test("maps packages/be to hosted database.ts and api/**", () => {
   const mapped = mapWorkspaceToDeployFiles([
     { path: "packages/be/database.ts", content: "db" },

package/src/deploy-files.ts

@@ -268,6 +268,69 @@ export function isAllowedWorkspacePath(filePath: string): boolean {
   return isAllowedDeployPath(path);
 }
 
+const ROOT_FE_CONFIG_FILES = new Set([
+  "package.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "tsconfig.json",
+  "vite.config.ts",
+  "vite.config.js",
+  "vite.config.mts",
+  "vite.config.mjs",
+]);
+
+/** Tiny `apps/fe/**` or root FE (`index.html`, `src/**`, Vite/package) — never backend or secrets. */
+export function isWorkspaceFrontendSourcePath(filePath: string): boolean {
+  const path = normalizeDeployPath(filePath);
+  if (!isAllowedWorkspacePath(path)) return false;
+  if (path.startsWith("apps/fe/")) return true;
+  if (path === "index.html" || path.startsWith("src/") || path.startsWith("public/")) return true;
+  if (ROOT_FE_CONFIG_FILES.has(path)) return true;
+  if (isTsconfigName(basename(path)) && !path.includes("/")) return true;
+  return false;
+}
+
+export function validateFrontendSourceFiles(
+  input: { path: string; content: string }[],
+): DeployFile[] {
+  const files: DeployFile[] = [];
+  const seen = new Set<string>();
+  let totalBytes = 0;
+
+  if (input.length > MAX_FILE_COUNT) {
+    fail("too_many_files", `Frontend source may include at most ${MAX_FILE_COUNT} files`);
+  }
+
+  for (const raw of input) {
+    const path = normalizeDeployPath(raw.path);
+    if (
+      isUnsafeDeployPath(path) ||
+      path.length > MAX_PATH_LENGTH ||
+      path.split("/").length > MAX_PATH_DEPTH
+    ) {
+      fail("invalid_file_path", `Invalid file path: ${path}`, path);
+    }
+    if (seen.has(path)) {
+      fail("invalid_file", `Duplicate file path: ${path}`, path);
+    }
+    seen.add(path);
+    if (!isWorkspaceFrontendSourcePath(path)) {
+      fail("invalid_file", `File is not allowed: ${path}`, path);
+    }
+    const storedBytes = Buffer.byteLength(raw.content, "utf8");
+    if (storedBytes > MAX_FILE_BYTES) {
+      fail("file_too_large", `File must be under ${formatLimitMb(MAX_FILE_BYTES)}: ${path}`, path);
+    }
+    totalBytes += storedBytes;
+    if (totalBytes > MAX_TREE_BYTES) {
+      fail("tree_too_large", `Frontend source tree must be under ${formatLimitMb(MAX_TREE_BYTES)}`);
+    }
+    files.push({ path, content: raw.content });
+  }
+
+  return files;
+}
+
 export function mapPackagesBePath(filePath: string): string | null {
   const path = normalizeDeployPath(filePath);
   if (path === "packages/be/database.ts") return LEGACY_DATABASE_FILE;

package/src/index.ts

@@ -31,6 +31,8 @@ export {
   formatLimitMb,
   isAllowedDeployPath,
   isAllowedWorkspacePath,
+  isWorkspaceFrontendSourcePath,
+  validateFrontendSourceFiles,
   isApiPath,
   isBackendTestPath,
   isConfigPath,
@@ -342,3 +344,30 @@ export {
   resolvePdfOptions,
   type ResolvedPdfOptions,
 } from "./local-pdf.js";
+
+export {
+  BrowseError,
+  IDENT,
+  MAX_LIMIT,
+  MAX_SEARCH,
+  SECRET_COLUMNS,
+  asStringArray,
+  attachForeignKeys,
+  browseRows,
+  browseSchema,
+  buildRowWhere,
+  escapeIlikePattern,
+  isSecretColumn,
+  isTextLikeType,
+  quoteIdent,
+  quoteTable,
+  type BrowseColumn,
+  type BrowseForeignKey,
+  type BrowseQueryable,
+  type BrowseRowFilter,
+  type BrowseRowFilterOp,
+  type BrowseRowsOptions,
+  type BrowseRowsResult,
+  type BrowseTable,
+  type ResolvedColumn,
+} from "./db-browse.js";