work-tempo 0.0.1__tar.gz

work_tempo-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ren Diao
+
+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.

work_tempo-0.0.1/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: work-tempo
+Version: 0.0.1
+Summary: Track source-code momentum across Git workspaces
+Author: Ren Diao
+License: MIT
+Project-URL: Homepage, https://github.com/endario/work-tempo
+Project-URL: Source, https://github.com/endario/work-tempo
+Project-URL: Issues, https://github.com/endario/work-tempo/issues
+Keywords: git,loc,churn,metrics,productivity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Work Tempo
+
+Work Tempo tracks source-code momentum across a Git workspace and its related repositories. It produces terminal summaries, a self-contained HTML report, and optional schema-versioned JSON for other local tools.
+
+It measures:
+
+- Source and test LOC snapshots over time.
+- Added plus deleted source churn by month or day.
+- Language composition and per-repository contribution.
+- Documentation LOC and churn as separate informational metrics.
+
+
+The optional native macOS menu-bar app opens on an aggregate of all tracked workspaces. Its menu-bar value and primary dashboard metric show source churn per day over the trailing closed days, up to thirty. An individual workspace remains selectable from the header.
+
+Repository comparison and component classification are outside Work Tempo's scope.
+
+## Requirements
+
+- Python 3.10 or newer.
+- Git 2.30 or newer.
+
+Work Tempo has no Python runtime dependencies outside the standard library.
+
+## Install
+
+```bash
+pipx install work-tempo   # or: pip install work-tempo
+```
+
+For local development:
+
+```bash
+git clone https://github.com/endario/work-tempo.git
+cd work-tempo
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+Then run it from any Git repository:
+
+```bash
+work-tempo
+```
+
+The current directory is the default workspace. Analyze another checkout with:
+
+```bash
+work-tempo --root ~/projects/my-app
+```
+
+Without installation, use:
+
+```bash
+PYTHONPATH=src python3 -m work_tempo --root ~/projects/my-app
+```
+
+## Reports
+
+The default report covers the latest 18 monthly periods and writes HTML under the workspace-specific user cache directory. The exact path is printed after each run.
+
+```bash
+# Monthly history with explicit outputs
+work-tempo --root ~/projects/my-app \
+  --html /tmp/work-tempo.html \
+  --json /tmp/work-tempo.json
+
+# Daily view for the latest 30 days
+work-tempo --root ~/projects/my-app --period day --days 30
+
+# Terminal and JSON only
+work-tempo --root ~/projects/my-app --no-html --json /tmp/work-tempo.json
+
+# Optional three-month LOC forecast using the last six completed months
+work-tempo --root ~/projects/my-app --forecast
+```
+
+Period boundaries use the active system timezone, falling back to UTC. The resolved timezone is included in JSON and HTML report metadata.
+
+## Workspace Scope
+
+Work Tempo always considers the parent Git repository. It also discovers usable initialized submodules declared in `.gitmodules` and can aggregate additional repositories configured outside the workspace.
+
+Create a personal configuration:
+
+```bash
+work-tempo --root ~/projects/my-app --init-config
+```
+
+This writes `~/projects/my-app/.work-tempo.local.json`, which should remain untracked. For shared workspace policy, generate or maintain `~/projects/my-app/.work-tempo.json` instead.
+
+Configuration layers are applied in this order:
+
+1. Built-in generic defaults.
+2. Tracked `.work-tempo.json`.
+3. Untracked `.work-tempo.local.json`, or the file passed with `--config`.
+
+Later keys replace earlier keys. Arrays replace rather than append. Each file is validated on its own before merging: an unknown key, a wrong type, or an unsupported `schema_version` is an error that names the key and file, so a typo cannot silently change the numbers.
+
+Config files declare `"schema_version": 1` or `2` (missing means 1). `test_file_markers`, the filename infixes that mark a test file, needs version 2; `--init-config` writes version 2. A version-2 file is rejected by older releases instead of being miscounted. Existing caches are recomputed once after upgrading. Run `work-tempo --init-config` to write every supported field with its default, or read [src/work_tempo/defaults.json](src/work_tempo/defaults.json).
+
+Additional repositories use paths relative to the main checkout:
+
+```json
+{
+  "schema_version": 1,
+  "extra_repos": [
+    {
+      "label": "client-app",
+      "path": "../client-app"
+    },
+    {
+      "label": "shared-sdk",
+      "path": "packages/shared-sdk"
+    }
+  ]
+}
+```
+
+Only actual Git repository roots are counted. Missing or uninitialized configured repositories are reported and skipped.
+
+## Counting Model
+
+LOC snapshots count newline-delimited tracked source files from the last commit available at each period cutoff. Source and tests are separated using conventional test directories and test/spec/e2e filename patterns.
+
+Churn is added plus deleted lines from non-merge commits, grouped by author date and filtered through the same current counting policy. Blank lines and comments count because WorkTempo measures physical source lines rather than semantic SLOC.
+
+Generated, minified, dependency, build, cache, scratch, and vendor-like paths are excluded by default. Documentation is counted separately and does not contribute to source LOC, growth, or churn metrics.
+
+## Cache
+
+On macOS, artifacts default to:
+
+```text
+~/Library/Caches/WorkTempo/<workspace-name>-<workspace-key>/
+```
+
+Linux uses `$XDG_CACHE_HOME/work-tempo` or `~/.cache/work-tempo`. Set `WORK_TEMPO_CACHE_HOME` to override the root.
+
+```bash
+# Rebuild the workspace cache
+work-tempo --clear-cache
+
+# Run without reading or writing a cache
+work-tempo --no-cache
+
+# Use an explicit cache file
+work-tempo --cache /tmp/work-tempo-cache.json
+```
+
+Snapshot cache entries include the commit and effective counting policy. Churn entries also include period kind and timezone. Rewritten history triggers a full churn rescan.
+
+## JSON Compatibility
+
+Reports currently use schema version 1. Additive fields may be introduced within version 1, and consumers must ignore unknown fields. Removing a field, changing its type or meaning, or changing period-series alignment requires a schema-version increment.
+
+## Development
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m compileall -q src tests
+```
+
+### macOS menu-bar app
+
+The local app requires macOS 14 or newer on Apple Silicon, Swift 6, and an installed `work-tempo` CLI. It resolves the collector from `~/.local/bin`, Homebrew locations, and then `PATH`.
+
+Build an ad-hoc signed app bundle:
+
+```bash
+scripts/build-macos-app.sh
+open dist/WorkTempo.app
+```
+
+Install the local build in `/Applications`:
+
+```bash
+scripts/build-macos-app.sh --install
+open /Applications/WorkTempo.app
+```
+
+Use the plus button to add individual Git repository roots. Each workspace keeps its own `.work-tempo.json` and `.work-tempo.local.json` counting policy. The default All Workspaces scope rejects overlapping reports and mixed timezones. Historical metrics share a common closed-day watermark, while current totals use each contributing report's latest snapshot. Both charts keep code and test activity above the axis and informational documentation below it.
+
+The app renders saved reports immediately. Collection is sequential, skips unattended work in Low Power Mode, uses two workers, and checkpoints the collector cache so an interrupted history extension can resume.
+
+App state and saved reports live under:
+
+```text
+~/Library/Application Support/WorkTempo/
+```
+
+The collector's existing cache remains under `~/Library/Caches/WorkTempo/`, shared with terminal runs. Removing a workspace from the app does not alter its source repository. To uninstall, quit WorkTempo and remove `/Applications/WorkTempo.app`; remove the Application Support directory separately only when its saved workspace list and reports are no longer wanted.
+
+Swift development checks:
+
+```bash
+cd macos
+swift test
+swift build -c release
+```
+
+## Design docs
+
+- [Architecture](docs/architecture.md): the collector, configuration, counting model, and cache.
+- [macOS app](docs/macos-app.md): scheduling, aggregation, and metric definitions.
+
+## Releasing
+
+Bump `version` in `pyproject.toml` in a pull request and merge it, then tag the merge commit `vX.Y.Z` and push the tag. The Publish workflow builds the package and uploads it to PyPI by trusted publishing, with no stored token.
+
+## Contributing
+
+`main` takes changes only through a pull request that passes the tests and the identity check. Every commit is authored and committed under `5214595+ren-diao@users.noreply.github.com` (or a bot's noreply address); an AI model may be credited with a `Co-authored-by` trailer. Turn the same check on locally with `git config core.hooksPath .githooks`.
+
+## Authors
+
+Ren Diao, co-authored with Claude (Anthropic).
+
+## License
+
+[MIT](LICENSE)
+
+## 2mw2lt
+
+Work Tempo is part of [2mw2lt](https://2mw2lt.com) — *Too Much Work, Too Little Time* — a steering partner that coordinates work across AI workers and trusted people. Its sibling [unlimited](https://github.com/endario/unlimited) reads AI-subscription usage.

work_tempo-0.0.1/README.md

@@ -0,0 +1,224 @@
+# Work Tempo
+
+Work Tempo tracks source-code momentum across a Git workspace and its related repositories. It produces terminal summaries, a self-contained HTML report, and optional schema-versioned JSON for other local tools.
+
+It measures:
+
+- Source and test LOC snapshots over time.
+- Added plus deleted source churn by month or day.
+- Language composition and per-repository contribution.
+- Documentation LOC and churn as separate informational metrics.
+
+
+The optional native macOS menu-bar app opens on an aggregate of all tracked workspaces. Its menu-bar value and primary dashboard metric show source churn per day over the trailing closed days, up to thirty. An individual workspace remains selectable from the header.
+
+Repository comparison and component classification are outside Work Tempo's scope.
+
+## Requirements
+
+- Python 3.10 or newer.
+- Git 2.30 or newer.
+
+Work Tempo has no Python runtime dependencies outside the standard library.
+
+## Install
+
+```bash
+pipx install work-tempo   # or: pip install work-tempo
+```
+
+For local development:
+
+```bash
+git clone https://github.com/endario/work-tempo.git
+cd work-tempo
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+Then run it from any Git repository:
+
+```bash
+work-tempo
+```
+
+The current directory is the default workspace. Analyze another checkout with:
+
+```bash
+work-tempo --root ~/projects/my-app
+```
+
+Without installation, use:
+
+```bash
+PYTHONPATH=src python3 -m work_tempo --root ~/projects/my-app
+```
+
+## Reports
+
+The default report covers the latest 18 monthly periods and writes HTML under the workspace-specific user cache directory. The exact path is printed after each run.
+
+```bash
+# Monthly history with explicit outputs
+work-tempo --root ~/projects/my-app \
+  --html /tmp/work-tempo.html \
+  --json /tmp/work-tempo.json
+
+# Daily view for the latest 30 days
+work-tempo --root ~/projects/my-app --period day --days 30
+
+# Terminal and JSON only
+work-tempo --root ~/projects/my-app --no-html --json /tmp/work-tempo.json
+
+# Optional three-month LOC forecast using the last six completed months
+work-tempo --root ~/projects/my-app --forecast
+```
+
+Period boundaries use the active system timezone, falling back to UTC. The resolved timezone is included in JSON and HTML report metadata.
+
+## Workspace Scope
+
+Work Tempo always considers the parent Git repository. It also discovers usable initialized submodules declared in `.gitmodules` and can aggregate additional repositories configured outside the workspace.
+
+Create a personal configuration:
+
+```bash
+work-tempo --root ~/projects/my-app --init-config
+```
+
+This writes `~/projects/my-app/.work-tempo.local.json`, which should remain untracked. For shared workspace policy, generate or maintain `~/projects/my-app/.work-tempo.json` instead.
+
+Configuration layers are applied in this order:
+
+1. Built-in generic defaults.
+2. Tracked `.work-tempo.json`.
+3. Untracked `.work-tempo.local.json`, or the file passed with `--config`.
+
+Later keys replace earlier keys. Arrays replace rather than append. Each file is validated on its own before merging: an unknown key, a wrong type, or an unsupported `schema_version` is an error that names the key and file, so a typo cannot silently change the numbers.
+
+Config files declare `"schema_version": 1` or `2` (missing means 1). `test_file_markers`, the filename infixes that mark a test file, needs version 2; `--init-config` writes version 2. A version-2 file is rejected by older releases instead of being miscounted. Existing caches are recomputed once after upgrading. Run `work-tempo --init-config` to write every supported field with its default, or read [src/work_tempo/defaults.json](src/work_tempo/defaults.json).
+
+Additional repositories use paths relative to the main checkout:
+
+```json
+{
+  "schema_version": 1,
+  "extra_repos": [
+    {
+      "label": "client-app",
+      "path": "../client-app"
+    },
+    {
+      "label": "shared-sdk",
+      "path": "packages/shared-sdk"
+    }
+  ]
+}
+```
+
+Only actual Git repository roots are counted. Missing or uninitialized configured repositories are reported and skipped.
+
+## Counting Model
+
+LOC snapshots count newline-delimited tracked source files from the last commit available at each period cutoff. Source and tests are separated using conventional test directories and test/spec/e2e filename patterns.
+
+Churn is added plus deleted lines from non-merge commits, grouped by author date and filtered through the same current counting policy. Blank lines and comments count because WorkTempo measures physical source lines rather than semantic SLOC.
+
+Generated, minified, dependency, build, cache, scratch, and vendor-like paths are excluded by default. Documentation is counted separately and does not contribute to source LOC, growth, or churn metrics.
+
+## Cache
+
+On macOS, artifacts default to:
+
+```text
+~/Library/Caches/WorkTempo/<workspace-name>-<workspace-key>/
+```
+
+Linux uses `$XDG_CACHE_HOME/work-tempo` or `~/.cache/work-tempo`. Set `WORK_TEMPO_CACHE_HOME` to override the root.
+
+```bash
+# Rebuild the workspace cache
+work-tempo --clear-cache
+
+# Run without reading or writing a cache
+work-tempo --no-cache
+
+# Use an explicit cache file
+work-tempo --cache /tmp/work-tempo-cache.json
+```
+
+Snapshot cache entries include the commit and effective counting policy. Churn entries also include period kind and timezone. Rewritten history triggers a full churn rescan.
+
+## JSON Compatibility
+
+Reports currently use schema version 1. Additive fields may be introduced within version 1, and consumers must ignore unknown fields. Removing a field, changing its type or meaning, or changing period-series alignment requires a schema-version increment.
+
+## Development
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m compileall -q src tests
+```
+
+### macOS menu-bar app
+
+The local app requires macOS 14 or newer on Apple Silicon, Swift 6, and an installed `work-tempo` CLI. It resolves the collector from `~/.local/bin`, Homebrew locations, and then `PATH`.
+
+Build an ad-hoc signed app bundle:
+
+```bash
+scripts/build-macos-app.sh
+open dist/WorkTempo.app
+```
+
+Install the local build in `/Applications`:
+
+```bash
+scripts/build-macos-app.sh --install
+open /Applications/WorkTempo.app
+```
+
+Use the plus button to add individual Git repository roots. Each workspace keeps its own `.work-tempo.json` and `.work-tempo.local.json` counting policy. The default All Workspaces scope rejects overlapping reports and mixed timezones. Historical metrics share a common closed-day watermark, while current totals use each contributing report's latest snapshot. Both charts keep code and test activity above the axis and informational documentation below it.
+
+The app renders saved reports immediately. Collection is sequential, skips unattended work in Low Power Mode, uses two workers, and checkpoints the collector cache so an interrupted history extension can resume.
+
+App state and saved reports live under:
+
+```text
+~/Library/Application Support/WorkTempo/
+```
+
+The collector's existing cache remains under `~/Library/Caches/WorkTempo/`, shared with terminal runs. Removing a workspace from the app does not alter its source repository. To uninstall, quit WorkTempo and remove `/Applications/WorkTempo.app`; remove the Application Support directory separately only when its saved workspace list and reports are no longer wanted.
+
+Swift development checks:
+
+```bash
+cd macos
+swift test
+swift build -c release
+```
+
+## Design docs
+
+- [Architecture](docs/architecture.md): the collector, configuration, counting model, and cache.
+- [macOS app](docs/macos-app.md): scheduling, aggregation, and metric definitions.
+
+## Releasing
+
+Bump `version` in `pyproject.toml` in a pull request and merge it, then tag the merge commit `vX.Y.Z` and push the tag. The Publish workflow builds the package and uploads it to PyPI by trusted publishing, with no stored token.
+
+## Contributing
+
+`main` takes changes only through a pull request that passes the tests and the identity check. Every commit is authored and committed under `5214595+ren-diao@users.noreply.github.com` (or a bot's noreply address); an AI model may be credited with a `Co-authored-by` trailer. Turn the same check on locally with `git config core.hooksPath .githooks`.
+
+## Authors
+
+Ren Diao, co-authored with Claude (Anthropic).
+
+## License
+
+[MIT](LICENSE)
+
+## 2mw2lt
+
+Work Tempo is part of [2mw2lt](https://2mw2lt.com) — *Too Much Work, Too Little Time* — a steering partner that coordinates work across AI workers and trusted people. Its sibling [unlimited](https://github.com/endario/unlimited) reads AI-subscription usage.

work_tempo-0.0.1/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "work-tempo"
+version = "0.0.1"
+description = "Track source-code momentum across Git workspaces"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Ren Diao" }]
+keywords = ["git", "loc", "churn", "metrics", "productivity"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/endario/work-tempo"
+Source = "https://github.com/endario/work-tempo"
+Issues = "https://github.com/endario/work-tempo/issues"
+
+[project.scripts]
+work-tempo = "work_tempo.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+work_tempo = ["defaults.json"]

work_tempo-0.0.1/setup.cfg

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

work_tempo-0.0.1/src/work_tempo/__init__.py

@@ -0,0 +1 @@
+"""WorkTempo source-momentum reporting."""

work_tempo-0.0.1/src/work_tempo/__main__.py

@@ -0,0 +1,5 @@
+from work_tempo.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())