talkops-opscloud 0.3.0b1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (309) hide show
  1. opscloud/__init__.py +5 -0
  2. opscloud/__main__.py +6 -0
  3. opscloud/_constants.py +53 -0
  4. opscloud/_debug.py +145 -0
  5. opscloud/_debug_buffer.py +250 -0
  6. opscloud/_textual_patches.py +367 -0
  7. opscloud/_version.py +15 -0
  8. opscloud/agent/__init__.py +27 -0
  9. opscloud/agent/config.py +168 -0
  10. opscloud/agent/factory.py +1103 -0
  11. opscloud/approval_mode.py +44 -0
  12. opscloud/backend/__init__.py +49 -0
  13. opscloud/backend/composite.py +89 -0
  14. opscloud/backend/local.py +183 -0
  15. opscloud/backend/registry.py +79 -0
  16. opscloud/backend/sandbox_config.py +107 -0
  17. opscloud/backend/sandbox_factory.py +432 -0
  18. opscloud/built_in_skills/remember/SKILL.md +124 -0
  19. opscloud/built_in_skills/skill-creator/SKILL.md +348 -0
  20. opscloud/built_in_skills/skill-creator/scripts/init_skill.py +371 -0
  21. opscloud/built_in_skills/skill-creator/scripts/quick_validate.py +165 -0
  22. opscloud/cli/__init__.py +1 -0
  23. opscloud/cli/commands/__init__.py +15 -0
  24. opscloud/cli/commands/auth.py +45 -0
  25. opscloud/cli/commands/doctor.py +100 -0
  26. opscloud/cli/commands/mcp.py +137 -0
  27. opscloud/cli/commands/threads.py +51 -0
  28. opscloud/cli/interactive.py +154 -0
  29. opscloud/cli/main.py +903 -0
  30. opscloud/cli/non_interactive.py +425 -0
  31. opscloud/cli/server_manager.py +58 -0
  32. opscloud/commands/__init__.py +19 -0
  33. opscloud/commands/_base.py +110 -0
  34. opscloud/commands/_guards.py +52 -0
  35. opscloud/commands/_router.py +146 -0
  36. opscloud/commands/_types.py +36 -0
  37. opscloud/commands/core/__init__.py +47 -0
  38. opscloud/commands/core/auth.py +94 -0
  39. opscloud/commands/core/bug.py +46 -0
  40. opscloud/commands/core/clear.py +106 -0
  41. opscloud/commands/core/cloud.py +185 -0
  42. opscloud/commands/core/compact.py +128 -0
  43. opscloud/commands/core/config_cmd.py +120 -0
  44. opscloud/commands/core/context.py +220 -0
  45. opscloud/commands/core/cost.py +44 -0
  46. opscloud/commands/core/doctor.py +535 -0
  47. opscloud/commands/core/effort.py +108 -0
  48. opscloud/commands/core/exit_cmd.py +41 -0
  49. opscloud/commands/core/fast.py +148 -0
  50. opscloud/commands/core/help_cmd.py +94 -0
  51. opscloud/commands/core/mcp.py +134 -0
  52. opscloud/commands/core/model.py +109 -0
  53. opscloud/commands/core/permissions.py +196 -0
  54. opscloud/commands/core/plugins.py +92 -0
  55. opscloud/commands/core/pool.py +108 -0
  56. opscloud/commands/core/resume.py +97 -0
  57. opscloud/commands/core/skills.py +178 -0
  58. opscloud/commands/power/__init__.py +51 -0
  59. opscloud/commands/power/agents.py +98 -0
  60. opscloud/commands/power/btw.py +85 -0
  61. opscloud/commands/power/copy.py +97 -0
  62. opscloud/commands/power/goal.py +548 -0
  63. opscloud/commands/power/loop.py +295 -0
  64. opscloud/commands/power/memory.py +287 -0
  65. opscloud/commands/power/review.py +152 -0
  66. opscloud/commands/power/rubric.py +287 -0
  67. opscloud/commands/power/runtime.py +321 -0
  68. opscloud/commands/power/skill_creator.py +70 -0
  69. opscloud/commands/power/skill_invoke.py +165 -0
  70. opscloud/commands/power/tasks.py +209 -0
  71. opscloud/commands/power/trace.py +117 -0
  72. opscloud/commands/power/ui_toggles.py +135 -0
  73. opscloud/commands/power/version.py +52 -0
  74. opscloud/commands/registry.py +176 -0
  75. opscloud/config/__init__.py +114 -0
  76. opscloud/config/adapters/__init__.py +5 -0
  77. opscloud/config/adapters/postgres.py +776 -0
  78. opscloud/config/adapters/sqlite.py +769 -0
  79. opscloud/config/aws.py +248 -0
  80. opscloud/config/cloud_profiles.py +437 -0
  81. opscloud/config/env_vars.py +81 -0
  82. opscloud/config/langsmith.py +319 -0
  83. opscloud/config/manifest.py +817 -0
  84. opscloud/config/metadata.py +205 -0
  85. opscloud/config/paths.py +604 -0
  86. opscloud/config/plugins.py +130 -0
  87. opscloud/config/settings.py +834 -0
  88. opscloud/config/store.py +453 -0
  89. opscloud/config/store_factory.py +97 -0
  90. opscloud/config/toml_config.py +562 -0
  91. opscloud/editor.py +173 -0
  92. opscloud/exceptions.py +65 -0
  93. opscloud/file_ops.py +217 -0
  94. opscloud/hooks/__init__.py +139 -0
  95. opscloud/hooks/env.py +44 -0
  96. opscloud/hooks/interrupt.py +121 -0
  97. opscloud/hooks/models/__init__.py +109 -0
  98. opscloud/hooks/models/adapters.py +19 -0
  99. opscloud/hooks/models/config.py +79 -0
  100. opscloud/hooks/models/domain.py +434 -0
  101. opscloud/hooks/models/transport.py +37 -0
  102. opscloud/hooks/tools.py +231 -0
  103. opscloud/input.py +48 -0
  104. opscloud/integrations/__init__.py +80 -0
  105. opscloud/integrations/base.py +153 -0
  106. opscloud/integrations/content_filter.py +119 -0
  107. opscloud/integrations/event_bus.py +480 -0
  108. opscloud/integrations/hooks.py +238 -0
  109. opscloud/integrations/identity.py +181 -0
  110. opscloud/integrations/notifications.py +134 -0
  111. opscloud/integrations/stream_bridge.py +397 -0
  112. opscloud/integrations/thread_store.py +81 -0
  113. opscloud/json_types.py +20 -0
  114. opscloud/mcp/__init__.py +57 -0
  115. opscloud/mcp/config.py +203 -0
  116. opscloud/mcp/discovery.py +229 -0
  117. opscloud/mcp/mcp_info.py +109 -0
  118. opscloud/mcp/middleware.py +102 -0
  119. opscloud/mcp/preload.py +505 -0
  120. opscloud/mcp/raw_config.py +149 -0
  121. opscloud/mcp/semantic_profiler.py +305 -0
  122. opscloud/mcp/session_manager.py +727 -0
  123. opscloud/mcp/trust.py +105 -0
  124. opscloud/memory/__init__.py +27 -0
  125. opscloud/memory/branch.py +61 -0
  126. opscloud/memory/guard.py +19 -0
  127. opscloud/memory/onboarding.py +120 -0
  128. opscloud/memory/registry.py +134 -0
  129. opscloud/memory/store.py +223 -0
  130. opscloud/middleware/__init__.py +106 -0
  131. opscloud/middleware/_repository_bounds.py +459 -0
  132. opscloud/middleware/ask_user.py +152 -0
  133. opscloud/middleware/auto_mode.py +60 -0
  134. opscloud/middleware/auto_mode_hitl.py +2434 -0
  135. opscloud/middleware/compaction.py +566 -0
  136. opscloud/middleware/configurable_model.py +233 -0
  137. opscloud/middleware/cost_tracking.py +1021 -0
  138. opscloud/middleware/glm_stall_recovery.py +109 -0
  139. opscloud/middleware/goal_criteria.py +1234 -0
  140. opscloud/middleware/goal_state_notice.py +712 -0
  141. opscloud/middleware/goal_tools.py +407 -0
  142. opscloud/middleware/headless_mcp_guard.py +88 -0
  143. opscloud/middleware/jev_model_router.py +1018 -0
  144. opscloud/middleware/local_context.py +460 -0
  145. opscloud/middleware/mcp_context.py +151 -0
  146. opscloud/middleware/mcp_middleware.py +146 -0
  147. opscloud/middleware/memory_guard.py +393 -0
  148. opscloud/middleware/model_retry.py +205 -0
  149. opscloud/middleware/registry.py +137 -0
  150. opscloud/middleware/reliable_rubric.py +709 -0
  151. opscloud/middleware/resume_state.py +91 -0
  152. opscloud/middleware/server_hooks.py +1189 -0
  153. opscloud/middleware/shell_allow_list.py +90 -0
  154. opscloud/middleware/skills.py +382 -0
  155. opscloud/middleware/subagent_artifacts.py +84 -0
  156. opscloud/middleware/subagent_telemetry.py +261 -0
  157. opscloud/middleware/subagents.py +243 -0
  158. opscloud/middleware/tool_filter.py +384 -0
  159. opscloud/middleware/unified_system_message.py +62 -0
  160. opscloud/model/__init__.py +37 -0
  161. opscloud/model/config.py +2992 -0
  162. opscloud/model/factory.py +477 -0
  163. opscloud/model/pool.py +459 -0
  164. opscloud/model/reasoning.py +282 -0
  165. opscloud/offload.py +173 -0
  166. opscloud/output.py +64 -0
  167. opscloud/plugins/__init__.py +189 -0
  168. opscloud/plugins/_json.py +22 -0
  169. opscloud/plugins/adapters/__init__.py +13 -0
  170. opscloud/plugins/adapters/agents.py +112 -0
  171. opscloud/plugins/adapters/commands.py +190 -0
  172. opscloud/plugins/adapters/mcp.py +363 -0
  173. opscloud/plugins/adapters/skills.py +132 -0
  174. opscloud/plugins/commands_cli.py +541 -0
  175. opscloud/plugins/discovery.py +512 -0
  176. opscloud/plugins/manifest.py +335 -0
  177. opscloud/plugins/marketplace.py +893 -0
  178. opscloud/plugins/models.py +334 -0
  179. opscloud/plugins/project_plugins.py +317 -0
  180. opscloud/plugins/protocol.py +31 -0
  181. opscloud/plugins/store.py +905 -0
  182. opscloud/plugins/substitution.py +122 -0
  183. opscloud/project_utils.py +145 -0
  184. opscloud/prompts/__init__.py +37 -0
  185. opscloud/prompts/system.py +483 -0
  186. opscloud/prompts/templates/system_prompt.md +166 -0
  187. opscloud/prompts/types.py +54 -0
  188. opscloud/rubrics/__init__.py +42 -0
  189. opscloud/rubrics/evaluator.py +404 -0
  190. opscloud/rubrics/evidence_extractor.py +229 -0
  191. opscloud/rubrics/generator.py +239 -0
  192. opscloud/rubrics/jev_compiler.py +175 -0
  193. opscloud/rubrics/jev_grader.py +297 -0
  194. opscloud/rubrics/middleware.py +8 -0
  195. opscloud/schema/__init__.py +107 -0
  196. opscloud/schema/interrupts.py +981 -0
  197. opscloud/security/__init__.py +91 -0
  198. opscloud/security/approval_mode.py +528 -0
  199. opscloud/security/approval_mode_source.py +230 -0
  200. opscloud/security/cli_ast_evaluator.py +552 -0
  201. opscloud/security/jev_classifier.py +651 -0
  202. opscloud/security/shell_safety.py +340 -0
  203. opscloud/security/unicode_security.py +439 -0
  204. opscloud/security/url_validation.py +160 -0
  205. opscloud/server/__init__.py +13 -0
  206. opscloud/server/_server_config.py +158 -0
  207. opscloud/server/server.py +242 -0
  208. opscloud/server/server_graph.py +93 -0
  209. opscloud/skills/__init__.py +91 -0
  210. opscloud/skills/commands.py +1099 -0
  211. opscloud/skills/invocation.py +200 -0
  212. opscloud/skills/load.py +388 -0
  213. opscloud/skills/loader.py +23 -0
  214. opscloud/skills/merge.py +65 -0
  215. opscloud/skills/registry.py +263 -0
  216. opscloud/skills/sources.py +174 -0
  217. opscloud/skills/trust.py +417 -0
  218. opscloud/state/__init__.py +142 -0
  219. opscloud/state/base.py +154 -0
  220. opscloud/state/cloud_context.py +262 -0
  221. opscloud/state/goal_channels.py +124 -0
  222. opscloud/state/goal_state_limits.py +175 -0
  223. opscloud/state/resume_state.py +58 -0
  224. opscloud/state/service_context.py +281 -0
  225. opscloud/state/session.py +957 -0
  226. opscloud/state/state_migration.py +86 -0
  227. opscloud/subagents/__init__.py +30 -0
  228. opscloud/subagents/loader.py +331 -0
  229. opscloud/subagents/subagents_parser.py +117 -0
  230. opscloud/subagents/types.py +25 -0
  231. opscloud/tools/__init__.py +36 -0
  232. opscloud/tools/catalog.py +37 -0
  233. opscloud/tools/display.py +24 -0
  234. opscloud/tools/fetch_url.py +176 -0
  235. opscloud/tools/goal_tools.py +423 -0
  236. opscloud/tools/registry.py +105 -0
  237. opscloud/tools/thread.py +32 -0
  238. opscloud/tools/web_search.py +215 -0
  239. opscloud/ui/__init__.py +119 -0
  240. opscloud/ui/app.py +5400 -0
  241. opscloud/ui/app.tcss +479 -0
  242. opscloud/ui/clipboard.py +147 -0
  243. opscloud/ui/command_registry.py +482 -0
  244. opscloud/ui/message_store.py +152 -0
  245. opscloud/ui/permission_store.py +360 -0
  246. opscloud/ui/preferences.py +113 -0
  247. opscloud/ui/prompt_manager.py +96 -0
  248. opscloud/ui/remote_client.py +505 -0
  249. opscloud/ui/textual_adapter.py +1269 -0
  250. opscloud/ui/theme.py +728 -0
  251. opscloud/ui/ui_help.py +415 -0
  252. opscloud/ui/widgets/__init__.py +383 -0
  253. opscloud/ui/widgets/_ask_user_types.py +81 -0
  254. opscloud/ui/widgets/_copy_spans.py +52 -0
  255. opscloud/ui/widgets/_inline_prompt.py +290 -0
  256. opscloud/ui/widgets/_js_eval_display.py +139 -0
  257. opscloud/ui/widgets/_links.py +175 -0
  258. opscloud/ui/widgets/_tool_stream.py +308 -0
  259. opscloud/ui/widgets/agent_selector.py +297 -0
  260. opscloud/ui/widgets/approval.py +741 -0
  261. opscloud/ui/widgets/ask_user.py +539 -0
  262. opscloud/ui/widgets/auth.py +695 -0
  263. opscloud/ui/widgets/auth_manager.py +214 -0
  264. opscloud/ui/widgets/auto_mode_notice.py +146 -0
  265. opscloud/ui/widgets/autocomplete.py +709 -0
  266. opscloud/ui/widgets/chat_input.py +805 -0
  267. opscloud/ui/widgets/cloud_selector.py +528 -0
  268. opscloud/ui/widgets/config_manager.py +652 -0
  269. opscloud/ui/widgets/debug_console.py +1269 -0
  270. opscloud/ui/widgets/devops_renderers.py +184 -0
  271. opscloud/ui/widgets/diff.py +237 -0
  272. opscloud/ui/widgets/effort_selector.py +166 -0
  273. opscloud/ui/widgets/goal_review.py +612 -0
  274. opscloud/ui/widgets/goal_status.py +57 -0
  275. opscloud/ui/widgets/infra_panel.py +141 -0
  276. opscloud/ui/widgets/install_confirm.py +114 -0
  277. opscloud/ui/widgets/loading.py +170 -0
  278. opscloud/ui/widgets/mcp_viewer.py +1204 -0
  279. opscloud/ui/widgets/messages.py +4461 -0
  280. opscloud/ui/widgets/model_selector.py +863 -0
  281. opscloud/ui/widgets/notification_center.py +108 -0
  282. opscloud/ui/widgets/notification_settings.py +119 -0
  283. opscloud/ui/widgets/operation_card.py +106 -0
  284. opscloud/ui/widgets/permissions_manager.py +667 -0
  285. opscloud/ui/widgets/plugin_manager.py +1212 -0
  286. opscloud/ui/widgets/pool_selector.py +376 -0
  287. opscloud/ui/widgets/preamble.py +53 -0
  288. opscloud/ui/widgets/skills_viewer.py +432 -0
  289. opscloud/ui/widgets/status.py +1037 -0
  290. opscloud/ui/widgets/subagent_panel.py +927 -0
  291. opscloud/ui/widgets/theme_selector.py +232 -0
  292. opscloud/ui/widgets/thread_selector.py +358 -0
  293. opscloud/ui/widgets/toast.py +31 -0
  294. opscloud/ui/widgets/tool_display.py +325 -0
  295. opscloud/ui/widgets/tool_renderers.py +234 -0
  296. opscloud/ui/widgets/tool_widgets.py +278 -0
  297. opscloud/ui/widgets/welcome.py +421 -0
  298. opscloud/ui/widgets/welcome_popup.py +102 -0
  299. opscloud/utils/__init__.py +24 -0
  300. opscloud/utils/cost_estimation.py +169 -0
  301. opscloud/utils/git.py +390 -0
  302. opscloud/utils/logger.py +571 -0
  303. opscloud/utils/session_stats.py +115 -0
  304. opscloud/utils/startup_error.py +37 -0
  305. talkops_opscloud-0.3.0b1.dist-info/METADATA +449 -0
  306. talkops_opscloud-0.3.0b1.dist-info/RECORD +309 -0
  307. talkops_opscloud-0.3.0b1.dist-info/WHEEL +4 -0
  308. talkops_opscloud-0.3.0b1.dist-info/entry_points.txt +2 -0
  309. talkops_opscloud-0.3.0b1.dist-info/licenses/LICENSE +175 -0
@@ -0,0 +1,893 @@
1
+ """Marketplace parsing and materialization for K8s Autopilot."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import base64
6
+ from collections.abc import Callable
7
+ import hashlib
8
+ from http.client import HTTPMessage
9
+ import json
10
+ import os
11
+ from pathlib import Path
12
+ import re
13
+ import shutil
14
+ import subprocess
15
+ import tempfile
16
+ from typing import IO, TYPE_CHECKING
17
+ import urllib.error
18
+ from urllib.parse import parse_qsl, unquote, urlencode, urlparse, urlunparse
19
+ import urllib.request
20
+
21
+ if TYPE_CHECKING:
22
+ from opscloud.config.plugins import DefaultMarketplaceConfig
23
+
24
+ from opscloud.plugins.manifest import _resolve_component_path, _validate_name
25
+ from opscloud.plugins.models import (
26
+ ExternalPluginRepositorySourceType,
27
+ GithubPluginSource,
28
+ GitSubdirectoryPluginSource,
29
+ JsonObject,
30
+ JsonValue,
31
+ LocalMarketplaceSource,
32
+ LocalPluginSource,
33
+ MarketplacePluginEntry,
34
+ MarketplaceRecord,
35
+ MarketplaceSource,
36
+ PluginMarketplace,
37
+ PluginSource,
38
+ RepositoryMarketplaceSource,
39
+ UrlMarketplaceSource,
40
+ UrlPluginSource,
41
+ )
42
+ from opscloud.utils.logger import get_logger
43
+
44
+ logger = get_logger(__name__)
45
+
46
+ _MARKETPLACE_RELATIVE_PATHS = (
47
+ Path(".claude-plugin") / "marketplace.json",
48
+ Path(".opscode-plugin") / "marketplace.json",
49
+ Path(".opscode") / ".opscode-plugin" / "marketplace.json",
50
+ Path(".opscode") / "plugins" / "marketplace.json",
51
+ Path(".agents") / "plugins" / "marketplace.json",
52
+ Path("marketplace.json"),
53
+ )
54
+
55
+ _SSH_GIT_RE = re.compile(r"^([A-Za-z0-9._-]+@[^:]+:.+?(?:\.git)?)(?:#(.+))?$")
56
+ _GITHUB_REPO_RE = re.compile(r"^[^/\s]+/[^/\s]+$")
57
+ _GIT_TIMEOUT_SECONDS = 120
58
+ _GITHUB_REPO_PART_COUNT = 2
59
+ _SENSITIVE_QUERY_TERMS = (
60
+ "credential",
61
+ "key",
62
+ "password",
63
+ "secret",
64
+ "signature",
65
+ "token",
66
+ )
67
+ _SENSITIVE_PATH_KEY_RE = re.compile(
68
+ r"^(?:access[-_.]?token|api[-_.]?key|credential|key|password|secret|signature|token)s?$",
69
+ re.IGNORECASE,
70
+ )
71
+ _HTTP_URL_RE = re.compile(r"https?://\S+")
72
+
73
+
74
+ class MarketplaceError(ValueError):
75
+ """Raised when a marketplace cannot be loaded."""
76
+
77
+
78
+ def get_marketplace_cache_dir() -> Path:
79
+ """Return cache directory for marketplace catalogs."""
80
+ base_dir = os.getenv("PLUGIN_CACHE_DIR")
81
+ if base_dir:
82
+ cache_dir = Path(base_dir) / "marketplaces"
83
+ else:
84
+ from opscloud.config import paths
85
+
86
+ cache_dir = paths.PLUGINS_DIR / "marketplaces"
87
+ cache_dir.mkdir(parents=True, exist_ok=True)
88
+ return cache_dir
89
+
90
+
91
+ def opaque_cache_key(value: str) -> str:
92
+ """Return a sanitized, short SHA256 hex string for a cache key."""
93
+ return hashlib.sha256(value.encode("utf-8")).hexdigest()[:16]
94
+
95
+
96
+ def _redact_url_credentials(value: str) -> str:
97
+ """Redact HTTP credentials while preserving a useful URL for logs."""
98
+ try:
99
+ parsed = urlparse(value)
100
+ except ValueError:
101
+ return "https://***" if value.startswith("https://") else "http://***"
102
+ if parsed.scheme not in {"http", "https"}:
103
+ return value
104
+ netloc = parsed.netloc
105
+ if "@" in netloc:
106
+ try:
107
+ host = parsed.hostname or ""
108
+ if parsed.port is not None:
109
+ host = f"{host}:{parsed.port}"
110
+ except ValueError:
111
+ return f"{parsed.scheme}://***"
112
+ netloc = f"***@{host}"
113
+ query = urlencode(
114
+ [
115
+ (
116
+ key,
117
+ "***" if any(term in key.lower() for term in _SENSITIVE_QUERY_TERMS) else item,
118
+ )
119
+ for key, item in parse_qsl(parsed.query, keep_blank_values=True)
120
+ ]
121
+ )
122
+ path_parts = parsed.path.split("/")
123
+ redact_next = False
124
+ for index, part in enumerate(path_parts):
125
+ if redact_next and part:
126
+ path_parts[index] = "***"
127
+ redact_next = False
128
+ elif part:
129
+ redact_next = _SENSITIVE_PATH_KEY_RE.fullmatch(unquote(part)) is not None
130
+ path = "/".join(path_parts)
131
+ return urlunparse(parsed._replace(netloc=netloc, path=path, query=query))
132
+
133
+
134
+ _AUTH_HEADER_RE = re.compile(r"AUTHORIZATION:\s*(?:basic|bearer)\s+[A-Za-z0-9+/=._-]+", re.IGNORECASE)
135
+
136
+
137
+ def redact_marketplace_source(value: str) -> str:
138
+ """Return a marketplace source safe for display."""
139
+ return _redact_url_credentials(value)
140
+
141
+
142
+ def redact_urls_in_text(value: str) -> str:
143
+ """Redact credentials from every HTTP URL and authorization header embedded in text."""
144
+ redacted = _HTTP_URL_RE.sub(lambda match: _redact_url_credentials(match.group(0)), value)
145
+ return _AUTH_HEADER_RE.sub("AUTHORIZATION: [REDACTED]", redacted)
146
+
147
+
148
+ def parse_marketplace_source(raw: str) -> MarketplaceSource:
149
+ """Parse a user-provided marketplace source."""
150
+ value = raw.strip()
151
+ if not value:
152
+ msg = "Please enter a marketplace source"
153
+ raise MarketplaceError(msg)
154
+
155
+ ssh_match = _SSH_GIT_RE.match(value)
156
+ if ssh_match:
157
+ return RepositoryMarketplaceSource(source_type="git", value=ssh_match.group(1), ref=ssh_match.group(2))
158
+
159
+ if value.startswith("http://"):
160
+ msg = "Remote marketplace sources must use https"
161
+ raise MarketplaceError(msg)
162
+ if value.startswith("https://"):
163
+ url, _, ref = value.partition("#")
164
+ try:
165
+ parsed = urlparse(url)
166
+ except ValueError as exc:
167
+ msg = "Invalid marketplace URL"
168
+ raise MarketplaceError(msg) from exc
169
+ path = parsed.path
170
+ if path.endswith(".git") or "/_git/" in path:
171
+ return RepositoryMarketplaceSource(source_type="git", value=url, ref=ref or None)
172
+ if parsed.hostname in {"github.com", "www.github.com"}:
173
+ parts = [part for part in path.split("/") if part]
174
+ if len(parts) == _GITHUB_REPO_PART_COUNT:
175
+ repo_path = "/".join(parts)
176
+ git_url = urlunparse(parsed._replace(path=f"/{repo_path}.git"))
177
+ return RepositoryMarketplaceSource(source_type="git", value=git_url, ref=ref or None)
178
+ if len(parts) > _GITHUB_REPO_PART_COUNT:
179
+ msg = "GitHub marketplace URLs must contain exactly owner/repo"
180
+ raise MarketplaceError(msg)
181
+ return UrlMarketplaceSource(source_type="url", value=url)
182
+
183
+ if value.startswith(("./", "../", "/", "~")):
184
+ return _marketplace_source_from_path(value)
185
+
186
+ candidate = Path(value).expanduser()
187
+ if candidate.exists():
188
+ return _marketplace_source_from_path(value)
189
+
190
+ repo, sep, ref = value.replace("#", "@", 1).partition("@")
191
+ if "/" in value and ":" not in value and not value.startswith("@") and _GITHUB_REPO_RE.match(repo):
192
+ return RepositoryMarketplaceSource(source_type="github", value=repo, ref=ref if sep else None)
193
+
194
+ msg = "Invalid marketplace source format. Try: owner/repo, https://..., or ./path"
195
+ raise MarketplaceError(msg)
196
+
197
+
198
+ def _marketplace_source_from_path(value: str) -> MarketplaceSource:
199
+ path = Path(value).expanduser().resolve()
200
+ if not path.exists():
201
+ msg = f"Path does not exist: {path}"
202
+ raise MarketplaceError(msg)
203
+ if path.is_file():
204
+ if path.suffix != ".json":
205
+ msg = f"File path must point to a .json marketplace file: {path}"
206
+ raise MarketplaceError(msg)
207
+ return LocalMarketplaceSource(source_type="file", value=str(path))
208
+ if path.is_dir():
209
+ return LocalMarketplaceSource(source_type="directory", value=str(path))
210
+ msg = f"Path is neither a file nor a directory: {path}"
211
+ raise MarketplaceError(msg)
212
+
213
+
214
+ def _root_for_marketplace_file(path: Path) -> Path:
215
+ for relative in _MARKETPLACE_RELATIVE_PATHS:
216
+ if len(path.parts) >= len(relative.parts) and path.parts[-len(relative.parts) :] == relative.parts:
217
+ return path.parents[len(relative.parts) - 1]
218
+ return path.parent
219
+
220
+
221
+ def _load_marketplace_file(path: Path) -> PluginMarketplace:
222
+ root = _root_for_marketplace_file(path.expanduser().resolve())
223
+ return _load_marketplace_from_path(root, path.expanduser().resolve())
224
+
225
+
226
+ def _run_git(args: list[str]) -> None:
227
+ git_path = shutil.which("git")
228
+ if git_path is None:
229
+ msg = "Git is required to add repository-backed plugin marketplaces"
230
+ raise MarketplaceError(msg)
231
+ env = {
232
+ **os.environ,
233
+ "GIT_TERMINAL_PROMPT": "0",
234
+ "GIT_ASKPASS": "",
235
+ }
236
+ try:
237
+ result = subprocess.run(
238
+ [git_path, *args],
239
+ check=False,
240
+ capture_output=True,
241
+ env=env,
242
+ text=True,
243
+ timeout=_GIT_TIMEOUT_SECONDS,
244
+ )
245
+ except (OSError, subprocess.TimeoutExpired) as exc:
246
+ msg = f"Failed to run git: {redact_urls_in_text(str(exc))}"
247
+ raise MarketplaceError(msg) from exc
248
+ if result.returncode != 0:
249
+ detail = result.stderr.strip() or result.stdout.strip() or "unknown git error"
250
+ msg = f"Git command failed: {redact_urls_in_text(detail)}"
251
+ raise MarketplaceError(msg)
252
+
253
+
254
+ def _get_github_token() -> str | None:
255
+ """Retrieve GitHub token from environment or Settings if available."""
256
+ token = os.environ.get("GITHUB_PERSONAL_ACCESS_TOKEN") or os.environ.get("GITHUB_TOKEN")
257
+ if not token:
258
+ try:
259
+ from opscloud.config.settings import get_settings
260
+
261
+ token = getattr(get_settings(), "github_personal_access_token", None)
262
+ except Exception:
263
+ pass
264
+ if token and str(token).strip():
265
+ return str(token).strip()
266
+ return None
267
+
268
+
269
+ def _is_github_url(url: str) -> bool:
270
+ """Check if a URL points to GitHub."""
271
+ return "github.com" in url.lower()
272
+
273
+
274
+ def _build_github_auth_args(token: str) -> list[str]:
275
+ """Build git config CLI arguments to authenticate against github.com."""
276
+ b64_token = base64.b64encode(f"x-access-token:{token}".encode("utf-8")).decode("ascii")
277
+ return ["-c", f"http.https://github.com/.extraHeader=AUTHORIZATION: basic {b64_token}"]
278
+
279
+
280
+ def _clone_repository_to_cache(
281
+ source: RepositoryMarketplaceSource,
282
+ git_url: str,
283
+ *,
284
+ cache_key: str,
285
+ destination: Path | None = None,
286
+ validate: Callable[[Path], None] | None = None,
287
+ ) -> Path:
288
+ cache_path = (
289
+ destination.expanduser().resolve()
290
+ if destination is not None
291
+ else get_marketplace_cache_dir() / (f"repository-{opaque_cache_key(cache_key)}")
292
+ )
293
+ temp_path = Path(tempfile.mkdtemp(prefix=f".{cache_path.name}.", dir=cache_path.parent))
294
+
295
+ # Check for GitHub token
296
+ github_token = _get_github_token() if _is_github_url(git_url) else None
297
+
298
+ # If GitHub SSH URL was provided and a token exists, convert to HTTPS
299
+ effective_git_url = git_url
300
+ if github_token and (git_url.startswith("git@github.com:") or "git@github.com" in git_url):
301
+ match = _SSH_GIT_RE.match(git_url)
302
+ if match:
303
+ raw_target = match.group(1).split(":", 1)[-1]
304
+ effective_git_url = f"https://github.com/{raw_target}"
305
+
306
+ base_args = ["clone", "--depth", "1", "--recurse-submodules", "--shallow-submodules"]
307
+ if source.ref:
308
+ base_args.extend(["--branch", source.ref])
309
+ base_args.extend([effective_git_url, str(temp_path)])
310
+
311
+ try:
312
+ if github_token:
313
+ auth_args = _build_github_auth_args(github_token) + base_args
314
+ try:
315
+ _run_git(auth_args)
316
+ except MarketplaceError as exc:
317
+ # If authenticated clone failed, it might be:
318
+ # 1. A public repository where the configured token is invalid/expired/missing scopes
319
+ # 2. A truly private repository where token lacks permission
320
+ # Resilient fallback: attempt unauthenticated clone so public repos NEVER fail due to bad tokens!
321
+ logger.warning(
322
+ "Authenticated git clone failed for %s (%s). Retrying unauthenticated clone in case repository is public...",
323
+ redact_urls_in_text(effective_git_url),
324
+ exc,
325
+ )
326
+ if temp_path.exists():
327
+ shutil.rmtree(temp_path, ignore_errors=True)
328
+ try:
329
+ _run_git(base_args)
330
+ except MarketplaceError as unauth_exc:
331
+ raise MarketplaceError(
332
+ f"Failed to clone repository '{redact_urls_in_text(effective_git_url)}'. "
333
+ "Authentication failed, and unauthenticated public clone also failed. "
334
+ "Please verify the repository exists and that your GITHUB_PERSONAL_ACCESS_TOKEN has appropriate repository access."
335
+ ) from unauth_exc
336
+ else:
337
+ # No token provided (user forgot to set it, or repository is public)
338
+ try:
339
+ _run_git(base_args)
340
+ except MarketplaceError as exc:
341
+ err_lower = str(exc).lower()
342
+ if any(phrase in err_lower for phrase in (
343
+ "could not read username",
344
+ "authentication failed",
345
+ "terminal prompts disabled",
346
+ "not found",
347
+ "fatal: repository",
348
+ )):
349
+ raise MarketplaceError(
350
+ f"Failed to clone repository '{redact_urls_in_text(effective_git_url)}'. "
351
+ "If this is a private repository, please configure your GITHUB_PERSONAL_ACCESS_TOKEN in Settings."
352
+ ) from exc
353
+ raise
354
+
355
+ if validate is not None:
356
+ validate(temp_path)
357
+ backup_path = cache_path.with_name(f".{cache_path.name}.backup")
358
+ if backup_path.exists():
359
+ shutil.rmtree(backup_path, ignore_errors=True)
360
+ if cache_path.exists():
361
+ cache_path.replace(backup_path)
362
+ try:
363
+ temp_path.replace(cache_path)
364
+ except OSError:
365
+ if backup_path.exists() and not cache_path.exists():
366
+ backup_path.replace(cache_path)
367
+ raise
368
+ if backup_path.exists():
369
+ shutil.rmtree(backup_path, ignore_errors=True)
370
+ except Exception:
371
+ shutil.rmtree(temp_path, ignore_errors=True)
372
+ raise
373
+ return cache_path
374
+
375
+
376
+ def _materialize_marketplace_repository(source: RepositoryMarketplaceSource, git_url: str) -> Path:
377
+ return _clone_repository_to_cache(
378
+ source,
379
+ git_url,
380
+ cache_key=f"marketplace-{source.source_type}-{source.value}",
381
+ validate=_validate_marketplace_repository,
382
+ )
383
+
384
+
385
+ def _validate_marketplace_repository(root: Path) -> None:
386
+ load_marketplace(root)
387
+
388
+
389
+ def _materialize_plugin_repository(
390
+ source: RepositoryMarketplaceSource,
391
+ git_url: str,
392
+ *,
393
+ cache_key: str,
394
+ ) -> Path:
395
+ return _clone_repository_to_cache(source, git_url, cache_key=cache_key)
396
+
397
+
398
+ class _HttpsOnlyRedirectHandler(urllib.request.HTTPRedirectHandler):
399
+ """HTTP redirect handler that rejects non-HTTPS redirect targets."""
400
+
401
+ def redirect_request(
402
+ self,
403
+ req: urllib.request.Request,
404
+ fp: IO[bytes],
405
+ code: int,
406
+ msg: str,
407
+ headers: HTTPMessage,
408
+ newurl: str,
409
+ ) -> urllib.request.Request | None:
410
+ """Validate that redirection target uses HTTPS and return redirect request.
411
+
412
+ Args:
413
+ req: Original request object.
414
+ fp: File-like object pointing to response body.
415
+ code: HTTP response status code.
416
+ msg: HTTP response reason phrase.
417
+ headers: HTTP response headers.
418
+ newurl: Target redirection URL.
419
+
420
+ Returns:
421
+ urllib.request.Request | None: Redirected request object or None.
422
+
423
+ Raises:
424
+ MarketplaceError: If redirect target scheme is not HTTPS.
425
+ """
426
+ if urlparse(newurl).scheme != "https":
427
+ detail = _redact_url_credentials(newurl)
428
+ error = f"Marketplace redirect must use https: {detail}"
429
+ raise MarketplaceError(error)
430
+ return super().redirect_request(req, fp, code, msg, headers, newurl)
431
+
432
+
433
+ def _download_marketplace(url: str) -> Path:
434
+ parsed = urlparse(url)
435
+ if parsed.scheme != "https":
436
+ msg = f"Marketplace URL must use https: {_redact_url_credentials(url)}"
437
+ raise MarketplaceError(msg)
438
+ cache_path = get_marketplace_cache_dir() / f"marketplace-url-{opaque_cache_key(url)}.json"
439
+ request = urllib.request.Request(url, headers={"User-Agent": "opscloud-plugin-manager"})
440
+ opener = urllib.request.build_opener(_HttpsOnlyRedirectHandler())
441
+ try:
442
+ with opener.open(request, timeout=10) as response:
443
+ final_url = response.geturl()
444
+ if urlparse(final_url).scheme != "https":
445
+ detail = _redact_url_credentials(final_url)
446
+ msg = f"Marketplace response must use https: {detail}"
447
+ raise MarketplaceError(msg)
448
+ data = json.load(response)
449
+ except (OSError, urllib.error.URLError, json.JSONDecodeError) as exc:
450
+ msg = f"Failed to download marketplace from {_redact_url_credentials(url)}: {redact_urls_in_text(str(exc))}"
451
+ raise MarketplaceError(msg) from exc
452
+ if not isinstance(data, dict):
453
+ msg = f"Marketplace URL must return a JSON object: {_redact_url_credentials(url)}"
454
+ raise MarketplaceError(msg)
455
+ cache_path.parent.mkdir(parents=True, exist_ok=True)
456
+ cache_path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
457
+ return cache_path
458
+
459
+
460
+ def materialize_marketplace_source(
461
+ source: MarketplaceSource,
462
+ ) -> tuple[PluginMarketplace, Path]:
463
+ """Load a marketplace source and return its local install location."""
464
+ if source.source_type == "directory":
465
+ root = Path(source.value).expanduser().resolve()
466
+ return load_marketplace(root), root
467
+ if source.source_type == "file":
468
+ path = Path(source.value).expanduser().resolve()
469
+ return _load_marketplace_file(path), path
470
+ if source.source_type == "url":
471
+ path = _download_marketplace(source.value)
472
+ marketplace = _load_marketplace_file(path)
473
+ _reject_url_marketplace_with_local_plugins(marketplace, source.value)
474
+ return marketplace, path
475
+ if source.source_type == "github":
476
+ if not isinstance(source, RepositoryMarketplaceSource):
477
+ msg = "GitHub marketplace source is missing repository metadata"
478
+ raise MarketplaceError(msg)
479
+ root = _materialize_marketplace_repository(source, f"https://github.com/{source.value}.git")
480
+ return load_marketplace(root), root
481
+ if source.source_type == "git":
482
+ if not isinstance(source, RepositoryMarketplaceSource):
483
+ msg = "Git marketplace source is missing repository metadata"
484
+ raise MarketplaceError(msg)
485
+ root = _materialize_marketplace_repository(source, source.value)
486
+ return load_marketplace(root), root
487
+ msg = f"Unsupported marketplace source type: {source.source_type}"
488
+ raise MarketplaceError(msg)
489
+
490
+
491
+ def _reject_url_marketplace_with_local_plugins(marketplace: PluginMarketplace, url: str) -> None:
492
+ local_plugins = [plugin.name for plugin in marketplace.plugins if _source_path(plugin.source) is not None]
493
+ if not local_plugins:
494
+ unsupported = [plugin.name for plugin in marketplace.plugins if _plugin_repository_source(plugin) is None]
495
+ if not unsupported:
496
+ return
497
+ names = ", ".join(sorted(unsupported))
498
+ msg = (
499
+ f"Marketplace URL {_redact_url_credentials(url)} contains plugins "
500
+ f"with unsupported remote sources: [{names}]"
501
+ )
502
+ raise MarketplaceError(msg)
503
+ names = ", ".join(sorted(local_plugins))
504
+ msg = (
505
+ f"Marketplace URL {_redact_url_credentials(url)} only downloads the "
506
+ f"catalog JSON, but plugins [{names}] use local relative sources. "
507
+ "Use a git repository or local directory for this marketplace."
508
+ )
509
+ raise MarketplaceError(msg)
510
+
511
+
512
+ def load_live_default_marketplace(
513
+ root: Path,
514
+ config: DefaultMarketplaceConfig | None = None,
515
+ ) -> PluginMarketplace:
516
+ """Fetch the live default marketplace catalog from the remote repository and construct PluginMarketplace."""
517
+ from opscloud.config.plugins import (
518
+ fetch_marketplace_manifest,
519
+ get_default_marketplace_config,
520
+ )
521
+
522
+ if config is None:
523
+ config = get_default_marketplace_config(root.name)
524
+ if config is None:
525
+ msg = f"No default marketplace configuration found for {root.name}"
526
+ raise MarketplaceError(msg)
527
+
528
+ try:
529
+ raw = fetch_marketplace_manifest(config.manifest_url)
530
+ except Exception as exc:
531
+ msg = f"Failed to fetch live default marketplace manifest for '{config.name}' from {config.manifest_url}: {exc}"
532
+ raise MarketplaceError(msg) from exc
533
+
534
+ try:
535
+ name = _validate_name(raw.get("name"), allow_at=False)
536
+ except ValueError as exc:
537
+ raise MarketplaceError(str(exc)) from exc
538
+
539
+ plugins_raw = raw.get("plugins")
540
+ if not isinstance(plugins_raw, list):
541
+ msg = f"Marketplace {name} must contain a plugins array"
542
+ raise MarketplaceError(msg)
543
+
544
+ warnings: list[str] = []
545
+ plugins = tuple(
546
+ plugin for entry in plugins_raw if (plugin := _parse_entry(entry, warnings=warnings)) is not None
547
+ )
548
+ for warning in warnings:
549
+ logger.warning("%s", warning)
550
+
551
+ metadata = raw.get("metadata") or {}
552
+ manifest_path = root / ".claude-plugin" / "marketplace.json"
553
+ return PluginMarketplace(
554
+ name=name,
555
+ root=root,
556
+ manifest_path=manifest_path,
557
+ metadata=metadata,
558
+ plugins=plugins,
559
+ warnings=tuple(warnings),
560
+ )
561
+
562
+
563
+ def load_marketplace_location(path: Path) -> PluginMarketplace:
564
+ """Load a marketplace from either a cached directory, JSON file, or live default marketplace."""
565
+ from opscloud.config.plugins import get_default_marketplace_config
566
+
567
+ resolved = path.expanduser().resolve()
568
+ default_cfg = get_default_marketplace_config(resolved.name)
569
+ if default_cfg is not None:
570
+ return load_live_default_marketplace(resolved, config=default_cfg)
571
+ if resolved.is_file():
572
+ return _load_marketplace_file(resolved)
573
+ return load_marketplace(resolved)
574
+
575
+
576
+ def find_marketplace_manifest(root: Path) -> Path | None:
577
+ """Return a marketplace manifest path under `root`, if present."""
578
+ for rel in _MARKETPLACE_RELATIVE_PATHS:
579
+ path = root / rel
580
+ try:
581
+ if path.is_file():
582
+ return path
583
+ except OSError:
584
+ logger.warning("Could not inspect marketplace manifest path %s", path)
585
+ return None
586
+
587
+
588
+ def _source_path(source: PluginSource) -> str | None:
589
+ return source.path if isinstance(source, LocalPluginSource) else None
590
+
591
+
592
+ def _external_plugin_repository_source_type(
593
+ value: JsonValue,
594
+ ) -> ExternalPluginRepositorySourceType | None:
595
+ if value == "github":
596
+ return "github"
597
+ if value == "git-subdir":
598
+ return "git-subdir"
599
+ if value == "url":
600
+ return "url"
601
+ return None
602
+
603
+
604
+ def _plugin_repository_source(
605
+ plugin: MarketplacePluginEntry,
606
+ ) -> tuple[RepositoryMarketplaceSource, str, str | None] | None:
607
+ if not isinstance(
608
+ plugin.source,
609
+ (GithubPluginSource, GitSubdirectoryPluginSource, UrlPluginSource),
610
+ ):
611
+ return None
612
+ kind = plugin.source.source_type
613
+ ref_value = plugin.source.ref
614
+ subpath_value = plugin.source.path
615
+ if kind == "github":
616
+ if not isinstance(plugin.source, GithubPluginSource):
617
+ return None
618
+ repo = plugin.source.repo
619
+ parsed = parse_marketplace_source(f"{repo}#{ref_value}" if ref_value else repo)
620
+ if not isinstance(parsed, RepositoryMarketplaceSource):
621
+ return None
622
+ return parsed, f"https://github.com/{parsed.value}.git", subpath_value
623
+ if kind not in {"git-subdir", "url"}:
624
+ return None
625
+ if not isinstance(plugin.source, (GitSubdirectoryPluginSource, UrlPluginSource)):
626
+ return None
627
+ raw_url = plugin.source.url
628
+ parsed = parse_marketplace_source(f"{raw_url}#{ref_value}" if ref_value else raw_url)
629
+ if parsed.source_type == "github":
630
+ git_url = f"https://github.com/{parsed.value}.git"
631
+ elif parsed.source_type == "git":
632
+ git_url = parsed.value
633
+ else:
634
+ return None
635
+ if not isinstance(parsed, RepositoryMarketplaceSource):
636
+ return None
637
+ return parsed, git_url, subpath_value
638
+
639
+
640
+ def materialize_plugin_source(marketplace: PluginMarketplace, plugin: MarketplacePluginEntry) -> Path | None:
641
+ """Resolve or materialize a marketplace plugin entry to a plugin root."""
642
+ raw = _source_path(plugin.source)
643
+ if raw is not None:
644
+ metadata_root = marketplace.metadata.get("pluginRoot")
645
+ warnings: list[str] = []
646
+ base = marketplace.root
647
+ if isinstance(metadata_root, str) and raw.startswith("./"):
648
+ clean_meta = metadata_root.removeprefix("./").strip("/")
649
+ clean_raw = raw.removeprefix("./").strip("/")
650
+ if clean_raw.startswith(clean_meta + "/") or clean_raw == clean_meta:
651
+ base = marketplace.root
652
+ else:
653
+ base_path = _resolve_component_path(metadata_root, marketplace.root, "metadata.pluginRoot", warnings)
654
+ if base_path is not None:
655
+ base = base_path
656
+ resolved = _resolve_component_path(raw, base, f"plugins.{plugin.name}.source", warnings)
657
+ for warning in warnings:
658
+ logger.warning("Marketplace %s: %s", marketplace.name, warning)
659
+ if resolved is not None and not resolved.exists():
660
+ from opscloud.config.plugins import get_default_marketplace_config
661
+
662
+ cfg = get_default_marketplace_config(marketplace.name)
663
+ if cfg is not None:
664
+ repo_source = RepositoryMarketplaceSource(
665
+ source_type="git",
666
+ value=cfg.repository_url,
667
+ ref=cfg.ref,
668
+ )
669
+ _clone_repository_to_cache(
670
+ repo_source,
671
+ cfg.repository_url,
672
+ cache_key=f"marketplace-git-{cfg.repository_url}",
673
+ destination=marketplace.root,
674
+ )
675
+ if resolved.exists():
676
+ return resolved
677
+ return resolved
678
+
679
+ repository = _plugin_repository_source(plugin)
680
+ if repository is None:
681
+ return None
682
+ source, git_url, subpath = repository
683
+ root = _materialize_plugin_repository(
684
+ source,
685
+ git_url,
686
+ cache_key=(f"plugin-source-{marketplace.name}-{plugin.name}-{plugin.source!r}"),
687
+ )
688
+ if subpath is None:
689
+ return root
690
+ warnings: list[str] = []
691
+ resolved = _resolve_component_path(subpath, root, f"plugins.{plugin.name}.source.path", warnings)
692
+ for warning in warnings:
693
+ logger.warning("Marketplace %s: %s", marketplace.name, warning)
694
+ return resolved
695
+
696
+
697
+ def _optional_source_string(
698
+ source: JsonObject,
699
+ field: str,
700
+ *,
701
+ plugin_name: object,
702
+ warnings: list[str],
703
+ ) -> tuple[str | None, bool]:
704
+ value = source.get(field)
705
+ if value is None:
706
+ return None, True
707
+ if isinstance(value, str):
708
+ return value, True
709
+ warnings.append(f"Skipping marketplace plugin {plugin_name!r}: source.{field} must be a string")
710
+ return None, False
711
+
712
+
713
+ def _parse_plugin_source(value: object, *, plugin_name: object, warnings: list[str]) -> PluginSource | None:
714
+ if isinstance(value, str):
715
+ return LocalPluginSource(source_type="local", path=value)
716
+ if not isinstance(value, dict):
717
+ warnings.append(f"Skipping marketplace plugin {plugin_name!r}: missing source")
718
+ return None
719
+ source = value
720
+ kind = source.get("source")
721
+ path, path_valid = _optional_source_string(source, "path", plugin_name=plugin_name, warnings=warnings)
722
+ ref, ref_valid = _optional_source_string(source, "ref", plugin_name=plugin_name, warnings=warnings)
723
+ if not path_valid or not ref_valid:
724
+ return None
725
+ if kind == "local":
726
+ if path is None:
727
+ warnings.append(f"Skipping marketplace plugin {plugin_name!r}: local source requires path")
728
+ return None
729
+ return LocalPluginSource(source_type="local", path=path)
730
+ source_type = _external_plugin_repository_source_type(kind)
731
+ if source_type is None:
732
+ warnings.append(f"Skipping marketplace plugin {plugin_name!r}: unsupported source {kind!r}")
733
+ return None
734
+ repo, repo_valid = _optional_source_string(source, "repo", plugin_name=plugin_name, warnings=warnings)
735
+ url, url_valid = _optional_source_string(source, "url", plugin_name=plugin_name, warnings=warnings)
736
+ if not repo_valid or not url_valid:
737
+ return None
738
+ if source_type == "github" and repo is None:
739
+ warnings.append(f"Skipping marketplace plugin {plugin_name!r}: github source requires repo")
740
+ return None
741
+ if source_type in {"git-subdir", "url"} and url is None:
742
+ warnings.append(f"Skipping marketplace plugin {plugin_name!r}: {source_type} source requires url")
743
+ return None
744
+ if source_type == "github":
745
+ if repo is None:
746
+ return None
747
+ return GithubPluginSource(
748
+ source_type="github",
749
+ repo=repo,
750
+ ref=ref,
751
+ path=path,
752
+ )
753
+ if url is None:
754
+ return None
755
+ if source_type == "git-subdir":
756
+ return GitSubdirectoryPluginSource(
757
+ source_type="git-subdir",
758
+ url=url,
759
+ ref=ref,
760
+ path=path,
761
+ )
762
+ return UrlPluginSource(
763
+ source_type="url",
764
+ url=url,
765
+ ref=ref,
766
+ path=path,
767
+ )
768
+
769
+
770
+ def _parse_entry(entry: object, *, warnings: list[str]) -> MarketplacePluginEntry | None:
771
+ if not isinstance(entry, dict):
772
+ warnings.append(f"Skipping marketplace plugin entry: expected object, got {type(entry).__name__}")
773
+ return None
774
+ source = _parse_plugin_source(entry.get("source"), plugin_name=entry.get("name"), warnings=warnings)
775
+ if source is None:
776
+ return None
777
+ try:
778
+ name = _validate_name(entry.get("name"))
779
+ except ValueError as exc:
780
+ warnings.append(f"Skipping marketplace plugin with invalid name: {exc}")
781
+ return None
782
+ description_value = entry.get("description")
783
+ author_value = entry.get("author")
784
+ author = author_value if isinstance(author_value, (dict, str)) else None
785
+ display_name_value = entry.get("displayName") or entry.get("display_name")
786
+ version_value = entry.get("version")
787
+ version = version_value if isinstance(version_value, str) else "0.1.0"
788
+ category_value = entry.get("category")
789
+ category = category_value if isinstance(category_value, str) else None
790
+ keywords_value = entry.get("keywords")
791
+ if isinstance(keywords_value, list):
792
+ keywords = tuple(str(k) for k in keywords_value if isinstance(k, (str, int)))
793
+ else:
794
+ keywords = ()
795
+ return MarketplacePluginEntry(
796
+ name=name,
797
+ source=source,
798
+ description=description_value if isinstance(description_value, str) else None,
799
+ author=author,
800
+ display_name=(display_name_value if isinstance(display_name_value, str) else None),
801
+ version=version,
802
+ category=category,
803
+ keywords=keywords,
804
+ )
805
+
806
+
807
+ def _load_marketplace_from_path(root: Path, manifest_path: Path) -> PluginMarketplace:
808
+ try:
809
+ raw = json.loads(manifest_path.read_text(encoding="utf-8"))
810
+ except json.JSONDecodeError as exc:
811
+ msg = f"Invalid JSON syntax in {manifest_path}: {exc}"
812
+ raise MarketplaceError(msg) from exc
813
+ except OSError as exc:
814
+ msg = f"Could not read marketplace manifest {manifest_path}: {exc}"
815
+ raise MarketplaceError(msg) from exc
816
+ if not isinstance(raw, dict):
817
+ msg = f"Marketplace manifest {manifest_path} must be a JSON object"
818
+ raise MarketplaceError(msg)
819
+ try:
820
+ name = _validate_name(raw.get("name"), allow_at=False)
821
+ except ValueError as exc:
822
+ raise MarketplaceError(str(exc)) from exc
823
+ plugins_raw = raw.get("plugins")
824
+ if not isinstance(plugins_raw, list):
825
+ msg = f"Marketplace {name} must contain a plugins array"
826
+ raise MarketplaceError(msg)
827
+ warnings: list[str] = []
828
+ plugins = tuple(plugin for entry in plugins_raw if (plugin := _parse_entry(entry, warnings=warnings)) is not None)
829
+ for warning in warnings:
830
+ logger.warning("%s", warning)
831
+ metadata = raw.get("metadata") or {}
832
+ return PluginMarketplace(
833
+ name=name,
834
+ root=root,
835
+ manifest_path=manifest_path,
836
+ metadata=metadata,
837
+ plugins=plugins,
838
+ warnings=tuple(warnings),
839
+ )
840
+
841
+
842
+ def load_marketplace(root: Path) -> PluginMarketplace:
843
+ """Load a marketplace manifest from a root directory."""
844
+ manifest_path = find_marketplace_manifest(root)
845
+ if manifest_path is None:
846
+ msg = f"No marketplace manifest found under {root}"
847
+ raise MarketplaceError(msg)
848
+ return _load_marketplace_from_path(root, manifest_path)
849
+
850
+
851
+ def refresh_marketplace_catalog(record: MarketplaceRecord) -> PluginMarketplace:
852
+ """Refresh a marketplace catalog and its underlying repository cache.
853
+
854
+ For default marketplaces:
855
+ - Fetches the updated live remote catalog manifest.
856
+ - If the repository cache directory exists on disk, updates git clone to latest HEAD.
857
+ For git/github/url marketplaces:
858
+ - Re-materializes from the remote git/url source into cache.
859
+ For local directory marketplaces:
860
+ - Re-loads the marketplace from its filesystem location.
861
+
862
+ Returns:
863
+ The refreshed PluginMarketplace instance.
864
+ """
865
+ from opscloud.config.plugins import get_default_marketplace_config
866
+
867
+ cfg = get_default_marketplace_config(record.name)
868
+ install_path = Path(record.install_location)
869
+
870
+ if cfg is not None or record.is_default:
871
+ if install_path.exists():
872
+ repo_url = cfg.repository_url if cfg else record.source
873
+ ref = cfg.ref if cfg else record.ref
874
+ repo_source = RepositoryMarketplaceSource(
875
+ source_type="git",
876
+ value=repo_url,
877
+ ref=ref,
878
+ )
879
+ _clone_repository_to_cache(
880
+ repo_source,
881
+ repo_url,
882
+ cache_key=f"marketplace-git-{repo_url}",
883
+ destination=install_path,
884
+ )
885
+ return load_marketplace_location(install_path)
886
+
887
+ if record.source_type in {"git", "github", "url"}:
888
+ source_str = f"{record.source}#{record.ref}" if record.ref else record.source
889
+ source = parse_marketplace_source(source_str)
890
+ marketplace, _location = materialize_marketplace_source(source)
891
+ return marketplace
892
+
893
+ return load_marketplace_location(install_path)