sandstream-kit 1.8.0 → 1.11.0

package/dist/triage-gate.js

@@ -0,0 +1,96 @@
+/**
+ * Triage gate — kit installs NOTHING untriaged.
+ *
+ * Every third-party tool/package kit would install (mise scanners pinned as
+ * `aqua:`/`npm:`/`pipx:` refs, etc.) is run through `kit triage` first. Only an
+ * explicit triage PASS lets an install proceed. This is WATERTIGHT / fail-closed:
+ * a WARN, a FAIL, an offline triage, a missing triage script, or a ref we cannot
+ * map to a triage target ALL block the install. The only escape is an explicit
+ * `--no-triage` override at the command layer, which itself requires elevation
+ * and is audit-logged — heal never takes that escape.
+ *
+ * Core language runtimes (bare mise names like `node`, `pnpm`) are the trusted
+ * base: mise installs them from its registry with checksum verification, and
+ * they are the language floor kit itself runs on. They pass without a reputation
+ * triage. Anything carrying a `scheme:` (a third-party package/binary) is the
+ * supply-chain surface and is always triaged.
+ */
+import { runTriage } from "./triage.js";
+/** Core language runtimes managed by mise core — the trusted base, not triaged. */
+export const CORE_RUNTIMES = new Set([
+    "node", "nodejs", "pnpm", "npm", "yarn", "bun", "deno",
+    "python", "python3", "go", "golang", "ruby", "java", "openjdk",
+    "rust", "cargo", "dotnet", "php", "zig", "elixir", "erlang",
+]);
+/** Extract `owner/repo` from `owner/repo`, a github URL, or a `host/owner/repo`. */
+function extractOwnerRepo(rest) {
+    const cleaned = rest
+        .replace(/^https?:\/\//, "")
+        .replace(/^github\.com\//, "")
+        .replace(/\.git$/, "");
+    const m = cleaned.match(/([^/\s]+\/[^/\s@]+)/);
+    return m ? m[1] : null;
+}
+/**
+ * Map a mise tool identifier to a triage (type, target), mark it a trusted core
+ * runtime, or mark it untriageable (→ the gate will fail-closed on it). PURE.
+ */
+export function triageTargetFor(tool) {
+    const ref = tool.trim();
+    if (!ref.includes(":")) {
+        return CORE_RUNTIMES.has(ref.toLowerCase()) ? { kind: "runtime" } : { kind: "untriageable", ref };
+    }
+    const idx = ref.indexOf(":");
+    const scheme = ref.slice(0, idx).toLowerCase();
+    const rest = ref.slice(idx + 1);
+    if (scheme === "npm")
+        return { kind: "triage", type: "npm", target: rest };
+    if (scheme === "pip" || scheme === "pipx")
+        return { kind: "triage", type: "pip", target: rest };
+    // Everything else that names a repo (aqua/ubi/go/github/cargo/...) → repo triage.
+    const ownerRepo = extractOwnerRepo(rest);
+    if (ownerRepo)
+        return { kind: "triage", type: "repo", target: `https://github.com/${ownerRepo}` };
+    return { kind: "untriageable", ref };
+}
+const defaultDeps = { runTriage };
+/** First non-empty line of triage output, for a compact block reason. */
+function firstLine(output) {
+    return output.split("\n").map((l) => l.trim()).find(Boolean) ?? "no triage output";
+}
+/**
+ * Watertight gate: returns `pass` ONLY for a trusted core runtime or an explicit
+ * triage PASS. WARN / FAIL / offline / missing-script / unmappable-ref all return
+ * `blocked` (fail-closed).
+ */
+export async function gateInstall(tool, deps = defaultDeps) {
+    const t = triageTargetFor(tool);
+    if (t.kind === "runtime") {
+        return { tool, decision: "pass", reason: "core language runtime (trusted base)" };
+    }
+    if (t.kind === "untriageable") {
+        return {
+            tool,
+            decision: "blocked",
+            reason: `no triage path for "${t.ref}" — cannot verify, refusing to install (fail-closed)`,
+        };
+    }
+    const res = await deps.runTriage(t.type, t.target);
+    if (res.passed) {
+        return {
+            tool,
+            decision: "pass",
+            reason: `triage passed (${t.type} ${t.target})`,
+            triageType: t.type,
+            triageTarget: t.target,
+        };
+    }
+    return {
+        tool,
+        decision: "blocked",
+        reason: `triage did not pass (${t.type} ${t.target}): ${firstLine(res.output)}`,
+        triageType: t.type,
+        triageTarget: t.target,
+    };
+}
+//# sourceMappingURL=triage-gate.js.map

package/dist/triage-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"triage-gate.js","sourceRoot":"","sources":["../src/triage-gate.ts"],"names":[],"mappings":"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"}

package/dist/triage.d.ts

@@ -3,6 +3,13 @@
  * Wraps the Python triage script and integrates with kit's check-security system.
  */
 import { triageNpmSandbox, type SandboxResult } from "./triage-sandbox.js";
+/**
+ * Self-bootstrap the gate: copy the triage skill kit ships with into
+ * ~/.claude/skills/triage. Copying kit's OWN bundled, provenance-published asset
+ * is not a third-party install, so it does not itself need triage. Returns true
+ * if the script is in place afterwards.
+ */
+export declare function installBundledTriageSkill(targetDir?: string): Promise<boolean>;
 export type TriageType = "docker" | "npm" | "pip" | "repo" | "skill" | "all" | "tools";
 export { triageNpmSandbox, type SandboxResult };
 export interface TriageResult {

package/dist/triage.js

@@ -2,14 +2,40 @@
  * Triage — Security evaluation for open source packages, Docker images, skills, and repos.
  * Wraps the Python triage script and integrates with kit's check-security system.
  */
-import { access } from "node:fs/promises";
-import { resolve } from "node:path";
+import { access, cp, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { triageNpmSandbox } from "./triage-sandbox.js";
 import { exec } from "./utils/exec.js";
-const TRIAGE_SCRIPT = resolve(process.env.HOME || "~", ".claude/skills/triage/scripts/triage.py");
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Where kit looks for the triage skill at runtime. */
+const TRIAGE_SKILL_DIR = resolve(homedir(), ".claude/skills/triage");
+const TRIAGE_SCRIPT = resolve(TRIAGE_SKILL_DIR, "scripts/triage.py");
+/** The copy kit ships in its own package (published via package.json "files"). */
+const BUNDLED_TRIAGE_SKILL = resolve(__dirname, "..", "skills", "triage");
+/**
+ * Self-bootstrap the gate: copy the triage skill kit ships with into
+ * ~/.claude/skills/triage. Copying kit's OWN bundled, provenance-published asset
+ * is not a third-party install, so it does not itself need triage. Returns true
+ * if the script is in place afterwards.
+ */
+export async function installBundledTriageSkill(targetDir = TRIAGE_SKILL_DIR) {
+    try {
+        await mkdir(dirname(targetDir), { recursive: true });
+        await cp(BUNDLED_TRIAGE_SKILL, targetDir, { recursive: true });
+        await access(resolve(targetDir, "scripts/triage.py"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export { triageNpmSandbox };
 /**
- * Check if the triage script exists
+ * Ensure the triage script is present. If it is missing, self-bootstrap from the
+ * copy kit ships, so the watertight gate works on a fresh machine without a
+ * manual "copy the triage skill" step.
  */
 async function ensureTriageScript() {
     try {
@@ -17,7 +43,7 @@ async function ensureTriageScript() {
         return true;
     }
     catch {
-        return false;
+        return installBundledTriageSkill();
     }
 }
 /**

package/dist/triage.js.map

@@ -1 +1 @@
-{"version":3,"file":"triage.js","sourceRoot":"","sources":["../src/triage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"triage.js","sourceRoot":"","sources":["../src/triage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,gBAAgB,EAAsB,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,uDAAuD;AACvD,MAAM,gBAAgB,GAAG,OAAO,CAAC,OAAO,EAAE,EAAE,uBAAuB,CAAC,CAAC;AACrE,MAAM,aAAa,GAAG,OAAO,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,CAAC;AACrE,kFAAkF;AAClF,MAAM,oBAAoB,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,YAAoB,gBAAgB;IAEpC,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,MAAM,EAAE,CAAC,oBAAoB,EAAE,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/D,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,mBAAmB,CAAC,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAID,OAAO,EAAE,gBAAgB,EAAsB,CAAC;AAShD;;;;GAIG;AACH,KAAK,UAAU,kBAAkB;IAC/B,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,yBAAyB,EAAE,CAAC;IACrC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAgB,EAChB,MAAc;IAEd,MAAM,YAAY,GAAG,MAAM,kBAAkB,EAAE,CAAC;IAChD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO;YACL,MAAM;YACN,IAAI;YACJ,MAAM,EAAE,KAAK;YACb,MAAM,EAAE,8BAA8B,aAAa,0DAA0D;SAC9G,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CACnC,SAAS,EACT,CAAC,aAAa,EAAE,IAAI,EAAE,MAAM,CAAC,EAC7B,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,yBAAyB;SAC/C,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACtD,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;QAEhD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,KAA+D,CAAC;QAC5E,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QAC7E,OAAO;YACL,MAAM;YACN,IAAI;YACJ,MAAM,EAAE,KAAK;YACb,MAAM,EAAE,MAAM,IAAI,gCAAgC;SACnD,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,OAAO,SAAS,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAM9C,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC7D,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC7D,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,MAAM;SACpB,KAAK,CAAC,QAAQ,CAAC;SACf,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACvB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;SAC3C,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnB,OAAO;QACL,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;QAC7B,cAAc,EAAE,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9D,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxD,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/update-check.d.ts

@@ -9,5 +9,14 @@ export interface UpdateInfo {
  * Never throws — all errors are caught silently.
  */
 export declare function checkForUpdate(currentVersion: string): Promise<UpdateInfo | null>;
+/** Current kit version from the installed package.json (sync, fail-safe). */
+export declare function getKitVersionSync(): string;
+/**
+ * Cache-only update check — NO network. For hot paths (the Claude Code hooks that
+ * run on every prompt): reads the cache the post-command banner / `kit check`
+ * already refresh, never fetches. Returns null on cache miss, error, suppression,
+ * or when current is already latest.
+ */
+export declare function readCachedUpdateSync(currentVersion: string): UpdateInfo | null;
 /** Format and print the update notice after command output. */
 export declare function printUpdateNotice(info: UpdateInfo): void;

package/dist/update-check.js

@@ -1,6 +1,9 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
+const __dirname = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_NAME = "sandstream-kit";
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const CACHE_DIR = join(homedir(), ".kit");
@@ -63,6 +66,36 @@ export async function checkForUpdate(currentVersion) {
         return null;
     }
 }
+/** Current kit version from the installed package.json (sync, fail-safe). */
+export function getKitVersionSync() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Cache-only update check — NO network. For hot paths (the Claude Code hooks that
+ * run on every prompt): reads the cache the post-command banner / `kit check`
+ * already refresh, never fetches. Returns null on cache miss, error, suppression,
+ * or when current is already latest.
+ */
+export function readCachedUpdateSync(currentVersion) {
+    try {
+        if (process.env.KIT_NO_UPDATE_CHECK === "1")
+            return null;
+        const cache = JSON.parse(readFileSync(CACHE_FILE, "utf8"));
+        if (cache?.latestVersion && isNewer(cache.latestVersion, currentVersion)) {
+            return { available: true, latest: cache.latestVersion, current: currentVersion };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Returns true if `latest` is strictly newer than `current` (semver comparison). */
 function isNewer(latest, current) {
     try {
@@ -86,6 +119,6 @@ export function printUpdateNotice(info) {
     const yellow = "\x1b[33m";
     const cyan = "\x1b[36m";
     console.log(`\n  ${dim}╰─${reset} ${yellow}Update available${reset}: ${dim}${info.current}${reset} → ${cyan}${info.latest}${reset}  ` +
-        `${dim}npm install -g ${PACKAGE_NAME}${reset}`);
+        `${dim}run ${reset}${cyan}kit upgrade --self${reset}${dim} (triages before installing)${reset}`);
 }
 //# sourceMappingURL=update-check.js.map

package/dist/update-check.js.map

@@ -1 +1 @@
-{"version":3,"file":"update-check.js","sourceRoot":"","sources":["../src/update-check.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"update-check.js","sourceRoot":"","sources":["../src/update-check.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandstream-kit",
-  "version": "1.8.0",
+  "version": "1.11.0",
   "description": "developer kit. zero LLM, local-first, multi-vault. one command from git clone to working dev environment.",
   "license": "MIT",
   "funding": "https://buymeacoffee.com/sandstream",
@@ -19,7 +19,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "publishConfig": {
     "access": "public"

package/skills/triage/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: triage
+description: "Security-triage a dependency before installing it."
+---
+
+# Triage
+
+Deterministic, zero-LLM pre-install security evaluation. kit shells to
+`scripts/triage.py` from its watertight install gate; only an explicit
+`TRIAGE PASSED` lets an install proceed.
+
+## Run
+
+```
+python3 scripts/triage.py <type> <target>
+```
+
+| type | target | checks |
+| --- | --- | --- |
+| `npm` | package name | existence, deprecation, age, maintainer count |
+| `pip` | package name | existence, yanked, age, license |
+| `repo` | `owner/repo` or a GitHub URL | archived/disabled, maintenance, license, age |
+| `docker` | image | existence, freshness, publisher |
+| `skill` | path or name | validate a local `SKILL.md` (frontmatter, no secrets), else repo-check |
+| `tools` | (none) | list available checks |
+
+## Output contract
+
+- Prints `Health score: N/100`, `Critical issues: N`, `Warnings: N`.
+- Prints `TRIAGE PASSED` when there are **zero critical issues**; warnings are
+  surfaced and scored but do not, by themselves, withhold a pass (criticals do).
+- **Fail-closed:** if a registry cannot be reached (offline, timeout, HTTP error)
+  that is a CRITICAL ("cannot verify"), so the pass is withheld and kit blocks the
+  install. Set `GITHUB_TOKEN` to avoid GitHub rate limits on `repo` checks.
+
+## Rules
+
+- Stdlib only (urllib). No third-party deps, no network calls other than the
+  target registry/API. No LLM, no randomness: same input + same upstream state
+  yields the same verdict.
+- Keep new checks deterministic and offline-degrading (a check that cannot run is
+  a critical, never a silent pass).

package/skills/triage/scripts/triage.py

@@ -0,0 +1,300 @@
+#!/usr/bin/env python3
+"""kit triage — deterministic, zero-LLM pre-install security evaluation.
+
+Usage:
+    triage.py <type> <target>
+    type: npm | pip | repo | docker | skill | tools | all
+
+kit (src/triage.ts) shells to this script and reads its STDOUT:
+  - the line "TRIAGE PASSED" must be present for kit to treat the target as safe;
+  - "Health score: N/100", "Critical issues: N", "Warnings: N" are parsed for the
+    structured summary.
+
+Design contract (matches kit's watertight gate):
+  - Deterministic. No LLM, no randomness. Same input + same upstream state => same verdict.
+  - Dependency-light. Python stdlib only (urllib), so the skill is portable.
+  - Fail-closed. If a registry cannot be reached (offline, timeout, error), that is a
+    CRITICAL ("cannot verify") and "TRIAGE PASSED" is withheld, so kit blocks the install.
+  - PASS rule: "TRIAGE PASSED" is printed when there are zero CRITICAL issues. Warnings
+    are surfaced and scored but do not, by themselves, withhold PASS (criticals do).
+
+Exit code is always 0 on a completed evaluation; kit reads the text, not the code.
+"""
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+
+TIMEOUT = 15
+UA = {"User-Agent": "kit-triage/1.0 (+https://github.com/sandstream/kit)"}
+NEW_DAYS = 30          # younger than this => warning (insufficient track record)
+ABANDONED_DAYS = 730   # no release/push in this long => warning
+
+
+def _get_json(url, headers=None):
+    h = dict(UA)
+    if headers:
+        h.update(headers)
+    req = urllib.request.Request(url, headers=h)
+    with urllib.request.urlopen(req, timeout=TIMEOUT) as r:
+        return json.load(r), r.status
+
+
+def _days_since(iso):
+    """Days since an ISO-8601 timestamp, or None if unparseable."""
+    if not iso:
+        return None
+    try:
+        s = iso.replace("Z", "+00:00")
+        dt = datetime.fromisoformat(s)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return (datetime.now(timezone.utc) - dt).days
+    except ValueError:
+        return None
+
+
+class Report:
+    def __init__(self, ttype, target):
+        self.ttype = ttype
+        self.target = target
+        self.criticals = []
+        self.warnings = []
+        self.facts = []
+
+    def critical(self, m):
+        self.criticals.append(m)
+
+    def warn(self, m):
+        self.warnings.append(m)
+
+    def fact(self, m):
+        self.facts.append(m)
+
+    def emit(self):
+        score = max(0, 100 - 45 * len(self.criticals) - 12 * len(self.warnings))
+        print(f"Triage: {self.ttype} {self.target}")
+        print("-" * 50)
+        for f in self.facts:
+            print(f"  . {f}")
+        for w in self.warnings:
+            print(f"  ! WARNING: {w}")
+        for c in self.criticals:
+            print(f"  x CRITICAL: {c}")
+        print()
+        print(f"Health score: {score}/100")
+        print(f"Critical issues: {len(self.criticals)}")
+        print(f"Warnings: {len(self.warnings)}")
+        if not self.criticals:
+            print("TRIAGE PASSED")
+        else:
+            print("TRIAGE FAILED")
+
+
+def triage_npm(rep):
+    pkg = rep.target
+    url = f"https://registry.npmjs.org/{urllib.parse.quote(pkg, safe='@/')}"
+    try:
+        data, _ = _get_json(url)
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            rep.critical(f"package '{pkg}' not found on the npm registry")
+        else:
+            rep.critical(f"npm registry returned HTTP {e.code} (cannot verify)")
+        return
+    except (urllib.error.URLError, TimeoutError, OSError):
+        rep.critical("could not reach the npm registry (offline?) -- cannot verify")
+        return
+
+    latest = (data.get("dist-tags") or {}).get("latest")
+    versions = data.get("versions") or {}
+    meta = versions.get(latest, {}) if latest else {}
+    times = data.get("time") or {}
+
+    if meta.get("deprecated"):
+        rep.critical(f"latest version {latest} is DEPRECATED: {str(meta.get('deprecated'))[:80]}")
+    created_days = _days_since(times.get("created"))
+    last_days = _days_since(times.get(latest)) if latest else None
+    maint = data.get("maintainers") or meta.get("maintainers") or []
+
+    rep.fact(f"latest {latest}, {len(versions)} versions, {len(maint)} maintainer(s)")
+    if created_days is not None:
+        rep.fact(f"first published {created_days} days ago")
+        if created_days < NEW_DAYS:
+            rep.warn(f"package is very new ({created_days} days) -- limited track record")
+    if last_days is not None and last_days > ABANDONED_DAYS:
+        rep.warn(f"no publish in {last_days} days -- possibly abandoned")
+    if len(maint) <= 1:
+        rep.warn("single maintainer -- bus-factor / takeover risk")
+
+
+def triage_pip(rep):
+    pkg = rep.target
+    url = f"https://pypi.org/pypi/{urllib.parse.quote(pkg)}/json"
+    try:
+        data, _ = _get_json(url)
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            rep.critical(f"package '{pkg}' not found on PyPI")
+        else:
+            rep.critical(f"PyPI returned HTTP {e.code} (cannot verify)")
+        return
+    except (urllib.error.URLError, TimeoutError, OSError):
+        rep.critical("could not reach PyPI (offline?) -- cannot verify")
+        return
+
+    info = data.get("info") or {}
+    releases = data.get("releases") or {}
+    ver = info.get("version")
+    files = releases.get(ver) or []
+    if any(f.get("yanked") for f in files):
+        rep.critical(f"latest version {ver} is YANKED")
+    rep.fact(f"latest {ver}, {len(releases)} releases, author: {info.get('author') or 'unknown'}")
+    last_iso = files[0].get("upload_time_iso_8601") if files else None
+    last_days = _days_since(last_iso)
+    if last_days is not None and last_days > ABANDONED_DAYS:
+        rep.warn(f"no release in {last_days} days -- possibly abandoned")
+    if not info.get("license") and not (info.get("classifiers") or []):
+        rep.warn("no declared license -- review terms before use")
+
+
+def _owner_repo(target):
+    t = target.strip()
+    t = t.replace("https://", "").replace("http://", "")
+    t = t.replace("github.com/", "")
+    if t.endswith(".git"):
+        t = t[:-4]
+    parts = [p for p in t.split("/") if p]
+    if len(parts) >= 2:
+        return f"{parts[0]}/{parts[1]}"
+    return None
+
+
+def triage_repo(rep):
+    or_ = _owner_repo(rep.target)
+    if not or_:
+        rep.critical(f"could not parse owner/repo from '{rep.target}'")
+        return
+    headers = {}
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    try:
+        data, _ = _get_json(f"https://api.github.com/repos/{or_}", headers=headers)
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            rep.critical(f"repo '{or_}' not found (or private)")
+        elif e.code in (403, 429):
+            rep.critical("GitHub API rate-limited -- cannot verify (set GITHUB_TOKEN and retry)")
+        else:
+            rep.critical(f"GitHub API returned HTTP {e.code} (cannot verify)")
+        return
+    except (urllib.error.URLError, TimeoutError, OSError):
+        rep.critical("could not reach GitHub (offline?) -- cannot verify")
+        return
+
+    rep.fact(f"{or_}: {data.get('stargazers_count', 0)} stars, "
+             f"license: {(data.get('license') or {}).get('spdx_id') or 'none'}")
+    if data.get("archived"):
+        rep.critical(f"repo '{or_}' is ARCHIVED (read-only / unmaintained)")
+    if data.get("disabled"):
+        rep.critical(f"repo '{or_}' is DISABLED")
+    pushed_days = _days_since(data.get("pushed_at"))
+    created_days = _days_since(data.get("created_at"))
+    if created_days is not None and created_days < NEW_DAYS:
+        rep.warn(f"repo is very new ({created_days} days)")
+    if pushed_days is not None and pushed_days > ABANDONED_DAYS:
+        rep.warn(f"no push in {pushed_days} days -- possibly unmaintained")
+    if not (data.get("license") or {}).get("spdx_id"):
+        rep.warn("no detected license -- review terms before use")
+
+
+def triage_docker(rep):
+    repo = rep.target
+    api_repo = repo if "/" in repo else f"library/{repo}"
+    try:
+        data, _ = _get_json(f"https://hub.docker.com/v2/repositories/{api_repo}")
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            rep.critical(f"image '{repo}' not found on Docker Hub")
+        else:
+            rep.critical(f"Docker Hub returned HTTP {e.code} (cannot verify)")
+        return
+    except (urllib.error.URLError, TimeoutError, OSError):
+        rep.critical("could not reach Docker Hub (offline?) -- cannot verify")
+        return
+    rep.fact(f"{api_repo}: {data.get('pull_count', 0)} pulls, official={data.get('is_official', False)}")
+    last_days = _days_since(data.get("last_updated"))
+    if last_days is not None and last_days > ABANDONED_DAYS:
+        rep.warn(f"image not updated in {last_days} days -- stale base / unpatched CVEs likely")
+    if not data.get("is_official") and (data.get("pull_count") or 0) < 1000:
+        rep.warn("unofficial image with low pull count -- verify the publisher")
+
+
+def triage_skill(rep):
+    target = rep.target
+    # Local path -> validate the SKILL.md deterministically.
+    candidates = [target, os.path.join(target, "SKILL.md")]
+    path = next((p for p in candidates if os.path.isfile(p)), None)
+    if path:
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                text = f.read()
+        except OSError as e:
+            rep.critical(f"cannot read skill at '{path}': {e}")
+            return
+        head = text[:400]
+        if not head.lstrip().startswith("---"):
+            rep.critical("SKILL.md has no YAML frontmatter (--- ... ---)")
+        if "name:" not in head:
+            rep.warn("frontmatter missing 'name:'")
+        if "description:" not in head:
+            rep.warn("frontmatter missing 'description:'")
+        # crude secret scan
+        for marker in ("sk-", "ghp_", "AKIA", "-----BEGIN", "xoxb-", "AIza"):
+            if marker in text:
+                rep.critical(f"possible secret in skill body (matched '{marker}')")
+        rep.fact(f"validated local skill at {path} ({len(text)} bytes)")
+        return
+    # Otherwise treat a name/owner-repo as a repo triage.
+    rep.fact("no local SKILL.md found; treating target as a repo")
+    triage_repo(rep)
+
+
+def main(argv):
+    if len(argv) < 1 or argv[0] == "tools":
+        print("kit triage -- available checks:")
+        print("  npm <pkg>        npm registry: existence, deprecation, age, maintainers")
+        print("  pip <pkg>        PyPI: existence, yanked, age, license")
+        print("  repo <owner/repo|url>   GitHub: archived, maintenance, license, age")
+        print("  docker <image>   Docker Hub: existence, freshness, publisher")
+        print("  skill <path|name>   validate a local SKILL.md, else repo-check")
+        return 0
+    ttype = argv[0]
+    target = argv[1] if len(argv) > 1 else ""
+    if ttype == "all" or not target:
+        print(f"Usage: triage.py <npm|pip|repo|docker|skill> <target>")
+        return 0
+    rep = Report(ttype, target)
+    dispatch = {
+        "npm": triage_npm,
+        "pip": triage_pip,
+        "repo": triage_repo,
+        "docker": triage_docker,
+        "skill": triage_skill,
+    }
+    fn = dispatch.get(ttype)
+    if not fn:
+        rep.critical(f"unknown triage type '{ttype}'")
+    else:
+        fn(rep)
+    rep.emit()
+    return 0
+
+
+if __name__ == "__main__":
+    import urllib.parse  # noqa: E402  (kept local to module load is fine)
+    sys.exit(main(sys.argv[1:]))