feat: add 13 new builtin extensions (sources, previewers, renderers)

CLAUDE.md

@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with
+code in this repository.
+
+## Project Overview
+
+This is `@vim-fall/std`, the standard library for Fall - a fuzzy finder plugin
+for Vim/Neovim powered by Denops. The project provides built-in extensions and
+utility functions for the Fall ecosystem, written in Deno/TypeScript.
+
+## Key Commands
+
+### Development
+
+- **Type check**: `deno task check` - Run TypeScript type checking
+- **Test**: `deno test -A --parallel --shuffle --doc` - Run all tests
+- **Test single file**: `deno test -A path/to/file_test.ts` - Run specific test
+  file
+- **Test with coverage**: `deno task test:coverage` - Run tests with coverage
+  collection
+- **Lint**: `deno lint` - Run Deno linter
+- **Format**: `deno fmt` - Auto-format code
+- **Format check**: `deno fmt --check` - Check formatting without modifying
+
+### Code Generation
+
+- **Generate all**: `deno task gen` - Run all code generation tasks
+- **Generate modules**: `deno task gen:mod` - Generate module files in each
+  directory
+- **Generate exports**: `deno task gen:exports` - Generate export declarations
+- **Generate nerdfont**: `deno task gen:builtin-renderer-nerdfont` - Generate
+  nerdfont icon mappings
+
+### Dependencies
+
+- **Update check**: `deno task update` - Check for dependency updates
+- **Update write**: `deno task update:write` - Update dependencies in place
+- **Update commit**: `deno task update:commit` - Update and commit dependency
+  changes
+
+### Publishing
+
+- **Dry run**: `deno publish --dry-run` - Test JSR publishing without publishing
+
+## Architecture
+
+### Module Organization
+
+The codebase follows a plugin-based architecture with these core concepts:
+
+1. **Extension Types** (in `/builtin/`):
+
+   - **Actions**: Operations performed on selected items (open, yank, cd)
+   - **Coordinators**: UI layout managers (compact, modern, separate)
+   - **Curators**: Search/filter tools wrapping external commands (grep,
+     ripgrep, git-grep)
+   - **Matchers**: Fuzzy matching algorithms (fzf, regexp, substring)
+   - **Previewers**: Item preview handlers (file, buffer, helptag)
+   - **Refiners**: Item transformation/filtering tools
+   - **Renderers**: Display formatters (nerdfont icons, path formatting)
+   - **Sorters**: Sorting algorithms (lexical, numerical)
+   - **Sources**: Data providers (files, buffers, quickfix, history)
+   - **Themes**: UI border styles (ascii, modern, single, double)
+
+2. **Core APIs** (in root):
+
+   - Each extension type has a corresponding definition file (e.g., `action.ts`,
+     `source.ts`)
+   - These files define the interface and helper functions for that extension
+     type
+   - The `mod.ts` file re-exports utility functions for composing extensions
+
+3. **Denops Integration**:
+   - All extensions receive a `Denops` instance for Vim/Neovim interaction
+   - Uses `@denops/std` for Vim API access
+   - Test files use `@denops/test` for testing with real Vim instances
+
+### Key Patterns
+
+1. **Extension Definition**: Use `define*` functions (e.g., `defineAction`,
+   `defineSource`)
+2. **Composition**: Use `compose*` functions to combine multiple extensions
+3. **Type Safety**: Extensive use of TypeScript generics for item detail types
+4. **Async/Streaming**: Sources use async generators for efficient data
+   streaming
+5. **Parameter Binding**: `ArgsBinder` pattern for flexible parameter handling
+
+### Testing Approach
+
+- Tests use Deno's built-in test runner with `Deno.test()`
+- Integration tests use real Vim/Neovim instances via `@denops/test`
+- Test files follow `*_test.ts` naming convention
+- Use `@std/assert` for assertions
+
+### Libraries
+
+- Use `@core/unknownutil` for type-guarding unknown types
+  - Note that if you use `@denops/std/function`, some functions already provides
+    proper types so you may not need to use `@core/unknownutil`
+  - You should try hard to avoid using `as any` or `as unkonwn as`. Proper
+    type-guarding is preferred.
+- Use `@denops/std` for Vim/Neovim API access.

builtin/previewer/mod.ts

@@ -3,3 +3,4 @@ export * from "./buffer.ts";
 export * from "./file.ts";
 export * from "./helptag.ts";
 export * from "./noop.ts";
+export * from "./shell.ts";

builtin/previewer/shell.ts

@@ -0,0 +1,163 @@
+import { unnullish } from "@lambdalisue/unnullish";
+
+import { definePreviewer, type Previewer } from "../../previewer.ts";
+import { splitText } from "../../util/stringutil.ts";
+
+type Detail = {
+  /**
+   * Command to execute
+   */
+  command?: string;
+
+  /**
+   * Arguments to pass to the command
+   */
+  args?: string[];
+
+  /**
+   * Current working directory for command execution
+   */
+  cwd?: string;
+
+  /**
+   * Environment variables
+   */
+  env?: Record<string, string>;
+
+  /**
+   * Timeout in milliseconds
+   */
+  timeout?: number;
+};
+
+export type ShellOptions = {
+  /**
+   * Default shell to use if no command is specified.
+   * @default ["sh", "-c"]
+   */
+  shell?: string[];
+
+  /**
+   * Default timeout in milliseconds.
+   * @default 5000
+   */
+  defaultTimeout?: number;
+
+  /**
+   * Maximum number of lines to display.
+   * @default 1000
+   */
+  maxLines?: number;
+};
+
+/**
+ * Creates a Previewer that executes shell commands and displays their output.
+ *
+ * This Previewer runs a specified command and shows its stdout/stderr output.
+ * It supports custom working directories, environment variables, and timeouts.
+ *
+ * @param options - Options to customize shell command execution.
+ * @returns A Previewer that shows the command output.
+ */
+export function shell(options: Readonly<ShellOptions> = {}): Previewer<Detail> {
+  const shell = options.shell ?? ["sh", "-c"];
+  const defaultTimeout = options.defaultTimeout ?? 5000;
+  const maxLines = options.maxLines ?? 1000;
+
+  return definePreviewer(async (_denops, { item }, { signal }) => {
+    // Get command from detail or use item value as command
+    const command = item.detail.command ?? item.value;
+    const args = item.detail.args ?? [];
+    const cwd = item.detail.cwd;
+    const env = item.detail.env;
+    const timeout = item.detail.timeout ?? defaultTimeout;
+
+    // Prepare command array
+    let cmd: string[];
+    if (args.length > 0) {
+      cmd = [command, ...args];
+    } else {
+      // Use shell to execute the command string
+      cmd = [...shell, command];
+    }
+
+    try {
+      // Create subprocess
+      const process = new Deno.Command(cmd[0], {
+        args: cmd.slice(1),
+        cwd: unnullish(cwd, (v) => v),
+        env: unnullish(env, (v) => v),
+        stdout: "piped",
+        stderr: "piped",
+        signal,
+      });
+
+      // Set up timeout
+      const timeoutId = setTimeout(() => {
+        try {
+          process.spawn().kill();
+        } catch {
+          // Ignore errors when killing
+        }
+      }, timeout);
+
+      try {
+        // Execute command
+        const { stdout, stderr, success } = await process.output();
+        clearTimeout(timeoutId);
+
+        // Decode output
+        const decoder = new TextDecoder();
+        const stdoutText = decoder.decode(stdout);
+        const stderrText = decoder.decode(stderr);
+
+        // Combine stdout and stderr
+        let content: string[] = [];
+
+        if (stdoutText) {
+          content.push(...splitText(stdoutText));
+        }
+
+        if (stderrText) {
+          if (content.length > 0) {
+            content.push("--- stderr ---");
+          }
+          content.push(...splitText(stderrText));
+        }
+
+        // Add status line if command failed
+        if (!success) {
+          content.push("", `[Command failed with non-zero exit code]`);
+        }
+
+        // Limit output lines
+        if (content.length > maxLines) {
+          content = content.slice(0, maxLines);
+          content.push("", `[Output truncated to ${maxLines} lines]`);
+        }
+
+        // Handle empty output
+        if (content.length === 0) {
+          content = ["[No output]"];
+        }
+
+        return {
+          content,
+          filename: `$ ${cmd.join(" ")}`,
+        };
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    } catch (err) {
+      // Handle command execution errors
+      return {
+        content: [
+          `Error executing command: ${command}`,
+          "",
+          ...String(err).split("\n"),
+        ],
+        filename: `$ ${cmd.join(" ")}`,
+      };
+    }
+  });
+}