3

api-definitions-default-index

Jonathan Miller edited this page 2026-05-20 01:26:17 +00:00

Table of Contents

• Default Repository Definitions
• Overview
• Definition Files
• File Format
• Usage
• Platform Detection
• Manual Selection
• During Bulk Sync
• Platform Mapping
• Creating New Definitions
• Validation Levels
• Maintenance
• Updating Definitions
• Version Control
• Related Documentation

← Home

Default Repository Definitions

Overview

This directory contains base platform-specific definition files that serve as templates for repository validation and structure. These definitions are used as the foundation for generating repository-specific definitions during bulk sync operations.

Definition Files

File	Platform	Description
crm-module.tf	Dolibarr	Structure for Dolibarr/CRM modules with core/modules structure, language files, SQL tables
default-repository.json	Generic	JSON format of default repository structure (legacy format)
default-repository.tf	Generic	Standard structure for generic repositories, libraries, and multi-language projects
generic-repository.tf	Generic	Alternative generic repository structure with minimal requirements
standards-repository.tf	Standards	Structure for moko-platform organizational repository with api/, templates/, docs/, logs/
waas-component.tf	Joomla	Structure for Joomla/WaaS components, modules, plugins with manifest validation
mcp-server.tf	MCP Server	Structure for MCP (Model Context Protocol) server projects — TypeScript/Node.js servers exposing REST APIs as AI tools

File Format

All definition files use Terraform HCL (HashiCorp Configuration Language) format with .tf extension:

locals {
  repository_structure = {
    metadata = {
      name             = "Repository Type Name"
      description      = "Detailed description"
      repository_type  = "type-identifier"
      platform         = "platform-name"
      last_updated     = "ISO8601-timestamp"
      maintainer       = "Maintainer Name"
      version          = "1.0"
      schema_version   = "1.0"
    }
    
    root_files = [
      {
        name              = "filename.ext"
        extension         = "ext"
        description       = "File description"
        required          = true
        audience          = "general"
      }
    ]
    
    directories = [
      {
        name        = "dirname"
        path        = "path/to/dir"
        description = "Directory description"
        required    = true
        purpose     = "Purpose description"
        
        files = [ /* nested files */ ]
        subdirectories = [ /* nested directories */ ]
      }
    ]
    
    repository_requirements = {
      secrets = [ /* required secrets */ ]
      variables = [ /* required variables */ ]
      branch_protections = { /* protection rules */ }
      repository_settings = { /* settings */ }
    }
  }
}

Usage

Platform Detection

These definitions are automatically selected during platform detection:

# Auto-detect platform and load appropriate definition
php api/validate/auto_detect_platform.php \
  --repo-path /path/to/repository \
  --schema-dir api/definitions/default

The detection script will:

1. Analyze repository structure and content
2. Score each platform based on indicators
3. Select the best-matching definition
4. Validate repository against the definition

Manual Selection

You can manually specify which definition to use:

# Use specific definition
php api/validate/auto_detect_platform.php \
  --repo-path /path/to/repository \
  --platform dolibarr

This will load api/definitions/default/crm-module.tf.

During Bulk Sync

When bulk sync runs, it:

1. Detects the repository platform
2. Loads the corresponding base definition from this directory
3. Customizes it with repository-specific metadata
4. Saves to api/definitions/sync/{repo}.def.tf

Platform Mapping

The auto-detection script maps platforms to definition files:

Platform	Definition File
joomla	waas-component.tf
dolibarr	crm-module.tf
nodejs	nodejs-repository.tf (future)
python	python-repository.tf (future)
terraform	terraform-repository.tf (future)
mcp-server	mcp-server.tf
standards	standards-repository.tf
generic	default-repository.tf

Creating New Definitions

To create a new platform definition:

1. Copy an existing definition as template:

   cp api/definitions/default/default-repository.tf \
      api/definitions/default/myplatform-repository.tf
   

2. Update metadata:

   • Change name, description, repository_type, platform
   • Update last_updated timestamp
   • Set appropriate version and schema_version

3. Define structure:

   • Update root_files array with platform-specific files
   • Define directories with nested structure
   • Add platform-specific validation rules
   • Specify repository requirements (secrets, variables, etc.)

4. Update platform detection: Add mapping in api/validate/auto_detect_platform.php:

   'myplatform' => 'myplatform-repository.tf',
   

5. Add detection logic: Update detection scoring to recognize your platform based on:

   • File patterns (e.g., composer.json, package.json)
   • Directory structure
   • Repository topics
   • Naming conventions

6. Validate syntax:

   # Using Terraform (if installed)
   terraform fmt -check api/definitions/default/myplatform-repository.tf
   

7. Test definition:

   php api/validate/auto_detect_platform.php \
     --repo-path /test/repository \
     --platform myplatform
   

Validation Levels

Definitions support multiple requirement levels:

Level	Meaning	Impact
required	MUST be present	Blocks deployment if missing
suggested	SHOULD be present	Warning if missing, reduces health score
optional	MAY be present	No validation, informational only
not-allowed	MUST NOT be present	Error if present (e.g., node_modules)

Maintenance

Updating Definitions

1. Edit the definition file
2. Update last_updated timestamp
3. Increment version if breaking changes
4. Test with validation script
5. Update CHANGELOG.md
6. Commit changes

Version Control

• Definition files are versioned through git
• Breaking changes require major version bump
• Schema version tracked in definition metadata
• Maintain backward compatibility when possible

Related Documentation

• Synced Definitions - Auto-generated repository definitions
• Schema Guide - Complete schema specification
• Validation Guide - Platform detection and validation
• Main Definitions README - Overview of definitions structure

---

Repo: moko-platform · moko-platform wiki

Field	Value
Minimum Version	04.07.00
Platform	all
Applies To	moko-platform

Revision	Date	Author	Description
1.0	2026-05-08	Moko Consulting	Initial version