alchemy 2.0.0-beta.76 → 2.0.0-beta.77

package/src/Alchemist/routes/cloudflare.ts

@@ -0,0 +1,188 @@
+import * as workers from "@distilled.cloud/cloudflare/workers";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
+import { AuthProviders } from "../../Auth/AuthProvider.ts";
+import { resolveProfileName, withProfileOverride } from "../../Auth/Resolve.ts";
+import * as CloudflareAccess from "../../Cloudflare/Access.ts";
+import { CloudflareAuth } from "../../Cloudflare/Auth/AuthProvider.ts";
+import * as CloudflareEnvironment from "../../Cloudflare/CloudflareEnvironment.ts";
+import * as CloudflareCredentials from "../../Cloudflare/Credentials.ts";
+import { CloudflareLogs } from "../../Cloudflare/Logs.ts";
+import { STATE_STORE_SCRIPT_NAME } from "../../Cloudflare/StateStore/Api.ts";
+import {
+  bootstrap as bootstrapStateStore,
+  teardownStateStore,
+} from "../../Cloudflare/StateStore/State.ts";
+import { loadConfigProvider } from "../../Util/ConfigProvider.ts";
+import { fileLogger } from "../../Util/FileLogger.ts";
+import type { Target } from "../Session.ts";
+import type { LogEntry } from "./logs.ts";
+
+export interface StateTarget extends Target {
+  /** State-store worker to act on. @default the managed state-store worker */
+  readonly workerName?: string;
+}
+
+export interface BootstrapInput extends StateTarget {
+  readonly force?: boolean;
+}
+
+export interface StateLogsInput extends StateTarget {
+  readonly limit?: number;
+  readonly since?: Date;
+}
+
+const logEntry = (
+  scriptName: string,
+  line: { readonly timestamp: Date; readonly message: string },
+): LogEntry => ({
+  resource: {
+    fqn: scriptName,
+    logicalId: scriptName,
+    resourceType: "Cloudflare.Worker",
+  },
+  timestamp: line.timestamp,
+  message: line.message,
+});
+
+const services = Effect.fn(function* (target: StateTarget) {
+  const auth = Layer.provideMerge(
+    CloudflareAuth,
+    Layer.succeed(AuthProviders, {} satisfies AuthProviders["Service"]),
+  );
+  // `provideMerge` (not `mergeAll`) so `fromProfile` / `fromAuthProvider`
+  // actually *see* `--profile`. Sibling-merging ConfigProvider left those
+  // layers requiring it from the outer CLI `fromEnv()` — which is how
+  // `alchemy provider cloudflare bootstrap --profile <name>` ignored the
+  // flag and resolved the default profile (#252).
+  const config = ConfigProvider.layer(
+    withProfileOverride(
+      yield* loadConfigProvider(Option.fromNullishOr(target.envFile)),
+      target.profile,
+    ),
+  );
+  return Layer.mergeAll(
+    Layer.provideMerge(
+      Layer.mergeAll(
+        CloudflareCredentials.fromAuthProvider(),
+        CloudflareEnvironment.fromProfile(),
+        CloudflareAccess.AccessLive,
+      ),
+      auth,
+    ).pipe(Layer.provideMerge(config)),
+    Logger.layer([fileLogger("cloudflare.txt")], { mergeWithExisting: true }),
+  );
+});
+
+/**
+ * Resolve the profile, Cloudflare account, and provider layer every
+ * state-store route (`bootstrap`, `teardown`, logs) is scoped to.
+ */
+export const resolveStateStoreScope = Effect.fn(function* (
+  target: StateTarget,
+) {
+  const profile = yield* resolveProfileName(
+    Option.fromNullishOr(target.envFile),
+    target.profile,
+  );
+  const resolved = { ...target, profile };
+  const layer = yield* services(resolved);
+  const { accountId } = yield* Effect.flatten(
+    CloudflareEnvironment.CloudflareEnvironment,
+  ).pipe(Effect.provide(layer));
+  return {
+    layer,
+    profile,
+    accountId,
+    workerName: target.workerName ?? STATE_STORE_SCRIPT_NAME,
+  };
+});
+
+/** Provision (or adopt) the Cloudflare-hosted state-store worker. */
+export const bootstrap = Effect.fn("Alchemist.provider.cloudflare.bootstrap")(
+  function* (input: BootstrapInput) {
+    const { layer, accountId, workerName, profile } =
+      yield* resolveStateStoreScope(input);
+    return yield* Effect.gen(function* () {
+      const existed = yield* workers
+        .getScriptSetting({ accountId, scriptName: workerName })
+        .pipe(
+          Effect.as(true),
+          Effect.catchTag(
+            ["WorkerNotFound", "InvalidRoute", "WorkerHasNoVersions"],
+            () => Effect.succeed(false),
+          ),
+        );
+      const state = yield* bootstrapStateStore({
+        workerName,
+        force: input.force,
+        profile,
+      });
+      return {
+        accountId,
+        workerName,
+        status: !existed
+          ? ("created" as const)
+          : input.force
+            ? ("redeployed" as const)
+            : ("adopted" as const),
+        credentialsRefreshed: true,
+        stateStoreVersion: yield* state.getVersion(),
+      };
+    }).pipe(Effect.provide(layer));
+  },
+);
+
+/** Tear down the Cloudflare-hosted state store. */
+export const teardown = Effect.fn("Alchemist.provider.cloudflare.teardown")(
+  function* (input: StateTarget) {
+    const { layer, accountId, workerName, profile } =
+      yield* resolveStateStoreScope(input);
+    yield* Effect.provide(teardownStateStore({ workerName, profile }), layer);
+    return { accountId, workerName, deleted: [workerName] };
+  },
+);
+
+/** Query past log entries from the state-store worker, oldest first. */
+export const stateLogs = Effect.fn("Alchemist.provider.cloudflare.stateLogs")(
+  function* (input: StateLogsInput) {
+    const { layer, accountId, workerName } =
+      yield* resolveStateStoreScope(input);
+    const lines = yield* Effect.gen(function* () {
+      const telemetry = yield* CloudflareLogs;
+      return yield* telemetry.queryLogs({
+        accountId,
+        filters: [
+          {
+            key: "$workers.scriptName",
+            operation: "eq",
+            type: "string",
+            value: workerName,
+          },
+        ],
+        options: { limit: input.limit ?? 100, since: input.since },
+      });
+    }).pipe(Effect.provide(layer));
+    return lines
+      .map((line) => logEntry(workerName, line))
+      .sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+  },
+);
+
+/** Live-stream log entries from the state-store worker. */
+export const tailStateLogs = (input: StateTarget) =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const { layer, accountId, workerName } =
+        yield* resolveStateStoreScope(input);
+      const telemetry = yield* Effect.provide(CloudflareLogs, layer);
+      return telemetry.tailScript({ accountId, scriptName: workerName }).pipe(
+        Stream.provide(layer),
+        Stream.map((line) => logEntry(workerName, line)),
+      );
+    }),
+  );

package/src/Alchemist/routes/cloudflareToken.ts

@@ -0,0 +1,215 @@
+import * as accounts from "@distilled.cloud/cloudflare/accounts";
+import {
+  apiKeyCredentials,
+  apiTokenCredentials,
+} from "@distilled.cloud/cloudflare/Credentials";
+import * as user from "@distilled.cloud/cloudflare/user";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import {
+  selectableScopes,
+  tokenPolicies,
+  type PermissionGroup,
+  type TokenPolicy,
+} from "../../Cloudflare/Auth/TokenPolicy.ts";
+import * as CloudflareCredentials from "../../Cloudflare/Credentials.ts";
+import { AlchemistInvalidInput, type Diagnostic } from "../Errors.ts";
+
+export interface GlobalCredentials {
+  readonly email: string;
+  readonly apiKey: Redacted.Redacted<string>;
+}
+
+export interface Account {
+  readonly id: string;
+  readonly name: string;
+}
+
+export type {
+  PermissionGroup,
+  TokenPolicy,
+} from "../../Cloudflare/Auth/TokenPolicy.ts";
+
+export interface TokenCatalog {
+  readonly accounts: ReadonlyArray<Account>;
+  readonly permissionGroups: ReadonlyArray<PermissionGroup>;
+}
+
+export interface PlanInput {
+  readonly credentials: GlobalCredentials;
+  readonly name: string;
+  readonly accountIds: ReadonlyArray<string>;
+  readonly permissionGroupIds: ReadonlyArray<string> | "all";
+}
+
+export interface TokenPlan {
+  readonly name: string;
+  readonly accountIds: ReadonlyArray<string>;
+  readonly permissionGroupIds: ReadonlyArray<string>;
+  readonly permissionCount: number;
+  readonly grantsFullAccess: boolean;
+  readonly policies: ReadonlyArray<TokenPolicy>;
+}
+
+export interface CreateInput {
+  readonly credentials: GlobalCredentials;
+  readonly plan: TokenPlan;
+}
+
+export interface CreatedToken {
+  readonly id: string;
+  readonly name: string;
+  readonly value: Redacted.Redacted<string>;
+  readonly grantedPermissionGroups: number;
+  /** Echoed back by Cloudflare; may contain effects we never request. */
+  readonly policies: ReadonlyArray<unknown>;
+  readonly verificationStatus?: string;
+  readonly diagnostics: ReadonlyArray<Diagnostic>;
+}
+
+/** Cloudflare accepted the create call but returned no usable token. */
+export class CloudflareTokenError extends Data.TaggedError(
+  "CloudflareTokenError",
+)<{ readonly message: string }> {}
+
+/** Authenticate the surrounding effect with the user's Global API Key. */
+const withGlobalKey = (credentials: GlobalCredentials) =>
+  Effect.provideService(
+    CloudflareCredentials.Credentials,
+    Effect.succeed(
+      apiKeyCredentials({
+        apiKey: Redacted.value(credentials.apiKey),
+        email: credentials.email,
+      }),
+    ),
+  );
+
+/** The accounts and permission groups a token can be scoped to. */
+export const catalog = Effect.fn("Alchemist.cloudflare.token.catalog")(
+  // The credentials only authenticate the call, via the transformer below.
+  function* (_credentials: GlobalCredentials) {
+    const listAccounts = yield* accounts.listAccounts;
+    const listPermissionGroups = yield* user.listTokenPermissionGroups;
+    const { accountResponse, permissionGroupResponse } = yield* Effect.all(
+      {
+        accountResponse: listAccounts({}),
+        permissionGroupResponse: listPermissionGroups({}),
+      },
+      { concurrency: "unbounded" },
+    );
+    return {
+      accounts: accountResponse.result.map(({ id, name }) => ({
+        id,
+        name,
+      })),
+      permissionGroups: permissionGroupResponse.result.flatMap((group) =>
+        group.id && group.name && group.scopes?.length
+          ? [
+              {
+                id: group.id,
+                name: group.name,
+                category: group.category ?? undefined,
+                scopes: group.scopes,
+                selectable: selectableScopes.has(group.scopes[0]!),
+              },
+            ]
+          : [],
+      ),
+    } satisfies TokenCatalog;
+  },
+  (effect, credentials) => withGlobalKey(credentials)(effect),
+);
+
+/** Resolve the selected permission groups into concrete token policies. */
+export const plan = Effect.fn("Alchemist.cloudflare.token.plan")(function* (
+  input: PlanInput,
+) {
+  const tokenCatalog = yield* catalog(input.credentials);
+  const selected =
+    input.permissionGroupIds === "all"
+      ? tokenCatalog.permissionGroups
+      : yield* Effect.forEach(input.permissionGroupIds, (id) => {
+          const group = tokenCatalog.permissionGroups.find(
+            (candidate) => candidate.id === id,
+          );
+          if (group === undefined) {
+            return Effect.fail(
+              new AlchemistInvalidInput({
+                field: "permissionGroupIds",
+                message: `Unknown Cloudflare permission group '${id}'.`,
+              }),
+            );
+          }
+          return Effect.succeed(group);
+        });
+  const currentUser = yield* user
+    .getUser({})
+    .pipe(withGlobalKey(input.credentials));
+  const resolved = tokenPolicies(input.accountIds, currentUser.id, selected);
+  if (resolved.length === 0) {
+    return yield* Effect.fail(
+      new AlchemistInvalidInput({
+        field: "permissionGroupIds",
+        message:
+          "No selected permission groups can be expressed as token policies.",
+      }),
+    );
+  }
+  return {
+    name: input.name,
+    accountIds: input.accountIds,
+    permissionGroupIds: selected.map(({ id }) => id),
+    permissionCount: selected.length,
+    grantsFullAccess: input.permissionGroupIds === "all",
+    policies: resolved,
+  } satisfies TokenPlan;
+});
+
+/** Mint the planned token with the user's Global API Key. */
+export const create = Effect.fn("Alchemist.cloudflare.token.create")(
+  function* (input: CreateInput) {
+    const result = yield* user.createToken({
+      name: input.plan.name,
+      policies: input.plan.policies as TokenPolicy[],
+    });
+    if (!result.value) {
+      return yield* Effect.fail(
+        new CloudflareTokenError({
+          message: "Cloudflare did not return a token value.",
+        }),
+      );
+    }
+    const granted = (result.policies ?? []).reduce(
+      (count, policy) => count + (policy.permissionGroups?.length ?? 0),
+      0,
+    );
+    const verificationStatus = yield* user.verifyToken({}).pipe(
+      Effect.provideService(
+        CloudflareCredentials.Credentials,
+        Effect.succeed(apiTokenCredentials({ apiToken: result.value })),
+      ),
+      Effect.map(({ status }) => status),
+      Effect.catch(() => Effect.succeed(undefined)),
+    );
+    return {
+      id: result.id ?? "unknown",
+      name: result.name ?? input.plan.name,
+      value: Redacted.make(result.value),
+      grantedPermissionGroups: granted,
+      policies: result.policies ?? input.plan.policies,
+      verificationStatus,
+      diagnostics:
+        granted === 0
+          ? [
+              {
+                severity: "warning" as const,
+                code: "cloudflare.token.zero-permissions",
+                message: "Cloudflare created the token with zero permissions.",
+              },
+            ]
+          : [],
+    } satisfies CreatedToken;
+  },
+  (effect, input) => withGlobalKey(input.credentials)(effect),
+);

package/src/Alchemist/routes/drift.ts

@@ -0,0 +1,94 @@
+import * as Effect from "effect/Effect";
+import * as EngineDrift from "../../Drift.ts";
+import type { Plan } from "../../Plan.ts";
+import { applySession, Progress, withSpanEvents } from "../Progress.ts";
+import { open, type Session, type StackTarget } from "../Session.ts";
+import * as Stack from "./stack.ts";
+
+export interface DriftedResource {
+  readonly fqn: string;
+  readonly logicalId: string;
+  readonly resourceType: string;
+  readonly status: "in-sync" | "drifted" | "missing";
+  readonly actual?: unknown;
+}
+
+export interface DriftSnapshot {
+  readonly stack: { readonly name: string; readonly stage: string };
+  readonly resources: ReadonlyArray<DriftedResource>;
+  readonly repairPlan: {
+    readonly summary: Stack.PlanSummary;
+    readonly native: Plan;
+  };
+  /** The session drift was inspected under; {@link repair} runs in it. */
+  readonly session: Session;
+}
+
+/** Whether the drift check found anything worth repairing. */
+export const hasDrift = (snapshot: DriftSnapshot): boolean =>
+  snapshot.resources.some(
+    (resource) =>
+      resource.status === "drifted" || resource.status === "missing",
+  );
+
+const status = (action: string) =>
+  action === "unchanged"
+    ? ("in-sync" as const)
+    : action === "missing"
+      ? ("missing" as const)
+      : ("drifted" as const);
+
+/** Compare deployed state against the real cloud and plan the repair. */
+export const inspect = Effect.fn("Alchemist.drift.inspect")(function* (
+  target: StackTarget,
+) {
+  const report = withSpanEvents(yield* Progress);
+  // `open` emits importing-module / resolving-services at the real work
+  // boundaries; hand it the wrapped reporter so they land in traces too.
+  const session = yield* open(target).pipe(
+    Effect.provideService(Progress, report),
+  );
+  const identity = {
+    name: session.stack.name,
+    stage: session.stack.stage,
+  };
+  const { result, plan } = yield* EngineDrift.plan(identity).pipe(
+    // The engine's phase and per-resource observation events flow through
+    // the same wrapped reporter; drift-flavored wording is the renderer's
+    // job (renderPlanning's computingLabel).
+    Effect.provideService(Progress, report),
+    Effect.provide(session.context),
+  );
+  yield* report({ _tag: "plan.phase", phase: "plan-ready" });
+  return {
+    stack: identity,
+    resources: Object.values(result.resources)
+      .filter((resource) => resource.action !== "skipped")
+      .map((resource) => ({
+        fqn: resource.fqn,
+        logicalId: resource.logicalId,
+        resourceType: resource.resourceType,
+        status: status(resource.action),
+        actual: resource.attr,
+      })),
+    repairPlan: { summary: Stack.summarize(plan), native: plan },
+    session,
+  } satisfies DriftSnapshot;
+});
+
+/**
+ * Converge state back to the cloud's actual shape. Engine apply events are
+ * reported through {@link Progress}.
+ */
+export const repair = Effect.fn("Alchemist.drift.repair")(function* (
+  snapshot: DriftSnapshot,
+) {
+  const report = withSpanEvents(yield* Progress);
+  return yield* Effect.provide(
+    EngineDrift.repair(
+      { name: snapshot.stack.name, stage: snapshot.stack.stage },
+      { session: applySession(report) },
+    ),
+    snapshot.session.context,
+  );
+});

package/src/Alchemist/routes/logs.ts

@@ -0,0 +1,185 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import { findProviderByType } from "../../Provider.ts";
+import { stampedMode } from "../../ProviderMode.ts";
+import * as State from "../../State/index.ts";
+import { AlchemistInvalidInput } from "../Errors.ts";
+import { open, type StackTarget } from "../Session.ts";
+
+export interface ResourceIdentity {
+  readonly fqn: string;
+  readonly logicalId: string;
+  readonly resourceType: string;
+}
+
+export interface LogResource extends ResourceIdentity {
+  readonly supportsQuery: boolean;
+  readonly supportsTail: boolean;
+}
+
+export interface LogEntry {
+  readonly resource: ResourceIdentity;
+  readonly timestamp: Date;
+  readonly message: string;
+}
+
+export interface LogInput {
+  readonly target: StackTarget;
+  /** Logical IDs to include. Empty or omitted means every resource. */
+  readonly resources?: ReadonlyArray<string>;
+}
+
+export interface QueryInput extends LogInput {
+  readonly limit?: number;
+  readonly since?: Date;
+}
+
+/**
+ * Open the stack and pair every deployed resource with the provider that
+ * can speak for it. `entries` and `tail` differ only in which provider hook
+ * they then call, so the selection lives here once.
+ */
+const select = Effect.fn(function* (input: LogInput) {
+  const session = yield* open(input.target);
+  // The local store sits UNDER the session context, so the stack's own
+  // store wins where it configures one: a project may only wire a remote
+  // store at deploy time, and `alchemy logs` still has to resolve what was
+  // deployed.
+  const context = Context.merge(
+    yield* Layer.build(State.localState()),
+    session.context,
+  );
+  const selected = new Set(input.resources ?? []);
+  const available = [
+    ...new Set(
+      Object.values(session.stack.resources).map(
+        (resource) => resource.LogicalId,
+      ),
+    ),
+  ].sort();
+  const unknown = [...selected].find((name) => !available.includes(name));
+  if (unknown !== undefined) {
+    return yield* Effect.fail(
+      new AlchemistInvalidInput({
+        field: "resources",
+        message: `Unknown resource '${unknown}'. Available: ${available.join(", ") || "(none)"}`,
+      }),
+    );
+  }
+  const rows = yield* Effect.provide(
+    Effect.gen(function* () {
+      const state = yield* yield* State.State;
+      return yield* Effect.forEach(
+        Object.entries(session.stack.resources),
+        ([fqn, resource]) =>
+          Effect.gen(function* () {
+            if (selected.size > 0 && !selected.has(resource.LogicalId)) {
+              return [];
+            }
+            const stored = yield* state.get({
+              stack: session.stack.name,
+              stage: session.stack.stage,
+              fqn,
+            });
+            if (!State.isResourceState(stored) || stored.attr === undefined) {
+              return [];
+            }
+            return [
+              {
+                resource: {
+                  fqn,
+                  logicalId: resource.LogicalId,
+                  resourceType: resource.Type,
+                } satisfies ResourceIdentity,
+                provider: yield* findProviderByType(
+                  resource.Type,
+                  stampedMode(stored),
+                ),
+                request: {
+                  id: resource.LogicalId,
+                  fqn,
+                  instanceId: stored.instanceId,
+                  props: stored.props,
+                  output: stored.attr,
+                },
+              },
+            ];
+          }),
+      ).pipe(Effect.map((rows) => rows.flat()));
+    }),
+    context,
+  );
+  return { context, rows };
+});
+
+/** Every deployed resource, with the log capabilities its provider offers. */
+export const resources = Effect.fn("Alchemist.logs.resources")(function* (
+  target: StackTarget,
+) {
+  const { rows } = yield* select({ target });
+  return rows.map(({ resource, provider }): LogResource => ({
+    ...resource,
+    supportsQuery: provider.logs !== undefined,
+    supportsTail: provider.tail !== undefined,
+  }));
+});
+
+/** Query past log entries across the selected resources, oldest first. */
+export const entries = Effect.fn("Alchemist.logs.entries")(function* (
+  input: QueryInput,
+) {
+  const { context, rows } = yield* select(input);
+  const entries = yield* Effect.provide(
+    Effect.forEach(rows, ({ resource, provider, request }) =>
+      provider.logs === undefined
+        ? Effect.succeed([])
+        : provider
+            .logs({
+              ...request,
+              options: {
+                limit: input.limit ?? 100,
+                since: input.since,
+              },
+            })
+            .pipe(
+              Effect.map((lines) =>
+                lines.map((line) => ({
+                  resource,
+                  timestamp: line.timestamp,
+                  message: line.message,
+                })),
+              ),
+            ),
+    ),
+    context,
+  );
+  return entries
+    .flat()
+    .sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+});
+
+/** Live-stream log entries from every selected resource that supports it. */
+export const tail = (input: LogInput) =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const { context, rows } = yield* select(input);
+      return Stream.mergeAll(
+        rows.flatMap(({ resource, provider, request }) =>
+          provider.tail === undefined
+            ? []
+            : [
+                Stream.provide(provider.tail(request), context).pipe(
+                  Stream.map((line): LogEntry => ({
+                    resource,
+                    timestamp: line.timestamp,
+                    message: line.message,
+                  })),
+                ),
+              ],
+        ),
+        { concurrency: "unbounded" },
+      );
+    }),
+  );