@vyuhlabs/dxkit 2.5.0 → 2.5.2

package/dist/upgrade.js

@@ -0,0 +1,324 @@
+"use strict";
+/**
+ * `vyuh-dxkit upgrade` — combined CLI for the dxkit upgrade flow.
+ *
+ * Two modes, one subcommand:
+ *
+ *   `--plan [--json]` — preview only. Emits UpgradePlan JSON
+ *   (consumed by dxkit-update skill) or text-prose summary. No
+ *   mutations. Used to inspect what an upgrade would do before
+ *   committing.
+ *
+ *   (no flag, or `--yes`) — execute. Runs the three-step upgrade:
+ *     1. `npm install @vyuhlabs/dxkit@<target>`     (binary)
+ *     2. `npx vyuh-dxkit update`                    (scaffold refresh)
+ *     3. `npx vyuh-dxkit doctor`                    (verify)
+ *   Then prints devcontainer-rebuild instructions if .devcontainer/
+ *   was refreshed.
+ *
+ * Architectural mirror of the doctor → dxkit-fix pattern: structured
+ * CLI output (--plan --json) for skill consumption, execution mode
+ * for direct human use. Same shape, different content.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyDelta = classifyDelta;
+exports.buildUpgradePlan = buildUpgradePlan;
+exports.runUpgrade = runUpgrade;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const logger = __importStar(require("./logger"));
+// ────────────────────────────────────────────────────────────────────
+// Version helpers
+// ────────────────────────────────────────────────────────────────────
+function readScaffoldVersion(cwd) {
+    const manifestPath = path.join(cwd, '.vyuh-dxkit.json');
+    if (!fs.existsSync(manifestPath))
+        return null;
+    try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+        return manifest.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function readBinaryVersion(cwd) {
+    try {
+        const out = (0, child_process_1.execSync)('npx --no-install vyuh-dxkit --version 2>/dev/null', {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+        });
+        return out.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function readLatestPublished() {
+    try {
+        const out = (0, child_process_1.execSync)('npm view @vyuhlabs/dxkit version 2>/dev/null', {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+            timeout: 15000,
+        });
+        return out.trim();
+    }
+    catch {
+        // npm registry unreachable — return empty so caller can decide
+        return '';
+    }
+}
+/**
+ * Classify the delta between two semver-shaped strings. Returns
+ * `'none'` if equal, `'downgrade'` if target < current.
+ */
+function classifyDelta(current, target) {
+    if (!current || !target)
+        return 'none';
+    const [c1, c2, c3] = current.split('.').map((n) => parseInt(n, 10));
+    const [t1, t2, t3] = target.split('.').map((n) => parseInt(n, 10));
+    if (Number.isNaN(c1) || Number.isNaN(t1))
+        return 'none';
+    if (t1 > c1)
+        return 'major';
+    if (t1 < c1)
+        return 'downgrade';
+    if (t2 > c2)
+        return 'minor';
+    if (t2 < c2)
+        return 'downgrade';
+    if (t3 > c3)
+        return 'patch';
+    if (t3 < c3)
+        return 'downgrade';
+    return 'none';
+}
+// ────────────────────────────────────────────────────────────────────
+// Plan construction
+// ────────────────────────────────────────────────────────────────────
+function buildUpgradePlan(cwd, opts = {}) {
+    const scaffold = readScaffoldVersion(cwd);
+    const binary = (opts._readBinary ?? readBinaryVersion)(cwd);
+    const latest = opts.target ?? (opts._readLatest ?? readLatestPublished)();
+    // Use binary version as the "current" anchor for delta classification —
+    // it's what npm install will replace. Scaffold version informs whether
+    // vyuh-dxkit update is needed even when binary is already up to date.
+    const delta = classifyDelta(binary, latest);
+    const steps = [];
+    const warnings = [];
+    if (!latest) {
+        warnings.push('Could not query npm for the latest version (registry unreachable or rate-limited). ' +
+            'Pass --target=X.Y.Z to upgrade to a specific version.');
+    }
+    // Step 1: binary upgrade. Always included unless delta is none AND
+    // scaffold already matches.
+    if (delta !== 'none' || (scaffold && binary && scaffold !== binary)) {
+        if (latest) {
+            steps.push({
+                command: `npm install @vyuhlabs/dxkit@${latest}`,
+                purpose: `Install dxkit binary ${binary ?? '(missing)'} → ${latest}`,
+            });
+        }
+    }
+    // Step 2: scaffold refresh. Always run when scaffold ≠ binary OR after
+    // a binary upgrade (scaffold may need updating to match the new binary).
+    if (latest) {
+        steps.push({
+            command: 'npx vyuh-dxkit update',
+            purpose: 'Refresh scaffold (.devcontainer, .githooks, .claude/skills, CI workflows)',
+        });
+    }
+    // Step 3: verify with doctor.
+    if (latest) {
+        steps.push({
+            command: 'npx vyuh-dxkit doctor',
+            purpose: 'Verify operational health post-upgrade',
+        });
+    }
+    // Optional: devcontainer rebuild reminder. We mark this optional so
+    // dxkit-update can surface it as a "you also need to do this manually"
+    // step rather than something the CLI can execute.
+    const hasDevcontainer = fs.existsSync(path.join(cwd, '.devcontainer', 'devcontainer.json'));
+    if (hasDevcontainer && delta !== 'none') {
+        steps.push({
+            command: '# Rebuild devcontainer: VSCode Command Palette → "Dev Containers: Rebuild Container"',
+            purpose: 'Pick up devcontainer.json changes (if any) — manual step',
+            optional: true,
+        });
+    }
+    // Warnings.
+    if (delta === 'major') {
+        warnings.push(`Major version jump (${binary} → ${latest}). Read CHANGELOG.md for breaking changes ` +
+            'before running the upgrade.');
+    }
+    if (delta === 'downgrade') {
+        warnings.push(`Target version ${latest} is OLDER than installed ${binary}. ` +
+            'Downgrades are not officially supported; baseline + manifest schemas may differ.');
+    }
+    if (scaffold && binary && scaffold !== binary) {
+        warnings.push(`Scaffold version (${scaffold}) doesn't match binary (${binary}). ` +
+            'Step 2 (vyuh-dxkit update) will reconcile.');
+    }
+    return {
+        schema: 'upgrade-plan.v1',
+        generatedAt: new Date().toISOString(),
+        cwd,
+        current: { binary, scaffold },
+        target: latest,
+        delta,
+        steps,
+        warnings,
+        changelogNote: latest
+            ? `For per-version details: https://github.com/vyuh-labs/dxkit/blob/main/CHANGELOG.md`
+            : '',
+    };
+}
+// ────────────────────────────────────────────────────────────────────
+// Renderers
+// ────────────────────────────────────────────────────────────────────
+function renderPlanProse(plan) {
+    logger.header('vyuh-dxkit upgrade --plan');
+    logger.info(`Current: scaffold ${plan.current.scaffold ?? '(none)'} + binary ${plan.current.binary ?? '(none)'}`);
+    logger.info(`Target:  ${plan.target || '(latest unavailable)'}`);
+    logger.info(`Delta:   ${plan.delta}`);
+    if (plan.warnings.length) {
+        console.log(''); // slop-ok
+        for (const w of plan.warnings)
+            logger.warn(w);
+    }
+    if (plan.steps.length) {
+        console.log(''); // slop-ok
+        logger.info('Plan:');
+        plan.steps.forEach((s, i) => {
+            const marker = s.optional ? '○' : '●';
+            logger.dim(`  ${marker} [${i + 1}/${plan.steps.length}] ${s.purpose}`);
+            logger.dim(`     ${s.command}`);
+        });
+    }
+    if (plan.changelogNote) {
+        console.log(''); // slop-ok
+        logger.dim(plan.changelogNote);
+    }
+}
+// ────────────────────────────────────────────────────────────────────
+// Execution
+// ────────────────────────────────────────────────────────────────────
+function runStep(step, cwd, dryRun) {
+    if (step.optional) {
+        // Optional steps are never auto-executed — surfaced for the
+        // customer to do manually.
+        return true;
+    }
+    logger.info(`→ ${step.purpose}`);
+    logger.dim(`  ${step.command}`);
+    if (dryRun) {
+        logger.dim('  (dry-run; skipping)');
+        return true;
+    }
+    // Shell out to a real shell so npx/npm work the same way as the
+    // customer's terminal would. We DON'T use spawnSync's shell:true
+    // bash escaping concerns because the commands here are all dxkit-
+    // controlled — no customer input flows into them.
+    const result = (0, child_process_1.spawnSync)('bash', ['-c', step.command], {
+        cwd,
+        stdio: 'inherit',
+    });
+    return result.status === 0;
+}
+async function runUpgradeExecution(cwd, plan, opts) {
+    // Print the plan so the customer sees what's about to happen.
+    renderPlanProse(plan);
+    if (plan.steps.length === 0) {
+        console.log(''); // slop-ok
+        logger.success('Already up to date — nothing to do.');
+        return;
+    }
+    if (!opts.yes && !opts.dryRun) {
+        // We don't bundle a real prompt library here — the upgrade is
+        // intended either non-interactive (--yes) or driven by the
+        // dxkit-update skill (which handles confirmation). Surface the
+        // hint so a direct human invocation knows to add --yes.
+        console.log(''); // slop-ok
+        logger.warn('Interactive confirmation is not implemented for this command. ' +
+            'Re-run with --yes to execute, --dry-run to print without executing, ' +
+            'or use the dxkit-update skill for a guided upgrade.');
+        return;
+    }
+    console.log(''); // slop-ok
+    logger.header('Executing upgrade');
+    const optionalAfter = [];
+    for (const step of plan.steps) {
+        if (step.optional) {
+            optionalAfter.push(step);
+            continue;
+        }
+        const ok = runStep(step, cwd, !!opts.dryRun);
+        if (!ok) {
+            logger.fail(`Step failed: ${step.purpose}`);
+            logger.dim('  Upgrade aborted. Re-run `vyuh-dxkit doctor` to see current state.');
+            process.exitCode = 1;
+            return;
+        }
+    }
+    console.log(''); // slop-ok
+    logger.success(`Upgraded to ${plan.target}.`);
+    if (optionalAfter.length) {
+        console.log(''); // slop-ok
+        logger.info('Manual steps still required:');
+        for (const s of optionalAfter)
+            logger.dim(`  • ${s.purpose}\n    ${s.command}`);
+    }
+}
+// ────────────────────────────────────────────────────────────────────
+// Entry point
+// ────────────────────────────────────────────────────────────────────
+async function runUpgrade(cwd, opts = {}) {
+    const plan = buildUpgradePlan(cwd, opts);
+    if (opts.planOnly) {
+        if (opts.json) {
+            // Logger already routes to stderr in --json mode (cli.ts sets it).
+            console.log(JSON.stringify(plan, null, 2)); // slop-ok
+        }
+        else {
+            renderPlanProse(plan);
+        }
+        return;
+    }
+    await runUpgradeExecution(cwd, plan, opts);
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/upgrade.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vyuhlabs/dxkit",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "description": "AI-native developer experience toolkit for any codebase",
   "license": "MIT",
   "author": "Vyuh Labs",

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

@@ -0,0 +1,150 @@
+---
+name: dxkit-action
+description: Read a dxkit report and execute fixes — prioritize findings by severity, plan the fix sequence, run the fix, verify the score moved, re-baseline if appropriate. Use when the user says "fix these findings", "act on the health report", "close out these vulnerabilities", or after dxkit-reports has surfaced something concrete.
+---
+
+# dxkit-action
+
+This skill takes a dxkit report and drives the fix loop with the user. Reach for it after `dxkit-reports` has surfaced concrete findings.
+
+## The action loop
+
+```
+[1] Read the report          → understand what's flagged
+[2] Prioritize               → severity + reachability + cost
+[3] Plan                     → ordered list of edits
+[4] Execute                  → fix one finding at a time
+[5] Verify                   → re-run the analyzer, confirm score moved
+[6] Decide on baseline       → commit fix or accept-as-baseline
+```
+
+Don't skip [5]. Re-running the analyzer is the only way to confirm the fix landed correctly.
+
+## Priority order
+
+Walk findings in this order (highest to lowest):
+
+1. **CRITICAL** secrets (leaked credentials) — these are public-internet-facing. Stop everything and rotate.
+2. **CRITICAL / HIGH** SAST findings in primary-architecture paths (controllers/handlers/services for backend; components/pages for frontend).
+3. **CRITICAL / HIGH** dep-vulns with known exploits + a patched version available.
+4. **HIGH** test-gap findings on primary-architecture files.
+5. **MEDIUM** SAST / dep-vuln.
+6. **LOW** anything (often defer to backlog).
+
+Skip items where reachability is "no" (graphify can't find a call path) UNLESS the finding is a secret leak (those don't depend on reachability).
+
+## Common fix recipes
+
+### Secret in code
+
+```bash
+# 1. Rotate the credential immediately (in the issuing provider's UI)
+# 2. Remove the secret from the file
+# 3. If the secret was committed: `git filter-repo` or BFG to scrub history
+# 4. Re-scan to confirm gitleaks no longer reports it
+npx vyuh-dxkit vulnerabilities --json | jq '.summary.findings'
+```
+
+Don't try to redact the secret in place — the git history still has it. Rotation is the only true fix.
+
+### SAST finding (semgrep)
+
+```bash
+# 1. Read the finding's rule + line range from the report
+# 2. Open the file, understand why semgrep flagged it
+# 3. Either FIX (preferred) or SUPPRESS (carefully)
+```
+
+Suppression is `// nosemgrep: <rule-id>` on the offending line. Use sparingly — every suppression is a future maintenance burden. Better: fix the underlying issue.
+
+### Dependency vulnerability
+
+```bash
+# Find the patched version (osv-scanner / npm-audit / etc. report it)
+npm install <pkg>@<patched-version>
+# Re-run the scan
+npx vyuh-dxkit vulnerabilities
+```
+
+For peer-dep conflicts: `npm install <pkg>@<patched-version> --legacy-peer-deps` (matches the post-create.sh fallback chain).
+
+For Python: `pip install --upgrade <pkg>=<patched>` then re-pip-freeze. For Go: `go get <pkg>@<patched>` then `go mod tidy`. For Ruby: edit Gemfile, `bundle update <pkg>`. For Rust: `cargo update -p <pkg> --precise <patched>`.
+
+### Test gap
+
+```bash
+# 1. Read the source file the test-gap analyzer flagged
+# 2. Write a test that exercises the file's primary contract
+# 3. Run the test runner to confirm it passes
+npm test  # or pytest, go test, cargo test, etc.
+# 4. Re-run test-gaps to confirm the file dropped off the list
+npx vyuh-dxkit test-gaps
+```
+
+Don't write tests that just import the module — write tests that exercise behavior. Useless tests inflate the count but don't move the dimension.
+
+### Slop / code-pattern finding
+
+```bash
+# Read the slop check report at .dxkit/reports/
+# Most slop hits are in committed AI-generated prose: README sections,
+# CHANGELOG entries, doc comments. Rewrite by hand to remove the patterns.
+```
+
+If the finding is a false positive, add `// slop-ok: <reason>` on the offending line (or `# slop-ok` for non-JS).
+
+## Verification — never skip
+
+After each fix:
+
+```bash
+# Re-run the SPECIFIC analyzer that flagged the finding
+npx vyuh-dxkit vulnerabilities  # or quality / test-gaps / health
+```
+
+The fix is verified when:
+- The specific finding fingerprint disappears from the report.
+- The dimension score moves in the right direction.
+- (Optional) The dashboard's diff view confirms the count dropped.
+
+If the finding's still there: the fix didn't work, try again.
+
+## Baseline decisions
+
+Once a finding is fixed AND verified gone, the workflow depends on what changed:
+
+| Scenario | Action |
+|---|---|
+| Fix landed via a code change | Commit the code. Baseline is unchanged. Future scans confirm the fix held. |
+| Fix landed via a config change (e.g., new entry in `.dxkit-ignore`) | Re-baseline: `npx vyuh-dxkit baseline create --force`. Commit both `.dxkit-ignore` and the new baseline. |
+| Finding accepted as known + not blocking | Re-baseline with explicit reason in the commit message. Future scans treat it as pre-existing, not net-new. |
+| Finding is genuinely a false positive | First try suppression on the offending line. If you can't suppress, re-baseline. |
+
+**Never** re-baseline a finding silently — the commit message should explain why the regression is accepted. Future maintainers reading `git log .dxkit/baselines/` should see the rationale.
+
+## Workflow guardrail
+
+After fixing N findings, run the guardrail check before pushing:
+
+```bash
+npx vyuh-dxkit guardrail check
+```
+
+Exit 0 = your fixes didn't introduce any net-new regressions (you only removed/fixed things). Exit 1 = something new appeared; address that before pushing.
+
+## When fixes get expensive
+
+Sometimes the right call is: don't fix, accept as baseline.
+
+Examples:
+- Legacy code on a deprecation path (sunset > fix)
+- A SAST finding in vendored code you don't maintain
+- A test gap on a one-off script that doesn't merit tests
+
+In those cases: accept-as-baseline with a commit message explaining the call. dxkit's baseline IS designed to support this — the brownfield contract is "today's mess is acknowledged; tomorrow's must be a real improvement." Use it.
+
+## Hand-offs
+
+- For ignore-file edits as part of a fix → `dxkit-config` skill
+- For hook-related issues during a fix push → `dxkit-hooks` skill
+- For re-running reports between fixes → `dxkit-reports` skill

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

@@ -0,0 +1,124 @@
+---
+name: dxkit-config
+description: Edit dxkit configuration — add/remove paths in .dxkit-ignore, tune .npx vyuh-dxkit.json, adjust .dxkit/policy.json guardrail severity. Use when the user wants to exclude a directory from scanning, change scoring thresholds, or modify what blocks a PR.
+---
+
+# dxkit-config
+
+This skill modifies the three configuration files dxkit reads. Reach for it when the user asks to "ignore this vendored directory," "stop flagging X," "make the guardrail stricter/laxer," or "what controls Y."
+
+## The three config files
+
+| File | Purpose | When to edit |
+|---|---|---|
+| `.dxkit-ignore` | Extra paths dxkit's analyzers should skip (gitignore-style format) | Vendored code, generated code, test fixtures, large data files |
+| `.npx vyuh-dxkit.json` | Manifest of detected stack + custom settings (regenerated by `init` / `update`) | Rare — usually let `dxkit update` regenerate. Override version pins or framework detection here. |
+| `.dxkit/policy.json` | Severity policy for guardrail check | Customize what blocks a PR (e.g., demote `medium` to warning) |
+
+## Adding a path to `.dxkit-ignore`
+
+Format mirrors `.gitignore`: directory/, file-glob, multi-segment paths.
+
+```bash
+# Append a vendored directory
+echo 'vendor/' >> .dxkit-ignore
+
+# Append a generated-code dir
+echo 'src/generated/' >> .dxkit-ignore
+
+# Append a glob (auto-generated TypeScript types)
+echo '*.generated.ts' >> .dxkit-ignore
+```
+
+Or use Edit to add multiple entries cleanly. The file accepts comments (`#`).
+
+After editing, the **next** `baseline create` picks up the change. Existing baselines stay valid (the file's content hash is recorded in the baseline envelope, so a mismatch surfaces as a "baseline regenerated against newer .dxkit-ignore" note rather than an error).
+
+### Common exclusions
+
+```gitignore
+# Vendored third-party code committed to git
+vendor/
+third_party/
+
+# Generated code
+generated/
+*.generated.ts
+*.designer.cs
+*.pb.go
+src/proto-types/
+
+# Legacy code you don't want to track findings against
+legacy/
+deprecated/
+
+# Test fixtures that inflate metrics
+fixtures/large/
+test/fixtures/
+
+# Build artifacts (most are gitignored already, but defensive)
+dist/
+build/
+target/
+```
+
+## Tuning `.npx vyuh-dxkit.json`
+
+This file is mostly auto-generated. Common manual edits:
+
+```json
+{
+  "framework": "express",          // Override if auto-detection picked wrong
+  "languages": {
+    "typescript": true,
+    "python": false
+  },
+  "testRunner": {
+    "framework": "vitest",         // Override auto-detected test runner
+    "command": "npm test"
+  }
+}
+```
+
+When you edit this file, run `npx vyuh-dxkit update` to propagate changes through the rest of the scaffold (per-language rules, devcontainer features, etc.). Use `--force` only if you've also edited evolving files — otherwise `update` preserves customer changes.
+
+## Customizing `.dxkit/policy.json`
+
+The policy file controls what severity counts as "blocking" for the guardrail. Default:
+
+```json
+{
+  "code": { "block": ["critical", "high"], "warn": ["medium"] },
+  "dependency": { "block": ["critical", "high"], "warn": ["medium"] },
+  "secret": { "block": ["critical", "high", "medium", "low"] },
+  "test-gap": { "block": ["critical"], "warn": ["high"] },
+  "duplicate": { "warn": ["all"] }
+}
+```
+
+Each finding-kind has `block` (exit 1) and `warn` (log only) lists. Adjust to your team's tolerance:
+
+```json
+// Stricter — block medium SAST findings too
+{ "code": { "block": ["critical", "high", "medium"] } }
+
+// Laxer — make secret medium/low non-blocking (don't recommend)
+{ "secret": { "block": ["critical", "high"] } }
+```
+
+Run `npx vyuh-dxkit guardrail check --policy=.dxkit/policy.json` to test the new policy. If no `policy.json` exists, dxkit uses the built-in defaults.
+
+## Workflow
+
+When the user asks for a config change:
+
+1. Identify which file owns the concern (path exclusion → `.dxkit-ignore`; severity routing → `.dxkit/policy.json`; detection override → `.npx vyuh-dxkit.json`).
+2. Open the file, propose the edit, confirm.
+3. After writing, run `npx vyuh-dxkit baseline create --force` if exclusions changed (so the baseline doesn't carry stale findings from the now-excluded paths).
+4. Commit both: the config file + the regenerated baseline.
+
+## What NOT to do
+
+- Don't edit `.dxkit/cache/` or `.dxkit/reports/` — they're regenerated on every run (gitignored).
+- Don't manually mutate `.dxkit/baselines/main.json` — use `baseline create --force` to regenerate.
+- Don't add `.dxkit/` to `.dxkit-ignore` — dxkit itself doesn't scan its own outputs.