sessionmemory 0.12.0__tar.gz → 0.14.0__tar.gz

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 (48) hide show
  1. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/PKG-INFO +6 -2
  2. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/README.md +5 -1
  3. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/pyproject.toml +1 -1
  4. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/pyproject.toml.orig +1 -1
  5. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/cli.py +4 -0
  6. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/commands/inject.py +2 -2
  7. sessionmemory-0.14.0/src/sessionmemory/commands/local.py +540 -0
  8. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/commands/path.py +3 -3
  9. sessionmemory-0.14.0/src/sessionmemory/commands/reconcile.py +75 -0
  10. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/atomic.py +12 -2
  11. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/bootstrap.py +49 -4
  12. sessionmemory-0.14.0/src/sessionmemory/lib/changes.py +126 -0
  13. sessionmemory-0.14.0/src/sessionmemory/lib/commits.py +529 -0
  14. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/doctor.py +283 -53
  15. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/gitinfo.py +10 -2
  16. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/inject.py +2 -26
  17. sessionmemory-0.14.0/src/sessionmemory/lib/localmd.py +1324 -0
  18. sessionmemory-0.14.0/src/sessionmemory/lib/localtree.py +206 -0
  19. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/paths.py +12 -6
  20. sessionmemory-0.14.0/src/sessionmemory/lib/reconcile.py +388 -0
  21. sessionmemory-0.14.0/src/sessionmemory/lib/settingsdiff.py +133 -0
  22. sessionmemory-0.12.0/src/sessionmemory/commands/local.py +0 -134
  23. sessionmemory-0.12.0/src/sessionmemory/lib/localmd.py +0 -430
  24. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/__init__.py +0 -0
  25. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/commands/__init__.py +0 -0
  26. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/commands/_common.py +0 -0
  27. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/commands/delete.py +0 -0
  28. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/commands/doctor.py +0 -0
  29. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/commands/export.py +0 -0
  30. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/commands/init.py +0 -0
  31. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/commands/log.py +0 -0
  32. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/commands/new.py +0 -0
  33. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/commands/project.py +0 -0
  34. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/commands/reindex.py +0 -0
  35. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/commands/search.py +0 -0
  36. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/__init__.py +0 -0
  37. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/backlog.py +0 -0
  38. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/config.py +0 -0
  39. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/embed.py +0 -0
  40. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/export.py +0 -0
  41. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/field.py +0 -0
  42. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/fieldindex.py +0 -0
  43. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/frontmatter.py +0 -0
  44. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/ids.py +0 -0
  45. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/log.py +0 -0
  46. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/registry.py +0 -0
  47. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/resolve.py +0 -0
  48. {sessionmemory-0.12.0 → sessionmemory-0.14.0}/src/sessionmemory/lib/specs.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: sessionmemory
3
- Version: 0.12.0
3
+ Version: 0.14.0
4
4
  Summary: Durable memory for coding agents, one folder of searchable pages per project.
5
5
  Author: Nathaniel Landau
6
6
  Author-email: Nathaniel Landau <github@natelandau.com>
@@ -44,9 +44,13 @@ speaks the format.
44
44
  - Python 3.13 or 3.14. `uv` downloads one when none is installed.
45
45
  - git. The vault is a git repository, and a project is registered by its git remote.
46
46
  - Claude Code, to run the plugin. The CLI works on its own without it.
47
+ - Optional: the [GitHub CLI](https://cli.github.com/) (`gh`), signed in. `sessionmemory
48
+ reconcile` uses it to find the commit a squash-merged pull request landed as, when a
49
+ project's `origin` is on GitHub.
47
50
 
48
51
  The first search downloads the `nomic-embed-text-v1.5` embedding model, about 520MB, and
49
- caches it under `~/.cache/sessionmemory/models`. Nothing else touches the network.
52
+ caches it under `~/.cache/sessionmemory/models`. `sessionmemory reconcile` runs
53
+ `git fetch origin` and asks GitHub through `gh`. Nothing else touches the network.
50
54
 
51
55
  ## Install
52
56
 
@@ -29,9 +29,13 @@ speaks the format.
29
29
  - Python 3.13 or 3.14. `uv` downloads one when none is installed.
30
30
  - git. The vault is a git repository, and a project is registered by its git remote.
31
31
  - Claude Code, to run the plugin. The CLI works on its own without it.
32
+ - Optional: the [GitHub CLI](https://cli.github.com/) (`gh`), signed in. `sessionmemory
33
+ reconcile` uses it to find the commit a squash-merged pull request landed as, when a
34
+ project's `origin` is on GitHub.
32
35
 
33
36
  The first search downloads the `nomic-embed-text-v1.5` embedding model, about 520MB, and
34
- caches it under `~/.cache/sessionmemory/models`. Nothing else touches the network.
37
+ caches it under `~/.cache/sessionmemory/models`. `sessionmemory reconcile` runs
38
+ `git fetch origin` and asks GitHub through `gh`. Nothing else touches the network.
35
39
 
36
40
  ## Install
37
41
 
@@ -11,7 +11,7 @@ description = "Durable memory for coding agents, one folder of searchable pages
11
11
  name = "sessionmemory"
12
12
  readme = "README.md"
13
13
  requires-python = ">=3.13,<3.15"
14
- version = "0.12.0"
14
+ version = "0.14.0"
15
15
 
16
16
  [[project.authors]]
17
17
  name = "Nathaniel Landau"
@@ -12,7 +12,7 @@
12
12
  name = "sessionmemory"
13
13
  readme = "README.md"
14
14
  requires-python = ">=3.13,<3.15"
15
- version = "0.12.0"
15
+ version = "0.14.0"
16
16
 
17
17
  [project.scripts]
18
18
  sessionmemory = "sessionmemory.cli:main"
@@ -17,6 +17,7 @@ from sessionmemory.commands import log as log_commands
17
17
  from sessionmemory.commands import new as new_commands
18
18
  from sessionmemory.commands import path as path_commands
19
19
  from sessionmemory.commands import project
20
+ from sessionmemory.commands import reconcile as reconcile_commands
20
21
  from sessionmemory.commands import reindex as reindex_commands
21
22
  from sessionmemory.commands import search as search_commands
22
23
  from sessionmemory.commands._common import VersionedGroup, emit_value
@@ -68,6 +69,9 @@ app.command("path", help="Print one of this project's vault paths.")(path_comman
68
69
  app.command("project", help="Report this directory's project, or register it.")(
69
70
  project.project_command
70
71
  )
72
+ app.command("reconcile", help="Bring this project's logs in line with what landed on the trunk.")(
73
+ reconcile_commands.reconcile_command
74
+ )
71
75
  app.command("reindex", help="Rebuild this project's search indexes, or every project's.")(
72
76
  reindex_commands.reindex_command
73
77
  )
@@ -2,7 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from pathlib import Path
5
+ from pathlib import Path # noqa: TC003
6
6
 
7
7
  import typer
8
8
 
@@ -18,7 +18,7 @@ def inject_command(cwd: Path | None = CWD, command: str = COMMAND, *, as_json: b
18
18
  """Print what this project's session should start with."""
19
19
  vault = require_vault()
20
20
  slug = require_project(vault, cwd)
21
- injection = inject.build(vault, slug, cwd=cwd if cwd is not None else Path.cwd())
21
+ injection = inject.build(vault, slug)
22
22
  if as_json:
23
23
  emit_json(inject.payload(injection, command=command))
24
24
  return
@@ -0,0 +1,540 @@
1
+ """Commands that keep a checkout's private CLAUDE.local.md, skills, rules, and settings."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import shlex
6
+ import sys
7
+ from dataclasses import dataclass, field
8
+ from pathlib import Path
9
+ from typing import Literal
10
+
11
+ import typer
12
+ from nclutils import ask, pp
13
+
14
+ from sessionmemory.commands._common import (
15
+ VersionedGroup,
16
+ emit_json,
17
+ emit_value,
18
+ fail,
19
+ require_project,
20
+ require_vault,
21
+ )
22
+ from sessionmemory.lib import localmd, paths
23
+
24
+ app = typer.Typer(
25
+ cls=VersionedGroup,
26
+ no_args_is_help=True,
27
+ help=(
28
+ "Keep this project's CLAUDE.local.md, private skills and rules, and "
29
+ "settings.local.json in the vault and sync them with checkouts."
30
+ ),
31
+ )
32
+
33
+ CWD = typer.Option(None, "--cwd", help="Directory to resolve the project from.")
34
+ JSON = typer.Option(False, "--json", help="Emit JSON instead of prose.") # noqa: FBT003
35
+ ADOPT = typer.Option(
36
+ None,
37
+ "--adopt",
38
+ help="Adopt an entry: CLAUDE.local.md, skills/<name>, or rules/<name>. Repeatable.",
39
+ show_default=False,
40
+ )
41
+ KEEP_SETTINGS = typer.Option(
42
+ None,
43
+ "--keep-settings",
44
+ help="Keep this copy of settings.local.json and write it over the other.",
45
+ show_default=False,
46
+ )
47
+
48
+ # Wide enough for the longest link or copy state, so names line up.
49
+ _STATE_WIDTH = max(len(state) for state in [*localmd.State, *localmd.CopyState])
50
+
51
+
52
+ def _interactive() -> bool:
53
+ """Report whether a person can answer a prompt, so an agent's call never blocks."""
54
+ return sys.stdin.isatty() and sys.stdout.isatty()
55
+
56
+
57
+ def _checkout(cwd: Path | None) -> localmd.Checkout:
58
+ """Resolve the project and locate the checkout, failing on any library error.
59
+
60
+ Args:
61
+ cwd (Path | None): The directory to resolve from, or the shell's directory.
62
+
63
+ Returns:
64
+ localmd.Checkout: The checkout holding `cwd`.
65
+ """
66
+ vault = require_vault()
67
+ slug = require_project(vault=vault, cwd=cwd)
68
+ try:
69
+ return localmd.checkout(vault=vault, slug=slug, cwd=cwd if cwd is not None else Path.cwd())
70
+ except localmd.LocalMdError as err:
71
+ fail(err.message, details=err.details)
72
+
73
+
74
+ def _warn_legacy(co: localmd.Checkout, legacy: Path) -> None:
75
+ """Name both vault copies of CLAUDE.local.md when they differ and neither was moved."""
76
+ pp.warning(
77
+ localmd.legacy_conflict(legacy=legacy, target=co.local / paths.LOCAL_MD_FILE),
78
+ details=[localmd.KEEP_ONE],
79
+ )
80
+
81
+
82
+ def _migrate(co: localmd.Checkout) -> None:
83
+ """Move an old-path vault copy into `local/` before anything looks at the entries."""
84
+ try:
85
+ legacy = localmd.migrate_legacy(vault=co.vault, slug=co.slug)
86
+ except OSError as err:
87
+ fail(f"could not move the vault's old {paths.LOCAL_MD_FILE} into {co.local}: {err}")
88
+ if legacy is not None:
89
+ _warn_legacy(co=co, legacy=legacy)
90
+
91
+
92
+ Side = Literal["checkout", "vault"]
93
+
94
+
95
+ @dataclass
96
+ class _Plan:
97
+ """What one sync run was asked to do beyond the safe link work."""
98
+
99
+ adopt: list[str] = field(default_factory=list)
100
+ keep: Side | None = None
101
+ refused: bool = False
102
+
103
+
104
+ def _pending_settings(
105
+ co: localmd.Checkout, tracked: set[str]
106
+ ) -> tuple[localmd.SettingsPending | None, bool]:
107
+ """Describe the settings difference waiting for the person.
108
+
109
+ A read error is reported rather than fatal, so the links this run made still reach
110
+ the caller's payload.
111
+
112
+ Returns:
113
+ tuple[localmd.SettingsPending | None, bool]: The difference, and False on an error.
114
+ """
115
+ item = localmd.settings_entry(co)
116
+ try:
117
+ return localmd.settings_pending(co=co, tracked=item.name in tracked), True
118
+ except localmd.LocalMdError as err:
119
+ pp.error(err.message, details=err.details)
120
+ except OSError as err:
121
+ pp.error(f"could not read {item.link} or {item.target}: {err}")
122
+ return None, False
123
+
124
+
125
+ def _waiting(co: localmd.Checkout, tracked: set[str]) -> tuple[list[localmd.Entry], bool]:
126
+ """List the entries adopt could take, reporting a git error rather than failing.
127
+
128
+ Returns:
129
+ tuple[list[localmd.Entry], bool]: The entries, and False on an error.
130
+ """
131
+ try:
132
+ return localmd.candidates(co, tracked=tracked), True
133
+ except localmd.LocalMdError as err:
134
+ pp.error(err.message, details=err.details)
135
+ except OSError as err:
136
+ pp.error(f"could not read the entries of {co.worktree}: {err}")
137
+ return [], False
138
+
139
+
140
+ def _settings_rows(pending: localmd.SettingsPending) -> list[tuple[str, tuple[str, str]]]:
141
+ """Offer one row per side that holds a copy, so a missing side is never chosen."""
142
+ rows = []
143
+ for side, mtime in (("checkout", pending.checkout_mtime), ("vault", pending.vault_mtime)):
144
+ if mtime is not None:
145
+ rows.append((f"keep the {side}'s settings.local.json ({mtime})", ("keep", side)))
146
+ return rows
147
+
148
+
149
+ def _checklist(waiting: list[localmd.Entry], pending: localmd.SettingsPending | None) -> _Plan:
150
+ """Ask the person which pending items to act on, refusing both settings copies at once."""
151
+ rows: list[tuple[str, tuple[str, str]]] = [
152
+ (f"adopt {item.name}", ("adopt", item.name)) for item in waiting
153
+ ]
154
+ if pending is not None:
155
+ if pending.summary:
156
+ pp.info(
157
+ "settings.local.json differs from the vault copy", details=list(pending.summary)
158
+ )
159
+ rows.extend(_settings_rows(pending))
160
+ if not rows:
161
+ return _Plan()
162
+ chosen = (
163
+ ask.choose_multiple_from_list(
164
+ choices=rows, message="Choose what to adopt or which settings copy to keep"
165
+ )
166
+ or []
167
+ )
168
+ plan = _Plan(adopt=[name for action, name in chosen if action == "adopt"])
169
+ sides = [side for action, side in chosen if action == "keep"]
170
+ if len(sides) > 1:
171
+ pp.error("both settings copies were chosen, so neither was kept")
172
+ plan.refused = True
173
+ elif sides:
174
+ plan.keep = "checkout" if sides[0] == "checkout" else "vault"
175
+ return plan
176
+
177
+
178
+ def _entries(co: localmd.Checkout, names: list[str]) -> tuple[list[localmd.Entry], bool]:
179
+ """Build the link entries a person named, reporting each name that is not one.
180
+
181
+ Returns:
182
+ tuple[list[localmd.Entry], bool]: The valid entries, and whether any name failed.
183
+ """
184
+ items: list[localmd.Entry] = []
185
+ failed = False
186
+ for name in names:
187
+ try:
188
+ item = localmd.entry(co=co, name=name)
189
+ except localmd.LocalMdError as err:
190
+ pp.error(err.message, details=err.details)
191
+ failed = True
192
+ continue
193
+ if item.mode == "copy":
194
+ pp.error(
195
+ f"{name} is kept by copy, not adopted",
196
+ details=["Choose a copy with --keep-settings checkout or --keep-settings vault."],
197
+ )
198
+ failed = True
199
+ continue
200
+ items.append(item)
201
+ return items, failed
202
+
203
+
204
+ def _adopt_one(
205
+ co: localmd.Checkout, item: localmd.Entry, *, tracked: bool
206
+ ) -> localmd.AdoptResult | None:
207
+ """Adopt one entry, reporting a failure so the next entry still runs.
208
+
209
+ Returns:
210
+ localmd.AdoptResult | None: The outcome, or None when the entry failed.
211
+ """
212
+ try:
213
+ result = localmd.adopt(co=co, item=item, tracked=tracked)
214
+ except localmd.LocalMdError as err:
215
+ pp.error(err.message, details=err.details)
216
+ return None
217
+ except OSError as err:
218
+ pp.error(f"could not adopt {item.name}: {err}")
219
+ return None
220
+ for target in result.relative_imports:
221
+ pp.warning(
222
+ f"@{target} in {item.name} resolves from the vault copy's folder and will not load"
223
+ )
224
+ return result
225
+
226
+
227
+ def _adopt_all(
228
+ co: localmd.Checkout, names: list[str], tracked: set[str]
229
+ ) -> tuple[list[localmd.AdoptResult], bool]:
230
+ """Adopt each named entry, warning once about rule approval.
231
+
232
+ Returns:
233
+ tuple[list[localmd.AdoptResult], bool]: The adopted entries, and whether any failed.
234
+ """
235
+ items, failed = _entries(co=co, names=names)
236
+ if not items:
237
+ return [], failed
238
+ adopted: list[localmd.AdoptResult] = []
239
+ for item in items:
240
+ result = _adopt_one(co=co, item=item, tracked=item.name in tracked)
241
+ if result is None:
242
+ failed = True
243
+ else:
244
+ adopted.append(result)
245
+ copied = [result for result in adopted if not result.already_linked]
246
+ if any(result.entry.kind == "rule" for result in copied):
247
+ pp.warning(
248
+ "Claude Code asks once per checkout to allow a linked rule as an external import"
249
+ )
250
+ return adopted, failed
251
+
252
+
253
+ def _keep(co: localmd.Checkout, side: Side, tracked: set[str]) -> tuple[Path | None, bool]:
254
+ """Write the chosen settings copy over the other, reporting a refusal.
255
+
256
+ Returns:
257
+ tuple[Path | None, bool]: The path holding the kept copy, or None when the keep
258
+ was refused, and whether anything was written.
259
+ """
260
+ item = localmd.settings_entry(co)
261
+ try:
262
+ current = localmd.copy_state(co=co, item=item, tracked=item.name in tracked)
263
+ written = localmd.keep_settings(co=co, side=side, tracked=item.name in tracked)
264
+ except localmd.LocalMdError as err:
265
+ pp.error(err.message, details=err.details)
266
+ return None, False
267
+ except OSError as err:
268
+ pp.error(f"could not copy {item.name}: {err}")
269
+ return None, False
270
+ changed = current is not localmd.CopyState.SAME
271
+ if side == "vault" and changed:
272
+ pp.warning(
273
+ "Claude Code read its settings before this ran; start a new session before "
274
+ "approving anything so it does not write the old copy back"
275
+ )
276
+ return written, changed
277
+
278
+
279
+ def _link_warning(result: localmd.LinkResult) -> None:
280
+ """Explain a conflict and the remedy that fits its cause.
281
+
282
+ Args:
283
+ result (localmd.LinkResult): A `conflict` result from `link_all`.
284
+ """
285
+ pp.warning(
286
+ result.reason or f"{result.entry.name} was not linked",
287
+ details=[result.remedy] if result.remedy else [],
288
+ )
289
+
290
+
291
+ def _report_links(results: list[localmd.LinkResult]) -> None:
292
+ """Print each created link on stdout and explain every other outcome off it."""
293
+ for result in results:
294
+ if result.status == "created":
295
+ emit_value(str(result.entry.link))
296
+ elif result.status == "conflict":
297
+ _link_warning(result)
298
+ elif result.status == "tracked":
299
+ pp.warning(f"{result.entry.link} is tracked by git; the vault copy stays in the vault")
300
+ elif result.status == "removed":
301
+ pp.warning(f"removed {result.entry.link}, whose vault entry is gone")
302
+
303
+
304
+ def _report_pending(waiting: list[localmd.Entry], pending: localmd.SettingsPending | None) -> None:
305
+ """Name each pending item and the command that resolves it, off stdout."""
306
+ if waiting:
307
+ adopt = " ".join(f"--adopt {shlex.quote(item.name)}" for item in waiting)
308
+ pp.warning(
309
+ f"not in the vault yet: {', '.join(item.name for item in waiting)}",
310
+ details=[f"Adopt them with: sessionmemory local sync {adopt} --cwd ."],
311
+ )
312
+ if pending is not None:
313
+ details = [*pending.summary]
314
+ details.extend(
315
+ f"Keep the {side}'s copy with: sessionmemory local sync --keep-settings {side} --cwd ."
316
+ for side, mtime in (
317
+ ("checkout", pending.checkout_mtime),
318
+ ("vault", pending.vault_mtime),
319
+ )
320
+ if mtime is not None
321
+ )
322
+ pp.warning(f"settings.local.json: {pending.state}", details=details)
323
+
324
+
325
+ def _settings_payload(pending: localmd.SettingsPending | None) -> dict[str, object] | None:
326
+ if pending is None:
327
+ return None
328
+ return {
329
+ "state": str(pending.state),
330
+ "checkout": {"path": str(pending.checkout), "mtime": pending.checkout_mtime},
331
+ "vault": {"path": str(pending.vault), "mtime": pending.vault_mtime},
332
+ "summary": list(pending.summary),
333
+ }
334
+
335
+
336
+ def _link_rows(results: list[localmd.LinkResult]) -> list[dict[str, object]]:
337
+ return [
338
+ {
339
+ "kind": result.entry.kind,
340
+ "name": result.entry.name,
341
+ "status": result.status,
342
+ "link": str(result.entry.link),
343
+ "target": str(result.entry.target),
344
+ "reason": result.reason,
345
+ "remedy": result.remedy,
346
+ }
347
+ for result in results
348
+ ]
349
+
350
+
351
+ @dataclass(frozen=True)
352
+ class _Report:
353
+ """Everything one sync run did and found, for its JSON or prose output."""
354
+
355
+ results: list[localmd.LinkResult]
356
+ adopted: list[localmd.AdoptResult]
357
+ kept: Path | None
358
+ waiting: list[localmd.Entry]
359
+ pending: localmd.SettingsPending | None
360
+
361
+ def payload(self, plan: _Plan) -> dict[str, object]:
362
+ """Build the `--json` payload; `adopted` and `settings` only for flags that ran."""
363
+ payload: dict[str, object] = {
364
+ "entries": _link_rows(self.results),
365
+ "pending": {
366
+ "adopt": [item.name for item in self.waiting],
367
+ "settings": _settings_payload(self.pending),
368
+ },
369
+ }
370
+ if plan.adopt:
371
+ payload["adopted"] = [
372
+ {"name": result.entry.name, "target": str(result.target)} for result in self.adopted
373
+ ]
374
+ if plan.keep is not None and self.kept is not None:
375
+ payload["settings"] = {"kept": plan.keep, "path": str(self.kept)}
376
+ return payload
377
+
378
+ def prose(self) -> None:
379
+ """Print written paths on stdout and everything else, pending work included, off it."""
380
+ _report_links(self.results)
381
+ for result in self.adopted:
382
+ emit_value(str(result.target))
383
+ if self.kept is not None:
384
+ emit_value(str(self.kept))
385
+ _report_pending(waiting=self.waiting, pending=self.pending)
386
+ if not (self.results or self.adopted or self.kept or self.waiting or self.pending):
387
+ pp.info("nothing to sync for this project")
388
+
389
+
390
+ @app.command(
391
+ "sync",
392
+ help=(
393
+ "Link the vault's entries into this checkout, then adopt entries and keep a settings "
394
+ "copy as asked. With no flags on a terminal, choose from a checklist."
395
+ ),
396
+ )
397
+ def sync_command(
398
+ adopt: list[str] | None = ADOPT,
399
+ keep_settings: Side | None = KEEP_SETTINGS,
400
+ as_json: bool = JSON, # noqa: FBT001
401
+ cwd: Path | None = CWD,
402
+ ) -> None:
403
+ """Link the vault's entries into this checkout, then adopt and keep settings as asked.
404
+
405
+ Raises:
406
+ Exit: When an entry is in conflict, or a requested adopt or keep failed.
407
+ """
408
+ co = _checkout(cwd)
409
+ try:
410
+ # One listing of git's index serves linking, the pending report, adopt, and keep.
411
+ tracked = localmd.tracked_all(co)
412
+ results = localmd.link_all(co, tracked=tracked)
413
+ except localmd.LocalMdError as err:
414
+ fail(err.message, details=err.details)
415
+ except OSError as err:
416
+ fail(f"could not link the entries of {co.worktree}: {err}")
417
+
418
+ plan = _Plan(adopt=list(adopt or []), keep=keep_settings)
419
+ flagged = bool(plan.adopt) or plan.keep is not None
420
+ waiting, listed = _waiting(co, tracked) if not flagged else ([], True)
421
+ pending, compared = _pending_settings(co, tracked) if not flagged else (None, True)
422
+ if not flagged and not as_json and _interactive():
423
+ plan = _checklist(waiting=waiting, pending=pending)
424
+
425
+ adopted, failed = (
426
+ _adopt_all(co=co, names=plan.adopt, tracked=tracked) if plan.adopt else ([], False)
427
+ )
428
+ kept, changed = _keep(co=co, side=plan.keep, tracked=tracked) if plan.keep else (None, False)
429
+ if any(not result.already_linked for result in adopted) or (
430
+ changed and plan.keep == "checkout"
431
+ ):
432
+ pp.warning("the hooks commit the vault copy to the vault's git remote")
433
+ failed = failed or plan.refused or (plan.keep is not None and kept is None)
434
+ # Linking runs first, so an entry adopted by this run was in its way.
435
+ done = {result.entry.name for result in adopted}
436
+ results = [r for r in results if not (r.status == "conflict" and r.entry.name in done)]
437
+ # Recomputed only after an adopt or keep, which change what is still pending.
438
+ if plan.adopt or plan.keep is not None:
439
+ waiting, listed = _waiting(co, tracked)
440
+ pending, compared = _pending_settings(co, tracked)
441
+ failed = failed or not (listed and compared)
442
+
443
+ report = _Report(results=results, adopted=adopted, kept=kept, waiting=waiting, pending=pending)
444
+ if as_json:
445
+ emit_json(report.payload(plan))
446
+ else:
447
+ report.prose()
448
+ if failed or any(result.status == "conflict" for result in results):
449
+ raise typer.Exit(1)
450
+
451
+
452
+ def _flags(row: dict[str, object]) -> list[str]:
453
+ """List what is surprising about an entry: tracked, an unignored link, or the contents."""
454
+ flags: list[str] = []
455
+ if row["tracked"]:
456
+ flags.append("tracked")
457
+ elif (
458
+ row["kind"] != "settings"
459
+ and row["state"] == localmd.State.LINKED
460
+ and row["ignored"] is False
461
+ ):
462
+ flags.append("not ignored")
463
+ if row["state"] == localmd.State.DIVERGED and row["match"] is not None:
464
+ flags.append(f"contents {'identical' if row['match'] else 'different'}")
465
+ return flags
466
+
467
+
468
+ def _status_row(co: localmd.Checkout, item: localmd.Entry, *, tracked: bool) -> dict[str, object]:
469
+ """Describe one entry for `status`, in the shape `--json` prints.
470
+
471
+ Returns:
472
+ dict[str, object]: The entry's kind, name, state, paths, and git and content flags.
473
+ """
474
+ return {
475
+ "kind": item.kind,
476
+ "name": item.name,
477
+ "state": str(localmd.state(item)),
478
+ "link": str(item.link),
479
+ "target": str(item.target),
480
+ # Git cannot be asked about a path behind a symlinked or non-folder `.claude/`.
481
+ "ignored": None if localmd.blocked(co=co, item=item) else localmd.ignored(co=co, item=item),
482
+ "tracked": tracked,
483
+ "match": localmd.contents_match(item),
484
+ }
485
+
486
+
487
+ def _settings_row(
488
+ co: localmd.Checkout, item: localmd.Entry, *, tracked: bool
489
+ ) -> dict[str, object] | None:
490
+ """Describe the settings entry for `status`, or None when neither side has a copy.
491
+
492
+ Returns:
493
+ dict[str, object] | None: The row, with the copy state in place of a link state.
494
+ """
495
+ current = localmd.copy_state(co=co, item=item, tracked=tracked)
496
+ if current is None:
497
+ return None
498
+ return {
499
+ "kind": item.kind,
500
+ "name": item.name,
501
+ "state": str(current),
502
+ "link": str(item.link),
503
+ "target": str(item.target),
504
+ "ignored": None if localmd.blocked(co=co, item=item) else localmd.ignored(co=co, item=item),
505
+ "tracked": tracked,
506
+ "match": None,
507
+ }
508
+
509
+
510
+ @app.command("status", help="Report how each of this checkout's entries relates to the vault.")
511
+ def status_command(cwd: Path | None = CWD, as_json: bool = JSON) -> None: # noqa: FBT001
512
+ """Report how each of this checkout's entries relates to the vault.
513
+
514
+ Raises:
515
+ Exit: When git or the filesystem cannot be read.
516
+ """
517
+ co = _checkout(cwd)
518
+ _migrate(co)
519
+ try:
520
+ items = localmd.entries(co)
521
+ settings = localmd.settings_entry(co)
522
+ tracked = localmd.tracked_names(co=co, items=[*items, settings])
523
+ rows = [_status_row(co=co, item=item, tracked=item.name in tracked) for item in items]
524
+ settings_row = _settings_row(co=co, item=settings, tracked=settings.name in tracked)
525
+ if settings_row is not None:
526
+ rows.append(settings_row)
527
+ except localmd.LocalMdError as err:
528
+ fail(err.message, details=err.details)
529
+ except OSError as err:
530
+ fail(f"could not read the entries of {co.worktree}: {err}")
531
+
532
+ if as_json:
533
+ emit_json({"local": str(co.local), "entries": rows})
534
+ return
535
+
536
+ for row in rows:
537
+ flags = _flags(row)
538
+ suffix = f" ({', '.join(flags)})" if flags else ""
539
+ emit_value(f"{row['state']:<{_STATE_WIDTH}} {row['name']}{suffix}")
540
+ emit_value(f"local: {co.local}")
@@ -11,8 +11,8 @@ from sessionmemory.commands._common import emit_value, require_project, require_
11
11
  from sessionmemory.lib import paths
12
12
 
13
13
  # Typer lists an Enum's members in --help and rejects anything else at parse time. The
14
- # members are the keys of `paths.project_paths`, with `project` standing for `project_dir`
15
- # and `local` for `local_md`.
14
+ # members are the keys of `paths.project_paths`, with `project` standing for
15
+ # `project_dir`.
16
16
  PathKind = enum.Enum(
17
17
  "PathKind",
18
18
  {
@@ -40,5 +40,5 @@ def path_command(kind: PathKind = KIND_ARGUMENT, cwd: Path | None = CWD_OPTION)
40
40
  """Print one of this project's vault paths."""
41
41
  vault = require_vault()
42
42
  slug = require_project(vault, cwd)
43
- key = {"project": "project_dir", "local": "local_md"}.get(kind.value, kind.value)
43
+ key = {"project": "project_dir"}.get(kind.value, kind.value)
44
44
  emit_value(paths.project_paths(vault, slug)[key])