crowdtime-cli 0.17.1__tar.gz → 0.18.0__tar.gz

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crowdtime-cli
-Version: 0.17.1
+Version: 0.18.0
 Summary: AI-powered time tracking CLI — a modern, developer-friendly alternative to Harvest
 Project-URL: Homepage, https://crowdtime.lat
 Project-URL: Documentation, https://crowdtime.lat/docs
@@ -56,10 +56,19 @@ Track time, manage projects, log expenses, generate reports, submit timesheets,
 ## Installation
 
 ```bash
-pip install crowdtime-cli
+pipx install crowdtime-cli
 ```
 
-Requires Python 3.11+
+Requires Python 3.11+. [pipx](https://pipx.pypa.io/) installs the CLI in its own isolated environment and puts `crowdtime` and `ct` on your PATH. On Debian, Ubuntu and other systems where the system Python is "externally managed", plain `pip install` into the system Python is blocked, so use pipx (or `uv tool install crowdtime-cli`).
+
+Prefer pip? Install into a virtualenv:
+
+```bash
+python3 -m venv ~/.venvs/crowdtime
+~/.venvs/crowdtime/bin/pip install crowdtime-cli
+```
+
+To upgrade later: `pipx upgrade crowdtime-cli` (or `pip install -U crowdtime-cli` in the virtualenv).
 
 ## Quick Start
 

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/README.md

@@ -21,10 +21,19 @@ Track time, manage projects, log expenses, generate reports, submit timesheets,
 ## Installation
 
 ```bash
-pip install crowdtime-cli
+pipx install crowdtime-cli
 ```
 
-Requires Python 3.11+
+Requires Python 3.11+. [pipx](https://pipx.pypa.io/) installs the CLI in its own isolated environment and puts `crowdtime` and `ct` on your PATH. On Debian, Ubuntu and other systems where the system Python is "externally managed", plain `pip install` into the system Python is blocked, so use pipx (or `uv tool install crowdtime-cli`).
+
+Prefer pip? Install into a virtualenv:
+
+```bash
+python3 -m venv ~/.venvs/crowdtime
+~/.venvs/crowdtime/bin/pip install crowdtime-cli
+```
+
+To upgrade later: `pipx upgrade crowdtime-cli` (or `pip install -U crowdtime-cli` in the virtualenv).
 
 ## Quick Start
 

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "crowdtime-cli"
-version = "0.17.1"
+version = "0.18.0"
 description = "AI-powered time tracking CLI — a modern, developer-friendly alternative to Harvest"
 readme = "README.md"
 license = {text = "Proprietary"}

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/src/crowdtime_cli/__init__.py

@@ -1,3 +1,3 @@
 """CrowdTime CLI - AI-powered time tracking from the command line."""
 
-__version__ = "0.17.1"
+__version__ = "0.18.0"

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/src/crowdtime_cli/auth.py

@@ -5,6 +5,8 @@ Stores API tokens in the system keyring, with file-based fallback.
 
 from __future__ import annotations
 
+import os
+import sys
 from pathlib import Path
 
 from .config import CONFIG_DIR
@@ -51,8 +53,23 @@ def clear_token() -> None:
 def _save_token_file(token: str) -> None:
     """File-based fallback for token storage."""
     CONFIG_DIR.mkdir(parents=True, exist_ok=True)
-    CREDENTIALS_FILE.write_text(token)
-    CREDENTIALS_FILE.chmod(0o600)
+    # Created owner-only from the start — writing first and tightening the
+    # mode afterwards leaves the token world-readable in between.
+    fd = os.open(CREDENTIALS_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        # The mode above only applies to a new file; an existing one keeps
+        # whatever it had, so tighten it before the token goes in.
+        if hasattr(os, "fchmod"):
+            os.fchmod(fd, 0o600)
+    except OSError:
+        pass
+    with os.fdopen(fd, "w") as f:
+        f.write(token)
+    print(
+        "Warning: no system keyring available — the API token was stored in "
+        f"plain text at {CREDENTIALS_FILE} (readable only by you).",
+        file=sys.stderr,
+    )
 
 
 def _get_token_file() -> str | None:

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/src/crowdtime_cli/client.py

@@ -7,16 +7,39 @@ and friendly error handling.
 from __future__ import annotations
 
 import os
+import sys
 from typing import Any
 
 import httpx
 from rich.console import Console
+from rich.markup import escape
 
 from .auth import get_token
-from .config import get_config
+from .config import INSECURE_SERVER_URL_WARNING, get_config, is_insecure_server_url
 
 console = Console(stderr=True)
 _DEBUG = os.environ.get("CROWDTIME_DEBUG", "").lower() in ("1", "true", "yes")
+# One warning per invocation, however many clients a command creates.
+_warned_insecure_url = False
+
+
+def _error_message(detail: Any) -> str:
+    """Turn an API error body into one readable line.
+
+    Validation errors arrive as ``{"field": ["message", ...]}``; printing the
+    dict verbatim buries the reason the server gave.
+    """
+    if isinstance(detail, dict):
+        if isinstance(detail.get("detail"), str):
+            return detail["detail"]
+        parts = []
+        for field, value in detail.items():
+            text = "; ".join(str(v) for v in value) if isinstance(value, (list, tuple)) else str(value)
+            parts.append(text if field in ("non_field_errors", "detail") else f"{field}: {text}")
+        return " | ".join(parts) if parts else str(detail)
+    if isinstance(detail, list):
+        return "; ".join(str(item) for item in detail)
+    return str(detail)
 
 
 class APIError(Exception):
@@ -37,6 +60,14 @@ class CrowdTimeClient:
         self.base_url = self.config.server_url
         self.token = get_token()
         self.org_slug = self.config.organization
+        # Extra line a command can set before a call, shown if the server
+        # answers 403 — for pointing at the command that would work instead.
+        self.forbidden_hint: str | None = None
+
+        global _warned_insecure_url
+        if not _warned_insecure_url and is_insecure_server_url(self.base_url):
+            _warned_insecure_url = True
+            print(INSECURE_SERVER_URL_WARNING.format(url=self.base_url), file=sys.stderr)
 
         if require_auth and not self.token:
             console.print(
@@ -138,7 +169,20 @@ class CrowdTimeClient:
             raise SystemExit(1)
 
         if response.status_code == 403:
-            console.print("[red]Permission denied.[/red] You don't have access to this resource.")
+            # The server says why (not your entry, already invoiced, no
+            # approval authority, read-only token…) — pass that on instead of
+            # a generic refusal.
+            reason = "You don't have access to this resource."
+            try:
+                body = response.json()
+                if isinstance(body, dict) and isinstance(body.get("detail"), str) and body["detail"]:
+                    reason = body["detail"]
+            except Exception:
+                pass
+            console.print(f"[red]Permission denied.[/red] {escape(reason)}")
+            hint = getattr(self, "forbidden_hint", None)
+            if hint:
+                console.print(f"[dim]{escape(hint)}[/dim]")
             raise SystemExit(1)
 
         if response.status_code == 402:
@@ -179,8 +223,7 @@ class CrowdTimeClient:
                 detail = response.json()
             except Exception:
                 detail = response.text
-            msg = detail.get("detail", str(detail)) if isinstance(detail, dict) else str(detail)
-            raise APIError(msg, status_code=response.status_code, detail=detail)
+            raise APIError(_error_message(detail), status_code=response.status_code, detail=detail)
 
         if not response.content:
             return None

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/src/crowdtime_cli/commands/auth_cmd.py

@@ -81,7 +81,14 @@ def _login_with_browser(output_json: bool) -> None:
     console.print(f"[dim]Server: {server_url}[/dim]")
     console.print(f"[dim]Waiting for authentication (up to 2 minutes)...[/dim]\n")
 
-    result = run_oauth_flow(server_url)
+    def _show_code(code: str) -> None:
+        console.print(f"Verification code: [bold]{code}[/bold]")
+        console.print(
+            "[dim]The browser will ask you to authorize this login. "
+            "Only approve it if it shows the same code.[/dim]\n"
+        )
+
+    result = run_oauth_flow(server_url, on_verification_code=_show_code)
 
     if result is None:
         console.print()

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/src/crowdtime_cli/commands/config_cmd.py

@@ -8,7 +8,7 @@ import subprocess
 import typer
 from rich.console import Console
 
-from ..config import get_config
+from ..config import INSECURE_SERVER_URL_WARNING, get_config, is_insecure_server_url
 from ..formatters import format_error, format_success, print_json
 
 app = typer.Typer(name="config", help="Manage CLI configuration.")
@@ -23,11 +23,13 @@ def config_set(
     """Set a configuration value.
 
     Examples:
-        ct config set server.url https://api.crowdtime.io
+        ct config set server.url https://api.crowdtime.lat
         ct config set defaults.project myproject
         ct config set defaults.daily_target 7h
     """
     config = get_config()
+    if key == "server.url" and is_insecure_server_url(value):
+        typer.echo(INSECURE_SERVER_URL_WARNING.format(url=value), err=True)
     # Convert boolean strings
     if value.lower() in ("true", "yes", "1"):
         config.set(key, True)

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/src/crowdtime_cli/commands/insights_cmd.py

@@ -571,7 +571,8 @@ def profitability_insights(
 
     Revenue is computed from billable time entries. Cost is derived from team
     compensation configs (hourly rate or prorated salary). Margin = Revenue - Cost.
-    Requires manager+ role. Cost data requires payroll compensation configs.
+    Requires manager+ role. Cost and margin are shown to admins and owners only
+    (they derive from payroll); account managers get revenue and hours.
 
     Examples:
         ct insights profitability
@@ -671,7 +672,8 @@ def profitability_insights(
 
         if not has_cost:
             console.print(
-                "[dim]ℹ Cost data unavailable — configure compensation in Payroll to see margins.[/dim]"
+                "[dim]ℹ Cost and margin are not shown. They derive from payroll, so they are "
+                "visible to admins and owners only, and need compensation configured in Payroll.[/dim]"
             )
 
         console.print()

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/src/crowdtime_cli/commands/log_cmd.py

@@ -277,8 +277,15 @@ def bulk_delete(
         if skipped:
             for s in skipped:
                 console.print(f"  [yellow]Skipped[/yellow] {s['id']}: {s['reason']}")
+        # Entries that aren't yours are not reported at all — the server
+        # treats them as not found.
+        unmatched = len(set(ids)) - deleted_count - len(skipped)
         if not deleted_count and not skipped:
             console.print("[dim]No matching entries found.[/dim]")
+        elif unmatched > 0:
+            console.print(
+                f"  [dim]{unmatched} ID(s) not found (wrong ID, or not your entry).[/dim]"
+            )
     except APIError as e:
         format_error(e.message)
         raise typer.Exit(1)

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/src/crowdtime_cli/commands/org_cmd.py

@@ -231,7 +231,10 @@ def update_member(
     capacity: Optional[float] = typer.Option(None, "--capacity", help="Weekly capacity hours."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
-    """Update an organization member's role, rate, or capacity.
+    """Update an organization member's role, rate, or capacity (admin+).
+
+    You cannot grant a role above your own, and only the owner can change
+    the owner's membership. Ownership is not assignable here.
 
     Examples:
         ct org update-member <user-id> --role project_manager
@@ -363,7 +366,7 @@ def revoke_invite(
 def invitations(
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
-    """List pending invitations for the current organization."""
+    """List pending invitations for the current organization (admin+)."""
     client = CrowdTimeClient(require_auth=True, require_org=True)
 
     try:

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/src/crowdtime_cli/commands/report_cmd.py

@@ -649,7 +649,7 @@ def saved_delete(
     client = CrowdTimeClient(require_auth=True, require_org=True)
 
     if not force:
-        if not typer.confirm(f"Delete saved report {report_id[:8]}…?"):
+        if not typer.confirm(f"Delete saved report {report_id}?"):
             console.print("[dim]Cancelled.[/dim]")
             raise typer.Exit(0)
 

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/src/crowdtime_cli/commands/timesheet_cmd.py

@@ -83,6 +83,14 @@ def _print_timesheets_table(timesheets: list[dict], show_user: bool = False) ->
     console.print(table)
 
 
+_REVIEW_BY_PROJECT_HINT = (
+    "A whole timesheet can be decided by an admin, by the person's direct manager, or by "
+    "someone who manages every project in it. Otherwise review your project's portion: "
+    "ct timesheet approvals <timesheet-id>, then ct timesheet approve|reject <timesheet-id> "
+    "--project <project-id>."
+)
+
+
 def _print_team_overview(data: dict) -> None:
     """Print team overview in a Rich table."""
     from rich.table import Table
@@ -113,6 +121,7 @@ def _print_team_overview(data: dict) -> None:
     table.add_column("Entries", justify="right", width=8)
     table.add_column("Status", width=14)
 
+    any_by_project = False
     for m in members:
         # When project filter is active, surface the per-project approval
         # status rather than the whole-timesheet status.
@@ -123,8 +132,12 @@ def _print_team_overview(data: dict) -> None:
             status = m.get("timesheet_status")
         style = _status_style(status)
 
-        capacity_pct = m.get("capacity_percent", 0)
-        if capacity_pct > 100:
+        # Null for people who only share a project with the caller: their
+        # hours here are that project's, not their whole week.
+        capacity_pct = m.get("capacity_percent")
+        if capacity_pct is None:
+            pct_display = "[dim]—[/dim]"
+        elif capacity_pct > 100:
             pct_display = f"[red]{capacity_pct}%[/red]"
         elif capacity_pct >= 80:
             pct_display = f"[green]{capacity_pct}%[/green]"
@@ -133,17 +146,27 @@ def _print_team_overview(data: dict) -> None:
 
         period_cap = m.get("period_capacity_hours", "40.0")
 
+        review_by_project = m.get("can_review_timesheet") is False
+        if review_by_project:
+            any_by_project = True
+
         table.add_row(
-            m.get("user_name", ""),
-            format_duration(Decimal(str(m.get("total_hours", 0)))),
+            m.get("user_name", "") + (" *" if review_by_project else ""),
+            format_duration(Decimal(str(m.get("total_hours") or 0))),
             f"{period_cap}h",
             pct_display,
-            format_duration(Decimal(str(m.get("billable_hours", 0)))),
+            format_duration(Decimal(str(m.get("billable_hours") or 0))),
             str(m.get("entry_count", 0)),
             f"[{style}]{_status_label(status)}[/{style}]",
         )
 
     console.print(table)
+    if any_by_project:
+        console.print(
+            "[dim]* Shares a project with you but is not your direct report: hours shown are "
+            "for your projects only, and you review their timesheet per project "
+            "(ct timesheet approve <id> --project <project-id>).[/dim]"
+        )
 
 
 # ─── Commands ─────────────────────────────────────────────────────
@@ -282,7 +305,8 @@ def approve_timesheet(
 ) -> None:
     """Approve a submitted timesheet (project_manager+).
 
-    Without --project: approves all project portions at once (manager+).
+    Without --project: approves the whole timesheet. Allowed for admins, the
+    person's direct manager, or someone who manages every project in it.
     With --project: approves only that project's portion (PM for that project).
 
     Examples:
@@ -294,7 +318,7 @@ def approve_timesheet(
 
     if not force and not output_json:
         scope = f"project portion for {project}" if project else "all projects"
-        if not typer.confirm(f"Approve timesheet {timesheet_id[:8]}… ({scope})?"):
+        if not typer.confirm(f"Approve timesheet {timesheet_id} ({scope})?"):
             console.print("[dim]Cancelled.[/dim]")
             raise typer.Exit(0)
 
@@ -309,13 +333,14 @@ def approve_timesheet(
                 data=data or None,
             )
         else:
+            client.forbidden_hint = _REVIEW_BY_PROJECT_HINT
             result = client.post(f"/timesheets/{timesheet_id}/approve/", data=data or None)
 
         if output_json:
             print_json(result)
         else:
             if project:
-                project_name = result.get("project_name") or project[:8]
+                project_name = result.get("project_name") or project
                 ts_status = result.get("timesheet_status", "")
                 format_success(f"Project '{project_name}' approved.")
                 if ts_status == "approved":
@@ -344,7 +369,9 @@ def reject_timesheet(
     """Reject a submitted timesheet with notes (project_manager+).
 
     Rejecting any project portion rejects the entire timesheet.
-    The user must fix entries and resubmit.
+    The user must fix entries and resubmit. Without --project you need
+    authority over the whole timesheet (admin, direct manager, or managing
+    every project in it); with --project, managing that project is enough.
 
     Examples:
         ct timesheet reject <timesheet-id> --notes "Missing entries for Wednesday"
@@ -354,7 +381,7 @@ def reject_timesheet(
 
     if not force and not output_json:
         console.print("[yellow]Rejecting will return the entire timesheet for revision.[/yellow]")
-        if not typer.confirm(f"Reject timesheet {timesheet_id[:8]}…?"):
+        if not typer.confirm(f"Reject timesheet {timesheet_id}?"):
             console.print("[dim]Cancelled.[/dim]")
             raise typer.Exit(0)
 
@@ -365,6 +392,7 @@ def reject_timesheet(
                 data={"notes": notes},
             )
         else:
+            client.forbidden_hint = _REVIEW_BY_PROJECT_HINT
             result = client.post(f"/timesheets/{timesheet_id}/reject/", data={
                 "notes": notes,
             })
@@ -373,7 +401,7 @@ def reject_timesheet(
             print_json(result)
         else:
             if project:
-                project_name = result.get("project_name") or project[:8]
+                project_name = result.get("project_name") or project
                 format_success(f"Project '{project_name}' rejected. Timesheet returned for revision.")
             else:
                 user_name = result.get("user_name", "user")
@@ -402,7 +430,7 @@ def recall_timesheet(
     client = CrowdTimeClient(require_auth=True, require_org=True)
 
     if not force and not output_json:
-        if not typer.confirm(f"Recall timesheet {timesheet_id[:8]}… back to draft?"):
+        if not typer.confirm(f"Recall timesheet {timesheet_id} back to draft?"):
             console.print("[dim]Cancelled.[/dim]")
             raise typer.Exit(0)
 
@@ -439,7 +467,8 @@ def reopen_timesheet(
     The reviewer-side undo for an approval granted in error: clears the
     approval, unlocks the period's time entries and returns the timesheet to
     draft so the user can fix it and resubmit. Blocked if any of that time is
-    already on a finalized invoice.
+    already on a finalized invoice. Needs authority over the whole timesheet:
+    admin, the person's direct manager, or managing every project in it.
 
     Examples:
         ct timesheet reopen <timesheet-id> --notes "Approved before Friday's entries were added"

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/src/crowdtime_cli/commands/version_cmd.py

@@ -7,7 +7,7 @@ from rich.console import Console
 
 from .. import __version__
 from ..formatters import print_json
-from ..version_check import _parse_simple, get_latest, is_outdated
+from ..version_check import _parse_simple, get_latest, is_outdated, upgrade_command
 
 app = typer.Typer(name="version", help="Show installed and latest CLI versions.")
 console = Console()
@@ -51,7 +51,7 @@ def version(
     elif outdated:
         console.print(
             f"[yellow]\u26a0 A newer version is available. "
-            f"Run [bold]pip install -U crowdtime-cli[/bold] to upgrade.[/yellow]"
+            f"Run [bold]{upgrade_command()}[/bold] to upgrade.[/yellow]"
         )
     else:
         console.print("[green]\u2713 You are up to date.[/green]")

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/src/crowdtime_cli/config.py

@@ -34,6 +34,22 @@ DEFAULT_CONFIG = {
 }
 
 
+INSECURE_SERVER_URL_WARNING = (
+    "Warning: server.url is {url} — plain http sends your API token "
+    "unencrypted. Use https for anything but a local server."
+)
+
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+def is_insecure_server_url(url: str) -> bool:
+    """True for a plain-http server URL that isn't on this machine."""
+    from urllib.parse import urlsplit
+
+    parts = urlsplit(str(url).strip())
+    return parts.scheme == "http" and (parts.hostname or "") not in _LOCAL_HOSTS
+
+
 class CrowdTimeConfig:
     """Manages CrowdTime CLI configuration."""
 

{crowdtime_cli-0.17.1 → crowdtime_cli-0.18.0}/src/crowdtime_cli/oauth.py

@@ -10,20 +10,39 @@ import hashlib
 import secrets
 import time
 import webbrowser
+from collections.abc import Callable
 
 import httpx
 
 
-def run_oauth_flow(server_url: str, timeout: int = 120) -> tuple[str, str] | None:
+def verification_code(state: str) -> str:
+    """Short code the server shows on its consent page for this login.
+
+    Comparing it with the terminal confirms the browser is authorizing the
+    session started here. Must match ``cli_verification_code`` on the server.
+    """
+    digest = hashlib.sha256(f'cli-verify:{state}'.encode()).hexdigest().upper()
+    return f'{digest[:4]}-{digest[4:8]}'
+
+
+def run_oauth_flow(
+    server_url: str,
+    timeout: int = 120,
+    on_verification_code: Callable[[str], None] | None = None,
+) -> tuple[str, str] | None:
     """Run the browser-based OAuth login flow with PKCE protection.
 
     1. Opens browser for Google OAuth on the server
-    2. Polls the server until the auth code is available
-    3. Exchanges the code + PKCE verifier for an API token
+    2. The user confirms on the server's consent page that the code shown
+       there matches the one printed here
+    3. Polls the server until the auth code is available
+    4. Exchanges the code + PKCE verifier for an API token
 
     Args:
         server_url: The CrowdTime server URL (e.g. https://api.crowdtime.lat).
         timeout: Max seconds to wait for the user to complete OAuth.
+        on_verification_code: Called with the code to display before the
+            browser opens.
 
     Returns:
         Tuple of (api_token, org_slug) on success, or None on failure/timeout.
@@ -40,6 +59,9 @@ def run_oauth_flow(server_url: str, timeout: int = 120) -> tuple[str, str] | Non
         f'?state={state}&code_challenge={code_challenge}'
     )
 
+    if on_verification_code is not None:
+        on_verification_code(verification_code(state))
+
     if not webbrowser.open(login_url):
         return None