mdcompose 0.1.0__py3-none-any.whl

mdcompose/cli.py

@@ -0,0 +1,219 @@
+"""The mdcompose command line interface.
+
+A thin adapter over the core layer. Commands parse arguments, call core, and
+format the result. No detection, path resolution, encoding, or config logic
+lives here, which is what lets the core behavior be documented as a contract
+independent of Python and of Typer.
+
+Rich markup is disabled deliberately. Its help output draws boxes with Unicode
+characters, which would break the plain-ASCII guarantee that exists so a legacy
+Windows console cannot raise an encoding error.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from mdcompose.commands import (
+    config_cmd,
+    convert_cmd,
+    eject_cmd,
+    import_cmd,
+    init_cmd,
+    snippet_cmd,
+    target_cmd,
+)
+from mdcompose.core import report as report_module
+from mdcompose.core.exit_codes import EXIT_ATTENTION, EXIT_INTERNAL, EXIT_OK, AttentionError
+from mdcompose.core.output import GlobalOptions, OutputContext, assert_ascii
+from mdcompose.prompts import output_for
+from mdcompose.version import PACKAGE_NAME, resolve_version
+
+app = typer.Typer(
+    name=PACKAGE_NAME,
+    help="Manage CLAUDE.md and AGENTS.md, and compose them from a personal snippet library.",
+    rich_markup_mode=None,
+    add_completion=False,
+)
+
+
+def _version_callback(requested: bool) -> None:
+    if not requested:
+        return
+    print(assert_ascii(resolve_version()), file=sys.stdout)
+    raise typer.Exit(EXIT_OK)
+
+
+QuietOption = Annotated[
+    bool,
+    typer.Option("--quiet", "-q", help="Suppress informational output. Errors still print."),
+]
+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."),
+]
+VersionOption = Annotated[
+    bool,
+    typer.Option(
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+]
+
+
+@app.callback()
+def main(
+    context: typer.Context,
+    quiet: QuietOption = False,
+    json_output: JsonOption = False,
+    no_colour: NoColourOption = False,
+    _version: VersionOption = False,
+) -> None:
+    """Record the flags every command shares on the Typer context."""
+    context.obj = GlobalOptions(quiet=quiet, json_mode=json_output, no_colour=no_colour)
+
+
+app.add_typer(snippet_cmd.app, name="snippet")
+app.add_typer(config_cmd.app, name="config")
+app.add_typer(target_cmd.app, name="target")
+init_cmd.register(app)
+import_cmd.register(app)
+convert_cmd.register(app)
+eject_cmd.register(app)
+
+
+@app.command()
+def doctor(
+    context: typer.Context,
+    quiet: QuietOption = False,
+    json_output: JsonOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Report the detected platform and every path mdcompose resolves.
+
+    Creates nothing, modifies nothing, and never prompts, so it is safe to run
+    anywhere. Exits 0 when healthy and 1 when something needs attention, which
+    makes it usable as a CI gate without parsing its output.
+    """
+    output = output_for(
+        context, quiet=quiet, json_output=json_output, no_colour=no_colour
+    )
+    report = report_module.build_doctor_report(project_root=Path.cwd())
+
+    for warning in report.warnings:
+        output.warn(warning)
+
+    if output.json_mode:
+        output.emit(report.to_json())
+    else:
+        render_doctor(output, report)
+
+    if report.needs_attention:
+        raise typer.Exit(EXIT_ATTENTION)
+
+
+def render_doctor(output: OutputContext, report: report_module.DoctorReport) -> None:
+    """Format the report for a person reading a terminal.
+
+    Every status is readable from the text, so nothing depends on colour, and
+    the columns align because every generated character is ASCII.
+    """
+    output.info(output.bold("platform"))
+    output.info(f"  os   {report.os_name}")
+    output.info(f"  wsl  {'yes' if report.is_wsl else 'no'}")
+    output.info("")
+    output.info(output.bold("paths"))
+
+    label_width = max(len(entry.label) for entry in report.entries)
+    status_width = max(len(entry.status) for entry in report.entries)
+    for entry in report.entries:
+        location = "-" if entry.resolved is None else entry.resolved.path.as_posix()
+        label = entry.label.ljust(label_width)
+        status = entry.status.ljust(status_width)
+        output.info(f"  {label}  {status}  {location}")
+
+    if report.targets:
+        output.info("")
+        output.info(output.bold("registered targets"))
+        label_width = max(len(target.label) for target in report.targets)
+        for target in report.targets:
+            present = "present" if target.present else "absent"
+            output.info(
+                f"  {target.label.ljust(label_width)}  {target.sync:12}  {present}  {target.path}"
+            )
+
+    output.info("")
+    output.info(output.bold("managed files"))
+    if report.drift is None:
+        output.info("  not initialized, mdcompose has not composed this directory")
+        return
+    if not report.drift:
+        output.info("  the manifest records no managed files")
+        return
+    key_width = max(len(drift.key) for drift in report.drift)
+    for drift in report.drift:
+        detail = "" if drift.detail is None else f"  ({drift.detail})"
+        output.info(f"  {drift.key.ljust(key_width)}  {drift.status}{detail}")
+
+
+def run(argv: list[str] | None = None) -> int:
+    """The single error boundary. Every exception becomes an exit code here.
+
+    ``AttentionError`` means mdcompose worked and is reporting a real condition
+    the user must resolve, so it exits 1 with the message on stderr. A usage
+    error or an unexpected exception means mdcompose could not do its job, so
+    both exit 2.
+
+    Typer 0.27 vendors Click as a private module, so the usage error family is
+    caught through the public ``typer.TyperException``, which every vendored
+    Click exception inherits from.
+
+    A command signals a non-zero outcome by raising ``typer.Exit``. Outside
+    standalone mode Typer does not let that propagate; it converts it into the
+    value ``app`` returns. So the return value is the exit code, and ignoring it
+    would silently turn every non-zero outcome into success.
+
+    ``argv`` defaults to the real command line. Tests pass it explicitly so the
+    boundary itself is exercised rather than bypassed.
+
+    A bare invocation shows help and succeeds. Running mdcompose with no
+    arguments is not mdcompose failing, so it does not earn exit code 2.
+    """
+    arguments = sys.argv[1:] if argv is None else argv
+    if not arguments:
+        arguments = ["--help"]
+    try:
+        result = app(args=arguments, prog_name=PACKAGE_NAME, standalone_mode=False)
+    except AttentionError as error:
+        print(assert_ascii(f"error: {error.message}"), file=sys.stderr)
+        return EXIT_ATTENTION
+    except typer.Exit as request:
+        return request.exit_code
+    except typer.Abort:
+        print("error: aborted", file=sys.stderr)
+        return EXIT_ATTENTION
+    except typer.TyperException as error:
+        show = getattr(error, "show", None)
+        if show is None:
+            print(f"error: {error}", file=sys.stderr)
+        else:
+            show()
+        return EXIT_INTERNAL
+    except Exception as error:  # the boundary must catch everything
+        print(
+            f"error: mdcompose failed unexpectedly ({type(error).__name__}: {error}). "
+            "This is a bug in mdcompose.",
+            file=sys.stderr,
+        )
+        return EXIT_INTERNAL
+    return EXIT_OK if result is None else int(result)

mdcompose/commands/config_cmd.py

@@ -0,0 +1,172 @@
+"""The config command group: show, set, unset, edit.
+
+The write half of a capability change 1 left half-built. Reading the config
+already existed; these commands are the way to change it without hand-editing a
+JSON file whose location the user would have to work out from `doctor`.
+
+Every write goes through `config.write_config`, which validates nothing itself:
+validation is `config.apply_set`'s job and runs before the file is touched, so a
+rejected value cannot corrupt the config.
+"""
+
+from __future__ import annotations
+
+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
+from mdcompose.core import platform as platform_module
+from mdcompose.core.exit_codes import AttentionError
+from mdcompose.core.output import OutputContext
+from mdcompose.prompts import output_for
+
+app = typer.Typer(
+    name="config",
+    help="Show and change the global configuration.",
+    rich_markup_mode=None,
+    no_args_is_help=True,
+)
+
+QuietOption = Annotated[bool, typer.Option("--quiet", "-q", help="Suppress informational output.")]
+NoColourOption = Annotated[bool, typer.Option("--no-color", help="Never colourize output.")]
+
+
+def _resolve() -> tuple[Path, Path]:
+    directory = platform_module.config_dir()
+    return directory, config_module.config_path(directory)
+
+
+@app.command("show")
+def show(
+    context: typer.Context,
+    quiet: QuietOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Print every recognized field, its effective value, and where the value came from.
+
+    Creates nothing. With no config file, every field prints its default or
+    not-configured state and the exit code is 0.
+    """
+    output = output_for(context, quiet=quiet, no_colour=no_colour)
+    directory, path = _resolve()
+    configuration = config_module.load_config(path)
+    present = "present" if files.path_exists(path) else "absent"
+    output.info(f"config file  {path.as_posix()}  {present}")
+
+    views = config_module.describe(configuration, directory)
+    key_width = max(len(view.key) for view in views)
+    state_width = max(len(view.state) for view in views)
+    for view in views:
+        output.info(f"  {view.key.ljust(key_width)}  {view.state.ljust(state_width)}  {view.value}")
+
+
+@app.command("set")
+def set_value(
+    context: typer.Context,
+    key: Annotated[str, typer.Argument(help="Field to set, dotted for a nested field.")],
+    value: Annotated[str, typer.Argument(help="New value.")],
+    quiet: QuietOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Validate a value against the field's schema, then write it.
+
+    A dotted key addresses a nested field. An invalid value, an unknown key, and
+    schema_version are each refused before the file is touched.
+    """
+    output = output_for(context, quiet=quiet, no_colour=no_colour)
+    _, path = _resolve()
+    configuration = config_module.load_config(path)
+    updated = config_module.apply_set(configuration, key, value)
+    if config_module.is_path_key(key):
+        _warn_windows_mount(output, value)
+    config_module.write_config(updated, path)
+    output.info(f"set {key}")
+
+
+@app.command("unset")
+def unset_value(
+    context: typer.Context,
+    key: Annotated[str, typer.Argument(help="Field to remove, dotted for a nested field.")],
+    quiet: QuietOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Remove an explicitly set field so it falls back to its default or to unset.
+
+    A field that is already absent is a no-op: the file is left unchanged and the
+    exit code is 0. An unknown key is refused.
+    """
+    output = output_for(context, quiet=quiet, no_colour=no_colour)
+    _, path = _resolve()
+    configuration = config_module.load_config(path)
+    if not config_module.is_set(configuration, key):
+        config_module.apply_unset(configuration, key)  # raises on an unknown key
+        output.info(f"{key} was not set")
+        return
+    config_module.write_config(config_module.apply_unset(configuration, key), path)
+    output.info(f"unset {key}")
+
+
+@app.command("edit")
+def edit(
+    context: typer.Context,
+    quiet: QuietOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Open the config in the configured editor, validating the result before installing it.
+
+    With no config file, the editor opens on the current defaults. An edit that
+    is not valid JSON or violates the schema is refused and the existing config
+    is left byte-identical.
+    """
+    output = output_for(context, quiet=quiet, no_colour=no_colour)
+    _, path = _resolve()
+    original = files.read_text(path) if files.path_exists(path) else config_module.render(
+        config_module.GlobalConfig()
+    )
+    edited = _edit_in_editor(original, path.name)
+    if edited is None or files.content_equal(edited, original):
+        output.info("config unchanged")
+        return
+    validated = config_module.load_config_text(edited, path)
+    config_module.write_config(validated, path)
+    output.info(f"wrote {path.as_posix()}")
+
+
+def _edit_in_editor(seed: str, name: str) -> str | None:
+    """Open a copy of ``seed`` in the editor and return the result, or None if unchanged."""
+    editor = os.environ.get("VISUAL") or os.environ.get("EDITOR")
+    if not editor:
+        raise AttentionError(
+            "no editor configured. Set VISUAL or EDITOR, or use 'config set' to change "
+            "one field at a time."
+        )
+    with tempfile.TemporaryDirectory() as scratch:
+        draft = Path(scratch) / name
+        files.write_text(draft, seed)
+        completed = subprocess.run([*shlex.split(editor), str(draft)], check=False)
+        if completed.returncode != 0:
+            raise AttentionError(f"editor exited with status {completed.returncode}")
+        result = files.read_text(draft)
+    return None if result == seed else result
+
+
+def _warn_windows_mount(output: OutputContext, raw_value: str) -> None:
+    """Warn when a path field is set to a location across the WSL and Windows boundary.
+
+    Checked against the value the user typed, not the stored expansion: on
+    Windows the expansion of a ``/mnt/`` path is not itself under ``/mnt/``.
+    """
+    info = platform_module.detect_platform()
+    if platform_module.is_on_windows_mount(Path(raw_value), info):
+        output.warn(
+            f"{raw_value} is on a Windows drive mounted under "
+            f"{platform_module.WINDOWS_MOUNT_PREFIX}, which crosses the WSL and Windows "
+            "filesystem boundary"
+        )

mdcompose/commands/convert_cmd.py

@@ -0,0 +1,299 @@
+"""The convert command: move unmanaged content between AGENTS.md and CLAUDE.md.
+
+`convert` moves the sections a user wrote into the wrong file: Claude-only prose
+that belongs in the shared AGENTS.md, or the reverse. It reads and writes only
+content outside managed blocks, so it never overlaps with `init`. The content is
+removed from the source once the target write succeeds, which is why every run
+shows a diff and asks before writing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from mdcompose.commands.import_cmd import _picker as _section_picker
+from mdcompose.core import composition, convert_ops, files, import_ops, init_ops, managed_block
+from mdcompose.core import config as config_module
+from mdcompose.core import manifest as manifest_module
+from mdcompose.core import platform as platform_module
+from mdcompose.core.config import Mode
+from mdcompose.core.exit_codes import AttentionError
+from mdcompose.core.output import OutputContext
+from mdcompose.core.sections import Section
+from mdcompose.prompts import is_interactive, output_for, prompt_choice
+from mdcompose.version import generated_by
+
+SourceArgument = Annotated[
+    str, typer.Argument(help="File to move content out of: AGENTS.md or CLAUDE.md.")
+]
+TargetArgument = Annotated[
+    str, typer.Argument(help="File to move content into: the other of the pair.")
+]
+SectionOption = Annotated[
+    list[str] | None,
+    typer.Option(
+        "--section", help="Move the section with this heading. Repeatable. Bypasses the picker."
+    ),
+]
+ModeOption = Annotated[
+    str | None,
+    typer.Option("--mode", help="How a new CLAUDE.md block relates to AGENTS.md: import or copy."),
+]
+YesOption = Annotated[
+    bool, typer.Option("--yes", "-y", help="Confirm the conversion without a prompt.")
+]
+QuietOption = Annotated[bool, typer.Option("--quiet", "-q", help="Suppress informational output.")]
+NoColourOption = Annotated[bool, typer.Option("--no-color", help="Never colourize output.")]
+
+
+def register(app: typer.Typer) -> None:
+    """Attach the command to an app under its real name."""
+    app.command("convert")(convert_files)
+
+
+def convert_files(
+    context: typer.Context,
+    source: SourceArgument,
+    target: TargetArgument,
+    section_names: SectionOption = None,
+    mode: ModeOption = None,
+    yes: YesOption = False,
+    quiet: QuietOption = False,
+    no_colour: NoColourOption = False,
+) -> None:
+    """Move chosen sections of one project file into the other, outside its block.
+
+    The moved content leaves the source and lands in the target's user-owned
+    region, so a later `init` neither overwrites nor removes it. --mode applies
+    only when the target is a CLAUDE.md with no managed block, since creating one
+    means deciding what it holds.
+    """
+    output = output_for(context, quiet=quiet, no_colour=no_colour)
+    info = platform_module.detect_platform()
+    source_path, target_path = _resolve_pair(source, target, info)
+    convert_ops.require_different(source_path, target_path)
+
+    project_root = Path.cwd()
+    requested_mode = _validated_mode(mode)
+    _reject_mode_where_it_cannot_apply(target_path, requested_mode)
+
+    source_text = files.read_text(source_path)
+    available = convert_ops.unmanaged_sections(source_text, source_path)
+    if _nothing_convertible(available):
+        output.info("nothing to convert, the source has no content outside a managed block")
+        return
+
+    names = tuple(section_names or ())
+    selected = import_ops.resolve_selection(
+        available, requested_headings=names or None, selector=_section_picker(output)
+    )
+    if not selected:
+        output.info("nothing selected, nothing converted")
+        return
+
+    new_block_mode = _new_block_mode(output, target_path, project_root, requested_mode)
+    target_text = files.read_text(target_path) if target_path.is_file() else ""
+    plan = convert_ops.plan_conversion(
+        source_path,
+        target_path,
+        moved=selected,
+        source_text=source_text,
+        target_text=target_text,
+        new_block_mode=new_block_mode,
+    )
+    diff = convert_ops.render_diff(plan)
+    if diff:
+        output.content(diff)
+    if not _confirmed(output, yes):
+        output.info("declined, nothing converted")
+        return
+
+    convert_ops.apply_conversion(plan)
+    if new_block_mode is not None:
+        _record_mode(project_root, target_path, new_block_mode)
+    plural = "" if len(selected) == 1 else "s"
+    output.info(
+        f"moved {len(selected)} section{plural} from {source_path.name} to {target_path.name}"
+    )
+
+
+def _validated_mode(raw: str | None) -> Mode | None:
+    if raw is None:
+        return None
+    if raw not in {composition.IMPORT, composition.COPY}:
+        raise AttentionError(
+            f"--mode must be '{composition.IMPORT}' or '{composition.COPY}', found '{raw}'"
+        )
+    return raw
+
+
+def _reject_mode_where_it_cannot_apply(target_path: Path, requested: Mode | None) -> None:
+    """--mode is rejected, not ignored, everywhere it cannot apply.
+
+    It applies only when creating a claude-managed block: a CLAUDE.md target with
+    no block yet. On AGENTS.md, or a CLAUDE.md that already has a block, supplying
+    it means the user expected something that will not happen.
+    """
+    if requested is None:
+        return
+    if target_path.name != platform_module.CLAUDE_MD_NAME:
+        raise AttentionError("--mode does not apply to AGENTS.md, which is always plain markdown")
+    if _has_claude_block(target_path):
+        raise AttentionError(
+            "CLAUDE.md already has a managed block; a mode change belongs to init, not convert"
+        )
+
+
+def _has_claude_block(target_path: Path) -> bool:
+    return (
+        target_path.is_file()
+        and managed_block.read_blocks(target_path).find(managed_block.CLAUDE_MANAGED_BLOCK)
+        is not None
+    )
+
+
+def _new_block_mode(
+    output: OutputContext,
+    target_path: Path,
+    project_root: Path,
+    requested: Mode | None,
+) -> Mode | None:
+    """The mode for a claude-managed block this run would create, or None.
+
+    Only a CLAUDE.md target with no block yet needs one. Precedence follows
+    `init`: an explicit flag, then the recorded project mode, then the configured
+    default, then a question, then a refusal naming the flag.
+    """
+    if target_path.name != platform_module.CLAUDE_MD_NAME or _has_claude_block(target_path):
+        return None
+
+    configuration = config_module.load_config(
+        config_module.config_path(platform_module.config_dir())
+    )
+    manifest = manifest_module.load_manifest(manifest_module.manifest_path(project_root))
+    recorded = None
+    entry = None if manifest is None else manifest.files.get(manifest_module.CLAUDE_MD_KEY)
+    if entry is not None:
+        recorded = entry.mode
+    return init_ops.resolve_mode(
+        requested=requested,
+        recorded=recorded,
+        default=configuration.default_mode,
+        ask=_mode_asker(output),
+    )
+
+
+def _mode_asker(output: OutputContext) -> Callable[[], Mode] | None:
+    if output.json_mode or not is_interactive():
+        return None
+
+    def ask() -> Mode:
+        answer = prompt_choice(
+            output,
+            "the target CLAUDE.md needs a managed block; how should it relate to AGENTS.md",
+            options=(composition.IMPORT, composition.COPY),
+            default=composition.IMPORT,
+            flag="--mode",
+        )
+        return answer  # type: ignore[return-value]
+
+    return ask
+
+
+def _record_mode(project_root: Path, target_path: Path, mode: Mode) -> None:
+    """Record the created block's mode, updating the manifest or writing a new one."""
+    block = managed_block.read_blocks(target_path).find(managed_block.CLAUDE_MANAGED_BLOCK)
+    block_hash = files.hash_content("" if block is None else block.content)
+    imports = "AGENTS.md" if mode == composition.IMPORT else None
+    entry = manifest_module.FileEntry(
+        path=platform_module.CLAUDE_MD_NAME,
+        mode=mode,
+        managed_block_hash=block_hash,
+        imports=imports,
+    )
+    path = manifest_module.manifest_path(project_root)
+    manifest = manifest_module.load_manifest(path)
+    if manifest is None:
+        built = manifest_module.build(
+            generated_by=generated_by(),
+            generated_at=_now(),
+            detected_stack=(),
+            snippets=(),
+            files_recorded={manifest_module.CLAUDE_MD_KEY: entry},
+            source=path,
+        )
+    else:
+        files_recorded = dict(manifest.files)
+        files_recorded[manifest_module.CLAUDE_MD_KEY] = entry
+        built = manifest_module.build(
+            generated_by=manifest.generated_by or "",
+            generated_at=manifest.generated_at or _now(),
+            detected_stack=manifest.detected_stack,
+            snippets=manifest.snippets_in_order(),
+            files_recorded=files_recorded,
+            source=path,
+        )
+    manifest_module.write_manifest(built, path)
+
+
+def _now() -> str:
+    from datetime import UTC, datetime
+
+    return datetime.now(UTC).replace(microsecond=0).isoformat()
+
+
+def _resolve_pair(
+    source: str, target: str, info: platform_module.PlatformInfo
+) -> tuple[Path, Path]:
+    """Resolve both arguments to the project's own AGENTS.md or CLAUDE.md."""
+    project = Path.cwd()
+    supported = {
+        files.normalized_path(project / platform_module.AGENTS_MD_NAME): project
+        / platform_module.AGENTS_MD_NAME,
+        files.normalized_path(project / platform_module.CLAUDE_MD_NAME): project
+        / platform_module.CLAUDE_MD_NAME,
+    }
+    source_path = _one_of(source, info, supported)
+    target_path = _one_of(target, info, supported)
+    if not source_path.is_file():
+        raise AttentionError(f"{source_path}: no such file to convert from")
+    return source_path, target_path
+
+
+def _one_of(
+    raw: str, info: platform_module.PlatformInfo, supported: dict[str, Path]
+) -> Path:
+    resolved = platform_module.resolve_path(raw, info)
+    match = supported.get(files.normalized_path(resolved.path))
+    if match is None:
+        raise AttentionError(
+            f"{resolved.path}: convert operates on this project's AGENTS.md and CLAUDE.md, "
+            "nothing else"
+        )
+    return match
+
+
+def _nothing_convertible(available: tuple[Section, ...]) -> bool:
+    if not available:
+        return True
+    return all(section.synthetic and not section.content.strip() for section in available)
+
+
+def _confirmed(output: OutputContext, yes: bool) -> bool:
+    """Confirm the conversion after the diff, refusing to guess with nobody to ask.
+
+    The diff is always printed first, by the caller, so a scripted run with --yes
+    still records what changed.
+    """
+    if yes:
+        return True
+    if output.json_mode or not is_interactive():
+        raise AttentionError(
+            "convert moves content between both files. Re-run with --yes to apply the "
+            "diff shown above."
+        )
+    return typer.confirm("apply this conversion?", default=False, err=True)