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

package/src/Cli/NamespaceTree.ts

@@ -4,17 +4,71 @@ import type {
   CRUD,
   ActionApply,
   ActionDelete,
+  Plan,
 } from "../Plan.ts";
 import type { ProviderMode } from "../ProviderMode.ts";
-
-export interface TreeBinding {
-  sid: string;
-  action: BindingAction;
-}
+import {
+  formatDeclaredPropertyYaml,
+  formatDriftPropertyYaml,
+  type DeclaredPropertyYaml,
+} from "./PropertyDiff.ts";
 
 export type ActionTreeItem = ActionApply | ActionDelete;
 export type ActionVerb = ActionTreeItem["action"]; // "run" | "noop" | "delete"
 
+/** No-op actions are dependency markers, not work the user needs to review. */
+export const actionHasPlannedWork = (item: ActionTreeItem): boolean =>
+  item.action !== "noop";
+
+export interface PlanSummaryCounts {
+  readonly counts: Record<
+    | "create"
+    | "update"
+    | "adopted"
+    | "delete"
+    | "orphaned"
+    | "replace"
+    | "noop",
+    number
+  >;
+  readonly taskCounts: Record<"run" | "delete" | "noop", number>;
+  readonly bindingChanges: number;
+}
+
+/** Count every resource and task, plus binding changes, for the Plan summary. */
+export const buildPlanSummary = (plan: Plan): PlanSummaryCounts => {
+  const allItems = [
+    ...Object.values(plan.resources),
+    ...Object.values(plan.deletions),
+  ].filter((item): item is CRUD => item !== undefined);
+  const counts = {
+    create: 0,
+    update: 0,
+    adopted: 0,
+    delete: 0,
+    orphaned: 0,
+    noop: 0,
+    replace: 0,
+  };
+  for (const item of allItems) {
+    counts[item.action]++;
+  }
+  const taskCounts = { run: 0, noop: 0, delete: 0 };
+  for (const item of [
+    ...Object.values(plan.actions ?? {}),
+    ...Object.values(plan.actionDeletions ?? {}),
+  ].filter((task): task is ActionTreeItem => task !== undefined)) {
+    taskCounts[item.action]++;
+  }
+  const bindingChanges = allItems.reduce(
+    (count, item) =>
+      count +
+      item.bindings.filter((binding) => binding.action !== "noop").length,
+    0,
+  );
+  return { counts, taskCounts, bindingChanges };
+};
+
 /**
  * A tree node representing a namespace.
  * Resources and tasks live directly inside the namespace where they were
@@ -31,7 +85,9 @@ export interface TreeNode {
 export type DerivedAction =
   | "create"
   | "update"
+  | "adopted"
   | "delete"
+  | "orphaned"
   | "replace"
   | "noop"
   | "mixed";
@@ -78,7 +134,7 @@ export function buildNamespaceTree(
   return root;
 }
 
-export function deriveNamespaceAction(node: TreeNode): DerivedAction {
+function deriveNamespaceAction(node: TreeNode): DerivedAction {
   const actions = new Set<BindingAction | CRUD["action"] | DerivedAction>();
 
   for (const resource of node.resources) {
@@ -128,14 +184,20 @@ export interface FlattenedItem {
    * old generation was created with (always differs from `providerMode`).
    */
   fromProviderMode?: ProviderMode;
+  /** Safe YAML detail attached only when the caller opts into detailed view. */
+  propertyYaml?: DeclaredPropertyYaml;
+}
+
+export interface FlattenTreeOptions {
+  includePropertyYaml?: boolean;
 }
 
 export function flattenTree(
   node: TreeNode,
-  depth = 0,
-  result: FlattenedItem[] = [],
+  options: FlattenTreeOptions = {},
 ): FlattenedItem[] {
-  flattenNamespace(node, depth, result);
+  const result: FlattenedItem[] = [];
+  flattenNamespace(node, 0, result, options);
   return result;
 }
 
@@ -143,6 +205,7 @@ const flattenNamespace = (
   node: TreeNode,
   depth: number,
   result: FlattenedItem[],
+  options: FlattenTreeOptions,
 ) => {
   const sortedResources = [...node.resources].sort((a, b) =>
     a.resource.LogicalId.localeCompare(b.resource.LogicalId),
@@ -166,7 +229,7 @@ const flattenNamespace = (
       action: deriveNamespaceAction(child),
       hasChildren: true,
     });
-    flattenNamespace(child, depth + 1, result);
+    flattenNamespace(child, depth + 1, result, options);
   }
 
   for (const resource of sortedResources) {
@@ -187,6 +250,24 @@ const flattenNamespace = (
         resource.state.providerMode !== resource.mode
           ? resource.state.providerMode
           : undefined,
+      propertyYaml:
+        "drift" in resource && resource.drift !== undefined
+          ? formatDriftPropertyYaml(
+              resource.drift.expected,
+              resource.drift.actual,
+              resource.drift.missing,
+            )
+          : options.includePropertyYaml &&
+              (resource.action === "create" ||
+                resource.action === "update" ||
+                resource.action === "adopted" ||
+                resource.action === "replace")
+            ? formatDeclaredPropertyYaml(
+                resource.action === "create" ? {} : resource.state.props,
+                resource.props,
+                resource.action === "adopted" ? "update" : resource.action,
+              )
+            : undefined,
     });
     for (const binding of [...resource.bindings].sort((a, b) =>
       a.sid.localeCompare(b.sid),
@@ -201,7 +282,7 @@ const flattenNamespace = (
       });
     }
     if (childNamespace) {
-      flattenNamespace(childNamespace, depth + 1, result);
+      flattenNamespace(childNamespace, depth + 1, result, options);
     }
   }
 
@@ -226,16 +307,6 @@ const isEmpty = (node: TreeNode) =>
   node.actions.length === 0 &&
   Array.from(node.children.values()).every(isEmpty);
 
-const countVisibleChildren = (node: TreeNode) => {
-  const resourceIds = new Set(
-    node.resources.map((resource) => resource.resource.LogicalId),
-  );
-  return (
-    node.resources.length +
-    Array.from(node.children.keys()).filter((id) => !resourceIds.has(id)).length
-  );
-};
-
 const deriveResourceChildrenAction = (
   resource: CRUD,
   node: TreeNode,
@@ -258,8 +329,10 @@ const deriveAction = (
 ): DerivedAction => {
   if (actions.size === 0) return "noop";
   if (actions.has("replace")) return actions.size === 1 ? "replace" : "mixed";
+  if (actions.has("orphaned")) return actions.size === 1 ? "orphaned" : "mixed";
   if (actions.has("delete")) return actions.size === 1 ? "delete" : "mixed";
   if (actions.has("create")) return actions.size === 1 ? "create" : "mixed";
+  if (actions.has("adopted")) return actions.size === 1 ? "adopted" : "mixed";
   if (actions.has("update")) return actions.size === 1 ? "update" : "mixed";
   return "noop";
 };

package/src/Cli/PlainCliFormatter.ts

@@ -0,0 +1,75 @@
+import * as CliOutput from "effect/unstable/cli/CliOutput";
+import type { FlagDoc, HelpDoc } from "effect/unstable/cli/HelpDoc";
+
+/**
+ * Compact enum-style flag types so one long choice list (`--log-level`'s
+ * nine choices) doesn't widen the description column for every flag.
+ */
+const compactFlagType = (type: string): string => {
+  if (type === "boolean" || type.length <= 24) return type;
+  const bracketed = type.startsWith("<") && type.endsWith(">");
+  const value = bracketed ? type.slice(1, -1) : type;
+  const choices = value.split("|");
+  const compact =
+    choices.length > 2
+      ? `${choices.slice(0, 2).join("|")}|…`
+      : `${value.slice(0, 21)}…`;
+  return bracketed ? `<${compact}>` : compact;
+};
+
+const compactFlag = (flag: FlagDoc): FlagDoc => ({
+  ...flag,
+  type: compactFlagType(flag.type),
+});
+
+const compactDoc = (doc: HelpDoc): HelpDoc => ({
+  ...doc,
+  flags: doc.flags?.map(compactFlag),
+  globalFlags: doc.globalFlags?.map(compactFlag),
+});
+
+/**
+ * Bound every line to the terminal width, breaking at spaces; continuation
+ * lines keep the original indent plus two columns. The default formatter
+ * never wraps, so long descriptions would otherwise run off the terminal.
+ */
+const wrapLines = (text: string, width: number): string =>
+  text
+    .split("\n")
+    .flatMap((line) => {
+      if (line.length <= width) return [line];
+      const continuation = `${line.match(/^\s*/)![0]}  `;
+      const out: string[] = [];
+      let current: string | undefined;
+      for (const word of line.trim().split(/\s+/)) {
+        if (current === undefined) {
+          current = `${line.match(/^\s*/)![0]}${word}`;
+        } else if (current.length + word.length + 1 <= width) {
+          current += ` ${word}`;
+        } else {
+          out.push(current);
+          current = continuation + word;
+        }
+      }
+      if (current !== undefined) out.push(current);
+      return out;
+    })
+    .join("\n");
+
+/**
+ * Help formatter for plain (non-interactive) runs: the default effect/cli
+ * formatter with colors off, enum flag types compacted, and output wrapped
+ * to the terminal width — CI logs, redirected output, and coding agents
+ * get parseable, bounded lines.
+ */
+export const plainCliFormatter = (options: {
+  columns: number;
+}): CliOutput.Formatter => {
+  const columns = Math.max(60, Math.min(options.columns, 120));
+  const fallback = CliOutput.defaultFormatter({ colors: false });
+  return {
+    ...fallback,
+    formatHelpDoc: (doc) =>
+      wrapLines(fallback.formatHelpDoc(compactDoc(doc)), columns),
+  };
+};

package/src/Cli/PropertyDiff.ts

@@ -0,0 +1,229 @@
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { havePropsChanged } from "../Diff.ts";
+import * as Output from "../Output.ts";
+import { isPlainData } from "../Util/data.ts";
+import { stringify } from "yaml";
+
+export type YamlDisplayValue =
+  | string
+  | number
+  | boolean
+  | null
+  | YamlDisplayValue[]
+  | { readonly [key: string]: YamlDisplayValue };
+
+export interface DeclaredPropertyYaml {
+  readonly kind: "create" | "change" | "drift";
+  readonly lines: ReadonlyArray<string>;
+}
+
+const unifiedDriftLines = (
+  expected: YamlDisplayValue,
+  actual: YamlDisplayValue,
+  depth = 0,
+): string[] => {
+  const padding = " ".repeat(depth);
+  if (JSON.stringify(expected) === JSON.stringify(actual)) {
+    return indent(formatYamlLines(expected), depth);
+  }
+  if (
+    expected !== null &&
+    actual !== null &&
+    !Array.isArray(expected) &&
+    !Array.isArray(actual) &&
+    typeof expected === "object" &&
+    typeof actual === "object"
+  ) {
+    const lines: string[] = [];
+    for (const key of [
+      ...new Set([...Object.keys(expected), ...Object.keys(actual)]),
+    ].sort((a, b) => a.localeCompare(b))) {
+      const hasExpected = Object.hasOwn(expected, key);
+      const hasActual = Object.hasOwn(actual, key);
+      const expectedValue = hasExpected ? expected[key]! : UNDEFINED;
+      const actualValue = hasActual ? actual[key]! : UNDEFINED;
+      if (
+        hasExpected &&
+        hasActual &&
+        expectedValue !== null &&
+        actualValue !== null &&
+        !Array.isArray(expectedValue) &&
+        !Array.isArray(actualValue) &&
+        typeof expectedValue === "object" &&
+        typeof actualValue === "object" &&
+        JSON.stringify(expectedValue) !== JSON.stringify(actualValue)
+      ) {
+        lines.push(`${padding}${key}:`);
+        lines.push(...unifiedDriftLines(expectedValue, actualValue, depth + 2));
+      } else if (
+        JSON.stringify(expectedValue) === JSON.stringify(actualValue)
+      ) {
+        lines.push(...indent(formatYamlLines({ [key]: expectedValue }), depth));
+      } else {
+        if (hasExpected) {
+          lines.push(
+            ...indent(formatYamlLines({ [key]: expectedValue }), depth).map(
+              mark("-"),
+            ),
+          );
+        }
+        if (hasActual) {
+          lines.push(
+            ...indent(formatYamlLines({ [key]: actualValue }), depth).map(
+              mark("+"),
+            ),
+          );
+        }
+      }
+    }
+    return lines;
+  }
+  return [
+    ...indent(formatYamlLines(expected), depth).map(mark("-")),
+    ...indent(formatYamlLines(actual), depth).map(mark("+")),
+  ];
+};
+
+const mark = (marker: "-" | "+") => (line: string) => {
+  return `${marker} ${line}`;
+};
+
+export interface YamlChangeMatch {
+  readonly marker: "-" | "+";
+  readonly content: string;
+}
+
+/** Match a `- `/`+ ` change marker emitted by {@link unifiedDriftLines}. */
+export const matchYamlChange = (line: string): YamlChangeMatch | undefined => {
+  const match = line.match(/^([+-]) (.*)$/);
+  return match === null
+    ? undefined
+    : { marker: match[1] as "-" | "+", content: match[2]! };
+};
+
+export interface YamlKeyMatch {
+  readonly indent: string;
+  /** The key including its trailing colon. */
+  readonly key: string;
+  readonly value: string;
+}
+
+/** Match an `indent` + `key:` + rest display-YAML line for colorizing. */
+export const matchYamlKey = (line: string): YamlKeyMatch | undefined => {
+  const match = line.match(/^(\s*)([A-Za-z_][\w .-]*:)(.*)$/);
+  return match === null
+    ? undefined
+    : { indent: match[1]!, key: match[2]!, value: match[3]! };
+};
+
+/** Format the changed cloud attributes carried by a drift-repair plan. */
+export const formatDriftPropertyYaml = (
+  expected: unknown,
+  actual: unknown,
+  missing = false,
+): DeclaredPropertyYaml => {
+  const expectedValue = toYamlDisplayValue(expected);
+  const actualValue = missing ? "(missing)" : toYamlDisplayValue(actual);
+  return {
+    kind: "drift",
+    lines: unifiedDriftLines(expectedValue, actualValue),
+  };
+};
+
+const REDACTED = "(redacted)";
+const KNOWN_AFTER_APPLY = "(known after apply)";
+const COMPUTED = "(computed)";
+const UNDEFINED = "(undefined)";
+const OPAQUE = "(opaque)";
+const CIRCULAR = "(circular)";
+
+/**
+ * Turn arbitrary declared inputs or persisted state into safe, deterministic
+ * plain data for terminal display. Deferred values are described, never run,
+ * and Redacted values are replaced before their contents can reach YAML.
+ */
+export const toYamlDisplayValue = (
+  value: unknown,
+  ancestors: WeakSet<object> = new WeakSet(),
+): YamlDisplayValue => {
+  // Output expressions are Effects too, so this order is security-sensitive.
+  if (Redacted.isRedacted(value)) return REDACTED;
+  if (Output.isExpr(value)) return KNOWN_AFTER_APPLY;
+  if (Effect.isEffect(value) || typeof value === "function") return COMPUTED;
+  if (value === undefined) return UNDEFINED;
+  if (value === null || typeof value === "string") return value;
+  if (typeof value === "boolean" || typeof value === "number") return value;
+  if (typeof value === "bigint") return `${value}n`;
+  if (!isPlainData(value)) return OPAQUE;
+  if (ancestors.has(value)) return CIRCULAR;
+
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return value.map((item) => toYamlDisplayValue(item, ancestors));
+    }
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort((a, b) => a.localeCompare(b))
+        .map((key) => [
+          key,
+          toYamlDisplayValue(
+            (value as Record<string, unknown>)[key],
+            ancestors,
+          ),
+        ]),
+    );
+  } finally {
+    ancestors.delete(value);
+  }
+};
+
+/** Format a value as stable, unadorned YAML lines for terminal renderers. */
+export const formatYamlLines = (value: unknown): string[] => {
+  const yaml = stringify(toYamlDisplayValue(value), {
+    lineWidth: 0,
+    sortMapEntries: true,
+  });
+  return (yaml || `${UNDEFINED}\n`).trimEnd().split("\n");
+};
+
+/**
+ * Build the detailed property document for a plan resource. This compares
+ * persisted declared props to desired declared props; it is not cloud drift.
+ */
+export const formatDeclaredPropertyYaml = (
+  oldProps: unknown,
+  newProps: unknown,
+  action: "create" | "update" | "replace",
+): DeclaredPropertyYaml | undefined => {
+  const desired = newProps ?? {};
+  if (action === "create") {
+    return {
+      kind: "create",
+      lines: ["properties:", ...indent(formatYamlLines(desired))],
+    };
+  }
+  if (
+    !havePropsChanged(
+      (oldProps ?? {}) as Record<string, unknown>,
+      desired as Record<string, unknown>,
+    )
+  ) {
+    return undefined;
+  }
+  return {
+    kind: "change",
+    lines: [
+      "properties:",
+      ...unifiedDriftLines(
+        toYamlDisplayValue(oldProps ?? {}),
+        toYamlDisplayValue(desired),
+        2,
+      ),
+    ],
+  };
+};
+
+const indent = (lines: ReadonlyArray<string>, spaces = 2): string[] =>
+  lines.map((line) => `${" ".repeat(spaces)}${line}`);

package/src/Cli/checkVersion.ts

@@ -9,6 +9,14 @@ import * as HttpClient from "effect/unstable/http/HttpClient";
 
 import { AlchemyContext } from "alchemy/AlchemyContext";
 import packageJson from "../../package.json" with { type: "json" };
+import {
+  ANSI_RESET,
+  ansiFg,
+  colorsEnabled,
+  glyphsFor,
+  theme,
+  unicodeEnabled,
+} from "./CliKit/index.ts";
 
 const NPM_DIST_TAGS_URL =
   "https://registry.npmjs.org/-/package/alchemy/dist-tags";
@@ -173,17 +181,22 @@ export const checkLatestVersion = Effect.gen(function* () {
   if (latest === undefined || compareVersions(latest, current) <= 0) return;
 
   const installCmd =
-    typeof process !== "undefined" && (process as any).versions?.bun
+    typeof process !== "undefined" && process.versions.bun !== undefined
       ? `bun add alchemy@${latest}`
       : `pnpm add alchemy@${latest}`;
-  // Print via the Console service, not Effect.logWarning: TelemetryLive
-  // replaces the default stdout logger with an OTLP-only logger at this
-  // stage of the program, so log output would never reach the terminal.
-  const useColor = process.stderr.isTTY === true;
+  // Print via the Console service, not Effect.logWarning: this is a
+  // user-facing notice, not a log record, so it should reach the terminal
+  // regardless of the installed loggers or the configured log floor.
+  const useColor = colorsEnabled();
+  const glyphs = glyphsFor(unicodeEnabled());
   const message =
     `alchemy ${latest} is available (you're on ${current}). ` +
     `Run \`${installCmd}\` to upgrade.`;
-  yield* Console.warn(useColor ? `\x1b[33m${message}\x1b[0m` : message);
+  yield* Console.warn(
+    useColor
+      ? `${ansiFg(theme.color.warning)}${glyphs.warning} ${message}${ANSI_RESET}`
+      : message,
+  );
 }).pipe(Effect.catch(() => Effect.void));
 
 // Exported for tests.