treeing 1.0.1__py3-none-any.whl

treeing/__init__.py

@@ -0,0 +1,7 @@
+"""treeing
+
+Top-level package entry point for the Treeing project.
+Exposes the version string and core submodules (core, cli, gui) for external imports.
+"""
+
+__version__ = "1.0.1"

treeing/_release_defaults.py

@@ -0,0 +1,3 @@
+# Default locale for this release tree.
+# Set during release preparation; do not edit in the release repository.
+DEFAULT_LOCALE = 'en'

treeing/cli/__init__.py

@@ -0,0 +1,5 @@
+"""treeing/cli
+
+Command-line interface layer.
+Provides argument parsing, the help system, path validation, confirmation prompts, result reporting and the main entry point.
+"""

treeing/cli/confirm.py

@@ -0,0 +1,197 @@
+"""
+treeing/cli/confirm.py
+
+Defines the pre-write confirmation logic: interactive --confirm, headless
+--yes, and the TREEING_YES environment variable. Provides
+`gate_before_write` as the unified entry point, handling TTY detection,
+confirmation prompts and mode resolution.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from ..config import get_string
+from .io import cli_err, cli_out, cli_warn
+
+ENV_ASSUME_YES = 'TREEING_YES'
+
+
+def assume_yes_from_env() -> bool:
+    """
+    Check whether the TREEING_YES environment variable is truthy (1/true/yes/on).
+
+    Used by gate_before_write to auto-confirm in non-interactive or CI
+    environments; the check is case-insensitive.
+    """
+    val = os.environ.get(ENV_ASSUME_YES, '').strip().lower()
+    if not val:
+        return False
+    return val in ('1', 'true', 'yes', 'on')
+
+
+def is_interactive_tty() -> bool:
+    """
+    Return whether the current session is an interactive TTY (both stdin and stderr are ttys).
+
+    Only treats the session as interactive when both are ttys; returns False
+    under pipes or redirection.
+    """
+    return bool(sys.stdin.isatty() and sys.stderr.isatty())
+
+
+def read_yes_no(*, default: bool = False) -> bool:
+    """
+    Read a y/n answer from the user; the default is controlled by `default`.
+
+    Windows uses msvcrt; Unix uses /dev/tty.
+    """
+    suffix = '[Y/n] ' if default else '[y/N] '
+    cli_err(get_string('cli_confirm_prompt', suffix=suffix), end='')
+    if sys.platform == 'win32':
+        return _read_yes_no_windows(default=default)
+    return _read_yes_no_unix(default=default)
+
+
+def _read_yes_no_windows(*, default: bool) -> bool:
+    """
+    Read a single y/n character on Windows (no Enter needed).
+
+    Accepts only y/n; Enter falls back to the default; other keys keep waiting.
+    """
+    import msvcrt
+
+    while True:
+        ch = msvcrt.getwch()
+        if ch in '\r\n':
+            cli_err('')
+            return default
+        lower = ch.lower()
+        if lower in ('y', 'n'):
+            cli_err(ch)
+            return lower == 'y'
+
+
+def _read_yes_no_unix(*, default: bool) -> bool:
+    """
+    Read a line on Unix (via /dev/tty to avoid pipe interference).
+
+    Returns the default on a blank line or read failure; only the first
+    character is consulted.
+    """
+    try:
+        with open('/dev/tty', encoding='utf-8', errors='replace') as tty:
+            line = tty.readline()
+    except OSError:
+        return default
+    answer = line.strip().lower()
+    if not answer:
+        return default
+    return answer in ('y', 'yes')
+
+
+def warn_confirm_ignored_on_dry_run() -> None:
+    """
+    Warn that --confirm is ignored under --dry-run.
+
+    Because dry-run writes nothing, asking the user to confirm is pointless.
+    """
+    cli_warn(get_string('cli_confirm_dry_run_ignored'))
+
+
+def audit_yes_confirmed(*, path: str, node_count: int, quiet: bool) -> None:
+    """
+    In headless mode (--yes / env), print a confirmation summary.
+
+    Even though the interactive prompt is skipped, the log still shows
+    "confirmed: N nodes will be created".
+    """
+    if quiet:
+        return
+    cli_out(get_string('cli_confirm_yes_audit', count=node_count, path=path))
+
+
+def prompt_generate_confirm(
+    *,
+    path: str,
+    node_count: int,
+    fail_on_conflict: bool,
+    warn_count: int,
+) -> bool:
+    """
+    In interactive mode, print the generation confirmation prompt and read the user's answer.
+
+    Returns True if the user confirms, False if cancelled.
+    """
+    cli_err(get_string(
+        'cli_msg_generate_confirm',
+        path=path,
+        count=node_count,
+        conflict_hint=get_string(
+            'cli_confirm_conflict_enabled' if fail_on_conflict
+            else 'cli_confirm_conflict_disabled',
+        ),
+        warn_hint=get_string(
+            'cli_confirm_warn_count', count=warn_count,
+        ) if warn_count else get_string('cli_confirm_no_warnings'),
+    ))
+    return read_yes_no(default=False)
+
+
+def resolve_confirm_mode(args) -> str | None:
+    """
+    Resolve the confirmation mode from the arguments: yes / env / interactive / None.
+
+    Priority: --yes > TREEING_YES > --confirm.
+    """
+    if getattr(args, 'yes', False):
+        return 'yes'
+    if assume_yes_from_env():
+        return 'env'
+    if getattr(args, 'confirm', False):
+        return 'interactive'
+    return None
+
+
+def gate_before_write(
+    args,
+    *,
+    path: str,
+    node_count: int,
+    fail_on_conflict: bool,
+    warn_count: int,
+) -> tuple[int | None, str | None]:
+    """
+    Pre-write confirmation entry point.
+
+    Returns (early_exit_code, confirm_mode). A non-None early_exit_code means
+    the run should exit early and skip writing.
+    """
+    if args.dry_run:
+        if args.confirm:
+            warn_confirm_ignored_on_dry_run()
+        return None, None
+
+    mode = resolve_confirm_mode(args)
+    if mode in ('yes', 'env'):
+        audit_yes_confirmed(path=path, node_count=node_count, quiet=args.quiet)
+        return None, mode
+
+    if not args.confirm:
+        return None, None
+
+    if not is_interactive_tty():
+        cli_err(get_string('cli_error_confirm_not_tty'))
+        return 1, None
+
+    if not prompt_generate_confirm(
+        path=path,
+        node_count=node_count,
+        fail_on_conflict=fail_on_conflict,
+        warn_count=warn_count,
+    ):
+        cli_err(get_string('cli_confirm_cancelled'))
+        return 0, None
+
+    return None, 'interactive'

treeing/cli/help_text.py

@@ -0,0 +1,311 @@
+"""
+treeing/cli/help_text.py
+
+Defines the layered CLI help system: short help, full help, topic help, and about.
+Provides `build_parser` and `dispatch_help_argv` as entry points.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable
+
+from .. import __version__
+from ..config import get_string, get_ui_string
+from .io import cli_out
+
+# topic name -> (title string key, body string key or None to use gui_tooltip_*)
+TOPIC_SPECS: dict[str, tuple[str, str | None, str | None]] = {
+    # name: (title_key, body_key, tooltip_fallback_key)
+    'input': ('cli_help_topic_title_input', 'cli_help_topic_input', 'gui_tooltip_input'),
+    'output': ('cli_help_topic_title_output', 'cli_help_topic_output', None),
+    'encoding': ('cli_help_topic_title_encoding', None, 'gui_tooltip_encoding'),
+    'parse': ('cli_help_topic_title_parse', 'cli_help_topic_parse', None),
+    'no-fix': ('cli_help_topic_title_no_fix', None, 'gui_tooltip_no_fix'),
+    'strict-dirs': ('cli_help_topic_title_strict_dirs', None, 'gui_tooltip_strict_dirs'),
+    'indent-unit': ('cli_help_topic_title_indent_unit', None, 'gui_tooltip_indent_unit'),
+    'dry-run': ('cli_help_topic_title_dry_run', 'cli_help_topic_dry_run', None),
+    'allow-nested': ('cli_help_topic_title_allow_nested', None, 'gui_tooltip_allow_nested'),
+    'fail-on-conflict': ('cli_help_topic_title_fail_on_conflict', None, 'gui_tooltip_fail_on_conflict'),
+    'rollback-on-error': ('cli_help_topic_title_rollback_on_error', 'cli_help_topic_rollback_on_error', None),
+    'format': ('cli_help_topic_title_format', 'cli_help_topic_format', 'gui_tooltip_preview'),
+    'json': ('cli_help_topic_title_json', 'cli_help_topic_json', None),
+    'automation': ('cli_help_topic_title_automation', 'cli_help_topic_automation', None),
+    'windows': ('cli_help_topic_title_windows', 'cli_help_topic_windows', None),
+    'warnings': ('cli_help_topic_title_warnings', None, 'gui_tooltip_view_warnings'),
+    'strict': ('cli_help_topic_title_strict', 'cli_help_topic_strict', None),
+    'confirm': ('cli_help_topic_title_confirm', 'cli_help_topic_confirm', None),
+    'about': ('cli_help_topic_title_about', None, None),
+}
+
+# P3: topic index groups (section_key, [topic names])
+TOPIC_INDEX: list[tuple[str, list[str]]] = [
+    ('cli_help_topics_section_input', ['input', 'output', 'encoding']),
+    ('cli_help_topics_section_parse', ['parse', 'no-fix', 'strict-dirs', 'indent-unit']),
+    ('cli_help_topics_section_generate', [
+        'dry-run', 'allow-nested', 'fail-on-conflict', 'rollback-on-error',
+        'format', 'strict', 'confirm',
+    ]),
+    ('cli_help_topics_section_automation', ['json', 'automation', 'warnings']),
+    ('cli_help_topics_section_platform', ['windows']),
+    ('cli_help_topics_section_meta', ['about']),
+]
+
+TOPIC_ALIASES: dict[str, str] = {
+    'i': 'input',
+    'o': 'output',
+    'p': 'paste',
+    'paste': 'input',
+    'nested': 'allow-nested',
+    'conflict': 'fail-on-conflict',
+    'rollback': 'rollback-on-error',
+    'yes': 'confirm',
+    'y': 'confirm',
+    'topics': 'topics',
+}
+
+
+def _body_for_topic(name: str) -> str:
+    """
+    Fetch the body text for a help topic.
+
+    Prefer the dedicated body_key; otherwise fall back to the gui_tooltip_*
+    text. The `about` topic is special-cased and prints the about text.
+    """
+    if name == 'about':
+        return get_ui_string('gui_msg_about', version=__version__)
+    spec = TOPIC_SPECS.get(name)
+    if not spec:
+        return ''
+    _, body_key, tooltip_key = spec
+    if body_key:
+        text = get_string(body_key)
+        if text != body_key:
+            return text
+    if tooltip_key:
+        return get_string(tooltip_key)
+    return ''
+
+
+def print_about() -> None:
+    """Print the --about content (shares the same text as the GUI about dialogue)."""
+    cli_out(get_ui_string('gui_msg_about', version=__version__))
+
+
+def print_topics_index() -> None:
+    """Print the topic index for `treeing help`, grouped by section."""
+    cli_out(get_ui_string('cli_help_topics_intro'))
+    cli_out('')
+    for section_key, names in TOPIC_INDEX:
+        cli_out(get_string(section_key))
+        for name in names:
+            title_key = TOPIC_SPECS[name][0]
+            cli_out(get_string('cli_help_topics_item', topic=name, title=get_string(title_key)))
+        cli_out('')
+    cli_out(get_ui_string('cli_help_topics_footer'))
+
+
+def print_topic(name: str) -> int:
+    """
+    Print detailed help for a single topic.
+
+    Supports aliases (e.g. nested -> allow-nested); an unknown topic prints an
+    error first, then lists the available topics.
+    """
+    canonical = TOPIC_ALIASES.get(name, name)
+    if canonical == 'topics':
+        print_topics_index()
+        return 0
+    if canonical not in TOPIC_SPECS:
+        cli_out(get_string('cli_help_unknown_topic', topic=name))
+        cli_out('')
+        print_topics_index()
+        return 1
+    title = get_string(TOPIC_SPECS[canonical][0])
+    body = _body_for_topic(canonical)
+    cli_out(title)
+    cli_out('')
+    cli_out(body)
+    cli_out('')
+    cli_out(get_ui_string('cli_help_topic_see_also'))
+    return 0
+
+
+def dispatch_help_argv(argv: list[str]) -> int | None:
+    """
+    Handle help / --about / --help-full requests before formal argument parsing.
+
+    Returns an exit code when handled; returns None when this is not a help
+    request and normal flow should continue.
+    """
+    if len(argv) == 2 and argv[1] == '--about':
+        print_about()
+        return 0
+    if len(argv) == 2 and argv[1] == '--help-full':
+        print_help_full()
+        return 0
+    try:
+        idx = argv.index('help')
+    except ValueError:
+        return None
+    if idx != 1:
+        return None
+    topic = argv[idx + 1] if len(argv) > idx + 1 else None
+    if topic is None:
+        print_topics_index()
+        return 0
+    return print_topic(topic)
+
+
+def _add_group(parser: argparse.ArgumentParser, title_key: str, add_fn: Callable) -> None:
+    """Add an argument group to the parser; the group title comes from the string resources."""
+    group = parser.add_argument_group(get_string(title_key))
+    add_fn(group)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build and return the CLI argument parser; all text comes from strings.json."""
+    parser = argparse.ArgumentParser(
+        description=get_string('cli_help_desc'),
+        epilog=get_ui_string('cli_help_epilog'),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        '--version', action='version',
+        version=get_string('cli_version_fmt', version=__version__),
+    )
+    parser.add_argument(
+        '--about', action='store_true',
+        help=get_string('cli_about_flag'),
+    )
+    parser.add_argument(
+        '--help-full', action='store_true',
+        help=get_string('cli_help_full_flag'),
+    )
+
+    def add_input(g):
+        """Register input-related arguments: -i/--input, -p/--paste, --encoding."""
+        g.add_argument('-i', '--input', help=get_string('cli_input_file'))
+        g.add_argument('-p', '--paste', action='store_true', help=get_string('cli_paste'))
+        g.add_argument(
+            '--encoding', default='utf-8', metavar='ENC',
+            help=get_string('cli_encoding'),
+        )
+
+    def add_output(g):
+        """Register output-related arguments: -o/--output, --use-settings, --check-writable."""
+        g.add_argument('-o', '--output', default=None, help=get_string('cli_output_dir'))
+        g.add_argument(
+            '--use-settings', action='store_true',
+            help=get_string('cli_use_settings'),
+        )
+        g.add_argument(
+            '--check-writable', action='store_true',
+            help=get_string('cli_check_writable'),
+        )
+
+    def add_parse(g):
+        """Register parse-related arguments: --no-fix, --strict-dirs, --indent-unit."""
+        g.add_argument('--no-fix', action='store_true', help=get_string('cli_no_fix'))
+        g.add_argument(
+            '--strict-dirs', action='store_true',
+            help=get_string('cli_strict_dirs'),
+        )
+        g.add_argument(
+            '--indent-unit', type=int, default=None, metavar='N',
+            help=get_string('cli_indent_unit'),
+        )
+
+    def add_generate(g):
+        """Register generation-related arguments: dry-run, nested names, conflict handling, confirmation mode, etc."""
+        g.add_argument('--dry-run', action='store_true', help=get_string('cli_dry_run'))
+        g.add_argument(
+            '--allow-nested-names', action='store_true',
+            help=get_string('cli_allow_nested_names'),
+        )
+        g.add_argument(
+            '--fail-on-conflict', action='store_true',
+            help=get_string('cli_fail_on_conflict'),
+        )
+        g.add_argument(
+            '--fail-on-duplicate', action='store_true',
+            help=get_string('cli_fail_on_duplicate'),
+        )
+        g.add_argument(
+            '--strict', action='store_true',
+            help=get_string('cli_strict'),
+        )
+        g.add_argument(
+            '--rollback-on-error', action='store_true',
+            help=get_string('cli_rollback_on_error'),
+        )
+        confirm = g.add_mutually_exclusive_group()
+        confirm.add_argument(
+            '--confirm', action='store_true',
+            help=get_string('cli_confirm'),
+        )
+        confirm.add_argument(
+            '-y', '--yes', action='store_true',
+            help=get_string('cli_yes'),
+        )
+
+    def add_automation(g):
+        """Register automation-related arguments: --json, --quiet, --warn-exit-code, --warnings-file, --format, warning cap."""
+        g.add_argument('--json', action='store_true', help=get_string('cli_json'))
+        g.add_argument('--quiet', action='store_true', help=get_string('cli_quiet'))
+        g.add_argument(
+            '--warn-exit-code', action='store_true',
+            help=get_string('cli_warn_exit_code'),
+        )
+        g.add_argument(
+            '--warnings-file', metavar='PATH',
+            help=get_string('cli_warnings_file'),
+        )
+        g.add_argument(
+            '--format', choices=['text', 'tree'], default='text',
+            help=get_string('cli_format'),
+        )
+        warn_limit = g.add_mutually_exclusive_group()
+        warn_limit.add_argument(
+            '--no-warn-limit', action='store_true',
+            help=get_string('cli_no_warn_limit'),
+        )
+        warn_limit.add_argument(
+            '--warn-limit', type=int, default=None, metavar='N',
+            help=get_string('cli_warn_limit'),
+        )
+
+    _add_group(parser, 'cli_help_group_input', add_input)
+    _add_group(parser, 'cli_help_group_output', add_output)
+    _add_group(parser, 'cli_help_group_parse', add_parse)
+    _add_group(parser, 'cli_help_group_generate', add_generate)
+    _add_group(parser, 'cli_help_group_automation', add_automation)
+    return parser
+
+
+def print_help_full() -> None:
+    """Full help: short help plus an expanded description for each option."""
+    parser = build_parser()
+    parser.print_help()
+    cli_out('')
+    cli_out(get_string('cli_help_full_header'))
+    cli_out('')
+    sections = [
+        ('cli_help_full_section_input', ['input', 'output', 'encoding']),
+        ('cli_help_full_section_parse', ['parse', 'no-fix', 'strict-dirs', 'indent-unit']),
+        ('cli_help_full_section_generate', [
+            'dry-run', 'allow-nested', 'fail-on-conflict', 'rollback-on-error', 'format', 'strict', 'confirm',
+        ]),
+        ('cli_help_full_section_automation', ['json', 'automation', 'warnings']),
+        ('cli_help_full_section_platform', ['windows']),
+    ]
+    for section_key, topics in sections:
+        cli_out(get_string(section_key))
+        for topic in topics:
+            title = get_string(TOPIC_SPECS[topic][0])
+            body = _body_for_topic(topic)
+            cli_out(get_string('cli_help_full_topic_line', topic=topic, title=title))
+            for line in body.splitlines():
+                cli_out(f'  {line}')
+            cli_out('')
+    cli_out(get_ui_string('cli_help_topics_footer'))

treeing/cli/io.py

@@ -0,0 +1,72 @@
+"""
+treeing/cli/io.py
+
+Defines CLI standard-stream configuration and safe writing.
+Provides `configure_stdio` (UTF-8 + replace) and the cli_out / cli_warn /
+cli_err helpers, so Windows legacy-codepage consoles do not crash on output.
+"""
+
+import sys
+
+_configured = False
+
+
+def configure_stdio() -> None:
+    """
+    At startup, set stdout/stderr to UTF-8 + replace mode.
+
+    Runs once; later calls return immediately.
+    """
+    global _configured
+    if _configured:
+        return
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, 'reconfigure'):
+            try:
+                stream.reconfigure(encoding='utf-8', errors='replace')
+            except (OSError, ValueError, AttributeError):
+                pass
+    _configured = True
+
+
+def _safe_write(stream, text: str, *, end: str = '\n') -> None:
+    """
+    Safe write: try a direct write first, then fall back to buffer + replace encoding.
+    """
+    msg = text + end
+    try:
+        stream.write(msg)
+        stream.flush()
+    except UnicodeEncodeError:
+        encoding = getattr(stream, 'encoding', None) or 'utf-8'
+        if hasattr(stream, 'buffer'):
+            stream.buffer.write(msg.encode(encoding, errors='replace'))
+            stream.buffer.flush()
+        else:
+            raise
+
+
+def cli_out(text: str, *, end: str = '\n') -> None:
+    """
+    Success summaries and [WARN] warnings go to stdout.
+
+    Easier for pipes / agents to parse, and friendlier under PowerShell.
+    """
+    _safe_write(sys.stdout, text, end=end)
+
+
+def cli_warn(text: str, *, end: str = '\n') -> None:
+    """
+    Warning prompts go to stdout (same stream as cli_out).
+
+    MING routes warnings through stdout so agents / scripts get stable
+    structured output via a pipe, leaving genuine errors for stderr.
+    """
+    _safe_write(sys.stdout, text, end=end)
+
+
+def cli_err(text: str, *, end: str = '\n') -> None:
+    """
+    Errors and interactive prompts go to stderr ([ERR] and confirm prompts).
+    """
+    _safe_write(sys.stderr, text, end=end)