alchemy 0.2.3 → 0.2.5

package/src/test/bun.ts

@@ -6,35 +6,111 @@ import { alchemy } from "../alchemy";
 import { destroy } from "../destroy";
 import type { Scope } from "../scope";
 
+/**
+ * Extend the Alchemy interface to include test functionality
+ */
 declare module "../alchemy" {
   interface Alchemy {
     test: typeof test;
   }
 }
 
+/**
+ * Add test functionality to alchemy instance
+ */
 alchemy.test = test;
 
+/**
+ * Options for configuring test behavior
+ */
 export interface TestOptions {
+  /**
+   * Whether to automatically destroy resources after test.
+   * @default true.
+   */
   destroy?: boolean;
+
+  /**
+   * Whether to suppress logging output.
+   * @default false.
+   */
   quiet?: boolean;
+
+  /**
+   * Password to use for test resources.
+   * @default "test-password".
+   */
   password?: string;
 }
 
+/**
+ * Global test scope for all tests
+ */
 const globalTestScope = alchemy.scope("test");
 
+/**
+ * Test function type definition with overloads
+ */
 type test = {
+  /**
+   * Create a test with default options
+   * @param name Test name
+   * @param fn Test function
+   * @param timeout Optional timeout in milliseconds
+   */
   (name: string, fn: (scope: Scope) => Promise<any>, timeout?: number): void;
+
+  /**
+   * Create a test with custom options
+   * @param name Test name
+   * @param options Test configuration options
+   * @param fn Test function
+   * @param timeout Optional timeout in milliseconds
+   */
   (
     name: string,
     options: TestOptions,
     fn: (scope: Scope) => Promise<any>,
     timeout?: number,
   ): void;
+
+  /**
+   * Skip test conditionally
+   * @param condition If true, test will be skipped
+   */
   skipIf(condition: boolean): test;
+
+  /**
+   * Current test scope
+   */
   scope: Scope;
 };
 
+/**
+ * Creates a test helper function that provides scoped resource management
+ *
+ * @param meta Import meta object from the test file
+ * @param defaultOptions Default options to apply to all tests
+ * @returns Test function with scope management
+ *
+ * @example
+ * ```typescript
+ * const test = alchemy.test(import.meta);
+ *
+ * describe("My Resource", () => {
+ *   test("create and delete", async (scope) => {
+ *     try {
+ *       const resource = await MyResource("test", { ... });
+ *       expect(resource.id).toBeTruthy();
+ *     } finally {
+ *       await alchemy.destroy(scope);
+ *     }
+ *   });
+ * });
+ * ```
+ */
 export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
+  // Add skipIf functionality
   test.skipIf = (condition: boolean) => {
     if (condition) {
       // TODO: proxy through to bun:test.skipIf
@@ -43,11 +119,13 @@ export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
     return test;
   };
 
+  // Create local test scope based on filename
   const localTestScope = alchemy.scope(path.basename(meta.filename), {
     parent: globalTestScope,
   });
   test.scope = localTestScope;
 
+  // Clean up test scope after all tests complete
   afterAll(() => alchemy.destroy(test.scope));
 
   return test as any;
@@ -71,13 +149,16 @@ export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
             ),
           )
         : {};
+
+    // Merge options with defaults
     const options = {
-      destroy: false,
+      destroy: true,
       quiet: false,
       password: "test-password",
       ...spread(defaultOptions),
       ...spread(_options),
     };
+
     const fn = typeof args[1] === "function" ? args[1] : args[2]!;
 
     return alchemy.run(
@@ -88,13 +169,12 @@ export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
       },
       async (scope) => {
         return it(testName, async () => {
-          // bun will call from a different scope, so we need to enter the test's scope manually
+          // Enter test scope since bun calls from different scope
           scope.enter();
           try {
             await fn(scope);
           } finally {
             if (options.destroy !== false) {
-              // TODO: auto-destroy resources
               await destroy(scope);
             }
           }

package/src/util/serde.ts

@@ -2,6 +2,17 @@ import { Scope } from "../scope";
 import { Secret } from "../secret";
 import { decryptWithKey, encryptWithKey } from "./encrypt";
 
+import type { Type } from "arktype";
+
+// zero-dependency type guard for ArkType
+function isType(value: any): value is Type<any, any> {
+  return (
+    value &&
+    typeof value === "object" &&
+    typeof value.toJsonSchema === "function"
+  );
+}
+
 export async function serialize(
   scope: Scope,
   value: any,
@@ -21,6 +32,10 @@ export async function serialize(
           ? await encryptWithKey(value.unencrypted, scope.password)
           : value.unencrypted,
     };
+  } else if (isType(value)) {
+    return {
+      "@schema": value.toJSON(),
+    };
   } else if (value instanceof Scope) {
     return undefined;
   } else if (value && typeof value === "object") {
@@ -47,6 +62,8 @@ export async function deserialize(scope: Scope, value: any): Promise<any> {
         throw new Error("Cannot deserialize secret without password");
       }
       return new Secret(await decryptWithKey(value["@secret"], scope.password));
+    } else if ("@schema" in value) {
+      return value["@schema"];
     } else {
       return Object.fromEntries(
         await Promise.all(

package/src/vitepress/vitepress.ts

@@ -70,6 +70,19 @@ export interface VitePressProjectProps {
    * The home page configuration
    */
   home: HomePage;
+
+  /**
+   * Whether to delete the project folder during the delete phase
+   * @default true
+   */
+  delete?: boolean;
+
+  /**
+   * The directory to generate the docs in
+   *
+   * @default {@link name}
+   */
+  dir?: string;
 }
 
 export interface VitePressProject extends VitePressProjectProps, Resource {
@@ -89,11 +102,14 @@ export const VitePressProject = Resource(
     id: string,
     props: VitePressProjectProps,
   ): Promise<VitePressProject> {
+    const dir = props.dir ?? props.name;
     if (this.phase === "delete") {
       try {
-        if (await fs.exists(props.name)) {
-          // Delete the entire project directory
-          await execAsync(`rm -rf ${props.name}`);
+        if (props.delete !== false) {
+          if (await fs.exists(dir)) {
+            // Delete the entire project directory
+            await execAsync(`rm -rf ${dir}`);
+          }
         }
       } catch (error) {
         console.error(`Error deleting VitePress project ${id}:`, error);
@@ -101,7 +117,12 @@ export const VitePressProject = Resource(
       return this.destroy();
     }
 
-    const cwd = (await Folder(props.name)).path;
+    const cwd = (
+      await Folder("dir", {
+        path: dir,
+        delete: props.delete,
+      })
+    ).path;
 
     // Initialize package.json
     await JsonFile(path.join(cwd, "package.json"), {
@@ -142,28 +163,28 @@ export const VitePressProject = Resource(
         path.join(cwd, "index.md"),
         `---\n${yaml.stringify(props.home)}---\n`,
       ),
-      TypeScriptFile(
-        path.join(cwd, "alchemy.run.ts"),
-        `import alchemy from "alchemy";
-import { Folder } from "alchemy/fs";
-import { Document } from "alchemy/docs";
-import path from "path";
-
-await using _ = alchemy("alchemy.run", {
-  stage: "prod",
-  phase: process.argv.includes("--destroy") ? "destroy" : "up",
-  password: process.env.SECRET_PASSPHRASE,
-  quiet: !process.argv.includes("--verbose"),
-});
-
-const docs = await Folder(path.join("alchemy.run", "docs"));
-
-await Document("home.md", {
-  path: path.join(docs.path, "home.md"),
-  prompt: await alchemy\`Generate a landing page.\`,
-});
-`,
-      ),
+      //       TypeScriptFile(
+      //         path.join(cwd, "alchemy.run.ts"),
+      //         `import alchemy from "alchemy";
+      // import { Folder } from "alchemy/fs";
+      // import { Document } from "alchemy/docs";
+      // import path from "path";
+
+      // await using _ = alchemy("alchemy.run", {
+      //   stage: "prod",
+      //   phase: process.argv.includes("--destroy") ? "destroy" : "up",
+      //   password: process.env.SECRET_PASSPHRASE,
+      //   quiet: !process.argv.includes("--verbose"),
+      // });
+
+      // const docs = await Folder(path.join("alchemy.run", "docs"));
+
+      // await Document("home.md", {
+      //   path: path.join(docs.path, "home.md"),
+      //   prompt: await alchemy\`Generate a landing page.\`,
+      // });
+      // `,
+      //       ),
       TypeScriptFile(
         path.join(cwd, ".vitepress", "theme", "index.ts"),
         `import TwoslashFloatingVue from "@shikijs/vitepress-twoslash/client";

package/lib/docs/document.d.ts

@@ -1,123 +0,0 @@
-import type { Context } from "../context";
-import { Resource } from "../resource";
-import type { Secret } from "../secret";
-/**
- * Base properties for a Document
- */
-interface BaseDocumentProps {
-    /**
-     * Path to the markdown document
-     */
-    path: string;
-    /**
-     * Base URL for the OpenAI API
-     * @default 'https://api.openai.com/v1'
-     */
-    baseURL?: string;
-}
-/**
- * Properties for creating a document with static content
- */
-interface StaticDocumentProps extends BaseDocumentProps {
-    /**
-     * Static content of the document
-     */
-    content: string;
-    /**
-     * Prompt for generating content
-     * @internal This is marked as never to ensure content and prompt are mutually exclusive
-     */
-    prompt?: never;
-    /**
-     * OpenAI API key
-     * @internal This is marked as never since it's not needed for static content
-     */
-    apiKey?: never;
-    /**
-     * Model configuration
-     * @internal This is marked as never since it's not needed for static content
-     */
-    model?: never;
-    /**
-     * Context files
-     * @internal This is marked as never since it's not needed for static content
-     */
-    context?: never;
-}
-/**
- * Properties for creating a document with AI-generated content
- */
-interface GeneratedDocumentProps extends BaseDocumentProps {
-    /**
-     * Static content of the document
-     * @internal This is marked as never to ensure content and prompt are mutually exclusive
-     */
-    content?: never;
-    /**
-     * Prompt for generating content
-     * Can be either a single string or an array of strings that will be joined with newlines
-     */
-    prompt: string | string[];
-    /**
-     * Optional context files to include in the prompt
-     * Key is the relative path to the file
-     * Value can be either the content string or another Document resource
-     */
-    context?: {
-        [relativePath: string]: string | Document | {
-            path: string;
-            content: string;
-        };
-    };
-    /**
-     * OpenAI API key to use for generating content
-     * If not provided, will use OPENAI_API_KEY environment variable
-     */
-    apiKey?: Secret;
-    /**
-     * Model configuration
-     */
-    model?: {
-        /**
-         * Model ID to use
-         * @default 'gpt-4o'
-         */
-        id?: string;
-        /**
-         * Model provider name
-         * @default 'openai'
-         */
-        provider?: string;
-        /**
-         * Model-specific options
-         */
-        options?: Record<string, unknown>;
-    };
-}
-/**
- * Properties for creating or updating a Document
- * Must provide either static content or a prompt for AI generation
- */
-export type DocumentProps = StaticDocumentProps | GeneratedDocumentProps;
-/**
- * A markdown document that can be created, updated, and deleted
- */
-export interface Document extends Omit<DocumentProps, "content" | "prompt" | "context">, 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 markdown documents using the Vercel AI SDK
- */
-export declare const Document: ((this: Context<Document, DocumentProps>, id: string, props: DocumentProps) => Promise<Document>) | (((this: any, id: string, props?: DocumentProps | undefined) => never) & (new (_: never) => never));
-export {};

package/lib/docs/document.js

@@ -1,67 +0,0 @@
-import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
-import { generateText } from "ai";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { Resource } from "../resource";
-/**
- * Resource for managing markdown documents using the Vercel AI SDK
- */
-export const Document = Resource("docs::Document", async function (id, props) {
-    // Ensure directory exists
-    await fs.mkdir(path.dirname(props.path), { recursive: true });
-    if (this.phase === "delete") {
-        try {
-            await fs.unlink(props.path);
-        }
-        catch (error) {
-            // Ignore if file doesn't exist
-            if (error.code !== "ENOENT") {
-                throw error;
-            }
-        }
-        return this.destroy();
-    }
-    let content;
-    console.log("Generating content for", props.path);
-    // Generate content if prompt is provided
-    if ("prompt" in props) {
-        // Get API key from props or environment
-        const apiKey = props.apiKey?.unencrypted || process.env.OPENAI_API_KEY;
-        if (!apiKey) {
-            throw new Error("OpenAI API key is required for content generation");
-        }
-        // Initialize OpenAI compatible provider
-        const provider = createOpenAICompatible({
-            name: props.model?.provider || "openai",
-            apiKey,
-            baseURL: props.baseURL || "https://api.openai.com/v1",
-        });
-        // Build the full prompt with context if provided
-        const fullPrompt = Array.isArray(props.prompt)
-            ? props.prompt.join("\n")
-            : props.prompt;
-        // console.log(fullPrompt);
-        const { text } = await generateText({
-            model: provider(props.model?.id || "gpt-4o"),
-            prompt: fullPrompt,
-            ...(props.model?.options || {}),
-        });
-        content = text;
-    }
-    else {
-        // Use static content
-        content = props.content;
-    }
-    // Write content to file
-    await fs.writeFile(props.path, content);
-    // Get file stats for timestamps
-    const stats = await fs.stat(props.path);
-    // Return the resource
-    return this({
-        path: props.path,
-        baseURL: props.baseURL,
-        content,
-        createdAt: stats.birthtimeMs,
-        updatedAt: stats.mtimeMs,
-    });
-});

package/lib/docs/index.d.ts

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

package/lib/docs/index.js

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