@fuzdev/fuz_app 0.1.0

package/dist/env/resolve.js

@@ -0,0 +1,200 @@
+/**
+ * Environment variable `$$VAR$$` resolution suite.
+ *
+ * Resolves `$$VAR$$` references in strings and object trees,
+ * scans configs for references, and validates/formats missing vars.
+ *
+ * The double-dollar bookending syntax is:
+ * - Visually distinct from shell `$VAR` syntax
+ * - Unambiguous about variable boundaries
+ * - Easy to grep: `grep '\$\$'`
+ * - Fails loud if accidentally shell-processed (`$$`=PID in shell)
+ *
+ * @module
+ */
+/**
+ * Pattern for environment variable references: `$$VAR$$`.
+ */
+const ENV_VAR_PATTERN = /\$\$([A-Za-z_][A-Za-z0-9_]*)\$\$/g;
+/**
+ * Resolve environment variable references in a string.
+ *
+ * Uses `$$VAR$$` syntax (bookended double-dollar signs).
+ * Only resolves variables that are actually set in the environment.
+ * Unset variables are left as-is for clear error messages.
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param value - string that may contain `$$VAR$$` references
+ * @returns string with env vars resolved
+ */
+export const resolve_env_vars = (runtime, value) => {
+    return value.replace(ENV_VAR_PATTERN, (match, name) => {
+        const resolved = runtime.env_get(name);
+        // leave unresolved for the validation phase to report
+        return resolved !== undefined ? resolved : match;
+    });
+};
+/**
+ * Check if a string contains unresolved env var references.
+ *
+ * @param value - string to check
+ * @returns `true` if string contains `$$VAR$$` patterns
+ */
+export const has_env_vars = (value) => {
+    // use a fresh regex to avoid global regex lastIndex state issues
+    return /\$\$[A-Za-z_][A-Za-z0-9_]*\$\$/.test(value);
+};
+/**
+ * Get list of env var names referenced in a string.
+ *
+ * @param value - string to scan
+ * @returns array of variable names (without `$$` delimiters)
+ */
+export const get_env_var_names = (value) => {
+    const names = [];
+    let match;
+    // reset regex lastIndex since it's global
+    const pattern = new RegExp(ENV_VAR_PATTERN.source, 'g');
+    while ((match = pattern.exec(value)) !== null) {
+        names.push(match[1]);
+    }
+    return names;
+};
+/**
+ * Resolve env vars in an object's string values (shallow).
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param obj - object with string values
+ * @returns new object with env vars resolved
+ */
+export const resolve_env_vars_in_object = (runtime, obj) => {
+    const result = { ...obj };
+    for (const [key, value] of Object.entries(result)) {
+        if (typeof value === 'string') {
+            result[key] = resolve_env_vars(runtime, value);
+        }
+    }
+    return result;
+};
+/**
+ * Resolve env vars and throw if any are missing/empty.
+ *
+ * Use this for values that must be present.
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param value - string with `$$VAR$$` references
+ * @param context - description for error message (e.g., `"target.host"`)
+ * @returns resolved string
+ * @throws error if any referenced env var is missing or empty
+ */
+export const resolve_env_vars_required = (runtime, value, context) => {
+    const missing = [];
+    const result = value.replace(ENV_VAR_PATTERN, (match, name) => {
+        const resolved = runtime.env_get(name);
+        if (resolved === undefined || resolved === '') {
+            missing.push(name);
+            return match; // keep original for error message
+        }
+        return resolved;
+    });
+    if (missing.length > 0) {
+        throw new Error(`Missing required environment variable(s) for ${context}: ${missing.join(', ')}`);
+    }
+    return result;
+};
+/**
+ * Recursively scan an object for `$$VAR$$` env var references.
+ *
+ * Walks all string values in the object tree and extracts env var names
+ * with their path context for error reporting.
+ *
+ * @param obj - object to scan (typically a config)
+ * @returns array of env var references with paths
+ */
+export const scan_env_vars = (obj) => {
+    const refs = [];
+    scan_recursive(obj, '', refs);
+    return refs;
+};
+/**
+ * Recursive helper for `scan_env_vars`.
+ */
+const scan_recursive = (value, path, refs) => {
+    if (typeof value === 'string') {
+        const names = get_env_var_names(value);
+        for (const name of names) {
+            refs.push({ name, path });
+        }
+    }
+    else if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            scan_recursive(value[i], `${path}[${i}]`, refs);
+        }
+    }
+    else if (value !== null && typeof value === 'object') {
+        for (const [key, v] of Object.entries(value)) {
+            const new_path = path ? `${path}.${key}` : key;
+            scan_recursive(v, new_path, refs);
+        }
+    }
+    // primitives (number, boolean, null, undefined) have no env vars
+};
+/**
+ * Validate that all referenced env vars exist in the environment.
+ *
+ * Returns all missing refs (including duplicates by name). Grouping
+ * and deduplication is handled by `format_missing_env_vars` at display time.
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param refs - env var references from `scan_env_vars`
+ * @returns validation result with any missing vars
+ */
+export const validate_env_vars = (runtime, refs) => {
+    let missing = null;
+    for (const ref of refs) {
+        const value = runtime.env_get(ref.name);
+        if (value === undefined || value === '') {
+            (missing ??= []).push(ref);
+        }
+    }
+    return missing === null ? { ok: true, missing: null } : { ok: false, missing };
+};
+/**
+ * Format missing env vars error message.
+ *
+ * Groups refs by variable name so each missing var is shown once
+ * with all paths where it's referenced.
+ *
+ * @param missing - missing env var references (may contain duplicate names)
+ * @param options - formatting options
+ * @returns formatted error message for display
+ */
+export const format_missing_env_vars = (missing, options) => {
+    const lines = ['Missing required environment variables:', ''];
+    // group by variable name, preserving insertion order
+    const grouped = new Map();
+    for (const ref of missing) {
+        let paths = grouped.get(ref.name);
+        if (!paths) {
+            paths = [];
+            grouped.set(ref.name, paths);
+        }
+        paths.push(ref.path);
+    }
+    for (const [name, paths] of grouped) {
+        lines.push(`  ${name} - used in ${paths.join(', ')}`);
+    }
+    lines.push('');
+    const env_file = options?.env_file;
+    if (env_file) {
+        lines.push(`Loaded from: ${env_file}`);
+        lines.push(`Add these to your ${env_file} file.`);
+        if (options.setup_hint) {
+            lines.push(options.setup_hint);
+        }
+    }
+    else {
+        lines.push('Use --env_file to load environment variables from a file.');
+    }
+    return lines.join('\n');
+};

package/dist/hono_context.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Hono context variable augmentation for fuz_app.
+ *
+ * Cross-cutting shared vocabulary — defines the Hono `ContextVariableMap`
+ * variables used by auth, http, server, and testing modules.
+ *
+ * Import this module once in your app to get type-safe access to
+ * `auth_session_id`, `request_context`, and `credential_type` on the Hono context.
+ *
+ * In practice, this is auto-loaded by `app_server.ts` (side-effect import)
+ * and transitively by auth middleware modules that import `CREDENTIAL_TYPE_KEY`.
+ * Consumers don't need a manual import unless bypassing the standard server assembly.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import type { RequestContext } from './auth/request_context.js';
+/** The credential types that can authenticate a request. */
+export declare const CREDENTIAL_TYPES: readonly ["session", "api_token", "daemon_token"];
+/** Credential type — how a request was authenticated. */
+export declare const CredentialType: z.ZodEnum<{
+    session: "session";
+    api_token: "api_token";
+    daemon_token: "daemon_token";
+}>;
+export type CredentialType = z.infer<typeof CredentialType>;
+/** Hono context variable name for the credential type. */
+export declare const CREDENTIAL_TYPE_KEY = "credential_type";
+declare module 'hono' {
+    interface ContextVariableMap {
+        /** Resolved client IP, set by the trusted proxy middleware. */
+        client_ip: string;
+        auth_session_id: string | null;
+        request_context: RequestContext | null;
+        validated_input: unknown;
+        validated_params: unknown;
+        validated_query: unknown;
+        /** How the request was authenticated (`'session'`, `'api_token'`, or `'daemon_token'`). */
+        credential_type: CredentialType | null;
+        /**
+         * Pending fire-and-forget effects for this request (audit logs, usage tracking, etc.).
+         * Initialized by `create_app_server`. In test mode (`await_pending_effects: true`),
+         * all effects are awaited before the response returns.
+         */
+        pending_effects: Array<Promise<void>>;
+    }
+}
+//# sourceMappingURL=hono_context.d.ts.map

package/dist/hono_context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono_context.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/hono_context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAE9D,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,mDAAoD,CAAC;AAElF,yDAAyD;AACzD,eAAO,MAAM,cAAc;;;;EAA2B,CAAC;AACvD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,0DAA0D;AAC1D,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD,OAAO,QAAQ,MAAM,CAAC;IACrB,UAAU,kBAAkB;QAC3B,+DAA+D;QAC/D,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;QACvC,eAAe,EAAE,OAAO,CAAC;QACzB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,eAAe,EAAE,OAAO,CAAC;QACzB,2FAA2F;QAC3F,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;QACvC;;;;WAIG;QACH,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;KACtC;CACD"}

package/dist/hono_context.js

@@ -0,0 +1,22 @@
+/**
+ * Hono context variable augmentation for fuz_app.
+ *
+ * Cross-cutting shared vocabulary — defines the Hono `ContextVariableMap`
+ * variables used by auth, http, server, and testing modules.
+ *
+ * Import this module once in your app to get type-safe access to
+ * `auth_session_id`, `request_context`, and `credential_type` on the Hono context.
+ *
+ * In practice, this is auto-loaded by `app_server.ts` (side-effect import)
+ * and transitively by auth middleware modules that import `CREDENTIAL_TYPE_KEY`.
+ * Consumers don't need a manual import unless bypassing the standard server assembly.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** The credential types that can authenticate a request. */
+export const CREDENTIAL_TYPES = ['session', 'api_token', 'daemon_token'];
+/** Credential type — how a request was authenticated. */
+export const CredentialType = z.enum(CREDENTIAL_TYPES);
+/** Hono context variable name for the credential type. */
+export const CREDENTIAL_TYPE_KEY = 'credential_type';

package/dist/http/common_routes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Common route spec factories for fuz_app consumers.
+ *
+ * Generic HTTP route factories with no auth-domain dependencies.
+ * Auth-aware route factories (account status) live in `auth/account_routes.ts`.
+ *
+ * @module
+ */
+import type { RouteSpec } from './route_spec.js';
+import type { AppSurface } from './surface.js';
+/**
+ * Create a public health check route spec.
+ *
+ * Infrastructure endpoint for uptime monitors and load balancers.
+ * Bootstrap availability is exposed via `/api/account/status` instead.
+ *
+ * @returns a single health check route spec
+ */
+export declare const create_health_route_spec: () => RouteSpec;
+/** Options for the authenticated server status route. */
+export interface ServerStatusOptions {
+    /** Application version string. */
+    version: string;
+    /** Returns milliseconds since server start. */
+    get_uptime_ms: () => number;
+}
+/**
+ * Create an authenticated server status route spec.
+ *
+ * Returns version and uptime. Unlike the public health check,
+ * this requires authentication.
+ *
+ * @param options - version and uptime source
+ * @returns route spec for `GET /api/server/status`
+ */
+export declare const create_server_status_route_spec: (options: ServerStatusOptions) => RouteSpec;
+/** Options for the surface explorer route. */
+export interface SurfaceRouteOptions {
+    /** The generated app surface to serve. */
+    surface: AppSurface;
+}
+/**
+ * Create an authenticated route spec that serves the `AppSurface` as JSON.
+ *
+ * Surface data reveals API structure (routes, auth, schemas), so this
+ * requires authentication like the server status route.
+ *
+ * @param options - surface data source
+ * @returns route spec for `GET /api/surface`
+ */
+export declare const create_surface_route_spec: (options: SurfaceRouteOptions) => RouteSpec;
+//# sourceMappingURL=common_routes.d.ts.map

package/dist/http/common_routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/common_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,QAAO,SAQ1C,CAAC;AAEH,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IACnC,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,GAAI,SAAS,mBAAmB,KAAG,SAQ7E,CAAC;AAEH,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IACnC,0CAA0C;IAC1C,OAAO,EAAE,UAAU,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,mBAAmB,KAAG,SAWvE,CAAC"}

package/dist/http/common_routes.js

@@ -0,0 +1,65 @@
+/**
+ * Common route spec factories for fuz_app consumers.
+ *
+ * Generic HTTP route factories with no auth-domain dependencies.
+ * Auth-aware route factories (account status) live in `auth/account_routes.ts`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Create a public health check route spec.
+ *
+ * Infrastructure endpoint for uptime monitors and load balancers.
+ * Bootstrap availability is exposed via `/api/account/status` instead.
+ *
+ * @returns a single health check route spec
+ */
+export const create_health_route_spec = () => ({
+    method: 'GET',
+    path: '/health',
+    auth: { type: 'none' },
+    handler: (c) => c.json({ status: 'ok' }),
+    description: 'Health check',
+    input: z.null(),
+    output: z.strictObject({ status: z.literal('ok') }),
+});
+/**
+ * Create an authenticated server status route spec.
+ *
+ * Returns version and uptime. Unlike the public health check,
+ * this requires authentication.
+ *
+ * @param options - version and uptime source
+ * @returns route spec for `GET /api/server/status`
+ */
+export const create_server_status_route_spec = (options) => ({
+    method: 'GET',
+    path: '/api/server/status',
+    auth: { type: 'authenticated' },
+    handler: (c) => c.json({ version: options.version, uptime_ms: options.get_uptime_ms() }),
+    description: 'Server version and uptime',
+    input: z.null(),
+    output: z.looseObject({ version: z.string(), uptime_ms: z.number() }),
+});
+/**
+ * Create an authenticated route spec that serves the `AppSurface` as JSON.
+ *
+ * Surface data reveals API structure (routes, auth, schemas), so this
+ * requires authentication like the server status route.
+ *
+ * @param options - surface data source
+ * @returns route spec for `GET /api/surface`
+ */
+export const create_surface_route_spec = (options) => ({
+    method: 'GET',
+    path: '/api/surface',
+    auth: { type: 'authenticated' },
+    handler: (c) => c.json(options.surface),
+    description: 'Application surface (routes, middleware, schemas)',
+    input: z.null(),
+    output: z.looseObject({
+        routes: z.array(z.looseObject({})),
+        middleware: z.array(z.looseObject({})),
+    }),
+});

package/dist/http/db_routes.d.ts

@@ -0,0 +1,57 @@
+/**
+ * API route specs for database administration.
+ *
+ * Generic PostgreSQL table browser using `information_schema`.
+ * Provides: list tables, view columns/rows (paginated), delete rows by PK, health check.
+ *
+ * @module
+ */
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { Db, DbType } from '../db/db.js';
+import { type RouteSpec } from './route_spec.js';
+/**
+ * Table metadata from `information_schema`.
+ */
+export interface TableInfo {
+    table_name: string;
+}
+/**
+ * Table info with row count.
+ */
+export interface TableWithCount {
+    name: string;
+    row_count: number;
+}
+/**
+ * Primary key constraint info.
+ */
+export interface PrimaryKeyInfo {
+    column_name: string;
+}
+/**
+ * Column metadata from `information_schema`.
+ */
+export interface ColumnInfo {
+    column_name: string;
+    data_type: string;
+    is_nullable: string;
+}
+/**
+ * Per-factory configuration for db routes.
+ */
+export interface DbRouteOptions {
+    db_type: DbType;
+    db_name: string;
+    /** Optional callback to provide app-specific stats in the health response. */
+    extra_stats?: (db: Db) => Promise<Record<string, unknown>>;
+    /** Optional logger for server-side diagnostics (e.g. FK violation details). */
+    log?: Logger;
+}
+/**
+ * Create the db API route specs.
+ *
+ * @param options - route configuration (db_type, db_name, extra_stats)
+ * @returns route specs for database administration
+ */
+export declare const create_db_route_specs: (options: DbRouteOptions) => Array<RouteSpec>;
+//# sourceMappingURL=db_routes.d.ts.map

package/dist/http/db_routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/db_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,EAAE,EAAE,MAAM,EAAC,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAmB,KAAK,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAWjE;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3D,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,SAAS,cAAc,KAAG,KAAK,CAAC,SAAS,CAqN9E,CAAC"}

package/dist/http/db_routes.js

@@ -0,0 +1,176 @@
+/**
+ * API route specs for database administration.
+ *
+ * Generic PostgreSQL table browser using `information_schema`.
+ * Provides: list tables, view columns/rows (paginated), delete rows by PK, health check.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { get_route_params } from './route_spec.js';
+import { ApiError, ForeignKeyError, ERROR_TABLE_NOT_FOUND, ERROR_TABLE_NO_PRIMARY_KEY, ERROR_ROW_NOT_FOUND, ERROR_FOREIGN_KEY_VIOLATION, } from './error_schemas.js';
+import { assert_valid_sql_identifier, VALID_SQL_IDENTIFIER } from '../db/sql_identifier.js';
+/**
+ * Create the db API route specs.
+ *
+ * @param options - route configuration (db_type, db_name, extra_stats)
+ * @returns route specs for database administration
+ */
+export const create_db_route_specs = (options) => {
+    const { db_type, db_name, extra_stats, log } = options;
+    return [
+        {
+            method: 'GET',
+            path: '/health',
+            auth: { type: 'keeper' },
+            description: 'Database health and stats',
+            input: z.null(),
+            output: z.looseObject({ connected: z.boolean() }),
+            errors: { 503: ApiError },
+            handler: async (c, route) => {
+                try {
+                    await route.db.query('SELECT 1');
+                    const table_result = await route.db.query(`SELECT COUNT(*) as count FROM information_schema.tables WHERE table_schema = 'public'`);
+                    const table_count = table_result[0] ? parseInt(table_result[0].count, 10) : 0;
+                    const stats = extra_stats ? await extra_stats(route.db) : {};
+                    return c.json({
+                        connected: true,
+                        type: db_type,
+                        name: db_name,
+                        table_count,
+                        ...stats,
+                    });
+                }
+                catch (err) {
+                    log?.error('Database health check failed:', err);
+                    return c.json({
+                        connected: false,
+                        type: db_type,
+                        error: 'database_connection_failed',
+                    }, 503);
+                }
+            },
+        },
+        {
+            method: 'GET',
+            path: '/tables',
+            auth: { type: 'keeper' },
+            description: 'List public tables with row counts',
+            input: z.null(),
+            output: z.looseObject({ tables: z.array(z.object({ name: z.string(), row_count: z.number() })) }),
+            handler: async (c, route) => {
+                const table_names = await route.db.query(`SELECT table_name FROM information_schema.tables
+					 WHERE table_schema = 'public'
+					 ORDER BY table_name`);
+                const tables = [];
+                for (const { table_name } of table_names) {
+                    // eslint-disable-next-line no-await-in-loop
+                    const result = await route.db.query_one(`SELECT COUNT(*) as count FROM "${assert_valid_sql_identifier(table_name)}"`);
+                    tables.push({
+                        name: table_name,
+                        row_count: result ? parseInt(result.count, 10) : 0,
+                    });
+                }
+                return c.json({ tables });
+            },
+        },
+        {
+            method: 'GET',
+            path: '/tables/:name',
+            auth: { type: 'keeper' },
+            description: 'Get table columns and rows (paginated)',
+            params: z.strictObject({ name: z.string().regex(VALID_SQL_IDENTIFIER) }),
+            input: z.null(),
+            errors: { 404: z.looseObject({ error: z.literal(ERROR_TABLE_NOT_FOUND) }) },
+            output: z.looseObject({
+                columns: z.array(z.object({ column_name: z.string(), data_type: z.string(), is_nullable: z.string() })),
+                rows: z.array(z.record(z.string(), z.unknown())),
+                total: z.number(),
+                offset: z.number(),
+                limit: z.number(),
+                primary_key: z.string().nullable(),
+            }),
+            handler: async (c, route) => {
+                const { name } = get_route_params(c);
+                const offset = Math.max(0, parseInt(c.req.query('offset') ?? '0', 10) || 0);
+                const limit = Math.min(1000, Math.max(1, parseInt(c.req.query('limit') ?? '100', 10) || 100));
+                const exists = await route.db.query_one(`SELECT table_name FROM information_schema.tables
+					 WHERE table_schema = 'public' AND table_name = $1`, [name]);
+                if (!exists) {
+                    return c.json({ error: ERROR_TABLE_NOT_FOUND }, 404);
+                }
+                const columns = await route.db.query(`SELECT column_name, data_type, is_nullable
+					 FROM information_schema.columns
+					 WHERE table_schema = 'public' AND table_name = $1
+					 ORDER BY ordinal_position`, [name]);
+                const count_result = await route.db.query_one(`SELECT COUNT(*) as count FROM "${assert_valid_sql_identifier(name)}"`);
+                const total = count_result ? parseInt(count_result.count, 10) : 0;
+                const pk_info = await route.db.query_one(`SELECT kcu.column_name
+					 FROM information_schema.table_constraints tc
+					 JOIN information_schema.key_column_usage kcu
+					   ON tc.constraint_name = kcu.constraint_name
+					   AND tc.table_schema = kcu.table_schema
+					 WHERE tc.constraint_type = 'PRIMARY KEY'
+					   AND tc.table_schema = 'public'
+					   AND tc.table_name = $1
+					 LIMIT 1`, [name]);
+                const primary_key = pk_info?.column_name ?? null;
+                const rows = await route.db.query(`SELECT * FROM "${assert_valid_sql_identifier(name)}" LIMIT $1 OFFSET $2`, [limit, offset]);
+                return c.json({ columns, rows, total, offset, limit, primary_key });
+            },
+        },
+        {
+            method: 'DELETE',
+            path: '/tables/:name/rows/:id',
+            auth: { type: 'keeper' },
+            description: 'Delete a row by primary key',
+            params: z.strictObject({
+                name: z.string().regex(VALID_SQL_IDENTIFIER),
+                id: z.string(),
+            }),
+            input: z.null(),
+            output: z.looseObject({ success: z.boolean() }),
+            errors: {
+                404: z.looseObject({
+                    error: z.enum([ERROR_TABLE_NOT_FOUND, ERROR_ROW_NOT_FOUND]),
+                }),
+                409: ForeignKeyError,
+            },
+            handler: async (c, route) => {
+                const { name, id } = get_route_params(c);
+                const exists = await route.db.query_one(`SELECT table_name FROM information_schema.tables
+					 WHERE table_schema = 'public' AND table_name = $1`, [name]);
+                if (!exists) {
+                    return c.json({ error: ERROR_TABLE_NOT_FOUND }, 404);
+                }
+                const pk_info = await route.db.query_one(`SELECT kcu.column_name
+					 FROM information_schema.table_constraints tc
+					 JOIN information_schema.key_column_usage kcu
+					   ON tc.constraint_name = kcu.constraint_name
+					   AND tc.table_schema = kcu.table_schema
+					 WHERE tc.constraint_type = 'PRIMARY KEY'
+					   AND tc.table_schema = 'public'
+					   AND tc.table_name = $1
+					 LIMIT 1`, [name]);
+                if (!pk_info) {
+                    return c.json({ error: ERROR_TABLE_NO_PRIMARY_KEY }, 400);
+                }
+                try {
+                    const result = await route.db.query(`DELETE FROM "${assert_valid_sql_identifier(name)}" WHERE "${assert_valid_sql_identifier(pk_info.column_name)}" = $1 RETURNING *`, [id]);
+                    if (result.length === 0) {
+                        return c.json({ error: ERROR_ROW_NOT_FOUND }, 404);
+                    }
+                    return c.json({ success: true });
+                }
+                catch (err) {
+                    if (err instanceof Error && 'code' in err && err.code === '23503') {
+                        const pg_err = err;
+                        log?.warn('Foreign key violation:', pg_err.detail, pg_err.constraint);
+                        return c.json({ error: ERROR_FOREIGN_KEY_VIOLATION }, 409);
+                    }
+                    throw err;
+                }
+            },
+        },
+    ];
+};