topview-3d-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{topview_3d_cli-0.1.0/topview_3d_cli.egg-info → topview_3d_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topview-3d-cli
-Version: 0.1.0
+Version: 0.1.2
 Summary: Build and render 3D director scenes locally with the topview-3d-cli command.
 License-Expression: Apache-2.0 AND CC-BY-4.0
 Project-URL: Homepage, https://www.topview.ai/topview-3d-builder
@@ -26,7 +26,7 @@ Dynamic: license-file
 # topview-3d-cli
 
 `topview-3d-cli` builds and renders 3D director scenes on your machine. Projects are plain files in a
-`.topview3d/` directory; rendering uses a local headless Chromium and makes no network requests.
+`.topview-3d/` directory; rendering uses a local headless Chromium and makes no network requests.
 
 Requirements: Python 3.11+ and Node.js 20.6+ (with npm).
 

{topview_3d_cli-0.1.0 → topview_3d_cli-0.1.2}/README.md

@@ -1,7 +1,7 @@
 # topview-3d-cli
 
 `topview-3d-cli` builds and renders 3D director scenes on your machine. Projects are plain files in a
-`.topview3d/` directory; rendering uses a local headless Chromium and makes no network requests.
+`.topview-3d/` directory; rendering uses a local headless Chromium and makes no network requests.
 
 Requirements: Python 3.11+ and Node.js 20.6+ (with npm).
 

{topview_3d_cli-0.1.0 → topview_3d_cli-0.1.2}/topview_3d_cli/__init__.py

@@ -1,3 +1,3 @@
 """Local, offline Scene3D director projects and the ``topview-3d-cli`` CLI."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

{topview_3d_cli-0.1.0 → topview_3d_cli-0.1.2}/topview_3d_cli/_runtime/director-cli/render.mjs

@@ -143,7 +143,7 @@ function publicAssetBase(body) {
 }
 
 // outputDir is `<absolute>/renders/<runId>`: the caller chooses the root (a project's
-// .topview3d/renders), the renderer writes exactly one run directory below it.
+// .topview-3d/renders), the renderer writes exactly one run directory below it.
 export function resolveOutputDir(outputDir, pathApi = path) {
   if (typeof outputDir !== 'string' || !outputDir.trim()) {
     throw new Error('RENDER_OUTPUT_DIR_REQUIRED')

{topview_3d_cli-0.1.0 → topview_3d_cli-0.1.2}/topview_3d_cli/bom.py

@@ -1,7 +1,7 @@
 """Plan / constraint record (BOM): intent, relationships, constraints, camera roles, model review.
 
 Pure merge and evidence logic behind the ``topview-3d-cli bom`` and ``inspect views`` commands (stored as
-``.topview3d/bom.json``). ``checkpoint`` fields are model-owned; the
+``.topview-3d/bom.json``). ``checkpoint`` fields are model-owned; the
 runtime owns ``observed`` and ``verification``. Errors are ``ValueError("<CODE>: ...")``.
 """
 from __future__ import annotations

{topview_3d_cli-0.1.0 → topview_3d_cli-0.1.2}/topview_3d_cli/local_bom.py

@@ -1,4 +1,4 @@
-"""``.topview3d/bom.json``: the plan / constraint record kept next to the director document."""
+"""``.topview-3d/bom.json``: the plan / constraint record kept next to the director document."""
 from __future__ import annotations
 
 import json

{topview_3d_cli-0.1.0 → topview_3d_cli-0.1.2}/topview_3d_cli/local_cli.py

@@ -22,6 +22,7 @@ from topview_3d_cli.local_errors import EXIT_INVALID_INPUT, EXIT_OK, exit_code_f
 from topview_3d_cli.local_project import (
     CLI_VERSION,
     LocalProjectError,
+    adopt_edit,
     apply_operations,
     init_project,
     open_project,
@@ -31,6 +32,7 @@ from topview_3d_cli.local_project import (
 from topview_3d_cli.local_inspect import evaluate, inspect_nodes, inspect_views, parse_frames
 from topview_3d_cli.local_read import camera_presets, document_view, renders_list, renders_show
 from topview_3d_cli.local_render import render
+from topview_3d_cli.local_studio import open_studio
 from topview_3d_cli.renderer import node_path
 from topview_3d_cli.runtime import PLAYWRIGHT_VERSION, builder_version, node_env, runtime
 
@@ -261,6 +263,9 @@ def _parser() -> argparse.ArgumentParser:
     init.add_argument("directory")
     init.add_argument("--force", action="store_true", help="replace an existing project")
     project.add_parser("status").add_argument("directory")
+    adopt = project.add_parser("adopt", help="write a Studio edit back into the project so later commands continue from it")
+    adopt.add_argument("directory")
+    adopt.add_argument("payload", help="{\"document\"?, \"fcurves\"?} JSON file, or - for stdin")
 
     document = group("document", "read, validate and edit the director document")
     get = document.add_parser("get", help="the stored document; --summary or --entity for smaller reads")
@@ -317,7 +322,7 @@ def _parser() -> argparse.ArgumentParser:
     camera = group("camera", "camera helpers")
     camera.add_parser("presets", help="camera preset ids for add_camera")
 
-    bom = group("bom", "plan / constraint record (.topview3d/bom.json)")
+    bom = group("bom", "plan / constraint record (.topview-3d/bom.json)")
     bom.add_parser("get").add_argument("directory")
     checkpoint = bom.add_parser("checkpoint", help="merge a checkpoint patch (compare-and-set)")
     checkpoint.add_argument("directory")
@@ -329,7 +334,7 @@ def _parser() -> argparse.ArgumentParser:
     listing.add_argument("--kind", choices=KINDS)
     search = asset.add_parser("search", help="keyword search with filters and facets")
     search.add_argument("query", nargs="?", default="")
-    search.add_argument("--project", dest="directory", help="also search <project>/.topview3d/assets")
+    search.add_argument("--project", dest="directory", help="also search <project>/.topview-3d/assets")
     search.add_argument("--kind", choices=KINDS)
     search.add_argument("--category")
     search.add_argument("--tag", action="append", help="required tag (repeatable)")
@@ -342,7 +347,7 @@ def _parser() -> argparse.ArgumentParser:
     show_asset.add_argument("--kind", choices=KINDS)
     importing = asset.add_parser("import", help="copy a model or pose file into an asset root")
     target = importing.add_mutually_exclusive_group(required=True)
-    target.add_argument("--project", dest="directory", help="import into <project>/.topview3d/assets")
+    target.add_argument("--project", dest="directory", help="import into <project>/.topview-3d/assets")
     target.add_argument("--builtin", action="store_true", help="import into the built-in asset root")
     importing.add_argument("file")
     importing.add_argument("--kind", required=True, choices=("character", "prop", "pose"))
@@ -376,6 +381,8 @@ def _parser() -> argparse.ArgumentParser:
     browser = group("browser", "renderer browser setup")
     ensure = browser.add_parser("ensure", help="install the pinned Playwright and Chromium (idempotent)")
     ensure.add_argument("--with-deps", action="store_true", help="also install Linux system packages (sudo)")
+    studio = group("studio", "open the local Studio app on this project")
+    studio.add_parser("open", help="start Studio with Node if needed and open this project in the browser").add_argument("directory")
     return parser
 
 
@@ -405,8 +412,14 @@ def _dispatch(args: argparse.Namespace) -> dict[str, Any]:
         return doctor()
     if command == "browser":
         return browser_ensure(with_deps=args.with_deps)
+    if command == "studio":
+        return open_studio(args.directory)
     if command == "project":
-        return init_project(args.directory, force=args.force) if sub == "init" else project_status(args.directory)
+        if sub == "init":
+            return init_project(args.directory, force=args.force)
+        if sub == "adopt":
+            return adopt_edit(args.directory, load_spec(args.payload, "PROJECT_ADOPT_INVALID"))
+        return project_status(args.directory)
     if command == "document":
         if sub == "get":
             return document_view(args.directory, summary=args.summary, entity=args.entity,

{topview_3d_cli-0.1.0 → topview_3d_cli-0.1.2}/topview_3d_cli/local_errors.py

@@ -14,8 +14,9 @@ EXIT_INVALID_INPUT = 2
 ERROR_CODES: dict[str, tuple[int, str]] = {
     # Command line and input files
     "USAGE_INVALID": (2, "Unknown command, missing argument or bad option."),
-    "PROJECT_NOT_INITIALIZED": (2, "The directory has no .topview3d project; run `project init`."),
+    "PROJECT_NOT_INITIALIZED": (2, "The directory has no .topview-3d project; run `project init`."),
     "PROJECT_EXISTS": (2, "`project init` target already contains a project; pass --force to replace it."),
+    "PROJECT_ADOPT_INVALID": (2, "`project adopt` body must be a JSON object with document and/or fcurves."),
     "OPERATIONS_NOT_FOUND": (2, "The operations file does not exist."),
     "OPERATIONS_JSON_INVALID": (2, "The operations file is not JSON or not an operation batch."),
     "RENDER_PAYLOAD_INVALID": (2, "The render payload is not a JSON object of frames/width/height/cameraNodeId/publicAssetBase."),
@@ -34,7 +35,7 @@ ERROR_CODES: dict[str, tuple[int, str]] = {
     "ENTITY_NOT_FOUND": (2, "Delete targets an entity that never existed."),
     "DIRECTOR_NODE_NOT_FOUND": (2, "A referenced node does not exist (the message names it; batches add details.index)."),
     "DOCUMENT_ENTITY_NOT_FOUND": (2, "`document get --entity` found no node, clip or fcurves shard with that id."),
-    "RENDER_NOT_FOUND": (2, "No such render run or frame image in .topview3d/renders."),
+    "RENDER_NOT_FOUND": (2, "No such render run or frame image in .topview-3d/renders."),
     "BOM_CHECKPOINT_INVALID": (2, "`bom checkpoint` patch fails its schema or repeats/conflicts ids."),
     "BOM_TOO_LARGE": (2, "The merged BOM would exceed 64 KiB."),
     # Operation shape (nothing is applied)
@@ -72,7 +73,7 @@ ERROR_CODES: dict[str, tuple[int, str]] = {
     "BUILDER_PACKAGE_UNREADABLE": (1, "editor/packages/builder/package.json is missing or has no version."),
     "ASSET_MANIFEST_INVALID": (1, "An asset manifest is corrupt or lists a path outside its root."),
     "POSE_ASSET_INVALID": (1, "A pose file is larger than 1 MiB or lacks hips and 1-256 bone quaternions."),
-    "BOM_JSON_INVALID": (1, ".topview3d/bom.json is corrupt; fix or delete it."),
+    "BOM_JSON_INVALID": (1, ".topview-3d/bom.json is corrupt; fix or delete it."),
     "RENDER_IMAGE_INVALID": (1, "A render image is not a PNG or no longer matches the sha256 in render.json."),
     "ASSET_FILE_MISSING": (1, "A manifest entry points to a file that does not exist."),
     "ASSET_NOT_AVAILABLE": (1, "A character or prop model in the document has no local asset (see details)."),
@@ -87,6 +88,9 @@ ERROR_CODES: dict[str, tuple[int, str]] = {
     "RENDER_RESULT_MISSING": (1, "The Node renderer printed no result."),
     "RENDER_RESULT_INVALID": (1, "The Node renderer printed a non-JSON result."),
     "DOCTOR_FAILED": (1, "Plain `doctor` found a missing or outdated dependency (`doctor --json` always exits 0)."),
+    "STUDIO_UNAVAILABLE": (1, "Studio is not in this install: it lives in editor/apps/studio of a checkout with Next.js installed."),
+    "STUDIO_START_FAILED": (1, "Node started Studio, but it did not list this project on port 3002."),
+    "STUDIO_PROJECT_MISSING": (1, "Studio is already running on port 3002 without this project; stop it and retry."),
     "INTERNAL_ERROR": (1, "Unexpected failure; the message carries the exception."),
 }
 

{topview_3d_cli-0.1.0 → topview_3d_cli-0.1.2}/topview_3d_cli/local_inspect.py

@@ -1,7 +1,7 @@
 """Read-only checks: ``evaluate`` (dry-run numbers), ``inspect nodes`` (mesh measurements), ``inspect views``.
 
 Nothing here edits the director document. ``inspect views`` writes render runs and records the
-runtime evidence in ``.topview3d/bom.json``.
+runtime evidence in ``.topview-3d/bom.json``.
 """
 from __future__ import annotations
 

{topview_3d_cli-0.1.0 → topview_3d_cli-0.1.2}/topview_3d_cli/local_project.py

@@ -1,6 +1,6 @@
 """Local, single-writer Scene3D project storage.
 
-``.topview3d/entities.json`` is the authoritative entity store (see
+``.topview-3d/entities.json`` is the authoritative entity store (see
 ``director_operations``). ``document.json`` and ``fcurves.json`` are derived views
 rewritten on every commit for renderers and humans; editing them has no effect.
 """
@@ -25,9 +25,11 @@ from topview_3d_cli.director_document import (
     validate_fcurves,
 )
 from topview_3d_cli.director_operations import (
+    MAX_BATCH_OPERATIONS,
     DirectorConflictError,
     DirectorOperationError,
     DirectorStore,
+    diff_operations,
     genesis_store,
 )
 from topview_3d_cli.local_errors import LocalProjectError
@@ -36,6 +38,7 @@ from topview_3d_cli.runtime import builder_version
 FORMAT_NAME = "scene3d-local-project"
 SCHEMA_VERSION = 2
 CLI_VERSION = __version__
+STATE_DIR_NAME = ".topview-3d"
 
 
 @dataclass(frozen=True)
@@ -61,7 +64,7 @@ class Project:
 
 def project_paths(root: str | os.PathLike[str]) -> ProjectPaths:
     directory = Path(root).expanduser().resolve()
-    state = directory / ".topview3d"
+    state = directory / STATE_DIR_NAME
     return ProjectPaths(
         root=directory,
         state=state,
@@ -192,6 +195,33 @@ def base_result(project: Project) -> dict[str, Any]:
     return result
 
 
+def adopt_edit(root: str | os.PathLike[str], payload: dict[str, Any]) -> dict[str, Any]:
+    """Replace the stored scene with a Studio edit so the next CLI command continues from it.
+
+    ``payload`` may include ``document``, ``fcurves``, or both. The omitted side stays as stored.
+    The entity store remains authoritative: the edit is applied as operations, then rewritten.
+    """
+    if not isinstance(payload, dict) or not ({"document", "fcurves"} & payload.keys()):
+        raise LocalProjectError("PROJECT_ADOPT_INVALID", "body must be an object with document and/or fcurves")
+    project = open_project(root)
+    current = project.store.assemble()
+    document = payload["document"] if "document" in payload else current["document"]
+    fcurves = payload["fcurves"] if "fcurves" in payload else current["fcurves"]
+    try:
+        operations = diff_operations(current, document, fcurves, stem="studio")
+    except (TypeError, ValueError) as exc:
+        raise LocalProjectError("INVALID_DIRECTOR_DOCUMENT", str(exc)) from exc
+    if not operations:
+        return {**base_result(project), "adopted": False, "operations": 0}
+    try:
+        for start in range(0, len(operations), MAX_BATCH_OPERATIONS):
+            project.store.apply(operations[start:start + MAX_BATCH_OPERATIONS], strict_versions=False, batch_id="studio")
+    except (DirectorConflictError, DirectorOperationError, ValueError) as exc:
+        raise LocalProjectError("INVALID_DIRECTOR_DOCUMENT", str(exc)) from exc
+    commit(project)
+    return {**base_result(project), "adopted": True, "operations": len(operations)}
+
+
 def project_status(root: str | os.PathLike[str]) -> dict[str, Any]:
     project = open_project(root)
     assembled = project.store.assemble()

{topview_3d_cli-0.1.0 → topview_3d_cli-0.1.2}/topview_3d_cli/local_render.py

@@ -1,4 +1,4 @@
-"""Render runs under ``.topview3d/renders/<runId>`` with the Node renderer and local model files."""
+"""Render runs under ``.topview-3d/renders/<runId>`` with the Node renderer and local model files."""
 from __future__ import annotations
 
 import hashlib

topview_3d_cli-0.1.2/topview_3d_cli/local_studio.py

@@ -0,0 +1,146 @@
+"""Open a local project in the checkout's Studio app.
+
+Studio is the Next.js app at ``editor/apps/studio``. It is not inside the published
+wheel, so this command only works from a repository checkout. It starts Studio with
+Node when port 3002 is free, then opens the system browser on this project.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import socket
+import sys
+import subprocess
+import time
+import urllib.error
+import urllib.request
+import webbrowser
+from pathlib import Path
+
+from topview_3d_cli.local_errors import LocalProjectError
+from topview_3d_cli.local_project import open_project
+from topview_3d_cli.runtime import REPO_ROOT, runtime, user_cache_dir
+
+STUDIO_PORT = 3002
+STUDIO_HOST = "127.0.0.1"
+
+
+def studio_project_id(directory_name: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", directory_name.lower()).strip("-") or "project"
+    return f"cli-{slug[:48]}"
+
+
+def _studio_dir() -> Path:
+    studio = REPO_ROOT / "editor" / "apps" / "studio"
+    if not (studio / "package.json").is_file():
+        raise LocalProjectError(
+            "STUDIO_UNAVAILABLE",
+            "Studio is part of a repository checkout (editor/apps/studio), not the published package",
+        )
+    return studio
+
+
+def _next_bin(studio: Path) -> Path:
+    candidates = [
+        studio / "node_modules" / "next" / "dist" / "bin" / "next",
+        studio.parents[1] / "node_modules" / "next" / "dist" / "bin" / "next",
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    raise LocalProjectError(
+        "STUDIO_UNAVAILABLE",
+        "Next.js is not installed; run pnpm install in editor/ of the checkout",
+    )
+
+
+def _port_open(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.settimeout(0.2)
+        return sock.connect_ex((STUDIO_HOST, port)) == 0
+
+
+def _projects(port: int) -> list[dict]:
+    url = f"http://{STUDIO_HOST}:{port}/api/projects"
+    try:
+        with urllib.request.urlopen(url, timeout=2) as response:
+            body = json.loads(response.read().decode("utf-8"))
+    except (OSError, urllib.error.URLError, json.JSONDecodeError, TimeoutError) as exc:
+        raise LocalProjectError("STUDIO_START_FAILED", f"Studio on port {port} did not list projects: {exc}") from exc
+    projects = body.get("projects") if isinstance(body, dict) else None
+    if not isinstance(projects, list):
+        raise LocalProjectError("STUDIO_START_FAILED", "Studio /api/projects did not return a project list")
+    return projects
+
+
+def _wait_until_listed(port: int, project_id: str, timeout: float = 60) -> None:
+    deadline = time.monotonic() + timeout
+    last_error = "timed out"
+    while time.monotonic() < deadline:
+        if _port_open(port):
+            try:
+                if any(item.get("id") == project_id for item in _projects(port) if isinstance(item, dict)):
+                    return
+                last_error = f"project {project_id} is not in the list"
+            except LocalProjectError as exc:
+                last_error = str(exc)
+        time.sleep(0.4)
+    raise LocalProjectError("STUDIO_START_FAILED", f"Studio did not become ready: {last_error}")
+
+
+def _start(studio: Path, next_bin: Path, project_root: Path) -> int:
+    log_dir = user_cache_dir() / "studio"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_path = log_dir / "studio.log"
+    env = dict(os.environ)
+    env["TOPVIEW3D_PROJECTS"] = str(project_root)
+    env["TOPVIEW3D_CLI"] = shutil.which("topview-3d-cli") or sys.argv[0]
+    try:
+        env["TOPVIEW3D_BUILTIN_ASSETS"] = str(runtime().builtin_assets)
+    except LocalProjectError:
+        pass
+    log = log_path.open("ab")
+    try:
+        process = subprocess.Popen(
+            ["node", str(next_bin), "dev", "--port", str(STUDIO_PORT), "--hostname", STUDIO_HOST],
+            cwd=studio,
+            env=env,
+            stdout=log,
+            stderr=subprocess.STDOUT,
+            start_new_session=True,
+        )
+    finally:
+        log.close()
+    return process.pid
+
+
+def open_studio(directory: str) -> dict:
+    project = open_project(directory)
+    root = project.paths.root
+    project_id = studio_project_id(root.name)
+    url = f"http://{STUDIO_HOST}:{STUDIO_PORT}/?project={project_id}"
+    started = False
+    pid = None
+    if _port_open(STUDIO_PORT):
+        listed = _projects(STUDIO_PORT)
+        if not any(item.get("id") == project_id for item in listed if isinstance(item, dict)):
+            raise LocalProjectError(
+                "STUDIO_PROJECT_MISSING",
+                f"Studio is already running on port {STUDIO_PORT} without this project; stop it and run studio open again",
+            )
+    else:
+        studio = _studio_dir()
+        pid = _start(studio, _next_bin(studio), root)
+        started = True
+        _wait_until_listed(STUDIO_PORT, project_id)
+    webbrowser.open(url)
+    return {
+        "ok": True,
+        "url": url,
+        "projectId": project_id,
+        "project": str(root),
+        "started": started,
+        "pid": pid,
+    }

{topview_3d_cli-0.1.0 → topview_3d_cli-0.1.2/topview_3d_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topview-3d-cli
-Version: 0.1.0
+Version: 0.1.2
 Summary: Build and render 3D director scenes locally with the topview-3d-cli command.
 License-Expression: Apache-2.0 AND CC-BY-4.0
 Project-URL: Homepage, https://www.topview.ai/topview-3d-builder
@@ -26,7 +26,7 @@ Dynamic: license-file
 # topview-3d-cli
 
 `topview-3d-cli` builds and renders 3D director scenes on your machine. Projects are plain files in a
-`.topview3d/` directory; rendering uses a local headless Chromium and makes no network requests.
+`.topview-3d/` directory; rendering uses a local headless Chromium and makes no network requests.
 
 Requirements: Python 3.11+ and Node.js 20.6+ (with npm).
 

{topview_3d_cli-0.1.0 → topview_3d_cli-0.1.2}/topview_3d_cli.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ topview_3d_cli/local_inspect.py
 topview_3d_cli/local_project.py
 topview_3d_cli/local_read.py
 topview_3d_cli/local_render.py
+topview_3d_cli/local_studio.py
 topview_3d_cli/node_batch.py
 topview_3d_cli/renderer.py
 topview_3d_cli/runtime.py