functualize 0.2.0__tar.gz → 0.2.2__tar.gz

{functualize-0.2.0 → functualize-0.2.2}/CHANGELOG.md

@@ -7,6 +7,115 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-09-04
+
+### Added — the standalone binary manages itself
+
+`func builtin self update` on a standalone install now **replaces the binary**.
+It reads the release source baked into the distribution, fetches that release,
+verifies the archive against its `SHA256SUMS` *before unpacking*, and swaps the
+file through a staged `os.replace` in the target's own directory — atomic, so
+an interrupted update leaves one working binary or the other, never a truncated
+file. An archive the checksums file does not mention is refused exactly like one
+that fails to match.
+
+`self install`, `self uninstall`, `plugin install` and `plugin uninstall` work
+on a standalone install too, through the bundled interpreter's own pip. A binary
+is the install method for a machine with no Python toolchain, so requiring `uv`
+on `PATH` to add a dependency would defeat it — and the baked distribution ships
+no uv. `self python -- ...` remains the escape hatch; `self uv` is the one
+command a standalone install does not have.
+
+The release source is baked, never hard-coded. An application that builds its
+own PyApp binary over functualize writes its own `standalone-release.json` and
+points its users at its own releases; its absence refuses cleanly rather than
+offering functualize's artifact to somebody else's users.
+
+### Fixed — the binaries 0.2.1 announced and could not build
+
+**All seven `binaries` jobs failed on 0.2.1.** The reported error was PyApp
+panicking without `PYAPP_DISTRIBUTION_PYTHON_PATH`, but fixing that alone was
+not enough: building a binary locally showed the baked artifact was unusable in
+a second, quieter way.
+
+- **A virtual environment is not a distribution.** The bake produced
+  `uv venv --relocatable`, whose `bin/python` is a symlink to the interpreter it
+  was created from and whose standard library lives in that interpreter's
+  prefix. Unpacked on another machine it contains no Python at all, and the
+  binary died on launch with `project execution failed / No such file or
+  directory (os error 2)`. The bake now copies the python-build-standalone
+  installation itself.
+
+- **uv installs a workspace root as editable by default**, writing a `.pth`
+  that points at the build machine and leaving no package in site-packages — a
+  binary that starts and then imports nothing. The bake passes `--no-editable`
+  and asserts no editable `.pth` survives.
+
+- **`uv python install` offers only the host libc's distributions**, so a musl
+  target baked on a glibc runner would embed a glibc interpreter. The musl bakes
+  run inside Alpine, with `build-base` installed because aarch64-musl has no
+  published wheel for one dependency.
+
+- **The size-measurement step failed six working builds.** `ls a b` exits
+  non-zero when one of the two names is absent, and under `set -o pipefail`
+  that failed the job *after* a successful ten-minute build.
+
+- **A `python.exe` at the distribution root**, not under `Scripts/`, is the
+  Windows layout for a standalone install.
+
+### Fixed — a standalone install could not be identified
+
+PyApp launches the application as `python -c "..."`, so `argv[0]` is the literal
+string `-c`. Self-management reverse-maps that to a distribution, found nothing,
+and read a healthy binary as a degraded install: every mutating command refused
+with exit `3`, `self doctor` reported "self-management is unavailable here", and
+the installation registry recorded `<prefix>/bin/-c` — a path that never existed
+— which it then correctly reported as stale on the run that created it.
+
+Identity now comes from PyApp itself, which supplies the executable's absolute
+path in `PYAPP` when built with `PYAPP_PASS_LOCATION=1`. A standalone install is
+no longer degraded for want of an owning distribution: it has none by
+construction, because it is a file rather than a package.
+
+`self update` previously delegated to `func pyapp update`. That command does not
+work on a pre-baked binary: PyApp hides it unless `PYAPP_EXPOSE_UPDATE=1`,
+refuses it outright under `PYAPP_SKIP_INSTALL=1`, and would `pip install
+--upgrade` from an index if it ran — dissolving the offline-complete
+distribution the binary exists to be.
+
+`install.sh` and `install.ps1` work from **this** release onward; 0.2.1's note
+to that effect was premature, as it shipped no binaries.
+
+## [0.2.1] - 2026-09-04
+
+### Fixed — the release pipeline that could not deliver 0.2.0's binaries
+
+**No library changes.** This release exists to ship the standalone binaries that
+0.2.0 announced and could not produce. If you install from PyPI, 0.2.1 and 0.2.0
+are the same code.
+
+The binary pipeline shipped in 0.2.0 and ran for the first time on its tag —
+these stages cannot execute before a tag exists, so the tag *was* the first test.
+Three defects surfaced:
+
+- **The `macos-13` runner label was retired on 2025-12-04.** A workflow naming a
+  dead label does not fail — it queues forever. The release sat "in progress"
+  for an hour with no runner ever assigned. Now `macos-15-intel`, which is the
+  last x86_64 macOS image GitHub will offer.
+
+- **The binary and checksum stages required their entire upstream matrix to
+  succeed.** `needs.<job>.result` is the aggregate across a matrix, so one
+  target failing skipped all seven — `fail-fast: false` buys nothing across a
+  stage boundary. A broken platform now costs its own binary and nothing else.
+
+- **The GitHub Release depended on the binaries.** A failed binary build
+  therefore skipped the release entirely, leaving PyPI with the version and
+  GitHub with a bare tag. It is now gated on the PyPI publish alone; the wheel
+  is the primary artifact and the binaries ride along.
+
+`install.sh` and `install.ps1` work from this release onward. 0.2.0 remains a
+PyPI-only release.
+
 ## [0.2.0] - 2026-09-04
 
 ### Added — a standalone binary, and installations that manage themselves
@@ -1065,7 +1174,9 @@ function knowing which.
   through the injected `Log` is deferred to a later release.
   *(Fixed in 0.1.1.)*
 
-[Unreleased]: https://github.com/raicing-ai/functualize/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/raicing-ai/functualize/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/raicing-ai/functualize/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/raicing-ai/functualize/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/raicing-ai/functualize/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/raicing-ai/functualize/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/raicing-ai/functualize/compare/v0.1.1...v0.1.2

{functualize-0.2.0 → functualize-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: functualize
-Version: 0.2.0
+Version: 0.2.2
 Summary: A reusable Python CLI framework with auto-discovery, structured run context, layered configuration, and TUI integration
 Project-URL: Homepage, https://github.com/raicing-ai/functualize
 Project-URL: Repository, https://github.com/raicing-ai/functualize
@@ -156,6 +156,11 @@ self update` then restores anything you had added — including packages install
 > binary, a `uv tool` install, a `pipx` install, or a project checkout. A bare `pip install`
 > into a system interpreter is not self-managing: the command prints guidance, changes
 > nothing, and exits `3`. `func builtin self doctor` tells you which kind you have.
+>
+> The standalone binary updates by **replacing itself**: it fetches the release for its own
+> platform, verifies it against the release's `SHA256SUMS` before unpacking, and swaps the
+> file. Packages you had added are reinstalled into the new distribution afterwards — a new
+> binary unpacks a new environment, so they do not carry over on their own.
 
 ### How `func` finds jobs
 

{functualize-0.2.0 → functualize-0.2.2}/README.md

@@ -107,6 +107,11 @@ self update` then restores anything you had added — including packages install
 > binary, a `uv tool` install, a `pipx` install, or a project checkout. A bare `pip install`
 > into a system interpreter is not self-managing: the command prints guidance, changes
 > nothing, and exits `3`. `func builtin self doctor` tells you which kind you have.
+>
+> The standalone binary updates by **replacing itself**: it fetches the release for its own
+> platform, verifies it against the release's `SHA256SUMS` before unpacking, and swaps the
+> file. Packages you had added are reinstalled into the new distribution afterwards — a new
+> binary unpacks a new environment, so they do not carry over on their own.
 
 ### How `func` finds jobs
 

{functualize-0.2.0 → functualize-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "functualize"
-version = "0.2.0"
+version = "0.2.2"
 description = "A reusable Python CLI framework with auto-discovery, structured run context, layered configuration, and TUI integration"
 readme = "README.md"
 license = "MIT"

{functualize-0.2.0 → functualize-0.2.2}/skills/functualize/SKILL.md

@@ -12,7 +12,7 @@ description: >
   upgrading, or configuring the `func` tool itself — use functualize-cli.
 license: MIT
 metadata:
-  version: "0.2.0"
+  version: "0.2.2"
   project: functualize
 ---
 

{functualize-0.2.0 → functualize-0.2.2}/skills/functualize-app/SKILL.md

@@ -11,7 +11,7 @@ description: >
   ready" or well tested, or when packaging a functualize CLI for distribution.
 license: MIT
 metadata:
-  version: "0.2.0"
+  version: "0.2.2"
   project: functualize
 ---
 

{functualize-0.2.0 → functualize-0.2.2}/skills/functualize-cli/SKILL.md

@@ -14,7 +14,7 @@ description: >
   skill.
 license: MIT
 metadata:
-  version: "0.2.0"
+  version: "0.2.2"
   project: functualize
 ---
 

{functualize-0.2.0 → functualize-0.2.2}/skills/functualize-skill/SKILL.md

@@ -10,7 +10,7 @@ description: >
   real work, or when asked how to share or publish a skill.
 license: MIT
 metadata:
-  version: "0.2.0"
+  version: "0.2.2"
   project: functualize
 ---
 

{functualize-0.2.0 → functualize-0.2.2}/src/functualize/__init__.py

@@ -1,6 +1,6 @@
 """Functualize - A reusable Python CLI framework."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 from functualize._config.job_config import JobConfigView
 from functualize._gate import GateContext, GateResolver, GateStrategy

{functualize-0.2.0 → functualize-0.2.2}/src/functualize/_cli/main.py

@@ -1758,7 +1758,12 @@ def _register_this_installation() -> None:
         # than imported so the warm path stays free of that module's dataclass
         # codegen. `tests/_cli/test_manifest.py` asserts the two agree.
         argv0 = sys.argv[0] if sys.argv else ""
-        if not argv0:
+        pyapp = os.environ.get("PYAPP", "")
+        if pyapp and pyapp != "1":
+            # A standalone binary: `argv0` is `-c` and useless. See
+            # `resolve_binary_path`.
+            binary_path = str(Path(pyapp).resolve())
+        elif not argv0:
             binary_path = ""
         elif "/" in argv0 or "\\" in argv0:
             binary_path = str(Path(argv0).resolve())

{functualize-0.2.0 → functualize-0.2.2}/src/functualize/_cli/manifest.py

@@ -164,9 +164,18 @@ class Manifest:
         }
 
 
-def resolve_binary_path(argv0: str, executable: str) -> str:
+def resolve_binary_path(
+    argv0: str, executable: str, standalone_binary: str | None = None
+) -> str:
     """A stable identity for "this installation", whatever `argv[0]` looks like.
 
+    `standalone_binary` wins outright when supplied. PyApp launches a standalone
+    binary as `python -c "..."`, so `argv[0]` is the literal string `-c` and
+    every derivation below produces `<prefix>/bin/-c` -- a path that has never
+    existed, which the registry then correctly reports as stale on the very run
+    that recorded it. PyApp hands over the real executable path in `PYAPP`
+    (built with `PYAPP_PASS_LOCATION=1`), and that is the only honest answer.
+
     `sys.argv[0]` is not stable across invocation styles: a direct call gives an
     absolute path, while `uv run func` gives the bare name `func`. Recording it
     raw registers one installation twice, and then reports the bare-name copy as
@@ -181,6 +190,15 @@ def resolve_binary_path(argv0: str, executable: str) -> str:
     avoid importing this module; `tests/_cli/test_manifest.py` asserts the two
     agree.
     """
+    if standalone_binary:
+        # Substituted for `argv0` rather than returned directly, so it goes
+        # through the same normalization. PyApp's `PYAPP` is always absolute and
+        # falls out of the separator branch unchanged; a bare name -- which is
+        # what the `FUNCTUALIZE_RUNTIME=standalone` override sees -- must still
+        # resolve against the interpreter's directory and not the working one,
+        # or this disagrees with `main.py`'s warm path and the registry records
+        # the same installation twice.
+        argv0 = standalone_binary
     if not argv0:
         return ""
     if "/" in argv0 or "\\" in argv0:

{functualize-0.2.0 → functualize-0.2.2}/src/functualize/_cli/package_ops.py

@@ -38,11 +38,12 @@ from functualize._cli.runtime import Detection, InstallMode
 from functualize.app.utils import ExitCode
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable, Sequence
+    from collections.abc import Callable, Iterable, Mapping, Sequence
 
 __all__ = [
     "LossyReceiptError",
     "MissingToolError",
+    "StandaloneUpdateError",
     "Requirement",
     "announce",
     "capture_environment",
@@ -510,6 +511,24 @@ def owned_python() -> str:
 # ---------------------------------------------------------------------------
 
 
+class StandaloneUpdateError(Exception):
+    """``self update`` on a standalone install is not a subprocess.
+
+    Every other mode delegates to a package manager, so its update is a command
+    tuple. A standalone binary is a single file, and updating it means
+    downloading a release and replacing that file -- work that happens
+    in-process, in :mod:`functualize._cli.self_update`. Raised rather than
+    returned so a caller that forgets to handle it fails loudly instead of
+    running an empty command list and reporting success.
+
+    PyApp's own updater is not an option: it is hidden unless
+    ``PYAPP_EXPOSE_UPDATE=1``, refuses outright under ``PYAPP_SKIP_INSTALL=1``
+    (`"Cannot update as installation is disabled"`), and would ``pip install
+    --upgrade`` from an index if it ran -- replacing the offline-complete
+    environment the binary exists to be.
+    """
+
+
 def update_commands(
     detection: Detection, binary_path: str
 ) -> tuple[tuple[str, ...], ...]:
@@ -526,15 +545,23 @@ def update_commands(
             backstop that keeps a refusal from silently becoming a command.
         MissingToolError: the mode's manager is not installed.
     """
+    # Standalone is checked *before* the owner guard. It has no owning
+    # distribution by construction -- it is a file, not a package -- so the
+    # guard that protects every other mode from acting on a name it could not
+    # resolve would refuse every healthy binary.
+    if detection.mode is InstallMode.STANDALONE:
+        if detection.standalone_binary is None:
+            raise ValueError(
+                "standalone installations cannot be updated without knowing "
+                "their own path"
+            )
+        raise StandaloneUpdateError(detection.standalone_binary)
+
     distribution = detection.owning_distribution
     if detection.degraded or distribution is None:
         raise ValueError(f"{detection.mode.value} installations are not self-managing")
 
     match detection.mode:
-        case InstallMode.STANDALONE:
-            # PyApp's own updater, reachable at the renamed self-command
-            # (`PYAPP_SELF_COMMAND=pyapp`). It replaces the binary in place.
-            return ((binary_path, "pyapp", "update"),)
         case InstallMode.TOOL_UV:
             return ((resolve_uv(), "tool", "upgrade", distribution),)
         case InstallMode.TOOL_PIPX:
@@ -562,18 +589,14 @@ def install_commands(detection: Detection, package: str) -> tuple[tuple[str, ...
         MissingToolError: the mode's manager is not installed.
         LossyReceiptError: a uv receipt could not be reproduced faithfully.
     """
+    if detection.mode is InstallMode.STANDALONE:
+        return ((*_bundled_pip(), "install", package),)
+
     distribution = detection.owning_distribution
     if detection.degraded or distribution is None:
         raise ValueError(f"{detection.mode.value} installations are not self-managing")
 
     match detection.mode:
-        case InstallMode.STANDALONE:
-            # `--python` targets the bundled interpreter explicitly. Without it
-            # uv picks a Python by its own discovery rules, which in a shell
-            # with an activated venv is somebody else's environment.
-            return (
-                (resolve_uv(), "pip", "install", "--python", owned_python(), package),
-            )
         case InstallMode.TOOL_UV:
             uv = resolve_uv()
             receipt = read_receipt(Path(sys.prefix))
@@ -597,15 +620,14 @@ def uninstall_commands(
         MissingToolError: the mode's manager is not installed.
         LossyReceiptError: a uv receipt could not be reproduced faithfully.
     """
+    if detection.mode is InstallMode.STANDALONE:
+        return ((*_bundled_pip(), "uninstall", "-y", package),)
+
     distribution = detection.owning_distribution
     if detection.degraded or distribution is None:
         raise ValueError(f"{detection.mode.value} installations are not self-managing")
 
     match detection.mode:
-        case InstallMode.STANDALONE:
-            return (
-                (resolve_uv(), "pip", "uninstall", "--python", owned_python(), package),
-            )
         case InstallMode.TOOL_UV:
             uv = resolve_uv()
             receipt = read_receipt(Path(sys.prefix))
@@ -638,16 +660,53 @@ def render(argv: Sequence[str]) -> str:
     return " ".join(parts)
 
 
-def script_name() -> str:
+def _bundled_pip() -> tuple[str, ...]:
+    """The bundled interpreter's own pip, as a command prefix.
+
+    Not uv. A standalone binary is the install method for a machine with no
+    Python toolchain, so requiring ``uv`` on ``PATH`` before a package can be
+    added defeats the reason it exists -- and PyApp's baked distribution ships
+    no uv, so ``resolve_uv()`` would raise on the very install method that
+    cannot fix it. pip is present in the distribution and the bake asserts so.
+
+    ``-m pip`` rather than the ``pip`` script: the script's shebang is written
+    at build time and points at the *build machine's* path, which is not where
+    the distribution unpacks.
+    """
+    return (owned_python(), "-m", "pip")
+
+
+def script_name(environ: Mapping[str, str] | None = None) -> str:
     """The console script the user actually typed, for use in guidance.
 
     Never a hard-coded ``func``: in a consumer application this text has to
     name *that* application's script or it tells the user to run a command they
     do not have.
+
+    And never ``-c``. PyApp launches a standalone binary as ``python -c "..."``,
+    so ``argv[0]`` is that literal string and guidance built from it reads
+    ``Run `-c builtin self doctor` `` -- a command nobody can type. PyApp
+    supplies the real name in ``PYAPP_COMMAND_NAME``; falling back to the
+    binary's own basename covers a build that did not expose one.
     """
+    env = os.environ if environ is None else environ
+
+    exposed = env.get("PYAPP_COMMAND_NAME", "")
+    if exposed:
+        return exposed
+
     argv0 = sys.argv[0] if sys.argv else ""
     name = argv0.replace("\\", "/").rsplit("/", 1)[-1]
-    return name or "func"
+    if name and name != "-c":
+        return name
+
+    binary = env.get("PYAPP", "")
+    if binary and binary != "1":
+        basename = binary.replace("\\", "/").rsplit("/", 1)[-1]
+        if basename:
+            return basename
+
+    return "func"
 
 
 def refuse(detection: Detection, what: str) -> NoReturn:

{functualize-0.2.0 → functualize-0.2.2}/src/functualize/_cli/plugin_cmd.py

@@ -174,10 +174,13 @@ def _binary_and_config() -> tuple[str, Path]:
     import sys
 
     from functualize._cli import manifest
+    from functualize._cli.runtime import detect_from_process
     from functualize.app.utils import resolve_user_config_dir
 
     binary = manifest.resolve_binary_path(
-        sys.argv[0] if sys.argv else "", sys.executable
+        sys.argv[0] if sys.argv else "",
+        sys.executable,
+        detect_from_process().standalone_binary,
     )
     return binary, resolve_user_config_dir()
 

{functualize-0.2.0 → functualize-0.2.2}/src/functualize/_cli/runtime.py

@@ -90,10 +90,23 @@ class Detection:
     #: wrong-owner failure this module exists to prevent, so ``None`` forces
     #: the refusal path.
     owning_distribution: str | None
+    #: The standalone binary's own absolute path, as PyApp reports it in
+    #: ``PYAPP`` when built with ``PYAPP_PASS_LOCATION=1``. ``None`` for every
+    #: other mode, and for a standalone binary built without that flag or whose
+    #: ``current_exe()`` lookup failed.
+    standalone_binary: str | None = None
 
     @property
     def degraded(self) -> bool:
         """Either the environment or the owner is unusable for management."""
+        if self.mode is InstallMode.STANDALONE:
+            # A standalone binary has no owning distribution *by construction*
+            # -- it is a file, not a package -- so the absence that degrades
+            # every other mode says nothing here. What a mutating command needs
+            # is the executable to act on, and PyApp launches the application
+            # through `python -c`, so `argv[0]` is the literal string `-c` and
+            # can never supply it. The binary's own path is the discriminator.
+            return self.standalone_binary is None
         return self.mode.degraded or self.owning_distribution is None
 
 
@@ -233,9 +246,33 @@ def detect(
     return Detection(
         mode=_detect_mode(prefix, base_prefix, environ, cwd),
         owning_distribution=_owning_distribution(argv0),
+        standalone_binary=_standalone_binary(environ, argv0),
     )
 
 
+def _standalone_binary(environ: Mapping[str, str], argv0: str) -> str | None:
+    """The running executable's path, for a standalone installation.
+
+    ``PYAPP`` holds the absolute path only when the binary was built with
+    ``PYAPP_PASS_LOCATION=1``; older builds set the literal ``"1"`` and a build
+    whose ``current_exe()`` failed sets the empty string. Both are "unknown",
+    not a path — returning ``"1"`` here would have every mutating command
+    operate on a file named ``1`` in the working directory.
+
+    ``argv0`` is the second rung, and it is not a fallback guess. Inside a real
+    PyApp binary it is the literal string ``-c`` and this rung cannot fire. It
+    fires only when the mode was pinned with ``FUNCTUALIZE_RUNTIME=standalone``
+    — where ``argv0`` genuinely *is* the command that ran — which is what keeps
+    that override useful rather than a way to manufacture a degraded install.
+    """
+    value = environ.get("PYAPP", "")
+    if value and value != "1":
+        return value
+    if argv0 and argv0 != "-c":
+        return argv0
+    return None
+
+
 def _detect_mode(
     prefix: str,
     base_prefix: str,
@@ -254,8 +291,14 @@ def _detect_mode(
                 f"Expected one of: {', '.join(m.value for m in InstallMode)}"
             ) from None
 
-    # 2. The binary announces itself: PyApp injects PYAPP=1 into its runtime.
-    if environ.get("PYAPP") or environ.get("PYAPP_COMMAND_NAME"):
+    # 2. The binary announces itself: PyApp injects PYAPP into its runtime --
+    #    the executable's own path under `PYAPP_PASS_LOCATION=1`, otherwise
+    #    "1". Membership, not truthiness: PyApp sets it to the *empty string*
+    #    when `current_exe()` fails (`distribution.rs:56`), and a binary that
+    #    cannot name itself is still a standalone binary. Reading that as
+    #    "not standalone" would send it down the project or unknown rungs and
+    #    describe it as something it is not.
+    if "PYAPP" in environ or environ.get("PYAPP_COMMAND_NAME"):
         return InstallMode.STANDALONE
 
     prefix_path = Path(prefix)

{functualize-0.2.0 → functualize-0.2.2}/src/functualize/_cli/self_cmd.py

@@ -39,7 +39,7 @@ from pathlib import Path
 
 import click
 
-from functualize._cli.runtime import Detection, detect_from_process
+from functualize._cli.runtime import Detection, InstallMode, detect_from_process
 from functualize.app.utils import ExitCode
 
 # `manifest` and `package_ops` are imported *inside* the commands that need
@@ -154,7 +154,37 @@ def _check_install(detection: Detection) -> list[Check]:
     checks = [
         Check("install-mode", CheckStatus.INFO, detection.mode.value),
     ]
-    if detection.owning_distribution is None:
+    if detection.mode is InstallMode.STANDALONE:
+        # Not a warning, and not "unknown". A standalone binary has no owning
+        # distribution *by construction* -- it is a file, not a package -- so
+        # reporting the absence as a fault would tell a healthy installation
+        # that self-management is unavailable, which it is not. What identifies
+        # it is the executable, and that is worth showing.
+        checks.append(
+            Check(
+                "owning-distribution",
+                CheckStatus.INFO,
+                "not applicable — a standalone binary manages itself",
+            )
+        )
+        if detection.standalone_binary is None:
+            checks.append(
+                Check(
+                    "binary-path",
+                    CheckStatus.WARNING,
+                    "this binary cannot determine its own location",
+                    remedy=(
+                        "It was built without PYAPP_PASS_LOCATION=1, so there is "
+                        "nothing for `self update` to replace. Reinstall from a "
+                        "current release."
+                    ),
+                )
+            )
+        else:
+            checks.append(
+                Check("binary-path", CheckStatus.OK, detection.standalone_binary)
+            )
+    elif detection.owning_distribution is None:
         checks.append(
             Check(
                 "owning-distribution",
@@ -470,7 +500,11 @@ def doctor(output_format: str) -> None:
 def _this_binary() -> str:
     from functualize._cli import manifest
 
-    return manifest.resolve_binary_path(sys.argv[0] if sys.argv else "", sys.executable)
+    return manifest.resolve_binary_path(
+        sys.argv[0] if sys.argv else "",
+        sys.executable,
+        detect_from_process().standalone_binary,
+    )
 
 
 def _config_dir() -> Path:
@@ -496,9 +530,18 @@ def update(assume_yes: bool) -> None:
         package_ops.refuse(detection, "update")
 
     binary = _this_binary()
-    commands = package_ops.plan_or_exit(
-        lambda: package_ops.update_commands(detection, binary)
-    )
+    try:
+        commands = package_ops.plan_or_exit(
+            lambda: package_ops.update_commands(detection, binary)
+        )
+    except package_ops.StandaloneUpdateError:
+        # A standalone binary has no package manager to delegate to: updating
+        # it means fetching a release and replacing one file, which happens
+        # in-process. Raised rather than returned as an empty command list, so
+        # forgetting this branch fails loudly instead of reporting success
+        # having done nothing.
+        raise SystemExit(_update_standalone(binary, assume_yes)) from None
+
     package_ops.announce(commands, assume_yes)
 
     config_dir = _config_dir()
@@ -529,6 +572,59 @@ def update(assume_yes: bool) -> None:
     _reconcile(detection, config_dir, binary, before)
 
 
+def _update_standalone(binary: str, assume_yes: bool) -> int:
+    """`self update` for a standalone binary. Returns the process exit code.
+
+    Reconciliation is deliberately *not* the in-process kind the other modes
+    use. Replacing the executable means the next launch unpacks a different
+    distribution at a different path, so packages added to the old one are not
+    "removed by an upgrade" -- they are in a directory nothing will look at
+    again. The new binary is therefore asked to install them into its own
+    distribution, which it can only do after it has unpacked one.
+    """
+    import functualize
+    from functualize._cli import manifest, self_update
+
+    config_dir = _config_dir()
+    # Captured before the replacement, for the same reason every other mode
+    # persists first: an update interrupted between the two loses the record of
+    # what to put back.
+    keep = sorted(set(manifest.recorded_additions(config_dir, binary)))
+
+    code = self_update.perform(
+        binary=Path(binary),
+        prefix=Path(sys.prefix),
+        current_version=functualize.__version__,
+        assume_yes=assume_yes,
+        echo=click.echo,
+        confirm=click.confirm,
+    )
+    if code != int(ExitCode.OK) or not keep:
+        return code
+
+    click.echo(f"Reinstalling {len(keep)} package(s) into the new distribution.")
+    failed: list[str] = []
+    for package in keep:
+        result = subprocess.run(  # noqa: S603 - argv list, no shell
+            [binary, "builtin", "self", "install", package, "--yes"],
+            check=False,
+        )
+        if result.returncode != 0:
+            failed.append(package)
+
+    for package in failed:
+        click.echo(f"  could not reinstall {package}", err=True)
+    if failed:
+        # Reported, not fatal: the update itself succeeded, and turning one
+        # unreachable package into a failed update would misdescribe the state
+        # of the installation.
+        click.echo(
+            f"{len(failed)} package(s) need reinstalling by hand.",
+            err=True,
+        )
+    return int(ExitCode.OK)
+
+
 def _reconcile(
     detection: Detection,
     config_dir: Path,