scriptorium 0.0.3 → 0.7.2

data/doc/anti-amnesia/20250804-190700-anti-amnesia-timestamping-fix.md

@@ -0,0 +1,27 @@
+# Anti-Amnesia Timestamping Fix
+
+**Date**: 2025-08-04 19:07:00  
+**Issue**: Anti-amnesia file created with incorrect timestamp in filename  
+**Status**: Fixed
+
+## Problem
+The file `20250728-143000-cognitive-loop-bug.md` was created today (August 4th, 2025) but had an incorrect timestamp in its filename showing July 28th, 2025.
+
+## Root Cause
+The anti-amnesia system appears to have used an old timestamp when creating the file, possibly from:
+- Cached timestamp from previous session
+- System clock issues
+- Manual timestamp entry error
+
+## Solution
+Renamed the file to use the correct current timestamp:
+- **From**: `20250728-143000-cognitive-loop-bug.md`
+- **To**: `20250804-190500-cognitive-loop-bug.md`
+
+## Prevention
+- Anti-amnesia files should always be created with the CURRENT timestamp
+- Use `date +%Y%m%d-%H%M%S` format for consistent timestamping
+- Verify timestamp accuracy before creating files
+
+## Key Takeaway
+Always use current timestamps when creating anti-amnesia files to maintain accurate chronological order and prevent confusion. 

data/doc/anti-amnesia/20250807-213025.md

@@ -0,0 +1,116 @@
+
+# Livetext Knowledge Summary
+
+## Overview
+Livetext is a text processing system that transforms plain text files into HTML output. It's designed to be simple and non-Turing-complete, supporting minimal nesting and currently no branching. It's used extensively in projects like Scriptorium (a blogging tool).
+
+## Core Architecture
+- Main class: `Livetext` (in lib/livetext/core.rb)
+- Previously had a circular dependency between `Livetext` and `Processor` classes
+- Recently refactored to merge `Processor` into `Livetext` to eliminate circular dependency
+- Uses a stack-based source management system (`@sources`) for handling nested includes
+
+## Key Components
+1. **Livetext::Core** - Main processing class
+2. **Livetext::Standard** - Built-in dot commands (lib/livetext/standard.rb)
+3. **Livetext::Expansion** - Variable and function expansion (lib/livetext/expansion.rb)
+4. **Livetext::UserAPI** - API for dot commands (lib/livetext/userapi.rb)
+5. **Livetext::VariableManager** - Manages variables
+6. **Livetext::HTML** - HTML generation utilities
+
+## Processing Methods
+- `process(text: nil, file: nil, vars: {})` - New unified method, returns [body, vars]
+- `transform(text)` - Legacy method, returns body only
+- `xform(*args, file: nil, text: nil, vars: {})` - Legacy wrapper
+- `xform_file(file, vars: nil)` - Legacy wrapper
+
+## Dot Commands
+Dot commands start with `.` and control Livetext's behavior. They can have different parameter signatures:
+
+1. **No parameters**: `.def mymeth`
+2. **Args + data**: `.def mymeth args`
+3. **Args + data + body**: `.def mymeth body`
+4. **Args + data + raw body**: `.def mymeth body raw` (NEW)
+
+Examples:
+- `.set VAR="value"` - Set variables
+- `.h1 Title` - Generate HTML headings
+- `.def mymethod` - Define custom methods
+- `.include file.inc` - Include other files
+- `.func myfunction` - Define functions
+
+## Functions
+Functions are called with `$$funcname[param]` syntax:
+- `$$func[]` - Passes empty string `""` as parameter
+- `$$func[""]` - Passes literal empty string `'""'` as parameter
+- `$$func[value]` - Passes `value` as parameter
+
+Functions are never passed `nil` - empty brackets result in empty string.
+
+## Variables
+- Set with `.set VAR="value"`
+- Referenced with `$VAR`
+- Built-in variables should be capitalized
+- Variables are shared across nested includes
+
+## Includes and Nesting
+- `.include file.inc` - Include other files
+- Supports arbitrary levels of nesting
+- Uses stack-based source management (`@sources`)
+- Variables and functions are preserved through includes
+
+## Plugin System
+- Plugins in `plugin/` directory
+- Imports in `imports/` directory
+- Loaded via `Livetext.customize(mix: "plugin_name")`
+- Plugins can define new dot commands and functions
+
+## Recent Refactoring Changes
+1. **Eliminated circular dependency**: Merged `Processor` into `Livetext`
+2. **Fixed double-reading**: Methods now use passed parameters instead of calling `api.body()` again
+3. **New body raw syntax**: `.def mymeth body raw` for raw body content
+4. **Updated method signatures**: Explicit parameter declarations
+5. **Unified processing API**: New `process()` method returns both body and variables
+
+## API Changes-
+- `@parent.body` → `self.body` (in plugins)
+- `live.vars.vars` → `live.variables.to_h` or `live.vars.to_h`
+- `live.xform_file()` → `live.process(file: file)` (recommended)
+
+## Testing
+- Comprehensive test suite in `test/` directory
+- Snapshot tests in `test/snapshots/`
+- Unit tests in `test/unit/`
+- All 154 tests currently passing
+- Plugin testing not yet implemented
+
+## Usage Patterns
+Old pattern:
+```ruby
+live = Livetext.customize(mix: "plugin", call: ".nopara", vars: vars)
+text = live.xform_file(content_file)
+vars = live.vars.vars
+```
+
+New pattern (recommended):
+```ruby
+live = Livetext.customize(mix: "plugin", call: ".nopara", vars: vars)
+body, vars = live.process(file: content_file)
+```
+
+## Key Files
+- `lib/livetext/core.rb` - Main Livetext class
+- `lib/livetext/standard.rb` - Built-in dot commands
+- `lib/livetext/expansion.rb` - Variable/function expansion
+- `lib/livetext/helpers.rb` - Helper methods
+- `lib/livetext/userapi.rb` - User API
+- `test/all.rb` - Test runner
+
+## Known Limitations
+- Not Turing-complete
+- Limited nesting support
+- No branching (if/else)
+- Plugin system needs dedicated testing
+
+This summary represents the current state after the major refactoring that eliminated circular dependencies and improved the architecture significantly.
+

data/doc/anti-amnesia/20250901-211714-codemirror-integration-and-web-tests.md

@@ -0,0 +1,172 @@
+# CodeMirror Integration and Web Test Framework
+
+**Date**: 2024-12-19 16:00:00
+
+## CodeMirror Integration
+
+### Overview
+Integrated CodeMirror code editor into the web interface for enhanced post and page editing with LiveText syntax highlighting.
+
+### Files Created/Modified
+
+#### `test/manual/codemirror_demo.html`
+- Standalone HTML demo showcasing CodeMirror with custom LiveText syntax highlighting
+- Includes macro toolbar with buttons for common editing tasks
+- Demonstrates LiveText-specific syntax rules (non-terminating markers, bracketed formatting, etc.)
+- Features responsive SVG banner generation and theme switching
+
+#### `ui/web/app/assets/livetext_mode.js`
+- Custom CodeMirror mode definition for LiveText syntax
+- Handles LiveText-specific constructs:
+  - Variables (`$foo`, `$foo.bar`) - stops at invalid characters
+  - Functions (`$$max`, `$$link:param`, `$$index[param]`)
+  - Markers (`*`, `_`, `` ` ``, `~`) - non-terminating, space/comma/period terminated
+  - Bracketed formatting (`*[bold text]`)
+  - Dot commands (`.h1`, `.list`, `.banner`, etc.)
+  - Block structures:
+    - `.raw`...`__RAW__` (plain text)
+    - `.comment`...`.end` (plain text)
+    - `.def`/`.func`...`.end` (Ruby code)
+    - `.code ruby`/`elixir`/`bash`...`.end` (language-specific highlighting)
+
+#### `ui/web/app/views/edit_post.erb`
+- Integrated CodeMirror for post editing
+- Replaces textarea with enhanced editor
+- Includes LiveText syntax highlighting
+- Form submission syncs CodeMirror content back to hidden textarea
+
+#### `ui/web/app/views/edit_pages.erb`
+- Integrated CodeMirror for page editing
+- Similar functionality to edit_post.erb
+- Button-triggered save with explicit content syncing
+
+#### `ui/web/app/app.rb`
+- Added `/web_assets/*` route to serve CodeMirror assets
+- Fixed post creation workflow to redirect to edit page
+- Enhanced error handling and debugging
+
+### Key Features
+- **Syntax Highlighting**: Custom LiveText mode with accurate tokenization
+- **Macro System**: Toolbar buttons for common editing tasks
+- **Responsive Design**: Adapts to different screen sizes
+- **Theme Support**: Light/dark mode switching
+- **Content Syncing**: Seamless integration with existing form submission
+
+## Web Test Framework
+
+### Overview
+Comprehensive automated testing framework for web interface functionality, covering complete user workflows.
+
+### Files Created
+
+#### `test/web_test_helper.rb`
+- Shared helper module for web integration tests
+- Provides methods for:
+  - Starting/stopping web server
+  - Making HTTP requests (GET, POST)
+  - Asserting response types (success, redirect)
+  - Managing test repository
+- Silent operation (no debug output)
+
+#### `test/web_integration_test.rb`
+- Basic web integration tests
+- Verifies core functionality and test mode
+- Tests repository creation, view management, basic navigation
+
+#### `test/web_workflow_test.rb`
+- Comprehensive workflow tests covering:
+  - **Post Creation**: Create post via web interface, verify redirect to edit page
+  - **Post Editing**: Edit post content, save, verify file content matches
+  - **Publish/Unpublish**: Toggle post status, verify API response and HTML display
+  - **Delete/Restore**: Delete post (strikethrough), restore (normal display)
+  - **Asset Management**: Upload and manage assets
+  - **View Configuration**: Configure view settings
+  - **Deployment**: Deploy configuration workflow
+  - **Error Handling**: Edge cases and error conditions
+
+#### `test/web_test_mode_simple_test.rb`
+- Simple test to verify web app test mode functionality
+- Uses curl-based verification of test repository usage
+
+### Test Coverage
+
+#### API Level Testing
+- HTTP status codes (200, 302, 303, 404, 500)
+- JSON response validation
+- Redirect behavior verification
+- Error handling and edge cases
+
+#### UI Level Testing
+- HTML content verification
+- Visual state changes (published/unpublished status)
+- Strikethrough styling for deleted posts
+- Form submission and content persistence
+
+#### Workflow Testing
+- Complete user journeys from start to finish
+- Cross-page navigation and state persistence
+- File system verification (actual file content)
+- Database/metadata verification
+
+### Key Features
+- **Fully Automated**: No manual intervention required
+- **Silent Operation**: No debug output, only errors shown
+- **Comprehensive Coverage**: Tests both API and UI layers
+- **Real File Verification**: Checks actual file content, not just responses
+- **Test Mode Support**: Uses separate test repository (`ui/web/scriptorium-TEST`)
+- **Parallel Safe**: Each test creates fresh test environment
+
+### Integration
+- Added to `test/all` for inclusion in full test suite
+- Follows existing project testing patterns (Minitest)
+- Uses same helper patterns as TUI integration tests
+- Maintains consistency with project coding standards
+
+## Benefits
+
+### CodeMirror Integration
+- Enhanced editing experience with syntax highlighting
+- Reduced editing errors through visual feedback
+- Familiar code editor interface for users
+- Extensible macro system for common tasks
+
+### Web Test Framework
+- Catches regressions in web interface functionality
+- Verifies complete user workflows, not just individual components
+- Provides confidence in web interface reliability
+- Enables safe refactoring and feature additions
+- Documents expected behavior through test cases
+
+## Usage
+
+### Running Web Tests
+```bash
+# Run all web tests
+ruby test/web_workflow_test.rb
+ruby test/web_integration_test.rb
+
+# Run specific test
+ruby test/web_workflow_test.rb -n test_004_post_editing_workflow
+
+# Run as part of full test suite
+ruby test/all
+```
+
+### CodeMirror Demo
+Open `test/manual/codemirror_demo.html` in browser to see LiveText syntax highlighting and macro functionality.
+
+## Technical Notes
+
+### LiveText Syntax Rules
+- Markers are non-terminating (unlike Markdown)
+- Single vs. double markers differ only in termination (space vs. comma/period)
+- Bracketed formatting allows multi-word formatting
+- Variables and functions have specific naming rules
+- Block structures have different body processing rules
+
+### Test Architecture
+- Uses `WebTestHelper` module for shared functionality
+- Each test creates fresh test environment
+- Tests verify both API responses and HTML content
+- File system verification ensures actual persistence
+- Silent operation focuses on genuine errors only

data/doc/anti-amnesia/20250902-002402-backup-restore-system.md

@@ -0,0 +1,126 @@
+# Backup/Restore System Implementation
+
+## Overview
+Implemented a comprehensive backup and restore system for Scriptorium repositories with full/incremental backups, hybrid restore strategies, and 30-day retention.
+
+## Architecture
+
+### Storage Structure
+```
+repo/backups/
+├── manifest.txt          # Backup registry
+└── data/                 # Backup content
+    ├── 20250902-120000-full/
+    ├── 20250902-130000-incr/
+    └── 20250902-140000-incr/
+```
+
+### Manifest Format
+```
+20250902-120000-full Initial full backup
+20250902-130000-incr Added new post
+20250902-140000-incr Updated existing post
+```
+
+### Flat File Structure
+Each backup directory contains files with full relative paths:
+```
+data/20250902-120000-full/
+├── posts/0001/source.lt3
+├── posts/0001/meta.txt
+├── views/sample/config.txt
+└── config/repo.txt
+```
+
+## Core Features
+
+### Backup Types
+- **Full Backup**: Complete repository snapshot
+- **Incremental Backup**: Only changed files since last backup
+
+### Change Detection
+- Uses `File.mtime` to identify modified files
+- 1-second sleep before backup creation ensures distinct timestamps
+- Compares file modification times against last backup timestamp
+
+### Restore Strategies
+- **`:safe`** (default): Creates pre-restore backup, then restores
+- **`:merge`**: Overlays backup content on existing files
+- **`:destroy`**: Clears repository and restores from backup
+
+### Dependency Management
+- Always preserves most recent full backup (30-day retention)
+- Restore finds most recent full backup before target
+- Applies all subsequent incremental backups up to target
+- Handles missing dependencies gracefully
+
+## API Methods
+
+### `create_backup(type: :full|:incr, description: nil)`
+- Creates timestamped backup directory
+- Records entry in manifest.txt
+- Handles both full and incremental backups
+
+### `list_backups()`
+- Returns array of backup info: `{timestamp, type, description}`
+- Parses manifest.txt entries
+
+### `restore_backup(timestamp, strategy: :safe)`
+- Implements hybrid restore strategies
+- Finds dependency chain (full + incrementals)
+- Preserves existing files in merge mode
+
+### `delete_backup(timestamp)`
+- Removes backup directory and manifest entry
+- Enforces retention policy (keeps most recent full)
+
+## Key Implementation Details
+
+### Timestamp Precision
+- Uses `Time.now.strftime("%Y%m%d-%H%M%S")` for directory names
+- 1-second sleep before backup creation prevents sub-second conflicts
+- Temporary directory creation + rename ensures atomic operations
+
+### Error Handling
+- Contract system validation (enabled in tests)
+- Graceful handling of missing dependencies
+- Clear error messages for invalid operations
+
+### Test Coverage
+- 16 comprehensive tests covering all scenarios
+- Tests for full/incremental backups, restore strategies, edge cases
+- 100% pass rate with proper contract system integration
+
+## Usage Examples
+
+```ruby
+# Create full backup
+api.create_backup(type: :full, description: "Before major changes")
+
+# Create incremental backup
+api.create_backup(type: :incr, description: "Added new post")
+
+# List available backups
+backups = api.list_backups
+
+# Restore with safe strategy (default)
+api.restore_backup("20250902-120000-full")
+
+# Restore with merge strategy
+api.restore_backup("20250902-130000-incr", strategy: :merge)
+
+# Delete old backup
+api.delete_backup("20250902-120000-full")
+```
+
+## Files Modified
+- `lib/scriptorium/api.rb`: Core backup/restore implementation
+- `test/unit/backup_test.rb`: Comprehensive test suite
+- `test/all`: Added backup tests to full test suite
+
+## Status
+✅ **Complete and Production Ready**
+- All 16 tests passing
+- Full test suite integration
+- Comprehensive error handling
+- 30-day retention policy implemented

data/doc/anti-amnesia/20250907-203339-backup-metadata-implementation.md

@@ -0,0 +1,66 @@
+# Backup Metadata Implementation - 2025-09-07 20:33:39
+
+## Overview
+Added per-backup metadata storage to track version information and backup statistics for better debugging, compatibility checking, and audit trails.
+
+## Changes Made
+
+### 1. Backup Location Change
+- **Changed backup storage location** from `repo/backups/` to `backup-scriptorium/` (parallel to repo)
+- **Test repositories** use `backup-scriptorium-TEST/` 
+- **Updated `get_backup_directory()` method** to handle both production and test environments
+- **Made method public** (was private) to allow direct access without `api.send()`
+
+### 2. Per-Backup Metadata File
+- **Added `backup-info.txt`** to each backup directory (both full and incremental)
+- **Contains essential metadata**:
+  - Scriptorium version (from `Scriptorium::VERSION`)
+  - LiveText version (from `livetext -v` command)
+  - Ruby version (from `RUBY_VERSION`)
+  - Backup type (full/incremental)
+  - Backup name (timestamp-type)
+  - Repository path (which repo was backed up)
+  - File count (number of files backed up)
+  - Total size (backup size in bytes)
+  - Platform (OS and Ruby engine)
+  - Git commit (first 8 characters, if available)
+
+### 3. Implementation Details
+- **`create_backup_info()` method** - Creates the metadata file
+- **`get_livetext_version()` method** - Gets LiveText version via command line
+- **`get_git_commit_hash()` method** - Gets git commit hash if available
+- **`count_files_in_backup()` method** - Counts files in backup directory
+- **`calculate_directory_size()` method** - Calculates total backup size
+- **Called after backup creation** but before final directory rename
+
+### 4. Test Updates
+- **Added backup info file assertions** to both full and incremental backup tests
+- **Verifies file existence** and content validation
+- **All 16 backup tests pass** with new functionality
+
+## Benefits
+- **Restore validation** - Check compatibility before restoring
+- **Debugging** - Know exactly what versions were used
+- **Migration help** - Understand what needs updating  
+- **Audit trail** - Track backup environment over time
+- **Better error diagnosis** - Version mismatch detection
+
+## Files Modified
+- `lib/scriptorium/api.rb` - Added backup metadata functionality
+- `test/unit/backup_test.rb` - Added backup info file tests
+
+## Example Backup Info File
+```
+# Scriptorium Backup Information
+# Generated: 2025-09-07 20:32:33
+scriptorium_version: 0.6.1
+livetext_version: 0.9.60
+ruby_version: 3.2.3
+backup_type: full
+backup_name: 20250907-203233-full
+repository_path: test/scriptorium-TEST
+file_count: 110
+total_size: 138338
+platform: x86_64-darwin22 ruby
+git_commit: 3b5bcc67
+```

data/doc/banner_svg_config.md

@@ -0,0 +1,114 @@
+# BannerSVG Configuration Options
+
+This document describes all configuration options available for customizing SVG banners using BannerSVG.
+
+---
+
+## Background Options
+
+### `back.color <color>`
+Solid color background.
+- Example: `back.color #FF6B6B`
+
+### `back.linear <start> <end> [direction]`
+Linear gradient background.
+- `start`, `end`: Colors (hex or CSS names)
+- `direction` (optional):
+  - `lr` (left-right, default)
+  - `tb` (top-bottom)
+  - `ul-lr` (upper-left to lower-right)
+  - `ll-ur` (lower-left to upper-right)
+- Example: `back.linear #FF6B6B #4ECDC4 lr`
+
+### `back.radial <start> <end> [cx cy r [ar]]`
+Radial gradient background.
+- `start`, `end`: Colors
+- `cx`, `cy`: Center (default: `50% 50%`)
+- `r`: Radius (default: `50%`)
+- `ar`: Aspect ratio compensation (default: `1/aspect` for circular vignette)
+  - Example: `back.radial #FF6B6B #4ECDC4 50% 50% 150%`
+  - Example with custom aspect: `back.radial #FF6B6B #4ECDC4 75% 25% 60% 0.5`
+
+### `back.image <url>`
+Image background. The image should match the banner's aspect ratio for best results.
+- Example: `back.image /assets/banner.jpg`
+
+---
+
+## Banner Geometry
+
+### `aspect <number>`
+Set the banner's aspect ratio (width/height).
+- Example: `aspect 5.0` (for a 5:1 banner)
+
+---
+
+## Font and Text Options
+
+### `text.font <font-family>`
+Set the font family for both title and subtitle.
+- Example: `text.font Verdana`
+
+### `text.color <color>`
+Set the default text color for both title and subtitle.
+- Example: `text.color #222222`
+
+### `title.color <color>` / `subtitle.color <color>`
+Set the color for title or subtitle individually.
+- Example: `title.color #FF0000`
+
+### `title.scale <number>` / `subtitle.scale <number>`
+Scale the font size for title or subtitle (relative to base size).
+- Example: `title.scale 1.2`
+
+### `title.style <style>` / `subtitle.style <style>`
+Set font style for title or subtitle. Options: `bold`, `italic`, or both.
+- Example: `title.style bold italic`
+
+### `title.align <direction> [x y]` / `subtitle.align <direction> [x y]`
+Align title or subtitle. Directions: `left`, `center`, `right`. Optionally override x/y positions.
+- Example: `title.align center`
+- Example: `subtitle.align right 95% 80%`
+
+### `title.xy <x> <y>` / `subtitle.xy <x> <y>`
+Set explicit x/y coordinates for title or subtitle (overrides align).
+- Example: `title.xy 50% 52%`
+
+### `text.align <direction>`
+Set alignment for both title and subtitle at once.
+- Example: `text.align center`
+
+---
+
+## Advanced/Other Options
+
+### `preserve_aspect <value>`
+Override the SVG's `preserveAspectRatio` attribute. Usually not needed.
+- Example: `preserve_aspect xMidYMid slice`
+
+---
+
+## Example Config
+
+```
+# BannerSVG Example Config
+aspect 5.0
+back.radial #FF6B6B #4ECDC4 50% 50% 150%
+text.font Verdana
+text.color #222222
+
+title.color #FFFFFF
+title.scale 1.2
+title.style bold italic
+title.align center
+
+title.xy 50% 52%
+subtitle.color #4ECDC4
+subtitle.scale 0.6
+subtitle.style italic
+subtitle.align right 95% 80%
+```
+
+---
+
+For more details or advanced usage, see the code or ask for help! 

data/doc/contrib.lt3

@@ -0,0 +1,8 @@
+Layout of files and classes
+Conventions and style
+How to...
+- add a dot command
+- add a livetext function
+- create a widget
+- create a theme
+- add tests