@canonical/summon 0.1.0

package/src/primitives.ts

@@ -0,0 +1,442 @@
+/**
+ * Primitive Operations
+ *
+ * This module provides primitive task-returning functions for common operations.
+ * These are the building blocks for constructing generators.
+ */
+
+import {
+  appendFileEffect,
+  copyDirectoryEffect,
+  copyFileEffect,
+  deleteDirectoryEffect,
+  deleteFileEffect,
+  execEffect,
+  existsEffect,
+  globEffect,
+  logEffect,
+  makeDirEffect,
+  promptEffect,
+  readContextEffect,
+  readFileEffect,
+  writeContextEffect,
+  writeFileEffect,
+} from "./effect.js";
+import { effect, flatMap, pure } from "./task.js";
+import type { ExecResult, LogLevel, PromptQuestion, Task } from "./types.js";
+
+// =============================================================================
+// File System Primitives
+// =============================================================================
+
+/**
+ * Read a file and return its contents as a string.
+ */
+export const readFile = (path: string): Task<string> =>
+  effect(readFileEffect(path));
+
+/**
+ * Write content to a file.
+ */
+export const writeFile = (path: string, content: string): Task<void> =>
+  effect(writeFileEffect(path, content));
+
+/**
+ * Append content to a file.
+ * @param path - Path to the file
+ * @param content - Content to append
+ * @param createIfMissing - Create the file if it doesn't exist (default: true)
+ */
+export const appendFile = (
+  path: string,
+  content: string,
+  createIfMissing = true,
+): Task<void> => effect(appendFileEffect(path, content, createIfMissing));
+
+/**
+ * Copy a file from source to destination.
+ */
+export const copyFile = (source: string, dest: string): Task<void> =>
+  effect(copyFileEffect(source, dest));
+
+/**
+ * Copy a directory recursively from source to destination.
+ */
+export const copyDirectory = (source: string, dest: string): Task<void> =>
+  effect(copyDirectoryEffect(source, dest));
+
+/**
+ * Delete a file.
+ */
+export const deleteFile = (path: string): Task<void> =>
+  effect(deleteFileEffect(path));
+
+/**
+ * Delete a directory recursively.
+ */
+export const deleteDirectory = (path: string): Task<void> =>
+  effect(deleteDirectoryEffect(path));
+
+/**
+ * Create a directory (recursively by default).
+ */
+export const mkdir = (path: string, recursive = true): Task<void> =>
+  effect(makeDirEffect(path, recursive));
+
+/**
+ * Check if a file or directory exists.
+ */
+export const exists = (path: string): Task<boolean> =>
+  effect(existsEffect(path));
+
+/**
+ * Find files matching a glob pattern.
+ */
+export const glob = (pattern: string, cwd: string): Task<string[]> =>
+  effect(globEffect(pattern, cwd));
+
+// =============================================================================
+// File Transformation Primitives
+// =============================================================================
+
+/**
+ * Options for sorting file lines.
+ */
+export interface SortFileLinesOptions {
+  /**
+   * Custom comparator function for sorting.
+   * Defaults to locale-aware string comparison.
+   */
+  compare?: (a: string, b: string) => number;
+
+  /**
+   * If true, remove duplicate lines after sorting.
+   * @default false
+   */
+  unique?: boolean;
+
+  /**
+   * Lines matching this pattern are considered "header" lines and will
+   * be kept at the top of the file, unsorted.
+   * Useful for preserving file headers, comments, or specific imports.
+   *
+   * @example /^\/\// - Keep lines starting with // at the top
+   * @example /^import.*from ["']react["']/ - Keep React imports at top
+   */
+  headerPattern?: RegExp;
+
+  /**
+   * Lines matching this pattern are considered "footer" lines and will
+   * be kept at the bottom of the file, unsorted.
+   */
+  footerPattern?: RegExp;
+
+  /**
+   * If true, preserve blank lines in their relative positions within
+   * the sorted content. If false, blank lines are sorted with other lines.
+   * @default false
+   */
+  preserveBlankLines?: boolean;
+}
+
+/**
+ * Sort the lines of a file.
+ *
+ * This is useful for maintaining sorted barrel files (index.ts with exports),
+ * sorted import lists, or any file where line order should be alphabetical.
+ *
+ * @param path - Path to the file to sort
+ * @param options - Sorting options
+ *
+ * @example
+ * // Sort a barrel file alphabetically
+ * sortFileLines("src/index.ts")
+ *
+ * @example
+ * // Sort exports, keeping the header comment
+ * sortFileLines("src/index.ts", {
+ *   headerPattern: /^\/\//,  // Keep comment lines at top
+ * })
+ *
+ * @example
+ * // Sort and deduplicate
+ * sortFileLines("src/exports.ts", { unique: true })
+ *
+ * @example
+ * // Custom sort (case-insensitive)
+ * sortFileLines("src/index.ts", {
+ *   compare: (a, b) => a.toLowerCase().localeCompare(b.toLowerCase())
+ * })
+ */
+export const sortFileLines = (
+  path: string,
+  options: SortFileLinesOptions = {},
+): Task<void> => {
+  const {
+    compare = (a, b) => a.localeCompare(b),
+    unique = false,
+    headerPattern,
+    footerPattern,
+    preserveBlankLines = false,
+  } = options;
+
+  return flatMap(readFile(path), (content) => {
+    const lines = content.split("\n");
+
+    // Separate header, body, and footer lines
+    const headerLines: string[] = [];
+    const footerLines: string[] = [];
+    const bodyLines: string[] = [];
+    const blankLineIndices: number[] = [];
+
+    // First pass: identify header lines (consecutive matches at start)
+    let inHeader = true;
+    let bodyStartIndex = 0;
+
+    if (headerPattern) {
+      for (let i = 0; i < lines.length; i++) {
+        if (inHeader && headerPattern.test(lines[i])) {
+          headerLines.push(lines[i]);
+          bodyStartIndex = i + 1;
+        } else {
+          inHeader = false;
+          break;
+        }
+      }
+    }
+
+    // Second pass: identify footer lines (consecutive matches at end)
+    let footerStartIndex = lines.length;
+
+    if (footerPattern) {
+      for (let i = lines.length - 1; i >= bodyStartIndex; i--) {
+        if (footerPattern.test(lines[i])) {
+          footerLines.unshift(lines[i]);
+          footerStartIndex = i;
+        } else {
+          break;
+        }
+      }
+    }
+
+    // Third pass: collect body lines
+    for (let i = bodyStartIndex; i < footerStartIndex; i++) {
+      const line = lines[i];
+      if (preserveBlankLines && line.trim() === "") {
+        blankLineIndices.push(bodyLines.length);
+        bodyLines.push(line);
+      } else {
+        bodyLines.push(line);
+      }
+    }
+
+    // Sort body lines (excluding blank lines if preserving them)
+    let sortedBody: string[];
+
+    if (preserveBlankLines) {
+      // Extract non-blank lines, sort them, then reinsert blanks
+      const nonBlankLines = bodyLines.filter((line) => line.trim() !== "");
+      const sortedNonBlank = unique
+        ? [...new Set(nonBlankLines)].sort(compare)
+        : nonBlankLines.sort(compare);
+
+      // Rebuild with blank lines in relative positions
+      sortedBody = [];
+      let nonBlankIdx = 0;
+      for (let i = 0; i < bodyLines.length; i++) {
+        if (blankLineIndices.includes(i)) {
+          sortedBody.push("");
+        } else if (nonBlankIdx < sortedNonBlank.length) {
+          sortedBody.push(sortedNonBlank[nonBlankIdx++]);
+        }
+      }
+    } else {
+      sortedBody = unique
+        ? [...new Set(bodyLines)].sort(compare)
+        : bodyLines.sort(compare);
+    }
+
+    // Reassemble the file
+    const sortedContent = [...headerLines, ...sortedBody, ...footerLines].join(
+      "\n",
+    );
+
+    return writeFile(path, sortedContent);
+  });
+};
+
+// =============================================================================
+// Process Primitives
+// =============================================================================
+
+/**
+ * Execute a command with arguments.
+ */
+export const exec = (
+  command: string,
+  args: string[],
+  cwd?: string,
+): Task<ExecResult> => effect(execEffect(command, args, cwd));
+
+/**
+ * Execute a simple command string (split on spaces).
+ */
+export const execSimple = (
+  commandLine: string,
+  cwd?: string,
+): Task<ExecResult> => {
+  const parts = commandLine.split(" ");
+  const [command, ...args] = parts;
+  return exec(command, args, cwd);
+};
+
+// =============================================================================
+// Prompt Primitives
+// =============================================================================
+
+/**
+ * Prompt the user with a question.
+ */
+export const prompt = <T = unknown>(question: PromptQuestion): Task<T> =>
+  effect(promptEffect(question));
+
+/**
+ * Prompt for text input.
+ */
+export const promptText = (
+  name: string,
+  message: string,
+  defaultValue?: string,
+): Task<string> =>
+  prompt({
+    type: "text",
+    name,
+    message,
+    default: defaultValue,
+  });
+
+/**
+ * Prompt for confirmation.
+ */
+export const promptConfirm = (
+  name: string,
+  message: string,
+  defaultValue = false,
+): Task<boolean> =>
+  prompt({
+    type: "confirm",
+    name,
+    message,
+    default: defaultValue,
+  });
+
+/**
+ * Prompt for selection from a list.
+ */
+export const promptSelect = (
+  name: string,
+  message: string,
+  choices: Array<{ label: string; value: string }>,
+  defaultValue?: string,
+): Task<string> =>
+  prompt({
+    type: "select",
+    name,
+    message,
+    choices,
+    default: defaultValue,
+  });
+
+/**
+ * Prompt for multiple selections from a list.
+ */
+export const promptMultiselect = (
+  name: string,
+  message: string,
+  choices: Array<{ label: string; value: string }>,
+  defaultValue?: string[],
+): Task<string[]> =>
+  prompt({
+    type: "multiselect",
+    name,
+    message,
+    choices,
+    default: defaultValue,
+  });
+
+// =============================================================================
+// Logging Primitives
+// =============================================================================
+
+/**
+ * Log a message at a specific level.
+ */
+export const log = (level: LogLevel, message: string): Task<void> =>
+  effect(logEffect(level, message));
+
+/**
+ * Log a debug message.
+ */
+export const debug = (message: string): Task<void> => log("debug", message);
+
+/**
+ * Log an info message.
+ */
+export const info = (message: string): Task<void> => log("info", message);
+
+/**
+ * Log a warning message.
+ */
+export const warn = (message: string): Task<void> => log("warn", message);
+
+/**
+ * Log an error message.
+ */
+export const error = (message: string): Task<void> => log("error", message);
+
+// =============================================================================
+// Context Primitives
+// =============================================================================
+
+/**
+ * Read a value from the context.
+ */
+export const getContext = <T = unknown>(key: string): Task<T | undefined> =>
+  effect(readContextEffect(key));
+
+/**
+ * Write a value to the context.
+ */
+export const setContext = (key: string, value: unknown): Task<void> =>
+  effect(writeContextEffect(key, value));
+
+/**
+ * Execute a task with a temporary context value.
+ */
+export const withContext = <A>(
+  key: string,
+  value: unknown,
+  task: Task<A>,
+): Task<A> => {
+  // This is a higher-level pattern that will be handled specially by interpreters
+  // For now, we implement it as set -> run -> restore
+  return {
+    _tag: "Effect",
+    effect: writeContextEffect(key, value),
+    cont: () => task,
+  };
+};
+
+// =============================================================================
+// Pure Primitives
+// =============================================================================
+
+/**
+ * A task that does nothing and returns void.
+ */
+export const noop: Task<void> = pure(undefined);
+
+/**
+ * A task that returns the given value.
+ */
+export const succeed = <A>(value: A): Task<A> => pure(value);

package/src/task.ts

@@ -0,0 +1,245 @@
+/**
+ * Task Monad Implementation
+ *
+ * The Task monad is the core abstraction for building composable, testable generators.
+ * Tasks represent computations that may perform effects and can fail.
+ *
+ * Key properties:
+ * - Pure: Tasks return effect descriptions, not actual effects
+ * - Composable: Tasks can be sequenced with flatMap/chain
+ * - Testable: Effects can be collected without execution
+ * - Type-safe: Full TypeScript inference for composed tasks
+ */
+
+import type { Effect, Task, TaskError } from "./types.js";
+
+// =============================================================================
+// Core Constructors
+// =============================================================================
+
+/**
+ * Lift a pure value into a Task.
+ */
+export const pure = <A>(value: A): Task<A> => ({
+  _tag: "Pure",
+  value,
+});
+
+/**
+ * Create a Task from an Effect.
+ * The continuation receives the result of executing the effect.
+ */
+export const effect = <A>(eff: Effect): Task<A> => ({
+  _tag: "Effect",
+  effect: eff,
+  cont: (result) => pure(result as A),
+});
+
+/**
+ * Create a failed Task with an error.
+ */
+export const fail = <A = never>(error: TaskError): Task<A> => ({
+  _tag: "Fail",
+  error,
+});
+
+/**
+ * Create a failed Task from an error code and message.
+ */
+export const failWith = <A = never>(code: string, message: string): Task<A> =>
+  fail({
+    code,
+    message,
+  });
+
+// =============================================================================
+// Monad Operations
+// =============================================================================
+
+/**
+ * Monadic bind (flatMap).
+ * Sequences two tasks, passing the result of the first to produce the second.
+ */
+export const flatMap = <A, B>(task: Task<A>, f: (a: A) => Task<B>): Task<B> => {
+  switch (task._tag) {
+    case "Pure":
+      return f(task.value);
+    case "Fail":
+      return task as unknown as Task<B>;
+    case "Effect":
+      return {
+        _tag: "Effect",
+        effect: task.effect,
+        cont: (result) => flatMap(task.cont(result), f),
+      };
+  }
+};
+
+/**
+ * Functor map.
+ * Transform the result of a task with a pure function.
+ */
+export const map = <A, B>(task: Task<A>, f: (a: A) => B): Task<B> =>
+  flatMap(task, (a) => pure(f(a)));
+
+/**
+ * Apply a function wrapped in a Task to a value wrapped in a Task.
+ */
+export const ap = <A, B>(taskF: Task<(a: A) => B>, taskA: Task<A>): Task<B> =>
+  flatMap(taskF, (f) => map(taskA, f));
+
+/**
+ * Error recovery.
+ * If the task fails, the handler can produce a new task.
+ */
+export const recover = <A>(
+  task: Task<A>,
+  handler: (error: TaskError) => Task<A>,
+): Task<A> => {
+  switch (task._tag) {
+    case "Pure":
+      return task;
+    case "Fail":
+      return handler(task.error);
+    case "Effect":
+      return {
+        _tag: "Effect",
+        effect: task.effect,
+        cont: (result) => recover(task.cont(result), handler),
+      };
+  }
+};
+
+/**
+ * Map over the error of a failed task.
+ */
+export const mapError = <A>(
+  task: Task<A>,
+  f: (error: TaskError) => TaskError,
+): Task<A> => {
+  switch (task._tag) {
+    case "Pure":
+      return task;
+    case "Fail":
+      return fail(f(task.error));
+    case "Effect":
+      return {
+        _tag: "Effect",
+        effect: task.effect,
+        cont: (result) => mapError(task.cont(result), f),
+      };
+  }
+};
+
+// =============================================================================
+// Fluent Builder API
+// =============================================================================
+
+/**
+ * Fluent builder for composing tasks.
+ * Provides a chainable API for common task operations.
+ */
+export class TaskBuilder<A> {
+  constructor(private readonly _task: Task<A>) {}
+
+  /**
+   * Transform the result with a pure function.
+   */
+  map<B>(f: (a: A) => B): TaskBuilder<B> {
+    return new TaskBuilder(map(this._task, f));
+  }
+
+  /**
+   * Chain with another task-producing function.
+   */
+  flatMap<B>(f: (a: A) => Task<B>): TaskBuilder<B> {
+    return new TaskBuilder(flatMap(this._task, f));
+  }
+
+  /**
+   * Chain with another TaskBuilder-producing function.
+   */
+  chain<B>(f: (a: A) => TaskBuilder<B>): TaskBuilder<B> {
+    return new TaskBuilder(flatMap(this._task, (a) => f(a).unwrap()));
+  }
+
+  /**
+   * Recover from errors.
+   */
+  recover(f: (error: TaskError) => Task<A>): TaskBuilder<A> {
+    return new TaskBuilder(recover(this._task, f));
+  }
+
+  /**
+   * Map over errors.
+   */
+  mapError(f: (error: TaskError) => TaskError): TaskBuilder<A> {
+    return new TaskBuilder(mapError(this._task, f));
+  }
+
+  /**
+   * Execute a side effect without changing the value.
+   */
+  tap(f: (a: A) => Task<unknown>): TaskBuilder<A> {
+    return new TaskBuilder(flatMap(this._task, (a) => map(f(a), () => a)));
+  }
+
+  /**
+   * Sequence with another task, discarding the current value.
+   * Useful for chaining void tasks.
+   *
+   * @example
+   * task(mkdir("output"))
+   *   .andThen(writeFile("output/a.txt", "A"))
+   *   .andThen(writeFile("output/b.txt", "B"))
+   *   .andThen(info("Done!"))
+   */
+  andThen<B>(next: Task<B>): TaskBuilder<B> {
+    return new TaskBuilder(flatMap(this._task, () => next));
+  }
+
+  /**
+   * Extract the underlying Task.
+   */
+  unwrap(): Task<A> {
+    return this._task;
+  }
+}
+
+/**
+ * Create a TaskBuilder from a Task.
+ */
+export const task = <A>(t: Task<A>): TaskBuilder<A> => new TaskBuilder(t);
+
+/**
+ * Create a TaskBuilder from a pure value.
+ */
+export const of = <A>(value: A): TaskBuilder<A> => task(pure(value));
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Check if a task is pure (no effects).
+ */
+export const isPure = <A>(t: Task<A>): t is { _tag: "Pure"; value: A } =>
+  t._tag === "Pure";
+
+/**
+ * Check if a task has failed.
+ */
+export const isFailed = <A>(
+  t: Task<A>,
+): t is { _tag: "Fail"; error: TaskError } => t._tag === "Fail";
+
+/**
+ * Check if a task has effects.
+ */
+export const hasEffects = <A>(
+  t: Task<A>,
+): t is {
+  _tag: "Effect";
+  effect: Effect;
+  cont: (result: unknown) => Task<A>;
+} => t._tag === "Effect";