Implements Web Server & Hardens WFLHASH Security

.augment/rules/Docs.md

@@ -0,0 +1,52 @@
+---
+type: "always_apply"
+description: "Example description"
+---
+
+📂 Where to Put Things
+
+All documentation belongs under docs/ at the project root. If you’re tempted to start a new folder somewhere else, imagine Ritsu smacking your hand away with a drumstick. Centralizing docs makes them easier to find and keeps the repo tidy.
+
+Core language feature docs live in docs/wfldocs/. Each file in this directory should describe a feature that already exists in the language—think variables, control flow, pattern matching, and so on. Name these files with a WFL- prefix followed by a concise, hyphenated description (e.g., WFL-variables.md, WFL-actions.md). Clear, descriptive names and consistent prefixes help readers (and search tools) understand what’s inside
+.
+
+Planned or experimental features go in docs/wflspecs/. These “spec” documents outline features that are proposed but not yet implemented. Use descriptive filenames (a SPEC- prefix is recommended) and include the status (draft, planned, under discussion) at the top. Explain the rationale, proposed syntax, semantics, and any open questions.
+
+A single “living AI document” stays at the root of docs/. This file (for example, wfl-living-ai.md) serves as a constantly‑updated cheat sheet for AI agents building WFL apps. It should summarize current language features, list available modules, and provide guidance on composing WFL code using natural language. Whenever the language or its specs evolve, update this document so AI agents aren’t left playing catch‑up.
+
+🧰 How to Structure Your Docs
+
+When adding or updating documentation, follow these best practices:
+
+Choose the right location. Place user‑facing docs in wfldocs/, planned features in wflspecs/, and keep the living AI document at the root. If your content doesn’t fit neatly into one of these, think again—good organization is half the battle
+
+.
+
+Use consistent naming conventions. File names should be lowercase, hyphen‑separated, and start with an appropriate prefix (WFL- or SPEC-). Avoid cryptic abbreviations. Pretend you’re explaining it to a friend who’s never seen the code
+
+.
+
+Update the index. Whenever you add a new document, make sure it appears in the documentation index (or table of contents) so others can find it
+
+.
+
+Follow the WFL documentation policy and foundation guidelines. Write in a friendly, conversational tone, avoid jargon, and use plenty of examples
+. Your goal is to be a mentor, not a gatekeeper.
+
+Cross‑reference related docs. Link to other relevant pages so readers can explore topics in depth. For example, a spec for pattern matching improvements should link back to the existing WFL-patterns.md.
+
+Provide clear, actionable information. Use natural language to describe concepts, prioritize clarity over brevity, and make documentation accessible to beginners
+
+. If your doc reads like a textbook, lighten it up—imagine you’re explaining it over coffee.
+
+✍️ Writing Style and Tone
+
+The WFL docs should feel like a conversation with a knowledgeable friend. Keep sentences short, avoid obscure terminology, and include examples wherever possible. Stick to natural language syntax and minimize unnecessary symbols. Remember that WFL is designed for humans first, computers second.
+
+Use a warm, encouraging tone. Explain concepts step‑by‑step and invite readers to experiment. When showing code, favor plain English constructs over terse symbols. For example, “Let the age be 25” is preferable to “int age = 25;”
+
+🔄 Keeping Docs Up to Date
+
+Documentation is a living system, not a one‑time dump. Review your docs regularly to ensure they match the current implementation and planned features. Update the living AI document whenever the language evolves. If a spec graduates to a full feature, move it from wflspecs/ into wfldocs/ and rename it with a WFL- prefix.
+
+Always track changes through version control and include a summary of updates so others understand what’s new. Encourage feedback and contributions from the community—fresh eyes catch mistakes and spark new ideas.

.augment/rules/Fundimentals.md

@@ -0,0 +1,115 @@
+---
+type: "always_apply"
+---
+
+WebFirst Language (WFL) Project Statement and Guiding Principles (Version 2)
+Project Statement
+The WebFirst Language (WFL) is a pioneering programming language designed to revolutionize web development by making it intuitive, accessible, and aligned with human communication. By leveraging natural-language patterns in its syntax and minimizing the use of special characters, WFL bridges the gap between how people think and how code is written. The language empowers developers of all experience levels—beginners and experts alike—to create clear, readable, and maintainable web applications. WFL’s mission is to lower the barriers to programming, foster a collaborative community rooted in clarity and simplicity, and provide robust tools that support creativity and innovation in the global developer ecosystem.
+Guiding Principles
+The following principles have been refined and expanded to enhance WFL’s accessibility, practicality, and power, drawing inspiration from languages like Inform 7, EnglishScript, and Elm, as well as best practices in modern web development.
+1. Natural-Language Syntax
+
+    Description: Embrace a syntax that mirrors natural language to make coding intuitive, incorporating features like type inference and relation definitions (e.g., "The button is clickable" implies a type and property). Reduce reliance on special characters by favoring words and phrases.
+    Goal: Lower the learning curve for beginners and improve readability for all developers by using familiar, English-like constructs.
+
+2. Minimize Use of Special Characters
+
+    Description: Eliminate special characters (e.g., ,, <, >, @, ^, %, &, *, (, ), _, +, !, #, $) unless they serve a clear, necessary purpose. Allow intuitive symbols (e.g., + for addition) alongside word-based alternatives (e.g., "plus") for conciseness where widely understood.
+    Goal: Simplify coding by prioritizing words over symbols, making the language less intimidating and more approachable for newcomers.
+
+3. Readability and Clarity
+
+    Description: Prioritize code that is easy to read and understand over terse or cryptic expressions, using natural-language constructs to clearly convey intent (e.g., "Add a paragraph to the page" vs. document.createElement('p')).
+    Goal: Enhance maintainability and collaboration by ensuring code is self-explanatory.
+
+4. Clear and Actionable Error Reporting
+
+    Description: Provide user-friendly, context-aware error messages inspired by Elm, offering specific guidance and solutions (e.g., "Expected a number but found text—try converting it first").
+    Goal: Enable developers to quickly identify and resolve issues, boosting productivity and confidence.
+
+5. Type Safety and Compatibility
+
+    Description: Enforce strict type checking with support for type inference where practical (e.g., "Let age be 25" infers age as a number), ensuring operations are performed on compatible data types.
+    Goal: Prevent runtime errors and improve code reliability while maintaining flexibility.
+
+6. Support for Modern Features
+
+    Description: Incorporate advanced constructs like asynchronous operations and pattern matching, expressed naturally (e.g., "Wait for the server response, then show it" for async tasks).
+    Goal: Equip developers with tools to handle complex web development scenarios efficiently and intuitively.
+
+7. Interoperability with Web Standards
+
+    Description: Ensure seamless integration with existing web technologies, such as JavaScript libraries, CSS, and HTML, allowing WFL to compile to or interact with these standards.
+    Goal: Leverage the web ecosystem to make WFL practical and adoptable for real-world projects.
+
+8. Built-in Security Features
+
+    Description: Embed security best practices into the language, such as automatic output escaping (e.g., to prevent XSS) and secure coding patterns by default.
+    Goal: Enable developers, especially beginners, to write secure code effortlessly, reducing common web vulnerabilities.
+
+9. Accessibility for Beginners
+
+    Description: Design features that are approachable and easy to learn, such as "Let name be 'Alice'" instead of var name = 'Alice';.
+    Goal: Remove entry barriers to programming and encourage novices to start coding with confidence.
+
+10. Expressiveness for Experienced Developers
+
+    Description: Provide powerful, concise features (e.g., pattern matching, relation definitions) that allow sophisticated coding without excessive verbosity.
+    Goal: Empower seasoned developers to write advanced, efficient code tailored to complex needs.
+
+11. Balanced Simplicity and Power
+
+    Description: Strike a balance where the language remains simple to use yet retains robust capabilities for diverse applications.
+    Goal: Avoid overwhelming users with complexity while ensuring functionality for large-scale projects.
+
+12. Community and Collaboration
+
+    Description: Foster a community that values sharing, collaboration, and mutual learning through clear, understandable code.
+    Goal: Promote best practices and collective growth within the developer ecosystem.
+
+13. Performance Optimization
+
+    Description: Optimize performance with features like short-circuit evaluation and caching, implemented transparently to the user.
+    Goal: Ensure efficient applications without requiring developers to manually optimize code.
+
+14. Integration with Standard Libraries
+
+    Description: Provide a comprehensive standard library that aligns with WFL’s natural-language syntax (e.g., "Fetch data from 'api/users'").
+    Goal: Offer essential tools and functions that complement the language’s design and simplify common tasks.
+
+15. Scalability and Maintainability
+
+    Description: Support the development of both small scripts and large-scale applications with modular, maintainable code structures.
+    Goal: Enable projects to evolve over time without necessitating rewrites or creating maintenance challenges.
+
+16. Gradual Learning Curve
+
+    Description: Introduce advanced concepts progressively, allowing users to start with basics (e.g., "Show 'Hello'") and later adopt complex features (e.g., async operations).
+    Goal: Facilitate a smooth learning journey from novice to expert.
+
+17. Error Transparency
+
+    Description: Make error handling and debugging straightforward, with transparent processes and clear feedback.
+    Goal: Reduce frustration and build trust in the language by simplifying issue resolution.
+
+18. Encouragement of Best Practices
+
+    Description: Promote coding standards that lead to high-quality, maintainable code (e.g., clear naming, consistent structure).
+    Goal: Improve code quality and minimize technical debt across projects.
+
+19. Avoidance of Unnecessary Conventions
+
+    Description: Challenge traditional programming conventions that rely on special characters or legacy practices without clear justification (e.g., avoiding mandatory semicolons).
+    Goal: Innovate language design to align with natural communication and modern needs.
+
+Key Enhancements in Version 2
+This v2 spec refines WFL’s principles based on research and analysis:
+
+    Natural-Language Focus: Enhanced with type inference and relation definitions, inspired by Inform 7, for greater expressiveness (e.g., "The door is open" defines state and type).
+    Special Characters: Clarified to allow intuitive symbols optionally, balancing accessibility with conciseness.
+    New Principles: Added Interoperability with Web Standards and Built-in Security Features to address real-world web development needs.
+    Implementation: Suggests practical examples like "Wait for the response, then display it" for async tasks and Elm-inspired error messages for usability.
+    Balance: Ensures simplicity for beginners (e.g., minimal syntax) while offering power for experts (e.g., advanced features).
+
+Conclusion
+The WebFirst Language (WFL) v2 refines its guiding principles to create a language that is both accessible and powerful, ideal for modern web development. By emphasizing natural-language syntax, minimizing special characters, and integrating interoperability and security, WFL lowers barriers for beginners while providing robust tools for experienced developers. Drawing from languages like Inform 7, EnglishScript, and Elm, WFL aims to transform programming into an intuitive, inclusive, and innovative experience, fostering a vibrant global developer community.

.gitignore

@@ -120,6 +120,10 @@ pids
 *_debug.txt
 wfl_exec.log
 
+# Temporary test files
+temp_test_*.wfl
+temp_test_*_debug.txt
+
 # Python cache (for Tools/ directory)
 __pycache__/
 *.py[cod]

CLAUDE.md

@@ -0,0 +1,144 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Common Development Commands
+
+### Building and Testing
+```bash
+# Build debug version
+cargo build
+
+# Build release version (REQUIRED for integration tests)
+cargo build --release
+
+# Run all tests
+cargo test
+
+# Run integration tests (requires release build)
+# Windows:
+.\scripts\run_integration_tests.ps1
+# Linux/macOS:
+./scripts/run_integration_tests.sh
+
+# Run specific integration test
+cargo test --test split_functionality
+
+# Format code
+cargo fmt --all
+
+# Run linter
+cargo clippy --all-targets --all-features -- -D warnings
+```
+
+### WFL Language Commands
+```bash
+# Run WFL program
+wfl program.wfl
+
+# Lint WFL code
+wfl --lint program.wfl
+
+# Auto-fix WFL code
+wfl --fix program.wfl --in-place
+
+# Debug WFL execution
+wfl --debug program.wfl
+
+# Show tokens/AST
+wfl --lex program.wfl
+wfl --parse program.wfl
+
+# Check configuration
+wfl --configCheck
+```
+
+### VSCode Extension
+```bash
+# Install WFL VSCode extension
+scripts/install_vscode_extension.ps1
+```
+
+## Architecture Overview
+
+WFL is a natural language programming language implemented in Rust with a traditional compiler pipeline enhanced for async execution.
+
+### Core Processing Pipeline
+```
+Source Code → Lexer → Parser → Analyzer → Type Checker → Interpreter
+              ↓       ↓         ↓           ↓              ↓
+            Tokens   AST    Validated   Type Info    Execution
+```
+
+### Key Components
+
+- **Lexer** (`src/lexer/`): High-performance tokenization using Logos crate
+- **Parser** (`src/parser/`): Recursive descent parser with natural language constructs and error recovery
+- **Analyzer** (`src/analyzer/`): Semantic validation and static analysis
+- **Type Checker** (`src/typechecker/`): Static type analysis with intelligent inference
+- **Interpreter** (`src/interpreter/`): Async-capable direct AST execution using Tokio runtime
+- **Standard Library** (`src/stdlib/`): Built-in modules (core, math, text, list, filesystem, crypto, etc.)
+- **LSP Server** (`wfl-lsp/`): Language Server Protocol implementation for IDE integration
+- **Development Tools**: Linter, code fixer, analyzer with real-time error checking
+
+### Workspace Structure
+- Root crate `wfl` contains the main compiler/interpreter
+- `wfl-lsp/` workspace member provides Language Server Protocol support
+- `vscode-extension/` provides VSCode language support
+- `TestPrograms/` contains WFL test programs that MUST all pass
+- `tests/` contains Rust unit and integration tests
+- `Docs/` contains all user-facing documentation
+
+## Critical Development Rules
+
+### Test-Driven Development (MANDATORY)
+**TDD is as critical as backward compatibility. Every change MUST start with a failing test.**
+
+1. **Write failing tests FIRST** for any feature or bug fix
+2. **Confirm tests fail** before writing implementation
+3. **Never modify tests to make them pass** - fix the implementation instead
+4. All TestPrograms/*.wfl files MUST pass after any change
+
+### Backward Compatibility
+**NEVER BREAK EXISTING WFL PROGRAMS**. WFL has a backward compatibility promise:
+- All existing WFL code must continue to work
+- Run ALL TestPrograms after changes
+- If implementing parser features, also update bytecode
+
+### Integration Test Requirements
+Integration tests require the **release binary** (`target/release/wfl.exe` on Windows, `target/release/wfl` on Unix):
+- Always run `cargo build --release` before integration tests
+- Use provided scripts: `scripts/run_integration_tests.ps1` or `scripts/run_integration_tests.sh`
+- If tests fail with "path not found", you need to build the release binary
+
+### Configuration System
+WFL uses `.wflcfg` files for project configuration:
+- Supports execution settings (timeouts, logging)
+- Code style settings (line length, indentation)
+- Global config can be overridden with `WFL_GLOBAL_CONFIG_PATH`
+
+### Key Language Features
+- **Natural Language Syntax**: `store name as "value"`, `check if x is greater than 5`
+- **Type Safety**: Static typing with intelligent type inference
+- **Async Support**: Built-in async/await using Tokio runtime
+- **Error Handling**: Comprehensive try/when/otherwise error handling
+- **Standard Library**: Math, text, list, filesystem, crypto, and web modules
+
+### Memory and Performance
+- Uses WFLHASH custom cryptographic hash function (see security reviews)
+- Optional heap profiling with dhat feature flags
+- Async-capable interpreter for concurrent operations
+- Memory optimization for large programs
+
+### Documentation Standards
+- All documentation in `Docs/` folder
+- Update README.md with significant changes
+- Component documentation required for all major modules
+- Dev diary entries for significant changes in `Dev diary/`
+
+### Cursor Rules Integration
+The codebase includes Cursor IDE rules in `.cursor/rules/wfl-rules.mdc`:
+- Always read README.md first
+- Update documentation with changes
+- All test programs must pass
+- Update bytecode when modifying parser