mdcompose 0.1.0__py3-none-any.whl

mdcompose/commands/snippet_cmd.py

@@ -0,0 +1,312 @@
+"""The snippet command group: list, edit, remove, adopt.
+
+A thin adapter. Each command parses arguments, resolves the library, calls into
+core, and formats the result. The prompting lives here and the outcome lives in
+core, which is what lets a flag and an answered prompt reach the same code.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from mdcompose.core import config as config_module
+from mdcompose.core import files, library_ops
+from mdcompose.core import manifest as manifest_module
+from mdcompose.core import platform as platform_module
+from mdcompose.core import snippets as snippets_module
+from mdcompose.core.exit_codes import AttentionError
+from mdcompose.core.output import OutputContext
+from mdcompose.prompts import confirm, output_for, prompt_choice
+
+app = typer.Typer(
+    name="snippet",
+    help="Manage the personal snippet library.",
+    rich_markup_mode=None,
+    no_args_is_help=True,
+)
+
+QuietOption = Annotated[
+    bool, typer.Option("--quiet", "-q", help="Suppress informational output.")
+]
+JsonOption = Annotated[
+    bool, typer.Option("--json", help="Emit one JSON document on stdout and nothing else.")
+]
+NoColourOption = Annotated[bool, typer.Option("--no-color", help="Never colourize output.")]
+TagOption = Annotated[str | None, typer.Option("--tag", help="Only snippets carrying this tag.")]
+CategoryOption = Annotated[
+    str | None, typer.Option("--category", help="Only snippets in this category.")
+]
+ContentOption = Annotated[
+    str | None,
+    typer.Option(
+        "--content", help="Replacement file contents. Supplying this skips the editor."
+    ),
+]
+YesOption = Annotated[bool, typer.Option("--yes", "-y", help="Answer yes to every confirmation.")]
+OnCollisionOption = Annotated[
+    str | None,
+    typer.Option(
+        "--on-collision",
+        help="Resolve every collision without asking: keep or overwrite.",
+    ),
+]
+IdsArgument = Annotated[
+    list[str] | None,
+    typer.Argument(help="Snippet ids to adopt. Defaults to every embedded snippet."),
+]
+
+
+def resolve_library() -> snippets_module.LibraryView:
+    """Read the configured snippet library once."""
+    directory = platform_module.config_dir()
+    configuration = config_module.load_config(config_module.config_path(directory))
+    return snippets_module.view(config_module.library_dir(configuration, directory))
+
+
+@app.command("list")
+def list_snippets(
+    context: typer.Context,
+    tag: TagOption = None,
+    category: CategoryOption = None,
+    quiet: QuietOption = False,
+    json_output: JsonOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """List the snippets in the library.
+
+    Filters narrow rather than widen: supplying both a tag and a category lists
+    only snippets matching both. An empty library is reported, not an error.
+    """
+    output = output_for(context, quiet=quiet, json_output=json_output, no_colour=no_colour)
+    library = resolve_library()
+    matched = snippets_module.filter_snippets(library.snippets, tag=tag, category=category)
+
+    if output.json_mode:
+        output.emit(_as_json(library, matched))
+        return
+
+    if library.is_empty:
+        output.info(
+            f"the snippet library at {library.directory.as_posix()} is empty. "
+            "Add one with 'mdcompose import <file> --save-as-snippet <name>'."
+        )
+        return
+    if not matched:
+        output.info("no snippet matches that filter")
+        return
+
+    id_width = max(len(snippet.id) for snippet in matched)
+    name_width = max(len(snippet.display_name) for snippet in matched)
+    id_width = max(id_width, len("id"))
+    name_width = max(name_width, len("name"))
+    output.info(f"  {'id'.ljust(id_width)}  {'name'.ljust(name_width)}  description")
+    for snippet in matched:
+        row_id = snippet.id.ljust(id_width)
+        row_name = snippet.display_name.ljust(name_width)
+        description = "" if snippet.description is None else snippet.description
+        output.info(f"  {row_id}  {row_name}  {description}")
+
+
+def _as_json(
+    library: snippets_module.LibraryView, matched: tuple[snippets_module.Snippet, ...]
+) -> str:
+    return json.dumps(
+        {
+            "library": library.directory.as_posix(),
+            "snippets": [
+                {
+                    "id": snippet.id,
+                    "title": snippet.title,
+                    "description": snippet.description,
+                    "tags": list(snippet.tags),
+                    "applies_to": snippet.applies_to,
+                    "stack_signals": list(snippet.stack_signals),
+                    "category": snippet.category,
+                    "order": snippet.order,
+                }
+                for snippet in matched
+            ],
+        },
+        indent=2,
+        ensure_ascii=True,
+    )
+
+
+@app.command("edit")
+def edit_snippet(
+    context: typer.Context,
+    snippet_id: Annotated[str, typer.Argument(help="The snippet to edit.")],
+    content: ContentOption = None,
+    quiet: QuietOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Open a snippet in the configured editor, or replace its contents directly.
+
+    The result is validated before it is installed, so a broken edit leaves the
+    existing snippet exactly as it was.
+    """
+    output = output_for(context, quiet=quiet, no_colour=no_colour)
+    library = resolve_library()
+    snippet = library.require(snippet_id)
+
+    if content is not None:
+        library_ops.replace_body(library, snippet_id, content)
+        output.info(f"wrote {snippet_id}")
+        return
+
+    if snippet.path is None:
+        raise AttentionError(f"snippet '{snippet_id}' has no file on disk to edit")
+    edited = _edit_in_editor(snippet.path)
+    if edited is None:
+        output.info(f"{snippet_id} unchanged")
+        return
+    library_ops.replace_body(library, snippet_id, edited)
+    output.info(f"wrote {snippet_id}")
+
+
+def _edit_in_editor(path: Path) -> str | None:
+    """Open a copy in the editor and return the result, or None if unchanged.
+
+    A copy rather than the file itself, so an edit that fails validation cannot
+    leave the library holding it.
+    """
+    editor = os.environ.get("VISUAL") or os.environ.get("EDITOR")
+    if not editor:
+        raise AttentionError(
+            "no editor configured. Set VISUAL or EDITOR, or pass --content to "
+            "supply the new contents directly."
+        )
+    original = files.read_text(path)
+    with tempfile.TemporaryDirectory() as scratch:
+        draft = Path(scratch) / path.name
+        files.write_text(draft, original)
+        completed = subprocess.run([*shlex.split(editor), str(draft)], check=False)
+        if completed.returncode != 0:
+            raise AttentionError(f"editor exited with status {completed.returncode}")
+        edited = files.read_text(draft)
+    return None if files.content_equal(edited, original) else edited
+
+
+@app.command("remove")
+def remove_snippet(
+    context: typer.Context,
+    snippet_id: Annotated[str, typer.Argument(help="The snippet to delete.")],
+    yes: YesOption = False,
+    quiet: QuietOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Delete a snippet from the library.
+
+    Confirms first. Never touches a project that already composed it: composition
+    copies content, so a composed file keeps working without its source snippet.
+    """
+    output = output_for(context, quiet=quiet, no_colour=no_colour)
+    library = resolve_library()
+    library.require(snippet_id)
+
+    if not confirm(output, f"delete snippet '{snippet_id}' from the library?", assume_yes=yes):
+        output.info(f"kept {snippet_id}")
+        return
+    library_ops.remove_snippet(library, snippet_id)
+    output.info(f"removed {snippet_id}")
+
+
+@app.command("adopt")
+def adopt_snippets(
+    context: typer.Context,
+    ids: IdsArgument = None,
+    on_collision: OnCollisionOption = None,
+    quiet: QuietOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Save the snippets embedded in this project's manifest into the library.
+
+    Always explicit, never a side effect of composing, because pulling someone
+    else's conventions into a personal library should be a deliberate act.
+    Touches no project file and no manifest.
+    """
+    output = output_for(context, quiet=quiet, no_colour=no_colour)
+    project_root = Path.cwd()
+    manifest = manifest_module.load_manifest(manifest_module.manifest_path(project_root))
+    if manifest is None:
+        raise AttentionError(
+            f"{project_root.as_posix()} has no {manifest_module.MANIFEST_FILENAME}, "
+            "so there is nothing to adopt"
+        )
+
+    library = resolve_library()
+    plan = library_ops.plan_adopt(manifest, library, only=tuple(ids or ()))
+    if plan.is_empty:
+        output.info("the manifest embeds no snippets")
+        return
+
+    resolutions = _resolve_collisions(output, plan, on_collision)
+    result = library_ops.apply_adopt(plan, library.directory, resolutions=resolutions)
+    _report_adoption(output, result)
+
+
+def _resolve_collisions(
+    output: OutputContext,
+    plan: library_ops.AdoptPlan,
+    on_collision: str | None,
+) -> dict[str, library_ops.Resolution]:
+    """Decide what to do about each collision, by flag or by asking."""
+    if not plan.collisions:
+        return {}
+    if on_collision is not None:
+        decision = _validated_resolution(on_collision)
+        return {collision.snippet_id: decision for collision in plan.collisions}
+
+    resolutions: dict[str, library_ops.Resolution] = {}
+    for collision in plan.collisions:
+        output.warn(
+            f"snippet '{collision.snippet_id}' already exists in the library with "
+            "different content"
+        )
+        _show_difference(output, collision)
+        answer = prompt_choice(
+            output,
+            f"snippet '{collision.snippet_id}'",
+            options=library_ops.RESOLUTIONS,
+            default=library_ops.KEEP,
+            flag="--on-collision",
+        )
+        resolutions[collision.snippet_id] = answer  # type: ignore[assignment]
+    return resolutions
+
+
+def _validated_resolution(candidate: str) -> library_ops.Resolution:
+    if candidate not in library_ops.RESOLUTIONS:
+        raise AttentionError(
+            f"--on-collision must be one of {', '.join(library_ops.RESOLUTIONS)}, "
+            f"found '{candidate}'"
+        )
+    return candidate
+
+
+def _show_difference(output: OutputContext, collision: library_ops.Collision) -> None:
+    """Show both versions, so the choice is made with the content in view."""
+    output.info(f"  library copy of '{collision.snippet_id}':")
+    output.content_indented(collision.local)
+    output.info(f"  embedded copy of '{collision.snippet_id}':")
+    output.content_indented(collision.embedded)
+
+
+def _report_adoption(output: OutputContext, result: library_ops.AdoptResult) -> None:
+    for outcome, phrasing in (
+        ("written", "adopted"),
+        ("overwritten", "overwrote"),
+        ("already-present", "already present"),
+        ("kept", "kept the library copy of"),
+    ):
+        named = result.ids_with(outcome)  # type: ignore[arg-type]
+        if named:
+            output.info(f"  {phrasing}: {', '.join(named)}")

mdcompose/commands/target_cmd.py

@@ -0,0 +1,134 @@
+"""The target command group: add, list, remove.
+
+A target is a tool-specific global location the canonical global AGENTS.md is
+projected into. These commands own the ``registered_global_targets`` config
+field; ``config set`` refuses it because its uniqueness and absoluteness rules
+cannot be enforced from a single key and value.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from mdcompose.core import config as config_module
+from mdcompose.core import files, managed_block
+from mdcompose.core import platform as platform_module
+from mdcompose.core import targets as targets_module
+from mdcompose.prompts import output_for
+
+app = typer.Typer(
+    name="target",
+    help="Register tool-specific global locations for projection.",
+    rich_markup_mode=None,
+    no_args_is_help=True,
+)
+
+QuietOption = Annotated[bool, typer.Option("--quiet", "-q", help="Suppress informational output.")]
+JsonOption = Annotated[
+    bool, typer.Option("--json", help="Emit one JSON document on stdout and nothing else.")
+]
+NoColourOption = Annotated[bool, typer.Option("--no-color", help="Never colourize output.")]
+
+
+def _config() -> tuple[Path, config_module.GlobalConfig]:
+    path = config_module.config_path(platform_module.config_dir())
+    return path, config_module.load_config(path)
+
+
+@app.command("add")
+def add(
+    context: typer.Context,
+    label: Annotated[str, typer.Argument(help="A short name for the target.")],
+    path: Annotated[str, typer.Argument(help="Absolute path of the tool's global file.")],
+    quiet: QuietOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Register a tool-specific global location. Writes no file at the path."""
+    output = output_for(context, quiet=quiet, no_colour=no_colour)
+    config_path, configuration = _config()
+    updated = targets_module.add_target(configuration, label, path)
+    entry = updated.registered_global_targets[-1]
+    info = platform_module.detect_platform()
+    if platform_module.is_on_windows_mount(Path(entry.path), info):
+        output.warn(
+            f"{entry.path} is on a Windows drive mounted under "
+            f"{platform_module.WINDOWS_MOUNT_PREFIX}, which crosses the WSL and Windows "
+            "filesystem boundary"
+        )
+    config_module.write_config(updated, config_path)
+    output.info(f"registered '{label}' at {entry.path}")
+
+
+@app.command("remove")
+def remove(
+    context: typer.Context,
+    label: Annotated[str, typer.Argument(help="The target to unregister.")],
+    quiet: QuietOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Unregister a target. Its file is left exactly where it is."""
+    output = output_for(context, quiet=quiet, no_colour=no_colour)
+    config_path, configuration = _config()
+    updated = targets_module.remove_target(configuration, label)  # raises on an unknown label
+    existing = next(t for t in configuration.registered_global_targets if t.label == label)
+    config_module.write_config(updated, config_path)
+    output.info(
+        f"unregistered '{label}'. Its file at {existing.path} was left in place; "
+        "delete it by hand if you no longer need it."
+    )
+
+
+@app.command("list")
+def list_targets(
+    context: typer.Context,
+    quiet: QuietOption = False,
+    json_output: JsonOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Show every registered target, its path, and whether its file is in sync."""
+    output = output_for(context, quiet=quiet, json_output=json_output, no_colour=no_colour)
+    _, configuration = _config()
+    canonical = _canonical_content(configuration)
+    entries = configuration.registered_global_targets
+
+    def sync_of(entry: config_module.TargetEntry) -> str:
+        if canonical is None:
+            return "unknown"
+        return targets_module.sync_status(entry, canonical)
+
+    if output.json_mode:
+        rows = [
+            {
+                "label": entry.label,
+                "path": targets_module.target_path(entry).as_posix(),
+                "present": files.path_exists(targets_module.target_path(entry)),
+                "sync": sync_of(entry),
+            }
+            for entry in entries
+        ]
+        output.emit(json.dumps({"targets": rows}, indent=2, ensure_ascii=True))
+        return
+    if not entries:
+        output.info("no targets registered")
+        return
+    width = max(len(entry.label) for entry in entries)
+    for entry in entries:
+        path = targets_module.target_path(entry)
+        present = "present" if files.path_exists(path) else "absent"
+        label = entry.label.ljust(width)
+        output.info(f"  {label}  {sync_of(entry):12}  {present}  {path.as_posix()}")
+
+
+def _canonical_content(configuration: config_module.GlobalConfig) -> str | None:
+    """The composed content of the canonical global AGENTS.md, or None when unresolvable."""
+    if configuration.global_agents_path is None:
+        return None
+    path = Path(configuration.global_agents_path).expanduser()
+    if not (files.path_exists(path) and path.is_file()):
+        return None
+    block = managed_block.scan(files.read_text(path)).find(targets_module.TARGET_BLOCK)
+    return None if block is None else block.content

mdcompose/core/composition.py

@@ -0,0 +1,96 @@
+"""Turning a snippet selection into the content of AGENTS.md and CLAUDE.md.
+
+Mode is a property of CLAUDE.md alone. AGENTS.md is byte-identical whichever mode
+a project uses, because AGENTS.md is always plain import-agnostic markdown: the
+`@import` directive is a Claude Code mechanism and no other tool resolves it.
+Keeping the mode recorded per pair matches how a user thinks about it, while only
+one branch in this module ever reads it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from mdcompose.core import files, managed_block
+from mdcompose.core.config import Mode
+from mdcompose.core.snippets import Snippet, compose_order
+
+IMPORT: Mode = "import"
+COPY: Mode = "copy"
+
+SEPARATOR = "\n"
+
+Scope = Literal["agents", "claude"]
+
+
+@dataclass(frozen=True, slots=True)
+class Composition:
+    """The content both managed blocks should hold for one selection and mode."""
+
+    agents_block: str
+    claude_block: str
+    snippet_ids: tuple[str, ...]
+    imports: str | None
+
+
+def compose(
+    selection: Sequence[Snippet],
+    *,
+    mode: Mode,
+    import_target: str = "AGENTS.md",
+) -> Composition:
+    """Work out both blocks' content from one selection.
+
+    ``import_target`` is the path CLAUDE.md points at in import mode, relative to
+    CLAUDE.md itself. It is normally the AGENTS.md beside it, but a subdirectory
+    CLAUDE.md may import one from elsewhere in the repository.
+    """
+    ordered = compose_order(selection)
+    return Composition(
+        agents_block=_join_bodies(item for item in ordered if item.applies_to_agents()),
+        claude_block=(
+            import_directive(import_target)
+            if mode == IMPORT
+            else _join_bodies(item for item in ordered if item.applies_to_claude())
+        ),
+        snippet_ids=tuple(item.id for item in ordered),
+        imports=import_target if mode == IMPORT else None,
+    )
+
+
+def import_directive(target: str) -> str:
+    """Return the import directive CLAUDE.md carries in import mode."""
+    return f"@{target}\n"
+
+
+def _join_bodies(selected: Iterable[Snippet]) -> str:
+    """Concatenate snippet bodies with one blank line between them."""
+    bodies = [files.normalize(item.body).strip("\n") for item in selected]
+    present = [body for body in bodies if body]
+    if not present:
+        return ""
+    return SEPARATOR.join(f"{body}\n" for body in present)
+
+
+def apply_to_file(
+    path: Path,
+    block_id: str,
+    content: str,
+) -> bool:
+    """Write one block into a file, returning whether anything changed.
+
+    Creates the file when it does not exist. Preserves every byte outside the
+    block, and preserves the file's existing line endings. Returns False when the
+    result would be identical to what is already there, so a repeat run is a
+    no-op rather than a rewrite.
+    """
+    existing = files.read_text(path) if files.path_exists(path) and path.is_file() else ""
+    updated = managed_block.upsert(existing, block_id, content, path)
+    if existing and files.content_equal(existing, updated):
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    files.write_text(path, updated, line_ending=files.line_ending_for(path))
+    return True