Documentation: Update nxpkg and add nxstore guide.

Documentation/applications/system/nxpkg/index.rst

@@ -0,0 +1,154 @@
+=========
+``nxpkg``
+=========
+
+``nxpkg`` manages standalone Dynamic ELF application images in a small,
+versioned on-device store.  It can synchronize a static package catalog,
+install or update a compatible payload, list available and installed
+packages, roll back to the previous installed version, and remove a package.
+
+The implementation is intentionally small.  It does not resolve dependencies
+or provide a general-purpose system package format.
+
+Configuration
+=============
+
+Enable ``CONFIG_SYSTEM_NXPKG``.  The command name, task settings, and storage
+root are configured with:
+
+* ``CONFIG_SYSTEM_NXPKG_PROGNAME``
+* ``CONFIG_SYSTEM_NXPKG_PRIORITY``
+* ``CONFIG_SYSTEM_NXPKG_STACKSIZE``
+* ``CONFIG_SYSTEM_NXPKG_ROOT``
+
+The default storage root is ``/var/lib/nxpkg``.  Mount persistent storage at
+``/var`` or select a board-appropriate persistent path, such as
+``/mnt/sdcard/nxpkg``, if installed packages must survive a reset.  A
+``tmpfs``-backed root is useful for tests but is not persistent.
+
+Dynamic ELF loading and the target's required binary-format support must also
+be enabled.  Synchronizing or downloading from an HTTP URL requires
+``CONFIG_NETUTILS_WEBCLIENT`` and a working network configuration.  Local
+filesystem sources work without the web client.
+
+Commands
+========
+
+The command-line interface is:
+
+.. code-block:: console
+
+   nxpkg sync <index-source>
+   nxpkg available
+   nxpkg install <name>
+   nxpkg update <name>
+   nxpkg list
+   nxpkg rollback <name>
+   nxpkg remove <name>
+
+``sync`` accepts either a local index path or an HTTP/HTTPS URL.  ``install``
+selects the newest catalog entry whose architecture and compatibility strings
+match the running target.  ``update`` uses the same operation and therefore
+installs the newest matching version.  ``rollback`` swaps the current and
+previous installed versions.
+
+Repository format
+=================
+
+A repository is a directory of static files.  No package-specific server is
+required.  Its index contains a ``packages`` array, for example:
+
+.. code-block:: json
+
+   {
+     "packages": [
+       {
+         "name": "hello",
+         "version": "1.0.0",
+         "arch": "xtensa",
+         "compat": "esp32s3-xiao",
+         "artifact": "artifacts/xtensa/esp32s3/esp32s3-xiao/hello/1.0.0/hello",
+         "sha256": "<64 hexadecimal characters>",
+         "type": "elf"
+       }
+     ]
+   }
+
+``name``, ``version``, ``arch``, ``compat``, ``artifact``, ``sha256``, and
+``type`` are required.  Supported types are ``elf`` and ``shared-lib``.
+``description``, ``category``, ``icon``, and ``launch_args`` are optional
+metadata used by front ends.  Relative artifact and icon paths are resolved
+from the synchronized index location.
+
+The catalog may contain entries for several targets and versions.  Version
+selection compares dot-separated numeric components numerically and other
+components lexically; it is not a complete Semantic Versioning
+implementation.
+
+The repository export helper in ``apps/tools/export_pkg_repo.py`` copies
+built artifacts, calculates their SHA-256 digests, and writes the index:
+
+.. code-block:: console
+
+   python3 apps/tools/export_pkg_repo.py /tmp/nxpkg-repo \
+     --arch xtensa \
+     --chip esp32s3 \
+     --compat esp32s3-xiao \
+     --package hello:1.0.0:elf:apps/bin/hello
+
+The resulting directory can be served during local development with any
+static file server, for example:
+
+.. code-block:: console
+
+   cd /tmp/nxpkg-repo
+   python3 -m http.server 8000
+
+Then synchronize the board from the development host:
+
+.. code-block:: console
+
+   nsh> nxpkg sync http://192.0.2.1:8000/index.json
+   nsh> nxpkg available
+   nsh> nxpkg install hello
+   nsh> nxpkg list
+
+Replace the example address with one reachable from the target.
+
+On-device layout
+================
+
+Under ``CONFIG_SYSTEM_NXPKG_ROOT``, ``nxpkg`` stores:
+
+* ``index.jsn``: the last synchronized catalog and the source used to resolve
+  relative artifact and icon paths
+* ``instpkg.jsn``: the authoritative installed-package database
+* ``pkgs/<name>/<version>/``: versioned payload and manifest files
+* ``pkgs/<name>/current`` and ``previous``: convenience mirrors of the
+  database state
+* ``tmp/``: bounded temporary downloads and atomic-write files
+
+Install and update operations use per-package locks.  A separate lock
+serializes changes to the shared installed database.  An interrupted
+operation leaves transaction state that the next operation can clean up.
+
+Security scope
+==============
+
+The SHA-256 field detects accidental corruption only when the index itself is
+trusted.  If both the catalog and artifact arrive over unauthenticated HTTP,
+an active attacker can replace both and provide a matching digest.  Use an
+authenticated transport and a trusted endpoint for untrusted networks.
+
+The current format does not include signed repository metadata or package
+signatures.  Plain HTTP is therefore appropriate only for a trusted, isolated
+development network where that risk is explicitly accepted.  Package
+compatibility checks are target-selection checks, not a security boundary.
+
+Current limitations
+===================
+
+``nxpkg`` does not currently provide dependency solving, repository metadata
+signatures, package signatures, or a policy engine.  Filesystem constraints
+also apply to the selected storage root; for example, a short-name-only FAT
+configuration limits usable package and artifact names.

Documentation/applications/system/nxstore/index.rst

@@ -0,0 +1,99 @@
+===========
+``nxstore``
+===========
+
+``nxstore`` is an LVGL front end for :doc:`../nxpkg/index`.  It displays the
+packages in the synchronized catalog, installs a selected package on a worker
+thread, launches installed Dynamic ELF applications, and supervises the one
+application currently using the display.
+
+.. figure:: nxstore-esp32s3.jpg
+   :figwidth: 80%
+   :align: center
+   :alt: NXStore package catalog running on an ESP32-S3 touchscreen board
+
+   NXStore package catalog running on a Waveshare
+   ESP32-S3-Touch-LCD-7 board.
+
+Configuration
+=============
+
+Enable ``CONFIG_SYSTEM_NXSTORE``.  It depends on
+``CONFIG_GRAPHICS_LVGL`` and ``CONFIG_SYSTEM_NXPKG``.  Its principal options
+are:
+
+* ``CONFIG_SYSTEM_NXSTORE_PROGNAME``
+* ``CONFIG_SYSTEM_NXSTORE_PRIORITY``
+* ``CONFIG_SYSTEM_NXSTORE_STACKSIZE``
+* ``CONFIG_SYSTEM_NXSTORE_FBDEVPATH``
+* ``CONFIG_SYSTEM_NXSTORE_INPUT_DEVPATH``
+
+The framebuffer and input paths default to ``/dev/fb0`` and ``/dev/input0``.
+The board must provide LVGL-compatible display and input drivers.  ``nxpkg``
+must use a writable storage root, and remote synchronization additionally
+requires the networking options described in the ``nxpkg`` documentation.
+
+Starting the store
+==================
+
+With no argument, ``nxstore`` opens the last catalog synchronized by
+``nxpkg``:
+
+.. code-block:: console
+
+   nsh> nxstore
+
+An optional index URL asks the store to synchronize before drawing the list:
+
+.. code-block:: console
+
+   nsh> nxstore http://192.0.2.1:8000/index.json
+
+Transient network failures are retried for a bounded interval.  If
+synchronization still fails, the UI reports the failure and uses the last
+valid cached catalog when one exists.  Invalid metadata and local storage
+errors are not retried.
+
+Interaction
+===========
+
+Each catalog package appears once, using its newest compatible version.
+
+* Tap an uninstalled package to install and launch it.
+* Tap an installed package to launch its current installed version.
+* Long-press an installed package to remove all its installed versions.
+* Tap ``Close`` on the running-application screen to request termination.
+
+Installation runs outside the LVGL thread so progress remains visible.  LVGL
+objects are updated only by the main UI thread.  Launch arguments are read
+from the stored manifest for the current installed version, including after a
+rollback.
+
+Application termination contract
+================================
+
+The ``Close`` control sends ``SIGTERM`` to the launched process.  A
+long-running application should install a signal handler that performs only
+an async-signal-safe action, such as setting a ``volatile sig_atomic_t`` flag,
+and then poll that flag from its main loop.  The normal execution path should
+release framebuffer, input, and other resources before returning.
+
+``nxstore`` does not force-delete an application that ignores ``SIGTERM``.
+Forceful task deletion can interrupt display, heap, or filesystem operations
+and leave the system in an unsafe state.  Until the child exits, the store
+keeps the running-application screen visible and does not hand the display
+back to the package list.
+
+The store and the launched application share one framebuffer.  A
+framebuffer application must leave the top ``NXSTORE_BAR_HEIGHT`` pixels
+untouched so the supervisor bar remains visible.  Include
+``<system/nxstore_chrome.h>`` instead of duplicating the current height.
+
+Current limitations
+===================
+
+Only one install worker and one supervised application are supported at a
+time.  The launcher currently uses one fixed, generous stack size for all
+packages because the manifest format does not carry a per-application stack
+requirement.  Applications that cannot reserve the supervisor strip are not
+currently suitable for launch from ``nxstore``.