alchemy 0.3.1 → 0.4.1

package/README.md

@@ -9,8 +9,10 @@ Resources are simple memoized async functions that can run in any JavaScript run
 ```ts
 import alchemy from "alchemy";
 
-await using app = alchemy("cloudflare-worker");
+// initialize the app (with default state $USER)
+const app = alchemy("cloudflare-worker");
 
+// create a Cloudflare Worker
 export const worker = await Worker("worker", {
   name: "my-worker",
   entrypoint: "./src/index.ts",
@@ -18,10 +20,13 @@ export const worker = await Worker("worker", {
     COUNTER: counter,
     STORAGE: storage, // Bind the R2 bucket to the worker
     AUTH_STORE: authStore,
-    GITHUB_CLIENT_ID: secret(process.env.GITHUB_CLIENT_ID),
-    GITHUB_CLIENT_SECRET: secret(process.env.GITHUB_CLIENT_SECRET),
+    GITHUB_CLIENT_ID: alchemy.secret(process.env.GITHUB_CLIENT_ID),
+    GITHUB_CLIENT_SECRET: alchemy.secret(process.env.GITHUB_CLIENT_SECRET),
   },
 });
+
+// finalize the alchemy app (triggering deletion of orphaned resources)
+await app.finalize();
 ```
 
 # Features

package/lib/ai/document.d.ts

@@ -10,8 +10,10 @@ import { type ModelConfig } from "./client";
 export interface DocumentProps {
     /**
      * Title of the document
+     *
+     * @default id
      */
-    title: string;
+    title?: string;
     /**
      * Optional path to the markdown document
      * If provided, document will be written to this path
@@ -72,11 +74,20 @@ export interface DocumentProps {
      * @default 10000
      */
     maxTokens?: number;
+    /**
+     * Freeze the document after creation (do not re-generate on updates)
+     * @default false
+     */
+    freeze?: boolean;
 }
 /**
  * A markdown document that can be created, updated, and deleted
  */
 export interface Document extends DocumentProps, Resource<"docs::Document"> {
+    /**
+     * The title of the document
+     */
+    title: string;
     /**
      * Content of the document
      */

package/lib/ai/document.js

@@ -99,6 +99,14 @@ export const Document = Resource("docs::Document", async function (id, props) {
     if (this.phase === "delete") {
         return this.destroy();
     }
+    if (this.phase === "update" && props.freeze) {
+        if (props.path) {
+            const filePath = props.path;
+            const fileId = `${id}-file`;
+            await StaticTextFile(fileId, filePath, this.output.content);
+        }
+        return this(this.output);
+    }
     // Use provided system prompt or default
     const system = props.system || DEFAULT_MD_SYSTEM_PROMPT;
     // Generate initial content with rate limit retry
@@ -137,7 +145,7 @@ export const Document = Resource("docs::Document", async function (id, props) {
         });
         const retryResult = extractMarkdownContent(retryText);
         if (retryResult.error) {
-            throw new Error(`Failed to generate valid markdown content: ${retryResult.error}`);
+            throw new Error(`Failed to generate valid markdown content: ${retryResult.error}\n${retryText}`);
         }
         content = retryResult.content;
     }
@@ -151,6 +159,7 @@ export const Document = Resource("docs::Document", async function (id, props) {
         ],
         createdAt: this.output?.createdAt || Date.now(),
         updatedAt: Date.now(),
+        title: props.title || id,
     };
     // Write file if path is provided
     if (props.path) {

package/lib/ai/index.d.ts

@@ -1,4 +1,3 @@
-export * from "./approve";
 export * from "./ark";
 export * from "./astro-file";
 export * from "./css-file";
@@ -6,7 +5,6 @@ export * from "./data";
 export * from "./document";
 export * from "./html-file";
 export * from "./json-file";
-export * from "./review";
 export * from "./typescript-file";
 export * from "./vue-file";
 export * from "./yaml-file";

package/lib/ai/index.js

@@ -1,4 +1,3 @@
-export * from "./approve";
 export * from "./ark";
 export * from "./astro-file";
 export * from "./css-file";
@@ -6,7 +5,6 @@ export * from "./data";
 export * from "./document";
 export * from "./html-file";
 export * from "./json-file";
-export * from "./review";
 export * from "./typescript-file";
 export * from "./vue-file";
 export * from "./yaml-file";

package/lib/alchemy.d.ts

@@ -31,6 +31,10 @@ export interface Alchemy {
     scope: typeof scope;
     run: typeof run;
     destroy: typeof destroy;
+    /**
+     * Get an environment variable and error if it's not set.
+     */
+    env: typeof env;
     /**
      * Creates an encrypted secret that can be safely stored in state files.
      * Requires a password to be set either globally in the application options
@@ -146,4 +150,5 @@ declare function run<T>(...args: [id: string, fn: (this: Scope, scope: Scope) =>
     options: AlchemyOptions,
     fn: (this: Scope, scope: Scope) => Promise<T>
 ]): Promise<T>;
+export declare function env<T = string>(name: string, value?: T | undefined, error?: string): Promise<T>;
 export {};

package/lib/alchemy.js

@@ -13,11 +13,17 @@ export const alchemy = _alchemy;
 function _alchemy(...args) {
     if (typeof args[0] === "string") {
         const [appName, options] = args;
-        return scope(undefined, {
+        const root = scope(undefined, {
             ...options,
             appName,
             stage: options?.stage,
         });
+        if (options?.phase === "destroy") {
+            return destroy(root).finally(() => {
+                process.exit(0);
+            });
+        }
+        return root;
     }
     else {
         const [template, ...values] = args;
@@ -64,6 +70,22 @@ function _alchemy(...args) {
                 else if (Array.isArray(value)) {
                     return (await Promise.all(value.map(async (value, i) => `${i}. ${await resolve(value)}`))).join("\n");
                 }
+                else if (typeof value === "object" &&
+                    typeof value.path === "string") {
+                    if (typeof value.content === "string") {
+                        appendices[value.path] = value.content;
+                        return `[${path.basename(value.path)}](${value.path})`;
+                    }
+                    else {
+                        appendices[value.path] = await fs.readFile(value.path, "utf-8");
+                        return `[${path.basename(value.path)}](${value.path})`;
+                    }
+                }
+                else if (typeof value === "object") {
+                    return (await Promise.all(Object.entries(value).map(async ([key, value]) => {
+                        return `* ${key}: ${await resolve(value)}`;
+                    }))).join("\n");
+                }
                 else {
                     // TODO: support other types
                     console.log(value);
@@ -102,6 +124,7 @@ _alchemy.destroy = destroy;
 _alchemy.run = run;
 _alchemy.scope = scope;
 _alchemy.secret = secret;
+_alchemy.env = env;
 /**
  * Enter a new scope synchronously.
  *
@@ -165,3 +188,23 @@ async function run(...args) {
         await scope.finalize();
     }
 }
+export async function env(name, value, error) {
+    if (value !== undefined) {
+        return value;
+    }
+    else if (typeof process !== undefined) {
+        // we are in a node environment
+        return process.env[name];
+    }
+    else {
+        // we are in a browser environment
+        try {
+            const { env } = await import("cloudflare:workers");
+            if (name in env) {
+                return env[name];
+            }
+        }
+        catch (error) { }
+    }
+    throw new Error(error ?? `Environment variable ${name} is not set`);
+}

package/lib/apply.js

@@ -1,8 +1,7 @@
 import { alchemy } from "./alchemy";
 import { context } from "./context";
 import { PROVIDERS, } from "./resource";
-import { Secret } from "./secret";
-import { serialize } from "./util/serde";
+import { serialize } from "./serde";
 export async function apply(resource, props, options) {
     const scope = resource.Scope;
     try {
@@ -36,20 +35,27 @@ export async function apply(resource, props, options) {
         const alwaysUpdate = options?.alwaysUpdate ?? provider.options?.alwaysUpdate ?? false;
         // Skip update if inputs haven't changed and resource is in a stable state
         if (state.status === "created" || state.status === "updated") {
-            const oldProps = JSON.stringify(state.props, (_, value) => value instanceof Secret
-                ? {
-                    "@secret": value.unencrypted,
-                }
-                : value, 2);
-            const newProps = JSON.stringify(await serialize(scope, props, {
+            const oldProps = await serialize(scope, state.props, {
+                encrypt: false,
+            });
+            const newProps = await serialize(scope, props, {
                 encrypt: false,
-            }), null, 2);
-            if (oldProps === newProps && alwaysUpdate !== true) {
+            });
+            if (JSON.stringify(oldProps) === JSON.stringify(newProps) &&
+                alwaysUpdate !== true) {
                 if (!quiet) {
                     // console.log(`Skip:    "${resource.FQN}" (no changes)`);
                 }
                 return state.output;
             }
+            const diff = await import("diff");
+            const yaml = await import("yaml");
+            const old = yaml.stringify(oldProps);
+            const news = yaml.stringify(newProps);
+            const patch = diff.createPatch(resource.ID, old, news);
+            // console.log(patch);
+            // if (resource.ID === "what-is-alchemy") {
+            // }
         }
         const phase = state.status === "creating" ? "create" : "update";
         state.status = phase === "create" ? "creating" : "updating";
@@ -98,6 +104,7 @@ export async function apply(resource, props, options) {
         return output;
     }
     catch (error) {
+        console.error(new Error().stack);
         scope.fail();
         throw error;
     }

package/lib/aws/account-id.d.ts

@@ -1,4 +1,7 @@
+export type AccountId = string & {
+    readonly __brand: "AccountId";
+};
 /**
  * Helper to get the current AWS account ID
  */
-export declare function getAccountId(): Promise<string>;
+export declare function AccountId(): Promise<AccountId>;

package/lib/aws/account-id.js

@@ -3,7 +3,7 @@ const sts = new STSClient({});
 /**
  * Helper to get the current AWS account ID
  */
-export async function getAccountId() {
+export async function AccountId() {
     const identity = await sts.send(new GetCallerIdentityCommand({}));
     return identity.Account;
 }

package/lib/aws/credentials.d.ts

@@ -0,0 +1,5 @@
+import type { Secret } from "../secret";
+export interface AwsCredentials {
+    accessKeyId: Secret;
+    secretAccessKey: Secret;
+}

package/lib/aws/oidc/oidc-provider.js

@@ -1,6 +1,6 @@
 import { CreateOpenIDConnectProviderCommand, DeleteOpenIDConnectProviderCommand, GetOpenIDConnectProviderCommand, GetRoleCommand, IAMClient, UpdateAssumeRolePolicyCommand, } from "@aws-sdk/client-iam";
 import { Resource } from "../../resource";
-import { getAccountId } from "../account-id";
+import { AccountId } from "../account-id";
 /**
  * AWS OIDC Provider Resource for GitHub Actions
  *
@@ -91,7 +91,7 @@ export const OIDCProvider = Resource("aws::OIDCProvider", async function (id, pr
         catch (error) {
             if (error.name === "EntityAlreadyExistsException") {
                 // Provider exists, use its ARN
-                providerArn = `arn:aws:iam::${await getAccountId()}:oidc-provider/${url}`;
+                providerArn = `arn:aws:iam::${await AccountId()}:oidc-provider/${url}`;
             }
             else {
                 throw error;

package/lib/aws/role.js

@@ -118,38 +118,50 @@ import { ignore } from "../util/ignore";
 export const Role = Resource("iam::Role", async function (id, props) {
     const client = new IAMClient({});
     if (this.phase === "delete") {
-        // Delete any inline policies first
-        if (props.policies) {
-            for (const policy of props.policies) {
-                await ignore(NoSuchEntityException.name, () => client.send(new DeleteRolePolicyCommand({
-                    RoleName: props.roleName,
-                    PolicyName: policy.policyName,
-                })));
-            }
-        }
-        // We need to detach managed policies before deleting the role
-        // First, get all attached policies
         try {
-            const attachedPoliciesResponse = await client.send(new ListAttachedRolePoliciesCommand({
-                RoleName: props.roleName,
-            }));
-            // Detach all managed policies
-            const attachedPolicies = attachedPoliciesResponse.AttachedPolicies || [];
-            for (const policy of attachedPolicies) {
-                await client.send(new DetachRolePolicyCommand({
+            // Delete any inline policies first
+            if (props.policies) {
+                for (const policy of props.policies) {
+                    await ignore(NoSuchEntityException.name, () => client.send(new DeleteRolePolicyCommand({
+                        RoleName: props.roleName,
+                        PolicyName: policy.policyName,
+                    })));
+                }
+            }
+            // We need to detach managed policies before deleting the role
+            // First, get all attached policies
+            try {
+                const attachedPoliciesResponse = await client.send(new ListAttachedRolePoliciesCommand({
                     RoleName: props.roleName,
-                    PolicyArn: policy.PolicyArn,
                 }));
+                // Detach all managed policies
+                const attachedPolicies = attachedPoliciesResponse.AttachedPolicies || [];
+                for (const policy of attachedPolicies) {
+                    await ignore(NoSuchEntityException.name, () => client.send(new DetachRolePolicyCommand({
+                        RoleName: props.roleName,
+                        PolicyArn: policy.PolicyArn,
+                    })));
+                }
             }
+            catch (error) {
+                if (error.name !== NoSuchEntityException.name) {
+                    throw error;
+                }
+                // Role doesn't exist, no need to continue with detaching policies
+            }
+            // Try to delete the role, ignoring if it doesn't exist
+            await ignore(NoSuchEntityException.name, () => client.send(new DeleteRoleCommand({
+                RoleName: props.roleName,
+            })));
         }
         catch (error) {
+            // If we get any other error besides NoSuchEntityException, log it but don't fail
+            // This ensures the resource is still marked as destroyed
             if (error.name !== NoSuchEntityException.name) {
-                throw error;
+                console.error(`Error deleting role ${props.roleName}:`, error);
             }
         }
-        await ignore(NoSuchEntityException.name, () => client.send(new DeleteRoleCommand({
-            RoleName: props.roleName,
-        })));
+        // Always return destroyed state regardless of any errors
         return this.destroy();
     }
     const assumeRolePolicyDocument = JSON.stringify(props.assumeRolePolicy);

package/lib/cloudflare/account-api-token.d.ts

@@ -0,0 +1,168 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { Secret } from "../secret";
+/**
+ * Permission group for a token policy
+ */
+export interface TokenPolicyPermissionGroup {
+    /**
+     * ID of the permission group
+     */
+    id: string;
+    /**
+     * Optional metadata for the permission group
+     */
+    meta?: Record<string, any>;
+}
+/**
+ * Policy that defines what the token can access
+ */
+export interface TokenPolicy {
+    /**
+     * Effect of the policy
+     */
+    effect: "allow" | "deny";
+    /**
+     * Permission groups to include in the policy
+     */
+    permissionGroups: TokenPolicyPermissionGroup[];
+    /**
+     * Resources the policy applies to
+     */
+    resources: Record<string, string>;
+}
+/**
+ * Condition for token usage (e.g., IP restrictions)
+ */
+export interface TokenCondition {
+    /**
+     * IP address conditions
+     */
+    requestIp?: {
+        /**
+         * IP ranges to allow
+         */
+        in?: string[];
+        /**
+         * IP ranges to deny
+         */
+        notIn?: string[];
+    };
+}
+/**
+ * Properties for creating or updating an Account API Token
+ */
+export interface AccountApiTokenProps {
+    /**
+     * Name of the token
+     */
+    name: string;
+    /**
+     * Policies that define what the token can access
+     */
+    policies: TokenPolicy[];
+    /**
+     * Optional expiration date for the token (ISO format)
+     */
+    expiresOn?: string;
+    /**
+     * Optional "not before" date (token is not valid before this date) (ISO format)
+     */
+    notBefore?: string;
+    /**
+     * Optional conditions for token use (like IP restrictions)
+     */
+    condition?: TokenCondition;
+}
+/**
+ * Output returned after Account API Token creation/update
+ */
+export interface AccountApiToken extends Resource<"cloudflare::AccountApiToken">, AccountApiTokenProps {
+    /**
+     * The ID of the token
+     *
+     * Equiv. to ACCESS_KEY_ID
+     */
+    id: string;
+    /**
+     * Status of the token
+     */
+    status: string;
+    /**
+     * Actual token value (only available on creation)
+     * Stored as a Secret for security
+     *
+     * Equiv. to SECRET_ACCESS_KEY
+     */
+    value?: Secret;
+    /**
+     * Access key ID for the token
+     *
+     * An alias of {@link id}
+     */
+    accessKeyId: string;
+    /**
+     * Secret access key for the token
+     *
+     * The SHA-256 hash of the token {@link value}
+     *
+     * @see https://developers.cloudflare.com/r2/api/tokens/#get-s3-api-credentials-from-an-api-token
+     */
+    secretAccessKey: string;
+}
+/**
+ * Creates a Cloudflare Account API Token with specified permissions.
+ *
+ * @see https://developers.cloudflare.com/api/resources/accounts/subresources/tokens/methods/create/
+ *
+ * @example
+ * // First, fetch all permission groups
+ * const permissions = await PermissionGroups("cloudflare-permissions", {
+ *   accountId: cfAccountId,
+ * });
+ *
+ * // Create a token with read-only permissions for specific zones
+ * const readOnlyToken = await AccountApiToken("readonly-token", {
+ *   name: "Readonly Zone Token",
+ *   policies: [
+ *     {
+ *       effect: "allow",
+ *       permissionGroups: [
+ *         { id: permissions["Zone Read"].id },
+ *         { id: permissions["Analytics Read"].id }
+ *       ],
+ *       resources: {
+ *         "com.cloudflare.api.account.zone.22b1de5f1c0e4b3ea97bb1e963b06a43": "*",
+ *         "com.cloudflare.api.account.zone.eb78d65290b24279ba6f44721b3ea3c4": "*"
+ *       }
+ *     }
+ *   ],
+ *   expiresOn: "2024-12-31T23:59:59Z"
+ * });
+ *
+ * @example
+ * // Create a token with time and IP restrictions
+ * const restrictedToken = await AccountApiToken("restricted-token", {
+ *   name: "Restricted Access Token",
+ *   policies: [
+ *     {
+ *       effect: "allow",
+ *       permissionGroups: [
+ *         { id: permissions["Worker Routes Edit"].id }
+ *       ],
+ *       resources: {
+ *         "com.cloudflare.api.account.worker.route.*": "*"
+ *       }
+ *     }
+ *   ],
+ *   notBefore: "2023-01-01T00:00:00Z",
+ *   expiresOn: "2023-12-31T23:59:59Z",
+ *   condition: {
+ *     requestIp: {
+ *       in: ["192.168.1.0/24", "10.0.0.0/8"],
+ *       notIn: ["192.168.1.100/32"]
+ *     }
+ *   }
+ * });
+ */
+export declare const AccountApiToken: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<AccountApiToken>, id: string, props: AccountApiTokenProps) => Promise<AccountApiToken>);