mindslice 0.1.0__py3-none-any.whl

mindslice/baking/slice_transfer.py

@@ -0,0 +1,265 @@
+"""Reference rewriting, dependency closure and overlay retirement shared by bake and mount.
+
+Every reference (``extends``, ``supersedes``, ``[[wikilinks]]``) is first
+resolved against ``@overlay`` (source-first), then classified:
+
+* included ``@overlay`` target -> written slice-relative (``<path>``)
+* external slice target        -> kept qualified (``@alias/<path>``) and listed
+                                   under ``dependencies`` in ``slice.toml``
+* excluded ``@overlay`` target -> ``UnresolvedExportDependencyError`` unless
+                                   ``include_deps=True`` pulls it in transitively
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, Sequence
+
+from ..model.addressing import MountCatalog, format_address, resolve_ref, rewrite_wikilinks
+from ..model.card import ParsedCard, normalize_newlines, parse_card
+from ..errors import UnresolvedExportDependencyError
+from ..storage.fsutil import iter_markdown
+from ..storage.history import change, event, file_action
+from ..storage.card_io import read_card_file
+from ..model.card import reassemble
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ..workspace import Workspace
+
+
+def rewrite_refs(text: str, parsed: ParsedCard, mapper: Callable[[str], str]) -> str:
+    """``text`` with every ``extends`` / ``supersedes`` / ``[[wikilink]]`` reference passed through ``mapper``.
+
+    Parts no reference touches are kept byte for byte (``reassemble``).
+    """
+    new_ext = [mapper(r) for r in parsed.extends]
+    new_sup = [mapper(r) for r in parsed.supersedes]
+    fields = None
+    if new_ext != parsed.extends or new_sup != parsed.supersedes:
+        fields = dict(parsed.frontmatter)
+        fields["extends"], fields["supersedes"] = new_ext, new_sup
+    link_map = {t: mapper(t) for t in parsed.wikilink_targets()}
+    link_map = {k: v for k, v in link_map.items() if k != v}
+    new_after = rewrite_wikilinks(parsed.after, link_map) if link_map else None
+    return reassemble(parsed, text, fields, new_after)
+
+
+def export_text(text: str, parsed: ParsedCard, overlay_alias: str, cats: dict[str, MountCatalog]) -> str:
+    """The file a new ``bake()`` writes for one overlay card (source-first reference rewriting)."""
+
+    def rewrite(raw: str) -> str:
+        res = resolve_ref(raw, overlay_alias, cats)
+        if res.mount == overlay_alias:
+            if raw.strip().startswith("@") and res.path:
+                return res.path  # @overlay/x -> slice-relative x
+            return raw  # slice-relative refs keep resolving inside the exported slice
+        if res.mount and res.resolved and res.path:
+            return format_address(res.mount, res.path)  # canonical qualified external ref
+        return raw
+
+    return rewrite_refs(text, parsed, rewrite)
+
+
+def overlay_cards(ws: "Workspace", table) -> dict[str, tuple[str, ParsedCard]]:
+    """Every ``@overlay`` card from disk (``{path: (text, parsed)}``), skipping mounts nested inside it."""
+    overlay = table.overlay
+    nested = tuple(o.root for o in table.all() if o.alias != overlay.alias and overlay.root in o.root.parents)
+    cards: dict[str, tuple[str, ParsedCard]] = {}
+    for rel, _ in iter_markdown(overlay.root, exclude=tuple(ws._exclude()) + nested):
+        text, _ = read_card_file(overlay.root / f"{rel}.md")
+        if text is not None:
+            cards[rel] = (text, parse_card(text))
+    return cards
+
+
+def dependency_closure(
+    cards: dict[str, tuple[str, ParsedCard]],
+    selected: Sequence[str],
+    overlay_alias: str,
+    cats: dict[str, MountCatalog],
+    include_deps: bool,
+) -> tuple[set[str], list[str], set[str], list[str]]:
+    """``(included, pulled, external_mounts, warnings)`` for exporting ``selected`` overlay cards.
+
+    A reference to an overlay card outside the selection raises ``UnresolvedExportDependencyError``,
+    unless ``include_deps`` pulls it in (transitively; ``pulled`` lists those).
+    """
+    included = set(selected)
+    pulled: list[str] = []
+    missing: list[dict[str, str]] = []
+    warnings: list[str] = []
+    external: set[str] = set()
+    queue = list(selected)
+    while queue:
+        path = queue.pop(0)
+        parsed = cards[path][1]
+        refs = [(k, r) for k in ("extends", "supersedes") for r in parsed.list_field(k)]
+        refs += [("wikilink", r) for r in parsed.wikilink_targets()]
+        for kind, raw in refs:
+            res = resolve_ref(raw, overlay_alias, cats)
+            if res.mount is None:
+                warnings.append(f"{path}: {kind} reference {raw!r} is not a valid address; copied verbatim")
+                continue
+            if res.mount != overlay_alias:
+                external.add(res.mount)
+                if not res.resolved:
+                    warnings.append(f"{path}: {kind} reference {raw!r} does not resolve in {res.mount}")
+                continue
+            if not res.resolved or res.path not in cards:
+                warnings.append(f"{path}: {kind} reference {raw!r} does not resolve in {overlay_alias}; copied verbatim")
+                continue
+            if res.path in included:
+                continue
+            if include_deps:
+                included.add(res.path)
+                pulled.append(res.path)
+                queue.append(res.path)
+            else:
+                missing.append({"source": format_address(overlay_alias, path), "field": kind, "ref": raw,
+                                "target": format_address(overlay_alias, res.path)})
+    if missing:
+        targets = sorted({m["target"] for m in missing})
+        raise UnresolvedExportDependencyError(
+            f"export references {len(targets)} excluded {overlay_alias} card(s): {', '.join(targets)} "
+            "(pass include_deps=True to pull them in)",
+            missing=missing,
+            next_steps=["Add `--include-deps` to bake those cards into the slice too, or widen `--prefix`/`--tag` "
+                        "so the selection covers them.",
+                        "Or remove the references to them from the selected cards, then bake again."],
+        )
+    return included, pulled, external, warnings
+
+
+def retire_copies(ws: "Workspace", table, alias: str) -> dict[str, Any]:
+    """Remove the ``@overlay`` cards that the newly mounted slice ``alias`` holds unchanged.
+
+    Imported slices may contain copies of overlay cards; once its slice is mounted, the copies left in ``@overlay`` (higher
+    precedence) would shadow it and turn every ``supersedes`` they carry into competing replacements.
+    An overlay card is retired when the export transform of it is exactly the slice's card at the
+    same path: nothing is lost, the slice holds it. It is kept (and reported) when it differs (edited
+    since, or not an exported copy), when it has a staged change, or when a staged card references it.
+    References to a retired card from overlay cards that stay are rewritten to its new address
+    (``[[db/pool]]`` -> ``[[@db/db/pool]]``), so links and lineage keep their targets; references from
+    read-only mounts can't be rewritten and are reported. Runs under the caller's ``LOCK_EX``; the
+    caller syncs the index afterwards.
+    """
+    overlay = table.overlay
+    mount = table.get(alias)
+    idx = ws.index
+    cats = idx.catalogs()
+    staged = set(ws.staging.entries())
+    slice_paths = {r["path"] for r in idx.all_cards(alias)}
+    overlay_paths = {r["path"] for r in idx.all_cards(overlay.alias)}
+    retired: list[str] = []
+    kept: list[dict[str, str]] = []
+    for path in sorted(slice_paths & overlay_paths):
+        o_text, _ = read_card_file(overlay.root / f"{path}.md")
+        s_text, _ = read_card_file(mount.root / f"{path}.md")
+        if o_text is None or s_text is None:
+            continue
+        address = format_address(overlay.alias, path)
+        if path in staged:
+            kept.append({"address": address, "reason": "staged change pending"})
+            continue
+        exported = normalize_newlines(export_text(o_text, parse_card(o_text), overlay.alias, cats))
+        if normalize_newlines(s_text) not in (exported, normalize_newlines(o_text)):
+            kept.append({"address": address, "reason": f"differs from {format_address(alias, path)}"})
+            continue
+        retired.append(path)
+    return retire_overlay_paths(ws, table, alias, retired, kept, cats)
+
+
+def retire_overlay_paths(ws: "Workspace", table, alias: str, retired: list[str], kept: list[dict[str, str]],
+                         cats: dict[str, MountCatalog], *, actions: list | None = None,
+                         events: list | None = None) -> dict[str, Any]:
+    """Remove the ``@overlay`` cards at ``retired`` paths, now held by slice ``alias`` at the same paths.
+
+    References to them from overlay cards that stay are rewritten to ``@alias/<path>``; a card that a
+    staged card references is kept instead (rewriting the overlay file would conflict) and added to
+    ``kept``. Runs under the caller's ``LOCK_EX``; the caller syncs the index afterwards.
+    """
+    own_transaction = actions is None
+    actions = [] if actions is None else actions
+    events = [] if events is None else events
+    overlay = table.overlay
+    idx = ws.index
+    staged = set(ws.staging.entries())
+    retired = list(retired)
+    kept = list(kept)
+
+    def referrers(path: str) -> list[tuple[str, str, str]]:
+        out = []
+        for kind in ("extends", "supersedes", "wikilink"):
+            out += [(kind, r["src_mount"], r["src_path"]) for r in idx.inbound(kind, overlay.alias, path)]
+        return out
+
+    blocked = True
+    while blocked:  # a staged card that references a copy keeps it (rewriting the overlay file would conflict)
+        blocked = False
+        for path in list(retired):
+            stager = next((f"{m}/{p}" for _, m, p in referrers(path)
+                           if m == overlay.alias and p in staged and p not in retired), None)
+            if stager:
+                retired.remove(path)
+                kept.append({"address": format_address(overlay.alias, path), "reason": f"referenced by staged {stager}"})
+                blocked = True
+    retired_set = set(retired)
+
+    def mapper(raw: str) -> str:
+        res = resolve_ref(raw, overlay.alias, cats)
+        if res.resolved and res.mount == overlay.alias and res.path in retired_set:
+            return format_address(alias, res.path)
+        return raw
+
+    rebased: list[dict[str, str]] = []
+    broken: list[dict[str, str]] = []
+    to_rewrite: set[str] = set()
+    for path in retired:
+        target = format_address(overlay.alias, path)
+        for kind, src_mount, src_path in referrers(path):
+            if src_mount == overlay.alias:
+                if src_path not in retired_set:
+                    to_rewrite.add(src_path)
+                continue
+            for link in idx.outbound(src_mount, src_path, kind):
+                if link["resolved"] and format_address(link["dst_mount"], link["dst_path"]) == target:
+                    item = {"address": format_address(src_mount, src_path), "kind": kind, "ref": link["raw"]}
+                    if item not in broken:
+                        broken.append(item)
+    for src_path in sorted(to_rewrite):
+        text, _ = read_card_file(overlay.root / f"{src_path}.md")
+        if text is None:
+            continue
+        parsed = parse_card(text)
+        address = format_address(overlay.alias, src_path)
+        refs = [(k, r) for k in ("extends", "supersedes") for r in parsed.list_field(k)]
+        refs += [("wikilink", r) for r in parsed.wikilink_targets()]
+        changes = [{"address": address, "kind": k, "ref": r, "to": mapper(r)} for k, r in refs if mapper(r) != r]
+        if parsed.errors:
+            broken += [{"address": address, "kind": c["kind"], "ref": c["ref"]} for c in changes]
+            continue
+        new_text = rewrite_refs(text, parsed, mapper)
+        if new_text != normalize_newlines(text):
+            action = file_action(overlay.root / f"{src_path}.md", new_text)
+            actions.append(action)
+            events.append(change("applied", address=address, op="rebase", origin="engine",
+                                 reason=f"Rebase references to cards moved into {alias}",
+                                 before_sha256=action["before_sha256"], after_sha256=action["after_sha256"]))
+            rebased += changes
+    for path in retired:
+        file = overlay.root / f"{path}.md"
+        actions.append(file_action(file, None, overlay.root))
+    out: dict[str, Any] = {}
+    if retired:
+        out["retired_overlay_cards"] = [format_address(overlay.alias, p) for p in retired]
+    if kept:
+        out["shadowing_overlay_cards"] = sorted(kept, key=lambda k: k["address"])
+    if rebased:
+        out["rebased_references"] = rebased
+    if broken:
+        out["broken_references"] = sorted(broken, key=lambda b: (b["address"], b["kind"], b["ref"]))
+    if own_transaction and (actions or events):
+        events.append(event("retired", alias=alias, path=str(table.get(alias).root),
+                            retired_overlay_cards=out.get("retired_overlay_cards", [])))
+        ws.history.transact(actions, events)
+    return out
+

mindslice/errors.py

@@ -0,0 +1,104 @@
+"""Exception hierarchy for MindSlice.
+
+Every error carries a machine-readable ``code`` and an optional ``details``
+payload so CLI and MCP front-ends can serialize failures as structured JSON.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class MindSliceError(Exception):
+    """Base class for all MindSlice errors."""
+
+    code = "mindslice_error"
+
+    def __init__(self, message: str, **details: Any) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"error": type(self).__name__, "code": self.code, "message": self.message}
+        if self.details:
+            out["details"] = self.details
+        return out
+
+
+class WorkspaceNotFoundError(MindSliceError):
+    code = "workspace_not_found"
+
+
+class InvalidAddressError(MindSliceError, ValueError):
+    code = "invalid_address"
+
+
+class AmbiguousAddressError(InvalidAddressError):
+    code = "ambiguous_address"
+
+
+class NotFoundError(MindSliceError, LookupError):
+    code = "not_found"
+
+
+class AlreadyExistsError(MindSliceError):
+    code = "already_exists"
+
+
+class PreconditionFailedError(MindSliceError):
+    """Raised when ``if_match`` does not match the current revision."""
+
+    code = "precondition_failed"
+
+
+class LineageCycleError(MindSliceError):
+    code = "lineage_cycle"
+
+
+class FrontmatterError(MindSliceError, ValueError):
+    code = "invalid_frontmatter"
+
+
+class ReadOnlyMountError(MindSliceError):
+    code = "read_only_mount"
+
+
+class MountError(MindSliceError):
+    code = "mount_error"
+
+
+class ApplyConflictError(MindSliceError):
+    """Raised by ``apply()`` when staged preconditions or graph checks fail."""
+
+    code = "apply_conflict"
+
+
+class UnresolvedExportDependencyError(MindSliceError):
+    code = "unresolved_export_dependency"
+
+
+class BakeConflictError(MindSliceError):
+    """Raised by ``bake()`` before writing anything, when a card can't move into the slice as it is."""
+
+    code = "bake_conflict"
+
+
+class InvalidArgumentsError(MindSliceError, ValueError):
+    """A tool call's arguments don't fit the tool: a required one is missing, or one isn't in its schema."""
+
+    code = "invalid_arguments"
+
+
+class LockTimeoutError(MindSliceError, TimeoutError):
+    code = "lock_timeout"
+
+
+class HistoryError(MindSliceError):
+    code = "history_error"
+
+
+class RecoveryError(MindSliceError):
+    """Recovery or backup cannot proceed without changing its reviewed scope."""
+
+    code = "recovery_error"

mindslice/interfaces/__init__.py

@@ -0,0 +1 @@
+"""CLI and MCP adapters; terminal interaction lives here."""

mindslice/interfaces/bake_review.py

@@ -0,0 +1,230 @@
+"""Human review for workspace bake; prompts go to stderr so stdout carries only the plan or receipt."""
+from __future__ import annotations
+
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+from ..baking import bake_batch
+from ..model.addressing import normalize_alias
+from ..errors import BakeConflictError, InvalidArgumentsError, MindSliceError
+from .render import render_next_steps
+
+
+def render_plan(plan, *, details=False):
+    lines = [f"{len(plan['cards'])} overlay cards", "", "Destination       Cards   Action"]
+    for item in plan["slices"]:
+        lines.append(f"{item['alias']:<18}{len(item['cards']):>5}   {item['action']} → {item['path']} (v{item['version']})")
+        if item["dependencies_added"]:
+            lines.append("  New dependencies: " + ", ".join(item["dependencies_added"]))
+        if item.get("rebased_baseline_cards"):
+            lines.append("  Baseline references updated: " + ", ".join(item["rebased_baseline_cards"]))
+    lines += [f"Needs destination: {len(plan['unassigned'])}", f"Deferred: {len(plan['deferred'])}",
+              f"Remaining overlay cards after bake: {len(plan['remaining_overlay_cards'])}",
+              f"Staged changes excluded: {len(plan['pending_review'])}"]
+    if details:
+        for card in plan["cards"]:
+            lines.append(f"  {card['address']} → {card['destination'] or card['state']}: {card['summary']}")
+            if card["state"] == "unassigned" and card["candidates"]:
+                lines.append("    Related slices: " + ", ".join(card["candidates"]))
+            for change in card.get("changes", []):
+                if change.get("reason"):
+                    lines.append("    Reason: " + change["reason"])
+    for item in plan["retained_overlay_cards"]:
+        lines.append(f"Retain {item['address']}: {item['reason']}")
+    for item in plan["blockers"]:
+        extra = [repr(item["ref"])] if item.get("ref") else []
+        extra += [str(item[k]) for k in ("dependency", "path") if item.get(k)]
+        extra += item.get("errors", []) + item.get("cards", [])
+        lines.append(f"Blocked: {item.get('address', item.get('alias', 'workspace'))}: {item['reason']}"
+                     + (f" ({'; '.join(extra)})" if extra else ""))
+    return "\n".join(lines) + "\n"
+
+
+def render_receipt(result):
+    if result.get("cancelled"):
+        return f"Bake cancelled; destination choices saved in {result['plan_path']}\n"
+    lines = [f"Baked {len(result['baked'])} slice(s)"]
+    lines += [f"{item['alias']}  v{item['version']}  {item['path']}" for item in result["baked"]]
+    lines.append(f"Overlay: {len(result['remaining_overlay_cards'])} remaining cards. "
+                 f"Staging: {result['pending_review']} pending changes.")
+    return "\n".join(lines) + "\n"
+
+
+def _choose_paths(plan, selector):
+    selector = selector.removeprefix("@overlay/").removeprefix("./")
+    ids = [c["id"] for c in plan["cards"]]
+    if selector == "*":
+        return ids
+    if selector.endswith("/"):
+        paths = [p for p in ids if p.startswith(selector)]
+    else:
+        paths = [p for p in ids if p == selector.removesuffix(".md")]
+    if not paths:
+        raise InvalidArgumentsError("selector matches no overlay cards; use an ID, folder/ or *", selector=selector)
+    return paths
+
+
+def _inspect(plan, paths, stream):
+    for c in plan["cards"]:
+        if c["id"] not in paths:
+            continue
+        stream.write(f"\n{c['address']} → {c['destination'] or c['state']}\n{c['summary']}\n")
+        for change in c.get("changes", []):
+            if change.get("reason"):
+                stream.write(f"Reason ({change['op']}): {change['reason']}\n")
+        stream.write(c.get("diff", "") + "\n")
+
+
+def _answer(prompt):
+    sys.stderr.write(prompt)
+    sys.stderr.flush()
+    line = sys.stdin.readline()
+    if not line:
+        raise EOFError
+    return line.strip()
+
+
+def review(ws, plan):
+    """Resume assignments by card hash, but never execute without a fresh final confirmation."""
+    try:
+        while True:
+            sys.stderr.write(render_plan(plan))
+            groups = defaultdict(list)
+            for c in plan["cards"]:
+                if c["state"] == "unassigned":
+                    groups[(c["id"].partition("/")[0], tuple(c["candidates"]))].append(c)
+            for (_, candidates), cards in groups.items():
+                paths = [c["id"] for c in cards]
+                sys.stderr.write("\nNeeds destination:\n")
+                for c in cards:
+                    sys.stderr.write(f"  {c['id']}: {c['summary']}\n")
+                if candidates:
+                    sys.stderr.write("Related slices: " + ", ".join(candidates) + "\n")
+                sys.stderr.write("Mounted slices: " + (", ".join(m.alias for m in ws.table().mounts) or "none") + "\n")
+                while True:
+                    value = _answer("Destination alias (existing or new), inspect, split, defer, or cancel: ")
+                    if value == "cancel":
+                        return None
+                    if value == "inspect":
+                        _inspect(plan, paths, sys.stderr)
+                        continue
+                    if value == "split":
+                        choices = dict(plan["assignments"])
+                        for path in paths:
+                            while True:
+                                dest = _answer(f"{path}: alias, defer, or cancel: ")
+                                if dest == "cancel":
+                                    return None
+                                try:
+                                    choices[path] = None if dest == "defer" else normalize_alias(dest)
+                                    plan = ws.plan_bake(choices, resume=False)
+                                    bake_batch.save_plan(ws, plan)
+                                    break
+                                except (InvalidArgumentsError, ValueError) as exc:
+                                    sys.stderr.write(str(exc) + "\n")
+                        break
+                    try:
+                        dest = None if value == "defer" else normalize_alias(value)
+                        choices = dict(plan["assignments"], **{p: dest for p in paths})
+                        plan = ws.plan_bake(choices, resume=False)
+                        bake_batch.save_plan(ws, plan)
+                        break
+                    except (InvalidArgumentsError, ValueError) as exc:
+                        sys.stderr.write(str(exc) + "\n")
+            sys.stderr.write("\n" + render_plan(plan))
+            action = _answer("[Bake all] [Edit plan] [Inspect] [Cancel]: ").lower()
+            if action in ("cancel", "c", ""):
+                return None
+            if action in ("inspect", "i"):
+                _inspect(plan, [c["id"] for c in plan["cards"]], sys.stderr)
+            elif action in ("edit", "edit plan", "e"):
+                selector = _answer("Cards (ID, folder/, or *): ")
+                value = _answer("Destination alias, or defer: ")
+                try:
+                    paths = _choose_paths(plan, selector)
+                    dest = None if value == "defer" else normalize_alias(value)
+                    plan = ws.plan_bake(dict(plan["assignments"], **{p: dest for p in paths}), resume=False)
+                    bake_batch.save_plan(ws, plan)
+                except (MindSliceError, ValueError) as exc:
+                    sys.stderr.write(str(exc) + "\n")
+            elif action in ("bake", "bake all", "b", "yes", "y"):
+                if plan["ready"]:
+                    return plan
+                sys.stderr.write("Resolve the blockers or defer those cards before baking. Your plan is saved.\n"
+                                 + render_next_steps(bake_batch.next_steps(plan)))
+    except (EOFError, KeyboardInterrupt):
+        sys.stderr.write("\nReview cancelled; destination choices saved.\n")
+        return None
+
+
+def _steps(plan, *, saved):
+    """Next steps for a CLI user: what blocks the plan, then how to run it.
+
+    ``saved`` is False for ``--dry-run``, which keeps no choices: its flags have to be repeated.
+    """
+    steps = bake_batch.next_steps(plan)
+    if steps:
+        return steps + [
+            "Destination choices made so far are saved. Finish with `mindslice bake --yes`; "
+            "`mindslice bake --dry-run` previews the plan." if saved else
+            "Once that is done, re-run this command (with any new `--assign`/`--defer` choices) and "
+            "replace `--dry-run` with `--yes` to bake."]
+    if not plan["cards"]:
+        return []
+    if saved:
+        return ["The plan is ready and saved: run `mindslice bake --yes` to execute it as shown, "
+                "or `mindslice bake` in a terminal to review it card by card."]
+    return ["The plan is ready: replace `--dry-run` with `--yes` to bake it as shown."]
+
+
+def run(ws, args, out):
+    """``out(result, renderer)`` prints human text, or JSON under ``--json``."""
+    single_options = (args.output, args.prefix, args.tags, args.include_deps, args.name, args.description, args.slice_version)
+    if any(x is not None and x is not False for x in single_options):
+        raise InvalidArgumentsError("workspace bake uses --assign/--defer; output/filter/version options require bake @alias")
+    if args.plan and args.fresh:
+        raise InvalidArgumentsError("use either --plan or --fresh")
+    if args.plan:
+        old = bake_batch.load_plan(Path(args.plan))
+        plan = ws.plan_bake(old["assignments"], resume=False)
+        if (old.get("workspace") != plan["workspace"] or old.get("revision") != plan["revision"]
+                or old.get("slices") != plan["slices"]):
+            raise BakeConflictError("saved input plan is stale; regenerate with bake --dry-run", code="stale_bake_plan", next_steps=[
+                "Regenerate the plan from the current workspace: re-run the `mindslice bake ... --dry-run --json` "
+                f"command that produced it and save its output to {args.plan}.",
+                f"Review it, then run `mindslice bake --plan {args.plan} --yes`."])
+    else:
+        plan = ws.plan_bake(resume=not args.fresh)
+    choices = dict(plan["assignments"])
+    for assignment in args.assign or []:
+        selector, sep, alias = assignment.rpartition("=")
+        if not sep:
+            raise InvalidArgumentsError("--assign expects CARD_OR_FOLDER=ALIAS")
+        for path in _choose_paths(plan, selector):
+            choices[path] = normalize_alias(alias)
+    for selector in args.defer or []:
+        for path in _choose_paths(plan, selector):
+            choices[path] = None
+    plan = ws.plan_bake(choices, resume=False)
+    if args.dry_run:
+        out(plan, lambda p: render_plan(p, details=True) + render_next_steps(_steps(p, saved=False)))
+        return 0
+    bake_batch.save_plan(ws, plan)
+    if not plan["cards"]:
+        out({"baked": [], "remaining_overlay_cards": [], "pending_review": len(plan["pending_review"]), "dry_run": False},
+            render_receipt)
+        return 0
+    if not args.yes and sys.stdin.isatty() and not args.json:
+        plan = review(ws, plan)
+        if plan is None:
+            out({"cancelled": True, "plan_path": str(ws.root / bake_batch.PLAN_FILE)}, render_receipt)
+            return 0
+    elif not plan["ready"]:
+        raise BakeConflictError(bake_batch.blocked_message(plan), plan=plan,
+                                plan_path=str(ws.root / bake_batch.PLAN_FILE), next_steps=_steps(plan, saved=True))
+    elif not args.yes:
+        raise BakeConflictError("review required; run in a terminal or use --yes with a reviewed plan",
+                                code="bake_review_required", plan=plan, next_steps=_steps(plan, saved=True))
+    out(ws.bake(plan=plan), render_receipt)
+    return 0