skilldrop-cli 0.16.31 → 0.16.33

package/packs/dev-team/skills/dependency-upgrade-review/reference.md

@@ -1,6 +1,6 @@
 # dependency-upgrade-review reference
 
-Long-form material for the steps in `SKILL.md`: what each ecosystem's diff shows, where the risky signals live, how to list the releases between two versions, how to verify a pin, and how to roll back.
+Long-form material for the steps in `SKILL.md`: what each ecosystem's diff shows, where the risky signals live, how to list the releases between two versions, how to trace a behaviour change to its callers, where runtime floors bite, how to verify a pin, and how to roll back.
 
 ## Reading a lockfile diff, by ecosystem
 
@@ -44,6 +44,36 @@ What to pull from each release, in this order:
 3. **Deprecations:** still works, removed later. A deprecated call the repo makes is a 🟧, not a 🟥.
 4. **Licence:** a changed `license` field or a LICENSE file change. Moves between permissive licences (MIT, BSD, Apache-2.0, ISC) are a note. A move to a copyleft licence (GPL, AGPL, MPL at file level, LGPL) or a source-available licence (BUSL, SSPL, Elastic, "Commons Clause") needs a sign-off from whoever owns licence policy before merge.
 
+## Tracing a behaviour change to its callers
+
+A search hit is where the review starts. Read the calling function and write what it does under the new version.
+
+| Change in the notes | What to look for in the caller | What breaks |
+|---|---|---|
+| Returns `None` / `-1` / `false` → raises | `if result is None`, `== -1`, `if not ok` branches; retry loops and fallbacks built on them | The branch never runs; the first failure escapes as an exception and the retry or fallback is dead code |
+| Raises → returns a sentinel | `try` / `except` around the call | The error is swallowed; the code carries on with the sentinel |
+| Exception class renamed or re-parented | `except OldError`, `catch (e instanceof OldError)` | The handler stops catching it |
+| Tuple or dict → object | `a, b = f(...)`, `result["key"]` | Unpacking or key access fails at runtime |
+| Changed default | Every call that does not pass the option | Each one gets the new behaviour silently |
+| Module or function removed | Imports at the top of a file, and imports inside functions | A top-level import fails at startup and in tests; an import inside a function fails only when that function runs |
+
+Name the fix in the repo's code, and any migration aid an intermediate release ships (an opt-in flag that turns on the new behaviour early). Moving to that release first lets the code change land and be tested before the major.
+
+## Runtime floors
+
+A release that drops a runtime version breaks wherever the old runtime still runs, and CI usually runs a newer one.
+
+| Floor raised in | Compare with |
+|---|---|
+| Release notes ("requires Python 3.10"), `python_requires`, `python-versions` in `poetry.lock`, `requires-python` in `uv.lock` | Dockerfile `FROM`, `setup-python` version and matrix, `.python-version`, the Python the lockfile was compiled on |
+| `engines.node` in `package-lock.json` or `package.json` | `.nvmrc`, `setup-node` / toolchain version, Dockerfile `FROM`, `engine-strict` in `.npmrc` |
+| `go` directive in `go.mod`, `toolchain` line | `setup-go` version, Dockerfile builder image |
+| `rust-version` (MSRV) in a crate | `rust-toolchain.toml`, CI toolchain |
+| Wheels or prebuilt binaries only for some versions or platforms | Every image and runner that installs it; elsewhere it builds from source and needs a compiler or toolchain |
+| An action's runtime (`node20` → `node24`) | Self-hosted runner versions; GitHub-hosted runners update themselves |
+
+A lockfile generated on a newer runtime than production can resolve versions production cannot install. `pip install --require-hashes` and `npm ci` fail at build time, not at review time.
+
 ## Verifying a pin
 
 ```bash
@@ -57,6 +87,7 @@ git ls-remote https://github.com/<owner>/<repo> refs/tags/<tag> 'refs/tags/<tag>
 - A SHA with no `# vX.Y.Z` comment: list the tags (`git ls-remote --tags https://github.com/<owner>/<repo>`) and find the SHA. No tag points to it means it is not a release.
 - Tag-only pin (`uses: owner/repo@v3`): the maintainer, or anyone who takes over the account, can point `v3` at new code after review. Pin to the commit the `^{}` line returns and keep the tag as a comment.
 - Branch pin (`@main`): every run gets whatever was pushed last. A PR that introduces one is DO NOT MERGE.
+- Two SHAs for one tag: when the same `owner/repo` and `# vX.Y.Z` comment appear with different SHAs across workflow files, at most one is the tag's commit. Run the command once and compare both; until then, the PR is DO NOT MERGE. Read the PR's commit list: a bot writes every pin the same way, so a pin that differs from the bot's usually came from a hand-made commit.
 
 Stakes come from the job, not the action: look at `permissions:` (`contents: write`, `id-token: write`, `packages: write`), the `secrets.*` it receives, and the `environment:` it runs in.
 
@@ -70,6 +101,10 @@ Stakes come from the job, not the action: look at `permissions:` (`contents: wri
 | A build or publish step (bundler, packager, uploader) not in the PR workflow | No |
 | A source file no test imports | No |
 | A test that imports the file but never hits the changed behaviour (a default, an edge case the notes name) | Not the part that changed |
+| A test that mocks the dependency with the old contract (a fake that returns a value where the new version raises) | No; it tests the old behaviour |
+| An import inside a function no test calls | No; it never fails at import or collection |
+| An install script, when the PR job installs with `--ignore-scripts` and the release job does not | No; it first runs in the release job, with that job's secrets and permissions |
+| A runtime older than the one CI uses (production image, self-hosted runner) | No |
 
 Ways to exercise an unrun path before merge: a `workflow_dispatch` dry run on the PR branch, a release to a test index (TestPyPI, a scratch npm scope), or a test that covers the changed behaviour, added in the same PR.
 

package/packs/dev-team/skills/dependency-upgrade-review/scripts/upgrade_diff.py

@@ -161,6 +161,7 @@ def host_of(url):
 class Report:
     def __init__(self):
         self.changes, self.flags, self.files, self.unattributed = [], [], [], {}
+        self.sha_pins = {}  # (repo, tag) -> {sha: [files]}, from added `uses:` lines
 
     def change(self, path, eco, where, name, old, new, note=None):
         if old == new:
@@ -256,6 +257,12 @@ def merge_blocks(rep, path, eco, hunks, key_fn, field_res, name_fn, reset_re=Non
                     rep.flag("source", path, f"{label}: {f} moved from {oh} to {nh}")
                 elif nh and not o and f != "index" and nh not in DEFAULT_HOSTS:
                     rep.flag("source", path, f"{label}: new package comes from {nh}, not the default registry")
+            for f in ("node", "python-versions"):
+                orv, nrv = of.get(f, (None,))[0], nf.get(f, (None,))[0]
+                if o and nrv and orv != nrv:
+                    rt = "Node" if f == "node" else "Python"
+                    rep.flag("runtime", path, f"{label}: requires {rt} {nrv} (was {orv or 'unstated'}); check every "
+                                              f"place it installs and runs (base images, CI versions, runners)")
             ol, nl = of.get("license", (None,))[0], nf.get("license", (None,))[0]
             if ol and nl and ol != nl:
                 rep.flag("licence", path, f"{label}: licence changed from {ol} to {nl}")
@@ -317,7 +324,7 @@ def npm_lock_name(key):
 
 
 NPM_FIELDS = {f: re.compile(rf'^\s*"{f}":\s*"?([^",]+)"?,?\s*$') for f in
-              ("version", "resolved", "license", "hasInstallScript", "dev", "optional", "gypfile")}
+              ("version", "resolved", "license", "hasInstallScript", "dev", "optional", "gypfile", "node")}
 
 
 def h_package_lock(rep, path, hunks):
@@ -360,7 +367,8 @@ def h_pnpm_lock(rep, path, hunks):
 
 TOML_PKG_FIELDS = {"version": re.compile(r'^version\s*=\s*"([^"]+)"'),
                    "source": re.compile(r'^source\s*=\s*"([^"]+)"'),
-                   "url": re.compile(r'^(?:url|source\s*=\s*\{\s*(?:registry|git|url))\s*=\s*"([^"]+)"')}
+                   "url": re.compile(r'^(?:url|source\s*=\s*\{\s*(?:registry|git|url))\s*=\s*"([^"]+)"'),
+                   "python-versions": re.compile(r'^python-versions\s*=\s*"([^"]+)"')}
 
 
 def h_toml_lock(eco):
@@ -527,6 +535,7 @@ def h_workflow(rep, path, hunks):
             if n and SHA40.fullmatch(n[0]):
                 tag_ = re.match(r"^(v?[\w.\-]+)", n[1]).group(1) if n[1] else None
                 if tag_:
+                    rep.sha_pins.setdefault((repo, tag_), {}).setdefault(n[0], []).append(path)
                     rep.flag("pin", path, f"{name}@{n[0]} claims {tag_}. UNVERIFIED until the tag resolves to this commit: "
                                           f"`git ls-remote https://github.com/{repo} refs/tags/{tag_} 'refs/tags/{tag_}^{{}}'` "
                                           f"(the `^{{}}` line is the commit for an annotated tag; it must equal {n[0]})")
@@ -591,9 +600,16 @@ def analyse(files, title):
         for r in rep.changes:
             short = r["name"].split("/")[-1].lower()
             r["in_title"] = r["name"].lower() in t or (len(short) > 3 and re.search(rf"\b{re.escape(short)}\b", t) is not None)
+    for (repo, tag_), shas in rep.sha_pins.items():
+        if len(shas) > 1:
+            where = "; ".join(f"{s} in {', '.join(dict.fromkeys(ps))}" for s, ps in shas.items())
+            rep.flag("pin-conflict", next(iter(shas.values()))[0],
+                     f"{repo} {tag_} is pinned to {len(shas)} different commits ({where}). A tag points to one "
+                     f"commit, so at most one of these is {tag_}; find which with "
+                     f"`git ls-remote https://github.com/{repo} refs/tags/{tag_} 'refs/tags/{tag_}^{{}}'`")
     reasons_stop, reasons_check = [], []
     for fl in rep.flags:
-        if fl["kind"] in ("install-script", "source"):
+        if fl["kind"] in ("install-script", "source", "pin-conflict"):
             reasons_stop.append(f"{fl['kind']}: {fl['text']}")
         elif fl["kind"] == "pin":
             reasons_check.append("pin: " + fl["text"].split(". ")[0])
@@ -662,9 +678,11 @@ def render_md(rep, floor, stop, check, title):
         out += ["", f"## Beyond the title ({len(beyond)})", ""]
         out += [f"- `{r['name']}` {r['kind']}: {r['old'] or '—'} → {r['new'] or '—'} ({r['file']})" for r in beyond] or ["None."]
     labels = (("install-script", "Install scripts"), ("native", "Native code"), ("source", "Sources and registries"),
-              ("licence", "Licences"), ("pin", "Pins (verify every SHA; the script cannot)"))
+              ("licence", "Licences"), ("runtime", "Runtime requirements"), ("pin", "Pins (verify every SHA; the script cannot)"))
     for kind, heading in labels:
         rows = [f for f in rep.flags if f["kind"] == kind]
+        if kind == "pin":
+            rows = [f for f in rep.flags if f["kind"] == "pin-conflict"] + rows
         out += ["", f"## {heading} ({len(rows)})", ""]
         out += [f"- `{f['file']}`: {f['text']}" for f in rows] or ["None seen in the diff."]
     if rep.unattributed:

package/packs/dev-team/skills/sonar-review/manifest.json

@@ -33,5 +33,17 @@
   "model": {
     "tier": "standard",
     "rationale": "Formats Sonar API findings into a report. The hard analysis is Sonar's; this is synthesis. Escalates on very large diffs."
+  },
+  "permissions": {
+    "network": [
+      "sonarcloud.io"
+    ],
+    "commands": [
+      "sonar-scanner",
+      "git",
+      "curl"
+    ],
+    "files": "none",
+    "notes": "No scripts. Its instructions run sonar-scanner and query the Sonar API with curl, using SONAR_TOKEN from the environment, against sonarcloud.io or the self-hosted SonarQube URL the user configures."
   }
 }

package/packs/infra-as-code/skills/terraform-module/manifest.json

@@ -37,5 +37,16 @@
   "model": {
     "tier": "standard",
     "rationale": "Structured generation against fixed module conventions and a secure-defaults checklist; the judgment is bounded to choosing defaults and validation rules for a described need."
+  },
+  "permissions": {
+    "network": [
+      "registry.terraform.io",
+      "releases.hashicorp.com"
+    ],
+    "commands": [
+      "terraform"
+    ],
+    "files": "none",
+    "notes": "No scripts. Its instructions run `terraform fmt`, `terraform init -backend=false` and `terraform validate` on the module it writes. `init` downloads the providers from the Terraform registry; none of the commands contacts a cloud account."
   }
 }

package/packs/infra-as-code/skills/terraform-plan-review/manifest.json

@@ -40,7 +40,14 @@
     "iam",
     "drift"
   ],
-  "permissions": {"network": [], "commands": [], "files": "named-paths", "notes": "Reads a plan JSON, which can hold secrets in clear text; the script never prints attribute values."},
+  "permissions": {
+    "network": [],
+    "commands": [
+      "terraform"
+    ],
+    "files": "named-paths",
+    "notes": "Reads a plan JSON, which can hold secrets in clear text; the script never prints attribute values. Its instructions run `terraform show -json` to produce that plan JSON."
+  },
   "model": {
     "tier": "heavy",
     "rationale": "Adversarial review of a destructive change: judging which replacements lose data, which access changes widen exposure, and what is out of scope needs careful reasoning; a missed destroy costs far more than the model."

package/packs/solution-architect/skills/figma-diagrams/manifest.json

@@ -28,7 +28,18 @@
     "design",
     "api"
   ],
-  "permissions": {"network": ["api.figma.com"], "commands": [], "files": "named-paths", "notes": "Reads FIGMA_TOKEN from the environment to call the Figma REST API."},
+  "permissions": {
+    "network": [
+      "api.figma.com",
+      "pypi.org",
+      "files.pythonhosted.org"
+    ],
+    "commands": [
+      "pip"
+    ],
+    "files": "named-paths",
+    "notes": "Reads FIGMA_TOKEN from the environment to call the Figma REST API. Its instructions install the pinned requirements once with `python3 -m pip install -r requirements.txt`, which reaches PyPI."
+  },
   "model": {
     "tier": "standard",
     "rationale": "API calls + spec generation. Bounded transformation."