@canonical/summon 0.1.0

package/src/cli-format.ts

@@ -0,0 +1,165 @@
+/**
+ * CLI Formatting Utilities
+ *
+ * Shared formatting functions for CLI output (both interactive and batch modes).
+ */
+
+import chalk from "chalk";
+import type { Effect } from "./types.js";
+
+// Fixed width for action label column
+const ACTION_LABEL_WIDTH = 14;
+
+/**
+ * Filter effects to only show user-relevant ones (not internal effects).
+ * @param effect - The effect to check
+ * @param verbose - If true, include debug logs
+ */
+export const isVisibleEffect = (effect: Effect, verbose = false): boolean => {
+  switch (effect._tag) {
+    case "WriteFile":
+    case "AppendFile":
+    case "MakeDir":
+    case "CopyFile":
+    case "CopyDirectory":
+    case "DeleteFile":
+    case "DeleteDirectory":
+    case "Exec":
+      return true;
+    case "Log":
+      // Filter out debug logs unless verbose is enabled
+      if (effect.level === "debug") {
+        return verbose;
+      }
+      return true;
+    // Internal effects are not shown
+    case "ReadFile":
+    case "Exists":
+    case "Glob":
+    case "ReadContext":
+    case "WriteContext":
+    case "Prompt":
+    case "Parallel":
+    case "Race":
+      return false;
+    default:
+      return false;
+  }
+};
+
+/**
+ * Get human-readable action label for an effect.
+ */
+export const getActionLabel = (effect: Effect): string => {
+  switch (effect._tag) {
+    case "WriteFile":
+      return "Create file";
+    case "AppendFile":
+      return "Append to";
+    case "MakeDir":
+      return "Create dir";
+    case "CopyFile":
+      return "Copy file";
+    case "CopyDirectory":
+      return "Copy dir";
+    case "DeleteFile":
+      return "Delete file";
+    case "DeleteDirectory":
+      return "Delete dir";
+    case "Exec":
+      return "Execute";
+    case "Log":
+      switch (effect.level) {
+        case "debug":
+          return "Debug";
+        case "info":
+          return "Info";
+        case "warn":
+          return "Warning";
+        case "error":
+          return "Error";
+        default:
+          return "Log";
+      }
+    default:
+      return effect._tag;
+  }
+};
+
+/**
+ * Get color for action label based on effect type.
+ */
+export const getActionColor = (
+  effect: Effect,
+): "green" | "red" | "yellow" | "cyan" | "blue" | "magenta" | undefined => {
+  switch (effect._tag) {
+    case "WriteFile":
+    case "MakeDir":
+      return "green";
+    case "AppendFile":
+      return "magenta";
+    case "DeleteFile":
+    case "DeleteDirectory":
+      return "red";
+    case "CopyFile":
+    case "CopyDirectory":
+      return "cyan";
+    case "Exec":
+      return "yellow";
+    case "Log":
+      switch (effect.level) {
+        case "error":
+          return "red";
+        case "warn":
+          return "yellow";
+        case "debug":
+          return undefined; // dim by default
+        default:
+          return "blue";
+      }
+    default:
+      return undefined;
+  }
+};
+
+/**
+ * Get the payload (description) for an effect.
+ */
+export const getEffectPayload = (effect: Effect): string => {
+  switch (effect._tag) {
+    case "WriteFile":
+      return effect.path;
+    case "AppendFile":
+      return effect.path;
+    case "MakeDir":
+      return effect.path;
+    case "CopyFile":
+      return `${effect.source} → ${effect.dest}`;
+    case "CopyDirectory":
+      return `${effect.source}/ → ${effect.dest}/`;
+    case "DeleteFile":
+    case "DeleteDirectory":
+      return effect.path;
+    case "Exec":
+      return `${effect.command} ${effect.args.join(" ")}`;
+    case "Log":
+      return effect.message;
+    default:
+      return effect._tag;
+  }
+};
+
+/**
+ * Format a single effect as a CLI line (for non-interactive output).
+ */
+export const formatEffectLine = (effect: Effect, isLast: boolean): string => {
+  const connector = isLast ? "└─" : "├─";
+  const actionLabel = getActionLabel(effect);
+  const color = getActionColor(effect);
+  const payload = getEffectPayload(effect);
+
+  const colorFn = color ? chalk[color] : (s: string) => s;
+  const paddedLabel = actionLabel.padEnd(ACTION_LABEL_WIDTH);
+
+  return `${chalk.dim(connector)} ${colorFn(paddedLabel)}${payload}`;
+};

package/src/cli-types.ts

@@ -0,0 +1,53 @@
+/**
+ * CLI Type Definitions
+ *
+ * Types for generator authors to validate their prompt names at compile-time.
+ */
+
+/**
+ * Reserved option names for CLI global options.
+ * Generator prompts MUST NOT use these names.
+ *
+ * Use the `ForbidReserved` type to enforce at compile-time:
+ * @example
+ * ```typescript
+ * interface MyAnswers {
+ *   name: string;       // OK
+ *   help: string;       // Will cause type error
+ * }
+ *
+ * // This will produce a compile-time error if any key is reserved
+ * type ValidatedAnswers = ForbidReserved<MyAnswers>;
+ * ```
+ */
+export type ReservedOption =
+  | "help"
+  | "version"
+  | "dryRun"
+  | "dry-run"
+  | "yes"
+  | "output"
+  | "preview"
+  | "generators"
+  | "run"
+  | "init";
+
+/**
+ * Type helper that produces a compile-time error if T contains any reserved option names.
+ *
+ * @example
+ * ```typescript
+ * interface BadAnswers {
+ *   name: string;
+ *   help: string; // Reserved!
+ * }
+ *
+ * // This will error: Type 'string' is not assignable to type '["Error: 'help' is a reserved option name"]'
+ * const generator: GeneratorDefinition<ForbidReserved<BadAnswers>> = { ... };
+ * ```
+ */
+export type ForbidReserved<T> = {
+  [K in keyof T]: K extends ReservedOption
+    ? [`Error: '${K & string}' is a reserved option name`]
+    : T[K];
+};