workstream-cli 0.0.1__tar.gz

workstream_cli-0.0.1/LICENSE

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

workstream_cli-0.0.1/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.3
+Name: workstream-cli
+Version: 0.0.1
+Summary: Attention management for makers. Track trains of thought across projects.
+License: MIT
+Keywords: workstream,productivity,cli,attention-management,task-management
+Author: Mahmoud Hashemi
+Author-email: mahmoud@hatnote.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Only
+Classifier: Topic :: Office/Business :: Scheduling
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Dist: ashes (>=24.0.0)
+Requires-Dist: clastic (>=24.0.0)
+Requires-Dist: face (>=20.0.0)
+Requires-Dist: pyyaml (>=6.0,<7.0)
+Project-URL: Homepage, https://github.com/mahmoud/workstream
+Project-URL: Repository, https://github.com/mahmoud/workstream
+Description-Content-Type: text/markdown
+
+# workstream
+
+Attention management for makers. Track trains of thought across projects.
+
+`ws` is a CLI tool for managing workstreams -- named trains of thought that
+span code repos, non-code activities, and time. Obsidian-native markdown files
+with YAML frontmatter, designed to be legible to both humans and LLMs.
+
+## Install
+
+```bash
+pipx install workstream-cli   # recommended
+# or
+pip install workstream-cli
+```
+
+For development:
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+ws init                        # first-time setup
+ws new "API Redesign"          # create a workstream
+ws list                        # see all workstreams
+ws next --tag code --size day  # what should I work on?
+ws stale                       # what's gone cold?
+ws sweep                       # scan repos for plan/branch updates
+ws report --since 7d           # summarize recent work
+```
+
+## Development
+
+### Running Tests
+
+```bash
+pytest                              # quick, no coverage
+pytest --cov=workstream             # with coverage report
+tox                                 # full matrix + combined coverage report
+tox -e py311                        # single Python version
+tox -e py311 -- -k test_models      # single env, filtered tests
+```
+
+### Coverage Report
+
+After running `tox` (which ends with `coverage-report`):
+- Terminal summary prints automatically
+- HTML report: open `htmlcov/index.html`
+
+For a quick local coverage check without tox:
+
+```bash
+pytest --cov=workstream --cov-report=term-missing --cov-report=html
+open htmlcov/index.html
+```
+
+## License
+
+MIT
+

workstream_cli-0.0.1/README.md

@@ -0,0 +1,61 @@
+# workstream
+
+Attention management for makers. Track trains of thought across projects.
+
+`ws` is a CLI tool for managing workstreams -- named trains of thought that
+span code repos, non-code activities, and time. Obsidian-native markdown files
+with YAML frontmatter, designed to be legible to both humans and LLMs.
+
+## Install
+
+```bash
+pipx install workstream-cli   # recommended
+# or
+pip install workstream-cli
+```
+
+For development:
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+ws init                        # first-time setup
+ws new "API Redesign"          # create a workstream
+ws list                        # see all workstreams
+ws next --tag code --size day  # what should I work on?
+ws stale                       # what's gone cold?
+ws sweep                       # scan repos for plan/branch updates
+ws report --since 7d           # summarize recent work
+```
+
+## Development
+
+### Running Tests
+
+```bash
+pytest                              # quick, no coverage
+pytest --cov=workstream             # with coverage report
+tox                                 # full matrix + combined coverage report
+tox -e py311                        # single Python version
+tox -e py311 -- -k test_models      # single env, filtered tests
+```
+
+### Coverage Report
+
+After running `tox` (which ends with `coverage-report`):
+- Terminal summary prints automatically
+- HTML report: open `htmlcov/index.html`
+
+For a quick local coverage check without tox:
+
+```bash
+pytest --cov=workstream --cov-report=term-missing --cov-report=html
+open htmlcov/index.html
+```
+
+## License
+
+MIT

workstream_cli-0.0.1/pyproject.toml

@@ -0,0 +1,63 @@
+[tool.poetry]
+name = "workstream-cli"
+version = "0.0.1"
+readme = "README.md"
+description = "Attention management for makers. Track trains of thought across projects."
+authors = ["Mahmoud Hashemi <mahmoud@hatnote.com>"]
+license = "MIT"
+packages = [{include = "workstream", from = "src"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "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 :: Only",
+    "Topic :: Office/Business :: Scheduling",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+keywords = ["workstream", "productivity", "cli", "attention-management", "task-management"]
+
+[tool.poetry.scripts]
+ws = "workstream.cli:main"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+face = ">=20.0.0"
+pyyaml = "^6.0"
+ashes = ">=24.0.0"
+clastic = ">=24.0.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4"
+pytest-cov = ">=4.1"
+coverage = {version = ">=7.0", extras = ["toml"]}
+tox = ">=4.0"
+
+[tool.poetry.urls]
+Homepage = "https://github.com/mahmoud/workstream"
+Repository = "https://github.com/mahmoud/workstream"
+
+[tool.pytest.ini_options]
+testpaths = ["src/workstream/test"]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.coverage.run]
+source = ["workstream"]
+branch = true
+omit = ["src/workstream/test/*"]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+
+[tool.coverage.html]
+directory = "htmlcov"

workstream_cli-0.0.1/src/workstream/ARCHITECTURE.md

@@ -0,0 +1,89 @@
+# ws Architecture
+
+ws is a workstream manager — it tracks trains of thought spanning projects and time.
+Data lives as markdown files in `_Workstreams/`, each with YAML frontmatter and a markdown body.
+
+## Execution Modes
+
+ws operates in four distinct modes depending on who initiates the call and how results are consumed.
+
+| Mode       | Who drives       | LLM involved | ws lifetime        | Examples                                          |
+|------------|------------------|--------------|--------------------|----------------------------------------------------|
+| **direct** | User via CLI     | No           | Runs and exits     | `ws list`, `ws stale`, `ws next`, `ws report`, `ws show` |
+| **handoff**| User via CLI     | Yes (omp)    | Execs into omp     | `ws review`, `ws sweep --review-plans`, `ws init` bootstrap |
+| **batch**  | User via CLI     | Yes (loop)   | Stays alive        | `ws sweep --discover`, `ws sweep --review-plans --batch`, summary backfill |
+| **tool**   | Agent in omp     | Already running | Runs and exits  | Agent runs `ws stale`, `ws show`, etc. as tool calls |
+
+### Direct
+
+Deterministic CLI commands. Pure Python, no LLM. Read workstream files, compute, print.
+
+### Handoff
+
+ws gathers context, writes a manifest to a temp file, then **replaces itself** via `os.execv` into an omp/claude harness process. The harness receives the manifest as `--append-system-prompt` and a skill directive. After exec, ws is gone — the harness owns the session.
+
+### Batch
+
+ws orchestrates repeated LLM calls in a loop. It stays alive as the driver: sends prompts via `llm.py`, parses structured responses, writes results back to workstream files. Used for bulk operations where interactive review is unnecessary.
+
+### Tool
+
+The user is already inside an omp session. The agent calls ws CLI commands as tools. ws is a passive data source — it reads, computes, prints, and exits. No handoff occurs.
+
+## Recursion Guard
+
+When a handoff command is invoked from **within** an existing omp session (tool mode), ws must not exec into a second harness. Detection: check for `$OMPCODE=1` or `$CLAUDECODE=1` environment variables. When detected, print the context manifest to stdout instead of calling `os.execv`. See `commands/sweep.py` for the handoff path.
+
+## Data Model
+
+All types live in `models.py`. No I/O — pure dataclasses and helpers.
+
+| Type            | Description                                              |
+|-----------------|----------------------------------------------------------|
+| `Workstream`    | Top-level entity: id, title, status, size, tags, repos, timestamps, thread, plans, branches, next_actions, log, thoughts, ideas, decisions, summary |
+| `ThreadEntry`   | Timestamped narrative entry in a workstream's thread     |
+| `ThoughtEntry`  | Captured thought with timestamp and content              |
+| `IdeaEntry`     | Idea with timestamp and content                          |
+| `PlanRef`       | Reference to a plan file: path, id, optional workstream  |
+| `BranchRef`     | Reference to a git branch: name, repo, optional dates    |
+| `LogEntry`      | Timestamped structured log entry (action + detail)       |
+
+Serialization to/from markdown+YAML frontmatter is handled by `markdown.py`.
+
+## Key Modules
+
+| Module              | Responsibility                                                        |
+|---------------------|-----------------------------------------------------------------------|
+| `cli.py`            | Entry point, face `Command` tree, middleware for config loading        |
+| `config.py`         | Config discovery (`$WS_DIR`, walk-up, global pointer), LLM detection  |
+| `models.py`         | Dataclasses for all entities. Pure data + helpers, no I/O             |
+| `markdown.py`       | YAML frontmatter round-trip, section-level read/write                 |
+| `llm.py`            | LLM shell-out abstraction — detect and invoke CLI-based LLM agents    |
+| `git.py`            | Thin subprocess wrappers for branch and commit queries                |
+| `repo_discovery.py` | Scan directories for git repos, build activity index                  |
+| `sweep_state.py`    | Persistent state for sweep deduplication across runs                  |
+| `thoughts.py`       | Thought/snooze computation helpers                                    |
+| `web.py`            | Live web dashboard                                                    |
+
+### Commands (`commands/`)
+
+| Command       | Mode     | What it does                                              |
+|---------------|----------|-----------------------------------------------------------|
+| `init`        | handoff  | First-time setup, install harness skills, optional bootstrap |
+| `list_cmd`    | direct   | Tabular listing of workstreams                            |
+| `show`        | direct   | Display a single workstream by id prefix                  |
+| `stale`       | direct   | Find workstreams that need attention                      |
+| `next_cmd`    | direct   | Prioritized active workstreams by staleness               |
+| `report`      | direct   | Activity report across workstreams                        |
+| `sweep`       | all four | Scan repos, discover/review plans, batch or interactive   |
+| `backfill`    | batch    | Add IDs and infer associations for plan files             |
+| `checkin`     | direct   | Record a check-in on a workstream                         |
+| `new`         | direct   | Create a new workstream                                   |
+| `idea`        | direct   | Idea capture, listing, promotion                          |
+| `snooze`      | direct   | Snooze/wake workstreams                                   |
+| `nest`        | direct   | Workstream hierarchy (nest/unnest)                        |
+| `tree`        | direct   | ASCII tree of workstream hierarchy                        |
+| `index`       | direct   | Generate index.md for the workstreams directory           |
+| `serve`       | direct   | Live web dashboard server                                 |
+| `setup`       | direct   | Validate installation health, optionally fix              |
+| `cron`        | direct   | Set up periodic sweep in user crontab                     |

workstream_cli-0.0.1/src/workstream/__init__.py

@@ -0,0 +1,8 @@
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version('workstream')
+except PackageNotFoundError:
+    __version__ = '0.1.0-dev'
+
+__all__ = ['__version__']

workstream_cli-0.0.1/src/workstream/cli.py

@@ -0,0 +1,136 @@
+"""ws CLI entry point and shared helpers."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from face import Command, CommandLineError, UsageError, face_middleware
+
+from workstream.config import Config, apply_timezone, load_config
+from workstream.markdown import load_workstream
+from workstream.models import Workstream, slugify
+
+
+# Files that live in the workstream directory but aren't workstream files.
+_SKIP_FILES = frozenset(('index.md', 'inbox.md', 'dashboard.html'))
+
+
+def load_all_workstreams(ws_dir: Path) -> list[Workstream]:
+    """Load every workstream from *ws_dir*, skipping non-workstream files."""
+    result: list[Workstream] = []
+    for f in sorted(ws_dir.glob('*.md')):
+        if f.name in _SKIP_FILES:
+            continue
+        try:
+            result.append(load_workstream(f))
+        except Exception:
+            continue
+    return result
+
+
+def resolve_workstream(config: Config, id_prefix: str) -> Workstream:
+    """Find the unique workstream matching *id_prefix*.
+
+    Matches against full ID, hex suffix, any prefix/suffix of the ID,
+    or title slug prefix. Raises ``UsageError`` on zero or multiple matches.
+    """
+    ws_dir = config.workstreams_path
+    matches: list[Workstream] = []
+    for ws in load_all_workstreams(ws_dir):
+        # Match: full ID prefix, full ID suffix, hex-suffix prefix, or slug prefix
+        hex_suffix = ws.id.split('-', 3)[-1]  # e.g. 'a1b2c3d4e5'
+        slug = slugify(ws.title)
+        if (ws.id.startswith(id_prefix)
+                or ws.id.endswith(id_prefix)
+                or hex_suffix.startswith(id_prefix)
+                or slug.startswith(id_prefix)):
+            matches.append(ws)
+
+    if len(matches) == 0:
+        raise UsageError(f'No workstream matching "{id_prefix}"')
+    if len(matches) > 1:
+        names = ', '.join(f'{w.id} ({w.title})' for w in matches)
+        raise UsageError(f'Multiple matches for "{id_prefix}": {names}')
+    return matches[0]
+
+
+# ---------------------------------------------------------------------------
+# Middleware: resolve config via --dir flag / env var / auto-discovery
+# ---------------------------------------------------------------------------
+
+@face_middleware(provides=['config'], optional=True)
+def mw_load_config(next_, dir):
+    """Resolve workstreams dir from --dir flag, $WS_DIR, or auto-discovery."""
+    if dir:
+        ws_dir = Path(dir).expanduser().resolve()
+        # Accept both notes root (parent dir) and direct _Workstreams path
+        candidate = ws_dir / '_Workstreams'
+        if candidate.is_dir():
+            ws_dir = candidate
+        elif not ws_dir.is_dir():
+            # CommandLineError from middleware doesn't get printed by face's
+            # run loop; print explicitly so the user sees the message.
+            print(f'error: --dir: directory does not exist: {ws_dir}', file=sys.stderr)
+            raise SystemExit(1)
+        config = load_config(ws_dir_override=ws_dir)
+    else:
+        config = load_config()
+        # Guard: if we resolved a workstreams dir but it has no config.yaml,
+        # the pointer is stale or WS_DIR is pointing at the wrong directory.
+        if config.workstreams_dir:
+            ws_path = Path(config.workstreams_dir)
+            if ws_path.is_dir() and not (ws_path / 'config.yaml').exists():
+                raise UsageError(
+                    f'Directory {str(ws_path)!r} has no workstream config (config.yaml).\n'
+                    f"Is $WS_DIR set correctly? Run 'ws init' to initialize."
+                )
+    apply_timezone(config)
+    return next_(config=config)
+
+
+def build_command() -> Command:
+    """Construct the top-level ``ws`` command with all subcommands."""
+    cmd = Command(None, name='ws', doc='Workstream manager \u2014 track trains of thought across projects.')
+    cmd.add('--dir', parse_as=str, missing=None,
+            doc='Workstreams directory (or parent); overrides $WS_DIR and auto-discovery')
+    cmd.add(mw_load_config)
+
+    from workstream.commands import init, new, list_cmd, show, report, index, next_cmd, stale, sweep, serve, backfill, cron, nest, tree, snooze, idea, checkin, setup, inspect_cmd, review, block, focus_cmd, resume, update_status
+
+    cmd.add(init.get_command())
+    cmd.add(new.get_command())
+    cmd.add(list_cmd.get_command())
+    cmd.add(show.get_command())
+    cmd.add(report.get_command())
+    cmd.add(index.get_command())
+    cmd.add(next_cmd.get_command())
+    cmd.add(stale.get_command())
+    cmd.add(sweep.get_command())
+    cmd.add(serve.get_command())
+    cmd.add(backfill.get_command())
+    cmd.add(cron.get_command())
+    cmd.add(nest.get_nest_command())
+    cmd.add(nest.get_unnest_command())
+    cmd.add(tree.get_command())
+    cmd.add(snooze.get_command())
+    cmd.add(snooze.get_wake_command())
+    cmd.add(idea.get_idea_command())
+    cmd.add(idea.get_ideas_command())
+    cmd.add(idea.get_promote_command())
+    cmd.add(checkin.get_command())
+    cmd.add(inspect_cmd.get_command())
+    cmd.add(setup.get_command())
+    cmd.add(review.get_command())
+    cmd.add(block.get_command())
+    cmd.add(block.get_unblock_command())
+    cmd.add(focus_cmd.get_command())
+    cmd.add(resume.get_command())
+    cmd.add(update_status.get_command())
+    return cmd
+
+
+def main() -> None:
+    """CLI entry point."""
+    cmd = build_command()
+    cmd.run()

workstream_cli-0.0.1/src/workstream/commands/backfill.py

@@ -0,0 +1,139 @@
+"""ws backfill — add IDs and infer workstream associations for .plans/ files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from face import Command
+
+from workstream.config import Config
+from workstream.cli import load_all_workstreams
+from workstream.markdown import parse_frontmatter, write_frontmatter
+from workstream.models import ACTIVE_STATUSES, generate_id, slugify
+
+
+def _load_active_workstreams(config):
+    """Load active workstreams from the configured directory."""
+    return [ws for ws in load_all_workstreams(config.workstreams_path)
+            if ws.status in ACTIVE_STATUSES]
+
+
+def _slug_overlap(plan_slug: str, ws_slug: str) -> bool:
+    """Check if plan slug shares meaningful tokens with workstream slug."""
+    plan_parts = set(plan_slug.split('-'))
+    ws_parts = set(ws_slug.split('-'))
+    # Remove trivially short tokens (single chars, empty)
+    plan_parts = {p for p in plan_parts if len(p) > 1}
+    ws_parts = {p for p in ws_parts if len(p) > 1}
+    if not plan_parts or not ws_parts:
+        return False
+    return bool(plan_parts & ws_parts)
+
+
+def _infer_workstream(repo_name: str, plan_slug: str, workstreams):
+    """Try to infer the workstream for a plan.
+
+    Returns the workstream ID if exactly one active workstream matches
+    by repo AND has title/slug overlap. Returns None otherwise.
+    """
+    candidates = []
+    for ws in workstreams:
+        if repo_name not in ws.repos:
+            continue
+        ws_slug = slugify(ws.title)
+        if _slug_overlap(plan_slug, ws_slug):
+            candidates.append(ws)
+    if len(candidates) == 1:
+        return candidates[0].id
+    return None
+
+
+def _backfill_handler(config: Config, dry_run: bool = False) -> None:
+    workstreams = _load_active_workstreams(config)
+
+    total_plans = 0
+    ids_added = 0
+    ws_associated = 0
+
+    for repo_cfg in config.repos:
+        repo_path = Path(repo_cfg.path).expanduser()
+        plans_dir = config.get_plans_dir(repo_cfg.name, repo_path)
+        if not plans_dir.is_dir():
+            continue
+
+        for plan_file in sorted(plans_dir.glob('*.md')):
+            total_plans += 1
+            try:
+                text = plan_file.read_text(encoding='utf-8')
+                meta, body = parse_frontmatter(text)
+            except Exception as exc:
+                print(f'  warning: skipping {repo_cfg.name}/{plan_file.name}: {exc}')
+                continue
+
+            changed = False
+            plan_id = meta.get('id', '')
+            title = meta.get('title', plan_file.stem)
+            plan_slug = slugify(title)
+
+            # Step b/c: ensure plan has an ID and filename matches
+            if not plan_id:
+                plan_id = generate_id()
+                meta['id'] = plan_id
+                changed = True
+                ids_added += 1
+                if dry_run:
+                    print(f'  would add id {plan_id} to {repo_cfg.name}/{plan_file.name}')
+
+            # Determine canonical filename
+            canonical_name = f'{plan_id}-{plan_slug}.md'
+            needs_rename = plan_file.name != canonical_name
+
+            # Step d: infer workstream if empty
+            ws_field = meta.get('workstream', '')
+            if not ws_field:
+                inferred = _infer_workstream(repo_cfg.name, plan_slug, workstreams)
+                if inferred:
+                    meta['workstream'] = inferred
+                    changed = True
+                    ws_associated += 1
+                    if dry_run:
+                        print(f'  would set workstream={inferred} on {repo_cfg.name}/{plan_file.name}')
+
+            if not changed and not needs_rename:
+                continue
+
+            if dry_run:
+                if needs_rename:
+                    print(f'  would rename {repo_cfg.name}/{plan_file.name} -> {canonical_name}')
+                continue
+
+            # Write updated frontmatter
+            new_text = write_frontmatter(meta, body)
+
+            if needs_rename:
+                new_path = plans_dir / canonical_name
+                if new_path.exists() and new_path != plan_file:
+                    print(f'  warning: cannot rename {plan_file.name} -> {canonical_name}: target exists')
+                    # Still write updated metadata to the original file
+                    plan_file.write_text(new_text, encoding='utf-8')
+                else:
+                    plan_file.write_text(new_text, encoding='utf-8')
+                    if new_path != plan_file:
+                        plan_file.rename(new_path)
+                        print(f'  renamed {repo_cfg.name}/{plan_file.name} -> {canonical_name}')
+            else:
+                plan_file.write_text(new_text, encoding='utf-8')
+
+    label = 'Would process' if dry_run else 'Processed'
+    print(f'Backfill {"(dry run) " if dry_run else ""}complete: '
+          f'{total_plans} plans {label.lower()}, '
+          f'{ids_added} IDs added, '
+          f'{ws_associated} workstream associations made.')
+
+
+def get_command() -> Command:
+    cmd = Command(_backfill_handler, name='backfill',
+                  doc='Add IDs and infer workstream associations for .plans/ files.')
+    cmd.add('--dry-run', parse_as=True,
+            doc='Show what would be done without modifying files.')
+    return cmd