markdown_exec 3.5.1 → 3.5.2

data/docs/ux-blocks.md

@@ -0,0 +1,376 @@
+# UX Blocks
+
+UX blocks create interactive forms that prompt users for input, validate values, and initialize from various sources. This document covers the complete UX block system.
+
+## Overview
+
+UX blocks provide an interactive form system for markdown_exec that allows you to:
+- Prompt users for input with custom prompts
+- Validate input using regex patterns
+- Transform validated input using format strings
+- Initialize values from environment variables, commands, or allowed lists
+- Create dynamic selection menus from command output
+- Chain UX blocks with dependencies
+
+## Block Structure
+
+A UX block is a fenced code block with type `ux`:
+
+```ux
+name: VARIABLE_NAME
+prompt: Enter a value
+init: Default value
+```
+
+## Key Fields
+
+### Required Fields
+
+- **`name`**: The variable name that will be set (required)
+
+### Optional Fields
+
+- **`prompt`**: Text displayed when prompting for input
+- **`init`**: Initial value or initialization method (see Init Phase below)
+- **`act`**: Activation method (see Act Phase below)
+- **`allow`**: List of allowed values for selection
+- **`validate`**: Regex pattern for input validation
+- **`transform`**: Format string for transforming validated input
+- **`format`**: Format string for displaying the value
+- **`echo`**: Shell expression to evaluate
+- **`exec`**: Command to execute
+- **`require`**: List of other UX block names that must be set first
+
+## Init and Act Behavior
+
+The `init` and `act` keys determine which other key is read for processing during initialization (when document is loaded) and activation (when block is selected) respectively.
+
+### Init Phase
+
+The init phase runs when the document is loaded. The behavior depends on the `init` value:
+
+1. **`init: false`**: No initialization occurs
+2. **`init: "string"`**: That string becomes the initial value
+3. **`init: :allow`**: First value from `allow` list is used
+4. **`init: :echo`**: Value from `echo` key is evaluated and returned
+5. **`init: :exec`**: Command from `exec` key is executed and stdout is returned
+6. **`init` not present**: Defaults to first available in order:
+   - `:allow` if `allow` exists
+   - `:default` if `default` exists
+   - `:echo` if `echo` exists
+   - `:exec` if `exec` exists
+   - `false` if none of the above exist
+
+### Act Phase
+
+The act phase runs when the block is activated (selected). The behavior depends on the `act` value:
+
+1. **`act: false`**: Block cannot be activated
+2. **`act: :allow`**: User selects from `allow` list
+3. **`act: :echo`**: Value from `echo` key is evaluated and returned
+4. **`act: :edit`**: User is prompted for input
+5. **`act: :exec`**: Command from `exec` key is executed and stdout is returned
+6. **`act` not present**: Defaults to:
+   - If `init` is `false`: First available in order: `:allow`, `:echo`, `:edit`, `:exec`
+   - Otherwise:
+     - `:allow` if `allow` exists
+     - `:edit` if `allow` does not exist
+
+## Examples
+
+### Simple Variable Display and Edit
+
+```ux
+init: Guest
+name: USER_NAME
+prompt: Enter your name
+```
+
+- On init: Sets `USER_NAME` to "Guest"
+- On act: Prompts user to enter their name
+
+### Command Output Initialization
+
+```ux
+name: CURRENT_DIR
+init: :exec
+exec: basename $(pwd)
+transform: :chomp
+```
+
+- On init: Executes `basename $(pwd)` and uses output as value
+- On act: Prompts for input (default behavior)
+
+### Echo-based Initialization
+
+```ux
+name: SHELL_VERSION
+init: :echo
+echo: $SHELL
+```
+
+- On init: Evaluates `$SHELL` and uses result as value
+- On act: Evaluates echo string (default behavior)
+
+### Selection from Allowed Values
+
+```ux
+name: ENVIRONMENT
+allow:
+  - development
+  - staging
+  - production
+prompt: Select environment
+```
+
+- On init: Uses first allowed value (development)
+- On act: Shows menu of allowed values for selection
+
+### Email Validation
+
+```ux
+name: USER_EMAIL
+prompt: Enter email address
+validate: '(?<local>[^@]+)@(?<domain>[^@]+)'
+transform: '%{local}@%{domain}'
+```
+
+- Validates input matches email pattern
+- Transforms using captured groups from validation regex
+
+### Version Number Validation
+
+```ux
+name: VERSION
+prompt: Enter version number
+validate: '(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)'
+transform: '%{major}.%{minor}.%{patch}'
+```
+
+- Validates version number format
+- Normalizes format using captured groups
+
+### Git Branch Selection with Validation
+
+```ux
+name: BRANCH_NAME
+init: ":exec"
+exec: "git branch --format='%(refname:short)'"
+validate: '^(?<type>feature|bugfix|hotfix)/(?<ticket>[A-Z]+-\d+)-(?<desc>.+)$'
+transform: "${type}/${ticket}-${desc}"
+prompt: "Select or enter branch name"
+```
+
+- On init: Executes git command to get branch list
+- Validates branch name format
+- Transforms to normalized format
+
+### Environment Configuration with Dependencies
+
+```ux
+name: DATABASE_URL
+require:
+  - ENVIRONMENT
+  - DB_HOST
+  - DB_PORT
+format: "postgresql://${DB_USER}:${DB_PASS}@${DB_HOST}:${DB_PORT}/${DB_NAME}"
+```
+
+- Requires other UX blocks to be set first
+- Formats final value using required variables
+
+### Multi-step Configuration
+
+```ux
+name: DEPLOY_CONFIG
+require:
+  - ENVIRONMENT
+  - VERSION
+init: ":echo"
+echo: "Deploying ${VERSION} to ${ENVIRONMENT}"
+act: ":exec"
+exec: "deploy.sh ${ENVIRONMENT} ${VERSION}"
+```
+
+- On init: Evaluates echo string with dependencies
+- On act: Executes deploy script with parameters
+
+### Conditional Initialization
+
+```ux
+name: API_KEY
+init: ":allow"
+allow:
+  - ${PROD_API_KEY}
+  - ${STAGING_API_KEY}
+  - ${DEV_API_KEY}
+require:
+  - ENVIRONMENT
+```
+
+- On init: Uses first allowed API key
+- On act: Shows menu of allowed API keys for selection
+- Requires ENVIRONMENT to be set first
+
+### Formatted Output with Validation
+
+```ux
+name: PHONE_NUMBER
+prompt: "Enter phone number"
+validate: '(?<country>\d{1,3})(?<area>\d{3})(?<number>\d{7})'
+transform: "+${country} (${area}) ${number}"
+format: "Phone: ${PHONE_NUMBER}"
+```
+
+- Validates phone number format
+- Transforms to formatted display
+- Uses format string for final display
+
+### Command Output with Transformation
+
+```ux
+name: GIT_STATUS
+init: ":exec"
+exec: "git status --porcelain"
+validate: '(?<status>[AMDR])\s+(?<file>.+)'
+transform: "${status}: ${file}"
+format: "Changes: ${GIT_STATUS}"
+```
+
+- On init: Executes git status command
+- Validates and transforms output
+- Formats for display
+
+## Advanced Patterns
+
+### Echo on Init, Exec on Act
+
+```ux
+name: DEPLOY_CONFIG
+init: :echo
+echo: "Deploying ${VERSION} to ${ENVIRONMENT}"
+act: :exec
+exec: "deploy.sh ${ENVIRONMENT} ${VERSION}"
+```
+
+**Behavior:**
+- On init: Evaluates echo string "Deploying ${VERSION} to ${ENVIRONMENT}"
+- On act: Executes deploy.sh with environment and version parameters
+
+### Allow on Init, Edit on Act
+
+```ux
+name: ENVIRONMENT
+init: :allow
+allow:
+  - development
+  - staging
+  - production
+act: :edit
+prompt: Select environment
+```
+
+**Behavior:**
+- On init: Uses first allowed value (development)
+- On act: Prompts user to select from allowed values
+
+### Exec on Init, Echo on Act
+
+```ux
+name: CURRENT_DIR
+init: :exec
+exec: basename $(pwd)
+act: :echo
+echo: "Current directory: ${CURRENT_DIR}"
+```
+
+**Behavior:**
+- On init: Executes basename command on current directory
+- On act: Evaluates echo string with current directory value
+
+### Allow on Both
+
+```ux
+name: API_KEY
+init: :allow
+allow:
+  - ${PROD_API_KEY}
+  - ${STAGING_API_KEY}
+  - ${DEV_API_KEY}
+act: :allow
+require:
+  - ENVIRONMENT
+```
+
+**Behavior:**
+- On init: Uses first allowed API key
+- On act: Shows menu of allowed API keys for selection
+
+### Echo on Both
+
+```ux
+name: SHELL_VERSION
+init: :echo
+echo: $SHELL
+act: :echo
+echo: "Using shell: ${SHELL_VERSION}"
+```
+
+**Behavior:**
+- On init: Gets shell value from environment
+- On act: Evaluates echo string with current shell value
+
+## Validation and Transformation
+
+### Validation Regex
+
+The `validate` field uses Ruby regex syntax with named capture groups:
+
+```ux
+validate: '(?<local>[^@]+)@(?<domain>[^@]+)'
+```
+
+This creates capture groups that can be referenced in the `transform` field.
+
+### Transformation Format
+
+The `transform` field uses format string syntax with capture group references:
+
+```ux
+transform: '%{local}@%{domain}'
+```
+
+Or with shell variable expansion:
+
+```ux
+transform: "${local}@${domain}"
+```
+
+### Format Display
+
+The `format` field controls how the value is displayed in menus:
+
+```ux
+format: "Phone: ${PHONE_NUMBER}"
+```
+
+## Dependencies
+
+UX blocks can depend on other UX blocks using the `require` field:
+
+```ux
+name: DATABASE_URL
+require:
+  - ENVIRONMENT
+  - DB_HOST
+  - DB_PORT
+```
+
+When a UX block has dependencies, those blocks must be initialized or activated first before this block can be used.
+
+## Related Documentation
+
+- [Block Naming Patterns](block-naming-patterns.md) - How block names are parsed
+- [Block Execution Modes](block-execution-modes.md) - Execution mode configuration
+- [Import Options](import-options.md) - Using UX blocks with imports
+

data/examples/linked1.md

@@ -40,5 +40,12 @@ file: examples/linked2.md
 ```link :linked2_import_vars +(vars2)
 file: examples/linked2.md
 vars:
-  page2_var_via_environment: for_page2_from_page1_via_current_environment
+  page2_var_via_environment: ${PAGE2_VAR_VIA_INHERIT}
+  page2_var_via_environment1: ${d1_v1}
+  page2_var_via_environment2: for_page2_from_page1_via_current_environment
 ```
+```vars :(document_vars)
+d1_v1: 1
+```
+
+```

data/implementation-decisions.md

@@ -0,0 +1,212 @@
+# Implementation Decisions
+
+**STDD Methodology Version**: 1.0.0
+
+## Overview
+This document captures detailed implementation decisions for your project, including specific APIs, data structures, and algorithms. All decisions are cross-referenced with architecture decisions using `[ARCH:*]` tokens and requirements using `[REQ:*]` tokens for traceability.
+
+## 1. Configuration Structure [IMPL:CONFIG_STRUCT] [ARCH:CONFIG_STRUCTURE] [REQ:CONFIGURATION]
+
+### Config Type
+```[your-language]
+type Config struct {
+    // Add your configuration fields here
+    Field1 string
+    Field2 int
+    Field3 bool
+}
+```
+
+### Default Values
+- Field1: default value
+- Field2: default value
+- Field3: default value
+
+## 2. Core Implementation [IMPL:EXAMPLE_IMPLEMENTATION] [ARCH:EXAMPLE_DECISION] [REQ:EXAMPLE_FEATURE]
+
+### Data Structure
+```[your-language]
+type ExampleStruct struct {
+    Field1 string
+    Field2 int
+}
+```
+
+### Implementation Approach
+- Approach description
+- Key algorithms
+- Performance considerations
+
+### Platform-Specific Considerations
+- Platform 1: Specific considerations
+- Platform 2: Specific considerations
+
+## 3. Error Handling Implementation [IMPL:ERROR_HANDLING] [ARCH:ERROR_HANDLING] [REQ:ERROR_HANDLING]
+
+### Error Types
+```[your-language]
+var (
+    ErrExampleError = errors.New("example error message")
+    ErrAnotherError = errors.New("another error message")
+)
+```
+
+### Error Wrapping
+```[your-language]
+if err != nil {
+    return fmt.Errorf("context: %w", err)
+}
+```
+
+### Error Reporting
+- Error logging approach
+- Error propagation pattern
+- User-facing error messages
+
+## 4. Testing Implementation [IMPL:TESTING] [ARCH:TESTING_STRATEGY] [REQ:*]
+
+**Note**: This implementation realizes the validation criteria specified in `requirements.md` and follows the testing strategy defined in `architecture-decisions.md`. Each test validates specific satisfaction criteria from requirements.
+
+### Unit Test Structure
+```[your-language]
+func TestExampleFeature(t *testing.T) {
+    tests := []struct {
+        name     string
+        input    InputType
+        expected OutputType
+    }{
+        {
+            name:     "test case 1",
+            input:    inputValue,
+            expected: expectedValue,
+        },
+    }
+    
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := functionUnderTest(tt.input)
+            if result != tt.expected {
+                t.Errorf("expected %v, got %v", tt.expected, result)
+            }
+        })
+    }
+}
+```
+
+### Integration Test Structure
+```[your-language]
+func TestIntegrationScenario(t *testing.T) {
+    // Setup
+    // Execute
+    // Verify
+}
+```
+
+## 5. Code Style and Conventions [IMPL:CODE_STYLE]
+
+### Naming
+- Use descriptive names
+- Follow language naming conventions
+- Exported types/functions: PascalCase (or language equivalent)
+- Unexported: camelCase (or language equivalent)
+
+### Documentation
+- Package-level documentation
+- Exported function documentation
+- Inline comments for complex logic
+- Examples in test files
+
+### Formatting
+- Use standard formatter for chosen language
+- Use linter for code quality
+
+## 6. Shebang Line Detection Logic [IMPL:SHEBANG_DETECTION] [ARCH:SHEBANG_EXTRACTION] [REQ:SHEBANG_HIDING]
+
+### Detection Algorithm
+```ruby
+  # [REQ:SHEBANG_HIDING] Detect shebang lines at the start of file content
+  # [IMPL:SHEBANG_DETECTION] [ARCH:SHEBANG_EXTRACTION] [REQ:SHEBANG_HIDING]
+  # Matches the beginning of the first line as '#!' - anything after that matches a shebang
+  # Works directly with raw string segments (not NestedLine objects)
+  def is_shebang_line?(line, is_first_line)
+    return false unless is_first_line
+    line.start_with?('#!')
+  end
+```
+
+### Detection Rules
+- Shebang lines must start with `#!` at the beginning of the line (no leading whitespace)
+- Only the first line of file content is considered (index 0)
+- The line must begin with `#!` - anything after that matches a shebang
+- Detection occurs before import directive processing
+- Each file in nested imports is checked independently
+
+### Edge Cases
+- Empty files: No shebang (no first line)
+- Files starting with whitespace before `#!`: Not recognized as shebang (must be at beginning)
+- Files with only shebang: File becomes effectively empty after filtering
+- Import directives on first line: Shebang takes precedence (shebang is first)
+
+## 7. Shebang Line Filtering Implementation [IMPL:SHEBANG_FILTERING] [ARCH:SHEBANG_EXTRACTION] [REQ:SHEBANG_HIDING]
+
+### Filtering Logic
+```ruby
+# [REQ:SHEBANG_HIDING] Filter shebang lines from processed output
+# [IMPL:SHEBANG_FILTERING] [ARCH:SHEBANG_EXTRACTION] [REQ:SHEBANG_HIDING]
+# Filtering occurs inline during segment reading
+File.readlines(filename, chomp: true).each.with_index do |segment, ind|
+  # Skip shebang lines at the beginning of the file
+  next if @hide_shebang && is_shebang_line?(segment, ind == 0)
+  
+  # Process remaining lines normally
+  # ...
+end
+```
+
+### Implementation Details
+- Filtering occurs inline in `CachedNestedFileReader#readlines` during segment reading
+- Shebang lines are skipped before they are processed into `NestedLine` objects
+- Applied to both direct file reads and nested imports (via recursive calls)
+- Option `hide_shebang` controls filtering behavior
+- When disabled (`hide_shebang: false`), all lines included
+- When enabled (`hide_shebang: true`), first line (index 0) is skipped if it's a shebang
+- Filtering happens at the source, preventing shebang lines from entering the processing pipeline
+- More efficient than post-processing as it avoids creating `NestedLine` objects for shebang lines
+
+### Integration with CachedNestedFileReader
+- Option stored as instance variable `@hide_shebang` set during initialization
+- Filtering applied inline during the `File.readlines` loop before segment processing
+- Shebang detection uses `is_shebang_line?(segment, ind == 0)` where `segment` is the raw string line
+- Cached results already have shebang filtered (if option was enabled during cache)
+- Recursive calls to `readlines` use the same `@hide_shebang` instance variable, ensuring consistent behavior across nested imports
+
+## 8. CLI Option Implementation in Menu System [IMPL:CLI_OPTION_IMPLEMENTATION] [ARCH:CLI_OPTION_DESIGN] [REQ:SHEBANG_HIDING]
+
+### Menu Configuration
+```yaml
+# [REQ:SHEBANG_HIDING] CLI option for hiding shebang lines
+# [IMPL:CLI_OPTION_IMPLEMENTATION] [ARCH:CLI_OPTION_DESIGN] [REQ:SHEBANG_HIDING]
+- :opt_name: hide_shebang
+  :env_var: MDE_HIDE_SHEBANG
+  :description: Hide shebang lines in document output
+  :arg_name: BOOL
+  :default: true
+  :procname: val_as_bool
+```
+
+### Option Access
+- CLI: `--hide-shebang` (enables) / `--no-hide-shebang` (disables)
+- Environment: `MDE_HIDE_SHEBANG=true` or `MDE_HIDE_SHEBANG=false`
+- Configuration file: `hide_shebang: true` in `.mde.yml`
+- Default: `true` (shebang lines hidden by default)
+
+### Option Propagation
+- Option available in `@options` hash via `MarkParse#base_options`
+- Option passed to `CachedNestedFileReader` during initialization or read calls
+- Option value accessible as `options[:hide_shebang]` (boolean)
+
+### Integration Points
+- `MarkParse#base_options`: Includes option in base options hash
+- `CachedNestedFileReader#initialize`: Option passed as parameter (or via options hash)
+- `CachedNestedFileReader#readlines`: Option used to control filtering behavior
+