okstra 0.180.0 → 0.183.2

package/runtime/python/okstra_ctl/manager_cli.py

@@ -10,6 +10,7 @@ from pathlib import Path
 from okstra_project.dirs import okstra_home
 
 from .manager_launch import build_launch_packet
+from .fixed_text import line, value_lines
 from .manager_store import (
     ManagerError,
     append_directive,
@@ -23,11 +24,90 @@ from .manager_store import (
 from .manager_sync import status_task, sync_task
 
 
-def _emit(payload: dict | list[dict], as_json: bool) -> None:
+def render_manager_text(command: str, payload: dict | list[dict]) -> str:
+    """manager 모델 표면에 승인된 식별자와 상태만 투영한다."""
+    allowed = {"init", "discover-projects", "new-project", "new-task-group", "new-task",
+               "task-assign", "task-note", "task-sync", "task-status", "task-run"}
+    if command not in allowed:
+        raise ValueError("unknown manager text purpose")
+    rows = [f"Okstra manager {command}\n", line("Status", "ready")]
+    if isinstance(payload, list):
+        rows.append(line("Result count", len(payload)))
+        rows.extend(_render_manager_projects(payload))
+        return "".join(rows)
+    if command == "task-status":
+        rows.extend(_render_manager_status(payload))
+        rows.extend(value_lines("Status details", payload))
+        return "".join(rows)
+    for label, key in (("Manager ID", "managerId"), ("Schema version", "schemaVersion"),
+                       ("Task key", "taskKey"), ("Project ID", "projectId"),
+                       ("Task group", "taskGroup"), ("Task ID", "taskId"),
+                       ("Work status", "workStatus"), ("Run command", "command"),
+                       ("Backend", "backend"),
+                       ("Worker dispatch backend", "workerDispatchBackend"),
+                       ("Project root", "projectRoot"), ("Context path", "contextPath")):
+        if key in payload:
+            rows.append(line(label, payload.get(key)))
+    run_args = payload.get("runArgs")
+    if isinstance(run_args, list):
+        for index, value in enumerate(run_args, 1):
+            rows.append(line(f"Run arg {index}", value))
+    structures = {
+        "new-project": (("Projects", "projects"),),
+        "new-task": (("Manifest", "manifest"), ("Children", "children")),
+        "task-assign": (("Children", "children"),),
+        "task-sync": (("Children", "children"),),
+    }
+    for label, key in structures.get(command, ()):
+        rows.extend(value_lines(label, payload.get(key)))
+    if command == "task-note":
+        for label, key in (("Scope", "scope"), ("Directive project ID", "projectId"),
+                           ("Directive body", "body"), ("Created at", "createdAt"),
+                           ("Source", "source")):
+            rows.append(line(label, payload.get(key)))
+    if command == "task-sync" and "syncedAt" in payload:
+        rows.append(line("Synced at", payload.get("syncedAt")))
+    return "".join(rows)
+
+
+def _render_manager_projects(projects: list[dict]) -> list[str]:
+    rows: list[str] = []
+    for index, project in enumerate(projects, 1):
+        if not isinstance(project, dict):
+            continue
+        for label, key in (("ID", "projectId"), ("root", "projectRoot"),
+                           ("run count", "runCount"), ("active count", "activeCount"),
+                           ("last run at", "lastRunAt")):
+            rows.append(line(f"Project {index} {label}", project.get(key)))
+    return rows
+
+
+def _render_manager_status(payload: dict) -> list[str]:
+    rows: list[str] = []
+    manifest = payload.get("manifest") if isinstance(payload.get("manifest"), dict) else {}
+    for label, key in (("Manager ID", "managerId"), ("Task group", "taskGroup"),
+                       ("Task ID", "taskId"), ("Progress mode", "progressMode")):
+        rows.append(line(label, manifest.get(key)))
+    summary = payload.get("summary") if isinstance(payload.get("summary"), dict) else {}
+    for key in ("planned", "missing", "running", "done", "blocked"):
+        rows.append(line(f"Summary {key}", summary.get(key)))
+    children = payload.get("children") if isinstance(payload.get("children"), list) else []
+    for index, child in enumerate(children, 1):
+        if not isinstance(child, dict):
+            continue
+        for label, key in (("task key", "taskKey"), ("run status", "latestRunStatus"),
+                           ("current phase", "currentPhase"), ("work status", "workStatus"),
+                           ("report path", "latestReportRecordPath"), ("error", "error")):
+            if key in child:
+                rows.append(line(f"Child {index} {label}", child.get(key)))
+    return rows
+
+
+def _emit(command: str, payload: dict | list[dict], as_json: bool) -> None:
     if as_json:
         print(json.dumps(payload, ensure_ascii=False, indent=2))
         return
-    print(json.dumps(payload, ensure_ascii=False))
+    print(render_manager_text(command, payload), end="")
 
 
 def _normalize_global_flags(argv: list[str] | None) -> list[str]:
@@ -142,11 +222,12 @@ def main(argv: list[str] | None = None) -> int:
     home = okstra_home()
     try:
         if args.command == "init":
-            _emit(init_manager(home, args.manager_id), args.json)
+            _emit("init", init_manager(home, args.manager_id), args.json)
         elif args.command == "discover-projects":
-            _emit(discover_projects(home), args.json)
+            _emit("discover-projects", discover_projects(home), args.json)
         elif args.command == "new" and args.new_command == "project":
             _emit(
+                "new-project",
                 link_project(
                     home,
                     args.manager_id,
@@ -158,9 +239,10 @@ def main(argv: list[str] | None = None) -> int:
                 args.json,
             )
         elif args.command == "new" and args.new_command == "task-group":
-            _emit(create_task_group(home, args.manager_id, args.task_group), args.json)
+            _emit("new-task-group", create_task_group(home, args.manager_id, args.task_group), args.json)
         elif args.command == "new" and args.new_command == "task":
             _emit(
+                "new-task",
                 create_task(
                     home,
                     args.manager_id,
@@ -175,6 +257,7 @@ def main(argv: list[str] | None = None) -> int:
             )
         elif args.command == "task" and args.task_command == "assign":
             _emit(
+                "task-assign",
                 assign_child(
                     home,
                     args.manager_id,
@@ -190,6 +273,7 @@ def main(argv: list[str] | None = None) -> int:
             )
         elif args.command == "task" and args.task_command == "note":
             _emit(
+                "task-note",
                 append_directive(
                     home,
                     args.manager_id,
@@ -202,11 +286,12 @@ def main(argv: list[str] | None = None) -> int:
                 args.json,
             )
         elif args.command == "task" and args.task_command == "sync":
-            _emit(sync_task(home, args.manager_id, args.task_group, args.task_id), args.json)
+            _emit("task-sync", sync_task(home, args.manager_id, args.task_group, args.task_id), args.json)
         elif args.command == "task" and args.task_command == "status":
-            _emit(status_task(home, args.manager_id, args.task_group, args.task_id), args.json)
+            _emit("task-status", status_task(home, args.manager_id, args.task_group, args.task_id), args.json)
         elif args.command == "task" and args.task_command == "run":
             _emit(
+                "task-run",
                 build_launch_packet(
                     home,
                     args.manager_id,

package/runtime/python/okstra_ctl/manager_store.py

@@ -9,6 +9,11 @@ from pathlib import Path
 from okstra_project import project_json_path, upsert_project_json
 
 from okstra_ctl.jsonl import append_jsonl
+from okstra_ctl.json_boundary import (
+    JsonBoundaryError,
+    load_owned_object,
+    write_owned_object_atomic,
+)
 
 from .manager_paths import (
     ManagerPathError,
@@ -32,18 +37,15 @@ def _now_iso() -> str:
 
 
 def _write_json(path: Path, payload: dict) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    tmp = path.with_suffix(path.suffix + ".tmp")
-    tmp.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    os.replace(tmp, path)
+    write_owned_object_atomic(path, payload, artifact="manager state")
 
 
 def _read_json(path: Path) -> dict:
     if not path.is_file():
         raise ManagerError(f"manager file not found: {path}")
     try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
+        data = load_owned_object(path, artifact="manager state")
+    except JsonBoundaryError as exc:
         raise ManagerError(f"failed to parse {path}: {exc}") from exc
     if not isinstance(data, dict):
         raise ManagerError(f"expected JSON object in {path}")
@@ -101,8 +103,8 @@ def discover_projects(home: Path) -> list[dict]:
     items: list[dict] = []
     for meta in sorted(base.glob("*/meta.json")):
         try:
-            data = json.loads(meta.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError):
+            data = load_owned_object(meta, artifact="project metadata")
+        except JsonBoundaryError:
             continue
         if isinstance(data, dict):
             items.append(
@@ -134,8 +136,8 @@ def link_project(
     project_json = project_json_path(root)
     if project_json.is_file():
         try:
-            existing = json.loads(project_json.read_text(encoding="utf-8"))
-        except json.JSONDecodeError as exc:
+            existing = load_owned_object(project_json, artifact="project metadata")
+        except JsonBoundaryError as exc:
             raise ManagerError(f"failed to parse {project_json}: {exc}") from exc
         existing_id = str(existing.get("projectId") or "")
         if existing_id != project_id:

package/runtime/python/okstra_ctl/material.py

@@ -11,6 +11,8 @@ import json
 from pathlib import Path
 from typing import Optional
 
+from .json_boundary import load_owned_object
+
 
 def build_analysis_material(brief_path: Path, directive: str = "") -> str:
     """`analysis-material.md` 본문 문자열을 돌려준다."""
@@ -35,7 +37,9 @@ def resolve_related_tasks(
     existing: list[str] = []
     if task_manifest_path and Path(task_manifest_path).exists():
         try:
-            manifest = json.loads(Path(task_manifest_path).read_text(encoding="utf-8"))
+            manifest = load_owned_object(
+                Path(task_manifest_path), artifact="task manifest"
+            )
             existing = manifest.get("relatedTasks") or []
             if not isinstance(existing, list):
                 existing = []

package/runtime/python/okstra_ctl/migrate.py

@@ -24,6 +24,11 @@ from pathlib import Path
 from typing import Optional
 
 from okstra_ctl.worktree import is_git_work_tree
+from okstra_ctl.json_boundary import (
+    JsonBoundaryError,
+    load_owned_object,
+    write_owned_object_atomic,
+)
 # 모듈 import 인 이유: 이 파일의 공개 함수들이 `okstra_home` 이라는 파라미터
 # 이름을 쓰고 있어, 같은 이름의 함수를 직접 import 하면 가려진다.
 from okstra_project import dirs as project_dirs
@@ -305,9 +310,10 @@ def _scan_registries(project_root: Path, *, okstra_home: Path) -> list[dict]:
     registry = okstra_home / "worktrees" / "registry.json"
     if registry.is_file():
         try:
-            text = registry.read_text(encoding="utf-8")
-        except OSError:
-            text = ""
+            data = load_owned_object(registry, artifact="worktree registry")
+        except JsonBoundaryError:
+            data = {}
+        text = json.dumps(data, ensure_ascii=False)
         if LEGACY_OKSTRA_DIR_NAME in text and _mentions_project_path(text, project_str):
             updates.append({"file": str(registry), "rowCount": text.count(LEGACY_OKSTRA_DIR_NAME), "scope": "worktrees-registry"})
     return updates
@@ -342,47 +348,45 @@ def _apply_registry_updates(plan: MigrationPlan, *, okstra_home: Path) -> int:
     registry = okstra_home / "worktrees" / "registry.json"
     if registry.is_file():
         try:
-            text = registry.read_text(encoding="utf-8")
-        except OSError:
-            text = ""
+            data = load_owned_object(registry, artifact="worktree registry")
+        except JsonBoundaryError:
+            data = {}
         # Only mutate when this project's root appears anywhere in the file —
         # otherwise leave it alone (covers the case where registry.json
         # contains an unrelated `.project-docs/okstra` literal in someone
         # else's row).
+        text = json.dumps(data, ensure_ascii=False)
         if _mentions_project_path(text, project_str) and LEGACY_OKSTRA_DIR_NAME in text:
-            new_text = _replace_in_project_rows(text, project_str)
-            if new_text != text:
-                registry.write_text(new_text, encoding="utf-8")
-                total += text.count(LEGACY_OKSTRA_DIR_NAME) - new_text.count(
-                    LEGACY_OKSTRA_DIR_NAME
+            updated, changed = _replace_in_project_rows(data, project_str)
+            if changed:
+                write_owned_object_atomic(
+                    registry, updated, artifact="worktree registry"
                 )
+                total += changed
     return total
 
 
-def _replace_in_project_rows(text: str, project_str: str) -> str:
+def _replace_in_project_rows(
+    data: dict[str, object], project_str: str
+) -> tuple[dict[str, object], int]:
     """For registry.json: replace `.project-docs/okstra` with `.okstra` only
     inside rows that mention `project_str`. registry.json is structured JSON
     (top-level object with task-key → row), so we operate at the JSON level
     to avoid clobbering unrelated rows.
     """
-    try:
-        data = json.loads(text)
-    except json.JSONDecodeError:
-        return text
-    if not isinstance(data, dict):
-        return text
-    changed = False
+    updated = dict(data)
+    changed = 0
     for key, row in data.items():
-        row_text = json.dumps(row)
+        row_text = json.dumps(row, ensure_ascii=False)
         if not _mentions_project_path(row_text, project_str) or LEGACY_OKSTRA_DIR_NAME not in row_text:
             continue
         new_row_text = row_text.replace(LEGACY_OKSTRA_DIR_NAME, OKSTRA_DIR_NAME)
         if new_row_text != row_text:
-            data[key] = json.loads(new_row_text)
-            changed = True
-    if not changed:
-        return text
-    return json.dumps(data, indent=2, ensure_ascii=False) + "\n"
+            updated[key] = json.loads(new_row_text)
+            changed += row_text.count(LEGACY_OKSTRA_DIR_NAME) - new_row_text.count(
+                LEGACY_OKSTRA_DIR_NAME
+            )
+    return updated, changed
 
 
 def main(argv: Optional[list[str]] = None) -> int:

package/runtime/python/okstra_ctl/model_cli.py

@@ -17,6 +17,7 @@ from .model_pool import ModelPool, ModelPoolValidationError
 from .ports.host_model import HostModelBindingError, HostModelBindingRequest
 from .registry.host_registry import default_host_registry
 from .registry.provider_registry import default_provider_registry
+from .json_boundary import load_owned_object, write_owned_object_atomic
 
 
 class ModelCliError(ValueError):
@@ -226,24 +227,11 @@ def _config_path(scope: str, cwd: Path) -> Path:
 def _read_json(path: Path) -> dict[str, Any]:
     if not path.is_file():
         return {}
-    payload = json.loads(path.read_text(encoding="utf-8"))
-    return payload if isinstance(payload, dict) else {}
+    return load_owned_object(path, artifact="model configuration")
 
 
 def _write_json_atomic(path: Path, payload: dict[str, Any]) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    handle = tempfile.NamedTemporaryFile(
-        "w", encoding="utf-8", delete=False, dir=path.parent
-    )
-    try:
-        json.dump(payload, handle, ensure_ascii=False, indent=2)
-        handle.write("\n")
-        handle.close()
-        os.replace(handle.name, path)
-    except Exception:
-        handle.close()
-        Path(handle.name).unlink(missing_ok=True)
-        raise
+    write_owned_object_atomic(path, payload, artifact="model configuration")
 
 
 def main(argv: list[str] | None = None) -> int: