alchemy 0.2.2 → 0.2.3

package/lib/vitepress/vitepress.js

@@ -0,0 +1,260 @@
+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 { InstallDependencies, fixedDependencies } from "./dependencies";
+const execAsync = promisify(exec);
+export const VitePressProject = Resource("project::VitePressProject", {
+    alwaysUpdate: true,
+}, async function (id, props) {
+    if (this.phase === "delete") {
+        try {
+            if (await fs.exists(props.name)) {
+                // Delete the entire project directory
+                await execAsync(`rm -rf ${props.name}`);
+            }
+        }
+        catch (error) {
+            console.error(`Error deleting VitePress project ${id}:`, error);
+        }
+        return this.destroy();
+    }
+    const cwd = (await Folder(props.name)).path;
+    // Initialize package.json
+    await JsonFile(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",
+        },
+        dependencies: fixedDependencies(props.dependencies || {}),
+        devDependencies: fixedDependencies(props.devDependencies || {}),
+    });
+    await InstallDependencies("dependencies", {
+        cwd,
+        dependencies: props.dependencies,
+        devDependencies: {
+            vue: "latest",
+            vitepress: "latest",
+            "@shikijs/vitepress-twoslash": "latest",
+            "markdown-it-footnote": "latest",
+            ...props.devDependencies,
+        },
+    });
+    // Create .vitepress directory and config
+    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`),
+        TypeScriptFile(path.join(cwd, "alchemy.run.ts"), `import alchemy from "alchemy";
+import { Folder } from "alchemy/fs";
+import { Document } from "alchemy/docs";
+import path from "path";
+
+await using _ = alchemy("alchemy.run", {
+  stage: "prod",
+  phase: process.argv.includes("--destroy") ? "destroy" : "up",
+  password: process.env.SECRET_PASSPHRASE,
+  quiet: !process.argv.includes("--verbose"),
+});
+
+const docs = await Folder(path.join("alchemy.run", "docs"));
+
+await Document("home.md", {
+  path: path.join(docs.path, "home.md"),
+  prompt: await alchemy\`Generate a landing page.\`,
+});
+`),
+        TypeScriptFile(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";
+import "./style.css";
+
+export default {
+  extends: Theme,
+  enhanceApp(ctx) {
+    ctx.app.use(TwoslashFloatingVue);
+  },
+} satisfies ThemeConfig;
+  `),
+        TextFile(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
+*/
+
+/**
+* Colors
+*
+* Each colors have exact same color scale system with 3 levels of solid
+* colors with different brightness, and 1 soft color.
+*
+* - \`XXX-1\`: The most solid color used mainly for colored text. It must
+*   satisfy the contrast ratio against when used on top of \`XXX-soft\`.
+*
+* - \`XXX-2\`: The color used mainly for hover state of the button.
+*
+* - \`XXX-3\`: The color for solid background, such as bg color of the button.
+*   It must satisfy the contrast ratio with pure white (#ffffff) text on
+*   top of it.
+*
+* - \`XXX-soft\`: The color used for subtle background such as custom container
+*   or badges. It must satisfy the contrast ratio when putting \`XXX-1\` colors
+*   on top of it.
+*
+*   The soft color must be semi transparent alpha channel. This is crucial
+*   because it allows adding multiple "soft" colors on top of each other
+*   to create a accent, such as when having inline code block inside
+*   custom containers.
+*
+* - \`default\`: The color used purely for subtle indication without any
+*   special meanings attached to it such as bg color for menu hover state.
+*
+* - \`brand\`: Used for primary brand colors, such as link text, button with
+*   brand theme, etc.
+*
+* - \`tip\`: Used to indicate useful information. The default theme uses the
+*   brand color for this by default.
+*
+* - \`warning\`: Used to indicate warning to the users. Used in custom
+*   container, badges, etc.
+*
+* - \`danger\`: Used to show error, or dangerous message to the users. Used
+*   in custom container, badges, etc.
+* -------------------------------------------------------------------------- */
+
+:root {
+  --vp-c-default-1: var(--vp-c-gray-1);
+  --vp-c-default-2: var(--vp-c-gray-2);
+  --vp-c-default-3: var(--vp-c-gray-3);
+  --vp-c-default-soft: var(--vp-c-gray-soft);
+
+  --vp-c-brand-1: var(--vp-c-indigo-1);
+  --vp-c-brand-2: var(--vp-c-indigo-2);
+  --vp-c-brand-3: var(--vp-c-indigo-3);
+  --vp-c-brand-soft: var(--vp-c-indigo-soft);
+
+  --vp-c-tip-1: var(--vp-c-brand-1);
+  --vp-c-tip-2: var(--vp-c-brand-2);
+  --vp-c-tip-3: var(--vp-c-brand-3);
+  --vp-c-tip-soft: var(--vp-c-brand-soft);
+
+  --vp-c-warning-1: var(--vp-c-yellow-1);
+  --vp-c-warning-2: var(--vp-c-yellow-2);
+  --vp-c-warning-3: var(--vp-c-yellow-3);
+  --vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+  --vp-c-danger-1: var(--vp-c-red-1);
+  --vp-c-danger-2: var(--vp-c-red-2);
+  --vp-c-danger-3: var(--vp-c-red-3);
+  --vp-c-danger-soft: var(--vp-c-red-soft);
+}
+
+/**
+* Component: Button
+* -------------------------------------------------------------------------- */
+
+:root {
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-text: var(--vp-c-white);
+  --vp-button-brand-bg: var(--vp-c-brand-3);
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-hover-text: var(--vp-c-white);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+  --vp-button-brand-active-border: transparent;
+  --vp-button-brand-active-text: var(--vp-c-white);
+  --vp-button-brand-active-bg: var(--vp-c-brand-1);
+}
+
+/**
+* Component: Home
+* -------------------------------------------------------------------------- */
+
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    #bd34fe 30%,
+    #41d1ff
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    #bd34fe 50%,
+    #47caff 50%
+  );
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+
+/**
+* Component: Custom Block
+* -------------------------------------------------------------------------- */
+
+:root {
+  --vp-custom-block-tip-border: transparent;
+  --vp-custom-block-tip-text: var(--vp-c-text-1);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
+  --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
+}
+
+/**
+* Component: Algolia
+* -------------------------------------------------------------------------- */
+
+.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);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "module": "./lib/index.js",
   "scripts": {
@@ -12,6 +12,7 @@
     "./aws": "./lib/aws/index.js",
     "./aws/oidc": "./lib/aws/oidc/index.js",
     "./cloudflare": "./lib/cloudflare/index.js",
+    "./docs": "./lib/docs/index.js",
     "./esbuild": "./lib/esbuild/index.js",
     "./fs": "./lib/fs/index.js",
     "./github": "./lib/github/index.js",
@@ -22,6 +23,7 @@
   },
   "peerDependencies": {
     "@ai-sdk/openai": "^1.1.9",
+    "@ai-sdk/openai-compatible": "^0.2.2",
     "@aws-sdk/client-dynamodb": "^3.0.0",
     "@aws-sdk/client-iam": "^3.0.0",
     "@aws-sdk/client-lambda": "^3.0.0",
@@ -31,17 +33,19 @@
     "@aws-sdk/client-sesv2": "^3.0.0",
     "@aws-sdk/client-sqs": "^3.0.0",
     "@aws-sdk/client-sts": "^3.0.0",
+    "prettier": "^3.0.0",
     "@octokit/rest": "^21.1.1",
-    "ai": "^4.1.16",
+    "ai": "^4.0.0",
     "diff": "^7.0.0",
-    "esbuild": "^0.24.2",
-    "glob": "^10.3.10",
-    "hono": "^4.7.4",
+    "esbuild": "^0.25.1",
+    "glob": "^10.0.0",
+    "hono": "^4.0.0",
     "libsodium-wrappers": "^0.7.15",
     "jszip": "^3.0.0",
-    "stripe": "^17.7.0",
-    "turndown": "^7.2.0",
-    "zod": "^3.24.1"
+    "stripe": "^17.0.0",
+    "turndown": "^7.0.0",
+    "yaml": "^2.0.0",
+    "zod": "^3.0.0"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^1.1.6",
@@ -58,9 +62,12 @@
     "change-case": "^5.4.4",
     "libsodium-wrappers": "^0.7.15",
     "openpgp": "^6.1.0",
+    "prettier": "^3.5.3",
     "turndown": "^7.2.0",
     "typescript": "latest",
     "vite": "^6.0.7",
-    "wrangler": "^3.114.0"
+    "vitepress": "^1.6.3",
+    "wrangler": "^3.114.0",
+    "yaml": "^2.7.1"
   }
 }

package/src/alchemy.ts

@@ -1,3 +1,6 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
 import { DestroyedSignal, destroy } from "./destroy";
 import { Scope } from "./scope";
 import { secret } from "./secret";
@@ -6,18 +9,6 @@ import type { StateStoreType } from "./state";
 // TODO: support browser
 const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
 
-function _alchemy(appName: string, options: Omit<AlchemyOptions, "appName">) {
-  return scope(undefined, {
-    ...options,
-    appName,
-    stage: options.stage,
-  });
-}
-_alchemy.destroy = destroy;
-_alchemy.run = run;
-_alchemy.scope = scope;
-_alchemy.secret = secret;
-
 // alchemy type is to semantically highlight `alchemy` as a type (keyword)
 export type alchemy = Alchemy;
 
@@ -30,8 +21,106 @@ export interface Alchemy {
   destroy: typeof destroy;
   secret: typeof secret;
   (...parameters: Parameters<typeof scope>): ReturnType<typeof scope>;
+  (template: TemplateStringsArray, ...values: any[]): Promise<string>;
 }
 
+function _alchemy(
+  ...args:
+    | [template: TemplateStringsArray, ...values: any[]]
+    | [appName: string, options?: Omit<AlchemyOptions, "appName">]
+): any {
+  if (typeof args[0] === "string") {
+    const [appName, options] = args;
+    return scope(undefined, {
+      ...options,
+      appName,
+      stage: options?.stage,
+    });
+  } else {
+    const [template, ...values] = args;
+    const [, secondLine] = template[0].split("\n");
+    const leadingSpaces = secondLine
+      ? secondLine.match(/^(\s*)/)?.[1]?.length || 0
+      : 0;
+    const indent = " ".repeat(leadingSpaces);
+
+    return (async () => {
+      const { isFileCollection, isFileRef } = await import("./fs/file");
+
+      const appendices: Record<string, string> = {};
+
+      const stringValues = await Promise.all(
+        values.map(async function resolve(value): Promise<string> {
+          if (typeof value === "string") {
+            return indent + value;
+          } else if (value instanceof Promise) {
+            return resolve(await value);
+          } else if (isFileRef(value)) {
+            if (!(value.path in appendices)) {
+              appendices[value.path] = await fs.readFile(value.path, "utf-8");
+            }
+            return `[${path.basename(value.path)}](${value.path})`;
+          } else if (isFileCollection(value)) {
+            return Object.entries(value.files)
+              .map(([filePath, content]) => {
+                appendices[filePath] = content;
+                return `[${path.basename(filePath)}](${filePath})`;
+              })
+              .join("\n\n");
+          } else if (Array.isArray(value)) {
+            return (
+              await Promise.all(
+                value.map(async (value, i) => `${i}. ${await resolve(value)}`),
+              )
+            ).join("\n");
+          } else {
+            // TODO: support other types
+            throw new Error(`Unsupported value type: ${JSON.stringify(value)}`);
+          }
+        }),
+      );
+
+      // Construct the string template by joining template parts with interpolated values
+      const lines = template
+        .map((part) =>
+          part
+            .split("\n")
+            .map((line) =>
+              line.startsWith(indent) ? line.slice(indent.length) : line,
+            )
+            .join("\n"),
+        )
+        .flatMap((part, i) =>
+          i < stringValues.length ? [part, stringValues[i] ?? ""] : [part],
+        )
+        .join("")
+        .split("\n");
+
+      // Collect and sort appendices by file path
+      return [
+        // format the user prompt and trim the first line if it's empty
+        lines.length > 1 && lines[0].replaceAll(" ", "").length === 0
+          ? lines.slice(1).join("\n")
+          : lines.join("\n"),
+
+        // sort appendices by path and include at the end of the prompt
+        Object.entries(appendices)
+          .sort(([a], [b]) => a.localeCompare(b))
+          .map(([filePath, content]) => {
+            const extension = path.extname(filePath).slice(1);
+            const codeTag = extension ? extension : "";
+            return `// ${filePath}\n\`\`\`${codeTag}\n${content}\n\`\`\``;
+          })
+          .join("\n\n"),
+      ].join("\n");
+    })();
+  }
+}
+_alchemy.destroy = destroy;
+_alchemy.run = run;
+_alchemy.scope = scope;
+_alchemy.secret = secret;
+
 export interface AlchemyOptions {
   /**
    * The name of the application.
@@ -115,13 +204,16 @@ async function run<T>(
           AlchemyOptions | undefined,
           (this: Scope, scope: Scope) => Promise<T>,
         ]);
-  await using scope = alchemy.scope(id, options);
+  const scope = alchemy.scope(id, options);
   try {
     return await fn.bind(scope)(scope);
   } catch (error) {
     if (!(error instanceof DestroyedSignal)) {
       scope.fail();
+    } else {
     }
     throw error;
+  } finally {
+    await scope.finalize();
   }
 }

package/src/apply.ts

@@ -7,6 +7,7 @@ import {
   type Resource,
   type ResourceProps,
 } from "./resource";
+import { Secret } from "./secret";
 import type { State } from "./state";
 import { serialize } from "./util/serde";
 
@@ -17,12 +18,12 @@ export interface ApplyOptions {
 
 export async function apply<Out extends Resource>(
   resource: PendingResource<Out>,
-  props: ResourceProps,
+  props: ResourceProps | undefined,
   options?: ApplyOptions,
 ): Promise<Awaited<Out>> {
   const scope = resource.Scope;
   try {
-    const quiet = props.quiet ?? scope.quiet;
+    const quiet = props?.quiet ?? scope.quiet;
     await scope.init();
     let state: State | undefined = (await scope.state.get(resource.ID))!;
     const provider: Provider = PROVIDERS.get(resource.Kind);
@@ -55,17 +56,27 @@ export async function apply<Out extends Resource>(
 
     // Skip update if inputs haven't changed and resource is in a stable state
     if (state.status === "created" || state.status === "updated") {
-      if (
-        JSON.stringify(state.props) ===
-          JSON.stringify(await serialize(scope, props)) &&
-        alwaysUpdate !== true
-      ) {
+      const oldProps = JSON.stringify(
+        state.props,
+        (_, value) =>
+          value instanceof Secret
+            ? {
+                "@secret": value.unencrypted,
+              }
+            : value,
+        2,
+      );
+      const newProps = JSON.stringify(
+        await serialize(scope, props, {
+          encrypt: false,
+        }),
+        null,
+        2,
+      );
+      if (oldProps === newProps && alwaysUpdate !== true) {
         if (!quiet) {
           console.log(`Skip:    "${resource.FQN}" (no changes)`);
         }
-        // if (resourceState.output !== undefined) {
-        //   resource[Provide](resourceState.output);
-        // }
         return state.output as Awaited<Out>;
       }
     }
@@ -92,6 +103,7 @@ export async function apply<Out extends Resource>(
       id: resource.ID,
       fqn: resource.FQN,
       seq: resource.Seq,
+      props: state.oldProps,
       state,
       replace: () => {
         if (isReplaced) {
@@ -104,9 +116,9 @@ export async function apply<Out extends Resource>(
       },
     });
 
-    const output = await alchemy.run(resource.ID, async () => {
-      return provider.handler.bind(ctx)(resource.ID, props);
-    });
+    const output = await alchemy.run(resource.ID, async () =>
+      provider.handler.bind(ctx)(resource.ID, props),
+    );
 
     if (!quiet) {
       console.log(

package/src/context.ts

@@ -9,24 +9,33 @@ import type {
 import type { Scope } from "./scope";
 import type { State } from "./state";
 
-export type Context<Out extends Resource> =
-  | CreateContext<Out>
-  | UpdateContext<Out>
-  | DeleteContext<Out>;
+export type Context<
+  Out extends Resource,
+  Props extends ResourceProps = ResourceProps,
+> = CreateContext<Out> | UpdateContext<Out, Props> | DeleteContext<Out, Props>;
 
 export interface CreateContext<Out extends Resource> extends BaseContext<Out> {
   phase: "create";
   output?: undefined;
+  props?: undefined;
 }
 
-export interface UpdateContext<Out extends Resource> extends BaseContext<Out> {
+export interface UpdateContext<
+  Out extends Resource,
+  Props extends ResourceProps = ResourceProps,
+> extends BaseContext<Out> {
   phase: "update";
   output: Out;
+  props: Props;
 }
 
-export interface DeleteContext<Out extends Resource> extends BaseContext<Out> {
+export interface DeleteContext<
+  Out extends Resource,
+  Props extends ResourceProps = ResourceProps,
+> extends BaseContext<Out> {
   phase: "delete";
   output: Out;
+  props: Props;
 }
 
 export interface BaseContext<Out extends Resource> {
@@ -43,7 +52,6 @@ export interface BaseContext<Out extends Resource> {
    * This will cause the resource to be deleted at the end of the stack's CREATE phase.
    */
   replace(): void;
-
   /**
    * Terminate the resource lifecycle handler and destroy the resource.
    *
@@ -60,12 +68,13 @@ export interface BaseContext<Out extends Resource> {
   /**
    * Create the Resource envelope (with Alchemy + User properties)
    */
+  (id: string, props: Omit<Out, keyof Resource>): Out;
   (props: Omit<Out, keyof Resource>): Out;
 }
 
 export function context<
   Kind extends string,
-  Props extends ResourceProps,
+  Props extends ResourceProps | undefined,
   Out extends Resource,
 >({
   scope,
@@ -83,14 +92,24 @@ export function context<
   id: ResourceID;
   fqn: ResourceFQN;
   seq: number;
+  props: Props;
   state: State<Kind, Props, Out>;
   replace: () => void;
 }): Context<Out> {
-  function create(props: Omit<Out, "Kind" | "ID" | "Scope">): Out {
+  function create(props: Omit<Out, "Kind" | "ID" | "Scope">): Out;
+  function create(id: string, props: Omit<Out, "Kind" | "ID" | "Scope">): Out;
+  function create(
+    ...args:
+      | [props: Omit<Out, "Kind" | "ID" | "Scope">]
+      | [id: string, props: Omit<Out, "Kind" | "ID" | "Scope">]
+  ): Out {
+    const [ID, props] =
+      typeof args[0] === "string" ? (args as [string, any]) : [id, args[0]];
+
     return {
       ...props,
       Kind: kind,
-      ID: id,
+      ID,
       FQN: fqn,
       Scope: scope,
       Seq: seq,
@@ -103,6 +122,7 @@ export function context<
     fqn: fqn,
     phase,
     output: state.output,
+    props: state.props,
     replace,
     get: (key: string) => state.data[key],
     set: async (key: string, value: any) => {

package/src/destroy.ts

@@ -23,12 +23,15 @@ export async function destroy<Type extends string>(
     | [resource: Resource<Type> | undefined | null, options?: DestroyOptions]
 ): Promise<void> {
   if (isScopeArgs(args)) {
-    const [scope, options] = args;
-    const strategy = options?.strategy ?? "sequential";
+    const [scope] = args;
+    const options = {
+      strategy: "sequential",
+      ...(args[1] ?? {}),
+    } satisfies DestroyOptions;
+
     // destroy all active resources
-    await destroy.all(Array.from(scope.resources.values()), {
-      strategy,
-    });
+    await destroy.all(Array.from(scope.resources.values()), options);
+
     // then detect orphans and destroy them
     const orphans = await scope.state.all();
     await destroy.all(
@@ -67,10 +70,9 @@ export async function destroy<Type extends string>(
       console.log(`Delete:  "${instance.FQN}"`);
     }
 
-    const state = (await scope.state.get(instance.ID))!;
+    const state = await scope.state.get(instance.ID);
 
     if (state === undefined) {
-      console.warn(`Resource "${instance.FQN}" not found`);
       return;
     }
 
@@ -81,6 +83,7 @@ export async function destroy<Type extends string>(
       id: instance.ID,
       fqn: instance.FQN,
       seq: instance.Seq,
+      props: state.props,
       state,
       replace: () => {
         throw new Error("Cannot replace a resource that is being deleted");