skillctl-secure 0.28.0__py3-none-any.whl

skillctl/bulk_plan.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from .install_intent import aggregate_plan_intent
+from .safety_plan import build_install_plan
+
+
+_GATE_RANK = {"ALLOW": 0, "REVIEW": 1, "BLOCK": 2}
+
+
+def _max_gate(current: str, candidate: str) -> str:
+    return candidate if _GATE_RANK.get(candidate, 2) > _GATE_RANK.get(current, 2) else current
+
+
+def build_bulk_install_plan(manager, skill_names: Iterable[str]) -> dict[str, Any]:
+    """Build one read-only, fail-closed plan for multiple requested skills.
+
+    Shared dependencies are deduplicated while preserving first-seen dependency
+    order. Per-skill evidence is retained unchanged from build_install_plan().
+    """
+    requested: list[str] = []
+    seen_requested: set[str] = set()
+    for raw in skill_names:
+        name = str(raw).strip()
+        if name and name not in seen_requested:
+            seen_requested.add(name)
+            requested.append(name)
+
+    known = {spec.name for spec in manager.specs()}
+    unknown = [name for name in requested if name not in known]
+    root_plans: list[dict[str, Any]] = []
+    gate = "BLOCK" if unknown else "ALLOW"
+    gate_reasons: list[str] = [f"Unknown requested skill: {name}" for name in unknown]
+
+    ordered_steps: list[dict[str, Any]] = []
+    step_index: dict[str, dict[str, Any]] = {}
+    required_by: dict[str, list[str]] = {}
+
+    for root in requested:
+        if root not in known:
+            continue
+        plan = build_install_plan(manager, root)
+        root_plans.append(plan)
+        gate = _max_gate(gate, str(plan.get("gate", "BLOCK")))
+        gate_reasons.extend(f"{root}: {reason}" for reason in plan.get("gate_reasons", []))
+
+        for step in plan.get("steps", []):
+            skill = str(step.get("skill", ""))
+            required_by.setdefault(skill, [])
+            if root not in required_by[skill]:
+                required_by[skill].append(root)
+            if skill in step_index:
+                continue
+            copied = dict(step)
+            copied["required_by"] = required_by[skill]
+            step_index[skill] = copied
+            ordered_steps.append(copied)
+
+    # required_by lists may have grown after a shared dependency's first insertion.
+    for step in ordered_steps:
+        step["required_by"] = list(required_by.get(step["skill"], []))
+
+    mutations = [
+        {"action": step["action"], "skill": step["skill"], "destination": step["destination"]}
+        for step in ordered_steps
+        if step.get("action") == "INSTALL"
+    ]
+
+    return {
+        "schema_version": 1,
+        "operation": "BULK_INSTALL",
+        "environment": manager.active_environment,
+        "install_root": str(manager.install_dir),
+        "requested": requested,
+        "unknown_requested": unknown,
+        "gate": gate,
+        "gate_reasons": gate_reasons,
+        "mutation_count": len(mutations),
+        "mutations": mutations,
+        "intent": aggregate_plan_intent(ordered_steps),
+        "steps": ordered_steps,
+        "root_plans": [
+            {
+                "skill": plan["skill"],
+                "gate": plan["gate"],
+                "dependency_order": plan["dependency_order"],
+                "missing_dependencies": plan["missing_dependencies"],
+            }
+            for plan in root_plans
+        ],
+        "no_mutation_performed": True,
+    }
+
+
+__all__ = ["build_bulk_install_plan"]

skillctl/bulk_update.py

@@ -0,0 +1,173 @@
+"""Review and apply installed updates, preserving each skill's policy gate."""
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass, field
+import re
+
+from .operation_lock import exclusive_operation
+
+
+@dataclass
+class UpdateItem:
+    name: str
+    status: str
+    message: str = ""
+    spec: object = None
+    baseline: dict = field(default_factory=dict)
+    digest: str = ""
+    review: dict = field(default_factory=dict)
+    initial_install: bool = False
+
+
+@dataclass
+class UpdateBatch:
+    scope: tuple[str, ...]
+    items: list[UpdateItem]
+
+
+def _scope(manager):
+    store = getattr(manager, "environment_store", None)
+    active = store.load().get("active", "default") if store else "default"
+    return (str(manager.install_dir.resolve()), str(manager.state_file.resolve()), active)
+
+
+@exclusive_operation
+def review_updates(manager, names=None, progress=None) -> UpdateBatch:
+    manager.reload()
+    state = manager._load_state()
+    batch = UpdateBatch(_scope(manager), [])
+    for spec in manager.specs():
+        if names is not None and spec.name not in names:
+            continue
+        if not (manager.install_dir / spec.name).is_dir():
+            continue
+        if spec.name not in state:
+            batch.items.append(UpdateItem(spec.name, "FAILED", "Installed files have no state record. Open Doctor and recover the state record before updating.", spec=deepcopy(spec)))
+            continue
+        if progress:
+            progress(f"Checking {spec.name}…")
+        item = UpdateItem(spec.name, "SKIPPED", spec=deepcopy(spec))
+        batch.items.append(item)
+        if not spec.enabled or spec.local_path or re.fullmatch(r"[0-9a-fA-F]{7,40}", spec.ref or ""):
+            item.message = ("Disabled in the catalog." if not spec.enabled else
+                            "Local skill: managed from its local source, not a Git update." if spec.local_path else
+                            "Pinned to a commit. Unpin the skill before checking for updates.")
+            continue
+        try:
+            item.baseline = deepcopy(state[spec.name])
+            item.digest = manager._hash_tree(manager.install_dir / spec.name)
+            item.review = manager.update_review(spec)
+            target = item.review["target_commit"]
+            if target == item.baseline.get("commit"):
+                item.status, item.message = "CURRENT", "Already up to date."
+                continue
+            if not re.fullmatch(r"[0-9a-fA-F]{40}", target):
+                raise ValueError("Update did not resolve to an exact Git commit.")
+            decision = item.review["policy_after"]["decision"]
+            item.status = {"ALLOW": "READY", "REVIEW": "REVIEW"}.get(decision, "BLOCKED")
+            # The install gate also requires approval for untrusted HIGH findings.
+            if item.status == "READY" and not spec.trusted and item.review.get("audit_after", {}).get("high", 0):
+                item.status = "REVIEW"
+            item.message = "Policy: " + decision
+        except Exception as exc:
+            item.status, item.message = "FAILED", str(exc)
+    return batch
+
+
+@exclusive_operation
+def apply_updates(manager, batch: UpdateBatch, *, approve_review: bool = False, acknowledge_risk: bool = False, progress=None) -> list[dict]:
+    manager.reload()
+    if _scope(manager) != batch.scope:
+        raise RuntimeError("Environment changed; review updates again.")
+    results = []
+    for item in batch.items:
+        result = {"skill": item.name, "status": item.status, "message": item.message}
+        results.append(result)
+        denied = item.status == "BLOCKED" and item.review.get("policy_after", {}).get("decision") == "DENY"
+        if item.status not in {"READY", "REVIEW"} and not (denied and acknowledge_risk):
+            continue
+        if item.status == "REVIEW" and not approve_review:
+            result.update(status="SKIPPED", message="Explicit review approval was not granted.")
+            continue
+        try:
+            if progress:
+                progress(f"Installing {item.name}…")
+            spec = manager.get(item.name)
+            path = manager.install_dir / item.name
+            changed = (path.exists() if item.initial_install else
+                       not path.is_dir() or manager._hash_tree(path) != item.digest)
+            if spec != item.spec or manager._load_state().get(item.name) != item.baseline or changed:
+                raise RuntimeError("Installed skill or catalog changed; review again.")
+            target = item.review["target_commit"]
+            if item.initial_install:
+                missing = [name for name in spec.requires if not (manager.install_dir / name).is_dir()]
+                if missing:
+                    raise RuntimeError('Required skills were not installed: ' + ', '.join(missing))
+                if not spec.enabled:
+                    raise RuntimeError('Skill is disabled in the catalog.')
+            if item.initial_install and spec.local_path:
+                from .risk_acknowledgment import validate_receipt
+                receipt = item.review.get('risk_receipt')
+                if not receipt:
+                    raise RuntimeError('Source review is incomplete; review again.')
+                validate_receipt(manager, spec, target, spec.local_path, receipt)
+                kwargs = {'risk_acknowledgment': receipt} if denied else {}
+                installed = manager.install(spec, force=denied or (item.status == 'REVIEW' and approve_review), **kwargs)
+            elif denied:
+                receipt = item.review.get('risk_receipt')
+                if not receipt:
+                    raise RuntimeError('Risk review is incomplete. Refresh and review again.')
+                installed = manager.install_reviewed_commit(spec, target, force=True, risk_acknowledgment=receipt)
+            else:
+                installed = manager.install_reviewed_commit(spec, target, force=item.status == "REVIEW" and approve_review)
+            result.update(status="APPLIED", message=installed["commit"])
+        except Exception as exc:
+            result.update(status="FAILED", message=str(exc))
+    return results
+
+
+def format_review(batch: UpdateBatch, title="Update all — review", for_ui=False, include_diff=True) -> str:
+    lines = [title, "Only installed, enabled, unpinned remote skills are eligible.",
+             "Updates apply independently. A failure does not undo earlier successes.",
+             "REVIEW skills require the approval checkbox (CLI: --force). DENY is never overridden.", ""]
+    if for_ui:
+        lines = [title, "Check the risk acknowledgment to include policy-denied updates. This does not change global policy.", ""]
+    if not batch.items:
+        lines.append("No installed skills to update.")
+    for item in batch.items:
+        status = ({'READY':'Ready to install', 'REVIEW':'Needs approval', 'BLOCKED':'Risk acknowledgment required',
+                   'FAILED':'Check failed', 'CURRENT':'Up to date', 'SKIPPED':'Skipped'}.get(item.status,item.status)
+                  if for_ui else item.status)
+        lines.append(f"{item.name}: {status} — {item.message}")
+    for item in batch.items:
+        if item.status not in {"READY", "REVIEW", "BLOCKED"}:
+            continue
+        r = item.review
+        lines.extend(["", f"Review: {item.name}",
+                      f"Commit: {(item.baseline or {}).get('commit', '-')} → {r['target_commit']}",
+                      f"Policy: {r['policy_after']['decision']}"])
+        for reason in r['policy_after'].get('reasons', []):
+            lines.append(str(reason))
+        context = r.get('context_cost')
+        if context:
+            from .context_cost import display_tokens
+            before, after = context['before'], context['after']
+            lines.append(f"Estimated metadata tokens: {display_tokens(before['metadata_tokens'])} → {display_tokens(after['metadata_tokens'])}")
+            lines.append(f"Full instructions when used: {display_tokens(before['full_tokens'])} → {display_tokens(after['full_tokens'])} tokens")
+        audit = r.get('audit_after', {})
+        lines.append(f"Audit: HIGH {audit.get('high', 0)}, MEDIUM {audit.get('medium', 0)}, LOW {audit.get('low', 0)}")
+        for key, label in [('capabilities_added', 'Capabilities added'),
+                           ('capabilities_removed', 'Capabilities removed'),
+                           ('permission_drift_added', 'New permission drift')]:
+            lines.append(label + ': ' + (', '.join(r.get(key, [])) or 'none'))
+        lines.extend(str(x) for x in r.get('intent_delta', {}).get('summary', []))
+        for kind, paths in r.get('files', {}).items():
+            lines.append(f"Files {kind}: " + (', '.join(paths) or 'none'))
+        if include_diff and r.get('diff'):
+            lines.extend(['Diff:', r['diff']])
+    return "\n".join(lines)
+
+
+def format_results(results: list[dict]) -> str:
+    return "Update results\n\n" + ("\n".join(f"{r['skill']}: {r['status']} — {r['message']}" for r in results) or "No updates applied.")

skillctl/bulk_update_tui.py

@@ -0,0 +1,196 @@
+from textual import work
+from textual.containers import Horizontal, Vertical, VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import Button, Checkbox, Static
+
+from .bulk_update import apply_updates, format_results, format_review, review_updates
+
+
+class BulkUpdateScreen(ModalScreen):
+    """Keep network work off the UI thread and evidence visible before approval."""
+    CSS = """
+    BulkUpdateScreen { align: center middle; }
+    #bulk-dialog { width: 90%; height: 90%; border: solid $accent; padding: 1; background: $surface; }
+    #bulk-evidence { height: 1fr; }
+    #bulk-summary { height: auto; padding-bottom: 1; }
+    #bulk-buttons { height: 3; }
+    #bulk-buttons Button { width: 1fr; min-width: 0; }
+    #bulk-approve { height: auto; }
+    #bulk-diff { height: 3; min-width: 0; }
+    """
+    BINDINGS = [("escape", "cancel", "Cancel")]
+
+    def __init__(self, manager, names=None, install_name=None, collection_name=None):
+        super().__init__()
+        self.manager = manager
+        self.names = names
+        self.install_name = install_name
+        self.collection_name = collection_name
+        self.install_label = install_name or ("collection " + collection_name if collection_name else None)
+        self.review_id = 0
+        self.closed = False
+        self.completed = False
+        self.show_diff = False
+        self.batch = None
+        self.applying = False
+
+    def compose(self):
+        with Vertical(id="bulk-dialog"):
+            yield Static("Review update" if self.names else "Review all updates", id="bulk-summary", markup=False)
+            with VerticalScroll(id="bulk-evidence"):
+                yield Static("Checking installed skills and preparing update reviews…", id="bulk-text", markup=False)
+            yield Button("Show file diff", id="bulk-diff", disabled=True)
+            yield Checkbox("I acknowledge the listed risks and choose to install", id="bulk-approve", disabled=True)
+            with Horizontal(id="bulk-buttons"):
+                yield Button("Cancel", id="bulk-cancel")
+                yield Button("Review again", id="bulk-retry", disabled=True)
+                yield Button("Install updates", id="bulk-apply", variant="success", disabled=True)
+
+    def on_mount(self):
+        self.owner_app = self.app
+        self.query_one('#bulk-cancel', Button).focus()
+        self.start_review()
+
+    def start_review(self):
+        self.review_id += 1
+        self.batch = None
+        self.completed = False
+        self.show_diff = False
+        self.query_one("#bulk-diff", Button).display = False
+        self.query_one("#bulk-diff", Button).disabled = True
+        self.query_one("#bulk-approve", Checkbox).display = False
+        self.query_one("#bulk-text", Static).update("Checking sources…")
+        self.query_one("#bulk-approve", Checkbox).value = False
+        self.query_one("#bulk-approve", Checkbox).disabled = True
+        self.query_one("#bulk-apply", Button).display = True
+        self.query_one("#bulk-apply", Button).disabled = True
+        self.query_one("#bulk-retry", Button).disabled = True
+        self.query_one("#bulk-summary", Static).update("Preparing a fresh review. No installation has started.")
+        self.query_one("#bulk-cancel", Button).label = "Cancel"
+        self.prepare(self.review_id)
+
+    @work(thread=True, group="bulk-review")
+    def prepare(self, review_id):
+        try:
+            if self.collection_name:
+                from .install_review import review_collection
+                batch = review_collection(self.manager, self.collection_name, progress=self.report_progress)
+            elif self.install_name:
+                from .install_review import review_install
+                batch = review_install(self.manager, self.install_name, progress=self.report_progress)
+            else:
+                batch = review_updates(self.manager, self.names, progress=self.report_progress)
+            self.owner_app.call_from_thread(self.show_review, batch, None, review_id)
+        except Exception as exc:
+            self.owner_app.call_from_thread(self.show_review, None, str(exc), review_id)
+
+    def report_progress(self, message):
+        self.owner_app.call_from_thread(self.show_progress, message)
+
+    def show_progress(self, message):
+        if not self.closed and self.is_mounted:
+            self.query_one('#bulk-text', Static).update(message)
+
+    def show_review(self, batch, error, review_id):
+        if self.closed or not self.is_mounted or review_id != self.review_id:
+            return
+        self.batch = batch
+        self.query_one("#bulk-retry", Button).disabled = False
+        if error:
+            self.query_one('#bulk-text', Static).update(error)
+        elif batch:
+            self.render_review()
+        if error:
+            self.query_one('#bulk-summary', Static).update('Unable to complete the review. Address the error below, then choose Review again.')
+        if batch:
+            self.query_one('#bulk-evidence', VerticalScroll).scroll_home(animate=False)
+            self.query_one('#bulk-approve', Checkbox).disabled = not any(i.status in {'REVIEW', 'BLOCKED'} for i in batch.items)
+            self.update_approval()
+
+    def render_review(self):
+        title = ("Review installation: " + self.install_label if self.install_label else
+                 "Review update: " + self.names[0] if self.names else "Review all updates")
+        text = format_review(self.batch, title, for_ui=True, include_diff=self.show_diff)
+        if not self.batch.items:
+            text = ("All collection members and their dependencies are already installed." if self.collection_name else
+                    "This skill and its dependencies are already installed." if self.install_name else
+                    "No installed skills to update. Install a skill from Available to get started.")
+        self.query_one('#bulk-text', Static).update(text)
+        button = self.query_one('#bulk-diff', Button)
+        button.display = any(item.review.get('diff') for item in self.batch.items)
+        button.disabled = False
+        button.label = 'Hide file diff' if self.show_diff else 'Show file diff'
+        self.query_one('#bulk-evidence', VerticalScroll).scroll_home(animate=False)
+
+    def on_checkbox_changed(self, event: Checkbox.Changed):
+        if event.checkbox.id == 'bulk-approve' and self.batch and not self.applying and not self.completed:
+            self.update_approval()
+
+    def update_approval(self):
+        ready = sum(i.status == 'READY' for i in self.batch.items)
+        review = sum(bool(i.status == 'REVIEW' or (i.status == 'BLOCKED' and i.review.get('risk_receipt') and i.review.get('policy_after', {}).get('decision') == 'DENY')) for i in self.batch.items)
+        blocked = sum(i.status == 'BLOCKED' and not (i.review.get('risk_receipt') and i.review.get('policy_after', {}).get('decision') == 'DENY') for i in self.batch.items)
+        skipped = sum(i.status in {'CURRENT', 'SKIPPED'} for i in self.batch.items)
+        failed = sum(i.status == 'FAILED' for i in self.batch.items)
+        approved = self.query_one('#bulk-approve', Checkbox).value
+        count = ready + (review if approved else 0)
+        self.query_one('#bulk-summary', Static).update(
+            f"Ready: {ready} • Needs approval: {review} • Blocked: {blocked} • Check failed: {failed} • Unchanged: {skipped}\n"
+            + ("Acknowledge the listed risks below to enable installation. Global policy stays unchanged. " if review else "")
+            + (f"Selected for installation: {count}." if count else "No skills selected for installation."))
+        self.query_one('#bulk-approve', Checkbox).display = bool(review)
+        button = self.query_one('#bulk-apply', Button)
+        noun = 'skill' if self.install_label else 'update'
+        button.label = f'Install {noun}' if count == 1 else f'Install {count} {noun}s'
+        button.disabled = count == 0
+        button.tooltip = 'Installs only the exact commits shown in this review.'
+
+    def action_cancel(self):
+        if not self.applying:
+            self.closed = True
+            self.dismiss()
+
+    def on_button_pressed(self, event: Button.Pressed):
+        event.stop()
+        if event.button.id == 'bulk-cancel':
+            self.action_cancel()
+        elif event.button.id == 'bulk-diff' and self.batch and not self.applying and not self.completed:
+            self.show_diff = not self.show_diff
+            self.render_review()
+        elif event.button.id == 'bulk-retry' and not self.applying:
+            self.start_review()
+        elif event.button.id == 'bulk-apply' and self.batch and not self.applying:
+            self.query_one("#bulk-retry", Button).disabled = True
+            self.applying = True
+            self.query_one("#bulk-diff", Button).display = False
+            self.query_one('#bulk-apply', Button).disabled = True
+            self.query_one('#bulk-cancel', Button).disabled = True
+            checkbox = self.query_one('#bulk-approve', Checkbox)
+            checkbox.disabled = True
+            self.query_one('#bulk-summary', Static).update('Installing reviewed skills… Please wait for the results.')
+            self.query_one('#bulk-text', Static).update('Applying reviewed commits…')
+            self.apply_batch(checkbox.value)
+
+    @work(thread=True, group="bulk-apply")
+    def apply_batch(self, approved):
+        try:
+            message = format_results(apply_updates(self.manager, self.batch, approve_review=approved, acknowledge_risk=approved, progress=self.report_progress))
+        except Exception as exc:
+            message = 'Installation failed: ' + str(exc)
+        if self.install_label:
+            message = message.replace('Update results', 'Installation results', 1).replace('No updates applied.', 'No new skills installed.')
+        self.owner_app.call_from_thread(self.show_results, message)
+
+    def show_results(self, message):
+        self.applying = False
+        self.completed = True
+        self.query_one("#bulk-retry", Button).disabled = False
+        self.query_one("#bulk-summary", Static).update("Installation attempt finished. Check each result below; failed or blocked skills were not reported as installed.")
+        self.query_one("#bulk-approve", Checkbox).display = False
+        self.query_one("#bulk-apply", Button).display = False
+        self.query_one("#bulk-evidence", VerticalScroll).scroll_home(animate=False)
+        self.query_one('#bulk-text', Static).update(message)
+        button = self.query_one('#bulk-cancel', Button)
+        button.label = 'Close'
+        button.disabled = False
+        button.focus()

skillctl/cacheutil.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+import shutil
+from pathlib import Path
+
+def cache_stats(root:Path|None=None)->dict:
+    root=root or Path("~/.skillctl/cache").expanduser()
+    result={"root":str(root),"total_files":0,"total_bytes":0,"evidence_files":0,"stage_files":0}
+    if not root.exists(): return result
+    for p in root.rglob("*"):
+        if not p.is_file(): continue
+        result["total_files"]+=1
+        try: result["total_bytes"]+=p.stat().st_size
+        except OSError: pass
+        rel=str(p.relative_to(root))
+        if rel.startswith("evidence/"): result["evidence_files"]+=1
+        if rel.startswith("stages/"): result["stage_files"]+=1
+    return result
+
+def clear_cache(root:Path|None=None)->None:
+    root=root or Path("~/.skillctl/cache").expanduser()
+    if root.exists(): shutil.rmtree(root)