workrail 0.1.0__py3-none-any.whl

workrail/__init__.py

@@ -0,0 +1,3 @@
+"""WorkRail package."""
+
+__version__ = "0.1.0"

workrail/__main__.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import sys
+
+from workrail.cli import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())

workrail/cli.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, TextIO
+
+from workrail import __version__
+from workrail.project import detect_project
+from workrail.report import render_report, render_today, write_report
+from workrail.skill import install_skill
+from workrail.storage import ActiveRailExistsError, NoActiveRailError, Storage
+from workrail.web import run_server
+
+
+SOURCES = ("human", "agent")
+LOOPBACK_HOSTS = {"127.0.0.1", "localhost", "::1"}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="workrail", description="Local workstream journal.")
+    parser.add_argument("--version", action="version", version=f"workrail {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    start = subparsers.add_parser("start", help="Start a new rail.")
+    start.add_argument("title")
+    start.add_argument("--source", choices=SOURCES, default="human")
+    start.add_argument("--project", default="auto")
+    start.add_argument("--quiet", action="store_true")
+    start.add_argument("--json", dest="json_output", action="store_true")
+    start.add_argument("--force", action="store_true")
+
+    for name, event_type, help_text in [
+        ("note", "note", "Record a note."),
+        ("n", "note", "Record a note."),
+        ("checkpoint", "checkpoint", "Record a checkpoint."),
+        ("block", "block", "Record a blocker."),
+        ("next", "next", "Record the next step."),
+        ("done", "done", "Complete the current rail."),
+        ("abandon", "abandon", "Abandon the current rail."),
+    ]:
+        event = subparsers.add_parser(name, help=help_text)
+        event.add_argument("content")
+        event.add_argument("--source", choices=SOURCES, default="human")
+        event.add_argument("--quiet", action="store_true")
+        event.add_argument("--json", dest="json_output", action="store_true")
+        event.set_defaults(event_type=event_type)
+
+    current = subparsers.add_parser("current", help="Show the current rail.")
+    current.add_argument("--json", dest="json_output", action="store_true")
+
+    today = subparsers.add_parser("today", help="Show today's workstream.")
+    today.add_argument("--json", dest="json_output", action="store_true")
+
+    report = subparsers.add_parser("report", help="Generate a Markdown report.")
+    report.add_argument("period", choices=("today", "week"))
+    report.add_argument("--output")
+
+    web = subparsers.add_parser("web", help="Start the local dashboard.")
+    web.add_argument("--host", default="127.0.0.1")
+    web.add_argument("--port", type=int, default=18765)
+
+    skill = subparsers.add_parser("install-skill", help="Install the bundled agent skill.")
+    skill.add_argument("--target", help="Target skills directory.")
+    skill.add_argument("--agent", choices=("auto", "codex", "claude", "opencode"), default="auto")
+    skill.add_argument("--force", action="store_true", help="Replace an existing skill.")
+    skill.add_argument("--source", help="Use a custom skill source directory.")
+
+    return parser
+
+
+def main(argv: list[str] | None = None, out: TextIO | None = None, err: TextIO | None = None) -> int:
+    output = out or sys.stdout
+    error = err or sys.stderr
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    storage = Storage()
+
+    try:
+        if args.command == "start":
+            return _handle_start(storage, args, output)
+        if args.command in {"note", "n", "checkpoint", "block", "next", "done", "abandon"}:
+            return _handle_event(storage, args, output, error)
+        if args.command == "current":
+            return _handle_current(storage, args, output)
+        if args.command == "today":
+            return _handle_today(storage, args, output)
+        if args.command == "report":
+            return _handle_report(storage, args, output)
+        if args.command == "web":
+            if args.host not in LOOPBACK_HOSTS:
+                print(
+                    f"WARNING: Binding the WorkRail dashboard to {args.host} exposes it "
+                    "without authentication. Use 127.0.0.1 unless you trust this network.",
+                    file=error,
+                )
+            try:
+                run_server(args.host, args.port, storage)
+            except OSError as exc:
+                print(f"Could not start dashboard: {exc}. Try --port with another value.", file=error)
+                return 2
+            return 0
+        if args.command == "install-skill":
+            destination = install_skill(
+                args.target,
+                agent=args.agent,
+                force=args.force,
+                source=args.source,
+            )
+            print(f"Installed skill: {destination}", file=output)
+            return 0
+    except (ActiveRailExistsError, NoActiveRailError) as exc:
+        print(str(exc), file=error)
+        return 2
+    except (FileExistsError, FileNotFoundError, ValueError) as exc:
+        print(str(exc), file=error)
+        return 2
+
+    parser.error(f"Unsupported command: {args.command}")
+    return 2
+
+
+def _handle_start(storage: Storage, args: argparse.Namespace, output: TextIO) -> int:
+    if args.project == "auto":
+        project_info = detect_project()
+        project = project_info.project
+        branch = project_info.branch
+        cwd = project_info.cwd
+    else:
+        project_info = detect_project()
+        project = args.project
+        branch = project_info.branch
+        cwd = project_info.cwd
+
+    rail = storage.create_rail(
+        title=args.title,
+        project=project,
+        branch=branch,
+        cwd=cwd,
+        source=args.source,
+        force=args.force,
+    )
+
+    if args.json_output:
+        print(json.dumps(_rail_payload(rail), indent=2), file=output)
+    elif not args.quiet:
+        print(f"Started: {rail['title']}", file=output)
+        print(f"Rail ID: {rail['id']}", file=output)
+    return 0
+
+
+def _handle_event(
+    storage: Storage, args: argparse.Namespace, output: TextIO, error: TextIO
+) -> int:
+    del error
+    event = storage.add_event_to_current(args.event_type, args.content, args.source)
+    if args.json_output:
+        print(json.dumps(event, indent=2), file=output)
+    elif not args.quiet:
+        verb = "Completed" if args.event_type == "done" else "Recorded"
+        print(f"{verb} {args.event_type}: {event['content']}", file=output)
+    return 0
+
+
+def _handle_current(storage: Storage, args: argparse.Namespace, output: TextIO) -> int:
+    rail = storage.current_rail()
+    payload = _rail_payload(rail) if rail else {"active": False}
+    if args.json_output:
+        print(json.dumps(payload, indent=2), file=output)
+    elif rail:
+        print(f"{rail['id']} {rail['title']} [{rail['status']}]", file=output)
+        print(f"Project: {rail['project'] or '-'}", file=output)
+    else:
+        print("No active rail.", file=output)
+    return 0
+
+
+def _handle_today(storage: Storage, args: argparse.Namespace, output: TextIO) -> int:
+    if args.json_output:
+        from datetime import date
+
+        day = date.today().isoformat()
+        payload = {
+            "date": day,
+            "rails": storage.rails_with_events_between(day, day),
+            "events": storage.events_between(day, day),
+        }
+        print(json.dumps(payload, indent=2), file=output)
+    else:
+        print(render_today(storage), file=output)
+    return 0
+
+
+def _handle_report(storage: Storage, args: argparse.Namespace, output: TextIO) -> int:
+    content = render_report(storage, args.period)
+    if args.output:
+        write_report(Path(args.output), content)
+    print(content, file=output)
+    return 0
+
+
+def _rail_payload(rail: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "active": rail["status"] in {"in_progress", "blocked"},
+        "id": rail["id"],
+        "title": rail["title"],
+        "project": rail["project"],
+        "branch": rail["branch"],
+        "cwd": rail["cwd"],
+        "status": rail["status"],
+        "source": rail["source"],
+        "started_at": rail["started_at"],
+        "ended_at": rail["ended_at"],
+        "updated_at": rail["updated_at"],
+    }

workrail/config.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+APP_NAME = "WorkRail"
+DB_ENV_VAR = "WORKRAIL_DB"
+
+
+def default_data_dir() -> Path:
+    if sys.platform == "win32":
+        root = os.environ.get("LOCALAPPDATA")
+        if root:
+            return Path(root) / APP_NAME
+        return Path.home() / "AppData" / "Local" / APP_NAME
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "workrail"
+    root = os.environ.get("XDG_DATA_HOME")
+    if root:
+        return Path(root) / "workrail"
+    return Path.home() / ".local" / "share" / "workrail"
+
+
+def get_db_path() -> Path:
+    override = os.environ.get(DB_ENV_VAR)
+    if override:
+        return Path(override).expanduser().resolve()
+    return default_data_dir() / "workrail.db"

workrail/project.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ProjectInfo:
+    project: str
+    branch: str | None
+    cwd: str
+
+
+def _git(args: list[str], cwd: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=str(cwd),
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=2,
+        )
+    except (FileNotFoundError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+    value = result.stdout.strip()
+    return value or None
+
+
+def detect_project(cwd: str | Path | None = None) -> ProjectInfo:
+    current = Path(cwd or Path.cwd()).resolve()
+    root_text = _git(["rev-parse", "--show-toplevel"], current)
+    branch = _git(["rev-parse", "--abbrev-ref", "HEAD"], current)
+
+    if root_text:
+        root = Path(root_text).resolve()
+        project = root.name
+    else:
+        project = current.name
+        branch = None
+
+    return ProjectInfo(project=project, branch=branch, cwd=str(current))

workrail/report.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from workrail.storage import DateRange, Storage
+
+
+REPORT_EVENT_ORDER = {"done": 0, "checkpoint": 1, "block": 2, "next": 3, "note": 4, "start": 5}
+
+
+def render_report(storage: Storage, period: str = "today") -> str:
+    date_range = DateRange.for_period(period)
+    rails = storage.rails_with_events_between(date_range.start, date_range.end)
+
+    if period == "week":
+        title = f"# Weekly Report - {date_range.start} to {date_range.end}"
+    else:
+        title = f"# Daily Report - {date.today().isoformat()}"
+
+    completed: list[str] = []
+    in_progress: list[str] = []
+    blockers: list[str] = []
+    next_steps: list[str] = []
+
+    for rail in rails:
+        events = rail.get("events", [])
+        if rail["status"] == "done":
+            completed.append(_rail_bullet(rail, events, {"done", "checkpoint", "block"}))
+        elif rail["status"] in {"in_progress", "blocked"}:
+            in_progress.append(_rail_bullet(rail, events, {"checkpoint", "note", "next", "block"}))
+
+        block_events = [event for event in events if event["type"] == "block"]
+        for event in block_events:
+            blockers.append(f"- {rail['title']}: {event['content']}")
+
+        next_events = [event for event in events if event["type"] == "next"]
+        for event in next_events:
+            next_steps.append(f"- {rail['title']}: {event['content']}")
+
+    sections = [
+        title,
+        "",
+        "## Completed",
+        *(completed or ["- None"]),
+        "",
+        "## In Progress",
+        *(in_progress or ["- None"]),
+        "",
+        "## Blockers",
+        *(blockers or ["- None"]),
+        "",
+        "## Next Steps",
+        *(next_steps or ["- None"]),
+        "",
+    ]
+    return "\n".join(sections)
+
+
+def render_today(storage: Storage) -> str:
+    day = date.today().isoformat()
+    rails = storage.rails_with_events_between(day, day)
+    lines = [f"Today - {day}", ""]
+    if not rails:
+        lines.append("No work events recorded.")
+        return "\n".join(lines)
+
+    for rail in rails:
+        lines.append(f"{rail['id']} {rail['title']}")
+        for event in rail.get("events", []):
+            time_text = event["created_at"][11:16]
+            lines.append(f"  {time_text} {event['type']} {event['content']}")
+        lines.append("")
+    return "\n".join(lines).rstrip()
+
+
+def write_report(path: str | Path, content: str) -> None:
+    Path(path).expanduser().write_text(content, encoding="utf-8")
+
+
+def _rail_bullet(rail: dict[str, Any], events: list[dict[str, Any]], allowed: set[str]) -> str:
+    lines = [f"- {rail['title']}"]
+    selected = [event for event in events if event["type"] in allowed and event["type"] != "start"]
+    selected.sort(key=lambda event: (REPORT_EVENT_ORDER.get(event["type"], 99), event["created_at"]))
+
+    if not selected:
+        return lines[0]
+
+    note_count = 0
+    for event in selected:
+        if event["type"] == "note":
+            note_count += 1
+            if note_count > 2:
+                continue
+        prefix = "next: " if event["type"] == "next" else ""
+        lines.append(f"  - {prefix}{event['content']}")
+    return "\n".join(lines)
+
+
+def summarize_by_status(rails: list[dict[str, Any]]) -> dict[str, int]:
+    counts: dict[str, int] = defaultdict(int)
+    for rail in rails:
+        counts[rail["status"]] += 1
+    return {
+        "done": counts["done"],
+        "in_progress": counts["in_progress"],
+        "blocked": counts["blocked"],
+        "abandoned": counts["abandoned"],
+    }

workrail/safety.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SensitiveMatch:
+    rule: str
+
+
+SENSITIVE_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    (
+        "secret-key-value",
+        re.compile(
+            r"\b(password|passwd|pwd|token|secret|api[_-]?key|apikey|access[_-]?key)"
+            r"\s*[:=]\s*['\"]?[^\s'\"]{6,}",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "bearer-token",
+        re.compile(r"\bBearer\s+[A-Za-z0-9._\-]{20,}", re.IGNORECASE),
+    ),
+    (
+        "private-key",
+        re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"),
+    ),
+    (
+        "aws-access-key",
+        re.compile(r"\b(AKIA|ASIA)[0-9A-Z]{16}\b"),
+    ),
+)
+
+
+def find_sensitive_content(content: str) -> SensitiveMatch | None:
+    for rule, pattern in SENSITIVE_PATTERNS:
+        if pattern.search(content):
+            return SensitiveMatch(rule=rule)
+    return None
+
+
+def validate_safe_content(content: str) -> None:
+    match = find_sensitive_content(content)
+    if match:
+        raise ValueError(
+            f"Refusing to record content that matches sensitive rule: {match.rule}."
+        )

workrail/skill.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+
+SKILL_NAME = "workrail-agent"
+AGENTS = ("codex", "claude", "opencode")
+
+
+def default_skill_target(agent: str = "codex") -> Path:
+    if agent == "codex":
+        return _codex_skill_target()
+    if agent == "claude":
+        return Path.home() / ".claude" / "skills"
+    if agent == "opencode":
+        return Path.home() / ".opencode" / "skills"
+    raise ValueError(f"Unsupported agent: {agent}")
+
+
+def _codex_skill_target() -> Path:
+    codex_home = os.environ.get("CODEX_HOME")
+    root = Path(codex_home).expanduser() if codex_home else Path.home() / ".codex"
+    return root / "skills"
+
+
+def resolve_skill_target(agent: str = "auto", target: str | Path | None = None) -> Path:
+    if target:
+        return Path(target).expanduser().resolve()
+
+    if agent != "auto":
+        return default_skill_target(agent).expanduser().resolve()
+
+    existing = [default_skill_target(name) for name in AGENTS if default_skill_target(name).exists()]
+    if len(existing) == 1:
+        return existing[0].expanduser().resolve()
+    if len(existing) > 1:
+        names = ", ".join(str(path) for path in existing)
+        raise ValueError(f"Multiple agent skill directories found: {names}. Use --agent or --target.")
+    return default_skill_target("codex").expanduser().resolve()
+
+
+def find_skill_source() -> Path:
+    current = Path(__file__).resolve()
+    for parent in current.parents:
+        candidate = parent / "skills" / SKILL_NAME
+        if (candidate / "SKILL.md").is_file():
+            return candidate
+    raise FileNotFoundError("Bundled workrail-agent skill was not found.")
+
+
+def install_skill(
+    target: str | Path | None = None,
+    *,
+    agent: str = "auto",
+    force: bool = False,
+    source: str | Path | None = None,
+) -> Path:
+    source_path = Path(source).expanduser().resolve() if source else find_skill_source()
+    if not (source_path / "SKILL.md").is_file():
+        raise FileNotFoundError(f"Skill source is missing SKILL.md: {source_path}")
+
+    target_root = resolve_skill_target(agent, target)
+    destination = target_root if target_root.name == SKILL_NAME else target_root / SKILL_NAME
+
+    if destination.exists():
+        if not force:
+            raise FileExistsError(
+                f"Skill already exists at {destination}. Use --force to replace it."
+            )
+        shutil.rmtree(destination)
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(source_path, destination)
+    return destination