Metadata-Version: 2.4
Name: automas-maafw-project-update
Version: 0.2.3
Summary: Standalone MaaFW project update plugin for AUTO-MAS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: aiofiles>=23
Requires-Dist: automas-maafw-interface>=0.2.0
Requires-Dist: httpx>=0.27
Requires-Dist: packaging>=23
Requires-Dist: pydantic>=2

# automas-maafw-project-update

Standalone MaaFW project update service and AUTO-MAS plugin.

It provides `maafw.project_update.v1` and supports `mirrorchyan` and
`github_release` providers without depending on MaaFW runner or agent runtime.

With no explicit provider, MirrorChyan remains the version-metadata authority
when the ProjectInterface declares a RID. A CDK-less discovery can report a
newer version, but it never exposes an installable candidate; the caller must
provide a project or host CDK. Automatic checks do not cross-fallback to
GitHub. Explicit providers never cross-fallback, and GitHub source archives or
ambiguous asset sets are not treated as installable releases.

`download_package()` downloads an installable candidate into a caller-owned
managed directory without changing an existing project tree. It accepts only
HTTPS URLs, validates every redirect, enforces a streamed size limit, checks
ZIP/SHA256 integrity and publishes the complete archive atomically. Managed
downloads use unique temporary files and a content-addressed final name, so
concurrent scripts cannot delete each other's in-progress archive. Project
Store consumers can then import the returned local path.

`release_download_package()` releases that caller-owned staging archive after
the immutable import is durable. It accepts only the exact content-addressed
package DTO returned by `download_package()`, re-verifies SHA256, rejects path
escapes, extra nesting, symlinks and Windows reparse points, and unlinks only
the regular archive plus its now-empty direct archive-key directory. Missing
packages are idempotently treated as already released; no recursive cache
deletion is exposed. Failed or cancelled downloads apply the same narrow
cleanup to their UUID work files and empty archive-key directory.

Downloads share one 300-second wall-clock deadline across retries. The optional
best-effort progress callback reports real streamed bytes (when available),
validation, extraction, switching and terminal states without allowing a UI
callback failure to affect the update transaction.

`discover_update()` distinguishes a newer version from an installable package.
It returns a discovery with `candidate=None` when the provider supplies version
metadata without a download URL. The legacy `check_update()` method returns only
an actionable candidate and raises a diagnostic error for a non-installable
discovery, so callers cannot accidentally present it as ready to install.

Archive validation (ZIP inspection and SHA256), publication, extraction,
copy/rollback and cleanup run in worker threads. The async service therefore
keeps the AUTO-MAS event loop responsive while applying large project updates.
