45 lines
2.0 KiB
Markdown
45 lines
2.0 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project Scope
|
|
- Repository contains a small PHP CLI utility for SFTP-based sync/delete operations.
|
|
- Main executable: `src/SFTPsync.php`
|
|
- Connection layer: `src/SFTPconnection.php`
|
|
|
|
## Goals When Editing
|
|
- Preserve backward-compatible CLI behavior unless the user explicitly requests a breaking change.
|
|
- Keep the tool dependency-free (only PHP core + `ext-ssh2`).
|
|
- Prefer minimal, readable changes.
|
|
|
|
## Important Behavior to Preserve
|
|
- Actions are repeatable and executed in the same order as provided on CLI.
|
|
- Exit codes:
|
|
- `0` success
|
|
- `1` runtime/SFTP error
|
|
- `2` argument/usage error
|
|
- Missing `--host`, `--user`, `--password` should still support interactive prompt mode.
|
|
- `--skip` and `--skip-delete` matching semantics should remain stable.
|
|
- Rules without wildcard characters (`*`, `?`) use legacy exact matching.
|
|
- Exact rules without slash match any path segment; exact rules with slash match a relative subpath.
|
|
- Rules containing `*` or `?` are glob patterns matched against normalized relative paths.
|
|
- Glob matching should prefer native `fnmatch()` and keep a regex fallback for platforms where it is unavailable.
|
|
- Skip patterns should be prepared once, not recompiled for every file.
|
|
- `--no-print-skip` must suppress only `SKIP` log lines, without changing skip decisions or summary counters.
|
|
- `--delete-dir` safety guard against dangerous paths (`/`, empty path, dot paths) must remain intact.
|
|
|
|
## Coding Conventions
|
|
- Target PHP 8+ compatibility.
|
|
- Keep strict types in `src/SFTPsync.php`.
|
|
- Avoid adding external libraries or framework structure.
|
|
- Use clear runtime exceptions for operational failures.
|
|
|
|
## Validation Checklist
|
|
- Lint changed PHP files:
|
|
- `php -l src/SFTPsync.php`
|
|
- `php -l src/SFTPconnection.php`
|
|
- If CLI options are changed, update `README.md` in the same change.
|
|
- Ensure examples in `README.md` remain executable from repository root.
|
|
|
|
## Documentation Rules
|
|
- Keep `README.md` in English.
|
|
- Document user-visible flags/behavior changes in README immediately.
|