alchemy 0.2.2 → 0.2.4

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/ai/index.ts

@@ -0,0 +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

@@ -1,3 +1,6 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
 import { DestroyedSignal, destroy } from "./destroy";
 import { Scope } from "./scope";
 import { secret } from "./secret";
@@ -6,31 +9,175 @@ import type { StateStoreType } from "./state";
 // TODO: support browser
 const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
 
-function _alchemy(appName: string, options: Omit<AlchemyOptions, "appName">) {
-  return scope(undefined, {
-    ...options,
-    appName,
-    stage: options.stage,
-  });
-}
-_alchemy.destroy = destroy;
-_alchemy.run = run;
-_alchemy.scope = scope;
-_alchemy.secret = secret;
-
-// 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[]]
+    | [appName: string, options?: Omit<AlchemyOptions, "appName">]
+): any {
+  if (typeof args[0] === "string") {
+    const [appName, options] = args;
+    return scope(undefined, {
+      ...options,
+      appName,
+      stage: options?.stage,
+    });
+  } else {
+    const [template, ...values] = args;
+    const [, secondLine] = template[0].split("\n");
+    const leadingSpaces = secondLine
+      ? secondLine.match(/^(\s*)/)?.[1]?.length || 0
+      : 0;
+    const indent = " ".repeat(leadingSpaces);
+
+    return (async () => {
+      const { isFileCollection, isFileRef } = await import("./fs");
+
+      const appendices: Record<string, string> = {};
+
+      const stringValues = await Promise.all(
+        values.map(async function resolve(value): Promise<string> {
+          if (typeof value === "string") {
+            return indent + value;
+          } else if (value instanceof Promise) {
+            return resolve(await value);
+          } else if (isFileRef(value)) {
+            if (!(value.path in appendices)) {
+              appendices[value.path] = await fs.readFile(value.path, "utf-8");
+            }
+            return `[${path.basename(value.path)}](${value.path})`;
+          } else if (isFileCollection(value)) {
+            return Object.entries(value.files)
+              .map(([filePath, content]) => {
+                appendices[filePath] = content;
+                return `[${path.basename(filePath)}](${filePath})`;
+              })
+              .join("\n\n");
+          } else if (Array.isArray(value)) {
+            return (
+              await Promise.all(
+                value.map(async (value, i) => `${i}. ${await resolve(value)}`),
+              )
+            ).join("\n");
+          } else {
+            // TODO: support other types
+            throw new Error(`Unsupported value type: ${JSON.stringify(value)}`);
+          }
+        }),
+      );
+
+      // Construct the string template by joining template parts with interpolated values
+      const lines = template
+        .map((part) =>
+          part
+            .split("\n")
+            .map((line) =>
+              line.startsWith(indent) ? line.slice(indent.length) : line,
+            )
+            .join("\n"),
+        )
+        .flatMap((part, i) =>
+          i < stringValues.length ? [part, stringValues[i] ?? ""] : [part],
+        )
+        .join("")
+        .split("\n");
+
+      // Collect and sort appendices by file path
+      return [
+        // format the user prompt and trim the first line if it's empty
+        lines.length > 1 && lines[0].replaceAll(" ", "").length === 0
+          ? lines.slice(1).join("\n")
+          : lines.join("\n"),
+
+        // sort appendices by path and include at the end of the prompt
+        Object.entries(appendices)
+          .sort(([a], [b]) => a.localeCompare(b))
+          .map(([filePath, content]) => {
+            const extension = path.extname(filePath).slice(1);
+            const codeTag = extension ? extension : "";
+            return `// ${filePath}\n\`\`\`${codeTag}\n${content}\n\`\`\``;
+          })
+          .join("\n\n"),
+      ].join("\n");
+    })();
+  }
 }
+_alchemy.destroy = destroy;
+_alchemy.run = run;
+_alchemy.scope = scope;
+_alchemy.secret = secret;
 
 export interface AlchemyOptions {
   /**
@@ -72,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,
@@ -98,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>]
@@ -115,13 +287,16 @@ async function run<T>(
           AlchemyOptions | undefined,
           (this: Scope, scope: Scope) => Promise<T>,
         ]);
-  await using scope = alchemy.scope(id, options);
+  const scope = alchemy.scope(id, options);
   try {
     return await fn.bind(scope)(scope);
   } catch (error) {
     if (!(error instanceof DestroyedSignal)) {
       scope.fail();
+    } else {
     }
     throw error;
+  } finally {
+    await scope.finalize();
   }
 }

package/src/apply.ts

@@ -7,6 +7,7 @@ import {
   type Resource,
   type ResourceProps,
 } from "./resource";
+import { Secret } from "./secret";
 import type { State } from "./state";
 import { serialize } from "./util/serde";
 
@@ -17,12 +18,12 @@ export interface ApplyOptions {
 
 export async function apply<Out extends Resource>(
   resource: PendingResource<Out>,
-  props: ResourceProps,
+  props: ResourceProps | undefined,
   options?: ApplyOptions,
 ): Promise<Awaited<Out>> {
   const scope = resource.Scope;
   try {
-    const quiet = props.quiet ?? scope.quiet;
+    const quiet = props?.quiet ?? scope.quiet;
     await scope.init();
     let state: State | undefined = (await scope.state.get(resource.ID))!;
     const provider: Provider = PROVIDERS.get(resource.Kind);
@@ -55,17 +56,27 @@ export async function apply<Out extends Resource>(
 
     // Skip update if inputs haven't changed and resource is in a stable state
     if (state.status === "created" || state.status === "updated") {
-      if (
-        JSON.stringify(state.props) ===
-          JSON.stringify(await serialize(scope, props)) &&
-        alwaysUpdate !== true
-      ) {
+      const oldProps = JSON.stringify(
+        state.props,
+        (_, value) =>
+          value instanceof Secret
+            ? {
+                "@secret": value.unencrypted,
+              }
+            : value,
+        2,
+      );
+      const newProps = JSON.stringify(
+        await serialize(scope, props, {
+          encrypt: false,
+        }),
+        null,
+        2,
+      );
+      if (oldProps === newProps && alwaysUpdate !== true) {
         if (!quiet) {
           console.log(`Skip:    "${resource.FQN}" (no changes)`);
         }
-        // if (resourceState.output !== undefined) {
-        //   resource[Provide](resourceState.output);
-        // }
         return state.output as Awaited<Out>;
       }
     }
@@ -92,6 +103,7 @@ export async function apply<Out extends Resource>(
       id: resource.ID,
       fqn: resource.FQN,
       seq: resource.Seq,
+      props: state.oldProps,
       state,
       replace: () => {
         if (isReplaced) {
@@ -104,9 +116,9 @@ export async function apply<Out extends Resource>(
       },
     });
 
-    const output = await alchemy.run(resource.ID, async () => {
-      return provider.handler.bind(ctx)(resource.ID, props);
-    });
+    const output = await alchemy.run(resource.ID, async () =>
+      provider.handler.bind(ctx)(resource.ID, props),
+    );
 
     if (!quiet) {
       console.log(