alchemy 0.2.3 → 0.2.4

package/src/ai/ark.ts

@@ -0,0 +1,118 @@
+import {
+  type Tool as AITool,
+  type Schema,
+  type ToolExecutionOptions,
+  tool as aitool,
+  jsonSchema,
+} from "ai";
+import { ArkErrors, type JsonSchema, type type } from "arktype";
+
+export namespace ark {
+  export function schema<T>(type: JsonSchema): Schema<T>;
+  export function schema<T extends type>(type: T): Schema<type.infer<T>> {
+    const jsonSchemaObj = type.toJsonSchema() as any;
+    const processedSchema = processSchema(jsonSchemaObj);
+
+    return jsonSchema(processedSchema, {
+      validate: (value) => {
+        const out = type(value) as type.infer<T> | type.errors;
+        if (out instanceof ArkErrors) {
+          return {
+            success: false,
+            error: new Error(out.summary),
+          };
+        }
+        return {
+          success: true,
+          value: out,
+        };
+      },
+    });
+  }
+
+  /**
+   * Recursively processes a JSON schema and sets additionalProperties: false
+   * for any object types.
+   *
+   * Structured Outputs requires additionalProperties: false
+   */
+  function processSchema(schema: any): any {
+    if (!schema || typeof schema !== "object") return schema;
+
+    // Create a copy to avoid mutating the original
+    const result = { ...schema };
+
+    // Convert anyOf with all const values to enum
+    if (result.anyOf && Array.isArray(result.anyOf)) {
+      const allConst = result.anyOf.every(
+        (item: any) => item && typeof item === "object" && "const" in item,
+      );
+
+      if (allConst) {
+        // Extract all const values
+        const enumValues = result.anyOf.map((item: any) => item.const);
+
+        // Determine the type based on the first const value
+        // Assuming all const values are of the same type
+        const firstType = typeof enumValues[0];
+
+        // Replace anyOf with enum
+        delete result.anyOf;
+        result.type = firstType;
+        result.enum = enumValues;
+      } else {
+        // Process each item in anyOf
+        result.anyOf = result.anyOf.map(processSchema);
+      }
+    }
+
+    // If this is an object type, set additionalProperties: false
+    if (result.type === "object") {
+      result.additionalProperties = false;
+      result.properties ??= {};
+    }
+
+    // Process properties of objects
+    if (result.properties && typeof result.properties === "object") {
+      result.properties = Object.fromEntries(
+        Object.entries(result.properties).map(([key, value]) => [
+          key,
+          processSchema(value),
+        ]),
+      );
+    }
+
+    // Process items in arrays
+    if (result.items) {
+      result.items = processSchema(result.items);
+    }
+
+    // Process allOf, oneOf
+    for (const key of ["allOf", "oneOf"]) {
+      if (Array.isArray(result[key])) {
+        result[key] = result[key].map(processSchema);
+      }
+    }
+
+    return result;
+  }
+
+  export interface Tool<Input extends type, Output>
+    extends Omit<AITool<Schema<type.infer<Input>>>, "parameters" | "execute"> {
+    description?: string;
+    parameters: Input;
+    execute: (
+      input: type.infer<Input>,
+      options: ToolExecutionOptions,
+    ) => Promise<Output>;
+  }
+
+  export function tool<Input extends type, Output>(
+    tool: Tool<Input, Output>,
+  ): AITool<Schema<type.infer<Input>>, Output> {
+    return aitool({
+      ...tool,
+      parameters: ark.schema<Input>(tool.parameters),
+    } as any);
+  }
+}

package/src/ai/client.ts

@@ -0,0 +1,78 @@
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import type { Secret } from "../secret";
+
+/**
+ * Model configuration for AI operations
+ */
+export interface ModelConfig {
+  /**
+   * Model ID to use
+   * @default 'gpt-4o'
+   */
+  id?: string;
+
+  /**
+   * Model provider name
+   * @default 'openai'
+   */
+  provider?: string;
+
+  /**
+   * Model-specific options
+   */
+  options?: Record<string, unknown>;
+}
+
+/**
+ * Configuration for creating an OpenAI client
+ */
+export interface ClientConfig {
+  /**
+   * Base URL for the OpenAI API
+   * @default 'https://api.openai.com/v1'
+   */
+  baseURL?: string;
+
+  /**
+   * OpenAI API key to use for generating content
+   * If not provided, will use OPENAI_API_KEY environment variable
+   */
+  apiKey?: Secret;
+
+  /**
+   * Model configuration
+   */
+  model?: ModelConfig;
+}
+
+/**
+ * Creates an OpenAI-compatible client with the given configuration
+ */
+export function createClient(config: ClientConfig) {
+  // Get API key from props or environment
+  const apiKey = config.apiKey?.unencrypted || process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    throw new Error("OpenAI API key is required");
+  }
+
+  // Initialize OpenAI compatible provider
+  return createOpenAICompatible({
+    name: config.model?.provider || "openai",
+    apiKey,
+    baseURL: config.baseURL || "https://api.openai.com/v1",
+  });
+}
+
+/**
+ * Gets the model ID from the configuration or returns the default
+ */
+export function getModelId(config: ClientConfig): string {
+  return config.model?.id || "gpt-4o";
+}
+
+/**
+ * Gets the model options from the configuration
+ */
+export function getModelOptions(config: ClientConfig): Record<string, unknown> {
+  return config.model?.options || {};
+}

package/src/ai/document.ts

@@ -0,0 +1,160 @@
+import { generateText } from "ai";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import type { Secret } from "../secret";
+import {
+  type ModelConfig,
+  createClient,
+  getModelId,
+  getModelOptions,
+} from "./client";
+
+/**
+ * Properties for creating or updating a Document
+ */
+export interface DocumentProps {
+  /**
+   * Path to the markdown document
+   */
+  path: string;
+
+  /**
+   * Base URL for the OpenAI API
+   * @default 'https://api.openai.com/v1'
+   */
+  baseURL?: string;
+
+  /**
+   * Prompt for generating content
+   * Use alchemy template literals to include file context:
+   * @example
+   * prompt: await alchemy`
+   *   Generate docs using:
+   *   ${alchemy.file("src/api.ts")}
+   * `
+   */
+  prompt: string;
+
+  /**
+   * OpenAI API key to use for generating content
+   * If not provided, will use OPENAI_API_KEY environment variable
+   */
+  apiKey?: Secret;
+
+  /**
+   * Model configuration
+   */
+  model?: ModelConfig;
+}
+
+/**
+ * A markdown document that can be created, updated, and deleted
+ */
+export interface Document extends DocumentProps, Resource<"docs::Document"> {
+  /**
+   * Content of the document
+   */
+  content: string;
+
+  /**
+   * Time at which the document was created
+   */
+  createdAt: number;
+
+  /**
+   * Time at which the document was last updated
+   */
+  updatedAt: number;
+}
+
+/**
+ * Resource for managing AI-generated markdown documents using the Vercel AI SDK.
+ * Supports powerful context handling through the alchemy template literal tag.
+ *
+ * @example
+ * // Create a document using alchemy template literals for context
+ * const apiDocs = await Document("api-docs", {
+ *   path: "./docs/api.md",
+ *   prompt: await alchemy`
+ *     Generate API documentation based on these source files:
+ *     ${alchemy.file("src/api.ts")}
+ *     ${alchemy.file("src/types.ts")}
+ *   `
+ *   // The above will automatically append the file contents as code blocks:
+ *   //
+ *   // Generate API documentation based on these source files:
+ *   // [api.ts](src/api.ts)
+ *   // [types.ts](src/types.ts)
+ *   //
+ *   // // src/api.ts
+ *   // ```ts
+ *   // ... contents of api.ts ...
+ *   // ```
+ *   //
+ *   // // src/types.ts
+ *   // ```ts
+ *   // ... contents of types.ts ...
+ *   // ```
+ * });
+ *
+ * @example
+ * // Use alchemy template literals with file collections
+ * const modelDocs = await Document("models", {
+ *   path: "./docs/models.md",
+ *   prompt: await alchemy`
+ *     Write documentation for these data models:
+ *     ${alchemy.files("src/models/user.ts", "src/models/post.ts")}
+ *   `
+ *   // This creates a prompt with all files appended as code blocks,
+ *   // automatically handling syntax highlighting based on file extensions
+ * });
+ */
+export const Document = Resource(
+  "docs::Document",
+  async function (
+    this: Context<Document>,
+    id: string,
+    props: DocumentProps,
+  ): Promise<Document> {
+    // Ensure directory exists
+    await fs.mkdir(path.dirname(props.path), { recursive: true });
+
+    if (this.phase === "delete") {
+      try {
+        await fs.unlink(props.path);
+      } catch (error: any) {
+        // Ignore if file doesn't exist
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
+      }
+      return this.destroy();
+    }
+
+    // Initialize OpenAI compatible provider using shared client
+    const provider = createClient(props);
+
+    // Generate content
+    const { text } = await generateText({
+      model: provider(getModelId(props)),
+      prompt: props.prompt,
+      ...getModelOptions(props),
+    });
+
+    // Write content to file
+    await fs.writeFile(props.path, text);
+
+    // Get file stats for timestamps
+    const stats = await fs.stat(props.path);
+
+    // Return the resource
+    return this({
+      ...props,
+      content: text,
+      createdAt: stats.birthtimeMs,
+      updatedAt: stats.mtimeMs,
+    });
+  },
+);

package/src/{docs → ai}/index.ts

@@ -1 +1,2 @@
 export * from "./document";
+export * from "./object";

package/src/ai/object.ts

@@ -0,0 +1,149 @@
+import { generateObject } from "ai";
+import type { JsonSchema, Type, type } from "arktype";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import type { Secret } from "../secret";
+import { ark } from "./ark";
+import {
+  type ModelConfig,
+  createClient,
+  getModelId,
+  getModelOptions,
+} from "./client";
+
+/**
+ * Properties for creating or updating an AI Object
+ */
+export interface ObjectProps<T extends Type<any, any>> {
+  /**
+   * The ArkType schema to validate and structure the generated content
+   */
+  schema: T | JsonSchema;
+
+  /**
+   * Prompt for generating the content
+   * Use alchemy template literals to include file context:
+   * @example
+   * prompt: await alchemy`
+   *   Generate a description for:
+   *   ${alchemy.file("src/data.ts")}
+   * `
+   */
+  prompt: string;
+
+  /**
+   * System prompt to guide the AI's behavior
+   * @example
+   * system: "You are a technical writer tasked with describing code"
+   */
+  system?: string;
+
+  /**
+   * Base URL for the OpenAI API
+   * @default 'https://api.openai.com/v1'
+   */
+  baseURL?: string;
+
+  /**
+   * OpenAI API key to use for generating content
+   * If not provided, will use OPENAI_API_KEY environment variable
+   */
+  apiKey?: Secret;
+
+  /**
+   * Model configuration
+   */
+  model?: ModelConfig;
+}
+
+/**
+ * A resource that uses AI to generate structured content based on a schema
+ */
+export interface Object<T> extends Resource<"ai::Object"> {
+  type: JsonSchema;
+
+  /**
+   * The generated content, typed according to the provided schema
+   */
+  object: T;
+
+  /**
+   * Time at which the content was generated
+   */
+  createdAt: number;
+}
+
+/**
+ * Resource for generating structured content using the Vercel AI SDK.
+ * Supports powerful context handling through the alchemy template literal tag.
+ *
+ * @example
+ * // Generate a product description with specific fields
+ * const productSchema = type({
+ *   name: "string",
+ *   description: "string",
+ *   features: "string[]",
+ *   price: "number"
+ * });
+ *
+ * const product = await Object("new-product", {
+ *   schema: productSchema,
+ *   prompt: "Generate a product description for a new smartphone",
+ *   system: "You are a product copywriter specializing in tech products"
+ * });
+ *
+ * console.log(product.content); // Typed as per schema
+ *
+ * @example
+ * // Generate code documentation with context
+ * const docSchema = type({
+ *   summary: "string",
+ *   parameters: {
+ *     name: "string",
+ *     type: "string",
+ *     description: "string"
+ *   }[],
+ *   returns: "string"
+ * });
+ *
+ * const docs = await Object("function-docs", {
+ *   schema: docSchema,
+ *   prompt: await alchemy`
+ *     Generate documentation for this function:
+ *     ${alchemy.file("src/utils/format.ts")}
+ *   `,
+ *   system: "You are a technical documentation writer"
+ * });
+ */
+export const Object = Resource("ai::Object", async function <
+  const T extends Type<any, any>,
+>(this: Context<Object<any>>, id: string, props: ObjectProps<T>): Promise<
+  Object<type.infer<T>>
+> {
+  if (this.phase === "delete") {
+    return this.destroy();
+  }
+
+  // Initialize OpenAI compatible provider using shared client
+  const provider = createClient(props);
+
+  // Generate structured output using generateObject
+  const { object } = await generateObject({
+    model: provider(getModelId(props)),
+    // Convert ArkType schema to Zod schema for generateObject
+    // This is needed because generateObject expects a Zod schema
+    schema: ark.schema<type.infer<T>>(props.schema),
+    system:
+      props.system ||
+      "You are an AI assistant tasked with generating structured content.",
+    prompt: props.prompt,
+    ...getModelOptions(props),
+  });
+
+  // Return the resource with typed content
+  return this({
+    type: props.schema,
+    object: object,
+    createdAt: Date.now(),
+  });
+});

package/src/alchemy.ts

@@ -9,21 +9,79 @@ import type { StateStoreType } from "./state";
 // TODO: support browser
 const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
 
-// alchemy type is to semantically highlight `alchemy` as a type (keyword)
+/**
+ * Type alias for semantic highlighting of `alchemy` as a type keyword
+ */
 export type alchemy = Alchemy;
 
 export const alchemy: Alchemy = _alchemy as any;
 
-// Alchemy is for module augmentation
+/**
+ * The Alchemy interface provides core functionality and is augmented by providers.
+ * Supports both application scoping with secrets and template string interpolation.
+ *
+ * @example
+ * // Create an application scope with stage and secret handling
+ * const app = alchemy("github:alchemy", {
+ *   stage: "prod",
+ *   phase: "up",
+ *   // Required for encrypting/decrypting secrets
+ *   password: process.env.SECRET_PASSPHRASE
+ * });
+ *
+ * // Create a resource with encrypted secrets
+ * const resource = await Resource("my-resource", {
+ *   apiKey: alchemy.secret(process.env.API_KEY)
+ * });
+ *
+ * await app.finalize();
+ */
 export interface Alchemy {
   scope: typeof scope;
   run: typeof run;
   destroy: typeof destroy;
+  /**
+   * Creates an encrypted secret that can be safely stored in state files.
+   * Requires a password to be set either globally in the application options
+   * or locally in the current scope.
+   */
   secret: typeof secret;
+  /**
+   * Creates a new application scope with the given name and options.
+   * Used to create and manage resources with proper secret handling.
+   *
+   * @example
+   * const app = alchemy("my-app", {
+   *   stage: "prod",
+   *   // Required for encrypting/decrypting secrets
+   *   password: process.env.SECRET_PASSPHRASE
+   * });
+   */
   (...parameters: Parameters<typeof scope>): ReturnType<typeof scope>;
+  /**
+   * Template literal tag that supports file interpolation for documentation.
+   * Automatically formats the content and appends file contents as code blocks.
+   *
+   * @example
+   * // Generate documentation using file contents
+   * await Document("api-docs", {
+   *   prompt: await alchemy`
+   *     Generate docs using the contents of:
+   *     ${alchemy.file("README.md")}
+   *     ${alchemy.file("./.cursorrules")}
+   *
+   *     And here are the source files:
+   *     ${alchemy.files(files)}
+   *   `
+   * });
+   */
   (template: TemplateStringsArray, ...values: any[]): Promise<string>;
 }
 
+/**
+ * Implementation of the alchemy function that handles both application scoping
+ * and template string interpolation.
+ */
 function _alchemy(
   ...args:
     | [template: TemplateStringsArray, ...values: any[]]
@@ -45,7 +103,7 @@ function _alchemy(
     const indent = " ".repeat(leadingSpaces);
 
     return (async () => {
-      const { isFileCollection, isFileRef } = await import("./fs/file");
+      const { isFileCollection, isFileRef } = await import("./fs");
 
       const appendices: Record<string, string> = {};
 
@@ -161,14 +219,24 @@ export interface AlchemyOptions {
 
   /**
    * A passphrase to use to encrypt/decrypt secrets.
+   * Required if using alchemy.secret() in this scope.
    */
   password?: string;
 }
 
 /**
  * Enter a new scope synchronously.
- * @param options
- * @returns
+ *
+ * @example
+ * // Create a scope with a password for secret handling
+ * await using scope = alchemy.scope("my-scope", {
+ *   password: process.env.SECRET_PASSPHRASE
+ * });
+ *
+ * // Use secrets within the scope
+ * const resource = await Resource("my-resource", {
+ *   apiKey: alchemy.secret(process.env.API_KEY)
+ * });
  */
 function scope(
   id: string | undefined,
@@ -187,6 +255,21 @@ function scope(
   return scope;
 }
 
+/**
+ * Run a function in a new scope asynchronously.
+ * Useful for isolating secret handling with a specific password.
+ *
+ * @example
+ * // Run operations in a scope with its own password
+ * await alchemy.run("secure-scope", {
+ *   password: process.env.SCOPE_PASSWORD
+ * }, async () => {
+ *   // Secrets in this scope will use this password
+ *   const resource = await Resource("my-resource", {
+ *     apiKey: alchemy.secret(process.env.API_KEY)
+ *   });
+ * });
+ */
 async function run<T>(
   ...args:
     | [id: string, fn: (this: Scope, scope: Scope) => Promise<T>]