skillporter 2.0.0__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.
skillporter/cli.py ADDED
@@ -0,0 +1,1288 @@
1
+ """skillporter CLI — Complete Universal Lifecycle Manager for Agent Skills.
2
+
3
+ Commands:
4
+ init, add, install, uninstall, remove, list, search, inspect, validate,
5
+ scan, diagnose, doctor, detect, matrix, update, sync, rollback, lock,
6
+ info, pack, mcp.
7
+
8
+ Every verification command exits non-zero when it finds a real problem, so it
9
+ drops straight into CI.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import argparse
15
+ import difflib
16
+ import json
17
+ import sys
18
+ from pathlib import Path
19
+
20
+ from . import __version__, harnesses
21
+ from .diagnose import diagnose as run_diagnose
22
+ from .formats import inspect_skill_dir, render_adapted_skill
23
+ from .frontmatter import Issue, discover, parse_skill, validate
24
+ from .install import InstallError, plan_install, rollback_skill
25
+ from .install import install as run_install
26
+ from .install import uninstall as run_uninstall
27
+ from .manifest import (
28
+ LOCKFILE_FILENAME,
29
+ MANIFEST_FILENAME,
30
+ LockedSkill,
31
+ ManifestSkillSpec,
32
+ ProjectManifest,
33
+ load_lockfile,
34
+ load_manifest,
35
+ save_lockfile,
36
+ save_manifest,
37
+ )
38
+ from .mcp_server import run_mcp_stdio
39
+ from .registry import pack_skill, resolve_registry_spec, search_catalog
40
+ from .security import compute_tree_hash, scan_skill
41
+ from .sources import SourceError, resolve_source
42
+ from .state import load_state
43
+ from .ui import BOLD, CYAN, DIM, badge, style
44
+
45
+ EXIT_OK = 0
46
+ EXIT_PROBLEM = 1
47
+ EXIT_ERROR = 2
48
+
49
+
50
+ def _resolve_target_harnesses(
51
+ raw_harnesses: list[str] | None,
52
+ root: Path,
53
+ *,
54
+ scope: str = "project",
55
+ default_detected: bool = True,
56
+ ) -> list[str]:
57
+ """Resolve ``--harness`` arguments, supporting ``all`` and auto-detection."""
58
+ if raw_harnesses:
59
+ expanded: list[str] = []
60
+ for item in raw_harnesses:
61
+ for part in item.split(","):
62
+ tok = part.strip().lower()
63
+ if not tok:
64
+ continue
65
+ if tok == "all":
66
+ detected = [
67
+ d.harness.name
68
+ for d in harnesses.detect_harnesses(root)
69
+ if d.installed and (d.harness.project_paths if scope == "project" else d.harness.user_paths)
70
+ ]
71
+ if detected:
72
+ expanded.extend(detected)
73
+ else:
74
+ expanded.extend(["claude-code", "codex", "cursor"])
75
+ else:
76
+ expanded.append(harnesses.get(tok).name)
77
+ seen: list[str] = []
78
+ for h in expanded:
79
+ if h not in seen:
80
+ seen.append(h)
81
+ return seen
82
+
83
+ if default_detected:
84
+ manifest = load_manifest(root)
85
+ if manifest and manifest.harnesses:
86
+ return [harnesses.get(h).name for h in manifest.harnesses]
87
+ detected = [
88
+ d.harness.name
89
+ for d in harnesses.detect_harnesses(root)
90
+ if d.project_active and (d.harness.project_paths if scope == "project" else d.harness.user_paths)
91
+ ]
92
+ if detected:
93
+ return detected
94
+ return ["claude-code", "codex", "cursor"]
95
+
96
+
97
+ def _print_matrix(as_json: bool, category: str | None = None) -> int:
98
+ rows = []
99
+ for name in harnesses.names():
100
+ h = harnesses.get(name)
101
+ if category and h.category != category:
102
+ continue
103
+ rows.append(
104
+ {
105
+ "harness": h.name,
106
+ "display_name": h.label,
107
+ "category": h.category,
108
+ "support_status": h.support_status,
109
+ "verification_level": h.verification_level,
110
+ "verified_date": h.verified_date,
111
+ "verified": h.verified,
112
+ "recursive": h.recursive,
113
+ "project_paths": [p.path for p in h.project_paths],
114
+ "user_paths": [p.path for p in h.user_paths],
115
+ "capabilities": {
116
+ "allowed_tools": h.capabilities.allowed_tools,
117
+ "context_fork": h.capabilities.context_fork,
118
+ "hooks": h.capabilities.hooks,
119
+ "recursive": h.capabilities.recursive_discovery,
120
+ "adapted_format": h.capabilities.adapted_format,
121
+ },
122
+ "docs": h.docs,
123
+ "notes": list(h.notes),
124
+ "limitations": list(h.limitations),
125
+ }
126
+ )
127
+ if as_json:
128
+ print(json.dumps(rows, indent=2))
129
+ return EXIT_OK
130
+
131
+ print(f"skillporter {__version__} — universal harness compatibility matrix ({len(rows)} harnesses)\n")
132
+ width = max(len(r["harness"]) for r in rows)
133
+ print(f"{'HARNESS'.ljust(width)} {'SUPPORT':10} {'VERIFICATION':22} PRIMARY PROJECT PATH")
134
+ print(f"{'-' * width} {'-' * 10} {'-' * 22} {'-' * 36}")
135
+ for r in rows:
136
+ proj = r["project_paths"][0] if r["project_paths"] else "(user-only: " + ", ".join(r["user_paths"]) + ")"
137
+ if len(r["project_paths"]) > 1:
138
+ proj += f" (+{len(r['project_paths']) - 1} compat)"
139
+ print(
140
+ f"{r['harness'].ljust(width)} "
141
+ f"{r['support_status']:10} "
142
+ f"{r['verification_level']:22} "
143
+ f"{proj}"
144
+ )
145
+ print("\nNotes:")
146
+ for r in rows:
147
+ for n in r["notes"]:
148
+ print(f" {r['harness']}: {n}")
149
+ return EXIT_OK
150
+
151
+
152
+ def _cmd_diagnose(args: argparse.Namespace) -> int:
153
+ root = Path(args.path).expanduser()
154
+ if not root.exists():
155
+ print(f"error: {root} does not exist", file=sys.stderr)
156
+ return EXIT_ERROR
157
+
158
+ selected = args.harness or None
159
+ if selected and "all" in selected:
160
+ selected = harnesses.names()
161
+
162
+ diag = run_diagnose(root, only=selected, scope=args.scope)
163
+
164
+ if args.json:
165
+ payload = {
166
+ "root": str(diag.root),
167
+ "scope": args.scope,
168
+ "skills": diag.skill_names,
169
+ "drifted": diag.drifted,
170
+ "duplicates": diag.duplicates,
171
+ "harnesses": {
172
+ name: {
173
+ "verified": r.verified,
174
+ "support_status": r.support_status,
175
+ "verification_level": r.verification_level,
176
+ "reachable_skills": sorted(r.reachable_skills),
177
+ "drifted_skills": sorted(r.drifted_skills),
178
+ "duplicate_skills": r.duplicate_skills,
179
+ "locations": [
180
+ {
181
+ "path": str(loc.resolved),
182
+ "status": loc.status,
183
+ "skills": loc.skill_dirs,
184
+ "broken_links": loc.broken_links,
185
+ "skill_hashes": loc.skill_hashes,
186
+ }
187
+ for loc in r.locations
188
+ ],
189
+ }
190
+ for name, r in diag.reports.items()
191
+ },
192
+ "issues": {
193
+ path: [{"level": i.level, "code": i.code, "message": i.message} for i in issues]
194
+ for path, issues in diag.issues.items()
195
+ },
196
+ "findings": diag.findings,
197
+ }
198
+ print(json.dumps(payload, indent=2))
199
+ return EXIT_PROBLEM if diag.findings else EXIT_OK
200
+
201
+ print(f"skillporter {__version__} — diagnosing {diag.root} (scope: {args.scope})\n")
202
+ if not diag.skills:
203
+ print("no SKILL.md found under this path.")
204
+ return EXIT_PROBLEM
205
+
206
+ print(f"skills found: {', '.join(diag.skill_names)}\n")
207
+
208
+ # Show core/active harnesses in compact table unless --harness was explicitly passed
209
+ if selected:
210
+ names = [harnesses.get(h).name for h in selected]
211
+ else:
212
+ active = [
213
+ name
214
+ for name, rep in diag.reports.items()
215
+ if rep.reachable_skills or any(loc.exists for loc in rep.locations)
216
+ ]
217
+ names = sorted(set(harnesses.CORE_HARNESS_NAMES) | set(active))
218
+
219
+ width = max(max(len(s) for s in diag.skill_names), 5)
220
+ header = "SKILL".ljust(width) + " " + " ".join(n[:14].ljust(14) for n in names)
221
+ print(header)
222
+ print("-" * len(header))
223
+ for skill in diag.skill_names:
224
+ cells = []
225
+ for n in names:
226
+ state = diag.reports[n].cell_state(skill)
227
+ cells.append(state.ljust(14))
228
+ print(skill.ljust(width) + " " + " ".join(cells))
229
+
230
+ print()
231
+ if diag.findings:
232
+ print("findings:")
233
+ for f in diag.findings:
234
+ print(f" - {f}")
235
+ else:
236
+ print("no findings — every skill is reachable and synchronized across checked harnesses.")
237
+
238
+ return EXIT_PROBLEM if diag.findings else EXIT_OK
239
+
240
+
241
+ def _cmd_add(args: argparse.Namespace) -> int:
242
+ root = Path(args.path).expanduser().resolve()
243
+ try:
244
+ targets = _resolve_target_harnesses(args.harness, root, scope=args.scope, default_detected=True)
245
+ except KeyError as exc:
246
+ print(f"error: {exc}", file=sys.stderr)
247
+ return EXIT_ERROR
248
+
249
+ try:
250
+ resolved = resolve_source(args.source, base_dir=root, ref_override=args.ref or "")
251
+ except (SourceError, KeyError) as exc:
252
+ print(f"error: {exc}", file=sys.stderr)
253
+ return EXIT_ERROR
254
+
255
+ try:
256
+ skill_dirs = resolved.skill_dirs
257
+ if args.skill:
258
+ wanted = {s.strip() for s in args.skill}
259
+ skill_dirs = [d for d in skill_dirs if d.name in wanted]
260
+ if not skill_dirs:
261
+ print(f"error: requested skill(s) {sorted(wanted)} not found in {args.source}", file=sys.stderr)
262
+ return EXIT_ERROR
263
+
264
+ plan = plan_install(
265
+ root,
266
+ skill_dirs,
267
+ targets,
268
+ strategy=args.strategy,
269
+ scope=args.scope,
270
+ force=args.force,
271
+ )
272
+
273
+ # Validate & scan all discovered skills
274
+ spec_errors: list[str] = []
275
+ sec_critical = 0
276
+ sec_high = 0
277
+ sec_info = 0
278
+ sec_reports = {}
279
+ for sdir in skill_dirs:
280
+ issues = validate(parse_skill(sdir / "SKILL.md"))
281
+ for iss in issues:
282
+ if iss.level == "error":
283
+ spec_errors.append(f"{sdir.name}: {iss}")
284
+ srep = scan_skill(sdir)
285
+ sec_reports[sdir.name] = srep
286
+ sec_critical += srep.critical_count
287
+ sec_high += srep.high_count
288
+ sec_info += srep.medium_count + srep.low_count
289
+
290
+ if args.json:
291
+ if args.dry_run:
292
+ print(
293
+ json.dumps(
294
+ {
295
+ "dry_run": True,
296
+ "source": resolved.canonical_source,
297
+ "resolved_commit": resolved.resolved_commit,
298
+ "skills": [d.name for d in skill_dirs],
299
+ "harnesses": targets,
300
+ "shared_destinations": plan.shared_count,
301
+ "spec_errors": spec_errors,
302
+ "security": {k: v.to_dict() for k, v in sec_reports.items()},
303
+ },
304
+ indent=2,
305
+ )
306
+ )
307
+ return EXIT_PROBLEM if (spec_errors or sec_critical or sec_high) else EXIT_OK
308
+ else:
309
+ print(style("SKILLPORTER", BOLD, CYAN))
310
+ print(f"\nSource: {resolved.kind}:{args.source}")
311
+ if resolved.resolved_commit:
312
+ print(f"Commit: {resolved.resolved_commit[:12]}")
313
+ print("\nFound skills:")
314
+ for sdir in skill_dirs:
315
+ print(f" {sdir.name}")
316
+ print("\nTarget harnesses:")
317
+ for t in targets:
318
+ print(f" {harnesses.get(t).label} ({t})")
319
+ print("\nInstallation plan:")
320
+ print(f" {len(plan.destinations)} destination(s) across {len(targets)} harness(es)")
321
+ if plan.shared_count:
322
+ print(f" {plan.shared_count} shared destination(s) deduplicated (.agents/skills)")
323
+ val_label = "PASSED" if not spec_errors else f"FAILED ({len(spec_errors)} error(s))"
324
+ print(f"\nValidation: {badge(val_label)}")
325
+ for err in spec_errors:
326
+ print(f" - {err}")
327
+ print("\nSecurity assessment (static):")
328
+ print(f" {sec_info} informational/medium finding(s)")
329
+ print(f" {sec_critical + sec_high} critical/high finding(s)")
330
+
331
+ if (sec_critical > 0 or sec_high > 0) and not args.allow_risky and not args.force:
332
+ print(
333
+ "\nerror: installation blocked by static security policy "
334
+ "(re-run with --allow-risky after reviewing `skillporter scan` output)",
335
+ file=sys.stderr,
336
+ )
337
+ return EXIT_PROBLEM
338
+
339
+ if args.dry_run:
340
+ if not args.json:
341
+ print("\nDry run complete (no files modified).")
342
+ return EXIT_OK
343
+
344
+ if not args.json:
345
+ print("\nInstalling...\n")
346
+
347
+ all_results = []
348
+ for sdir in skill_dirs:
349
+ try:
350
+ res = run_install(
351
+ root,
352
+ sdir,
353
+ targets,
354
+ strategy=args.strategy,
355
+ scope=args.scope,
356
+ force=args.force,
357
+ source=resolved.canonical_source,
358
+ resolved_commit=resolved.resolved_commit,
359
+ record_state=True,
360
+ adapt=args.adapt,
361
+ )
362
+ all_results.extend(res)
363
+ except InstallError as exc:
364
+ print(f"error: {exc}", file=sys.stderr)
365
+ return EXIT_ERROR
366
+
367
+ # Update manifest if skillporter.yaml exists
368
+ manifest = load_manifest(root)
369
+ if manifest and args.scope == "project":
370
+ existing_names = {s.name for s in manifest.skills}
371
+ for sdir in skill_dirs:
372
+ if sdir.name not in existing_names:
373
+ manifest.skills.append(
374
+ ManifestSkillSpec(
375
+ name=sdir.name,
376
+ source=args.source,
377
+ ref=resolved.resolved_commit[:12] if resolved.resolved_commit else (args.ref or ""),
378
+ strategy=args.strategy,
379
+ harnesses=targets,
380
+ )
381
+ )
382
+ save_manifest(root, manifest)
383
+
384
+ if args.json:
385
+ print(
386
+ json.dumps(
387
+ {
388
+ "source": resolved.canonical_source,
389
+ "resolved_commit": resolved.resolved_commit,
390
+ "installed": [
391
+ {
392
+ "skill": r.skill,
393
+ "harness": r.harness,
394
+ "dest": str(r.dest),
395
+ "action": r.action,
396
+ "detail": r.detail,
397
+ }
398
+ for r in all_results
399
+ ],
400
+ },
401
+ indent=2,
402
+ )
403
+ )
404
+ return EXIT_OK
405
+
406
+ for r in all_results:
407
+ label = harnesses.get(r.harness).label
408
+ status_str = "SUCCESS" if r.action in ("created", "updated", "unchanged") else r.action.upper()
409
+ print(f"{label:22} {badge(status_str)} ({r.detail})")
410
+
411
+ print("\nInstallation verified.")
412
+ return EXIT_OK
413
+ finally:
414
+ resolved.cleanup()
415
+
416
+
417
+ def _cmd_install(args: argparse.Namespace) -> int:
418
+ root = Path(args.path).expanduser().resolve()
419
+ skill_dir = Path(args.skill).expanduser()
420
+ if not skill_dir.is_absolute():
421
+ skill_dir = (root / skill_dir).resolve()
422
+ try:
423
+ targets = _resolve_target_harnesses(args.harness, root, scope=args.scope, default_detected=False)
424
+ results = run_install(
425
+ root,
426
+ skill_dir,
427
+ targets,
428
+ strategy=args.strategy,
429
+ scope=args.scope,
430
+ force=args.force,
431
+ record_state=True,
432
+ adapt=getattr(args, "adapt", False),
433
+ )
434
+ except (InstallError, KeyError) as exc:
435
+ print(f"error: {exc}", file=sys.stderr)
436
+ return EXIT_ERROR
437
+
438
+ for r in results:
439
+ print(f"{r.action:9} {r.harness:12} {r.dest} ({r.detail})")
440
+ return EXIT_OK
441
+
442
+
443
+ def _cmd_uninstall(args: argparse.Namespace) -> int:
444
+ root = Path(args.path).expanduser().resolve()
445
+ try:
446
+ targets = _resolve_target_harnesses(
447
+ args.harness or ["all"], root, scope=args.scope, default_detected=True
448
+ )
449
+ results = run_uninstall(root, args.skill, targets, scope=args.scope, record_state=True)
450
+ except (InstallError, KeyError) as exc:
451
+ print(f"error: {exc}", file=sys.stderr)
452
+ return EXIT_ERROR
453
+ for r in results:
454
+ print(f"{r.action:9} {r.harness:12} {r.dest}")
455
+ return EXIT_OK
456
+
457
+
458
+ def _cmd_validate(args: argparse.Namespace) -> int:
459
+ target = Path(args.path).expanduser()
460
+ files = [target] if target.name == "SKILL.md" else discover(target)
461
+ if not files:
462
+ print(f"error: no SKILL.md under {target}", file=sys.stderr)
463
+ return EXIT_ERROR
464
+
465
+ problems = 0
466
+ json_out = {}
467
+ for path in files:
468
+ issues: list[Issue] = validate(parse_skill(path))
469
+ errors = [i for i in issues if i.level == "error"]
470
+ problems += len(errors)
471
+ label = path.parent.name
472
+ json_out[str(path)] = [{"level": i.level, "code": i.code, "message": i.message} for i in issues]
473
+ if not getattr(args, "json", False):
474
+ if issues:
475
+ print(f"{label}:")
476
+ for i in issues:
477
+ print(f" {i}")
478
+ else:
479
+ print(f"{label}: OK")
480
+ if getattr(args, "json", False):
481
+ print(json.dumps({"valid": problems == 0, "files": json_out}, indent=2))
482
+ return EXIT_PROBLEM if problems else EXIT_OK
483
+
484
+
485
+ def _cmd_scan(args: argparse.Namespace) -> int:
486
+ target = Path(args.path).expanduser().resolve()
487
+ if not target.exists():
488
+ print(f"error: {target} does not exist", file=sys.stderr)
489
+ return EXIT_ERROR
490
+
491
+ skill_dirs = [target] if (target / "SKILL.md").is_file() else [p.parent for p in discover(target)]
492
+ if not skill_dirs:
493
+ skill_dirs = [target]
494
+
495
+ reports = {d.name: scan_skill(d) for d in skill_dirs}
496
+ blocked = any(not r.passed for r in reports.values())
497
+
498
+ if args.json:
499
+ print(
500
+ json.dumps(
501
+ {
502
+ "passed": not blocked,
503
+ "reports": {k: v.to_dict() for k, v in reports.items()},
504
+ },
505
+ indent=2,
506
+ )
507
+ )
508
+ return EXIT_PROBLEM if blocked else EXIT_OK
509
+
510
+ print(f"skillporter {__version__} — static security assessment\n")
511
+ for sname, rep in reports.items():
512
+ verdict = "PASSED" if rep.passed else "BLOCKED"
513
+ print(f"{sname}: {badge(verdict)} (sha256: {rep.tree_hash[:12] if rep.tree_hash else 'n/a'})")
514
+ if not rep.findings:
515
+ print(" 0 findings across all scanned files.")
516
+ for f in rep.findings:
517
+ loc = f"{f.file}:{f.line}" if f.line else f.file
518
+ print(f" [{badge(f.severity)}] {f.code} ({loc}): {f.message}")
519
+ print(
520
+ style(
521
+ "\nNote: Static scanning inspects patterns and symlinks; it does not guarantee runtime safety.",
522
+ DIM,
523
+ )
524
+ )
525
+ return EXIT_PROBLEM if blocked else EXIT_OK
526
+
527
+
528
+ def _cmd_detect(args: argparse.Namespace) -> int:
529
+ root = Path(args.path).expanduser().resolve()
530
+ detected = harnesses.detect_harnesses(root, probe_versions=args.versions)
531
+ if args.json:
532
+ print(
533
+ json.dumps(
534
+ [
535
+ {
536
+ "harness": d.harness.name,
537
+ "display_name": d.harness.label,
538
+ "category": d.harness.category,
539
+ "support_status": d.harness.support_status,
540
+ "installed": d.installed,
541
+ "project_active": d.project_active,
542
+ "user_present": d.user_present,
543
+ "binary": d.binary_path,
544
+ "version": d.version,
545
+ "reasons": d.reasons,
546
+ }
547
+ for d in detected
548
+ ],
549
+ indent=2,
550
+ )
551
+ )
552
+ return EXIT_OK
553
+
554
+ print(f"skillporter {__version__} — detected harnesses in {root}\n")
555
+ width = max(len(d.harness.name) for d in detected)
556
+ print(f"{'HARNESS'.ljust(width)} {'DETECTED':8} {'WORKSPACE':9} {'SUPPORT':10} EVIDENCE")
557
+ print(f"{'-' * width} {'-' * 8} {'-' * 9} {'-' * 10} {'-' * 30}")
558
+ for d in detected:
559
+ if not args.all and not d.installed:
560
+ continue
561
+ det_str = "yes" if d.installed else "no"
562
+ ws_str = "active" if d.project_active else "-"
563
+ ev = ", ".join(d.reasons) if d.reasons else "-"
564
+ if d.version:
565
+ ev += f" ({d.version})"
566
+ print(f"{d.harness.name.ljust(width)} {det_str:8} {ws_str:9} {d.harness.support_status:10} {ev}")
567
+ return EXIT_OK
568
+
569
+
570
+ def _cmd_init(args: argparse.Namespace) -> int:
571
+ root = Path(args.path).expanduser().resolve()
572
+ root.mkdir(parents=True, exist_ok=True)
573
+ mpath = root / MANIFEST_FILENAME
574
+ if mpath.exists() and not args.force:
575
+ print(f"error: {mpath} already exists (use --force to overwrite)", file=sys.stderr)
576
+ return EXIT_ERROR
577
+
578
+ detected = [d.harness.name for d in harnesses.detect_harnesses(root) if d.project_active]
579
+ default_harnesses = detected if detected else ["claude-code", "codex", "cursor"]
580
+
581
+ existing_skills: list[ManifestSkillSpec] = []
582
+ seen: set[str] = set()
583
+ for skill_md in discover(root):
584
+ sname = skill_md.parent.name
585
+ if sname in seen:
586
+ continue
587
+ seen.add(sname)
588
+ try:
589
+ rel = skill_md.parent.resolve().relative_to(root).as_posix()
590
+ except ValueError:
591
+ rel = str(skill_md.parent)
592
+ existing_skills.append(ManifestSkillSpec(name=sname, source=f"./{rel}"))
593
+
594
+ manifest = ProjectManifest(
595
+ project=root.name or "my-project",
596
+ scope="project",
597
+ strategy="copy",
598
+ harnesses=default_harnesses,
599
+ skills=existing_skills,
600
+ )
601
+ save_manifest(root, manifest)
602
+ print(f"initialized {mpath} ({len(existing_skills)} skill(s), harnesses: {', '.join(default_harnesses)})")
603
+ return EXIT_OK
604
+
605
+
606
+ def _cmd_list(args: argparse.Namespace) -> int:
607
+ root = Path(args.path).expanduser().resolve()
608
+ records = load_state(root, scope=args.scope)
609
+ diag = run_diagnose(root, scope=args.scope)
610
+
611
+ rows = []
612
+ seen: set[str] = set()
613
+ for sname, rec in sorted(records.items()):
614
+ seen.add(sname)
615
+ rows.append(
616
+ {
617
+ "name": sname,
618
+ "version": rec.version,
619
+ "strategy": rec.strategy,
620
+ "managed": True,
621
+ "source": rec.source,
622
+ "tree_hash": rec.tree_hash[:12] if rec.tree_hash else "",
623
+ "harnesses": sorted(rec.harnesses),
624
+ }
625
+ )
626
+ for skill_md in diag.skills:
627
+ sname = skill_md.parent.name
628
+ if sname in seen:
629
+ continue
630
+ thash, _ = compute_tree_hash(skill_md.parent)
631
+ loaded_in = sorted(h for h, r in diag.reports.items() if r.loads(sname))
632
+ rel_src = (
633
+ skill_md.parent.relative_to(root)
634
+ if skill_md.parent.is_relative_to(root)
635
+ else skill_md.parent
636
+ )
637
+ rows.append(
638
+ {
639
+ "name": sname,
640
+ "version": "untracked",
641
+ "strategy": "local",
642
+ "managed": False,
643
+ "source": str(rel_src),
644
+ "tree_hash": thash[:12] if thash else "",
645
+ "harnesses": loaded_in,
646
+ }
647
+ )
648
+
649
+ if args.json:
650
+ print(json.dumps(rows, indent=2))
651
+ return EXIT_OK
652
+
653
+ if not rows:
654
+ print(f"no skills installed or discovered under {root}")
655
+ return EXIT_OK
656
+
657
+ w_name = max(max(len(str(r["name"])) for r in rows), 5)
658
+ print(f"{'SKILL'.ljust(w_name)} {'MANAGED':8} {'HASH':12} HARNESSES")
659
+ print(f"{'-' * w_name} {'-' * 8} {'-' * 12} {'-' * 35}")
660
+ for r in rows:
661
+ m_str = "yes" if r["managed"] else "no"
662
+ h_str = ", ".join(r["harnesses"]) if r["harnesses"] else "(none)"
663
+ print(f"{str(r['name']).ljust(w_name)} {m_str:8} {str(r['tree_hash']):12} {h_str}")
664
+ return EXIT_OK
665
+
666
+
667
+ def _cmd_search(args: argparse.Namespace) -> int:
668
+ results = search_catalog(args.query or "", category=args.category or "")
669
+ if args.json:
670
+ print(json.dumps([p.to_dict() for p in results], indent=2))
671
+ return EXIT_OK
672
+
673
+ if not results:
674
+ print(f"no skill packages matched query {args.query!r}")
675
+ return EXIT_OK
676
+
677
+ w_slug = max(len(p.slug) for p in results)
678
+ print(f"{'PACKAGE'.ljust(w_slug)} {'CATEGORY':18} DESCRIPTION")
679
+ print(f"{'-' * w_slug} {'-' * 18} {'-' * 44}")
680
+ for p in results:
681
+ print(f"{p.slug.ljust(w_slug)} {p.category:18} {p.description}")
682
+ return EXIT_OK
683
+
684
+
685
+ def _cmd_inspect(args: argparse.Namespace) -> int:
686
+ root = Path.cwd()
687
+ try:
688
+ resolved = resolve_source(args.source, base_dir=root)
689
+ except (SourceError, KeyError) as exc:
690
+ print(f"error: {exc}", file=sys.stderr)
691
+ return EXIT_ERROR
692
+
693
+ try:
694
+ items = []
695
+ for sdir in resolved.skill_dirs:
696
+ pkg = inspect_skill_dir(sdir)
697
+ doc = pkg.skill_doc or parse_skill(sdir / "SKILL.md")
698
+ issues = validate(doc)
699
+ sec = scan_skill(sdir)
700
+ adapted_previews = {}
701
+ if args.preview_adapt:
702
+ fmt = args.preview_adapt
703
+ rel_p, rendered = render_adapted_skill(doc, fmt)
704
+ adapted_previews[fmt] = {"path": rel_p, "content": rendered}
705
+ items.append(
706
+ {
707
+ "name": doc.name or sdir.name,
708
+ "description": doc.description,
709
+ "license": doc.frontmatter.get("license", ""),
710
+ "compatibility": doc.frontmatter.get("compatibility", ""),
711
+ "formats": pkg.detected_formats,
712
+ "scripts": pkg.scripts,
713
+ "references": pkg.references,
714
+ "assets": pkg.assets,
715
+ "validation_issues": [str(i) for i in issues],
716
+ "security": sec.to_dict(),
717
+ "adapted_previews": adapted_previews,
718
+ }
719
+ )
720
+
721
+ if args.json:
722
+ print(
723
+ json.dumps(
724
+ {
725
+ "source": resolved.canonical_source,
726
+ "kind": resolved.kind,
727
+ "resolved_commit": resolved.resolved_commit,
728
+ "skills": items,
729
+ },
730
+ indent=2,
731
+ )
732
+ )
733
+ return EXIT_OK
734
+
735
+ print(f"Source: {resolved.canonical_source} ({resolved.kind})")
736
+ if resolved.resolved_commit:
737
+ print(f"Commit: {resolved.resolved_commit}")
738
+ for item in items:
739
+ print(f"\nSkill: {style(str(item['name']), BOLD)}")
740
+ print(f" Description: {item['description']}")
741
+ print(f" Formats: {', '.join(item['formats'])}")
742
+ print(
743
+ f" Structure: {len(item['scripts'])} script(s), "
744
+ f"{len(item['references'])} reference(s), {len(item['assets'])} asset(s)"
745
+ )
746
+ sec_d = item["security"]
747
+ verdict = "PASSED" if sec_d["passed"] else "BLOCKED"
748
+ print(f" Security: {badge(verdict)} (sha256: {str(sec_d['tree_hash'])[:12]})")
749
+ if item["validation_issues"]:
750
+ print(" Validation issues:")
751
+ for iss in item["validation_issues"]:
752
+ print(f" - {iss}")
753
+ for fmt, prev in item["adapted_previews"].items():
754
+ print(f"\n Adapted preview ({fmt} -> {prev['path']}):")
755
+ for line in str(prev["content"]).splitlines()[:15]:
756
+ print(f" {line}")
757
+ return EXIT_OK
758
+ finally:
759
+ resolved.cleanup()
760
+
761
+
762
+ def _cmd_lock(args: argparse.Namespace) -> int:
763
+ root = Path(args.path).expanduser().resolve()
764
+ records = load_state(root)
765
+ lock = load_lockfile(root)
766
+
767
+ if records:
768
+ for sname, rec in sorted(records.items()):
769
+ lock.skills[sname] = LockedSkill(
770
+ name=sname,
771
+ source=rec.source,
772
+ resolved_commit=rec.resolved_commit,
773
+ version=rec.version,
774
+ tree_hash=rec.tree_hash,
775
+ strategy=rec.strategy,
776
+ installed_targets=rec.harnesses,
777
+ locked_at=rec.updated_at,
778
+ )
779
+ else:
780
+ for skill_md in discover(root):
781
+ sname = skill_md.parent.name
782
+ if sname in lock.skills:
783
+ continue
784
+ thash, _ = compute_tree_hash(skill_md.parent)
785
+ lock.skills[sname] = LockedSkill(
786
+ name=sname,
787
+ source=f"./{skill_md.parent.relative_to(root).as_posix()}",
788
+ resolved_commit="",
789
+ version="1.0.0",
790
+ tree_hash=thash,
791
+ strategy="copy",
792
+ installed_targets=[],
793
+ )
794
+
795
+ lpath = save_lockfile(root, lock)
796
+ print(f"wrote {lpath} ({len(lock.skills)} locked skill(s))")
797
+ return EXIT_OK
798
+
799
+
800
+ def _cmd_sync(args: argparse.Namespace) -> int:
801
+ root = Path(args.path).expanduser().resolve()
802
+ manifest = load_manifest(root)
803
+ targets = _resolve_target_harnesses(args.harness, root, scope=args.scope, default_detected=True)
804
+
805
+ synced_results = []
806
+ if manifest and manifest.skills:
807
+ for spec in manifest.skills:
808
+ skill_targets = spec.harnesses or manifest.harnesses or targets
809
+ strategy = spec.strategy or manifest.strategy or args.strategy
810
+ resolved = resolve_source(spec.source, base_dir=root, ref_override=spec.ref)
811
+ try:
812
+ for sdir in resolved.skill_dirs:
813
+ if sdir.name != spec.name and len(resolved.skill_dirs) > 1:
814
+ continue
815
+ res = run_install(
816
+ root,
817
+ sdir,
818
+ skill_targets,
819
+ strategy=strategy,
820
+ scope=args.scope,
821
+ force=True,
822
+ source=resolved.canonical_source,
823
+ resolved_commit=resolved.resolved_commit,
824
+ record_state=True,
825
+ )
826
+ synced_results.extend(res)
827
+ finally:
828
+ resolved.cleanup()
829
+ else:
830
+ # Discover canonical skills in the repo and synchronize across target harnesses
831
+ canonical_by_name: dict[str, Path] = {}
832
+ for skill_md in discover(root):
833
+ sname = skill_md.parent.name
834
+ if sname not in canonical_by_name:
835
+ canonical_by_name[sname] = skill_md.parent
836
+
837
+ if not canonical_by_name:
838
+ print(f"no skills or {MANIFEST_FILENAME} found under {root}")
839
+ return EXIT_PROBLEM
840
+
841
+ for _sname, sdir in sorted(canonical_by_name.items()):
842
+ res = run_install(
843
+ root,
844
+ sdir,
845
+ targets,
846
+ strategy=args.strategy,
847
+ scope=args.scope,
848
+ force=True,
849
+ source=str(sdir),
850
+ record_state=True,
851
+ )
852
+ synced_results.extend(res)
853
+
854
+ # Update lockfile automatically if present or if manifest exists
855
+ if (root / LOCKFILE_FILENAME).exists() or manifest is not None:
856
+ _cmd_lock(argparse.Namespace(path=str(root)))
857
+
858
+ for r in synced_results:
859
+ print(f"{r.action:9} {r.harness:16} {r.dest}")
860
+ return EXIT_OK
861
+
862
+
863
+ def _cmd_update(args: argparse.Namespace) -> int:
864
+ root = Path(args.path).expanduser().resolve()
865
+ records = load_state(root, scope=args.scope)
866
+ if not records:
867
+ print("no managed skills recorded in .skillporter/state.json to update.")
868
+ return EXIT_OK
869
+
870
+ names = [args.skill] if args.skill else sorted(records)
871
+ updated_count = 0
872
+ for sname in names:
873
+ rec = records.get(sname)
874
+ if not rec:
875
+ print(f"error: skill {sname!r} is not tracked by skillporter", file=sys.stderr)
876
+ return EXIT_ERROR
877
+ resolved = resolve_source(rec.source, base_dir=root)
878
+ try:
879
+ matching = [d for d in resolved.skill_dirs if d.name == sname] or resolved.skill_dirs
880
+ for sdir in matching:
881
+ res = run_install(
882
+ root,
883
+ sdir,
884
+ rec.harnesses or ["claude-code", "codex", "cursor"],
885
+ strategy=rec.strategy,
886
+ scope=rec.scope,
887
+ force=True,
888
+ source=resolved.canonical_source,
889
+ resolved_commit=resolved.resolved_commit,
890
+ record_state=True,
891
+ )
892
+ updated_count += 1
893
+ for r in res:
894
+ print(f"updated {r.harness:16} {r.dest}")
895
+ finally:
896
+ resolved.cleanup()
897
+ return EXIT_OK if updated_count >= 0 else EXIT_PROBLEM
898
+
899
+
900
+ def _cmd_rollback(args: argparse.Namespace) -> int:
901
+ root = Path(args.path).expanduser().resolve()
902
+ try:
903
+ results = rollback_skill(
904
+ root,
905
+ args.skill,
906
+ backup_id=args.backup_id or "",
907
+ scope=args.scope,
908
+ )
909
+ except InstallError as exc:
910
+ print(f"error: {exc}", file=sys.stderr)
911
+ return EXIT_ERROR
912
+
913
+ for r in results:
914
+ print(f"{r.action:12} {r.harness:16} {r.dest} ({r.detail})")
915
+ return EXIT_OK
916
+
917
+
918
+ def _cmd_doctor(args: argparse.Namespace) -> int:
919
+ root = Path(args.path).expanduser().resolve()
920
+ diag = run_diagnose(root, only=args.harness or None, scope=args.scope)
921
+ detected = [d for d in harnesses.detect_harnesses(root) if d.installed]
922
+
923
+ if args.fix and diag.skills:
924
+ # Remove broken symlinks first
925
+ for rep in diag.reports.values():
926
+ for loc in rep.locations:
927
+ for blink in loc.broken_links:
928
+ bp = Path(blink)
929
+ if bp.is_symlink():
930
+ bp.unlink(missing_ok=True)
931
+ # Re-sync discovered skills across active/checked harnesses
932
+ active_proj = {d.harness.name for d in detected if d.project_active}
933
+ targets = args.harness or sorted({"claude-code", "codex", "cursor"} | active_proj)
934
+ for skill_md in diag.skills:
935
+ run_install(
936
+ root,
937
+ skill_md.parent,
938
+ targets,
939
+ strategy="copy",
940
+ scope=args.scope,
941
+ force=True,
942
+ record_state=True,
943
+ )
944
+ diag = run_diagnose(root, only=targets, scope=args.scope)
945
+
946
+ if args.json:
947
+ print(
948
+ json.dumps(
949
+ {
950
+ "root": str(root),
951
+ "detected_harnesses": [d.harness.name for d in detected],
952
+ "skills": diag.skill_names,
953
+ "drifted": diag.drifted,
954
+ "findings": diag.findings,
955
+ "healthy": len(diag.findings) == 0,
956
+ },
957
+ indent=2,
958
+ )
959
+ )
960
+ return EXIT_PROBLEM if diag.findings else EXIT_OK
961
+
962
+ print(f"skillporter {__version__} — doctor report for {root}\n")
963
+ print(f"Detected harnesses: {', '.join(d.harness.name for d in detected) or '(none)'}")
964
+ print(f"Discovered skills: {', '.join(diag.skill_names) or '(none)'}")
965
+ print(f"Content drift: {len(diag.drifted)} skill(s)")
966
+ if diag.findings:
967
+ print("\nIssues found:")
968
+ for f in diag.findings:
969
+ print(f" - {f}")
970
+ if not args.fix:
971
+ print("\nTip: run `skillporter doctor --fix` or `skillporter sync` to repair reachability and drift.")
972
+ return EXIT_PROBLEM
973
+ print("\nStatus: HEALTHY (all checked skills reachable, valid, and in sync).")
974
+ return EXIT_OK
975
+
976
+
977
+ def _cmd_info(args: argparse.Namespace) -> int:
978
+ target = args.target.strip()
979
+ # 1. Check if target is a known harness adapter
980
+ try:
981
+ h = harnesses.get(target)
982
+ payload = {
983
+ "type": "harness",
984
+ "id": h.name,
985
+ "display_name": h.label,
986
+ "category": h.category,
987
+ "support_status": h.support_status,
988
+ "verification_level": h.verification_level,
989
+ "verified_date": h.verified_date,
990
+ "docs": h.docs,
991
+ "project_paths": [p.path for p in h.project_paths],
992
+ "user_paths": [p.path for p in h.user_paths],
993
+ "notes": list(h.notes),
994
+ "limitations": list(h.limitations),
995
+ }
996
+ if args.json:
997
+ print(json.dumps(payload, indent=2))
998
+ return EXIT_OK
999
+ print(f"Harness: {h.label} ({h.name})")
1000
+ print(f"Category: {h.category}")
1001
+ print(f"Support: {h.support_status} ({h.verification_level}, verified {h.verified_date})")
1002
+ print(f"Docs: {h.docs}")
1003
+ print(f"Project paths: {', '.join(p.path for p in h.project_paths) or '(none)'}")
1004
+ print(f"User paths: {', '.join(p.path for p in h.user_paths) or '(none)'}")
1005
+ for n in h.notes:
1006
+ print(f"Note: {n}")
1007
+ for lim in h.limitations:
1008
+ print(f"Limitation: {lim}")
1009
+ return EXIT_OK
1010
+ except KeyError:
1011
+ pass
1012
+
1013
+ # 2. Check registry catalog
1014
+ try:
1015
+ pkg = resolve_registry_spec(target)
1016
+ if args.json:
1017
+ print(json.dumps(pkg.to_dict(), indent=2))
1018
+ return EXIT_OK
1019
+ print(f"Package: {pkg.slug} (v{pkg.version})")
1020
+ print(f"Publisher: {pkg.publisher}")
1021
+ print(f"Category: {pkg.category}")
1022
+ print(f"License: {pkg.license}")
1023
+ print(f"Source: {pkg.source}")
1024
+ print(f"Description: {pkg.description}")
1025
+ print(f"Harnesses: {', '.join(pkg.verified_harnesses)}")
1026
+ print(f"\nInstall: skillporter add {pkg.slug}")
1027
+ return EXIT_OK
1028
+ except KeyError:
1029
+ print(f"error: {target!r} is neither a registered harness nor a known registry package", file=sys.stderr)
1030
+ return EXIT_ERROR
1031
+
1032
+
1033
+ def _cmd_pack(args: argparse.Namespace) -> int:
1034
+ skill_dir = Path(args.path).expanduser().resolve()
1035
+ out_dir = Path(args.out).expanduser().resolve()
1036
+ try:
1037
+ rel = pack_skill(skill_dir, out_dir)
1038
+ except ValueError as exc:
1039
+ print(f"error: {exc}", file=sys.stderr)
1040
+ return EXIT_ERROR
1041
+ if args.json:
1042
+ print(
1043
+ json.dumps(
1044
+ {
1045
+ "skill": rel.skill_name,
1046
+ "version": rel.version,
1047
+ "archive": str(rel.archive_path),
1048
+ "provenance": str(rel.provenance_path),
1049
+ "archive_sha256": rel.archive_sha256,
1050
+ "tree_hash": rel.tree_hash,
1051
+ },
1052
+ indent=2,
1053
+ )
1054
+ )
1055
+ return EXIT_OK
1056
+ print(f"packed {rel.skill_name}@{rel.version}:")
1057
+ print(f" archive: {rel.archive_path} (sha256: {rel.archive_sha256[:16]}...)")
1058
+ print(f" provenance: {rel.provenance_path}")
1059
+ return EXIT_OK
1060
+
1061
+
1062
+ def build_parser() -> argparse.ArgumentParser:
1063
+ p = argparse.ArgumentParser(
1064
+ prog="skillporter",
1065
+ description=(
1066
+ "ONE SKILL. EVERY AGENT. Universal package manager, validator, security scanner, "
1067
+ "and cross-harness synchronizer for AI-agent skills."
1068
+ ),
1069
+ )
1070
+ p.add_argument("--version", action="version", version=f"skillporter {__version__}")
1071
+ sub = p.add_subparsers(dest="command", required=False)
1072
+
1073
+ # diagnose
1074
+ d = sub.add_parser("diagnose", help="show which harnesses can actually see each skill, plus drift & broken links")
1075
+ d.add_argument("path", nargs="?", default=".", help="repo root (default: .)")
1076
+ d.add_argument("--harness", action="append", help="limit to specific harness(es) or 'all' (repeatable)")
1077
+ d.add_argument("--scope", choices=["project", "user"], default="project")
1078
+ d.add_argument("--json", action="store_true", help="machine-readable output")
1079
+ d.set_defaults(func=_cmd_diagnose)
1080
+
1081
+ # add (flagship universal installer)
1082
+ a = sub.add_parser("add", help="install skills from GitHub, git URL, archive, registry, or local path")
1083
+ a.add_argument("source", help="owner/repo, GitHub URL, archive, or local path")
1084
+ a.add_argument("--harness", action="append", help="target harness or 'all' (repeatable)")
1085
+ a.add_argument("--skill", action="append", help="select specific skill name(s) from a multi-skill repo")
1086
+ a.add_argument("--ref", help="git branch, tag, or commit hash")
1087
+ a.add_argument("--strategy", choices=["copy", "symlink"], default="copy")
1088
+ a.add_argument("--scope", choices=["project", "user"], default="project")
1089
+ a.add_argument("--path", default=".", help="repo root (default: .)")
1090
+ a.add_argument("--adapt", action="store_true", help="also emit adapted rule files (.mdc, .instructions.md)")
1091
+ a.add_argument("--dry-run", action="store_true", help="plan, validate, and scan without writing files")
1092
+ a.add_argument(
1093
+ "--allow-risky",
1094
+ action="store_true",
1095
+ help="proceed even if static security scan finds high/critical issues",
1096
+ )
1097
+ a.add_argument("--force", action="store_true", help="overwrite existing installations")
1098
+ a.add_argument("--json", action="store_true", help="machine-readable output")
1099
+ a.set_defaults(func=_cmd_add)
1100
+
1101
+ # install (local path installer)
1102
+ i = sub.add_parser("install", help="install a local skill directory into one or more harnesses")
1103
+ i.add_argument("skill", help="path to the skill directory")
1104
+ i.add_argument("--harness", action="append", required=True, help="target harness (repeatable)")
1105
+ i.add_argument(
1106
+ "--strategy",
1107
+ choices=["copy", "symlink"],
1108
+ default="copy",
1109
+ help="copy (portable, Docker/CI safe) or symlink (single source of truth)",
1110
+ )
1111
+ i.add_argument("--scope", choices=["project", "user"], default="project")
1112
+ i.add_argument("--path", default=".", help="repo root (default: .)")
1113
+ i.add_argument("--adapt", action="store_true", help="also emit adapted harness rule file")
1114
+ i.add_argument("--force", action="store_true", help="overwrite an existing install")
1115
+ i.set_defaults(func=_cmd_install)
1116
+
1117
+ # uninstall / remove
1118
+ for cmd_name in ("uninstall", "remove"):
1119
+ u = sub.add_parser(cmd_name, help="remove a skill from harnesses")
1120
+ u.add_argument("skill", help="skill name")
1121
+ u.add_argument("--harness", action="append", required=(cmd_name == "uninstall"))
1122
+ u.add_argument("--scope", choices=["project", "user"], default="project")
1123
+ u.add_argument("--path", default=".")
1124
+ u.set_defaults(func=_cmd_uninstall)
1125
+
1126
+ # validate
1127
+ v = sub.add_parser("validate", help="validate SKILL.md files against the Agent Skills spec")
1128
+ v.add_argument("path", nargs="?", default=".")
1129
+ v.add_argument("--json", action="store_true")
1130
+ v.set_defaults(func=_cmd_validate)
1131
+
1132
+ # scan
1133
+ sc = sub.add_parser("scan", help="run static security and supply-chain checks on skills")
1134
+ sc.add_argument("path", nargs="?", default=".")
1135
+ sc.add_argument("--json", action="store_true")
1136
+ sc.set_defaults(func=_cmd_scan)
1137
+
1138
+ # matrix
1139
+ m = sub.add_parser("matrix", help="print the 19-harness compatibility matrix")
1140
+ m.add_argument("--category", choices=["coding", "autonomous"])
1141
+ m.add_argument("--json", action="store_true")
1142
+ m.set_defaults(func=lambda a: _print_matrix(a.json, getattr(a, "category", None)))
1143
+
1144
+ # detect
1145
+ dt = sub.add_parser("detect", help="detect installed AI agent harnesses on this machine and workspace")
1146
+ dt.add_argument("path", nargs="?", default=".")
1147
+ dt.add_argument("--all", action="store_true", help="include harnesses not currently detected")
1148
+ dt.add_argument("--versions", action="store_true", help="probe CLI versions where available")
1149
+ dt.add_argument("--json", action="store_true")
1150
+ dt.set_defaults(func=_cmd_detect)
1151
+
1152
+ # init
1153
+ init_p = sub.add_parser("init", help="initialize skillporter.yaml in a project")
1154
+ init_p.add_argument("path", nargs="?", default=".")
1155
+ init_p.add_argument("--force", action="store_true")
1156
+ init_p.set_defaults(func=_cmd_init)
1157
+
1158
+ # list
1159
+ ls_p = sub.add_parser("list", help="list installed and discovered skills")
1160
+ ls_p.add_argument("path", nargs="?", default=".")
1161
+ ls_p.add_argument("--scope", choices=["project", "user"], default="project")
1162
+ ls_p.add_argument("--json", action="store_true")
1163
+ ls_p.set_defaults(func=_cmd_list)
1164
+
1165
+ # search
1166
+ sr = sub.add_parser("search", help="search the skill registry catalog")
1167
+ sr.add_argument("query", nargs="?", default="")
1168
+ sr.add_argument("--category", default="")
1169
+ sr.add_argument("--json", action="store_true")
1170
+ sr.set_defaults(func=_cmd_search)
1171
+
1172
+ # inspect
1173
+ ins = sub.add_parser("inspect", help="inspect a local or remote skill package before installing")
1174
+ ins.add_argument("source", help="local path, archive, or GitHub owner/repo")
1175
+ ins.add_argument(
1176
+ "--preview-adapt",
1177
+ choices=["cursor-mdc", "copilot-instructions", "windsurf-rules", "continue-rules", "aider-conventions"],
1178
+ )
1179
+ ins.add_argument("--json", action="store_true")
1180
+ ins.set_defaults(func=_cmd_inspect)
1181
+
1182
+ # sync
1183
+ sy = sub.add_parser("sync", help="synchronize skills across harnesses or from skillporter.yaml")
1184
+ sy.add_argument("path", nargs="?", default=".")
1185
+ sy.add_argument("--harness", action="append")
1186
+ sy.add_argument("--strategy", choices=["copy", "symlink"], default="copy")
1187
+ sy.add_argument("--scope", choices=["project", "user"], default="project")
1188
+ sy.set_defaults(func=_cmd_sync)
1189
+
1190
+ # update
1191
+ up = sub.add_parser("update", help="update managed skills from their tracked sources")
1192
+ up.add_argument("skill", nargs="?", default="")
1193
+ up.add_argument("--scope", choices=["project", "user"], default="project")
1194
+ up.add_argument("--path", default=".")
1195
+ up.set_defaults(func=_cmd_update)
1196
+
1197
+ # rollback
1198
+ rb = sub.add_parser("rollback", help="restore a skill to its previous backup snapshot")
1199
+ rb.add_argument("skill", help="skill name to roll back")
1200
+ rb.add_argument("--backup-id", default="")
1201
+ rb.add_argument("--scope", choices=["project", "user"], default="project")
1202
+ rb.add_argument("--path", default=".")
1203
+ rb.set_defaults(func=_cmd_rollback)
1204
+
1205
+ # lock
1206
+ lk = sub.add_parser("lock", help="generate or update deterministic skillporter.lock")
1207
+ lk.add_argument("path", nargs="?", default=".")
1208
+ lk.set_defaults(func=_cmd_lock)
1209
+
1210
+ # doctor
1211
+ doc = sub.add_parser("doctor", help="run comprehensive health check (and optional --fix repair)")
1212
+ doc.add_argument("path", nargs="?", default=".")
1213
+ doc.add_argument("--harness", action="append")
1214
+ doc.add_argument("--scope", choices=["project", "user"], default="project")
1215
+ doc.add_argument("--fix", action="store_true", help="auto-repair missing/drifted installs and broken symlinks")
1216
+ doc.add_argument("--json", action="store_true")
1217
+ doc.set_defaults(func=_cmd_doctor)
1218
+
1219
+ # info
1220
+ inf = sub.add_parser("info", help="show detailed metadata for a harness adapter or registry package")
1221
+ inf.add_argument("target", help="harness ID (e.g. cursor) or package slug (e.g. anthropics/skills)")
1222
+ inf.add_argument("--json", action="store_true")
1223
+ inf.set_defaults(func=_cmd_info)
1224
+
1225
+ # pack
1226
+ pk = sub.add_parser("pack", help="build an immutable .tar.gz release bundle and SHA-256 provenance manifest")
1227
+ pk.add_argument("path", nargs="?", default=".")
1228
+ pk.add_argument("--out", default=".skillporter/dist")
1229
+ pk.add_argument("--json", action="store_true")
1230
+ pk.set_defaults(func=_cmd_pack)
1231
+
1232
+ # mcp
1233
+ mcp_p = sub.add_parser("mcp", help="run the stdio Model Context Protocol (MCP) server for agent harnesses")
1234
+ mcp_p.set_defaults(func=lambda _a: run_mcp_stdio())
1235
+
1236
+ return p
1237
+
1238
+
1239
+ KNOWN_COMMANDS = (
1240
+ "diagnose",
1241
+ "add",
1242
+ "install",
1243
+ "uninstall",
1244
+ "remove",
1245
+ "validate",
1246
+ "scan",
1247
+ "matrix",
1248
+ "detect",
1249
+ "init",
1250
+ "list",
1251
+ "search",
1252
+ "inspect",
1253
+ "sync",
1254
+ "update",
1255
+ "rollback",
1256
+ "lock",
1257
+ "doctor",
1258
+ "info",
1259
+ "pack",
1260
+ "mcp",
1261
+ )
1262
+
1263
+
1264
+ def main(argv: list[str] | None = None) -> int:
1265
+ args_list = list(sys.argv[1:] if argv is None else argv)
1266
+ parser = build_parser()
1267
+
1268
+ if not args_list:
1269
+ parser.print_help()
1270
+ return EXIT_OK
1271
+
1272
+ # Helpful typo suggestion when an unknown command is given
1273
+ first = args_list[0]
1274
+ if not first.startswith("-") and first not in KNOWN_COMMANDS:
1275
+ matches = difflib.get_close_matches(first, KNOWN_COMMANDS, n=2, cutoff=0.5)
1276
+ hint = f" (did you mean: {', '.join(matches)}?)" if matches else ""
1277
+ print(f"error: unknown command {first!r}{hint}", file=sys.stderr)
1278
+ return EXIT_ERROR
1279
+
1280
+ args = parser.parse_args(args_list)
1281
+ if not getattr(args, "command", None):
1282
+ parser.print_help()
1283
+ return EXIT_OK
1284
+ return int(args.func(args))
1285
+
1286
+
1287
+ if __name__ == "__main__":
1288
+ raise SystemExit(main())