alchemy 0.2.5 → 0.3.1

package/src/web/vitepress/home-page.ts

@@ -0,0 +1,375 @@
+import yaml from "yaml";
+import { Document } from "../../ai/document";
+import { alchemy } from "../../alchemy";
+import { StaticTextFile } from "../../fs";
+import type { Secret } from "../../secret";
+
+/**
+ * Image that can be themed for light/dark mode
+ */
+export interface ThemeableImage {
+  /**
+   * Image source URL
+   */
+  src?: string;
+
+  /**
+   * Image alt text
+   */
+  alt?: string;
+
+  /**
+   * Light theme image URL
+   */
+  light?: string;
+
+  /**
+   * Dark theme image URL
+   */
+  dark?: string;
+}
+
+/**
+ * Hero action button configuration
+ */
+export interface HeroAction {
+  /**
+   * Color theme of the button
+   * @default "brand"
+   */
+  theme?: "brand" | "alt";
+
+  /**
+   * Label of the button
+   */
+  text: string;
+
+  /**
+   * Destination link of the button
+   */
+  link: string;
+
+  /**
+   * Link target attribute
+   */
+  target?: string;
+
+  /**
+   * Link rel attribute
+   */
+  rel?: string;
+}
+
+/**
+ * Hero section configuration
+ */
+export interface Hero {
+  /**
+   * The string shown top of text. Comes with brand color
+   * and expected to be short, such as product name.
+   */
+  name?: string;
+
+  /**
+   * The main text for the hero section. This will be defined
+   * as h1 tag.
+   */
+  text: string;
+
+  /**
+   * Tagline displayed below text
+   */
+  tagline?: string;
+
+  /**
+   * The image displayed next to the text and tagline area
+   */
+  image?: string | ThemeableImage;
+
+  /**
+   * Action buttons to display in home hero section
+   */
+  actions?: HeroAction[];
+}
+
+/**
+ * Feature item configuration
+ */
+export interface Feature {
+  /**
+   * Show icon on each feature box
+   */
+  icon?: string | ThemeableImage;
+
+  /**
+   * Title of the feature
+   */
+  title: string;
+
+  /**
+   * Details of the feature
+   */
+  details: string;
+
+  /**
+   * Link when clicked on feature component
+   */
+  link?: string;
+
+  /**
+   * Link text to be shown inside feature component
+   */
+  linkText?: string;
+
+  /**
+   * Link rel attribute
+   */
+  rel?: string;
+
+  /**
+   * Link target attribute
+   */
+  target?: string;
+}
+
+/**
+ * VitePress home page configuration
+ */
+export interface HomePageConfig {
+  /**
+   * Use home page layout
+   */
+  layout: "home";
+
+  /**
+   * Hero section configuration
+   */
+  hero?: Hero;
+
+  /**
+   * Features section configuration
+   */
+  features?: Feature[];
+
+  /**
+   * Whether to apply default markdown styles
+   * @default true
+   */
+  markdownStyles?: boolean;
+}
+
+/**
+ * Properties for creating or updating a VitePress HomePage
+ */
+export interface HomePageProps {
+  /**
+   * Output directory for the home page markdown file
+   */
+  outFile: string;
+
+  /**
+   * Title of the home page document
+   */
+  title: string;
+
+  /**
+   * Hero section configuration
+   */
+  hero?: Hero;
+
+  /**
+   * Features section configuration
+   */
+  features?: Feature[];
+
+  /**
+   * User prompt describing the design of the home page
+   */
+  prompt?: string;
+
+  /**
+   * Optional extension to the built-in system prompt
+   */
+  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 for the AI generator
+   */
+  model?: import("../../ai/client").ModelConfig;
+
+  /**
+   * Temperature for controlling randomness in generation
+   * @default 0.7
+   */
+  temperature?: number;
+}
+
+/**
+ * Output type for the HomePage resource
+ */
+export type HomePage = StaticTextFile | Document;
+
+/**
+ * Parse YAML frontmatter to home page config
+ */
+export function parseHomePage(content: string): HomePageConfig {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) {
+    throw new Error("Invalid frontmatter format");
+  }
+  return yaml.parse(match[1]) as HomePageConfig;
+}
+
+/**
+ * Resource for generating a VitePress homepage using AI.
+ * Creates an index.md file with the appropriate frontmatter and content
+ * based on the provided prompt and configuration.
+ *
+ * @example
+ * // Create a basic home page with just a prompt
+ * const homePage = await HomePage("docs-home", {
+ *   outDir: "./docs",
+ *   title: "My Project Documentation",
+ *   prompt: "Create a welcoming homepage for a JavaScript utility library with modern design"
+ * });
+ *
+ * @example
+ * // Create a home page with hero and features configuration
+ * const detailedHome = await HomePage("product-home", {
+ *   outDir: "./website",
+ *   title: "Product Landing Page",
+ *   prompt: "Create an engaging product page for our cloud database service",
+ *   hero: {
+ *     name: "CloudDB",
+ *     text: "The database built for the cloud era",
+ *     tagline: "Scalable, reliable, and developer-friendly",
+ *     image: "/images/cloud-db-logo.png",
+ *     actions: [
+ *       { text: "Get Started", link: "/guide/", theme: "brand" },
+ *       { text: "View on GitHub", link: "https://github.com/org/cloud-db" }
+ *     ]
+ *   },
+ *   features: [
+ *     {
+ *       icon: "🚀",
+ *       title: "Lightning Fast",
+ *       details: "Optimized for performance at any scale"
+ *     },
+ *     {
+ *       icon: "🔒",
+ *       title: "Secure by Default",
+ *       details: "Enterprise-grade security built in"
+ *     }
+ *   ]
+ * });
+ *
+ * @example
+ * // Create a home page with custom model settings
+ * const customHome = await HomePage("docs-home", {
+ *   outDir: "./docs",
+ *   title: "API Documentation",
+ *   prompt: "Create a technical homepage for our REST API documentation",
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   },
+ *   temperature: 0.3,
+ *   systemPromptExtension: "Make sure to use technical terminology appropriate for developers."
+ * });
+ */
+export async function HomePage(
+  id: string,
+  props: HomePageProps,
+): Promise<HomePage> {
+  // Build the system prompt with optional extension
+  const systemPrompt = `
+You are creating a VitePress homepage (index.md file).
+
+VitePress uses YAML frontmatter to configure the homepage.
+The homepage must have "layout: home" in its frontmatter.
+
+The homepage can include:
+- A hero section with name, text, tagline, image, and action buttons
+- A features section with multiple feature items (title, icon, details)
+- Additional markdown content below the frontmatter
+
+Follow these guidelines:
+1. Start with YAML frontmatter (--- at beginning and end)
+2. Include "layout: home" in the frontmatter
+3. Use the provided hero and features configuration if supplied
+4. Add any additional sections or content based on the user's prompt
+5. Create visually appealing, well-structured content
+6. Ensure all links are properly formatted
+7. Use appropriate markdown formatting for headings, lists, etc.
+
+${props.system || ""}
+`;
+
+  // Convert hero and features to YAML strings if provided
+  const heroYaml = props.hero ? JSON.stringify(props.hero, null, 2) : "";
+  const featuresYaml = props.features
+    ? JSON.stringify(props.features, null, 2)
+    : "";
+
+    if (props.prompt) {
+      return Document(id, {
+        title: props.title,
+        path: props.outFile,
+        baseURL: props.baseURL,
+        apiKey: props.apiKey,
+        model: props.model ?? {
+          id: "claude-3-7-sonnet-latest",
+          provider: "anthropic",
+        },
+        temperature: props.temperature ?? 0.7,
+        prompt: await alchemy`
+    ${systemPrompt}
+    
+    Create a VitePress homepage based on the following description:
+    ${props.prompt}
+    
+    ${
+      props.hero
+        ? `Use this hero section configuration:
+    \`\`\`json
+    ${heroYaml}
+    \`\`\``
+        : ""
+    }
+    
+    ${
+      props.features
+        ? `Use these features:
+    \`\`\`json
+    ${featuresYaml}
+    \`\`\``
+        : ""
+    }
+        
+        The output should be a complete index.md file with proper YAML frontmatter and markdown content.
+        `,
+      });
+  } else {
+    return StaticTextFile(id, props.outFile, `---
+${yaml.stringify({
+  layout: "home",
+  name: props.title,
+  hero: props.hero,
+  features: props.features,
+})}
+---
+`);
+  }
+}

package/src/{vitepress → web/vitepress}/index.ts

@@ -1,2 +1,4 @@
+export * from "./config";
+export * from "./custom-theme";
 export * from "./home-page";
 export * from "./vitepress";

package/src/{vitepress → web/vitepress}/vitepress.ts

@@ -2,13 +2,15 @@ import { exec } from "child_process";
 import fs from "fs/promises";
 import path from "path";
 import { promisify } from "util";
-import type { DefaultTheme, ThemeOptions } from "vitepress";
-import yaml from "yaml";
-import type { Context } from "../context";
-import { Folder, JsonFile, TextFile, TypeScriptFile } from "../fs";
-import { Resource } from "../resource";
+import type { Context } from "../../context";
+import {
+  Folder,
+  StaticJsonFile,
+  StaticTextFile,
+  StaticTypeScriptFile,
+} from "../../fs";
+import { Resource } from "../../resource";
 import { InstallDependencies, fixedDependencies } from "./dependencies";
-import type { HomePage } from "./home-page";
 
 const execAsync = promisify(exec);
 
@@ -34,6 +36,14 @@ export interface VitePressProjectProps {
    */
   typescript?: boolean;
 
+  /**
+   * The scripts to add to the project
+   */
+  scripts?: Record<string, string>;
+
+  /**
+   * The tsconfig to use
+   */
   tsconfig?: {
     extends?: string;
     references?: string[];
@@ -59,17 +69,12 @@ export interface VitePressProjectProps {
   /**
    * The theme options to use
    */
-  theme?: ThemeOptions;
+  // theme?: ThemeOptions;
 
   /**
    * The theme config to use
    */
-  themeConfig: DefaultTheme.Config;
-
-  /**
-   * The home page configuration
-   */
-  home: HomePage;
+  // themeConfig: DefaultTheme.Config;
 
   /**
    * Whether to delete the project folder during the delete phase
@@ -78,7 +83,7 @@ export interface VitePressProjectProps {
   delete?: boolean;
 
   /**
-   * The directory to generate the docs in
+   * The directory to initialize the project in.
    *
    * @default {@link name}
    */
@@ -90,17 +95,22 @@ export interface VitePressProject extends VitePressProjectProps, Resource {
    * The name/path of the project
    */
   name: string;
+
+  /**
+   * The directory of the project
+   */
+  dir: string;
 }
 
-export const VitePressProject = Resource(
-  "project::VitePressProject",
+export const VitepressProject = Resource(
+  "project::VitepressProject",
   {
     alwaysUpdate: true,
   },
   async function (
     this: Context<VitePressProject>,
     id: string,
-    props: VitePressProjectProps,
+    props: VitePressProjectProps
   ): Promise<VitePressProject> {
     const dir = props.dir ?? props.name;
     if (this.phase === "delete") {
@@ -117,21 +127,25 @@ export const VitePressProject = Resource(
       return this.destroy();
     }
 
-    const cwd = (
-      await Folder("dir", {
-        path: dir,
-        delete: props.delete,
-      })
-    ).path;
+    const cwd = path.relative(
+      process.cwd(),
+      (
+        await Folder("dir", {
+          path: dir,
+          delete: props.delete,
+        })
+      ).path
+    );
 
     // Initialize package.json
-    await JsonFile(path.join(cwd, "package.json"), {
+    await StaticJsonFile(path.join(cwd, "package.json"), {
       name: props.name,
       scripts: {
         "docs:gen": "bun alchemy.run.ts",
         "docs:dev": "vitepress dev",
         "docs:build": "vitepress build",
         "docs:preview": "vitepress preview",
+        ...props.scripts,
       },
       dependencies: fixedDependencies(props.dependencies || {}),
       devDependencies: fixedDependencies(props.devDependencies || {}),
@@ -153,16 +167,21 @@ export const VitePressProject = Resource(
     await Folder(path.join(cwd, ".vitepress", "theme"));
 
     await Promise.all([
-      TextFile(path.join(cwd, ".gitignore"), `.vitepress/cache\n`),
-      JsonFile(path.join(cwd, "tsconfig.json"), {
-        extends: props.tsconfig?.extends,
-        references: props.tsconfig?.references?.map((path) => ({ path })),
-        compilerOptions: props.tsconfig?.compilerOptions,
-      }),
-      TextFile(
-        path.join(cwd, "index.md"),
-        `---\n${yaml.stringify(props.home)}---\n`,
-      ),
+      StaticTextFile(path.join(cwd, ".gitignore"), `.vitepress/cache\n`),
+      // StaticJsonFile(path.join(cwd, "tsconfig.json"), {
+      //   extends: props.tsconfig?.extends,
+      //   references: props.tsconfig?.references?.map((path) => ({ path })),
+      //   compilerOptions: props.tsconfig?.compilerOptions ?? {
+      //     target: "ES2020",
+      //     module: "ESNext",
+      //     moduleResolution: "Node",
+      //     allowJs: true,
+      //     skipLibCheck: true,
+      //     forceConsistentCasingInFileNames: true,
+
+      //   },
+      // }),
+
       //       TypeScriptFile(
       //         path.join(cwd, "alchemy.run.ts"),
       //         `import alchemy from "alchemy";
@@ -185,7 +204,7 @@ export const VitePressProject = Resource(
       // });
       // `,
       //       ),
-      TypeScriptFile(
+      StaticTypeScriptFile(
         path.join(cwd, ".vitepress", "theme", "index.ts"),
         `import TwoslashFloatingVue from "@shikijs/vitepress-twoslash/client";
 import "@shikijs/vitepress-twoslash/style.css";
@@ -199,9 +218,9 @@ export default {
     ctx.app.use(TwoslashFloatingVue);
   },
 } satisfies ThemeConfig;
-  `,
+  `
       ),
-      TextFile(
+      StaticTextFile(
         path.join(cwd, ".vitepress", "theme", "style.css"),
         `/**
 * Customize default theme styling by overriding CSS variables:
@@ -341,42 +360,13 @@ export default {
 .DocSearch {
   --docsearch-primary-color: var(--vp-c-brand-1) !important;
 }
-`,
-      ),
-      TypeScriptFile(
-        path.join(cwd, ".vitepress", "config.mts"),
-        `import { transformerTwoslash } from "@shikijs/vitepress-twoslash";
-import footnotePlugin from "markdown-it-footnote";
-import { defineConfig } from "vitepress";
-
-// https://vitepress.dev/reference/site-config
-export default defineConfig({
-  title: ${JSON.stringify(props.title || "Alchemy")},
-  description: ${JSON.stringify(props.description || "Alchemy Docs")},
-  markdown: {
-    // @ts-ignore
-    codeTransformers: [transformerTwoslash()],
-    theme: ${JSON.stringify(
-      props.theme ?? {
-        light: "light-plus",
-        dark: "dark-plus",
-      },
-    )},
-    config: (md) => md.use(footnotePlugin),
-  },
-  // https://vitepress.dev/reference/default-theme-config
-  themeConfig: ${JSON.stringify({
-    ...props.themeConfig,
-    search: props.themeConfig.search ?? { provider: "local" },
-    nav: props.themeConfig.nav ?? [{ text: "Home", link: "/" }],
-    sidebar: props.themeConfig.sidebar ?? [],
-    socialLinks: props.themeConfig.socialLinks ?? [],
-  })}
-});
-`,
+`
       ),
     ]);
 
-    return this(props);
-  },
+    return this({
+      ...props,
+      dir,
+    });
+  }
 );

package/lib/cloudflare/state.d.ts

@@ -1,82 +0,0 @@
-import type { KVNamespace } from "@cloudflare/workers-types";
-import type { State, StateStore } from "../state";
-/**
- * Options for CloudflareStateStore
- */
-export interface CloudflareStateStoreOptions {
-    /**
-     * The prefix to use for keys in the KV namespace
-     * This allows multiple state stores to use the same KV namespace
-     */
-    prefix?: string;
-}
-/**
- * State store implementation using Cloudflare KV Namespace
- */
-export declare class CloudflareStateStore implements StateStore {
-    private namespace;
-    private prefix;
-    /**
-     * Create a new CloudflareStateStore
-     *
-     * @param namespace The KV namespace to use for storing state
-     * @param options Options for the state store
-     */
-    constructor(namespace: KVNamespace, options?: CloudflareStateStoreOptions);
-    /**
-     * No initialization needed for KV namespaces as they are pre-provisioned
-     */
-    init(): Promise<void>;
-    /**
-     * KV namespaces cannot be deleted programmatically
-     */
-    deinit(): Promise<void>;
-    /**
-     * List all resources in the state store
-     */
-    list(): Promise<string[]>;
-    /**
-     * Count the number of items in the state store
-     */
-    count(): Promise<number>;
-    /**
-     * Get a state by key
-     *
-     * @param key The key to look up
-     * @returns The state or undefined if not found
-     */
-    get(key: string): Promise<State | undefined>;
-    /**
-     * Get multiple states by their keys
-     *
-     * @param ids Array of keys to fetch
-     * @returns Record mapping keys to their states
-     */
-    getBatch(ids: string[]): Promise<Record<string, State>>;
-    /**
-     * Get all states in the store
-     *
-     * @returns Record mapping all keys to their states
-     */
-    all(): Promise<Record<string, State>>;
-    /**
-     * Set a state for a key
-     *
-     * @param key The key to set
-     * @param value The state to store
-     */
-    set(key: string, value: State): Promise<void>;
-    /**
-     * Delete a state by key
-     *
-     * @param key The key to delete
-     */
-    delete(key: string): Promise<void>;
-    /**
-     * Get the namespaced key for storage
-     *
-     * @param key The original key
-     * @returns The key with prefix for use in the KV namespace
-     */
-    private getNamespacedKey;
-}