@flink-app/flink 0.14.3 → 2.0.0-alpha.100

package/spec/ToolExecutor.spec.ts

@@ -0,0 +1,465 @@
+import { z } from "zod";
+import { ToolExecutor } from "../src/ai/ToolExecutor";
+import { FlinkTool, FlinkToolProps, ToolResult } from "../src/ai/FlinkTool";
+import { FlinkContext } from "../src/FlinkContext";
+
+describe("ToolExecutor", () => {
+    let mockCtx: FlinkContext;
+
+    beforeEach(() => {
+        mockCtx = {
+            repos: {},
+            plugins: {},
+        };
+    });
+
+    describe("Input validation", () => {
+        it("should validate input with Zod schema", async () => {
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({
+                    name: z.string(),
+                    age: z.number(),
+                }),
+            };
+
+            const toolFn: FlinkTool<any> = async ({ input }) => {
+                return { success: true, data: { result: "ok" } };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            const result = await executor.execute({ name: "John", age: 30 });
+
+            expect(result.success).toBe(true);
+            if (result.success) {
+                expect(result.data).toEqual({ result: "ok" });
+            }
+        });
+
+        it("should reject invalid input", async () => {
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({
+                    name: z.string(),
+                    age: z.number(),
+                }),
+            };
+
+            const toolFn: FlinkTool<any> = async ({ input }) => {
+                return { success: true, data: { result: "ok" } };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            const result = await executor.execute({ name: "John", age: "invalid" });
+
+            expect(result.success).toBe(false);
+            if (!result.success) {
+                expect(result.error).toContain("Invalid input");
+            }
+        });
+    });
+
+    describe("Output validation", () => {
+        it("should validate output when schema provided", async () => {
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({ input: z.string() }),
+                outputSchema: z.object({ result: z.string() }),
+            };
+
+            const toolFn: FlinkTool<any> = async ({ input }) => {
+                return { success: true, data: { result: "valid" } };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            const result = await executor.execute({ input: "test" });
+
+            expect(result.success).toBe(true);
+            if (result.success) {
+                expect(result.data).toEqual({ result: "valid" });
+            }
+        });
+
+        it("should reject invalid output", async () => {
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({ input: z.string() }),
+                outputSchema: z.object({ result: z.string() }),
+            };
+
+            const toolFn: FlinkTool<any> = async ({ input }) => {
+                return { success: true, data: { result: 123 } }; // Invalid: number instead of string
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            const result = await executor.execute({ input: "test" });
+
+            expect(result.success).toBe(false);
+            if (!result.success) {
+                expect(result.error).toContain("Invalid output");
+            }
+        });
+    });
+
+    describe("Permission checks", () => {
+        it("should allow execution with no permissions", async () => {
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({ input: z.string() }),
+            };
+
+            const toolFn: FlinkTool<any> = async ({ input }) => {
+                return { success: true, data: { result: "ok" } };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            const result = await executor.execute({ input: "test" });
+
+            expect(result.success).toBe(true);
+        });
+
+        it("should check static string permission", async () => {
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({ input: z.string() }),
+                permissions: "admin",
+            };
+
+            const toolFn: FlinkTool<any> = async ({ input }) => {
+                return { success: true, data: { result: "ok" } };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            // Without user - should throw forbidden error
+            await expectAsync(executor.execute({ input: "test" })).toBeRejected();
+
+            // With user but no permission - should throw forbidden error
+            await expectAsync(executor.execute({ input: "test" }, { permissions: [] })).toBeRejected();
+
+            // With user and permission - should succeed
+            const result3 = await executor.execute({ input: "test" }, { permissions: ["admin"] });
+            expect(result3.success).toBe(true);
+        });
+
+        it("should check array of permissions", async () => {
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({ input: z.string() }),
+                permissions: ["admin", "user"],
+            };
+
+            const toolFn: FlinkTool<any> = async ({ input }) => {
+                return { success: true, data: { result: "ok" } };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            // With partial permissions - should throw forbidden error
+            await expectAsync(executor.execute({ input: "test" }, { permissions: ["admin"] })).toBeRejected();
+
+            // With all permissions - should succeed
+            const result2 = await executor.execute({ input: "test" }, { permissions: ["admin", "user"] });
+            expect(result2.success).toBe(true);
+        });
+
+        it("should check function-based permissions", async () => {
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({ value: z.number() }),
+                permissions: (input, user) => {
+                    return input.value > 10 && user?.isAdmin === true;
+                },
+            };
+
+            const toolFn: FlinkTool<any> = async ({ input }) => {
+                return { success: true, data: { result: "ok" } };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            // Invalid input value - should throw forbidden error
+            await expectAsync(executor.execute({ value: 5 }, { user: { isAdmin: true } })).toBeRejected();
+
+            // Not admin - should throw forbidden error
+            await expectAsync(executor.execute({ value: 15 }, { user: { isAdmin: false } })).toBeRejected();
+
+            // Valid - should succeed
+            const result3 = await executor.execute({ value: 15 }, { user: { isAdmin: true } });
+            expect(result3.success).toBe(true);
+        });
+    });
+
+    describe("Error handling", () => {
+        it("should handle tool errors gracefully", async () => {
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({ input: z.string() }),
+            };
+
+            const toolFn: FlinkTool<any> = async ({ input }) => {
+                return {
+                    success: false,
+                    error: "Something went wrong",
+                    code: "TOOL_ERROR",
+                };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            const result = await executor.execute({ input: "test" });
+
+            expect(result.success).toBe(false);
+            if (!result.success) {
+                expect(result.error).toBe("Something went wrong");
+                expect(result.code).toBe("TOOL_ERROR");
+            }
+        });
+
+        it("should catch thrown errors", async () => {
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({ input: z.string() }),
+            };
+
+            const toolFn: FlinkTool<any> = async ({ input }) => {
+                throw new Error("Unexpected error");
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            const result = await executor.execute({ input: "test" });
+
+            expect(result.success).toBe(false);
+            if (!result.success) {
+                expect(result.error).toContain("Tool execution failed");
+                expect(result.code).toBe("EXECUTION_ERROR");
+            }
+        });
+    });
+
+    describe("Tool schema generation", () => {
+        it("should generate tool schema for AI", () => {
+            const toolProps: FlinkToolProps = {
+                id: "get_weather",
+                description: "Get weather for a city",
+                inputSchema: z.object({
+                    city: z.string().describe("City name"),
+                    units: z.enum(["celsius", "fahrenheit"]).optional(),
+                }),
+            };
+
+            const toolFn: FlinkTool<any> = async ({ input }) => {
+                return { success: true, data: {} };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            const schema = executor.getToolSchema();
+
+            expect(schema.name).toBe("get_weather");
+            expect(schema.description).toBe("Get weather for a city");
+            expect(schema.inputSchema).toBeDefined();
+        });
+
+        describe("cross-schema $ref resolution", () => {
+            const allSchemas = {
+                "MyTool.Input": {
+                    $id: "MyTool.Input",
+                    $schema: "http://json-schema.org/draft-07/schema#",
+                    type: "object",
+                    properties: {
+                        id: { type: "string" },
+                        item: { $ref: "Shared.Item" },
+                    },
+                    required: ["id", "item"],
+                },
+                "Shared.Item": {
+                    $id: "Shared.Item",
+                    $schema: "http://json-schema.org/draft-07/schema#",
+                    type: "object",
+                    properties: {
+                        name: { type: "string" },
+                        tag: { $ref: "Shared.Tag" },
+                    },
+                    required: ["name"],
+                },
+                "Shared.Tag": {
+                    $id: "Shared.Tag",
+                    $schema: "http://json-schema.org/draft-07/schema#",
+                    type: "string",
+                    enum: ["foo", "bar"],
+                },
+            };
+
+            it("should resolve cross-schema $refs into $defs", () => {
+                const toolProps: FlinkToolProps = { id: "my-tool", description: "Test" };
+                const toolFn: FlinkTool<any> = async () => ({ success: true, data: {} });
+                const executor = new ToolExecutor(
+                    toolProps,
+                    toolFn,
+                    mockCtx,
+                    { inputSchema: allSchemas["MyTool.Input"], inputTypeHint: "named" },
+                    allSchemas
+                );
+
+                const { inputSchema } = executor.getToolSchema();
+
+                // $ref values should use JSON pointer format
+                expect(inputSchema.properties.item.$ref).toBe("#/$defs/Shared.Item");
+
+                // All transitively referenced schemas should be in $defs
+                expect(inputSchema.$defs).toBeDefined();
+                expect(inputSchema.$defs["Shared.Item"]).toBeDefined();
+                expect(inputSchema.$defs["Shared.Tag"]).toBeDefined();
+
+                // $refs inside $defs should also be rewritten
+                expect(inputSchema.$defs["Shared.Item"].properties.tag.$ref).toBe("#/$defs/Shared.Tag");
+            });
+
+            it("should strip $id and $schema from inlined $defs", () => {
+                const toolProps: FlinkToolProps = { id: "my-tool", description: "Test" };
+                const toolFn: FlinkTool<any> = async () => ({ success: true, data: {} });
+                const executor = new ToolExecutor(
+                    toolProps,
+                    toolFn,
+                    mockCtx,
+                    { inputSchema: allSchemas["MyTool.Input"], inputTypeHint: "named" },
+                    allSchemas
+                );
+
+                const { inputSchema } = executor.getToolSchema();
+
+                expect(inputSchema.$defs["Shared.Item"].$id).toBeUndefined();
+                expect(inputSchema.$defs["Shared.Item"].$schema).toBeUndefined();
+                expect(inputSchema.$defs["Shared.Tag"].$id).toBeUndefined();
+                expect(inputSchema.$defs["Shared.Tag"].$schema).toBeUndefined();
+            });
+
+            it("should strip $id and $schema from root schema", () => {
+                const toolProps: FlinkToolProps = { id: "my-tool", description: "Test" };
+                const toolFn: FlinkTool<any> = async () => ({ success: true, data: {} });
+                const executor = new ToolExecutor(
+                    toolProps,
+                    toolFn,
+                    mockCtx,
+                    { inputSchema: allSchemas["MyTool.Input"], inputTypeHint: "named" },
+                    allSchemas
+                );
+
+                const { inputSchema } = executor.getToolSchema();
+
+                expect(inputSchema.$id).toBeUndefined();
+                expect(inputSchema.$schema).toBeUndefined();
+            });
+
+            it("should return schema unchanged when no cross-schema refs exist", () => {
+                const simpleSchema = {
+                    $id: "Simple.Input",
+                    type: "object",
+                    properties: { name: { type: "string" } },
+                };
+                const toolProps: FlinkToolProps = { id: "simple-tool", description: "Test" };
+                const toolFn: FlinkTool<any> = async () => ({ success: true, data: {} });
+                const executor = new ToolExecutor(
+                    toolProps,
+                    toolFn,
+                    mockCtx,
+                    { inputSchema: simpleSchema, inputTypeHint: "named" },
+                    allSchemas
+                );
+
+                const { inputSchema } = executor.getToolSchema();
+
+                expect(inputSchema.$defs).toBeUndefined();
+            });
+        });
+    });
+
+    describe("Result formatting for AI", () => {
+        it("should format success result as JSON", () => {
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({ input: z.string() }),
+            };
+
+            const toolFn: FlinkTool<any> = async ({ input }) => {
+                return { success: true, data: {} };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            const result: ToolResult<any> = {
+                success: true,
+                data: { temperature: 22, conditions: "sunny" },
+            };
+
+            const formatted = executor.formatResultForAI(result);
+
+            expect(formatted).toBe('{"temperature":22,"conditions":"sunny"}');
+        });
+
+        it("should format error result with code", () => {
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({ input: z.string() }),
+            };
+
+            const toolFn: FlinkTool<any> = async ({ input }) => {
+                return { success: true, data: {} };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            const result: ToolResult<any> = {
+                success: false,
+                error: "API rate limit exceeded",
+                code: "RATE_LIMIT",
+            };
+
+            const formatted = executor.formatResultForAI(result);
+
+            expect(formatted).toBe("Error: API rate limit exceeded (RATE_LIMIT)");
+        });
+
+        it("should format error result without code", () => {
+            const toolProps: FlinkToolProps = {
+                id: "test_tool",
+                description: "Test tool",
+                inputSchema: z.object({ input: z.string() }),
+            };
+
+            const toolFn: FlinkTool<any> = async ({ input }) => {
+                return { success: true, data: {} };
+            };
+
+            const executor = new ToolExecutor(toolProps, toolFn, mockCtx);
+
+            const result: ToolResult<any> = {
+                success: false,
+                error: "Something went wrong",
+            };
+
+            const formatted = executor.formatResultForAI(result);
+
+            expect(formatted).toBe("Error: Something went wrong");
+        });
+    });
+});

package/spec/TypeScriptCompiler.spec.ts

@@ -26,7 +26,7 @@ describe("TypeScriptCompiler", () => {
         expect(generatedFile.getText()).toContain(`import { autoRegisteredHandlers, HttpMethod } from "@flink-app/flink"`);
         expect(generatedFile.getText()).toContain(`import * as GetCar_0 from "../src/handlers/GetCar"`);
         expect(generatedFile.getText()).toContain(`export const handlers =`);
-        expect(generatedFile.getText()).toContain(`{handler: GetCar_0, assumedHttpMethod: HttpMethod.get}`);
+        expect(generatedFile.getText()).toContain(`{handler: GetCar_0, assumedHttpMethod: HttpMethod.get, __file: "src/handlers/GetCar.ts"}`);
         // expect(generatedFile.getText()).toContain(
         //   `{routeProps: PostCar_5.Route, handlerFn: PostCar_5.default, assumedHttpMethod: HttpMethod.post}`
         // );