@preply/ds-ai-core 11.1.0

package/src/utils/define-tool.ts

@@ -0,0 +1,67 @@
+import * as z from 'zod';
+
+/**
+ * Resolves callback parameter types based on which schemas a tool defines.
+ * Uses `[T] extends [never]` (wrapped in tuple) instead of `T extends never`
+ * to prevent TypeScript from collapsing the conditional via distributive behavior.
+ *
+ * - Both Arguments and Options are `never` -> callback takes no parameters
+ * - Only Options defined                   -> callback takes parsed Options
+ * - Only Arguments defined                 -> callback takes parsed Arguments
+ * - Both defined                           -> callback takes merged Arguments & Options
+ */
+type CallbackParameters<
+    Arguments extends z.AnyZodObject = never,
+    Options extends z.AnyZodObject = never,
+> = [Arguments] extends [never]
+    ? [Options] extends [never]
+        ? []
+        : [z.input<Options>]
+    : [Options] extends [never]
+      ? [z.input<Arguments>]
+      : [z.input<Arguments> & z.input<Options>];
+
+/**
+ * Shape of a single AI tool definition.
+ *
+ * A tool has a CLI-style interface with positional `arguments` and named
+ * `options`, both validated at runtime via Zod schemas. The `callback`
+ * receives the parsed (and type-safe) values and must return an array of
+ * output lines that are surfaced to the calling agent.
+ */
+export type Tool<
+    Arguments extends z.AnyZodObject = never,
+    Options extends z.AnyZodObject = never,
+> = {
+    /** The tool name. Used when using as MCP tool. */
+    name: string;
+    /** The tool description. Used when using as MCP tool and displayed as a help message to CLI command. */
+    description: string;
+    /** Positional arguments schema. Omit if the tool takes no positional args. */
+    arguments?: Arguments;
+    /** Named options/flags schema. Omit if the tool takes no options. */
+    options?: Options;
+    /** Executes the tool logic; returns output lines shown to the agent. */
+    callback: (...args: CallbackParameters<Arguments, Options>) => string[];
+};
+
+/**
+ * Identity helper that infers the generic types from the tool object literal,
+ * giving full type-safety on `callback` params without manual type annotations.
+ *
+ * @example
+ * ```ts
+ * const myTool = defineTool({
+ *     name: 'greet',
+ *     description: 'Say hello',
+ *     arguments: z.object({ name: z.string() }),
+ *     callback: (args) => [`Hello, ${args.name}!`], // args is typed automatically
+ * });
+ * ```
+ */
+export function defineTool<
+    Arguments extends z.AnyZodObject = never,
+    Options extends z.AnyZodObject = never,
+>(tool: Tool<Arguments, Options>) {
+    return tool;
+}

package/src/utils/format-list.ts

@@ -0,0 +1,38 @@
+import { stringify } from 'yaml';
+
+/**
+ * Formats a list of objects into readable string.
+ *
+ * @example
+ * ```
+ * const list = [
+ *     { name: 'John', age: 30 },
+ *     { name: 'Jane', age: 25 },
+ * ];
+ * const formattedList = formatList(list);
+ * ```
+ *
+ * returns:
+ * ```
+ * ---
+ * name: John
+ * age: 30
+ * ---
+ * name: Jane
+ * age: 25
+ * ---
+ * ```
+ */
+export function formatList(list: unknown[]) {
+    if (list.length === 0) return '';
+
+    const delimiter = '\n---\n';
+
+    return ['', ...list.map(item => stringify(item).trim()), ''].join(delimiter).trim();
+}
+
+export function formatListInline(list: unknown[]) {
+    if (list.length === 0) return '';
+
+    return list.join(', ');
+}

package/src/utils/md.ts

@@ -0,0 +1,12 @@
+import * as tsmd from 'ts-markdown-builder';
+import { stringify } from 'yaml';
+
+function frontMatter(object: Record<string, unknown>): string {
+    if (Object.keys(object).length === 0) return '';
+
+    const yaml = stringify(object).trim();
+
+    return [tsmd.horizontalRule, yaml, tsmd.horizontalRule].join('\n');
+}
+
+export const md = { ...tsmd, frontMatter, comment: (comment: string) => `<!-- ${comment} -->` };

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "extends": "../../tsconfig.json",
+    "include": ["src", "package.json"],
+    "exclude": ["node_modules", "dist"],
+    "compilerOptions": {
+        "resolveJsonModule": true,
+        "module": "esnext",
+        "target": "esnext",
+        "types": ["vitest/globals", "node"]
+    }
+}

package/vite.config.ts

@@ -0,0 +1,23 @@
+import { builtinModules } from 'node:module';
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+import macros from 'unplugin-macros/vite';
+
+const nodeBuiltins = builtinModules.flatMap(m => [m, `node:${m}`]);
+
+export default defineConfig({
+    plugins: [dts({ exclude: ['vite.config.ts'], entryRoot: 'src' }), macros()],
+    build: {
+        target: 'esnext',
+        lib: {
+            entry: 'src/index.ts',
+            formats: ['es'],
+        },
+        rolldownOptions: {
+            external: nodeBuiltins,
+            output: {
+                entryFileNames: '[name].js',
+            },
+        },
+    },
+});