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.
- supamem/__init__.py +2 -0
- supamem/__main__.py +4 -0
- supamem/cli.py +267 -0
- supamem/config.py +168 -0
- supamem/config_io.py +227 -0
- supamem/console.py +116 -0
- supamem/doctor.py +201 -0
- supamem/embedders/__init__.py +33 -0
- supamem/embedders/bm25.py +26 -0
- supamem/embedders/minilm.py +22 -0
- supamem/eval/__init__.py +22 -0
- supamem/eval/auto_goldens.py +70 -0
- supamem/eval/goldens/__init__.py +0 -0
- supamem/eval/goldens/phase_80_1_tuned_hybrid.jsonl +33 -0
- supamem/eval/runner.py +159 -0
- supamem/hooks/__init__.py +31 -0
- supamem/hooks/claude_code.py +217 -0
- supamem/hooks/cursor.py +194 -0
- supamem/hooks/opencode.py +30 -0
- supamem/indexer/__init__.py +179 -0
- supamem/indexer/chunker.py +69 -0
- supamem/indexer/manifest.py +56 -0
- supamem/init.py +214 -0
- supamem/install/__init__.py +98 -0
- supamem/install/_types.py +13 -0
- supamem/install/claude_code.py +211 -0
- supamem/install/cursor.py +178 -0
- supamem/install/opencode.py +136 -0
- supamem/install/share.py +74 -0
- supamem/mcp_server.py +259 -0
- supamem/migrate.py +214 -0
- supamem/retrieval/__init__.py +22 -0
- supamem/retrieval/bm25.py +21 -0
- supamem/retrieval/dense.py +37 -0
- supamem/retrieval/tuned_hybrid.py +203 -0
- supamem/retrieval/types.py +20 -0
- supamem/share/__init__.py +0 -0
- supamem/share/commands/__init__.py +0 -0
- supamem/share/commands/sm-search.md +33 -0
- supamem/share/cursor-rules/__init__.py +0 -0
- supamem/share/cursor-rules/dual-memory.mdc +33 -0
- supamem/share/hooks/__init__.py +0 -0
- supamem/share/hooks/qdrant-semantic-guard.sh +36 -0
- supamem/share/rules/__init__.py +0 -0
- supamem/share/rules/dual-memory.md +49 -0
- supamem/share/skills/__init__.py +0 -0
- supamem/share/skills/supamem/SKILL.md +41 -0
- supamem/share/skills/supamem/__init__.py +0 -0
- supamem/stats/__init__.py +99 -0
- supamem/stats/counter.py +138 -0
- supamem/update_check.py +249 -0
- supamem-0.1.1.dist-info/METADATA +408 -0
- supamem-0.1.1.dist-info/RECORD +56 -0
- supamem-0.1.1.dist-info/WHEEL +4 -0
- supamem-0.1.1.dist-info/entry_points.txt +14 -0
- supamem-0.1.1.dist-info/licenses/LICENSE +21 -0
supamem/__init__.py
ADDED
supamem/__main__.py
ADDED
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
|
+
)
|