3

standards-mokostandards-file-spec

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

Table of Contents

• .mokostandards File Specification
• Overview
• Location
• Format
• Sections
• <identity> — Required
• <governance> — Required
• <build> — Optional
• <deploy> — Optional
• <scripts> — Optional
• <overrides> — Optional
• Minimal Example
• Full Example (WaaS Component)
• Migration from Legacy Format
• Validation
• Tooling Integration

← Home

.mokostandards File Specification

Version: 1.0 Status: Active Schema: mokostandards-schema.xsd Last Updated: 2026-05-02

Overview

The .mokostandards file is the repository manifest for every repo governed by moko-platform. It lives at .gitea/.mokostandards (no file extension) and uses XML format internally.

The file serves three purposes:

1. Identity — declares the repo's name, organization, description, license, and topics.
2. Governance binding — ties the repo to a specific moko-platform platform definition, enabling the bulk sync to know which files, workflows, and templates to enforce.
3. Repo-specific configuration — captures build/deploy targets, automation scripts, and per-repo sync overrides so that tooling (CI, make, composer run) can operate without guessing.

Location

.gitea/.mokostandards          ← primary (Gitea-hosted repos)

Legacy locations (.mokostandards at repo root, .github/.mokostandards) are auto-migrated by the bulk sync into .gitea/.mokostandards.

Format

The file is well-formed XML with no .xml extension. It uses the namespace https://git.mokoconsulting.tech/MokoConsulting/moko-platform and is validated against mokostandards-schema.xsd.

Sections

<identity> — Required

Element	Required	Description
<name>	yes	Repository name (e.g. MokoCRM)
<org>	yes	Organization slug (e.g. MokoConsulting)
<description>	no	Human-readable project description
<license>	no	License name; optional spdx attribute for the SPDX identifier
<topics>	no	Container for <topic> elements — Gitea/GitHub topics

<governance> — Required

Element	Required	Description
<platform>	yes	Platform slug — must match a definitions/default/*.tf file. One of: default-repository, crm-module, crm-platform, generic-repository, github-private-repository, joomla-template, standards-repository, waas-component
<standards-version>	yes	moko-platform version that last synced this repo (e.g. 04.07.00)
<standards-source>	yes	URL to the moko-platform repo
<last-synced>	no	ISO 8601 timestamp of last bulk sync

<build> — Optional

Element	Required	Description
<language>	no	Primary language (PHP, JavaScript, CSS, etc.)
<runtime>	no	Runtime version requirement (e.g. php:>=8.1)
<package-type>	no	Package format (composer, npm, joomla-extension, dolibarr-module)
<entry-point>	no	Main entry file relative to repo root
<artifact>	no	Build output: <format>, <path>, <filename>
<dependencies>	no	Container for <requires name="" version="" type=""> elements

<deploy> — Optional

Contains one or more <target> elements:

Attribute/Element	Required	Description
@name	yes	Target name (dev, demo, staging, production)
@enabled	no	Boolean, default true
<host>	yes	Hostname or secret reference (e.g. ${{ secrets.DEV_HOST }})
<path>	yes	Remote deployment path
<method>	no	One of: sftp, rsync, scp, composer, webhook
<branch>	no	Branch that triggers this deploy
<src-dir>	no	Local source directory to deploy (default: src/)

<scripts> — Optional

Contains one or more <script> elements:

Attribute/Element	Required	Description
@name	yes	Script identifier (e.g. build, test, lint, package)
@phase	no	Lifecycle phase: pre-build, build, post-build, test, lint, pre-deploy, post-deploy, release, validate
<command>	yes	Shell command to execute
<description>	no	Human-readable purpose
<runner>	no	Execution context (make, composer, bash, php)

<overrides> — Optional

Per-repo exceptions to the platform definition:

Element	Description
<skip-files>	<file> elements listing paths that bulk sync should NOT overwrite
<skip-workflows>	<file> elements listing workflow filenames to skip
<extra-secrets>	<secret name="" required="" scope=""> for repo-specific secrets beyond the platform default

Minimal Example

<?xml version="1.0" encoding="UTF-8"?>
<mokostandards xmlns="https://git.mokoconsulting.tech/MokoConsulting/moko-platform"
               schema-version="1.0">
  <identity>
    <name>MokoTesting</name>
    <org>MokoConsulting</org>
  </identity>
  <governance>
    <platform>default-repository</platform>
    <standards-version>04.07.00</standards-version>
    <standards-source>https://git.mokoconsulting.tech/MokoConsulting/moko-platform</standards-source>
  </governance>
</mokostandards>

Full Example (WaaS Component)

<?xml version="1.0" encoding="UTF-8"?>
<mokostandards xmlns="https://git.mokoconsulting.tech/MokoConsulting/moko-platform"
               schema-version="1.0">

  <identity>
    <name>MokoJoomTOS</name>
    <org>MokoConsulting</org>
    <description>A component to present a site's Terms of Service and privacy policy even through offline.</description>
    <license spdx="GPL-3.0-or-later">GNU General Public License v3</license>
    <topics>
      <topic>joomla</topic>
      <topic>system-plugin</topic>
      <topic>terms-of-service</topic>
      <topic>waas</topic>
    </topics>
  </identity>

  <governance>
    <platform>waas-component</platform>
    <standards-version>04.07.00</standards-version>
    <standards-source>https://git.mokoconsulting.tech/MokoConsulting/moko-platform</standards-source>
    <last-synced>2026-05-01T12:00:00Z</last-synced>
  </governance>

  <build>
    <language>PHP</language>
    <runtime>php:>=8.1</runtime>
    <package-type>joomla-extension</package-type>
    <entry-point>src/mokojoomtos.xml</entry-point>
    <artifact>
      <format>zip</format>
      <path>dist/</path>
      <filename>plg_system_mokojoomtos.zip</filename>
    </artifact>
    <dependencies>
      <requires name="joomla/cms" version=">=5.0" type="platform" />
      <requires name="mokoconsulting-tech/enterprise" version="*" type="composer" />
    </dependencies>
  </build>

  <deploy>
    <target name="dev" enabled="true">
      <host>${{ secrets.DEV_HOST }}</host>
      <path>/var/www/dev/plugins/system/mokojoomtos</path>
      <method>sftp</method>
      <branch>dev/**</branch>
      <src-dir>src/</src-dir>
    </target>
    <target name="demo">
      <host>${{ secrets.DEMO_HOST }}</host>
      <path>/var/www/demo/plugins/system/mokojoomtos</path>
      <method>sftp</method>
      <branch>main</branch>
      <src-dir>src/</src-dir>
    </target>
  </deploy>

  <scripts>
    <script name="build" phase="build">
      <command>make build</command>
      <description>Build the extension zip package</description>
      <runner>make</runner>
    </script>
    <script name="lint" phase="lint">
      <command>vendor/bin/phpcs --standard=Joomla src/</command>
      <description>Run PHP_CodeSniffer with Joomla coding standard</description>
      <runner>composer</runner>
    </script>
    <script name="test" phase="test">
      <command>vendor/bin/phpunit</command>
      <description>Run PHPUnit test suite</description>
      <runner>composer</runner>
    </script>
    <script name="validate" phase="validate">
      <command>vendor/bin/moko-validate</command>
      <description>Validate moko-platform compliance</description>
      <runner>composer</runner>
    </script>
  </scripts>

  <overrides>
    <skip-files>
      <file>composer.json</file>
    </skip-files>
    <extra-secrets>
      <secret name="JOOMLA_API_TOKEN" required="true" scope="repository" />
    </extra-secrets>
  </overrides>

</mokostandards>

Migration from Legacy Format

The old format was a single YAML-like line:

platform: default-repository

The bulk sync will:

1. Read the legacy value
2. Generate a new XML .mokostandards with the detected platform
3. Commit the replacement file to .gitea/.mokostandards
4. Delete the old file from legacy locations (root, .github/)

Validation

Repos are validated against mokostandards-schema.xsd during:

• Bulk sync (automation/bulk_sync.php)
• Standards compliance workflow (.gitea/workflows/standards-compliance.yml)
• Local validation via vendor/bin/moko-validate

A missing or invalid .mokostandards file is a compliance failure.

Tooling Integration

Tool	How it uses .mokostandards
bulk_sync.php	Reads <governance><platform> to select the correct definition .tf file; updates <last-synced> on success
enforce_tags.sh	Reads <identity><name> for tag naming
deploy-*.yml	Reads <deploy><target> for host, path, method
Makefile	Can source <scripts> for consistent make targets
moko-validate	Validates the XML against the XSD and checks required fields
detectPlatform()	Falls back to name/topic heuristics only when .mokostandards is missing or unparseable

---

Repo: moko-platform · moko-platform wiki

Field	Value
Minimum Version	04.07.00
Platform	all
Applies To	All repositories

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