mindslice 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. mindslice/__init__.py +58 -0
  2. mindslice/__main__.py +5 -0
  3. mindslice/baking/__init__.py +1 -0
  4. mindslice/baking/archive.py +66 -0
  5. mindslice/baking/bake.py +299 -0
  6. mindslice/baking/bake_batch.py +537 -0
  7. mindslice/baking/slice_transfer.py +265 -0
  8. mindslice/errors.py +104 -0
  9. mindslice/interfaces/__init__.py +1 -0
  10. mindslice/interfaces/bake_review.py +230 -0
  11. mindslice/interfaces/cli.py +392 -0
  12. mindslice/interfaces/cli_addressing.py +52 -0
  13. mindslice/interfaces/doctor.py +184 -0
  14. mindslice/interfaces/mcp_server.py +536 -0
  15. mindslice/interfaces/render.py +346 -0
  16. mindslice/interfaces/staging_review.py +92 -0
  17. mindslice/model/__init__.py +1 -0
  18. mindslice/model/addressing.py +251 -0
  19. mindslice/model/card.py +641 -0
  20. mindslice/model/lineage.py +228 -0
  21. mindslice/model/text.py +19 -0
  22. mindslice/model/tomlfmt.py +129 -0
  23. mindslice/operations/__init__.py +1 -0
  24. mindslice/operations/audit.py +195 -0
  25. mindslice/operations/boot.py +183 -0
  26. mindslice/operations/impact.py +98 -0
  27. mindslice/operations/recovery.py +113 -0
  28. mindslice/operations/staging.py +641 -0
  29. mindslice/operations/status.py +137 -0
  30. mindslice/operations/validation.py +250 -0
  31. mindslice/operations/writer.py +481 -0
  32. mindslice/retrieval/__init__.py +1 -0
  33. mindslice/retrieval/index.py +634 -0
  34. mindslice/retrieval/lexical.py +215 -0
  35. mindslice/retrieval/query.py +593 -0
  36. mindslice/storage/__init__.py +1 -0
  37. mindslice/storage/card_io.py +14 -0
  38. mindslice/storage/config.py +192 -0
  39. mindslice/storage/fsutil.py +141 -0
  40. mindslice/storage/history.py +182 -0
  41. mindslice/storage/locking.py +125 -0
  42. mindslice/storage/snapshots.py +262 -0
  43. mindslice/workspace.py +385 -0
  44. mindslice-0.1.0.dist-info/METADATA +98 -0
  45. mindslice-0.1.0.dist-info/RECORD +50 -0
  46. mindslice-0.1.0.dist-info/WHEEL +5 -0
  47. mindslice-0.1.0.dist-info/entry_points.txt +2 -0
  48. mindslice-0.1.0.dist-info/licenses/LICENSE +202 -0
  49. mindslice-0.1.0.dist-info/licenses/NOTICE +22 -0
  50. mindslice-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,137 @@
1
+ """Workspace overview for humans: mounts, pending review, and unbaked overlay changes."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import shlex
7
+ import subprocess
8
+ from typing import TYPE_CHECKING, Any
9
+
10
+ from ..model.addressing import format_address
11
+ from ..storage.config import OVERVIEW_PATH
12
+ from .staging import _diff_overlay, _diff_staging
13
+
14
+ if TYPE_CHECKING: # pragma: no cover
15
+ from ..workspace import Workspace
16
+
17
+
18
+ def status(ws: "Workspace") -> dict[str, Any]:
19
+ with ws._reading() as table:
20
+ staged = _diff_staging(ws, table)
21
+ pending = [{k: item[k] for k in ("address", "change", "conflict", "requires_approval", "orphan", "changes", "change_ids") if k in item}
22
+ for item in staged["items"]]
23
+ changes = {m.alias: [] for m in table.mounts}
24
+ unassigned = []
25
+ standing = {format_address(row["mount"], row["path"]) for row in ws.index.always_cards()}
26
+ for item in _diff_overlay(ws, table)["items"]:
27
+ if item["id"] == OVERVIEW_PATH:
28
+ continue
29
+ relations: dict[str, set[str]] = {}
30
+ for field, kind in (("extends", "extends"), ("supersedes", "supersedes"), ("shadows", "shadow")):
31
+ for target in item[field]:
32
+ alias = target.partition("/")[0]
33
+ if alias in changes:
34
+ relations.setdefault(alias, set()).add(kind)
35
+ entry = {k: item[k] for k in ("address", "kind", "unresolved", "unrebased", "changes", "change_ids") if k in item}
36
+ if not relations:
37
+ if entry["address"] in standing:
38
+ entry["standing"] = True # a load="always" card: the overlay is where it normally lives
39
+ unassigned.append(entry)
40
+ for alias, kinds in relations.items():
41
+ changes[alias].append(dict(entry, kinds=sorted(kinds)))
42
+ dirty = []
43
+ mounts = []
44
+ for mount in table.all():
45
+ mounts.append({
46
+ "alias": mount.alias, "path": mount.path, "precedence": mount.precedence, "role": mount.role,
47
+ "kind": mount.kind, "card_count": ws.index.folder_counts(mount.alias)[2],
48
+ "missing": not mount.root.is_dir(), "dirty": bool(changes.get(mount.alias)),
49
+ })
50
+ cards = changes.get(mount.alias, [])
51
+ if cards:
52
+ dirty.append({"alias": mount.alias, "cards": cards, "summary": {
53
+ "total": len(cards),
54
+ **{kind: sum(kind in c["kinds"] for c in cards) for kind in ("extends", "supersedes", "shadow")},
55
+ }})
56
+ overlay_count = next(m["card_count"] for m in mounts if m["kind"] == "overlay")
57
+ summary = {"saved_overlay_cards": overlay_count,
58
+ "mounted_cards": sum(m["card_count"] for m in mounts if m["kind"] != "overlay"),
59
+ "pending_changes": len(pending), "unassigned_cards": len(unassigned)}
60
+ if any(m["missing"] for m in mounts):
61
+ next_step = {"command": "doctor", "reason": "Check missing slice directories."}
62
+ elif pending:
63
+ next_step = {"command": "review", "reason": "Review pending changes before they affect memory."}
64
+ elif dirty or any(not card.get("standing") for card in unassigned):
65
+ next_step = {"command": "bake", "reason": "Optionally organize saved overlay cards into slice versions."}
66
+ else:
67
+ next_step = {"command": "doctor", "reason": "Verify local readiness and follow the new-session check."}
68
+ next_step["arguments"] = ["-w", str(ws.root), next_step["command"]]
69
+ return {
70
+ "memory_state": summary,
71
+ "next_step": next_step,
72
+ "workspace": str(ws.root),
73
+ "mounts": mounts,
74
+ "pending_review": {"files": pending, "summary": staged["summary"]},
75
+ "dirty_slices": dirty,
76
+ "unassigned_overlay_cards": unassigned,
77
+ # Nothing waits for the user: no pending review, no slice with unbaked changes. Overlay cards without
78
+ # a slice destination are saved and live; they are listed, not counted as unfinished work.
79
+ "clean": not (pending or dirty),
80
+ }
81
+
82
+
83
+ def render_status(result: dict[str, Any]) -> str:
84
+ state = result["memory_state"]
85
+ lines = [f"Workspace: {result['workspace']}", "",
86
+ f"Saved memory: {state['saved_overlay_cards']} overlay cards, {state['mounted_cards']} mounted cards.",
87
+ "Overlay memory is already saved and available to retrieval; bake creates reusable slice versions.",
88
+ f"Pending review: {state['pending_changes']} changes, not yet active (existing live cards stay active).",
89
+ f"Not yet assigned to a slice: {state['unassigned_cards']} overlay cards; already saved, not an error.",
90
+ "", f"Mounts ({len(result['mounts'])}):"]
91
+ for mount in result["mounts"]:
92
+ flags = [name for name in ("missing", "dirty") if mount[name]]
93
+ if mount["kind"] == "overlay":
94
+ flags.insert(0, "writable")
95
+ suffix = f" [{', '.join(flags)}]" if flags else ""
96
+ lines.append(f" {mount['alias']} {mount['path']} precedence={mount['precedence']} "
97
+ f"role={mount['role']} cards={mount['card_count']}{suffix}")
98
+ pending = result["pending_review"]
99
+ counts = pending["summary"]
100
+ lines += ["", f"Pending review ({counts['total']}): "
101
+ f"{counts['create']} added, {counts['modify']} modified, {counts['delete']} deleted, "
102
+ f"{counts['conflicts']} conflicts"]
103
+ for item in pending["files"]:
104
+ lines.append(f" {item['change']} {item['address']}")
105
+ for change in item.get("changes", []):
106
+ if change.get("reason"):
107
+ lines.append(f" reason ({change['op']}): {change['reason']}")
108
+ if item.get("requires_approval"):
109
+ lines.append(f" awaiting approval: {item['requires_approval']}")
110
+ if item["conflict"]:
111
+ lines.append(f" conflict: {item['conflict']}")
112
+ lines += ["", f"Dirty slices ({len(result['dirty_slices'])}; unbaked overlay changes):"]
113
+ for item in result["dirty_slices"]:
114
+ counts = item["summary"]
115
+ lines.append(f" {item['alias']}: {counts['total']} cards "
116
+ f"({counts['extends']} extends, {counts['supersedes']} supersedes, {counts['shadow']} shadows)")
117
+ for card in item["cards"]:
118
+ lines.append(f" {card['address']} ({', '.join(card['kinds'])})")
119
+ for change in card.get("changes", []):
120
+ if change.get("reason"):
121
+ lines.append(f" reason ({change['op']}): {change['reason']}")
122
+ new = result["unassigned_overlay_cards"]
123
+ lines += ["", f"Overlay cards without a slice destination ({len(new)}; saved and available):"]
124
+ for card in new:
125
+ lines.append(f" {card['address']}" + (" [standing]" if card.get("standing") else ""))
126
+ for change in card.get("changes", []):
127
+ if change.get("reason"):
128
+ lines.append(f" reason ({change['op']}): {change['reason']}")
129
+ if pending["files"]:
130
+ lines += ["", "Use `mindslice review` to accept/reject individual proposals; `mindslice diff` shows the patch.",
131
+ "`mindslice apply ID...` and `mindslice discard ID...` select cards; omitting IDs affects all pending cards."]
132
+ if result["clean"]:
133
+ lines += ["", "No pending review or unbaked slice changes."]
134
+ command = ["mindslice", *result["next_step"]["arguments"]]
135
+ command = subprocess.list2cmdline(command) if os.name == "nt" else shlex.join(command)
136
+ lines += ["", f"Next: {command} — {result['next_step']['reason']}"]
137
+ return "\n".join(lines) + "\n"
@@ -0,0 +1,250 @@
1
+ """``validate()``: lint slices straight from disk (the index is never trusted here)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections import defaultdict
6
+ from dataclasses import dataclass
7
+ from pathlib import Path
8
+ from typing import TYPE_CHECKING, Any
9
+
10
+ from ..model.addressing import MountCatalog, format_address, normalize_alias, resolve_ref
11
+ from ..model.card import MAX_CARD_LINES, SUMMARY_PREVIEW_CHARS, ParsedCard, parse_card
12
+ from ..storage.config import DESCRIPTION_CHARS, OVERVIEW_PATH, SliceManifest, load_slice_manifest
13
+ from ..errors import InvalidAddressError
14
+ from ..storage.fsutil import iter_markdown
15
+ from ..model.text import fold
16
+ from ..model.lineage import strongly_connected_cycles
17
+ from ..storage.card_io import read_card_file
18
+
19
+ if TYPE_CHECKING: # pragma: no cover
20
+ from ..workspace import Workspace
21
+
22
+
23
+ @dataclass
24
+ class SliceSource:
25
+ alias: str
26
+ root: Path
27
+ manifest: SliceManifest
28
+ kind: str # overlay | slice | standalone
29
+ exclude: tuple[Path, ...] = ()
30
+
31
+
32
+ class Report:
33
+ def __init__(self, target: str) -> None:
34
+ self.target = target
35
+ self.errors: list[dict[str, Any]] = []
36
+ self.warnings: list[dict[str, Any]] = []
37
+ self.cards = 0
38
+ self.slices = 0
39
+
40
+ def add(self, severity: str, code: str, message: str, address: str | None = None, file: str | None = None) -> None:
41
+ issue: dict[str, Any] = {"severity": severity, "code": code, "message": message}
42
+ if address:
43
+ issue["address"] = address
44
+ if file:
45
+ issue["file"] = file
46
+ (self.errors if severity == "error" else self.warnings).append(issue)
47
+
48
+ def to_dict(self) -> dict[str, Any]:
49
+ return {
50
+ "ok": not self.errors,
51
+ "target": self.target,
52
+ "errors": self.errors,
53
+ "warnings": self.warnings,
54
+ "stats": {"slices": self.slices, "cards": self.cards, "errors": len(self.errors), "warnings": len(self.warnings)},
55
+ }
56
+
57
+
58
+ def _deps(manifest: SliceManifest) -> set[str]:
59
+ out = set()
60
+ for dep in manifest.dependencies:
61
+ try:
62
+ out.add(normalize_alias(dep))
63
+ except InvalidAddressError:
64
+ pass
65
+ return out
66
+
67
+
68
+ def lint(
69
+ sources: list[SliceSource],
70
+ report: Report,
71
+ external: dict[str, MountCatalog] | None = None,
72
+ standalone: bool = False,
73
+ ) -> None:
74
+ cats: dict[str, MountCatalog] = dict(external or {})
75
+ cards: dict[tuple[str, str], tuple[ParsedCard, int, Path]] = {}
76
+ for src in sources:
77
+ report.slices += 1
78
+ cat = cats[src.alias] = MountCatalog()
79
+ for rel, _ in sorted(iter_markdown(src.root, exclude=src.exclude)):
80
+ file = src.root / f"{rel}.md"
81
+ text, _ = read_card_file(file)
82
+ if text is None:
83
+ continue
84
+ parsed = parse_card(text)
85
+ lines = text.count("\n") + (0 if text.endswith("\n") or not text else 1)
86
+ cards[(src.alias, rel)] = (parsed, lines, file)
87
+ cat.add(rel, parsed.aliases)
88
+ by_alias = {s.alias: s for s in sources}
89
+ succ: dict[str, list[str]] = defaultdict(list)
90
+
91
+ for src in sources:
92
+ sm = src.manifest
93
+ if sm.errors:
94
+ for err in sm.errors:
95
+ report.add("error", "invalid_slice_manifest", err, file=str(src.root / "slice.toml"))
96
+ if len(sm.description) > DESCRIPTION_CHARS:
97
+ report.add("warning", "long_description", f"slice.toml description exceeds {DESCRIPTION_CHARS} chars",
98
+ file=str(src.root / "slice.toml"))
99
+ if not standalone:
100
+ for dep in sm.dependencies:
101
+ try:
102
+ dep_alias = normalize_alias(dep)
103
+ except InvalidAddressError:
104
+ report.add("error", "invalid_dependency", f"invalid dependency alias {dep!r}", address=src.alias)
105
+ continue
106
+ if dep_alias not in cats:
107
+ report.add("warning", "missing_dependency", f"{src.alias} depends on {dep_alias}, which is not mounted",
108
+ address=src.alias)
109
+
110
+ aliases_seen: dict[tuple[str, str], list[str]] = defaultdict(list)
111
+ for (mount, path), (parsed, lines, file) in sorted(cards.items()):
112
+ report.cards += 1
113
+ address = format_address(mount, path)
114
+ fname = str(file)
115
+ is_overview = path == OVERVIEW_PATH
116
+ for err in parsed.errors:
117
+ report.add("error", "invalid_frontmatter", err, address, fname)
118
+ for warn in parsed.warnings:
119
+ report.add("warning", "frontmatter_schema", warn, address, fname)
120
+ if not is_overview:
121
+ summary = parsed.index_parts()[0]
122
+ if parsed.frontmatter_format == "yaml":
123
+ report.add("warning", "yaml_frontmatter", "legacy --- YAML frontmatter, read as a flat subset "
124
+ "(title, aliases, tags, extends, supersedes); +++ TOML is the card format", address, fname)
125
+ elif not parsed.has_frontmatter:
126
+ report.add("warning", "missing_frontmatter", "plain Markdown (no +++ TOML frontmatter): titled by its "
127
+ "first heading or file name, summarized by its first paragraph", address, fname)
128
+ elif not parsed.title.strip():
129
+ report.add("warning", "missing_title", "frontmatter has no title", address, fname)
130
+ if not summary:
131
+ report.add("warning", "missing_summary", "no summary paragraph directly below the frontmatter"
132
+ if parsed.is_card_format else "no prose paragraph to summarize the note", address, fname)
133
+ elif parsed.is_card_format and len(" ".join(summary.split())) > SUMMARY_PREVIEW_CHARS:
134
+ report.add("warning", "long_summary", f"summary exceeds {SUMMARY_PREVIEW_CHARS} chars", address, fname)
135
+ if lines > MAX_CARD_LINES:
136
+ report.add("warning", "card_too_long", f"card has {lines} lines (> {MAX_CARD_LINES}); consider splitting", address, fname)
137
+ for a in parsed.aliases:
138
+ aliases_seen[(mount, fold(a))].append(path)
139
+
140
+ src = by_alias[mount]
141
+ refs = [(k, r) for k in ("extends", "supersedes") for r in parsed.list_field(k)]
142
+ refs += [("wikilink", r) for r in parsed.wikilink_targets()]
143
+ for kind, raw in refs:
144
+ res = resolve_ref(raw, mount, cats)
145
+ if res.resolved:
146
+ if standalone and res.mount != mount and res.mount not in _deps(src.manifest):
147
+ report.add("warning", "undeclared_dependency",
148
+ f"{kind} reference {raw!r} targets {res.mount}, which is not declared in slice.toml dependencies",
149
+ address, fname)
150
+ if res.address == address:
151
+ if kind != "wikilink":
152
+ report.add("error", "self_reference", f"{kind} points at the card itself", address, fname)
153
+ elif kind != "wikilink":
154
+ succ[address].append(res.address)
155
+ continue
156
+ lineage = kind != "wikilink"
157
+ if res.mount is None:
158
+ report.add("error", "invalid_reference", f"{kind} reference {raw!r} is not a valid address", address, fname)
159
+ elif raw.strip().startswith("@") and res.mount not in cats:
160
+ if standalone and res.mount in _deps(src.manifest):
161
+ continue # declared external dependency; target cannot be checked here
162
+ code = "undeclared_dependency" if standalone else "unmounted_dependency"
163
+ report.add("warning", code, f"{kind} reference {raw!r} targets {res.mount}, which is "
164
+ + ("not declared in slice.toml dependencies" if standalone else "not mounted"), address, fname)
165
+ elif lineage:
166
+ report.add("error", "broken_lineage", f"{kind} target {raw!r} does not exist", address, fname)
167
+ else:
168
+ report.add("warning", "broken_wikilink", f"[[{raw}]] does not resolve", address, fname)
169
+
170
+ for (mount, alias), paths in sorted(aliases_seen.items()):
171
+ if len(set(paths)) > 1:
172
+ report.add("warning", "duplicate_alias", f"alias {alias!r} is used by {', '.join(sorted(set(paths)))}",
173
+ address=mount)
174
+ nodes = sorted(set(succ) | {t for ts in succ.values() for t in ts})
175
+ for comp in strongly_connected_cycles(nodes, lambda n: succ.get(n, ())):
176
+ report.add("error", "lineage_cycle", "circular extends/supersedes chain: " + " -> ".join(comp + comp[:1]),
177
+ address=comp[0])
178
+
179
+
180
+ def validate(ws: "Workspace | None", slice_path: str | Path | None = None, rebuild_index: bool = False) -> dict[str, Any]:
181
+ rebuilt = None
182
+ if rebuild_index:
183
+ if ws is None:
184
+ raise ValueError("rebuild_index requires a workspace")
185
+ with ws._writing(sync=False) as table:
186
+ rebuilt = ws.index.rebuild(table, ws._exclude()).to_dict()
187
+ if slice_path is None:
188
+ if ws is None:
189
+ raise ValueError("validate() needs a workspace or a slice_path")
190
+ out = _validate_workspace(ws)
191
+ else:
192
+ out = validate_slice_dir(Path(slice_path), ws)
193
+ out["rebuilt_index"] = rebuilt
194
+ return out
195
+
196
+
197
+ def _validate_workspace(ws: "Workspace") -> dict[str, Any]:
198
+ with ws._reading() as table:
199
+ report = Report(str(ws.root))
200
+ sources = []
201
+ exclude = tuple(ws._exclude())
202
+ for m in table.all():
203
+ nested = tuple(o.root for o in table.all() if o.alias != m.alias and m.root in o.root.parents)
204
+ if not m.root.is_dir():
205
+ report.add("error", "missing_mount", f"mount path {m.path} does not exist", address=m.alias)
206
+ continue
207
+ sources.append(SliceSource(m.alias, m.root, load_slice_manifest(m.root), m.kind, exclude + nested))
208
+ lint(sources, report)
209
+ # Staged files must be valid cards; conflicts are reported (apply would abort on them).
210
+ from .staging import precondition_conflict # local import: staging imports writer
211
+
212
+ overlay = table.overlay
213
+ for path, entry in ws.staging.entries().items():
214
+ address = format_address(overlay.alias, path)
215
+ _, current = read_card_file(overlay.root / f"{path}.md")
216
+ conflict = precondition_conflict(entry.get("base_sha256"), current)
217
+ if conflict:
218
+ report.add("warning", "staging_conflict", f"staged change would not apply: {conflict}", address)
219
+ if entry.get("op") != "delete":
220
+ text, _ = read_card_file(ws.staging.file(path))
221
+ if text is None:
222
+ report.add("error", "staged_file_missing", "manifest entry has no staged file", address)
223
+ continue
224
+ for err in parse_card(text).errors:
225
+ report.add("error", "invalid_staged_card", err, address, str(ws.staging.file(path)))
226
+ return report.to_dict()
227
+
228
+
229
+ def validate_slice_dir(root: Path, ws: "Workspace | None" = None) -> dict[str, Any]:
230
+ """Validate a standalone ``.slice`` directory (mounted or not)."""
231
+ root = Path(root).resolve()
232
+ report = Report(str(root))
233
+ if not root.is_dir():
234
+ report.add("error", "missing_slice", f"{root} is not a directory")
235
+ return report.to_dict()
236
+ sm = load_slice_manifest(root)
237
+ alias_name = sm.alias or root.name.removesuffix(".slice")
238
+ try:
239
+ alias = normalize_alias(alias_name)
240
+ except InvalidAddressError:
241
+ alias = "@self"
242
+ external: dict[str, MountCatalog] = {}
243
+ if ws is not None:
244
+ with ws._reading():
245
+ external = {a: c for a, c in ws.index.catalogs().items() if a != alias}
246
+ for row in ws.index.mount_rows():
247
+ if Path(row["root"]) == root:
248
+ external.pop(row["alias"], None)
249
+ lint([SliceSource(alias, root, sm, "standalone")], report, external=external, standalone=True)
250
+ return report.to_dict()