language-operator 0.1.30 → 0.1.31

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c31089cce835003d727a915a79d0ddf4a3fe1300dee6027ec842e6ef8dc5361b
-  data.tar.gz: e6450b3f1a2c898247b1dc01d543086881371939549889fbfcb7d6d8c8c992a0
+  metadata.gz: eb53d7e9ca7cceedb04334c17bcfde8c976f94916c2da54c35de1dee3884444e
+  data.tar.gz: 0b71cd8e346ae4a058806e5db91165a1a5cd24c63bd9b68fd361b430cd333131
 SHA512:
-  metadata.gz: 61f3a17c1e9b7369e18a686a9fcd02af26f0e66a7f7a9e24540e6695532390c931cfc426a3f8e67e6cbf2ad5a71a98dfaa0c2564cd4819a3d8c85af99bd70040
-  data.tar.gz: ecb13cc62fba6fe0e2a7f05e383727680c9c8d34fefc6522fdafea07947373117cacda56b8c36c88bfb460b0d1a627d3ca45b561893026ac652e517bbf12af73
+  metadata.gz: 85349b922729847281abeadcf0bc27a0abff89034c97ffe01d0c8b1adfd97db104622c9f9bb4a9f16e65b90e9ad22dd6c6ede84c61714e210b2da72b3c7050e0
+  data.tar.gz: d2daaeb57d6ce2fbe50e231980d306e5b5bd4b592cade3bbf3a92df15b3733db53b6f12c693c68af5ee82d27f5f6902aab724c80ef589d0ed7733719018469df

data/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Schema Version Method**: Added `LanguageOperator::Dsl::Schema.version` method that returns the current schema version (linked to gem version)
+- **Schema Versioning Documentation**: Added comprehensive `docs/dsl/SCHEMA_VERSION.md` documenting versioning policy, semantic version semantics for schema changes, compatibility rules, and deprecation policy
+- **Schema Export CLI Commands**: New `aictl system schema` command for exporting DSL schema
+  - Export as JSON Schema v7 (default): `aictl system schema`
+  - Export as YAML: `aictl system schema --format yaml`
+  - Export as OpenAPI 3.0.3 spec: `aictl system schema --format openapi`
+  - Show version only: `aictl system schema --version`
+- **Synthesis Template Management**: New `aictl system synthesis-template` command for managing code generation templates
+  - Export agent synthesis template: `aictl system synthesis-template`
+  - Export persona distillation template: `aictl system synthesis-template --type persona`
+  - Export with JSON/YAML metadata: `aictl system synthesis-template --format json --with-schema`
+  - Validate template syntax: `aictl system synthesis-template --validate`
+- **Template Validation**: New `aictl system validate-template` command for validating synthesis templates
+  - Validate custom templates: `aictl system validate-template --template /path/to/template.tmpl`
+  - Validate bundled templates: `aictl system validate-template --type agent`
+  - AST-based validation against DSL schema
+  - Detailed violation reporting with line numbers
+- **Synthesis Testing**: New `aictl system test-synthesis` command for testing agent code generation
+  - Test synthesis from natural language: `aictl system test-synthesis --instructions "Monitor GitHub issues"`
+  - Dry-run mode to preview prompts: `--dry-run`
+  - Automatic temporal intent detection (scheduled vs autonomous)
+  - LLM-powered code generation with validation
+- **Schema Artifacts**: Auto-generated schema artifacts stored in `lib/language_operator/templates/schema/`
+  - `agent_dsl_schema.json` - Complete JSON Schema v7 specification
+  - `agent_dsl_openapi.yaml` - OpenAPI 3.0.3 API documentation
+  - `CHANGELOG.md` - Schema version history
+- **Safe Methods API**: New public methods on `LanguageOperator::Dsl::Schema`
+  - `Schema.safe_agent_methods` - Returns array of safe agent DSL methods
+  - `Schema.safe_tool_methods` - Returns array of safe tool DSL methods
+  - `Schema.safe_helper_methods` - Returns array of safe helper methods
+- Schema version method includes YARD documentation with examples
+- Tests added for schema version access and validation
+- Integration tests for all new CLI commands
+
 ### Changed
 - **GitHub Migration**: Migrated project from self-hosted Forgejo to GitHub
   - Repository now hosted at: https://github.com/language-operator/language-operator-gem

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    language-operator (0.1.30)
+    language-operator (0.1.31)
       k8s-ruby (~> 0.17)
       mcp (~> 0.4)
       opentelemetry-exporter-otlp (~> 0.27)

data/Makefile

@@ -1,4 +1,4 @@
-.PHONY: help build test install console docs clean version-bump lint
+.PHONY: help build test install console docs clean version-bump lint schema
 
 .DEFAULT_GOAL := help
 
@@ -8,7 +8,12 @@ help: ## Show this help message
 	@echo 'Available targets:'
 	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  %-20s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
 
-build: ## Build the gem
+schema: ## Generate schema artifacts (JSON Schema and OpenAPI)
+	@echo "Generating schema artifacts..."
+	@bundle exec rake schema:generate
+	@echo "✅ Schema artifacts generated"
+
+build: schema ## Build the gem
 	@echo "Building language-operator gem..."
 	@gem build language-operator.gemspec
 	@echo "✅ Gem built successfully"

data/Rakefile

@@ -32,3 +32,32 @@ task :console do
   ARGV.clear
   IRB.start
 end
+
+namespace :schema do
+  desc 'Generate schema artifacts (JSON Schema and OpenAPI)'
+  task :generate do
+    require 'json'
+    require 'yaml'
+    require_relative 'lib/language_operator/dsl/schema'
+
+    schema_dir = File.join(__dir__, 'lib', 'language_operator', 'templates', 'schema')
+    FileUtils.mkdir_p(schema_dir)
+
+    # Generate JSON Schema
+    json_schema_path = File.join(schema_dir, 'agent_dsl_schema.json')
+    puts "Generating JSON Schema: #{json_schema_path}"
+    schema = LanguageOperator::Dsl::Schema.to_json_schema
+    File.write(json_schema_path, JSON.pretty_generate(schema))
+    puts "✅ Generated #{json_schema_path}"
+
+    # Generate OpenAPI spec
+    openapi_path = File.join(schema_dir, 'agent_dsl_openapi.yaml')
+    puts "Generating OpenAPI spec: #{openapi_path}"
+    openapi = LanguageOperator::Dsl::Schema.to_openapi
+    File.write(openapi_path, YAML.dump(openapi))
+    puts "✅ Generated #{openapi_path}"
+
+    puts "\nSchema artifacts generated successfully!"
+    puts "Version: #{LanguageOperator::Dsl::Schema.version}"
+  end
+end

data/docs/dsl/SCHEMA_VERSION.md

@@ -0,0 +1,250 @@
+# Schema Versioning Policy
+
+Language Operator DSL Schema uses semantic versioning linked directly to the gem version.
+
+## Version Format
+
+Schema versions follow [Semantic Versioning 2.0.0](https://semver.org/):
+
+```
+MAJOR.MINOR.PATCH
+```
+
+## Accessing Schema Version
+
+### Programmatic Access
+
+```ruby
+require 'language_operator'
+
+# Get schema version
+LanguageOperator::Dsl::Schema.version
+# => "0.1.30"
+
+# Version is also included in JSON Schema output
+schema = LanguageOperator::Dsl::Schema.to_json_schema
+schema[:version]
+# => "0.1.30"
+```
+
+### JSON Schema Output
+
+When generating JSON Schema, the version is automatically included:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/language-operator/language-operator-gem/schema/agent-dsl.json",
+  "title": "Language Operator Agent DSL",
+  "version": "0.1.30",
+  ...
+}
+```
+
+## Version Semantics
+
+The schema version is **identical** to the gem version (`LanguageOperator::VERSION`). Changes to the schema follow these rules:
+
+### MAJOR Version (X.0.0)
+
+Breaking changes that require updates to existing agent definitions:
+
+**Examples:**
+- Removing DSL methods (e.g., removing `schedule` method)
+- Renaming required fields (e.g., `description` → `summary`)
+- Changing parameter types incompatibly (e.g., `mode` from Symbol to String)
+- Removing supported execution modes
+- Changing workflow dependency resolution behavior
+- Altering constraint validation rules in breaking ways
+
+**Migration Required:** Users must update their agent definitions to match new schema.
+
+**Breaking Change Indicators:**
+- Methods removed from `SAFE_AGENT_METHODS`, `SAFE_TOOL_METHODS`, or `SAFE_HELPER_METHODS`
+- Required fields added or changed
+- Enum values removed
+- Pattern validation tightened (existing valid values become invalid)
+
+### MINOR Version (0.X.0)
+
+Backward-compatible additions and enhancements:
+
+**Examples:**
+- Adding new DSL methods (e.g., new output destinations)
+- Adding new optional fields (e.g., new constraint types)
+- Adding new execution modes
+- Expanding enums (e.g., adding authentication types)
+- Adding new workflow features that don't affect existing workflows
+- Relaxing validation patterns (more values become valid)
+- Adding new helper methods
+
+**Migration Required:** None. Existing agent definitions continue to work.
+
+**Addition Indicators:**
+- New methods added to safe method lists
+- New optional properties in schema definitions
+- New enum values
+- New JSON Schema definitions
+- Pattern validation relaxed
+
+### PATCH Version (0.0.X)
+
+Bug fixes and non-breaking improvements:
+
+**Examples:**
+- Fixing validation regex patterns that were too strict
+- Correcting schema descriptions or documentation
+- Fixing default values
+- Improving error messages
+- Performance optimizations in schema generation
+- Documentation improvements
+
+**Migration Required:** None. Fully backward compatible.
+
+**Fix Indicators:**
+- Pattern fixes (making existing valid definitions work correctly)
+- Description clarifications
+- Default value corrections
+- Schema metadata updates
+
+## Schema Evolution Examples
+
+### Example: MAJOR Version Change (Breaking)
+
+**Before (v0.1.x):**
+```ruby
+agent "my-agent" do
+  mode :autonomous  # Symbol
+  schedule "0 12 * * *"
+end
+```
+
+**After (v1.0.0) - Hypothetical Breaking Change:**
+```ruby
+agent "my-agent" do
+  mode "autonomous"  # Now requires String
+  cron_schedule "0 12 * * *"  # Renamed method
+end
+```
+
+**Impact:** Existing agent definitions fail validation. Users must update code.
+
+### Example: MINOR Version Change (Addition)
+
+**Before (v0.1.x):**
+```ruby
+agent "my-agent" do
+  constraints do
+    daily_budget 10.00
+  end
+end
+```
+
+**After (v0.2.0) - New Feature:**
+```ruby
+agent "my-agent" do
+  constraints do
+    daily_budget 10.00
+    monthly_budget 250.00  # NEW: Added in 0.2.0
+  end
+end
+```
+
+**Impact:** None. Old definitions still valid. New feature available optionally.
+
+### Example: PATCH Version Change (Fix)
+
+**Before (v0.1.29):**
+```ruby
+# Bug: timeout pattern too strict, rejects "120s"
+constraints do
+  timeout "2m"  # Works
+  # timeout "120s"  # Would fail validation
+end
+```
+
+**After (v0.1.30) - Bug Fix:**
+```ruby
+# Fixed: timeout pattern now accepts both formats
+constraints do
+  timeout "2m"    # Still works
+  timeout "120s"  # Now works too
+end
+```
+
+**Impact:** None. Existing valid definitions unchanged. Previously invalid definitions may now work.
+
+## Version Compatibility
+
+### Agent Definition Compatibility
+
+Agent definitions are compatible across:
+- ✅ Same MAJOR version (e.g., 0.1.0 agent works with 0.1.30 gem)
+- ✅ MINOR upgrades (e.g., 0.1.x agent works with 0.2.x gem)
+- ❌ MAJOR upgrades (e.g., 0.x.x agent may not work with 1.x.x gem)
+
+### JSON Schema Compatibility
+
+Generated JSON Schemas are versioned. Consumers should:
+
+1. **Check schema version** before validation:
+   ```ruby
+   schema = LanguageOperator::Dsl::Schema.to_json_schema
+   if Gem::Version.new(schema[:version]) >= Gem::Version.new("0.2.0")
+     # Use features from 0.2.0+
+   end
+   ```
+
+2. **Pin gem versions** in production:
+   ```ruby
+   # Gemfile
+   gem 'language-operator', '~> 0.1.0'  # Allow patch updates only
+   ```
+
+## Deprecation Policy
+
+When planning MAJOR version changes:
+
+1. **Deprecation warnings** added in MINOR version before removal
+2. **Migration guides** provided in documentation
+3. **Minimum deprecation period** of one MAJOR version cycle
+
+Example timeline:
+- v0.1.0: Feature X introduced
+- v0.2.0: Feature X deprecated (warnings added, docs updated)
+- v0.3.0: Still supported with warnings
+- v1.0.0: Feature X removed (breaking change)
+
+## Validation and Testing
+
+### Schema Version Testing
+
+The gem includes comprehensive tests ensuring:
+- Schema version matches gem version
+- Version is included in JSON Schema output
+- Safe method lists are validated against ASTValidator constants
+
+See: `spec/language_operator/dsl/schema_spec.rb`
+
+### Breaking Change Detection
+
+When submitting changes:
+
+1. **Check if change is breaking** using checklist above
+2. **Update version accordingly** in `lib/language_operator/version.rb`
+3. **Document in CHANGELOG.md** under appropriate section
+4. **Add migration guide** if MAJOR version bump
+5. **Update this document** if versioning policy changes
+
+## Related Documentation
+
+- [Semantic Versioning Specification](https://semver.org/)
+- [Agent DSL Reference](./agent-reference.md)
+- [Best Practices](./best-practices.md)
+- [CHANGELOG.md](../../CHANGELOG.md)
+
+## Questions?
+
+For questions about schema versioning:
+- Open an issue: https://github.com/language-operator/language-operator-gem/issues
+- Check existing discussions about schema changes

data/docs/dsl/agent-reference.md

@@ -4,6 +4,7 @@ Complete reference guide for the Language Operator agent DSL.
 
 ## Table of Contents
 
+- [Schema Version](#schema-version)
 - [Agent Definition](#agent-definition)
 - [Execution Modes](#execution-modes)
 - [Schedule Configuration](#schedule-configuration)
@@ -14,6 +15,18 @@ Complete reference guide for the Language Operator agent DSL.
 - [Output Configuration](#output-configuration)
 - [Complete Examples](#complete-examples)
 
+## Schema Version
+
+The Language Operator DSL schema is versioned using semantic versioning. The schema version is identical to the gem version.
+
+**Access schema version:**
+
+```ruby
+LanguageOperator::Dsl::Schema.version  # => "0.1.30"
+```
+
+For detailed information about schema versioning policy, version semantics, and compatibility, see [Schema Versioning Policy](./SCHEMA_VERSION.md).
+
 ## Agent Definition
 
 The basic structure of an agent definition:

data/lib/language_operator/agent/safety/safe_executor.rb

@@ -69,6 +69,18 @@ module LanguageOperator
             # Log the call
             @__executor__.log_call(@__context__, method_name, args)
 
+            # Special handling for require - allow only 'language_operator'
+            if %i[require require_relative].include?(method_name)
+              required_gem = args.first.to_s
+              return ::Kernel.require(required_gem) if required_gem == 'language_operator'
+
+              # Allow require 'language_operator'
+
+              ::Kernel.raise ::LanguageOperator::Agent::Safety::SafeExecutor::SecurityError,
+                             "Require '#{required_gem}' is not allowed. Only 'require \"language_operator\"' is permitted."
+
+            end
+
             # Check if method is safe
             unless safe_method?(method_name)
               ::Kernel.raise ::LanguageOperator::Agent::Safety::SafeExecutor::SecurityError,