workfold 0.1.0a1__tar.gz

workfold-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan T. Müller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

workfold-0.1.0a1/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include tests *.py
+include THIRD_PARTY_NOTICES.md

workfold-0.1.0a1/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: workfold
+Version: 0.1.0a1
+Summary: Fold local Git and filesystem timestamp activity onto a representative week.
+Author-email: "Jan T. Müller" <mail@jantmueller.com>
+License-Expression: MIT
+Project-URL: homepage, https://github.com/janthmueller/workfold
+Project-URL: documentation, https://janthmueller.github.io/workfold/
+Project-URL: source, https://github.com/janthmueller/workfold
+Project-URL: tracker, https://github.com/janthmueller/workfold/issues
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pathspec<2,>=1
+Requires-Dist: rich<15,>=14
+Requires-Dist: tzdata>=2025.2; sys_platform == "win32"
+Requires-Dist: tzlocal<6,>=5
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=6; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Provides-Extra: release
+Requires-Dist: build>=1; extra == "release"
+Requires-Dist: pyinstaller>=6; extra == "release"
+Requires-Dist: python-semantic-release<11,>=10; extra == "release"
+Requires-Dist: twine>=5; extra == "release"
+Dynamic: license-file
+
+# Workfold
+
+Workfold is a private, local CLI that folds timestamped activity from Git and
+filesystem metadata onto one representative Monday-to-Sunday week. It makes the
+shape of recorded activity easy to scan and marks events outside a configured
+working schedule without pretending to measure hours worked.
+
+```text
+Time          Mon       Tue       Wed       Thu       Fri       Sat       Sun
+07:48–08:12  ○●■       ●
+              ⋮ 1h 8m
+09:20–09:29                      ■●
+```
+
+Terminal output starts directly with this matrix, followed by a content-aware
+symbol key and three direct statistic rows: total events, the inside/outside
+schedule split, and the weekday/weekend calendar split. There is no summary
+heading. The key has no heading and names only categories actually
+visible in the matrix; its `×N` explanation appears only when a cell uses exact
+count notation. The configured working hours follow on their own left-aligned
+line. Schedule and calendar percentages each use the total event count as their
+denominator; weekend activity may also be outside the configured schedule. A
+normal complete run stops there.
+`--verbose` adds scope, period, the full successful coverage status, operational
+metadata, and the detailed coverage ledger. Use `--coverage` when the ledger is
+wanted without those verbose details. Partial collection, explicit narrowing,
+unsupported capabilities, and nonzero display cropping remain visible by
+default as exception notices; compact output never hides those limitations.
+
+Each ordinary symbol is one activity marker. Circles are Git and squares are
+filesystem evidence; filled shapes are inside working hours and hollow red
+shapes are outside. Git-inside markers are green and filesystem-inside markers
+are blue. Shapes preserve the same meaning with `--no-color`. Rows are greedy,
+globally aligned time clusters (one hour by default), so empty time disappears
+without losing the order expressed by the labels.
+
+## Status
+
+Workfold is an alpha, terminal-only CLI with its sparse terminal renderer and
+local collection pipeline implemented end to end. Git commits, per-file
+changes, annotated tags, local
+reflogs, filesystem metadata, combined-source views, the `full` profile, strict
+coverage accounting, and outside-event listing share the same normalized
+pipeline.
+
+The [documentation](https://janthmueller.github.io/workfold/) covers CLI usage,
+accuracy, and development. The Astro site in `docs/` documents the terminal
+product; it is not an HTML reporting feature.
+
+## Install
+
+Workfold requires Python 3.10 or newer. Git collection uses the installed
+`git` executable and never contacts a remote.
+
+Install Workfold from PyPI:
+
+```bash
+pip install workfold
+workfold --help
+```
+
+For an isolated CLI environment, `uv tool install workfold` and
+`pipx install workfold` are supported alternatives. Standalone archives for
+supported platforms are attached to
+[GitHub releases](https://github.com/janthmueller/workfold/releases).
+
+## Quick Git view
+
+Run inside a repository to fold the current ISO week's author timestamps from
+commits reachable through all local refs:
+
+```bash
+workfold
+```
+
+This uses the default selectors `-t this-week -m git -p standard`.
+`-t/--time` also accepts an ISO week, repeated ISO weeks, an inclusive
+`DATE..DATE` range with either endpoint open, or `all`. `-m/--mode` accepts
+`git`, `fs`, or `all`; changing time never changes mode and vice versa.
+
+Common selections include:
+
+```bash
+workfold . -t 2026-W31
+workfold . -t 2026-W30 -t 2026-W31
+workfold . -t 2026-07-01..2026-07-31
+workfold . -t 2026-01-01..
+workfold . -t all -m git --git-commit-times author,committer --coverage
+workfold . --hours 'Mo-Thu 08:00-16:30; Fr 08:00-14:00'
+workfold . --cluster-window 30s
+workfold . --cluster-window 10m
+workfold . --cluster-window 1h5m
+workfold . --cluster-window '1h 5m'
+workfold . --timezone Europe/Berlin --list-outside --limit 50
+```
+
+Chart band labels always use `HH:MM`, even for second-level cluster windows and
+events. Exact seconds and nanoseconds remain in normalized provenance and the
+outside-hours event list.
+
+For portable Git-object evidence across all available history, use:
+
+```bash
+workfold . -t all -m git -p portable
+```
+
+The portable profile includes commit author and committer timestamps plus
+annotated-tag tagger timestamps. It does not use filesystem metadata or local
+reflogs, contact a remote, or claim to show when an object was published
+remotely.
+
+The exhaustive local command is:
+
+```bash
+workfold . -t all -m all -p full
+```
+
+`-p/--profile` defaults to `standard`. The `full` profile broadens timestamp
+and record collection only inside the selected time and mode. It never changes
+either selector. With `-m all`, it requests all
+supported Git and filesystem evidence, ignored entries, and all local refs. It
+changes collection scope only: detailed ledger output still requires
+`--coverage` or `--verbose`. It does not parse date-like text inside files.
+
+## Accuracy and privacy
+
+A Workfold event is a discrete timestamp observation, not a work session. Git
+file changes are derived from first-parent tree differences, not stored human
+actions. Commits can be rewritten; annotated tags have independent tagger dates
+while lightweight tags do not; and reflogs can expire. Filesystem metadata is a
+mutable current snapshot: Linux birth time is collected through `statx` when
+the filesystem returns it, birth time remains platform-dependent elsewhere,
+ctime is metadata-change time, and atime may be unreliable. Workfold cannot
+recover unsaved edit sessions, deleted untracked files, or earlier metadata
+values.
+
+Collection remains local. No Git hosting API, telemetry service, web server, or
+network collector is part of the MVP. Coverage reports account for captured,
+filtered, unavailable, unsupported, and unreadable timestamps within the exact
+requested scope instead of claiming unqualified completeness.
+
+## Development
+
+The project intentionally uses a flat Python package: the implementation is in
+`workfold/`, with no `src/` wrapper.
+
+```bash
+nix develop
+uv sync --extra dev
+uv run pytest
+ruff check .
+ruff format --check .
+uv run pyright
+uv run workfold --help
+```
+
+Build the Python distributions and validate the Astro documentation with:
+
+```bash
+uv build
+nix run .#docs-check
+nix run .#docs-build
+```
+
+Start the documentation site locally with `nix run .#docs-dev`.

workfold-0.1.0a1/README.md

@@ -0,0 +1,165 @@
+# Workfold
+
+Workfold is a private, local CLI that folds timestamped activity from Git and
+filesystem metadata onto one representative Monday-to-Sunday week. It makes the
+shape of recorded activity easy to scan and marks events outside a configured
+working schedule without pretending to measure hours worked.
+
+```text
+Time          Mon       Tue       Wed       Thu       Fri       Sat       Sun
+07:48–08:12  ○●■       ●
+              ⋮ 1h 8m
+09:20–09:29                      ■●
+```
+
+Terminal output starts directly with this matrix, followed by a content-aware
+symbol key and three direct statistic rows: total events, the inside/outside
+schedule split, and the weekday/weekend calendar split. There is no summary
+heading. The key has no heading and names only categories actually
+visible in the matrix; its `×N` explanation appears only when a cell uses exact
+count notation. The configured working hours follow on their own left-aligned
+line. Schedule and calendar percentages each use the total event count as their
+denominator; weekend activity may also be outside the configured schedule. A
+normal complete run stops there.
+`--verbose` adds scope, period, the full successful coverage status, operational
+metadata, and the detailed coverage ledger. Use `--coverage` when the ledger is
+wanted without those verbose details. Partial collection, explicit narrowing,
+unsupported capabilities, and nonzero display cropping remain visible by
+default as exception notices; compact output never hides those limitations.
+
+Each ordinary symbol is one activity marker. Circles are Git and squares are
+filesystem evidence; filled shapes are inside working hours and hollow red
+shapes are outside. Git-inside markers are green and filesystem-inside markers
+are blue. Shapes preserve the same meaning with `--no-color`. Rows are greedy,
+globally aligned time clusters (one hour by default), so empty time disappears
+without losing the order expressed by the labels.
+
+## Status
+
+Workfold is an alpha, terminal-only CLI with its sparse terminal renderer and
+local collection pipeline implemented end to end. Git commits, per-file
+changes, annotated tags, local
+reflogs, filesystem metadata, combined-source views, the `full` profile, strict
+coverage accounting, and outside-event listing share the same normalized
+pipeline.
+
+The [documentation](https://janthmueller.github.io/workfold/) covers CLI usage,
+accuracy, and development. The Astro site in `docs/` documents the terminal
+product; it is not an HTML reporting feature.
+
+## Install
+
+Workfold requires Python 3.10 or newer. Git collection uses the installed
+`git` executable and never contacts a remote.
+
+Install Workfold from PyPI:
+
+```bash
+pip install workfold
+workfold --help
+```
+
+For an isolated CLI environment, `uv tool install workfold` and
+`pipx install workfold` are supported alternatives. Standalone archives for
+supported platforms are attached to
+[GitHub releases](https://github.com/janthmueller/workfold/releases).
+
+## Quick Git view
+
+Run inside a repository to fold the current ISO week's author timestamps from
+commits reachable through all local refs:
+
+```bash
+workfold
+```
+
+This uses the default selectors `-t this-week -m git -p standard`.
+`-t/--time` also accepts an ISO week, repeated ISO weeks, an inclusive
+`DATE..DATE` range with either endpoint open, or `all`. `-m/--mode` accepts
+`git`, `fs`, or `all`; changing time never changes mode and vice versa.
+
+Common selections include:
+
+```bash
+workfold . -t 2026-W31
+workfold . -t 2026-W30 -t 2026-W31
+workfold . -t 2026-07-01..2026-07-31
+workfold . -t 2026-01-01..
+workfold . -t all -m git --git-commit-times author,committer --coverage
+workfold . --hours 'Mo-Thu 08:00-16:30; Fr 08:00-14:00'
+workfold . --cluster-window 30s
+workfold . --cluster-window 10m
+workfold . --cluster-window 1h5m
+workfold . --cluster-window '1h 5m'
+workfold . --timezone Europe/Berlin --list-outside --limit 50
+```
+
+Chart band labels always use `HH:MM`, even for second-level cluster windows and
+events. Exact seconds and nanoseconds remain in normalized provenance and the
+outside-hours event list.
+
+For portable Git-object evidence across all available history, use:
+
+```bash
+workfold . -t all -m git -p portable
+```
+
+The portable profile includes commit author and committer timestamps plus
+annotated-tag tagger timestamps. It does not use filesystem metadata or local
+reflogs, contact a remote, or claim to show when an object was published
+remotely.
+
+The exhaustive local command is:
+
+```bash
+workfold . -t all -m all -p full
+```
+
+`-p/--profile` defaults to `standard`. The `full` profile broadens timestamp
+and record collection only inside the selected time and mode. It never changes
+either selector. With `-m all`, it requests all
+supported Git and filesystem evidence, ignored entries, and all local refs. It
+changes collection scope only: detailed ledger output still requires
+`--coverage` or `--verbose`. It does not parse date-like text inside files.
+
+## Accuracy and privacy
+
+A Workfold event is a discrete timestamp observation, not a work session. Git
+file changes are derived from first-parent tree differences, not stored human
+actions. Commits can be rewritten; annotated tags have independent tagger dates
+while lightweight tags do not; and reflogs can expire. Filesystem metadata is a
+mutable current snapshot: Linux birth time is collected through `statx` when
+the filesystem returns it, birth time remains platform-dependent elsewhere,
+ctime is metadata-change time, and atime may be unreliable. Workfold cannot
+recover unsaved edit sessions, deleted untracked files, or earlier metadata
+values.
+
+Collection remains local. No Git hosting API, telemetry service, web server, or
+network collector is part of the MVP. Coverage reports account for captured,
+filtered, unavailable, unsupported, and unreadable timestamps within the exact
+requested scope instead of claiming unqualified completeness.
+
+## Development
+
+The project intentionally uses a flat Python package: the implementation is in
+`workfold/`, with no `src/` wrapper.
+
+```bash
+nix develop
+uv sync --extra dev
+uv run pytest
+ruff check .
+ruff format --check .
+uv run pyright
+uv run workfold --help
+```
+
+Build the Python distributions and validate the Astro documentation with:
+
+```bash
+uv build
+nix run .#docs-check
+nix run .#docs-build
+```
+
+Start the documentation site locally with `nix run .#docs-dev`.

workfold-0.1.0a1/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,19 @@
+# Third-party notices for standalone Workfold bundles
+
+The standalone archives are produced with PyInstaller and include portions of
+the Python runtime plus Workfold's runtime dependencies. Their exact license
+files are copied into the archive's `licenses/` directory at build time.
+
+- Python and its standard library: Python Software Foundation License.
+- pathspec: Mozilla Public License 2.0.
+- Rich: MIT License.
+- markdown-it-py and mdurl: MIT License.
+- Pygments: BSD 2-Clause License.
+- tzlocal: MIT License.
+- tzdata, when bundled on Windows: licenses shipped by the Python tzdata
+  distribution and the underlying IANA time-zone database.
+- PyInstaller bootloader: GNU General Public License with PyInstaller's
+  bootloader exception; its shipped notices are included.
+
+This notice is informational. The complete license texts included beside the
+binary control the corresponding components.

workfold-0.1.0a1/pyproject.toml

@@ -0,0 +1,107 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "workfold"
+version = "0.1.0-alpha.1"
+description = "Fold local Git and filesystem timestamp activity onto a representative week."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "pathspec>=1,<2",
+    "rich>=14,<15",
+    "tzdata>=2025.2; sys_platform == 'win32'",
+    "tzlocal>=5,<6",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[[project.authors]]
+name = "Jan T. Müller"
+email = "mail@jantmueller.com"
+
+[project.urls]
+homepage = "https://github.com/janthmueller/workfold"
+documentation = "https://janthmueller.github.io/workfold/"
+source = "https://github.com/janthmueller/workfold"
+tracker = "https://github.com/janthmueller/workfold/issues"
+
+[project.scripts]
+workfold = "workfold.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pyright>=1.1",
+    "pytest>=8",
+    "pytest-cov>=6",
+    "ruff>=0.8",
+]
+release = [
+    "build>=1",
+    "pyinstaller>=6",
+    "python-semantic-release>=10,<11",
+    "twine>=5",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["workfold*"]
+exclude = ["tests*"]
+
+[tool.setuptools.package-data]
+workfold = ["py.typed"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+src = ["workfold", "tests"]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[tool.pyright]
+pythonVersion = "3.10"
+typeCheckingMode = "strict"
+include = ["workfold", "tests"]
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+addopts = ["-ra", "--strict-config", "--strict-markers"]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["workfold"]
+omit = ["workfold/__main__.py"]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+commit_parser = "conventional"
+allow_zero_version = true
+major_on_zero = false
+commit_message = "chore(release): {version} [skip ci]\n\nAutomatically generated by python-semantic-release"
+build_command = "python -m build"
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease = false
+
+[tool.semantic_release.publish]
+upload_to_vcs_release = true

workfold-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

workfold-0.1.0a1/tests/support/__init__.py

@@ -0,0 +1 @@
+"""Deterministic test support for Workfold."""

workfold-0.1.0a1/tests/support/git_repo.py

@@ -0,0 +1,130 @@
+"""Isolated local Git repositories with exact timestamp fixtures."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+
+@dataclass(slots=True)
+class GitRepo:
+    """Small plumbing-based repository fixture independent of user config."""
+
+    path: Path
+    branch: str = "main"
+
+    @classmethod
+    def create(cls, path: Path) -> GitRepo:
+        path.mkdir(parents=True)
+        repo = cls(path=path)
+        repo.run("init", "--initial-branch=main")
+        return repo
+
+    def _environment(self, additions: Mapping[str, str] | None = None) -> dict[str, str]:
+        environment = dict(os.environ)
+        environment.update(
+            {
+                "GIT_CONFIG_GLOBAL": os.devnull,
+                "GIT_CONFIG_NOSYSTEM": "1",
+                "GIT_TERMINAL_PROMPT": "0",
+                "LANG": "C",
+                "LC_ALL": "C",
+            }
+        )
+        if additions is not None:
+            environment.update(additions)
+        return environment
+
+    def run(
+        self,
+        *arguments: str,
+        input_data: bytes | None = None,
+        environment: Mapping[str, str] | None = None,
+    ) -> bytes:
+        completed = subprocess.run(
+            (
+                "git",
+                "--no-pager",
+                "-c",
+                "commit.gpgSign=false",
+                "-c",
+                "core.hooksPath=/dev/null",
+                *arguments,
+            ),
+            cwd=self.path,
+            env=self._environment(environment),
+            input=input_data,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            shell=False,
+            check=False,
+        )
+        if completed.returncode != 0:
+            stderr = completed.stderr.decode("utf-8", errors="replace")
+            raise AssertionError(f"fixture Git command failed ({completed.returncode}): {stderr}")
+        return completed.stdout
+
+    def commit(
+        self,
+        filename: str,
+        content: str,
+        subject: str,
+        *,
+        author_date: str,
+        committer_date: str,
+        author_name: str = "Fixture Author",
+        author_email: str = "author@example.test",
+        committer_name: str = "Fixture Committer",
+        committer_email: str = "committer@example.test",
+        parent: str | None = None,
+        update_ref: str | None = None,
+    ) -> str:
+        target = self.path / filename
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+        self.run("add", "--", filename)
+        tree = self.run("write-tree").decode("ascii").strip()
+        if parent is None:
+            parent_result = subprocess.run(
+                ("git", "rev-parse", "--verify", "HEAD^{commit}"),
+                cwd=self.path,
+                env=self._environment(),
+                stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL,
+                shell=False,
+                check=False,
+            )
+            parent = parent_result.stdout.decode("ascii").strip() if parent_result.returncode == 0 else None
+
+        arguments = ["commit-tree", tree]
+        if parent is not None:
+            arguments.extend(("-p", parent))
+        identity_environment = {
+            "GIT_AUTHOR_DATE": author_date,
+            "GIT_AUTHOR_EMAIL": author_email,
+            "GIT_AUTHOR_NAME": author_name,
+            "GIT_COMMITTER_DATE": committer_date,
+            "GIT_COMMITTER_EMAIL": committer_email,
+            "GIT_COMMITTER_NAME": committer_name,
+        }
+        commit_id = (
+            self.run(
+                *arguments,
+                input_data=subject.encode("utf-8") + b"\n",
+                environment=identity_environment,
+            )
+            .decode("ascii")
+            .strip()
+        )
+        ref_name = update_ref or f"refs/heads/{self.branch}"
+        self.run("update-ref", ref_name, commit_id)
+        return commit_id
+
+    def point_ref(self, ref_name: str, object_id: str) -> None:
+        self.run("update-ref", ref_name, object_id)
+
+    def detach(self, object_id: str) -> None:
+        self.run("update-ref", "--no-deref", "HEAD", object_id)