@vyuhlabs/dxkit 2.5.1 → 2.6.0

package/templates/.claude/skills/dxkit-reports/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dxkit-reports
-description: Run dxkit reports and explain their output. Use when the user asks "run health", "check security", "show me the dashboard", "what does this score mean", or anything about generating / reading dxkit analyzer output. Hands off to dxkit-action for fixing findings.
+description: Run dxkit reports and explain their output, including the consolidated dashboard view. Use when the user asks "run health", "check security", "show me the dashboard", "open the dashboard", "tour the dashboard", "explain the dashboard", "what does this score mean", or anything about generating / interpreting dxkit analyzer output. Always reach for this skill even when the user names a specific subcommand (health, vulnerabilities, dashboard, bom, etc.) — running the command is only half of the value; the skill wraps the output with the right framing. Hands off to dxkit-action for fixing findings.
 ---
 
 # dxkit-reports
@@ -11,15 +11,15 @@ This skill runs dxkit analyzers and reads their output back to the user. It's th
 
 | User asks | Command | Output |
 |---|---|---|
-| "Overall health" / "give me the score" | `vyuh-dxkit health` | 6-dimension score table + top actions per dimension |
-| "Check security" / "find vulns" | `vyuh-dxkit vulnerabilities` | Code-level SAST + dep-vuln + secret findings, grouped by severity |
-| "Test coverage gaps" | `vyuh-dxkit test-gaps` | Source files without matching tests, prioritized by architectural role |
-| "Code quality" | `vyuh-dxkit quality` | Lint findings + duplication + slop score |
-| "Who's been working on what" | `vyuh-dxkit dev-report` | Per-author activity, hot files, churn |
-| "License inventory" | `vyuh-dxkit licenses` | Every dependency's declared license |
-| "Bill of materials" | `vyuh-dxkit bom` | Licenses + dep vulnerabilities joined (15-col XLSX-ready output) |
-| "Run everything" | `vyuh-dxkit report` | Every analyzer in one shot, ~3-5 min |
-| "Show me the dashboard" | `vyuh-dxkit dashboard` | Single HTML view of all reports — opens at `.dxkit/reports/dashboard.html` |
+| "Overall health" / "give me the score" | `npx vyuh-dxkit health` | 6-dimension score table + top actions per dimension |
+| "Check security" / "find vulns" | `npx vyuh-dxkit vulnerabilities` | Code-level SAST + dep-vuln + secret findings, grouped by severity |
+| "Test coverage gaps" | `npx vyuh-dxkit test-gaps` | Source files without matching tests, prioritized by architectural role |
+| "Code quality" | `npx vyuh-dxkit quality` | Lint findings + duplication + slop score |
+| "Who's been working on what" | `npx vyuh-dxkit dev-report` | Per-author activity, hot files, churn |
+| "License inventory" | `npx vyuh-dxkit licenses` | Every dependency's declared license |
+| "Bill of materials" | `npx vyuh-dxkit bom` | Licenses + dep vulnerabilities joined (15-col XLSX-ready output) |
+| "Run everything" | `npx vyuh-dxkit report` | Every analyzer in one shot, ~3-5 min |
+| "Show me the dashboard" | `npx vyuh-dxkit dashboard` | Single HTML view of all reports — opens at `.dxkit/reports/dashboard.html` |
 
 ## Where output lands
 
@@ -56,7 +56,7 @@ Score → rating: A ≥ 80, B ≥ 60, C ≥ 40, D ≥ 20, E < 20. **Cap tiers**
 ### Quick health check (warm cache)
 
 ```bash
-vyuh-dxkit health
+npx vyuh-dxkit health
 ```
 
 Re-uses cached scanner outputs where possible. ~5-15s on warm cache, ~30-60s cold.
@@ -64,9 +64,9 @@ Re-uses cached scanner outputs where possible. ~5-15s on warm cache, ~30-60s col
 ### Pre-merge audit (thorough)
 
 ```bash
-vyuh-dxkit health --with-coverage   # Runs tests + materializes coverage before scoring
-vyuh-dxkit vulnerabilities          # Always re-runs the deep security scan
-vyuh-dxkit dashboard                 # Renders the latest reports into one HTML view
+npx vyuh-dxkit health --with-coverage   # Runs tests + materializes coverage before scoring
+npx vyuh-dxkit vulnerabilities          # Always re-runs the deep security scan
+npx vyuh-dxkit dashboard                 # Renders the latest reports into one HTML view
 ```
 
 `--with-coverage` is slow (runs your test suite) but switches the Tests dimension from heuristic ("files match a test pattern") to real ("line coverage from your reporter"). Worth it for pre-merge audits.
@@ -74,7 +74,7 @@ vyuh-dxkit dashboard                 # Renders the latest reports into one HTML
 ### Per-PR scope
 
 ```bash
-vyuh-dxkit guardrail check
+npx vyuh-dxkit guardrail check
 ```
 
 Diffs the current scan vs the baseline. Exit 1 on net-new findings (the same logic the pre-push hook uses).
@@ -82,8 +82,8 @@ Diffs the current scan vs the baseline. Exit 1 on net-new findings (the same log
 ### Failing CI on a threshold
 
 ```bash
-vyuh-dxkit health --fail-on-score=70                 # Exit 1 if overall score < 70
-vyuh-dxkit vulnerabilities --fail-on-severity=high   # Exit 1 if any high-severity finding
+npx vyuh-dxkit health --fail-on-score=70                 # Exit 1 if overall score < 70
+npx vyuh-dxkit vulnerabilities --fail-on-severity=high   # Exit 1 if any high-severity finding
 ```
 
 Use these in CI for hard floors.
@@ -105,7 +105,7 @@ Hand off to the `dxkit-action` skill — that's the workflow for prioritizing +
 
 ## Troubleshooting
 
-- **"Scanner X unavailable"** → run `vyuh-dxkit tools list` to see status; `vyuh-dxkit tools install` to install missing ones.
+- **"Scanner X unavailable"** → run `npx vyuh-dxkit tools list` to see status; `npx vyuh-dxkit tools install` to install missing ones.
 - **"N/A for this stack"** → applicability-guard fired (e.g., vitest-coverage on a mocha repo). Not a problem; the scanner doesn't apply here.
 - **Report looks stale** → `.dxkit/reports/` is keyed by date. Re-run the analyzer to get a fresh date-stamped file.
 - **Numbers don't match between two reports** → check whether `--with-coverage` was used. Without it, Tests dimension uses heuristic; with it, real coverage. They legitimately differ.

package/templates/.claude/skills/dxkit-update/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: dxkit-update
+description: Walk the customer through upgrading dxkit to a newer version safely. Use when the user asks "update dxkit", "upgrade to latest", "what's new in dxkit", "is there a new dxkit version", "should I upgrade dxkit", or anything about moving an existing dxkit install forward. Reads version delta + changelog + recommended steps; confirms each step. Hands off to dxkit-fix if post-upgrade doctor surfaces broken signals.
+---
+
+# dxkit-update
+
+This skill drives the dxkit upgrade flow conversationally. It's the "I have something working — make it newer" surface (complement to `dxkit-onboard` for fresh installs and `dxkit-fix` for repairs).
+
+## When to use this skill
+
+Use when:
+
+- "Is there a new dxkit version?"
+- "Update dxkit"
+- "Upgrade to latest"
+- "What changed in dxkit recently?"
+- "What's new in 2.5.5?" (or any other specific version)
+- "Should I upgrade?"
+
+Don't use when:
+
+- Customer has no `.vyuh-dxkit.json` (they need `dxkit-init`, not update)
+- Something is BROKEN — use `dxkit-fix` first; then maybe update after
+- Customer wants to roll back to an older version (downgrade — surface the risk + manual command, don't auto-execute)
+
+## How the upgrade works (two stages)
+
+dxkit ships in two layers and an upgrade touches both:
+
+1. **The binary** — `@vyuhlabs/dxkit` npm package. `npm update` or `npm install @vyuhlabs/dxkit@<version>` replaces the local binary.
+2. **The scaffold** — files in the customer's repo (`.devcontainer/`, `.githooks/`, `.claude/skills/dxkit-*/`, `AGENTS.md`, `CLAUDE.md`, `.github/workflows/dxkit-*.yml`). `npx vyuh-dxkit update` refreshes these to match the new binary's templates.
+
+Both run for any non-trivial upgrade. The CLI subcommand `vyuh-dxkit upgrade` orchestrates them; this skill drives the customer through the orchestration with explanations and confirmations.
+
+## The upgrade loop
+
+```
+[1] Read the plan        → npx vyuh-dxkit upgrade --plan --json
+[2] Explain the delta    → current vs target, classification, what's new
+[3] Surface warnings     → major bumps, breaking changes, scaffold drift
+[4] Confirm              → "proceed?" (default Y for low-risk; default N for major/downgrade)
+[5] Execute              → drive each step with per-step status
+[6] Verify               → run doctor + report operational health post-upgrade
+[7] Surface manual steps → devcontainer rebuild instructions if .devcontainer/ changed
+```
+
+## Steps
+
+### 1. Snapshot the plan
+
+```bash
+npx vyuh-dxkit upgrade --plan --json > /tmp/dxkit-upgrade-plan.json
+```
+
+The JSON has shape `{ schema: "upgrade-plan.v1", current: { binary, scaffold }, target, delta, steps: [...], warnings: [...], changelogNote }`. Capturing to a file (instead of piping inline) lets the customer re-read the plan if they pause mid-flow.
+
+### 2. Explain what's about to happen
+
+Translate the structured plan into customer-friendly prose:
+
+| Plan field | What to say |
+|---|---|
+| `current.binary` + `current.scaffold` | "You're on dxkit X (scaffold also X). Latest: Y." |
+| `delta: 'none'` | "Already up to date — nothing to do." Skip to End. |
+| `delta: 'patch'` | "N patch versions between you and latest. Low risk — bug fixes + small features only." |
+| `delta: 'minor'` | "Minor bump — new features + scaffold changes likely. Probably safe; CHANGELOG.md has details." |
+| `delta: 'major'` | "**Major bump** — read CHANGELOG.md for breaking changes BEFORE upgrading. Possible baseline/manifest schema migrations; possibly broken policy files; possibly removed CLI flags." |
+| `delta: 'downgrade'` | "Target is OLDER than installed. Downgrades aren't officially supported — baseline/manifest schemas may differ. Surface this and let the customer decide." |
+
+### 3. Surface every warning
+
+Iterate `plan.warnings` and present each as its own bullet. Don't bury them. If `warnings` is empty, mention "No warnings — proceed when ready."
+
+### 4. Confirm before execution
+
+Ask:
+
+> **Proceed with the upgrade?**
+
+Default Y for patch/minor; default N for major/downgrade. If they decline, end gracefully — leave the plan in their hands.
+
+### 5. Execute step-by-step
+
+For each step in `plan.steps`:
+
+- Skip `optional: true` steps from auto-execution (devcontainer rebuild is the only one today; surface it after)
+- Show: "[i/N] purpose"
+- Run: the command via Bash
+- Note: success/failure based on exit code
+
+If any step fails, **stop**. Don't continue with downstream steps. Surface:
+
+- Which step failed + its stderr
+- Suggested recovery: "Run `npx vyuh-dxkit doctor` to see current state, or invoke the `dxkit-fix` skill to walk through repair."
+
+### 6. Verify with doctor
+
+If all steps succeeded, run `npx vyuh-dxkit doctor` and report. If doctor surfaces operational issues post-upgrade (e.g. `summary.fixable[]` not empty), **hand off to dxkit-fix** — say "Upgrade complete, but doctor surfaced N gaps. Walking through dxkit-fix to close them."
+
+### 7. Surface manual follow-ups
+
+Iterate optional steps in the plan:
+
+```
+⚠ Your .devcontainer/ was refreshed. Rebuild your container to pick up:
+    VSCode:     Command Palette → "Dev Containers: Rebuild Container"
+    Codespaces: Command Palette → "Codespaces: Rebuild Container"
+    Local Docker: `docker compose down && docker compose up -d --build`
+```
+
+## What dxkit-update can NOT do
+
+- **Cross-major migrations** — major bumps may need MIGRATION.md guidance + manual policy edits. Surface the link; don't auto-execute.
+- **Customer code changes** — if the upgrade requires changes to the customer's scoring policy, baseline schema, or workflow file customizations, point at the CHANGELOG.md section and stop.
+- **Downgrades** — never auto-execute. Always confirm; warn about schema differences; suggest backing up `.dxkit/baselines/` first.
+- **Rollback** — if execution mid-step fails, dxkit-update can't undo the binary install. Customer needs to `npm install @vyuhlabs/dxkit@<previous-version>` themselves.
+
+## Boundary with other lifecycle skills
+
+| Customer state | Reach for |
+|---|---|
+| "I have nothing" | `dxkit-onboard` |
+| "I have working install, make it newer" | **dxkit-update (this skill)** |
+| "Doctor says X is broken" | `dxkit-fix` |
+| "I want to run a report" | `dxkit-reports` |
+| "Fix these findings" | `dxkit-action` |
+| "Configure dxkit" | `dxkit-config` |
+| "Set up hooks" | `dxkit-hooks` |
+| "Explain dxkit" | `dxkit-learn` |
+
+If the customer asks something that spans skills (e.g. "update dxkit and then fix the new issues"), chain: dxkit-update first, then auto-invoke dxkit-fix on the post-upgrade doctor output.
+
+## CHANGELOG hygiene (worth raising)
+
+The plan's `changelogNote` field points at the canonical CHANGELOG.md URL. Currently it's just a pointer — future versions of `vyuh-dxkit upgrade --plan` may parse the changelog and surface per-version highlights inline. For now, when the customer asks "what changed?", offer to fetch + summarize the CHANGELOG.md for the version range:
+
+```bash
+# Fetch the changelog locally (the installed package ships it)
+cat node_modules/@vyuhlabs/dxkit/CHANGELOG.md
+```
+
+Or for content between current and target (which isn't in the installed tarball until AFTER upgrade), suggest visiting the URL in `plan.changelogNote`.
+
+## Final report
+
+After the loop completes:
+
+```
+✓ Upgraded: dxkit X → Y
+✓ Scaffold refreshed: N files updated, M new (e.g. dxkit-fix skill if upgrading from <2.5.2)
+✓ Doctor: all green
+○ Manual: rebuild devcontainer to pick up changes
+```
+
+Or if something failed:
+
+```
+✗ Upgrade halted at step [i/N]: <purpose>
+   stderr: <captured>
+   → Recovery: `npx vyuh-dxkit doctor` to see current state; ask "fix dxkit" to walk through repair
+```
+
+End with a one-line CTA: "Anything else? Ask 'check dxkit health' to see current scores on the new version."

package/templates/.devcontainer/devcontainer.json

@@ -24,23 +24,14 @@
   // registry pinned-versions advanced since last use.
   "postStartCommand": "command -v vyuh-dxkit >/dev/null 2>&1 && vyuh-dxkit tools list || true",
 
+  // Extensions list is generated by `vyuh-dxkit init` from the detected
+  // stack — only active packs' editor support gets installed. Always-on
+  // entries (anthropic.claude-code + GitHub Actions/PR) ship on every
+  // container regardless. Add or remove entries by hand to override the
+  // auto-detected set.
   "customizations": {
     "vscode": {
-      "extensions": [
-        "anthropic.claude-code",
-        "dbaeumer.vscode-eslint",
-        "esbenp.prettier-vscode",
-        "ms-python.python",
-        "ms-python.vscode-pylance",
-        "golang.go",
-        "rust-lang.rust-analyzer",
-        "ms-dotnettools.csharp",
-        "redhat.java",
-        "fwcd.kotlin",
-        "rebornix.ruby",
-        "github.vscode-github-actions",
-        "github.vscode-pull-request-github"
-      ],
+      "extensions": __DXKIT_DEVCONTAINER_EXTENSIONS__,
       "settings": {
         "editor.formatOnSave": true,
         "files.eol": "\n"

package/templates/.devcontainer/post-create.sh

@@ -50,18 +50,33 @@ if [ -f package.json ]; then
   fi
 fi
 
-# Resolve dxkit. Prefer the project-local install if a `package.json`
-# pinned dxkit in devDependencies; otherwise install globally so the
-# binary is on PATH for the rest of the script and any subshell.
+# Resolve dxkit for THIS script. Prefer the project-local install if a
+# package.json pinned dxkit in devDependencies (so the script uses the
+# project's pinned version); otherwise install globally and use that.
 if [ -x ./node_modules/.bin/vyuh-dxkit ]; then
   DXKIT="./node_modules/.bin/vyuh-dxkit"
 elif command -v vyuh-dxkit >/dev/null 2>&1; then
   DXKIT="vyuh-dxkit"
 else
-  echo "==> Installing @vyuhlabs/dxkit globally..."
+  echo "==> Installing @vyuhlabs/dxkit globally (for script use)..."
   npm install -g @vyuhlabs/dxkit
   DXKIT="vyuh-dxkit"
 fi
+
+# Make sure `vyuh-dxkit` is on the CUSTOMER's interactive shell PATH
+# regardless of where the script-local resolution above ended up.
+# Project-local installs (./node_modules/.bin/) are NOT on PATH for
+# terminal sessions or for the dxkit-* agent skills' bash invocations
+# — only the global install puts the bare command on PATH. Without
+# this, the customer types `vyuh-dxkit doctor` and gets "command not
+# found" until they discover `npx vyuh-dxkit`. Soft-fail: if global
+# install fails (offline / registry hiccup), `npx vyuh-dxkit` still
+# works as a fallback.
+if ! command -v vyuh-dxkit >/dev/null 2>&1; then
+  echo "==> Installing @vyuhlabs/dxkit globally (for shell PATH)..."
+  npm install -g @vyuhlabs/dxkit || \
+    echo "WARN: global install failed — customer terminal will need 'npx vyuh-dxkit'." >&2
+fi
 echo "==> Using dxkit binary: ${DXKIT}"
 
 echo "==> Installing scanner toolchain via dxkit registry..."

package/dist/baseline/producers/licenses.d.ts

@@ -1,23 +0,0 @@
-/**
- * Licenses → baseline-entry producer.
- *
- * One kind: `license` — per-package license attribution.
- * `(package, version, licenseType)` is the identity tuple, so a
- * re-licensing event on the same pinned version (compliance teams'
- * canonical concern) registers as a fresh finding even when no
- * version bump happened.
- *
- * Reads from `CapabilityReport.licenses.findings` — already in the
- * cached `AnalysisResult`, no extra gather work needed. Pure
- * function over its input.
- */
-import type { BaselineEntry } from '../types';
-import type { LicensesResult } from '../../languages/capabilities/types';
-/**
- * Build `license` entries from a licenses capability envelope.
- * Findings with an empty `licenseType` are emitted with the literal
- * `'UNKNOWN'` so identity stays stable across runs even when the
- * underlying tool can't resolve the SPDX id.
- */
-export declare function licensesToBaselineEntries(licenses: LicensesResult | undefined): BaselineEntry[];
-//# sourceMappingURL=licenses.d.ts.map

package/dist/baseline/producers/licenses.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"licenses.d.ts","sourceRoot":"","sources":["../../../src/baseline/producers/licenses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAwB,MAAM,UAAU,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,GAAG,aAAa,EAAE,CAoB/F"}

package/dist/baseline/producers/licenses.js

@@ -1,46 +0,0 @@
-"use strict";
-/**
- * Licenses → baseline-entry producer.
- *
- * One kind: `license` — per-package license attribution.
- * `(package, version, licenseType)` is the identity tuple, so a
- * re-licensing event on the same pinned version (compliance teams'
- * canonical concern) registers as a fresh finding even when no
- * version bump happened.
- *
- * Reads from `CapabilityReport.licenses.findings` — already in the
- * cached `AnalysisResult`, no extra gather work needed. Pure
- * function over its input.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.licensesToBaselineEntries = licensesToBaselineEntries;
-const finding_identity_1 = require("../finding-identity");
-/**
- * Build `license` entries from a licenses capability envelope.
- * Findings with an empty `licenseType` are emitted with the literal
- * `'UNKNOWN'` so identity stays stable across runs even when the
- * underlying tool can't resolve the SPDX id.
- */
-function licensesToBaselineEntries(licenses) {
-    if (!licenses)
-        return [];
-    const out = [];
-    for (const f of licenses.findings) {
-        const licenseType = f.licenseType.length > 0 ? f.licenseType : 'UNKNOWN';
-        const input = {
-            kind: 'license',
-            package: f.package,
-            version: f.version,
-            licenseType,
-        };
-        out.push({
-            id: (0, finding_identity_1.identityFor)(input),
-            kind: 'license',
-            package: f.package,
-            version: f.version,
-            licenseType,
-        });
-    }
-    return out;
-}
-//# sourceMappingURL=licenses.js.map

package/dist/baseline/producers/licenses.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"licenses.js","sourceRoot":"","sources":["../../../src/baseline/producers/licenses.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AAYH,8DAoBC;AA9BD,0DAAkD;AAIlD;;;;;GAKG;AACH,SAAgB,yBAAyB,CAAC,QAAoC;IAC5E,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IACzB,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;QAClC,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;QACzE,MAAM,KAAK,GAAyB;YAClC,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,WAAW;SACZ,CAAC;QACF,GAAG,CAAC,IAAI,CAAC;YACP,EAAE,EAAE,IAAA,8BAAW,EAAC,KAAK,CAAC;YACtB,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,WAAW;SACZ,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}