<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>

This file is part of a Moko Consulting project.

SPDX-License-Identifier: GPL-3.0-or-later

# FILE INFORMATION
DEFGROUP: MokoStandards.Documentation.API
INGROUP: MokoStandards.Documentation
REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API
PATH: /docs/api/maintenance/index.md
VERSION: 04.06.00
BRIEF: API reference for housekeeping and maintenance scripts in api/maintenance/
-->

# Maintenance Scripts

Scripts in `api/maintenance/` perform housekeeping tasks: pinning action SHAs,
syncing README files, propagating version numbers, and managing GitHub labels.

---

## pin_action_shas.php

Pins all `uses:` references in `.github/workflows/` to immutable SHA digests,
replacing floating tags (e.g. `v4`) to prevent supply-chain attacks.

```bash
php api/maintenance/pin_action_shas.php --dry-run
php api/maintenance/pin_action_shas.php --verbose
```

| Option | Description |
|--------|-------------|
| `--dry-run` | Show changes without writing files |
| `--verbose` / `-v` | Print each file processed |
| `--help` / `-h` | Show help and exit |

---

## setup_labels.php

Deploys the full set of GitHub issue and PR labels to all governed
repositories. Idempotent — creates missing labels and updates colour/description
of existing ones via `gh label create --force`.

**Label groups (67 total):**

| Group | Count | Examples |
|-------|-------|---------|
| Project Type | 3 | `joomla`, `dolibarr`, `generic` |
| Language | 6 | `php`, `javascript`, `css` |
| Component | 8 | `documentation`, `ci-cd`, `security`, `tests` |
| Workflow | 5 | `automation`, `mokostandards`, `breaking-change` |
| Priority | 4 | `priority: critical` … `priority: low` |
| Type | 5 | `type: bug`, `type: feature`, `type: chore` |
| Status | 5 | `status: pending`, `status: in-progress`, `status: blocked` |
| Size | 6 | `size/xs` … `size/xxl` |
| Health | 4 | `health: excellent` … `health: poor` |
| Sync/Automation | 11 | `standards-update`, `deploy-failure`, `version-drift` |
| Testing | 4 | `type: test`, `needs-testing`, `test-failure`, `regression` |
| Version/Release | 6 | `type: release`, `release-candidate`, `minor-release`, `patch-release` |

```bash
php api/maintenance/setup_labels.php
php api/maintenance/setup_labels.php --dry-run
```

| Option | Description |
|--------|-------------|
| `--dry-run` | Preview label changes without applying them |
| `--help` / `-h` | Show help and exit |

---

## sync_dolibarr_readmes.php

Keeps the root `README.md` and `src/README.md` in sync for Dolibarr module
repositories. Copies the canonical root README into `src/` to satisfy the
module store requirement.

```bash
php api/maintenance/sync_dolibarr_readmes.php --path /path/to/module
php api/maintenance/sync_dolibarr_readmes.php --path /path/to/module --dry-run
```

| Option | Default | Description |
|--------|---------|-------------|
| `--path` | `.` | Repository root |
| `--dry-run` | off | Show what would be synced without writing |

---

## update_sha_hashes.php

Regenerates SHA-256 hashes in the script registry (`api/definitions/`) to
reflect current file contents after scripts are modified.

```bash
php api/maintenance/update_sha_hashes.php --dry-run
php api/maintenance/update_sha_hashes.php --verbose
```

| Option | Description |
|--------|-------------|
| `--dry-run` | Show hash differences without updating |
| `--verbose` / `-v` | Print each file processed |
| `--help` / `-h` | Show help and exit |

---

## update_version_from_readme.php

Reads the canonical version from the `VERSION` field in `README.md`'s FILE
INFORMATION block and propagates it to all badges, headers, and other VERSION
fields throughout the repository. Run this after bumping the version in
`README.md` instead of manually updating every file.

```bash
php api/maintenance/update_version_from_readme.php --path .
php api/maintenance/update_version_from_readme.php --path . --dry-run
php api/maintenance/update_version_from_readme.php --path . --create-issue --repo owner/repo
```

| Option | Default | Description |
|--------|---------|-------------|
| `--path` | `.` | Repository root |
| `--dry-run` | off | Show changes without writing |
| `--create-issue` | off | Create a GitHub issue listing updated files |
| `--repo <owner/repo>` | — | Repository for issue creation |

---

## rotate_secrets.php

Audits FTP secrets and variables (DEV/DEMO/RS) across all governed repositories.
Reports missing auth keys, incomplete environment configs, and optionally posts
results as a GitHub issue in MokoStandards.

```bash
php api/maintenance/rotate_secrets.php --all
php api/maintenance/rotate_secrets.php --repo MokoCRM
php api/maintenance/rotate_secrets.php --all --create-issue
php api/maintenance/rotate_secrets.php --all --json
```

| Option | Description |
|--------|-------------|
| `--all` | Audit all governed repos |
| `--repo <name>` | Audit a single repo |
| `--json` | Machine-readable JSON output |
| `--create-issue` | Post/update audit results as a GitHub issue |
| `--org <name>` | GitHub organization (default: `MokoConsulting`) |

---

## repo_inventory.php

Generates a live inventory dashboard of all governed repos and posts it as a
GitHub issue in MokoStandards. Shows platform, version, rulesets status,
project linkage, and open issue count per repo. Auto-updates on each run.

```bash
php api/maintenance/repo_inventory.php
php api/maintenance/repo_inventory.php --dry-run
php api/maintenance/repo_inventory.php --json
```

| Option | Description |
|--------|-------------|
| `--dry-run` | Preview without posting issue |
| `--json` | JSON output to stdout |
| `--org <name>` | GitHub organization (default: `MokoConsulting`) |

---

**Location:** `docs/api/maintenance/`
**Mirrors:** `api/maintenance/`
**Last Updated:** 2026-03-30