bunsane 0.1.4 → 0.2.0

package/endpoints/archetypes.ts

@@ -0,0 +1,362 @@
+import { getSerializedMetadataStorage } from "../core/metadata";
+import { findIndicatorComponentName } from "../studio/utils";
+import db from "../database";
+import type {
+    StudioArcheTypeQueryParams,
+    StudioArcheTypeResponse,
+    DeleteArcheTypeEntitiesRequest,
+    DeleteResponse,
+    ArcheTypeField,
+    ArcheTypeEntityRecord,
+} from "./types";
+
+export async function handleStudioArcheTypeRecordsRequest(
+    archeTypeName: string,
+    params: StudioArcheTypeQueryParams = {}
+): Promise<Response> {
+    const limit = Math.min(Math.max(params.limit ?? 50, 1), 1000);
+    const offset = Math.max(params.offset ?? 0, 0);
+    const searchTerm = params.search ?? "";
+    const includeDeleted = params.include_deleted ?? false;
+
+    // Conditional filter: include or exclude soft-deleted rows
+    const deletedFilter = includeDeleted ? "" : "AND c.deleted_at IS NULL";
+    const deletedFilterBare = includeDeleted ? "" : "AND deleted_at IS NULL";
+
+    try {
+        const metadataStorage = getSerializedMetadataStorage();
+        const archeTypeFields: ArcheTypeField[] | undefined =
+            metadataStorage.archeTypes[archeTypeName];
+
+        if (!archeTypeFields || archeTypeFields.length === 0) {
+            return new Response(
+                JSON.stringify({
+                    error: `ArcheType '${archeTypeName}' not found`,
+                }),
+                {
+                    status: 404,
+                    headers: { "Content-Type": "application/json" },
+                }
+            );
+        }
+
+        const indicatorComponentName = findIndicatorComponentName(
+            archeTypeName,
+            archeTypeFields
+        );
+
+        if (!indicatorComponentName) {
+            return new Response(
+                JSON.stringify({
+                    error: `No indicator component found for '${archeTypeName}'`,
+                }),
+                {
+                    status: 400,
+                    headers: { "Content-Type": "application/json" },
+                }
+            );
+        }
+
+        const requiredComponentNames = archeTypeFields
+            .filter((field) => !field?.nullable)
+            .map((field) => field.componentName);
+
+        const allComponentNames = archeTypeFields.map(
+            (field) => field.componentName
+        );
+
+        const requiredComponentCount = requiredComponentNames.length;
+
+        let entityIdsResult: { entity_id: string }[];
+        let totalResult: { count: number }[];
+
+        const batchSize = limit * 3;
+        let currentOffset = offset;
+        const validEntities: ArcheTypeEntityRecord[] = [];
+        let hasMoreData = true;
+
+        while (validEntities.length < limit && hasMoreData) {
+            if (searchTerm) {
+                const searchPattern = `%${searchTerm}%`;
+                const componentNamePlaceholders = requiredComponentNames
+                    .map((_, index) => `$${index + 2}`)
+                    .join(", ");
+
+                entityIdsResult = await db.unsafe(
+                    `SELECT entity_id FROM (
+                         SELECT entity_id, MAX(created_at) as max_created_at
+                         FROM components
+                         WHERE TRUE ${deletedFilterBare}
+                         GROUP BY entity_id
+                         HAVING COUNT(DISTINCT CASE WHEN name IN (${componentNamePlaceholders}) THEN name END) = $${
+                        requiredComponentNames.length + 2
+                    }
+                     ) archetype_entities
+                     WHERE entity_id IN (
+                         SELECT DISTINCT entity_id
+                         FROM components
+                         WHERE TRUE ${deletedFilterBare}
+                         AND (
+                             data::text ILIKE $1
+                             OR id::text ILIKE $1
+                             OR entity_id::text ILIKE $1
+                         )
+                     )
+                     ORDER BY max_created_at DESC
+                     LIMIT $${requiredComponentNames.length + 3} OFFSET $${
+                        requiredComponentNames.length + 4
+                    }`,
+                    [
+                        searchPattern,
+                        ...requiredComponentNames,
+                        requiredComponentCount,
+                        batchSize,
+                        currentOffset,
+                    ]
+                );
+            } else {
+                entityIdsResult = await db.unsafe(
+                    `SELECT entity_id FROM (
+                         SELECT c.entity_id, MAX(c.created_at) as max_created_at
+                         FROM components c
+                         WHERE c.name = $1
+                         ${deletedFilter}
+                         GROUP BY c.entity_id
+                         ORDER BY max_created_at DESC
+                         LIMIT $2 OFFSET $3
+                     ) sub`,
+                    [indicatorComponentName, batchSize, currentOffset]
+                );
+            }
+
+            if (entityIdsResult.length === 0) {
+                hasMoreData = false;
+                break;
+            }
+
+            const entityIds = entityIdsResult.map((row) => row.entity_id);
+
+            const entityIdPlaceholders = entityIds
+                .map((_, index) => `$${index + 1}`)
+                .join(", ");
+            const componentNameStartIndex = entityIds.length + 1;
+            const componentNamePlaceholders = allComponentNames
+                .map((_, index) => `$${componentNameStartIndex + index}`)
+                .join(", ");
+
+            const componentsResult = await db.unsafe(
+                `SELECT c.entity_id, c.name, c.data
+                 FROM components c
+                 WHERE c.entity_id IN (${entityIdPlaceholders})
+                 AND c.name IN (${componentNamePlaceholders})
+                 ${deletedFilter}`,
+                [...entityIds, ...allComponentNames]
+            );
+
+            // When including deleted, also fetch entity-level deleted_at
+            let entityDeletedMap = new Map<string, string | null>();
+            if (includeDeleted) {
+                const entitiesResult = await db.unsafe(
+                    `SELECT id, deleted_at FROM entities WHERE id IN (${entityIdPlaceholders})`,
+                    entityIds
+                );
+                for (const row of entitiesResult) {
+                    entityDeletedMap.set(
+                        row.id as string,
+                        (row.deleted_at as string) ?? null
+                    );
+                }
+            }
+
+            const entityComponentsMap = new Map<string, Map<string, unknown>>();
+
+            for (const row of componentsResult) {
+                const entityId = row.entity_id as string;
+                const componentName = row.name as string;
+                const componentData = row.data as unknown;
+
+                if (!entityComponentsMap.has(entityId)) {
+                    entityComponentsMap.set(entityId, new Map());
+                }
+                entityComponentsMap
+                    .get(entityId)!
+                    .set(componentName, componentData);
+            }
+
+            for (const entityId of entityIds) {
+                const componentsMap = entityComponentsMap.get(entityId);
+
+                if (!componentsMap) {
+                    continue;
+                }
+
+                const allRequiredComponentsPresent =
+                    requiredComponentNames.every((name) =>
+                        componentsMap.has(name)
+                    );
+
+                if (allRequiredComponentsPresent) {
+                    const componentsObject: Record<string, unknown> = {};
+                    for (const [name, data] of componentsMap) {
+                        componentsObject[name] = data;
+                    }
+
+                    const record: ArcheTypeEntityRecord = {
+                        entityId,
+                        components: componentsObject,
+                    };
+
+                    if (includeDeleted) {
+                        record.deleted_at = entityDeletedMap.get(entityId) ?? null;
+                    }
+
+                    validEntities.push(record);
+
+                    if (validEntities.length >= limit) {
+                        break;
+                    }
+                }
+            }
+
+            currentOffset += batchSize;
+
+            if (entityIdsResult.length < batchSize) {
+                hasMoreData = false;
+            }
+        }
+
+        if (searchTerm) {
+            const searchPattern = `%${searchTerm}%`;
+            const componentNamePlaceholders = requiredComponentNames
+                .map((_, index) => `$${index + 2}`)
+                .join(", ");
+
+            totalResult = await db.unsafe(
+                `SELECT COUNT(DISTINCT c.entity_id) as count
+                 FROM components c
+                 WHERE TRUE ${deletedFilter}
+                 AND (
+                     c.data::text ILIKE $1
+                     OR c.id::text ILIKE $1
+                     OR c.entity_id::text ILIKE $1
+                 )
+                 AND c.entity_id IN (
+                     SELECT entity_id
+                     FROM components
+                     WHERE TRUE ${deletedFilterBare}
+                     GROUP BY entity_id
+                     HAVING COUNT(DISTINCT CASE WHEN name IN (${componentNamePlaceholders}) THEN name END) = $${
+                    requiredComponentNames.length + 2
+                }
+                 )`,
+                [
+                    searchPattern,
+                    ...requiredComponentNames,
+                    requiredComponentCount,
+                ]
+            );
+        } else {
+            totalResult = await db.unsafe(
+                `SELECT COUNT(DISTINCT c.entity_id) as count
+                 FROM components c
+                 WHERE c.name = $1
+                 ${deletedFilter}`,
+                [indicatorComponentName]
+            );
+        }
+
+        const total = Number(totalResult[0]?.count ?? 0);
+
+        const responseData: StudioArcheTypeResponse = {
+            name: archeTypeName,
+            fields: archeTypeFields,
+            indicatorComponent: indicatorComponentName,
+            entities: validEntities,
+            total,
+            limit,
+            offset,
+        };
+
+        return new Response(JSON.stringify(responseData), {
+            headers: { "Content-Type": "application/json" },
+        });
+    } catch (error) {
+        const errorMessage =
+            error instanceof Error ? error.message : "Unknown error";
+        return new Response(
+            JSON.stringify({
+                error: `Failed to fetch archetype data: ${errorMessage}`,
+            }),
+            {
+                status: 500,
+                headers: { "Content-Type": "application/json" },
+            }
+        );
+    }
+}
+
+export async function handleStudioArcheTypeDeleteRequest(
+    archeTypeName: string,
+    requestBody: DeleteArcheTypeEntitiesRequest
+): Promise<Response> {
+    const { entityIds } = requestBody;
+
+    if (!entityIds || !Array.isArray(entityIds) || entityIds.length === 0) {
+        return new Response(
+            JSON.stringify({
+                error: "entityIds array is required and must not be empty",
+            }),
+            {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            }
+        );
+    }
+
+    try {
+        const idPlaceholders = entityIds
+            .map((_, index) => `$${index + 1}`)
+            .join(", ");
+
+        // Delete in correct order to avoid foreign key constraint violations
+        // 1. Delete from entity_components (junction table)
+        await db.unsafe(
+            `DELETE FROM entity_components WHERE entity_id IN (${idPlaceholders})`,
+            entityIds
+        );
+
+        // 2. Delete from components
+        await db.unsafe(
+            `DELETE FROM components WHERE entity_id IN (${idPlaceholders})`,
+            entityIds
+        );
+
+        // 3. Delete from entities
+        await db.unsafe(
+            `DELETE FROM entities WHERE id IN (${idPlaceholders})`,
+            entityIds
+        );
+
+        const responseData: DeleteResponse = {
+            success: true,
+            deletedCount: entityIds.length,
+            message: `Successfully deleted ${entityIds.length} entity(ies) of type ${archeTypeName}`,
+        };
+
+        return new Response(JSON.stringify(responseData), {
+            headers: { "Content-Type": "application/json" },
+        });
+    } catch (error) {
+        const errorMessage =
+            error instanceof Error ? error.message : "Unknown error";
+        return new Response(
+            JSON.stringify({
+                error: `Failed to delete entities: ${errorMessage}`,
+            }),
+            {
+                status: 500,
+                headers: { "Content-Type": "application/json" },
+            }
+        );
+    }
+}

package/endpoints/components.ts

@@ -0,0 +1,58 @@
+import db from "../database";
+import { GenerateTableName } from "../database/DatabaseHelper";
+import type { ComponentTypeInfo, StudioComponentsResponse } from "./types";
+
+export async function handleStudioComponentsRequest(): Promise<Response> {
+    try {
+        // Get distinct component names with entity counts
+        const componentRows = await db`
+            SELECT name, COUNT(DISTINCT entity_id) as entity_count
+            FROM components
+            WHERE deleted_at IS NULL
+            GROUP BY name
+            ORDER BY entity_count DESC
+        `;
+
+        const components: ComponentTypeInfo[] = [];
+
+        for (const row of componentRows) {
+            const name = row.name as string;
+            const entityCount = Number(row.entity_count);
+            const partitionTable = GenerateTableName(name);
+
+            // Get sample row to discover JSONB field shape
+            const sampleResult = await db.unsafe(
+                `SELECT data FROM components WHERE name = $1 AND deleted_at IS NULL AND data IS NOT NULL LIMIT 1`,
+                [name]
+            );
+
+            let fields: string[] = [];
+            if (sampleResult.length > 0 && sampleResult[0].data) {
+                const sampleData = sampleResult[0].data;
+                if (typeof sampleData === "object" && sampleData !== null) {
+                    fields = Object.keys(sampleData as Record<string, unknown>);
+                }
+            }
+
+            components.push({ name, entityCount, partitionTable, fields });
+        }
+
+        const responseData: StudioComponentsResponse = { components };
+
+        return new Response(JSON.stringify(responseData), {
+            headers: { "Content-Type": "application/json" },
+        });
+    } catch (error) {
+        const errorMessage =
+            error instanceof Error ? error.message : "Unknown error";
+        return new Response(
+            JSON.stringify({
+                error: `Failed to fetch components: ${errorMessage}`,
+            }),
+            {
+                status: 500,
+                headers: { "Content-Type": "application/json" },
+            }
+        );
+    }
+}

package/endpoints/entity.ts

@@ -0,0 +1,80 @@
+import db from "../database";
+import type { EntityInspectorResponse } from "./types";
+
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export async function handleEntityInspectorRequest(
+    entityId: string
+): Promise<Response> {
+    if (!entityId || !UUID_REGEX.test(entityId)) {
+        return new Response(
+            JSON.stringify({ error: "Invalid entity ID format. Expected a UUID." }),
+            {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            }
+        );
+    }
+
+    try {
+        const entityResult = await db`
+            SELECT id, created_at, updated_at, deleted_at
+            FROM entities
+            WHERE id = ${entityId}
+        `;
+
+        if (entityResult.length === 0) {
+            return new Response(
+                JSON.stringify({ error: `Entity '${entityId}' not found` }),
+                {
+                    status: 404,
+                    headers: { "Content-Type": "application/json" },
+                }
+            );
+        }
+
+        const entity = entityResult[0];
+
+        // Fetch ALL components for this entity (including soft-deleted)
+        const componentsResult = await db`
+            SELECT id, name, type_id, data, created_at, updated_at, deleted_at
+            FROM components
+            WHERE entity_id = ${entityId}
+            ORDER BY name ASC, created_at ASC
+        `;
+
+        const responseData: EntityInspectorResponse = {
+            entity: {
+                id: entity.id as string,
+                created_at: entity.created_at as string,
+                updated_at: entity.updated_at as string,
+                deleted_at: (entity.deleted_at as string) ?? null,
+            },
+            components: componentsResult.map((row: Record<string, unknown>) => ({
+                id: row.id as string,
+                name: row.name as string,
+                type_id: row.type_id as string,
+                data: row.data as unknown,
+                created_at: row.created_at as string,
+                updated_at: row.updated_at as string,
+                deleted_at: (row.deleted_at as string) ?? null,
+            })),
+        };
+
+        return new Response(JSON.stringify(responseData), {
+            headers: { "Content-Type": "application/json" },
+        });
+    } catch (error) {
+        const errorMessage =
+            error instanceof Error ? error.message : "Unknown error";
+        return new Response(
+            JSON.stringify({
+                error: `Failed to fetch entity: ${errorMessage}`,
+            }),
+            {
+                status: 500,
+                headers: { "Content-Type": "application/json" },
+            }
+        );
+    }
+}

package/endpoints/index.ts

@@ -0,0 +1,27 @@
+import {
+    handleStudioTableRequest,
+    handleStudioTableDeleteRequest,
+    handleGetTables,
+} from "./tables";
+import {
+    handleStudioArcheTypeRecordsRequest,
+    handleStudioArcheTypeDeleteRequest,
+} from "./archetypes";
+import { handleEntityInspectorRequest } from "./entity";
+import { handleStudioStatsRequest } from "./stats";
+import { handleStudioComponentsRequest } from "./components";
+import { handleStudioQueryRequest } from "./query";
+
+const studioEndpoint = {
+    handleStudioTableRequest,
+    handleStudioArcheTypeRecordsRequest,
+    handleStudioTableDeleteRequest,
+    handleStudioArcheTypeDeleteRequest,
+    handleEntityInspectorRequest,
+    handleStudioStatsRequest,
+    handleStudioComponentsRequest,
+    handleStudioQueryRequest,
+    getTables: handleGetTables,
+};
+
+export default studioEndpoint;

package/endpoints/query.ts

@@ -0,0 +1,93 @@
+import db from "../database";
+import type { StudioQueryRequest, StudioQueryResponse } from "./types";
+
+const FORBIDDEN_KEYWORDS = /\b(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|TRUNCATE|GRANT|REVOKE|COPY|EXECUTE|DO)\b/i;
+const MAX_ROWS = 500;
+const QUERY_TIMEOUT_MS = 10_000;
+
+export async function handleStudioQueryRequest(
+    requestBody: StudioQueryRequest
+): Promise<Response> {
+    // Only allow in non-production
+    if (process.env.NODE_ENV === "production") {
+        return new Response(
+            JSON.stringify({ error: "Query runner is disabled in production" }),
+            {
+                status: 403,
+                headers: { "Content-Type": "application/json" },
+            }
+        );
+    }
+
+    const { sql } = requestBody;
+
+    if (!sql || typeof sql !== "string" || sql.trim().length === 0) {
+        return new Response(
+            JSON.stringify({ error: "SQL query is required" }),
+            {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            }
+        );
+    }
+
+    const trimmed = sql.trim();
+
+    // Block write operations
+    if (FORBIDDEN_KEYWORDS.test(trimmed)) {
+        return new Response(
+            JSON.stringify({
+                error: "Only read-only (SELECT) queries are allowed",
+            }),
+            {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            }
+        );
+    }
+
+    // Enforce LIMIT if not present
+    const hasLimit = /\bLIMIT\b/i.test(trimmed);
+    const queryToRun = hasLimit ? trimmed : `${trimmed} LIMIT ${MAX_ROWS}`;
+
+    try {
+        const startTime = Date.now();
+
+        const result = await Promise.race([
+            db.unsafe(queryToRun),
+            new Promise<never>((_, reject) =>
+                setTimeout(
+                    () => reject(new Error("Query timed out")),
+                    QUERY_TIMEOUT_MS
+                )
+            ),
+        ]);
+
+        const duration = Date.now() - startTime;
+
+        const rows = Array.isArray(result) ? result : [];
+        const columns =
+            rows.length > 0 ? Object.keys(rows[0] as Record<string, unknown>) : [];
+
+        const responseData: StudioQueryResponse = {
+            columns,
+            rows: rows.slice(0, MAX_ROWS) as Record<string, unknown>[],
+            rowCount: rows.length,
+            duration,
+        };
+
+        return new Response(JSON.stringify(responseData), {
+            headers: { "Content-Type": "application/json" },
+        });
+    } catch (error) {
+        const errorMessage =
+            error instanceof Error ? error.message : "Unknown error";
+        return new Response(
+            JSON.stringify({ error: errorMessage }),
+            {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            }
+        );
+    }
+}

package/endpoints/stats.ts

@@ -0,0 +1,76 @@
+import db from "../database";
+import { getSerializedMetadataStorage } from "../core/metadata";
+import type { StudioStatsResponse, ComponentTypeStats, ArcheTypeStats } from "./types";
+
+export async function handleStudioStatsRequest(): Promise<Response> {
+    try {
+        // Run entity counts and component type counts in parallel
+        const [activeCountResult, deletedCountResult, componentTypesResult] =
+            await Promise.all([
+                db`SELECT COUNT(*) as count FROM entities WHERE deleted_at IS NULL`,
+                db`SELECT COUNT(*) as count FROM entities WHERE deleted_at IS NOT NULL`,
+                db`SELECT name, COUNT(*) as count FROM components WHERE deleted_at IS NULL GROUP BY name ORDER BY count DESC`,
+            ]);
+
+        const activeCount = Number(activeCountResult[0]?.count ?? 0);
+        const deletedCount = Number(deletedCountResult[0]?.count ?? 0);
+
+        const componentTypes: ComponentTypeStats[] = componentTypesResult.map(
+            (row: Record<string, unknown>) => ({
+                name: row.name as string,
+                count: Number(row.count),
+            })
+        );
+
+        // Derive archetype stats from metadata + component counts
+        const metadata = getSerializedMetadataStorage();
+        const componentCountMap = new Map(
+            componentTypes.map((ct) => [ct.name, ct.count])
+        );
+
+        const archetypes: ArcheTypeStats[] = [];
+        for (const [name, fields] of Object.entries(metadata.archeTypes)) {
+            const requiredComponents = fields.filter((f) => !f.nullable);
+            const indicatorComponent =
+                requiredComponents.find((f) =>
+                    f.componentName.endsWith("Tag")
+                ) ?? requiredComponents[0];
+
+            archetypes.push({
+                name,
+                entityCount: indicatorComponent
+                    ? componentCountMap.get(indicatorComponent.componentName) ?? 0
+                    : 0,
+                componentCount: fields.length,
+            });
+        }
+
+        archetypes.sort((a, b) => b.entityCount - a.entityCount);
+
+        const responseData: StudioStatsResponse = {
+            entities: {
+                active: activeCount,
+                deleted: deletedCount,
+                total: activeCount + deletedCount,
+            },
+            componentTypes,
+            archetypes,
+        };
+
+        return new Response(JSON.stringify(responseData), {
+            headers: { "Content-Type": "application/json" },
+        });
+    } catch (error) {
+        const errorMessage =
+            error instanceof Error ? error.message : "Unknown error";
+        return new Response(
+            JSON.stringify({
+                error: `Failed to fetch stats: ${errorMessage}`,
+            }),
+            {
+                status: 500,
+                headers: { "Content-Type": "application/json" },
+            }
+        );
+    }
+}