cite2site 1.0.0__tar.gz

cite2site-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cite2Site contributors
+
+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.

cite2site-1.0.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: cite2site
+Version: 1.0.0
+Summary: Source-clean citations that don't touch your files. Record evidence outside the file, replay it to check if it still holds.
+Author: Cite2Site contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/paragon-ux/Cite2Site
+Project-URL: Documentation, https://paragon-ux.github.io/Cite2Site/
+Project-URL: Repository, https://github.com/paragon-ux/Cite2Site
+Keywords: citations,evidence,verification,source-clean,append-only,cli
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: context-menu
+Dynamic: license-file
+
+# Cite2Site
+
+**v1.0** — Source-clean citations that don't touch your files.
+
+Cite2Site lets you point at evidence — in code, in a doc, on a page —
+without leaving a mark on it. Every citation lives in a separate,
+append-only ledger. Replay that history at any time and Cite2Site tells
+you whether the evidence still holds: still there, changed, gone, or —
+when it genuinely can't verify — it says so instead of guessing.
+
+## Why doesn't it touch my files?
+
+Most citation tools want to write something into the thing you're citing —
+a comment, a bookmark, a hidden ID. That falls apart the moment the source
+isn't yours to edit: a shared PDF, someone else's code, an exported chat
+log, a spreadsheet with strict formatting. Cite2Site sidesteps that
+entirely:
+
+```text
+select evidence -> source-clean citation -> inspectable citation projection
+```
+
+The current implementation uses the CLI. Integration contracts and reference
+examples for editor, browser, and document-tool builders are delivered;
+native right-click plugins are deferred.
+
+The source file never changes. Citations live in a dedicated `.c2s`
+repository as an append-only history, and everything you see — status,
+exports, the published site — is generated by replaying that history
+against the current state of your files.
+
+## Quick Start — Human Path (Right-Click)
+
+```bash
+pip install cite2site
+c2s init
+echo "Alpha claim" > notes.md
+c2s cite-selection --artifact notes.md --start 0 --end 11 --handle ALPHA
+
+# Install the right-click context menu
+c2s install-context-menu
+```
+
+Right-click any file in Explorer → **Cite2Site → Look up citations here** to
+see what citations exist at that position. **Cite selection here** to create
+a new citation.
+
+The `lookup-actions` command behind the menu is the same contract editor
+plugins and browser extensions call. See the **[Integration Contract](build-docs/architecture/INTEGRATION_CONTRACT.md)**
+for the API, and the **[User Guide](build-docs/guides/USER_GUIDE.md)** for
+everyday workflows.
+
+To uninstall: `c2s uninstall-context-menu`.
+
+## Quick Start — Agent Path (CLI)
+
+Agents and automation use the deterministic JSON CLI. Install, init, cite,
+query, export:
+
+```bash
+pip install cite2site
+echo -e "Alpha claim\nBeta claim\n" > notes.md
+c2s init
+c2s cite-selection --artifact notes.md --start 0 --end 11 --handle NOTE-1
+c2s citations --artifact notes.md --format json
+c2s export
+```
+
+Every command returns JSON. Errors are structured. Citations never touch
+your files. See the **[Agent Guide](build-docs/guides/AGENT_GUIDE.md)** for
+batch operations, workflow commands, and the full agent contract.
+
+A few things worth knowing:
+
+- **Handles are aliases, not identity.** Rename one anytime — the
+  underlying citation ID never changes.
+- **Publication policy defaults to metadata-only.** Default exports omit
+  accepted evidence text; richer snippet and private-link modes require
+  explicit repository authorization.
+- **The source artifact is never rewritten**, no matter which command you
+  run.
+
+## Where things stand
+
+Cite2Site v1.0 is a working CLI tool for text and Markdown files. It creates
+source-clean citations, validates hash chains, replays citation history
+against current files, and exports grouped JSON and MkDocs sites — all with
+metadata-only privacy by default. 98 tests cover the core engine.
+
+Beyond text and Markdown, a **ConverterAdapter** turns DOCX, PDF, and XLSX
+into canonical text by shelling out to standard converters (pandoc for DOCX,
+pdftotext for PDF). The architecture separates *how you get text out of an
+artifact* from *how citation history, verification, and replay work* — new
+formats extend the first part without touching the second. When a converter
+isn't available, Cite2Site reports the limitation honestly rather than
+returning a guess.
+
+The v1 stable contract is frozen: 15 CLI commands, 7 event types, 38 stable
+error codes, 4 privacy modes, and 6 schema identifiers. See
+[`build-docs/internal/CURRENT_STATUS_MATRIX.md`](build-docs/internal/CURRENT_STATUS_MATRIX.md)
+for the full capability inventory.
+
+## Guides
+
+- **[User Guide](build-docs/guides/USER_GUIDE.md)** — everyday commands,
+  fixing mistakes, handles, publishing, batch citations, error codes.
+- **[Agent Guide](build-docs/guides/AGENT_GUIDE.md)** — deterministic JSON CLI,
+  agent workflows, batch schema, privacy modes, integration contract.
+- **[Integration Contract](build-docs/architecture/INTEGRATION_CONTRACT.md)** —
+  for editor, browser, and document-tool builders.
+- **[v1 Stable Contract](build-docs/architecture/V1_STABLE_CONTRACT.md)** —
+  every frozen command, event field, error code, projection field, and URL shape.
+
+## Running the tests
+
+```bash
+python -m unittest discover -s tests
+```
+
+## If you're an agent picking this up
+
+Start with [`AGENTS.md`](AGENTS.md). It has the reading order, the
+invariants that keep citations trustworthy, and the session gate protocol
+this project uses instead of ad-hoc review. Don't skip it — the short
+version is "the source file is sacred, everything else is a replay."
+
+## Digging deeper
+
+The full build plan — requirements, workflows, whitepaper, protocol and
+implementation specs, current status, and ADRs — lives under
+[`build-docs/`](build-docs/README.md).

cite2site-1.0.0/README.md

@@ -0,0 +1,131 @@
+# Cite2Site
+
+**v1.0** — Source-clean citations that don't touch your files.
+
+Cite2Site lets you point at evidence — in code, in a doc, on a page —
+without leaving a mark on it. Every citation lives in a separate,
+append-only ledger. Replay that history at any time and Cite2Site tells
+you whether the evidence still holds: still there, changed, gone, or —
+when it genuinely can't verify — it says so instead of guessing.
+
+## Why doesn't it touch my files?
+
+Most citation tools want to write something into the thing you're citing —
+a comment, a bookmark, a hidden ID. That falls apart the moment the source
+isn't yours to edit: a shared PDF, someone else's code, an exported chat
+log, a spreadsheet with strict formatting. Cite2Site sidesteps that
+entirely:
+
+```text
+select evidence -> source-clean citation -> inspectable citation projection
+```
+
+The current implementation uses the CLI. Integration contracts and reference
+examples for editor, browser, and document-tool builders are delivered;
+native right-click plugins are deferred.
+
+The source file never changes. Citations live in a dedicated `.c2s`
+repository as an append-only history, and everything you see — status,
+exports, the published site — is generated by replaying that history
+against the current state of your files.
+
+## Quick Start — Human Path (Right-Click)
+
+```bash
+pip install cite2site
+c2s init
+echo "Alpha claim" > notes.md
+c2s cite-selection --artifact notes.md --start 0 --end 11 --handle ALPHA
+
+# Install the right-click context menu
+c2s install-context-menu
+```
+
+Right-click any file in Explorer → **Cite2Site → Look up citations here** to
+see what citations exist at that position. **Cite selection here** to create
+a new citation.
+
+The `lookup-actions` command behind the menu is the same contract editor
+plugins and browser extensions call. See the **[Integration Contract](build-docs/architecture/INTEGRATION_CONTRACT.md)**
+for the API, and the **[User Guide](build-docs/guides/USER_GUIDE.md)** for
+everyday workflows.
+
+To uninstall: `c2s uninstall-context-menu`.
+
+## Quick Start — Agent Path (CLI)
+
+Agents and automation use the deterministic JSON CLI. Install, init, cite,
+query, export:
+
+```bash
+pip install cite2site
+echo -e "Alpha claim\nBeta claim\n" > notes.md
+c2s init
+c2s cite-selection --artifact notes.md --start 0 --end 11 --handle NOTE-1
+c2s citations --artifact notes.md --format json
+c2s export
+```
+
+Every command returns JSON. Errors are structured. Citations never touch
+your files. See the **[Agent Guide](build-docs/guides/AGENT_GUIDE.md)** for
+batch operations, workflow commands, and the full agent contract.
+
+A few things worth knowing:
+
+- **Handles are aliases, not identity.** Rename one anytime — the
+  underlying citation ID never changes.
+- **Publication policy defaults to metadata-only.** Default exports omit
+  accepted evidence text; richer snippet and private-link modes require
+  explicit repository authorization.
+- **The source artifact is never rewritten**, no matter which command you
+  run.
+
+## Where things stand
+
+Cite2Site v1.0 is a working CLI tool for text and Markdown files. It creates
+source-clean citations, validates hash chains, replays citation history
+against current files, and exports grouped JSON and MkDocs sites — all with
+metadata-only privacy by default. 98 tests cover the core engine.
+
+Beyond text and Markdown, a **ConverterAdapter** turns DOCX, PDF, and XLSX
+into canonical text by shelling out to standard converters (pandoc for DOCX,
+pdftotext for PDF). The architecture separates *how you get text out of an
+artifact* from *how citation history, verification, and replay work* — new
+formats extend the first part without touching the second. When a converter
+isn't available, Cite2Site reports the limitation honestly rather than
+returning a guess.
+
+The v1 stable contract is frozen: 15 CLI commands, 7 event types, 38 stable
+error codes, 4 privacy modes, and 6 schema identifiers. See
+[`build-docs/internal/CURRENT_STATUS_MATRIX.md`](build-docs/internal/CURRENT_STATUS_MATRIX.md)
+for the full capability inventory.
+
+## Guides
+
+- **[User Guide](build-docs/guides/USER_GUIDE.md)** — everyday commands,
+  fixing mistakes, handles, publishing, batch citations, error codes.
+- **[Agent Guide](build-docs/guides/AGENT_GUIDE.md)** — deterministic JSON CLI,
+  agent workflows, batch schema, privacy modes, integration contract.
+- **[Integration Contract](build-docs/architecture/INTEGRATION_CONTRACT.md)** —
+  for editor, browser, and document-tool builders.
+- **[v1 Stable Contract](build-docs/architecture/V1_STABLE_CONTRACT.md)** —
+  every frozen command, event field, error code, projection field, and URL shape.
+
+## Running the tests
+
+```bash
+python -m unittest discover -s tests
+```
+
+## If you're an agent picking this up
+
+Start with [`AGENTS.md`](AGENTS.md). It has the reading order, the
+invariants that keep citations trustworthy, and the session gate protocol
+this project uses instead of ad-hoc review. Don't skip it — the short
+version is "the source file is sacred, everything else is a replay."
+
+## Digging deeper
+
+The full build plan — requirements, workflows, whitepaper, protocol and
+implementation specs, current status, and ADRs — lives under
+[`build-docs/`](build-docs/README.md).

cite2site-1.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cite2site"
+version = "1.0.0"
+description = "Source-clean citations that don't touch your files. Record evidence outside the file, replay it to check if it still holds."
+requires-python = ">=3.11"
+dependencies = ["context-menu"]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+authors = [{name = "Cite2Site contributors"}]
+keywords = ["citations", "evidence", "verification", "source-clean", "append-only", "cli"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Text Processing",
+    "Topic :: Software Development :: Documentation",
+]
+
+[project.urls]
+Homepage = "https://github.com/paragon-ux/Cite2Site"
+Documentation = "https://paragon-ux.github.io/Cite2Site/"
+Repository = "https://github.com/paragon-ux/Cite2Site"
+
+[project.scripts]
+c2s = "c2s.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

cite2site-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cite2site-1.0.0/src/c2s/__init__.py

@@ -0,0 +1,24 @@
+"""Cite2Site first-slice implementation."""
+
+__all__ = [
+    "__version__",
+    "BaseAdapter",
+    "FilesystemTextAdapter",
+    "MarkdownAdapter",
+    "AdapterArtifact",
+    "get_adapter",
+    "adapter_for_uri",
+    "adapter_diagnostics",
+]
+
+__version__ = "1.0.0"
+
+from .adapter import (  # noqa: E402  — re-export after version
+    AdapterArtifact,
+    BaseAdapter,
+    FilesystemTextAdapter,
+    MarkdownAdapter,
+    adapter_diagnostics,
+    adapter_for_uri,
+    get_adapter,
+)

cite2site-1.0.0/src/c2s/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cite2site-1.0.0/src/c2s/_context_menu.py

@@ -0,0 +1,44 @@
+"""Windows context-menu integration for Cite2Site.
+
+Provides `c2s install-context-menu` and `c2s uninstall-context-menu` CLI
+commands.  Registers Cite2Site entries in the Windows Explorer right-click
+menu so users can look up citations and cite selections directly from any
+file.
+"""
+from __future__ import annotations
+
+
+def _menu_entries() -> list[dict[str, str]]:
+    """Return the context-menu entries to register."""
+    return [
+        {
+            "name": "Look up citations here",
+            "command": 'cmd /k c2s lookup-actions --artifact "%1" --start 0 --end 0',
+        },
+        {
+            "name": "Cite selection here",
+            "command": 'cmd /k c2s cite-selection --artifact "%1" --start 0 --end 0',
+        },
+    ]
+
+
+def install() -> None:
+    """Register Cite2Site in the Windows Explorer context menu."""
+    from context_menu import menus
+
+    entries = [
+        menus.ContextCommand(name=e["name"], command=e["command"])
+        for e in _menu_entries()
+    ]
+    menu = menus.ContextMenu(name="Cite2Site", type="FILES", entries=entries)
+    menu.compile()
+    print("Cite2Site added to Windows right-click menu.")
+    print("Right-click any file -> Cite2Site -> Look up citations here / Cite selection here")
+
+
+def uninstall() -> None:
+    """Remove Cite2Site from the Windows Explorer context menu."""
+    from context_menu import menus
+
+    menus.ContextMenu(name="Cite2Site", type="FILES", entries=[]).remove()
+    print("Cite2Site removed from Windows right-click menu.")