Skip to content

Home

Jump to bottom
Joyal George K J edited this page Jun 29, 2026 · 2 revisions

This wiki provides a technical breakdown of how Labeled-CLI operates under the hood, how arguments are routed, and how the state engine avoids redundancy.

Architecture Overview

Labeled-CLI is a local-first, performance-optimized CLI engine designed to manage targeted system configuration blocks across multiple package managers natively. Instead of introducing a custom virtualization layer or heavy tracking configurations, Labeled-CLI acts as a surgical wrapper around your host system's native package manager binaries (dnf, apt, pacman).

Core Storage Schema: tracking.json

To prevent data bloat and structural redundancy over time, Labeled-CLI organizes records using a relational hierarchy instead of flat key-value pairs.

Packages are grouped dynamically by the underlying package manager and their explicit installation status. This keeps the state file highly compressed and scalable.

{
  "dev-env": {
    "dnf": {
      "tracked": ["ncdu", "tmux"],
      "timestamp": "2026-06-24 01:25:00",
      "skipped": ["vhs"]
    },
    "flatpak": {
      "timestamp": "2026-06-24 01:25:00",
      "tracked": ["slack"]
    }
  }
}

State Blocks Deconstructed:

  • created: The absolute timestamp indicating when the specific environment label block was first initialized.
  • tracked: An array of string package names that did not exist on the machine prior to execution. These are owned directly by the label and will be cleanly uninstalled during a purge request.
  • skipped: Core utilities or daily drivers that were already present on the host system when the installation loop ran. Labeled-CLI records their footprint for environment visibility but protects them from accidental deletion during down-stream purging loops.

Command Lifecycle and Argument Pipeline

Every invocation of a labeled command passes through a structured four-stage runtime execution pipeline.

1. Token Slicing and Flag Sanitization

The system passes process.argv directly to an explicit allowed-list argument parser. The parser compares command elements against hardcoded valid flag constraints (--verbose, -y, etc.).

If a token is found in the list, it is separated into a flags array. Everything else is parsed strictly by order as command, label, and packages. This ensures that execution configurations can be declared anywhere in the string without polluting package names.

2. State and Binary Validation

Before executing package actions, the tool verifies:

  • The host environment's default native package manager.
  • The explicit existence of the target environment profile inside tracking.json (for untrack and remove commands).

3. Sequential Isolation Loop

When executing installations, Labeled-CLI processes packages sequentially. Before triggering the installer, it queries the local package tree using non-destructive exit-status checks (such as dnf list --installed or pacman -Q).

This pre-check accurately isolates the condition of each package (New, Pre-existing, or Needs Update) before passing execution controls to the native shell stream.

4. Cascading State Pruning

During untrack or remove actions, mutations are applied to the local state file. To prevent file size creep from dead metadata branches, the engine runs a cascading safety cleanup:

  • If a package manager block loses all package array references, the manager key is deleted.
  • If a label block loses all active package manager fields, the parent label schema is completely scrubbed from tracking.json.

CLI Command Specification

install

labeled install <label> <packages...>
  • Behavior: Evaluates package existence, prompts the user for validation up front, handles sequential native installation streams, and commits tracked/skipped arrays directly to storage.

untrack

labeled untrack <label> <packages...>
  • Behavior: Removes a package record from the specified label's tracking index without altering the physical system binary. Useful for manually severing configuration ties.

remove

labeled remove <label>
  • Behavior: Queries the specific label profile inside tracking.json, extracts the items stored within the tracked arrays for the active package managers, executes a unified system deletion, and prunes the storage schema block.

list

labeled list
  • Behavior: Renders a comprehensive tree-table matrix layout within the terminal interface, organizing environment profiles cleanly while explicitly mapping [TRACKED] and [SKIPPED] components.

More can be found in Repo Readme

Clone this wiki locally