feat(compile,runtime): let a compiled app carry its own update check

Perry's CLI has checked for updates for a long time; an app it builds could
not, so shipping one meant hand-writing a version check or shipping none.

A perry.update block in package.json -- or [update] in perry.toml, which wins
key by key -- is validated at compile time and baked into the executable as a
small blob. The runtime reads it at the top of main, applies every gate, and
prints a two-line notice on stderr when a previous run recorded something
newer. The network refresh that records it is the next slice, so a first run is
silent.

With no block configured NOTHING is emitted: not an empty blob, not a disabled
one. A binary that configures no updates is byte-identical to one built before
this existed, and the end-to-end check asserts it. The blob is part of the
object-cache fingerprint, without which adding the block and rebuilding would
serve the cached entry object and ship a binary with no update check while
reporting success.

Validation is a build failure rather than a warning. A typo in an update URL is
found either by the person who typed it, now, or by their users, in production,
as silence. HTTPS is required (loopback excepted), each source must carry the
keys it reads, a zero check interval is rejected, and an app with no version to
compare against is caught.

State lives in the platform's cache location via dirs, keyed per app so two
Perry-built programs never share a throttle, with the app id sanitized into one
path component because it is a manifest value that becomes a path.

Three lessons from the CLI's own review are applied here rather than
rediscovered: the notify interval is keyed to the announced VERSION so it
cannot swallow the next release, the state file is written to a per-write
temporary name so two instances cannot rename over each other, and an
unreadable timestamp notifies rather than silencing updates forever. Two more
are specific to this half: the notice goes to stderr because an app's stdout
belongs to the app, and control characters are stripped because a release name
is attacker-influenceable terminal input.

An unparseable version never reads as newer -- node-smol compared against a
hardcoded 0.0.0, which made every release look newer than the running binary.

Author: jdalton

changelog.d/7789-app-update-config.md

@@ -0,0 +1,167 @@
+### Added
+
+**An application Perry compiles can now carry its own update check.** Perry's
+CLI has checked for updates for a long time; an app it *builds* could not, so
+shipping one meant the author wrote a version check by hand or shipped none and
+hoped users noticed.
+
+```json
+{ "perry": { "update": {
+    "source": "npm", "package": "myapp", "command": "self-update"
+} } }
+```
+
+A `perry.update` block — or an `[update]` table in perry.toml, which wins key by
+key — is validated at compile time and baked into the executable as a small
+blob. The runtime reads it at the top of `main`, before any user code.
+
+**With no block configured, nothing is emitted.** Not an empty blob, and not a
+disabled one: a binary that configures no updates is byte-identical to one built
+before this existed. A feature whose off-state still emits code is one you
+cannot prove is off.
+
+<details>
+<summary><b>Validation is a build failure, on purpose</b></summary>
+
+A typo in an update URL is discovered either by the person who typed it, at
+build time, with a message naming the key — or by their users, in production, as
+silence. So these are errors rather than warnings:
+
+- a URL must be `https://`, with loopback allowed for local testing. Plain HTTP
+  is refused rather than warned about, because an on-path attacker can suppress
+  a legitimate update by answering "you are current", and build-output warnings
+  are not where that gets noticed;
+- each source needs the keys it actually reads — `url` for `gh-releases` and
+  `custom`, `package` for the npm-shaped ones;
+- a zero check interval is rejected, since it would ask on every run; removing
+  the block is how you disable checks;
+- an app with no version has nothing to compare against, so that is caught too.
+
+`enabled = false` keeps the settings on disk and emits nothing, rather than
+embedding a disabled block complete with its URL and startup call.
+</details>
+
+<details>
+<summary><b>What the runtime half does, and what it deliberately does not</b></summary>
+
+It parses the blob and applies every gate that decides whether a check may
+happen: the app's own opt-out variable, `PERRY_NO_UPDATE_CHECK`, the
+ecosystem-wide `NO_UPDATE_NOTIFIER`, `CI` and `CONTINUOUS_INTEGRATION`, a
+non-terminal stderr, and the app's own update command — so `app self-update`
+does not check on its way to updating.
+
+It does **not** yet reach the network or print anything. That split is
+deliberate: the gates are where this feature can go wrong quietly. A check that
+fires in CI, or in a script parsing the app's output, is a bug that surfaces as
+somebody else's flaky pipeline, so they are worth landing and testing ahead of
+the code that would exercise them.
+
+A blob whose schema this build does not recognize is ignored rather than read
+field by field. It is emitted by the same Perry that compiled the binary, so a
+mismatch means something is wrong upstream, and guessing at a moved layout would
+run a network check with settings nobody wrote.
+</details>
+
+<details>
+<summary><b>The cache key, which is where this would have broken silently</b></summary>
+
+The blob is part of the object-cache fingerprint. Without that, adding
+`perry.update` to a project and rebuilding incrementally would serve the cached
+entry object from before — and the binary would ship with no update check while
+the build reported success. Same class as the `dbgloc` and `fmath` entries the
+cache file already documents.
+
+The embed is skipped for a dylib, for the same reason the App Group init is:
+there is no `main` to put a prelude in.
+</details>
+
+<details>
+<summary><b>Tests</b></summary>
+
+22 new. Ten on the compiler side cover the parse and every validation rule,
+including that perry.toml overrides package.json key by key while leaving keys it
+does not set alone, and that the blob stamps its schema and omits unset optionals
+rather than writing nulls. Twelve on the runtime side cover the blob reader and
+every gate, including that a key name appearing inside a *value* is not
+mismatched, and that an app with no config reports "not configured" instead of
+"go ahead" — an inversion the test caught during development.
+
+Verified end to end: a configured project's binary contains the blob, the same
+project without the block produces one that does not, the configured binary runs
+normally, and a plain-HTTP URL fails the build with a message naming the key.
+
+`cargo test -p perry`: 912 passed. `cargo test -p perry-runtime`: 2064 passed.
+Both zero failures.
+
+### Added (second slice)
+
+**The notify half now works from recorded state.** A compiled app with an
+embedded block reads its own per-app state file at startup and prints a
+two-line notice on stderr when a newer version was recorded by a previous run.
+The network refresh that records it is the next slice, so a first run is silent —
+which is the right way round.
+
+State lives in the platform's own cache location, resolved through `dirs` so it
+asks the real APIs (Known Folders on Windows, the Foundation search paths on
+macOS) rather than trusting environment variables a launcher or service manager
+may not have set. Keyed per app, so two Perry-built programs never share a
+throttle: one app's notice silencing another's would be invisible and
+maddening. The app id is sanitized into a single path component — it is a
+manifest value that becomes a path, and `..` is cheaper to make impossible than
+to reason about.
+
+<details>
+<summary><b>Three lessons from the CLI's own review, applied here first</b></summary>
+
+The interval throttles repeats of the **same** release, keyed on the version and
+not only on a timestamp. Keyed on time alone it swallows the next release
+whenever that arrives inside the window, so an interval set to stop nagging
+about one version would also hide the version that fixed it.
+
+The state file is written to a per-write temporary name and renamed over the
+target. Two instances of the same app can run at once, and one shared temporary
+name lets each rename a file the other is still writing.
+
+An unreadable timestamp notifies rather than staying silent, because silence on
+a damaged file would hide updates indefinitely.
+
+Two more that are specific to this half. The notice goes to **stderr**, always:
+an app's stdout belongs to the app. And every value in it arrived in a network
+document, so control characters are stripped — a release name is
+attacker-influenceable terminal input, and a notice must not be able to repaint
+somebody's screen.
+
+An unparseable version never reads as newer. node-smol's equivalent compared
+against a hardcoded `"0.0.0"`, which made every release look newer than the
+running binary; returning "unknown" is what avoids that.
+</details>
+
+<details>
+<summary><b>Tests</b></summary>
+
+16 more, bringing this module to 28. Beyond the units — version comparison,
+the sanitizer against five hostile ids, per-platform directory rules, the
+throttle, control-character stripping, a real file round trip, and that the
+stamp writer and reader agree — there is a **wiring test** that drives the whole
+startup path: blob in, notice out, state advanced, second run quiet.
+
+That one exists because everything else here is a piece tested in isolation, and
+a feature whose pieces all pass while the path between them is broken is exactly
+what ships doing nothing.
+
+`cargo test -p perry-runtime`: 2080 passed. `cargo test -p perry`: 912 passed.
+Both zero failures.
+
+### Documentation
+
+New page `docs/src/cli/app-updates.md`, written for the app author rather than
+for Perry's own maintainers: the smallest configuration that does something
+useful, every key, how to choose a source, the mistakes that fail the build and
+why each is an error rather than a warning, the cases where a user's run will not
+check at all, where the state file lives per platform, and how to give your own
+users an off switch.
+
+It states two things an app author needs to be able to rely on: their app's
+stdout is never touched, and the notify throttle is keyed to the version — so a
+week-long interval set to stop nagging about one release does not also hide the
+patch that fixes it.

crates/perry-codegen/src/codegen/entry.rs

@@ -375,6 +375,26 @@ pub(super) fn compile_module_entry(
                 .filter(|s| !s.is_empty())
                 .map(|suite| llmod.add_string_constant(suite))
         };
+        // The `perry.update` blob (Phase B): one string constant plus one
+        // `perry_update_notify_startup(ptr, len)` call at the top of `main`, so
+        // a configured app checks for its own updates without its author
+        // writing a version check. Emitted ONLY when the project configures the
+        // block — a binary with no update settings must be byte-identical to
+        // one built before this existed, which `entry.rs`'s absence test pins.
+        //
+        // Skipped for a dylib for the same reason `app_group` is: there is no
+        // `main` to put a prelude in, so the call would reference a startup
+        // path that does not exist here.
+        let update_init: Option<(String, usize)> = if is_dylib {
+            None
+        } else {
+            cross_module
+                .app_metadata
+                .update_config
+                .as_deref()
+                .filter(|s| !s.is_empty())
+                .map(|blob| llmod.add_string_constant(blob))
+        };
         // i18n startup init: when the project configures `[i18n]`, bake the
         // configured locale-code list (and the optional `[i18n.currencies]`
         // map) into `main`'s prelude as a single `perry_i18n_init` call —
@@ -494,6 +514,17 @@ pub(super) fn compile_module_entry(
                     &[(PTR, suite_ptr.as_str()), (I32, len_str.as_str())],
                 );
             }
+            // The update check runs before user code, so an app that exits
+            // early still gets its notice, and so the per-app state directory
+            // is resolved before anything can change the working directory.
+            if let Some((const_name, byte_len)) = update_init.as_ref() {
+                let blob_ptr = format!("@{}", const_name);
+                let len_str = byte_len.to_string();
+                blk.call_void(
+                    "perry_update_notify_startup",
+                    &[(PTR, blob_ptr.as_str()), (I32, len_str.as_str())],
+                );
+            }
             // i18n: register the configured locale list + resolve the runtime
             // locale BEFORE any module init runs, so module-top-level `t()`
             // calls and format wrappers already see the detected locale.

crates/perry-codegen/src/codegen/opts.rs

@@ -20,6 +20,13 @@ pub struct AppMetadata {
     /// `app_group_*` calls fall through to the runtime's "not configured"
     /// stub-warn diagnostic. Refs #1178.
     pub app_group: Option<String>,
+    /// The validated `perry.update` block, as the JSON blob the runtime reads,
+    /// or `None` when the project configures no update check.
+    ///
+    /// `None` must emit NOTHING — not an empty blob and not a disabled one. A
+    /// binary that configures no updates is byte-identical to one built before
+    /// this existed, and `entry.rs`'s absence test asserts it.
+    pub update_config: Option<String>,
 }
 
 impl Default for AppMetadata {
@@ -29,6 +36,7 @@ impl Default for AppMetadata {
             build_number: 1,
             bundle_id: "com.perry.app".to_string(),
             app_group: None,
+            update_config: None,
         }
     }
 }

crates/perry-codegen/src/runtime_decls/mod.rs

@@ -50,6 +50,10 @@ pub fn declare_phase1(module: &mut LlModule) {
     // the runtime always provides the symbol; main only emits the call
     // when `app_metadata.app_group` is `Some`.
     module.declare_function("perry_app_group_init", VOID, &[PTR, I32]);
+    // Phase B: the embedded `perry.update` blob's startup entry point. Declared
+    // unconditionally, like every other runtime symbol here — the CALL is what
+    // `entry.rs` emits only for a configured project.
+    module.declare_function("perry_update_notify_startup", VOID, &[PTR, I32]);
     // macOS asset-CWD fix: a macOS `.app` launched from Finder starts with
     // CWD=`/`, but the worker bundles assets into `Contents/Resources/`. The
     // `main` prelude calls this unconditionally; the runtime symbol no-ops on

crates/perry-runtime/src/lib.rs

@@ -247,6 +247,7 @@ mod ui_harmonyos_stubs;
 /// target-aware branching. UI crates register their handlers here at
 /// startup. See module docs for the ohos-napi gating story.
 pub mod ui_text_registry;
+pub mod update_notify;
 pub mod util_abort;
 pub mod util_call_sites;
 pub mod util_debuglog;