@funkai/prompts 0.1.0

package/src/engine.test.ts

@@ -0,0 +1,44 @@
+import { Liquid } from "liquidjs";
+import { describe, expect, it } from "vitest";
+
+import { createEngine, engine } from "@/engine.js";
+
+describe("createEngine", () => {
+  it("should return a Liquid instance", () => {
+    const eng = createEngine("/tmp/test-partials");
+    expect(eng).toBeInstanceOf(Liquid);
+  });
+
+  it("should render basic variable expressions", () => {
+    const eng = createEngine("/tmp/test-partials");
+    const result = eng.parseAndRenderSync("Hello {{ name }}", { name: "World" });
+    expect(result).toBe("Hello World");
+  });
+
+  it("should merge custom options with defaults", () => {
+    const eng = createEngine("/tmp/test-partials", {
+      cache: false,
+      strictFilters: false,
+    });
+    // Should not throw on unknown filter when strictFilters is disabled
+    const result = eng.parseAndRenderSync("{{ name | nonexistent }}", { name: "test" });
+    expect(result).toBe("test");
+  });
+});
+
+describe("engine", () => {
+  it("should be a Liquid instance", () => {
+    expect(engine).toBeInstanceOf(Liquid);
+  });
+
+  it("should render variable expressions", () => {
+    const result = engine.parseAndRenderSync("Hello {{ name }}", { name: "World" });
+    expect(result).toBe("Hello World");
+  });
+
+  it("should throw on unknown filters (strictFilters)", () => {
+    expect(() => {
+      engine.parseAndRenderSync("{{ name | bogus }}", { name: "test" });
+    }).toThrow();
+  });
+});

package/src/engine.ts

@@ -0,0 +1,37 @@
+import { Liquid } from "liquidjs";
+
+import type { CreateEngineOptions } from "./types.js";
+
+/**
+ * Create a LiquidJS engine with custom options.
+ *
+ * The `partialsDir` is used as the root for `{% render %}` resolution.
+ * The `.prompt` extension is appended automatically.
+ *
+ * @param partialsDir - Root directory for `{% render %}` partial resolution.
+ * @param options - Optional overrides for the LiquidJS engine configuration.
+ * @returns A configured {@link Liquid} engine instance.
+ */
+export function createEngine(partialsDir: string, options?: Partial<CreateEngineOptions>): Liquid {
+  return new Liquid({
+    root: [partialsDir],
+    partials: [partialsDir],
+    extname: ".prompt",
+    cache: true,
+    strictFilters: true,
+    ownPropertyOnly: true,
+    ...options,
+  });
+}
+
+/**
+ * Shared LiquidJS engine for rendering prompt templates at runtime.
+ *
+ * Partials are flattened at codegen time by the CLI, so this engine
+ * only needs to handle `{{ var }}` expressions and basic Liquid
+ * control flow (`{% if %}`, `{% for %}`). No filesystem access required.
+ */
+export const engine = new Liquid({
+  strictFilters: true,
+  ownPropertyOnly: true,
+});

package/src/index.ts

@@ -0,0 +1,11 @@
+export { engine, createEngine } from "./engine.js";
+export { clean } from "./clean.js";
+export { PARTIALS_DIR } from "./partials-dir.js";
+export { createPromptRegistry } from "./registry.js";
+export type {
+  CreateEngineOptions,
+  Liquid,
+  PromptModule,
+  PromptNamespace,
+  PromptRegistry,
+} from "./types.js";

package/src/partials-dir.test.ts

@@ -0,0 +1,15 @@
+import { isAbsolute } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { PARTIALS_DIR } from "@/partials-dir.js";
+
+describe("PARTIALS_DIR", () => {
+  it("should be an absolute path", () => {
+    expect(isAbsolute(PARTIALS_DIR)).toBe(true);
+  });
+
+  it("should point to the prompts directory", () => {
+    expect(PARTIALS_DIR).toMatch(/prompts$/);
+  });
+});

package/src/partials-dir.ts

@@ -0,0 +1,5 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Absolute path to the SDK's built-in partials directory. */
+export const PARTIALS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "../prompts");

package/src/prompts/constraints.prompt

@@ -0,0 +1,20 @@
+<constraints>
+{% if in_scope %}
+## In Scope
+{% for item in in_scope %}
+- {{ item }}
+{% endfor %}
+{% endif %}
+{% if out_of_scope %}
+## Out of Scope
+{% for item in out_of_scope %}
+- {{ item }}
+{% endfor %}
+{% endif %}
+{% if rules %}
+## Rules
+{% for rule in rules %}
+- {{ rule }}
+{% endfor %}
+{% endif %}
+</constraints>

package/src/prompts/identity.prompt

@@ -0,0 +1,6 @@
+<identity>
+You are {{ role }}, {{ desc }}.
+{% if context %}
+{{ context }}
+{% endif %}
+</identity>

package/src/prompts/tools.prompt

@@ -0,0 +1,14 @@
+<tools>
+You have access to the following tools:
+{% if tools %}
+{% for tool in tools %}
+**{{ tool.name }}** -- {{ tool.description }}
+{% for param in tool.params %}
+- `{{ param.name }}` ({{ param.type }}{% if param.required %}, required{% endif %}) -- {{ param.description }}
+{% endfor %}
+
+{% endfor %}
+{% else %}
+No tools are configured for this agent.
+{% endif %}
+</tools>

package/src/registry.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import { createPromptRegistry } from "@/registry.js";
+
+const mockPrompt = {
+  name: "test-prompt" as const,
+  group: "agents" as const,
+  schema: z.object({ name: z.string() }),
+  render(variables: { name: string }) {
+    return `Hello ${variables.name}`;
+  },
+  validate(variables: unknown) {
+    return z.object({ name: z.string() }).parse(variables);
+  },
+};
+
+const emptyPrompt = {
+  name: "empty" as const,
+  group: undefined,
+  schema: z.object({}),
+  render() {
+    return "static";
+  },
+  validate(variables: unknown) {
+    return z.object({}).parse(variables);
+  },
+};
+
+describe("createPromptRegistry", () => {
+  it("should provide dot-access to a registered prompt", () => {
+    const registry = createPromptRegistry({ testPrompt: mockPrompt });
+    expect(registry.testPrompt.name).toBe("test-prompt");
+    expect(registry.testPrompt.render({ name: "Alice" })).toBe("Hello Alice");
+  });
+
+  it("should provide nested dot-access for grouped prompts", () => {
+    const registry = createPromptRegistry({
+      agents: { testPrompt: mockPrompt },
+    });
+    expect(registry.agents.testPrompt.name).toBe("test-prompt");
+    expect(registry.agents.testPrompt.render({ name: "Bob" })).toBe("Hello Bob");
+  });
+
+  it("should freeze the top-level registry object", () => {
+    const registry = createPromptRegistry({ testPrompt: mockPrompt });
+    expect(Object.isFrozen(registry)).toBe(true);
+  });
+
+  it("should freeze nested namespace objects", () => {
+    const registry = createPromptRegistry({
+      agents: { testPrompt: mockPrompt },
+    });
+    expect(Object.isFrozen(registry.agents)).toBe(true);
+  });
+
+  it("should expose all keys via Object.keys", () => {
+    const registry = createPromptRegistry({
+      testPrompt: mockPrompt,
+      empty: emptyPrompt,
+    });
+    expect(Object.keys(registry)).toEqual(["testPrompt", "empty"]);
+  });
+
+  it("should work with an empty registry", () => {
+    const registry = createPromptRegistry({});
+    expect(Object.keys(registry)).toEqual([]);
+  });
+});

package/src/registry.ts

@@ -0,0 +1,65 @@
+import type { PromptModule, PromptNamespace, PromptRegistry } from "./types.js";
+
+/**
+ * Check whether a value looks like a PromptModule leaf.
+ * Leaves have `name`, `schema`, and `render` — namespaces do not.
+ *
+ * @private
+ */
+function isPromptModule(value: unknown): value is PromptModule {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "render" in value &&
+    "schema" in value &&
+    "name" in value
+  );
+}
+
+/**
+ * Recursively freeze a prompt namespace tree.
+ * Only recurses into plain namespace nodes — PromptModule leaves
+ * (which contain Zod schemas) are frozen shallowly.
+ *
+ * @param obj - The namespace object to freeze.
+ * @returns The frozen object cast to its deep-readonly type.
+ *
+ * @private
+ */
+function deepFreeze<T extends PromptNamespace>(obj: T): PromptRegistry<T> {
+  Object.freeze(obj);
+  Object.values(obj).forEach((value) => {
+    if (
+      typeof value === "object" &&
+      value !== null &&
+      !Object.isFrozen(value) &&
+      !isPromptModule(value)
+    ) {
+      deepFreeze(value as PromptNamespace);
+    }
+  });
+  return obj as PromptRegistry<T>;
+}
+
+/**
+ * Create a typed, frozen prompt registry from a (possibly nested) map of prompt modules.
+ *
+ * The registry is typically created by generated code — the CLI produces
+ * an `index.ts` that calls `createPromptRegistry()` with all discovered
+ * prompt modules keyed by camelCase name, nested by group.
+ *
+ * @param modules - Record mapping camelCase prompt names (or group namespaces) to their modules.
+ * @returns A deep-frozen, typed record with direct property access.
+ *
+ * @example
+ * ```ts
+ * const prompts = createPromptRegistry({
+ *   agents: { coverageAssessor },
+ *   greeting,
+ * })
+ * prompts.agents.coverageAssessor.render({ scope: 'full' })
+ * ```
+ */
+export function createPromptRegistry<T extends PromptNamespace>(modules: T): PromptRegistry<T> {
+  return deepFreeze({ ...modules });
+}

package/src/types.ts

@@ -0,0 +1,62 @@
+import type { Liquid, LiquidOptions } from "liquidjs";
+import type { ZodType } from "zod";
+
+/**
+ * Options for creating a custom LiquidJS engine.
+ */
+export type CreateEngineOptions = Pick<
+  LiquidOptions,
+  | "root"
+  | "partials"
+  | "extname"
+  | "cache"
+  | "strictFilters"
+  | "strictVariables"
+  | "ownPropertyOnly"
+>;
+
+/**
+ * A single prompt module produced by codegen.
+ *
+ * Each `.prompt` file generates a default export conforming to this shape.
+ */
+export interface PromptModule<T = unknown> {
+  readonly name: string;
+  readonly group: string | undefined;
+  readonly schema: ZodType<T>;
+  render(variables: T): string;
+  validate(variables: unknown): T;
+}
+
+/**
+ * A nested namespace node in the prompt tree.
+ * Values are either PromptModule leaves or further nested namespaces.
+ */
+export type PromptNamespace = {
+  readonly [key: string]: PromptModule | PromptNamespace;
+};
+
+/**
+ * Deep-readonly version of a prompt tree.
+ * Prevents reassignment at any nesting level.
+ *
+ * @example
+ * ```ts
+ * type MyRegistry = PromptRegistry<{
+ *   agents: { coverageAssessor: PromptModule }
+ *   greeting: PromptModule
+ * }>
+ * ```
+ */
+export type PromptRegistry<T extends PromptNamespace> = {
+  readonly [K in keyof T]: T[K] extends PromptModule
+    ? T[K]
+    : T[K] extends PromptNamespace
+      ? PromptRegistry<T[K]>
+      : T[K];
+};
+
+/**
+ * Re-export the Liquid type for consumers that need to type the engine.
+ */
+export type { Liquid };

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2024"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsdown.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  outDir: "dist/lib",
+  format: ["esm"],
+  dts: true,
+  clean: true,
+  unbundle: false,
+  platform: "node",
+  target: "node22",
+});

package/vitest.config.ts

@@ -0,0 +1,21 @@
+import { resolve } from "node:path";
+
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.{ts,tsx}"],
+    passWithNoTests: true,
+    coverage: {
+      provider: "v8",
+      include: ["src/**/*.ts"],
+      exclude: ["src/**/*.test.ts", "src/**/*.test-d.ts", "src/**/index.ts", "src/types.ts"],
+      reporter: ["text", "lcov"],
+    },
+  },
+  resolve: {
+    alias: {
+      "@": resolve(__dirname, "./src"),
+    },
+  },
+});