redmine-worklog 0.1.0__py3-none-any.whl

redmine_worklog/__init__.py

@@ -0,0 +1,3 @@
+"""redmine_worklog — a tiny retro CLI to log daily tasks to Redmine."""
+
+__version__ = "0.1.0"

redmine_worklog/cli.py

@@ -0,0 +1,405 @@
+"""
+cli.py — the `rmlog` command. Retro CLI to log tasks to Redmine.
+
+First run  -> setup wizard (name, Redmine URL, API token, project).
+After that -> greets by first name and logs tasks in the strict format.
+"""
+
+import sys
+
+import requests
+
+from . import __version__, csv_backfill, engine, retro, userconfig
+from . import worklog_parser as wl
+
+
+def _verify_token(url, api_key):
+    """Return (user_dict, error). Confirms the token works."""
+    try:
+        client = engine.RedmineClient(url, api_key)
+        return client.current_user(), None
+    except requests.HTTPError as e:
+        code = e.response.status_code if e.response is not None else "?"
+        if str(code) == "401":
+            return None, "Invalid API token (401 Unauthorized)."
+        return None, f"Redmine returned HTTP {code}."
+    except requests.RequestException as e:
+        return None, f"Could not reach Redmine: {e}"
+
+
+def run_setup():
+    print(retro.banner())
+    print(retro.box([
+        retro.c("Welcome, player one!", retro.BOLD + retro.WHITE),
+        "",
+        "Let's set up your worklog cartridge.",
+        "You'll need your Redmine URL and API access key",
+        "(Redmine -> My account -> API access key).",
+    ], color=retro.MAGENTA, title="NEW GAME"))
+    print()
+
+    cfg = userconfig.load()
+
+    name = retro.prompt("Your name >").strip()
+    while not name:
+        name = retro.prompt("Please enter your name >").strip()
+
+    url = retro.prompt("Redmine URL >").strip().rstrip("/")
+    while not url:
+        url = retro.prompt("Redmine URL (e.g. http://redmine.local) >").strip().rstrip("/")
+
+    # Loop until the token verifies.
+    while True:
+        token = retro.prompt("API access key >").strip()
+        if not token:
+            continue
+        retro.typewriter("  ...connecting to Redmine...", retro.DIM + retro.CYAN)
+        user, err = _verify_token(url, token)
+        if err:
+            retro.typewriter("  X  " + err, retro.RED)
+            retry = retro.prompt("Try again? (y/n) >").strip().lower()
+            if retry not in ("y", "yes", ""):
+                retro.typewriter("Setup cancelled.", retro.YELLOW)
+                sys.exit(1)
+            # allow re-entering URL too
+            new_url = retro.prompt(f"Redmine URL [{url}] >").strip().rstrip("/")
+            if new_url:
+                url = new_url
+            continue
+        redmine_name = f"{user.get('firstname','')} {user.get('lastname','')}".strip()
+        retro.typewriter(f"  OK  Connected as {redmine_name} "
+                         f"(id {user.get('id')}).", retro.GREEN)
+        break
+
+    project = retro.prompt("Default project name/identifier >").strip()
+    while not project:
+        project = retro.prompt("Default project (required) >").strip()
+
+    tracker = retro.prompt("Tracker [Tasks] >").strip() or "Tasks"
+
+    cfg.update({
+        "name": name,
+        "url": url,
+        "api_key": token,
+        "project": project,
+        "tracker": tracker,
+    })
+    userconfig.save(cfg)
+
+    print()
+    print(retro.box([
+        retro.c("Saved! Your progress is stored at:", retro.GREEN),
+        retro.c(userconfig.CONFIG_PATH, retro.DIM + retro.WHITE),
+        "",
+        "Run  rmlog  again any time to log tasks.",
+    ], color=retro.GREEN, title="SAVE COMPLETE"))
+    print()
+    return cfg
+
+
+def _print_help(first):
+    print(retro.box([
+        retro.c(f"How to play, {first}:", retro.BOLD + retro.WHITE),
+        "",
+        "Type ONE task per line, like:",
+        retro.c("  upload module discovery 3 hr today", retro.YELLOW),
+        retro.c("  fix login bug 2h yesterday", retro.YELLOW),
+        retro.c("  sprint planning 1.5 hr 15-09-2026 16-09-2026", retro.YELLOW),
+        "",
+        "dates: today | yesterday | dd-mm-yyyy",
+        "end date is optional (defaults to start date).",
+        "",
+        "Commands:",
+        retro.c("  csv", retro.YELLOW) + "             bulk upload from a CSV",
+        retro.c("  change project", retro.YELLOW) + "  switch default project",
+        retro.c("  change user", retro.YELLOW) + "     switch saved account",
+        retro.c("  help", retro.YELLOW) + "            show this screen",
+        retro.c("  quit", retro.YELLOW) + "            exit",
+        "",
+        retro.c("Tip: run  rmlog --plain  on old terminals.",
+                retro.DIM + retro.WHITE),
+    ], color=retro.CYAN, title="INSTRUCTIONS"))
+
+
+def switch_user():
+    """
+    Let the user pick a saved profile (no token re-entry) or add a new one.
+    Returns the newly-active config dict, or None if unchanged/cancelled.
+    """
+    profiles = userconfig.list_profiles()
+    active = userconfig.active_key()
+
+    lines = [retro.c("Saved accounts:", retro.BOLD + retro.WHITE)]
+    for i, (key, display) in enumerate(profiles, 1):
+        mark = retro.c("  (active)", retro.GREEN) if key == active else ""
+        lines.append(f"  {i}. {display}{mark}")
+    lines.append("")
+    lines.append(retro.c("  N. add a new account", retro.YELLOW))
+    print(retro.box(lines, color=retro.MAGENTA, title="CHANGE  USER"))
+
+    choice = retro.prompt("Pick a number, 'N' for new, or 'cancel' >").strip().lower()
+    if not choice or choice == "cancel":
+        retro.typewriter("  User unchanged.", retro.YELLOW)
+        return None
+    if choice in ("n", "new"):
+        return run_setup()  # adds/updates a profile and makes it active
+    if choice.isdigit():
+        idx = int(choice)
+        if 1 <= idx <= len(profiles):
+            key = profiles[idx - 1][0]
+            cfg = userconfig.switch_to(key)
+            if cfg:
+                return cfg
+    retro.typewriter("  Not a valid choice. User unchanged.", retro.YELLOW)
+    return None
+
+
+def change_project(cfg, client):
+    """Prompt for a new default project, verify it exists, save. Returns bool."""
+    print(retro.box([
+        retro.c(f"Current project: {cfg.get('project','(none)')}", retro.WHITE),
+        "",
+        "Enter a new project name or identifier.",
+    ], color=retro.MAGENTA, title="CHANGE  PROJECT"))
+    new_project = retro.prompt("New project (or 'cancel') >").strip()
+    if not new_project or new_project.lower() == "cancel":
+        retro.typewriter("  Project unchanged.", retro.YELLOW)
+        return False
+    retro.typewriter("  ...checking project in Redmine...", retro.DIM + retro.CYAN)
+    try:
+        client.project_id(new_project)  # raises if not found
+    except Exception as e:  # noqa: BLE001
+        retro.typewriter("  X  " + str(e), retro.RED)
+        return False
+    cfg["project"] = new_project
+    userconfig.save(cfg)
+    retro.typewriter(f"  OK  Default project is now '{new_project}'.", retro.GREEN)
+    return True
+
+
+def run_csv_backfill(cfg, client, ids, holidays, first):
+    """Interactive CSV backfill. Returns nothing; posts on confirm."""
+    print(retro.box(
+        [retro.c(ln, retro.WHITE) for ln in csv_backfill.INSTRUCTIONS],
+        color=retro.CYAN, title="CSV  BACKFILL"))
+
+    # Sample shown as a column | value table (generic, easy to read).
+    req = {"subject", "hours", "date"}
+    col_w = max(len(c) for c, _ in csv_backfill.SAMPLE_ROW)
+    sample_lines = [
+        retro.c(f"{'COLUMN':<{col_w}}", retro.BOLD + retro.CYAN)
+        + "  |  " + retro.c("EXAMPLE VALUE", retro.BOLD + retro.CYAN),
+        retro.c("-" * col_w + "--+--" + "-" * 28, retro.DIM + retro.WHITE),
+    ]
+    for col, val in csv_backfill.SAMPLE_ROW:
+        tag = retro.c(" *", retro.YELLOW) if col in req else "  "
+        sample_lines.append(
+            retro.c(f"{col:<{col_w}}", retro.WHITE) + "  |  "
+            + retro.c(val, retro.GREEN) + tag)
+    sample_lines.append("")
+    sample_lines.append(retro.c(" * = required in every row", retro.YELLOW))
+    print(retro.box(sample_lines, color=retro.GREEN, title="SAMPLE  ROW"))
+
+    path = retro.prompt("\nPath to your CSV (or 'cancel') >").strip().strip('"')
+    if not path or path.lower() == "cancel":
+        retro.typewriter("  CSV upload cancelled.", retro.YELLOW)
+        return
+
+    entries, errors = csv_backfill.read_and_validate(path, cfg["defaults"])
+
+    # File/format-level problems (no entries at all)
+    if not entries and errors:
+        retro.typewriter("  X  Could not use this CSV:", retro.RED)
+        for e in errors:
+            retro.typewriter("     " + e, retro.YELLOW)
+        return
+
+    # Apply org rules across all rows. Hard errors block; warnings need override.
+    rule_errors, warnings = engine.validate_entries(
+        entries, cfg["rules"], holidays, client, ids["user_id"])
+    all_errors = errors + rule_errors
+    if all_errors:
+        retro.typewriter(f"  Found {len(all_errors)} issue(s). "
+                         f"Nothing uploaded. Fix and try again:", retro.RED)
+        for e in all_errors:
+            retro.typewriter("     - " + e, retro.YELLOW)
+        return
+
+    # Summary + confirm
+    total_hours = sum(float(e["hours"]) for e in entries)
+    days = sorted({str(e["date"]) for e in entries})
+    print(retro.box([
+        retro.c(f"Rows OK : {len(entries)} task(s)", retro.WHITE),
+        retro.c(f"Hours   : {total_hours}h total", retro.WHITE),
+        retro.c(f"Dates   : {days[0]}  ->  {days[-1]}", retro.WHITE),
+    ], color=retro.YELLOW, title="CSV  VALIDATED"))
+
+    if warnings:
+        warn_lines = [retro.c("Over the daily hours limit:", retro.BOLD + retro.YELLOW)]
+        warn_lines += [retro.c("  " + w, retro.WHITE) for w in warnings]
+        print(retro.box(warn_lines, color=retro.RED, title="!  WARNING"))
+        ow = retro.prompt("Log more than the limit anyway? (yes/no) >").strip().lower()
+        if ow not in ("yes", "y"):
+            retro.typewriter("  Cancelled. Nothing was uploaded.", retro.YELLOW)
+            return
+
+    ans = retro.prompt(f"Upload all {len(entries)} tasks to Redmine? "
+                       f"(yes/no) >").strip().lower()
+    if ans not in ("yes", "y"):
+        retro.typewriter("  Cancelled. Nothing was uploaded.", retro.YELLOW)
+        return
+
+    ok_count, fail_count = 0, 0
+    for e in entries:
+        ok, res = engine.post_entry(client, ids, e, cfg["defaults"])
+        if ok:
+            ok_count += 1
+            retro.typewriter(f"  {retro.c('★', retro.GREEN)} {e['subject']}: {res}",
+                             retro.WHITE)
+        else:
+            fail_count += 1
+            retro.typewriter(f"  {retro.c('✖', retro.RED)} {e['subject']}: {res}",
+                             retro.WHITE)
+    print(retro.box([
+        retro.c(f"Uploaded: {ok_count}", retro.GREEN),
+        retro.c(f"Failed  : {fail_count}",
+                retro.RED if fail_count else retro.DIM + retro.WHITE),
+    ], color=retro.GREEN, title="BACKFILL  COMPLETE"))
+
+
+def _connect(cfg):
+    """Create client + resolve ids. Exits with a friendly message on failure."""
+    client = engine.RedmineClient(cfg["url"], cfg["api_key"])
+    try:
+        ids = engine.resolve_ids(client, cfg)
+    except Exception as e:  # noqa: BLE001
+        retro.typewriter(f"Could not connect: {e}", retro.RED)
+        retro.typewriter("Run  rmlog --setup  to fix your settings.", retro.YELLOW)
+        sys.exit(1)
+    return client, ids
+
+
+def run_chat(cfg):
+    client, ids = _connect(cfg)
+    holidays = engine.parse_holidays(cfg.get("holidays", []))
+    first = userconfig.first_name(cfg["name"]) or "player"
+
+    print(retro.banner())
+    print(retro.box([
+        retro.c(f"Player 1: {first}", retro.BOLD + retro.WHITE),
+        retro.c(f"Redmine : {cfg['url']}", retro.DIM + retro.WHITE),
+        retro.c(f"Project : {cfg['project']}", retro.DIM + retro.WHITE),
+        "",
+        f"Ready when you are, {first}.",
+        "Type a task, 'csv' to bulk upload, or 'help'.",
+    ], color=retro.GREEN, title=f"PRESS START  -  v{__version__}"))
+
+    pending = None
+    while True:
+        try:
+            msg = retro.prompt(f"\n{retro.c('◄' + first + '►', retro.MAGENTA)} >").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+
+        if not msg:
+            continue
+        low = msg.lower()
+        if low in ("quit", "exit", "q"):
+            retro.typewriter(f"GAME OVER. See you, {first}!", retro.YELLOW)
+            break
+        if low in ("help", "?"):
+            _print_help(first)
+            continue
+        if low in ("csv", "upload", "backfill"):
+            run_csv_backfill(cfg, client, ids, holidays, first)
+            pending = None
+            continue
+        if low in ("change user", "switch user", "logout"):
+            new_cfg = switch_user()
+            if new_cfg:
+                cfg = new_cfg
+                client, ids = _connect(cfg)
+                first = userconfig.first_name(cfg["name"]) or "player"
+                holidays = engine.parse_holidays(cfg.get("holidays", []))
+                retro.typewriter(f"  Switched. Welcome, {first}!", retro.GREEN)
+            pending = None
+            continue
+        if low in ("change project", "switch project"):
+            if change_project(cfg, client):
+                ids = engine.resolve_ids(client, cfg)  # re-resolve for new project
+            pending = None
+            continue
+
+        # confirmation of a pending task
+        if pending is not None:
+            if low in ("yes", "y", "ok", "confirm"):
+                ok, res = engine.post_entry(client, ids, pending, cfg["defaults"])
+                mark = retro.c("★ WIN", retro.GREEN) if ok else retro.c("✖ MISS", retro.RED)
+                print(f"  {mark}  {res}")
+            else:
+                retro.typewriter("  Cancelled. Nothing was logged.", retro.YELLOW)
+            pending = None
+            continue
+
+        entries, err = wl.parse(msg)
+        if err:
+            retro.typewriter("  ! " + err.splitlines()[0], retro.RED)
+            for extra in err.splitlines()[1:]:
+                retro.typewriter("    " + extra, retro.DIM + retro.WHITE)
+            continue
+
+        verrs, warnings = engine.validate_entries(
+            entries, cfg["rules"], holidays, client, ids["user_id"])
+        if verrs:
+            retro.typewriter("  BLOCKED by the rules:", retro.RED)
+            for v in verrs:
+                retro.typewriter("    - " + v, retro.YELLOW)
+            continue
+
+        # show preview
+        d = engine.describe_entry(entries[0], cfg["defaults"])
+        lines = [retro.c(f"{k:<9}", retro.CYAN) + ": " + str(v)
+                 for k, v in d.items()]
+        print(retro.box(lines, color=retro.YELLOW, title="CONFIRM  TASK"))
+
+        # Over the daily limit -> warn and require an explicit override first.
+        if warnings:
+            warn_lines = [retro.c("Over the daily hours limit:",
+                                  retro.BOLD + retro.YELLOW)]
+            warn_lines += [retro.c("  " + w, retro.WHITE) for w in warnings]
+            print(retro.box(warn_lines, color=retro.RED, title="!  WARNING"))
+            ow = retro.prompt("Log more than the limit anyway? (yes/no) >").strip().lower()
+            if ow not in ("yes", "y"):
+                retro.typewriter("  Cancelled. Nothing was logged.", retro.YELLOW)
+                pending = None
+                continue
+
+        retro.typewriter("  Push to Redmine? type 'yes' to confirm.",
+                         retro.BOLD + retro.WHITE)
+        pending = entries[0]
+
+
+def main():
+    args = sys.argv[1:]
+    if "--version" in args:
+        print(f"redmine-worklog {__version__}")
+        return
+
+    # Plain mode for old terminals / piping: --plain flag or NO_COLOR env var.
+    import os as _os
+    if "--plain" in args or _os.environ.get("NO_COLOR"):
+        retro.set_plain(True)
+
+    if "--setup" in args or not userconfig.exists():
+        cfg = run_setup()
+    else:
+        cfg = userconfig.load()
+        # guard against half-set config
+        if not (cfg.get("url") and cfg.get("api_key") and cfg.get("project")):
+            cfg = run_setup()
+    run_chat(cfg)
+
+
+if __name__ == "__main__":
+    main()

redmine_worklog/csv_backfill.py

@@ -0,0 +1,173 @@
+"""
+csv_backfill.py — read and validate a CSV of tasks for bulk backfill.
+
+Expected header (order doesn't matter; case-insensitive):
+    subject,description,priority,status,start_date,due_date,
+    estimated_hours,date,hours,activity,comment
+
+Required per row: subject, hours, date.
+Everything else is optional and falls back to the user's defaults.
+
+Dates accepted: YYYY-MM-DD or dd-mm-yyyy or dd/mm/yyyy.
+"""
+
+import csv
+import datetime as dt
+import os
+
+REQUIRED = ["subject", "hours", "date"]
+KNOWN_COLUMNS = [
+    "subject", "description", "priority", "status", "start_date",
+    "due_date", "estimated_hours", "date", "hours", "activity", "comment",
+]
+
+# Raw CSV template (written to file when the user asks for a sample).
+TEMPLATE = (
+    "subject,description,priority,status,start_date,due_date,"
+    "estimated_hours,date,hours,activity,comment\n"
+    "Task title,short description of the work,Normal,"
+    "Closed,2026-09-17,2026-09-18,8,2026-09-18,4,Development,"
+    "worked on the task\n"
+)
+
+# A generic sample shown as a vertical table (column -> value), which reads
+# far better in a terminal than a single very wide CSV line.
+SAMPLE_ROW = [
+    ("subject", "Task title"),
+    ("description", "short description of the work"),
+    ("priority", "Normal"),
+    ("status", "Closed"),
+    ("start_date", "2026-09-17"),
+    ("due_date", "2026-09-18"),
+    ("estimated_hours", "8"),
+    ("date", "2026-09-18"),
+    ("hours", "4"),
+    ("activity", "Development"),
+    ("comment", "worked on the task"),
+]
+
+INSTRUCTIONS = [
+    "CSV backfill lets you upload many tasks at once (e.g. last 3 months).",
+    "",
+    "Header row (exactly these column names):",
+    "  subject,description,priority,status,start_date,due_date,",
+    "  estimated_hours,date,hours,activity,comment",
+    "",
+    "Required in every row : subject, hours, date",
+    "Optional (use default): description, priority, status, start_date,",
+    "                        due_date, estimated_hours, activity, comment",
+    "",
+    "Dates: YYYY-MM-DD  or  dd-mm-yyyy",
+    "One row = one task. Rules (9h/day, weekends, holidays) still apply.",
+]
+
+
+def _parse_date(value):
+    v = str(value).strip()
+    # try ISO first
+    try:
+        return dt.date.fromisoformat(v)
+    except ValueError:
+        pass
+    # dd-mm-yyyy or dd/mm/yyyy
+    for sep in ("-", "/"):
+        parts = v.split(sep)
+        if len(parts) == 3 and len(parts[0]) <= 2:
+            d, m, y = parts
+            return dt.date(int(y), int(m), int(d))
+    raise ValueError(v)
+
+
+def read_and_validate(path, defaults):
+    """
+    Returns (entries, errors).
+    - entries: list of entry dicts ready for engine.post_entry
+    - errors : list of human-readable problems (empty => file is valid)
+    If the file/headers are unusable, entries is [] and errors explains why.
+    """
+    if not os.path.exists(path):
+        return [], [f"File not found: {path}"]
+
+    try:
+        with open(path, newline="", encoding="utf-8-sig") as f:
+            reader = csv.DictReader(f)
+            if reader.fieldnames is None:
+                return [], ["The CSV appears to be empty."]
+            headers = [(h or "").strip().lower() for h in reader.fieldnames]
+            rows = list(reader)
+    except (OSError, csv.Error) as e:
+        return [], [f"Could not read the CSV: {e}"]
+
+    # header check
+    missing_required_cols = [c for c in REQUIRED if c not in headers]
+    if missing_required_cols:
+        return [], [f"Missing required column(s): {', '.join(missing_required_cols)}.",
+                    "Expected header: " + ",".join(KNOWN_COLUMNS)]
+
+    entries, errors = [], []
+    for i, raw in enumerate(rows, start=2):  # line 1 is the header
+        row = {(k or "").strip().lower(): (v.strip() if isinstance(v, str) else v)
+               for k, v in raw.items()}
+
+        # skip fully blank lines
+        if not any((row.get(c) or "").strip() for c in KNOWN_COLUMNS):
+            continue
+
+        subject = row.get("subject") or ""
+        if not subject:
+            errors.append(f"Line {i}: 'subject' is required.")
+            continue
+
+        # hours
+        hraw = row.get("hours") or ""
+        try:
+            hours = float(hraw)
+            if hours <= 0:
+                errors.append(f"Line {i}: 'hours' must be > 0.")
+                continue
+        except ValueError:
+            errors.append(f"Line {i}: 'hours' ('{hraw}') is not a number.")
+            continue
+
+        # date (logging date, required)
+        draw = row.get("date") or ""
+        try:
+            day = _parse_date(draw)
+        except ValueError:
+            errors.append(f"Line {i}: 'date' ('{draw}') is invalid "
+                          f"(use YYYY-MM-DD or dd-mm-yyyy).")
+            continue
+
+        entry = {"subject": subject, "hours": hours, "date": day}
+
+        # optional dates
+        for key in ("start_date", "due_date"):
+            val = row.get(key)
+            if val:
+                try:
+                    entry[key] = _parse_date(val)
+                except ValueError:
+                    errors.append(f"Line {i}: '{key}' ('{val}') is invalid.")
+        entry.setdefault("start_date", day)
+        entry.setdefault("due_date", entry.get("start_date", day))
+
+        # optional estimated_hours
+        est = row.get("estimated_hours")
+        if est:
+            try:
+                entry["estimated_hours"] = float(est)
+            except ValueError:
+                errors.append(f"Line {i}: 'estimated_hours' ('{est}') "
+                              f"is not a number.")
+
+        # optional free-text / lookup fields
+        for key in ("description", "priority", "status", "activity", "comment"):
+            if row.get(key):
+                entry[key] = row[key]
+
+        entries.append(entry)
+
+    if not entries and not errors:
+        errors.append("No task rows found in the CSV.")
+
+    return entries, errors