alchemy 2.0.0-beta.4 → 2.0.0-beta.41

package/src/Cli/LoggingCli.ts

@@ -0,0 +1,137 @@
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { CRUD, Plan } from "../Plan.ts";
+import { Cli } from "./Cli.ts";
+import type { ApplyEvent, ApplyStatus } from "./Event.ts";
+
+const ESC = "\x1b[";
+const RESET = `${ESC}0m`;
+const useColor = process.stdout.hasColors?.() ?? !!process.stdout.isTTY;
+const c = (code: string, s: string) =>
+  useColor ? `${ESC}${code}m${s}${RESET}` : s;
+const dim = (s: string) => c("2", s);
+const bold = (s: string) => c("1", s);
+const red = (s: string) => c("31", s);
+const green = (s: string) => c("32", s);
+const yellow = (s: string) => c("33", s);
+const blue = (s: string) => c("34", s);
+const magenta = (s: string) => c("35", s);
+const cyan = (s: string) => c("36", s);
+
+const actionColor: Record<CRUD["action"], (s: string) => string> = {
+  create: green,
+  update: yellow,
+  replace: magenta,
+  delete: red,
+  noop: dim,
+};
+
+const statusColor = (status: ApplyStatus): ((s: string) => string) => {
+  switch (status) {
+    case "created":
+    case "updated":
+    case "replaced":
+      return green;
+    case "deleted":
+      return dim;
+    case "fail":
+      return red;
+    case "attaching":
+    case "post-attach":
+      return cyan;
+    default:
+      return yellow;
+  }
+};
+
+const tag = (id: string) => bold(`[${id}]`);
+
+const isTerminal = (status: ApplyStatus): boolean =>
+  status === "created" ||
+  status === "updated" ||
+  status === "deleted" ||
+  status === "replaced" ||
+  status === "fail";
+
+const formatPlanLines = (plan: Plan): string[] => {
+  const items = [
+    ...Object.values(plan.resources),
+    ...Object.values(plan.deletions),
+  ] as CRUD[];
+  if (items.length === 0) return [bold("Plan:") + " no changes"];
+
+  const counts = items.reduce(
+    (acc, item) => ((acc[item.action] = (acc[item.action] ?? 0) + 1), acc),
+    {} as Record<CRUD["action"], number>,
+  );
+  const summary = (["create", "update", "replace", "delete", "noop"] as const)
+    .filter((a) => counts[a])
+    .map((a) => actionColor[a](`${counts[a]} to ${a}`))
+    .join(dim(", "));
+
+  const sorted = [...items].sort((a, b) =>
+    a.resource.LogicalId.localeCompare(b.resource.LogicalId),
+  );
+  const lines = [`${bold("Plan:")} ${summary}`];
+  for (const item of sorted) {
+    const action = actionColor[item.action](item.action);
+    lines.push(`${tag(item.resource.LogicalId)} ${action}`);
+    for (const binding of item.bindings) {
+      if (binding.action === "noop") continue;
+      const bindingAction = actionColor[binding.action](binding.action);
+      lines.push(
+        `${tag(`${item.resource.LogicalId}/${binding.sid}`)} ${bindingAction}`,
+      );
+    }
+  }
+  return lines;
+};
+
+export const LoggingCli = Layer.succeed(
+  Cli,
+  Cli.of({
+    approvePlan: (plan) =>
+      Effect.gen(function* () {
+        for (const line of formatPlanLines(plan)) yield* Console.log(line);
+        yield* Console.log(
+          `\n${yellow("Non-interactive terminal detected.")} Pass ${bold("--yes")} to approve, or set ${bold("ALCHEMY_TUI=1")} for the interactive UI.`,
+        );
+        return false;
+      }),
+    displayPlan: (plan) =>
+      Effect.gen(function* () {
+        for (const line of formatPlanLines(plan)) yield* Console.log(line);
+      }),
+    startApplySession: (plan) =>
+      Effect.gen(function* () {
+        for (const line of formatPlanLines(plan)) yield* Console.log(line);
+        yield* Console.log("");
+
+        const counts = { ok: 0, fail: 0 };
+        return {
+          emit: (event: ApplyEvent) =>
+            Effect.sync(() => {
+              if (event.kind === "annotate") {
+                console.log(`${tag(event.id)} ${blue(event.message)}`);
+                return;
+              }
+              const id = event.bindingId
+                ? `${event.id}/${event.bindingId}`
+                : event.id;
+              const status = statusColor(event.status)(event.status);
+              const msg = event.message ? ` ${dim("—")} ${event.message}` : "";
+              console.log(`${tag(id)} ${status}${msg}`);
+              if (isTerminal(event.status)) {
+                if (event.status === "fail") counts.fail++;
+                else counts.ok++;
+              }
+            }),
+          done: () =>
+            Console.log(
+              `\n${bold("Done:")} ${green(`${counts.ok} succeeded`)}${counts.fail ? dim(", ") + red(`${counts.fail} failed`) : ""}`,
+            ),
+        };
+      }),
+  }),
+);

package/src/Cli/NamespaceTree.ts

@@ -1,20 +1,30 @@
 import { toPath } from "../FQN.ts";
-import type { BindingAction, CRUD } from "../Plan.ts";
+import type {
+  BindingAction,
+  CRUD,
+  ActionApply,
+  ActionDelete,
+} from "../Plan.ts";
 
 export interface TreeBinding {
   sid: string;
   action: BindingAction;
 }
 
+export type ActionTreeItem = ActionApply | ActionDelete;
+export type ActionVerb = ActionTreeItem["action"]; // "run" | "noop" | "delete"
+
 /**
  * A tree node representing a namespace.
- * Resources live directly inside the namespace where they were created.
+ * Resources and tasks live directly inside the namespace where they were
+ * created.
  */
 export interface TreeNode {
   id: string;
   path: string[];
   children: Map<string, TreeNode>;
   resources: CRUD[];
+  actions: ActionTreeItem[];
 }
 
 export type DerivedAction =
@@ -25,12 +35,16 @@ export type DerivedAction =
   | "noop"
   | "mixed";
 
-export function buildNamespaceTree(items: CRUD[]): TreeNode {
+export function buildNamespaceTree(
+  items: CRUD[],
+  actions: ReadonlyArray<ActionTreeItem> = [],
+): TreeNode {
   const root: TreeNode = {
     id: "",
     path: [],
     children: new Map(),
     resources: [],
+    actions: [],
   };
 
   const getNode = (path: string[]) => {
@@ -44,6 +58,7 @@ export function buildNamespaceTree(items: CRUD[]): TreeNode {
           path: path.slice(0, i + 1),
           children: new Map(),
           resources: [],
+          actions: [],
         };
         current.children.set(segment, child);
       }
@@ -55,6 +70,9 @@ export function buildNamespaceTree(items: CRUD[]): TreeNode {
   for (const item of items) {
     getNode(toPath(item.resource.Namespace)).resources.push(item);
   }
+  for (const action of actions) {
+    getNode(toPath(action.def.Namespace)).actions.push(action);
+  }
 
   return root;
 }
@@ -65,6 +83,17 @@ export function deriveNamespaceAction(node: TreeNode): DerivedAction {
   for (const resource of node.resources) {
     actions.add(deriveResourceChildrenAction(resource, node));
   }
+  for (const action of node.actions) {
+    // Map task actions onto the resource action space for the rollup:
+    // run → create, delete → delete, noop → noop.
+    actions.add(
+      action.action === "run"
+        ? "create"
+        : action.action === "delete"
+          ? "delete"
+          : "noop",
+    );
+  }
   for (const child of node.children.values()) {
     const childAction = deriveNamespaceAction(child);
     if (childAction === "mixed") {
@@ -77,15 +106,17 @@ export function deriveNamespaceAction(node: TreeNode): DerivedAction {
 }
 
 export interface FlattenedItem {
-  type: "namespace" | "resource" | "binding";
+  type: "namespace" | "resource" | "binding" | "action";
   depth: number;
   id: string;
   path: string[];
-  action: CRUD["action"] | BindingAction | DerivedAction;
+  action: CRUD["action"] | BindingAction | DerivedAction | ActionVerb;
   resourceType?: string;
   bindingSid?: string;
   bindingCount?: number;
   hasChildren?: boolean;
+  /** For task items, the Task's Type (e.g. "Sync"). */
+  actionType?: string;
 }
 
 export function flattenTree(
@@ -154,10 +185,26 @@ const flattenNamespace = (
       flattenNamespace(childNamespace, depth + 1, result);
     }
   }
+
+  // Actions are listed after resources at the same depth.
+  const sortedActions = [...node.actions].sort((a, b) =>
+    a.def.LogicalId.localeCompare(b.def.LogicalId),
+  );
+  for (const action of sortedActions) {
+    result.push({
+      type: "action",
+      depth,
+      id: action.def.LogicalId,
+      path: [...node.path, action.def.LogicalId],
+      action: action.action,
+      actionType: action.def.Type,
+    });
+  }
 };
 
 const isEmpty = (node: TreeNode) =>
   node.resources.length === 0 &&
+  node.actions.length === 0 &&
   Array.from(node.children.values()).every(isEmpty);
 
 const countVisibleChildren = (node: TreeNode) => {

package/src/Cli/checkVersion.ts

@@ -0,0 +1,57 @@
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+
+import packageJson from "../../package.json" with { type: "json" };
+
+const NPM_DIST_TAGS_URL =
+  "https://registry.npmjs.org/-/package/alchemy/dist-tags";
+
+/**
+ * Pick the dist-tag matching the current channel. For pre-release versions
+ * like `2.0.0-beta.33`, npm's `latest` tag points at the most recent stable
+ * release — not the newest beta — so we match the prerelease identifier
+ * (`beta`, `next`, etc.), falling back through `next` → `latest`.
+ */
+const pickDistTag = (
+  current: string,
+  distTags: Record<string, string>,
+): string | undefined => {
+  const pre = current.split("-", 2)[1];
+  if (pre) {
+    const id = pre.split(".")[0];
+    if (id && distTags[id]) return distTags[id];
+    if (distTags.next) return distTags.next;
+  }
+  return distTags.latest;
+};
+
+/**
+ * Fetch the published `alchemy` version on the dist-tag matching the
+ * current channel and log a warning if it's different from the bundled
+ * version. Best-effort: any failure (offline, registry hiccup, slow
+ * response) is swallowed silently.
+ */
+export const checkLatestVersion = Effect.gen(function* () {
+  const http = yield* HttpClient.HttpClient;
+  const response = yield* http.get(NPM_DIST_TAGS_URL);
+  const distTags = (yield* response.json) as Record<string, string>;
+  if (typeof distTags !== "object" || distTags === null) return;
+  const current = packageJson.version;
+  const latest = pickDistTag(current, distTags);
+  if (typeof latest !== "string" || latest === current) return;
+  const installCmd =
+    typeof process !== "undefined" && (process as any).versions?.bun
+      ? `bun add alchemy@${latest}`
+      : `pnpm add alchemy@${latest}`;
+  yield* Effect.logWarning(
+    `alchemy ${latest} is available (you're on ${current}). ` +
+      `Run \`${installCmd}\` to upgrade.`,
+  );
+}).pipe(
+  Effect.timeout(Duration.seconds(5)),
+  Effect.catch(() => Effect.void),
+);
+
+// Exported for tests.
+export const _internal = { pickDistTag };

package/src/Cli/commands/_shared.ts

@@ -0,0 +1,273 @@
+import * as Cause from "effect/Cause";
+import * as Config from "effect/Config";
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as S from "effect/Schema";
+import * as Argument from "effect/unstable/cli/Argument";
+import * as CliError from "effect/unstable/cli/CliError";
+import * as Flag from "effect/unstable/cli/Flag";
+
+import { AuthError } from "../../Auth/AuthProvider.ts";
+import type * as Stack from "../../Stack.ts";
+import { recordCli } from "../../Telemetry/Metrics.ts";
+import { PromptCancelled } from "../../Util/Clank.ts";
+
+export const USER = Config.string("USER").pipe(
+  Config.orElse(() => Config.string("USERNAME")),
+  Config.withDefault("unknown"),
+);
+
+export const STAGE = Config.string("stage").pipe(
+  Config.option,
+  (a) => a,
+  Effect.map(Option.getOrUndefined),
+);
+
+/**
+ * `true` if `e` is a {@link PromptCancelled}, or an {@link AuthError} whose
+ * `cause` chain bottoms out in one. Schema-tagged errors don't always
+ * survive `instanceof` across module boundaries, so we also accept any
+ * object whose `_tag` matches.
+ */
+const isPromptCancellation = (e: unknown): boolean => {
+  for (let cur: unknown = e, i = 0; cur != null && i < 16; i++) {
+    if (cur instanceof PromptCancelled) return true;
+    if (
+      typeof cur === "object" &&
+      (cur as { _tag?: unknown })._tag === "PromptCancelled"
+    ) {
+      return true;
+    }
+    if (
+      cur instanceof AuthError ||
+      (typeof cur === "object" &&
+        (cur as { _tag?: unknown })._tag === "AuthError")
+    ) {
+      cur = (cur as { cause?: unknown }).cause;
+      continue;
+    }
+    return false;
+  }
+  return false;
+};
+
+/**
+ * Catches user cancellations (Ctrl+C inside a prompt, surfaced as
+ * {@link PromptCancelled} or wrapped in an {@link AuthError}) and exits
+ * the CLI cleanly with a friendly message instead of dumping a stack
+ * trace.
+ */
+export const handleCancellation = <A, E, R>(self: Effect.Effect<A, E, R>) =>
+  self.pipe(
+    Effect.catchCause((cause) => {
+      const cancelled = cause.reasons.some((r) => {
+        if (Cause.isFailReason(r)) return isPromptCancellation(r.error);
+        if (Cause.isDieReason(r)) return isPromptCancellation(r.defect);
+        return false;
+      });
+      return cancelled
+        ? Console.log("\nCancelled.")
+        : (Effect.failCause(cause) as Effect.Effect<never, E, never>);
+    }),
+    // A bare fiber interrupt (Ctrl+C while not inside a prompt) shouldn't
+    // dump a stack trace either.
+    Effect.onInterrupt(() => Console.log("\nInterrupted.")),
+  );
+
+export const stage = Flag.string("stage").pipe(
+  Flag.withSchema(S.String.check(S.isPattern(/^[a-z0-9]+([-_a-z0-9]+)*$/gi))),
+  Flag.withDescription("Stage to deploy to, defaults to dev_${USER}"),
+  Flag.optional,
+  Flag.map(Option.getOrUndefined),
+  Flag.mapEffect(
+    Effect.fn(function* (stage) {
+      if (stage) {
+        return stage;
+      }
+      return yield* STAGE.pipe(
+        Effect.catch(() =>
+          Effect.fail(
+            new CliError.MissingOption({
+              option: "stage",
+            }),
+          ),
+        ),
+        Effect.flatMap((s) =>
+          s === undefined
+            ? USER.pipe(
+                Effect.map((user) => `dev_${user}`),
+                Effect.catch(() => Effect.succeed("unknown")),
+              )
+            : Effect.succeed(s),
+        ),
+      );
+    }),
+  ),
+);
+
+export const envFile = Flag.file("env-file").pipe(
+  Flag.optional,
+  Flag.withDescription(
+    "File to load environment variables from, defaults to .env",
+  ),
+);
+
+export const dryRun = Flag.boolean("dry-run").pipe(
+  Flag.withDescription("Dry run the deployment, do not actually deploy"),
+  Flag.withDefault(false),
+);
+
+export const yes = Flag.boolean("yes").pipe(
+  Flag.withDescription("Yes to all prompts"),
+  Flag.withDefault(false),
+);
+
+export const force = Flag.boolean("force").pipe(
+  Flag.withDescription(
+    "Force updates for resources that would otherwise no-op",
+  ),
+  Flag.withDefault(false),
+);
+
+export const script = Argument.file("main", {
+  mustExist: true,
+}).pipe(
+  Argument.withDescription("Main file to deploy, defaults to alchemy.run.ts"),
+  Argument.withDefault("alchemy.run.ts"),
+);
+
+export const profile = Flag.string("profile").pipe(
+  Flag.withDescription(
+    "Auth profile to use (~/.alchemy/profiles.json). Defaults to 'default' or $ALCHEMY_PROFILE.",
+  ),
+  Flag.optional,
+  Flag.map(Option.getOrElse(() => "default")),
+);
+
+export const resourceFilter = Flag.string("filter").pipe(
+  Flag.withDescription(
+    "Comma-separated logical resource IDs (e.g. Api,Sandbox). Only those resources are included.",
+  ),
+  Flag.optional,
+  Flag.map(Option.getOrUndefined),
+);
+
+export const TAIL_COLORS = [
+  "\x1b[36m", // cyan
+  "\x1b[35m", // magenta
+  "\x1b[33m", // yellow
+  "\x1b[32m", // green
+  "\x1b[34m", // blue
+  "\x1b[91m", // bright red
+  "\x1b[96m", // bright cyan
+  "\x1b[95m", // bright magenta
+  "\x1b[93m", // bright yellow
+  "\x1b[92m", // bright green
+];
+export const TAIL_RESET = "\x1b[0m";
+
+export const formatLocalTimestamp = (date: Date): string => {
+  const y = date.getFullYear();
+  const mo = String(date.getMonth() + 1).padStart(2, "0");
+  const d = String(date.getDate()).padStart(2, "0");
+  const h = String(date.getHours()).padStart(2, "0");
+  const mi = String(date.getMinutes()).padStart(2, "0");
+  const s = String(date.getSeconds()).padStart(2, "0");
+  const ms = String(date.getMilliseconds()).padStart(3, "0");
+  const tz =
+    new Intl.DateTimeFormat("en-US", { timeZoneName: "short" })
+      .formatToParts(date)
+      .find((p) => p.type === "timeZoneName")?.value ?? "";
+  return `${y}-${mo}-${d} ${h}:${mi}:${s}.${ms} ${tz}`;
+};
+
+export const parseResourceFilter = (
+  filter: string | undefined,
+): ReadonlySet<string> | undefined => {
+  if (filter === undefined) return undefined;
+  const ids = filter
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  if (ids.length === 0) return undefined;
+  return new Set(ids);
+};
+
+export const parseSince = (value: string): Date => {
+  const match = value.match(/^(\d+)([smhd])$/);
+  if (match) {
+    const num = parseInt(match[1]!, 10);
+    const unit = match[2]!;
+    const ms =
+      unit === "s"
+        ? num * 1000
+        : unit === "m"
+          ? num * 60_000
+          : unit === "h"
+            ? num * 3_600_000
+            : num * 86_400_000;
+    return new Date(Date.now() - ms);
+  }
+  const parsed = new Date(value);
+  if (isNaN(parsed.getTime())) {
+    throw new Error(
+      `Invalid --since value: '${value}'. Use a duration (e.g. '1h', '30m') or ISO date.`,
+    );
+  }
+  return parsed;
+};
+
+/**
+ * Wraps a CLI command handler with a top-level OpenTelemetry span
+ * (`cli.<command>`) and bumps the `alchemy.cli.invocations` counter.
+ *
+ * `attrs` runs against the parsed command args and contributes
+ * additional attributes to the span (e.g. stage, profile, dry-run flag).
+ *
+ * Usage:
+ * ```ts
+ * Command.make(
+ *   "deploy",
+ *   { ...flags },
+ *   instrumentCommand("deploy", (a) => ({
+ *     "alchemy.stage": a.stage,
+ *     "alchemy.profile": a.profile,
+ *   }))(execStack),
+ * );
+ * ```
+ */
+export const instrumentCommand =
+  <AttrsArgs = unknown>(
+    command: string,
+    attrs?: (args: AttrsArgs) => Record<string, unknown>,
+  ) =>
+  <Args extends AttrsArgs, A, E, R>(
+    handler: (args: Args) => Effect.Effect<A, E, R>,
+  ): ((args: Args) => Effect.Effect<A, E, R>) =>
+  (args) =>
+    handler(args).pipe(
+      Effect.withSpan(`cli.${command}`, {
+        attributes: attrs ? attrs(args) : {},
+      }),
+      recordCli(command),
+    );
+
+export const importStack = Effect.fn(function* (main: string) {
+  const path = yield* Path.Path;
+  const module = yield* Effect.promise(
+    () => import(path.resolve(process.cwd(), main)),
+  );
+  const stackEffect = module.default as ReturnType<
+    ReturnType<typeof Stack.make>
+  >;
+  if (!Effect.isEffect(stackEffect)) {
+    return yield* Effect.die(
+      new Error(
+        `Main file '${main}' must export a default stack definition (export default Alchemy.Stack({...}))`,
+      ),
+    );
+  }
+  return stackEffect;
+});