worklogs 0.2.0__tar.gz → 0.2.1__tar.gz

{worklogs-0.2.0 → worklogs-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: worklogs
-Version: 0.2.0
+Version: 0.2.1
 Summary: Local markdown worklog helpers for developer workflows.
 Project-URL: Homepage, https://github.com/alik-git/worklogs
 Project-URL: Repository, https://github.com/alik-git/worklogs
@@ -99,6 +99,41 @@ Print created paths for scripts:
 worklogs new note--personal-site--theme-ideas --scope personal --print-path
 ```
 
+Create a dated project workset directory:
+
+```bash
+worklogs workset new backend-api-refactor --worksets-root ~/worksets
+```
+
+Create a dated workset under organizer folders:
+
+```bash
+worklogs workset new release-tools/python-packaging/worklogs-0.2.1 \
+  --worksets-root ~/worksets
+```
+
+Worksets are created under:
+
+```text
+<worksets-root>/YYYY/MM/DD/<workset-path>/
+```
+
+Preview a workset path without creating it:
+
+```bash
+worklogs workset new release-tools/python-packaging/worklogs-0.2.1 \
+  --worksets-root ~/worksets \
+  --dry-run
+```
+
+Print only the created path for scripts:
+
+```bash
+worklogs workset new backend-api-refactor \
+  --worksets-root ~/worksets \
+  --print-path
+```
+
 Supported kinds:
 
 ```text
@@ -122,13 +157,14 @@ Example:
 root = "~/worklog"
 default_scope = "work"
 timezone = "America/Toronto"
+worksets_root = "~/worksets"
 ```
 
 Resolution order:
 
 1. CLI flags
 2. environment variables: `WORKLOG_ROOT`, `WORKLOG_SCOPE`,
-   `WORKLOG_TIMEZONE`
+   `WORKLOG_TIMEZONE`, `WORKLOG_WORKSETS_ROOT`
 3. config file
 4. package defaults
 
@@ -138,6 +174,12 @@ With `default_scope` configured, the fast path can omit `--scope`:
 worklogs new plan--backend-api--improve-deploy-notes
 ```
 
+With `worksets_root` configured, the workset path can omit `--worksets-root`:
+
+```bash
+worklogs workset new backend-api-refactor
+```
+
 For shorter personal shell usage, add a local alias:
 
 ```bash
@@ -196,9 +238,9 @@ Environment name: pypi
 Create a GitHub Release for the version in [`pyproject.toml`](pyproject.toml):
 
 ```bash
-gh release create v0.2.0 \
-  --title "v0.2.0" \
-  --notes "Add worklog file creation commands."
+gh release create v0.2.1 \
+  --title "v0.2.1" \
+  --notes "Add dated workset directory creation."
 ```
 
 Publishing is release-driven on purpose: normal pushes and pull requests build

{worklogs-0.2.0 → worklogs-0.2.1}/README.md

@@ -72,6 +72,41 @@ Print created paths for scripts:
 worklogs new note--personal-site--theme-ideas --scope personal --print-path
 ```
 
+Create a dated project workset directory:
+
+```bash
+worklogs workset new backend-api-refactor --worksets-root ~/worksets
+```
+
+Create a dated workset under organizer folders:
+
+```bash
+worklogs workset new release-tools/python-packaging/worklogs-0.2.1 \
+  --worksets-root ~/worksets
+```
+
+Worksets are created under:
+
+```text
+<worksets-root>/YYYY/MM/DD/<workset-path>/
+```
+
+Preview a workset path without creating it:
+
+```bash
+worklogs workset new release-tools/python-packaging/worklogs-0.2.1 \
+  --worksets-root ~/worksets \
+  --dry-run
+```
+
+Print only the created path for scripts:
+
+```bash
+worklogs workset new backend-api-refactor \
+  --worksets-root ~/worksets \
+  --print-path
+```
+
 Supported kinds:
 
 ```text
@@ -95,13 +130,14 @@ Example:
 root = "~/worklog"
 default_scope = "work"
 timezone = "America/Toronto"
+worksets_root = "~/worksets"
 ```
 
 Resolution order:
 
 1. CLI flags
 2. environment variables: `WORKLOG_ROOT`, `WORKLOG_SCOPE`,
-   `WORKLOG_TIMEZONE`
+   `WORKLOG_TIMEZONE`, `WORKLOG_WORKSETS_ROOT`
 3. config file
 4. package defaults
 
@@ -111,6 +147,12 @@ With `default_scope` configured, the fast path can omit `--scope`:
 worklogs new plan--backend-api--improve-deploy-notes
 ```
 
+With `worksets_root` configured, the workset path can omit `--worksets-root`:
+
+```bash
+worklogs workset new backend-api-refactor
+```
+
 For shorter personal shell usage, add a local alias:
 
 ```bash
@@ -169,9 +211,9 @@ Environment name: pypi
 Create a GitHub Release for the version in [`pyproject.toml`](pyproject.toml):
 
 ```bash
-gh release create v0.2.0 \
-  --title "v0.2.0" \
-  --notes "Add worklog file creation commands."
+gh release create v0.2.1 \
+  --title "v0.2.1" \
+  --notes "Add dated workset directory creation."
 ```
 
 Publishing is release-driven on purpose: normal pushes and pull requests build

{worklogs-0.2.0 → worklogs-0.2.1}/docs/api.md

@@ -9,5 +9,11 @@ Use `worklogs new` to create dated markdown worklog files:
 worklogs new plan--backend-api--improve-deploy-notes --scope work
 ```
 
+Use `worklogs workset new` to create dated project workset directories:
+
+```bash
+worklogs workset new backend-api-refactor --worksets-root ~/worksets
+```
+
 Public Python helpers will be documented here if the package grows a stable API
 outside the CLI.

{worklogs-0.2.0 → worklogs-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "worklogs"
-version = "0.2.0"
+version = "0.2.1"
 description = "Local markdown worklog helpers for developer workflows."
 readme = "README.md"
 requires-python = ">=3.11"

{worklogs-0.2.0 → worklogs-0.2.1}/src/worklogs/__init__.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 __all__ = ["__version__"]

{worklogs-0.2.0 → worklogs-0.2.1}/src/worklogs/cli.py

@@ -8,7 +8,7 @@ import re
 import sys
 import tomllib
 from dataclasses import dataclass
-from datetime import UTC, datetime, tzinfo
+from datetime import UTC, date, datetime, tzinfo
 from pathlib import Path
 from typing import TYPE_CHECKING
 from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
@@ -55,6 +55,14 @@ class WorklogConfig:
     timezone: tzinfo
 
 
+@dataclass(frozen=True)
+class WorksetConfig:
+    """Resolved user defaults for workset directory creation."""
+
+    root: Path
+    timezone: tzinfo
+
+
 @dataclass(frozen=True)
 class WorklogEntry:
     """A worklog file that should be created."""
@@ -122,6 +130,51 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="print created path or paths",
     )
+
+    workset_parser = subparsers.add_parser(
+        "workset",
+        help="create and maintain project workset directories",
+        description="Create and maintain project workset directories.",
+    )
+    workset_subparsers = workset_parser.add_subparsers(
+        dest="workset_command",
+        required=True,
+    )
+    workset_new_parser = workset_subparsers.add_parser(
+        "new",
+        help="create a dated project workset directory",
+        description="Create a dated project workset directory.",
+    )
+    workset_new_parser.add_argument(
+        "path",
+        metavar="PATH",
+        help="relative workset path under YYYY/MM/DD, for example app/refactor",
+    )
+    workset_new_parser.add_argument(
+        "--worksets-root",
+        metavar="PATH",
+        help="root directory for dated workset folders",
+    )
+    workset_new_parser.add_argument(
+        "--timezone",
+        metavar="ZONE",
+        help="IANA timezone name used when choosing today's date",
+    )
+    workset_new_parser.add_argument(
+        "--date",
+        metavar="YYYY-MM-DD",
+        help="explicit date for reproducible workset creation",
+    )
+    workset_new_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="print the intended path without creating it",
+    )
+    workset_new_parser.add_argument(
+        "--print-path",
+        action="store_true",
+        help="print only the created or intended path",
+    )
     return parser
 
 
@@ -137,6 +190,8 @@ def main(argv: Sequence[str] | None = None) -> int:
     try:
         if args.command == "new":
             return _run_new(args)
+        if args.command == "workset" and args.workset_command == "new":
+            return _run_workset_new(args)
     except WorklogsError as error:
         print(f"worklogs: error: {error}", file=sys.stderr)
         return 2
@@ -176,6 +231,34 @@ def _run_new(args: argparse.Namespace) -> int:
     return 0
 
 
+def _run_workset_new(args: argparse.Namespace) -> int:
+    config = _resolve_workset_config(args, os.environ)
+    workset_date = _resolve_workset_date(args.date, config.timezone)
+    path_parts = _parse_workset_path(args.path)
+    workset_path = _build_workset_path(
+        config=config,
+        workset_date=workset_date,
+        path_parts=path_parts,
+    )
+
+    if args.dry_run:
+        if args.print_path:
+            print(workset_path)
+        else:
+            print("Would create workset:")
+            print(workset_path)
+        return 0
+
+    created = _create_workset_directory(workset_path)
+    if args.print_path:
+        print(workset_path)
+    elif created:
+        print(f"Created workset directory: {workset_path}")
+    else:
+        print(f"Workset directory already exists and is empty: {workset_path}")
+    return 0
+
+
 def _resolve_identity(args: argparse.Namespace) -> WorklogIdentity:
     explicit_fields = (args.kind, args.project, args.slug)
     has_explicit_fields = any(value is not None for value in explicit_fields)
@@ -267,6 +350,35 @@ def _resolve_config(
     )
 
 
+def _resolve_workset_config(
+    args: argparse.Namespace,
+    environment: Mapping[str, str],
+) -> WorksetConfig:
+    file_config = _load_config()
+
+    root_value = _first_string(
+        args.worksets_root,
+        environment.get("WORKLOG_WORKSETS_ROOT"),
+        file_config.get("worksets_root"),
+    )
+    if root_value is None:
+        msg = (
+            "worksets root is required; set --worksets-root, "
+            "WORKLOG_WORKSETS_ROOT, or worksets_root in config"
+        )
+        raise WorklogsError(msg)
+
+    timezone_value = _first_string(
+        args.timezone,
+        environment.get("WORKLOG_TIMEZONE"),
+        file_config.get("timezone"),
+    )
+    return WorksetConfig(
+        root=Path(root_value).expanduser(),
+        timezone=_resolve_timezone(timezone_value),
+    )
+
+
 def _load_config() -> dict[str, str]:
     config_path = CONFIG_PATH.expanduser()
     if not config_path.exists():
@@ -283,7 +395,7 @@ def _load_config() -> dict[str, str]:
         raise WorklogsError(msg) from error
 
     config: dict[str, str] = {}
-    for key in ("root", "default_scope", "timezone"):
+    for key in ("root", "default_scope", "timezone", "worksets_root"):
         value = raw_config.get(key)
         if value is None:
             continue
@@ -311,6 +423,77 @@ def _resolve_timezone(timezone_name: str | None) -> tzinfo:
         raise WorklogsError(msg) from error
 
 
+def _resolve_workset_date(value: str | None, timezone: tzinfo) -> date:
+    if value is None:
+        return datetime.now(UTC).astimezone(timezone).date()
+    try:
+        return date.fromisoformat(value)
+    except ValueError as error:
+        msg = f"invalid date {value!r}; expected YYYY-MM-DD"
+        raise WorklogsError(msg) from error
+
+
+def _parse_workset_path(value: str) -> tuple[str, ...]:
+    if not value:
+        msg = "workset path cannot be empty"
+        raise WorklogsError(msg)
+    if Path(value).is_absolute():
+        msg = "workset path must be relative"
+        raise WorklogsError(msg)
+
+    parts = tuple(value.split("/"))
+    for part in parts:
+        if part in {"", ".", ".."}:
+            msg = "workset path cannot contain empty, '.', or '..' components"
+            raise WorklogsError(msg)
+        if not SLUG_PATTERN.fullmatch(part):
+            msg = (
+                "workset path components must start with a lowercase letter or "
+                "digit and contain only lowercase letters, digits, dots, "
+                "underscores, or hyphens"
+            )
+            raise WorklogsError(msg)
+    return parts
+
+
+def _build_workset_path(
+    *,
+    config: WorksetConfig,
+    workset_date: date,
+    path_parts: Sequence[str],
+) -> Path:
+    return (
+        config.root
+        / f"{workset_date:%Y}"
+        / f"{workset_date:%m}"
+        / f"{workset_date:%d}"
+        / Path(*path_parts)
+    )
+
+
+def _create_workset_directory(path: Path) -> bool:
+    if path.exists():
+        if not path.is_dir():
+            msg = f"workset path exists but is not a directory: {path}"
+            raise WorklogsError(msg)
+        try:
+            has_contents = next(path.iterdir(), None) is not None
+        except OSError as error:
+            msg = f"could not inspect existing workset directory {path}: {error}"
+            raise WorklogsError(msg) from error
+        if has_contents:
+            msg = f"refusing to use existing non-empty workset directory: {path}"
+            raise WorklogsError(msg)
+        return False
+
+    try:
+        path.mkdir(parents=True)
+    except OSError as error:
+        msg = f"could not create workset directory {path}: {error}"
+        raise WorklogsError(msg) from error
+    return True
+
+
 def _build_entries(
     *,
     identity: WorklogIdentity,

{worklogs-0.2.0 → worklogs-0.2.1}/tests/test_package.py

@@ -14,8 +14,11 @@ from worklogs.cli import (
     WorklogEntry,
     WorklogIdentity,
     WorklogsError,
+    WorksetConfig,
     _build_entries,
+    _build_workset_path,
     _parse_identity_token,
+    _parse_workset_path,
     _write_entries,
     main,
 )
@@ -26,7 +29,7 @@ if TYPE_CHECKING:
 
 def test_version_is_exposed() -> None:
     """Verify the package exposes its current version."""
-    assert worklogs.__version__ == "0.2.0"
+    assert worklogs.__version__ == "0.2.1"
 
 
 def test_cli_accepts_no_arguments() -> None:
@@ -210,6 +213,185 @@ def test_dry_run_writes_nothing(
     assert not root.exists()
 
 
+def test_workset_new_uses_config_root_and_explicit_date(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Verify workset creation uses the configured root and dated layout."""
+    worksets_root = tmp_path / "Projects" / "worksets"
+    _write_config(
+        tmp_path,
+        monkeypatch,
+        root=tmp_path / "worklog",
+        default_scope="work",
+        worksets_root=worksets_root,
+    )
+
+    assert (
+        main(
+            [
+                "workset",
+                "new",
+                "release-tools/worklogs-0.2.1",
+                "--date",
+                "2026-05-29",
+            ]
+        )
+        == 0
+    )
+
+    created_path = (
+        worksets_root / "2026" / "05" / "29" / "release-tools" / "worklogs-0.2.1"
+    )
+    assert created_path.is_dir()
+    assert f"Created workset directory: {created_path}" in capsys.readouterr().out
+
+
+def test_workset_new_dry_run_writes_nothing(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Verify workset dry-run prints the intended path without writing."""
+    _isolate_home(tmp_path, monkeypatch)
+    worksets_root = tmp_path / "worksets"
+
+    assert (
+        main(
+            [
+                "workset",
+                "new",
+                "release-tools/python-packaging/worklogs-0.2.1",
+                "--worksets-root",
+                str(worksets_root),
+                "--date",
+                "2026-05-29",
+                "--dry-run",
+            ]
+        )
+        == 0
+    )
+
+    output = capsys.readouterr().out
+    assert "Would create workset:" in output
+    assert (
+        str(
+            worksets_root
+            / "2026"
+            / "05"
+            / "29"
+            / "release-tools"
+            / "python-packaging"
+            / "worklogs-0.2.1"
+        )
+        in output
+    )
+    assert not worksets_root.exists()
+
+
+def test_workset_new_print_path_is_script_friendly(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Verify --print-path prints only the created workset path."""
+    _isolate_home(tmp_path, monkeypatch)
+    worksets_root = tmp_path / "worksets"
+
+    assert (
+        main(
+            [
+                "workset",
+                "new",
+                "worklogs-0.2.1",
+                "--worksets-root",
+                str(worksets_root),
+                "--date",
+                "2026-05-29",
+                "--print-path",
+            ]
+        )
+        == 0
+    )
+
+    expected_path = worksets_root / "2026" / "05" / "29" / "worklogs-0.2.1"
+    assert capsys.readouterr().out == f"{expected_path}\n"
+    assert expected_path.is_dir()
+
+
+def test_workset_new_refuses_existing_non_empty_directory(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Verify workset creation refuses to reuse non-empty directories."""
+    _isolate_home(tmp_path, monkeypatch)
+    worksets_root = tmp_path / "worksets"
+    existing_path = worksets_root / "2026" / "05" / "29" / "worklogs-0.2.1"
+    existing_path.mkdir(parents=True)
+    (existing_path / "README.md").write_text("existing\n", encoding="utf-8")
+
+    assert (
+        main(
+            [
+                "workset",
+                "new",
+                "worklogs-0.2.1",
+                "--worksets-root",
+                str(worksets_root),
+                "--date",
+                "2026-05-29",
+            ]
+        )
+        == 2
+    )
+    assert "existing non-empty workset directory" in capsys.readouterr().err
+
+
+def test_workset_new_requires_configured_root(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Verify workset creation does not guess a local machine default."""
+    _isolate_home(tmp_path, monkeypatch)
+
+    assert main(["workset", "new", "worklogs-0.2.1", "--date", "2026-05-29"]) == 2
+    assert "worksets root is required" in capsys.readouterr().err
+
+
+def test_parse_workset_path_rejects_unsafe_components() -> None:
+    """Verify workset path parsing rejects absolute or escaping paths."""
+    for value in (
+        "/absolute/workset",
+        "release-tools/../workset",
+        "release-tools//workset",
+    ):
+        with pytest.raises(WorklogsError):
+            _parse_workset_path(value)
+
+
+def test_build_workset_path_renders_date_folders(tmp_path: Path) -> None:
+    """Verify workset paths include YYYY/MM/DD before organizer folders."""
+    workset_path = _build_workset_path(
+        config=WorksetConfig(root=tmp_path / "worksets", timezone=ZoneInfo("UTC")),
+        workset_date=datetime(2026, 5, 29, tzinfo=ZoneInfo("UTC")).date(),
+        path_parts=("release-tools", "worklogs-0.2.1"),
+    )
+
+    assert (
+        workset_path
+        == tmp_path
+        / "worksets"
+        / "2026"
+        / "05"
+        / "29"
+        / "release-tools"
+        / "worklogs-0.2.1"
+    )
+
+
 def test_scope_is_required_without_config_or_flag(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
@@ -249,16 +431,19 @@ def _write_config(
     *,
     root: Path,
     default_scope: str,
+    worksets_root: Path | None = None,
 ) -> None:
     home = _isolate_home(tmp_path, monkeypatch)
     config_path = home / ".config" / "worklogs" / "config.toml"
     config_path.parent.mkdir(parents=True)
-    config_path.write_text(
-        f'root = "{root}"\n'
-        f'default_scope = "{default_scope}"\n'
-        'timezone = "America/Toronto"\n',
-        encoding="utf-8",
-    )
+    lines = [
+        f'root = "{root}"',
+        f'default_scope = "{default_scope}"',
+        'timezone = "America/Toronto"',
+    ]
+    if worksets_root is not None:
+        lines.append(f'worksets_root = "{worksets_root}"')
+    config_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
 
 
 def _isolate_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
@@ -268,4 +453,5 @@ def _isolate_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
     monkeypatch.delenv("WORKLOG_ROOT", raising=False)
     monkeypatch.delenv("WORKLOG_SCOPE", raising=False)
     monkeypatch.delenv("WORKLOG_TIMEZONE", raising=False)
+    monkeypatch.delenv("WORKLOG_WORKSETS_ROOT", raising=False)
     return home

{worklogs-0.2.0 → worklogs-0.2.1}/uv.lock

@@ -420,7 +420,7 @@ wheels = [
 
 [[package]]
 name = "worklogs"
-version = "0.2.0"
+version = "0.2.1"
 source = { editable = "." }
 
 [package.optional-dependencies]