alchemy 0.0.8 → 0.1.1

package/src/components/agent/requirements.ts

@@ -0,0 +1,111 @@
+import { generateText } from "ai";
+import { mkdir, unlink, writeFile } from "fs/promises";
+import { dirname } from "path";
+import { z } from "zod";
+import { Agent } from "./agent";
+import { resolveModel } from "./model";
+import { scrapeWebPage } from "./scrape";
+
+export const RequirementsInput = z.object({
+  /**
+   * The ID of the model to use for generating requirements documentation
+   * @default "gpt-4o"
+   */
+  modelId: z.string().optional(),
+
+  /**
+   * List of requirements to document and analyze
+   */
+  requirements: z.array(z.string()),
+
+  /**
+   * One-line summary of the requirements document
+   */
+  title: z.string(),
+
+  /**
+   * Temperature setting for model generation (higher = more creative, lower = more focused)
+   * @default 0.7
+   */
+  temperature: z.number().optional(),
+
+  /**
+   * File path where the requirements document should be written
+   */
+  path: z.string(),
+});
+
+export const RequirementsOutput = z.object({
+  /**
+   * Generated markdown document containing organized and analyzed requirements
+   */
+  content: z.string(),
+});
+
+export type RequirementsInput = z.infer<typeof RequirementsInput>;
+export type RequirementsOutput = z.infer<typeof RequirementsOutput>;
+
+export class Requirements extends Agent(
+  "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) => {
+    if (ctx.event === "delete") {
+      await unlink(input.path);
+      return;
+    }
+
+    // Get the appropriate model based on the ID
+    const { model } = await resolveModel(input.modelId ?? "gpt-4o");
+
+    // Generate the requirements document
+    const { text } = await generateText({
+      model,
+      temperature: input.temperature ?? 0.7,
+      maxSteps: 3, // Allow multiple steps for potential tool usage
+      tools: {
+        scrapeWebPage,
+      },
+      messages: [
+        {
+          role: "system",
+          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.",
+        },
+        {
+          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")}
+
+Guidelines:
+1. Make explicit decisions for any ambiguous requirements - do not leave open questions
+2. Document the reasoning behind key decisions
+3. Be specific about technical choices and implementation details
+4. Avoid phrases like "could be", "might need", or "possibly requires" - be definitive
+5. Organize requirements into logical sections with clear dependencies and relationships
+
+Format the output in markdown with appropriate headers, lists, and sections, starting with the title as an H1 header.
+Include technical considerations and implementation details, ensuring every requirement has a clear, actionable specification.`,
+        },
+      ],
+    });
+
+    // Ensure the directory exists
+    await mkdir(dirname(input.path), { recursive: true });
+
+    // Write the requirements to the file
+    await writeFile(input.path, text);
+
+    return {
+      content: text,
+    };
+  },
+) {}

package/src/components/agent/scrape.ts

@@ -0,0 +1,47 @@
+import { tool } from "ai";
+import TurndownService from "turndown";
+import { z } from "zod";
+
+export const scrapeWebPage = tool({
+  description: "Scrapes a web page and converts HTML content to Markdown",
+  parameters: z.object({
+    url: z.string().url().describe("The URL to scrape content from"),
+    turndownOptions: z
+      .object({
+        headingStyle: z.enum(["setext", "atx"]).optional(),
+        hr: z.string().optional(),
+        bulletListMarker: z.enum(["-", "*", "+"]).optional(),
+        codeBlockStyle: z.enum(["indented", "fenced"]).optional(),
+        emDelimiter: z.enum(["_", "*"]).optional(),
+        strongDelimiter: z.enum(["__", "**"]).optional(),
+        linkStyle: z.enum(["inlined", "referenced"]).optional(),
+        linkReferenceStyle: z
+          .enum(["full", "collapsed", "shortcut"])
+          .optional(),
+      })
+      .optional()
+      .describe("Custom options for Turndown HTML to Markdown conversion"),
+  }),
+  execute: async ({ url, turndownOptions }) => {
+    console.log("Scraping web page:", url);
+    try {
+      // Fetch the page content
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
+      }
+
+      // Get the HTML content
+      const html = await response.text();
+
+      // Initialize Turndown with options
+      const turndownService = new TurndownService(turndownOptions);
+
+      // Convert HTML to Markdown and return
+      return turndownService.turndown(html);
+    } catch (error) {
+      console.error("Error scraping web page:", error);
+      throw error;
+    }
+  },
+});

package/src/components/agent/tsconfig.ts

@@ -0,0 +1,150 @@
+import { generateObject } from "ai";
+import { mkdir, unlink, writeFile } from "fs/promises";
+import { dirname } from "path";
+import { z } from "zod";
+import { Agent } from "./agent";
+import { resolveModel } from "./model";
+
+export type TsConfigProps = z.infer<typeof TsConfigProps>;
+
+export const TsConfigProps = z.object({
+  /**
+   * The ID of the model to use for generating tsconfig configuration
+   * @default "gpt-4o"
+   */
+  modelId: z.string().optional(),
+
+  /**
+   * List of requirements for the TypeScript configuration
+   * Can include module settings, compilation options, etc.
+   */
+  requirements: z.array(z.string()),
+
+  /**
+   * Temperature setting for model generation
+   * @default 0.3
+   */
+  temperature: z.number().optional(),
+
+  /**
+   * Path to the tsconfig.json file to generate
+   */
+  path: z.string(),
+});
+
+export type TsConfigJson = z.infer<typeof TsConfigSchema>;
+export const TsConfigSchema = z.object({
+  $schema: z.string().optional(),
+  compilerOptions: z.object({
+    target: z.enum([
+      "es2015",
+      "es2016",
+      "es2017",
+      "es2018",
+      "es2019",
+      "es2020",
+      "es2021",
+      "es2022",
+      "esnext",
+    ]),
+    module: z.enum([
+      "commonjs",
+      "es2015",
+      "es2020",
+      "es2022",
+      "esnext",
+      "node16",
+      "nodenext",
+    ]),
+    lib: z.array(z.string()).optional(),
+    declaration: z.boolean().optional(),
+    declarationMap: z.boolean().optional(),
+    sourceMap: z.boolean().optional(),
+    outDir: z.string().optional(),
+    rootDir: z.string().optional(),
+    strict: z.boolean(),
+    esModuleInterop: z.boolean().optional(),
+    skipLibCheck: z.boolean().optional(),
+    forceConsistentCasingInFileNames: z.boolean().optional(),
+    moduleResolution: z
+      .enum(["node", "node16", "nodenext", "bundler"])
+      .optional(),
+    resolveJsonModule: z.boolean().optional(),
+    isolatedModules: z.boolean().optional(),
+    allowJs: z.boolean().optional(),
+    checkJs: z.boolean().optional(),
+    noEmit: z.boolean().optional(),
+    incremental: z.boolean().optional(),
+    composite: z.boolean().optional(),
+    tsBuildInfoFile: z.string().optional(),
+    paths: z.record(z.array(z.string())).optional(),
+    baseUrl: z.string().optional(),
+    types: z.array(z.string()).optional(),
+    typeRoots: z.array(z.string()).optional(),
+  }),
+  include: z.array(z.string()).optional(),
+  exclude: z.array(z.string()).optional(),
+  references: z
+    .array(
+      z.object({
+        path: z.string(),
+      }),
+    )
+    .optional(),
+});
+
+export class TypeScriptConfig extends Agent(
+  "code::tsconfig",
+  {
+    description:
+      "This Agent is responsible for generating tsconfig.json configuration based on requirements.",
+    input: TsConfigProps,
+    output: TsConfigSchema,
+  },
+  async (ctx, props) => {
+    if (ctx.event === "delete") {
+      await unlink(props.path);
+      return;
+    }
+
+    // Get the appropriate model
+    const { model } = await resolveModel(props.modelId ?? "gpt-4o");
+
+    // Generate the tsconfig configuration using generateObject for type safety
+    const result = await generateObject({
+      model,
+      schema: TsConfigSchema,
+      temperature: props.temperature ?? 0.3,
+      messages: [
+        {
+          role: "system",
+          content:
+            "You are an expert at creating TypeScript configurations. You will generate a tsconfig.json configuration based on requirements.",
+        },
+        {
+          role: "user",
+          content: `Please generate a tsconfig.json configuration based on these requirements:
+
+Requirements:
+${props.requirements.map((req) => `- ${req}`).join("\n")}
+
+Rules:
+1. Use modern TypeScript features
+2. Enable strict type checking
+3. Use ESM modules by default
+4. Include source maps for better debugging
+5. Infer appropriate settings for declarations, module resolution, and other options based on the requirements
+6. Use appropriate paths for source and output directories`,
+        },
+      ],
+    });
+
+    // Ensure the directory exists
+    await mkdir(dirname(props.path), { recursive: true });
+
+    // Write the tsconfig.json file
+    await writeFile(props.path, JSON.stringify(result.object, null, 2));
+
+    return result.object;
+  },
+) {}

package/src/components/agent/typescript.ts

@@ -0,0 +1,177 @@
+import type { CoreMessage } from "ai";
+import { generateText } from "ai";
+import { mkdir, unlink, writeFile } from "fs/promises";
+import { dirname } from "path";
+import { z } from "zod";
+import { Agent } from "./agent";
+import { resolveModel } from "./model";
+
+export type CodeProps = z.infer<typeof CodeProps>;
+
+export type File = z.infer<typeof File>;
+export const File = z.object({
+  path: z.string(),
+  content: z.string(),
+});
+
+const CodeProps = z.object({
+  /**
+   * The ID of the model to use for generating TypeScript code
+   * @default "gpt-4o"
+   */
+  modelId: z.string().optional(),
+
+  /**
+   * The name of the file to write the code to
+   */
+  path: z.string(),
+
+  /**
+   * The requirements for the TypeScript file
+   */
+  requirements: z.string(),
+
+  /**
+   * List of other code files that it depends on
+   */
+  dependencies: z.array(File).optional(),
+
+  /**
+   * Temperature setting for model generation (higher = more creative, lower = more focused)
+   * @default 0.7
+   */
+  temperature: z.number().optional(),
+});
+
+export type CodeOutput = z.infer<typeof CodeOutput>;
+export const CodeOutput = File;
+
+export class TypeScriptFile extends Agent(
+  "code::TypeScriptFile",
+  {
+    description:
+      "This Agent is responsible for generating TypeScript code based on requirements and context from other code files.",
+    input: CodeProps,
+    output: CodeOutput,
+  },
+  async (ctx, props) => {
+    if (ctx.event === "delete") {
+      await unlink(props.path);
+      return;
+    }
+
+    // Get the appropriate model based on the ID
+    const { model } = await resolveModel(props.modelId ?? "gpt-4o");
+
+    // Generate the TypeScript code with retries
+    const content = await generateCodeWithRetries(model, props);
+
+    // Ensure the directory exists
+    await mkdir(dirname(props.path), { recursive: true });
+
+    // Write the TypeScript file
+    await writeFile(props.path, content);
+
+    return {
+      path: props.path,
+      content: content,
+    };
+  },
+) {}
+
+/**
+ * Attempts to generate valid TypeScript code with retries
+ */
+async function generateCodeWithRetries(
+  model: any,
+  props: CodeProps,
+  maxAttempts = 3,
+): Promise<string> {
+  const baseMessages: CoreMessage[] = [
+    {
+      role: "system",
+      content:
+        "You are an expert TypeScript developer that generates clean, well-documented code following best practices. " +
+        "Your response must follow this exact format:\n" +
+        "1. A single sentence describing what the code will do\n" +
+        "2. A single TypeScript code block surrounded by ```ts and ``` tags\n" +
+        "Do not include any other explanations or multiple code blocks.",
+    },
+    {
+      role: "user",
+      content: `Please generate TypeScript code based on the following specifications:
+
+Requirements:
+${props.requirements}
+
+${
+  props.dependencies?.length
+    ? `Context (other code files):
+${props.dependencies.map((dep) => dep.content).join("\n\n")}`
+    : ""
+}
+
+The code should:
+1. Be well-documented with JSDoc comments
+2. Follow TypeScript best practices
+3. Include proper type definitions
+4. Be ready to use with the provided context files
+
+Your response MUST follow this format:
+- One sentence summary of what the code will do
+- Single TypeScript code block surrounded by \`\`\`ts and \`\`\` tags
+- No other explanations or multiple code blocks`,
+    },
+  ];
+
+  const messages = [...baseMessages];
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const { text } = await generateText({
+      model,
+      temperature: Math.max(
+        0.1,
+        (props.temperature ?? 0.7) * (1 - attempt * 0.2),
+      ), // Reduce temperature with each attempt
+      messages,
+    });
+
+    const code = extractTypeScriptCode(text);
+    if (code) {
+      return code;
+    }
+
+    if (attempt === maxAttempts) {
+      throw new Error(
+        "Failed to generate valid TypeScript code after maximum attempts",
+      );
+    }
+
+    // Add the failed attempt and correction request to the message chain
+    messages.push(
+      {
+        role: "assistant",
+        content: text,
+      },
+      {
+        role: "user",
+        content:
+          "Your response did not match the required format. Please provide your response with exactly one sentence summary" +
+          " followed by a single TypeScript code block surrounded by ```ts and ``` tags. No other text or explanations.",
+      },
+    );
+  }
+
+  // This should never be reached due to the throw above
+  throw new Error("Unexpected code generation failure");
+}
+
+/**
+ * Extracts TypeScript code from a markdown code block
+ * @param text Response text that may contain markdown
+ * @returns The TypeScript code if found, undefined otherwise
+ */
+function extractTypeScriptCode(text: string): string | undefined {
+  const matches = text.match(/```(?:ts|typescript)\n([\s\S]*?)```/);
+  return matches?.[1]?.trim();
+}

package/src/components/aws/bucket.ts

@@ -0,0 +1,168 @@
+import {
+  CreateBucketCommand,
+  DeleteBucketCommand,
+  GetBucketAclCommand,
+  GetBucketLocationCommand,
+  GetBucketTaggingCommand,
+  GetBucketVersioningCommand,
+  HeadBucketCommand,
+  NoSuchBucket,
+  PutBucketTaggingCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import { ignore } from "../../error";
+import { Resource } from "../../resource";
+
+export interface BucketProps {
+  bucketName: string;
+  tags?: Record<string, string>;
+}
+
+export interface BucketOutput extends BucketProps {
+  id: string; // Same as bucketName for AWS
+  arn: string;
+  bucketDomainName: string; // Format: bucket-name.s3.amazonaws.com
+  bucketRegionalDomainName?: string; // Format: bucket-name.s3.region.amazonaws.com
+  hostedZoneId?: string; // S3 hosted zone ID for the region
+  region?: string; // AWS Region where bucket resides
+  websiteEndpoint?: string; // Only if website hosting is enabled
+  websiteDomain?: string; // Only if website hosting is enabled
+  versioningEnabled?: boolean;
+  acl?: string;
+}
+
+export class Bucket extends Resource(
+  "s3::Bucket",
+  async (ctx, props: BucketProps) => {
+    const client = new S3Client({});
+
+    if (ctx.event === "delete") {
+      await ignore(NoSuchBucket.name, () =>
+        client.send(
+          new DeleteBucketCommand({
+            Bucket: props.bucketName,
+          }),
+        ),
+      );
+      return props;
+    } else {
+      try {
+        // Check if bucket exists
+        await client.send(
+          new HeadBucketCommand({
+            Bucket: props.bucketName,
+          }),
+        );
+
+        // Update tags if they changed and bucket exists
+        if (ctx.event === "update" && props.tags) {
+          await client.send(
+            new PutBucketTaggingCommand({
+              Bucket: props.bucketName,
+              Tagging: {
+                TagSet: Object.entries(props.tags).map(([Key, Value]) => ({
+                  Key,
+                  Value,
+                })),
+              },
+            }),
+          );
+        }
+      } catch (error: any) {
+        if (error.name === "NotFound") {
+          // Create bucket if it doesn't exist
+          await client.send(
+            new CreateBucketCommand({
+              Bucket: props.bucketName,
+              // Add tags during creation if specified
+              ...(props.tags && {
+                Tagging: {
+                  TagSet: Object.entries(props.tags).map(([Key, Value]) => ({
+                    Key,
+                    Value,
+                  })),
+                },
+              }),
+            }),
+          );
+        } else {
+          throw error;
+        }
+      }
+
+      // Get bucket details
+      const [locationResponse, versioningResponse, aclResponse] =
+        await Promise.all([
+          client.send(
+            new GetBucketLocationCommand({ Bucket: props.bucketName }),
+          ),
+          client.send(
+            new GetBucketVersioningCommand({ Bucket: props.bucketName }),
+          ),
+          client.send(new GetBucketAclCommand({ Bucket: props.bucketName })),
+        ]);
+
+      const region = locationResponse.LocationConstraint || "us-east-1";
+
+      // Get tags if they exist
+      let tags = props.tags;
+      if (!tags) {
+        try {
+          const taggingResponse = await client.send(
+            new GetBucketTaggingCommand({ Bucket: props.bucketName }),
+          );
+          tags = Object.fromEntries(
+            taggingResponse.TagSet?.map(({ Key, Value }) => [Key, Value]) || [],
+          );
+        } catch (error: any) {
+          if (error.name !== "NoSuchTagSet") {
+            throw error;
+          }
+        }
+      }
+
+      const output: BucketOutput = {
+        bucketName: props.bucketName,
+        id: props.bucketName,
+        arn: `arn:aws:s3:::${props.bucketName}`,
+        bucketDomainName: `${props.bucketName}.s3.amazonaws.com`,
+        bucketRegionalDomainName: `${props.bucketName}.s3.${region}.amazonaws.com`,
+        region,
+        hostedZoneId: getHostedZoneId(region),
+        versioningEnabled: versioningResponse.Status === "Enabled",
+        acl: aclResponse.Grants?.[0]?.Permission?.toLowerCase(),
+        ...(tags && { tags }),
+      };
+
+      return output;
+    }
+  },
+) {}
+
+// Helper function to get S3 hosted zone IDs by region
+function getHostedZoneId(region: string): string {
+  const hostedZoneIds: Record<string, string> = {
+    "us-east-1": "Z3AQBSTGFYJSTF",
+    "us-east-2": "Z2O1EMRO9K5GLX",
+    "us-west-1": "Z2F56UZL2M1ACD",
+    "us-west-2": "Z3BJ6K6RIION7M",
+    "af-south-1": "Z11KHD8FBVPUYU",
+    "ap-east-1": "ZNB98KWMFR0R6",
+    "ap-south-1": "Z11RGJOFQNVJUP",
+    "ap-northeast-1": "Z2M4EHUR26P7ZW",
+    "ap-northeast-2": "Z3W03O7B5YMIYP",
+    "ap-northeast-3": "Z2YQB5RD63NC85",
+    "ap-southeast-1": "Z3O0J2DXBE1FTB",
+    "ap-southeast-2": "Z1WCIGYICN2BYD",
+    "ca-central-1": "Z1QDHH18159H29",
+    "eu-central-1": "Z21DNDUVLTQW6Q",
+    "eu-west-1": "Z1BKCTXD74EZPE",
+    "eu-west-2": "Z3GKZC51ZF0DB4",
+    "eu-west-3": "Z3R1K369G5AVDG",
+    "eu-north-1": "Z3BAZG2TWCNX0D",
+    "eu-south-1": "Z30OZKI7KPW7MI",
+    "me-south-1": "Z1MPMWCPA7YB62",
+    "sa-east-1": "Z7KQH4QJS55SO",
+  };
+  return hostedZoneIds[region] || "Z3AQBSTGFYJSTF"; // Default to us-east-1 if region not found
+}