alchemy 0.62.2 → 0.63.0

package/src/alchemy.ts

@@ -1,6 +1,3 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-
 import { execArgv } from "node:process";
 import { onExit } from "signal-exit";
 import { ReplacedSignal } from "./apply.ts";
@@ -14,12 +11,10 @@ import {
   ResourceSeq,
   type PendingResource,
 } from "./resource.ts";
-import { isRuntime } from "./runtime/global.ts";
 import { DEFAULT_STAGE, Scope, type ProviderCredentials } from "./scope.ts";
 import { secret } from "./secret.ts";
 import type { StateStoreType } from "./state.ts";
 import type { LoggerApi } from "./util/cli.ts";
-import { logger } from "./util/logger.ts";
 import { TelemetryClient } from "./util/telemetry/client.ts";
 
 /**
@@ -71,10 +66,6 @@ export interface Alchemy {
    * or locally in the current scope.
    */
   secret: typeof secret;
-  /**
-   * Whether the current runtime is the Cloudflare Workers runtime.
-   */
-  isRuntime: boolean;
 
   /**
    * Creates a new application scope with the given name and options.
@@ -95,74 +86,51 @@ export interface Alchemy {
    * });
    */
   (appName: string, options?: Omit<AlchemyOptions, "appName">): Promise<Scope>;
-  /**
-   * Template literal tag that supports file interpolation for documentation.
-   * Automatically formats the content and appends file contents as code blocks.
-   *
-   * @example
-   * // Generate documentation using file contents
-   * await Document("api-docs", {
-   *   prompt: await alchemy`
-   *     Generate docs using the contents of:
-   *     ${alchemy.file("README.md")}
-   *     ${alchemy.file("./.cursorrules")}
-   *
-   *     And here are the source files:
-   *     ${alchemy.files(files)}
-   *   `
-   * });
-   */
-  (template: TemplateStringsArray, ...values: any[]): Promise<string>;
 }
 
 _alchemy.destroy = destroy;
 _alchemy.run = run;
 _alchemy.secret = secret;
 _alchemy.env = env;
-_alchemy.isRuntime = isRuntime;
 
 /**
- * Implementation of the alchemy function that handles both application scoping
- * and template string interpolation.
+ * Implementation of the alchemy function.
  */
 async function _alchemy(
-  ...args:
-    | [template: TemplateStringsArray, ...values: any[]]
-    | [appName: string, options?: Omit<AlchemyOptions, "appName">]
-): Promise<Scope | string | never> {
-  if (typeof args[0] === "string") {
-    const [appName, options] = args as [string, AlchemyOptions?];
-
-    const cliArgs = process.argv.slice(2);
-    const cliOptions = {
-      phase: cliArgs.includes("--destroy")
-        ? "destroy"
-        : cliArgs.includes("--read")
-          ? "read"
-          : "up",
-      local: cliArgs.includes("--local") || cliArgs.includes("--dev"),
-      watch: cliArgs.includes("--watch") || execArgv.includes("--watch"),
-      quiet: cliArgs.includes("--quiet"),
-      force: cliArgs.includes("--force"),
-      // Parse stage argument (--stage my-stage) functionally and inline as a property declaration
-      stage: (function parseStage() {
-        const i = cliArgs.indexOf("--stage");
-        return i !== -1 && i + 1 < cliArgs.length
-          ? cliArgs[i + 1]
-          : process.env.STAGE;
-      })(),
-      password: process.env.ALCHEMY_PASSWORD,
-    } satisfies Partial<AlchemyOptions>;
-    const mergedOptions = {
-      ...cliOptions,
-      ...options,
-    };
-    if (
-      mergedOptions.stateStore === undefined &&
-      process.env.CI &&
-      process.env.ALCHEMY_CI_STATE_STORE_CHECK !== "false"
-    ) {
-      throw new Error(`You are running Alchemy in a CI environment with the default local state store. 
+  appName: string,
+  options?: Omit<AlchemyOptions, "appName">,
+): Promise<Scope> {
+  const cliArgs = process.argv.slice(2);
+  const cliOptions = {
+    phase: cliArgs.includes("--destroy")
+      ? "destroy"
+      : cliArgs.includes("--read")
+        ? "read"
+        : "up",
+    local: cliArgs.includes("--local") || cliArgs.includes("--dev"),
+    watch: cliArgs.includes("--watch") || execArgv.includes("--watch"),
+    quiet: cliArgs.includes("--quiet"),
+    force: cliArgs.includes("--force"),
+    // Parse stage argument (--stage my-stage) functionally and inline as a property declaration
+    stage: (function parseStage() {
+      const i = cliArgs.indexOf("--stage");
+      return i !== -1 && i + 1 < cliArgs.length
+        ? cliArgs[i + 1]
+        : process.env.STAGE;
+    })(),
+    password: process.env.ALCHEMY_PASSWORD,
+    adopt: cliArgs.includes("--adopt"),
+  } satisfies Partial<AlchemyOptions>;
+  const mergedOptions = {
+    ...cliOptions,
+    ...options,
+  };
+  if (
+    mergedOptions.stateStore === undefined &&
+    process.env.CI &&
+    process.env.ALCHEMY_CI_STATE_STORE_CHECK !== "false"
+  ) {
+    throw new Error(`You are running Alchemy in a CI environment with the default local state store. 
 This can lead to orphaned infrastructure and is rarely what you want to do.
 
 Instead, you should choose a persistent state store:
@@ -173,165 +141,45 @@ You can read more about State and State Stores here: https://alchemy.run/concept
 
 If this is a mistake, you can disable this check by setting the ALCHEMY_CI_STATE_STORE_CHECK=false.
 `);
-    }
+  }
 
-    const phase = isRuntime ? "read" : (mergedOptions?.phase ?? "up");
-    const telemetryClient =
-      mergedOptions?.parent?.telemetryClient ??
-      TelemetryClient.create({
-        phase,
-        enabled: mergedOptions?.telemetry ?? true,
-        quiet: mergedOptions?.quiet ?? false,
-      });
-    const root = new Scope({
-      ...mergedOptions,
-      parent: undefined,
-      scopeName: appName,
+  const phase = mergedOptions?.phase ?? "up";
+  const telemetryClient =
+    mergedOptions?.parent?.telemetryClient ??
+    TelemetryClient.create({
       phase,
-      password: mergedOptions?.password ?? process.env.ALCHEMY_PASSWORD,
-      telemetryClient,
+      enabled: mergedOptions?.telemetry ?? true,
+      quiet: mergedOptions?.quiet ?? false,
     });
-    onExit((code) => {
-      root.cleanup().then(() => {
-        code = code === 130 ? 0 : (code ?? 0);
-        process.exit(code);
-      });
-      return true;
-    });
-    const stageName = mergedOptions?.stage ?? DEFAULT_STAGE;
-    const stage = new Scope({
-      ...mergedOptions,
-      parent: root,
-      scopeName: stageName,
-      stage: stageName,
+  const root = new Scope({
+    ...mergedOptions,
+    parent: undefined,
+    scopeName: appName,
+    phase,
+    password: mergedOptions?.password ?? process.env.ALCHEMY_PASSWORD,
+    telemetryClient,
+  });
+  onExit((code) => {
+    root.cleanup().then(() => {
+      code = code === 130 ? 0 : (code ?? 0);
+      process.exit(code);
     });
-    try {
-      Scope.storage.enterWith(root);
-      Scope.storage.enterWith(stage);
-    } catch {
-      // we are in Cloudflare Workers, we will emulate the enterWith behavior
-      // see Scope.finalize for where we pop the global scope
-      Scope.globals.push(root);
-      Scope.globals.push(stage);
-    }
-    if (mergedOptions?.phase === "destroy") {
-      await destroy(stage);
-      return process.exit(0);
-    }
-    return root;
+    return true;
+  });
+  const stageName = mergedOptions?.stage ?? DEFAULT_STAGE;
+  const stage = new Scope({
+    ...mergedOptions,
+    parent: root,
+    scopeName: stageName,
+    stage: stageName,
+  });
+  Scope.storage.enterWith(root);
+  Scope.storage.enterWith(stage);
+  if (mergedOptions?.phase === "destroy") {
+    await destroy(stage);
+    return process.exit(0);
   }
-  const [template, ...values] = args;
-  const [, secondLine] = template[0].split("\n");
-  const leadingSpaces = secondLine
-    ? secondLine.match(/^(\s*)/)?.[1]?.length || 0
-    : 0;
-  const indent = " ".repeat(leadingSpaces);
-
-  const [{ isFileRef }, { isFileCollection }] = await Promise.all([
-    import("./fs/file-ref.js"),
-    import("./fs/file-collection.js"),
-  ]);
-
-  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;
-      }
-      if (value === null) {
-        return "null";
-      }
-      if (value === undefined) {
-        return "undefined";
-      }
-      if (
-        typeof value === "number" ||
-        typeof value === "boolean" ||
-        typeof value === "bigint"
-      ) {
-        return value.toString();
-      }
-      if (value instanceof Promise) {
-        return resolve(await value);
-      }
-      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})`;
-      }
-      if (isFileCollection(value)) {
-        return Object.entries(value.files)
-          .map(([filePath, content]) => {
-            appendices[filePath] = content;
-            return `[${path.basename(filePath)}](${filePath})`;
-          })
-          .join("\n\n");
-      }
-      if (Array.isArray(value)) {
-        return (
-          await Promise.all(
-            value.map(async (value, i) => `${i}. ${await resolve(value)}`),
-          )
-        ).join("\n");
-      }
-      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})`;
-        }
-        appendices[value.path] = await fs.readFile(value.path, "utf-8");
-        return `[${path.basename(value.path)}](${value.path})`;
-      }
-      if (typeof value === "object") {
-        return (
-          await Promise.all(
-            Object.entries(value).map(async ([key, value]) => {
-              return `* ${key}: ${await resolve(value)}`;
-            }),
-          )
-        ).join("\n");
-      }
-      // TODO: support other types
-      logger.log(value);
-      throw new Error(`Unsupported value type: ${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");
+  return root;
 }
 
 export type Phase = "up" | "destroy" | "read";
@@ -414,6 +262,12 @@ export interface AlchemyOptions {
    * If not provided, the default fallback logger will be used.
    */
   logger?: LoggerApi;
+  /**
+   * Whether to adopt resources if they already exist but are not yet managed by your Alchemy app.
+   *
+   * @default false
+   */
+  adopt?: boolean;
 }
 
 export interface ScopeOptions extends AlchemyOptions {
@@ -463,7 +317,7 @@ async function run<T>(
   const telemetryClient =
     options?.parent?.telemetryClient ??
     TelemetryClient.create({
-      phase: isRuntime ? "read" : (options?.phase ?? "up"),
+      phase: options?.phase ?? "up",
       enabled: options?.telemetry ?? true,
       quiet: options?.quiet ?? false,
     });

package/src/apply.ts

@@ -13,7 +13,7 @@ import {
   type Resource,
   type ResourceProps,
 } from "./resource.ts";
-import { Scope, type PendingDeletions } from "./scope.ts";
+import type { PendingDeletions } from "./scope.ts";
 import { serialize } from "./serde.ts";
 import { formatFQN } from "./util/cli.ts";
 import { logger } from "./util/logger.ts";
@@ -22,7 +22,6 @@ import type { Telemetry } from "./util/telemetry/index.ts";
 export interface ApplyOptions {
   quiet?: boolean;
   alwaysUpdate?: boolean;
-  resolveInnerScope?: (scope: Scope) => void;
 }
 
 export function apply<Out extends Resource>(
@@ -63,12 +62,6 @@ async function _apply<Out extends Resource>(
           `Resource "${resource[ResourceFQN]}" not found and running in 'read' phase.`,
         );
       }
-      options?.resolveInnerScope?.(
-        new Scope({
-          parent: scope,
-          scopeName: resource[ResourceID],
-        }),
-      );
       scope.telemetryClient.record({
         event: "resource.read",
         resource: resource[ResourceKind],
@@ -115,11 +108,6 @@ async function _apply<Out extends Resource>(
         alwaysUpdate !== true &&
         !scope.force
       ) {
-        const innerScope = new Scope({
-          parent: scope,
-          scopeName: resource[ResourceID],
-        });
-        innerScope.skip();
         if (!quiet) {
           logger.task(resource[ResourceFQN], {
             prefix: "skipped",
@@ -129,7 +117,6 @@ async function _apply<Out extends Resource>(
             status: "success",
           });
         }
-        options?.resolveInnerScope?.(innerScope);
         scope.telemetryClient.record({
           event: "resource.skip",
           resource: resource[ResourceKind],
@@ -199,10 +186,8 @@ async function _apply<Out extends Resource>(
           parent: scope,
           destroyStrategy: provider.options?.destroyStrategy ?? "sequential",
         },
-        async (scope) => {
-          options?.resolveInnerScope?.(scope);
-          return provider.handler.bind(ctx)(resource[ResourceID], props);
-        },
+        async () =>
+          await provider.handler.bind(ctx)(resource[ResourceID], props),
       );
     } catch (error) {
       if (error instanceof ReplacedSignal) {
@@ -216,7 +201,9 @@ async function _apply<Out extends Resource>(
             },
           });
         } else {
-          if (scope.children.get(resource[ResourceID])?.children.size! > 0) {
+          if (
+            (scope.children.get(resource[ResourceID])?.children.size ?? 0) > 0
+          ) {
             throw new Error(
               `Resource ${resource[ResourceFQN]} has children and cannot be replaced.`,
             );

package/src/aws/account-id.ts

@@ -1,6 +1,4 @@
-import { GetCallerIdentityCommand, STSClient } from "@aws-sdk/client-sts";
-
-const sts = new STSClient({});
+import { importPeer } from "../util/peer.ts";
 
 export type AccountId = string & {
   readonly __brand: "AccountId";
@@ -10,6 +8,11 @@ export type AccountId = string & {
  * Helper to get the current AWS account ID
  */
 export async function AccountId(): Promise<AccountId> {
+  const { GetCallerIdentityCommand, STSClient } = await importPeer(
+    import("@aws-sdk/client-sts"),
+    "aws::AccountId",
+  );
+  const sts = new STSClient({});
   const identity = await sts.send(new GetCallerIdentityCommand({}));
   return identity.Account! as AccountId;
 }

package/src/aws/bucket.ts

@@ -1,18 +1,7 @@
-import {
-  CreateBucketCommand,
-  DeleteBucketCommand,
-  GetBucketAclCommand,
-  GetBucketLocationCommand,
-  GetBucketTaggingCommand,
-  GetBucketVersioningCommand,
-  HeadBucketCommand,
-  NoSuchBucket,
-  PutBucketTaggingCommand,
-  S3Client,
-} from "@aws-sdk/client-s3";
 import type { Context } from "../context.ts";
 import { Resource } from "../resource.ts";
 import { ignore } from "../util/ignore.ts";
+import { importPeer } from "../util/peer.ts";
 import { retry } from "./retry.ts";
 
 /**
@@ -22,8 +11,10 @@ export interface BucketProps {
   /**
    * The name of the bucket. Must be globally unique across all AWS accounts.
    * Should be lowercase alphanumeric characters or hyphens.
+   *
+   * @default ${app}-${stage}-${id}
    */
-  bucketName: string;
+  bucketName?: string;
 
   /**
    * Optional tags to apply to the bucket for organization and cost tracking.
@@ -42,6 +33,11 @@ export interface Bucket extends Resource<"s3::Bucket">, BucketProps {
    */
   arn: string;
 
+  /**
+   * Name of the Bucket.
+   */
+  bucketName: string;
+
   /**
    * The global domain name for the bucket
    * Format: bucket-name.s3.amazonaws.com
@@ -129,15 +125,36 @@ export interface Bucket extends Resource<"s3::Bucket">, BucketProps {
  */
 export const Bucket = Resource(
   "s3::Bucket",
-  async function (this: Context<Bucket>, _id: string, props: BucketProps) {
+  async function (this: Context<Bucket>, id: string, props: BucketProps) {
+    const {
+      CreateBucketCommand,
+      DeleteBucketCommand,
+      GetBucketAclCommand,
+      GetBucketLocationCommand,
+      GetBucketTaggingCommand,
+      GetBucketVersioningCommand,
+      HeadBucketCommand,
+      NoSuchBucket,
+      PutBucketTaggingCommand,
+      S3Client,
+    } = await importPeer(import("@aws-sdk/client-s3"), "s3::Bucket");
     const client = new S3Client({});
 
+    const bucketName =
+      props.bucketName ??
+      this.output?.bucketName ??
+      this.scope.createPhysicalName(id);
+
+    if (this.phase === "update" && this.output.bucketName !== bucketName) {
+      this.replace();
+    }
+
     if (this.phase === "delete") {
       await ignore(NoSuchBucket.name, () =>
         retry(() =>
           client.send(
             new DeleteBucketCommand({
-              Bucket: props.bucketName,
+              Bucket: bucketName,
             }),
           ),
         ),
@@ -149,7 +166,7 @@ export const Bucket = Resource(
       await retry(() =>
         client.send(
           new HeadBucketCommand({
-            Bucket: props.bucketName,
+            Bucket: bucketName,
           }),
         ),
       );
@@ -159,7 +176,7 @@ export const Bucket = Resource(
         await retry(() =>
           client.send(
             new PutBucketTaggingCommand({
-              Bucket: props.bucketName,
+              Bucket: bucketName,
               Tagging: {
                 TagSet: Object.entries(props.tags!).map(([Key, Value]) => ({
                   Key,
@@ -176,7 +193,7 @@ export const Bucket = Resource(
         await retry(() =>
           client.send(
             new CreateBucketCommand({
-              Bucket: props.bucketName,
+              Bucket: bucketName,
               // Add tags during creation if specified
               ...(props.tags && {
                 Tagging: {
@@ -198,17 +215,13 @@ export const Bucket = Resource(
     const [locationResponse, versioningResponse, aclResponse] =
       await Promise.all([
         retry(() =>
-          client.send(
-            new GetBucketLocationCommand({ Bucket: props.bucketName }),
-          ),
+          client.send(new GetBucketLocationCommand({ Bucket: bucketName })),
         ),
         retry(() =>
-          client.send(
-            new GetBucketVersioningCommand({ Bucket: props.bucketName }),
-          ),
+          client.send(new GetBucketVersioningCommand({ Bucket: bucketName })),
         ),
         retry(() =>
-          client.send(new GetBucketAclCommand({ Bucket: props.bucketName })),
+          client.send(new GetBucketAclCommand({ Bucket: bucketName })),
         ),
       ]);
 
@@ -219,9 +232,7 @@ export const Bucket = Resource(
     if (!tags) {
       try {
         const taggingResponse = await retry(() =>
-          client.send(
-            new GetBucketTaggingCommand({ Bucket: props.bucketName }),
-          ),
+          client.send(new GetBucketTaggingCommand({ Bucket: bucketName })),
         );
         tags = Object.fromEntries(
           taggingResponse.TagSet?.map(({ Key, Value }) => [Key, Value]) || [],
@@ -234,10 +245,10 @@ export const Bucket = Resource(
     }
 
     return this({
-      bucketName: props.bucketName,
-      arn: `arn:aws:s3:::${props.bucketName}`,
-      bucketDomainName: `${props.bucketName}.s3.amazonaws.com`,
-      bucketRegionalDomainName: `${props.bucketName}.s3.${region}.amazonaws.com`,
+      bucketName: bucketName,
+      arn: `arn:aws:s3:::${bucketName}`,
+      bucketDomainName: `${bucketName}.s3.amazonaws.com`,
+      bucketRegionalDomainName: `${bucketName}.s3.${region}.amazonaws.com`,
       region,
       hostedZoneId: getHostedZoneId(region),
       versioningEnabled: versioningResponse.Status === "Enabled",

package/src/aws/ec2/security-group.ts

@@ -31,8 +31,10 @@ export interface SecurityGroupProps extends AwsClientProps {
 
   /**
    * The name of the security group.
+   *
+   * @default ${app}-${stage}-${id}
    */
-  groupName: string;
+  groupName?: string;
 
   /**
    * The description of the security group.
@@ -62,6 +64,11 @@ export interface SecurityGroup
    */
   groupId: string;
 
+  /**
+   * The name of the security group.
+   */
+  groupName: string;
+
   /**
    * The ID of the VPC the security group belongs to.
    */
@@ -200,7 +207,7 @@ export const SecurityGroup = Resource(
   "aws::SecurityGroup",
   async function (
     this: Context<SecurityGroup>,
-    _id: string,
+    id: string,
     props: SecurityGroupProps,
   ): Promise<SecurityGroup> {
     // Create EC2 client with credential resolution handled internally
@@ -210,6 +217,10 @@ export const SecurityGroup = Resource(
       SECURITY_GROUP_TIMEOUT,
       props.timeout,
     );
+    const groupName = props.groupName ?? this.scope.createPhysicalName(id);
+    if (this.phase === "update" && this.output.groupName !== groupName) {
+      this.replace();
+    }
 
     if (this.phase === "delete") {
       if (this.output?.groupId) {
@@ -259,7 +270,7 @@ export const SecurityGroup = Resource(
     } else {
       // Create new security group
       const createParams: CreateSecurityGroupParams = {
-        GroupName: props.groupName,
+        GroupName: groupName,
         GroupDescription: props.description,
         VpcId: vpcId,
       };
@@ -313,6 +324,7 @@ export const SecurityGroup = Resource(
 
     return this({
       groupId: securityGroup.GroupId,
+      groupName,
       vpcId: securityGroup.VpcId,
       ownerId: securityGroup.OwnerId,
       ...props,