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

package/src/Cli/components/view/ApprovePlan.tsx

@@ -0,0 +1,101 @@
+/** @jsxImportSource react */
+import { useMemo, useState, type JSX } from "react";
+import {
+  ChoiceGroup,
+  Box,
+  KeyBar,
+  Text,
+  useGlyphs,
+  useKeyGlyphs,
+  useTerminalInput,
+} from "../ui/index.ts";
+import { Screen, theme, type ScreenController } from "../../CliKit/index.ts";
+import type { Plan as AlchemyPlan } from "../../../Plan.ts";
+import { Plan, PlanTree } from "./PlanView.tsx";
+
+export interface ApprovePlanProps {
+  plan: AlchemyPlan;
+  detailed?: boolean;
+  controller: ScreenController<boolean>;
+}
+
+/**
+ * Plan approval prompt: the plan tree followed by an operation-specific
+ * action and Cancel. Escape cancels; Ctrl+C is handled centrally by the
+ * screen runner.
+ */
+export function ApprovePlan(props: ApprovePlanProps): JSX.Element {
+  const { plan, detailed = false, controller } = props;
+  // Destruction is the risky path: require an explicit move to Destroy before
+  // Enter can remove or orphan resources. Deploy approvals remain action-first.
+  const [approved, setApproved] = useState(!plan.destroy);
+  const action = plan.destroy ? "Destroy" : "Deploy";
+  const glyphs = useGlyphs();
+  const keys = useKeyGlyphs();
+  const tree = useMemo(
+    () =>
+      new PlanTree(plan, {
+        detailed,
+        mode: "review",
+        label: action,
+      }),
+    [plan, detailed, action],
+  );
+  const complete = (answer: boolean) => {
+    const verdict = (
+      <Text color={answer ? theme.color.success : theme.color.danger}>
+        {answer ? glyphs.success : glyphs.error} {answer ? action : "Cancelled"}
+      </Text>
+    );
+    // On approval the plan disappears — the apply progress that follows
+    // shows every row again. A declined plan stays on screen (complete,
+    // unscrolled) so the user can review what they just turned down.
+    if (!answer) tree.setViewport("full");
+    const summary = answer ? (
+      verdict
+    ) : (
+      <Box flexDirection="column">
+        <Plan tree={tree} />
+        {verdict}
+      </Box>
+    );
+    controller.submit(answer, summary);
+  };
+
+  useTerminalInput((input, key) => {
+    if (key.enter) complete(approved);
+    else if (key.escape) controller.cancel();
+    else if (key.ctrl || key.meta) return;
+    else if (input.toLowerCase() === "y") complete(true);
+    else if (input.toLowerCase() === "n") complete(false);
+  });
+
+  const prompt = (
+    <Box flexDirection="column">
+      <Text bold>{action}?</Text>
+      <ChoiceGroup
+        value={approved}
+        choices={[
+          { value: true, label: action },
+          { value: false, label: "Cancel" },
+        ]}
+        onChange={setApproved}
+      />
+      <KeyBar
+        keys={[
+          [keys.upDown, "scroll plan"],
+          [keys.leftRight, "choose"],
+          [keys.enter, "confirm"],
+          [keys.escape, "cancel"],
+        ]}
+      />
+    </Box>
+  );
+
+  return <Plan tree={tree} footer={prompt} />;
+}
+
+export const approvePlanScreen = (plan: AlchemyPlan, detailed = false) =>
+  Screen.make<boolean>("plan approval", (controller) => (
+    <ApprovePlan plan={plan} detailed={detailed} controller={controller} />
+  ));

package/src/Cli/components/view/Help.tsx

@@ -0,0 +1,381 @@
+/** @jsxImportSource react */
+/** Branded help screens + the CliOutput formatter that renders them. */
+import { stripVTControlCharacters } from "node:util";
+import * as Option from "effect/Option";
+import * as CliOutput from "effect/unstable/cli/CliOutput";
+import type { HelpDoc } from "effect/unstable/cli/HelpDoc";
+import { Box, Heading, Text, useGlyphs } from "../ui/index.ts";
+import type { JSX } from "react";
+import packageJson from "../../../../package.json" with { type: "json" };
+import type { CliKit } from "../../CliKit/CliKit.ts";
+import {
+  ANSI_BOLD,
+  ANSI_DIM,
+  ansiFg,
+  glyphsFor,
+  paint,
+  truncate,
+  theme,
+} from "../../CliKit/index.ts";
+import { Logo } from "./Logo.tsx";
+
+const commandLabel = (command: {
+  readonly name: string;
+  readonly alias?: string | undefined;
+}) => (command.alias ? `${command.name}, ${command.alias}` : command.name);
+
+/** Shell-like highlighting shared by usage lines, examples, and help hints. */
+function CommandText({ command }: { readonly command: string }): JSX.Element {
+  const tokens = command.match(
+    /\s+|"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s]+/g,
+  ) ?? [command];
+  let word = 0;
+  let valueAfterFlag = false;
+
+  return (
+    <Text>
+      {tokens.map((token, index) => {
+        if (/^\s+$/.test(token)) return token;
+
+        const currentWord = word++;
+        const isFlag = token.startsWith("-");
+        const isPlaceholder =
+          (token.startsWith("<") && token.endsWith(">")) ||
+          (token.startsWith("[") && token.endsWith("]"));
+        const isQuoted =
+          (token.startsWith('"') && token.endsWith('"')) ||
+          (token.startsWith("'") && token.endsWith("'"));
+        const isValue = valueAfterFlag || isQuoted;
+        valueAfterFlag = isFlag;
+
+        return (
+          <Text
+            key={`${index}:${token}`}
+            bold={currentWord <= 1 || isFlag}
+            color={
+              currentWord === 0
+                ? theme.color.accent
+                : isFlag
+                  ? theme.color.info
+                  : isPlaceholder
+                    ? theme.color.warning
+                    : isValue
+                      ? theme.color.success
+                      : currentWord === 1
+                        ? theme.color.accentBright
+                        : undefined
+            }
+          >
+            {token}
+          </Text>
+        );
+      })}
+    </Text>
+  );
+}
+
+/** One aligned help row: fixed-width bold label cell + description. */
+type RowProps = {
+  label: JSX.Element | string;
+  description: string;
+  width: number;
+};
+
+function Row({ label, description, width }: RowProps) {
+  return (
+    <Box paddingLeft={2}>
+      <Box width={width} flexShrink={0}>
+        {typeof label === "string" ? (
+          <Text bold tone="emphasis">
+            {label}
+          </Text>
+        ) : (
+          label
+        )}
+      </Box>
+      <Text>{description}</Text>
+    </Box>
+  );
+}
+
+function BrandLine(): JSX.Element {
+  const glyphs = useGlyphs();
+  return (
+    <Text>
+      <Text tone="brand">{glyphs.selected}</Text>{" "}
+      <Text bold tone="emphasis">
+        alchemy
+      </Text>{" "}
+      <Text tone="muted">— Infrastructure as Effects</Text>
+    </Text>
+  );
+}
+
+/**
+ * Branded help for every command. The root gets a brand header and shows
+ * only `--help`/`--version` (as OPTIONS); subcommands list all global flags.
+ */
+type SubHelpProps = {
+  doc: HelpDoc;
+  root?: boolean;
+};
+
+function SubHelp({ doc, root = false }: SubHelpProps): JSX.Element {
+  const commands = doc.subcommands?.flatMap((group) => group.commands) ?? [];
+  const flags = doc.flags ?? [];
+  const globalFlags = root
+    ? (doc.globalFlags ?? []).filter(
+        (flag) => flag.name === "help" || flag.name === "version",
+      )
+    : (doc.globalFlags ?? []);
+  const args = doc.args ?? [];
+
+  const flagLabel = (flag: (typeof flags)[number]) => {
+    const aliases =
+      flag.aliases.length > 0 ? `, ${flag.aliases.join(", ")}` : "";
+    return `--${flag.name}${aliases}`;
+  };
+  const argLabel = (arg: (typeof args)[number]) =>
+    arg.required ? `<${arg.name}>` : `[${arg.name}]`;
+  // width from labels only — enum types (--log-level's choice list) would
+  // otherwise blow the column out; long types truncate inside the cell
+  const nameWidth =
+    Math.min(
+      30,
+      Math.max(
+        12,
+        ...commands.map((c) => commandLabel(c).length),
+        ...[...flags, ...globalFlags].map((f) => flagLabel(f).length),
+        ...args.map((a) => argLabel(a).length),
+      ),
+    ) + 4;
+
+  type FlagRowProps = { readonly flag: (typeof flags)[number] };
+
+  function FlagRow({ flag }: FlagRowProps) {
+    const label = flagLabel(flag);
+    const typeRoom = nameWidth - label.length - 2;
+    return (
+      <Row
+        width={nameWidth}
+        description={Option.getOrElse(flag.description, () => "")}
+        label={
+          <Text>
+            <Text bold color={theme.color.info}>
+              --{flag.name}
+            </Text>
+            {flag.aliases.map((alias) => (
+              <Text key={alias} color={theme.color.info}>
+                , {alias}
+              </Text>
+            ))}
+            {flag.type === "boolean" || typeRoom < 8 ? null : (
+              <Text color={theme.color.warning}>
+                {" "}
+                {truncate(flag.type, typeRoom)}
+              </Text>
+            )}
+          </Text>
+        }
+      />
+    );
+  }
+
+  return (
+    <Box flexDirection="column" flexShrink={root ? 0 : 1}>
+      {root ? <BrandLine /> : null}
+      {doc.description === "" ? null : (
+        <Box marginTop={root ? 1 : 0}>
+          <Text>{doc.description}</Text>
+        </Box>
+      )}
+      <Box marginTop={doc.description === "" && !root ? 0 : 1}>
+        <Heading glyph={false}>USAGE</Heading>
+      </Box>
+      <Text>
+        {"  "}
+        <Text tone="brand">$</Text> <CommandText command={doc.usage} />
+      </Text>
+      {args.length === 0 ? null : (
+        <>
+          <Box marginTop={1}>
+            <Heading glyph={false}>ARGUMENTS</Heading>
+          </Box>
+          {args.map((arg) => (
+            <Row
+              key={arg.name}
+              width={nameWidth}
+              label={
+                <Text bold color={theme.color.warning}>
+                  {argLabel(arg)}
+                </Text>
+              }
+              description={Option.getOrElse(arg.description, () => "")}
+            />
+          ))}
+        </>
+      )}
+      {commands.length === 0 ? null : (
+        <>
+          <Box marginTop={1}>
+            <Heading glyph={false}>COMMANDS</Heading>
+          </Box>
+          {commands.map((command) => (
+            <Row
+              key={command.name}
+              width={nameWidth}
+              label={
+                <Text>
+                  <Text bold color={theme.color.accentBright}>
+                    {command.name}
+                  </Text>
+                  {command.alias === undefined ? null : (
+                    <Text color={theme.color.info}>, {command.alias}</Text>
+                  )}
+                </Text>
+              }
+              description={command.description || ""}
+            />
+          ))}
+        </>
+      )}
+      {flags.length === 0 ? null : (
+        <>
+          <Box marginTop={1}>
+            <Heading glyph={false}>FLAGS</Heading>
+          </Box>
+          {flags.map((flag) => (
+            <FlagRow key={flag.name} flag={flag} />
+          ))}
+        </>
+      )}
+      {globalFlags.length === 0 ? null : (
+        <>
+          <Box marginTop={1}>
+            <Heading glyph={false}>{root ? "OPTIONS" : "GLOBAL FLAGS"}</Heading>
+          </Box>
+          {globalFlags.map((flag) => (
+            <FlagRow key={flag.name} flag={flag} />
+          ))}
+        </>
+      )}
+      {doc.examples === undefined || doc.examples.length === 0 ? null : (
+        <>
+          <Box marginTop={1}>
+            <Heading glyph={false}>EXAMPLES</Heading>
+          </Box>
+          {doc.examples.map((example) => (
+            <Text key={example.command}>
+              {"  "}
+              <Text tone="brand">$</Text>{" "}
+              <CommandText command={example.command} />
+            </Text>
+          ))}
+        </>
+      )}
+      {commands.length === 0 ? null : (
+        <Box marginTop={1}>
+          <Text>
+            <Text color={theme.color.muted}>Run '</Text>
+            <CommandText
+              command={`${doc.usage.replace(/\s*<subcommand>.*$/, "")} <command> --help`}
+            />
+            <Text color={theme.color.muted}>
+              ' for more information on a command.
+            </Text>
+          </Text>
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+const formatSubHelp = (cli: CliKit["Service"], doc: HelpDoc) => {
+  const termCols = cli.terminal.columns;
+  return cli.output.format(
+    <Box width={termCols}>
+      <SubHelp doc={doc} />
+    </Box>,
+    { columns: termCols },
+  );
+};
+
+/** Hide the logo entirely when it can't be at least this many columns wide. */
+const MIN_LOGO_COLS = 20;
+
+const formatRootHelp = (cli: CliKit["Service"], doc: HelpDoc) => {
+  const termCols = cli.terminal.columns;
+
+  // First pass: render the text alone to measure its exact footprint (post
+  // ANSI codes and wrapping), then size the logo into the leftover space.
+  const text = cli.output.format(
+    <Box width={termCols}>
+      <SubHelp doc={doc} root />
+    </Box>,
+    { columns: termCols },
+  );
+
+  // The braille logo is mojibake without Unicode support.
+  if (!cli.terminal.unicode) return text;
+
+  const lines = text.split("\n");
+  const textWidth = Math.max(
+    ...lines.map((line) => stripVTControlCharacters(line).trimEnd().length),
+  );
+  const textHeight = lines.length;
+
+  // Fill the free space beside the text: a logo of C columns is C/2 rows
+  // tall (braille cell is 1:2). Reserve two rows for the wordmark caption.
+  const logoCols = Math.min(termCols - textWidth - 2, (textHeight - 2) * 2);
+
+  if (logoCols < MIN_LOGO_COLS) return text;
+
+  return cli.output.format(
+    <Box flexDirection="row" width={termCols}>
+      <SubHelp doc={doc} root />
+      <Box
+        flexGrow={1}
+        flexDirection="column"
+        justifyContent="center"
+        alignItems="center"
+      >
+        <Logo cols={logoCols} />
+        <Box marginTop={1}>
+          <Text>
+            <Text bold color={theme.color.accent}>
+              ALCHEMY
+            </Text>{" "}
+            <Text tone="muted">v{packageJson.version}</Text>
+          </Text>
+        </Box>
+      </Box>
+    </Box>,
+    { columns: termCols },
+  );
+};
+
+export const brandedCliFormatter = (
+  cli: CliKit["Service"],
+): CliOutput.Formatter => {
+  const fallback = CliOutput.defaultFormatter();
+  const glyphs = glyphsFor(cli.terminal.unicode);
+  const formatErrorLine = (message: string) =>
+    `${paint(ansiFg(theme.color.danger), `${glyphs.error} error:`)} ${message}`;
+  return {
+    ...fallback,
+    formatHelpDoc: (doc) =>
+      doc.usage.startsWith("alchemy <subcommand>")
+        ? formatRootHelp(cli, doc)
+        : formatSubHelp(cli, doc),
+    formatVersion: (name, version) =>
+      `${paint(ansiFg(theme.color.brand), glyphs.selected)} ${paint(ANSI_BOLD, name)} ${paint(ANSI_DIM, `v${version}`)}`,
+    formatError: (error) => `\n${formatErrorLine(error.message)}`,
+    formatErrors: (errors) => {
+      if (errors.length === 0) return "";
+      if (errors.length === 1) return `\n${formatErrorLine(errors[0].message)}`;
+      return `\n${formatErrorLine(`${errors.length} problems`)}\n${errors
+        .map((error) => `  ${paint(ANSI_DIM, glyphs.bullet)} ${error.message}`)
+        .join("\n")}`;
+    },
+  };
+};

package/src/Cli/components/view/Logo.tsx

@@ -0,0 +1,168 @@
+/** @jsxImportSource react */
+/**
+ * The yantra logo, rasterized at runtime. Geometry mirrors
+ * website/src/brand/yantra.ts (the brand's source of truth): a downward
+ * equilateral triangle inscribed in a circle, bindu at the center. Rendered
+ * as braille dots (2x4 subpixels per cell) via signed distance functions, so
+ * it scales to any column width.
+ */
+import { Box, Text } from "../ui/index.ts";
+import { useMemo, type JSX } from "react";
+import { theme } from "../../CliKit/index.ts";
+
+const CENTER = 12;
+const CIRCLE_R = 9.5;
+const BINDU_R = 1.1;
+const DOT_THRESHOLD = 0.35;
+// stroke thickness in braille subpixels, independent of logo size — keeps the
+// outline delicate instead of thickening into solid slabs as the logo grows
+const STROKE_SUBPIXELS = 2.5;
+
+const trianglePoints = (
+  strokeW: number,
+): ReadonlyArray<readonly [number, number]> => {
+  const triR = CIRCLE_R - strokeW / 4;
+  const triDx = triR * Math.cos(Math.PI / 6);
+  const triTopY = CENTER - triR * Math.sin(Math.PI / 6);
+  const triApexY = CENTER + triR;
+  return [
+    [CENTER, triApexY],
+    [CENTER - triDx, triTopY],
+    [CENTER + triDx, triTopY],
+  ];
+};
+
+const sdCircleRing = (x: number, y: number, strokeW: number) =>
+  Math.abs(Math.hypot(x - CENTER, y - CENTER) - CIRCLE_R) - strokeW / 2;
+
+const sdSegment = (
+  px: number,
+  py: number,
+  ax: number,
+  ay: number,
+  bx: number,
+  by: number,
+) => {
+  const abx = bx - ax;
+  const aby = by - ay;
+  const apx = px - ax;
+  const apy = py - ay;
+  const t = Math.max(
+    0,
+    Math.min(1, (apx * abx + apy * aby) / (abx * abx + aby * aby)),
+  );
+  return Math.hypot(apx - t * abx, apy - t * aby);
+};
+
+const sdTriangle = (
+  x: number,
+  y: number,
+  pts: ReadonlyArray<readonly [number, number]>,
+  strokeW: number,
+) => {
+  let d = Infinity;
+  for (let i = 0; i < 3; i++) {
+    const [ax, ay] = pts[i];
+    const [bx, by] = pts[(i + 1) % 3];
+    d = Math.min(d, sdSegment(x, y, ax, ay, bx, by));
+  }
+  return d - strokeW / 2;
+};
+
+const sdBindu = (x: number, y: number) =>
+  Math.hypot(x - CENTER, y - CENTER) - BINDU_R;
+
+// braille dot bit per (row 0-3, column 0-1) subpixel
+const BRAILLE_BITS = [
+  [0x01, 0x08],
+  [0x02, 0x10],
+  [0x04, 0x20],
+  [0x40, 0x80],
+] as const;
+
+interface LogoRun {
+  text: string;
+  color?: string;
+}
+
+const rasterizeLogo = (cols: number): LogoRun[][] => {
+  const width = cols * 2; // subpixel grid, square (2 wide x 4 tall per cell)
+  const rows = Math.ceil(width / 4);
+  const scale = 24 / width;
+  const strokeW = STROKE_SUBPIXELS * scale;
+  const triPts = trianglePoints(strokeW);
+  const lines: LogoRun[][] = [];
+  for (let r = 0; r < rows; r++) {
+    const runs: LogoRun[] = [];
+    const push = (text: string, color?: string) => {
+      const last = runs[runs.length - 1];
+      if (last && last.color === color) last.text += text;
+      else runs.push({ text, color });
+    };
+    for (let c = 0; c < cols; c++) {
+      let bits = 0;
+      let strokeSum = 0;
+      let binduSum = 0;
+      for (let sy = 0; sy < 4; sy++) {
+        for (let sx = 0; sx < 2; sx++) {
+          const x = (c * 2 + sx + 0.5) * scale;
+          const y = (r * 4 + sy + 0.5) * scale;
+          const dStroke = Math.min(
+            sdCircleRing(x, y, strokeW),
+            sdTriangle(x, y, triPts, strokeW),
+          );
+          const strokeCov = Math.min(1, Math.max(0, 0.5 - dStroke / scale));
+          const binduCov = Math.min(
+            1,
+            Math.max(0, 0.5 - sdBindu(x, y) / scale),
+          );
+          if (Math.max(strokeCov, binduCov) > DOT_THRESHOLD) {
+            bits |= BRAILLE_BITS[sy][sx];
+            strokeSum += strokeCov;
+            binduSum += binduCov;
+          }
+        }
+      }
+      if (bits === 0) push(" ");
+      else {
+        push(
+          String.fromCharCode(0x2800 + bits),
+          binduSum > strokeSum ? theme.color.brand : theme.color.accent,
+        );
+      }
+    }
+    // drop trailing whitespace runs
+    while (runs.length > 0) {
+      const last = runs[runs.length - 1];
+      if (last.color !== undefined || last.text.trim() !== "") break;
+      runs.pop();
+    }
+    lines.push(runs);
+  }
+  while (lines.length > 0 && lines[0].length === 0) lines.shift();
+  while (lines.length > 0 && lines[lines.length - 1].length === 0) lines.pop();
+  return lines;
+};
+
+// Braille rasterization is mojibake on non-Unicode terminals — the help
+// formatter skips mounting the logo entirely when Unicode is unavailable.
+type LogoProps = { cols: number };
+
+export function Logo({ cols }: LogoProps): JSX.Element | null {
+  const lines = useMemo(() => rasterizeLogo(cols), [cols]);
+  return (
+    <Box flexDirection="column" flexShrink={0}>
+      {lines.map((runs, i) => (
+        <Text key={i}>
+          {runs.length === 0
+            ? " "
+            : runs.map((run, j) => (
+                <Text key={j} color={run.color}>
+                  {run.text}
+                </Text>
+              ))}
+        </Text>
+      ))}
+    </Box>
+  );
+}