student-task-manager-cli 0.1.0__py3-none-any.whl

student_task_manager_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: student-task-manager-cli
+Version: 0.1.0
+Summary: A simple command-line task manager
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+## Install
+
+From the project directory, on macOS or Linux:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+On Windows PowerShell:
+
+```powershell
+py -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install -e .
+```
+
+After activation, run `task` to open the interactive terminal view.
+Enter commands at the `❯` prompt, for example `add Write report`, `ls`, or `/help`.
+`list` and `ls` are the same command. `list` shows To do tasks, `list --done` shows completed tasks, and `list --all` shows both.
+Titles may contain spaces without quotes. `clear` and `cls` clear the interactive screen;
+`clear-completed` removes completed tasks. Type `task` at the prompt to show the welcome view again.
+
+Tab completes commands and the arrow keys recall history on terminals with readline.
+The welcome screen shows your next task and a small activity chart.
+
+You can also run single commands directly, such as:
+`task add "Write report"` or `task --help`. 
+
+To leave the environment, run `deactivate`.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `task add "Write report"` | Add a task |
+| `task list` or `task ls` | List To do tasks |
+| `task list --done` | List completed tasks |
+| `task list --undone` | List To do tasks |
+| `task list --all` | List every task |
+| `task done 1` | Complete task 1 |
+| `task undone 1` | Make task 1 pending |
+| `task delete 1` | Delete task 1 |
+| `task update 1 "New title"` | Change task 1's title |
+| `task show 1` | Show task 1's details |
+| `task clear` | Delete completed tasks |
+| `task stats` | Show progress and a 7-day completion chart |
+| `task demo` | Try 26 sample tasks in a temporary workspace |
+| `task help` | Show all commands |
+
+Also available: `task --help`, `task --version`, and `task <command> --help` (for example, `task add --help`). IDs are positive integers. After deletion or a status change, tasks are renumbered from 1, with To do tasks first. Use `list --all` to see current IDs. Existing task files are normalized when read; new IDs are saved on the next change. Titles cannot be blank.
+
+## Try it with sample data
+
+```bash
+task demo
+```
+
+Or run `python test_task.py` from the project directory. Both open a separate
+session with 8 pending and 18 completed tasks spread across the last week.
+Try `ls`, `ls --done`, `done 1`, then `stats`. Type `/exit` to leave.
+Demo changes are discarded; your own tasks stay untouched.
+`task demo --preview` prints the sample list and chart without opening a prompt.
+
+## Progress
+
+`stats` shows task counts, completion percentage, and a daily chart:
+
+```text
+Progress  ━━━━━━━━━━━━━━──────  69%
+
+This week · completed tasks
+
+Tue 06  ━━━━              1
+Wed 07  ━━━━━━━━━━━━      3
+Thu 08  ━━━━━━━━          2
+Fri 09  ━━━━━━━━━━━━━━━━  4
+Sat 10  ━━━━              1
+Sun 11  ━━━━━━━━━━━━      3
+Mon 12  ━━━━━━━━━━━━━━━━  4
+```
+
+Dates follow your local timezone. `done` records the completion time; `undone`
+removes it. The chart counts tasks still in the file, so deleting completed tasks
+also removes them from the chart. Older tasks without a completion date still
+count toward the total, but not the daily chart.
+
+## Project structure
+
+```text
+src/task_manager/
+  cli.py            Entry point: one command or interactive mode
+  arguments.py      Command names, flags, and ls alias
+  commands.py       Add, edit, complete, delete, list
+  storage.py        JSON file, validation, task IDs
+  productivity.py   Weekly counts and progress
+  input.py          Parse commands typed at the prompt
+  interactive.py    Input loop and command history
+  demo.py           Sample tasks and temporary workspace
+  ui/
+    theme.py        Colors and terminal sizing
+    animation.py    Startup and result transitions
+    views.py        Welcome screen, help, and task list
+tests/              CLI, interactive, demo, and productivity tests
+test_task.py        Start the demo from the project directory
+```
+
+A command goes through `cli → arguments → commands → storage`.
+Interactive mode adds `input` and `ui`; both modes use the same commands.
+No runtime dependencies. Set `TASK_MANAGER_NO_ANIMATION=1` to disable motion,
+or `NO_COLOR=1` for plain output. Redirected output has no colors or animation.
+
+## Where tasks are stored
+
+The file is `tasks.json` in `~/Library/Application Support/task-manager/` on macOS, `%APPDATA%\task-manager\` on Windows, or `${XDG_DATA_HOME:-~/.local/share}/task-manager/` on Linux. It is created when a command saves tasks. A missing or empty file means no tasks. If JSON is corrupted, the command reports an error and leaves the file intact.
+
+## Run tests
+
+With the virtual environment active, install pytest separately for development:
+
+```bash
+python -m pip install pytest
+python -m pytest
+```
+
+Tests set `TASK_MANAGER_DATA_DIR` to a temporary directory. Your real task data is never cleared by the test suite.

student_task_manager_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+task_manager/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+task_manager/__main__.py,sha256=PSQ4rpL0dG6f-qH4N7H-gD9igQkdHzH4yVZDcW8lfZo,80
+task_manager/arguments.py,sha256=9Hq4VHDBfUfRyueN3VmFLd9Qr_wJSw004lA2OujhSpw,2157
+task_manager/cli.py,sha256=RblrY0GU5C9cDDWF3-1K59QPXVfLdNeG7EMbmE1xC9c,563
+task_manager/commands.py,sha256=5nXQhrglLo-XE6NiQc8WgjWKm972jqTjgoZ-xUCzOdE,3213
+task_manager/demo.py,sha256=-qfyP5anpaHAXmBsJmfKmQKaVZmJFBdl2R1jbJXr1m8,2950
+task_manager/input.py,sha256=cmV2_xQZNeYChEMb_5b2ZYSZ3ljlhrQUsTsXD9IUcfk,1210
+task_manager/interactive.py,sha256=YZsFwuh9CNTQVsWvu8i1XLiZJnK7b4YqNv-eoQr9L7M,3226
+task_manager/productivity.py,sha256=LRwnDIfG6wC7wYudVoeU_X1Qb_GMCkZQiNX7M7ewriU,1795
+task_manager/storage.py,sha256=Cbrd8AH_gETRhalO4nwF6med-8HAssBoUp0WtHHYcwM,2911
+task_manager/ui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+task_manager/ui/animation.py,sha256=yxexybBlelYpRe6Cdm-9Vb-2ajFNkuJ3MORlUth3f7I,681
+task_manager/ui/theme.py,sha256=7eqxQsPuKgC4DryiYcxtAItXYtYtJLfdG9cjSRaljbI,1360
+task_manager/ui/views.py,sha256=5tYxwg2i7P08pRQvzQ5W_pDVR1J4t-vYHi0fJ4iy_qs,5489
+student_task_manager_cli-0.1.0.dist-info/METADATA,sha256=MwVTU_xu5s80AUrlp7sTt4sknBBLSQP0E69NXmx1Axk,5240
+student_task_manager_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+student_task_manager_cli-0.1.0.dist-info/entry_points.txt,sha256=r3oqZvrjOl-rGX2jprgCiv-ejzWlbQmZv-le8hB6KyA,47
+student_task_manager_cli-0.1.0.dist-info/top_level.txt,sha256=txVWUWwaSeBBGIFJea7iM-OGDJJYKyVuQPPXqt-CXyw,13
+student_task_manager_cli-0.1.0.dist-info/RECORD,,

student_task_manager_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

student_task_manager_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+task = task_manager.cli:main

student_task_manager_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+task_manager

task_manager/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

task_manager/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

task_manager/arguments.py

@@ -0,0 +1,52 @@
+import argparse
+
+from . import __version__
+
+
+def positive_id(value: str) -> int:
+    try:
+        task_id = int(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError("task ID must be a positive number") from error
+    if task_id < 1:
+        raise argparse.ArgumentTypeError("task ID must be a positive number")
+    return task_id
+
+
+def parser_for_cli() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="task", description="Manage your tasks.")
+    parser.add_argument("--version", action="version", version=f"task {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    descriptions = {
+        "add": "Add a new task",
+        "list": "List pending tasks (or filter by status)",
+        "done": "Mark a task as completed",
+        "undone": "Mark a task as pending",
+        "delete": "Delete a task",
+        "update": "Change a task title",
+        "show": "Show task details",
+        "clear": "Delete completed tasks",
+        "stats": "Show weekly productivity",
+        "demo": "Open a session with sample tasks",
+        "help": "Show all commands",
+    }
+    for name, description in descriptions.items():
+        command = commands.add_parser(
+            name, aliases=["ls"] if name == "list" else [],
+            help=description, description=description,
+        )
+        command.set_defaults(command=name)
+        if name in ("done", "undone", "delete", "update", "show"):
+            command.add_argument("id", type=positive_id, help="positive task ID")
+        if name in ("add", "update"):
+            command.add_argument("title", help="task title")
+        if name == "demo":
+            command.add_argument("--preview", action="store_true", help="print the demo and exit")
+        if name == "list":
+            filters = command.add_mutually_exclusive_group()
+            filters.add_argument("--done", action="store_true", help="show completed tasks")
+            filters.add_argument("--undone", action="store_true", help="show pending tasks")
+            filters.add_argument("--all", action="store_true", help="show every task")
+    return parser
+
+

task_manager/cli.py

@@ -0,0 +1,22 @@
+import sys
+
+from .arguments import parser_for_cli
+from .commands import execute
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if not argv:
+        from .interactive import run_interactive
+
+        return run_interactive(main)
+    parser = parser_for_cli()
+    args = parser.parse_args(argv)
+    if args.command == "help":
+        parser.print_help()
+        return 0
+    if args.command == "demo":
+        from .demo import run_demo
+
+        return run_demo(preview=args.preview)
+    return execute(args)

task_manager/commands.py

@@ -0,0 +1,75 @@
+import sys
+from datetime import datetime, timezone
+
+from .productivity import format_stats
+from .storage import StorageError, load_data, save_data
+
+
+def execute(args) -> int:
+    if args.command in ("add", "update"):
+        title = args.title.strip()
+        if not title:
+            print("Error: task title cannot be empty.", file=sys.stderr)
+            return 1
+
+    try:
+        data = load_data()
+        tasks = data["tasks"]
+
+        if args.command == "add":
+            task = {
+                "id": data["next_id"],
+                "title": title,
+                "status": "pending",
+                "created_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            }
+            tasks.append(task)
+            save_data(data)
+            print(f"Added task {task['id']}: {title}")
+        elif args.command == "list":
+            visible = [task for task in tasks if args.all or task["status"] == ("completed" if args.done else "pending")]
+            if not visible:
+                print("No tasks yet." if not tasks else "No completed tasks." if args.done else "No pending tasks.")
+            for task in visible:
+                print(f"{task['id']}. [{task['status']}] {task['title']}")
+        elif args.command == "stats":
+            print(format_stats(tasks))
+        elif args.command == "clear":
+            remaining = [task for task in tasks if task["status"] != "completed"]
+            removed = len(tasks) - len(remaining)
+            data["tasks"] = remaining
+            save_data(data)
+            print(f"Removed {removed} completed task(s).")
+        else:
+            task = next((task for task in tasks if task["id"] == args.id), None)
+            if task is None:
+                print(f"Error: task {args.id} not found.", file=sys.stderr)
+                return 1
+            if args.command == "show":
+                print(f"ID: {task['id']}\nTitle: {task['title']}\nStatus: {task['status']}\nCreated: {task['created_at']}")
+                if task.get("completed_at"):
+                    print(f"Completed: {task['completed_at']}")
+            elif args.command == "delete":
+                tasks.remove(task)
+                save_data(data)
+                print(f"Deleted task {args.id}.")
+            else:
+                if args.command == "update":
+                    task["title"] = title
+                else:
+                    if args.command == "done" and task["status"] != "completed":
+                        task["completed_at"] = datetime.now(timezone.utc).isoformat(timespec="seconds")
+                    elif args.command == "undone":
+                        task.pop("completed_at", None)
+                    task["status"] = "completed" if args.command == "done" else "pending"
+                save_data(data)
+                if args.command == "done":
+                    print(f"Completed: {task['title']}")
+                elif args.command == "undone":
+                    print(f"Back to To do: {task['title']}")
+                else:
+                    print(f"Renamed task {task['id']}: {task['title']}")
+    except StorageError as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 1
+    return 0

task_manager/demo.py

@@ -0,0 +1,69 @@
+import os
+from datetime import datetime, timedelta
+from tempfile import TemporaryDirectory
+
+from .storage import save_data
+
+PENDING = (
+    "Prepare the CLI project presentation",
+    "Draw the module diagram for the teacher",
+    "Practice explaining JSON storage",
+    "Review Python decorators",
+    "Finish database homework",
+    "Read 15 pages of Clean Code",
+    "Plan next week's study sessions",
+    "Push the final package to GitHub",
+)
+COMPLETED = (
+    "Set up the virtual environment", "Create the package structure",
+    "Build the add command", "Save tasks as JSON", "Handle missing files",
+    "Implement list filters", "Validate task IDs", "Add update and delete",
+    "Write storage tests", "Test Unicode titles", "Fix empty task names",
+    "Add command history", "Design the welcome screen", "Add the ls alias",
+    "Build the weekly chart", "Check the README examples", "Run the test suite",
+    "Rehearse the project demo",
+)
+
+
+def sample_data(now: datetime | None = None) -> dict:
+    now = now or datetime.now().astimezone()
+    tasks = []
+    for title in PENDING:
+        tasks.append({"id": len(tasks) + 1, "title": title, "status": "pending",
+                      "created_at": (now - timedelta(days=2)).isoformat(timespec="seconds")})
+    titles = iter(COMPLETED)
+    for days_ago, count in zip(range(6, -1, -1), (1, 3, 2, 4, 1, 3, 4)):
+        completed = now - timedelta(days=days_ago)
+        for _ in range(count):
+            tasks.append({"id": len(tasks) + 1, "title": next(titles), "status": "completed",
+                          "created_at": (completed - timedelta(days=1)).isoformat(timespec="seconds"),
+                          "completed_at": completed.isoformat(timespec="seconds")})
+    return {"next_id": len(tasks) + 1, "tasks": tasks}
+
+
+def run_demo(preview: bool = False) -> int:
+    from .cli import main
+    from .productivity import format_stats
+    from .ui.views import show_result, welcome
+
+    previous = os.environ.get("TASK_MANAGER_DATA_DIR")
+    with TemporaryDirectory(prefix="task-manager-demo-") as directory:
+        os.environ["TASK_MANAGER_DATA_DIR"] = directory
+        try:
+            data = sample_data()
+            save_data(data)
+            print("\n  DEMO · 26 sample tasks · changes last only for this session")
+            if preview:
+                welcome()
+                message = "\n".join(f"{task['id']}. [{task['status']}] {task['title']}" for task in data["tasks"])
+                show_result("list", message, False, ["list", "--all"])
+                print()
+                show_result("stats", format_stats(data["tasks"]), False)
+                return 0
+            print("  Try ls, ls --done, done 1, stats. /exit leaves the demo.")
+            return main([])
+        finally:
+            if previous is None:
+                os.environ.pop("TASK_MANAGER_DATA_DIR", None)
+            else:
+                os.environ["TASK_MANAGER_DATA_DIR"] = previous

task_manager/input.py

@@ -0,0 +1,36 @@
+import shlex
+
+
+def parse_command(line: str) -> list[str]:
+    line = line.strip()
+    if line.startswith("/"):
+        line = line[1:]
+    parts = line.split(maxsplit=1)
+    if not parts:
+        return ["help"]
+    command, rest = parts[0], parts[1] if len(parts) > 1 else ""
+    command = command.lower()
+    command = "list" if command == "ls" else command
+    rest = rest.strip()
+    if command == "task":
+        return parse_command(rest) if rest else ["home"]
+    if rest in {"--help", "-h"}:
+        return [command, rest]
+    if command == "add":
+        if rest.startswith(('"', "'")):
+            words = shlex.split(rest)
+            if len(words) == 1:
+                rest = words[0]
+        return [command, rest] if rest else [command]
+    if command == "update":
+        parts = rest.split(maxsplit=1)
+        task_id = parts[0] if parts else ""
+        title = parts[1].strip() if len(parts) > 1 else ""
+        if title.startswith(('"', "'")):
+            words = shlex.split(title)
+            if len(words) == 1:
+                title = words[0]
+        return [command, task_id, title] if title else [command, task_id] if task_id else [command]
+    return [command, *shlex.split(rest)]
+
+

task_manager/interactive.py

@@ -0,0 +1,97 @@
+import contextlib
+import io
+import sys
+from collections.abc import Callable
+
+from .input import parse_command
+from .ui.animation import startup
+from .ui.theme import MUTED, paint, prompt, rule, styled
+from .ui.views import show_help, show_result, welcome
+
+COMMANDS = {"add", "list", "ls", "done", "undone", "delete", "update", "show",
+            "clear-completed", "stats", "demo"}
+
+
+@contextlib.contextmanager
+def completion():
+    try:
+        import readline
+    except ImportError:
+        yield
+        return
+    previous = readline.get_completer()
+    words = sorted(COMMANDS | {"help", "exit", "clear", "cls", "task", "home"})
+
+    def complete(text: str, state: int) -> str | None:
+        prefix = "/" if text.startswith("/") else ""
+        matches = [prefix + word + " " for word in words if word.startswith(text.lstrip("/"))]
+        return matches[state] if state < len(matches) else None
+
+    delimiters = readline.get_completer_delims()
+    readline.set_completer_delims(" \t\n")
+    readline.set_completer(complete)
+    binding = "bind ^I rl_complete" if "libedit" in (readline.__doc__ or "") else "tab: complete"
+    readline.parse_and_bind(binding)
+    try:
+        yield
+    finally:
+        readline.set_completer(previous)
+        readline.set_completer_delims(delimiters)
+
+
+def run_interactive(execute: Callable[[list[str]], int]) -> int:
+    try:
+        with completion():
+            startup()
+            welcome()
+            return command_loop(execute)
+    except (EOFError, KeyboardInterrupt):
+        print("\n  Goodbye.")
+        return 0
+
+
+def command_loop(execute: Callable[[list[str]], int]) -> int:
+    while True:
+        if styled():
+            print(paint("  /help for commands · Tab to complete", MUTED))
+            rule()
+        line = input(prompt())
+        if not line.strip():
+            continue
+        if styled():
+            rule()
+        try:
+            args = parse_command(line)
+        except ValueError as error:
+            show_result("", str(error), True)
+            continue
+        command = args[0]
+        if command in {"exit", "quit"}:
+            print("  Goodbye.")
+            return 0
+        if command == "home":
+            welcome()
+            continue
+        if command in {"clear", "cls", "clear-screen"}:
+            print("\x1b[2J\x1b[H" if styled() else "", end="")
+            welcome()
+            continue
+        if command == "help":
+            show_help()
+        elif command not in COMMANDS:
+            show_result(command, f"Unknown command: {command}. Type /help for commands.", True)
+        elif command == "demo":
+            try:
+                execute(args)
+            except SystemExit:
+                pass
+            welcome()
+        else:
+            output, errors = io.StringIO(), io.StringIO()
+            with contextlib.redirect_stdout(output), contextlib.redirect_stderr(errors):
+                try:
+                    result = execute(["clear", *args[1:]] if command == "clear-completed" else args)
+                except SystemExit as error:
+                    result = error.code
+            show_result(command, (errors if result else output).getvalue().strip(), bool(result), args)
+        print()

task_manager/productivity.py

@@ -0,0 +1,37 @@
+from datetime import date, datetime, timedelta
+
+
+def weekly_counts(tasks: list[dict], today: date | None = None) -> list[tuple[date, int]]:
+    today = today or datetime.now().astimezone().date()
+    counts = {today - timedelta(days=offset): 0 for offset in range(6, -1, -1)}
+    for task in tasks:
+        if task["status"] != "completed" or not task.get("completed_at"):
+            continue
+        try:
+            completed = datetime.fromisoformat(task["completed_at"]).astimezone().date()
+        except (ValueError, TypeError):
+            continue
+        if completed in counts:
+            counts[completed] += 1
+    return list(counts.items())
+
+
+def format_stats(tasks: list[dict], today: date | None = None) -> str:
+    completed = sum(task["status"] == "completed" for task in tasks)
+    total = len(tasks)
+    percent = round(100 * completed / total) if total else 0
+    filled = round(20 * completed / total) if total else 0
+    lines = [f"Total: {total}", f"Completed: {completed}", f"Pending: {total - completed}", "",
+             f"Progress  {'━' * filled}{'─' * (20 - filled)}  {percent}%", "",
+             "This week · completed tasks", ""]
+    week = weekly_counts(tasks, today)
+    peak = max(count for _, count in week) or 1
+    for day, count in week:
+        bar = '━' * max(1, round(count / peak * 16)) if count else '·'
+        lines.append(f"{day:%a %d}  {bar:<16}  {count}")
+    lines += ["", f"{sum(count for _, count in week)} completed in the last 7 days"]
+    undated = sum(task["status"] == "completed" and not task.get("completed_at") for task in tasks)
+    if undated:
+        lines.append(f"{undated} older completed task(s) without a date")
+    lines.append("Chart uses completion dates of tasks still in your list.")
+    return "\n".join(lines)

task_manager/storage.py

@@ -0,0 +1,78 @@
+import json
+import os
+import sys
+from pathlib import Path
+
+
+class StorageError(Exception):
+    pass
+
+
+def normalize_data(data: dict) -> None:
+    """Pending tasks first, IDs from one."""
+    tasks = data["tasks"]
+    tasks[:] = ([task for task in tasks if task["status"] == "pending"]
+                + [task for task in tasks if task["status"] == "completed"])
+    for task_id, task in enumerate(tasks, start=1):
+        task["id"] = task_id
+    data["next_id"] = len(tasks) + 1
+
+
+def data_file() -> Path:
+    override = os.environ.get("TASK_MANAGER_DATA_DIR")
+    if override:
+        directory = Path(override)
+    elif sys.platform == "win32":
+        directory = Path(os.environ.get("APPDATA", str(Path.home() / "AppData" / "Roaming"))) / "task-manager"
+    elif sys.platform == "darwin":
+        directory = Path.home() / "Library" / "Application Support" / "task-manager"
+    else:
+        directory = Path(os.environ.get("XDG_DATA_HOME", str(Path.home() / ".local" / "share"))) / "task-manager"
+    return directory / "tasks.json"
+
+
+def load_data() -> dict:
+    path = data_file()
+    try:
+        if not path.exists() or path.stat().st_size == 0:
+            return {"next_id": 1, "tasks": []}
+        with path.open(encoding="utf-8") as file:
+            data = json.load(file)
+    except (OSError, UnicodeError) as error:
+        raise StorageError(f"Cannot read task file {path}: {error}") from error
+    except json.JSONDecodeError as error:
+        raise StorageError(f"Task file {path} contains invalid JSON: {error.msg}") from error
+
+    if (not isinstance(data, dict)
+            or type(data.get("next_id")) is not int
+            or data["next_id"] < 1
+            or not isinstance(data.get("tasks"), list)):
+        raise StorageError(f"Task file {path} has an invalid format.")
+    ids = set()
+    for task in data["tasks"]:
+        if (not isinstance(task, dict)
+                or type(task.get("id")) is not int
+                or task["id"] < 1
+                or task["id"] in ids
+                or not isinstance(task.get("title"), str)
+                or not task["title"].strip()
+                or task.get("status") not in ("pending", "completed")
+                or not isinstance(task.get("created_at"), str)):
+            raise StorageError(f"Task file {path} has an invalid format.")
+        ids.add(task["id"])
+    if ids and data["next_id"] <= max(ids):
+        raise StorageError(f"Task file {path} has an invalid format.")
+    normalize_data(data)
+    return data
+
+
+def save_data(data: dict) -> None:
+    normalize_data(data)
+    path = data_file()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("w", encoding="utf-8") as file:
+            json.dump(data, file, indent=2, ensure_ascii=False)
+            file.write("\n")
+    except OSError as error:
+        raise StorageError(f"Cannot save task file {path}: {error}") from error

task_manager/ui/animation.py

@@ -0,0 +1,26 @@
+import sys
+import time
+
+from .theme import ACCENT, animated, paint
+
+
+def startup() -> None:
+    if not animated():
+        return
+    try:
+        sys.stdout.write("\x1b[?25l")
+        for frame in ("·", "✢", "✳", "✶", "✳", "✢"):
+            sys.stdout.write("\r  " + paint(frame + "  Opening your workspace", ACCENT))
+            sys.stdout.flush()
+            time.sleep(0.055)
+    finally:
+        sys.stdout.write("\r\x1b[2K\x1b[?25h")
+        sys.stdout.flush()
+
+
+def reveal(lines: list[str]) -> None:
+    motion = animated()
+    for index, line in enumerate(lines):
+        print(line, flush=motion)
+        if motion and index < 10:
+            time.sleep(0.012)

task_manager/ui/theme.py

@@ -0,0 +1,57 @@
+import os
+import shutil
+import sys
+import unicodedata
+
+ACCENT = "\x1b[38;5;173m"
+GREEN = "\x1b[38;5;114m"
+MUTED = "\x1b[38;5;245m"
+RED = "\x1b[38;5;203m"
+BOLD = "\x1b[1m"
+RESET = "\x1b[0m"
+
+
+def styled() -> bool:
+    return sys.stdout.isatty() and os.environ.get("TERM") != "dumb" and "NO_COLOR" not in os.environ
+
+
+def animated() -> bool:
+    return styled() and not os.environ.get("TASK_MANAGER_NO_ANIMATION")
+
+
+def paint(value: str, color: str) -> str:
+    return f"{color}{value}{RESET}" if color and styled() else value
+
+
+def width() -> int:
+    return max(12, min(shutil.get_terminal_size((80, 24)).columns - 2, 96))
+
+
+def clean(value: str) -> str:
+    return "".join(char if not unicodedata.category(char).startswith("C") else " " for char in value)
+
+
+def cells(value: str) -> int:
+    return sum(0 if unicodedata.combining(char) else 2 if unicodedata.east_asian_width(char) in "WF" else 1 for char in value)
+
+
+def fit(value: str, limit: int) -> str:
+    value = clean(value)
+    if cells(value) <= limit:
+        return value
+    result = ""
+    for char in value:
+        if cells(result + char) > limit - 1:
+            break
+        result += char
+    return result + "…"
+
+
+def rule() -> None:
+    print(paint("─" * width(), MUTED))
+
+
+def prompt() -> str:
+    if styled():
+        return f"\001{ACCENT}\002❯\001{RESET}\002 "
+    return "❯ "

task_manager/ui/views.py

@@ -0,0 +1,123 @@
+import re
+
+from .. import __version__
+from ..productivity import weekly_counts
+from ..storage import StorageError, load_data
+from .animation import reveal
+from .theme import ACCENT, BOLD, GREEN, MUTED, RED, cells, clean, fit, paint, width
+
+
+HELP = (
+    ("add <title>", "Create a task"),
+    ("list / ls", "Show To do tasks"),
+    ("ls --done / --all", "Completed / every task"),
+    ("done / undone <id>", "Change status"),
+    ("update <id> <title>", "Rename a task"),
+    ("show <id>", "Task details"),
+    ("delete <id>", "Remove a task"),
+    ("stats", "Progress and weekly chart"),
+    ("demo", "Try a separate sample workspace"),
+    ("clear / cls", "Clear the terminal"),
+    ("clear-completed", "Remove completed tasks"),
+    ("task / home", "Show the welcome view"),
+    ("/exit", "Close this session"),
+)
+
+
+def welcome() -> None:
+    inner = width() - 2
+    label = fit(f" Task Manager · v{__version__} ", inner)
+    print()
+    print(paint("╭" + label + "─" * (inner - cells(label)) + "╮", ACCENT))
+
+    def padded(text: str, size: int, color: str = "") -> str:
+        text = fit(text, size)
+        return paint(text, color) + " " * (size - cells(text))
+
+    def row(left: str = "", right: str | None = None, color: str = "") -> None:
+        if right is None:
+            body = padded(left, inner, color)
+        else:
+            split = 33
+            body = padded(left, split, color) + paint("│", MUTED) + padded(right, inner - split - 2, color) + " "
+        print(paint("│", MUTED) + body + paint("│", MUTED))
+
+    try:
+        tasks = load_data()["tasks"]
+        done = sum(task["status"] == "completed" for task in tasks)
+        counts = [count for _, count in weekly_counts(tasks)]
+        peak = max(counts) or 1
+        spark = "".join("▁▂▃▄▅▆▇█"[round(count / peak * 7)] for count in counts)
+        next_task = next((task for task in tasks if task["status"] == "pending"), None)
+        next_title = f"#{next_task['id']} {next_task['title']}" if next_task else "All clear. Add your next task."
+        summary = f"{len(tasks) - done} to do   /   {done} completed"
+        if inner >= 72:
+            row("", "")
+            row("       Welcome back", "   This week", BOLD)
+            row("", "")
+            row("            ▗▄▄▄▖", f"   {spark}   {sum(counts)} completed", ACCENT)
+            row("            ▐▪ ▪▌", "   Last 7 days · stats for details", MUTED)
+            row("            ▝▀▀▀▘", "")
+            row("", "   Up next", BOLD)
+            row("   " + summary, "   " + next_title)
+            row("   Local workspace · Python CLI", "   ls to view your tasks", MUTED)
+            row("", "")
+        else:
+            row()
+            row("   ✳  Welcome back", color=BOLD)
+            row("   Your tasks, one place.", color=MUTED)
+            row()
+            row("   " + summary)
+            row(f"   {spark}   {sum(counts)} this week", color=GREEN)
+            row("   Up next  " + next_title, color=MUTED)
+            row()
+    except StorageError:
+        row("   Welcome back", color=BOLD)
+        row("   Tasks unavailable — check your data file", color=RED)
+    print(paint("╰" + "─" * inner + "╯", MUTED))
+    print("  " + paint(fit("/help commands · stats progress · /exit quit", width() - 2), MUTED))
+    print()
+
+
+def show_help() -> None:
+    print("  " + paint("Commands", BOLD))
+    for command, hint in HELP:
+        if width() < 62:
+            print("  " + paint(command, ACCENT))
+            print("    " + paint(hint, MUTED))
+        else:
+            print(f"  {paint(command.ljust(26), ACCENT)}{paint(hint, MUTED)}")
+    print("\n  Commands accept a leading / or task prefix.")
+    print("  Tab completes commands; ↑ / ↓ recalls history where supported.")
+    print("  IDs change after edits. Use ls to see current IDs.")
+
+
+def show_result(command: str, message: str, is_error: bool, args: list[str] | None = None) -> None:
+    if not message:
+        return
+    lines = []
+    if command in {"list", "ls"} and not is_error:
+        heading = "Completed" if args and "--done" in args else "All tasks" if args and "--all" in args else "To do"
+        lines.append("  " + paint(heading, BOLD))
+        count = 0
+        for line in message.splitlines():
+            match = re.fullmatch(r"(\d+)\. \[(pending|completed)\] (.*)", line)
+            if match:
+                task_id, status, title = match.groups()
+                done = status == "completed"
+                symbol = paint("✓", GREEN) if done else paint("○", ACCENT)
+                lines.append(f"  {symbol}  {paint(task_id.rjust(3), MUTED)}  {paint(fit(title, width() - 11), MUTED) if done else fit(title, width() - 11)}")
+                count += 1
+            else:
+                lines.append("  " + paint(clean(line), MUTED))
+        if count:
+            lines += ["", "  " + paint(f"{count} task(s) · done <id> to complete · stats to see progress", MUTED)]
+    elif command == "stats" and not is_error:
+        lines.append("  " + paint("Your momentum", BOLD))
+        for line in message.splitlines():
+            color = GREEN if "━" in line else MUTED if line.startswith("Chart") else ""
+            lines.append("  " + paint(line, color))
+    else:
+        marker = paint("✕", RED) if is_error else paint("●", GREEN)
+        lines = [f"  {marker if index == 0 else ' '}  {clean(line)}" for index, line in enumerate(message.splitlines())]
+    reveal(lines)