worklog-opsdevnz 0.1.0__py3-none-any.whl

worklog_opsdevnz/__init__.py

@@ -0,0 +1,8 @@
+"""worklog-opsdevnz — Configurable worklog management CLI."""
+
+from importlib import metadata
+
+try:
+    __version__ = metadata.version("worklog-opsdevnz")
+except metadata.PackageNotFoundError:
+    __version__ = "0.0.0+local"

worklog_opsdevnz/cli.py

@@ -0,0 +1,68 @@
+"""CLI entry point for worklog-opsdevnz."""
+
+import shutil
+import subprocess
+from datetime import date
+from pathlib import Path
+
+import click
+
+from worklog_opsdevnz import __version__
+from worklog_opsdevnz.config import get_config
+from worklog_opsdevnz.paths import resolve_path
+from worklog_opsdevnz.template import generate_content
+
+
+@click.command()
+@click.version_option(version=__version__, prog_name="worklog-opsdevnz")
+@click.option(
+    "-e",
+    "--editor",
+    default=None,
+    help="Override the editor command (default: $VISUAL or $EDITOR).",
+)
+def main(editor: str | None) -> None:
+    """Create or open today's worklog entry."""
+    entry_date = date.today()
+
+    config = get_config()
+    target = resolve_path(config, entry_date)
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    if target.exists():
+        print(f"Opening existing worklog: {target}")
+    else:
+        content = generate_content(config, entry_date.isoformat())
+        target.write_text(content)
+        print(f"Created: {target}")
+
+    _open_editor(target, editor)
+
+
+def _open_editor(path: str | Path, override: str | None = None) -> None:
+    """Open the file in the configured editor, or print the path."""
+    editor = _resolve_editor(override)
+    if editor:
+        editor_cmd = shutil.which(editor)
+        if editor_cmd:
+            # fmt: off
+            subprocess.run([editor_cmd, str(path)])
+            # fmt: on
+        else:
+            print(f"Editor '{editor}' not found. Path: {path}")
+    else:
+        print(f"No editor configured. Path: {path}")
+
+
+def _resolve_editor(override: str | None = None) -> str | None:
+    """Resolve editor from CLI override, $VISUAL, or $EDITOR."""
+    import os
+
+    for candidate in (override, os.environ.get("VISUAL"), os.environ.get("EDITOR")):
+        if candidate:
+            return candidate
+    return None
+
+
+if __name__ == "__main__":
+    main()

worklog_opsdevnz/config.py

@@ -0,0 +1,71 @@
+"""Configuration discovery and loading for worklog-opsdevnz."""
+
+import os
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "worklog_dir": "docs/worklog",
+    "structure": "year",
+    "suffix": "worklog",
+    "author": os.environ.get("USER", "unknown"),
+    "default_tags": ["internal", "log"],
+    "sections": [
+        {"title": "Focus for Today", "content": ""},
+        {"title": "Completed", "content": ""},
+        {"title": "Notes & Reflections", "content": ""},
+        {"title": "Related", "content": ""},
+        {"title": "Next", "content": ""},
+    ],
+}
+
+
+def find_config(start: Path | None = None) -> Path | None:
+    """Search for worklog.toml or worklog.yaml from start up to root."""
+    if start is None:
+        start = Path.cwd()
+    candidates = list(start.parents) + [start]
+    for candidate in candidates:
+        for name in ("worklog.toml", "worklog.yaml", "worklog.yml"):
+            path = candidate / name
+            if path.exists():
+                return path
+    return None
+
+
+def load_config(path: Path) -> dict[str, Any]:
+    """Load config from TOML or YAML file."""
+    if path.suffix == ".toml":
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    else:
+        try:
+            import yaml  # type: ignore[import-untyped]
+        except ImportError:
+            print("Error: PyYAML required for .yaml config", file=sys.stderr)
+            sys.exit(1)
+        with open(path) as f:
+            return yaml.safe_load(f) or {}
+
+
+def merge_config(
+    file_config: dict[str, Any], defaults: dict[str, Any]
+) -> dict[str, Any]:
+    """Merge file config over defaults."""
+    merged = dict(defaults)
+    merged.update(file_config)
+    return merged
+
+
+def get_config() -> dict[str, Any]:
+    """Discover and load config, falling back to defaults."""
+    config_path = find_config()
+    if config_path:
+        merged = merge_config(load_config(config_path), DEFAULT_CONFIG)
+        worklog_dir = merged["worklog_dir"]
+        if not Path(worklog_dir).is_absolute():
+            merged["worklog_dir"] = str(config_path.parent / worklog_dir)
+        return merged
+    return dict(DEFAULT_CONFIG)

worklog_opsdevnz/paths.py

@@ -0,0 +1,28 @@
+"""Path resolution for worklog files."""
+
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+
+def resolve_path(
+    config: dict[str, Any],
+    entry_date: date,
+) -> Path:
+    """Compute the target file path based on config structure."""
+    base = Path(config.get("worklog_dir", "docs/worklog"))
+    structure = config.get("structure", "year")
+    suffix = config.get("suffix", "worklog")
+
+    if structure == "flat":
+        filename = f"{entry_date.isoformat()}-{suffix}.md"
+        return base / filename
+    elif structure == "year-month":
+        year = entry_date.strftime("%Y")
+        month = entry_date.strftime("%m")
+        filename = f"{entry_date.strftime('%d-%m-%Y')}-{suffix}.md"
+        return base / year / month / filename
+    else:  # "year" (default)
+        year = entry_date.strftime("%Y")
+        filename = f"{entry_date.strftime('%d-%m-%Y')}-{suffix}.md"
+        return base / year / filename

worklog_opsdevnz/template.py

@@ -0,0 +1,46 @@
+"""Frontmatter and body generation for worklog entries."""
+
+from typing import Any
+
+
+def generate_frontmatter(
+    config: dict[str, Any],
+    iso_date: str,
+) -> str:
+    """Generate YAML frontmatter."""
+    title = f"Work Log - {iso_date}"
+    tags = "\n".join(f"  - {t}" for t in config.get("default_tags", []))
+    author = config.get("author", "unknown")
+
+    return f"""---
+title: "{title}"
+date: {iso_date}
+author: {author}
+tags:
+{tags}
+draft: false
+---
+"""
+
+
+def generate_body(config: dict[str, Any]) -> str:
+    """Generate section headers from config."""
+    sections = config.get("sections", [])
+    lines = []
+    for section in sections:
+        title = section.get("title", "")
+        content = section.get("content", "")
+        lines.append(f"## {title}\n")
+        if content:
+            lines.append(f"{content}\n")
+    return "\n".join(lines)
+
+
+def generate_content(
+    config: dict[str, Any],
+    iso_date: str,
+) -> str:
+    """Generate full worklog content."""
+    frontmatter = generate_frontmatter(config, iso_date)
+    body = generate_body(config)
+    return f"{frontmatter}\n{body}"

worklog_opsdevnz-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: worklog-opsdevnz
+Version: 0.1.0
+Summary: Configurable worklog management CLI for dated development logs
+Author-email: "OpsDev.nz Collective" <john@opsdev.nz>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/startmeup-nz/worklog-opsdevnz
+Project-URL: Documentation, https://opsdev.nz/modules/worklog-opsdevnz
+Project-URL: Repository, https://github.com/startmeup-nz/worklog-opsdevnz.git
+Project-URL: Bug Tracker, https://github.com/startmeup-nz/worklog-opsdevnz/issues
+Keywords: worklog,documentation,daily-log,cli,markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+# WorkLog OpsDev.NZ
+
+**Status:** Development — see pyproject.toml for version
+
+Configurable CLI tool for creating and managing dated development worklogs.
+Generates Markdown entries with YAML frontmatter from per-project templates.
+
+## Problem
+
+Across multiple projects we kept reinventing the same pattern: a script that
+creates a dated Markdown file from a template, with frontmatter for date,
+author, tags, and draft status.  Each implementation had slightly different
+directory structures, section headers, and filenames. The core concept was
+always the same.
+
+## Solution
+
+`worklog-opsdevnz` formalises this pattern into a single published module:
+
+- **Per-project config** — `worklog.toml` controls directory structure, sections,
+  author, tags, and filename patterns
+- **Three structure modes** — `flat`, `year`, or `year-month` directory layouts
+- **YAML frontmatter** — date, title, author, tags, draft status
+- **Configurable sections** — each project defines its own section headers
+- **Editor integration** — opens new entries in `$VISUAL` / `$EDITOR`
+- **List existing entries** — browse worklogs with `--list`
+
+## Quick Start
+
+```bash
+# Create today's worklog
+worklog-opsdevnz
+
+# Create yesterday's worklog
+worklog-opsdevnz --previous
+
+# Override the editor for this run
+worklog-opsdevnz --editor nvim
+```
+
+## Configuration
+
+Each project gets a `worklog.toml` at its root:
+
+```toml
+worklog_dir = "docs/worklog"
+structure = "year"           # "flat", "year", or "year-month"
+author = "Your Name"
+default_tags = ["worklog", "log"]
+
+[[sections]]
+title = "Focus for Today"
+
+[[sections]]
+title = "Completed"
+
+[[sections]]
+title = "Notes"
+
+[[sections]]
+title = "Next"
+```
+
+## Scope
+
+**WorkLog DOES:**
+- Create dated Markdown worklog entries with YAML frontmatter
+- Per-project configuration via `worklog.toml`
+- Open entries in configured editor (`$VISUAL` / `$EDITOR`)
+- Three directory structure modes: flat, year, year-month
+
+**WorkLog DOES NOT (out of scope for 0.0.2):**
+- Zensical blog integration (see design doc)
+- Auto-generated index pages
+- Retro template support (planned for 0.1.0)
+- Time tracking / timesheet aggregation
+- `list`, `init`, or `create` subcommands (planned for 0.1.0)
+
+## Requirements
+
+- Python 3.12+
+- See [pyproject.toml](pyproject.toml) for full dependencies
+
+## Related
+
+- [Functional Requirements](docs/specs/README.md)
+- [Design Decisions](docs/design/README.md)
+- [User Stories](docs/stories/README.md)
+
+---
+
+**Last Updated:** 2026-05-23
+**Status:** Development (migrated to module template)
+**Maintainer:** OpsDev.nz Collective

worklog_opsdevnz-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+worklog_opsdevnz/__init__.py,sha256=I0a8AiVu_N2aha9ZIxCTTHrTrVf--pURLvtIej9hFU8,227
+worklog_opsdevnz/cli.py,sha256=WB-lxWEt30EjiMKE1eOfcEy2NI3WmPbC7PvaMAttTo4,1899
+worklog_opsdevnz/config.py,sha256=ny-PZXAZdeofmA6NM5BZidOJPhUPmZ4m79OgtYnb1Wo,2215
+worklog_opsdevnz/paths.py,sha256=rsKAfeR_1RwvnPUaL0lxe-wSej_m2Z3dvSXNXmhgFQA,944
+worklog_opsdevnz/template.py,sha256=qNkect11b3L5CmZURCQMpeWvI92GgisfWtpVDgoIfnA,1112
+worklog_opsdevnz-0.1.0.dist-info/licenses/LICENSE,sha256=4_FAkzAt5058r8NSaCDaV-4-CRq2AnVS1iYdtt2uIkM,4555
+worklog_opsdevnz-0.1.0.dist-info/METADATA,sha256=7F3GJB9oilIEpni0GJq1xL6gQMpjh85aGDSKH_jyaEw,4024
+worklog_opsdevnz-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+worklog_opsdevnz-0.1.0.dist-info/entry_points.txt,sha256=PZADo4QtDyTeSkL6U13edCZap6CyCgW28qV42QHFsBs,63
+worklog_opsdevnz-0.1.0.dist-info/top_level.txt,sha256=7JqIlXAq1DVyOW6T4AmjViKTZ5jsTcXtxruJg8tBfqY,17
+worklog_opsdevnz-0.1.0.dist-info/RECORD,,

worklog_opsdevnz-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

worklog_opsdevnz-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+worklog-opsdevnz = worklog_opsdevnz.cli:main

worklog_opsdevnz-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,90 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   END OF TERMS AND CONDITIONS

worklog_opsdevnz-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+worklog_opsdevnz