rosett-ai 1.3.3

data/QUICKSTART.md

@@ -0,0 +1,73 @@
+# Quick Start
+
+Get from zero to your first compiled rules in 5 minutes.
+
+## 1. Install
+
+```bash
+sudo dpkg -i nncc_1.0.0-1_amd64.deb
+sudo apt-get install -f   # resolve dependencies
+```
+
+## 2. Initialize
+
+```bash
+# Set up global ~/.claude/ structure
+rai init --global
+
+# (Optional) Set up project-local structure
+rai init --local
+```
+
+## 3. Create a behaviour rule
+
+```bash
+rai behaviour manage add my_first_rule
+```
+
+Edit the created file at `conf/behaviour/my_first_rule.yml`:
+
+```yaml
+name: my_first_rule
+description: My first rai behaviour rule
+version: 1.0.0
+author: your_name
+created_at: "2026-01-01"
+modified_at: "2026-01-01"
+modified_by: your_name
+sensitive: false
+used_in: []
+rules:
+  - id: rule_001
+    description: Always explain your reasoning before making changes
+    priority: 50
+    enabled: true
+```
+
+## 4. Compile
+
+```bash
+# Preview what would change
+rai compile --simulate --verbose
+
+# Compile rules to ~/.claude/rules/
+rai compile --verbose
+```
+
+## 5. Verify
+
+```bash
+# Check the generated files
+ls ~/.claude/rules/
+
+# Validate everything is consistent
+rai validate
+```
+
+## Next Steps
+
+- `rai compile --engine generic` to compile for non-Claude tools
+- `rai design list` to explore design documents
+- `rai adopt --verbose` to analyze your existing rules
+- `man raictl` for the full manual
+- See [INSTALL.md](INSTALL.md) for detailed installation options

data/README.md

@@ -0,0 +1,366 @@
+# Rosett-AI
+
+**Author rules once, compile to Claude Code, AGENTS.md, and more engines coming soon.**
+
+raictl is an engine-agnostic configuration management tool for AI-assisted development workflows.
+Define operational rules in generic YAML, then compile them to any supported AI tool's native format.
+v1.2.0 ships with Claude Code and AGENTS.md engines.
+Additional engines (Cursor, Copilot, Windsurf, Goose, Aider, Ollama, GPT-NeoX, Generic) are in development.
+
+```mermaid
+graph LR
+    subgraph Input["Human Intent (YAML)"]
+        B[conf/behaviour/*.yml]
+        D[conf/design/*.yml]
+    end
+
+    subgraph rosett-ai["Rosett-AI Compiler"]
+        P[Compilation Pipeline]
+    end
+
+    subgraph Engines["Engine Backends"]
+        C[Claude Code]:::available
+        A[AGENTS.md]:::available
+        CU[Cursor]:::planned
+        CP[Copilot]:::planned
+        WS[Windsurf]:::planned
+        GO[Goose]:::planned
+        AI[Aider]:::planned
+        O[Ollama]:::planned
+        G[GPT-NeoX]:::planned
+        X[Generic]:::planned
+    end
+
+    B --> P
+    D --> P
+    P --> C
+    P --> A
+    P --> CU
+    P --> CP
+    P --> WS
+    P --> GO
+    P --> AI
+    P --> O
+    P --> G
+    P --> X
+
+    classDef available stroke:#22c55e,stroke-width:2px
+    classDef planned stroke:#94a3b8,stroke-width:1px,stroke-dasharray:5 5,fill:#f8fafc,color:#64748b
+```
+
+| Field | Value |
+|-------|-------|
+| Version | <!-- rai:version -->1.2.0<!-- /rai:version --> |
+| License | GPL-3.0-only |
+| Ruby | 3.3.10 (rbenv) |
+| Tests | <!-- rai:tests -->4672 RSpec specs<!-- /rai:tests --> |
+| Author | Hugo Antonio Sepulveda Manriquez |
+
+## Quick Start
+
+### Install from RubyGems
+
+```bash
+gem install rosett-ai
+```
+
+### Or install from .deb (Debian/Ubuntu)
+
+```bash
+sudo dpkg -i rosett-ai_1.2.0-1_amd64.deb
+```
+
+### Initialize
+
+```bash
+raictl init --global
+```
+
+### Write your first behaviour rule
+
+```bash
+raictl behaviour manage add my_rules
+```
+
+### Compile to Claude Code
+
+```bash
+raictl compile --verbose
+```
+
+### Verify
+
+```bash
+ls ~/.claude/rules/
+```
+
+## Features
+
+```mermaid
+mindmap
+  root((raictl))
+    Engine Backends
+      Claude Code ✓
+      AGENTS.md ✓
+      Cursor ○
+      Copilot ○
+      Windsurf ○
+      Goose ○
+      Aider ○
+      Ollama ○
+      GPT-NeoX ○
+      Generic ○
+    Desktop Integration
+      D-Bus IPC Service
+      GTK4/Adwaita App
+      Focus Monitoring
+      5 Compositor Adapters
+    Configuration
+      Behaviour Rules
+      Design Documents
+      JSON Schema Validation
+      Configuration Hierarchy
+    Security
+      Ed25519 JWT Licensing
+      YAML DoS Prevention
+      Path Whitelisting
+      Custom RuboCop Cops
+    CLI
+      Compile / Validate / Adopt
+      Backup / Migrate / Doctor
+      Engine Detection
+    Accessibility
+      EN 301 549 Compliance
+      Accessible TUI
+      i18n (en, fr, ar)
+```
+
+### Core Capabilities
+
+- **Engine-Agnostic Compilation** -- Write rules in generic YAML, compile to any AI tool
+- **<!-- rai:engines -->2<!-- /rai:engines --> Available Engine Backends** -- Claude Code, AGENTS.md (8 more planned: Cursor, Copilot, Windsurf, Goose, Aider, Ollama, GPT-NeoX, Generic)
+- **D-Bus Desktop Service** -- `be.neatnerds.rosettai` session bus with Manager and FocusMonitor interfaces
+- **GTK4/Adwaita Application** -- Crash-proof GUI with `safe_action()` wrapper pattern
+- **Behaviour Management** -- Priority-sorted rules (1-100 scale) with sensitivity filtering
+- **Adopt Analysis** -- Local structural checks with optional API-powered analysis
+- **Content Packs** -- Premium content delivery via Ed25519-signed JWT licensing
+- **Debian Packaging** -- `.deb` packages via fpm for core, gtk4, and qt6 variants
+- **i18n** -- Internationalisation with gettext/Qt locale compilation
+
+## Architecture Overview
+
+```mermaid
+graph TB
+    subgraph CLI["CLI Layer (Thor)"]
+        BIN[bin/raictl]
+        THOR[RosettAi::Thor::CLI]
+    end
+
+    subgraph LIB["Library Layer"]
+        COMP[Compiler::Pipeline]
+        VALID[Validators]
+        CONFIG[Configuration]
+        PATH[PathResolver]
+        ADOPT[Adopter]
+        YAML[YamlLoader]
+    end
+
+    subgraph ENGINES["Engine Layer"]
+        CLAUDE[engines/claude/]:::available
+        AGENTS[engines/agents_md/]:::available
+        CURSOR[engines/cursor/]:::planned
+        COPILOT[engines/copilot/]:::planned
+        WINDSURF[engines/windsurf/]:::planned
+        GOOSE[engines/goose/]:::planned
+        AIDER[engines/aider/]:::planned
+        OLLAMA[engines/ollama/]:::planned
+        NEOX[engines/gpt_neox/]:::planned
+        GENERIC[engines/generic/]:::planned
+    end
+
+    subgraph DESKTOP["Desktop Layer"]
+        DBUS_SVC[D-Bus Service]
+        GTK4[GTK4 App]
+        FOCUS[Focus Monitor]
+    end
+
+    BIN --> THOR
+    THOR --> COMP
+    THOR --> VALID
+    THOR --> CONFIG
+    THOR --> ADOPT
+    COMP --> ENGINES
+    COMP --> YAML
+    VALID --> YAML
+    CONFIG --> PATH
+    DBUS_SVC --> COMP
+    GTK4 -->|D-Bus IPC| DBUS_SVC
+    FOCUS --> DBUS_SVC
+
+    classDef available stroke:#22c55e,stroke-width:2px
+    classDef planned stroke:#94a3b8,stroke-width:1px,stroke-dasharray:5 5,fill:#f8fafc,color:#64748b
+```
+
+> **Legend:** Solid border = Available | Dashed border = Planned
+
+## CLI Commands
+
+```bash
+# Compilation
+raictl compile                        # Compile rules (default engine)
+raictl compile --engine agents_md     # Compile to AGENTS.md format
+raictl compile --engine ollama        # Compile for Ollama
+raictl compile --strict               # Treat warnings as errors
+raictl compile --simulate --verbose   # Dry run with diffs
+
+# Engine management
+raictl engines list                   # List all known engines
+raictl engines detect                 # Detect installed engines
+raictl engines status                 # Show default engine + detection
+
+# Validation & analysis
+raictl validate                       # Validate all config files
+raictl adopt                          # Local-only structural checks
+raictl adopt --api --verbose          # Remote API analysis
+
+# Configuration
+raictl behaviour display              # Show behaviour configuration
+raictl config compile                 # Compile YAML scopes to JSON
+raictl design list                    # List design documents
+
+# Desktop
+raictl dbus start                     # Start D-Bus service
+raictl desktop gtk4                   # Launch GTK4 application
+
+# Backup
+raictl backup --global --local        # Back up all configurations
+```
+
+See [USAGE.md](doc/USAGE.md) for the full command reference.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [ARCHITECTURE.md](doc/ARCHITECTURE.md) | System architecture with Mermaid diagrams |
+| [ENGINES.md](doc/ENGINES.md) | Engine backends and compilation targets |
+| [DESKTOP.md](doc/DESKTOP.md) | D-Bus service and GTK4 desktop app |
+| [SETUP.md](doc/SETUP.md) | Installation and setup guide |
+| [USAGE.md](doc/USAGE.md) | CLI usage and examples |
+| [CONFIGURATION.md](doc/CONFIGURATION.md) | Configuration reference |
+| [BEHAVIOUR.md](doc/BEHAVIOUR.md) | Behaviour system documentation |
+| [ADOPT.md](doc/ADOPT.md) | Adopt analysis documentation |
+| [PACKAGING.md](doc/PACKAGING.md) | Debian packaging |
+| [REFERENCES.md](doc/REFERENCES.md) | External references and bibliography |
+| [IMPLEMENTATION_PLAN.md](doc/IMPLEMENTATION_PLAN.md) | Phased roadmap |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Developer guide |
+
+### Architecture Decision Records
+
+| ADR | Status | Decision |
+|-----|--------|----------|
+| [001](doc/decisions/001-flog-deferred.md) | Accepted | Defer Flog (covered by RuboCop) |
+| [002](doc/decisions/002-path-resolution-strategy.md) | Accepted | Centralised PathResolver |
+| [003](doc/decisions/003-ui-adapter-selection.md) | Accepted | 5-level UI cascade |
+| [004](doc/decisions/004-design-document-validation.md) | Accepted | Generic SchemaValidator |
+| [005](doc/decisions/005-package-splitting-strategy.md) | Accepted | Plugin gems in mono-repo |
+| [006](doc/decisions/006-multi-engine-architecture.md) | Superseded | Multi-engine (see ADR-007) |
+| [007](doc/decisions/007-engine-agnostic-pivot.md) | Accepted | Engine-agnostic pivot |
+
+## Project Structure
+
+```text
+rosett-ai/
+├── bin/raictl                        # CLI executable
+├── lib/rosett_ai/                       # Ruby library (4800+ LOC)
+│   ├── engines/                    # Engine backends
+│   │   ├── claude/                 # Claude Code engine (7 components)
+│   │   ├── cursor/                # Cursor (Anysphere) engine
+│   │   ├── copilot/               # GitHub Copilot engine
+│   │   ├── windsurf/              # Windsurf (Codeium) engine
+│   │   ├── agents_md/             # AGENTS.md engine
+│   │   ├── goose/                 # Goose (Block) engine
+│   │   ├── aider/                 # Aider engine
+│   │   ├── generic/               # Generic markdown engine
+│   │   ├── ollama/                # Ollama engine
+│   │   └── gpt_neox/             # GPT-NeoX engine
+│   ├── compiler/                   # Compilation pipeline
+│   ├── desktop/                    # GTK4 app + GUI logger
+│   ├── dbus/                       # D-Bus service + focus adapters
+│   ├── validators/                 # Schema-based validators
+│   ├── licensing/                  # Ed25519 JWT license keys
+│   ├── content/                    # Content pack system
+│   ├── backup/                     # Backup with compression
+│   ├── thor/tasks/                 # 16 CLI subcommands
+│   └── ui/                         # UI adapter registry
+├── conf/                           # Configuration
+│   ├── behaviour/                  # Behaviour YAML files
+│   ├── design/                     # Design documents (21 files)
+│   ├── schemas/                    # JSON Schemas (10 files)
+│   ├── engines/                    # Per-engine config
+│   └── packaging/                  # Package variant configs
+├── spec/                           # RSpec tests (119 files)
+├── doc/                            # Documentation
+│   ├── decisions/                  # ADRs (001-007)
+│   └── changes/                    # Implementation notes
+├── locales/                        # i18n (en, fr, ar)
+├── packaging/                      # Debian scripts
+└── CLAUDE.md                       # Project instructions
+```
+
+## Development
+
+### Building from source
+
+```bash
+git clone https://gitlab.com/neatnerds/foss/rosett-ai.git
+cd rosett-ai
+rbenv install 3.3.10
+bundle install
+overcommit --install
+bin/raictl version
+```
+
+### Quality checks
+
+```bash
+bundle exec rspec                   # Run tests
+bundle exec rubocop                 # Lint
+bundle exec reek                    # Code smell detection
+bundle exec bundler-audit check     # Security audit
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full developer guide.
+
+## Roadmap
+
+```mermaid
+gantt
+    title Rosett-AI Development Roadmap
+    dateFormat YYYY-MM-DD
+    axisFormat %b %d
+
+    section Engine Phases
+    Phase 0a - Rename                :done, e0a, 2026-02-26, 1d
+    Phase 0b - Engine dirs           :done, e0b, after e0a, 1d
+    Phase 0c - XDG + detection       :done, e0c, after e0b, 1d
+    Engine 1 - AGENTS.md             :done, e1, after e0c, 1d
+    Engine 2 - Ollama + GPT-NeoX     :done, e2, after e1, 1d
+    Engine 3 - Goose + Aider         :done, e3, after e2, 1d
+    Engine 4 - Cursor + Copilot      :done, e4, after e3, 1d
+
+    section Desktop Phases
+    Desktop 1 - D-Bus service        :done, d1, after e0c, 1d
+    Desktop 2 - GTK4 app             :done, d2, after d1, 1d
+    GTK4 hardening                   :done, d2h, after d2, 1d
+    Desktop 3 - KDE KCM              :d3, after d2h, 5d
+```
+
+## License
+
+GPL-3.0-only
+
+## Contact
+
+- Author: hugo@neatnerds.be
+- Support: query@neatnerds.be

data/Rakefile

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+desc 'Run reek smell detector'
+task :reek do
+  sh 'bundle', 'exec', 'reek', 'lib/rosett_ai.rb', 'lib/rosett_ai/'
+end
+
+desc 'Check dependency licenses for GPL-3.0 compatibility'
+task :licenses do
+  sh 'bundle', 'exec', 'license_finder'
+end
+
+desc 'Detect potentially uncalled methods'
+task :debride do
+  sh 'bundle', 'exec', 'debride', '-w', '.debride_whitelist', 'lib/'
+end
+
+desc 'Audit dependencies for known vulnerabilities'
+task :bundler_audit do
+  sh 'bundle', 'exec', 'bundler-audit', 'check', '--update'
+end
+
+desc 'Detect structural code duplication'
+task :flay do
+  sh 'bundle', 'exec', 'flay', '--mass', '16', 'lib/'
+end
+
+desc 'Run all quality gates'
+task quality: [:spec, :rubocop, :reek, :licenses, :debride, :bundler_audit, :fasterer, :flay]
+
+task default: :quality
+
+namespace :docs do
+  desc 'Update all documentation'
+  task :update do
+    require_relative 'lib/rosett_ai'
+    RosettAi::Thor::Tasks::Documentation.new.update
+  end
+
+  desc 'Check documentation status'
+  task :status do
+    require_relative 'lib/rosett_ai'
+    RosettAi::Thor::Tasks::Documentation.new.status
+  end
+end
+
+namespace :man do
+  desc 'Build man pages from ronn source'
+  task :build do
+    require 'ronn'
+    source = File.expand_path('doc/man/rai.1.ronn', __dir__)
+    output_dir = File.expand_path('man/man1', __dir__)
+    FileUtils.mkdir_p(output_dir)
+
+    doc = Ronn::Document.new(source)
+    File.write(File.join(output_dir, 'rai.1'), doc.to_roff)
+    puts 'Generated man/man1/rai.1'
+  end
+end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new(:yard) do |t|
+    t.files = ['lib/**/*.rb']
+    t.options = ['--output-dir', 'doc/api', '--markup', 'markdown', '--no-private']
+  end
+rescue LoadError
+  desc 'Generate YARD documentation (yard gem not installed)'
+  task(:yard) { warn 'yard gem is not installed. Run: gem install yard' }
+end
+
+desc 'Generate CHANGELOG.md from conventional commits (requires git-cliff)'
+task :changelog do
+  unless system('which git-cliff > /dev/null 2>&1')
+    warn 'git-cliff is not installed. See: https://git-cliff.org/docs/installation'
+    exit 1
+  end
+  system('git-cliff', '--config', 'cliff.toml', '--output', 'CHANGELOG.md') || exit(1)
+  puts 'Generated CHANGELOG.md'
+end
+
+desc 'Run fasterer performance suggestions'
+task :fasterer do
+  require 'fasterer/cli'
+  Fasterer::CLI.execute
+rescue LoadError
+  warn 'fasterer gem is not installed. Run: gem install fasterer'
+end
+
+namespace :behaviour do
+  desc 'Validate all behaviour files'
+  task :validate do
+    require_relative 'lib/rosett_ai'
+    RosettAi::Thor::Tasks::Behaviour.new.validate
+  end
+
+  desc 'List all behaviour files'
+  task :list do
+    require_relative 'lib/rosett_ai'
+    RosettAi::Thor::Tasks::Behaviour.new.list
+  end
+end
+
+namespace :build do
+  desc 'Build core .deb package (variant: core, gtk4, qt6)'
+  task :package, [:variant] do |_t, args|
+    require_relative 'lib/rosett_ai'
+    # Trigger Zeitwerk autoload of Build (which defines BuildPackage)
+    RosettAi::Thor::Tasks::Build # rubocop:disable Lint/Void
+    opts = build_package_opts(args)
+    RosettAi::Thor::Tasks::BuildPackage.new([], opts).invoke(:create)
+  end
+
+  desc 'Build engine plugin .deb package'
+  task :engine do
+    require_relative 'lib/rosett_ai'
+    RosettAi::Thor::Tasks::Build # rubocop:disable Lint/Void
+    RosettAi::Thor::Tasks::BuildEngine.new.invoke(:create)
+  end
+end
+
+# Build option flags from Rake args and environment variables.
+# Usage:
+#   rake build:package                          # defaults
+#   rake build:package[gtk4]                    # variant only
+#   rake build:package VERBOSE=1 CLEAN=1        # flags via env
+#   rake build:package[gtk4] VERBOSE=1 CLEAN=1  # both
+def build_package_opts(args)
+  opts = {}
+  opts[:variant] = args[:variant] if args[:variant]
+  opts[:verbose] = true if ENV['VERBOSE']
+  opts[:clean] = true if ENV['CLEAN']
+  opts[:ruby_version] = ENV['RUBY_VERSION'] if ENV['RUBY_VERSION']
+  opts[:architecture] = ENV['ARCHITECTURE'] if ENV['ARCHITECTURE']
+  opts[:output_dir] = ENV['OUTPUT_DIR'] if ENV['OUTPUT_DIR']
+  opts[:build_iteration] = ENV['BUILD_ITERATION'].to_i if ENV['BUILD_ITERATION']
+  opts
+end
+
+namespace :release do
+  desc 'Prepare release (level: major, minor, patch)'
+  task :prepare, [:level] do |_t, args|
+    require_relative 'lib/rosett_ai'
+    RosettAi::Thor::Tasks::Release.new.invoke(:prepare, [args[:level] || 'patch'])
+  end
+
+  desc 'Create annotated git tag from current VERSION'
+  task :tag do
+    require_relative 'lib/rosett_ai'
+    RosettAi::Thor::Tasks::Release.new.invoke(:tag)
+  end
+
+  desc 'Show release status (version, last tag, unreleased commits)'
+  task :status do
+    require_relative 'lib/rosett_ai'
+    RosettAi::Thor::Tasks::Release.new.invoke(:status)
+  end
+end
+
+namespace :readme do
+  desc 'Update README version, test count, and engine count from live sources'
+  task :update do
+    require_relative 'lib/rosett_ai/version'
+    require 'json'
+
+    readme_path = File.expand_path('README.md', __dir__)
+    content = File.read(readme_path)
+
+    # Version from constant
+    version = RosettAi::VERSION
+    content.gsub!(%r{<!-- rai:version -->.*?<!-- /rai:version -->},
+                  "<!-- rai:version -->#{version}<!-- /rai:version -->")
+
+    # Test count via rspec --dry-run (COVERAGE=false suppresses SimpleCov noise in stdout)
+    env = { 'COVERAGE' => 'false' }
+    json_output = IO.popen(env, ['bundle', 'exec', 'rspec', '--dry-run', '--format', 'json'],
+                           err: File::NULL, &:read)
+    test_count = JSON.parse(json_output).dig('summary', 'example_count')
+    content.gsub!(%r{<!-- rai:tests -->.*?<!-- /rai:tests -->},
+                  "<!-- rai:tests -->#{test_count} RSpec specs<!-- /rai:tests -->")
+
+    # Engine count from target profiles
+    engine_count = Dir[File.expand_path('conf/targets/*.yml', __dir__)].size
+    content.gsub!(%r{<!-- rai:engines -->\d+<!-- /rai:engines -->},
+                  "<!-- rai:engines -->#{engine_count}<!-- /rai:engines -->")
+
+    File.write(readme_path, content)
+    puts "README.md updated: v#{version}, #{test_count} specs, #{engine_count} engines"
+  end
+end