alchemy 0.2.5 → 0.3.1

package/lib/web/vitepress/home-page.d.ts

@@ -0,0 +1,246 @@
+import { Document } from "../../ai/document";
+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 declare function parseHomePage(content: string): 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 declare function HomePage(id: string, props: HomePageProps): Promise<HomePage>;

package/lib/web/vitepress/home-page.js

@@ -0,0 +1,147 @@
+import yaml from "yaml";
+import { Document } from "../../ai/document";
+import { alchemy } from "../../alchemy";
+import { StaticTextFile } from "../../fs";
+/**
+ * Parse YAML frontmatter to home page config
+ */
+export function parseHomePage(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+        throw new Error("Invalid frontmatter format");
+    }
+    return yaml.parse(match[1]);
+}
+/**
+ * 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, props) {
+    // 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/lib/{vitepress → web/vitepress}/index.d.ts

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

package/lib/{vitepress → web/vitepress}/index.js

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

package/lib/{vitepress → web/vitepress}/vitepress.d.ts

@@ -1,7 +1,5 @@
-import type { DefaultTheme, ThemeOptions } from "vitepress";
-import type { Context } from "../context";
-import { Resource } from "../resource";
-import type { HomePage } from "./home-page";
+import type { Context } from "../../context";
+import { Resource } from "../../resource";
 export interface VitePressProjectProps {
     /**
      * The name/path of the project
@@ -20,6 +18,13 @@ export interface VitePressProjectProps {
      * @default true
      */
     typescript?: boolean;
+    /**
+     * The scripts to add to the project
+     */
+    scripts?: Record<string, string>;
+    /**
+     * The tsconfig to use
+     */
     tsconfig?: {
         extends?: string;
         references?: string[];
@@ -41,22 +46,16 @@ export interface VitePressProjectProps {
     /**
      * The theme options to use
      */
-    theme?: ThemeOptions;
     /**
      * The theme config to use
      */
-    themeConfig: DefaultTheme.Config;
-    /**
-     * 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
+     * The directory to initialize the project in.
      *
      * @default {@link name}
      */
@@ -67,5 +66,9 @@ export interface VitePressProject extends VitePressProjectProps, Resource {
      * The name/path of the project
      */
     name: string;
+    /**
+     * The directory of the project
+     */
+    dir: string;
 }
-export declare const VitePressProject: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<VitePressProject>, id: string, props: VitePressProjectProps) => Promise<VitePressProject>);
+export declare const VitepressProject: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<VitePressProject>, id: string, props: VitePressProjectProps) => Promise<VitePressProject>);

package/lib/{vitepress → web/vitepress}/vitepress.js

@@ -2,12 +2,11 @@ import { exec } from "child_process";
 import fs from "fs/promises";
 import path from "path";
 import { promisify } from "util";
-import yaml from "yaml";
-import { Folder, JsonFile, TextFile, TypeScriptFile } from "../fs";
-import { Resource } from "../resource";
+import { Folder, StaticJsonFile, StaticTextFile, StaticTypeScriptFile, } from "../../fs";
+import { Resource } from "../../resource";
 import { InstallDependencies, fixedDependencies } from "./dependencies";
 const execAsync = promisify(exec);
-export const VitePressProject = Resource("project::VitePressProject", {
+export const VitepressProject = Resource("project::VitepressProject", {
     alwaysUpdate: true,
 }, async function (id, props) {
     const dir = props.dir ?? props.name;
@@ -25,18 +24,19 @@ export const VitePressProject = Resource("project::VitePressProject", {
         }
         return this.destroy();
     }
-    const cwd = (await Folder("dir", {
+    const cwd = path.relative(process.cwd(), (await Folder("dir", {
         path: dir,
         delete: props.delete,
-    })).path;
+    })).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 || {}),
@@ -56,13 +56,19 @@ export const VitePressProject = Resource("project::VitePressProject", {
     await Folder(path.join(cwd, ".vitepress"));
     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";
@@ -82,7 +88,7 @@ export const VitePressProject = Resource("project::VitePressProject", {
         // });
         // `,
         //       ),
-        TypeScriptFile(path.join(cwd, ".vitepress", "theme", "index.ts"), `import TwoslashFloatingVue from "@shikijs/vitepress-twoslash/client";
+        StaticTypeScriptFile(path.join(cwd, ".vitepress", "theme", "index.ts"), `import TwoslashFloatingVue from "@shikijs/vitepress-twoslash/client";
 import "@shikijs/vitepress-twoslash/style.css";
 import type { Theme as ThemeConfig } from "vitepress";
 import Theme from "vitepress/theme-without-fonts";
@@ -95,7 +101,7 @@ export default {
   },
 } satisfies ThemeConfig;
   `),
-        TextFile(path.join(cwd, ".vitepress", "theme", "style.css"), `/**
+        StaticTextFile(path.join(cwd, ".vitepress", "theme", "style.css"), `/**
 * Customize default theme styling by overriding CSS variables:
 * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
 */
@@ -233,34 +239,10 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "type": "module",
   "module": "./lib/index.js",
   "scripts": {
@@ -14,13 +14,17 @@
     "./aws": "./lib/aws/index.js",
     "./aws/oidc": "./lib/aws/oidc/index.js",
     "./cloudflare": "./lib/cloudflare/index.js",
+    "./dns": "./lib/dns/index.js",
     "./esbuild": "./lib/esbuild/index.js",
     "./fs": "./lib/fs/index.js",
     "./github": "./lib/github/index.js",
     "./shadcn": "./lib/shadcn/index.js",
     "./stripe": "./lib/stripe/index.js",
     "./test/bun": "./lib/test/bun.js",
-    "./vite": "./lib/vite/index.js"
+    "./web/astro": "./lib/web/astro/index.js",
+    "./web/tailwind": "./lib/web/tailwind/index.js",
+    "./web/vite": "./lib/web/vite/index.js",
+    "./web/vitepress": "./lib/web/vitepress/index.js"
   },
   "peerDependencies": {
     "@ai-sdk/openai": "^1.1.9",