# Developer Tools Architecture

> Standalone CLI utilities for development, testing, and CI support workflows.

## Overview

The Tools directory contains a set of independent CLI applications, each with its own `Program.cs` entry point. These tools are not deployed as services -- they are invoked locally by developers or executed in CI pipelines. Each tool is narrowly scoped to a single responsibility, from fixture management to workflow generation.

## Components

```
src/Tools/
  FixtureUpdater/           # Golden fixture refresh from live APIs
    Program.cs
  GoldenPairs/              # SBOM/advisory corpus management
    Program.cs
  PolicyDslValidator/       # Policy DSL file validation
    Program.cs
  PolicySchemaExporter/     # JSON schema export for IDE support
    Program.cs
  PolicySimulationSmoke/    # Policy simulation smoke tests
    Program.cs
  LanguageAnalyzerSmoke/    # Language detection accuracy tests
    Program.cs
  RustFsMigrator/           # RustFS data migration between schema versions
    Program.cs
  WorkflowGenerator/        # CI workflow generation (F# DSL)
    Program.fs
```

## Tool Descriptions

### FixtureUpdater

Pulls latest test data from running Stella Ops services and updates frozen golden fixtures deterministically. Ensures test suites use realistic, version-controlled data without manual fixture authoring.

### GoldenPairs

Manages SBOM/advisory pairs used for testing. Provides version tracking and diff tools for the test corpus, ensuring changes to upstream advisory formats are detected and accommodated.

### PolicyDslValidator

Validates policy DSL files against the current schema. Used in CI gates to catch policy syntax errors before merge.

### PolicySchemaExporter

Exports the Policy DSL schema to JSON format for documentation and IDE autocomplete support. Enables policy authors to get inline validation and completion in their editors.

### PolicySimulationSmoke

Runs end-to-end policy simulation smoke tests against a configured Policy Engine instance. Validates that policy evaluation produces expected verdicts for a known set of inputs.

### LanguageAnalyzerSmoke

Tests the language analyzer's detection accuracy against a curated set of source files. Reports precision and recall metrics for supported languages.

### RustFsMigrator

Migrates data stored in RustFS (S3-compatible object storage) between schema versions. Handles object key transformations and metadata updates required during platform upgrades.

### WorkflowGenerator

Generates GitHub Actions and .NET test workflow definitions from an F# DSL. Ensures CI workflow files are consistent, auditable, and derived from a single source of truth rather than hand-edited YAML.

## Data Flow

Tools are consumers and producers of artifacts:

1. **FixtureUpdater** and **GoldenPairs** pull data from live services or local corpora and write deterministic fixture files to the repository.
2. **PolicyDslValidator** and **PolicySchemaExporter** read policy definitions and produce validation results or schema files.
3. **PolicySimulationSmoke** and **LanguageAnalyzerSmoke** execute tests against upstream services/libraries and produce pass/fail reports.
4. **RustFsMigrator** reads from and writes to S3-compatible storage.
5. **WorkflowGenerator** reads F# DSL definitions and writes CI workflow YAML files.

## Database Schema

Not applicable. Tools are CLI utilities with no persistent database.

## Endpoints

Not applicable. Tools are client-side CLI applications with no HTTP endpoints.

## Dependencies

| Library/Tool         | Purpose                                        |
|---------------------|------------------------------------------------|
| Policy Engine libs   | Policy DSL parsing, schema definitions         |
| Scanner libs         | Language analyzer, SBOM processing             |
| F# compiler          | WorkflowGenerator DSL compilation              |
| DotNet.Glob          | File pattern matching in fixture tools         |
| AWS SDK (S3)         | RustFsMigrator object storage access           |

## Security Considerations

- **No network listeners**: Tools do not expose HTTP endpoints or accept inbound connections.
- **Credential handling**: Tools that connect to live services (FixtureUpdater, PolicySimulationSmoke) use the same Authority-issued tokens as other Stella Ops services. Credentials are never embedded in tool binaries or fixture files.
- **Deterministic output**: FixtureUpdater and GoldenPairs produce deterministic output to ensure reproducible test runs and prevent fixture drift.
- **CI isolation**: Tools run in isolated CI containers with scoped permissions; they do not have access to production secrets.