alchemy 0.2.2 → 0.2.3

package/src/docs/document.ts

@@ -0,0 +1,225 @@
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { generateText } from "ai";
+import fs from "node:fs/promises";
+import path from "node:path";
+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 const Document = Resource(
+  "docs::Document",
+  async function (
+    this: Context<Document, DocumentProps>,
+    id: string,
+    props: DocumentProps,
+  ): Promise<Document> {
+    // Ensure directory exists
+    await fs.mkdir(path.dirname(props.path), { recursive: true });
+
+    if (this.phase === "delete") {
+      try {
+        await fs.unlink(props.path);
+      } catch (error: any) {
+        // Ignore if file doesn't exist
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
+      }
+      return this.destroy();
+    }
+
+    let content: string;
+
+    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/src/docs/index.ts

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

package/src/fs/file.ts

@@ -4,6 +4,69 @@ import type { Context } from "../context";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
 
+import { alchemy } from "../alchemy";
+
+declare module "../alchemy" {
+  interface Alchemy {
+    file(path: string): Promise<FileRef>;
+    files(paths: string[]): Promise<FileCollection>;
+    files(path: string, ...paths: string[]): Promise<FileCollection>;
+  }
+}
+
+export type FileRef = {
+  kind: "fs::FileRef";
+  path: string;
+};
+
+export function isFileRef(value: unknown): value is FileRef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "kind" in value &&
+    value.kind === "fs::FileRef"
+  );
+}
+
+export type FileCollection = {
+  type: "fs::FileCollection";
+  files: {
+    [relativePath: string]: string;
+  };
+};
+
+export function isFileCollection(value: unknown): value is FileCollection {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "type" in value &&
+    value.type === "fs::FileCollection"
+  );
+}
+
+alchemy.file = async (path: string) => ({
+  kind: "fs::FileRef",
+  path,
+});
+
+alchemy.files = async (
+  ...args: [paths: string[]] | [...paths: string[]]
+): Promise<FileCollection> => {
+  const paths: string[] =
+    typeof args[0] === "string" ? (args as string[]) : args[0];
+  return {
+    type: "fs::FileCollection",
+    files: Object.fromEntries(
+      await Promise.all(
+        paths.map(async (path) => [
+          path,
+          await fs.promises.readFile(path, "utf-8"),
+        ]),
+      ),
+    ),
+  };
+};
+
 export interface File extends Resource<"fs::File"> {
   path: string;
   content: string;
@@ -14,14 +77,12 @@ export const File = Resource(
   async function (
     this: Context<File>,
     id: string,
-    {
-      path: filePath,
-      content,
-    }: {
+    props: {
       path: string;
       content: string;
     },
   ): Promise<File> {
+    const filePath = props?.path ?? id;
     if (this.phase === "delete") {
       await ignore("ENOENT", async () => fs.promises.unlink(filePath));
       return this.destroy();
@@ -29,11 +90,58 @@ export const File = Resource(
       await fs.promises.mkdir(path.dirname(filePath), {
         recursive: true,
       });
-      await fs.promises.writeFile(filePath, content);
+      await fs.promises.writeFile(filePath, props.content);
     }
     return this({
       path: filePath,
-      content,
+      content: props.content,
     });
   },
 );
+
+export type JsonFile = File;
+
+export function JsonFile(id: string, content: any): Promise<JsonFile> {
+  return File(id, {
+    path: id,
+    content: JSON.stringify(content, null, 2),
+  });
+}
+
+export type TextFile = File;
+
+export function TextFile(id: string, content: string): Promise<TextFile> {
+  return File(id, {
+    path: id,
+    content,
+  });
+}
+
+export type YamlFile = File;
+
+export async function YamlFile(id: string, content: any): Promise<YamlFile> {
+  const yaml = await import("yaml");
+  return File(id, {
+    path: id,
+    content: yaml.stringify(content),
+  });
+}
+
+export type TypeScriptFile = File;
+
+export async function TypeScriptFile(
+  id: string,
+  content: string,
+): Promise<TypeScriptFile> {
+  const prettier = await import("prettier");
+  return File(id, {
+    path: id,
+    content: await prettier.format(content, {
+      parser: "typescript",
+      editor: {
+        tabWidth: 2,
+        indentWidth: 2,
+      },
+    }),
+  });
+}

package/src/fs/folder.ts

@@ -12,8 +12,9 @@ export const Folder = Resource(
   async function (
     this: Context<Folder>,
     id: string,
-    { path: dirPath }: { path: string },
+    props?: { path: string },
   ): Promise<Folder> {
+    const dirPath = props?.path ?? id;
     if (this.phase === "delete") {
       // we just do a best effort attempt
       await ignore(["ENOENT", "ENOTEMPTY"], async () =>

package/src/resource.ts

@@ -67,7 +67,7 @@ type IsClass = {
 };
 
 type ResourceLifecycleHandler = (
-  this: Context<any>,
+  this: Context<any, any>,
   id: string,
   props: any,
 ) => Promise<Resource<string>>;
@@ -75,7 +75,7 @@ type ResourceLifecycleHandler = (
 // see: https://x.com/samgoodwin89/status/1904640134097887653
 type Handler<F extends (...args: any[]) => any> =
   | F
-  | (((this: any, id: string, props: Parameters<F>[1]) => never) & IsClass);
+  | (((this: any, id: string, props?: Parameters<F>[1]) => never) & IsClass);
 
 export function Resource<
   const Type extends string,
@@ -104,6 +104,11 @@ export function Resource<
   ): Promise<Resource<string>> => {
     const scope = _Scope.current;
 
+    if (resourceID.includes(":")) {
+      // we want to use : as an internal separator for resources
+      throw new Error(`ID cannot include colons: ${resourceID}`);
+    }
+
     if (scope.resources.has(resourceID)) {
       // TODO(sam): do we want to throw?
       // it's kind of awesome that you can re-create a resource and call apply

package/src/scope.ts

@@ -98,6 +98,14 @@ export class Scope {
     return [...this.chain, resourceID].join("/");
   }
 
+  public async run<T>(fn: (scope: Scope) => Promise<T>): Promise<T> {
+    return scopeStorage.run(this, () => fn(this));
+  }
+
+  [Symbol.asyncDispose]() {
+    return this.finalize();
+  }
+
   public async finalize() {
     if (!this.isErrored) {
       // TODO: need to detect if it is in error
@@ -118,18 +126,10 @@ export class Scope {
     }
   }
 
-  public async run<T>(fn: (scope: Scope) => Promise<T>): Promise<T> {
-    return scopeStorage.run(this, () => fn(this));
-  }
-
-  [Symbol.asyncDispose]() {
-    return this.finalize();
-  }
-
   /**
    * Returns a string representation of the scope.
    */
-  toString() {
+  public toString() {
     return `Scope(
   chain=${this.chain.join("/")},
   resources=[${Array.from(this.resources.values())

package/src/state.ts

@@ -7,7 +7,7 @@ import { deserialize, serialize } from "./util/serde";
 
 export interface State<
   Kind extends string = string,
-  Props extends ResourceProps = ResourceProps,
+  Props extends ResourceProps | undefined = ResourceProps | undefined,
   Out extends Resource = Resource,
 > {
   status:
@@ -74,7 +74,8 @@ export class FileSystemStateStore implements StateStore {
       });
       return files
         .filter((dirent) => dirent.isFile() && dirent.name.endsWith(".json"))
-        .map((dirent) => dirent.name.replace(/\.json$/, ""));
+        .map((dirent) => dirent.name.replace(/\.json$/, ""))
+        .map((key) => key.replaceAll(":", "/"));
     } catch (error: any) {
       if (error.code === "ENOENT") {
         return [];
@@ -138,6 +139,12 @@ export class FileSystemStateStore implements StateStore {
   }
 
   private async getPath(key: string): Promise<string> {
+    if (key.includes(":")) {
+      throw new Error(`ID cannot include colons: ${key}`);
+    }
+    if (key.includes("/")) {
+      key = key.replaceAll("/", ":");
+    }
     const file = path.join(this.dir, `${key}.json`);
     const dir = path.dirname(file);
     await fs.promises.mkdir(dir, { recursive: true });

package/src/util/serde.ts

@@ -2,15 +2,24 @@ import { Scope } from "../scope";
 import { Secret } from "../secret";
 import { decryptWithKey, encryptWithKey } from "./encrypt";
 
-export async function serialize(scope: Scope, value: any): Promise<any> {
+export async function serialize(
+  scope: Scope,
+  value: any,
+  options?: {
+    encrypt?: boolean;
+  },
+): Promise<any> {
   if (Array.isArray(value)) {
-    return Promise.all(value.map((value) => serialize(scope, value)));
+    return Promise.all(value.map((value) => serialize(scope, value, options)));
   } else if (value instanceof Secret) {
     if (!scope.password) {
       throw new Error("Cannot serialize secret without password");
     }
     return {
-      "@secret": await encryptWithKey(value.unencrypted, scope.password),
+      "@secret":
+        options?.encrypt !== false
+          ? await encryptWithKey(value.unencrypted, scope.password)
+          : value.unencrypted,
     };
   } else if (value instanceof Scope) {
     return undefined;
@@ -19,7 +28,7 @@ export async function serialize(scope: Scope, value: any): Promise<any> {
       await Promise.all(
         Object.entries(value).map(async ([key, value]) => [
           key,
-          await serialize(scope, value),
+          await serialize(scope, value, options),
         ]),
       ),
     );

package/src/vitepress/dependencies.ts

@@ -0,0 +1,68 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+
+const execAsync = promisify(exec);
+
+export type InstallDependencies = Resource<"project::InstallDependencies">;
+
+export const InstallDependencies = Resource(
+  "project::InstallDependencies",
+  {
+    alwaysUpdate: true,
+  },
+  async function (
+    this: Context<InstallDependencies>,
+    id: string,
+    {
+      cwd,
+      dependencies,
+      devDependencies,
+    }: {
+      cwd: string;
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    },
+  ) {
+    if (this.phase === "delete") {
+      return this.destroy();
+    }
+
+    await installDependencies(cwd, dependencies);
+    await installDependencies(cwd, devDependencies, "-D");
+    await execAsync("bun install", { cwd });
+
+    return this({});
+  },
+);
+
+function isInstallableVersion(version: string) {
+  // TODO: file:// ?
+  return !version.startsWith("workspace:");
+}
+
+export function fixedDependencies(dependencies?: Record<string, string>) {
+  if (!dependencies) return {};
+  return Object.fromEntries(
+    Object.entries(dependencies).filter(
+      ([, value]) => !isInstallableVersion(value),
+    ),
+  );
+}
+
+export async function installDependencies(
+  cwd: string,
+  dependencies: Record<string, string> | undefined,
+  ...args: string[]
+) {
+  if (!dependencies) return;
+  const deps = Object.entries(dependencies)
+    .filter(([, value]) => isInstallableVersion(value))
+    .map(([pkg, version]) => `${pkg}@${version}`)
+    .join(" ");
+
+  const cmd = `bun add ${args.join(" ")} ${deps}`;
+  console.log(cmd);
+  await execAsync(cmd, { cwd });
+}