@alchemy.run/fly 2.0.0-beta.84 → 2.0.0-beta.86

package/src/Secret.ts

@@ -54,9 +54,21 @@ export type Secret = Resource<
     updatedAt: string | undefined;
   },
   never,
-  Providers
+  Providers,
+  SecretLookup
 >;
 
+/**
+ * Props for {@link Secret.lookup}: find a secret this stack doesn't
+ * manage by its App and name.
+ */
+export interface SecretLookup {
+  /** Fly App name the secret belongs to. */
+  appName: string;
+  /** Secret name (case-sensitive). */
+  name: string;
+}
+
 const resolveSecretProps = (
   props: SecretProps | Effect.Effect<SecretProps, never, Providers>,
 ): Effect.Effect<SecretProps, never, Providers> =>
@@ -196,6 +208,17 @@ const SecretResource = Resource<Secret>("Fly.Secret");
  * );
  * ```
  *
+ * ### Looking up an existing secret
+ * `Secret.lookup` references a secret Alchemy doesn't manage (set with
+ * `fly secrets set` or by another stack). It is read during plan/deploy,
+ * never set or unset. Its value is never read; `digest` changes when the
+ * value does.
+ *
+ * **Example:** Reference an existing secret
+ * ```typescript
+ * const token = Fly.Secret.lookup({ appName: "my-site", name: "API_TOKEN" });
+ * ```
+ *
  * @resource
  * @product Secret
  */
@@ -207,7 +230,7 @@ export const Secret: typeof SecretResource = Object.assign(
 
 export class SecretNotCreated extends Data.TaggedError("Fly.SecretNotCreated")<{
   appName: string;
-  name: string;
+  secretName: string;
 }> {}
 
 export class SecretAppRequired extends Data.TaggedError("Fly.SecretAppRequired")<{
@@ -251,7 +274,7 @@ const getByName = (appName: string, secretName: string) =>
       secret_name: secretName,
       show_secrets: false,
     })
-    .pipe(Effect.catchTag("NotFound", () => Effect.succeed(undefined)));
+    .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
 
 const listSecrets = (appName: string) =>
   machines
@@ -295,6 +318,11 @@ export const SecretProvider = () =>
       return undefined;
     }),
 
+    lookup: Effect.fn(function* ({ appName, name }) {
+      const found = yield* getByName(appName, name);
+      return found === undefined ? undefined : toAttrs(appName, found, name);
+    }),
+
     read: Effect.fn(function* ({ id, olds, output }) {
       const appName = output?.appName ?? (olds !== undefined ? appNameOf(olds.app) : undefined);
       if (appName === undefined) return undefined;
@@ -360,7 +388,7 @@ export const SecretProvider = () =>
       }
 
       if (current === undefined) {
-        return yield* new SecretNotCreated({ appName, name });
+        return yield* new SecretNotCreated({ appName, secretName: name });
       }
 
       // Sync — skip if we just created. Prefer observed digest vs hash of

package/src/SecretKey.ts

@@ -64,9 +64,21 @@ export type SecretKey = Resource<
     updatedAt: string | undefined;
   },
   never,
-  Providers
+  Providers,
+  SecretKeyLookup
 >;
 
+/**
+ * Props for {@link SecretKey.lookup}: find a secret key this stack
+ * doesn't manage by its App and name.
+ */
+export interface SecretKeyLookup {
+  /** Fly App name the key belongs to. */
+  appName: string;
+  /** Secret key name. */
+  name: string;
+}
+
 const resolveSecretKeyProps = (
   props: SecretKeyProps | Effect.Effect<SecretKeyProps, never, Providers>,
 ): Effect.Effect<SecretKeyProps, never, Providers> =>
@@ -173,6 +185,17 @@ const SecretKeyResource = Resource<SecretKey>("Fly.SecretKey");
  * const { valid } = yield* verify({ plaintext, signature });
  * ```
  *
+ * ### Looking up an existing key
+ * `SecretKey.lookup` references a key Alchemy doesn't manage (created with
+ * `fly secrets keys` or by another stack). It is read during plan/deploy,
+ * never generated or deleted. Bind it like a declared key.
+ *
+ * **Example:** Verify with an existing key
+ * ```typescript
+ * const Signing = Fly.SecretKey.lookup({ appName: "my-site", name: "signing" });
+ * const verify = yield* Fly.Verify(Signing);
+ * ```
+ *
  * @resource
  * @product Secret Key
  */
@@ -184,7 +207,7 @@ export const SecretKey: typeof SecretKeyResource = Object.assign(
 
 export class SecretKeyNotCreated extends Data.TaggedError("Fly.SecretKeyNotCreated")<{
   appName: string;
-  name: string;
+  secretName: string;
 }> {}
 
 export class SecretKeyAppRequired extends Data.TaggedError("Fly.SecretKeyAppRequired")<{
@@ -223,7 +246,7 @@ const getByName = (appName: string, secretName: string) =>
       app_name: appName,
       secret_name: secretName,
     })
-    .pipe(Effect.catchTag("NotFound", () => Effect.succeed(undefined)));
+    .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
 
 const listKeys = (appName: string) =>
   machines.listSecretKeys({ app_name: appName }).pipe(
@@ -285,6 +308,11 @@ export const SecretKeyProvider = () =>
       return undefined;
     }),
 
+    lookup: Effect.fn(function* ({ appName, name }) {
+      const found = yield* getByName(appName, name);
+      return found === undefined ? undefined : toAttrs(appName, found, name);
+    }),
+
     read: Effect.fn(function* ({ id, olds, output }) {
       const appName = output?.appName ?? (olds !== undefined ? appNameOf(olds.app) : undefined);
       if (appName === undefined) return undefined;
@@ -346,7 +374,7 @@ export const SecretKeyProvider = () =>
       }
 
       if (current === undefined) {
-        return yield* new SecretKeyNotCreated({ appName, name });
+        return yield* new SecretKeyNotCreated({ appName, secretName: name });
       }
 
       // Sync — re-set when the caller supplied new material. Observed