machine-root 0.1.0__tar.gz

machine_root-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+venv/
+.venv/
+.local/
+.claude/
+.focus-explorer/
+.pycard/
+.zookeep/
+zookeeper-report.json

machine_root-0.1.0/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.

machine_root-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,79 @@
+# 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/docs/raw/0000__machine-root.json

@@ -0,0 +1,58 @@
+{
+  "document": {
+    "document-id": "machine-root.system.spec.v1",
+    "title": "Machine Root System Specification",
+    "tags": ["machineroot", "registry", "discovery", "system"],
+    "purpose": "Define a minimal system for locating named resources on a local machine.",
+    "conversation": "https://chatgpt.com/c/69c409a1-22e4-83e8-af6d-3272197ee231"
+  },
+
+  "vision": [
+    "Provide a single, simple way for programs, scripts, and AIs to locate important resources on a machine.",
+    "Avoid complex configuration systems by using a single JSON file with direct key-to-location mappings.",
+    "Enable systems to interoperate by agreeing on shared names for important locations."
+  ],
+
+  "format": [
+    "The machine root file is a JSON object.",
+    "Each key is a string identifier.",
+    "Each value is a string representing a location (typically a filesystem path).",
+    "No additional structure is required.",
+    "The machine root file is named 'machine-root.json'."
+  ],
+
+  "example": {
+    "zoo.projects": "C:/lion/zoo/projects",
+    "filetalk.registry": "C:/lion/filetalk/service-registry.json",
+    "librarian.main": "C:/lion/librarian/registry.json"
+  },
+
+  "resolution-process": {
+    "description": "The system resolves the machine root file by checking candidate locations in order.  The first existing file found is used.",
+    "order": [
+      "If the MACHINE_ROOT environment variable is set and the referenced file exists, use it.",
+      "If a file named 'machine-root.json' exists in the current working directory, use it.",
+      "If a file named 'machine-root.json' exists in the user's home directory, use it.",
+      "If a file named 'machine-root.json' exists at the machine level, use it.",
+      "If none are found, resolution fails and the system should report that no machine root file is available."
+    ],
+    "platform-notes": {
+      "windows": [
+        "User home directory is typically C:/Users/<username>/.",
+        "Machine-level path is typically C:/machine-root.json."
+      ],
+      "linux": [
+        "User home directory is typically /home/<username>/ or as defined by $HOME.",
+        "Machine-level path is typically /etc/machine-root.json."
+      ]
+    }
+  },
+
+  "principles": [
+    "Keep the format minimal and easy to parse.",
+    "Prefer stable names (keys) and allow locations (values) to change.",
+    "Do not embed metadata; use other files for richer descriptions.",
+    "Allow layering via resolution order (environment, local, user, machine).",
+    "Ensure the system is usable by both humans and simple programs."
+  ]
+}

machine_root-0.1.0/docs/raw/0001__machineroot-package.json

@@ -0,0 +1,124 @@
+{
+  "document": {
+    "document-id": "machine-root.package.description.v1",
+    "title": "MachineRoot Python Package Description",
+    "tags": ["machineroot", "python", "registry", "cli", "api"],
+    "purpose": "Describe the Python package and CLI interface for interacting with the Machine Root system."
+  },
+
+  "overview": [
+    "The machineroot package provides a minimal interface for locating and interacting with the machine-root.json registry.",
+    "It supports both a Python API and a command-line interface.",
+    "The package enables programs, scripts, and AIs to resolve named resources on a machine using a shared registry."
+  ],
+
+  "python-api": {
+    "description": "The Python API provides simple functions for resolving and modifying machine root entries.",
+    "functions": {
+      "get": {
+        "signature": "machineroot.get(key: str) -> str",
+        "description": "Return the value associated with the given key.",
+        "errors": [
+          "Raises MachineRootNotFoundError if no machine-root.json file can be resolved.",
+          "Raises MachineRootKeyError if the key does not exist."
+        ]
+      },
+      "set": {
+        "signature": "machineroot.set(key: str, value: str) -> None",
+        "description": "Set or update the value for the given key in the active machine root file.",
+        "errors": [
+          "Raises MachineRootNotFoundError if no machine-root.json file can be resolved."
+        ]
+      },
+      "delete": {
+        "signature": "machineroot.delete(key: str) -> None",
+        "description": "Delete the entry for the given key from the active machine root file.",
+        "errors": [
+          "Raises MachineRootNotFoundError if no machine-root.json file can be resolved.",
+          "Raises MachineRootKeyError if the key does not exist."
+        ]
+      },
+      "keys": {
+        "signature": "machineroot.keys() -> List[str]",
+        "description": "Return a list of all keys in the active machine root file.",
+        "errors": [
+          "Raises MachineRootNotFoundError if no machine-root.json file can be resolved."
+        ]
+      },
+      "locate": {
+        "signature": "machineroot.locate() -> str",
+        "description": "Return the path to the machine-root.json file currently in use.",
+        "errors": [
+          "Raises MachineRootNotFoundError if no machine-root.json file can be resolved."
+        ]
+      }
+    },
+
+    "exceptions": {
+      "MachineRootError": {
+        "description": "Base exception for all MachineRoot-related errors."
+      },
+      "MachineRootNotFoundError": {
+        "base": "MachineRootError",
+        "description": "Raised when no machine-root.json file can be found."
+      },
+      "MachineRootKeyError": {
+        "base": "KeyError",
+        "description": "Raised when a key is not present in the machine-root.json file."
+      }
+    }
+  },
+
+  "cli": {
+    "description": "The package installs a command-line tool named 'machine-root'.",
+    "commands": {
+      "create": {
+        "usage": "machine-root create",
+        "description": "Create an empty machine-root.json file in the user's home directory. Fails if the file already exists."
+      },
+      "get": {
+        "usage": "machine-root get <key>",
+        "description": "Print the value associated with the given key. Fails if the file or key does not exist."
+      },
+      "set": {
+        "usage": "machine-root set <key> <value>",
+        "description": "Set or update the value for the given key. Fails if the file does not exist."
+      },
+      "delete": {
+        "usage": "machine-root delete <key>",
+        "description": "Delete the entry for the given key. Fails if the file or key does not exist."
+      },
+      "keys": {
+        "usage": "machine-root keys",
+        "description": "List all keys in the active machine root file. Fails if the file does not exist."
+      },
+      "locate": {
+        "usage": "machine-root locate",
+        "description": "Print the path to the machine-root.json file currently in use. Fails if no file exists."
+      },
+      "help": {
+        "usage": "machine-root help",
+        "description": "Display usage information and available commands."
+      }
+    }
+  },
+
+  "resolution": {
+    "description": "All API and CLI operations use the Machine Root resolution process to locate the active registry file.",
+    "notes": [
+      "The same resolution logic is used across both Python API and CLI.",
+      "The resolved file is the target for all read and write operations."
+    ]
+  },
+
+  "design-principles": [
+    "Require explicit creation of the machine root file.",
+    "Fail clearly when the system is not initialized.",
+    "Provide specific exceptions for clarity and debuggability.",
+    "Keep the API surface minimal and obvious.",
+    "Ensure parity between CLI and Python API.",
+    "Favor direct key-value access over abstraction.",
+    "Make all operations fast and dependency-free.",
+    "Allow the system to be used interactively, programmatically, and by AIs."
+  ]
+}

machine_root-0.1.0/docs/raw/0002__help-output.txt

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

machine_root-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "machine-root"
+version = "0.1.0"
+requires-python = ">=3.11"
+license = { text = "CC0-1.0" }
+description = "A minimal shared registry for locating resources on a local machine"
+readme = "README.md"
+authors = [{ name = "Lion Kimbro" }]
+classifiers = [
+  "License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication",
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/LionKimbro/machine-root"
+Repository = "https://github.com/LionKimbro/machine-root"
+
+[project.scripts]
+machine-root = "machineroot.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/machineroot"]

machine_root-0.1.0/src/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)

machine_root-0.1.0/src/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()

machine_root-0.1.0/src/machineroot/_exceptions.py

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

machine_root-0.1.0/src/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)

machine_root-0.1.0/zoo-project.json

@@ -0,0 +1,9 @@
+{
+  "name": "machine-root",
+  "repo-type": "python-2026-03",
+  "license": "CC0-1.0",
+  "repository": {
+    "name": "machine-root",
+    "visibility": "public"
+  }
+}