alchemy 2.0.0-beta.3 → 2.0.0-beta.4

package/src/AWS/AuthProvider.ts

@@ -0,0 +1,392 @@
+import * as DistilledAuth from "@distilled.cloud/aws/Auth";
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Match from "effect/Match";
+import * as Path from "effect/Path";
+import * as Redacted from "effect/Redacted";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import {
+  ChildProcess,
+  type ChildProcessSpawner,
+} from "effect/unstable/process";
+import * as NodeCrypto from "node:crypto";
+import * as NodeOs from "node:os";
+import { AuthError, type AuthProvider } from "../Auth/AuthProvider.ts";
+import {
+  deleteCredentials,
+  displayRedacted,
+  readCredentials,
+  writeCredentials,
+} from "../Auth/Credentials.ts";
+import {
+  getEnv,
+  getEnvRedacted,
+  getEnvRedactedRequired,
+  retryOnce,
+} from "../Auth/Env.ts";
+import * as Clank from "../Util/Clank.ts";
+
+export type AwsAuthConfig =
+  | { method: "sso"; ssoProfile: string }
+  | { method: "stored" }
+  | { method: "env" };
+
+const options: Array<{
+  value: AwsAuthConfig["method"];
+  label: string;
+  hint?: string;
+}> = [
+  {
+    value: "sso",
+    label: "SSO",
+    hint: "aws sso login — credentials loaded from AWS SSO cache",
+  },
+  {
+    value: "env",
+    label: "Environment Variables",
+    hint: "AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY",
+  },
+  {
+    value: "stored",
+    label: "Stored",
+    hint: "stored in ~/.alchemy/credentials",
+  },
+];
+
+export interface AwsStoredCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+  region?: string;
+}
+
+export interface AwsResolvedCredentials {
+  accessKeyId: Redacted.Redacted<string>;
+  secretAccessKey: Redacted.Redacted<string>;
+  sessionToken?: Redacted.Redacted<string>;
+  region?: string;
+  source: { type: AwsAuthConfig["method"]; details?: string };
+}
+
+export const AwsAuth = Effect.gen(function* () {
+  const context = yield* Effect.context<
+    | FileSystem.FileSystem
+    | Path.Path
+    | HttpClient.HttpClient
+    | ChildProcessSpawner.ChildProcessSpawner
+  >();
+
+  return {
+    name: "AWS",
+    configure: (profileName: string) =>
+      configureCredentials(profileName).pipe(Effect.provide(context)),
+
+    logout: (profileName, config) =>
+      logout(profileName, config).pipe(Effect.provide(context)),
+
+    login: (profileName, config) =>
+      login(profileName, config).pipe(Effect.provide(context)),
+
+    prettyPrint: (profileName, config) =>
+      prettyPrint(profileName, config).pipe(Effect.provide(context)),
+
+    read: (profileName, config) =>
+      resolveCredentials(profileName, config).pipe(Effect.provide(context)),
+  } satisfies AuthProvider<AwsAuthConfig, AwsResolvedCredentials>;
+});
+
+const runSsoCommand = (command: "login" | "logout", ssoProfile: string) =>
+  Effect.gen(function* () {
+    const handle = yield* ChildProcess.make(
+      "aws",
+      ["sso", command, "--profile", ssoProfile],
+      {
+        shell: false,
+        stdin: "inherit",
+        stdout: "inherit",
+        stderr: "inherit",
+      },
+    );
+    const exit = yield* handle.exitCode;
+    if (exit !== 0) {
+      yield* Effect.fail(
+        new AuthError({
+          message: `aws sso ${command} exited with code ${exit}`,
+        }),
+      );
+    }
+  }).pipe(Effect.scoped);
+
+const resolveCredentials = (profileName: string, config: AwsAuthConfig) =>
+  Match.value(config)
+    .pipe(
+      Match.when(
+        { method: "env" },
+        Effect.fnUntraced(function* () {
+          const accessKeyId =
+            yield* getEnvRedactedRequired("AWS_ACCESS_KEY_ID");
+          const secretAccessKey = yield* getEnvRedactedRequired(
+            "AWS_SECRET_ACCESS_KEY",
+          );
+          const sessionToken = yield* getEnvRedacted("AWS_SESSION_TOKEN");
+          const region = yield* (
+            getEnv("AWS_REGION") ?? getEnv("AWS_DEFAULT_REGION") ?? undefined
+          );
+          return {
+            accessKeyId,
+            secretAccessKey,
+            sessionToken,
+            region,
+            source: { type: "env" as const },
+          };
+        }),
+      ),
+      Match.when({ method: "stored" }, () =>
+        readCredentials<AwsStoredCredentials>(profileName, "aws").pipe(
+          Effect.flatMap((creds) =>
+            creds == null
+              ? Effect.fail(
+                  new AuthError({
+                    message:
+                      "AWS stored credentials not found. Run: alchemy-effect login --configure",
+                  }),
+                )
+              : Effect.succeed({
+                  accessKeyId: Redacted.make(creds.accessKeyId),
+                  secretAccessKey: Redacted.make(creds.secretAccessKey),
+                  sessionToken: creds.sessionToken
+                    ? Redacted.make(creds.sessionToken)
+                    : undefined,
+                  region: creds.region,
+                  source: { type: "stored" as const },
+                }),
+          ),
+        ),
+      ),
+      Match.when({ method: "sso" }, (config) =>
+        Effect.gen(function* () {
+          const auth = yield* DistilledAuth.Default;
+          const creds = yield* auth
+            .loadProfileCredentials(config.ssoProfile)
+            .pipe(
+              Effect.mapError(
+                (e) =>
+                  new AuthError({
+                    message: "failed to load credentials",
+                    cause: e,
+                  }),
+              ),
+            );
+          const profile = yield* auth
+            .loadProfile(config.ssoProfile)
+            .pipe(Effect.catch(() => Effect.succeed(undefined)));
+          return {
+            accessKeyId: creds.accessKeyId,
+            secretAccessKey: creds.secretAccessKey,
+            sessionToken: creds.sessionToken,
+            region: profile?.region,
+            source: { type: "sso" as const, details: config.ssoProfile },
+          };
+        }),
+      ),
+      Match.exhaustive,
+    )
+    .pipe(
+      Effect.mapError(
+        (e) => new AuthError({ message: "login failed", cause: e }),
+      ),
+    );
+
+const prettyPrint = (profileName: string, config: AwsAuthConfig) =>
+  resolveCredentials(profileName, config).pipe(
+    Effect.tap((creds) =>
+      Effect.all([
+        Console.log(`  accessKeyId:     ${displayRedacted(creds.accessKeyId)}`),
+        Console.log(
+          `  secretAccessKey: ${displayRedacted(creds.secretAccessKey)}`,
+        ),
+        creds.sessionToken
+          ? Console.log(
+              `  sessionToken:    ${displayRedacted(creds.sessionToken)}`,
+            )
+          : Effect.void,
+        creds.region
+          ? Console.log(`  region:          ${creds.region}`)
+          : Effect.void,
+        Console.log(
+          //@ts-expect-error
+          `  source: ${creds.source.details ? `${creds.source.type} - ${creds.source.details}` : creds.source.type}`,
+        ),
+      ]),
+    ),
+    Effect.catch((e) =>
+      Console.error(`  Failed to retrieve credentials: ${e}`),
+    ),
+  );
+
+/**
+ * `aws sso logout` only clears AWS CLI's own caches — it does not know about the
+ * `<sha1(sso_session)>.credentials.json` file that `@distilled.cloud/aws`
+ * writes alongside the SSO token. Without this cleanup, `loadProfileCredentials`
+ * short-circuits on the stale distilled cache file after logout and appears to
+ * stay logged in until the role creds hit their TTL.
+ */
+const clearDistilledSsoCache = (ssoProfile: string) =>
+  Effect.gen(function* () {
+    const auth = yield* DistilledAuth.Default;
+    const profile = yield* auth.loadProfile(ssoProfile);
+    const ssoSession = (profile as { sso_session?: string }).sso_session;
+    if (!ssoSession) return;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const hash = NodeCrypto.createHash("sha1").update(ssoSession).digest("hex");
+    const cacheFile = path.join(
+      NodeOs.homedir(),
+      ".aws",
+      "sso",
+      "cache",
+      `${hash}.credentials.json`,
+    );
+    yield* fs.remove(cacheFile).pipe(Effect.catch(() => Effect.void));
+  }).pipe(Effect.catch(() => Effect.void));
+
+const logout = (profileName: string, config: AwsAuthConfig) =>
+  Match.value(config).pipe(
+    Match.when({ method: "env" }, () => Effect.void),
+    Match.when({ method: "sso" }, (config) =>
+      Clank.info(
+        `AWS: running 'aws sso logout --profile ${config.ssoProfile}'...`,
+      ).pipe(
+        Effect.zip(runSsoCommand("logout", config.ssoProfile)),
+        Effect.zip(clearDistilledSsoCache(config.ssoProfile)),
+        Effect.match({
+          onSuccess: () => Clank.success("AWS: SSO logout complete"),
+          onFailure: (e) =>
+            Clank.warn(`AWS: SSO logout failed: \`${e.message}\``),
+        }),
+      ),
+    ),
+    Match.when({ method: "stored" }, () =>
+      deleteCredentials(profileName, "aws").pipe(
+        Effect.andThen(Clank.success("AWS: stored credentials removed")),
+      ),
+    ),
+    Match.exhaustive,
+  );
+
+const login = (profileName: string, config: AwsAuthConfig) =>
+  Match.value(config)
+    .pipe(
+      Match.when({ method: "env" }, () => Effect.void),
+      Match.when({ method: "sso" }, (config) =>
+        DistilledAuth.loadProfileCredentials(config.ssoProfile).pipe(
+          Effect.matchEffect({
+            onSuccess: () =>
+              Clank.info(
+                `AWS: SSO profile '${config.ssoProfile}' already has valid credentials`,
+              ),
+            onFailure: () => loginSSO(config),
+          }),
+        ),
+      ),
+      Match.when({ method: "stored" }, () =>
+        readCredentials<AwsStoredCredentials>(profileName, "aws").pipe(
+          Effect.flatMap((creds) =>
+            creds == null ? loginStored(profileName) : Effect.void,
+          ),
+        ),
+      ),
+      Match.exhaustive,
+    )
+    .pipe(
+      Effect.mapError(
+        (e) => new AuthError({ message: "login failed", cause: e }),
+      ),
+    );
+
+const configureCredentials = (profileName: string) =>
+  Clank.select({
+    message: "AWS authentication method",
+    options,
+  })
+    .pipe(
+      Effect.flatMap((method) =>
+        Match.value(method).pipe(
+          Match.when("env", () => Effect.succeed({ method: "env" as const })),
+          Match.when("sso", () =>
+            Effect.gen(function* () {
+              const ssoProfile = yield* Clank.text({
+                message: "AWS profile name (from ~/.aws/config)",
+                placeholder: "default",
+                defaultValue: "default",
+              });
+
+              const config = {
+                method: "sso" as const,
+                ssoProfile: ssoProfile ?? "default",
+              };
+
+              yield* loginSSO(config);
+
+              return config;
+            }),
+          ),
+          Match.when("stored", () => loginStored(profileName)),
+          Match.exhaustive,
+        ),
+      ),
+    )
+    .pipe(
+      Effect.mapError(
+        (e) =>
+          new AuthError({
+            message: "failed to configure credentials",
+            cause: e,
+          }),
+      ),
+    );
+
+const loginSSO = (config: Extract<AwsAuthConfig, { method: "sso" }>) =>
+  Clank.info(
+    `AWS SSO: running 'aws sso login --profile ${config.ssoProfile}'...`,
+  ).pipe(
+    Effect.andThen(runSsoCommand("login", config.ssoProfile)),
+    Effect.matchEffect({
+      onSuccess: () => Clank.success("AWS SSO: login complete"),
+      onFailure: (e) => Clank.warn(`AWS SSO: login faield: \`${e.message}\``),
+    }),
+  );
+
+const loginStored = Effect.fnUntraced(function* (profileName: string) {
+  const accessKeyId = yield* Clank.text({
+    message: "AWS Access Key ID",
+    validate: (v) => (v.length === 0 ? "Required" : undefined),
+  }).pipe(retryOnce);
+
+  const secretAccessKey = yield* Clank.password({
+    message: "AWS Secret Access Key",
+    validate: (v) => (v.length === 0 ? "Required" : undefined),
+  }).pipe(retryOnce);
+
+  const sessionToken = yield* Clank.text({
+    message: "AWS Session Token (optional — press Enter or Esc to skip)",
+    placeholder: "(none)",
+  }).pipe(Effect.catch(() => Effect.succeed("")));
+
+  const region = yield* Clank.text({
+    message: "AWS Region",
+    placeholder: "us-east-1",
+    defaultValue: "us-east-1",
+  }).pipe(retryOnce);
+
+  yield* writeCredentials<AwsStoredCredentials>(profileName, "aws", {
+    accessKeyId,
+    secretAccessKey,
+    sessionToken,
+    region,
+  });
+  yield* Clank.success("AWS credentials saved.");
+
+  return { method: "stored" as const };
+});

package/src/AWS/Credentials.ts

@@ -7,7 +7,6 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import { Profile } from "./Profile.ts";
-
 import { StageConfig } from "./StageConfig.ts";
 
 export { Credentials } from "@distilled.cloud/aws/Credentials";

package/src/AWS/DynamoDB/Table.ts

@@ -115,7 +115,9 @@ export interface Table extends Resource<
  * @section Creating Tables
  * @example Basic Table
  * ```typescript
- * const table = yield* Table("UsersTable", {
+ * import * as DynamoDB from "alchemy/AWS/DynamoDB";
+ *
+ * const table = yield* DynamoDB.Table("UsersTable", {
  *   partitionKey: "pk",
  *   attributes: {
  *     pk: "S",
@@ -125,7 +127,7 @@ export interface Table extends Resource<
  *
  * @example Table with Sort Key and TTL
  * ```typescript
- * const table = yield* Table("SessionsTable", {
+ * const table = yield* DynamoDB.Table("SessionsTable", {
  *   partitionKey: "userId",
  *   sortKey: "sessionId",
  *   attributes: {
@@ -140,18 +142,69 @@ export interface Table extends Resource<
  * });
  * ```
  *
- * @section Runtime Operations
- * @example Read an Item
+ * @example Table with Global Secondary Index
  * ```typescript
- * const getItem = yield* GetItem.bind(table);
- *
- * const response = yield* getItem({
- *   Key: {
- *     pk: { S: "user#123" },
+ * const table = yield* DynamoDB.Table("OrdersTable", {
+ *   partitionKey: "pk",
+ *   sortKey: "sk",
+ *   attributes: {
+ *     pk: "S",
+ *     sk: "S",
+ *     gsi1pk: "S",
+ *     gsi1sk: "S",
  *   },
- *   ConsistentRead: true,
+ *   globalSecondaryIndexes: [{
+ *     IndexName: "GSI1",
+ *     KeySchema: [
+ *       { AttributeName: "gsi1pk", KeyType: "HASH" },
+ *       { AttributeName: "gsi1sk", KeyType: "RANGE" },
+ *     ],
+ *     Projection: { ProjectionType: "ALL" },
+ *   }],
  * });
  * ```
+ *
+ * @section Runtime Operations
+ * Bind DynamoDB operations in the init phase and use them in runtime
+ * handlers. Bindings inject the table name and grant scoped IAM
+ * permissions automatically.
+ *
+ * @example Read and write items
+ * ```typescript
+ * // init
+ * const getItem = yield* DynamoDB.GetItem.bind(table);
+ * const putItem = yield* DynamoDB.PutItem.bind(table);
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     // runtime
+ *     yield* putItem({
+ *       Item: { pk: { S: "user#123" }, name: { S: "Alice" } },
+ *     });
+ *     const result = yield* getItem({
+ *       Key: { pk: { S: "user#123" } },
+ *     });
+ *     return yield* HttpServerResponse.json(result.Item);
+ *   }),
+ * };
+ * ```
+ *
+ * @section DynamoDB Streams
+ * Process change data capture events from a DynamoDB table using a
+ * Lambda event source mapping. The stream is enabled automatically
+ * through the binding contract.
+ *
+ * @example Process table changes
+ * ```typescript
+ * // init
+ * yield* DynamoDB.streams(table, {
+ *   StreamViewType: "NEW_AND_OLD_IMAGES",
+ * }).process(
+ *   Effect.fn(function* (record) {
+ *     yield* Effect.log(`${record.eventName}: ${JSON.stringify(record.dynamodb)}`);
+ *   }),
+ * );
+ * ```
  */
 export const Table = Resource<Table>("AWS.DynamoDB.Table");
 

package/src/AWS/EC2/VpcEndpoint.ts

@@ -9,10 +9,10 @@ import type { ScopedPlanStatusSession } from "../../Cli/Cli.ts";
 import { isResolved } from "../../Diff.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
-import type { Providers } from "../Providers.ts";
 import { createInternalTags, createTagsList, diffTags } from "../../Tags.ts";
 import type { AccountID } from "../Account.ts";
 import { Account } from "../Account.ts";
+import type { Providers } from "../Providers.ts";
 import type { RegionID } from "../Region.ts";
 import type { RouteTableId } from "./RouteTable.ts";
 import type { SecurityGroupId } from "./SecurityGroup.ts";
@@ -595,11 +595,11 @@ const waitForVpcEndpointAvailable = (
       return yield* new VpcEndpointNotFound({ vpcEndpointId });
     }
 
-    if (ep.State === "Available") {
+    if (ep.State === "available") {
       return ep;
     }
 
-    if (ep.State === "Failed" || ep.State === "Rejected") {
+    if (ep.State === "failed" || ep.State === "rejected") {
       return yield* new VpcEndpointFailed({
         vpcEndpointId,
         errorCode: ep.LastError?.Code,
@@ -641,7 +641,7 @@ const waitForVpcEndpointDeleted = (
 
     const ep = result.VpcEndpoints?.[0];
 
-    if (!ep || ep.State === "Deleted") {
+    if (!ep || ep.State === "deleted") {
       return; // Successfully deleted
     }
 

package/src/AWS/EC2/hosted.ts

@@ -223,7 +223,7 @@ export const createEc2HostedSupport = ({
           virtualEntryPlugin(
             (importPath) => `
 import { NodeServices } from "@effect/platform-node";
-import { Stack } from "alchemy-effect/Stack";
+import { Stack } from "alchemy/Stack";
 import * as Config from "effect/Config";
 import * as ConfigProvider from "effect/ConfigProvider";
 import * as Credentials from "@distilled.cloud/aws/Credentials";

package/src/AWS/ECS/Task.ts

@@ -486,7 +486,7 @@ export const TaskProvider = () =>
               virtualEntryPlugin(
                 (importPath) => `
 import { NodeServices } from "@effect/platform-node";
-import { Stack } from "alchemy-effect/Stack";
+import { Stack } from "alchemy/Stack";
 import * as Config from "effect/Config";
 import * as ConfigProvider from "effect/ConfigProvider";
 import * as Credentials from "@distilled.cloud/aws/Credentials";

package/src/AWS/Kinesis/Stream.ts

@@ -170,32 +170,68 @@ export interface Stream extends Resource<
  *
  * `Stream` owns the stream's lifecycle and mutable control-plane configuration,
  * including retention, encryption, monitoring, warm throughput, record size, tags,
- * and stream resource policy.
+ * and stream resource policy. A stream name is auto-generated from the app,
+ * stage, and logical ID unless you provide one explicitly.
  *
  * @section Creating Streams
  * @example On-Demand Stream
  * ```typescript
- * const stream = yield* Stream("OrdersStream");
+ * import * as Kinesis from "alchemy/AWS/Kinesis";
+ *
+ * const stream = yield* Kinesis.Stream("OrdersStream");
  * ```
  *
  * @example Provisioned Stream
  * ```typescript
- * const stream = yield* Stream("AnalyticsStream", {
+ * const stream = yield* Kinesis.Stream("AnalyticsStream", {
  *   streamMode: "PROVISIONED",
  *   shardCount: 2,
  *   retentionPeriodHours: 48,
  * });
  * ```
  *
+ * @example Encrypted Stream
+ * ```typescript
+ * const stream = yield* Kinesis.Stream("SecureStream", {
+ *   encryption: true,
+ *   kmsKeyId: "alias/my-key",
+ * });
+ * ```
+ *
  * @section Runtime Producers
- * @example Put a Record
+ * Bind producer operations in the init phase and use them in runtime
+ * handlers.
+ *
+ * @example Put a record from a handler
  * ```typescript
+ * // init
  * const putRecord = yield* Kinesis.PutRecord.bind(stream);
  *
- * yield* putRecord({
- *   PartitionKey: "order-123",
- *   Data: new TextEncoder().encode(JSON.stringify({ orderId: "123" })),
- * });
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     // runtime
+ *     yield* putRecord({
+ *       PartitionKey: "order-123",
+ *       Data: new TextEncoder().encode(JSON.stringify({ orderId: "123" })),
+ *     });
+ *     return HttpServerResponse.text("Sent");
+ *   }),
+ * };
+ * ```
+ *
+ * @section Event Sources
+ * Process records from a Kinesis stream using a Lambda event source
+ * mapping.
+ *
+ * @example Process stream records
+ * ```typescript
+ * // init
+ * yield* Kinesis.records(stream).process(
+ *   Effect.fn(function* (record) {
+ *     const data = new TextDecoder().decode(record.data);
+ *     yield* Effect.log(`Received: ${data}`);
+ *   }),
+ * );
  * ```
  */
 export const Stream = Resource<Stream>("AWS.Kinesis.Stream");