afterpresets 0.1.0 → 0.3.0

package/README.md

@@ -1,20 +1,22 @@
 # AfterPresets CLI
 
-Make Adobe After Effects extensions with an AI agent, and sell them on
+Make Adobe After Effects and Premiere Pro extensions with an AI agent, and sell them on
 [AfterPresets](https://afterpresets.com) with licensing, signed auto-updates
 and checkout handled.
 
 You do not need to write code. Open an empty folder in your agent (the Code
 tab of the Claude desktop app, Claude Code, Codex, Cursor...) and follow the
-**[Quickstart](https://docs.afterpresets.com/get-started/quickstart/)**.
+**[Quickstart](https://docs.afterpresets.com/extensions/quickstart/)**.
+Building a native After Effects effect plugin (C++) instead? See the
+**[plugin Quickstart](https://docs.afterpresets.com/plugins/quickstart/)**.
 
 ```sh
 npx afterpresets login
 npx afterpresets init my-extension
 ```
 
-Inside a project, `ap dev` puts the extension into After Effects and reloads
-it on every save, `ap push` publishes a release, and `ap upgrade` updates
+Inside a project, `ap dev` puts the extension into After Effects or Premiere
+Pro and reloads it on every save, `ap push` publishes a release, and `ap upgrade` updates
 this package. Every project includes `AGENTS.md` and an MCP server
 (`ap mcp`) so your agent can see, click and test the live panel.
 

package/native-runtime/CMakeLists.txt

@@ -0,0 +1,82 @@
+cmake_minimum_required(VERSION 3.20)
+project(ap_native VERSION 0.1.0 LANGUAGES C CXX)
+
+# Plugins add this folder with add_subdirectory() and link ap_native statically.
+# Tests: tests/run.sh (configures this file with -DAP_NATIVE_TESTS=ON).
+option(AP_NATIVE_TESTS "Build the host-free unit tests" OFF)
+
+if(APPLE)
+  enable_language(OBJCXX)
+  if(NOT CMAKE_OSX_DEPLOYMENT_TARGET)
+    set(CMAKE_OSX_DEPLOYMENT_TARGET "12.0" CACHE STRING "" FORCE)
+  endif()
+endif()
+
+set(AP_NATIVE_SOURCES
+  src/apply.cpp
+  src/crypto.cpp
+  src/dialog.cpp
+  src/engine.cpp
+  src/fsutil.cpp
+  src/json.cpp
+  src/platform_common.cpp
+  src/runtime.cpp
+  src/util.cpp
+  src/zip.cpp
+  third_party/monocypher/monocypher.c
+  third_party/monocypher/monocypher-ed25519.c
+  third_party/tinf/tinflate.c
+  third_party/tinf/crc32.c
+)
+if(APPLE)
+  list(APPEND AP_NATIVE_SOURCES src/platform_mac.mm)
+elseif(WIN32)
+  list(APPEND AP_NATIVE_SOURCES src/platform_win.cpp)
+else()
+  message(FATAL_ERROR "ap_native supports macOS and Windows only")
+endif()
+
+add_library(ap_native STATIC ${AP_NATIVE_SOURCES})
+target_include_directories(ap_native
+  PUBLIC include
+  PRIVATE src third_party/monocypher third_party/tinf)
+target_compile_features(ap_native PUBLIC cxx_std_17)
+# Hidden symbols: two plugins carrying different copies never clash, and the
+# shipped binary does not advertise the license functions by name.
+set_target_properties(ap_native PROPERTIES
+  CXX_VISIBILITY_PRESET hidden
+  C_VISIBILITY_PRESET hidden
+  OBJCXX_VISIBILITY_PRESET hidden
+  VISIBILITY_INLINES_HIDDEN ON
+  POSITION_INDEPENDENT_CODE ON)
+
+# Warnings for our own sources only (not the vendored C files).
+set_source_files_properties(
+  src/apply.cpp src/crypto.cpp src/dialog.cpp src/engine.cpp src/fsutil.cpp src/json.cpp
+  src/platform_common.cpp src/runtime.cpp src/util.cpp src/zip.cpp src/platform_win.cpp
+  PROPERTIES COMPILE_OPTIONS "-Wall;-Wextra;-Wno-unused-parameter")
+
+if(APPLE)
+  set_source_files_properties(src/platform_mac.mm PROPERTIES COMPILE_FLAGS "-fobjc-arc -Wall -Wextra -Wno-unused-parameter")
+  target_link_libraries(ap_native PUBLIC "-framework Foundation" "-framework AppKit" "-framework IOKit")
+elseif(WIN32)
+  target_compile_definitions(ap_native PRIVATE UNICODE _UNICODE WIN32_LEAN_AND_MEAN)
+  target_link_libraries(ap_native PUBLIC winhttp iphlpapi bcrypt shell32 ole32 advapi32 user32)
+endif()
+
+if(AP_NATIVE_TESTS)
+  add_executable(ap_native_tests
+    tests/test_main.cpp
+    tests/test_crypto.cpp
+    tests/test_json_zip.cpp
+    tests/test_license.cpp
+    tests/test_updates.cpp
+    tests/test_runtime.cpp
+    tests/test_server.cpp
+    tests/test_dialog.cpp)
+  target_include_directories(ap_native_tests PRIVATE src tests third_party/monocypher third_party/tinf)
+  target_link_libraries(ap_native_tests PRIVATE ap_native)
+  add_executable(ap_native_probe tests/probe.cpp)
+  target_include_directories(ap_native_probe PRIVATE src)
+  target_link_libraries(ap_native_probe PRIVATE ap_native)
+endif()

package/native-runtime/README.md

@@ -0,0 +1,40 @@
+# ap_native
+
+The AfterPresets runtime for native (C++) After Effects plugins: licensing
+(browser sign-in, signed license proofs, offline grace) and signed self-updates.
+It is the C++ counterpart of `@afterpresets/runtime` and talks to the same API.
+AfterPresets maintains it; developers do not edit it. The CLI copies the files
+in `vendor-files.json` into each native project.
+
+- Design, threading, security and the integration snippet:
+  [`docs/native-runtime-design.md`](../../docs/native-runtime-design.md)
+- C API: [`include/ap_native.h`](include/ap_native.h)
+- Third-party code: [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)
+
+## Use from a plugin's CMake
+
+```cmake
+add_subdirectory(vendor/ap_native)
+target_link_libraries(MyEffect PRIVATE ap_native)
+```
+
+## Tests (maintainers)
+
+```sh
+packages/native-runtime/tests/run.sh               # 63 C++ tests + Node parity/integration tests
+AP_SANITIZE=1 packages/native-runtime/tests/run.sh # AddressSanitizer + UBSan
+AP_TSAN=1 packages/native-runtime/tests/run.sh     # ThreadSanitizer
+```
+
+Requirements: macOS with the Command Line Tools, `brew install cmake ninja`,
+Node 18+, and `pnpm install` at the repo root. The server-signature tests run
+the API's signing code through `apps/api`'s `tsx`.
+
+Windows cross-build check (needs `brew install zig`; links, but cannot run without Windows):
+
+```sh
+cmake -S packages/native-runtime -B packages/native-runtime/build/win -G Ninja \
+  -DAP_NATIVE_TESTS=ON \
+  -DCMAKE_TOOLCHAIN_FILE=docs/native-research/spike-hello/cmake/zig-x86_64-windows.cmake
+ninja -C packages/native-runtime/build/win
+```

package/native-runtime/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,14 @@
+# Third-party code in ap_native
+
+Both are vendored unmodified. Their licences allow use in closed-source,
+commercial plugins. Keep this file, and each folder's licence file, with every
+copy of the library.
+
+| Folder | Project | Version | Licence | Used for |
+|---|---|---|---|---|
+| `third_party/monocypher/` | [Monocypher](https://monocypher.org) (`monocypher.c/.h`, `optional/monocypher-ed25519.c/.h`) | 4.0.2 (matches the GitHub tag apart from the version comment) | CC0-1.0 or BSD-2-Clause, your choice (`LICENCE.md`) | Ed25519 signature verification (SHA-512 inside) |
+| `third_party/tinf/` | [tinf](https://github.com/jibsen/tinf) by Jørgen Ibsen (`tinflate.c`, `crc32.c`, `tinf.h`) | commit 57ffa1f (2022-02-12) | zlib (`LICENSE`) | Inflate (ZIP deflate entries) and CRC-32 |
+
+The CC0 option means Monocypher needs no attribution. tinf's zlib licence asks
+that its notice stay in the source distribution; attribution in shipped
+binaries is appreciated but not required.

package/native-runtime/include/ap_native.h

@@ -0,0 +1,223 @@
+/* ap_native - AfterPresets runtime for native (C++) After Effects plugins.
+ *
+ * Licensing (browser sign-in, Ed25519-signed license proofs, offline grace)
+ * and signed updates (check, download, verify, stage, apply on next launch)
+ * against the same API as the JS runtime (@afterpresets/runtime):
+ *   POST {apiBase}/v1/api/extensions/{bundleId}/license/sign-in | sign-in/poll
+ *        | validate | sign-out, and /updates/check.
+ * Design: docs/native-runtime-design.md.
+ *
+ * Threading contract
+ *   - ap_init / ap_shutdown / ap_apply_staged_update: main (UI) thread, from
+ *     PF_Cmd_GLOBAL_SETUP / PF_Cmd_GLOBAL_SETDOWN.
+ *   - ap_is_unlocked, ap_status_get, ap_generation: any thread, including
+ *     render threads (MFR). Lock-free atomic reads; never block, never allocate.
+ *   - Everything else: any non-render thread (normally the UI thread).
+ *     Commands only enqueue work; all network I/O happens on one background
+ *     worker thread owned by the runtime. No call in this header ever does
+ *     network I/O on the calling thread.
+ *
+ * The plugin links this library statically. Build it with hidden symbol
+ * visibility (the CMake target does) so two plugins carrying different copies
+ * never clash. No secrets live in this library: the public key verifies,
+ * it cannot sign. */
+#ifndef AP_NATIVE_H
+#define AP_NATIVE_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define AP_NATIVE_VERSION "0.1.0"
+
+typedef struct ap_runtime ap_runtime;
+
+/* Same statuses as the JS runtime's AP.license.state.status. */
+typedef enum ap_status {
+    AP_STATUS_DISABLED = 0,     /* licensing off: always unlocked */
+    AP_STATUS_SIGNED_OUT,
+    AP_STATUS_SIGNING_IN,       /* browser sign-in in progress (state.sign_in_url) */
+    AP_STATUS_CHECKING,
+    AP_STATUS_ACTIVE,
+    AP_STATUS_NOT_OWNED,
+    AP_STATUS_REFUNDED,
+    AP_STATUS_OFFLINE_GRACE,    /* unlocked; state.grace_days_left */
+    AP_STATUS_OFFLINE_EXPIRED,
+    AP_STATUS_ERROR
+} ap_status;
+
+typedef enum ap_update_mode {
+    AP_UPDATES_OFF = 0,         /* never checks */
+    AP_UPDATES_MANUAL,          /* only when ap_check_for_update is called */
+    AP_UPDATES_NOTIFY,          /* checks automatically; downloads on ap_download_update */
+    AP_UPDATES_BACKGROUND       /* checks, downloads, verifies and stages automatically (default) */
+} ap_update_mode;
+
+typedef enum ap_update_status {
+    AP_UPDATE_IDLE = 0,
+    AP_UPDATE_CHECKING,
+    AP_UPDATE_UP_TO_DATE,
+    AP_UPDATE_AVAILABLE,        /* found, not downloaded (notify/manual mode) */
+    AP_UPDATE_DOWNLOADING,
+    AP_UPDATE_STAGED,           /* verified and staged; applied by ap_apply_staged_update */
+    AP_UPDATE_APPLIED,          /* files replaced; the new version runs after After Effects restarts */
+    AP_UPDATE_ERROR
+} ap_update_status;
+
+typedef struct ap_config {
+    const char *bundle_id;          /* com.afterpresets.<seller>.<slug> (required) */
+    const char *version;            /* semver of this build (required) */
+    const char *api_base;           /* https://api.afterpresets.com (http only for 127.0.0.1/localhost) */
+    const char *public_key;         /* Ed25519 public key: base64 SPKI DER, PEM, base64 of a PEM, or base64 of the raw 32 bytes */
+    const char *product_url;        /* listing page (buy / download again) */
+    const char *manage_devices_url; /* where buyers free a computer slot */
+    int license_enabled;            /* 0: status DISABLED, no license network calls */
+    int offline_grace_days;         /* 0-30, measured from the last signed validation */
+    int check_in_background;        /* nonzero: a signed but stale check unlocks at launch while the API is asked */
+    ap_update_mode update_mode;
+    const char *channel;            /* "production" (default) or "test"; only validated by the API */
+    int dev;                        /* dev build: updates are checked but never staged or applied */
+    int apply_when_staged;          /* default 1: replace the installed plugin right after a verified download, so the
+                                       effect can show "Update installed: restart After Effects" in this session.
+                                       0: only ap_apply_staged_update replaces it (GLOBAL_SETDOWN / next GLOBAL_SETUP). */
+    const char *install_dir;        /* optional: the installed <bundleId> folder. NULL: found from the binary's path */
+    const char *data_root;          /* optional (tests): replaces ~/Library/Application Support or %LOCALAPPDATA%; logs then go to <data_root>/AfterPresets/Logs */
+    const char *build_id;           /* optional; written to the log at ap_init so tools can prove which build is loaded */
+    void (*on_change)(void *user);  /* optional; called on the WORKER thread after any state change. Only set a flag. */
+    void (*log)(void *user, int level, const char *message); /* optional; 0 debug 1 info 2 warn 3 error. Never receives tokens or signed URLs. */
+    void *user;
+} ap_config;
+
+#define AP_TEXT_MAX 512
+
+typedef struct ap_state {
+    ap_status status;
+    int unlocked;                   /* active, offline_grace or disabled */
+    int grace_days_left;
+    uint64_t generation;            /* increments on every license or update state change */
+    char message[AP_TEXT_MAX];      /* default English message for the status (UTF-8) */
+    char sign_in_url[AP_TEXT_MAX];  /* while SIGNING_IN: the page to reopen */
+    char username[128];             /* signed-in AfterPresets username, if known */
+} ap_state;
+
+typedef struct ap_update_state {
+    ap_update_status status;
+    int restart_required;           /* 1 after a successful apply */
+    int needs_manual_install;       /* staged but the install folder is not writable */
+    char version[64];               /* target version */
+    char direction[16];             /* "upgrade" | "downgrade" */
+    char change_log[2048];          /* target release's changelog, truncated */
+    char error_code[48];            /* e.g. network, bad_signature, bad_checksum, bad_zip, not_writable */
+    char error_message[AP_TEXT_MAX];
+} ap_update_state;
+
+typedef enum ap_apply_result {
+    AP_APPLY_NOTHING = 0,           /* nothing staged */
+    AP_APPLY_OK = 1,                /* replaced; restart After Effects to run it */
+    AP_APPLY_NOT_INSTALLED = -1,    /* the binary is not inside an installed <bundleId> folder (dev build, symlink) */
+    AP_APPLY_NOT_WRITABLE = -2,     /* install folder not writable by this user: buyer must reinstall */
+    AP_APPLY_FAILED = -3,           /* error while replacing; the previous version was restored */
+    AP_APPLY_DEV = -4               /* dev build */
+} ap_apply_result;
+
+/* Fills defaults: licensing on, 0 grace days, check_in_background on,
+ * AP_UPDATES_BACKGROUND, apply_when_staged on, channel "production", everything else NULL/0. */
+void ap_config_defaults(ap_config *config);
+
+/* Creates the runtime: reads the license cache from disk and verifies its
+ * proof synchronously (no network; a few ms), then starts the worker thread,
+ * which validates online when needed and checks for updates. Returns NULL for
+ * an invalid config (bad bundle id, version or api_base). Call once per
+ * process (PF_Cmd_GLOBAL_SETUP); keep the pointer in global data. */
+ap_runtime *ap_init(const ap_config *config);
+
+/* Stops the worker (cancels in-flight requests; waits at most ~3 s) and frees
+ * the runtime. PF_Cmd_GLOBAL_SETDOWN. NULL is ignored. */
+void ap_shutdown(ap_runtime *rt);
+
+/* Render-thread safe. 1 when the effect may render without the watermark. */
+int ap_is_unlocked(const ap_runtime *rt);
+ap_status ap_status_get(const ap_runtime *rt);
+/* Changes whenever anything in ap_state or ap_update_state changes. Cheap:
+ * compare it in PF_Cmd_UPDATE_PARAMS_UI and refresh the UI when it moved. */
+uint64_t ap_generation(const ap_runtime *rt);
+
+void ap_get_state(ap_runtime *rt, ap_state *out);
+void ap_get_update_state(ap_runtime *rt, ap_update_state *out);
+
+/* Starts a browser sign-in: asks the API for a sign-in request, opens the
+ * verification page in the default browser and polls until the buyer approves
+ * it (status SIGNING_IN, then ACTIVE). Returns 0 when queued, -1 when
+ * licensing is off. Safe to call repeatedly (one sign-in at a time). */
+int ap_begin_sign_in(ap_runtime *rt);
+void ap_cancel_sign_in(ap_runtime *rt);
+/* Reopens the pending sign-in page (e.g. the buyer closed the tab). */
+void ap_open_sign_in_page(ap_runtime *rt);
+/* Re-validates the stored license (after NOT_OWNED, OFFLINE_EXPIRED, ERROR). */
+void ap_retry(ap_runtime *rt);
+/* Deletes the local license and frees this computer's slot (best effort when offline). */
+void ap_sign_out(ap_runtime *rt);
+
+/* Checks now (any mode except OFF). In BACKGROUND mode a found update is downloaded and staged. */
+void ap_check_for_update(ap_runtime *rt);
+/* Downloads, verifies and stages the update found by the last check (NOTIFY/MANUAL modes). */
+void ap_download_update(ap_runtime *rt);
+/* One line for the effect's UI (UTF-8), or "" when there is nothing to say:
+ *   "Update installed: restart After Effects to use v1.2.0"
+ *   "Update v1.2.0 downloaded: it installs when After Effects quits"
+ *   "Update v1.2.0 is ready, but this plugin's folder is not writable: download it again from AfterPresets"
+ *   "Update v1.2.0 available"
+ * Copies into buf (NUL-terminated, never cut inside a UTF-8 sequence); returns the full length. */
+size_t ap_update_notice(ap_runtime *rt, char *buf, size_t size);
+/* The update's changelog (up to 8000 bytes, UTF-8) for the Options dialog; returns the full length. */
+size_t ap_update_changelog(ap_runtime *rt, char *buf, size_t size);
+
+typedef enum ap_dialog_action {
+    AP_DIALOG_NONE = -1,            /* could not be shown (not the main thread) */
+    AP_DIALOG_CLOSE = 0,
+    AP_DIALOG_SIGN_IN,              /* browser sign-in started */
+    AP_DIALOG_OPEN_SIGN_IN_PAGE,
+    AP_DIALOG_CANCEL_SIGN_IN,
+    AP_DIALOG_SIGN_OUT,
+    AP_DIALOG_RETRY,
+    AP_DIALOG_OPEN_PRODUCT,         /* product_url opened (buy) */
+    AP_DIALOG_MANAGE_DEVICES        /* manage_devices_url opened */
+} ap_dialog_action;
+
+/* The effect's Options dialog (PF_OutFlag_I_DO_DIALOG -> PF_Cmd_DO_DIALOG).
+ * Shows the license status, the signed-in account, the update notice and
+ * changelog, with buttons for the current state (Sign in / Buy / Open
+ * sign-in page / Sign out / Try again / Manage devices), performs the chosen
+ * action (network work goes to the worker) and returns it. Modal; main thread
+ * only. title: the effect's name (UTF-8). */
+ap_dialog_action ap_options_dialog(ap_runtime *rt, const char *title);
+
+/* Replaces the installed files with the staged, verified update. Filesystem
+ * only, synchronous; call from PF_Cmd_GLOBAL_SETDOWN (After Effects is
+ * quitting) and/or PF_Cmd_GLOBAL_SETUP. The running code keeps running; the new
+ * version loads at the next launch. Never call from a render thread. */
+ap_apply_result ap_apply_staged_update(ap_runtime *rt);
+
+/* Appends a line to this plugin's log (macOS ~/Library/Logs/AfterPresets/<bundleId>.log,
+ * Windows %LOCALAPPDATA%\AfterPresets\Logs\<bundleId>.log; 1 MB, one rotated
+ * file). Any thread, including render threads: never blocks, never does I/O on
+ * the caller (the worker writes the file); a line is dropped if the queue is
+ * busy or full. Never log tokens or URLs; tokens and query strings are scrubbed anyway. */
+void ap_log(ap_runtime *rt, int level, const char *message);
+/* Copies the log file path into buf (NUL-terminated); returns its full length. */
+size_t ap_log_path(ap_runtime *rt, char *buf, size_t size);
+
+/* Waits until the worker has no queued or running work (tests, tools). 0 on idle, -1 on timeout. */
+int ap_wait_idle(ap_runtime *rt, int timeout_ms);
+
+const char *ap_status_name(ap_status status);       /* "active", "signed_out", ... (JS names) */
+const char *ap_update_status_name(ap_update_status status);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* AP_NATIVE_H */

package/native-runtime/src/apply.cpp

@@ -0,0 +1,199 @@
+// Applies a staged, verified update to the installed <bundleId> folder.
+//
+// Install layout (docs/native-runtime-design.md, "Install layout"):
+//   .../MediaCore/AfterPresets/<bundleId>/<Name>.plugin   (macOS)
+//   ...\MediaCore\AfterPresets\<bundleId>\<Name>.aex     (Windows)
+// The buyer's install script creates MediaCore/AfterPresets once with admin and
+// gives it to the user, so updates never need admin. Only this OS's plugin is
+// replaced; other files in <bundleId>/ are left alone, and any other plugin of
+// this OS there (an old name after a rename) is removed so AE never loads two.
+// macOS swaps the bundle atomically (renamex_np RENAME_SWAP); elsewhere the old
+// plugin is renamed away first (Windows allows renaming a loaded DLL, not
+// deleting or overwriting it). Work copies are named "<Name>.plugin.ap-new" /
+// "<Name>.aex.ap-old" inside "(ap-update)" / "(ap-old)": AE only loads
+// *.plugin / *.aex, so an interrupted apply never leaves a second loadable
+// copy. The running process keeps its already-loaded code; the new version
+// loads at the next launch.
+#include <cctype>
+#include <set>
+
+#include "engine.hpp"
+#include "fsutil.hpp"
+#include "util.hpp"
+
+namespace apn {
+
+namespace {
+
+const char *const WORK_DIR = "(ap-update)";
+const char *const OLD_DIR = "(ap-old)";
+
+struct Lock {
+    std::string path;
+    bool held = false;
+    Lock(const std::string &p, int64_t now) : path(p) {
+        for (int attempt = 0; attempt < 2 && !held; attempt++) {
+            auto r = fsu::write_exclusive(path, std::to_string(now));
+            if (r == fsu::Excl::Ok) { held = true; break; }
+            if (r == fsu::Excl::Error) break;
+            int64_t age = fsu::age_ms(path, now);
+            if (age >= 0 && age <= Engine::LOCK_STALE_MS) break;
+            fsu::remove_file(path);
+        }
+    }
+    ~Lock() {
+        if (held) fsu::remove_file(path);
+    }
+};
+
+}  // namespace
+
+std::string find_install_dir(const std::string &binary_path, const std::string &bundle_id) {
+    if (binary_path.empty() || bundle_id.empty()) return "";
+    std::string dir = fsu::parent(binary_path);
+    for (int depth = 0; depth < 8 && !dir.empty(); depth++) {
+        if (fsu::basename(dir) == bundle_id) return dir;
+        std::string up = fsu::parent(dir);
+        if (up == dir) break;
+        dir = up;
+    }
+    return "";
+}
+
+void cleanup_install_leftovers(const Settings &s) {
+    if (s.install_dir.empty() || fsu::basename(s.install_dir) != s.bundle_id) return;
+    fsu::remove_all(fsu::join(s.install_dir, OLD_DIR));
+    fsu::remove_all(fsu::join(s.install_dir, WORK_DIR));
+}
+
+namespace {
+
+bool is_os_plugin(const std::string &name, const std::string &os) {
+    std::string lower = name;
+    for (auto &c : lower) c = (char)std::tolower((unsigned char)c);
+    const std::string ext = os == "windows" ? ".aex" : ".plugin";
+    return lower.size() > ext.size() && lower.compare(lower.size() - ext.size(), ext.size(), ext) == 0;
+}
+
+}  // namespace
+
+ApplyResult apply_staged_update(const Settings &s, const Env &env, std::string *version, std::string *error) {
+    auto say = [&](const std::string &m) {
+        if (error) *error = m;
+        if (env.log && !m.empty()) env.log(2, m);
+    };
+    Paths paths = Paths::make(env.data_root, s.bundle_id);
+    auto meta_text = fsu::read(paths.staged_meta, 1 << 20);
+    auto meta = meta_text ? Json::parse(*meta_text) : std::nullopt;
+    if (!meta || !meta->is_object() || !fsu::is_dir(paths.staged)) return ApplyResult::Nothing;
+    std::string staged_version = (*meta)["version"].str();
+    if (version) *version = staged_version;
+    if (s.dev) return ApplyResult::Dev;
+    if (staged_version.empty() || staged_version == s.version) {
+        fsu::remove_all(paths.staged);
+        fsu::remove_file(paths.staged_meta);
+        return ApplyResult::Nothing;
+    }
+    std::vector<std::string> staged_entries = fsu::list(paths.staged);
+    if (staged_entries.size() != 1 || !is_os_plugin(staged_entries[0], s.os)) {
+        fsu::remove_all(paths.staged);
+        fsu::remove_file(paths.staged_meta);
+        say("The staged update is incomplete; it was discarded.");
+        return ApplyResult::Failed;
+    }
+    const std::string plugin = staged_entries[0];
+    // Only ever touch a folder named exactly <bundleId>: a wrong install_dir
+    // must never make us rename things in the shared MediaCore folder.
+    const std::string &install = s.install_dir;
+    if (install.empty() || fsu::basename(install) != s.bundle_id || !fsu::is_dir(install)) {
+        say("The plugin is not inside an installed " + s.bundle_id + " folder; the update was not applied.");
+        return ApplyResult::NotInstalled;
+    }
+    if (!fsu::dir_writable(install)) {
+        say("The plugin folder is not writable; reinstall the plugin to update it.");
+        return ApplyResult::NotWritable;
+    }
+    Lock lock(paths.lock, env.now_ms());
+    if (!lock.held) {
+        say("Another process is installing this update.");
+        return ApplyResult::Failed;
+    }
+
+    std::string work = fsu::join(install, WORK_DIR);
+    std::string old = fsu::join(install, OLD_DIR);
+    fsu::remove_all(work);
+    fsu::remove_all(old);  // may fail on Windows while an old DLL is still loaded; names below are unique
+    std::string fresh = fsu::join(work, plugin + ".ap-new");
+    std::string copy_error;
+    bool copied = fsu::is_dir(fsu::join(paths.staged, plugin))
+                      ? fsu::copy_tree(fsu::join(paths.staged, plugin), fresh, &copy_error)
+                      : (fsu::mkdirs(work) && [&] {
+                            auto bytes = fsu::read(fsu::join(paths.staged, plugin), 2ULL * 1024 * 1024 * 1024);
+                            return bytes && fsu::write_file(fresh, *bytes, true);
+                        }());
+    if (!copied) {
+        fsu::remove_all(work);
+        say("The update could not be copied: " + copy_error);
+        return ApplyResult::Failed;
+    }
+    // The staged files were verified; a quarantine flag must not block loading.
+    if (env.strip_quarantine) env.strip_quarantine(fresh);
+    if (!fsu::mkdirs(old)) {
+        fsu::remove_all(work);
+        say("The update could not be prepared.");
+        return ApplyResult::Failed;
+    }
+    std::string stamp = env.random_hex ? env.random_hex(4) : std::to_string(env.now_ms());
+    auto park_path = [&](const std::string &name) { return fsu::join(old, name + ".ap-old-" + stamp); };
+
+    std::string target = fsu::join(install, plugin);
+    std::string parked;  // where the previous version went ("" if there was none)
+    bool failed = false;
+    if (!fsu::exists(target)) {
+        failed = !fsu::rename(fresh, target);
+    } else if (fsu::swap(fresh, target)) {
+        parked = park_path(plugin);
+        if (!fsu::rename(fresh, parked)) parked = fresh;  // fresh now holds the previous version
+    } else {
+        parked = park_path(plugin);
+        if (!fsu::rename(target, parked)) {
+            parked.clear();
+            failed = true;
+        } else if (!fsu::rename(fresh, target)) {
+            fsu::rename(parked, target);
+            parked.clear();
+            failed = true;
+        }
+    }
+    // Other plugins of this OS in the folder (the product's previous name): park them.
+    std::vector<std::pair<std::string, std::string>> removed;
+    if (!failed) {
+        for (const auto &name : fsu::list(install)) {
+            if (name == plugin || name == WORK_DIR || name == OLD_DIR || !is_os_plugin(name, s.os)) continue;
+            std::string to = park_path(name);
+            if (!fsu::rename(fsu::join(install, name), to)) { failed = true; break; }
+            removed.emplace_back(name, to);
+        }
+        if (failed) {
+            // Roll everything back, including the plugin itself.
+            for (auto it = removed.rbegin(); it != removed.rend(); ++it) fsu::rename(it->second, fsu::join(install, it->first));
+            fsu::rename(target, fsu::join(work, plugin + ".rollback"));
+            if (!parked.empty()) fsu::rename(parked, target);
+        }
+    }
+    if (failed) {
+        fsu::remove_all(work);
+        fsu::remove_all(old);
+        say("The update could not be installed; the previous version was restored.");
+        return ApplyResult::Failed;
+    }
+    fsu::remove_all(work);
+    fsu::remove_all(old);  // Windows: a renamed loaded .aex stays until the next launch's cleanup
+    fsu::remove_all(paths.staged);
+    fsu::remove_file(paths.staged_meta);
+    if (error) error->clear();
+    if (env.log) env.log(1, "Update " + staged_version + " installed; it loads the next time After Effects starts.");
+    return ApplyResult::Ok;
+}
+
+}  // namespace apn