knbn 0.0.1__py3-none-any.whl

knbn/__init__.py

@@ -0,0 +1 @@
+"""knbn — terminal-native personal Kanban board."""

knbn/__main__.py

@@ -0,0 +1,11 @@
+"""knbn — terminal Kanban board."""
+
+from knbn.cli import cli
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == '__main__':
+    main()

knbn/app.py

@@ -0,0 +1,207 @@
+"""Textual TUI application."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+from textual.app import App, ComposeResult, SystemCommand
+from textual.binding import Binding
+from textual.reactive import reactive
+from textual.screen import Screen
+from textual.widgets import Footer, Static
+from textual.widgets._footer import FooterKey
+
+from knbn.config import (
+    BoardConfig,
+    BoardConfigError,
+    build_default_board_config,
+    load_board_config,
+    load_settings,
+    save_settings,
+)
+from knbn.model.store import ensure_data_dir, load_tasks
+from knbn.model.task import Task
+
+_VIEW_ACTION = {
+    'kanban': 'show_kanban',
+    'tabular': 'show_tabular',
+    'closed': 'show_closed',
+}
+
+
+class KnbnFooter(Footer):
+    """Footer that highlights the active view tab key and shows the data dir."""
+
+    active_view: reactive[str] = reactive('kanban')
+
+    def __init__(self, data_dir: Path) -> None:
+        super().__init__()
+        home = Path.home()
+        try:
+            rel = data_dir.relative_to(home)
+            self._data_dir_display = '~' if rel == Path() else f'~/{rel}'
+        except ValueError:
+            self._data_dir_display = str(data_dir)
+
+    def compose(self) -> ComposeResult:
+        yield from super().compose()
+        yield Static(self._data_dir_display, id='data-dir-label')
+
+    def bindings_changed(self, screen: Screen) -> None:
+        super().bindings_changed(screen)
+        self.call_after_refresh(self._apply_active_class)
+
+    def watch_active_view(self) -> None:
+        self.call_after_refresh(self._apply_active_class)
+
+    def _apply_active_class(self) -> None:
+        active_action = _VIEW_ACTION.get(self.active_view, '')
+        for key_widget in self.query(FooterKey):
+            key_widget.set_class(key_widget.action == active_action, '-active-tab')
+
+
+class KnbnApp(App[None]):
+    """Terminal Kanban board."""
+
+    TITLE = 'knbn'
+    CSS = """
+    Screen {
+        background: $surface;
+    }
+    #view-container {
+        height: 1fr;
+    }
+    FooterKey.-active-tab .footer-key--key {
+        color: $footer-key-background;
+        background: $footer-key-foreground;
+    }
+    FooterKey.-active-tab .footer-key--description {
+        color: $footer-key-foreground;
+        background: $footer-description-background;
+        text-style: bold;
+    }
+    #data-dir-label {
+        width: 1fr;
+        text-align: right;
+        text-style: dim;
+        padding: 0 1;
+    }
+    """
+
+    BINDINGS = [
+        Binding('1', 'show_kanban', 'Kanban', show=True),
+        Binding('2', 'show_tabular', 'Tabular', show=True),
+        Binding('3', 'show_closed', 'Closed', show=True),
+        Binding('q', 'quit', 'Quit', show=True),
+        Binding('r', 'reload', 'Reload', show=True),
+        Binding('a', 'add_task', 'Add', show=True),
+        Binding('question_mark', 'help', 'Help', show=True),
+    ]
+
+    def __init__(self, data_dir: Path, theme: str = 'textual-dark') -> None:
+        self.data_dir = data_dir
+        super().__init__()
+        self._tasks: list[Task] = []
+        self._current_view: str = 'kanban'
+        self.theme = theme
+        self.board_config: BoardConfig = build_default_board_config()
+
+    def on_mount(self) -> None:
+        size = self.app.size
+        if size.width < 100 or size.height < 30:
+            self.exit(message='Terminal too small. Minimum size: 100×30.')
+            return
+        try:
+            self.board_config = load_board_config(self.data_dir)
+        except BoardConfigError as e:
+            self.exit(message=f'Board config error: {e}')
+            return
+        self._reload_tasks()
+        self._show_view('kanban')
+
+    def _reload_tasks(self) -> None:
+        ensure_data_dir(self.data_dir)
+        self._tasks = load_tasks(self.data_dir)
+
+    def _show_view(self, view: str) -> None:
+        from knbn.views.done_week import ClosedView
+        from knbn.views.kanban import KanbanView
+        from knbn.views.tabular import TabularView
+
+        self._reload_tasks()
+        container = self.query_one('#view-container')
+        container.remove_children()
+        if view == 'kanban':
+            container.mount(KanbanView(self._tasks, self.data_dir))
+        elif view == 'tabular':
+            container.mount(TabularView(self._tasks, self.data_dir))
+        elif view == 'closed':
+            container.mount(ClosedView(self._tasks, self.data_dir))
+        self._current_view = view
+        self.query_one(KnbnFooter).active_view = view
+
+    def compose(self) -> ComposeResult:
+        yield Static(id='view-container')
+        yield KnbnFooter(self.data_dir)
+
+    def action_reload(self) -> None:
+        self._show_view(self._current_view)
+
+    def action_show_kanban(self) -> None:
+        self._show_view('kanban')
+
+    def action_show_tabular(self) -> None:
+        self._show_view('tabular')
+
+    def action_show_closed(self) -> None:
+        self._show_view('closed')
+
+    def get_system_commands(self, screen: Screen) -> Iterable[SystemCommand]:
+        yield SystemCommand(
+            'Theme', 'Change the current theme', self.action_change_theme
+        )
+        yield SystemCommand('Quit', 'Quit the application', self.action_quit)
+        if screen.query('HelpPanel'):
+            yield SystemCommand(
+                'Keys', 'Hide the keys panel', self.action_hide_help_panel
+            )
+        else:
+            yield SystemCommand(
+                'Keys', 'Show help for the focused widget', self.action_show_help_panel
+            )
+
+    def action_add_task(self) -> None:
+        from knbn.views.kanban import KanbanView
+        from knbn.widgets.form import TaskForm
+
+        initial_status: str | None = None
+        initial_priority: str | None = None
+        if self._current_view == 'kanban':
+            kanban_views = self.query(KanbanView)
+            if kanban_views:
+                ctx = kanban_views.first(KanbanView).get_lane_context()
+                if ctx is not None:
+                    initial_status, initial_priority = ctx
+
+        self.push_screen(
+            TaskForm(
+                data_dir=self.data_dir,
+                task=None,
+                initial_status=initial_status,
+                initial_priority=initial_priority,
+            )
+        )
+
+    def action_help(self) -> None:
+        from knbn.widgets.help import HelpOverlay
+
+        self.push_screen(HelpOverlay())
+
+    def on_task_form_task_saved(self) -> None:
+        self._show_view(self._current_view)
+
+    def watch_theme(self, theme: str) -> None:
+        settings = load_settings(self.data_dir)
+        settings['app']['theme'] = theme
+        save_settings(self.data_dir, settings)

knbn/cli.py

@@ -0,0 +1,175 @@
+"""CLI commands for knbn."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from knbn.config import load_board_config, resolve_data_dir
+from knbn.model.store import add_task, ensure_data_dir
+from knbn.model.task import Task, now_str
+
+
+def _prompt_select(label: str, options: list[str], default: str) -> str:
+    opts_str = '  '.join(f'({i + 1}) {opt}' for i, opt in enumerate(options))
+    default_idx = options.index(default) + 1 if default in options else 1
+    while True:
+        idx: int = click.prompt(
+            f'{label}\n  {opts_str}',
+            type=int,
+            default=default_idx,
+        )
+        if 1 <= idx <= len(options):
+            return options[idx - 1]
+        click.echo(f'Please enter a number between 1 and {len(options)}.')
+
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(board)
+
+
+@cli.command()
+@click.argument('path', required=False)
+def init(path: str | None) -> None:
+    """Initialize the knbn data directory."""
+    data_dir = Path(path) if path else resolve_data_dir()
+    from knbn.setup import run_setup_wizard, should_run_wizard
+
+    already_existed = data_dir.exists()
+    if should_run_wizard(data_dir):
+        run_setup_wizard(data_dir)
+    ensure_data_dir(data_dir)
+    if already_existed:
+        print(f'Already initialized at {data_dir}')
+    else:
+        print(f'Initialized knbn data at {data_dir}')
+
+
+@cli.command()
+def board() -> None:
+    """Launch the interactive Kanban board."""
+    from knbn.app import KnbnApp  # pragma: no cover
+    from knbn.config import get_app_setting  # pragma: no cover
+    from knbn.setup import run_setup_wizard, should_run_wizard  # pragma: no cover
+
+    data_dir = resolve_data_dir()  # pragma: no cover
+    if should_run_wizard(data_dir):  # pragma: no cover
+        run_setup_wizard(data_dir)  # pragma: no cover
+    ensure_data_dir(data_dir)  # pragma: no cover
+    theme = get_app_setting(data_dir, 'theme', 'textual-dark')  # pragma: no cover
+    KnbnApp(data_dir=data_dir, theme=theme).run()  # pragma: no cover
+
+
+@cli.command()
+@click.option('--title', '-t', default=None, help='Task title (skips prompt)')
+@click.option(
+    '--status-default', 'status_default', is_flag=True, help='Use default status'
+)
+@click.option(
+    '--priority-default',
+    'priority_default',
+    is_flag=True,
+    help='Use default priority',
+)
+@click.option(
+    '--category-default',
+    'category_default',
+    is_flag=True,
+    help='Use default category',
+)
+@click.option(
+    '--no-resource', 'no_resource', is_flag=True, help='Skip key resource prompt'
+)
+@click.option(
+    '--no-free-text', 'no_free_text', is_flag=True, help='Skip free-text field prompts'
+)
+@click.option(
+    '--fast', '-f', is_flag=True, help='Use all defaults and skip all optional prompts'
+)
+def add(
+    title: str | None,
+    status_default: bool,
+    priority_default: bool,
+    category_default: bool,
+    no_resource: bool,
+    no_free_text: bool,
+    fast: bool,
+) -> None:
+    """Quickly add a new task."""
+    if fast:
+        status_default = priority_default = category_default = no_resource = (
+            no_free_text
+        ) = True
+
+    data_dir = resolve_data_dir()
+    ensure_data_dir(data_dir)
+    board_config = load_board_config(data_dir)
+
+    active_statuses = board_config.active_statuses
+    category_names = [c.name for c in board_config.categories]
+    priorities = board_config.priorities
+    default_status = active_statuses[0]
+    default_priority = priorities[len(priorities) // 2]
+    default_category = category_names[-1] if category_names else ''
+
+    # Title
+    if title is None:
+        title = click.prompt(click.style('Title', bold=True), type=str)
+
+    # Status
+    if status_default:
+        status = default_status
+    else:
+        status = _prompt_select('Status', active_statuses, default_status)
+
+    # Priority
+    if priority_default:
+        priority = default_priority
+    else:
+        priority = _prompt_select('Priority', priorities, default_priority)
+
+    # Category
+    if category_default:
+        category = default_category
+    else:
+        category = _prompt_select('Category', category_names, default_category)
+
+    # Key Resource
+    key_resource = ''
+    if not no_resource:
+        raw = click.prompt(
+            click.style('Key Resource', bold=True) + ' (URL, Enter to skip)',
+            default='',
+        )
+        key_resource = '' if raw in ('', '-') else raw
+
+    # Free-text fields
+    free_texts: dict[str, str] = {}
+    if not no_free_text:
+        for i, label in board_config.active_free_text_fields():
+            raw = click.prompt(
+                click.style(label, bold=True) + ' (Enter to skip)',
+                default='',
+            )
+            free_texts[f'free_text_{i + 1}'] = raw
+
+    now = now_str()
+    task = Task(
+        title=title,
+        category=category,
+        status=status,
+        priority=priority,
+        date_created=now,
+        date_modified=now,
+        due='',
+        key_resource=key_resource,
+        free_text_1=free_texts.get('free_text_1', ''),
+        free_text_2=free_texts.get('free_text_2', ''),
+        free_text_3=free_texts.get('free_text_3', ''),
+    )
+    add_task(data_dir, task)
+    print(f'✓ Task added: {title}')

knbn/config.py

@@ -0,0 +1,272 @@
+"""Data directory resolution, user settings, and board configuration."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+_ENV_VAR = 'KNBN_DATA_DIR'
+_DEFAULT_DIR = Path.home() / '.knbn'
+_SETTINGS_FILENAME = 'settings.json'
+_SETTINGS_TMP_FILENAME = '.settings.json.tmp'
+
+_HEX_COLOR_RE = re.compile(r'^#[0-9a-f]{6}$')
+NAME_MIN = 2
+NAME_MAX = 20
+
+CATEGORY_COLOR_PALETTE: list[str] = [
+    '#e879a0',
+    '#f4a7b9',
+    '#7ec8e3',
+    '#5b9bd5',
+    '#4dbfbf',
+    '#f5a623',
+    '#cccccc',
+    '#a78bfa',
+    '#34d399',
+    '#fbbf24',
+]
+
+
+class BoardConfigError(Exception):
+    """Raised when board configuration in settings.json is invalid."""
+
+
+@dataclass
+class CategoryConfig:
+    name: str
+    color: str
+
+
+@dataclass
+class BoardConfig:
+    active_statuses: list[str]
+    default_active_status: str
+    terminal_statuses: list[str]
+    default_terminal_status: str
+    priorities: list[str]
+    categories: list[CategoryConfig]
+    free_text_fields: list[str]
+
+    def category_color(self, name: str) -> str:
+        for cat in self.categories:
+            if cat.name == name:
+                return cat.color
+        return '#888888'
+
+    def active_free_text_fields(self) -> list[tuple[int, str]]:
+        return [(i, label) for i, label in enumerate(self.free_text_fields) if label]
+
+    def all_statuses(self) -> list[str]:
+        return self.active_statuses + self.terminal_statuses
+
+
+def load_default_board_config() -> dict[str, Any]:
+    """Return the board config block from the bundled defaults/settings.json."""
+    resource = files('knbn').joinpath('defaults/settings.json')
+    try:
+        raw = resource.read_text(encoding='utf-8')
+    except (FileNotFoundError, OSError) as exc:
+        raise RuntimeError(
+            f'knbn defaults file not found — package may be incomplete: {exc}'
+        ) from exc
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(
+            f'knbn defaults/settings.json is not valid JSON: {exc}'
+        ) from exc
+    return dict(data['board'])
+
+
+SETTINGS_DEFAULTS: dict[str, Any] = {
+    'app': {
+        'theme': 'textual-dark',
+        'deadline_warning_hours': '24',
+    },
+}
+
+
+def resolve_data_dir() -> Path:
+    env_val = os.environ.get(_ENV_VAR)
+    if env_val:
+        return Path(env_val)
+    return _DEFAULT_DIR
+
+
+def load_settings(data_dir: Path) -> dict[str, Any]:
+    settings_file = data_dir / _SETTINGS_FILENAME
+    result: dict[str, Any] = {
+        'app': dict(SETTINGS_DEFAULTS['app']),
+    }
+    if not settings_file.exists():
+        return result
+    try:
+        raw = json.loads(settings_file.read_text(encoding='utf-8'))
+        if isinstance(raw, dict):
+            if 'app' in raw and isinstance(raw['app'], dict):
+                result['app'].update(raw['app'])
+            if 'board' in raw:
+                result['board'] = raw['board']
+    except (json.JSONDecodeError, OSError):
+        pass
+    return result
+
+
+def save_settings(data_dir: Path, settings: dict[str, Any]) -> None:
+    tmp_file = data_dir / _SETTINGS_TMP_FILENAME
+    tmp_file.write_text(json.dumps(settings, indent=2), encoding='utf-8')
+    tmp_file.rename(data_dir / _SETTINGS_FILENAME)
+
+
+def get_app_setting(data_dir: Path, key: str, default: Any = '') -> Any:
+    settings = load_settings(data_dir)
+    return settings.get('app', {}).get(key, default)
+
+
+def _validate_name(value: str, field: str) -> None:
+    if not (NAME_MIN <= len(value) <= NAME_MAX):
+        raise BoardConfigError(
+            f'{field} name {value!r} must be between {NAME_MIN} and {NAME_MAX} characters'
+        )
+
+
+def build_default_board_config() -> BoardConfig:
+    d = load_default_board_config()
+    categories = [
+        CategoryConfig(name=c['name'], color=c['color']) for c in d['categories']
+    ]
+    return BoardConfig(
+        active_statuses=list(d['active_statuses']),
+        default_active_status=d['default_active_status'],
+        terminal_statuses=list(d['terminal_statuses']),
+        default_terminal_status=d['default_terminal_status'],
+        priorities=list(d['priorities']),
+        categories=categories,
+        free_text_fields=_parse_free_text_fields(d),
+    )
+
+
+def _parse_active_statuses(board: dict[str, Any]) -> tuple[list[str], str]:
+    active = board.get('active_statuses', [])
+    if not isinstance(active, list) or not (2 <= len(active) <= 5):
+        raise BoardConfigError(
+            f'active_statuses must have 2-5 entries, got '
+            f'{len(active) if isinstance(active, list) else "invalid"}'
+        )
+    for name in active:
+        _validate_name(str(name), 'active_statuses')
+    default = board.get('default_active_status', '')
+    if default not in active:
+        raise BoardConfigError(
+            f'default_active_status {default!r} not found in active_statuses'
+        )
+    return [str(s) for s in active], str(default)
+
+
+def _parse_terminal_statuses(board: dict[str, Any]) -> tuple[list[str], str]:
+    terminal = board.get('terminal_statuses', [])
+    if not isinstance(terminal, list) or not (1 <= len(terminal) <= 3):
+        raise BoardConfigError(
+            f'terminal_statuses must have 1-3 entries, got '
+            f'{len(terminal) if isinstance(terminal, list) else "invalid"}'
+        )
+    for name in terminal:
+        _validate_name(str(name), 'terminal_statuses')
+    default = board.get('default_terminal_status', '')
+    if default not in terminal:
+        raise BoardConfigError(
+            f'default_terminal_status {default!r} not found in terminal_statuses'
+        )
+    return [str(s) for s in terminal], str(default)
+
+
+def _parse_priorities(board: dict[str, Any]) -> list[str]:
+    priorities = board.get('priorities', [])
+    if not isinstance(priorities, list) or not (1 <= len(priorities) <= 5):
+        raise BoardConfigError(
+            f'priorities must have 1-5 entries, got '
+            f'{len(priorities) if isinstance(priorities, list) else "invalid"}'
+        )
+    for name in priorities:
+        _validate_name(str(name), 'priorities')
+    return [str(p) for p in priorities]
+
+
+def _parse_categories(board: dict[str, Any]) -> list[CategoryConfig]:
+    raw_cats = board.get('categories', [])
+    if not isinstance(raw_cats, list) or not (1 <= len(raw_cats) <= 10):
+        raise BoardConfigError(
+            f'categories must have 1-10 entries, got '
+            f'{len(raw_cats) if isinstance(raw_cats, list) else "invalid"}'
+        )
+    categories: list[CategoryConfig] = []
+    for cat in raw_cats:
+        if not isinstance(cat, dict):
+            raise BoardConfigError(
+                'each category must be a JSON object with name and color'
+            )
+        cat_name = str(cat.get('name', ''))
+        cat_color = str(cat.get('color', ''))
+        _validate_name(cat_name, 'categories')
+        if not _HEX_COLOR_RE.match(cat_color):
+            raise BoardConfigError(
+                f'category color {cat_color!r} must match #[0-9a-f]{{6}}'
+            )
+        categories.append(CategoryConfig(name=cat_name, color=cat_color))
+    return categories
+
+
+def _parse_free_text_fields(board: dict[str, Any]) -> list[str]:
+    raw = board.get('free_text_fields', [])
+    if not isinstance(raw, list) or len(raw) > 3:
+        raise BoardConfigError(
+            f'free_text_fields must have 0-3 entries, got '
+            f'{len(raw) if isinstance(raw, list) else "invalid"}'
+        )
+    fields: list[str] = []
+    for label in raw:
+        label_str = str(label)
+        if label_str and not (NAME_MIN <= len(label_str) <= NAME_MAX):
+            raise BoardConfigError(
+                f'free_text_fields label {label_str!r} must be between '
+                f'{NAME_MIN} and {NAME_MAX} characters'
+            )
+        fields.append(label_str)
+    while len(fields) < 3:
+        fields.append('')
+    return fields
+
+
+def load_board_config(data_dir: Path) -> BoardConfig:
+    settings_file = data_dir / _SETTINGS_FILENAME
+    if not settings_file.exists():
+        return build_default_board_config()
+    try:
+        raw = json.loads(settings_file.read_text(encoding='utf-8'))
+        if not isinstance(raw, dict) or 'board' not in raw:
+            return build_default_board_config()
+        board = raw['board']
+    except (json.JSONDecodeError, OSError):
+        return build_default_board_config()
+    if not isinstance(board, dict):
+        raise BoardConfigError('board block must be a JSON object')
+    active, default_active = _parse_active_statuses(board)
+    terminal, default_terminal = _parse_terminal_statuses(board)
+    priorities = _parse_priorities(board)
+    categories = _parse_categories(board)
+    free_text_fields = _parse_free_text_fields(board)
+    return BoardConfig(
+        active_statuses=active,
+        default_active_status=default_active,
+        terminal_statuses=terminal,
+        default_terminal_status=default_terminal,
+        priorities=priorities,
+        categories=categories,
+        free_text_fields=free_text_fields,
+    )