alchemy 0.1.2 → 0.1.3

package/src/apply.ts

@@ -1,4 +1,4 @@
-import { defaultStage, stateStore } from "./global";
+import { defaultStage, defaultStateStore } from "./global";
 import { Output } from "./output";
 import {
   Input,
@@ -7,11 +7,14 @@ import {
   ResourceID,
   isResource,
 } from "./resource";
+import { type Scope as IScope, getScope } from "./scope";
 import type { StateStore } from "./state";
 
-interface ApplyOptions {
-  stage?: string;
-  stateStore?: StateStore;
+export interface ApplyOptions {
+  stage: string;
+  scope: IScope;
+  stateStore: StateStore;
+  quiet?: boolean;
 }
 
 /**
@@ -21,9 +24,16 @@ interface ApplyOptions {
  */
 export async function apply<T>(
   output: T | Output<T>,
-  options?: ApplyOptions,
+  options?: Partial<ApplyOptions>,
 ): Promise<T> {
-  return (await evaluate(output, options)).value;
+  const stage = options?.stage ?? defaultStage;
+  const scope = options?.scope ?? getScope();
+  const statePath = scope.getScopePath(stage);
+  const stateStore = options?.stateStore ?? new defaultStateStore(statePath);
+
+  return (
+    await evaluate(output, { stage, scope, stateStore, quiet: options?.quiet })
+  ).value;
 }
 
 class Evaluated<T> {
@@ -37,9 +47,10 @@ const cache = new WeakMap<Resource, Promise<Evaluated<any>>>();
 
 export async function evaluate<T>(
   output: T | Output<T>,
-  options: ApplyOptions = {},
+  options: ApplyOptions,
 ): Promise<Evaluated<T>> {
-  const state = options.stateStore ?? stateStore;
+  const stage = options.stage;
+  const stateStore = options.stateStore;
   if (isResource(output)) {
     const resource = output;
     const resourceID = resource[ResourceID];
@@ -63,14 +74,16 @@ export async function evaluate<T>(
     const inputs = evaluated.map((input) => input.value);
     try {
       const result: T = await resource[Provider].update(
-        options.stage ?? defaultStage,
+        stage,
         resource,
         deps,
         inputs as [],
-        state,
+        stateStore,
+        options,
       );
       resolve!(new Evaluated(result, [resourceID, ...deps]));
     } catch (error) {
+      console.error(error);
       reject!(error);
     }
     return promise;
@@ -95,6 +108,8 @@ export async function evaluate<T>(
       evaluatedItems.map((e) => e.value) as unknown as T,
       evaluatedItems.flatMap((e) => e.deps),
     );
+  } else if (output instanceof Date) {
+    return new Evaluated(output as T);
   } else if (output && typeof output === "object") {
     const entries = Object.entries(output);
     const evaluatedEntries = await Promise.all(

package/src/{components/aws → aws}/bucket.ts

@@ -10,8 +10,8 @@ import {
   PutBucketTaggingCommand,
   S3Client,
 } from "@aws-sdk/client-s3";
-import { ignore } from "../../error";
-import { Resource } from "../../resource";
+import { ignore } from "../error";
+import { Resource } from "../resource";
 
 export interface BucketProps {
   bucketName: string;

package/src/{components/aws → aws}/function.ts

@@ -12,8 +12,8 @@ import {
 } from "@aws-sdk/client-lambda";
 import fs from "node:fs";
 import path from "node:path";
-import { ignore } from "../../error";
-import { Resource, type Context } from "../../resource";
+import { ignore } from "../error";
+import { type Context, Resource } from "../resource";
 
 async function resolveRegion(client: LambdaClient): Promise<string> {
   const region = client.config.region;

package/src/{components/aws → aws}/policy.ts

@@ -11,8 +11,8 @@ import {
   ListPolicyVersionsCommand,
   NoSuchEntityException,
 } from "@aws-sdk/client-iam";
-import { ignore } from "../../error";
-import { Resource } from "../../resource";
+import { ignore } from "../error";
+import { Resource } from "../resource";
 
 // Type-safe policy document types
 export type Effect = "Allow" | "Deny";

package/src/{components/aws → aws}/queue.ts

@@ -5,7 +5,7 @@ import {
   GetQueueUrlCommand,
   SQSClient,
 } from "@aws-sdk/client-sqs";
-import { Resource } from "../../resource";
+import { Resource } from "../resource";
 
 export interface QueueProps {
   queueName: string;

package/src/{components/aws → aws}/role.ts

@@ -12,8 +12,8 @@ import {
   UpdateAssumeRolePolicyCommand,
   UpdateRoleCommand,
 } from "@aws-sdk/client-iam";
-import { ignore } from "../../error";
-import { type Context, Resource } from "../../resource";
+import { ignore } from "../error";
+import { type Context, Resource } from "../resource";
 import type { PolicyDocument } from "./policy";
 
 export interface RoleProps {

package/src/{components/aws → aws}/table.ts

@@ -7,8 +7,8 @@ import {
   ResourceInUseException,
   ResourceNotFoundException,
 } from "@aws-sdk/client-dynamodb";
-import { ignore } from "../../error";
-import { type Context, Resource } from "../../resource";
+import { ignore } from "../error";
+import { type Context, Resource } from "../resource";
 
 export interface TableProps {
   tableName: string;

package/src/destroy.ts

@@ -1,10 +1,14 @@
-import { defaultStage, stateStore } from "./global";
+import { defaultStage, defaultStateStore, rootScope } from "./global";
 import type { Output } from "./output";
 import { Provider, ResourceID, isResource } from "./resource";
-import type { State } from "./state";
+import type { Scope } from "./scope";
+import type { State, StateStore } from "./state";
 
-interface DestroyOptions {
+export interface DestroyOptions {
   stage?: string;
+  stateStore?: StateStore;
+  scope?: Scope;
+  quiet?: boolean;
 }
 
 /**
@@ -20,44 +24,64 @@ export async function destroy<T>(
  */
 export async function destroy<T>(
   stage: string,
+  scope: Scope,
   resourceID: ResourceID,
   resourceState: State,
   resourceProvider: Provider,
+  stateStore: StateStore,
+  options: DestroyOptions,
 ): Promise<void>;
 
 export async function destroy<T>(
-  ...args: [Output<T>, DestroyOptions?] | [string, ResourceID, State, Provider]
+  ...args:
+    | [Output<T>, DestroyOptions?]
+    | [string, Scope, ResourceID, State, Provider, StateStore, DestroyOptions]
 ): Promise<void> {
   let resourceID: ResourceID;
   let resourceState: State;
   let resourceProvider: Provider;
   let stage: string;
-
-  if (args.length === 4) {
+  let stateStore: StateStore;
+  let scope: Scope | undefined = undefined;
+  let options: DestroyOptions | undefined = undefined;
+  if (args.length === 7) {
     stage = args[0];
-    resourceID = args[1];
-    resourceState = args[2];
-    resourceProvider = args[3];
+    scope = args[1];
+    resourceID = args[2];
+    resourceState = args[3];
+    resourceProvider = args[4];
+    stateStore = args[5];
+    options = args[6];
   } else if (isResource(args[0])) {
     const resource = args[0];
-    stage = args[1]?.stage ?? defaultStage;
+    // stage = args[1]?.stage ?? defaultStage;
     resourceID = resource[ResourceID];
+    stage = args[1]?.stage ?? defaultStage;
+    scope = args[1]?.scope ?? rootScope;
+    const statePath = scope.getScopePath(stage);
+    stateStore = args[1]?.stateStore ?? new defaultStateStore(statePath);
     // First destroy all dependencies
-    const _resourceState = await stateStore.get(stage, resourceID);
+    const _resourceState = await stateStore.get(resourceID);
     if (_resourceState === undefined) {
       // we have no record of this resource, we must assume it's already deleted
       return;
     }
     resourceState = _resourceState;
     resourceProvider = resource[Provider];
+    options = args[1];
   } else {
+    console.log(args[0]);
     throw new Error("Not implemented: must handle destroy a Output chain");
   }
   await resourceProvider.delete(
     stage,
+    scope,
     resourceID,
     resourceState,
     resourceState.inputs as [],
+    options ?? {
+      quiet: false,
+    },
   );
-  await stateStore.delete(stage, resourceID);
+  await stateStore.delete(resourceID);
 }

package/src/{components/esbuild.ts → esbuild.ts}

@@ -2,7 +2,7 @@ import * as esbuild from "esbuild";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { Resource } from "../resource";
+import { Resource } from "./resource";
 
 export interface BundleProps {
   /**

package/src/{components/fs.ts → fs.ts}

@@ -1,7 +1,8 @@
 import fs from "node:fs";
+import { unlink } from "node:fs/promises";
 import path from "node:path";
-import { ignore } from "../error";
-import { Resource } from "../resource";
+import { ignore } from "./error";
+import { Resource } from "./resource";
 
 export class File extends Resource(
   "fs::File",
@@ -18,28 +19,29 @@ export class File extends Resource(
 
 export class Folder extends Resource(
   "fs::Folder",
-  async (ctx, dirPath: string) => {
+  async (ctx, dirPath: string): Promise<{ path: string }> => {
     if (ctx.event === "delete") {
-      if (await ctx.get("isOwned")) {
-        // only delete the folder if we own it (we created it)
-        await ignore("ENOENT", () => fs.promises.rmdir(dirPath));
-      }
+      // we just do a best effort attempt
+      await ignore(["ENOENT", "ENOTEMPTY"], () => fs.promises.rmdir(dirPath));
     } else {
-      try {
-        await fs.promises.mkdir(dirPath, { recursive: true });
-      } catch (error: any) {
-        if (error.code === "EEXIST") {
-          // record that we own the directory
-          await ctx.set("isOwned", true);
-        } else {
-          throw error;
-        }
-      }
+      await ignore("EEXIST", () =>
+        fs.promises.mkdir(dirPath, { recursive: true }),
+      );
     }
-    return dirPath;
+    return { path: dirPath };
   },
 ) {
   public file(filePath: string, content: string) {
     return new File(path.basename(filePath), filePath, content);
   }
 }
+
+export async function rm(filePath: string) {
+  try {
+    await unlink(filePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+  }
+}

package/src/global.ts

@@ -1,11 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
-import type { Provider, Resource, ResourceID, ResourceType } from "./resource";
-import { defaultStore, type StateStore } from "./state";
+import type { Provider, ResourceType } from "./resource";
+import { Scope } from "./scope";
+import { FileSystemStateStore } from "./state";
 
 export interface Config {
   defaultStage?: string;
-  stateStore?: StateStore;
+  stateStore?: new (dir: string) => FileSystemStateStore;
 }
 
 const alchemy = path.resolve(process.cwd(), "alchemy.ts");
@@ -43,20 +44,14 @@ const _stage = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
 
 export const config: Config = _config ?? {
   defaultStage: _stage,
-  stateStore: defaultStore,
+  stateStore: FileSystemStateStore,
 };
 
 export const defaultStage = config.defaultStage ?? _stage;
 
-export const stateStore = config.stateStore ?? defaultStore;
+export const defaultStateStore = config.stateStore ?? FileSystemStateStore;
 
-export const nodes = new Map<
-  ResourceID,
-  {
-    provider: Provider<any, any[], any>;
-    resource: Resource<any, any>;
-  }
->();
+export const rootScope = new Scope(null);
 
 export const providers = new Map<
   ResourceType,
@@ -68,5 +63,3 @@ export const deletions: {
   data: Record<string, any>;
   inputs: any[];
 }[] = [];
-
-await stateStore.init?.();

package/src/index.ts

@@ -1,6 +1,15 @@
+export * from "./$.ts";
 export * from "./alchemize";
+export * from "./error";
 export * from "./global";
+export * from "./input";
 export * from "./output";
-export * from "./resource";
+export {
+  Resource,
+  type Context,
+  type CreateContext,
+  type DeleteContext,
+  type UpdateContext,
+} from "./resource";
 
-export type { StateStore } from "./state";
+export type { FileSystemStateStore as StateStore } from "./state";

package/src/input.ts

@@ -4,7 +4,7 @@ export type Inputs<P extends any[]> = P extends [infer First, ...infer Rest]
   ? [Input<First>, ...Inputs<Rest>]
   : [];
 
-export type Input<T> =
+export type Input<T = any> =
   | T
   | Output<T>
   | (T extends any[] ? Inputs<T> : never)

package/src/markdown/design.ts

@@ -0,0 +1,125 @@
+import { tool } from "ai";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import {
+  type FileContext,
+  type ModelId,
+  dependenciesAsMessages,
+  generateText,
+  resolveModel,
+} from "../agent";
+import { Prompts } from "../agent/prompts";
+import { rm } from "../fs";
+import { extractMarkdown } from "../markdown/extract";
+import { type Context, Resource } from "../resource";
+
+export interface DesignInput {
+  prompt: string;
+  path: string;
+  deps?: any[];
+  model?: ModelId;
+  dependencies: FileContext[];
+}
+
+export interface DesignOutput {
+  path: string;
+  content: string;
+}
+
+export class Design extends Resource(
+  "design",
+  async (ctx: Context<DesignOutput>, props: DesignInput) => {
+    if (ctx.event === "delete") {
+      await rm(props.path);
+      return;
+    }
+    const model = await resolveModel(props.model ?? "gpt-4o");
+
+    const importFile = tool({
+      description: "Imports a relevant file into context",
+      parameters: z.object({
+        file: z.string(),
+      }),
+      execute: async ({ file }) => fs.readFile(file, "utf-8"),
+    });
+
+    let existingContent: string | undefined = undefined;
+    if (ctx.event === "update") {
+      if (props.path) {
+        try {
+          existingContent = await fs.readFile(props.path, "utf-8");
+        } catch {
+          // File doesn't exist yet, continue with empty content
+        }
+      } else {
+        existingContent = ctx.output.content;
+      }
+    }
+
+    console.log(
+      ctx.event === "create" ? "Designing" : "Revising design",
+      ":",
+      props.path,
+    );
+
+    const result = await generateText({
+      model,
+      // tools: {
+      //   import: importFile,
+      // },
+      providerOptions:
+        props.model === "o3-mini"
+          ? {
+              openai: {
+                reasoningEffort: "high",
+              },
+            }
+          : undefined,
+      messages: [
+        {
+          role: "system",
+          content: Prompts.program,
+        },
+        ...dependenciesAsMessages(props.dependencies),
+        ...(existingContent
+          ? [
+              {
+                role: "user" as const,
+                content: `Here is the prior version of ${props.path}:\n${existingContent}`,
+              },
+              {
+                role: "assistant" as const,
+                content:
+                  "Thanks, I'll make sure to consider this when producing the next revision.",
+              },
+            ]
+          : []),
+        {
+          role: "user",
+          content: props.prompt,
+        },
+        {
+          role: "user",
+          content: [
+            `Make sure to list each of the files that need to be implemented and`,
+            "and to follow best practices in term of separation of concerns.",
+            "Ideally, each component has its own dedicated file.",
+            "Each file should be referenced using markdown links, e.g. [file.ts](./file.ts).",
+          ].join(" "),
+        },
+      ],
+    });
+
+    const content = extractMarkdown(result.text);
+
+    await fs.mkdir(path.dirname(props.path), { recursive: true });
+
+    await fs.writeFile(props.path, content);
+
+    return {
+      path: props.path,
+      content,
+    };
+  },
+) {}

package/src/markdown/extract.ts

@@ -0,0 +1,9 @@
+/**
+ * Extracts markdown content from a code block or returns the full content
+ * @param text Response text that may contain markdown code blocks
+ * @returns The markdown content from code block if found, otherwise returns the full text
+ */
+export function extractMarkdown(text: string): string {
+  const matches = text.match(/```md\n([\s\S]*?)```/);
+  return matches?.[1]?.trim() ?? text.trim();
+}

package/src/markdown/index.ts

@@ -0,0 +1,3 @@
+export * from "./design";
+export * from "./extract";
+export * from "./requirements";

package/src/{components/agent → markdown}/requirements.ts

@@ -1,17 +1,29 @@
-import { generateText } from "ai";
-import { mkdir, unlink, writeFile } from "fs/promises";
+import { mkdir, writeFile } from "fs/promises";
 import { dirname } from "path";
 import { z } from "zod";
-import { Agent } from "./agent";
-import { resolveModel } from "./model";
-import { scrapeWebPage } from "./scrape";
+import {
+  FileContext,
+  ModelId,
+  dependenciesAsMessages,
+  generateText,
+  resolveModel,
+} from "../agent";
+import { rm } from "../fs";
+import { type Context, Resource } from "../resource";
+
+export const ReasoningEffort = z.enum(["low", "medium", "high"]);
 
 export const RequirementsInput = z.object({
   /**
    * The ID of the model to use for generating requirements documentation
    * @default "gpt-4o"
    */
-  modelId: z.string().optional(),
+  modelId: ModelId.optional(),
+
+  /**
+   * The effort to put into reasoning about the requirements
+   */
+  reasoningEffort: ReasoningEffort.optional(),
 
   /**
    * List of requirements to document and analyze
@@ -19,9 +31,9 @@ export const RequirementsInput = z.object({
   requirements: z.array(z.string()),
 
   /**
-   * One-line summary of the requirements document
+   * List of dependencies for the requirements document
    */
-  title: z.string(),
+  dependencies: z.array(FileContext).optional(),
 
   /**
    * Temperature setting for model generation (higher = more creative, lower = more focused)
@@ -32,7 +44,7 @@ export const RequirementsInput = z.object({
   /**
    * File path where the requirements document should be written
    */
-  path: z.string(),
+  file: z.string().optional(),
 });
 
 export const RequirementsOutput = z.object({
@@ -42,33 +54,44 @@ export const RequirementsOutput = z.object({
   content: z.string(),
 });
 
-export type RequirementsInput = z.infer<typeof RequirementsInput>;
+export interface RequirementsInput extends z.infer<typeof RequirementsInput> {}
 export type RequirementsOutput = z.infer<typeof RequirementsOutput>;
 
-export class Requirements extends Agent(
+export class Requirements extends Resource(
   "code::Requirements",
-  {
-    description:
-      "This Agent is responsible for writing and refining a detailed requirements document from a list of requirements.",
-    input: RequirementsInput,
-    output: RequirementsOutput,
-  },
-  async (ctx, input) => {
+  async (ctx: Context<RequirementsOutput>, props: RequirementsInput) => {
     if (ctx.event === "delete") {
-      await unlink(input.path);
+      if (props.file) {
+        await rm(props.file);
+      }
       return;
     }
 
+    if (props.file) {
+      console.log(
+        ctx.event === "create" ? "Designing" : "Revising",
+        "requirements",
+        props.file,
+      );
+    }
+
     // Get the appropriate model based on the ID
-    const { model } = await resolveModel(input.modelId ?? "gpt-4o");
+    const model = await resolveModel(props.modelId ?? "gpt-4o");
 
     // Generate the requirements document
     const { text } = await generateText({
       model,
-      temperature: input.temperature ?? 0.7,
+      temperature: props.temperature ?? 0.7,
       maxSteps: 3, // Allow multiple steps for potential tool usage
+      providerOptions: props.reasoningEffort
+        ? {
+            openai: {
+              reasoningEffort: props.reasoningEffort,
+            },
+          }
+        : undefined,
       tools: {
-        scrapeWebPage,
+        // scrapeWebPage,
       },
       messages: [
         {
@@ -76,14 +99,13 @@ export class Requirements extends Agent(
           content:
             "You are a helpful assistant that creates markdown documents from requirements. You can use the scrapeWebPage tool to get additional requirements from relevant URLs if needed.",
         },
+        ...dependenciesAsMessages(props.dependencies ?? []),
         {
           role: "user",
           content: `Please analyze the following system requirements and create a comprehensive, unambiguous markdown document that covers all aspects:
 
-Title: ${input.title}
-
 Requirements:
-${input.requirements.map((req) => `- ${req}`).join("\n")}
+${props.requirements.map((req) => `- ${req}`).join("\n")}
 
 Guidelines:
 1. Make explicit decisions for any ambiguous requirements - do not leave open questions
@@ -98,11 +120,13 @@ Include technical considerations and implementation details, ensuring every requ
       ],
     });
 
-    // Ensure the directory exists
-    await mkdir(dirname(input.path), { recursive: true });
+    if (props.file) {
+      // Ensure the directory exists
+      await mkdir(dirname(props.file), { recursive: true });
 
-    // Write the requirements to the file
-    await writeFile(input.path, text);
+      // Write the requirements to the file
+      await writeFile(props.file, text);
+    }
 
     return {
       content: text,