okstra 0.201.3 → 0.204.0

package/runtime/python/okstra_ctl/manager_store.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import json
 import os
+import shutil
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -18,12 +19,17 @@ from okstra_ctl.json_boundary import (
 from .manager_paths import (
     ManagerPathError,
     canonical_manager_id,
+    child_context_path,
     children_json_path,
     directives_jsonl_path,
     events_jsonl_path,
     manager_json_path,
     manager_root,
     projects_json_path,
+    snapshots_json_path,
+    task_group_meta_path,
+    task_group_root,
+    task_groups_root,
     task_manifest_path,
 )
 
@@ -96,6 +102,63 @@ def load_manager(home: Path, manager_id: str) -> dict:
     return _read_json(path)
 
 
+def _task_manifest_paths(home: Path, manager_id: str) -> list[Path]:
+    return sorted(manager_root(home, manager_id).glob("task-groups/*/*/manifest.json"))
+
+
+def list_managers(home: Path) -> list[dict]:
+    """이 홈의 manager 를 id 순으로, 소속 프로젝트 수와 manager task 수와 함께 돌려준다."""
+    base = Path(home) / "managers"
+    if not base.is_dir():
+        return []
+    items: list[dict] = []
+    for path in sorted(base.glob("*/manager.json")):
+        manager = _read_json(path)
+        manager_id = str(manager.get("managerId") or path.parent.name)
+        items.append(
+            {
+                "managerId": manager_id,
+                "createdAt": str(manager.get("createdAt") or ""),
+                "projectCount": len(_load_projects(home, manager_id).get("projects", [])),
+                "taskCount": len(_task_manifest_paths(home, manager_id)),
+            }
+        )
+    return items
+
+
+def list_projects(home: Path, manager_id: str) -> list[dict]:
+    """manager 에 등록된 프로젝트를 등록 파일(projects.json) 순서 그대로 돌려준다."""
+    load_manager(home, manager_id)
+    return [
+        project
+        for project in _load_projects(home, manager_id).get("projects", [])
+        if isinstance(project, dict)
+    ]
+
+
+def list_tasks(home: Path, manager_id: str) -> list[dict]:
+    """manager task 를 task-group, task-id 순으로 하위 task 수와 함께 돌려준다.
+
+    디렉터리 이름은 slug 라 원래 입력값과 다를 수 있으므로 식별자는 manifest 에서 읽는다.
+    """
+    load_manager(home, manager_id)
+    items: list[dict] = []
+    for path in _task_manifest_paths(home, manager_id):
+        manifest = _read_json(path)
+        children = _read_json_default(path.parent / "children.json", {"children": []})
+        items.append(
+            {
+                "taskGroup": str(manifest.get("taskGroup") or ""),
+                "taskId": str(manifest.get("taskId") or ""),
+                "objective": str(manifest.get("objective") or ""),
+                "progressMode": str(manifest.get("progressMode") or ""),
+                "createdAt": str(manifest.get("createdAt") or ""),
+                "childCount": len(children.get("children", [])),
+            }
+        )
+    return sorted(items, key=lambda item: (item["taskGroup"], item["taskId"]))
+
+
 def discover_projects(home: Path) -> list[dict]:
     base = Path(home) / "projects"
     if not base.is_dir():
@@ -167,11 +230,31 @@ def link_project(
     return payload
 
 
+def _ensure_group_meta(home: Path, manager_id: str, task_group: str, when: str) -> dict:
+    """그룹 폴더와 `group.json` 을 만든다. 이미 있으면 처음 기록을 그대로 둔다."""
+    path = task_group_meta_path(home, manager_id, task_group)
+    if path.is_file():
+        return _read_json(path)
+    meta = {"taskGroup": task_group, "createdAt": when}
+    _write_json(path, meta)
+    return meta
+
+
 def create_task_group(home: Path, manager_id: str, task_group: str, *, now: str | None = None) -> dict:
     load_manager(home, manager_id)
-    group_dir = task_manifest_path(home, manager_id, task_group, "group-marker").parents[1]
-    group_dir.mkdir(parents=True, exist_ok=True)
-    return {"managerId": manager_id, "taskGroup": task_group, "createdAt": now or _now_iso()}
+    meta = _ensure_group_meta(home, manager_id, task_group, now or _now_iso())
+    return {"managerId": manager_id, **meta}
+
+
+def _merge_manifest(existing: dict, requested: dict) -> None:
+    """이미 있는 manager task 의 manifest 값을 `new task` 가 바꾸지 못하게 한다."""
+    for key, value in requested.items():
+        if value is None or value == "" or existing.get(key) == value:
+            continue
+        raise ManagerError(
+            f"manager task already exists with {key}={existing.get(key)!r}; "
+            f"refusing to change it to {value!r}"
+        )
 
 
 def create_task(
@@ -183,32 +266,56 @@ def create_task(
     *,
     objective: str = "",
     common_brief_path: str = "",
-    progress_mode: str = "manual",
+    progress_mode: str | None = None,
     now: str | None = None,
 ) -> dict:
+    """manager task 를 만들거나, 이미 있으면 새 하위 task 만 덧붙인다.
+
+    다시 실행해도 기존 하위 task 의 assignment·launch 상태는 지우지 않는다.
+    """
+    load_manager(home, manager_id)
     projects = _load_projects(home, manager_id)
     when = now or _now_iso()
-    manifest = {
-        "managerId": manager_id,
-        "taskGroup": task_group,
-        "taskId": task_id,
-        "progressMode": progress_mode,
-        "commonBriefPath": common_brief_path,
-        "objective": objective,
-        "createdAt": when,
-    }
-    children = []
+    manifest_path = task_manifest_path(home, manager_id, task_group, task_id)
+    existing = manifest_path.is_file()
+    if existing:
+        manifest = _read_json(manifest_path)
+        _merge_manifest(
+            manifest,
+            {
+                "objective": objective,
+                "commonBriefPath": common_brief_path,
+                "progressMode": progress_mode,
+            },
+        )
+    else:
+        manifest = {
+            "managerId": manager_id,
+            "taskGroup": task_group,
+            "taskId": task_id,
+            "progressMode": progress_mode or "manual",
+            "commonBriefPath": common_brief_path,
+            "objective": objective,
+            "createdAt": when,
+        }
+    children = _load_children(home, manager_id, task_group, task_id)
+    known_keys = {child.get("taskKey") for child in children["children"] if isinstance(child, dict)}
+    added = []
     for spec in child_specs:
         project_id = str(spec.get("projectId") or "")
         child_task_id = str(spec.get("taskId") or task_id)
         if _project_entry(projects, project_id) is None:
             raise ManagerError(f"unknown project membership: {project_id}")
-        children.append(
+        task_key = _child_task_key(project_id, task_group, child_task_id)
+        if task_key in known_keys:
+            continue
+        known_keys.add(task_key)
+        added.append(
             {
                 "projectId": project_id,
                 "taskGroup": task_group,
                 "taskId": child_task_id,
-                "taskKey": f"{project_id}:{task_group}:{child_task_id}",
+                "taskKey": task_key,
                 "role": "",
                 "tags": [],
                 "assignment": "",
@@ -219,14 +326,20 @@ def create_task(
                 },
             }
         )
-    payload = {"manifest": manifest, "children": {"children": children}}
-    _write_json(task_manifest_path(home, manager_id, task_group, task_id), manifest)
-    _write_json(children_json_path(home, manager_id, task_group, task_id), payload["children"])
+    children["children"].extend(added)
+    if not existing:
+        _ensure_group_meta(home, manager_id, task_group, when)
+        _write_json(manifest_path, manifest)
+    _write_json(children_json_path(home, manager_id, task_group, task_id), children)
     append_jsonl(
         events_jsonl_path(home, manager_id, task_group, task_id),
-        {"event": "task-created", "createdAt": when},
+        {
+            "event": "task-children-added" if existing else "task-created",
+            "createdAt": when,
+            "taskKeys": [child["taskKey"] for child in added],
+        },
     )
-    return payload
+    return {"manifest": manifest, "children": children}
 
 
 def _load_children(home: Path, manager_id: str, task_group: str, task_id: str) -> dict:
@@ -286,6 +399,7 @@ def assign_child(
     assignment: str,
     child_task_id: str | None = None,
 ) -> dict:
+    _read_json(task_manifest_path(home, manager_id, task_group, task_id))
     payload = _load_children(home, manager_id, task_group, task_id)
     child = _select_child_for_assignment(payload["children"], project_id, task_group, child_task_id)
     child["role"] = role
@@ -311,6 +425,11 @@ def append_directive(
         raise ManagerError("scope must be shared or project")
     if scope == "project" and not project_id:
         raise ManagerError("project directive requires project-id")
+    _read_json(task_manifest_path(home, manager_id, task_group, task_id))
+    if scope == "project":
+        children = _load_children(home, manager_id, task_group, task_id)["children"]
+        if not any(isinstance(child, dict) and child.get("projectId") == project_id for child in children):
+            raise ManagerError(f"project directive target has no child in this task: {project_id}")
     row = {
         "scope": scope,
         "projectId": project_id if scope == "project" else "",
@@ -320,3 +439,194 @@ def append_directive(
     }
     append_jsonl(directives_jsonl_path(home, manager_id, task_group, task_id), row)
     return row
+
+
+def list_task_groups(home: Path, manager_id: str) -> list[dict]:
+    """태스크가 없는 그룹까지 포함해 그룹을 이름 순으로 돌려준다.
+
+    `group.json` 이 없는 기존 그룹은 소속 태스크 manifest 의 그룹 이름을, 태스크도 없으면
+    폴더 이름을 쓴다.
+    """
+    load_manager(home, manager_id)
+    base = task_groups_root(home, manager_id)
+    if not base.is_dir():
+        return []
+    items: list[dict] = []
+    for group_dir in sorted(path for path in base.iterdir() if path.is_dir()):
+        manifests = sorted(group_dir.glob("*/manifest.json"))
+        meta_path = group_dir / "group.json"
+        meta = _read_json(meta_path) if meta_path.is_file() else {}
+        name = str(meta.get("taskGroup") or "")
+        if not name and manifests:
+            name = str(_read_json(manifests[0]).get("taskGroup") or "")
+        items.append(
+            {
+                "taskGroup": name or group_dir.name,
+                "createdAt": str(meta.get("createdAt") or ""),
+                "taskCount": len(manifests),
+            }
+        )
+    return sorted(items, key=lambda item: item["taskGroup"])
+
+
+def _children_of_project(home: Path, manager_id: str, project_id: str) -> list[tuple[dict, list[str]]]:
+    """(task manifest, 그 task 에서 project_id 를 가리키는 하위 태스크 키) 목록."""
+    rows = []
+    for path in _task_manifest_paths(home, manager_id):
+        children = _read_json_default(path.parent / "children.json", {"children": []})
+        keys = [
+            str(child.get("taskKey"))
+            for child in children.get("children", [])
+            if isinstance(child, dict) and child.get("projectId") == project_id
+        ]
+        if keys:
+            rows.append((_read_json(path), keys))
+    return rows
+
+
+def unlink_project(
+    home: Path, manager_id: str, project_id: str, *, confirm: bool, now: str | None = None
+) -> dict:
+    """프로젝트 등록을 해제한다. 하위 태스크는 남기고, 등록 목록에 없다는 사실로 해제 상태를 표시한다.
+
+    `confirm` 이 거짓이면 대상만 돌려주고 아무것도 바꾸지 않는다.
+    """
+    load_manager(home, manager_id)
+    payload = _load_projects(home, manager_id)
+    entry = _project_entry(payload, project_id)
+    if entry is None:
+        raise ManagerError(f"unknown project membership: {project_id}")
+    affected = _children_of_project(home, manager_id, project_id)
+    result = {
+        "managerId": manager_id,
+        "projectId": project_id,
+        "projectRoot": str(entry.get("projectRoot") or ""),
+        "keptChildren": [key for _, keys in affected for key in keys],
+        "removed": confirm,
+    }
+    if not confirm:
+        return result
+    payload["projects"] = [item for item in payload["projects"] if item is not entry]
+    _write_json(projects_json_path(home, manager_id), payload)
+    when = now or _now_iso()
+    for manifest, keys in affected:
+        append_jsonl(
+            events_jsonl_path(home, manager_id, str(manifest["taskGroup"]), str(manifest["taskId"])),
+            {"event": "project-unlinked", "createdAt": when, "projectId": project_id, "taskKeys": keys},
+        )
+    return result
+
+
+def remove_child(
+    home: Path,
+    manager_id: str,
+    task_group: str,
+    task_id: str,
+    project_id: str,
+    *,
+    child_task_id: str | None = None,
+    confirm: bool,
+    now: str | None = None,
+) -> dict:
+    """하위 태스크 하나를 manager 에서 뺀다. 프로젝트의 `.okstra/` 는 건드리지 않는다."""
+    _read_json(task_manifest_path(home, manager_id, task_group, task_id))
+    payload = _load_children(home, manager_id, task_group, task_id)
+    child = _select_child_for_assignment(payload["children"], project_id, task_group, child_task_id)
+    task_key = str(child.get("taskKey") or "")
+    result = {"managerId": manager_id, "taskGroup": task_group, "taskId": task_id,
+              "taskKey": task_key, "removed": confirm}
+    if not confirm:
+        return result
+    payload["children"] = [item for item in payload["children"] if item is not child]
+    _write_json(children_json_path(home, manager_id, task_group, task_id), payload)
+    # 남은 형제의 context 에 지운 하위 태스크가 형제로 실리지 않게 스냅샷 행도 뺀다.
+    snapshot_path = snapshots_json_path(home, manager_id, task_group, task_id)
+    if snapshot_path.is_file():
+        snapshot = _read_json(snapshot_path)
+        snapshot["children"] = [
+            row for row in snapshot.get("children", []) if not isinstance(row, dict) or row.get("taskKey") != task_key
+        ]
+        _write_json(snapshot_path, snapshot)
+    child_context_path(
+        home, manager_id, task_group, task_id, project_id, str(child.get("taskId") or task_id)
+    ).unlink(missing_ok=True)
+    append_jsonl(
+        events_jsonl_path(home, manager_id, task_group, task_id),
+        {"event": "task-child-removed", "createdAt": now or _now_iso(), "taskKey": task_key},
+    )
+    return result
+
+
+def update_task(
+    home: Path,
+    manager_id: str,
+    task_group: str,
+    task_id: str,
+    *,
+    objective: str | None = None,
+    common_brief_path: str | None = None,
+    progress_mode: str | None = None,
+    now: str | None = None,
+) -> dict:
+    """manager task 의 objective·공통 브리프·진행 방식 중 넘긴 값만 바꾼다."""
+    manifest_path = task_manifest_path(home, manager_id, task_group, task_id)
+    manifest = _read_json(manifest_path)
+    requested = {"objective": objective, "commonBriefPath": common_brief_path, "progressMode": progress_mode}
+    requested = {key: value for key, value in requested.items() if value is not None}
+    if not requested:
+        raise ManagerError("task update needs at least one of --objective, --common-brief, --progress-mode")
+    if requested.get("progressMode") not in (None, "manual", "auto"):
+        raise ManagerError("progress-mode must be manual or auto")
+    changes = {
+        key: {"from": manifest.get(key), "to": value}
+        for key, value in requested.items()
+        if manifest.get(key) != value
+    }
+    for key, change in changes.items():
+        manifest[key] = change["to"]
+    if changes:
+        _write_json(manifest_path, manifest)
+        append_jsonl(
+            events_jsonl_path(home, manager_id, task_group, task_id),
+            {"event": "task-updated", "createdAt": now or _now_iso(), "changes": changes},
+        )
+    return {"manifest": manifest, "changedFields": sorted(changes)}
+
+
+def remove_task(
+    home: Path, manager_id: str, task_group: str, task_id: str, *, confirm: bool
+) -> dict:
+    """manager task 폴더를 지운다. 하위 프로젝트의 태스크와 브리프는 남는다."""
+    manifest = _read_json(task_manifest_path(home, manager_id, task_group, task_id))
+    root = task_manifest_path(home, manager_id, task_group, task_id).parent
+    children = _load_children(home, manager_id, task_group, task_id)["children"]
+    result = {
+        "managerId": manager_id,
+        "taskGroup": str(manifest.get("taskGroup") or task_group),
+        "taskId": str(manifest.get("taskId") or task_id),
+        "path": str(root),
+        "childCount": len(children),
+        "removed": confirm,
+    }
+    if confirm:
+        shutil.rmtree(root)
+    return result
+
+
+def remove_task_group(home: Path, manager_id: str, task_group: str, *, confirm: bool) -> dict:
+    """그룹 폴더와 그 안의 manager task 전부를 지운다."""
+    load_manager(home, manager_id)
+    root = task_group_root(home, manager_id, task_group)
+    if not root.is_dir():
+        raise ManagerError(f"unknown task group: {task_group}")
+    task_ids = [str(_read_json(path).get("taskId") or path.parent.name) for path in sorted(root.glob("*/manifest.json"))]
+    result = {
+        "managerId": manager_id,
+        "taskGroup": task_group,
+        "path": str(root),
+        "taskIds": task_ids,
+        "removed": confirm,
+    }
+    if confirm:
+        shutil.rmtree(root)
+    return result

package/runtime/python/okstra_ctl/manager_sync.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from okstra_project import TASKS_RELATIVE, StateError, parse_task_key, read_task_catalog, read_task_manifest, slugify
 
 from . import next_phase
+from .next_phase import STATUS_BLOCKED, STATUS_TERMINAL
 from .manager_paths import children_json_path, projects_json_path, snapshots_json_path, task_manifest_path
 from .manager_store import _now_iso, _read_json, _read_json_default, _write_json
 
@@ -89,6 +90,7 @@ def _snapshot_child(project_root: Path, child: dict) -> dict:
             workflow.get("nextRecommendedPhase")
         ),
         "latestRunStatus": str(manifest.get("latestRunStatus") or manifest.get("currentStatus") or ""),
+        "workStatus": str(manifest.get("workStatus") or ""),
         "latestReportRecordPath": str(manifest.get("latestReportRecordPath") or ""),
         "finalVerdict": str(outcome.get("finalVerdict") or ""),
         "crossProjectDependencies": _list_field(outcome, "crossProjectDependencies"),
@@ -107,7 +109,7 @@ def sync_task(home: Path, manager_id: str, task_group: str, task_id: str, *, now
             continue
         project = projects.get(str(child.get("projectId") or ""))
         if project is None:
-            rows.append({**child, "exists": False, "error": "unknown project membership"})
+            rows.append({**child, "exists": False, "error": "project unlinked from this manager; re-register it with `okstra manager new project`"})
             continue
         root = Path(str(project.get("projectRoot") or ""))
         if not root.is_dir():
@@ -125,31 +127,50 @@ def sync_task(home: Path, manager_id: str, task_group: str, task_id: str, *, now
     return payload
 
 
+# 사용자가 `okstra set-work-status` 로 적은 값이 파생 포인터보다 우선한다.
+# 그룹 큐(group_context.catalog_progress)와 같은 순서다. `latestRunStatus` 는
+# phase 한 번의 실행 결과(`completed` / `contract-violated` / `in-progress` …)라
+# task 가 끝났는지 말해 주지 않으므로 요약 분류에 쓰지 않는다.
+_WORK_STATUS_BUCKETS = {
+    "done": "done",
+    "blocked": "blocked",
+    "in-progress": "running",
+    "todo": "planned",
+}
+_POINTER_STATUS_BUCKETS = {
+    STATUS_TERMINAL: "done",
+    STATUS_BLOCKED: "blocked",
+}
+
+
+def summary_bucket(row: dict) -> str:
+    """스냅샷이 있는 하위 task 한 줄을 요약 칸 하나로 분류한다."""
+    if not row.get("exists", False):
+        return "missing"
+    work_status = str(row.get("workStatus") or "")
+    if work_status in _WORK_STATUS_BUCKETS:
+        return _WORK_STATUS_BUCKETS[work_status]
+    pointer = row.get("nextRecommendedPhase")
+    pointer_status = pointer.get("status") if isinstance(pointer, dict) else ""
+    return _POINTER_STATUS_BUCKETS.get(pointer_status, "running")
+
+
 def status_task(home: Path, manager_id: str, task_group: str, task_id: str) -> dict:
     manifest = _read_json(task_manifest_path(home, manager_id, task_group, task_id))
     children = _read_json_default(children_json_path(home, manager_id, task_group, task_id), {"children": []})
     snapshot = _read_json_default(snapshots_json_path(home, manager_id, task_group, task_id), {"children": []})
     by_key = {row.get("taskKey"): row for row in snapshot.get("children", []) if isinstance(row, dict)}
+    linked = _project_map(home, manager_id)
     rows = []
     summary = {"planned": 0, "missing": 0, "running": 0, "done": 0, "blocked": 0}
     for child in children.get("children", []):
         if not isinstance(child, dict):
             continue
-        key = child.get("taskKey")
-        snapshot_row = by_key.get(key)
+        snapshot_row = by_key.get(child.get("taskKey"))
         row = {**child, **(snapshot_row or {})}
-        status = str(row.get("latestRunStatus") or row.get("launch", {}).get("status") or "planned")
-        if snapshot_row is None:
-            summary["planned"] += 1
-        elif not row.get("exists", False):
-            summary["missing"] += 1
-        elif status == "done":
-            summary["done"] += 1
-        elif status in {"running", "started", "in-progress"}:
-            summary["running"] += 1
-        elif status == "blocked":
-            summary["blocked"] += 1
-        else:
-            summary["planned"] += 1
+        row["summaryBucket"] = "planned" if snapshot_row is None else summary_bucket(row)
+        # `remove project` 는 하위 태스크를 남긴다. 등록 목록에 없으면 해제된 프로젝트의 것이다.
+        row["projectLinked"] = str(child.get("projectId") or "") in linked
+        summary[row["summaryBucket"]] += 1
         rows.append(row)
     return {"manifest": manifest, "summary": summary, "children": rows, "lastSnapshot": snapshot}