hlsync 1.17.2__py3-none-any.whl

hlsync-1.17.2.dist-info/METADATA

@@ -0,0 +1,687 @@
+Metadata-Version: 2.4
+Name: hlsync
+Version: 1.17.2
+Summary: Synchronize local files with remote servers over explicit FTPS
+Author: HLSync contributors
+License-Expression: LicenseRef-PolyForm-Strict-1.0.0
+Project-URL: Homepage, https://github.com/ediril/hlsync
+Project-URL: Changelog, https://github.com/ediril/hlsync/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ediril/hlsync/issues
+Project-URL: Repository, https://github.com/ediril/hlsync.git
+Keywords: deployment,ftp,ftps,synchronization
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Archiving :: Backup
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pathspec<2,>=0.12.1
+Provides-Extra: dev
+Requires-Dist: build<2,>=1; extra == "dev"
+Requires-Dist: pyftpdlib[ssl]<3,>=2.0; extra == "dev"
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: ruff<1,>=0.12; extra == "dev"
+Requires-Dist: setuptools>=77; extra == "dev"
+Requires-Dist: twine<7,>=6; extra == "dev"
+Dynamic: license-file
+
+# HLSync
+
+HLSync (`hlsync`) is a command-line workflow for deploying local
+projects to shared hosting over explicit FTP over TLS (FTPS): map once, preview
+the diff, then push the intended files.
+
+HLSync is pre-alpha software. Commands and configuration may change before a
+stable release.
+
+## Who is it for?
+
+HLSync is for people who still deploy websites or small projects to shared hosting over FTP.
+
+If your current process is basically “figure out which files changed and upload them,” HLSync gives you a safer, more repeatable version of that workflow without requiring a full deployment system.
+
+It works best when your local project is the source of truth and the remote server is simply where the project gets deployed.
+
+## Installation
+
+HLSync requires Python 3.10 or newer. Install it from PyPI as an isolated
+command-line tool with uv:
+
+```console
+uv tool install hlsync
+```
+
+If you previously installed `hook-line-sync`, switch with:
+
+```console
+uv tool uninstall hook-line-sync
+uv tool install hlsync
+```
+
+Upgrade later with:
+
+```console
+uv tool upgrade hlsync
+```
+
+The FTPS server must support explicit TLS with protected data connections
+(`AUTH TLS` and `PROT P`). HLSync prefers MLSD listings; servers without MLSD
+use Unix-style LIST listings with SIZE and MDTM for exact file metadata.
+LIST mode includes dotfiles and requires two extra requests per file. Push additionally
+requires MFMT (or writable MDTM on vsFTPd) and MDTM read-back to apply and verify
+uploaded-file timestamps.
+
+## Quick start
+
+HLSync reads credentials from environment variables. The defaults are:
+
+```text
+PROD_FTPS_USERNAME
+PROD_FTPS_PASSWORD
+```
+
+From the local project root:
+
+```console
+hlsync create prod --host ftp.example.com --remote-root /public_html/site
+hlsync connect
+hlsync exclude .git node_modules
+hlsync diff
+hlsync push
+```
+
+`create` proposes the current directory as the local root; pressing Enter accepts
+it. Declining prompts for another local folder. Use `--local-root PATH` to
+provide one directly. Both `diff` and `push` recurse by default. Use `-s` /
+`--shallow` to process only the selected folder's immediate contents.
+
+## Profiles and mapping
+
+A profile identifies one deployment target: protocol, host, port, remote root,
+credential environment-variable names, and one local root. Multiple
+profiles may use the same server. Credential values are never stored in
+`~/.hlsync/configs.json`.
+
+FTPS is the default and currently the only protocol. Override credential
+variable names when creating a profile if needed:
+
+```console
+hlsync create staging \
+  --host ftp.example.com \
+  --remote-root /public_html/staging \
+  --local-root /path/to/project \
+  --username-env STAGING_FTPS_USERNAME \
+  --password-env STAGING_FTPS_PASSWORD
+```
+
+HLSync stores the canonical absolute local root and maps every descendant to
+the same relative path under the remote root. Roots may not overlap across
+profiles. Remapping requires confirmation and defaults to no.
+
+Use `map` to change either side after creation. Omit `--local-root` to use the
+current directory; changing only the remote root preserves the local root:
+
+```console
+hlsync map staging --local-root /new/local/path
+hlsync map staging --remote-root /new/remote/root
+```
+
+The normal workflow is to run HLSync inside a mapped root or one of its
+descendants. The current directory selects the containing profile and relative
+local scope automatically:
+
+```console
+hlsync profiles          # all profiles; * marks the current one
+hlsync profile           # current profile name
+hlsync profile --details # current profile details
+hlsync profile staging   # verify and print a named profile
+hlsync profile staging --details
+hlsync root staging      # print the mapped local root only
+hlsync connect            # verify FTPS, then disconnect
+hlsync remove staging    # remove local configuration only
+```
+
+Outside every mapped root, `hlsync profile` reports that no profile is active
+and suggests `hlsync PROFILE COMMAND`. Commands that require a profile need
+that explicit profile prefix. Named and inferred lookups both require
+`--details` for the full view.
+
+Because `root` writes only the canonical path, it can be composed with the
+shell when you want to switch directories:
+
+```console
+cd "$(hlsync root staging)"
+```
+
+An unqualified profile-aware command fails outside every mapped root. When you
+intentionally need to operate from elsewhere—or override the profile inferred
+from the current directory—put the profile before the command. The override
+lasts for that command only and uses the selected profile's local root as its
+working directory:
+
+```console
+hlsync staging list
+hlsync staging diff templates
+hlsync staging push templates -r
+```
+
+No profile selection is persisted between commands.
+
+## Synchronization rules
+
+HLSync automatically honors `.gitignore` files as local exclusions. When the
+mapped local root is inside a Git repository, this includes all ancestor
+`.gitignore` files up to the nearest repository root, plus files inside the
+mapped tree. Without an enclosing repository, ignore scope starts at the mapped
+root. Git worktrees are supported; no Git installation is needed.
+Explicit HLSync rules override this baseline; profile rules override global rules.
+To deploy a Git-ignored path, use `hlsync include vendor/` (or a specific file).
+Ignore files above the repository root, Git's global excludes, and the Git index
+are not consulted; matching tracked files are excluded too.
+
+**Review `hlsync push --dry -p` before pruning:** with `-p`, locally excluded
+files that are already deployed are deleted remotely. Without `-p`, their remote
+copies are left alone; remote exclusion rules protect paths even when pruning.
+
+Global rules live in `~/.hlsync/rules.json`, apply to every profile, and are
+created with default exclusions for version-control metadata and common logs:
+
+```text
+**/.git/**
+**/.svn/**
+**/.hg/**
+**/.DS_Store
+**/Thumbs.db
+**/desktop.ini
+**/.gitignore
+**/.gitmodules
+**/error_log
+```
+
+Manage global exclusions and inclusions from any directory with `-g` /
+`--global`. Global operands are reusable patterns rooted at every profile's
+local root; append `/` to target a complete directory tree:
+
+```console
+hlsync exclude -g --pattern '*.tmp'
+hlsync include -g --pattern 'public/*.tmp'
+hlsync rules -g      # inspect global rules
+hlsync rules rm g4   # g prefix selects global rules
+```
+
+Global rules apply first and profile rules apply afterward, so an ordinary
+profile inclusion can override a global exclusion. `hlsync rules` merges both
+layers into one folder-grouped view, placing matching profile rules after
+global rules. Global rules have `g`-prefixed IDs such as `g4`; profile rule IDs
+remain numeric. IDs identify only current rules and may be reused after a rule
+is removed. HLSync never silently adds new defaults to an existing global
+rules file.
+
+Exclude current paths permanently:
+
+```console
+hlsync exclude .git node_modules composer.json composer.lock
+hlsync exclude '*.md'
+```
+
+Normal wildcard operands are expanded against the current local tree and
+recorded as exact paths. Quote them so the shell does not reject or alter them;
+quoted and shell-expanded matches produce the same path rules.
+
+Use `--pattern` when future matching paths should also be covered:
+
+```console
+hlsync exclude --pattern '*.md'       # this directory only
+hlsync exclude --pattern '**/*.log'   # every directory below this point
+hlsync include --pattern 'vendor/**'  # re-include a subtree
+```
+
+Use `--anywhere` (or `--any`) to match a name at every depth, including future
+files. It works with both `exclude` and `include`, and replaces `--pattern`:
+
+```console
+hlsync exclude --anywhere filename.ext  # current directory and descendants
+hlsync exclude --any '*.log'            # quote wildcards to preserve the pattern
+hlsync exclude -g --anywhere cache/     # matching directory trees in every profile
+```
+
+`*` matches within one path segment; a complete `**` segment crosses directory
+levels. Patterns are rooted where the command runs. HLSync rules are not
+Gitignore syntax: `!`, `?`, bracket patterns, absolute paths, parent traversal,
+and partial-segment `**` are rejected.
+
+Local rules define the authoritative local set. Remote rules instead protect
+server-side paths from synchronization:
+
+```console
+hlsync exclude --remote subdomains
+hlsync include --remote subdomains
+```
+
+Remote operands are declarative and never require a connection when recorded.
+`subdomains` and `subdomains/` store the same exact boundary. During diff or
+push, an existing remote file is left untouched; an existing remote directory
+and everything beneath it are left untouched without traversing the directory.
+A matching remote inclusion removes or overrides that boundary and returns the
+path to normal push policy. Remote directory boundaries cannot be pierced by a
+more specific child inclusion. `hlsync rules` groups the two rule targets under
+`Local` and `Remote`.
+
+Local rules keep the original compact JSON form. A missing stored `target`
+means local; only remote rules add `"target": "remote"`.
+
+Rules have stable IDs and the highest matching ID wins. HLSync removes provably
+redundant exact rules but preserves ambiguous wildcard overlaps.
+
+```console
+hlsync rules
+hlsync rules rm 3
+```
+
+Multiple operands and comma-separated groups are accepted. A literal filename
+containing a comma cannot be addressed because commas delimit groups.
+
+## Paths and traversal
+
+Paths are relative to the current directory inside the mapped root. Multiple
+paths and wildcard patterns form one deterministic selection. Absolute paths,
+parent traversal, and paths escaping the mapped root are rejected.
+
+| Command | No path | Explicit directory | Depth option |
+| --- | --- | --- | --- |
+| `list` / `list --remote` | Current directory, one level | Directory contents, one level | `-r` includes descendants |
+| `diff` | Complete current subtree | Complete directory subtree | `-s` limits to immediate contents |
+| `push` | Complete current subtree | Complete directory subtree | `-s` limits to immediate contents |
+| `pull` | Error: path required | Directory contents, one level | `-r` includes descendants |
+
+Diff and push accept `-s` / `--shallow`; `-r` / `--recursive` remains available
+to explicitly select the default. The two flags cannot be combined.
+
+`.` explicitly selects the current directory. An immediate child directory
+outside the traversal depth appears with `▸` but is diagnostic-only: it is not
+created, replaced, deleted, or entered. The selected directory itself may be
+created when selected files require it as their parent. An explicitly selected
+remote-only directory is the deletion target itself, so recursive push
+enumerates that subtree and removes its contents deepest-first. With `-s`,
+deeper folders and their deletion ancestors are retained.
+
+## Local and remote listing
+
+`list` reads only the local filesystem, includes dotfiles, and applies the
+configured rules:
+
+```console
+hlsync list
+hlsync list templates
+hlsync list '*.md'
+hlsync list -r
+hlsync list -r -i
+```
+
+Use `--remote`—or the `lsr` shorthand—to inspect the equivalent FTPS
+tree with the same operands and traversal controls:
+
+```console
+hlsync list --remote
+hlsync list --remote templates -r
+hlsync lsr
+```
+
+Remote listing connects read-only. Remote-excluded paths use `#` and their
+directories are shown as boundaries without being entered.
+
+Directories appear before files at each level, with each group sorted by name.
+Directories end in `/`; local exclusions use `x`, remote exclusions use `#`.
+Single-side listings do not report whether the other side has a copy. `-i`, `--inc`, and
+`--included-only` hide excluded paths. `hlsync ls` remains an unadvertised
+compatibility spelling.
+
+## Diff
+
+`diff` is read-only and shows what the corresponding push would do:
+
+```console
+hlsync diff
+hlsync diff templates
+hlsync diff -s
+hlsync diff templates --shallow
+hlsync diff index.html app.js styles.css
+hlsync diff '**/*.css'
+```
+
+Local path existence decides what is uploaded or replaced. In the default
+push view, remote-only paths are retained because push never deletes without
+`-p`. Preview a pruning push with:
+
+```console
+hlsync diff --prune
+hlsync diff -p
+```
+
+`--pull` changes the perspective for changed existing files and retains
+remote-only paths.
+
+By default, diff shows only what the matching push or pull would do: uploads,
+updates, deletions, and conflicts, under their folder headings. A final
+`Not shown:` line counts what was hidden. Widen the view with:
+
+```console
+hlsync diff -x      # also show excluded paths (--excluded)
+hlsync diff -I      # compare locally excluded paths as included (--include-excluded)
+hlsync diff -a      # show everything, including unchanged and kept paths (--all)
+```
+Recursive diff keeps file-browser order in both views: directories and their
+indented contents appear before files at the parent level.
+Rows without status markers retain blank status columns so names stay aligned.
+Status columns stay fixed at the left; tree indentation applies to path names.
+The status has three slots: action (`+`, `~`, `-`, `?`, `=`), exclusion
+(`x` local, `#` remote), and presence (`l`, `r`, or blank for both sides), so
+`-x` marks an excluded path that `--prune` would delete.
+The `▸` marker means contents were not inspected, including excluded folders.
+Diff reads directories as it traverses the tree and groups their entries under
+folder headings, without separate per-directory read announcements.
+
+For pruning, a locally excluded file is treated as absent. If it exists
+remotely, default diff marks it ` x` and retains it; `diff -p` marks its
+deletion as `-x`. The presence column still reports the actual copies:
+blank when both exist, `r` when only the remote copy exists. An excluded
+directory is a traversal boundary and is retained with `x`. An explicit local
+inclusion for a descendant permits traversal;
+remote exclusions remain hard boundaries. Hiding exclusions never hides a
+deletion: with `-p`, an excluded path that would be deleted always shows as `-x`.
+
+`-I` / `--include-excluded` treats locally excluded paths as included for one
+`diff`, `push`, or `pull`. Exclusion rules and `.gitignore` files are not
+consulted, so nested paths such as `.git/` and `.DS_Store` count too. Remote
+exclusions still apply.
+
+```console
+hlsync diff -I collectiq/data
+hlsync pull -I collectiq/data/.waitlist.sqlite
+hlsync push -I collectiq/data --dry
+```
+
+Diff enters eligible child folders by default. `diff -s` or
+`diff templates --shallow` reads only immediate contents. Unentered child
+folders retain the `▸` marker and are retained, matching `push -s`. Unentered
+folders appear by default only when they could still hold changes; an
+unentered remote-only folder appears as `   r folder/ ▸` with `-a`. Without
+`-p`, diff does not enter remote-only folders, since push would neither change
+nor delete their contents.
+
+Show the current status and directory notation without connecting:
+
+```console
+hlsync --legend
+```
+
+Diff prints each directory as it is compared. For a shell-driven review,
+`--paged` prints one directory, exits, and provides the exact stateless
+`--resume` command for the next deterministic directory.
+
+Colors are automatic on terminals, disabled for pipes and redirection, and
+suppressed when `NO_COLOR` is set. Text markers retain the core meaning without
+color. The left column reports action or status: `x` means locally excluded
+and `#` means remotely excluded. The right column reports presence: `l` means
+local only, `r` means remote only, and a blank means both sides. For example,
+`x   notes/ ▸` exists on both sides but is locally excluded, while
+`# r millionminds/ ▸` exists only remotely and is remotely excluded. Exclusion
+source never changes the presence column.
+
+## Push and pull
+
+Push local changes or replace explicitly selected existing local files from the
+remote side:
+
+```console
+hlsync push
+hlsync push templates
+hlsync push templates -r
+hlsync pull index.html
+hlsync pull templates -r
+```
+
+Push uploads local-only files and replaces changed remote files. Pull replaces
+changed existing local files but never restores a missing local path. A changed
+file is replaced only when the source copy is strictly newer than the
+destination. If the destination is newer or the same age (for example, a file
+edited on the server after your last push), diff shows `?` and push or pull
+stops before changing anything, listing the conflicting paths. Use `--force` to
+overwrite them, or select other paths. Because HLSync copies timestamps on every
+transfer, a later edit on either side makes that side newer; the check assumes
+the local and server clocks roughly agree. Locally
+excluded paths are not uploaded or pulled unless `-I` / `--include-excluded` is
+given, which applies to everything in scope, so review `push -I --dry` first:
+a bare `push -I` would upload `.git/`, `.env`, and anything else your rules keep
+out. Remote-excluded paths are never
+traversed or changed. Push never deletes unless `-p` / `--prune` is given;
+then it deletes selected remote-only paths, including remote copies of locally
+excluded files. Excluded directories on
+either side are retained and never entered; an explicit local inclusion beneath
+an excluded local directory is the only reason to enter that local boundary.
+Push recurses into selected directories by default, including remote-only
+deletion targets when pruning. `-s` /
+`--shallow` processes immediate contents without entering child folders,
+creating them, or deleting them. A selected remote-only directory containing
+an unentered child folder is also retained.
+
+Preview the exact push scope and operation order without changing either side:
+
+```console
+hlsync push --dry
+hlsync push templates --dry
+hlsync push templates -s --dry
+```
+
+Both `diff` and `push --dry` inherit push's recursive default. Dry push
+honors `-s`, `-p`, remote exclusions, and explicit directory scope exactly as a
+real push would. Interrupted-upload recovery is projected and reported but not
+performed. After planning, dry push runs the live transfer executor and skips
+only its mutation calls, preserving preflight, operation order, feedback, and
+counts.
+
+Dry and live push identify each local and remote directory as they scan it. A
+parent is fully classified before HLSync enters eligible children, and excluded
+directories are never entered. Dry-run plans use diff's compact colored `+`,
+`~`, and `-` action markers under an explicit dry-push heading.
+
+Live transfers print the colored `+`, `~`, or `-` action and path after each
+operation succeeds. Failures and skips appear immediately; the final summary
+contains counts without repeating errors. Dry runs use the same feedback to
+show planned operations without performing them.
+When no operation is needed, HLSync prints `Nothing to push` or `Nothing to
+pull` without announcing an empty transfer phase. An empty push also reports
+how many included files are up to date in the selected scope. Push summaries
+report the outcome without a retained-path reminder.
+
+After scanning, push shows the planned upload count and total size. Interactive
+terminals show remote reads as completed/discovered directories (such as 2/12)
+and the current path, without animation. The discovered total grows as eligible
+subdirectories are found. During uploads, interactive
+terminals display a progress bar with bytes sent and files installed. File
+counts advance only after timestamp verification and installation; failures
+remain visible immediately. Redirected output keeps ordinary per-file logs.
+Dry runs show planned totals without simulating byte progress.
+
+Delete selected remote-only paths explicitly with:
+
+```console
+hlsync push --prune
+hlsync push -p 'generated/*.html'
+```
+
+Deletion is limited to the selected scope, runs only after every upload
+succeeds, and is suppressed after any upload failure. Pull never deletes remote
+paths.
+
+### Safe file replacement
+
+Remote ownership and permissions are controlled by the server. HLSync does not
+apply local modes or issue remote chmod/chown commands. Staging files are created
+beside their destinations and retain server-assigned permissions when installed.
+For shared writable app-data trees (for example, `ftps-deploy` and `www-data`),
+configure setgid directories and an appropriate umask or default ACL to create
+`664` files and `2775` directories. Setgid alone does not grant group write;
+replacement files receive the staging file's mode, not the old file's mode.
+
+HLSync never uploads directly over a live destination. A direct FTP upload can
+truncate or expose a partial live file when the connection fails. Instead,
+HLSync:
+
+1. Uploads to a uniquely named staging file beside the destination.
+2. Verifies its size.
+3. Applies the local whole-second UTC timestamp with MFMT (writable MDTM on
+   vsFTPd) and independently
+   reads it back with MDTM.
+4. Moves the existing destination to a temporary backup.
+5. Renames the verified staging file into place, then removes the backup.
+
+This makes each file replacement recoverable, not the complete project
+transactional—FTPS has no project-wide transaction. A later failure does not
+roll back files already installed.
+
+During a push, HLSync recovers its exact reserved artifacts as each selected
+remote directory is read. It does not perform a separate recursive cleanup
+scan. Abandoned upload files are deleted; obsolete backups are deleted when
+their destination exists; a sole backup is restored when its destination is
+missing. This cleanup is independent of remote-only deletion policy and does
+not affect ordinary remote-only files. Concurrent pushes to one profile are not
+supported.
+
+A path-scoped permission failure skips that path or unwritable subtree while
+independent paths continue. The command exits nonzero and suppresses all
+pruning. Type or symlink conflicts, connection failures, and failed replacement
+recovery on selected paths stop the operation when continued state cannot be
+trusted.
+
+## Command behavior
+
+Commands accept the shortest unique prefix. Exact names win. An ambiguous
+prefix prompts for a numbered choice on an interactive terminal and fails with
+the candidate list in noninteractive use.
+
+Use `hlsync help [command]`, `hlsync version`, and `hlsync --legend` for
+built-in reference. `hlsync v`, `hlsync -v`, and `hlsync --version` also print
+the installed version.
+
+## License
+
+HLSync is source-available under the [PolyForm Strict License 1.0.0](LICENSE).
+Use is free of charge for the purposes permitted by that license, including:
+
+- Any noncommercial purpose.
+- The personal uses listed in the license, such as personal study and hobby
+  projects, without any anticipated commercial application.
+- Use by charitable organizations, educational institutions, public research
+  organizations, public safety or health organizations, environmental protection
+  organizations, and government institutions, regardless of funding source or
+  obligations resulting from funding.
+
+This license grants no rights to modify or redistribute HLSync or create works
+based on it. The full license governs; this summary does not grant additional
+permissions.
+
+Commercial use outside those permissions requires a separate paid license.
+Contact [Emrah Diril](mailto:emrah@diril.org) for pricing and a commercial
+agreement before beginning such use.
+
+## Development and maintenance
+
+Install the development environment and run the test suite:
+
+```console
+python -m pip install -e '.[dev]'
+pytest
+```
+
+To try local changes using your installed `hlsync` command, run this from the
+repository root:
+
+```console
+uv tool install --force --reinstall .
+```
+
+This replaces the installed tool with a build of your current checkout. Rerun
+it after making changes. Use `hlsync --legend` for a quick display check, or
+run `hlsync diff` from a mapped project to preview its differences.
+
+The PyPI distribution, installed command, and Python package are all `hlsync`.
+See [`TODO.md`](TODO.md) for the ordered work queue and [`CHANGELOG.md`](CHANGELOG.md) for completed changes.
+[`decisions/`](decisions/) holds substantial architectural choices and their
+rationale. CLI conventions and current usage are documented here; smaller
+changes are explained in commit messages.
+
+The self-contained PHP 8.3 project site is in [`website/`](website/README.md).
+
+### Releasing to PyPI
+
+Releases use `<major>.<work-day>.<increment>` without leading zeroes. Versions
+advance from a starting version using Git history, not the build date:
+
+- [`version.json`](version.json) assigns a starting version to a baseline
+  commit. The empty root commit starts the counter at `1.16.2`; the first
+  source snapshot is `1.16.3`, continuing the version 1 release sequence.
+- Each subsequent date with commits advances the starting work-day number
+  by one, regardless of how many idle days pass.
+- On the baseline day, the increment advances from its starting value for
+  each later commit. On subsequent work days, it starts at `1` and counts
+  commits on that date.
+- Dates use each commit's recorded committer date and timezone. Only the
+  first-parent history of the current checkout counts; a merge counts once.
+  All commits count, including documentation and maintenance changes.
+
+The first source snapshot is `1.16.3`. Another commit on the same date is
+`1.16.4`. The next date with a commit produces `1.17.1`, even after a week
+without changes.
+
+Builds require history back to the baseline and reject backwards-moving commit
+dates. Wheels and source archives preserve the computed version; installed
+commands do not access Git. Reinstall editable checkouts after committing to
+refresh their installed version. To select a new baseline, update `version.json`
+with its starting `version` and an existing `commit` on the same first-parent
+history. To start a new major, use `<major>.0.1` as its starting version.
+Keep the baseline fixed between releases; ordinary commits advance the version.
+
+Use an existing PyPI account with two-factor authentication and an API token.
+Twine uses credentials from `~/.pypirc` or `TWINE_USERNAME`/`TWINE_PASSWORD`,
+and prompts if needed. Do not store the token in the repository.
+
+1. Commit the changes to release. Use a checkout with history back to the
+   baseline in `version.json`. Do not edit the generated `_version.py`.
+2. Update [`CHANGELOG.md`](CHANGELOG.md) when useful. Release notes and dated
+   headings are optional and do not block publishing.
+3. Commit any release-note changes. From that clean checkout, with development
+   dependencies installed, run:
+
+   ```console
+   ./scripts/publish.sh
+   ```
+
+   The script uses the repository's `.venv/bin/python` when available, otherwise
+   `python3`; set `PYTHON` to select another interpreter. It builds through
+   helpers in `scripts/helpers/`, which run identity checks, lint, tests, isolated builds,
+   metadata checks, and a clean wheel installation, then uploads both artifacts.
+   If `dist/hlsync/<version>/` already exists, it reuses those prepared artifacts after
+   checking their metadata. New commits advance the version;
+   existing artifacts are not rebuilt automatically.
+
+   To prepare artifacts without publishing, run `./scripts/publish.sh --prepare`.
+
+4. A Git tag is not required by PyPI. It is strongly recommended for source
+   provenance: tag the release commit as `v<version>`, push that tag, and create
+   a corresponding GitHub Release.
+5. Install the published version in a clean environment and run `hlsync --version`
+   before announcing it.
+
+PyPI does not allow a published version to be replaced. If publication fails
+after accepting either artifact, create another commit (an empty release-retry
+commit is sufficient) and build a new release; do not reuse the failed version.
+Publish from one release history: separate branches can compute the same
+version and are not separate publication streams.