novaya 0.1.0__tar.gz

novaya-0.1.0/.gitignore

@@ -0,0 +1,98 @@
+user.md
+credentials.md
+# ...but NOT the generated setup guide of that name. The rule above is
+# unanchored, so it matches `credentials.md` at ANY depth — which silently
+# swallowed novaya-deploy/setup/credentials.md, a PUBLIC document every setup
+# guide links to. It generated fine, passed tests (they read the disk) and
+# 404'd in production, because it never reached git at all.
+!novaya-deploy/setup/credentials.md
+.env
+data/
+__pycache__/
+*.pyc
+connectors/*/auth.json
+
+# Runtime / agent-generated artifacts (not source)
+workspace/
+.gstack/
+.nexus_server.pid
+*.log
+=*
+dist/
+build/
+# Generated by packaging/build_npm_package.py — a verbatim copy of the manifest's
+# npm distribution, rmtree'd and rebuilt on every run. Ignored so it is neither
+# committed nor indexed: it duplicated every symbol in the knowledge graph and
+# made impact analysis report doubled blast radius.
+npm/payload/
+
+# Same reasoning, same failure mode: a verbatim copy of sdk/python/codewiki/,
+# rebuilt by novaya-installer/scripts/sync-payload.js on every pack.
+novaya-installer/payload/
+node_modules/
+
+# A LOCAL OVERRIDE for render.yaml, so there is somewhere safe to put values
+# while working on the deploy. render.yaml ITSELF is deliberately NOT ignored:
+# Render reads it out of the repository to build the service, so ignoring it
+# would stop the deploy working at all — and ignoring a file git already tracks
+# does not untrack it or remove anything already committed, so it would buy no
+# safety either. Real credentials belong in the Render dashboard, which is why
+# every secret in render.yaml is declared `sync: false` with no value.
+render.local.yaml
+render.*.local.yaml
+
+config/google_oauth.json
+config/github_oauth.json
+config/airtable_oauth.json
+config/supabase_oauth.json
+config/huggingface_oauth.json
+config/twitter_oauth.json
+config/netlify_oauth.json
+config/digitalocean_oauth.json
+config/heroku_oauth.json
+config/gitlab_oauth.json
+config/dropbox_oauth.json
+config/asana_oauth.json
+
+# npm pack output — a build artifact, rebuilt by `npm pack` on demand.
+*.tgz
+
+# Large binaries that no page references — verified with grep before removal, and
+# untracked with `git rm --cached`, so every one is still on disk. The repo is
+# about to be pushed to GitHub for Render to deploy from; 72MB of unreferenced
+# video makes every clone slower forever and buys nothing.
+#
+# nexus-hero.mp4 (7MB) IS referenced by novaya-deploy/index.html and stays.
+# nexus-hero.mp4.mp4 is a 60MB duplicate with a doubled extension.
+novaya-deploy/nexus-hero.mp4.mp4
+Nexus codewiki - Trim.mp4
+Nexus codewiki - Trim 2.mp4
+# The extracted copy is tracked alongside these, so the archives are the same
+# bytes twice.
+design_extracted/design.tar
+design_extracted/design.tar.gz
+
+# RUNTIME STATE, not source. core/skill_library.py's _write_stats() rewrites
+# one of these after EVERY skill invocation (success_rate, invocation_count,
+# last_used), so tracking them meant 264 files churning on every Nexus run and
+# turning up as diff noise in unrelated commits. Deleting them never stuck —
+# the next run recreates them — and a .gitignore rule alone could not help
+# while git still tracked them (see the render.local.yaml note above for the
+# same trap). They are untracked with `git rm --cached`, so all 264 stay on
+# disk and no counter is lost.
+#
+# Safe to be absent on a fresh clone: _load_meta() backfills `name` from the
+# skill's directory and `description` from its SKILL.md, and every counter has
+# a default — verified by loading a skill with its stats.json removed.
+agents/*/skills/*/stats.json
+
+# Per-machine Claude Code settings — was tracked AND matched by an ignore rule,
+# which is the one combination where .gitignore silently does nothing.
+.claude/settings.local.json
+
+# installClaudeCode writes project-scoped MCP config to process.cwd(), so any
+# test or manual run from novaya-installer/ drops one here. It is a per-project
+# artifact of whoever ran the installer, never something to ship.
+novaya-installer/.mcp.json
+.mcp.json
+.coldtest/

novaya-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: novaya
+Version: 0.1.0
+Summary: Ngraph: the Codewiki client. Repository context for coding agents.
+Project-URL: Homepage, https://trynovaya.com
+Project-URL: Dashboard, https://app.trynovaya.com
+Author: Novaya
+License: Proprietary
+Keywords: codewiki,coding-agents,context,mcp,ngraph
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Ngraph
+
+The client half of [Codewiki](https://trynovaya.com). Codewiki is a hosted
+knowledge graph over your codebase; Ngraph is the small thing you install so
+your coding agents can reach it.
+
+```sh
+uv tool install novaya
+ngraph install <KEY>          # key from https://app.trynovaya.com -> Manage keys
+```
+
+That is the whole setup. `install` stores the key in your OS credential store,
+resolves which indexed codebase this checkout is, writes `.ngraph/`, wires
+every supported agent on the machine, and then proves it worked. If it prints
+`Done`, a fresh session in this repository can already use it.
+
+## What it wires
+
+| Client | Instructions | MCP |
+| --- | --- | --- |
+| Claude Code | `CLAUDE.md` | `~/.claude.json` |
+| Codex | `AGENTS.md` | `~/.codex/config.toml` |
+| OpenCode | `AGENTS.md` | `~/.config/opencode/opencode.json` |
+
+Each gets the MCP server registered natively **and** a short delimited block in
+its instruction file pointing at `.ngraph/rules.md`. Both, because MCP gives an
+agent real tools and only reaches clients that speak it, while the pointer
+reaches anything that reads a file.
+
+## Commands
+
+```
+ngraph summary              what this project is, in prose
+ngraph overview             computed architecture: hubs, subsystems, layers
+ngraph why <path>           the recorded reasoning behind a file
+ngraph connections <path>   what it is wired to, including historical co-change
+ngraph impact <path>        blast radius
+ngraph recent               recent commits with the intent behind them
+ngraph search <query>       find by meaning
+ngraph ask "<question>"     a decision-shaped briefing
+ngraph record-why "<why>"   write reasoning back after a commit
+
+ngraph doctor               prove the setup still works (exit code for CI)
+ngraph adapters             which clients this knows how to wire
+ngraph uninstall            remove everything it wrote
+```
+
+## Where things live
+
+- **Key** -- your OS credential store (DPAPI, Keychain, libsecret, or a 0600
+  file). Never in the repository, never in a `.md`, never printed.
+- **`.ngraph/rules.md`** -- how to work with the graph. Same in every repo.
+- **`.ngraph/skills.md`** -- what the server serves, generated from the live API.
+- **`.ngraph/blueprint.md`** -- this repository: its codebase name and origin.
+
+Commit `.ngraph/`. It is generated but stable, and sharing it means your
+teammates' agents resolve the same codebase you did.
+
+## Why the package is `novaya` and the command is `ngraph`
+
+`ngraph` on PyPI is an active network-modeling library and `codewiki` is an
+unrelated project. Neither name is available, and installing either gets you
+working software that is not this. `uv tool install novaya` is the only
+install line.

novaya-0.1.0/README-ngraph.md

@@ -0,0 +1,64 @@
+# Ngraph
+
+The client half of [Codewiki](https://trynovaya.com). Codewiki is a hosted
+knowledge graph over your codebase; Ngraph is the small thing you install so
+your coding agents can reach it.
+
+```sh
+uv tool install novaya
+ngraph install <KEY>          # key from https://app.trynovaya.com -> Manage keys
+```
+
+That is the whole setup. `install` stores the key in your OS credential store,
+resolves which indexed codebase this checkout is, writes `.ngraph/`, wires
+every supported agent on the machine, and then proves it worked. If it prints
+`Done`, a fresh session in this repository can already use it.
+
+## What it wires
+
+| Client | Instructions | MCP |
+| --- | --- | --- |
+| Claude Code | `CLAUDE.md` | `~/.claude.json` |
+| Codex | `AGENTS.md` | `~/.codex/config.toml` |
+| OpenCode | `AGENTS.md` | `~/.config/opencode/opencode.json` |
+
+Each gets the MCP server registered natively **and** a short delimited block in
+its instruction file pointing at `.ngraph/rules.md`. Both, because MCP gives an
+agent real tools and only reaches clients that speak it, while the pointer
+reaches anything that reads a file.
+
+## Commands
+
+```
+ngraph summary              what this project is, in prose
+ngraph overview             computed architecture: hubs, subsystems, layers
+ngraph why <path>           the recorded reasoning behind a file
+ngraph connections <path>   what it is wired to, including historical co-change
+ngraph impact <path>        blast radius
+ngraph recent               recent commits with the intent behind them
+ngraph search <query>       find by meaning
+ngraph ask "<question>"     a decision-shaped briefing
+ngraph record-why "<why>"   write reasoning back after a commit
+
+ngraph doctor               prove the setup still works (exit code for CI)
+ngraph adapters             which clients this knows how to wire
+ngraph uninstall            remove everything it wrote
+```
+
+## Where things live
+
+- **Key** -- your OS credential store (DPAPI, Keychain, libsecret, or a 0600
+  file). Never in the repository, never in a `.md`, never printed.
+- **`.ngraph/rules.md`** -- how to work with the graph. Same in every repo.
+- **`.ngraph/skills.md`** -- what the server serves, generated from the live API.
+- **`.ngraph/blueprint.md`** -- this repository: its codebase name and origin.
+
+Commit `.ngraph/`. It is generated but stable, and sharing it means your
+teammates' agents resolve the same codebase you did.
+
+## Why the package is `novaya` and the command is `ngraph`
+
+`ngraph` on PyPI is an active network-modeling library and `codewiki` is an
+unrelated project. Neither name is available, and installing either gets you
+working software that is not this. `uv tool install novaya` is the only
+install line.

novaya-0.1.0/novaya/__init__.py

@@ -0,0 +1,13 @@
+"""Ngraph -- the client half of Codewiki.
+
+Cloud owns indexing, the graph, retrieval and the API. This owns auth,
+discovery, agent adapters and request transport. Nothing else, ever: see
+build.md, LAW 2.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+# The typed command. Distribution is `novaya`: `ngraph` and `codewiki` are both
+# taken on PyPI by live unrelated projects, so a guess installs the wrong tool.
+COMMAND = "ngraph"

novaya-0.1.0/novaya/__main__.py

@@ -0,0 +1,11 @@
+"""`python -m novaya` -- the entrypoint a client config falls back to.
+
+The console script is the normal path. This exists because an MCP config has to
+name something that will still resolve when the client launches it from an
+environment that is not the user's shell -- and on a checkout, or a PATH the
+resolver cannot see, the module is the thing that always works.
+"""
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

novaya-0.1.0/novaya/adapters/__init__.py

@@ -0,0 +1,53 @@
+"""The adapter registry. One declaration.
+
+install, doctor, `ngraph adapters` and the docs all read ADAPTERS. Three ship:
+each one is a claim that somebody checked where that client keeps its config.
+"""
+from __future__ import annotations
+
+from .base import Adapter, Result, mcp_command, probe_server, SERVER_NAME
+from .claude_code import ClaudeCode
+from .codex import Codex
+from .opencode import OpenCode
+
+ADAPTERS = (ClaudeCode(), Codex(), OpenCode())
+
+SLUGS = tuple(a.slug for a in ADAPTERS)
+
+
+def get(slug: str):
+    for adapter in ADAPTERS:
+        if adapter.slug == slug:
+            return adapter
+    return None
+
+
+def detected():
+    """The clients actually present on this machine."""
+    return [a for a in ADAPTERS if a.detect()]
+
+
+def resolve(names):
+    """Names from the command line to adapters.
+
+    ("all",) or nothing means "whatever is installed here" -- an install should
+    not wire a client the user does not have, and should not need to be told
+    which ones they do.
+    """
+    wanted = [n.strip().lower() for n in (names or []) if n and n.strip()]
+    if not wanted or "auto" in wanted:
+        return detected(), []
+    if "all" in wanted:
+        return list(ADAPTERS), []
+    chosen, unknown = [], []
+    for name in wanted:
+        adapter = get(name)
+        if adapter is None:
+            unknown.append(name)
+        elif adapter not in chosen:
+            chosen.append(adapter)
+    return chosen, unknown
+
+
+__all__ = ["ADAPTERS", "SLUGS", "Adapter", "Result", "get", "detected",
+           "resolve", "mcp_command", "probe_server", "SERVER_NAME"]

novaya-0.1.0/novaya/adapters/base.py

@@ -0,0 +1,236 @@
+"""What an adapter is: native MCP config, plus a pointer block.
+
+Neither alone reaches every client. Rules all of them follow -- read-modify-
+write a user's config, replace between markers rather than append, warn rather
+than crash on a config we cannot parse, and place a command, never a key.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .. import docs
+
+# One name everywhere. Changing it orphans every config already written.
+SERVER_NAME = "codewiki"
+
+BLOCK_START = "# ngraph:start"
+BLOCK_END = "# ngraph:end"
+
+
+@dataclass
+class Result:
+    """What one adapter did, in terms an install report can print."""
+    slug: str
+    name: str
+    detected: bool = False
+    actions: list = field(default_factory=list)
+    warnings: list = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return self.detected and not self.warnings
+
+    def act(self, text: str):
+        self.actions.append(text)
+
+    def warn(self, text: str):
+        self.warnings.append(text)
+
+
+def mcp_command() -> list:
+    """How a client launches our server. The shim, ABSOLUTE: a client spawns
+    MCP servers from its own environment, which often has no ~/.local/bin."""
+    shim = shutil.which("ngraph")
+    if shim:
+        return [str(Path(shim).resolve()), "mcp"]
+    # A checkout, or a PATH we cannot see. The module needs no shim.
+    return [sys.executable, "-m", "novaya", "mcp"]
+
+
+def home() -> Path:
+    return Path.home()
+
+
+def config_home() -> Path:
+    """XDG config root, with the Windows equivalent."""
+    if sys.platform.startswith("win"):
+        return Path(os.environ.get("APPDATA") or (home() / "AppData" / "Roaming"))
+    return Path(os.environ.get("XDG_CONFIG_HOME") or (home() / ".config"))
+
+
+def read_json(path: Path):
+    """(document, error). A missing file is an empty document, not an error."""
+    if not path.exists():
+        return {}, ""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return None, "could not read " + str(path) + ": " + exc.strerror
+    if not text.strip():
+        return {}, ""
+    try:
+        doc = json.loads(text)
+    except json.JSONDecodeError as exc:
+        return None, "not valid JSON (" + str(exc) + "): " + str(path)
+    if not isinstance(doc, dict):
+        return None, "expected a JSON object at the top level: " + str(path)
+    return doc, ""
+
+
+def write_json(path: Path, doc: dict) -> str:
+    """Write a config back; a crash cannot truncate it."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".ngraph-tmp")
+    tmp.write_text(json.dumps(doc, indent=2) + "\n", encoding="utf-8")
+    os.replace(tmp, path)
+    return str(path)
+
+
+def set_block(path: Path, body: str) -> str:
+    """Replace our block in a line-based config. No TOML writer in the stdlib,
+    and a round-trip parser would eat the user's comments."""
+    original = path.read_text(encoding="utf-8") if path.exists() else ""
+    block = BLOCK_START + "\n" + body.strip() + "\n" + BLOCK_END
+    if BLOCK_START in original and BLOCK_END in original:
+        head = original.split(BLOCK_START)[0]
+        tail = original.split(BLOCK_END, 1)[1]
+        updated = head + block + tail
+    elif original.strip():
+        updated = original.rstrip("\n") + "\n\n" + block + "\n"
+    else:
+        updated = block + "\n"
+    if updated == original:
+        return "unchanged"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(updated, encoding="utf-8")
+    return "updated" if original else "created"
+
+
+def drop_block(path: Path) -> bool:
+    if not path.exists():
+        return False
+    original = path.read_text(encoding="utf-8")
+    if BLOCK_START not in original or BLOCK_END not in original:
+        return False
+    head = original.split(BLOCK_START)[0]
+    tail = original.split(BLOCK_END, 1)[1]
+    path.write_text((head.rstrip("\n") + "\n" + tail.lstrip("\n")).strip() + "\n",
+                    encoding="utf-8")
+    return True
+
+
+def on_path(binary: str) -> bool:
+    return shutil.which(binary) is not None
+
+
+def command_problem(argv) -> str:
+    """'' when argv[0] is a launchable program, else why not."""
+    program = str(argv[0])
+    if Path(program).is_absolute():
+        return "" if Path(program).exists() else (
+            "registered command no longer exists: " + program
+            + " -- re-run `ngraph install`")
+    if shutil.which(program):
+        return ""
+    return "registered command is not on PATH: " + program
+
+
+class Adapter:
+    """One coding client. Subclasses supply paths and a config shape."""
+
+    slug = ""
+    name = ""
+    instruction_file = "AGENTS.md"
+    docs_url = ""
+
+    def detect(self) -> bool:
+        raise NotImplementedError
+
+    def register_mcp(self, result: Result):
+        """Put our server in the client's own config. Optional per client."""
+        result.act("no MCP registration for this client -- shell verbs only")
+
+    def unregister_mcp(self, result: Result):
+        pass
+
+    # -- the half every adapter shares ----------------------------------------
+
+    def wire(self, root: Path, codebase: str = "", with_mcp: bool = True) -> Result:
+        result = Result(self.slug, self.name, detected=True)
+        path = Path(root) / self.instruction_file
+        state = docs.apply_pointer(path, codebase)
+        result.act(state + " pointer block in " + self.instruction_file)
+        if not with_mcp:
+            # Claude Code blocks startup on an MCP server that never
+            # answers: registering a broken one hangs it, not degrades it.
+            result.warn("MCP not registered -- the server did not answer a "
+                        "handshake (see the mcp server check)")
+            return result
+        try:
+            self.register_mcp(result)
+        except OSError as exc:
+            result.warn("MCP registration failed: " + str(exc))
+        return result
+
+    def unwire(self, root: Path) -> Result:
+        result = Result(self.slug, self.name, detected=True)
+        if docs.remove_pointer(Path(root) / self.instruction_file):
+            result.act("removed pointer block from " + self.instruction_file)
+        try:
+            self.unregister_mcp(result)
+        except OSError as exc:
+            result.warn("MCP removal failed: " + str(exc))
+        return result
+
+    def recorded_command(self):
+        """The argv this client's config will actually launch, or None."""
+        return None
+
+    def verify_mcp(self) -> str:
+        """'' when this client can really start our server, else why not.
+
+        Presence of the key is not enough. An upgrade that moves the shim
+        leaves a config naming a path that no longer exists -- the client gets
+        nothing and every other check still passes, which is the silent
+        success this whole design exists to remove.
+        """
+        argv = self.recorded_command()
+        if argv is None:
+            return "not registered"
+        if not argv:
+            return "registered with an empty command"
+        return command_problem(argv)
+
+
+def probe_server(timeout: float = 25.0) -> str:
+    """Handshake with our own server the way a client would. Registering
+    proves a config has a line; this proves the line points at something."""
+    argv = mcp_command()
+    request = json.dumps({
+        "jsonrpc": "2.0", "id": 1, "method": "initialize",
+        "params": {"protocolVersion": "2024-11-05", "capabilities": {},
+                   "clientInfo": {"name": "ngraph-doctor", "version": "1"}},
+    }) + "\n"
+    try:
+        proc = subprocess.run(argv, input=request, capture_output=True,
+                              text=True, timeout=timeout, check=False)
+    except (OSError, subprocess.SubprocessError) as exc:
+        return "could not start " + " ".join(argv) + ": " + str(exc)
+    for line in (proc.stdout or "").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            doc = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(doc, dict) and doc.get("id") == 1 and "result" in doc:
+            return ""
+    detail = (proc.stderr or "").strip().splitlines()
+    return "no initialize response" + (": " + detail[-1] if detail else "")

novaya-0.1.0/novaya/adapters/claude_code.py

@@ -0,0 +1,68 @@
+"""Claude Code.
+
+MCP servers go in `~/.claude.json`, not settings.json -- that file ignores an
+mcpServers key silently. The same file holds every project and server the user
+has, so it is read-modify-write or it is data loss.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import base
+
+
+class ClaudeCode(base.Adapter):
+    slug = "claude-code"
+    name = "Claude Code"
+    instruction_file = "CLAUDE.md"
+    docs_url = "https://code.claude.com/docs/en/mcp"
+
+    def config_path(self) -> Path:
+        return base.home() / ".claude.json"
+
+    def detect(self) -> bool:
+        return (self.config_path().exists()
+                or (base.home() / ".claude").is_dir()
+                or base.on_path("claude"))
+
+    def register_mcp(self, result: base.Result):
+        path = self.config_path()
+        doc, err = base.read_json(path)
+        if doc is None:
+            result.warn(err + " -- left untouched; shell verbs still work")
+            return
+        servers = doc.get("mcpServers")
+        if not isinstance(servers, dict):
+            if servers is not None:
+                result.warn("mcpServers in ~/.claude.json is not an object -- "
+                            "left untouched")
+                return
+            servers = {}
+        argv = base.mcp_command()
+        entry = {"command": argv[0], "args": argv[1:]}
+        if servers.get(base.SERVER_NAME) == entry:
+            result.act("MCP server already registered in ~/.claude.json")
+            return
+        servers[base.SERVER_NAME] = entry
+        doc["mcpServers"] = servers
+        base.write_json(path, doc)
+        result.act("registered MCP server '" + base.SERVER_NAME
+                   + "' in ~/.claude.json")
+
+    def unregister_mcp(self, result: base.Result):
+        path = self.config_path()
+        doc, err = base.read_json(path)
+        if doc is None or not isinstance(doc.get("mcpServers"), dict):
+            return
+        if doc["mcpServers"].pop(base.SERVER_NAME, None) is not None:
+            base.write_json(path, doc)
+            result.act("removed MCP server from ~/.claude.json")
+
+    def recorded_command(self):
+        doc, _err = base.read_json(self.config_path())
+        if doc is None:
+            return None
+        entry = (doc.get("mcpServers") or {}).get(base.SERVER_NAME)
+        if not isinstance(entry, dict) or not entry.get("command"):
+            return None
+        return [entry["command"], *(entry.get("args") or [])]