dsh-xray 0.4.1 → 0.5.0

package/bin/xray.js

@@ -12,6 +12,7 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--profile' || a === '-p') args.profile = argv[++i];
+    else if (a === '--against') args.against = argv[++i];
     else if (a === '--json') args.json = true;
     else args._.push(a);
   }
@@ -118,7 +119,44 @@ function cmdDiff(args) {
 function cmdSnapshot(args) {
   const data = collectStatic(args.profile);
   const { dump } = tryDump(args.profile);
-  console.log(JSON.stringify(model.snapshot(data, dump), null, 2));
+  const current = model.snapshot(data, dump);
+  const againstFile = args.against;
+  if (!againstFile) return console.log(JSON.stringify(current, null, 2));
+
+  const fs = require('node:fs');
+  const { compareSnapshots } = require('../lib/compare.js');
+  const saved = JSON.parse(fs.readFileSync(againstFile, 'utf8'));
+  const result = compareSnapshots(saved, current);
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+
+  if (result.identical) {
+    return console.log(`composition identical to snapshot from ${result.savedAt}`);
+  }
+  console.log(`composition drifted from snapshot (${result.savedAt}):`);
+  for (const b of result.changes.bundles) {
+    if (b.change === 'added') console.log(`  bundle + ${b.name}@${b.version}`);
+    else if (b.change === 'removed') console.log(`  bundle - ${b.name}`);
+    else
+      console.log(
+        `  bundle ~ ${b.name}: ${b.change} ${b.from.version ?? b.from.patchHash} → ${b.to.version ?? b.to.patchHash}`,
+      );
+  }
+  for (const p of result.changes.patches) {
+    console.log(
+      `  patch ${p.change === 'added' ? '+' : p.change === 'removed' ? '-' : '~'} ${p.kind}${p.change === 'content' ? `: ${p.from} → ${p.to}` : ''}`,
+    );
+  }
+  for (const p of result.changes.packages) {
+    if (p.change === 'added') console.log(`  package + ${p.name}@${p.version}`);
+    else if (p.change === 'removed') console.log(`  package - ${p.name}`);
+    else console.log(`  package ~ ${p.name}: ${p.from} → ${p.to}`);
+  }
+  if (result.changes.composed) {
+    console.log(
+      `  composed tree hash: ${result.changes.composed.from} → ${result.changes.composed.to}`,
+    );
+  }
+  process.exitCode = 1;
 }
 
 function readRuntimeSnapshot() {
@@ -266,7 +304,7 @@ Commands:
   attribute   which layer introduced each row, and who patched it since
   conflicts   rows whose fields have multiple writers, and who wins
   diff        declared (static layers) vs actual (dump-config) tree
-  snapshot    content-addressed lockfile of the effective composition
+  snapshot    content-addressed lockfile; --against <file> diffs a saved one
   deps        service dependency graph from the live runtime snapshot
   health      plugin lifecycle health from the live runtime snapshot
   cost        estimated context-token cost of each model-facing tool schema

package/lib/collect/static.js

@@ -109,6 +109,41 @@ function collectStatic(profileName) {
     });
   }
 
+  // Repository plugins: the third-party plugin-console mechanism mounts
+  // `.dsh-plugin` directories under the harness home; each carries its own
+  // patch file. Not dsh core — absence is normal.
+  const repoRoot = path.join(home, '.dsh-plugin');
+  if (fs.existsSync(repoRoot)) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(repoRoot, { withFileTypes: true }).filter((e) => e.isDirectory());
+    } catch {
+      /* unreadable repository root: skip */
+    }
+    for (const e of entries) {
+      const dir = path.join(repoRoot, e.name);
+      const pkg = readJson(path.join(dir, 'package.json'));
+      const rel = pkg?.dsh?.bundle?.patch;
+      if (!rel) continue;
+      const file = path.join(dir, rel);
+      if (!fs.existsSync(file)) {
+        warnings.push(`repository plugin ${e.name}: patch missing (${rel})`);
+        continue;
+      }
+      const text = fs.readFileSync(file, 'utf8');
+      const { value, error } = parseYaml(text, file);
+      if (error) warnings.push(error);
+      layers.push({
+        kind: 'repository',
+        name: pkg.name ?? e.name,
+        version: pkg.version ?? null,
+        file,
+        entries: Array.isArray(value) ? value : [],
+        text,
+      });
+    }
+  }
+
   // Out-of-tree plugins: profile dependencies carrying a `dsh` field.
   const packages = [];
   for (const dep of Object.keys(manifest.dependencies ?? {})) {

package/lib/compare.js

@@ -0,0 +1,74 @@
+// Snapshot comparison: current composition vs a saved lockfile.
+
+function indexBy(list, key) {
+  const m = new Map();
+  for (const item of list ?? []) m.set(item[key], item);
+  return m;
+}
+
+/**
+ * F9b: compare a live snapshot against a saved one (`xray snapshot > lock.json`).
+ * Returns per-category changes; `identical` is true only when everything matches.
+ */
+function compareSnapshots(saved, current) {
+  if (saved?.schema !== 'dsh-xray/snapshot@1') {
+    throw new Error(`not a dsh-xray snapshot: schema=${saved?.schema ?? 'missing'}`);
+  }
+  const changes = { bundles: [], patches: [], packages: [], composed: null };
+
+  const savedBundles = indexBy(saved.bundles, 'name');
+  const currentBundles = indexBy(current.bundles, 'name');
+  for (const [name, b] of currentBundles) {
+    const old = savedBundles.get(name);
+    if (!old) changes.bundles.push({ name, change: 'added', version: b.version });
+    else if (old.version !== b.version || old.patchHash !== b.patchHash) {
+      changes.bundles.push({
+        name,
+        change: old.version !== b.version ? 'version' : 'patch-content',
+        from: { version: old.version, patchHash: old.patchHash },
+        to: { version: b.version, patchHash: b.patchHash },
+      });
+    }
+  }
+  for (const name of savedBundles.keys()) {
+    if (!currentBundles.has(name)) changes.bundles.push({ name, change: 'removed' });
+  }
+
+  const savedPatches = indexBy(saved.patches, 'kind');
+  const currentPatches = indexBy(current.patches, 'kind');
+  for (const [kind, p] of currentPatches) {
+    const old = savedPatches.get(kind);
+    if (!old) changes.patches.push({ kind, change: 'added' });
+    else if (old.hash !== p.hash)
+      changes.patches.push({ kind, change: 'content', from: old.hash, to: p.hash });
+  }
+  for (const kind of savedPatches.keys()) {
+    if (!currentPatches.has(kind)) changes.patches.push({ kind, change: 'removed' });
+  }
+
+  const savedPkgs = indexBy(saved.packages, 'name');
+  const currentPkgs = indexBy(current.packages, 'name');
+  for (const [name, p] of currentPkgs) {
+    const old = savedPkgs.get(name);
+    if (!old) changes.packages.push({ name, change: 'added', version: p.version });
+    else if (old.version !== p.version) {
+      changes.packages.push({ name, change: 'version', from: old.version, to: p.version });
+    }
+  }
+  for (const name of savedPkgs.keys()) {
+    if (!currentPkgs.has(name)) changes.packages.push({ name, change: 'removed' });
+  }
+
+  if (saved.composedHash && current.composedHash && saved.composedHash !== current.composedHash) {
+    changes.composed = { from: saved.composedHash, to: current.composedHash };
+  }
+
+  const identical =
+    !changes.bundles.length &&
+    !changes.patches.length &&
+    !changes.packages.length &&
+    !changes.composed;
+  return { identical, savedAt: saved.createdAt, profile: saved.profile, changes };
+}
+
+module.exports = { compareSnapshots };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-xray",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "X-ray for your DeepSeek Harness — see what's actually loaded, why, and what it costs you.",
   "repository": {
     "type": "git",