nodeengine 0.1.0__py3-none-any.whl

nodeengine-0.1.0.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: nodeengine
+Version: 0.1.0
+Summary: Install the NodeEngine staleness-guard scaffold into the current repo
+Project-URL: Homepage, https://github.com/Alexyodude/NodeEngine
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# NodeEngine
+
+A Claude Code plugin. Makes staleness **fail a check** instead of relying on
+someone remembering.
+
+*The name is literal: what it builds is a graph of **nodes** — clauses, blocks,
+generated files — each holding the hash of the source it was derived from. The
+engine walks that graph and reports every edge whose source has moved.*
+
+A fact stated twice is a fact that will disagree with itself — not might, will,
+usually within hours, because the two copies are edited by different people at
+different times for different reasons.
+
+The usual response is to be careful. That fails, because carefulness does not
+survive a deadline. What works is to make the second copy *derived*, and then
+make derivation *checkable*.
+
+## The idea, in one line
+
+> **Store the hash of the source beside the derived thing. Compare on every run.**
+
+```json
+"6.2B": { "hash": "3e40ff04…", "summary": "The reservations preserve rights as partners only…" }
+            ^^^^^^^^^^^^^^^^^ the source text when a human last confirmed
+                              this summary was true of it
+```
+
+Change the source and its hash changes; the summary no longer matches its
+anchor; the check says `summary-stale: 6.2B`. Nobody had to remember. The
+staleness is not caught by cleverness — it is **structurally unable to hide**.
+
+## Install
+
+One line, in any repo:
+
+```
+curl -sL https://raw.githubusercontent.com/Alexyodude/NodeEngine/main/install.py | python -
+```
+
+That copies `stale.py`, `checkall.py` and `viewer.html` into `./tools/` and
+prints what to do next. No clone, no plugin, no dependencies. Add
+`--into scripts` or `--dry-run` after `python -` if you want them.
+
+If you have [uv](https://docs.astral.sh/uv/), the same installer runs as a
+packaged tool — same files land, same refusal to overwrite:
+
+```
+uvx --from git+https://github.com/Alexyodude/NodeEngine nodeengine
+```
+
+*It runs code fetched over the network, which is worth being deliberate about.
+To read it first:*
+
+```
+curl -sL https://raw.githubusercontent.com/Alexyodude/NodeEngine/main/install.py -o install.py
+less install.py && python install.py
+```
+
+**As a Claude Code plugin**, if you also want the skill and the guided setup:
+
+```
+/plugin marketplace add Alexyodude/NodeEngine
+/plugin install node-engine@node-engine
+/node-engine:install
+```
+
+The plugin adds the method itself — an agent that knows the three shapes, the
+defect taxonomy, and the rule that a new check is guilty until it has failed on
+demand. The one-liner just gives you the files.
+
+## What it covers
+
+Three shapes, because different relationships need different guarantees:
+
+| Shape | For | Guarantee |
+|---|---|---|
+| **Anchored** | a human judgement about a source — summaries, descriptions, a sentence citing a spec | re-anchoring is an explicit act; you cannot clear a stale flag by accident |
+| **Content-addressed** | anything that must track an original exactly — translations, mirrors | the hash *is* the key, so a changed source has no entry rather than the wrong one |
+| **Ordered** | files a human generates by running a command | catches the case the others cannot: nobody ran it |
+
+Plus the cheapest win in most repos: **a number restated in prose should be
+computed at check time and compared** — version, file count, step count, size.
+No hash needed; the artefact is the source of truth.
+
+## Two files carry the human side
+
+**`tools/DUPLICATION.md`** is the survey: what this repo states twice, where
+both copies live, which shape guards each, and what is knowingly left
+unguarded. The wiring-up writes it first, because a survey that lives only in
+a conversation is gone when the session is.
+
+**`tools/viewer.html`** is the search UI. Open it in a browser — no server, no
+dependencies — drop in the store JSONs your checks keep, and search every id,
+hash and summary. Paste a piece of source text and it computes the same key
+`stale.py` computes, then tells you whether anything still anchors that exact
+text. Read-only on purpose: re-anchoring stays a deliberate act in code,
+because the one action that must remain expensive is clearing a stale flag
+without looking.
+
+## It carries the discipline, not just the machinery
+
+When a defect is found:
+
+1. Fix the instance.
+2. **Name the class.**
+3. **Measure what else has that shape** — grep for the *claim*, not the sentence.
+4. Fix the class.
+5. **Add a check, and make it fail on purpose before believing it.**
+
+Step 5 is where this is won or lost. **A new check that passes has told you
+nothing.** It might be correct; it might be structurally incapable of failing,
+and you cannot tell those apart by reading it.
+
+## Why that last point is not paranoia
+
+`reference/traps.md` documents ten checks that shipped, each reporting a clean
+pass, each unable to fail. In **eight of ten the failure mode was a clean
+result** — not a crash, not a wrong answer, a pass. Examples:
+
+- `glob_newer_than("*.pdf", ".pdf", ".pdf")` — compared every file to itself and
+  reported *"9 rendered and current"*
+- a regex using `[^.]` to span `2.4 … 11.1`, where every id contains a period —
+  returned zero across the whole corpus, three times, by someone who had already
+  documented the bug twice
+- `if not X: return {}` upstream of `if X:` downstream — an unparseable input
+  silently switched off every check that depended on it, while the run printed `ok`
+- `if not path.exists(): continue` in a checker — a moved file quietly left the
+  watch list and the run still said `clean`
+
+Remembering these does not prevent them. Breaking the check does.
+
+## Contents
+
+```
+skills/node-engine/
+  SKILL.md              the method, the rule, and when not to use it
+  reference/
+    patterns.md         the three shapes, with implementations
+    traps.md            ten checks that could not fail — all real
+    taxonomy.md         thirteen defect classes, ranked by how many each produced
+  scaffold/
+    stale.py            the store and comparators (~150 lines, meant to be read)
+    checkall.py         the runner; `--prove` prints how to break each check
+    viewer.html         search the stores in a browser; paste text, see what anchors it
+```
+
+The scaffold is deliberately **not** a library. Copy it in, delete what you do
+not need, change what does not fit. A dependency you cannot read is one you will
+trust when it is wrong — which is the exact failure this plugin exists to prevent.
+
+## Origin
+
+Extracted from a bilingual legal package: nine documents making claims about a
+tenth, in two languages, with a generated digest in the middle. Thirteen defect
+classes and about forty real defects informed it.
+
+The examples throughout stay concrete on purpose. *"A check compared PDFs to
+themselves and reported 9 rendered and current"* transfers. *"Ensure comparison
+operands differ"* does not.
+
+## Licence
+
+MIT

nodeengine-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+nodeengine_install.py,sha256=AIAGLVluklZ8kxH7ID121UeM-34ybSGukW2ZVLsIjw8,5855
+nodeengine-0.1.0.dist-info/METADATA,sha256=6UpQGz0iQYsSiZrcxryQInvfJ0-BOSZ-cegZ7eO-Cfw,7128
+nodeengine-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+nodeengine-0.1.0.dist-info/entry_points.txt,sha256=cM2X9L20-b-i7Q1kcTiEyOpfbcizLWU0DGAD77mkP70,55
+nodeengine-0.1.0.dist-info/licenses/LICENSE,sha256=s4lN5fjZSMkhHFv97ur-mkWxol9g0c9od3QuuW_RT5U,1067
+nodeengine-0.1.0.dist-info/RECORD,,

nodeengine-0.1.0.dist-info/WHEEL

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

nodeengine-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nodeengine = nodeengine_install:main

nodeengine-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexyodude
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nodeengine_install.py

@@ -0,0 +1,152 @@
+"""Install the NodeEngine scaffold into whatever repository you are standing in.
+
+One line, from anywhere:
+
+    curl -sL https://raw.githubusercontent.com/Alexyodude/NodeEngine/main/install.py | python -
+
+Or, if you have the repo or the plugin:
+
+    python install.py                    # into ./tools/
+    python install.py --into scripts     # somewhere else
+    python install.py --dry-run          # say what would happen, touch nothing
+
+**It works with or without the rest of the repository.** If the scaffold is
+sitting next to it, it copies from disk. If it is not -- because you piped this
+file in on its own -- it fetches the scaffold files over HTTPS. That is what
+makes the one-liner possible without a clone or a plugin install.
+
+**It refuses to overwrite.** If a file is already there it says so and leaves it,
+because the scaffold is meant to be edited once it lands -- silently replacing an
+edited `stale.py` would destroy exactly the local knowledge this method is for.
+`--force` is available and tells you what you would lose.
+
+The scaffold is copied, not imported. That is deliberate: a dependency you cannot
+read is one you will trust when it is wrong, which is the failure this whole
+thing exists to prevent.
+"""
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+RAW = "https://raw.githubusercontent.com/Alexyodude/NodeEngine/main"
+REL = "skills/node-engine/scaffold"
+FILES = ["stale.py", "checkall.py", "viewer.html"]
+
+#: `__file__` is absent when this is piped to the interpreter, which is exactly
+#: how the one-liner runs it. Falling back to cwd rather than crashing is what
+#: lets the same script serve both paths.
+HERE = Path(__file__).resolve().parent if "__file__" in globals() else Path.cwd()
+LOCAL = HERE / REL
+
+
+def repo_root(start: Path) -> Path:
+    """The git root if there is one, else where you are standing.
+
+    Not `Path.cwd()` alone: running from a subdirectory would scatter the
+    scaffold somewhere arbitrary, and you would not notice until an import
+    failed.
+    """
+    try:
+        out = subprocess.run(["git", "rev-parse", "--show-toplevel"],
+                             cwd=start, capture_output=True, text=True)
+        if out.returncode == 0 and out.stdout.strip():
+            return Path(out.stdout.strip())
+    except OSError:
+        pass
+    return start
+
+
+def fetch(name: str) -> bytes:
+    from urllib.request import urlopen
+    with urlopen(f"{RAW}/{REL}/{name}", timeout=30) as r:
+        return r.read()
+
+
+def source(name: str) -> bytes:
+    """Prefer disk; fall back to the network. Say which, so it is never a guess."""
+    p = LOCAL / name
+    if p.exists():
+        return p.read_bytes()
+    return fetch(name)
+
+
+def main() -> int:
+    #: Here rather than under `__main__`: the `nodeengine` entry point calls
+    #: main() directly, and a piped stdout on Windows is cp1252 without this.
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, OSError):
+        pass
+    ap = argparse.ArgumentParser(
+        description="Install the NodeEngine scaffold into this repository.")
+    ap.add_argument("--into", default="tools", help="directory to install into (default: tools)")
+    ap.add_argument("--dry-run", action="store_true")
+    ap.add_argument("--force", action="store_true", help="overwrite existing files")
+    a = ap.parse_args()
+
+    root = repo_root(Path.cwd())
+    dest = root / a.into
+    where = "disk" if (LOCAL / FILES[0]).exists() else RAW
+    print(f"\n  repository : {root}")
+    print(f"  installing : {a.into}/")
+    print(f"  scaffold   : {where}\n")
+
+    wrote, skipped = [], []
+    for name in FILES:
+        target = dest / name
+        if target.exists() and not a.force:
+            skipped.append(name)
+            continue
+        try:
+            blob = source(name)
+        except Exception as e:                      # network, 404, TLS…
+            print(f"    could not obtain {name}: {e}", file=sys.stderr)
+            return 1
+        wrote.append(name)
+        if not a.dry_run:
+            dest.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(blob)
+
+    for n in wrote:
+        print(f"    {'would write' if a.dry_run else 'wrote'}   {a.into}/{n}")
+    for n in skipped:
+        print(f"    kept      {a.into}/{n}  (already there — not overwritten)")
+
+    if skipped and not a.force:
+        print("\n  Existing files were left alone. The scaffold is meant to be edited")
+        print("  after it lands, so replacing it would destroy local changes.")
+        print("  Use --force only after reading what you would lose.")
+
+    print(f"""
+  Next, and in this order:
+
+  1. Find the duplication. What does this repo state in more than one place?
+     Versions, counts, file inventories, a README describing a config, a
+     summary describing code. Write the list to {a.into}/DUPLICATION.md before
+     writing any code -- the survey is the half of the work that evaporates if
+     it only ever exists in your head or a chat scrollback.
+
+  2. Decide which copy is the source. Exactly one. Everything else derives.
+
+  3. Pick a shape per relationship — anchored, content-addressed, or ordered.
+
+  4. Edit {a.into}/checkall.py so its table names your checks. Adding a watched
+     thing should mean adding a row, never writing a new function.
+
+  5. Break every check on purpose and confirm it fails. A new check that passes
+     has told you nothing — you cannot distinguish "correct" from "structurally
+     unable to fail" by reading it.
+
+       python {a.into}/checkall.py --prove
+
+  Then commit. Once your checks keep stores, open {a.into}/viewer.html in a
+  browser to search them and probe what still anchors a piece of text.""")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())