indesign-cli 0.2.0__py3-none-any.whl

cli_anything/indesign/core/paths.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+
+
+def _hash_path(path: Path) -> str:
+    digest = hashlib.sha256(str(path).encode("utf-8")).hexdigest()
+    return digest[:16]
+
+
+def scrub_path(path_value: str, cwd: Path) -> dict[str, object]:
+    path = Path(path_value)
+    try:
+        resolved = path.resolve()
+    except OSError:
+        resolved = path
+    try:
+        relative = resolved.relative_to(cwd.resolve())
+        return {
+            "path": str(relative).replace("\\", "/"),
+            "external": False,
+            "extension": resolved.suffix.lower(),
+        }
+    except ValueError:
+        return {
+            "external": True,
+            "kind": "external_path",
+            "extension": resolved.suffix.lower(),
+            "hash": _hash_path(resolved),
+        }
+
+
+def scrub_text_paths(value: str) -> str:
+    def replace(match: re.Match[str]) -> str:
+        raw_path = match.group(0)
+        suffix = Path(raw_path).suffix.lower()
+        return f"<external_path extension={suffix or 'unknown'} hash={_hash_path(Path(raw_path))}>"
+
+    return re.sub(r"[A-Za-z]:[\\/][^'\"\r\n]+", replace, value)

cli_anything/indesign/core/plugins/__init__.py

@@ -0,0 +1,2 @@
+from __future__ import annotations
+

cli_anything/indesign/core/plugins/backend.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import uuid
+from pathlib import Path
+from typing import Any
+
+from ..errors import CliError
+from .manifest import PluginRecord
+
+
+class PluginBackend:
+    def __init__(self, record: PluginRecord, *, timeout: int = 30) -> None:
+        self.record = record
+        self.timeout = timeout
+
+    def request(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        payload = {
+            "jsonrpc": "2.0",
+            "id": uuid.uuid4().hex[:12],
+            "method": method,
+            "params": params or {},
+        }
+        try:
+            completed = subprocess.run(
+                ["node", str(self.record.entry_path)],
+                cwd=self.record.root,
+                input=json.dumps(payload, ensure_ascii=False),
+                text=True,
+                encoding="utf-8",
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                timeout=self.timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise CliError("Plugin timed out", code="PLUGIN_TIMEOUT", retryable=True, details={"plugin": self.record.id, "method": method}) from exc
+
+        if completed.returncode != 0:
+            raise CliError(
+                "Plugin process failed",
+                code="PLUGIN_CALL_FAILED",
+                details={"plugin": self.record.id, "method": method, "returncode": completed.returncode, "stderr": completed.stderr[-1000:]},
+            )
+        try:
+            response = json.loads(completed.stdout)
+        except json.JSONDecodeError as exc:
+            raise CliError(
+                "Plugin stdout must be a single JSON response",
+                code="PLUGIN_STDOUT_INVALID",
+                details={"plugin": self.record.id, "method": method, "stdout_prefix": completed.stdout[:200]},
+            ) from exc
+        if not isinstance(response, dict):
+            raise CliError("Plugin response must be an object", code="PLUGIN_RESPONSE_INVALID", details={"plugin": self.record.id, "method": method})
+        if response.get("error"):
+            error = response["error"]
+            if not isinstance(error, dict):
+                raise CliError("Plugin error must be an object", code="PLUGIN_RESPONSE_INVALID", details={"plugin": self.record.id, "method": method})
+            raise CliError(
+                str(error.get("message") or "Plugin error"),
+                code=str(error.get("code") or "PLUGIN_ERROR"),
+                details=error.get("details") if isinstance(error.get("details"), dict) else {},
+            )
+        result = response.get("result")
+        if not isinstance(result, dict):
+            raise CliError("Plugin result must be an object", code="PLUGIN_RESPONSE_INVALID", details={"plugin": self.record.id, "method": method})
+        return result
+
+    def handshake(self, host: dict[str, Any]) -> dict[str, Any]:
+        return self.request("plugin/handshake", {"host": host})
+
+    def list_tools(self, context: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        result = self.request("tools/list", {"context": context or {}})
+        tools = result.get("tools")
+        if not isinstance(tools, list):
+            raise CliError("Plugin tools/list must return tools array", code="PLUGIN_RESPONSE_INVALID", details={"plugin": self.record.id})
+        return [tool for tool in tools if isinstance(tool, dict)]
+
+    def schema(self, tool_id: str) -> dict[str, Any]:
+        return self.request("tools/schema", {"tool_id": tool_id})
+
+    def call_tool(self, tool_id: str, args: dict[str, Any], context: dict[str, Any]) -> dict[str, Any]:
+        return self.request("tools/call", {"tool_id": tool_id, "args": args, "context": context})
+
+    def resume_tool(self, tool_id: str, state: dict[str, Any], host_results: list[dict[str, Any]]) -> dict[str, Any]:
+        return self.request("tools/resume", {"tool_id": tool_id, "state": state, "host_results": host_results})
+
+    def doctor(self) -> dict[str, Any]:
+        return self.request("plugin/doctor", {})

cli_anything/indesign/core/plugins/discovery.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+from ..errors import CliError
+from .manifest import PluginRecord, load_installed_plugin
+
+
+SOURCE_PRIORITY = {
+    "project": 1,
+    "user": 2,
+    "entry_point": 3,
+    "builtin": 4,
+}
+
+
+def project_plugin_dir(cwd: Path) -> Path:
+    return cwd / ".indesign-cli" / "plugins"
+
+
+def user_plugin_dir(home: Path | None = None) -> Path:
+    base = home or Path.home()
+    return base / ".indesign-cli" / "plugins"
+
+
+def discover_project_plugins(cwd: Path, *, host_version: str) -> tuple[list[PluginRecord], list[str]]:
+    directory = project_plugin_dir(cwd)
+    if not directory.exists():
+        return [], []
+    records: list[PluginRecord] = []
+    warnings: list[str] = []
+    for path in sorted(directory.glob("*.json")):
+        try:
+            record = load_installed_plugin(path, source="project", host_version=host_version)
+        except CliError as exc:
+            warnings.append(f"plugin record unavailable: {path.name}: {exc.code}")
+            continue
+        if record.enabled:
+            records.append(record)
+    return records, warnings
+
+
+def discover_plugins(cwd: Path, *, host_version: str) -> tuple[list[PluginRecord], list[str]]:
+    candidates, warnings = discover_project_plugins(cwd, host_version=host_version)
+    by_id: dict[str, list[PluginRecord]] = defaultdict(list)
+    for record in candidates:
+        by_id[record.id].append(record)
+
+    selected: list[PluginRecord] = []
+    for plugin_id, records in by_id.items():
+        grouped: dict[int, list[PluginRecord]] = defaultdict(list)
+        for record in records:
+            grouped[SOURCE_PRIORITY.get(record.source, 99)].append(record)
+        best_priority = min(grouped)
+        if len(grouped[best_priority]) > 1:
+            raise CliError("Duplicate plugins at the same priority", code="PLUGIN_DUPLICATE_ID", details={"id": plugin_id})
+        selected_record = grouped[best_priority][0]
+        selected.append(selected_record)
+        covered = [record for record in records if record is not selected_record]
+        for record in covered:
+            warnings.append(f"plugin {plugin_id} from {record.source} was covered by {selected_record.source}")
+
+    return sorted(selected, key=lambda item: item.id), warnings
+
+
+def plugin_summaries(records: list[PluginRecord]) -> list[dict[str, Any]]:
+    return [record.summary() for record in sorted(records, key=lambda item: item.id)]

cli_anything/indesign/core/plugins/host_actions.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..errors import CliError
+
+
+ALLOWED_HOST_ACTIONS = {"script.run", "export.verify", "session.show"}
+
+
+def _validate_script_path(path_value: str, cwd: Path) -> None:
+    script_path = Path(path_value).resolve()
+    cwd_root = cwd.resolve()
+    try:
+        script_path.relative_to(cwd_root)
+    except ValueError as exc:
+        raise CliError(
+            "Plugin script.run host action must stay inside the current project",
+            code="PLUGIN_HOST_ACTION_DENIED",
+            details={"path": str(script_path)},
+        ) from exc
+
+
+class HostActionExecutor:
+    def __init__(self, router: Any, cwd: Path, *, max_resume_rounds: int = 3) -> None:
+        self.router = router
+        self.cwd = cwd
+        self.max_resume_rounds = max_resume_rounds
+
+    def complete(self, backend: Any, tool_id: str, initial: dict[str, Any]) -> dict[str, Any]:
+        current = initial
+        failed_results: list[dict[str, Any]] = []
+        for _round in range(self.max_resume_rounds + 1):
+            if current.get("status") != "requires_host_actions":
+                if failed_results and current.get("data", {}).get("ok") is not False:
+                    raise CliError(
+                        "Plugin host action failed",
+                        code="PLUGIN_HOST_ACTION_FAILED",
+                        details={"tool_id": tool_id, "host_results": failed_results, "plugin_result": current},
+                    )
+                return current
+            actions = current.get("actions")
+            if not isinstance(actions, list):
+                raise CliError("Plugin host actions must be an array", code="PLUGIN_HOST_ACTION_INVALID")
+            host_results = [self._execute_action(action) for action in actions if isinstance(action, dict)]
+            failed_results.extend(result for result in host_results if result.get("ok") is False)
+            current = backend.resume_tool(tool_id, current.get("state") if isinstance(current.get("state"), dict) else {}, host_results)
+        raise CliError("Plugin exceeded host action resume limit", code="PLUGIN_HOST_ACTION_LIMIT_EXCEEDED", details={"tool_id": tool_id})
+
+    def _execute_action(self, action: dict[str, Any]) -> dict[str, Any]:
+        action_id = str(action.get("id") or "")
+        host_tool_id = str(action.get("tool_id") or "")
+        args = action.get("args") if isinstance(action.get("args"), dict) else {}
+        if host_tool_id not in ALLOWED_HOST_ACTIONS:
+            return {
+                "id": action_id,
+                "tool_id": host_tool_id,
+                "ok": False,
+                "error": {
+                    "code": "PLUGIN_HOST_ACTION_DENIED",
+                    "message": f"Host action is not allowed: {host_tool_id}",
+                },
+            }
+        try:
+            if host_tool_id == "script.run" and args.get("file"):
+                _validate_script_path(str(args["file"]), self.cwd)
+            data = self.router.call(host_tool_id, args)
+        except CliError as exc:
+            return {
+                "id": action_id,
+                "tool_id": host_tool_id,
+                "ok": False,
+                "error": {"code": exc.code, "message": exc.message, "details": exc.details},
+            }
+        return {"id": action_id, "tool_id": host_tool_id, "ok": True, "data": data}

cli_anything/indesign/core/plugins/install.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ..errors import CliError
+from .discovery import discover_plugins, plugin_summaries, project_plugin_dir
+from .manifest import install_record_for, load_plugin_record
+
+
+def install_plugin(path_value: str, *, cwd: Path, host_version: str) -> dict[str, Any]:
+    record = load_plugin_record(Path(path_value), source="project", host_version=host_version)
+    directory = project_plugin_dir(cwd)
+    directory.mkdir(parents=True, exist_ok=True)
+    target = directory / f"{record.id}.json"
+    target.write_text(json.dumps(install_record_for(record), ensure_ascii=False, indent=2), encoding="utf-8")
+    return {
+        "installed": True,
+        "id": record.id,
+        "domain": record.domain,
+        "version": record.version,
+        "record_path": str(target),
+        "root": str(record.root),
+    }
+
+
+def remove_plugin(plugin_id: str, *, cwd: Path) -> dict[str, Any]:
+    target = project_plugin_dir(cwd) / f"{plugin_id}.json"
+    if not target.exists():
+        raise CliError("Plugin is not installed in this project", code="PLUGIN_NOT_INSTALLED", details={"id": plugin_id})
+    target.unlink()
+    return {"removed": True, "id": plugin_id, "record_path": str(target)}
+
+
+def list_plugins(*, cwd: Path, host_version: str) -> dict[str, Any]:
+    records, warnings = discover_plugins(cwd, host_version=host_version)
+    return {"plugins": plugin_summaries(records), "warnings": warnings}

cli_anything/indesign/core/plugins/manifest.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..errors import CliError
+
+
+PLUGIN_PROTOCOL = "indesign-cli-plugin.v1"
+PLUGIN_SCHEMA_VERSION = 1
+SUPPORTED_KINDS = {"node-plugin"}
+ID_PATTERN = re.compile(r"^[a-z][a-z0-9-]{2,63}$")
+DOMAIN_PATTERN = re.compile(r"^[a-z][a-z0-9_]{1,31}$")
+TOOL_ID_PATTERN = re.compile(r"^[a-z][a-z0-9_]{1,31}\.[a-z][a-z0-9_]*$")
+CORE_DOMAINS = {
+    "template",
+    "document",
+    "page",
+    "spread",
+    "master",
+    "layer",
+    "object",
+    "text",
+    "graphics",
+    "style",
+    "export",
+    "book",
+    "presentation",
+    "script",
+    "session",
+    "server",
+    "skill",
+    "utility",
+}
+
+REQUIRED_MANIFEST_FIELDS = {
+    "schema_version",
+    "protocol",
+    "id",
+    "name",
+    "version",
+    "kind",
+    "domain",
+    "entry",
+    "description",
+    "requires",
+    "capabilities",
+    "permissions",
+}
+
+
+@dataclass(frozen=True)
+class PluginRecord:
+    id: str
+    source: str
+    root: Path
+    manifest_path: Path
+    manifest: dict[str, Any]
+    install_record_path: Path | None = None
+    enabled: bool = True
+
+    @property
+    def domain(self) -> str:
+        return str(self.manifest["domain"])
+
+    @property
+    def version(self) -> str:
+        return str(self.manifest["version"])
+
+    @property
+    def entry_path(self) -> Path:
+        return (self.root / str(self.manifest["entry"])).resolve()
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "domain": self.domain,
+            "version": self.version,
+            "source": self.source,
+            "enabled": self.enabled,
+            "root": str(self.root),
+            "manifest": str(self.manifest_path),
+        }
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8-sig"))
+    except FileNotFoundError as exc:
+        raise CliError("Plugin manifest not found", code="PLUGIN_MANIFEST_NOT_FOUND", details={"path": str(path)}) from exc
+    except json.JSONDecodeError as exc:
+        raise CliError("Plugin manifest must be valid JSON", code="PLUGIN_MANIFEST_JSON_INVALID", details={"path": str(path)}) from exc
+    if not isinstance(payload, dict):
+        raise CliError("Plugin manifest must be a JSON object", code="PLUGIN_MANIFEST_INVALID", details={"path": str(path)})
+    return payload
+
+
+def default_manifest_path(root: Path) -> Path:
+    preferred = root / "src" / "indesign-cli-plugin" / "manifest.json"
+    if preferred.exists():
+        return preferred
+    return root / "manifest.json"
+
+
+def resolve_manifest_input(path_or_manifest: Path) -> tuple[Path, Path, dict[str, Any]]:
+    path = path_or_manifest.resolve()
+    if path.is_dir():
+        root = path
+        manifest_path = default_manifest_path(root).resolve()
+    else:
+        manifest_path = path
+        if manifest_path.parent.name == "indesign-cli-plugin" and manifest_path.parent.parent.name == "src":
+            root = manifest_path.parent.parent.parent
+        else:
+            root = manifest_path.parent
+    manifest = read_json(manifest_path)
+    return root, manifest_path, manifest
+
+
+def resolve_install_record(record_path: Path) -> tuple[Path, Path, dict[str, Any], dict[str, Any]]:
+    record = read_json(record_path)
+    root_value = record.get("root")
+    if not isinstance(root_value, str) or not root_value:
+        raise CliError("Plugin install record requires root", code="PLUGIN_INSTALL_RECORD_INVALID", details={"path": str(record_path)})
+    root = Path(root_value).resolve()
+    manifest_relative = record.get("manifest") or "src/indesign-cli-plugin/manifest.json"
+    manifest_path = (root / str(manifest_relative)).resolve()
+    if not manifest_path.exists() and (root / "manifest.json").exists():
+        manifest_path = (root / "manifest.json").resolve()
+    manifest = read_json(manifest_path)
+    return root, manifest_path, manifest, record
+
+
+def _version_tuple(value: str) -> tuple[int, int, int]:
+    parts = value.split(".")
+    if len(parts) < 3:
+        raise ValueError(value)
+    return tuple(int(part) for part in parts[:3])
+
+
+def version_satisfies(version: str, requirement: str | None) -> bool:
+    if not requirement:
+        return True
+    requirement = requirement.strip()
+    if requirement.startswith(">="):
+        try:
+            return _version_tuple(version) >= _version_tuple(requirement[2:].strip())
+        except ValueError:
+            return False
+    return version == requirement
+
+
+def validate_manifest(
+    *,
+    manifest: dict[str, Any],
+    root: Path,
+    manifest_path: Path,
+    host_version: str,
+    allow_core_domain: bool = False,
+) -> list[dict[str, Any]]:
+    errors: list[dict[str, Any]] = []
+
+    missing = sorted(field for field in REQUIRED_MANIFEST_FIELDS if field not in manifest)
+    for field in missing:
+        errors.append({"code": "PLUGIN_MANIFEST_INVALID", "message": f"Missing manifest field: {field}", "details": {"field": field}})
+
+    if errors:
+        return errors
+
+    if manifest.get("schema_version") != PLUGIN_SCHEMA_VERSION:
+        errors.append({"code": "PLUGIN_MANIFEST_INVALID", "message": "Unsupported plugin schema_version", "details": {"schema_version": manifest.get("schema_version")}})
+    if manifest.get("protocol") != PLUGIN_PROTOCOL:
+        errors.append({"code": "PLUGIN_PROTOCOL_UNSUPPORTED", "message": "Unsupported plugin protocol", "details": {"protocol": manifest.get("protocol")}})
+    if manifest.get("kind") not in SUPPORTED_KINDS:
+        errors.append({"code": "PLUGIN_MANIFEST_INVALID", "message": "Unsupported plugin kind", "details": {"kind": manifest.get("kind")}})
+
+    plugin_id = manifest.get("id")
+    if not isinstance(plugin_id, str) or not ID_PATTERN.match(plugin_id):
+        errors.append({"code": "PLUGIN_MANIFEST_INVALID", "message": "Invalid plugin id", "details": {"id": plugin_id}})
+
+    domain = manifest.get("domain")
+    if not isinstance(domain, str) or not DOMAIN_PATTERN.match(domain):
+        errors.append({"code": "PLUGIN_MANIFEST_INVALID", "message": "Invalid plugin domain", "details": {"domain": domain}})
+    elif domain in CORE_DOMAINS and not allow_core_domain:
+        errors.append({"code": "PLUGIN_MANIFEST_INVALID", "message": "Plugin domain conflicts with core domain", "details": {"domain": domain}})
+
+    version = manifest.get("version")
+    if not isinstance(version, str):
+        errors.append({"code": "PLUGIN_MANIFEST_INVALID", "message": "Plugin version must be a string", "details": {"version": version}})
+    else:
+        try:
+            _version_tuple(version)
+        except ValueError:
+            errors.append({"code": "PLUGIN_MANIFEST_INVALID", "message": "Plugin version must be SemVer-like", "details": {"version": version}})
+
+    entry = manifest.get("entry")
+    if not isinstance(entry, str) or not entry:
+        errors.append({"code": "PLUGIN_ENTRY_NOT_FOUND", "message": "Plugin entry is required", "details": {"entry": entry}})
+    else:
+        entry_path = (root / entry).resolve()
+        try:
+            entry_path.relative_to(root.resolve())
+        except ValueError:
+            errors.append({"code": "PLUGIN_ENTRY_NOT_FOUND", "message": "Plugin entry must stay inside plugin root", "details": {"entry": entry}})
+        if not entry_path.exists():
+            errors.append({"code": "PLUGIN_ENTRY_NOT_FOUND", "message": "Plugin entry file not found", "details": {"entry": str(entry_path)}})
+
+    permissions = manifest.get("permissions")
+    if not isinstance(permissions, dict) or permissions.get("indesign") != "host_only":
+        errors.append({"code": "PLUGIN_MANIFEST_INVALID", "message": "permissions.indesign must be host_only", "details": {"permissions": permissions}})
+
+    requires = manifest.get("requires")
+    if not isinstance(requires, dict):
+        errors.append({"code": "PLUGIN_MANIFEST_INVALID", "message": "requires must be an object", "details": {"requires": requires}})
+    elif not version_satisfies(host_version, requires.get("indesign_cli")):
+        errors.append(
+            {
+                "code": "PLUGIN_PROTOCOL_UNSUPPORTED",
+                "message": "Plugin requires a different indesign-cli version",
+                "details": {"requires": requires.get("indesign_cli"), "host_version": host_version},
+            }
+        )
+
+    if not isinstance(manifest.get("capabilities"), dict):
+        errors.append({"code": "PLUGIN_MANIFEST_INVALID", "message": "capabilities must be an object", "details": {"capabilities": manifest.get("capabilities")}})
+
+    return errors
+
+
+def load_plugin_record(path_or_manifest: Path, *, source: str, host_version: str) -> PluginRecord:
+    root, manifest_path, manifest = resolve_manifest_input(path_or_manifest)
+    errors = validate_manifest(manifest=manifest, root=root, manifest_path=manifest_path, host_version=host_version)
+    if errors:
+        first = errors[0]
+        raise CliError(first["message"], code=first["code"], details={"errors": errors, "manifest": str(manifest_path)})
+    return PluginRecord(
+        id=str(manifest["id"]),
+        source=source,
+        root=root,
+        manifest_path=manifest_path,
+        manifest=manifest,
+        enabled=True,
+    )
+
+
+def load_installed_plugin(record_path: Path, *, source: str, host_version: str) -> PluginRecord:
+    root, manifest_path, manifest, record = resolve_install_record(record_path)
+    enabled = bool(record.get("enabled", True))
+    errors = validate_manifest(manifest=manifest, root=root, manifest_path=manifest_path, host_version=host_version)
+    if errors:
+        first = errors[0]
+        raise CliError(first["message"], code=first["code"], details={"errors": errors, "record": str(record_path)})
+    return PluginRecord(
+        id=str(manifest["id"]),
+        source=source,
+        root=root,
+        manifest_path=manifest_path,
+        manifest=manifest,
+        install_record_path=record_path,
+        enabled=enabled,
+    )
+
+
+def install_record_for(record: PluginRecord) -> dict[str, Any]:
+    try:
+        manifest_relative = record.manifest_path.relative_to(record.root)
+    except ValueError:
+        manifest_relative = record.manifest_path
+    return {
+        "schema_version": 1,
+        "id": record.id,
+        "kind": record.manifest["kind"],
+        "root": str(record.root),
+        "manifest": str(manifest_relative).replace("\\", "/"),
+        "enabled": True,
+    }