📦 Packets – Custom Package Manager for Linux

A fast and minimal package manager written in Go with Lua hooks, local network discovery, and SQLite-based indexing.

---

📘 Overview

Packets is a lightweight package manager for Linux, written in Go. It supports:

• Installation and removal of packages
• Dependency resolution and upgrading
• .tar.zst compressed packages with manifest.toml metadata
• Lua-based install/remove hooks
• Local cache with SHA-256 validation
• Peer-to-peer discovery over LAN
• Remote package syncing via HTTP
• SQLite-based local database

---

📁 Directory Structure

Path	Description
/etc/packets/	Configuration files
/opt/packets/	Installed package data
/var/cache/packets/	Cached .tar.zst package files

(This can be changed in /etc/packets/config.toml)

---

Available Commands

Command	Description
packets install <name>	Install a package (resolves dependencies, executes Lua install hook)
packets remove <name>	Remove a package (executes Lua remove hook)
packets upgrade <name>	Upgrade a package by checking family and serial in the manifest
packets sync [url]	Synchronize index.db from remote HTTP source
packets serve init/stop	Starts and stop the LAN service daemon
packets list	List all installed packages

📦 Package Format

Packages must be compressed as .tar.zst and include:

• ├── manifest.toml # Package metadata
• ├── data/ # Files to install
• ├── install.lua # Lua install hook
• └── remove.lua # Lua remove hook

Example manifest.toml

[Info]
 name = "packets"
 version = "1.0.0"
 description = "offline and online packetmanager"
 dependencies = []
 author = "robo"
 family = "1f84ca15-5077-4f1d-a370-0ec860766eb2"
 serial = 0

[Hooks]
 install = "install.lua"
 remove = "remove.lua"

--

🔄 Installation Process

• Check if package is already cached and validated via SHA-256.

• If not, search the package:

  Via LAN: Sends UDP broadcast (Q:filename) to peers.

  Via HTTP: Downloads from configured mirrors.

  Decompress .tar.zst, install files.

  Execute Lua install hook.

🧩 Core Features

✅ Dependency Resolution

Installs required dependencies listed in the manifest.

🌐 LAN Discovery

Broadcasts package request to devices in the same network via UDP.

📡 Remote Download

Downloads package via HTTP if not found on LAN.

🔒 Security

SHA-256 checksum validation

Path validation to avoid exploits (..)

Safe, sandboxed Lua runtime with limited API

🌍 Global Variables Available in Lua Scripts

During the execution of install.lua and remove.lua hooks, some global variables are automatically provided to the Lua environment. These help simplify file path handling and access to package-specific directories.

Available variables:

Name	Type	Description
packets_package_dir	string	Absolute path to the package's data directory (e.g., /opt/packets/...)
packets_bin_dir	string	Path where executables should be installed (e.g., /usr/bin)
script	string	Path to the currently executing script (e.g., "install.lua")
data_dir	string	Path to the /data folder of the current package

Example usage in Lua:

    print("Installing into: " .. packets_bin_dir)
    print("Package data in: " .. data_dir)

    -- Copy a binary to /usr/bin
    os.copy(path_join(data_dir, "htop"), path_join(packets_bin_dir, "htop"))

These variables are preloaded in the Lua environment—no need to manually declare or initialize them.

🛠️ Allowed Lua API (install/remove hooks)

To ensure security, only a limited set of safe functions are exposed in Lua hooks:

os.remove(path)
os.rename(old, new)
os.copy(source, target)
os.symlink(source, target)
io.open(path, mode)
path_join(...)  -- Safely join path segments

Note: Dangerous functions like os.execute, os.getenv, etc. are removed.

🗃️ Databases

index.db: Available packages (after sync)

installed.db: Packages currently installed

⚠️ Restrictions & Notes

Linux only (//go:build linux)

Root permissions required for most commands

Changing dataDir triggers prompt to migrate installed packages

Binaries in binDir are not automatically moved if path changes

Do not manually edit lastDataDir