alchemy 0.2.5 → 0.3.0

package/lib/web/vitepress/custom-theme.js

@@ -0,0 +1,336 @@
+import { type } from "arktype";
+import path from "path";
+import { CSSFile } from "../../ai/css-file";
+import { Data } from "../../ai/data";
+import { TypeScriptFile } from "../../ai/typescript-file";
+import { VueFile } from "../../ai/vue-file";
+import { alchemy } from "../../alchemy";
+import { Folder } from "../../fs";
+import { Resource } from "../../resource";
+/**
+ * Resource for generating a custom VitePress theme using AI.
+ *
+ * Generates the necessary theme files including:
+ * - Theme entry file (index.ts)
+ * - Layout component (Layout.vue)
+ * - Additional components based on configuration
+ * - Style sheets and utilities
+ *
+ * @example
+ * // Create a basic custom theme
+ * const theme = await CustomTheme("docs-theme", {
+ *   outDir: "./.vitepress/theme",
+ *   title: "My Custom Theme",
+ *   description: "A clean, minimal theme for documentation",
+ *   prompt: "Create a clean documentation theme with a sidebar and search"
+ * });
+ *
+ * @example
+ * // Create a theme with specific components
+ * const complexTheme = await CustomTheme("blog-theme", {
+ *   outDir: "./.vitepress/theme",
+ *   title: "Blog Theme",
+ *   description: "A theme for technical blogs",
+ *   components: [
+ *     {
+ *       name: "PostList",
+ *       description: "Component that displays a list of blog posts with pagination",
+ *       features: ["thumbnail images", "post dates", "categories", "excerpts"]
+ *     },
+ *     {
+ *       name: "TableOfContents",
+ *       description: "Component that displays the current page's table of contents",
+ *       features: ["sticky positioning", "active link highlighting"]
+ *     }
+ *   ],
+ *   darkMode: true,
+ *   prompt: "Create a modern blog theme with post listings and detailed article pages"
+ * });
+ *
+ * @example
+ * // Create a theme with custom CSS variables
+ * const brandedTheme = await CustomTheme("branded-theme", {
+ *   outDir: "./.vitepress/theme",
+ *   title: "Branded Docs",
+ *   description: "A themed documentation site with custom branding",
+ *   customCssVars: {
+ *     "--vp-c-brand": "#3a70b0",
+ *     "--vp-c-brand-light": "#5785bc",
+ *     "--vp-c-brand-lighter": "#79a1ce",
+ *     "--vp-c-brand-dark": "#2c5989",
+ *     "--vp-c-brand-darker": "#1e3d5c"
+ *   },
+ *   prompt: "Create a documentation theme with custom branding and color scheme"
+ * });
+ */
+export const CustomTheme = Resource("vitepress::CustomTheme", async function (id, props) {
+    // Handle deletion
+    if (this.phase === "delete") {
+        // No need to actually delete files, as they're not critical infrastructure
+        // In a real implementation, you might want to clean up files
+        return this.destroy();
+    }
+    // Ensure the output directory exists
+    await Folder(props.outDir);
+    // Create components directory if it doesn't exist
+    await Folder(path.join(props.outDir, "components"));
+    // Build the system prompt with optional extension
+    const systemPrompt = `
+You are creating a custom VitePress theme.
+
+A VitePress custom theme consists of multiple files:
+1. An entry file (index.ts or index.js) that exports the theme object
+2. A Layout component (Layout.vue) that handles the overall page structure
+3. Optional additional Vue components for specific functionality
+4. Optional style files for theming and customization
+
+The theme entry file must export an object with:
+- Layout: The root layout component (required)
+- enhanceApp: Function to enhance the Vue app (optional)
+- extends: Another theme to extend (optional)
+
+Follow these guidelines:
+1. Use Vue 3 Composition API and <script setup> syntax
+2. Ensure the theme is SSR-compatible
+3. Use the useData() composable to access page and site data
+4. Handle different page layouts (home, 404, regular pages)
+5. Include proper TypeScript types
+6. Use modern JavaScript/TypeScript features
+7. Include clear comments explaining key functionality
+8. Make components reusable and customizable
+9. Include support for dark mode if requested
+
+${props.systemPromptExtension || ""}
+`;
+    // Generate the theme entry file (index.ts)
+    const indexFile = await TypeScriptFile(`${id}-index`, {
+        path: path.join(props.outDir, "index.ts"),
+        prompt: await alchemy `
+Create a VitePress theme entry file (index.ts) for a theme named "${props.title}".
+
+The theme should:
+- Export a default theme object with the required properties
+- Import the Layout component
+- Include a proper enhanceApp function
+- Include TypeScript types
+- Have clear comments explaining the code
+
+${props.description ? `Theme description: ${props.description}` : ""}
+${props.plugins?.length ? `Include these plugins: ${props.plugins.join(", ")}` : ""}
+
+The output should be a complete, well-structured TypeScript file.
+`,
+        system: `${systemPrompt}
+You are writing a TypeScript entry file for a VitePress theme.`,
+        baseURL: props.baseURL,
+        apiKey: props.apiKey,
+        model: props.model,
+        temperature: props.temperature,
+    });
+    // Generate the Layout component
+    const layoutFile = await VueFile(`${id}-layout`, {
+        path: path.join(props.outDir, "Layout.vue"),
+        prompt: await alchemy `
+Create a Layout.vue component for a VitePress theme named "${props.title}".
+
+The layout should:
+- Use <script setup> with the Composition API
+- Import and use the useData() composable
+- Handle different page types (regular pages, home pages, 404 pages)
+- Include a <Content /> component to render the page content
+- Have a clean, modern design
+- Include proper TypeScript types
+- Use Vue's Teleport for elements like modals if needed
+
+The layout should use modular components for different parts of the UI, such as:
+- NavBar/Header component for navigation
+- Sidebar component for documentation navigation
+- Footer component
+- Home page specific components (like hero sections)
+- 404 page component
+
+These components should be imported from the components directory.
+
+${props.description ? `Theme description: ${props.description}` : ""}
+${props.darkMode !== false ? "Include support for dark mode" : "Dark mode is not required"}
+
+The layout should follow the user's requirements:
+${props.prompt}
+
+The output should be a complete, well-structured Vue component file.
+`,
+        system: `${systemPrompt}
+You are writing a Vue component for a VitePress theme Layout.
+Import smaller components from the components directory using relative paths (e.g., import NavBar from './components/NavBar.vue').
+Break down the layout into logical components like NavBar, Sidebar, Footer, etc., which will be generated separately.`,
+        baseURL: props.baseURL,
+        apiKey: props.apiKey,
+        model: props.model,
+        temperature: props.temperature,
+    });
+    // Extract component imports from the Layout.vue file
+    const componentImportsData = await Data(`${id}-component-imports`, {
+        schema: type({
+            components: type({
+                name: type("string").describe("Component name as used in the import statement (e.g., NavBar, Footer)"),
+                path: type("string").describe("Import path as written in the import statement (e.g., './components/NavBar.vue')"),
+                purpose: type("string").describe("A clear description of the component's purpose, functionality, and responsibilities in the layout"),
+            }).array(),
+        }),
+        prompt: await alchemy `
+Analyze the following Layout.vue file and extract information about all the component imports:
+
+${layoutFile.content}
+
+For each component import:
+1. Extract the component name (e.g., NavBar)
+2. Extract the import path (e.g., ./components/NavBar.vue)
+3. Infer the purpose of the component based on its name and usage in the file
+
+Return a structured list of all component imports found in the file.
+Only include components that are imported from local files (not from VitePress or other libraries).
+Focus on components that are likely Vue components (.vue files).
+`,
+        system: "You are a code analyzer tasked with extracting component imports from a Vue file. Be precise and thorough in identifying all local component imports.",
+        baseURL: props.baseURL,
+        apiKey: props.apiKey,
+        model: props.model,
+        temperature: props.temperature || 0.2, // Lower temperature for more deterministic extraction
+    });
+    // Generate the detected components
+    const autoComponentFiles = await Promise.all(componentImportsData.object.components.map(async (component) => {
+        const componentName = component.name;
+        const componentPath = component.path;
+        const componentPurpose = component.purpose;
+        // Extract the relative path from the import
+        const relativePath = componentPath.startsWith("./")
+            ? componentPath.slice(2) // Remove './'
+            : componentPath.startsWith("/")
+                ? componentPath.slice(1) // Remove '/'
+                : componentPath;
+        // Compute the full file path
+        const fullPath = path.join(props.outDir, relativePath);
+        return VueFile(`${id}-component-${componentName}`, {
+            path: fullPath,
+            prompt: await alchemy `
+Create a Vue component named "${componentName}" for a VitePress theme.
+
+Component purpose: ${componentPurpose}
+
+The component should:
+- Use <script setup> with the Composition API
+- Have a clean, focused design for its specific purpose
+- Include proper TypeScript types
+- Be reusable and customizable
+- Include clear comments explaining key functionality
+- Fit seamlessly with the overall theme design described below
+
+This component will be used in the following layout context:
+${layoutFile.content}
+
+${props.description ? `Theme description: ${props.description}` : ""}
+${props.darkMode !== false ? "Include support for dark mode" : "Dark mode is not required"}
+
+The component should follow the user's theme requirements:
+${props.prompt}
+`,
+            system: `${systemPrompt}
+You are writing a Vue component for a VitePress theme. This component (${componentName}) is intended to ${componentPurpose}.
+Make sure it integrates well with the overall layout and theme style.`,
+            baseURL: props.baseURL,
+            apiKey: props.apiKey,
+            model: props.model,
+            temperature: props.temperature,
+        });
+    }));
+    // Generate user-specified components if provided
+    const userComponentFiles = await Promise.all((props.components || []).map(async (component) => {
+        return VueFile(`${id}-user-component-${component.name}`, {
+            path: path.join(props.outDir, "components", `${component.name}.vue`),
+            prompt: await alchemy `
+Create a Vue component named "${component.name}" for a VitePress theme.
+
+Component description: ${component.description}
+
+The component should:
+- Use <script setup> with the Composition API
+- Have a clean, focused design for its specific purpose
+- Include proper TypeScript types
+- Be reusable and customizable
+- Include clear comments
+
+${component.features?.length
+                ? `Include these features:
+${component.features.map((f) => `- ${f}`).join("\n")}`
+                : ""}
+
+Make sure the component integrates well with the overall theme.
+
+The output should be a complete, well-structured Vue component file.
+`,
+            system: `${systemPrompt}
+You are writing a Vue component for a VitePress theme.`,
+            baseURL: props.baseURL,
+            apiKey: props.apiKey,
+            model: props.model,
+            temperature: props.temperature,
+        });
+    }));
+    // Generate styles file
+    const stylesFile = await CSSFile(`${id}-styles`, {
+        path: path.join(props.outDir, "styles.css"),
+        prompt: await alchemy `
+Create a CSS styles file for a VitePress theme named "${props.title}".
+
+The styles should:
+- Define a cohesive set of styles for the theme
+- Include CSS variables for customization
+- Use modern CSS features
+- Be well-organized with clear comments
+${props.darkMode !== false ? "- Include dark mode variants using :root.dark selectors" : ""}
+
+${props.description ? `Theme description: ${props.description}` : ""}
+
+${props.customCssVars
+            ? `Include these custom CSS variables:
+${Object.entries(props.customCssVars)
+                .map(([key, value]) => `${key}: ${value};`)
+                .join("\n")}`
+            : ""}
+
+Style according to the user's requirements:
+${props.prompt}
+
+The output should be a complete, well-structured CSS file.
+`,
+        system: `${systemPrompt}
+You are writing CSS styles for a VitePress theme.`,
+        baseURL: props.baseURL,
+        apiKey: props.apiKey,
+        model: props.model,
+        temperature: props.temperature,
+    });
+    // Collect all generated files
+    const allFiles = [
+        indexFile,
+        layoutFile,
+        ...autoComponentFiles,
+        ...userComponentFiles,
+        stylesFile,
+    ];
+    // Create file objects for resource output
+    const files = allFiles.map((file) => ({
+        path: file.path,
+        content: file.content,
+    }));
+    // Get the current timestamp
+    const now = Date.now();
+    // Return the resource using this() to construct output
+    return this({
+        ...props,
+        themePath: props.outDir,
+        files,
+        createdAt: this.output?.createdAt || now,
+        updatedAt: now,
+    });
+});

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

@@ -1,5 +1,5 @@
-import type { Context } from "../context";
-import { Resource } from "../resource";
+import type { Context } from "../../context";
+import { Resource } from "../../resource";
 export type InstallDependencies = Resource<"project::InstallDependencies">;
 export declare const InstallDependencies: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<InstallDependencies>, id: string, { cwd, dependencies, devDependencies, }: {
     cwd: string;

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

@@ -1,6 +1,6 @@
 import { exec } from "child_process";
 import { promisify } from "util";
-import { Resource } from "../resource";
+import { Resource } from "../../resource";
 const execAsync = promisify(exec);
 export const InstallDependencies = Resource("project::InstallDependencies", {
     alwaysUpdate: true,

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

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