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.

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

@@ -80,8 +80,44 @@ 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
+			wrapperPath, err := hookRunner.GenerateWrapperScript(hooks, executable, maybeArgs)
+			if err != nil {
+				fmt.Printf("Error generating wrapper script: %v\n", err)
+				os.Exit(1)
+			}
+
+			// Clean up wrapper on exit (best effort)
+			defer os.Remove(wrapperPath)
+
+			// Execute wrapper instead of script directly
+			execTarget = wrapperPath
+			execArgs = []string{wrapperPath}
+		} 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
 }
 
@@ -128,9 +164,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)
 }