cowork-flow 0.0.1

package/template/.cowork-flow/scripts/change.py

@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Cowork Flow change 管理脚本。"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from common.paths import DIR_ARCHIVE, DIR_CHANGES, DIR_WORKFLOW, get_repo_root
+
+
+SLUG_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+VALID_LEVELS = {"L1", "L2"}
+VALID_STATUSES = {"draft", "active", "archived"}
+
+
+def _now_iso() -> str:
+    return datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def _changes_dir(repo_root: Path) -> Path:
+    return repo_root / DIR_WORKFLOW / DIR_CHANGES
+
+
+def _change_dir(repo_root: Path, slug: str) -> Path:
+    return _changes_dir(repo_root) / slug
+
+
+def _archive_dir(repo_root: Path) -> Path:
+    return _changes_dir(repo_root) / DIR_ARCHIVE
+
+
+def _validate_slug(slug: str) -> bool:
+    if SLUG_PATTERN.fullmatch(slug):
+        return True
+    print(
+        "Error: slug must match lowercase hyphenated pattern "
+        "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+        file=sys.stderr,
+    )
+    return False
+
+
+def _metadata_path(change_dir: Path) -> Path:
+    return change_dir / "change.yaml"
+
+
+def _format_scalar(value: object) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _write_metadata(change_dir: Path, metadata: dict[str, object]) -> None:
+    lines = [f"{key}: {_format_scalar(value)}\n" for key, value in metadata.items()]
+    _metadata_path(change_dir).write_text("".join(lines), encoding="utf-8")
+
+
+def _parse_scalar(value: str) -> object:
+    if value == "null":
+        return None
+    if value == "true":
+        return True
+    if value == "false":
+        return False
+    return value
+
+
+def _read_metadata(change_dir: Path) -> dict[str, object]:
+    path = _metadata_path(change_dir)
+    data: dict[str, object] = {}
+    if not path.is_file():
+        return data
+
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        data[key.strip()] = _parse_scalar(value.strip())
+    return data
+
+
+def _has_text(path: Path) -> bool:
+    return path.is_file() and bool(path.read_text(encoding="utf-8").strip())
+
+
+def _spec_files(change_dir: Path) -> list[Path]:
+    specs_dir = change_dir / "specs"
+    if not specs_dir.is_dir():
+        return []
+    return sorted(path for path in specs_dir.rglob("spec.md") if path.is_file())
+
+
+def _resolve_link(repo_root: Path, base_dir: str, value: object) -> Path | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip():
+        return None
+
+    raw_path = Path(value)
+    if raw_path.is_absolute():
+        return raw_path
+
+    direct = repo_root / raw_path
+    if direct.exists():
+        return direct
+    return repo_root / DIR_WORKFLOW / base_dir / raw_path
+
+
+def _validate_link(repo_root: Path, metadata: dict[str, object], field: str, base_dir: str) -> str | None:
+    target = _resolve_link(repo_root, base_dir, metadata.get(field))
+    if target is not None and not target.exists():
+        return f"{field} points to missing path: {target}"
+    return None
+
+
+def validate_change(repo_root: Path, slug: str, quiet: bool = False) -> bool:
+    if not _validate_slug(slug):
+        return False
+
+    change_dir = _change_dir(repo_root, slug)
+    errors: list[str] = []
+
+    if not change_dir.is_dir():
+        errors.append(f"change not found: {slug}")
+    else:
+        metadata = _read_metadata(change_dir)
+        if not metadata:
+            errors.append("missing change.yaml")
+
+        if metadata.get("slug") != slug:
+            errors.append("change.yaml slug does not match directory name")
+
+        status = metadata.get("status")
+        if status not in VALID_STATUSES:
+            errors.append("change.yaml status must be draft, active, or archived")
+
+        level = metadata.get("level")
+        if level not in VALID_LEVELS:
+            errors.append("change.yaml level must be L1 or L2")
+
+        if not _has_text(change_dir / "proposal.md"):
+            errors.append("proposal.md is missing or empty")
+
+        documentation_only = metadata.get("documentation_only") is True
+        if not documentation_only:
+            specs = _spec_files(change_dir)
+            if not specs or not any(_has_text(spec) for spec in specs):
+                errors.append("specs must include at least one non-empty behavior spec")
+
+        if level == "L2" and not _has_text(change_dir / "design.md"):
+            errors.append("design.md is required for L2 changes")
+
+        plan_error = _validate_link(repo_root, metadata, "plan", "plans")
+        if plan_error:
+            errors.append(plan_error)
+
+        task_error = _validate_link(repo_root, metadata, "task", "tasks")
+        if task_error:
+            errors.append(task_error)
+
+    if errors:
+        for error in errors:
+            print(f"Error: {error}", file=sys.stderr)
+        return False
+
+    if not quiet:
+        print(f"{slug} valid")
+    return True
+
+
+def create_change(args: argparse.Namespace) -> int:
+    repo_root = get_repo_root()
+    slug = args.slug
+    if not _validate_slug(slug):
+        return 2
+
+    change_dir = _change_dir(repo_root, slug)
+    if change_dir.exists():
+        print(f"Error: change already exists: {slug}", file=sys.stderr)
+        return 1
+
+    change_dir.mkdir(parents=True)
+    (change_dir / "specs").mkdir()
+    (change_dir / "proposal.md").write_text(
+        f"# {slug}\n\nDescribe the proposed behavior change.\n",
+        encoding="utf-8",
+    )
+    (change_dir / "design.md").write_text("", encoding="utf-8")
+    (change_dir / "specs" / ".gitkeep").write_text("", encoding="utf-8")
+    _write_metadata(
+        change_dir,
+        {
+            "slug": slug,
+            "status": "draft",
+            "level": args.level,
+            "created_at": _now_iso(),
+            "documentation_only": False,
+            "plan": None,
+            "task": None,
+        },
+    )
+
+    print(f"created {slug}")
+    return 0
+
+
+def validate_command(args: argparse.Namespace) -> int:
+    repo_root = get_repo_root()
+    return 0 if validate_change(repo_root, args.slug) else 1
+
+
+def archive_change(args: argparse.Namespace) -> int:
+    repo_root = get_repo_root()
+    slug = args.slug
+    if not validate_change(repo_root, slug, quiet=True):
+        return 1
+
+    source = _change_dir(repo_root, slug)
+    month = datetime.now().astimezone().strftime("%Y-%m")
+    destination = _archive_dir(repo_root) / month / slug
+    if destination.exists():
+        print(f"Error: archive destination already exists: {destination}", file=sys.stderr)
+        return 1
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(source), str(destination))
+
+    metadata = _read_metadata(destination)
+    metadata["status"] = "archived"
+    metadata["archived_at"] = _now_iso()
+    _write_metadata(destination, metadata)
+
+    print(f"archived {slug}")
+    return 0
+
+
+def _change_rows(repo_root: Path) -> list[tuple[str, dict[str, object]]]:
+    rows: list[tuple[str, dict[str, object]]] = []
+    changes_dir = _changes_dir(repo_root)
+
+    if changes_dir.is_dir():
+        for path in sorted(changes_dir.iterdir()):
+            if not path.is_dir() or path.name == DIR_ARCHIVE:
+                continue
+            rows.append((path.name, _read_metadata(path)))
+
+    archive_dir = _archive_dir(repo_root)
+    if archive_dir.is_dir():
+        for metadata_path in sorted(archive_dir.glob("*/*/change.yaml")):
+            change_dir = metadata_path.parent
+            rows.append((change_dir.name, _read_metadata(change_dir)))
+
+    return rows
+
+
+def list_changes(args: argparse.Namespace) -> int:
+    repo_root = get_repo_root()
+    rows = _change_rows(repo_root)
+    if not rows:
+        print("No changes")
+        return 0
+
+    for slug, metadata in rows:
+        status = metadata.get("status", "unknown")
+        level = metadata.get("level", "unknown")
+        plan = metadata.get("plan")
+        task = metadata.get("task")
+        print(
+            f"{slug}\tstatus={status}\tlevel={level}\t"
+            f"plan={_format_scalar(plan)}\ttask={_format_scalar(task)}"
+        )
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Manage Cowork Flow changes")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    create_parser = subparsers.add_parser("create")
+    create_parser.add_argument("slug")
+    create_parser.add_argument("--level", choices=sorted(VALID_LEVELS), default="L1")
+    create_parser.set_defaults(func=create_change)
+
+    validate_parser = subparsers.add_parser("validate")
+    validate_parser.add_argument("slug")
+    validate_parser.set_defaults(func=validate_command)
+
+    archive_parser = subparsers.add_parser("archive")
+    archive_parser.add_argument("slug")
+    archive_parser.set_defaults(func=archive_change)
+
+    list_parser = subparsers.add_parser("list")
+    list_parser.set_defaults(func=list_changes)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/template/.cowork-flow/scripts/common/__init__.py

@@ -0,0 +1,84 @@
+"""
+Common utilities for cowork-flow workflow scripts.
+
+This module provides shared functionality used by other cowork-flow scripts.
+"""
+
+import io
+import sys
+
+# =============================================================================
+# Windows Encoding Fix (MUST be at top, before any other output)
+# =============================================================================
+# On Windows, stdout defaults to the system code page (often GBK/CP936).
+# This causes UnicodeEncodeError when printing non-ASCII characters.
+#
+# Any script that imports from common will automatically get this fix.
+# =============================================================================
+
+
+def _configure_stream(stream: object) -> object:
+    """Configure a stream for UTF-8 encoding on Windows."""
+    # Try reconfigure() first (Python 3.7+, more reliable)
+    if hasattr(stream, "reconfigure"):
+        stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+        return stream
+    # Fallback: detach and rewrap with TextIOWrapper
+    elif hasattr(stream, "detach"):
+        return io.TextIOWrapper(
+            stream.detach(),  # type: ignore[union-attr]
+            encoding="utf-8",
+            errors="replace",
+        )
+    return stream
+
+
+if sys.platform == "win32":
+    sys.stdout = _configure_stream(sys.stdout)  # type: ignore[assignment]
+    sys.stderr = _configure_stream(sys.stderr)  # type: ignore[assignment]
+    sys.stdin = _configure_stream(sys.stdin)  # type: ignore[assignment]
+
+
+def configure_encoding() -> None:
+    """
+    Configure stdout/stderr/stdin for UTF-8 encoding on Windows.
+
+    This is automatically called when importing from common,
+    but can be called manually for scripts that don't import common.
+
+    Safe to call multiple times.
+    """
+    global sys
+    if sys.platform == "win32":
+        sys.stdout = _configure_stream(sys.stdout)  # type: ignore[assignment]
+        sys.stderr = _configure_stream(sys.stderr)  # type: ignore[assignment]
+        sys.stdin = _configure_stream(sys.stdin)  # type: ignore[assignment]
+
+
+from .paths import (
+    DIR_WORKFLOW,
+    DIR_AGENT,
+    DIR_CHANGES,
+    DIR_WORKSPACE,
+    DIR_TASKS,
+    DIR_ARCHIVE,
+    DIR_SPEC,
+    DIR_SCRIPTS,
+    FILE_DEVELOPER,
+    FILE_CURRENT_TASK,
+    FILE_TASK_JSON,
+    FILE_JOURNAL_PREFIX,
+    get_repo_root,
+    get_developer,
+    check_developer,
+    get_tasks_dir,
+    get_workspace_dir,
+    get_active_journal_file,
+    count_lines,
+    get_current_task,
+    get_current_task_abs,
+    set_current_task,
+    clear_current_task,
+    has_current_task,
+    generate_task_date_prefix,
+)

package/template/.cowork-flow/scripts/common/config.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""
+cowork-flow configuration reader.
+
+Reads settings from .cowork-flow/config.yaml with sensible defaults.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .paths import DIR_WORKFLOW, get_repo_root
+
+
+# Defaults
+DEFAULT_SESSION_COMMIT_MESSAGE = "chore: record journal"
+DEFAULT_MAX_JOURNAL_LINES = 2000
+
+CONFIG_FILE = "config.yaml"
+
+
+def _unquote(value: str) -> str:
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+        return value[1:-1]
+    return value
+
+
+def _parse_simple_yaml(content: str) -> dict:
+    result: dict = {}
+    current_section: str | None = None
+    current_list_key: str | None = None
+
+    for raw_line in content.splitlines():
+        stripped = raw_line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        indent = len(raw_line) - len(raw_line.lstrip())
+
+        if indent == 0 and ":" in stripped:
+            key, _, value = stripped.partition(":")
+            key = key.strip()
+            value = _unquote(value.strip())
+            current_section = None
+            current_list_key = None
+
+            if value:
+                result[key] = value
+            else:
+                result[key] = {}
+                current_section = key
+            continue
+
+        if current_section and indent >= 2:
+            section = result.setdefault(current_section, {})
+            if not isinstance(section, dict):
+                continue
+
+            if stripped.startswith("- ") and current_list_key:
+                current_list = section.setdefault(current_list_key, [])
+                if isinstance(current_list, list):
+                    current_list.append(_unquote(stripped[2:].strip()))
+                continue
+
+            if ":" in stripped:
+                key, _, value = stripped.partition(":")
+                key = key.strip()
+                value = _unquote(value.strip())
+                if value:
+                    section[key] = value
+                    current_list_key = None
+                else:
+                    section[key] = []
+                    current_list_key = key
+
+    return result
+
+
+def _get_config_path(repo_root: Path | None = None) -> Path:
+    """Get path to config.yaml."""
+    root = repo_root or get_repo_root()
+    return root / DIR_WORKFLOW / CONFIG_FILE
+
+
+def _load_config(repo_root: Path | None = None) -> dict:
+    """Load and parse config.yaml. Returns empty dict on any error."""
+    config_file = _get_config_path(repo_root)
+    try:
+        content = config_file.read_text(encoding="utf-8")
+        return _parse_simple_yaml(content)
+    except (OSError, IOError):
+        return {}
+
+
+def get_session_commit_message(repo_root: Path | None = None) -> str:
+    """Get the commit message for auto-committing session records."""
+    config = _load_config(repo_root)
+    return config.get("session_commit_message", DEFAULT_SESSION_COMMIT_MESSAGE)
+
+
+def get_max_journal_lines(repo_root: Path | None = None) -> int:
+    """Get the maximum lines per journal file."""
+    config = _load_config(repo_root)
+    value = config.get("max_journal_lines", DEFAULT_MAX_JOURNAL_LINES)
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return DEFAULT_MAX_JOURNAL_LINES
+
+
+def get_hooks(event: str, repo_root: Path | None = None) -> list[str]:
+    """Get hook commands for a lifecycle event.
+
+    Args:
+        event: Event name (e.g. "after_create", "after_archive").
+        repo_root: Repository root path.
+
+    Returns:
+        List of shell commands to execute, empty if none configured.
+    """
+    config = _load_config(repo_root)
+    hooks = config.get("hooks")
+    if not isinstance(hooks, dict):
+        return []
+    commands = hooks.get(event)
+    if isinstance(commands, list):
+        return [str(c) for c in commands]
+    return []