Repository navigation
Expand file tree
/
Copy pathcommand_add.py
More file actions
376 lines (335 loc) · 19.2 KB
/
Copy pathcommand_add.py
File metadata and controls
376 lines (335 loc) · 19.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
"""Implementation of ``specify extension add``.
Registered by ``_commands.register()``; shared command infrastructure lives in
``_commands.py``.
"""
from __future__ import annotations
from pathlib import Path
from typing import Optional
import typer
from packaging.version import InvalidVersion, Version
from rich.markup import escape as _escape_markup
from rich.panel import Panel
from .._console import console
from . import _commands
@_commands.extension_app.command("add")
def extension_add(
extension: Optional[str] = typer.Argument(None, help="Extension name or path (optional when --from is given)"),
dev: bool = typer.Option(False, "--dev", help="Install from local directory"),
from_url: Optional[str] = typer.Option(None, "--from", help="Install from custom URL"),
force: bool = typer.Option(False, "--force", help="Overwrite if already installed, and overwrite modified or unowned skill resource copies (generic replaces only recorded resources)"),
priority: int = typer.Option(10, "--priority", help="Resolution priority (lower = higher precedence, default 10)"),
version: Optional[str] = typer.Option(None, "--version", help="Install an exact version from a catalog"),
):
"""Install an extension."""
from . import ExtensionManager, ExtensionCatalog, ExtensionError, ValidationError, CompatibilityError, REINSTALL_COMMAND
# Compatibility callers invoke this function directly, in which case
# Typer supplies its OptionInfo object instead of a parsed option value.
if not isinstance(version, str):
version = None
# Same for the optional positional name when a caller omits it.
if not isinstance(extension, str):
extension = None
# The name is optional only for URL installs (``--from <url>``), where the
# archive's manifest supplies the extension ID. ``--dev`` needs a local
# path, and a catalog install needs a name to look up.
if extension is None and (dev or not from_url):
if dev:
console.print("[red]Error:[/red] --dev requires the path to a local extension directory.")
else:
console.print(
"[red]Error:[/red] Missing extension name or source. "
"Provide an extension name, or install from a URL with --from <url>."
)
console.print("\nUsage:")
console.print(" specify extension add <name>")
console.print(" specify extension add --from <url>")
console.print(" specify extension add --dev <path>")
raise typer.Exit(1)
project_root = _commands._require_specify_project()
# Validate priority
if priority < 1:
console.print("[red]Error:[/red] Priority must be a positive integer (1 or higher)")
raise typer.Exit(1)
if version is not None and (not version.strip() or dev or from_url):
console.print("[red]Error:[/red] --version requires a catalog install (without --dev or --from).")
raise typer.Exit(1)
manager = ExtensionManager(project_root)
speckit_version = _commands.get_speckit_version()
if force:
console.print("[yellow]--force:[/yellow] Will overwrite if already installed and overwrite modified or unowned skill resource copies (generic replaces only recorded resources)")
# Prompt for URL-based installs BEFORE the spinner so the user can
# actually see and respond to the confirmation (the Rich status
# spinner overwrites the typer.confirm prompt line, making it appear
# as though the command is hung).
# Guard with ``not dev`` so that --dev + --from does not show a
# confusing confirmation for a URL that will be ignored.
if from_url and not dev:
from urllib.parse import urlparse
try:
parsed = urlparse(from_url)
# Read .hostname inside the try: parsing a malformed authority -- or
# accessing .hostname on one, e.g. an invalid bracketed IPv6 host like
# "https://[not-an-ip]/x.zip" -- can raise ValueError. Keeping both the
# parse and the .hostname read inside the guard surfaces a clean
# "Invalid URL" message instead of leaking a raw traceback past the
# CLI. Reuse the value below.
hostname = parsed.hostname
parsed.port
except ValueError:
console.print(f"[red]Error:[/red] Invalid URL: {_escape_markup(from_url)}")
raise typer.Exit(1)
if not hostname:
console.print(f"[red]Error:[/red] Invalid URL: {_escape_markup(from_url)}")
raise typer.Exit(1)
if not _commands.is_https_or_localhost_http(from_url):
console.print("[red]Error:[/red] URL must use HTTPS for security.")
console.print("HTTP is only allowed for loopback URLs.")
raise typer.Exit(1)
safe_url = _escape_markup(from_url)
# Warn about untrusted sources — default-deny confirmation
console.print()
console.print(Panel(
f"[bold]You are installing an extension directly from an external URL,\n"
f"bypassing your trusted (install-allowed) extension catalogs.[/bold]\n\n"
f"URL: {safe_url}\n\n"
f"Only install extensions from sources you trust.",
title="[bold yellow]⚠ Untrusted Source[/bold yellow]",
border_style="yellow",
padding=(1, 2),
))
console.print()
confirm = typer.confirm("Continue with installation?", default=False)
if not confirm:
console.print("Cancelled")
raise typer.Exit(0)
# With ``--from`` and no name, describe the install by its source URL.
safe_extension = _escape_markup(extension if extension is not None else str(from_url))
try:
with console.status(f"[cyan]Installing extension: {safe_extension}[/cyan]"):
if dev:
# Install from local directory
source_path = Path(extension).expanduser().resolve()
safe_source_path = _escape_markup(str(source_path))
if not source_path.exists():
console.print(f"[red]Error:[/red] Directory not found: {safe_source_path}")
raise typer.Exit(1)
if not (source_path / "extension.yml").exists():
console.print(f"[red]Error:[/red] No extension.yml found in {safe_source_path}")
raise typer.Exit(1)
if force:
console.print(f"[yellow]--force:[/yellow] Installing from [cyan]{safe_source_path}[/cyan] (will overwrite if already installed and overwrite modified or unowned skill resource copies; generic replaces only recorded resources)...")
manifest = manager.install_from_directory(
source_path,
speckit_version,
priority=priority,
link_commands=True,
force=force
)
elif from_url:
# Install from URL archive via the shared hardened downloader
# (HTTPS enforcement, authenticated redirect-guarded fetch,
# bounded read, archive-format detection, TOCTOU-safe transient
# archive). Same path used by ``specify init --extension <url>``.
console.print(f"Downloading from {safe_url}...")
manifest = _commands.install_extension_from_url(
manager,
project_root,
from_url,
speckit_version,
priority=priority,
force=force,
)
else:
# Try bundled extensions first (shipped with spec-kit)
bundled_path = (
_commands._locate_bundled_extension(extension)
if version is None else None
)
if bundled_path is not None:
manifest = manager.install_from_directory(
bundled_path, speckit_version, priority=priority, force=force
)
else:
# Install from catalog (also resolves display names to IDs)
catalog = ExtensionCatalog(project_root)
# Check if extension exists in catalog (supports both ID and display name)
ext_info, catalog_error = _commands._resolve_catalog_extension(
extension, catalog, "add"
)
if catalog_error:
console.print(f"[red]Error:[/red] Could not query extension catalog: {_escape_markup(str(catalog_error))}")
raise typer.Exit(1)
if not ext_info:
console.print(f"[red]Error:[/red] Extension '{safe_extension}' not found in catalog")
console.print("\nSearch available extensions:")
console.print(" specify extension search")
raise typer.Exit(1)
if version is not None:
# Resolve within the winning catalog source. A missing
# historical release must not fall through to a lower
# priority (or discovery-only) catalog. Reuse the entry
# already resolved above rather than fetching again.
from ._catalog_versions import select_release
selected = select_release(ext_info, version)
if selected is None:
console.print(
f"[red]Error:[/red] Extension '{_escape_markup(str(ext_info['id']))}' "
f"has no catalog release for version {_escape_markup(version)}."
)
raise typer.Exit(1)
ext_info = selected
if not ext_info.get("_install_allowed", True):
console.print(
f"[red]Error:[/red] Extension '{_escape_markup(str(ext_info['id']))}' "
"is from a discovery-only catalog and cannot be installed."
)
raise typer.Exit(1)
# If catalog resolved a display name to an ID, check bundled again
resolved_id = ext_info['id']
if version is not None and ext_info.get("bundled") and not ext_info.get("download_url"):
from . import ExtensionManifest
candidate = _commands._locate_bundled_extension(resolved_id)
if candidate is not None:
bundled_manifest = ExtensionManifest(candidate / "extension.yml")
try:
packaged_matches = Version(bundled_manifest.version) == Version(
version
)
except InvalidVersion:
packaged_matches = False
if packaged_matches:
bundled_path = candidate
manifest = manager.install_from_directory(
bundled_path, speckit_version, priority=priority, force=force
)
if bundled_path is None:
console.print(
f"[red]Error:[/red] Bundled extension '{_escape_markup(resolved_id)}' "
f"version {_escape_markup(version)} is not shipped with this Spec Kit release. "
"Upgrade Spec Kit or choose an available catalog archive."
)
raise typer.Exit(1)
if version is None and resolved_id != extension:
bundled_path = _commands._locate_bundled_extension(resolved_id)
if bundled_path is not None:
manifest = manager.install_from_directory(
bundled_path, speckit_version, priority=priority, force=force
)
if bundled_path is None:
# Bundled extensions without a download URL must come from the local package
if ext_info.get("bundled") and not ext_info.get("download_url"):
console.print(
f"[red]Error:[/red] Extension '{_escape_markup(ext_info['id'])}' is bundled with spec-kit "
f"but could not be found in the installed package."
)
console.print(
"\nThis usually means the spec-kit installation is incomplete or corrupted."
)
console.print("Try reinstalling spec-kit:")
console.print(f" {REINSTALL_COMMAND}")
raise typer.Exit(1)
# Enforce install_allowed policy
if not ext_info.get("_install_allowed", True):
catalog_name = _escape_markup(str(ext_info.get("_catalog_name", "community")))
resolved_id = _commands._command_safe_id(ext_info["id"])
console.print(
f"[red]Error:[/red] '{safe_extension}' was found in the "
f"'{catalog_name}' catalog, which is discovery-only — a search "
f"surface, not an install source."
)
console.print(
"\nDiscovery-only catalogs are intentionally not installable so "
"unvetted extensions can't be pulled in without review. Don't flip "
"such a catalog to install_allowed. Instead, once you've vetted this "
"extension:"
)
console.print(
f" • install it directly from its archive URL:\n"
f" specify extension add {resolved_id} --from <archive-url>"
)
console.print(
" • or add it to a catalog you curate and control "
"(install_allowed: true)."
)
raise typer.Exit(1)
# Download extension archive (use the resolved catalog ID).
extension_id = ext_info['id']
console.print(f"Downloading {_escape_markup(str(ext_info['name']))} v{_escape_markup(str(ext_info.get('version', 'unknown')))}...")
archive_path = (
catalog.download_extension_info(ext_info)
if version is not None
else catalog.download_extension(extension_id)
)
try:
manifest = manager.install_from_zip(
archive_path,
speckit_version,
priority=priority,
force=force,
catalog_name=ext_info.get("_catalog_name"),
**(
{"expected_id": extension_id, "expected_version": version}
if version is not None else {}
),
)
finally:
archive_path.unlink(missing_ok=True)
console.print("\n[green]✓[/green] Extension installed successfully!")
console.print(f"\n[bold]{_escape_markup(str(manifest.name))}[/bold] (v{_escape_markup(str(manifest.version))})")
console.print(f" {_escape_markup(str(manifest.description))}")
# #1: regenerate native event config for installed event-capable
# integrations so the new extension's events take effect immediately.
_commands._refresh_events_and_warn(project_root)
for warning in manifest.warnings:
console.print(f"\n[yellow]⚠ Compatibility warning:[/yellow] {_escape_markup(str(warning))}")
extension_dir = manager.extensions_dir / manifest.id
provided_commands = []
missing_commands = []
for cmd in manifest.commands:
if (extension_dir / cmd["file"]).is_file():
provided_commands.append(cmd)
else:
missing_commands.append(cmd)
if provided_commands:
console.print("\n[bold cyan]Provided commands:[/bold cyan]")
for cmd in provided_commands:
cmd_name = _commands._registered_command_name(project_root, cmd["name"])
console.print(f" • {_escape_markup(str(cmd_name))} - {_escape_markup(str(cmd.get('description', '')))}")
if missing_commands:
console.print("\n[yellow]Warning:[/yellow] Command files missing:")
for cmd in missing_commands:
console.print(f" • {_escape_markup(cmd['name'])} ({_escape_markup(cmd['file'])})")
# Report agent skills registration
reg_meta = manager.registry.get(manifest.id)
reg_skills = reg_meta.get("registered_skills", []) if reg_meta else []
# Normalize to guard against corrupted registry entries
if not isinstance(reg_skills, list):
reg_skills = []
if reg_skills:
console.print(f"\n[green]✓[/green] {len(reg_skills)} agent skill(s) auto-registered")
# Scaffold config templates automatically
deployed, skipped, failed = manager.scaffold_config(manifest.id)
config_home = f".specify/extensions/{_escape_markup(str(manifest.id))}"
if deployed:
console.print("\n[bold cyan]Config scaffolded:[/bold cyan]")
for cfg in deployed:
console.print(f" • {config_home}/{_escape_markup(str(cfg))}")
if skipped:
console.print(f"\n[dim]Config files already exist (preserved): {_escape_markup(', '.join(skipped))}[/dim]")
if failed:
console.print(
f"\n[yellow]Warning:[/yellow] Config templates not scaffolded: "
f"{_escape_markup(', '.join(failed))}. "
"Verify the extension manifest and template files."
)
console.print("\n[yellow]⚠[/yellow] Configuration may be required")
console.print(f" Check: {config_home}/")
except ValidationError as e:
console.print(f"\n[red]Validation Error:[/red] {_escape_markup(str(e))}")
raise typer.Exit(1)
except CompatibilityError as e:
console.print(f"\n[red]Compatibility Error:[/red] {_escape_markup(str(e))}")
raise typer.Exit(1)
except ExtensionError as e:
console.print(f"\n[red]Error:[/red] {_escape_markup(str(e))}")
raise typer.Exit(1)