net-kingdom/local-identity/src/local_identity/cli.py

"""
local-identity CLI — entry point.

Commands:
  init [--force] [--username U] [--fullname N] [--email E]
                                   Derive primary user, generate test users,
                                   write store.  All three identity fields are
                                   resolved flag > config > system derivation.
  list                             List all users in the store.
  show <username>                  Display a user's YAML record.
  export [<username>]              Export a single user as Keycloak JSON.
  export --all [--realm R]         Bulk partial-import body (primary users only).
                                   Add --include-test to include generated users.

Environment:
  LOCAL_IDENTITY_HOME   Override the store directory (default: ~/.local-identity).
"""

import argparse
import json
import sys

from .gecos import current_username, get_gecos_fullname
from .user import UserRecord, make_test_user
from . import export as export_mod
from . import store


def _resolve_init_params(args: argparse.Namespace, config: dict) -> tuple[str, str, str]:
    """
    Resolve (username, fullname, email) for init from three sources in order:
      1. CLI flags (--username, --fullname, --email)
      2. Persisted config (~/.local-identity/config.yaml)
      3. System derivation ($USER / /etc/passwd GECOS) — username + fullname only
         Email has no system default; missing email falls through to prompt in cmd_init.
    """
    username: str = args.username or config.get("username") or current_username()
    fullname: str = args.fullname or config.get("fullname") or get_gecos_fullname(username)
    email: str = args.email or config.get("email") or ""
    return username, fullname, email


def cmd_init(args: argparse.Namespace) -> None:
    if store.store_exists() and not args.force:
        print(
            f"Store already exists at {store._store_dir()}. "
            "Use --force to reinitialise.",
            file=sys.stderr,
        )
        sys.exit(1)

    config = store.read_config() if store.store_exists() else {}
    username, fullname, email = _resolve_init_params(args, config)

    if not email:
        try:
            email = input(f"Email address for {username}: ").strip()
        except EOFError:
            email = ""
        if not email:
            print("Error: email address is required.", file=sys.stderr)
            sys.exit(1)

    store.init_dirs()
    config.update({"username": username, "fullname": fullname, "email": email})
    store.write_config(config)

    primary = UserRecord(username=username, fullname=fullname, email=email)
    store.write_user(primary)

    test1 = make_test_user(primary, 1)
    test2 = make_test_user(primary, 2)
    store.write_user(test1)
    store.write_user(test2)

    print(f"Initialised local-identity store at {store._store_dir()}")
    print(f"  Primary : {primary.username}  ({primary.fullname})  <{primary.email}>")
    print(f"  Test 1  : {test1.username}  <{test1.email}>")
    print(f"  Test 2  : {test2.username}  <{test2.email}>")


def cmd_list(args: argparse.Namespace) -> None:
    users = store.list_users()
    if not users:
        print("No users found. Run 'local-identity init' first.")
        return
    header = f"{'USERNAME':<20} {'FULLNAME':<30} {'EMAIL':<40} TYPE"
    print(header)
    print("-" * len(header))
    for u in users:
        utype = "test   " if u.generated else "primary"
        print(f"{u.username:<20} {u.fullname:<30} {u.email:<40} {utype}")


def cmd_export(args: argparse.Namespace) -> None:
    if args.username:
        # Single-user export
        try:
            user = store.read_user(args.username)
        except FileNotFoundError as exc:
            print(str(exc), file=sys.stderr)
            sys.exit(1)
        kc = export_mod.user_to_keycloak(user, realm=args.realm)
        print(json.dumps(kc, indent=2))
    else:
        # Bulk export
        all_users = store.list_users()
        if args.include_test:
            users = all_users
        else:
            users = [u for u in all_users if not u.generated]
            skipped = len(all_users) - len(users)
            if skipped:
                print(
                    f"Note: skipping {skipped} test user(s). "
                    "Use --include-test to export them.",
                    file=sys.stderr,
                )
        body = export_mod.bulk_export_body(
            users,
            realm=args.realm,
            if_resource_exists=args.if_resource_exists,
        )
        print(json.dumps(body, indent=2))


def cmd_show(args: argparse.Namespace) -> None:
    try:
        user = store.read_user(args.username)
    except FileNotFoundError as exc:
        print(str(exc), file=sys.stderr)
        sys.exit(1)
    print(user.to_yaml(), end="")


def main() -> None:
    parser = argparse.ArgumentParser(
        prog="local-identity",
        description="Zero-dependency bootstrap user store for net-kingdom environments.",
        epilog=(
            "Store location: ~/.local-identity  "
            "(override with LOCAL_IDENTITY_HOME)"
        ),
    )
    sub = parser.add_subparsers(dest="command", required=True)

    p_init = sub.add_parser(
        "init",
        help="Initialise store from Linux identity",
    )
    p_init.add_argument(
        "--force", action="store_true",
        help="Reinitialise even if the store already exists",
    )
    p_init.add_argument(
        "--username",
        help="Bootstrap username (default: $USER / $LOGNAME)",
    )
    p_init.add_argument(
        "--fullname",
        help="Full display name (default: /etc/passwd GECOS field)",
    )
    p_init.add_argument(
        "--email",
        help="Email address (default: interactive prompt)",
    )
    p_init.set_defaults(func=cmd_init)

    p_export = sub.add_parser(
        "export",
        help="Export user(s) as Keycloak-compatible JSON",
    )
    p_export.add_argument(
        "username", nargs="?",
        help="Export a single user (omit for bulk export)",
    )
    p_export.add_argument(
        "--realm", default="net-kingdom",
        help="Target Keycloak realm name (default: net-kingdom)",
    )
    p_export.add_argument(
        "--include-test", action="store_true",
        help="Include generated test users in bulk export",
    )
    p_export.add_argument(
        "--if-resource-exists", default="SKIP",
        choices=["SKIP", "OVERWRITE", "FAIL"],
        help="Conflict strategy for bulk import (default: SKIP)",
    )
    p_export.set_defaults(func=cmd_export)

    p_list = sub.add_parser("list", help="List all users in the store")
    p_list.set_defaults(func=cmd_list)

    p_show = sub.add_parser("show", help="Display a user record")
    p_show.add_argument("username", help="Username to display")
    p_show.set_defaults(func=cmd_show)

    args = parser.parse_args()
    args.func(args)


if __name__ == "__main__":
    main()