okstra 0.179.2 → 0.183.2

package/runtime/python/okstra_ctl/listing.py

@@ -1,13 +1,13 @@
 """list/format/show."""
 from __future__ import annotations
 
-import json
 import re as _re
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import List, Optional
 
 from .paths import resolve_under_root
+from .json_boundary import JsonBoundaryError, load_owned_object
 from .reconcile import _parse_iso
 from .run_index_row import read_run_index
 
@@ -24,8 +24,8 @@ def list_projects(home: Path, *, only_active: bool = False,
         if not meta_file.is_file():
             continue
         try:
-            meta = json.loads(meta_file.read_text())
-        except (OSError, json.JSONDecodeError):
+            meta = load_owned_object(meta_file, artifact="project metadata")
+        except JsonBoundaryError:
             # 동시 쓰기/이전 크래시로 깨진 meta.json 하나가 전체 listing 을
             # 죽이지 않도록 해당 프로젝트만 건너뛴다(다른 JSON 리더와 동일 정책).
             continue

package/runtime/python/okstra_ctl/log_report.py

@@ -13,12 +13,18 @@ import json
 import sys
 from pathlib import Path
 
+from .fixed_text import line
+
 from okstra_project import resolve_project_root
+from okstra_ctl.json_boundary import load_owned_object
 
 
 def _project_id(project_root: Path) -> str:
     try:
-        return json.loads((project_root / ".okstra" / "project.json").read_text(encoding="utf-8")).get("projectId", "")
+        return load_owned_object(
+            project_root / ".okstra" / "project.json",
+            artifact="project configuration",
+        ).get("projectId", "")
     except (OSError, ValueError):
         return ""
 
@@ -120,6 +126,20 @@ def scan_logs(logs_root: Path, project_root: Path, top: int = 20) -> dict:
     }
 
 
+def render_result_text(result: dict) -> str:
+    parts = ["# Okstra Log Inventory\n\n", line("Project root", result.get("projectRoot")), line("Logs root", result.get("logsRoot"))]
+    totals = result.get("totals") if isinstance(result.get("totals"), dict) else {}
+    for key, label in (("fileCount", "File count"), ("totalBytes", "Total bytes"), ("taskCount", "Task count"), ("promptBytes", "Prompt bytes"), ("transcriptBytes", "Transcript bytes"), ("pairedFileCount", "Paired file count")):
+        parts.append(line(label, totals.get(key)))
+    for row in result.get("topLargest", []):
+        if isinstance(row, dict):
+            parts.extend(("\n## Log\n\n", line("Task key", row.get("taskKey")), line("Phase", row.get("phase")), line("Worker", row.get("worker")), line("Sequence", row.get("seq")), line("Size bytes", row.get("sizeBytes")), line("Modified epoch", row.get("mtimeEpoch")), line("Path", row.get("path"))))
+    for row in result.get("perTask", []):
+        if isinstance(row, dict):
+            parts.extend(("\n## Task total\n\n", line("Task key", row.get("taskKey")), line("File count", row.get("fileCount")), line("Total bytes", row.get("totalBytes")), line("Oldest epoch", row.get("oldestEpoch")), line("Newest epoch", row.get("newestEpoch"))))
+    return "".join(parts)
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="okstra log-report",
@@ -128,12 +148,14 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--cwd", default=".")
     parser.add_argument("--top", type=int, default=20, help="topLargest entry count")
     parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
+    parser.add_argument("--text", action="store_true", help="emit fixed text fields")
     args = parser.parse_args(argv)
 
     project_root = resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
     result = {"ok": True, "projectRoot": str(project_root)}
     result.update(scan_logs(project_root / ".okstra" / "tasks", project_root, top=args.top))
-    print(json.dumps(result, ensure_ascii=False, indent=2))
+    output = render_result_text(result) if args.text else json.dumps(result, ensure_ascii=False, indent=2)
+    print(output, end="" if args.text else "\n")
     return 0
 
 

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: