jobhound 0.2.0__tar.gz

jobhound-0.2.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.3
+Name: jobhound
+Version: 0.2.0
+Summary: Action-based CLI for tracking a job hunt
+Requires-Dist: cyclopts==4.11.2
+Requires-Dist: questionary>=2.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: rich>=13
+Requires-Dist: xdg-base-dirs>=6
+Requires-Python: >=3.13

jobhound-0.2.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "jobhound"
+version = "0.2.0"
+description = "Action-based CLI for tracking a job hunt"
+requires-python = ">=3.13"
+dependencies = [
+    "cyclopts==4.11.2",
+    "questionary>=2.0",
+    "tomli-w>=1.0",
+    "rich>=13",
+    "xdg-base-dirs>=6",
+]
+
+[project.scripts]
+jh = "jobhound.cli:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.6",
+    "ty>=0.0.1a8",
+    "pytest-cov>=5",
+]
+
+[build-system]
+requires = ["uv_build>=0.4,<0.12"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.ty.rules]
+# strict-by-default; tighten as needed
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"

jobhound-0.2.0/src/jobhound/__init__.py

@@ -0,0 +1,3 @@
+"""jh — action-based CLI for tracking a job hunt."""
+
+__version__ = "0.2.0"

jobhound-0.2.0/src/jobhound/cli.py

@@ -0,0 +1,48 @@
+"""The `jh` CLI entry point. Commands are registered explicitly below."""
+
+from __future__ import annotations
+
+from cyclopts import App
+
+from jobhound import __version__
+from jobhound.commands import accept as cmd_accept
+from jobhound.commands import apply as cmd_apply
+from jobhound.commands import archive as cmd_archive
+from jobhound.commands import contact as cmd_contact
+from jobhound.commands import decline as cmd_decline
+from jobhound.commands import delete as cmd_delete
+from jobhound.commands import edit as cmd_edit
+from jobhound.commands import ghost as cmd_ghost
+from jobhound.commands import link as cmd_link
+from jobhound.commands import list_ as cmd_list
+from jobhound.commands import log as cmd_log
+from jobhound.commands import new as cmd_new
+from jobhound.commands import note as cmd_note
+from jobhound.commands import priority as cmd_priority
+from jobhound.commands import sync as cmd_sync
+from jobhound.commands import tag as cmd_tag
+from jobhound.commands import withdraw as cmd_withdraw
+
+app = App(
+    name="jh",
+    help="Action-based CLI for tracking a job hunt.",
+    version=__version__,
+)
+
+app.command(cmd_new.run, name="new")
+app.command(cmd_apply.run, name="apply")
+app.command(cmd_log.run, name="log")
+app.command(cmd_withdraw.run, name="withdraw")
+app.command(cmd_ghost.run, name="ghost")
+app.command(cmd_accept.run, name="accept")
+app.command(cmd_decline.run, name="decline")
+app.command(cmd_note.run, name="note")
+app.command(cmd_priority.run, name="priority")
+app.command(cmd_tag.run, name="tag")
+app.command(cmd_link.run, name="link")
+app.command(cmd_contact.run, name="contact")
+app.command(cmd_list.run, name="list")
+app.command(cmd_edit.run, name="edit")
+app.command(cmd_archive.run, name="archive")
+app.command(cmd_delete.run, name="delete")
+app.command(cmd_sync.run, name="sync")

jobhound-0.2.0/src/jobhound/commands/_terminal.py

@@ -0,0 +1,43 @@
+"""Shared logic for terminal-status verbs (withdraw, ghost, accept, decline)."""
+
+from __future__ import annotations
+
+import sys
+from datetime import date
+
+from jobhound.config import load_config
+from jobhound.opportunities import Opportunity
+from jobhound.paths import paths_from_config
+from jobhound.repository import OpportunityRepository
+from jobhound.transitions import InvalidTransitionError
+
+_METHODS = {
+    "withdraw": Opportunity.withdraw,
+    "ghost": Opportunity.ghost,
+    "accept": Opportunity.accept,
+    "decline": Opportunity.decline,
+}
+
+
+def run_transition(
+    *,
+    slug_query: str,
+    verb: str,
+    today: str | None,
+    no_commit: bool,
+) -> None:
+    """Move an opportunity to its terminal status via the entity method."""
+    cfg = load_config()
+    repo = OpportunityRepository(paths_from_config(cfg), cfg)
+    today_date = date.fromisoformat(today) if today else date.today()
+    opp, opp_dir = repo.find(slug_query)
+
+    method = _METHODS[verb]
+    try:
+        updated = method(opp, today=today_date)
+    except InvalidTransitionError as exc:
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(1) from exc
+
+    repo.save(updated, opp_dir, message=f"{verb}: {opp.slug}", no_commit=no_commit)
+    print(f"{verb}: {opp.slug}")

jobhound-0.2.0/src/jobhound/commands/accept.py

@@ -0,0 +1,25 @@
+"""`jh accept` — accepted offer, status → accepted."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import Parameter
+
+from jobhound.commands._terminal import run_transition
+
+
+def run(
+    slug_query: str,
+    /,
+    *,
+    today: Annotated[str | None, Parameter(show=False)] = None,
+    no_commit: Annotated[bool, Parameter(negative=())] = False,
+) -> None:
+    """Accept the offer."""
+    run_transition(
+        slug_query=slug_query,
+        verb="accept",
+        today=today,
+        no_commit=no_commit,
+    )

jobhound-0.2.0/src/jobhound/commands/apply.py

@@ -0,0 +1,48 @@
+"""`jh apply` — submitted application, status → applied."""
+
+from __future__ import annotations
+
+import sys
+from datetime import date
+from typing import Annotated
+
+from cyclopts import Parameter
+
+from jobhound.config import load_config
+from jobhound.paths import paths_from_config
+from jobhound.repository import OpportunityRepository
+from jobhound.transitions import InvalidTransitionError
+
+
+def run(
+    slug_query: str,
+    /,
+    *,
+    on: str | None = None,
+    next_action: str,
+    next_action_due: str,
+    today: Annotated[str | None, Parameter(show=False)] = None,
+    no_commit: Annotated[bool, Parameter(negative=())] = False,
+) -> None:
+    """Mark the application as submitted."""
+    cfg = load_config()
+    repo = OpportunityRepository(paths_from_config(cfg), cfg)
+
+    today_date = date.fromisoformat(today) if today else date.today()
+    applied_on = date.fromisoformat(on) if on else today_date
+    due = date.fromisoformat(next_action_due)
+
+    opp, opp_dir = repo.find(slug_query)
+    try:
+        updated = opp.apply(
+            applied_on=applied_on,
+            today=today_date,
+            next_action=next_action,
+            next_action_due=due,
+        )
+    except InvalidTransitionError as exc:
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(1) from exc
+
+    repo.save(updated, opp_dir, message=f"apply: {opp.slug}", no_commit=no_commit)
+    print(f"applied: {opp.slug}")

jobhound-0.2.0/src/jobhound/commands/archive.py

@@ -0,0 +1,32 @@
+"""`jh archive` — move <slug> from opportunities/ to archive/."""
+
+from __future__ import annotations
+
+import sys
+from typing import Annotated
+
+from cyclopts import Parameter
+
+from jobhound.config import load_config
+from jobhound.paths import Paths, paths_from_config
+from jobhound.repository import OpportunityRepository
+
+
+def run(
+    slug_query: str,
+    /,
+    *,
+    no_commit: Annotated[bool, Parameter(negative=())] = False,
+) -> None:
+    """Move an opportunity to the archive directory."""
+    cfg = load_config()
+    paths = paths_from_config(cfg)
+    Paths.ensure(paths)
+    repo = OpportunityRepository(paths, cfg)
+    _, opp_dir = repo.find(slug_query)
+    try:
+        repo.archive(opp_dir, no_commit=no_commit)
+    except FileExistsError as exc:
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(1) from exc
+    print(f"archived: {opp_dir.name}")

jobhound-0.2.0/src/jobhound/commands/contact.py

@@ -0,0 +1,39 @@
+"""`jh contact` — append a contact entry."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import Parameter
+
+from jobhound.config import load_config
+from jobhound.contact import Contact
+from jobhound.paths import paths_from_config
+from jobhound.repository import OpportunityRepository
+
+
+def run(
+    slug_query: str,
+    /,
+    *,
+    name: str,
+    role_title: str | None = None,
+    channel: str | None = None,
+    company: str | None = None,
+    note: str | None = None,
+    no_commit: Annotated[bool, Parameter(negative=())] = False,
+) -> None:
+    """Add a contact to the contacts list."""
+    contact = Contact(
+        name=name,
+        role=role_title,
+        channel=channel,
+        company=company,
+        note=note,
+    )
+    cfg = load_config()
+    repo = OpportunityRepository(paths_from_config(cfg), cfg)
+    opp, opp_dir = repo.find(slug_query)
+    updated = opp.with_contact(contact)
+    repo.save(updated, opp_dir, message=f"contact: {opp.slug} {name}", no_commit=no_commit)
+    print(f"contact added: {opp.slug} {name}")

jobhound-0.2.0/src/jobhound/commands/decline.py

@@ -0,0 +1,25 @@
+"""`jh decline` — declined offer, status → declined."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import Parameter
+
+from jobhound.commands._terminal import run_transition
+
+
+def run(
+    slug_query: str,
+    /,
+    *,
+    today: Annotated[str | None, Parameter(show=False)] = None,
+    no_commit: Annotated[bool, Parameter(negative=())] = False,
+) -> None:
+    """Decline the offer."""
+    run_transition(
+        slug_query=slug_query,
+        verb="decline",
+        today=today,
+        no_commit=no_commit,
+    )

jobhound-0.2.0/src/jobhound/commands/delete.py

@@ -0,0 +1,36 @@
+"""`jh delete` — remove an opportunity directory."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import questionary
+from cyclopts import Parameter
+
+from jobhound.config import load_config
+from jobhound.paths import paths_from_config
+from jobhound.repository import OpportunityRepository
+
+
+def run(
+    slug_query: str,
+    /,
+    *,
+    yes: bool = False,
+    no_commit: Annotated[bool, Parameter(negative=())] = False,
+) -> None:
+    """Delete an opportunity directory (e.g. a duplicate scaffold).
+
+    --yes: skip the confirmation prompt.
+    """
+    cfg = load_config()
+    repo = OpportunityRepository(paths_from_config(cfg), cfg)
+    _, opp_dir = repo.find(slug_query)
+    if not yes:
+        confirm = questionary.confirm(f"Delete {opp_dir.name}?", default=False).ask()
+        if not confirm:
+            print("aborted")
+            raise SystemExit(1)
+    name = opp_dir.name
+    repo.delete(opp_dir, no_commit=no_commit)
+    print(f"deleted: {name}")

jobhound-0.2.0/src/jobhound/commands/edit.py

@@ -0,0 +1,81 @@
+"""`jh edit` — open meta.toml in $EDITOR with validation loop."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+from pathlib import Path
+from typing import Annotated
+
+from cyclopts import Parameter
+
+from jobhound.config import load_config
+from jobhound.meta_io import ValidationError, read_meta
+from jobhound.paths import paths_from_config
+from jobhound.repository import OpportunityRepository
+
+_ERROR_PREFIX = "# ERROR:"
+
+
+def _editor_argv(cfg_editor: str) -> list[str]:
+    raw = cfg_editor or os.environ.get("EDITOR") or "vi"
+    return shlex.split(raw)
+
+
+def _strip_error_block(text: str) -> str:
+    lines = text.splitlines(keepends=True)
+    idx = 0
+    while idx < len(lines) and lines[idx].startswith(_ERROR_PREFIX):
+        idx += 1
+    if idx == 0:
+        return text
+    if idx < len(lines) and lines[idx].rstrip() == "#":
+        idx += 1
+    if idx < len(lines) and lines[idx].strip() == "":
+        idx += 1
+    return "".join(lines[idx:])
+
+
+def _prepend_error(path: Path, message: str) -> None:
+    body = _strip_error_block(path.read_text())
+    block = "".join(f"{_ERROR_PREFIX} {line}\n" for line in message.splitlines())
+    path.write_text(f"{block}#\n{body}")
+
+
+def _open_editor(argv: list[str], path: Path) -> None:
+    subprocess.run([*argv, str(path)], check=True)
+
+
+def run(
+    slug_query: str,
+    /,
+    *,
+    no_commit: Annotated[bool, Parameter(negative=())] = False,
+) -> None:
+    """Open meta.toml in $EDITOR; validate on save; rename on slug change."""
+    cfg = load_config()
+    repo = OpportunityRepository(paths_from_config(cfg), cfg)
+    _, opp_dir = repo.find(slug_query)
+    meta = opp_dir / "meta.toml"
+    editor_argv = _editor_argv(cfg.editor)
+
+    while True:
+        before = meta.read_text()
+        _open_editor(editor_argv, meta)
+        after = meta.read_text()
+        if after == before:
+            print("No changes.")
+            return
+        try:
+            opp = read_meta(meta)
+        except ValidationError as exc:
+            _prepend_error(meta, str(exc))
+            continue
+        cleaned = _strip_error_block(meta.read_text())
+        if cleaned != after:
+            meta.write_text(cleaned)
+            opp = read_meta(meta)
+        final_dir = repo.save(opp, opp_dir, message=f"edit: {opp.slug}", no_commit=no_commit)
+        print(f"Updated {final_dir.relative_to(repo.paths.db_root)}")
+        return

jobhound-0.2.0/src/jobhound/commands/ghost.py

@@ -0,0 +1,25 @@
+"""`jh ghost` — no response, status → ghosted."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import Parameter
+
+from jobhound.commands._terminal import run_transition
+
+
+def run(
+    slug_query: str,
+    /,
+    *,
+    today: Annotated[str | None, Parameter(show=False)] = None,
+    no_commit: Annotated[bool, Parameter(negative=())] = False,
+) -> None:
+    """Mark this opportunity as ghosted (no response, giving up)."""
+    run_transition(
+        slug_query=slug_query,
+        verb="ghost",
+        today=today,
+        no_commit=no_commit,
+    )

jobhound-0.2.0/src/jobhound/commands/link.py

@@ -0,0 +1,28 @@
+"""`jh link` — add or update an entry in the links table."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import Parameter
+
+from jobhound.config import load_config
+from jobhound.paths import paths_from_config
+from jobhound.repository import OpportunityRepository
+
+
+def run(
+    slug_query: str,
+    /,
+    *,
+    name: str,
+    url: str,
+    no_commit: Annotated[bool, Parameter(negative=())] = False,
+) -> None:
+    """Add or update a link."""
+    cfg = load_config()
+    repo = OpportunityRepository(paths_from_config(cfg), cfg)
+    opp, opp_dir = repo.find(slug_query)
+    updated = opp.with_link(name=name, url=url)
+    repo.save(updated, opp_dir, message=f"link: {opp.slug} {name}", no_commit=no_commit)
+    print(f"link {opp.slug}: {name} = {url}")

jobhound-0.2.0/src/jobhound/commands/list_.py

@@ -0,0 +1,15 @@
+"""`jh list` — one-line summary of every opportunity."""
+
+from __future__ import annotations
+
+from jobhound.config import load_config
+from jobhound.paths import paths_from_config
+from jobhound.repository import OpportunityRepository
+
+
+def run() -> None:
+    """List every opportunity as `<slug> <status> <priority>`, sorted by slug."""
+    cfg = load_config()
+    repo = OpportunityRepository(paths_from_config(cfg), cfg)
+    for opp in repo.all():
+        print(f"{opp.slug:<55} {opp.status:<12} {opp.priority}")

jobhound-0.2.0/src/jobhound/commands/log.py

@@ -0,0 +1,79 @@
+"""`jh log` — record an interaction; default next status advances one stage."""
+
+from __future__ import annotations
+
+import re
+import sys
+from datetime import date
+from pathlib import Path
+from typing import Annotated
+
+from cyclopts import Parameter
+
+from jobhound.config import load_config
+from jobhound.paths import paths_from_config
+from jobhound.repository import OpportunityRepository
+from jobhound.transitions import InvalidTransitionError
+
+_NAME_SLUG = re.compile(r"[^a-z0-9]+")
+
+
+def _name_slug(who: str) -> str:
+    return _NAME_SLUG.sub("-", who.lower()).strip("-") or "unknown"
+
+
+def _correspondence_filename(when: date, channel: str, direction: str, who: str) -> str:
+    return f"{when.isoformat()}-{channel}-{direction}-{_name_slug(who)}.md"
+
+
+def run(
+    slug_query: str,
+    /,
+    *,
+    channel: str,
+    direction: str,
+    who: str,
+    body: Path,
+    next_status: str = "stay",
+    next_action: str | None = None,
+    next_action_due: str | None = None,
+    force: bool = False,
+    today: Annotated[str | None, Parameter(show=False)] = None,
+    no_commit: Annotated[bool, Parameter(negative=())] = False,
+) -> None:
+    """Record an interaction (correspondence) and update status + next action."""
+    cfg = load_config()
+    repo = OpportunityRepository(paths_from_config(cfg), cfg)
+    today_date = date.fromisoformat(today) if today else date.today()
+
+    if direction not in {"from", "to"}:
+        print(f"--direction must be 'from' or 'to', got {direction!r}", file=sys.stderr)
+        raise SystemExit(1)
+    if not body.is_file():
+        print(f"--body file not found: {body}", file=sys.stderr)
+        raise SystemExit(1)
+
+    opp, opp_dir = repo.find(slug_query)
+    due = date.fromisoformat(next_action_due) if next_action_due else None
+    try:
+        updated = opp.log_interaction(
+            today=today_date,
+            next_status=next_status,
+            next_action=next_action,
+            next_action_due=due,
+            force=force,
+        )
+    except InvalidTransitionError as exc:
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(1) from exc
+
+    corr_dir = opp_dir / "correspondence"
+    corr_dir.mkdir(exist_ok=True)
+    corr_path = corr_dir / _correspondence_filename(today_date, channel, direction, who)
+    corr_path.write_text(body.read_text())
+
+    arrow = (
+        f"{opp.status} → {updated.status}" if updated.status != opp.status else "(no status change)"
+    )
+    repo.save(updated, opp_dir, message=f"log: {opp.slug} {arrow}", no_commit=no_commit)
+    print(f"logged: {opp.slug} {arrow}")

jobhound-0.2.0/src/jobhound/commands/new.py

@@ -0,0 +1,60 @@
+"""`jh new` — scaffold a new opportunity at status `prospect`."""
+
+from __future__ import annotations
+
+import sys
+from datetime import date, timedelta
+from typing import Annotated
+
+from cyclopts import Parameter
+
+from jobhound.config import load_config
+from jobhound.opportunities import Opportunity
+from jobhound.paths import Paths, paths_from_config
+from jobhound.priority import Priority
+from jobhound.repository import OpportunityRepository
+from jobhound.slug_value import Slug
+from jobhound.status import Status
+
+
+def run(
+    *,
+    company: str,
+    role: str,
+    source: str = "(unspecified)",
+    next_action: str = "Initial review of role and company",
+    next_action_due: str | None = None,
+    today: Annotated[str | None, Parameter(show=False)] = None,
+    no_commit: Annotated[bool, Parameter(negative=())] = False,
+) -> None:
+    """Create a new opportunity at status `prospect`."""
+    cfg = load_config()
+    paths = paths_from_config(cfg)
+    Paths.ensure(paths)
+    repo = OpportunityRepository(paths, cfg)
+
+    today_date = date.fromisoformat(today) if today else date.today()
+    due = date.fromisoformat(next_action_due) if next_action_due else today_date + timedelta(days=7)
+    slug = Slug.build(today_date, company, role)
+
+    opp = Opportunity(
+        slug=slug.value,
+        company=company,
+        role=role,
+        status=Status.PROSPECT,
+        priority=Priority.MEDIUM,
+        source=source,
+        location=None,
+        comp_range=None,
+        first_contact=today_date,
+        applied_on=None,
+        last_activity=today_date,
+        next_action=next_action,
+        next_action_due=due,
+    )
+    try:
+        opp_dir = repo.create(opp, message=f"new: {slug.value}", no_commit=no_commit)
+    except FileExistsError as exc:
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(1) from exc
+    print(f"Created {opp_dir.relative_to(paths.db_root)}")