relinkra 0.1.2__tar.gz

relinkra-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 José Julián Sánchez Rodríguez
+
+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.

relinkra-0.1.2/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: relinkra
+Version: 0.1.2
+Summary: Shared code intelligence, persistent memory and optimized context for AI coding agents.
+Author: José Julián Sánchez Rodríguez
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jojusa/relinkra
+Project-URL: Repository, https://github.com/jojusa/relinkra
+Project-URL: Issues, https://github.com/jojusa/relinkra/issues
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Relinkra
+
+## What Relinkra does
+
+Relinkra gives AI coding agents shared code intelligence, persistent memory, and optimized context: one codebase, one shared context, many agents. Every connected agent sees the same project memory, handoffs, and code references instead of re-discovering the repository alone. Relinkra optimizes the path to information; it does not restrict the agent's ability to search, reason, edit, or validate by itself.
+
+## Quick start
+
+Requirements: Python 3.9+ and Git. The quick start does not require any optional component.
+
+### Install
+
+The normal installation path after publication is:
+
+```bash
+python -m pip install relinkra
+```
+
+The literal `pip install relinkra` command is the equivalent user-facing
+contract. Relinkra is not being published to PyPI in this checkpoint, so this
+is the post-publication path rather than a claim of current public availability.
+
+For local validation or unreleased development only, install a built artifact
+or a source checkout:
+
+```bash
+# Install a locally built wheel or sdist
+python -m pip install path/to/relinkra-<version>-py3-none-any.whl
+
+# Or install from an unreleased source checkout
+git clone https://github.com/jojusa/relinkra.git
+cd relinkra
+python -m pip install .
+```
+
+Use `python -m pip install -e .` only when actively developing Relinkra. The
+source-checkout paths are not the normal user installation.
+
+### Initialize
+
+From inside the Git repository you want your agents to share:
+
+```bash
+relinkra --version
+relinkra init
+```
+
+### Connect an agent
+
+Run the supported command sequence for the host you use:
+
+```bash
+relinkra doctor
+relinkra connect check <host>
+relinkra connect plan <host>
+relinkra connect apply <host>
+```
+
+Supported hosts include `claude`, `opencode`, `codex`, `zcode`, and
+`devin-desktop`. OpenCode and Codex receive global, bare `relinkra-mcp`
+registrations; Codex uses `args = []`. ZCode receives a workspace-local
+configuration with the repository-root `cwd`.
+
+For the complete host list, run `relinkra connect list`. `connect check` is
+read-only, `connect plan` previews changes, and `connect apply` writes the
+configuration after creating a backup where supported.
+
+### Verify
+
+Restart the host so it can reread its configuration and launch Relinkra as its
+MCP (Model Context Protocol) server. Then record host-side proof:
+
+```bash
+relinkra connect verify <host> --proof <proof-file>
+```
+
+`connect apply` and `connect check` validate configuration only; they do not
+prove that a real host launched the server.
+
+### Use
+
+Once the connector is configured, ask normal project questions. You should not
+normally need to say "use Relinkra": the MCP server advertises when its shared
+context, memory, architecture, relationship, Git, or bounded-packet tools can
+reduce redundant exploration. It does not force those tools for trivial work,
+replace native tools, or make stale context authoritative.
+
+## What just happened?
+
+- `relinkra init` registered a portable identity for your repository and this workspace under `.relinkra/` — nothing else was touched.
+- `connect apply` added one MCP server entry named `relinkra` to the selected host configuration, after creating a timestamped backup where that host uses a writable config target.
+- Your agent can now request shared project context — memory, code references, and handoffs — through Relinkra instead of starting from zero.
+- Optional integrations are not required; their absence is reported honestly, and your agent's native tools remain untouched.
+
+## How do I know it worked?
+
+Run `relinkra doctor`, then `relinkra connect check <agent>`. After applying the
+configuration and restarting the host, use
+`relinkra connect verify <agent> --proof <proof-file>` when host-side evidence
+is required.
+
+Healthy means: no FAIL entries in `doctor` (WARN entries are typically optional components in degraded mode — safe to ignore for now), and `check` reports the registration as valid. This confirms configuration only; host runtime proof is a separate `connect verify` concern.
+
+## If something fails
+
+- **Python too old** — Relinkra requires Python 3.9+; check with `python --version`. See [Installation](docs/installation.md).
+- **Commands not found** — the virtual environment is not activated (or the console scripts directory is not on `PATH`). See [Troubleshooting](docs/troubleshooting.md).
+- **`init` refuses** — you are not inside a git repository. Run it from your project root. See [Installation](docs/installation.md).
+- **Outside Git or before `init`** — binding fails closed and does not create `.relinkra`; run `git init` for a new repository, then `relinkra init` before connecting a host.
+- **`doctor` reports a degraded backend** — an optional component is missing; the core still works. See [Troubleshooting](docs/troubleshooting.md).
+- **Host connector not detected** — the agent's config was not found; `connect inspect <agent>` shows what Relinkra probed. See [Connectors](docs/connectors.md).
+- **CBM unavailable or not certified on this platform** — code intelligence is unavailable; everything else works. See [CBM backend](docs/cbm-backend.md).
+- **Engram unavailable** — memory and handoffs report as unavailable; commands still succeed. See [Installation](docs/installation.md).
+
+Direct Engram use remains independently available; host binding does not depend
+on it and does not require direct CBM configuration.
+
+## Conflicting and stale context
+
+Relinkra combines evidence from source, Git, CBM graphs, memory, and handoffs.
+When those sources disagree it does not silently collapse them into one truth:
+older evidence stays visible and is marked stale/historical, current-source
+evidence is presented as current for current-code claims, and unresolvable
+conflicts are surfaced as unresolved rather than guessed away. See
+[Freshness, contradictions, and explainability](docs/freshness-explainability.md).
+
+## Optional external integrations
+
+Both are third-party projects, installed and managed independently. Neither is bundled with Relinkra, and neither is required for the quick start. Direct CBM setup is optional advanced/local configuration, not part of the normal public installation path.
+
+- **Codebase Memory (CBM)** — code intelligence backend maintained by [DeusData](https://github.com/DeusData/codebase-memory-mcp) (MIT license). Certified with the real binary on Windows; on Linux/macOS it is NOT certified, and Relinkra keeps working without it. Manage its index with `relinkra cbm status/index/refresh` — see [CBM backend](docs/cbm-backend.md).
+- **Engram** — persistent memory backend maintained by Gentleman Programming (MIT license). External and optional; without it, memory and handoffs report as unavailable and commands still exit successfully.
+
+## Current state
+
+- Python 3.9 through 3.14 is covered by the repository's CI matrix, with zero runtime dependencies.
+- Windows is currently certified. Linux/macOS exact-SHA certification and hosted CI evidence are pending; runner quota/billing availability is infrastructure evidence, not a product defect.
+- The package is pure Python. Public release requires retained exact wheel and sdist E2E results for both CLI and MCP, supplied as the mandatory `INSTALLED_CLI_MCP` evidence; unsupported platforms are not certified.
+- CBM managed certification is Windows-focused; Linux/macOS remain an honest degraded path.
+- The ZCode connector is structurally validated, but runtime certification is pending; broader host certification remains visible as external PARTIAL debt. Devin Cloud is unsupported (roadmap).
+- The public release check requires local regression/package evidence plus exact-SHA external evidence:
+
+  ```bash
+  RELEASE_SHA="$(git rev-parse HEAD)"
+  python tools/release_check.py --run-regression --run-packaging \
+    --evidence exact-release-head-evidence.json \
+    --require-sha "$RELEASE_SHA" --require public
+  ```
+  The evidence file must include the retained exact-artifact CLI/MCP results;
+  `release_check` does not collect installed E2E proof.
+- PyPI publication is not performed in this checkpoint; local validation uses built artifacts or a source checkout.
+
+## License
+
+Relinkra is released under the [MIT License](LICENSE).
+
+## Learn more
+
+- [Installation](docs/installation.md) — install, upgrade, and uninstall.
+- [Connectors](docs/connectors.md) — how agent hosts are connected.
+- [Product CLI](docs/cli.md) — the full command reference.
+- [Freshness, contradictions, and explainability](docs/freshness-explainability.md) — why context was shown and whether it is current.
+- [Release verification](docs/release.md) — CI, verification levels, and release gates (maintainer-facing).
+- [Contributing](CONTRIBUTING.md) — set up a development checkout and run the tests.
+- [Security](SECURITY.md) — supported versions and how to report a vulnerability.

relinkra-0.1.2/README.md

@@ -0,0 +1,165 @@
+# Relinkra
+
+## What Relinkra does
+
+Relinkra gives AI coding agents shared code intelligence, persistent memory, and optimized context: one codebase, one shared context, many agents. Every connected agent sees the same project memory, handoffs, and code references instead of re-discovering the repository alone. Relinkra optimizes the path to information; it does not restrict the agent's ability to search, reason, edit, or validate by itself.
+
+## Quick start
+
+Requirements: Python 3.9+ and Git. The quick start does not require any optional component.
+
+### Install
+
+The normal installation path after publication is:
+
+```bash
+python -m pip install relinkra
+```
+
+The literal `pip install relinkra` command is the equivalent user-facing
+contract. Relinkra is not being published to PyPI in this checkpoint, so this
+is the post-publication path rather than a claim of current public availability.
+
+For local validation or unreleased development only, install a built artifact
+or a source checkout:
+
+```bash
+# Install a locally built wheel or sdist
+python -m pip install path/to/relinkra-<version>-py3-none-any.whl
+
+# Or install from an unreleased source checkout
+git clone https://github.com/jojusa/relinkra.git
+cd relinkra
+python -m pip install .
+```
+
+Use `python -m pip install -e .` only when actively developing Relinkra. The
+source-checkout paths are not the normal user installation.
+
+### Initialize
+
+From inside the Git repository you want your agents to share:
+
+```bash
+relinkra --version
+relinkra init
+```
+
+### Connect an agent
+
+Run the supported command sequence for the host you use:
+
+```bash
+relinkra doctor
+relinkra connect check <host>
+relinkra connect plan <host>
+relinkra connect apply <host>
+```
+
+Supported hosts include `claude`, `opencode`, `codex`, `zcode`, and
+`devin-desktop`. OpenCode and Codex receive global, bare `relinkra-mcp`
+registrations; Codex uses `args = []`. ZCode receives a workspace-local
+configuration with the repository-root `cwd`.
+
+For the complete host list, run `relinkra connect list`. `connect check` is
+read-only, `connect plan` previews changes, and `connect apply` writes the
+configuration after creating a backup where supported.
+
+### Verify
+
+Restart the host so it can reread its configuration and launch Relinkra as its
+MCP (Model Context Protocol) server. Then record host-side proof:
+
+```bash
+relinkra connect verify <host> --proof <proof-file>
+```
+
+`connect apply` and `connect check` validate configuration only; they do not
+prove that a real host launched the server.
+
+### Use
+
+Once the connector is configured, ask normal project questions. You should not
+normally need to say "use Relinkra": the MCP server advertises when its shared
+context, memory, architecture, relationship, Git, or bounded-packet tools can
+reduce redundant exploration. It does not force those tools for trivial work,
+replace native tools, or make stale context authoritative.
+
+## What just happened?
+
+- `relinkra init` registered a portable identity for your repository and this workspace under `.relinkra/` — nothing else was touched.
+- `connect apply` added one MCP server entry named `relinkra` to the selected host configuration, after creating a timestamped backup where that host uses a writable config target.
+- Your agent can now request shared project context — memory, code references, and handoffs — through Relinkra instead of starting from zero.
+- Optional integrations are not required; their absence is reported honestly, and your agent's native tools remain untouched.
+
+## How do I know it worked?
+
+Run `relinkra doctor`, then `relinkra connect check <agent>`. After applying the
+configuration and restarting the host, use
+`relinkra connect verify <agent> --proof <proof-file>` when host-side evidence
+is required.
+
+Healthy means: no FAIL entries in `doctor` (WARN entries are typically optional components in degraded mode — safe to ignore for now), and `check` reports the registration as valid. This confirms configuration only; host runtime proof is a separate `connect verify` concern.
+
+## If something fails
+
+- **Python too old** — Relinkra requires Python 3.9+; check with `python --version`. See [Installation](docs/installation.md).
+- **Commands not found** — the virtual environment is not activated (or the console scripts directory is not on `PATH`). See [Troubleshooting](docs/troubleshooting.md).
+- **`init` refuses** — you are not inside a git repository. Run it from your project root. See [Installation](docs/installation.md).
+- **Outside Git or before `init`** — binding fails closed and does not create `.relinkra`; run `git init` for a new repository, then `relinkra init` before connecting a host.
+- **`doctor` reports a degraded backend** — an optional component is missing; the core still works. See [Troubleshooting](docs/troubleshooting.md).
+- **Host connector not detected** — the agent's config was not found; `connect inspect <agent>` shows what Relinkra probed. See [Connectors](docs/connectors.md).
+- **CBM unavailable or not certified on this platform** — code intelligence is unavailable; everything else works. See [CBM backend](docs/cbm-backend.md).
+- **Engram unavailable** — memory and handoffs report as unavailable; commands still succeed. See [Installation](docs/installation.md).
+
+Direct Engram use remains independently available; host binding does not depend
+on it and does not require direct CBM configuration.
+
+## Conflicting and stale context
+
+Relinkra combines evidence from source, Git, CBM graphs, memory, and handoffs.
+When those sources disagree it does not silently collapse them into one truth:
+older evidence stays visible and is marked stale/historical, current-source
+evidence is presented as current for current-code claims, and unresolvable
+conflicts are surfaced as unresolved rather than guessed away. See
+[Freshness, contradictions, and explainability](docs/freshness-explainability.md).
+
+## Optional external integrations
+
+Both are third-party projects, installed and managed independently. Neither is bundled with Relinkra, and neither is required for the quick start. Direct CBM setup is optional advanced/local configuration, not part of the normal public installation path.
+
+- **Codebase Memory (CBM)** — code intelligence backend maintained by [DeusData](https://github.com/DeusData/codebase-memory-mcp) (MIT license). Certified with the real binary on Windows; on Linux/macOS it is NOT certified, and Relinkra keeps working without it. Manage its index with `relinkra cbm status/index/refresh` — see [CBM backend](docs/cbm-backend.md).
+- **Engram** — persistent memory backend maintained by Gentleman Programming (MIT license). External and optional; without it, memory and handoffs report as unavailable and commands still exit successfully.
+
+## Current state
+
+- Python 3.9 through 3.14 is covered by the repository's CI matrix, with zero runtime dependencies.
+- Windows is currently certified. Linux/macOS exact-SHA certification and hosted CI evidence are pending; runner quota/billing availability is infrastructure evidence, not a product defect.
+- The package is pure Python. Public release requires retained exact wheel and sdist E2E results for both CLI and MCP, supplied as the mandatory `INSTALLED_CLI_MCP` evidence; unsupported platforms are not certified.
+- CBM managed certification is Windows-focused; Linux/macOS remain an honest degraded path.
+- The ZCode connector is structurally validated, but runtime certification is pending; broader host certification remains visible as external PARTIAL debt. Devin Cloud is unsupported (roadmap).
+- The public release check requires local regression/package evidence plus exact-SHA external evidence:
+
+  ```bash
+  RELEASE_SHA="$(git rev-parse HEAD)"
+  python tools/release_check.py --run-regression --run-packaging \
+    --evidence exact-release-head-evidence.json \
+    --require-sha "$RELEASE_SHA" --require public
+  ```
+  The evidence file must include the retained exact-artifact CLI/MCP results;
+  `release_check` does not collect installed E2E proof.
+- PyPI publication is not performed in this checkpoint; local validation uses built artifacts or a source checkout.
+
+## License
+
+Relinkra is released under the [MIT License](LICENSE).
+
+## Learn more
+
+- [Installation](docs/installation.md) — install, upgrade, and uninstall.
+- [Connectors](docs/connectors.md) — how agent hosts are connected.
+- [Product CLI](docs/cli.md) — the full command reference.
+- [Freshness, contradictions, and explainability](docs/freshness-explainability.md) — why context was shown and whether it is current.
+- [Release verification](docs/release.md) — CI, verification levels, and release gates (maintainer-facing).
+- [Contributing](CONTRIBUTING.md) — set up a development checkout and run the tests.
+- [Security](SECURITY.md) — supported versions and how to report a vulnerability.

relinkra-0.1.2/pyproject.toml

@@ -0,0 +1,57 @@
+# Relinkra packaging contract.
+#
+# The version lives in exactly one place: relinkra/__init__.py (__version__).
+# This file reads it dynamically; never duplicate the version string here.
+# tests/test_packaging.py guards that contract.
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "relinkra"
+dynamic = ["version"]
+description = "Shared code intelligence, persistent memory and optimized context for AI coding agents."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "José Julián Sánchez Rodríguez" },
+]
+# PEP 639 SPDX expression (setuptools >= 77). Per PyPA rules this must not
+# be combined with a deprecated "License ::" classifier.
+license = "MIT"
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development",
+]
+
+[project.urls]
+Homepage = "https://github.com/jojusa/relinkra"
+Repository = "https://github.com/jojusa/relinkra"
+Issues = "https://github.com/jojusa/relinkra/issues"
+
+# Console entry points. Every target is an existing `main() -> int`;
+# no wrappers, no generated launch logic.
+#   relinkra      — the user-facing front door (init/status/doctor/project/version/connect)
+#   relinkra-mcp  — the MCP server endpoint hosts connect to
+#                   (name pre-agreed in relinkra/connectors.py: CONSOLE_SCRIPT)
+[project.scripts]
+relinkra = "relinkra.product_cli:main"
+relinkra-mcp = "relinkra.mcp_cli:main"
+
+[tool.setuptools]
+# Flat layout, declared explicitly: auto-discovery would also see tests/
+# and fail or, worse, silently ship the test suite inside the package.
+packages = ["relinkra"]
+
+[tool.setuptools.dynamic]
+version = { attr = "relinkra.__version__" }

relinkra-0.1.2/relinkra/__init__.py

@@ -0,0 +1,47 @@
+"""Relinkra — portable logical project identity above path-derived CBM identity."""
+
+from .identity import (
+    AmbiguousIdentityError,
+    CASE_INSENSITIVE_HOSTS,
+    LogicalProject,
+    RepositoryIdentity,
+    Workspace,
+    canonicalize_path,
+    choose_remote,
+    derive_project_id,
+    derive_workspace_id,
+    discover_repository_identity,
+    explicit_identity,
+    local_root_identity,
+    normalize_os_family,
+    normalize_remote_url,
+    redact_url,
+)
+from .registry import Registry, RegistryError
+from .cbm import CBMBinaryInfo, CBMProjectIdentity, cbm_db_path, workspace_cbm_record
+
+__version__ = "0.1.2"
+
+__all__ = [
+    "AmbiguousIdentityError",
+    "CASE_INSENSITIVE_HOSTS",
+    "CBMBinaryInfo",
+    "CBMProjectIdentity",
+    "LogicalProject",
+    "Registry",
+    "RegistryError",
+    "RepositoryIdentity",
+    "Workspace",
+    "canonicalize_path",
+    "cbm_db_path",
+    "choose_remote",
+    "derive_project_id",
+    "derive_workspace_id",
+    "discover_repository_identity",
+    "explicit_identity",
+    "local_root_identity",
+    "normalize_os_family",
+    "normalize_remote_url",
+    "redact_url",
+    "workspace_cbm_record",
+]