supamem 0.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. supamem/__init__.py +2 -0
  2. supamem/__main__.py +4 -0
  3. supamem/cli.py +267 -0
  4. supamem/config.py +168 -0
  5. supamem/config_io.py +227 -0
  6. supamem/console.py +116 -0
  7. supamem/doctor.py +201 -0
  8. supamem/embedders/__init__.py +33 -0
  9. supamem/embedders/bm25.py +26 -0
  10. supamem/embedders/minilm.py +22 -0
  11. supamem/eval/__init__.py +22 -0
  12. supamem/eval/auto_goldens.py +70 -0
  13. supamem/eval/goldens/__init__.py +0 -0
  14. supamem/eval/goldens/phase_80_1_tuned_hybrid.jsonl +33 -0
  15. supamem/eval/runner.py +159 -0
  16. supamem/hooks/__init__.py +31 -0
  17. supamem/hooks/claude_code.py +217 -0
  18. supamem/hooks/cursor.py +194 -0
  19. supamem/hooks/opencode.py +30 -0
  20. supamem/indexer/__init__.py +179 -0
  21. supamem/indexer/chunker.py +69 -0
  22. supamem/indexer/manifest.py +56 -0
  23. supamem/init.py +214 -0
  24. supamem/install/__init__.py +98 -0
  25. supamem/install/_types.py +13 -0
  26. supamem/install/claude_code.py +211 -0
  27. supamem/install/cursor.py +178 -0
  28. supamem/install/opencode.py +136 -0
  29. supamem/install/share.py +74 -0
  30. supamem/mcp_server.py +259 -0
  31. supamem/migrate.py +214 -0
  32. supamem/retrieval/__init__.py +22 -0
  33. supamem/retrieval/bm25.py +21 -0
  34. supamem/retrieval/dense.py +37 -0
  35. supamem/retrieval/tuned_hybrid.py +203 -0
  36. supamem/retrieval/types.py +20 -0
  37. supamem/share/__init__.py +0 -0
  38. supamem/share/commands/__init__.py +0 -0
  39. supamem/share/commands/sm-search.md +33 -0
  40. supamem/share/cursor-rules/__init__.py +0 -0
  41. supamem/share/cursor-rules/dual-memory.mdc +33 -0
  42. supamem/share/hooks/__init__.py +0 -0
  43. supamem/share/hooks/qdrant-semantic-guard.sh +36 -0
  44. supamem/share/rules/__init__.py +0 -0
  45. supamem/share/rules/dual-memory.md +49 -0
  46. supamem/share/skills/__init__.py +0 -0
  47. supamem/share/skills/supamem/SKILL.md +41 -0
  48. supamem/share/skills/supamem/__init__.py +0 -0
  49. supamem/stats/__init__.py +99 -0
  50. supamem/stats/counter.py +138 -0
  51. supamem/update_check.py +249 -0
  52. supamem-0.1.1.dist-info/METADATA +408 -0
  53. supamem-0.1.1.dist-info/RECORD +56 -0
  54. supamem-0.1.1.dist-info/WHEEL +4 -0
  55. supamem-0.1.1.dist-info/entry_points.txt +14 -0
  56. supamem-0.1.1.dist-info/licenses/LICENSE +21 -0
supamem/__init__.py ADDED
@@ -0,0 +1,2 @@
1
+ """supamem — project-agnostic dual-memory tooling."""
2
+ __version__ = "0.1.1"
supamem/__main__.py ADDED
@@ -0,0 +1,4 @@
1
+ from supamem.cli import main
2
+
3
+ if __name__ == "__main__":
4
+ main()
supamem/cli.py ADDED
@@ -0,0 +1,267 @@
1
+ """supamem CLI — Typer app dispatching to subcommands."""
2
+ from __future__ import annotations
3
+
4
+ from enum import Enum
5
+ from typing import Optional
6
+
7
+ import typer
8
+
9
+ from supamem import __version__
10
+ from supamem.console import CREDIT_LINE, console, err_console
11
+
12
+ app = typer.Typer(
13
+ name="supamem",
14
+ no_args_is_help=True,
15
+ add_completion=False,
16
+ rich_markup_mode="rich",
17
+ help="Project-agnostic dual-memory tooling for Claude Code, Cursor, and opencode.",
18
+ )
19
+
20
+
21
+ def _version_callback(value: bool) -> None:
22
+ if value:
23
+ console.print(
24
+ f"[supamem.brand]supamem[/supamem.brand] "
25
+ f"[supamem.accent]v{__version__}[/supamem.accent]"
26
+ )
27
+ console.print(CREDIT_LINE)
28
+ raise typer.Exit(0)
29
+
30
+
31
+ @app.callback()
32
+ def _root(
33
+ version: bool = typer.Option(
34
+ False,
35
+ "--version",
36
+ callback=_version_callback,
37
+ is_eager=True,
38
+ help="Show version and exit.",
39
+ ),
40
+ ) -> None:
41
+ """supamem root command."""
42
+ return None
43
+
44
+
45
+ def _stub(name: str) -> None:
46
+ err_console.print(
47
+ f"[supamem.warn]⚠[/supamem.warn] [supamem.accent]supamem {name}[/supamem.accent] "
48
+ f"[supamem.muted]is not yet implemented (lands in a later 80.6 plan)[/supamem.muted]"
49
+ )
50
+ raise typer.Exit(2)
51
+
52
+
53
+ class Transport(str, Enum):
54
+ stdio = "stdio"
55
+ http = "http"
56
+
57
+
58
+ class Client(str, Enum):
59
+ claude_code = "claude-code"
60
+ cursor = "cursor"
61
+ opencode = "opencode"
62
+
63
+
64
+ @app.command("index")
65
+ def cmd_index(
66
+ target: str = typer.Option("tuned", "--target", help="Retrieval target (e.g. tuned, dense, bm25)."),
67
+ force: bool = typer.Option(False, "--force", help="Re-embed even if manifest is current."),
68
+ snapshot: Optional[str] = typer.Option(None, "--snapshot", help="Path to snapshot artifact (e.g. cursor)."),
69
+ ) -> None:
70
+ """Embed dev memories into Qdrant using the locked tuned-hybrid pipeline."""
71
+ from supamem.config import load_config
72
+ from supamem.console import info
73
+ from supamem.indexer import run_index
74
+
75
+ cfg, _chain = load_config()
76
+ if snapshot == "cursor":
77
+ from supamem.hooks.cursor import run_snapshot
78
+
79
+ info(f"snapshot → cursor ({cfg.collection})")
80
+ raise typer.Exit(run_snapshot(config=cfg))
81
+
82
+ info(f"indexing → {cfg.collection} (target={target}, force={force})")
83
+ raise typer.Exit(run_index(target=target, force=force, sources=cfg.sources, config=cfg))
84
+
85
+
86
+ @app.command("mcp-server")
87
+ def cmd_mcp_server(
88
+ transport: Transport = typer.Option(Transport.stdio, "--transport", help="MCP transport: stdio or http."),
89
+ port: int = typer.Option(8765, "--port", help="HTTP port (only used when --transport http)."),
90
+ host: str = typer.Option("127.0.0.1", "--host", help="HTTP bind host (only used when --transport http)."),
91
+ ) -> None:
92
+ """Run the dual-memory MCP server."""
93
+ from supamem.config import load_config
94
+ from supamem.mcp_server import run_http, run_stdio
95
+
96
+ cfg, _chain = load_config()
97
+ if transport is Transport.stdio:
98
+ run_stdio(cfg)
99
+ elif transport is Transport.http:
100
+ run_http(cfg, port=port, host=host)
101
+ else:
102
+ err_console.print(f"[supamem.err]✗[/supamem.err] unknown transport: {transport}")
103
+ raise typer.Exit(2)
104
+
105
+
106
+ @app.command("hook")
107
+ def cmd_hook(
108
+ client: str = typer.Argument(..., help="Target client (claude-code, opencode, cursor)."),
109
+ file_path: Optional[str] = typer.Option(None, "--file-path", help="Path being edited (for edit-time hooks)."),
110
+ ) -> None:
111
+ """Per-client session/edit hooks."""
112
+ from pathlib import Path
113
+
114
+ from supamem.config import load_config
115
+ from supamem.hooks import dispatch
116
+
117
+ cfg, _chain = load_config()
118
+ fp = Path(file_path) if file_path else None
119
+ raise typer.Exit(dispatch(client=client, file_path=fp, config=cfg))
120
+
121
+
122
+ class StatsWindow(str, Enum):
123
+ today = "today"
124
+ week = "week"
125
+ all_ = "all"
126
+
127
+
128
+ class StatsFormat(str, Enum):
129
+ table = "table"
130
+ json = "json"
131
+
132
+
133
+ @app.command("stats")
134
+ def cmd_stats(
135
+ show: StatsWindow = typer.Option(StatsWindow.today, "--show", help="Time window."),
136
+ fmt: StatsFormat = typer.Option(StatsFormat.table, "--format", help="Output format."),
137
+ ) -> None:
138
+ """Render Welford schema-v2 usage counters."""
139
+ from supamem.stats import render
140
+
141
+ out = render(show=show.value, format=fmt.value)
142
+ if fmt is StatsFormat.table:
143
+ console.print(f"[supamem.brand]{out.splitlines()[0]}[/supamem.brand]")
144
+ for line in out.splitlines()[1:]:
145
+ console.print(line)
146
+ else:
147
+ console.print_json(out)
148
+
149
+
150
+ @app.command("eval")
151
+ def cmd_evalbench(
152
+ regress: bool = typer.Option(False, "--regress", help="Run regression suite against bundled goldens."),
153
+ goldens: Optional[str] = typer.Option(None, "--goldens", help="Custom goldens JSONL path."),
154
+ ) -> None:
155
+ """Run the regression harness against the Phase 80.1 golden corpus."""
156
+ from supamem.config import load_config
157
+ from supamem.eval.runner import run_bench
158
+
159
+ cfg, _chain = load_config()
160
+ raise typer.Exit(run_bench(regress=regress, goldens_path=goldens, config=cfg))
161
+
162
+
163
+ @app.command("install")
164
+ def cmd_install(
165
+ client: Optional[Client] = typer.Option(None, "--client", help="Target client (claude-code, cursor, opencode)."),
166
+ dry_run: bool = typer.Option(False, "--dry-run", help="Show planned config patches without applying."),
167
+ ) -> None:
168
+ """Patch a client config to point at supamem."""
169
+ from supamem.install import install as do_install
170
+
171
+ raise typer.Exit(do_install(client=client.value if client else None, dry_run=dry_run))
172
+
173
+
174
+ @app.command("uninstall")
175
+ def cmd_uninstall(
176
+ client: Optional[Client] = typer.Option(None, "--client", help="Target client (claude-code, cursor, opencode)."),
177
+ ) -> None:
178
+ """Reverse `supamem install` on a client."""
179
+ from supamem.install import uninstall as do_uninstall
180
+
181
+ raise typer.Exit(do_uninstall(client=client.value if client else None))
182
+
183
+
184
+ @app.command("doctor")
185
+ def cmd_doctor(
186
+ show_secrets: bool = typer.Option(
187
+ False, "--show-secrets", help="Show qdrant_api_key in plain text (DANGEROUS)."
188
+ ),
189
+ ) -> None:
190
+ """Probe Qdrant, print resolved config chain, report version drift."""
191
+ from supamem.doctor import run_doctor
192
+
193
+ raise typer.Exit(run_doctor(redact_secrets=not show_secrets))
194
+
195
+
196
+ @app.command("init")
197
+ def cmd_init(
198
+ yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompts."),
199
+ force: bool = typer.Option(False, "--force", help="Overwrite existing config / collection."),
200
+ qdrant_url: Optional[str] = typer.Option(None, "--qdrant-url", help="Qdrant URL (defaults to QDRANT_URL env or http://localhost:6333)."),
201
+ ) -> None:
202
+ """Greenfield bootstrap on a new project."""
203
+ from pathlib import Path
204
+
205
+ from supamem.init import run_init
206
+
207
+ raise typer.Exit(run_init(cwd=Path.cwd(), yes=yes, qdrant_url=qdrant_url, force=force))
208
+
209
+
210
+ class MigratePath(str, Enum):
211
+ coexist = "coexist"
212
+ migrate = "migrate"
213
+ adopt_as_is = "adopt-as-is"
214
+
215
+
216
+ @app.command("migrate")
217
+ def cmd_migrate(
218
+ source: str = typer.Option(..., "--source", help="Existing collection name to migrate from."),
219
+ target: Optional[str] = typer.Option(None, "--target", help="Target collection (defaults to supamem-<cwd-slug>)."),
220
+ path: MigratePath = typer.Option(MigratePath.coexist, "--path", help="Migration strategy."),
221
+ yes: bool = typer.Option(False, "--yes", help="Confirm destructive migration paths."),
222
+ ) -> None:
223
+ """Brownfield migration from a pre-existing dev_memory collection."""
224
+ from pathlib import Path
225
+
226
+ from supamem.config import load_config
227
+ from supamem.console import info
228
+ from supamem.init import _slugify
229
+ from supamem.migrate import run_migrate
230
+
231
+ cfg, _chain = load_config()
232
+ tgt = target or f"supamem-{_slugify(Path.cwd().name)}"
233
+ info(f"migrate {source!r} → {tgt!r} (path={path.value}, yes={yes})")
234
+
235
+ from qdrant_client import QdrantClient
236
+
237
+ client = QdrantClient(
238
+ url=cfg.qdrant_url,
239
+ api_key=cfg.qdrant_api_key or None,
240
+ check_compatibility=False,
241
+ timeout=60,
242
+ )
243
+ raise typer.Exit(run_migrate(client, source, tgt, path=path.value, yes=yes))
244
+
245
+
246
+ def main() -> None:
247
+ # Fire-and-forget update probe — writes cache for *next* invocation. Skipped
248
+ # when env vars opt out, when stderr is non-TTY (piped/redirected output),
249
+ # or when the in-process probe fails for any reason. Never blocks.
250
+ from supamem.update_check import get_pending_notification, start_background_check
251
+
252
+ start_background_check(__version__)
253
+ try:
254
+ app()
255
+ finally:
256
+ # Print any update notice queued from the *previous* invocation. Goes
257
+ # to stderr so JSON consumers piping stdout are unaffected.
258
+ notice = get_pending_notification(__version__)
259
+ if notice:
260
+ try:
261
+ err_console.print(notice, end="")
262
+ except Exception:
263
+ pass
264
+
265
+
266
+ if __name__ == "__main__":
267
+ main()
supamem/config.py ADDED
@@ -0,0 +1,168 @@
1
+ """Per-project config discovery for supamem (D-38 precedence ladder).
2
+
3
+ Resolution order (highest to lowest):
4
+
5
+ 1. ``$SUPAMEM_CONFIG`` env var pointing to an explicit TOML file
6
+ 2. ``<cwd>/.supamem/config.toml`` (the canonical project config)
7
+ 3. ``<cwd>/pyproject.toml`` ``[tool.supamem]`` section
8
+ 4. Auto-detect: presence of ``<cwd>/.claude/insights/`` seeds ``sources``
9
+ 5. Defaults baked into ``ResolvedConfig``
10
+
11
+ Per-key resolution: each field is resolved independently. A user can put just
12
+ ``QDRANT_URL`` in env and inherit everything else from a TOML file.
13
+
14
+ Legacy single-key env vars (compatibility with earlier embed-dev-memories.py):
15
+ - ``QDRANT_URL``, ``QDRANT_API_KEY``, ``COLLECTION_NAME``, ``EMBEDDING_MODEL``
16
+
17
+ Implementation note: lower-precedence rungs are applied FIRST, then higher
18
+ rungs unconditionally overwrite. The ``ConfigChain`` record always reflects the
19
+ last writer per field, which matches user-visible precedence.
20
+
21
+ NOTE on secrets: ``ResolvedConfig.qdrant_api_key`` may contain a user secret.
22
+ ``supamem doctor`` (plan 11) MUST redact this field by default — see STRIDE
23
+ T-80.6-03-01.
24
+ """
25
+ from __future__ import annotations
26
+
27
+ import os
28
+ import tomllib
29
+ from dataclasses import dataclass, field
30
+ from pathlib import Path
31
+ from typing import Any, Literal
32
+
33
+ Source = Literal["env", "supamem_toml", "pyproject", "auto_detect", "default"]
34
+
35
+
36
+ @dataclass
37
+ class ResolvedConfig:
38
+ qdrant_url: str = "http://localhost:6333"
39
+ qdrant_api_key: str = ""
40
+ collection: str = "dev_memory_tuned_hybrid"
41
+ embedder: str = "minilm"
42
+ chunker: str = "markdown_header"
43
+ sources: list[str] = field(default_factory=list)
44
+ chunk_size: int = 200
45
+ fusion: str = "rrf"
46
+ drop_tokens: list[str] = field(default_factory=list)
47
+ goldens_path: str = ""
48
+ cache_dir: str = ""
49
+ allow_legacy_collection: bool = False
50
+
51
+
52
+ @dataclass
53
+ class ConfigChain:
54
+ qdrant_url: Source = "default"
55
+ qdrant_api_key: Source = "default"
56
+ collection: Source = "default"
57
+ embedder: Source = "default"
58
+ chunker: Source = "default"
59
+ sources: Source = "default"
60
+ chunk_size: Source = "default"
61
+ fusion: Source = "default"
62
+ drop_tokens: Source = "default"
63
+ goldens_path: Source = "default"
64
+ cache_dir: Source = "default"
65
+
66
+
67
+ _LEGACY_ENV: dict[str, str] = {
68
+ "QDRANT_URL": "qdrant_url",
69
+ "QDRANT_API_KEY": "qdrant_api_key",
70
+ "COLLECTION_NAME": "collection",
71
+ "EMBEDDING_MODEL": "embedder",
72
+ }
73
+
74
+ _NESTED_TABLES: list[tuple[str, dict[str, str]]] = [
75
+ ("hook", {"drop_tokens": "drop_tokens"}),
76
+ ("eval", {"goldens_path": "goldens_path"}),
77
+ ("cache", {"cache_dir": "cache_dir"}),
78
+ ]
79
+
80
+
81
+ def _load_toml(p: Path) -> dict[str, Any]:
82
+ try:
83
+ return tomllib.loads(p.read_text(encoding="utf-8"))
84
+ except Exception as exc:
85
+ raise RuntimeError(f"supamem: failed to parse {p}: {exc}") from exc
86
+
87
+
88
+ def _apply_section(
89
+ cfg: ResolvedConfig,
90
+ chain: ConfigChain,
91
+ section: dict[str, Any],
92
+ source: Source,
93
+ ) -> None:
94
+ """Apply flat field overrides from a [supamem] / [tool.supamem] section."""
95
+ for key, value in section.items():
96
+ if hasattr(cfg, key) and not isinstance(getattr(cfg, key), dict):
97
+ # skip nested tables (hook/eval/cache) — handled by _apply_nested
98
+ if key in {sub for sub, _ in _NESTED_TABLES}:
99
+ continue
100
+ setattr(cfg, key, value)
101
+ setattr(chain, key, source)
102
+
103
+
104
+ def _apply_nested(
105
+ cfg: ResolvedConfig,
106
+ chain: ConfigChain,
107
+ section: dict[str, Any],
108
+ source: Source,
109
+ ) -> None:
110
+ """Apply nested [supamem.hook], [supamem.eval], [supamem.cache] tables."""
111
+ for sub_key, field_map in _NESTED_TABLES:
112
+ sub = section.get(sub_key, {})
113
+ if not isinstance(sub, dict):
114
+ continue
115
+ for src_key, dst_field in field_map.items():
116
+ if src_key in sub:
117
+ setattr(cfg, dst_field, sub[src_key])
118
+ setattr(chain, dst_field, source)
119
+
120
+
121
+ def load_config(cwd: Path | None = None) -> tuple[ResolvedConfig, ConfigChain]:
122
+ """Resolve the supamem config for ``cwd`` (defaults to ``Path.cwd()``)."""
123
+ cwd = cwd or Path.cwd()
124
+ cfg = ResolvedConfig()
125
+ chain = ConfigChain()
126
+
127
+ # ── 4. Auto-detect (lowest applied rung) ──────────────────────────────
128
+ if (cwd / ".claude" / "insights").exists():
129
+ cfg.sources = [".claude/insights/", ".claude/rules/"]
130
+ chain.sources = "auto_detect"
131
+
132
+ # ── 3. pyproject.toml [tool.supamem] ──────────────────────────────────
133
+ pyproject = cwd / "pyproject.toml"
134
+ if pyproject.is_file():
135
+ data = _load_toml(pyproject)
136
+ section = data.get("tool", {}).get("supamem", {}) or {}
137
+ _apply_section(cfg, chain, section, "pyproject")
138
+ _apply_nested(cfg, chain, section, "pyproject")
139
+
140
+ # ── 2. .supamem/config.toml ───────────────────────────────────────────
141
+ supamem_toml = cwd / ".supamem" / "config.toml"
142
+ if supamem_toml.is_file():
143
+ data = _load_toml(supamem_toml)
144
+ section = data.get("supamem", {}) or {}
145
+ _apply_section(cfg, chain, section, "supamem_toml")
146
+ _apply_nested(cfg, chain, section, "supamem_toml")
147
+
148
+ # ── 1a. SUPAMEM_CONFIG explicit path ──────────────────────────────────
149
+ explicit = os.environ.get("SUPAMEM_CONFIG", "").strip()
150
+ if explicit:
151
+ ep = Path(explicit)
152
+ if not ep.is_file():
153
+ raise FileNotFoundError(
154
+ f"supamem: SUPAMEM_CONFIG points to missing file: {ep}"
155
+ )
156
+ data = _load_toml(ep)
157
+ section = data.get("supamem", {}) or {}
158
+ _apply_section(cfg, chain, section, "env")
159
+ _apply_nested(cfg, chain, section, "env")
160
+
161
+ # ── 1b. Legacy single-key env vars (highest precedence) ───────────────
162
+ for env_name, field_name in _LEGACY_ENV.items():
163
+ val = os.environ.get(env_name)
164
+ if val is not None and val != "":
165
+ setattr(cfg, field_name, val)
166
+ setattr(chain, field_name, "env")
167
+
168
+ return cfg, chain
supamem/config_io.py ADDED
@@ -0,0 +1,227 @@
1
+ """Atomic config-write primitives for supamem installers and migrators.
2
+
3
+ Public API:
4
+ - ``atomic_write_json`` — crash-safe JSON write with .bak snapshot and dry-run.
5
+ - ``deep_merge_json`` — recursive dict/list merge with explicit replace marker.
6
+ - ``wrap_managed_block`` / ``extract_managed_block`` — fence-marker primitives
7
+ for embedding supamem-owned regions inside line-oriented user-edited files.
8
+ - ``compute_diff`` — unified-diff helper for ``--dry-run`` callers.
9
+ - ``WriteResult`` (dataclass), ``BackupNotWritten`` (exception).
10
+
11
+ NOTE on diffs: ``compute_diff`` is intentionally low-level. Callers that print
12
+ the diff to stdout MUST sanitize secrets first — config files like
13
+ ``~/.claude.json`` and ``~/.cursor/mcp.json`` may contain MCP-server env blocks
14
+ with API keys (see plan 80.6-02 STRIDE T-80.6-02-02).
15
+
16
+ NOTE on symlinks: ``atomic_write_json`` does not follow ``target.parent``
17
+ symlinks that escape ``$HOME`` — installers should resolve and validate the
18
+ path before calling.
19
+ """
20
+ from __future__ import annotations
21
+
22
+ import difflib
23
+ import json
24
+ import os
25
+ import re
26
+ import tempfile
27
+ import time
28
+ from dataclasses import dataclass
29
+ from pathlib import Path
30
+ from typing import Any, Optional
31
+
32
+ from supamem import __version__
33
+
34
+
35
+ @dataclass
36
+ class WriteResult:
37
+ written: bool
38
+ backup_path: Optional[Path]
39
+ diff: str
40
+
41
+
42
+ class BackupNotWritten(Exception):
43
+ """Raised when a backup snapshot could not be written to disk."""
44
+
45
+
46
+ # ──────────────────────────── deep_merge_json ─────────────────────────────
47
+
48
+
49
+ _REPLACE_MARKER = "__supamem_replace__"
50
+
51
+
52
+ def _is_replace_marker(value: Any) -> bool:
53
+ return (
54
+ isinstance(value, dict)
55
+ and value.get(_REPLACE_MARKER) is True
56
+ and "value" in value
57
+ )
58
+
59
+
60
+ def deep_merge_json(base: dict, overlay: dict) -> dict:
61
+ """Recursively merge ``overlay`` into ``base``.
62
+
63
+ - Dicts: merged key-wise.
64
+ - Lists: overlay items NOT already in base (by deep equality) are appended.
65
+ - Scalars: overlay wins.
66
+ - Special replace marker: overlay value
67
+ ``{"__supamem_replace__": True, "value": <X>}`` forces replacement of the
68
+ base value with ``<X>`` instead of merging.
69
+ """
70
+ out = dict(base)
71
+ for key, ov in overlay.items():
72
+ if _is_replace_marker(ov):
73
+ out[key] = ov["value"]
74
+ continue
75
+ if key not in out:
76
+ out[key] = ov
77
+ continue
78
+ existing = out[key]
79
+ if isinstance(existing, dict) and isinstance(ov, dict):
80
+ out[key] = deep_merge_json(existing, ov)
81
+ elif isinstance(existing, list) and isinstance(ov, list):
82
+ merged = list(existing)
83
+ for item in ov:
84
+ if item not in merged:
85
+ merged.append(item)
86
+ out[key] = merged
87
+ else:
88
+ out[key] = ov
89
+ return out
90
+
91
+
92
+ # ─────────────────────────── atomic_write_json ────────────────────────────
93
+
94
+
95
+ def _serialize(content: dict) -> str:
96
+ """Serialize to canonical JSON. Raises TypeError before any disk write."""
97
+ return json.dumps(content, indent=2, ensure_ascii=False, sort_keys=False)
98
+
99
+
100
+ def _read_existing(target: Path) -> str:
101
+ if not target.exists():
102
+ return ""
103
+ return target.read_text(encoding="utf-8")
104
+
105
+
106
+ def atomic_write_json(
107
+ target: Path,
108
+ content: dict,
109
+ *,
110
+ dry_run: bool = False,
111
+ backup: bool = True,
112
+ ) -> WriteResult:
113
+ """Atomically write ``content`` to ``target`` as pretty JSON.
114
+
115
+ Behavior:
116
+ 1. Serialize first (raises TypeError on non-serializable input — nothing
117
+ is written if this fails).
118
+ 2. If existing content equals new content, return a no-op WriteResult.
119
+ 3. Compute a unified diff for callers / dry-run reporting.
120
+ 4. If ``dry_run``: return without writing.
121
+ 5. Otherwise write ``<target>.bak.<unix_ns>`` (when ``backup=True`` and
122
+ target exists), then a tempfile sibling, fsync, ``os.replace``.
123
+
124
+ On replace failure the original target file is left untouched. The tempfile
125
+ may remain on disk; callers can ignore or sweep ``*.tmp.*`` later.
126
+ """
127
+ new_text = _serialize(content)
128
+ old_text = _read_existing(target)
129
+ diff = compute_diff(
130
+ old_text,
131
+ new_text,
132
+ fromfile=str(target),
133
+ tofile=str(target),
134
+ )
135
+
136
+ if old_text == new_text:
137
+ return WriteResult(written=False, backup_path=None, diff="")
138
+
139
+ if dry_run:
140
+ return WriteResult(written=False, backup_path=None, diff=diff)
141
+
142
+ parent = target.parent
143
+ parent.mkdir(parents=True, exist_ok=True)
144
+
145
+ backup_path: Optional[Path] = None
146
+ if backup and target.exists():
147
+ backup_path = target.with_suffix(target.suffix + f".bak.{time.time_ns()}")
148
+ try:
149
+ backup_path.write_text(old_text, encoding="utf-8")
150
+ except OSError as exc: # pragma: no cover — surface clearly
151
+ raise BackupNotWritten(
152
+ f"Could not write backup to {backup_path}: {exc}"
153
+ ) from exc
154
+
155
+ tmp = tempfile.NamedTemporaryFile(
156
+ mode="w",
157
+ encoding="utf-8",
158
+ dir=str(parent),
159
+ prefix=target.name + ".tmp.",
160
+ delete=False,
161
+ )
162
+ try:
163
+ tmp.write(new_text)
164
+ tmp.flush()
165
+ os.fsync(tmp.fileno())
166
+ finally:
167
+ tmp.close()
168
+
169
+ os.replace(tmp.name, target)
170
+
171
+ return WriteResult(written=True, backup_path=backup_path, diff=diff)
172
+
173
+
174
+ # ──────────────────────────── managed-block fences ─────────────────────────
175
+
176
+
177
+ _BEGIN_FMT = "# BEGIN SUPAMEM v{version} MANAGED BLOCK — DO NOT EDIT"
178
+ _END_FMT = "# END SUPAMEM v{version} MANAGED BLOCK"
179
+ _FENCE_RE = re.compile(
180
+ r"# BEGIN SUPAMEM v[\d\.]+ MANAGED BLOCK — DO NOT EDIT\n"
181
+ r"(?P<owned>.*?)\n"
182
+ r"# END SUPAMEM v[\d\.]+ MANAGED BLOCK",
183
+ re.DOTALL,
184
+ )
185
+ _BEGIN_RE = re.compile(r"# BEGIN SUPAMEM v[\d\.]+ MANAGED BLOCK — DO NOT EDIT")
186
+
187
+
188
+ def wrap_managed_block(content: str, version: str = __version__) -> str:
189
+ """Wrap ``content`` between BEGIN/END SUPAMEM fence markers."""
190
+ return f"{_BEGIN_FMT.format(version=version)}\n{content}\n{_END_FMT.format(version=version)}"
191
+
192
+
193
+ def extract_managed_block(text: str) -> tuple[str, str, str]:
194
+ """Split ``text`` into ``(before, owned, after)`` around the fence pair.
195
+
196
+ Raises ``ValueError`` if multiple BEGIN markers are present.
197
+ """
198
+ if len(_BEGIN_RE.findall(text)) > 1:
199
+ raise ValueError("multiple BEGIN SUPAMEM markers found in text")
200
+ match = _FENCE_RE.search(text)
201
+ if match is None:
202
+ return (text, "", "")
203
+ before = text[: match.start()]
204
+ owned = match.group("owned")
205
+ after = text[match.end():]
206
+ return (before, owned, after)
207
+
208
+
209
+ # ──────────────────────────── compute_diff ─────────────────────────────────
210
+
211
+
212
+ def compute_diff(
213
+ old: str,
214
+ new: str,
215
+ *,
216
+ fromfile: str = "old",
217
+ tofile: str = "new",
218
+ ) -> str:
219
+ """Unified diff between ``old`` and ``new`` strings."""
220
+ return "".join(
221
+ difflib.unified_diff(
222
+ old.splitlines(keepends=True),
223
+ new.splitlines(keepends=True),
224
+ fromfile=fromfile,
225
+ tofile=tofile,
226
+ )
227
+ )