sessionmemory 0.17.0__tar.gz → 0.19.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.
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/PKG-INFO +10 -8
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/README.md +7 -5
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/pyproject.toml +13 -13
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/pyproject.toml.orig +13 -13
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/local.py +13 -5
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/new.py +20 -26
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/backlog.py +135 -15
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/bootstrap.py +3 -2
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/doctor.py +13 -12
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/gitinfo.py +2 -2
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/inject.py +7 -5
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localmd.py +225 -55
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/registry.py +23 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/resolve.py +9 -2
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/__init__.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/cli.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/__init__.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/_common.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/delete.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/doctor.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/export.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/init.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/inject.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/log.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/path.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/project.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/reconcile.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/reindex.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/search.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/entry.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/__init__.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/atomic.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/changes.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/commits.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/config.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/embed.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/export.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/field.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/fieldindex.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/frontmatter.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/ids.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localdeclined.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localmanifest.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localtree.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/log.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/paths.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/reconcile.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/registration.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/settingsdiff.py +0 -0
- {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/specs.py +0 -0
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
Metadata-Version: 2.3
|
|
2
2
|
Name: sessionmemory
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.19.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>
|
|
7
|
-
Requires-Dist: fastembed>=0.9.
|
|
7
|
+
Requires-Dist: fastembed>=0.9.1
|
|
8
8
|
Requires-Dist: nclutils>=4.0.0
|
|
9
9
|
Requires-Dist: pyyaml>=6.0.3
|
|
10
10
|
Requires-Dist: sqlite-vec>=0.1.9
|
|
11
11
|
Requires-Dist: tomli-w>=1.2.0
|
|
12
|
-
Requires-Dist: typer>=0.
|
|
12
|
+
Requires-Dist: typer>=0.29.1
|
|
13
13
|
Requires-Python: >=3.13, <3.15
|
|
14
14
|
Description-Content-Type: text/markdown
|
|
15
15
|
|
|
@@ -232,15 +232,17 @@ all for a script.
|
|
|
232
232
|
- Past sessions, one page each: `sessionmemory search "<words>" --logs`. Search them
|
|
233
233
|
for why something was decided, what happened the last time an area changed, or
|
|
234
234
|
whether a fix was already tried.
|
|
235
|
-
- Open work: read `backlog.md`. Any top-level bullet is an open item
|
|
235
|
+
- Open work: read `backlog.md`. Any top-level bullet is an open item, and the
|
|
236
|
+
indented lines under it are its detail. Under a
|
|
236
237
|
`## <kind>` heading (feat, fix, refactor, perf, docs, test, build, ci, decide), the
|
|
237
238
|
full shape is sized S, M, or L: `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`.
|
|
238
239
|
Add one with
|
|
239
240
|
`sessionmemory new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
|
|
240
|
-
which writes that shape and creates the file or heading when missing.
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
241
|
+
which writes that shape and creates the file or heading when missing. Keep the
|
|
242
|
+
title to one short sentence and pass context (why, where, what was tried) with
|
|
243
|
+
`--detail "..."`, in single quotes when it holds a backtick or `$`. Questions for
|
|
244
|
+
the user to answer go under `## decide`. Delete a finished item with its detail,
|
|
245
|
+
and one that will never be done, directly; never tick or annotate it. Git history is the record of what was finished.
|
|
244
246
|
- Specs: `specs/` holds one design record per feature, named `<date>-<topic>.md`
|
|
245
247
|
and kept after the work ships. Before designing or changing a feature, search
|
|
246
248
|
them: `sessionmemory search "<words>" --specs` (listing the directory works too), so a
|
|
@@ -217,15 +217,17 @@ all for a script.
|
|
|
217
217
|
- Past sessions, one page each: `sessionmemory search "<words>" --logs`. Search them
|
|
218
218
|
for why something was decided, what happened the last time an area changed, or
|
|
219
219
|
whether a fix was already tried.
|
|
220
|
-
- Open work: read `backlog.md`. Any top-level bullet is an open item
|
|
220
|
+
- Open work: read `backlog.md`. Any top-level bullet is an open item, and the
|
|
221
|
+
indented lines under it are its detail. Under a
|
|
221
222
|
`## <kind>` heading (feat, fix, refactor, perf, docs, test, build, ci, decide), the
|
|
222
223
|
full shape is sized S, M, or L: `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`.
|
|
223
224
|
Add one with
|
|
224
225
|
`sessionmemory new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
|
|
225
|
-
which writes that shape and creates the file or heading when missing.
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
226
|
+
which writes that shape and creates the file or heading when missing. Keep the
|
|
227
|
+
title to one short sentence and pass context (why, where, what was tried) with
|
|
228
|
+
`--detail "..."`, in single quotes when it holds a backtick or `$`. Questions for
|
|
229
|
+
the user to answer go under `## decide`. Delete a finished item with its detail,
|
|
230
|
+
and one that will never be done, directly; never tick or annotate it. Git history is the record of what was finished.
|
|
229
231
|
- Specs: `specs/` holds one design record per feature, named `<date>-<topic>.md`
|
|
230
232
|
and kept after the work ships. Before designing or changing a feature, search
|
|
231
233
|
them: `sessionmemory search "<words>" --specs` (listing the directory works too), so a
|
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
dependencies = [
|
|
3
|
-
"fastembed>=0.9.
|
|
3
|
+
"fastembed>=0.9.1",
|
|
4
4
|
"nclutils>=4.0.0",
|
|
5
5
|
"pyyaml>=6.0.3",
|
|
6
6
|
"sqlite-vec>=0.1.9",
|
|
7
7
|
"tomli-w>=1.2.0",
|
|
8
|
-
"typer>=0.
|
|
8
|
+
"typer>=0.29.1",
|
|
9
9
|
]
|
|
10
10
|
description = "Durable memory for coding agents, one folder of searchable pages per project."
|
|
11
11
|
name = "sessionmemory"
|
|
12
12
|
readme = "README.md"
|
|
13
13
|
requires-python = ">=3.13,<3.15"
|
|
14
|
-
version = "0.
|
|
14
|
+
version = "0.19.0"
|
|
15
15
|
|
|
16
16
|
[[project.authors]]
|
|
17
17
|
name = "Nathaniel Landau"
|
|
@@ -22,23 +22,23 @@ sessionmemory = "sessionmemory.entry:main"
|
|
|
22
22
|
|
|
23
23
|
[dependency-groups]
|
|
24
24
|
dev = [
|
|
25
|
-
"commitizen>=4.19.
|
|
26
|
-
"coverage>=7.
|
|
25
|
+
"commitizen>=4.19.3",
|
|
26
|
+
"coverage>=7.17.3",
|
|
27
27
|
"duty>=1.10.1",
|
|
28
|
-
"gate-cache>=0.
|
|
29
|
-
"prek>=0.5.
|
|
28
|
+
"gate-cache>=0.7.0",
|
|
29
|
+
"prek>=0.5.11",
|
|
30
30
|
"pytest-clarity>=1.0.1",
|
|
31
31
|
"pytest-cov>=7.1.0",
|
|
32
32
|
"pytest-devtools>=1.3.0",
|
|
33
|
-
"pytest-mock>=3.
|
|
33
|
+
"pytest-mock>=3.17.0",
|
|
34
34
|
"pytest-xdist>=3.8.0",
|
|
35
|
-
"pytest>=9.
|
|
35
|
+
"pytest>=9.2.0",
|
|
36
36
|
"rich>=15.0.0",
|
|
37
|
-
"ruff>=0.17.
|
|
37
|
+
"ruff>=0.17.5",
|
|
38
38
|
"shellcheck-py>=0.11.0.1",
|
|
39
|
-
"ty>=0.0.
|
|
40
|
-
"types-pyyaml>=6.0.12.
|
|
41
|
-
"typos>=1.
|
|
39
|
+
"ty>=0.0.104",
|
|
40
|
+
"types-pyyaml>=6.0.12.20261113",
|
|
41
|
+
"typos>=1.52.2",
|
|
42
42
|
"yamllint>=1.38.0",
|
|
43
43
|
]
|
|
44
44
|
|
|
@@ -1,41 +1,41 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
authors = [{ name = "Nathaniel Landau", email = "github@natelandau.com" }]
|
|
3
3
|
dependencies = [
|
|
4
|
-
"fastembed>=0.9.
|
|
4
|
+
"fastembed>=0.9.1",
|
|
5
5
|
"nclutils>=4.0.0",
|
|
6
6
|
"pyyaml>=6.0.3",
|
|
7
7
|
"sqlite-vec>=0.1.9",
|
|
8
8
|
"tomli-w>=1.2.0",
|
|
9
|
-
"typer>=0.
|
|
9
|
+
"typer>=0.29.1",
|
|
10
10
|
]
|
|
11
11
|
description = "Durable memory for coding agents, one folder of searchable pages per project."
|
|
12
12
|
name = "sessionmemory"
|
|
13
13
|
readme = "README.md"
|
|
14
14
|
requires-python = ">=3.13,<3.15"
|
|
15
|
-
version = "0.
|
|
15
|
+
version = "0.19.0"
|
|
16
16
|
|
|
17
17
|
[project.scripts]
|
|
18
18
|
sessionmemory = "sessionmemory.entry:main"
|
|
19
19
|
|
|
20
20
|
[dependency-groups]
|
|
21
21
|
dev = [
|
|
22
|
-
"commitizen>=4.19.
|
|
23
|
-
"coverage>=7.
|
|
22
|
+
"commitizen>=4.19.3",
|
|
23
|
+
"coverage>=7.17.3",
|
|
24
24
|
"duty>=1.10.1",
|
|
25
|
-
"gate-cache>=0.
|
|
26
|
-
"prek>=0.5.
|
|
25
|
+
"gate-cache>=0.7.0",
|
|
26
|
+
"prek>=0.5.11",
|
|
27
27
|
"pytest-clarity>=1.0.1",
|
|
28
28
|
"pytest-cov>=7.1.0",
|
|
29
29
|
"pytest-devtools>=1.3.0",
|
|
30
|
-
"pytest-mock>=3.
|
|
30
|
+
"pytest-mock>=3.17.0",
|
|
31
31
|
"pytest-xdist>=3.8.0",
|
|
32
|
-
"pytest>=9.
|
|
32
|
+
"pytest>=9.2.0",
|
|
33
33
|
"rich>=15.0.0",
|
|
34
|
-
"ruff>=0.17.
|
|
34
|
+
"ruff>=0.17.5",
|
|
35
35
|
"shellcheck-py>=0.11.0.1",
|
|
36
|
-
"ty>=0.0.
|
|
37
|
-
"types-pyyaml>=6.0.12.
|
|
38
|
-
"typos>=1.
|
|
36
|
+
"ty>=0.0.104",
|
|
37
|
+
"types-pyyaml>=6.0.12.20261113",
|
|
38
|
+
"typos>=1.52.2",
|
|
39
39
|
"yamllint>=1.38.0",
|
|
40
40
|
]
|
|
41
41
|
|
|
@@ -69,12 +69,18 @@ def _checkout(cwd: Path | None) -> localmd.Checkout:
|
|
|
69
69
|
"""
|
|
70
70
|
vault = require_vault()
|
|
71
71
|
slug, resolved = require_registered(vault=vault, cwd=cwd)
|
|
72
|
+
project = resolved.project
|
|
73
|
+
# Only a match by path, which resolution allows only outside any repository, may root
|
|
74
|
+
# the checkout at the registered folder.
|
|
75
|
+
by_path = resolved.matched_by == "path" and project is not None and project.root
|
|
76
|
+
registered_root = Path(project.root) if by_path else None
|
|
72
77
|
try:
|
|
73
78
|
return localmd.checkout(
|
|
74
79
|
vault=vault,
|
|
75
80
|
slug=slug,
|
|
76
81
|
cwd=_common.target_dir(cwd),
|
|
77
82
|
worktree=resolved.worktree_root,
|
|
83
|
+
registered_root=registered_root,
|
|
78
84
|
)
|
|
79
85
|
except localmd.LocalMdError as err:
|
|
80
86
|
fail(err.message, details=err.details)
|
|
@@ -86,14 +92,14 @@ def _or_fail(co: localmd.Checkout, doing: str) -> Generator[None]:
|
|
|
86
92
|
|
|
87
93
|
Args:
|
|
88
94
|
co (localmd.Checkout): The checkout being worked on.
|
|
89
|
-
doing (str): What failed, as in "could not <doing> the entries of <
|
|
95
|
+
doing (str): What failed, as in "could not <doing> the entries of <root>".
|
|
90
96
|
"""
|
|
91
97
|
try:
|
|
92
98
|
yield
|
|
93
99
|
except localmd.LocalMdError as err:
|
|
94
100
|
fail(err.message, details=err.details)
|
|
95
101
|
except OSError as err:
|
|
96
|
-
fail(f"could not {doing} the entries of {co.
|
|
102
|
+
fail(f"could not {doing} the entries of {co.root}: {err}")
|
|
97
103
|
|
|
98
104
|
|
|
99
105
|
def _migrate(co: localmd.Checkout) -> None:
|
|
@@ -161,7 +167,7 @@ def _waiting(co: localmd.Checkout, tracked: set[str]) -> tuple[list[localmd.Entr
|
|
|
161
167
|
except localmd.LocalMdError as err:
|
|
162
168
|
pp.error(err.message, details=err.details)
|
|
163
169
|
except OSError as err:
|
|
164
|
-
pp.error(f"could not read the entries of {co.
|
|
170
|
+
pp.error(f"could not read the entries of {co.root}: {err}")
|
|
165
171
|
return [], False
|
|
166
172
|
|
|
167
173
|
|
|
@@ -808,7 +814,7 @@ def _declinable(co: localmd.Checkout, raw: str, cwd: Path, present: list[str]) -
|
|
|
808
814
|
except localmd.LocalMdError as err:
|
|
809
815
|
pp.error(err.message, details=err.details)
|
|
810
816
|
except OSError as err:
|
|
811
|
-
pp.error(f"could not read {raw} in {co.
|
|
817
|
+
pp.error(f"could not read {raw} in {co.root}: {err}")
|
|
812
818
|
return None
|
|
813
819
|
|
|
814
820
|
|
|
@@ -904,7 +910,9 @@ def status_command(cwd: Path | None = CWD_OPTION, as_json: bool = JSON_OPTION) -
|
|
|
904
910
|
asked = {item.name for item in askable}
|
|
905
911
|
|
|
906
912
|
def is_ignored(item: localmd.Entry) -> bool | None:
|
|
907
|
-
|
|
913
|
+
if ignored is None or item.name not in asked:
|
|
914
|
+
return None
|
|
915
|
+
return item.name in ignored
|
|
908
916
|
|
|
909
917
|
rows = [
|
|
910
918
|
_status_row(
|
|
@@ -55,6 +55,11 @@ SUPERSEDES = typer.Option(
|
|
|
55
55
|
None, "--supersedes", help="The spec this one replaces, by name; it is marked superseded."
|
|
56
56
|
)
|
|
57
57
|
TOPIC = typer.Option(None, "--topic", help="A topic tag, without the leading hash.")
|
|
58
|
+
DETAIL = typer.Option(
|
|
59
|
+
None,
|
|
60
|
+
"--detail",
|
|
61
|
+
help="Context written as nested bullets under the item: why, where, what was tried.",
|
|
62
|
+
)
|
|
58
63
|
|
|
59
64
|
|
|
60
65
|
def _report(path: Path, title: str, *, as_json: bool, uuid: str | None = None) -> None:
|
|
@@ -200,33 +205,13 @@ def new_reference(
|
|
|
200
205
|
_new_living_document(paths.reference_dir, title, body, body_file, cwd, as_json=as_json)
|
|
201
206
|
|
|
202
207
|
|
|
203
|
-
def _warn_about_shape(*, in_use: list[str], title: str, topic: str | None) -> None:
|
|
204
|
-
"""Warn, without blocking the write, about a new topic tag or an overlong description.
|
|
205
|
-
|
|
206
|
-
`in_use` is read before the write, since the line just written always carries its own
|
|
207
|
-
topic.
|
|
208
|
-
"""
|
|
209
|
-
if topic is not None:
|
|
210
|
-
tag = topic.strip().removeprefix("#")
|
|
211
|
-
if tag and in_use and tag not in in_use:
|
|
212
|
-
pp.warning(
|
|
213
|
-
f"#{tag} is a new topic in this backlog",
|
|
214
|
-
details=[f"in use: {', '.join(in_use)}"],
|
|
215
|
-
)
|
|
216
|
-
length = len(title.strip())
|
|
217
|
-
if length > backlog.LONG_DESCRIPTION:
|
|
218
|
-
pp.warning(
|
|
219
|
-
f"the description is {length} characters, over the {backlog.LONG_DESCRIPTION} limit",
|
|
220
|
-
details=["keep a line to one sentence and put detail in a spec"],
|
|
221
|
-
)
|
|
222
|
-
|
|
223
|
-
|
|
224
208
|
@app.command("backlog", help="Add one open item to this project's backlog.md.")
|
|
225
209
|
def new_backlog(
|
|
226
210
|
kind: Kind = KIND,
|
|
227
211
|
size: Size = SIZE,
|
|
228
212
|
title: str = DESCRIPTION,
|
|
229
213
|
topic: str | None = TOPIC,
|
|
214
|
+
detail: str | None = DETAIL,
|
|
230
215
|
cwd: Path | None = CWD_OPTION,
|
|
231
216
|
*,
|
|
232
217
|
as_json: bool = JSON_OPTION,
|
|
@@ -241,13 +226,22 @@ def new_backlog(
|
|
|
241
226
|
path = paths.backlog_path(vault, slug)
|
|
242
227
|
in_use = backlog.topics(path)
|
|
243
228
|
try:
|
|
244
|
-
|
|
245
|
-
path,
|
|
229
|
+
block = backlog.add_item(
|
|
230
|
+
path,
|
|
231
|
+
kind=kind.value,
|
|
232
|
+
size=size.value,
|
|
233
|
+
description=title,
|
|
234
|
+
topic=topic,
|
|
235
|
+
today=today(),
|
|
236
|
+
detail=detail,
|
|
246
237
|
)
|
|
247
238
|
except backlog.BacklogError as error:
|
|
248
239
|
fail(str(error))
|
|
249
|
-
|
|
240
|
+
for warning in backlog.shape_warnings(
|
|
241
|
+
in_use=in_use, description=title, topic=topic, detail=detail
|
|
242
|
+
):
|
|
243
|
+
pp.warning(warning.message, details=[warning.advice])
|
|
250
244
|
if as_json:
|
|
251
|
-
emit_json({"path": str(path), "line":
|
|
245
|
+
emit_json({"path": str(path), "line": block[0], "detail": block[1:]})
|
|
252
246
|
return
|
|
253
|
-
emit_value(
|
|
247
|
+
emit_value("\n".join([*block, str(path)]))
|
|
@@ -6,11 +6,17 @@ does not depend on that shape: a person writes lines by hand, often as plain pro
|
|
|
6
6
|
every top-level bullet with text is an item. The line has no checkbox: finished work is
|
|
7
7
|
deleted, and git history is the record of it, so there is nothing to tick. Deleting a
|
|
8
8
|
line needs no validation and stays a direct edit.
|
|
9
|
+
|
|
10
|
+
Context that would crowd the line goes in an optional detail block: indented bullets
|
|
11
|
+
directly under it. Counting ignores indented lines, so the headline stays the item and
|
|
12
|
+
the detail never inflates the count.
|
|
9
13
|
"""
|
|
10
14
|
|
|
11
15
|
from __future__ import annotations
|
|
12
16
|
|
|
13
17
|
import re
|
|
18
|
+
import textwrap
|
|
19
|
+
from dataclasses import dataclass
|
|
14
20
|
from typing import TYPE_CHECKING
|
|
15
21
|
|
|
16
22
|
from sessionmemory.lib import atomic
|
|
@@ -22,14 +28,32 @@ KINDS = ("feat", "fix", "refactor", "perf", "docs", "test", "build", "ci", "deci
|
|
|
22
28
|
SIZES = ("S", "M", "L")
|
|
23
29
|
HEADING = "# Backlog"
|
|
24
30
|
_SECTION_PREFIX = "## "
|
|
25
|
-
LONG_DESCRIPTION =
|
|
31
|
+
LONG_DESCRIPTION = 120
|
|
32
|
+
LONG_DETAIL = 1500
|
|
33
|
+
DETAIL_BULLET = " - "
|
|
34
|
+
_DETAIL_CONTINUATION = " "
|
|
35
|
+
DETAIL_WIDTH = 88
|
|
36
|
+
_TICKED = ("- [x]", "- [X]")
|
|
26
37
|
_TOPIC_TAG = re.compile(r"\[#([^\s\]]+)\]")
|
|
38
|
+
_BULLET_MARKER = re.compile(r"^-(\s+|$)")
|
|
27
39
|
|
|
28
40
|
|
|
29
41
|
class BacklogError(ValueError):
|
|
30
42
|
"""An item field that cannot be written as a well-formed line."""
|
|
31
43
|
|
|
32
44
|
|
|
45
|
+
@dataclass(frozen=True)
|
|
46
|
+
class ShapeWarning:
|
|
47
|
+
"""A field that is written as given but likely misplaced, with what to do instead."""
|
|
48
|
+
|
|
49
|
+
message: str
|
|
50
|
+
advice: str
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _tag(topic: str) -> str:
|
|
54
|
+
return topic.strip().removeprefix("#")
|
|
55
|
+
|
|
56
|
+
|
|
33
57
|
def format_item(*, kind: str, size: str, description: str, topic: str | None, today: str) -> str:
|
|
34
58
|
"""Return the checklist line for one open item, validating every field.
|
|
35
59
|
|
|
@@ -64,7 +88,7 @@ def format_item(*, kind: str, size: str, description: str, topic: str | None, to
|
|
|
64
88
|
line = f"- [{size}] {description} - {today}"
|
|
65
89
|
if topic is None:
|
|
66
90
|
return line
|
|
67
|
-
topic = topic
|
|
91
|
+
topic = _tag(topic)
|
|
68
92
|
if not topic:
|
|
69
93
|
msg = "the topic is empty"
|
|
70
94
|
raise BacklogError(msg)
|
|
@@ -77,6 +101,91 @@ def format_item(*, kind: str, size: str, description: str, topic: str | None, to
|
|
|
77
101
|
return f"{line} [#{topic}]"
|
|
78
102
|
|
|
79
103
|
|
|
104
|
+
def format_detail(detail: str | None) -> list[str]:
|
|
105
|
+
"""Return the nested bullets that carry an item's detail under its headline.
|
|
106
|
+
|
|
107
|
+
Each line of `detail` becomes one bullet, so a markdown viewer shows the lines apart
|
|
108
|
+
instead of joining them into the item's paragraph. A bullet the caller wrote keeps
|
|
109
|
+
its text without gaining a second marker. Blank lines are dropped so the item stays
|
|
110
|
+
one tight block and the next item's insert point is unambiguous.
|
|
111
|
+
|
|
112
|
+
Args:
|
|
113
|
+
detail (str | None): Free text, possibly several lines, or None for no detail.
|
|
114
|
+
|
|
115
|
+
Returns:
|
|
116
|
+
list[str]: The lines to write, each bullet starting with `DETAIL_BULLET` and
|
|
117
|
+
wrapped onto indented continuation lines, or an empty list when there is no
|
|
118
|
+
detail.
|
|
119
|
+
"""
|
|
120
|
+
texts = (_BULLET_MARKER.sub("", line.strip()) for line in (detail or "").splitlines())
|
|
121
|
+
return [
|
|
122
|
+
wrapped
|
|
123
|
+
for text in texts
|
|
124
|
+
if text
|
|
125
|
+
for wrapped in textwrap.wrap(
|
|
126
|
+
text,
|
|
127
|
+
width=DETAIL_WIDTH,
|
|
128
|
+
initial_indent=DETAIL_BULLET,
|
|
129
|
+
subsequent_indent=_DETAIL_CONTINUATION,
|
|
130
|
+
break_long_words=False,
|
|
131
|
+
break_on_hyphens=False,
|
|
132
|
+
)
|
|
133
|
+
]
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def shape_warnings(
|
|
137
|
+
*, in_use: list[str], description: str, topic: str | None, detail: str | None
|
|
138
|
+
) -> list[ShapeWarning]:
|
|
139
|
+
"""Return what is likely misplaced in an item that is otherwise well-formed.
|
|
140
|
+
|
|
141
|
+
None of these refuses the write: a new topic may be deliberate, and length is advice.
|
|
142
|
+
|
|
143
|
+
Args:
|
|
144
|
+
in_use (list[str]): The topics on the backlog before this item, from `topics`.
|
|
145
|
+
description (str): The item's description as given.
|
|
146
|
+
topic (str | None): The item's topic as given, or None.
|
|
147
|
+
detail (str | None): The item's detail as given, or None.
|
|
148
|
+
|
|
149
|
+
Returns:
|
|
150
|
+
list[ShapeWarning]: One per problem, empty when the item is well placed.
|
|
151
|
+
"""
|
|
152
|
+
warnings: list[ShapeWarning] = []
|
|
153
|
+
tag = _tag(topic) if topic is not None else ""
|
|
154
|
+
if tag and in_use and tag not in in_use:
|
|
155
|
+
warnings.append(
|
|
156
|
+
ShapeWarning(f"#{tag} is a new topic in this backlog", f"in use: {', '.join(in_use)}")
|
|
157
|
+
)
|
|
158
|
+
length = len(description.strip())
|
|
159
|
+
if length > LONG_DESCRIPTION:
|
|
160
|
+
warnings.append(
|
|
161
|
+
ShapeWarning(
|
|
162
|
+
f"the description is {length} characters, longer than {LONG_DESCRIPTION}",
|
|
163
|
+
"keep the line to one short sentence and move context into --detail",
|
|
164
|
+
)
|
|
165
|
+
)
|
|
166
|
+
detail_length = len((detail or "").strip())
|
|
167
|
+
if detail_length > LONG_DETAIL:
|
|
168
|
+
warnings.append(
|
|
169
|
+
ShapeWarning(
|
|
170
|
+
f"the detail is {detail_length} characters, longer than {LONG_DETAIL}",
|
|
171
|
+
"a design this size belongs in a spec",
|
|
172
|
+
)
|
|
173
|
+
)
|
|
174
|
+
return warnings
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
def is_ticked(line: str) -> bool:
|
|
178
|
+
"""Return whether `line` is a ticked top-level bullet: finished work left in place.
|
|
179
|
+
|
|
180
|
+
Args:
|
|
181
|
+
line (str): One line of `backlog.md`.
|
|
182
|
+
|
|
183
|
+
Returns:
|
|
184
|
+
bool: True for a `- [x]` or `- [X]` line at column 0.
|
|
185
|
+
"""
|
|
186
|
+
return line.startswith(_TICKED)
|
|
187
|
+
|
|
188
|
+
|
|
80
189
|
def is_item(line: str) -> bool:
|
|
81
190
|
"""Return whether `line` is an open item, the only lines the session start counts.
|
|
82
191
|
|
|
@@ -88,7 +197,7 @@ def is_item(line: str) -> bool:
|
|
|
88
197
|
whatever size, date, or topic it carries. False for a ticked `- [x]` line,
|
|
89
198
|
an indented sub-bullet, an empty bullet, and anything that is not a bullet.
|
|
90
199
|
"""
|
|
91
|
-
if not line.startswith("- ") or line
|
|
200
|
+
if not line.startswith("- ") or is_ticked(line):
|
|
92
201
|
return False
|
|
93
202
|
return bool(line.removeprefix("- ").removeprefix("[ ]").strip())
|
|
94
203
|
|
|
@@ -108,12 +217,12 @@ def topics(path: Path) -> list[str]:
|
|
|
108
217
|
return sorted({tag for line in lines if is_item(line) for tag in _TOPIC_TAG.findall(line)})
|
|
109
218
|
|
|
110
219
|
|
|
111
|
-
def _insert(lines: list[str], kind: str,
|
|
112
|
-
"""Place `
|
|
220
|
+
def _insert(lines: list[str], kind: str, block: list[str]) -> list[str]:
|
|
221
|
+
"""Place `block` at the end of the `## kind` section, or open that section last."""
|
|
113
222
|
heading = f"{_SECTION_PREFIX}{kind}"
|
|
114
223
|
start = next((i for i, line in enumerate(lines) if line.rstrip() == heading), None)
|
|
115
224
|
if start is None:
|
|
116
|
-
return [*lines, "", heading, "",
|
|
225
|
+
return [*lines, "", heading, "", *block]
|
|
117
226
|
end = next(
|
|
118
227
|
(i for i in range(start + 1, len(lines)) if lines[i].startswith(_SECTION_PREFIX)),
|
|
119
228
|
len(lines),
|
|
@@ -122,14 +231,21 @@ def _insert(lines: list[str], kind: str, item: str) -> list[str]:
|
|
|
122
231
|
while last > start + 1 and not lines[last - 1].strip():
|
|
123
232
|
last -= 1
|
|
124
233
|
if last == start + 1:
|
|
125
|
-
return [*lines[:last], "",
|
|
126
|
-
return [*lines[:last],
|
|
234
|
+
return [*lines[:last], "", *block, *lines[last:]]
|
|
235
|
+
return [*lines[:last], *block, *lines[last:]]
|
|
127
236
|
|
|
128
237
|
|
|
129
238
|
def add_item(
|
|
130
|
-
path: Path,
|
|
131
|
-
|
|
132
|
-
|
|
239
|
+
path: Path,
|
|
240
|
+
*,
|
|
241
|
+
kind: str,
|
|
242
|
+
size: str,
|
|
243
|
+
description: str,
|
|
244
|
+
topic: str | None,
|
|
245
|
+
today: str,
|
|
246
|
+
detail: str | None = None,
|
|
247
|
+
) -> list[str]:
|
|
248
|
+
"""Append one open item under its kind heading and return the lines written.
|
|
133
249
|
|
|
134
250
|
A missing file starts with `# Backlog`. An existing file keeps whatever heads it,
|
|
135
251
|
since the `# Backlog` heading is never inserted into a file someone else structured.
|
|
@@ -141,14 +257,18 @@ def add_item(
|
|
|
141
257
|
description (str): The imperative description.
|
|
142
258
|
topic (str | None): The tag, or None for none.
|
|
143
259
|
today (str): The date as `YYYY-MM-DD`.
|
|
260
|
+
detail (str | None): Context written as indented lines under the item, or None.
|
|
144
261
|
|
|
145
262
|
Returns:
|
|
146
|
-
str: The line
|
|
263
|
+
list[str]: The item line followed by its detail lines, without newlines.
|
|
147
264
|
|
|
148
265
|
Raises:
|
|
149
266
|
BacklogError: A field cannot be written as a well-formed line.
|
|
150
267
|
"""
|
|
151
|
-
|
|
268
|
+
block = [
|
|
269
|
+
format_item(kind=kind, size=size, description=description, topic=topic, today=today),
|
|
270
|
+
*format_detail(detail),
|
|
271
|
+
]
|
|
152
272
|
lines = path.read_text(encoding="utf-8").rstrip().splitlines() if path.is_file() else [HEADING]
|
|
153
|
-
atomic.write_text(path, "\n".join(_insert(lines, kind=kind,
|
|
154
|
-
return
|
|
273
|
+
atomic.write_text(path, "\n".join(_insert(lines, kind=kind, block=block)) + "\n")
|
|
274
|
+
return block
|
|
@@ -74,8 +74,9 @@ One folder per project under `projects/`. Inside each:
|
|
|
74
74
|
indexed. `plans/` is scratch and is never committed: `.gitignore` and the plugin's
|
|
75
75
|
commits both leave it out.
|
|
76
76
|
- `backlog.md` is the list of open items for the project: every top-level bullet is an
|
|
77
|
-
open item, under any heading or none
|
|
78
|
-
A finished item is deleted
|
|
77
|
+
open item, under any heading or none, and the indented lines under it are its detail.
|
|
78
|
+
A question for the user goes under `## decide`. A finished item is deleted with its
|
|
79
|
+
detail, not ticked.
|
|
79
80
|
|
|
80
81
|
The `{MODEL_CODE}.sqlite3` file inside a field is its vector index. It is
|
|
81
82
|
derived from the pages beside it, gitignored, and rebuilt by `sessionmemory reindex`.
|
|
@@ -16,6 +16,7 @@ from pathlib import Path
|
|
|
16
16
|
from typing import TYPE_CHECKING
|
|
17
17
|
|
|
18
18
|
from sessionmemory.lib import (
|
|
19
|
+
backlog,
|
|
19
20
|
changes,
|
|
20
21
|
commits,
|
|
21
22
|
field,
|
|
@@ -36,7 +37,7 @@ from sessionmemory.lib.frontmatter import (
|
|
|
36
37
|
)
|
|
37
38
|
|
|
38
39
|
if TYPE_CHECKING:
|
|
39
|
-
from collections.abc import Callable
|
|
40
|
+
from collections.abc import Callable, Mapping
|
|
40
41
|
|
|
41
42
|
from sessionmemory.lib.embed import Embedder
|
|
42
43
|
|
|
@@ -147,9 +148,6 @@ def dead_projects(vault: Path, _embedder: Embedder) -> list[Finding]:
|
|
|
147
148
|
]
|
|
148
149
|
|
|
149
150
|
|
|
150
|
-
_TICKED = ("- [x]", "- [X]")
|
|
151
|
-
|
|
152
|
-
|
|
153
151
|
def ticked_backlog_lines(vault: Path, _embedder: Embedder) -> list[Finding]:
|
|
154
152
|
"""Report a ticked top-level bullet in a backlog.
|
|
155
153
|
|
|
@@ -162,7 +160,7 @@ def ticked_backlog_lines(vault: Path, _embedder: Embedder) -> list[Finding]:
|
|
|
162
160
|
if not path.is_file():
|
|
163
161
|
continue
|
|
164
162
|
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
|
|
165
|
-
if
|
|
163
|
+
if backlog.is_ticked(line):
|
|
166
164
|
message = f"line {number}: ticked; finished work is deleted, not ticked"
|
|
167
165
|
findings.append(Finding("backlog", str(path), message))
|
|
168
166
|
return findings
|
|
@@ -516,16 +514,20 @@ def _declined_findings(co: localmd.Checkout, *, checked: bool) -> list[Finding]:
|
|
|
516
514
|
return findings
|
|
517
515
|
|
|
518
516
|
|
|
519
|
-
def _project_local_findings(
|
|
517
|
+
def _project_local_findings(
|
|
518
|
+
vault: Path, slug: str, root: Path | None, projects: Mapping[str, registry.Project]
|
|
519
|
+
) -> list[Finding]:
|
|
520
520
|
"""Report one project's local entries, checking the checkout only when `root` exists."""
|
|
521
521
|
findings = []
|
|
522
522
|
legacy = _legacy_finding(vault, slug)
|
|
523
523
|
if legacy is not None:
|
|
524
524
|
findings.append(legacy)
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
525
|
+
if root is not None and root.is_dir():
|
|
526
|
+
checked = True
|
|
527
|
+
co = localmd.checkout_at(vault=vault, slug=slug, root=root, projects=projects)
|
|
528
|
+
else:
|
|
529
|
+
checked = False
|
|
530
|
+
co = localmd.vault_stand_in(vault=vault, slug=slug)
|
|
529
531
|
findings.extend(_manifest_findings(co))
|
|
530
532
|
try:
|
|
531
533
|
items = localmd.vault_entries(co)
|
|
@@ -544,7 +546,6 @@ def _project_local_findings(vault: Path, slug: str, root: Path | None) -> list[F
|
|
|
544
546
|
for item in items:
|
|
545
547
|
findings.extend(_import_findings(item))
|
|
546
548
|
findings.extend(_repository_findings(item))
|
|
547
|
-
checked = root is not None and root.is_dir()
|
|
548
549
|
findings.extend(_declined_findings(co, checked=checked))
|
|
549
550
|
if not checked:
|
|
550
551
|
return findings
|
|
@@ -588,7 +589,7 @@ def local_instructions(vault: Path, _embedder: Embedder) -> list[Finding]:
|
|
|
588
589
|
for slug in paths.iter_project_slugs(vault):
|
|
589
590
|
project = projects.get(slug)
|
|
590
591
|
root = Path(project.root) if project and project.root else None
|
|
591
|
-
findings.extend(_project_local_findings(vault, slug, root))
|
|
592
|
+
findings.extend(_project_local_findings(vault, slug, root, projects))
|
|
592
593
|
return findings
|
|
593
594
|
|
|
594
595
|
|
|
@@ -31,7 +31,7 @@ GIT_TIMEOUT_SECONDS = 10
|
|
|
31
31
|
|
|
32
32
|
# The one git failure that is an answer rather than an outage. Every other non-zero exit,
|
|
33
33
|
# such as a `safe.directory` refusal or a held index lock, leaves the question open.
|
|
34
|
-
|
|
34
|
+
NOT_A_REPOSITORY = "not a git repository"
|
|
35
35
|
|
|
36
36
|
|
|
37
37
|
@dataclass(frozen=True)
|
|
@@ -118,7 +118,7 @@ def _git(cwd: Path, *args: str) -> _GitAnswer:
|
|
|
118
118
|
if completed is None:
|
|
119
119
|
return _GitAnswer(stdout=None, answered=False)
|
|
120
120
|
if completed.returncode != 0:
|
|
121
|
-
return _GitAnswer(stdout=None, answered=
|
|
121
|
+
return _GitAnswer(stdout=None, answered=NOT_A_REPOSITORY in completed.stderr.lower())
|
|
122
122
|
return _GitAnswer(stdout=completed.stdout.strip() or None, answered=True)
|
|
123
123
|
|
|
124
124
|
|