alchemy 0.2.5 → 0.3.0

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

@@ -0,0 +1,363 @@
+import alchemy from "alchemy";
+import yaml from "yaml";
+import { Document } from "../../ai/document";
+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
+   */
+  systemPromptExtension?: 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 = import("../../ai/document").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.systemPromptExtension || ""}
+`;
+
+  // 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)
+    : "";
+
+  // Create the document using the AI Document resource
+  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.
+    `,
+  });
+}

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

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

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

@@ -3,12 +3,15 @@ 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 +37,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[];
@@ -66,11 +77,6 @@ export interface VitePressProjectProps {
    */
   themeConfig: DefaultTheme.Config;
 
-  /**
-   * The home page configuration
-   */
-  home: HomePage;
-
   /**
    * Whether to delete the project folder during the delete phase
    * @default true
@@ -78,7 +84,7 @@ export interface VitePressProjectProps {
   delete?: boolean;
 
   /**
-   * The directory to generate the docs in
+   * The directory to initialize the project in.
    *
    * @default {@link name}
    */
@@ -117,21 +123,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 +163,13 @@ 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"), {
+      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,
       }),
-      TextFile(
-        path.join(cwd, "index.md"),
-        `---\n${yaml.stringify(props.home)}---\n`,
-      ),
+
       //       TypeScriptFile(
       //         path.join(cwd, "alchemy.run.ts"),
       //         `import alchemy from "alchemy";
@@ -185,7 +192,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";
@@ -201,7 +208,7 @@ export default {
 } satisfies ThemeConfig;
   `,
       ),
-      TextFile(
+      StaticTextFile(
         path.join(cwd, ".vitepress", "theme", "style.css"),
         `/**
 * Customize default theme styling by overriding CSS variables:
@@ -343,7 +350,7 @@ export default {
 }
 `,
       ),
-      TypeScriptFile(
+      StaticTypeScriptFile(
         path.join(cwd, ".vitepress", "config.mts"),
         `import { transformerTwoslash } from "@shikijs/vitepress-twoslash";
 import footnotePlugin from "markdown-it-footnote";

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;
-}

package/lib/cloudflare/state.js

@@ -1,108 +0,0 @@
-/**
- * State store implementation using Cloudflare KV Namespace
- */
-export class CloudflareStateStore {
-    namespace;
-    prefix;
-    /**
-     * Create a new CloudflareStateStore
-     *
-     * @param namespace The KV namespace to use for storing state
-     * @param options Options for the state store
-     */
-    constructor(namespace, options = {}) {
-        this.namespace = namespace;
-        this.prefix = options.prefix || "alchemy-state:";
-    }
-    /**
-     * No initialization needed for KV namespaces as they are pre-provisioned
-     */
-    async init() {
-        // KV namespaces are pre-provisioned in Cloudflare, so no initialization is needed
-    }
-    /**
-     * KV namespaces cannot be deleted programmatically
-     */
-    async deinit() {
-        // KV namespaces can only be deleted through the Cloudflare dashboard or API
-        // We cannot delete the namespace itself here
-    }
-    /**
-     * List all resources in the state store
-     */
-    async list() {
-        const list = await this.namespace.list({ prefix: this.prefix });
-        return list.keys.map((key) => key.name.slice(this.prefix.length));
-    }
-    /**
-     * Count the number of items in the state store
-     */
-    async count() {
-        const list = await this.namespace.list({ prefix: this.prefix });
-        return list.keys.length;
-    }
-    /**
-     * Get a state by key
-     *
-     * @param key The key to look up
-     * @returns The state or undefined if not found
-     */
-    async get(key) {
-        const data = await this.namespace.get(this.getNamespacedKey(key), "json");
-        return data;
-    }
-    /**
-     * Get multiple states by their keys
-     *
-     * @param ids Array of keys to fetch
-     * @returns Record mapping keys to their states
-     */
-    async getBatch(ids) {
-        const result = {};
-        // KV doesn't have a native batch get operation, so we need to make multiple requests
-        // We could optimize this with Promise.all for parallel fetching
-        const promises = ids.map(async (id) => {
-            const state = await this.get(id);
-            if (state) {
-                result[id] = state;
-            }
-        });
-        await Promise.all(promises);
-        return result;
-    }
-    /**
-     * Get all states in the store
-     *
-     * @returns Record mapping all keys to their states
-     */
-    async all() {
-        const keys = await this.list();
-        return this.getBatch(keys);
-    }
-    /**
-     * Set a state for a key
-     *
-     * @param key The key to set
-     * @param value The state to store
-     */
-    async set(key, value) {
-        await this.namespace.put(this.getNamespacedKey(key), JSON.stringify(value));
-    }
-    /**
-     * Delete a state by key
-     *
-     * @param key The key to delete
-     */
-    async delete(key) {
-        await this.namespace.delete(this.getNamespacedKey(key));
-    }
-    /**
-     * Get the namespaced key for storage
-     *
-     * @param key The original key
-     * @returns The key with prefix for use in the KV namespace
-     */
-    getNamespacedKey(key) {
-        return `${this.prefix}${key}`;
-    }
-}

package/lib/fs/json-file.js

@@ -1,7 +0,0 @@
-import { File } from "./file";
-export function JsonFile(id, content) {
-    return File(id, {
-        path: id,
-        content: JSON.stringify(content, null, 2),
-    });
-}

package/lib/internal/docs.d.ts

@@ -1,5 +0,0 @@
-export interface DocsProps {
-    docs?: boolean | number;
-}
-export type AlchemyDocs = Awaited<ReturnType<typeof AlchemyDocs>>;
-export declare function AlchemyDocs({ docs: isDocsEnabled }: DocsProps): Promise<void>;