@alchemy.run/boat 0.0.0 → 2.0.0-beta.87

package/src/Environment.ts

@@ -0,0 +1,416 @@
+import * as boat from "@distilled.cloud/boat-dev/boat";
+import { Unowned } from "alchemy/AdoptPolicy";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { BoatUnexpectedResponse, InvalidEnvironmentValue } from "./Errors.ts";
+import { declarable } from "./internal/Declared.ts";
+import { inOrg, sameOrg, stackOrg } from "./internal/Org.ts";
+import { boatName, isGeneratedName } from "./internal/Ownership.ts";
+import type { Providers } from "./Providers.ts";
+
+/** A file written into every sandbox on the environment. */
+export interface EnvironmentSecretFile {
+  /** Where it goes, under the home directory: `.npmrc`, `~/.npmrc` or `/home/user/.npmrc`. */
+  path: string;
+  contents: string | Redacted.Redacted<string>;
+}
+
+/** A credential profile, by id. Accepts a `Boat.CredentialProfile`. */
+export interface EnvironmentCredentialProfileRef {
+  credentialProfileId: string;
+}
+
+/** An AI credentials proxy switch. Accepts a `Boat.AiProxy`. */
+export interface EnvironmentAiProxyRef {
+  enabled: boolean;
+}
+
+export interface EnvironmentProps {
+  /**
+   * Environment name: letters, digits, `.`, `-` and `_`, up to 64. If
+   * omitted, a unique name is generated from the stack, stage and logical
+   * ID. Renamed in place.
+   */
+  name?: string;
+  /**
+   * Environment variables every sandbox on it gets. Updated in place;
+   * running sandboxes keep the version they started with. A value can't
+   * hold a newline, or both `'` and `"`.
+   */
+  env?: Record<string, string | Redacted.Redacted<string>>;
+  /** Files written into every sandbox on it. Updated in place. */
+  secretFiles?: EnvironmentSecretFile[];
+  /**
+   * Pass nothing to sandboxes: no repositories, secrets or credentials,
+   * whatever the flags below say. For sandboxes you give to third parties.
+   * @default false
+   */
+  safeForThirdParties?: boolean;
+  /**
+   * Attach `env` and `secretFiles`.
+   * @default true
+   */
+  passSecrets?: boolean;
+  /**
+   * Attach your GitHub token, the repositories selected on the dashboard,
+   * and their setup scripts. A sandbox with it can push as you.
+   * @default false
+   */
+  passGithub?: boolean;
+  /**
+   * Attach a Boat API key, so a sandbox can snapshot, stop and resume
+   * itself.
+   * @default false
+   */
+  passSandboxCredentials?: boolean;
+  /**
+   * Attach the keys and sign-ins of `credentialProfile`, or of the sandbox
+   * owner's default profile when there is none.
+   * @default true with a `credentialProfile`, else false
+   */
+  passAgentsCredentials?: boolean;
+  /**
+   * The `Boat.CredentialProfile` whose keys the sandboxes get (or
+   * `{ credentialProfileId }` of one). Omit for the sandbox owner's default
+   * profile.
+   */
+  credentialProfile?: EnvironmentCredentialProfileRef;
+  /**
+   * With `safeForThirdParties`, still give sandboxes the credential
+   * profile, as placeholders the AI credentials proxy swaps for the real
+   * keys. Real keys never enter them. Boat rejects it while the proxy is
+   * off for the profile's owner, so pass the `Boat.AiProxy` that turns it
+   * on: the environment then waits for it, and proxies only while it is on.
+   * @default false
+   */
+  proxyAiCredentials?: boolean | EnvironmentAiProxyRef;
+  /**
+   * Make it the account's default: sandboxes created without an
+   * `environment` use it.
+   * @default false
+   */
+  isDefault?: boolean;
+}
+
+export interface EnvironmentAttributes {
+  /** Boat's environment id. */
+  environmentId: string;
+  name: string;
+  /** Each change mints a version; new sandboxes start on the latest. */
+  latestVersionNumber: number;
+  isDefault: boolean;
+  /**
+   * The organization whose shared environment this is, as the stack's
+   * `org` named it; `undefined` for a personal environment.
+   */
+  org: string | undefined;
+}
+
+export interface Environment extends Resource<
+  "Boat.Environment",
+  EnvironmentProps,
+  EnvironmentAttributes,
+  never,
+  Providers,
+  { name: string }
+> {}
+
+/**
+ * A Boat environment: the environment variables, secret files and
+ * credential settings a sandbox starts with.
+ *
+ * Every change mints a new version. New sandboxes start on the latest
+ * version; running ones keep the version they started with until they are
+ * upgraded on the dashboard.
+ *
+ * An environment is personal, or shared by an organization. With an `org`
+ * on the stack (`Boat.providers({ org })`, or the profile's), it is that
+ * organization's: every member can use it, and owners and admins change
+ * it. Without one it is yours alone, even when your active wallet is an
+ * organization's. Changing the stack's `org` replaces it.
+ *
+ * An environment passes a sandbox its own `env` and `secretFiles`, and
+ * nothing of your account. Your GitHub token, a Boat API key and your AI
+ * credentials are each one flag, off until you turn it on.
+ *
+ * ### Creating an environment
+ * **Example:** Variables and a secret file
+ * ```typescript
+ * export const MyEnv = Boat.Environment("MyEnv", {
+ *   env: { NODE_ENV: "production", API_TOKEN: Config.Redacted("API_TOKEN") },
+ *   secretFiles: [{ path: ".npmrc", contents: Config.Redacted("NPMRC") }],
+ * });
+ *
+ * export const Box = Boat.Sandbox("Box", { environment: MyEnv });
+ * ```
+ *
+ * **Example:** An environment for sandboxes you hand to users
+ * ```typescript
+ * export const Tenants = Boat.Environment("Tenants", { safeForThirdParties: true });
+ * ```
+ *
+ * ### Passing account credentials
+ * **Example:** Let sandboxes push to GitHub as you, and manage themselves
+ * ```typescript
+ * export const Mine = Boat.Environment("Mine", {
+ *   passGithub: true,
+ *   passSandboxCredentials: true,
+ * });
+ * ```
+ *
+ * ### Giving sandboxes AI credentials
+ * **Example:** The keys of a credential profile
+ * ```typescript
+ * export const MyProfile = Boat.CredentialProfile("MyProfile", {
+ *   anthropic: Config.Redacted("ANTHROPIC_API_KEY"),
+ * });
+ *
+ * export const MyEnv = Boat.Environment("MyEnv", { credentialProfile: MyProfile });
+ * ```
+ *
+ * **Example:** The sign-ins you made on the dashboard
+ * ```typescript
+ * export const MyEnv = Boat.Environment("MyEnv", {
+ *   credentialProfile: Boat.CredentialProfile.lookup({ name: "default" }),
+ * });
+ * ```
+ *
+ * **Example:** Placeholders, for sandboxes you hand to users
+ * ```typescript
+ * export const MyProfile = Boat.CredentialProfile("MyProfile", {
+ *   anthropic: Config.Redacted("ANTHROPIC_API_KEY"),
+ * });
+ *
+ * // Billed: $1 a day, plus $1 per 1,000 proxied requests.
+ * export const Proxy = Boat.AiProxy("Proxy", { enabled: true });
+ *
+ * export const Tenants = Boat.Environment("Tenants", {
+ *   safeForThirdParties: true,
+ *   credentialProfile: MyProfile,
+ *   proxyAiCredentials: Proxy,
+ * });
+ * ```
+ *
+ * ### Sharing with an organization
+ * **Example:** An environment the whole team uses
+ * ```typescript
+ * // alchemy.run.ts
+ * export default Alchemy.Stack(
+ *   "Team",
+ *   { providers: Boat.providers({ org: "acme" }) },
+ *   Effect.gen(function* () {
+ *     const env = yield* Boat.Environment("MyEnv", { env: { MODE: "agent" } });
+ *     return { environment: env.name };
+ *   }),
+ * );
+ * ```
+ *
+ * ### Referencing an environment the stack doesn't manage
+ * **Example:** Look one up by name
+ * ```typescript
+ * export const Box = Boat.Sandbox("Box", {
+ *   environment: Boat.Environment.lookup({ name: "base" }),
+ * });
+ * ```
+ *
+ * @resource
+ * @product Environment
+ */
+export const Environment = declarable<Environment>()(Resource<Environment>("Boat.Environment"));
+
+const reveal = (value: string | Redacted.Redacted<string>) =>
+  Redacted.isRedacted(value) ? Redacted.value(value) : value;
+
+/**
+ * One `KEY=value` line as Boat reads it: single quotes keep a value
+ * verbatim; double quotes are stripped without escapes. A value holding a
+ * newline, or both kinds of quote, has no form Boat reads back intact.
+ */
+const envLine = (key: string, value: string) =>
+  /^[A-Za-z0-9_./:@+,=%-]*$/.test(value)
+    ? Effect.succeed(`${key}=${value}`)
+    : value.includes("\n") || (value.includes("'") && value.includes('"'))
+      ? Effect.fail(
+          new InvalidEnvironmentValue({
+            key,
+            message: `Boat can't hold environment variable ${key}: its value has a newline, or both ' and "`,
+          }),
+        )
+      : Effect.succeed(value.includes("'") ? `${key}="${value}"` : `${key}='${value}'`);
+
+const envContentsOf = (env: EnvironmentProps["env"]) =>
+  Effect.map(
+    Effect.forEach(Object.entries(env ?? {}), ([key, value]) => envLine(key, reveal(value))),
+    (lines) => lines.join("\n"),
+  );
+
+/** Boat writes secret files relative to the home directory and doesn't expand `~`. */
+const relativePath = (path: string) => path.replace(/^~\//, "").replace(/^\/home\/user\//, "");
+
+const secretFilesOf = (files: EnvironmentProps["secretFiles"]) =>
+  (files ?? []).map((file) => ({
+    path: relativePath(file.path),
+    contents: reveal(file.contents),
+  }));
+
+const listEnvironments = Effect.fn(function* (org: string | undefined) {
+  const { environments } = yield* boat.listEnvironments(inOrg(org));
+  return environments;
+});
+
+const findEnvironment = Effect.fn(function* (
+  org: string | undefined,
+  match: { environmentId?: string; name: string },
+) {
+  const environments = yield* listEnvironments(org);
+  return (
+    environments.find((environment) => environment.id === match.environmentId) ??
+    environments.find((environment) => environment.name === match.name)
+  );
+});
+
+const toAttributes = (
+  environment: boat.SandboxEnvironment,
+  org: string | undefined,
+): EnvironmentAttributes => ({
+  environmentId: environment.id,
+  name: environment.name,
+  latestVersionNumber: environment.latestVersionNumber ?? 0,
+  isDefault: environment.isDefault,
+  org,
+});
+
+/**
+ * What the props set, as the fields `updateEnvironment` takes. Nothing of
+ * the account is passed unless a prop asks for it: Boat's own defaults pass
+ * everything.
+ */
+const desiredOf = (name: string, news: EnvironmentProps, envContents: string) => ({
+  name,
+  envContents,
+  secretFiles: secretFilesOf(news.secretFiles),
+  safeForThirdParties: news.safeForThirdParties ?? false,
+  passSecrets: news.passSecrets ?? true,
+  passGithub: news.passGithub ?? false,
+  passSandboxCredentials: news.passSandboxCredentials ?? false,
+  passAgentsCredentials: news.passAgentsCredentials ?? news.credentialProfile !== undefined,
+  proxyAiCredentials:
+    typeof news.proxyAiCredentials === "object"
+      ? news.proxyAiCredentials.enabled
+      : (news.proxyAiCredentials ?? false),
+  credentialProfileId: news.credentialProfile?.credentialProfileId ?? null,
+});
+
+const sortedFiles = (files: ReadonlyArray<{ path: string; contents: string }>) =>
+  JSON.stringify([...files].sort((a, b) => a.path.localeCompare(b.path)));
+
+export const EnvironmentProvider = () =>
+  Provider.effect(
+    Environment,
+    Effect.gen(function* () {
+      return {
+        stables: ["environmentId", "org"],
+        // An environment belongs to one organization (or to you) for life.
+        diff: Effect.fn(function* ({ output }) {
+          if (output !== undefined && !sameOrg(output.org, yield* stackOrg)) {
+            return { action: "replace" } as const;
+          }
+        }),
+        read: Effect.fn(function* ({ id, olds, output }) {
+          const name = output?.name ?? (yield* boatName(id, olds?.name, 64));
+          const org = output ? output.org : yield* stackOrg;
+          const environment = yield* findEnvironment(org, {
+            environmentId: output?.environmentId,
+            name,
+          });
+          if (environment === undefined) return undefined;
+          const attrs = toAttributes(environment, org);
+          return output !== undefined || isGeneratedName(environment.name) ? attrs : Unowned(attrs);
+        }),
+        lookup: Effect.fn(function* ({ name }) {
+          const org = yield* stackOrg;
+          const environment = yield* findEnvironment(org, { name });
+          return environment === undefined ? undefined : toAttributes(environment, org);
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const name = yield* boatName(id, news.name ?? output?.name, 64);
+          // A different org replaces (see diff), so this is the org it lives in.
+          const org = yield* stackOrg;
+
+          // Observe — by id once we have one (it survives renames), else by name.
+          let environment = yield* findEnvironment(org, {
+            environmentId: output?.environmentId,
+            name,
+          });
+
+          // Ensure — a concurrent create of the same name is a race, not a failure.
+          if (environment === undefined) {
+            yield* session.note(`Creating environment ${name}...`);
+            const created = yield* boat
+              .createEnvironment({ name, ...inOrg(org) })
+              .pipe(Effect.catchTag("Conflict", () => Effect.succeed(undefined)));
+            environment =
+              created?.environments.find((candidate) => candidate.name === name) ??
+              (yield* findEnvironment(org, { name }));
+            if (environment === undefined) {
+              return yield* new BoatUnexpectedResponse({
+                message: `Boat environment ${name} vanished after create`,
+              });
+            }
+          }
+
+          // Sync — each update mints a version, so send only what differs.
+          const desired = desiredOf(name, news, yield* envContentsOf(news.env));
+          const delta: Partial<typeof desired> = {};
+          if (environment.name !== desired.name) delta.name = desired.name;
+          if (environment.envContents.trim() !== desired.envContents.trim()) {
+            delta.envContents = desired.envContents;
+          }
+          if (sortedFiles(environment.secretFiles) !== sortedFiles(desired.secretFiles)) {
+            delta.secretFiles = desired.secretFiles;
+          }
+          for (const flag of [
+            "safeForThirdParties",
+            "passGithub",
+            "passSecrets",
+            "passSandboxCredentials",
+            "passAgentsCredentials",
+          ] as const) {
+            if (environment[flag] !== desired[flag]) delta[flag] = desired[flag];
+          }
+          if ((environment.proxyAiCredentials ?? false) !== desired.proxyAiCredentials) {
+            delta.proxyAiCredentials = desired.proxyAiCredentials;
+          }
+          if ((environment.credentialProfileId ?? null) !== desired.credentialProfileId) {
+            delta.credentialProfileId = desired.credentialProfileId;
+          }
+          const makeDefault = news.isDefault === true && !environment.isDefault;
+          if (Object.keys(delta).length > 0 || makeDefault) {
+            yield* session.note(`Updating environment ${name}...`);
+            const updated = yield* boat.updateEnvironment({
+              environmentId: environment.id,
+              ...inOrg(org),
+              ...delta,
+              ...(makeDefault ? { isDefault: true } : {}),
+            });
+            environment = updated.environment ?? environment;
+          }
+
+          return toAttributes(environment, org);
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* boat
+            .deleteEnvironment({ environmentId: output.environmentId, ...inOrg(output.org) })
+            .pipe(Effect.catchTag("NotFound", () => Effect.void));
+        }),
+        list: Effect.fn(function* () {
+          const org = yield* stackOrg;
+          return (yield* listEnvironments(org))
+            .filter((environment) => isGeneratedName(environment.name))
+            .map((environment) => toAttributes(environment, org));
+        }),
+      };
+    }),
+  );

package/src/Errors.ts

@@ -0,0 +1,34 @@
+import * as Data from "effect/Data";
+
+/** Boat answered with something Alchemy can't use (a missing field, a vanished object). */
+export class BoatUnexpectedResponse extends Data.TaggedError("Boat.UnexpectedResponse")<{
+  readonly message: string;
+}> {}
+
+/** A command ran past its `timeout` and Boat stopped it. */
+export class ExecTimedOut extends Data.TaggedError("Boat.ExecTimedOut")<{
+  readonly message: string;
+  readonly stdout: string;
+  readonly stderr: string;
+}> {}
+
+/** A saved snapshot Boat could not save. */
+export class SnapshotFailed extends Data.TaggedError("Boat.SnapshotFailed")<{
+  readonly message: string;
+  /** The snapshot's name, or the sandbox whose setup it waited on. */
+  readonly snapshot: string;
+}> {}
+
+/** An environment variable value Boat's `.env` format can't hold. */
+export class InvalidEnvironmentValue extends Data.TaggedError("Boat.InvalidEnvironmentValue")<{
+  readonly message: string;
+  readonly key: string;
+}> {}
+
+/** A snapshot's setup command failed or ran past 10 minutes. */
+export class SnapshotSetupFailed extends Data.TaggedError("Boat.SnapshotSetupFailed")<{
+  readonly message: string;
+  readonly command: string;
+  readonly exitCode: number;
+  readonly stderr: string;
+}> {}

package/src/Providers.ts

@@ -0,0 +1,71 @@
+import { CredentialsStoreLive } from "alchemy/Auth/Credentials";
+import { ProfileStoreLive } from "alchemy/Auth/Profile";
+import * as Provider from "alchemy/Provider";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import { AiProxy, AiProxyProvider } from "./AiProxy.ts";
+import { ApiKey, ApiKeyProvider } from "./ApiKey.ts";
+import { BoatAuth } from "./AuthProvider.ts";
+import { CredentialProfile, CredentialProfileProvider } from "./CredentialProfile.ts";
+import * as Credentials from "./Credentials.ts";
+import { Environment, EnvironmentProvider } from "./Environment.ts";
+import { Sandbox, SandboxProvider } from "./Sandbox.ts";
+import { Snapshot, SnapshotProvider } from "./Snapshot.ts";
+import { Webhook, WebhookProvider } from "./Webhook.ts";
+
+/**
+ * Service tag bundling all Boat providers + auth + credentials. Use
+ * `Boat.providers()` to materialize the full layer.
+ */
+export class Providers extends Provider.ProviderCollection<Providers>()("Boat") {}
+
+export type ProviderRequirements = Layer.Services<ReturnType<typeof providers>>;
+
+/**
+ * Build the complete Boat providers Layer: every Boat resource, the Boat
+ * AuthProvider registration (so `alchemy profile edit` can configure it),
+ * and credential resolution.
+ *
+ * `org` picks the organization (wallet) the stack's resources bill and the
+ * one whose shared environments `Boat.Environment` manages: an org id
+ * (`team_…`), an org name, or `personal`. It overrides the profile's `org`
+ * (or `BOAT_ORG`); with neither, Boat uses the account's active wallet and
+ * environments are your personal ones.
+ *
+ * @example
+ * ```ts
+ * Alchemy.Stack("App", { providers: Boat.providers() }, ...)
+ * Alchemy.Stack("App", { providers: Boat.providers({ org: "team_abc" }) }, ...)
+ * ```
+ */
+export const providers = (options?: { readonly org?: string }) =>
+  Layer.effect(
+    Providers,
+    Provider.collection([
+      AiProxy,
+      ApiKey,
+      CredentialProfile,
+      Environment,
+      Sandbox,
+      Snapshot,
+      Webhook,
+    ]),
+  ).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        AiProxyProvider(),
+        ApiKeyProvider(),
+        CredentialProfileProvider(),
+        EnvironmentProvider(),
+        SandboxProvider(),
+        SnapshotProvider(),
+        WebhookProvider(),
+      ),
+    ),
+    Layer.provideMerge(Credentials.fromAuthProvider(options)),
+    Layer.provideMerge(FetchHttpClient.layer),
+    Layer.provideMerge(BoatAuth),
+    Layer.provideMerge(ProfileStoreLive),
+    Layer.provideMerge(CredentialsStoreLive),
+    Layer.orDie,
+  );