Metadata-Version: 2.4
Name: mql5-safe-maintainer-toolkit
Version: 0.4.0
Summary: Deterministic integrity, safety, and compile-log reporting for MQL5 maintenance.
Author: MQL5 Safe Maintainer Toolkit contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/darenyew7527/mql5-safe-maintainer-toolkit
Project-URL: Repository, https://github.com/darenyew7527/mql5-safe-maintainer-toolkit
Project-URL: Issues, https://github.com/darenyew7527/mql5-safe-maintainer-toolkit/issues
Project-URL: Changelog, https://github.com/darenyew7527/mql5-safe-maintainer-toolkit/blob/main/CHANGELOG.md
Keywords: mql5,metaeditor,integrity,maintenance,security
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

﻿# MQL5 Safe Maintainer Toolkit

A safety-focused, open-source command-line toolkit for maintaining MQL5
codebases. Version 0.4.0 provides deterministic integrity, source-review,
combined-maintenance, and privacy-reduced MetaEditor compile-log reports in
text, JSON, and SARIF 2.1.0, plus a reusable GitHub Action, verified PyPI and
`pipx` installation paths, and tokenless Trusted Publishing.

## Current status

This project is in early development. All source code, tests, examples, and
documentation in this repository are newly written for this project.

## Available capabilities

- Deterministic SHA-256 source integrity manifests
- Verification of modified, missing, and unexpected files
- Deterministic source safety and privacy review scans
- Deterministic combined JSON and Markdown maintenance reports
- Read-only MetaEditor compile-log parsing with bounded, path-reduced text and
  JSON reports
- Deterministic SARIF 2.1.0 output with stable rules and partial fingerprints
- A reusable, read-only GitHub Action for an existing MetaEditor compile log
- A verified wheel and source distribution published through PyPI Trusted
  Publishing without a stored API token
- Isolated command-line installation with `pipx`

## v0.x safety contract

The `manifest` and `verify` scope is limited to a trusted, stationary
local source snapshot whose target directory is explicitly supplied by the
user. No other program may modify, move, replace, or relink files or
directories in that snapshot while a command is running.

Checked paths and scanned entries are rejected when they contain a symbolic
link, Windows junction, or other reparse point. Repeated metadata checks reduce
accidental race exposure, but v0.4.0 does not claim to resist malicious
concurrent filesystem replacement or to eliminate every TOCTOU race.

The `compile-report` command reads only the explicitly selected stationary log
file. It does not launch MetaEditor, compile or execute source, inspect a
terminal, or connect to an account or broker. Absolute source paths are reduced
before output, but source file names and diagnostic messages can still contain
project-specific information and must be reviewed before sharing.

A manifest output path must name a new file that does not already exist, and
its parent directory must already exist as an ordinary directory. The toolkit
never intentionally overwrites an existing file or other filesystem object.
All scan and verification results require human review; they are evidence, not
an automatic safety approval. The same rule applies to compile reports.

## Installation and usage

For the command-line application, the recommended installation is an isolated
`pipx` environment:

```text
pipx install mql5-safe-maintainer-toolkit==0.4.0
mql5-safe-maintainer --version
```

Alternatively, install the package inside an activated Python virtual
environment:

```text
python -m pip install mql5-safe-maintainer-toolkit==0.4.0
mql5-safe-maintainer --version
```

The exact version pin prevents an installation command from silently selecting
a later release. The
[release guide](https://github.com/darenyew7527/mql5-safe-maintainer-toolkit/blob/main/docs/releasing.md)
documents distribution checksums, PyPI attestations, and maintainer publishing
steps.

For development, this project uses a `src` layout. The recommended editable
setup from a trusted repository checkout is:

```text
python -m pip install -e .
mql5-safe-maintainer manifest <target-directory> --output <new-manifest.json>
mql5-safe-maintainer verify <target-directory> --manifest <manifest.json>
mql5-safe-maintainer scan <target-directory> --format text
mql5-safe-maintainer check-all <target-directory> --output-dir <new-report-directory>
mql5-safe-maintainer compile-report <metaeditor-log> --format json
mql5-safe-maintainer compile-report <metaeditor-log> --format sarif --output <new-report.sarif>
```

Alternatively, when running directly from the repository, set `PYTHONPATH` to
the repository's `src` directory first. For PowerShell:

```powershell
$env:PYTHONPATH = "src"
python -m mql5_safe_maintainer_toolkit --help
```

Exit codes:

- `0`: help or version output succeeded, no subcommand performed the retained
  no-op behavior, manifest creation succeeded, or verification found an exact
  match, or a scan, combined check, or compile report completed with a `PASS`
  result
- `1`: verification found differences, a source scan produced findings, or a
  combined check or compile report completed with a `REVIEW` result
- `2`: invalid arguments, unsafe paths, malformed manifest data, or an I/O or
  output error

## Quick Start with the safe example

The repository includes a newly written, no-op MQL5 source snapshot at
`examples/safe-mql5-project` and synthetic compile logs at
`examples/compile-logs`. Create a new ignored output directory, then run the
maintenance workflows and parse a clean synthetic compile result:

```text
python -c "from pathlib import Path; Path('artifacts/v0.4.0-demo').mkdir(parents=True)"
mql5-safe-maintainer manifest examples/safe-mql5-project --output artifacts/v0.4.0-demo/manifest.json
mql5-safe-maintainer verify examples/safe-mql5-project --manifest artifacts/v0.4.0-demo/manifest.json
mql5-safe-maintainer scan examples/safe-mql5-project --format text
mql5-safe-maintainer check-all examples/safe-mql5-project --output-dir artifacts/v0.4.0-demo/check-all
mql5-safe-maintainer compile-report examples/compile-logs/clean.txt --format sarif --output artifacts/v0.4.0-demo/compile-report.sarif
```

The output paths must be new. Use a different output directory for a repeated
run. The module form `python -m mql5_safe_maintainer_toolkit` can replace
`mql5-safe-maintainer` in each command.

## Source safety scan

`scan` checks only the explicitly supplied trusted, stationary source snapshot.
It reports possible credentials, private data, absolute paths, private runtime
files, MQL imports, web requests, and order or position operations for human
review. Findings are observations and do not assert that content is malicious.

```text
python -m mql5_safe_maintainer_toolkit scan <target-directory>
python -m mql5_safe_maintainer_toolkit scan <target-directory> --format json --output <new-report.json>
python -m mql5_safe_maintainer_toolkit scan <target-directory> --max-file-bytes 1048576
```

The default format is text and the default per-file limit is 1,048,576 bytes.
Files over the limit are reported without reading their full content. Binary or
non-decodable files are reported without displaying their bytes. Sensitive
evidence is redacted and bounded. An output path must be new, is excluded when
it is inside the target, and is never intentionally overwritten.

## MetaEditor compile reports

`compile-report` reads one explicitly selected MetaEditor compilation log. It
accepts UTF-8 and UTF-16 text, recognizes diagnostic lines shaped like
`source(line,column) : error|warning [code]: message`, and uses a final
`Result: N errors, M warnings` line when present. If the result line is absent
but diagnostics are present, the report marks its counts as derived.

```text
python -m mql5_safe_maintainer_toolkit compile-report <compile-log>
python -m mql5_safe_maintainer_toolkit compile-report <compile-log> --format json
python -m mql5_safe_maintainer_toolkit compile-report <compile-log> --format json --output <new-report.json>
python -m mql5_safe_maintainer_toolkit compile-report <compile-log> --format sarif --output <new-report.sarif>
python -m mql5_safe_maintainer_toolkit compile-report <compile-log> --max-log-bytes 4194304
```

The default input limit is 4,194,304 bytes. Output omits the input path and
reduces diagnostic source paths to bounded file names. Absolute paths and
common secret-looking values in messages are replaced before rendering.
Messages and file names can still expose project-specific identifiers, so
review every report before publishing it.

SARIF output uses version 2.1.0, stable rule identifiers, code-scanning levels,
bounded unlocated-summary results, and deterministic partial fingerprints.
Diagnostic source paths remain reduced to file names. That privacy boundary
means a code-scanning consumer might not attach a finding to the exact nested
repository path; review the SARIF before upload.

MetaQuotes documents compilation
[errors](https://www.mql5.com/en/docs/constants/errorswarnings/errorscompile)
and [warnings](https://www.mql5.com/en/docs/constants/errorswarnings/warningscompile)
separately. This toolkit records those results but does not invoke or replace
the compiler.

## Reusable GitHub Action

The repository root contains a composite action that sets up a supported
Python runtime and creates a report from one existing compile log. It does not
install MetaEditor, run a compiler, execute MQL5, or access a terminal.

```yaml
permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@v6

  # A preceding, separately controlled step must create build/metaeditor.log.
  - name: Create privacy-reduced MQL5 compile evidence
    id: mql5-report
    uses: darenyew7527/mql5-safe-maintainer-toolkit@v0.4.0
    with:
      log-file: build/metaeditor.log
      output: build/mql5-compile-report.sarif
      format: sarif
      fail-on-findings: "false"

  - name: Upload SARIF
    uses: github/codeql-action/upload-sarif@v4
    with:
      sarif_file: build/mql5-compile-report.sarif

  - name: Enforce compile review gate
    if: steps.mql5-report.outputs.result == 'REVIEW'
    shell: bash
    run: exit 1
```

The action outputs `result`, `errors`, `warnings`, and `report-file`. Its report
path must be new. With the default `fail-on-findings: "true"`, any error or
warning returns a failing step after the no-clobber report is created. GitHub
documents the supported SARIF 2.1.0 subset and the separate upload action in
its [SARIF upload guidance](https://docs.github.com/en/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/upload-sarif-file).

## Combined maintenance reports

`check-all` creates one new output directory and runs manifest creation,
immediate verification, and the source scan before producing a shared summary:

```text
python -m mql5_safe_maintainer_toolkit check-all <target-directory> --output-dir <new-report-directory>
```

The new directory contains exactly `manifest.json`, `scan-report.json`,
`maintenance-report.json`, and `maintenance-report.md`. If the output directory
is inside the target, that exact directory is excluded from every component
check. The directory and all four files use no-clobber creation. Treat a report
set as complete only after the command returns exit code `0` or `1`. On exit
code `2`, do not assume the set is complete. Error paths attempt identity-bound
best-effort cleanup, but a complete four-file set can remain if only the final
console message fails; inspect such a directory manually before removing it.

The JSON and Markdown summaries come from the same result data and contain no
timestamps, host names, user names, or absolute target paths. A `PASS` or
`REVIEW` result still requires human review.

## Planned capabilities

The versioned
[release roadmap](https://github.com/darenyew7527/mql5-safe-maintainer-toolkit/blob/main/ROADMAP.md)
records the ordered path from
`0.4.0` through the proposed stable `1.0.0` contract. Work advances one fully
tested, merged, and released version at a time.

## Documentation and contribution

- [Getting started](https://github.com/darenyew7527/mql5-safe-maintainer-toolkit/blob/main/docs/getting-started.md)
- [Command reference](https://github.com/darenyew7527/mql5-safe-maintainer-toolkit/blob/main/docs/command-reference.md)
- [Security model](https://github.com/darenyew7527/mql5-safe-maintainer-toolkit/blob/main/docs/security-model.md)
- [Release and installation verification](https://github.com/darenyew7527/mql5-safe-maintainer-toolkit/blob/main/docs/releasing.md)
- [Contributing](https://github.com/darenyew7527/mql5-safe-maintainer-toolkit/blob/main/CONTRIBUTING.md)
- [Security policy](https://github.com/darenyew7527/mql5-safe-maintainer-toolkit/blob/main/SECURITY.md)
- [Changelog](https://github.com/darenyew7527/mql5-safe-maintainer-toolkit/blob/main/CHANGELOG.md)
- [Release roadmap](https://github.com/darenyew7527/mql5-safe-maintainer-toolkit/blob/main/ROADMAP.md)
- [Code of conduct](https://github.com/darenyew7527/mql5-safe-maintainer-toolkit/blob/main/CODE_OF_CONDUCT.md)

## Safety model

- No trading strategy implementation
- No broker or account integration
- No credentials or private runtime data
- No automatic discovery of unrelated directories
- Only a target directory explicitly supplied by the user is scanned
- Only an explicitly supplied compile log is parsed
- Targets must be trusted, stationary local source snapshots
- Symbolic links, junctions, and other reparse points are rejected
- Existing output objects are never intentionally overwritten
- v0.4.0 does not promise protection from malicious concurrent filesystem races
- Every scan, verification, and compile result requires human review
- No trading actions

## Development status

The v0.4.0 release provides deterministic manifest, verification, source-scan,
combined-report, and MetaEditor compile-report commands; text, JSON, and SARIF
compile evidence; a reusable GitHub Action; verified wheel, source-distribution,
`pip`, and `pipx` installation paths; tokenless PyPI publishing with PEP 740
attestations; Linux and Windows test coverage; and synthetic examples under the
restricted v0.x safety contract above.

## License

This project is licensed under the MIT License. See the LICENSE file for details.
