[Prototype] Implement pre-run hooks with .hooks.d support (#15)

* Implement pre-run hooks with .hooks.d support

Add pre-run hooks feature that executes scripts before main script execution.
Hooks enable environment validation, dependency checking, authentication, and setup tasks.

Implementation:
- Hook discovery from .hooks.d directory with lexicographic ordering
- Two hook types: executable (separate process) and sourced (same shell context)
- Sourced hooks use .source suffix and can modify environment variables
- Wrapper script generation for proper execution flow
- --skip-hooks flag to bypass hook execution
- Full environment variable injection (TOME_ROOT, TOME_SCRIPT_PATH, etc.)

Tests:
- 38 total tests covering unit, integration, and E2E scenarios
- Comprehensive validation of hook discovery, execution, and environment handling
- Deno E2E tests verify real-world usage with both tome-cli and wrapper

Documentation:
- Complete user guide in docs/hooks.md with examples and use cases
- Updated README.md with hooks feature section
- Example hooks in examples/.hooks.d for reference

All tests passing. Feature ready for use.

* Refactor hooks implementation with proper quoting and improved portability

This commit improves the hooks system with better shell compatibility,
proper argument escaping, and cleaner code organization.

Changes:

* Rename findBash() to findShell() and simplify implementation
  - Better name reflects that it finds bash OR sh
  - Remove hardcoded path checks for bash and sh
  - Use exec.LookPath("bash") with fallback to exec.LookPath("sh")
  - Use actual shell name (bash/sh) as argv[0] instead of hardcoding
  - More portable and idiomatic Go code

* Add proper shell escaping for paths and arguments
  - Integrate al.essio.dev/pkg/shellescape library
  - Quote all hook paths, script paths in wrapper template
  - Quote arguments only when necessary (e.g., spaces, special chars)
  - Prevents command injection and handles edge cases correctly

* Fix hardcoded /tmp paths in tests
  - Replace all hardcoded /tmp paths with t.TempDir()
  - Ensures proper test isolation and cross-platform compatibility
  - Updated: hooks_test.go, hooks_integration_test.go

* Add comprehensive sh compatibility tests
  - New TestShellCompatibility suite with 3 test cases
  - Verify wrapper scripts execute correctly with sh (not just bash)
  - Test sourced hooks work with sh
  - Validate POSIX-compliant syntax (no bash-specific features)
  - Add executeWrapperContentWithSh() helper function

* Add test for paths with spaces
  - Verify proper quoting of paths containing spaces
  - Test that simple args remain unquoted while complex args are quoted
  - Ensures robustness with real-world path scenarios

All tests passing:
- Unit tests: 9 test suites
- Integration tests: including new sh compatibility tests
- E2E tests: 25/25

Author: zph

README.md

@@ -176,6 +176,26 @@ case $1 in
 esac
 ```
 
+### Pre-Run Hooks
+
+Execute custom scripts before your main scripts run. Perfect for:
+- Environment validation and setup
+- Dependency checking
+- Authentication checks
+- Audit logging
+
+Create a `.hooks.d/` directory in your scripts root and add numbered hooks:
+
+```bash
+# Executable hook - runs as separate process
+.hooks.d/00-check-deps
+
+# Sourced hook - runs in same shell, can modify environment
+.hooks.d/05-set-env.source
+```
+
+See [docs/hooks.md](./docs/hooks.md) for complete guide with examples.
+
 ### Flexible Root Detection
 
 tome-cli determines the scripts root directory from multiple sources (in order of precedence):
@@ -200,10 +220,10 @@ This flexibility allows team members to customize locations without changing the
 - ✅ Environment variable injection
 - ✅ Structured logging with levels
 - ✅ Generated documentation
+- ✅ Pre-run hooks (.hooks.d folder execution)
 
 ### Planned
 - ⏳ ActiveHelp integration for contextual assistance
-- ⏳ Pre/post hooks (hooks.d folder execution)
 - ⏳ Enhanced directory help (show all subcommands in tree)
 - ⏳ Improved completion output filtering
 
@@ -318,6 +338,7 @@ Make sure:
 - [Your First Script](#your-first-script) - Create your first script
 - [Writing Scripts Guide](./docs/writing-scripts.md) - Comprehensive guide to writing scripts
 - [Completion Guide](./docs/completion-guide.md) - Implement custom tab completions
+- [Pre-Run Hooks Guide](./docs/hooks.md) - Add validation and setup hooks
 - [Migration Guide](./docs/migration.md) - Migrate from original tome/sub
 
 ### Core Documentation

cmd/exec.go

@@ -6,6 +6,7 @@ package cmd
 import (
 	"fmt"
 	"os"
+	"os/exec"
 	"path"
 	"path/filepath"
 	"strings"
@@ -80,11 +81,67 @@ func ExecRunE(cmd *cobra.Command, args []string) error {
 	envs = append(envs, fmt.Sprintf("%s_ROOT=%s", executableAsEnvPrefix, absRootDir))
 	envs = append(envs, fmt.Sprintf("%s_EXECUTABLE=%s", executableAsEnvPrefix, config.ExecutableName()))
 
-	args = append([]string{maybeFile}, maybeArgs...)
-	execOrLog(maybeFile, args, envs)
+	// Check for hooks and generate wrapper if needed
+	var execTarget string
+	var execArgs []string
+
+	if !skipHooks {
+		hookRunner := NewHookRunner(config)
+		hooks, err := hookRunner.DiscoverHooks()
+		if err != nil {
+			fmt.Printf("Error discovering hooks: %v\n", err)
+			os.Exit(1)
+		}
+
+		if len(hooks) > 0 {
+			// Generate wrapper script content
+			wrapperContent, err := hookRunner.GenerateWrapperScriptContent(hooks, executable, maybeArgs)
+			if err != nil {
+				fmt.Printf("Error generating wrapper script: %v\n", err)
+				os.Exit(1)
+			}
+
+			// Execute shell with inline script instead of script directly
+			shellPath, err := findShell()
+			if err != nil {
+				fmt.Printf("Error finding shell: %v\n", err)
+				os.Exit(1)
+			}
+			execTarget = shellPath
+			// Use basename of shell path for argv[0]
+			shellName := filepath.Base(shellPath)
+			execArgs = []string{shellName, "-c", wrapperContent}
+		} else {
+			// No hooks, execute script directly
+			execTarget = executable
+			execArgs = append([]string{executable}, maybeArgs...)
+		}
+	} else {
+		// Skip hooks, execute script directly
+		execTarget = executable
+		execArgs = append([]string{executable}, maybeArgs...)
+	}
+
+	execOrLog(execTarget, execArgs, envs)
 	return nil
 }
 
+// findShell locates a POSIX shell, preferring bash but falling back to sh if unavailable
+func findShell() (string, error) {
+	// Try bash first
+	if bashPath, err := exec.LookPath("bash"); err == nil {
+		return bashPath, nil
+	}
+
+	// Fall back to sh (POSIX standard)
+	if shPath, err := exec.LookPath("sh"); err == nil {
+		log.Debugw("bash not found, using sh as fallback", "path", shPath)
+		return shPath, nil
+	}
+
+	return "", fmt.Errorf("neither bash nor sh found")
+}
+
 func execOrLog(arv0 string, argv []string, env []string) {
 	if dryRun {
 		fmt.Printf("dry run:\nbinary: %s\nargs: %+v\nenv (injected):\n%+v\n", arv0, strings.Join(argv, " "), strings.Join(env, "\n"))
@@ -128,9 +185,12 @@ var execCmd = &cobra.Command{
 }
 
 var dryRun bool
+var skipHooks bool
 
 func init() {
 	execCmd.Flags().BoolVar(&dryRun, "dry-run", false, "Dry run the exec command")
+	execCmd.Flags().BoolVar(&skipHooks, "skip-hooks", false, "Skip pre-execution hooks")
 	viper.BindPFlag("dry-run", execCmd.Flags().Lookup("dry-run"))
+	viper.BindPFlag("skip-hooks", execCmd.Flags().Lookup("skip-hooks"))
 	rootCmd.AddCommand(execCmd)
 }