machine-root 0.1.0__py3-none-any.whl

machine_root-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+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.

machine_root-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+machineroot/__init__.py,sha256=9iMItU6DcDiSs1W8NgeGDuecXMPYe0z1XMaECFsi6kQ,720
+machineroot/__main__.py,sha256=onRzIo8JvsuiAZNN9Y-jWC07NJbs5RarUCywvPu_fL8,3625
+machineroot/_exceptions.py,sha256=F3_MyAp_6KP5krcDxlXTaFRSusUWdkRLbVmBLAO7_jQ,181
+machineroot/_resolve.py,sha256=z4yZQelGTDw1hXciKikDRWTzg3UM02sfsyL-87dgjtk,1163
+machine_root-0.1.0.dist-info/METADATA,sha256=kfXfC_6x59z90jhqkeykEA2NggRLXQ7trADgYTmBBps,3084
+machine_root-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+machine_root-0.1.0.dist-info/entry_points.txt,sha256=I0gmRNltiMgr6aSGfaaSLi-EtcNG7WtONtDw7XXtX0M,59
+machine_root-0.1.0.dist-info/licenses/LICENSE,sha256=J3cutLOIV6T_qvfoxvKVoFemyzMQtnMARm5jpL5TYI4,335
+machine_root-0.1.0.dist-info/RECORD,,

machine_root-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

machine_root-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+machine-root = machineroot.__main__:main

machine_root-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+CC0 1.0 Universal
+
+This work is dedicated to the public domain under the Creative Commons CC0 1.0
+Universal Public Domain Dedication.
+
+To the extent possible under law, the author(s) have waived all copyright and
+related or neighboring rights to this work.
+
+See https://creativecommons.org/publicdomain/zero/1.0/ for details.

machineroot/__init__.py

@@ -0,0 +1,32 @@
+from ._exceptions import MachineRootError, MachineRootNotFoundError, MachineRootKeyError
+from ._resolve import locate as _locate_path, read_registry, write_registry
+
+
+def locate():
+    return str(_locate_path())
+
+
+def get(key):
+    data, _ = read_registry()
+    if key not in data:
+        raise MachineRootKeyError(key)
+    return data[key]
+
+
+def set(key, value):
+    data, path = read_registry()
+    data[key] = value
+    write_registry(data, path)
+
+
+def keys():
+    data, _ = read_registry()
+    return list(data.keys())
+
+
+def delete(key):
+    data, path = read_registry()
+    if key not in data:
+        raise MachineRootKeyError(key)
+    del data[key]
+    write_registry(data, path)

machineroot/__main__.py

@@ -0,0 +1,144 @@
+import pathlib
+import sys
+
+import machineroot
+from machineroot._exceptions import MachineRootError, MachineRootNotFoundError
+from machineroot._resolve import kFILENAME, locate as _locate_path
+
+
+kHELP = """\
+machine-root — locate and manage the machine-root.json registry
+
+USAGE
+  machine-root <command> [arguments]
+
+COMMANDS
+  create
+      Create an empty machine-root.json file in the user's home directory.
+      Fails if the file already exists.
+
+  get <key>
+      Print the value associated with <key>.
+      Fails if the registry file or key does not exist.
+
+  set <key> <value>
+      Set or update the value for <key>.
+      Fails if the registry file does not exist.
+
+  delete <key>
+      Delete the entry for <key>.
+      Fails if the registry file or key does not exist.
+
+  keys
+      List all keys in the registry.
+      Fails if the registry file does not exist.
+
+  locate
+      Print the path to the active machine-root.json file.
+      Fails if no registry file can be found.
+
+  help
+      Show this help message.
+
+RESOLUTION ORDER
+  1. MACHINE_ROOT environment variable
+  2. ./machine-root.json
+  3. ~/machine-root.json
+  4. Machine-level file
+     - Windows: C:/machine-root.json
+     - Linux:   /etc/machine-root.json
+
+EXAMPLES
+  machine-root create
+  machine-root set zoo.projects C:/lion/zoo/projects
+  machine-root get zoo.projects
+  machine-root keys
+  machine-root locate
+
+NOTES
+  - The registry file must be created explicitly using 'machine-root create'.
+  - All commands fail if the registry file is not found.
+  - Keys are simple strings; values are typically filesystem paths.
+"""
+
+
+def run_create():
+    path = pathlib.Path.home() / kFILENAME
+    if path.exists():
+        print(f"error: {path} already exists.", file=sys.stderr)
+        sys.exit(1)
+    import json
+    tmp = pathlib.Path(str(path) + ".tmp")
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump({}, f, indent=2)
+        f.write("\n")
+    tmp.replace(path)
+    print(f"Created {path}")
+
+
+def run_get(key):
+    print(machineroot.get(key))
+
+
+def run_set(key, value):
+    machineroot.set(key, value)
+
+
+def run_delete(key):
+    machineroot.delete(key)
+
+
+def run_keys():
+    for k in machineroot.keys():
+        print(k)
+
+
+def run_locate():
+    print(machineroot.locate())
+
+
+def run_help():
+    print(kHELP, end="")
+
+
+def main():
+    args = sys.argv[1:]
+
+    if not args or args[0] == "help":
+        run_help()
+        return
+
+    cmd = args[0]
+
+    try:
+        if cmd == "create":
+            run_create()
+        elif cmd == "get":
+            if len(args) < 2:
+                print("error: get requires a key.", file=sys.stderr)
+                sys.exit(1)
+            run_get(args[1])
+        elif cmd == "set":
+            if len(args) < 3:
+                print("error: set requires a key and a value.", file=sys.stderr)
+                sys.exit(1)
+            run_set(args[1], args[2])
+        elif cmd == "delete":
+            if len(args) < 2:
+                print("error: delete requires a key.", file=sys.stderr)
+                sys.exit(1)
+            run_delete(args[1])
+        elif cmd == "keys":
+            run_keys()
+        elif cmd == "locate":
+            run_locate()
+        else:
+            print(f"error: unknown command '{cmd}'. Run 'machine-root help' for usage.", file=sys.stderr)
+            sys.exit(1)
+    except MachineRootError as e:
+        print(f"error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

machineroot/_exceptions.py

@@ -0,0 +1,10 @@
+class MachineRootError(Exception):
+    pass
+
+
+class MachineRootNotFoundError(MachineRootError):
+    pass
+
+
+class MachineRootKeyError(MachineRootError, KeyError):
+    pass

machineroot/_resolve.py

@@ -0,0 +1,51 @@
+import json
+import os
+import pathlib
+
+from ._exceptions import MachineRootNotFoundError
+
+
+kFILENAME = "machine-root.json"
+
+
+def locate():
+    # 1. MACHINE_ROOT environment variable
+    env = os.environ.get("MACHINE_ROOT")
+    if env:
+        p = pathlib.Path(env)
+        if p.exists():
+            return p
+
+    # 2. Current working directory
+    p = pathlib.Path.cwd() / kFILENAME
+    if p.exists():
+        return p
+
+    # 3. User home directory
+    p = pathlib.Path.home() / kFILENAME
+    if p.exists():
+        return p
+
+    # 4. Machine-level
+    if os.name == "nt":
+        p = pathlib.Path("C:/") / kFILENAME
+    else:
+        p = pathlib.Path("/etc") / kFILENAME
+    if p.exists():
+        return p
+
+    raise MachineRootNotFoundError("No machine-root.json file could be found.")
+
+
+def read_registry():
+    p = locate()
+    with open(p, "r", encoding="utf-8") as f:
+        return json.load(f), p
+
+
+def write_registry(data, path):
+    tmp = pathlib.Path(str(path) + ".tmp")
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+    tmp.replace(path)