twd-m4sc0 2.0.3__tar.gz → 3.0.1__tar.gz

twd_m4sc0-3.0.1/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: twd-m4sc0
+Version: 3.0.1
+Summary: TWD by m4sc0
+Author: m4sc0
+License: MIT
+Project-URL: Homepage, https://github.com/m4sc0/twd
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Requires-Dist: click>=8
+Requires-Dist: textual>=7.2
+Requires-Dist: pydantic>=2.12

twd_m4sc0-3.0.1/README.md

@@ -0,0 +1,34 @@
+# twd-m4sc0
+
+> [!IMPORTANT]
+> This is complete rewrite of the program `twd`. If you're using `<=v2.0.3` please make sure to upgrade to the newest major release. The archived version v2 can be viewed [here](https://github.com/m4sc0/twd-archived).
+
+> twd-m4sc0 / twd is a command-line tool that allows you to temporarily save a working directory and easily navigate back to it. It's designed for developers and users who frequently need to switch between directories in the terminal.
+
+That's what it was supposed to do at the start. Now it's more like a hub for your frequently visited directories. You can use it like a bookmark manager or for the quickest method of changing between directories that you can find.
+
+There are quite a few things I wanna make better this time.
+
+### Better directory changing
+
+Previously twd wrote to a temp file, then a bash function used the contents if that file exists, cd's to the dir and deletes the file again. This time around I'm going a different way. I found the method `os.write(3, path)` which can write to [file descriptors](https://en.wikipedia.org/wiki/File_descriptor) directly. This is the same way stdout and stderr are handled in the background (i think). But i'm using a fourth (0 = stdin, 1 = stdout, 2 = stderr), unused FD to write to. This is then captured in the bash function separately from the stdout. 
+
+### Improved TUI
+
+For some reason I thought writing a whole UI system using [curses](https://de.wikipedia.org/wiki/Curses) was a good idea. Well, now at least I know better and can say that I won't do that ever again.
+
+I'll use [Textual](https://textual.textualize.io/) now.
+
+### Setup
+
+It's possible to use TWD without the feature of cd'ing anywhere. But that's kinda lame lol. To make sure it works as intended, copy the following snippet into something like a `~/.bashrc` file.
+
+```bash
+t () {
+  binary="twd"
+  local target=$($binary "$@" 3>&1 >/dev/tty)
+  if [[ -n "$target" && -d "$target" ]]; then
+    cd "$target"
+  fi
+}
+```

twd_m4sc0-3.0.1/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "twd-m4sc0"
+version = "3.0.1"
+description = "TWD by m4sc0"
+authors = [{name = "m4sc0"}]
+requires-python = ">=3.13"
+license = {text = "MIT"}
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+  "click>=8",
+  "textual>=7.2",
+  "pydantic>=2.12"
+]
+
+[project.urls]
+Homepage = "https://github.com/m4sc0/twd"
+
+[project.scripts]
+twd = "twd.cli:cli"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+

twd_m4sc0-3.0.1/src/twd/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("twd")
+except PackageNotFoundError as e:
+    __version__ = "unknown"

twd_m4sc0-3.0.1/src/twd/cli.py

@@ -0,0 +1,104 @@
+import click
+import os
+from pathlib import Path
+from . import __version__
+from .config import Config
+from .data import TwdManager
+from .tui import TWDApp
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+@click.version_option(version=__version__)
+def cli(ctx):
+    """
+    TWD - Temp / Tracked Working Directory
+    """
+    ctx.ensure_object(dict)
+
+    ctx.obj['config'] = Config.load() # load config
+    ctx.obj['manager'] = TwdManager(ctx.obj['config'].data_path)
+
+    # if no subcommand was provided, launch TUI
+    if ctx.invoked_subcommand is None:
+        # TODO: launch TUI here
+
+        path = TWDApp(manager=ctx.obj['manager']).run()
+
+        # write to fd3
+        os.write(3, bytes(str(path), "utf-8"))
+
+        pass
+
+@cli.command()
+@click.argument('path')
+@click.argument('alias', required=False)
+@click.argument('name', required=False)
+@click.pass_context
+def save(ctx, path, alias, name):
+    """
+    Save a new twd with PATH, [opt] ALIAS and [opt] NAME
+    """
+    manager: TwdManager = ctx.obj['manager']
+
+    path_obj = Path(path).expanduser().resolve()
+
+    # get alias from path
+    if alias is None:
+        alias = path_obj.name.lower().replace(" ", "_")
+
+    try:
+        entry = manager.add(alias, path_obj, name)
+        click.echo(f"Saved '{entry.alias}' -> {entry.path}")
+    except ValueError as e:
+        click.echo(f"Error: {e}")
+        raise click.Abort()
+
+@cli.command()
+@click.argument('alias')
+@click.pass_context
+def get(ctx, alias):
+    """
+    get path for ALIAS
+    """
+    manager = ctx.obj['manager']
+
+    entry = manager.get(alias)
+
+    if entry is None:
+        click.echo(f"Alias '{alias}' not found")
+        raise click.Abort()
+
+    # TODO: os.write(3) / write to fd3 for shell integration
+    os.write(3, bytes(str(entry.path), "utf-8"))
+
+    click.echo(f"cd-ing to {entry.path}")
+
+@cli.command()
+@click.argument('alias')
+@click.pass_context
+def remove(ctx, alias):
+    """
+    remove TWD by ALIAS
+    """
+    manager = ctx.obj['manager']
+    
+    try:
+        manager.remove(alias)
+        click.echo(f"Removed '{alias}'")
+    except KeyError as e:
+        click.echo(f"{e}", err=True)
+        raise click.Abort()
+
+@cli.command('list')
+@click.pass_context
+def list_twds(ctx):
+    """List all TWDs"""
+    manager = ctx.obj['manager']
+    
+    entries = manager.list_all()
+    if not entries:
+        click.echo("No TWDs saved yet. Use 'twd save <path> <alias>' to add one.")
+        return
+    
+    for entry in entries:
+        click.echo(f"{entry.alias:20} {entry.name:30} {entry.path}")

twd_m4sc0-3.0.1/src/twd/config.py

@@ -0,0 +1,76 @@
+
+
+from pathlib import Path
+from pydantic import BaseModel, Field, validator
+import json
+import os
+import sys
+
+def get_config_path() -> Path:
+    """Cross-platform config location"""
+
+    if sys.platform == "win32":
+        base = Path(os.getenv("APPDATA", Path.home() / "AppData" / "Local"))
+    else:
+        base = Path(os.getenv("XDG_CONFIG_HOME", Path.home() / ".config"))
+
+    config_dir = base / "twd"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    
+    return config_dir / "config.json"
+
+def get_data_path() -> Path:
+    """Cross-platform data location"""
+
+    if sys.platform == "win32":
+        base = Path(os.getenv("APPDATA", Path.home() / "AppData" / "Local"))
+    else:
+        base = Path(os.getenv("XDG_DATA_HOME", Path.home() / ".local" / "share"))
+
+    data_dir = base / "twd"
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    return data_dir / "data.csv"
+
+class Config(BaseModel):
+    """App configuration"""
+
+    data_path: Path = Field(default_factory=get_data_path)
+    
+    @validator("data_path")
+    def validate_path(cls, v):
+        """Expand home and ensure path exists"""
+
+        path = Path(v).expanduser()
+        if not path.exists():
+            path = get_data_path()
+        return path
+
+    @classmethod
+    def load(cls) -> "Config":
+        """Load config from file, create with defaults"""
+        config_file = get_config_path()
+
+        if not config_file.exists():
+            config = cls()
+            config.save()
+            return config
+
+        try:
+            with open(config_file, "rb") as f:
+                data = json.load(f)
+
+            return cls(**data)
+        except Exception as e:
+            print(f"Warning: config file corrupted, using defaults: {e}")
+            return cls()
+
+    def save(self) -> None:
+        """save config to file"""
+
+        config_file = get_config_path()
+        
+        data = self.model_dump(mode="json")
+
+        with open(config_file, 'w') as f:
+            json.dump(data, f, indent=2)

twd_m4sc0-3.0.1/src/twd/data.py

@@ -0,0 +1,143 @@
+import csv
+
+from pathlib import Path
+from pydantic import BaseModel, Field, validator
+from typing import List, Optional
+from datetime import datetime
+
+from .config import Config
+from .utils import search
+
+class Entry(BaseModel):
+    """Data class for a signle TWD Entry"""
+    
+    alias: str = Field(..., min_length=2, max_length=64)
+    path: Path
+    name: str = Field(..., min_length=3)
+    created_at: datetime = Field(default_factory=datetime.now)
+
+    @validator("alias")
+    def validate_alias(cls, v):
+        if not v.replace("_", "").replace("-", "").isalnum():
+            raise ValueError("Alias must be alphanumeric with - or _")
+
+        return v.lower()
+
+    @validator("path")
+    def validate_path(cls, v):
+        path = Path(v).expanduser().resolve()
+
+        if not path.exists():
+            raise ValueError(f"Path does not exist: {path}")
+        if not path.is_dir():
+            raise ValueError(f"Path is not a directory: {path}")
+        return path
+
+    def to_csv(self) -> List[str]:
+        """Convert to csv row"""
+        return [
+                self.alias,
+                str(self.path),
+                self.name,
+                self.created_at.isoformat()
+                ]
+
+    @classmethod
+    def from_csv(cls, row: List[str]) -> "Entry":
+        """create from csv row"""
+        return cls(
+                alias=row[0],
+                path=Path(row[1]),
+                name=row[2],
+                created_at=datetime.fromisoformat(row[3])
+                )
+
+class TwdManager:
+    """twd entry manager stored in csv"""
+
+    CSV_HEADERS = ["alias", "path", "name", "created_at"]
+
+    def __init__(self, csv_path: Path):
+        self.csv_path = csv_path
+        self._ensure_csv_exists()
+        self.cwd = str(Path.cwd())
+
+    def _ensure_csv_exists(self) -> None:
+        """create csv headers"""
+        if not self.csv_path.exists():
+            self.csv_path.parent.mkdir(parents=True, exist_ok=True) 
+
+            with open(self.csv_path, 'w', newline='') as f:
+                writer = csv.writer(f)
+                writer.writerow(self.CSV_HEADERS)
+
+    def _read_all(self) -> List[Entry]:
+        """read all entries"""
+        entries = []
+
+        with open(self.csv_path, 'r', newline='') as f:
+            reader = csv.reader(f)
+
+            next(reader) # skip headers
+
+            for row in reader:
+                try:
+                    entries.append(Entry.from_csv(row))
+                except Exception as e:
+                    print(f"Warning: skipping invalid row: {e}")
+
+        return entries
+
+    def _write_all(self, entries: List[Entry]) -> None:
+        with open(self.csv_path, 'w', newline='') as f:
+            writer = csv.writer(f)
+            writer.writerow(self.CSV_HEADERS)
+
+            for entry in entries:
+                writer.writerow(entry.to_csv())
+
+    def add(self, alias: str, path: Path, name: Optional[str] = None) -> Entry:
+        """Add new entry"""
+        entries = self._read_all()
+
+        if any(e.alias == alias.lower() for e in entries):
+            raise ValueError(f"Alias '{alias}' already exists")
+
+        if name is None:
+            name = Path(path).name
+
+        entry = Entry(alias=alias, path=path, name=name)
+        entries.append(entry)
+        self._write_all(entries)
+
+        return entry
+
+    def get(self, alias: str) -> Optional[Entry]:
+        """get entry by alias"""
+        entries = self._read_all()
+
+        for entry in entries:
+            if entry.alias == alias.lower():
+                return entry
+
+        return None
+
+    def remove(self, alias: str) -> None:
+        """remove entry by alias"""
+        entries = self._read_all()
+        original_len = len(entries)
+
+        entries = [e for e in entries if e.alias != alias.lower()]
+
+        if len(entries) == original_len:
+            raise KeyError(f"Alias '{alias}' not found")
+
+        self._write_all(entries)
+
+    def list_all(self) -> List[Entry]:
+        entries = self._read_all()
+
+        return sorted(entries, key=lambda e: e.created_at)
+
+    def exists(self, alias: str) -> bool:
+        return self.get(alias) is not None

twd_m4sc0-3.0.1/src/twd/tui.py

@@ -0,0 +1,217 @@
+from enum import Enum
+from textual import on
+from textual.app import App, ComposeResult, Binding
+from textual.containers import HorizontalGroup, VerticalScroll
+from textual.reactive import reactive
+from textual.widgets import Button, Digits, Footer, Header, DataTable, Label, Rule, Input
+from textual.color import Color
+
+from twd.config import Config
+from twd.data import TwdManager
+from twd.utils import search, linear_search
+
+class Mode(Enum):
+    NORMAL = "normal"
+    SEARCH = "search"
+
+class TWDApp(App):
+    """
+    TWD TUI Application
+    """
+
+    CSS_PATH = "tui.tcss"
+
+    BINDINGS = [
+            # motion
+            Binding("j", "cursor_down", "Down"),
+            Binding("k", "cursor_up", "Up"),
+
+            # modify
+            Binding("/", "enter_search_mode", "Search"),
+            Binding("escape", "enter_normal_mode", "Normal", show=False),
+            # TODO: edit
+            # TODO: rename
+
+            # select
+            Binding("enter", "select", "Select"),
+
+            # exit
+            Binding("q", "exit", "Exit"),
+        ]
+
+    mode: Mode = reactive(Mode.NORMAL)
+
+    def __init__(self, manager: TwdManager, *args, **kwargs):
+        self.manager = manager
+        super().__init__(*args, **kwargs)
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=True)
+        yield Footer()
+
+        # cwd
+        yield Label(f"cwd: {self.manager.cwd}", classes="cwd")
+
+        yield Input(placeholder="Search...", id="search-input")
+
+        # twd selection table
+        yield DataTable(
+                cursor_type='row',
+                cell_padding=2,
+                # zebra_stripes=True,
+                id="data",
+                )
+
+    def on_mount(self) -> None:
+        # app config
+        self.theme = "flexoki"
+        self.title = "TWD"
+        self.sub_title = "Tracked Working Directory"
+
+        search_input = self.query_one("#search-input", Input)
+        search_input.display = False
+        
+        self._populate_table()
+
+    def _populate_table(self, entries=None) -> None:
+        """
+        fill or refresh data table
+        """
+        table = self.query_one(DataTable)
+        table.clear(columns=True)
+
+        # add headers
+        table.add_columns(*self.manager.CSV_HEADERS)
+
+        if entries is None:
+            entries = self.manager.list_all()
+        
+        # fill data
+        for entry in entries:
+            table.add_row(entry.alias, str(entry.path), entry.name, entry.created_at)
+
+    def watch_mode(self, old_mode: Mode, new_mode: Mode) -> None:
+        """
+        react to mode changes
+        """
+        search_input = self.query_one("#search-input", Input)
+        table = self.query_one(DataTable)
+
+        if new_mode == Mode.SEARCH:
+            # enter search mode
+            search_input.display = True
+            search_input.value = ""
+            search_input.focus()
+            self.sub_title = "Tracked Working Directory — SEARCH"
+        elif new_mode == Mode.NORMAL:
+            # enter normal mode
+            search_input.display = False
+            search_input.value = ""
+            self._populate_table()
+            table.focus()
+            self.sub_title = "Tracked Working Directory"
+
+    # actions
+    def action_cursor_down(self) -> None:
+        """
+        move cursor down
+        """
+        table = self.query_one(DataTable)
+
+        current_row = table.cursor_coordinate.row
+        next_row = (current_row + 1) % table.row_count
+
+        table.move_cursor(row=next_row)
+
+    def action_cursor_up(self) -> None:
+        """
+        move cursor up
+        """
+        table = self.query_one(DataTable)
+        
+        current_row = table.cursor_coordinate.row
+        prev_row = (current_row - 1) % table.row_count
+
+        table.move_cursor(row=prev_row)
+
+    def action_enter_search_mode(self) -> None:
+        """
+        enter search mode
+        """
+        if self.mode == Mode.SEARCH:
+            return
+        self.mode = Mode.SEARCH
+
+    def action_enter_normal_mode(self) -> None:
+        """
+        enter normal mode
+        """
+        if self.mode == Mode.NORMAL:
+            return
+        self.mode = Mode.NORMAL
+
+    def action_exit(self) -> None:
+        self.exit()
+
+    @on(Input.Changed, "#search-input")
+    def on_search_input_changed(self, e: Input.Changed) -> None:
+        """
+        filter table as user types
+        """
+        if self.mode != Mode.SEARCH:
+            return
+
+        query = e.value
+
+        all_entries = self.manager.list_all()
+
+        # TODO: filter entries and repopulate table
+
+        search_result = linear_search(query, all_entries)
+
+        filtered = [entry for entry in all_entries if entry.alias in search_result]
+
+        self._populate_table(filtered)
+
+    @on(Input.Submitted, "#search-input")
+    def on_search_submitted(self, e: Input.Submitted) -> None:
+        """
+        when user presses enter in search, return to normal mode
+        """
+        if self.mode != Mode.SEARCH:
+            return
+
+        self.mode = Mode.NORMAL
+
+        self.query_one(DataTable).focus()
+
+
+    @on(DataTable.RowSelected)
+    def on_data_table_row_selected(self, event: DataTable.RowSelected) -> None:
+        """
+        select row and send back to the original program (probably cli)
+        """
+        table = event.data_table
+        row_key = event.row_key
+
+        # get row
+        row_data = table.get_row(row_key)
+        alias = row_data[0]
+
+        # get entry
+        entry = self.manager.get(alias)
+
+        self.notify(f"Selected: {entry.alias} -> {entry.path}")
+
+        # return selected path to cli
+        self.exit(entry.path) 
+
+if __name__ == "__main__":
+    # made sure it works with 'serve'
+    config = Config.load()
+    manager = TwdManager(config.data_path)
+
+    app = TWDApp(manager=manager)
+    path = app.run()
+
+    print(path)

twd_m4sc0-3.0.1/src/twd/utils.py

@@ -0,0 +1,46 @@
+from rapidfuzz import fuzz
+from typing import List
+
+FUZZY_THRESHOLD = 50
+
+def normalize(name) -> str:
+    return name.lower().replace('-', ' ').replace('_', ' ')
+
+def search(query, items, threshold = 50) -> List:
+    """
+    query: search input
+    items: list of (alias, name)
+
+    returns: list of (alias, name, score)
+    """
+
+    # return all items if query is empty
+    if not query:
+        return [(alias, name, 100) for alias, name in items]
+
+    normalized_query = normalize(query)
+    results = []
+
+    # filtering
+    for alias, name in items:
+        alias_score = fuzz.WRatio(normalized_query, normalize(alias))
+        name_score = fuzz.WRatio(normalized_query, normalize(name))
+
+        # choose higher score
+        best_score = max(alias_score, name_score)
+
+        # filter out low scores
+        if best_score >= threshold:
+            results.append((alias, name, best_score))
+
+    results.sort(key=lambda x: x[2], reverse=True)
+
+    return results
+
+def linear_search(query, items) -> List:
+    """
+    simple substring search
+    """
+    result = [entry.alias for entry in items if query in entry.alias]
+
+    return result

twd_m4sc0-3.0.1/src/twd_m4sc0.egg-info/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: twd-m4sc0
+Version: 3.0.1
+Summary: TWD by m4sc0
+Author: m4sc0
+License: MIT
+Project-URL: Homepage, https://github.com/m4sc0/twd
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Requires-Dist: click>=8
+Requires-Dist: textual>=7.2
+Requires-Dist: pydantic>=2.12