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

package/src/Cli/CliKit/CliKit.ts

@@ -0,0 +1,183 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+import type { TerminalProgressState } from "@alchemy.run/sigil/ansi";
+import type { NonInteractiveTerminal } from "../../Interaction.ts";
+import type {
+  ConfirmOptions,
+  CycleSelectOptions,
+  AwaitExternalOptions,
+  MessageOptions,
+  InteractionError,
+  LiveViewHandle,
+  LiveViewOptions,
+  MenuOptions,
+  MultiSelectOptions,
+  PasswordInputOptions,
+  ProgressHandle,
+  ProgressOptions,
+  RenderOptions,
+  Screen,
+  SelectOptions,
+  CliKitCapabilities,
+  TextInputOptions,
+  View,
+} from "../components/types.ts";
+
+/** The sole injected owner of terminal rendering and input for a CLI process. */
+export class CliKit extends Context.Service<
+  CliKit,
+  {
+    readonly terminal: CliKitCapabilities;
+
+    /** Terminal-emulator progress displayed outside the rendered TUI. */
+    readonly nativeProgress: {
+      readonly set: (
+        state: TerminalProgressState,
+        value?: number,
+      ) => Effect.Effect<void>;
+    };
+
+    readonly output: {
+      /** Append a completed layout to terminal scrollback/output. */
+      readonly print: (
+        view: View,
+        options?: RenderOptions,
+      ) => Effect.Effect<void>;
+
+      /** Render a layout without writing it. Useful for help, logs and snapshots. */
+      readonly format: (view: View, options?: RenderOptions) => string;
+
+      /** Effect form of `format`, useful when composing CLI programs. */
+      readonly render: (
+        view: View,
+        options?: RenderOptions,
+      ) => Effect.Effect<string>;
+
+      /** Append an arbitrary visual layout. Prefer the semantic methods for logs. */
+      readonly info: (message: string | MessageOptions) => Effect.Effect<void>;
+      readonly success: (
+        message: string | MessageOptions,
+      ) => Effect.Effect<void>;
+      readonly warning: (
+        message: string | MessageOptions,
+      ) => Effect.Effect<void>;
+      readonly error: (message: string | MessageOptions) => Effect.Effect<void>;
+    };
+
+    readonly prompt: {
+      readonly text: (
+        options: TextInputOptions,
+      ) => Effect.Effect<string, InteractionError>;
+      readonly password: (
+        options: PasswordInputOptions,
+      ) => Effect.Effect<string, InteractionError>;
+      readonly confirm: (
+        options: ConfirmOptions,
+      ) => Effect.Effect<boolean, InteractionError>;
+      readonly select: <Value>(
+        options: SelectOptions<Value>,
+      ) => Effect.Effect<Value, InteractionError>;
+      readonly multiSelect: <Value>(
+        options: MultiSelectOptions<Value>,
+      ) => Effect.Effect<ReadonlyArray<Value>, InteractionError>;
+      readonly cycle: <State>(
+        options: CycleSelectOptions<State>,
+      ) => Effect.Effect<ReadonlyArray<State>, InteractionError>;
+      readonly awaitExternal: (
+        options: AwaitExternalOptions,
+      ) => Effect.Effect<string, InteractionError>;
+
+      /**
+       * Display an application menu. Each invocation replaces the current app
+       * flow, so looping back to a menu clears any prompts shown since the last
+       * selection.
+       */
+      readonly menu: <Value>(
+        options: MenuOptions<Value>,
+      ) => Effect.Effect<Value, InteractionError>;
+
+      /** Run an arbitrary interactive screen in the service's single live region. */
+      readonly custom: <Value>(
+        screen: Screen<Value>,
+      ) => Effect.Effect<Value, InteractionError>;
+    };
+
+    /** Run a sequence of prompts as one owned interaction. */
+    readonly wizard: <A, E, R>(
+      effect: Effect.Effect<A, E, R>,
+    ) => Effect.Effect<A, E | NonInteractiveTerminal, R>;
+
+    /**
+     * Keep one renderer alive while an Effect drives menus, screens and prompt
+     * flows. The application is cleared and the renderer exits when it settles.
+     */
+    readonly application: <A, E, R>(
+      effect: Effect.Effect<A, E, R>,
+    ) => Effect.Effect<A, E | NonInteractiveTerminal, R>;
+
+    readonly live: {
+      /**
+       * Add a mutable row to the live region. The handle is idempotent, and
+       * the enclosing Scope closes it as a backstop so interruption can never
+       * leave an orphaned row keeping the renderer mounted.
+       */
+      readonly progress: (
+        options: ProgressOptions,
+      ) => Effect.Effect<ProgressHandle, never, Scope.Scope>;
+      /**
+       * Mount a live layout while the scope is open. The view is immutable —
+       * dynamic content flows through a caller-owned store (`LiveStore` +
+       * `useLiveStore`) that the view's component subscribes to.
+       */
+      readonly open: (
+        view: View,
+        options?: LiveViewOptions,
+      ) => Effect.Effect<LiveViewHandle, never, Scope.Scope>;
+    };
+
+    /** Run work behind a progress row and collapse it to a final status line. */
+    readonly task: <A, E, R>(
+      options: ProgressOptions,
+      effect: Effect.Effect<A, E, R>,
+    ) => Effect.Effect<A, E, R>;
+  }
+>()("Alchemy::CliKit") {}
+
+/** Effectful service accessors for code that must defer acquisition to use time. */
+export const accessors = {
+  output: {
+    info: (message: string | MessageOptions) =>
+      Effect.flatMap(CliKit, (service) => service.output.info(message)),
+    success: (message: string | MessageOptions) =>
+      Effect.flatMap(CliKit, (service) => service.output.success(message)),
+    warning: (message: string | MessageOptions) =>
+      Effect.flatMap(CliKit, (service) => service.output.warning(message)),
+    error: (message: string | MessageOptions) =>
+      Effect.flatMap(CliKit, (service) => service.output.error(message)),
+  },
+  prompt: {
+    text: (options: TextInputOptions) =>
+      Effect.flatMap(CliKit, (service) => service.prompt.text(options)),
+    password: (options: PasswordInputOptions) =>
+      Effect.flatMap(CliKit, (service) => service.prompt.password(options)),
+    confirm: (options: ConfirmOptions) =>
+      Effect.flatMap(CliKit, (service) => service.prompt.confirm(options)),
+    select: <Value>(options: SelectOptions<Value>) =>
+      Effect.flatMap(CliKit, (service) => service.prompt.select(options)),
+    multiSelect: <Value>(options: MultiSelectOptions<Value>) =>
+      Effect.flatMap(CliKit, (service) => service.prompt.multiSelect(options)),
+  },
+};
+
+export const ApplicationPresentation = Context.Reference<
+  "inline" | "alternate"
+>("Alchemy::CliKit/ApplicationPresentation", { defaultValue: () => "inline" });
+
+/** Pipeable presentation modifiers for {@link CliKit.application}. */
+export const Application = {
+  alternate: <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+    effect.pipe(
+      Effect.provideService(ApplicationPresentation, "alternate" as const),
+    ),
+};

package/src/Cli/CliKit/index.ts

@@ -0,0 +1,50 @@
+export { accessors, Application, CliKit } from "./CliKit.ts";
+export { layer } from "./layer.ts";
+export { CliKitInteraction } from "./interaction.ts";
+export { openUrl } from "../../Interaction.ts";
+export {
+  BrowserOpenFailed,
+  NonInteractiveTerminal,
+  TerminalCancelled,
+} from "../../Interaction.ts";
+export {
+  glyphsFor,
+  spinnerFramesFor,
+  theme,
+  type GlyphName,
+} from "../../Util/Theme.ts";
+export {
+  ANSI_BOLD,
+  ANSI_DIM,
+  ANSI_RESET,
+  ansiFg,
+  colorsEnabled,
+  paint,
+  pipedColorEnv,
+  truncate,
+  unicodeEnabled,
+} from "../../Util/Terminal.ts";
+export {
+  Screen,
+  type Choice,
+  type AwaitExternalOptions,
+  type ConfirmOptions,
+  type CycleChoice,
+  type CycleSelectOptions,
+  type InteractionError,
+  type LiveViewHandle,
+  type LiveViewOptions,
+  type MenuOptions,
+  type MessageOptions,
+  type MultiSelectOptions,
+  type PasswordInputOptions,
+  type ProgressHandle,
+  type ProgressOptions,
+  type RenderOptions,
+  type ScreenController,
+  type SelectOptions,
+  type CliKitCapabilities,
+  type CliKitOptions,
+  type TextInputOptions,
+  type View,
+} from "../components/types.ts";

package/src/Cli/CliKit/interaction.ts

@@ -0,0 +1,19 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { Interaction } from "../../Interaction.ts";
+import { CliKit } from "./CliKit.ts";
+
+/**
+ * The CLI's implementation of the engine's {@link Interaction} capability,
+ * backed by the full CliKit terminal runtime: messages and `task` render
+ * through the live renderer, prompts run as real interactive screens.
+ * Provided by the CLI entrypoints next to `CliKit.layer()`; every other
+ * process uses `Interaction.layerNonInteractive` (or nothing at all —
+ * children have no interaction capability in their graphs).
+ */
+export const CliKitInteraction = Layer.effect(
+  Interaction,
+  // CliKit's surface is a structural superset of Interaction's — the
+  // terminal service IS the CLI's Interaction implementation.
+  Effect.map(CliKit, (cli): Interaction["Service"] => cli),
+);

package/src/Cli/CliKit/layer.ts

@@ -0,0 +1,50 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { detectCapabilities } from "@alchemy.run/sigil/capabilities";
+import { isNonInteractive } from "../../Util/interactive.ts";
+import { CliKit } from "./CliKit.ts";
+import type { CliKitCapabilities, CliKitOptions } from "../components/types.ts";
+
+export const resolveCapabilities = (
+  options: CliKitOptions,
+): CliKitCapabilities => {
+  const stdout = options.stdout ?? process.stdout;
+  const stdin = options.stdin ?? process.stdin;
+  const detected = detectCapabilities({ stdout });
+  const input =
+    options.input ??
+    (stdin.isTTY === true && stdout.isTTY === true && !isNonInteractive());
+  return {
+    input,
+    columns: detected.size.columns,
+    rows: detected.size.rows,
+    colors: options.colors ?? detected.supports.color,
+    unicode: options.unicode ?? detected.supports.unicode,
+    alternateScreen: detected.supports.alternateScreen,
+  };
+};
+
+// One shared import promise per process. Concurrent dynamic imports of the
+// same module (e.g. two test files building this layer at once) can race in
+// bun and hand one caller a partially-evaluated namespace, which throws a
+// TDZ ReferenceError on `makeRuntime`; funneling every build through a
+// single import() sidesteps the race.
+let sigilRuntime:
+  | Promise<typeof import("../components/view/Runtime.tsx")>
+  | undefined;
+const loadSigilRuntime = () =>
+  (sigilRuntime ??= import("../components/view/Runtime.tsx"));
+
+/** Provides one terminal runtime for the enclosing scope. */
+export const layer = (options: CliKitOptions = {}) =>
+  Layer.effect(
+    CliKit,
+    Effect.acquireRelease(
+      Effect.promise(async () => {
+        const capabilities = resolveCapabilities(options);
+        const { makeRuntime } = await loadSigilRuntime();
+        return makeRuntime(options, capabilities);
+      }),
+      ({ dispose }) => Effect.promise(dispose),
+    ).pipe(Effect.map(({ service }) => service)),
+  );

package/src/Cli/DevOptions.ts

@@ -0,0 +1,19 @@
+import * as Schema from "effect/Schema";
+
+/** Wire format passed from the `alchemy dev` supervisor to its exec child. */
+export const DevOptions = Schema.Struct({
+  main: Schema.String,
+  stage: Schema.String,
+  envFile: Schema.OptionFromOptional(Schema.String),
+  profile: Schema.optional(Schema.String),
+  force: Schema.Boolean,
+});
+
+export type DevOptions = typeof DevOptions.Type;
+
+/**
+ * Exit status the exec child uses to ask the supervisor for a fresh process.
+ * Bun cannot evict evaluated modules, so a stack-graph change under Bun tears
+ * the generation down and exits with this code instead of reloading in place.
+ */
+export const DEV_RELOAD_EXIT_CODE = 75;

package/src/Cli/Format.ts

@@ -0,0 +1,31 @@
+import { ansiFg, theme } from "./CliKit/index.ts";
+
+/** `450ms` under a second, `1.2s` at or above — shared by every renderer. */
+export const formatElapsed = (ms: number): string =>
+  ms < 1000 ? `${Math.max(0, Math.round(ms))}ms` : `${(ms / 1000).toFixed(1)}s`;
+
+export const TAIL_COLORS = [
+  ansiFg(theme.color.accent),
+  ansiFg(theme.color.info),
+  ansiFg(theme.color.danger),
+  ansiFg(theme.color.warning),
+  ansiFg(theme.color.accentBright),
+  ansiFg(theme.color.muted),
+  ansiFg(theme.color.accentMuted),
+  ansiFg(theme.color.success),
+];
+
+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((part) => part.type === "timeZoneName")?.value ?? "";
+  return `${y}-${mo}-${d} ${h}:${mi}:${s}.${ms} ${tz}`;
+};

package/src/Cli/GlobalLog.ts

@@ -0,0 +1,147 @@
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Duration from "effect/Duration";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as LogLevel from "effect/LogLevel";
+import * as Option from "effect/Option";
+import { Path } from "effect/Path";
+import { MinimumLogLevel } from "effect/References";
+import { rootDir } from "../Auth/Paths.ts";
+import packageJson from "../../package.json" with { type: "json" };
+import { makePlainConsoleSink } from "../Util/ConsoleSink.ts";
+
+/** Logs older than this are pruned (by mtime) on CLI start. */
+const MAX_LOG_AGE = Duration.days(7);
+
+/** Same spellings `GlobalFlag.LogLevel` accepts, so the two never disagree. */
+const logLevelChoices: Record<string, LogLevel.LogLevel> = {
+  all: "All",
+  trace: "Trace",
+  debug: "Debug",
+  info: "Info",
+  warn: "Warn",
+  warning: "Warn",
+  error: "Error",
+  fatal: "Fatal",
+  none: "None",
+};
+
+/**
+ * The console keeps its usual Info+ noise floor by default; everything below
+ * it exists only for the run log, so support requests can start with "attach
+ * the file from ~/.alchemy/logs". An explicit `--log-level` lowers the floor
+ * for that run so `--log-level debug` actually puts debug records on the
+ * terminal (#1231) — the run log captures Debug regardless.
+ *
+ * Read from argv rather than `GlobalFlag.LogLevel` because the console logger
+ * is installed while the service layers are built, before the parser has
+ * produced flag values (same reason `--no-input` is an argv scan). Only the
+ * segment before a `--` separator is inspected; an unrecognised value falls
+ * back to Info and is left for the parser to reject.
+ */
+export const consoleLogFloor = (
+  argv: ReadonlyArray<string>,
+): LogLevel.LogLevel => {
+  const separator = argv.indexOf("--");
+  const flagArgs = separator === -1 ? argv : argv.slice(0, separator);
+  let floor: LogLevel.LogLevel = "Info";
+  for (let i = 0; i < flagArgs.length; i++) {
+    const arg = flagArgs[i]!;
+    const value =
+      arg === "--log-level"
+        ? flagArgs[i + 1]
+        : arg.startsWith("--log-level=")
+          ? arg.slice("--log-level=".length)
+          : undefined;
+    if (value === undefined) continue;
+    floor = logLevelChoices[value.toLowerCase()] ?? floor;
+  }
+  return floor;
+};
+
+/** Terminal sink: forwards records at or above `floor` to `sink`. */
+export const makeConsoleLogger = (
+  floor: LogLevel.LogLevel,
+  sink: Logger.Logger<unknown, void> = makePlainConsoleSink(),
+) =>
+  Logger.make<unknown, void>((options) => {
+    if (LogLevel.isGreaterThanOrEqualTo(options.logLevel, floor)) {
+      sink.log(options);
+    }
+  });
+
+/** Shared terminal logger for CLI entrypoints that do not need a run file. */
+export const ConsoleLogLive = Layer.mergeAll(
+  Logger.layer([makeConsoleLogger(consoleLogFloor(process.argv.slice(2)))]),
+  Layer.succeed(MinimumLogLevel, "Debug"),
+);
+
+/** Drops everything — the fallback when the log file cannot be opened. */
+const noopLogger = Logger.make<unknown, void>(() => {});
+
+/**
+ * Debug run log for the whole CLI under `~/.alchemy/logs` (relocated by
+ * `ALCHEMY_HOME` together with the rest of the auth state). Every run writes
+ * `{timestamp}-pid{pid}.log` in logfmt at Debug level — profile/auth flows
+ * and command failures record their full causes there even though the
+ * terminal only shows the friendly message. Console output stays at Info+
+ * unless `--log-level` lowers the floor (see {@link consoleLogFloor}).
+ *
+ * Commands that install their own loggers with `mergeWithExisting: true`
+ * compose with this one; a replacing `Logger.layer` scopes it out for that
+ * subtree only. Best-effort throughout: an unwritable `~/.alchemy` must
+ * never take the CLI down with it.
+ */
+export const GlobalLogLive = Layer.unwrap(
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path;
+    const dir = path.join(rootDir(), "logs");
+    yield* fs.makeDirectory(dir, { recursive: true });
+
+    // Prune stale run logs so the directory stays bounded.
+    const now = yield* Clock.currentTimeMillis;
+    const entries = yield* fs
+      .readDirectory(dir)
+      .pipe(Effect.catch(() => Effect.succeed([] as string[])));
+    yield* Effect.forEach(
+      entries,
+      (entry) =>
+        Effect.gen(function* () {
+          const file = path.join(dir, entry);
+          const info = yield* fs.stat(file);
+          const mtime = Option.getOrUndefined(info.mtime)?.getTime();
+          if (
+            mtime !== undefined &&
+            now - mtime > Duration.toMillis(MAX_LOG_AGE)
+          ) {
+            yield* fs.remove(file);
+          }
+        }).pipe(Effect.ignore),
+      { discard: true },
+    );
+
+    const stamp = new Date(yield* Clock.currentTimeMillis)
+      .toISOString()
+      .slice(0, 19)
+      .replaceAll(":", "-");
+    const file = path.join(dir, `${stamp}-pid${process.pid}.log`);
+    return Layer.mergeAll(
+      Logger.layer([
+        makeConsoleLogger(consoleLogFloor(process.argv.slice(2))),
+        Logger.formatLogFmt.pipe(
+          Logger.toFile(file, { flag: "a" }),
+          Effect.catch(() => Effect.succeed(noopLogger)),
+        ),
+      ]),
+      Layer.succeed(MinimumLogLevel, "Debug"),
+    );
+  }).pipe(Effect.catch(() => Effect.succeed(Layer.empty))),
+);
+
+/** First line of every run log: enough context to read it standalone. */
+export const logRunHeader: Effect.Effect<void> = Effect.logDebug(
+  `alchemy ${packageJson.version} pid=${process.pid} cwd=${process.cwd()} argv=${JSON.stringify(process.argv.slice(2))}`,
+);