clockify-export 0.1.1__tar.gz → 0.1.4__tar.gz

{clockify_export-0.1.1 → clockify_export-0.1.4}/.idea/clockify-export.iml

@@ -2,7 +2,9 @@
 <module type="JAVA_MODULE" version="4">
   <component name="NewModuleRootManager" inherit-compiler-output="true">
     <exclude-output />
-    <content url="file://$MODULE_DIR$" />
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
     <orderEntry type="inheritedJdk" />
     <orderEntry type="sourceFolder" forTests="false" />
   </component>

clockify_export-0.1.4/.idea/git_toolbox_prj.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="GitToolBoxProjectSettings">
+    <option name="commitMessageIssueKeyValidationOverride">
+      <BoolValueOverride>
+        <option name="enabled" value="true" />
+      </BoolValueOverride>
+    </option>
+    <option name="commitMessageValidationEnabledOverride">
+      <BoolValueOverride>
+        <option name="enabled" value="true" />
+      </BoolValueOverride>
+    </option>
+  </component>
+</project>

clockify_export-0.1.4/.idea/go.imports.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="GoImports">
+    <option name="excludedPackages">
+      <array>
+        <option value="golang.org/x/net/context" />
+      </array>
+    </option>
+  </component>
+</project>

clockify_export-0.1.4/.idea/jsonSchemas.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="JsonSchemaMappingsProjectConfiguration">
+    <state>
+      <map>
+        <entry key="mise">
+          <value>
+            <SchemaInfo>
+              <option name="name" value="mise" />
+              <option name="relativePathToSchema" value="https://mise.jdx.dev/schema/mise.json" />
+              <option name="applicationDefined" value="true" />
+              <option name="patterns">
+                <list>
+                  <Item>
+                    <option name="path" value="mise.toml" />
+                  </Item>
+                </list>
+              </option>
+            </SchemaInfo>
+          </value>
+        </entry>
+      </map>
+    </state>
+  </component>
+</project>

clockify_export-0.1.4/.idea/misc.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="Python 3.14" />
+  </component>
+  <component name="ProjectRootManager" version="2" languageLevel="JDK_25" project-jdk-name="Python 3.14" project-jdk-type="Python SDK">
+    <output url="file://$PROJECT_DIR$/out" />
+  </component>
+</project>

clockify_export-0.1.4/AGENTS.md

@@ -0,0 +1,54 @@
+# Agent Instructions
+
+When generating documentation and comments, be as concise and brief as possible without loosing relevant information.
+
+## Project Files
+
+| File | Purpose |
+|------|---------|
+| `PLAN.md` | Development roadmap and task tracking |
+| `CHANGELOG.md` | Version history (Keep a Changelog format) |
+| `README.md` | User documentation |
+
+---
+
+## Updating the Plan
+
+When **adding/removing/starting/resolving tasks**:
+
+1. Edit `PLAN.md`
+2. Use status markers:
+   - `[ ]` — Not started
+   - `🔄` — In progress
+3. When a task is implemented, update `CHANGELOG.md` (in "Unreleased" section) and remove from `PLAN.md`
+
+---
+
+## Updating the Changelog
+
+1. Edit `CHANGELOG.md`
+3. Keep `[Unreleased]` section for things done since last release
+4. Follow [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format
+
+---
+
+## Versioning
+
+This project uses [Semantic Versioning](https://semver.org/):
+- **MAJOR** — Breaking changes
+- **MINOR** — New features (backward compatible)
+- **PATCH** — Bug fixes (backward compatible)
+
+Current version defined in: `pyproject.toml` (also read by `src/clockify_export/__init__.py`)
+
+---
+
+## Code Locations
+
+| Feature | File |
+|---------|------|
+| CLI entry point | `src/clockify_export/cli.py` |
+| Export logic | `src/clockify_export/export.py` |
+| API client | `src/clockify_export/api.py` |
+| Config/state | `src/clockify_export/config.py` |
+| Cache | `src/clockify_export/cache.py` |

clockify_export-0.1.4/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Auto-refresh cache when unknown project/client/tag ID encountered during entry processing
+- Cache for workspaces, projects, clients, tags with 1-week expiry
+- `--no-cache` flag to bypass cache and force fresh API fetch
+- Current month CSV includes date in filename (e.g., `...-2026-09-17.csv`)
+- Auto-cleanup of old current-month files with different dates
+- Mutually exclusive date range options: `--from`, `--last`, `--refetch`
+
+### Changed
+- Removed `last` option from config file (prevents inconsistent behavior)
+- `last` is now CLI-only flag
+- Cache now stores timestamp and expires after 1 week
+
+### Fixed
+- Cache validation: expired cache entries are ignored
+
+---
+
+## [0.1.0] - 2026-09-10
+
+### Added
+- Initial release
+- Multi-workspace export
+- Incremental export with state tracking
+- Monthly CSV output per workspace/year
+- Config file support (`~/.config/clockify-export/config.toml`)
+- `--full`, `--from`, `--last`, `--refetch`, `--workspace`, `--status` flags
+- Zero dependencies (stdlib only)
+- systemd timer support for scheduled exports

{clockify_export-0.1.1 → clockify_export-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: clockify-export
-Version: 0.1.1
+Version: 0.1.4
 Summary: Export Clockify time entries to CSV with incremental support
 Project-URL: Homepage, https://github.com/ptandler/clockify-export
 Project-URL: Repository, https://github.com/ptandler/clockify-export
@@ -191,3 +191,55 @@ always consistent.
 ## License
 
 MIT
+
+## Schedule Daily Export via systemd
+
+Use can use systemd timers to call the export regularily.
+
+### Install with mise
+
+[mise](https://mise.jdx.dev) can install the systemd unit automatically:
+
+```bash
+mise install-systemd
+```
+
+This copies the service/timer files to `~/.config/systemd/user/` and enables the timer.
+
+### Systemd Timer (daily export)
+
+To run the export automatically every day as a systemd user unit:
+
+#### 1. Install the service and timer
+
+```bash
+cp systemd/clockify-export.service "$HOME/.config/systemd/user/"
+cp systemd/clockify-export.timer "$HOME/.config/systemd/user/"
+systemctl --user daemon-reload
+systemctl --user enable --now clockify-export.timer
+```
+
+#### 2. Set your API key
+
+The unit reads the Clockify API key from the config file.
+You can create one via `clockify-export --init-config` and ensure the
+`api_key` is set in `~/.config/clockify-export/config.toml`.
+
+#### 3. Manage the timer
+
+The default timer is for daily export. Feel free to adjust `OnUnitActiveSec` if desired.
+
+```bash
+# View status
+systemctl --user status clockify-export.timer
+systemctl --user status clockify-export.service
+
+# Manual run
+systemctl --user clockify-export
+
+# Disable
+systemctl --user disable --now clockify-export.timer
+```
+
+> Note: The service uses `Type=oneshot` so it completes and exits each day.
+> Logs can be viewed with `journalctl --user -u clockify-export.service`.

clockify_export-0.1.4/PLAN.md

@@ -0,0 +1,48 @@
+# Development Plan
+
+## Current Version: 0.2.0
+
+---
+
+## ✅ Completed (v0.2.0)
+
+- [x] Cache for workspaces, projects, clients, tags (1-week expiry)
+- [x] `--no-cache` flag to bypass cache
+- [x] Current month CSV includes date in filename (e.g., `...-2026-09-17.csv`)
+- [x] Auto-cleanup of old current-month files
+- [x] Mutually exclusive `--from`, `--last`, `--refetch` options
+- [x] Removed `last` from config file (only CLI)
+
+---
+
+## 🔄 In Progress
+
+- [ ] Auto-refresh cache when unknown project/client/tag ID encountered during entry processing
+
+---
+
+## 📋 Backlog
+
+### Cache Improvements
+- [ ] Add cache stats/debug command (`--cache-status`)
+- [ ] Add config option for cache TTL (default 1 week)
+- [ ] Cache workspaces list (currently only workspace data cached)
+
+### Export Features
+- [ ] Add `--dry-run` to show what would be exported without writing
+- [ ] Add `--format json` output option
+- [ ] Support exporting to single combined CSV (optionally)
+
+### Reliability
+- [ ] Add retry logic with exponential backoff for API requests
+- [ ] Handle HTTP 429 rate limits gracefully (wait and retry)
+
+### Developer Experience
+- [ ] Add `--verbose` / `--quiet` flags
+- [ ] Add progress bar for long exports
+
+---
+
+## 🐛 Known Issues
+
+- None currently

{clockify_export-0.1.1 → clockify_export-0.1.4}/README.md

@@ -168,3 +168,55 @@ always consistent.
 ## License
 
 MIT
+
+## Schedule Daily Export via systemd
+
+Use can use systemd timers to call the export regularily.
+
+### Install with mise
+
+[mise](https://mise.jdx.dev) can install the systemd unit automatically:
+
+```bash
+mise install-systemd
+```
+
+This copies the service/timer files to `~/.config/systemd/user/` and enables the timer.
+
+### Systemd Timer (daily export)
+
+To run the export automatically every day as a systemd user unit:
+
+#### 1. Install the service and timer
+
+```bash
+cp systemd/clockify-export.service "$HOME/.config/systemd/user/"
+cp systemd/clockify-export.timer "$HOME/.config/systemd/user/"
+systemctl --user daemon-reload
+systemctl --user enable --now clockify-export.timer
+```
+
+#### 2. Set your API key
+
+The unit reads the Clockify API key from the config file.
+You can create one via `clockify-export --init-config` and ensure the
+`api_key` is set in `~/.config/clockify-export/config.toml`.
+
+#### 3. Manage the timer
+
+The default timer is for daily export. Feel free to adjust `OnUnitActiveSec` if desired.
+
+```bash
+# View status
+systemctl --user status clockify-export.timer
+systemctl --user status clockify-export.service
+
+# Manual run
+systemctl --user clockify-export
+
+# Disable
+systemctl --user disable --now clockify-export.timer
+```
+
+> Note: The service uses `Type=oneshot` so it completes and exits each day.
+> Logs can be viewed with `journalctl --user -u clockify-export.service`.

clockify_export-0.1.4/mise-tasks/bump-version

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+uv version --bump $@
+uv run pytest
+git add -A
+git commit -m "chore: release v$(uv version --short)"
+git tag "v$(uv version --short)"
+git push && git push --tags

{clockify_export-0.1.1 → clockify_export-0.1.4}/mise.toml

@@ -11,4 +11,5 @@ export = "uv run clockify-export --output-dir ./export"
 export-full = "uv run clockify-export --full --output-dir ./export"
 status = "uv run clockify-export --status"
 init-config = "uv run clockify-export --init-config"
-test = "uv run python -c \"from clockify_export.api import ClockifyAPI; print('import ok')\""
+test = "uv run python -c \"from clockify_export.api import ClockifyAPI; print('import ok')\""
+install-systemd = "cp systemd/clockify-export.service \"$HOME/.config/systemd/user/\" && cp systemd/clockify-export.timer \"$HOME/.config/systemd/user/\" && systemctl --user daemon-reload && systemctl --user enable --now clockify-export.timer"

{clockify_export-0.1.1 → clockify_export-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "clockify-export"
-version = "0.1.1"
+version = "0.1.4"
 description = "Export Clockify time entries to CSV with incremental support"
 readme = "README.md"
 requires-python = ">=3.11"

clockify_export-0.1.4/src/clockify_export/__init__.py

@@ -0,0 +1,8 @@
+"""clockify-export — export Clockify time entries to CSV."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("clockify-export")
+except PackageNotFoundError:  # pragma: no cover - running from source without install
+    __version__ = "0.0.0"

clockify_export-0.1.4/src/clockify_export/cache.py

@@ -0,0 +1,90 @@
+"""Cache management for Clockify data."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+
+CACHE_DIR = ".cache"
+DEFAULT_MAX_AGE_SECONDS = 7 * 24 * 60 * 60  # 1 week
+
+
+def get_cache_dir(export_dir: Path) -> Path:
+    """Get the cache directory path."""
+    return export_dir / CACHE_DIR
+
+
+def _read_json(path: Path) -> dict | None:
+    """Read JSON file, return None if not exists or invalid."""
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def _write_json(path: Path, data: dict) -> None:
+    """Write JSON file, creating parent directories."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+
+
+def load_cache(export_dir: Path, name: str, max_age_seconds: int = DEFAULT_MAX_AGE_SECONDS) -> dict | None:
+    """Load cached data by name, return None if expired or missing."""
+    cache_dir = get_cache_dir(export_dir)
+    data = _read_json(cache_dir / f"{name}.json")
+    if data is None:
+        return None
+    # Check age
+    cached_time = data.get("_cached_at", 0)
+    if time.time() - cached_time > max_age_seconds:
+        return None
+    return data
+
+
+def save_cache(export_dir: Path, name: str, data: dict) -> bool:
+    """Save data to cache if changed. Returns True if written."""
+    cache_dir = get_cache_dir(export_dir)
+    path = cache_dir / f"{name}.json"
+    existing = _read_json(path)
+    if existing == data:
+        return False
+    # Add timestamp
+    data_with_ts = {"_cached_at": time.time(), **data}
+    _write_json(path, data_with_ts)
+    return True
+
+
+def load_workspaces(export_dir: Path, max_age_seconds: int = DEFAULT_MAX_AGE_SECONDS) -> list[dict] | None:
+    """Load cached workspaces."""
+    data = load_cache(export_dir, "workspaces", max_age_seconds)
+    return data.get("workspaces") if data else None
+
+
+def save_workspaces(export_dir: Path, workspaces: list[dict]) -> bool:
+    """Save workspaces to cache if changed."""
+    return save_cache(export_dir, "workspaces", {"workspaces": workspaces})
+
+
+def load_workspace_data(export_dir: Path, workspace_id: str, max_age_seconds: int = DEFAULT_MAX_AGE_SECONDS) -> dict | None:
+    """Load cached workspace data (projects, clients, tags)."""
+    return load_cache(export_dir, f"workspace_{workspace_id}", max_age_seconds)
+
+
+def save_workspace_data(
+    export_dir: Path,
+    workspace_id: str,
+    projects: list[dict],
+    clients: list[dict],
+    tags: list[dict],
+) -> bool:
+    """Save workspace data to cache if changed."""
+    data = {
+        "projects": projects,
+        "clients": clients,
+        "tags": tags,
+    }
+    return save_cache(export_dir, f"workspace_{workspace_id}", data)

{clockify_export-0.1.1 → clockify_export-0.1.4}/src/clockify_export/cli.py

@@ -7,14 +7,22 @@ import sys
 from datetime import datetime, timedelta, timezone
 
 from .api import ClockifyAPI, ClockifyError
-from .config import CONFIG_FILE, Config, create_config_file, get_last_exported, set_last_exported
+from .config import CONFIG_FILE, Config, CONFIG_HELP, create_config_file, get_last_exported, set_last_exported, parse_from_date, calculate_last_months, calculate_refetch_date
 from .export import export_workspace
+from . import __version__
 
 
 def main() -> None:
     parser = argparse.ArgumentParser(
         prog="clockify-export",
         description="Export Clockify time entries to CSV",
+        epilog=CONFIG_HELP,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
     )
     parser.add_argument(
         "--output-dir", "-o",
@@ -33,12 +41,27 @@ def main() -> None:
         action="store_true",
         help="Full export: ignore incremental state, export everything",
     )
-    parser.add_argument(
+
+    # Mutually exclusive date range options
+    date_group = parser.add_mutually_exclusive_group()
+    date_group.add_argument(
         "--from",
         dest="from_date",
         type=str,
         default=None,
-        help="Export entries from this date (YYYY-MM-DD). Overrides incremental state.",
+        help="Export entries from this date (YYYY-MM or YYYY-MM-DD). Always starts at beginning of month. Overrides incremental state.",
+    )
+    date_group.add_argument(
+        "--last",
+        type=int,
+        default=None,
+        help="Export the last N complete months (e.g., --last 3 exports last 3 complete months).",
+    )
+    date_group.add_argument(
+        "--refetch",
+        type=int,
+        default=None,
+        help="Re-fetch N months back from last exported date (can be set in config). Useful if entries were modified.",
     )
     parser.add_argument(
         "--workspace",
@@ -56,6 +79,11 @@ def main() -> None:
         action="store_true",
         help="Create ~/.config/clockify-export/config.toml and exit",
     )
+    parser.add_argument(
+        "--no-cache",
+        action="store_true",
+        help="Bypass cache, fetch fresh projects/clients/tags from API",
+    )
     args = parser.parse_args()
 
     if args.init_config:
@@ -131,9 +159,21 @@ def main() -> None:
         # Determine start date
         since = None
         if cfg.from_date:
-            # Explicit --from flag overrides everything
-            since = datetime.strptime(cfg.from_date, "%Y-%m-%d").replace(tzinfo=timezone.utc)
-            print(f"  --from: fetching since {cfg.from_date}")
+            # Explicit --from flag overrides everything, always start at beginning of month
+            since = parse_from_date(cfg.from_date)
+            print(f"  --from: fetching since {since.strftime('%Y-%m-%d')}")
+        elif args.last is not None and args.last > 0:
+            # --last N: export last N complete months
+            since = calculate_last_months(args.last)
+            print(f"  --last {args.last}: fetching since {since.strftime('%Y-%m-%d')} (last {args.last} complete months)")
+        elif cfg.refetch > 0:
+            # --refetch N: re-fetch N months back from last exported date
+            last = get_last_exported(ws_id)
+            since = calculate_refetch_date(cfg.refetch, last)
+            if since:
+                print(f"  --refetch {cfg.refetch}: re-fetching from {since.strftime('%Y-%m-%d')} (last exported: {last})")
+            else:
+                print(f"  --refetch {cfg.refetch}: no prior export found, skipping refetch")
         elif not cfg.full:
             last = get_last_exported(ws_id)
             if last:
@@ -146,16 +186,14 @@ def main() -> None:
             print("  Full export mode")
 
         try:
-            counts = export_workspace(api, ws_id, ws_name, output_dir, since=since)
+            counts, latest_entry_dt = export_workspace(
+                api, ws_id, ws_name, output_dir, since=since,
+                use_cache=not args.no_cache,
+            )
             if counts:
-                # Update state to the latest entry date
-                latest_month = max(counts.keys())
-                latest_ts = datetime.strptime(latest_month, "%Y-%m").replace(tzinfo=timezone.utc)
-                # Set to end of month to mark the whole month as exported
-                from calendar import monthrange
-                _, last_day = monthrange(latest_ts.year, latest_ts.month)
-                latest_ts = latest_ts.replace(day=last_day)
-                set_last_exported(ws_id, latest_ts.isoformat())
+                # Update state to the actual latest entry date (not end of month)
+                if latest_entry_dt:
+                    set_last_exported(ws_id, latest_entry_dt.isoformat())
                 total = sum(counts.values())
                 print(f"  Total: {total} entries across {len(counts)} month(s)")
             else:

{clockify_export-0.1.1 → clockify_export-0.1.4}/src/clockify_export/config.py

@@ -25,8 +25,22 @@ STATE_FILE = CONFIG_DIR / "state.json"
 DEFAULTS = {
     "api_key": None,
     "export_dir": "export",
+    "refetch": 1,
 }
 
+CONFIG_HELP = """
+Supported configuration options (config.toml):
+  api_key       - Clockify API key (required)
+  export_dir    - Output directory for CSV files (default: "export")
+  refetch       - Number of months to re-fetch from last exported date (default: 1)
+
+Example config.toml:
+  # Clockify export configuration
+  api_key = "YOUR_API_KEY"
+  export_dir = "export"
+  refetch = 1
+"""
+
 
 @dataclass
 class Config:
@@ -35,6 +49,7 @@ class Config:
     full: bool = False
     workspaces: list[str] = field(default_factory=list)
     from_date: str | None = None
+    refetch: int = 0
 
     @classmethod
     def load(cls, args=None) -> Config:
@@ -61,6 +76,12 @@ class Config:
         full = getattr(args, "full", False) if args else False
         workspaces = getattr(args, "workspace", []) if args else []
         from_date = getattr(args, "from_date", None) if args else None
+        
+        # For refetch: CLI arg wins, then config file, then default
+        if args and getattr(args, "refetch", None) is not None:
+            refetch = args.refetch
+        else:
+            refetch = file_cfg.get("refetch", DEFAULTS["refetch"])
 
         return cls(
             api_key=api_key or "",
@@ -68,6 +89,7 @@ class Config:
             full=full,
             workspaces=workspaces or [],
             from_date=from_date,
+            refetch=refetch,
         )
 
 
@@ -111,10 +133,48 @@ def create_config_file(api_key: str = "", export_dir: str = "export") -> Path:
         "# Clockify export configuration\n"
         f'api_key = "{api_key}"\n'
         f'export_dir = "{export_dir}"\n'
+        "# Number of months to re-fetch from last exported date (default: 1)\n"
+        "refetch = 1\n"
     )
     return CONFIG_FILE
 
 
+def parse_from_date(date_str: str) -> datetime:
+    """Parse --from date string (YYYY-MM or YYYY-MM-DD) and return first day of that month."""
+    parts = date_str.split("-")
+    if len(parts) < 2:
+        raise ValueError(f"Invalid date format: {date_str}. Use YYYY-MM or YYYY-MM-DD")
+    year = int(parts[0])
+    month = int(parts[1])
+    return datetime(year, month, 1, tzinfo=timezone.utc)
+
+
+def calculate_last_months(last: int) -> datetime:
+    """Calculate the first day of the month that is 'last' complete months ago."""
+    now = datetime.now(timezone.utc)
+    # Go back 'last' months from the current month, then get the first day of that month
+    # If last=1, we want last complete month (not current month)
+    year = now.year
+    month = now.month - last
+    while month <= 0:
+        month += 12
+        year -= 1
+    return datetime(year, month, 1, tzinfo=timezone.utc)
+
+
+def calculate_refetch_date(refetch: int, last_exported: str | None) -> datetime | None:
+    """Calculate the date to start re-fetching from, going back 'refetch' months from last exported."""
+    if not last_exported or refetch <= 0:
+        return None
+    last_dt = datetime.fromisoformat(last_exported)
+    year = last_dt.year
+    month = last_dt.month - refetch
+    while month <= 0:
+        month += 12
+        year -= 1
+    return datetime(year, month, 1, tzinfo=timezone.utc)
+
+
 def get_state() -> dict:
     if STATE_FILE.exists():
         try:

{clockify_export-0.1.1 → clockify_export-0.1.4}/src/clockify_export/export.py

@@ -4,10 +4,11 @@ from __future__ import annotations
 
 import csv
 import re
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 
 from .api import ClockifyAPI, parse_iso_duration_to_hours
+from .cache import load_workspace_data, save_workspace_data, DEFAULT_MAX_AGE_SECONDS
 
 CSV_HEADERS = [
     "Date",
@@ -46,30 +47,67 @@ def _sanitize_dirname(name: str) -> str:
     return re.sub(r'[<>:"/\\|?*]', "_", name).strip()
 
 
+def _is_current_month(year: str, month: str) -> bool:
+    """Check if the given year/month is the current month."""
+    now = datetime.now(timezone.utc)
+    return int(year) == now.year and int(month) == now.month
+
+
+def _cleanup_old_current_month_files(year_dir: Path, safe_ws_name: str, year: str, month: str, current_date_str: str) -> None:
+    """Remove old current-month files with different dates."""
+    pattern = f"{safe_ws_name}_{year}-{month}-*.csv"
+    for old_file in year_dir.glob(pattern):
+        if current_date_str not in old_file.name:
+            print(f"  Removing old current-month file: {old_file.relative_to(year_dir.parent.parent)}")
+            old_file.unlink(missing_ok=True)
+
+
 def export_workspace(
     api: ClockifyAPI,
     workspace_id: str,
     workspace_name: str,
     output_dir: Path,
     since: datetime | None = None,
-) -> dict[str, int]:
+    use_cache: bool = True,
+    max_age_seconds: int = DEFAULT_MAX_AGE_SECONDS,
+) -> tuple[dict[str, int], datetime | None]:
     """Export all time entries for a workspace, grouped by year/month.
 
     Directory structure: {output_dir}/{workspace_name}/{year}/{MM}.csv
-    Returns dict of {YYYY-MM: row_count}.
+    Returns (counts_dict, latest_entry_date) where latest_entry_date is the
+    most recent entry's start time (or None if no entries).
     """
     # Resolve current user
     user = api.get_current_user()
     user_id = user["id"]
     print(f"  User: {user.get('name', user_id)}")
 
-    # Fetch lookup tables
-    print("  Fetching projects...")
-    projects = {p["id"]: p for p in api.get_projects(workspace_id)}
-    print("  Fetching clients...")
-    clients = {c["id"]: c for c in api.get_clients(workspace_id)}
-    print("  Fetching tags...")
-    tags = {t["id"]: t for t in api.get_tags(workspace_id)}
+    # Try to load from cache first
+    if use_cache:
+        cached = load_workspace_data(output_dir, workspace_id, max_age_seconds)
+        if cached:
+            projects = {p["id"]: p for p in cached.get("projects", [])}
+            clients = {c["id"]: c for c in cached.get("clients", [])}
+            tags = {t["id"]: t for t in cached.get("tags", [])}
+            print("  Using cached projects, clients, tags")
+        else:
+            # Fetch lookup tables
+            print("  Fetching projects...")
+            projects = {p["id"]: p for p in api.get_projects(workspace_id)}
+            print("  Fetching clients...")
+            clients = {c["id"]: c for c in api.get_clients(workspace_id)}
+            print("  Fetching tags...")
+            tags = {t["id"]: t for t in api.get_tags(workspace_id)}
+            # Save to cache
+            save_workspace_data(output_dir, workspace_id, list(projects.values()), list(clients.values()), list(tags.values()))
+    else:
+        # Fetch lookup tables (no cache)
+        print("  Fetching projects...")
+        projects = {p["id"]: p for p in api.get_projects(workspace_id)}
+        print("  Fetching clients...")
+        clients = {c["id"]: c for c in api.get_clients(workspace_id)}
+        print("  Fetching tags...")
+        tags = {t["id"]: t for t in api.get_tags(workspace_id)}
 
     # Fetch time entries first to know which projects have entries
     print("  Fetching time entries...")
@@ -91,13 +129,16 @@ def export_workspace(
         if client_id and client_id in clients:
             project_client[p["id"]] = clients[client_id].get("name", "")
 
-    # Group by year/month
+    # Group by year/month, track latest entry date
     by_month: dict[str, list[dict]] = {}
+    latest_entry_dt: datetime | None = None
     for entry in entries:
         start_str = entry.get("timeInterval", {}).get("start")
         if not start_str:
             continue
         dt = datetime.fromisoformat(start_str)
+        if latest_entry_dt is None or dt > latest_entry_dt:
+            latest_entry_dt = dt
         month_key = dt.strftime("%Y-%m")
         by_month.setdefault(month_key, []).append(entry)
 
@@ -105,12 +146,19 @@ def export_workspace(
     safe_ws_name = _sanitize_dirname(workspace_name)
     ws_dir = output_dir / safe_ws_name
     counts: dict[str, int] = {}
+    now = datetime.now(timezone.utc)
+    current_date_str = now.strftime("%Y-%m-%d")
     for month_key, month_entries in sorted(by_month.items()):
         year, month = month_key.split("-")
         year_dir = ws_dir / year
         year_dir.mkdir(parents=True, exist_ok=True)
-        # Filename carries workspace + year so files stay identifiable when moved
-        csv_path = year_dir / f"{safe_ws_name}_{year}-{month}.csv"
+
+        # For current month, include date in filename; otherwise just year-month
+        if _is_current_month(year, month):
+            csv_filename = f"{safe_ws_name}_{year}-{month}-{current_date_str}.csv"
+        else:
+            csv_filename = f"{safe_ws_name}_{year}-{month}.csv"
+        csv_path = year_dir / csv_filename
 
         with open(csv_path, "w", newline="", encoding="utf-8") as f:
             writer = csv.writer(f)
@@ -150,7 +198,11 @@ def export_workspace(
                     (entry.get("timeInterval") or {}).get("timeZone", ""),
                 ])
 
+        # Clean up old current-month files if this is the current month
+        if _is_current_month(year, month):
+            _cleanup_old_current_month_files(year_dir, safe_ws_name, year, month, current_date_str)
+
         counts[month_key] = len(month_entries)
         print(f"  Wrote {csv_path.relative_to(output_dir)} ({len(month_entries)} entries)")
 
-    return counts
+    return counts, latest_entry_dt

clockify_export-0.1.4/systemd/clockify-export.service

@@ -0,0 +1,8 @@
+[Unit]
+Description=Clockify Export - Daily export of time entries to CSV
+After=network.target
+
+[Service]
+Type=oneshot
+ExecStart=%h/.local/bin/clockify-export
+WorkingDirectory=%h

clockify_export-0.1.4/systemd/clockify-export.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Run Clockify Export daily
+
+[Timer]
+OnBootSec=15min
+OnUnitActiveSec=24h
+Persistent=true
+
+[Install]
+WantedBy=timers.target

{clockify_export-0.1.1 → clockify_export-0.1.4}/uv.lock

@@ -4,5 +4,5 @@ requires-python = ">=3.11"
 
 [[package]]
 name = "clockify-export"
-version = "0.1.1"
+version = "0.1.4"
 source = { editable = "." }

clockify_export-0.1.1/.idea/misc.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="ProjectRootManager">
-    <output url="file://$PROJECT_DIR$/out" />
-  </component>
-</project>