adamant-tools

Development tools for Adamant component workflows. Three standalone Python scripts that require no Docker or build environment (except adamant_inspect which reads generated files).

Tools

adamant_inspect.py -- Generated API Extractor

Purpose: After redo generates a component, extract a concise summary of the generated API: connectors, methods to override, helpers to call, events, data products, commands, parameters, faults, data dependencies, and tester histories.

When to use: After first successful redo build of a component, before writing the implementation body or test body. Eliminates guessing at generated method names, parameter types, and tester API.

python3 adamant_inspect.py <component_dir>

# Example:
python3 adamant_inspect.py src/components/voltage_monitor

Output sections:

• INIT PARAMETERS -- Init procedure signature
• SET_ID_BASES -- which ID bases the component requires
• RECV CONNECTORS -- abstract procedures to override (handler implementations)
• SEND/GET/REQUEST CONNECTORS -- helper procedures/functions to call
• DROPPED HANDLERS -- abstract null procedures for each send connector
• DATA DEPENDENCY HELPERS -- private Get_* functions for data deps
• DATA DEPENDENCY ABSTRACTS -- Get_Data_Dependency and Invalid_Data_Dependency
• INSTANCE FIELDS -- Self.* record fields (Events, Data_Products, Faults, etc.)
• EVENTS/DATA_PRODUCTS/COMMANDS/FAULTS -- creation function signatures
• PARAMETERS -- table fields and Validate_Parameters signature
• TESTER API -- typed history names, connector histories, override fields

Key value: The #1 cold-start error is guessing at generated API names. This tool provides the exact signatures.

adamant_scaffold.py -- Component Scaffolder

Purpose: Generate all YAML models, implementation stubs (.ads/.adb), and test infrastructure (tests.yaml, env.py) from a spec file.

When to use: Starting a new component. Write a simple YAML spec describing what the component needs, then scaffold generates all files.

python3 adamant_scaffold.py <spec_file.yaml> [output_dir]

# Example:
python3 adamant_scaffold.py watchdog_timer_spec.yaml
# Creates src/components/watchdog_timer/ with all files

Spec file format:

name: watchdog_timer
description: Monitors heartbeats and triggers timeout faults
execution: passive
init:
  - name: Timeout_Ms
    type: Unsigned_32
    description: Timeout period in milliseconds
connectors:
  recv_sync:
    - type: Tick.T
      description: Periodic check
  send:
    - type: Event.T
      description: Event output
    - type: Data_Product.T
      description: Data product output
  get:
    - type: Sys_Time.T
      description: System time
events:
  - name: Heartbeat_Received
    description: Valid heartbeat detected
  - name: Timeout_Triggered
    description: Heartbeat timeout detected
    param_type: Packed_U32.T
data_products:
  - name: Heartbeat_Count
    type: Packed_U32.T
    description: Total heartbeats received
commands:
  - name: Reset
    description: Reset the watchdog timer
faults:
  - name: Heartbeat_Timeout
    description: No heartbeat within timeout period
parameters:
  description: Configurable parameters
  items:
    - name: Timeout_Threshold
      type: Packed_U32.T
      default: "5000"
      description: Timeout in milliseconds
data_dependencies:
  description: External data dependencies
  items:
    - name: System_Health
      type: Packed_Boolean.T
      description: Overall system health status

Generated files:

• <name>.component.yaml -- main component model
• <name>.events.yaml -- event definitions (if events specified)
• <name>.data_products.yaml -- data product definitions (if DPs specified)
• <name>.commands.yaml -- command definitions (if commands specified)
• <name>.parameters.yaml -- parameter definitions (if parameters specified)
• <name>.faults.yaml -- fault definitions (if faults specified)
• <name>.data_dependencies.yaml -- data dependency definitions (if data deps specified)
• component-<name>-implementation.ads -- implementation spec stub
• component-<name>-implementation.adb -- implementation body stub with TODO markers
• test/<name>.tests.yaml -- test configuration
• test/env.py -- test environment

After scaffolding:

1. Review and edit generated files (fill in TODOs)
2. admt build <component_dir>/build/src/component-<name>.ads (generate base class)
3. Run adamant_inspect.py to see the full generated API
4. admt build <component_dir>/test/build/template/ (generate test templates) -- or use admt templates <component_dir> which runs this plus the stub copy
5. cp <component_dir>/test/build/template/*.ads <component_dir>/test/ (skipped when admt templates handles the copy)
6. Write test body, then cd test && admt test

adamant_validate_yaml.py -- YAML Pre-flight Checker

Purpose: Fast structural validation of component YAML files without Docker. Catches the errors that most commonly cause build failures.

When to use: After writing or editing YAML files, before running admt build. Saves a Docker round-trip per error.

python3 adamant_validate_yaml.py <component_dir>

# Example:
python3 adamant_validate_yaml.py src/components/voltage_monitor

What it checks:

• Required fields in component YAML (description, execution, connector types/kinds)
• Framework component name collisions (58 known names)
• Init parameter structure and string defaults
• Feature YAML field names (param_type not type for events, arg_type not type for commands)
• Cross-file consistency (feature YAML exists but matching connector missing)
• File naming conventions (implementation spec/body, test directory structure)
• Test directory rules (env.py content, no .all_path in test dirs)

What it does NOT check:

• Full JSON Schema validation (requires Adamant Python environment)
• Ada compilation correctness
• Connector count or wiring validity

Integration with Skills

These tools complement the existing skills:

• adamant-component-dev: Use adamant_scaffold to create files, adamant_validate_yaml before building
• adamant-testing: Use adamant_inspect after first build to see tester API before writing tests
• adamant-build-system: Tools run outside Docker; admt (and the underlying redo) handle all in-container code generation

Environment Caching

admt owns a cached environment snapshot per registered project (/tmp/admt/<project>/env_snapshot.sh + exec.sh) and restores it in milliseconds on every call. The legacy adamant_env.sh wrapper still provides its own /tmp/.<project>_env_snapshot as a fallback.

# Run any in-container command through admt (snapshot-cached):
admt env exec "python3 /tmp/adamant_validate_yaml.py src/components/foo"

# Force snapshot regeneration after container recreation:
admt env refresh

Sub-agent workflow pattern:

# Step 1: Copy tools into container (once per container start)
docker cp adamant-tools/*.py <project>_container:/tmp/

# Step 2: Validate YAML (uses pykwalify if SCHEMAPATH set)
admt env exec "python3 /tmp/adamant_validate_yaml.py $COMP_DIR"

# Step 3: Build component
admt build $COMP_DIR/build/src/component-$NAME.ads

# Step 4: Inspect generated API
admt env exec "python3 /tmp/adamant_inspect.py $COMP_DIR"

# Step 5: Build and test
admt test $COMP_DIR/test

Fallback form (when admt is not applicable):

bash <project_dir>/docker/adamant_env.sh exec "python3 /tmp/adamant_validate_yaml.py src/components/foo"

pykwalify Schema Validation

Inside Docker (with source activate), the validator automatically uses Adamant's real pykwalify schemas from $SCHEMAPATH. This catches all YAML structural errors authoritatively -- no heuristic guessing.

Outside Docker, the validator falls back to heuristic checks (field names, connector consistency, naming conventions). These catch the most common errors but are not exhaustive.

Location

Tools are in the adamant-tools/ directory of the skills repository. Copy into Docker containers or run from the host against mounted volumes.