markstate 0.1.0__tar.gz

markstate-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: markstate
+Version: 0.1.0
+Summary: Generic document flow processor for state tracking in markdown front matter
+Requires-Python: >=3.11
+Requires-Dist: click>=8.3.1
+Requires-Dist: pyyaml>=6.0.3

markstate-0.1.0/README.md

@@ -0,0 +1,139 @@
+# markstate
+
+Generic document flow processor for state tracking in markdown front matter.
+
+Define a workflow in `flow.yml` — phases, gate conditions, and moves — then use `markstate` to track and advance documents through the flow.
+
+## Install
+
+```bash
+pip install markstate
+```
+
+## Quick start
+
+Create `flow.yml` in your project root:
+
+```yaml
+status_field: status
+
+phases:
+  - name: drafting
+    advance_when:
+      - file: spec.md
+        status: approved
+
+  - name: review
+    gates:
+      - file: spec.md
+        status: approved
+    advance_when:
+      - glob: "docs/*.md"
+        all_status: reviewed
+
+moves:
+  - name: approve-spec
+    from: draft
+    to: approved
+
+  - name: mark-reviewed
+    from: in-review
+    to: reviewed
+```
+
+Documents are markdown files with YAML front matter:
+
+```markdown
+---
+status: draft
+---
+
+# My document
+```
+
+## Commands
+
+```
+markstate status [DIRECTORY]        Show current phase and completion status
+markstate do MOVE TARGET            Apply a named move to a document
+markstate moves                     List all available moves
+markstate check-gate PHASE [DIR]    Check if gate conditions for a phase are met
+```
+
+### `status`
+
+```
+$ markstate status
+current phase: drafting
+
+  drafting              gates=ok  in progress
+  review                gates=blocked  in progress
+```
+
+Add `--json` for machine-readable output.
+
+### `do`
+
+Apply a move to advance a document's status:
+
+```
+$ markstate do approve-spec spec.md
+spec.md: draft → approved
+```
+
+Moves are validated against the current status — applying a move to a document in the wrong state is an error.
+
+### `moves`
+
+```
+$ markstate moves
+  approve-spec          draft → approved
+  mark-reviewed         in-review → reviewed
+```
+
+### `check-gate`
+
+Exits 0 if all gate conditions pass, 1 otherwise:
+
+```
+$ markstate check-gate review
+gate not satisfied:
+  - spec.md must have status 'approved'
+```
+
+## Configuration reference
+
+`flow.yml` is discovered by walking up from the current directory.
+
+| Field | Description |
+|---|---|
+| `status_field` | Front matter key to track state (default: `status`) |
+| `phases` | Ordered list of phases |
+| `moves` | Named transitions between states |
+
+**Phase fields:**
+
+| Field | Description |
+|---|---|
+| `name` | Phase name |
+| `gates` | Conditions that must pass to enter this phase |
+| `advance_when` | Conditions that must pass to leave this phase |
+
+**Condition fields** (use one pair):
+
+| Fields | Description |
+|---|---|
+| `file` + `status` | A specific file must have the given status |
+| `glob` + `all_status` | All files matching the glob must have the given status |
+
+**Move fields:**
+
+| Field | Description |
+|---|---|
+| `name` | Move name (used with `markstate do`) |
+| `from` | Required current status |
+| `to` | New status after applying the move |
+
+## License
+
+MIT

markstate-0.1.0/markstate/__main__.py

@@ -0,0 +1,4 @@
+from markstate.cli import main
+
+if __name__ == "__main__":
+    main()

markstate-0.1.0/markstate/cli.py

@@ -0,0 +1,111 @@
+"""CLI entry point for doc-flow."""
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from markstate import engine
+from markstate.config import FlowConfig, find_and_load
+from markstate.engine import MoveError
+
+
+def _load_config() -> FlowConfig:
+    try:
+        return find_and_load()
+    except FileNotFoundError as e:
+        click.echo(f"error: {e}", err=True)
+        sys.exit(1)
+
+
+@click.group()
+def main() -> None:
+    """Generic document flow processor."""
+
+
+@main.command()
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+@click.argument("directory", default=".", type=click.Path(exists=True, file_okay=False, path_type=Path))
+def status(as_json: bool, directory: Path) -> None:
+    """Show current phase and phase completion status."""
+    config = _load_config()
+    result = engine.status(config, directory.resolve())
+    if as_json:
+        click.echo(json.dumps(result, indent=2))
+    else:
+        phase = result["current_phase"]
+        click.echo(f"current phase: {phase or '(complete)'}")
+        click.echo()
+        for p in result["phases"]:
+            gate = "ok" if p["gates_pass"] else "blocked"
+            done = "complete" if p["complete"] else "in progress"
+            click.echo(f"  {p['name']:20s}  gates={gate}  {done}")
+
+
+@main.command("check-gate")
+@click.argument("phase_name")
+@click.argument("directory", default=".", type=click.Path(exists=True, file_okay=False, path_type=Path))
+def check_gate(phase_name: str, directory: Path) -> None:
+    """Check if all gate conditions for a phase are met."""
+    config = _load_config()
+    phase = config.phase(phase_name)
+    if phase is None:
+        click.echo(f"error: unknown phase '{phase_name}'", err=True)
+        sys.exit(1)
+
+    unmet = engine.check_gate(phase, config, directory.resolve())
+    if unmet:
+        click.echo("gate not satisfied:")
+        for condition in unmet:
+            click.echo(f"  - {condition}")
+        sys.exit(1)
+    else:
+        click.echo("gate satisfied")
+
+
+class MoveName(click.ParamType):
+    """Dynamic choice type that loads move names from flow.yml."""
+
+    name = "move"
+
+    def convert(self, value: str, param: click.Parameter | None, ctx: click.Context | None) -> str:
+        try:
+            config = find_and_load()
+            names = config.move_names()
+            if value not in names:
+                self.fail(f"'{value}' is not a valid move. Choose from: {', '.join(names)}", param, ctx)
+        except FileNotFoundError:
+            pass  # let the command handle the missing config
+        return value
+
+    def shell_complete(self, ctx: click.Context, param: click.Parameter, incomplete: str):
+        from click.shell_completion import CompletionItem
+
+        try:
+            config = find_and_load()
+            return [CompletionItem(name) for name in config.move_names() if name.startswith(incomplete)]
+        except FileNotFoundError:
+            return []
+
+
+@main.command("do")
+@click.argument("move_name", type=MoveName())
+@click.argument("target", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+def do_move(move_name: str, target: Path) -> None:
+    """Apply a named move to a document."""
+    config = _load_config()
+    try:
+        old, new = engine.do_move(move_name, target.resolve(), config)
+        click.echo(f"{target}: {old} → {new}")
+    except MoveError as e:
+        click.echo(f"error: {e}", err=True)
+        sys.exit(1)
+
+
+@main.command("moves")
+def list_moves() -> None:
+    """List all available moves."""
+    config = _load_config()
+    for move in config.moves:
+        click.echo(f"  {move.name:20s}  {move.from_state} → {move.to_state}")

markstate-0.1.0/markstate/config.py

@@ -0,0 +1,105 @@
+"""Load and validate flow.yml, walking up from cwd to find it."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+CONFIG_FILENAME = "flow.yml"
+
+
+@dataclass
+class Move:
+    name: str
+    from_state: str
+    to_state: str
+
+
+@dataclass
+class Condition:
+    file: str | None = None
+    glob: str | None = None
+    status: str | None = None
+    all_status: str | None = None
+
+
+@dataclass
+class Phase:
+    name: str
+    produces: list[str] = field(default_factory=list)
+    gates: list[Condition] = field(default_factory=list)
+    advance_when: list[Condition] = field(default_factory=list)
+
+
+@dataclass
+class FlowConfig:
+    root: Path
+    status_field: str
+    phases: list[Phase]
+    moves: list[Move]
+
+    def move(self, name: str) -> Move | None:
+        return next((m for m in self.moves if m.name == name), None)
+
+    def phase(self, name: str) -> Phase | None:
+        return next((p for p in self.phases if p.name == name), None)
+
+    def move_names(self) -> list[str]:
+        return [m.name for m in self.moves]
+
+
+def find_and_load(start: Path | None = None) -> FlowConfig:
+    """Walk up from start (default: cwd) to find flow.yml and load it."""
+    path = _find(start or Path.cwd())
+    if path is None:
+        raise FileNotFoundError(f"{CONFIG_FILENAME} not found in {start or Path.cwd()} or any parent")
+    return _load(path)
+
+
+def _find(start: Path) -> Path | None:
+    for directory in [start, *start.parents]:
+        candidate = directory / CONFIG_FILENAME
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _load(path: Path) -> FlowConfig:
+    raw = yaml.safe_load(path.read_text())
+
+    phases = [_parse_phase(p) for p in raw.get("phases", [])]
+    moves = [_parse_move(m) for m in raw.get("moves", [])]
+
+    return FlowConfig(
+        root=path.parent,
+        status_field=raw.get("status_field", "status"),
+        phases=phases,
+        moves=moves,
+    )
+
+
+def _parse_phase(raw: dict) -> Phase:
+    return Phase(
+        name=raw["name"],
+        produces=raw.get("produces", []),
+        gates=[_parse_condition(c) for c in raw.get("gates", [])],
+        advance_when=[_parse_condition(c) for c in raw.get("advance_when", [])],
+    )
+
+
+def _parse_move(raw: dict) -> Move:
+    return Move(
+        name=raw["name"],
+        from_state=raw["from"],
+        to_state=raw["to"],
+    )
+
+
+def _parse_condition(raw: dict) -> Condition:
+    return Condition(
+        file=raw.get("file"),
+        glob=raw.get("glob"),
+        status=raw.get("status"),
+        all_status=raw.get("all_status"),
+    )

markstate-0.1.0/markstate/engine.py

@@ -0,0 +1,93 @@
+"""State engine: evaluate conditions and execute moves."""
+
+from pathlib import Path
+
+from markstate import frontmatter
+from markstate.config import Condition, FlowConfig, Move, Phase
+
+
+class MoveError(Exception):
+    pass
+
+
+def current_phase(config: FlowConfig, directory: Path) -> Phase | None:
+    """Return the first phase whose gates all pass but advance_when conditions don't all pass."""
+    for phase in config.phases:
+        if not _all_pass(phase.gates, config, directory):
+            continue
+        if not _all_pass(phase.advance_when, config, directory):
+            return phase
+    return None
+
+
+def check_gate(phase: Phase, config: FlowConfig, directory: Path) -> list[str]:
+    """Return list of unmet gate conditions, empty if all pass."""
+    return [_describe(c) for c in phase.gates if not _evaluate(c, config, directory)]
+
+
+def do_move(move_name: str, target: Path, config: FlowConfig) -> tuple[str, str]:
+    """Execute a named move on target file. Returns (old_status, new_status)."""
+    move = config.move(move_name)
+    if move is None:
+        raise MoveError(f"unknown move '{move_name}'. Available: {config.move_names()}")
+
+    doc = frontmatter.load(target)
+    current = str(doc.get(config.status_field) or "")
+
+    if current != move.from_state:
+        raise MoveError(
+            f"cannot apply move '{move_name}' to '{target.name}': "
+            f"expected status '{move.from_state}', got '{current}'"
+        )
+
+    doc.set(config.status_field, move.to_state)
+    doc.save()
+    return current, move.to_state
+
+
+def status(config: FlowConfig, directory: Path) -> dict[str, object]:
+    """Return a status summary for the given directory."""
+    phase = current_phase(config, directory)
+    return {
+        "current_phase": phase.name if phase else None,
+        "phases": [
+            {
+                "name": p.name,
+                "gates_pass": _all_pass(p.gates, config, directory),
+                "complete": _all_pass(p.advance_when, config, directory),
+            }
+            for p in config.phases
+        ],
+    }
+
+
+def _all_pass(conditions: list[Condition], config: FlowConfig, directory: Path) -> bool:
+    return all(_evaluate(c, config, directory) for c in conditions)
+
+
+def _evaluate(condition: Condition, config: FlowConfig, directory: Path) -> bool:
+    if condition.file is not None and condition.status is not None:
+        path = directory / condition.file
+        if not path.exists():
+            return False
+        doc = frontmatter.load(path)
+        return str(doc.get(config.status_field) or "") == condition.status
+
+    if condition.glob is not None and condition.all_status is not None:
+        paths = list(directory.glob(condition.glob))
+        if not paths:
+            return False
+        return all(
+            str(frontmatter.load(p).get(config.status_field) or "") == condition.all_status
+            for p in paths
+        )
+
+    return False
+
+
+def _describe(condition: Condition) -> str:
+    if condition.file and condition.status:
+        return f"{condition.file} must have status '{condition.status}'"
+    if condition.glob and condition.all_status:
+        return f"all files matching '{condition.glob}' must have status '{condition.all_status}'"
+    return str(condition)

markstate-0.1.0/markstate/frontmatter.py

@@ -0,0 +1,48 @@
+"""Read and write YAML front matter in markdown files."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+DELIMITER = "---"
+
+
+@dataclass
+class Document:
+    path: Path
+    front_matter: dict[str, object] = field(default_factory=dict)
+    body: str = ""
+
+    def get(self, key: str) -> object | None:
+        return self.front_matter.get(key)
+
+    def set(self, key: str, value: object) -> None:
+        self.front_matter[key] = value
+
+    def save(self) -> None:
+        self.path.write_text(_serialize(self.front_matter, self.body))
+
+
+def load(path: Path) -> Document:
+    text = path.read_text()
+    front_matter, body = _parse(text)
+    return Document(path=path, front_matter=front_matter, body=body)
+
+
+def _parse(text: str) -> tuple[dict[str, object], str]:
+    if not text.startswith(DELIMITER + "\n"):
+        return {}, text
+
+    end = text.index("\n" + DELIMITER, len(DELIMITER))
+    raw = text[len(DELIMITER) + 1 : end]
+    body = text[end + len(DELIMITER) + 2 :]  # skip closing --- and newline
+    return yaml.safe_load(raw) or {}, body
+
+
+def _serialize(front_matter: dict[str, object], body: str) -> str:
+    if not front_matter:
+        return body
+    raw = yaml.dump(front_matter, default_flow_style=False, allow_unicode=True)
+    return f"{DELIMITER}\n{raw}{DELIMITER}\n{body}"

markstate-0.1.0/markstate.egg-info/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: markstate
+Version: 0.1.0
+Summary: Generic document flow processor for state tracking in markdown front matter
+Requires-Python: >=3.11
+Requires-Dist: click>=8.3.1
+Requires-Dist: pyyaml>=6.0.3

markstate-0.1.0/markstate.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+markstate/__init__.py
+markstate/__main__.py
+markstate/cli.py
+markstate/config.py
+markstate/engine.py
+markstate/frontmatter.py
+markstate.egg-info/PKG-INFO
+markstate.egg-info/SOURCES.txt
+markstate.egg-info/dependency_links.txt
+markstate.egg-info/entry_points.txt
+markstate.egg-info/requires.txt
+markstate.egg-info/top_level.txt

markstate-0.1.0/markstate.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

markstate-0.1.0/markstate.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+markstate = markstate.cli:main

markstate-0.1.0/markstate.egg-info/requires.txt

@@ -0,0 +1,2 @@
+click>=8.3.1
+pyyaml>=6.0.3

markstate-0.1.0/markstate.egg-info/top_level.txt

@@ -0,0 +1 @@
+markstate

markstate-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "markstate"
+version = "0.1.0"
+description = "Generic document flow processor for state tracking in markdown front matter"
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.3.1",
+    "pyyaml>=6.0.3",
+]
+
+[project.scripts]
+markstate = "markstate.cli:main"
+
+[tool.uv]
+package = true
+
+[[tool.uv.index]]
+url = "https://pypi.org/simple"
+default = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "F",      # pyflakes
+    "I",      # isort
+    "UP",     # pyupgrade
+]
+
+[tool.ruff.format]
+quote-style = "double"

markstate-0.1.0/setup.cfg

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