Minn\Ops

A zip unpacked the safe way, for the plugin and theme installer and for the engine's own update alike: every entry stays inside its folder (no absolute path, no "..", no backslash, no NUL), none is a symbolic link, there are no more than 20,000 of them, they unpack to no more than 512 MB, and they all sit in exactly one top folder (macOS's __MACOSX noise aside). Nothing is written until every entry has passed.

Whether per-item auto-updates apply to plugins or themes, as the reference decides it (contracts/rest/minn-admin-v1.md "Auto-updates"): never when file mods are off (DISALLOW_FILE_MODS through file_mod_allowed, context automatic_updater), never when the updater is disabled (AUTOMATIC_UPDATER_DISABLED through automatic_updater_disabled, which a plugin may turn back), and then the type's own filter has the last word. Only plugins and themes can be on.

A changelog read from its repository rather than shipped: a Minn release carries no notes, its own or Minn Admin's, for anyone to find on the sites that run it. The update service reads changelog.md from the repository's default branch on GitHub; the engine asks the service at most once a day and keeps the copy in an option (JSON) with the time it came; sections still marked Unreleased are left out, so a site only reads about releases that exist. A fetch GitHub does not answer keeps the last copy; a 404 (no such file, or a private repository) keeps nothing.

The core the app's update banner and chip speak of, which on Minn is Minn: the running engine's version, a newer release on offer (Ops\Releases, asked of the update service once a day), and installing it (Ops\EngineUpdate). WordPress's own offer (the update_core transient a parked copy may write) is not Minn's to act on and is not shown. dbUpgrade is false: the database is WordPress's, and a Minn release never migrates it.

The System view's facts about this install: the engine, PHP, the database, and the server, with the health checks a site owner acts on. Every number is read live; nothing is cached or fetched from outside.

The Minn update service, https://updates.minn.run: the one place the engine asks about anything it does not have yet, so a site running Minn talks to Minn and never to wordpress.org. The service speaks wordpress.org's own endpoints under /v1/ (plugin and theme update checks, directory search and information, translations) with every address a site would fetch pointed back at itself: packages under /v1/download/, icons, screenshots and emoji under /v1/assets/. It also serves Minn's own releases and changelogs. Every request names the engine and the WordPress version it is compatible with (which judges a plugin's "Requires at least"), never the site's address.

plugins_api() and themes_api() as plugins call them and answer them (probes plugins-api, themes-api), one class for both ($kind 'plugins' or 'themes'): the arguments as an object with the reader's locale and the major.minor version beside them, through <kind>_api_args; then whatever a plugin answers through <kind>_api (a seller's own information, or an error) stands, and only when nobody answers is the directory asked, through Ops\Packages (behind the Minn update service); <kind>_api_result is handed what came back either way. A refusal is <kind>_api_failed in the directory's own words.

Checks a Minn install's files against the release they claim to be, the way `wp core verify-checksums` checks WordPress's against wordpress.org: the update service describes the running version's release, its minn.zip is downloaded from the service alone and must match its published sha256 and carry a signature from a key this engine trusts (EngineUpdate), and then every file of the engine is compared with the archive's, as are the shape files at the webroot with the archive's layout templates. A file that differs, one the archive has and the install lacks, and one the install has beyond the archive are all named. The install record (.install.json) is the site's own and is not compared.

Replaces the running engine with a published release. The release's minn.zip comes from the Minn update service and nowhere else (every redirect hop is judged), must match the sha256 its release records, and must carry an Ed25519 signature made with a key this engine was built to trust (KEYS; the secret half never leaves the release maintainer's machine, so neither GitHub nor the service can stand in a build of their own). It is unpacked beside the engine into a folder of its own, where it is checked again: its bootstrap names the version on offer and bin/minn is there. Then the swap, two renames in the folder the engine lives in: the running engine moves aside, the new one moves in, and the old copy is removed; when the second rename fails the first is undone. The webroot's shape files are laid again from the new engine (ShapeFiles::refresh): one still as the old engine wrote it, a stock empty placeholder above all, is replaced, and one the site changed is left alone. The legacy install record (.install.json, from installs that kept it inside the engine) comes along. One update runs at a time. A development checkout (a symbolic link, or a folder under git) is refused: git owns those. The site keeps answering throughout.

What is installed, as the System view lists it: every extension and WordPress plugin with whether it runs, the mu-plugins, the themes with their parents, and the active theme's label.

The log files the System view can read and clear: the debug log the engine's failure handler writes, and PHP's own error log when it is a separate file inside the site. Anything outside the site is named but never read; it may be another tenant's.

Putting plugins, themes and extensions on disk. Plugins and themes come from the directory (wordpress.org's, asked through the Minn update service, Ops\Directory) or an uploaded zip, and are installed through WordPress's upgraders (UpgraderRun), so plugins hear every upgrader hook; a Minn extension (a folder with a minn.json) is placed by the engine. Every archive passes Archive's checks first: exactly one top-level folder that is a plain name (never "." or ".."), no absolute or dotted paths, no symbolic links, bounded entry count and size. Removal proves the folder is a direct child of its kind's directory before anything is deleted.

One published Minn release as the update service describes it (and as the minn_release option keeps it, the same shape): the version, its notes and page, when it went out, and its minn.zip with that file's sha256 and its Ed25519 signature. Anything else is not a release Minn offers: a version that is not major.minor.patch, a package anywhere but Minn's own downloads, a missing checksum, or a missing signature.

Whether a newer Minn is out, asked of the Minn update service at most once a day: its latest installable release (published on GitHub, read by the service), kept in the minn_release option (JSON) with the time it was asked. A check the service does not answer (offline, GitHub rate limiting it) keeps the last answer and waits a day like any other; no installable release (a 404) offers nothing. This is Minn asking Minn, never wordpress.org, and never GitHub directly.

The files an install lays at the webroot for tooling to find: the shape files from layout/ (index.php, wp-settings.php, version.php and the rest) and one file for each of the reference's wp-includes and wp-admin/includes files, an empty placeholder or, where layout/ ships one, the engine's loader. An engine update lays them again from the new engine: a file still as the replaced engine wrote it is replaced, a missing one is written, and one the site changed is left alone.

An archive unpacked as unzip_file() unpacks it (probe unzip-file): into the destination through the filesystem the site set up, every folder made first (the destination and its missing parents included), resource-fork entries (__MACOSX/) and entries whose names climb out or are absolute left out; refused when the disk cannot take twice the unpacked size and a little more. pre_unzip_file may answer first, and unzip_file is handed the result, each with the folders to make and the space needed. An archive the reader cannot open is refused in the words of the library the reference falls back to.

Update offers for the site's plugins and themes from the directory, asked through the Minn update service (Ops\Directory), which answers with wordpress.org's own offers and serves their packages: the update-check endpoints asked with the installed headers (each plugin's Name, Version and Update URI, so a plugin that updates from elsewhere is never offered the directory's plugin of the same folder name), the answer kept in the minn_updates option (JSON) for twelve hours, and the offers applied by downloading the release archive through the one package unpacker. A plugin or theme the directory does not know keeps its folder untouched and is never offered anything. The per-item auto-update lists are the site's own auto_update_plugins and auto_update_themes options, in the shape the app already reads.

The directory is not the only source. A plugin that hosts itself answers for its own version through the update transient's filter, which is where WordPress reads it too, so Runtime\PluginUpdates asks the runtime the same question and its answer is merged in. Applying such an offer goes through the publisher: a package outside the directory is unpacked only when `upgrader_pre_download` hands back a copy it verified.

The engine's own installs and updates, run through the reference's upgraders (Plugin_Upgrader, Theme_Upgrader) so plugins hear every hook a WordPress install or update tells them: the REST plugin route, Minn Admin's install, upload and update routes, the CLI verbs and the automatic updates all come here. The Minn update service's packages are fetched over the engine's own client (Packages::fetch: https, the service's host, a size cap) and handed to the upgrader as a file through upgrader_pre_download, so where Minn gets code is never the plugin-filterable HTTP API's to change. A package from anywhere else is installed only when its publisher answered upgrader_pre_download with a copy it checked (or refused it): nobody's word, no install. A package from the service passes Archive's checks before the upgrader unpacks it; a local file (an upload, checked by Packages) is the upgrader's to read. The upgrader's refusals come back as the engine's REST errors, in the words its routes already use.