From f94d1374566a63657ac0e3193c4249c436de0a55 Mon Sep 17 00:00:00 2001
From: James Watt <james@bevjam.com>
Date: Thu, 4 Jan 2024 17:09:44 -0500
Subject: [PATCH 1/4] feature: add support for opkg (OpenWrt's package manager)

---
 pyinfra/facts/opkg.py                         | 208 ++++++++++++++++++
 pyinfra/operations/opkg.py                    |  95 ++++++++
 tests/facts/opkg.Conf/opkg_conf.json          |  42 ++++
 tests/facts/opkg.Feeds/opkg_feeds.json        |  51 +++++
 .../opkg_installable_architectures.json       |  20 ++
 tests/facts/opkg.Packages/opkg_packages.json  |  39 ++++
 .../opkg_upgradeable_packages.json            |  34 +++
 .../opkg.packages/add_existing_package.json   |  12 +
 .../opkg.packages/add_multiple_packages.json  |  12 +
 .../opkg.packages/add_one_package.json        |  12 +
 .../add_with_unallowed_pinning.json           |  11 +
 .../list_of_nulls_package_list.json           |   9 +
 .../opkg.packages/null_package_list.json      |   9 +
 .../remove_existing_package.json              |  13 ++
 ...e_existing_package_and_require_update.json |  14 ++
 .../remove_not_existing_package.json          |  13 ++
 .../opkg.packages/update_then_add_one.json    |  11 +
 .../operations/opkg.update/first_update.json  |   9 +
 .../opkg_second_update_forced.json            |  10 +
 .../operations/opkg.update/second_update.json |   9 +
 .../opkg.update/second_update_with_force.json |  10 +
 tests/words.txt                               |   4 +
 22 files changed, 647 insertions(+)
 create mode 100644 pyinfra/facts/opkg.py
 create mode 100644 pyinfra/operations/opkg.py
 create mode 100644 tests/facts/opkg.Conf/opkg_conf.json
 create mode 100644 tests/facts/opkg.Feeds/opkg_feeds.json
 create mode 100644 tests/facts/opkg.InstallableArchitectures/opkg_installable_architectures.json
 create mode 100644 tests/facts/opkg.Packages/opkg_packages.json
 create mode 100644 tests/facts/opkg.UpgradeablePackages/opkg_upgradeable_packages.json
 create mode 100644 tests/operations/opkg.packages/add_existing_package.json
 create mode 100644 tests/operations/opkg.packages/add_multiple_packages.json
 create mode 100644 tests/operations/opkg.packages/add_one_package.json
 create mode 100644 tests/operations/opkg.packages/add_with_unallowed_pinning.json
 create mode 100644 tests/operations/opkg.packages/list_of_nulls_package_list.json
 create mode 100644 tests/operations/opkg.packages/null_package_list.json
 create mode 100644 tests/operations/opkg.packages/remove_existing_package.json
 create mode 100644 tests/operations/opkg.packages/remove_existing_package_and_require_update.json
 create mode 100644 tests/operations/opkg.packages/remove_not_existing_package.json
 create mode 100644 tests/operations/opkg.packages/update_then_add_one.json
 create mode 100644 tests/operations/opkg.update/first_update.json
 create mode 100644 tests/operations/opkg.update/opkg_second_update_forced.json
 create mode 100644 tests/operations/opkg.update/second_update.json
 create mode 100644 tests/operations/opkg.update/second_update_with_force.json

diff --git a/pyinfra/facts/opkg.py b/pyinfra/facts/opkg.py
new file mode 100644
index 000000000..52eac9eda
--- /dev/null
+++ b/pyinfra/facts/opkg.py
@@ -0,0 +1,208 @@
+"""
+Gather the information provided by ``opkg`` on OpenWrt systems:
+    + ``opkg`` configuration
+    + feeds configuration
+    + list of installed packages
+    + list of packages with available upgrades
+
+
+    see https://openwrt.org/docs/guide-user/additional-software/opkg
+"""
+from __future__ import annotations
+
+import re
+from typing import NamedTuple
+
+from pyinfra import logger
+from pyinfra.api import FactBase
+from pyinfra.facts.util.packaging import parse_packages
+
+# TODO - change NamedTuple to dataclass but need to figure out how to get json serialization
+#        to work without changing core code
+
+
+class PkgUpgradeInfo(NamedTuple):
+    installed: str
+    available: str
+
+
+class ConfInfo(NamedTuple):
+    paths: dict[str, str]  # list of paths, e.g. {'root':'/', 'ram':'/tmp}
+    list_dir: str  # where package lists are stored, e.g. /var/opkg-lists
+    options: dict[str, str | bool]  # mapping from option to value, e.g. {'check_signature': True}
+    arch_cfg: dict[str, int]  # priorities for architectures
+
+
+class FeedInfo(NamedTuple):
+    url: str  # url for the feed
+    fmt: str  # format of the feed, e.g. "src/gz"
+    kind: str  # whether it comes from the 'distribution' or is 'custom'
+
+
+class Conf(FactBase):
+    """
+    Returns a NamedTuple with the current configuration:
+
+    .. code:: python
+
+        dest root /
+        dest ram /tmp
+        lists_dir ext /var/opkg-lists
+        option overlay_root /overlay
+        option check_signature
+
+    """
+
+    regex = re.compile(
+        r"""
+                       ^(?:\s*)
+                       (?:
+                       (?:arch\s+(?P<arch>\w+)\s+(?P<priority>\d+))|
+                       (?:dest\s+(?P<dest>\w+)\s+(?P<dest_path>[\w/\-]+))|
+                       (?:lists_dir\s+(?P<lists_dir>ext)\s+(?P<list_path>[\w/\-]+))|
+                       (?:option\s+(?P<option>\w+)(?:\s+(?P<value>[^#]+))?)
+                       )?
+                       (?:\s*\#.*)?
+                       $
+                       """,
+        re.X,
+    )
+    conf_file = "/etc/opkg.conf"
+    command = f"cat {conf_file}"
+    default = lambda x: ConfInfo({}, "", {}, {})  # noqa:
+
+    def process(self, output: list[str]):
+        dest, lists_dir, options, arch_cfg = {}, "", {}, {}
+        for line in output:
+            match = self.regex.match(line)
+
+            if match is None:
+                logger.warning(f"Opkg: could not parse opkg.conf line '{line}'")
+            elif match.group("arch") is not None:
+                arch_cfg[match.group("arch")] = int(match.group("priority"))
+            elif match.group("dest") is not None:
+                dest[match.group("dest")] = match.group("dest_path")
+            elif match.group("lists_dir") is not None:
+                lists_dir = match.group("list_path")
+            elif match.group("option") is not None:
+                options[match.group("option")] = match.group("value") or True
+
+        return ConfInfo(dest, lists_dir, options, arch_cfg)
+
+
+class Feeds(FactBase):
+    """
+        Returns a dictionary containing the information for the distribution-provided and
+        custom opkg feeds:
+
+        .. code:: python
+
+            {
+             'openwrt_base': FeedInfo(url='http://downloads ... /i386_pentium/base', fmt='src/gz', kind='distribution'),
+             'openwrt_core': FeedInfo(url='http://downloads ... /x86/geode/packages', fmt='src/gz', kind='distribution'),
+             'openwrt_luci': FeedInfo(url='http://downloads ... /i386_pentium/luci', fmt='src/gz', kind='distribution'),
+             'openwrt_packages': FeedInfo(url='http://downloads ... /i386_pentium/packages', fmt='src/gz', kind='distribution'),
+             'openwrt_routing': FeedInfo(url='http://downloads ... /i386_pentium/routing', fmt='src/gz', kind='distribution'),
+             'openwrt_telephony': FeedInfo(url='http://downloads ... /i386_pentium/telephony', fmt='src/gz', kind='distribution')
+            }
+    """
+
+    regex = re.compile(
+        r"^(CUSTOM)|(?:\s*(?P<fmt>[\w/]+)\s+(?P<name>[\w]+)\s+(?P<url>[\w./:]+))?(?:\s*#.*)?$"
+    )
+    command = "cat /etc/opkg/distfeeds.conf; echo CUSTOM; cat /etc/opkg/customfeeds.conf"
+    default = dict
+
+    def process(self, output: list[str]):
+        feeds, kind = {}, "distribution"
+        for line in output:
+            match = self.regex.match(line)
+
+            if match is None:
+                logger.warning(f"Opkg: could not parse /etc/opkg/*feeds.conf line '{line}'")
+            elif match.group(0) == "CUSTOM":
+                kind = "custom"
+            elif match.group("name") is not None:
+                feeds[match.group("name")] = FeedInfo(match.group("url"), match.group("fmt"), kind)
+
+        return feeds
+
+
+class InstallableArchitectures(FactBase):
+    """
+    Returns a dictionary containing the currently installable architectures for this system along
+    with their priority:
+
+    .. code:: python
+
+       {
+         'all': 1,
+         'i386_pentium': 10,
+         'noarch': 1
+        }
+    """
+
+    regex = re.compile(r"^(?:\s*arch\s+(?P<arch>[\w]+)\s+(?P<prio>\d+))?(\s*#.*)?$")
+    command = "/bin/opkg print-architecture"
+    default = dict
+
+    def process(self, output: list[str]):
+        arch_list = {}
+        for line in output:
+            match = self.regex.match(line)
+
+            if match is None:
+                logger.warning(f"could not parse arch line '{line}'")
+            elif match.group("arch") is not None:
+                arch_list[match.group("arch")] = int(match.group("prio"))
+
+        return arch_list
+
+
+class Packages(FactBase):
+    """
+    Returns a dict of installed opkg packages:
+
+    .. code:: python
+
+       {
+         'package_name': ['version'],
+         ...
+       }
+    """
+
+    command = "/bin/opkg list-installed"
+    regex = r"^([a-zA-Z0-9][\w\-\.]*)\s-\s([\w\-\.]+)"
+    default = dict
+
+    def process(self, output: list[str]):
+        return parse_packages(self.regex, sorted(output))
+
+
+class UpgradeablePackages(FactBase):
+    """
+    Returns a dict of installed and upgradable opkg packages:
+
+    .. code:: python
+
+        {
+          'package_name': (installed='1.2.3', available='1.2.8')
+          ...
+        }
+    """
+
+    command = "/bin/opkg list-upgradable"  # yes, really spelled that way
+    regex = re.compile(r"^([a-zA-Z0-9][\w\-.]*)\s-\s([\w\-.]+)\s-\s([\w\-.]+)")
+    default = dict
+    use_default_on_error = True
+
+    def process(self, output: list[str]):
+        result = {}
+        for line in output:
+            match = self.regex.match(line)
+            if match and len(match.groups()) == 3:
+                result[match.group(1)] = PkgUpgradeInfo(match.group(2), match.group(3))
+            else:
+                logger.warning(f"Opkg: could not list-upgradable line '{line}'")
+
+        return result
diff --git a/pyinfra/operations/opkg.py b/pyinfra/operations/opkg.py
new file mode 100644
index 000000000..a21d631e5
--- /dev/null
+++ b/pyinfra/operations/opkg.py
@@ -0,0 +1,95 @@
+"""
+    Manage packages on OpenWrt using opkg (see https://openwrt.org/docs/guide-user/additional-software/opkg)
+        + ``update`` - update local copy of package information
+        + ``packages`` -  install and remove packages
+
+    OpenWrt recommends against upgrading all packages  thus there is no ``opkg.upgrade`` function
+"""
+from __future__ import annotations
+
+from pyinfra import host
+from pyinfra.api import StringCommand, operation
+from pyinfra.facts.opkg import Packages
+from pyinfra.operations.util.packaging import ensure_packages
+
+EQUALS = "="
+UPDATE_ENTRY = "$$updated$$"  # use $ as not allowed in package names (TODO - need reference)
+
+
+@operation(is_idempotent=False)
+def update(force: bool = False):
+    """
+    Update the local opkg information.  Unless force is set, will only run
+    once per host per invocation of pyinfra.
+
+    + force - refresh the package list even if already done
+    """
+
+    if force or (UPDATE_ENTRY not in host.get_fact(Packages)):
+        host.get_fact(Packages).update({UPDATE_ENTRY: [UPDATE_ENTRY]})
+        yield StringCommand("opkg update > /dev/null 2>&1")
+    else:
+        host.noop("opkg packages already updated and not forced")
+
+
+_update = update
+
+
+@operation
+def packages(
+    packages: str | list[str] = "",
+    present: bool = True,
+    latest: bool = False,
+    update: bool = True,
+):
+    """
+    Add/remove/update opkg packages.
+
+    + packages: package or list of packages to that must/must not be present
+    + present: whether the package(s) should be installed (default True) or removed
+    + latest: whether to attempt to upgrade the specified package(s) (default False)
+    + update: run ``opkg update`` before installing packages (default True)
+
+    Not Supported:
+        Opkg does not support version pinning, i.e. ``<pkg>=<version>`` is not allowed
+        and will cause an exception.
+
+    **Examples:**
+
+    .. code:: python
+
+        # Ensure packages are installed∂ (will not force package upgrade)
+        opkg.packages(['asterisk', 'vim'], name="Install Asterisk and Vim")
+
+        # Install the latest versions of packages (always check)
+        opkg.packages(
+            'vim',
+            latest=True,
+            name="Ensure we have the latest version of Vim"
+        )
+    """
+    if str(packages) == "" or (
+        isinstance(packages, list) and (len(packages) < 1 or all(len(p) < 1 for p in packages))
+    ):
+        host.noop("empty or invalid package list provided to opkg.packages")
+        return
+
+    pkg_list = packages if isinstance(packages, list) else [packages]
+    have_equals = ",".join([pkg.split(EQUALS)[0] for pkg in pkg_list if EQUALS in pkg])
+    if len(have_equals) > 0:
+        raise ValueError(f"opkg does not support version pinning but found for: '{have_equals}'")
+
+    if update:
+        yield from _update()
+
+    yield from ensure_packages(
+        host,
+        pkg_list,
+        host.get_fact(Packages),
+        present,
+        install_command="opkg install",
+        upgrade_command="opkg upgrade",
+        uninstall_command="opkg remove",
+        latest=latest,
+        # lower=True, # FIXME - does ensure_packages always do this or ?
+    )
diff --git a/tests/facts/opkg.Conf/opkg_conf.json b/tests/facts/opkg.Conf/opkg_conf.json
new file mode 100644
index 000000000..fe5ff3001
--- /dev/null
+++ b/tests/facts/opkg.Conf/opkg_conf.json
@@ -0,0 +1,42 @@
+{
+    "command": "cat /etc/opkg.conf",
+    "output": [
+        "",
+        "# a comment",
+        "    # another comment",
+        "extra",
+        "dest root /",
+        "dest ram /tmp",
+        "lists_dir ext /var/opkg-lists",
+        "list_dir ext /var/foo/bar",
+        "list_dir zap /var/foo/bar",
+        "option",
+        "option overlay_root /overlay",
+        "option check_signature",
+        "option http_proxy http://username:password@proxy.example.org:8080/",
+        "option ftp_proxy http://username:password@proxy.example.org:2121/",
+        "arch all 1",
+        "arch noarch 2",
+        "arch brcm4716 200",
+        "arch brcm47xx 300  # generic has lower priority than specific",
+        "arch zzz"
+    ],
+    "fact": [
+        {
+            "root": "/",
+            "ram": "/tmp"
+        },
+        "/var/opkg-lists",
+        {
+            "overlay_root": "/overlay",
+            "check_signature": true,
+            "http_proxy": "http://username:password@proxy.example.org:8080/",
+            "ftp_proxy": "http://username:password@proxy.example.org:2121/"        },
+        {
+            "all": 1,
+            "noarch": 2,
+            "brcm4716": 200,
+            "brcm47xx": 300
+        }
+    ]
+}
diff --git a/tests/facts/opkg.Feeds/opkg_feeds.json b/tests/facts/opkg.Feeds/opkg_feeds.json
new file mode 100644
index 000000000..f3e4c0439
--- /dev/null
+++ b/tests/facts/opkg.Feeds/opkg_feeds.json
@@ -0,0 +1,51 @@
+{
+    "command": "cat /etc/opkg/distfeeds.conf; echo CUSTOM; cat /etc/opkg/customfeeds.conf",
+    "output": [
+        "",
+        "   # a different comment",
+        "aaa",
+        "src/gz",
+        "src/gz openwrt_core http://downloads.openwrt.org/releases/19.07.2/targets/x86/geode/packages",
+        "src/gz openwrt_base http://downloads.openwrt.org/releases/19.07.2/packages/i386_pentium/base",
+        "src/gz openwrt_luci http://downloads.openwrt.org/releases/19.07.2/packages/i386_pentium/luci",
+        "src/gz openwrt_packages http://downloads.openwrt.org/releases/19.07.2/packages/i386_pentium/packages",
+        "src/gz openwrt_routing http://downloads.openwrt.org/releases/19.07.2/packages/i386_pentium/routing",
+        "src/gz openwrt_telephony http://downloads.openwrt.org/releases/19.07.2/packages/i386_pentium/telephony",
+        "CUSTOM",
+        "# add your custom package feeds here",
+        "#",
+        "# src/gz example_feed_name http://www.example.com/path/to/files"
+    ],
+    "fact": {
+        "openwrt_core": [
+            "http://downloads.openwrt.org/releases/19.07.2/targets/x86/geode/packages",
+            "src/gz",
+            "distribution"
+        ],
+        "openwrt_base": [
+            "http://downloads.openwrt.org/releases/19.07.2/packages/i386_pentium/base",
+            "src/gz",
+            "distribution"
+        ],
+        "openwrt_luci": [
+            "http://downloads.openwrt.org/releases/19.07.2/packages/i386_pentium/luci",
+            "src/gz",
+            "distribution"
+        ],
+        "openwrt_packages": [
+            "http://downloads.openwrt.org/releases/19.07.2/packages/i386_pentium/packages",
+            "src/gz",
+            "distribution"
+        ],
+        "openwrt_routing": [
+            "http://downloads.openwrt.org/releases/19.07.2/packages/i386_pentium/routing",
+            "src/gz",
+            "distribution"
+        ],
+        "openwrt_telephony": [
+            "http://downloads.openwrt.org/releases/19.07.2/packages/i386_pentium/telephony",
+            "src/gz",
+            "distribution"
+        ]
+    }
+}
diff --git a/tests/facts/opkg.InstallableArchitectures/opkg_installable_architectures.json b/tests/facts/opkg.InstallableArchitectures/opkg_installable_architectures.json
new file mode 100644
index 000000000..08ce22866
--- /dev/null
+++ b/tests/facts/opkg.InstallableArchitectures/opkg_installable_architectures.json
@@ -0,0 +1,20 @@
+{
+    "command": "/bin/opkg print-architecture",
+    "output": [
+        "",
+        "# a comment to start",
+        "arch all 1",
+        "    # another comment",
+        "arch noarch 1",
+        "arch",
+        "arch thisarch",
+        "arch xray zulu",
+        "arch i386_pentium 10 # some sort of comment"
+    ],
+    "fact":
+        {
+            "all": 1,
+            "noarch": 1,
+            "i386_pentium": 10
+        }
+}
diff --git a/tests/facts/opkg.Packages/opkg_packages.json b/tests/facts/opkg.Packages/opkg_packages.json
new file mode 100644
index 000000000..17005738c
--- /dev/null
+++ b/tests/facts/opkg.Packages/opkg_packages.json
@@ -0,0 +1,39 @@
+{
+    "command": "/bin/opkg list-installed",
+    "output": [
+        "urandom-seed - 1.0-1",
+        "urngd - 2020-01-21-c7f7b6b6-1",
+        "usign - 2019-08-06-5a52b379-1",
+        "wget - 1.20.3-4",
+        "wget-nossl - 1.20.3-4",
+        "wireless-regdb - 2019.06.03",
+        "wpad-basic - 2019-08-08-ca8c2bd2-2",
+        "zlib - 1.2.11-3"
+    ],
+    "fact": {
+        "urandom-seed": [
+            "1.0-1"
+        ],
+        "urngd": [
+            "2020-01-21-c7f7b6b6-1"
+        ],
+        "usign": [
+            "2019-08-06-5a52b379-1"
+        ],
+        "wget": [
+            "1.20.3-4"
+        ],
+        "wget-nossl": [
+            "1.20.3-4"
+        ],
+        "wireless-regdb": [
+            "2019.06.03"
+        ],
+        "wpad-basic": [
+            "2019-08-08-ca8c2bd2-2"
+        ],
+        "zlib": [
+            "1.2.11-3"
+        ]
+    }
+}
diff --git a/tests/facts/opkg.UpgradeablePackages/opkg_upgradeable_packages.json b/tests/facts/opkg.UpgradeablePackages/opkg_upgradeable_packages.json
new file mode 100644
index 000000000..d5bec577d
--- /dev/null
+++ b/tests/facts/opkg.UpgradeablePackages/opkg_upgradeable_packages.json
@@ -0,0 +1,34 @@
+{
+    "command": "/bin/opkg list-upgradable",
+    "output": [
+        "",
+        "rpcd-mod-iwinfo - 2019-12-10-aaa08366-2 - 2020-05-26-67c8a3fd-1",
+        "luci-mod-network - git-20.115.52331-39a8290-1 - git-20.319.48994-50b7ab5-1",
+        "hostapd-common - 2019-08-08-ca8c2bd2-2 - 2019-08-08-ca8c2bd2-4",
+        "libuv1 - 1.34.2-1 - 1.40.0-1",
+        "xray123-123",
+        "wireless-regdb - 2019.06.03 - 2019.06.03-1"
+    ],
+    "fact": {
+        "rpcd-mod-iwinfo": [
+            "2019-12-10-aaa08366-2",
+            "2020-05-26-67c8a3fd-1"
+        ],
+        "luci-mod-network": [
+            "git-20.115.52331-39a8290-1",
+            "git-20.319.48994-50b7ab5-1"
+        ],
+        "hostapd-common": [
+            "2019-08-08-ca8c2bd2-2",
+            "2019-08-08-ca8c2bd2-4"
+        ],
+        "libuv1": [
+            "1.34.2-1",
+            "1.40.0-1"
+        ],
+        "wireless-regdb": [
+            "2019.06.03",
+            "2019.06.03-1"
+        ]
+    }
+}
diff --git a/tests/operations/opkg.packages/add_existing_package.json b/tests/operations/opkg.packages/add_existing_package.json
new file mode 100644
index 000000000..17c7e74e9
--- /dev/null
+++ b/tests/operations/opkg.packages/add_existing_package.json
@@ -0,0 +1,12 @@
+{
+    "args": ["curl"],
+    "kwargs": {
+        "update": false
+    },
+    "facts": {
+        "opkg.Packages": {"curl": ["7.66.0-2"]}
+    },
+    "commands": [
+    ],
+    "noop_description": "package curl is installed (7.66.0-2)"
+}
diff --git a/tests/operations/opkg.packages/add_multiple_packages.json b/tests/operations/opkg.packages/add_multiple_packages.json
new file mode 100644
index 000000000..520c06498
--- /dev/null
+++ b/tests/operations/opkg.packages/add_multiple_packages.json
@@ -0,0 +1,12 @@
+{
+    "args":[["curl", "wget"]],
+    "kwargs": {
+        "update": false
+    },
+    "facts": {
+        "opkg.Packages": {}
+    },
+    "commands": [
+        "opkg install curl wget"
+    ]
+}
diff --git a/tests/operations/opkg.packages/add_one_package.json b/tests/operations/opkg.packages/add_one_package.json
new file mode 100644
index 000000000..3f11acd6b
--- /dev/null
+++ b/tests/operations/opkg.packages/add_one_package.json
@@ -0,0 +1,12 @@
+{
+    "args": ["curl"],
+    "kwargs": {
+        "update": false
+    },
+    "facts": {
+        "opkg.Packages": {}
+    },
+    "commands": [
+        "opkg install curl"
+    ]
+}
diff --git a/tests/operations/opkg.packages/add_with_unallowed_pinning.json b/tests/operations/opkg.packages/add_with_unallowed_pinning.json
new file mode 100644
index 000000000..da91cecd4
--- /dev/null
+++ b/tests/operations/opkg.packages/add_with_unallowed_pinning.json
@@ -0,0 +1,11 @@
+{
+    "args": ["curl=7.66.0-2"],
+    "facts": {
+        "opkg.Packages": {}
+    },
+    "commands": [ ],
+    "exception": {
+        "name":"ValueError",
+        "message": "opkg does not support version pinning but found for: 'curl'"
+    }
+}
diff --git a/tests/operations/opkg.packages/list_of_nulls_package_list.json b/tests/operations/opkg.packages/list_of_nulls_package_list.json
new file mode 100644
index 000000000..ac63a624d
--- /dev/null
+++ b/tests/operations/opkg.packages/list_of_nulls_package_list.json
@@ -0,0 +1,9 @@
+{
+    "args": ["", "", ""],
+    "facts": {
+        "opkg.Packages": {}
+    },
+    "commands": [],
+    "noop_description": "empty or invalid package list provided to opkg.packages",
+    "logs": "foo"
+}
diff --git a/tests/operations/opkg.packages/null_package_list.json b/tests/operations/opkg.packages/null_package_list.json
new file mode 100644
index 000000000..42e795cac
--- /dev/null
+++ b/tests/operations/opkg.packages/null_package_list.json
@@ -0,0 +1,9 @@
+{
+    "args": [],
+    "facts": {
+        "opkg.Packages": {}
+    },
+    "commands": [],
+    "noop_description": "empty or invalid package list provided to opkg.packages",
+    "logs": "foo"
+}
diff --git a/tests/operations/opkg.packages/remove_existing_package.json b/tests/operations/opkg.packages/remove_existing_package.json
new file mode 100644
index 000000000..c56aee400
--- /dev/null
+++ b/tests/operations/opkg.packages/remove_existing_package.json
@@ -0,0 +1,13 @@
+{
+    "args": ["curl"],
+    "kwargs": {
+        "present": false,
+        "update": false
+    },
+    "facts": {
+        "opkg.Packages": {"curl": ["7.66.0-2"]}
+    },
+    "commands": [
+        "opkg remove curl"
+    ]
+}
diff --git a/tests/operations/opkg.packages/remove_existing_package_and_require_update.json b/tests/operations/opkg.packages/remove_existing_package_and_require_update.json
new file mode 100644
index 000000000..6b9ba3f80
--- /dev/null
+++ b/tests/operations/opkg.packages/remove_existing_package_and_require_update.json
@@ -0,0 +1,14 @@
+{
+    "args": ["curl"],
+    "kwargs": {
+        "present": false,
+        "update": true
+    },
+    "facts": {
+        "opkg.Packages": {"curl": ["7.66.0-2"]}
+    },
+    "commands": [
+        "opkg update > /dev/null 2>&1",
+        "opkg remove curl"
+    ]
+}
diff --git a/tests/operations/opkg.packages/remove_not_existing_package.json b/tests/operations/opkg.packages/remove_not_existing_package.json
new file mode 100644
index 000000000..cc783d2c1
--- /dev/null
+++ b/tests/operations/opkg.packages/remove_not_existing_package.json
@@ -0,0 +1,13 @@
+{
+    "args": ["curl"],
+    "kwargs": {
+        "present": false,
+        "update": false
+    },
+    "facts": {
+        "opkg.Packages": {}
+    },
+    "commands": [
+    ],
+    "noop_description": "package curl is not installed"
+}
diff --git a/tests/operations/opkg.packages/update_then_add_one.json b/tests/operations/opkg.packages/update_then_add_one.json
new file mode 100644
index 000000000..539e0725b
--- /dev/null
+++ b/tests/operations/opkg.packages/update_then_add_one.json
@@ -0,0 +1,11 @@
+{
+    "args": ["curl"],
+    "kwargs": {"update": true},
+    "facts": {
+        "opkg.Packages": {}
+    },
+    "commands": [
+        "opkg update > /dev/null 2>&1",
+        "opkg install curl"
+    ]
+}
diff --git a/tests/operations/opkg.update/first_update.json b/tests/operations/opkg.update/first_update.json
new file mode 100644
index 000000000..c4ece2ed1
--- /dev/null
+++ b/tests/operations/opkg.update/first_update.json
@@ -0,0 +1,9 @@
+{
+    "args": [],
+    "facts": {
+        "opkg.Packages": {}
+    },
+    "commands": [
+        "opkg update > /dev/null 2>&1"
+    ]
+}
diff --git a/tests/operations/opkg.update/opkg_second_update_forced.json b/tests/operations/opkg.update/opkg_second_update_forced.json
new file mode 100644
index 000000000..76bd6d894
--- /dev/null
+++ b/tests/operations/opkg.update/opkg_second_update_forced.json
@@ -0,0 +1,10 @@
+{
+    "args": [],
+    "kwargs": {"force": true},
+    "facts": {
+        "opkg.Packages": {"$$updated$$": ["$$updated$$"]}
+    },
+    "commands": [
+         "opkg update > /dev/null 2>&1"
+   ]
+}
diff --git a/tests/operations/opkg.update/second_update.json b/tests/operations/opkg.update/second_update.json
new file mode 100644
index 000000000..4cfa4a8bb
--- /dev/null
+++ b/tests/operations/opkg.update/second_update.json
@@ -0,0 +1,9 @@
+{
+    "args": [],
+    "facts": {
+        "opkg.Packages": {"$$updated$$": ["$$updated$$"]}
+    },
+    "commands": [
+    ],
+    "noop_description": "opkg packages already updated and not forced"
+}
diff --git a/tests/operations/opkg.update/second_update_with_force.json b/tests/operations/opkg.update/second_update_with_force.json
new file mode 100644
index 000000000..76bd6d894
--- /dev/null
+++ b/tests/operations/opkg.update/second_update_with_force.json
@@ -0,0 +1,10 @@
+{
+    "args": [],
+    "kwargs": {"force": true},
+    "facts": {
+        "opkg.Packages": {"$$updated$$": ["$$updated$$"]}
+    },
+    "commands": [
+         "opkg update > /dev/null 2>&1"
+   ]
+}
diff --git a/tests/words.txt b/tests/words.txt
index 39547ce27..7b4e23e70 100644
--- a/tests/words.txt
+++ b/tests/words.txt
@@ -162,6 +162,7 @@ graphlib
 greenlet
 greenlets
 groupname
+gz
 hacky
 hashability
 hklm
@@ -178,6 +179,7 @@ ignoretz
 ini
 initd
 initrd
+installable
 ip6tables
 ipdb
 iproute2
@@ -246,6 +248,7 @@ onerror
 openrc
 openstack
 openvz
+opkg
 osversion
 pacman
 paramiko
@@ -371,6 +374,7 @@ unignored
 unmount
 up
 up2
+upgradeable
 useradd
 utf16
 v

From c708ae484d3c17285a48a13e1227e9bc045e9252 Mon Sep 17 00:00:00 2001
From: James Watt <james@bevjam.com>
Date: Thu, 4 Jan 2024 17:28:36 -0500
Subject: [PATCH 2/4] fix: clean up formatting and remove type annotations

---
 pyinfra/facts/opkg.py      | 36 ++++++++++++++++++------------------
 pyinfra/operations/opkg.py |  3 ++-
 2 files changed, 20 insertions(+), 19 deletions(-)

diff --git a/pyinfra/facts/opkg.py b/pyinfra/facts/opkg.py
index 52eac9eda..418c9e6f4 100644
--- a/pyinfra/facts/opkg.py
+++ b/pyinfra/facts/opkg.py
@@ -71,7 +71,7 @@ class Conf(FactBase):
     command = f"cat {conf_file}"
     default = lambda x: ConfInfo({}, "", {}, {})  # noqa:
 
-    def process(self, output: list[str]):
+    def process(self, output):
         dest, lists_dir, options, arch_cfg = {}, "", {}, {}
         for line in output:
             match = self.regex.match(line)
@@ -92,19 +92,19 @@ def process(self, output: list[str]):
 
 class Feeds(FactBase):
     """
-        Returns a dictionary containing the information for the distribution-provided and
-        custom opkg feeds:
-
-        .. code:: python
-
-            {
-             'openwrt_base': FeedInfo(url='http://downloads ... /i386_pentium/base', fmt='src/gz', kind='distribution'),
-             'openwrt_core': FeedInfo(url='http://downloads ... /x86/geode/packages', fmt='src/gz', kind='distribution'),
-             'openwrt_luci': FeedInfo(url='http://downloads ... /i386_pentium/luci', fmt='src/gz', kind='distribution'),
-             'openwrt_packages': FeedInfo(url='http://downloads ... /i386_pentium/packages', fmt='src/gz', kind='distribution'),
-             'openwrt_routing': FeedInfo(url='http://downloads ... /i386_pentium/routing', fmt='src/gz', kind='distribution'),
-             'openwrt_telephony': FeedInfo(url='http://downloads ... /i386_pentium/telephony', fmt='src/gz', kind='distribution')
-            }
+    Returns a dictionary containing the information for the distribution-provided and
+    custom opkg feeds:
+
+    .. code:: python
+
+        {
+         'openwrt_base': FeedInfo(url='http://downloads ... /i386_pentium/base', fmt='src/gz', kind='distribution'), # noqa: E501
+         'openwrt_core': FeedInfo(url='http://downloads ... /x86/geode/packages', fmt='src/gz', kind='distribution'), # noqa: E501
+         'openwrt_luci': FeedInfo(url='http://downloads ... /i386_pentium/luci', fmt='src/gz', kind='distribution'),# noqa: E501
+         'openwrt_packages': FeedInfo(url='http://downloads ... /i386_pentium/packages', fmt='src/gz', kind='distribution'),# noqa: E501
+         'openwrt_routing': FeedInfo(url='http://downloads ... /i386_pentium/routing', fmt='src/gz', kind='distribution'),# noqa: E501
+         'openwrt_telephony': FeedInfo(url='http://downloads ... /i386_pentium/telephony', fmt='src/gz', kind='distribution') # noqa: E501
+        }
     """
 
     regex = re.compile(
@@ -113,7 +113,7 @@ class Feeds(FactBase):
     command = "cat /etc/opkg/distfeeds.conf; echo CUSTOM; cat /etc/opkg/customfeeds.conf"
     default = dict
 
-    def process(self, output: list[str]):
+    def process(self, output):
         feeds, kind = {}, "distribution"
         for line in output:
             match = self.regex.match(line)
@@ -146,7 +146,7 @@ class InstallableArchitectures(FactBase):
     command = "/bin/opkg print-architecture"
     default = dict
 
-    def process(self, output: list[str]):
+    def process(self, output):
         arch_list = {}
         for line in output:
             match = self.regex.match(line)
@@ -175,7 +175,7 @@ class Packages(FactBase):
     regex = r"^([a-zA-Z0-9][\w\-\.]*)\s-\s([\w\-\.]+)"
     default = dict
 
-    def process(self, output: list[str]):
+    def process(self, output):
         return parse_packages(self.regex, sorted(output))
 
 
@@ -196,7 +196,7 @@ class UpgradeablePackages(FactBase):
     default = dict
     use_default_on_error = True
 
-    def process(self, output: list[str]):
+    def process(self, output):
         result = {}
         for line in output:
             match = self.regex.match(line)
diff --git a/pyinfra/operations/opkg.py b/pyinfra/operations/opkg.py
index a21d631e5..03dae7685 100644
--- a/pyinfra/operations/opkg.py
+++ b/pyinfra/operations/opkg.py
@@ -1,8 +1,9 @@
 """
-    Manage packages on OpenWrt using opkg (see https://openwrt.org/docs/guide-user/additional-software/opkg)
+    Manage packages on OpenWrt using opkg
         + ``update`` - update local copy of package information
         + ``packages`` -  install and remove packages
 
+    see https://openwrt.org/docs/guide-user/additional-software/opkg
     OpenWrt recommends against upgrading all packages  thus there is no ``opkg.upgrade`` function
 """
 from __future__ import annotations

From a5268cb1aba62fa92c9d3eb344b5c964dad02c47 Mon Sep 17 00:00:00 2001
From: James Watt <james@bevjam.com>
Date: Thu, 4 Jan 2024 17:41:03 -0500
Subject: [PATCH 3/4] fix: correct documentation for opkg.Conf

---
 pyinfra/facts/opkg.py | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/pyinfra/facts/opkg.py b/pyinfra/facts/opkg.py
index 418c9e6f4..6755796fc 100644
--- a/pyinfra/facts/opkg.py
+++ b/pyinfra/facts/opkg.py
@@ -45,11 +45,21 @@ class Conf(FactBase):
 
     .. code:: python
 
-        dest root /
-        dest ram /tmp
-        lists_dir ext /var/opkg-lists
-        option overlay_root /overlay
-        option check_signature
+        ConfInfo(
+            paths = {
+                "root": "/",
+                "ram": "/tmp",
+            },
+            list_dir = "/opt/opkg-lists",
+            options = {
+                "overlay_root": "/overlay"
+            },
+            arch_cfg = {
+                "all": 1,
+                "noarch": 1,
+                "i386_pentium": 10
+            }
+        )
 
     """
 

From ea7eefd9836564c0cad9f2bf2e5ea01b89ef8906 Mon Sep 17 00:00:00 2001
From: James Watt <james@bevjam.com>
Date: Thu, 4 Jan 2024 17:47:35 -0500
Subject: [PATCH 4/4] fix: remove import of __annotations__ and use older style
 type definitions

---
 pyinfra/facts/opkg.py      | 12 ++++++------
 pyinfra/operations/opkg.py |  4 ++--
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/pyinfra/facts/opkg.py b/pyinfra/facts/opkg.py
index 6755796fc..0c6594dfe 100644
--- a/pyinfra/facts/opkg.py
+++ b/pyinfra/facts/opkg.py
@@ -8,10 +8,8 @@
 
     see https://openwrt.org/docs/guide-user/additional-software/opkg
 """
-from __future__ import annotations
-
 import re
-from typing import NamedTuple
+from typing import Dict, NamedTuple, Union
 
 from pyinfra import logger
 from pyinfra.api import FactBase
@@ -27,10 +25,12 @@ class PkgUpgradeInfo(NamedTuple):
 
 
 class ConfInfo(NamedTuple):
-    paths: dict[str, str]  # list of paths, e.g. {'root':'/', 'ram':'/tmp}
+    paths: Dict[str, str]  # list of paths, e.g. {'root':'/', 'ram':'/tmp}
     list_dir: str  # where package lists are stored, e.g. /var/opkg-lists
-    options: dict[str, str | bool]  # mapping from option to value, e.g. {'check_signature': True}
-    arch_cfg: dict[str, int]  # priorities for architectures
+    options: Dict[
+        str, Union[str, bool]
+    ]  # mapping from option to value, e.g. {'check_signature': True}
+    arch_cfg: Dict[str, int]  # priorities for architectures
 
 
 class FeedInfo(NamedTuple):
diff --git a/pyinfra/operations/opkg.py b/pyinfra/operations/opkg.py
index 03dae7685..d60ed7f3c 100644
--- a/pyinfra/operations/opkg.py
+++ b/pyinfra/operations/opkg.py
@@ -6,7 +6,7 @@
     see https://openwrt.org/docs/guide-user/additional-software/opkg
     OpenWrt recommends against upgrading all packages  thus there is no ``opkg.upgrade`` function
 """
-from __future__ import annotations
+from typing import List, Union
 
 from pyinfra import host
 from pyinfra.api import StringCommand, operation
@@ -38,7 +38,7 @@ def update(force: bool = False):
 
 @operation
 def packages(
-    packages: str | list[str] = "",
+    packages: Union[str, List[str]] = "",
     present: bool = True,
     latest: bool = False,
     update: bool = True,