h1.Problem

A file integrity check in translate5 instances is needed. 

That enables then: 

• identification of modified (hotpatched) files, to prevent overwrite by update
• clean up of out dated / not used files anymore

The manifest source of truth should be the deployment process, where the final downloadable ZIP contents are known.

Goal

Implement integrity checking based on manifests generated during deployment and embedded into downloadable installer ZIPs.

Scope

• Generate integrity manifests during deployment.
• Embed manifests into checked package ZIPs.
• Update installer/checker logic to use package-local manifests.
• Exclude ExtJS dependency ZIPs from manifest generation and checking.
• Keep legacy installations usable by warning and skipping missing manifests.

implementation

The implementation provides package-local integrity manifests and a `system:integrity` CLI command for checking installed files against those manifests.

The command reports:

• modified files, including manifest/local mtime and size
• additional files, meaning files present locally but not covered by manifests
• deleted files, meaning manifest files missing locally

`system:integrity` loads manifests from:

• application root
• installed dependency targets
• `post_install_copy` target manifests

  If no integrity manifests are loaded at all, the command fails because no reliable check can be performed. Missing legacy/package manifests are still reported as warnings where partial checks remain possible.

CLI options

• `--check-modified`: checks modified files only and returns success only if no modifications are found. Intended for updater hotfix protection.
• `--list-additional-files`: disables compact directory output and lists all additional files.
• `--clean-additional`: enables cleanup mode for additional files.
• `--path <path>`: required repeatable path filter for cleanup.
• `--yes`: executes cleanup. Without `yes`, cleanup is a dry-run.

exclusions

The integrity check excludes:

• ExtJS dependencies `extjs-62` and `extjs-70`
• manifest files
• `application/config/installation.ini`
• `application/config/dependencies-installed.json`
• legacy `application/config/integrity-manifest.json`
• `downloads/`
• `APPLICATION_ROOT/data`
• `APPLICATION_DATA` if defined and different from `APPLICATION_ROOT/data`

cleanup safety

Cleanup deletes only paths detected as additional and matching the provided `--path` filters. Cleanup is blocked if modified files are detected. Symlinks are deleted as links and are not followed.

technical notes

`IntegrityManifest` is implemented as an instance-based helper with dedicated exceptions. Lower-level integrity services receive dependencies via constructor injection and provide `create()` helpers for high-level wiring.

Manual follow-up

• Run deployment packaging on the build server.
• Verify generated ZIPs contain .translate5-integrity-manifest.json.
• Verify ExtJS ZIPs do not contain manifests.
• Install/update an instance and run:
  • t5 system:integrity

Acceptance Criteria

• Deployment creates package-local manifests for translate5.zip and third-party-dependencies.
• ExtJS dependency ZIPs are excluded from manifest generation and integrity checking.
• Installer no longer relies on one aggregate manifest generated during update.
• system:integrity checks all available package manifests and reports modified, added, and deleted files.
• Legacy installations without manifests produce warnings instead of hard failures.