Metadata-Version: 2.4
Name: machine-root
Version: 0.1.0
Summary: A minimal shared registry for locating resources on a local machine
Project-URL: Homepage, https://github.com/LionKimbro/machine-root
Project-URL: Repository, https://github.com/LionKimbro/machine-root
Author: Lion Kimbro
License: CC0-1.0
License-File: LICENSE
Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# machine-root

## The Problem

Programs, scripts, and AIs that run on a machine often need to locate resources - a project folder, a service registry, a configuration file. The usual solutions are fragile: hard-coded paths break when things move, environment variables require manual setup, and configuration systems are overkill for something this simple.

## The System

Machine Root is a minimal, shared registry for a local machine. It is a single JSON file - `machine-root.json` - that maps string keys to locations (typically filesystem paths):

```json
{
  "zoo.projects": "C:/lion/zoo/projects",
  "filetalk.registry": "C:/lion/filetalk/service-registry.json",
  "librarian.main": "C:/lion/librarian/registry.json"
}
```

Any program that knows the convention can read from the same registry. Keys are stable names; values are locations that can change. No metadata, no nesting, no configuration framework required.

### Resolution Order

When looking for `machine-root.json`, the system checks these locations in order and uses the first one found:

1. The path in the `MACHINE_ROOT` environment variable (if set and the file exists)
2. `./machine-root.json` (current working directory)
3. `~/machine-root.json` (user home directory)
4. Machine-level: `C:/machine-root.json` (Windows) or `/etc/machine-root.json` (Linux)

If none are found, operations fail clearly.

---

## The Package

`machine-root` is a Python package that implements the Machine Root system. It provides a minimal API and a command-line tool for reading and writing the registry.

### Install

```
pip install machine-root
```

### Python API

```python
import machineroot

machineroot.locate()           # path to the active machine-root.json
machineroot.keys()             # list all keys
machineroot.get("zoo.projects")           # get a value
machineroot.set("zoo.projects", "C:/lion/zoo/projects")  # set a value
machineroot.delete("zoo.projects")        # delete a key
```

Errors:

- `MachineRootNotFoundError` - no `machine-root.json` could be found
- `MachineRootKeyError` - the requested key does not exist

### CLI

```
machine-root create
machine-root set zoo.projects C:/lion/zoo/projects
machine-root get zoo.projects
machine-root delete zoo.projects
machine-root keys
machine-root locate
machine-root help
```

The registry file must be created explicitly with `machine-root create`, which places it in the user's home directory. All other commands fail if the file does not exist.

---

## License

CC0-1.0 - public domain.
