awkno 0.1.0__py3-none-any.whl

awkno/__init__.py

@@ -0,0 +1,25 @@
+"""awkno — The man page for the Aither World.
+
+    from awkno import AwknoRegistry
+
+    registry = AwknoRegistry()
+    page = registry.get("awdk")
+    print(page.render())
+
+Every brick, stack and law in your terminal, offline. No external dependencies,
+no network required. Pages are generated from ecosystem.yaml and the laws corpus,
+committed as data files.
+"""
+
+from __future__ import annotations
+
+from awkno.corpus import AwknoPage, AwknoRegistry, NotFoundError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AwknoRegistry",
+    "AwknoPage",
+    "NotFoundError",
+    "__version__",
+]

awkno/_doctor.py

@@ -0,0 +1,139 @@
+"""Stack-aware `doctor` for awkno.
+
+GENERATED BY gen_aw_doctor.py -- DO NOT EDIT.
+Regenerate it with the generator named above; a hand-edit here is reverted by
+the next run and fails the parity gate.
+
+Why a doctor exists at all: the aw* bricks are designed to COMPOSE, so the
+interesting failures live BETWEEN them. "awkno is installed" is not the useful
+fact -- "awkno is installed and the thing it pairs with is not" is. This reports
+the whole stack, not just itself.
+
+stdlib only, on purpose: a diagnostic that cannot run because a dependency is
+missing is worthless precisely when you need it.
+"""
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import sys
+
+#: Frozen from AitherOS/config/ecosystem.yaml at generation time. A shipped
+#: package cannot read the registry, and a doctor that guessed at the family
+#: would go stale in silence. Regenerate to update.
+SELF = 'awkno'
+FAMILY = ['awask', 'awask', 'awbac', 'awbrowse', 'awdit', 'awevolve', 'awevolve', 'awfind', 'awgit', 'awgraph', 'awiam', 'awm', 'awmail', 'awnboard', 'awnest', 'awnet', 'awnode', 'awpredict', 'awprism', 'awreason', 'awrecover', 'awrecurse', 'awrelay', 'awrepl', 'awresearch', 'awrun', 'awseal', 'awshare', 'awtunnel']
+PAIRS_WITH = ['awfind', 'awm']
+
+#: This brick's OWN config, read out of its source at generation time.
+#: ENV_REQUIRED is `os.environ["X"]` -- absent, that is a KeyError the moment
+#: the line runs. ENV_OPTIONAL is `os.getenv("X")`, which returns None and lets
+#: the caller cope. Only this brick's namespace is listed: reporting the
+#: platform-wide vars it also touches would be noise, and a doctor that floods
+#: gets ignored.
+ENV_REQUIRED = []
+ENV_OPTIONAL = []
+
+
+def _installed(mod: str) -> "str | None":
+    """Version if importable, else None. Never raises -- a broken sibling must
+    not take the diagnostic down with it."""
+    try:
+        if importlib.util.find_spec(mod) is None:
+            return None
+    except (ImportError, ValueError):
+        return None
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+        try:
+            return version(mod)
+        except PackageNotFoundError:
+            return "installed"
+    except Exception:
+        return "installed"
+
+
+def report(out=None) -> int:
+    """Print the stack picture. 0 = this brick and its pairs are present."""
+    out = out or sys.stdout
+    print(f"{SELF} doctor", file=out)
+
+    mine = _installed(SELF)
+    print(f"  self       {SELF} {mine or 'NOT IMPORTABLE'}", file=out)
+    shim = shutil.which(SELF)
+    print(f"  command    {shim or 'not on PATH'}", file=out)
+
+    # The stack. Siblings this brick pairs with are called out separately,
+    # because a missing pair is a REASON, while a missing unrelated brick is
+    # just a fact about your machine.
+    missing_pairs, present = [], []
+    for name in FAMILY:
+        v = _installed(name)
+        if v:
+            present.append(name)
+        elif name in PAIRS_WITH:
+            missing_pairs.append(name)
+    print(f"  stack      {len(present)}/{len(FAMILY)} aw* packages installed",
+          file=out)
+    if present:
+        print(f"             {' '.join(sorted(present))}", file=out)
+
+    missing_req = [v for v in ENV_REQUIRED if not os.environ.get(v)]
+    if ENV_REQUIRED or ENV_OPTIONAL:
+        have = sum(1 for v in ENV_REQUIRED + ENV_OPTIONAL if os.environ.get(v))
+        total = len(ENV_REQUIRED) + len(ENV_OPTIONAL)
+        print(f"  config     {have}/{total} of this brick's own vars set", file=out)
+        if missing_req:
+            # Not a preference. os.environ[...] raises the moment it runs.
+            print(f"             MISSING REQUIRED: {' '.join(missing_req)}", file=out)
+
+    local = _local_checks()
+    for line in local:
+        print(f"  {line}", file=out)
+
+    if mine is None:
+        print(f"\nverdict: {SELF} itself is not importable. Reinstall it before "
+              f"anything else here means much.", file=out)
+        return 1
+    if missing_req:
+        print(f"\nverdict: {SELF} is missing required config "
+              f"({', '.join(missing_req)}). Those are read with os.environ[...], "
+              f"so the code path that needs them raises rather than degrades.",
+              file=out)
+        return 1
+    if missing_pairs:
+        print(f"\nverdict: {SELF} works, but pairs with "
+              f"{', '.join(sorted(missing_pairs))} which "
+              f"{'is' if len(missing_pairs) == 1 else 'are'} not installed. "
+              f"That is a capability you are missing, not an error.", file=out)
+        return 0
+    print(f"\nverdict: {SELF} and everything it pairs with are present.", file=out)
+    return 0
+
+
+def _local_checks() -> "list[str]":
+    """Per-brick checks, if this package defines them.
+
+    Kept as a HOOK rather than generated guesses: the generator knows the family
+    from the registry, but it does not know what awkno needs at runtime, and a
+    doctor that invented config requirements would be confidently wrong. A
+    package supplies `_doctor_local()` returning display lines; absent, the
+    stack picture above still stands on its own.
+    """
+    try:
+        mod = importlib.import_module(f"{SELF}.doctor_local")
+    except Exception:
+        return []
+    try:
+        return list(mod._doctor_local())
+    except Exception as exc:                       # noqa: BLE001
+        return [f"local     checks raised {type(exc).__name__}: {exc}"]
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    return report()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

awkno/cli.py

@@ -0,0 +1,355 @@
+"""awkno CLI.
+
+    awkno awdk
+    awkno awsh
+    awkno law 5
+    awkno list
+    awkno search design-for-the-silence
+    awkno -k silence
+    awkno --plain
+
+Type awkno with no args to show an overview.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+
+from awkno.corpus import AwknoRegistry, NotFoundError
+
+
+def pager_render(text: str) -> None:
+    """Render text through $PAGER if available, else stdout."""
+    pager = os.environ.get("PAGER", "less" if sys.platform != "win32" else "more")
+
+    if not sys.stdout.isatty():
+        print(text)
+        return
+
+    try:
+        import subprocess
+
+        proc = subprocess.Popen(
+            pager, stdin=subprocess.PIPE, text=True, bufsize=1024
+        )
+        try:
+            proc.stdin.write(text)
+            proc.stdin.close()
+        except BrokenPipeError:
+            pass
+        proc.wait()
+    except (FileNotFoundError, OSError):
+        print(text)
+
+
+def show_overview() -> None:
+    """Show the overview page."""
+    text = """NAME
+    awkno — The man page for the Aither World
+
+SYNOPSIS
+    awkno [TOPIC]
+    awkno list
+    awkno law <N|SLUG>
+    awkno search TERM
+    awkno -k TERM
+    awkno --plain
+    awkno --json
+
+DESCRIPTION
+    awkno is an offline reference for the Aither World ecosystem. Every brick
+    (standalone tool), stack (curated set), and law (learned principle) lives
+    here — no browser, no internet connection needed.
+
+    The registry is built from ecosystem.yaml and the laws corpus at build time
+    and committed as data files. After install, the pages are always there.
+
+QUICK START
+    awkno awdk                 Show the awdk brick
+    awkno awsh                 Show the awsh brick
+    awkno law 5                Show law 5
+    awkno list                 List all topics
+    awkno search kubernetes    Search for "kubernetes"
+
+OPTIONS
+    --plain              No ANSI formatting
+    --json               JSON output (for piping)
+    -k, --apropos TERM   Search for TERM (like man -k)
+
+SEE ALSO
+    For the full ecosystem, visit https://github.com/Aitherium/awkno
+"""
+    pager_render(text)
+
+
+def slugify(text: str) -> str:
+    """Reduce a synopsis to a comparable slug."""
+    return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+
+
+def resolve_law_key(registry: "AwknoRegistry", law_id: str) -> str | None:
+    """Map `5` or `design-for-the-silence` onto a law page key.
+
+    A slug matches when it prefixes the slugified synopsis of exactly ONE law.
+    Ambiguous prefixes return None rather than the first hit: a prefix matcher
+    that guesses is how `get("nemotron")` came to answer for a model nobody
+    registered.
+    """
+    if law_id.isdigit():
+        return f"law-{int(law_id):02d}"
+
+    want = slugify(law_id)
+    if not want:
+        return None
+
+    laws = [t for t in registry.list_topics() if t.startswith("law-")]
+
+    # The law's OWN slug first. Exact, and it survives a retitle -- the
+    # synopsis fallback below does not.
+    for topic in laws:
+        if slugify(registry.pages[topic].slug or "") == want:
+            return topic
+
+    # Fall back to a unique prefix of the synopsis, for a corpus generated
+    # before slugs were carried. Unique or nothing: a prefix matcher that
+    # answers with its first hit is fail-open, and returns a confident wrong
+    # law for a slug nobody registered.
+    hits = [
+        topic
+        for topic in laws
+        if slugify(registry.pages[topic].synopsis).startswith(want)
+    ]
+    return hits[0] if len(hits) == 1 else None
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser.
+
+    Separate from main() so the self-test can assert that every form printed
+    in the SYNOPSIS actually parses.
+    """
+    parser = argparse.ArgumentParser(
+        description="The man page for the Aither World",
+        add_help=False,
+        usage="awkno [TOPIC] or awkno COMMAND [OPTIONS]",
+    )
+
+    # nargs="*", not "?": the SYNOPSIS advertises `awkno law 5` and
+    # `awkno search TERM`, both of which argparse rejected as
+    # "unrecognized arguments" under nargs="?" -- only the quoted
+    # `awkno "law 5"` worked, which nobody would type.
+    parser.add_argument(
+        "topic", nargs="*", help="Topic, brick, stack, law, or command"
+    )
+    parser.add_argument(
+        "--plain", action="store_true", help="Plain text, no ANSI formatting"
+    )
+    parser.add_argument(
+        "--json", action="store_true", help="JSON output for piping"
+    )
+    parser.add_argument(
+        "-k", "--apropos", dest="search", help="Search for term (like man -k)"
+    )
+    parser.add_argument(
+        "--self-test", action="store_true", help="Run self-test"
+    )
+
+    return parser
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    # GENERATED doctor intercept (gen_aw_doctor.py) -- do not edit
+    _dv = locals().get("argv")
+    if (_dv if _dv is not None else __import__("sys").argv[1:])[:1] == ["doctor"]:
+        from ._doctor import report
+        return report()
+    parser = _build_parser()
+    args = parser.parse_args()
+    topic = " ".join(args.topic).strip()
+
+    if args.self_test:
+        _self_test()
+        return
+
+    registry = AwknoRegistry()
+
+    if not topic and not args.search:
+        show_overview()
+        return
+
+    if args.search:
+        results = registry.search(args.search)
+        if not results:
+            print(f"No matches for '{args.search}'")
+            return
+        if args.json:
+            output = [
+                {"topic": page.topic, "score": score}
+                for page, score in results[:10]
+            ]
+            print(json.dumps(output))
+        else:
+            print(f"\n[{args.search}]\n")
+            for page, score in results[:10]:
+                print(f"    {page.topic:<20} {page.synopsis}")
+        return
+
+    topic_lower = topic.lower()
+
+    if topic_lower == "list":
+        topics = registry.list_topics()
+        categories = {
+            "brick": [],
+            "stack": [],
+            "law": [],
+            "topic": [],
+        }
+        for t in topics:
+            page = registry.pages[t]
+            if page.category not in categories:
+                categories[page.category] = []
+            categories[page.category].append(t)
+
+        print()
+        for cat in ["brick", "stack", "law", "topic"]:
+            if categories[cat]:
+                print(f"{cat.upper()}S ({len(categories[cat])})")
+                for name in sorted(categories[cat]):
+                    page = registry.pages[name]
+                    print(f"    {name:<20} {page.synopsis}")
+                print()
+        return
+
+    if topic_lower.startswith("law"):
+        parts = topic.split()
+        if len(parts) < 2:
+            print("Usage: awkno law <N|SLUG>")
+            return
+        law_id = parts[1]
+        law_key = resolve_law_key(registry, law_id)
+        if law_key is None:
+            print(
+                f"Law '{law_id}' not found or ambiguous. "
+                "Try: awkno law 5, awkno law design-for-the-silence"
+            )
+            return
+        try:
+            page = registry.get(law_key)
+        except NotFoundError:
+            print(f"Law '{law_id}' not found. Try: awkno law 1, awkno law 5, etc.")
+            return
+    else:
+        try:
+            page = registry.get(topic)
+        except NotFoundError:
+            print(f"Topic '{topic}' not found")
+            print(f"Try: awkno list, awkno -k '{topic}'")
+            return
+
+    if args.json:
+        print(json.dumps(page.to_dict()))
+    else:
+        text = page.render(plain=args.plain)
+        pager_render(text)
+
+
+def _self_test() -> None:
+    """Run self-test (pure, no external service needed)."""
+    from awkno.corpus import AwknoPage, AwknoRegistry
+
+    page = AwknoPage(
+        topic="test",
+        category="topic",
+        synopsis="A test page",
+        description="This is a test",
+        adopt="Adopt this test",
+        status="test",
+    )
+
+    assert page.topic == "test"
+    assert page.render()
+    assert page.to_dict()
+
+    # --- the SYNOPSIS is a promise; assert it ------------------------------
+    #
+    # This block exists because every two-word form printed in this tool's own
+    # SYNOPSIS -- `awkno law 5`, `awkno search TERM` -- was rejected by argparse
+    # as "unrecognized arguments" in a SHIPPED release on PyPI, and `<N|SLUG>`
+    # advertised a slug lookup the generator computed and discarded, so no slug
+    # ever resolved. The self-test above could not see any of it: it asserted
+    # that a dataclass renders. A tool that documents an invocation it cannot
+    # perform is a broken tool that reads as an authoritative one.
+    parser = _build_parser()
+
+    for argv in (["law", "5"], ["search", "silence"], ["list"], ["awdk"]):
+        try:
+            parsed = parser.parse_args(argv)
+        except SystemExit:  # argparse exits rather than raising
+            raise AssertionError(
+                f"SYNOPSIS form `awkno {' '.join(argv)}` was REJECTED by the parser"
+            ) from None
+        joined = " ".join(parsed.topic).strip()
+        assert joined == " ".join(argv), f"SYNOPSIS form {argv} did not parse"
+
+    # the quoted form callers may already be using must keep working
+    assert " ".join(parser.parse_args(["law 5"]).topic).strip() == "law 5"
+
+    registry = AwknoRegistry()
+
+    # numeric and slug lookups both resolve, and to the SAME law
+    by_num = resolve_law_key(registry, "5")
+    by_slug = resolve_law_key(registry, "design-for-the-silence")
+    assert by_num == "law-05", f"numeric law lookup gave {by_num}"
+    assert by_slug == "law-05", f"slug law lookup gave {by_slug}"
+    assert registry.get(by_num).synopsis
+
+    # every law is reachable by BOTH spellings -- a resolver that answers for
+    # law 5 and nothing else passes a single-case test while being useless
+    law_topics = [t for t in registry.list_topics() if t.startswith("law-")]
+    assert len(law_topics) >= 19, f"only {len(law_topics)} laws in the corpus"
+    for topic in law_topics:
+        number = topic.split("-", 1)[1].lstrip("0") or "0"
+        assert resolve_law_key(registry, number) == topic, f"{topic} not reachable by number"
+        slug = slugify(registry.pages[topic].synopsis)
+        assert resolve_law_key(registry, slug) == topic, f"{topic} not reachable by slug"
+        own = registry.pages[topic].slug
+        assert own, f"{topic} carries no slug -- regenerate the corpus"
+        assert resolve_law_key(registry, own) == topic, f"{topic} not reachable by its own slug"
+
+    # A RETITLED law: slug and synopsis diverge, which is the only case the
+    # exact-slug branch exists for. Without this the branch is dead weight --
+    # every current law's filename slug happens to prefix its own synopsis, so
+    # deleting the branch leaves the suite green and the lookup silently
+    # dependent on a coincidence that a single retitle ends.
+    registry.pages["law-99"] = AwknoPage(
+        topic="law-99",
+        category="law",
+        synopsis="Completely different words after a retitle",
+        description="Law #99",
+        slug="the-original-filename-slug",
+    )
+    try:
+        assert resolve_law_key(registry, "the-original-filename-slug") == "law-99", (
+            "a retitled law is unreachable by its own slug"
+        )
+        assert resolve_law_key(registry, "completely-different-words") == "law-99"
+    finally:
+        del registry.pages["law-99"]
+
+    # fail closed: nonsense and ambiguity resolve to nothing, never to law 1.
+    # An ambiguous prefix returning its first hit is the trap that made a
+    # licence lookup answer for models nobody had registered.
+    assert resolve_law_key(registry, "no-such-law-anywhere") is None
+    assert resolve_law_key(registry, "") is None
+    assert resolve_law_key(registry, "a") is None, "bare prefix must be ambiguous, not law-01"
+
+    print(f"[OK] awkno self-test passed ({len(law_topics)} laws, both spellings)")
+
+
+if __name__ == "__main__":
+    main()