sessionmemory 0.14.0__tar.gz → 0.16.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 (50) hide show
  1. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/PKG-INFO +4 -4
  2. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/README.md +3 -3
  3. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/pyproject.toml +1 -1
  4. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/pyproject.toml.orig +1 -1
  5. sessionmemory-0.16.0/src/sessionmemory/cli.py +101 -0
  6. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/commands/_common.py +93 -3
  7. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/commands/export.py +9 -5
  8. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/commands/init.py +13 -5
  9. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/commands/inject.py +10 -3
  10. sessionmemory-0.16.0/src/sessionmemory/commands/local.py +822 -0
  11. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/commands/log.py +3 -3
  12. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/commands/new.py +19 -9
  13. sessionmemory-0.16.0/src/sessionmemory/commands/path.py +66 -0
  14. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/commands/project.py +158 -34
  15. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/commands/reconcile.py +8 -3
  16. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/commands/reindex.py +2 -2
  17. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/commands/search.py +12 -7
  18. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/doctor.py +83 -2
  19. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/field.py +12 -2
  20. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/inject.py +2 -2
  21. sessionmemory-0.16.0/src/sessionmemory/lib/localmanifest.py +267 -0
  22. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/localmd.py +432 -37
  23. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/settingsdiff.py +27 -17
  24. sessionmemory-0.14.0/src/sessionmemory/cli.py +0 -87
  25. sessionmemory-0.14.0/src/sessionmemory/commands/local.py +0 -540
  26. sessionmemory-0.14.0/src/sessionmemory/commands/path.py +0 -44
  27. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/__init__.py +0 -0
  28. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/commands/__init__.py +0 -0
  29. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/commands/delete.py +0 -0
  30. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/commands/doctor.py +0 -0
  31. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/__init__.py +0 -0
  32. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/atomic.py +0 -0
  33. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/backlog.py +0 -0
  34. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/bootstrap.py +0 -0
  35. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/changes.py +0 -0
  36. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/commits.py +0 -0
  37. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/config.py +0 -0
  38. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/embed.py +0 -0
  39. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/export.py +0 -0
  40. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/fieldindex.py +0 -0
  41. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/frontmatter.py +0 -0
  42. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/gitinfo.py +0 -0
  43. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/ids.py +0 -0
  44. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/localtree.py +0 -0
  45. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/log.py +0 -0
  46. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/paths.py +0 -0
  47. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/reconcile.py +0 -0
  48. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/registry.py +0 -0
  49. {sessionmemory-0.14.0 → sessionmemory-0.16.0}/src/sessionmemory/lib/resolve.py +0 -0
  50. {sessionmemory-0.14.0 → sessionmemory-0.16.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.14.0
3
+ Version: 0.16.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>
@@ -145,7 +145,7 @@ yourself, run the command once:
145
145
 
146
146
  ```bash
147
147
  cd ~/repos/invoice-api
148
- sessionmemory project --register --cwd .
148
+ sessionmemory project register --cwd .
149
149
  ```
150
150
 
151
151
  ```
@@ -221,8 +221,8 @@ loaded for you: the titles are what the vault holds, and each is one `sessionmem
221
221
  away. The project's folder has `learnings/` and `logs/`, searched by meaning, beside
222
222
  `specs/`, `runbooks/`, `reference/`, and `backlog.md`, which are ordinary files you Read
223
223
  and Edit. `sessionmemory path <kind>` prints one path, where kind is project, learnings,
224
- logs, specs, runbooks, reference, or backlog; `sessionmemory project --json` prints
225
- them all for a script.
224
+ logs, specs, runbooks, reference, or backlog; `sessionmemory path --json` prints them
225
+ all for a script.
226
226
 
227
227
  - Before assuming nothing was written down, search: `sessionmemory search "<words>"`
228
228
  prints each hit's path, title, and summary, and `--read` prints every hit's whole
@@ -130,7 +130,7 @@ yourself, run the command once:
130
130
 
131
131
  ```bash
132
132
  cd ~/repos/invoice-api
133
- sessionmemory project --register --cwd .
133
+ sessionmemory project register --cwd .
134
134
  ```
135
135
 
136
136
  ```
@@ -206,8 +206,8 @@ loaded for you: the titles are what the vault holds, and each is one `sessionmem
206
206
  away. The project's folder has `learnings/` and `logs/`, searched by meaning, beside
207
207
  `specs/`, `runbooks/`, `reference/`, and `backlog.md`, which are ordinary files you Read
208
208
  and Edit. `sessionmemory path <kind>` prints one path, where kind is project, learnings,
209
- logs, specs, runbooks, reference, or backlog; `sessionmemory project --json` prints
210
- them all for a script.
209
+ logs, specs, runbooks, reference, or backlog; `sessionmemory path --json` prints them
210
+ all for a script.
211
211
 
212
212
  - Before assuming nothing was written down, search: `sessionmemory search "<words>"`
213
213
  prints each hit's path, title, and summary, and `--read` prints every hit's whole
@@ -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.14.0"
14
+ version = "0.16.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.14.0"
15
+ version = "0.16.0"
16
16
 
17
17
  [project.scripts]
18
18
  sessionmemory = "sessionmemory.cli:main"
@@ -0,0 +1,101 @@
1
+ """Session memory CLI invoked as `sessionmemory` by a user."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import importlib.metadata
6
+
7
+ import typer
8
+
9
+ from sessionmemory.commands import delete as delete_commands
10
+ from sessionmemory.commands import doctor as doctor_commands
11
+ from sessionmemory.commands import export as export_commands
12
+ from sessionmemory.commands import init as init_commands
13
+ from sessionmemory.commands import inject as inject_commands
14
+ from sessionmemory.commands import local as local_commands
15
+ from sessionmemory.commands import log as log_commands
16
+ from sessionmemory.commands import new as new_commands
17
+ from sessionmemory.commands import path as path_commands
18
+ from sessionmemory.commands import project
19
+ from sessionmemory.commands import reconcile as reconcile_commands
20
+ from sessionmemory.commands import reindex as reindex_commands
21
+ from sessionmemory.commands import search as search_commands
22
+ from sessionmemory.commands._common import VersionedGroup, emit_value
23
+
24
+ app = typer.Typer(
25
+ cls=VersionedGroup,
26
+ no_args_is_help=True,
27
+ context_settings={"help_option_names": ["-h", "--help"]},
28
+ )
29
+
30
+ # Panels order the top-level help by who runs a command, so a newcomer reads the
31
+ # everyday commands first and the plugin's plumbing last.
32
+ EVERYDAY = "Everyday"
33
+ SETUP = "Setup"
34
+ MAINTENANCE = "Maintenance"
35
+ PLUGIN = "Plugin internals"
36
+
37
+
38
+ def _print_version(value: bool) -> None: # noqa: FBT001
39
+ """Print the installed version bare and exit, for a caller that compares it."""
40
+ if value:
41
+ emit_value(importlib.metadata.version("sessionmemory"))
42
+ raise typer.Exit
43
+
44
+
45
+ @app.callback()
46
+ def _root(
47
+ version: bool = typer.Option( # noqa: FBT001
48
+ False, # noqa: FBT003
49
+ "--version",
50
+ callback=_print_version,
51
+ is_eager=True,
52
+ help="Print the version and exit.",
53
+ ),
54
+ ) -> None:
55
+ """Manage a project's memory in a vault of markdown pages."""
56
+
57
+
58
+ app.command(
59
+ "search", help="Search learnings by meaning, or logs or specs.", rich_help_panel=EVERYDAY
60
+ )(search_commands.search_command)
61
+ app.add_typer(new_commands.app, name="new", rich_help_panel=EVERYDAY)
62
+ app.command("path", help="Print this project's vault paths.", rich_help_panel=EVERYDAY)(
63
+ path_commands.path_command
64
+ )
65
+ app.command("delete", help="Delete files from the vault permanently.", rich_help_panel=EVERYDAY)(
66
+ delete_commands.delete_command
67
+ )
68
+ app.command("init", help="Create the files a new vault needs.", rich_help_panel=SETUP)(
69
+ init_commands.init
70
+ )
71
+ app.add_typer(project.app, name="project", rich_help_panel=SETUP)
72
+ app.add_typer(local_commands.app, name="local", rich_help_panel=SETUP)
73
+ app.command(
74
+ "doctor", help="Report pages, projects, and indexes worth a look.", rich_help_panel=MAINTENANCE
75
+ )(doctor_commands.doctor_command)
76
+ app.command(
77
+ "reindex",
78
+ help="Rebuild this project's search indexes, or every project's.",
79
+ rich_help_panel=MAINTENANCE,
80
+ )(reindex_commands.reindex_command)
81
+ app.command(
82
+ "reconcile",
83
+ help="Update this project's session logs to match the commits on its default branch.",
84
+ rich_help_panel=MAINTENANCE,
85
+ )(reconcile_commands.reconcile_command)
86
+ app.command(
87
+ "export",
88
+ help="Write this project's learnings or logs as a .memoryfield.zip.",
89
+ rich_help_panel=MAINTENANCE,
90
+ )(export_commands.export_command)
91
+ app.command("inject", help="Print the block a session starts with.", rich_help_panel=PLUGIN)(
92
+ inject_commands.inject_command
93
+ )
94
+ app.command(
95
+ "log", help="Write this session's log page, replacing its body.", rich_help_panel=PLUGIN
96
+ )(log_commands.log_command)
97
+
98
+
99
+ def main() -> None:
100
+ """Run the CLI. This is the console script entry point."""
101
+ app()
@@ -11,14 +11,14 @@ from typing import TYPE_CHECKING, NoReturn
11
11
 
12
12
  import typer
13
13
  import typer.core
14
- from nclutils import pp
14
+ from nclutils import ask, pp
15
15
 
16
16
  # Typer vendors Click, so the `click` package's classes never match its errors.
17
17
  from typer._click import core as click_core
18
18
  from typer._click import exceptions as click_exceptions
19
19
 
20
20
  from sessionmemory.lib import embed, registry
21
- from sessionmemory.lib.bootstrap import is_empty
21
+ from sessionmemory.lib.bootstrap import InitResult, initialize, is_empty
22
22
  from sessionmemory.lib.config import (
23
23
  CONFIG_FILE,
24
24
  VaultNotConfiguredError,
@@ -33,6 +33,8 @@ if TYPE_CHECKING:
33
33
 
34
34
  EMBEDDER_ENV_VAR = "SESSIONMEMORY_EMBEDDER"
35
35
 
36
+ CWD_OPTION = typer.Option(None, "--cwd", "-C", help="Directory to resolve the project from.")
37
+
36
38
 
37
39
  # The two ways to name the vault, offered together whenever neither is set.
38
40
  VAULT_FIX = [
@@ -162,6 +164,78 @@ def emit_json(payload: object) -> None:
162
164
  emit_value(json.dumps(payload, indent=2))
163
165
 
164
166
 
167
+ def interactive() -> bool:
168
+ """Report whether a person can answer a prompt, so an agent's call never blocks.
169
+
170
+ Returns:
171
+ bool: True when both stdin and stdout are terminals.
172
+ """
173
+ return sys.stdin.isatty() and sys.stdout.isatty()
174
+
175
+
176
+ def confirm(question: str, yes: str) -> bool:
177
+ """Ask one yes-or-no question whose answers say what each choice does.
178
+
179
+ Args:
180
+ question (str): The question.
181
+ yes (str): The yes answer, naming what it does.
182
+
183
+ Returns:
184
+ bool: True only when the person chose yes; cancelling counts as no.
185
+ """
186
+ choices = [(yes, "yes"), ("No, leave it alone", "no")]
187
+ return ask.choose_one_from_list(choices=choices, message=question) == "yes"
188
+
189
+
190
+ def init_question(vault: Path, *, force: bool) -> tuple[str, str]:
191
+ """Word the question that offers to initialize a vault, and its yes answer.
192
+
193
+ Args:
194
+ vault (Path): The directory to initialize.
195
+ force (bool): Whether the directory holds files but no vault marker.
196
+
197
+ Returns:
198
+ tuple[str, str]: The question and the yes answer.
199
+ """
200
+ if force:
201
+ return (
202
+ f"{vault} holds files but no vault marker. Initialize a vault there anyway?",
203
+ "Yes, initialize it (its files are kept)",
204
+ )
205
+ return f"{vault} is not a vault yet. Initialize one there?", "Yes, initialize it"
206
+
207
+
208
+ def offer_init(vault: Path) -> InitResult | None:
209
+ """Ask a person at a terminal whether to initialize `vault`, and do it on a yes.
210
+
211
+ Args:
212
+ vault (Path): The uninitialized directory.
213
+
214
+ Returns:
215
+ InitResult | None: What was created, or None when the person declined.
216
+ """
217
+ force = not is_empty(vault)
218
+ question, yes = init_question(vault, force=force)
219
+ if not confirm(question=question, yes=yes):
220
+ return None
221
+ return initialize(vault, force=force)
222
+
223
+
224
+ def ask_text(message: str) -> str | None:
225
+ """Ask a person at a terminal to type an answer.
226
+
227
+ Args:
228
+ message (str): The prompt.
229
+
230
+ Returns:
231
+ str | None: The answer, or None when the person cancelled.
232
+ """
233
+ try:
234
+ return str(typer.prompt(message)).strip() or None
235
+ except typer.Abort:
236
+ return None
237
+
238
+
165
239
  def require_vault() -> Path:
166
240
  """Return an initialized vault root, or exit with the command that fixes it.
167
241
 
@@ -182,6 +256,13 @@ def require_vault() -> Path:
182
256
  pp.error(str(error), details=VAULT_FIX)
183
257
  raise typer.Exit(1) from error
184
258
 
259
+ if not is_initialized(vault) and interactive():
260
+ if offer_init(vault) is None:
261
+ pp.error(f"{vault} is not a vault")
262
+ raise typer.Exit(1)
263
+ pp.success(f"initialized {vault}")
264
+ return vault
265
+
185
266
  if not is_initialized(vault):
186
267
  # An empty directory is the ordinary bootstrap case, and `sessionmemory init` is safe
187
268
  # for a caller, human or agent, to run there. A non-empty directory holding no
@@ -255,9 +336,18 @@ def require_project(vault: Path, cwd: Path | None = None) -> str:
255
336
  report_malformed_registry(vault, error)
256
337
 
257
338
  if not result.registered or result.slug is None:
339
+ if interactive():
340
+ # Imported here, since the project command imports this module.
341
+ from sessionmemory.commands.project import offer_registration
342
+
343
+ target = (cwd if cwd is not None else Path.cwd()).resolve()
344
+ if offer_registration(vault, target):
345
+ return require_project(vault, target)
346
+ pp.error("this directory is not a registered project")
347
+ raise typer.Exit(1)
258
348
  pp.error(
259
349
  "this directory is not a registered project",
260
- details=["run: sessionmemory project --register"],
350
+ details=["run: sessionmemory project register"],
261
351
  )
262
352
  raise typer.Exit(1)
263
353
  return result.slug
@@ -1,4 +1,4 @@
1
- """The `export` command: write a project's field as a .memoryfield.zip."""
1
+ """The `export` command: write a project's learnings or logs as a .memoryfield.zip."""
2
2
 
3
3
  from __future__ import annotations
4
4
 
@@ -8,6 +8,7 @@ import typer
8
8
  from nclutils import pp
9
9
 
10
10
  from sessionmemory.commands._common import (
11
+ CWD_OPTION,
11
12
  build_embedder,
12
13
  emit_json,
13
14
  fail,
@@ -16,24 +17,27 @@ from sessionmemory.commands._common import (
16
17
  )
17
18
  from sessionmemory.lib import export, field, paths
18
19
 
19
- CWD = typer.Option(None, "--cwd", help="Directory to resolve the project from.")
20
20
  LOGS = typer.Option(False, "--logs", help="Export the logs field instead of learnings.") # noqa: FBT003
21
21
  OUTPUT = typer.Option(
22
22
  None,
23
23
  "--output",
24
- help="Where to write the zip. Defaults to <slug>.memoryfield.zip in the current directory.",
24
+ "-o",
25
+ help=(
26
+ "Where to write the zip. Defaults to <slug>.memoryfield.zip in the current "
27
+ "directory, which is usually the checkout."
28
+ ),
25
29
  )
26
30
  JSON = typer.Option(False, "--json", help="Emit JSON instead of prose.") # noqa: FBT003
27
31
 
28
32
 
29
33
  def export_command(
30
- cwd: Path | None = CWD,
34
+ cwd: Path | None = CWD_OPTION,
31
35
  *,
32
36
  logs: bool = LOGS,
33
37
  output: Path | None = OUTPUT,
34
38
  as_json: bool = JSON,
35
39
  ) -> None:
36
- """Write this project's field as a .memoryfield.zip."""
40
+ """Write this project's learnings, or its logs, as a .memoryfield.zip."""
37
41
  vault = require_vault()
38
42
  slug = require_project(vault, cwd)
39
43
  embedder = build_embedder()
@@ -9,6 +9,7 @@ from pathlib import Path # noqa: TC003
9
9
  import typer
10
10
  from nclutils import pp
11
11
 
12
+ from sessionmemory.commands import _common
12
13
  from sessionmemory.commands._common import VAULT_FIX, emit_json
13
14
  from sessionmemory.lib.bootstrap import InitResult, NotAVaultError, initialize
14
15
  from sessionmemory.lib.config import VaultNotConfiguredError, vault_root
@@ -58,9 +59,10 @@ def init(
58
59
  ) -> None:
59
60
  """Create the files a new vault needs.
60
61
 
61
- A vault cannot be created through `require_vault`, since that helper refuses an
62
- uninitialized directory and this command is what fixes that. When no directory is
63
- given, the configured root is read directly instead.
62
+ Off a terminal, `require_vault` refuses an uninitialized directory, and this command is
63
+ what fixes that. When no directory is given, the configured root is read directly
64
+ instead. On a terminal, a directory holding unrelated files is initialized once the
65
+ person agrees, as if `--force` were given.
64
66
 
65
67
  Raises:
66
68
  Exit: When no directory is given and no vault root is configured or the
@@ -82,7 +84,13 @@ def init(
82
84
  try:
83
85
  result = initialize(vault, force=force)
84
86
  except NotAVaultError as error:
85
- pp.error(str(error))
86
- raise typer.Exit(1) from error
87
+ if not _common.interactive():
88
+ pp.error(str(error))
89
+ raise typer.Exit(1) from error
90
+ question, yes = _common.init_question(vault, force=True)
91
+ if not _common.confirm(question=question, yes=yes):
92
+ pp.error(f"{vault} was not initialized")
93
+ raise typer.Exit(1) from error
94
+ result = initialize(vault, force=True)
87
95
 
88
96
  _report(result, as_json=as_json)
@@ -6,15 +6,22 @@ from pathlib import Path # noqa: TC003
6
6
 
7
7
  import typer
8
8
 
9
- from sessionmemory.commands._common import emit_json, emit_value, require_project, require_vault
9
+ from sessionmemory.commands._common import (
10
+ CWD_OPTION,
11
+ emit_json,
12
+ emit_value,
13
+ require_project,
14
+ require_vault,
15
+ )
10
16
  from sessionmemory.lib import inject
11
17
 
12
- CWD = typer.Option(None, "--cwd", help="Directory to resolve the project from.")
13
18
  COMMAND = typer.Option("sessionmemory", "--command", help="How the guidance names this CLI.")
14
19
  JSON = typer.Option(False, "--json", help="Emit JSON instead of prose.") # noqa: FBT003
15
20
 
16
21
 
17
- def inject_command(cwd: Path | None = CWD, command: str = COMMAND, *, as_json: bool = JSON) -> None:
22
+ def inject_command(
23
+ cwd: Path | None = CWD_OPTION, command: str = COMMAND, *, as_json: bool = JSON
24
+ ) -> None:
18
25
  """Print what this project's session should start with."""
19
26
  vault = require_vault()
20
27
  slug = require_project(vault, cwd)